Extend Events to support tokens for listeners.

[withoutboats]

The Event and EventListener types become parameterized by a new type T, which represents the type of the token that is passed with each notifitication. This type is () by default, unless specified otherwise by users. This allows users to pass tokens from the notifier to the listener with new notify_with_token APIs. The EventListener Future now resolves to its token type, instead of always resolving to ().

An example use case is a Mutex which, like the parking_lot Mutex, can pass the lock directly on to the next waiting listener, without ever actually unlocking the Mutex's state.

This change was done backwards compatibly, so APIs which previous relied on the absence of a token type (like the existing notify APIs, and some of the wait APIs) are only provided by events which have no token, whereas new APIs with tokens are added additionally.

Events with tokens can only notify one event at a type. It would be interesting to extend this to support passing multiple tokens to notify multiple listeners at once, with tokens. The best API I can think of would rely on min_const_generics (and so be unsuitable as an additional right now) but would look like this:

impl<T> Event<T> {
     pub fn notify_with_tokens<const N: usize>(&self, tokens: [T; N]) {
          // ...
     }
}

@stjepang This is just an idea I had that seemed like an easy extension. I don't have any compelling and urgent need for this functionality (yet, at least!) If you're not interested in supporting it, that's cool with me, I just wanted to explore the possibility.

[ghost]

Sorry I haven't had the time to review this yet, been kinda swamped for the last two weeks :(

Glancing over it, this is a change I've also wanted before so it seems good to me. I also feel open to adding new APIs and experimenting with this crate in general.

Would you perhaps like push/publish permissions on this crate so you're not always blocked on me?

[withoutboats]

@stjepang I wouldn't mind, but I haven't been blocked on this at all. It was also just an idea I wanted to explore!

[notgull]

Superseded by #52