From: Austin Clements Date: Wed, 2 Aug 2017 19:54:05 +0000 (-0400) Subject: runtime: make (Un)LockOSThread doc more prescriptive X-Git-Tag: go1.10beta1~777 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=0aef82aa4a301a7914e6a38d6e3d4722a6e1c547;p=gostls13.git runtime: make (Un)LockOSThread doc more prescriptive Right now users have to infer why they would want LockOSThread and when it may or may not be appropriate to call UnlockOSThread. This requires some understanding of Go's internal thread pool implementation, which is unfortunate. Improve the situation by making the documentation on these functions more prescriptive so users can figure out when to use them even if they don't know about the scheduler. Change-Id: Ide221791e37cb5106dd8a172f89fbc5b3b98fe32 Reviewed-on: https://go-review.googlesource.com/52871 Run-TryBot: Austin Clements TryBot-Result: Gobot Gobot Reviewed-by: Keith Randall --- diff --git a/src/runtime/proc.go b/src/runtime/proc.go index 1e41a020bb..165b04eb43 100644 --- a/src/runtime/proc.go +++ b/src/runtime/proc.go @@ -3433,6 +3433,9 @@ func dolockOSThread() { // UnlockOSThread as to LockOSThread. // If the calling goroutine exits without unlocking the thread, // the thread will be terminated. +// +// A goroutine should call LockOSThread before calling OS services or +// non-Go library functions that depend on per-thread state. func LockOSThread() { if atomic.Load(&newmHandoff.haveTemplateThread) == 0 { // If we need to start a new thread from the locked @@ -3475,6 +3478,13 @@ func dounlockOSThread() { // calling goroutine to zero, it unwires the calling goroutine from // its fixed operating system thread. // If there are no active LockOSThread calls, this is a no-op. +// +// Before calling UnlockOSThread, the caller must ensure that the OS +// thread is suitable for running other goroutines. If the caller made +// any permanent changes to the state of the thread that would affect +// other goroutines, it should not call this function and thus leave +// the goroutine locked to the OS thread until the goroutine (and +// hence the thread) exits. func UnlockOSThread() { _g_ := getg() if _g_.m.lockedExt == 0 {