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

1. You can only call OS_TLS_SetDestruct() once for each TLS ID.
2. 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 */
          }