Struct ste::Tag

#[repr(transparent)]
pub struct Tag(_);

A tag associated with a thread. Threads which are executed with Thread support tagging.

You must ensure that any thread trying to use values first is checked with the current tag through Tag::ensure_on_thread. This includes everything which poses a potential thread safety risk.

This includes, but is not limited to:

• Accessing or mutating any racy data or APIs, such as Cell<T>.
• The type that is tagged, (and any nested types) drop implementation.

If all of the above is satifised, you can safely implement Send and Sync for the type. Make sure to include a comprehensive safety message such as:

// Safety: the structure is explicitly tagged with the thread that created
// it, and we ensure everywhere (including drop implementations) where racy
// access might occur that it is on the thread that created it.
unsafe impl Send for Foo {}

Tags can only be correctly constructed in two ways:

• By calling Tag::current_thread if inside of a thread context. Such as Thread::submit or Thread::submit_async.
• Externally by calling Thread::tag.

Examples

use std::cell::Cell;

struct Foo {
    tag: ste::Tag,
    data: Cell<usize>,
}

impl Foo {
    fn new() -> Self {
        Self {
            tag: ste::Tag::current_thread(),
            data: Cell::new(42),
        }
    }

    fn say_hello(&self) {
        self.tag.ensure_on_thread();
        println!("Hello from Foo: {}", self.data.get());
    }
}

// Safety: the structure is explicitly tagged with the thread that created
// it, and we ensure everywhere (including drop implementations) where racy
// access might occur that it is on the thread that created it.
unsafe impl Send for Foo {}
unsafe impl Sync for Foo {}

let thread = ste::spawn();

let foo = thread.submit(|| Foo::new());

assert!(!foo.tag.is_on_thread());

thread.submit(|| foo.say_hello());

thread.join();

Incorrect use of the tagged struct must panic:

let thread = ste::spawn();

let foo = thread.submit(|| Foo::new());

assert!(!foo.tag.is_on_thread());

foo.say_hello(); // <- oops, this panics!

thread.join();

Implementations

impl Tag

pub fn current_thread() -> Self

Get the tag associated with the current thread.

See Tag documentation for how to use correctly.

Panics

Panics if not running on a tagged thread. Tagged threads are the ones created with Thread.

pub fn ensure_on_thread(&self)

Ensure that the tag is currently executing on the thread that created it.

See Tag documentation for how to use.

Panics

Panics if not running on a tagged thread. Tagged threads are the ones created with Thread.

Also panics unless called on the same thread that the tag was created on.

pub fn is_on_thread(&self) -> bool

Test if we’re currently on the tagged thread.

See Tag documentation for how to use.

Trait Implementations

impl Clone for Tag

fn clone(&self) -> Tag

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Copy for Tag

impl Debug for Tag

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Tag

impl Hash for Tag

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

pub fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl PartialEq<Tag> for Tag

fn eq(&self, other: &Tag) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Tag) -> bool

This method tests for !=.

impl StructuralEq for Tag

impl StructuralPartialEq for Tag