Trait Capsule

pub trait Capsule: Send + 'static {
    type Data: Send + Sync + 'static;

    // Required methods
    fn build(&self, handle: CapsuleHandle<'_, '_, '_>) -> Self::Data;
    fn eq(old: &Self::Data, new: &Self::Data) -> bool;

    // Provided method
    fn key(&self) -> impl CapsuleKey { ... }
}

Capsules are blueprints for creating some immutable data and do not actually contain any data themselves. See the documentation for more.

Required Associated Types

type Data: Send + Sync + 'static

The type of data associated with this capsule, which must be Send + Sync + 'static.

Capsule::Data that implements Clone will also unlock a few convenience methods.

Note: when your types do implement Clone, it is suggested to be a “cheap” Clone. Arcs, small collections/data structures, and the im crate are great for this.

Required Methods

fn build(&self, handle: CapsuleHandle<'_, '_, '_>) -> Self::Data

Builds the capsule’s immutable data using a given snapshot of the data flow graph. (The snapshot, a ContainerWriteTxn, is abstracted away for you via CapsuleHandle.)

Concurrency

ABSOLUTELY DO NOT TRIGGER ANY REBUILDS WITHIN THIS FUNCTION! Doing so may result in a deadlock or a panic.

fn eq(old: &Self::Data, new: &Self::Data) -> bool

Returns whether or not a capsule’s old data and new data are equivalent (and thus whether or not we can skip rebuilding dependents as an optimization).

Provided Methods

fn key(&self) -> impl CapsuleKey

Returns the key to use for this capsule. Most capsules should use the default implementation, which is for static capsules. If you specifically need dynamic capsules, such as for an incremental computation focused application, you will need to implement this function and return your capsule’s key.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<T, F> Capsule for F

where T: Send + Sync + 'static, F: Fn(CapsuleHandle<'_, '_, '_>) -> T + Send + 'static,

type Data = T