TASK.h File Reference

Task/Thread facility, a portable interface between VxWorks and POSIX implementations, callable version. More...

#include <PBS/TOV.h>

Classes

struct _TASK_attr

Encapsulates the more esoteric options. More...

Defines

#define TASK_PRINTF(_args)

Debugging macro acting as a stand in for printf.

#define TASK_K_NAME_MAX   16

The maximum size of a task's name, including the terminating NUL character.

Typedefs

typedef struct _TASK_attr TASK_attr

Typedef for struct _TASK_attr.

typedef enum _TASK_priority_type TASK_priority_type

Typedef for enum _TASK_priority_type.

typedef void * TASK_parameter

The type of the parameter passed to the task's entry point routine.

typedef void *(* TASK_entry )(TASK_parameter parameter)

The function signature of the task's entry point routine.

typedef struct _TASK_tcb TASK_tcb

TASK facility's definition of a Task Control Block.

typedef int TASK_int

typedef int(* TASK_block_cb )(void *prm)

Callback routine of TASK_block.

Enumerations

enum _TASK_priority_type {
  TASK_K_PRIORITY_TYPE_ABS = 0,
  TASK_K_PRIORITY_TYPE_REL = 1
}

Indicates how a priority specification to TASK_attr_setpriority is interpretted. More...

Functions

int TASK_attr_init (TASK_attr *attributes)

Provides a standard method of initializing the attributes block to a set of known values. These values may be platform dependent.

int TASK_attr_priority_set (TASK_attr *attributes, int priority)

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.

int TASK_activate (TASK_tcb *tcb)

Activates a previously created task.

int TASK_create (TASK_tcb *tcb, const TASK_attr *attributes, TASK_entry entry_point, TASK_parameter parameter)

Creates, but does not activate a task.

TASK_int TASK_convert (TASK_tcb *tcb, const TASK_attr *attributes, TASK_entry entry_point, TASK_parameter parameter)

Converts an existing VxWorks task to a TASK.

int TASK_spawn (TASK_tcb *tcb, const TASK_attr *attributes, TASK_entry entry_point, TASK_parameter parameter)

Convenience routine to both create and activate a task.

int TASK_destroy (TASK_tcb *tcb)

Destroys, ie deletes, a previously created task.

void TASK_exit (void *status)

Causes the calling task to delete itself and allows notification to another task, via TASK_join() that the calling task has deleted itself.

int TASK_join (TASK_tcb *tcb, void **status)

Blocks the calling task until the specified task completes.

int TASK_revert (TASK_tcb *tcb)

Strips a task/thread of its TASK functionality.

TASK_tcb * TASK_cvt (void)

Converts an existing VXWORKs task or POSIX thread to TASK object.

int TASK_rvt (void)

Reverts the current task back to its native self by stripping it of its TASK functionality.

int TASK_pause (unsigned int nsecs)

Causes the calling task to wait (pause) for the specified number of nanoseconds.

int TASK_resume (TASK_tcb *tcb)

Resumes a previously suspended task.

int TASK_suspend (TASK_tcb *tcb)

Suspends a task.

int TASK_wait (const TOV tov)

Causes the calling task to wait (pause) until the specified timeout is reached.

int TASK_block (TASK_block_handle *tbh, TASK_block_cb rtn, void *prm)

Provides a simple way to turn an asynchronous routine into a synchronous routine.

int TASK_unblock (TASK_block_handle tbh)

Unblocks a task blocked on a call to TASK_block.

int TASK_priority_get (const TASK_tcb *tcb)

Gets the current priority of the specified task. The priority is returned expressed in the native tasking model's scheme.

int TASK_tcb_sizeof (void)

Returns the size, in bytes, of a TCB to be used when creating or spawning a TASK.

int TASK_xtcb_sizeof (void)

Returns the size, in bytes, of a TCB to be used when converting an existing (platform native task) to a TASK type task.

TASK_tcb * TASK_self (void)

Returns the tcb of the calling task.

const char * TASK_name (const TASK_tcb *tcb)

Returns a pointer to the task's name.

int TASK_priority_number_boost (int priority, int boost)

Boosts the priority number by the boost.

int TASK_priority_number_compute (int priority, TASK_priority_type type, const TASK_tcb *tcb)

Computes a priority number, either as an absolute or based on the priority of another task.

int TASK_priority_number_limit (int priority)

Limits the priority number to fit within the specified bounds.

int TASK_priority_set (TASK_tcb *tcb, int priority)

Sets priority of the specified task to the specified value.

Detailed Description

Task/Thread facility, a portable interface between VxWorks and POSIX implementations, callable version.

Author:: JJRussell - russell@slac.stanford.edu


   CVS $Id: TASK.h,v 1.7 2011/03/24 23:05:44 apw Exp $

SYNOPSIS: These routines attempt to make TASK/THREAD manipulation portable across VxWorks 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.

PRIORITIES: The VxWorks and POSIX priorities are, unfortunately very different. The VxWorks priorities run from the highest (0) to the lowest (255). POSIX priorities run from the lowest (1) to the highest (99).

One possibly portable scheme would map the two priorities into a common set. For example, accept the POSIX priorities and map the VxWorks 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 VxWorks set to the full range of the POSIX set. This mapping scheme could cause two different VxWorks 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 VxWorks set (say 0-98) to the POSIX range. This is better but suffers from another problem. Some VxWorks 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 VxWork's range could impair this ability.

Another possibility is to map the POSIX set to the VxWorks 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 VxWorks 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 VxWorks 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 VxWorks implementation RAISING the priority results in lowering the task's priority number. (God, this is confusing.)

Two sets of limits are given

                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

The first set is useful for limit checking, i.e. making sure a given priority is acceptable on that platform. The second set allows one to implement a relative mapping scheme.

STACKS: The POSIX version supports only specifying a stack size. In both the VxWorks and POSIX cases TASK_K_STACK_SIZE_MIN provides a symbol for the minimum stack size. The VxWorks version supports stack allocation. It is up to the user to figure out how to make this portable. Sorry....

Define Documentation

#define TASK_K_NAME_MAX 16

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.

#define TASK_PRINTF ( _args )

Debugging macro acting as a stand in for printf.

Parameters:

_args

A parenthesis inclosed set of arguments to printf

This macro is active iff the compiler symbol TASK_DEBUG is defined, otherwise it is defined as a NOP

Referenced by TASK_priority_get().

Typedef Documentation

TASK_attr

Typedef for struct _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.

int(* TASK_block_cb)(void *prm)

Callback routine of TASK_block.

Returns:: status

Parameters:

A

user parameter passed to the callback routine

TASK_entry

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, i.e.

        void *exit_parameter = (*entry_point) (TASK_parameter parameter);

The TASK_parameter is just a void *, but is typedef'd so that the code documents neatly.

TASK_parameter

The type of the parameter passed to the task's entry point routine.

This type is just a void *, but is typedef'd so that the code documents neatly.

TASK_priority_type

Typedef for enum _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.

TASK_tcb

TASK facility's definition of a Task Control Block.

Typedef for struct _TASK_tcb.

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.

The user should never directly manipulate this structure. It is defined here only so that the compiler can set aside memory when one is declared.

Warning:: This structure must begin with the POSIX tcb at the top, followed by the TASK common stuff. The TASK.ih.px-xxx-xxx assume this.

Enumeration Type Documentation

enum _TASK_priority_type

Indicates how a priority specification to TASK_attr_setpriority is interpretted.

Enumerator:

TASK_K_PRIORITY_TYPE_ABS	Interpret priority as an absolute
TASK_K_PRIORITY_TYPE_REL	Interpret priority relative to the current task's priority

Function Documentation

int TASK_activate ( TASK_tcb * tcb )

Activates a previously created task.

Parameters:

tcb

The task control block of the task to activate.

Returns:: Status

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 TASK_create(), and from the task activation.

References _TASK_wcb::activated, BUG_check(), _TASK_wcb::cond, _TASK_wcb::mutex, and _TASK_tcb::wcb.

int TASK_attr_init ( TASK_attr * attributes )

Provides a standard method of initializing the attributes block to a set of known values. These values may be platform dependent.

Parameters:

attributes

The attributes block to initialize

Returns:: Status.

References _TASK_attr::name, _TASK_attr::options, _TASK_attr::priority, _TASK_attr::stack_addr, and _TASK_attr::stack_size.

Referenced by wut_sys_connect().

int TASK_attr_priority_set	(	TASK_attr *	attributes,
		int	priority
	)

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.

Parameters:

	attributes	The target attributes block
	priority	A signed integer indicating the absolute or relative priority.

Returns:: The assigned priority level.

Absolute priorities numbers are always expressed in terms of the native system.

References _TASK_attr::priority, and TASK__priority_number_limit().

Referenced by wut_sys_connect().

int TASK_block	(	TASK_block_handle *	tbh,
		TASK_block_cb	rtn,
		void *	prm
	)

Provides a simple way to turn an asynchronous routine into a synchronous routine.

Returns:: Status of the task blocking callback routine

Parameters:

	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.
	rtn	The asynchronous callback routine to execute
	prm	A parameter to be passed to the above routine.

Example: In this example an asynchronous routine, read_it, is executed in a synchronous manner. The first code block illustrates the TASK_block call.

      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);

: This illustrates the TASK_unblock call

        int read_synch (Synch *synch)
        {
            return TASK_unblock (synch->tbh);
        }

;

TASK_int TASK_convert	(	TASK_tcb *	tcb,
		const TASK_attr *	attributes,
		TASK_entry	entry_point,
		TASK_parameter	parameter
	)

Converts an existing VxWorks task to a TASK.

Returns:: Status or whatever entry_point returns (cast to an int)

Parameters:

	tcb	The task control block to initialize
	attributes	The task attributes block. This may be NULL, in which case the system defaults are used.
	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 parameter being passed to this routine. If NULL, control will pass back to the caller.
	parameter	A parameter passed transparently to the entry_point routine.

For consistency, the calling sequence is the same as TASK_create(), however certain differences exist. The differences are mainly in the attributes block. The disposition of the attributes block is

name : Ignored. This differs from the pthreads version where the name can be assigned at task conversion time.
priority : If non-negative, the priority of the converted task will be changed to this value
options : Ignored
stack_addr: Ignored
stack_size: Ignored.

Usage: There are two typical uses of this routine, both allowing the caller to add TASK features, such as the Task Global Data Block,

See also:: TASK_pause (),
TASK_resume (), etc.

The first usage is in the main task (on host platforms) and in the root task (on VxWork'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.

     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

The second usage is when doing informal coding in the shell.

     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

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.

Note:: For quick and dirty applications (like test programs and shell scripting), see

See also:: TASK_cvt() and
TASK_rvt(). TASK_cvt combines the sizing and memory allocation with TASK_convert(), while, at least currently TASK_rvt() returns the memory and calls TASK_revert(). The rule is always pair TASK_convert/TASK_revert or TASK_cvt/TASK_rvt

References _TASK_tcb::entry_point, _TASK_attr::name, _TASK_tcb::ncb, _TASK_tcb::parameter, _TASK_tcb::pcb, _TASK_attr::priority, TASK_priority_set(), _TASK_tcb::tid, and _TASK_tcb::wcb.

Referenced by TASK_cvt().

int TASK_create	(	TASK_tcb *	tcb,
		const TASK_attr *	attributes,
		TASK_entry	entry_point,
		TASK_parameter	parameter
	)

Creates, but does not activate a task.

Parameters:

	tcb	The task control block of the task to create
	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.
	entry_point	The address of the entry point of the newly created task. See TASK_entry for the call signature.
	parameter	A parameter which is passed transparently to the newly created task's entry point.

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 TASK_create(), and from the task activation.

TASK_tcb * TASK_cvt ( void )

Converts an existing VXWORKs task or POSIX thread to TASK object.

Returns:: The TASK's control block

Warning:: This is made for quick and dirty shell and test programming. It should never be used in production code. Use

See also:: TASK_convert () and
TASK_revert ().

References MBA_alloc(), MBA_free(), TASK_convert(), and TASK_xtcb_sizeof().

int TASK_destroy ( TASK_tcb * tcb )

Destroys, ie deletes, a previously created task.

Parameters:

tcb

The task control block of the task to destroy.

Destroys, ie deletes, previously created task. This routine will return any resources gathered by the TASK_create() utility, but will not free any user resources, such as the stack, associated with the task.

References TASK_revert(), and _TASK_tcb::tid.

int TASK_exit ( void * exit_value )

Causes the calling task to delete itself and allows notification to another task, via TASK_join() that the calling task has deleted itself.

Parameters:

exit_value

An arbitrary 32-bit value passed to TASK_join().

Returns:: Status, 0 = SUCCESS

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 *, 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.

References TASK_revert().

Referenced by wut_sys_kill().

int TASK_join	(	TASK_tcb *	tcb,
		void **	exit_value
	)

Blocks the calling task until the specified task completes.

Parameters:

	tcb	The task to join
	exit_value	Location to receive the exiting task's completion value.

Returns:: Status of the TASK_join operation.

This routine is used in conjunction with TASK_exit to provide a synchronized rundown. 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.

References _TASK_tcb::tid.

Referenced by FORK_join(), and wut_sys_shutdown().

const char * TASK_name ( const TASK_tcb * tcb )

Returns a pointer to the task's name.

Parameters:

tcb

The tcb of the task

Return values:

	ISR>,of	tcb is specified as NULL, but in interrupt context
	UND>,if	tcb is non-NULL and not in interrupt context but no name is associated with the task.

Returns:: The task name, if neither of the above conditions are true.

The name of the task is maintain purely for informational and debugging reasons. The lifetime of the pointer is guaranteed only

On VxWorks, the lifetime of the underlying VxWorks task
On host platforms, the lifetime of the TASK tcb.

Explanation: On VxWorks: The name being used is the name given to the VxWorks task creation routines (taskSpawn and taskInit). 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.

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.

The Task Name: TASK_name 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

Case 1, the 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 "ISR>" is returned. Since POSIX does not have an interrupt context, this string will not be returned on POSIX platforms
Case 2, the tcb is specified or the context is task context, but no name can be associated with the task. In this case, the string "UND>" is returned. Since, in on VxWorks platforms, all tasks are assigned a name, this string will not be returned on VxWorks platforms. On POSIX platforms, this string will be returned if the task was not created or converted by TASK.

References _TASK_ncb::name, _TASK_tcb::ncb, and TASK_self().

int TASK_pause ( unsigned int nsecs )

Causes the calling task to wait (pause) for the specified number of nanoseconds.

Parameters:

nsecs

The number of nanoseconds to pause.

Returns:: Status

Warning:: This call should only be used for debugging purposes. The range of the pause is approximately 0 to 4 seconds.

References TASK_wait(), and TOV_from_nsecs().

int TASK_priority_get ( const TASK_tcb * tcb )

Gets the current priority of the specified task. The priority is returned expressed in the native tasking model's scheme.

Parameters:

tcb

The task control block of which task to query. If specified as NULL, the current task's priority.

Returns:: The priority level of the specified task expressed in the native tasking model's scheme.

References TASK_PRINTF, and _TASK_tcb::tid.

Referenced by TASK_priority_number_compute().

int TASK_priority_number_boost	(	int	priority,
		int	boost
	)

Boosts the priority number by the boost.

Parameters:

	priority	The priority number to boost
	boost	The amount to boost the priority number

Returns:: The boosted priority. This will be a number between the minimum,

See also:: TASK_K_PRIORITY_MIN, and maximum,
TASK_K_PRIORITY_MAX allowed priority numbers.

The specified priority number is boosted by 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,

See also:: TASK_K_PRIORITY_MIN and
TASK_K_PRIORITY_MAX numbers.

int TASK_priority_number_compute	(	int	priority,
		TASK_priority_type	type,
		const TASK_tcb *	tcb
	)

Computes a priority number, either as an absolute or based on the priority of another task.

Parameters:

	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.)
	type	The type or manner in which to set the priority. This can be either relative or absolulte.
	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.

Returns:: The priority number expressed in the native tasking model's scheme.

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.

References TASK__priority_number_boost(), TASK__priority_number_limit(), TASK_K_PRIORITY_TYPE_REL, and TASK_priority_get().

int TASK_priority_number_limit ( int priority )

Limits the priority number to fit within the specified bounds.

Parameters:

priority

The priority number to limit.

Returns:: The limit priority number

int TASK_priority_set	(	TASK_tcb *	tcb,
		int	priority
	)

Sets priority of the specified task to the specified value.

Parameters:

	tcb	The Task Control Block of the task to change the priority. If NULL, then the current task.
	priority	The priority to set the task to.

Returns:: Status

References _TASK_tcb::tid.

Referenced by TASK_convert().

int TASK_resume ( TASK_tcb * tcb )

Resumes a previously suspended task.

Parameters:

tcb

The Task Control Block of the task to resume

Returns:: Status

Warning:: This call should only be used for debugging purposes.

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.

References BUG_check(), _TASK_wcb::cond, _TASK_wcb::mutex, _TASK_wcb::suspend, TASK__self(), and _TASK_tcb::wcb.

Referenced by FORK_resume().

int TASK_revert ( TASK_tcb * tcb )

Strips a task/thread of its TASK functionality.

Returns:: Status

Parameters:

tcb

The Task Control Block. This may be NULL, in which case the current task is reverted.

Reverts a converted task to a native task. It does this by returning the resources gathered by TASK_create(), TASK_spawn() or TASK_convert().

Although this call can be used with TASK_create() and TASK_spawn(), it is most usually called after TASK_convert().

References _TASK_tcb::pcb, TASK_self(), and _TASK_tcb::wcb.

Referenced by TASK_destroy(), TASK_exit(), and TASK_rvt().

int TASK_rvt ( void )

Reverts the current task back to its native self by stripping it of its TASK functionality.

Warning:: This is made for quick and dirty shell and test programming. It should never be used in production code. Use

See also:

TASK_convert () and

TASK_revert (). This function should be used with its partner,

TASK_cvt().

References MBA_free(), TASK_revert(), and TASK_self().

TASK_tcb * TASK_self ( void )

Returns the tcb of the calling task.

Returns:: The tcb of the calling task

Referenced by TASK_name(), TASK_revert(), and TASK_rvt().

int TASK_spawn	(	TASK_tcb *	tcb,
		const TASK_attr *	attributes,
		TASK_entry	entry_point,
		TASK_parameter	parameter
	)

Convenience routine to both create and activate a task.

Parameters:

	tcb	The task control block of the task to spawn
	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.
	entry_point	The address of the entry point of the newly created task. See TASK_entry for the call signature.
	parameter	A parameter which is passed transparently to the newly created task's entry point.

Convenience routine to both create and activate a task.

Referenced by FORK_create(), and wut_sys_connect().

int TASK_suspend ( TASK_tcb * tcb )

Suspends a task.

Parameters:

tcb

The Task Control Block of the task to suspend

Returns:: Status

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 VxWorks convention.

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.

References BUG_check(), _TASK_wcb::cond, _TASK_wcb::mutex, _TASK_wcb::suspend, TASK__self(), and _TASK_tcb::wcb.

Referenced by FORK_suspend().

TASK_tcb_sizeof ( void )

Returns the size, in bytes, of a TCB to be used when creating or spawning a TASK.

Returns:: The size, in bytes, of a TCB

Use this size to allocate memory for a TASK_tcb to use when calling TASK_create() or TASK_spawn().

Referenced by FORK_create(), and FORK_fcb_sizeof().

int TASK_unblock ( TASK_block_handle tbh )

Unblocks a task blocked on a call to TASK_block.

Returns:: Status

See also:: TASK_block

Parameters:

tbh

The task blocking handle

int TASK_wait ( const TOV tov )

Causes the calling task to wait (pause) until the specified timeout is reached.

Parameters:

tov

The timeout value to wait until

Returns:: Status

Warning:: This call should only be used for debugging purposes. It is just a convenience routine which wrappers TASK_wait() with a timeout value calculation.

References BUG_check(), _TASK_wcb::cond, _TASK_wcb::mutex, TASK__self(), TOV_NSECS, TOV_SECS, and _TASK_tcb::wcb.

Referenced by TASK_pause().

TASK_xtcb_sizeof ( void )

Returns the size, in bytes, of a TCB to be used when converting an existing (platform native task) to a TASK type task.

Returns:: The size, in bytes, of a TCB

Use this size to allocate memory for a TASK_tcb to use when calling TASK_convert().

Referenced by TASK_cvt().


Classes
struct	_TASK_attr
	Encapsulates the more esoteric options. More...
Defines
#define	TASK_PRINTF(_args)
	Debugging macro acting as a stand in for printf.
#define	TASK_K_NAME_MAX 16
	The maximum size of a task's name, including the terminating NUL character.
Typedefs
typedef struct _TASK_attr	TASK_attr
	Typedef for struct _TASK_attr.
typedef enum _TASK_priority_type	TASK_priority_type
	Typedef for enum _TASK_priority_type.
typedef void *	TASK_parameter
	The type of the parameter passed to the task's entry point routine.
typedef void (	TASK_entry )(TASK_parameter parameter)
	The function signature of the task's entry point routine.
typedef struct _TASK_tcb	TASK_tcb
	TASK facility's definition of a Task Control Block.
typedef int	TASK_int
typedef int(*	TASK_block_cb )(void *prm)
	Callback routine of TASK_block.
Enumerations
enum	_TASK_priority_type { TASK_K_PRIORITY_TYPE_ABS = 0, TASK_K_PRIORITY_TYPE_REL = 1 }
	Indicates how a priority specification to TASK_attr_setpriority is interpretted. More...
Functions
int	TASK_attr_init (TASK_attr *attributes)
	Provides a standard method of initializing the attributes block to a set of known values. These values may be platform dependent.
int	TASK_attr_priority_set (TASK_attr *attributes, int priority)
	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.
int	TASK_activate (TASK_tcb *tcb)
	Activates a previously created task.
int	TASK_create (TASK_tcb tcb, const TASK_attr attributes, TASK_entry entry_point, TASK_parameter parameter)
	Creates, but does not activate a task.
TASK_int	TASK_convert (TASK_tcb tcb, const TASK_attr attributes, TASK_entry entry_point, TASK_parameter parameter)
	Converts an existing VxWorks task to a TASK.
int	TASK_spawn (TASK_tcb tcb, const TASK_attr attributes, TASK_entry entry_point, TASK_parameter parameter)
	Convenience routine to both create and activate a task.
int	TASK_destroy (TASK_tcb *tcb)
	Destroys, ie deletes, a previously created task.
void	TASK_exit (void *status)
	Causes the calling task to delete itself and allows notification to another task, via TASK_join() that the calling task has deleted itself.
int	TASK_join (TASK_tcb tcb, void *status)
	Blocks the calling task until the specified task completes.
int	TASK_revert (TASK_tcb *tcb)
	Strips a task/thread of its TASK functionality.
TASK_tcb *	TASK_cvt (void)
	Converts an existing VXWORKs task or POSIX thread to TASK object.
int	TASK_rvt (void)
	Reverts the current task back to its native self by stripping it of its TASK functionality.
int	TASK_pause (unsigned int nsecs)
	Causes the calling task to wait (pause) for the specified number of nanoseconds.
int	TASK_resume (TASK_tcb *tcb)
	Resumes a previously suspended task.
int	TASK_suspend (TASK_tcb *tcb)
	Suspends a task.
int	TASK_wait (const TOV tov)
	Causes the calling task to wait (pause) until the specified timeout is reached.
int	TASK_block (TASK_block_handle tbh, TASK_block_cb rtn, void prm)
	Provides a simple way to turn an asynchronous routine into a synchronous routine.
int	TASK_unblock (TASK_block_handle tbh)
	Unblocks a task blocked on a call to TASK_block.
int	TASK_priority_get (const TASK_tcb *tcb)
	Gets the current priority of the specified task. The priority is returned expressed in the native tasking model's scheme.
int	TASK_tcb_sizeof (void)
	Returns the size, in bytes, of a TCB to be used when creating or spawning a TASK.
int	TASK_xtcb_sizeof (void)
	Returns the size, in bytes, of a TCB to be used when converting an existing (platform native task) to a TASK type task.
TASK_tcb *	TASK_self (void)
	Returns the tcb of the calling task.
const char *	TASK_name (const TASK_tcb *tcb)
	Returns a pointer to the task's name.
int	TASK_priority_number_boost (int priority, int boost)
	Boosts the priority number by the boost.
int	TASK_priority_number_compute (int priority, TASK_priority_type type, const TASK_tcb *tcb)
	Computes a priority number, either as an absolute or based on the priority of another task.
int	TASK_priority_number_limit (int priority)
	Limits the priority number to fit within the specified bounds.
int	TASK_priority_set (TASK_tcb *tcb, int priority)
	Sets priority of the specified task to the specified value.