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

Comparing libeio/eio.pod (file contents):
Revision 1.8 by root, Sun Jun 5 22:45:49 2011 UTC vs.
Revision 1.16 by root, Tue Jul 5 17:05:54 2011 UTC

… …
124=back 124=back
125 125
126For libev, you would typically use an C<ev_async> watcher: the 126For 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 127C<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 128loop. 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 129()>.
130all requests have been handled yet). The race is taken care of because 130
131libev resets/rearms the async watcher before calling your callback, 131If 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) 132(i.e. it returns C<-1>) then you should start an idle watcher that calls
133spurious wake-ups, but is generally harmless. 133C<eio_poll> until it returns something C<!= -1>.
134
135A full-featured conenctor between libeio and libev would look as follows
136(if C<eio_poll> is handling all requests, it can of course be simplified a
137lot by removing the idle watcher logic):
138
139 static struct ev_loop *loop;
140 static ev_idle repeat_watcher;
141 static ev_async ready_watcher;
142
143 /* idle watcher callback, only used when eio_poll */
144 /* didn't handle all results in one call */
145 static void
146 repeat (EV_P_ ev_idle *w, int revents)
147 {
148 if (eio_poll () != -1)
149 ev_idle_stop (EV_A_ w);
150 }
151
152 /* eio has some results, process them */
153 static void
154 ready (EV_P_ ev_async *w, int revents)
155 {
156 if (eio_poll () == -1)
157 ev_idle_start (EV_A_ &repeat_watcher);
158 }
159
160 /* wake up the event loop */
161 static void
162 want_poll (void)
163 {
164 ev_async_send (loop, &ready_watcher)
165 }
166
167 void
168 my_init_eio ()
169 {
170 loop = EV_DEFAULT;
171
172 ev_idle_init (&repeat_watcher, repeat);
173 ev_async_init (&ready_watcher, ready);
174 ev_async_start (loop &watcher);
175
176 eio_init (want_poll, 0);
177 }
134 178
135For most other event loops, you would typically use a pipe - the event 179For 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 180loop 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 181C<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 182to 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 183C<eio_poll>.
140your callback again and again until the byte has been read (as the pipe 184
141read callback does not read it, only C<done_poll>). 185You 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
187will still signal readyness for the pipe until I<all> results have been
188processed.
142 189
143 190
144=head1 HIGH LEVEL REQUEST API 191=head1 HIGH LEVEL REQUEST API
145 192
146Libeio has both a high-level API, which consists of calling a request 193Libeio has both a high-level API, which consists of calling a request
… …
153 200
154You submit a request by calling the relevant C<eio_TYPE> function with the 201You 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)> 202required 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. 203(called C<eio_cb> below) and a freely usable C<void *data> argument.
157 204
158The return value will either be 0 205The return value will either be 0, in case something went really wrong
206(which can basically only happen on very fatal errors, such as C<malloc>
207returning 0, which is rather unlikely), or a pointer to the newly-created
208and submitted C<eio_req *>.
159 209
160The callback will be called with an C<eio_req *> which contains the 210The callback will be called with an C<eio_req *> which contains the
161results of the request. The members you can access inside that structure 211results of the request. The members you can access inside that structure
162vary from request to request, except for: 212vary from request to request, except for:
163 213
… …
226custom data value as C<data>. 276custom data value as C<data>.
227 277
228=head3 POSIX API WRAPPERS 278=head3 POSIX API WRAPPERS
229 279
230These requests simply wrap the POSIX call of the same name, with the same 280These requests simply wrap the POSIX call of the same name, with the same
231arguments: 281arguments. If a function is not implemented by the OS and cannot be emulated
282in some way, then all of these return C<-1> and set C<errorno> to C<ENOSYS>.
232 283
233=over 4 284=over 4
234 285
235=item eio_open (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data) 286=item eio_open (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data)
236 287
288=item eio_truncate (const char *path, off_t offset, int pri, eio_cb cb, void *data)
289
290=item eio_chown (const char *path, uid_t uid, gid_t gid, int pri, eio_cb cb, void *data)
291
292=item eio_chmod (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
293
294=item eio_mkdir (const char *path, mode_t mode, int pri, eio_cb cb, void *data)
295
296=item eio_rmdir (const char *path, int pri, eio_cb cb, void *data)
297
298=item eio_unlink (const char *path, int pri, eio_cb cb, void *data)
299
237=item eio_utime (const char *path, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data) 300=item eio_utime (const char *path, eio_tstamp atime, eio_tstamp mtime, int pri, eio_cb cb, void *data)
238 301
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) 302=item eio_mknod (const char *path, mode_t mode, dev_t dev, int pri, eio_cb cb, void *data)
260 303
261=item eio_link (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 304=item eio_link (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
262 305
263=item eio_symlink (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 306=item eio_symlink (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
264 307
265=item eio_rename (const char *path, const char *new_path, int pri, eio_cb cb, void *data) 308=item eio_rename (const char *path, const char *new_path, int pri, eio_cb cb, void *data)
266 309
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) 310=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 311
273=item eio_close (int fd, int pri, eio_cb cb, void *data) 312=item eio_close (int fd, int pri, eio_cb cb, void *data)
274 313
275=item eio_sync (int pri, eio_cb cb, void *data) 314=item eio_sync (int pri, eio_cb cb, void *data)
276 315
… …
305 344
306Not surprisingly, pread and pwrite are not thread-safe on Darwin (OS/X), 345Not 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 346so it is advised not to submit multiple requests on the same fd on this
308horrible pile of garbage. 347horrible pile of garbage.
309 348
349=item eio_mlockall (int flags, int pri, eio_cb cb, void *data)
350
351Like C<mlockall>, but the flag value constants are called
352C<EIO_MCL_CURRENT> and C<EIO_MCL_FUTURE>.
353
354=item eio_msync (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
355
356Just like msync, except that the flag values are called C<EIO_MS_ASYNC>,
357C<EIO_MS_INVALIDATE> and C<EIO_MS_SYNC>.
358
359=item eio_readlink (const char *path, int pri, eio_cb cb, void *data)
360
361If successful, the path read by C<readlink(2)> can be accessed via C<<
362req->ptr2 >> and is I<NOT> null-terminated, with the length specified as
363C<< req->result >>.
364
365 if (req->result >= 0)
366 {
367 char *target = strndup ((char *)req->ptr2, req->result);
368
369 free (target);
370 }
371
372=item eio_realpath (const char *path, int pri, eio_cb cb, void *data)
373
374Similar to the realpath libc function, but unlike that one, result is
375C<-1> on failure and the length of the returned path in C<ptr2> (which is
376not 0-terminated) - this is similar to readlink.
377
378=item eio_stat (const char *path, int pri, eio_cb cb, void *data)
379
380=item eio_lstat (const char *path, int pri, eio_cb cb, void *data)
381
310=item eio_fstat (int fd, int pri, eio_cb cb, void *data) 382=item eio_fstat (int fd, int pri, eio_cb cb, void *data)
311 383
312Stats a file - if C<< req->result >> indicates success, then you can 384Stats a file - if C<< req->result >> indicates success, then you can
313access the C<struct stat>-like structure via C<< req->ptr2 >>: 385access the C<struct stat>-like structure via C<< req->ptr2 >>:
314 386
315 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2; 387 EIO_STRUCT_STAT *statdata = (EIO_STRUCT_STAT *)req->ptr2;
316 388
317=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data) /* stat buffer=ptr2 allocated dynamically */ 389=item eio_statvfs (const char *path, int pri, eio_cb cb, void *data)
390
391=item eio_fstatvfs (int fd, int pri, eio_cb cb, void *data)
318 392
319Stats a filesystem - if C<< req->result >> indicates success, then you can 393Stats a filesystem - if C<< req->result >> indicates success, then you can
320access the C<struct statvfs>-like structure via C<< req->ptr2 >>: 394access the C<struct statvfs>-like structure via C<< req->ptr2 >>:
321 395
322 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2; 396 EIO_STRUCT_STATVFS *statdata = (EIO_STRUCT_STATVFS *)req->ptr2;
… …
338(via the C<opendir>, C<readdir> and C<closedir> calls) and returns either 412(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> 413the names or an array of C<struct eio_dirent>, depending on the C<flags>
340argument. 414argument.
341 415
342The C<< req->result >> indicates either the number of files found, or 416The 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 >>, 417C<-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<< 418and C<struct eio_dirents>, if requested by C<flags>, can be found via C<<
345req->ptr1 >>. 419req->ptr1 >>.
346 420
347Here is an example that prints all the names: 421Here is an example that prints all the names:
348 422
… …
480=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data) 554=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
481 555
482Calls C<sync_file_range>. If the syscall is missing, then this is the same 556Calls C<sync_file_range>. If the syscall is missing, then this is the same
483as calling C<fdatasync>. 557as calling C<fdatasync>.
484 558
559Flags 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>.
561
485=back 562=back
486 563
487=head3 LIBEIO-SPECIFIC REQUESTS 564=head3 LIBEIO-SPECIFIC REQUESTS
488 565
489These requests are specific to libeio and do not correspond to any OS call. 566These requests are specific to libeio and do not correspond to any OS call.
490 567
491=over 4 568=over 4
492 569
493=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data) 570=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
494 571
572Reads (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
574first octet of every page that spans the memory area.
575
576This 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
578the some other thread modifies the data stored in that memory area.
579
495=item eio_custom (void (*)(eio_req *) execute, int pri, eio_cb cb, void *data) 580=item eio_custom (void (*)(eio_req *) execute, int pri, eio_cb cb, void *data)
496 581
497Executes a custom request, i.e., a user-specified callback. 582Executes a custom request, i.e., a user-specified callback.
498 583
499The callback gets the C<eio_req *> as parameter and is expected to read 584The callback gets the C<eio_req *> as parameter and is expected to read
500and modify any request-specific members. Specifically, it should set C<< 585and modify any request-specific members. Specifically, it should set C<<
… …
520 req->result = open (req->data, O_RDONLY); 605 req->result = open (req->data, O_RDONLY);
521 } 606 }
522 607
523 eio_custom (my_open, 0, my_open_done, "/etc/passwd"); 608 eio_custom (my_open, 0, my_open_done, "/etc/passwd");
524 609
525=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data) 610=item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data)
526 611
527This is a a request that takes C<delay> seconds to execute, but otherwise 612This is a a request that takes C<delay> seconds to execute, but otherwise
528does nothing - it simply puts one of the worker threads to sleep for this 613does nothing - it simply puts one of the worker threads to sleep for this
529long. 614long.
530 615
531This request can be used to artificially increase load, e.g. for debugging 616This request can be used to artificially increase load, e.g. for debugging
532or benchmarking reasons. 617or benchmarking reasons.
533 618
534=item eio_nop (int pri, eio_cb cb, void *data) 619=item eio_nop (int pri, eio_cb cb, void *data)
535 620
536This request does nothing, except go through the whole request cycle. This 621This request does nothing, except go through the whole request cycle. This
537can be used to measure latency or in some cases to simplify code, but is 622can be used to measure latency or in some cases to simplify code, but is
538not really of much use. 623not really of much use.
539 624
540=back 625=back
541 626
542=head3 GROUPING AND LIMITING REQUESTS 627=head3 GROUPING AND LIMITING REQUESTS
628
629There is one more rather special request, C<eio_grp>. It is a very special
630aio request: Instead of doing something, it is a container for other eio
631requests.
632
633There are two primary use cases for this: a) bundle many requests into a
634single, composite, request with a definite callback and the ability to
635cancel the whole request with its subrequests and b) limiting the number
636of "active" requests.
637
638Further below you will find more dicussion of these topics - first follows
639the reference section detailing the request generator and other methods.
640
641=over 4
642
643=item eio_grp (eio_cb cb, void *data)
644
645Creates and submits a group request.
646
647=back
648
649
543 650
544#TODO 651#TODO
545 652
546/*****************************************************************************/ 653/*****************************************************************************/
547/* groups */ 654/* groups */

Diff Legend

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