Another common activity for protocols is to schedule an event to happen some time in the future. To understand how a protocol might use such events, consider the situation where a network sometimes fails to deliver a message to the destination. A protocol that wants to offer a reliable channel across such a network might, after sending a message, schedule an event that is to occur after a certain period of time. If the protocol has not received confirmation that the message was delivered by the time this event happens, then the protocol retransmits the message. In this case, the event implements a timeout; we will see an example of a protocol that uses timeouts in a later section. Note that another use for events is to perform periodic maintenance functions, such as garbage collection.
This section introduces the interface to the x-kernel's event manager, which allows protocols to schedule a procedure that is to be called after a period of time. (See [6] for a description of the algorithm and data structures that underly the event manageer.)
The event manager defines a single object---the Event---and the following operation:
Event evSchedule(EvFunc function, void *argument, int time)
This operation schedules an event that executes the specified function with the given argument after a delay of time microseconds. ( EvFunc is a pointer to function that returns a void.) A handle to the event is returned, and this can be used to cancel the event at some later time. When an event fires, a new process is created to run the specified function; that is, the event runs asynchronously with respect to the rest of the system. Since each event occurs at most one time, if the protocol wants a repeating event, then the next incarnation of the event should be re-scheduled using evSchedule as the last action taken in the event handling function.
A second operation:
EvCancelReturn evCancel(Event event)
is used to cancel the given Event. evCancel is called, for example, because a source has received confirmation that a message it sent was successfully delivered, and so there is no reason for it to retransmit the message. The operation's return value, as defined by the enumeration type EvCancelReturn, is set to EVENT_FINISHED if the event has already happened, EVENT_RUNNING if the event is currently running, and EVENT_CANCELLED if the event has not run and can be guaranteed to not run.
Finally, the following operation releases a handle to an event. As soon as function completes, the internal resources associated with the event are freed:
void evDetach(Event event)