| <!-- Effective Go --> |
| |
| <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="go_spec.html">language specification</a> |
| and the <a href="go_tutorial.html">tutorial</a>, both of which you |
| should read first. |
| </p> |
| |
| <h3 id="read">Examples</h3> |
| |
| <p> |
| The <a href="/src/pkg/">Go package sources</a> |
| are intended to serve not |
| only as the core library but also as examples of how to |
| use the language. |
| If you have a question about how to approach a problem or how something |
| might be implemented, they 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. |
| A program, <code>gofmt</code>, 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, fix the program (or file a bug), 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 code in the libraries 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: control structures (<code>if</code>, |
| <code>for</code>, <code>switch</code>) do not require 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. |
| </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 and |
| are also useful 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> |
| /* |
| The regexp package 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> |
| // The path package 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. |
| Finally, 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. |
| </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 English 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 |
| // object that can be used to match against text. |
| func Compile(str string) (regexp *Regexp, error os.Error) { |
| </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 = os.NewError("internal error") |
| ErrUnmatchedLpar = os.NewError("unmatched '('") |
| ErrUnmatchedRpar = os.NewError("unmatched ')'") |
| ... |
| ) |
| </pre> |
| |
| <p> |
| Even for private names, 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. |
| In some cases they even have semantic effect: for instance, |
| 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/pkg/container/vector</code> |
| is imported as <code>"container/vector"</code> but has name <code>vector</code>, |
| not <code>container_vector</code> and not <code>containerVector</code>. |
| </p> |
| |
| <p> |
| The importer of a package will use the name to refer to its contents |
| (the <code>import .</code> notation is intended mostly for tests and other |
| unusual situations), so exported names in the package can use that fact |
| to avoid stutter. |
| 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>. |
| Clients of the package see that 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. |
| If the name represents something intricate or subtle, it's usually better |
| to write a helpful doc comment than to attempt to put all the information |
| into the name. |
| </p> |
| |
| <h3 id="interface-names">Interface names</h3> |
| |
| <p> |
| By convention, one-method interfaces are named by |
| the method name plus the -er suffix: <code>Reader</code>, |
| <code>Writer</code>, <code>Formatter</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; |
| unlike 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, add 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 caveat. You should never 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 different |
| 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>; |
| and there are new control structures including a type switch and a |
| multiway communications multiplexer, <code>select</code>. |
| The syntax is also slightly different: |
| parentheses are not required |
| 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.Stderr(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, os.O_RDONLY, 0) |
| if err != nil { |
| return err |
| } |
| codeUsing(f) |
| </pre> |
| |
| <p> |
| This is a example of a common situation where code must analyze a |
| sequence of error possibilities. 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, os.O_RDONLY, 0) |
| if err != nil { |
| return err |
| } |
| d, err := f.Stat() |
| if err != nil { |
| return err |
| } |
| codeUsing(f, d) |
| </pre> |
| |
| |
| <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 for you. |
| </p> |
| <pre> |
| var m map[string]int |
| sum := 0 |
| for _, value := range m { // key is unused |
| sum += value |
| } |
| </pre> |
| |
| <p> |
| For strings, the <code>range</code> does more work for you, breaking out individual |
| Unicode characters by parsing the UTF-8 (erroneous encodings consume one byte and produce the |
| replacement rune U+FFFD). The loop |
| </p> |
| <pre> |
| for pos, char := range "日本語" { |
| fmt.Printf("character %c starts at byte position %d\n", char, pos) |
| } |
| </pre> |
| <p> |
| prints |
| </p> |
| <pre> |
| character æ—¥ starts at byte position 0 |
| character 本 starts at byte position 3 |
| character 語 starts at byte position 6 |
| </pre> |
| |
| <p> |
| Finally, since Go has no comma operator and <code>++</code> and <code>--</code> |
| are statements not expressions, if you want to run multiple variables in a <code>for</code> |
| you should use parallel assignment. |
| </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. |
| <pre> |
| func shouldEscape(c byte) bool { |
| switch c { |
| case ' ', '?', '&', '=', '#', '+', '%': |
| return true |
| } |
| return false |
| } |
| </pre> |
| |
| <p> |
| Here's a comparison routine for byte arrays that uses two |
| <code>switch</code> statements: |
| <pre> |
| // Compare returns an integer comparing the two byte arrays |
| // 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> |
| |
| <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. |
| </p> |
| <pre> |
| switch t := interfaceValue.(type) { |
| default: |
| fmt.Printf("unexpected type %T", t) // %T prints type |
| case bool: |
| fmt.Printf("boolean %t\n", t) |
| case int: |
| fmt.Printf("integer %d\n", t) |
| case *bool: |
| fmt.Printf("pointer to boolean %t\n", *t) |
| case *int: |
| fmt.Printf("pointer to integer %d\n", *t) |
| } |
| </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 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. |
| </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 <code>*File.Write</code> in 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 array, 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 array <code>a</code> like this: |
| </p> |
| |
| <pre> |
| for i := 0; i < len(a); { |
| x, i = nextInt(a, 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 os.Error) { |
| for len(buf) > 0 && err == nil { |
| var nr int |
| nr, err = r.Read(buf) |
| n += nr |
| buf = buf[nr:len(buf)] |
| } |
| return |
| } |
| </pre> |
| |
| <h2 id="data">Data</h2> |
| |
| <h3 id="allocation_new">Allocation with <code>new()</code></h3> |
| |
| <p> |
| Go has two allocation primitives, <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 essentially the same as its namesakes |
| in other languages: <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 that the |
| zeroed object 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 this 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 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 initialized (not zero) |
| value of type <code>T</code>, not <code>*T</code>. |
| The reason for the distinction |
| is that these three types are, 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; 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> |
| 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) // 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>. |
| </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]float) (sum float) { |
| for _, v := range *a { |
| sum += v |
| } |
| return |
| } |
| |
| array := [...]float{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. Slices are. |
| </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 are <i>reference types</i>, which means that if you assign one |
| slice to another, both refer to the same underlying array. For |
| instance, 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 (file *File) Read(buf []byte) (n int, err os.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>b</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, this snippet would also read the first 32 bytes of the buffer. |
| </p> |
| <pre> |
| var n int |
| var err os.Error |
| for i := 0; i < 32; i++ { |
| nbytes, e := f.Read(buf[i:i+1]) // Read one byte. |
| if nbytes == 0 || e != nil { |
| err = e |
| break |
| } |
| n += nbytes |
| } |
| </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) |
| // Copy data (could use bytes.Copy()). |
| for i, c := range slice { |
| newSlice[i] = c |
| } |
| slice = newSlice |
| } |
| slice = slice[0:l+len(data)] |
| for i, c := range data { |
| slice[l+i] = c |
| } |
| 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> |
| |
| |
| <h3 id="maps">Maps</h3> |
| |
| <p> |
| Maps are a convenient and powerful built-in data structure to associate |
| values of different types. |
| The key can be of any type for which the equality operator is defined, |
| such as integers, |
| floats, strings, pointers, and interfaces (as long as the dynamic type |
| supports equality). Structs, arrays and slices cannot be used as map keys, |
| because equality is not defined on those types. |
| Like slices, maps are a reference type. 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 except that the index doesn't need to |
| be an integer. An attempt to fetch a map value with a key that |
| is not present in the map will cause the program to crash, but |
| there is a way to do so safely using a 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: |
| </p> |
| <pre> |
| func offset(tz string) int { |
| if seconds, ok := timeZone[tz]; ok { |
| return seconds |
| } |
| log.Stderr("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 <em>blank identifier</em>, a simple underscore (<code>_</code>). |
| The blank identifier can be assigned or declared with any value of any type, with the |
| value discarded harmlessly. For testing presence in a map, use the blank |
| identifier in place of the usual variable for the value. |
| </p> |
| <pre> |
| _, present := timeZone[tz] |
| </pre> |
| <p> |
| To delete a map entry, turn the multiple assignment around by placing |
| an extra boolean on the right; if the boolean is false, the entry |
| is deleted. It's safe to do this even if the key is already absent |
| from the map. |
| </p> |
| <pre> |
| timeZone["PDT"] = 0, false // 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>ln</code> version also inserts a blank |
| between arguments if neither is a string and appends a newline to the output. |
| 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(fmt.Sprint("Hello ", 23)) |
| </pre> |
| <p> |
| As mentioned in |
| the <a href="go_tutorial.html">tutorial</a>, <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, 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 float |
| 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. |
| Also, <code>%x</code> works on strings and arrays of bytes 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. |
| <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 <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> |
| Our <code>String()</code> method is able to call <code>Sprintf</code> because the |
| print routines are fully reentrant and can be used recursively. |
| We can even go one step further and pass a print routine's arguments directly to another such routine. |
| The signature of <code>Printf</code> uses the <code>...</code> |
| type for its final argument to specify that an arbitrary number of parameters can appear |
| after the format. |
| </p> |
| <pre> |
| func Printf(format string, v ...) (n int, errno os.Error) { |
| </pre> |
| <p> |
| Within the function <code>Printf</code>, <code>v</code> is a variable that can be passed, |
| for instance, to another print routine. Here is the implementation of the |
| function <code>log.Stderr</code> we used above. It passes its arguments directly to |
| <code>fmt.Sprintln</code> for the actual formatting. |
| </p> |
| <pre> |
| // Stderr is a helper function for easy logging to stderr. It is analogous to Fprint(os.Stderr). |
| func Stderr(v ...) { |
| stderr.Output(2, fmt.Sprintln(v)) // Output takes parameters (int, string) |
| } |
| </pre> |
| <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> |
| |
| <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 between initialized objects in 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, 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> |
| <pre> |
| type ByteSize float64 |
| const ( |
| _ = iota // ignore first value by assigning to blank identifier |
| KB ByteSize = 1<<(10*iota) |
| MB |
| GB |
| TB |
| PB |
| EB |
| ZB |
| YB |
| ) |
| </pre> |
| <p> |
| The ability to attach a method such as <code>String</code> to a |
| type makes it possible for such values to format themselves |
| automatically for printing, even as part of a general type. |
| </p> |
| <pre> |
| func (b ByteSize) String() string { |
| switch { |
| case b >= YB: |
| return fmt.Sprintf("%.2fYB", b/YB) |
| case b >= ZB: |
| return fmt.Sprintf("%.2fZB", b/ZB) |
| case b >= EB: |
| return fmt.Sprintf("%.2fEB", b/EB) |
| case b >= PB: |
| return fmt.Sprintf("%.2fPB", b/PB) |
| case b >= TB: |
| return fmt.Sprintf("%.2fTB", b/TB) |
| case b >= GB: |
| return fmt.Sprintf("%.2fGB", b/GB) |
| case b >= MB: |
| return fmt.Sprintf("%.2fMB", b/MB) |
| case b >= KB: |
| return fmt.Sprintf("%.2fKB", b/KB) |
| } |
| return fmt.Sprintf("%.2fB", b) |
| } |
| </pre> |
| <p> |
| The expression <code>YB</code> prints as <code>1.00YB</code>, |
| while <code>ByteSize(1e13)</code> prints as <code>9.09TB</code>. |
| </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") |
| GOROOT = os.Getenv("GOROOT") |
| ) |
| </pre> |
| |
| <h3 id="init">The init function</h3> |
| |
| <p> |
| Finally, each source file can define its own <code>init()</code> function to |
| set up whatever state is required. The only restriction is that, although |
| goroutines can be launched during initialization, they will not begin |
| execution until it completes; initialization always runs as a single thread |
| of execution. |
| 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.Exit("$USER not set") |
| } |
| if HOME == "" { |
| HOME = "/usr/" + USER |
| } |
| if GOROOT == "" { |
| GOROOT = HOME + "/go" |
| } |
| // GOROOT may be overridden by --goroot flag on command line. |
| flag.StringVar(&GOROOT, "goroot", GOROOT, "Go root directory") |
| } |
| </pre> |
| |
| <h2 id="methods">Methods</h2> |
| |
| <h3 id="pointers_vs_values">Pointers vs. Values</h3> |
| <p> |
| Methods can be defined for any named type that is not a pointer or an interface; |
| the receiver does not have to be a struct. |
| <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 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 os.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. This is because pointer methods can modify the |
| receiver; invoking them on a copy of the value would cause those |
| modifications to be discarded. |
| </p> |
| <p> |
| By the way, the idea of using <code>Write</code> on a slice of bytes |
| is implemented by <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> |
| <pre> |
| type Sequence []int |
| |
| // Methods required by sort.Interface. |
| func (s Sequence) Len() int { |
| return len(s) |
| } |
| func (s Sequence) Less(i, j int) bool { |
| return s[i] < s[j] |
| } |
| func (s Sequence) Swap(i, j int) { |
| s[i], s[j] = s[j], s[i] |
| } |
| |
| // Method for printing - sorts the elements before printing. |
| func (s Sequence) String() string { |
| sort.Sort(s) |
| str := "[" |
| for i, elem := range s { |
| if i > 0 { |
| str += " " |
| } |
| str += fmt.Sprint(elem) |
| } |
| return str + "]" |
| } |
| </pre> |
| |
| <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. We can share the |
| effort 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 { |
| sort.Sort(s) |
| return fmt.Sprint([]int(s)) |
| } |
| </pre> |
| <p> |
| The conversion causes <code>s</code> to be treated as an ordinary slice |
| and therefore receive the default formatting. |
| Without the conversion, <code>Sprint</code> would find the |
| <code>String</code> method of <code>Sequence</code> and recur indefinitely. |
| 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 float, 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.IntArray</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 { |
| sort.IntArray(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.IntArray</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="generality">Generality</h3> |
| <p> |
| If a type exists only to implement an interface |
| and has no exported methods beyond that interface, |
| there is no need to export the type itself. |
| Exporting just the interface makes it clear that |
| it's the behavior that matters, not the implementation, |
| and that other implementations with different properties |
| can mirror the behavior of the original type. |
| 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 <code>crypto/block</code> package to be |
| separated from the block ciphers they chain together. |
| By analogy with the <code>bufio</code> package, |
| they wrap a <code>Cipher</code> interface |
| and return <code>hash.Hash</code>, |
| <code>io.Reader</code>, or <code>io.Writer</code> |
| interface values, not specific implementations. |
| </p> |
| <p> |
| The interface to <code>crypto/block</code> includes: |
| </p> |
| <pre> |
| type Cipher interface { |
| BlockSize() int |
| Encrypt(src, dst []byte) |
| Decrypt(src, dst []byte) |
| } |
| |
| // NewECBDecrypter returns a reader that reads data |
| // from r and decrypts it using c in electronic codebook (ECB) mode. |
| func NewECBDecrypter(c Cipher, r io.Reader) io.Reader |
| |
| // NewCBCDecrypter returns a reader that reads data |
| // from r and decrypts it using c in cipher block chaining (CBC) mode |
| // with the initialization vector iv. |
| func NewCBCDecrypter(c Cipher, iv []byte, r io.Reader) io.Reader |
| </pre> |
| <p> |
| <code>NewECBDecrypter</code> and <code>NewCBCReader</code> apply not |
| just to one specific encryption algorithm and data source but to any |
| implementation of the <code>Cipher</code> interface and any |
| <code>io.Reader</code>. Because they return <code>io.Reader</code> |
| interface values, replacing ECB |
| encryption with CBC encryption is a localized change. The constructor |
| calls must be edited, but because the surrounding code must treat the result only |
| as an <code>io.Reader</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(*Conn, *Request) |
| } |
| </pre> |
| <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(c *http.Conn, req *http.Request) { |
| ctr.n++ |
| fmt.Fprintf(c, "counter = %d\n", ctr.n) |
| } |
| </pre> |
| <p> |
| (Keeping with our theme, note how <code>Fprintf</code> can print to an HTTP connection.) |
| For reference, here's how to attach such a server to a node on the URL tree. |
| <pre> |
| import "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(c *http.Conn, req *http.Request) { |
| *ctr++ |
| fmt.Fprintf(c, "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(c *http.Conn, req *http.Request) { |
| ch <- req |
| fmt.Fprint(c, "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() { |
| for i, s := range os.Args { |
| fmt.Println(s) |
| } |
| } |
| </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(*Conn, *Request) |
| |
| // ServeHTTP calls f(c, req). |
| func (f HandlerFunc) ServeHTTP(c *Conn, req *Request) { |
| f(c, 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(c *http.Conn, req *http.Request) { |
| for i, s := range os.Args { |
| fmt.Fprintln(c, s) |
| } |
| } |
| </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>IntArray</code> |
| to access <code>IntArray.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(c, 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="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 os.Error) |
| } |
| |
| type Writer interface { |
| Write(p []byte) (n int, err os.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> |
| // ReadWrite is the interface that groups the basic Read and Write methods. |
| 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> |
| 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 os.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>Log</code>, <code>Logf</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.Log("starting now...") |
| </pre> |
| <p> |
| The <code>Logger</code> is a regular field of the struct and we can initialize |
| it in the usual way with a constructor, |
| </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, nil, "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. 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>. |
| This would be useful if we wanted to refine the methods of <code>Logger</code>. |
| </p> |
| <pre> |
| func (job *Job) Logf(format string, args ...) { |
| job.Logger.Logf("%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 <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 in parallel 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 in parallel; don't wait for it. |
| </pre> |
| <p> |
| A function literal can be handy in a goroutine invocation. |
| <pre> |
| func Announce(message string, delay int64) { |
| 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> |
| 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 a reference type and are allocated with <code>make</code>. |
| 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> |
| 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. |
| 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> |
| Here's the same idea implemented by starting 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 *clientRequests, 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> |
| 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, 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 NCPU = 4 // number of CPU cores |
| |
| func (v Vector) DoAll(u Vector) { |
| c := make(chan int, NCPU) // Buffering optional but sensible. |
| for i := 0; i < NCPU; i++ { |
| go v.DoSome(i*len(v)/NCPU, (i+1)*len(v)/NCPU, u, c) |
| } |
| // Drain the channel. |
| for i := 0; i < NCPU; i++ { |
| <-c // wait for one task to complete |
| } |
| // All done. |
| } |
| |
| </pre> |
| |
| <p> |
| The current implementation of <code>gc</code> (<code>6g</code>, etc.) |
| will not parallelize this code by default. |
| It dedicates only a single core to user-level processing. An |
| arbitrary number of goroutines can be blocked in system calls, but |
| by default only one can be executing user-level code at any time. |
| It should be smarter and one day it will be smarter, but until it |
| is if you want CPU parallelism you must tell the run-time |
| how many goroutines you want executing code simultaneously. There |
| are two related ways to do this. Either run your job with environment |
| variable <code>GOMAXPROCS</code> set to the number of cores to use |
| (default 1); or import the <code>runtime</code> package and call |
| <code>runtime.GOMAXPROCS(NCPU)</code>. |
| Again, this requirement is expected to be retired as the scheduling and run-time improve. |
| </p> |
| |
| <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 { |
| b, ok := <-freeList // grab a buffer if available |
| if !ok { // if not, 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 messages from the client, processes them, |
| and returns the buffer to the free list. |
| </p> |
| <pre> |
| func server() { |
| for { |
| b := <-serverChan // wait for work |
| process(b) |
| _ = freeList <- b // reuse buffer if room |
| } |
| } |
| </pre> |
| <p> |
| The client's non-blocking receive from <code>freeList</code> obtains a |
| buffer if one is available; otherwise the client allocates |
| a fresh one. |
| The server's non-blocking send on freeList 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 assignment of the send operation to the blank identifier |
| makes it non-blocking but ignores whether |
| the operation succeeded.) |
| 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. By convention, errors have type <code>os.Error</code>, |
| a simple interface. |
| </p> |
| <pre> |
| type Error interface { |
| String() 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. |
| For example, <code>os.Open</code> returns 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. |
| Error Error // Returned by the system call. |
| } |
| |
| func (e *PathError) String() string { |
| return e.Op + " " + e.Path + ": " + e.Error.String() |
| } |
| </pre> |
| <p> |
| <code>PathError</code>'s <code>String</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> |
| 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>Error</code> |
| field for recoverable failures. |
| </p> |
| |
| <pre> |
| for try := 0; try < 2; try++ { |
| file, err = os.Open(filename, os.O_RDONLY, 0) |
| if err == nil { |
| return |
| } |
| if e, ok := err.(*os.PathError); ok && e.Error == os.ENOSPC { |
| deleteTempFiles() // Recover some space. |
| continue |
| } |
| return |
| } |
| </pre> |
| |
| <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 |
| <a href="http://chart.apis.google.com">http://chart.apis.google.com</a> |
| 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> |
| |
| <pre> |
| package main |
| |
| import ( |
| "flag" |
| "http" |
| "io" |
| "log" |
| "strings" |
| "template" |
| ) |
| |
| var addr = flag.String("addr", ":1718", "http service address") // Q=17, R=18 |
| var fmap = template.FormatterMap{ |
| "html": template.HTMLFormatter, |
| "url+html": UrlHtmlFormatter, |
| } |
| var templ = template.MustParse(templateStr, fmap) |
| |
| func main() { |
| flag.Parse() |
| http.Handle("/", http.HandlerFunc(QR)) |
| err := http.ListenAndServe(*addr, nil) |
| if err != nil { |
| log.Exit("ListenAndServe:", err) |
| } |
| } |
| |
| func QR(c *http.Conn, req *http.Request) { |
| templ.Execute(req.FormValue("s"), c) |
| } |
| |
| func UrlHtmlFormatter(w io.Writer, v interface{}, fmt string) { |
| template.HTMLEscape(w, strings.Bytes(http.URLEscape(v.(string)))) |
| } |
| |
| |
| const templateStr = ` |
| <html> |
| <head> |
| <title>QR Link Generator</title> |
| </head> |
| <body> |
| {.section @} |
| <img src="http://chart.apis.google.com/chart?chs=300x300&cht=qr&choe=UTF-8&chl={@|url+html}" |
| /> |
| <br> |
| {@|html} |
| <br> |
| <br> |
| {.end} |
| <form action="/" name=f method="GET"><input maxLength=1024 size=70 |
| name=s value="" title="Text to QR Encode"><input type=submit |
| value="Show QR" name=qr> |
| </form> |
| </body> |
| </html> |
| ` |
| </pre> |
| |
| <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, inspired by <a |
| href="http://code.google.com/p/json-template">json-template</a>, is |
| powerful; |
| this program just touches on its capabilities. |
| In essence, it rewrites a piece of 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>), |
| brace-delimited pieces denote template actions. |
| The piece from the <code>{.section @}</code> |
| to <code>{.end}</code> executes with the value of the data item <code>@</code>, |
| which is a shorthand for “the current item”, which is the form value. |
| (When the string is empty, this piece of the template is suppressed.) |
| </p> |
| <p> |
| The snippet <code>{@|url+html}</code> says to run the data through the formatter |
| installed in the formatter map (<code>fmap</code>) |
| under the name <code>"url+html"</code>. |
| That is the function <code>UrlHtmlFormatter</code>, which sanitizes the string |
| for safe display on the web page. |
| </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/template/">documentation</a> |
| for the template package for a more thorough discussion. |
| </p> |
| <p> |
| And there you have it: a useful webserver 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> |
| --> |
| |