# -*- text -*-
#
# Copyright (c) 2025-2026 Nanook Consulting  All rights reserved.
# $COPYRIGHT$
#
# Additional copyrights may follow
#
# $HEADER$
#
# This is the US/English general help file for PRTE's dash-host.
#
[host]

Host syntax consists of a comma-delimited list of node names, each
entry optionally containing a ":N" extension indicating the number of
slots to assign to that entry:

   --host node01:5,node02

In the absence of the slot extension, one slot will be assigned to the
node. Duplicate entries are aggregated and the number of slots
assigned to that node are summed together.

Note:

  A "slot" is the PRRTE term for an allocatable unit where we can
  launch a process. Thus, the number of slots equates to the maximum
  number of processes PRRTE may start on that node without
  oversubscribing it.

See the "Host specification" HTML documentation for details about the
format and content of hostfiles.
#
[add-host]

PRRTE allows a user to expand an existing DVM prior to launching an
application.  Users can specify a a comma-delimited list of node
names, each entry optionally containing a ":N" extension indicating
the number of slots to assign to that entry:

   --host node01:5,node02

In the absence of the slot extension, one slot will be assigned to the
node. Duplicate entries are aggregated and the number of slots
assigned to that node are summed together.

Note:

  A "slot" is the PRRTE term for an allocatable unit where we can
  launch a process. Thus, the number of slots equates to the maximum
  number of processes PRRTE may start on that node without
  oversubscribing it.

The list can include nodes that are already part of the DVM — in this
case, the number of slots available on those nodes will be set to the
new specification, or adjusted as directed:

   --host node01:5,node02

would direct that node01 be set to 5 slots and node02 will have 1
slot, while

   --host node01:+5,node02

would add 5 slots to the current value for node01, and

   --host node01:-5,node02

would subtract 5 slots from the current value.

Slot adjustments for existing nodes will have no impact on currently
executing jobs, but will be applied to any new spawn requests. Nodes
contained in the add-host specification are available for immediate
use by the accompanying application.

Users desiring to constrain the accompanying application to the newly
added nodes should also include the "--host" command line directive,
giving the same hosts in its argument:

   --add-host node01:+5,node02 --host node01:5,node02

Note that the "--host" argument indicates the number of slots to
assign node01 for this spawn request, and not the number of slots
being added to the node01 allocation.

#
[activate]

A DVM does not necessarily span every node of its allocation.  A
"--host" or "--hostfile" given when the DVM was started narrows which
allocated nodes get a daemon, and a released reservation hands its
nodes back without one.  Such a node is allocated and up, but no part
of the DVM: nothing can be launched on it.

"--activate" starts a daemon on those nodes, bringing them into the
DVM before the accompanying application is launched.  It takes the
same argument syntax as "--host": a comma-delimited list of node
names,

   --activate node01,node02

or, to bring in everything the allocation holds that is not already in
the DVM,

   --activate +all

or the relative form that names a node by its position in the
allocation,

   --activate +n3

which selects the fourth node (relative node indices count from zero).
Entries may also name a file, in the same format "--hostfile" reads:

   --activate file=/path/to/hostfile

and the forms may be mixed in one list:

   --activate node01,file=/path/to/hostfile

Only the node names are taken from the file.  A "slots=" it carries is
not applied - a hostfile given to a launcher selects nodes, it does not
resize them - but everything else the hostfile format offers, including
"^host" exclusions, works as it does anywhere else.

Note that "+e" is NOT accepted here.  For "--host" it means "nodes with
no application process running on them", which says nothing about
whether a node is in the DVM: most of the nodes it picks are already in
it, so the request would start no daemon and still report success.

Unlike "--add-host", this adds nothing to the allocation.  It can only
name nodes the allocation already contains, it changes no slot counts,
and it asks no resource manager for anything - which is why it is
permitted even where the allocation is owned by a scheduler and
"--add-host" is refused.  For the same reason a ":N" slot extension is
not accepted here: activate has no authority to set slot counts, so a
count given to it is refused rather than silently ignored.

Naming a node that is already in the DVM is not an error - the request
is a statement about the DVM's membership, and for that node it is
already satisfied.  For the same reason "+all" is satisfied, not
refused, when every allocated node is already in the DVM.

Users desiring to constrain the accompanying application to the newly
activated nodes should also include the "--host" command line
directive, giving the same hosts in its argument:

   --activate node01,node02 --host node01,node02

#
[not-all-mapped-alloc]

At least one of the requested hosts is not included in the current
allocation.

   Missing requested host: %s

Please check your allocation or your request.
#
[dash-host:relative-node-not-found]

A relative host was specified, but was not found. The requested host
was specified with "--host" as:

   Index: %d
   Syntax given: %s

Re-run this command with "--help hosts" for further information.
#
[dash-host:relative-node-out-of-bounds]

A relative host was specified, but the index given is beyond the
number of hosts in the current allocation:

   Index: %d
   #hosts: %d

You could obtain a larger allocation or reduce the relative host
index.

Re-run this command with "--help hosts" for further information.
#
[dash-host:invalid-relative-node-syntax]

A relative host was improperly specified — the value provided was.

   --host: %s

You may have forgotten to preface a node with "N" or "n", or used the
"e" or "E" to indicate empty nodes, or you ended the value with a
colon but forgot to include the number of empty nodes you were
requesting.

Re-run this command with "--help hosts" for further information.
#
[dash-host:not-enough-empty]

The requested number of empty hosts was not available — the system was
short by %d hosts.  Please recheck your allocation.

Re-run this command with "--help hosts" for further information.
#
[dash-host:slots-exceed-allocation]

The "--host" specification asked for more slots on a node than the
allocation provides:

   Node:              %s
   Slots requested:   %d
   Slots available:   %d

The allocation came from a resource manager, so the number of slots on
this node is not PRRTE's to change — a "--host" entry can only select
from what was allocated to you.

Either reduce the number requested for this host, obtain a larger
allocation, or add the ":OVERSUBSCRIBE" qualifier to your mapping
directive if you truly want more processes than slots on this node.
#
[dash-host:slots-exceed-max]

The "--host" specification asked for more slots on a node than its
maximum permits:

   Node:              %s
   Slots requested:   %d
   Slots available:   %d
   Max slots:         %d

The maximum slot count is a hard limit — unlike the slot count itself,
it cannot be raised by a "--host" entry. It is usually set by a
"max_slots=" entry in a hostfile.

Either reduce the number requested for this host or raise the maximum
for this node.
