29/Hostlist Format

This specification describes a compact form for expressing a list of hostnames which contain an optional numerical part.

  • Name: github.com/flux-framework/rfc/spec_29.rst

  • Editor: Mark A. Grondona <mgrondona@llnl.gov>

  • State: raw

Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Background

The hostlist is a somewhat well known format supported by existing HPC tools such as pdsh, powerman, and genders. The format is designed as a convenience on systems where hostnames are assigned with a common prefix, a numeric part, and an optional suffix. The result is a compact way to represent a possibly large list of hosts by name, e.g. prefix[0-1024].

This RFC details the Flux implementation of the hostlist format.

Implementation

A hostlist SHALL represent an ordered list of strings.

A hostlist string SHALL be a list of comma separated hostlist expressions.

A hostlist expression SHALL be a string of the form prefix[idlist]suffix, where all components prefix, [idlist], and suffix are OPTIONAL.

An empty hostlist expression, "", SHALL represent an empty list.

The prefix and suffix components of a hostlist expression SHALL consist of any printable, non-whitespace ASCII character besides the special characters including square brackets: “[ ]”, and comma: “,”.

An idlist SHALL represent an ordered list of non-negative integer ids.

An idlist MAY be a simple comma-separated list, e.g. 5,4,10,11,12,13.

Consecutive ids in an idlist MAY be compressed into hyphenated ranges, e.g. 5,4,11-13.

Leading zeros in the first element of an idlist SHALL be preserved across all ids in the list, e.g. 005,4,11-13 represents the list 005,004,011,012,013.

An idlist MAY contain repeated numbers, e.g. 2,2,2 is a valid list.

Within a hostlist expression, an idlist SHALL be enclosed in square brackets, e.g. host[0-10,12].

Test Vectors

  • "" = ""

  • "foox,fooy,fooz" = "foox,fooy,fooz"

  • "[1-3,5-6]" = "1,2,3,5,6"

  • "foo[1-5]" = "foo1,foo2,foo3,foo4,foo5"

  • "foo[0-4]-eth2" = "foo0-eth2,foo1-eth2,foo2-eth2,foo3-eth2,foo4-eth2"

  • "foo1,foo1,foo1" = "foo1,foo1,foo1"

  • "[00-02]" = "00,01,02"

  • "[00-2]" = "00,01,02"

  • "foo[1,1,2,1]" = "foo1,foo1,foo2,foo1"