aboutsummaryrefslogtreecommitdiff
path: root/src/runtime/HACKING.md
AgeCommit message (Collapse)Author
2022-08-19runtime: add and use runtime/internal/sys.NotInHeapCuong Manh Le
Updates #46731 Change-Id: Ic2208c8bb639aa1e390be0d62e2bd799ecf20654 Reviewed-on: https://go-review.googlesource.com/c/go/+/421878 Reviewed-by: Keith Randall <khr@google.com> Reviewed-by: Keith Randall <khr@golang.org> Reviewed-by: Matthew Dempsky <mdempsky@google.com> TryBot-Result: Gopher Robot <gobot@golang.org> Run-TryBot: Cuong Manh Le <cuong.manhle.vn@gmail.com>
2022-06-13runtime: add HACKING section on nosplit functionsAustin Clements
Change-Id: I247874d5c49d2c0d8db2a3d227aa848093551d9b Reviewed-on: https://go-review.googlesource.com/c/go/+/401759 Reviewed-by: Michael Pratt <mpratt@google.com>
2022-05-17runtime: fix code span elementJohn Bampton
Change-Id: I99c593573b3bec560ab3af49ac2f486ee442ee1c GitHub-Last-Rev: e399ec50f9dde9229e05f801fd752694cc661822 GitHub-Pull-Request: golang/go#52946 Reviewed-on: https://go-review.googlesource.com/c/go/+/406837 TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Michael Knyszek <mknyszek@google.com> Reviewed-by: Ian Lance Taylor <iant@google.com> Run-TryBot: Ian Lance Taylor <iant@google.com> Auto-Submit: Michael Knyszek <mknyszek@google.com>
2022-04-28runtime: simply user throws, expand runtime throwsMichael Pratt
This gives explicit names to the possible states of throwing (-1, 0, 1). m.throwing is now one of: throwTypeOff: not throwing, previously == 0 throwTypeUser: user throw, previously == -1 throwTypeRuntime: runtime throw, previously == 1 For runtime throws, we now always include frame metadata and system goroutines regardless of GOTRACEBACK to aid in debugging the runtime. For user throws, we no longer include frame metadata or runtime frames, unless GOTRACEBACK=system or higher. For #51485. Change-Id: If252e2377a0b6385ce7756b937929be4273a56c0 Reviewed-on: https://go-review.googlesource.com/c/go/+/390421 Run-TryBot: Michael Pratt <mpratt@google.com> TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Michael Knyszek <mknyszek@google.com> Reviewed-by: Austin Clements <austin@google.com>
2022-04-28runtime: differentiate "user" and "system" throwsMichael Pratt
"User" throws are throws due to some invariant broken by the application. "System" throws are due to some invariant broken by the runtime, environment, etc (i.e., not the fault of the application). This CL sends "user" throws through the new fatal. Currently this function is identical to throw, but with a different name to clearly differentiate the throw type in the stack trace, and hopefully be a bit more clear to users what it means. This CL changes a few categories of throw to fatal: 1. Concurrent map read/write. 2. Deadlock detection. 3. Unlock of unlocked sync.Mutex. 4. Inconsistent results from syscall.AllThreadsSyscall. "Thread exhaustion" and "out of memory" (usually address space full) throws are additional throws that are arguably the fault of user code, but I've left off for now because there is no specific invariant that they have broken to get into these states. For #51485 Change-Id: I713276a6c290fd34a6563e6e9ef378669d74ae32 Reviewed-on: https://go-review.googlesource.com/c/go/+/390420 TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Austin Clements <austin@google.com> Run-TryBot: Michael Pratt <mpratt@google.com>
2022-04-21cmd/compile: add //go:uintptrkeepaliveMichael Pratt
This CL exports the existing ir.UintptrKeepAlive via the new directive //go:uintptrkeepalive. This makes the compiler insert KeepAlives for pointers converted to uintptr in calls, keeping them alive for the duration of the call. //go:uintptrkeepalive requires //go:nosplit, as stack growth can't handle these arguments (it cannot know which are pointers). We currently check this on the immediate function, but the actual restriction applies to all transitive calls. The existing //go:uintptrescapes is an extension of //go:uintptrkeepalive which forces pointers to escape to the heap, thus eliminating the stack growth issue. This pragma is limited to the standard library. For #51087 Change-Id: If9a19d484d3561b4219e5539b70c11a3cc09391e Reviewed-on: https://go-review.googlesource.com/c/go/+/388095 Run-TryBot: Michael Pratt <mpratt@google.com> Reviewed-by: Matthew Dempsky <mdempsky@google.com> TryBot-Result: Gopher Robot <gobot@golang.org>
2020-09-25runtime: update go:notinheap documentationAustin Clements
The rules for go:notinheap were recently tweaked to disallow stack allocation (CL 249917). This CL updates the documentation about go:notinheap in runtime/HACKING.md. Change-Id: Ibca5d9b9d02e1c22c6af1d303aa84c6303a86d92 Reviewed-on: https://go-review.googlesource.com/c/go/+/257357 Trust: Austin Clements <austin@google.com> Reviewed-by: Keith Randall <khr@golang.org>
2018-11-30runtime: fix heap pointer invariant rules in HACKING.mdMichael Anthony Knyszek
This change fixes an error in HACKING.md which claims all pointers which live in unmanaged memory but point to the heap must be marked as GC roots explicitly by runtime.markroot. This isn't technically necessary if the pointer is accessible through a global variable. Change-Id: I632b25272fdb2f789c5259dd1685d517f45fd435 Reviewed-on: https://go-review.googlesource.com/c/151539 Reviewed-by: Rick Hudson <rlh@golang.org>
2018-07-11runtime: document philosophy behind runtime atomic usageAustin Clements
Based on Dmitry Vyukov's comments in CL 65210. Change-Id: I5dce7286b0d180cd43cad3aaf70f537fafcda588 Reviewed-on: https://go-review.googlesource.com/123275 Reviewed-by: Ian Lance Taylor <iant@golang.org> Reviewed-by: Rick Hudson <rlh@golang.org> Reviewed-by: Dmitry Vyukov <dvyukov@google.com>
2017-06-28runtime: make rwmutex work on Ms instead of GsAustin Clements
Currently runtime.rwmutex is written to block the calling goroutine rather than the calling thread. However, rwmutex was intended to be used in the scheduler, which means it needs to be a thread-level synchronization primitive. Hence, this modifies rwmutex to synchronize threads instead of goroutines. This has the consequence of making it write-barrier-free, which is also important for using it in the scheduler. The implementation makes three changes: it replaces the "w" semaphore with a mutex, since this was all it was being used for anyway; it replaces "writerSem" with a single pending M that parks on its note; and it replaces "readerSem" with a list of Ms that park on their notes plus a pass count that together emulate a counting semaphore. I model-checked the safety and liveness of this implementation through >1 billion schedules. For #20738. Change-Id: I3cf5a18c266a96a3f38165083812803510217787 Reviewed-on: https://go-review.googlesource.com/47071 Run-TryBot: Austin Clements <austin@google.com> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Ian Lance Taylor <iant@golang.org>
2017-04-13runtime: generalize {alloc,free}Stack to {alloc,free}ManualAustin Clements
We're going to start using manually-managed spans for GC workbufs, so rename the allocate/free methods and pass in a pointer to the stats to use instead of using the stack stats directly. For #19325. Change-Id: I37df0147ae5a8e1f3cb37d59c8e57a1fcc6f2980 Reviewed-on: https://go-review.googlesource.com/38576 Run-TryBot: Austin Clements <austin@google.com> Reviewed-by: Rick Hudson <rlh@golang.org>
2017-01-06runtime: expand HACKING.mdAustin Clements
This adds high-level descriptions of the scheduler structures, the user and system stacks, error handling, and synchronization. Change-Id: I1eed97c6dd4a6e3d351279e967b11c6e64898356 Reviewed-on: https://go-review.googlesource.com/34290 Reviewed-by: Rick Hudson <rlh@golang.org>
2016-10-28runtime: document rules about unmanaged memoryAustin Clements
Updates #17503. Change-Id: I109d8742358ae983fdff3f3dbb7136973e81f4c3 Reviewed-on: https://go-review.googlesource.com/31452 Reviewed-by: Keith Randall <khr@golang.org> Reviewed-by: Rick Hudson <rlh@golang.org>
2016-10-15cmd/compile: add go:notinheap type pragmaAustin Clements
This adds a //go:notinheap pragma for declarations of types that must not be heap allocated. We ensure these rules by disallowing new(T), make([]T), append([]T), or implicit allocation of T, by disallowing conversions to notinheap types, and by propagating notinheap to any struct or array that contains notinheap elements. The utility of this pragma is that we can eliminate write barriers for writes to pointers to go:notinheap types, since the write barrier is guaranteed to be a no-op. This will let us mark several scheduler and memory allocator structures as go:notinheap, which will let us disallow write barriers in the scheduler and memory allocator much more thoroughly and also eliminate some problematic hybrid write barriers. This also makes go:nowritebarrierrec and go:yeswritebarrierrec much more powerful. Currently we use go:nowritebarrier all over the place, but it's almost never what you actually want: when write barriers are illegal, they're typically illegal for a whole dynamic scope. Partly this is because go:nowritebarrier has been around longer, but it's also because go:nowritebarrierrec couldn't be used in situations that had no-op write barriers or where some nested scope did allow write barriers. go:notinheap eliminates many no-op write barriers and go:yeswritebarrierrec makes it possible to opt back in to write barriers, so these two changes will let us use go:nowritebarrierrec far more liberally. This updates #13386, which is about controlling pointers from non-GC'd memory to GC'd memory. That would require some additional pragma (or pragmas), but could build on this pragma. Change-Id: I6314f8f4181535dd166887c9ec239977b54940bd Reviewed-on: https://go-review.googlesource.com/30939 Reviewed-by: Keith Randall <khr@golang.org> Reviewed-by: Matthew Dempsky <mdempsky@google.com>
2016-10-15cmd/compile, runtime: add go:yeswritebarrierrec pragmaAustin Clements
This pragma cancels the effect of go:nowritebarrierrec. This is useful in the scheduler because there are places where we enter a function without a valid P (and hence cannot have write barriers), but then obtain a P. This allows us to annotate the function with go:nowritebarrierrec and split out the part after we've obtained a P into a go:yeswritebarrierrec function. Change-Id: Ic8ce4b6d3c074a1ecd8280ad90eaf39f0ffbcc2a Reviewed-on: https://go-review.googlesource.com/30938 Reviewed-by: Matthew Dempsky <mdempsky@google.com> Reviewed-by: Keith Randall <khr@golang.org>