Struct ffi_support::handle_map::ConcurrentHandleMap

pub struct ConcurrentHandleMap<T> {
    pub map: RwLock<HandleMap<Mutex<T>>>,
}

ConcurrentHandleMap is a relatively thin wrapper around RwLock<HandleMap<Mutex<T>>>. Due to the nested locking, it's not possible to implement the same API as HandleMap, however it does implement an API that offers equivalent functionality, as well as several functions that greatly simplify FFI usage (see example below).

See the module level documentation for more info.

Example

// Somewhere...
struct Thing { value: f64 }

lazy_static! {
    static ref ITEMS: ConcurrentHandleMap<Thing> = ConcurrentHandleMap::new();
}

#[no_mangle]
pub extern "C" fn mylib_new_thing(value: f64, err: &mut ExternError) -> u64 {
    // Most uses will be `ITEMS.insert_with_result`. Note that this already
    // calls `call_with_output` (or `call_with_result` if this were
    // `insert_with_result`) for you.
    ITEMS.insert_with_output(err, || Thing { value })
}

#[no_mangle]
pub extern "C" fn mylib_thing_value(h: u64, err: &mut ExternError) -> f64 {
    // Or `ITEMS.call_with_result` for the fallible functions.
    ITEMS.call_with_output(err, h, |thing| thing.value)
}

#[no_mangle]
pub extern "C" fn mylib_thing_set_value(h: u64, new_value: f64, err: &mut ExternError) {
    ITEMS.call_with_output_mut(err, h, |thing| {
        thing.value = new_value;
    })
}

// Note: defines the following function:
// pub extern "C" fn mylib_destroy_thing(h: u64, err: &mut ExternError)
define_handle_map_deleter!(ITEMS, mylib_destroy_thing);

Fields

map: RwLock<HandleMap<Mutex<T>>>

The underlying map. Public so that more advanced use-cases may use it as they please.

Methods

impl<T> ConcurrentHandleMap<T>

pub fn new() -> Self

Construct a new ConcurrentHandleMap.

pub fn len(&self) -> usize

Get the number of entries in the ConcurrentHandleMap.

This takes the map's read lock.

pub fn is_empty(&self) -> bool

Returns true if the ConcurrentHandleMap is empty.

This takes the map's read lock.

pub fn insert(&self, v: T) -> Handle

Insert an item into the map, returning the newly allocated handle to the item.

Locking

Note that this requires taking the map's write lock, and so it will block until all other threads have finished any read/write operations.

pub fn delete(&self, h: Handle) -> Result<(), HandleError>

Remove an item from the map.

Locking

Note that this requires taking the map's write lock, and so it will block until all other threads have finished any read/write operations.

pub fn delete_u64(&self, h: u64) -> Result<(), HandleError>

Convenient wrapper for delete which takes a u64 that it will convert to a handle.

The main benefit (besides convenience) of this over the version that takes a Handle is that it allows handling handle-related errors in one place.

pub fn remove(&self, h: Handle) -> Result<Option<T>, HandleError>

Remove an item from the map, returning either the item, or None if its guard mutex got poisoned at some point.

Locking

Note that this requires taking the map's write lock, and so it will block until all other threads have finished any read/write operations.

pub fn remove_u64(&self, h: u64) -> Result<Option<T>, HandleError>

Convenient wrapper for remove which takes a u64 that it will convert to a handle.

The main benefit (besides convenience) of this over the version that takes a Handle is that it allows handling handle-related errors in one place.

pub fn get<F, E, R>(&self, h: Handle, callback: F) -> Result<R, E> where
    F: FnOnce(&T) -> Result<R, E>,
    E: From<HandleError>, 

Call callback with a non-mutable reference to the item from the map, after acquiring the necessary locks.

Locking

Note that this requires taking both:

• The map's read lock, and so it will block until all other threads have finished any write operations.
• The mutex on the slot the handle is mapped to.

And so it will block if there are ongoing write operations, or if another thread is reading from the same handle.

Panics

This will panic if a previous get() or get_mut() call has panicked inside it's callback. The solution to this

(It may also panic if the handle map detects internal state corruption, however this should not happen except for bugs in the handle map code).

pub fn get_mut<F, E, R>(&self, h: Handle, callback: F) -> Result<R, E> where
    F: FnOnce(&mut T) -> Result<R, E>,
    E: From<HandleError>, 

Call callback with a mutable reference to the item from the map, after acquiring the necessary locks.

Locking

Note that this requires taking both:

• The map's read lock, and so it will block until all other threads have finished any write operations.
• The mutex on the slot the handle is mapped to.

And so it will block if there are ongoing write operations, or if another thread is reading from the same handle.

Panics

This will panic if a previous get() or get_mut() call has panicked inside it's callback. The only solution to this is to remove and reinsert said item.

(It may also panic if the handle map detects internal state corruption, however this should not happen except for bugs in the handle map code).

pub fn get_u64<F, E, R>(&self, u: u64, callback: F) -> Result<R, E> where
    F: FnOnce(&T) -> Result<R, E>,
    E: From<HandleError>, 

Convenient wrapper for get which takes a u64 that it will convert to a handle.

The other benefit (besides convenience) of this over the version that takes a Handle is that it allows handling handle-related errors in one place.

Locking

Note that this requires taking both:

• The map's read lock, and so it will block until all other threads have finished any write operations.
• The mutex on the slot the handle is mapped to.

And so it will block if there are ongoing write operations, or if another thread is reading from the same handle.

pub fn get_mut_u64<F, E, R>(&self, u: u64, callback: F) -> Result<R, E> where
    F: FnOnce(&mut T) -> Result<R, E>,
    E: From<HandleError>, 

Convenient wrapper for get_mut which takes a u64 that it will convert to a handle.

The main benefit (besides convenience) of this over the version that takes a Handle is that it allows handling handle-related errors in one place.

Locking

Note that this requires taking both:

• The map's read lock, and so it will block until all other threads have finished any write operations.
• The mutex on the slot the handle is mapped to.

And so it will block if there are ongoing write operations, or if another thread is reading from the same handle.

pub fn call_with_result_mut<R, E, F>(
    &self,
    out_error: &mut ExternError,
    h: u64,
    callback: F
) -> R::Value where
    F: UnwindSafe + FnOnce(&mut T) -> Result<R, E>,
    ExternError: From<E>,
    R: IntoFfi, 

Helper that performs both a [call_with_result] and get.

pub fn call_with_result<R, E, F>(
    &self,
    out_error: &mut ExternError,
    h: u64,
    callback: F
) -> R::Value where
    F: UnwindSafe + FnOnce(&T) -> Result<R, E>,
    ExternError: From<E>,
    R: IntoFfi, 

Helper that performs both a [call_with_result] and get.

pub fn call_with_output<R, F>(
    &self,
    out_error: &mut ExternError,
    h: u64,
    callback: F
) -> R::Value where
    F: UnwindSafe + FnOnce(&T) -> R,
    R: IntoFfi, 

Helper that performs both a [call_with_output] and get.

pub fn call_with_output_mut<R, F>(
    &self,
    out_error: &mut ExternError,
    h: u64,
    callback: F
) -> R::Value where
    F: UnwindSafe + FnOnce(&mut T) -> R,
    R: IntoFfi, 

Helper that performs both a [call_with_output] and get_mut.

pub fn insert_with_result<E, F>(
    &self,
    out_error: &mut ExternError,
    constructor: F
) -> u64 where
    F: UnwindSafe + FnOnce() -> Result<T, E>,
    ExternError: From<E>, 

Use constructor to create and insert a T, while inside a [call_with_result] call (to handle panics and map errors onto an ExternError).

pub fn insert_with_output<F>(
    &self,
    out_error: &mut ExternError,
    constructor: F
) -> u64 where
    F: UnwindSafe + FnOnce() -> T, 

Equivalent to insert_with_result for the case where the constructor cannot produce an error.

The name is somewhat dubious, since there's no output, but it's intended to make it clear that it contains a [call_with_output] internally.

Trait Implementations

impl<T> Default for ConcurrentHandleMap<T>

fn default() -> Self

Returns the "default value" for a type.