flux.resource.ResourceCount module

ResourceCount: parsed RFC 14/22 resource count with iteration support.

A ResourceCount wraps one of three count forms that may appear in a jobspec resource vertex:

  • a simple integer (fixed count)

  • an RFC 14 range dict {"min": N, "max": M, "operator": OP, "operand": K}

  • an RFC 45 string ("2-8:2:*", "2+", IDset "1,7-9", …)

The design of the parsing interface mirrors libjob/count.h:

count_create(json_t *)   →  ResourceCount.from_count_spec(int | dict | str)
count_first / count_next →  ResourceCount.valid_counts(available)
class flux.resource.ResourceCount.ResourceCount(mn, mx, values=None)

Bases: object

Parsed RFC 14/22 resource count with full iteration support.

Wraps the three count forms that appear in a jobspec resource vertex (integer, RFC 14 range dict, RFC 45 / IDset string) into a uniform object that schedulers can iterate over candidate values.

min

Minimum (or fixed) count value.

Type

int

max

Maximum count value. None means unbounded.

Type

int | None

_values

Explicit ordered set of valid values for stepped arithmetic and IDset count forms. None for simple contiguous integer ranges and unbounded ranges.

Type

IDset | None

See also

from_count_spec() — construct from a parsed-jobspec count field.

classmethod from_count_spec(v, default=1)

Parse an RFC 14/22 count spec and return a ResourceCount.

Modeled after count_create() / count_decode() in libjob/count.h: accepts the same three representations that appear in a JSON-parsed jobspec resource vertex.

Supported forms:

  • Integer: 4 → ResourceCount(4, 4)

  • Range dict: {"min": 2, "max": 8} → ResourceCount(2, 8)

  • Unbounded dict: {"min": 2} → ResourceCount(2, None)

  • Stepped dict: {"min": 2, "max": 8, "operator": "*", "operand": 2} → ResourceCount(2, 8, IDset("2,4,8"))

  • RFC 45 range string: "2-5" → ResourceCount(2, 5); "2+" → ResourceCount(2, None)

  • Stepped RFC 45 string: "2-8:2:*" → ResourceCount(2, 8, IDset("2,4,8"))

  • IDset string: "1,7-9" → ResourceCount(1, 9, IDset("1,7-9"))

Strings may optionally be surrounded by square brackets per RFC 45.

_values is None for simple contiguous ranges and unbounded ranges; set to an IDset for stepped and non-contiguous IDset forms.

Parameters

  • v -- Count spec — an int, dict, or str as it appears in a JSON-decoded jobspec. Any other type is treated as a fixed count equal to default.

  • default (int) -- Fallback fixed count when v is not a recognised type. Defaults to 1.

Raises

ValueError -- For unbounded ranges with a non-unit step (cannot be expanded to a finite set), unsupported operators, or counts less than 1.

max
min
scaled(factor)

Return a new ResourceCount with all values multiplied by factor.

Returns self unchanged when factor is 1 (avoids an allocation).

valid_counts(available)

Yield valid count values <= available, largest first.

Mirrors count_first() / count_next() from libjob/count.h but presents the sequence in descending order so callers can greedily try the largest feasible allocation first.

Parameters

available (int) -- Upper bound (e.g. number of available resources).

Yields

int --

Valid count values in descending order, from

min(available, max) (or just available if unbounded) down to min. Nothing is yielded when available < min.