From 694b244e1dbc35ebc8f2491a27b452859bbbabcb Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Mon, 29 Jun 2015 13:27:41 +1000 Subject: [PATCH] doc: update FAQ for Go 1.5 Change-Id: I4befb21d0811819ce0a5721421a2f6df7a9b62fa Reviewed-on: https://go-review.googlesource.com/11605 Reviewed-by: Russ Cox Reviewed-by: Andrew Gerrand --- doc/go_faq.html | 153 ++++++++++++++++++++++++++++++------------------ 1 file changed, 96 insertions(+), 57 deletions(-) diff --git a/doc/go_faq.html b/doc/go_faq.html index 47d3ccff45..c3824e6937 100644 --- a/doc/go_faq.html +++ b/doc/go_faq.html @@ -107,7 +107,8 @@ The mascot and logo were designed by Renée French, who also designed Glenda, the Plan 9 bunny. -The gopher is derived from one she used for an WFMU +The gopher +is derived from one she used for an WFMU T-shirt design some years ago. The logo and mascot are covered by the Creative Commons Attribution 3.0 @@ -153,7 +154,7 @@ Go is an attempt to combine the ease of programming of an interpreted, dynamically typed language with the efficiency and safety of a statically typed, compiled language. It also aims to be modern, with support for networked and multicore -computing. Finally, it is intended to be fast: it should take +computing. Finally, working with Go is intended to be fast: it should take at most a few seconds to build a large executable on a single computer. To meet these goals required addressing a number of linguistic issues: an expressive but lightweight type system; @@ -508,7 +509,7 @@ They are not restricted to structs (classes).

-Also, the lack of type hierarchy makes “objects” in Go feel much more +Also, the lack of a type hierarchy makes “objects” in Go feel much more lightweight than in languages such as C++ or Java.

@@ -608,17 +609,19 @@ How can I guarantee my type satisfies an interface?

You can ask the compiler to check that the type T implements the -interface I by attempting an assignment: +interface I by attempting an assignment using the zero value for +T or pointer to T, as appropriate: 

 type T struct{}
-var _ I = T{}   // Verify that T implements I.
+var _ I = T{}       // Verify that T implements I.
+var _ I = (*T)(nil) // Verify that *T implements I.

-If T doesn't implement I, the mistake will be caught -at compile time. +If T (or *T, accordingly) doesn't implement +I, the mistake will be caught at compile time.

@@ -726,7 +729,7 @@ interface satisfaction very easy to state: are the function's names and signatures exactly those of the interface? Go's rule is also easy to implement efficiently. We feel these benefits offset the lack of -automatic type promotion. Should Go one day adopt some form of generic +automatic type promotion. Should Go one day adopt some form of polymorphic typing, we expect there would be a way to express the idea of these examples and also have them be statically checked.

@@ -765,7 +768,7 @@ schematically, (int, 3). An interface value is nil only if the inner value and type are both unset, (nil, nil). In particular, a nil interface will always hold a nil type. -If we store a pointer of type *int inside +If we store a nil pointer of type *int inside an interface value, the inner type will be *int regardless of the value of the pointer: (*int, nil). Such an interface value will therefore be non-nil @@ -773,7 +776,7 @@ Such an interface value will therefore be non-nil

-This situation can be confusing, and often arises when a nil value is +This situation can be confusing, and arises when a nil value is stored inside an interface value such as an error return:

@@ -890,7 +893,7 @@ encourages you to be explicit.

-A blog post, title Constants, +A blog post titled Constants explores this topic in more detail.

@@ -950,6 +953,19 @@ In fact, godoc implements the full site at golang.org/.

+

+A godoc instance may be configured to provide rich, +interactive static analyses of symbols in the programs it displays; details are +listed here. +

+ +

+For access to documentation from the command line, the +go tool has a +doc +subcommand that provides a textual interface to the same information. +

+

Is there a Go programming style guide?

@@ -1046,7 +1062,17 @@ unexpected ways, the simplest solution is to copy it to your local repository. (This is the approach Google takes internally.) Store the copy under a new import path that identifies it as a local copy. For example, you might copy "original.com/pkg" to "you.com/external/original.com/pkg". -gomvpkg is one tool to help automate this process. +The gomvpkg +program is one tool to help automate this process. +

+ +

+The Go 1.5 release includes an experimental facility to the +go command +that makes it easier to manage external dependencies by "vendoring" +them into a special directory near the package that depends upon them. +See the design +document for details.

Pointers and Allocation

@@ -1061,7 +1087,8 @@ thing being passed, as if there were an assignment statement assigning the value to the parameter. For instance, passing an int value to a function makes a copy of the int, and passing a pointer value makes a copy of the pointer, but not the data it points to. -(See the next section for a discussion of how this affects method receivers.) +(See a later +section for a discussion of how this affects method receivers.)

@@ -1290,14 +1317,20 @@ See the Share Memory By Communicating code Why doesn't my multi-goroutine program use multiple CPUs?

-You must set the GOMAXPROCS shell environment variable -or use the similarly-named function -of the runtime package to allow the -run-time support to utilize more than one OS thread. +The number of CPUs available simultaneously to executing goroutines is +controlled by the GOMAXPROCS shell environment variable. +In earlier releases of Go, the default value was 1, but as of Go 1.5 the default +value is the number of cores available. +Therefore programs compiled afer 1.5 should demonstrate parallel execution +of multiple goroutines. +To change the behavior, set the environment variable or use the similarly-named +function +of the runtime package to configure the +run-time support to utilize a different number of threads.

-Programs that perform parallel computation should benefit from an increase in +Programs that perform parallel computation might benefit from a further increase in GOMAXPROCS. However, be aware that concurrency @@ -1319,7 +1352,7 @@ intrinsically parallel.

In practical terms, programs that spend more time communicating on channels than doing computation -will experience performance degradation when using +may experience performance degradation when using multiple OS threads. This is because sending data between threads involves switching contexts, which has significant cost. @@ -1330,9 +1363,11 @@ to speed it up.

-Go's goroutine scheduler is not as good as it needs to be. In the future, it -should recognize such cases and optimize its use of OS threads. For now, -GOMAXPROCS should be set on a per-application basis. +Go's goroutine scheduler is not as good as it needs to be, although it +has improved in recent releases. +In the future, it may better optimize its use of OS threads. +For now, if there are performance issues, +setting GOMAXPROCS on a per-application basis may help.

@@ -1367,7 +1402,10 @@ there is no useful way for a method call to obtain a pointer. Even in cases where the compiler could take the address of a value to pass to the method, if the method modifies the value the changes will be lost in the caller. -As a common example, this code: +As an example, if the Write method of +bytes.Buffer +used a value receiver rather than a pointer, +this code: 

@@ -1461,7 +1499,7 @@ seem odd but works fine in Go:
 Does Go have the ?: operator?
 
 

-There is no ternary form in Go. You may use the following to achieve the same
+There is no ternary testing operation in Go. You may use the following to achieve the same
 result:
 

 
@@ -1561,11 +1599,10 @@ What compiler technology is used to build the compilers?
 
 

 Gccgo has a front end written in C++, with a recursive descent parser coupled to the
-standard GCC back end. Gc is written in C using
-yacc/bison for the parser.
-Although it's a new program, it fits in the Plan 9 C compiler suite
-(http://plan9.bell-labs.com/sys/doc/compiler.html)
-and uses a variant of the Plan 9 loader to generate ELF/Mach-O/PE binaries.
+standard GCC back end. Gc is written in Go using
+yacc/bison for the parser
+and uses a custom loader, also written in Go but
+based on the Plan 9 loader, to generate ELF/Mach-O/PE binaries.
 

 
 

@@ -1574,24 +1611,26 @@ slow to meet our performance goals.
 

 
 

-We also considered writing gc, the original Go compiler, in Go itself but
-elected not to do so because of the difficulties of bootstrapping and
-especially of open source distribution—you'd need a Go compiler to
-set up a Go environment. Gccgo, which came later, makes it possible to
-consider writing a compiler in Go.
-A plan to do that by machine translation of the existing compiler is under development.
-A separate document
-explains the reason for this approach.
+The original gc, the Go compiler, was written in C
+because of the difficulties of bootstrapping—you'd need a Go compiler to
+set up a Go environment.
+But things have advanced and as of Go 1.5 the compiler is written in Go.
+It was converted from C to Go using automatic translation tools, as
+described in this design document
+and a recent talk.
+Thus the compiler is now "self-hosting", which means we must face
+the bootstrapping problem.
+The solution, naturally, is to have a working Go installation already,
+just as one normally has a working C installation in place.
+The story of how to bring up a new Go installation from source
+is described separately.
 

 
 

-That plan aside,
-Go is a
-fine language in which to implement a self-hosting compiler: a native lexer and
-parser are already available in the go package
-and a separate type checking
-package
-has also been written.
+Go is a fine language in which to implement a Go compiler.
+Although gc does not use them (yet?), a native lexer and
+parser are available in the go package
+and there is also a type checker.
 

 
 

@@ -1599,15 +1638,11 @@ How is the run-time support implemented?

 
 

 Again due to bootstrapping issues, the run-time code was originally written mostly in C (with a
-tiny bit of assembler) although much of it has been translated to Go since then
-and one day all of it might be (except for the assembler bits).
+tiny bit of assembler) but it has since been translated to Go
+(except for some assembler bits).
 Gccgo's run-time support uses glibc.
-Gc uses a custom C library to keep the footprint under
-control; it is
-compiled with a version of the Plan 9 C compiler that supports
-resizable stacks for goroutines.
-The gccgo compiler implements these on Linux only,
-using a technique called segmented stacks,
+The gccgo compiler implements goroutines using
+a technique called segmented stacks,
 supported by recent modifications to the gold linker.
 

 
@@ -1615,8 +1650,8 @@ supported by recent modifications to the gold linker.
 Why is my trivial program such a large binary?
 
 

-The linkers in the gc tool chain (5l, 6l, and 8l)
-do static linking.  All Go binaries therefore include the Go
+The linker in the gc tool chain
+creates statically-linked binaries by default.  All Go binaries therefore include the Go
 run-time, along with the run-time type information necessary to support dynamic
 type checks, reflection, and even panic-time stack traces.
 

@@ -1626,7 +1661,7 @@ A simple C "hello, world" program compiled and linked statically using gcc
 on Linux is around 750 kB,
 including an implementation of printf.
 An equivalent Go program using fmt.Printf
-is around 1.9 MB, but
+is around 2.3 MB, but
 that includes more powerful run-time support and type information.
 

 
@@ -1885,8 +1920,12 @@ simpler because they don't need to specify how memory is managed across them.
 

 
 

-The current implementation is a parallel mark-and-sweep
-collector but a future version might take a different approach.
+The current implementation is a parallel mark-and-sweep collector.
+Recent improvements, documented in
+this design document,
+have introduced bounded pause times and improved the
+parallelism.
+Future versions might attempt new approaches.