Struct VibeEngine 

pub struct VibeEngine {
    pub ctx: Arc<VibeEngineContext>,
    /* private fields */
}

Main entry point for creating and driving a vibe-ready runtime. Main runtime facade for task execution, logging, and SDK context access.

Fields

ctx: Arc<VibeEngineContext>

Shared engine context for advanced integrations that need low-level clients.

Implementations

impl VibeEngine

pub fn capabilities(&self) -> VibeCapabilities

Returns compile-time capabilities enabled for this crate build.

Returns

A VibeCapabilities snapshot describing enabled storage, logging, and platform capabilities.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
let capabilities = engine.capabilities();
assert_eq!(capabilities.log_store, cfg!(feature = "log-diesel"));

pub fn state(&self) -> VibeEngineState

Returns the current engine lifecycle state.

Returns

A VibeEngineState value such as VibeEngineState::Running or VibeEngineState::Closed.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeEngineState, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
assert_eq!(engine.state(), VibeEngineState::Running);

pub fn executor(&self) -> VibeEngineExecutor

Clones the engine executor for advanced task and callback integrations.

Returns

A cheap clone of VibeEngineExecutor sharing the engine runtime.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
let executor = engine.executor();
executor.post(async {})?;

pub fn store(&self) -> VibeKvStore

Creates a high-level key-value store facade bound to this engine.

Returns

A VibeKvStore that performs blocking-friendly operations through the engine executor.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
let store = engine.store();
store.set_str("theme", "dark")?;

pub fn invoke<T, F>(&self, future: T) -> Result<F, VibeEngineError>

where T: Future<Output = F> + Send + 'static, F: Send + 'static,

Runs a future on the engine runtime and waits for its result.

Use this for short async operations where the caller needs the return value synchronously.

Returns

Ok(F) with the future output, or VibeEngineError if the engine is not running or the task cannot be delivered.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
let answer = engine.invoke(async { 42 })?;
assert_eq!(answer, 42);

pub fn post<T>(&self, future: T)

where T: Future<Output = ()> + Send + 'static,

Posts a fire-and-forget future to the engine runtime.

The method logs failures instead of returning them, making it suitable for background work where the caller does not need a result.

Returns

This method returns (); delivery errors are written to the SDK log.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
engine.post(async {
    // perform background work here
});

pub fn cb_pool_once<F, R>(&self, cb: F) -> impl FnOnce(R)

where F: FnOnce(R) + Send + 'static, R: Send + 'static,

Wraps a one-argument callback so it runs on the engine callback pool.

Returns

A FnOnce(R) wrapper that schedules cb on the callback thread pool.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
let callback = engine.cb_pool_once(|value: i32| assert_eq!(value, 7));
callback(7);

pub fn cb_pool_once2<F, R1, R2>(&self, cb: F) -> impl FnOnce(R1, R2)

where F: FnOnce(R1, R2) + Send + 'static, R1: Send + 'static, R2: Send + 'static,

Wraps a two-argument callback so it runs on the engine callback pool.

Returns

A FnOnce(R1, R2) wrapper that schedules cb on the callback thread pool.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
let callback = engine.cb_pool_once2(|left: i32, right: i32| assert_eq!(left + right, 3));
callback(1, 2);

impl VibeEngine

pub fn post_with_priority<F>( &self, name: impl Into<String>, priority: VibeTaskPriority, future: F, ) -> Result<VibeTaskHandle, VibeEngineError>

where F: Future<Output = ()> + Send + 'static,

Posts a future to a dedicated priority lane.

Tasks submitted to a higher priority lane run before lower-priority tasks queued at the same time. Returns a VibeTaskHandle that can be cancelled or awaited.

pub fn schedule_after<F, Fut>( &self, name: impl Into<String>, delay: Duration, builder: F, ) -> Result<VibeTaskHandle, VibeEngineError>

where F: FnOnce(VibeCancellationToken) -> Fut + Send + 'static, Fut: Future<Output = ()> + Send + 'static,

Schedule a one-shot task to run after delay.

The builder receives a VibeCancellationToken so the user task can abort cooperatively when the handle is cancelled.

pub fn schedule_every<F, Fut>( &self, name: impl Into<String>, period: Duration, builder: F, ) -> Result<VibeTaskHandle, VibeEngineError>

where F: FnMut(VibeCancellationToken) -> Fut + Send + 'static, Fut: Future<Output = ()> + Send + 'static,

Schedule a periodic task. The builder is invoked once every period until the returned handle is cancelled or the engine is destroyed.

pub fn tasks(&self) -> VibeTaskPanel

Diagnostic panel exposing live snapshots of scheduler-tracked tasks.

impl VibeEngine

pub fn create(config: VibeEngineConfig) -> Result<Self, VibeEngineError>

Creates an engine with a Tokio runtime owned by vibe-ready.

Returns

Ok(VibeEngine) when configuration is valid and storage/logging backends open successfully, otherwise VibeEngineError.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().app_name("demo").build())?;
engine.destroy_with_timeout(std::time::Duration::from_secs(1))?;

pub fn create_with_runtime_handle( config: VibeEngineConfig, runtime_handle: Handle, ) -> Result<Self, VibeEngineError>

Creates an engine using a Tokio runtime owned by the host application.

The host runtime must stay alive for the lifetime of the engine. Destroying the engine closes vibe-ready resources, but does not shut down this runtime.

Returns

Ok(VibeEngine) bound to runtime_handle, or VibeEngineError if validation or backend initialization fails.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let runtime = tokio::runtime::Runtime::new().expect("create runtime");
let engine = VibeEngine::create_with_runtime_handle(
    VibeEngineConfig::builder().app_name("hosted").build(),
    runtime.handle().clone(),
)?;
engine.destroy_with_timeout(std::time::Duration::from_secs(1))?;

pub fn destroy_with_timeout( &self, timeout: Duration, ) -> Result<(), VibeEngineError>

Destroys the engine and waits up to timeout for resources to close.

Returns

Ok(()) when shutdown finishes or the engine is already closed; VibeEngineError on timeout, runtime, or backend close failures.

Examples

use std::time::Duration;
use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
engine.destroy_with_timeout(Duration::from_secs(2))?;

pub fn destroy<CB>(&self, cb: CB)

where CB: FnOnce(Result<(), VibeEngineError>) + Send + 'static,

Destroys the engine using the default timeout and reports through a callback.

Returns

This method returns () immediately after invoking cb on the callback pool with Result<(), VibeEngineError>.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
engine.destroy(|result| {
    let _ = result;
});

impl VibeEngine

pub fn insert_log( &self, should_output_log: bool, level: LogLevel, tag: String, content: String, )

Inserts a log record into the configured log backend.

Returns

This method returns (); backend write failures are handled by the log subsystem.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeLogLevel, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
engine.insert_log(true, VibeLogLevel::Info, "startup".into(), "ready".into());

impl VibeEngine

pub fn set_log_listener(&self, listener: Option<LogListener>)

Sets or clears the listener that receives emitted log entries.

Returns

This method returns () and schedules listener installation on the engine runtime.

Examples

use vibe_ready::{VibeEngine, VibeEngineConfig, VibeResult};

let engine = VibeEngine::create(VibeEngineConfig::builder().build())?;
engine.set_log_listener(Some(Box::new(|info| {
    let _ = info;
})));
engine.set_log_listener(None);