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

Comparing libeio/eio.pod (file contents):
Revision 1.7 by root, Sun Jun 5 22:44:30 2011 UTC vs.
Revision 1.13 by root, Tue Jul 5 09:24:12 2011 UTC

… …
138to read that byte, and in the callback for the read end, you would call 138to read that byte, and in the callback for the read end, you would call
139C<eio_poll>. The race is avoided here because the event loop should invoke 139C<eio_poll>. The race is avoided here because the event loop should invoke
140your callback again and again until the byte has been read (as the pipe 140your callback again and again until the byte has been read (as the pipe
141read callback does not read it, only C<done_poll>). 141read callback does not read it, only C<done_poll>).
142 142
143=head2 CONFIGURATION
144
145The functions in this section can sometimes be useful, but the default
146configuration will do in most case, so you should skip this section on
147first reading.
148
149=over 4
150
151=item eio_set_max_poll_time (eio_tstamp nseconds)
152
153This causes C<eio_poll ()> to return after it has detected that it was
154running for C<nsecond> seconds or longer (this number can be fractional).
155
156This can be used to limit the amount of time spent handling eio requests,
157for example, in interactive programs, you might want to limit this time to
158C<0.01> seconds or so.
159
160Note that:
161
162a) libeio doesn't know how long your request callbacks take, so the time
163spent in C<eio_poll> is up to one callback invocation longer then this
164interval.
165
166b) this is implemented by calling C<gettimeofday> after each request,
167which can be costly.
168
169c) at least one request will be handled.
170
171=item eio_set_max_poll_reqs (unsigned int nreqs)
172
173When C<nreqs> is non-zero, then C<eio_poll> will not handle more than
174C<nreqs> requests per invocation. This is a less costly way to limit the
175amount of work done by C<eio_poll> then setting a time limit.
176
177If you know your callbacks are generally fast, you could use this to
178encourage interactiveness in your programs by setting it to C<10>, C<100>
179or even C<1000>.
180
181=item eio_set_min_parallel (unsigned int nthreads)
182
183Make sure libeio can handle at least this many requests in parallel. It
184might be able handle more.
185
186=item eio_set_max_parallel (unsigned int nthreads)
187
188Set the maximum number of threads that libeio will spawn.
189
190=item eio_set_max_idle (unsigned int nthreads)
191
192Libeio uses threads internally to handle most requests, and will start and stop threads on demand.
193
194This call can be used to limit the number of idle threads (threads without
195work to do): libeio will keep some threads idle in preparation for more
196requests, but never longer than C<nthreads> threads.
197
198In addition to this, libeio will also stop threads when they are idle for
199a few seconds, regardless of this setting.
200
201=item unsigned int eio_nthreads ()
202
203Return the number of worker threads currently running.
204
205=item unsigned int eio_nreqs ()
206
207Return the number of requests currently handled by libeio. This is the
208total number of requests that have been submitted to libeio, but not yet
209destroyed.
210
211=item unsigned int eio_nready ()
212
213Returns the number of ready requests, i.e. requests that have been
214submitted but have not yet entered the execution phase.
215
216=item unsigned int eio_npending ()
217
218Returns the number of pending requests, i.e. requests that have been
219executed and have results, but have not been finished yet by a call to
220C<eio_poll>).
221
222=back
223
224 143
225=head1 HIGH LEVEL REQUEST API 144=head1 HIGH LEVEL REQUEST API
226 145
227Libeio has both a high-level API, which consists of calling a request 146Libeio has both a high-level API, which consists of calling a request
228function with a callback to be called on completion, and a low-level API 147function with a callback to be called on completion, and a low-level API
… …
234 153
235You 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
236required 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)>
237(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.
238 157
239The 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 *>.
240 162
241The 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
242results of the request. The members you can access inside that structure 164results of the request. The members you can access inside that structure
243vary from request to request, except for: 165vary from request to request, except for:
244 166
… …
307custom data value as C<data>. 229custom data value as C<data>.
308 230
309=head3 POSIX API WRAPPERS 231=head3 POSIX API WRAPPERS
310 232
311These 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
312arguments: 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>.
313 236
314=over 4 237=over 4
315 238
316=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)
317 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
318=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)
319 254
320=item eio_truncate (const char *path, off_t offset, int pri, eio_cb cb, void *data)
321
322=item eio_chown (const char *path, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data)
323
324=item eio_chmod (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
325
326=item eio_mkdir (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
327
328=item eio_rmdir (const char *path, int pri, eio_cb cb, void *data)
329
330=item eio_unlink (const char *path, int pri, eio_cb cb, void *data)
331
332=item eio_readlink (const char *path, int pri, eio_cb cb, void *data) /* result=ptr2 allocated dynamically */
333
334=item eio_stat (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
335
336=item eio_lstat (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
337
338=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
339
340=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)
341 256
342=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)
343 258
344=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)
345 260
346=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)
347 262
348=item eio_msync (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
349
350=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)
351
352=item eio_mlockall (int flags, int pri, eio_cb cb, void *data)
353 264
354=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)
355 266
356=item eio_sync (int pri, eio_cb cb, void *data) 267=item eio_sync (int pri, eio_cb cb, void *data)
357 268
… …
386 297
387Not 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),
388so 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
389horrible pile of garbage. 300horrible pile of garbage.
390 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_realpath (const char *path, int pri, eio_cb cb, void *data)
326
327Similar to the realpath libc function, but unlike that one, result is
328C<0> on failure and the length of the returned path in C<ptr2> - this is
329similar to readlink.
330
331=item eio_stat (const char *path, int pri, eio_cb cb, void *data)
332
333=item eio_lstat (const char *path, int pri, eio_cb cb, void *data)
334
391=item eio_fstat (int fd, int pri, eio_cb cb, void *data) 335=item eio_fstat (int fd, int pri, eio_cb cb, void *data)
392 336
393Stats a file - if C<< req->result >> indicates success, then you can 337Stats a file - if C<< req->result >> indicates success, then you can
394access the C<struct stat>-like structure via C<< req->ptr2 >>: 338access the C<struct stat>-like structure via C<< req->ptr2 >>:
395 339
396 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2; 340 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2;
397 341
398=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */ 342=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data)
343
344=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data)
399 345
400Stats a filesystem - if C<< req->result >> indicates success, then you can 346Stats a filesystem - if C<< req->result >> indicates success, then you can
401access the C<struct statvfs>-like structure via C<< req->ptr2 >>: 347access the C<struct statvfs>-like structure via C<< req->ptr2 >>:
402 348
403 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2; 349 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2;
… …
419(via the C<opendir>, C<readdir> and C<closedir> calls) and returns either 365(via the C<opendir>, C<readdir> and C<closedir> calls) and returns either
420the names or an array of C<struct eio_dirent>, depending on the C<flags> 366the names or an array of C<struct eio_dirent>, depending on the C<flags>
421argument. 367argument.
422 368
423The C<< req->result >> indicates either the number of files found, or 369The C<< req->result >> indicates either the number of files found, or
424C<-1> on error. On success, zero-terminated names can be found as C<< req->ptr2 >>, 370C<-1> on error. On success, null-terminated names can be found as C<< req->ptr2 >>,
425and C<struct eio_dirents>, if requested by C<flags>, can be found via C<< 371and C<struct eio_dirents>, if requested by C<flags>, can be found via C<<
426req->ptr1 >>. 372req->ptr1 >>.
427 373
428Here is an example that prints all the names: 374Here is an example that prints all the names:
429 375
… …
561=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data) 507=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
562 508
563Calls C<sync_file_range>. If the syscall is missing, then this is the same 509Calls C<sync_file_range>. If the syscall is missing, then this is the same
564as calling C<fdatasync>. 510as calling C<fdatasync>.
565 511
512Flags can be any combination of C<EIO_SYNC_FILE_RANGE_WAIT_BEFORE>,
513C<EIO_SYNC_FILE_RANGE_WRITE> and C<EIO_SYNC_FILE_RANGE_WAIT_AFTER>.
514
566=back 515=back
567 516
568=head3 LIBEIO-SPECIFIC REQUESTS 517=head3 LIBEIO-SPECIFIC REQUESTS
569 518
570These requests are specific to libeio and do not correspond to any OS call. 519These requests are specific to libeio and do not correspond to any OS call.
571 520
572=over 4 521=over 4
573 522
574=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data) 523=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
575 524
525Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY) the given
526memory area, page-wise, that is, it reads (or reads and writes back) the
527first octet of every page that spans the memory area.
528
529This can be used to page in some mmapped file, or dirty some pages. Note
530that dirtying is an unlocked read-write access, so races can ensue when
531the some other thread modifies the data stored in that memory area.
532
576=item eio_custom (void (*)(eio_req *) execute, int pri, eio_cb cb, void *data) 533=item eio_custom (void (*)(eio_req *) execute, int pri, eio_cb cb, void *data)
577 534
578Executes a custom request, i.e., a user-specified callback. 535Executes a custom request, i.e., a user-specified callback.
579 536
580The callback gets the C<eio_req *> as parameter and is expected to read 537The callback gets the C<eio_req *> as parameter and is expected to read
581and modify any request-specific members. Specifically, it should set C<< 538and modify any request-specific members. Specifically, it should set C<<
… …
601 req->result = open (req->data, O_RDONLY); 558 req->result = open (req->data, O_RDONLY);
602 } 559 }
603 560
604 eio_custom (my_open, 0, my_open_done, "/etc/passwd"); 561 eio_custom (my_open, 0, my_open_done, "/etc/passwd");
605 562
606=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data) 563=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data)
607 564
608This is a a request that takes C<delay> seconds to execute, but otherwise 565This is a a request that takes C<delay> seconds to execute, but otherwise
609does nothing - it simply puts one of the worker threads to sleep for this 566does nothing - it simply puts one of the worker threads to sleep for this
610long. 567long.
611 568
612This request can be used to artificially increase load, e.g. for debugging 569This request can be used to artificially increase load, e.g. for debugging
613or benchmarking reasons. 570or benchmarking reasons.
614 571
615=item eio_nop (int pri, eio_cb cb, void *data) 572=item eio_nop (int pri, eio_cb cb, void *data)
616 573
617This request does nothing, except go through the whole request cycle. This 574This request does nothing, except go through the whole request cycle. This
618can be used to measure latency or in some cases to simplify code, but is 575can be used to measure latency or in some cases to simplify code, but is
619not really of much use. 576not really of much use.
620 577
621=back 578=back
622 579
623=head3 GROUPING AND LIMITING REQUESTS 580=head3 GROUPING AND LIMITING REQUESTS
581
582There is one more rather special request, C<eio_grp>. It is a very special
583aio request: Instead of doing something, it is a container for other eio
584requests.
585
586There are two primary use cases for this: a) bundle many requests into a
587single, composite, request with a definite callback and the ability to
588cancel the whole request with its subrequests and b) limiting the number
589of "active" requests.
590
591Further below you will find more dicussion of these topics - first follows
592the reference section detailing the request generator and other methods.
593
594=over 4
595
596=item eio_grp (eio_cb cb, void *data)
597
598Creates and submits a group request.
599
600=back
601
602
624 603
625#TODO 604#TODO
626 605
627/*****************************************************************************/ 606/*****************************************************************************/
628/* groups */ 607/* groups */
… …
660 639
661zero 640zero
662 641
663#TODO 642#TODO
664 643
644=head2 CONFIGURATION
645
646The functions in this section can sometimes be useful, but the default
647configuration will do in most case, so you should skip this section on
648first reading.
649
650=over 4
651
652=item eio_set_max_poll_time (eio_tstamp nseconds)
653
654This causes C<eio_poll ()> to return after it has detected that it was
655running for C<nsecond> seconds or longer (this number can be fractional).
656
657This can be used to limit the amount of time spent handling eio requests,
658for example, in interactive programs, you might want to limit this time to
659C<0.01> seconds or so.
660
661Note that:
662
663a) libeio doesn't know how long your request callbacks take, so the time
664spent in C<eio_poll> is up to one callback invocation longer then this
665interval.
666
667b) this is implemented by calling C<gettimeofday> after each request,
668which can be costly.
669
670c) at least one request will be handled.
671
672=item eio_set_max_poll_reqs (unsigned int nreqs)
673
674When C<nreqs> is non-zero, then C<eio_poll> will not handle more than
675C<nreqs> requests per invocation. This is a less costly way to limit the
676amount of work done by C<eio_poll> then setting a time limit.
677
678If you know your callbacks are generally fast, you could use this to
679encourage interactiveness in your programs by setting it to C<10>, C<100>
680or even C<1000>.
681
682=item eio_set_min_parallel (unsigned int nthreads)
683
684Make sure libeio can handle at least this many requests in parallel. It
685might be able handle more.
686
687=item eio_set_max_parallel (unsigned int nthreads)
688
689Set the maximum number of threads that libeio will spawn.
690
691=item eio_set_max_idle (unsigned int nthreads)
692
693Libeio uses threads internally to handle most requests, and will start and stop threads on demand.
694
695This call can be used to limit the number of idle threads (threads without
696work to do): libeio will keep some threads idle in preparation for more
697requests, but never longer than C<nthreads> threads.
698
699In addition to this, libeio will also stop threads when they are idle for
700a few seconds, regardless of this setting.
701
702=item unsigned int eio_nthreads ()
703
704Return the number of worker threads currently running.
705
706=item unsigned int eio_nreqs ()
707
708Return the number of requests currently handled by libeio. This is the
709total number of requests that have been submitted to libeio, but not yet
710destroyed.
711
712=item unsigned int eio_nready ()
713
714Returns the number of ready requests, i.e. requests that have been
715submitted but have not yet entered the execution phase.
716
717=item unsigned int eio_npending ()
718
719Returns the number of pending requests, i.e. requests that have been
720executed and have results, but have not been finished yet by a call to
721C<eio_poll>).
722
723=back
724
665=head1 EMBEDDING 725=head1 EMBEDDING
666 726
667Libeio can be embedded directly into programs. This functionality is not 727Libeio can be embedded directly into programs. This functionality is not
668documented and not (yet) officially supported. 728documented and not (yet) officially supported.
669 729

Diff Legend

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