C API

This API provides a very low-level interface to FoundationDB. It is primarily intended for use in implementing higher level APIs, rather than for direct use. If you are new to FoundationDB, you are probably better served by reading one of the other APIs first.

Installation

FoundationDB’s C bindings are installed with the FoundationDB client binaries (see Installing FoundationDB client binaries).

On Linux,: fdb_c.h is installed into /usr/include/foundationdb/

libfdb_c.so is installed into /usr/lib/
On macOS,: fdb_c.h is installed into /usr/local/include/foundationdb/

libfdb_c.dylib is installed into /usr/local/lib/

Linking

The FoundationDB C bindings are provided as a shared object which may be linked against at build time, or dynamically loaded at runtime. Any program that uses this API must be able to find a platform-appropriate shared library at runtime. Generally, this condition is best met by installing the FoundationDB client binaries (see Installing FoundationDB client binaries) on any machine where the program will be run.

Linux

When linking against libfdb_c.so, you must also link against libm, libpthread and librt. These dependencies will be resolved by the dynamic linker when using this API via dlopen() or an FFI.

macOS

When linking against libfdb_c.dylib, no additional libraries are required.

API versioning

Prior to including fdb_c.h, you must define the FDB_API_VERSION macro. This, together with the fdb_select_api_version() function, allows programs written against an older version of the API to compile and run with newer versions of the C library. The current version of the FoundationDB C API is 730.

#define FDB_API_VERSION 730
#include <foundationdb/fdb_c.h>

fdb_error_t fdb_select_api_version(int version)

Must be called before any other API functions. version must be less than or equal to FDB_API_VERSION (and should almost always be equal).

Language bindings implemented in C which themselves expose API versioning will usually pass the version requested by the application, instead of always passing FDB_API_VERSION.

Passing a version less than FDB_API_VERSION will cause the API to behave as it did in the older version.

It is an error to call this function after it has returned successfully. It is not thread safe, and if called from more than one thread simultaneously its behavior is undefined.

Note

This is actually implemented as a macro. If you are accessing this API via dlopen() or an FFI, you will need to use fdb_select_api_version_impl().

Warning

When using the multi-version client API, setting an API version that is not supported by a particular client library will prevent that client from being used to connect to the cluster. In particular, you should not advance the API version of your application after upgrading your client until the cluster has also been upgraded.

fdb_error_t fdb_select_api_version_impl(int runtime_version, int header_version)

This is the actual entry point called by the fdb_select_api_version() macro. It should never be called directly from C, but if you are accessing this API via dlopen() or an FFI, you will need to use it. fdb_select_api_version(v) is equivalent to fdb_select_api_version_impl(v, FDB_API_VERSION).

It is an error to call this function after it has returned successfully. It is not thread safe, and if called from more than one thread simultaneously its behavior is undefined.

runtime_version

The version of run-time behavior the API is requested to provide. Must be less than or equal to header_version, and should almost always be equal.

Language bindings which themselves expose API versioning will usually pass the version requested by the application.

header_version

The version of the ABI (application binary interface) that the calling code expects to find in the shared library. If you are using an FFI, this must correspond to the version of the API you are using as a reference (currently 730). For example, the number of arguments that a function takes may be affected by this value, and an incorrect value is unlikely to yield success.

Warning

int fdb_get_max_api_version(): Returns FDB_API_VERSION, the current version of the FoundationDB C API. This is the maximum version that may be passed to fdb_select_api_version().

Network

The FoundationDB client library performs most tasks on a singleton thread (which usually will be a different thread than your application runs on). These functions are used to configure, start and stop the FoundationDB event loop on this thread.

fdb_error_t fdb_network_set_option(FDBNetworkOption option, uint8_t const *value, int value_length): Called to set network options. If the given option is documented as taking a parameter, you must also pass a pointer to the parameter value and the parameter value’s length. If the option is documented as taking an Int parameter, value must point to a signed 64-bit integer (little-endian), and value_length must be 8. This memory only needs to be valid until fdb_network_set_option() returns.

type FDBNetworkOption: Please see fdb_c_options.g.h for a definition of this type, along with documentation of its allowed values.

fdb_error_t fdb_setup_network(): Must be called after fdb_select_api_version() (and zero or more calls to fdb_network_set_option()) and before any other function in this API. fdb_setup_network() can only be called once.

fdb_error_t fdb_add_network_thread_completion_hook(void (*hook)(void*), void *hook_parameter): Must be called after fdb_setup_network() and prior to fdb_run_network() if called at all. This will register the given callback to run at the completion of the network thread. If there are multiple network threads running (which might occur if one is running multiple versions of the client, for example), then the callback is invoked once on each thread. When the supplied function is called, the supplied parameter is passed to it.

fdb_error_t fdb_run_network()

Must be called after fdb_setup_network() before any asynchronous functions in this API can be expected to complete. Unless your program is entirely event-driven based on results of asynchronous functions in this API and has no event loop of its own, you will want to invoke this function on an auxiliary thread (which it is your responsibility to create).

This function will not return until fdb_stop_network() is called by you or a serious error occurs. It is not possible to run more than one network thread, and the network thread cannot be restarted once it has been stopped. This means that once fdb_run_network has been called, it is not legal to call it again for the lifetime of the running program.

fdb_error_t fdb_stop_network()

Signals the event loop invoked by fdb_run_network() to terminate. You must call this function and wait for fdb_run_network() to return before allowing your program to exit, or else the behavior is undefined. For example, when running fdb_run_network() on a thread (using pthread), this will look like:

pthread_t network_thread; /* handle for thread which invoked fdb_run_network() */
int err;

...

err = fdb_stop_network();
if ( err ) {
    /* An error occurred (probably network not running) */
}
err = pthread_join( network_thread, NULL );
if ( err ) {
    /* Unknown error */
}
exit(0);

This function may be called from any thread. Once the network is stopped it cannot be restarted during the lifetime of the running program.

Future

Most functions in the FoundationDB API are asynchronous, meaning that they may return to the caller before actually delivering their result. These functions always return FDBFuture*. An FDBFuture object represents a result value or error to be delivered at some future time. You can wait for a Future to be “ready” – to have a value or error delivered – by setting a callback function, or by blocking a thread, or by polling. Once a Future is ready, you can extract either an error code or a value of the appropriate type (the documentation for the original function will tell you which fdb_future_get_() function you should call).

To use the API in a synchronous way, you would typically do something like this for each asynchronous call:

// Call an API that returns FDBFuture*, documented as returning type foo in the future
f = fdb_something();

// Wait for the Future to be *ready*
if ( (fdb_future_block_until_ready(f)) != 0 ) {
    // Exceptional error (e.g. out of memory)
}

if ( (err = fdb_future_get_foo(f, &result)) == 0 ) {
    // Use result
    // In some cases, you must be finished with result before calling
    // fdb_future_destroy() (see the documentation for the specific
    // fdb_future_get_*() method)
} else {
    // Handle the error. If this is an error in a transaction, see
    // fdb_transaction_on_error()
}

fdb_future_destroy(f);

Futures make it easy to do multiple operations in parallel, by calling several asynchronous functions before waiting for any of the results. This can be important for reducing the latency of transactions.

See Programming with futures for further (language-independent) discussion.

type FDBFuture: An opaque type that represents a Future in the FoundationDB C API.

void fdb_future_cancel(FDBFuture *future): Cancels an FDBFuture object and its associated asynchronous operation. If called before the future is ready, attempts to access its value will return an operation_cancelled error. Cancelling a future which is already ready has no effect. Note that even if a future is not ready, its associated asynchronous operation may have succesfully completed and be unable to be cancelled.

void fdb_future_destroy(FDBFuture *future): Destroys an FDBFuture object. It must be called exactly once for each FDBFuture* returned by an API function. It may be called before or after the future is ready. It will also cancel the future (and its associated operation if the latter is still outstanding).

fdb_error_t fdb_future_block_until_ready(FDBFuture *future): Blocks the calling thread until the given Future is ready. It will return success even if the Future is set to an error – you must call fdb_future_get_error() to determine that. fdb_future_block_until_ready() will return an error only in exceptional conditions (e.g. deadlock detected, out of memory or other operating system resources).

Warning

Never call this function from a callback passed to fdb_future_set_callback(). This may block the thread on which fdb_run_network() was invoked, resulting in a deadlock. In some cases the client can detect the deadlock and throw a blocked_from_network_thread error.

fdb_bool_t fdb_future_is_ready(FDBFuture *future): Returns non-zero if the Future is ready. A Future is ready if it has been set to a value or an error.

fdb_error_t fdb_future_set_callback(FDBFuture *future, FDBCallback callback, void *callback_parameter): Causes the FDBCallback function to be invoked as callback(future, callback_parameter) when the given Future is ready. If the Future is already ready, the call may occur in the current thread before this function returns (but this behavior is not guaranteed). Alternatively, the call may be delayed indefinitely and take place on the thread on which fdb_run_network() was invoked, and the callback is responsible for any necessary thread synchronization (and/or for posting work back to your application event loop, thread pool, etc. if your application’s architecture calls for that).

Note

This function guarantees the callback will be executed at most once.

Warning

Never call fdb_future_block_until_ready() from a callback passed to this function. This may block the thread on which fdb_run_network() was invoked, resulting in a deadlock.

type FDBCallback: A pointer to a function which takes FDBFuture* and void* and returns void.

void fdb_future_release_memory(FDBFuture *future)

Note

This function provides no benefit to most application code. It is designed for use in writing generic, thread-safe language bindings. Applications should normally call fdb_future_destroy() only.

This function may only be called after a successful (zero return value) call to fdb_future_get_key(), fdb_future_get_value(), or fdb_future_get_keyvalue_array(). It indicates that the memory returned by the prior get call is no longer needed by the application. After this function has been called the same number of times as fdb_future_get_*(), further calls to fdb_future_get_*() will return a future_released error. It is still necessary to later destroy the future with fdb_future_destroy().

Calling this function is optional, since fdb_future_destroy() will also release the memory returned by get functions. However, fdb_future_release_memory() leaves the future object itself intact and provides a specific error code which can be used for coordination by multiple threads racing to do something with the results of a specific future. This has proven helpful in writing binding code.

fdb_error_t fdb_future_get_error(FDBFuture *future): Returns zero if future is ready and not in an error state, and a non-zero error code otherwise.

fdb_error_t fdb_future_get_int64(FDBFuture *future, int64_t *out)

Extracts a 64-bit integer from a pointer to FDBFuture into a caller-provided variable of type int64_t. future must represent a result of the appropriate type (i.e. must have been returned by a function documented as returning this type), or the results are undefined.