From 18086694f4c9c6494d8074c71fb7c0011dc9e28e Mon Sep 17 00:00:00 2001 From: Sam Maloney <56830868+sam-maloney@users.noreply.github.com> Date: Tue, 21 Mar 2023 16:39:35 -0600 Subject: [PATCH] rfc46: command line jobspec resources Problem: we cannot define arbitrary jobspec resources lists easily on the command line Define a compact string representation that can be mapped to a full jobspec resources request --- README.md | 1 + index.rst | 7 + spec_46.rst | 400 +++++++++++++++++++++++++++++++++++++++++++++++++++ spell.en.pws | 1 + 4 files changed, 409 insertions(+) create mode 100644 spec_46.rst diff --git a/README.md b/README.md index 8f04b86..2e383ad 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,7 @@ Table of Contents - [43/Job List Service](spec_43.rst) - [44/Resource Events](spec_44.rst) - [45/Resource Range String Representation](spec_45.rst) +- [46/Command Line Job](spec_46.rst) Build Instructions ------------------ diff --git a/index.rst b/index.rst index 8afc69d..9213bf7 100644 --- a/index.rst +++ b/index.rst @@ -294,6 +294,12 @@ Changes to resource availability are recorded in an RFC 18 eventlog. This specification describes a compact form for expressing an RFC 14 resource range defined by a min/max/operand/operator combination. +:doc:`spec_46` +~~~~~~~~~~~~~~ + +This specification describes a compact form for expressing an RFC 14 jobspec +resources list that can be provided to several Flux commands by a user. + .. Each file must appear in a toctree .. toctree:: :hidden: @@ -341,3 +347,4 @@ resource range defined by a min/max/operand/operator combination. spec_43 spec_44 spec_45 + spec_46 diff --git a/spec_46.rst b/spec_46.rst new file mode 100644 index 0000000..b260eb5 --- /dev/null +++ b/spec_46.rst @@ -0,0 +1,400 @@ +.. github display + GitHub is NOT the preferred viewer for this file. Please visit + https://flux-framework.rtfd.io/projects/flux-rfc/en/latest/spec_46.html + +46/Command Line Job Specification Resources Shape +################################################# + +This specification describes a compact form for expressing an RFC 14 jobspec +resources list that can be provided to several Flux commands by a user. + +.. list-table:: + :widths: 25 75 + + * - **Name** + - github.com/flux-framework/rfc/spec_46.rst + * - **Editor** + - Sam Maloney + * - **State** + - raw + +Language +******** + +.. include:: common/language.rst + +Related Standards +***************** + +- :doc:`spec_4` +- :doc:`spec_14` +- :doc:`spec_22` +- :doc:`spec_25` +- :doc:`spec_45` + + +Goals +***** + +- Express a resource specification on the command line (a.k.a. a "shape") to + expand into the resources list of a Canonical Job Specification. + +- The shape should make simple resource requests compact and easy to express, + but without restricting complex requests from being fully specifiable. + +- Allow inclusion in several submission contexts, including submit, run, and batch. + + +Overview +******** + +This RFC describes a "shape" string that can be expanded into the full YAML +or JSON representation of the equivalent :doc:`RFC 14 ` Job +Specification resources list. + +Description +*********** + +A shape string is essentially a compacted form of the equivalent JSON array, +according to the following rules: + +- Every level of the resource graph (including the outermost level) is a list + of resource vertices which SHALL be separated by a semicolon ``;`` (to reduce + ambiguity with commas in idsets for counts) and the entire list SHALL in + general be surrounded by square brackets ``[...]`` except: + + - If a list contains only a single vertex then the brackets MAY be omitted. + +- A resource vertex is a dictionary which SHALL be represented by the general + form ``={:}``, where ```` and ```` are + the *values* of the corresponding mandatory keys, and the following apply: + + - Strings such as ````, ````, or a string type ```` do not + need to be quoted unless they contain special characters (or would otherwise + be parsed as a different ```` type). + + - ```` SHALL be one of a positive integer, an :doc:`RFC 22 ` + idset, or an :doc:`RFC 45 ` compact range string (i.e. not a range + dictionary). + + - If the ```` is integer ``1`` then it (and the ``=``) MAY be omitted. + + - If the ```` is ``slot`` then the first entry in the braces SHALL be + the *value* (and only the value) of the mandatory ``label`` key, except: + + - If there is only a single ``slot`` vertex in the entire jobspec, then the + label MAY be omitted; however, if there are any other ``:`` + pairs then the label is REQUIRED and MUST be the first entry. + + - Additional ``:`` pairs SHALL be separated by a comma ``,``. + + - Boolean keys (e.g. ``exclusive``) MAY omit the ``:`` and instead: + + - Prepend either ``+`` or ``-`` to the key name to indicate ``true`` or + ``false`` respectively, or: + + - Add nothing to indicate an implicit value of ``true``. + + - As a special case, the ``exclusive`` key may be shortened to simply ``x``. + + - The ```` should be a `valid JSON value + `_, except: + + - Objects (sub-dictionaries) MAY be specified with the same syntax as the + outer dict (i.e. using unquoted strings/keys and shortened booleans). + + - If there are no ``:`` pairs or slot ``