RTEMS 4.6.0pre5 On-Line Library

Task Manager TASK_VARIABLE_ADD - Associate per task variable

RTEMS C User's Guide

5.4.15: TASK_VARIABLE_ADD - Associate per task variable

CALLING SEQUENCE:

rtems_status_code rtems_task_variable_add(
  rtems_id  tid,
  void    **ptr,
  void    (*dtor)(void *)
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL - per task variable added successfully
RTEMS_INVALID_ID - invalid task id
RTEMS_NO_MEMORY - invalid task id
RTEMS_ILLEGAL_ON_REMOTE_OBJECT - not supported on remote tasks

DESCRIPTION:

This directive adds the memory location specified by the ptr argument to the context of the given task. The variable will then be private to the task. The task can access and modify the variable, but the modifications will not appear to other tasks, and other tasks' modifications to that variable will not affect the value seen by the task. This is accomplished by saving and restoring the variable's value each time a task switch occurs to or from the calling task. If the dtor argument is non-NULL it specifies the address of a `destructor' function which will be called when the task is deleted. The argument passed to the destructor function is the task's value of the variable.

NOTES:

Task variables increase the context switch time to and from the tasks that own them so it is desirable to minimize the number of task variables. One efficient method is to have a single task variable that is a pointer to a dynamically allocated structure containing the task's private `global' data. In this case the destructor function could be `free'.

RTEMS C User's Guide