external_state v1.0.5 ExternalState View Source

Support storing all or part of some state externally to the owning pid(s). Builds on ETS existing functionality.

Link to this section Summary

Functions

The using/1 macro introduces the external state data structure and the module functions used to interact with the external state.

Link to this section Functions

Link to this macro

__using__(kwl) View Source (macro)

The using/1 macro introduces the external state data structure and the module functions used to interact with the external state.

Parameters

  • kwl The keyword list describing the using module's external state. The following are supported:

    • {:persist, boolean} Set persist to true for the external state to be persisted after the pid that calls init_ex_state/1 exits. This is the default.
    • {:props, struct_def} Set the properties of the external state structure. The struct_def is a keyword list identical to what you would use to define any structure.

Functions and Properties

The following functions and properties are introduced to the module that uses ExternalState:

  • @ex_state_struct An atom name for your external state structure
  • default_ex_state/0 Get a state structure with default values from props
  • init_ex_state/0 Initialize your external state; must call once, multiple calls are okay
  • get_ex_state/0 Get the current external state or nil if no init yet
  • put_ex_state/1 Set the external state, returns the state or nil if no init yet
  • merge_ex_state/1 Update the external state with values from the parameter, which can be a keyword list of keys and values or a map.

Usage

defmodule MyGenserver do
  use ExternalState, persist: false, props: [foo: true]

  def init(:ok) do
    init_ex_state() # external state is now at the defaults specified in use
  end

  # ...

  def do_foo do
    # ... something that sets foo to true ...
    merge_ex_state(foo: true)
  end

  def undo_foo do
    # ... something that sets foo to false ...
    merge_ex_state(foo: false)
    # or: merge_ex_state(%{foo: false})
  end

  def foo? do
    get_ex_state().foo
  end

end