phylactery 0.5.1

In Brief

Given a trait Trait and a T: Trait, any &'a T can be split into a Lich<dyn Trait + 'static> and a Soul<'a> pair such that the dyn Trait can cross 'static boundaries while tracking the lifetime 'a.

The general usage pattern of this library is:

Choose a Lich<T>/Soul<'a> variant for your use-case (see below for the tradeoffs).
Implement Shroud for the trait for which you want to extend the lifetime (#[shroud] trait Trait will impl<T: Trait> Shroud<T> for dyn Trait automatically).
Use the corresponding ritual::<T: Trait, dyn Trait>(value: &'a T) to produce a Lich<dyn Trait + 'static> bound to a Soul<'a>.
Use the Lich<dyn Trait> as a 'static reference to your otherwise non-static &'a T.
Use the corresponding redeem(Lich<T>, Soul<'a>) to guarantee that all references to &'a T are dropped before the end of lifetime 'a.

When Soul<'a> is dropped or when calling Soul::sever, it is guaranteed that the captured reference is also dropped, thus inaccessible from a remaining Lich<T>.

Different variants exist with different tradeoffs:

phylactery::raw:
- Zero cost (wraps a pointer in a new type).
- Does not allocate heap memory.
- Does require the Lich<T> to be redeemed with its Soul<'a> (otherwise, Lich<T> and Soul<'a> will panic on drop).
- Does require some unsafe calls (Lich<T>::borrow).
- Lich<T> can not be cloned.
- Can be sent to other threads.
- Can be used with #[no_std].
phylactery::atomic:
- Adds minimal overhead with an AtomicU32 reference counter.
- Does not allocate heap memory.
- Does require an additional memory location (an &mut u32) to create the Lich<T>/Soul<'a> pair.
- If a Lich<T> still exists when the Soul<'a> is dropped, the thread will block until the Lich<T> is dropped (which can lead to dead locks).
- Does not require unsafe calls.
- Lich<T> can be cloned.
- Can be sent to other threads.
- Can be used with #[no_std].
phylactery::cell:
- Adds an indirection and minimal overhead using Rc<RefCell>.
- Does allocate heap memory.
- Allows for the use of the Lich<T>/Soul<'a>::sever methods.
- If a borrow still exists when the Soul<'a> is dropped, the thread will panic.
- Does not require the Lich<T>es to be redeemed (although it is considered good practice to do so).
- Does not require unsafe calls.
- Lich<T> can be cloned.
- Can not be sent to other threads.
phylactery::lock:
- Adds an indirection and some overhead using Arc<RwLock>.
- Does allocate heap memory.
- Allows for the use of the Lich<T>/Soul<'a>::sever methods.
- If a borrow still exists when the Soul<'a> is dropped, the thread will block until the borrow expires (which can lead to dead locks).
- Does not require the Lich<T> to be redeemed (although it is considered good practice to do so).
- Does not require unsafe calls.
- Lich<T> can be cloned.
- Can be sent to other threads.

Since this library makes use of some unsafe code, all tests are run with miri to try to catch any unsoundness.

Examples

/// Trivially reimplement `thread::scope` in a more powerful way.
///
/// Contrarily to other `scope` solutions, here, the captured reference can be
/// returned (as a `Soul<'a>`) while the threads continue to execute.
#[cfg(feature = "lock")]
pub mod thread_spawn_bridge {
    use core::num::NonZeroUsize;
    use phylactery::lock::{ritual, Soul};
    use std::thread;

    pub fn broadcast<F: Fn(usize) + Send + Sync>(
        parallelism: NonZeroUsize,
        function: &F,
    ) -> Soul<'_> {
        let (lich, soul) = ritual::<_, dyn Fn(usize) + Send + Sync>(function);
        // Spawn a bunch of threads that will all call `F`.
        for index in 0..parallelism.get() {
            let lich = lich.clone();
            // The non-static function `F` crosses a `'static` boundary protected by the
            // `Lich<T>`.
            thread::spawn(move || {
                // Borrowing may fail if the `Soul<'a>` has been dropped/severed.
                if let Some(guard) = lich.borrow() {
                    // Call the non-static function.
                    guard(index);
                }
                // Allow the `Guard` and `Lich<T>` to drop such that the
                // `Soul<'a>` can complete its `Soul::sever`.
            });
        }

        // The `Soul<'a>` continues to track the captured `'a` reference and will
        // guarantee that it becomes inaccessible when it itself drops.
        //
        // Note that this may block this thread if there still are active borrows at the
        // time of drop.
        //
        // Note that the `Lich<T>`es do not need be `redeem`ed.
        soul
    }
}

fn main() {
    #[cfg(feature = "lock")]
    thread_spawn_bridge::broadcast(
        std::thread::available_parallelism().unwrap_or(core::num::NonZeroUsize::MIN),
        &|index| println!("{index}"),
    );
}

/// Implements a thread local scoped logger available from anywhere that can
/// borrow values that live on the stack.
#[cfg(all(feature = "cell", feature = "shroud"))]
pub mod scoped_static_logger {
    use core::{cell::RefCell, fmt::Display};
    use phylactery::{
        cell::{Lich, redeem, ritual},
        shroud::shroud,
    };

    // Use the convenience macro to automatically implement the required `Shroud`
    // trait for all `T: Log`.
    #[shroud]
    pub trait Log {
        fn parent(&self) -> Option<&dyn Log>;
        fn prefix(&self) -> &str;
        fn format(&self) -> &str;
        fn arguments(&self) -> &[&dyn Display];
    }

    pub struct Logger<'a> {
        parent: Option<&'a dyn Log>,
        prefix: &'a str,
        format: &'a str,
        arguments: &'a [&'a dyn Display],
    }

    impl Log for Logger<'_> {
        fn parent(&self) -> Option<&dyn Log> {
            self.parent
        }

        fn prefix(&self) -> &str {
            self.prefix
        }

        fn format(&self) -> &str {
            self.format
        }

        fn arguments(&self) -> &[&dyn Display] {
            self.arguments
        }
    }

    // This thread local storage allows preserve this thread's call stack while
    // being able to log from anywhere without the need to pass a logger around.
    //
    // Note that the `Lich<dyn Log>` implements `Default` and has the `'static`
    // lifetime.
    thread_local! {
        static LOGGER: RefCell<Lich<dyn Log>> = RefCell::default();
    }

    pub fn scope<T: Display, F: FnOnce(&T)>(prefix: &str, argument: &T, function: F) {
        let parent = LOGGER.take();
        {
            // `Lich::borrow` can fail if the binding between it and its `Soul<'a>` has been
            // severed.
            let guard = parent.borrow();
            // This `Logger` captures some references that live on the stack.
            let logger = Logger {
                parent: guard.as_deref(),
                prefix,
                format: "({})",
                arguments: &[argument],
            };
            // `ritual` produces a `Lich<dyn Log + 'static>` and `Soul<'a>` pair.
            let (lich, soul) = ritual::<_, dyn Log + 'static>(&logger);
            // Push this logger as the current scope.
            LOGGER.set(lich);
            function(argument);
            // Pop the logger.
            let lich = LOGGER.take();
            // Although not strictly required in this case (letting the `Lich<T>` and
            // `Soul<'a>` be dropped would also work), `redeem` is the recommended
            // pattern to dispose of a `Lich<T>` and `Soul<'a>` pair since it is going to
            // work with all variants of `Lich<T>/Soul<'a>`.
            redeem(lich, soul).ok().expect("must be able to redeem");
        }
        // Put back the old logger.
        LOGGER.set(parent);
    }
}

fn main() {
    #[cfg(all(feature = "cell", feature = "shroud"))]
    scoped_static_logger::scope("some-prefix", &37, |value| {
        assert_eq!(*value, 37);
    });
}

See the examples and tests folder for more detailed examples.

Contribute

If you find a bug or have a feature request, please open an issues.
phylactery is actively maintained and pull requests are welcome.
If phylactery was useful to you, please consider leaving a star!