-spec add(database() | transaction() | snapshot(), key(), atomic_operand()) -> ok.

Performs an atomic add on the value in the database.

C API function: fdb_transaction_atomic_op

See FDBMutationType.FDB_MUTATION_TYPE_ADD.

-spec add_conflict_range(transaction() | snapshot(), key(), key(), read | write) -> ok.

Adds a conflict to the transaction without actually performing the associated action.

This is not needed in simple cases.

C API function: fdb_transaction_add_conflict_range

-spec add_read_conflict_key(transaction() | snapshot(), key()) -> ok.

Adds a read conflict to the transaction without actually reading the key.

This is not needed in simple cases.

C API function: fdb_transaction_add_conflict_range

-spec add_read_conflict_range(transaction() | snapshot(), key(), key()) -> ok.

Adds a read conflict to the transaction without actually reading the range.

This is not needed in simple cases.

C API function: fdb_transaction_add_conflict_range

-spec add_write_conflict_key(transaction() | snapshot(), key()) -> ok.

Adds a write conflict to the transaction without actually writing to the key.

This is not needed in simple cases.

C API function: fdb_transaction_add_conflict_range

-spec add_write_conflict_range(transaction() | snapshot(), key(), key()) -> ok.

Adds a write conflict to the transaction without actually writing to the range.

This is not needed in simple cases.

C API function: fdb_transaction_add_conflict_range

-spec atomic_op(database() | transaction() | snapshot(), key(), atomic_operand(), atomic_mode()) -> ok.

Performs one of the available atomic operations.

C API function: fdb_transaction_atomic_op

-spec bit_and(database() | transaction() | snapshot(), key(), atomic_operand()) -> ok.

Performs an atomic bitwise 'and' on the value in the database.

C API function: fdb_transaction_atomic_op

See FDBMutationType.FDB_MUTATION_TYPE_AND.

-spec bit_or(database() | transaction() | snapshot(), key(), atomic_operand()) -> ok.

Performs an atomic bitwise 'or' on the value in the database.

C API function: fdb_transaction_atomic_op

See FDBMutationType.FDB_MUTATION_TYPE_OR.

-spec bit_xor(database() | transaction() | snapshot(), key(), atomic_operand()) -> ok.

Performs an atomic bitwise 'xor' on the value in the database.

C API function: fdb_transaction_atomic_op

See FDBMutationType.FDB_MUTATION_TYPE_XOR.

-spec block_until_ready(future()) -> ok.

Blocks the calling process until the future is ready.

C API function: fdb_future_block_until_ready

Tip

Use one of the wait* functions instead, such as wait/1.

-spec byte_max(database() | transaction() | snapshot(), key(), atomic_operand()) -> ok.

Performs an atomic lexocogrpahic maximum on the value in the database.

C API function: fdb_transaction_atomic_op

See FDBMutationType.FDB_MUTATION_TYPE_BYTE_MAX.

-spec byte_min(database() | transaction() | snapshot(), key(), atomic_operand()) -> ok.

Performs an atomic lexocogrpahic minimum on the value in the database.

C API function: fdb_transaction_atomic_op

See FDBMutationType.FDB_MUTATION_TYPE_BYTE_MIN.

-spec cancel(fold_future() | future() | transaction()) -> ok.

Cancels a future or a transaction.

C API functions:

• For a transaction/0, fdb_transaction_cancel
• For a future/0 or fold_future/0, fdb_future_cancel

-spec cancel(fold_future() | future(), [{flush, boolean()}] | []) -> ok.

Cancels a future.

If [{flush, true}] is provided, the calling process's mailbox is cleared of any messages from this future. Defaults to false.

C API functions:

• For a transaction/0, fdb_transaction_cancel
• For a future/0 or fold_future/0, fdb_future_cancel

-spec clear(database() | transaction() | snapshot(), key()) -> ok.

Clears a key in the database.

C API function: fdb_transaction_clear

Examples

In a transaction with a single operation:

1> Db = erlfdb:open().
2> erlfdb:clear(Db, <<"hello">>).copy

In a transaction with many operations:

1> Db = erlfdb:open().
2> erlfdb:transactional(Db, fun(Tx) ->
..     erlfdb:clear(Tx, <<"hello">>),
..     erlfdb:clear(Tx, <<"foo">>)
.. end).copy

-spec clear_and_watch(database(), key()) -> future().

Does both a clear/2 and watch/2 in a transaction.

-spec clear_range(database() | transaction() | snapshot(), key(), key()) -> ok.

Clears a range of keys in the database.

Reminder: FoundationDB keys are ordered such that a single operation can work on many keys, as long as they are in a contiguous range.

C API function: fdb_transaction_clear_range

Examples

Clears all keys with prefix <<"user/0">> In a transaction with a single operation:

1> Db = erlfdb:open().
2> erlfdb:clear_range(Db, <<"user/0">>, <<"user/1">>).copy

(!!) Clears all keys in the entire database (!!):

1> Db = erlfdb:open().
2> erlfdb:clear_range(Db, <<>>, <<16#FF>>).copy

-spec clear_range_startswith(database() | transaction() | snapshot(), key()) -> ok.

Equivalent to clear_range(DbOrTx, Prefix, erlfdb_key:strinc(Prefix)).

C API function: fdb_transaction_clear_range

-spec commit(transaction()) -> future().

Commits a transaction.

C API function: fdb_transaction_commit

Tip

Use transactional/2 instead.

-spec create_transaction(database()) -> transaction().

Creates a transaction from a database.

The caller is responsible for calling commit/1 when appropriate and implementing any retry behavior.

C API function: fdb_database_create_transaction

Tip

Use transactional/2 instead.

-spec error_predicate(error_predicate(), error() | integer()) -> boolean().

Evaluates a predicate against an error code.

C API function: fdb_error_predicate

-spec fold_mapped_range_future(transaction(), key(), key(), mapper()) -> any().

Deprecated. Equivalent to fold_mapped_range_future(Tx, StartKey, EndKey, Mapper, []).

-spec fold_range(database() | transaction(), key(), key(), function(), any()) -> any().

Equivalent to fold_range(DbOrTex, StartKey, EndKey, Fun, []).

-spec fold_range(database() | transaction(), key(), key(), function(), any(), [fold_option()]) -> any().

Gets a range of key-value pairs. Executes a reducing function as the pairs are retrieved.

Tip

Use get_range/5 with wait_for_all_interleaving/2 instead.

-spec fold_range_future(transaction() | snapshot(), key(), key(), [fold_option()]) -> fold_future().

Deprecated. Gets a fold_future/0 from a key range.

Tip

Use get_range/5 with option [{wait, false}] instead.

-spec fold_range_wait(transaction() | snapshot(), fold_future(), function(), any()) -> any().

Deprecated. Equivalent to fold_range_wait(Tx, FF, Fun, Acc, []).

-spec fold_range_wait(transaction() | snapshot(), fold_future(), function(), any(), [wait_option()]) ->
                         any().

Retrieves results from a fold_future/0. Executes a reducing function as the pairs are retrieved.

Tip

Use wait_for_all_interleaving/2 instead.

-spec get(future()) -> result().

Returns the result of a ready future.

C API functions: fdb_future_get_*

Tip

Use one of the wait* functions instead, such as wait/1.

-spec get(database() | transaction() | snapshot(), key()) -> future() | result().

Gets a value from the database.

When used inside a transactional/2, the return is a future/0.

C API function: fdb_transaction_get

Examples

Using a database/0 as input, the value is retrieved:

1> Db = erlfdb:open().
3> <<"world">> = erlfdb:get(Db, <<"hello">>).copy

Using a transaction/0 as input, you must wait on the future/0:

1> Db = erlfdb:open().
2> erlfdb:transactional(Db, fun(Tx) ->
..     Future = erlfdb:get(Tx, <<"hello">>),
..     <<"world">> = erlfdb:wait(Future)
.. end).copy

-spec get_addresses_for_key(database() | transaction() | snapshot(), key()) -> future() | result().

Returns a list of public network addresses as strings, one for each of the storage servers responsible for storing key_name and its associated value.

C API function: fdb_transaction_get_addresses_for_key

-spec get_and_watch(database(), key()) -> {result(), future()}.

Does both a get/2 and watch/2 in a transaction.

-spec get_approximate_size(transaction() | snapshot()) -> non_neg_integer().

Gets the approximate transaction size so far.

C API function: fdb_transaction_get_approximate_size

-spec get_committed_version(transaction() | snapshot()) -> version().

Retrieves the database version number at which a given transaction was committed.

This is not needed in simple cases. Not compatible with transactional/2.

C API function: fdb_transaction_get_committed_version

-spec get_conflicting_keys(transaction()) -> any().

Gets any conflicting keys on this transaction.

-spec get_error(future()) -> ok | error().

Returns ok if future is ready and not in an error state, and an error/0 otherwise.

C API function: fdb_future_get_error

Tip

Use one of the wait* functions instead, such as wait/1.

-spec get_error_string(integer()) -> binary().

Returns a (somewhat) human-readable English message from an error code.

C API function: fdb_get_error

-spec get_estimated_range_size(transaction() | snapshot(), key(), key()) -> future().

Returns an estimated byte size of the key range.

C API function: fdb_transaction_get_estimated_range_size_bytes

-spec get_key(database() | transaction() | snapshot(), key_selector()) -> future() | key().

Resolves a key_selector/0 against the keys in the database.

C API function: fdb_transaction_get_key

-spec get_key_ss(transaction(), key_selector()) -> future() | key().

With snapshot isolation, resolves a key_selector/0 against the keys in the database.

C API function: fdb_transaction_get_key

-spec get_last_error() -> error() | undefined.

Gets the last error stored by erlfdb in the process dictionary.

-spec get_mapped_range(database() | transaction(), key(), key(), mapper()) -> [mapped_kv()].

Equivalent to get_mapped_range(Tx, StartKey, EndKey, []).

This function never returns a fold_future/0. Use [{wait, false}] with get_mapped_range/5 if you want future semantics.

-spec get_mapped_range(database() | transaction(), key(), key(), mapper(), [fold_option()]) ->
                          fold_future() | [mapped_kv()].

Experimental. A two-stage GetRange operation that uses the first retrieved list of key-value pairs to do a secondary lookup.

To use this function, any keys or values defined by the mapper MUST be encoded with the FoundationDB Tuple layer. Use erlfdb_tuple for this.

The mapper/0 is an Erlang tuple that describes the Mapper specification as detailed by Everything about GetMappedRange.

C API function: fdb_transaction_get_range

Motivation

GetMappedRange was created to support a common pattern when implementing indexed lookups. It can allow your Layer to follow a single level of indirection: reading one key and then "hopping" over to read the key pointed to by that key. Instead of doing so with 2 separate waits in your transaction, GetMappedRange sends the small mapping operation to the FoundationDB server so that it may do it for us. In doing so, we effectively perform 2 chained gets with a single network round trip between client and server.

Data Modeling with Indirection

Examples

Here is a minimal example. First we set up the following key-value pairs in the database:

(a, {b})
({b}, c)copy

Let's create our kvs:

1> Db = erlfdb:open().
2> erlfdb:transactional(Db, fun(Tx) ->
..    erlfdb:set(Tx, <<"a">>, erlfdb_tuple:pack({<<"b">>})),
..    erlfdb:set(Tx, erlfdb_tuple:pack({<<"b">>}), <<"c">>)
.. end).copy

Now, we can retrieve the <<"c">> value in a single shot:

3> Result = erlfdb:transactional(Tenant, fun(Tx) ->
..     erlfdb:get_mapped_range(
..         Tx,
..         <<"a">>,
..         erlfdb_key:strinc(<<"a">>),
..         {<<"{V[0]}">>, <<"{...}">>},
..         []
..     )
.. end).copy

The Result includes both of our setup key-value pairs using only a single network round-trip to the FoundationDB server.

-spec get_next_tx_id(transaction() | snapshot()) -> non_neg_integer().

Gets a local auto-incrementing integer for this transaction.

Each time this function is executed, a local counter on the transaction is incremented, and the value returned.

This integer is useful in combination with versionstamps to ensure uniqueness of versionstamped keys and values for your transaction.

Examples

1> erlfdb:transactional(Db, fun(Tx) ->
..
..   Key1 = erlfdb_tuple:pack_vs({<<"sample">>,
..          {versionstamp, 16#ffffffffffffffff, 16#ffff, erlfdb:get_next_tx_id(Tx)}}),
..   erlfdb:set_versionstamped_key(Key1, <<"hello">>),
..
..   Key2 = erlfdb_tuple:pack_vs({<<"sample">>,
..          {versionstamp, 16#ffffffffffffffff, 16#ffff, erlfdb:get_next_tx_id(Tx)}}),
..   erlfdb:set_versionstamped_key(Key2, <<"world">>)
..
.. end)copy

Without get_next_tx_id, the versionstamped keys generated at commit time would collide, because exactly one versionstamp is created at commit time.

-spec get_range(database() | transaction(), key(), key()) -> [kv()].

Gets a range of key-value pairs from the database.

This function never returns a fold_future/0. Use [{wait, false}] with get_raange/4 if you want future semantics.

C API function: fdb_transaction_get_range

Examples

Gets all key-value pairs that are between keys <<"user/0">> and <<"user/1">>. No key with prefix <<"user/1">> will be returned. (right side exclusive)

1> Db = erlfdb:open().
2> erlfdb:get_range(DB, <<"user/0">>, <<"user/1">>).copy

-spec get_range(database() | transaction(), key(), key(), [fold_option()]) ->
                   fold_future() | [mapped_kv()] | [kv()].

Gets a range of key-value pairs from the database.

C API function: fdb_transaction_get_range

Wait option

A wait option can be provided with the following effect:

• When true, the result is waited upon and returned.
• When false, a fold_future/0 is returned, and the result can be retrieved with wait_for_all_interleaving/2.
• Experimental: When interleaving, get_range_split_points/4 is used to divide the range and the futures are waited upon with wait_for_all_interleaving/2. The flattened result is returned.

Default is true.

Examples

Gets all key-value pairs that are between keys <<"user/0">> and <<"user/1">>. No key with prefix <<"user/1">> will be returned. (left-inclusive, right-exclusive)

1> Db = erlfdb:open().
2> erlfdb:transactional(Db, fun(Tx) ->
..     Future = erlfdb:get_range(Tx, <<"user/0">>, <<"user/1">>, [{wait, false}]),
..     [Result] = erlfdb:wait_for_all_interleaving(Tx, [Future]),
..     Result
.. end).copy

-spec get_range_split_points(database() | transaction(), key(), key(), [split_option()]) ->
                                future() | [key()].

Returns a list of keys that can split the given range into (roughly) equally sized chunks based on chunk_size.

C API function: fdb_transaction_get_range_split_points

-spec get_range_startswith(database() | transaction(), key()) -> [kv()].

Gets a range of key-value pairs from the database that begin with the given prefix.

This function never returns a fold_future/0. If you want future semantics, use [{wait, false}] with get_raange_startswith/3.

C API function: fdb_transaction_get_range

-spec get_range_startswith(database() | transaction(), key(), [fold_option()]) ->
                              fold_future() | [mapped_kv()] | [kv()].

Equivalent to get_range(Tx, Prefix, erlfdb_key:strinc(Prefix), Options).

-spec get_read_version(transaction() | snapshot()) -> future().

Gets the snapshot read version used by a transaction.

This is not needed in simple cases.

C API function: fdb_transaction_get_read_version

-spec get_ss(transaction() | snapshot(), key()) -> future().

With snapshot isolation, gets a value from the database.

C API function: fdb_transaction_get

-spec get_versionstamp(transaction() | snapshot()) -> future().

Gets the versionstamp value that was used by any versionstamp operations in this transaction.

This is not needed in simple cases.

C API function: fdb_transaction_get_versionstamp

-spec get_writes_allowed(transaction() | snapshot()) -> boolean().

Returns false if disallow_writes was set on the transaction.

-spec has_watches(transaction() | snapshot()) -> boolean().

Returns true if at least one operation on the transaction up until now has been a watch.

-spec is_read_only(transaction() | snapshot()) -> boolean().

Returns true if all operations on the transaction up until now have been reads.

-spec is_ready(future()) -> boolean().

Returns true if the future is ready. That is, its result can be retrieved immediately.

C API function: fdb_future_is_ready

Tip

Use one of the wait* functions instead, such as wait/1.

-spec max(database() | transaction() | snapshot(), key(), atomic_operand()) -> ok.

Performs an atomic maximum on the value in the database.

C API function: fdb_transaction_atomic_op

See FDBMutationType.FDB_MUTATION_TYPE_MAX.

-spec min(database() | transaction() | snapshot(), key(), atomic_operand()) -> ok.

Performs an atomic minimum on the value in the database.

C API function: fdb_transaction_atomic_op

See FDBMutationType.FDB_MUTATION_TYPE_MIN.

-spec on_error(transaction() | snapshot(), error() | integer()) -> future().

Implements the recommended retry and backoff behavior for a transaction.

C API function: fdb_transaction_on_error

Tip

Use transactional/2 instead.

-spec open() -> database().

Opens a handle to the FoundationDB server using the default cluster file.

C API function: fdb_create_database

-spec open(cluster_filename()) -> database().

Opens a handle to the FoundationDB server using the provided cluster file string.

C API function: fdb_create_database

-spec open_tenant(database(), tenant_name()) -> tenant().

Opens a handle to the Tenant.

C API function: fdb_database_open_tenant

-spec reset(transaction()) -> ok.

Resets a transaction.

C API function: fdb_transaction_reset

Tip

Use transactional/2 instead.

-spec set(database() | transaction() | snapshot(), key(), value()) -> ok.

Sets a key to the given value.

C API function: fdb_transaction_set

Examples

In a transaction with a single operation:

1> Db = erlfdb:open().
2> erlfdb:set(Db, <<"hello">>, <<"world">>).copy

In a transaction with many operations:

1> Db = erlfdb:open().
2> erlfdb:transactional(Db, fun(Tx) ->
..     erlfdb:set(Tx, <<"hello">>, <<"world">>),
..     erlfdb:set(Tx, <<"foo">>, <<"bar">>)
.. end).copy

-spec set_and_watch(database(), key(), value()) -> future().

Does both a set/3 and watch/2 in a transaction.

-spec set_option(database() | transaction(), database_option() | transaction_option()) -> ok.

Equivalent to set_option(DbOrTx, Option, <<>>).

-spec set_option(database() | transaction(), database_option() | transaction_option(), binary()) -> ok.

Sets a valued option on a database or transaction.

C API functions:

• For a database/0, `fdb_database_set_option - For a t:transaction/0, [fdb_transaction_set_option`](https://apple.github.io/foundationdb/api-c.html#c.fdb_transaction_set_option)

-spec set_read_version(transaction() | snapshot(), version()) -> ok.

Sets the snapshot read version used by a transaction.

This is not needed in simple cases.

C API function: fdb_transaction_set_read_version

-spec set_versionstamped_key(database() | transaction() | snapshot(), key(), atomic_operand()) -> ok.

Transforms key using a versionstamp for the transaction.

C API function: fdb_transaction_atomic_op

See FDBMutationType.FDB_MUTATION_TYPE_SET_VERSIONSTAMPED_KEY.

-spec set_versionstamped_value(database() | transaction() | snapshot(), key(), atomic_operand()) -> ok.

Transforms param using a versionstamp for the transaction.

C API function: fdb_transaction_atomic_op

See FDBMutationType.FDB_MUTATION_TYPE_SET_VERSIONSTAMPED_VALUE.

-spec snapshot(transaction() | snapshot()) -> snapshot().

Use this to modify a transaction so that operations on the returned object are performed as Snapshot Reads.

Example

1> Db = erlfdb:open().
2> erlfdb:transactional(Db, fun(Tx) ->
..     SS = erlfdb:snapshot(Tx),
..     F1 = erlfdb:get(Tx, <<"strictly serializable read">>),
..     F2 = erlfdb:get(SS, <<"snapshot isolation read">>),
..     erlfdb:wait_for_all([F1, F2])
.. end).copy

-spec tenant_create_transaction(tenant()) -> transaction().

Creates a transaction from an open tenant.

The caller is responsible for calling commit/ when appropriate and implementing any retry behavior.

C API function: fdb_tenant_create_transaction

Tip

Use transactional/2 instead.

-spec transactional(database() | tenant() | transaction() | snapshot(), function()) -> any().

Executes the provided 1-arity function in a transaction.

You'll use the other erlfdb functions inside a transaction to safely achieve interesting behavior in your application. The FoundationDB Transaction Manifesto is a good starting point for understanding the why and how. Some examples are below.

Transaction Commit and Error Handling

The provided 1-arity function is executed, and when it returns, erlfdb inspects the transaction is for its read-only status. If read-only, control returns to the caller immediately. Otherwise, the transaction is committed to the database with commit/1. In both cases, the return value from the provided function is returned to the caller after the transaction has been completed.

An error can be encountered during the transaction (for example, when a key conflict is detected by the FDB Server). If it is an error code that FoundationDB recommends as eligible for retry, your function will be executed again. For this reason, your function should have no side-effects. Logging, sending messages, and updates to an ets table that exist in your transaction function will execute multiple times when a key conflict is encountered. Moreover, if your transaction has any branching logic, such side effects can be misleading or harmful.

Imagine a transaction to be a pure function that receives the entire database as input and returns the entire database as output. If your function's implementation is purely functional under this point of view, then it is safe.

The transaction will be executed repeatedly as needed until either (a) it is completed successfully, and control flow returns to the caller, or (b) a non-retriable error is thrown. A transaction timeout is an example of a non-retriable error, but by default, the timeout is set to infinity.

C API functions:

• For the commit, fdb_transaction_commit.
• For the retry behavior, fdb_transaction_on_error.

Arguments

• Db / Tenant: The context under which the transaction is created.
• UserFun: 1-arity function to be executed with FDB transactional semantics. The transaction (transaction/0) is provided as the argument to the function.

Examples

Using a database as the transactional context:

1> Db = erlfdb:open().
2> erlfdb:transactional(Db, fun(Tx) ->
..     not_found = erlfdb:wait(erlfdb:get(Tx, <<"hello">>)),
..     erlfdb:set(Tx, <<"hello">>, <<"world">>)
.. end).copy

Using a tenant as the transactional context:

1> Db = erlfdb:open().
2> Tenant = erlfdb:open_tenant(Db, <<"some-org">>)
2> erlfdb:transactional(Tenant, fun(Tx) ->
..     not_found = erlfdb:wait(erlfdb:get(Tx, <<"hello">>)),
..     erlfdb:set(Tx, <<"hello">>, <<"world">>)
.. end).copy

Performing non-trivial logic inside a transaction:

1> Db = erlfdb:open().
2> erlfdb:set(Db, <<"toggle">>, <<"off">>).
3> erlfdb:transactional(Db, fun(Tx) ->
..     case erlfdb:wait(erlfdb:get(Tx, <<"toggle">>)) of
..         <<"off">> ->
..             erlfdb:set(Tx, <<"toggle">>, <<"on">>),
..             off_to_on;
..         <<"on">> ->
..             erlfdb:set(Tx, <<"toggle">>, <<"off">>),
..             on_to_off
..     end
.. end).copy

-spec wait(future() | result()) -> result().

Equivalent to wait(Future, []).

-spec wait(future() | result(), [wait_option()]) -> result().

Waits for future to be ready, and returns the result.

If first argument is not a future, then simply return the first argument.

Examples

wait/2 is typically used inside a transaction:

1> Db = erlfdb:open().
2> erlfdb:transactional(Db, fun(Tx) ->
..     erlfdb:wait(erlfdb:get(Tx, <<"hello">>)),
.. end).copy

-spec wait_for_all([future() | result()]) -> [result()].

Equivalent to wait_for_all(Futures, []).

-spec wait_for_all([future() | result()], [wait_option()]) -> [result()].

Waits for each future and returns all results. The order of the results is guaranteed to match the order of the futures.

Examples

wait_for_all/2 returns the results from all futures:

1> Db = erlfdb:open().
2> erlfdb:transactional(Db, fun(Tx) ->
..     T = erlfdb:get(Tx, <<"tortoise">>)),
..     H = erlfdb:get(Tx, <<"hare">>)),
..     erlfdb:wait_for_all([T, H])
.. end).copy

-spec wait_for_all_interleaving(transaction() | snapshot(), [fold_future() | future()]) -> list().

Equivalent to wait_for_all_interleaving(Tx, Futures, []).

-spec wait_for_all_interleaving(transaction() | snapshot(), [fold_future() | future()], [wait_option()]) ->
                                   list().

Experimental. Waits for all futures and returns all results. The order of the results is guaranteed to match the order of the futures. Uses an interleaving approach, which is described below.

A future of type fold_future/0 may require multiple round trips to the database server. When provided more than one, the requests to the database are pipelined so that the server can optimize retrieval of keys. In this interleaving approach, the client sends all known requests to the server as quickly as possible.

This is an experimental optimization of wait_for_all/1, and is functionally equivalent.

Examples

Imagine a large set of users stored with prefix <<"user/">> and a large set of blog posts stored with prefix <<"post/">>. We can retrieve all users and posts efficiently with wait_for_all_interleaving/2:

1> Db = erlfdb:open().
2> erlfdb:transactional(Db, fun(Tx) ->
..     UsersF = erlfdb:get_range_startswith(Tx, <<"user/">>, [{wait, false}])),
..     PostsF = erlfdb:get_range_startswith(Tx, <<"post/">>, [{wait, false}])),
..     erlfdb:wait_for_all_interleaving(Tx, [UsersF, PostsF])
.. end).copy

-spec wait_for_any([future()]) -> future().

Equivalent to wait_for_any(Futures, []).

-spec wait_for_any([future()], [wait_option()]) -> future().

Waits for one of the provided futures in the list to enter ready state. When such a future is found, return it. The result of that future must be retrieved by the caller with get/1.

Examples

wait_for_any/2 returns a future. It will typically be the future that is the first to resolve, but that is not guaranteed:

1> Db = erlfdb:open().
2> erlfdb:transactional(Db, fun(Tx) ->
..     T = erlfdb:get(Tx, <<"tortoise">>)),
..     H = erlfdb:get(Tx, <<"hare">>)),
..     Winner = erlfdb:wait_for_any([T, H]),
..     erlfdb:get(Winner)
.. end).copy

-spec watch(database() | transaction() | snapshot(), key()) -> future().

Creates a watch on a key.

An Overview how Watches Work

C API function: fdb_transaction_watch

Examples

In this example, when wait/1 returns, the value at the key <<"hello">> has changed. We must then do a get/2 if we want to know what the value is.

1> Db = erlfdb:open().
2> Watch = erlfdb:watch(Db, <<"hello">>).
3> ok = erlfdb:wait(Watch).
4> erlfdb:get(Db, <<"hello">>).copy

In this example, we rely on the future's ready message to be delivered to our calling process. This form of the ready message (watch_future_ready_message/0) is valid only for futures created by watch/2.

1> Db = erlfdb:open(),
2> Watch = erlfdb:watch(Db, <<"hello">>).
3> receive
..    {_Ref, ready} ->
..        erlfdb:get(Db, <<"hello">>)
.. endcopy