Getting Started

Learn how to integrate CRDTosphere into your embedded systems project

Installation

Add to Cargo.toml

[dependencies]
crdtosphere = { version = "0.1.0", features = ["hardware-atomic", "automotive"] }

Import the Prelude

use crdtosphere::prelude::*;

Basic Usage

Creating a Counter

use crdtosphere::prelude::*;

fn main() -> Result<(), CRDTError> {
    // Create a grow-only counter with node ID 1
    let mut counter = GCounter::<DefaultConfig>::new(1);
    
    // Increment the counter
    counter.increment()?;
    counter.increment()?;
    
    println!("Counter value: {}", counter.value()); // Output: 2
    
    Ok(())
}

Working with Registers

use crdtosphere::prelude::*;

fn main() -> Result<(), CRDTError> {
    // Create a last-writer-wins register
    let mut register = LWWRegister::<&str, DefaultConfig>::new(1);
    
    // Set a value with timestamp
    register.set("Hello, World!", 1000)?;
    
    // Get the current value
    if let Some(value) = register.get() {
        println!("Register value: {}", value);
    }
    
    Ok(())
}

Using Sets

use crdtosphere::prelude::*;

fn main() -> Result<(), CRDTError> {
    // Create a grow-only set
    let mut set = GSet::<u32, DefaultConfig>::new();
    
    // Add elements
    set.insert(1)?;
    set.insert(2)?;
    set.insert(3)?;
    
    // Check membership
    println!("Contains 2: {}", set.contains(&2)); // true
    println!("Set size: {}", set.len()); // 3
    
    Ok(())
}

Configuration

Custom Configuration

use crdtosphere::prelude::*;

// Define custom configuration for your embedded system
#[derive(Debug, Clone)]
struct EmbeddedConfig;

impl CRDTConfig for EmbeddedConfig {
    const MAX_NODES: usize = 8;        // Maximum 8 nodes
    const MAX_ELEMENTS: usize = 64;    // Maximum 64 elements per CRDT
    const ENABLE_VALIDATION: bool = true;
    const ENABLE_METRICS: bool = false; // Disable for performance
}

fn main() -> Result<(), CRDTError> {
    // Use custom configuration
    let mut counter = GCounter::<EmbeddedConfig>::new(1);
    counter.increment()?;
    
    Ok(())
}

Memory-Bounded Configuration

use crdtosphere::prelude::*;

// Ultra-constrained configuration for microcontrollers
#[derive(Debug, Clone)]
struct MicroConfig;

impl CRDTConfig for MicroConfig {
    const MAX_NODES: usize = 4;
    const MAX_ELEMENTS: usize = 16;
    const ENABLE_VALIDATION: bool = false; // Disable for minimal memory
    const ENABLE_METRICS: bool = false;
}

fn main() -> Result<(), CRDTError> {
    // Memory usage is known at compile time
    let mut set = GSet::<u8, MicroConfig>::new();
    
    // All operations are bounded
    for i in 0..10 {
        set.insert(i)?;
    }
    
    Ok(())
}

Merging CRDTs

Distributed Counter Example

use crdtosphere::prelude::*;

fn main() -> Result<(), CRDTError> {
    // Create counters on different nodes
    let mut node1_counter = GCounter::<DefaultConfig>::new(1);
    let mut node2_counter = GCounter::<DefaultConfig>::new(2);
    
    // Each node increments independently
    node1_counter.increment()?; // Node 1: 1
    node1_counter.increment()?; // Node 1: 2
    
    node2_counter.increment()?; // Node 2: 1
    node2_counter.increment()?; // Node 2: 2
    node2_counter.increment()?; // Node 2: 3
    
    println!("Node 1 count: {}", node1_counter.value()); // 2
    println!("Node 2 count: {}", node2_counter.value()); // 3
    
    // Merge the counters (commutative and idempotent)
    node1_counter.merge(&node2_counter)?;
    
    println!("Merged count: {}", node1_counter.value()); // 5
    
    Ok(())
}

Error Handling

Handling CRDT Errors

use crdtosphere::prelude::*;

fn main() {
    let mut set = GSet::<u32, DefaultConfig>::new();
    
    // Handle potential errors
    match set.insert(42) {
        Ok(()) => println!("Successfully inserted 42"),
        Err(CRDTError::CapacityExceeded) => {
            println!("Set is full, cannot insert more elements");
        }
        Err(CRDTError::InvalidOperation) => {
            println!("Invalid operation attempted");
        }
        Err(e) => println!("Other error: {:?}", e),
    }
}

Safety-Critical Error Handling

use crdtosphere::prelude::*;

fn safety_critical_operation() -> Result<(), CRDTError> {
    let mut register = LWWRegister::<f32, DefaultConfig>::new(1);
    
    // Validate input before setting
    let sensor_value = 25.5;
    if sensor_value < 0.0 || sensor_value > 100.0 {
        return Err(CRDTError::InvalidOperation);
    }
    
    // Set with current timestamp
    let timestamp = get_current_timestamp();
    register.set(sensor_value, timestamp)?;
    
    Ok(())
}

fn get_current_timestamp() -> u64 {
    // Implementation depends on your embedded platform
    1000 // Placeholder
}

Feature Flags

hardware-atomic

Enable lock-free operations using hardware atomic primitives for multi-core systems.

hardware-atomic = ["crdtosphere/hardware-atomic"]

automotive

ASIL-compliant CRDTs for automotive safety systems.

automotive = ["crdtosphere/automotive"]

robotics

Specialized CRDTs for robot coordination and mapping.

robotics = ["crdtosphere/robotics"]

iot

IoT device registries and sensor network CRDTs.

iot = ["crdtosphere/iot"]

Next Steps

📚

Learn CRDT Types

Explore the different CRDT types available and learn when to use each one.

View CRDT Types →

💻

Try Examples

See practical examples and real-world usage patterns for different scenarios.

View Examples →

🌐

Domain Applications

Discover specialized CRDTs for automotive, robotics, IoT, and industrial use cases.

Explore Domains →