GoLang Runtime

The Go runtime might seem mysterious at first glance, but is it, really? Coming from a C/C++ background, it is easy to assume that Go is just like C++, after all, both languages compile to native binaries, how different can Go be? When I first started out on this investigation, I thought it couldn't be that different, but comments from expert Go programmers soon destroyed that idea.

Most Go documentation is rightly targeted at Go programmers, not operating system designers. A side-effect of this is that it is possible to use Go without understanding what it is (which can be a good thing). However, this is akin to a novice Java programmer thinking they are writing native binaries, which, unless they're using GCJ, is probably not what they are actually doing. It is nice to have a surface understanding of Go's features such as garbage collection and interface types, and I/O blocking, but without having a complete understanding of how these are implemented down to the core, it is far too easy to misuse and abuse the runtime in surprising ways. As such, what I was looking for was an in-depth per-platform exposition of how the stack works, along with other nitty gritty details. This feature, also known as segmented stacks, is a very popular feature, but most documentation that discusses this feature was more brief than I would have liked. More in-depth documentation is really hard to find - but I found it - in three files in the go/src/pkg/runtime/ directory:

proc.c
stack.h
runtime.h
To overview the Go runtime internals, we can start with the functions listed in the runtime.h header. These functions are implemented in C, but are only available in Go to the runtime package, and so they are partially undocumented. My goal is not to encourage you to use them; it is only to document and expose the internals of the runtime, so as to dispell the mystery. Once the internals of the runtime are clear, you should use Go, not C. The C functions that follow come straight from runtime.h with the math functions (which have nothing to do with segmented stacks) and the runtime prefix removed:

addfinalizer allocmcache asmcgocall asminit breakpoint call callers cas casp catstring chancap chanlen chanrecv chansend charntorune cputicks dopanic efaceeq_c efacehash entersyscall exit exit1 exitsyscall fastrand1 findfunc free funcline futexsleep futexwakeup gcount gentraceback getcallerpc getcallersp getenv getu goargs gobytes goenvs goenvs_unix goexit gogo gogocall gomaxprocsfunc goroutineheader gosave gosched gostring gostringn gostringnocopy gostringw gotraceback ifaceE2I ifaceeq_c ifacehash initsig jmpdefer lessstack lock madvise makechan_c makemap_c mal malg malloc mallocinit mapaccess mapassign mapiterkey mapiterkeyvalue mapiternext mcall mchr mcmp mcount memclr memlimit memmove mincore minit mmap munmap nanotime newm newosproc newproc1 noteclear notesleep notetsleep notewakeup osyield panic panicindex panicslice panicstring printany printf prints procyield ready resetcpuprofiler runetochar runpanic semacquire semacreate semasleep semawakeup semrelease setcallerpc setcpuprofilerate setprof showframe sigenable signalstack sigprof sigsend stackalloc stackfree startpanic starttheworld stoptheworld throw traceback tracebackothers tsleep unlock usleep write
The Go runtime is similar to the C standard library (libc), but is written portably so that it works on Windows and Mac platforms, on Intel and ARM architectures, and on gc (the primary Go compiler) and gccgo compilers. The functions look similar enough to libc, but some have nonstandard names. For example, runtime·charntorune() is similar to mbtowc(), and runtime·runetochar() is similar to wctomb(), only without the extra headache of trying to determine how big your platform's wchar_t is. In Go, the rune type is defined to be int32 on every platform.

In addition to the functions listed above, there are also many structures in runtime.h, any you may recognize some of them. Structures such as Slice, String, ChanType, MapType, are easily mapped to their equivalents in Go, but there are more that may not seem familiar. Two structures in particular that I would like to focus on are G and M, which are obviously the most mysterious names ever. As a Go user, I had no part in making decisions about naming systems, so I can't be sure about this, but I think they stand for Goroutines and Machines respectively.

For example, suppose you had a dual-core CPU, and you launched 4 goroutines. Then with this definition, you would have 2 M structs (one for each CPU) and 6 G structs, 4 for the goroutines you just launched, 1 for the goroutine you launched them from, and 1 for the idle goroutine.