Implementing truly safe semaphores in rust

A couple of months ago there was a discussion on r/rust about why the standard library doesn't include a semaphore and I mentioned that it's a deceivingly difficult synchronization primitive to safely model in a rusty way. I ended up nerd-sniping myself into trying anyway [0], [1] and decided to share a writeup with some of the issues I ran into trying to come up with a safe and no/low-cost rusty interface for a semaphore.

It ended up being a great example of some of the things I love about the rust ecosystem (though it did also reveal some of the weaknesses of the rust ro^rw borrow semantics) in terms of the thought and care it takes to make an api that's resistant to misuse but still (hopefully) ergonomic.

[0]: https://github.com/neosmart/rsevents-extra

[1]: https://docs.rs/rsevents-extra/latest/rsevents_extra/struct....