Module khepri_tx

Khepri API for transactional queries and updates.

Description

Khepri API for transactional queries and updates.

Transactions are anonymous functions which take no arguments, much like what Mnesia supports. However, unlike with Mnesia, transaction functions in Khepri are restricted:

The reason is that the transaction function must always have the exact same outcome given its inputs. Indeed, the transaction function is executed on every Ra cluster members participating in the consensus. The function must therefore modify the Khepri state (the database) identically on all Ra members. This is also true for Ra members joining the cluster later or catching up after a network partition.

To achieve that:
  1. The code of the transaction function is extracted from the its initial Erlang module. This way, the transaction function does not depend on the initial module availability and is not affected by a module reload. See Horus documentation
  2. The code is verified to make sure it does not perform any denied operations.
  3. The extracted transaction function is stored as a Khepri state machine command in the Ra journal to be replicated on all Ra members.
Functions in this module have simplified return values to cover most frequent use cases. If you need more details about the queried or modified tree nodes, like the ability to distinguish a non-existent tree node from a tree node with no payload, you can use the khepri_tx_adv module.

Data Types

tx_abort()

tx_abort() = khepri:error(any())

Return value after a transaction function aborted.

tx_fun()

tx_fun() = function()

Transaction function signature.

tx_fun_result()

tx_fun_result() = any() | no_return()

Return value of a transaction function.

Function Index

is_empty/0Indicates if the store is empty or not.
is_empty/1Indicates if the store is empty or not.
get/1Returns the payload of the tree node pointed to by the given path pattern.
get/2Returns the payload of the tree node pointed to by the given path pattern.
get_or/2Returns the payload of the tree node pointed to by the given path pattern, or a default value.
get_or/3Returns the payload of the tree node pointed to by the given path pattern, or a default value.
get_many/1Returns payloads of all the tree nodes matching the given path pattern.
get_many/2Returns payloads of all the tree nodes matching the given path pattern.
get_many_or/2Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
get_many_or/3Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
exists/1Indicates if the tree node pointed to by the given path exists or not.
exists/2Indicates if the tree node pointed to by the given path exists or not.
has_data/1Indicates if the tree node pointed to by the given path has data or not.
has_data/2Indicates if the tree node pointed to by the given path has data or not.
is_sproc/1Indicates if the tree node pointed to by the given path holds a stored procedure or not.
is_sproc/2Indicates if the tree node pointed to by the given path holds a stored procedure or not.
count/1Counts all tree nodes matching the given path pattern.
count/2Counts all tree nodes matching the given path pattern.
fold/3Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.
fold/4Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.
foreach/2Calls Fun for each tree node matching the given path pattern.
foreach/3Calls Fun for each tree node matching the given path pattern.
map/2Produces a new map by calling Fun for each tree node matching the given path pattern.
map/3Produces a new map by calling Fun for each tree node matching the given path pattern.
filter/2Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.
filter/3Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.
put/2Sets the payload of the tree node pointed to by the given path pattern.
put/3Sets the payload of the tree node pointed to by the given path pattern.
put_many/2Sets the payload of all the tree nodes matching the given path pattern.
put_many/3Sets the payload of all the tree nodes matching the given path pattern.
create/2Creates a tree node with the given payload.
create/3Creates a tree node with the given payload.
update/2Updates an existing tree node with the given payload.
update/3Updates an existing tree node with the given payload.
compare_and_swap/3Updates an existing tree node with the given payload only if its data matches the given pattern.
compare_and_swap/4Updates an existing tree node with the given payload only if its data matches the given pattern.
delete/1Deletes the tree node pointed to by the given path pattern.
delete/2Deletes the tree node pointed to by the given path pattern.
delete_many/1Deletes all tree nodes matching the given path pattern.
delete_many/2Deletes all tree nodes matching the given path pattern.
clear_payload/1Deletes the payload of the tree node pointed to by the given path pattern.
clear_payload/2Deletes the payload of the tree node pointed to by the given path pattern.
clear_many_payloads/1Deletes the payload of all tree nodes matching the given path pattern.
clear_many_payloads/2Deletes the payload of all tree nodes matching the given path pattern.
abort/1Aborts the transaction.
is_transaction/0Indicates if the calling function runs in the context of a transaction function.

Function Details

is_empty/0

is_empty() -> IsEmpty | Error

Indicates if the store is empty or not.

This is the same as khepri:is_empty/1 but inside the context of a transaction function.

See also: is_empty/1, khepri:is_empty/2.

is_empty/1

is_empty(Options) -> IsEmpty | Error

Indicates if the store is empty or not.

This is the same as khepri:is_empty/2 but inside the context of a transaction function.

See also: khepri:is_empty/2.

get/1

get(PathPattern) -> Ret

Returns the payload of the tree node pointed to by the given path pattern.

This is the same as khepri:get/2 but inside the context of a transaction function.

See also: khepri:get/2.

get/2

get(PathPattern, Options) -> Ret

Returns the payload of the tree node pointed to by the given path pattern.

This is the same as khepri:get/3 but inside the context of a transaction function.

See also: khepri:get/3.

get_or/2

get_or(PathPattern, Default) -> Ret

Returns the payload of the tree node pointed to by the given path pattern, or a default value.

This is the same as khepri:get_or/3 but inside the context of a transaction function.

See also: khepri:get_or/3.

get_or/3

get_or(PathPattern, Default, Options) -> Ret

Returns the payload of the tree node pointed to by the given path pattern, or a default value.

This is the same as khepri:get_or/4 but inside the context of a transaction function.

See also: khepri:get_or/4.

get_many/1

get_many(PathPattern) -> Ret

Returns payloads of all the tree nodes matching the given path pattern.

This is the same as khepri:get_many/2 but inside the context of a transaction function.

See also: khepri:get_many/2.

get_many/2

get_many(PathPattern, Options) -> Ret

Returns payloads of all the tree nodes matching the given path pattern.

This is the same as khepri:get_many/3 but inside the context of a transaction function.

See also: khepri:get_many/3.

get_many_or/2

get_many_or(PathPattern, Default) -> Ret

Returns payloads of all the tree nodes matching the given path pattern, or a default payload.

This is the same as khepri:get_many_or/3 but inside the context of a transaction function.

See also: khepri:get_many_or/3.

get_many_or/3

get_many_or(PathPattern, Default, Options) -> Ret

Returns payloads of all the tree nodes matching the given path pattern, or a default payload.

This is the same as khepri:get_many_or/4 but inside the context of a transaction function.

See also: khepri:get_many_or/4.

exists/1

exists(PathPattern) -> Exists

Indicates if the tree node pointed to by the given path exists or not.

This is the same as khepri:exists/2 but inside the context of a transaction function.

See also: khepri:exists/2.

exists/2

exists(PathPattern, Options) -> Exists

Indicates if the tree node pointed to by the given path exists or not.

This is the same as khepri:exists/3 but inside the context of a transaction function.

See also: khepri:exists/3.

has_data/1

has_data(PathPattern) -> HasData | Error

Indicates if the tree node pointed to by the given path has data or not.

This is the same as khepri:has_data/2 but inside the context of a transaction function.

See also: khepri:has_data/2.

has_data/2

has_data(PathPattern, Options) -> HasData | Error

Indicates if the tree node pointed to by the given path has data or not.

This is the same as khepri:has_data/3 but inside the context of a transaction function.

See also: khepri:has_data/3.

is_sproc/1

is_sproc(PathPattern) -> IsSproc | Error

Indicates if the tree node pointed to by the given path holds a stored procedure or not.

This is the same as khepri:is_sproc/2 but inside the context of a transaction function.

See also: khepri:is_sproc/2.

is_sproc/2

is_sproc(PathPattern, Options) -> IsSproc | Error

Indicates if the tree node pointed to by the given path holds a stored procedure or not.

This is the same as khepri:is_sproc/3 but inside the context of a transaction function.

See also: khepri:is_sproc/3.

count/1

count(PathPattern) -> Ret

Counts all tree nodes matching the given path pattern.

This is the same as khepri:count/2 but inside the context of a transaction function.

See also: khepri:count/2.

count/2

count(PathPattern, Options) -> Ret

Counts all tree nodes matching the given path pattern.

This is the same as khepri:count/3 but inside the context of a transaction function.

See also: khepri:count/3.

fold/3

fold(PathPattern, Fun, Acc) -> Ret

Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.

This is the same as khepri:fold/4 but inside the context of a transaction function.

See also: khepri:fold/4.

fold/4

fold(PathPattern, Fun, Acc, Options) -> Ret

Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.

This is the same as khepri:fold/5 but inside the context of a transaction function.

See also: khepri:fold/5.

foreach/2

foreach(PathPattern, Fun) -> Ret

Calls Fun for each tree node matching the given path pattern.

This is the same as khepri:foreach/3 but inside the context of a transaction function.

See also: khepri:foreach/3.

foreach/3

foreach(PathPattern, Fun, Options) -> Ret

Calls Fun for each tree node matching the given path pattern.

This is the same as khepri:foreach/4 but inside the context of a transaction function.

See also: khepri:foreach/4.

map/2

map(PathPattern, Fun) -> Ret

Produces a new map by calling Fun for each tree node matching the given path pattern.

This is the same as khepri:map/3 but inside the context of a transaction function.

See also: khepri:map/3.

map/3

map(PathPattern, Fun, Options) -> Ret

Produces a new map by calling Fun for each tree node matching the given path pattern.

This is the same as khepri:map/4 but inside the context of a transaction function.

See also: khepri:map/4.

filter/2

filter(PathPattern, Pred) -> Ret

Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.

This is the same as khepri:filter/3 but inside the context of a transaction function.

See also: khepri:filter/3.

filter/3

filter(PathPattern, Pred, Options) -> Ret

Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.

This is the same as khepri:filter/4 but inside the context of a transaction function.

See also: khepri:filter/4.

put/2

put(PathPattern, Data) -> Ret

Sets the payload of the tree node pointed to by the given path pattern.

This is the same as khepri:put/3 but inside the context of a transaction function.

See also: khepri:put/3.

put/3

put(PathPattern, Data, Options) -> Ret

Sets the payload of the tree node pointed to by the given path pattern.

This is the same as khepri:put/4 but inside the context of a transaction function.

See also: khepri:put/4.

put_many/2

put_many(PathPattern, Data) -> Ret

Sets the payload of all the tree nodes matching the given path pattern.

This is the same as khepri:put_many/3 but inside the context of a transaction function.

See also: khepri:put_many/3.

put_many/3

put_many(PathPattern, Data, Options) -> Ret

Sets the payload of all the tree nodes matching the given path pattern.

This is the same as khepri:put_many/4 but inside the context of a transaction function.

See also: khepri:put_many/4.

create/2

create(PathPattern, Data) -> Ret

Creates a tree node with the given payload.

This is the same as khepri:create/3 but inside the context of a transaction function.

See also: khepri:create/3.

create/3

create(PathPattern, Data, Options) -> Ret

Creates a tree node with the given payload.

This is the same as khepri:create/4 but inside the context of a transaction function.

See also: khepri:create/4.

update/2

update(PathPattern, Data) -> Ret

Updates an existing tree node with the given payload.

This is the same as khepri:update/3 but inside the context of a transaction function.

See also: khepri:update/3.

update/3

update(PathPattern, Data, Options) -> Ret

Updates an existing tree node with the given payload.

This is the same as khepri:update/4 but inside the context of a transaction function.

See also: khepri:update/4.

compare_and_swap/3

compare_and_swap(PathPattern, DataPattern, Data) -> Ret

Updates an existing tree node with the given payload only if its data matches the given pattern.

This is the same as khepri:compare_and_swap/4 but inside the context of a transaction function.

See also: khepri:compare_and_swap/4.

compare_and_swap/4

compare_and_swap(PathPattern, DataPattern, Data, Options) -> Ret

Updates an existing tree node with the given payload only if its data matches the given pattern.

This is the same as khepri:compare_and_swap/5 but inside the context of a transaction function.

See also: khepri:compare_and_swap/5.

delete/1

delete(PathPattern) -> Ret

Deletes the tree node pointed to by the given path pattern.

This is the same as khepri:delete/2 but inside the context of a transaction function.

See also: khepri:delete/2.

delete/2

delete(PathPattern, Options) -> Ret

Deletes the tree node pointed to by the given path pattern.

This is the same as khepri:delete/3 but inside the context of a transaction function.

See also: khepri:delete/3.

delete_many/1

delete_many(PathPattern) -> Ret

Deletes all tree nodes matching the given path pattern.

This is the same as khepri:delete_many/2 but inside the context of a transaction function.

See also: khepri:delete_many/2.

delete_many/2

delete_many(PathPattern, Options) -> Ret

Deletes all tree nodes matching the given path pattern.

This is the same as khepri:delete_many/3 but inside the context of a transaction function.

See also: khepri:delete_many/3.

clear_payload/1

clear_payload(PathPattern) -> Ret

Deletes the payload of the tree node pointed to by the given path pattern.

This is the same as khepri:clear_payload/2 but inside the context of a transaction function.

See also: khepri:clear_payload/2.

clear_payload/2

clear_payload(PathPattern, Options) -> Ret

Deletes the payload of the tree node pointed to by the given path pattern.

This is the same as khepri:clear_payload/3 but inside the context of a transaction function.

See also: khepri:clear_payload/3.

clear_many_payloads/1

clear_many_payloads(PathPattern) -> Ret

Deletes the payload of all tree nodes matching the given path pattern.

This is the same as khepri:clear_many_payloads/2 but inside the context of a transaction function.

See also: khepri:clear_many_payloads/2.

clear_many_payloads/2

clear_many_payloads(PathPattern, Options) -> Ret

Deletes the payload of all tree nodes matching the given path pattern.

This is the same as khepri:clear_many_payloads/3 but inside the context of a transaction function.

See also: khepri:clear_many_payloads/3.

abort/1

abort(Reason) -> no_return()

Reason: term to return to caller of the transaction.

Aborts the transaction.

Any changes so far are not committed to the store.

khepri:transaction/1 and friends will return tx_abort().

is_transaction/0

is_transaction() -> boolean()

returns: true if the calling code runs inside a transaction function, false otherwise.

Indicates if the calling function runs in the context of a transaction function.


Generated by EDoc