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.12 by root, Wed Jun 29 10:32:55 2011 UTC

… …
153 153
154You submit a request by calling the relevant C<eio_TYPE> function with the 154You submit a request by calling the relevant C<eio_TYPE> function with the
155required parameters, a callback of type C<int (*eio_cb)(eio_req *req)> 155required parameters, a callback of type C<int (*eio_cb)(eio_req *req)>
156(called C<eio_cb> below) and a freely usable C<void *data> argument. 156(called C<eio_cb> below) and a freely usable C<void *data> argument.
157 157
158The return value will either be 0 158The return value will either be 0, in case something went really wrong
159(which can basically only happen on very fatal errors, such as C<malloc>
160returning 0, which is rather unlikely), or a pointer to the newly-created
161and submitted C<eio_req *>.
159 162
160The callback will be called with an C<eio_req *> which contains the 163The callback will be called with an C<eio_req *> which contains the
161results of the request. The members you can access inside that structure 164results of the request. The members you can access inside that structure
162vary from request to request, except for: 165vary from request to request, except for:
163 166
… …
226custom data value as C<data>. 229custom data value as C<data>.
227 230
228=head3 POSIX API WRAPPERS 231=head3 POSIX API WRAPPERS
229 232
230These requests simply wrap the POSIX call of the same name, with the same 233These requests simply wrap the POSIX call of the same name, with the same
231arguments: 234arguments. If a function is not implemented by the OS and cannot be emulated
235in some way, then all of these return C<-1> and set C<errorno> to C<ENOSYS>.
232 236
233=over 4 237=over 4
234 238
235=item eio_open (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data) 239=item eio_open (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data)
236 240
241=item eio_truncate (const char *path, off_t offset, int pri, eio_cb cb, void *data)
242
243=item eio_chown (const char *path, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data)
244
245=item eio_chmod (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
246
247=item eio_mkdir (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
248
249=item eio_rmdir (const char *path, int pri, eio_cb cb, void *data)
250
251=item eio_unlink (const char *path, int pri, eio_cb cb, void *data)
252
237=item eio_utime (const char *path, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data) 253=item eio_utime (const char *path, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data)
238 254
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) 255=item eio_mknod (const char *path, mode_t mode, dev_t dev, int pri, eio_cb cb, void *data)
260 256
261=item eio_link (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 257=item eio_link (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
262 258
263=item eio_symlink (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 259=item eio_symlink (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
264 260
265=item eio_rename (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 261=item eio_rename (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
266 262
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) 263=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 264
273=item eio_close (int fd, int pri, eio_cb cb, void *data) 265=item eio_close (int fd, int pri, eio_cb cb, void *data)
274 266
275=item eio_sync (int pri, eio_cb cb, void *data) 267=item eio_sync (int pri, eio_cb cb, void *data)
276 268
… …
305 297
306Not surprisingly, pread and pwrite are not thread-safe on Darwin (OS/X), 298Not 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 299so it is advised not to submit multiple requests on the same fd on this
308horrible pile of garbage. 300horrible pile of garbage.
309 301
302=item eio_mlockall (int flags, int pri, eio_cb cb, void *data)
303
304Like C<mlockall>, but the flag value constants are called
305C<EIO_MCL_CURRENT> and C<EIO_MCL_FUTURE>.
306
307=item eio_msync (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
308
309Just like msync, except that the flag values are called C<EIO_MS_ASYNC>,
310C<EIO_MS_INVALIDATE> and C<EIO_MS_SYNC>.
311
312=item eio_readlink (const char *path, int pri, eio_cb cb, void *data)
313
314If successful, the path read by C<readlink(2)> can be accessed via C<<
315req->ptr2 >> and is I<NOT> null-terminated, with the length specified as
316C<< req->result >>.
317
318 if (req->result >= 0)
319 {
320 char *target = strndup ((char *)req->ptr2, req->result);
321
322 free (target);
323 }
324
325=item eio_stat (const char *path, int pri, eio_cb cb, void *data)
326
327=item eio_lstat (const char *path, int pri, eio_cb cb, void *data)
328
310=item eio_fstat (int fd, int pri, eio_cb cb, void *data) 329=item eio_fstat (int fd, int pri, eio_cb cb, void *data)
311 330
312Stats a file - if C<< req->result >> indicates success, then you can 331Stats a file - if C<< req->result >> indicates success, then you can
313access the C<struct stat>-like structure via C<< req->ptr2 >>: 332access the C<struct stat>-like structure via C<< req->ptr2 >>:
314 333
315 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2; 334 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2;
316 335
317=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */ 336=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data)
337
338=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data)
318 339
319Stats a filesystem - if C<< req->result >> indicates success, then you can 340Stats a filesystem - if C<< req->result >> indicates success, then you can
320access the C<struct statvfs>-like structure via C<< req->ptr2 >>: 341access the C<struct statvfs>-like structure via C<< req->ptr2 >>:
321 342
322 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2; 343 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2;
… …
338(via the C<opendir>, C<readdir> and C<closedir> calls) and returns either 359(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> 360the names or an array of C<struct eio_dirent>, depending on the C<flags>
340argument. 361argument.
341 362
342The C<< req->result >> indicates either the number of files found, or 363The 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 >>, 364C<-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<< 365and C<struct eio_dirents>, if requested by C<flags>, can be found via C<<
345req->ptr1 >>. 366req->ptr1 >>.
346 367
347Here is an example that prints all the names: 368Here is an example that prints all the names:
348 369
… …
480=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data) 501=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
481 502
482Calls C<sync_file_range>. If the syscall is missing, then this is the same 503Calls C<sync_file_range>. If the syscall is missing, then this is the same
483as calling C<fdatasync>. 504as calling C<fdatasync>.
484 505
506Flags can be any combination of C<EIO_SYNC_FILE_RANGE_WAIT_BEFORE>,
507C<EIO_SYNC_FILE_RANGE_WRITE> and C<EIO_SYNC_FILE_RANGE_WAIT_AFTER>.
508
485=back 509=back
486 510
487=head3 LIBEIO-SPECIFIC REQUESTS 511=head3 LIBEIO-SPECIFIC REQUESTS
488 512
489These requests are specific to libeio and do not correspond to any OS call. 513These requests are specific to libeio and do not correspond to any OS call.
490 514
491=over 4 515=over 4
492 516
493=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data) 517=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
494 518
519Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY) the given
520memory area, page-wise, that is, it reads (or reads and writes back) the
521first octet of every page that spans the memory area.
522
523This can be used to page in some mmapped file, or dirty some pages. Note
524that dirtying is an unlocked read-write access, so races can ensue when
525the some other thread modifies the data stored in that memory area.
526
495=item eio_custom (void (*)(eio_req *) execute, int pri, eio_cb cb, void *data) 527=item eio_custom (void (*)(eio_req *) execute, int pri, eio_cb cb, void *data)
496 528
497Executes a custom request, i.e., a user-specified callback. 529Executes a custom request, i.e., a user-specified callback.
498 530
499The callback gets the C<eio_req *> as parameter and is expected to read 531The callback gets the C<eio_req *> as parameter and is expected to read
500and modify any request-specific members. Specifically, it should set C<< 532and modify any request-specific members. Specifically, it should set C<<
… …
520 req->result = open (req->data, O_RDONLY); 552 req->result = open (req->data, O_RDONLY);
521 } 553 }
522 554
523 eio_custom (my_open, 0, my_open_done, "/etc/passwd"); 555 eio_custom (my_open, 0, my_open_done, "/etc/passwd");
524 556
525=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data) 557=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data)
526 558
527This is a a request that takes C<delay> seconds to execute, but otherwise 559This 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 560does nothing - it simply puts one of the worker threads to sleep for this
529long. 561long.
530 562
531This request can be used to artificially increase load, e.g. for debugging 563This request can be used to artificially increase load, e.g. for debugging
532or benchmarking reasons. 564or benchmarking reasons.
533 565
534=item eio_nop (int pri, eio_cb cb, void *data) 566=item eio_nop (int pri, eio_cb cb, void *data)
535 567
536This request does nothing, except go through the whole request cycle. This 568This 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 569can be used to measure latency or in some cases to simplify code, but is
538not really of much use. 570not really of much use.
539 571
540=back 572=back
541 573
542=head3 GROUPING AND LIMITING REQUESTS 574=head3 GROUPING AND LIMITING REQUESTS
575
576There is one more rather special request, C<eio_grp>. It is a very special
577aio request: Instead of doing something, it is a container for other eio
578requests.
579
580There are two primary use cases for this: a) bundle many requests into a
581single, composite, request with a definite callback and the ability to
582cancel the whole request with its subrequests and b) limiting the number
583of "active" requests.
584
585Further below you will find more dicussion of these topics - first follows
586the reference section detailing the request generator and other methods.
587
588=over 4
589
590=item eio_grp (eio_cb cb, void *data)
591
592Creates and submits a group request.
593
594=back
595
596
543 597
544#TODO 598#TODO
545 599
546/*****************************************************************************/ 600/*****************************************************************************/
547/* groups */ 601/* groups */

Diff Legend

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