Module maybe_future

Conditional future types for async/sync compatibility.

This module provides the MaybeFuture type, which has different definitions depending on whether the async feature is enabled. This allows the same API to work seamlessly in both synchronous and asynchronous contexts.

⚠️ Feature-Dependent Type Definition

Critical: MaybeFuture is implemented differently based on feature flags:

Feature State	Type Definition	Behavior
No async	type MaybeFuture<'a, T, E> = Result<T, E>	Simple type alias, zero overhead
With async	enum MaybeFuture<'a, T, E> { Result(..), Future(..) }	Can hold immediate results or futures

Documentation Generation

Important: When building documentation with --all-features (as on docs.rs), only the async variant is shown because the async feature is enabled. The synchronous variant (simple type alias) is only visible when building docs without the async feature.

• On docs.rs: Shows the enum variant with Result and Future cases
• Without async feature: MaybeFuture is just a type alias for Result<T, E>
• Each definition is marked with appropriate #[cfg(...)] attributes

Usage Guidelines

For Library Authors

When returning MaybeFuture from your APIs:

use cel_cxx::MaybeFuture;

// This signature works regardless of async feature
fn your_function() -> MaybeFuture<'_, YourType, YourError> {
    // Implementation varies by feature
}

For Library Users

When consuming MaybeFuture values:

// Sync mode (no async feature)
#[cfg(not(feature = "async"))]
fn example_usage<'a>(maybe_future: MaybeFuture<'a, i32, Error>) -> Result<(), Error> {
    let result = maybe_future?; // It's just Result<T, E>
    Ok(())
}

// Async mode (with async feature)
#[cfg(feature = "async")]
async fn example_usage<'a>(maybe_future: MaybeFuture<'a, i32, Error>) -> Result<(), Error> {
    match maybe_future {
        MaybeFuture::Result(result) => {
            let value = result?; // Immediate result
        }
        MaybeFuture::Future(future) => {
            let result = future.await?; // Await the future
        }
    }
    Ok(())
}

Examples

Synchronous mode (without async feature)

use cel_cxx::{Error, MaybeFuture};

// MaybeFuture is just Result<T, E> in sync mode
let result: MaybeFuture<'_, i32, Error> = Ok(42);
assert_eq!(result.unwrap(), 42);

Asynchronous mode (with async feature)

use cel_cxx::MaybeFuture;

// Can hold either immediate results or futures
let immediate: MaybeFuture<'_, i32, &str> = MaybeFuture::Result(Ok(42));
let future_result: MaybeFuture<'_, i32, &str> = MaybeFuture::Future(
    Box::pin(async { Ok(100) })
);

assert!(immediate.is_result());
assert!(future_result.is_future());

Type Definitions

Enums

MaybeFutureasync

A type that can represent either an immediate result or a future.