[go] runtime: document sudog

[Austin Clements (Gerrit)]

Reviewers: Keith Randall

Austin Clements uploaded a change:
https://go-review.googlesource.com/20774

runtime: document sudog

Change-Id: I85c0bcf02842cc32dbc9bfdcea27efe871173574
---
M src/runtime/runtime2.go
1 file changed, 10 insertions(+), 0 deletions(-)



diff --git a/src/runtime/runtime2.go b/src/runtime/runtime2.go
index 8977479..2fc45c3 100644
--- a/src/runtime/runtime2.go
+++ b/src/runtime/runtime2.go
@@ -210,6 +210,16 @@
bp uintptr // for GOEXPERIMENT=framepointer
}

+// sudog represents a g in a wait list, such as for sending/receiving
+// on a channel.
+//
+// sudog is necessary because the g ↔ synchronization object relation
+// is many-to-many. A g can be on many wait lists, so there may be
+// many sudogs for one g; and many gs may be waiting on the same
+// synchronization object, so there may be many sudogs for one object.
+//
+// sudogs are allocated from a special pool. Use acquireSudog and
+// releaseSudog to allocated and free them.
type sudog struct {
// The following fields are protected by the hchan.lock of the
// channel this sudog is blocking on. shrinkstack depends on

--
https://go-review.googlesource.com/20774
Gerrit-Reviewer: Keith Randall <k...@golang.org>

[Matthew Dempsky (Gerrit)]

Matthew Dempsky has posted comments on this change.

runtime: document sudog

Patch Set 1: Code-Review+1

Now I know!

--
https://go-review.googlesource.com/20774
Gerrit-Reviewer: Keith Randall <k...@golang.org>

Gerrit-Reviewer: Matthew Dempsky <mdem...@google.com>
Gerrit-HasComments: No

[Brad Fitzpatrick (Gerrit)]

Brad Fitzpatrick has posted comments on this change.

runtime: document sudog

Patch Set 1: Code-Review+2

--
https://go-review.googlesource.com/20774
Gerrit-Reviewer: Brad Fitzpatrick <brad...@golang.org>

[Ian Lance Taylor (Gerrit)]

Ian Lance Taylor has posted comments on this change.

runtime: document sudog

Patch Set 1:

(2 comments)

https://go-review.googlesource.com/#/c/20774/1/src/runtime/runtime2.go
File src/runtime/runtime2.go:

Line 213: // sudog represents a g in a wait list, such as for
sending/receiving
Perhaps it would help to explain briefly why the name "sudog" is a good one?


Line 222: // releaseSudog to allocated and free them.
s/allocated/allocate/

--
https://go-review.googlesource.com/20774
Gerrit-Reviewer: Brad Fitzpatrick <brad...@golang.org>

Gerrit-Reviewer: Ian Lance Taylor <ia...@golang.org>

Gerrit-Reviewer: Keith Randall <k...@golang.org>
Gerrit-Reviewer: Matthew Dempsky <mdem...@google.com>

Gerrit-HasComments: Yes

[Austin Clements (Gerrit)]

Austin Clements has posted comments on this change.

runtime: document sudog

Patch Set 1:

(2 comments)

https://go-review.googlesource.com/#/c/20774/1/src/runtime/runtime2.go
File src/runtime/runtime2.go:

Line 213: // sudog represents a g in a wait list, such as for
sending/receiving

> Perhaps it would help to explain briefly why the name "sudog" is a good
> one

Why is "sudog" a good name? I've never figured out what this stands for,
though it clearly has nothing to do with running commands as another
user. :)


Line 222: // releaseSudog to allocated and free them.
> s/allocated/allocate/
Done


--
https://go-review.googlesource.com/20774
Gerrit-Reviewer: Austin Clements <aus...@google.com>

[Ian Lance Taylor (Gerrit)]

Ian Lance Taylor has posted comments on this change.

runtime: document sudog

Patch Set 1:

(1 comment)

https://go-review.googlesource.com/#/c/20774/1/src/runtime/runtime2.go
File src/runtime/runtime2.go:

Line 213: // sudog represents a g in a wait list, such as for
sending/receiving

> Why is "sudog" a good name? I've never figured out what this stands for,
> th

I was afraid you were going to ask that question. I was hoping that you
knew.

Looks like Ken introduced it back in 2008 in revision
b78676a49d77f6bde1c54bc4a6389120e5a8c391. I have never known what it meant
and I'm unable to figure it out today.

[Austin Clements (Gerrit)]

Austin Clements has posted comments on this change.

runtime: document sudog

Patch Set 1:

(1 comment)

https://go-review.googlesource.com/#/c/20774/1/src/runtime/runtime2.go
File src/runtime/runtime2.go:

Line 213: // sudog represents a g in a wait list, such as for
sending/receiving

> I was afraid you were going to ask that question. I was hoping that you
> kn

I figured it was a Ken name. :)

Perhaps the name will just have to remain a mystery. At least the
functionality doesn't have to.

[Austin Clements (Gerrit)]

Reviewers: Matthew Dempsky, Brad Fitzpatrick

Austin Clements uploaded a new patch set:

https://go-review.googlesource.com/20774

runtime: document sudog

Change-Id: I85c0bcf02842cc32dbc9bfdcea27efe871173574
---
M src/runtime/runtime2.go
1 file changed, 10 insertions(+), 0 deletions(-)

[Austin Clements (Gerrit)]

Austin Clements has submitted this change and it was merged.

runtime: document sudog

Change-Id: I85c0bcf02842cc32dbc9bfdcea27efe871173574

Reviewed-on: https://go-review.googlesource.com/20774
Reviewed-by: Brad Fitzpatrick <brad...@golang.org>

---
M src/runtime/runtime2.go
1 file changed, 10 insertions(+), 0 deletions(-)

Approvals:
Brad Fitzpatrick: Looks good to me, approved

[Minux Ma (Gerrit)]

Minux Ma has posted comments on this change.

runtime: document sudog

Patch Set 1:

(1 comment)

https://go-review.googlesource.com/#/c/20774/1/src/runtime/runtime2.go
File src/runtime/runtime2.go:

Line 213: // sudog represents a g in a wait list, such as for
sending/receiving

> I figured it was a Ken name. :)

I always assumed it was a short for "pseudo".

for example, the compiler also have a func called "sudoaddable".

--
https://go-review.googlesource.com/20774
Gerrit-Reviewer: Austin Clements <aus...@google.com>
Gerrit-Reviewer: Brad Fitzpatrick <brad...@golang.org>
Gerrit-Reviewer: Ian Lance Taylor <ia...@golang.org>
Gerrit-Reviewer: Keith Randall <k...@golang.org>
Gerrit-Reviewer: Matthew Dempsky <mdem...@google.com>

Gerrit-Reviewer: Minux Ma <mi...@golang.org>
Gerrit-HasComments: Yes

[Austin Clements (Gerrit)]

Austin Clements has posted comments on this change.

runtime: document sudog

Patch Set 1:

(1 comment)

https://go-review.googlesource.com/#/c/20774/1/src/runtime/runtime2.go
File src/runtime/runtime2.go:

Line 213: // sudog represents a g in a wait list, such as for
sending/receiving

> I always assumed it was a short for "pseudo".

That would be my guess, too. But in what way is it sort of like a g? My
best guess (and now I'm piling guesses on guesses) is that the "pseudo" g
evolved because, prior to select, the wait link used to be in the g struct
itself (since a g could only be on one wait list at a time). Now the thing
on the wait list isn't a g at all, but it used to be, hence whatever's on
the wait list can't be completely unlike a g, hence it's sort of a g.