---

GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > PBS / V2-10-6

Constituent: pbs     Tag: linux-gcc

---

         

---

FORK.h File Reference

Fork an execution thread, create and manage buffered queues between two tasks. More...

#include "PBS/LI_pubdefs.h"
#include "PBS/PL_comdefs.h"
#include "PBS/TOC_comdefs.h"

Include dependency graph for FORK.h:

This graph shows which files directly or indirectly include this file:

Data Structures
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...
union	_FORK_node
	Structure defining a FORK_node. More...
struct	_FORK_que_cfg
	Describes the configuration of a que. More...
Typedefs
typedef _FORK_msg_hdr	FORK_msg_hdr
	Typedef for struct _FORK_msg_hdr.
typedef _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 _FORK_node	FORK_node
	Typedef for a FORK_node.
typedef _FORK_msg_sys	FORK_msg_sys
	Typedef for struct _FORK_msg_sys.
typedef _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 _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.

---

Detailed Description

Fork an execution thread, create and manage buffered queues between two tasks.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: FORK.h,v 1.7 2004/10/20 14:36:51 russell Exp $

---

Typedef Documentation

FORK_cb_modify

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(). Warning: It should be stated that this callback routine is done with the que locked. Depending on the implementation, locking the que may be implemented by disabling interrupts. With this in mind, the user is encouraged to get in and out of this routine as quickly as possible.

FORK_cb_prm

Typedef for the FORK callback parameter. This parameter is specified when calling FORK_create() and is passed transparently into the user's callback handler.

FORK_cb_rtn

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.

FORK_fcb

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.

FORK_msg_sys

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.

FORK_node

Typedef for a FORK_node. Warning: This is an internal union needed only to define a message header. The user never needs to manipulate this structure directly.

FORK_que_cfg

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.

---

Enumeration Type Documentation

enum _FORK_cb_status

Enumerates the status of the call back routine. This enumerates the return value of the user's dispatch callback handler. Any value but FORK_C_CONTINUE (0) causes the FORK'd task to delete itself. Enumeration values: FORK_C_CONTINUE  Continue normal processing

enum _FORK_type

Enumerates the different pending types. This determines the behaviour when one attempts to allocate a system message from an empty list. Enumeration values: FORK_K_TYPE_LOCKING_ONLY  Locking mechanism only, no pending mechanism available FORK_K_TYPE_PENDING  Pending mechanism available, single pender/reader only FORK_K_TYPE_PENDING_WTO  Pending with timeouts, single pender/reader only FORK_K_TYPE_PENDING_FIFO  Use FIFO pending order FORK_K_TYPE_PENDING_FIFO_WTO  Use FIFO pending order with timeouts available FORK_K_TYPE_PENDING_PRIORITY  Use PRIORITY pending order FORK_K_TYPE_PENDING_PRIORITY_WTO  Use PRIORITY pending order with timeouts available

---

Function Documentation

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. Parameters: 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. The user does not provide an explicit routine queing the message. A timeout occurs Parameters: 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. Warning: Do not pass NULL for this parameter. The standard intepretation of NULL for a timeout control block is as NO_WAIT. This is almost certainly not what one wants in the FORK routines. Parameters: 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. Non-blocking, this is the equivalent of a poll and is not very useful Blocking without a timeout. This is the equivalent of a indefinite wait for a message. Blocking with a timeout. Note: This parameter is applicable if and only if one is using a system pool to allocate messages from. Use of a system pool is determined by a non-zero message count, msg_cnt Parameters: msg_blks  A source of internal message blocks. This may be specified as NULL and is ignored if msg_cnt is specified as 0. Note: This parameter is applicable if and only if one is using a system pool to allocate messages from. Use of a system pool is determined by a non-zero message count, msg_cnt Parameters: 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. Returns: Status This routine creates the FORK message que and its associated task. The def_handler will be used as the callback handler when a message is queued without an explicit handler, see FORK_qsysW(), FORK_qsysWTO(), and FORK_quser(). It is also used when a timeout occurs.

Here is the call graph for this function:

int FORK_destroy (  FORK_fcb *  fcb  )

Destroys a FORK que. Parameters: fcb  The Fork Control Block of the FORK que to destroy Returns: Status Releases all the internal resources used by the FORK que. It does not release either the memory associated with any potential internal pool of message blocks that the FORK routines may be managing on behalf of the user, nor does it release the memory associated with the Fork Control Block itself. Both these are user providef blocks of memory and, therefore, user managed blocks of memories. 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. Warning: As with all delete operations, care must be taken to ensure it is safe to destroy the FORK que. The above suggests one method of doing this.

Here is the call graph for this function:

FORK_que_list FORK_disable (  FORK_fcb *  fcb, FORK_que_list  disable_list )

Disables the servicing of the specified ques. Parameters: fcb  The FORK Control Block disable_list  The list of ques to disable Returns: The list of previously of enabled ques

Here is the call graph for this function:

FORK_que_list FORK_enable (  FORK_fcb *  fcb, FORK_que_list  enable_list )

Enables the servicing of the specified ques. Parameters: fcb  The FORK Control Block enable_list  The list of ques to enable Returns: The list of previously of enabled ques

Here is the call graph for this function:

FORK_que_list FORK_enabled (  const FORK_fcb *  fcb  )

Returns the enable/disabled state of the specified que. Parameters: fcb  The FORK control block Returns: A list of the enabled ques, MSB = que 0. Warning: As with all queries of this type, the answer is only good until it changes. The user is cautioned on its usage. It is primarily provided as a debugging tool.

Here is the call graph for this function:

int FORK_fcb_sizeof (  int  nques  )

Returns the size, in bytes, of a FORK Control Block. Parameters: nques  The number of internal ques to be supported Returns: The sizeof of a fork control block Returns the size of a FORK CONTROL BLOCK. This allows the user to allocate and control the FORK CONTROL BLOCK without making its internal structure known. The FORK routines are capable of supporting multiple prioritized internal ques. This is done by specifying nques to be greater than 1.

Here is the call graph for this function:

int FORK_join (  FORK_fcb *  fcb, int *  exit_status )

Waits until the FORK'd task is deleted. Parameters: fcb  The Fork Control Block exit_status  Returned as the exit status of the FORK'd task. Returns: Status of the join operation. This allows the parent task to synchronize with the deletion 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.

Here is the call graph for this function:

int FORK_qdisable (  FORK_que *  que  )

Disables the servicing of the specified que. Return values: 0,if  the specified que was not originally enabled !=0, if the specified que was previously enabled Parameters: que  The FORK que to disable Warning: Note that the return value is the original state of the all enables before the qdisable was performed.

Here is the call graph for this function:

int FORK_qenable (  FORK_que *  que  )

Enables the servicing of the specified que. Return values: 0,if  the specified que was not originally enabled !=0, if the specified que was previously enabled Parameters: que  The FORK que to enable

Here is the call graph for this function:

int FORK_qenabled (  const FORK_que *  que  )

Returns the enable/disabled state of all ques. Return values: =  0 if the queue was previously disabled != 0 if the queue was previously enabled Parameters: que  The que to query Warning: As with all queries of this type, the answer is only good until it changes. The user is cautioned on its usage. It is primarily provided as a debugging tool.

Here is the call graph for this function:

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. Parameters: 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. Warning: If the que is empty, NULL is passed as the msg_hdr header in the callback routine. Parameters: context  A user provided context parameter. Returns: Whatever the user callback routine does.

int FORK_qsys (  FORK_que *  que, FORK_cb_rtn  handler, void *  contents )

Ques a message using the internal FORK message blocks. Parameters: 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. Returns: Status Ques a message to the FORK message que using the internal system message pool. System messages are limited to queing a single 32-bit number. Of course one can always use this to que a pointer to another data structure. The user should consider FORK_qusr(), to que a more complicated message without absorbing another level of indirection. 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

Here is the call graph for this function:

int FORK_qsysW (  FORK_que *  que, FORK_cb_rtn  handler, void *  contents )

Ques a message using the internal FORK message blocks. Parameters: 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. Returns: Status Ques a message to the FORK message que using the internal system message pool. System messages are limited to queing a single 32-bit number. Of course one can always use this to que a pointer to another data structure. The user should consider FORK_qusr(), to que a more complicated message without absorbing another level of indirection. 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.

Here is the call graph for this function:

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. Parameters: 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. Returns: Status Ques a message to the FORK message que using the internal system message pool. System messages are limited to queing a single 32-bit number. Of course one can always use this to que a pointer to another data structure. The user should consider FORK_qusr(), to que a more complicated message without absorbing another level of indirection. 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.

Here is the call graph for this function:

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. Parameters: 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. Warning: If the que is empty, NULL is passed as the msg_hdr header in the callback routine. Parameters: context  A user provided context parameter. Returns: Whatever the user callback routine does.

FORK_que* FORK_que_get (  FORK_fcb *  fcb, int  que_id )

Returns a handle to the specified que. Parameters: fcb  The FORK Control Block que_id  The ID of the que Returns: A handle to the specified que or NULL if no such que exists. The FORK que routines take a FORK que as a parameter. This is used routine is used to get that handle. When a single que is managed by the FORK routines, only a que_id of 0 is allowed. When multiple ques are managed by the FORK routines, then an a que_id up to nques - 1 is allowed, with que_id = 0 being the highest priority que.

Here is the call graph for this function:

int FORK_qusr (  FORK_que *  que, FORK_cb_rtn  handler, FORK_msg_hdr *  msg_hdr )

Ques a user composed message. Parameters: 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 Returns: Status Ques a user defined message. This routine behaves in much the same manner as FORK_qsys(), except the message being queued is controlled almost entirely by the user. (The except part, is that the message must be prefaced by a standard message header.) 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.

int FORK_resume (  FORK_fcb *  fcb  )

Resumes a previously suspended FORK task. Parameters: fcb  The FORK Control Block Returns: Status Warning: This routine and its companion, FORK_suspend(), are primarily intended to be used for debugging and test code purposes.

Here is the call graph for this function:

int FORK_suspend (  FORK_fcb *  fcb  )

Suspends the FORK task. Parameters: fcb  The FORK Control Block Returns: Status Warning: This routine and its companion, FORK_resume(), are primarily intended to be used for debugging and test code purposes.

Here is the call graph for this function:

---