Skip to content

Commit

Permalink
flux_watcher_start(3): add ref/unref/is_ref
Browse files Browse the repository at this point in the history
Problem: flux_watcher_ref(), flux_watcher_unref(), and
flux_watcher_is_referenced() are undocumented.

Update man pages.
  • Loading branch information
garlick committed Dec 23, 2024
1 parent 2fbd742 commit a12af4e
Show file tree
Hide file tree
Showing 4 changed files with 33 additions and 5 deletions.
3 changes: 3 additions & 0 deletions doc/Makefile.am
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,9 @@ MAN3_FILES_SECONDARY = \
man3/flux_watcher_stop.3 \
man3/flux_watcher_is_active.3 \
man3/flux_watcher_destroy.3 \
man3/flux_watcher_ref.3 \
man3/flux_watcher_unref.3 \
man3/flux_watcher_is_referenced.3 \
man3/flux_watcher_next_wakeup.3 \
man3/flux_handle_watcher_get_flux.3 \
man3/flux_timer_watcher_reset.3 \
Expand Down
21 changes: 21 additions & 0 deletions doc/man3/flux_watcher_start.rst
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,12 @@ SYNOPSIS
bool flux_watcher_is_active (flux_watcher_t *w);
void flux_watcher_unref (flux_watcher_t *w);
void flux_watcher_ref (flux_watcher_t *w);
bool flux_watcher_is_referenced (flux_watcher_t *w);
void flux_watcher_destroy (flux_watcher_t *w);
double flux_watcher_next_wakeup (flux_watcher_t *w);
Expand All @@ -36,6 +42,21 @@ callback.
:func:`flux_watcher_is_active` returns a true value if the watcher is active
(i.e. it has been started and not yet stopped) and false otherwise.

:func:`flux_watcher_unref` drops the watcher's reference on the reactor.
This function is idempotent. :func:`flux_reactor_run` normally runs until
there are no more active watchers with references.

:func:`flux_watcher_ref` restores the watcher's reference on the reactor.
This function is idempotent.

:func:`flux_watcher_is_referenced` returns true if the watcher is referenced.
All watchers are referenced unless updated with :func:`flux_watcher_unref`.

.. note::
All watchers in the public API support :func:`flux_watcher_unref`, but some
specialized watchers internal to flux-core do not. If in doubt about whether
the call had any effect, check with :func:`flux_watcher_is_referenced`.

:func:`flux_watcher_destroy` destroys a :type:`flux_watcher_t` object :var:`w`,
after stopping it. It is not safe to destroy a watcher object within a
:type:`flux_watcher_f` callback.
Expand Down
13 changes: 8 additions & 5 deletions doc/manpages.py
Original file line number Diff line number Diff line change
Expand Up @@ -280,11 +280,14 @@
('man3/flux_stat_watcher_create', 'flux_stat_watcher_create', 'create stat watcher', [author], 3),
('man3/flux_timer_watcher_create', 'flux_timer_watcher_reset', 'set/reset a timer', [author], 3),
('man3/flux_timer_watcher_create', 'flux_timer_watcher_create', 'set/reset a timer', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_stop', 'start/stop/destroy/query reactor watcher', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_is_active', 'start/stop/destroy/query reactor watcher', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_destroy', 'start/stop/destroy/query reactor watcher', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_next_wakeup', 'start/stop/destroy/query reactor watcher', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_start', 'start/stop/destroy/query reactor watcher', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_stop', 'common reactor watcher methods', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_is_active', 'common reactor watcher methods', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_destroy', 'common reactor watcher methods', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_next_wakeup', 'common reactor watcher methods', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_start', 'common reactor watcher methods', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_ref', 'common reactor watcher methods', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_unref', 'common reactor watcher methods', [author], 3),
('man3/flux_watcher_start', 'flux_watcher_is_referenced', 'common reactor watcher methods', [author], 3),
('man3/flux_watcher_set_priority', 'flux_watcher_set_priority', 'set watcher priority', [author], 3),
('man3/hostlist_create', 'hostlist_create', 'Manipulate lists of hostnames', [author], 3),
('man3/hostlist_create', 'hostlist_destroy', 'Manipulate lists of hostnames', [author], 3),
Expand Down
1 change: 1 addition & 0 deletions doc/test/spell.en.pws
Original file line number Diff line number Diff line change
Expand Up @@ -939,3 +939,4 @@ aTGTz
cPATH
SATTR
myprogram
unref

0 comments on commit a12af4e

Please sign in to comment.