rsevents-extra VS rsevents

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....

A couple of months ago, there was a discussion here on r/rust about why there's no semaphore in the rust standard library. I mentioned that it's a deceivingly difficult type to model in a way that would be appropriate for rust's std, but nerd-sniped myself into writing my own (docs.rs link) and thought there might be some interest in the tradeoffs involved and what makes it a difficult synchronization primitive to safely model in a rusty way, and so here we are.

Rust’s synchronization types are built on the semantics of shared objects, with the synchronization object owning the data access to which is channeled exclusively via the synchronization type.

Events and signals aren’t intended to be used off you’re trying to share ownership of memory or data - you should use the std types in that case. They’re for signaling between threads or for building your own synchronization objects atop of. For example, an auto reset event can be used in lieu of a one-bit channel (sort of like Mpmc<()>) and manual reset events can be used to implement the same in broadcast mode, much more efficiently than the channel crates. A common usage is to block until an event is available or a shutdown has been requested - in lieu of manually polling an AtomicBool and aborting if it is true, making your code more responsive (no delay between polls) and more efficient (no repeated polling, no busy waits, etc). They can be used to signal state transitions or readiness, which doesn’t have anything to “own”, for example, the rsevents-extra crate [0] implements a countdown event (event becomes available when n outstanding tasks have finished in parallel threads) or a semaphore (restricting concurrency to a region of code, not limiting access to a variable or object).

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

rsevents-extra v0.2.0 has been published to crates.io and is available under the MIT license on GitHub. The repository README is just a rundown of the crate's components and doesn't contain any code or examples, but the crate documentation has been thoroughly overhauled and contains extensive type- and function-level documentation plus examples.

Thanks. Perhaps I did go overboard with that disclaimer.. probably because I myself made the mistake of initially using [0] the oh-so-convenient tokio::io::copy() instead of writing my own copy method that would drop the other half of the connection when one side was closed.

The copy_with_abort() routine is still taking the easy way out in this not-optimized-for-heavy-production-use sample because it uses a broadcast channel per connection to reactively signal that the other half of the connection should be closed (rather than timing out every x ms to see if an abort flag has been set). In the real world, I'd probably replace the join! macro with a manual event loop to be able to do the same but without creating a broadcast channel per-connection.

(I maintain an extremely lightweight "awaitable bools" library for rust [1] that is perfect for this kind of thing (roughly equivalent to a "bounded broadcast_channel<()> of queue length 1, but each "channel" is only a single (optionally stack-allocated) byte) — but it's for event loops in synchronous code and not async executor compatible.)

[0]: https://github.com/mqudsi/tcpproxy/commit/0164ef836a49f2f738...

[1]: https://github.com/neosmart/rsevents

The AutoResetEvent takes care of that, doing Acquire and Release as needed. Source code here if you’re interested, not too long: https://github.com/neosmart/rsevents/blob/master/src/lib.rs

I wrote my own FOSS signals/events library in C++ [0] and in rust [1] (atop of parking lot as a futex shoe-in) and I disagree. This has nothing to do with the language and everything to do with the semantics of the locks. Writing concurrency primitives is HARD and the more functionality your API exposes, the more room there is for nuanced bugs in how everything interplays with everything else.

[0]: https://github.com/neosmart/pevents

[1]: https://github.com/neosmart/rsevents

rsevents-extra types are built on top of the low-level synchronization types from the rsevents crate, which are fast and tiny (one-byte) Send + Sync synchronization types for signalling one or more waiting threads (à la WIN32 events), doing everything but putting a thread to sleep in userland.