Ambient.Error exception (Ambient v0.1.0)

Copy Markdown View Source

The exception every Ambient misuse raises, carrying a machine-readable :reason alongside the human-readable message.

Match on :reason rather than on message text – the wording is not part of the contract:

try do
  Ambient.ProcessOverride.put(table, :k, :v)
rescue
  e in Ambient.Error ->
    case e.reason do
      :overrides_disabled -> :skip
      :server_not_started -> start_and_retry()
    end
end

Reasons

  • :overrides_disabled – the build didn't opt into the override machinery (config :ambient, enable_overrides: …). See Ambient.ProcessOverride.
  • :server_not_started – no Ambient.ProcessOverride.Server owns this table; call Ambient.start_servers/1 first.
  • {:not_shared_owner, pid} – the table is in shared mode and only pid may write to it.
  • :cant_allow_in_shared_mode – allow/3 is meaningless while a table is shared, since every process already reads the shared owner's values.
  • :not_a_value_module – something that is neither a module built with Ambient.Value nor a table atom was passed to Ambient.start_servers/1 and friends.
  • {:server_start_failed, reason} – the supervisor refused to start a table's server.

Summary

Types

reason()
t()

Types

reason()

@type reason() ::
  :overrides_disabled
  | :server_not_started
  | {:not_shared_owner, pid()}
  | :cant_allow_in_shared_mode
  | :not_a_value_module
  | {:server_start_failed, term()}

t()

@type t() :: %Ambient.Error{
  __exception__: term(),
  message: String.t(),
  reason: reason(),
  table: atom() | nil
}