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

gets an attribute from your Map-backed state machine, using the Map.get/2 function

transitions the start state back around to itself

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

(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

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

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

Returns a specification to start this module under a supervisor.

See Supervisor.

returns a new map from your Map-backed state machine consisting of attributes that aren't in the listed atoms.

Link to this function

fail_transition(failure_transition) View Source
fail_transition(atom()) :: no_return()

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.

gets an attribute from your Map-backed state machine, using the Map.get/2 function.

Link to this function

loop(sm) View Source
loop(Agent.agent()) :: :ok | {:error, String.t()}

transitions the start state back around to itself

(an autogenerated stategraph transition)

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.

(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.

Link to this function

on_stop(sm, f) View Source
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.

Link to this function

on_update(v) View Source
on_update(any()) :: any()

(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.

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.

Link to this function

set_transition_filter(sm, filter_fn) View Source
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.

Link to this function

set_transition_trigger(sm_pid, trigger_fn) View Source
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.

Link to this function

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

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.

Link to this function

terminal_states() View Source
terminal_states() :: [atom()]

retrieves a list of all of the terminal states in the state graph of Statex.Example

Link to this function

transitions() View Source
transitions() :: [atom()]

retrieves a list of all of the transitions in the state graph of Statex.Example