*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->FreeBSD man pages -> evMainLoop (3)              



NAME    [Toc]    [Back]

     evConnFunc, evFileFunc, evStreamFunc, evTimerFunc, evWaitFunc, evCreate,
     evDestroy, evGetNext, evDispatch, evDrop, evMainLoop, evConsTime,
     evTimeSpec, evTimeVal, evAddTime, evSubTime, evCmpTime, evNowTime,
     evLastEventTime, evSetTimer, evResetTimer, 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 --
     event handling library

SYNOPSIS    [Toc]    [Back]

     #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);

     evCreate(evContext *ctx);

     evDestroy(evContext ctx);

     evGetNext(evContext ctx, evEvent *ev, int options);

     evDispatch(evContext ctx, evEvent ev);

     evDrop(evContext ctx, evEvent ev);

     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

     struct timespec
     evLastEventTime(evContext opaqueCtx);

     evSetTimer(evContext ctx, evTimerFunc func, void *uap,
	 struct timespec due, struct timespec inter, evTimerID *id);

     evResetTimer(evContext ctx, evTimerID id, evTimerFunc func, void *uap,
	 struct timespec due, struct timespec inter);

     evClearTimer(evContext ctx, evTimerID id);

     evSetIdleTimer(evContext opaqueCtx, evTimerFunc func, void *uap,
	 struct timespec max_idle, evTimerID *opaqueID);

     evTouchIdleTimer(evContext opaqueCtx, evTimerID id);

     evResetIdleTimer(evContext opaqueCtx, evTimerID id, evTimerFunc func,
	 void *uap, struct timespec max_idle);

     evClearIdleTimer(evContext opaqueCtx, evTimerID id);

     evWaitFor(evContext opaqueCtx, const void *tag, evWaitFunc func,
	 void *uap, evWaitID *id);

     evDo(evContext opaqueCtx, const void *tag);

     evUnwait(evContext opaqueCtx, evWaitID id);

     evDefer(evContext opaqueCtx, evWaitFunc func, void *uap);

     evSelectFD(evContext ctx, int fd, int eventmask, evFileFunc func,
	 void *uap, evFileID *id);

     evDeselectFD(evContext ctx, evFileID id);

     struct iovec
     evConsIovec(void *buf, size_t cnt);

     evWrite(evContext ctx, int fd, const struct iovec *iov, int cnt,
	 evStreamFunc func, void *uap, evStreamID *id);

     evRead(evContext ctx, int fd, const struct iovec *iov, int cnt,
	 evStreamFunc func, void *uap, evStreamID *id);

     evCancelRW(evContext ctx, evStreamID id);

     evTimeRW(evContext opaqueCtx, evStreamID id, evTimerID timer);

     evUntimeRW(evContext opaqueCtx, evStreamID id);

     evListen(evContext ctx, int fd, int maxconn, evConnFunc func, void *uap,
	 evConnID *id);

     evConnect(evContext ctx, int fd, void *ra, int ralen, evConnFunc func,
	 void *uap, evConnID *id);

     evCancelConn(evContext ctx, evConnID id);

     evHold(evContext ctx, evConnID id);

     evUnhold(evContext ctx, evConnID id);

     evTryAccept(evContext ctx, evConnID id, int *sys_errno);

     evSetDebug(evContext ctx, int level, FILE *output);

     evPrintf(const evContext_p *ctx, int level, const char *fmt, ...);



DESCRIPTION    [Toc]    [Back]

     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)
	   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

     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 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 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

     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

     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.

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

RETURN VALUES    [Toc]    [Back]

     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    [Toc]    [Back]

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

ERRORS    [Toc]    [Back]

     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    [Toc]    [Back]

     gettimeofday(2), select(2), fcntl(3), malloc(3), named(8), readv(3),

BUGS    [Toc]    [Back]

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

HISTORY    [Toc]    [Back]

     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.

4th Berkeley Distribution	 March 6, 1996	     4th Berkeley Distribution
[ Back ]
 Similar pages
Name OS Title
mvEvent IRIX Movie Playback Library event handling functions
vleventrecv IRIX event handling routines
vlnextevent IRIX VL event handling routines
vlcallbacks IRIX IRIS VL event handling routines
TIFFError IRIX library error handling interface
cplxerr IRIX error-handling function for the C++ Complex Math Library
vlxeventrecv IRIX VL Event Receive library extension for O2 workstations (now obsolete)
alPendingEvents IRIX Get total number of event queued in event queue
alCheckEvent IRIX Looks for an event in the event queue and retrieves it.
sat_eventtostr IRIX convert an audit event index to/from an audit event string
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service