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

Comparing libeio/eio.pod (file contents):
Revision 1.16 by root, Tue Jul 5 17:05:54 2011 UTC vs.
Revision 1.29 by sf-exg, Mon Sep 26 17:10:10 2011 UTC

… …
45Unlike the name component C<stamp> might indicate, it is also used for 45Unlike the name component C<stamp> might indicate, it is also used for
46time differences throughout libeio. 46time differences throughout libeio.
47 47
48=head2 FORK SUPPORT 48=head2 FORK SUPPORT
49 49
50Calling C<fork ()> is fully supported by this module. It is implemented in these steps: 50Usage of pthreads in a program changes the semantics of fork
51considerably. Specifically, only async-safe functions can be called after
52fork. Libeio uses pthreads, so this applies, and makes using fork hard for
53anything but relatively fork + exec uses.
51 54
52 1. wait till all requests in "execute" state have been handled 55This library only works in the process that initialised it: Forking is
53 (basically requests that are already handed over to the kernel). 56fully supported, but using libeio in any other process than the one that
54 2. fork 57called C<eio_init> is not.
55 3. in the parent, continue business as usual, done
56 4. in the child, destroy all ready and pending requests and free the
57 memory used by the worker threads. This gives you a fully empty
58 libeio queue.
59 58
60Note, however, since libeio does use threads, thr above guarantee doesn't 59You might get around by not I<using> libeio before (or after) forking in
61cover your libc, for example, malloc and other libc functions are not 60the parent, and using it in the child afterwards. You could also try to
62fork-safe, so there is very little you can do after a fork, and in fatc, 61call the L<eio_init> function again in the child, which will brutally
63the above might crash, and thus change. 62reinitialise all data structures, which isn't POSIX conformant, but
63typically works.
64
65Otherwise, the only recommendation you should follow is: treat fork code
66the same way you treat signal handlers, and only ever call C<eio_init> in
67the process that uses it, and only once ever.
64 68
65=head1 INITIALISATION/INTEGRATION 69=head1 INITIALISATION/INTEGRATION
66 70
67Before you can call any eio functions you first have to initialise the 71Before you can call any eio functions you first have to initialise the
68library. The library integrates into any event loop, but can also be used 72library. The library integrates into any event loop, but can also be used
… …
77This function initialises the library. On success it returns C<0>, on 81This function initialises the library. On success it returns C<0>, on
78failure it returns C<-1> and sets C<errno> appropriately. 82failure it returns C<-1> and sets C<errno> appropriately.
79 83
80It accepts two function pointers specifying callbacks as argument, both of 84It accepts two function pointers specifying callbacks as argument, both of
81which can be C<0>, in which case the callback isn't called. 85which can be C<0>, in which case the callback isn't called.
86
87There is currently no way to change these callbacks later, or to
88"uninitialise" the library again.
82 89
83=item want_poll callback 90=item want_poll callback
84 91
85The C<want_poll> callback is invoked whenever libeio wants attention (i.e. 92The C<want_poll> callback is invoked whenever libeio wants attention (i.e.
86it wants to be polled by calling C<eio_poll>). It is "edge-triggered", 93it wants to be polled by calling C<eio_poll>). It is "edge-triggered",
… …
130 137
131If C<eio_poll ()> is configured to not handle all results in one go 138If C<eio_poll ()> is configured to not handle all results in one go
132(i.e. it returns C<-1>) then you should start an idle watcher that calls 139(i.e. it returns C<-1>) then you should start an idle watcher that calls
133C<eio_poll> until it returns something C<!= -1>. 140C<eio_poll> until it returns something C<!= -1>.
134 141
135A full-featured conenctor between libeio and libev would look as follows 142A full-featured connector between libeio and libev would look as follows
136(if C<eio_poll> is handling all requests, it can of course be simplified a 143(if C<eio_poll> is handling all requests, it can of course be simplified a
137lot by removing the idle watcher logic): 144lot by removing the idle watcher logic):
138 145
139 static struct ev_loop *loop; 146 static struct ev_loop *loop;
140 static ev_idle repeat_watcher; 147 static ev_idle repeat_watcher;
141 static ev_async ready_watcher; 148 static ev_async ready_watcher;
142 149
143 /* idle watcher callback, only used when eio_poll */ 150 /* idle watcher callback, only used when eio_poll */
144 /* didn't handle all results in one call */ 151 /* didn't handle all results in one call */
145 static void 152 static void
146 repeat (EV_P_ ev_idle *w, int revents) 153 repeat (EV_P_ ev_idle *w, int revents)
147 { 154 {
148 if (eio_poll () != -1) 155 if (eio_poll () != -1)
149 ev_idle_stop (EV_A_ w); 156 ev_idle_stop (EV_A_ w);
150 } 157 }
151 158
152 /* eio has some results, process them */ 159 /* eio has some results, process them */
153 static void 160 static void
154 ready (EV_P_ ev_async *w, int revents) 161 ready (EV_P_ ev_async *w, int revents)
155 { 162 {
156 if (eio_poll () == -1) 163 if (eio_poll () == -1)
157 ev_idle_start (EV_A_ &repeat_watcher); 164 ev_idle_start (EV_A_ &repeat_watcher);
158 } 165 }
159 166
160 /* wake up the event loop */ 167 /* wake up the event loop */
161 static void 168 static void
162 want_poll (void) 169 want_poll (void)
163 { 170 {
164 ev_async_send (loop, &ready_watcher) 171 ev_async_send (loop, &ready_watcher)
165 } 172 }
166 173
167 void 174 void
168 my_init_eio () 175 my_init_eio ()
169 { 176 {
170 loop = EV_DEFAULT; 177 loop = EV_DEFAULT;
171 178
172 ev_idle_init (&repeat_watcher, repeat); 179 ev_idle_init (&repeat_watcher, repeat);
173 ev_async_init (&ready_watcher, ready); 180 ev_async_init (&ready_watcher, ready);
174 ev_async_start (loop &watcher); 181 ev_async_start (loop &watcher);
175 182
176 eio_init (want_poll, 0); 183 eio_init (want_poll, 0);
177 } 184 }
178 185
179For most other event loops, you would typically use a pipe - the event 186For most other event loops, you would typically use a pipe - the event
180loop should be told to wait for read readiness on the read end. In 187loop should be told to wait for read readiness on the read end. In
181C<want_poll> you would write a single byte, in C<done_poll> you would try 188C<want_poll> you would write a single byte, in C<done_poll> you would try
182to read that byte, and in the callback for the read end, you would call 189to read that byte, and in the callback for the read end, you would call
183C<eio_poll>. 190C<eio_poll>.
184 191
185You don't have to take special care in the case C<eio_poll> doesn't handle 192You don't have to take special care in the case C<eio_poll> doesn't handle
186all requests, as the done callback will not be invoked, so the event loop 193all requests, as the done callback will not be invoked, so the event loop
187will still signal readyness for the pipe until I<all> results have been 194will still signal readiness for the pipe until I<all> results have been
188processed. 195processed.
189 196
190 197
191=head1 HIGH LEVEL REQUEST API 198=head1 HIGH LEVEL REQUEST API
192 199
… …
226 233
227The C<void *data> member simply stores the value of the C<data> argument. 234The C<void *data> member simply stores the value of the C<data> argument.
228 235
229=back 236=back
230 237
238Members not explicitly described as accessible must not be
239accessed. Specifically, there is no guarantee that any members will still
240have the value they had when the request was submitted.
241
231The return value of the callback is normally C<0>, which tells libeio to 242The return value of the callback is normally C<0>, which tells libeio to
232continue normally. If a callback returns a nonzero value, libeio will 243continue normally. If a callback returns a nonzero value, libeio will
233stop processing results (in C<eio_poll>) and will return the value to its 244stop processing results (in C<eio_poll>) and will return the value to its
234caller. 245caller.
235 246
236Memory areas passed to libeio must stay valid as long as a request 247Memory areas passed to libeio wrappers must stay valid as long as a
237executes, with the exception of paths, which are being copied 248request executes, with the exception of paths, which are being copied
238internally. Any memory libeio itself allocates will be freed after the 249internally. Any memory libeio itself allocates will be freed after the
239finish callback has been called. If you want to manage all memory passed 250finish callback has been called. If you want to manage all memory passed
240to libeio yourself you can use the low-level API. 251to libeio yourself you can use the low-level API.
241 252
242For example, to open a file, you could do this: 253For example, to open a file, you could do this:
… …
260 } 271 }
261 272
262 /* the first three arguments are passed to open(2) */ 273 /* the first three arguments are passed to open(2) */
263 /* the remaining are priority, callback and data */ 274 /* the remaining are priority, callback and data */
264 if (!eio_open ("/etc/passwd", O_RDONLY, 0, 0, file_open_done, 0)) 275 if (!eio_open ("/etc/passwd", O_RDONLY, 0, 0, file_open_done, 0))
265 abort (); /* something ent wrong, we will all die!!! */ 276 abort (); /* something went wrong, we will all die!!! */
266 277
267Note that you additionally need to call C<eio_poll> when the C<want_cb> 278Note that you additionally need to call C<eio_poll> when the C<want_cb>
268indicates that requests are ready to be processed. 279indicates that requests are ready to be processed.
280
281=head2 CANCELLING REQUESTS
282
283Sometimes the need for a request goes away before the request is
284finished. In that case, one can cancel the request by a call to
285C<eio_cancel>:
286
287=over 4
288
289=item eio_cancel (eio_req *req)
290
291Cancel the request (and all its subrequests). If the request is currently
292executing it might still continue to execute, and in other cases it might
293still take a while till the request is cancelled.
294
295Even if cancelled, the finish callback will still be invoked - the
296callbacks of all cancellable requests need to check whether the request
297has been cancelled by calling C<EIO_CANCELLED (req)>:
298
299 static int
300 my_eio_cb (eio_req *req)
301 {
302 if (EIO_CANCELLED (req))
303 return 0;
304 }
305
306In addition, cancelled requests will I<either> have C<< req->result >>
307set to C<-1> and C<errno> to C<ECANCELED>, or I<otherwise> they were
308successfully executed, despite being cancelled (e.g. when they have
309already been executed at the time they were cancelled).
310
311C<EIO_CANCELLED> is still true for requests that have successfully
312executed, as long as C<eio_cancel> was called on them at some point.
313
314=back
269 315
270=head2 AVAILABLE REQUESTS 316=head2 AVAILABLE REQUESTS
271 317
272The following request functions are available. I<All> of them return the 318The following request functions are available. I<All> of them return the
273C<eio_req *> on success and C<0> on failure, and I<all> of them have the 319C<eio_req *> on success and C<0> on failure, and I<all> of them have the
… …
369 free (target); 415 free (target);
370 } 416 }
371 417
372=item eio_realpath (const char *path, int pri, eio_cb cb, void *data) 418=item eio_realpath (const char *path, int pri, eio_cb cb, void *data)
373 419
374Similar to the realpath libc function, but unlike that one, result is 420Similar to the realpath libc function, but unlike that one, C<<
375C<-1> on failure and the length of the returned path in C<ptr2> (which is 421req->result >> is C<-1> on failure. On success, the result is the length
376not 0-terminated) - this is similar to readlink. 422of the returned path in C<ptr2> (which is I<NOT> 0-terminated) - this is
423similar to readlink.
377 424
378=item eio_stat (const char *path, int pri, eio_cb cb, void *data) 425=item eio_stat (const char *path, int pri, eio_cb cb, void *data)
379 426
380=item eio_lstat (const char *path, int pri, eio_cb cb, void *data) 427=item eio_lstat (const char *path, int pri, eio_cb cb, void *data)
381 428
382=item eio_fstat (int fd, int pri, eio_cb cb, void *data) 429=item eio_fstat (int fd, int pri, eio_cb cb, void *data)
383 430
384Stats a file - if C<< req->result >> indicates success, then you can 431Stats a file - if C<< req->result >> indicates success, then you can
385access the C<struct stat>-like structure via C<< req->ptr2 >>: 432access the C<struct stat>-like structure via C<< req->ptr2 >>:
386 433
387 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2; 434 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2;
388 435
389=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data) 436=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data)
390 437
391=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data) 438=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data)
392 439
393Stats a filesystem - if C<< req->result >> indicates success, then you can 440Stats a filesystem - if C<< req->result >> indicates success, then you can
394access the C<struct statvfs>-like structure via C<< req->ptr2 >>: 441access the C<struct statvfs>-like structure via C<< req->ptr2 >>:
395 442
396 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2; 443 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2;
397 444
398=back 445=back
399 446
400=head3 READING DIRECTORIES 447=head3 READING DIRECTORIES
401 448
402Reading directories sounds simple, but can be rather demanding, especially 449Reading directories sounds simple, but can be rather demanding, especially
403if you want to do stuff such as traversing a diretcory hierarchy or 450if you want to do stuff such as traversing a directory hierarchy or
404processing all files in a directory. Libeio can assist thess complex tasks 451processing all files in a directory. Libeio can assist these complex tasks
405with it's C<eio_readdir> call. 452with it's C<eio_readdir> call.
406 453
407=over 4 454=over 4
408 455
409=item eio_readdir (const char *path, int flags, int pri, eio_cb cb, void *data) 456=item eio_readdir (const char *path, int flags, int pri, eio_cb cb, void *data)
… …
441 488
442If this flag is specified, then, in addition to the names in C<ptr2>, 489If this flag is specified, then, in addition to the names in C<ptr2>,
443also an array of C<struct eio_dirent> is returned, in C<ptr1>. A C<struct 490also an array of C<struct eio_dirent> is returned, in C<ptr1>. A C<struct
444eio_dirent> looks like this: 491eio_dirent> looks like this:
445 492
446 struct eio_dirent 493 struct eio_dirent
447 { 494 {
448 int nameofs; /* offset of null-terminated name string in (char *)req->ptr2 */ 495 int nameofs; /* offset of null-terminated name string in (char *)req->ptr2 */
449 unsigned short namelen; /* size of filename without trailing 0 */ 496 unsigned short namelen; /* size of filename without trailing 0 */
450 unsigned char type; /* one of EIO_DT_* */ 497 unsigned char type; /* one of EIO_DT_* */
451 signed char score; /* internal use */ 498 signed char score; /* internal use */
452 ino_t inode; /* the inode number, if available, otherwise unspecified */ 499 ino_t inode; /* the inode number, if available, otherwise unspecified */
453 }; 500 };
454 501
455The only members you normally would access are C<nameofs>, which is the 502The only members you normally would access are C<nameofs>, which is the
456byte-offset from C<ptr2> to the start of the name, C<namelen> and C<type>. 503byte-offset from C<ptr2> to the start of the name, C<namelen> and C<type>.
457 504
458C<type> can be one of: 505C<type> can be one of:
… …
501When this flag is specified, then the names will be returned in an order 548When this flag is specified, then the names will be returned in an order
502suitable for stat()'ing each one. That is, when you plan to stat() 549suitable for stat()'ing each one. That is, when you plan to stat()
503all files in the given directory, then the returned order will likely 550all files in the given directory, then the returned order will likely
504be fastest. 551be fastest.
505 552
506If both this flag and C<EIO_READDIR_DIRS_FIRST> are specified, then 553If both this flag and C<EIO_READDIR_DIRS_FIRST> are specified, then the
507the likely dirs come first, resulting in a less optimal stat order. 554likely directories come first, resulting in a less optimal stat order.
508 555
509=item EIO_READDIR_FOUND_UNKNOWN 556=item EIO_READDIR_FOUND_UNKNOWN
510 557
511This flag should not be specified when calling C<eio_readdir>. Instead, 558This flag should not be specified when calling C<eio_readdir>. Instead,
512it is being set by C<eio_readdir> (you can access the C<flags> via C<< 559it is being set by C<eio_readdir> (you can access the C<flags> via C<<
513req->int1 >>, when any of the C<type>'s found were C<EIO_DT_UNKNOWN>. The 560req->int1 >>, when any of the C<type>'s found were C<EIO_DT_UNKNOWN>. The
514absense of this flag therefore indicates that all C<type>'s are known, 561absence of this flag therefore indicates that all C<type>'s are known,
515which can be used to speed up some algorithms. 562which can be used to speed up some algorithms.
516 563
517A typical use case would be to identify all subdirectories within a 564A typical use case would be to identify all subdirectories within a
518directory - you would ask C<eio_readdir> for C<EIO_READDIR_DIRS_FIRST>. If 565directory - you would ask C<eio_readdir> for C<EIO_READDIR_DIRS_FIRST>. If
519then this flag is I<NOT> set, then all the entries at the beginning of the 566then this flag is I<NOT> set, then all the entries at the beginning of the
… …
549=item eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data) 596=item eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data)
550 597
551Calls C<readahead(2)>. If the syscall is missing, then the call is 598Calls C<readahead(2)>. If the syscall is missing, then the call is
552emulated by simply reading the data (currently in 64kiB chunks). 599emulated by simply reading the data (currently in 64kiB chunks).
553 600
601=item eio_syncfs (int fd, int pri, eio_cb cb, void *data)
602
603Calls Linux' C<syncfs> syscall, if available. Returns C<-1> and sets
604C<errno> to C<ENOSYS> if the call is missing I<but still calls sync()>,
605if the C<fd> is C<< >= 0 >>, so you can probe for the availability of the
606syscall with a negative C<fd> argument and checking for C<-1/ENOSYS>.
607
554=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data) 608=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
555 609
556Calls C<sync_file_range>. If the syscall is missing, then this is the same 610Calls C<sync_file_range>. If the syscall is missing, then this is the same
557as calling C<fdatasync>. 611as calling C<fdatasync>.
558 612
559Flags can be any combination of C<EIO_SYNC_FILE_RANGE_WAIT_BEFORE>, 613Flags can be any combination of C<EIO_SYNC_FILE_RANGE_WAIT_BEFORE>,
560C<EIO_SYNC_FILE_RANGE_WRITE> and C<EIO_SYNC_FILE_RANGE_WAIT_AFTER>. 614C<EIO_SYNC_FILE_RANGE_WRITE> and C<EIO_SYNC_FILE_RANGE_WAIT_AFTER>.
615
616=item eio_fallocate (int fd, int mode, off_t offset, off_t len, int pri, eio_cb cb, void *data)
617
618Calls C<fallocate> (note: I<NOT> C<posix_fallocate>!). If the syscall is
619missing, then it returns failure and sets C<errno> to C<ENOSYS>.
620
621The C<mode> argument can be C<0> (for behaviour similar to
622C<posix_fallocate>), or C<EIO_FALLOC_FL_KEEP_SIZE>, which keeps the size
623of the file unchanged (but still preallocates space beyond end of file).
561 624
562=back 625=back
563 626
564=head3 LIBEIO-SPECIFIC REQUESTS 627=head3 LIBEIO-SPECIFIC REQUESTS
565 628
… …
607 670
608 eio_custom (my_open, 0, my_open_done, "/etc/passwd"); 671 eio_custom (my_open, 0, my_open_done, "/etc/passwd");
609 672
610=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data) 673=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data)
611 674
612This is a a request that takes C<delay> seconds to execute, but otherwise 675This is a request that takes C<delay> seconds to execute, but otherwise
613does nothing - it simply puts one of the worker threads to sleep for this 676does nothing - it simply puts one of the worker threads to sleep for this
614long. 677long.
615 678
616This request can be used to artificially increase load, e.g. for debugging 679This request can be used to artificially increase load, e.g. for debugging
617or benchmarking reasons. 680or benchmarking reasons.
… …
633There are two primary use cases for this: a) bundle many requests into a 696There are two primary use cases for this: a) bundle many requests into a
634single, composite, request with a definite callback and the ability to 697single, composite, request with a definite callback and the ability to
635cancel the whole request with its subrequests and b) limiting the number 698cancel the whole request with its subrequests and b) limiting the number
636of "active" requests. 699of "active" requests.
637 700
638Further below you will find more dicussion of these topics - first follows 701Further below you will find more discussion of these topics - first
639the reference section detailing the request generator and other methods. 702follows the reference section detailing the request generator and other
703methods.
640 704
641=over 4 705=over 4
642 706
643=item eio_grp (eio_cb cb, void *data) 707=item eio_req *grp = eio_grp (eio_cb cb, void *data)
644 708
645Creates and submits a group request. 709Creates, submits and returns a group request. Note that it doesn't have a
710priority, unlike all other requests.
646 711
647=back 712=item eio_grp_add (eio_req *grp, eio_req *req)
648 713
714Adds a request to the request group.
715
716=item eio_grp_cancel (eio_req *grp)
717
718Cancels all requests I<in> the group, but I<not> the group request
719itself. You can cancel the group request I<and> all subrequests via a
720normal C<eio_cancel> call.
721
722=back
723
724=head4 GROUP REQUEST LIFETIME
725
726Left alone, a group request will instantly move to the pending state and
727will be finished at the next call of C<eio_poll>.
728
729The usefulness stems from the fact that, if a subrequest is added to a
730group I<before> a call to C<eio_poll>, via C<eio_grp_add>, then the group
731will not finish until all the subrequests have finished.
732
733So the usage cycle of a group request is like this: after it is created,
734you normally instantly add a subrequest. If none is added, the group
735request will finish on it's own. As long as subrequests are added before
736the group request is finished it will be kept from finishing, that is the
737callbacks of any subrequests can, in turn, add more requests to the group,
738and as long as any requests are active, the group request itself will not
739finish.
740
741=head4 CREATING COMPOSITE REQUESTS
742
743Imagine you wanted to create an C<eio_load> request that opens a file,
744reads it and closes it. This means it has to execute at least three eio
745requests, but for various reasons it might be nice if that request looked
746like any other eio request.
747
748This can be done with groups:
749
750=over 4
751
752=item 1) create the request object
753
754Create a group that contains all further requests. This is the request you
755can return as "the load request".
756
757=item 2) open the file, maybe
758
759Next, open the file with C<eio_open> and add the request to the group
760request and you are finished setting up the request.
761
762If, for some reason, you cannot C<eio_open> (path is a null ptr?) you
763can set C<< grp->result >> to C<-1> to signal an error and let the group
764request finish on its own.
765
766=item 3) open callback adds more requests
767
768In the open callback, if the open was not successful, copy C<<
769req->errorno >> to C<< grp->errorno >> and set C<< grp->errorno >> to
770C<-1> to signal an error.
771
772Otherwise, malloc some memory or so and issue a read request, adding the
773read request to the group.
774
775=item 4) continue issuing requests till finished
776
777In the real callback, check for errors and possibly continue with
778C<eio_close> or any other eio request in the same way.
779
780As soon as no new requests are added the group request will finish. Make
781sure you I<always> set C<< grp->result >> to some sensible value.
782
783=back
784
785=head4 REQUEST LIMITING
649 786
650 787
651#TODO 788#TODO
652 789
653/*****************************************************************************/
654/* groups */
655
656eio_req *eio_grp (eio_cb cb, void *data);
657void eio_grp_feed (eio_req *grp, void (*feed)(eio_req *req), int limit);
658void eio_grp_limit (eio_req *grp, int limit); 790void eio_grp_limit (eio_req *grp, int limit);
659void eio_grp_add (eio_req *grp, eio_req *req);
660void eio_grp_cancel (eio_req *grp); /* cancels all sub requests but not the group */
661 791
662 792
663=back 793=back
664 794
665 795
… …
671=head1 ANATOMY AND LIFETIME OF AN EIO REQUEST 801=head1 ANATOMY AND LIFETIME OF AN EIO REQUEST
672 802
673A request is represented by a structure of type C<eio_req>. To initialise 803A request is represented by a structure of type C<eio_req>. To initialise
674it, clear it to all zero bytes: 804it, clear it to all zero bytes:
675 805
676 eio_req req; 806 eio_req req;
677 807
678 memset (&req, 0, sizeof (req)); 808 memset (&req, 0, sizeof (req));
679 809
680A more common way to initialise a new C<eio_req> is to use C<calloc>: 810A more common way to initialise a new C<eio_req> is to use C<calloc>:
681 811
682 eio_req *req = calloc (1, sizeof (*req)); 812 eio_req *req = calloc (1, sizeof (*req));
683 813
684In either case, libeio neither allocates, initialises or frees the 814In either case, libeio neither allocates, initialises or frees the
685C<eio_req> structure for you - it merely uses it. 815C<eio_req> structure for you - it merely uses it.
686 816
687zero 817zero
… …
705for example, in interactive programs, you might want to limit this time to 835for example, in interactive programs, you might want to limit this time to
706C<0.01> seconds or so. 836C<0.01> seconds or so.
707 837
708Note that: 838Note that:
709 839
840=over 4
841
710a) libeio doesn't know how long your request callbacks take, so the time 842=item a) libeio doesn't know how long your request callbacks take, so the
711spent in C<eio_poll> is up to one callback invocation longer then this 843time spent in C<eio_poll> is up to one callback invocation longer then
712interval. 844this interval.
713 845
714b) this is implemented by calling C<gettimeofday> after each request, 846=item b) this is implemented by calling C<gettimeofday> after each
715which can be costly. 847request, which can be costly.
716 848
717c) at least one request will be handled. 849=item c) at least one request will be handled.
850
851=back
718 852
719=item eio_set_max_poll_reqs (unsigned int nreqs) 853=item eio_set_max_poll_reqs (unsigned int nreqs)
720 854
721When C<nreqs> is non-zero, then C<eio_poll> will not handle more than 855When C<nreqs> is non-zero, then C<eio_poll> will not handle more than
722C<nreqs> requests per invocation. This is a less costly way to limit the 856C<nreqs> requests per invocation. This is a less costly way to limit the
… …
792This symbol governs the stack size for each eio thread. Libeio itself 926This symbol governs the stack size for each eio thread. Libeio itself
793was written to use very little stackspace, but when using C<EIO_CUSTOM> 927was written to use very little stackspace, but when using C<EIO_CUSTOM>
794requests, you might want to increase this. 928requests, you might want to increase this.
795 929
796If this symbol is undefined (the default) then libeio will use its default 930If this symbol is undefined (the default) then libeio will use its default
797stack size (C<sizeof (long) * 4096> currently). If it is defined, but 931stack size (C<sizeof (void *) * 4096> currently). If it is defined, but
798C<0>, then the default operating system stack size will be used. In all 932C<0>, then the default operating system stack size will be used. In all
799other cases, the value must be an expression that evaluates to the desired 933other cases, the value must be an expression that evaluates to the desired
800stack size. 934stack size.
801 935
802=back 936=back

Diff Legend

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