Struct rayon_tlsctx::ThreadLocalCtx

pub struct ThreadLocalCtx<T, F> { /* fields omitted */ }

A thread local storage container for Rayon jobs

This context can be used to efficiently clone inner, only when it’s necessary.

Implementations

impl<T, F: Fn() -> T> ThreadLocalCtx<T, F>

pub fn new(inner: F) -> Self

Create a new TlsCtx

Examples

Creating a thread-local byte buffer:

use rayon_tlsctx::ThreadLocalCtx;
let ctx = ThreadLocalCtx::new(Vec::<u8>::new);

pub fn new_locked(inner: F) -> ThreadLocalCtx<T, impl Fn() -> T>

Create a new TlsCtx.

This context utilises a lock for cloning values, making it usable for non-sync types.

Cloning an initialised buffer for each thread:

use rayon_tlsctx::ThreadLocalCtx;
use rayon::iter::*;
use std::cell::Cell;

let mut buf: Vec<u16> = (0..!0).collect();
buf.shuffle(&mut rng);

let buf = (buf, Cell::new(0));

// Must use new_locked, because cloning a cell across threads is not allowed
let ctx = ThreadLocalCtx::new_locked(move || buf.clone());

(0..16).into_par_iter().for_each(|_| unsafe { ctx.get(); });

pub unsafe fn get(&self) -> ThreadLocalMut<'_, T>

Get a thread local context reference with dynamically checked borrow rules

Remarks

It is advised to manually drop the borrowed context if it is to be reborrowed within inner scope. This is because chances of heap allocations significantly increase.

Safety

Only one thread pool should use this scope (throughout the duration of its lifetime). The thread pool size can not grow midway through.

Examples

use rayon_tlsctx::ThreadLocalCtx;
use rayon::iter::*;

const NUM_COPIES: usize = 16;

let mut buf: Vec<u16> = (0..!0).collect();

// Create a thread local context with value 0.
let ctx = ThreadLocalCtx::new(|| 0);

// Sum the buffer `NUM_COPIES` times and accumulate the results
// into the threaded pool of counts. Note that the counts may be
// Unevenly distributed.
(0..NUM_COPIES)
    .into_par_iter()
    .flat_map(|_| buf.par_iter())
    .for_each(|i| {
        let mut cnt = unsafe { ctx.get() };
        *cnt += *i as usize;
    });

let buf_sum = buf.into_iter().fold(0, |acc, i| acc + i as usize);

// What matters is that the final sum matches the expected value.
assert_eq!(ctx.into_iter().sum::<usize>(), buf_sum * NUM_COPIES);

Trait Implementations

impl<T, F> IntoIterator for ThreadLocalCtx<T, F>

Consume the context and retrieve all created items.

type Item = T

The type of the elements being iterated over.

type IntoIter = ThreadNodeIterator<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, F: Send + Sync> Send for ThreadLocalCtx<T, F>

impl<T, F: Send + Sync> Sync for ThreadLocalCtx<T, F>