ct_distribute_enq

The ct_distribute_enq function enqueues all threads that have subscribed to messages of the specified type, for execution at the highest priority.

Prototype:

int ct_distribute_msg( Ct_msgtype type );

Parameters:

type
A non-zero integer designating a message type. Zero is reserved to denote the absence of a message. Otherwise, the message types are defined by the application.

Return Value:

CT_OKAY if successful, or CT_ERROR if not.

Discussion:

When the scheduler regains control, it enqueues every thread that is subscribed to messages of the specified type in the highest priority run qeueue. If no threads are subscribed to the specified message type at that time, the scheduler will silently ignore the enqueue request. A thread may subscribe by calling ct_subscribe(), or cancel the subscription by calling ct_unsubscribe() or ct_unsubscribe_all().

This function is similar to ct_enqueue(), except that you specify a message type instead of a particular thread. It is also similar to ct_distribute_msg(), except that it doesn't deliver any messages. As a result, the threads enqueued don't need to examine or dequeue a message.

The term "message type" is a bit misleading in this context because no message is involved. The message type merely identifies a class of threads.

If a thread is itself subscribed to the specified message type, it will be the last thread enqueued.

Restrictions:

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

It is also possible to call ct_distribute_enq() before the scheduler runs. In that case, before the first thread runs, the scheduler will enqueue every thread subscribed to the specified message type -- including threads that were subscribed after the call to ct_enqueue().

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

Home