.\" For license: see LICENSE file at top-level
.TH oshrun 1 "" "OSSS-UCX"
.SH NAME
\fBoshrun\fP \- run an OpenSHMEM program
.SH SYNOPSIS
\fBoshrun | oshexec\fP
.RS 2
.br
[launcher pass-through arguments]
.br
[ -n N | -np N ]
.br
program [arguments...]
.RE
.SH DESCRIPTION
\fBoshrun\fP, a.k.a. \fBoshexec\fP, runs an OpenSHMEM program on the
given number of processing elements.
.SH OPTIONS
.IP "-n N | -np N" 2
Run the program on N processing elements (PEs or processors).
Overrides any PE count inherited from launch environment.
.LP
.SH ENVIRONMENT
.LP
If set, boolean flags are enabled with a non-zero numeric value, or
"y", "yes", or "on"; disabled with zero numeric value, or "n", "no",
or "off".
.LP
Controlling the launcher:
.LP
.RS 2
.IP "OSHRUN_DEBUG (bool, default: false)"
If set to true, oshrun outputs its progress of launching the
application to standard error.
.RE
.\"
.LP
OpenSHMEM environment variables are prefixed with "SHMEM_".
.LP
Some older SHMEM implementations had variables prefixed with "SMA_":
these are still supported in OpenSHMEM, but are deprecated.  If both
are set for a given variable, the "SHMEM_" one will be used.
.LP
.\"
.RS 2
.\"
.LP
Required by specification:
.RS 2
.IP "SHMEM_VERSION, SMA_VERSION (bool: default false)"
print library version at start-up
.IP "SHMEM_INFO, SMA_INFO (bool: default false)"
print information about supported environment variables
.IP "SHMEM_SYMMETRIC_SIZE, SMA_SYMMETRIC_SIZE (number: default @SHMEM_DEFAULT_HEAP_SIZE@)"
set the size of the symmetric heap, in bytes.  Can add K,M,G,T units
(2^10).
.IP "SHMEM_DEBUG, SMA_DEBUG (bool: default false)"
enable run debugging/sanity checking (if configured).
.RE
.LP
This implementation also has:
.RS 2
.IP "SHMEM_LOGGING (bool: default false)"
enable message logging (if configured).
.IP "SHMEM_LOGGING_EVENTS (string: default none)"
A comma-separated list of events that selects logging messages (if
logging enabled, see above): fatal, init, finalize, memory, heaps,
contexts, info, reductions, barriers, deprecate, locks, atomics; or
"all".
.RE
.RS 2
.IP "SHMEM_LOGGING_FILE (string: default none)"
filename to receive logging information.  "%" substitutions are: "%h"
for hostname, "%p" for process ID, "%n" for PE number, and "%N" for
the number of PEs.
.RE
.RS 2
.IP "SHMEM_PREALLOC_CTXS (integer: default 64)"
How many OpenSHMEM context slots to preallocate at startup.
.RE
.RS 2
.IP "SHMEM_LAUNCHER (default: search)"
Name of program to use for underlying launcher.  Default behavior is
to search for PRRTE or a PMIx-aware MPI launcher.  Can also be set by
configure.
.RE
.RS 2
.IP "SHMEM_PROGRESS_THREADS (default: unset)"
If we need extra progress for transports that don't provide it,
activate progress threads on the named PEs, e.g. "0", "1-3", "2,4,6";
or on all PEs if the variable's (case-insensitive) value is "y[es]" or
"a[ll]".
.RE
.RS 2
.IP "SHMEM_PROGRESS_DELAY (default: 1000)"
If progress threads requested, control the delay between polls.  Given
in nanoseconds.
.RE
.RS 2
.IP "SHMEM_MEMERR_FATAL (bool, default: true)"
If set to true, symmetric memory corruption or overflow is treated as
a fatal condition, and the program exits.  If unset or false, the
issue will be logged (see SHMEM_LOGGING and
SHMEM_LOGGING_EVENTS=memory above), but the program will try to
continue, which will likely lead to undefined behavior.
.RE
.LP
Collectives:
.LP
The possible values for the different algorithms are those implemented
in SHCOLL, q.v.
.RS 2
.IP "SHMEM_{BARRIER,BARRIER_ALL}__ALGO (string: binomial_tree)"
Algorithm name to use for barriers.
.RE
.RS 2
.IP "SHMEM_{SYNC,SYNC_ALL}__ALGO (string: default binomial_tree)"
Algorithm name to use for syncs.
.RE
.RS 2
.IP "SHMEM_BROADCAST_ALGO (string: default binomial_tree)"
Algorithm name to use for broadcasts.
.RE
.RS 2
.IP "SHMEM_COLLECT_ALGO (string: default bruck)"
Algorithm name to use for collects.
.RE
.RS 2
.IP "SHMEM_FCOLLECT_ALGO (string: default bruck_inplace)"
Algorithm name to use for fixed collects.
.RE
.RS 2
.IP "SHMEM_{ALLTOALL,ALLTOALLS}_ALGO (string: default color_pairwise_exchange_counter)"
Algorithm name to use for alltoall/alltoalls.
.RE
.\"
.RE
.\"
.SH EXAMPLES
The command
.LP
.RS 2
$ oshrun -np 4 ./sping.x -e 8192
.RE
.LP
runs the ping-pong code from
.RS 2
.LP
\f(CRhttps://github.com/openshmem-org/openshmem-examples\fP
.RE
.LP
on 4 processing elements, and passes the command-line arguments "-e"
and "8192" through to the OpenSHMEM program.
.SH NOTES
.LP
The OpenSHMEM specification does not say anything normative about how
OpenSHMEM programs are compiled, linked and launched.  These wrapper
programs are supplied as part of the Reference Library for
convenience.
.SH SEE ALSO
osh_intro(1).
.LP
SHCOLL \f(CRhttps://github.com/srki/shcoll\fP.
.SH OPENSHMEM
\f(CRhttp://www.openshmem.org/\fP
.br
\f(CRhttps://github.com/openshmem-org/openshmem-examples\fP