[ViewVC] Diff of: cvs/libev/ev.pod

Comparing libev/ev.pod (file contents):
Revision 1.358 by sf-exg, Tue Jan 11 08:43:48 2011 UTC vs.
Revision 1.363 by root, Sun Jan 30 22:38:59 2011 UTC

      ev_timer_start (loop, &timeout_watcher);
      // now wait for events to arrive
      ev_run (loop, 0);
-     // unloop was called, so exit
+     // break was called, so exit
      return 0;
    }
 =head1 ABOUT THIS DOCUMENT
 when you want to receive them.
 This behaviour is useful when you want to do your own signal handling, or
 want to handle signals only in specific threads and want to avoid libev
 unblocking the signals.
+It's also required by POSIX in a threaded program, as libev calls
+C<sigprocmask>, whose behaviour is officially unspecified.
 This flag's behaviour will become the default in future versions of libev.
 =item C<EVBACKEND_SELECT>  (value 1, portable select backend)
 anymore.
    ... queue jobs here, make sure they register event watchers as long
    ... as they still have work to do (even an idle watcher will do..)
    ev_run (my_loop, 0);
-   ... jobs done or somebody called unloop. yeah!
+   ... jobs done or somebody called break. yeah!
 =item ev_break (loop, how)
 Can be used to make a call to C<ev_run> return early (but only after it
 has processed all outstanding events). The C<how> argument must be either
 Before a watcher can be registered with the event looop it has to be
 initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
 C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
-In this state it is simply some block of memory that is suitable for use
+In this state it is simply some block of memory that is suitable for
-in an event loop. It can be moved around, freed, reused etc. at will.
+use in an event loop. It can be moved around, freed, reused etc. at
+will - as long as you either keep the memory contents intact, or call
+C<ev_TYPE_init> again.
 =item started/running/active
 Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
 property of the event loop, and is actively waiting for events. While in
 latter will clear any pending state the watcher might be in, regardless
 of whether it was active or not, so stopping a watcher explicitly before
 freeing it is often a good idea.
 While stopped (and not pending) the watcher is essentially in the
-initialised state, that is it can be reused, moved, modified in any way
+initialised state, that is, it can be reused, moved, modified in any way
-you wish.
+you wish (but when you trash the memory block, you need to C<ev_TYPE_init>
+it again).
 =back
 =head2 WATCHER PRIORITY MODELS
 =head3 The special problem of inheritance over fork/execve/pthread_create
 Both the signal mask (C<sigprocmask>) and the signal disposition
 (C<sigaction>) are unspecified after starting a signal watcher (and after
 stopping it again), that is, libev might or might not block the signal,
-and might or might not set or restore the installed signal handler.
+and might or might not set or restore the installed signal handler (but
+see C<EVFLAG_NOSIGMASK>).
 While this does not matter for the signal disposition (libev never
 sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
 C<execve>), this matters for the signal mask: many programs do not expect
 certain signals to be blocked.
    atexit (program_exits);
 =head2 C<ev_async> - how to wake up an event loop
-In general, you cannot use an C<ev_run> from multiple threads or other
+In general, you cannot use an C<ev_loop> from multiple threads or other
 asynchronous sources such as signal handlers (as opposed to multiple event
 loops - those are of course safe to use in different threads).
 Sometimes, however, you need to wake up an event loop you do not control,
 for example because it belongs to another thread. This is what C<ev_async>
 trust me.
 =item ev_async_send (loop, ev_async *)
 Sends/signals/activates the given C<ev_async> watcher, that is, feeds
-an C<EV_ASYNC> event on the watcher into the event loop. Unlike
+an C<EV_ASYNC> event on the watcher into the event loop, and instanlty
+returns.
-C<ev_feed_event>, this call is safe to do from other threads, signal or
+Unlike C<ev_feed_event>, this call is safe to do from other threads,
-similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
+signal or similar contexts (see the discussion of C<EV_ATOMIC_T> in the
-section below on what exactly this means).
+embedding section below on what exactly this means).
 Note that, as with other watchers in libev, multiple events might get
 compressed into a single callback invocation (another way to look at this
 is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
 reset when the event loop detects that).
    exit_main_loop = exit_nested_loop = 1;
 =head2 THREAD LOCKING EXAMPLE
 Here is a fictitious example of how to run an event loop in a different
-thread than where callbacks are being invoked and watchers are
+thread from where callbacks are being invoked and watchers are
 created/added/removed.
 For a real-world example, see the C<EV::Loop::Async> perl module,
 which uses exactly this technique (which is suited for many high-level
 languages).
       // now associate this with the loop
       ev_set_userdata (EV_A_ u);
       ev_set_invoke_pending_cb (EV_A_ l_invoke);
       ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
-      // then create the thread running ev_loop
+      // then create the thread running ev_run
       pthread_create (&u->tid, 0, l_run, EV_A);
    }
 The callback for the C<ev_async> watcher does nothing: the watcher is used
 solely to wake up the event loop so it takes notice of any new watchers

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.358 by sf-exg, Tue Jan 11 08:43:48 2011 UTC vs. Revision 1.363 by root, Sun Jan 30 22:38:59 2011 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.358 by sf-exg, Tue Jan 11 08:43:48 2011 UTC vs.
Revision 1.363 by root, Sun Jan 30 22:38:59 2011 UTC