Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

io, net: document methods safe to call concurently #1599

Closed
rogpeppe opened this issue Mar 10, 2011 · 7 comments

Comments

Projects
None yet
5 participants
@rogpeppe
Copy link
Contributor

commented Mar 10, 2011

io.Pipe and the net.Conn implementations are specifically written so
that it is ok, and sometimes necessary, to call some methods concurrently
(for example Read, Write and Close).

For other types (for example bufio.Reader) it is incorrect to call methods concurrently.

There appears to be nothing in the documentation that makes
this distinction clear.
@adg

This comment has been minimized.

Copy link
Contributor

commented Mar 14, 2011

Comment 1:

What examples are you thinking of, specifically? Closing during a Read or Write?
I'm not sure whether a wide-reaching documentation change is appropriate, or whether a
few select culprits should be better-documented.

Labels changed: added documentation.

Owner changed to a...@golang.org.

Status changed to Accepted.

@rogpeppe

This comment has been minimized.

Copy link
Contributor Author

commented Mar 14, 2011

Comment 2:

I'm specifically thinking of:
   Close during Read or Write
   Read/Write during Read or Write (is Write during Write ok?)
   Close during Accept
Types that I can think of are:
net.IPConn, net.TCPConn, net.UDPConn, net.UnixConn
net.TCPListener, net.UnixListener
io.Pipe
One way of catching all the above with a small change
would be to change the documentation of net.Conn
and net.Listener to explicitly allow concurrent calls,
making it clear that to fit with existing expectations,
any new implementation of net.Conn must allow concurrent
calls.
Then any type implementing Close, for instance,
may document that it is implementing net.Conn.Close,
which implies that it may be called concurrently.
Some types in other packages that might want to document
allowable concurrent method calls:
rpc.Client
netchan.Exporter
http.Client, http.ServerConn, http.ClientConn, ...
reflect.Value
time.Time
Any more?
Some other packages might want some documentation the other way.
It seems that in general it is OK to call package-level
function concurrently. That's not true in all cases
(for instance, the flag package, gob.Register).
Any more of these?
Another area which could probably do with a sentence of annotation
is the sync package - yes, it's "obvious" that it's OK to call
Mutex.Lock concurrently with Mutex.Unlock, but perhaps
it doesn't hurt to state the obvious.
@rsc

This comment has been minimized.

Copy link
Contributor

commented Dec 9, 2011

Comment 3:

Labels changed: added priority-later.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Dec 12, 2011

Comment 4:

Labels changed: added priority-go1.

@robpike

This comment has been minimized.

Copy link
Contributor

commented Jan 13, 2012

Comment 5:

Owner changed to builder@golang.org.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Jan 30, 2012

Comment 7:

Labels changed: added go1-must.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Mar 7, 2012

Comment 8:

This issue was closed by revision babbf94.

Status changed to Fixed.

@rsc rsc added this to the Go1 milestone Apr 10, 2015

@rsc rsc removed priority-go1 labels Apr 10, 2015

@golang golang locked and limited conversation to collaborators Jun 24, 2016

This issue was closed.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.