diff options
author | Andrew Gerrand <adg@golang.org> | 2010-03-04 12:56:08 +1100 |
---|---|---|
committer | Andrew Gerrand <adg@golang.org> | 2010-03-04 12:56:08 +1100 |
commit | 1d5af1553c91d346e70c83aa5b7132e242c15242 (patch) | |
tree | 48d796815b835a96b7eedefc92f452b6151c6957 | |
parent | e53f7d8993b4fae1e2de425e5c87852803362bd2 (diff) | |
download | go-1d5af1553c91d346e70c83aa5b7132e242c15242.tar.gz go-1d5af1553c91d346e70c83aa5b7132e242c15242.zip |
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
-rw-r--r-- | doc/go_faq.html | 61 | ||||
-rw-r--r-- | doc/go_programming_faq.html | 271 | ||||
-rw-r--r-- | lib/godoc/godoc.html | 1 |
3 files changed, 277 insertions, 56 deletions
diff --git a/doc/go_faq.html b/doc/go_faq.html index 9205c4507e..ff096ec9c3 100644 --- a/doc/go_faq.html +++ b/doc/go_faq.html @@ -79,15 +79,15 @@ the C and C++ languages themselves. 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 @@ How do I get dynamic dispatch of methods?</h3> 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 @@ See the document <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 0000000000..ecb64983c7 --- /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 b404857ebc..49902ff106 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> |