Goblin.Tx (Goblin v0.10.0)

Copy Markdown View Source

Module for reading and writing within a transaction.

Used inside Goblin.transaction/2 (read-write) and Goblin.read/2 (read-only).

Goblin.transaction(db, fn tx ->
  counter = Goblin.Tx.get(tx, :counter, default: 0)

  tx
  |> Goblin.Tx.put(:counter, counter + 1)
  |> Goblin.Tx.commit()
end)

Goblin.read(db, fn tx ->
  Goblin.Tx.get(tx, :alice)
end)

Summary

Types

t()

Functions

abort(tx, reply \\ :error)

Pipeline-friendly helper function to abort the transaction.

commit(tx, reply \\ :ok)

Pipeline-friendly helper function to commit the transaction.

get(tx, key, opts \\ [])

Retrieves a value within a transaction.

get_multi(tx, keys, opts \\ [])

Retrieves values for multiple keys within a transaction.

put(tx, key, value, opts \\ [])

Writes a key-value pair within a transaction.

put_multi(tx, pairs, opts \\ [])

Writes multiple key-value pairs within a transaction.

remove(tx, key, opts \\ [])

Removes a key within a transaction.

remove_multi(tx, keys, opts \\ [])

Removes multiple keys within a transaction.

Types

t()

@type t() :: %Goblin.Tx{
  commits: [{term(), non_neg_integer(), term()}],
  max_level_key: -1 | non_neg_integer(),
  mode: :write | :read,
  mvcc: :ets.table(),
  sequence: non_neg_integer(),
  tx_id: non_neg_integer()
}

Functions

abort(tx, reply \\ :error)

@spec abort(t(), any()) :: :abort

Pipeline-friendly helper function to abort the transaction.

Parameters

  • tx - The transaction to abort
  • reply - The reply after aborting (default: :error)

Returns

  • The abort tuple, i.e. {:abort, reply}.

Examples

tx
|> Goblin.Tx.put(:alice, "Alice")
|> Goblin.Tx.abort()

commit(tx, reply \\ :ok)

@spec commit(t(), any()) :: {:commit, t(), any()}

Pipeline-friendly helper function to commit the transaction.

Parameters

  • tx - The transaction to commit
  • reply - The reply after committing (default: :ok)

Returns

  • The commit tuple, i.e. {:commit, tx, reply}.

Examples

tx
|> Goblin.Tx.put(:alice, "Alice")
|> Goblin.Tx.commit()

get(tx, key, opts \\ [])

@spec get(t(), term(), keyword()) :: term()

Retrieves a value within a transaction.

Parameters

  • tx - The transaction struct
  • key - The key to look up
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag the key is namespaced under
    • :default - Value to return if key is not found (default: nil)

Returns

  • The value associated with the key, or default if not found

Examples

Goblin.Tx.get(tx, :alice)
# => "Alice"

Goblin.Tx.get(tx, :nonexistent, default: :not_found)
# => :not_found

get_multi(tx, keys, opts \\ [])

@spec get_multi(t(), [term()], keyword()) :: [{term(), term()}]

Retrieves values for multiple keys within a transaction.

Keys not found are excluded from the result.

Parameters

  • tx - The transaction struct
  • keys - A list of keys to look up
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag the keys are namespaced under

Returns

  • A list of {key, value} tuples for keys found, in unspecified order

Examples

[{:alice, "Alice"}, {:bob, "Bob"}] = Goblin.Tx.get_multi(tx, [:alice, :bob])

put(tx, key, value, opts \\ [])

@spec put(t(), term(), term(), keyword()) :: t()

Writes a key-value pair within a transaction.

Parameters

  • tx - The transaction struct
  • key - Any Elixir term to use as the key
  • value - Any Elixir term to store
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag to namespace the key under

Returns

  • Updated transaction struct

Examples

tx = Goblin.Tx.put(tx, :alice, "Alice")

put_multi(tx, pairs, opts \\ [])

@spec put_multi(t(), [{term(), term()}], keyword()) :: t()

Writes multiple key-value pairs within a transaction.

Parameters

  • tx - The transaction struct
  • pairs - A list of {key, value} tuples
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag to namespace the keys under

Returns

  • Updated transaction struct

Examples

tx = Goblin.Tx.put_multi(tx, [{:alice, "Alice"}, {:bob, "Bob"}])

remove(tx, key, opts \\ [])

@spec remove(t(), term(), keyword()) :: t()

Removes a key within a transaction.

Parameters

  • tx - The transaction struct
  • key - The key to remove
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag the key is namespaced under

Returns

  • Updated transaction struct

Examples

tx = Goblin.Tx.remove(tx, :alice)

remove_multi(tx, keys, opts \\ [])

@spec remove_multi(t(), [term()], keyword()) :: t()

Removes multiple keys within a transaction.

Parameters

  • tx - The transaction struct
  • keys - A list of keys to remove
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag the keys are namespaced under

Returns

  • Updated transaction struct

Examples

tx = Goblin.Tx.remove_multi(tx, [:alice, :bob])