ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libeio/eio.pod
(Generate patch)

Comparing libeio/eio.pod (file contents):
Revision 1.8 by root, Sun Jun 5 22:45:49 2011 UTC vs.
Revision 1.10 by root, Sun Jun 5 23:22:04 2011 UTC

… …
226custom data value as C<data>. 226custom data value as C<data>.
227 227
228=head3 POSIX API WRAPPERS 228=head3 POSIX API WRAPPERS
229 229
230These requests simply wrap the POSIX call of the same name, with the same 230These requests simply wrap the POSIX call of the same name, with the same
231arguments: 231arguments. If a function is not implemented by the OS and cnanot be emulated
232in some way, then all of these return C<-1> and set C<errorno> to C<ENOSYS>.
232 233
233=over 4 234=over 4
234 235
235=item eio_open (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data) 236=item eio_open (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data)
236 237
238=item eio_truncate (const char *path, off_t offset, int pri, eio_cb cb, void *data)
239
240=item eio_chown (const char *path, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data)
241
242=item eio_chmod (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
243
244=item eio_mkdir (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
245
246=item eio_rmdir (const char *path, int pri, eio_cb cb, void *data)
247
248=item eio_unlink (const char *path, int pri, eio_cb cb, void *data)
249
237=item eio_utime (const char *path, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data) 250=item eio_utime (const char *path, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data)
238 251
239=item eio_truncate (const char *path, off_t offset, int pri, eio_cb cb, void *data)
240
241=item eio_chown (const char *path, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data)
242
243=item eio_chmod (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
244
245=item eio_mkdir (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
246
247=item eio_rmdir (const char *path, int pri, eio_cb cb, void *data)
248
249=item eio_unlink (const char *path, int pri, eio_cb cb, void *data)
250
251=item eio_readlink (const char *path, int pri, eio_cb cb, void *data) /* result=ptr2 allocated dynamically */
252
253=item eio_stat (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
254
255=item eio_lstat (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
256
257=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
258
259=item eio_mknod (const char *path, mode_t mode, dev_t dev, int pri, eio_cb cb, void *data) 252=item eio_mknod (const char *path, mode_t mode, dev_t dev, int pri, eio_cb cb, void *data)
260 253
261=item eio_link (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 254=item eio_link (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
262 255
263=item eio_symlink (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 256=item eio_symlink (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
264 257
265=item eio_rename (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 258=item eio_rename (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
266 259
267=item eio_msync (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
268
269=item eio_mlock (void *addr, size_t length, int pri, eio_cb cb, void *data) 260=item eio_mlock (void *addr, size_t length, int pri, eio_cb cb, void *data)
270
271=item eio_mlockall (int flags, int pri, eio_cb cb, void *data)
272 261
273=item eio_close (int fd, int pri, eio_cb cb, void *data) 262=item eio_close (int fd, int pri, eio_cb cb, void *data)
274 263
275=item eio_sync (int pri, eio_cb cb, void *data) 264=item eio_sync (int pri, eio_cb cb, void *data)
276 265
… …
305 294
306Not surprisingly, pread and pwrite are not thread-safe on Darwin (OS/X), 295Not surprisingly, pread and pwrite are not thread-safe on Darwin (OS/X),
307so it is advised not to submit multiple requests on the same fd on this 296so it is advised not to submit multiple requests on the same fd on this
308horrible pile of garbage. 297horrible pile of garbage.
309 298
299=item eio_mlockall (int flags, int pri, eio_cb cb, void *data)
300
301Like C<mlockall>, but the flag value constants are called
302C<EIO_MCL_CURRENT> and C<EIO_MCL_FUTURE>.
303
304=item eio_msync (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
305
306Just like msync, except that the flag values are called C<EIO_MS_ASYNC>,
307C<EIO_MS_INVALIDATE> and C<EIO_MS_SYNC>.
308
309=item eio_readlink (const char *path, int pri, eio_cb cb, void *data)
310
311If successful, the path read by C<readlink(2)> can be accessed via C<<
312req->ptr2 >> and is I<NOT> null-terminated, with the length specified as
313C<< req->result >>.
314
315 if (req->result >= 0)
316 {
317 char *target = strndup ((char *)req->ptr2, req->result);
318
319 free (target);
320 }
321
322=item eio_stat (const char *path, int pri, eio_cb cb, void *data)
323
324=item eio_lstat (const char *path, int pri, eio_cb cb, void *data)
325
310=item eio_fstat (int fd, int pri, eio_cb cb, void *data) 326=item eio_fstat (int fd, int pri, eio_cb cb, void *data)
311 327
312Stats a file - if C<< req->result >> indicates success, then you can 328Stats a file - if C<< req->result >> indicates success, then you can
313access the C<struct stat>-like structure via C<< req->ptr2 >>: 329access the C<struct stat>-like structure via C<< req->ptr2 >>:
314 330
315 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2; 331 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2;
316 332
317=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */ 333=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data)
334
335=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data)
318 336
319Stats a filesystem - if C<< req->result >> indicates success, then you can 337Stats a filesystem - if C<< req->result >> indicates success, then you can
320access the C<struct statvfs>-like structure via C<< req->ptr2 >>: 338access the C<struct statvfs>-like structure via C<< req->ptr2 >>:
321 339
322 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2; 340 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2;
… …
338(via the C<opendir>, C<readdir> and C<closedir> calls) and returns either 356(via the C<opendir>, C<readdir> and C<closedir> calls) and returns either
339the names or an array of C<struct eio_dirent>, depending on the C<flags> 357the names or an array of C<struct eio_dirent>, depending on the C<flags>
340argument. 358argument.
341 359
342The C<< req->result >> indicates either the number of files found, or 360The C<< req->result >> indicates either the number of files found, or
343C<-1> on error. On success, zero-terminated names can be found as C<< req->ptr2 >>, 361C<-1> on error. On success, null-terminated names can be found as C<< req->ptr2 >>,
344and C<struct eio_dirents>, if requested by C<flags>, can be found via C<< 362and C<struct eio_dirents>, if requested by C<flags>, can be found via C<<
345req->ptr1 >>. 363req->ptr1 >>.
346 364
347Here is an example that prints all the names: 365Here is an example that prints all the names:
348 366
… …
480=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data) 498=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
481 499
482Calls C<sync_file_range>. If the syscall is missing, then this is the same 500Calls C<sync_file_range>. If the syscall is missing, then this is the same
483as calling C<fdatasync>. 501as calling C<fdatasync>.
484 502
503Flags can be any combination of C<EIO_SYNC_FILE_RANGE_WAIT_BEFORE>,
504C<EIO_SYNC_FILE_RANGE_WRITE> and C<EIO_SYNC_FILE_RANGE_WAIT_AFTER>.
505
485=back 506=back
486 507
487=head3 LIBEIO-SPECIFIC REQUESTS 508=head3 LIBEIO-SPECIFIC REQUESTS
488 509
489These requests are specific to libeio and do not correspond to any OS call. 510These requests are specific to libeio and do not correspond to any OS call.
490 511
491=over 4 512=over 4
492 513
493=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data) 514=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
494 515
516Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY) the given
517memory area, page-wise, that is, it reads (or reads and writes back) the
518first octet of every page that spans the memory area.
519
520This can be used to page in some mmapped file, or dirty some pages. Note
521that dirtying is an unlocked read-write access, so races can ensue when
522the some other thread modifies the data stored in that memory area.
523
495=item eio_custom (void (*)(eio_req *) execute, int pri, eio_cb cb, void *data) 524=item eio_custom (void (*)(eio_req *) execute, int pri, eio_cb cb, void *data)
496 525
497Executes a custom request, i.e., a user-specified callback. 526Executes a custom request, i.e., a user-specified callback.
498 527
499The callback gets the C<eio_req *> as parameter and is expected to read 528The callback gets the C<eio_req *> as parameter and is expected to read
500and modify any request-specific members. Specifically, it should set C<< 529and modify any request-specific members. Specifically, it should set C<<
… …
520 req->result = open (req->data, O_RDONLY); 549 req->result = open (req->data, O_RDONLY);
521 } 550 }
522 551
523 eio_custom (my_open, 0, my_open_done, "/etc/passwd"); 552 eio_custom (my_open, 0, my_open_done, "/etc/passwd");
524 553
525=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data) 554=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data)
526 555
527This is a a request that takes C<delay> seconds to execute, but otherwise 556This is a a request that takes C<delay> seconds to execute, but otherwise
528does nothing - it simply puts one of the worker threads to sleep for this 557does nothing - it simply puts one of the worker threads to sleep for this
529long. 558long.
530 559
531This request can be used to artificially increase load, e.g. for debugging 560This request can be used to artificially increase load, e.g. for debugging
532or benchmarking reasons. 561or benchmarking reasons.
533 562
534=item eio_nop (int pri, eio_cb cb, void *data) 563=item eio_nop (int pri, eio_cb cb, void *data)
535 564
536This request does nothing, except go through the whole request cycle. This 565This request does nothing, except go through the whole request cycle. This
537can be used to measure latency or in some cases to simplify code, but is 566can be used to measure latency or in some cases to simplify code, but is
538not really of much use. 567not really of much use.
539 568

Diff Legend

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