Module khepri_tx

Description
Data Types
Function Index
Function Details

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:

Calls to BIFs and other functions is limited to a set of whitelisted APIs. See khepri_tx_adv:is_remote_call_valid/3 for the complete list.
Sending or receiving messages is denied.

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:

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
The code is verified to make sure it does not perform any denied operations.
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.

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

Function Details

is_empty/0

is_empty() -> IsEmpty | Error

IsEmpty = boolean()
Error = khepri: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

Options = khepri:tree_options()
IsEmpty = boolean()
Error = khepri: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

PathPattern = khepri_path:pattern()
Ret = khepri:payload_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

PathPattern = khepri_path:pattern()
Default = khepri:data()
Ret = khepri:payload_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

PathPattern = khepri_path:pattern()
Default = khepri:data()
Options = khepri:tree_options()
Ret = khepri:payload_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

PathPattern = khepri_path:pattern()
Ret = khepri:many_payloads_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

PathPattern = khepri_path:pattern()
Exists = boolean()

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

PathPattern = khepri_path:pattern()
Options = khepri:tree_options()
Exists = boolean()

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

PathPattern = khepri_path:pattern()
HasData = boolean()
Error = khepri: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

PathPattern = khepri_path:pattern()
Options = khepri:tree_options()
HasData = boolean()
Error = khepri: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

PathPattern = khepri_path:pattern()
IsSproc = boolean()
Error = khepri: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

PathPattern = khepri_path:pattern()
Options = khepri:tree_options()
IsSproc = boolean()
Error = khepri: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

PathPattern = khepri_path:pattern()
Ret = khepri:ok(Count) | khepri:error()
Count = non_neg_integer()

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

PathPattern = khepri_path:pattern()
Options = khepri:tree_options()
Ret = khepri:ok(Count) | khepri:error()
Count = non_neg_integer()

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

PathPattern = khepri_path:pattern()
Fun = khepri:fold_fun()
Acc = khepri:fold_acc()
Ret = khepri:ok(NewAcc) | khepri:error()
NewAcc = Acc

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

PathPattern = khepri_path:pattern()
Fun = khepri:fold_fun()
Acc = khepri:fold_acc()
Options = khepri:tree_options()
Ret = khepri:ok(NewAcc) | khepri:error()
NewAcc = Acc

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

PathPattern = khepri_path:pattern()
Fun = khepri:foreach_fun()
Ret = ok | khepri:error()

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

PathPattern = khepri_path:pattern()
Fun = khepri:foreach_fun()
Options = khepri:tree_options()
Ret = ok | khepri:error()

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

PathPattern = khepri_path:pattern()
Fun = khepri:map_fun()
Ret = khepri:ok(Map) | khepri:error()
Map = #{khepri_path:native_path() => khepri:map_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

PathPattern = khepri_path:pattern()
Fun = khepri:map_fun()
Options = khepri:tree_options()
Ret = khepri:ok(Map) | khepri:error()
Map = #{khepri_path:native_path() => khepri:map_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/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

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data() | function()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data() | function()
Options = khepri:tree_options() | khepri:put_options()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data() | function()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data() | function()
Options = khepri:tree_options() | khepri:put_options()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data() | function()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data() | function()
Options = khepri:tree_options() | khepri:put_options()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data() | function()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data() | function()
Options = khepri:tree_options() | khepri:put_options()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | khepri:data() | function()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | khepri:data() | function()
Options = khepri:tree_options() | khepri:put_options()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Options = khepri:tree_options() | khepri:put_options()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Ret = khepri:minimal_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

PathPattern = khepri_path:pattern()
Options = khepri:tree_options() | khepri:put_options()
Ret = khepri:minimal_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 = any()

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