First run at a Programming FAQ
Moved a couple of FAQs from the main FAQ, and added some others
R=r, rsc, iant, gri
CC=golang-dev
https://golang.org/cl/218070
diff --git a/doc/go_faq.html b/doc/go_faq.html
index 9205c45..ff096ec 100644
--- a/doc/go_faq.html
+++ b/doc/go_faq.html
@@ -79,15 +79,15 @@
We felt a viable solution required a more complete approach.
<h3 id="Why_doesnt_Go_run_on_Windows">
-Why doesn't Go run on Windows?</h3>
+Why doesn't Go run on Windows yet?</h3>
<p>
We understand that a significant fraction of computers in the world
run Windows and it would be great if those computers could run Go
-programs. However, the Go team is small and we don't have the
-resources to do a Windows port at the moment. We would be
-more than willing to answer questions and offer advice to anyone
-willing to develop a Windows version.
+programs. A group of volunteers has made significant progress toward
+porting Go to <a href="http://www.mingw.org/">MinGW</a>.
+You can follow their progress on the
+<a href="http://groups.google.com/group/golang-nuts">mailing list</a>.
</p>
<h3 id="Whats_the_origin_of_the_mascot">
@@ -220,26 +220,6 @@
The only way to have dynamically dispatched methods is through an
interface. Methods on structs or other types are always resolved statically.
-<h2 id="Concurrent_programming">Concurrent programming</h2>
-
-<h3 id="What_operations_are_atomic_What_about_mutexes">
-What operations are atomic? What about mutexes?</h3>
-
-<p>
-We haven't fully defined it all yet, but some details about atomicity are available in the
-<a href="go_mem.html">Go Memory Model specification</a>.
-Also, some concurrency questions are answered in more detail in the
-<a href="go_lang_faq.html">language design FAQ</a>.
-
-<p>
-Regarding mutexes, the <a href="/pkg/sync">sync</a>
-package implements them, but we hope Go programming style will
-encourage people to try higher-level techniques. In particular, consider
-structuring your program so that only one goroutine at a time is ever
-responsible for a particular piece of data.
-
-<p>
-Do not communicate by sharing memory. Instead, share memory by communicating.
<h2 id="Writing_Code">Writing Code</h2>
@@ -279,37 +259,6 @@
<a href="contribute.html">Contributing to the Go project</a>
for more information about how to proceed.
-<h3 id="How_do_I_create_a_multifile_package">
-How do I create a multifile package?</h3>
-
-<p>
-Put all the source files for the package in a directory by themselves.
-Source files can refer to items from different files at will; there is
-no header file or need for forward declarations.
-
-<p>
-Other than being split into multiple files, the package will compile and test
-just like a single-file package.
-
-<h3 id="How_do_I_write_a_unit_test">
-How do I write a unit test?</h3>
-
-<p>
-Create a new file ending in <code>_test.go</code> in the same directory
-as your package sources. Inside that file, <code>import "testing"</code>
-and write functions of the form
-
-<pre>
-func TestFoo(t *testing.T) {
- ...
-}
-</pre>
-
-<p>
-Run <code>gotest</code> in that directory.
-That script finds the <code>Test</code> functions,
-builds a test binary, and runs it.
-
<h3 id="Where_is_assert">
Where is assert?</h3>
diff --git a/doc/go_programming_faq.html b/doc/go_programming_faq.html
new file mode 100644
index 0000000..ecb6498
--- /dev/null
+++ b/doc/go_programming_faq.html
@@ -0,0 +1,271 @@
+<!-- Programming FAQ -->
+
+<h2 id="Pointers">Pointers and Allocation</h2>
+
+<h3 id="pass_by_value">
+When are function paramters passed by value?</h3>
+
+<p>
+Everything in Go is passed by value. A function always gets a copy of the
+thing being passed, as if there were an assignment statement assigning the
+value to the parameter. For instance, copying a pointer value makes a copy of
+the pointer, not the data it points to.
+</p>
+
+<p>
+Map and slice values behave like pointers; they are descriptors that
+contain pointers to the underlying map or slice data. Copying a map or
+slice value doesn't copy the data it points to. Copying an interface value
+makes a copy of the thing stored in the interface value. If the interface
+value holds a struct, copying the interface value makes a copy of the
+struct. If the interface value holds a pointer, copying the interface value
+makes a copy of the pointer, but again not the data it points to.
+</p>
+
+<h3 id="methods_on_values_or_pointers">
+Should I define methods on values or pointers?</h3>
+
+<pre>
+func (s *MyStruct) someMethod() { } // method on pointer
+func (s MyStruct) someMethod() { } // method on value
+</pre>
+
+<p>
+When defining a method on a type, the receiver (<code>s</code> in the above
+example) behaves exactly is if it were an argument to the method. Define the
+method on a pointer type if you need the method to modify the data the receiver
+points to. Otherwise, it is often cleaner to define the method on a value type.
+</p>
+
+<h3 id="new_and_make">
+What's the difference between new and make?</h3>
+
+<p>
+In short: <code>new</code> allocates memory, <code>make</code> initializes
+the slice, map, and channel types.
+</p>
+
+<p>
+See the <a href="/doc/effective_go.html#allocation_new">relevant section
+of Effective Go</a> for more details.
+</p>
+
+<h3 id="64bit_machine_32bit_int">
+Why is <code>int</code> 32 bits on 64 bit machines?</h3>
+
+<p>
+The size of <code>int</code> and <code>float</code> is implementation-specific.
+The 64 bit Go compilers (both 6g and gccgo) use a 32 bit representation for
+both <code>int</code> and <code>float</code>. Code that relies on a particular
+size of value should use an explicitly sized type, like <code>int64</code> or
+<code>float64</code>.
+</p>
+
+<h2 id="Concurrent_programming">Concurrent programming</h2>
+
+<h3 id="What_operations_are_atomic_What_about_mutexes">
+What operations are atomic? What about mutexes?</h3>
+
+<p>
+We haven't fully defined it all yet, but some details about atomicity are
+available in the <a href="go_mem.html">Go Memory Model specification</a>.
+Also, some concurrency questions are answered in more detail in the <a
+href="go_lang_faq.html">language design FAQ</a>.
+</p>
+
+<p>
+Regarding mutexes, the <a href="/pkg/sync">sync</a>
+package implements them, but we hope Go programming style will
+encourage people to try higher-level techniques. In particular, consider
+structuring your program so that only one goroutine at a time is ever
+responsible for a particular piece of data.
+</p>
+
+<p>
+Do not communicate by sharing memory. Instead, share memory by communicating.
+</p>
+
+<h3 id="Why_no_multi_CPU">
+Why doesn't my multi-goroutine program use multiple CPUs?</h3>
+
+<p>
+Under the gc compilers you must set <code>GOMAXPROCS</code> to allow the
+runtime to utilise more than one OS thread. Under <code>gccgo</code> an OS
+thread will be created for each goroutine, and <code>GOMAXPROCS</code> is
+effectively equal to the number of running goroutines.
+</p>
+
+<p>
+Programs that perform concurrent computation should benefit from an increase in
+<code>GOMAXPROCS</code>. (See the <a
+href="http://golang.org/pkg/runtime/#GOMAXPROCS">runtime package
+documentation</a>.)
+</p>
+
+<h3 id="Why_GOMAXPROCS">
+Why does using <code>GOMAXPROCS</code> > 1 sometimes make my program
+slower?</h3>
+
+<p>
+(This is specific to the gc compilers. See above.)
+</p>
+
+<p>
+It depends on the nature of your program.
+Programs that contain several goroutines that spend a lot of time
+communicating on channels will experience performance degradation when using
+multiple OS threads. This is because of the significant context-switching
+penalty involved in sending data between threads.
+</p>
+
+<p>
+The Go runtime's scheduler is not as good as it needs to be. In future, it
+should recognise such cases and optimize its use of OS threads. For now,
+<code>GOMAXPROCS</code> should be set on a per-application basis.
+</p>
+
+
+<h2 id="Closures">Closures</h2>
+
+<h3 id="closures_and_goroutines">
+Why am I confused by the way my closures behave as goroutines?</h3>
+
+<p>
+Some confusion may arise when using closures with concurrency.
+Consider the following program:
+</p>
+
+<pre>
+func main() {
+ done := make(chan bool)
+
+ values = []string{ "a", "b", "c" }
+ for _, v := range values {
+ go func() {
+ fmt.Println(v)
+ done <- true
+ }()
+ }
+
+ // wait for all goroutines to complete before exiting
+ for i := range values {
+ <-done
+ }
+}
+</pre>
+
+<p>
+One might mistakenly expect to see <code>a, b, c</code> as the output.
+What you'll probably see instead is <code>c, c, c</code>. This is because
+each closure shares the same variable <code>v</code>. Each closure prints the
+value of <code>v</code> at the time <code>fmt.Println</code> is executed,
+rather than the value of <code>v</code> when the goroutine was launched.
+</p>
+
+<p>
+To bind the value of <code>v</code> to each closure as they are launched, one
+could modify the inner loop to read:
+</p>
+
+<pre>
+ for _, v := range values {
+ go func(<b>u</b>) {
+ fmt.Println(<b>u</b>)
+ done <- true
+ }(<b>v</b>)
+ }
+</pre>
+
+<p>
+In this example, the value of <code>v</code> is passed as an argument to the
+anonymous function. That value is then accessible inside the function as
+the variable <code>u</code>.
+</p>
+
+<h2 id="Control_flow">Control flow</h2>
+
+<h3 id="Does_Go_have_a_ternary_form">
+Does Go have the <code>?:</code> operator?</h3>
+
+<p>
+There is no ternary form in Go. You may use the following to achieve the same
+result:
+</p>
+
+<pre>
+if expr {
+ n = trueVal
+} else {
+ n = falseVal
+}
+</pre>
+
+<h2 id="Packages_Testing">Packages and Testing</h2>
+
+<h3 id="How_do_I_create_a_multifile_package">
+How do I create a multifile package?</h3>
+
+<p>
+Put all the source files for the package in a directory by themselves.
+Source files can refer to items from different files at will; there is
+no need for forward declarations or a header file.
+</p>
+
+<p>
+Other than being split into multiple files, the package will compile and test
+just like a single-file package.
+</p>
+
+<h3 id="How_do_I_write_a_unit_test">
+How do I write a unit test?</h3>
+
+<p>
+Create a new file ending in <code>_test.go</code> in the same directory
+as your package sources. Inside that file, <code>import "testing"</code>
+and write functions of the form
+</p>
+
+<pre>
+func TestFoo(t *testing.T) {
+ ...
+}
+</pre>
+
+<p>
+Run <code>gotest</code> in that directory.
+That script finds the <code>Test</code> functions,
+builds a test binary, and runs it.
+</p>
+
+
+<h2 id="Data_structures">Data Structures</h2>
+
+<h3 id="nested_array_verbose"
+>Why does the syntax for nested array literals seem overly verbose?</h3>
+
+<p>
+In Go, you must specify a 2-dimensional array literal like this:
+</p>
+
+<pre>
+var intArray = [4][4]int{
+ [4]int{1, 2, 3, 4},
+ [4]int{2, 4, 8, 16},
+ [4]int{3, 9, 27, 81},
+ [4]int{4, 16, 64, 256},
+}
+</pre>
+
+<p>
+It seems that the <code>[4]int</code> could be inferred, but in general it's
+hard to get this sort of thing right.
+</p>
+
+<p>
+Some of Go's designers had worked on other languages that derived types
+automatically in such expressions, but the special cases that arise can
+be messy, especially when interfaces, nil, constant conversions, and
+such are involved. It seemed better to require the full type
+information. That way there will be no surprises.
+</p>
+
diff --git a/lib/godoc/godoc.html b/lib/godoc/godoc.html
index b404857..49902ff 100644
--- a/lib/godoc/godoc.html
+++ b/lib/godoc/godoc.html
@@ -83,6 +83,7 @@
<li><a href="/doc/effective_go.html">Effective Go</a></li>
<li><a href="/doc/go_faq.html">FAQ</a></li>
<li><a href="/doc/go_lang_faq.html">Language Design FAQ</a></li>
+ <li><a href="/doc/go_programming_faq.html">Programming FAQ</a></li>
<li><a href="http://www.youtube.com/watch?v=rKnDgT73v8s">Tech talk (1 hour)</a> (<a href="/doc/talks/go_talk-20091030.pdf">PDF</a>)</li>
<li><a href="/doc/go_spec.html">Language Specification</a></li>
<li><a href="/doc/go_mem.html">Memory Model</a></li>
