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

Comparing libeio/eio.pod (file contents):
Revision 1.9 by root, Sun Jun 5 23:07:46 2011 UTC vs.
Revision 1.17 by root, Tue Jul 5 18:59:28 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: 50Calling C<fork ()> is fully supported by this module - but you must not
51rely on this. It is currently implemented in these steps:
51 52
52 1. wait till all requests in "execute" state have been handled 53 1. wait till all requests in "execute" state have been handled
53 (basically requests that are already handed over to the kernel). 54 (basically requests that are already handed over to the kernel).
54 2. fork 55 2. fork
55 3. in the parent, continue business as usual, done 56 3. in the parent, continue business as usual, done
56 4. in the child, destroy all ready and pending requests and free the 57 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 memory used by the worker threads. This gives you a fully empty
58 libeio queue. 59 libeio queue.
59 60
60Note, however, since libeio does use threads, thr above guarantee doesn't 61Note, however, since libeio does use threads, the above guarantee doesn't
61cover your libc, for example, malloc and other libc functions are not 62cover your libc, for example, malloc and other libc functions are not
62fork-safe, so there is very little you can do after a fork, and in fatc, 63fork-safe, so there is very little you can do after a fork, and in fact,
63the above might crash, and thus change. 64the above might crash, and thus change.
64 65
65=head1 INITIALISATION/INTEGRATION 66=head1 INITIALISATION/INTEGRATION
66 67
67Before you can call any eio functions you first have to initialise the 68Before you can call any eio functions you first have to initialise the
… …
124=back 125=back
125 126
126For libev, you would typically use an C<ev_async> watcher: the 127For 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 128C<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 129loop. 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 130()>.
130all requests have been handled yet). The race is taken care of because 131
131libev resets/rearms the async watcher before calling your callback, 132If 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) 133(i.e. it returns C<-1>) then you should start an idle watcher that calls
133spurious wake-ups, but is generally harmless. 134C<eio_poll> until it returns something C<!= -1>.
135
136A full-featured conenctor between libeio and libev would look as follows
137(if C<eio_poll> is handling all requests, it can of course be simplified a
138lot by removing the idle watcher logic):
139
140 static struct ev_loop *loop;
141 static ev_idle repeat_watcher;
142 static ev_async ready_watcher;
143
144 /* idle watcher callback, only used when eio_poll */
145 /* didn't handle all results in one call */
146 static void
147 repeat (EV_P_ ev_idle *w, int revents)
148 {
149 if (eio_poll () != -1)
150 ev_idle_stop (EV_A_ w);
151 }
152
153 /* eio has some results, process them */
154 static void
155 ready (EV_P_ ev_async *w, int revents)
156 {
157 if (eio_poll () == -1)
158 ev_idle_start (EV_A_ &repeat_watcher);
159 }
160
161 /* wake up the event loop */
162 static void
163 want_poll (void)
164 {
165 ev_async_send (loop, &ready_watcher)
166 }
167
168 void
169 my_init_eio ()
170 {
171 loop = EV_DEFAULT;
172
173 ev_idle_init (&repeat_watcher, repeat);
174 ev_async_init (&ready_watcher, ready);
175 ev_async_start (loop &watcher);
176
177 eio_init (want_poll, 0);
178 }
134 179
135For most other event loops, you would typically use a pipe - the event 180For 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 181loop 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 182C<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 183to 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 184C<eio_poll>.
140your callback again and again until the byte has been read (as the pipe 185
141read callback does not read it, only C<done_poll>). 186You don't have to take special care in the case C<eio_poll> doesn't handle
187all requests, as the done callback will not be invoked, so the event loop
188will still signal readyness for the pipe until I<all> results have been
189processed.
142 190
143 191
144=head1 HIGH LEVEL REQUEST API 192=head1 HIGH LEVEL REQUEST API
145 193
146Libeio has both a high-level API, which consists of calling a request 194Libeio has both a high-level API, which consists of calling a request
… …
153 201
154You submit a request by calling the relevant C<eio_TYPE> function with the 202You submit a request by calling the relevant C<eio_TYPE> function with the
155required parameters, a callback of type C<int (*eio_cb)(eio_req *req)> 203required parameters, a callback of type C<int (*eio_cb)(eio_req *req)>
156(called C<eio_cb> below) and a freely usable C<void *data> argument. 204(called C<eio_cb> below) and a freely usable C<void *data> argument.
157 205
158The return value will either be 0 206The return value will either be 0, in case something went really wrong
207(which can basically only happen on very fatal errors, such as C<malloc>
208returning 0, which is rather unlikely), or a pointer to the newly-created
209and submitted C<eio_req *>.
159 210
160The callback will be called with an C<eio_req *> which contains the 211The callback will be called with an C<eio_req *> which contains the
161results of the request. The members you can access inside that structure 212results of the request. The members you can access inside that structure
162vary from request to request, except for: 213vary from request to request, except for:
163 214
… …
215 abort (); /* something ent wrong, we will all die!!! */ 266 abort (); /* something ent wrong, we will all die!!! */
216 267
217Note that you additionally need to call C<eio_poll> when the C<want_cb> 268Note that you additionally need to call C<eio_poll> when the C<want_cb>
218indicates that requests are ready to be processed. 269indicates that requests are ready to be processed.
219 270
271=head2 CANCELLING REQUESTS
272
273Sometimes the need for a request goes away before the request is
274finished. In that case, one can cancel the reqiest by a call to
275C<eio_cancel>:
276
277=over 4
278
279=item eio_cancel (eio_req *req)
280
281Cancel the request. If the request is currently executing it might still
282continue to execute, and in other cases it might still take a while till
283the request is cancelled.
284
285Even if cancelled, the finish callback will still be invoked - the
286callbacks of all cancellable requests need to check whether the request
287has been cancelled by calling C<EIO_CANCELLED (req)>:
288
289 static int
290 my_eio_cb (eio_req *req)
291 {
292 if (EIO_CANCELLED (req))
293 return 0;
294 }
295
296In addition, cancelled requests will either have C<< req->result >> set to
297C<-1> and C<errno> to C<ECANCELED>, or otherwise they were successfully
298executed despite being cancelled (e.g. when they have already been
299executed at the time they were cancelled).
300
301=back
302
220=head2 AVAILABLE REQUESTS 303=head2 AVAILABLE REQUESTS
221 304
222The following request functions are available. I<All> of them return the 305The following request functions are available. I<All> of them return the
223C<eio_req *> on success and C<0> on failure, and I<all> of them have the 306C<eio_req *> on success and C<0> on failure, and I<all> of them have the
224same three trailing arguments: C<pri>, C<cb> and C<data>. The C<cb> is 307same three trailing arguments: C<pri>, C<cb> and C<data>. The C<cb> is
… …
226custom data value as C<data>. 309custom data value as C<data>.
227 310
228=head3 POSIX API WRAPPERS 311=head3 POSIX API WRAPPERS
229 312
230These requests simply wrap the POSIX call of the same name, with the same 313These requests simply wrap the POSIX call of the same name, with the same
231arguments: 314arguments. If a function is not implemented by the OS and cannot be emulated
315in some way, then all of these return C<-1> and set C<errorno> to C<ENOSYS>.
232 316
233=over 4 317=over 4
234 318
235=item eio_open (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data) 319=item eio_open (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data)
236 320
321=item eio_truncate (const char *path, off_t offset, int pri, eio_cb cb, void *data)
322
323=item eio_chown (const char *path, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data)
324
325=item eio_chmod (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
326
327=item eio_mkdir (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
328
329=item eio_rmdir (const char *path, int pri, eio_cb cb, void *data)
330
331=item eio_unlink (const char *path, int pri, eio_cb cb, void *data)
332
237=item eio_utime (const char *path, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data) 333=item eio_utime (const char *path, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data)
238 334
239=item eio_truncate (const char *path, off_t offset, int pri, eio_cb cb, void *data)
240
241=item eio_chown (const char *path, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data)
242
243=item eio_chmod (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
244
245=item eio_mkdir (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
246
247=item eio_rmdir (const char *path, int pri, eio_cb cb, void *data)
248
249=item eio_unlink (const char *path, int pri, eio_cb cb, void *data)
250
251=item eio_readlink (const char *path, int pri, eio_cb cb, void *data) /* result=ptr2 allocated dynamically */
252
253=item eio_stat (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
254
255=item eio_lstat (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
256
257=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */
258
259=item eio_mknod (const char *path, mode_t mode, dev_t dev, int pri, eio_cb cb, void *data) 335=item eio_mknod (const char *path, mode_t mode, dev_t dev, int pri, eio_cb cb, void *data)
260 336
261=item eio_link (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 337=item eio_link (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
262 338
263=item eio_symlink (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 339=item eio_symlink (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
264 340
265=item eio_rename (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 341=item eio_rename (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
266 342
267=item eio_msync (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
268
269=item eio_mlock (void *addr, size_t length, int pri, eio_cb cb, void *data) 343=item eio_mlock (void *addr, size_t length, int pri, eio_cb cb, void *data)
270
271=item eio_mlockall (int flags, int pri, eio_cb cb, void *data)
272 344
273=item eio_close (int fd, int pri, eio_cb cb, void *data) 345=item eio_close (int fd, int pri, eio_cb cb, void *data)
274 346
275=item eio_sync (int pri, eio_cb cb, void *data) 347=item eio_sync (int pri, eio_cb cb, void *data)
276 348
… …
305 377
306Not surprisingly, pread and pwrite are not thread-safe on Darwin (OS/X), 378Not surprisingly, pread and pwrite are not thread-safe on Darwin (OS/X),
307so it is advised not to submit multiple requests on the same fd on this 379so it is advised not to submit multiple requests on the same fd on this
308horrible pile of garbage. 380horrible pile of garbage.
309 381
382=item eio_mlockall (int flags, int pri, eio_cb cb, void *data)
383
384Like C<mlockall>, but the flag value constants are called
385C<EIO_MCL_CURRENT> and C<EIO_MCL_FUTURE>.
386
387=item eio_msync (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
388
389Just like msync, except that the flag values are called C<EIO_MS_ASYNC>,
390C<EIO_MS_INVALIDATE> and C<EIO_MS_SYNC>.
391
392=item eio_readlink (const char *path, int pri, eio_cb cb, void *data)
393
394If successful, the path read by C<readlink(2)> can be accessed via C<<
395req->ptr2 >> and is I<NOT> null-terminated, with the length specified as
396C<< req->result >>.
397
398 if (req->result >= 0)
399 {
400 char *target = strndup ((char *)req->ptr2, req->result);
401
402 free (target);
403 }
404
405=item eio_realpath (const char *path, int pri, eio_cb cb, void *data)
406
407Similar to the realpath libc function, but unlike that one, result is
408C<-1> on failure and the length of the returned path in C<ptr2> (which is
409not 0-terminated) - this is similar to readlink.
410
411=item eio_stat (const char *path, int pri, eio_cb cb, void *data)
412
413=item eio_lstat (const char *path, int pri, eio_cb cb, void *data)
414
310=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)
311 416
312Stats a file - if C<< req->result >> indicates success, then you can 417Stats a file - if C<< req->result >> indicates success, then you can
313access the C<struct stat>-like structure via C<< req->ptr2 >>: 418access the C<struct stat>-like structure via C<< req->ptr2 >>:
314 419
315 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2; 420 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2;
316 421
317=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */ 422=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data)
423
424=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data)
318 425
319Stats a filesystem - if C<< req->result >> indicates success, then you can 426Stats a filesystem - if C<< req->result >> indicates success, then you can
320access the C<struct statvfs>-like structure via C<< req->ptr2 >>: 427access the C<struct statvfs>-like structure via C<< req->ptr2 >>:
321 428
322 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2; 429 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2;
323 430
324=back 431=back
325 432
326=head3 READING DIRECTORIES 433=head3 READING DIRECTORIES
327 434
… …
338(via the C<opendir>, C<readdir> and C<closedir> calls) and returns either 445(via the C<opendir>, C<readdir> and C<closedir> calls) and returns either
339the names or an array of C<struct eio_dirent>, depending on the C<flags> 446the names or an array of C<struct eio_dirent>, depending on the C<flags>
340argument. 447argument.
341 448
342The C<< req->result >> indicates either the number of files found, or 449The C<< req->result >> indicates either the number of files found, or
343C<-1> on error. On success, zero-terminated names can be found as C<< req->ptr2 >>, 450C<-1> on error. On success, null-terminated names can be found as C<< req->ptr2 >>,
344and C<struct eio_dirents>, if requested by C<flags>, can be found via C<< 451and C<struct eio_dirents>, if requested by C<flags>, can be found via C<<
345req->ptr1 >>. 452req->ptr1 >>.
346 453
347Here is an example that prints all the names: 454Here is an example that prints all the names:
348 455
… …
367 474
368If 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>,
369also 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
370eio_dirent> looks like this: 477eio_dirent> looks like this:
371 478
372 struct eio_dirent 479 struct eio_dirent
373 { 480 {
374 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 */
375 unsigned short namelen; /* size of filename without trailing 0 */ 482 unsigned short namelen; /* size of filename without trailing 0 */
376 unsigned char type; /* one of EIO_DT_* */ 483 unsigned char type; /* one of EIO_DT_* */
377 signed char score; /* internal use */ 484 signed char score; /* internal use */
378 ino_t inode; /* the inode number, if available, otherwise unspecified */ 485 ino_t inode; /* the inode number, if available, otherwise unspecified */
379 }; 486 };
380 487
381The 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
382byte-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>.
383 490
384C<type> can be one of: 491C<type> can be one of:
… …
480=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data) 587=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
481 588
482Calls C<sync_file_range>. If the syscall is missing, then this is the same 589Calls C<sync_file_range>. If the syscall is missing, then this is the same
483as calling C<fdatasync>. 590as calling C<fdatasync>.
484 591
592Flags can be any combination of C<EIO_SYNC_FILE_RANGE_WAIT_BEFORE>,
593C<EIO_SYNC_FILE_RANGE_WRITE> and C<EIO_SYNC_FILE_RANGE_WAIT_AFTER>.
594
485=back 595=back
486 596
487=head3 LIBEIO-SPECIFIC REQUESTS 597=head3 LIBEIO-SPECIFIC REQUESTS
488 598
489These requests are specific to libeio and do not correspond to any OS call. 599These requests are specific to libeio and do not correspond to any OS call.
… …
547 657
548=back 658=back
549 659
550=head3 GROUPING AND LIMITING REQUESTS 660=head3 GROUPING AND LIMITING REQUESTS
551 661
662There is one more rather special request, C<eio_grp>. It is a very special
663aio request: Instead of doing something, it is a container for other eio
664requests.
665
666There are two primary use cases for this: a) bundle many requests into a
667single, composite, request with a definite callback and the ability to
668cancel the whole request with its subrequests and b) limiting the number
669of "active" requests.
670
671Further below you will find more dicussion of these topics - first follows
672the reference section detailing the request generator and other methods.
673
674=over 4
675
676=item eio_req *grp = eio_grp (eio_cb cb, void *data)
677
678Creates, submits and returns a group request.
679
680=item eio_grp_add (eio_req *grp, eio_req *req)
681
682Adds a request to the request group.
683
684=item eio_grp_cancel (eio_req *grp)
685
686Cancels all requests I<in> the group, but I<not> the group request
687itself. You can cancel the group request via a normal C<eio_cancel> call.
688
689
690
691=back
692
693
694
552#TODO 695#TODO
553 696
554/*****************************************************************************/ 697/*****************************************************************************/
555/* groups */ 698/* groups */
556 699
557eio_req *eio_grp (eio_cb cb, void *data); 700eio_req *eio_grp (eio_cb cb, void *data);
558void eio_grp_feed (eio_req *grp, void (*feed)(eio_req *req), int limit); 701void eio_grp_feed (eio_req *grp, void (*feed)(eio_req *req), int limit);
559void eio_grp_limit (eio_req *grp, int limit); 702void eio_grp_limit (eio_req *grp, int limit);
560void eio_grp_add (eio_req *grp, eio_req *req);
561void eio_grp_cancel (eio_req *grp); /* cancels all sub requests but not the group */ 703void eio_grp_cancel (eio_req *grp); /* cancels all sub requests but not the group */
562 704
563 705
564=back 706=back
565 707
… …
572=head1 ANATOMY AND LIFETIME OF AN EIO REQUEST 714=head1 ANATOMY AND LIFETIME OF AN EIO REQUEST
573 715
574A request is represented by a structure of type C<eio_req>. To initialise 716A request is represented by a structure of type C<eio_req>. To initialise
575it, clear it to all zero bytes: 717it, clear it to all zero bytes:
576 718
577 eio_req req; 719 eio_req req;
578 720
579 memset (&req, 0, sizeof (req)); 721 memset (&req, 0, sizeof (req));
580 722
581A more common way to initialise a new C<eio_req> is to use C<calloc>: 723A more common way to initialise a new C<eio_req> is to use C<calloc>:
582 724
583 eio_req *req = calloc (1, sizeof (*req)); 725 eio_req *req = calloc (1, sizeof (*req));
584 726
585In either case, libeio neither allocates, initialises or frees the 727In either case, libeio neither allocates, initialises or frees the
586C<eio_req> structure for you - it merely uses it. 728C<eio_req> structure for you - it merely uses it.
587 729
588zero 730zero

Diff Legend

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