Struct async_injector::Injector

pub struct Injector { /* fields omitted */ }

Use for handling injection.

Implementations

impl Injector

pub fn new() -> Self

Create a new injector instance.

pub fn child(&self) -> Injector

Construct a new child injector.

When a child injector is dropped, all associated listeners are cleaned up as well.

pub async fn clear<T, '_>(&'_ self) -> Option<T> where
    T: Clone + Any + Send + Sync, 

Get a value from the injector.

This will cause the clear to be propagated to all streams set up using stream. And for future calls to get to return the updated value.

Examples

use async_injector::Injector;

#[tokio::main]
async fn main() {
    let injector = Injector::new();

    assert_eq!(None, injector.get::<u32>().await);
    injector.update(1u32).await;
    assert_eq!(Some(1u32), injector.get::<u32>().await);
    assert!(injector.clear::<u32>().await.is_some());
    assert_eq!(None, injector.get::<u32>().await);
}

pub async fn clear_key<T, '_>(&'_ self, key: impl AsRef<Key<T>>) -> Option<T> where
    T: Clone + Any + Send + Sync, 

Clear the given value with the given key.

This will cause the clear to be propagated to all streams set up using stream. And for future calls to get to return the updated value.

Examples

use async_injector::{Key, Injector};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let injector = Injector::new();
    let k = Key::<u32>::tagged("foo")?;

    assert_eq!(None, injector.get_key(&k).await);
    injector.update_key(&k, 1u32).await;
    assert_eq!(Some(1u32), injector.get_key(&k).await);
    assert!(injector.clear_key(&k).await.is_some());
    assert_eq!(None, injector.get_key(&k).await);

    Ok(())
}

pub async fn update<T, '_>(&'_ self, value: T) -> Option<T> where
    T: Clone + Any + Send + Sync, 

Set the given value and notify any subscribers.

This will cause the update to be propagated to all streams set up using stream. And for future calls to get to return the updated value.

Examples

use async_injector::Injector;

#[tokio::main]
async fn main() {
    let injector = Injector::new();

    assert_eq!(None, injector.get::<u32>().await);
    injector.update(1u32).await;
    assert_eq!(Some(1u32), injector.get::<u32>().await);
}

pub async fn update_key<T, '_>(
    &'_ self,
    key: impl AsRef<Key<T>>,
    value: T
) -> Option<T> where
    T: Clone + Any + Send + Sync, 

Update the value associated with the given key.

This will cause the update to be propagated to all streams set up using stream. And for future calls to get to return the updated value.

Examples

use async_injector::{Key, Injector};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let injector = Injector::new();
    let k = Key::<u32>::tagged("foo")?;

    assert_eq!(None, injector.get_key(&k).await);
    injector.update_key(&k, 1u32).await;
    assert_eq!(Some(1u32), injector.get_key(&k).await);

    Ok(())
}

pub async fn exists<T, '_>(&'_ self) -> bool where
    T: Clone + Any + Send + Sync, 

Test if a given value exists by type.

Examples

use async_injector::Injector;

#[tokio::main]
async fn main() {
    let injector = Injector::new();

    assert_eq!(false, injector.exists::<u32>().await);
    injector.update(1u32).await;
    assert_eq!(true, injector.exists::<u32>().await);
}

pub async fn exists_key<T, '_>(&'_ self, key: impl AsRef<Key<T>>) -> bool where
    T: Clone + Any + Send + Sync, 

Test if a given value exists by key.

Examples

use async_injector::{Key, Injector};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let injector = Injector::new();
    let k = Key::<u32>::tagged("foo")?;

    assert_eq!(false, injector.exists_key(&k).await);
    injector.update_key(&k, 1u32).await;
    assert_eq!(true, injector.exists_key(&k).await);

    Ok(())
}

pub async fn mutate<T, M, R, '_>(&'_ self, mutator: M) -> Option<R> where
    T: Clone + Any + Send + Sync,
    M: FnMut(&mut T) -> R, 

Mutate the given value by type.

Examples

use async_injector::Injector;

#[tokio::main]
async fn main() {
    let injector = Injector::new();

    injector.update(1u32).await;

    let old = injector.mutate(|value: &mut u32| {
        let old = *value;
        *value += 1;
        old
    }).await;

    assert_eq!(Some(1u32), old);
}

pub async fn mutate_key<T, M, R, '_>(
    &'_ self,
    key: impl AsRef<Key<T>>,
    __arg2: M
) -> Option<R> where
    T: Clone + Any + Send + Sync,
    M: FnMut(&mut T) -> R, 

Mutate the given value by key.

Examples

use async_injector::{Key, Injector};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let injector = Injector::new();
    let k = Key::<u32>::tagged("foo")?;

    injector.update_key(&k, 1u32).await;

    let old = injector.mutate_key(&k, |value| {
        let old = *value;
        *value += 1;
        old
    }).await;

    assert_eq!(Some(1u32), old);
    Ok(())
}

pub async fn get<T, '_>(&'_ self) -> Option<T> where
    T: Clone + Any + Send + Sync, 

Get a value from the injector.

Examples

use async_injector::Injector;

#[tokio::main]
async fn main() {
    let injector = Injector::new();

    assert_eq!(None, injector.get::<u32>().await);
    injector.update(1u32).await;
    assert_eq!(Some(1u32), injector.get::<u32>().await);
}

pub async fn get_key<T, '_>(&'_ self, key: impl AsRef<Key<T>>) -> Option<T> where
    T: Clone + Any + Send + Sync, 

Get a value from the injector with the given key.

Examples

use async_injector::{Injector, Key};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let k1 = Key::<u32>::tagged("foo")?;
    let k2 = Key::<u32>::tagged("bar")?;

    let injector = Injector::new();

    assert_eq!(None, injector.get_key(&k1).await);
    assert_eq!(None, injector.get_key(&k2).await);

    injector.update_key(&k1, 1u32).await;

    assert_eq!(Some(1u32), injector.get_key(&k1).await);
    assert_eq!(None, injector.get_key(&k2).await);

    Ok(())
}

pub async fn stream<T, '_>(&'_ self) -> (Stream<T>, Option<T>) where
    T: Clone + Any + Send + Sync, 

Get an existing value and setup a stream for updates at the same time.

Examples

use async_injector::Injector;
use tokio::stream::StreamExt as _;
use std::error::Error;

#[derive(Clone)]
struct Database;

#[tokio::main]
async fn main() {
    let injector = Injector::new();
    let (mut database_stream, mut database) = injector.stream::<Database>().await;

    // Update the key somewhere else.
    tokio::spawn({
        let injector = injector.clone();

        async move {
            injector.update(Database).await;
        }
    });

    loop {
        tokio::select! {
            Some(update) = database_stream.next() => {
                database = update;
                break;
            }
        }
    }
}

pub async fn stream_key<T, '_>(
    &'_ self,
    key: impl AsRef<Key<T>>
) -> (Stream<T>, Option<T>) where
    T: Clone + Any + Send + Sync, 

Get an existing value and setup a stream for updates at the same time.

Examples

use async_injector::{Injector, Key};
use tokio::stream::StreamExt as _;
use std::error::Error;

#[derive(Clone)]
struct Database;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let injector = Injector::new();
    let db = Key::<Database>::tagged("foo")?;
    let (mut database_stream, mut database) = injector.stream_key(&db).await;

    // Update the key somewhere else.
    tokio::spawn({
        let db = db.clone();
        let injector = injector.clone();

        async move {
            injector.update_key(&db, Database).await;
        }
    });

    loop {
        tokio::select! {
            Some(update) = database_stream.next() => {
                database = update;
                break;
            }
        }
    }

    Ok(())
}

pub async fn var<T, '_>(&'_ self) -> Result<Var<Option<T>>, Error> where
    T: Clone + Any + Send + Sync + Unpin, 

Get a synchronized variable for the given configuration key.

Examples

use async_injector::Injector;
use tokio::stream::StreamExt as _;
use std::error::Error;

#[derive(Clone)]
struct Database;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let injector = Injector::new();

    // Drive variable updates.
    tokio::spawn({
        let injector = injector.clone();

        async move {
            injector.drive().await.expect("injector driver failed");
        }
    });

    let database = injector.var::<Database>().await?;

    assert!(database.read().await.is_none());
    injector.update(Database).await;

    /// Variable updated in the background by the driver.
    while database.read().await.is_none() {
    }

    assert!(database.read().await.is_some());
    Ok(())
}

pub async fn var_key<T, '_>(
    &'_ self,
    key: impl AsRef<Key<T>>
) -> Result<Var<Option<T>>, Error> where
    T: Clone + Any + Send + Sync + Unpin, 

Get a synchronized variable for the given configuration key.

Examples

use async_injector::{Injector, Key};
use tokio::stream::StreamExt as _;
use std::error::Error;

#[derive(Clone)]
struct Database;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let injector = Injector::new();
    let db = Key::<Database>::tagged("foo")?;

    // Drive variable updates.
    tokio::spawn({
        let injector = injector.clone();

        async move {
            injector.drive().await.expect("injector driver failed");
        }
    });

    let database = injector.var_key(&db).await?;

    assert!(database.read().await.is_none());
    injector.update_key(&db, Database).await;

    /// Variable updated in the background by the driver.
    while database.read().await.is_none() {
    }

    assert!(database.read().await.is_some());
    Ok(())
}

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

Run the injector as a future, making sure all asynchronous processes associated with it are driven to completion.

This has to be called for the injector to perform important tasks.

Examples

use async_injector::Injector;
use tokio::stream::StreamExt as _;
use std::error::Error;

#[derive(Clone)]
struct Database;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let injector = Injector::new();

    // Drive variable updates.
    tokio::spawn({
        let injector = injector.clone();

        async move {
            injector.drive().await.expect("injector driver failed");
        }
    });

    let database = injector.var::<Database>().await?;

    assert!(database.read().await.is_none());
    injector.update(Database).await;

    /// Variable updated in the background by the driver.
    while database.read().await.is_none() {
    }

    assert!(database.read().await.is_some());
    Ok(())
}

pub fn chain(&self) -> Chain<'_>

Iterate through the chain of injectors.

Examples

use async_injector::Injector;

let injector = Injector::new();
let child = injector.child();

assert_eq!(1, injector.chain().count());
assert_eq!(2, child.chain().count());

Trait Implementations

impl Clone for Injector

fn clone(&self) -> Injector

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Injector

fn default() -> Self

Returns the "default value" for a type.