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 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 khepri_fun)
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.

Data Types

tx_abort()

tx_abort() = {aborted, any()}

tx_fun()

tx_fun() = fun(() -> tx_fun_result())

tx_fun_bindings()

tx_fun_bindings() = #{Name::atom() => Value::any()}

tx_fun_result()

tx_fun_result() = any() | no_return()

Function Index

put/2	Creates or modifies a specific tree node in the tree structure.
put/3	Creates or modifies a specific tree node in the tree structure.
create/2	Creates a specific tree node in the tree structure only if it does not exist.
create/3	Creates a specific tree node in the tree structure only if it does not exist.
update/2	Updates a specific tree node in the tree structure only if it already exists.
update/3	Updates a specific tree node in the tree structure only if it already exists.
compare_and_swap/3	Updates a specific tree node in the tree structure only if it already exists and its data matches the given `DataPattern`.
compare_and_swap/4	Updates a specific tree node in the tree structure only if it already exists and its data matches the given `DataPattern`.
clear_payload/1	Clears the payload of a specific tree node in the tree structure.
clear_payload/2	Clears the payload of a specific tree node in the tree structure.
delete/1	Deletes all tree nodes matching the path pattern.
exists/1	Returns `true` if the tree node pointed to by the given path exists, otherwise `false`.
exists/2	Returns `true` if the tree node pointed to by the given path exists, otherwise `false`.
get/1	Returns all tree nodes matching the path pattern.
get/2	Returns all tree nodes matching the path pattern.
get_node_props/1	Returns the tree node properties associated with the given node path.
get_node_props/2	Returns the tree node properties associated with the given node path.
has_data/1	Returns `true` if the tree node pointed to by the given path has data, otherwise `false`.
get_data/1	Returns the data associated with the given node path.
get_data/2	Returns the data associated with the given node path.
get_data_or/2	Returns the data associated with the given node path, or `Default` if there is no data.
get_data_or/3	Returns the data associated with the given node path, or `Default` if there is no data.
list/1	Returns all direct child nodes under the given path.
list/2	Returns all direct child nodes under the given path.
find/2	Returns all tree nodes matching the path pattern.
find/3	Finds tree nodes under `PathPattern` which match the given `Condition`.
abort/1	Aborts the transaction.
is_transaction/0	Indicates if the calling function runs in the context of a transaction function.

Function Details

put/2

put(PathPattern, Data) -> Result

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data()
Result = khepri:result()

Creates or modifies a specific tree node in the tree structure.

put/3

put(PathPattern, Data, Extra) -> Result

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data()
Extra = #{keep_while => khepri_condition:keep_while()}
Result = khepri:result()

Creates or modifies a specific tree node in the tree structure.

create/2

create(PathPattern, Data) -> Result

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data()
Result = khepri:result()

Creates a specific tree node in the tree structure only if it does not exist.

create/3

create(PathPattern, Data, Extra) -> Result

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data()
Extra = #{keep_while => khepri_condition:keep_while()}
Result = khepri:result()

Creates a specific tree node in the tree structure only if it does not exist.

update/2

update(PathPattern, Data) -> Result

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data()
Result = khepri:result()

Updates a specific tree node in the tree structure only if it already exists.

update/3

update(PathPattern, Data, Extra) -> Result

PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | khepri:data()
Extra = #{keep_while => khepri_condition:keep_while()}
Result = khepri:result()

Updates a specific tree node in the tree structure only if it already exists.

compare_and_swap/3

compare_and_swap(PathPattern, DataPattern, Data) -> Result

PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | khepri:data()
Result = khepri:result()

Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.

compare_and_swap/4

compare_and_swap(PathPattern, DataPattern, Data, Extra) -> Result

PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | khepri:data()
Extra = #{keep_while => khepri_condition:keep_while()}
Result = khepri:result()

Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.

clear_payload/1

clear_payload(PathPattern) -> Result

PathPattern = khepri_path:pattern()
Result = khepri:result()

Clears the payload of a specific tree node in the tree structure.

clear_payload/2

clear_payload(PathPattern, Extra) -> Result

PathPattern = khepri_path:pattern()
Extra = #{keep_while => khepri_condition:keep_while()}
Result = khepri:result()

Clears the payload of a specific tree node in the tree structure.

delete/1

delete(PathPattern) -> Result

PathPattern = khepri_path:pattern()
Result = khepri:result()

Deletes all tree nodes matching the path pattern.

exists/1

exists(PathPattern) -> Exists

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

Returns true if the tree node pointed to by the given path exists, otherwise false.

exists/2

exists(PathPattern, Options) -> Exists

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

Returns true if the tree node pointed to by the given path exists, otherwise false.

get/1

get(PathPattern) -> Result

PathPattern = khepri_path:pattern()
Result = khepri:result()

Returns all tree nodes matching the path pattern.

get/2

get(PathPattern, Options) -> Result

PathPattern = khepri_path:pattern()
Options = khepri:query_options()
Result = khepri:result()

Returns all tree nodes matching the path pattern.

get_node_props/1

get_node_props(PathPattern) -> NodeProps

PathPattern = khepri_path:pattern()
NodeProps = khepri:node_props()

Returns the tree node properties associated with the given node path.

get_node_props/2

get_node_props(PathPattern, Options) -> NodeProps

PathPattern = khepri_path:pattern()
Options = khepri:query_options()
NodeProps = khepri:node_props()

Returns the tree node properties associated with the given node path.

has_data/1

has_data(PathPattern) -> HasData

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

Returns true if the tree node pointed to by the given path has data, otherwise false.

get_data/1

get_data(PathPattern) -> Data

PathPattern = khepri_path:pattern()
Data = khepri:data()

Returns the data associated with the given node path.

get_data/2

get_data(PathPattern, Options) -> Data

PathPattern = khepri_path:pattern()
Options = khepri:query_options()
Data = khepri:data()

Returns the data associated with the given node path.

get_data_or/2

get_data_or(PathPattern, Default) -> Data

PathPattern = khepri_path:pattern()
Default = khepri:data()
Data = khepri:data()

Returns the data associated with the given node path, or Default if there is no data.

get_data_or/3

get_data_or(PathPattern, Default, Options) -> Data

PathPattern = khepri_path:pattern()
Default = khepri:data()
Options = khepri:query_options()
Data = khepri:data()

Returns the data associated with the given node path, or Default if there is no data.

list/1

list(PathPattern) -> Result

PathPattern = khepri_path:pattern()
Result = khepri:result()

Returns all direct child nodes under the given path.

list/2

list(PathPattern, Options) -> Result

PathPattern = khepri_path:pattern()
Options = khepri:query_options()
Result = khepri:result()

Returns all direct child nodes under the given path.

find/2

find(PathPattern, Condition) -> Result

PathPattern = khepri_path:pattern()
Condition = khepri_path:pattern_component()
Result = khepri:result()

Returns all tree nodes matching the path pattern.

find/3

find(PathPattern, Condition, Options) -> Result

PathPattern = khepri_path:pattern()
Condition = khepri_path:pattern_component()
Options = khepri:query_options()
Result = khepri:result()

Finds tree nodes under PathPattern which match the given Condition.

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 {atomic, Reason}.

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