\hypertarget{FORK_8h}{ \section{FORK.h File Reference} \label{FORK_8h}\index{FORK.h@{FORK.h}} } The FORK utilities create and manage a buffered queue between two tasks. {\tt \#include \char`\"{}BBC/LLI.h\char`\"{}}\par {\tt \#include \char`\"{}BBC/TASK.h\char`\"{}}\par \subsection*{Data Structures} \begin{CompactItemize} \item struct \hyperlink{struct__FORK__msg__hdr}{\_\-FORK\_\-msg\_\-hdr} \begin{CompactList}\small\item\em All messages queued by the FORK routines must be prefaced by this controlling structure.\item\end{CompactList}\item struct \hyperlink{struct__FORK__msg__sys}{\_\-FORK\_\-msg\_\-sys} \begin{CompactList}\small\item\em A predefined message consisting of a FORK\_\-msg\_\-hdr and a single 32-bit location to hold the contents.\item\end{CompactList}\end{CompactItemize} \subsection*{Typedefs} \begin{CompactItemize} \item \hypertarget{FORK_8h_a0}{ \index{FORK_fcb@{FORK\_\-fcb}!FORK.h@{FORK.h}}\index{FORK.h@{FORK.h}!FORK_fcb@{FORK\_\-fcb}} typedef \hyperlink{struct__FORK__fcb}{\_\-FORK\_\-fcb} \hyperlink{FORK_8h_a0}{FORK\_\-fcb}} \label{FORK_8h_a0} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__FORK__fcb}{\_\-FORK\_\-fcb}.\item\end{CompactList}\item \hypertarget{FORK_8h_a1}{ \index{FORK_msg_hdr@{FORK\_\-msg\_\-hdr}!FORK.h@{FORK.h}}\index{FORK.h@{FORK.h}!FORK_msg_hdr@{FORK\_\-msg\_\-hdr}} typedef \hyperlink{struct__FORK__msg__hdr}{\_\-FORK\_\-msg\_\-hdr} \hyperlink{FORK_8h_a1}{FORK\_\-msg\_\-hdr}} \label{FORK_8h_a1} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__FORK__msg__hdr}{\_\-FORK\_\-msg\_\-hdr}.\item\end{CompactList}\item \hypertarget{FORK_8h_a2}{ \index{FORK_msg_sys@{FORK\_\-msg\_\-sys}!FORK.h@{FORK.h}}\index{FORK.h@{FORK.h}!FORK_msg_sys@{FORK\_\-msg\_\-sys}} typedef \hyperlink{struct__FORK__msg__sys}{\_\-FORK\_\-msg\_\-sys} \hyperlink{FORK_8h_a2}{FORK\_\-msg\_\-sys}} \label{FORK_8h_a2} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__FORK__msg__sys}{\_\-FORK\_\-msg\_\-sys}.\item\end{CompactList}\item typedef enum \hyperlink{FORK_8h_a18}{\_\-FORK\_\-type} \hyperlink{FORK_8h_a3}{FORK\_\-type} \begin{CompactList}\small\item\em Typedef for the enum \_\-FORK\_\-type.\item\end{CompactList}\item \hypertarget{FORK_8h_a4}{ \index{FORK_cb_status@{FORK\_\-cb\_\-status}!FORK.h@{FORK.h}}\index{FORK.h@{FORK.h}!FORK_cb_status@{FORK\_\-cb\_\-status}} typedef enum \hyperlink{FORK_8h_a19}{\_\-FORK\_\-cb\_\-status} \hyperlink{FORK_8h_a4}{FORK\_\-cb\_\-status}} \label{FORK_8h_a4} \begin{CompactList}\small\item\em Typedef for enum \_\-FORK\_\-cb\_\-status.\item\end{CompactList}\item typedef void $\ast$ \hyperlink{FORK_8h_a5}{FORK\_\-cb\_\-prm} \begin{CompactList}\small\item\em Typedef for the FORK callback parameter.\item\end{CompactList}\item typedef \hyperlink{FORK_8h_a4}{FORK\_\-cb\_\-status}($\ast$ \hyperlink{FORK_8h_a6}{FORK\_\-cb\_\-rtn} )(\hyperlink{FORK_8h_a5}{FORK\_\-cb\_\-prm} context, struct \hyperlink{struct__FORK__msg__hdr}{\_\-FORK\_\-msg\_\-hdr} $\ast$msg\_\-hdr) \begin{CompactList}\small\item\em Signature of the FORK callback handler.\item\end{CompactList}\end{CompactItemize} \subsection*{Enumerations} \begin{CompactItemize} \item enum \hyperlink{FORK_8h_a18}{\_\-FORK\_\-type} \{ \hyperlink{FORK_8h_a18a7}{FORK\_\-K\_\-TYPE\_\-NON\_\-BLOCKING} = LLI\_\-K\_\-TYPE\_\-NON\_\-BLOCKING, \hyperlink{FORK_8h_a18a8}{FORK\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING} = LLI\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING, \hyperlink{FORK_8h_a18a9}{FOKR\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING} = LLI\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING \} \begin{CompactList}\small\item\em Enumerates the different blocking types. This determines the behaviour one attempts to remove an system message from an empty list.\item\end{CompactList}\item enum \hyperlink{FORK_8h_a19}{\_\-FORK\_\-cb\_\-status} \{ \hyperlink{FORK_8h_a19a10}{FORK\_\-C\_\-DESTROY} = -2, \hyperlink{FORK_8h_a19a11}{FORK\_\-C\_\-ABORT} = -1, \hyperlink{FORK_8h_a19a12}{FORK\_\-C\_\-CONTINUE} = 0 \} \begin{CompactList}\small\item\em Enumerates the status of the call back routine.\item\end{CompactList}\end{CompactItemize} \subsection*{Functions} \begin{CompactItemize} \item int \hyperlink{FORK_8h_a13}{FORK\_\-fcb\_\-sizeof} (void) \begin{CompactList}\small\item\em Returns the size, in bytes, of a FORK Control Block.\item\end{CompactList}\item int \hyperlink{FORK_8h_a14}{FORK\_\-create} (\hyperlink{FORK_8h_a0}{FORK\_\-fcb} $\ast$fcb, \hyperlink{FORK_8h_a6}{FORK\_\-cb\_\-rtn} def\_\-handler, \hyperlink{FORK_8h_a5}{FORK\_\-cb\_\-prm} ctx, \hyperlink{FORK_8h_a5}{FORK\_\-cb\_\-prm} tmo\_\-ctx, int tmo, \hyperlink{FORK_8h_a2}{FORK\_\-msg\_\-sys} $\ast$msg\_\-blks, int msg\_\-cnt, \hyperlink{FORK_8h_a3}{FORK\_\-type} type, const TASK\_\-attr $\ast$attr) \begin{CompactList}\small\item\em Creates a FORK message que.\item\end{CompactList}\item int \hyperlink{FORK_8h_a15}{FORK\_\-destroy} (\hyperlink{FORK_8h_a0}{FORK\_\-fcb} $\ast$fcb) \begin{CompactList}\small\item\em Destroys a FORK que.\item\end{CompactList}\item int \hyperlink{FORK_8h_a16}{FORK\_\-qsys} (\hyperlink{FORK_8h_a0}{FORK\_\-fcb} $\ast$fcb, \hyperlink{FORK_8h_a6}{FORK\_\-cb\_\-rtn} handler, void $\ast$contents, int tmo) \begin{CompactList}\small\item\em Ques a message using the internal FORK message blocks.\item\end{CompactList}\item int \hyperlink{FORK_8h_a17}{FORK\_\-qusr} (\hyperlink{FORK_8h_a0}{FORK\_\-fcb} $\ast$fcb, \hyperlink{FORK_8h_a6}{FORK\_\-cb\_\-rtn} handler, \hyperlink{FORK_8h_a1}{FORK\_\-msg\_\-hdr} $\ast$msg\_\-hdr) \begin{CompactList}\small\item\em Ques a user composed message.\item\end{CompactList}\end{CompactItemize} \subsection{Detailed Description} The FORK utilities create and manage a buffered queue between two tasks. The FORK routines provide a convenient way to spread work across to tasks or threads. A interlocked message que is created between the task calling task of FORK\_\-create () and a task/thread created by the \hyperlink{FORK_8h_a14}{FORK\_\-create}(). Messages can be placed on this que by any task that has access to the que through the Fork Control Block. In this sense, it is a multi-writer, single-reader half-duplex communication link. These routines serve much the same purpose as the Vx\-Works sem\-Q routines with some important advantages. \par 1. These routines allow one complete control over the memory containing the messages. The Vx\-Works send routine merely returns a {\em failure} status code when one memory exists to buffer a new message. This causes two problems for the programmer. The first is, exactly when does should one try again. The only recourse here, aside from the non-answer of polling until success, is to provide a synchronizing mechanism. One could give a semaphore when a message was consumed. This seems kludgy, since the semaphore is not tied explicitly to the message que and overly complicated to use. T The second problem is what does the user do when blocking is not an option, as in an interrupt service routine. The FORK routines allow the user to pre-allocate the message buffer before committing to servicing an interrupt. This ensures that the necessary resources are in hand. 2. The burden of creating the receiving task is taken on by the \hyperlink{FORK_8h_a14}{FORK\_\-create}() routine. Since the metaphor of the FORK routines is to transparently {\bf fork} the execution path, this seems more natural than manually creating an task/thread to handle the messages. In most cases, this is all the create task is going to do, ie pend on a message que and service the incominig messages. 3. The messsage to be queued is not copied twice as it is in the Vx\-Works routines (once when sending and once when receiving). This is a direct consequence of allowing the user to do his own management of the message buffers. {\bf USAGE} \par {\bf -----} \par The user first creates the FORK que by calling \hyperlink{FORK_8h_a14}{FORK\_\-create}(). \hyperlink{FORK_8h_a14}{FORK\_\-create}() allows control overall the parameters of the FORK que, including the attributes of the FORK servicing task. The user also has the option having the FORK routines create an internally managed pool of message buffers. A queued message always consists of two quantities, a routine to handle the message and the message contents itself. If the internal message pool, referred to here as the system pool, is used, the contents of the message are limited to a single 32 bit number. If the user chooses to que his own messages, the contents can be any size he wishes, his own obligation is to preface the message with a FORK\_\-msg\_\-hdr structure. Messages of varying sizes and types, ie both user and system messages, can be queued to the same FORK que. The deallocation of user messages are the responsibility of the user, while system messages are freed immediately after the dispatch routine finishes its processing. This latter design choice has only a slight impact on performance, since, in theory, the dispatch routine could release the message memory earlier. However, given the single reader nature of the FORK utilities, only one such buffer can be outstanding at an given time. The truly concerned user can avoid this limitation by using only message buffers that he manages. {\bf EXAMPLE} \par {\bf -------} \par \footnotesize\begin{verbatim} FORK_fcb *fcb; int size; / * Allocate 10 message blocks for the FORK ques internal pool * / FORK_msg_sys msg_blks[10]; int msg_blk_cnt = sizeof (msg_blks) / sizeof (*msg_blks); size = FORK_fcb_sizeof (); / * Size of Fork Control Block * / fcb = (FORK_fcb *) malloc (size); / * Allocate the memory for it * / / * Create the fork que * / status = FORK_create (fcb, / * Fork Control Block to init * / normalPrint, / * Default handling routine * / forkParameter, / * Parameter passed to handler * / forkTmoParameter, / * Parameter passed if timeout * / timeout, / * How long to pend before tmo * / msg_blks, / * A source of message blocks * / msg_blk_cnt, / * Number of messge blocks * / FORK_K_TYPE_FIFO_BLOCKING, / * FIFO style blocking when * / / * allocating system messges * / NULL); / * Use default task attributes * / status = FORK_qsys (fcb, NULL, "Hello World\n", FORK_K_WTO_FOREVER); status = FORK_qsys (fcb, boldPrint, "Goodbye World\n", FORK_K_WTO_FOREVER); } int normalPrint (void *parameter, FORK_msg_sys *msg) { fputs (msg->contents); return FORK_C_CONTINUE; } int boldPrint (void *parameter, FORK_msg_sys *msg) { printf ("%s", BOLD_ESC_SEQUENCE); fputs (msg->contents); printf ("%s", NORMAL_ESC_SEQUENCE); return FORK_C_CONTINUE; } \end{verbatim}\normalsize The usual precautions should be heeded. For example, in this example, not allowing the creating task to terminate when messages are still on the que. Since the memory is from stack, that would be bad. \subsection{Typedef Documentation} \hypertarget{FORK_8h_a5}{ \index{FORK.h@{FORK.h}!FORK_cb_prm@{FORK\_\-cb\_\-prm}} \index{FORK_cb_prm@{FORK\_\-cb\_\-prm}!FORK.h@{FORK.h}} \subsubsection[FORK\_\-cb\_\-prm]{\setlength{\rightskip}{0pt plus 5cm}FORK\_\-cb\_\-prm}} \label{FORK_8h_a5} Typedef for the FORK callback parameter. This parameter is specified when calling \hyperlink{FORK_8h_a14}{FORK\_\-create}() and is passed transparently into the user's callback handler. \hypertarget{FORK_8h_a6}{ \index{FORK.h@{FORK.h}!FORK_cb_rtn@{FORK\_\-cb\_\-rtn}} \index{FORK_cb_rtn@{FORK\_\-cb\_\-rtn}!FORK.h@{FORK.h}} \subsubsection[FORK\_\-cb\_\-rtn]{\setlength{\rightskip}{0pt plus 5cm}FORK\_\-cb\_\-rtn}} \label{FORK_8h_a6} Signature of the FORK callback handler. Defines the signature for the user callback \& parameter \footnotesize\begin{verbatim} 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, keep going. FORK_C_ABORT, abort the FORK task. FORK_C_DESTROY, abort the FORK task and destroy the FORK q \end{verbatim}\normalsize \hypertarget{FORK_8h_a3}{ \index{FORK.h@{FORK.h}!FORK_type@{FORK\_\-type}} \index{FORK_type@{FORK\_\-type}!FORK.h@{FORK.h}} \subsubsection[FORK\_\-type]{\setlength{\rightskip}{0pt plus 5cm}FORK\_\-type}} \label{FORK_8h_a3} Typedef for the enum \_\-FORK\_\-type. \subsection{Enumeration Type Documentation} \hypertarget{FORK_8h_a19}{ \index{FORK.h@{FORK.h}!_FORK_cb_status@{\_\-FORK\_\-cb\_\-status}} \index{_FORK_cb_status@{\_\-FORK\_\-cb\_\-status}!FORK.h@{FORK.h}} \subsubsection[\_\-FORK\_\-cb\_\-status]{\setlength{\rightskip}{0pt plus 5cm}enum \_\-FORK\_\-cb\_\-status}} \label{FORK_8h_a19} Enumerates the status of the call back routine. This enumerates the return value of the user's dispatch callback handler. Basically one can tell the FORK pend routine to do one of three things, pend for another message, FORK\_\-C\_\-CONTINUE, abort, FORK\_\-C\_\-ABORT, or FORK\_\-C\_\-DESTROY, abort the FORK que and destroy the FORK que context. Aborting the FORK pend operation kills the FORK servicing task, so be careful that all context has been cleaned up before issuing this return code. It is up to the user to clean-up these resources. \begin{Desc} \item[Warning: ]\par The FORK shutdown procedure is not well-defined at this time so avoid using this feature for a while. \end{Desc} \begin{Desc} \item[Enumeration values:]\par \begin{description} \index{FORK_C_DESTROY@{FORK\_\-C\_\-DESTROY}!FORK.h@{FORK.h}}\index{FORK.h@{FORK.h}!FORK_C_DESTROY@{FORK\_\-C\_\-DESTROY}}\item[{\em \hypertarget{FORK_8h_a19a10}{ {\em FORK\_\-C\_\-DESTROY}} \label{FORK_8h_a19a10} }]Kill the FORK task and the FORK context \index{FORK_C_ABORT@{FORK\_\-C\_\-ABORT}!FORK.h@{FORK.h}}\index{FORK.h@{FORK.h}!FORK_C_ABORT@{FORK\_\-C\_\-ABORT}}\item[{\em \hypertarget{FORK_8h_a19a11}{ {\em FORK\_\-C\_\-ABORT}} \label{FORK_8h_a19a11} }]Kill the FORK task, but not the FORK context \index{FORK_C_CONTINUE@{FORK\_\-C\_\-CONTINUE}!FORK.h@{FORK.h}}\index{FORK.h@{FORK.h}!FORK_C_CONTINUE@{FORK\_\-C\_\-CONTINUE}}\item[{\em \hypertarget{FORK_8h_a19a12}{ {\em FORK\_\-C\_\-CONTINUE}} \label{FORK_8h_a19a12} }]Continue normal processing \end{description} \end{Desc} \hypertarget{FORK_8h_a18}{ \index{FORK.h@{FORK.h}!_FORK_type@{\_\-FORK\_\-type}} \index{_FORK_type@{\_\-FORK\_\-type}!FORK.h@{FORK.h}} \subsubsection[\_\-FORK\_\-type]{\setlength{\rightskip}{0pt plus 5cm}enum \_\-FORK\_\-type}} \label{FORK_8h_a18} Enumerates the different blocking types. This determines the behaviour one attempts to remove an system message from an empty list. \begin{Desc} \item[Enumeration values:]\par \begin{description} \index{FORK_K_TYPE_NON_BLOCKING@{FORK\_\-K\_\-TYPE\_\-NON\_\-BLOCKING}!FORK.h@{FORK.h}}\index{FORK.h@{FORK.h}!FORK_K_TYPE_NON_BLOCKING@{FORK\_\-K\_\-TYPE\_\-NON\_\-BLOCKING}}\item[{\em \hypertarget{FORK_8h_a18a7}{ {\em FORK\_\-K\_\-TYPE\_\-NON\_\-BLOCKING}} \label{FORK_8h_a18a7} }]No blocking mechanism available \index{FORK_K_TYPE_FIFO_BLOCKING@{FORK\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING}!FORK.h@{FORK.h}}\index{FORK.h@{FORK.h}!FORK_K_TYPE_FIFO_BLOCKING@{FORK\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING}}\item[{\em \hypertarget{FORK_8h_a18a8}{ {\em FORK\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING}} \label{FORK_8h_a18a8} }]Use FIFO blocking order \index{FOKR_K_TYPE_PRIORITY_BLOCKING@{FOKR\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING}!FORK.h@{FORK.h}}\index{FORK.h@{FORK.h}!FOKR_K_TYPE_PRIORITY_BLOCKING@{FOKR\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING}}\item[{\em \hypertarget{FORK_8h_a18a9}{ {\em FOKR\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING}} \label{FORK_8h_a18a9} }]Use PRIORITY blocking order \end{description} \end{Desc} \subsection{Function Documentation} \hypertarget{FORK_8h_a14}{ \index{FORK.h@{FORK.h}!FORK_create@{FORK\_\-create}} \index{FORK_create@{FORK\_\-create}!FORK.h@{FORK.h}} \subsubsection[FORK\_\-create]{\setlength{\rightskip}{0pt plus 5cm}int FORK\_\-create (\hyperlink{FORK_8h_a0}{FORK\_\-fcb} $\ast$ {\em fcb}, \hyperlink{FORK_8h_a6}{FORK\_\-cb\_\-rtn} {\em def\_\-handler}, \hyperlink{FORK_8h_a5}{FORK\_\-cb\_\-prm} {\em ctx}, \hyperlink{FORK_8h_a5}{FORK\_\-cb\_\-prm} {\em tmo\_\-ctx}, int {\em tmo}, \hyperlink{FORK_8h_a2}{FORK\_\-msg\_\-sys} $\ast$ {\em msg\_\-blks}, int {\em msg\_\-cnt}, \hyperlink{FORK_8h_a3}{FORK\_\-type} {\em type}, const TASK\_\-attr $\ast$ {\em attr})}} \label{FORK_8h_a14} Creates a FORK message que. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em fcb}]The FORK Control Block to initialize \item[{\em def\_\-handler}]The address of a default FORK handler. This routine will be called back in one of two circumstances. \par \par 1. The user does not provide an explicit \par routine queing the message. \par 2. A timeout occurs\par \par \item[{\em ctx}]Parameter passed transparently to the user's callback handler, except in the case of a timeout. \item[{\em 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.) \item[{\em msg\_\-blks}]A source of internal message blocks. This may be specified as NULL. \item[{\em msg\_\-cnt}]The number of {\em msg\_\-blks}. This may be specified as 0. Note that this parameter is ignored if {\em msg\_\-blks} is specified as NULL. \item[{\em type}]The blocking type to use when attempting allocate a message from the system queue. \item[{\em attributes}]The attributes to use when creating the FORK servicing task. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status\end{Desc} This routine creates the FORK message que and its associated task. The {\em def\_\-handler} will be used as the callback handler when a message is queued without an explicit handler, see \hyperlink{FORK_8h_a16}{FORK\_\-qsys}() and FORK\_\-quser(). It is also used when a timeout occurs. \hypertarget{FORK_8h_a15}{ \index{FORK.h@{FORK.h}!FORK_destroy@{FORK\_\-destroy}} \index{FORK_destroy@{FORK\_\-destroy}!FORK.h@{FORK.h}} \subsubsection[FORK\_\-destroy]{\setlength{\rightskip}{0pt plus 5cm}int FORK\_\-destroy (\hyperlink{FORK_8h_a0}{FORK\_\-fcb} $\ast$ {\em fcb})}} \label{FORK_8h_a15} Destroys a FORK que. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em fcb}]The Fork Control Block of the FORK que to destroy \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status\end{Desc} 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. \begin{Desc} \item[Warning: ]\par As with all delete operations, care must be taken to ensure it is safe to destroy the FORK que. \end{Desc} \hypertarget{FORK_8h_a13}{ \index{FORK.h@{FORK.h}!FORK_fcb_sizeof@{FORK\_\-fcb\_\-sizeof}} \index{FORK_fcb_sizeof@{FORK\_\-fcb\_\-sizeof}!FORK.h@{FORK.h}} \subsubsection[FORK\_\-fcb\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}FORK\_\-fcb\_\-sizeof (void)}} \label{FORK_8h_a13} Returns the size, in bytes, of a FORK Control Block. \begin{Desc} \item[Returns: ]\par The sizeof of a fork control block\end{Desc} 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. \hypertarget{FORK_8h_a16}{ \index{FORK.h@{FORK.h}!FORK_qsys@{FORK\_\-qsys}} \index{FORK_qsys@{FORK\_\-qsys}!FORK.h@{FORK.h}} \subsubsection[FORK\_\-qsys]{\setlength{\rightskip}{0pt plus 5cm}int FORK\_\-qsys (\hyperlink{FORK_8h_a0}{FORK\_\-fcb} $\ast$ {\em fcb}, \hyperlink{FORK_8h_a6}{FORK\_\-cb\_\-rtn} {\em handler}, void $\ast$ {\em contents}, int {\em tmo})}} \label{FORK_8h_a16} Ques a message using the internal FORK message blocks. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em fcb}]The Fork Control Block to que the message to \item[{\em handler}]A callback handler. This may be specified as NULL, in which case, the default handler established by \hyperlink{FORK_8h_a14}{FORK\_\-create}(), will handle the message. \item[{\em contents}]A single 32-bit value representing the message contents. \item[{\em 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. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status\end{Desc} 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 \hyperlink{FORK_8h_a17}{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. \hypertarget{FORK_8h_a17}{ \index{FORK.h@{FORK.h}!FORK_qusr@{FORK\_\-qusr}} \index{FORK_qusr@{FORK\_\-qusr}!FORK.h@{FORK.h}} \subsubsection[FORK\_\-qusr]{\setlength{\rightskip}{0pt plus 5cm}int FORK\_\-qusr (\hyperlink{FORK_8h_a0}{FORK\_\-fcb} $\ast$ {\em fcb}, \hyperlink{FORK_8h_a6}{FORK\_\-cb\_\-rtn} {\em handler}, \hyperlink{FORK_8h_a1}{FORK\_\-msg\_\-hdr} $\ast$ {\em msg\_\-hdr})}} \label{FORK_8h_a17} Ques a user composed message. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em fcb}]The Fork Control Block to que the message to \item[{\em handler}]A callback handler. This may be specified as NULL, in which case, the default handler established by \hyperlink{FORK_8h_a14}{FORK\_\-create}(), will handle the message. \item[{\em msg\_\-hdr}]Pointer to the message to que. It is mandatory that all queued messages are prefaced by a standard message header block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status\end{Desc} Ques a user defined message. This routine behaves in much the same manner as \hyperlink{FORK_8h_a16}{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.