Description

These functions are provided for cases when an application requires a function to be automatically called when a thread exits. This is often useful when, for example, freeing up resources allocated by the thread.

This support must be enabled with the configuration option CYGPKG_KERNEL_THREADS_DESTRUCTORS. When enabled, you may register a function of type cyg_thread_destructor_fn to be called on thread termination using cyg_thread_add_destructor. You may also provide it with a piece of arbitrary information in the data argument which will be passed to the destructor function fn when the thread terminates. If you no longer wish to call a function previous registered with cyg_thread_add_destructor, you may call cyg_thread_rem_destructor with the same parameters used to register the destructor function. Both these functions return true on success and false on failure.

By default, thread destructors are per-thread, which means that registering a destructor function only registers that function for the current thread. In other words, each thread has its own list of destructors. Alternatively you may disable the configuration option CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD in which case any registered destructors will be run when any threads exit. In other words, the thread destructor list is global and all threads have the same destructors.

There is a limit to the number of destructors which may be registered, which can be controlled with the CYGNUM_KERNEL_THREADS_DESTRUCTORS configuration option. Increasing this value will very slightly increase the amount of memory in use, and when CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD is enabled, the amount of memory used per thread will increase. When the limit has been reached, cyg_thread_add_destructor will return false.

Valid contexts

When CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD is enabled, these functions must only be called from a thread context as they implicitly operate on the current thread. When CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD is disabled, these functions may be called from thread or DSR context, or at initialization time.