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.4"}
  ]
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