Struct RegionLocal

pub struct RegionLocal<T>
where
    T: Clone + Send + Sync + 'static,
{ /* private fields */ }

Provides access to an instance of T whose values are local to the current memory region. Callers from different memory regions will observe different instances of T.

Refer to crate-level documentation for more information.

Implementations

impl<T> RegionLocal<T>

where T: Clone + Send + Sync + 'static,

pub fn new(initializer: fn() -> T) -> Self

Creates a new instance of RegionLocal, providing a callback to create the initial value.

This callback will be called on a thread in the memory region where the value will be used.

The instance of RegionLocal may be cloned and shared between threads using mechanisms of the linked object pattern. Every instance from the same family of objects in the same memory region will reference the same region-local value.

This type is internally used by the region_local! macro but can also be used independently of that macro, typically via a PerThread wrapper that automatically manages the per-thread instance lifecycle and delivery across threads.

pub fn with_local<F, R>(&self, f: F) -> R

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

Executes the provided function with a reference to the value stored in the current memory region.

Example

use linked::InstancePerThread;
use region_local::{RegionLocal};

let favorite_color_regional = InstancePerThread::new(RegionLocal::new(|| "blue".to_string()));

// This localizes the object to the current thread. Reuse this object when possible.
let favorite_color = favorite_color_regional.acquire();

let len = favorite_color.with_local(|color| color.len());
assert_eq!(len, 4);

pub fn set_local(&self, value: T)

Publishes a new value to all threads in the current memory region.

The update will be applied to all threads in the current memory region in a weakly consistent manner. The updated value will not be visible in other memory regions - storage is independent for each memory region.

Example

use linked::InstancePerThread;
use region_local::{RegionLocal};

let favorite_color_regional = InstancePerThread::new(RegionLocal::new(|| "blue".to_string()));

// This localizes the object to the current thread. Reuse this object when possible.
let favorite_color = favorite_color_regional.acquire();

favorite_color.set_local("red".to_string());

Updating the value is weakly consistent. Do not expect the update to be immediately visible. Even on the same thread, it is only guaranteed to be immediately visible if the thread is pinned to a specific memory region.

use linked::InstancePerThread;
use many_cpus::ProcessorSet;
use region_local::{RegionLocal};
use std::num::NonZero;

let favorite_color_regional = InstancePerThread::new(RegionLocal::new(|| "blue".to_string()));

// We can use this to pin a thread to a specific processor, to demonstrate a
// situation where you can rely on consistency guarantees for immediate visibility.
let one_processor = ProcessorSet::builder()
    .take(NonZero::new(1).unwrap())
    .unwrap();

one_processor.spawn_thread(move |processor_set| {
    let processor = processor_set.processors().first();
    println!("Thread pinned to processor {} in memory region {}",
        processor.id(),
        processor.memory_region_id()
    );

    // This localizes the object to the current thread. Reuse this object when possible.
    let favorite_color = favorite_color_regional.acquire();

    favorite_color.set_local("red".to_string());

    // This thread is pinned to a specific processor, so it is guaranteed to stay
    // within the same memory region (== on the same physical hardware). This means
    // that an update to a region-local value is immediately visible.
    let color = favorite_color.with_local(|color| color.clone());
    assert_eq!(color, "red");
}).join().unwrap();

impl<T> RegionLocal<T>

where T: Clone + Copy + Send + Sync + 'static,

pub fn get_local(&self) -> T

Gets a copy of the value from the current memory region.

Example

use linked::InstancePerThread;
use region_local::{RegionLocal};

let current_access_token_regional = InstancePerThread::new(RegionLocal::new(|| 0x123100));

// This localizes the object to the current thread. Reuse this object when possible.
let current_access_token = current_access_token_regional.acquire();

let token = current_access_token.get_local();
assert_eq!(token, 0x123100);

Trait Implementations

impl<T> Clone for RegionLocal<T>

where T: Clone + Send + Sync + 'static,

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 for RegionLocal<T>

where T: Clone + Send + Sync + 'static + Debug,

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

Formats the value using the given formatter.

impl<T> From<Family<RegionLocal<T>>> for RegionLocal<T>

where T: Clone + Send + Sync + 'static,

fn from(family: Family<RegionLocal<T>>) -> Self

Converts to this type from the input type.

impl<T> Object for RegionLocal<T>

where T: Clone + Send + Sync + 'static,

fn family(&self) -> Family<Self>

The object family that the current instance is linked to.