Struct EmbeddedEngine 

pub struct EmbeddedEngine { /* private fields */ }

Embedded d-engine with automatic lifecycle management.

Provides high-level KV API for embedded usage:

• start() / start_with() - Initialize and spawn node
• wait_ready() - Wait for leader election
• client() - Get local KV client
• stop() - Graceful shutdown

Example

use d_engine::EmbeddedEngine;
use std::time::Duration;

let engine = EmbeddedEngine::start().await?;
engine.wait_ready(Duration::from_secs(5)).await?;

let client = engine.client();
client.put(b"key", b"value").await?;

engine.stop().await?;

Implementations

impl EmbeddedEngine

pub async fn start() -> Result<EmbeddedEngine, Error>

Start engine with configuration from environment.

Reads CONFIG_PATH environment variable or uses default configuration. Data directory is determined by config’s cluster.db_root_dir setting.

Example

// Set config path via environment variable
std::env::set_var("CONFIG_PATH", "/etc/d-engine/production.toml");

let engine = EmbeddedEngine::start().await?;
engine.wait_ready(Duration::from_secs(5)).await?;

pub async fn start_with(config_path: &str) -> Result<EmbeddedEngine, Error>

Start engine with explicit configuration file.

Reads configuration from specified file path. Data directory is determined by config’s cluster.db_root_dir setting.

Arguments

• config_path: Path to configuration file (e.g. “d-engine.toml”)

Example

let engine = EmbeddedEngine::start_with("config/node1.toml").await?;
engine.wait_ready(Duration::from_secs(5)).await?;

pub async fn start_custom<SE, SM>( storage_engine: Arc<SE>, state_machine: Arc<SM>, config_path: Option<&str>, ) -> Result<EmbeddedEngine, Error>

where SE: StorageEngine + Debug + 'static, SM: StateMachine + Debug + 'static,

Start engine with custom storage and state machine.

Advanced API for users providing custom storage implementations.

Arguments

• config_path: Optional path to configuration file
• storage_engine: Custom storage engine implementation
• state_machine: Custom state machine implementation

Example

let storage = Arc::new(MyCustomStorage::new()?);
let sm = Arc::new(MyCustomStateMachine::new()?);
let engine = EmbeddedEngine::start_custom(storage, sm, None).await?;

pub async fn wait_ready(&self, timeout: Duration) -> Result<LeaderInfo, Error>

Wait for leader election to complete.

Blocks until a leader has been elected in the cluster. Event-driven notification (no polling), <1ms latency.

Timeout

• Single-node: Returns immediately (<100ms)
• Multi-node: May take seconds depending on network

Example

let engine = EmbeddedEngine::start().await?;
let leader = engine.wait_ready(Duration::from_secs(10)).await?;
println!("Leader elected: {} (term {})", leader.leader_id, leader.term);

pub fn leader_change_notifier(&self) -> Receiver<Option<LeaderInfo>>

Subscribe to leader change notifications.

Returns a receiver that will be notified whenever:

• First leader is elected
• Leader changes (re-election)
• No leader exists (during election)

Performance

Event-driven notification (no polling), <1ms latency

Example

let mut leader_rx = engine.leader_change_notifier();
tokio::spawn(async move {
    while leader_rx.changed().await.is_ok() {
        match leader_rx.borrow().as_ref() {
            Some(info) => println!("Leader: {} (term {})", info.leader_id, info.term),
            None => println!("No leader"),
        }
    }
});

pub fn client(&self) -> &LocalKvClient

Get a reference to the local KV client.

The client is available immediately after start(), but requests will only succeed after wait_ready() completes.

Example

let engine = EmbeddedEngine::start().await?;
engine.wait_ready(Duration::from_secs(5)).await?;
let client = engine.client();
client.put(b"key", b"value").await?;

pub fn watch(&self, key: impl AsRef<[u8]>) -> Result<WatcherHandle, Error>

Register a watcher for a specific key.

Returns a handle that receives watch events via an mpsc channel. The watcher is automatically unregistered when the handle is dropped.

Arguments

• key - The exact key to watch

Returns

• Result<WatcherHandle> - Handle for receiving events

Example

let engine = EmbeddedEngine::start().await?;
let mut handle = engine.watch(b"mykey")?;
while let Some(event) = handle.receiver_mut().recv().await {
    println!("Key changed: {:?}", event);
}

pub async fn stop(self) -> Result<(), Error>

Gracefully stop the embedded engine.

This method:

1. Sends shutdown signal to node
2. Waits for node.run() to complete
3. Propagates any errors from node execution

Errors

Returns error if node encountered issues during shutdown.

Example

engine.stop().await?;

Trait Implementations

impl Drop for EmbeddedEngine

fn drop(&mut self)

Executes the destructor for this type.