ChoreRunner.Chore behaviour (chore_runner v0.5.0)
Behaviour and DSL for chores.
Link to this section Summary
Callbacks
An optional callback function for defining a chore's inputs.
An optional callback function for defining a chore restriction.
Optional callback to be called once the chore has been completed.
A non-optional callback used to contain the main Chore logic.
Link to this section Types
Specs
t() :: %ChoreRunner.Chore{ downloads: [ChoreRunner.Downloads.StorageService.file()], extra_data: map(), finished_at: DateTime.t(), id: String.t(), inputs: map(), logs: [{unix_timestamp(), String.t()}], mod: module(), reporter: pid(), result: any(), started_at: DateTime.t(), task: Task.t(), values: %{required(atom()) => number()} }
unix_timestamp()
Specs
unix_timestamp() :: integer()
Link to this section Callbacks
inputs()
Specs
inputs() :: [ChoreRunner.Input.t()]
An optional callback function for defining a chore's inputs.
Expects a list of input function calls.
The input functions provided are string
, int
, float
, file
, and bool
.
All input functions follow the same syntax.
For example:
def inputs do
[
string(:name),
int(:name2, [some: :option])
]
end
The supported options are
:description
— a string description of the input, for UI use:validators
— a list of anonymous or captured validator functions. Valiator functions should accept a single argument as a parameter, but can return a variety of things, including:- an
{:ok, value}
, or{:error, reason}
tuple - an
:ok
or:error
atom - a
true
orfalse
- any erlang value, or nil
The positive values (
:ok
,true
, non-falsey values) pass validation. The negative values (:error
,false
,nil
) fail validation If a value is passed back as part of an {:ok, value} tuple, or by itself, that value is treated as the new value of the given input. This way, validators can also transform input if needed. If this callback is not defined, the default return is[]
, or no inputs.
- an
restriction()
Specs
restriction() :: :none | :self | :global
An optional callback function for defining a chore restriction.
The restriction can be either :none, :self, or :global
:none
is no restrictions:self
prevents more than one of the same chore from running simultaneously across all connected nodes:global
prevents more than one of all chores with the restriction:global
from running simultaneously across all connected nodes. This restriction does not affect non-:global
chores. If this callback is not defined, the default return is:self
Specs
Optional callback to be called once the chore has been completed.
run(map)
Specs
A non-optional callback used to contain the main Chore logic.
Accepts a map of input, always atom keyed. (When calling ChoreRunner.run_chore/2, a string keyed map will be intelligently converted to an atom-keyed map automatically)
Only keys defined in the inputs/0
callback will be present in the input map, but defined inputs are not garaunteed to be present.
The chore callback has access to several Reporter
functions, used for live chore metrics and loggin.
These functions are:
log(message)
— Logs a string message with timestampset_counter(name, value)
— Sets a named counter, expects an atom for a name and a number for a valueinc_counter(name, inc_value)
— Increments a named counter. If the counter does not exist, it will default to 0, and then be incremented. Used negative values for decrements.report_failed(reason_message)
— Fails a chore, marking it as failed. The return value of therun/1
callback will be stored in the chore struct and forwarded to the final chore handling function.