View Source Reactive (Reactive State v0.2.3)

Module to manage reactive state by using GenServer processes ("reactive process" from here on) to manage each piece of state and its relationships to other reactive processes.

Installation

The package can be installed by adding reactive_state to your list of dependencies in mix.exs:

def deps do
  [
    {:reactive_state, "~> 0.2.3"}
  ]
end

Reactive Block

To automatically import the reactive/1 and reactive/2 macros, you can use use Reactive which is the equivalent of:

import Reactive, only: [reactive: 1, reactive: 2]
alias Reactive.Ref

Example usage:

iex> use Reactive
iex> ref = reactive(do: 2)
iex> ref_squared = reactive do
...>   get(ref) ** 2
...> end
iex> Reactive.get(ref_squared)
4
iex> Ref.set(ref, 3)
iex> Reactive.get(ref_squared)
9

To set options at the module level, you can pass options, for example:

iex> defmodule ReactiveExample do
...>   use Reactive, reactive: :reactive_protected, ref: :ref_protected, opts: [gc: false]
...>
...>   def run do
...>     value = ref_protected(0)
...>     computed = reactive_protected do
...>       get(value) + 1
...>     end
...>     {Ref.get(value), Ref.get(computed)}
...>   end
...> end
iex>
iex> ReactiveExample.run()
{0, 1}

Working with data directly with Reactive.Ref

iex> alias Reactive.Ref
iex> ref = Ref.new(0) #PID<0.204.0>
iex> Ref.get(ref) # or Ref.get(ref)
0
iex> Ref.set(ref, 1)
:ok
iex> Ref.get(ref)
1

Supervisor

By default, new reactive processes will be linked to the current process. To override this behavior, pass the supervisor keyword arg with the name of your DynamicSupervisor during process creation:

value = Ref.new(0, supervisor: MyApp.Supervisor)
computed = reactive supervisor: MyApp.Supervisor do
  get(value) + 1
end

You can also pass default options like this:

use Reactive, ref: :ref, opts: [supervisor: MyApp.Supervisor]
...
value = ref(0)
computed = reactive do
  get(value) + 1
end

Process Restarting

If a reactive process has been killed for any reason, it will be restarted upon a Reactive.get or Ref.get call:

iex> use Reactive
iex> Reactive.Supervisor.ensure_started()
iex> ref = Ref.new(0)
iex> DynamicSupervisor.terminate_child(Reactive.Supervisor, ref)
iex> Ref.get(ref)
0

Garbage Collection

The default garbage collection strategy is to kill any processes that were not accessed through a Reactive.get or Ref.get call between GC calls:

iex> use Reactive
iex> Reactive.Supervisor.ensure_started()
iex> ref = Ref.new(0)
iex> Reactive.Supervisor.gc()
iex> nil == Reactive.resolve_process(ref)

Reactive processes can be protected with the gc option:

iex> use Reactive
iex> Reactive.Supervisor.ensure_started()
iex> ref = Ref.new(0, gc: false)
iex> Reactive.Supervisor.gc()
iex> ^ref = Reactive.resolve_process(ref)

iex> use Reactive
iex> Reactive.Supervisor.ensure_started()
iex> ref = reactive gc: false do
...>    # some expensive computation
...> end
iex> Reactive.Supervisor.gc()
iex> ^ref = Reactive.resolve_process(ref)

Named Process

You can name a reactive process using the name option:

iex> use Reactive
iex> Reactive.Supervisor.ensure_started()
iex> Ref.new(0, name: MyApp.Value)
iex> reactive name: MyApp.Computed do
...>   get(MyApp.Value) + 1
...> end
iex> Ref.get(MyApp.Value)
0
iex> Reactive.get(MyApp.Computed)
1

Proactive Process

Proactive reactive processes will not trigger immediately after a dependency changes; they must triggered with a call to Reactive.Supervisor.trigger_proactive

iex> use Reactive
iex> Reactive.Supervisor.ensure_started()
iex> num = Ref.new(0)
iex> ref =
...>   reactive proactive: true do
...>     get(num) + 1
...>   end
iex> Reactive.get_cached(ref)
1
iex> Ref.set(num, 1)
iex> Reactive.Supervisor.trigger_proactive()
iex> Reactive.get_cached(ref)
2

Summary

Functions

Returns a specification to start this module under a supervisor.

Retrieve the state of a reactive process

Retrieve the cached state of a reactive process, or :stale if it has not been computed or is stale

Create a reactive process using a method

Syntatic sugar for creating reactive blocks

Create a reactive process with options

Find a reactive process from a pid or alias.

Replace a reactive process's computation method

Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Retrieve the state of a reactive process

Example

iex> ref = Reactive.new(fn _ -> 0 end)
iex> Reactive.get(ref)
0

Retrieve the cached state of a reactive process, or :stale if it has not been computed or is stale

Example

iex> use Reactive
iex> ref = reactive do
...>   0
...> end
iex> Reactive.get_cached(ref)
:stale
iex> Reactive.get(ref)
0
iex> Reactive.get_cached(ref)
0

Create a reactive process using a method

iex> use Reactive
iex> ref = Ref.new(2)
iex> ref_squared = Reactive.new(fn call_id ->
...>   Reactive.get(ref, call_id: call_id) ** 2
...> end)
iex> Reactive.get(ref_squared)
4
Link to this macro

reactive(opts)

View Source (macro)

Syntatic sugar for creating reactive blocks

iex> use Reactive
iex> ref = Ref.new(2)
iex> ref_squared = reactive do
...>   get(ref) ** 2
...> end #PID<0.204.0>
iex> Reactive.get(ref_squared)
4
iex> Ref.set(ref, 3)
iex> Reactive.get(ref_squared)
9

Using the reactive macro in this way is roughly equivalent to:

iex> use Reactive
iex> ref = Ref.new(2)
iex> ref_squared = Reactive.new(fn from ->
...>   Reactive.get(ref, from: from) ** 2
...> end)
iex> Reactive.get(ref_squared)
4
iex> Ref.set(ref, 3)
iex> Reactive.get(ref_squared)
9
Link to this macro

reactive(opts, list)

View Source (macro)

Create a reactive process with options:

reactive name: MyApp.SomeValue, gc: false, proactive: true, supervisor: MyApp.DynamicSupervisor do
  # ...
end
Link to this function

resolve_process(name, opts \\ [])

View Source

Find a reactive process from a pid or alias.

iex> use Reactive
iex> pid = Ref.new(0, name: MyApp.Value)
iex> true = Reactive.resolve_process(MyApp.Value) == Reactive.resolve_process(pid)

You can ensure a process will be returned by passing the create: true option

Reactive.resolve_process(pid, create: true)
Link to this function

set(pid, method, opts \\ [])

View Source

Replace a reactive process's computation method

iex> use Reactive
iex> Reactive.Supervisor.ensure_started()
iex> ref = reactive do
...>   0
...> end
iex> Reactive.get(ref)
0
iex> Reactive.set(ref, fn _ -> 1 end)
:ok
iex> Reactive.get(ref)
1