16 breaking releases
0.17.2 | Oct 19, 2024 |
---|---|
0.17.0 | Sep 23, 2023 |
0.16.1 | Apr 6, 2023 |
0.16.0 | Dec 26, 2022 |
0.3.0 | Jun 28, 2021 |
#57 in Concurrency
545 downloads per month
Used in 28 crates
(3 directly)
120KB
3K
SLoC
🗂️ resman
Runtime managed resource borrowing.
This library provides a map that can store one of any type, as well as mutable borrows to each type at the same time.
Note: This implementation is extracted from shred
, with the
following differences:
Debug
implementation prints out the type name instead of type ID for the key.- Uses
downcast-rs
instead ofmopa
for downcasting types. - Adds
Debug
andPartialEq
implementations for borrow types when the resource type implements those traits. - Returns
Err
instead of panicking fortry_borrow*
functions when the resource is already borrowed.
Usage
Add the following to Cargo.toml
resman = "0.16.0"
# or
resman = { version = "0.17.2", features = ["debug"] }
resman = { version = "0.17.2", features = ["fn_res"] }
resman = { version = "0.17.2", features = ["fn_res", "fn_res_mut"] }
resman = { version = "0.17.2", features = ["fn_res", "fn_meta"] }
resman = { version = "0.17.2", features = ["fn_res", "fn_res_mut", "fn_meta"] }
# requires nightly
resman = { version = "0.17.2", features = ["fn_res", "fn_res_mut", "fn_res_once"] }
In code:
use resman::Resources;
#[derive(Debug)]
struct A(u32);
#[derive(Debug)]
struct B(u32);
let mut resources = Resources::default();
resources.insert(A(1));
resources.insert(B(2));
// We can validly have two mutable borrows from the `Resources` map!
let mut a = resources.borrow_mut::<A>();
let mut b = resources.borrow_mut::<B>();
a.0 = 2;
b.0 = 3;
// We need to explicitly drop the A and B borrows, because they are runtime
// managed borrows, and rustc doesn't know to drop them before the immutable
// borrows after this.
drop(a);
drop(b);
// Multiple immutable borrows to the same resource are valid.
let a_0 = resources.borrow::<A>();
let _a_1 = resources.borrow::<A>();
let b = resources.borrow::<B>();
println!("A: {}", a_0.0);
println!("B: {}", b.0);
// Trying to mutably borrow a resource that is already borrowed (immutably
// or mutably) returns `Err`.
let a_try_borrow_mut = resources.try_borrow_mut::<A>();
let exists = if a_try_borrow_mut.is_ok() {
"Ok(..)"
} else {
"Err"
};
println!("a_try_borrow_mut: {}", exists); // prints "Err"
Features
"debug"
:
The Debug
implementation for Resources
will use the Debug
implementation for the values when printed. This requires that all
Resources
to also implement Debug
.
Example:
use resman::Resources;
let mut resources = Resources::default();
resources.insert(1u32);
println!("{:?}", resources);
// Without `"debug"` feature:
// {u32: ".."}
// With `"debug"` feature:
// {u32: 1}
"fn_res"
:
Enables the FnRes
trait, allowing dynamic functions invocation under a
generic function type.
Usage of this API is as follows:
-
Define regular functions or closures to run.
- The functions should take
&T
or&mut T
as parameters. - The return type of all functions should be the same.
Currently there is a limit of 7 parameters.
- The functions should take
-
Call
my_function.into_fn_res()
to obtain aBox<dyn FnRes>
. -
Call
fn_res.call(&resources)
to automatically borrowT
fromresources
and invoke the function.
Example:
use resman::{FnRes, IntoFnRes, Resources};
/// Borrows `u32` mutably, and `u64` immutably.
fn f1(a: &mut u32, b: &u64) -> u64 {
*a += 1;
*a as u64 + *b
}
/// Borrows `u32` immutably, and `u64` mutably.
fn f2(a: &u32, b: &mut u64) -> u64 {
*b += 1;
*a as u64 + *b
}
let functions = [
f1.into_fn_res(),
f2.into_fn_res(),
(|a: &u32, b: &u64| *a as u64 + *b).into_fn_res(),
];
let mut resources = Resources::default();
resources.insert(0u32);
resources.insert(0u64);
let sum = functions
.iter()
.fold(0, |sum, fn_res| sum + fn_res.call(&resources));
assert_eq!(5, sum); // 1 + 2 + 2
let debug_str = format!("{:?}", resources);
assert!(debug_str.contains("u32: 1"));
assert!(debug_str.contains("u64: 1"));
Since Resources
has internal mutability, care must be taken to not run
multiple functions that borrow the same value mutably from Resources
at
the same time when using FnRes::call
, otherwise it will panic.
Use FnRes::try_call
for a non-panicking version, which will return a
BorrowFail
error if there is an overlapping borrow conflict at runtime.
"fn_res_mut"
:
Like "fn_res"
, enables the IntoFnResMut
and FnResMut
traits.
FnResMut
is implemented for functions and closures that impl FnMut
, but
not Fn
.
"fn_res_once"
:
Requires nightly
Like "fn_res_mut"
, enables the IntoFnResOnce
and FnResOnce
traits.
FnResOnce
is implemented for functions and closures that impl FnOnce
,
but not FnMut
.
"fn_meta"
:
Adds FnMeta
as an implied trait to FnRes
. This means function
metadata can be queried for any FnRes
.
"high_arg_count"
:
Raises the number of arguments that FnRes
, IntoFnRes
, and
IntoFnResource
are implemented for from 6 to 8.
This is feature gated because compilation time increasing significantly with
higher numbers of arguments -- as much as from 4 seconds for 6 arguments
to 26 seconds for 8 arguments when only "fn_res"
is enabled, and up to a
minute when "fn_mut"
and "fn_once"
are enabled.
See Also
anymap
: Map of any type, without multiple mutable borrows.rt_map
: Runtime managed mutable borrowing from a map.shred
: ContainsResources
type, plus a task dispatcher.
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Dependencies
~1MB
~22K SLoC