Struct ffi_support::handle_map::ConcurrentHandleMap [−][src]
Expand description
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.
Implementations
Get the number of entries in the ConcurrentHandleMap
.
This takes the map’s read
lock.
Returns true if the ConcurrentHandleMap
is empty.
This takes the map’s read
lock.
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.
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.
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.
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.
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.
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).
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).
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>,
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 Self::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,
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,
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,
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,
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>,
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,
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.