statex v0.1.0 Statex.Example View Source
this example only is built in :dev
and :test
modes, and exists for two purposes: To
showcase the autogenerated documentation and to trigger dialyzer analysis on the
macro functions.
Code
defmodule Statex.Example do
use Statex
@graphdoc loop: "transitions the start state back around to itself"
@state_graph start: [loop: :start]
end
Link to this section Summary
Functions
Returns a specification to start this module under a supervisor
returns a new map from your Map
-backed state machine
consisting of attributes that aren't in the listed atoms
a utility function used inside of transition trigger functions to
escape out of the transition trigger routine and send a failure
transition instead. passing nil
instead of a transition atom will
result in no transition occurring
transitions the start state back around to itself
(optional) allows intercepting the attribute datastructure creation event
registers a finalizer on the state machine. This is a function
that takes a map and returns either :ok
, or :cancel
; if any
finalizer returns :cancel
, the stop event will be cancelled
(optional) allows intercepting the attribute datastructure modification events
dynamically sets a transition filter for this state machine
dynamically sets a transition trigger for this state machine
Starts a state machine linked to the current process with the given function
retrieves the current :state
attribute of the state machine
retrieves a list of all of the states in the state graph of Statex.Example
executes a stop on state machine. If called from within the current state machine, it will spawn task to take care of the termination. either way it will trigger all registered finalizers
returns a new map from your Map
-backed state machine consisting of
attributes from the listed atoms
retrieves a list of all of the terminal states in the state graph of Statex.Example
retrieves a list of all of the transitions in the state graph of Statex.Example
Link to this section Functions
child_spec(arg) View Source
Returns a specification to start this module under a supervisor.
See Supervisor
.
drop(sm, list)
View Source
drop(Agent.agent(), [atom()]) :: map()
drop(Agent.agent(), [atom()]) :: map()
returns a new map from your Map
-backed state machine
consisting of attributes that aren't in the listed atoms.
fail_transition(failure_transition) View Source
a utility function used inside of transition trigger functions to
escape out of the transition trigger routine and send a failure
transition instead. passing nil
instead of a transition atom will
result in no transition occurring.
get(sm, key)
View Source
get(Agent.agent(), atom()) :: any()
get(Agent.agent(), atom()) :: any()
gets an attribute from your Map
-backed state machine,
using the Map.get/2
function.
loop(sm)
View Source
loop(Agent.agent()) :: :ok | {:error, String.t()}
loop(Agent.agent()) :: :ok | {:error, String.t()}
transitions the start state back around to itself
(an autogenerated stategraph transition)
merge(sm, map)
View Source
merge(Agent.agent(), map()) :: Agent.agent()
merge(Agent.agent(), map()) :: Agent.agent()
merges a map into your Map
-backed state machine. Returns the
passed agent so that you can chain modules. The intent of this
function is to save you from having to make multiple put/3
calls,
which will take unnecessary and interruptable trips to the agent.
on_new(v) View Source
(optional) allows intercepting the attribute datastructure creation event.
NB this does not take the map
datatype, but rather takes the custom
datatype that is used by the backing engine. In particular, for struct
backing engines, this will be the datatype: {%STRUCT{}, map}
defaults to identity with no side effects.
Callback implementation for Statex.on_new/1
.
on_stop(sm, f)
View Source
on_stop(Agent.agent(), (map() -> :ok | :cancel)) :: Agent.agent()
on_stop(Agent.agent(), (map() -> :ok | :cancel)) :: Agent.agent()
registers a finalizer on the state machine. This is a function
that takes a map and returns either :ok
, or :cancel
; if any
finalizer returns :cancel
, the stop event will be cancelled.
on_update(v) View Source
(optional) allows intercepting the attribute datastructure modification events.
NB this does not take the map
datatype, but rather takes the custom
datatype that is used by the backing engine. In particular, for struct
backing engines, this will be the datatype: {%STRUCT{}, map}
defaults to identity with no side effects.
Callback implementation for Statex.on_update/1
.
put(sm, atom, value)
View Source
put(Agent.agent(), atom(), any()) :: Agent.agent()
put(Agent.agent(), atom(), any()) :: Agent.agent()
puts an attribute into your Map
-backed state machine,
using the Map.put/3
function. This function returns
the passed agent so that you can use it to chain operations.
NB: you can't use put/3
to set the :state
attribute.
set_transition_filter(sm, filter_fn)
View Source
set_transition_filter(Agent.agent(), Statex.filter()) ::
:ok | {:error, String.t()}
set_transition_filter(Agent.agent(), Statex.filter()) :: :ok | {:error, String.t()}
dynamically sets a transition filter for this state machine
transition filters match on the current attribs and the proposed transition, returning true if the transition should be rejected, and false if it should not. When being called, a filter function does not need to cover all match cases, a mismatch is ignored by the filter processing mechanism.
set_transition_trigger(sm_pid, trigger_fn)
View Source
set_transition_trigger(Agent.agent(), Statex.trigger()) ::
:ok | {:error, String.t()}
set_transition_trigger(Agent.agent(), Statex.trigger()) :: :ok | {:error, String.t()}
dynamically sets a transition trigger for this state machine
transition triggers match on the current attribs and the proposed transition,
returning any changes to be made to the attribs. In general, this change
should not include the :state
attribute. When being called a trigger
function does not need to cover all match cases, a mismatch is ignored by the
trigger processing mechanism.
start_link(options \\ []) View Source
Starts a state machine linked to the current process with the given function.
This is often used to start the agent as part of a supervision tree.
Options
The :initial_attribs
option (a map) lets you set the initial attributes
state(sm)
View Source
state(Agent.agent()) :: atom()
state(Agent.agent()) :: atom()
retrieves the current :state
attribute of the state machine.
states()
View Source
states() :: [atom()]
states() :: [atom()]
retrieves a list of all of the states in the state graph of Statex.Example
stop(sm)
View Source
stop(Agent.agent()) :: :ok | %{}
stop(Agent.agent()) :: :ok | %{}
executes a stop on state machine. If called from within the current state machine, it will spawn task to take care of the termination. either way it will trigger all registered finalizers
take(sm, list)
View Source
take(Agent.agent(), [atom()]) :: map()
take(Agent.agent(), [atom()]) :: map()
returns a new map from your Map
-backed state machine consisting of
attributes from the listed atoms.
terminal_states()
View Source
terminal_states() :: [atom()]
terminal_states() :: [atom()]
retrieves a list of all of the terminal states in the state graph of Statex.Example
transitions()
View Source
transitions() :: [atom()]
transitions() :: [atom()]
retrieves a list of all of the transitions in the state graph of Statex.Example