whitfin / global-lazy

Lazy global initialization for Elixir, without state

GlobalLazy

NOTE: This library is deprecated in favour of whitfin/global-flags. You should migrate when possible as this library will not receive updates - it only exists to avoid breaking existing applications.

This library is designed to provide an easy way to lazily initial global state in Elixir, without having to be linked to a main application tree.

This is useful for libraries which always require certain state, regardless of the state of the parent application. It's aimed at use cases where it's slow to have a separate process, and it's wasteful to start an ETS table.

This library is tiny, so you can include it with minimal overhead.

Installation

To install it for your project, you can pull it directly from Hex. Rather than use the version shown below, you can use the the latest version from Hex (shown at the top of this README).

def deps do
  [{:global_lazy, "~> 1.0"}]
end

Documentation and examples can be found on Hexdocs as they're updated automatically alongside each release.

Usage

As mentioned above, the API is extremely small, so there's really only one thing to learn how to use. Below is an example of lazily initializing an Agent, used to keep track of a global counter.

defmodule MyLibrary do

  @doc """
  Retrieves the next integer in the global counter.
  """
  def next_int do
    # initializes the Agent only the first time called
    GlobalLazy.init("my_library:started", fn ->
      Agent.start(fn -> 1 end, [ name: :my_library_agent ])
    end)

    # guaranteed to now have a started Agent
    Agent.get_and_update(:my_library_agent, fn count ->
      {count, count + 1}
    end)
  end
end

You should handle all errors inside the provided function; feel free to just crash if you'd prefer to retry initialization on the next call - the flag is only switched if the function returns successfully. You should also be careful to namespace your flags, because they're global (duh).