Define rmw_initialize_error_handling_thread_local_storage
Defined in File error_handling.h
Define Documentation
-
rmw_initialize_error_handling_thread_local_storage
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.- Returns:
RCUTILS_RET_OKif successful, or- Returns:
RCUTILS_RET_INVALID_ARGUMENTif the allocator is invalid, or- Returns:
RCUTILS_RET_BAD_ALLOCif allocating memory fails, or- Returns:
RCUTILS_RET_ERRORif an unspecified error occurs.