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

Comparing libeio/eio.pod (file contents):
Revision 1.12 by root, Wed Jun 29 10:32:55 2011 UTC vs.
Revision 1.35 by root, Mon Aug 18 08:11:54 2014 UTC

25similar functions, as well as less rarely ones such as C<mknod>, C<futime> 25similar functions, as well as less rarely ones such as C<mknod>, C<futime>
26or C<readlink>. 26or C<readlink>.
27 27
28It also offers wrappers around C<sendfile> (Solaris, Linux, HP-UX and 28It also offers wrappers around C<sendfile> (Solaris, Linux, HP-UX and
29FreeBSD, with emulation on other platforms) and C<readahead> (Linux, with 29FreeBSD, with emulation on other platforms) and C<readahead> (Linux, with
30emulation elsewhere>). 30emulation elsewhere).
31 31
32The goal is to enable you to write fully non-blocking programs. For 32The goal is to enable you to write fully non-blocking programs. For
33example, in a game server, you would not want to freeze for a few seconds 33example, in a game server, you would not want to freeze for a few seconds
34just because the server is running a backup and you happen to call 34just because the server is running a backup and you happen to call
35C<readdir>. 35C<readdir>.
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",
124=back 131=back
125 132
126For libev, you would typically use an C<ev_async> watcher: the 133For libev, you would typically use an C<ev_async> watcher: the
127C<want_poll> callback would invoke C<ev_async_send> to wake up the event 134C<want_poll> callback would invoke C<ev_async_send> to wake up the event
128loop. Inside the callback set for the watcher, one would call C<eio_poll 135loop. Inside the callback set for the watcher, one would call C<eio_poll
129()> (followed by C<ev_async_send> again if C<eio_poll> indicates that not 136()>.
130all requests have been handled yet). The race is taken care of because 137
131libev resets/rearms the async watcher before calling your callback, 138If C<eio_poll ()> is configured to not handle all results in one go
132and therefore, before calling C<eio_poll>. This might result in (some) 139(i.e. it returns C<-1>) then you should start an idle watcher that calls
133spurious wake-ups, but is generally harmless. 140C<eio_poll> until it returns something C<!= -1>.
141
142A full-featured connector between libeio and libev would look as follows
143(if C<eio_poll> is handling all requests, it can of course be simplified a
144lot by removing the idle watcher logic):
145
146 static struct ev_loop *loop;
147 static ev_idle repeat_watcher;
148 static ev_async ready_watcher;
149
150 /* idle watcher callback, only used when eio_poll */
151 /* didn't handle all results in one call */
152 static void
153 repeat (EV_P_ ev_idle *w, int revents)
154 {
155 if (eio_poll () != -1)
156 ev_idle_stop (EV_A_ w);
157 }
158
159 /* eio has some results, process them */
160 static void
161 ready (EV_P_ ev_async *w, int revents)
162 {
163 if (eio_poll () == -1)
164 ev_idle_start (EV_A_ &repeat_watcher);
165 }
166
167 /* wake up the event loop */
168 static void
169 want_poll (void)
170 {
171 ev_async_send (loop, &ready_watcher)
172 }
173
174 void
175 my_init_eio ()
176 {
177 loop = EV_DEFAULT;
178
179 ev_idle_init (&repeat_watcher, repeat);
180 ev_async_init (&ready_watcher, ready);
181 ev_async_start (loop, &watcher);
182
183 eio_init (want_poll, 0);
184 }
134 185
135For 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
136loop 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
137C<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
138to 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
139C<eio_poll>. The race is avoided here because the event loop should invoke 190C<eio_poll>.
140your callback again and again until the byte has been read (as the pipe 191
141read callback does not read it, only C<done_poll>). 192You don't have to take special care in the case C<eio_poll> doesn't handle
193all requests, as the done callback will not be invoked, so the event loop
194will still signal readiness for the pipe until I<all> results have been
195processed.
142 196
143 197
144=head1 HIGH LEVEL REQUEST API 198=head1 HIGH LEVEL REQUEST API
145 199
146Libeio has both a high-level API, which consists of calling a request 200Libeio has both a high-level API, which consists of calling a request
179 233
180The 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.
181 235
182=back 236=back
183 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
184The 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
185continue normally. If a callback returns a nonzero value, libeio will 243continue normally. If a callback returns a nonzero value, libeio will
186stop 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
187caller. 245caller.
188 246
189Memory 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
190executes, with the exception of paths, which are being copied 248request executes, with the exception of paths, which are being copied
191internally. Any memory libeio itself allocates will be freed after the 249internally. Any memory libeio itself allocates will be freed after the
192finish 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
193to libeio yourself you can use the low-level API. 251to libeio yourself you can use the low-level API.
194 252
195For example, to open a file, you could do this: 253For example, to open a file, you could do this:
213 } 271 }
214 272
215 /* the first three arguments are passed to open(2) */ 273 /* the first three arguments are passed to open(2) */
216 /* the remaining are priority, callback and data */ 274 /* the remaining are priority, callback and data */
217 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))
218 abort (); /* something ent wrong, we will all die!!! */ 276 abort (); /* something went wrong, we will all die!!! */
219 277
220Note 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>
221indicates 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
295When cancelled, the finish callback will not be invoked.
296
297C<EIO_CANCELLED> is still true for requests that have successfully
298executed, as long as C<eio_cancel> was called on them at some point.
299
300=back
222 301
223=head2 AVAILABLE REQUESTS 302=head2 AVAILABLE REQUESTS
224 303
225The following request functions are available. I<All> of them return the 304The following request functions are available. I<All> of them return the
226C<eio_req *> on success and C<0> on failure, and I<all> of them have the 305C<eio_req *> on success and C<0> on failure, and I<all> of them have the
320 char *target = strndup ((char *)req->ptr2, req->result); 399 char *target = strndup ((char *)req->ptr2, req->result);
321 400
322 free (target); 401 free (target);
323 } 402 }
324 403
404=item eio_realpath (const char *path, int pri, eio_cb cb, void *data)
405
406Similar to the realpath libc function, but unlike that one, C<<
407req->result >> is C<-1> on failure. On success, the result is the length
408of the returned path in C<ptr2> (which is I<NOT> 0-terminated) - this is
409similar to readlink.
410
325=item eio_stat (const char *path, int pri, eio_cb cb, void *data) 411=item eio_stat (const char *path, int pri, eio_cb cb, void *data)
326 412
327=item eio_lstat (const char *path, int pri, eio_cb cb, void *data) 413=item eio_lstat (const char *path, int pri, eio_cb cb, void *data)
328 414
329=item eio_fstat (int fd, int pri, eio_cb cb, void *data) 415=item eio_fstat (int fd, int pri, eio_cb cb, void *data)
330 416
331Stats a file - if C<< req->result >> indicates success, then you can 417Stats a file - if C<< req->result >> indicates success, then you can
332access the C<struct stat>-like structure via C<< req->ptr2 >>: 418access the C<struct stat>-like structure via C<< req->ptr2 >>:
333 419
334 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2; 420 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2;
335 421
336=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data) 422=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data)
337 423
338=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data) 424=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data)
339 425
340Stats a filesystem - if C<< req->result >> indicates success, then you can 426Stats a filesystem - if C<< req->result >> indicates success, then you can
341access the C<struct statvfs>-like structure via C<< req->ptr2 >>: 427access the C<struct statvfs>-like structure via C<< req->ptr2 >>:
342 428
343 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2; 429 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2;
344 430
345=back 431=back
346 432
347=head3 READING DIRECTORIES 433=head3 READING DIRECTORIES
348 434
349Reading directories sounds simple, but can be rather demanding, especially 435Reading directories sounds simple, but can be rather demanding, especially
350if you want to do stuff such as traversing a diretcory hierarchy or 436if you want to do stuff such as traversing a directory hierarchy or
351processing all files in a directory. Libeio can assist thess complex tasks 437processing all files in a directory. Libeio can assist these complex tasks
352with it's C<eio_readdir> call. 438with it's C<eio_readdir> call.
353 439
354=over 4 440=over 4
355 441
356=item eio_readdir (const char *path, int flags, int pri, eio_cb cb, void *data) 442=item eio_readdir (const char *path, int flags, int pri, eio_cb cb, void *data)
388 474
389If this flag is specified, then, in addition to the names in C<ptr2>, 475If this flag is specified, then, in addition to the names in C<ptr2>,
390also an array of C<struct eio_dirent> is returned, in C<ptr1>. A C<struct 476also an array of C<struct eio_dirent> is returned, in C<ptr1>. A C<struct
391eio_dirent> looks like this: 477eio_dirent> looks like this:
392 478
393 struct eio_dirent 479 struct eio_dirent
394 { 480 {
395 int nameofs; /* offset of null-terminated name string in (char *)req->ptr2 */ 481 int nameofs; /* offset of null-terminated name string in (char *)req->ptr2 */
396 unsigned short namelen; /* size of filename without trailing 0 */ 482 unsigned short namelen; /* size of filename without trailing 0 */
397 unsigned char type; /* one of EIO_DT_* */ 483 unsigned char type; /* one of EIO_DT_* */
398 signed char score; /* internal use */ 484 signed char score; /* internal use */
399 ino_t inode; /* the inode number, if available, otherwise unspecified */ 485 ino_t inode; /* the inode number, if available, otherwise unspecified */
400 }; 486 };
401 487
402The only members you normally would access are C<nameofs>, which is the 488The only members you normally would access are C<nameofs>, which is the
403byte-offset from C<ptr2> to the start of the name, C<namelen> and C<type>. 489byte-offset from C<ptr2> to the start of the name, C<namelen> and C<type>.
404 490
405C<type> can be one of: 491C<type> can be one of:
448When this flag is specified, then the names will be returned in an order 534When this flag is specified, then the names will be returned in an order
449suitable for stat()'ing each one. That is, when you plan to stat() 535suitable for stat()'ing each one. That is, when you plan to stat()
450all files in the given directory, then the returned order will likely 536all files in the given directory, then the returned order will likely
451be fastest. 537be fastest.
452 538
453If both this flag and C<EIO_READDIR_DIRS_FIRST> are specified, then 539If both this flag and C<EIO_READDIR_DIRS_FIRST> are specified, then the
454the likely dirs come first, resulting in a less optimal stat order. 540likely directories come first, resulting in a less optimal stat order.
455 541
456=item EIO_READDIR_FOUND_UNKNOWN 542=item EIO_READDIR_FOUND_UNKNOWN
457 543
458This flag should not be specified when calling C<eio_readdir>. Instead, 544This flag should not be specified when calling C<eio_readdir>. Instead,
459it is being set by C<eio_readdir> (you can access the C<flags> via C<< 545it is being set by C<eio_readdir> (you can access the C<flags> via C<<
460req->int1 >>, when any of the C<type>'s found were C<EIO_DT_UNKNOWN>. The 546req->int1 >>, when any of the C<type>'s found were C<EIO_DT_UNKNOWN>. The
461absense of this flag therefore indicates that all C<type>'s are known, 547absence of this flag therefore indicates that all C<type>'s are known,
462which can be used to speed up some algorithms. 548which can be used to speed up some algorithms.
463 549
464A typical use case would be to identify all subdirectories within a 550A typical use case would be to identify all subdirectories within a
465directory - you would ask C<eio_readdir> for C<EIO_READDIR_DIRS_FIRST>. If 551directory - you would ask C<eio_readdir> for C<EIO_READDIR_DIRS_FIRST>. If
466then this flag is I<NOT> set, then all the entries at the beginning of the 552then this flag is I<NOT> set, then all the entries at the beginning of the
496=item eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data) 582=item eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data)
497 583
498Calls C<readahead(2)>. If the syscall is missing, then the call is 584Calls C<readahead(2)>. If the syscall is missing, then the call is
499emulated by simply reading the data (currently in 64kiB chunks). 585emulated by simply reading the data (currently in 64kiB chunks).
500 586
587=item eio_syncfs (int fd, int pri, eio_cb cb, void *data)
588
589Calls Linux' C<syncfs> syscall, if available. Returns C<-1> and sets
590C<errno> to C<ENOSYS> if the call is missing I<but still calls sync()>,
591if the C<fd> is C<< >= 0 >>, so you can probe for the availability of the
592syscall with a negative C<fd> argument and checking for C<-1/ENOSYS>.
593
501=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data) 594=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
502 595
503Calls C<sync_file_range>. If the syscall is missing, then this is the same 596Calls C<sync_file_range>. If the syscall is missing, then this is the same
504as calling C<fdatasync>. 597as calling C<fdatasync>.
505 598
506Flags can be any combination of C<EIO_SYNC_FILE_RANGE_WAIT_BEFORE>, 599Flags 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>. 600C<EIO_SYNC_FILE_RANGE_WRITE> and C<EIO_SYNC_FILE_RANGE_WAIT_AFTER>.
508 601
602=item eio_fallocate (int fd, int mode, off_t offset, off_t len, int pri, eio_cb cb, void *data)
603
604Calls C<fallocate> (note: I<NOT> C<posix_fallocate>!). If the syscall is
605missing, then it returns failure and sets C<errno> to C<ENOSYS>.
606
607The C<mode> argument can be C<0> (for behaviour similar to
608C<posix_fallocate>), or C<EIO_FALLOC_FL_KEEP_SIZE>, which keeps the size
609of the file unchanged (but still preallocates space beyond end of file).
610
509=back 611=back
510 612
511=head3 LIBEIO-SPECIFIC REQUESTS 613=head3 LIBEIO-SPECIFIC REQUESTS
512 614
513These requests are specific to libeio and do not correspond to any OS call. 615These requests are specific to libeio and do not correspond to any OS call.
514 616
515=over 4 617=over 4
516 618
517=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data) 619=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
518 620
519Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY) the given 621Reads (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 622memory area, page-wise, that is, it reads (or reads and writes back) the
521first octet of every page that spans the memory area. 623first octet of every page that spans the memory area.
522 624
523This can be used to page in some mmapped file, or dirty some pages. Note 625This 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 626that dirtying is an unlocked read-write access, so races can ensue when
554 656
555 eio_custom (my_open, 0, my_open_done, "/etc/passwd"); 657 eio_custom (my_open, 0, my_open_done, "/etc/passwd");
556 658
557=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data) 659=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data)
558 660
559This is a a request that takes C<delay> seconds to execute, but otherwise 661This is a request that takes C<delay> seconds to execute, but otherwise
560does nothing - it simply puts one of the worker threads to sleep for this 662does nothing - it simply puts one of the worker threads to sleep for this
561long. 663long.
562 664
563This request can be used to artificially increase load, e.g. for debugging 665This request can be used to artificially increase load, e.g. for debugging
564or benchmarking reasons. 666or benchmarking reasons.
580There are two primary use cases for this: a) bundle many requests into a 682There are two primary use cases for this: a) bundle many requests into a
581single, composite, request with a definite callback and the ability to 683single, composite, request with a definite callback and the ability to
582cancel the whole request with its subrequests and b) limiting the number 684cancel the whole request with its subrequests and b) limiting the number
583of "active" requests. 685of "active" requests.
584 686
585Further below you will find more dicussion of these topics - first follows 687Further below you will find more discussion of these topics - first
586the reference section detailing the request generator and other methods. 688follows the reference section detailing the request generator and other
689methods.
587 690
588=over 4 691=over 4
589 692
590=item eio_grp (eio_cb cb, void *data) 693=item eio_req *grp = eio_grp (eio_cb cb, void *data)
591 694
592Creates and submits a group request. 695Creates, submits and returns a group request. Note that it doesn't have a
696priority, unlike all other requests.
593 697
594=back 698=item eio_grp_add (eio_req *grp, eio_req *req)
595 699
700Adds a request to the request group.
701
702=item eio_grp_cancel (eio_req *grp)
703
704Cancels all requests I<in> the group, but I<not> the group request
705itself. You can cancel the group request I<and> all subrequests via a
706normal C<eio_cancel> call.
707
708=back
709
710=head4 GROUP REQUEST LIFETIME
711
712Left alone, a group request will instantly move to the pending state and
713will be finished at the next call of C<eio_poll>.
714
715The usefulness stems from the fact that, if a subrequest is added to a
716group I<before> a call to C<eio_poll>, via C<eio_grp_add>, then the group
717will not finish until all the subrequests have finished.
718
719So the usage cycle of a group request is like this: after it is created,
720you normally instantly add a subrequest. If none is added, the group
721request will finish on it's own. As long as subrequests are added before
722the group request is finished it will be kept from finishing, that is the
723callbacks of any subrequests can, in turn, add more requests to the group,
724and as long as any requests are active, the group request itself will not
725finish.
726
727=head4 CREATING COMPOSITE REQUESTS
728
729Imagine you wanted to create an C<eio_load> request that opens a file,
730reads it and closes it. This means it has to execute at least three eio
731requests, but for various reasons it might be nice if that request looked
732like any other eio request.
733
734This can be done with groups:
735
736=over 4
737
738=item 1) create the request object
739
740Create a group that contains all further requests. This is the request you
741can return as "the load request".
742
743=item 2) open the file, maybe
744
745Next, open the file with C<eio_open> and add the request to the group
746request and you are finished setting up the request.
747
748If, for some reason, you cannot C<eio_open> (path is a null ptr?) you
749can set C<< grp->result >> to C<-1> to signal an error and let the group
750request finish on its own.
751
752=item 3) open callback adds more requests
753
754In the open callback, if the open was not successful, copy C<<
755req->errorno >> to C<< grp->errorno >> and set C<< grp->result >> to
756C<-1> to signal an error.
757
758Otherwise, malloc some memory or so and issue a read request, adding the
759read request to the group.
760
761=item 4) continue issuing requests till finished
762
763In the read callback, check for errors and possibly continue with
764C<eio_close> or any other eio request in the same way.
765
766As soon as no new requests are added, the group request will finish. Make
767sure you I<always> set C<< grp->result >> to some sensible value.
768
769=back
770
771=head4 REQUEST LIMITING
596 772
597 773
598#TODO 774#TODO
599 775
600/*****************************************************************************/
601/* groups */
602
603eio_req *eio_grp (eio_cb cb, void *data);
604void eio_grp_feed (eio_req *grp, void (*feed)(eio_req *req), int limit);
605void eio_grp_limit (eio_req *grp, int limit); 776void eio_grp_limit (eio_req *grp, int limit);
606void eio_grp_add (eio_req *grp, eio_req *req);
607void eio_grp_cancel (eio_req *grp); /* cancels all sub requests but not the group */
608 777
609
610=back
611 778
612 779
613=head1 LOW LEVEL REQUEST API 780=head1 LOW LEVEL REQUEST API
614 781
615#TODO 782#TODO
618=head1 ANATOMY AND LIFETIME OF AN EIO REQUEST 785=head1 ANATOMY AND LIFETIME OF AN EIO REQUEST
619 786
620A request is represented by a structure of type C<eio_req>. To initialise 787A request is represented by a structure of type C<eio_req>. To initialise
621it, clear it to all zero bytes: 788it, clear it to all zero bytes:
622 789
623 eio_req req; 790 eio_req req;
624 791
625 memset (&req, 0, sizeof (req)); 792 memset (&req, 0, sizeof (req));
626 793
627A more common way to initialise a new C<eio_req> is to use C<calloc>: 794A more common way to initialise a new C<eio_req> is to use C<calloc>:
628 795
629 eio_req *req = calloc (1, sizeof (*req)); 796 eio_req *req = calloc (1, sizeof (*req));
630 797
631In either case, libeio neither allocates, initialises or frees the 798In either case, libeio neither allocates, initialises or frees the
632C<eio_req> structure for you - it merely uses it. 799C<eio_req> structure for you - it merely uses it.
633 800
634zero 801zero
652for example, in interactive programs, you might want to limit this time to 819for example, in interactive programs, you might want to limit this time to
653C<0.01> seconds or so. 820C<0.01> seconds or so.
654 821
655Note that: 822Note that:
656 823
824=over 4
825
657a) libeio doesn't know how long your request callbacks take, so the time 826=item a) libeio doesn't know how long your request callbacks take, so the
658spent in C<eio_poll> is up to one callback invocation longer then this 827time spent in C<eio_poll> is up to one callback invocation longer then
659interval. 828this interval.
660 829
661b) this is implemented by calling C<gettimeofday> after each request, 830=item b) this is implemented by calling C<gettimeofday> after each
662which can be costly. 831request, which can be costly.
663 832
664c) at least one request will be handled. 833=item c) at least one request will be handled.
834
835=back
665 836
666=item eio_set_max_poll_reqs (unsigned int nreqs) 837=item eio_set_max_poll_reqs (unsigned int nreqs)
667 838
668When C<nreqs> is non-zero, then C<eio_poll> will not handle more than 839When 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 840C<nreqs> requests per invocation. This is a less costly way to limit the
739This symbol governs the stack size for each eio thread. Libeio itself 910This symbol governs the stack size for each eio thread. Libeio itself
740was written to use very little stackspace, but when using C<EIO_CUSTOM> 911was written to use very little stackspace, but when using C<EIO_CUSTOM>
741requests, you might want to increase this. 912requests, you might want to increase this.
742 913
743If this symbol is undefined (the default) then libeio will use its default 914If this symbol is undefined (the default) then libeio will use its default
744stack size (C<sizeof (long) * 4096> currently). If it is defined, but 915stack size (C<sizeof (void *) * 4096> currently). In all other cases, the
745C<0>, then the default operating system stack size will be used. In all
746other cases, the value must be an expression that evaluates to the desired 916value must be an expression that evaluates to the desired stack size.
747stack size.
748 917
749=back 918=back
750 919
751 920
752=head1 PORTABILITY REQUIREMENTS 921=head1 PORTABILITY REQUIREMENTS

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines