Merge pull request #6829 from garlick/clique_term

doc: update glossary with parallel program terms + trivial broker cleanup

Author: mergify[bot]

doc/guide/glossary.rst

@@ -6,6 +6,11 @@ used in our documentation that may not be familiar to all readers.
 
 .. glossary::
 
+  clique
+    A group of :term:`tasks <task>` belonging to a :term:`parallel program`
+    that are co-located on a node.  Cliques may communicate with each other
+    more efficiently than tasks on different nodes.
+
   enclosing instance
     The Flux instance that a process naturally interacts with.  It is
     the instance referred to by the :envvar:`FLUX_URI` environment variable,
@@ -60,7 +65,9 @@ used in our documentation that may not be familiar to all readers.
 
   job
     The smallest unit of work that can be allocated resources and run by Flux.
-    A job can be a Flux instance which in turn can run more jobs.
+    A job is typically a :term:`parallel program`, but may consist of one
+    or more :term:`singletons <singleton>`.  A job can be a Flux instance
+    which in turn can run more jobs.
 
   jobspec
     The JSON or YAML object representing a Flux job request, defined by
@@ -77,6 +84,10 @@ used in our documentation that may not be familiar to all readers.
     A moldable job requests a variable, bounded quantity of resources
     that, once allocated by the system, is fixed at runtime [#Feitelson96]_.
 
+  parallel program
+    A ranked group of :term:`tasks`, often the same executable, launched
+    in parallel and working together to solve a problem.
+
   priority
     The order in which the scheduler considers jobs.  By default, priority
     is derived from the :term:`urgency` and submit time, but a priority plugin
@@ -102,8 +113,11 @@ used in our documentation that may not be familiar to all readers.
     and resource utilization when it decides upon a schedule for fulfilling
     competing requests.
 
+  singleton
+    A degenerate :term:`parallel program` with only one :term:`task`.
+
   slot
-    The abstract resource requirements of one task.
+    The abstract resource requirements of one :term:`task`.
 
   step
     In other workload managers, a job step is a unit of work within a job.
@@ -116,8 +130,12 @@ used in our documentation that may not be familiar to all readers.
     system user like ``flux``, is started by :linux:man1:`systemd`, and
     allows :term:`guest` users to run jobs.
 
+  task
+    A process at the operating system level.  A task may represent one
+    rank of a :term:`parallel program`.
+
   taskmap
-    A compact mapping between job task ranks and node IDs, defined by
+    A compact mapping between job :term:`task` ranks and node IDs, defined by
     :doc:`rfc:spec_34`.
 
   TBON

doc/man1/flux-start.rst

@@ -204,11 +204,12 @@ OPTIONS
 
 .. option:: --test-pmi-clique=MODE
 
-   Set the pmi clique mode, which determines how ``PMI_process_mapping`` is set
-   in the PMI server used to bootstrap the brokers.  If ``none``, the mapping
-   is not created.  If ``single``, all brokers are placed in one clique. If
-   ``per-broker``, each broker is placed in its own clique.  Otherwise the
-   option argument is interpreted as an RFC 34 taskmap.  Default: ``single``.
+   Set the PMI :term:`clique` mode, which determines how
+   ``PMI_process_mapping`` is set in the PMI server used to bootstrap the
+   brokers.  If ``none``, the mapping is not created.  If ``single``, all
+   brokers are placed in one clique. If ``per-broker``, each broker is placed
+   in its own clique.  Otherwise the option argument is interpreted as an
+   RFC 34 taskmap.  Default: ``single``.
 
 .. option:: -r, --recovery=[TARGET]
 

src/broker/boot_pmi.c

@@ -133,7 +133,7 @@ static int fetch_taskmap (struct upmi *upmi,
     return 0;
 }
 
-/* Set broker.mapping attribute from enclosing instance taskmap.
+/* Set broker.mapping attribute.
  * It is not an error if the map is NULL.
  */
 static int set_broker_mapping_attr (attr_t *attrs, struct taskmap *map)
@@ -150,38 +150,24 @@ static int set_broker_mapping_attr (attr_t *attrs, struct taskmap *map)
     return 0;
 }
 
-/* Count the number of TBON children that could be reached by IPC.
+/* Return the number of ranks[] members that are in the same clique as rank.
  */
-static int count_local_children (struct taskmap *map,
-                                 int *child_ranks,
-                                 int child_count,
-                                 int rank)
+static int clique_ranks (struct taskmap *map, int rank, int *ranks, int nranks)
 {
     int count = 0;
 
     if (map) {
-        int nodeid = taskmap_nodeid (map, rank); // this broker's nodeid
-        if (nodeid >= 0) {
-            for (int i = 0; i < child_count; i++) {
-                if (taskmap_nodeid (map, child_ranks[i]) == nodeid)
+        int nid = taskmap_nodeid (map, rank);
+        if (nid >= 0) {
+            for (int i = 0; i < nranks; i++) {
+                if (taskmap_nodeid (map, ranks[i]) == nid)
                     count++;
             }
         }
     }
     return count;
 }
 
-static bool ranks_are_peers (struct taskmap *map, int rank1, int rank2)
-{
-    int nid1;
-    int nid2;
-
-    if ((nid1 = taskmap_nodeid (map, rank1)) < 0
-        || (nid2 = taskmap_nodeid (map, rank2)) < 0)
-        return false;
-    return (nid1 == nid2 ? true : false);
-}
-
 /* Check if TCP should be used, even if IPC could work.
  */
 static bool get_prefer_tcp (attr_t *attrs)
@@ -532,10 +518,7 @@ int boot_pmi (const char *hostname, struct overlay *overlay, attr_t *attrs)
         char tcp[1024];
         char ipc[1024];
 
-        nlocal = count_local_children (taskmap,
-                                       child_ranks,
-                                       child_count,
-                                       info.rank);
+        nlocal = clique_ranks (taskmap, info.rank, child_ranks, child_count);
 
         if (format_tcp_uri (tcp, sizeof (tcp), attrs, &error) < 0) {
             log_err ("%s", error.text);
@@ -600,7 +583,7 @@ int boot_pmi (const char *hostname, struct overlay *overlay, attr_t *attrs)
             goto error;
         }
         if (!get_prefer_tcp (attrs)
-            && ranks_are_peers (taskmap, info.rank, parent_rank))
+            && clique_ranks (taskmap, info.rank, &parent_rank, 1) == 1)
             uri = bizcard_uri_find (bc, "ipc://");
         if (!uri)
             uri = bizcard_uri_find (bc, NULL);