eio 0.1

data/ext/libeio/eio.h

@@ -0,0 +1,336 @@
+/*
+ * libeio API header
+ *
+ * Copyright (c) 2007,2008,2009,2010,2011 Marc Alexander Lehmann <libeio@schmorp.de>
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modifica-
+ * tion, are permitted provided that the following conditions are met:
+ * 
+ *   1.  Redistributions of source code must retain the above copyright notice,
+ *       this list of conditions and the following disclaimer.
+ * 
+ *   2.  Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in the
+ *       documentation and/or other materials provided with the distribution.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MER-
+ * CHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO
+ * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPE-
+ * CIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+ * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTH-
+ * ERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+ * OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * Alternatively, the contents of this file may be used under the terms of
+ * the GNU General Public License ("GPL") version 2 or any later version,
+ * in which case the provisions of the GPL are applicable instead of
+ * the above. If you wish to allow the use of your version of this file
+ * only under the terms of the GPL and not to allow others to use your
+ * version of this file under the BSD license, indicate your decision
+ * by deleting the provisions above and replace them with the notice
+ * and other provisions required by the GPL. If you do not delete the
+ * provisions above, a recipient may use your version of this file under
+ * either the BSD or the GPL.
+ */
+
+#ifndef EIO_H_
+#define EIO_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stddef.h>
+#include <sys/types.h>
+
+typedef struct eio_req    eio_req;
+typedef struct eio_dirent eio_dirent;
+
+typedef int (*eio_cb)(eio_req *req);
+
+#ifndef EIO_REQ_MEMBERS
+# define EIO_REQ_MEMBERS
+#endif
+
+#ifndef EIO_STRUCT_STAT
+# define EIO_STRUCT_STAT struct stat
+#endif
+
+#ifndef EIO_STRUCT_STATVFS
+# define EIO_STRUCT_STATVFS struct statvfs
+#endif
+
+/* for readdir */
+
+/* eio_readdir flags */
+enum
+{
+  EIO_READDIR_DENTS         = 0x01, /* ptr2 contains eio_dirents, not just the (unsorted) names */
+  EIO_READDIR_DIRS_FIRST    = 0x02, /* dirents gets sorted into a good stat() ing order to find directories first */
+  EIO_READDIR_STAT_ORDER    = 0x04, /* dirents gets sorted into a good stat() ing order to quickly stat all files */
+  EIO_READDIR_FOUND_UNKNOWN = 0x80, /* set by eio_readdir when *_ARRAY was set and any TYPE=UNKNOWN's were found */
+
+  EIO_READDIR_CUSTOM1       = 0x100, /* for use by apps */
+  EIO_READDIR_CUSTOM2       = 0x200  /* for use by apps */
+};
+
+/* using "typical" values in the hope that the compiler will do something sensible */
+enum eio_dtype
+{
+  EIO_DT_UNKNOWN =  0,
+  EIO_DT_FIFO    =  1,
+  EIO_DT_CHR     =  2,
+  EIO_DT_MPC     =  3, /* multiplexed char device (v7+coherent) */
+  EIO_DT_DIR     =  4,
+  EIO_DT_NAM     =  5, /* xenix special named file */
+  EIO_DT_BLK     =  6,
+  EIO_DT_MPB     =  7, /* multiplexed block device (v7+coherent) */
+  EIO_DT_REG     =  8,
+  EIO_DT_NWK     =  9, /* HP-UX network special */
+  EIO_DT_CMP     =  9, /* VxFS compressed */
+  EIO_DT_LNK     = 10,
+  /*  DT_SHAD    = 11,*/
+  EIO_DT_SOCK    = 12,
+  EIO_DT_DOOR    = 13, /* solaris door */
+  EIO_DT_WHT     = 14,
+  EIO_DT_MAX     = 15  /* highest DT_VALUE ever, hopefully */
+};
+
+struct eio_dirent
+{
+  int nameofs; /* offset of null-terminated name string in (char *)req->ptr2 */
+  unsigned short namelen; /* size of filename without trailing 0 */
+  unsigned char type; /* one of EIO_DT_* */
+  signed char score; /* internal use */
+  ino_t inode; /* the inode number, if available, otherwise unspecified */
+};
+
+/* eio_msync flags */
+enum
+{
+  EIO_MS_ASYNC      = 1,
+  EIO_MS_INVALIDATE = 2,
+  EIO_MS_SYNC       = 4
+};
+
+/* eio_mtouch flags */
+
+enum
+{
+  EIO_MT_MODIFY     = 1
+};
+
+/* eio_sync_file_range flags */
+
+enum
+{
+  EIO_SYNC_FILE_RANGE_WAIT_BEFORE = 1,
+  EIO_SYNC_FILE_RANGE_WRITE       = 2,
+  EIO_SYNC_FILE_RANGE_WAIT_AFTER  = 4
+};
+
+typedef double eio_tstamp; /* feel free to use double in your code directly */
+
+/* the eio request structure */
+
+enum
+{
+  EIO_CUSTOM,
+  EIO_OPEN, EIO_CLOSE, EIO_DUP2,
+  EIO_READ, EIO_WRITE,
+  EIO_READAHEAD, EIO_SENDFILE,
+  EIO_STAT, EIO_LSTAT, EIO_FSTAT,
+  EIO_STATVFS, EIO_FSTATVFS,
+  EIO_TRUNCATE, EIO_FTRUNCATE,
+  EIO_UTIME, EIO_FUTIME,
+  EIO_CHMOD, EIO_FCHMOD,
+  EIO_CHOWN, EIO_FCHOWN,
+  EIO_SYNC, EIO_FSYNC, EIO_FDATASYNC,
+  EIO_MSYNC, EIO_MTOUCH, EIO_SYNC_FILE_RANGE,
+  EIO_MLOCK, EIO_MLOCKALL,
+  EIO_UNLINK, EIO_RMDIR, EIO_MKDIR, EIO_RENAME,
+  EIO_MKNOD, EIO_READDIR,
+  EIO_LINK, EIO_SYMLINK, EIO_READLINK,
+  EIO_GROUP, EIO_NOP,
+  EIO_BUSY
+};
+
+/* mlockall constants */
+enum
+{
+  EIO_MCL_CURRENT = 1,
+  EIO_MCL_FUTURE  = 2,
+};
+
+/* request priorities */
+
+enum {
+  EIO_PRI_MIN     = -4,
+  EIO_PRI_MAX     =  4,
+  EIO_PRI_DEFAULT =  0,
+};
+
+/* eio request structure */
+/* this structure is mostly read-only */
+/* when initialising it, all members must be zero-initialised */
+struct eio_req
+{
+  eio_req volatile *next; /* private ETP */
+
+  ssize_t result;  /* result of syscall, e.g. result = read (... */
+  off_t offs;      /* read, write, truncate, readahead, sync_file_range: file offset, mknod: dev_t */
+  size_t size;     /* read, write, readahead, sendfile, msync, mlock, sync_file_range: length */
+  void *ptr1;      /* all applicable requests: pathname, old name; readdir: optional eio_dirents */
+  void *ptr2;      /* all applicable requests: new name or memory buffer; readdir: name strings */
+  eio_tstamp nv1;  /* utime, futime: atime; busy: sleep time */
+  eio_tstamp nv2;  /* utime, futime: mtime */
+
+  int type;        /* EIO_xxx constant ETP */
+  int int1;        /* all applicable requests: file descriptor; sendfile: output fd; open, msync, mlockall, readdir: flags */
+  long int2;       /* chown, fchown: uid; sendfile: input fd; open, chmod, mkdir, mknod: file mode, sync_file_range: flags */
+  long int3;       /* chown, fchown: gid */
+  int errorno;     /* errno value on syscall return */
+
+  unsigned char flags; /* private */
+  signed char pri;     /* the priority */
+
+  void *data;
+  eio_cb finish;
+  void (*destroy)(eio_req *req); /* called when requets no longer needed */
+  void (*feed)(eio_req *req);    /* only used for group requests */
+
+  EIO_REQ_MEMBERS
+
+  eio_req *grp, *grp_prev, *grp_next, *grp_first; /* private */
+};
+
+/* _private_ request flags */
+enum {
+  EIO_FLAG_CANCELLED = 0x01, /* request was cancelled */
+  EIO_FLAG_PTR1_FREE = 0x02, /* need to free(ptr1) */
+  EIO_FLAG_PTR2_FREE = 0x04, /* need to free(ptr2) */
+  EIO_FLAG_GROUPADD  = 0x08  /* some request was added to the group */
+};
+
+/* undocumented/unsupported/private helper */
+/*void eio_page_align (void **addr, size_t *length);*/
+
+/* returns < 0 on error, errno set
+ * need_poll, if non-zero, will be called when results are available
+ * and eio_poll_cb needs to be invoked (it MUST NOT call eio_poll_cb itself).
+ * done_poll is called when the need to poll is gone.
+ */
+int eio_init (void (*want_poll)(void), void (*done_poll)(void));
+
+/* must be called regularly to handle pending requests */
+/* returns 0 if all requests were handled, -1 if not, or the value of EIO_FINISH if != 0 */
+int eio_poll (void);
+
+/* stop polling if poll took longer than duration seconds */
+void eio_set_max_poll_time (eio_tstamp nseconds);
+/* do not handle more then count requests in one call to eio_poll_cb */
+void eio_set_max_poll_reqs (unsigned int nreqs);
+
+/* set minimum required number
+ * maximum wanted number
+ * or maximum idle number of threads */
+void eio_set_min_parallel (unsigned int nthreads);
+void eio_set_max_parallel (unsigned int nthreads);
+void eio_set_max_idle     (unsigned int nthreads);
+void eio_set_idle_timeout (unsigned int seconds);
+
+unsigned int eio_nreqs    (void); /* number of requests in-flight */
+unsigned int eio_nready   (void); /* number of not-yet handled requests */
+unsigned int eio_npending (void); /* numbe rof finished but unhandled requests */
+unsigned int eio_nthreads (void); /* number of worker threads in use currently */
+
+/*****************************************************************************/
+/* convinience wrappers */
+
+#ifndef EIO_NO_WRAPPERS
+eio_req *eio_nop       (int pri, eio_cb cb, void *data); /* does nothing except go through the whole process */
+eio_req *eio_busy      (eio_tstamp delay, int pri, eio_cb cb, void *data); /* ties a thread for this long, simulating busyness */
+eio_req *eio_sync      (int pri, eio_cb cb, void *data);
+eio_req *eio_fsync     (int fd, int pri, eio_cb cb, void *data);
+eio_req *eio_fdatasync (int fd, int pri, eio_cb cb, void *data);
+eio_req *eio_msync     (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data);
+eio_req *eio_mtouch    (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data);
+eio_req *eio_mlock     (void *addr, size_t length, int pri, eio_cb cb, void *data);
+eio_req *eio_mlockall  (int flags, int pri, eio_cb cb, void *data);
+eio_req *eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data);
+eio_req *eio_close     (int fd, int pri, eio_cb cb, void *data);
+eio_req *eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data);
+eio_req *eio_read      (int fd, void *buf, size_t length, off_t offset, int pri, eio_cb cb, void *data);
+eio_req *eio_write     (int fd, void *buf, size_t length, off_t offset, int pri, eio_cb cb, void *data);
+eio_req *eio_fstat     (int fd, int pri, eio_cb cb, void *data); /* stat buffer=ptr2 allocated dynamically */
+eio_req *eio_fstatvfs  (int fd, int pri, eio_cb cb, void *data); /* stat buffer=ptr2 allocated dynamically */
+eio_req *eio_futime    (int fd, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data);
+eio_req *eio_ftruncate (int fd, off_t offset, int pri, eio_cb cb, void *data);
+eio_req *eio_fchmod    (int fd, mode_t mode, int pri, eio_cb cb, void *data);
+eio_req *eio_fchown    (int fd, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data);
+eio_req *eio_dup2      (int fd, int fd2, int pri, eio_cb cb, void *data);
+eio_req *eio_sendfile  (int out_fd, int in_fd, off_t in_offset, size_t length, int pri, eio_cb cb, void *data);
+eio_req *eio_open      (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data);
+eio_req *eio_utime     (const char *path, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data);
+eio_req *eio_truncate  (const char *path, off_t offset, int pri, eio_cb cb, void *data);
+eio_req *eio_chown     (const char *path, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data);
+eio_req *eio_chmod     (const char *path, mode_t mode, int pri, eio_cb cb, void *data);
+eio_req *eio_mkdir     (const char *path, mode_t mode, int pri, eio_cb cb, void *data);
+eio_req *eio_readdir   (const char *path, int flags, int pri, eio_cb cb, void *data); /* result=ptr2 allocated dynamically */
+eio_req *eio_rmdir     (const char *path, int pri, eio_cb cb, void *data);
+eio_req *eio_unlink    (const char *path, int pri, eio_cb cb, void *data);
+eio_req *eio_readlink  (const char *path, int pri, eio_cb cb, void *data); /* result=ptr2 allocated dynamically */
+eio_req *eio_stat      (const char *path, int pri, eio_cb cb, void *data); /* stat buffer=ptr2 allocated dynamically */
+eio_req *eio_lstat     (const char *path, int pri, eio_cb cb, void *data); /* stat buffer=ptr2 allocated dynamically */
+eio_req *eio_statvfs   (const char *path, int pri, eio_cb cb, void *data); /* stat buffer=ptr2 allocated dynamically */
+eio_req *eio_mknod     (const char *path, mode_t mode, dev_t dev, int pri, eio_cb cb, void *data);
+eio_req *eio_link      (const char *path, const char *new_path, int pri, eio_cb cb, void *data);
+eio_req *eio_symlink   (const char *path, const char *new_path, int pri, eio_cb cb, void *data);
+eio_req *eio_rename    (const char *path, const char *new_path, int pri, eio_cb cb, void *data);
+eio_req *eio_custom    (eio_cb execute, int pri, eio_cb cb, void *data);
+#endif
+
+/*****************************************************************************/
+/* groups */
+
+eio_req *eio_grp       (eio_cb cb, void *data);
+void eio_grp_feed      (eio_req *grp, void (*feed)(eio_req *req), int limit);
+void eio_grp_limit     (eio_req *grp, int limit);
+void eio_grp_add       (eio_req *grp, eio_req *req);
+void eio_grp_cancel    (eio_req *grp); /* cancels all sub requests but not the group */
+
+/*****************************************************************************/
+/* request api */
+
+/* true if the request was cancelled, useful in the invoke callback */
+#define EIO_CANCELLED(req)   ((req)->flags & EIO_FLAG_CANCELLED)
+
+#define EIO_RESULT(req)      ((req)->result)
+/* returns a pointer to the result buffer allocated by eio */
+#define EIO_BUF(req)         ((req)->ptr2)
+#define EIO_STAT_BUF(req)    ((EIO_STRUCT_STAT    *)EIO_BUF(req))
+#define EIO_STATVFS_BUF(req) ((EIO_STRUCT_STATVFS *)EIO_BUF(req))
+#define EIO_PATH(req)        ((char *)(req)->ptr1)
+
+/* submit a request for execution */
+void eio_submit (eio_req *req);
+/* cancel a request as soon fast as possible, if possible */
+void eio_cancel (eio_req *req);
+/* destroy a request that has never been submitted */
+void eio_destroy (eio_req *req);
+
+/*****************************************************************************/
+/* convinience functions */
+
+ssize_t eio_sendfile_sync (int ofd, int ifd, off_t offset, size_t count);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
+

data/ext/libeio/eio.pod

@@ -0,0 +1,303 @@
+=head1 NAME
+
+libeio - truly asynchronous POSIX I/O
+
+=head1 SYNOPSIS
+
+  #include <eio.h>
+
+=head1 DESCRIPTION
+
+The newest version of this document is also available as an html-formatted
+web page you might find easier to navigate when reading it for the first
+time: L<http://pod.tst.eu/http://cvs.schmorp.de/libeio/eio.pod>.
+
+Note that this library is a by-product of the C<IO::AIO> perl
+module, and many of the subtler points regarding requests lifetime
+and so on are only documented in its documentation at the
+moment: L<http://pod.tst.eu/http://cvs.schmorp.de/IO-AIO/AIO.pm>.
+
+=head2 FEATURES
+
+This library provides fully asynchronous versions of most POSIX functions
+dealing with I/O. Unlike most asynchronous libraries, this not only
+includes C<read> and C<write>, but also C<open>, C<stat>, C<unlink> and
+similar functions, as well as less rarely ones such as C<mknod>, C<futime>
+or C<readlink>.
+
+It also offers wrappers around C<sendfile> (Solaris, Linux, HP-UX and
+FreeBSD, with emulation on other platforms) and C<readahead> (Linux, with
+emulation elsewhere>).
+
+The goal is to enable you to write fully non-blocking programs. For
+example, in a game server, you would not want to freeze for a few seconds
+just because the server is running a backup and you happen to call
+C<readdir>.
+
+=head2 TIME REPRESENTATION
+
+Libeio represents time as a single floating point number, representing the
+(fractional) number of seconds since the (POSIX) epoch (somewhere near
+the beginning of 1970, details are complicated, don't ask). This type is
+called C<eio_tstamp>, but it is guaranteed to be of type C<double> (or
+better), so you can freely use C<double> yourself.
+
+Unlike the name component C<stamp> might indicate, it is also used for
+time differences throughout libeio.
+
+=head2 FORK SUPPORT
+
+Calling C<fork ()> is fully supported by this module. It is implemented in these steps:
+
+   1. wait till all requests in "execute" state have been handled
+      (basically requests that are already handed over to the kernel).
+   2. fork
+   3. in the parent, continue business as usual, done
+   4. in the child, destroy all ready and pending requests and free the
+      memory used by the worker threads. This gives you a fully empty
+      libeio queue.
+
+=head1 INITIALISATION/INTEGRATION
+
+Before you can call any eio functions you first have to initialise the
+library. The library integrates into any event loop, but can also be used
+without one, including in polling mode.
+
+You have to provide the necessary glue yourself, however.
+
+=over 4
+
+=item int eio_init (void (*want_poll)(void), void (*done_poll)(void))
+
+This function initialises the library. On success it returns C<0>, on
+failure it returns C<-1> and sets C<errno> appropriately.
+
+It accepts two function pointers specifying callbacks as argument, both of
+which can be C<0>, in which case the callback isn't called.
+
+=item want_poll callback
+
+The C<want_poll> callback is invoked whenever libeio wants attention (i.e.
+it wants to be polled by calling C<eio_poll>). It is "edge-triggered",
+that is, it will only be called once when eio wants attention, until all
+pending requests have been handled.
+
+This callback is called while locks are being held, so I<you must
+not call any libeio functions inside this callback>. That includes
+C<eio_poll>. What you should do is notify some other thread, or wake up
+your event loop, and then call C<eio_poll>.
+
+=item done_poll callback
+
+This callback is invoked when libeio detects that all pending requests
+have been handled. It is "edge-triggered", that is, it will only be
+called once after C<want_poll>. To put it differently, C<want_poll> and
+C<done_poll> are invoked in pairs: after C<want_poll> you have to call
+C<eio_poll ()> until either C<eio_poll> indicates that everything has been
+handled or C<done_poll> has been called, which signals the same.
+
+Note that C<eio_poll> might return after C<done_poll> and C<want_poll>
+have been called again, so watch out for races in your code.
+
+As with C<want_poll>, this callback is called while locks are being held,
+so you I<must not call any libeio functions form within this callback>.
+
+=item int eio_poll ()
+
+This function has to be called whenever there are pending requests that
+need finishing. You usually call this after C<want_poll> has indicated
+that you should do so, but you can also call this function regularly to
+poll for new results.
+
+If any request invocation returns a non-zero value, then C<eio_poll ()>
+immediately returns with that value as return value.
+
+Otherwise, if all requests could be handled, it returns C<0>. If for some
+reason not all requests have been handled, i.e. some are still pending, it
+returns C<-1>.
+
+=back
+
+For libev, you would typically use an C<ev_async> watcher: the
+C<want_poll> callback would invoke C<ev_async_send> to wake up the event
+loop. Inside the callback set for the watcher, one would call C<eio_poll
+()> (followed by C<ev_async_send> again if C<eio_poll> indicates that not
+all requests have been handled yet). The race is taken care of because
+libev resets/rearms the async watcher before calling your callback,
+and therefore, before calling C<eio_poll>. This might result in (some)
+spurious wake-ups, but is generally harmless.
+
+For most other event loops, you would typically use a pipe - the event
+loop should be told to wait for read readiness on the read end. In
+C<want_poll> you would write a single byte, in C<done_poll> you would try
+to read that byte, and in the callback for the read end, you would call
+C<eio_poll>. The race is avoided here because the event loop should invoke
+your callback again and again until the byte has been read (as the pipe
+read callback does not read it, only C<done_poll>).
+
+=head2 CONFIGURATION
+
+The functions in this section can sometimes be useful, but the default
+configuration will do in most case, so you should skip this section on
+first reading.
+
+=over 4
+
+=item eio_set_max_poll_time (eio_tstamp nseconds)
+
+This causes C<eio_poll ()> to return after it has detected that it was
+running for C<nsecond> seconds or longer (this number can be fractional).
+
+This can be used to limit the amount of time spent handling eio requests,
+for example, in interactive programs, you might want to limit this time to
+C<0.01> seconds or so.
+
+Note that:
+
+a) libeio doesn't know how long your request callbacks take, so the time
+spent in C<eio_poll> is up to one callback invocation longer then this
+interval.
+
+b) this is implemented by calling C<gettimeofday> after each request,
+which can be costly.
+
+c) at least one request will be handled.
+
+=item eio_set_max_poll_reqs (unsigned int nreqs)
+
+When C<nreqs> is non-zero, then C<eio_poll> will not handle more than
+C<nreqs> requests per invocation. This is a less costly way to limit the
+amount of work done by C<eio_poll> then setting a time limit.
+
+If you know your callbacks are generally fast, you could use this to
+encourage interactiveness in your programs by setting it to C<10>, C<100>
+or even C<1000>.
+
+=item eio_set_min_parallel (unsigned int nthreads)
+
+Make sure libeio can handle at least this many requests in parallel. It
+might be able handle more.
+
+=item eio_set_max_parallel (unsigned int nthreads)
+
+Set the maximum number of threads that libeio will spawn.
+
+=item eio_set_max_idle (unsigned int nthreads)
+
+Libeio uses threads internally to handle most requests, and will start and stop threads on demand.
+
+This call can be used to limit the number of idle threads (threads without
+work to do): libeio will keep some threads idle in preparation for more
+requests, but never longer than C<nthreads> threads.
+
+In addition to this, libeio will also stop threads when they are idle for
+a few seconds, regardless of this setting.
+
+=item unsigned int eio_nthreads ()
+
+Return the number of worker threads currently running.
+
+=item unsigned int eio_nreqs ()
+
+Return the number of requests currently handled by libeio. This is the
+total number of requests that have been submitted to libeio, but not yet
+destroyed.
+
+=item unsigned int eio_nready ()
+
+Returns the number of ready requests, i.e. requests that have been
+submitted but have not yet entered the execution phase.
+
+=item unsigned int eio_npending ()
+
+Returns the number of pending requests, i.e. requests that have been
+executed and have results, but have not been finished yet by a call to
+C<eio_poll>).
+
+=back
+
+
+=head1 ANATOMY OF AN EIO REQUEST
+
+#TODO
+
+
+=head1 HIGH LEVEL REQUEST API
+
+#TODO
+
+=back
+
+
+=head1 LOW LEVEL REQUEST API
+
+#TODO
+
+=head1 EMBEDDING
+
+Libeio can be embedded directly into programs. This functionality is not
+documented and not (yet) officially supported.
+
+Note that, when including C<libeio.m4>, you are responsible for defining
+the compilation environment (C<_LARGEFILE_SOURCE>, C<_GNU_SOURCE> etc.).
+
+If you need to know how, check the C<IO::AIO> perl module, which does
+exactly that.
+
+
+=head1 COMPILETIME CONFIGURATION
+
+These symbols, if used, must be defined when compiling F<eio.c>.
+
+=over 4
+
+=item EIO_STACKSIZE
+
+This symbol governs the stack size for each eio thread. Libeio itself
+was written to use very little stackspace, but when using C<EIO_CUSTOM>
+requests, you might want to increase this.
+
+If this symbol is undefined (the default) then libeio will use its default
+stack size (C<sizeof (long) * 4096> currently).  If it is defined, but
+C<0>, then the default operating system stack size will be used. In all
+other cases, the value must be an expression that evaluates to the desired
+stack size.
+
+=back
+
+
+=head1 PORTABILITY REQUIREMENTS
+
+In addition to a working ISO-C implementation, libeio relies on a few
+additional extensions:
+
+=over 4
+
+=item POSIX threads
+
+To be portable, this module uses threads, specifically, the POSIX threads
+library must be available (and working, which partially excludes many xBSD
+systems, where C<fork ()> is buggy).
+
+=item POSIX-compatible filesystem API
+
+This is actually a harder portability requirement: The libeio API is quite
+demanding regarding POSIX API calls (symlinks, user/group management
+etc.).
+
+=item C<double> must hold a time value in seconds with enough accuracy
+
+The type C<double> is used to represent timestamps. It is required to
+have at least 51 bits of mantissa (and 9 bits of exponent), which is good
+enough for at least into the year 4000. This requirement is fulfilled by
+implementations implementing IEEE 754 (basically all existing ones).
+
+=back
+
+If you know of other additional requirements drop me a note.
+
+
+=head1 AUTHOR
+
+Marc Lehmann <libeio@schmorp.de>.
+