doc: add internals FAQ?

[bradfitz]

@bcantrill asked of Go recently:

I've never gotten a straight answer as to why Go makes system calls directly instead of doing what every other program on the planet does and calling into the system libraries. Certainly, it made the ports to non-Linux systems absolutely brutal: systems are required to make themselves look like Linux for Go to function correctly. So yes, this is unenlightened -- or perhaps it's a conscious attempt to make Go unportable?

And another thread recently happened on the mailing list about the g, m, and p internal runtime structures.

I'm starting to think we should have a documentation page for internals FAQs.

The closest we have now is a link from https://golang.org/doc/ to Go Slices: usage and internals

But there's more content not as well linked:

• http://research.swtch.com/interfaces
• http://research.swtch.com/gorace
• http://research.swtch.com/randhash
• http://blog.altoros.com/golang-part-1-main-concepts-and-project-structure.html (6 parts)

There's some good stuff in https://golang.org/wiki/DesignDocuments too, but that's also not well linked.

[josharian]

Do you have in mind a website doc or a wiki? Answers custom written for the purpose, or a collection of links, perhaps with commentary? I'm very sympathetic to the need here, since I slowly and painstakingly taught myself much of this based on the code and code reviews (and regularly continue to do so)...but there's also a whole lot of possible topics, many of which are intricate, and the material ages fast. It'd be very easy to bite off a chunk too big to chew.

[dgryski]

Wrong documentation (== "out of date" in this context) is worse than no documentation.

[mkevac]

It is not. Linux internals books from 2013 are still useful. Just put a date on it.

[josharian]

Missing from Brad's list above: blog posts from Daniel Morsing, particularly https://morsmachine.dk/go-scheduler.

I wonder whether a good place to start is a wiki that collects links like these and adds minor commentary about when they were written (probably a Go release is more helpful than a year) and some discussion of how accurate they still are.

[rsc]

Seems like a reasonable wiki page.

[akavel]

In case it's useful to anyone, I tried bootstrapping such a wiki independently at one point (somewhat long ago — '2010), see: goin.wikispot.org (archived) and goin.wikispot.org/All_Pages (archived). FWIW, I think much of the information (e.g. M, G) stayed relevant since then, if not 100% exactly precise. But I imagine it'd still help me when diving into the codebase for the first time, to at least get some basic ideas (instead of a "WTF is the f_reaking g I see everywhere but no idea how to find any docs on it?!?")

[aengelke]

I wrote about some Go internals in my master's thesis (ch. 3), mostly focused on parts relevant for reverse engineering of Go 1.8 binaries. Might be interesting as well in this context.