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.
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.