EVENTLIB(3)

NAME
evConnFunc, evFileFunc, evStreamFunc, evTimerFunc, evWaitFunc, evCreate, evDestroy, evGetNext, evDispatch, evDrop, evMainLoop, evConsTime, evTimeSpec, evTimeVal, evAddTime, evSubTime, evCmpTime, evNowTime, evUTCTime, evLastEventTime, evSetTimer, evResetTimer, evConfigTimer, evClearTimer, evSetIdleTimer, evTouchIdleTimer, evClearIdleTimer, evWaitFor, evDo, evUnwait, evDefer, evSelectFD, evDeselectFD, evWrite, evRead, evCancelRW, evTimeRW, evUntimeRW, evListen, evConnect, evCancelConn, evHold, evUnhold, evTryAccept, evConsIovec, evSetDebug, evPrintf, evInitID, evTestID, evGetOption, evSetOption - event handling library

SYNOPSIS
#include <isc/eventlib.h>
typedef void
*evConnFunc(evContext ctx, void *uap, int fd, const void *la, int lalen, const void *ra, int ralen);
typedef void
*evTimerFunc(evContext ctx, void *uap, struct timespec due, struct timespec inter);
typedef void
*evFileFunc(evContext ctx, void *uap, int fd, int eventmask);
typedef void
*evStreamFunc(evContext ctx, void *uap, int fd, int bytes);
typedef void
*evWaitFunc(evContext ctx, void *uap, const void *tag);
int
evCreate(evContext *ctx);
int
evDestroy(evContext ctx);
int
evGetNext(evContext ctx, evEvent *ev, int options);
int
evDispatch(evContext ctx, evEvent ev);
void
evDrop(evContext ctx, evEvent ev);
int
evMainLoop(evContext ctx);
struct timespec
evConsTime(int sec, int usec);
struct timespec
evTimeSpec(struct timeval tv);
struct timeval
evTimeVal(struct timespec ts);
struct timespec
evAddTime(struct timespec addend1, struct timespec addend2);
struct timespec
evSubTime(struct timespec minuend, struct timespec subtrahend);
struct timespec
evCmpTime(struct timespec a, struct timespec b);
struct timespec
evNowTime(void);
struct timespec
evUTCTime(void);
struct timespec
evLastEventTime(evContext opaqueCtx);
int
evSetTimer(evContext ctx, evTimerFunc func, void *uap, struct timespec due, struct timespec inter, evTimerID *id);
int
evResetTimer(evContext ctx, evTimerID id, evTimerFunc func, void *uap, struct timespec due, struct timespec inter);
int
evConfigTimer(evContext ctx, evTimerID id, const char *param, int value);
int
evClearTimer(evContext ctx, evTimerID id);
int
evSetIdleTimer(evContext opaqueCtx, evTimerFunc func, void *uap, struct timespec max_idle, evTimerID *opaqueID);
int
evTouchIdleTimer(evContext opaqueCtx, evTimerID id);
int
evResetIdleTimer(evContext opaqueCtx, evTimerID id, evTimerFunc func, void *uap, struct timespec max_idle);
int
evClearIdleTimer(evContext opaqueCtx, evTimerID id);
int
evWaitFor(evContext opaqueCtx, const void *tag, evWaitFunc func, void *uap, evWaitID *id);
int
evDo(evContext opaqueCtx, const void *tag);
int
evUnwait(evContext opaqueCtx, evWaitID id);
int
evDefer(evContext opaqueCtx, evWaitFunc func, void *uap);
int
evSelectFD(evContext ctx, int fd, int eventmask, evFileFunc func, void *uap, evFileID *id);
int
evDeselectFD(evContext ctx, evFileID id);
struct iovec
evConsIovec(void *buf, size_t cnt);
int
evWrite(evContext ctx, int fd, const struct iovec *iov, int cnt, evStreamFunc func, void *uap, evStreamID *id);
int
evRead(evContext ctx, int fd, const struct iovec *iov, int cnt, evStreamFunc func, void *uap, evStreamID *id);
int
evCancelRW(evContext ctx, evStreamID id);
int
evTimeRW(evContext opaqueCtx, evStreamID id, evTimerID timer);
int
evUntimeRW(evContext opaqueCtx, evStreamID id);
int
evListen(evContext ctx, int fd, int maxconn, evConnFunc func, void *uap, evConnID *id);
int
evConnect(evContext ctx, int fd, void *ra, int ralen, evConnFunc func, void *uap, evConnID *id);
int
evCancelConn(evContext ctx, evConnID id);
int
evHold(evContext ctx, evConnID id);
int
evUnhold(evContext ctx, evConnID id);
int
evTryAccept(evContext ctx, evConnID id, int *sys_errno);
void
evSetDebug(evContext ctx, int level, FILE *output);
void
evPrintf(const evContext_p *ctx, int level, const char *fmt, ...);
void
evInitID(*ID);
int
evTestID(ID);
int
evGetOption(evContext *ctx, const char *option, int *ret);
int
evSetOption(evContext *ctx, const char *option, int val);

DESCRIPTION
This library provides multiple outstanding asynchronous timers and I/O to a cooperating application. The model is similar to that of the X Toolkit, in that events are registered with the library and the application spends most of its time in the evMainLoop() function. If an application already has a main loop, it can safely register events with this library as long as it periodically calls the evGetNext() and evDispatch() functions. (Note that evGetNext() has both polling and blocking modes.)

The function evCreate() creates an event context which is needed by all the other functions in this library. All information used internally by this library is bound to this context, rather than to static storage. This makes the library “thread safe”, and permits other library functions to use events without disrupting the application's use of events.

The function evDestroy() destroys a context that has been created by evCreate(). All dynamic memory bound to this context will be freed. An implicit evTimerClear() will be done on all timers set in this event context. An implicit evDeselectFD() will be done on all file descriptors selected in this event context.

The function evGetNext() potentially waits for and then retrieves the next asynchronous event, placing it in the object of the ev pointer argument. The following options are available: EV_POLL, meaning that evGetNext() should not block, but rather return “-1” with errno set to EWOULDBLOCK if no events have occurred; EV_WAIT, which tells evGetNext() to block internally until the next event occurs; and EV_NULL, which tells evGetNext() that it should return a special “no-op” event, which is ignored by evDispatch() but handled correctly by evDrop(). EV_NULL can be necessary to the correct functioning of a caller-written equivilent to evMainLoop(), wherein perterbations caused by external system events must be polled for, and the default behaviour of internally ignoring such events is undesirable. Note that EV_POLL and EV_WAIT are mutually exclusive.

The function evDispatch() dispatches an event retrieved by evGetNext(). This usually involves calling the function that was associated with the event when the event was registered with evSetTimer(), evResetTimer(), or evSelectFD(). All events retrieved by evGetNext() must be given over to evDispatch() at some point, since there is some dynamic memory associated with each event.

The function evDrop() deallocates dynamic memory that has been allocated by evGetNext(). Calling evDispatch() has the side effect of calling evDrop(), but if you are going to drop the event rather than dispatch it, you will have to call evDrop() directly.

The function evMainLoop() is just:

    while ((x = evGetNext(opaqueCtx, &event, EV_WAIT)) == 0)
    	if ((x = evDispatch(opaqueCtx, event)) < 0)
    		break;
    return (x);

In other words, get events and dispatch them until an error occurs. One such error would be that all the events under this context become unregistered; in that event, there will be nothing to wait for and evGetNext() becomes an undefined operation.

The function evConsTime() is a constructor for “struct timespec” which allows these structures to be created and then passed as arguments to other functions without the use of temporary variables. (If C had inline constructors, there would be no need for this function.)

The functions evTimeSpec() and evTimeVal() are utilities which allow the caller to convert a “struct timeval” to a “struct timespec” (the function of evTimeSpec()) or vice versa (the function of evTimeVal()). Note that the name of the function indicates the type of the return value.

The function evAddTime() adds two “struct timespec” values and returns the result as a “struct timespec”.

The function evSubTime() subtracts its second “struct timespec” argument from its first “struct timespec” argument and returns the result as a “struct timespec”.

The function evCmpTime() compares its two “struct timespec” arguments and returns an “int” that is less than zero if the first argument specifies an earlier time than the second, or more than zero if the first argument specifies a later time than the second, or equal to zero if both arguments specify the same time.

The function evNowTime() returns a “struct timespec” which either describes the current time (using clock_gettime(2) or gettimeofday(2)), if successful, or has its fields set to zero, if there is an error. (In the latter case, the caller can check errno, since it will be set by gettimeofday(2).) The timestamp returned may not be UTC time if the "monotime" option has been enabled with evSetOption().

The function evUTCTime() is like evNowTime() except the result is always on the UTC timescale.

The function evLastEventTime() returns the “struct timespec” which describes the last time that certain events happened to the event context indicated by opaqueCtx. This value is updated by evCreate() and evGetNext() (upon entry and after select(2) returns); it is routinely compared with other times in the internal handling of, e.g., timers.

The function evSetTimer() registers a timer event, which will be delivered as a function call to the function specified by the func argument. The event will be delivered at absolute time due, and then if time inter is not equal to “evConsTime(0, 0)”, subsequently at intervals equal to time inter. As a special case, specifying a due argument equal to “evConsTime(0, 0)” means “due immediately”. The opaqueID argument, if specified as a value other than NULL, will be used to store the resulting “timer ID”, useful as an argument to evClearTimer(). Note that in a “one-shot” timer (which has an inter argument equal to “evConsTime(0,0)”) the user function func should deallocate any dynamic memory that is uniquely bound to the uap, since no handles to this memory will exist within the event library after a one-shot timer has been delivered.

The function evResetTimer() resets the values of the timer specified by id to the given arguments. The arguments are the same as in the description of evSetTimer() above.

The function evClearTimer() will unregister the timer event specified by id. Note that if the uap specified in the corresponding evSetTimer() call is uniquely bound to any dynamic memory, then that dynamic memory should be freed by the caller before the handle is lost. After a call to evClearTimer(), no handles to this uap will exist within the event library.

The function evConfigTimer() can be used to manipulate other aspects of a timer. Currently two modes are defined "rate" and "interval" which affect the way recurrent timers are scheduled. The default mode is "interval" where the event gets scheduled inter after last time it was run. If mode "rate" is selected the event gets scheduled inter after last time it was scheduled. For both "rate" and "interval" the numerical argument value is ignored.

The function evSetIdleTimer() is similar to (and built on) evSetTimer(); it registers an idle timer event which provides for the function call to func to occur. However, for an idle timer, the call will occur after at least “max_idle” time has passed since the time the idle timer was “last touched”; originally, this is set to the time returned by evLastEventTime() (described above) for the event context specified by opaqueCtx. This is a “one-shot” timer, but the time at which the func is actually called can be changed by recourse to evTouchIdleTimer() (described below). The pointer to the underlying “timer ID” is returned in opaqueID, if it is non-NULL.

The evTouchIdleTimer() function updates the idle timer associated with id, setting its idea of the time it was last accessed to the value returned by evLastEventTime() (described above) for the event context specified by opaqueCtx. This means that the idle timer will expire after at least max_idle time has passed since this (possibly new) time, providing a caller mechanism for resetting the call to the func associated with the idle timer. (See the description of evSetIdleTimer(), above, for information about func and max_idle.)

The evResetIdleTimer() function reschedules a timer and resets the callback function and its argument. Note that resetting a timer also ``touches'' it.

The evClearIdleTimer() function unregisters the idle timer associated with id. See the discussion under evClearTimer(), above, for information regarding caller handling of the uap associated with the corresponding evSetIdleTimer() call.

The function evWaitFor() places the function func on the given event context's wait queue with the associated (possibly NULL) “tag”; if id is non-NULL, then it will contain the “wait ID” associated with the created queue element.

The function evDo() marks all of the “waiting” functions in the given event context's wait queue with the associated (possibly NULL) “tag” as runnable. This places these functions in a “done” queue which will be read by evGetNext().

The function evUnwait() will search for the “wait ID” id in the wait queue of the given event context; if an element with the given id is not found, then the “done” queue of that context is searched. If found, the queue element is removed from the appropriate list.

The function evDefer() causes a function (specified as func, with argument uap) to be dispatched at some later time. Note that the tag argument to func will always be NULL when dispatched.

The function evSelectFD() registers a file I/O event for the file descriptor specified by fd. Bits in the eventmask argument are named EV_READ, EV_WRITE, and EV_EXCEPT. At least one of these bits must be specified. If the id argument is not equal to NULL, it will be used to store a unique ``file event ID'' for this event, which is useful in subsequent calls to evDeselectFD(). A file descriptor will be made nonblocking using the O_NONBLOCK flag with fcntl(2) on its first concurrent registration via evSelectFD(). An evSelectFD() remains in effect until cancelled via evDeselectFD().

The function evDeselectFD() unregisters the ``file event'' specified by the id argument. If the corresponding uap uniquely points to dynamic memory, that memory should be freed before its handle is lost, since after a call to evDeselectFD(), no handles to this event's uap will remain within the event library. A file descriptor will be taken out of nonblocking mode (see O_NONBLOCK and fcntl(2)) when its last event registration is removed via evDeselectFD(), if it was in blocking mode before the first registration via evSelectFD().

The function evConsIovec() is a constructor for a single struct iovec structure, which is useful for evWrite() and evRead().

The functions evWrite() and evRead() start asynchronous stream I/O operations on file descriptor fd. The data to be written or read is in the scatter/gather descriptor specified by iov and cnt. The supplied function func will be called with argument uap when the I/O operation is complete. If id is not NULL, it will be filled a with the stream event identifier suitable for use with evCancelRW().

The function evCancelRW() extinguishes an outstanding evWrite() or evRead() call. System I/O calls cannot always be cancelled, but you are guaranteed that the func function supplied to evWrite() or evRead() will not be called after a call to evCancelRW(). Care should be taken not to deallocate or otherwise reuse the space pointed to by the segment descriptors in iov unless the underlying file descriptor is closed first.

The function evTimeRW() sets the stream associated with the given stream ID “id” to have the idle timer associated with the timer ID “timer”.

The function evUntimeRW() says that the stream associated with the given stream ID “id” should ignore its idle timer, if present.

The functions evListen(), evConnect(), and evCancelConn() can be used to manage asynchronous incoming and outgoing socket connections. Sockets to be used with these functions should first be created with socket(2) and given a local name with bind(2). It is extremely unlikely that the same socket will ever be useful for both incoming and outgoing connections. The id argument to evListen() and evConnect() is either NULL or the address of a evFileID variable which can then be used in a subsequent call to evCancelConn().

After a call to evListen(), each incoming connection arriving on fd will cause func to be called with uap as one of its arguments. evConnect() initiates an outgoing connection on fd to destination address ra (whose length is ralen). When the connection is complete, func will be called with uap as one of its arguments. The argument fd to *func() will be -1 if an error occurred that prevented this connection from completing successfully. In this case errno() will have been set and the socket described by fd will have been closed. The evCancelConn() function will prevent delivery of all pending and subsequent events for the outstanding connection. The evHold() function will suspend the acceptance of new connections on the listener specified by id. Connections will be queued by the protocol stack up to the system's limit. The evUnhold() function will reverse the effects of evHold(), allowing incoming connections to be delivered for listener id. The evTryAccept() function will poll the listener specified by id, accepting a new connection if one is available, and queuing a connection event for later retrieval by evGetNext(). If the connection event queued is an accept error(), sys_errno will contain the error code; otherwise it will be zero. All connection events queued by evTryAccept() will be delivered by evGetNext() before a new select is done on the listener.

The function evSetDebug() sets the debugging level and diagnostic output file handle for an event context. Greater numeric levels will result in more verbose output being sent to the output FILE during program execution.

The function evPrintf() prints a message with the format “fmt” and the following arguments (if any), on the output stream associated with the event context pointed to by ctx. The message is output if the event context's debug level is greater than or equal to the indicated level.

The function evInitID() will initialize an opaque “evConn ID”, “evFile ID”, “evStream ID”, “evTimer ID”, “evWait ID”, “evContext”, or “evEvent”, which is passed by reference to a state which evTestID() will recognize. This is useful to make a handle as "not in use".

The function evTestID() will examine an opaque ID and return “TRUE” only if it is not in its initialized state.

The functions evGetOption() and evSetOption() can be used to inspect and modify options. Currently there is only one option, "monotime" and it is global for all instances of eventlib so the ctx argument must be passed as NULL.

The default value for the "monotime" option is zero which selects the UTC timescale. When set to a value of one, eventlib will use the CLOCK_MONOTONIC timescale from clock_gettime instead. The CLOCK_MONOTONIC timescale is never stepped and should run at a rate as close to TAI as possible, so it is unaffected when the system clock is set. If timerevents should run at a predictable rate, set the value to one, of they should run at a predictable time of day, leave it at zero. If the CLOCK_MONOTONIC timescale is not available on the system, attempts to set/get this option will fail.

RETURN VALUES
All the functions whose return type is “int” use the standard convention of returning zero (0) to indicate success, or returning “-1” and setting errno to indicate failure.

FILE
heap.h, which is in the src/lib/isc directory of the current BIND distribution.

ERRORS
The possible values for errno when one of the “int” functions in this library returns “-1” include those of the Standard C Library and also:

[EINVAL]
    Some function argument has an unreasonable value.

[EINVAL]
    The specified file descriptor has an integer value greater than the default FD_SETSIZE, meaning that the application's limit is higher than the library's.

[ENOENT]
    The specified “event ID” does not exist.

[EWOULDBLOCK]
    No events have occurred and the EV_POLL option was specified.

[EBADF]
    The specified signal was unblocked outside the library.

SEE ALSO
gettimeofday(2), select(2), fcntl(3), malloc(3), @INDOT@named(@SYS_OPS_EXT@), readv(3), writev(3).

BUGS
This huge man page needs to be broken up into a handful of smaller ones.

HISTORY
The eventlib library was designed by Paul Vixie with excellent advice from his friends and with tips 'o the cap to the X Consortium and the implementors of DEC SRC Modula-3.