cuberite/libevent
1
0
Fork 0
mirror of https://github.com/cuberite/libevent.git synced 2025-09-19 09:15:34 -04:00
Code Issues Packages Projects Releases Wiki Activity

event.3

Browse Source 
svn:r184
This commit is contained in:
Niels Provos 2005-09-20 15:59:00 +00:00
parent 50f7aaef6b
commit 11a40d478e
2 changed files with 50 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
buffer.c
View File

@ -193,7 +193,7 @@ evbuffer_readline(struct evbuffer *buffer)
if (data[i] == '\r' || data[i] == '\n') if (data[i] == '\r' || data[i] == '\n')
break; break;
} }
if (i == len) if (i == len)
return (NULL); return (NULL);

98
event.3
View File

@ -46,12 +46,12 @@
.Nm event_priority_set , .Nm event_priority_set ,
.Nm evtimer_set , .Nm evtimer_set ,
.Nm evtimer_add , .Nm evtimer_add ,
.Nm evtimer_del .Nm evtimer_del ,
.Nm evtimer_pending , .Nm evtimer_pending ,
.Nm evtimer_initialized , .Nm evtimer_initialized ,
.Nm signal_set , .Nm signal_set ,
.Nm signal_add , .Nm signal_add ,
.Nm signal_del .Nm signal_del ,
.Nm signal_pending , .Nm signal_pending ,
.Nm signal_initialized , .Nm signal_initialized ,
.Nm bufferevent_new , .Nm bufferevent_new ,
@ -193,24 +193,26 @@ sets
to indicate that a signal has been received. to indicate that a signal has been received.
The application sets The application sets
.Va event_sigcb .Va event_sigcb
to a callback function. After the signal handler sets to a callback function.
After the signal handler sets
.Va event_gotsig , .Va event_gotsig ,
.Nm event_dispatch .Nm event_dispatch
will execute the callback function to process received signals. The will execute the callback function to process received signals.
callback returns 1 when no events are registered any more. It can The callback returns 1 when no events are registered any more.
return -1 to indicate an error to the It can return -1 to indicate an error to the
.Nm event .Nm event
library, causing library, causing
.Fn event_dispatch .Fn event_dispatch
to terminate with to terminate with
.Va errno .Va errno
set to set to
.Er EINTR. .Er EINTR .
.Pp .Pp
The The
.Nm event_loop .Nm event_loop
function provides an interface for single pass execution of pending function provides an interface for single pass execution of pending
events. The flags events.
The flags
.Va EVLOOP_ONCE .Va EVLOOP_ONCE
and and
.Va EVLOOP_NONBLOCK .Va EVLOOP_NONBLOCK
@ -243,14 +245,14 @@ argument indicating the type of event, and a
argument given in the argument given in the
.Fa arg .Fa arg
argument. argument.
The The
.Fa fd .Fa fd
indicates the file descriptor that should be monitored for events. indicates the file descriptor that should be monitored for events.
The events can be either The events can be either
.Va EV_READ , .Va EV_READ ,
.Va EV_WRITE , .Va EV_WRITE ,
or both. or both,
Indicating that an application can read or write from the file descriptor indicating that an application can read or write from the file descriptor
respectively without blocking. respectively without blocking.
.Pp .Pp
The function The function
@ -278,18 +280,18 @@ and
.Fn event_del .Fn event_del
and does not need to be reinitialized unless the function called and/or and does not need to be reinitialized unless the function called and/or
the argument to it are to be changed. the argument to it are to be changed.
However, when an However, when an
.Fa ev .Fa ev
structure has been added to libevent using structure has been added to libevent using
.Fn event_add .Fn event_add
the structure must persist until the event occurs (assuming the structure must persist until the event occurs (assuming
.Fa EV_PERSIST .Fa EV_PERSIST
is not set) or is removed is not set) or is removed
using using
.Fn event_del . .Fn event_del .
You may not reuse the same You may not reuse the same
.Fa ev .Fa ev
structure for multiple monitored descriptors; each descriptor structure for multiple monitored descriptors; each descriptor
needs its own needs its own
.Fa ev . .Fa ev .
.Pp .Pp
@ -297,13 +299,15 @@ The function
.Fn event_add .Fn event_add
schedules the execution of the schedules the execution of the
.Fa ev .Fa ev
event when the event specified in event when the event specified in
.Fn event_set .Fn event_set
occurs or in at least the time specified in the occurs or in at least the time specified in the
.Fa tv . .Fa tv .
If If
.Fa tv .Fa tv
is NULL, no timeout occurs and the function will only be called is
.Dv NULL ,
no timeout occurs and the function will only be called
if a matching event occurs on the file descriptor. if a matching event occurs on the file descriptor.
The event in the The event in the
.Fa ev .Fa ev
@ -335,7 +339,7 @@ require the caller to prepare an
structure. structure.
This function supports This function supports
.Fa EV_TIMEOUT , .Fa EV_TIMEOUT ,
.Fa EV_READ .Fa EV_READ ,
and and
.Fa EV_WRITE . .Fa EV_WRITE .
.Pp .Pp
@ -346,10 +350,10 @@ function can be used to check if the event specified by
is pending to run. is pending to run.
If If
.Va EV_TIMEOUT .Va EV_TIMEOUT
was specified and was specified and
.Fa tv .Fa tv
is not is not
.Va NULL , .Dv NULL ,
the expiration time of the event will be returned in the expiration time of the event will be returned in
.Fa tv . .Fa tv .
.Pp .Pp
@ -365,10 +369,9 @@ The functions
and and
.Fn evtimer_pending .Fn evtimer_pending
are abbreviations for common situations where only a timeout is required. are abbreviations for common situations where only a timeout is required.
The file descriptor passed will be -1, and the event type will be The file descriptor passed will be \-1, and the event type will be
.Va EV_TIMEOUT . .Va EV_TIMEOUT .
.Pp .Pp
.Pp
The functions The functions
.Fn signal_set , .Fn signal_set ,
.Fn signal_add , .Fn signal_add ,
@ -385,23 +388,23 @@ adds
.Va EV_PERSIST . .Va EV_PERSIST .
.Pp .Pp
It is possible to disable support for It is possible to disable support for
.Va epoll , kqueue , devpoll, poll .Va epoll , kqueue , devpoll , poll
or or
.Va select .Va select
by setting the environment variable by setting the environment variable
.Va EVENT_NOEPOLL , EVENT_NOKQUEUE , EVENT_NODEVPOLL, EVENT_NOPOLL .Va EVENT_NOEPOLL , EVENT_NOKQUEUE , EVENT_NODEVPOLL , EVENT_NOPOLL
or or
.Va EVENT_NOSELECT . .Va EVENT_NOSELECT ,
respectively.
By setting the environment variable By setting the environment variable
.Va EVENT_SHOW_METHOD , .Va EVENT_SHOW_METHOD ,
.Nm libevent .Nm libevent
displays the kernel notification method that it uses. displays the kernel notification method that it uses.
.Pp
.Sh EVENT PRIORITIES .Sh EVENT PRIORITIES
By default By default
.Nm libevent .Nm libevent
schedules all active events with the same priority. schedules all active events with the same priority.
However, sometime it is desirable to process some events with a higher However, sometimes it is desirable to process some events with a higher
priority than others. priority than others.
For that reason, For that reason,
.Nm libevent .Nm libevent
@ -421,7 +424,6 @@ By default,
.Nm libevent .Nm libevent
assigns the middle priority to all events unless their priority assigns the middle priority to all events unless their priority
is explicitly set. is explicitly set.
.Pp
.Sh THREAD SAFE EVENTS .Sh THREAD SAFE EVENTS
.Nm Libevent .Nm Libevent
has experimental support for thread-safe events. has experimental support for thread-safe events.
@ -429,24 +431,23 @@ When initializing the library via
.Fn event_init , .Fn event_init ,
an event base is returned. an event base is returned.
This event base can be used in conjunction with calls to This event base can be used in conjunction with calls to
.Fn event_base_set .Fn event_base_set ,
.Fn event_base_dispatch , .Fn event_base_dispatch ,
.Fn event_base_loop , .Fn event_base_loop ,
and and
.Fn event_base_loopexit . .Fn event_base_loopexit .
.Fn event_base_set .Fn event_base_set
should be called after preparing an event with should be called after preparing an event with
.Fn event_set , .Fn event_set ,
as as
.Fn event_set .Fn event_set
assigns the provided event to the most recently created event base. assigns the provided event to the most recently created event base.
.Pp
.Sh BUFFERED EVENTS .Sh BUFFERED EVENTS
.Nm libevent .Nm libevent
provides an abstraction on top of the regular event callbacks. provides an abstraction on top of the regular event callbacks.
This abstraction is called a This abstraction is called a
.Va "buffered event" . .Va "buffered event" .
A buffered event provides input and output buffer that get filled A buffered event provides input and output buffers that get filled
and drained automatically. and drained automatically.
The user of a buffered event no longer deals directly with the IO, The user of a buffered event no longer deals directly with the IO,
but instead is reading from input and writing to output buffers. but instead is reading from input and writing to output buffers.
@ -454,21 +455,21 @@ but instead is reading from input and writing to output buffers.
A new bufferevent is created by A new bufferevent is created by
.Fn bufferevent_new . .Fn bufferevent_new .
The parameter The parameter
.Fa "fd" .Fa fd
specifies the file descriptor from which data is read and written to. specifies the file descriptor from which data is read and written to.
This file descriptor is not allowed to be a This file descriptor is not allowed to be a
.Xr pipe 2 . .Xr pipe 2 .
The next three parameters are callbacks. The next three parameters are callbacks.
The read and write callback have the following form The read and write callback have the following form:
.Ft void .Ft void
.Fn "(*cb)" "struct bufferevent *bufev" "void *arg" .Fn "(*cb)" "struct bufferevent *bufev" "void *arg" .
The argument is specified by the fourth parameter The argument is specified by the fourth parameter
.Fa "cbarg" . .Fa "cbarg" .
.Pp .Pp
By default the buffered event is read enabled and will try to read By default the buffered event is read enabled and will try to read
from the file descriptor. from the file descriptor.
The write callback is executed whenever the output buffer is drained The write callback is executed whenever the output buffer is drained
below the write low watermark which is below the write low watermark, which is
.Va 0 .Va 0
by default. by default.
.Pp .Pp
@ -481,19 +482,19 @@ The
.Fn bufferevent_read .Fn bufferevent_read
function is used to read data from the input buffer. function is used to read data from the input buffer.
Both functions return the amount of data written or read. Both functions return the amount of data written or read.
.Pp
.Sh RETURN VALUES .Sh RETURN VALUES
Upon successful completion Upon successful completion
.Fn event_add .Fn event_add
and and
.Fn event_del .Fn event_del
return 0. return 0.
Otherwise, -1 is returned and the global variable errno is Otherwise, \-1 is returned and the global variable errno is
set to indicate the error. set to indicate the error.
.Sh SEE ALSO .Sh SEE ALSO
.Xr timeout 9 , .Xr kqueue 2 ,
.Xr poll 2 ,
.Xr select 2 , .Xr select 2 ,
.Xr kqueue 2 .Xr timeout 9
.Sh HISTORY .Sh HISTORY
The The
.Nm event .Nm event
@ -508,7 +509,6 @@ Support for real-time signals is due to Taral.
The The
.Nm event .Nm event
library was written by Niels Provos. library was written by Niels Provos.
.Pp
.Sh BUGS .Sh BUGS
This documentation is neither complete nor authoritative. This documentation is neither complete nor authoritative.
If you are in doubt about the usage of this API then If you are in doubt about the usage of this API then