sync: Package sync should have examples

[gopherbot]

by aaron.l.france:

The sync package documentation would be greatly improved if each type (Mutex/RWMutex
etc) had a section for an example. To some people an RWMutex is quite foreign.

-Aaron

[ianlancetaylor]

Comment 1:

Labels changed: added priority-later, documentation, removed priority-triage.

Owner changed to @dvyukov.

[adg]

Comment 2:

It should have _more_ examples: http://golang.org/pkg/sync/#pkg-examples

[gopherbot]

Comment 3 by aaron.l.france:

Sorry, yes. More.

[fatih]

Comment 4:

I was the one who asked this on IRC too. I was confused because google didn't return any
page for "mutex" vs "rwmutex". And the documentation didn't have any example. Aaron did
help with a trivial example and than It was really easy to understand it

[dvyukov]

Comment 5:

FTR:
https://groups.google.com/forum/#!search/"Examples$20for$20sync$20package"/golang-dev/LHmIq7mJ5ZY/45kytJmiXUgJ
There also were this lost response from Russ:
------
It would be good to have examples for WaitGroup and Once.
I think Mutex and RWMutex probably don't need examples,
and Cond is low level enough that I'd rather not encourage
use of it.

[gopherbot]

Comment 6 by aaron.l.france:

I vehemently disagree with them not needing examples. If required I can
post some examples up myself, for review.

[robpike]

Comment 7:

Status changed to Accepted.

[rsc]

Comment 8:

Labels changed: added go1.2.

[dvyukov]

Comment 9:

Owner changed to @adg.

[adg]

Comment 10:

Dmitry says (and I agree) that "People who already know what the mutex is do not need
the example."
But let's go further—people who don't know what the mutex is do not need a mutex.

Status changed to WontFix.

[fatih]

Comment 11:

The problem is, the example is not needed for understanding mutex. It is needed for
understanding the difference between RWMutex and Mutex. The doc's are not clear on that.
I hope you consider that.

[adg]

Comment 12:

I have given the matter a lot of considered thought. Using these primitives correctly is
not something that can be learned by reading a couple of examples in the standard
library.

[cznic]

Comment 13:

FTR: http://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock

[gopherbot]

Comment 14 by aaron.l.france:

Perhaps I should have been clearer. My reasoning for asking for docs was
that for newbies to the language (and concurrent languages in general) then
a Mutex and an RWMutex is going to be something which requires an
explanation of the differences.