mirror of
https://github.com/VibeDarling/darling-libkqueue.git
synced 2026-11-15 18:41:59 -10:00
git-svn-id: svn://svn.code.sf.net/p/libkqueue/code/trunk@328 fb4e3144-bc1c-4b72-a658-5bcd248dd7f7
175 lines
5.9 KiB
Plaintext
175 lines
5.9 KiB
Plaintext
m4_include(header.m4)
|
|
|
|
<h2>Usage</h2>
|
|
|
|
Here are some issues to be aware of when using this library under any platform:
|
|
<br/>
|
|
|
|
<ol>
|
|
|
|
<li>
|
|
The EVFILT_PROC filter is not implemented.
|
|
</li>
|
|
|
|
<li>
|
|
The EVFILT_AIO filter is not implemented.
|
|
</li>
|
|
|
|
<li>When a kqueue descriptor is closed, it's resources are not immediately reclaimed. Instead, they will be freed the next time that the <code>kqueue(2)</code> function is called.
|
|
</li>
|
|
|
|
<li>
|
|
A signal handler is implicitly installed when a EVFILT_SIGNAL kevent is created. For compatibility with kernel-based <code>kqueue(2)</code>, programs must ignore signals that will generate kevents. After an EVFILT_SIGNAL kevent is created, a program must not modify the disposition of the associated signal. The following example shows the proper way to handle SIGUSR1 with a kevent:
|
|
|
|
<pre>
|
|
int main() {
|
|
int kqfd;
|
|
struct kevent kev;
|
|
|
|
kqfd = kqueue();
|
|
signal(SIGUSR1, SIG_IGN);
|
|
EV_SET(&kev, SIGUSR1, EVFILT_SIGNAL, EV_ADD, 0, 0, NULL);
|
|
kevent(kqfd, &kev, 1, NULL, 0, NULL);
|
|
}
|
|
</pre>
|
|
</ol>
|
|
|
|
<h3>Linux</h3>
|
|
|
|
There are several compatibility issues to be aware of when using this library under Linux:<br/>
|
|
|
|
<ol>
|
|
|
|
<li>The NOTE_LOWAT flag is not supported. According to <i>socket(7)</i>,<br/>
|
|
<pre style="blockquote">
|
|
"The select(2) and poll(2) system calls currently do not respect the
|
|
SO_RCVLOWAT setting on Linux, and mark a socket readable when even a
|
|
single byte of data is available. A subsequent read from the socket
|
|
will block until SO_RCVLOWAT bytes are available."</pre>
|
|
</li>
|
|
|
|
<li>
|
|
The NOTE_REVOKE flag is not supported because Linux does not have
|
|
a <code>revoke(2)</code> system call.
|
|
</li>
|
|
|
|
<li>
|
|
When an EVFILT_SIGNAL event is generated, the <code>data</code> field
|
|
is set to 1 regardless of how many times the signal was received by the process.
|
|
</li>
|
|
|
|
<li>
|
|
When an EVFILT_READ event occurs on a listening socket, the <code>data</code> field is set to 1 regardless of how many pending connections are available.
|
|
|
|
<!--
|
|
<li>
|
|
The EVFILT_PROC filter only supports the NOTE_EXIT flag, and the <code>ident</code> field must contain the PID of a child of the current process. This filter is only suitable as an event-driven replacement for the <code>wait(2)</code> family of system calls.
|
|
</li>
|
|
-->
|
|
|
|
</ol>
|
|
|
|
<h3>Solaris</h3>
|
|
|
|
Here are the issues to be aware of when using this library under Solaris:<br/>
|
|
|
|
<ol>
|
|
|
|
<li>
|
|
Solaris 10 or newer is required. It should work with OpenSolaris and other Solaris-based distributions, but has not been tested.
|
|
</li>
|
|
|
|
<li>
|
|
When an EVFILT_READ event is generated, the <code>data</code> field
|
|
is set to 1 regardless of how many bytes are available to read.
|
|
</li>
|
|
|
|
<li>
|
|
When an EVFILT_TIMER event is generated, the <code>data</code> field
|
|
is set to 1 regardless of how many times the timer has been triggered.
|
|
</li>
|
|
|
|
<li>
|
|
The EVFILT_VNODE filter is not implemented. This will eventually be implemented
|
|
using the PORT_SOURCE_FILE mechanism described <a href="http://blogs.sun.com/praks/entry/file_events_notification">here</a>.
|
|
</li>
|
|
|
|
<li>The EVFILT_TIMER filter is implemented using high-resolution timers. In order to use high-resolution timers, the calling process must hold the PRIV_PROC_CLOCK_HIGHRES privilege. This privilege is not granted to ordinary users by default. It can be granted to individual users by running the following command as root:<br/>
|
|
<pre>
|
|
# usermod -K defaultpriv=basic,proc_clock_highres $user
|
|
</pre>
|
|
</ol>
|
|
|
|
<h3>BSD-based systems</h3>
|
|
|
|
There are some differences in the behavior of the <code>kevent(2)</code> system call across the various BSD-based operating systems. Here are some of the differences to be aware of:
|
|
|
|
<ol>
|
|
|
|
<li>FreeBSD 8 does not set the <i>EV_ADD</i> flag for kevents on the eventlist, but OpenBSD and Darwin do. This means you should never use the equality operator (==) to test the flags; use the logical AND operator instead.
|
|
</li>
|
|
|
|
<li>The <code>EVFILT_USER</code> filter behaves differently from other filters with respect to the <i>EV_ONESHOT</i> flag. All other filters will preserve the flag when the event is triggered and placed on the eventlist. The <code>EVFILT_USER</code> filter does not preserve this flag.
|
|
</li>
|
|
|
|
<li>
|
|
OpenBSD has the <i>NOTE_TRUNCATE</i> fflag, while FreeBSD and Darwin do not.
|
|
</li>
|
|
|
|
<li>
|
|
EVFILT_FS is undocumented and only available on FreeBSD and Darwin. Here is the <a href="http://adam.kungfoohampster.com/lists/cvs-all/msg71399.shtml">CVS commit log</a> which could be helpful to document this filter.
|
|
</li>
|
|
<!--
|
|
<li>
|
|
[TODO - Verify and check against 10.6] OS X 10.5 and earlier do not implement the <code>EVFILT_AIO</code> or <code>EVFILT_TIMER</code> filters.
|
|
</li>
|
|
-->
|
|
|
|
</ol>
|
|
|
|
<h2>Integration</h2>
|
|
|
|
<h3>Ordinary Makefile</h3>
|
|
|
|
Here are the steps to use libkqueue in your program if you use an ordinary Makefile:
|
|
|
|
<ol>
|
|
<li>Add <code>‘pkg-config libkqueue --cflags‘</code> to the CFLAGS variable.
|
|
<li>Add <code>‘pkg-config libkqueue --libs‘</code> to the LDADD variable.
|
|
<li>Add <code>#include <sys/event.h></code> to the source code.
|
|
</ol>
|
|
|
|
<h3>Autoconf/Automake/Libtool</h3>
|
|
|
|
If your program uses the GNU Autoconf/Automake/Libtool build system, the following steps will allow you to use libkqueue:
|
|
|
|
<ol>
|
|
|
|
<li>Add the following to <code>configure.ac</code>:
|
|
<pre>
|
|
#
|
|
# Prefer native kqueue(2); otherwise use libkqueue if present.
|
|
#
|
|
AC_CHECK_HEADER(sys/event.h, [],
|
|
[PKG_CHECK_MODULES(KQUEUE, libkqueue)]
|
|
)
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
Add the following to <code>Makefile.am</code> (assuming your program is named "foo"):
|
|
<pre>
|
|
foo_CFLAGS+=$(KQUEUE_CFLAGS)
|
|
foo_LDADD+=$(KQUEUE_LIBS)
|
|
</pre>
|
|
</li>
|
|
</ol>
|
|
|
|
Instead of using the <code>$(KQUEUE_LIBS)</code> variable, you could just add <code>libkqueue.la</code> to your programs LDADD variable.
|
|
|
|
<h3>Threads</h3>
|
|
|
|
libkqueue uses one or more helper threads, so all programs that link with libkqueue must also link against the pthreads library. Calls to <code>kqueue()</code> and <code>kevent()</code> are safe to be used from multiple threads.
|
|
|
|
m4_include(footer.m4)
|