#owned #singleton #proxy

no-std owned-singleton

Owned singletons

1 unstable release

0.1.0 Nov 1, 2018

#5 in #owned

Download history 14/week @ 2018-11-02

4 downloads per month
Used in 1 crate

MIT/Apache

8KB

owned-singleton

Owned singletons

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.


lib.rs:

Owned singletons

An owned singleton is a proxy (struct) that grants exclusive access to a static mut variable.

Features

Owned singletons are smaller than &'static mut references; they are zero sized types.

Doesn't sound useful enough to you? The Singleton abstraction can be used to implement statically allocated memory pools whose handles are a single byte in size and are automatically deallocated on drop.

Examples

The Singleton attribute creates a proxy (struct) for the given static mut variable and implements the Singleton, Deref, DerefMut and StableDerefs traits for it.

use owned_singleton::Singleton;

#[Singleton]
static mut FOO: u32 = 0;

let mut foo = unsafe { FOO::new() };
assert_eq!(*foo, 0);
*foo += 1;
assert_eq!(*foo, 1);

let bar: &'static mut u32 = foo.unwrap();
assert_eq!(*bar, 1);

The Singleton attribute doesn't implement the Send or Sync traits by default; this results in a proxy struct that does not implement Send or Sync. To opt into the Send and Sync traits add the Send and Sync arguments to the Singleton attribute.

use owned_singleton::Singleton;

#[Singleton(Send, Sync)]
static mut FOO: u32 = 0;

fn is_send<T>() where T: Send {}
fn is_sync<T>() where T: Sync {}

is_send::<FOO>();
is_sync::<FOO>();

Using Singleton on a static variable results in DerefMut not being implemented for the proxy struct. However, the proxy struct will still be a handle to a static mut variable so there's no Sync requirement on the type of the static mut variable.

use std::marker::PhantomData;

use owned_singleton::Singleton;

// `PhantomData<*const ()>` does not implement `Send` or `Sync`
#[Singleton]
static FOO: PhantomData<*const ()> = PhantomData;

Dependencies

~1.5MB
~26K SLoC