2.10 Polling for Messages

As we stated earlier, CONVERSE messages trigger handler functions when they arrive. In fact, for this to work, the processor must occasionally poll for messages. When the user starts CONVERSE, he can put it into one of several modes. In the normal mode, the message polling happens automatically. However user-calls-scheduler mode is designed to let the user poll manually. To do this, the user must use one of two polling functions: CmiDeliverMsgs, or CsdScheduler. CsdScheduler is more general, it will notice any CONVERSE event. CmiDeliverMsgs is a lower-level function that ignores all events except for recently-arrived messages. (In particular, it ignores messages in the scheduler queue). You can save a tiny amount of overhead by using the lower-level function. We recommend the use of CsdScheduler for all applications except those that are using only the lowest level of CONVERSE, the CMI. A third polling function, CmiDeliverSpecificMsg, is used when you know the exact event you want to wait for: it does not allow any other event to occur.

In each iteration, a scheduler first looks for any message that has arrived from another processor, and delivers it. If there isn't any, it selects a message from the locally enqueued messages, and delivers it.

void CsdScheduleForever(void)
Extract and deliver messages until the scheduler is stopped. Raises the idle handling converse signals. This is the scheduler to use in most CONVERSE programs.

int CsdScheduleCount(int n)
Extract and deliver messages until messages have been delivered, then return 0. If the scheduler is stopped early, return minus the number of messages delivered so far. Raises the idle handling converse signals.

void CsdSchedulePoll(void)
Extract and deliver messages until no more messages are available, then return. This is useful for running non-networking code when the networking code has nothing to do.

void CsdScheduler(int n)
If is zero, call CsdSchedulePoll. If is negative, call CsdScheduleForever. If is positive, call CsdScheduleCount().

int CmiDeliverMsgs(int MaxMsgs)
Retrieves messages from the network message queue and invokes corresponding handler functions for arrived messages. This function returns after either the network message queue becomes empty or after MaxMsgs messages have been retrieved and their handlers called. It returns the difference between total messages delivered and MaxMsgs. The handler is given a pointer to the message as its parameter.

void CmiDeliverSpecificMsg(int HandlerId)
Retrieves messages from the network queue and delivers the first message with its handler field equal to HandlerId. This functions leaves alone all other messages. It returns after the invoked handler function returns.

void CsdExitScheduler(void)
This call causes CsdScheduler to stop processing messages when control has returned back to it. The scheduler then returns to its calling routine.