View Source RemotePersistentTerm behaviour (RemotePersistentTerm v0.1.1)

Fetch data from a remote source and store it in a persistent_term.

Can be configured to periodically check for updates.

use this module to define a GenServer that will manage the state of your fetcher and keep your term up to date.

Link to this section Summary

Callbacks

Deserializes the remote term, before storing it.

Retrieve the currently stored term.

Update the persistent_term.

Functions

Define a GenServer that will manage this specific persistent_term.

Link to this section Types

@type t() :: %RemotePersistentTerm{
  current_version: String.t(),
  fetcher_mod: module(),
  fetcher_state: term(),
  name: term(),
  refresh_interval: pos_integer()
}

Link to this section Callbacks

@callback deserialize(term()) :: {:ok, term()} | {:error, term()}

Deserializes the remote term, before storing it.

Overridable.

Commonly the remote term is an ETF encoded binary. In this case you will likely want to override this callback with something like:

  def deserialize(binary) do
    {:ok, :erlang.binary_to_term(binary)}
  rescue
    _ ->
      {:ok, "got invalid ETF"}
  end
@callback get() :: term() | nil

Retrieve the currently stored term.

Overridable.

@callback put(term()) :: :ok | {:error, term()}

Update the persistent_term.

Overridable.

This is called after deserialize/1.

Link to this section Functions

Link to this macro

__using__(opts)

View Source (macro)

Define a GenServer that will manage this specific persistent_term.

Example:

This will define a GenServer that should be placed in your supervision tree. The GenServer will check for a new version of s3://my-bucket/my-object every 12 hours and store it in a persistent_term.

Define the module:

  defmodule MyRemotePterm do
    use RemotePersistentTerm
  end

In your supervision tree:

  {MyRemotePterm,
   [
     fetcher_mod: RemotePersistentTerm.Fetcher.S3,
     fetcher_opts: [bucket: "my-bucket", key: "my-object"],
     refresh_interval: :timer.hours(12)
   ]}

Options:

  • :fetcher_mod - Required. The implementation of the RemotePersistentTerm.Fetcher behaviour which should be used. Either one of the built in modules or a custom module. The default value is RemotePersistentTerm.Fetcher.S3.

  • :fetcher_opts (keyword/0) - Configuration options for the chosen fetcher implementation. See your chosen implementation module for details." The default value is [].

  • :refresh_interval - How often the term should be updated in milliseconds. To disable automatic refresh, set the value to nil. Note: updating persistent_terms can be very expensive. See the docs for more info." The default value is nil.

  • :lazy_init? (boolean/0) - If true, the GenServer will start up immediately and the term will be populated in a handle_continue/2. This means that there will be a period while the remote term is being downloaded and no data is available. If this is not acceptable, set this value to false (the default). The default value is false.

  • :alias (atom/0) - An alias for this term. A value will be generated based on the module name if no value is provided. Used for Telemetry events.

Link to this function

update_term(state, deserialize_fun, put_fun)

View Source