Skip to content

Commit

Permalink
Make #kpayload_*{} records private
Browse files Browse the repository at this point in the history
The public API is now:
* `khepri_payload:none/0`
* `khepri_payload:data/1`
* `khepri_payload:sproc/1`

That said, the caller should rarely have to use them: `khepri:put/1`
tries to automatically detect if and how to wrap the given value.
Therefore, one should be able to just use:

    khepri:put(StoreId, Path, #my_record{...}).

Or:

    khepri:put(StoreId, Path, fun() -> ... end).

Only the "no payload" case has no value beside the internal one. In this
case, the caller should use:

    khepri:put(StoreId, Path, khepri_payload:none()).

Or:

    khepri:clear_payload(StoreId, Path).

The end goal is to reduce the chance that if we change the payload
records, users are forced to recompile their code. It also makes the
code maintenance easier for us.

Note that in the process, the records are renamed `#p_*{}`.
  • Loading branch information
dumbbell committed Apr 20, 2022
1 parent 85efb18 commit fc932c2
Show file tree
Hide file tree
Showing 22 changed files with 500 additions and 490 deletions.
9 changes: 2 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,9 +143,7 @@ khepri:transaction(
%% There is less than 100 pieces of wood, or there is none
%% at all (the node does not exist in Khepri). We need to
%% request a new order.
{ok, _} = khepri_tx:put(
[order, wood],
#kpayload_data{data = 1000}),
{ok, _} = khepri_tx:put([order, wood], 1000),
true
end
end).
Expand Down Expand Up @@ -174,10 +172,7 @@ the database itself and automatically execute it after some event occurs.
on_action => Action} = Props
end,

khepri:put(
StoreId,
StoredProcPath,
#kpayload_sproc{sproc = Fun}))}.
khepri:put(StoreId, StoredProcPath, Fun).
```

2. Register a trigger using an event filter:
Expand Down
27 changes: 10 additions & 17 deletions doc/overview.edoc
Original file line number Diff line number Diff line change
Expand Up @@ -89,20 +89,15 @@ A tree node may or may not have a payload. Khepri supports two types of
payload, the <em>data payload</em> and the <em>stored procedure payload</em>.
More payload types may be added in the future.

Payloads are represented using macros or helper functions:
When passed to {@link khepri:put/2}, the type of the payload is autodetected.
However if you need to prepare the payload before passing it to Khepri, you can
use the following functions:
<ul>
<li>`?NO_PAYLOAD' and {@link khepri:no_payload/0}</li>
<li>`#kpayload_data{data = Term}' and {@link khepri:data_payload/1}</li>
<li>`#kpayload_sproc{sproc = Fun}' and {@link khepri:sproc_payload/1}</li>
<li>{@link khepri_payload:none/0}</li>
<li>{@link khepri_payload:data/1}</li>
<li>{@link khepri_payload:sproc/1}</li>
</ul>

Functions in {@link khepri_machine} have no assumption on the type of the
payload because they are a low-level API. Therefore, it must be specified
explicitly using the macros or helper functions mentionned above.

Most functions in {@link khepri}, being a higher-level API, target more
specific use cases and detect the type of payload.

=== Properties ===

Properties are:
Expand Down Expand Up @@ -343,8 +338,7 @@ PathPattern = [stock,
conditions = [
<<"lime tree">>,
#if_payload_version{version = PayloadVersion}]}],
Payload = #kpayload_data{data = Term1},
case khepri_machine:put(StoredId, PathPattern, Payload) of
case khepri:put(StoredId, PathPattern, Term1) of
{ok, _} ->
ok; %% `Term1` was stored successfully.
{error, {mismatching_node, _}} ->
Expand Down Expand Up @@ -375,14 +369,13 @@ The indicated stored procedure must have been stored in the tree first.

=== Storing an anonymous function ===

This is possible to store an anonymous function as the payload of a tree node
using the {@link khepri_machine:payload_sproc()} record:
This is possible to store an anonymous function as the payload of a tree node:

```
khepri_machine:put(
khepri:put(
StoreId,
StoredProcPath,
#kpayload_sproc{sproc = fun() -> do_something() end}))}.
fun() -> do_something() end).
'''

The `StoredProcPath' can be <a href="#Addressing_a_tree_node">any path in the
Expand Down
12 changes: 0 additions & 12 deletions include/khepri.hrl
Original file line number Diff line number Diff line change
Expand Up @@ -33,18 +33,6 @@
-define(IS_PATH_PATTERN(Path),
(Path =:= [] orelse ?IS_PATH_CONDITION(hd(Path)))).

%% -------------------------------------------------------------------
%% Payload types.
%% -------------------------------------------------------------------

-define(NO_PAYLOAD, '$__NO_PAYLOAD__').
-record(kpayload_data, {data :: khepri:data()}).
-record(kpayload_sproc, {sproc :: khepri_fun:standalone_fun()}).

-define(IS_KHEPRI_PAYLOAD(Payload), (Payload =:= ?NO_PAYLOAD orelse
is_record(Payload, kpayload_data) orelse
is_record(Payload, kpayload_sproc))).

%% -------------------------------------------------------------------
%% Path conditions.
%% -------------------------------------------------------------------
Expand Down
12 changes: 10 additions & 2 deletions src/internal.hrl
Original file line number Diff line number Diff line change
Expand Up @@ -16,16 +16,24 @@
-define(TX_STATE_KEY, khepri_tx_machine_state).
-define(TX_PROPS, khepri_tx_properties).

-define(NO_PAYLOAD, '$__NO_PAYLOAD__').
-record(p_data, {data :: khepri:data()}).
-record(p_sproc, {sproc :: khepri_fun:standalone_fun()}).

-define(IS_KHEPRI_PAYLOAD(Payload), (Payload =:= ?NO_PAYLOAD orelse
is_record(Payload, p_data) orelse
is_record(Payload, p_sproc))).

%% Structure representing each node in the tree, including the root node.
%% TODO: Rename stat to something more correct?
-record(node, {stat = ?INIT_NODE_STAT :: khepri_machine:stat(),
payload = ?NO_PAYLOAD :: khepri:payload(),
payload = ?NO_PAYLOAD :: khepri_payload:payload(),
child_nodes = #{} :: #{khepri_path:component() := #node{}}}).

%% State machine commands.

-record(put, {path :: khepri_path:pattern(),
payload = ?NO_PAYLOAD :: khepri:payload(),
payload = ?NO_PAYLOAD :: khepri_payload:payload(),
extra = #{} :: #{keep_while =>
khepri:keep_while_conds_map()}}).

Expand Down
Loading

0 comments on commit fc932c2

Please sign in to comment.