FeOxDB

https://docs.rs/feoxdb/0.5.0/feoxdb/
Admin
FeOxDB is an ultra-fast embedded key-value database with sub-microsecond latency, lock-free...
Tokens:113,274
Snippets:1,050
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### get_format

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/format/fn.get_format.html

Factory function to get the appropriate format handler based on version.

```APIDOC
## get_format

### Description
Factory function to get the appropriate format handler based on version.

### Signature
```rust
pub fn get_format(version: u32) -> Box<dyn RecordFormat>
```

### Parameters
#### Path Parameters
- **version** (u32) - Required - The version number to determine the format handler.
```

--------------------------------

### FeoxStore Basic Operations Example

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/struct.FeoxStore.html

Demonstrates basic insert and compare-and-swap operations. Use compare_and_swap for conditional updates based on the current value.

```rust
store.insert(b"config", b"v1")?;

// Successful CAS - value matches
let swapped = store.compare_and_swap(b"config", b"v1", b"v2")?;
assert_eq!(swapped, true);

// Failed CAS - value doesn't match
let swapped = store.compare_and_swap(b"config", b"v1", b"v3")?;
assert_eq!(swapped, false); // Value is now "v2", not "v1"

// CAS on non-existent key
let swapped = store.compare_and_swap(b"missing", b"any", b"new")?;
assert_eq!(swapped, false);
```

--------------------------------

### Start WriteBuffer Workers

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/write_buffer/struct.WriteBuffer.html

Starts the background worker threads for the WriteBuffer. Specify the number of worker threads to start.

```rust
pub fn start_workers(&mut self, num_workers: usize)
```

--------------------------------

### Start TtlSweeper Thread

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/ttl_sweep/struct.TtlSweeper.html

Starts the background sweeper thread for the TtlSweeper. This method requires mutable access to the sweeper.

```rust
pub fn start(&mut self)
```

--------------------------------

### FeoxStore JSON Patch Example

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/struct.FeoxStore.html

Shows how to insert an initial JSON value and then apply a JSON patch to modify it. Ensure both the value and patch are valid JSON.

```rust
// Insert initial JSON value
let initial = br#"{"name":"Alice","age":30}"#;
store.insert(b"user:1", initial)?;

// Apply JSON patch to update age
let patch = br#"[{"op":"replace","path":"/age","value":31}]"#;
store.json_patch(b"user:1", patch)?;

// Value now has age updated to 31
let updated = store.get(b"user:1")?;
assert_eq!(updated.len(), initial.len()); // Same length, just age changed
```

--------------------------------

### FeoxStore::start_ttl_sweeper

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/struct.FeoxStore.html

Initializes and starts the Time-To-Live (TTL) sweeper process. This function requires an `Arc<Self>` and an optional `TtlConfig`.

```APIDOC
## FeoxStore::start_ttl_sweeper

### Description
Start the TTL sweeper if configured. This must be called with an `Arc<Self>` after construction.

### Method
`start_ttl_sweeper(self: &Arc<Self>, config: Option<TtlConfig>)`

### Parameters
#### Path Parameters
- `config` ( Option<TtlConfig> ) - Optional configuration for the TTL sweeper.

```

--------------------------------

### Example Usage of atomic_increment

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/struct.FeoxStore.html

Shows how to initialize, increment, and decrement a counter using the atomic_increment method. Handles creation of new counters as well.

```rust
// Initialize counter with proper binary format
let initial: i64 = 0;
store.insert(b"visits", &initial.to_le_bytes())?;

// Increment atomically
let val = store.atomic_increment(b"visits", 1)?;
assert_eq!(val, 1);

// Increment by 5
let val = store.atomic_increment(b"visits", 5)?;
assert_eq!(val, 6);

// Decrement by 2
let val = store.atomic_increment(b"visits", -2)?;
assert_eq!(val, 4);

// Or create new counter directly (starts at delta value)
let downloads = store.atomic_increment(b"downloads", 100)?;
assert_eq!(downloads, 100);
```

--------------------------------

### Define FEOX_DATA_START_BLOCK Constant

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/constants/constant.FEOX_DATA_START_BLOCK.html

This constant defines the starting block for FEOX data. It is a public constant of type u64.

```rust
pub const FEOX_DATA_START_BLOCK: u64 = 16;
```

--------------------------------

### FeoxStore::new

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/struct.FeoxStore.html

Creates a new FeoxStore instance with default configuration. This is the primary way to initialize the store.

```APIDOC
## FeoxStore::new

### Description
Create a new FeoxStore with default configuration.

### Method
`FeoxStore::new(device_path: Option<String>) -> Result<Self>`

### Parameters
* `device_path` (Option<String>) - Optional path to the device for store initialization.
```

--------------------------------

### ValueOffset

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/format/struct.FormatV1.html

Gets the offset where the value data starts in the serialized format.

```APIDOC
## fn value_offset(&self, key_len: usize) -> usize

### Description
Get the offset where value data starts in the serialized format

### Parameters
- **key_len** (usize) - The length of the key.

### Returns
- (usize) - The offset of the value data.
```

--------------------------------

### Get Value Offset in Serialized Format

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/format/struct.FormatV2.html

Determines the starting byte offset of the value data within the serialized record format. This is useful for direct value access without full parsing.

```rust
fn value_offset(&self, key_len: usize) -> usize
```

--------------------------------

### Insert and Get Size of a Value in FeoxStore

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/struct.FeoxStore.html

Demonstrates inserting a large value and then retrieving its size in bytes. Ensure the key exists before calling get_size.

```rust
store.insert(b"large_file", &vec![0u8; 1_000_000])?;

// Check size before loading
let size = store.get_size(b"large_file")?;
assert_eq!(size, 1_000_000);
```

--------------------------------

### FeoxStore Create New Instance

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/struct.FeoxStore.html

Demonstrates creating a new FeoxStore instance. Use `new` for default configuration or `with_config` for custom settings.

```rust
let store = FeoxStore::new(Some("/path/to/data".to_string()))?;
```

```rust
let config = StoreConfig { /* ... fields ... */ };
let store = FeoxStore::with_config(config)?;
```

--------------------------------

### Get element index using pointer arithmetic

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Use `element_offset` to find the index of an element reference within a slice using pointer arithmetic. Returns `None` if the element reference is not aligned to the start of an element. This is a nightly-only experimental API.

```rust
#![feature(substr_range)]

let nums: &[u32] = &[1, 7, 1, 1];
let num = &nums[2];

assert_eq!(num, &1);
assert_eq!(nums.element_offset(num), Some(2));
```

```rust
#![feature(substr_range)]

let arr: &[[u32; 2]] = &[[0, 1], [2, 3]];
let flat_arr: &[u32] = arr.as_flattened();

let ok_elm: &[u32; 2] = flat_arr[0..2].try_into().unwrap();
let weird_elm: &[u32; 2] = flat_arr[1..3].try_into().unwrap();

assert_eq!(ok_elm, &[0, 1]);
assert_eq!(weird_elm, &[1, 2]);

assert_eq!(arr.element_offset(ok_elm), Some(0)); // Points to element 0
assert_eq!(arr.element_offset(weird_elm), None); // Points between element 0 and 1
```

--------------------------------

### FeoxStore::with_config

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/struct.FeoxStore.html

Creates a new FeoxStore instance with custom configuration. Allows for fine-grained control over store settings.

```APIDOC
## FeoxStore::with_config

### Description
Create a new FeoxStore with custom configuration.

### Method
`FeoxStore::with_config(config: StoreConfig) -> Result<Self>`

### Parameters
* `config` (StoreConfig) - Custom configuration for the FeoxStore.
```

--------------------------------

### Trim Suffix Example for Bytes

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Illustrates removing a suffix from a byte slice using `trim_suffix`. This is also an experimental API. It shows behavior when the suffix exists, does not exist, or matches the entire slice.

```rust
#![feature(trim_prefix_suffix)]

let v = &[10, 40, 30];

// Suffix present - removes it
assert_eq!(v.trim_suffix(&[30]), &[10, 40][..]);
assert_eq!(v.trim_suffix(&[40, 30]), &[10][..]);
assert_eq!(v.trim_suffix(&[10, 40, 30]), &[][..]);

// Suffix absent - returns original slice
assert_eq!(v.trim_suffix(&[50]), &[10, 40, 30][..]);
assert_eq!(v.trim_suffix(&[50, 30]), &[10, 40, 30][..]);
```

--------------------------------

### Allocate Sectors Using Best-Fit

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/free_space/struct.FreeSpaceManager.html

Allocates a specified number of sectors using a best-fit algorithm. Returns the starting sector of the allocated block or an error if insufficient space is available.

```rust
pub fn allocate_sectors(&mut self, sectors_needed: u64) -> Result<u64>
```

--------------------------------

### Handling File Metadata Operations

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/error/type.Result.html

Illustrates using `and_then` to chain operations that might fail, such as getting file metadata and then its modification time.

```APIDOC
## File Metadata Example with and_then

### Description
This example shows chaining `metadata()` and `modified()` calls on a `Path`, both of which return `Result` types. `and_then` is used to handle the potential errors from each step.

### Method
`and_then`

### Endpoint
N/A (Illustrative code example)

### Parameters
N/A

### Request Example
```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

### Response
#### Success Response
Returns `Ok` with the modification time if all operations succeed.

#### Response Example
```rust
Ok(SystemTime)
```

#### Error Response
Returns `Err` if `metadata()` or `modified()` fails (e.g., `ErrorKind::NotFound`).

#### Error Response Example
```rust
Err(io::Error)
```
```

--------------------------------

### Retrieve Bytes Value by Key from FeoxStore

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/struct.FeoxStore.html

Retrieve a value by key without copying, returning it as Bytes. This is significantly faster than `get()` for large values.

```rust
let bytes = store.get_bytes(b"key")?;
// Use bytes directly without copying
assert_eq!(&bytes[..], b"value");
```

--------------------------------

### Create and Use In-Memory FeoxStore

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/index.html

Demonstrates creating an in-memory FeoxStore, inserting, retrieving, and deleting a key-value pair. This mode offers the fastest performance as no data is persisted to disk.

```rust
use feoxdb::FeoxStore;

// Create an in-memory store
let store = FeoxStore::new(None)?;

// Insert a key-value pair
store.insert(b"key", b"value")?;

// Retrieve the value
let value = store.get(b"key")?;
assert_eq!(value, b"value");

// Delete the key
store.delete(b"key")?;
```

--------------------------------

### Record Get Operation

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/stats/struct.Statistics.html

Records a get operation, including its latency and whether it resulted in a cache hit.

```rust
pub fn record_get(&self, latency_ns: u64, hit: bool)
```

--------------------------------

### FreeSpaceManager::initialize

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/free_space/struct.FreeSpaceManager.html

Initializes the FreeSpaceManager with a given device size.

```APIDOC
## FreeSpaceManager::initialize

### Description
Initialize with device size and initial free space.

### Method
`initialize(&mut self, device_size: u64) -> Result<()>`

### Parameters
- `device_size` (u64): The total size of the device.

### Returns
- `Result<()>`: Ok(()) on success, or an error if initialization fails.
```

--------------------------------

### WriteBuffer::start_workers

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/write_buffer/struct.WriteBuffer.html

Starts the background worker threads for the WriteBuffer.

```APIDOC
## WriteBuffer::start_workers

### Description
Starts the background worker threads for the WriteBuffer.

### Signature
```rust
pub fn start_workers(&mut self, num_workers: usize)
```
```

--------------------------------

### Create and Use Persistent FeoxStore

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/index.html

Shows how to create a FeoxStore that persists data to a specified file path. Operations are automatically persisted, and an explicit `flush()` call ensures data is written to disk.

```rust
use feoxdb::FeoxStore;

// Create a persistent store
let store = FeoxStore::new(Some("/path/to/data.feox".to_string()))?;

// Operations are automatically persisted
store.insert(b"persistent_key", b"persistent_value")?;

// Flush to disk
store.flush();
```

--------------------------------

### Configure FeoxStore with Builder Pattern

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/index.html

Illustrates using the builder pattern to configure various aspects of the FeoxStore, including device path, file size, memory limits, hash buckets, and enabling TTL support.

```rust
use feoxdb::FeoxStore;

let store = FeoxStore::builder()
    .device_path("/path/to/data.feox")
    .file_size(5 * 1024 * 1024 * 1024)  // 5GB initial file size (default: 1GB)
    .max_memory(1024 * 1024 * 1024)  // 1GB limit
    .hash_bits(20)  // 1M hash buckets
    .enable_ttl(true)  // Enable TTL support (default: false)
    .build()?;
```

--------------------------------

### try_get_i8

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed 8 bit integer from `self`.

```APIDOC
## try_get_i8

### Description
Gets a signed 8 bit integer from `self`.

### Signature
`fn try_get_i8(&mut self) -> Result<i8, TryGetError>`
```

--------------------------------

### try_get_u8

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned 8 bit integer from `self`.

```APIDOC
## try_get_u8

### Description
Gets an unsigned 8 bit integer from `self`.

### Signature
`fn try_get_u8(&mut self) -> Result<u8, TryGetError>`
```

--------------------------------

### Get Slice Length

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Returns the number of elements in the slice.

```rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

--------------------------------

### Basic StoreBuilder Usage

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/builder/struct.StoreBuilder.html

Demonstrates the basic usage of StoreBuilder to create a FeoxStore with custom memory, hash bits, and TTL settings. Ensure `build()` is called to finalize the store creation.

```rust
use feoxdb::FeoxStore;

let store = FeoxStore::builder()
    .max_memory(1_000_000_000)
    .hash_bits(20)
    .enable_ttl(true)
    .build()?;
```

--------------------------------

### iter

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Returns an iterator over the slice, yielding all items from start to end.

```APIDOC
## iter(&self) -> Iter<'_, T>

### Description
Returns an iterator over the slice. The iterator yields all items from start to end.

### Returns
* `Iter<'_, T>`: An iterator over the elements of the slice.
```

--------------------------------

### Create FeoxStore with Builder

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/struct.FeoxStore.html

Use the builder to configure FeoxStore with specific options like maximum memory. Ensure the store is built within a context that can handle potential errors.

```rust
use feoxdb::FeoxStore;

let store = FeoxStore::builder()
    .max_memory(2_000_000_000)
    .build()?;
```

--------------------------------

### get_int_ne

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed n-byte integer from `self` in native-endian byte order.

```APIDOC
## get_int_ne

### Description
Gets a signed n-byte integer from `self` in native-endian byte order.

### Signature
`fn get_int_ne(&mut self, nbytes: usize) -> i64`
```

--------------------------------

### Configure Persistent Store with File Size

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/builder/struct.StoreBuilder.html

Configures a persistent FeoxStore by setting the device path and pre-allocating a specific file size. This example shows how to set a 10GB file size for a new persistent store.

```rust
use feoxdb::FeoxStore;

let store = FeoxStore::builder()
    .device_path("/path/to/data.feox")
    .file_size(10 * 1024 * 1024 * 1024)  // 10GB
    .build()?;
```

--------------------------------

### Perform Range Queries and Store Operations

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/index.html

Demonstrates how to perform range queries on sorted keys and other store operations like checking key existence, getting the number of entries, and retrieving memory usage statistics.

```rust
use feoxdb::FeoxStore;

let store = FeoxStore::new(None)?;

// Insert sorted keys
store.insert(b"user:001", b"Mehran")?;
store.insert(b"user:002", b"Bob")?;
store.insert(b"user:003", b"Charlie")?;

// Range query (both start and end are inclusive)
let results = store.range_query(b"user:001", b"user:003", 10)?;
assert_eq!(results.len(), 3);  // Returns user:001, user:002, user:003

// Check existence
assert!(store.contains_key(b"user:001"));

// Get store metrics
assert_eq!(store.len(), 3);
println!("Memory usage: {} bytes", store.memory_usage());
```

--------------------------------

### get_int_le

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed n-byte integer from `self` in little-endian byte order.

```APIDOC
## get_int_le

### Description
Gets a signed n-byte integer from `self` in little-endian byte order.

### Signature
`fn get_int_le(&mut self, nbytes: usize) -> i64`
```

--------------------------------

### get_int

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed n-byte integer from `self` in big-endian byte order.

```APIDOC
## get_int

### Description
Gets a signed n-byte integer from `self` in big-endian byte order.

### Signature
`fn get_int(&mut self, nbytes: usize) -> i64`
```

--------------------------------

### DiskIO::new

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/io/struct.DiskIO.html

Constructs a new DiskIO instance. It takes an Arc<File> and a boolean to indicate whether to use direct I/O.

```APIDOC
## DiskIO::new

### Description
Constructs a new DiskIO instance.

### Signature
```rust
pub fn new(file: Arc<File>, use_direct_io: bool) -> Result<Self>
```

### Parameters
* `file` (Arc<File>) - A reference-counted pointer to the file to be used for I/O.
* `use_direct_io` (bool) - A boolean flag to enable or disable direct I/O.

### Returns
* `Result<Self>` - A Result containing the new DiskIO instance on success, or an error on failure.
```

--------------------------------

### get_uint_ne

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned n-byte integer from `self` in native-endian byte order.

```APIDOC
## get_uint_ne

### Description
Gets an unsigned n-byte integer from `self` in native-endian byte order.

### Signature
`fn get_uint_ne(&mut self, nbytes: usize) -> u64`
```

--------------------------------

### Time-To-Live (TTL) Support

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/index.html

Demonstrates how to enable and use the TTL feature to set expiration times for keys, check remaining TTL, and update or remove TTL.

```APIDOC
## Time-To-Live (TTL) Support

### Description
Enable TTL feature via builder and set, check, update, or remove TTL for keys.

### Usage
```rust
use feoxdb::FeoxStore;

// Enable TTL feature via builder
let store = FeoxStore::builder()
    .enable_ttl(true)
    .build()?;

// Set key to expire after 60 seconds
store.insert_with_ttl(b"session:123", b"user_session", 60)?;

// Check remaining TTL
if let Some(ttl) = store.get_ttl(b"session:123")? {
    println!("Session expires in {} seconds", ttl);
}

// Extend TTL to 120 seconds
store.update_ttl(b"session:123", 120)?;

// Remove TTL (make permanent)
store.persist(b"session:123")?;
```
```

--------------------------------

### Enable and Use TTL in FeoxStore

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/index.html

Demonstrates how to enable the TTL feature, set keys with expiration times, check remaining TTL, extend expiration, and remove TTL to make a key permanent.

```rust
use feoxdb::FeoxStore;

// Enable TTL feature via builder
let store = FeoxStore::builder()
    .enable_ttl(true)
    .build()?;

// Set key to expire after 60 seconds
store.insert_with_ttl(b"session:123", b"user_session", 60)?;

// Check remaining TTL
if let Some(ttl) = store.get_ttl(b"session:123")? {
    println!("Session expires in {} seconds", ttl);
}

// Extend TTL to 120 seconds
store.update_ttl(b"session:123", 120)?;

// Remove TTL (make permanent)
store.persist(b"session:123")?;
```

--------------------------------

### get_uint_le

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned n-byte integer from `self` in little-endian byte order.

```APIDOC
## get_uint_le

### Description
Gets an unsigned n-byte integer from `self` in little-endian byte order.

### Signature
`fn get_uint_le(&mut self, nbytes: usize) -> u64`
```

--------------------------------

### Run FeoxDB Benchmarks and Tests

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/index.html

Provides commands to run Criterion benchmarks for latency analysis and a deterministic test for reproducible results. Typical performance metrics on an M3 Max are also included.

```bash
# Criterion benchmarks for detailed latency analysis
car go bench

# Deterministic test for reproducible results
car go run --release --example deterministic_test 100000 100
```

--------------------------------

### get_uint

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned n-byte integer from `self` in big-endian byte order.

```APIDOC
## get_uint

### Description
Gets an unsigned n-byte integer from `self` in big-endian byte order.

### Signature
`fn get_uint(&mut self, nbytes: usize) -> u64`
```

--------------------------------

### Initialize FreeSpaceManager with Device Size

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/free_space/struct.FreeSpaceManager.html

Initializes the FreeSpaceManager with a given device size and sets up the initial free space. This is crucial before performing any allocation or release operations.

```rust
pub fn initialize(&mut self, device_size: u64) -> Result<()>
```

--------------------------------

### Get Last Element

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Returns the last element of the slice, or `None` if it is empty.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&30), v.last());

let w: &[i32] = &[];
assert_eq!(None, w.last());
```

--------------------------------

### Get First Element

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Returns the first element of the slice, or `None` if it is empty.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&10), v.first());

let w: &[i32] = &[];
assert_eq!(None, w.first());
```

--------------------------------

### FreeSpaceManager::new

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/free_space/struct.FreeSpaceManager.html

Creates a new instance of the FreeSpaceManager.

```APIDOC
## FreeSpaceManager::new

### Description
Create a new free space manager.

### Method
`new()`

### Returns
- `Self`: A new FreeSpaceManager instance.
```

--------------------------------

### Run FeoxDB Benchmarks

Source: https://docs.rs/feoxdb

Commands to run benchmarks using Criterion for latency analysis and a deterministic test for reproducible results.

```bash
# Criterion benchmarks for detailed latency analysis
cargo bench

# Deterministic test for reproducible results
cargo run --release --example deterministic_test 100000 100
```

--------------------------------

### Initialize WriteBuffer

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/write_buffer/struct.WriteBuffer.html

Creates a new instance of WriteBuffer. Requires disk I/O, free space manager, statistics, and format version.

```rust
pub fn new( disk_io: Arc<RwLock<DiskIO>>, free_space: Arc<RwLock<FreeSpaceManager>>, stats: Arc<Statistics>, format_version: u32, ) -> Self
```

--------------------------------

### Get Record Reference Count

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/record/struct.Record.html

Returns the current reference count of the Record.

```rust
pub fn ref_count(&self) -> u32
```

--------------------------------

### Create an empty Bytes instance

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Demonstrates how to create a new, empty Bytes instance. Use this when you need a Bytes buffer that initially contains no data.

```rust
use bytes::Bytes;

let b = Bytes::new();
assert!(b.is_empty());
```

--------------------------------

### Iterate Over Slice Elements

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Returns an iterator that yields all items in the slice from start to end.

```rust
let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
```

--------------------------------

### try_get_i64_ne

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed 64 bit integer from `self` in native-endian byte order.

```APIDOC
## try_get_i64_ne

### Description
Gets a signed 64 bit integer from `self` in native-endian byte order.

### Signature
`fn try_get_i64_ne(&mut self) -> Result<i64, TryGetError>`
```

--------------------------------

### Time-To-Live (TTL) Support

Source: https://docs.rs/feoxdb

Demonstrates how to enable and manage Time-To-Live (TTL) for keys in FeoxDB. This includes setting expiration times, checking remaining TTL, extending it, and making keys permanent.

```APIDOC
## Time-To-Live (TTL) Support

### Description
Enable and manage Time-To-Live (TTL) for keys. This includes setting expiration times, checking remaining TTL, extending it, and making keys permanent.

### Usage
```rust
use feoxdb::FeoxStore;

// Enable TTL feature via builder
let store = FeoxStore::builder()
    .enable_ttl(true)
    .build()?;

// Set key to expire after 60 seconds
store.insert_with_ttl(b"session:123", b"user_session", 60)?;

// Check remaining TTL
if let Some(ttl) = store.get_ttl(b"session:123")? {
    println!("Session expires in {} seconds", ttl);
}

// Extend TTL to 120 seconds
store.update_ttl(b"session:123", 120)?;

// Remove TTL (make permanent)
store.persist(b"session:123")?;
```
```

--------------------------------

### Create and Slice Bytes

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Demonstrates creating a Bytes object from a string literal and then slicing it to extract a portion of the data. Also shows splitting the Bytes into two separate instances.

```rust
use bytes::Bytes;

let mut mem = Bytes::from("Hello world");
let a = mem.slice(0..5);

assert_eq!(a, "Hello");

let b = mem.split_to(6);

assert_eq!(mem, "world");
assert_eq!(b, "Hello ");
```

--------------------------------

### try_get_i64_le

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed 64 bit integer from `self` in little-endian byte order.

```APIDOC
## try_get_i64_le

### Description
Gets a signed 64 bit integer from `self` in little-endian byte order.

### Signature
`fn try_get_i64_le(&mut self) -> Result<i64, TryGetError>`
```

--------------------------------

### DiskIO::new Constructor

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/io/struct.DiskIO.html

Creates a new DiskIO instance. Requires an Arc<File> and a boolean to enable direct I/O.

```rust
pub fn new(file: Arc<File>, use_direct_io: bool) -> Result<Self>
```

--------------------------------

### try_get_i64

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed 64 bit integer from `self` in big-endian byte order.

```APIDOC
## try_get_i64

### Description
Gets a signed 64 bit integer from `self` in big-endian byte order.

### Signature
`fn try_get_i64(&mut self) -> Result<i64, TryGetError>`
```

--------------------------------

### CloneToUninit (Nightly Experimental)

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/cache/struct.CacheStats.html

Performs copy-assignment from self to an uninitialized memory location. This is an experimental API.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### try_get_u64_ne

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned 64 bit integer from `self` in native-endian byte order.

```APIDOC
## try_get_u64_ne

### Description
Gets an unsigned 64 bit integer from `self` in native-endian byte order.

### Signature
`fn try_get_u64_ne(&mut self) -> Result<u64, TryGetError>`
```

--------------------------------

### try_get_u64_le

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned 64 bit integer from `self` in little-endian byte order.

```APIDOC
## try_get_u64_le

### Description
Gets an unsigned 64 bit integer from `self` in little-endian byte order.

### Signature
`fn try_get_u64_le(&mut self) -> Result<u64, TryGetError>`
```

--------------------------------

### Default StoreBuilder Initialization

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/builder/struct.StoreBuilder.html

Initializes a StoreBuilder with its default values. This is equivalent to calling `StoreBuilder::default()`.

```rust
let builder = StoreBuilder::default();
```

--------------------------------

### try_get_u64

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned 64 bit integer from `self` in big-endian byte order.

```APIDOC
## try_get_u64

### Description
Gets an unsigned 64 bit integer from `self` in big-endian byte order.

### Signature
`fn try_get_u64(&mut self) -> Result<u64, TryGetError>`
```

--------------------------------

### try_get_i32_ne

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed 32 bit integer from `self` in native-endian byte order.

```APIDOC
## try_get_i32_ne

### Description
Gets a signed 32 bit integer from `self` in native-endian byte order.

### Signature
`fn try_get_i32_ne(&mut self) -> Result<i32, TryGetError>`
```

--------------------------------

### try_get_i32_le

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed 32 bit integer from `self` in little-endian byte order.

```APIDOC
## try_get_i32_le

### Description
Gets a signed 32 bit integer from `self` in little-endian byte order.

### Signature
`fn try_get_i32_le(&mut self) -> Result<i32, TryGetError>`
```

--------------------------------

### starts_with

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Determines if the slice begins with a specified prefix slice.

```APIDOC
## pub fn starts_with(&self, needle: &[T]) -> bool

### Description
Returns `true` if `needle` is a prefix of the slice or equal to the slice.

### Method
`starts_with`

### Parameters
#### Path Parameters
- **needle** (&[T]) - Required - The slice to check as a prefix.

### Response
#### Success Response
- **bool** - `true` if the slice starts with the `needle`, `false` otherwise.

### Request Example
```rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));
```

Always returns `true` if `needle` is an empty slice:
```rust
let v = &[10, 40, 30];
assert!(v.starts_with(&[]));
let v: &[u8] = &[];
assert!(v.starts_with(&[]));
```
```

--------------------------------

### try_get_i32

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed 32 bit integer from `self` in big-endian byte order.

```APIDOC
## try_get_i32

### Description
Gets a signed 32 bit integer from `self` in big-endian byte order.

### Signature
`fn try_get_i32(&mut self) -> Result<i32, TryGetError>`
```

--------------------------------

### WriteBuffer::new

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/storage/write_buffer/struct.WriteBuffer.html

Constructs a new WriteBuffer instance. It requires disk I/O, free space manager, statistics, and the format version.

```APIDOC
## WriteBuffer::new

### Description
Constructs a new WriteBuffer instance. It requires disk I/O, free space manager, statistics, and the format version.

### Signature
```rust
pub fn new( disk_io: Arc<RwLock<DiskIO>>, free_space: Arc<RwLock<FreeSpaceManager>>, stats: Arc<Statistics>, format_version: u32, ) -> Self
```
```

--------------------------------

### try_get_u32_ne

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned 32 bit integer from `self` in native-endian byte order.

```APIDOC
## try_get_u32_ne

### Description
Gets an unsigned 32 bit integer from `self` in native-endian byte order.

### Signature
`fn try_get_u32_ne(&mut self) -> Result<u32, TryGetError>`
```

--------------------------------

### Trim Prefix Example for Bytes

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Demonstrates how to remove a prefix from a byte slice using `trim_prefix`. This function is part of an experimental feature and requires nightly Rust. It handles cases where the prefix is present, absent, or matches the entire slice.

```rust
#![feature(trim_prefix_suffix)]

let v = &[10, 40, 30];

// Prefix present - removes it
assert_eq!(v.trim_prefix(&[10]), &[40, 30][..]);
assert_eq!(v.trim_prefix(&[10, 40]), &[30][..]);
assert_eq!(v.trim_prefix(&[10, 40, 30]), &[][..]);

// Prefix absent - returns original slice
assert_eq!(v.trim_prefix(&[50]), &[10, 40, 30][..]);
assert_eq!(v.trim_prefix(&[10, 50]), &[10, 40, 30][..]);

let prefix : &str = "he";
assert_eq!(b"hello".trim_prefix(prefix.as_bytes()), b"llo".as_ref());
```

--------------------------------

### try_get_u32_le

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned 32 bit integer from `self` in little-endian byte order.

```APIDOC
## try_get_u32_le

### Description
Gets an unsigned 32 bit integer from `self` in little-endian byte order.

### Signature
`fn try_get_u32_le(&mut self) -> Result<u32, TryGetError>`
```

--------------------------------

### StoreBuilder Methods

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/store/builder/struct.StoreBuilder.html

Methods available on the StoreBuilder to configure FeoxStore parameters.

```APIDOC
## StoreBuilder

Builder for creating FeoxStore with custom configuration. Provides a fluent interface for configuring store parameters.

### Methods

#### `new()`

Creates a new instance of `StoreBuilder`.

#### `device_path(path: impl Into<String>) -> Self`

Set the device path for persistent storage. When set, data will be persisted to disk asynchronously. If not set, the store operates in memory-only mode.

#### `file_size(size: u64) -> Self`

Set the initial file size for new persistent stores (in bytes). When creating a new persistent store file, it will be pre-allocated to this size for better performance. If not set, defaults to 1GB. This option is ignored for existing files.

##### Example
```
use feoxdb::FeoxStore;

let store = FeoxStore::builder()
    .device_path("/path/to/data.feox")
    .file_size(10 * 1024 * 1024 * 1024)  // 10GB
    .build()?;
```

#### `max_memory(limit: usize) -> Self`

Set the maximum memory limit (in bytes). The store will start evicting entries when this limit is approached. Default: 1GB

#### `no_memory_limit() -> Self`

Remove memory limit. Use with caution as the store can grow unbounded.

#### `hash_bits(bits: u32) -> Self`

Set number of hash bits (determines hash table size). More bits = larger hash table = better performance for large datasets. Default: 18 (256K buckets)

#### `enable_caching(enable: bool) -> Self`

Enable or disable caching. When enabled, frequently accessed values are kept in memory even after being written to disk. Uses CLOCK eviction algorithm.

#### `enable_ttl(enable: bool) -> Self`

Enable or disable TTL (Time-To-Live) functionality. When disabled (default), TTL operations will return errors and no background cleaner runs. When enabled, keys can have expiry times and a background cleaner removes expired keys. Default: false (disabled for optimal performance)

#### `enable_ttl_cleaner(enable: bool) -> Self`

Enable or disable TTL sweeper. When enabled, a background thread periodically removes expired keys. Note: This method is deprecated in favor of `enable_ttl()`.

#### `ttl_sweeper_config(sample_size: usize, threshold: f32, max_time_ms: u64, interval_ms: u64) -> Self`

Configure TTL sweeper with custom parameters.

##### Arguments

* `sample_size` - Keys to check per batch
* `threshold` - Continue if >threshold expired (0.0-1.0)
* `max_time_ms` - Max milliseconds per cleaning run
* `interval_ms` - Sleep between runs

#### `build() -> Result<FeoxStore>`

Build the FeoxStore.
```

--------------------------------

### try_get_u32

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned 32 bit integer from `self` in big-endian byte order.

```APIDOC
## try_get_u32

### Description
Gets an unsigned 32 bit integer from `self` in big-endian byte order.

### Signature
`fn try_get_u32(&mut self) -> Result<u32, TryGetError>`
```

--------------------------------

### Inserting into Sorted Vector with partition_point

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Demonstrates how to efficiently insert an element into a sorted vector while maintaining its sorted order using `partition_point`. This method helps minimize element shifting.

```rust
let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
let num = 42;
let idx = s.partition_point(|&x| x <= num);
// If `num` is unique, `s.partition_point(|&x| x < num)` (with `<`) is equivalent to
// `s.binary_search(&num).unwrap_or_else(|x| x)`, but using `<=` will allow `insert`
// to shift less elements.
s.insert(idx, num);
assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);
```

--------------------------------

### try_get_i16_ne

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed 16 bit integer from `self` in native-endian byte order.

```APIDOC
## try_get_i16_ne

### Description
Gets a signed 16 bit integer from `self` in native-endian byte order.

### Signature
`fn try_get_i16_ne(&mut self) -> Result<i16, TryGetError>`
```

--------------------------------

### try_get_i16_le

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed 16 bit integer from `self` in little-endian byte order.

```APIDOC
## try_get_i16_le

### Description
Gets a signed 16 bit integer from `self` in little-endian byte order.

### Signature
`fn try_get_i16_le(&mut self) -> Result<i16, TryGetError>`
```

--------------------------------

### Record Constructors

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/record/struct.Record.html

Provides methods for creating new Record instances with various configurations for key, value, timestamp, and TTL.

```APIDOC
### impl Record

#### pub fn new(key: Vec<u8>, value: Vec<u8>, timestamp: u64) -> Self

#### pub fn new_with_timestamp(key: Vec<u8>, value: Vec<u8>, timestamp: u64) -> Self

#### pub fn new_with_timestamp_ttl( key: Vec<u8>, value: Vec<u8>, timestamp: u64, ttl_expiry: u64, ) -> Self

#### pub fn new_from_bytes(key: Vec<u8>, value: Bytes, timestamp: u64) -> Self
Create a new record from a Bytes value (zero-copy)

#### pub fn new_from_bytes_with_ttl( key: Vec<u8>, value: Bytes, timestamp: u64, ttl_expiry: u64, ) -> Self
Create a new record from Bytes with TTL
```

--------------------------------

### Insert and Update with Timestamps in FeoxStore

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/index.html

Shows how to insert a key-value pair with an explicit timestamp and how updates with higher timestamps succeed while those with lower timestamps fail, ensuring consistency.

```rust
// Insert with explicit timestamp
store.insert_with_timestamp(b"key", b"value_v1", Some(100))?;

// Update with higher timestamp succeeds
store.insert_with_timestamp(b"key", b"value_v2", Some(200))?;

// Update with lower timestamp fails
let result = store.insert_with_timestamp(b"key", b"value_v3", Some(150));
assert!(result.is_err());  // OlderTimestamp error
```

--------------------------------

### try_get_i16

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets a signed 16 bit integer from `self` in big-endian byte order.

```APIDOC
## try_get_i16

### Description
Gets a signed 16 bit integer from `self` in big-endian byte order.

### Signature
`fn try_get_i16(&mut self) -> Result<i16, TryGetError>`
```

--------------------------------

### Initialize Record from Pointer

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/core/record/struct.Record.html

Provides methods for initializing and managing memory for Record instances via raw pointers.

```rust
const ALIGN: usize
```

```rust
type Init = T
```

```rust
unsafe fn init(init: <T as Pointable>::Init) -> usize
```

```rust
unsafe fn deref<'a>(ptr: usize) -> &'a T
```

```rust
unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T
```

```rust
unsafe fn drop(ptr: usize)
```

--------------------------------

### try_get_u16_ne

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned 16 bit integer from `self` in native-endian byte order.

```APIDOC
## try_get_u16_ne

### Description
Gets an unsigned 16 bit integer from `self` in native-endian byte order.

### Signature
`fn try_get_u16_ne(&mut self) -> Result<u16, TryGetError>`
```

--------------------------------

### try_get_u16_le

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned 16 bit integer from `self` in little-endian byte order.

```APIDOC
## try_get_u16_le

### Description
Gets an unsigned 16 bit integer from `self` in little-endian byte order.

### Signature
`fn try_get_u16_le(&mut self) -> Result<u16, TryGetError>`
```

--------------------------------

### Perform Atomic Counter Operations in FeoxStore

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/index.html

Shows how to initialize a counter, and then atomically increment or decrement its value. The counter must be an 8-byte i64 value.

```rust
use feoxdb::FeoxStore;

let store = FeoxStore::new(None)?;

// Initialize a counter (must be 8-byte i64 value)
let zero: i64 = 0;
store.insert(b"counter:visits", &zero.to_le_bytes())?;

// Increment atomically
let new_value = store.atomic_increment(b"counter:visits", 1)?;
assert_eq!(new_value, 1);

// Increment by 5
let new_value = store.atomic_increment(b"counter:visits", 5)?;
assert_eq!(new_value, 6);

// Decrement by 2  
let new_value = store.atomic_increment(b"counter:visits", -2)?;
assert_eq!(new_value, 4);
```

--------------------------------

### try_get_u16

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Gets an unsigned 16 bit integer from `self` in big-endian byte order.

```APIDOC
## try_get_u16

### Description
Gets an unsigned 16 bit integer from `self` in big-endian byte order.

### Signature
`fn try_get_u16(&mut self) -> Result<u16, TryGetError>`
```

--------------------------------

### Finding Range of Matching Items with partition_point

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Shows how to use `partition_point` in conjunction with `binary_search` to find the range of elements equal to a specific value in a sorted slice. This is useful for determining the bounds of duplicate values.

```rust
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

let low = s.partition_point(|x| x < &1);
assert_eq!(low, 1);
let high = s.partition_point(|x| x <= &1);
assert_eq!(high, 5);
let r = s.binary_search(&1);
assert!((low..high).contains(&r.unwrap()));

assert!(s[..low].iter().all(|&x| x < 1));
assert!(s[low..high].iter().all(|&x| x == 1));
assert!(s[high..].iter().all(|&x| x > 1));

// For something not found, the "range" of equal items is empty
assert_eq!(s.partition_point(|x| x < &11), 9);
assert_eq!(s.partition_point(|x| x <= &11), 9);
assert_eq!(s.binary_search(&11), Err(9));
```

--------------------------------

### AsRef<[u8]> Implementation

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/struct.Bytes.html

Provides a way to get a shared reference to the underlying byte slice.

```APIDOC
## impl AsRef<[u8]> for Bytes

### fn as_ref(&self) -> &[u8]

#### Description
Converts this type into a shared reference of the (usually inferred) input type.

#### Returns
- `&[u8]`: A shared reference to the byte slice.
```

--------------------------------

### Execute Compare-and-Swap (CAS) Operations in FeoxStore

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/index.html

Illustrates how to use compare-and-swap to atomically update a value only if it matches an expected value. This is useful for optimistic concurrency control.

```rust
use feoxdb::FeoxStore;

let store = FeoxStore::new(None)?;

// Insert initial configuration
store.insert(b"config:version", b"v1.0")?;

// Atomically update only if value matches expected
let swapped = store.compare_and_swap(b"config:version", b"v1.0", b"v2.0")?;
assert!(swapped); // Returns true if swap succeeded

// This CAS will fail because current value is now "v2.0"
let swapped = store.compare_and_swap(b"config:version", b"v1.0", b"v3.0")?;
assert!(!swapped); // Returns false if current value didn't match

// CAS enables optimistic concurrency control for safe updates
// Multiple threads can attempt CAS - only one will succeed
```

--------------------------------

### Get the current length of the AlignedBuffer

Source: https://docs.rs/feoxdb/0.5.0/feoxdb/utils/allocator/struct.AlignedBuffer.html

Returns the number of bytes currently in use within the buffer.

```rust
pub fn len(&self) -> usize
```
Tokens:
Raw