Skip to content

G
golang
Commit 5dd74175 authored by Andrew Gerrand's avatar Andrew Gerrand
Browse files
Options

doc: re-organize golang.org site content 

Remove "References" section.
Remove most articles and redirect to blog.golang.org.
Move /ref/spec and /ref/mem to /doc/spec and /doc/mem.
Remove duplicate links from the remaining
"Documents", "The Project", and "Help" pages.
Defer to the wiki for more links and community content.
Update command reference and mention cover tool.
Add "Pop-out" text to the front page.
Pick one of four videos at random to feature on the front page.

Fixes #2547.
Fixes #5561.
Fixes #6321.

R=r, dominik.honnef
CC=golang-dev
https://golang.org/cl/13724043
parent 83da0fd9
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 77 additions and 2110 deletions
doc/articles/c_go_cgo.html deleted 100644 → 0
View file @ 83da0fd9
<!--{
"Title": "C? Go? Cgo!",
"Template": true
}-->
<p>
Cgo lets Go packages call C code. Given a Go source file written with some
special features, cgo outputs Go and C files that can be combined into a
single Go package.
</p>
<p>
To lead with an example, here's a Go package that provides two functions -
<code>Random</code> and <code>Seed</code> - that wrap C's <code>rand</code>
and <code>srand</code> functions.
</p>
{{code "/doc/progs/cgo1.go" `/package rand/` `/END/`}}
<p>
Let's look at what's happening here, starting with the import statement.
</p>
<p>
The <code>rand</code> package imports <code>"C"</code>, but you'll find there's
no such package in the standard Go library. That's because <code>C</code> is a
"pseudo-package", a special name interpreted by cgo as a reference to C's
name space.
</p>
<p>
The <code>rand</code> package contains four references to the <code>C</code>
package: the calls to <code>C.rand</code> and <code>C.srand</code>, the
conversion <code>C.uint(i)</code>, and the <code>import</code> statement.
</p>
<p>
The <code>Random</code> function calls the standard C library's <code>random</code>
function and returns the result. In C, <code>rand</code> returns a value of the
C type <code>int</code>, which cgo represents as the type <code>C.int</code>.
It must be converted to a Go type before it can be used by Go code outside this
package, using an ordinary Go type conversion:
</p>
{{code "/doc/progs/cgo1.go" `/func Random/` `/STOP/`}}
<p>
Here's an equivalent function that uses a temporary variable to illustrate
the type conversion more explicitly:
</p>
{{code "/doc/progs/cgo2.go" `/func Random/` `/STOP/`}}
<p>
The <code>Seed</code> function does the reverse, in a way. It takes a
regular Go <code>int</code>, converts it to the C <code>unsigned int</code>
type, and passes it to the C function <code>srand</code>.
</p>
{{code "/doc/progs/cgo1.go" `/func Seed/` `/END/`}}
<p>
Note that cgo knows the <code>unsigned int</code> type as <code>C.uint</code>;
see the <a href="/cmd/cgo">cgo documentation</a> for a complete list of
these numeric type names.
</p>
<p>
The one detail of this example we haven't examined yet is the comment
above the <code>import</code> statement.
</p>
{{code "/doc/progs/cgo1.go" `/\/\*/` `/STOP/`}}
<p>
Cgo recognizes this comment. Any lines starting
with <code>#cgo</code>
followed
by a space character are removed; these become directives for cgo.
The remaining lines are used as a header when compiling the C parts of
the package. In this case those lines are just a
single <code>#include</code>
statement, but they can be almost any C code. The <code>#cgo</code>
directives are
used to provide flags for the compiler and linker when building the C
parts of the package.
</p>
<p>
There is a limitation: if your program uses any <code>//export</code>
directives, then the C code in the comment may only include declarations
(<code>extern int f();</code>), not definitions (<code>int f() {
return 1; }</code>). You can use <code>//export</code> directives to
make Go functions accessible to C code.
</p>
<p>
The <code>#cgo</code> and <code>//export</code> directives are
documented in
the <a href="/cmd/cgo/">cgo documentation</a>.
</p>
<p>
<b>Strings and things</b>
</p>
<p>
Unlike Go, C doesn't have an explicit string type. Strings in C are
represented by a zero-terminated array of chars.
</p>
<p>
Conversion between Go and C strings is done with the
<code>C.CString</code>, <code>C.GoString</code>, and
<code>C.GoStringN</code> functions. These conversions make a copy of the
string data.
</p>
<p>
This next example implements a <code>Print</code> function that writes a
string to standard output using C's <code>fputs</code> function from the
<code>stdio</code> library:
</p>
{{code "/doc/progs/cgo3.go" `/package print/` `/END/`}}
<p>
Memory allocations made by C code are not known to Go's memory manager.
When you create a C string with <code>C.CString</code> (or any C memory
allocation) you must remember to free the memory when you're done with it
by calling <code>C.free</code>.
</p>
<p>
The call to <code>C.CString</code> returns a pointer to the start of the
char array, so before the function exits we convert it to an
<a href="/pkg/unsafe/#Pointer"><code>unsafe.Pointer</code></a> and release
the memory allocation with <code>C.free</code>. A common idiom in cgo programs
is to <a href="/doc/articles/defer_panic_recover.html"><code>defer</code></a>
the free immediately after allocating (especially when the code that follows
is more complex than a single function call), as in this rewrite of
<code>Print</code>:
</p>
{{code "/doc/progs/cgo4.go" `/func Print/` `/END/`}}
<p>
<b>Building cgo packages</b>
</p>
<p>
To build cgo packages, just use <a href="/cmd/go/#hdr-Compile_packages_and_dependencies">"
<code>go build</code>"</a> or
<a href="/cmd/go/#hdr-Compile_and_install_packages_and_dependencies">"<code>go install</code>
"</a> as usual. The go tool recognizes the special <code>"C"</code> import and automatically
uses cgo for those files.
</p>
<p>
<b>More cgo resources</b>
</p>
<p>
The <a href="/cmd/cgo/">cgo command</a> documentation has more detail about
the C pseudo-package and the build process. The <a href="/misc/cgo/">cgo examples</a>
in the Go tree demonstrate more advanced concepts.
</p>
<p>
For a simple, idiomatic example of a cgo-based package, see Russ Cox's <a
href="http://code.google.com/p/gosqlite/source/browse/sqlite/sqlite.go">gosqlite</a>.
Also, the <a href="http://code.google.com/p/go-wiki/wiki/Projects">Go Community Wiki</a>
lists many packages, some of which use cgo.
</p>
<p>
Finally, if you're curious as to how all this works internally, take a look
at the introductory comment of the runtime package's <a href="/src/pkg/runtime/cgocall.c">cgocall.c</a>.
</p>
doc/articles/concurrency_patterns.html deleted 100644 → 0
View file @ 83da0fd9
<!--{
"Title": "Go Concurrency Patterns: Timing out, moving on",
"Template": true
}-->
<p>
Concurrent programming has its own idioms. A good example is timeouts. Although
Go's channels do not support them directly, they are easy to implement. Say we
want to receive from the channel <code>ch</code>, but want to wait at most one
second for the value to arrive. We would start by creating a signalling channel
and launching a goroutine that sleeps before sending on the channel:
</p>
{{code "/doc/progs/timeout1.go" `/timeout :=/` `/STOP/`}}
<p>
We can then use a <code>select</code> statement to receive from either
<code>ch</code> or <code>timeout</code>. If nothing arrives on <code>ch</code>
after one second, the timeout case is selected and the attempt to read from
<code>ch</code> is abandoned.
</p>
{{code "/doc/progs/timeout1.go" `/select {/` `/STOP/`}}
<p>
The <code>timeout</code> channel is buffered with space for 1 value, allowing
the timeout goroutine to send to the channel and then exit. The goroutine
doesn't know (or care) whether the value is received. This means the goroutine
won't hang around forever if the <code>ch</code> receive happens before the
timeout is reached. The <code>timeout</code> channel will eventually be
deallocated by the garbage collector.
</p>
<p>
(In this example we used <code>time.Sleep</code> to demonstrate the mechanics
of goroutines and channels. In real programs you should use <code>
<a href="/pkg/time/#After">time.After</a></code>, a function that returns
a channel and sends on that channel after the specified duration.)
</p>
<p>
Let's look at another variation of this pattern. In this example we have a
program that reads from multiple replicated databases simultaneously. The
program needs only one of the answers, and it should accept the answer that
arrives first.
</p>
<p>
The function <code>Query</code> takes a slice of database connections and a
<code>query</code> string. It queries each of the databases in parallel and
returns the first response it receives:
</p>
{{code "/doc/progs/timeout2.go" `/func Query/` `/STOP/`}}
<p>
In this example, the closure does a non-blocking send, which it achieves by
using the send operation in <code>select</code> statement with a
<code>default</code> case. If the send cannot go through immediately the
default case will be selected. Making the send non-blocking guarantees that
none of the goroutines launched in the loop will hang around. However, if the
result arrives before the main function has made it to the receive, the send
could fail since no one is ready.
</p>
<p>
This problem is a textbook example of what is known as a
<a href="https://en.wikipedia.org/wiki/Race_condition">race condition</a>, but
the fix is trivial. We just make sure to buffer the channel <code>ch</code> (by
adding the buffer length as the second argument to <a href="/pkg/builtin/#make">make</a>),
guaranteeing that the first send has a place to put the value. This ensures the
send will always succeed, and the first value to arrive will be retrieved
regardless of the order of execution.
</p>
<p>
These two examples demonstrate the simplicity with which Go can express complex
interactions between goroutines.
</p>
doc/articles/defer_panic_recover.html deleted 100644 → 0
View file @ 83da0fd9
<!--{
"Title": "Defer, Panic, and Recover",
"Template": true
}-->
<p>
Go has the usual mechanisms for control flow: if, for, switch, goto. It also
has the go statement to run code in a separate goroutine. Here I'd like to
discuss some of the less common ones: defer, panic, and recover.
</p>
<p>
A <b>defer statement</b> pushes a function call onto a list. The list of saved
calls is executed after the surrounding function returns. Defer is commonly
used to simplify functions that perform various clean-up actions.
</p>
<p>
For example, let's look at a function that opens two files and copies the
contents of one file to the other:
</p>
{{code "/doc/progs/defer.go" `/func CopyFile/` `/STOP/`}}
<p>
This works, but there is a bug. If the call to os.Create fails, the
function will return without closing the source file. This can be easily
remedied by putting a call to src.Close before the second return statement,
but if the function were more complex the problem might not be so easily
noticed and resolved. By introducing defer statements we can ensure that the
files are always closed:
</p>
{{code "/doc/progs/defer2.go" `/func CopyFile/` `/STOP/`}}
<p>
Defer statements allow us to think about closing each file right after opening
it, guaranteeing that, regardless of the number of return statements in the
function, the files <i>will</i> be closed.
</p>
<p>
The behavior of defer statements is straightforward and predictable. There are
three simple rules:
</p>
<p>
1. <i>A deferred function's arguments are evaluated when the defer statement is
evaluated.</i>
</p>
<p>
In this example, the expression "i" is evaluated when the Println call is
deferred. The deferred call will print "0" after the function returns.
</p>
{{code "/doc/progs/defer.go" `/func a/` `/STOP/`}}
<p>
2. <i>Deferred function calls are executed in Last In First Out order
</i>after<i> the surrounding function returns.</i>
</p>
<p>
This function prints "3210":
</p>
{{code "/doc/progs/defer.go" `/func b/` `/STOP/`}}
<p>
3. <i>Deferred functions may read and assign to the returning function's named
return values.</i>
</p>
<p>
In this example, a deferred function increments the return value i <i>after</i>
the surrounding function returns. Thus, this function returns 2:
</p>
{{code "/doc/progs/defer.go" `/func c/` `/STOP/`}}
<p>
This is convenient for modifying the error return value of a function; we will
see an example of this shortly.
</p>
<p>
<b>Panic</b> is a built-in function that stops the ordinary flow of control and
begins <i>panicking</i>. When the function F calls panic, execution of F stops,
any deferred functions in F are executed normally, and then F returns to its
caller. To the caller, F then behaves like a call to panic. The process
continues up the stack until all functions in the current goroutine have
returned, at which point the program crashes. Panics can be initiated by
invoking panic directly. They can also be caused by runtime errors, such as
out-of-bounds array accesses.
</p>
<p>
<b>Recover</b> is a built-in function that regains control of a panicking
goroutine. Recover is only useful inside deferred functions. During normal
execution, a call to recover will return nil and have no other effect. If the
current goroutine is panicking, a call to recover will capture the value given
to panic and resume normal execution.
</p>
<p>
Here's an example program that demonstrates the mechanics of panic and defer:
</p>
{{code "/doc/progs/defer2.go" `/package main/` `/STOP/`}}
<p>
The function g takes the int i, and panics if i is greater than 3, or else it
calls itself with the argument i+1. The function f defers a function that calls
recover and prints the recovered value (if it is non-nil). Try to picture what
the output of this program might be before reading on.
</p>
<p>
The program will output:
</p>
<pre>Calling g.
Printing in g 0
Printing in g 1
Printing in g 2
Printing in g 3
Panicking!
Defer in g 3
Defer in g 2
Defer in g 1
Defer in g 0
Recovered in f 4
Returned normally from f.</pre>
<p>
If we remove the deferred function from f the panic is not recovered and
reaches the top of the goroutine's call stack, terminating the program. This
modified program will output:
</p>
<pre>Calling g.
Printing in g 0
Printing in g 1
Printing in g 2
Printing in g 3
Panicking!
Defer in g 3
Defer in g 2
Defer in g 1
Defer in g 0
panic: 4
panic PC=0x2a9cd8
[stack trace omitted]</pre>
<p>
For a real-world example of <b>panic</b> and <b>recover</b>, see the
<a href="/pkg/encoding/json/">json package</a> from the Go standard library.
It decodes JSON-encoded data with a set of recursive functions.
When malformed JSON is encountered, the parser calls panic to unwind the
stack to the top-level function call, which recovers from the panic and returns
an appropriate error value (see the 'error' and 'unmarshal' methods of
the decodeState type in
<a href="/src/pkg/encoding/json/decode.go">decode.go</a>).
</p>
<p>
The convention in the Go libraries is that even when a package uses panic
internally, its external API still presents explicit error return values.
</p>
<p>
Other uses of <b>defer</b> (beyond the file.Close example given earlier)
include releasing a mutex:
</p>
<pre>mu.Lock()
defer mu.Unlock()</pre>
<p>
printing a footer:
</p>
<pre>printHeader()
defer printFooter()</pre>
<p>
and more.
</p>
<p>
In summary, the defer statement (with or without panic and recover) provides an
unusual and powerful mechanism for control flow. It can be used to model a
number of features implemented by special-purpose structures in other
programming languages. Try it out.
</p>
doc/articles/error_handling.html deleted 100644 → 0
View file @ 83da0fd9
This diff is collapsed.
doc/articles/gobs_of_data.html deleted 100644 → 0
View file @ 83da0fd9
This diff is collapsed.
doc/articles/godoc_documenting_go_code.html deleted 100644 → 0
View file @ 83da0fd9
<!--{
"Title": "Godoc: documenting Go code",
"Template": true
}-->
<p>
The Go project takes documentation seriously. Documentation is a huge part of
making software accessible and maintainable. Of course it must be well-written
and accurate, but it also must be easy to write and to maintain. Ideally, it
should be coupled to the code itself so the documentation evolves along with the
code. The easier it is for programmers to produce good documentation, the better
for everyone.
</p>
<p>
To that end, we have developed the <a href="/cmd/godoc/">godoc</a> documentation
tool. This article describes godoc's approach to documentation, and explains how
you can use our conventions and tools to write good documentation for your own
projects.
</p>
<p>
Godoc parses Go source code - including comments - and produces documentation as
HTML or plain text. The end result is documentation tightly coupled with the
code it documents. For example, through godoc's web interface you can navigate
from a function's <a href="/pkg/strings/#HasPrefix">documentation</a> to its
<a href="/src/pkg/strings/strings.go?#L312">implementation</a> with one click.
</p>
<p>
Godoc is conceptually related to Python's
<a href="http://www.python.org/dev/peps/pep-0257/">Docstring</a> and Java's
<a href="http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html">Javadoc</a>,
but its design is simpler. The comments read by godoc are not language
constructs (as with Docstring) nor must they have their own machine-readable
syntax (as with Javadoc). Godoc comments are just good comments, the sort you
would want to read even if godoc didn't exist.
</p>
<p>
The convention is simple: to document a type, variable, constant, function, or
even a package, write a regular comment directly preceding its declaration, with
no intervening blank line. Godoc will then present that comment as text
alongside the item it documents. For example, this is the documentation for the
<code>fmt</code> package's <a href="/pkg/fmt/#Fprint"><code>Fprint</code></a>
function:
</p>
{{code "/src/pkg/fmt/print.go" `/Fprint formats using the default/` `/func Fprint/`}}
<p>
Notice this comment is a complete sentence that begins with the name of the
element it describes. This important convention allows us to generate
documentation in a variety of formats, from plain text to HTML to UNIX man
pages, and makes it read better when tools truncate it for brevity, such as when
they extract the first line or sentence.
</p>
<p>
Comments on package declarations should provide general package documentation.
These comments can be short, like the <a href="/pkg/sort/"><code>sort</code></a>
package's brief description:
</p>
{{code "/src/pkg/sort/sort.go" `/Package sort provides/` `/package sort/`}}
<p>
They can also be detailed like the <a href="/pkg/encoding/gob/"><code>gob</code></a>
package's overview. That package uses another convention for packages
that need large amounts of introductory documentation: the package comment is
placed in its own file, <a href="/src/pkg/encoding/gob/doc.go">doc.go</a>, which
contains only those comments and a package clause.
</p>
<p>
When writing package comments of any size, keep in mind that their first
sentence will appear in godoc's <a href="/pkg/">package list</a>.
</p>
<p>
Comments that are not adjacent to a top-level declaration are omitted from
godoc's output, with one notable exception. Top-level comments that begin with
the word <code>"BUG(who)"</code> are recognized as known bugs, and included in
the "Bugs" section of the package documentation. The "who" part should be the
user name of someone who could provide more information. For example, this is a
known issue from the <a href="/pkg/sync/atomic/#pkg-note-BUG"><code>sync/atomic</code></a> package:
</p>
<pre>
// BUG(rsc): On x86-32, the 64-bit functions use instructions
// unavailable before the Pentium MMX. On both ARM and x86-32, it is the
// caller's responsibility to arrange for 64-bit alignment of 64-bit
// words accessed atomically.
</pre>
<p>
Godoc treats executable commands in the same way. It looks for a comment on
package main, which is sometimes put in a separate file called <code>doc.go</code>.
For example, see the
<a href="/cmd/godoc/">godoc documentation</a> and its corresponding
<a href="/src/cmd/godoc/doc.go">doc.go</a> file.
</p>
<p>
There are a few formatting rules that Godoc uses when converting comments to
HTML:
</p>
<ul>
<li>
Subsequent lines of text are considered part of the same paragraph; you must
leave a blank line to separate paragraphs.
</li>
<li>
Pre-formatted text must be indented relative to the surrounding comment text
(see gob's <a href="/src/pkg/encoding/gob/doc.go">doc.go</a> for an example).
</li>
<li>
URLs will be converted to HTML links; no special markup is necessary.
</li>
</ul>
<p>
Note that none of these rules requires you to do anything out of the ordinary.
</p>
<p>
In fact, the best thing about godoc's minimal approach is how easy it is to use.
As a result, a lot of Go code, including all of the standard library, already
follows the conventions.
</p>
<p>
Your own code can present good documentation just by having comments as
described above. Any Go packages installed inside <code>$GOROOT/src/pkg</code>
and any <code>GOPATH</code> work spaces will already be accessible via godoc's
command-line and HTTP interfaces, and you can specify additional paths for
indexing via the <code>-path</code> flag or just by running <code>"godoc ."</code>
in the source directory. See the <a href="/cmd/godoc/">godoc documentation</a>
for more details.
</p>
<p>
Godoc recognizes example functions written according to the
<a href="/pkg/testing/#pkg-overview"><code>testing</code></a> package's naming
conventions and presents them appropriately.
</p>
doc/articles/gos_declaration_syntax.html deleted 100644 → 0
View file @ 83da0fd9
<!--{
"Title": "Go's Declaration Syntax"
}-->
<p>
Newcomers to Go wonder why the declaration syntax is different from the
tradition established in the C family. In this post we'll compare the
two approaches and explain why Go's declarations look as they do.
</p>
<p>
<b>C syntax</b>
</p>
<p>
First, let's talk about C syntax. C took an unusual and clever approach
to declaration syntax. Instead of describing the types with special
syntax, one writes an expression involving the item being declared, and
states what type that expression will have. Thus
</p>
<pre>
int x;
</pre>
<p>
declares x to be an int: the expression 'x' will have type int. In
general, to figure out how to write the type of a new variable, write an
expression involving that variable that evaluates to a basic type, then
put the basic type on the left and the expression on the right.
</p>
<p>
Thus, the declarations
</p>
<pre>
int *p;
int a[3];
</pre>
<p>
state that p is a pointer to int because '*p' has type int, and that a
is an array of ints because a[3] (ignoring the particular index value,
which is punned to be the size of the array) has type int.
</p>
<p>
What about functions? Originally, C's function declarations wrote the
types of the arguments outside the parens, like this:
</p>
<pre>
int main(argc, argv)
int argc;
char *argv[];
{ /* ... */ }
</pre>
<p>
Again, we see that main is a function because the expression main(argc,
argv) returns an int. In modern notation we'd write
</p>
<pre>
int main(int argc, char *argv[]) { /* ... */ }
</pre>
<p>
but the basic structure is the same.
</p>
<p>
This is a clever syntactic idea that works well for simple types but can
get confusing fast. The famous example is declaring a function pointer.
Follow the rules and you get this:
</p>
<pre>
int (*fp)(int a, int b);
</pre>
<p>
Here, fp is a pointer to a function because if you write the expression
(*fp)(a, b) you'll call a function that returns int. What if one of fp's
arguments is itself a function?
</p>
<pre>
int (*fp)(int (*ff)(int x, int y), int b)
</pre>
<p>
That's starting to get hard to read.
</p>
<p>
Of course, we can leave out the name of the parameters when we declare a
function, so main can be declared
</p>
<pre>
int main(int, char *[])
</pre>
<p>
Recall that argv is declared like this,
</p>
<pre>
char *argv[]
</pre>
<p>
so you drop the name from the <em>middle</em> of its declaration to construct
its type. It's not obvious, though, that you declare something of type
char *[] by putting its name in the middle.
</p>
<p>
And look what happens to fp's declaration if you don't name the
parameters:
</p>
<pre>
int (*fp)(int (*)(int, int), int)
</pre>
<p>
Not only is it not obvious where to put the name inside
</p>
<pre>
int (*)(int, int)
</pre>
<p>
it's not exactly clear that it's a function pointer declaration at all.
And what if the return type is a function pointer?
</p>
<pre>
int (*(*fp)(int (*)(int, int), int))(int, int)
</pre>
<p>
It's hard even to see that this declaration is about fp.
</p>
<p>
You can construct more elaborate examples but these should illustrate
some of the difficulties that C's declaration syntax can introduce.
</p>
<p>
There's one more point that needs to be made, though. Because type and
declaration syntax are the same, it can be difficult to parse
expressions with types in the middle. This is why, for instance, C casts
always parenthesize the type, as in
</p>
<pre>
(int)M_PI
</pre>
<p>
<b>Go syntax</b>
</p>
<p>
Languages outside the C family usually use a distinct type syntax in
declarations. Although it's a separate point, the name usually comes
first, often followed by a colon. Thus our examples above become
something like (in a fictional but illustrative language)
</p>
<pre>
x: int
p: pointer to int
a: array[3] of int
</pre>
<p>
These declarations are clear, if verbose - you just read them left to
right. Go takes its cue from here, but in the interests of brevity it
drops the colon and removes some of the keywords:
</p>
<pre>
x int
p *int
a [3]int
</pre>
<p>
There is no direct correspondence between the look of [3]int and how to
use a in an expression. (We'll come back to pointers in the next
section.) You gain clarity at the cost of a separate syntax.
</p>
<p>
Now consider functions. Let's transcribe the declaration for main, even
though the main function in Go takes no arguments:
</p>
<pre>
func main(argc int, argv *[]byte) int
</pre>
<p>
Superficially that's not much different from C, but it reads well from
left to right:
</p>
<p>
<em>function main takes an int and a pointer to a slice of bytes and returns an int.</em>
</p>
<p>
Drop the parameter names and it's just as clear - they're always first
so there's no confusion.
</p>
<pre>
func main(int, *[]byte) int
</pre>
<p>
One value of this left-to-right style is how well it works as the types
become more complex. Here's a declaration of a function variable
(analogous to a function pointer in C):
</p>
<pre>
f func(func(int,int) int, int) int
</pre>
<p>
Or if f returns a function:
</p>
<pre>
f func(func(int,int) int, int) func(int, int) int
</pre>
<p>
It still reads clearly, from left to right, and it's always obvious
which name is being declared - the name comes first.
</p>
<p>
The distinction between type and expression syntax makes it easy to
write and invoke closures in Go:
</p>
<pre>
sum := func(a, b int) int { return a+b } (3, 4)
</pre>
<p>
<b>Pointers</b>
</p>
<p>
Pointers are the exception that proves the rule. Notice that in arrays
and slices, for instance, Go's type syntax puts the brackets on the left
of the type but the expression syntax puts them on the right of the
expression:
</p>
<pre>
var a []int
x = a[1]
</pre>
<p>
For familiarity, Go's pointers use the * notation from C, but we could
not bring ourselves to make a similar reversal for pointer types. Thus
pointers work like this
</p>
<pre>
var p *int
x = *p
</pre>
<p>
We couldn't say
</p>
<pre>
var p *int
x = p*
</pre>
<p>
because that postfix * would conflate with multiplication. We could have
used the Pascal ^, for example:
</p>
<pre>
var p ^int
x = p^
</pre>
<p>
and perhaps we should have (and chosen another operator for xor),
because the prefix asterisk on both types and expressions complicates
things in a number of ways. For instance, although one can write
</p>
<pre>
[]int("hi")
</pre>
<p>
as a conversion, one must parenthesize the type if it starts with a *:
</p>
<pre>
(*int)(nil)
</pre>
<p>
Had we been willing to give up * as pointer syntax, those parentheses
would be unnecessary.
</p>
<p>
So Go's pointer syntax is tied to the familiar C form, but those ties
mean that we cannot break completely from using parentheses to
disambiguate types and expressions in the grammar.
</p>
<p>
Overall, though, we believe Go's type syntax is easier to understand
than C's, especially when things get complicated.
</p>
<p>
<b>Notes</b>
</p>
<p>
Go's declarations read left to right. It's been pointed out that C's
read in a spiral! See <a href="http://c-faq.com/decl/spiral.anderson.html">
The "Clockwise/Spiral Rule"</a> by David Anderson.
</p>
doc/articles/image_draw.html deleted 100644 → 0
View file @ 83da0fd9
<!--{
"Title": "The Go image/draw package",
"Template": true
}-->
<p>
<a href="/pkg/image/draw/">Package image/draw</a> defines
only one operation: drawing a source image onto a destination
image, through an optional mask image. This one operation is
surprisingly versatile and can perform a number of common image
manipulation tasks elegantly and efficiently.
</p>
<p>
Composition is performed pixel by pixel in the style of the Plan 9
graphics library and the X Render extension. The model is based on
the classic "Compositing Digital Images" paper by Porter and Duff,
with an additional mask parameter: <code>dst = (src IN mask) OP dst</code>.
For a fully opaque mask, this reduces to the original Porter-Duff
formula: <code>dst = src OP dst</code>. In Go, a nil mask image is equivalent
to an infinitely sized, fully opaque mask image.
</p>
<p>
The Porter-Duff paper presented
<a href="http://www.w3.org/TR/SVGCompositing/examples/compop-porterduff-examples.png">12 different composition operators</a>,
but with an explicit mask, only 2 of these are needed in practice:
source-over-destination and source. In Go, these operators are
represented by the <code>Over</code> and <code>Src</code> constants. The <code>Over</code> operator
performs the natural layering of a source image over a destination
image: the change to the destination image is smaller where the
source (after masking) is more transparent (that is, has lower
alpha). The <code>Src</code> operator merely copies the source (after masking)
with no regard for the destination image's original content. For
fully opaque source and mask images, the two operators produce the
same output, but the <code>Src</code> operator is usually faster.
</p>
<p><b>Geometric Alignment</b></p>
<p>
Composition requires associating destination pixels with source and
mask pixels. Obviously, this requires destination, source and mask
images, and a composition operator, but it also requires specifying
what rectangle of each image to use. Not every drawing should write
to the entire destination: when updating an animating image, it is
more efficient to only draw the parts of the image that have
changed. Not every drawing should read from the entire source: when
using a sprite that combines many small images into one large one,
only a part of the image is needed. Not every drawing should read
from the entire mask: a mask image that collects a font's glyphs is
similar to a sprite. Thus, drawing also needs to know three
rectangles, one for each image. Since each rectangle has the same
width and height, it suffices to pass a destination rectangle `r`
and two points <code>sp</code> and <code>mp</code>: the source rectangle is equal to <code>r</code>
translated so that <code>r.Min</code> in the destination image aligns with
<code>sp</code> in the source image, and similarly for <code>mp</code>. The effective
rectangle is also clipped to each image's bounds in their
respective co-ordinate space.
</p>
<p>
<img src="image-20.png">
</p>
<p>
The <a href="/pkg/image/draw/#DrawMask"><code>DrawMask</code></a>
function takes seven arguments, but an explicit mask and mask-point
are usually unnecessary, so the
<a href="/pkg/image/draw/#Draw"><code>Draw</code></a> function takes five:
</p>
<pre>
// Draw calls DrawMask with a nil mask.
func Draw(dst Image, r image.Rectangle, src image.Image, sp image.Point, op Op)
func DrawMask(dst Image, r image.Rectangle, src image.Image, sp image.Point,
mask image.Image, mp image.Point, op Op)
</pre>
<p>
The destination image must be mutable, so the image/draw package
defines a <a href="/pkg/image/draw/#Image"><code>draw.Image</code></a>
interface which has a <code>Set</code> method.
</p>
{{code "../src/pkg/image/draw/draw.go" `/type Image/` `/}/`}}
<p><b>Filling a Rectangle</b></p>
<p>
To fill a rectangle with a solid color, use an <code>image.Uniform</code>
source. The <code>Uniform</code> type re-interprets a <code>Color</code> as a
practically infinite-sized <code>Image</code> of that color. For those
familiar with the design of Plan 9's draw library, there is no need
for an explicit "repeat bit" in Go's slice-based image types; the
concept is subsumed by <code>Uniform</code>.
</p>
{{code "/doc/progs/image_draw.go" `/ZERO/` `/STOP/`}}
<p>
To initialize a new image to all-blue:
</p>
{{code "/doc/progs/image_draw.go" `/BLUE/` `/STOP/`}}
<p>
To reset an image to transparent (or black, if the destination
image's color model cannot represent transparency), use
<code>image.Transparent</code>, which is an <code>image.Uniform</code>:
</p>
{{code "/doc/progs/image_draw.go" `/RESET/` `/STOP/`}}
<p>
<img src="image-2a.png">
</p>
<p><b>Copying an Image</b></p>
<p>
To copy from a rectangle <code>sr</code> in the source image to a rectangle
starting at a point <code>dp</code> in the destination, convert the source
rectangle into the destination image's co-ordinate space:
</p>
{{code "/doc/progs/image_draw.go" `/RECT/` `/STOP/`}}
<p>
Alternatively:
</p>
{{code "/doc/progs/image_draw.go" `/RECT2/` `/STOP/`}}
<p>
To copy the entire source image, use <code>sr = src.Bounds()</code>.
</p>
<p>
<img src="image-2b.png">
</p>
<p><b>Scrolling an Image</b></p>
<p>
Scrolling an image is just copying an image to itself, with
different destination and source rectangles. Overlapping
destination and source images are perfectly valid, just as Go's
built-in copy function can handle overlapping destination and
source slices. To scroll an image m by 20 pixels:
</p>
{{code "/doc/progs/image_draw.go" `/SCROLL/` `/STOP/`}}
<p><img src="image-2c.png"></p>
<p><b>Converting an Image to RGBA</b></p>
<p>
The result of decoding an image format might not be an
<code>image.RGBA</code>: decoding a GIF results in an <code>image.Paletted</code>,
decoding a JPEG results in a <code>ycbcr.YCbCr</code>, and the result of
decoding a PNG depends on the image data. To convert any image to
an <code>image.RGBA</code>:
</p>
{{code "/doc/progs/image_draw.go" `/CONV/` `/STOP/`}}
<p>
<img src="image-2d.png">
</p>
<p><b>Drawing Through a Mask</b></p>
<p>
To draw an image through a circular mask with center <code>p</code> and radius
<code>r</code>:
</p>
{{code "/doc/progs/image_draw.go" `/CIRCLESTRUCT/` `/STOP/`}}
{{code "/doc/progs/image_draw.go" `/CIRCLE2/` `/STOP/`}}
<p>
<img src="image-2e.png">
</p>
<p><b>Drawing Font Glyphs</b></p>
<p>
To draw a font glyph in blue starting from a point <code>p</code>, draw with
an <code>image.Uniform</code> source and an <code>image.Alpha mask</code>. For
simplicity, we aren't performing any sub-pixel positioning or
rendering, or correcting for a font's height above a baseline.
</p>
{{code "/doc/progs/image_draw.go" `/GLYPH/` `/STOP/`}}
<p>
<img src="image-2f.png">
</p>
<p><b>Performance</b></p>
<p>
The image/draw package implementation demonstrates how to provide
an image manipulation function that is both general purpose, yet
efficient for common cases. The <code>DrawMask</code> function takes arguments
of interface types, but immediately makes type assertions that its
arguments are of specific struct types, corresponding to common
operations like drawing one <code>image.RGBA</code> image onto another, or
drawing an <code>image.Alpha</code> mask (such as a font glyph) onto an
<code>image.RGBA</code> image. If a type assertion succeeds, that type
information is used to run a specialized implementation of the
general algorithm. If the assertions fail, the fallback code path
uses the generic <code>At</code> and <code>Set</code> methods. The fast-paths are purely
a performance optimization; the resultant destination image is the
same either way. In practice, only a small number of special cases
are necessary to support typical applications.
</p>
doc/articles/image_package.html deleted 100644 → 0
View file @ 83da0fd9
This diff is collapsed.
doc/articles/index.html
View file @ 5dd74175
......@@ -3,5 +3,6 @@
}-->
<p>
See the <a href="/doc/#articles">Documents page</a> for a complete list of Go articles.
See the <a href="/doc/#articles">Documents page</a> and the
<a href="/blog/index">Blog index</a> for a complete list of Go articles.
</p>
doc/articles/json_and_go.html deleted 100644 → 0
View file @ 83da0fd9
<!--{
"Title": "JSON and Go",
"Template": true
}-->
<p>
JSON (JavaScript Object Notation) is a simple data interchange format.
Syntactically it resembles the objects and lists of JavaScript. It is most
commonly used for communication between web back-ends and JavaScript programs
running in the browser, but it is used in many other places, too. Its home page,
<a href="http://json.org">json.org</a>, provides a wonderfully clear and concise
definition of the standard.
</p>
<p>
With the <a href="/pkg/encoding/json/">json package</a> it's a snap to read and
write JSON data from your Go programs.
</p>
<p>
<b>Encoding</b>
</p>
<p>
To encode JSON data we use the
<a href="/pkg/encoding/json/#Marshal"><code>Marshal</code></a> function.
</p>
<pre>
func Marshal(v interface{}) ([]byte, error)
</pre>
<p>
Given the Go data structure, <code>Message</code>,
</p>
{{code "/doc/progs/json1.go" `/type Message/` `/STOP/`}}
<p>
and an instance of <code>Message</code>
</p>
{{code "/doc/progs/json1.go" `/m :=/`}}
<p>
we can marshal a JSON-encoded version of <code>m</code> using <code>json.Marshal</code>:
</p>
{{code "/doc/progs/json1.go" `/b, err :=/`}}
<p>
If all is well, <code>err</code> will be <code>nil</code> and <code>b</code>
will be a <code>[]byte</code> containing this JSON data:
</p>
<pre>
b == []byte(`{"Name":"Alice","Body":"Hello","Time":1294706395881547000}`)
</pre>
<p>
Only data structures that can be represented as valid JSON will be encoded:
</p>
<ul>
<li>
JSON objects only support strings as keys; to encode a Go map type it must be
of the form <code>map[string]T</code> (where <code>T</code> is any Go type
supported by the json package).
</li>
<li>
Channel, complex, and function types cannot be encoded.
</li>
<li>
Cyclic data structures are not supported; they will cause <code>Marshal</code>
to go into an infinite loop.
</li>
<li>
Pointers will be encoded as the values they point to (or 'null' if the pointer
is <code>nil</code>).
</li>
</ul>
<p>
The json package only accesses the exported fields of struct types (those that
begin with an uppercase letter). Therefore only the exported fields of a struct
will be present in the JSON output.
</p>
<p>
<b>Decoding</b>
</p>
<p>
To decode JSON data we use the
<a href="/pkg/encoding/json/#Unmarshal"><code>Unmarshal</code></a> function.
</p>
<pre>
func Unmarshal(data []byte, v interface{}) error
</pre>
<p>
We must first create a place where the decoded data will be stored
</p>
{{code "/doc/progs/json1.go" `/var m Message/`}}
<p>
and call <code>json.Unmarshal</code>, passing it a <code>[]byte</code> of JSON
data and a pointer to <code>m</code>
</p>
{{code "/doc/progs/json1.go" `/err := json.Unmarshal/`}}
<p>
If <code>b</code> contains valid JSON that fits in <code>m</code>, after the
call <code>err</code> will be <code>nil</code> and the data from <code>b</code>
will have been stored in the struct <code>m</code>, as if by an assignment
like:
</p>
{{code "/doc/progs/json1.go" `/m = Message/` `/STOP/`}}
<p>
How does <code>Unmarshal</code> identify the fields in which to store the
decoded data? For a given JSON key <code>"Foo"</code>, <code>Unmarshal</code>
will look through the destination struct's fields to find (in order of
preference):
</p>
<ul>
<li>
An exported field with a tag of <code>`json:"Foo"`</code> (see the
<a href="/ref/spec#Struct_types">Go spec</a> for more on struct tags),
</li>
<li>
An exported field named <code>"Foo"</code>, or
</li>
<li>
An exported field named <code>"FOO"</code> or <code>"FoO"</code> or some other
case-insensitive match of <code>"Foo"</code>.
</li>
</ul>
<p>
What happens when the structure of the JSON data doesn't exactly match the Go
type?
</p>
{{code "/doc/progs/json1.go" `/"Food":"Pickle"/` `/STOP/`}}
<p>
<code>Unmarshal</code> will decode only the fields that it can find in the
destination type. In this case, only the <code>Name</code> field of m will be
populated, and the <code>Food</code> field will be ignored. This behavior is
particularly useful when you wish to pick only a few specific fields out of a
large JSON blob. It also means that any unexported fields in the destination
struct will be unaffected by <code>Unmarshal</code>.
</p>
<p>
But what if you don't know the structure of your JSON data beforehand?
</p>
<p>
<b>Generic JSON with <code>interface{}</code></b>
</p>
<p>
The <code>interface{}</code> (empty interface) type describes an interface with
zero methods. Every Go type implements at least zero methods and therefore
satisfies the empty interface.
</p>
<p>
The empty interface serves as a general container type:
</p>
{{code "/doc/progs/json2.go" `/var i interface{}/` `/STOP/`}}
<p>
A type assertion accesses the underlying concrete type:
</p>
{{code "/doc/progs/json2.go" `/r := i/` `/STOP/`}}
<p>
Or, if the underlying type is unknown, a type switch determines the type:
</p>
{{code "/doc/progs/json2.go" `/switch v/` `/STOP/`}}
<p>
The json package uses <code>map[string]interface{}</code> and
<code>[]interface{}</code> values to store arbitrary JSON objects and arrays;
it will happily unmarshal any valid JSON blob into a plain
<code>interface{}</code> value. The default concrete Go types are:
</p>
<ul>
<li>
<code>bool</code> for JSON booleans,
</li>
<li>
<code>float64</code> for JSON numbers,
</li>
<li>
<code>string</code> for JSON strings, and
</li>
<li>
<code>nil</code> for JSON null.
</li>
</ul>
<p>
<b>Decoding arbitrary data</b>
</p>
<p>
Consider this JSON data, stored in the variable <code>b</code>:
</p>
{{code "/doc/progs/json3.go" `/b :=/`}}
<p>
Without knowing this data's structure, we can decode it into an
<code>interface{}</code> value with <code>Unmarshal</code>:
</p>
{{code "/doc/progs/json3.go" `/var f interface/` `/STOP/`}}
<p>
At this point the Go value in <code>f</code> would be a map whose keys are
strings and whose values are themselves stored as empty interface values:
</p>
{{code "/doc/progs/json3.go" `/f = map/` `/STOP/`}}
<p>
To access this data we can use a type assertion to access <code>f</code>'s
underlying <code>map[string]interface{}</code>:
</p>
{{code "/doc/progs/json3.go" `/m := f/`}}
<p>
We can then iterate through the map with a range statement and use a type switch
to access its values as their concrete types:
</p>
{{code "/doc/progs/json3.go" `/for k, v/` `/STOP/`}}
<p>
In this way you can work with unknown JSON data while still enjoying the
benefits of type safety.
</p>
<p>
<b>Reference Types</b>
</p>
<p>
Let's define a Go type to contain the data from the previous example:
</p>
{{code "/doc/progs/json4.go" `/type FamilyMember/` `/STOP/`}}
{{code "/doc/progs/json4.go" `/var m FamilyMember/` `/STOP/`}}
<p>
Unmarshaling that data into a <code>FamilyMember</code> value works as
expected, but if we look closely we can see a remarkable thing has happened.
With the var statement we allocated a <code>FamilyMember</code> struct, and
then provided a pointer to that value to <code>Unmarshal</code>, but at that
time the <code>Parents</code> field was a <code>nil</code> slice value. To
populate the <code>Parents</code> field, <code>Unmarshal</code> allocated a new
slice behind the scenes. This is typical of how <code>Unmarshal</code> works
with the supported reference types (pointers, slices, and maps).
</p>
<p>
Consider unmarshaling into this data structure:
</p>
<pre>
type Foo struct {
Bar *Bar
}
</pre>
<p>
If there were a <code>Bar</code> field in the JSON object,
<code>Unmarshal</code> would allocate a new <code>Bar</code> and populate it.
If not, <code>Bar</code> would be left as a <code>nil</code> pointer.
</p>
<p>
From this a useful pattern arises: if you have an application that receives a
few distinct message types, you might define "receiver" structure like
</p>
<pre>
type IncomingMessage struct {
Cmd *Command
Msg *Message
}
</pre>
<p>
and the sending party can populate the <code>Cmd</code> field and/or the
<code>Msg</code> field of the top-level JSON object, depending on the type of
message they want to communicate. <code>Unmarshal</code>, when decoding the
JSON into an <code>IncomingMessage</code> struct, will only allocate the data
structures present in the JSON data. To know which messages to process, the
programmer need simply test that either <code>Cmd</code> or <code>Msg</code> is
not <code>nil</code>.
</p>
<p>
<b>Streaming Encoders and Decoders</b>
</p>
<p>
The json package provides <code>Decoder</code> and <code>Encoder</code> types
to support the common operation of reading and writing streams of JSON data.
The <code>NewDecoder</code> and <code>NewEncoder</code> functions wrap the
<a href="/pkg/io/#Reader"><code>io.Reader</code></a> and
<a href="/pkg/io/#Writer"><code>io.Writer</code></a> interface types.
</p>
<pre>
func NewDecoder(r io.Reader) *Decoder
func NewEncoder(w io.Writer) *Encoder
</pre>
<p>
Here's an example program that reads a series of JSON objects from standard
input, removes all but the <code>Name</code> field from each object, and then
writes the objects to standard output:
</p>
{{code "/doc/progs/json5.go" `/package main/` `$`}}
<p>
Due to the ubiquity of Readers and Writers, these <code>Encoder</code> and
<code>Decoder</code> types can be used in a broad range of scenarios, such as
reading and writing to HTTP connections, WebSockets, or files.
</p>
<p>
<b>References</b>
</p>
<p>
For more information see the <a href="/pkg/encoding/json/">json package documentation</a>. For an example usage of
json see the source files of the <a href="/pkg/net/rpc/jsonrpc/">jsonrpc package</a>.
</p>
doc/articles/json_rpc_tale_of_interfaces.html deleted 100644 → 0
View file @ 83da0fd9
<!--{
"Title": "JSON-RPC: a tale of interfaces"
}-->
<p>
Here we present an example where Go's
<a href="/doc/effective_go.html#interfaces_and_types">interfaces</a> made it
easy to refactor some existing code to make it more flexible and extensible.
Originally, the standard library's <a href="/pkg/net/rpc/">RPC package</a> used
a custom wire format called <a href="/pkg/encoding/gob/">gob</a>. For a
particular application, we wanted to use <a href="/pkg/encoding/json/">JSON</a>
as an alternate wire format.
</p>
<p>
We first defined a pair of interfaces to describe the functionality of the
existing wire format, one for the client, and one for the server (depicted
below).
</p>
<pre>
type ServerCodec interface {
ReadRequestHeader(*Request) error
ReadRequestBody(interface{}) error
WriteResponse(*Response, interface{}) error
Close() error
}
</pre>
<p>
On the server side, we then changed two internal function signatures to accept
the <code>ServerCodec</code> interface instead of our existing
<code>gob.Encoder</code>. Here's one of them:
</p>
<pre>
func sendResponse(sending *sync.Mutex, req *Request,
reply interface{}, enc *gob.Encoder, errmsg string)
</pre>
<p>
became
</p>
<pre>
func sendResponse(sending *sync.Mutex, req *Request,
reply interface{}, enc ServerCodec, errmsg string)
</pre>
<p>
We then wrote a trivial <code>gobServerCodec</code> wrapper to reproduce the
original functionality. From there it is simple to build a
<code>jsonServerCodec</code>.
</p>
<p>
After some similar changes to the client side, this was the full extent of the
work we needed to do on the RPC package. This whole exercise took about 20
minutes! After tidying up and testing the new code, the
<a href="http://code.google.com/p/go/source/diff?spec=svn9daf796ebf1cae97b2fcf760a4ab682f1f063f29&amp;r=9daf796ebf1cae97b2fcf760a4ab682f1f063f29&amp;format=side&amp;path=/src/pkg/rpc/server.go">final changeset</a>
was submitted.
</p>
<p>
In an inheritance-oriented language like Java or C++, the obvious path would be
to generalize the RPC class, and create JsonRPC and GobRPC subclasses. However,
this approach becomes tricky if you want to make a further generalization
orthogonal to that hierarchy. (For example, if you were to implement an
alternate RPC standard). In our Go package, we took a route that is both
conceptually simpler and requires less code be written or changed.
</p>
<p>
A vital quality for any codebase is maintainability. As needs change, it is
essential to adapt your code easily and cleanly, lest it become unwieldy to work
with. We believe Go's lightweight, composition-oriented type system provides a
means of structuring code that scales.
</p>
doc/articles/laws_of_reflection.html deleted 100644 → 0
View file @ 83da0fd9
This diff is collapsed.
doc/articles/race_detector.html deleted 100644 → 0
View file @ 83da0fd9
<!--{
"Title": "Data Race Detector",
"Template": true
}-->
<h2 id="Introduction">Introduction</h2>
<p>
Data races are among the most common and hardest to debug types of bugs in concurrent systems.
A data race occurs when two goroutines access the same variable concurrently and at least one of the accesses is a write.
See the <a href="/ref/mem/">The Go Memory Model</a> for details.
</p>
<p>
Here is an example of a data race that can lead to crashes and memory corruption:
</p>
<pre>
func main() {
c := make(chan bool)
m := make(map[string]string)
go func() {
m["1"] = "a" // First conflicting access.
c &lt;- true
}()
m["2"] = "b" // Second conflicting access.
&lt;-c
for k, v := range m {
fmt.Println(k, v)
}
}
</pre>
<h2 id="Usage">Usage</h2>
<p>
To help diagnose such bugs, Go includes a built-in data race detector.
To use it, add the <code>-race</code> flag to the go command:
</p>
<pre>
$ go test -race mypkg // to test the package
$ go run -race mysrc.go // to run the source file
$ go build -race mycmd // to build the command
$ go install -race mypkg // to install the package
</pre>
<h2 id="Report_Format">Report Format</h2>
<p>
When the race detector finds a data race in the program, it prints a report.
The report contains stack traces for conflicting accesses, as well as stacks where the involved goroutines were created.
Here is an example:
</p>
<pre>
WARNING: DATA RACE
Read by goroutine 185:
net.(*pollServer).AddFD()
src/pkg/net/fd_unix.go:89 +0x398
net.(*pollServer).WaitWrite()
src/pkg/net/fd_unix.go:247 +0x45
net.(*netFD).Write()
src/pkg/net/fd_unix.go:540 +0x4d4
net.(*conn).Write()
src/pkg/net/net.go:129 +0x101
net.func·060()
src/pkg/net/timeout_test.go:603 +0xaf
Previous write by goroutine 184:
net.setWriteDeadline()
src/pkg/net/sockopt_posix.go:135 +0xdf
net.setDeadline()
src/pkg/net/sockopt_posix.go:144 +0x9c
net.(*conn).SetDeadline()
src/pkg/net/net.go:161 +0xe3
net.func·061()
src/pkg/net/timeout_test.go:616 +0x3ed
Goroutine 185 (running) created at:
net.func·061()
src/pkg/net/timeout_test.go:609 +0x288
Goroutine 184 (running) created at:
net.TestProlongTimeout()
src/pkg/net/timeout_test.go:618 +0x298
testing.tRunner()
src/pkg/testing/testing.go:301 +0xe8
</pre>
<h2 id="Options">Options</h2>
<p>
The <code>GORACE</code> environment variable sets race detector options.
The format is:
</p>
<pre>
GORACE="option1=val1 option2=val2"
</pre>
<p>
The options are:
</p>
<ul>
<li>
<code>log_path</code> (default <code>stderr</code>): The race detector writes
its report to a file named <code>log_path.<em>pid</em></code>.
The special names <code>stdout</code>
and <code>stderr</code> cause reports to be written to standard output and
standard error, respectively.
</li>
<li>
<code>exitcode</code> (default <code>66</code>): The exit status to use when
exiting after a detected race.
</li>
<li>
<code>strip_path_prefix</code> (default <code>""</code>): Strip this prefix
from all reported file paths, to make reports more concise.
</li>
<li>
<code>history_size</code> (default <code>1</code>): The per-goroutine memory
access history is <code>32K * 2**history_size elements</code>.
Increasing this value can avoid a "failed to restore the stack" error in reports, at the
cost of increased memory usage.
</li>
<li>
<code>halt_on_error</code> (default <code>0</code>): Controls whether the program
exits after reporting first data race.
</li>
</ul>
<p>
Example:
</p>
<pre>
$ GORACE="log_path=/tmp/race/report strip_path_prefix=/my/go/sources/" go test -race
</pre>
<h2 id="Excluding_Tests">Excluding Tests</h2>
<p>
When you build with <code>-race</code> flag, the <code>go</code> command defines additional
<a href="/pkg/go/build/#hdr-Build_Constraints">build tag</a> <code>race</code>.
You can use the tag to exclude some code and tests when running the race detector.
Some examples:
</p>
<pre>
// +build !race
package foo
// The test contains a data race. See issue 123.
func TestFoo(t *testing.T) {
// ...
}
// The test fails under the race detector due to timeouts.
func TestBar(t *testing.T) {
// ...
}
// The test takes too long under the race detector.
func TestBaz(t *testing.T) {
// ...
}
</pre>
<h2 id="How_To_Use">How To Use</h2>
<p>
To start, run your tests using the race detector (<code>go test -race</code>).
The race detector only finds races that happen at runtime, so it can't find
races in code paths that are not executed.
If your tests have incomplete coverage,
you may find more races by running a binary built with <code>-race</code> under a realistic
workload.
</p>
<h2 id="Typical_Data_Races">Typical Data Races</h2>
<p>
Here are some typical data races. All of them can be detected with the race detector.
</p>
<h3 id="Race_on_loop_counter">Race on loop counter</h3>
<pre>
func main() {
var wg sync.WaitGroup
wg.Add(5)
for i := 0; i < 5; i++ {
go func() {
fmt.Println(i) // Not the 'i' you are looking for.
wg.Done()
}()
}
wg.Wait()
}
</pre>
<p>
The variable <code>i</code> in the function literal is the same variable used by the loop, so
the read in the goroutine races with the loop increment.
(This program typically prints 55555, not 01234.)
The program can be fixed by making a copy of the variable:
</p>
<pre>
func main() {
var wg sync.WaitGroup
wg.Add(5)
for i := 0; i < 5; i++ {
go func(j int) {
fmt.Println(j) // Good. Read local copy of the loop counter.
wg.Done()
}(i)
}
wg.Wait()
}
</pre>
<h3 id="Accidentally_shared_variable">Accidentally shared variable</h3>
<pre>
// ParallelWrite writes data to file1 and file2, returns the errors.
func ParallelWrite(data []byte) chan error {
res := make(chan error, 2)
f1, err := os.Create("file1")
if err != nil {
res &lt;- err
} else {
go func() {
// This err is shared with the main goroutine,
// so the write races with the write below.
_, err = f1.Write(data)
res &lt;- err
f1.Close()
}()
}
f2, err := os.Create("file2") // The second conflicting write to err.
if err != nil {
res &lt;- err
} else {
go func() {
_, err = f2.Write(data)
res &lt;- err
f2.Close()
}()
}
return res
}
</pre>
<p>
The fix is to introduce new variables in the goroutines (note the use of <code>:=</code>):
</p>
<pre>
...
_, err := f1.Write(data)
...
_, err := f2.Write(data)
...
</pre>
<h3 id="Unprotected_global_variable">Unprotected global variable</h3>
<p>
If the following code is called from several goroutines, it leads to races on the <code>service</code> map.
Concurrent reads and writes of the same map are not safe:
</p>
<pre>
var service map[string]net.Addr
func RegisterService(name string, addr net.Addr) {
service[name] = addr
}
func LookupService(name string) net.Addr {
return service[name]
}
</pre>
<p>
To make the code safe, protect the accesses with a mutex:
</p>
<pre>
var (
service map[string]net.Addr
serviceMu sync.Mutex
)
func RegisterService(name string, addr net.Addr) {
serviceMu.Lock()
defer serviceMu.Unlock()
service[name] = addr
}
func LookupService(name string) net.Addr {
serviceMu.Lock()
defer serviceMu.Unlock()
return service[name]
}
</pre>
<h3 id="Primitive_unprotected_variable">Primitive unprotected variable</h3>
<p>
Data races can happen on variables of primitive types as well (<code>bool</code>, <code>int</code>, <code>int64</code>, etc.),
as in this example:
</p>
<pre>
type Watchdog struct{ last int64 }
func (w *Watchdog) KeepAlive() {
w.last = time.Now().UnixNano() // First conflicting access.
}
func (w *Watchdog) Start() {
go func() {
for {
time.Sleep(time.Second)
// Second conflicting access.
if w.last < time.Now().Add(-10*time.Second).UnixNano() {
fmt.Println("No keepalives for 10 seconds. Dying.")
os.Exit(1)
}
}
}()
}
</pre>
<p>
Even such "innocent" data races can lead to hard-to-debug problems caused by
non-atomicity of the memory accesses,
interference with compiler optimizations,
or reordering issues accessing processor memory .
</p>
<p>
A typical fix for this race is to use a channel or a mutex.
To preserve the lock-free behavior, one can also use the
<a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> package.
</p>
<pre>
type Watchdog struct{ last int64 }
func (w *Watchdog) KeepAlive() {
atomic.StoreInt64(&amp;w.last, time.Now().UnixNano())
}
func (w *Watchdog) Start() {
go func() {
for {
time.Sleep(time.Second)
if atomic.LoadInt64(&amp;w.last) < time.Now().Add(-10*time.Second).UnixNano() {
fmt.Println("No keepalives for 10 seconds. Dying.")
os.Exit(1)
}
}
}()
}
</pre>
<h2 id="Supported_Systems">Supported Systems</h2>
<p>
The race detector runs on <code>darwin/amd64</code>, <code>linux/amd64</code>, and <code>windows/amd64</code>.
</p>
<h2 id="Runtime_Overheads">Runtime Overhead</h2>
<p>
The cost of race detection varies by program, but for a typical program, memory
usage may increase by 5-10x and execution time by 2-20x.
</p>
doc/articles/slices_usage_and_internals.html deleted 100644 → 0
View file @ 83da0fd9
This diff is collapsed.
doc/cmd.html
View file @ 5dd74175
......@@ -27,9 +27,9 @@ the go <code>tool</code> subcommand.
</p>
<p>
Finally, two of the commands, <code>fmt</code> and <code>doc</code>, are also
installed as regular binaries called <code>gofmt</code> and <code>godoc</code>
because they are so often referenced.
Finally the <code>fmt</code> and <code>godoc</code> commands are installed
as regular binaries called <code>gofmt</code> and <code>godoc</code> because
they are so often referenced.
</p>
<p>
......@@ -62,17 +62,17 @@ details.
</tr>
<tr>
<td><a href="/cmd/fix/">fix</a></td>
<td><a href="http://godoc.org/code.google.com/p/go.tools/cmd/cover/">cover</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Fix finds Go programs that use old features of the language and libraries
and rewrites them to use newer ones.</td>
<td>Cover is a program for creating and analyzing the coverage profiles
generated by <code>"go test -coverprofile"</code>.
</tr>
<tr>
<td><a href="/cmd/go/">doc</a></td>
<td><a href="/cmd/fix/">fix</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Doc extracts and generates documentation for Go packages, it is also available as
an independent <a href="/cmd/godoc/">godoc</a> command with more general options.</td>
<td>Fix finds Go programs that use old features of the language and libraries
and rewrites them to use newer ones.</td>
</tr>
<tr>
......@@ -83,7 +83,13 @@ gofmt</a> command with more general options.</td>
</tr>
<tr>
<td><a href="/cmd/vet/">vet</a></td>
<td><a href="http://godoc.org/code.google.com/p/go.tools/cmd/godoc/">godoc</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Godoc extracts and generates documentation for Go packages.</td>
</tr>
<tr>
<td><a href="http://godoc.org/code.google.com/p/go.tools/cmd/vet/">vet</a></td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>Vet examines Go source code and reports suspicious constructs, such as Printf
calls whose arguments do not align with the format string.</td>
......
doc/contrib.html
View file @ 5dd74175
......@@ -26,14 +26,41 @@ We encourage all Go users to subscribe to
<a href="http://groups.google.com/group/golang-announce">golang-announce</a>.
</p>
<h2 id="resources">Developer Resources</h2>
<h3 id="source"><a href="https://code.google.com/p/go/source">Source Code</a></h3>
<p>Check out the Go source code.</p>
<h2 id="go1">Version history</h2>
<h3 id="release"><a href="/doc/devel/release.html">Release History</a></h3>
<p>A summary of the changes between Go releases.</p>
<h4 id="go1notes"><a href="/doc/go1">Go 1 Release Notes</a></h3>
<p>
A guide for updating your code to work with Go 1.
</p>
<h4 id="go1.1notes"><a href="/doc/go1.1">Go 1.1 Release Notes</a></h3>
<p>
A list of significant changes in Go 1.1, with instructions for updating your
code where necessary.
</p>
<h4 id="go1.2notes"><a href="/doc/go1.2">Go 1.2 Release Notes</a></h3>
<p>
A list of significant changes in Go 1.2, with instructions for updating your
code where necessary.
</p>
<h3 id="go1compat"><a href="/doc/go1compat">Go 1 and the Future of Go Programs</a></h3>
<p>
What Go 1 defines and the backwards-compatibility guarantees one can expect as
Go 1 matures.
</p>
<h2 id="resources">Developer Resources</h2>
<h3 id="source"><a href="https://code.google.com/p/go/source">Source Code</a></h3>
<p>Check out the Go source code.</p>
<h3 id="golang-dev"><a href="http://groups.google.com/group/golang-dev">Developer Mailing List</a></h3>
<p>The <a href="http://groups.google.com/group/golang-dev">golang-dev</a>
mailing list is for discussing and reviewing code for the Go project.</p>
......@@ -80,29 +107,3 @@ open issues that interest you. Those labeled
<a href="http://code.google.com/p/go/issues/list?q=status=HelpWanted">HelpWanted</a>
are particularly in need of outside help.
</p>
<h2 id="community">The Go Community</h2>
<h3 id="mailinglist"><a href="http://groups.google.com/group/golang-nuts">Go Nuts Mailing List</a></h3>
<p>The <a href="http://groups.google.com/group/golang-nuts">golang-nuts</a>
mailing list is for general Go discussion.</p>
<h3 id="projects"><a href="http://code.google.com/p/go-wiki/wiki/Projects">Go Wiki Projects Page</a></h3>
<p>A list of external Go projects including programs and libraries.</p>
<h3 id="irc"><a href="irc:irc.freenode.net/go-nuts">Go IRC Channel</a></h3>
<p><b>#go-nuts</b> on <b>irc.freenode.net</b> is the official Go IRC channel.</p>
<h3 id="pluscom"><a href="https://plus.google.com/communities/114112804251407510571">The Go+ community</a></h3>
<p>The Google+ community for Go enthusiasts.</p>
<h3 id="plus"><a href="https://plus.google.com/101406623878176903605/posts">The Go Programming Language at Google+</a></h3>
<p>The Go project's Google+ page.</p>
<h3 id="twitter"><a href="http://twitter.com/go_nuts">@go_nuts at Twitter</a></h3>
<p>The Go project's official Twitter account.</p>
<h3 id="blog"><a href="http://blog.golang.org/">The Go Blog</a></h3>
<p>The official blog of the Go project, featuring news and in-depth articles by
the Go team and guests.</p>
doc/docs.html
View file @ 5dd74175
This diff is collapsed.
doc/go1.html
View file @ 5dd74175
<!--{
"Title": "Go 1 Release Notes",
"Path": "/doc/go1",
"Template": true
}-->
......
doc/go1compat.html
View file @ 5dd74175
<!--{
"Title": "Go 1 and the Future of Go Programs"
"Title": "Go 1 and the Future of Go Programs",
"Path": "/doc/go1compat"
}-->
<h2 id="introduction">Introduction</h2>
......
doc/go_faq.html
View file @ 5dd74175
<!--{
"Title": "FAQ",
"Title": "Frequently Asked Questions (FAQ)",
"Path": "/doc/faq"
}-->
......
doc/go_mem.html
View file @ 5dd74175
<!--{
"Title": "The Go Memory Model",
"Subtitle": "Version of March 6, 2012",
"Path": "/ref/mem"
"Path": "/doc/mem"
}-->
<style>
......
doc/go_spec.html
View file @ 5dd74175
<!--{
"Title": "The Go Programming Language Specification",
"Subtitle": "Version of Sep 12, 2013",
"Path": "/ref/spec"
"Path": "/doc/spec"
}-->
<!--
......
doc/help.html
View file @ 5dd74175
......@@ -11,10 +11,13 @@ Need help with Go? Try these resources.
<div id="manual-nav"></div>
<h3 id="go_faq"><a href="/doc/go_faq.html">Frequently Asked Questions (FAQ)</a></h3>
<h3 id="faq"><a href="/doc/faq">Frequently Asked Questions (FAQ)</a></h3>
<p>Answers to common questions about Go.</p>
<h3 id="wiki"><a href="http://code.google.com/p/go-wiki/wiki">Go Language Community Wiki</a></h3>
<h3 id="playground"><a href="/play">The Go Playground</a></h3>
<p>A place to write, run, and share Go code.</p>
<h3 id="wiki"><a href="/wiki">The Go Wiki</a></h3>
<p>A wiki maintained by the Go community.</p>
<h3 id="mailinglist"><a href="http://groups.google.com/group/golang-nuts">Go Nuts Mailing List</a></h3>
......@@ -39,6 +42,9 @@ Go IRC channel.</p>
<p>Tweeting your about problem with the <code>#golang</code> hashtag usually
generates some helpful responses.</p>
<h3 id="blog"><a href="http://blog.golang.org/">The Go Blog</a></h3>
<p>The official blog of the Go project, featuring news and in-depth articles by
the Go team and guests.</p>
<h3 id="go_user_groups"><a href="/wiki/GoUserGroups">Go User Groups</a></h3>
<p>
Each month in places around the world, groups of Go programmers ("gophers")
meet to talk about Go. Find a chapter near you.
</p>
doc/reference.html deleted 100644 → 0
View file @ 83da0fd9
<!--{
"Title": "References",
"Path": "/ref/"
}-->
<img class="gopher" src="/doc/gopher/ref.png" />
<p>Good bedtime reading.</p>
<div>
<h3 id="pkg"><a href="/pkg/">Package Documentation</a></h3>
<p>
The documentation for the Go standard library.
</p>
<h3 id="cmd"><a href="/doc/cmd">Command Documentation</a></h3>
<p>
The documentation for the Go tools.
</p>
<h3 id="spec"><a href="/ref/spec">Language Specification</a></h3>
<p>
The official Go Language specification.
</p>
<h3 id="appengine"><a href="https://developers.google.com/appengine/docs/go/">App Engine Go Runtime Documentation</a></h3>
<p>
The documentation for
<a href="https://developers.google.com/appengine/">Google App Engine</a>'s Go runtime.
</p>
<h3 id="go_mem"><a href="/ref/mem">The Go Memory Model</a></h3>
<p>
A document that specifies the conditions under which reads of a variable in
one goroutine can be guaranteed to observe values produced by writes to the
same variable in a different goroutine.
</p>
<h4 id="subrepos">Sub-repositories</h4>
<p>
These packages are part of the Go Project but outside the main Go tree.
They are developed under looser <a href="/doc/go1compat.html">compatibility
requirements</a> than the Go core.
Install them with "<code><a href="/cmd/go/#hdr-Download_and_install_packages_and_dependencies">go get</a></code>".
</p>
<ul>
<li><a href="http://code.google.com/p/go/source/browse?repo=codereview"><code>code.google.com/p/go.codereview</code></a> [<a href="http://godoc.org/code.google.com/p/go.codereview">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=crypto"><code>code.google.com/p/go.crypto</code></a> [<a href="http://godoc.org/code.google.com/p/go.crypto">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=image"><code>code.google.com/p/go.image</code></a> [<a href="http://godoc.org/code.google.com/p/go.image">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=net"><code>code.google.com/p/go.net</code></a> [<a href="http://godoc.org/code.google.com/p/go.net">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=text"><code>code.google.com/p/go.text</code></a> [<a href="http://godoc.org/code.google.com/p/go.text">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=exp"><code>code.google.com/p/go.exp</code></a> [<a href="http://godoc.org/code.google.com/p/go.exp">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=talks"><code>code.google.com/p/go.talks</code></a> [<a href="http://godoc.org/code.google.com/p/go.talks">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=blog"><code>code.google.com/p/go.blog</code></a> [<a href="http://godoc.org/code.google.com/p/go.blog">docs</a>]
</ul>
<p>
See the <a href="/doc/">documents page</a> for more documentation.
</p>
</div>
doc/root.html
View file @ 5dd74175
......@@ -5,7 +5,7 @@
<div class="left">
<div id="learn">
<img class="icon share" src="/doc/share.png" alt="View full screen" title="View full screen">
<a class="popout share">Pop-out</a>
<div class="rootHeading">Try Go</div>
<div class="input">
<textarea spellcheck="false" class="code">// You can edit this code!
......@@ -69,7 +69,7 @@ Linux, Mac OS X, Windows, and more.
<div id="video">
<div class="rootHeading">Featured video</div>
<iframe width="415" height="241" src="http://www.youtube.com/embed/ytEkHepK08c" frameborder="0" allowfullscreen></iframe>
<iframe width="415" height="241" src="//www.youtube.com/embed/ytEkHepK08c" frameborder="0" allowfullscreen></iframe>
</div>
</div>
......@@ -135,6 +135,16 @@ window.initFuncs.push(function() {
$('<script/>').attr('text', 'text/javascript')
.attr('src', 'http://blog.golang.org/.json?jsonp=feedLoaded')
.appendTo('body');
// Set the video at random.
var videos = [
{h: 241, s: "//www.youtube.com/embed/ytEkHepK08c"}, // Tour of Go
{h: 241, s: "//www.youtube.com/embed/f6kdp27TYZs"}, // Concurrency Patterns
{h: 233, s: "//player.vimeo.com/video/53221560"}, // Grows with grace
{h: 233, s: "//player.vimeo.com/video/69237265"} // Simple environment
];
var v = videos[Math.floor(Math.random()*videos.length)];
$('#video iframe').attr('height', v.h).attr('src', v.s);
});
</script>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment