\hypertarget{TASK_8h}{ \section{TASK.h File Reference} \label{TASK_8h}\index{TASK.h@{TASK.h}} } Task/Thread facility, a portable interface between Vx\-Works and POSIX implementations, callable version. {\tt \#include \char`\"{}IPBS/TOV.h\char`\"{}}\par Include dependency graph for TASK.h:\begin{figure}[H] \begin{center} \leavevmode \includegraphics[width=226pt]{TASK_8h__incl} \end{center} \end{figure} This graph shows which files directly or indirectly include this file:\begin{figure}[H] \begin{center} \leavevmode \includegraphics[width=96pt]{TASK_8h__dep__incl} \end{center} \end{figure} \subsection*{Data Structures} \begin{CompactItemize} \item struct \hyperlink{struct__TASK__attr}{\_\-TASK\_\-attr} \begin{CompactList}\small\item\em Encapsulates the more esoteric options. \item\end{CompactList}\end{CompactItemize} \subsection*{Defines} \begin{CompactItemize} \item \#define \hyperlink{TASK_8h_a0}{TASK\_\-PRINTF}(\_\-args) \begin{CompactList}\small\item\em Debugging macro acting as a stand in for printf. \item\end{CompactList}\item \#define \hyperlink{TASK_8h_a1}{TASK\_\-K\_\-NAME\_\-MAX}~16 \begin{CompactList}\small\item\em The maximum size of a task's name, including the terminating NUL character. \item\end{CompactList}\end{CompactItemize} \subsection*{Typedefs} \begin{CompactItemize} \item typedef \hyperlink{struct__TASK__attr}{\_\-TASK\_\-attr} \hyperlink{TASK_8h_a2}{TASK\_\-attr} \begin{CompactList}\small\item\em Typedef for struct {\em \hyperlink{struct__TASK__attr}{\_\-TASK\_\-attr}\/}. \item\end{CompactList}\item typedef enum \hyperlink{TASK_8h_a37}{\_\-TASK\_\-priority\_\-type} \hyperlink{TASK_8h_a3}{TASK\_\-priority\_\-type} \begin{CompactList}\small\item\em Typedef for enum {\em \_\-TASK\_\-priority\_\-type\/}. \item\end{CompactList}\item typedef void $\ast$ \hyperlink{TASK_8h_a4}{TASK\_\-parameter} \begin{CompactList}\small\item\em The type of the parameter passed to the task's entry point routine. \item\end{CompactList}\item typedef void $\ast$($\ast$ \hyperlink{TASK_8h_a5}{TASK\_\-entry} )(\hyperlink{TASK_8h_a4}{TASK\_\-parameter} parameter) \begin{CompactList}\small\item\em The function signature of the task's entry point routine. \item\end{CompactList}\item typedef \hyperlink{struct__TASK__tcb}{\_\-TASK\_\-tcb} \hyperlink{TASK_8h_a6}{TASK\_\-tcb} \begin{CompactList}\small\item\em TASK facility's definition of a Task Control Block. \item\end{CompactList}\item typedef int($\ast$ \hyperlink{TASK_8h_a7}{TASK\_\-block\_\-cb} )(void $\ast$prm) \begin{CompactList}\small\item\em Callback routine of TASK\_\-block. \item\end{CompactList}\end{CompactItemize} \subsection*{Enumerations} \begin{CompactItemize} \item enum \hyperlink{TASK_8h_a37}{\_\-TASK\_\-priority\_\-type} \{ \par \hyperlink{TASK_8h_a37a8}{TASK\_\-K\_\-PRIORITY\_\-TYPE\_\-ABS} = 0, \par \hyperlink{TASK_8h_a37a9}{TASK\_\-K\_\-PRIORITY\_\-TYPE\_\-REL} = 1 \} \begin{CompactList}\small\item\em Indicates how a priority specification to TASK\_\-attr\_\-setpriority is interpretted. \item\end{CompactList}\end{CompactItemize} \subsection*{Functions} \begin{CompactItemize} \item int \hyperlink{TASK_8h_a10}{TASK\_\-attr\_\-init} (\hyperlink{struct__TASK__attr}{TASK\_\-attr} $\ast$attributes) \begin{CompactList}\small\item\em Provides a standard method of initializing the attributes block to a set of known values. These values may be platform dependent. \item\end{CompactList}\item int \hyperlink{TASK_8h_a11}{TASK\_\-attr\_\-priority\_\-set} (\hyperlink{struct__TASK__attr}{TASK\_\-attr} $\ast$attributes, int priority) \begin{CompactList}\small\item\em Sets the priority field in the task attributes block to the the specified value. This can be either absolute or relative to the current task's priority. \item\end{CompactList}\item int \hyperlink{TASK_8h_a12}{TASK\_\-activate} (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb) \begin{CompactList}\small\item\em Activates a previously created task. \item\end{CompactList}\item int \hyperlink{TASK_8h_a13}{TASK\_\-create} (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb, const \hyperlink{struct__TASK__attr}{TASK\_\-attr} $\ast$attributes, \hyperlink{TASK_8h_a5}{TASK\_\-entry} entry\_\-point, \hyperlink{TASK_8h_a4}{TASK\_\-parameter} parameter) \begin{CompactList}\small\item\em Creates, but does not activate a task. \item\end{CompactList}\item int \hyperlink{TASK_8h_a14}{TASK\_\-convert} (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb, const \hyperlink{struct__TASK__attr}{TASK\_\-attr} $\ast$attributes, \hyperlink{TASK_8h_a5}{TASK\_\-entry} entry\_\-point, \hyperlink{TASK_8h_a4}{TASK\_\-parameter} parameter) \begin{CompactList}\small\item\em Converts an existing Vx\-Works task to a TASK. \item\end{CompactList}\item int \hyperlink{TASK_8h_a15}{TASK\_\-spawn} (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb, const \hyperlink{struct__TASK__attr}{TASK\_\-attr} $\ast$attributes, \hyperlink{TASK_8h_a5}{TASK\_\-entry} entry\_\-point, \hyperlink{TASK_8h_a4}{TASK\_\-parameter} parameter) \begin{CompactList}\small\item\em Convenience routine to both create and activate a task. \item\end{CompactList}\item int \hyperlink{TASK_8h_a16}{TASK\_\-destroy} (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb) \begin{CompactList}\small\item\em Destroys, ie deletes, a previously created task. \item\end{CompactList}\item void \hyperlink{TASK_8h_a17}{TASK\_\-exit} (void $\ast$status) \begin{CompactList}\small\item\em Causes the calling task to delete itself and allows notification to another task, via {\em \hyperlink{TASK_8h_a18}{TASK\_\-join()}\/} that the calling task has deleted itself. \item\end{CompactList}\item int \hyperlink{TASK_8h_a18}{TASK\_\-join} (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb, void $\ast$$\ast$status) \begin{CompactList}\small\item\em Blocks the calling task until the specified task completes. \item\end{CompactList}\item int \hyperlink{TASK_8h_a19}{TASK\_\-revert} (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb) \begin{CompactList}\small\item\em Strips a task/thread of its TASK functionality. \item\end{CompactList}\item \hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ \hyperlink{TASK_8h_a20}{TASK\_\-cvt} (void) \begin{CompactList}\small\item\em Converts an existing VXWORKs task or POSIX thread to TASK object. \item\end{CompactList}\item int \hyperlink{TASK_8h_a21}{TASK\_\-rvt} (void) \begin{CompactList}\small\item\em Reverts the current task back to its native self by stripping it of its TASK functionality. \item\end{CompactList}\item int \hyperlink{TASK_8h_a22}{TASK\_\-pause} (unsigned int nsecs) \begin{CompactList}\small\item\em Causes the calling task to wait (pause) for the specified number of nanoseconds. \item\end{CompactList}\item int \hyperlink{TASK_8h_a23}{TASK\_\-resume} (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb) \begin{CompactList}\small\item\em Resumes a previously suspended task. \item\end{CompactList}\item int \hyperlink{TASK_8h_a24}{TASK\_\-suspend} (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb) \begin{CompactList}\small\item\em Suspends a task. \item\end{CompactList}\item int \hyperlink{TASK_8h_a25}{TASK\_\-wait} (const \hyperlink{TOV_8h_8vx-xxx-xxx_a8}{TOV} tov) \begin{CompactList}\small\item\em Causes the calling task to wait (pause) until the specified timeout is reached. \item\end{CompactList}\item int \hyperlink{TASK_8h_a26}{TASK\_\-block} (\hyperlink{TASK_8h_8vx-xxx-xxx_a7}{TASK\_\-block\_\-handle} $\ast$tbh, \hyperlink{TASK_8h_a7}{TASK\_\-block\_\-cb} rtn, void $\ast$prm) \begin{CompactList}\small\item\em Provides a simple way to turn an asynchronous routine into a synchronous routine. \item\end{CompactList}\item int \hyperlink{TASK_8h_a27}{TASK\_\-unblock} (\hyperlink{TASK_8h_8vx-xxx-xxx_a7}{TASK\_\-block\_\-handle} tbh) \begin{CompactList}\small\item\em Unblocks a task blocked on a call to TASK\_\-block. \item\end{CompactList}\item int \hyperlink{TASK_8h_a28}{TASK\_\-priority\_\-get} (const \hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb) \begin{CompactList}\small\item\em Gets the current priority of the specified task. The priority is returned expressed in the native tasking model's scheme. \item\end{CompactList}\item int \hyperlink{TASK_8h_a29}{TASK\_\-tcb\_\-sizeof} (void) \begin{CompactList}\small\item\em Returns the size, in bytes, of a TCB to be used when creating or spawning a TASK. \item\end{CompactList}\item int \hyperlink{TASK_8h_a30}{TASK\_\-xtcb\_\-sizeof} (void) \begin{CompactList}\small\item\em Returns the size, in bytes, of a TCB to be used when converting an existing (platform native task) to a TASK type task. \item\end{CompactList}\item \hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ \hyperlink{TASK_8h_a31}{TASK\_\-self} (void) \begin{CompactList}\small\item\em Returns the tcb of the calling task. \item\end{CompactList}\item const char $\ast$ \hyperlink{TASK_8h_a32}{TASK\_\-name} (const \hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb) \begin{CompactList}\small\item\em Returns a pointer to the task's name. \item\end{CompactList}\item int \hyperlink{TASK_8h_a33}{TASK\_\-priority\_\-number\_\-boost} (int priority, int boost) \begin{CompactList}\small\item\em Boosts the {\em priority\/} number by the {\em boost\/}. \item\end{CompactList}\item int \hyperlink{TASK_8h_a34}{TASK\_\-priority\_\-number\_\-compute} (int priority, \hyperlink{TASK_8h_a3}{TASK\_\-priority\_\-type} type, const \hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb) \begin{CompactList}\small\item\em Computes a priority number, either as an absolute or based on the priority of another task. \item\end{CompactList}\item int \hyperlink{TASK_8h_a35}{TASK\_\-priority\_\-number\_\-limit} (int priority) \begin{CompactList}\small\item\em Limits the priority number to fit within the specified bounds. \item\end{CompactList}\item int \hyperlink{TASK_8h_a36}{TASK\_\-priority\_\-set} (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$tcb, int priority) \begin{CompactList}\small\item\em Sets priority of the specified task to the specified value. \item\end{CompactList}\end{CompactItemize} \subsection{Detailed Description} Task/Thread facility, a portable interface between Vx\-Works and POSIX implementations, callable version. \begin{Desc} \item[Author:]JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc} \footnotesize\begin{verbatim} CVS $Id: TASK.h,v 1.1.1.1 2006/02/10 21:45:36 saxton Exp $ \end{verbatim} \normalsize \begin{Desc} \item[SYNOPSIS]These routines attempt to make TASK/THREAD manipulation portable across Vx\-Works and POSIX implementations. The thread models of these two systems are rather different so this is not an easy job and the rough edges certainly show.\end{Desc} \begin{Desc} \item[PRIORITIES]The Vx\-Works and POSIX priorities are, unfortunately very different. The Vx\-Works priorities run from the highest (0) to the lowest (255). POSIX priorities run from the lowest (1) to the highest (99).\end{Desc} One possibly portable scheme would map the two priorities into a common set. For example, accept the POSIX priorities and map the Vx\-Works priorities into them or vica-versa. Unfortunately either way has problems. This mapping could be done in one of two ways. The first would map the full range of the Vx\-Works set to the full range of the POSIX set. This mapping scheme could cause two different Vx\-Works priorities to map to the same POSIX priority, changing the priority relationship between the two tasks. This is unacceptable. Another way would be to map some restricted range of the Vx\-Works set (say 0-98) to the POSIX range. This is better but suffers from another problem. Some Vx\-Works layered products start tasks that run at very specific priorities, for example, the Network task when running with a TCP/IP stack. The user must be careful to correctly position his task's priority relative to these tasks. Restricting the range Vx\-Work's range could impair this ability. Another possibility is to map the POSIX set to the Vx\-Works set. One would always specify priorities in the POSIX scheme. This would avoid the problem of mapping two different priorities to the identical priorities. The cost of this would be to restrict the Vx\-Works priority set to 100 different priorities. This might be acceptable, but runs counter to the PBS philosophy of providing a portable set of routines biased towards the Vx\-Works implementation. In the end, there is really no good way to merge these two different schemes. The compromise is that absolute priorities are deemed to be not a portable concept. If the user chooses to use absolute priorities, it is up to him to layer this out. The TASK routines will, however, support the concept of RAISING and LOWERING priorities by a fixed delta. The only restriction is that the resulting priority must lie within the implementations acceptable range. Note that RAISING and LOWERING always means a task with a higher priority runs before a task of lower priority. In the Vx\-Works implementation RAISING the priority results in lowering the task's priority number. (God, this is confusing.) Two sets of limits are given \footnotesize\begin{verbatim} Symbol Meaning VxWorks POSIX TASK_K_PRIORITY_MIN Minimum task priority number 0 1 TASK_K_PRIORITY_MAX Maximum task priority number 255 99 TASK_K_PRIORITY_LO Lowest task priority number 255 1 TASK_K_PRIORITY_HI Highest task priority number 0 99 \end{verbatim} \normalsize The first set is useful for limit checking, {\em i.e\/}. making sure a given priority is acceptable on that platform. The second set allows one to implement a relative mapping scheme. \begin{Desc} \item[STACKS]The POSIX version supports only specifying a stack size. In both the Vx\-Works and POSIX cases TASK\_\-K\_\-STACK\_\-SIZE\_\-MIN provides a symbol for the minimum stack size. The Vx\-Works version supports stack allocation. It is up to the user to figure out how to make this portable. Sorry....\end{Desc} \subsection{Define Documentation} \hypertarget{TASK_8h_a1}{ \index{TASK.h@{TASK.h}!TASK_K_NAME_MAX@{TASK\_\-K\_\-NAME\_\-MAX}} \index{TASK_K_NAME_MAX@{TASK\_\-K\_\-NAME\_\-MAX}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-K\_\-NAME\_\-MAX]{\setlength{\rightskip}{0pt plus 5cm}\#define TASK\_\-K\_\-NAME\_\-MAX~16}} \label{TASK_8h_a1} The maximum size of a task's name, including the terminating NUL character. This quantity is defined for portability reasons. One some platforms, there is no maximum size, but, given that the only value of the name is for display purposes, it makes it easier to write displays if the name is limited to some reasonable number of characters. So, the request is that the user's of TASK limit the task names to this value independent of whether the underlying OS supports more or not. Note, however, that the TASK facility does not enforce this policy.\hypertarget{TASK_8h_a0}{ \index{TASK.h@{TASK.h}!TASK_PRINTF@{TASK\_\-PRINTF}} \index{TASK_PRINTF@{TASK\_\-PRINTF}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-PRINTF]{\setlength{\rightskip}{0pt plus 5cm}\#define TASK\_\-PRINTF(\_\-args)}} \label{TASK_8h_a0} Debugging macro acting as a stand in for printf. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em \_\-args}]A parenthesis inclosed set of arguments to printf\end{description} \end{Desc} This macro is active iff the compiler symbol TASK\_\-DEBUG is defined, otherwise it is defined as a NOP \subsection{Typedef Documentation} \hypertarget{TASK_8h_a2}{ \index{TASK.h@{TASK.h}!TASK_attr@{TASK\_\-attr}} \index{TASK_attr@{TASK\_\-attr}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-attr]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{struct__TASK__attr}{TASK\_\-attr}}} \label{TASK_8h_a2} Typedef for struct {\em \hyperlink{struct__TASK__attr}{\_\-TASK\_\-attr}\/}. This data structure allows the caller to fine tune the task creation parameters in a semi-portable fashion. Not all fields are supported on all platforms.\hypertarget{TASK_8h_a7}{ \index{TASK.h@{TASK.h}!TASK_block_cb@{TASK\_\-block\_\-cb}} \index{TASK_block_cb@{TASK\_\-block\_\-cb}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-block\_\-cb]{\setlength{\rightskip}{0pt plus 5cm}int($\ast$ \hyperlink{TASK_8h_a7}{TASK\_\-block\_\-cb})(void $\ast$prm)}} \label{TASK_8h_a7} Callback routine of TASK\_\-block. \begin{Desc} \item[Returns:]status\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em A}]user parameter passed to the callback routine\end{description} \end{Desc} \hypertarget{TASK_8h_a5}{ \index{TASK.h@{TASK.h}!TASK_entry@{TASK\_\-entry}} \index{TASK_entry@{TASK\_\-entry}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-entry]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{TASK_8h_a5}{TASK\_\-entry}}} \label{TASK_8h_a5} The function signature of the task's entry point routine. This is the function signature of the task's entry point routine. It is as simple as one can make it, {\em i.e\/}. \footnotesize\begin{verbatim} void *exit_parameter = (*entry_point) (TASK_parameter parameter); \end{verbatim} \normalsize The {\em TASK\_\-parameter\/} is just a void $\ast$, but is typedef'd so that the code documents neatly.\hypertarget{TASK_8h_a4}{ \index{TASK.h@{TASK.h}!TASK_parameter@{TASK\_\-parameter}} \index{TASK_parameter@{TASK\_\-parameter}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-parameter]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{TASK_8h_a4}{TASK\_\-parameter}}} \label{TASK_8h_a4} The type of the parameter passed to the task's entry point routine. This type is just a void $\ast$, but is typedef'd so that the code documents neatly.\hypertarget{TASK_8h_a3}{ \index{TASK.h@{TASK.h}!TASK_priority_type@{TASK\_\-priority\_\-type}} \index{TASK_priority_type@{TASK\_\-priority\_\-type}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-priority\_\-type]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{TASK_8h_a3}{TASK\_\-priority\_\-type}}} \label{TASK_8h_a3} Typedef for enum {\em \_\-TASK\_\-priority\_\-type\/}. Indicates how a priority specification to TASK\_\-attr\_\-setpriority is interpretted. This can be either as an absolute or as a signed number relative to the another task's priority.\hypertarget{TASK_8h_a6}{ \index{TASK.h@{TASK.h}!TASK_tcb@{TASK\_\-tcb}} \index{TASK_tcb@{TASK\_\-tcb}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-tcb]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{struct__TASK__tcb}{TASK\_\-tcb}}} \label{TASK_8h_a6} TASK facility's definition of a Task Control Block. The user should never manipulate this data structure directly. It is provided only so the compiler can lay down storage. Direct manipulation will kill the portability of the code since the exact contents are platform dependent. \subsection{Enumeration Type Documentation} \hypertarget{TASK_8h_a37}{ \index{TASK.h@{TASK.h}!_TASK_priority_type@{\_\-TASK\_\-priority\_\-type}} \index{_TASK_priority_type@{\_\-TASK\_\-priority\_\-type}!TASK.h@{TASK.h}} \subsubsection[\_\-TASK\_\-priority\_\-type]{\setlength{\rightskip}{0pt plus 5cm}enum \hyperlink{TASK_8h_a37}{\_\-TASK\_\-priority\_\-type}}} \label{TASK_8h_a37} Indicates how a priority specification to TASK\_\-attr\_\-setpriority is interpretted. \begin{Desc} \item[Enumerator: ]\par \begin{description} \index{TASK_K_PRIORITY_TYPE_ABS@{TASK\_\-K\_\-PRIORITY\_\-TYPE\_\-ABS}!TASK.h@{TASK.h}}\index{TASK.h@{TASK.h}!TASK_K_PRIORITY_TYPE_ABS@{TASK\_\-K\_\-PRIORITY\_\-TYPE\_\-ABS}}\item[{\em \hypertarget{TASK_8h_a37a8}{ TASK\_\-K\_\-PRIORITY\_\-TYPE\_\-ABS} \label{TASK_8h_a37a8} }]Interpret priority as an absolute \index{TASK_K_PRIORITY_TYPE_REL@{TASK\_\-K\_\-PRIORITY\_\-TYPE\_\-REL}!TASK.h@{TASK.h}}\index{TASK.h@{TASK.h}!TASK_K_PRIORITY_TYPE_REL@{TASK\_\-K\_\-PRIORITY\_\-TYPE\_\-REL}}\item[{\em \hypertarget{TASK_8h_a37a9}{ TASK\_\-K\_\-PRIORITY\_\-TYPE\_\-REL} \label{TASK_8h_a37a9} }]Interpret priority relative to the current task's priority \end{description} \end{Desc} \subsection{Function Documentation} \hypertarget{TASK_8h_a12}{ \index{TASK.h@{TASK.h}!TASK_activate@{TASK\_\-activate}} \index{TASK_activate@{TASK\_\-activate}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-activate]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-activate (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb})}} \label{TASK_8h_a12} Activates a previously created task. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The task control block of the task to activate. \end{description} \end{Desc} \begin{Desc} \item[Returns:]Status\end{Desc} Activates a previously created task. This allows the user to cleanly separate the definition, ie filling in the TASK\_\-attr block, the task creation, using \hyperlink{TASK_8h_a13}{TASK\_\-create()}, and from the task activation.\hypertarget{TASK_8h_a10}{ \index{TASK.h@{TASK.h}!TASK_attr_init@{TASK\_\-attr\_\-init}} \index{TASK_attr_init@{TASK\_\-attr\_\-init}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-attr\_\-init]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-attr\_\-init (\hyperlink{struct__TASK__attr}{TASK\_\-attr} $\ast$ {\em attributes})}} \label{TASK_8h_a10} Provides a standard method of initializing the attributes block to a set of known values. These values may be platform dependent. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em attributes}]The attributes block to initialize \end{description} \end{Desc} \begin{Desc} \item[Returns:]Status.\end{Desc} \hypertarget{TASK_8h_a11}{ \index{TASK.h@{TASK.h}!TASK_attr_priority_set@{TASK\_\-attr\_\-priority\_\-set}} \index{TASK_attr_priority_set@{TASK\_\-attr\_\-priority\_\-set}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-attr\_\-priority\_\-set]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-attr\_\-priority\_\-set (\hyperlink{struct__TASK__attr}{TASK\_\-attr} $\ast$ {\em attributes}, int {\em priority})}} \label{TASK_8h_a11} Sets the priority field in the task attributes block to the the specified value. This can be either absolute or relative to the current task's priority. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em attributes}]The target attributes block \item[{\em priority}]A signed integer indicating the absolute or relative priority. \end{description} \end{Desc} \begin{Desc} \item[Returns:]The assigned priority level.\end{Desc} Absolute priorities numbers are always expressed in terms of the native system.\hypertarget{TASK_8h_a26}{ \index{TASK.h@{TASK.h}!TASK_block@{TASK\_\-block}} \index{TASK_block@{TASK\_\-block}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-block]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-block (\hyperlink{TASK_8h_8vx-xxx-xxx_a7}{TASK\_\-block\_\-handle} $\ast$ {\em tbh}, \hyperlink{TASK_8h_a7}{TASK\_\-block\_\-cb} {\em rtn}, void $\ast$ {\em prm})}} \label{TASK_8h_a26} Provides a simple way to turn an asynchronous routine into a synchronous routine. \begin{Desc} \item[Returns:]Status of the task blocking callback routine\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tbh}]Pointer to a location to hold the task blocking handle This is must be passed to TASK\_\-unblock to unblock the TASK upon completion of the routine.\item[{\em rtn}]The asynchronous callback routine to execute\item[{\em prm}]A parameter to be passed to the above routine.\end{description} \end{Desc} \begin{Desc} \item[Example]In this example an asynchronous routine, {\em read\_\-it\/}, is executed in a synchronous manner. The first code block illustrates the TASK\_\-block call.\end{Desc} \footnotesize\begin{verbatim} struct Synch { TASK_block_handle tbh; char buf[100]; void nbytes; SynchRtn synch_rtn; } synch; synch->synch_rtn = read_synch; status = TASK_block (&synch->tbh, read_it, &synch); \end{verbatim} \normalsize \begin{Desc} \item[]This illustrates the TASK\_\-unblock call\end{Desc} \footnotesize\begin{verbatim} int read_synch (Synch *synch) { return TASK_unblock (synch->tbh); } \end{verbatim} \normalsize ;\hypertarget{TASK_8h_a14}{ \index{TASK.h@{TASK.h}!TASK_convert@{TASK\_\-convert}} \index{TASK_convert@{TASK\_\-convert}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-convert]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-convert (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb}, const \hyperlink{struct__TASK__attr}{TASK\_\-attr} $\ast$ {\em attributes}, \hyperlink{TASK_8h_a5}{TASK\_\-entry} {\em entry\_\-point}, \hyperlink{TASK_8h_a4}{TASK\_\-parameter} {\em parameter})}} \label{TASK_8h_a14} Converts an existing Vx\-Works task to a TASK. \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The task control block to initialize \item[{\em attributes}]The task attributes block. This may be NULL, in which case the system defaults are used. \item[{\em entry\_\-point}]The task's new entry point address. If this is non-NULL this will act as a user callback routine with the flow of control being passed onto this routine with {\em parameter\/} being passed to this routine. If NULL, control will pass back to the caller. \item[{\em parameter}]A parameter passed transparently to the {\em entry\_\-point\/} routine.\end{description} \end{Desc} For consistency, the calling sequence is the same as {\bf \hyperlink{TASK_8h_a13}{TASK\_\-create()}}, however certain differences exist. The differences are mainly in the attributes block. The disposition of the attributes block is \begin{itemize} \item name : Ignored. This differs from the pthreads version where the name can be assigned at task conversion time.\item priority : If non-negative, the priority of the converted task will be changed to this value\item options : Ignored\item stack\_\-addr: Ignored\item stack\_\-size: Ignored.\end{itemize} \begin{Desc} \item[Usage]There are two typical uses of this routine, both allowing the caller to add TASK features, such as the Task Global Data Block, \end{Desc} \begin{Desc} \item[See also:]\hyperlink{TASK_8c_a4}{TASK\_\-pause} (), \hyperlink{TASK_8c_8vx-xxx-xxx_a15}{TASK\_\-resume} (), etc.\end{Desc} The first usage is in the main task (on host platforms) and in the root task (on Vx\-Work's platforms). In both cases the user finds himself in a task/thread not created by the TASK routines, but wishes to avail himself of their functionality. \footnotesize\begin{verbatim} nbytes = TASK_xtcb_sizeof (); // Get the size of a conversion block tcb = MBA_alloc (nbytes); // Allocate memory for it // Give control to TASK, it will just call (*myRoutine)(myParameter) // then return when that routine is down status = TASK_convert (tcb, NULL, myRoutine, myParameter); // Strip this task of TASK functionality status = TASK_revert (tcb); // Return the TASK resources MBA_free (tcb); // Free the memory for the tcb \end{verbatim} \normalsize The second usage is when doing informal coding in the shell. \footnotesize\begin{verbatim} nbytes = TASK_xtcb_sizeof (); // Get the size of a conversion block tcb = MBA_alloc (nbytes); // Allocate memory for it // Just create and initialize the tcb status = TASK_convert (tcb, NULL, NULL, NULL); ... lots of code // Strip this task of TASK functionality status = TASK_revert (tcb); // Return the TASK resources MBA_free (tcb); // Free the memory for the tcb \end{verbatim} \normalsize Naturally the above example (the one without the user callback routine can be used in the other case also, but, style-wise, usage of the calback is structurally cleaner. \begin{Desc} \item[Note:]For quick and dirty applications (like test programs and shell scripting), see\end{Desc} \begin{Desc} \item[See also:]\hyperlink{TASK_8h_a20}{TASK\_\-cvt()} and \hyperlink{TASK_8h_a21}{TASK\_\-rvt()}. \hyperlink{TASK_8c_a3}{TASK\_\-cvt} combines the sizing and memory allocation with \hyperlink{TASK_8h_a14}{TASK\_\-convert()}, while, at least currently \hyperlink{TASK_8h_a21}{TASK\_\-rvt()} returns the memory and calls \hyperlink{TASK_8h_a19}{TASK\_\-revert()}. The rule is always pair TASK\_\-convert/TASK\_\-revert or TASK\_\-cvt/TASK\_\-rvt\end{Desc} \hypertarget{TASK_8h_a13}{ \index{TASK.h@{TASK.h}!TASK_create@{TASK\_\-create}} \index{TASK_create@{TASK\_\-create}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-create]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-create (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb}, const \hyperlink{struct__TASK__attr}{TASK\_\-attr} $\ast$ {\em attributes}, \hyperlink{TASK_8h_a5}{TASK\_\-entry} {\em entry\_\-point}, \hyperlink{TASK_8h_a4}{TASK\_\-parameter} {\em parameter})}} \label{TASK_8h_a13} Creates, but does not activate a task. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The task control block of the task to create \item[{\em attributes}]A collection of attributes used to exactly specify the task. This parameter may be specified as NULL. In this case, a platform dependent set of attributes is assigned. \item[{\em entry\_\-point}]The address of the entry point of the newly created task. See TASK\_\-entry for the call signature. \item[{\em parameter}]A parameter which is passed transparently to the newly created task's entry point.\end{description} \end{Desc} Creates, but does activate a task. This allows the user to cleanly separate the definition, ie filling in the TASK\_\-attr block, the task creation, using \hyperlink{TASK_8h_a13}{TASK\_\-create()}, and from the task activation.\hypertarget{TASK_8h_a20}{ \index{TASK.h@{TASK.h}!TASK_cvt@{TASK\_\-cvt}} \index{TASK_cvt@{TASK\_\-cvt}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-cvt]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ TASK\_\-cvt (void)}} \label{TASK_8h_a20} Converts an existing VXWORKs task or POSIX thread to TASK object. \begin{Desc} \item[Returns:]The TASK's control block\end{Desc} \begin{Desc} \item[Warning:]This is made for quick and dirty shell and test programming. It should {\bf never} be used in production code. Use\end{Desc} \begin{Desc} \item[See also:]\hyperlink{TASK_8c_8vx-xxx-xxx_a10}{TASK\_\-convert} () and \hyperlink{TASK_8c_8vx-xxx-xxx_a11}{TASK\_\-revert} ().\end{Desc} \hypertarget{TASK_8h_a16}{ \index{TASK.h@{TASK.h}!TASK_destroy@{TASK\_\-destroy}} \index{TASK_destroy@{TASK\_\-destroy}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-destroy]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-destroy (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb})}} \label{TASK_8h_a16} Destroys, ie deletes, a previously created task. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The task control block of the task to destroy.\end{description} \end{Desc} Destroys, ie deletes, previously created task. This routine will return any resources gathered by the \hyperlink{TASK_8h_a13}{TASK\_\-create()} utility, but will not free any user resources, such as the stack, associated with the task.\hypertarget{TASK_8h_a17}{ \index{TASK.h@{TASK.h}!TASK_exit@{TASK\_\-exit}} \index{TASK_exit@{TASK\_\-exit}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-exit]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-exit (void $\ast$ {\em exit\_\-value})}} \label{TASK_8h_a17} Causes the calling task to delete itself and allows notification to another task, via {\em \hyperlink{TASK_8h_a18}{TASK\_\-join()}\/} that the calling task has deleted itself. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em exit\_\-value}]An arbitrary 32-bit value passed to {\em \hyperlink{TASK_8h_a18}{TASK\_\-join()}\/}. \end{description} \end{Desc} \begin{Desc} \item[Returns:]Status, 0 = SUCCESS\end{Desc} Works in tandem with TASK\_\-join to allow synchonization when a task exits. The exiting task can supply a status value, which the task calling TASK\_\-join will receive when the task actually exits. Note that the status value is a void $\ast$, so a pointer to any piece of information can be supplied with the usual caveat that the memory the pointer is aimed at remains valid until read.\hypertarget{TASK_8h_a18}{ \index{TASK.h@{TASK.h}!TASK_join@{TASK\_\-join}} \index{TASK_join@{TASK\_\-join}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-join]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-join (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb}, void $\ast$$\ast$ {\em exit\_\-value})}} \label{TASK_8h_a18} Blocks the calling task until the specified task completes. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The task to join \item[{\em exit\_\-value}]Location to receive the exiting task's completion value. \end{description} \end{Desc} \begin{Desc} \item[Returns:]Status of the TASK\_\-join operation.\end{Desc} This routine is used in conjunction with TASK\_\-exit to provide a synchronized rundown. \hyperlink{TASK_8h_a18}{TASK\_\-join()} blocks the calling task until the specified task completes. If status is non-NULL it points to a location that will be filled in with the exiting task's completion value.\hypertarget{TASK_8h_a32}{ \index{TASK.h@{TASK.h}!TASK_name@{TASK\_\-name}} \index{TASK_name@{TASK\_\-name}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-name]{\setlength{\rightskip}{0pt plus 5cm}const char $\ast$ TASK\_\-name (const \hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb})}} \label{TASK_8h_a32} Returns a pointer to the task's name. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The tcb of the task \end{description} \end{Desc} \begin{Desc} \item[Return values:] \begin{description} \item[{\em ISR$>$,of}]tcb is specified as NULL, but in interrupt context \item[{\em UND$>$,if}]tcb is non-NULL and not in interrupt context but no name is associated with the task. \end{description} \end{Desc} \begin{Desc} \item[Returns:]The task name, if neither of the above conditions are true.\end{Desc} The name of the task is maintain purely for informational and debugging reasons. The lifetime of the pointer is guaranteed only \begin{itemize} \item On Vx\-Works, the lifetime of the underlying Vx\-Works task\item On host platforms, the lifetime of the TASK tcb.\end{itemize} \begin{Desc} \item[Explanation]On Vx\-Works: The name being used is the name given to the Vx\-Works task creation routines (task\-Spawn and task\-Init). The storage for this name is carved out of the first few locations of the stack associated with the task. Ergo, when the task is deleted, the name goes kaput.\end{Desc} On host platforms: POSIX has no facility to associate a name to a task. Therefore, the name under POSIX is a figment of TASK's imagination. The name is stored with the TASK\_\-tcb handle. Once the handle vanishes, the name does also. \begin{Desc} \item[The Task Name]TASK\_\-name {\bf always} returns a non-NULL string. In most cases the string will be the name associated with the task. However, in some cases, no name can be associated with the request\end{Desc} \begin{itemize} \item Case 1, the {\em tcb\/} is specified as NULL. This means get the name of the current task. However, if the current context is the interrupt context, then there is no current task. In this case a default string of \char`\"{}ISR$>$\char`\"{} is returned. Since POSIX does not have an interrupt context, this string will not be returned on POSIX platforms\item Case 2, the {\em tcb\/} is specified or the context is task context, but no name can be associated with the task. In this case, the string \char`\"{}UND$>$\char`\"{} is returned. Since, in on Vx\-Works platforms, all tasks are assigned a name, this string will not be returned on Vx\-Works platforms. On POSIX platforms, this string will be returned if the task was not created or converted by TASK.\end{itemize} \hypertarget{TASK_8h_a22}{ \index{TASK.h@{TASK.h}!TASK_pause@{TASK\_\-pause}} \index{TASK_pause@{TASK\_\-pause}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-pause]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-pause (unsigned int {\em nsecs})}} \label{TASK_8h_a22} Causes the calling task to wait (pause) for the specified number of nanoseconds. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em nsecs}]The number of nanoseconds to pause. \end{description} \end{Desc} \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Warning:]This call should only be used for debugging purposes. The range of the pause is approximately 0 to 4 seconds.\end{Desc} \hypertarget{TASK_8h_a28}{ \index{TASK.h@{TASK.h}!TASK_priority_get@{TASK\_\-priority\_\-get}} \index{TASK_priority_get@{TASK\_\-priority\_\-get}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-priority\_\-get]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-priority\_\-get (const \hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb})}} \label{TASK_8h_a28} Gets the current priority of the specified task. The priority is returned expressed in the native tasking model's scheme. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The task control block of which task to query. If specified as NULL, the current task's priority. \end{description} \end{Desc} \begin{Desc} \item[Returns:]The priority level of the specified task expressed in the native tasking model's scheme.\end{Desc} \hypertarget{TASK_8h_a33}{ \index{TASK.h@{TASK.h}!TASK_priority_number_boost@{TASK\_\-priority\_\-number\_\-boost}} \index{TASK_priority_number_boost@{TASK\_\-priority\_\-number\_\-boost}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-priority\_\-number\_\-boost]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-priority\_\-number\_\-boost (int {\em priority}, int {\em boost})}} \label{TASK_8h_a33} Boosts the {\em priority\/} number by the {\em boost\/}. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em priority}]The priority number to boost \item[{\em boost}]The amount to boost the {\em priority\/} number\end{description} \end{Desc} \begin{Desc} \item[Returns:]The boosted priority. This will be a number between the minimum,\end{Desc} \begin{Desc} \item[See also:]TASK\_\-K\_\-PRIORITY\_\-MIN, and maximum, TASK\_\-K\_\-PRIORITY\_\-MAX allowed priority numbers.\end{Desc} The specified {\em priority\/} number is boosted by {\em boost\/}. A task assigned a higher priority will run before a task with a lower priority. On some platforms were the highest priority tasks run with a lower priority number, the actual priority number will, in fact, decrease. The boost can be specified as a positive or negative number. Positive boosts will always result in a priority number that raises a task's absolute priority. Negative numbers will always result in a priority number that lowers a task's priority number. In all cases the routine will limit the resulting priority between the minimum,\begin{Desc} \item[See also:]TASK\_\-K\_\-PRIORITY\_\-MIN and TASK\_\-K\_\-PRIORITY\_\-MAX numbers.\end{Desc} \hypertarget{TASK_8h_a34}{ \index{TASK.h@{TASK.h}!TASK_priority_number_compute@{TASK\_\-priority\_\-number\_\-compute}} \index{TASK_priority_number_compute@{TASK\_\-priority\_\-number\_\-compute}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-priority\_\-number\_\-compute]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-priority\_\-number\_\-compute (int {\em priority}, \hyperlink{TASK_8h_a3}{TASK\_\-priority\_\-type} {\em type}, const \hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb})}} \label{TASK_8h_a34} Computes a priority number, either as an absolute or based on the priority of another task. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em priority}]If the type is specified as an absolute priority number, then this number is used as is. If the type is relative, then it is a signed number. Positive numbers are interpretted as raising the priority level (even though the value of the priority number itself may be decremented) whereas negative numbers are interpreted as lowering the priority level (even though the value of the priority number itself may be incremented.)\item[{\em type}]The type or manner in which to set the priority. This can be either relative or absolulte.\item[{\em tcb}]The task control block of a reference task. This is used iff type == TASK\_\-K\_\-PRIORITY\_\-TYPE\_\-REL. If specified as NULL, then the priority of the calling task is used.\end{description} \end{Desc} \begin{Desc} \item[Returns:]The priority number expressed in the native tasking model's scheme.\end{Desc} Simple utility routine to compute a priority potentially based on another task. The priority level is returned expressed in the native tasking model's scheme. If the type is an absolute priority, the priority number returned is potentially changed to keep it within bounds.\hypertarget{TASK_8h_a35}{ \index{TASK.h@{TASK.h}!TASK_priority_number_limit@{TASK\_\-priority\_\-number\_\-limit}} \index{TASK_priority_number_limit@{TASK\_\-priority\_\-number\_\-limit}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-priority\_\-number\_\-limit]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-priority\_\-number\_\-limit (int {\em priority})}} \label{TASK_8h_a35} Limits the priority number to fit within the specified bounds. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em priority}]The priority number to limit. \end{description} \end{Desc} \begin{Desc} \item[Returns:]The limit priority number\end{Desc} \hypertarget{TASK_8h_a36}{ \index{TASK.h@{TASK.h}!TASK_priority_set@{TASK\_\-priority\_\-set}} \index{TASK_priority_set@{TASK\_\-priority\_\-set}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-priority\_\-set]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-priority\_\-set (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb}, int {\em priority})}} \label{TASK_8h_a36} Sets priority of the specified task to the specified value. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The Task Control Block of the task to change the priority. If NULL, then the current task. \item[{\em priority}]The priority to set the task to. \end{description} \end{Desc} \begin{Desc} \item[Returns:]Status\end{Desc} \hypertarget{TASK_8h_a23}{ \index{TASK.h@{TASK.h}!TASK_resume@{TASK\_\-resume}} \index{TASK_resume@{TASK\_\-resume}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-resume]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-resume (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb})}} \label{TASK_8h_a23} Resumes a previously suspended task. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The Task Control Block of the task to resume \end{description} \end{Desc} \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Warning:]This call should only be used for debugging purposes.\end{Desc} \begin{Desc} \item[Note:]TASK\_\-resumes are additive, Thus calling 5 TASK\_\-resumes before calling any TASK\_\-suspends means it will take 6 TASK\_\-suspends before the task actually suspended. Because of this curious feature, calling TASK\_\-resume with a TCB that resolves to the calling task actually makes some sense.\end{Desc} \hypertarget{TASK_8h_a19}{ \index{TASK.h@{TASK.h}!TASK_revert@{TASK\_\-revert}} \index{TASK_revert@{TASK\_\-revert}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-revert]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-revert (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb})}} \label{TASK_8h_a19} Strips a task/thread of its TASK functionality. \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The Task Control Block. This may be NULL, in which case the current task is reverted.\end{description} \end{Desc} Reverts a converted task to a native task. It does this by returning the resources gathered by \hyperlink{TASK_8h_a13}{TASK\_\-create()}, \hyperlink{TASK_8h_a15}{TASK\_\-spawn()} or \hyperlink{TASK_8h_a14}{TASK\_\-convert()}. Although this call can be used with \hyperlink{TASK_8h_a13}{TASK\_\-create()} and \hyperlink{TASK_8h_a15}{TASK\_\-spawn()}, it is most usually called after \hyperlink{TASK_8h_a14}{TASK\_\-convert()}.\hypertarget{TASK_8h_a21}{ \index{TASK.h@{TASK.h}!TASK_rvt@{TASK\_\-rvt}} \index{TASK_rvt@{TASK\_\-rvt}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-rvt]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-rvt (void)}} \label{TASK_8h_a21} Reverts the current task back to its native self by stripping it of its TASK functionality. \begin{Desc} \item[Warning:]This is made for quick and dirty shell and test programming. It should {\bf never} be used in production code. Use\end{Desc} \begin{Desc} \item[See also:]\hyperlink{TASK_8c_8vx-xxx-xxx_a10}{TASK\_\-convert} () and \hyperlink{TASK_8c_8vx-xxx-xxx_a11}{TASK\_\-revert} (). This function should be used with its partner, \hyperlink{TASK_8h_a20}{TASK\_\-cvt()}.\end{Desc} \hypertarget{TASK_8h_a31}{ \index{TASK.h@{TASK.h}!TASK_self@{TASK\_\-self}} \index{TASK_self@{TASK\_\-self}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-self]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ TASK\_\-self (void)}} \label{TASK_8h_a31} Returns the tcb of the calling task. \begin{Desc} \item[Returns:]The tcb of the calling task\end{Desc} \hypertarget{TASK_8h_a15}{ \index{TASK.h@{TASK.h}!TASK_spawn@{TASK\_\-spawn}} \index{TASK_spawn@{TASK\_\-spawn}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-spawn]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-spawn (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb}, const \hyperlink{struct__TASK__attr}{TASK\_\-attr} $\ast$ {\em attributes}, \hyperlink{TASK_8h_a5}{TASK\_\-entry} {\em entry\_\-point}, \hyperlink{TASK_8h_a4}{TASK\_\-parameter} {\em parameter})}} \label{TASK_8h_a15} Convenience routine to both create and activate a task. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The task control block of the task to spawn \item[{\em attributes}]A collection of attributes used to exactly specify the task. This parameter may be specified as NULL. In this case, a platform dependent set of attributes is assigned. \item[{\em entry\_\-point}]The address of the entry point of the newly created task. See TASK\_\-entry for the call signature. \item[{\em parameter}]A parameter which is passed transparently to the newly created task's entry point.\end{description} \end{Desc} Convenience routine to both create and activate a task.\hypertarget{TASK_8h_a24}{ \index{TASK.h@{TASK.h}!TASK_suspend@{TASK\_\-suspend}} \index{TASK_suspend@{TASK\_\-suspend}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-suspend]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-suspend (\hyperlink{struct__TASK__tcb}{TASK\_\-tcb} $\ast$ {\em tcb})}} \label{TASK_8h_a24} Suspends a task. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tcb}]The Task Control Block of the task to suspend \end{description} \end{Desc} \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Warning:]This call should only be used for debugging purposes. The POSIX provides no mechanism for suspending any task but the calling task. Therefore the POSIX implementation will BUG\_\-check if the tcb is not that of the calling task. This is not a diseaster and is in keeping with the spirit that this is a debugging routine. The warning is using this routine with a non-NULL tcb that is not the calling task's tcb is non-portable and should be avoided. The calling convention was kept to match the Vx\-Works convention.\end{Desc} Note that it is completely portable to call TASK\_\-resume from any task. Here the reader might ask exactly the opposite question; does it make any sense to call TASK\_\-resume with a tcb that resolves to the calling task's tcb. The answer is yes because TASK\_\-resumes are additive, i.e. if TASK\_\-resume is called 5 times before an TASK\_\-suspend, it will take 6 TASK\_\-suspends before the task actually suspends.\hypertarget{TASK_8h_a29}{ \index{TASK.h@{TASK.h}!TASK_tcb_sizeof@{TASK\_\-tcb\_\-sizeof}} \index{TASK_tcb_sizeof@{TASK\_\-tcb\_\-sizeof}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-tcb\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}TASK\_\-tcb\_\-sizeof (void)}} \label{TASK_8h_a29} Returns the size, in bytes, of a TCB to be used when creating or spawning a TASK. \begin{Desc} \item[Returns:]The size, in bytes, of a TCB\end{Desc} Use this size to allocate memory for a TASK\_\-tcb to use when calling {\em \hyperlink{TASK_8h_a13}{TASK\_\-create()}\/} or {\em \hyperlink{TASK_8h_a15}{TASK\_\-spawn()}\/}.\hypertarget{TASK_8h_a27}{ \index{TASK.h@{TASK.h}!TASK_unblock@{TASK\_\-unblock}} \index{TASK_unblock@{TASK\_\-unblock}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-unblock]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-unblock (\hyperlink{TASK_8h_8vx-xxx-xxx_a7}{TASK\_\-block\_\-handle} {\em tbh})}} \label{TASK_8h_a27} Unblocks a task blocked on a call to TASK\_\-block. \begin{Desc} \item[Returns:]Status \end{Desc} \begin{Desc} \item[See also:]\hyperlink{TASK_8c_8vx-xxx-xxx_a22}{TASK\_\-block}\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tbh}]The task blocking handle\end{description} \end{Desc} \hypertarget{TASK_8h_a25}{ \index{TASK.h@{TASK.h}!TASK_wait@{TASK\_\-wait}} \index{TASK_wait@{TASK\_\-wait}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-wait]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-wait (const \hyperlink{TOV_8h_8vx-xxx-xxx_a8}{TOV} {\em tov})}} \label{TASK_8h_a25} Causes the calling task to wait (pause) until the specified timeout is reached. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tov}]The timeout value to wait until \end{description} \end{Desc} \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Warning:]This call should only be used for debugging purposes. It is just a convenience routine which wrappers \hyperlink{TASK_8h_a25}{TASK\_\-wait()} with a timeout value calculation.\end{Desc} \hypertarget{TASK_8h_a30}{ \index{TASK.h@{TASK.h}!TASK_xtcb_sizeof@{TASK\_\-xtcb\_\-sizeof}} \index{TASK_xtcb_sizeof@{TASK\_\-xtcb\_\-sizeof}!TASK.h@{TASK.h}} \subsubsection[TASK\_\-xtcb\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}TASK\_\-xtcb\_\-sizeof (void)}} \label{TASK_8h_a30} Returns the size, in bytes, of a TCB to be used when converting an existing (platform native task) to a TASK type task. \begin{Desc} \item[Returns:]The size, in bytes, of a TCB\end{Desc} Use this size to allocate memory for a TASK\_\-tcb to use when calling {\em \hyperlink{TASK_8h_a14}{TASK\_\-convert()}\/}.