VxWorks Reference Manual : Libraries
taskVarLib - task variables support library
taskVarInit( ) - initialize the task variables facility
taskVarAdd( ) - add a task variable to a task
taskVarDelete( ) - remove a task variable from a task
taskVarGet( ) - get the value of a task variable
taskVarSet( ) - set the value of a task variable
taskVarInfo( ) - get a list of task variables of a task
VxWorks provides a facility called "task variables," which allows 4-byte variables to be added to a task's context, and the variables' values to be switched each time a task switch occurs to or from the calling task. Typically, several tasks declare the same variable (4-byte memory location) as a task variable and treat that memory location as their own private variable. For example, this facility can be used when a routine must be spawned more than once as several simultaneous tasks.
The routines taskVarAdd( ) and taskVarDelete( ) are used to add or delete a task variable. The routines taskVarGet( ) and taskVarSet( ) are used to get or set the value of a task variable.
If you are using task variables in a task delete hook (see taskHookLib), refer to the manual entry for taskVarInit( ) for warnings on proper usage.
taskVarLib.h
taskVarLib, taskHookLib, VxWorks Programmer's Guide: Basic OS
taskVarInit( ) - initialize the task variables facility
STATUS taskVarInit (void)
This routine initializes the task variables facility. It installs task switch and delete hooks used for implementing task variables. If taskVarInit( ) is not called explicitly, taskVarAdd( ) will call it automatically when the first task variable is added.
After the first invocation of this routine, subsequent invocations have no effect.
Order dependencies in task delete hooks often involve task variables. If a facility uses task variables and has a task delete hook that expects to use those task variables, the facility's delete hook must run before the task variables' delete hook. Otherwise, the task variables will be deleted by the time the facility's delete hook runs.
VxWorks is careful to run the delete hooks in reverse of the order in which they were installed. Any facility that has a delete hook that will use task variables can guarantee proper ordering by calling taskVarInit( ) before adding its own delete hook.
Note that this is not an issue in normal use of task variables. The issue only arises when adding another task delete hook that uses task variables.
Caution should also be taken when adding task variables from within create hooks. If the task variable package has not been installed via taskVarInit( ), the create hook attempts to create a create hook, and that may cause system failure. To avoid this situation, taskVarInit( ) should be called during system initialization from the root task, usrRoot( ), in usrConfig.c.
OK, or ERROR if the task switch/delete hooks could not be installed.
taskVarAdd( ) - add a task variable to a task
STATUS taskVarAdd ( int tid, /* ID of task to have new variable */ int * pVar /* pointer to variable to be switched for task */ )
This routine adds a specified variable pVar (4-byte memory location) to a specified task's context. After calling this routine, the variable will 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 initial value each time a task switch occurs to or from the calling task.
This facility can be used when a routine is to be spawned repeatedly as several independent tasks. Although each task will have its own stack, and thus separate stack variables, they will all share the same static and global variables. To make a variable not shareable, the routine can call taskVarAdd( ) to make a separate copy of the variable for each task, but all at the same physical address.
Note that task variables increase the task switch time to and from the tasks that own them. Therefore, it is desirable to limit the number of task variables that a task uses. One efficient way to use task variables is to have a single task variable that is a pointer to a dynamically allocated structure containing the task's private data.
Assume that three identical tasks were spawned with a routine called operator( ). All three use the structure OP_GLOBAL for all variables that are specific to a particular incarnation of the task. The following code fragment shows how this is set up:
OP_GLOBAL *opGlobal; /* ptr to operator task's global variables */ void operator ( int opNum /* number of this operator task */ ) { if (taskVarAdd (0, (int *)&opGlobal) != OK) { printErr ("operator%d: can't taskVarAdd opGlobal\n", opNum); taskSuspend (0); } if ((opGlobal = (OP_GLOBAL *) malloc (sizeof (OP_GLOBAL))) == NULL) { printErr ("operator%d: can't malloc opGlobal\n", opNum); taskSuspend (0); } ... }
OK, or ERROR if memory is insufficient for the task variable descriptor.
taskVarLib, taskVarDelete( ), taskVarGet( ), taskVarSet( )
taskVarDelete( ) - remove a task variable from a task
STATUS taskVarDelete ( int tid, /* ID of task whose variable is to be removed */ int * pVar /* pointer to task variable to be removed */ )
This routine removes a specified task variable, pVar, from the specified task's context. The private value of that variable is lost.
OK, or ERROR if the task variable does not exist for the specified task.
taskVarLib, taskVarAdd( ), taskVarGet( ), taskVarSet( )
taskVarGet( ) - get the value of a task variable
int taskVarGet ( int tid, /* ID of task whose task variable is to be retrieved */ int * pVar /* pointer to task variable */ )
This routine returns the private value of a task variable for a specified task. The specified task is usually not the calling task, which can get its private value by directly accessing the variable. This routine is provided primarily for debugging purposes.
The private value of the task variable, or ERROR if the task is not found or it does not own the task variable.
taskVarLib, taskVarAdd( ), taskVarDelete( ), taskVarSet( )
taskVarSet( ) - set the value of a task variable
STATUS taskVarSet ( int tid, /* ID of task whose task variable is to be set */ int * pVar, /* pointer to task variable to be set for this task */ int value /* new value of task variable */ )
This routine sets the private value of the task variable for a specified task. The specified task is usually not the calling task, which can set its private value by directly modifying the variable. This routine is provided primarily for debugging purposes.
OK, or ERROR if the task is not found or it does not own the task variable.
taskVarLib, taskVarAdd( ), taskVarDelete( ), taskVarGet( )
taskVarInfo( ) - get a list of task variables of a task
int taskVarInfo ( int tid, /* ID of task whose task variable is to be set */ TASK_VAR varList[], /* array to hold task variable addresses */ int maxVars /* maximum variables varList can accommodate */ )
This routine provides the calling task with a list of all of the task variables of a specified task. The unsorted array of task variables is copied to varList.
Kernel rescheduling is disabled with taskLock( ) while task variables are looked up. There is no guarantee that all the task variables are still valid or that new task variables have not been created by the time this routine returns.
The number of task variables in the list.