---

FORK.c File Reference

The FORK routines. More...

#include "BBC/LLI.ih"
#include "BBC/TASK.h"
#include "BBC/FORK.h"

Data Structures
struct	_FORK_fcb
	The Fork Control Block. More...
Typedefs
typedef enum _FORK_msg_type	FORK_msg_type
	Typedef for enum FORK_msg_type.
Enumerations
enum	_FORK_msg_type {   FORK_K_MSG_TYPE_USR = 0,   FORK_K_MSG_TYPE_SYS = 1 }
	Distinguishes between the two types of messages, user or system.
Functions
int	FORK_pend (FORK_fcb *fcb)
	This is an internal routine used by the FORK servicing task. More...
void	create_list (LLI_list *list, FORK_msg_sys *msgs, int cnt, FORK_type type)
	Internal routine to initialize the system pool of messages. More...
int	que (FORK_fcb *fcb, FORK_cb_rtn handler, FORK_msg_hdr *msg, FORK_msg_type msg_type)
	Internal routine to que a message for servicing. More...
int	FORK_fcb_sizeof (void)
	Returns the size, in bytes, of a FORK Control Block. More...
int	FORK_create (FORK_fcb *fcb, FORK_cb_rtn def_handler, FORK_cb_prm ctx, FORK_cb_prm tmo_ctx, int tmo, FORK_msg_sys *msg_blks, int msg_cnt, FORK_type type, const TASK_attr *attributes)
	Creates a FORK message que. More...
int	FORK_destroy (FORK_fcb *fcb)
	Destroys a FORK que. More...
int	FORK_qsys (FORK_fcb *fcb, FORK_cb_rtn handler, void *contents, int tmo)
	Ques a message using the internal FORK message blocks. More...
int	FORK_qusr (FORK_fcb *fcb, FORK_cb_rtn handler, FORK_msg_hdr *msg)
	Ques a user composed message. More...

---

Detailed Description

The FORK routines.

---

Function Documentation

void create_list (  LLI_list *    list, FORK_msg_sys *    msgs, int    cnt, FORK_type    type )  [inline, static]

Internal routine to initialize the system pool of messages. Parameters: list  The list msgs  The array of messages to place on the que cnt  The number of messages to place on the que type  The type of blocking to use on the create pool.

int FORK_create (  FORK_fcb *    fcb, FORK_cb_rtn    def_handler, FORK_cb_prm    ctx, FORK_cb_prm    tmo_ctx, int    tmo, FORK_msg_sys *    msg_blks, int    msg_cnt, FORK_type    type, const TASK_attr *    attr )

Creates a FORK message que. Parameters: fcb  The FORK Control Block to initialize def_handler  The address of a default FORK handler. This routine will be called back in one of two circumstances. 1. The user does not provide an explicit routine queing the message. 2. A timeout occurs 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.) msg_blks  A source of internal message blocks. This may be specified as NULL. msg_cnt  The number of msg_blks. This may be specified as 0. Note that this parameter is ignored if msg_blks is specified as NULL. type  The blocking type to use when attempting allocate a message from the system queue. attributes  The attributes to use when creating the FORK servicing task. 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_qsys() and FORK_quser(). It is also used when a timeout occurs.

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 thr Fork Control Block itself. Both these are user providef blocks of memory and, therefore, user managed blocks of memories. Warning: As with all delete operations, care must be taken to ensure it is safe to destroy the FORK que.

FORK_fcb_sizeof (  void    )

Returns the size, in bytes, of a FORK Control Block. Returns: The sizeof of a fork control block Gets 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.

int FORK_pend (  FORK_fcb *    fcb )

This is an internal routine used by the FORK servicing task. Parameters: fcb  The FORK Control Block Returns: Status This is an internal routine used by the FORK servicing task to receive and dispatch messages to the appropriate handler.

int FORK_qsys (  FORK_fcb *    fcb, FORK_cb_rtn    handler, void *    contents, int    tmo )

Ques a message using the internal FORK message blocks. Parameters: fcb  The Fork Control Block to que the message to 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  A timeout value to be used in case there are no message blocks available. The values FORK_K_WTO_NO_WAIT (0) and FORK_K_WTO_FOREVER can be used here. In the future a real timeout value will be implemented. 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 a 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.

int FORK_qusr (  FORK_fcb *    fcb, FORK_cb_rtn    handler, FORK_msg_hdr *    msg_hdr )

Ques a user composed message. Parameters: fcb  The Fork Control Block to que the message to 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 que (  FORK_fcb *    fcb, FORK_cb_rtn    handler, FORK_msg_hdr *    msg, FORK_msg_type    msg_type )  [inline, static]

Internal routine to que a message for servicing. Parameters: fcb  The FORK Control Block to que the message to. handler  The address of the routine to the message msg  The message to que. msg_type  The message type that is being queued, ie user or system Returns: Status

---