--- libev/ev.3	2023/05/14 19:02:31	1.125
+++ libev/ev.3	2023/06/03 08:53:03	1.126
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "LIBEV 3"
-.TH LIBEV 3 "2021-01-11" "libev-4.33" "libev - high performance full featured event loop"
+.TH LIBEV 3 "2023-05-15" "libev-4.33" "libev - high performance full featured event loop"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -803,8 +803,8 @@
 .ie n .IP """EVBACKEND_PORT""    (value 32, Solaris 10)" 4
 .el .IP "\f(CWEVBACKEND_PORT\fR    (value 32, Solaris 10)" 4
 .IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
-This uses the Solaris 10 event port mechanism. As with everything on Solaris,
-it's really slow, but it still scales very well (O(active_fds)).
+This uses the Solaris 10 event port mechanism. As with everything on
+Solaris, it's really slow, but it still scales very well (O(active_fds)).
 .Sp
 While this backend scales well, it requires one system call per active
 file descriptor per loop iteration. For small and medium numbers of file
@@ -1535,6 +1535,9 @@
 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.
+.Sp
+Obviously, it is safe to call this on an active watcher, or actually any
+watcher that is initialised.
 .IP "bool ev_is_pending (ev_TYPE *watcher)" 4
 .IX Item "bool ev_is_pending (ev_TYPE *watcher)"
 Returns a true value iff the watcher is pending, (i.e. it has outstanding
@@ -1543,6 +1546,9 @@
 \&\f(CW\*(C`ev_TYPE_set\*(C'\fR is safe), you must not change its priority, and you must
 make sure the watcher is available to libev (e.g. you cannot \f(CW\*(C`free ()\*(C'\fR
 it).
+.Sp
+It is safe to call this on any watcher in any state as long as it is
+initialised.
 .IP "callback ev_cb (ev_TYPE *watcher)" 4
 .IX Item "callback ev_cb (ev_TYPE *watcher)"
 Returns the callback currently set on the watcher.
@@ -1565,8 +1571,8 @@
 If you need to suppress invocation when higher priority events are pending
 you need to look at \f(CW\*(C`ev_idle\*(C'\fR watchers, which provide this functionality.
 .Sp
-You \fImust not\fR change the priority of a watcher as long as it is active or
-pending.
+You \fImust not\fR change the priority of a watcher as long as it is active
+or pending. Reading the priority with \f(CW\*(C`ev_priority\*(C'\fR is fine in any state.
 .Sp
 Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is
 fine, as long as you do not mind that the priority value you query might
@@ -1595,8 +1601,9 @@
 .IX 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
-not free the watcher as long as it has pending events.
+initialised but not necessarily started event watcher, though it can be
+active). Obviously you must not free the watcher as long as it has pending
+events.
 .Sp
 Stopping the watcher, letting libev invoke it, or calling
 \&\f(CW\*(C`ev_clear_pending\*(C'\fR will clear the pending event, even if the watcher was
@@ -1627,23 +1634,32 @@
 .IX Item "started/running/active"
 Once a watcher has been started with a call to \f(CW\*(C`ev_TYPE_start\*(C'\fR 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,
-freed or anything else \- the only legal thing is to keep a pointer to it,
-and call libev functions on it that are documented to work on active watchers.
+this state it cannot be accessed (except in a few documented ways, such as
+stoping it), moved, freed or anything else \- the only legal thing is to
+keep a pointer to it, and call libev functions on it that are documented
+to work on active watchers.
+.Sp
+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.
 .IP "pending" 4
 .IX 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
-stay in this pending state until either it is stopped or its callback is
-about to be invoked, so it is not normally pending inside the watcher
-callback.
+in has occurred (such as a timer expiring), it will become pending. It
+will stay in this pending state until either it is explicitly stopped or
+its callback is about to be invoked, so it is not normally pending inside
+the watcher callback.
+.Sp
+Generally, the watcher might or might not be active while it is pending
+(for example, an expired non-repeating timer can be pending but no longer
+active). If it is pending but not active, it can be freely accessed (e.g.
+by calling \f(CW\*(C`ev_TYPE_set\*(C'\fR), but it is still property of the event loop at
+this time, so cannot be moved, freed or reused. And if it is active the
+rules described in the previous item still apply.
 .Sp
-The watcher might or might not be active while it is pending (for example,
-an expired non-repeating timer can be pending but no longer active). If it
-is stopped, it can be freely accessed (e.g. by calling \f(CW\*(C`ev_TYPE_set\*(C'\fR),
-but it is still property of the event loop at this time, so cannot be
-moved, freed or reused. And if it is active the 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.
 .Sp
 It is also possible to feed an event on a watcher that is not active (e.g.
 via \f(CW\*(C`ev_feed_event\*(C'\fR), in which case it becomes pending without being