# broomdog 🧹🐕

`broomdog` is a Rust library providing a map of type-erased values with indefinite loanership semantics.

## what is a type map?

`broomdog`'s type map is a map of `std::any::TypeId` keys to type-erased values.
There may be at most one value for each key, which means the map stores singleton values of different types.

## why another type map library?

`broomdog` provides the usual map-like API, and then some.
Notably `broomdog` provides "indefinite loanership".

### wtf is indefinite loanership?

It's a wordsmush that roughly means you can borrow a value from the map without
a lifetime.

#### wtf is a loaned value?

A loaned value is a smart pointer to a value that you can `deref` or `deref_mut`.

You may only have one exclusive (write) loan of any one type at a time, but you may have as many non-exclusive (read) loans of the same type as you like. You may also have **multiple exclusive loans of _different_ types at the same time**.

After an exclusive loan is dropped you may make another exclusive loan of the same type, or multiple non-exclusive loans of that type.

This allows you to make multiple loans of different types at the same time, without map borrow conflicts - so long as you don't try to share an exclusive loan of the same type at the same time.

Furthermore, `broomdog` has nice descriptive errors with the names of the types (more even, if compiled with `debug_assertions`).

## uses

Type erased maps have many uses, but `broomdog` was built to facilitate the following:

* singleton resource storage layer for [`apecs`](https://github.com/schell/apecs)'s system schedule runner (`apecs` is an ECS library)
* singleton resource storage layer for [`renderling`](https://github.com/schell/renderling)'s render node schedule runner (part of the render graph)

It works particularly well with [`dagga`](https://github.com/schell/dagga), which is a DAG scheduler. In fact, `dagga` and `broomdog` are joined in [`moongraph`](https://github.com/schell/moongraph) with some nice helpers to form a DAG scheduling, resource managment and execution library.

Together it's possible to define and run an extensible system of functions that share mutable resources, some of which may run in parallel.


## why (the heck) did you name it `broomdog`

* "broomdog" is the name of the part broom / part dog character in Alice in Wonderland that erases the path as it walks along it.

* I think names should be funny.

* It's my library, oh well 😏.

# example

```rust
use broomdog::{TypeMap, TypeKey};

let mut map = TypeMap::default();
assert!(map.insert_value(0usize).unwrap().is_none());
assert!(map.insert_value(0.0f32).unwrap().is_none());
assert!(map.insert_value("hello").unwrap().is_none());

{
    let num_usize = map.get_value_mut::<usize>().unwrap().unwrap();
    *num_usize += 666;
}
assert_eq!(666, *map.get_value::<usize>().unwrap().unwrap());
assert_eq!("hello", *map.get_value::<&str>().unwrap().unwrap());

{
    let loan = map.loan(TypeKey::new::<usize>()).unwrap().unwrap();
    assert_eq!(666, *loan.downcast_ref::<usize>().unwrap());
    let loan2 = map.loan(TypeKey::new::<usize>()).unwrap().unwrap();
    assert_eq!(666, *loan2.downcast_ref::<usize>().unwrap());

    let mut loan_mut = map.loan_mut(TypeKey::new::<&str>()).unwrap().unwrap();
    let word = loan_mut.downcast_mut::<&str>().unwrap();
    assert_eq!("hello", *word);
    *word = "goodbye";
}

map.unify().unwrap();
```