Fix RwLock::try_write

[jgallagher]

Previously, try_write actually only obtained shared read access (but would return a RwLockWriteGuard if that access was successful).

Also updates the docs for try_read and try_write, which were leftover from when those methods returned Option instead of Result.

[rust-highfive]

r? @brson

(rust_highfive has picked a reviewer for you, use r? to override)

[brson]

Nominating for beta by request of the author.

[alexcrichton]

I believe that a poisoned rwlock will also return an Err even if it was successful in the try_read, so technically the lock could be locked if Err is returned. Perhaps the docs could be updated slightly to account for this?

[jgallagher]

I think the pre-existing Failure section covers this, but it's outside the diff of this PR (https://github.com/jgallagher/rust/blob/rwlock-try-write/src/libstd/sync/rwlock.rs#L187-L190). Is what it states incorrect, or should this paragraph be reworded to include it somehow?

[alexcrichton]

Hm ok so upon re-reading my original though that this indicates Err means the lock wasn't grabbed isn't quite right, it just means that if it couldn't be grabbed Err is returned, so looks good to me!

[alexcrichton]

Nice catch @jgallagher! Just one small nit from me on the doc updates and otherwise this is good to go.

[alexcrichton]

@bors: r+ 833fc27 p=10

[bors]

⌛ Testing commit 833fc27 with merge e6378cb...

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-32-nopt-t, auto-win-32-opt, auto-win-64-nopt-t, auto-win-64-opt