📄 taskvarlib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/taskVarLib.html - generated by refgen from taskVarLib.c --> <title> taskVarLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.html"><i>VxWorks Reference Manual : Libraries</i></a></p></blockquote><h1>taskVarLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>taskVarLib</strong> - task variables support library </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><i><a href="./taskVarLib.html#taskVarInit">taskVarInit</a></i>( )</b> - initialize the task variables facility<br><b><i><a href="./taskVarLib.html#taskVarAdd">taskVarAdd</a></i>( )</b> - add a task variable to a task<br><b><i><a href="./taskVarLib.html#taskVarDelete">taskVarDelete</a></i>( )</b> - remove a task variable from a task<br><b><i><a href="./taskVarLib.html#taskVarGet">taskVarGet</a></i>( )</b> - get the value of a task variable<br><b><i><a href="./taskVarLib.html#taskVarSet">taskVarSet</a></i>( )</b> - set the value of a task variable<br><b><i><a href="./taskVarLib.html#taskVarInfo">taskVarInfo</a></i>( )</b> - get a list of task variables of a task<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>VxWorks provides a facility called "task variables," which allows4-byte variables to be added to a task's context, and thevariables' values to be switched each time a task switch occurs to orfrom the calling task. Typically, several tasks declare the samevariable (4-byte memory location) as a task variable and treat thatmemory location as their own private variable. For example, thisfacility can be used when a routine must be spawned more than once asseveral simultaneous tasks.<p>The routines <b><i><a href="./taskVarLib.html#taskVarAdd">taskVarAdd</a></i>( )</b> and <b><i><a href="./taskVarLib.html#taskVarDelete">taskVarDelete</a></i>( )</b> are used to add or deletea task variable. The routines <b><i><a href="./taskVarLib.html#taskVarGet">taskVarGet</a></i>( )</b> and <b><i><a href="./taskVarLib.html#taskVarSet">taskVarSet</a></i>( )</b> are used to getor set the value of a task variable.<p></blockquote><h4>NOTE</h4><blockquote><p>If you are using task variables in a task delete hook(see <b><a href="./taskHookLib.html#top">taskHookLib</a></b>), refer to the manual entry for <b><i><a href="./taskVarLib.html#taskVarInit">taskVarInit</a></i>( )</b>for warnings on proper usage.<p></blockquote><h4>INCLUDE FILES</h4><blockquote><p><b>taskVarLib.h</b><p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./taskVarLib.html#top">taskVarLib</a></b>, <b><a href="./taskHookLib.html#top">taskHookLib</a></b>, <i>VxWorks Programmer's Guide: Basic OS</i><hr><a name="taskVarInit"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>taskVarInit</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>taskVarInit</i>( )</strong> - initialize the task variables facility</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS taskVarInit (void)</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine initializes the task variables facility. It installs taskswitch and delete hooks used for implementing task variables.If <b><i><a href="./taskVarLib.html#taskVarInit">taskVarInit</a></i>( )</b> is not called explicitly, <b><i><a href="./taskVarLib.html#taskVarAdd">taskVarAdd</a></i>( )</b> will call itautomatically when the first task variable is added.<p>After the first invocation of this routine, subsequent invocationshave no effect.<p></blockquote><h4>WARNING</h4><blockquote><p>Order dependencies in task delete hooks often involvetask variables. If a facility uses task variables and has atask delete hook that expects to use those task variables,the facility's delete hook must run before the taskvariables' delete hook. Otherwise, the task variableswill be deleted by the time the facility's delete hook runs.<p>VxWorks is careful to run the delete hooks in reverse of the order inwhich they were installed. Any facility that has a delete hook that willuse task variables can guarantee proper ordering by calling <b><i><a href="./taskVarLib.html#taskVarInit">taskVarInit</a></i>( )</b>before adding its own delete hook.<p>Note that this is not an issue in normal use of task variables. The issueonly arises when adding another task delete hook that uses task variables.<p>Caution should also be taken when adding task variables from withincreate hooks. If the task variable package has not been installed via<b><i><a href="./taskVarLib.html#taskVarInit">taskVarInit</a></i>( )</b>, the create hook attempts to create a create hook, and thatmay cause system failure. To avoid this situation, <b><i><a href="./taskVarLib.html#taskVarInit">taskVarInit</a></i>( )</b> shouldbe called during system initialization from the root task, <b><i><a href="./usrConfig.html#usrRoot">usrRoot</a></i>( )</b>, in<b>usrConfig.c</b>.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, or ERROR if the task switch/delete hooks could not be installed.</blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./taskVarLib.html#top">taskVarLib</a></b><hr><a name="taskVarAdd"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>taskVarAdd</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>taskVarAdd</i>( )</strong> - add a task variable to a task</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS taskVarAdd ( int tid, /* ID of task to have new variable */ int * pVar /* pointer to variable to be switched for task */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine adds a specified variable <i>pVar</i> (4-byte memory location) to aspecified task's context. After calling this routine, the variable willbe private to the task. The task can access and modify the variable, butthe modifications will not appear to other tasks, and other tasks'modifications to that variable will not affect the value seen by thetask. This is accomplished by saving and restoring the variable's initialvalue each time a task switch occurs to or from the calling task.<p>This facility can be used when a routine is to be spawned repeatedly asseveral independent tasks. Although each task will have its own stack,and thus separate stack variables, they will all share the same static andglobal variables. To make a variable <i>not</i> shareable, the routine cancall <b><i><a href="./taskVarLib.html#taskVarAdd">taskVarAdd</a></i>( )</b> to make a separate copy of the variable for each task, butall at the same physical address.<p>Note that task variables increase the task switch time to and from thetasks that own them. Therefore, it is desirable to limit the number oftask 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.<p></blockquote><h4>EXAMPLE</h4><blockquote><p><p>Assume that three identical tasks were spawned with a routine called<i><b><i>operator</i>( )</b></i>. All three use the structure <b>OP_GLOBAL</b> for all variablesthat are specific to a particular incarnation of the task. The followingcode fragment shows how this is set up:<p><pre>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); } ... }</pre></blockquote><h4>RETURNS</h4><blockquote><p><p>OK, or ERROR if memory is insufficient for the task variable descriptor.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./taskVarLib.html#top">taskVarLib</a></b>, <b><i><a href="./taskVarLib.html#taskVarDelete">taskVarDelete</a></i>( )</b>, <b><i><a href="./taskVarLib.html#taskVarGet">taskVarGet</a></i>( )</b>, <b><i><a href="./taskVarLib.html#taskVarSet">taskVarSet</a></i>( )</b><hr><a name="taskVarDelete"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>taskVarDelete</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>taskVarDelete</i>( )</strong> - remove a task variable from a task</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS taskVarDelete ( int tid, /* ID of task whose variable is to be removed */ int * pVar /* pointer to task variable to be removed */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine removes a specified task variable, <i>pVar</i>, from the specifiedtask's context. The private value of that variable is lost.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, orERROR if the task variable does not exist for the specified task.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./taskVarLib.html#top">taskVarLib</a></b>, <b><i><a href="./taskVarLib.html#taskVarAdd">taskVarAdd</a></i>( )</b>, <b><i><a href="./taskVarLib.html#taskVarGet">taskVarGet</a></i>( )</b>, <b><i><a href="./taskVarLib.html#taskVarSet">taskVarSet</a></i>( )</b><hr><a name="taskVarGet"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>taskVarGet</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>taskVarGet</i>( )</strong> - get the value of a task variable</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>int taskVarGet ( int tid, /* ID of task whose task variable is to be retrieved */ int * pVar /* pointer to task variable */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine returns the private value of a task variable for aspecified 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.<p></blockquote><h4>RETURNS</h4><blockquote><p><p>The private value of the task variable, orERROR if the task is not found or itdoes not own the task variable.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./taskVarLib.html#top">taskVarLib</a></b>, <b><i><a href="./taskVarLib.html#taskVarAdd">taskVarAdd</a></i>( )</b>, <b><i><a href="./taskVarLib.html#taskVarDelete">taskVarDelete</a></i>( )</b>, <b><i><a href="./taskVarLib.html#taskVarSet">taskVarSet</a></i>( )</b><hr><a name="taskVarSet"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>taskVarSet</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>taskVarSet</i>( )</strong> - set the value of a task variable</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>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 */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine sets the private value of the task variable for a specifiedtask. The specified task is usually not the calling task, which can setits private value by directly modifying the variable. This routine isprovided primarily for debugging purposes.<p></blockquote><h4>RETURNS</h4><blockquote><p><p>OK, orERROR if the task is not found or itdoes not own the task variable.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./taskVarLib.html#top">taskVarLib</a></b>, <b><i><a href="./taskVarLib.html#taskVarAdd">taskVarAdd</a></i>( )</b>, <b><i><a href="./taskVarLib.html#taskVarDelete">taskVarDelete</a></i>( )</b>, <b><i><a href="./taskVarLib.html#taskVarGet">taskVarGet</a></i>( )</b><hr><a name="taskVarInfo"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>taskVarInfo</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>taskVarInfo</i>( )</strong> - get a list of task variables of a task</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>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 */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine provides the calling task with a list of all of the taskvariables of a specified task. The unsorted array of task variables iscopied to <i>varList</i>.<p></blockquote><h4>CAVEATS</h4><blockquote><p>Kernel rescheduling is disabled with <b><i><a href="./taskLib.html#taskLock">taskLock</a></i>( )</b> while task variables arelooked up. There is no guarantee that all the task variables are stillvalid or that new task variables have not been created by the time thisroutine returns.<p></blockquote><h4>RETURNS</h4><blockquote><p>The number of task variables in the list.</blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./taskVarLib.html#top">taskVarLib</a></b></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -