code review 4251047: doc changes

doc: add FAQ about large binaries and stack vs heap allocation
doc: add internationalization to roadmap

[adg, 2011-03-01 02:07:37]

Hello rsc, r,

I'd like you to review this change to
https://go.googlecode.com/hg/

[adg, 2011-03-01 02:12:34]

Looks like another FAQ about stack vs heap allocation snuck in there.
Review that too, if you please! (I hand intended to do more research
as to its veracity before sending it)

On 1 March 2011 13:07,  <adg@golang.org> wrote:
> Reviewers: rsc, r,
>
> Message:
> Hello rsc, r,
>
> I'd like you to review this change to
> https://go.googlecode.com/hg/
>
>
> Description:
> doc: add dynamic linking to roadmap, and FAQ about large binaries
>
> Please review this at http://codereview.appspot.com/4251047/
>
> Affected files:
>  M doc/devel/roadmap.html
>  M doc/go_faq.html
>
>
> Index: doc/devel/roadmap.html
> ===================================================================
> --- a/doc/devel/roadmap.html
> +++ b/doc/devel/roadmap.html
> @@ -59,6 +59,8 @@
>  Improved optimization.
>  <li>
>  Use escape analysis to keep more data on stack.
> +<li>
> +Dynamic linking.
>  </ul>
>
>  <h4 id="Gccgo_roadmap">
> Index: doc/go_faq.html
> ===================================================================
> --- a/doc/go_faq.html
> +++ b/doc/go_faq.html
> @@ -677,6 +677,23 @@
>  The default size of a floating-point constant is <code>float64</code>.
>  </p>
>
> +<h3 id="q_stack_v_heap">
> +How do I know whether a variable is allocated on the heap or the
> stack?</h3>
> +
> +<p>
> +Specific allocation characteristics are compiler dependent.
> +The gc and gccgo compilers will put data on the stack where they can,
> +and allocate on the heap where they must.
> +Taking the address of a variable will cause it to be allocated on the heap,
> +if it wasn't there already.
> +</p>
> +
> +<p>
> +There is room for improvement in making the compilers more clever using
> escape
> +analysis, permitting them to avoid some heap allocations (and thus produce
> less
> +garbage to be collected).
> +</p>
> +
>  <h2 id="Concurrency">Concurrency</h2>
>
>  <h3 id="What_operations_are_atomic_What_about_mutexes">
> @@ -934,6 +951,26 @@
>  Work is underway to provide the same stack management in
>  <code>gccgo</code>.
>
> +<h3 id="Why_is_my_trivial_program_such_a_large_binary">
> +Why is my trivial program such a large binary?</h3>
> +
> +<p>
> +The Plan 9 linkers (<code>6l</code> and co.) produce statically linked
> +binaries. All Go binaries therefore include the Go runtime (with its large
> +unicode tables). Most Go programs also depend on standard library packages
> that
> +themselves have a sizable tree of dependencies.
> +
> +<p>
> +A trivial "Hello, world" program written in C and built (statically linked)
> +with <code>gcc</code> is ~750kb. An equivalent Go program linked with
> +<code>6l</code> is ~1.8mb. This seems reasonable when you compare the scope
> of
> +C's <code>stdio</code> with Go's <a href="/pkg/fmt/"><code>fmt</code>
> +package</a> (which can automatically print any Go type and handle unicode).
> +
> +<p>
> +Support for dynamic linking is on <a href="/doc/devel/roadmap.html">our
> +roadmap</a>.
> +
>  <h2 id="Performance">Performance</h2>
>
>  <h3 id="Why_does_Go_perform_badly_on_benchmark_x">
>
>
>

[rsc, 2011-03-01 02:26:59]

s/q_stack_v_heap/stack_or_heap/
or follow the usual convention

[rsc, 2011-03-01 02:27:24]

I'm not sure about adding dynamic linking to the road map.
It's definitely not on my road map.

Russ

[adg, 2011-03-01 02:29:57]

On 1 March 2011 13:27, Russ Cox <rsc@golang.org> wrote:
> I'm not sure about adding dynamic linking to the road map.
> It's definitely not on my road map.

Fine. That's why I sent it for review off-list. Removed from CL.

[rsc, 2011-03-01 02:31:32]

> Fine. That's why I sent it for review off-list. Removed from CL.

Tricky.  :-)

[r2, 2011-03-01 04:53:18]

i was going to add something about internationalization to the road map. might
as well do it while you're here

[adg, 2011-03-01 04:57:20]

Done. PTAL.

http://codereview.appspot.com/4251047/

On 1 March 2011 15:53, Rob 'Commander' Pike <r@google.com> wrote:
> i was going to add something about internationalization to the road map. might
as well do it while you're here
>
>

[r, 2011-03-01 05:08:09]

http://codereview.appspot.com/4251047/diff/10001/doc/devel/roadmap.html
File doc/devel/roadmap.html (right):

http://codereview.appspot.com/4251047/diff/10001/doc/devel/roadmap.html#newco...
doc/devel/roadmap.html:51: Comprehensive internationalization support.
no need for noun phrase. the ridiculous unavoidable terminology is bad enough as
is.

Comprehensive support for internationalization.

http://codereview.appspot.com/4251047/diff/10001/doc/go_faq.html
File doc/go_faq.html (right):

http://codereview.appspot.com/4251047/diff/10001/doc/go_faq.html#newcode684
doc/go_faq.html:684: Specific allocation characteristics are compiler dependent.
x/compiler dependent/ s/ /-/

http://codereview.appspot.com/4251047/diff/10001/doc/go_faq.html#newcode685
doc/go_faq.html:685: The gc and gccgo compilers will put data on the stack where
they can,
i think we <code> or some such the compiler names. be consistent.
s/where/if/

http://codereview.appspot.com/4251047/diff/10001/doc/go_faq.html#newcode686
doc/go_faq.html:686: and allocate on the heap where they must.
s/where/when/

http://codereview.appspot.com/4251047/diff/10001/doc/go_faq.html#newcode694
doc/go_faq.html:694: garbage to be collected).
drop the parens, drop "thus"

http://codereview.appspot.com/4251047/diff/10001/doc/go_faq.html#newcode958
doc/go_faq.html:958: The Plan 9 linkers (<code>6l</code> and co.) produce
statically linked
the "co." is jargon.  just name them or say "and friends"

http://codereview.appspot.com/4251047/diff/10001/doc/go_faq.html#newcode960
doc/go_faq.html:960: unicode tables). Most Go programs also depend on standard
library packages that
s/^u/U/
but i think the unicode tables are a scapegoat, not important. type tables
matter more. rsc has studied this

http://codereview.appspot.com/4251047/diff/10001/doc/go_faq.html#newcode968
doc/go_faq.html:968: package</a> (which can automatically print any Go type and
handle unicode).
Unicode. it's a proper noun.
but... stdio can sorta handle it too. this is a false comparison.

[rsc, 2011-03-01 05:19:56]

i think the heap or stack question should start by
saying "you don't need to know".

i would like to avoid calling 6l etc "the plan 9 linkers"
since they are quite different at this point and
are actually were inferno linkers more recently than
they were the plan 9 linkers.

don't pin all the blame on unicode.  the runtime data
structures to support reflect and stack traces take
up a fair amount of space too.  someone recently did
the experiment (christopher wedgwood, i think) and
found that the unicode tables are only around 200kb.
they're symptomatic of a place where the linker could
be smarter, but they are not a problem per se. there's
a meme starting that all the bloat is unicode tables,
and that's simply not true.

suggested rephrasings:


How do I know whether a variable is allocated on the heap or the stack?

From a correctness standpoint, you don't need to know.
Each variable in Go exists as long as there are references to it.
The storage location chosen by the implementation is irrelevant to the
semantics of the language.

The storage location does have an effect on writing efficient programs.
When possible, the Go compilers will allocate variables that are
local to a function in that function's stack frame.  However, if the
compiler cannot prove that the variable is not referenced after the
function returns, then the compiler must allocate the variable on the
garbage-collected heap to avoid dangling pointer errors.  In the
current compilers, the analysis is crude: if a variable has its address
taken, that variable is allocated on the heap.


Why is my trivial program such a large binary?

The gc tool chain (5l, 6l, and 8l) only generate statically linked binaries.
All Go binaries therefore include the Go runtime, along with the runtime
type information necessary to support dynamic type checks, reflection, and
even panic-time stack traces.

A trivial C "hello, world" program compiled and linked statically using gcc
on Linux is around 750 kB.  An equivalent Go program is around 1.8 MB, but
that includes a more powerful runtime.

This difference in binary size ranks fairly low in our priorities for
evolving and improving Go, but we do believe it can be reduced.

[r2, 2011-03-01 05:26:05]

On Feb 28, 2011, at 9:19 PM, Russ Cox wrote:

> i think the heap or stack question should start by
> saying "you don't need to know".
> 
> i would like to avoid calling 6l etc "the plan 9 linkers"
> since they are quite different at this point and
> are actually were inferno linkers more recently than
> they were the plan 9 linkers.
> 
> don't pin all the blame on unicode.  the runtime data
> structures to support reflect and stack traces take
> up a fair amount of space too.  someone recently did
> the experiment (christopher wedgwood, i think) and
> found that the unicode tables are only around 200kb.
> they're symptomatic of a place where the linker could
> be smarter, but they are not a problem per se. there's
> a meme starting that all the bloat is unicode tables,
> and that's simply not true.
> 
> suggested rephrasings:
> 
> 
> How do I know whether a variable is allocated on the heap or the stack?
> 
> From a correctness standpoint, you don't need to know.
> Each variable in Go exists as long as there are references to it.
> The storage location chosen by the implementation is irrelevant to the
> semantics of the language.
> 
> The storage location does have an effect on writing efficient programs.
> When possible, the Go compilers will allocate variables that are
> local to a function in that function's stack frame.  However, if the
> compiler cannot prove that the variable is not referenced after the
> function returns, then the compiler must allocate the variable on the
> garbage-collected heap to avoid dangling pointer errors.  In the
> current compilers, the analysis is crude: if a variable has its address
> taken, that variable is allocated on the heap.
> 
> 
> Why is my trivial program such a large binary?
> 
> The gc tool chain (5l, 6l, and 8l) only generate statically linked binaries.
> All Go binaries therefore include the Go runtime, along with the runtime
> type information necessary to support dynamic type checks, reflection, and
> even panic-time stack traces.
> 
> A trivial C "hello, world" program compiled and linked statically using gcc
> on Linux is around 750 kB.  An equivalent Go program is around 1.8 MB, but
> that includes a more powerful runtime.
> 
> This difference in binary size ranks fairly low in our priorities for
> evolving and improving Go, but we do believe it can be reduced.

i wouldn't prioritize it here. that's bear-baiting.  just say it is likely to be
reduced as the tools evolve.

-rob

[adg, 2011-03-01 05:50:30]

PTAL

[r, 2011-03-01 07:40:56]

LGTM

http://codereview.appspot.com/4251047/diff/12004/doc/go_faq.html
File doc/go_faq.html (right):

http://codereview.appspot.com/4251047/diff/12004/doc/go_faq.html#newcode965
doc/go_faq.html:965: runtime, along with the runtime type information necessary
to support dynamic
s2/runtime/run-time/ (it's an adjective. teutonics in english are hyphenated
when adjectives. there are probably more of them in the docs)

http://codereview.appspot.com/4251047/diff/12004/doc/go_faq.html#newcode971
doc/go_faq.html:971: that includes a more powerful runtime.  We believe that
with some effort
not now, but for the record: i wish we didn't call this "runtime". that's the
name of the package and the right one but this is documentation.  runtime not a
real word and the neologism is ambiguous (its prior definition meant a time, not
a library).

i don't have a better suggestion anyway, but i'm still thinking about it.

[adg, 2011-03-01 10:35:54]

*** Submitted as http://code.google.com/p/go/source/detail?r=0ef245a79bee ***

doc: add FAQ about large binaries and stack vs heap allocation
doc: add internationalization to roadmap

R=rsc, r, r2
CC=golang-dev
http://codereview.appspot.com/4251047