Navigation Menu

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
Closed

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

rogpeppe opened this issue Mar 10, 2011 · 7 comments

Comments

@rogpeppe
Copy link
Contributor

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
Copy link
Contributor

adg 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
Copy link
Contributor Author

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
Copy link
Contributor

rsc commented Dec 9, 2011

Comment 3:

Labels changed: added priority-later.

@rsc
Copy link
Contributor

rsc commented Dec 12, 2011

Comment 4:

Labels changed: added priority-go1.

@robpike
Copy link
Contributor

robpike commented Jan 13, 2012

Comment 5:

Owner changed to builder@golang.org.

@rsc
Copy link
Contributor

rsc commented Jan 30, 2012

Comment 7:

Labels changed: added go1-must.

@rsc
Copy link
Contributor

rsc 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
@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.
Projects
None yet
Development

No branches or pull requests

5 participants