Function drmgr_register_cls_field 

pub unsafe extern "C" fn drmgr_register_cls_field(
    cb_init_func: Option<unsafe extern "C" fn(drcontext: *mut c_void, new_depth: bool_)>,
    cb_exit_func: Option<unsafe extern "C" fn(drcontext: *mut c_void, thread_exit: bool_)>,
) -> c_int

Reserves a callback-local storage (cls) slot. Thread-local storage (tls) is callback-shared. Callbacks interrupt thread execution to execute arbitrary amounts of code in a new context before returning to the interrupted context. Thread-local storage fields that persist across application execution can be overwritten during callback execution, resulting in incorrect values when returning to the original context. Callback-local storage, rather than thread-local storage, should be used for any fields that store information specific to the application’s execution.

Returns the index of the slot, which should be passed to drmgr_get_cls_field() and drmgr_set_cls_field(). Returns -1 if there are no more slots available.

Callbacks are frequent, but normally the stack of callback contexts is only a few entries deep. It is most efficient to re-use cls data from prior callbacks, only allocating new memory when entering a new context stack depth. The \p cb_init_func parameter is invoked on each new callback context, with \p new_depth set to true only when entering a new callback context stack depth. When \p new_depth is false, drmgr_get_cls_field() will return the value set at that depth the last time it was reached, and the client would normally not need to allocate memory but would only need to initialize it. When \p new_depth is true, drmgr_get_cls_field() will return NULL, and the user should use drmgr_set_cls_field() to initialize the slot itself as well as whatever it points to.

Similarly, normal usage should ignore \p cb_exit_func unless it is called with \p thread_exit set to true, in which case any memory in the cls slot should be de-allocated.

Callbacks are Windows-specific. The cls interfaces are not marked for Windows-only, however, to facilitate cross-platform code. We recommend that cross-plaform code be written using cls fields on both platforms; the fields on Linux will never be stacked and will function as tls fields. Technically the same context interruption can occur with a Linux signal, but Linux signals typically execute small amounts of code and avoid making stateful changes; furthermore, there is no guaranteed end point to a signal. The drmgr_push_cls() and drmgr_pop_cls() interface can be used to provide a stack of contexts on Linux, or to provide a stack of contexts for any other purpose such as layered wrapped functions. These push and pop functions are automatically called on Windows callback entry and exit, with the push called in DR’s kernel xfer event prior to any client callback for that event, and pop called in the same event but after any client callback.