From 59e44a08009a18393148eb944a105ef07c2637fb Mon Sep 17 00:00:00 2001 From: Jim Garlick Date: Sat, 11 Nov 2023 07:25:50 -0800 Subject: [PATCH] flux-pmi(1): add a new manual page Problem: flux-pmi has no documentation. Add man page. --- doc/Makefile.am | 1 + doc/man1/flux-pmi.rst | 137 ++++++++++++++++++++++++++++++++++++++++++ doc/manpages.py | 1 + doc/test/spell.en.pws | 1 + 4 files changed, 140 insertions(+) create mode 100644 doc/man1/flux-pmi.rst diff --git a/doc/Makefile.am b/doc/Makefile.am index 14ea2f292c0d..59ff42e1cdb5 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -41,6 +41,7 @@ MAN1_FILES_PRIMARY = \ man1/flux-job.1 \ man1/flux-version.1 \ man1/flux-jobs.1 \ + man1/flux-pmi.1 \ man1/flux-pstree.1 \ man1/flux-restore.1 \ man1/flux-shell.1 \ diff --git a/doc/man1/flux-pmi.rst b/doc/man1/flux-pmi.rst new file mode 100644 index 000000000000..3eee9923e985 --- /dev/null +++ b/doc/man1/flux-pmi.rst @@ -0,0 +1,137 @@ +=========== +flux-pmi(1) +=========== + + +SYNOPSIS +======== + +[**launcher**] **flux-pmi** [*OPTIONS*] *SUBCOMMAND* [OPTIONS] + + +DESCRIPTION +=========== + +.. program:: flux pmi + +:program:`flux pmi` is a standalone Process Management Interface (PMI) client +that embeds the same PMI client plugins as :man1:`flux-broker`. It can be +used to test the PMI service offered by :man1:`flux-shell` to parallel +programs launched by Flux, or to probe the PMI services of an external +launcher like Slurm or Hydra in isolation, without the complications of +starting a Flux instance. + +:program:`flux pmi` tries a sequence of PMI plugins until one successfully +initializes. Alternatively, the specific plugin can be forced with the +:option:`--method` option. Initialization is followed by a subcommand-specific +sequence of PMI operations that mimics a common pattern, and then PMI +finalization. The subcommand operations are as follows: + +barrier + #. Execute PMI barrier + #. Execute PMI barrier + #. Print elapsed time of (2) + +exchange + #. Execute PMI barrier + #. Put rank specific key to PMI KVS + #. Execute PMI barrier + #. Get rank specific key from PMI KVS for all other ranks + #. Execute PMI barrier + #. Print elapsed time of (2-5) + +get + Fetch a pre-set key from the PMI KVS. + + +GENERAL OPTIONS +=============== + +General options are placed before the subcommand. + +.. option:: -h, --help + + Summarize the general options. + +.. option:: -v, --verbose[=LEVEL] + + Trace PMI operations. This is equivalent to setting + :envvar:`FLUX_PMI_DEBUG` in the broker environment. + +.. option:: --method=URI + + Specify the PMI method to use, where the scheme portion of the URI specifies + a plugin and the path portion specifies plugin-specific options. The + builtin plugins are + + simple + Use the simple PMI-1 wire protocol. + + libpmi2[:PATH] + :func:`dlopen` ``libpmi2.so`` and use the PMI-2 API, optionally + at a specific *PATH*. + + libpmi[:PATH] + :func:`dlopen` ``libpmi.so`` and use the PMI-1 API, optionally + at a specific *PATH*. + + single + Become a singleton. + +.. option:: --libpmi-noflux + + Fail if the libpmi or libpmi2 methods find the Flux ``libpmi.so``. + +.. option:: --libpmi2-cray + + Force the libpmi2 Cray workarounds to be enabled for testing. Normally + they are enabled only if a heuristic detects that Cray libpmi2 is in use. + The workarounds are + + - Encode all KVS values with base64. + - Immediately fail an attempt to fetch any KVS with a ``flux.`` prefix. + +BARRIER OPTIONS +=============== + +.. option:: -h, --help + + Summarize the barrier subcommand options. + +.. option:: --count=N + + Execute *N* barrier operations (default 1). + +EXCHANGE OPTIONS +================ + +.. option:: -h, --help + + Summarize the exchange subcommand options. + +.. option:: --count=N + + Execute *N* exchange operations (default 1). + +GET OPTIONS +=========== + +.. option:: -h, --help + + Summarize the get subcommand options. + +.. option:: --ranks=RANKS + + Print the value on specified *RANKS*, an RFC 22 idset or ``all`` (default 0). + + +RESOURCES +========= + +Flux: http://flux-framework.org + + +SEE ALSO +======== + +:man7:`flux-broker-attributes` diff --git a/doc/manpages.py b/doc/manpages.py index 07208a731c54..52e01d158129 100644 --- a/doc/manpages.py +++ b/doc/manpages.py @@ -43,6 +43,7 @@ ('man1/flux-cancel', 'flux-cancel', 'cancel one or more jobs', [author], 1), ('man1/flux-pgrep', 'flux-pgrep', 'search or cancel matching jobs', [author], 1), ('man1/flux-pgrep', 'flux-pkill', 'search or cancel matching jobs', [author], 1), + ('man1/flux-pmi', 'flux-pmi', 'PMI client test tool', [author], 1), ('man1/flux-jobtap', 'flux-jobtap', 'List, remove, and load job-manager plugins', [author], 1), ('man1/flux-shutdown', 'flux-shutdown', 'Shut down a Flux instance', [author], 1), ('man1/flux-uri', 'flux-uri', 'resolve Flux URIs', [author], 1), diff --git a/doc/test/spell.en.pws b/doc/test/spell.en.pws index 0aa797ee2e9f..d1766f17405f 100644 --- a/doc/test/spell.en.pws +++ b/doc/test/spell.en.pws @@ -793,3 +793,4 @@ execvp gdb libtool prepend +noflux