Routines for Handling Thread-specific Data

The easiest way to handle thread-local data is to use a Thread-Local-Storage Section in your program. It is assumed that you understand the Thread-Local Storage facility.

Library routines are also provided to give you control over the way in which thread-specific data is handled. These routines enable your program to:

Allocating Thread-local Data From the Dynamic Heap

You can allocate thread-local data from the dynamic heap via CBL_ALLOC_MEM or the modular CBL_ALLOC_THREAD_MEM. The advantage of this form of allocation is that multiple memory blocks of varying sizes can be allocated and associated with a thread and/or program.

CBL_ALLOC_MEM can associate allocated heap data with a thread and the calling program. depending on the setting of the input parameters. CBL_ALLOC_THREAD_MEM always associates any allocated heap data with a thread, and optionally the calling program.

Memory allocated by these routines is automatically cleaned-up when the thread terminates.

Note that any pointer to thread-local storage returned by these calls should be saved in a Thread-Local Storage defined pointer, so that its value can be retrieved on subsequent calls to the program that allocated the thread-local storage area. Saving the returned pointer in a Working-Storage defined pointer and subsequently using that value causes the thread local heap area to be shared among threads and is bad programming practice.

Accessing Thread-local Data From an Initialized Thread-storage Handle

Routines are supplied that enable a program to access thread-local data from an initialized thread-storage handle. This handle is returned by the CBL_TSTORE_CREATE routine. Memory is returned by CBL_TSTORE_GET using a specific handle. The memory is of a fixed size and is the same across all invocations of CBL_TSTORE_GET within that thread. These routines provide, in essence, a distinct thread-local-storage area for each initialized handle.