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.36 by root, Sun Jan 24 16:36:20 2016 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",
… …
97This callback is invoked when libeio detects that all pending requests 104This callback is invoked when libeio detects that all pending requests
98have been handled. It is "edge-triggered", that is, it will only be 105have been handled. It is "edge-triggered", that is, it will only be
99called once after C<want_poll>. To put it differently, C<want_poll> and 106called once after C<want_poll>. To put it differently, C<want_poll> and
100C<done_poll> are invoked in pairs: after C<want_poll> you have to call 107C<done_poll> are invoked in pairs: after C<want_poll> you have to call
101C<eio_poll ()> until either C<eio_poll> indicates that everything has been 108C<eio_poll ()> until either C<eio_poll> indicates that everything has been
102handled or C<done_poll> has been called, which signals the same. 109handled or C<done_poll> has been called, which signals the same - only one
110method is needed.
103 111
104Note that C<eio_poll> might return after C<done_poll> and C<want_poll> 112Note that C<eio_poll> might return after C<done_poll> and C<want_poll>
105have been called again, so watch out for races in your code. 113have been called again, so watch out for races in your code.
106 114
115It is quite common to have an empty C<done_call> callback and only use
116the return value from C<eio_poll>, or, when C<eio_poll> is configured to
117handle all outstanding replies, it's enough to call C<eio_poll> once.
118
107As with C<want_poll>, this callback is called while locks are being held, 119As with C<want_poll>, this callback is called while locks are being held,
108so you I<must not call any libeio functions form within this callback>. 120so you I<must not call any libeio functions from within this callback>.
109 121
110=item int eio_poll () 122=item int eio_poll ()
111 123
112This function has to be called whenever there are pending requests that 124This function has to be called whenever there are pending requests that
113need finishing. You usually call this after C<want_poll> has indicated 125need finishing. You usually call this after C<want_poll> has indicated
… …
130 142
131If C<eio_poll ()> is configured to not handle all results in one go 143If 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 144(i.e. it returns C<-1>) then you should start an idle watcher that calls
133C<eio_poll> until it returns something C<!= -1>. 145C<eio_poll> until it returns something C<!= -1>.
134 146
135A full-featured conenctor between libeio and libev would look as follows 147A 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 148(if C<eio_poll> is handling all requests, it can of course be simplified a
137lot by removing the idle watcher logic): 149lot by removing the idle watcher logic):
138 150
139 static struct ev_loop *loop; 151 static struct ev_loop *loop;
140 static ev_idle repeat_watcher; 152 static ev_idle repeat_watcher;
141 static ev_async ready_watcher; 153 static ev_async ready_watcher;
142 154
143 /* idle watcher callback, only used when eio_poll */ 155 /* idle watcher callback, only used when eio_poll */
144 /* didn't handle all results in one call */ 156 /* didn't handle all results in one call */
145 static void 157 static void
146 repeat (EV_P_ ev_idle *w, int revents) 158 repeat (EV_P_ ev_idle *w, int revents)
147 { 159 {
148 if (eio_poll () != -1) 160 if (eio_poll () != -1)
149 ev_idle_stop (EV_A_ w); 161 ev_idle_stop (EV_A_ w);
150 } 162 }
151 163
152 /* eio has some results, process them */ 164 /* eio has some results, process them */
153 static void 165 static void
154 ready (EV_P_ ev_async *w, int revents) 166 ready (EV_P_ ev_async *w, int revents)
155 { 167 {
156 if (eio_poll () == -1) 168 if (eio_poll () == -1)
157 ev_idle_start (EV_A_ &repeat_watcher); 169 ev_idle_start (EV_A_ &repeat_watcher);
158 } 170 }
159 171
160 /* wake up the event loop */ 172 /* wake up the event loop */
161 static void 173 static void
162 want_poll (void) 174 want_poll (void)
163 { 175 {
164 ev_async_send (loop, &ready_watcher) 176 ev_async_send (loop, &ready_watcher)
165 } 177 }
166 178
167 void 179 void
168 my_init_eio () 180 my_init_eio ()
169 { 181 {
170 loop = EV_DEFAULT; 182 loop = EV_DEFAULT;
171 183
172 ev_idle_init (&repeat_watcher, repeat); 184 ev_idle_init (&repeat_watcher, repeat);
173 ev_async_init (&ready_watcher, ready); 185 ev_async_init (&ready_watcher, ready);
174 ev_async_start (loop &watcher); 186 ev_async_start (loop, &watcher);
175 187
176 eio_init (want_poll, 0); 188 eio_init (want_poll, 0);
177 } 189 }
178 190
179For most other event loops, you would typically use a pipe - the event 191For 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 192loop 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 193C<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 194to read that byte, and in the callback for the read end, you would call
183C<eio_poll>. 195C<eio_poll>.
184 196
185You don't have to take special care in the case C<eio_poll> doesn't handle 197You 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 198all 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 199will still signal readiness for the pipe until I<all> results have been
188processed. 200processed.
189 201
190 202
191=head1 HIGH LEVEL REQUEST API 203=head1 HIGH LEVEL REQUEST API
192 204
… …
226 238
227The C<void *data> member simply stores the value of the C<data> argument. 239The C<void *data> member simply stores the value of the C<data> argument.
228 240
229=back 241=back
230 242
243Members not explicitly described as accessible must not be
244accessed. Specifically, there is no guarantee that any members will still
245have the value they had when the request was submitted.
246
231The return value of the callback is normally C<0>, which tells libeio to 247The return value of the callback is normally C<0>, which tells libeio to
232continue normally. If a callback returns a nonzero value, libeio will 248continue normally. If a callback returns a nonzero value, libeio will
233stop processing results (in C<eio_poll>) and will return the value to its 249stop processing results (in C<eio_poll>) and will return the value to its
234caller. 250caller.
235 251
236Memory areas passed to libeio must stay valid as long as a request 252Memory areas passed to libeio wrappers must stay valid as long as a
237executes, with the exception of paths, which are being copied 253request executes, with the exception of paths, which are being copied
238internally. Any memory libeio itself allocates will be freed after the 254internally. Any memory libeio itself allocates will be freed after the
239finish callback has been called. If you want to manage all memory passed 255finish callback has been called. If you want to manage all memory passed
240to libeio yourself you can use the low-level API. 256to libeio yourself you can use the low-level API.
241 257
242For example, to open a file, you could do this: 258For example, to open a file, you could do this:
… …
260 } 276 }
261 277
262 /* the first three arguments are passed to open(2) */ 278 /* the first three arguments are passed to open(2) */
263 /* the remaining are priority, callback and data */ 279 /* the remaining are priority, callback and data */
264 if (!eio_open ("/etc/passwd", O_RDONLY, 0, 0, file_open_done, 0)) 280 if (!eio_open ("/etc/passwd", O_RDONLY, 0, 0, file_open_done, 0))
265 abort (); /* something ent wrong, we will all die!!! */ 281 abort (); /* something went wrong, we will all die!!! */
266 282
267Note that you additionally need to call C<eio_poll> when the C<want_cb> 283Note that you additionally need to call C<eio_poll> when the C<want_cb>
268indicates that requests are ready to be processed. 284indicates that requests are ready to be processed.
285
286=head2 CANCELLING REQUESTS
287
288Sometimes the need for a request goes away before the request is
289finished. In that case, one can cancel the request by a call to
290C<eio_cancel>:
291
292=over 4
293
294=item eio_cancel (eio_req *req)
295
296Cancel the request (and all its subrequests). If the request is currently
297executing it might still continue to execute, and in other cases it might
298still take a while till the request is cancelled.
299
300When cancelled, the finish callback will not be invoked.
301
302C<EIO_CANCELLED> is still true for requests that have successfully
303executed, as long as C<eio_cancel> was called on them at some point.
304
305=back
269 306
270=head2 AVAILABLE REQUESTS 307=head2 AVAILABLE REQUESTS
271 308
272The following request functions are available. I<All> of them return the 309The 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 310C<eio_req *> on success and C<0> on failure, and I<all> of them have the
… …
369 free (target); 406 free (target);
370 } 407 }
371 408
372=item eio_realpath (const char *path, int pri, eio_cb cb, void *data) 409=item eio_realpath (const char *path, int pri, eio_cb cb, void *data)
373 410
374Similar to the realpath libc function, but unlike that one, result is 411Similar 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 412req->result >> is C<-1> on failure. On success, the result is the length
376not 0-terminated) - this is similar to readlink. 413of the returned path in C<ptr2> (which is I<NOT> 0-terminated) - this is
414similar to readlink.
377 415
378=item eio_stat (const char *path, int pri, eio_cb cb, void *data) 416=item eio_stat (const char *path, int pri, eio_cb cb, void *data)
379 417
380=item eio_lstat (const char *path, int pri, eio_cb cb, void *data) 418=item eio_lstat (const char *path, int pri, eio_cb cb, void *data)
381 419
382=item eio_fstat (int fd, int pri, eio_cb cb, void *data) 420=item eio_fstat (int fd, int pri, eio_cb cb, void *data)
383 421
384Stats a file - if C<< req->result >> indicates success, then you can 422Stats a file - if C<< req->result >> indicates success, then you can
385access the C<struct stat>-like structure via C<< req->ptr2 >>: 423access the C<struct stat>-like structure via C<< req->ptr2 >>:
386 424
387 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2; 425 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2;
388 426
389=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data) 427=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data)
390 428
391=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data) 429=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data)
392 430
393Stats a filesystem - if C<< req->result >> indicates success, then you can 431Stats a filesystem - if C<< req->result >> indicates success, then you can
394access the C<struct statvfs>-like structure via C<< req->ptr2 >>: 432access the C<struct statvfs>-like structure via C<< req->ptr2 >>:
395 433
396 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2; 434 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2;
397 435
398=back 436=back
399 437
400=head3 READING DIRECTORIES 438=head3 READING DIRECTORIES
401 439
402Reading directories sounds simple, but can be rather demanding, especially 440Reading directories sounds simple, but can be rather demanding, especially
403if you want to do stuff such as traversing a diretcory hierarchy or 441if you want to do stuff such as traversing a directory hierarchy or
404processing all files in a directory. Libeio can assist thess complex tasks 442processing all files in a directory. Libeio can assist these complex tasks
405with it's C<eio_readdir> call. 443with it's C<eio_readdir> call.
406 444
407=over 4 445=over 4
408 446
409=item eio_readdir (const char *path, int flags, int pri, eio_cb cb, void *data) 447=item eio_readdir (const char *path, int flags, int pri, eio_cb cb, void *data)
… …
441 479
442If this flag is specified, then, in addition to the names in C<ptr2>, 480If 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 481also an array of C<struct eio_dirent> is returned, in C<ptr1>. A C<struct
444eio_dirent> looks like this: 482eio_dirent> looks like this:
445 483
446 struct eio_dirent 484 struct eio_dirent
447 { 485 {
448 int nameofs; /* offset of null-terminated name string in (char *)req->ptr2 */ 486 int nameofs; /* offset of null-terminated name string in (char *)req->ptr2 */
449 unsigned short namelen; /* size of filename without trailing 0 */ 487 unsigned short namelen; /* size of filename without trailing 0 */
450 unsigned char type; /* one of EIO_DT_* */ 488 unsigned char type; /* one of EIO_DT_* */
451 signed char score; /* internal use */ 489 signed char score; /* internal use */
452 ino_t inode; /* the inode number, if available, otherwise unspecified */ 490 ino_t inode; /* the inode number, if available, otherwise unspecified */
453 }; 491 };
454 492
455The only members you normally would access are C<nameofs>, which is the 493The 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>. 494byte-offset from C<ptr2> to the start of the name, C<namelen> and C<type>.
457 495
458C<type> can be one of: 496C<type> can be one of:
… …
501When this flag is specified, then the names will be returned in an order 539When 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() 540suitable for stat()'ing each one. That is, when you plan to stat()
503all files in the given directory, then the returned order will likely 541all files in the given directory, then the returned order will likely
504be fastest. 542be fastest.
505 543
506If both this flag and C<EIO_READDIR_DIRS_FIRST> are specified, then 544If 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. 545likely directories come first, resulting in a less optimal stat order.
508 546
509=item EIO_READDIR_FOUND_UNKNOWN 547=item EIO_READDIR_FOUND_UNKNOWN
510 548
511This flag should not be specified when calling C<eio_readdir>. Instead, 549This 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<< 550it 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 551req->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, 552absence of this flag therefore indicates that all C<type>'s are known,
515which can be used to speed up some algorithms. 553which can be used to speed up some algorithms.
516 554
517A typical use case would be to identify all subdirectories within a 555A 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 556directory - 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 557then 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) 587=item eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data)
550 588
551Calls C<readahead(2)>. If the syscall is missing, then the call is 589Calls C<readahead(2)>. If the syscall is missing, then the call is
552emulated by simply reading the data (currently in 64kiB chunks). 590emulated by simply reading the data (currently in 64kiB chunks).
553 591
592=item eio_syncfs (int fd, int pri, eio_cb cb, void *data)
593
594Calls Linux' C<syncfs> syscall, if available. Returns C<-1> and sets
595C<errno> to C<ENOSYS> if the call is missing I<but still calls sync()>,
596if the C<fd> is C<< >= 0 >>, so you can probe for the availability of the
597syscall with a negative C<fd> argument and checking for C<-1/ENOSYS>.
598
554=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data) 599=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
555 600
556Calls C<sync_file_range>. If the syscall is missing, then this is the same 601Calls C<sync_file_range>. If the syscall is missing, then this is the same
557as calling C<fdatasync>. 602as calling C<fdatasync>.
558 603
559Flags can be any combination of C<EIO_SYNC_FILE_RANGE_WAIT_BEFORE>, 604Flags 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>. 605C<EIO_SYNC_FILE_RANGE_WRITE> and C<EIO_SYNC_FILE_RANGE_WAIT_AFTER>.
561 606
607=item eio_fallocate (int fd, int mode, off_t offset, off_t len, int pri, eio_cb cb, void *data)
608
609Calls C<fallocate> (note: I<NOT> C<posix_fallocate>!). If the syscall is
610missing, then it returns failure and sets C<errno> to C<ENOSYS>.
611
612The C<mode> argument can be C<0> (for behaviour similar to
613C<posix_fallocate>), or C<EIO_FALLOC_FL_KEEP_SIZE>, which keeps the size
614of the file unchanged (but still preallocates space beyond end of file).
615
562=back 616=back
563 617
564=head3 LIBEIO-SPECIFIC REQUESTS 618=head3 LIBEIO-SPECIFIC REQUESTS
565 619
566These requests are specific to libeio and do not correspond to any OS call. 620These requests are specific to libeio and do not correspond to any OS call.
567 621
568=over 4 622=over 4
569 623
570=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data) 624=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
571 625
572Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY) the given 626Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY>) the given
573memory area, page-wise, that is, it reads (or reads and writes back) the 627memory area, page-wise, that is, it reads (or reads and writes back) the
574first octet of every page that spans the memory area. 628first octet of every page that spans the memory area.
575 629
576This can be used to page in some mmapped file, or dirty some pages. Note 630This can be used to page in some mmapped file, or dirty some pages. Note
577that dirtying is an unlocked read-write access, so races can ensue when 631that dirtying is an unlocked read-write access, so races can ensue when
… …
607 661
608 eio_custom (my_open, 0, my_open_done, "/etc/passwd"); 662 eio_custom (my_open, 0, my_open_done, "/etc/passwd");
609 663
610=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data) 664=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data)
611 665
612This is a a request that takes C<delay> seconds to execute, but otherwise 666This 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 667does nothing - it simply puts one of the worker threads to sleep for this
614long. 668long.
615 669
616This request can be used to artificially increase load, e.g. for debugging 670This request can be used to artificially increase load, e.g. for debugging
617or benchmarking reasons. 671or benchmarking reasons.
… …
633There are two primary use cases for this: a) bundle many requests into a 687There are two primary use cases for this: a) bundle many requests into a
634single, composite, request with a definite callback and the ability to 688single, composite, request with a definite callback and the ability to
635cancel the whole request with its subrequests and b) limiting the number 689cancel the whole request with its subrequests and b) limiting the number
636of "active" requests. 690of "active" requests.
637 691
638Further below you will find more dicussion of these topics - first follows 692Further below you will find more discussion of these topics - first
639the reference section detailing the request generator and other methods. 693follows the reference section detailing the request generator and other
694methods.
640 695
641=over 4 696=over 4
642 697
643=item eio_grp (eio_cb cb, void *data) 698=item eio_req *grp = eio_grp (eio_cb cb, void *data)
644 699
645Creates and submits a group request. 700Creates, submits and returns a group request. Note that it doesn't have a
701priority, unlike all other requests.
646 702
647=back 703=item eio_grp_add (eio_req *grp, eio_req *req)
648 704
705Adds a request to the request group.
706
707=item eio_grp_cancel (eio_req *grp)
708
709Cancels all requests I<in> the group, but I<not> the group request
710itself. You can cancel the group request I<and> all subrequests via a
711normal C<eio_cancel> call.
712
713=back
714
715=head4 GROUP REQUEST LIFETIME
716
717Left alone, a group request will instantly move to the pending state and
718will be finished at the next call of C<eio_poll>.
719
720The usefulness stems from the fact that, if a subrequest is added to a
721group I<before> a call to C<eio_poll>, via C<eio_grp_add>, then the group
722will not finish until all the subrequests have finished.
723
724So the usage cycle of a group request is like this: after it is created,
725you normally instantly add a subrequest. If none is added, the group
726request will finish on it's own. As long as subrequests are added before
727the group request is finished it will be kept from finishing, that is the
728callbacks of any subrequests can, in turn, add more requests to the group,
729and as long as any requests are active, the group request itself will not
730finish.
731
732=head4 CREATING COMPOSITE REQUESTS
733
734Imagine you wanted to create an C<eio_load> request that opens a file,
735reads it and closes it. This means it has to execute at least three eio
736requests, but for various reasons it might be nice if that request looked
737like any other eio request.
738
739This can be done with groups:
740
741=over 4
742
743=item 1) create the request object
744
745Create a group that contains all further requests. This is the request you
746can return as "the load request".
747
748=item 2) open the file, maybe
749
750Next, open the file with C<eio_open> and add the request to the group
751request and you are finished setting up the request.
752
753If, for some reason, you cannot C<eio_open> (path is a null ptr?) you
754can set C<< grp->result >> to C<-1> to signal an error and let the group
755request finish on its own.
756
757=item 3) open callback adds more requests
758
759In the open callback, if the open was not successful, copy C<<
760req->errorno >> to C<< grp->errorno >> and set C<< grp->result >> to
761C<-1> to signal an error.
762
763Otherwise, malloc some memory or so and issue a read request, adding the
764read request to the group.
765
766=item 4) continue issuing requests till finished
767
768In the read callback, check for errors and possibly continue with
769C<eio_close> or any other eio request in the same way.
770
771As soon as no new requests are added, the group request will finish. Make
772sure you I<always> set C<< grp->result >> to some sensible value.
773
774=back
775
776=head4 REQUEST LIMITING
649 777
650 778
651#TODO 779#TODO
652 780
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); 781void 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 782
662
663=back
664 783
665 784
666=head1 LOW LEVEL REQUEST API 785=head1 LOW LEVEL REQUEST API
667 786
668#TODO 787#TODO
… …
671=head1 ANATOMY AND LIFETIME OF AN EIO REQUEST 790=head1 ANATOMY AND LIFETIME OF AN EIO REQUEST
672 791
673A request is represented by a structure of type C<eio_req>. To initialise 792A request is represented by a structure of type C<eio_req>. To initialise
674it, clear it to all zero bytes: 793it, clear it to all zero bytes:
675 794
676 eio_req req; 795 eio_req req;
677 796
678 memset (&req, 0, sizeof (req)); 797 memset (&req, 0, sizeof (req));
679 798
680A more common way to initialise a new C<eio_req> is to use C<calloc>: 799A more common way to initialise a new C<eio_req> is to use C<calloc>:
681 800
682 eio_req *req = calloc (1, sizeof (*req)); 801 eio_req *req = calloc (1, sizeof (*req));
683 802
684In either case, libeio neither allocates, initialises or frees the 803In either case, libeio neither allocates, initialises or frees the
685C<eio_req> structure for you - it merely uses it. 804C<eio_req> structure for you - it merely uses it.
686 805
687zero 806zero
… …
705for example, in interactive programs, you might want to limit this time to 824for example, in interactive programs, you might want to limit this time to
706C<0.01> seconds or so. 825C<0.01> seconds or so.
707 826
708Note that: 827Note that:
709 828
829=over 4
830
710a) libeio doesn't know how long your request callbacks take, so the time 831=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 832time spent in C<eio_poll> is up to one callback invocation longer then
712interval. 833this interval.
713 834
714b) this is implemented by calling C<gettimeofday> after each request, 835=item b) this is implemented by calling C<gettimeofday> after each
715which can be costly. 836request, which can be costly.
716 837
717c) at least one request will be handled. 838=item c) at least one request will be handled.
839
840=back
718 841
719=item eio_set_max_poll_reqs (unsigned int nreqs) 842=item eio_set_max_poll_reqs (unsigned int nreqs)
720 843
721When C<nreqs> is non-zero, then C<eio_poll> will not handle more than 844When 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 845C<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 915This symbol governs the stack size for each eio thread. Libeio itself
793was written to use very little stackspace, but when using C<EIO_CUSTOM> 916was written to use very little stackspace, but when using C<EIO_CUSTOM>
794requests, you might want to increase this. 917requests, you might want to increase this.
795 918
796If this symbol is undefined (the default) then libeio will use its default 919If this symbol is undefined (the default) then libeio will use its default
797stack size (C<sizeof (long) * 4096> currently). If it is defined, but 920stack size (C<sizeof (void *) * 4096> currently). In all other cases, the
798C<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 921value must be an expression that evaluates to the desired stack size.
800stack size.
801 922
802=back 923=back
803 924
804 925
805=head1 PORTABILITY REQUIREMENTS 926=head1 PORTABILITY REQUIREMENTS

Diff Legend

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