GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> PBS / V2-12-1 > pbs / rhel5-32
#include <PBS/LI_pubdefs.h>
#include <PBS/PL_comdefs.h>
#include <PBS/TOC_comdefs.h>
Classes | |
union | _FORK_node |
Structure defining a FORK_node. More... | |
struct | _FORK_msg_hdr |
All messages queued by the FORK routines must be prefaced by this controlling structure. More... | |
struct | _FORK_msg_sys |
A predefined message consisting of a FORK_msg_hdr and a single 32-bit location to hold the contents. More... | |
struct | _FORK_que_cfg |
Describes the configuration of a que. More... | |
Typedefs | |
typedef struct _FORK_msg_hdr | FORK_msg_hdr |
Typedef for struct _FORK_msg_hdr. | |
typedef union _FORK_que | FORK_que |
Typedef for a FORK que. To the user this is an opaque handle. | |
typedef enum _FORK_type | FORK_type |
Typedef for the enum _FORK_type. | |
typedef enum _FORK_cb_status | FORK_cb_status |
Typedef for enum _FORK_cb_status. | |
typedef void * | FORK_cb_prm |
Typedef for the FORK callback parameter. | |
typedef FORK_cb_status(* | FORK_cb_rtn )(FORK_cb_prm context, FORK_msg_hdr *msg_hdr) |
Signature of the FORK callback handler. | |
typedef int(* | FORK_cb_modify )(FORK_cb_prm context, FORK_msg_hdr *msg_hdr) |
Signature of the FORK modify callback handler. | |
typedef union _FORK_node | FORK_node |
Typedef for a FORK_node. | |
typedef struct _FORK_msg_sys | FORK_msg_sys |
Typedef for struct _FORK_msg_sys. | |
typedef struct _FORK_que_cfg | FORK_que_cfg |
Typedef for struct _FORK_que_cfg. | |
typedef PL_list | FORK_que_list |
Used to enable and disable lists of ques. | |
typedef struct _FORK_fcb | FORK_fcb |
Typedef for struct _FORK_fcb. | |
Enumerations | |
enum | _FORK_type { FORK_K_TYPE_LOCKING_ONLY = RW_K_TYPE_LOCKING_ONLY, FORK_K_TYPE_PENDING = RW_K_TYPE_PENDING, FORK_K_TYPE_PENDING_WTO = RW_K_TYPE_PENDING_WTO, FORK_K_TYPE_PENDING_FIFO = RW_K_TYPE_PENDING_FIFO, FORK_K_TYPE_PENDING_FIFO_WTO = RW_K_TYPE_PENDING_FIFO_WTO, FORK_K_TYPE_PENDING_PRIORITY = RW_K_TYPE_PENDING_PRIORITY, FORK_K_TYPE_PENDING_PRIORITY_WTO = RW_K_TYPE_PENDING_PRIORITY_WTO } |
Enumerates the different pending types. This determines the behaviour when one attempts to allocate a system message from an empty list. More... | |
enum | _FORK_cb_status { FORK_C_CONTINUE = 0 } |
Enumerates the status of the call back routine. More... | |
Functions | |
int | FORK_fcb_sizeof (int nques) |
Returns the size, in bytes, of a FORK Control Block. | |
int | FORK_create (FORK_fcb *fcb, const struct _TASK_attr *attr, FORK_cb_rtn def_handler, FORK_cb_prm ctx, FORK_cb_prm tmo_ctx, const TOC *tmo_toc, int nques, const FORK_que_cfg *que_cfg, FORK_type msg_type, FORK_msg_sys *msg_blks, int msg_cnt) |
Creates a FORK message que. | |
int | FORK_destroy (FORK_fcb *fcb) |
Destroys a FORK que. | |
FORK_que_list | FORK_disable (FORK_fcb *fcb, FORK_que_list disable_list) |
Disables the servicing of the specified ques. | |
FORK_que_list | FORK_enable (FORK_fcb *fcb, FORK_que_list enable_list) |
Enables the servicing of the specified ques. | |
FORK_que_list | FORK_enabled (const FORK_fcb *fcb) |
Returns the enable/disabled state of the specified que. | |
int | FORK_join (FORK_fcb *fcb, int *exit_status) |
Waits until the FORK'd task is deleted. | |
int | FORK_qdisable (FORK_que *que) |
Disables the servicing of the specified que. | |
int | FORK_qenable (FORK_que *que) |
Enables the servicing of the specified que. | |
int | FORK_qenabled (const FORK_que *que) |
Returns the enable/disabled state of all ques. | |
int | FORK_qtail_modify (FORK_que *que, FORK_cb_modify modify, void *parameter) |
Sneaky way to modify the tail (newest) element on the specified FORK que. | |
int | FORK_qhead_modify (FORK_que *que, FORK_cb_modify modify, void *parameter) |
Sneaky way to modify the head (oldest) element on the specified FORK que. | |
int | FORK_qsys (FORK_que *que, FORK_cb_rtn handler, void *contents) |
Ques a message using the internal FORK message blocks. | |
int | FORK_qsysW (FORK_que *que, FORK_cb_rtn handler, void *contents) |
Ques a message using the internal FORK message blocks. | |
int | FORK_qsysW_toc (FORK_que *que, FORK_cb_rtn handler, void *contents, const TOC *tmo_toc) |
Ques a message using the internal FORK message blocks. | |
int | FORK_qusr (FORK_que *que, FORK_cb_rtn handler, FORK_msg_hdr *msg_hdr) |
Ques a user composed message. | |
int | FORK_resume (FORK_fcb *fcb) |
Resumes a previously suspended FORK task. | |
int | FORK_suspend (FORK_fcb *fcb) |
Suspends the FORK task. | |
FORK_que * | FORK_que_get (FORK_fcb *fcb, int que_id) |
Returns a handle to the specified que. |
CVS $Id: FORK.h,v 1.8 2011/03/24 23:05:41 apw Exp $
Signature of the FORK modify callback handler.
Defines the signature for the user callback & parameter
ret_code = (*cb_rtn) (FORK_cb_prm cb_prm, FORK_msg_hdr *msg_hdr) Where: cb_prm: The value of the context parameter passed into the FORK_qxxxx_modify routine. msg_hdr: A pointer to the message header of the message to be modified. This pointer will, in all likelihood, be recasted by the into a pointer to the specific style of message the user is expecting. ret_code: An arbitrary 32-bit integer passed back to the caller of FORK_qhead_modify() or FORK_qtail_modify().
Typedef for the FORK callback parameter.
This parameter is specified when calling FORK_create() and is passed transparently into the user's callback handler.
Signature of the FORK callback handler.
Defines the signature for the user callback & parameter
status = (*cb_rtn) (FORK_cb_prm cb_prm, FORK_msg_hdr *msg_hdr) Where: cb_prm: The value of the context parameter passed into the FORK_create routines. msg_hdr: A pointer to the message header. This pointer will, in all likelihood, be recasted into a pointer to the specific style of message one is expecting. RETURN VALUE: FORK_C_CONTINUE 0), keep going, anything else kill the FORK process.
Typedef for struct _FORK_fcb.
This block contains all the one time initialization parameters and serves as the caller's handle to the create FORK que. The free message list is used if and only if the user requests the creation of an internal que.
Typedef for struct _FORK_msg_sys.
This is a the message that is queued by the FORK_qsysXXX's routine. It consists of about the minimal usable message, a message header and one 4 byte location to store the message contents in.
Typedef for a FORK_node.
Typedef for struct _FORK_que_cfg.
This describes the properties of a que when the FORK facility is setup to handle multiple ques. This includes a default callback routine and parameter to be associated with the que.
enum _FORK_cb_status |
enum _FORK_type |
Enumerates the different pending types. This determines the behaviour when one attempts to allocate a system message from an empty list.
int FORK_create | ( | FORK_fcb * | fcb, | |
const struct _TASK_attr * | attributes, | |||
FORK_cb_rtn | def_handler, | |||
FORK_cb_prm | ctx, | |||
FORK_cb_prm | tmo_ctx, | |||
const TOC * | tmo_toc, | |||
int | nques, | |||
const FORK_que_cfg * | que_cfg, | |||
FORK_type | msg_type, | |||
FORK_msg_sys * | msg_blks, | |||
int | msg_cnt | |||
) |
Creates a FORK message que.
fcb | The FORK Control Block to initialize | |
attributes | The attributes to use when creating the FORK servicing task. | |
def_handler | The address of a default FORK handler. This routine will be called back in one of two circumstances. |
ctx | Parameter passed transparently to the user's callback handler, except in the case of a timeout. | |
tmo_ctx | Parameter passed transparently to the user's callback routine in case of a timeout. The user may use this parameter to distinguish a timeout condition from a normal message. (The message block will also be NULL in this case.) | |
tmo_toc | Timeout control specification. This is used when a message is being pended for. If this value is TOC_FOREVER, the pend is indefinite. |
nques | If specified as 0 or 1, a single non-prioritized que is used. If specified as >1, multiple prioritized ques are used. que_cfg configures each of the ques. | |
que_cfg | An array of que configuration blocks. If nques is specified as 0 or 1, this parameter is ignored. If the callback routine is specified as NULL for any individual que configuration, the default callback handler is used. | |
msg_type | The blocking type to use when attempting allocate a message from the system queue. There are three blocking styles. |
msg_blks | A source of internal message blocks. This may be specified as NULL and is ignored if msg_cnt is specified as 0. |
msg_cnt | The number of msg_blks. This may be specified as 0. In this case no system message pool is created and the values of the parameters msg_type and msg_blks are ignored. |
References _FORK_fcb::cfg, _FORK_que_cfg::ctx, _FORK_fcb::def, _FORK_fcb::enabled, _FORK_fcb::freelist, _FORK_que_cfg::handler, _FORK_que_head::li, LI_init(), LI_K_TYPE_PENDING_WTO, _FORK_fcb::msg_beg, _FORK_fcb::msg_cnt, _FORK_fcb::msg_end, _FORK_fcb::nques, _FORK_fcb::pend, _FORK_que_head::pl, PL_init(), PL_K_TYPE_PENDING_WTO, PL_SIZEOF, _FORK_fcb::rw, RW_init(), RW_K_TYPE_PENDING, TASK_spawn(), TASK_tcb_sizeof(), _FORK_fcb::tcb, _FORK_que_cfg::tmo_ctx, _FORK_fcb::tmo_toc, _FORK_fcb::toc_buf, TOC_IS_FOREVER, and TOC_IS_NOWAIT.
int FORK_destroy | ( | FORK_fcb * | fcb | ) |
Destroys a FORK que.
fcb | The Fork Control Block of the FORK que to destroy |
The usual method of winding down the FORK task is for the parent task to send a QUIT message to the FORK'd task. The parent task then calls FORK_join, which block until the FORK'd task exits. The FORK'd task performs any necessary clean-up then returns a non-zero status code from the callback routine. This causes the FORK'd task to delete itself, allowing the FORK_join() call to complete.
References _FORK_fcb::freelist, _FORK_que_head::li, LI_destroy(), _FORK_fcb::msg_cnt, _FORK_fcb::nques, _FORK_fcb::pend, _FORK_que_head::pl, PL_destroy(), _FORK_fcb::rw, and RW_destroy().
FORK_que_list FORK_disable | ( | FORK_fcb * | fcb, | |
FORK_que_list | disable_list | |||
) |
Disables the servicing of the specified ques.
fcb | The FORK Control Block | |
disable_list | The list of ques to disable |
References _FORK_fcb::enabled, _FORK_que_head::li, LI__disable(), _PL_ctl::mcfg, _FORK_fcb::nques, _FORK_fcb::pend, _FORK_que_head::pl, _FORK_fcb::rw, RW__lock(), and RW__unlock().
Referenced by FORK_qdisable().
FORK_que_list FORK_enable | ( | FORK_fcb * | fcb, | |
FORK_que_list | enable_list | |||
) |
Enables the servicing of the specified ques.
fcb | The FORK Control Block | |
enable_list | The list of ques to enable |
References _FORK_fcb::enabled, _FORK_que_head::li, LI__enable(), _PL_ctl::mcfg, _FORK_fcb::nques, _FORK_fcb::pend, _FORK_que_head::pl, PL__wake(), _FORK_fcb::rw, RW__lock(), and RW__unlock().
Referenced by FORK_qenable().
FORK_que_list FORK_enabled | ( | const FORK_fcb * | fcb | ) |
Returns the enable/disabled state of the specified que.
fcb | The FORK control block |
References _FORK_fcb::enabled, _FORK_que_head::li, LI__enabled(), _FORK_fcb::nques, and _FORK_fcb::pend.
int FORK_fcb_sizeof | ( | int | nques | ) |
Returns the size, in bytes, of a FORK Control Block.
nques | The number of internal ques to be supported |
The FORK routines are capable of supporting multiple prioritized internal ques. This is done by specifying nques to be greater than 1.
References PL_SIZEOF, and TASK_tcb_sizeof().
int FORK_join | ( | FORK_fcb * | fcb, | |
int * | exit_status | |||
) |
Waits until the FORK'd task is deleted.
fcb | The Fork Control Block | |
exit_status | Returned as the exit status of the FORK'd task. |
The usual method of winding down the FORK task is for the parent task to send a QUIT message to the FORK'd task. The parent task then calls FORK_join, which block until the FORK'd task exits. The FORK'd task performs any necessary clean-up then returns a non-zero status code from the callback routine. (This status code is returned to the user as exit_status.) This causes the FORK'd task to delete itself, allowing the FORK_join() call to complete. The user is then free to call FORK_destroy() to return the resources garnered by the FORK fcb.
Note that the exit_status may be returned as any non-zero 32-bit value. This includes returning a pointer to a structure which may contain additional information. If one does this, one must be careful to ensure that the memory is viable after task deletion. For instance, don't return pointers to things on the stack.
References TASK_join(), and _FORK_fcb::tcb.
int FORK_qdisable | ( | FORK_que * | que | ) |
Disables the servicing of the specified que.
0,if | the specified que was not originally enabled !=0, if the specified que was previously enabled |
que | The FORK que to disable |
References FORK_disable(), _PL_que::id, _FORK_que::pl, and PL_LIST.
int FORK_qenable | ( | FORK_que * | que | ) |
Enables the servicing of the specified que.
0,if | the specified que was not originally enabled !=0, if the specified que was previously enabled |
que | The FORK que to enable |
References FORK_enable(), _PL_que::id, _FORK_que::pl, and PL_LIST.
int FORK_qenabled | ( | const FORK_que * | que | ) |
Returns the enable/disabled state of all ques.
= | 0 if the queue was previously disabled != 0 if the queue was previously enabled |
que | The que to query |
References _FORK_fcb::enabled, _PL_que::id, _FORK_que_head::li, LI__enabled(), _FORK_fcb::nques, _FORK_fcb::pend, _FORK_que::pl, and PL_LIST.
int FORK_qhead_modify | ( | FORK_que * | que, | |
FORK_cb_modify | modify, | |||
void * | context | |||
) |
Sneaky way to modify the head (oldest) element on the specified FORK que.
que | The target fork que. | |
modify | A callback handler used to modify the que element. The return value of this callback routine is the return value of FORK_qhead_modify. |
context | A user provided context parameter. |
int FORK_qsys | ( | FORK_que * | que, | |
FORK_cb_rtn | handler, | |||
void * | contents | |||
) |
Ques a message using the internal FORK message blocks.
que | The target fork que. | |
handler | A callback handler. This may be specified as NULL, in which case, the default handler established by FORK_create(), will handle the message. | |
contents | A single 32-bit value representing the message contents. |
Note that because the message is internally allocated it may be possible that this list is exhausted. This version of the routine returns immediately with failure if the list is exhausted. See FORK_qsysW() or FORK_qsysW_toc for wait forever and wait with a timeout versions
References _FORK_msg_sys::contents, FORK_K_MSG_TYPE_SYS, _FORK_fcb::freelist, _FORK_msg_sys::hdr, and LI__remove().
int FORK_qsysW | ( | FORK_que * | que, | |
FORK_cb_rtn | handler, | |||
void * | contents | |||
) |
Ques a message using the internal FORK message blocks.
que | The target fork que. | |
handler | A callback handler. This may be specified as NULL, in which case, the default handler established by FORK_create(), will handle the message. | |
contents | A single 32-bit value representing the message contents. |
Note that because the message is internally allocated it may be possible that this list is exhausted. This version of the routine waits indefinitely until a message becomes available. See FORK_qsys() or FORK_qsysW_toc for no wait and wait with timeout versions.
References _FORK_msg_sys::contents, FORK_K_MSG_TYPE_SYS, _FORK_fcb::freelist, _FORK_msg_sys::hdr, and LI__removeW().
int FORK_qsysW_toc | ( | FORK_que * | que, | |
FORK_cb_rtn | handler, | |||
void * | contents, | |||
const TOC * | tmo_toc | |||
) |
Ques a message using the internal FORK message blocks.
que | The target fork que. | |
handler | A callback handler. This may be specified as NULL, in which case, the default handler established by FORK_create(), will handle the message. | |
contents | A single 32-bit value representing the message contents. | |
tmo_toc | A timeout control structure. This is used when no system message blocks available. The values TOC_NOWAIT and TOC_FOREVER can be used here. The information in this structure is copied, so the user may free the memory after the call. |
Note that because the message is internally allocated it may be possible that this list is exhausted. A timeout parameter is provided to handle this situation. See FORK_qsys() or FORK_qsysW for no wait and wait forever versions.
References _FORK_msg_sys::contents, FORK_K_MSG_TYPE_SYS, _FORK_fcb::freelist, _FORK_msg_sys::hdr, and LI__removeW_toc().
int FORK_qtail_modify | ( | FORK_que * | que, | |
FORK_cb_modify | modify, | |||
void * | context | |||
) |
Sneaky way to modify the tail (newest) element on the specified FORK que.
que | The target fork que. | |
modify | A callback handler used to modify the que element. The return value of this callback routine is the return value of FORK_qhead_modify. |
context | A user provided context parameter. |
Returns a handle to the specified que.
fcb | The FORK Control Block | |
que_id | The ID of the que |
References _FORK_que_head::li, _FORK_fcb::nques, _FORK_fcb::pend, _FORK_que_head::pl, and PL__que_get().
int FORK_qusr | ( | FORK_que * | que, | |
FORK_cb_rtn | handler, | |||
FORK_msg_hdr * | msg_hdr | |||
) |
Ques a user composed message.
que | The target fork que. | |
handler | A callback handler. This may be specified as NULL, in which case, the default handler established by FORK_create(), will handle the message. | |
msg_hdr | Pointer to the message to que. It is mandatory that all queued messages are prefaced by a standard message header block |
For the extra work involved in using this routine, the user gets to control his own memory allocation and the exact contents of the message. This means that there is almost no case, other than an internal corruption, under which this routine can fail.
References FORK_K_MSG_TYPE_USR.
int FORK_resume | ( | FORK_fcb * | fcb | ) |
Resumes a previously suspended FORK task.
fcb | The FORK Control Block |
References TASK_resume(), and _FORK_fcb::tcb.
int FORK_suspend | ( | FORK_fcb * | fcb | ) |
Suspends the FORK task.
fcb | The FORK Control Block |
References TASK_suspend(), and _FORK_fcb::tcb.