embassy-sync: add ResourcePool

[martin2250]

I think this would be a good addition to embassy-sync. I see two main uses:

• Managing similar peripherals (although in most cases it probably does matter which specific one you end up with)
• Managing larger buffers, similar to zerocopy_channel

I've mostly created it for the second case, because I needed to get around the limitations of zerocopy_channel.

The idea is that you can dynamically acquire a smart pointer to a shared resource, similar to MutexGuard, which you can then pass around between tasks.

Right now, the documentation is still incomplete because I want to ask for feedback first. Is this something you'd consider merging into embassy?

For a code example, see examples/stm32g4/src/bin/resource_pool.rs

Some TODOs:

• double-check the soundness of the implementation and lifetimes
• add proper documentation
• add map() function like Mutex?
• add dynamic versions of everything like DynamicChannel
• make new() const?
• reduce the size of the state by replacing the available Vec with an array of u32 and bit-masking (the reason I have not implemented that are that generic_const_exprs for calculating the number of u32s (ie. ceil(N/32)) are still unstable.

[diondokter]

Implementation looks fine to me. Got a couple of questions and notes though.

Whether this PR is actually accepted, well I'm not the endboss :P

[diondokter]

Make sure to add tests & more docs

[martin2250]

yes, absolutely!

[diondokter]

This is a weird API to me... When would you use this?
Especially the &mut U is weird to me. Where would the U be stored? In the closure? But then you get lifetime issues.

[martin2250]

embassy is already doing this with MutexGuard. It allows you to "narrow-down" a reference, eg. from a slice to only a sub-slice.

The main use I see here would be taking a buffer (eg. &mut [u8; 1024]), reading some data into it and then passing on a slice (&buffer[..n_bytes_read]) to the next part of your software. This works because the rust compiler will use fat pointers for pointers to slices (eg *mut/const [u8])

[diondokter]

Hmmm I guess. It's fine to have and the impl is fine. Just doesn't seem that useful to me