ct_distribute_msg

The ct_distribute_msg function enqueues a message to be delivered to all threads that have subscribed to messages of the specified type.

Prototype:

int ct_distribute_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 ct_distribute_msg function is similar to ct_send_msg(), except that you don't specify any particular recipient.

A separate copy of the message will be delivered to every thread that is subscribed to messages of the specified type when the scheduler regains control. A thread may subscribe by calling ct_subscribe(), or cancel the subscription by calling ct_unsubscribe() or ct_unsubscribe_all().

If no threads are currently subscribed to the specified message type, Cheap Threads will silently discard the message.

If a thread is itself subscribed to the message it sends, it will be the last thread to receive the message.

Restrictions:

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

It is also possible to call ct_distribute_msg() before the scheduler runs. In that case, before the first thread runs, the scheduler will deliver the message to every thread subscribed to the specified message type at that time -- including threads that were subscribed after the message was enqueued.

After the scheduler has finished, calling ct_send_msg() is possible but not useful, since there is neither a scheduler to deliver the message nor any threads to receive it. Such a call will also leak memory, unless the application later calls ct_clear() to recover it.

Home