Cheap Threads: ct_broadcast

ct_broadcast_msg

The ct_broadcast_msg function sends a message to all threads, including the sender.

Prototype:

int ct_broadcast_msg( Ct_msgtype type, void * pData, size_t len );

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.

Return Value:

CT_OKAY if successful, or CT_ERROR if not.

Discussion:

The interface of this function is similar to that of ct_distribute_msg().

ct_distribute_msg() enqueues the message for later delivery. However the message is not actually delivered until the sending thread returns control to the scheduler. Consequently if a thread not only broadcasts a message but also creates a new thread, before or after sending the message, the new thread will receive the message.

Restrictions:

Normally ct_broadcast_msg() will be called from a thread or user exit, i.e. while the scheduler is running.

You can also call ct_broadcast_msg() before the scheduler runs. In that case, any thread created before the scheduler starts will receive the message the first time it runs.

After the scheduler has finished, calling ct_broadcast_msg() is possible but pointless, since there is neither a scheduler to deliver the message nor a thread to receive it. Such a call will also leak memory unless you call ct_clear() later to recover it.

Home