eCos Reference Manual
Prev |  | Next

# Thread destructors

## Name

cyg_thread_add_destructor, cyg_thread_rem_destructor -- Call functions on thread termination

## Synopsis

    #include <cyg/kernel/kapi.h>
    typedef void (*cyg_thread_destructor_fn)(cyg_addrword_t);

``cyg_bool_t cyg_thread_add_destructor`(cyg_thread_destructor_fn fn, cyg_addrword_t data);`

``cyg_bool_t cyg_thread_rem_destructor`(cyg_thread_destructor_fn fn, cyg_addrword_t data);`

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

Prev | Home | Next
Per-thread data | Up | Exception handling