Spectre.Operation.Budget (Spectre v0.3.0)

Copy Markdown View Source

Portable limits and consumption counters for one operational loop.

A missing limit means that dimension is not bounded. Budget checks happen before a Runner is created and again after its committed result.

Summary

Types

dimension()
t()

Functions

consume(budget, usage)

Consumes one or more budget dimensions.

exhausted(budget, now \\ System.system_time(:millisecond))

Returns the first exhausted dimension, if any.

new(value \\ nil, now \\ System.system_time(:millisecond))

Builds a validated budget from a struct, map, keyword list or nil.

remaining(budget, dimension)

Returns the remaining value for a bounded dimension.

validate(budget)

Validates the budget's limits, consumption counters, timestamps and portability.

validate!(budget)

Same as validate/1 but returns the budget, raising ArgumentError when invalid.

Types

dimension()

@type dimension() :: :steps | :attempts | :retries | :duration_ms | :pages | :cost

t()

@type t() :: %Spectre.Operation.Budget{
  consumed: %{optional(atom()) => non_neg_integer() | number()},
  deadline_at: non_neg_integer() | nil,
  limits: %{optional(dimension()) => non_neg_integer() | number() | nil},
  resources: map(),
  started_at: non_neg_integer()
}

Functions

consume(budget, usage)

@spec consume(t(), map() | keyword()) :: t()

Consumes one or more budget dimensions.

exhausted(budget, now \\ System.system_time(:millisecond))

@spec exhausted(t(), non_neg_integer()) :: nil | {dimension(), number(), number()}

Returns the first exhausted dimension, if any.

new(value \\ nil, now \\ System.system_time(:millisecond))

@spec new(t() | map() | keyword() | nil, non_neg_integer()) :: t()

Builds a validated budget from a struct, map, keyword list or nil.

nil yields an unbounded budget. Limits may be given at the top level or under :limits; a :duration_ms limit derives deadline_at from now unless a deadline is given explicitly. Raises ArgumentError when the result is invalid.

remaining(budget, dimension)

@spec remaining(t(), dimension()) :: number() | :infinity

Returns the remaining value for a bounded dimension.

validate(budget)

@spec validate(t()) :: :ok | {:error, term()}

Validates the budget's limits, consumption counters, timestamps and portability.

Returns :ok, or {:error, reason} naming the first invalid field.

validate!(budget)

@spec validate!(t()) :: t()

Same as validate/1 but returns the budget, raising ArgumentError when invalid.