These are old aliases for event_get_fd and event_get_signal, and they
haven't been the preferred way of doing things since 2.0.1-alpha.
For a while, we made them use struct event if it was included, but call
event_get_(fd|signal) if it wasn't. This was entirely too cute.
This is necessary or useful for a few reasons:
1) Sometimes applications will add and delete the same event more
than once between calls to dispatch. Processing these changes
immediately is needless, and potentially expensive (especially
if we're on a system that makes one syscall per changed event).
Yes, this actually happens in practice for nonpathological
code, such as in cases where the user's callback conditionally
re-adds a non-persistent event, or where draining a buffer
turns off writing and invokes a user callback which adds more
data which in turn re-enabled writing.
2) Sometimes we can coalesce multiple changes on the same fd into
a single syscall if we know about them in advance. For
example, epoll can do an add and a delete at the same time, but
only if we have found out about both of them before we tell
epoll.
3) Sometimes adding an event that we immediately delete can cause
unintended consequences: in kqueue, this makes pending events
get reported spuriously.
I've gone through everything that it declared to see where it was used,
and it seems that we probably don't need it anywhere.
Here's what it declared, and why I think we're okay dropping it.
o struct timeval {}
(Used all over, and we can't really get away with declaring it ourselves;
we need the same definition the system uses. If we can't find struct
timeval, we're pretty much sunk.)
o struct timespec {}
(Used in event.c, evdns.c, kqueue.c, evport.c. Of these,
kqueue.c and event.c include sys/_time.h. event.c conditions its use on
_EVENT_HAVE_CLOCK_GETTIME, and kqueue() only works if timespec is defined.)
o TIMEVAL_TO_TIMESPEC
(Used in kqueue.c, but every place with kqueue has sys/time.h)
o struct timezone {}
(event2/util.h has a forward declaration; only evutil.c references it and
doesn't look at its contents.)
o timerclear, timerisset, timercmp, timeradd, timersub
(Everything now uses the evutil_timer* variants.)
o ITIMER_REAL, ITIMER_VIRTUAL, ITIMER_PROF, struct itemerval
(These are only used in test/regress.c, which does not include _time.h)
o CLOCK_REALTIME
(Only used in evdns.c, which does not include _time.h)
o TIMESPEC_TO_TIMEVAL
o DST_*
o timespecclear, timespecisset, timespeccmp, timespecadd, timespecsub
o struct clockinfo {}
o CLOCK_VIRTUAL, CLOCK_PROF
o TIMER_RELTIME, TIMER_ABSTIME
(unused)
svn:r1494
Basically, we suppress the notification when an event is added or deleted
and:
- The event has no fd, or there is no change in whether we are
reading/writing on the event's fd.
- The event has no timeout, or adding the event did not make the earliest
timeout become earlier.
This should be a big efficiency win in applications with multiple threads and
lots of timeouts.
svn:r1439
a) this is 2009
b) niels and nick have been comaintainers for a while
c) saying "all rights reserved" when you then go on to explicitly
disclaim some rights is sheer cargo-cultism.
svn:r1065
