mirror of
https://github.com/golang/go
synced 2024-09-04 23:44:16 +00:00
![Gabriel Aszalos](/assets/img/avatar_default.png)
Change-Id: I321890237f703b945711e59c15233ccf59c4f190 Reviewed-on: https://go-review.googlesource.com/c/156477 Run-TryBot: Gabriel Aszalos <gabriel.aszalos@gmail.com> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
3669 lines
114 KiB
HTML
3669 lines
114 KiB
HTML
<!--{
|
||
"Title": "Effective Go",
|
||
"Template": true
|
||
}-->
|
||
|
||
<h2 id="introduction">Introduction</h2>
|
||
|
||
<p>
|
||
Go is a new language. Although it borrows ideas from
|
||
existing languages,
|
||
it has unusual properties that make effective Go programs
|
||
different in character from programs written in its relatives.
|
||
A straightforward translation of a C++ or Java program into Go
|
||
is unlikely to produce a satisfactory result—Java programs
|
||
are written in Java, not Go.
|
||
On the other hand, thinking about the problem from a Go
|
||
perspective could produce a successful but quite different
|
||
program.
|
||
In other words,
|
||
to write Go well, it's important to understand its properties
|
||
and idioms.
|
||
It's also important to know the established conventions for
|
||
programming in Go, such as naming, formatting, program
|
||
construction, and so on, so that programs you write
|
||
will be easy for other Go programmers to understand.
|
||
</p>
|
||
|
||
<p>
|
||
This document gives tips for writing clear, idiomatic Go code.
|
||
It augments the <a href="/ref/spec">language specification</a>,
|
||
the <a href="//tour.golang.org/">Tour of Go</a>,
|
||
and <a href="/doc/code.html">How to Write Go Code</a>,
|
||
all of which you
|
||
should read first.
|
||
</p>
|
||
|
||
<h3 id="examples">Examples</h3>
|
||
|
||
<p>
|
||
The <a href="/src/">Go package sources</a>
|
||
are intended to serve not
|
||
only as the core library but also as examples of how to
|
||
use the language.
|
||
Moreover, many of the packages contain working, self-contained
|
||
executable examples you can run directly from the
|
||
<a href="//golang.org">golang.org</a> web site, such as
|
||
<a href="//golang.org/pkg/strings/#example_Map">this one</a> (if
|
||
necessary, click on the word "Example" to open it up).
|
||
If you have a question about how to approach a problem or how something
|
||
might be implemented, the documentation, code and examples in the
|
||
library can provide answers, ideas and
|
||
background.
|
||
</p>
|
||
|
||
|
||
<h2 id="formatting">Formatting</h2>
|
||
|
||
<p>
|
||
Formatting issues are the most contentious
|
||
but the least consequential.
|
||
People can adapt to different formatting styles
|
||
but it's better if they don't have to, and
|
||
less time is devoted to the topic
|
||
if everyone adheres to the same style.
|
||
The problem is how to approach this Utopia without a long
|
||
prescriptive style guide.
|
||
</p>
|
||
|
||
<p>
|
||
With Go we take an unusual
|
||
approach and let the machine
|
||
take care of most formatting issues.
|
||
The <code>gofmt</code> program
|
||
(also available as <code>go fmt</code>, which
|
||
operates at the package level rather than source file level)
|
||
reads a Go program
|
||
and emits the source in a standard style of indentation
|
||
and vertical alignment, retaining and if necessary
|
||
reformatting comments.
|
||
If you want to know how to handle some new layout
|
||
situation, run <code>gofmt</code>; if the answer doesn't
|
||
seem right, rearrange your program (or file a bug about <code>gofmt</code>),
|
||
don't work around it.
|
||
</p>
|
||
|
||
<p>
|
||
As an example, there's no need to spend time lining up
|
||
the comments on the fields of a structure.
|
||
<code>Gofmt</code> will do that for you. Given the
|
||
declaration
|
||
</p>
|
||
|
||
<pre>
|
||
type T struct {
|
||
name string // name of the object
|
||
value int // its value
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
<code>gofmt</code> will line up the columns:
|
||
</p>
|
||
|
||
<pre>
|
||
type T struct {
|
||
name string // name of the object
|
||
value int // its value
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
All Go code in the standard packages has been formatted with <code>gofmt</code>.
|
||
</p>
|
||
|
||
|
||
<p>
|
||
Some formatting details remain. Very briefly:
|
||
</p>
|
||
|
||
<dl>
|
||
<dt>Indentation</dt>
|
||
<dd>We use tabs for indentation and <code>gofmt</code> emits them by default.
|
||
Use spaces only if you must.
|
||
</dd>
|
||
<dt>Line length</dt>
|
||
<dd>
|
||
Go has no line length limit. Don't worry about overflowing a punched card.
|
||
If a line feels too long, wrap it and indent with an extra tab.
|
||
</dd>
|
||
<dt>Parentheses</dt>
|
||
<dd>
|
||
Go needs fewer parentheses than C and Java: control structures (<code>if</code>,
|
||
<code>for</code>, <code>switch</code>) do not have parentheses in
|
||
their syntax.
|
||
Also, the operator precedence hierarchy is shorter and clearer, so
|
||
<pre>
|
||
x<<8 + y<<16
|
||
</pre>
|
||
means what the spacing implies, unlike in the other languages.
|
||
</dd>
|
||
</dl>
|
||
|
||
<h2 id="commentary">Commentary</h2>
|
||
|
||
<p>
|
||
Go provides C-style <code>/* */</code> block comments
|
||
and C++-style <code>//</code> line comments.
|
||
Line comments are the norm;
|
||
block comments appear mostly as package comments, but
|
||
are useful within an expression or to disable large swaths of code.
|
||
</p>
|
||
|
||
<p>
|
||
The program—and web server—<code>godoc</code> processes
|
||
Go source files to extract documentation about the contents of the
|
||
package.
|
||
Comments that appear before top-level declarations, with no intervening newlines,
|
||
are extracted along with the declaration to serve as explanatory text for the item.
|
||
The nature and style of these comments determines the
|
||
quality of the documentation <code>godoc</code> produces.
|
||
</p>
|
||
|
||
<p>
|
||
Every package should have a <i>package comment</i>, a block
|
||
comment preceding the package clause.
|
||
For multi-file packages, the package comment only needs to be
|
||
present in one file, and any one will do.
|
||
The package comment should introduce the package and
|
||
provide information relevant to the package as a whole.
|
||
It will appear first on the <code>godoc</code> page and
|
||
should set up the detailed documentation that follows.
|
||
</p>
|
||
|
||
<pre>
|
||
/*
|
||
Package regexp implements a simple library for regular expressions.
|
||
|
||
The syntax of the regular expressions accepted is:
|
||
|
||
regexp:
|
||
concatenation { '|' concatenation }
|
||
concatenation:
|
||
{ closure }
|
||
closure:
|
||
term [ '*' | '+' | '?' ]
|
||
term:
|
||
'^'
|
||
'$'
|
||
'.'
|
||
character
|
||
'[' [ '^' ] character-ranges ']'
|
||
'(' regexp ')'
|
||
*/
|
||
package regexp
|
||
</pre>
|
||
|
||
<p>
|
||
If the package is simple, the package comment can be brief.
|
||
</p>
|
||
|
||
<pre>
|
||
// Package path implements utility routines for
|
||
// manipulating slash-separated filename paths.
|
||
</pre>
|
||
|
||
<p>
|
||
Comments do not need extra formatting such as banners of stars.
|
||
The generated output may not even be presented in a fixed-width font, so don't depend
|
||
on spacing for alignment—<code>godoc</code>, like <code>gofmt</code>,
|
||
takes care of that.
|
||
The comments are uninterpreted plain text, so HTML and other
|
||
annotations such as <code>_this_</code> will reproduce <i>verbatim</i> and should
|
||
not be used.
|
||
One adjustment <code>godoc</code> does do is to display indented
|
||
text in a fixed-width font, suitable for program snippets.
|
||
The package comment for the
|
||
<a href="/pkg/fmt/"><code>fmt</code> package</a> uses this to good effect.
|
||
</p>
|
||
|
||
<p>
|
||
Depending on the context, <code>godoc</code> might not even
|
||
reformat comments, so make sure they look good straight up:
|
||
use correct spelling, punctuation, and sentence structure,
|
||
fold long lines, and so on.
|
||
</p>
|
||
|
||
<p>
|
||
Inside a package, any comment immediately preceding a top-level declaration
|
||
serves as a <i>doc comment</i> for that declaration.
|
||
Every exported (capitalized) name in a program should
|
||
have a doc comment.
|
||
</p>
|
||
|
||
<p>
|
||
Doc comments work best as complete sentences, which allow
|
||
a wide variety of automated presentations.
|
||
The first sentence should be a one-sentence summary that
|
||
starts with the name being declared.
|
||
</p>
|
||
|
||
<pre>
|
||
// Compile parses a regular expression and returns, if successful,
|
||
// a Regexp that can be used to match against text.
|
||
func Compile(str string) (*Regexp, error) {
|
||
</pre>
|
||
|
||
<p>
|
||
If every doc comment begins with the name of the item it describes,
|
||
you can use the <a href="/cmd/go/#hdr-Show_documentation_for_package_or_symbol">doc</a>
|
||
subcommand of the <a href="/cmd/go/">go</a> tool
|
||
and run the output through <code>grep</code>.
|
||
Imagine you couldn't remember the name "Compile" but were looking for
|
||
the parsing function for regular expressions, so you ran
|
||
the command,
|
||
</p>
|
||
|
||
<pre>
|
||
$ go doc -all regexp | grep -i parse
|
||
</pre>
|
||
|
||
<p>
|
||
If all the doc comments in the package began, "This function...", <code>grep</code>
|
||
wouldn't help you remember the name. But because the package starts each
|
||
doc comment with the name, you'd see something like this,
|
||
which recalls the word you're looking for.
|
||
</p>
|
||
|
||
<pre>
|
||
$ go doc -all regexp | grep -i parse
|
||
Compile parses a regular expression and returns, if successful, a Regexp
|
||
MustCompile is like Compile but panics if the expression cannot be parsed.
|
||
parsed. It simplifies safe initialization of global variables holding
|
||
$
|
||
</pre>
|
||
|
||
<p>
|
||
Go's declaration syntax allows grouping of declarations.
|
||
A single doc comment can introduce a group of related constants or variables.
|
||
Since the whole declaration is presented, such a comment can often be perfunctory.
|
||
</p>
|
||
|
||
<pre>
|
||
// Error codes returned by failures to parse an expression.
|
||
var (
|
||
ErrInternal = errors.New("regexp: internal error")
|
||
ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
|
||
ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
|
||
...
|
||
)
|
||
</pre>
|
||
|
||
<p>
|
||
Grouping can also indicate relationships between items,
|
||
such as the fact that a set of variables is protected by a mutex.
|
||
</p>
|
||
|
||
<pre>
|
||
var (
|
||
countLock sync.Mutex
|
||
inputCount uint32
|
||
outputCount uint32
|
||
errorCount uint32
|
||
)
|
||
</pre>
|
||
|
||
<h2 id="names">Names</h2>
|
||
|
||
<p>
|
||
Names are as important in Go as in any other language.
|
||
They even have semantic effect:
|
||
the visibility of a name outside a package is determined by whether its
|
||
first character is upper case.
|
||
It's therefore worth spending a little time talking about naming conventions
|
||
in Go programs.
|
||
</p>
|
||
|
||
|
||
<h3 id="package-names">Package names</h3>
|
||
|
||
<p>
|
||
When a package is imported, the package name becomes an accessor for the
|
||
contents. After
|
||
</p>
|
||
|
||
<pre>
|
||
import "bytes"
|
||
</pre>
|
||
|
||
<p>
|
||
the importing package can talk about <code>bytes.Buffer</code>. It's
|
||
helpful if everyone using the package can use the same name to refer to
|
||
its contents, which implies that the package name should be good:
|
||
short, concise, evocative. By convention, packages are given
|
||
lower case, single-word names; there should be no need for underscores
|
||
or mixedCaps.
|
||
Err on the side of brevity, since everyone using your
|
||
package will be typing that name.
|
||
And don't worry about collisions <i>a priori</i>.
|
||
The package name is only the default name for imports; it need not be unique
|
||
across all source code, and in the rare case of a collision the
|
||
importing package can choose a different name to use locally.
|
||
In any case, confusion is rare because the file name in the import
|
||
determines just which package is being used.
|
||
</p>
|
||
|
||
<p>
|
||
Another convention is that the package name is the base name of
|
||
its source directory;
|
||
the package in <code>src/encoding/base64</code>
|
||
is imported as <code>"encoding/base64"</code> but has name <code>base64</code>,
|
||
not <code>encoding_base64</code> and not <code>encodingBase64</code>.
|
||
</p>
|
||
|
||
<p>
|
||
The importer of a package will use the name to refer to its contents,
|
||
so exported names in the package can use that fact
|
||
to avoid stutter.
|
||
(Don't use the <code>import .</code> notation, which can simplify
|
||
tests that must run outside the package they are testing, but should otherwise be avoided.)
|
||
For instance, the buffered reader type in the <code>bufio</code> package is called <code>Reader</code>,
|
||
not <code>BufReader</code>, because users see it as <code>bufio.Reader</code>,
|
||
which is a clear, concise name.
|
||
Moreover,
|
||
because imported entities are always addressed with their package name, <code>bufio.Reader</code>
|
||
does not conflict with <code>io.Reader</code>.
|
||
Similarly, the function to make new instances of <code>ring.Ring</code>—which
|
||
is the definition of a <em>constructor</em> in Go—would
|
||
normally be called <code>NewRing</code>, but since
|
||
<code>Ring</code> is the only type exported by the package, and since the
|
||
package is called <code>ring</code>, it's called just <code>New</code>,
|
||
which clients of the package see as <code>ring.New</code>.
|
||
Use the package structure to help you choose good names.
|
||
</p>
|
||
|
||
<p>
|
||
Another short example is <code>once.Do</code>;
|
||
<code>once.Do(setup)</code> reads well and would not be improved by
|
||
writing <code>once.DoOrWaitUntilDone(setup)</code>.
|
||
Long names don't automatically make things more readable.
|
||
A helpful doc comment can often be more valuable than an extra long name.
|
||
</p>
|
||
|
||
<h3 id="Getters">Getters</h3>
|
||
|
||
<p>
|
||
Go doesn't provide automatic support for getters and setters.
|
||
There's nothing wrong with providing getters and setters yourself,
|
||
and it's often appropriate to do so, but it's neither idiomatic nor necessary
|
||
to put <code>Get</code> into the getter's name. If you have a field called
|
||
<code>owner</code> (lower case, unexported), the getter method should be
|
||
called <code>Owner</code> (upper case, exported), not <code>GetOwner</code>.
|
||
The use of upper-case names for export provides the hook to discriminate
|
||
the field from the method.
|
||
A setter function, if needed, will likely be called <code>SetOwner</code>.
|
||
Both names read well in practice:
|
||
</p>
|
||
<pre>
|
||
owner := obj.Owner()
|
||
if owner != user {
|
||
obj.SetOwner(user)
|
||
}
|
||
</pre>
|
||
|
||
<h3 id="interface-names">Interface names</h3>
|
||
|
||
<p>
|
||
By convention, one-method interfaces are named by
|
||
the method name plus an -er suffix or similar modification
|
||
to construct an agent noun: <code>Reader</code>,
|
||
<code>Writer</code>, <code>Formatter</code>,
|
||
<code>CloseNotifier</code> etc.
|
||
</p>
|
||
|
||
<p>
|
||
There are a number of such names and it's productive to honor them and the function
|
||
names they capture.
|
||
<code>Read</code>, <code>Write</code>, <code>Close</code>, <code>Flush</code>,
|
||
<code>String</code> and so on have
|
||
canonical signatures and meanings. To avoid confusion,
|
||
don't give your method one of those names unless it
|
||
has the same signature and meaning.
|
||
Conversely, if your type implements a method with the
|
||
same meaning as a method on a well-known type,
|
||
give it the same name and signature;
|
||
call your string-converter method <code>String</code> not <code>ToString</code>.
|
||
</p>
|
||
|
||
<h3 id="mixed-caps">MixedCaps</h3>
|
||
|
||
<p>
|
||
Finally, the convention in Go is to use <code>MixedCaps</code>
|
||
or <code>mixedCaps</code> rather than underscores to write
|
||
multiword names.
|
||
</p>
|
||
|
||
<h2 id="semicolons">Semicolons</h2>
|
||
|
||
<p>
|
||
Like C, Go's formal grammar uses semicolons to terminate statements,
|
||
but unlike in C, those semicolons do not appear in the source.
|
||
Instead the lexer uses a simple rule to insert semicolons automatically
|
||
as it scans, so the input text is mostly free of them.
|
||
</p>
|
||
|
||
<p>
|
||
The rule is this. If the last token before a newline is an identifier
|
||
(which includes words like <code>int</code> and <code>float64</code>),
|
||
a basic literal such as a number or string constant, or one of the
|
||
tokens
|
||
</p>
|
||
<pre>
|
||
break continue fallthrough return ++ -- ) }
|
||
</pre>
|
||
<p>
|
||
the lexer always inserts a semicolon after the token.
|
||
This could be summarized as, “if the newline comes
|
||
after a token that could end a statement, insert a semicolon”.
|
||
</p>
|
||
|
||
<p>
|
||
A semicolon can also be omitted immediately before a closing brace,
|
||
so a statement such as
|
||
</p>
|
||
<pre>
|
||
go func() { for { dst <- <-src } }()
|
||
</pre>
|
||
<p>
|
||
needs no semicolons.
|
||
Idiomatic Go programs have semicolons only in places such as
|
||
<code>for</code> loop clauses, to separate the initializer, condition, and
|
||
continuation elements. They are also necessary to separate multiple
|
||
statements on a line, should you write code that way.
|
||
</p>
|
||
|
||
<p>
|
||
One consequence of the semicolon insertion rules
|
||
is that you cannot put the opening brace of a
|
||
control structure (<code>if</code>, <code>for</code>, <code>switch</code>,
|
||
or <code>select</code>) on the next line. If you do, a semicolon
|
||
will be inserted before the brace, which could cause unwanted
|
||
effects. Write them like this
|
||
</p>
|
||
|
||
<pre>
|
||
if i < f() {
|
||
g()
|
||
}
|
||
</pre>
|
||
<p>
|
||
not like this
|
||
</p>
|
||
<pre>
|
||
if i < f() // wrong!
|
||
{ // wrong!
|
||
g()
|
||
}
|
||
</pre>
|
||
|
||
|
||
<h2 id="control-structures">Control structures</h2>
|
||
|
||
<p>
|
||
The control structures of Go are related to those of C but differ
|
||
in important ways.
|
||
There is no <code>do</code> or <code>while</code> loop, only a
|
||
slightly generalized
|
||
<code>for</code>;
|
||
<code>switch</code> is more flexible;
|
||
<code>if</code> and <code>switch</code> accept an optional
|
||
initialization statement like that of <code>for</code>;
|
||
<code>break</code> and <code>continue</code> statements
|
||
take an optional label to identify what to break or continue;
|
||
and there are new control structures including a type switch and a
|
||
multiway communications multiplexer, <code>select</code>.
|
||
The syntax is also slightly different:
|
||
there are no parentheses
|
||
and the bodies must always be brace-delimited.
|
||
</p>
|
||
|
||
<h3 id="if">If</h3>
|
||
|
||
<p>
|
||
In Go a simple <code>if</code> looks like this:
|
||
</p>
|
||
<pre>
|
||
if x > 0 {
|
||
return y
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Mandatory braces encourage writing simple <code>if</code> statements
|
||
on multiple lines. It's good style to do so anyway,
|
||
especially when the body contains a control statement such as a
|
||
<code>return</code> or <code>break</code>.
|
||
</p>
|
||
|
||
<p>
|
||
Since <code>if</code> and <code>switch</code> accept an initialization
|
||
statement, it's common to see one used to set up a local variable.
|
||
</p>
|
||
|
||
<pre>
|
||
if err := file.Chmod(0664); err != nil {
|
||
log.Print(err)
|
||
return err
|
||
}
|
||
</pre>
|
||
|
||
<p id="else">
|
||
In the Go libraries, you'll find that
|
||
when an <code>if</code> statement doesn't flow into the next statement—that is,
|
||
the body ends in <code>break</code>, <code>continue</code>,
|
||
<code>goto</code>, or <code>return</code>—the unnecessary
|
||
<code>else</code> is omitted.
|
||
</p>
|
||
|
||
<pre>
|
||
f, err := os.Open(name)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
codeUsing(f)
|
||
</pre>
|
||
|
||
<p>
|
||
This is an example of a common situation where code must guard against a
|
||
sequence of error conditions. The code reads well if the
|
||
successful flow of control runs down the page, eliminating error cases
|
||
as they arise. Since error cases tend to end in <code>return</code>
|
||
statements, the resulting code needs no <code>else</code> statements.
|
||
</p>
|
||
|
||
<pre>
|
||
f, err := os.Open(name)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
d, err := f.Stat()
|
||
if err != nil {
|
||
f.Close()
|
||
return err
|
||
}
|
||
codeUsing(f, d)
|
||
</pre>
|
||
|
||
|
||
<h3 id="redeclaration">Redeclaration and reassignment</h3>
|
||
|
||
<p>
|
||
An aside: The last example in the previous section demonstrates a detail of how the
|
||
<code>:=</code> short declaration form works.
|
||
The declaration that calls <code>os.Open</code> reads,
|
||
</p>
|
||
|
||
<pre>
|
||
f, err := os.Open(name)
|
||
</pre>
|
||
|
||
<p>
|
||
This statement declares two variables, <code>f</code> and <code>err</code>.
|
||
A few lines later, the call to <code>f.Stat</code> reads,
|
||
</p>
|
||
|
||
<pre>
|
||
d, err := f.Stat()
|
||
</pre>
|
||
|
||
<p>
|
||
which looks as if it declares <code>d</code> and <code>err</code>.
|
||
Notice, though, that <code>err</code> appears in both statements.
|
||
This duplication is legal: <code>err</code> is declared by the first statement,
|
||
but only <em>re-assigned</em> in the second.
|
||
This means that the call to <code>f.Stat</code> uses the existing
|
||
<code>err</code> variable declared above, and just gives it a new value.
|
||
</p>
|
||
|
||
<p>
|
||
In a <code>:=</code> declaration a variable <code>v</code> may appear even
|
||
if it has already been declared, provided:
|
||
</p>
|
||
|
||
<ul>
|
||
<li>this declaration is in the same scope as the existing declaration of <code>v</code>
|
||
(if <code>v</code> is already declared in an outer scope, the declaration will create a new variable §),</li>
|
||
<li>the corresponding value in the initialization is assignable to <code>v</code>, and</li>
|
||
<li>there is at least one other variable in the declaration that is being declared anew.</li>
|
||
</ul>
|
||
|
||
<p>
|
||
This unusual property is pure pragmatism,
|
||
making it easy to use a single <code>err</code> value, for example,
|
||
in a long <code>if-else</code> chain.
|
||
You'll see it used often.
|
||
</p>
|
||
|
||
<p>
|
||
§ It's worth noting here that in Go the scope of function parameters and return values
|
||
is the same as the function body, even though they appear lexically outside the braces
|
||
that enclose the body.
|
||
</p>
|
||
|
||
<h3 id="for">For</h3>
|
||
|
||
<p>
|
||
The Go <code>for</code> loop is similar to—but not the same as—C's.
|
||
It unifies <code>for</code>
|
||
and <code>while</code> and there is no <code>do-while</code>.
|
||
There are three forms, only one of which has semicolons.
|
||
</p>
|
||
<pre>
|
||
// Like a C for
|
||
for init; condition; post { }
|
||
|
||
// Like a C while
|
||
for condition { }
|
||
|
||
// Like a C for(;;)
|
||
for { }
|
||
</pre>
|
||
|
||
<p>
|
||
Short declarations make it easy to declare the index variable right in the loop.
|
||
</p>
|
||
<pre>
|
||
sum := 0
|
||
for i := 0; i < 10; i++ {
|
||
sum += i
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
If you're looping over an array, slice, string, or map,
|
||
or reading from a channel, a <code>range</code> clause can
|
||
manage the loop.
|
||
</p>
|
||
<pre>
|
||
for key, value := range oldMap {
|
||
newMap[key] = value
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
If you only need the first item in the range (the key or index), drop the second:
|
||
</p>
|
||
<pre>
|
||
for key := range m {
|
||
if key.expired() {
|
||
delete(m, key)
|
||
}
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
If you only need the second item in the range (the value), use the <em>blank identifier</em>, an underscore, to discard the first:
|
||
</p>
|
||
<pre>
|
||
sum := 0
|
||
for _, value := range array {
|
||
sum += value
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
The blank identifier has many uses, as described in <a href="#blank">a later section</a>.
|
||
</p>
|
||
|
||
<p>
|
||
For strings, the <code>range</code> does more work for you, breaking out individual
|
||
Unicode code points by parsing the UTF-8.
|
||
Erroneous encodings consume one byte and produce the
|
||
replacement rune U+FFFD.
|
||
(The name (with associated builtin type) <code>rune</code> is Go terminology for a
|
||
single Unicode code point.
|
||
See <a href="/ref/spec#Rune_literals">the language specification</a>
|
||
for details.)
|
||
The loop
|
||
</p>
|
||
<pre>
|
||
for pos, char := range "日本\x80語" { // \x80 is an illegal UTF-8 encoding
|
||
fmt.Printf("character %#U starts at byte position %d\n", char, pos)
|
||
}
|
||
</pre>
|
||
<p>
|
||
prints
|
||
</p>
|
||
<pre>
|
||
character U+65E5 '日' starts at byte position 0
|
||
character U+672C '本' starts at byte position 3
|
||
character U+FFFD '<27>' starts at byte position 6
|
||
character U+8A9E '語' starts at byte position 7
|
||
</pre>
|
||
|
||
<p>
|
||
Finally, Go has no comma operator and <code>++</code> and <code>--</code>
|
||
are statements not expressions.
|
||
Thus if you want to run multiple variables in a <code>for</code>
|
||
you should use parallel assignment (although that precludes <code>++</code> and <code>--</code>).
|
||
</p>
|
||
<pre>
|
||
// Reverse a
|
||
for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 {
|
||
a[i], a[j] = a[j], a[i]
|
||
}
|
||
</pre>
|
||
|
||
<h3 id="switch">Switch</h3>
|
||
|
||
<p>
|
||
Go's <code>switch</code> is more general than C's.
|
||
The expressions need not be constants or even integers,
|
||
the cases are evaluated top to bottom until a match is found,
|
||
and if the <code>switch</code> has no expression it switches on
|
||
<code>true</code>.
|
||
It's therefore possible—and idiomatic—to write an
|
||
<code>if</code>-<code>else</code>-<code>if</code>-<code>else</code>
|
||
chain as a <code>switch</code>.
|
||
</p>
|
||
|
||
<pre>
|
||
func unhex(c byte) byte {
|
||
switch {
|
||
case '0' <= c && c <= '9':
|
||
return c - '0'
|
||
case 'a' <= c && c <= 'f':
|
||
return c - 'a' + 10
|
||
case 'A' <= c && c <= 'F':
|
||
return c - 'A' + 10
|
||
}
|
||
return 0
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
There is no automatic fall through, but cases can be presented
|
||
in comma-separated lists.
|
||
</p>
|
||
<pre>
|
||
func shouldEscape(c byte) bool {
|
||
switch c {
|
||
case ' ', '?', '&', '=', '#', '+', '%':
|
||
return true
|
||
}
|
||
return false
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Although they are not nearly as common in Go as some other C-like
|
||
languages, <code>break</code> statements can be used to terminate
|
||
a <code>switch</code> early.
|
||
Sometimes, though, it's necessary to break out of a surrounding loop,
|
||
not the switch, and in Go that can be accomplished by putting a label
|
||
on the loop and "breaking" to that label.
|
||
This example shows both uses.
|
||
</p>
|
||
|
||
<pre>
|
||
Loop:
|
||
for n := 0; n < len(src); n += size {
|
||
switch {
|
||
case src[n] < sizeOne:
|
||
if validateOnly {
|
||
break
|
||
}
|
||
size = 1
|
||
update(src[n])
|
||
|
||
case src[n] < sizeTwo:
|
||
if n+1 >= len(src) {
|
||
err = errShortInput
|
||
break Loop
|
||
}
|
||
if validateOnly {
|
||
break
|
||
}
|
||
size = 2
|
||
update(src[n] + src[n+1]<<shift)
|
||
}
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Of course, the <code>continue</code> statement also accepts an optional label
|
||
but it applies only to loops.
|
||
</p>
|
||
|
||
<p>
|
||
To close this section, here's a comparison routine for byte slices that uses two
|
||
<code>switch</code> statements:
|
||
</p>
|
||
<pre>
|
||
// Compare returns an integer comparing the two byte slices,
|
||
// lexicographically.
|
||
// The result will be 0 if a == b, -1 if a < b, and +1 if a > b
|
||
func Compare(a, b []byte) int {
|
||
for i := 0; i < len(a) && i < len(b); i++ {
|
||
switch {
|
||
case a[i] > b[i]:
|
||
return 1
|
||
case a[i] < b[i]:
|
||
return -1
|
||
}
|
||
}
|
||
switch {
|
||
case len(a) > len(b):
|
||
return 1
|
||
case len(a) < len(b):
|
||
return -1
|
||
}
|
||
return 0
|
||
}
|
||
</pre>
|
||
|
||
<h3 id="type_switch">Type switch</h3>
|
||
|
||
<p>
|
||
A switch can also be used to discover the dynamic type of an interface
|
||
variable. Such a <em>type switch</em> uses the syntax of a type
|
||
assertion with the keyword <code>type</code> inside the parentheses.
|
||
If the switch declares a variable in the expression, the variable will
|
||
have the corresponding type in each clause.
|
||
It's also idiomatic to reuse the name in such cases, in effect declaring
|
||
a new variable with the same name but a different type in each case.
|
||
</p>
|
||
<pre>
|
||
var t interface{}
|
||
t = functionOfSomeType()
|
||
switch t := t.(type) {
|
||
default:
|
||
fmt.Printf("unexpected type %T\n", t) // %T prints whatever type t has
|
||
case bool:
|
||
fmt.Printf("boolean %t\n", t) // t has type bool
|
||
case int:
|
||
fmt.Printf("integer %d\n", t) // t has type int
|
||
case *bool:
|
||
fmt.Printf("pointer to boolean %t\n", *t) // t has type *bool
|
||
case *int:
|
||
fmt.Printf("pointer to integer %d\n", *t) // t has type *int
|
||
}
|
||
</pre>
|
||
|
||
<h2 id="functions">Functions</h2>
|
||
|
||
<h3 id="multiple-returns">Multiple return values</h3>
|
||
|
||
<p>
|
||
One of Go's unusual features is that functions and methods
|
||
can return multiple values. This form can be used to
|
||
improve on a couple of clumsy idioms in C programs: in-band
|
||
error returns such as <code>-1</code> for <code>EOF</code>
|
||
and modifying an argument passed by address.
|
||
</p>
|
||
|
||
<p>
|
||
In C, a write error is signaled by a negative count with the
|
||
error code secreted away in a volatile location.
|
||
In Go, <code>Write</code>
|
||
can return a count <i>and</i> an error: “Yes, you wrote some
|
||
bytes but not all of them because you filled the device”.
|
||
The signature of the <code>Write</code> method on files from
|
||
package <code>os</code> is:
|
||
</p>
|
||
|
||
<pre>
|
||
func (file *File) Write(b []byte) (n int, err error)
|
||
</pre>
|
||
|
||
<p>
|
||
and as the documentation says, it returns the number of bytes
|
||
written and a non-nil <code>error</code> when <code>n</code>
|
||
<code>!=</code> <code>len(b)</code>.
|
||
This is a common style; see the section on error handling for more examples.
|
||
</p>
|
||
|
||
<p>
|
||
A similar approach obviates the need to pass a pointer to a return
|
||
value to simulate a reference parameter.
|
||
Here's a simple-minded function to
|
||
grab a number from a position in a byte slice, returning the number
|
||
and the next position.
|
||
</p>
|
||
|
||
<pre>
|
||
func nextInt(b []byte, i int) (int, int) {
|
||
for ; i < len(b) && !isDigit(b[i]); i++ {
|
||
}
|
||
x := 0
|
||
for ; i < len(b) && isDigit(b[i]); i++ {
|
||
x = x*10 + int(b[i]) - '0'
|
||
}
|
||
return x, i
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
You could use it to scan the numbers in an input slice <code>b</code> like this:
|
||
</p>
|
||
|
||
<pre>
|
||
for i := 0; i < len(b); {
|
||
x, i = nextInt(b, i)
|
||
fmt.Println(x)
|
||
}
|
||
</pre>
|
||
|
||
<h3 id="named-results">Named result parameters</h3>
|
||
|
||
<p>
|
||
The return or result "parameters" of a Go function can be given names and
|
||
used as regular variables, just like the incoming parameters.
|
||
When named, they are initialized to the zero values for their types when
|
||
the function begins; if the function executes a <code>return</code> statement
|
||
with no arguments, the current values of the result parameters are
|
||
used as the returned values.
|
||
</p>
|
||
|
||
<p>
|
||
The names are not mandatory but they can make code shorter and clearer:
|
||
they're documentation.
|
||
If we name the results of <code>nextInt</code> it becomes
|
||
obvious which returned <code>int</code>
|
||
is which.
|
||
</p>
|
||
|
||
<pre>
|
||
func nextInt(b []byte, pos int) (value, nextPos int) {
|
||
</pre>
|
||
|
||
<p>
|
||
Because named results are initialized and tied to an unadorned return, they can simplify
|
||
as well as clarify. Here's a version
|
||
of <code>io.ReadFull</code> that uses them well:
|
||
</p>
|
||
|
||
<pre>
|
||
func ReadFull(r Reader, buf []byte) (n int, err error) {
|
||
for len(buf) > 0 && err == nil {
|
||
var nr int
|
||
nr, err = r.Read(buf)
|
||
n += nr
|
||
buf = buf[nr:]
|
||
}
|
||
return
|
||
}
|
||
</pre>
|
||
|
||
<h3 id="defer">Defer</h3>
|
||
|
||
<p>
|
||
Go's <code>defer</code> statement schedules a function call (the
|
||
<i>deferred</i> function) to be run immediately before the function
|
||
executing the <code>defer</code> returns. It's an unusual but
|
||
effective way to deal with situations such as resources that must be
|
||
released regardless of which path a function takes to return. The
|
||
canonical examples are unlocking a mutex or closing a file.
|
||
</p>
|
||
|
||
<pre>
|
||
// Contents returns the file's contents as a string.
|
||
func Contents(filename string) (string, error) {
|
||
f, err := os.Open(filename)
|
||
if err != nil {
|
||
return "", err
|
||
}
|
||
defer f.Close() // f.Close will run when we're finished.
|
||
|
||
var result []byte
|
||
buf := make([]byte, 100)
|
||
for {
|
||
n, err := f.Read(buf[0:])
|
||
result = append(result, buf[0:n]...) // append is discussed later.
|
||
if err != nil {
|
||
if err == io.EOF {
|
||
break
|
||
}
|
||
return "", err // f will be closed if we return here.
|
||
}
|
||
}
|
||
return string(result), nil // f will be closed if we return here.
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Deferring a call to a function such as <code>Close</code> has two advantages. First, it
|
||
guarantees that you will never forget to close the file, a mistake
|
||
that's easy to make if you later edit the function to add a new return
|
||
path. Second, it means that the close sits near the open,
|
||
which is much clearer than placing it at the end of the function.
|
||
</p>
|
||
|
||
<p>
|
||
The arguments to the deferred function (which include the receiver if
|
||
the function is a method) are evaluated when the <i>defer</i>
|
||
executes, not when the <i>call</i> executes. Besides avoiding worries
|
||
about variables changing values as the function executes, this means
|
||
that a single deferred call site can defer multiple function
|
||
executions. Here's a silly example.
|
||
</p>
|
||
|
||
<pre>
|
||
for i := 0; i < 5; i++ {
|
||
defer fmt.Printf("%d ", i)
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Deferred functions are executed in LIFO order, so this code will cause
|
||
<code>4 3 2 1 0</code> to be printed when the function returns. A
|
||
more plausible example is a simple way to trace function execution
|
||
through the program. We could write a couple of simple tracing
|
||
routines like this:
|
||
</p>
|
||
|
||
<pre>
|
||
func trace(s string) { fmt.Println("entering:", s) }
|
||
func untrace(s string) { fmt.Println("leaving:", s) }
|
||
|
||
// Use them like this:
|
||
func a() {
|
||
trace("a")
|
||
defer untrace("a")
|
||
// do something....
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
We can do better by exploiting the fact that arguments to deferred
|
||
functions are evaluated when the <code>defer</code> executes. The
|
||
tracing routine can set up the argument to the untracing routine.
|
||
This example:
|
||
</p>
|
||
|
||
<pre>
|
||
func trace(s string) string {
|
||
fmt.Println("entering:", s)
|
||
return s
|
||
}
|
||
|
||
func un(s string) {
|
||
fmt.Println("leaving:", s)
|
||
}
|
||
|
||
func a() {
|
||
defer un(trace("a"))
|
||
fmt.Println("in a")
|
||
}
|
||
|
||
func b() {
|
||
defer un(trace("b"))
|
||
fmt.Println("in b")
|
||
a()
|
||
}
|
||
|
||
func main() {
|
||
b()
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
prints
|
||
</p>
|
||
|
||
<pre>
|
||
entering: b
|
||
in b
|
||
entering: a
|
||
in a
|
||
leaving: a
|
||
leaving: b
|
||
</pre>
|
||
|
||
<p>
|
||
For programmers accustomed to block-level resource management from
|
||
other languages, <code>defer</code> may seem peculiar, but its most
|
||
interesting and powerful applications come precisely from the fact
|
||
that it's not block-based but function-based. In the section on
|
||
<code>panic</code> and <code>recover</code> we'll see another
|
||
example of its possibilities.
|
||
</p>
|
||
|
||
<h2 id="data">Data</h2>
|
||
|
||
<h3 id="allocation_new">Allocation with <code>new</code></h3>
|
||
|
||
<p>
|
||
Go has two allocation primitives, the built-in functions
|
||
<code>new</code> and <code>make</code>.
|
||
They do different things and apply to different types, which can be confusing,
|
||
but the rules are simple.
|
||
Let's talk about <code>new</code> first.
|
||
It's a built-in function that allocates memory, but unlike its namesakes
|
||
in some other languages it does not <em>initialize</em> the memory,
|
||
it only <em>zeros</em> it.
|
||
That is,
|
||
<code>new(T)</code> allocates zeroed storage for a new item of type
|
||
<code>T</code> and returns its address, a value of type <code>*T</code>.
|
||
In Go terminology, it returns a pointer to a newly allocated zero value of type
|
||
<code>T</code>.
|
||
</p>
|
||
|
||
<p>
|
||
Since the memory returned by <code>new</code> is zeroed, it's helpful to arrange
|
||
when designing your data structures that the
|
||
zero value of each type can be used without further initialization. This means a user of
|
||
the data structure can create one with <code>new</code> and get right to
|
||
work.
|
||
For example, the documentation for <code>bytes.Buffer</code> states that
|
||
"the zero value for <code>Buffer</code> is an empty buffer ready to use."
|
||
Similarly, <code>sync.Mutex</code> does not
|
||
have an explicit constructor or <code>Init</code> method.
|
||
Instead, the zero value for a <code>sync.Mutex</code>
|
||
is defined to be an unlocked mutex.
|
||
</p>
|
||
|
||
<p>
|
||
The zero-value-is-useful property works transitively. Consider this type declaration.
|
||
</p>
|
||
|
||
<pre>
|
||
type SyncedBuffer struct {
|
||
lock sync.Mutex
|
||
buffer bytes.Buffer
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Values of type <code>SyncedBuffer</code> are also ready to use immediately upon allocation
|
||
or just declaration. In the next snippet, both <code>p</code> and <code>v</code> will work
|
||
correctly without further arrangement.
|
||
</p>
|
||
|
||
<pre>
|
||
p := new(SyncedBuffer) // type *SyncedBuffer
|
||
var v SyncedBuffer // type SyncedBuffer
|
||
</pre>
|
||
|
||
<h3 id="composite_literals">Constructors and composite literals</h3>
|
||
|
||
<p>
|
||
Sometimes the zero value isn't good enough and an initializing
|
||
constructor is necessary, as in this example derived from
|
||
package <code>os</code>.
|
||
</p>
|
||
|
||
<pre>
|
||
func NewFile(fd int, name string) *File {
|
||
if fd < 0 {
|
||
return nil
|
||
}
|
||
f := new(File)
|
||
f.fd = fd
|
||
f.name = name
|
||
f.dirinfo = nil
|
||
f.nepipe = 0
|
||
return f
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
There's a lot of boiler plate in there. We can simplify it
|
||
using a <i>composite literal</i>, which is
|
||
an expression that creates a
|
||
new instance each time it is evaluated.
|
||
</p>
|
||
|
||
<pre>
|
||
func NewFile(fd int, name string) *File {
|
||
if fd < 0 {
|
||
return nil
|
||
}
|
||
f := File{fd, name, nil, 0}
|
||
return &f
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Note that, unlike in C, it's perfectly OK to return the address of a local variable;
|
||
the storage associated with the variable survives after the function
|
||
returns.
|
||
In fact, taking the address of a composite literal
|
||
allocates a fresh instance each time it is evaluated,
|
||
so we can combine these last two lines.
|
||
</p>
|
||
|
||
<pre>
|
||
return &File{fd, name, nil, 0}
|
||
</pre>
|
||
|
||
<p>
|
||
The fields of a composite literal are laid out in order and must all be present.
|
||
However, by labeling the elements explicitly as <i>field</i><code>:</code><i>value</i>
|
||
pairs, the initializers can appear in any
|
||
order, with the missing ones left as their respective zero values. Thus we could say
|
||
</p>
|
||
|
||
<pre>
|
||
return &File{fd: fd, name: name}
|
||
</pre>
|
||
|
||
<p>
|
||
As a limiting case, if a composite literal contains no fields at all, it creates
|
||
a zero value for the type. The expressions <code>new(File)</code> and <code>&File{}</code> are equivalent.
|
||
</p>
|
||
|
||
<p>
|
||
Composite literals can also be created for arrays, slices, and maps,
|
||
with the field labels being indices or map keys as appropriate.
|
||
In these examples, the initializations work regardless of the values of <code>Enone</code>,
|
||
<code>Eio</code>, and <code>Einval</code>, as long as they are distinct.
|
||
</p>
|
||
|
||
<pre>
|
||
a := [...]string {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
|
||
s := []string {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
|
||
m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
|
||
</pre>
|
||
|
||
<h3 id="allocation_make">Allocation with <code>make</code></h3>
|
||
|
||
<p>
|
||
Back to allocation.
|
||
The built-in function <code>make(T, </code><i>args</i><code>)</code> serves
|
||
a purpose different from <code>new(T)</code>.
|
||
It creates slices, maps, and channels only, and it returns an <em>initialized</em>
|
||
(not <em>zeroed</em>)
|
||
value of type <code>T</code> (not <code>*T</code>).
|
||
The reason for the distinction
|
||
is that these three types represent, under the covers, references to data structures that
|
||
must be initialized before use.
|
||
A slice, for example, is a three-item descriptor
|
||
containing a pointer to the data (inside an array), the length, and the
|
||
capacity, and until those items are initialized, the slice is <code>nil</code>.
|
||
For slices, maps, and channels,
|
||
<code>make</code> initializes the internal data structure and prepares
|
||
the value for use.
|
||
For instance,
|
||
</p>
|
||
|
||
<pre>
|
||
make([]int, 10, 100)
|
||
</pre>
|
||
|
||
<p>
|
||
allocates an array of 100 ints and then creates a slice
|
||
structure with length 10 and a capacity of 100 pointing at the first
|
||
10 elements of the array.
|
||
(When making a slice, the capacity can be omitted; see the section on slices
|
||
for more information.)
|
||
In contrast, <code>new([]int)</code> returns a pointer to a newly allocated, zeroed slice
|
||
structure, that is, a pointer to a <code>nil</code> slice value.
|
||
</p>
|
||
|
||
<p>
|
||
These examples illustrate the difference between <code>new</code> and
|
||
<code>make</code>.
|
||
</p>
|
||
|
||
<pre>
|
||
var p *[]int = new([]int) // allocates slice structure; *p == nil; rarely useful
|
||
var v []int = make([]int, 100) // the slice v now refers to a new array of 100 ints
|
||
|
||
// Unnecessarily complex:
|
||
var p *[]int = new([]int)
|
||
*p = make([]int, 100, 100)
|
||
|
||
// Idiomatic:
|
||
v := make([]int, 100)
|
||
</pre>
|
||
|
||
<p>
|
||
Remember that <code>make</code> applies only to maps, slices and channels
|
||
and does not return a pointer.
|
||
To obtain an explicit pointer allocate with <code>new</code> or take the address
|
||
of a variable explicitly.
|
||
</p>
|
||
|
||
<h3 id="arrays">Arrays</h3>
|
||
|
||
<p>
|
||
Arrays are useful when planning the detailed layout of memory and sometimes
|
||
can help avoid allocation, but primarily
|
||
they are a building block for slices, the subject of the next section.
|
||
To lay the foundation for that topic, here are a few words about arrays.
|
||
</p>
|
||
|
||
<p>
|
||
There are major differences between the ways arrays work in Go and C.
|
||
In Go,
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Arrays are values. Assigning one array to another copies all the elements.
|
||
</li>
|
||
<li>
|
||
In particular, if you pass an array to a function, it
|
||
will receive a <i>copy</i> of the array, not a pointer to it.
|
||
<li>
|
||
The size of an array is part of its type. The types <code>[10]int</code>
|
||
and <code>[20]int</code> are distinct.
|
||
</li>
|
||
</ul>
|
||
|
||
<p>
|
||
The value property can be useful but also expensive; if you want C-like behavior and efficiency,
|
||
you can pass a pointer to the array.
|
||
</p>
|
||
|
||
<pre>
|
||
func Sum(a *[3]float64) (sum float64) {
|
||
for _, v := range *a {
|
||
sum += v
|
||
}
|
||
return
|
||
}
|
||
|
||
array := [...]float64{7.0, 8.5, 9.1}
|
||
x := Sum(&array) // Note the explicit address-of operator
|
||
</pre>
|
||
|
||
<p>
|
||
But even this style isn't idiomatic Go.
|
||
Use slices instead.
|
||
</p>
|
||
|
||
<h3 id="slices">Slices</h3>
|
||
|
||
<p>
|
||
Slices wrap arrays to give a more general, powerful, and convenient
|
||
interface to sequences of data. Except for items with explicit
|
||
dimension such as transformation matrices, most array programming in
|
||
Go is done with slices rather than simple arrays.
|
||
</p>
|
||
<p>
|
||
Slices hold references to an underlying array, and if you assign one
|
||
slice to another, both refer to the same array.
|
||
If a function takes a slice argument, changes it makes to
|
||
the elements of the slice will be visible to the caller, analogous to
|
||
passing a pointer to the underlying array. A <code>Read</code>
|
||
function can therefore accept a slice argument rather than a pointer
|
||
and a count; the length within the slice sets an upper
|
||
limit of how much data to read. Here is the signature of the
|
||
<code>Read</code> method of the <code>File</code> type in package
|
||
<code>os</code>:
|
||
</p>
|
||
<pre>
|
||
func (f *File) Read(buf []byte) (n int, err error)
|
||
</pre>
|
||
<p>
|
||
The method returns the number of bytes read and an error value, if
|
||
any.
|
||
To read into the first 32 bytes of a larger buffer
|
||
<code>buf</code>, <i>slice</i> (here used as a verb) the buffer.
|
||
</p>
|
||
<pre>
|
||
n, err := f.Read(buf[0:32])
|
||
</pre>
|
||
<p>
|
||
Such slicing is common and efficient. In fact, leaving efficiency aside for
|
||
the moment, the following snippet would also read the first 32 bytes of the buffer.
|
||
</p>
|
||
<pre>
|
||
var n int
|
||
var err error
|
||
for i := 0; i < 32; i++ {
|
||
nbytes, e := f.Read(buf[i:i+1]) // Read one byte.
|
||
n += nbytes
|
||
if nbytes == 0 || e != nil {
|
||
err = e
|
||
break
|
||
}
|
||
}
|
||
</pre>
|
||
<p>
|
||
The length of a slice may be changed as long as it still fits within
|
||
the limits of the underlying array; just assign it to a slice of
|
||
itself. The <i>capacity</i> of a slice, accessible by the built-in
|
||
function <code>cap</code>, reports the maximum length the slice may
|
||
assume. Here is a function to append data to a slice. If the data
|
||
exceeds the capacity, the slice is reallocated. The
|
||
resulting slice is returned. The function uses the fact that
|
||
<code>len</code> and <code>cap</code> are legal when applied to the
|
||
<code>nil</code> slice, and return 0.
|
||
</p>
|
||
<pre>
|
||
func Append(slice, data []byte) []byte {
|
||
l := len(slice)
|
||
if l + len(data) > cap(slice) { // reallocate
|
||
// Allocate double what's needed, for future growth.
|
||
newSlice := make([]byte, (l+len(data))*2)
|
||
// The copy function is predeclared and works for any slice type.
|
||
copy(newSlice, slice)
|
||
slice = newSlice
|
||
}
|
||
slice = slice[0:l+len(data)]
|
||
copy(slice[l:], data)
|
||
return slice
|
||
}
|
||
</pre>
|
||
<p>
|
||
We must return the slice afterwards because, although <code>Append</code>
|
||
can modify the elements of <code>slice</code>, the slice itself (the run-time data
|
||
structure holding the pointer, length, and capacity) is passed by value.
|
||
</p>
|
||
|
||
<p>
|
||
The idea of appending to a slice is so useful it's captured by the
|
||
<code>append</code> built-in function. To understand that function's
|
||
design, though, we need a little more information, so we'll return
|
||
to it later.
|
||
</p>
|
||
|
||
<h3 id="two_dimensional_slices">Two-dimensional slices</h3>
|
||
|
||
<p>
|
||
Go's arrays and slices are one-dimensional.
|
||
To create the equivalent of a 2D array or slice, it is necessary to define an array-of-arrays
|
||
or slice-of-slices, like this:
|
||
</p>
|
||
|
||
<pre>
|
||
type Transform [3][3]float64 // A 3x3 array, really an array of arrays.
|
||
type LinesOfText [][]byte // A slice of byte slices.
|
||
</pre>
|
||
|
||
<p>
|
||
Because slices are variable-length, it is possible to have each inner
|
||
slice be a different length.
|
||
That can be a common situation, as in our <code>LinesOfText</code>
|
||
example: each line has an independent length.
|
||
</p>
|
||
|
||
<pre>
|
||
text := LinesOfText{
|
||
[]byte("Now is the time"),
|
||
[]byte("for all good gophers"),
|
||
[]byte("to bring some fun to the party."),
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Sometimes it's necessary to allocate a 2D slice, a situation that can arise when
|
||
processing scan lines of pixels, for instance.
|
||
There are two ways to achieve this.
|
||
One is to allocate each slice independently; the other
|
||
is to allocate a single array and point the individual slices into it.
|
||
Which to use depends on your application.
|
||
If the slices might grow or shrink, they should be allocated independently
|
||
to avoid overwriting the next line; if not, it can be more efficient to construct
|
||
the object with a single allocation.
|
||
For reference, here are sketches of the two methods.
|
||
First, a line at a time:
|
||
</p>
|
||
|
||
<pre>
|
||
// Allocate the top-level slice.
|
||
picture := make([][]uint8, YSize) // One row per unit of y.
|
||
// Loop over the rows, allocating the slice for each row.
|
||
for i := range picture {
|
||
picture[i] = make([]uint8, XSize)
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
And now as one allocation, sliced into lines:
|
||
</p>
|
||
|
||
<pre>
|
||
// Allocate the top-level slice, the same as before.
|
||
picture := make([][]uint8, YSize) // One row per unit of y.
|
||
// Allocate one large slice to hold all the pixels.
|
||
pixels := make([]uint8, XSize*YSize) // Has type []uint8 even though picture is [][]uint8.
|
||
// Loop over the rows, slicing each row from the front of the remaining pixels slice.
|
||
for i := range picture {
|
||
picture[i], pixels = pixels[:XSize], pixels[XSize:]
|
||
}
|
||
</pre>
|
||
|
||
<h3 id="maps">Maps</h3>
|
||
|
||
<p>
|
||
Maps are a convenient and powerful built-in data structure that associate
|
||
values of one type (the <em>key</em>) with values of another type
|
||
(the <em>element</em> or <em>value</em>).
|
||
The key can be of any type for which the equality operator is defined,
|
||
such as integers,
|
||
floating point and complex numbers,
|
||
strings, pointers, interfaces (as long as the dynamic type
|
||
supports equality), structs and arrays.
|
||
Slices cannot be used as map keys,
|
||
because equality is not defined on them.
|
||
Like slices, maps hold references to an underlying data structure.
|
||
If you pass a map to a function
|
||
that changes the contents of the map, the changes will be visible
|
||
in the caller.
|
||
</p>
|
||
<p>
|
||
Maps can be constructed using the usual composite literal syntax
|
||
with colon-separated key-value pairs,
|
||
so it's easy to build them during initialization.
|
||
</p>
|
||
<pre>
|
||
var timeZone = map[string]int{
|
||
"UTC": 0*60*60,
|
||
"EST": -5*60*60,
|
||
"CST": -6*60*60,
|
||
"MST": -7*60*60,
|
||
"PST": -8*60*60,
|
||
}
|
||
</pre>
|
||
<p>
|
||
Assigning and fetching map values looks syntactically just like
|
||
doing the same for arrays and slices except that the index doesn't
|
||
need to be an integer.
|
||
</p>
|
||
<pre>
|
||
offset := timeZone["EST"]
|
||
</pre>
|
||
<p>
|
||
An attempt to fetch a map value with a key that
|
||
is not present in the map will return the zero value for the type
|
||
of the entries
|
||
in the map. For instance, if the map contains integers, looking
|
||
up a non-existent key will return <code>0</code>.
|
||
A set can be implemented as a map with value type <code>bool</code>.
|
||
Set the map entry to <code>true</code> to put the value in the set, and then
|
||
test it by simple indexing.
|
||
</p>
|
||
<pre>
|
||
attended := map[string]bool{
|
||
"Ann": true,
|
||
"Joe": true,
|
||
...
|
||
}
|
||
|
||
if attended[person] { // will be false if person is not in the map
|
||
fmt.Println(person, "was at the meeting")
|
||
}
|
||
</pre>
|
||
<p>
|
||
Sometimes you need to distinguish a missing entry from
|
||
a zero value. Is there an entry for <code>"UTC"</code>
|
||
or is that 0 because it's not in the map at all?
|
||
You can discriminate with a form of multiple assignment.
|
||
</p>
|
||
<pre>
|
||
var seconds int
|
||
var ok bool
|
||
seconds, ok = timeZone[tz]
|
||
</pre>
|
||
<p>
|
||
For obvious reasons this is called the “comma ok” idiom.
|
||
In this example, if <code>tz</code> is present, <code>seconds</code>
|
||
will be set appropriately and <code>ok</code> will be true; if not,
|
||
<code>seconds</code> will be set to zero and <code>ok</code> will
|
||
be false.
|
||
Here's a function that puts it together with a nice error report:
|
||
</p>
|
||
<pre>
|
||
func offset(tz string) int {
|
||
if seconds, ok := timeZone[tz]; ok {
|
||
return seconds
|
||
}
|
||
log.Println("unknown time zone:", tz)
|
||
return 0
|
||
}
|
||
</pre>
|
||
<p>
|
||
To test for presence in the map without worrying about the actual value,
|
||
you can use the <a href="#blank">blank identifier</a> (<code>_</code>)
|
||
in place of the usual variable for the value.
|
||
</p>
|
||
<pre>
|
||
_, present := timeZone[tz]
|
||
</pre>
|
||
<p>
|
||
To delete a map entry, use the <code>delete</code>
|
||
built-in function, whose arguments are the map and the key to be deleted.
|
||
It's safe to do this even if the key is already absent
|
||
from the map.
|
||
</p>
|
||
<pre>
|
||
delete(timeZone, "PDT") // Now on Standard Time
|
||
</pre>
|
||
|
||
<h3 id="printing">Printing</h3>
|
||
|
||
<p>
|
||
Formatted printing in Go uses a style similar to C's <code>printf</code>
|
||
family but is richer and more general. The functions live in the <code>fmt</code>
|
||
package and have capitalized names: <code>fmt.Printf</code>, <code>fmt.Fprintf</code>,
|
||
<code>fmt.Sprintf</code> and so on. The string functions (<code>Sprintf</code> etc.)
|
||
return a string rather than filling in a provided buffer.
|
||
</p>
|
||
<p>
|
||
You don't need to provide a format string. For each of <code>Printf</code>,
|
||
<code>Fprintf</code> and <code>Sprintf</code> there is another pair
|
||
of functions, for instance <code>Print</code> and <code>Println</code>.
|
||
These functions do not take a format string but instead generate a default
|
||
format for each argument. The <code>Println</code> versions also insert a blank
|
||
between arguments and append a newline to the output while
|
||
the <code>Print</code> versions add blanks only if the operand on neither side is a string.
|
||
In this example each line produces the same output.
|
||
</p>
|
||
<pre>
|
||
fmt.Printf("Hello %d\n", 23)
|
||
fmt.Fprint(os.Stdout, "Hello ", 23, "\n")
|
||
fmt.Println("Hello", 23)
|
||
fmt.Println(fmt.Sprint("Hello ", 23))
|
||
</pre>
|
||
<p>
|
||
The formatted print functions <code>fmt.Fprint</code>
|
||
and friends take as a first argument any object
|
||
that implements the <code>io.Writer</code> interface; the variables <code>os.Stdout</code>
|
||
and <code>os.Stderr</code> are familiar instances.
|
||
</p>
|
||
<p>
|
||
Here things start to diverge from C. First, the numeric formats such as <code>%d</code>
|
||
do not take flags for signedness or size; instead, the printing routines use the
|
||
type of the argument to decide these properties.
|
||
</p>
|
||
<pre>
|
||
var x uint64 = 1<<64 - 1
|
||
fmt.Printf("%d %x; %d %x\n", x, x, int64(x), int64(x))
|
||
</pre>
|
||
<p>
|
||
prints
|
||
</p>
|
||
<pre>
|
||
18446744073709551615 ffffffffffffffff; -1 -1
|
||
</pre>
|
||
<p>
|
||
If you just want the default conversion, such as decimal for integers, you can use
|
||
the catchall format <code>%v</code> (for “value”); the result is exactly
|
||
what <code>Print</code> and <code>Println</code> would produce.
|
||
Moreover, that format can print <em>any</em> value, even arrays, slices, structs, and
|
||
maps. Here is a print statement for the time zone map defined in the previous section.
|
||
</p>
|
||
<pre>
|
||
fmt.Printf("%v\n", timeZone) // or just fmt.Println(timeZone)
|
||
</pre>
|
||
<p>
|
||
which gives output
|
||
</p>
|
||
<pre>
|
||
map[CST:-21600 PST:-28800 EST:-18000 UTC:0 MST:-25200]
|
||
</pre>
|
||
<p>
|
||
For maps the keys may be output in any order, of course.
|
||
When printing a struct, the modified format <code>%+v</code> annotates the
|
||
fields of the structure with their names, and for any value the alternate
|
||
format <code>%#v</code> prints the value in full Go syntax.
|
||
</p>
|
||
<pre>
|
||
type T struct {
|
||
a int
|
||
b float64
|
||
c string
|
||
}
|
||
t := &T{ 7, -2.35, "abc\tdef" }
|
||
fmt.Printf("%v\n", t)
|
||
fmt.Printf("%+v\n", t)
|
||
fmt.Printf("%#v\n", t)
|
||
fmt.Printf("%#v\n", timeZone)
|
||
</pre>
|
||
<p>
|
||
prints
|
||
</p>
|
||
<pre>
|
||
&{7 -2.35 abc def}
|
||
&{a:7 b:-2.35 c:abc def}
|
||
&main.T{a:7, b:-2.35, c:"abc\tdef"}
|
||
map[string]int{"CST":-21600, "PST":-28800, "EST":-18000, "UTC":0, "MST":-25200}
|
||
</pre>
|
||
<p>
|
||
(Note the ampersands.)
|
||
That quoted string format is also available through <code>%q</code> when
|
||
applied to a value of type <code>string</code> or <code>[]byte</code>.
|
||
The alternate format <code>%#q</code> will use backquotes instead if possible.
|
||
(The <code>%q</code> format also applies to integers and runes, producing a
|
||
single-quoted rune constant.)
|
||
Also, <code>%x</code> works on strings, byte arrays and byte slices as well as
|
||
on integers, generating a long hexadecimal string, and with
|
||
a space in the format (<code>% x</code>) it puts spaces between the bytes.
|
||
</p>
|
||
<p>
|
||
Another handy format is <code>%T</code>, which prints the <em>type</em> of a value.
|
||
</p>
|
||
<pre>
|
||
fmt.Printf("%T\n", timeZone)
|
||
</pre>
|
||
<p>
|
||
prints
|
||
</p>
|
||
<pre>
|
||
map[string]int
|
||
</pre>
|
||
<p>
|
||
If you want to control the default format for a custom type, all that's required is to define
|
||
a method with the signature <code>String() string</code> on the type.
|
||
For our simple type <code>T</code>, that might look like this.
|
||
</p>
|
||
<pre>
|
||
func (t *T) String() string {
|
||
return fmt.Sprintf("%d/%g/%q", t.a, t.b, t.c)
|
||
}
|
||
fmt.Printf("%v\n", t)
|
||
</pre>
|
||
<p>
|
||
to print in the format
|
||
</p>
|
||
<pre>
|
||
7/-2.35/"abc\tdef"
|
||
</pre>
|
||
<p>
|
||
(If you need to print <em>values</em> of type <code>T</code> as well as pointers to <code>T</code>,
|
||
the receiver for <code>String</code> must be of value type; this example used a pointer because
|
||
that's more efficient and idiomatic for struct types.
|
||
See the section below on <a href="#pointers_vs_values">pointers vs. value receivers</a> for more information.)
|
||
</p>
|
||
|
||
<p>
|
||
Our <code>String</code> method is able to call <code>Sprintf</code> because the
|
||
print routines are fully reentrant and can be wrapped this way.
|
||
There is one important detail to understand about this approach,
|
||
however: don't construct a <code>String</code> method by calling
|
||
<code>Sprintf</code> in a way that will recur into your <code>String</code>
|
||
method indefinitely. This can happen if the <code>Sprintf</code>
|
||
call attempts to print the receiver directly as a string, which in
|
||
turn will invoke the method again. It's a common and easy mistake
|
||
to make, as this example shows.
|
||
</p>
|
||
|
||
<pre>
|
||
type MyString string
|
||
|
||
func (m MyString) String() string {
|
||
return fmt.Sprintf("MyString=%s", m) // Error: will recur forever.
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
It's also easy to fix: convert the argument to the basic string type, which does not have the
|
||
method.
|
||
</p>
|
||
|
||
<pre>
|
||
type MyString string
|
||
func (m MyString) String() string {
|
||
return fmt.Sprintf("MyString=%s", string(m)) // OK: note conversion.
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
In the <a href="#initialization">initialization section</a> we'll see another technique that avoids this recursion.
|
||
</p>
|
||
|
||
<p>
|
||
Another printing technique is to pass a print routine's arguments directly to another such routine.
|
||
The signature of <code>Printf</code> uses the type <code>...interface{}</code>
|
||
for its final argument to specify that an arbitrary number of parameters (of arbitrary type)
|
||
can appear after the format.
|
||
</p>
|
||
<pre>
|
||
func Printf(format string, v ...interface{}) (n int, err error) {
|
||
</pre>
|
||
<p>
|
||
Within the function <code>Printf</code>, <code>v</code> acts like a variable of type
|
||
<code>[]interface{}</code> but if it is passed to another variadic function, it acts like
|
||
a regular list of arguments.
|
||
Here is the implementation of the
|
||
function <code>log.Println</code> we used above. It passes its arguments directly to
|
||
<code>fmt.Sprintln</code> for the actual formatting.
|
||
</p>
|
||
<pre>
|
||
// Println prints to the standard logger in the manner of fmt.Println.
|
||
func Println(v ...interface{}) {
|
||
std.Output(2, fmt.Sprintln(v...)) // Output takes parameters (int, string)
|
||
}
|
||
</pre>
|
||
<p>
|
||
We write <code>...</code> after <code>v</code> in the nested call to <code>Sprintln</code> to tell the
|
||
compiler to treat <code>v</code> as a list of arguments; otherwise it would just pass
|
||
<code>v</code> as a single slice argument.
|
||
</p>
|
||
<p>
|
||
There's even more to printing than we've covered here. See the <code>godoc</code> documentation
|
||
for package <code>fmt</code> for the details.
|
||
</p>
|
||
<p>
|
||
By the way, a <code>...</code> parameter can be of a specific type, for instance <code>...int</code>
|
||
for a min function that chooses the least of a list of integers:
|
||
</p>
|
||
<pre>
|
||
func Min(a ...int) int {
|
||
min := int(^uint(0) >> 1) // largest int
|
||
for _, i := range a {
|
||
if i < min {
|
||
min = i
|
||
}
|
||
}
|
||
return min
|
||
}
|
||
</pre>
|
||
|
||
<h3 id="append">Append</h3>
|
||
<p>
|
||
Now we have the missing piece we needed to explain the design of
|
||
the <code>append</code> built-in function. The signature of <code>append</code>
|
||
is different from our custom <code>Append</code> function above.
|
||
Schematically, it's like this:
|
||
</p>
|
||
<pre>
|
||
func append(slice []<i>T</i>, elements ...<i>T</i>) []<i>T</i>
|
||
</pre>
|
||
<p>
|
||
where <i>T</i> is a placeholder for any given type. You can't
|
||
actually write a function in Go where the type <code>T</code>
|
||
is determined by the caller.
|
||
That's why <code>append</code> is built in: it needs support from the
|
||
compiler.
|
||
</p>
|
||
<p>
|
||
What <code>append</code> does is append the elements to the end of
|
||
the slice and return the result. The result needs to be returned
|
||
because, as with our hand-written <code>Append</code>, the underlying
|
||
array may change. This simple example
|
||
</p>
|
||
<pre>
|
||
x := []int{1,2,3}
|
||
x = append(x, 4, 5, 6)
|
||
fmt.Println(x)
|
||
</pre>
|
||
<p>
|
||
prints <code>[1 2 3 4 5 6]</code>. So <code>append</code> works a
|
||
little like <code>Printf</code>, collecting an arbitrary number of
|
||
arguments.
|
||
</p>
|
||
<p>
|
||
But what if we wanted to do what our <code>Append</code> does and
|
||
append a slice to a slice? Easy: use <code>...</code> at the call
|
||
site, just as we did in the call to <code>Output</code> above. This
|
||
snippet produces identical output to the one above.
|
||
</p>
|
||
<pre>
|
||
x := []int{1,2,3}
|
||
y := []int{4,5,6}
|
||
x = append(x, y...)
|
||
fmt.Println(x)
|
||
</pre>
|
||
<p>
|
||
Without that <code>...</code>, it wouldn't compile because the types
|
||
would be wrong; <code>y</code> is not of type <code>int</code>.
|
||
</p>
|
||
|
||
<h2 id="initialization">Initialization</h2>
|
||
|
||
<p>
|
||
Although it doesn't look superficially very different from
|
||
initialization in C or C++, initialization in Go is more powerful.
|
||
Complex structures can be built during initialization and the ordering
|
||
issues among initialized objects, even among different packages, are handled
|
||
correctly.
|
||
</p>
|
||
|
||
<h3 id="constants">Constants</h3>
|
||
|
||
<p>
|
||
Constants in Go are just that—constant.
|
||
They are created at compile time, even when defined as
|
||
locals in functions,
|
||
and can only be numbers, characters (runes), strings or booleans.
|
||
Because of the compile-time restriction, the expressions
|
||
that define them must be constant expressions,
|
||
evaluatable by the compiler. For instance,
|
||
<code>1<<3</code> is a constant expression, while
|
||
<code>math.Sin(math.Pi/4)</code> is not because
|
||
the function call to <code>math.Sin</code> needs
|
||
to happen at run time.
|
||
</p>
|
||
|
||
<p>
|
||
In Go, enumerated constants are created using the <code>iota</code>
|
||
enumerator. Since <code>iota</code> can be part of an expression and
|
||
expressions can be implicitly repeated, it is easy to build intricate
|
||
sets of values.
|
||
</p>
|
||
{{code "/doc/progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
|
||
<p>
|
||
The ability to attach a method such as <code>String</code> to any
|
||
user-defined type makes it possible for arbitrary values to format themselves
|
||
automatically for printing.
|
||
Although you'll see it most often applied to structs, this technique is also useful for
|
||
scalar types such as floating-point types like <code>ByteSize</code>.
|
||
</p>
|
||
{{code "/doc/progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
|
||
<p>
|
||
The expression <code>YB</code> prints as <code>1.00YB</code>,
|
||
while <code>ByteSize(1e13)</code> prints as <code>9.09TB</code>.
|
||
</p>
|
||
|
||
<p>
|
||
The use here of <code>Sprintf</code>
|
||
to implement <code>ByteSize</code>'s <code>String</code> method is safe
|
||
(avoids recurring indefinitely) not because of a conversion but
|
||
because it calls <code>Sprintf</code> with <code>%f</code>,
|
||
which is not a string format: <code>Sprintf</code> will only call
|
||
the <code>String</code> method when it wants a string, and <code>%f</code>
|
||
wants a floating-point value.
|
||
</p>
|
||
|
||
<h3 id="variables">Variables</h3>
|
||
|
||
<p>
|
||
Variables can be initialized just like constants but the
|
||
initializer can be a general expression computed at run time.
|
||
</p>
|
||
<pre>
|
||
var (
|
||
home = os.Getenv("HOME")
|
||
user = os.Getenv("USER")
|
||
gopath = os.Getenv("GOPATH")
|
||
)
|
||
</pre>
|
||
|
||
<h3 id="init">The init function</h3>
|
||
|
||
<p>
|
||
Finally, each source file can define its own niladic <code>init</code> function to
|
||
set up whatever state is required. (Actually each file can have multiple
|
||
<code>init</code> functions.)
|
||
And finally means finally: <code>init</code> is called after all the
|
||
variable declarations in the package have evaluated their initializers,
|
||
and those are evaluated only after all the imported packages have been
|
||
initialized.
|
||
</p>
|
||
<p>
|
||
Besides initializations that cannot be expressed as declarations,
|
||
a common use of <code>init</code> functions is to verify or repair
|
||
correctness of the program state before real execution begins.
|
||
</p>
|
||
|
||
<pre>
|
||
func init() {
|
||
if user == "" {
|
||
log.Fatal("$USER not set")
|
||
}
|
||
if home == "" {
|
||
home = "/home/" + user
|
||
}
|
||
if gopath == "" {
|
||
gopath = home + "/go"
|
||
}
|
||
// gopath may be overridden by --gopath flag on command line.
|
||
flag.StringVar(&gopath, "gopath", gopath, "override default GOPATH")
|
||
}
|
||
</pre>
|
||
|
||
<h2 id="methods">Methods</h2>
|
||
|
||
<h3 id="pointers_vs_values">Pointers vs. Values</h3>
|
||
<p>
|
||
As we saw with <code>ByteSize</code>,
|
||
methods can be defined for any named type (except a pointer or an interface);
|
||
the receiver does not have to be a struct.
|
||
</p>
|
||
<p>
|
||
In the discussion of slices above, we wrote an <code>Append</code>
|
||
function. We can define it as a method on slices instead. To do
|
||
this, we first declare a named type to which we can bind the method, and
|
||
then make the receiver for the method a value of that type.
|
||
</p>
|
||
<pre>
|
||
type ByteSlice []byte
|
||
|
||
func (slice ByteSlice) Append(data []byte) []byte {
|
||
// Body exactly the same as the Append function defined above.
|
||
}
|
||
</pre>
|
||
<p>
|
||
This still requires the method to return the updated slice. We can
|
||
eliminate that clumsiness by redefining the method to take a
|
||
<i>pointer</i> to a <code>ByteSlice</code> as its receiver, so the
|
||
method can overwrite the caller's slice.
|
||
</p>
|
||
<pre>
|
||
func (p *ByteSlice) Append(data []byte) {
|
||
slice := *p
|
||
// Body as above, without the return.
|
||
*p = slice
|
||
}
|
||
</pre>
|
||
<p>
|
||
In fact, we can do even better. If we modify our function so it looks
|
||
like a standard <code>Write</code> method, like this,
|
||
</p>
|
||
<pre>
|
||
func (p *ByteSlice) Write(data []byte) (n int, err error) {
|
||
slice := *p
|
||
// Again as above.
|
||
*p = slice
|
||
return len(data), nil
|
||
}
|
||
</pre>
|
||
<p>
|
||
then the type <code>*ByteSlice</code> satisfies the standard interface
|
||
<code>io.Writer</code>, which is handy. For instance, we can
|
||
print into one.
|
||
</p>
|
||
<pre>
|
||
var b ByteSlice
|
||
fmt.Fprintf(&b, "This hour has %d days\n", 7)
|
||
</pre>
|
||
<p>
|
||
We pass the address of a <code>ByteSlice</code>
|
||
because only <code>*ByteSlice</code> satisfies <code>io.Writer</code>.
|
||
The rule about pointers vs. values for receivers is that value methods
|
||
can be invoked on pointers and values, but pointer methods can only be
|
||
invoked on pointers.
|
||
</p>
|
||
|
||
<p>
|
||
This rule arises because pointer methods can modify the receiver; invoking
|
||
them on a value would cause the method to receive a copy of the value, so
|
||
any modifications would be discarded.
|
||
The language therefore disallows this mistake.
|
||
There is a handy exception, though. When the value is addressable, the
|
||
language takes care of the common case of invoking a pointer method on a
|
||
value by inserting the address operator automatically.
|
||
In our example, the variable <code>b</code> is addressable, so we can call
|
||
its <code>Write</code> method with just <code>b.Write</code>. The compiler
|
||
will rewrite that to <code>(&b).Write</code> for us.
|
||
</p>
|
||
|
||
<p>
|
||
By the way, the idea of using <code>Write</code> on a slice of bytes
|
||
is central to the implementation of <code>bytes.Buffer</code>.
|
||
</p>
|
||
|
||
<h2 id="interfaces_and_types">Interfaces and other types</h2>
|
||
|
||
<h3 id="interfaces">Interfaces</h3>
|
||
<p>
|
||
Interfaces in Go provide a way to specify the behavior of an
|
||
object: if something can do <em>this</em>, then it can be used
|
||
<em>here</em>. We've seen a couple of simple examples already;
|
||
custom printers can be implemented by a <code>String</code> method
|
||
while <code>Fprintf</code> can generate output to anything
|
||
with a <code>Write</code> method.
|
||
Interfaces with only one or two methods are common in Go code, and are
|
||
usually given a name derived from the method, such as <code>io.Writer</code>
|
||
for something that implements <code>Write</code>.
|
||
</p>
|
||
<p>
|
||
A type can implement multiple interfaces.
|
||
For instance, a collection can be sorted
|
||
by the routines in package <code>sort</code> if it implements
|
||
<code>sort.Interface</code>, which contains <code>Len()</code>,
|
||
<code>Less(i, j int) bool</code>, and <code>Swap(i, j int)</code>,
|
||
and it could also have a custom formatter.
|
||
In this contrived example <code>Sequence</code> satisfies both.
|
||
</p>
|
||
{{code "/doc/progs/eff_sequence.go" `/^type/` "$"}}
|
||
|
||
<h3 id="conversions">Conversions</h3>
|
||
|
||
<p>
|
||
The <code>String</code> method of <code>Sequence</code> is recreating the
|
||
work that <code>Sprint</code> already does for slices.
|
||
(It also has complexity O(N²), which is poor.) We can share the
|
||
effort (and also speed it up) if we convert the <code>Sequence</code> to a plain
|
||
<code>[]int</code> before calling <code>Sprint</code>.
|
||
</p>
|
||
<pre>
|
||
func (s Sequence) String() string {
|
||
s = s.Copy()
|
||
sort.Sort(s)
|
||
return fmt.Sprint([]int(s))
|
||
}
|
||
</pre>
|
||
<p>
|
||
This method is another example of the conversion technique for calling
|
||
<code>Sprintf</code> safely from a <code>String</code> method.
|
||
Because the two types (<code>Sequence</code> and <code>[]int</code>)
|
||
are the same if we ignore the type name, it's legal to convert between them.
|
||
The conversion doesn't create a new value, it just temporarily acts
|
||
as though the existing value has a new type.
|
||
(There are other legal conversions, such as from integer to floating point, that
|
||
do create a new value.)
|
||
</p>
|
||
<p>
|
||
It's an idiom in Go programs to convert the
|
||
type of an expression to access a different
|
||
set of methods. As an example, we could use the existing
|
||
type <code>sort.IntSlice</code> to reduce the entire example
|
||
to this:
|
||
</p>
|
||
<pre>
|
||
type Sequence []int
|
||
|
||
// Method for printing - sorts the elements before printing
|
||
func (s Sequence) String() string {
|
||
s = s.Copy()
|
||
sort.IntSlice(s).Sort()
|
||
return fmt.Sprint([]int(s))
|
||
}
|
||
</pre>
|
||
<p>
|
||
Now, instead of having <code>Sequence</code> implement multiple
|
||
interfaces (sorting and printing), we're using the ability of a data item to be
|
||
converted to multiple types (<code>Sequence</code>, <code>sort.IntSlice</code>
|
||
and <code>[]int</code>), each of which does some part of the job.
|
||
That's more unusual in practice but can be effective.
|
||
</p>
|
||
|
||
<h3 id="interface_conversions">Interface conversions and type assertions</h3>
|
||
|
||
<p>
|
||
<a href="#type_switch">Type switches</a> are a form of conversion: they take an interface and, for
|
||
each case in the switch, in a sense convert it to the type of that case.
|
||
Here's a simplified version of how the code under <code>fmt.Printf</code> turns a value into
|
||
a string using a type switch.
|
||
If it's already a string, we want the actual string value held by the interface, while if it has a
|
||
<code>String</code> method we want the result of calling the method.
|
||
</p>
|
||
|
||
<pre>
|
||
type Stringer interface {
|
||
String() string
|
||
}
|
||
|
||
var value interface{} // Value provided by caller.
|
||
switch str := value.(type) {
|
||
case string:
|
||
return str
|
||
case Stringer:
|
||
return str.String()
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
The first case finds a concrete value; the second converts the interface into another interface.
|
||
It's perfectly fine to mix types this way.
|
||
</p>
|
||
|
||
<p>
|
||
What if there's only one type we care about? If we know the value holds a <code>string</code>
|
||
and we just want to extract it?
|
||
A one-case type switch would do, but so would a <em>type assertion</em>.
|
||
A type assertion takes an interface value and extracts from it a value of the specified explicit type.
|
||
The syntax borrows from the clause opening a type switch, but with an explicit
|
||
type rather than the <code>type</code> keyword:
|
||
</p>
|
||
|
||
<pre>
|
||
value.(typeName)
|
||
</pre>
|
||
|
||
<p>
|
||
and the result is a new value with the static type <code>typeName</code>.
|
||
That type must either be the concrete type held by the interface, or a second interface
|
||
type that the value can be converted to.
|
||
To extract the string we know is in the value, we could write:
|
||
</p>
|
||
|
||
<pre>
|
||
str := value.(string)
|
||
</pre>
|
||
|
||
<p>
|
||
But if it turns out that the value does not contain a string, the program will crash with a run-time error.
|
||
To guard against that, use the "comma, ok" idiom to test, safely, whether the value is a string:
|
||
</p>
|
||
|
||
<pre>
|
||
str, ok := value.(string)
|
||
if ok {
|
||
fmt.Printf("string value is: %q\n", str)
|
||
} else {
|
||
fmt.Printf("value is not a string\n")
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
If the type assertion fails, <code>str</code> will still exist and be of type string, but it will have
|
||
the zero value, an empty string.
|
||
</p>
|
||
|
||
<p>
|
||
As an illustration of the capability, here's an <code>if</code>-<code>else</code>
|
||
statement that's equivalent to the type switch that opened this section.
|
||
</p>
|
||
|
||
<pre>
|
||
if str, ok := value.(string); ok {
|
||
return str
|
||
} else if str, ok := value.(Stringer); ok {
|
||
return str.String()
|
||
}
|
||
</pre>
|
||
|
||
<h3 id="generality">Generality</h3>
|
||
<p>
|
||
If a type exists only to implement an interface and will
|
||
never have exported methods beyond that interface, there is
|
||
no need to export the type itself.
|
||
Exporting just the interface makes it clear the value has no
|
||
interesting behavior beyond what is described in the
|
||
interface.
|
||
It also avoids the need to repeat the documentation
|
||
on every instance of a common method.
|
||
</p>
|
||
<p>
|
||
In such cases, the constructor should return an interface value
|
||
rather than the implementing type.
|
||
As an example, in the hash libraries
|
||
both <code>crc32.NewIEEE</code> and <code>adler32.New</code>
|
||
return the interface type <code>hash.Hash32</code>.
|
||
Substituting the CRC-32 algorithm for Adler-32 in a Go program
|
||
requires only changing the constructor call;
|
||
the rest of the code is unaffected by the change of algorithm.
|
||
</p>
|
||
<p>
|
||
A similar approach allows the streaming cipher algorithms
|
||
in the various <code>crypto</code> packages to be
|
||
separated from the block ciphers they chain together.
|
||
The <code>Block</code> interface
|
||
in the <code>crypto/cipher</code> package specifies the
|
||
behavior of a block cipher, which provides encryption
|
||
of a single block of data.
|
||
Then, by analogy with the <code>bufio</code> package,
|
||
cipher packages that implement this interface
|
||
can be used to construct streaming ciphers, represented
|
||
by the <code>Stream</code> interface, without
|
||
knowing the details of the block encryption.
|
||
</p>
|
||
<p>
|
||
The <code>crypto/cipher</code> interfaces look like this:
|
||
</p>
|
||
<pre>
|
||
type Block interface {
|
||
BlockSize() int
|
||
Encrypt(src, dst []byte)
|
||
Decrypt(src, dst []byte)
|
||
}
|
||
|
||
type Stream interface {
|
||
XORKeyStream(dst, src []byte)
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Here's the definition of the counter mode (CTR) stream,
|
||
which turns a block cipher into a streaming cipher; notice
|
||
that the block cipher's details are abstracted away:
|
||
</p>
|
||
|
||
<pre>
|
||
// NewCTR returns a Stream that encrypts/decrypts using the given Block in
|
||
// counter mode. The length of iv must be the same as the Block's block size.
|
||
func NewCTR(block Block, iv []byte) Stream
|
||
</pre>
|
||
<p>
|
||
<code>NewCTR</code> applies not
|
||
just to one specific encryption algorithm and data source but to any
|
||
implementation of the <code>Block</code> interface and any
|
||
<code>Stream</code>. Because they return
|
||
interface values, replacing CTR
|
||
encryption with other encryption modes is a localized change. The constructor
|
||
calls must be edited, but because the surrounding code must treat the result only
|
||
as a <code>Stream</code>, it won't notice the difference.
|
||
</p>
|
||
|
||
<h3 id="interface_methods">Interfaces and methods</h3>
|
||
<p>
|
||
Since almost anything can have methods attached, almost anything can
|
||
satisfy an interface. One illustrative example is in the <code>http</code>
|
||
package, which defines the <code>Handler</code> interface. Any object
|
||
that implements <code>Handler</code> can serve HTTP requests.
|
||
</p>
|
||
<pre>
|
||
type Handler interface {
|
||
ServeHTTP(ResponseWriter, *Request)
|
||
}
|
||
</pre>
|
||
<p>
|
||
<code>ResponseWriter</code> is itself an interface that provides access
|
||
to the methods needed to return the response to the client.
|
||
Those methods include the standard <code>Write</code> method, so an
|
||
<code>http.ResponseWriter</code> can be used wherever an <code>io.Writer</code>
|
||
can be used.
|
||
<code>Request</code> is a struct containing a parsed representation
|
||
of the request from the client.
|
||
</p>
|
||
<p>
|
||
For brevity, let's ignore POSTs and assume HTTP requests are always
|
||
GETs; that simplification does not affect the way the handlers are
|
||
set up. Here's a trivial but complete implementation of a handler to
|
||
count the number of times the
|
||
page is visited.
|
||
</p>
|
||
<pre>
|
||
// Simple counter server.
|
||
type Counter struct {
|
||
n int
|
||
}
|
||
|
||
func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
|
||
ctr.n++
|
||
fmt.Fprintf(w, "counter = %d\n", ctr.n)
|
||
}
|
||
</pre>
|
||
<p>
|
||
(Keeping with our theme, note how <code>Fprintf</code> can print to an
|
||
<code>http.ResponseWriter</code>.)
|
||
For reference, here's how to attach such a server to a node on the URL tree.
|
||
</p>
|
||
<pre>
|
||
import "net/http"
|
||
...
|
||
ctr := new(Counter)
|
||
http.Handle("/counter", ctr)
|
||
</pre>
|
||
<p>
|
||
But why make <code>Counter</code> a struct? An integer is all that's needed.
|
||
(The receiver needs to be a pointer so the increment is visible to the caller.)
|
||
</p>
|
||
<pre>
|
||
// Simpler counter server.
|
||
type Counter int
|
||
|
||
func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
|
||
*ctr++
|
||
fmt.Fprintf(w, "counter = %d\n", *ctr)
|
||
}
|
||
</pre>
|
||
<p>
|
||
What if your program has some internal state that needs to be notified that a page
|
||
has been visited? Tie a channel to the web page.
|
||
</p>
|
||
<pre>
|
||
// A channel that sends a notification on each visit.
|
||
// (Probably want the channel to be buffered.)
|
||
type Chan chan *http.Request
|
||
|
||
func (ch Chan) ServeHTTP(w http.ResponseWriter, req *http.Request) {
|
||
ch <- req
|
||
fmt.Fprint(w, "notification sent")
|
||
}
|
||
</pre>
|
||
<p>
|
||
Finally, let's say we wanted to present on <code>/args</code> the arguments
|
||
used when invoking the server binary.
|
||
It's easy to write a function to print the arguments.
|
||
</p>
|
||
<pre>
|
||
func ArgServer() {
|
||
fmt.Println(os.Args)
|
||
}
|
||
</pre>
|
||
<p>
|
||
How do we turn that into an HTTP server? We could make <code>ArgServer</code>
|
||
a method of some type whose value we ignore, but there's a cleaner way.
|
||
Since we can define a method for any type except pointers and interfaces,
|
||
we can write a method for a function.
|
||
The <code>http</code> package contains this code:
|
||
</p>
|
||
<pre>
|
||
// The HandlerFunc type is an adapter to allow the use of
|
||
// ordinary functions as HTTP handlers. If f is a function
|
||
// with the appropriate signature, HandlerFunc(f) is a
|
||
// Handler object that calls f.
|
||
type HandlerFunc func(ResponseWriter, *Request)
|
||
|
||
// ServeHTTP calls f(w, req).
|
||
func (f HandlerFunc) ServeHTTP(w ResponseWriter, req *Request) {
|
||
f(w, req)
|
||
}
|
||
</pre>
|
||
<p>
|
||
<code>HandlerFunc</code> is a type with a method, <code>ServeHTTP</code>,
|
||
so values of that type can serve HTTP requests. Look at the implementation
|
||
of the method: the receiver is a function, <code>f</code>, and the method
|
||
calls <code>f</code>. That may seem odd but it's not that different from, say,
|
||
the receiver being a channel and the method sending on the channel.
|
||
</p>
|
||
<p>
|
||
To make <code>ArgServer</code> into an HTTP server, we first modify it
|
||
to have the right signature.
|
||
</p>
|
||
<pre>
|
||
// Argument server.
|
||
func ArgServer(w http.ResponseWriter, req *http.Request) {
|
||
fmt.Fprintln(w, os.Args)
|
||
}
|
||
</pre>
|
||
<p>
|
||
<code>ArgServer</code> now has same signature as <code>HandlerFunc</code>,
|
||
so it can be converted to that type to access its methods,
|
||
just as we converted <code>Sequence</code> to <code>IntSlice</code>
|
||
to access <code>IntSlice.Sort</code>.
|
||
The code to set it up is concise:
|
||
</p>
|
||
<pre>
|
||
http.Handle("/args", http.HandlerFunc(ArgServer))
|
||
</pre>
|
||
<p>
|
||
When someone visits the page <code>/args</code>,
|
||
the handler installed at that page has value <code>ArgServer</code>
|
||
and type <code>HandlerFunc</code>.
|
||
The HTTP server will invoke the method <code>ServeHTTP</code>
|
||
of that type, with <code>ArgServer</code> as the receiver, which will in turn call
|
||
<code>ArgServer</code> (via the invocation <code>f(w, req)</code>
|
||
inside <code>HandlerFunc.ServeHTTP</code>).
|
||
The arguments will then be displayed.
|
||
</p>
|
||
<p>
|
||
In this section we have made an HTTP server from a struct, an integer,
|
||
a channel, and a function, all because interfaces are just sets of
|
||
methods, which can be defined for (almost) any type.
|
||
</p>
|
||
|
||
<h2 id="blank">The blank identifier</h2>
|
||
|
||
<p>
|
||
We've mentioned the blank identifier a couple of times now, in the context of
|
||
<a href="#for"><code>for</code> <code>range</code> loops</a>
|
||
and <a href="#maps">maps</a>.
|
||
The blank identifier can be assigned or declared with any value of any type, with the
|
||
value discarded harmlessly.
|
||
It's a bit like writing to the Unix <code>/dev/null</code> file:
|
||
it represents a write-only value
|
||
to be used as a place-holder
|
||
where a variable is needed but the actual value is irrelevant.
|
||
It has uses beyond those we've seen already.
|
||
</p>
|
||
|
||
<h3 id="blank_assign">The blank identifier in multiple assignment</h3>
|
||
|
||
<p>
|
||
The use of a blank identifier in a <code>for</code> <code>range</code> loop is a
|
||
special case of a general situation: multiple assignment.
|
||
</p>
|
||
|
||
<p>
|
||
If an assignment requires multiple values on the left side,
|
||
but one of the values will not be used by the program,
|
||
a blank identifier on the left-hand-side of
|
||
the assignment avoids the need
|
||
to create a dummy variable and makes it clear that the
|
||
value is to be discarded.
|
||
For instance, when calling a function that returns
|
||
a value and an error, but only the error is important,
|
||
use the blank identifier to discard the irrelevant value.
|
||
</p>
|
||
|
||
<pre>
|
||
if _, err := os.Stat(path); os.IsNotExist(err) {
|
||
fmt.Printf("%s does not exist\n", path)
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Occasionally you'll see code that discards the error value in order
|
||
to ignore the error; this is terrible practice. Always check error returns;
|
||
they're provided for a reason.
|
||
</p>
|
||
|
||
<pre>
|
||
// Bad! This code will crash if path does not exist.
|
||
fi, _ := os.Stat(path)
|
||
if fi.IsDir() {
|
||
fmt.Printf("%s is a directory\n", path)
|
||
}
|
||
</pre>
|
||
|
||
<h3 id="blank_unused">Unused imports and variables</h3>
|
||
|
||
<p>
|
||
It is an error to import a package or to declare a variable without using it.
|
||
Unused imports bloat the program and slow compilation,
|
||
while a variable that is initialized but not used is at least
|
||
a wasted computation and perhaps indicative of a
|
||
larger bug.
|
||
When a program is under active development, however,
|
||
unused imports and variables often arise and it can
|
||
be annoying to delete them just to have the compilation proceed,
|
||
only to have them be needed again later.
|
||
The blank identifier provides a workaround.
|
||
</p>
|
||
<p>
|
||
This half-written program has two unused imports
|
||
(<code>fmt</code> and <code>io</code>)
|
||
and an unused variable (<code>fd</code>),
|
||
so it will not compile, but it would be nice to see if the
|
||
code so far is correct.
|
||
</p>
|
||
{{code "/doc/progs/eff_unused1.go" `/package/` `$`}}
|
||
<p>
|
||
To silence complaints about the unused imports, use a
|
||
blank identifier to refer to a symbol from the imported package.
|
||
Similarly, assigning the unused variable <code>fd</code>
|
||
to the blank identifier will silence the unused variable error.
|
||
This version of the program does compile.
|
||
</p>
|
||
{{code "/doc/progs/eff_unused2.go" `/package/` `$`}}
|
||
|
||
<p>
|
||
By convention, the global declarations to silence import errors
|
||
should come right after the imports and be commented,
|
||
both to make them easy to find and as a reminder to clean things up later.
|
||
</p>
|
||
|
||
<h3 id="blank_import">Import for side effect</h3>
|
||
|
||
<p>
|
||
An unused import like <code>fmt</code> or <code>io</code> in the
|
||
previous example should eventually be used or removed:
|
||
blank assignments identify code as a work in progress.
|
||
But sometimes it is useful to import a package only for its
|
||
side effects, without any explicit use.
|
||
For example, during its <code>init</code> function,
|
||
the <code><a href="/pkg/net/http/pprof/">net/http/pprof</a></code>
|
||
package registers HTTP handlers that provide
|
||
debugging information. It has an exported API, but
|
||
most clients need only the handler registration and
|
||
access the data through a web page.
|
||
To import the package only for its side effects, rename the package
|
||
to the blank identifier:
|
||
</p>
|
||
<pre>
|
||
import _ "net/http/pprof"
|
||
</pre>
|
||
<p>
|
||
This form of import makes clear that the package is being
|
||
imported for its side effects, because there is no other possible
|
||
use of the package: in this file, it doesn't have a name.
|
||
(If it did, and we didn't use that name, the compiler would reject the program.)
|
||
</p>
|
||
|
||
<h3 id="blank_implements">Interface checks</h3>
|
||
|
||
<p>
|
||
As we saw in the discussion of <a href="#interfaces_and_types">interfaces</a> above,
|
||
a type need not declare explicitly that it implements an interface.
|
||
Instead, a type implements the interface just by implementing the interface's methods.
|
||
In practice, most interface conversions are static and therefore checked at compile time.
|
||
For example, passing an <code>*os.File</code> to a function
|
||
expecting an <code>io.Reader</code> will not compile unless
|
||
<code>*os.File</code> implements the <code>io.Reader</code> interface.
|
||
</p>
|
||
|
||
<p>
|
||
Some interface checks do happen at run-time, though.
|
||
One instance is in the <code><a href="/pkg/encoding/json/">encoding/json</a></code>
|
||
package, which defines a <code><a href="/pkg/encoding/json/#Marshaler">Marshaler</a></code>
|
||
interface. When the JSON encoder receives a value that implements that interface,
|
||
the encoder invokes the value's marshaling method to convert it to JSON
|
||
instead of doing the standard conversion.
|
||
The encoder checks this property at run time with a <a href="#interface_conversions">type assertion</a> like:
|
||
</p>
|
||
|
||
<pre>
|
||
m, ok := val.(json.Marshaler)
|
||
</pre>
|
||
|
||
<p>
|
||
If it's necessary only to ask whether a type implements an interface, without
|
||
actually using the interface itself, perhaps as part of an error check, use the blank
|
||
identifier to ignore the type-asserted value:
|
||
</p>
|
||
|
||
<pre>
|
||
if _, ok := val.(json.Marshaler); ok {
|
||
fmt.Printf("value %v of type %T implements json.Marshaler\n", val, val)
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
One place this situation arises is when it is necessary to guarantee within the package implementing the type that
|
||
it actually satisfies the interface.
|
||
If a type—for example,
|
||
<code><a href="/pkg/encoding/json/#RawMessage">json.RawMessage</a></code>—needs
|
||
a custom JSON representation, it should implement
|
||
<code>json.Marshaler</code>, but there are no static conversions that would
|
||
cause the compiler to verify this automatically.
|
||
If the type inadvertently fails to satisfy the interface, the JSON encoder will still work,
|
||
but will not use the custom implementation.
|
||
To guarantee that the implementation is correct,
|
||
a global declaration using the blank identifier can be used in the package:
|
||
</p>
|
||
<pre>
|
||
var _ json.Marshaler = (*RawMessage)(nil)
|
||
</pre>
|
||
<p>
|
||
In this declaration, the assignment involving a conversion of a
|
||
<code>*RawMessage</code> to a <code>Marshaler</code>
|
||
requires that <code>*RawMessage</code> implements <code>Marshaler</code>,
|
||
and that property will be checked at compile time.
|
||
Should the <code>json.Marshaler</code> interface change, this package
|
||
will no longer compile and we will be on notice that it needs to be updated.
|
||
</p>
|
||
|
||
<p>
|
||
The appearance of the blank identifier in this construct indicates that
|
||
the declaration exists only for the type checking,
|
||
not to create a variable.
|
||
Don't do this for every type that satisfies an interface, though.
|
||
By convention, such declarations are only used
|
||
when there are no static conversions already present in the code,
|
||
which is a rare event.
|
||
</p>
|
||
|
||
|
||
<h2 id="embedding">Embedding</h2>
|
||
|
||
<p>
|
||
Go does not provide the typical, type-driven notion of subclassing,
|
||
but it does have the ability to “borrow” pieces of an
|
||
implementation by <em>embedding</em> types within a struct or
|
||
interface.
|
||
</p>
|
||
<p>
|
||
Interface embedding is very simple.
|
||
We've mentioned the <code>io.Reader</code> and <code>io.Writer</code> interfaces before;
|
||
here are their definitions.
|
||
</p>
|
||
<pre>
|
||
type Reader interface {
|
||
Read(p []byte) (n int, err error)
|
||
}
|
||
|
||
type Writer interface {
|
||
Write(p []byte) (n int, err error)
|
||
}
|
||
</pre>
|
||
<p>
|
||
The <code>io</code> package also exports several other interfaces
|
||
that specify objects that can implement several such methods.
|
||
For instance, there is <code>io.ReadWriter</code>, an interface
|
||
containing both <code>Read</code> and <code>Write</code>.
|
||
We could specify <code>io.ReadWriter</code> by listing the
|
||
two methods explicitly, but it's easier and more evocative
|
||
to embed the two interfaces to form the new one, like this:
|
||
</p>
|
||
<pre>
|
||
// ReadWriter is the interface that combines the Reader and Writer interfaces.
|
||
type ReadWriter interface {
|
||
Reader
|
||
Writer
|
||
}
|
||
</pre>
|
||
<p>
|
||
This says just what it looks like: A <code>ReadWriter</code> can do
|
||
what a <code>Reader</code> does <em>and</em> what a <code>Writer</code>
|
||
does; it is a union of the embedded interfaces (which must be disjoint
|
||
sets of methods).
|
||
Only interfaces can be embedded within interfaces.
|
||
</p>
|
||
<p>
|
||
The same basic idea applies to structs, but with more far-reaching
|
||
implications. The <code>bufio</code> package has two struct types,
|
||
<code>bufio.Reader</code> and <code>bufio.Writer</code>, each of
|
||
which of course implements the analogous interfaces from package
|
||
<code>io</code>.
|
||
And <code>bufio</code> also implements a buffered reader/writer,
|
||
which it does by combining a reader and a writer into one struct
|
||
using embedding: it lists the types within the struct
|
||
but does not give them field names.
|
||
</p>
|
||
<pre>
|
||
// ReadWriter stores pointers to a Reader and a Writer.
|
||
// It implements io.ReadWriter.
|
||
type ReadWriter struct {
|
||
*Reader // *bufio.Reader
|
||
*Writer // *bufio.Writer
|
||
}
|
||
</pre>
|
||
<p>
|
||
The embedded elements are pointers to structs and of course
|
||
must be initialized to point to valid structs before they
|
||
can be used.
|
||
The <code>ReadWriter</code> struct could be written as
|
||
</p>
|
||
<pre>
|
||
type ReadWriter struct {
|
||
reader *Reader
|
||
writer *Writer
|
||
}
|
||
</pre>
|
||
<p>
|
||
but then to promote the methods of the fields and to
|
||
satisfy the <code>io</code> interfaces, we would also need
|
||
to provide forwarding methods, like this:
|
||
</p>
|
||
<pre>
|
||
func (rw *ReadWriter) Read(p []byte) (n int, err error) {
|
||
return rw.reader.Read(p)
|
||
}
|
||
</pre>
|
||
<p>
|
||
By embedding the structs directly, we avoid this bookkeeping.
|
||
The methods of embedded types come along for free, which means that <code>bufio.ReadWriter</code>
|
||
not only has the methods of <code>bufio.Reader</code> and <code>bufio.Writer</code>,
|
||
it also satisfies all three interfaces:
|
||
<code>io.Reader</code>,
|
||
<code>io.Writer</code>, and
|
||
<code>io.ReadWriter</code>.
|
||
</p>
|
||
<p>
|
||
There's an important way in which embedding differs from subclassing. When we embed a type,
|
||
the methods of that type become methods of the outer type,
|
||
but when they are invoked the receiver of the method is the inner type, not the outer one.
|
||
In our example, when the <code>Read</code> method of a <code>bufio.ReadWriter</code> is
|
||
invoked, it has exactly the same effect as the forwarding method written out above;
|
||
the receiver is the <code>reader</code> field of the <code>ReadWriter</code>, not the
|
||
<code>ReadWriter</code> itself.
|
||
</p>
|
||
<p>
|
||
Embedding can also be a simple convenience.
|
||
This example shows an embedded field alongside a regular, named field.
|
||
</p>
|
||
<pre>
|
||
type Job struct {
|
||
Command string
|
||
*log.Logger
|
||
}
|
||
</pre>
|
||
<p>
|
||
The <code>Job</code> type now has the <code>Print</code>, <code>Printf</code>, <code>Println</code>
|
||
and other
|
||
methods of <code>*log.Logger</code>. We could have given the <code>Logger</code>
|
||
a field name, of course, but it's not necessary to do so. And now, once
|
||
initialized, we can
|
||
log to the <code>Job</code>:
|
||
</p>
|
||
<pre>
|
||
job.Println("starting now...")
|
||
</pre>
|
||
<p>
|
||
The <code>Logger</code> is a regular field of the <code>Job</code> struct,
|
||
so we can initialize it in the usual way inside the constructor for <code>Job</code>, like this,
|
||
</p>
|
||
<pre>
|
||
func NewJob(command string, logger *log.Logger) *Job {
|
||
return &Job{command, logger}
|
||
}
|
||
</pre>
|
||
<p>
|
||
or with a composite literal,
|
||
</p>
|
||
<pre>
|
||
job := &Job{command, log.New(os.Stderr, "Job: ", log.Ldate)}
|
||
</pre>
|
||
<p>
|
||
If we need to refer to an embedded field directly, the type name of the field,
|
||
ignoring the package qualifier, serves as a field name, as it did
|
||
in the <code>Read</code> method of our <code>ReadWriter</code> struct.
|
||
Here, if we needed to access the
|
||
<code>*log.Logger</code> of a <code>Job</code> variable <code>job</code>,
|
||
we would write <code>job.Logger</code>,
|
||
which would be useful if we wanted to refine the methods of <code>Logger</code>.
|
||
</p>
|
||
<pre>
|
||
func (job *Job) Printf(format string, args ...interface{}) {
|
||
job.Logger.Printf("%q: %s", job.Command, fmt.Sprintf(format, args...))
|
||
}
|
||
</pre>
|
||
<p>
|
||
Embedding types introduces the problem of name conflicts but the rules to resolve
|
||
them are simple.
|
||
First, a field or method <code>X</code> hides any other item <code>X</code> in a more deeply
|
||
nested part of the type.
|
||
If <code>log.Logger</code> contained a field or method called <code>Command</code>, the <code>Command</code> field
|
||
of <code>Job</code> would dominate it.
|
||
</p>
|
||
<p>
|
||
Second, if the same name appears at the same nesting level, it is usually an error;
|
||
it would be erroneous to embed <code>log.Logger</code> if the <code>Job</code> struct
|
||
contained another field or method called <code>Logger</code>.
|
||
However, if the duplicate name is never mentioned in the program outside the type definition, it is OK.
|
||
This qualification provides some protection against changes made to types embedded from outside; there
|
||
is no problem if a field is added that conflicts with another field in another subtype if neither field
|
||
is ever used.
|
||
</p>
|
||
|
||
|
||
<h2 id="concurrency">Concurrency</h2>
|
||
|
||
<h3 id="sharing">Share by communicating</h3>
|
||
|
||
<p>
|
||
Concurrent programming is a large topic and there is space only for some
|
||
Go-specific highlights here.
|
||
</p>
|
||
<p>
|
||
Concurrent programming in many environments is made difficult by the
|
||
subtleties required to implement correct access to shared variables. Go encourages
|
||
a different approach in which shared values are passed around on channels
|
||
and, in fact, never actively shared by separate threads of execution.
|
||
Only one goroutine has access to the value at any given time.
|
||
Data races cannot occur, by design.
|
||
To encourage this way of thinking we have reduced it to a slogan:
|
||
</p>
|
||
<blockquote>
|
||
Do not communicate by sharing memory;
|
||
instead, share memory by communicating.
|
||
</blockquote>
|
||
<p>
|
||
This approach can be taken too far. Reference counts may be best done
|
||
by putting a mutex around an integer variable, for instance. But as a
|
||
high-level approach, using channels to control access makes it easier
|
||
to write clear, correct programs.
|
||
</p>
|
||
<p>
|
||
One way to think about this model is to consider a typical single-threaded
|
||
program running on one CPU. It has no need for synchronization primitives.
|
||
Now run another such instance; it too needs no synchronization. Now let those
|
||
two communicate; if the communication is the synchronizer, there's still no need
|
||
for other synchronization. Unix pipelines, for example, fit this model
|
||
perfectly. Although Go's approach to concurrency originates in Hoare's
|
||
Communicating Sequential Processes (CSP),
|
||
it can also be seen as a type-safe generalization of Unix pipes.
|
||
</p>
|
||
|
||
<h3 id="goroutines">Goroutines</h3>
|
||
|
||
<p>
|
||
They're called <em>goroutines</em> because the existing
|
||
terms—threads, coroutines, processes, and so on—convey
|
||
inaccurate connotations. A goroutine has a simple model: it is a
|
||
function executing concurrently with other goroutines in the same
|
||
address space. It is lightweight, costing little more than the
|
||
allocation of stack space.
|
||
And the stacks start small, so they are cheap, and grow
|
||
by allocating (and freeing) heap storage as required.
|
||
</p>
|
||
<p>
|
||
Goroutines are multiplexed onto multiple OS threads so if one should
|
||
block, such as while waiting for I/O, others continue to run. Their
|
||
design hides many of the complexities of thread creation and
|
||
management.
|
||
</p>
|
||
<p>
|
||
Prefix a function or method call with the <code>go</code>
|
||
keyword to run the call in a new goroutine.
|
||
When the call completes, the goroutine
|
||
exits, silently. (The effect is similar to the Unix shell's
|
||
<code>&</code> notation for running a command in the
|
||
background.)
|
||
</p>
|
||
<pre>
|
||
go list.Sort() // run list.Sort concurrently; don't wait for it.
|
||
</pre>
|
||
<p>
|
||
A function literal can be handy in a goroutine invocation.
|
||
</p>
|
||
<pre>
|
||
func Announce(message string, delay time.Duration) {
|
||
go func() {
|
||
time.Sleep(delay)
|
||
fmt.Println(message)
|
||
}() // Note the parentheses - must call the function.
|
||
}
|
||
</pre>
|
||
<p>
|
||
In Go, function literals are closures: the implementation makes
|
||
sure the variables referred to by the function survive as long as they are active.
|
||
</p>
|
||
<p>
|
||
These examples aren't too practical because the functions have no way of signaling
|
||
completion. For that, we need channels.
|
||
</p>
|
||
|
||
<h3 id="channels">Channels</h3>
|
||
|
||
<p>
|
||
Like maps, channels are allocated with <code>make</code>, and
|
||
the resulting value acts as a reference to an underlying data structure.
|
||
If an optional integer parameter is provided, it sets the buffer size for the channel.
|
||
The default is zero, for an unbuffered or synchronous channel.
|
||
</p>
|
||
<pre>
|
||
ci := make(chan int) // unbuffered channel of integers
|
||
cj := make(chan int, 0) // unbuffered channel of integers
|
||
cs := make(chan *os.File, 100) // buffered channel of pointers to Files
|
||
</pre>
|
||
<p>
|
||
Unbuffered channels combine communication—the exchange of a value—with
|
||
synchronization—guaranteeing that two calculations (goroutines) are in
|
||
a known state.
|
||
</p>
|
||
<p>
|
||
There are lots of nice idioms using channels. Here's one to get us started.
|
||
In the previous section we launched a sort in the background. A channel
|
||
can allow the launching goroutine to wait for the sort to complete.
|
||
</p>
|
||
<pre>
|
||
c := make(chan int) // Allocate a channel.
|
||
// Start the sort in a goroutine; when it completes, signal on the channel.
|
||
go func() {
|
||
list.Sort()
|
||
c <- 1 // Send a signal; value does not matter.
|
||
}()
|
||
doSomethingForAWhile()
|
||
<-c // Wait for sort to finish; discard sent value.
|
||
</pre>
|
||
<p>
|
||
Receivers always block until there is data to receive.
|
||
If the channel is unbuffered, the sender blocks until the receiver has
|
||
received the value.
|
||
If the channel has a buffer, the sender blocks only until the
|
||
value has been copied to the buffer; if the buffer is full, this
|
||
means waiting until some receiver has retrieved a value.
|
||
</p>
|
||
<p>
|
||
A buffered channel can be used like a semaphore, for instance to
|
||
limit throughput. In this example, incoming requests are passed
|
||
to <code>handle</code>, which sends a value into the channel, processes
|
||
the request, and then receives a value from the channel
|
||
to ready the “semaphore” for the next consumer.
|
||
The capacity of the channel buffer limits the number of
|
||
simultaneous calls to <code>process</code>.
|
||
</p>
|
||
<pre>
|
||
var sem = make(chan int, MaxOutstanding)
|
||
|
||
func handle(r *Request) {
|
||
sem <- 1 // Wait for active queue to drain.
|
||
process(r) // May take a long time.
|
||
<-sem // Done; enable next request to run.
|
||
}
|
||
|
||
func Serve(queue chan *Request) {
|
||
for {
|
||
req := <-queue
|
||
go handle(req) // Don't wait for handle to finish.
|
||
}
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Once <code>MaxOutstanding</code> handlers are executing <code>process</code>,
|
||
any more will block trying to send into the filled channel buffer,
|
||
until one of the existing handlers finishes and receives from the buffer.
|
||
</p>
|
||
|
||
<p>
|
||
This design has a problem, though: <code>Serve</code>
|
||
creates a new goroutine for
|
||
every incoming request, even though only <code>MaxOutstanding</code>
|
||
of them can run at any moment.
|
||
As a result, the program can consume unlimited resources if the requests come in too fast.
|
||
We can address that deficiency by changing <code>Serve</code> to
|
||
gate the creation of the goroutines.
|
||
Here's an obvious solution, but beware it has a bug we'll fix subsequently:
|
||
</p>
|
||
|
||
<pre>
|
||
func Serve(queue chan *Request) {
|
||
for req := range queue {
|
||
sem <- 1
|
||
go func() {
|
||
process(req) // Buggy; see explanation below.
|
||
<-sem
|
||
}()
|
||
}
|
||
}</pre>
|
||
|
||
<p>
|
||
The bug is that in a Go <code>for</code> loop, the loop variable
|
||
is reused for each iteration, so the <code>req</code>
|
||
variable is shared across all goroutines.
|
||
That's not what we want.
|
||
We need to make sure that <code>req</code> is unique for each goroutine.
|
||
Here's one way to do that, passing the value of <code>req</code> as an argument
|
||
to the closure in the goroutine:
|
||
</p>
|
||
|
||
<pre>
|
||
func Serve(queue chan *Request) {
|
||
for req := range queue {
|
||
sem <- 1
|
||
go func(req *Request) {
|
||
process(req)
|
||
<-sem
|
||
}(req)
|
||
}
|
||
}</pre>
|
||
|
||
<p>
|
||
Compare this version with the previous to see the difference in how
|
||
the closure is declared and run.
|
||
Another solution is just to create a new variable with the same
|
||
name, as in this example:
|
||
</p>
|
||
|
||
<pre>
|
||
func Serve(queue chan *Request) {
|
||
for req := range queue {
|
||
req := req // Create new instance of req for the goroutine.
|
||
sem <- 1
|
||
go func() {
|
||
process(req)
|
||
<-sem
|
||
}()
|
||
}
|
||
}</pre>
|
||
|
||
<p>
|
||
It may seem odd to write
|
||
</p>
|
||
|
||
<pre>
|
||
req := req
|
||
</pre>
|
||
|
||
<p>
|
||
but it's legal and idiomatic in Go to do this.
|
||
You get a fresh version of the variable with the same name, deliberately
|
||
shadowing the loop variable locally but unique to each goroutine.
|
||
</p>
|
||
|
||
<p>
|
||
Going back to the general problem of writing the server,
|
||
another approach that manages resources well is to start a fixed
|
||
number of <code>handle</code> goroutines all reading from the request
|
||
channel.
|
||
The number of goroutines limits the number of simultaneous
|
||
calls to <code>process</code>.
|
||
This <code>Serve</code> function also accepts a channel on which
|
||
it will be told to exit; after launching the goroutines it blocks
|
||
receiving from that channel.
|
||
</p>
|
||
|
||
<pre>
|
||
func handle(queue chan *Request) {
|
||
for r := range queue {
|
||
process(r)
|
||
}
|
||
}
|
||
|
||
func Serve(clientRequests chan *Request, quit chan bool) {
|
||
// Start handlers
|
||
for i := 0; i < MaxOutstanding; i++ {
|
||
go handle(clientRequests)
|
||
}
|
||
<-quit // Wait to be told to exit.
|
||
}
|
||
</pre>
|
||
|
||
<h3 id="chan_of_chan">Channels of channels</h3>
|
||
<p>
|
||
One of the most important properties of Go is that
|
||
a channel is a first-class value that can be allocated and passed
|
||
around like any other. A common use of this property is
|
||
to implement safe, parallel demultiplexing.
|
||
</p>
|
||
<p>
|
||
In the example in the previous section, <code>handle</code> was
|
||
an idealized handler for a request but we didn't define the
|
||
type it was handling. If that type includes a channel on which
|
||
to reply, each client can provide its own path for the answer.
|
||
Here's a schematic definition of type <code>Request</code>.
|
||
</p>
|
||
<pre>
|
||
type Request struct {
|
||
args []int
|
||
f func([]int) int
|
||
resultChan chan int
|
||
}
|
||
</pre>
|
||
<p>
|
||
The client provides a function and its arguments, as well as
|
||
a channel inside the request object on which to receive the answer.
|
||
</p>
|
||
<pre>
|
||
func sum(a []int) (s int) {
|
||
for _, v := range a {
|
||
s += v
|
||
}
|
||
return
|
||
}
|
||
|
||
request := &Request{[]int{3, 4, 5}, sum, make(chan int)}
|
||
// Send request
|
||
clientRequests <- request
|
||
// Wait for response.
|
||
fmt.Printf("answer: %d\n", <-request.resultChan)
|
||
</pre>
|
||
<p>
|
||
On the server side, the handler function is the only thing that changes.
|
||
</p>
|
||
<pre>
|
||
func handle(queue chan *Request) {
|
||
for req := range queue {
|
||
req.resultChan <- req.f(req.args)
|
||
}
|
||
}
|
||
</pre>
|
||
<p>
|
||
There's clearly a lot more to do to make it realistic, but this
|
||
code is a framework for a rate-limited, parallel, non-blocking RPC
|
||
system, and there's not a mutex in sight.
|
||
</p>
|
||
|
||
<h3 id="parallel">Parallelization</h3>
|
||
<p>
|
||
Another application of these ideas is to parallelize a calculation
|
||
across multiple CPU cores. If the calculation can be broken into
|
||
separate pieces that can execute independently, it can be parallelized,
|
||
with a channel to signal when each piece completes.
|
||
</p>
|
||
<p>
|
||
Let's say we have an expensive operation to perform on a vector of items,
|
||
and that the value of the operation on each item is independent,
|
||
as in this idealized example.
|
||
</p>
|
||
<pre>
|
||
type Vector []float64
|
||
|
||
// Apply the operation to v[i], v[i+1] ... up to v[n-1].
|
||
func (v Vector) DoSome(i, n int, u Vector, c chan int) {
|
||
for ; i < n; i++ {
|
||
v[i] += u.Op(v[i])
|
||
}
|
||
c <- 1 // signal that this piece is done
|
||
}
|
||
</pre>
|
||
<p>
|
||
We launch the pieces independently in a loop, one per CPU.
|
||
They can complete in any order but it doesn't matter; we just
|
||
count the completion signals by draining the channel after
|
||
launching all the goroutines.
|
||
</p>
|
||
<pre>
|
||
const numCPU = 4 // number of CPU cores
|
||
|
||
func (v Vector) DoAll(u Vector) {
|
||
c := make(chan int, numCPU) // Buffering optional but sensible.
|
||
for i := 0; i < numCPU; i++ {
|
||
go v.DoSome(i*len(v)/numCPU, (i+1)*len(v)/numCPU, u, c)
|
||
}
|
||
// Drain the channel.
|
||
for i := 0; i < numCPU; i++ {
|
||
<-c // wait for one task to complete
|
||
}
|
||
// All done.
|
||
}
|
||
</pre>
|
||
<p>
|
||
Rather than create a constant value for numCPU, we can ask the runtime what
|
||
value is appropriate.
|
||
The function <code><a href="/pkg/runtime#NumCPU">runtime.NumCPU</a></code>
|
||
returns the number of hardware CPU cores in the machine, so we could write
|
||
</p>
|
||
<pre>
|
||
var numCPU = runtime.NumCPU()
|
||
</pre>
|
||
<p>
|
||
There is also a function
|
||
<code><a href="/pkg/runtime#GOMAXPROCS">runtime.GOMAXPROCS</a></code>,
|
||
which reports (or sets)
|
||
the user-specified number of cores that a Go program can have running
|
||
simultaneously.
|
||
It defaults to the value of <code>runtime.NumCPU</code> but can be
|
||
overridden by setting the similarly named shell environment variable
|
||
or by calling the function with a positive number. Calling it with
|
||
zero just queries the value.
|
||
Therefore if we want to honor the user's resource request, we should write
|
||
</p>
|
||
<pre>
|
||
var numCPU = runtime.GOMAXPROCS(0)
|
||
</pre>
|
||
<p>
|
||
Be sure not to confuse the ideas of concurrency—structuring a program
|
||
as independently executing components—and parallelism—executing
|
||
calculations in parallel for efficiency on multiple CPUs.
|
||
Although the concurrency features of Go can make some problems easy
|
||
to structure as parallel computations, Go is a concurrent language,
|
||
not a parallel one, and not all parallelization problems fit Go's model.
|
||
For a discussion of the distinction, see the talk cited in
|
||
<a href="//blog.golang.org/2013/01/concurrency-is-not-parallelism.html">this
|
||
blog post</a>.
|
||
|
||
<h3 id="leaky_buffer">A leaky buffer</h3>
|
||
|
||
<p>
|
||
The tools of concurrent programming can even make non-concurrent
|
||
ideas easier to express. Here's an example abstracted from an RPC
|
||
package. The client goroutine loops receiving data from some source,
|
||
perhaps a network. To avoid allocating and freeing buffers, it keeps
|
||
a free list, and uses a buffered channel to represent it. If the
|
||
channel is empty, a new buffer gets allocated.
|
||
Once the message buffer is ready, it's sent to the server on
|
||
<code>serverChan</code>.
|
||
</p>
|
||
<pre>
|
||
var freeList = make(chan *Buffer, 100)
|
||
var serverChan = make(chan *Buffer)
|
||
|
||
func client() {
|
||
for {
|
||
var b *Buffer
|
||
// Grab a buffer if available; allocate if not.
|
||
select {
|
||
case b = <-freeList:
|
||
// Got one; nothing more to do.
|
||
default:
|
||
// None free, so allocate a new one.
|
||
b = new(Buffer)
|
||
}
|
||
load(b) // Read next message from the net.
|
||
serverChan <- b // Send to server.
|
||
}
|
||
}
|
||
</pre>
|
||
<p>
|
||
The server loop receives each message from the client, processes it,
|
||
and returns the buffer to the free list.
|
||
</p>
|
||
<pre>
|
||
func server() {
|
||
for {
|
||
b := <-serverChan // Wait for work.
|
||
process(b)
|
||
// Reuse buffer if there's room.
|
||
select {
|
||
case freeList <- b:
|
||
// Buffer on free list; nothing more to do.
|
||
default:
|
||
// Free list full, just carry on.
|
||
}
|
||
}
|
||
}
|
||
</pre>
|
||
<p>
|
||
The client attempts to retrieve a buffer from <code>freeList</code>;
|
||
if none is available, it allocates a fresh one.
|
||
The server's send to <code>freeList</code> puts <code>b</code> back
|
||
on the free list unless the list is full, in which case the
|
||
buffer is dropped on the floor to be reclaimed by
|
||
the garbage collector.
|
||
(The <code>default</code> clauses in the <code>select</code>
|
||
statements execute when no other case is ready,
|
||
meaning that the <code>selects</code> never block.)
|
||
This implementation builds a leaky bucket free list
|
||
in just a few lines, relying on the buffered channel and
|
||
the garbage collector for bookkeeping.
|
||
</p>
|
||
|
||
<h2 id="errors">Errors</h2>
|
||
|
||
<p>
|
||
Library routines must often return some sort of error indication to
|
||
the caller.
|
||
As mentioned earlier, Go's multivalue return makes it
|
||
easy to return a detailed error description alongside the normal
|
||
return value.
|
||
It is good style to use this feature to provide detailed error information.
|
||
For example, as we'll see, <code>os.Open</code> doesn't
|
||
just return a <code>nil</code> pointer on failure, it also returns an
|
||
error value that describes what went wrong.
|
||
</p>
|
||
|
||
<p>
|
||
By convention, errors have type <code>error</code>,
|
||
a simple built-in interface.
|
||
</p>
|
||
<pre>
|
||
type error interface {
|
||
Error() string
|
||
}
|
||
</pre>
|
||
<p>
|
||
A library writer is free to implement this interface with a
|
||
richer model under the covers, making it possible not only
|
||
to see the error but also to provide some context.
|
||
As mentioned, alongside the usual <code>*os.File</code>
|
||
return value, <code>os.Open</code> also returns an
|
||
error value.
|
||
If the file is opened successfully, the error will be <code>nil</code>,
|
||
but when there is a problem, it will hold an
|
||
<code>os.PathError</code>:
|
||
</p>
|
||
<pre>
|
||
// PathError records an error and the operation and
|
||
// file path that caused it.
|
||
type PathError struct {
|
||
Op string // "open", "unlink", etc.
|
||
Path string // The associated file.
|
||
Err error // Returned by the system call.
|
||
}
|
||
|
||
func (e *PathError) Error() string {
|
||
return e.Op + " " + e.Path + ": " + e.Err.Error()
|
||
}
|
||
</pre>
|
||
<p>
|
||
<code>PathError</code>'s <code>Error</code> generates
|
||
a string like this:
|
||
</p>
|
||
<pre>
|
||
open /etc/passwx: no such file or directory
|
||
</pre>
|
||
<p>
|
||
Such an error, which includes the problematic file name, the
|
||
operation, and the operating system error it triggered, is useful even
|
||
if printed far from the call that caused it;
|
||
it is much more informative than the plain
|
||
"no such file or directory".
|
||
</p>
|
||
|
||
<p>
|
||
When feasible, error strings should identify their origin, such as by having
|
||
a prefix naming the operation or package that generated the error. For example, in package
|
||
<code>image</code>, the string representation for a decoding error due to an
|
||
unknown format is "image: unknown format".
|
||
</p>
|
||
|
||
<p>
|
||
Callers that care about the precise error details can
|
||
use a type switch or a type assertion to look for specific
|
||
errors and extract details. For <code>PathErrors</code>
|
||
this might include examining the internal <code>Err</code>
|
||
field for recoverable failures.
|
||
</p>
|
||
|
||
<pre>
|
||
for try := 0; try < 2; try++ {
|
||
file, err = os.Create(filename)
|
||
if err == nil {
|
||
return
|
||
}
|
||
if e, ok := err.(*os.PathError); ok && e.Err == syscall.ENOSPC {
|
||
deleteTempFiles() // Recover some space.
|
||
continue
|
||
}
|
||
return
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
The second <code>if</code> statement here is another <a href="#interface_conversions">type assertion</a>.
|
||
If it fails, <code>ok</code> will be false, and <code>e</code>
|
||
will be <code>nil</code>.
|
||
If it succeeds, <code>ok</code> will be true, which means the
|
||
error was of type <code>*os.PathError</code>, and then so is <code>e</code>,
|
||
which we can examine for more information about the error.
|
||
</p>
|
||
|
||
<h3 id="panic">Panic</h3>
|
||
|
||
<p>
|
||
The usual way to report an error to a caller is to return an
|
||
<code>error</code> as an extra return value. The canonical
|
||
<code>Read</code> method is a well-known instance; it returns a byte
|
||
count and an <code>error</code>. But what if the error is
|
||
unrecoverable? Sometimes the program simply cannot continue.
|
||
</p>
|
||
|
||
<p>
|
||
For this purpose, there is a built-in function <code>panic</code>
|
||
that in effect creates a run-time error that will stop the program
|
||
(but see the next section). The function takes a single argument
|
||
of arbitrary type—often a string—to be printed as the
|
||
program dies. It's also a way to indicate that something impossible has
|
||
happened, such as exiting an infinite loop.
|
||
</p>
|
||
|
||
|
||
<pre>
|
||
// A toy implementation of cube root using Newton's method.
|
||
func CubeRoot(x float64) float64 {
|
||
z := x/3 // Arbitrary initial value
|
||
for i := 0; i < 1e6; i++ {
|
||
prevz := z
|
||
z -= (z*z*z-x) / (3*z*z)
|
||
if veryClose(z, prevz) {
|
||
return z
|
||
}
|
||
}
|
||
// A million iterations has not converged; something is wrong.
|
||
panic(fmt.Sprintf("CubeRoot(%g) did not converge", x))
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
This is only an example but real library functions should
|
||
avoid <code>panic</code>. If the problem can be masked or worked
|
||
around, it's always better to let things continue to run rather
|
||
than taking down the whole program. One possible counterexample
|
||
is during initialization: if the library truly cannot set itself up,
|
||
it might be reasonable to panic, so to speak.
|
||
</p>
|
||
|
||
<pre>
|
||
var user = os.Getenv("USER")
|
||
|
||
func init() {
|
||
if user == "" {
|
||
panic("no value for $USER")
|
||
}
|
||
}
|
||
</pre>
|
||
|
||
<h3 id="recover">Recover</h3>
|
||
|
||
<p>
|
||
When <code>panic</code> is called, including implicitly for run-time
|
||
errors such as indexing a slice out of bounds or failing a type
|
||
assertion, it immediately stops execution of the current function
|
||
and begins unwinding the stack of the goroutine, running any deferred
|
||
functions along the way. If that unwinding reaches the top of the
|
||
goroutine's stack, the program dies. However, it is possible to
|
||
use the built-in function <code>recover</code> to regain control
|
||
of the goroutine and resume normal execution.
|
||
</p>
|
||
|
||
<p>
|
||
A call to <code>recover</code> stops the unwinding and returns the
|
||
argument passed to <code>panic</code>. Because the only code that
|
||
runs while unwinding is inside deferred functions, <code>recover</code>
|
||
is only useful inside deferred functions.
|
||
</p>
|
||
|
||
<p>
|
||
One application of <code>recover</code> is to shut down a failing goroutine
|
||
inside a server without killing the other executing goroutines.
|
||
</p>
|
||
|
||
<pre>
|
||
func server(workChan <-chan *Work) {
|
||
for work := range workChan {
|
||
go safelyDo(work)
|
||
}
|
||
}
|
||
|
||
func safelyDo(work *Work) {
|
||
defer func() {
|
||
if err := recover(); err != nil {
|
||
log.Println("work failed:", err)
|
||
}
|
||
}()
|
||
do(work)
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
In this example, if <code>do(work)</code> panics, the result will be
|
||
logged and the goroutine will exit cleanly without disturbing the
|
||
others. There's no need to do anything else in the deferred closure;
|
||
calling <code>recover</code> handles the condition completely.
|
||
</p>
|
||
|
||
<p>
|
||
Because <code>recover</code> always returns <code>nil</code> unless called directly
|
||
from a deferred function, deferred code can call library routines that themselves
|
||
use <code>panic</code> and <code>recover</code> without failing. As an example,
|
||
the deferred function in <code>safelyDo</code> might call a logging function before
|
||
calling <code>recover</code>, and that logging code would run unaffected
|
||
by the panicking state.
|
||
</p>
|
||
|
||
<p>
|
||
With our recovery pattern in place, the <code>do</code>
|
||
function (and anything it calls) can get out of any bad situation
|
||
cleanly by calling <code>panic</code>. We can use that idea to
|
||
simplify error handling in complex software. Let's look at an
|
||
idealized version of a <code>regexp</code> package, which reports
|
||
parsing errors by calling <code>panic</code> with a local
|
||
error type. Here's the definition of <code>Error</code>,
|
||
an <code>error</code> method, and the <code>Compile</code> function.
|
||
</p>
|
||
|
||
<pre>
|
||
// Error is the type of a parse error; it satisfies the error interface.
|
||
type Error string
|
||
func (e Error) Error() string {
|
||
return string(e)
|
||
}
|
||
|
||
// error is a method of *Regexp that reports parsing errors by
|
||
// panicking with an Error.
|
||
func (regexp *Regexp) error(err string) {
|
||
panic(Error(err))
|
||
}
|
||
|
||
// Compile returns a parsed representation of the regular expression.
|
||
func Compile(str string) (regexp *Regexp, err error) {
|
||
regexp = new(Regexp)
|
||
// doParse will panic if there is a parse error.
|
||
defer func() {
|
||
if e := recover(); e != nil {
|
||
regexp = nil // Clear return value.
|
||
err = e.(Error) // Will re-panic if not a parse error.
|
||
}
|
||
}()
|
||
return regexp.doParse(str), nil
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
If <code>doParse</code> panics, the recovery block will set the
|
||
return value to <code>nil</code>—deferred functions can modify
|
||
named return values. It will then check, in the assignment
|
||
to <code>err</code>, that the problem was a parse error by asserting
|
||
that it has the local type <code>Error</code>.
|
||
If it does not, the type assertion will fail, causing a run-time error
|
||
that continues the stack unwinding as though nothing had interrupted
|
||
it.
|
||
This check means that if something unexpected happens, such
|
||
as an index out of bounds, the code will fail even though we
|
||
are using <code>panic</code> and <code>recover</code> to handle
|
||
parse errors.
|
||
</p>
|
||
|
||
<p>
|
||
With error handling in place, the <code>error</code> method (because it's a
|
||
method bound to a type, it's fine, even natural, for it to have the same name
|
||
as the builtin <code>error</code> type)
|
||
makes it easy to report parse errors without worrying about unwinding
|
||
the parse stack by hand:
|
||
</p>
|
||
|
||
<pre>
|
||
if pos == 0 {
|
||
re.error("'*' illegal at start of expression")
|
||
}
|
||
</pre>
|
||
|
||
<p>
|
||
Useful though this pattern is, it should be used only within a package.
|
||
<code>Parse</code> turns its internal <code>panic</code> calls into
|
||
<code>error</code> values; it does not expose <code>panics</code>
|
||
to its client. That is a good rule to follow.
|
||
</p>
|
||
|
||
<p>
|
||
By the way, this re-panic idiom changes the panic value if an actual
|
||
error occurs. However, both the original and new failures will be
|
||
presented in the crash report, so the root cause of the problem will
|
||
still be visible. Thus this simple re-panic approach is usually
|
||
sufficient—it's a crash after all—but if you want to
|
||
display only the original value, you can write a little more code to
|
||
filter unexpected problems and re-panic with the original error.
|
||
That's left as an exercise for the reader.
|
||
</p>
|
||
|
||
|
||
<h2 id="web_server">A web server</h2>
|
||
|
||
<p>
|
||
Let's finish with a complete Go program, a web server.
|
||
This one is actually a kind of web re-server.
|
||
Google provides a service at <code>chart.apis.google.com</code>
|
||
that does automatic formatting of data into charts and graphs.
|
||
It's hard to use interactively, though,
|
||
because you need to put the data into the URL as a query.
|
||
The program here provides a nicer interface to one form of data: given a short piece of text,
|
||
it calls on the chart server to produce a QR code, a matrix of boxes that encode the
|
||
text.
|
||
That image can be grabbed with your cell phone's camera and interpreted as,
|
||
for instance, a URL, saving you typing the URL into the phone's tiny keyboard.
|
||
</p>
|
||
<p>
|
||
Here's the complete program.
|
||
An explanation follows.
|
||
</p>
|
||
{{code "/doc/progs/eff_qr.go" `/package/` `$`}}
|
||
<p>
|
||
The pieces up to <code>main</code> should be easy to follow.
|
||
The one flag sets a default HTTP port for our server. The template
|
||
variable <code>templ</code> is where the fun happens. It builds an HTML template
|
||
that will be executed by the server to display the page; more about
|
||
that in a moment.
|
||
</p>
|
||
<p>
|
||
The <code>main</code> function parses the flags and, using the mechanism
|
||
we talked about above, binds the function <code>QR</code> to the root path
|
||
for the server. Then <code>http.ListenAndServe</code> is called to start the
|
||
server; it blocks while the server runs.
|
||
</p>
|
||
<p>
|
||
<code>QR</code> just receives the request, which contains form data, and
|
||
executes the template on the data in the form value named <code>s</code>.
|
||
</p>
|
||
<p>
|
||
The template package <code>html/template</code> is powerful;
|
||
this program just touches on its capabilities.
|
||
In essence, it rewrites a piece of HTML text on the fly by substituting elements derived
|
||
from data items passed to <code>templ.Execute</code>, in this case the
|
||
form value.
|
||
Within the template text (<code>templateStr</code>),
|
||
double-brace-delimited pieces denote template actions.
|
||
The piece from <code>{{html "{{if .}}"}}</code>
|
||
to <code>{{html "{{end}}"}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
|
||
is non-empty.
|
||
That is, when the string is empty, this piece of the template is suppressed.
|
||
</p>
|
||
<p>
|
||
The two snippets <code>{{html "{{.}}"}}</code> say to show the data presented to
|
||
the template—the query string—on the web page.
|
||
The HTML template package automatically provides appropriate escaping so the
|
||
text is safe to display.
|
||
</p>
|
||
<p>
|
||
The rest of the template string is just the HTML to show when the page loads.
|
||
If this is too quick an explanation, see the <a href="/pkg/html/template/">documentation</a>
|
||
for the template package for a more thorough discussion.
|
||
</p>
|
||
<p>
|
||
And there you have it: a useful web server in a few lines of code plus some
|
||
data-driven HTML text.
|
||
Go is powerful enough to make a lot happen in a few lines.
|
||
</p>
|
||
|
||
<!--
|
||
TODO
|
||
<pre>
|
||
verifying implementation
|
||
type Color uint32
|
||
|
||
// Check that Color implements image.Color and image.Image
|
||
var _ image.Color = Black
|
||
var _ image.Image = Black
|
||
</pre>
|
||
-->
|