Cheap Threads: ct_send

ct_send_msg

The ct_send_msg function enqueues a message to be sent to a specified thread.

Prototype:

int ct_send_msg( Ct_msgtype type, void * pData, size_t len,
    Ct_handle dest );

Parameters:

type: A non-zero integer designating the type of message. Zero is reserved to denote the absence of a message. Otherwise, the message types are defined by the application.
pData: If not NULL, this pointer points to zero or more bytes of data to be sent with the message.
len: How many bytes of data to send. If pData is NULL, then len must be zero. For Embedded Cheap Threads, len must not exceed CT_MSG_BUF_LEN, as #defined in ct.h. If pData is not null, then it is silly, but harmless, for len to be zero.
dest: Identifies the thread to which the message should be sent. This value must have been returned from ct_create_thread(), ct_create_sleeping_thread(), or ct_self(). Otherwise the results are undefined.

Return Value:

CT_OKAY if successful, or CT_ERROR if not.

Discussion:

The message is sent only to the designated recipient, even if other threads are subscribed to messages of the same type.

If there are data to be sent with the message, ct_send_msg() makes a copy of the data. After calling ct_send_msg() the sending thread may overwrite or destroy the original data.

If the destination thread has expired, Cheap Threads silently discards the message.

A thread may send a message to itself, but it will not receive the message until the next time it runs. Except for such a message-to-self, Cheap Threads guarantees that all recipients will run before the sending thread runs again.

Messaging is described in detail elsewhere.

Restrictions:

Normally ct_send_msg() will be called from a thread or user exit, i.e. while the scheduler is running. It is also possible to call ct_send_msg() before the scheduler runs, provided that the destination thread has already been created.

After the scheduler has finished, calling ct_send_msg() invokes undefined behavior.

Home