[ViewVC] Diff of: cvs/libeio/eio.pod

Comparing libeio/eio.pod (file contents):
Revision 1.9 by root, Sun Jun 5 23:07:46 2011 UTC vs.
Revision 1.13 by root, Tue Jul 5 09:24:12 2011 UTC

 You submit a request by calling the relevant C<eio_TYPE> function with the
 required parameters, a callback of type C<int (*eio_cb)(eio_req *req)>
 (called C<eio_cb> below) and a freely usable C<void *data> argument.
-The return value will either be 0
+The return value will either be 0, in case something went really wrong
+(which can basically only happen on very fatal errors, such as C<malloc>
+returning 0, which is rather unlikely), or a pointer to the newly-created
+and submitted C<eio_req *>.
 The callback will be called with an C<eio_req *> which contains the
 results of the request. The members you can access inside that structure
 vary from request to request, except for:
 custom data value as C<data>.
 =head3 POSIX API WRAPPERS
 These requests simply wrap the POSIX call of the same name, with the same
-arguments:
+arguments. If a function is not implemented by the OS and cannot be emulated
+in some way, then all of these return C<-1> and set C<errorno> to C<ENOSYS>.
 =over 4
 =item eio_open      (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data)
+=item eio_truncate  (const char *path, off_t offset, int pri, eio_cb cb, void *data)
+=item eio_chown     (const char *path, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data)
+=item eio_chmod     (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
+=item eio_mkdir     (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
+=item eio_rmdir     (const char *path, int pri, eio_cb cb, void *data)
+=item eio_unlink    (const char *path, int pri, eio_cb cb, void *data)
 =item eio_utime     (const char *path, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data)
-=item eio_truncate  (const char *path, off_t offset, int pri, eio_cb cb, void *data)
-=item eio_chown     (const char *path, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data)
-=item eio_chmod     (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
-=item eio_mkdir     (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
-=item eio_rmdir     (const char *path, int pri, eio_cb cb, void *data)
-=item eio_unlink    (const char *path, int pri, eio_cb cb, void *data)
-=item eio_readlink  (const char *path, int pri, eio_cb cb, void *data) /* result=ptr2 allocated dynamically */
-=item eio_stat      (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
-=item eio_lstat     (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
-=item eio_statvfs   (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
 =item eio_mknod     (const char *path, mode_t mode, dev_t dev, int pri, eio_cb cb, void *data)
 =item eio_link      (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
 =item eio_symlink   (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
 =item eio_rename    (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
-=item eio_msync     (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
 =item eio_mlock     (void *addr, size_t length, int pri, eio_cb cb, void *data)
-=item eio_mlockall  (int flags, int pri, eio_cb cb, void *data)
 =item eio_close     (int fd, int pri, eio_cb cb, void *data)
 =item eio_sync      (int pri, eio_cb cb, void *data)
 Not surprisingly, pread and pwrite are not thread-safe on Darwin (OS/X),
 so it is advised not to submit multiple requests on the same fd on this
 horrible pile of garbage.
+=item eio_mlockall  (int flags, int pri, eio_cb cb, void *data)
+Like C<mlockall>, but the flag value constants are called
+C<EIO_MCL_CURRENT> and C<EIO_MCL_FUTURE>.
+=item eio_msync     (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
+Just like msync, except that the flag values are called C<EIO_MS_ASYNC>,
+C<EIO_MS_INVALIDATE> and C<EIO_MS_SYNC>.
+=item eio_readlink  (const char *path, int pri, eio_cb cb, void *data)
+If successful, the path read by C<readlink(2)> can be accessed via C<<
+req->ptr2 >> and is I<NOT> null-terminated, with the length specified as
+C<< req->result >>.
+  if (req->result >= 0)
+    {
+      char *target = strndup ((char *)req->ptr2, req->result);
+      free (target);
+    }
+=item eio_realpath  (const char *path, int pri, eio_cb cb, void *data)
+Similar to the realpath libc function, but unlike that one, result is
+C<0> on failure and the length of the returned path in C<ptr2> - this is
+similar to readlink.
+=item eio_stat      (const char *path, int pri, eio_cb cb, void *data)
+=item eio_lstat     (const char *path, int pri, eio_cb cb, void *data)
 =item eio_fstat     (int fd, int pri, eio_cb cb, void *data)
 Stats a file - if C<< req->result >> indicates success, then you can
 access the C<struct stat>-like structure via C<< req->ptr2 >>:
    EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2;
-=item eio_fstatvfs  (int fd, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
+=item eio_statvfs   (const char *path, int pri, eio_cb cb, void *data)
+=item eio_fstatvfs  (int fd, int pri, eio_cb cb, void *data)
 Stats a filesystem - if C<< req->result >> indicates success, then you can
 access the C<struct statvfs>-like structure via C<< req->ptr2 >>:
    EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2;
 (via the C<opendir>, C<readdir> and C<closedir> calls) and returns either
 the names or an array of C<struct eio_dirent>, depending on the C<flags>
 argument.
 The C<< req->result >> indicates either the number of files found, or
-C<-1> on error. On success, zero-terminated names can be found as C<< req->ptr2 >>,
+C<-1> on error. On success, null-terminated names can be found as C<< req->ptr2 >>,
 and C<struct eio_dirents>, if requested by C<flags>, can be found via C<<
 req->ptr1 >>.
 Here is an example that prints all the names:
 =item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
 Calls C<sync_file_range>. If the syscall is missing, then this is the same
 as calling C<fdatasync>.
+Flags can be any combination of C<EIO_SYNC_FILE_RANGE_WAIT_BEFORE>,
+C<EIO_SYNC_FILE_RANGE_WRITE> and C<EIO_SYNC_FILE_RANGE_WAIT_AFTER>.
 =back
 =head3 LIBEIO-SPECIFIC REQUESTS
 These requests are specific to libeio and do not correspond to any OS call.
 =back
 =head3 GROUPING AND LIMITING REQUESTS
+There is one more rather special request, C<eio_grp>. It is a very special
+aio request: Instead of doing something, it is a container for other eio
+requests.
+There are two primary use cases for this: a) bundle many requests into a
+single, composite, request with a definite callback and the ability to
+cancel the whole request with its subrequests and b) limiting the number
+of "active" requests.
+Further below you will find more dicussion of these topics - first follows
+the reference section detailing the request generator and other methods.
+=over 4
+=item eio_grp (eio_cb cb, void *data)
+Creates and submits a group request.
+=back
 #TODO
 /*****************************************************************************/
 /* groups */

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing libeio/eio.pod (file contents): Revision 1.9 by root, Sun Jun 5 23:07:46 2011 UTC vs. Revision 1.13 by root, Tue Jul 5 09:24:12 2011 UTC

Diff Legend

Comparing libeio/eio.pod (file contents):
Revision 1.9 by root, Sun Jun 5 23:07:46 2011 UTC vs.
Revision 1.13 by root, Tue Jul 5 09:24:12 2011 UTC