GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > PBS / V2-10-14
Constituent: pbs     Tag: rad750
#include "PBS/TOV.h"
Include dependency graph for TASK.h:
This graph shows which files directly or indirectly include this file:
Data Structures | |
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 _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 _TASK_tcb | TASK_tcb |
TASK facility's definition of a Task Control Block. | |
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. | |
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. |
CVS $Id: TASK.h,v 1.6 2005/10/01 01:00:12 russell Exp $
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.
|
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. |
|
Debugging macro acting as a stand in for printf.
|
|
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. |
|
Callback routine of TASK_block.
|
|
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. |
|
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. |
|
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 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. |
|
Indicates how a priority specification to TASK_attr_setpriority is interpretted.
|
|
Activates a previously created task.
|
|
Provides a standard method of initializing the attributes block to a set of known values. These values may be platform dependent.
|
|
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.
|
|
Provides a simple way to turn an asynchronous routine into a synchronous routine.
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);
int read_synch (Synch *synch) { return TASK_unblock (synch->tbh); } |
|
Converts an existing VxWorks task to a TASK.
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.
|
|
Creates, but does not activate a task.
|
|
Converts an existing VXWORKs task or POSIX thread to TASK object.
|
|
Destroys, ie deletes, a previously created task.
|
|
Causes the calling task to delete itself and allows notification to another task, via TASK_join() that the calling task has deleted itself.
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. |
|
Blocks the calling task until the specified task completes.
|
|
Returns a pointer to the task's name.
|
|
Causes the calling task to wait (pause) for the specified number of nanoseconds.
|
|
Gets the current priority of the specified task. The priority is returned expressed in the native tasking model's scheme.
|
|
Boosts the priority number by the boost.
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,
|
|
Computes a priority number, either as an absolute or based on the priority of another task.
|
|
Limits the priority number to fit within the specified bounds.
|
|
Sets priority of the specified task to the specified value.
|
|
Resumes a previously suspended task.
|
|
Strips a task/thread of its TASK functionality.
Although this call can be used with TASK_create() and TASK_spawn(), it is most usually called after TASK_convert(). |
|
Reverts the current task back to its native self by stripping it of its TASK functionality.
|
|
Returns the tcb of the calling task.
|
|
Convenience routine to both create and activate a task.
|
|
Suspends a task.
|
|
Returns the size, in bytes, of a TCB to be used when creating or spawning a TASK.
|
|
Unblocks a task blocked on a call to TASK_block.
|
|
Causes the calling task to wait (pause) until the specified timeout is reached.
|
|
Returns the size, in bytes, of a TCB to be used when converting an existing (platform native task) to a TASK type task.
|