Struct Local 

pub struct Local<T> { /* private fields */ }

Local is a custom smart pointer-like structure designed to manage T in a single-threaded, non-concurrent context.

This design is aligned with the shared-nothing concurrency model, which avoids shared memory between threads to reduce the complexity of synchronization.

What does concurrent context mean in single-threaded execution?

Invalid code (with single-threaded concurrency):

use orengine::Local;


async fn write_and_dump_data_and_return_was_sent(counter: Local<Data>) -> bool {
    let mut local_ref = counter.borrow_mut();
    if is_valid_data(&*local_ref) {
        dump_data(&*local_ref).await; // Here the executor can execute other task, that change the data to invalid
        send_data(&*local_ref).await;

        return true;
    }

    false
}

Safety

• Local is used in one thread;
• Before every await operation, LocalRef and LocalRefMut need to be dropped, if other task can mutate the value and.

It is checked in debug mode. If you cannot guarantee compliance with the above rules you should use LocalMutex or LocalRWLock instead. Local synchronization-primitives have almost the same performance as Local or Rc<RefCell> and can be used in single-threaded concurrency context.

Shared-Nothing and spawn_local

In Rust, when working with local, task-specific data, you may want to leverage shared-nothing concurrency by isolating data to specific threads. Using the Local struct with spawn_local (which ensures that a task runs in a local thread) allows you to maintain this isolation. Since Local cannot be transferred to another thread, it enforces the shared-nothing principle, where each every thread holds and manages its own data independently.

Example

use orengine::local::Local;
use orengine::Executor;
use orengine::local_executor;

Executor::init().run_with_local_future(async {
    let local_data = Local::new(42);

    println!("The value is: {}", local_data);

    *local_data.borrow_mut() += 1;

    println!("Updated value: {}", local_data);

    // Cloning (increments the internal counter)
    let cloned_data = local_data.clone();
    local_executor().spawn_local(async move {
        assert_eq!(*cloned_data.borrow(), 43);
    });
});

Implementations

impl<T> Local<T>

pub fn new(data: T) -> Self

Creates a new Local instance, initializing it with the provided data.

Panics

If the Executor is not initialized.

Read MSG_LOCAL_EXECUTOR_IS_NOT_INIT for more details.

pub fn borrow(&self) -> LocalRef<'_, T>

Returns LocalRef that allows shared access to the data.

Read more in LocalRef.

Panics

Panics in debug mode if the value in Local is currently mutably borrowed or if Local has been moved to another thread.

pub fn borrow_mut(&self) -> LocalRefMut<'_, T>

Returns LocalRefMut that allows mutable access to the data.

Read more in LocalRefMut.

Panics

Panics in debug mode if the value in Local is currently mutably borrowed or if Local has been moved to another thread.

Trait Implementations

impl<T> Clone for Local<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Local<T>

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

Panics

Panics in debug mode if the value in Local is currently mutably borrowed or if Local has been moved to another thread.

impl<T: Default> Default for Local<T>

fn default() -> Self

Panics

Panics in debug mode if the value in Local is currently mutably borrowed or if Local has been moved to another thread.

impl<T: Display> Display for Local<T>

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

Panics

Panics in debug mode if the value in Local is currently mutably borrowed or if Local has been moved to another thread.

impl<T> Drop for Local<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> From<T> for Local<T>

fn from(value: T) -> Self

Converts to this type from the input type.

impl<T: Ord> Ord for Local<T>

fn cmp(&self, other: &Self) -> Ordering

Panics

Panics in debug mode if the value in either Local is currently mutably borrowed or if Local has been moved to another thread.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: PartialEq> PartialEq for Local<T>

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

Panics

Panics in debug mode if the value in Local is currently mutably borrowed or if Local has been moved to another thread.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialOrd> PartialOrd for Local<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

Panics

Panics in debug mode if the value in either Local is currently mutably borrowed or if Local has been moved to another thread.

fn lt(&self, other: &Self) -> bool

Panics

Panics in debug mode if the value in either Local is currently mutably borrowed or if Local has been moved to another thread.

fn le(&self, other: &Self) -> bool

Panics

Panics in debug mode if the value in either Local is currently mutably borrowed or if Local has been moved to another thread.

fn gt(&self, other: &Self) -> bool

Panics

Panics in debug mode if the value in either Local is currently mutably borrowed or if Local has been moved to another thread.

fn ge(&self, other: &Self) -> bool

Panics

Panics in debug mode if the value in either Local is currently mutably borrowed or if Local has been moved to another thread.

impl<T: Eq> Eq for Local<T>

impl<T> Sync for Local<T>