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.12 by root, Wed Jun 29 10:32:55 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_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
391=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)
392 330
393Stats a file - if C<< req->result >> indicates success, then you can 331Stats a file - if C<< req->result >> indicates success, then you can
394access the C<struct stat>-like structure via C<< req->ptr2 >>: 332access the C<struct stat>-like structure via C<< req->ptr2 >>:
395 333
396 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2; 334 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2;
397 335
398=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)
399 339
400Stats a filesystem - if C<< req->result >> indicates success, then you can 340Stats a filesystem - if C<< req->result >> indicates success, then you can
401access the C<struct statvfs>-like structure via C<< req->ptr2 >>: 341access the C<struct statvfs>-like structure via C<< req->ptr2 >>:
402 342
403 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2; 343 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2;
… …
419(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
420the 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>
421argument. 361argument.
422 362
423The C<< req->result >> indicates either the number of files found, or 363The 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 >>, 364C<-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<< 365and C<struct eio_dirents>, if requested by C<flags>, can be found via C<<
426req->ptr1 >>. 366req->ptr1 >>.
427 367
428Here is an example that prints all the names: 368Here is an example that prints all the names:
429 369
… …
561=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)
562 502
563Calls 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
564as calling C<fdatasync>. 504as calling C<fdatasync>.
565 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
566=back 509=back
567 510
568=head3 LIBEIO-SPECIFIC REQUESTS 511=head3 LIBEIO-SPECIFIC REQUESTS
569 512
570These 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.
571 514
572=over 4 515=over 4
573 516
574=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)
575 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
576=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)
577 528
578Executes a custom request, i.e., a user-specified callback. 529Executes a custom request, i.e., a user-specified callback.
579 530
580The 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
581and modify any request-specific members. Specifically, it should set C<< 532and modify any request-specific members. Specifically, it should set C<<
… …
601 req->result = open (req->data, O_RDONLY); 552 req->result = open (req->data, O_RDONLY);
602 } 553 }
603 554
604 eio_custom (my_open, 0, my_open_done, "/etc/passwd"); 555 eio_custom (my_open, 0, my_open_done, "/etc/passwd");
605 556
606=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)
607 558
608This 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
609does 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
610long. 561long.
611 562
612This 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
613or benchmarking reasons. 564or benchmarking reasons.
614 565
615=item eio_nop (int pri, eio_cb cb, void *data) 566=item eio_nop (int pri, eio_cb cb, void *data)
616 567
617This request does nothing, except go through the whole request cycle. This 568This 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 569can be used to measure latency or in some cases to simplify code, but is
619not really of much use. 570not really of much use.
620 571
621=back 572=back
622 573
623=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
624 597
625#TODO 598#TODO
626 599
627/*****************************************************************************/ 600/*****************************************************************************/
628/* groups */ 601/* groups */
… …
660 633
661zero 634zero
662 635
663#TODO 636#TODO
664 637
638=head2 CONFIGURATION
639
640The functions in this section can sometimes be useful, but the default
641configuration will do in most case, so you should skip this section on
642first reading.
643
644=over 4
645
646=item eio_set_max_poll_time (eio_tstamp nseconds)
647
648This causes C<eio_poll ()> to return after it has detected that it was
649running for C<nsecond> seconds or longer (this number can be fractional).
650
651This can be used to limit the amount of time spent handling eio requests,
652for example, in interactive programs, you might want to limit this time to
653C<0.01> seconds or so.
654
655Note that:
656
657a) libeio doesn't know how long your request callbacks take, so the time
658spent in C<eio_poll> is up to one callback invocation longer then this
659interval.
660
661b) this is implemented by calling C<gettimeofday> after each request,
662which can be costly.
663
664c) at least one request will be handled.
665
666=item eio_set_max_poll_reqs (unsigned int nreqs)
667
668When C<nreqs> is non-zero, then C<eio_poll> will not handle more than
669C<nreqs> requests per invocation. This is a less costly way to limit the
670amount of work done by C<eio_poll> then setting a time limit.
671
672If you know your callbacks are generally fast, you could use this to
673encourage interactiveness in your programs by setting it to C<10>, C<100>
674or even C<1000>.
675
676=item eio_set_min_parallel (unsigned int nthreads)
677
678Make sure libeio can handle at least this many requests in parallel. It
679might be able handle more.
680
681=item eio_set_max_parallel (unsigned int nthreads)
682
683Set the maximum number of threads that libeio will spawn.
684
685=item eio_set_max_idle (unsigned int nthreads)
686
687Libeio uses threads internally to handle most requests, and will start and stop threads on demand.
688
689This call can be used to limit the number of idle threads (threads without
690work to do): libeio will keep some threads idle in preparation for more
691requests, but never longer than C<nthreads> threads.
692
693In addition to this, libeio will also stop threads when they are idle for
694a few seconds, regardless of this setting.
695
696=item unsigned int eio_nthreads ()
697
698Return the number of worker threads currently running.
699
700=item unsigned int eio_nreqs ()
701
702Return the number of requests currently handled by libeio. This is the
703total number of requests that have been submitted to libeio, but not yet
704destroyed.
705
706=item unsigned int eio_nready ()
707
708Returns the number of ready requests, i.e. requests that have been
709submitted but have not yet entered the execution phase.
710
711=item unsigned int eio_npending ()
712
713Returns the number of pending requests, i.e. requests that have been
714executed and have results, but have not been finished yet by a call to
715C<eio_poll>).
716
717=back
718
665=head1 EMBEDDING 719=head1 EMBEDDING
666 720
667Libeio can be embedded directly into programs. This functionality is not 721Libeio can be embedded directly into programs. This functionality is not
668documented and not (yet) officially supported. 722documented and not (yet) officially supported.
669 723

Diff Legend

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