OS_TLS_SetDestruct
Description
Assigns a “destructor function” to a TLS (thread-local storage) ID. All destructor functions that have been set for the TLS IDs will be called when the task is deleted. Destructor functions are thus common to all tasks. Note that a destructor function must be declared as follows:
void MyDestructFunction (OS_TCB *p_tcb, OS_TLS_ID id, OS_TLS value);
When the destructor function is called, it will be passed the address of the OS_TCB
for the task being deleted, the TLS ID that is being destructed and the value of p_tcb->TLS_Tbl[id]
which was set by OS_TLS_SetValue()
.
Files
os.h/os_tls.c
Prototype
void OS_TLS_SetDestruct (OS_TLS_ID id, OS_TLS_DESTRUCT_PTR p_destruct, OS_ERR *p_err)
Arguments
id
is the TLS ID for which you want to set the destructor function for.
p_destruct
is a pointer to the destructor function you want to assign to the TLS ID.
p_err
is a pointer to a variable that contains an error code returned by this function. Possible values are:
OS_ERR_NONE
If the call was successful and the destructor function was assigned to the TLS ID value.
OS_ERR_TLS_DESTRUCT_ASSIGNED
If a destructor function has already been assigned. You can only assign a destructor function once for each TLS ID.
OS_ERR_TLS_ID_INVALID
If you specified a TLS ID that has not been assigned. See OS_TLS_GetID()
about assigning TLS IDs.
Returned Value
None
Required Configuration
OS_CFG_TLS_TBL_SIZE
must be greater than 0 in os_cfg.h
. Refer to µC-OS-III Configuration Manual.
Callers
Application.
Notes/Warnings
- You can only call
OS_TLS_SetDestruct()
once for each TLS ID. - Note that not all implementations of
os_tls.c
will have destructors for TLS IDs.
Example Usage
void MyDestructFunction (OS_TCB *p_tcb, OS_TLS_ID id, OS_TLS value); OS_TLS_ID MyTLS_ID; void main (void) { OS_ERR err; : OSInit(&err); : : MyTLS_ID = OS_TLS_GetID(&err); /* Obtain the next available TLS ID */ OS_TLS_SetDestruct((OS_TLS_ID)MyTLS_ID, (OS_TLS_DESTRUCT_PTR)MyTLS_Destructor, (OS_ERR *)&err); /* Check "err" */ : : } void MyDestructFunction (OS_TCB *p_tcb, OS_TLS_ID id, OS_TLS value) { /* Note that 'value' is typically a 'void *' that points to storage area for the TLS */ }