foundationdb/lib.rs
1// Copyright 2018 foundationdb-rs developers, https://github.com/Clikengo/foundationdb-rs/graphs/contributors
2//
3// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
4// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
5// http://opensource.org/licenses/MIT>, at your option. This file may not be
6// copied, modified, or distributed except according to those terms.
7#![doc = include_str!("../README.md")]
8
9use foundationdb_sys::if_cfg_api_versions;
10
11#[macro_use]
12extern crate static_assertions;
13
14pub mod api;
15#[deny(missing_docs)]
16pub mod budget;
17if_cfg_api_versions! {min = 510, max = 600 =>
18 pub mod cluster;
19}
20mod database;
21pub mod directory;
22#[deny(missing_docs)]
23pub mod env;
24mod error;
25if_cfg_api_versions! {min = 700 =>
26 #[deny(missing_docs)]
27 pub mod fdb_keys;
28}
29pub mod future;
30mod keyselector;
31if_cfg_api_versions! {min = 710 =>
32 #[deny(missing_docs)]
33 pub mod mapped_key_values;
34}
35
36pub mod metrics;
37
38/// Generated configuration types for use with the various `set_option` functions
39#[allow(clippy::all)]
40pub mod options;
41
42#[cfg(any(feature = "recipes", feature = "recipes-leader-election"))]
43pub mod recipes;
44
45// Re-export metrics types for convenience
46pub use crate::metrics::{
47 AttemptMetrics, AttemptOutcome, ConflictKeys, MetricsReport, TransactionMetrics,
48};
49
50#[deny(missing_docs)]
51pub mod runner;
52
53pub mod timekeeper;
54mod transaction;
55mod tuple_ext;
56
57pub mod tuple {
58 pub use crate::tuple_ext::*;
59 pub use foundationdb_tuple::*;
60}
61
62if_cfg_api_versions! {min = 510, max = 600 =>
63 pub use crate::cluster::Cluster;
64}
65
66pub use crate::budget::{AttemptUsage, BudgetExceeded, BudgetKind, ClientBudget, UsageSnapshot};
67pub use crate::database::*;
68pub use crate::env::{Clock, Environment, Rng, SeededRng, WallClock};
69pub use crate::error::{FdbBindingError, RetryDecision, RetryableError};
70pub use crate::error::{FdbError, FdbResult};
71pub use crate::keyselector::*;
72pub use crate::runner::{
73 AttemptFailure, MetricsHooks, NativeRetryPolicy, RetryPolicy, RunnerHooks, TransactionRunner,
74};
75pub use crate::transaction::*;
76
77/// Initialize the FoundationDB Client API and start the network thread.
78///
79/// Safe and idempotent: calling it multiple times returns `Ok` as long as the
80/// (default) API version matches. Calling it is optional: creating a [`Database`]
81/// initializes the client automatically. The network runs until process exit,
82/// where an atexit hook stops it and joins the network thread, or until an
83/// explicit [`api::stop_network`] call.
84///
85/// The returned guard is kept for backward compatibility, dropping it does
86/// nothing.
87///
88/// <div class="warning">
89///
90/// The automatic stop at process exit is a convenience suited to tests and
91/// short-lived tools. In a production application, prefer handling the network
92/// stop yourself: the network thread is the event loop driving every
93/// transaction, you may still have on-going operations at exit time, and you
94/// usually want a clean teardown. Finish or cancel your work, drop your
95/// [`Database`] handles, then call [`api::stop_network`].
96///
97/// </div>
98///
99/// # Errors
100///
101/// - error 2201 (`api_version_already_set`) if a different API version was
102/// selected before
103/// - error 2025 (`network_cannot_be_restarted`) if the network was stopped
104///
105/// # Examples
106///
107/// ```rust
108/// foundationdb::boot().expect("failed to initialize FoundationDB");
109/// // do some interesting things with the API...
110/// ```
111///
112/// ```rust
113/// #[tokio::main]
114/// async fn main() {
115/// foundationdb::boot().expect("failed to initialize FoundationDB");
116/// // do some interesting things with the API...
117/// }
118/// ```
119pub fn boot() -> FdbResult<api::NetworkAutoStop> {
120 api::FdbApiBuilder::default().build()?.boot()
121}
122
123/// Returns the default Fdb cluster configuration file path
124#[cfg(target_os = "linux")]
125pub fn default_config_path() -> &'static str {
126 "/etc/foundationdb/fdb.cluster"
127}
128
129/// Returns the default Fdb cluster configuration file path
130#[cfg(target_os = "macos")]
131pub fn default_config_path() -> &'static str {
132 "/usr/local/etc/foundationdb/fdb.cluster"
133}
134
135/// Returns the default Fdb cluster configuration file path
136#[cfg(target_os = "windows")]
137pub fn default_config_path() -> &'static str {
138 "C:/ProgramData/foundationdb/fdb.cluster"
139}
140
141/// slice::from_raw_parts assumes the pointer to be aligned and non-null.
142/// Since Rust nightly (mid-February 2024), it is enforced with debug asserts,
143/// but the FDBServer can return a null pointer if the slice is empty:
144/// ptr: 0x0, len: 0
145/// To avoid the assert, an empty slice is directly returned in that situation
146fn from_raw_fdb_slice<T, U: Into<usize>>(ptr: *const T, len: U) -> &'static [T] {
147 if ptr.is_null() {
148 return &[];
149 }
150 unsafe { std::slice::from_raw_parts(ptr, len.into()) }
151}