rciSend(3)

NAME
rciSend, rciReceive, rciFlush
 -- RCI message passing primitives.

USAGE
rciSend (taskMask, buffer, size)
   unsigned long taskMask;
   const char *buffer;
   int size;

rciReceive (taskMask, buffer, size, sender)
   unsigned long taskMask;
   char *buffer;
   int size;
   RCI_DESC **sender;

rciFlush (taskMask)
   unsigned long taskMask;

ARGUMENTS

taskMask --

    Bitmask describing tasks to which messages are to be sent, or from which they are to be received.

buffer --
    Buffer containing the message to be sent, or into which it is to be received.

size --
    Numbers of bytes to be sent, or maximum number of bytes to be received.

sender --
    (Optional) pointer through which is returned the task descriptor of the task which sent the received message.

DESCRIPTION
These routines may be called from any part of an RCI program.

rciSend() sends a message of size bytes contained in buffer to the task described by taskMask. Only one target may (presently) be specified. The task code for a particular task may be found from the task descriptor with the macro TASKMASK(td). The function returns the number of bytes sent (which will equal size unless there was an error). The largest message that can be sent is defined by MAX_MSG. The size of the pool used to allocate message buffer space is MSG_POOL_SIZE. All messages use a minimum internal buffer size defined by MIN_MSG.

rciReceive() receives a message into buffer, which is truncated to size, if necessary. The message is received from any sending task described by taskMask. Non-existent task specifications are ignored, so (unsigned long)~0 may be used to request a message from any task. The function returns the number of bytes received, or 0 if there are no messages.

rciFlush() flushes all incoming messages sent by the tasks specified in the argument taskMask. Again, (unsigned long)~0 may be used to denote all tasks.

DIAGNOSTICS

rciSend() returns -1 in the event of an error, and places one of the following codes on the errorStack (q.v.):

ETooMany --
    The sending task currently has more then MAX_OUTSTANDING_MSGS outstanding (i.e., sent but not yet read by the target tasks), or the input queue for the target task itself is full.

EMemory --
    Insufficient memory to buffer the message itself.

EDescriptor --
    The mask describing the target task is invalid (if this mask is 0, then rciSend() will return 0 instead of an error).

Errors detected by other functions are internal, and when detected will result in a program abort.

SEE ALSO
rciCreate(3).