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

Comparing libev/ev.pod (file contents):
Revision 1.360 by root, Mon Jan 17 12:11:12 2011 UTC vs.
Revision 1.364 by sf-exg, Sun Jan 30 23:07:20 2011 UTC

… …
58 ev_timer_start (loop, &timeout_watcher); 58 ev_timer_start (loop, &timeout_watcher);
59 59
60 // now wait for events to arrive 60 // now wait for events to arrive
61 ev_run (loop, 0); 61 ev_run (loop, 0);
62 62
63 // unloop was called, so exit 63 // break was called, so exit
64 return 0; 64 return 0;
65 } 65 }
66 66
67=head1 ABOUT THIS DOCUMENT 67=head1 ABOUT THIS DOCUMENT
68 68
… …
868anymore. 868anymore.
869 869
870 ... queue jobs here, make sure they register event watchers as long 870 ... queue jobs here, make sure they register event watchers as long
871 ... as they still have work to do (even an idle watcher will do..) 871 ... as they still have work to do (even an idle watcher will do..)
872 ev_run (my_loop, 0); 872 ev_run (my_loop, 0);
873 ... jobs done or somebody called unloop. yeah! 873 ... jobs done or somebody called break. yeah!
874 874
875=item ev_break (loop, how) 875=item ev_break (loop, how)
876 876
877Can be used to make a call to C<ev_run> return early (but only after it 877Can be used to make a call to C<ev_run> return early (but only after it
878has processed all outstanding events). The C<how> argument must be either 878has processed all outstanding events). The C<how> argument must be either
… …
1378 1378
1379Before a watcher can be registered with the event looop it has to be 1379Before a watcher can be registered with the event looop it has to be
1380initialised. This can be done with a call to C<ev_TYPE_init>, or calls to 1380initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
1381C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function. 1381C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
1382 1382
1383In this state it is simply some block of memory that is suitable for use 1383In this state it is simply some block of memory that is suitable for
1384in an event loop. It can be moved around, freed, reused etc. at will. 1384use in an event loop. It can be moved around, freed, reused etc. at
1385will - as long as you either keep the memory contents intact, or call
1386C<ev_TYPE_init> again.
1385 1387
1386=item started/running/active 1388=item started/running/active
1387 1389
1388Once a watcher has been started with a call to C<ev_TYPE_start> it becomes 1390Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
1389property of the event loop, and is actively waiting for events. While in 1391property of the event loop, and is actively waiting for events. While in
… …
1417latter will clear any pending state the watcher might be in, regardless 1419latter will clear any pending state the watcher might be in, regardless
1418of whether it was active or not, so stopping a watcher explicitly before 1420of whether it was active or not, so stopping a watcher explicitly before
1419freeing it is often a good idea. 1421freeing it is often a good idea.
1420 1422
1421While stopped (and not pending) the watcher is essentially in the 1423While stopped (and not pending) the watcher is essentially in the
1422initialised state, that is it can be reused, moved, modified in any way 1424initialised state, that is, it can be reused, moved, modified in any way
1423you wish. 1425you wish (but when you trash the memory block, you need to C<ev_TYPE_init>
1426it again).
1424 1427
1425=back 1428=back
1426 1429
1427=head2 WATCHER PRIORITY MODELS 1430=head2 WATCHER PRIORITY MODELS
1428 1431
… …
3185 atexit (program_exits); 3188 atexit (program_exits);
3186 3189
3187 3190
3188=head2 C<ev_async> - how to wake up an event loop 3191=head2 C<ev_async> - how to wake up an event loop
3189 3192
3190In general, you cannot use an C<ev_run> from multiple threads or other 3193In general, you cannot use an C<ev_loop> from multiple threads or other
3191asynchronous sources such as signal handlers (as opposed to multiple event 3194asynchronous sources such as signal handlers (as opposed to multiple event
3192loops - those are of course safe to use in different threads). 3195loops - those are of course safe to use in different threads).
3193 3196
3194Sometimes, however, you need to wake up an event loop you do not control, 3197Sometimes, however, you need to wake up an event loop you do not control,
3195for example because it belongs to another thread. This is what C<ev_async> 3198for example because it belongs to another thread. This is what C<ev_async>
… …
3305trust me. 3308trust me.
3306 3309
3307=item ev_async_send (loop, ev_async *) 3310=item ev_async_send (loop, ev_async *)
3308 3311
3309Sends/signals/activates the given C<ev_async> watcher, that is, feeds 3312Sends/signals/activates the given C<ev_async> watcher, that is, feeds
3310an C<EV_ASYNC> event on the watcher into the event loop. Unlike 3313an C<EV_ASYNC> event on the watcher into the event loop, and instantly
3314returns.
3315
3311C<ev_feed_event>, this call is safe to do from other threads, signal or 3316Unlike C<ev_feed_event>, this call is safe to do from other threads,
3312similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 3317signal or similar contexts (see the discussion of C<EV_ATOMIC_T> in the
3313section below on what exactly this means). 3318embedding section below on what exactly this means).
3314 3319
3315Note that, as with other watchers in libev, multiple events might get 3320Note that, as with other watchers in libev, multiple events might get
3316compressed into a single callback invocation (another way to look at this 3321compressed into a single callback invocation (another way to look at this
3317is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>, 3322is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
3318reset when the event loop detects that). 3323reset when the event loop detects that).
… …
3544 // now associate this with the loop 3549 // now associate this with the loop
3545 ev_set_userdata (EV_A_ u); 3550 ev_set_userdata (EV_A_ u);
3546 ev_set_invoke_pending_cb (EV_A_ l_invoke); 3551 ev_set_invoke_pending_cb (EV_A_ l_invoke);
3547 ev_set_loop_release_cb (EV_A_ l_release, l_acquire); 3552 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3548 3553
3549 // then create the thread running ev_loop 3554 // then create the thread running ev_run
3550 pthread_create (&u->tid, 0, l_run, EV_A); 3555 pthread_create (&u->tid, 0, l_run, EV_A);
3551 } 3556 }
3552 3557
3553The callback for the C<ev_async> watcher does nothing: the watcher is used 3558The callback for the C<ev_async> watcher does nothing: the watcher is used
3554solely to wake up the event loop so it takes notice of any new watchers 3559solely to wake up the event loop so it takes notice of any new watchers

Diff Legend

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