Usage Rules

Repeating Events

Each event that is scheduled executes at most one time. Repeating events are programmed as follows:

        foo_init()
        {
            ...
            evDetach( evSchedule( f, argument, INTERVAL ) );
        }
        
        
        f( Event self, void *arg )
        {
            actual work
            ...
            evDetach( evSchedule( f, arg, INTERVAL ) );
        }

Cancellable Events

The evIsCancelled routine is designed to make it easy to write events which might be cancelled before (or while) they run. It is common practice, for example, for a session to pass session state to a timeout event. The evIsCancelled notification can be used to synchronize the timeout event and the possible destruction of the session state. Here is an example:

        foo_destroy()
        {
            ...
            evCancel( state->timeoutEvent );
            ...
        }
        
        
        foo_timeout( Event self, void *state )
        {
           ...
           xPush(lls, retransmitMsg);
           /* 
            * xPush may have blocked -- check to see if state is 
            * still valid
            */
            if ( evIsCancelled(self) ) {
                return;
            }
            state->timeoutEvent = evSchedule( foo_timeout, arg, INTERVAL );
        }

Event Granularity

Although the event library uses an efficient representation (timing wheels) protocol programmers should be careful to not schedule events that are too fine grained. For example, in TCP, it is better to schedule one event for every session rather than for every message that is sent.