Fs_Dispatch — C Library Procedures

NAME

Fs_Dispatch, Fs_EventHandlerCreate, Fs_EventHandlerDestroy, Fs_EventHandlerData, Fs_EventHandlerChangeData, Fs_TimeoutHandlerCreate, Fs_TimeoutHandlerDestroy − stream event and timeout dispatcher routines.

SYNOPSIS

#include <fs.h>
void
Fs_Dispatch()
void
Fs_EventHandlerCreate(streamID, eventMask, proc, clientData)
void
Fs_EventHandlerDestroy(streamID)
void
Fs_EventHandlerData(streamID)
ClientData
Fs_EventHandlerChangeData(streamID, clientData)
#include <time.h>
Fs_TimeoutHandler
Fs_TimeoutHandlerCreate(time, relativeTime, proc, clientData)
void
Fs_TimeoutHandlerDestroy(token)

ARGUMENTS

int streamID (in) Specifies the stream to create an event handler for.

int eventMask (in) Mask indicating which events on streamID are to be processed by proc. Can be the bitwise OR of FS_READABLE, FS_WRITABLE and FS_EXCEPTION.

void (∗proc)() (in) Procedure to invoke when one of the events in eventMask occurs on a stream or when a timeout period expires.

ClientData clientData (in) Uninterpreted value passed to proc when it is invoked.

Time time (in) The absolute time when proc should be called or the time interval between calls to proc.

Boolean relativeTime (in) If TRUE, then time specifies a interval between calls to proc. If FALSE, then time specifies the absolute time when proc should be called.

Fs_TimeoutHandler token (in) A token to identify a particular timeout handler so it can be destroyed.

DESCRIPTION

These routines implement a dispatcher for events on streams and timeouts. An event occurs when the stream becomes readable, writable or has an exception condition pending. The dispatcher handles the details of waiting for events to occur on streams. When an event occurs, the dispatcher calls a routine supplied by the clients to deal with the event. Also, timeout handlers can be created so that a client-supplied routine can be called at a specific time or at regular intervals.

The dispatcher must be initialized by calling Fs_EventHandlerCreate and/or Fs_TimeoutHandlerCreate before Fs_Dispatch is called. Fs_Dispatch causes the process to wait until an event occurs on a stream or until a time-out occurs. At that point, it calls the appropriate handler. Once the handler completes, Fs_Dispatch returns to its caller. To have the dispatcher remain in control, do
while (TRUE) { Fs_Dispatch();
}

Fs_EventHandlerCreate is used to cause the procedure proc to be called when one or more of the events in eventMask occur on streamID. Only one procedure may be attached to a stream so it should be able to deal with all of the event types. Proc should be declared as: void proc(clientData, streamID, eventMask)
    ClientDataclientData;
    intstreamID;
    inteventMask; { } Fs_EventHandlerData can be used to get the clientData associated with streamID. Fs_EventHandlerChangeData can be used to change the clientData associated with streamID. The handler can be destroyed with Fs_EventHandlerDestroy.

In addition, a time-out routine can be setup to be called using Fs_TimeoutHandlerCreate. If relativeTime is TRUE, then time specifies an interval (e.g. one hour) from the current time that proc will be called at. When proc returns, it will automatically be rescheduled to be called at the next interval. If proc doesn’t need to be called again, it should call Fs_TimeoutHandlerDestroy. If relativeTime is FALSE, then time specifies a specific time (e.g., 3:15pm 17 Sept. 1987) that proc will be called at. Proc is called once — it is not automatically rescheduled to be called again. However, it could call Fs_TimeoutHandlerCreate to cause it to be called again. Proc should be declared as: void proc(clientData, time)
ClientDataclientData;
TimeTime; { } For example, to have ExampleRoutine called in 1 minute from now and every minute after that, the call should be:
Fs_TimeoutHandlerCreate(time_OneMinute, TRUE, ExampleRoutine, clientData); Fs_TimeoutHandlerCreate returns a token that must be saved if Fs_TimeoutHandlerDestroy is to be called.

KEYWORDS

callback, client data, dispatcher, stream ID, time