time: is documented as safe for concurrent use, but unmarshal methods do not synchronize

[nicholasmaniscalco]

time.Time is documented as being safe for concurrent use, however, some methods modify it without synchronization: GobDecode, UnmarshalBinary, UnmarshalJSON, and UnmarshalText.

It seems like we should update the documentation. What's the right way to document the goroutine-safety guarantee? Something like:

"A Time value can be used by multiple goroutines simultaneously so long as no goroutine calls an unmarshaler method (t.GobDecode, t.UnmarshalBinary, t.UnmarshalJSON, t.UnmarshalText)." ?

[gopherbot]

CL https://golang.org/cl/40390 mentions this issue.

[ianlancetaylor]

Just commented on the CL: The unmarshaler methods by definition modify the receiver. Is this something that confuses people in practice?

[nicholasmaniscalco]

(moving conversation from the CL to the issue)

Probably not. I just came across this and it seemed like the documentation wasn't completely accurate.

Since the docs say "A Time value can be used by multiple goroutines simultaneously" I was expecting the unmarshaler methods to modify the receiver atomically.

As it stands now, there's a potential data race if a Time is shared by two goroutines and one of them calls an unmarshaler method.

It seems unlikely to cause a real problem, but I figured it's worth making the docs more accurate.