#include <libcork/threads.h>
libcork provides several functions for handling threads and writing thread-aware code in a portable way.
We provide several platform-agnostic macros for implementing common atomic operations.
Atomically check whether the variable pointed to by var contains the value old_value, and if so, update it to contain the value new_value. We return the value of var before the compare-and-swap. (If this value is equal to old_value, then the compare-and-swap was successful.)
An identifier for a thread in the current process.
Returns the identifier of the currently executing thread.
The functions in this section let you ensure that a particular piece of code is executed exactly once, even if multiple threads attempt the execution at roughly the same time.
Declares a barrier that can be used with the cork_once() macro.
Ensure that call (which can be an arbitrary statement) is executed exactly once, regardless of how many times control reaches the call to cork_once. If control reaches the cork_once call at roughly the same time in multiple threads, exactly one of them will be allowed to execute the code. The call to cork_once won’t return until call has been executed.
If you have multiple calls to cork_once that use the same barrier, then exactly one call will succeed. If the call statements are different in those cork_once invocations, then it’s undefined which one gets executed.
It’s fine if the function that contains the cork_once call is recursive; if the same thread tries to obtain the underlying lock multiple times, the second and later calls will silently succeed.
These macros are usually used to initialize a static variable that will be shared across multiple threads:
static struct my_type shared_value;
static void
expensive_initialization(void)
{
/* do something to initialize shared_value */
}
cork_once_barrier(shared_value_once);
struct my_type *
get_shared_value(void)
{
cork_once(shared_value_once, expensive_initialization());
return &shared_value;
}
Each thread can then call get_shared_value to retrieve a properly initialized instance of struct my_type. Regardless of how many threads call this function, and how often they call it, the value will be initialized exactly once, and will be guaranteed to be initialized before any thread tries to use it.
The macro in this section can be used to create thread-local storage in a platform-agnostic manner.
Creates a static function called [name]_get, which will return a pointer to a thread-local instance of type. This is a static function, so it won’t be visible outside of the current compilation unit.
When a particular thread’s instance is created for the first time, it will be filled with 0 bytes. If the actual type needs more complex initialization before it can be used, you can create a wrapper struct that contains a boolean indiciating whether that initialization has happened:
struct wrapper {
bool initialized;
struct real_type val;
};
cork_tls(struct wrapper, wrapper);
static struct real_type *
real_type_get(void)
{
struct wrapper * wrapper = wrapper_get();
struct real_type * real_val = &wrapper->val;
if (CORK_UNLIKELY(!wrapper->initialized)) {
expensive_initialization(real_val);
}
return real_val;
}
It’s also not possible to provide a finalization function; if your thread-local variable acquires any resources or memory that needs to be freed when the thread finishes, you must make a “thread cleanup” function that you explicitly call at the end of each thread.
Note
On some platforms, the number of thread-local values that can be created by any given process is limited (i.e., on the order of 128 or 256 values). This means that you should limit the number of thread-local values you create, especially in a library.