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

Comparing libev/ev.pod (file contents):
Revision 1.468 by sf-exg, Sun May 14 19:02:31 2023 UTC vs.
Revision 1.469 by root, Sat Jun 3 08:53:03 2023 UTC

 and is not embeddable, which would limit the usefulness of this backend
 immensely.
 =item C<EVBACKEND_PORT>    (value 32, Solaris 10)
-This uses the Solaris 10 event port mechanism. As with everything on Solaris,
+This uses the Solaris 10 event port mechanism. As with everything on
-it's really slow, but it still scales very well (O(active_fds)).
+Solaris, it's really slow, but it still scales very well (O(active_fds)).
 While this backend scales well, it requires one system call per active
 file descriptor per loop iteration. For small and medium numbers of file
 descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
 might perform better.
 Returns a true value iff the watcher is active (i.e. it has been started
 and not yet been stopped). As long as a watcher is active you must not modify
 it unless documented otherwise.
+Obviously, it is safe to call this on an active watcher, or actually any
+watcher that is initialised.
 =item bool ev_is_pending (ev_TYPE *watcher)
 Returns a true value iff the watcher is pending, (i.e. it has outstanding
 events but its callback has not yet been invoked). As long as a watcher
 is pending (but not active) you must not call an init function on it (but
 C<ev_TYPE_set> is safe), you must not change its priority, and you must
 make sure the watcher is available to libev (e.g. you cannot C<free ()>
 it).
+It is safe to call this on any watcher in any state as long as it is
+initialised.
 =item callback ev_cb (ev_TYPE *watcher)
 Returns the callback currently set on the watcher.
 =item ev_set_cb (ev_TYPE *watcher, callback)
 from being executed (except for C<ev_idle> watchers).
 If you need to suppress invocation when higher priority events are pending
 you need to look at C<ev_idle> watchers, which provide this functionality.
-You I<must not> change the priority of a watcher as long as it is active or
+You I<must not> change the priority of a watcher as long as it is active
-pending.
+or pending. Reading the priority with C<ev_priority> is fine in any state.
 Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
 fine, as long as you do not mind that the priority value you query might
 or might not have been clamped to the valid range.
 =item ev_feed_event (loop, ev_TYPE *watcher, int revents)
 Feeds the given event set into the event loop, as if the specified event
 had happened for the specified watcher (which must be a pointer to an
-initialised but not necessarily started event watcher). Obviously you must
+initialised but not necessarily started event watcher, though it can be
-not free the watcher as long as it has pending events.
+active). Obviously you must not free the watcher as long as it has pending
+events.
 Stopping the watcher, letting libev invoke it, or calling
 C<ev_clear_pending> will clear the pending event, even if the watcher was
 not started in the first place.
 =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
-this state it cannot be accessed (except in a few documented ways), moved,
+this state it cannot be accessed (except in a few documented ways, such as
-freed or anything else - the only legal thing is to keep a pointer to it,
+stoping it), moved, freed or anything else - the only legal thing is to
-and call libev functions on it that are documented to work on active watchers.
+keep a pointer to it, and call libev functions on it that are documented
+to work on active watchers.
+As a rule of thumb, before accessing a member or calling any function on
+a watcher, it should be stopped (or freshly initialised). If that is not
+convenient, you can check the documentation for that function or member to
+see if it is safe to use on an active watcher.
 =item pending
 If a watcher is active and libev determines that an event it is interested
-in has occurred (such as a timer expiring), it will become pending. It will
+in has occurred (such as a timer expiring), it will become pending. It
-stay in this pending state until either it is stopped or its callback is
+will stay in this pending state until either it is explicitly stopped or
-about to be invoked, so it is not normally pending inside the watcher
+its callback is about to be invoked, so it is not normally pending inside
-callback.
+the watcher callback.
-The watcher might or might not be active while it is pending (for example,
+Generally, the watcher might or might not be active while it is pending
-an expired non-repeating timer can be pending but no longer active). If it
+(for example, an expired non-repeating timer can be pending but no longer
-is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>),
+active). If it is pending but not active, it can be freely accessed (e.g.
-but it is still property of the event loop at this time, so cannot be
+by calling C<ev_TYPE_set>), but it is still property of the event loop at
-moved, freed or reused. And if it is active the rules described in the
+this time, so cannot be moved, freed or reused. And if it is active the
-previous item still apply.
+rules described in the previous item still apply.
+Explicitly stopping a watcher will also clear the pending state
+unconditionally, so it is safe to stop a watcher and then free it.
 It is also possible to feed an event on a watcher that is not active (e.g.
 via C<ev_feed_event>), in which case it becomes pending without being
 active.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.468 by sf-exg, Sun May 14 19:02:31 2023 UTC vs. Revision 1.469 by root, Sat Jun 3 08:53:03 2023 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.468 by sf-exg, Sun May 14 19:02:31 2023 UTC vs.
Revision 1.469 by root, Sat Jun 3 08:53:03 2023 UTC