Function rcutils_initialize_error_handling_thread_local_storage

Function Documentation

rcutils_ret_t rcutils_initialize_error_handling_thread_local_storage(rcutils_allocator_t allocator)

Forces initialization of thread-local storage if called in a newly created thread.

If this function is not called beforehand, then the first time the error state is set or the first time the error message is retrieved, the default allocator will be used to allocate thread-local storage.

This function may or may not allocate memory. The system’s thread-local storage implementation may need to allocate memory, since it usually has no way of knowing how much storage is needed without knowing how many threads will be created. Most implementations (e.g. C11, C++11, and pthread) do not have ways to specify how this memory is allocated, but if the implementation allows, the given allocator to this function will be used, but is otherwise unused. This only occurs when creating and destroying threads, which can be avoided in the “steady” state by reusing pools of threads.

It is worth considering that repeated thread creation and destruction will result in repeated memory allocations and could result in memory fragmentation. This is typically avoided anyways by using pools of threads.

In case an error is indicated by the return code, no error message will have been set.

If called more than once in a thread, or after implicitly initialized by setting the error state, it will still return RCUTILS_RET_OK, even if the given allocator is invalid. Essentially this function does nothing if thread-local storage has already been called. If already initialized, the given allocator is ignored, even if it does not match the allocator used originally to initialize the thread-local storage.

Parameters:

allocator – [in] to be used to allocate and deallocate memory

Returns:

RCUTILS_RET_OK if successful, or

Returns:

RCUTILS_RET_INVALID_ARGUMENT if the allocator is invalid, or

Returns:

RCUTILS_RET_BAD_ALLOC if allocating memory fails, or

Returns:

RCUTILS_RET_ERROR if an unspecified error occurs.