Struct sc_consensus::shared_data::SharedData

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

Some shared data that provides support for locking this shared data for some time.

When working with consensus engines there is often data that needs to be shared between multiple parts of the system, like block production and block import. This struct provides an abstraction for this shared data in a generic way.

The pain point when sharing this data is often the usage of mutex guards in an async context as this doesn’t work for most of them as these guards don’t implement Send. This abstraction provides a way to lock the shared data, while not having the mutex locked. So, the data stays locked and we are still able to hold this lock over an await call.

Example

let shared_data = SharedData::new(String::from("hello world"));

let lock = shared_data.shared_data_locked();

let shared_data2 = shared_data.clone();
let join_handle1 = std::thread::spawn(move || {
    // This will need to wait for the outer lock to be released before it can access the data.
    shared_data2.shared_data().push_str("1");
});

assert_eq!(*lock, "hello world");

// Let us release the mutex, but we still keep it locked.
// Now we could call `await` for example.
let mut lock = lock.release_mutex();

let shared_data2 = shared_data.clone();
let join_handle2 = std::thread::spawn(move || {
    shared_data2.shared_data().push_str("2");
});

// We still have the lock and can upgrade it to access the data.
assert_eq!(*lock.upgrade(), "hello world");
lock.upgrade().push_str("3");

drop(lock);
join_handle1.join().unwrap();
join_handle2.join().unwrap();

let data = shared_data.shared_data();
// As we don't know the order of the threads, we need to check for both combinations
assert!(*data == "hello world321" || *data == "hello world312");

Deadlock

Be aware that this data structure doesn’t give you any guarantees that you can not create a deadlock. If you use release_mutex followed by a call to shared_data in the same thread will make your program dead lock. The same applies when you are using a single threaded executor.

Implementations

impl<T> SharedData<T>

pub fn new(shared_data: T) -> Self

Create a new instance of SharedData to share the given shared_data.

pub fn shared_data(&self) -> MappedMutexGuard<'_, T>

Acquire access to the shared data.

This will give mutable access to the shared data. After the returned mutex guard is dropped, the shared data is accessible by other threads. So, this function should be used when reading/writing of the shared data in a local context is required.

When requiring to lock shared data for some longer time, even with temporarily releasing the lock, Self::shared_data_locked should be used.

pub fn shared_data_locked(&self) -> SharedDataLocked<'_, T>

Acquire access to the shared data and lock it.

This will give mutable access to the shared data. The returned SharedDataLocked provides the function SharedDataLocked::release_mutex to release the mutex, but keeping the data locked. This is useful in async contexts for example where the data needs to be locked, but a mutex guard can not be held.

For an example see SharedData.

Trait Implementations

impl<T> Clone for SharedData<T>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.