tokio-sync: Add async mutual exclusion primitive

[jonhoo]

This PR introduces Lock: A concurrency primitive built on top of Semaphore that provides a Mutex-like primitive that interacts nicely with futures. Specifically, LockGuard (in contrast to MutexGuard) does not borrow the Lock, and can thus be passed into a future where it will later be unlocked.

This replaces #958, which attempted to introduce a less generic version. The primitive proposed there will instead live in async-lease.

[jonhoo]

@hawkw Thanks! Should both be addressed now.

[carllerche]

Lgtm thanks.

[carllerche]

@jonhoo

Given what it takes to make the feature flags work, do you think it is worth forwarding the read / write impls? They are usable via Deref and DerefMut. The main issue would be passing a LockGuard<TcpStream> to something that requires T: AsyncRead + AsyncWrite.

I believe @seanmonstar is wondering if the forwards are worth it, but he is not a strong -1 on it, so it is up to you.

[jonhoo]

It would make the example a little nicer I think, but I don't know how common the pattern is in practice. I'd be okay getting rid of them.

[carllerche]

@jonhoo Ok, just in the spirit of getting something out, I will opt for the conservative option and remove the impls + feature flag junk. If it turns out to be annoying, we can always bring it back later.

[carllerche]

@jonhoo let me know if this looks good to you.

[jonhoo]

@carllerche oh, I think the Stream, Sink, and Future impls should still stick around!

[carllerche]

@jonhoo do you have a “real” example where they are needed? I’m most hesitant because the std version does not forward. We also can always add it later once there is a clear example in support.

[jonhoo]

Forwarding Sink, Stream, and Future means that you can now use the guard with combinators that consume self, which is pretty much all of them. You can't do that if the guard doesn't forward (i.e., just through Deref).

[seanmonstar]

Should someone really use the combinators on a guard? That would mean keeping the lock even though the combinator isn't ready yet.

[jonhoo]

@seanmonstar I think that's totally reasonable. I'm specifically imagining a case like sharing a single-threaded connection-like object to send a single object. You take the lock, use the send combinator, and then release the lock.