10.4 Sending Messages to Threads

Threads may send messages to each other using CPathSend, which takes a complicated set of paramters. The parameters are most easily described by a context-free grammar:

void CPathSend(dest-clause, tag-clause, data-clause, end-clause)
Where:

    dest-clause :== CPATH_DEST ',' pathptr ',' index ',' index ',' ...
    tag-clause  :== CPATH_TAG ',' tag
    tag-clause  :== CPATH_TAGS ',' tag ',' tag ',' ... ',' 0
    tag-clause  :== CPATH_TAGVEC ',' numtags ',' tagvector
    data-clause :== CPATH_BYTES ',' numbytes ',' bufptr
    end-clause  :== CPATH_END

The symbols CPATH_DEST, CPATH_TAG, CPATH_TAGS, CPATH_TAGVEC, CPATH_BYTES, CPATH_END, and the comma are terminal symbols. The symbols descriptor, index, tag, numtags, tagvector, numbytes, and bufptr all represent C expressions.

The dest-clause specifies which array and which indices the message is to go to. One must provide a pointer to an array descriptor and a set of indices. Any index may be either a normal index, or the wildcard CPATH_ALL. Using the wildcard causes a multicast. The tag-clause provides several notations, all of which specify an array of one or more integer tags to be sent with the message. These tags can be used at the receiving end for pattern matching. The data-clause specifies the data to go in the message, as a sequence of bytes. The end-clause represents the end of the parameter list.

Messages sent with CPathSend can be received using CPathRecv, analyzed using CPathMsgDecodeBytes, and finally discarded with CPathMsgFree:

void *CPathRecv(tag-clause, end-clause)
The tag-clause and end-clause match the grammar for CPathSend. The function will wait until a message with the same tags shows up (it waits using the thread-blocking primitives, see CONVERSE threads). If any position in the CPathRecv tag-vector is CPATH_WILD, then that one position is ignored. CPathRecv returns an ``opaque CPath message''. The message contains the data somewhere inside it. The data can be located using CPathMsgDecodeBytes, below. The opaque CPath message can be freed using CPathMsgFree below.

void CPathMsgDecodeBytes(void *msg, int *len, void *bytes)
Given an opaque CPath message (as sent by CPathSend and returned by CPathRecv), this function will locate the data inside it. The parameter *len is filled in with the data length, and *bytes is filled in with a pointer to the data bytes. Bear in mind that once you free the opaque CPath message, this pointer is no longer valid.

void CPathMsgFree(void *msg)
Frees an opaque CPath message.