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

Comparing libev/ev.pod (file contents):
Revision 1.356 by root, Tue Jan 11 01:42:47 2011 UTC vs.
Revision 1.357 by root, Tue Jan 11 02:15:58 2011 UTC

… …
1357See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related 1357See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1358functions that do not need a watcher. 1358functions that do not need a watcher.
1359 1359
1360=back 1360=back
1361 1361
1362=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1362See also the L<ASSOCIATING CUSTOM DATA WITH A WATCHER> and L<BUILDING YOUR
1363 1363OWN COMPOSITE WATCHERS> idioms.
1364Each watcher has, by default, a member C<void *data> that you can change
1365and read at any time: libev will completely ignore it. This can be used
1366to associate arbitrary data with your watcher. If you need more data and
1367don't want to allocate memory and store a pointer to it in that data
1368member, you can also "subclass" the watcher type and provide your own
1369data:
1370
1371 struct my_io
1372 {
1373 ev_io io;
1374 int otherfd;
1375 void *somedata;
1376 struct whatever *mostinteresting;
1377 };
1378
1379 ...
1380 struct my_io w;
1381 ev_io_init (&w.io, my_cb, fd, EV_READ);
1382
1383And since your callback will be called with a pointer to the watcher, you
1384can cast it back to your own type:
1385
1386 static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
1387 {
1388 struct my_io *w = (struct my_io *)w_;
1389 ...
1390 }
1391
1392More interesting and less C-conformant ways of casting your callback type
1393instead have been omitted.
1394
1395Another common scenario is to use some data structure with multiple
1396embedded watchers:
1397
1398 struct my_biggy
1399 {
1400 int some_data;
1401 ev_timer t1;
1402 ev_timer t2;
1403 }
1404
1405In this case getting the pointer to C<my_biggy> is a bit more
1406complicated: Either you store the address of your C<my_biggy> struct
1407in the C<data> member of the watcher (for woozies), or you need to use
1408some pointer arithmetic using C<offsetof> inside your watchers (for real
1409programmers):
1410
1411 #include <stddef.h>
1412
1413 static void
1414 t1_cb (EV_P_ ev_timer *w, int revents)
1415 {
1416 struct my_biggy big = (struct my_biggy *)
1417 (((char *)w) - offsetof (struct my_biggy, t1));
1418 }
1419
1420 static void
1421 t2_cb (EV_P_ ev_timer *w, int revents)
1422 {
1423 struct my_biggy big = (struct my_biggy *)
1424 (((char *)w) - offsetof (struct my_biggy, t2));
1425 }
1426 1364
1427=head2 WATCHER STATES 1365=head2 WATCHER STATES
1428 1366
1429There are various watcher states mentioned throughout this manual - 1367There are various watcher states mentioned throughout this manual -
1430active, pending and so on. In this section these states and the rules to 1368active, pending and so on. In this section these states and the rules to
… …
3456 3394
3457This section explains some common idioms that are not immediately 3395This section explains some common idioms that are not immediately
3458obvious. Note that examples are sprinkled over the whole manual, and this 3396obvious. Note that examples are sprinkled over the whole manual, and this
3459section only contains stuff that wouldn't fit anywhere else. 3397section only contains stuff that wouldn't fit anywhere else.
3460 3398
3399=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
3400
3401Each watcher has, by default, a C<void *data> member that you can read
3402or modify at any time: libev will completely ignore it. This can be used
3403to associate arbitrary data with your watcher. If you need more data and
3404don't want to allocate memory separately and store a pointer to it in that
3405data member, you can also "subclass" the watcher type and provide your own
3406data:
3407
3408 struct my_io
3409 {
3410 ev_io io;
3411 int otherfd;
3412 void *somedata;
3413 struct whatever *mostinteresting;
3414 };
3415
3416 ...
3417 struct my_io w;
3418 ev_io_init (&w.io, my_cb, fd, EV_READ);
3419
3420And since your callback will be called with a pointer to the watcher, you
3421can cast it back to your own type:
3422
3423 static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
3424 {
3425 struct my_io *w = (struct my_io *)w_;
3426 ...
3427 }
3428
3429More interesting and less C-conformant ways of casting your callback
3430function type instead have been omitted.
3431
3432=head2 BUILDING YOUR OWN COMPOSITE WATCHERS
3433
3434Another common scenario is to use some data structure with multiple
3435embedded watchers, in effect creating your own watcher that combines
3436multiple libev event sources into one "super-watcher":
3437
3438 struct my_biggy
3439 {
3440 int some_data;
3441 ev_timer t1;
3442 ev_timer t2;
3443 }
3444
3445In this case getting the pointer to C<my_biggy> is a bit more
3446complicated: Either you store the address of your C<my_biggy> struct in
3447the C<data> member of the watcher (for woozies or C++ coders), or you need
3448to use some pointer arithmetic using C<offsetof> inside your watchers (for
3449real programmers):
3450
3451 #include <stddef.h>
3452
3453 static void
3454 t1_cb (EV_P_ ev_timer *w, int revents)
3455 {
3456 struct my_biggy big = (struct my_biggy *)
3457 (((char *)w) - offsetof (struct my_biggy, t1));
3458 }
3459
3460 static void
3461 t2_cb (EV_P_ ev_timer *w, int revents)
3462 {
3463 struct my_biggy big = (struct my_biggy *)
3464 (((char *)w) - offsetof (struct my_biggy, t2));
3465 }
3466
3461=head2 MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS 3467=head2 MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS
3462 3468
3463Often (especially in GUI toolkits) there are places where you have 3469Often (especially in GUI toolkits) there are places where you have
3464I<modal> interaction, which is most easily implemented by recursively 3470I<modal> interaction, which is most easily implemented by recursively
3465invoking C<ev_run>. 3471invoking C<ev_run>.
… …
3632 3638
3633Note that sending the C<ev_async> watcher is required because otherwise 3639Note that sending the C<ev_async> watcher is required because otherwise
3634an event loop currently blocking in the kernel will have no knowledge 3640an event loop currently blocking in the kernel will have no knowledge
3635about the newly added timer. By waking up the loop it will pick up any new 3641about the newly added timer. By waking up the loop it will pick up any new
3636watchers in the next event loop iteration. 3642watchers in the next event loop iteration.
3643
3644=head2 THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS
3645
3646While the overhead of a callback that e.g. schedules a thread is small, it
3647is still an overhead. If you embed libev, and your main usage is with some
3648kind of threads or coroutines, you might want to customise libev so that
3649doesn't need callbacks anymore.
3650
3651Imagine you have coroutines that you can switch to using a function
3652C<switch_to (coro)>, that libev runs in a coroutine called C<libev_coro>
3653and that due to some magic, the currently active coroutine is stored in a
3654global called C<current_coro>. Then you can build your own "wait for libev
3655event" primitive by changing C<EV_CB_DECLARE> and C<EV_CB_INVOKE> (note
3656the differing C<;> conventions):
3657
3658 #define EV_CB_DECLARE(type) struct my_coro *cb;
3659 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb)
3660
3661That means instead of having a C callback function, you store the
3662coroutine to switch to in each watcher, and instead of having libev call
3663your callback, you instead have it switch to that coroutine.
3664
3665A coroutine might now wait for an event with a function called
3666C<wait_for_event>. (the watcher needs to be started, as always, but it doesn't
3667matter when, or whether the watcher is active or not when this function is
3668called):
3669
3670 void
3671 wait_for_event (ev_watcher *w)
3672 {
3673 ev_cb_set (w) = current_coro;
3674 switch_to (libev_coro);
3675 }
3676
3677That basically suspends the coroutine inside C<wait_for_event> and
3678continues the libev coroutine, which, when appropriate, switches back to
3679this or any other coroutine. I am sure if you sue this your own :)
3680
3681You can do similar tricks if you have, say, threads with an event queue -
3682instead of storing a coroutine, you store the queue object and instead of
3683switching to a coroutine, you push the watcher onto the queue and notify
3684any waiters.
3685
3686To embed libev, see L<EMBEDDING>, but in short, it's easiest to create two
3687files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
3688
3689 // my_ev.h
3690 #define EV_CB_DECLARE(type) struct my_coro *cb;
3691 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb);
3692 #include "../libev/ev.h"
3693
3694 // my_ev.c
3695 #define EV_H "my_ev.h"
3696 #include "../libev/ev.c"
3697
3698And then use F<my_ev.h> when you would normally use F<ev.h>, and compile
3699F<my_ev.c> into your project. When properly specifying include paths, you
3700can even use F<ev.h> as header file name directly.
3637 3701
3638 3702
3639=head1 LIBEVENT EMULATION 3703=head1 LIBEVENT EMULATION
3640 3704
3641Libev offers a compatibility emulation layer for libevent. It cannot 3705Libev offers a compatibility emulation layer for libevent. It cannot

Diff Legend

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