Struct LocalKey 

pub struct LocalKey<T: 'static> { /* private fields */ }

A variable stored in task-local storage.

Usage

The primary mode of accessing this is through the LocalKey::with method. For LocalKey<RefCell<T>> and LocalKey<Cell<T>>, additional convenience methods are added that mirror the underlying [RefCell<T>] or [Cell<T>]’s methods.

Examples

use std::cell::{Cell, RefCell};

use vexide::prelude::*;

task_local! {
    static PHI: f64 = 1.61803;
    static COUNTER: Cell<u32> = Cell::new(0);
    static NAMES: RefCell<Vec<String>> = RefCell::new(Vec::new());
}

#[vexide::main]
async fn main(_peripherals: Peripherals) {
    // LocalKey::with accepts a function and applies it to a reference, returning whatever value
    // the function returned
    let double_phi = PHI.with(|&phi| phi * 2.0);
    assert_eq!(double_phi, 1.61803 * 2.0);

    // We can use interior mutability
    COUNTER.set(1);
    assert_eq!(COUNTER.get(), 1);

    NAMES.with_borrow_mut(|names| names.push(String::from("Johnny")));
    NAMES.with_borrow(|names| assert_eq!(names.len(), 1));

    // Creating another task
    spawn(async {
        // The locals of the previous task are completely different.
        assert_eq!(COUNTER.get(), 0);
        NAMES.with_borrow(|names| assert_eq!(names.len(), 0));
    })
    .await;
}

Implementations

impl<T: 'static> LocalKey<T>

pub fn with<F, R>(&'static self, f: F) -> R

where F: FnOnce(&T) -> R,

Obtains a reference to the local and applies it to the function f, returning whatever f returned.

Examples

use vexide::task::task_local;

task_local! {
    static PHI: f64 = 1.61803;
}

let double_phi = PHI.with(|&phi| phi * 2.0);
assert_eq!(double_phi, 1.61803 * 2.0);

impl<T: 'static> LocalKey<Cell<T>>

pub fn get(&'static self) -> T

where T: Copy,

Returns a copy of the contained value.

pub fn set(&'static self, value: T)

Sets the contained value.

pub fn take(&'static self) -> T

where T: Default,

Takes the value of contained value, leaving [Default::default()] in its place.

pub fn replace(&'static self, value: T) -> T

Replaces the contained value with value, returning the old contained value.

impl<T: 'static> LocalKey<RefCell<T>>

pub fn with_borrow<F, R>(&'static self, f: F) -> R

where F: FnOnce(&T) -> R,

Immutably borrows from the [RefCell] and applies the obtained reference to f.

Panics

Panics if the value is currently mutably borrowed. For a non-panicking variant, use LocalKey::try_with_borrow.

pub fn with_borrow_mut<F, R>(&'static self, f: F) -> R

where F: FnOnce(&mut T) -> R,

Mutably borrows from the [RefCell] and applies the obtained reference to f.

Panics

Panics if the value is currently borrowed. For a non-panicking variant, use LocalKey::try_with_borrow_mut.

pub fn try_with_borrow<F, R>(&'static self, f: F) -> Result<R, BorrowError>

where F: FnOnce(&T) -> R,

Tries to immutably borrow the contained value, returning an error if it is currently mutably borrowed, and applies the obtained reference to f.

This is the non-panicking variant of LocalKey::with_borrow.

Errors

Returns [BorrowError] if the contained value is currently mutably borrowed.

pub fn try_with_borrow_mut<F, R>( &'static self, f: F, ) -> Result<R, BorrowMutError>

where F: FnOnce(&T) -> R,

Tries to mutably borrow the contained value, returning an error if it is currently borrowed, and applies the obtained reference to f.

This is the non-panicking variant of LocalKey::with_borrow_mut.

Errors

Returns [BorrowMutError] if the contained value is currently borrowed.

pub fn set(&'static self, value: T)

Sets the contained value.

Panics

Panics if the value is currently borrowed.

pub fn take(&'static self) -> T

where T: Default,

Takes the contained value, leaving [Default::default()] in its place.

Panics

Panics if the value is currently borrowed.

pub fn replace(&'static self, value: T) -> T

Replaces the contained value with value, returning the old contained value.

Panics

Panics if the value is currently borrowed.

Trait Implementations

impl<T: Debug + 'static> Debug for LocalKey<T>

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

Formats the value using the given formatter.

impl<T> Send for LocalKey<T>

impl<T> Sync for LocalKey<T>