Crate try_drop

Source

Expand description

try-drop

Batteries included error handling mechanisms for drops which can fail

§Quick Usage

§For Clients

…where clients mean structures that may fail dropping,

Implement TryDrop for your type and adapt it like so:

use try_drop::TryDrop;

pub struct Foo { /* fields */ }

impl TryDrop for Foo {
    type Error = Error;
    
    unsafe fn try_drop(&mut self) -> Result<(), Self::Error> {
        // do stuff
        Ok(())
    }
}

let foo = Foo.adapt();

…or, if you want to avoid the adapt boilerplate:

use try_drop::{TryDrop, adapters::DropAdapter};

pub struct FooInner { /* fields */ }

impl TryDrop for FooInner {
    type Error = Error;
    
    unsafe fn try_drop(&mut self) -> Result<(), Self::Error> {
        // do stuff
        Ok(())
    }
}

pub struct Foo(pub DropAdapter<FooInner>);

impl Foo {
    pub fn from_inner(inner: FooInner) -> Self {
        Foo(DropAdapter(inner))
    }
}

With this, if dropping Foo fails, it will automatically print the error to standard error.

§For Servers

…where servers mean how to handle the drop errors (also means drop strategies),

Implement TryDropStrategy for your structure.

use try_drop::TryDropStrategy;

pub struct Strategy { /* fields */ }

impl TryDropStrategy for Strategy {
    fn handle_error(&self, error: try_drop::Error) {
        // handle the error here
    }
}

…then install either for this thread,

try_drop::install_thread_local_handlers(Strategy, /* other strategy, use the `PanicDropStrategy` if you don't know */)

…install it globally (meaning if no thread local strategies are set, use this),

try_drop::install_global_handlers(Strategy, /* other strategy */)

…or, if possible, install it for a structure.

struct Sample<D = ShimPrimaryHandler, DD = ShimFallbackHandler>
where
    D: FallibleTryDropStrategy,
    DD: TryDropStrategy,
{
    primary: D,
    fallback: DD,
    /* other fields */
}

impl<D, DD> Sample<D, DD>
where
    D: FallibleTryDropStrategy,
    DD: TryDropStrategy,
{
    pub fn new_with(/* other arguments */ primary: D, fallback: DD) -> Self {
        Self {
            // filled arguments
            primary,
            fallback,
        }
    }
}

let sample = Sample::new_with(Strategy, /* other strategy */)

§License

This project is licensed under the MIT License.

Re-exports§

pub use self::ImpureTryDrop as TryDrop;

Modules§

adapters: This stores all the adapters that this crate and users of this crate may use.
drop_strategies: Numerous strategies for handling drop errors.
handlers: Manage the primary and fallback handlers and their scopes.
prelude: Most commonly used traits.

Structs§

Error: The Error type, a wrapper around a dynamic error type.

Enums§

Infallible: The error type for errors that can never happen.

Traits§

DynFallibleTryDropStrategy: A trait which signifies a try drop strategy which can fail. Can be dynamically dispatched.
FallibleTryDropStrategy: A trait which signifies a try drop strategy which can fail.
GlobalDynFallibleTryDropStrategy: A trait which signifies a try drop strategy which can fail, can be dynamically dispatched, and can be used as the global try drop strategy.
GlobalTryDropStrategy: A trait which signifies a try drop strategy which can be used as the primary or fallback handler. Can be downcast.
ImpureTryDrop: A trait for types which can be dropped, but which may fail to do so.
PureTryDrop: A trait for types which can be dropped, but which may fail to do so.
RepeatableTryDrop: Marker trait signifying that the implementing type can repeatedly call its TryDrop::try_drop method.
ThreadLocalFallibleTryDropStrategy: A trait which signifies a try drop strategy which can be used in a thread local scenario. Must be dynamically dispatched and must live as long as the program does.
ThreadLocalTryDropStrategy: A trait which signifies an infallible try drop strategy which can be used in a thread local.
ThreadSafe: A trait which signifies a thread safe type. Can be used in a static.
TryDropStrategy: A trait which signifies a try drop strategy. This can never fail. If it can, use FallibleTryDropStrategy instead.

Functions§

install_global_handlers: This installs the primary and fallback global handlers.
install_global_handlers_dyn: This installs the primary and fallback global handlers. Must be a dynamic trait object.
install_thread_local_handlers: This installs the primary and fallback thread local handlers.
install_thread_local_handlers_dyn: This installs the primary and fallback thread local handlers. Must be a dynamic trait object.
install_thread_local_handlers_for_this_scope: This installs the primary and fallback thread local handlers for this scope.
install_thread_local_handlers_for_this_scope_dyn: This installs the primary and fallback thread local handlers for this scope. Must be a dynamic trait object.
uninstall_for_thread: This uninstalls the primary and fallback thread local handlers.
uninstall_globally: This uninstalls the primary and fallback global handlers.

Crate try_dropCopy item path