deps/libeio/eio.h

   1 /*
   2  * libeio API header
   3  *
   4  * Copyright (c) 2007,2008,2009,2010 Marc Alexander Lehmann <libeio@schmorp.de>
   5  * All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without modifica-
   8  * tion, are permitted provided that the following conditions are met:
   9  *
  10  *   1.  Redistributions of source code must retain the above copyright notice,
  11  *       this list of conditions and the following disclaimer.
  12  *
  13  *   2.  Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in the
  15  *       documentation and/or other materials provided with the distribution.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
  18  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MER-
  19  * CHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO
  20  * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPE-
  21  * CIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  22  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  23  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  24  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTH-
  25  * ERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  26  * OF THE POSSIBILITY OF SUCH DAMAGE.
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of
  29  * the GNU General Public License ("GPL") version 2 or any later version,
  30  * in which case the provisions of the GPL are applicable instead of
  31  * the above. If you wish to allow the use of your version of this file
  32  * only under the terms of the GPL and not to allow others to use your
  33  * version of this file under the BSD license, indicate your decision
  34  * by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL. If you do not delete the
  36  * provisions above, a recipient may use your version of this file under
  37  * either the BSD or the GPL.
  38  */
  39
  40 #ifndef EIO_H_
  41 #define EIO_H_
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 #include <stddef.h>
  48 #include <sys/types.h>
  49
  50 #ifdef __OpenBSD__
  51 # include <inttypes.h>
  52 #endif
  53
  54 #ifdef _WIN32
  55 # define uid_t int
  56 # define gid_t int
  57 #endif
  58
  59 typedef struct eio_req    eio_req;
  60 typedef struct eio_dirent eio_dirent;
  61
  62 typedef int (*eio_cb)(eio_req *req);
  63
  64 #ifndef EIO_REQ_MEMBERS
  65 # define EIO_REQ_MEMBERS
  66 #endif
  67
  68 #ifndef EIO_STRUCT_STAT
  69 # ifdef _WIN32
  70 #   define EIO_STRUCT_STAT struct _stati64
  71 # else
  72 #   define EIO_STRUCT_STAT struct stat
  73 # endif
  74 #endif
  75
  76 #ifndef EIO_STRUCT_STATVFS
  77 # define EIO_STRUCT_STATVFS struct statvfs
  78 #endif
  79
  80 /* for readdir */
  81
  82 /* eio_readdir flags */
  83 enum
  84 {
  85   EIO_READDIR_DENTS         = 0x01, /* ptr2 contains eio_dirents, not just the (unsorted) names */
  86   EIO_READDIR_DIRS_FIRST    = 0x02, /* dirents gets sorted into a good stat() ing order to find directories first */
  87   EIO_READDIR_STAT_ORDER    = 0x04, /* dirents gets sorted into a good stat() ing order to quickly stat all files */
  88   EIO_READDIR_FOUND_UNKNOWN = 0x80, /* set by eio_readdir when *_ARRAY was set and any TYPE=UNKNOWN's were found */
  89
  90   EIO_READDIR_CUSTOM1       = 0x100, /* for use by apps */
  91   EIO_READDIR_CUSTOM2       = 0x200  /* for use by apps */
  92 };
  93
  94 /* using "typical" values in the hope that the compiler will do something sensible */
  95 enum eio_dtype
  96 {
  97   EIO_DT_UNKNOWN =  0,
  98   EIO_DT_FIFO    =  1,
  99   EIO_DT_CHR     =  2,
 100   EIO_DT_MPC     =  3, /* multiplexed char device (v7+coherent) */
 101   EIO_DT_DIR     =  4,
 102   EIO_DT_NAM     =  5, /* xenix special named file */
 103   EIO_DT_BLK     =  6,
 104   EIO_DT_MPB     =  7, /* multiplexed block device (v7+coherent) */
 105   EIO_DT_REG     =  8,
 106   EIO_DT_NWK     =  9, /* HP-UX network special */
 107   EIO_DT_CMP     =  9, /* VxFS compressed */
 108   EIO_DT_LNK     = 10,
 109   /*  DT_SHAD    = 11,*/
 110   EIO_DT_SOCK    = 12,
 111   EIO_DT_DOOR    = 13, /* solaris door */
 112   EIO_DT_WHT     = 14,
 113   EIO_DT_MAX     = 15  /* highest DT_VALUE ever, hopefully */
 114 };
 115
 116 struct eio_dirent
 117 {
 118   int nameofs; /* offset of null-terminated name string in (char *)req->ptr2 */
 119   unsigned short namelen; /* size of filename without trailing 0 */
 120   unsigned char type; /* one of EIO_DT_* */
 121   signed char score; /* internal use */
 122   ino_t inode; /* the inode number, if available, otherwise unspecified */
 123 };
 124
 125 /* eio_msync flags */
 126 enum
 127 {
 128   EIO_MS_ASYNC      = 1,
 129   EIO_MS_INVALIDATE = 2,
 130   EIO_MS_SYNC       = 4
 131 };
 132
 133 /* eio_mtouch flags */
 134
 135 enum
 136 {
 137   EIO_MT_MODIFY     = 1
 138 };
 139
 140 /* eio_sync_file_range flags */
 141
 142 enum
 143 {
 144   EIO_SYNC_FILE_RANGE_WAIT_BEFORE = 1,
 145   EIO_SYNC_FILE_RANGE_WRITE       = 2,
 146   EIO_SYNC_FILE_RANGE_WAIT_AFTER  = 4
 147 };
 148
 149 typedef double eio_tstamp; /* feel free to use double in your code directly */
 150
 151 /* the eio request structure */
 152
 153 enum
 154 {
 155   EIO_CUSTOM,
 156   EIO_OPEN, EIO_CLOSE, EIO_DUP2,
 157   EIO_READ, EIO_WRITE,
 158   EIO_READAHEAD, EIO_SENDFILE,
 159   EIO_STAT, EIO_LSTAT, EIO_FSTAT,
 160   EIO_STATVFS, EIO_FSTATVFS,
 161   EIO_TRUNCATE, EIO_FTRUNCATE,
 162   EIO_UTIME, EIO_FUTIME,
 163   EIO_CHMOD, EIO_FCHMOD,
 164   EIO_CHOWN, EIO_FCHOWN,
 165   EIO_SYNC, EIO_FSYNC, EIO_FDATASYNC,
 166   EIO_MSYNC, EIO_MTOUCH, EIO_SYNC_FILE_RANGE,
 167   EIO_MLOCK, EIO_MLOCKALL,
 168   EIO_UNLINK, EIO_RMDIR, EIO_MKDIR, EIO_RENAME,
 169   EIO_MKNOD, EIO_READDIR,
 170   EIO_LINK, EIO_SYMLINK, EIO_READLINK,
 171   EIO_GROUP, EIO_NOP,
 172   EIO_BUSY
 173 };
 174
 175 /* mlockall constants */
 176 enum
 177 {
 178   EIO_MCL_CURRENT = 1,
 179   EIO_MCL_FUTURE  = 2,
 180 };
 181
 182 /* request priorities */
 183
 184 enum {
 185   EIO_PRI_MIN     = -4,
 186   EIO_PRI_MAX     =  4,
 187   EIO_PRI_DEFAULT =  0,
 188 };
 189
 190 /* eio request structure */
 191 /* this structure is mostly read-only */
 192 /* when initialising it, all members must be zero-initialised */
 193 struct eio_req
 194 {
 195   eio_req volatile *next; /* private ETP */
 196
 197   ssize_t result;  /* result of syscall, e.g. result = read (... */
 198   off_t offs;      /* read, write, truncate, readahead, sync_file_range: file offset */
 199   size_t size;     /* read, write, readahead, sendfile, msync, mlock, sync_file_range: length */
 200   void *ptr1;      /* all applicable requests: pathname, old name; readdir: optional eio_dirents */
 201   void *ptr2;      /* all applicable requests: new name or memory buffer; readdir: name strings */
 202   eio_tstamp nv1;  /* utime, futime: atime; busy: sleep time */
 203   eio_tstamp nv2;  /* utime, futime: mtime */
 204
 205   int type;        /* EIO_xxx constant ETP */
 206   int int1;        /* all applicable requests: file descriptor; sendfile: output fd; open, msync, mlockall, readdir: flags */
 207   long int2;       /* chown, fchown: uid; sendfile: input fd; open, chmod, mkdir, mknod: file mode, sync_file_range: flags */
 208   long int3;       /* chown, fchown: gid; mknod: dev_t */
 209   int errorno;     /* errno value on syscall return */
 210
 211   unsigned char flags; /* private */
 212   signed char pri;     /* the priority */
 213
 214   void *data;
 215   eio_cb finish;
 216   void (*destroy)(eio_req *req); /* called when requets no longer needed */
 217   void (*feed)(eio_req *req);    /* only used for group requests */
 218
 219   EIO_REQ_MEMBERS
 220
 221   eio_req *grp, *grp_prev, *grp_next, *grp_first; /* private */
 222 };
 223
 224 /* _private_ request flags */
 225 enum {
 226   EIO_FLAG_CANCELLED = 0x01, /* request was cancelled */
 227   EIO_FLAG_PTR1_FREE = 0x02, /* need to free(ptr1) */
 228   EIO_FLAG_PTR2_FREE = 0x04, /* need to free(ptr2) */
 229   EIO_FLAG_GROUPADD  = 0x08  /* some request was added to the group */
 230 };
 231
 232 /* undocumented/unsupported/private helper */
 233 /*void eio_page_align (void **addr, size_t *length);*/
 234
 235 /* returns < 0 on error, errno set
 236  * need_poll, if non-zero, will be called when results are available
 237  * and eio_poll_cb needs to be invoked (it MUST NOT call eio_poll_cb itself).
 238  * done_poll is called when the need to poll is gone.
 239  */
 240 int eio_init (void (*want_poll)(void), void (*done_poll)(void));
 241
 242 /* must be called regularly to handle pending requests */
 243 /* returns 0 if all requests were handled, -1 if not, or the value of EIO_FINISH if != 0 */
 244 int eio_poll (void);
 245
 246 /* stop polling if poll took longer than duration seconds */
 247 void eio_set_max_poll_time (eio_tstamp nseconds);
 248 /* do not handle more then count requests in one call to eio_poll_cb */
 249 void eio_set_max_poll_reqs (unsigned int nreqs);
 250
 251 /* set minimum required number
 252  * maximum wanted number
 253  * or maximum idle number of threads */
 254 void eio_set_min_parallel (unsigned int nthreads);
 255 void eio_set_max_parallel (unsigned int nthreads);
 256 void eio_set_max_idle     (unsigned int nthreads);
 257
 258 unsigned int eio_nreqs    (void); /* number of requests in-flight */
 259 unsigned int eio_nready   (void); /* number of not-yet handled requests */
 260 unsigned int eio_npending (void); /* numbe rof finished but unhandled requests */
 261 unsigned int eio_nthreads (void); /* number of worker threads in use currently */
 262
 263 /*****************************************************************************/
 264 /* convinience wrappers */
 265
 266 #ifndef EIO_NO_WRAPPERS
 267 eio_req *eio_nop       (int pri, eio_cb cb, void *data); /* does nothing except go through the whole process */
 268 eio_req *eio_busy      (eio_tstamp delay, int pri, eio_cb cb, void *data); /* ties a thread for this long, simulating busyness */
 269 eio_req *eio_sync      (int pri, eio_cb cb, void *data);
 270 eio_req *eio_fsync     (int fd, int pri, eio_cb cb, void *data);
 271 eio_req *eio_fdatasync (int fd, int pri, eio_cb cb, void *data);
 272 eio_req *eio_msync     (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data);
 273 eio_req *eio_mtouch    (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data);
 274 eio_req *eio_mlock     (void *addr, size_t length, int pri, eio_cb cb, void *data);
 275 eio_req *eio_mlockall  (int flags, int pri, eio_cb cb, void *data);
 276 eio_req *eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data);
 277 eio_req *eio_close     (int fd, int pri, eio_cb cb, void *data);
 278 eio_req *eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data);
 279 eio_req *eio_read      (int fd, void *buf, size_t length, off_t offset, int pri, eio_cb cb, void *data);
 280 eio_req *eio_write     (int fd, void *buf, size_t length, off_t offset, int pri, eio_cb cb, void *data);
 281 eio_req *eio_fstat     (int fd, int pri, eio_cb cb, void *data); /* stat buffer=ptr2 allocated dynamically */
 282 eio_req *eio_fstatvfs  (int fd, int pri, eio_cb cb, void *data); /* stat buffer=ptr2 allocated dynamically */
 283 eio_req *eio_futime    (int fd, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data);
 284 eio_req *eio_ftruncate (int fd, off_t offset, int pri, eio_cb cb, void *data);
 285 eio_req *eio_fchmod    (int fd, mode_t mode, int pri, eio_cb cb, void *data);
 286 eio_req *eio_fchown    (int fd, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data);
 287 eio_req *eio_dup2      (int fd, int fd2, int pri, eio_cb cb, void *data);
 288 eio_req *eio_sendfile  (int out_fd, int in_fd, off_t in_offset, size_t length, int pri, eio_cb cb, void *data);
 289 eio_req *eio_open      (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data);
 290 eio_req *eio_utime     (const char *path, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data);
 291 eio_req *eio_truncate  (const char *path, off_t offset, int pri, eio_cb cb, void *data);
 292 eio_req *eio_chown     (const char *path, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data);
 293 eio_req *eio_chmod     (const char *path, mode_t mode, int pri, eio_cb cb, void *data);
 294 eio_req *eio_mkdir     (const char *path, mode_t mode, int pri, eio_cb cb, void *data);
 295 eio_req *eio_readdir   (const char *path, int flags, int pri, eio_cb cb, void *data); /* result=ptr2 allocated dynamically */
 296 eio_req *eio_rmdir     (const char *path, int pri, eio_cb cb, void *data);
 297 eio_req *eio_unlink    (const char *path, int pri, eio_cb cb, void *data);
 298 eio_req *eio_readlink  (const char *path, int pri, eio_cb cb, void *data); /* result=ptr2 allocated dynamically */
 299 eio_req *eio_stat      (const char *path, int pri, eio_cb cb, void *data); /* stat buffer=ptr2 allocated dynamically */
 300 eio_req *eio_lstat     (const char *path, int pri, eio_cb cb, void *data); /* stat buffer=ptr2 allocated dynamically */
 301 eio_req *eio_statvfs   (const char *path, int pri, eio_cb cb, void *data); /* stat buffer=ptr2 allocated dynamically */
 302 eio_req *eio_mknod     (const char *path, mode_t mode, dev_t dev, int pri, eio_cb cb, void *data);
 303 eio_req *eio_link      (const char *path, const char *new_path, int pri, eio_cb cb, void *data);
 304 eio_req *eio_symlink   (const char *path, const char *new_path, int pri, eio_cb cb, void *data);
 305 eio_req *eio_rename    (const char *path, const char *new_path, int pri, eio_cb cb, void *data);
 306 eio_req *eio_custom    (eio_cb execute, int pri, eio_cb cb, void *data);
 307 #endif
 308
 309 /*****************************************************************************/
 310 /* groups */
 311
 312 eio_req *eio_grp       (eio_cb cb, void *data);
 313 void eio_grp_feed      (eio_req *grp, void (*feed)(eio_req *req), int limit);
 314 void eio_grp_limit     (eio_req *grp, int limit);
 315 void eio_grp_add       (eio_req *grp, eio_req *req);
 316 void eio_grp_cancel    (eio_req *grp); /* cancels all sub requests but not the group */
 317
 318 /*****************************************************************************/
 319 /* request api */
 320
 321 /* true if the request was cancelled, useful in the invoke callback */
 322 #define EIO_CANCELLED(req)   ((req)->flags & EIO_FLAG_CANCELLED)
 323
 324 #define EIO_RESULT(req)      ((req)->result)
 325 /* returns a pointer to the result buffer allocated by eio */
 326 #define EIO_BUF(req)         ((req)->ptr2)
 327 #define EIO_STAT_BUF(req)    ((EIO_STRUCT_STAT    *)EIO_BUF(req))
 328 #define EIO_STATVFS_BUF(req) ((EIO_STRUCT_STATVFS *)EIO_BUF(req))
 329 #define EIO_PATH(req)        ((char *)(req)->ptr1)
 330
 331 /* submit a request for execution */
 332 void eio_submit (eio_req *req);
 333 /* cancel a request as soon fast as possible, if possible */
 334 void eio_cancel (eio_req *req);
 335 /* destroy a request that has never been submitted */
 336 void eio_destroy (eio_req *req);
 337
 338 /*****************************************************************************/
 339 /* convinience functions */
 340
 341 ssize_t eio_sendfile_sync (int ofd, int ifd, off_t offset, size_t count);
 342
 343 /*****************************************************************************/
 344 /* export these so node_file can use these function instead of pread/write */
 345
 346 #if !HAVE_PREADWRITE
 347 ssize_t eio__pread (int fd, void *buf, size_t count, off_t offset);
 348 ssize_t eio__pwrite (int fd, void *buf, size_t count, off_t offset);
 349 #endif
 350
 351 #ifdef __cplusplus
 352 }
 353 #endif
 354
 355 #endif
 356