Brent Austin | ba3052e | 2015-04-21 16:08:23 -0700 | [diff] [blame^] | 1 | <!--{ |
| 2 | "Title": "Effective Go", |
| 3 | "Template": true |
| 4 | }--> |
| 5 | |
| 6 | <h2 id="introduction">Introduction</h2> |
| 7 | |
| 8 | <p> |
| 9 | Go is a new language. Although it borrows ideas from |
| 10 | existing languages, |
| 11 | it has unusual properties that make effective Go programs |
| 12 | different in character from programs written in its relatives. |
| 13 | A straightforward translation of a C++ or Java program into Go |
| 14 | is unlikely to produce a satisfactory result—Java programs |
| 15 | are written in Java, not Go. |
| 16 | On the other hand, thinking about the problem from a Go |
| 17 | perspective could produce a successful but quite different |
| 18 | program. |
| 19 | In other words, |
| 20 | to write Go well, it's important to understand its properties |
| 21 | and idioms. |
| 22 | It's also important to know the established conventions for |
| 23 | programming in Go, such as naming, formatting, program |
| 24 | construction, and so on, so that programs you write |
| 25 | will be easy for other Go programmers to understand. |
| 26 | </p> |
| 27 | |
| 28 | <p> |
| 29 | This document gives tips for writing clear, idiomatic Go code. |
| 30 | It augments the <a href="/ref/spec">language specification</a>, |
| 31 | the <a href="//tour.golang.org/">Tour of Go</a>, |
| 32 | and <a href="/doc/code.html">How to Write Go Code</a>, |
| 33 | all of which you |
| 34 | should read first. |
| 35 | </p> |
| 36 | |
| 37 | <h3 id="examples">Examples</h3> |
| 38 | |
| 39 | <p> |
| 40 | The <a href="/src/">Go package sources</a> |
| 41 | are intended to serve not |
| 42 | only as the core library but also as examples of how to |
| 43 | use the language. |
| 44 | Moreover, many of the packages contain working, self-contained |
| 45 | executable examples you can run directly from the |
| 46 | <a href="//golang.org">golang.org</a> web site, such as |
| 47 | <a href="//golang.org/pkg/strings/#example_Map">this one</a> (if |
| 48 | necessary, click on the word "Example" to open it up). |
| 49 | If you have a question about how to approach a problem or how something |
| 50 | might be implemented, the documentation, code and examples in the |
| 51 | library can provide answers, ideas and |
| 52 | background. |
| 53 | </p> |
| 54 | |
| 55 | |
| 56 | <h2 id="formatting">Formatting</h2> |
| 57 | |
| 58 | <p> |
| 59 | Formatting issues are the most contentious |
| 60 | but the least consequential. |
| 61 | People can adapt to different formatting styles |
| 62 | but it's better if they don't have to, and |
| 63 | less time is devoted to the topic |
| 64 | if everyone adheres to the same style. |
| 65 | The problem is how to approach this Utopia without a long |
| 66 | prescriptive style guide. |
| 67 | </p> |
| 68 | |
| 69 | <p> |
| 70 | With Go we take an unusual |
| 71 | approach and let the machine |
| 72 | take care of most formatting issues. |
| 73 | The <code>gofmt</code> program |
| 74 | (also available as <code>go fmt</code>, which |
| 75 | operates at the package level rather than source file level) |
| 76 | reads a Go program |
| 77 | and emits the source in a standard style of indentation |
| 78 | and vertical alignment, retaining and if necessary |
| 79 | reformatting comments. |
| 80 | If you want to know how to handle some new layout |
| 81 | situation, run <code>gofmt</code>; if the answer doesn't |
| 82 | seem right, rearrange your program (or file a bug about <code>gofmt</code>), |
| 83 | don't work around it. |
| 84 | </p> |
| 85 | |
| 86 | <p> |
| 87 | As an example, there's no need to spend time lining up |
| 88 | the comments on the fields of a structure. |
| 89 | <code>Gofmt</code> will do that for you. Given the |
| 90 | declaration |
| 91 | </p> |
| 92 | |
| 93 | <pre> |
| 94 | type T struct { |
| 95 | name string // name of the object |
| 96 | value int // its value |
| 97 | } |
| 98 | </pre> |
| 99 | |
| 100 | <p> |
| 101 | <code>gofmt</code> will line up the columns: |
| 102 | </p> |
| 103 | |
| 104 | <pre> |
| 105 | type T struct { |
| 106 | name string // name of the object |
| 107 | value int // its value |
| 108 | } |
| 109 | </pre> |
| 110 | |
| 111 | <p> |
| 112 | All Go code in the standard packages has been formatted with <code>gofmt</code>. |
| 113 | </p> |
| 114 | |
| 115 | |
| 116 | <p> |
| 117 | Some formatting details remain. Very briefly: |
| 118 | </p> |
| 119 | |
| 120 | <dl> |
| 121 | <dt>Indentation</dt> |
| 122 | <dd>We use tabs for indentation and <code>gofmt</code> emits them by default. |
| 123 | Use spaces only if you must. |
| 124 | </dd> |
| 125 | <dt>Line length</dt> |
| 126 | <dd> |
| 127 | Go has no line length limit. Don't worry about overflowing a punched card. |
| 128 | If a line feels too long, wrap it and indent with an extra tab. |
| 129 | </dd> |
| 130 | <dt>Parentheses</dt> |
| 131 | <dd> |
| 132 | Go needs fewer parentheses than C and Java: control structures (<code>if</code>, |
| 133 | <code>for</code>, <code>switch</code>) do not have parentheses in |
| 134 | their syntax. |
| 135 | Also, the operator precedence hierarchy is shorter and clearer, so |
| 136 | <pre> |
| 137 | x<<8 + y<<16 |
| 138 | </pre> |
| 139 | means what the spacing implies, unlike in the other languages. |
| 140 | </dd> |
| 141 | </dl> |
| 142 | |
| 143 | <h2 id="commentary">Commentary</h2> |
| 144 | |
| 145 | <p> |
| 146 | Go provides C-style <code>/* */</code> block comments |
| 147 | and C++-style <code>//</code> line comments. |
| 148 | Line comments are the norm; |
| 149 | block comments appear mostly as package comments, but |
| 150 | are useful within an expression or to disable large swaths of code. |
| 151 | </p> |
| 152 | |
| 153 | <p> |
| 154 | The program—and web server—<code>godoc</code> processes |
| 155 | Go source files to extract documentation about the contents of the |
| 156 | package. |
| 157 | Comments that appear before top-level declarations, with no intervening newlines, |
| 158 | are extracted along with the declaration to serve as explanatory text for the item. |
| 159 | The nature and style of these comments determines the |
| 160 | quality of the documentation <code>godoc</code> produces. |
| 161 | </p> |
| 162 | |
| 163 | <p> |
| 164 | Every package should have a <i>package comment</i>, a block |
| 165 | comment preceding the package clause. |
| 166 | For multi-file packages, the package comment only needs to be |
| 167 | present in one file, and any one will do. |
| 168 | The package comment should introduce the package and |
| 169 | provide information relevant to the package as a whole. |
| 170 | It will appear first on the <code>godoc</code> page and |
| 171 | should set up the detailed documentation that follows. |
| 172 | </p> |
| 173 | |
| 174 | <pre> |
| 175 | /* |
| 176 | Package regexp implements a simple library for regular expressions. |
| 177 | |
| 178 | The syntax of the regular expressions accepted is: |
| 179 | |
| 180 | regexp: |
| 181 | concatenation { '|' concatenation } |
| 182 | concatenation: |
| 183 | { closure } |
| 184 | closure: |
| 185 | term [ '*' | '+' | '?' ] |
| 186 | term: |
| 187 | '^' |
| 188 | '$' |
| 189 | '.' |
| 190 | character |
| 191 | '[' [ '^' ] character-ranges ']' |
| 192 | '(' regexp ')' |
| 193 | */ |
| 194 | package regexp |
| 195 | </pre> |
| 196 | |
| 197 | <p> |
| 198 | If the package is simple, the package comment can be brief. |
| 199 | </p> |
| 200 | |
| 201 | <pre> |
| 202 | // Package path implements utility routines for |
| 203 | // manipulating slash-separated filename paths. |
| 204 | </pre> |
| 205 | |
| 206 | <p> |
| 207 | Comments do not need extra formatting such as banners of stars. |
| 208 | The generated output may not even be presented in a fixed-width font, so don't depend |
| 209 | on spacing for alignment—<code>godoc</code>, like <code>gofmt</code>, |
| 210 | takes care of that. |
| 211 | The comments are uninterpreted plain text, so HTML and other |
| 212 | annotations such as <code>_this_</code> will reproduce <i>verbatim</i> and should |
| 213 | not be used. |
| 214 | One adjustment <code>godoc</code> does do is to display indented |
| 215 | text in a fixed-width font, suitable for program snippets. |
| 216 | The package comment for the |
| 217 | <a href="/pkg/fmt/"><code>fmt</code> package</a> uses this to good effect. |
| 218 | </p> |
| 219 | |
| 220 | <p> |
| 221 | Depending on the context, <code>godoc</code> might not even |
| 222 | reformat comments, so make sure they look good straight up: |
| 223 | use correct spelling, punctuation, and sentence structure, |
| 224 | fold long lines, and so on. |
| 225 | </p> |
| 226 | |
| 227 | <p> |
| 228 | Inside a package, any comment immediately preceding a top-level declaration |
| 229 | serves as a <i>doc comment</i> for that declaration. |
| 230 | Every exported (capitalized) name in a program should |
| 231 | have a doc comment. |
| 232 | </p> |
| 233 | |
| 234 | <p> |
| 235 | Doc comments work best as complete sentences, which allow |
| 236 | a wide variety of automated presentations. |
| 237 | The first sentence should be a one-sentence summary that |
| 238 | starts with the name being declared. |
| 239 | </p> |
| 240 | |
| 241 | <pre> |
| 242 | // Compile parses a regular expression and returns, if successful, a Regexp |
| 243 | // object that can be used to match against text. |
| 244 | func Compile(str string) (regexp *Regexp, err error) { |
| 245 | </pre> |
| 246 | |
| 247 | <p> |
| 248 | If the name always begins the comment, the output of <code>godoc</code> |
| 249 | can usefully be run through <code>grep</code>. |
| 250 | Imagine you couldn't remember the name "Compile" but were looking for |
| 251 | the parsing function for regular expressions, so you ran |
| 252 | the command, |
| 253 | </p> |
| 254 | |
| 255 | <pre> |
| 256 | $ godoc regexp | grep parse |
| 257 | </pre> |
| 258 | |
| 259 | <p> |
| 260 | If all the doc comments in the package began, "This function...", <code>grep</code> |
| 261 | wouldn't help you remember the name. But because the package starts each |
| 262 | doc comment with the name, you'd see something like this, |
| 263 | which recalls the word you're looking for. |
| 264 | </p> |
| 265 | |
| 266 | <pre> |
| 267 | $ godoc regexp | grep parse |
| 268 | Compile parses a regular expression and returns, if successful, a Regexp |
| 269 | parsed. It simplifies safe initialization of global variables holding |
| 270 | cannot be parsed. It simplifies safe initialization of global variables |
| 271 | $ |
| 272 | </pre> |
| 273 | |
| 274 | <p> |
| 275 | Go's declaration syntax allows grouping of declarations. |
| 276 | A single doc comment can introduce a group of related constants or variables. |
| 277 | Since the whole declaration is presented, such a comment can often be perfunctory. |
| 278 | </p> |
| 279 | |
| 280 | <pre> |
| 281 | // Error codes returned by failures to parse an expression. |
| 282 | var ( |
| 283 | ErrInternal = errors.New("regexp: internal error") |
| 284 | ErrUnmatchedLpar = errors.New("regexp: unmatched '('") |
| 285 | ErrUnmatchedRpar = errors.New("regexp: unmatched ')'") |
| 286 | ... |
| 287 | ) |
| 288 | </pre> |
| 289 | |
| 290 | <p> |
| 291 | Grouping can also indicate relationships between items, |
| 292 | such as the fact that a set of variables is protected by a mutex. |
| 293 | </p> |
| 294 | |
| 295 | <pre> |
| 296 | var ( |
| 297 | countLock sync.Mutex |
| 298 | inputCount uint32 |
| 299 | outputCount uint32 |
| 300 | errorCount uint32 |
| 301 | ) |
| 302 | </pre> |
| 303 | |
| 304 | <h2 id="names">Names</h2> |
| 305 | |
| 306 | <p> |
| 307 | Names are as important in Go as in any other language. |
| 308 | They even have semantic effect: |
| 309 | the visibility of a name outside a package is determined by whether its |
| 310 | first character is upper case. |
| 311 | It's therefore worth spending a little time talking about naming conventions |
| 312 | in Go programs. |
| 313 | </p> |
| 314 | |
| 315 | |
| 316 | <h3 id="package-names">Package names</h3> |
| 317 | |
| 318 | <p> |
| 319 | When a package is imported, the package name becomes an accessor for the |
| 320 | contents. After |
| 321 | </p> |
| 322 | |
| 323 | <pre> |
| 324 | import "bytes" |
| 325 | </pre> |
| 326 | |
| 327 | <p> |
| 328 | the importing package can talk about <code>bytes.Buffer</code>. It's |
| 329 | helpful if everyone using the package can use the same name to refer to |
| 330 | its contents, which implies that the package name should be good: |
| 331 | short, concise, evocative. By convention, packages are given |
| 332 | lower case, single-word names; there should be no need for underscores |
| 333 | or mixedCaps. |
| 334 | Err on the side of brevity, since everyone using your |
| 335 | package will be typing that name. |
| 336 | And don't worry about collisions <i>a priori</i>. |
| 337 | The package name is only the default name for imports; it need not be unique |
| 338 | across all source code, and in the rare case of a collision the |
| 339 | importing package can choose a different name to use locally. |
| 340 | In any case, confusion is rare because the file name in the import |
| 341 | determines just which package is being used. |
| 342 | </p> |
| 343 | |
| 344 | <p> |
| 345 | Another convention is that the package name is the base name of |
| 346 | its source directory; |
| 347 | the package in <code>src/encoding/base64</code> |
| 348 | is imported as <code>"encoding/base64"</code> but has name <code>base64</code>, |
| 349 | not <code>encoding_base64</code> and not <code>encodingBase64</code>. |
| 350 | </p> |
| 351 | |
| 352 | <p> |
| 353 | The importer of a package will use the name to refer to its contents, |
| 354 | so exported names in the package can use that fact |
| 355 | to avoid stutter. |
| 356 | (Don't use the <code>import .</code> notation, which can simplify |
| 357 | tests that must run outside the package they are testing, but should otherwise be avoided.) |
| 358 | For instance, the buffered reader type in the <code>bufio</code> package is called <code>Reader</code>, |
| 359 | not <code>BufReader</code>, because users see it as <code>bufio.Reader</code>, |
| 360 | which is a clear, concise name. |
| 361 | Moreover, |
| 362 | because imported entities are always addressed with their package name, <code>bufio.Reader</code> |
| 363 | does not conflict with <code>io.Reader</code>. |
| 364 | Similarly, the function to make new instances of <code>ring.Ring</code>—which |
| 365 | is the definition of a <em>constructor</em> in Go—would |
| 366 | normally be called <code>NewRing</code>, but since |
| 367 | <code>Ring</code> is the only type exported by the package, and since the |
| 368 | package is called <code>ring</code>, it's called just <code>New</code>, |
| 369 | which clients of the package see as <code>ring.New</code>. |
| 370 | Use the package structure to help you choose good names. |
| 371 | </p> |
| 372 | |
| 373 | <p> |
| 374 | Another short example is <code>once.Do</code>; |
| 375 | <code>once.Do(setup)</code> reads well and would not be improved by |
| 376 | writing <code>once.DoOrWaitUntilDone(setup)</code>. |
| 377 | Long names don't automatically make things more readable. |
| 378 | A helpful doc comment can often be more valuable than an extra long name. |
| 379 | </p> |
| 380 | |
| 381 | <h3 id="Getters">Getters</h3> |
| 382 | |
| 383 | <p> |
| 384 | Go doesn't provide automatic support for getters and setters. |
| 385 | There's nothing wrong with providing getters and setters yourself, |
| 386 | and it's often appropriate to do so, but it's neither idiomatic nor necessary |
| 387 | to put <code>Get</code> into the getter's name. If you have a field called |
| 388 | <code>owner</code> (lower case, unexported), the getter method should be |
| 389 | called <code>Owner</code> (upper case, exported), not <code>GetOwner</code>. |
| 390 | The use of upper-case names for export provides the hook to discriminate |
| 391 | the field from the method. |
| 392 | A setter function, if needed, will likely be called <code>SetOwner</code>. |
| 393 | Both names read well in practice: |
| 394 | </p> |
| 395 | <pre> |
| 396 | owner := obj.Owner() |
| 397 | if owner != user { |
| 398 | obj.SetOwner(user) |
| 399 | } |
| 400 | </pre> |
| 401 | |
| 402 | <h3 id="interface-names">Interface names</h3> |
| 403 | |
| 404 | <p> |
| 405 | By convention, one-method interfaces are named by |
| 406 | the method name plus an -er suffix or similar modification |
| 407 | to construct an agent noun: <code>Reader</code>, |
| 408 | <code>Writer</code>, <code>Formatter</code>, |
| 409 | <code>CloseNotifier</code> etc. |
| 410 | </p> |
| 411 | |
| 412 | <p> |
| 413 | There are a number of such names and it's productive to honor them and the function |
| 414 | names they capture. |
| 415 | <code>Read</code>, <code>Write</code>, <code>Close</code>, <code>Flush</code>, |
| 416 | <code>String</code> and so on have |
| 417 | canonical signatures and meanings. To avoid confusion, |
| 418 | don't give your method one of those names unless it |
| 419 | has the same signature and meaning. |
| 420 | Conversely, if your type implements a method with the |
| 421 | same meaning as a method on a well-known type, |
| 422 | give it the same name and signature; |
| 423 | call your string-converter method <code>String</code> not <code>ToString</code>. |
| 424 | </p> |
| 425 | |
| 426 | <h3 id="mixed-caps">MixedCaps</h3> |
| 427 | |
| 428 | <p> |
| 429 | Finally, the convention in Go is to use <code>MixedCaps</code> |
| 430 | or <code>mixedCaps</code> rather than underscores to write |
| 431 | multiword names. |
| 432 | </p> |
| 433 | |
| 434 | <h2 id="semicolons">Semicolons</h2> |
| 435 | |
| 436 | <p> |
| 437 | Like C, Go's formal grammar uses semicolons to terminate statements, |
| 438 | but unlike in C, those semicolons do not appear in the source. |
| 439 | Instead the lexer uses a simple rule to insert semicolons automatically |
| 440 | as it scans, so the input text is mostly free of them. |
| 441 | </p> |
| 442 | |
| 443 | <p> |
| 444 | The rule is this. If the last token before a newline is an identifier |
| 445 | (which includes words like <code>int</code> and <code>float64</code>), |
| 446 | a basic literal such as a number or string constant, or one of the |
| 447 | tokens |
| 448 | </p> |
| 449 | <pre> |
| 450 | break continue fallthrough return ++ -- ) } |
| 451 | </pre> |
| 452 | <p> |
| 453 | the lexer always inserts a semicolon after the token. |
| 454 | This could be summarized as, “if the newline comes |
| 455 | after a token that could end a statement, insert a semicolon”. |
| 456 | </p> |
| 457 | |
| 458 | <p> |
| 459 | A semicolon can also be omitted immediately before a closing brace, |
| 460 | so a statement such as |
| 461 | </p> |
| 462 | <pre> |
| 463 | go func() { for { dst <- <-src } }() |
| 464 | </pre> |
| 465 | <p> |
| 466 | needs no semicolons. |
| 467 | Idiomatic Go programs have semicolons only in places such as |
| 468 | <code>for</code> loop clauses, to separate the initializer, condition, and |
| 469 | continuation elements. They are also necessary to separate multiple |
| 470 | statements on a line, should you write code that way. |
| 471 | </p> |
| 472 | |
| 473 | <p> |
| 474 | One consequence of the semicolon insertion rules |
| 475 | is that you cannot put the opening brace of a |
| 476 | control structure (<code>if</code>, <code>for</code>, <code>switch</code>, |
| 477 | or <code>select</code>) on the next line. If you do, a semicolon |
| 478 | will be inserted before the brace, which could cause unwanted |
| 479 | effects. Write them like this |
| 480 | </p> |
| 481 | |
| 482 | <pre> |
| 483 | if i < f() { |
| 484 | g() |
| 485 | } |
| 486 | </pre> |
| 487 | <p> |
| 488 | not like this |
| 489 | </p> |
| 490 | <pre> |
| 491 | if i < f() // wrong! |
| 492 | { // wrong! |
| 493 | g() |
| 494 | } |
| 495 | </pre> |
| 496 | |
| 497 | |
| 498 | <h2 id="control-structures">Control structures</h2> |
| 499 | |
| 500 | <p> |
| 501 | The control structures of Go are related to those of C but differ |
| 502 | in important ways. |
| 503 | There is no <code>do</code> or <code>while</code> loop, only a |
| 504 | slightly generalized |
| 505 | <code>for</code>; |
| 506 | <code>switch</code> is more flexible; |
| 507 | <code>if</code> and <code>switch</code> accept an optional |
| 508 | initialization statement like that of <code>for</code>; |
| 509 | <code>break</code> and <code>continue</code> statements |
| 510 | take an optional label to identify what to break or continue; |
| 511 | and there are new control structures including a type switch and a |
| 512 | multiway communications multiplexer, <code>select</code>. |
| 513 | The syntax is also slightly different: |
| 514 | there are no parentheses |
| 515 | and the bodies must always be brace-delimited. |
| 516 | </p> |
| 517 | |
| 518 | <h3 id="if">If</h3> |
| 519 | |
| 520 | <p> |
| 521 | In Go a simple <code>if</code> looks like this: |
| 522 | </p> |
| 523 | <pre> |
| 524 | if x > 0 { |
| 525 | return y |
| 526 | } |
| 527 | </pre> |
| 528 | |
| 529 | <p> |
| 530 | Mandatory braces encourage writing simple <code>if</code> statements |
| 531 | on multiple lines. It's good style to do so anyway, |
| 532 | especially when the body contains a control statement such as a |
| 533 | <code>return</code> or <code>break</code>. |
| 534 | </p> |
| 535 | |
| 536 | <p> |
| 537 | Since <code>if</code> and <code>switch</code> accept an initialization |
| 538 | statement, it's common to see one used to set up a local variable. |
| 539 | </p> |
| 540 | |
| 541 | <pre> |
| 542 | if err := file.Chmod(0664); err != nil { |
| 543 | log.Print(err) |
| 544 | return err |
| 545 | } |
| 546 | </pre> |
| 547 | |
| 548 | <p id="else"> |
| 549 | In the Go libraries, you'll find that |
| 550 | when an <code>if</code> statement doesn't flow into the next statement—that is, |
| 551 | the body ends in <code>break</code>, <code>continue</code>, |
| 552 | <code>goto</code>, or <code>return</code>—the unnecessary |
| 553 | <code>else</code> is omitted. |
| 554 | </p> |
| 555 | |
| 556 | <pre> |
| 557 | f, err := os.Open(name) |
| 558 | if err != nil { |
| 559 | return err |
| 560 | } |
| 561 | codeUsing(f) |
| 562 | </pre> |
| 563 | |
| 564 | <p> |
| 565 | This is an example of a common situation where code must guard against a |
| 566 | sequence of error conditions. The code reads well if the |
| 567 | successful flow of control runs down the page, eliminating error cases |
| 568 | as they arise. Since error cases tend to end in <code>return</code> |
| 569 | statements, the resulting code needs no <code>else</code> statements. |
| 570 | </p> |
| 571 | |
| 572 | <pre> |
| 573 | f, err := os.Open(name) |
| 574 | if err != nil { |
| 575 | return err |
| 576 | } |
| 577 | d, err := f.Stat() |
| 578 | if err != nil { |
| 579 | f.Close() |
| 580 | return err |
| 581 | } |
| 582 | codeUsing(f, d) |
| 583 | </pre> |
| 584 | |
| 585 | |
| 586 | <h3 id="redeclaration">Redeclaration and reassignment</h3> |
| 587 | |
| 588 | <p> |
| 589 | An aside: The last example in the previous section demonstrates a detail of how the |
| 590 | <code>:=</code> short declaration form works. |
| 591 | The declaration that calls <code>os.Open</code> reads, |
| 592 | </p> |
| 593 | |
| 594 | <pre> |
| 595 | f, err := os.Open(name) |
| 596 | </pre> |
| 597 | |
| 598 | <p> |
| 599 | This statement declares two variables, <code>f</code> and <code>err</code>. |
| 600 | A few lines later, the call to <code>f.Stat</code> reads, |
| 601 | </p> |
| 602 | |
| 603 | <pre> |
| 604 | d, err := f.Stat() |
| 605 | </pre> |
| 606 | |
| 607 | <p> |
| 608 | which looks as if it declares <code>d</code> and <code>err</code>. |
| 609 | Notice, though, that <code>err</code> appears in both statements. |
| 610 | This duplication is legal: <code>err</code> is declared by the first statement, |
| 611 | but only <em>re-assigned</em> in the second. |
| 612 | This means that the call to <code>f.Stat</code> uses the existing |
| 613 | <code>err</code> variable declared above, and just gives it a new value. |
| 614 | </p> |
| 615 | |
| 616 | <p> |
| 617 | In a <code>:=</code> declaration a variable <code>v</code> may appear even |
| 618 | if it has already been declared, provided: |
| 619 | </p> |
| 620 | |
| 621 | <ul> |
| 622 | <li>this declaration is in the same scope as the existing declaration of <code>v</code> |
| 623 | (if <code>v</code> is already declared in an outer scope, the declaration will create a new variable §),</li> |
| 624 | <li>the corresponding value in the initialization is assignable to <code>v</code>, and</li> |
| 625 | <li>there is at least one other variable in the declaration that is being declared anew.</li> |
| 626 | </ul> |
| 627 | |
| 628 | <p> |
| 629 | This unusual property is pure pragmatism, |
| 630 | making it easy to use a single <code>err</code> value, for example, |
| 631 | in a long <code>if-else</code> chain. |
| 632 | You'll see it used often. |
| 633 | </p> |
| 634 | |
| 635 | <p> |
| 636 | § It's worth noting here that in Go the scope of function parameters and return values |
| 637 | is the same as the function body, even though they appear lexically outside the braces |
| 638 | that enclose the body. |
| 639 | </p> |
| 640 | |
| 641 | <h3 id="for">For</h3> |
| 642 | |
| 643 | <p> |
| 644 | The Go <code>for</code> loop is similar to—but not the same as—C's. |
| 645 | It unifies <code>for</code> |
| 646 | and <code>while</code> and there is no <code>do-while</code>. |
| 647 | There are three forms, only one of which has semicolons. |
| 648 | </p> |
| 649 | <pre> |
| 650 | // Like a C for |
| 651 | for init; condition; post { } |
| 652 | |
| 653 | // Like a C while |
| 654 | for condition { } |
| 655 | |
| 656 | // Like a C for(;;) |
| 657 | for { } |
| 658 | </pre> |
| 659 | |
| 660 | <p> |
| 661 | Short declarations make it easy to declare the index variable right in the loop. |
| 662 | </p> |
| 663 | <pre> |
| 664 | sum := 0 |
| 665 | for i := 0; i < 10; i++ { |
| 666 | sum += i |
| 667 | } |
| 668 | </pre> |
| 669 | |
| 670 | <p> |
| 671 | If you're looping over an array, slice, string, or map, |
| 672 | or reading from a channel, a <code>range</code> clause can |
| 673 | manage the loop. |
| 674 | </p> |
| 675 | <pre> |
| 676 | for key, value := range oldMap { |
| 677 | newMap[key] = value |
| 678 | } |
| 679 | </pre> |
| 680 | |
| 681 | <p> |
| 682 | If you only need the first item in the range (the key or index), drop the second: |
| 683 | </p> |
| 684 | <pre> |
| 685 | for key := range m { |
| 686 | if key.expired() { |
| 687 | delete(m, key) |
| 688 | } |
| 689 | } |
| 690 | </pre> |
| 691 | |
| 692 | <p> |
| 693 | If you only need the second item in the range (the value), use the <em>blank identifier</em>, an underscore, to discard the first: |
| 694 | </p> |
| 695 | <pre> |
| 696 | sum := 0 |
| 697 | for _, value := range array { |
| 698 | sum += value |
| 699 | } |
| 700 | </pre> |
| 701 | |
| 702 | <p> |
| 703 | The blank identifier has many uses, as described in <a href="#blank">a later section</a>. |
| 704 | </p> |
| 705 | |
| 706 | <p> |
| 707 | For strings, the <code>range</code> does more work for you, breaking out individual |
| 708 | Unicode code points by parsing the UTF-8. |
| 709 | Erroneous encodings consume one byte and produce the |
| 710 | replacement rune U+FFFD. |
| 711 | (The name (with associated builtin type) <code>rune</code> is Go terminology for a |
| 712 | single Unicode code point. |
| 713 | See <a href="/ref/spec#Rune_literals">the language specification</a> |
| 714 | for details.) |
| 715 | The loop |
| 716 | </p> |
| 717 | <pre> |
| 718 | for pos, char := range "日本\x80語" { // \x80 is an illegal UTF-8 encoding |
| 719 | fmt.Printf("character %#U starts at byte position %d\n", char, pos) |
| 720 | } |
| 721 | </pre> |
| 722 | <p> |
| 723 | prints |
| 724 | </p> |
| 725 | <pre> |
| 726 | character U+65E5 '日' starts at byte position 0 |
| 727 | character U+672C '本' starts at byte position 3 |
| 728 | character U+FFFD '�' starts at byte position 6 |
| 729 | character U+8A9E '語' starts at byte position 7 |
| 730 | </pre> |
| 731 | |
| 732 | <p> |
| 733 | Finally, Go has no comma operator and <code>++</code> and <code>--</code> |
| 734 | are statements not expressions. |
| 735 | Thus if you want to run multiple variables in a <code>for</code> |
| 736 | you should use parallel assignment (although that precludes <code>++</code> and <code>--</code>). |
| 737 | </p> |
| 738 | <pre> |
| 739 | // Reverse a |
| 740 | for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 { |
| 741 | a[i], a[j] = a[j], a[i] |
| 742 | } |
| 743 | </pre> |
| 744 | |
| 745 | <h3 id="switch">Switch</h3> |
| 746 | |
| 747 | <p> |
| 748 | Go's <code>switch</code> is more general than C's. |
| 749 | The expressions need not be constants or even integers, |
| 750 | the cases are evaluated top to bottom until a match is found, |
| 751 | and if the <code>switch</code> has no expression it switches on |
| 752 | <code>true</code>. |
| 753 | It's therefore possible—and idiomatic—to write an |
| 754 | <code>if</code>-<code>else</code>-<code>if</code>-<code>else</code> |
| 755 | chain as a <code>switch</code>. |
| 756 | </p> |
| 757 | |
| 758 | <pre> |
| 759 | func unhex(c byte) byte { |
| 760 | switch { |
| 761 | case '0' <= c && c <= '9': |
| 762 | return c - '0' |
| 763 | case 'a' <= c && c <= 'f': |
| 764 | return c - 'a' + 10 |
| 765 | case 'A' <= c && c <= 'F': |
| 766 | return c - 'A' + 10 |
| 767 | } |
| 768 | return 0 |
| 769 | } |
| 770 | </pre> |
| 771 | |
| 772 | <p> |
| 773 | There is no automatic fall through, but cases can be presented |
| 774 | in comma-separated lists. |
| 775 | </p> |
| 776 | <pre> |
| 777 | func shouldEscape(c byte) bool { |
| 778 | switch c { |
| 779 | case ' ', '?', '&', '=', '#', '+', '%': |
| 780 | return true |
| 781 | } |
| 782 | return false |
| 783 | } |
| 784 | </pre> |
| 785 | |
| 786 | <p> |
| 787 | Although they are not nearly as common in Go as some other C-like |
| 788 | languages, <code>break</code> statements can be used to terminate |
| 789 | a <code>switch</code> early. |
| 790 | Sometimes, though, it's necessary to break out of a surrounding loop, |
| 791 | not the switch, and in Go that can be accomplished by putting a label |
| 792 | on the loop and "breaking" to that label. |
| 793 | This example shows both uses. |
| 794 | </p> |
| 795 | |
| 796 | <pre> |
| 797 | Loop: |
| 798 | for n := 0; n < len(src); n += size { |
| 799 | switch { |
| 800 | case src[n] < sizeOne: |
| 801 | if validateOnly { |
| 802 | break |
| 803 | } |
| 804 | size = 1 |
| 805 | update(src[n]) |
| 806 | |
| 807 | case src[n] < sizeTwo: |
| 808 | if n+1 >= len(src) { |
| 809 | err = errShortInput |
| 810 | break Loop |
| 811 | } |
| 812 | if validateOnly { |
| 813 | break |
| 814 | } |
| 815 | size = 2 |
| 816 | update(src[n] + src[n+1]<<shift) |
| 817 | } |
| 818 | } |
| 819 | </pre> |
| 820 | |
| 821 | <p> |
| 822 | Of course, the <code>continue</code> statement also accepts an optional label |
| 823 | but it applies only to loops. |
| 824 | </p> |
| 825 | |
| 826 | <p> |
| 827 | To close this section, here's a comparison routine for byte slices that uses two |
| 828 | <code>switch</code> statements: |
| 829 | </p> |
| 830 | <pre> |
| 831 | // Compare returns an integer comparing the two byte slices, |
| 832 | // lexicographically. |
| 833 | // The result will be 0 if a == b, -1 if a < b, and +1 if a > b |
| 834 | func Compare(a, b []byte) int { |
| 835 | for i := 0; i < len(a) && i < len(b); i++ { |
| 836 | switch { |
| 837 | case a[i] > b[i]: |
| 838 | return 1 |
| 839 | case a[i] < b[i]: |
| 840 | return -1 |
| 841 | } |
| 842 | } |
| 843 | switch { |
| 844 | case len(a) > len(b): |
| 845 | return 1 |
| 846 | case len(a) < len(b): |
| 847 | return -1 |
| 848 | } |
| 849 | return 0 |
| 850 | } |
| 851 | </pre> |
| 852 | |
| 853 | <h3 id="type_switch">Type switch</h3> |
| 854 | |
| 855 | <p> |
| 856 | A switch can also be used to discover the dynamic type of an interface |
| 857 | variable. Such a <em>type switch</em> uses the syntax of a type |
| 858 | assertion with the keyword <code>type</code> inside the parentheses. |
| 859 | If the switch declares a variable in the expression, the variable will |
| 860 | have the corresponding type in each clause. |
| 861 | It's also idiomatic to reuse the name in such cases, in effect declaring |
| 862 | a new variable with the same name but a different type in each case. |
| 863 | </p> |
| 864 | <pre> |
| 865 | var t interface{} |
| 866 | t = functionOfSomeType() |
| 867 | switch t := t.(type) { |
| 868 | default: |
| 869 | fmt.Printf("unexpected type %T", t) // %T prints whatever type t has |
| 870 | case bool: |
| 871 | fmt.Printf("boolean %t\n", t) // t has type bool |
| 872 | case int: |
| 873 | fmt.Printf("integer %d\n", t) // t has type int |
| 874 | case *bool: |
| 875 | fmt.Printf("pointer to boolean %t\n", *t) // t has type *bool |
| 876 | case *int: |
| 877 | fmt.Printf("pointer to integer %d\n", *t) // t has type *int |
| 878 | } |
| 879 | </pre> |
| 880 | |
| 881 | <h2 id="functions">Functions</h2> |
| 882 | |
| 883 | <h3 id="multiple-returns">Multiple return values</h3> |
| 884 | |
| 885 | <p> |
| 886 | One of Go's unusual features is that functions and methods |
| 887 | can return multiple values. This form can be used to |
| 888 | improve on a couple of clumsy idioms in C programs: in-band |
| 889 | error returns such as <code>-1</code> for <code>EOF</code> |
| 890 | and modifying an argument passed by address. |
| 891 | </p> |
| 892 | |
| 893 | <p> |
| 894 | In C, a write error is signaled by a negative count with the |
| 895 | error code secreted away in a volatile location. |
| 896 | In Go, <code>Write</code> |
| 897 | can return a count <i>and</i> an error: “Yes, you wrote some |
| 898 | bytes but not all of them because you filled the device”. |
| 899 | The signature of the <code>Write</code> method on files from |
| 900 | package <code>os</code> is: |
| 901 | </p> |
| 902 | |
| 903 | <pre> |
| 904 | func (file *File) Write(b []byte) (n int, err error) |
| 905 | </pre> |
| 906 | |
| 907 | <p> |
| 908 | and as the documentation says, it returns the number of bytes |
| 909 | written and a non-nil <code>error</code> when <code>n</code> |
| 910 | <code>!=</code> <code>len(b)</code>. |
| 911 | This is a common style; see the section on error handling for more examples. |
| 912 | </p> |
| 913 | |
| 914 | <p> |
| 915 | A similar approach obviates the need to pass a pointer to a return |
| 916 | value to simulate a reference parameter. |
| 917 | Here's a simple-minded function to |
| 918 | grab a number from a position in a byte slice, returning the number |
| 919 | and the next position. |
| 920 | </p> |
| 921 | |
| 922 | <pre> |
| 923 | func nextInt(b []byte, i int) (int, int) { |
| 924 | for ; i < len(b) && !isDigit(b[i]); i++ { |
| 925 | } |
| 926 | x := 0 |
| 927 | for ; i < len(b) && isDigit(b[i]); i++ { |
| 928 | x = x*10 + int(b[i]) - '0' |
| 929 | } |
| 930 | return x, i |
| 931 | } |
| 932 | </pre> |
| 933 | |
| 934 | <p> |
| 935 | You could use it to scan the numbers in an input slice <code>b</code> like this: |
| 936 | </p> |
| 937 | |
| 938 | <pre> |
| 939 | for i := 0; i < len(b); { |
| 940 | x, i = nextInt(b, i) |
| 941 | fmt.Println(x) |
| 942 | } |
| 943 | </pre> |
| 944 | |
| 945 | <h3 id="named-results">Named result parameters</h3> |
| 946 | |
| 947 | <p> |
| 948 | The return or result "parameters" of a Go function can be given names and |
| 949 | used as regular variables, just like the incoming parameters. |
| 950 | When named, they are initialized to the zero values for their types when |
| 951 | the function begins; if the function executes a <code>return</code> statement |
| 952 | with no arguments, the current values of the result parameters are |
| 953 | used as the returned values. |
| 954 | </p> |
| 955 | |
| 956 | <p> |
| 957 | The names are not mandatory but they can make code shorter and clearer: |
| 958 | they're documentation. |
| 959 | If we name the results of <code>nextInt</code> it becomes |
| 960 | obvious which returned <code>int</code> |
| 961 | is which. |
| 962 | </p> |
| 963 | |
| 964 | <pre> |
| 965 | func nextInt(b []byte, pos int) (value, nextPos int) { |
| 966 | </pre> |
| 967 | |
| 968 | <p> |
| 969 | Because named results are initialized and tied to an unadorned return, they can simplify |
| 970 | as well as clarify. Here's a version |
| 971 | of <code>io.ReadFull</code> that uses them well: |
| 972 | </p> |
| 973 | |
| 974 | <pre> |
| 975 | func ReadFull(r Reader, buf []byte) (n int, err error) { |
| 976 | for len(buf) > 0 && err == nil { |
| 977 | var nr int |
| 978 | nr, err = r.Read(buf) |
| 979 | n += nr |
| 980 | buf = buf[nr:] |
| 981 | } |
| 982 | return |
| 983 | } |
| 984 | </pre> |
| 985 | |
| 986 | <h3 id="defer">Defer</h3> |
| 987 | |
| 988 | <p> |
| 989 | Go's <code>defer</code> statement schedules a function call (the |
| 990 | <i>deferred</i> function) to be run immediately before the function |
| 991 | executing the <code>defer</code> returns. It's an unusual but |
| 992 | effective way to deal with situations such as resources that must be |
| 993 | released regardless of which path a function takes to return. The |
| 994 | canonical examples are unlocking a mutex or closing a file. |
| 995 | </p> |
| 996 | |
| 997 | <pre> |
| 998 | // Contents returns the file's contents as a string. |
| 999 | func Contents(filename string) (string, error) { |
| 1000 | f, err := os.Open(filename) |
| 1001 | if err != nil { |
| 1002 | return "", err |
| 1003 | } |
| 1004 | defer f.Close() // f.Close will run when we're finished. |
| 1005 | |
| 1006 | var result []byte |
| 1007 | buf := make([]byte, 100) |
| 1008 | for { |
| 1009 | n, err := f.Read(buf[0:]) |
| 1010 | result = append(result, buf[0:n]...) // append is discussed later. |
| 1011 | if err != nil { |
| 1012 | if err == io.EOF { |
| 1013 | break |
| 1014 | } |
| 1015 | return "", err // f will be closed if we return here. |
| 1016 | } |
| 1017 | } |
| 1018 | return string(result), nil // f will be closed if we return here. |
| 1019 | } |
| 1020 | </pre> |
| 1021 | |
| 1022 | <p> |
| 1023 | Deferring a call to a function such as <code>Close</code> has two advantages. First, it |
| 1024 | guarantees that you will never forget to close the file, a mistake |
| 1025 | that's easy to make if you later edit the function to add a new return |
| 1026 | path. Second, it means that the close sits near the open, |
| 1027 | which is much clearer than placing it at the end of the function. |
| 1028 | </p> |
| 1029 | |
| 1030 | <p> |
| 1031 | The arguments to the deferred function (which include the receiver if |
| 1032 | the function is a method) are evaluated when the <i>defer</i> |
| 1033 | executes, not when the <i>call</i> executes. Besides avoiding worries |
| 1034 | about variables changing values as the function executes, this means |
| 1035 | that a single deferred call site can defer multiple function |
| 1036 | executions. Here's a silly example. |
| 1037 | </p> |
| 1038 | |
| 1039 | <pre> |
| 1040 | for i := 0; i < 5; i++ { |
| 1041 | defer fmt.Printf("%d ", i) |
| 1042 | } |
| 1043 | </pre> |
| 1044 | |
| 1045 | <p> |
| 1046 | Deferred functions are executed in LIFO order, so this code will cause |
| 1047 | <code>4 3 2 1 0</code> to be printed when the function returns. A |
| 1048 | more plausible example is a simple way to trace function execution |
| 1049 | through the program. We could write a couple of simple tracing |
| 1050 | routines like this: |
| 1051 | </p> |
| 1052 | |
| 1053 | <pre> |
| 1054 | func trace(s string) { fmt.Println("entering:", s) } |
| 1055 | func untrace(s string) { fmt.Println("leaving:", s) } |
| 1056 | |
| 1057 | // Use them like this: |
| 1058 | func a() { |
| 1059 | trace("a") |
| 1060 | defer untrace("a") |
| 1061 | // do something.... |
| 1062 | } |
| 1063 | </pre> |
| 1064 | |
| 1065 | <p> |
| 1066 | We can do better by exploiting the fact that arguments to deferred |
| 1067 | functions are evaluated when the <code>defer</code> executes. The |
| 1068 | tracing routine can set up the argument to the untracing routine. |
| 1069 | This example: |
| 1070 | </p> |
| 1071 | |
| 1072 | <pre> |
| 1073 | func trace(s string) string { |
| 1074 | fmt.Println("entering:", s) |
| 1075 | return s |
| 1076 | } |
| 1077 | |
| 1078 | func un(s string) { |
| 1079 | fmt.Println("leaving:", s) |
| 1080 | } |
| 1081 | |
| 1082 | func a() { |
| 1083 | defer un(trace("a")) |
| 1084 | fmt.Println("in a") |
| 1085 | } |
| 1086 | |
| 1087 | func b() { |
| 1088 | defer un(trace("b")) |
| 1089 | fmt.Println("in b") |
| 1090 | a() |
| 1091 | } |
| 1092 | |
| 1093 | func main() { |
| 1094 | b() |
| 1095 | } |
| 1096 | </pre> |
| 1097 | |
| 1098 | <p> |
| 1099 | prints |
| 1100 | </p> |
| 1101 | |
| 1102 | <pre> |
| 1103 | entering: b |
| 1104 | in b |
| 1105 | entering: a |
| 1106 | in a |
| 1107 | leaving: a |
| 1108 | leaving: b |
| 1109 | </pre> |
| 1110 | |
| 1111 | <p> |
| 1112 | For programmers accustomed to block-level resource management from |
| 1113 | other languages, <code>defer</code> may seem peculiar, but its most |
| 1114 | interesting and powerful applications come precisely from the fact |
| 1115 | that it's not block-based but function-based. In the section on |
| 1116 | <code>panic</code> and <code>recover</code> we'll see another |
| 1117 | example of its possibilities. |
| 1118 | </p> |
| 1119 | |
| 1120 | <h2 id="data">Data</h2> |
| 1121 | |
| 1122 | <h3 id="allocation_new">Allocation with <code>new</code></h3> |
| 1123 | |
| 1124 | <p> |
| 1125 | Go has two allocation primitives, the built-in functions |
| 1126 | <code>new</code> and <code>make</code>. |
| 1127 | They do different things and apply to different types, which can be confusing, |
| 1128 | but the rules are simple. |
| 1129 | Let's talk about <code>new</code> first. |
| 1130 | It's a built-in function that allocates memory, but unlike its namesakes |
| 1131 | in some other languages it does not <em>initialize</em> the memory, |
| 1132 | it only <em>zeros</em> it. |
| 1133 | That is, |
| 1134 | <code>new(T)</code> allocates zeroed storage for a new item of type |
| 1135 | <code>T</code> and returns its address, a value of type <code>*T</code>. |
| 1136 | In Go terminology, it returns a pointer to a newly allocated zero value of type |
| 1137 | <code>T</code>. |
| 1138 | </p> |
| 1139 | |
| 1140 | <p> |
| 1141 | Since the memory returned by <code>new</code> is zeroed, it's helpful to arrange |
| 1142 | when designing your data structures that the |
| 1143 | zero value of each type can be used without further initialization. This means a user of |
| 1144 | the data structure can create one with <code>new</code> and get right to |
| 1145 | work. |
| 1146 | For example, the documentation for <code>bytes.Buffer</code> states that |
| 1147 | "the zero value for <code>Buffer</code> is an empty buffer ready to use." |
| 1148 | Similarly, <code>sync.Mutex</code> does not |
| 1149 | have an explicit constructor or <code>Init</code> method. |
| 1150 | Instead, the zero value for a <code>sync.Mutex</code> |
| 1151 | is defined to be an unlocked mutex. |
| 1152 | </p> |
| 1153 | |
| 1154 | <p> |
| 1155 | The zero-value-is-useful property works transitively. Consider this type declaration. |
| 1156 | </p> |
| 1157 | |
| 1158 | <pre> |
| 1159 | type SyncedBuffer struct { |
| 1160 | lock sync.Mutex |
| 1161 | buffer bytes.Buffer |
| 1162 | } |
| 1163 | </pre> |
| 1164 | |
| 1165 | <p> |
| 1166 | Values of type <code>SyncedBuffer</code> are also ready to use immediately upon allocation |
| 1167 | or just declaration. In the next snippet, both <code>p</code> and <code>v</code> will work |
| 1168 | correctly without further arrangement. |
| 1169 | </p> |
| 1170 | |
| 1171 | <pre> |
| 1172 | p := new(SyncedBuffer) // type *SyncedBuffer |
| 1173 | var v SyncedBuffer // type SyncedBuffer |
| 1174 | </pre> |
| 1175 | |
| 1176 | <h3 id="composite_literals">Constructors and composite literals</h3> |
| 1177 | |
| 1178 | <p> |
| 1179 | Sometimes the zero value isn't good enough and an initializing |
| 1180 | constructor is necessary, as in this example derived from |
| 1181 | package <code>os</code>. |
| 1182 | </p> |
| 1183 | |
| 1184 | <pre> |
| 1185 | func NewFile(fd int, name string) *File { |
| 1186 | if fd < 0 { |
| 1187 | return nil |
| 1188 | } |
| 1189 | f := new(File) |
| 1190 | f.fd = fd |
| 1191 | f.name = name |
| 1192 | f.dirinfo = nil |
| 1193 | f.nepipe = 0 |
| 1194 | return f |
| 1195 | } |
| 1196 | </pre> |
| 1197 | |
| 1198 | <p> |
| 1199 | There's a lot of boiler plate in there. We can simplify it |
| 1200 | using a <i>composite literal</i>, which is |
| 1201 | an expression that creates a |
| 1202 | new instance each time it is evaluated. |
| 1203 | </p> |
| 1204 | |
| 1205 | <pre> |
| 1206 | func NewFile(fd int, name string) *File { |
| 1207 | if fd < 0 { |
| 1208 | return nil |
| 1209 | } |
| 1210 | f := File{fd, name, nil, 0} |
| 1211 | return &f |
| 1212 | } |
| 1213 | </pre> |
| 1214 | |
| 1215 | <p> |
| 1216 | Note that, unlike in C, it's perfectly OK to return the address of a local variable; |
| 1217 | the storage associated with the variable survives after the function |
| 1218 | returns. |
| 1219 | In fact, taking the address of a composite literal |
| 1220 | allocates a fresh instance each time it is evaluated, |
| 1221 | so we can combine these last two lines. |
| 1222 | </p> |
| 1223 | |
| 1224 | <pre> |
| 1225 | return &File{fd, name, nil, 0} |
| 1226 | </pre> |
| 1227 | |
| 1228 | <p> |
| 1229 | The fields of a composite literal are laid out in order and must all be present. |
| 1230 | However, by labeling the elements explicitly as <i>field</i><code>:</code><i>value</i> |
| 1231 | pairs, the initializers can appear in any |
| 1232 | order, with the missing ones left as their respective zero values. Thus we could say |
| 1233 | </p> |
| 1234 | |
| 1235 | <pre> |
| 1236 | return &File{fd: fd, name: name} |
| 1237 | </pre> |
| 1238 | |
| 1239 | <p> |
| 1240 | As a limiting case, if a composite literal contains no fields at all, it creates |
| 1241 | a zero value for the type. The expressions <code>new(File)</code> and <code>&File{}</code> are equivalent. |
| 1242 | </p> |
| 1243 | |
| 1244 | <p> |
| 1245 | Composite literals can also be created for arrays, slices, and maps, |
| 1246 | with the field labels being indices or map keys as appropriate. |
| 1247 | In these examples, the initializations work regardless of the values of <code>Enone</code>, |
| 1248 | <code>Eio</code>, and <code>Einval</code>, as long as they are distinct. |
| 1249 | </p> |
| 1250 | |
| 1251 | <pre> |
| 1252 | a := [...]string {Enone: "no error", Eio: "Eio", Einval: "invalid argument"} |
| 1253 | s := []string {Enone: "no error", Eio: "Eio", Einval: "invalid argument"} |
| 1254 | m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"} |
| 1255 | </pre> |
| 1256 | |
| 1257 | <h3 id="allocation_make">Allocation with <code>make</code></h3> |
| 1258 | |
| 1259 | <p> |
| 1260 | Back to allocation. |
| 1261 | The built-in function <code>make(T, </code><i>args</i><code>)</code> serves |
| 1262 | a purpose different from <code>new(T)</code>. |
| 1263 | It creates slices, maps, and channels only, and it returns an <em>initialized</em> |
| 1264 | (not <em>zeroed</em>) |
| 1265 | value of type <code>T</code> (not <code>*T</code>). |
| 1266 | The reason for the distinction |
| 1267 | is that these three types represent, under the covers, references to data structures that |
| 1268 | must be initialized before use. |
| 1269 | A slice, for example, is a three-item descriptor |
| 1270 | containing a pointer to the data (inside an array), the length, and the |
| 1271 | capacity, and until those items are initialized, the slice is <code>nil</code>. |
| 1272 | For slices, maps, and channels, |
| 1273 | <code>make</code> initializes the internal data structure and prepares |
| 1274 | the value for use. |
| 1275 | For instance, |
| 1276 | </p> |
| 1277 | |
| 1278 | <pre> |
| 1279 | make([]int, 10, 100) |
| 1280 | </pre> |
| 1281 | |
| 1282 | <p> |
| 1283 | allocates an array of 100 ints and then creates a slice |
| 1284 | structure with length 10 and a capacity of 100 pointing at the first |
| 1285 | 10 elements of the array. |
| 1286 | (When making a slice, the capacity can be omitted; see the section on slices |
| 1287 | for more information.) |
| 1288 | In contrast, <code>new([]int)</code> returns a pointer to a newly allocated, zeroed slice |
| 1289 | structure, that is, a pointer to a <code>nil</code> slice value. |
| 1290 | </p> |
| 1291 | |
| 1292 | <p> |
| 1293 | These examples illustrate the difference between <code>new</code> and |
| 1294 | <code>make</code>. |
| 1295 | </p> |
| 1296 | |
| 1297 | <pre> |
| 1298 | var p *[]int = new([]int) // allocates slice structure; *p == nil; rarely useful |
| 1299 | var v []int = make([]int, 100) // the slice v now refers to a new array of 100 ints |
| 1300 | |
| 1301 | // Unnecessarily complex: |
| 1302 | var p *[]int = new([]int) |
| 1303 | *p = make([]int, 100, 100) |
| 1304 | |
| 1305 | // Idiomatic: |
| 1306 | v := make([]int, 100) |
| 1307 | </pre> |
| 1308 | |
| 1309 | <p> |
| 1310 | Remember that <code>make</code> applies only to maps, slices and channels |
| 1311 | and does not return a pointer. |
| 1312 | To obtain an explicit pointer allocate with <code>new</code> or take the address |
| 1313 | of a variable explicitly. |
| 1314 | </p> |
| 1315 | |
| 1316 | <h3 id="arrays">Arrays</h3> |
| 1317 | |
| 1318 | <p> |
| 1319 | Arrays are useful when planning the detailed layout of memory and sometimes |
| 1320 | can help avoid allocation, but primarily |
| 1321 | they are a building block for slices, the subject of the next section. |
| 1322 | To lay the foundation for that topic, here are a few words about arrays. |
| 1323 | </p> |
| 1324 | |
| 1325 | <p> |
| 1326 | There are major differences between the ways arrays work in Go and C. |
| 1327 | In Go, |
| 1328 | </p> |
| 1329 | <ul> |
| 1330 | <li> |
| 1331 | Arrays are values. Assigning one array to another copies all the elements. |
| 1332 | </li> |
| 1333 | <li> |
| 1334 | In particular, if you pass an array to a function, it |
| 1335 | will receive a <i>copy</i> of the array, not a pointer to it. |
| 1336 | <li> |
| 1337 | The size of an array is part of its type. The types <code>[10]int</code> |
| 1338 | and <code>[20]int</code> are distinct. |
| 1339 | </li> |
| 1340 | </ul> |
| 1341 | |
| 1342 | <p> |
| 1343 | The value property can be useful but also expensive; if you want C-like behavior and efficiency, |
| 1344 | you can pass a pointer to the array. |
| 1345 | </p> |
| 1346 | |
| 1347 | <pre> |
| 1348 | func Sum(a *[3]float64) (sum float64) { |
| 1349 | for _, v := range *a { |
| 1350 | sum += v |
| 1351 | } |
| 1352 | return |
| 1353 | } |
| 1354 | |
| 1355 | array := [...]float64{7.0, 8.5, 9.1} |
| 1356 | x := Sum(&array) // Note the explicit address-of operator |
| 1357 | </pre> |
| 1358 | |
| 1359 | <p> |
| 1360 | But even this style isn't idiomatic Go. |
| 1361 | Use slices instead. |
| 1362 | </p> |
| 1363 | |
| 1364 | <h3 id="slices">Slices</h3> |
| 1365 | |
| 1366 | <p> |
| 1367 | Slices wrap arrays to give a more general, powerful, and convenient |
| 1368 | interface to sequences of data. Except for items with explicit |
| 1369 | dimension such as transformation matrices, most array programming in |
| 1370 | Go is done with slices rather than simple arrays. |
| 1371 | </p> |
| 1372 | <p> |
| 1373 | Slices hold references to an underlying array, and if you assign one |
| 1374 | slice to another, both refer to the same array. |
| 1375 | If a function takes a slice argument, changes it makes to |
| 1376 | the elements of the slice will be visible to the caller, analogous to |
| 1377 | passing a pointer to the underlying array. A <code>Read</code> |
| 1378 | function can therefore accept a slice argument rather than a pointer |
| 1379 | and a count; the length within the slice sets an upper |
| 1380 | limit of how much data to read. Here is the signature of the |
| 1381 | <code>Read</code> method of the <code>File</code> type in package |
| 1382 | <code>os</code>: |
| 1383 | </p> |
| 1384 | <pre> |
| 1385 | func (file *File) Read(buf []byte) (n int, err error) |
| 1386 | </pre> |
| 1387 | <p> |
| 1388 | The method returns the number of bytes read and an error value, if |
| 1389 | any. |
| 1390 | To read into the first 32 bytes of a larger buffer |
| 1391 | <code>buf</code>, <i>slice</i> (here used as a verb) the buffer. |
| 1392 | </p> |
| 1393 | <pre> |
| 1394 | n, err := f.Read(buf[0:32]) |
| 1395 | </pre> |
| 1396 | <p> |
| 1397 | Such slicing is common and efficient. In fact, leaving efficiency aside for |
| 1398 | the moment, the following snippet would also read the first 32 bytes of the buffer. |
| 1399 | </p> |
| 1400 | <pre> |
| 1401 | var n int |
| 1402 | var err error |
| 1403 | for i := 0; i < 32; i++ { |
| 1404 | nbytes, e := f.Read(buf[i:i+1]) // Read one byte. |
| 1405 | if nbytes == 0 || e != nil { |
| 1406 | err = e |
| 1407 | break |
| 1408 | } |
| 1409 | n += nbytes |
| 1410 | } |
| 1411 | </pre> |
| 1412 | <p> |
| 1413 | The length of a slice may be changed as long as it still fits within |
| 1414 | the limits of the underlying array; just assign it to a slice of |
| 1415 | itself. The <i>capacity</i> of a slice, accessible by the built-in |
| 1416 | function <code>cap</code>, reports the maximum length the slice may |
| 1417 | assume. Here is a function to append data to a slice. If the data |
| 1418 | exceeds the capacity, the slice is reallocated. The |
| 1419 | resulting slice is returned. The function uses the fact that |
| 1420 | <code>len</code> and <code>cap</code> are legal when applied to the |
| 1421 | <code>nil</code> slice, and return 0. |
| 1422 | </p> |
| 1423 | <pre> |
| 1424 | func Append(slice, data[]byte) []byte { |
| 1425 | l := len(slice) |
| 1426 | if l + len(data) > cap(slice) { // reallocate |
| 1427 | // Allocate double what's needed, for future growth. |
| 1428 | newSlice := make([]byte, (l+len(data))*2) |
| 1429 | // The copy function is predeclared and works for any slice type. |
| 1430 | copy(newSlice, slice) |
| 1431 | slice = newSlice |
| 1432 | } |
| 1433 | slice = slice[0:l+len(data)] |
| 1434 | for i, c := range data { |
| 1435 | slice[l+i] = c |
| 1436 | } |
| 1437 | return slice |
| 1438 | } |
| 1439 | </pre> |
| 1440 | <p> |
| 1441 | We must return the slice afterwards because, although <code>Append</code> |
| 1442 | can modify the elements of <code>slice</code>, the slice itself (the run-time data |
| 1443 | structure holding the pointer, length, and capacity) is passed by value. |
| 1444 | </p> |
| 1445 | |
| 1446 | <p> |
| 1447 | The idea of appending to a slice is so useful it's captured by the |
| 1448 | <code>append</code> built-in function. To understand that function's |
| 1449 | design, though, we need a little more information, so we'll return |
| 1450 | to it later. |
| 1451 | </p> |
| 1452 | |
| 1453 | <h3 id="two_dimensional_slices">Two-dimensional slices</h3> |
| 1454 | |
| 1455 | <p> |
| 1456 | Go's arrays and slices are one-dimensional. |
| 1457 | To create the equivalent of a 2D array or slice, it is necessary to define an array-of-arrays |
| 1458 | or slice-of-slices, like this: |
| 1459 | </p> |
| 1460 | |
| 1461 | <pre> |
| 1462 | type Transform [3][3]float64 // A 3x3 array, really an array of arrays. |
| 1463 | type LinesOfText [][]byte // A slice of byte slices. |
| 1464 | </pre> |
| 1465 | |
| 1466 | <p> |
| 1467 | Because slices are variable-length, it is possible to have each inner |
| 1468 | slice be a different length. |
| 1469 | That can be a common situation, as in our <code>LinesOfText</code> |
| 1470 | example: each line has an independent length. |
| 1471 | </p> |
| 1472 | |
| 1473 | <pre> |
| 1474 | text := LinesOfText{ |
| 1475 | []byte("Now is the time"), |
| 1476 | []byte("for all good gophers"), |
| 1477 | []byte("to bring some fun to the party."), |
| 1478 | } |
| 1479 | </pre> |
| 1480 | |
| 1481 | <p> |
| 1482 | Sometimes it's necessary to allocate a 2D slice, a situation that can arise when |
| 1483 | processing scan lines of pixels, for instance. |
| 1484 | There are two ways to achieve this. |
| 1485 | One is to allocate each slice independently; the other |
| 1486 | is to allocate a single array and point the individual slices into it. |
| 1487 | Which to use depends on your application. |
| 1488 | If the slices might grow or shrink, they should be allocated independently |
| 1489 | to avoid overwriting the next line; if not, it can be more efficient to construct |
| 1490 | the object with a single allocation. |
| 1491 | For reference, here are sketches of the two methods. |
| 1492 | First, a line at a time: |
| 1493 | </p> |
| 1494 | |
| 1495 | <pre> |
| 1496 | // Allocate the top-level slice. |
| 1497 | picture := make([][]uint8, YSize) // One row per unit of y. |
| 1498 | // Loop over the rows, allocating the slice for each row. |
| 1499 | for i := range picture { |
| 1500 | picture[i] = make([]uint8, XSize) |
| 1501 | } |
| 1502 | </pre> |
| 1503 | |
| 1504 | <p> |
| 1505 | And now as one allocation, sliced into lines: |
| 1506 | </p> |
| 1507 | |
| 1508 | <pre> |
| 1509 | // Allocate the top-level slice, the same as before. |
| 1510 | picture := make([][]uint8, YSize) // One row per unit of y. |
| 1511 | // Allocate one large slice to hold all the pixels. |
| 1512 | pixels := make([]uint8, XSize*YSize) // Has type []uint8 even though picture is [][]uint8. |
| 1513 | // Loop over the rows, slicing each row from the front of the remaining pixels slice. |
| 1514 | for i := range picture { |
| 1515 | picture[i], pixels = pixels[:XSize], pixels[XSize:] |
| 1516 | } |
| 1517 | </pre> |
| 1518 | |
| 1519 | <h3 id="maps">Maps</h3> |
| 1520 | |
| 1521 | <p> |
| 1522 | Maps are a convenient and powerful built-in data structure that associate |
| 1523 | values of one type (the <em>key</em>) with values of another type |
| 1524 | (the <em>element</em> or <em>value</em>) |
| 1525 | The key can be of any type for which the equality operator is defined, |
| 1526 | such as integers, |
| 1527 | floating point and complex numbers, |
| 1528 | strings, pointers, interfaces (as long as the dynamic type |
| 1529 | supports equality), structs and arrays. |
| 1530 | Slices cannot be used as map keys, |
| 1531 | because equality is not defined on them. |
| 1532 | Like slices, maps hold references to an underlying data structure. |
| 1533 | If you pass a map to a function |
| 1534 | that changes the contents of the map, the changes will be visible |
| 1535 | in the caller. |
| 1536 | </p> |
| 1537 | <p> |
| 1538 | Maps can be constructed using the usual composite literal syntax |
| 1539 | with colon-separated key-value pairs, |
| 1540 | so it's easy to build them during initialization. |
| 1541 | </p> |
| 1542 | <pre> |
| 1543 | var timeZone = map[string]int{ |
| 1544 | "UTC": 0*60*60, |
| 1545 | "EST": -5*60*60, |
| 1546 | "CST": -6*60*60, |
| 1547 | "MST": -7*60*60, |
| 1548 | "PST": -8*60*60, |
| 1549 | } |
| 1550 | </pre> |
| 1551 | <p> |
| 1552 | Assigning and fetching map values looks syntactically just like |
| 1553 | doing the same for arrays and slices except that the index doesn't |
| 1554 | need to be an integer. |
| 1555 | </p> |
| 1556 | <pre> |
| 1557 | offset := timeZone["EST"] |
| 1558 | </pre> |
| 1559 | <p> |
| 1560 | An attempt to fetch a map value with a key that |
| 1561 | is not present in the map will return the zero value for the type |
| 1562 | of the entries |
| 1563 | in the map. For instance, if the map contains integers, looking |
| 1564 | up a non-existent key will return <code>0</code>. |
| 1565 | A set can be implemented as a map with value type <code>bool</code>. |
| 1566 | Set the map entry to <code>true</code> to put the value in the set, and then |
| 1567 | test it by simple indexing. |
| 1568 | </p> |
| 1569 | <pre> |
| 1570 | attended := map[string]bool{ |
| 1571 | "Ann": true, |
| 1572 | "Joe": true, |
| 1573 | ... |
| 1574 | } |
| 1575 | |
| 1576 | if attended[person] { // will be false if person is not in the map |
| 1577 | fmt.Println(person, "was at the meeting") |
| 1578 | } |
| 1579 | </pre> |
| 1580 | <p> |
| 1581 | Sometimes you need to distinguish a missing entry from |
| 1582 | a zero value. Is there an entry for <code>"UTC"</code> |
| 1583 | or is that the empty string because it's not in the map at all? |
| 1584 | You can discriminate with a form of multiple assignment. |
| 1585 | </p> |
| 1586 | <pre> |
| 1587 | var seconds int |
| 1588 | var ok bool |
| 1589 | seconds, ok = timeZone[tz] |
| 1590 | </pre> |
| 1591 | <p> |
| 1592 | For obvious reasons this is called the “comma ok” idiom. |
| 1593 | In this example, if <code>tz</code> is present, <code>seconds</code> |
| 1594 | will be set appropriately and <code>ok</code> will be true; if not, |
| 1595 | <code>seconds</code> will be set to zero and <code>ok</code> will |
| 1596 | be false. |
| 1597 | Here's a function that puts it together with a nice error report: |
| 1598 | </p> |
| 1599 | <pre> |
| 1600 | func offset(tz string) int { |
| 1601 | if seconds, ok := timeZone[tz]; ok { |
| 1602 | return seconds |
| 1603 | } |
| 1604 | log.Println("unknown time zone:", tz) |
| 1605 | return 0 |
| 1606 | } |
| 1607 | </pre> |
| 1608 | <p> |
| 1609 | To test for presence in the map without worrying about the actual value, |
| 1610 | you can use the <a href="#blank">blank identifier</a> (<code>_</code>) |
| 1611 | in place of the usual variable for the value. |
| 1612 | </p> |
| 1613 | <pre> |
| 1614 | _, present := timeZone[tz] |
| 1615 | </pre> |
| 1616 | <p> |
| 1617 | To delete a map entry, use the <code>delete</code> |
| 1618 | built-in function, whose arguments are the map and the key to be deleted. |
| 1619 | It's safe to do this even if the key is already absent |
| 1620 | from the map. |
| 1621 | </p> |
| 1622 | <pre> |
| 1623 | delete(timeZone, "PDT") // Now on Standard Time |
| 1624 | </pre> |
| 1625 | |
| 1626 | <h3 id="printing">Printing</h3> |
| 1627 | |
| 1628 | <p> |
| 1629 | Formatted printing in Go uses a style similar to C's <code>printf</code> |
| 1630 | family but is richer and more general. The functions live in the <code>fmt</code> |
| 1631 | package and have capitalized names: <code>fmt.Printf</code>, <code>fmt.Fprintf</code>, |
| 1632 | <code>fmt.Sprintf</code> and so on. The string functions (<code>Sprintf</code> etc.) |
| 1633 | return a string rather than filling in a provided buffer. |
| 1634 | </p> |
| 1635 | <p> |
| 1636 | You don't need to provide a format string. For each of <code>Printf</code>, |
| 1637 | <code>Fprintf</code> and <code>Sprintf</code> there is another pair |
| 1638 | of functions, for instance <code>Print</code> and <code>Println</code>. |
| 1639 | These functions do not take a format string but instead generate a default |
| 1640 | format for each argument. The <code>Println</code> versions also insert a blank |
| 1641 | between arguments and append a newline to the output while |
| 1642 | the <code>Print</code> versions add blanks only if the operand on neither side is a string. |
| 1643 | In this example each line produces the same output. |
| 1644 | </p> |
| 1645 | <pre> |
| 1646 | fmt.Printf("Hello %d\n", 23) |
| 1647 | fmt.Fprint(os.Stdout, "Hello ", 23, "\n") |
| 1648 | fmt.Println("Hello", 23) |
| 1649 | fmt.Println(fmt.Sprint("Hello ", 23)) |
| 1650 | </pre> |
| 1651 | <p> |
| 1652 | The formatted print functions <code>fmt.Fprint</code> |
| 1653 | and friends take as a first argument any object |
| 1654 | that implements the <code>io.Writer</code> interface; the variables <code>os.Stdout</code> |
| 1655 | and <code>os.Stderr</code> are familiar instances. |
| 1656 | </p> |
| 1657 | <p> |
| 1658 | Here things start to diverge from C. First, the numeric formats such as <code>%d</code> |
| 1659 | do not take flags for signedness or size; instead, the printing routines use the |
| 1660 | type of the argument to decide these properties. |
| 1661 | </p> |
| 1662 | <pre> |
| 1663 | var x uint64 = 1<<64 - 1 |
| 1664 | fmt.Printf("%d %x; %d %x\n", x, x, int64(x), int64(x)) |
| 1665 | </pre> |
| 1666 | <p> |
| 1667 | prints |
| 1668 | </p> |
| 1669 | <pre> |
| 1670 | 18446744073709551615 ffffffffffffffff; -1 -1 |
| 1671 | </pre> |
| 1672 | <p> |
| 1673 | If you just want the default conversion, such as decimal for integers, you can use |
| 1674 | the catchall format <code>%v</code> (for “value”); the result is exactly |
| 1675 | what <code>Print</code> and <code>Println</code> would produce. |
| 1676 | Moreover, that format can print <em>any</em> value, even arrays, slices, structs, and |
| 1677 | maps. Here is a print statement for the time zone map defined in the previous section. |
| 1678 | </p> |
| 1679 | <pre> |
| 1680 | fmt.Printf("%v\n", timeZone) // or just fmt.Println(timeZone) |
| 1681 | </pre> |
| 1682 | <p> |
| 1683 | which gives output |
| 1684 | </p> |
| 1685 | <pre> |
| 1686 | map[CST:-21600 PST:-28800 EST:-18000 UTC:0 MST:-25200] |
| 1687 | </pre> |
| 1688 | <p> |
| 1689 | For maps the keys may be output in any order, of course. |
| 1690 | When printing a struct, the modified format <code>%+v</code> annotates the |
| 1691 | fields of the structure with their names, and for any value the alternate |
| 1692 | format <code>%#v</code> prints the value in full Go syntax. |
| 1693 | </p> |
| 1694 | <pre> |
| 1695 | type T struct { |
| 1696 | a int |
| 1697 | b float64 |
| 1698 | c string |
| 1699 | } |
| 1700 | t := &T{ 7, -2.35, "abc\tdef" } |
| 1701 | fmt.Printf("%v\n", t) |
| 1702 | fmt.Printf("%+v\n", t) |
| 1703 | fmt.Printf("%#v\n", t) |
| 1704 | fmt.Printf("%#v\n", timeZone) |
| 1705 | </pre> |
| 1706 | <p> |
| 1707 | prints |
| 1708 | </p> |
| 1709 | <pre> |
| 1710 | &{7 -2.35 abc def} |
| 1711 | &{a:7 b:-2.35 c:abc def} |
| 1712 | &main.T{a:7, b:-2.35, c:"abc\tdef"} |
| 1713 | map[string] int{"CST":-21600, "PST":-28800, "EST":-18000, "UTC":0, "MST":-25200} |
| 1714 | </pre> |
| 1715 | <p> |
| 1716 | (Note the ampersands.) |
| 1717 | That quoted string format is also available through <code>%q</code> when |
| 1718 | applied to a value of type <code>string</code> or <code>[]byte</code>. |
| 1719 | The alternate format <code>%#q</code> will use backquotes instead if possible. |
| 1720 | (The <code>%q</code> format also applies to integers and runes, producing a |
| 1721 | single-quoted rune constant.) |
| 1722 | Also, <code>%x</code> works on strings, byte arrays and byte slices as well as |
| 1723 | on integers, generating a long hexadecimal string, and with |
| 1724 | a space in the format (<code>% x</code>) it puts spaces between the bytes. |
| 1725 | </p> |
| 1726 | <p> |
| 1727 | Another handy format is <code>%T</code>, which prints the <em>type</em> of a value. |
| 1728 | </p> |
| 1729 | <pre> |
| 1730 | fmt.Printf("%T\n", timeZone) |
| 1731 | </pre> |
| 1732 | <p> |
| 1733 | prints |
| 1734 | </p> |
| 1735 | <pre> |
| 1736 | map[string] int |
| 1737 | </pre> |
| 1738 | <p> |
| 1739 | If you want to control the default format for a custom type, all that's required is to define |
| 1740 | a method with the signature <code>String() string</code> on the type. |
| 1741 | For our simple type <code>T</code>, that might look like this. |
| 1742 | </p> |
| 1743 | <pre> |
| 1744 | func (t *T) String() string { |
| 1745 | return fmt.Sprintf("%d/%g/%q", t.a, t.b, t.c) |
| 1746 | } |
| 1747 | fmt.Printf("%v\n", t) |
| 1748 | </pre> |
| 1749 | <p> |
| 1750 | to print in the format |
| 1751 | </p> |
| 1752 | <pre> |
| 1753 | 7/-2.35/"abc\tdef" |
| 1754 | </pre> |
| 1755 | <p> |
| 1756 | (If you need to print <em>values</em> of type <code>T</code> as well as pointers to <code>T</code>, |
| 1757 | the receiver for <code>String</code> must be of value type; this example used a pointer because |
| 1758 | that's more efficient and idiomatic for struct types. |
| 1759 | See the section below on <a href="#pointers_vs_values">pointers vs. value receivers</a> for more information.) |
| 1760 | </p> |
| 1761 | |
| 1762 | <p> |
| 1763 | Our <code>String</code> method is able to call <code>Sprintf</code> because the |
| 1764 | print routines are fully reentrant and can be wrapped this way. |
| 1765 | There is one important detail to understand about this approach, |
| 1766 | however: don't construct a <code>String</code> method by calling |
| 1767 | <code>Sprintf</code> in a way that will recur into your <code>String</code> |
| 1768 | method indefinitely. This can happen if the <code>Sprintf</code> |
| 1769 | call attempts to print the receiver directly as a string, which in |
| 1770 | turn will invoke the method again. It's a common and easy mistake |
| 1771 | to make, as this example shows. |
| 1772 | </p> |
| 1773 | |
| 1774 | <pre> |
| 1775 | type MyString string |
| 1776 | |
| 1777 | func (m MyString) String() string { |
| 1778 | return fmt.Sprintf("MyString=%s", m) // Error: will recur forever. |
| 1779 | } |
| 1780 | </pre> |
| 1781 | |
| 1782 | <p> |
| 1783 | It's also easy to fix: convert the argument to the basic string type, which does not have the |
| 1784 | method. |
| 1785 | </p> |
| 1786 | |
| 1787 | <pre> |
| 1788 | type MyString string |
| 1789 | func (m MyString) String() string { |
| 1790 | return fmt.Sprintf("MyString=%s", string(m)) // OK: note conversion. |
| 1791 | } |
| 1792 | </pre> |
| 1793 | |
| 1794 | <p> |
| 1795 | In the <a href="#initialization">initialization section</a> we'll see another technique that avoids this recursion. |
| 1796 | </p> |
| 1797 | |
| 1798 | <p> |
| 1799 | Another printing technique is to pass a print routine's arguments directly to another such routine. |
| 1800 | The signature of <code>Printf</code> uses the type <code>...interface{}</code> |
| 1801 | for its final argument to specify that an arbitrary number of parameters (of arbitrary type) |
| 1802 | can appear after the format. |
| 1803 | </p> |
| 1804 | <pre> |
| 1805 | func Printf(format string, v ...interface{}) (n int, err error) { |
| 1806 | </pre> |
| 1807 | <p> |
| 1808 | Within the function <code>Printf</code>, <code>v</code> acts like a variable of type |
| 1809 | <code>[]interface{}</code> but if it is passed to another variadic function, it acts like |
| 1810 | a regular list of arguments. |
| 1811 | Here is the implementation of the |
| 1812 | function <code>log.Println</code> we used above. It passes its arguments directly to |
| 1813 | <code>fmt.Sprintln</code> for the actual formatting. |
| 1814 | </p> |
| 1815 | <pre> |
| 1816 | // Println prints to the standard logger in the manner of fmt.Println. |
| 1817 | func Println(v ...interface{}) { |
| 1818 | std.Output(2, fmt.Sprintln(v...)) // Output takes parameters (int, string) |
| 1819 | } |
| 1820 | </pre> |
| 1821 | <p> |
| 1822 | We write <code>...</code> after <code>v</code> in the nested call to <code>Sprintln</code> to tell the |
| 1823 | compiler to treat <code>v</code> as a list of arguments; otherwise it would just pass |
| 1824 | <code>v</code> as a single slice argument. |
| 1825 | </p> |
| 1826 | <p> |
| 1827 | There's even more to printing than we've covered here. See the <code>godoc</code> documentation |
| 1828 | for package <code>fmt</code> for the details. |
| 1829 | </p> |
| 1830 | <p> |
| 1831 | By the way, a <code>...</code> parameter can be of a specific type, for instance <code>...int</code> |
| 1832 | for a min function that chooses the least of a list of integers: |
| 1833 | </p> |
| 1834 | <pre> |
| 1835 | func Min(a ...int) int { |
| 1836 | min := int(^uint(0) >> 1) // largest int |
| 1837 | for _, i := range a { |
| 1838 | if i < min { |
| 1839 | min = i |
| 1840 | } |
| 1841 | } |
| 1842 | return min |
| 1843 | } |
| 1844 | </pre> |
| 1845 | |
| 1846 | <h3 id="append">Append</h3> |
| 1847 | <p> |
| 1848 | Now we have the missing piece we needed to explain the design of |
| 1849 | the <code>append</code> built-in function. The signature of <code>append</code> |
| 1850 | is different from our custom <code>Append</code> function above. |
| 1851 | Schematically, it's like this: |
| 1852 | </p> |
| 1853 | <pre> |
| 1854 | func append(slice []<i>T</i>, elements ...<i>T</i>) []<i>T</i> |
| 1855 | </pre> |
| 1856 | <p> |
| 1857 | where <i>T</i> is a placeholder for any given type. You can't |
| 1858 | actually write a function in Go where the type <code>T</code> |
| 1859 | is determined by the caller. |
| 1860 | That's why <code>append</code> is built in: it needs support from the |
| 1861 | compiler. |
| 1862 | </p> |
| 1863 | <p> |
| 1864 | What <code>append</code> does is append the elements to the end of |
| 1865 | the slice and return the result. The result needs to be returned |
| 1866 | because, as with our hand-written <code>Append</code>, the underlying |
| 1867 | array may change. This simple example |
| 1868 | </p> |
| 1869 | <pre> |
| 1870 | x := []int{1,2,3} |
| 1871 | x = append(x, 4, 5, 6) |
| 1872 | fmt.Println(x) |
| 1873 | </pre> |
| 1874 | <p> |
| 1875 | prints <code>[1 2 3 4 5 6]</code>. So <code>append</code> works a |
| 1876 | little like <code>Printf</code>, collecting an arbitrary number of |
| 1877 | arguments. |
| 1878 | </p> |
| 1879 | <p> |
| 1880 | But what if we wanted to do what our <code>Append</code> does and |
| 1881 | append a slice to a slice? Easy: use <code>...</code> at the call |
| 1882 | site, just as we did in the call to <code>Output</code> above. This |
| 1883 | snippet produces identical output to the one above. |
| 1884 | </p> |
| 1885 | <pre> |
| 1886 | x := []int{1,2,3} |
| 1887 | y := []int{4,5,6} |
| 1888 | x = append(x, y...) |
| 1889 | fmt.Println(x) |
| 1890 | </pre> |
| 1891 | <p> |
| 1892 | Without that <code>...</code>, it wouldn't compile because the types |
| 1893 | would be wrong; <code>y</code> is not of type <code>int</code>. |
| 1894 | </p> |
| 1895 | |
| 1896 | <h2 id="initialization">Initialization</h2> |
| 1897 | |
| 1898 | <p> |
| 1899 | Although it doesn't look superficially very different from |
| 1900 | initialization in C or C++, initialization in Go is more powerful. |
| 1901 | Complex structures can be built during initialization and the ordering |
| 1902 | issues among initialized objects, even among different packages, are handled |
| 1903 | correctly. |
| 1904 | </p> |
| 1905 | |
| 1906 | <h3 id="constants">Constants</h3> |
| 1907 | |
| 1908 | <p> |
| 1909 | Constants in Go are just that—constant. |
| 1910 | They are created at compile time, even when defined as |
| 1911 | locals in functions, |
| 1912 | and can only be numbers, characters (runes), strings or booleans. |
| 1913 | Because of the compile-time restriction, the expressions |
| 1914 | that define them must be constant expressions, |
| 1915 | evaluatable by the compiler. For instance, |
| 1916 | <code>1<<3</code> is a constant expression, while |
| 1917 | <code>math.Sin(math.Pi/4)</code> is not because |
| 1918 | the function call to <code>math.Sin</code> needs |
| 1919 | to happen at run time. |
| 1920 | </p> |
| 1921 | |
| 1922 | <p> |
| 1923 | In Go, enumerated constants are created using the <code>iota</code> |
| 1924 | enumerator. Since <code>iota</code> can be part of an expression and |
| 1925 | expressions can be implicitly repeated, it is easy to build intricate |
| 1926 | sets of values. |
| 1927 | </p> |
| 1928 | {{code "/doc/progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}} |
| 1929 | <p> |
| 1930 | The ability to attach a method such as <code>String</code> to any |
| 1931 | user-defined type makes it possible for arbitrary values to format themselves |
| 1932 | automatically for printing. |
| 1933 | Although you'll see it most often applied to structs, this technique is also useful for |
| 1934 | scalar types such as floating-point types like <code>ByteSize</code>. |
| 1935 | </p> |
| 1936 | {{code "/doc/progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}} |
| 1937 | <p> |
| 1938 | The expression <code>YB</code> prints as <code>1.00YB</code>, |
| 1939 | while <code>ByteSize(1e13)</code> prints as <code>9.09TB</code>. |
| 1940 | </p> |
| 1941 | |
| 1942 | <p> |
| 1943 | The use here of <code>Sprintf</code> |
| 1944 | to implement <code>ByteSize</code>'s <code>String</code> method is safe |
| 1945 | (avoids recurring indefinitely) not because of a conversion but |
| 1946 | because it calls <code>Sprintf</code> with <code>%f</code>, |
| 1947 | which is not a string format: <code>Sprintf</code> will only call |
| 1948 | the <code>String</code> method when it wants a string, and <code>%f</code> |
| 1949 | wants a floating-point value. |
| 1950 | </p> |
| 1951 | |
| 1952 | <h3 id="variables">Variables</h3> |
| 1953 | |
| 1954 | <p> |
| 1955 | Variables can be initialized just like constants but the |
| 1956 | initializer can be a general expression computed at run time. |
| 1957 | </p> |
| 1958 | <pre> |
| 1959 | var ( |
| 1960 | home = os.Getenv("HOME") |
| 1961 | user = os.Getenv("USER") |
| 1962 | gopath = os.Getenv("GOPATH") |
| 1963 | ) |
| 1964 | </pre> |
| 1965 | |
| 1966 | <h3 id="init">The init function</h3> |
| 1967 | |
| 1968 | <p> |
| 1969 | Finally, each source file can define its own niladic <code>init</code> function to |
| 1970 | set up whatever state is required. (Actually each file can have multiple |
| 1971 | <code>init</code> functions.) |
| 1972 | And finally means finally: <code>init</code> is called after all the |
| 1973 | variable declarations in the package have evaluated their initializers, |
| 1974 | and those are evaluated only after all the imported packages have been |
| 1975 | initialized. |
| 1976 | </p> |
| 1977 | <p> |
| 1978 | Besides initializations that cannot be expressed as declarations, |
| 1979 | a common use of <code>init</code> functions is to verify or repair |
| 1980 | correctness of the program state before real execution begins. |
| 1981 | </p> |
| 1982 | |
| 1983 | <pre> |
| 1984 | func init() { |
| 1985 | if user == "" { |
| 1986 | log.Fatal("$USER not set") |
| 1987 | } |
| 1988 | if home == "" { |
| 1989 | home = "/home/" + user |
| 1990 | } |
| 1991 | if gopath == "" { |
| 1992 | gopath = home + "/go" |
| 1993 | } |
| 1994 | // gopath may be overridden by --gopath flag on command line. |
| 1995 | flag.StringVar(&gopath, "gopath", gopath, "override default GOPATH") |
| 1996 | } |
| 1997 | </pre> |
| 1998 | |
| 1999 | <h2 id="methods">Methods</h2> |
| 2000 | |
| 2001 | <h3 id="pointers_vs_values">Pointers vs. Values</h3> |
| 2002 | <p> |
| 2003 | As we saw with <code>ByteSize</code>, |
| 2004 | methods can be defined for any named type (except a pointer or an interface); |
| 2005 | the receiver does not have to be a struct. |
| 2006 | </p> |
| 2007 | <p> |
| 2008 | In the discussion of slices above, we wrote an <code>Append</code> |
| 2009 | function. We can define it as a method on slices instead. To do |
| 2010 | this, we first declare a named type to which we can bind the method, and |
| 2011 | then make the receiver for the method a value of that type. |
| 2012 | </p> |
| 2013 | <pre> |
| 2014 | type ByteSlice []byte |
| 2015 | |
| 2016 | func (slice ByteSlice) Append(data []byte) []byte { |
| 2017 | // Body exactly the same as above |
| 2018 | } |
| 2019 | </pre> |
| 2020 | <p> |
| 2021 | This still requires the method to return the updated slice. We can |
| 2022 | eliminate that clumsiness by redefining the method to take a |
| 2023 | <i>pointer</i> to a <code>ByteSlice</code> as its receiver, so the |
| 2024 | method can overwrite the caller's slice. |
| 2025 | </p> |
| 2026 | <pre> |
| 2027 | func (p *ByteSlice) Append(data []byte) { |
| 2028 | slice := *p |
| 2029 | // Body as above, without the return. |
| 2030 | *p = slice |
| 2031 | } |
| 2032 | </pre> |
| 2033 | <p> |
| 2034 | In fact, we can do even better. If we modify our function so it looks |
| 2035 | like a standard <code>Write</code> method, like this, |
| 2036 | </p> |
| 2037 | <pre> |
| 2038 | func (p *ByteSlice) Write(data []byte) (n int, err error) { |
| 2039 | slice := *p |
| 2040 | // Again as above. |
| 2041 | *p = slice |
| 2042 | return len(data), nil |
| 2043 | } |
| 2044 | </pre> |
| 2045 | <p> |
| 2046 | then the type <code>*ByteSlice</code> satisfies the standard interface |
| 2047 | <code>io.Writer</code>, which is handy. For instance, we can |
| 2048 | print into one. |
| 2049 | </p> |
| 2050 | <pre> |
| 2051 | var b ByteSlice |
| 2052 | fmt.Fprintf(&b, "This hour has %d days\n", 7) |
| 2053 | </pre> |
| 2054 | <p> |
| 2055 | We pass the address of a <code>ByteSlice</code> |
| 2056 | because only <code>*ByteSlice</code> satisfies <code>io.Writer</code>. |
| 2057 | The rule about pointers vs. values for receivers is that value methods |
| 2058 | can be invoked on pointers and values, but pointer methods can only be |
| 2059 | invoked on pointers. |
| 2060 | </p> |
| 2061 | |
| 2062 | <p> |
| 2063 | This rule arises because pointer methods can modify the receiver; invoking |
| 2064 | them on a value would cause the method to receive a copy of the value, so |
| 2065 | any modifications would be discarded. |
| 2066 | The language therefore disallows this mistake. |
| 2067 | There is a handy exception, though. When the value is addressable, the |
| 2068 | language takes care of the common case of invoking a pointer method on a |
| 2069 | value by inserting the address operator automatically. |
| 2070 | In our example, the variable <code>b</code> is addressable, so we can call |
| 2071 | its <code>Write</code> method with just <code>b.Write</code>. The compiler |
| 2072 | will rewrite that to <code>(&b).Write</code> for us. |
| 2073 | </p> |
| 2074 | |
| 2075 | <p> |
| 2076 | By the way, the idea of using <code>Write</code> on a slice of bytes |
| 2077 | is central to the implementation of <code>bytes.Buffer</code>. |
| 2078 | </p> |
| 2079 | |
| 2080 | <h2 id="interfaces_and_types">Interfaces and other types</h2> |
| 2081 | |
| 2082 | <h3 id="interfaces">Interfaces</h3> |
| 2083 | <p> |
| 2084 | Interfaces in Go provide a way to specify the behavior of an |
| 2085 | object: if something can do <em>this</em>, then it can be used |
| 2086 | <em>here</em>. We've seen a couple of simple examples already; |
| 2087 | custom printers can be implemented by a <code>String</code> method |
| 2088 | while <code>Fprintf</code> can generate output to anything |
| 2089 | with a <code>Write</code> method. |
| 2090 | Interfaces with only one or two methods are common in Go code, and are |
| 2091 | usually given a name derived from the method, such as <code>io.Writer</code> |
| 2092 | for something that implements <code>Write</code>. |
| 2093 | </p> |
| 2094 | <p> |
| 2095 | A type can implement multiple interfaces. |
| 2096 | For instance, a collection can be sorted |
| 2097 | by the routines in package <code>sort</code> if it implements |
| 2098 | <code>sort.Interface</code>, which contains <code>Len()</code>, |
| 2099 | <code>Less(i, j int) bool</code>, and <code>Swap(i, j int)</code>, |
| 2100 | and it could also have a custom formatter. |
| 2101 | In this contrived example <code>Sequence</code> satisfies both. |
| 2102 | </p> |
| 2103 | {{code "/doc/progs/eff_sequence.go" `/^type/` "$"}} |
| 2104 | |
| 2105 | <h3 id="conversions">Conversions</h3> |
| 2106 | |
| 2107 | <p> |
| 2108 | The <code>String</code> method of <code>Sequence</code> is recreating the |
| 2109 | work that <code>Sprint</code> already does for slices. We can share the |
| 2110 | effort if we convert the <code>Sequence</code> to a plain |
| 2111 | <code>[]int</code> before calling <code>Sprint</code>. |
| 2112 | </p> |
| 2113 | <pre> |
| 2114 | func (s Sequence) String() string { |
| 2115 | sort.Sort(s) |
| 2116 | return fmt.Sprint([]int(s)) |
| 2117 | } |
| 2118 | </pre> |
| 2119 | <p> |
| 2120 | This method is another example of the conversion technique for calling |
| 2121 | <code>Sprintf</code> safely from a <code>String</code> method. |
| 2122 | Because the two types (<code>Sequence</code> and <code>[]int</code>) |
| 2123 | are the same if we ignore the type name, it's legal to convert between them. |
| 2124 | The conversion doesn't create a new value, it just temporarily acts |
| 2125 | as though the existing value has a new type. |
| 2126 | (There are other legal conversions, such as from integer to floating point, that |
| 2127 | do create a new value.) |
| 2128 | </p> |
| 2129 | <p> |
| 2130 | It's an idiom in Go programs to convert the |
| 2131 | type of an expression to access a different |
| 2132 | set of methods. As an example, we could use the existing |
| 2133 | type <code>sort.IntSlice</code> to reduce the entire example |
| 2134 | to this: |
| 2135 | </p> |
| 2136 | <pre> |
| 2137 | type Sequence []int |
| 2138 | |
| 2139 | // Method for printing - sorts the elements before printing |
| 2140 | func (s Sequence) String() string { |
| 2141 | sort.IntSlice(s).Sort() |
| 2142 | return fmt.Sprint([]int(s)) |
| 2143 | } |
| 2144 | </pre> |
| 2145 | <p> |
| 2146 | Now, instead of having <code>Sequence</code> implement multiple |
| 2147 | interfaces (sorting and printing), we're using the ability of a data item to be |
| 2148 | converted to multiple types (<code>Sequence</code>, <code>sort.IntSlice</code> |
| 2149 | and <code>[]int</code>), each of which does some part of the job. |
| 2150 | That's more unusual in practice but can be effective. |
| 2151 | </p> |
| 2152 | |
| 2153 | <h3 id="interface_conversions">Interface conversions and type assertions</h3> |
| 2154 | |
| 2155 | <p> |
| 2156 | <a href="#type_switch">Type switches</a> are a form of conversion: they take an interface and, for |
| 2157 | each case in the switch, in a sense convert it to the type of that case. |
| 2158 | Here's a simplified version of how the code under <code>fmt.Printf</code> turns a value into |
| 2159 | a string using a type switch. |
| 2160 | If it's already a string, we want the actual string value held by the interface, while if it has a |
| 2161 | <code>String</code> method we want the result of calling the method. |
| 2162 | </p> |
| 2163 | |
| 2164 | <pre> |
| 2165 | type Stringer interface { |
| 2166 | String() string |
| 2167 | } |
| 2168 | |
| 2169 | var value interface{} // Value provided by caller. |
| 2170 | switch str := value.(type) { |
| 2171 | case string: |
| 2172 | return str |
| 2173 | case Stringer: |
| 2174 | return str.String() |
| 2175 | } |
| 2176 | </pre> |
| 2177 | |
| 2178 | <p> |
| 2179 | The first case finds a concrete value; the second converts the interface into another interface. |
| 2180 | It's perfectly fine to mix types this way. |
| 2181 | </p> |
| 2182 | |
| 2183 | <p> |
| 2184 | What if there's only one type we care about? If we know the value holds a <code>string</code> |
| 2185 | and we just want to extract it? |
| 2186 | A one-case type switch would do, but so would a <em>type assertion</em>. |
| 2187 | A type assertion takes an interface value and extracts from it a value of the specified explicit type. |
| 2188 | The syntax borrows from the clause opening a type switch, but with an explicit |
| 2189 | type rather than the <code>type</code> keyword: |
| 2190 | </p> |
| 2191 | |
| 2192 | <pre> |
| 2193 | value.(typeName) |
| 2194 | </pre> |
| 2195 | |
| 2196 | <p> |
| 2197 | and the result is a new value with the static type <code>typeName</code>. |
| 2198 | That type must either be the concrete type held by the interface, or a second interface |
| 2199 | type that the value can be converted to. |
| 2200 | To extract the string we know is in the value, we could write: |
| 2201 | </p> |
| 2202 | |
| 2203 | <pre> |
| 2204 | str := value.(string) |
| 2205 | </pre> |
| 2206 | |
| 2207 | <p> |
| 2208 | But if it turns out that the value does not contain a string, the program will crash with a run-time error. |
| 2209 | To guard against that, use the "comma, ok" idiom to test, safely, whether the value is a string: |
| 2210 | </p> |
| 2211 | |
| 2212 | <pre> |
| 2213 | str, ok := value.(string) |
| 2214 | if ok { |
| 2215 | fmt.Printf("string value is: %q\n", str) |
| 2216 | } else { |
| 2217 | fmt.Printf("value is not a string\n") |
| 2218 | } |
| 2219 | </pre> |
| 2220 | |
| 2221 | <p> |
| 2222 | If the type assertion fails, <code>str</code> will still exist and be of type string, but it will have |
| 2223 | the zero value, an empty string. |
| 2224 | </p> |
| 2225 | |
| 2226 | <p> |
| 2227 | As an illustration of the capability, here's an <code>if</code>-<code>else</code> |
| 2228 | statement that's equivalent to the type switch that opened this section. |
| 2229 | </p> |
| 2230 | |
| 2231 | <pre> |
| 2232 | if str, ok := value.(string); ok { |
| 2233 | return str |
| 2234 | } else if str, ok := value.(Stringer); ok { |
| 2235 | return str.String() |
| 2236 | } |
| 2237 | </pre> |
| 2238 | |
| 2239 | <h3 id="generality">Generality</h3> |
| 2240 | <p> |
| 2241 | If a type exists only to implement an interface |
| 2242 | and has no exported methods beyond that interface, |
| 2243 | there is no need to export the type itself. |
| 2244 | Exporting just the interface makes it clear that |
| 2245 | it's the behavior that matters, not the implementation, |
| 2246 | and that other implementations with different properties |
| 2247 | can mirror the behavior of the original type. |
| 2248 | It also avoids the need to repeat the documentation |
| 2249 | on every instance of a common method. |
| 2250 | </p> |
| 2251 | <p> |
| 2252 | In such cases, the constructor should return an interface value |
| 2253 | rather than the implementing type. |
| 2254 | As an example, in the hash libraries |
| 2255 | both <code>crc32.NewIEEE</code> and <code>adler32.New</code> |
| 2256 | return the interface type <code>hash.Hash32</code>. |
| 2257 | Substituting the CRC-32 algorithm for Adler-32 in a Go program |
| 2258 | requires only changing the constructor call; |
| 2259 | the rest of the code is unaffected by the change of algorithm. |
| 2260 | </p> |
| 2261 | <p> |
| 2262 | A similar approach allows the streaming cipher algorithms |
| 2263 | in the various <code>crypto</code> packages to be |
| 2264 | separated from the block ciphers they chain together. |
| 2265 | The <code>Block</code> interface |
| 2266 | in the <code>crypto/cipher</code> package specifies the |
| 2267 | behavior of a block cipher, which provides encryption |
| 2268 | of a single block of data. |
| 2269 | Then, by analogy with the <code>bufio</code> package, |
| 2270 | cipher packages that implement this interface |
| 2271 | can be used to construct streaming ciphers, represented |
| 2272 | by the <code>Stream</code> interface, without |
| 2273 | knowing the details of the block encryption. |
| 2274 | </p> |
| 2275 | <p> |
| 2276 | The <code>crypto/cipher</code> interfaces look like this: |
| 2277 | </p> |
| 2278 | <pre> |
| 2279 | type Block interface { |
| 2280 | BlockSize() int |
| 2281 | Encrypt(src, dst []byte) |
| 2282 | Decrypt(src, dst []byte) |
| 2283 | } |
| 2284 | |
| 2285 | type Stream interface { |
| 2286 | XORKeyStream(dst, src []byte) |
| 2287 | } |
| 2288 | </pre> |
| 2289 | |
| 2290 | <p> |
| 2291 | Here's the definition of the counter mode (CTR) stream, |
| 2292 | which turns a block cipher into a streaming cipher; notice |
| 2293 | that the block cipher's details are abstracted away: |
| 2294 | </p> |
| 2295 | |
| 2296 | <pre> |
| 2297 | // NewCTR returns a Stream that encrypts/decrypts using the given Block in |
| 2298 | // counter mode. The length of iv must be the same as the Block's block size. |
| 2299 | func NewCTR(block Block, iv []byte) Stream |
| 2300 | </pre> |
| 2301 | <p> |
| 2302 | <code>NewCTR</code> applies not |
| 2303 | just to one specific encryption algorithm and data source but to any |
| 2304 | implementation of the <code>Block</code> interface and any |
| 2305 | <code>Stream</code>. Because they return |
| 2306 | interface values, replacing CTR |
| 2307 | encryption with other encryption modes is a localized change. The constructor |
| 2308 | calls must be edited, but because the surrounding code must treat the result only |
| 2309 | as a <code>Stream</code>, it won't notice the difference. |
| 2310 | </p> |
| 2311 | |
| 2312 | <h3 id="interface_methods">Interfaces and methods</h3> |
| 2313 | <p> |
| 2314 | Since almost anything can have methods attached, almost anything can |
| 2315 | satisfy an interface. One illustrative example is in the <code>http</code> |
| 2316 | package, which defines the <code>Handler</code> interface. Any object |
| 2317 | that implements <code>Handler</code> can serve HTTP requests. |
| 2318 | </p> |
| 2319 | <pre> |
| 2320 | type Handler interface { |
| 2321 | ServeHTTP(ResponseWriter, *Request) |
| 2322 | } |
| 2323 | </pre> |
| 2324 | <p> |
| 2325 | <code>ResponseWriter</code> is itself an interface that provides access |
| 2326 | to the methods needed to return the response to the client. |
| 2327 | Those methods include the standard <code>Write</code> method, so an |
| 2328 | <code>http.ResponseWriter</code> can be used wherever an <code>io.Writer</code> |
| 2329 | can be used. |
| 2330 | <code>Request</code> is a struct containing a parsed representation |
| 2331 | of the request from the client. |
| 2332 | </p> |
| 2333 | <p> |
| 2334 | For brevity, let's ignore POSTs and assume HTTP requests are always |
| 2335 | GETs; that simplification does not affect the way the handlers are |
| 2336 | set up. Here's a trivial but complete implementation of a handler to |
| 2337 | count the number of times the |
| 2338 | page is visited. |
| 2339 | </p> |
| 2340 | <pre> |
| 2341 | // Simple counter server. |
| 2342 | type Counter struct { |
| 2343 | n int |
| 2344 | } |
| 2345 | |
| 2346 | func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) { |
| 2347 | ctr.n++ |
| 2348 | fmt.Fprintf(w, "counter = %d\n", ctr.n) |
| 2349 | } |
| 2350 | </pre> |
| 2351 | <p> |
| 2352 | (Keeping with our theme, note how <code>Fprintf</code> can print to an |
| 2353 | <code>http.ResponseWriter</code>.) |
| 2354 | For reference, here's how to attach such a server to a node on the URL tree. |
| 2355 | </p> |
| 2356 | <pre> |
| 2357 | import "net/http" |
| 2358 | ... |
| 2359 | ctr := new(Counter) |
| 2360 | http.Handle("/counter", ctr) |
| 2361 | </pre> |
| 2362 | <p> |
| 2363 | But why make <code>Counter</code> a struct? An integer is all that's needed. |
| 2364 | (The receiver needs to be a pointer so the increment is visible to the caller.) |
| 2365 | </p> |
| 2366 | <pre> |
| 2367 | // Simpler counter server. |
| 2368 | type Counter int |
| 2369 | |
| 2370 | func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) { |
| 2371 | *ctr++ |
| 2372 | fmt.Fprintf(w, "counter = %d\n", *ctr) |
| 2373 | } |
| 2374 | </pre> |
| 2375 | <p> |
| 2376 | What if your program has some internal state that needs to be notified that a page |
| 2377 | has been visited? Tie a channel to the web page. |
| 2378 | </p> |
| 2379 | <pre> |
| 2380 | // A channel that sends a notification on each visit. |
| 2381 | // (Probably want the channel to be buffered.) |
| 2382 | type Chan chan *http.Request |
| 2383 | |
| 2384 | func (ch Chan) ServeHTTP(w http.ResponseWriter, req *http.Request) { |
| 2385 | ch <- req |
| 2386 | fmt.Fprint(w, "notification sent") |
| 2387 | } |
| 2388 | </pre> |
| 2389 | <p> |
| 2390 | Finally, let's say we wanted to present on <code>/args</code> the arguments |
| 2391 | used when invoking the server binary. |
| 2392 | It's easy to write a function to print the arguments. |
| 2393 | </p> |
| 2394 | <pre> |
| 2395 | func ArgServer() { |
| 2396 | fmt.Println(os.Args) |
| 2397 | } |
| 2398 | </pre> |
| 2399 | <p> |
| 2400 | How do we turn that into an HTTP server? We could make <code>ArgServer</code> |
| 2401 | a method of some type whose value we ignore, but there's a cleaner way. |
| 2402 | Since we can define a method for any type except pointers and interfaces, |
| 2403 | we can write a method for a function. |
| 2404 | The <code>http</code> package contains this code: |
| 2405 | </p> |
| 2406 | <pre> |
| 2407 | // The HandlerFunc type is an adapter to allow the use of |
| 2408 | // ordinary functions as HTTP handlers. If f is a function |
| 2409 | // with the appropriate signature, HandlerFunc(f) is a |
| 2410 | // Handler object that calls f. |
| 2411 | type HandlerFunc func(ResponseWriter, *Request) |
| 2412 | |
| 2413 | // ServeHTTP calls f(c, req). |
| 2414 | func (f HandlerFunc) ServeHTTP(w ResponseWriter, req *Request) { |
| 2415 | f(w, req) |
| 2416 | } |
| 2417 | </pre> |
| 2418 | <p> |
| 2419 | <code>HandlerFunc</code> is a type with a method, <code>ServeHTTP</code>, |
| 2420 | so values of that type can serve HTTP requests. Look at the implementation |
| 2421 | of the method: the receiver is a function, <code>f</code>, and the method |
| 2422 | calls <code>f</code>. That may seem odd but it's not that different from, say, |
| 2423 | the receiver being a channel and the method sending on the channel. |
| 2424 | </p> |
| 2425 | <p> |
| 2426 | To make <code>ArgServer</code> into an HTTP server, we first modify it |
| 2427 | to have the right signature. |
| 2428 | </p> |
| 2429 | <pre> |
| 2430 | // Argument server. |
| 2431 | func ArgServer(w http.ResponseWriter, req *http.Request) { |
| 2432 | fmt.Fprintln(w, os.Args) |
| 2433 | } |
| 2434 | </pre> |
| 2435 | <p> |
| 2436 | <code>ArgServer</code> now has same signature as <code>HandlerFunc</code>, |
| 2437 | so it can be converted to that type to access its methods, |
| 2438 | just as we converted <code>Sequence</code> to <code>IntSlice</code> |
| 2439 | to access <code>IntSlice.Sort</code>. |
| 2440 | The code to set it up is concise: |
| 2441 | </p> |
| 2442 | <pre> |
| 2443 | http.Handle("/args", http.HandlerFunc(ArgServer)) |
| 2444 | </pre> |
| 2445 | <p> |
| 2446 | When someone visits the page <code>/args</code>, |
| 2447 | the handler installed at that page has value <code>ArgServer</code> |
| 2448 | and type <code>HandlerFunc</code>. |
| 2449 | The HTTP server will invoke the method <code>ServeHTTP</code> |
| 2450 | of that type, with <code>ArgServer</code> as the receiver, which will in turn call |
| 2451 | <code>ArgServer</code> (via the invocation <code>f(c, req)</code> |
| 2452 | inside <code>HandlerFunc.ServeHTTP</code>). |
| 2453 | The arguments will then be displayed. |
| 2454 | </p> |
| 2455 | <p> |
| 2456 | In this section we have made an HTTP server from a struct, an integer, |
| 2457 | a channel, and a function, all because interfaces are just sets of |
| 2458 | methods, which can be defined for (almost) any type. |
| 2459 | </p> |
| 2460 | |
| 2461 | <h2 id="blank">The blank identifier</h2> |
| 2462 | |
| 2463 | <p> |
| 2464 | We've mentioned the blank identifier a couple of times now, in the context of |
| 2465 | <a href="#for"><code>for</code> <code>range</code> loops</a> |
| 2466 | and <a href="#maps">maps</a>. |
| 2467 | The blank identifier can be assigned or declared with any value of any type, with the |
| 2468 | value discarded harmlessly. |
| 2469 | It's a bit like writing to the Unix <code>/dev/null</code> file: |
| 2470 | it represents a write-only value |
| 2471 | to be used as a place-holder |
| 2472 | where a variable is needed but the actual value is irrelevant. |
| 2473 | It has uses beyond those we've seen already. |
| 2474 | </p> |
| 2475 | |
| 2476 | <h3 id="blank_assign">The blank identifier in multiple assignment</h3> |
| 2477 | |
| 2478 | <p> |
| 2479 | The use of a blank identifier in a <code>for</code> <code>range</code> loop is a |
| 2480 | special case of a general situation: multiple assignment. |
| 2481 | </p> |
| 2482 | |
| 2483 | <p> |
| 2484 | If an assignment requires multiple values on the left side, |
| 2485 | but one of the values will not be used by the program, |
| 2486 | a blank identifier on the left-hand-side of |
| 2487 | the assignment avoids the need |
| 2488 | to create a dummy variable and makes it clear that the |
| 2489 | value is to be discarded. |
| 2490 | For instance, when calling a function that returns |
| 2491 | a value and an error, but only the error is important, |
| 2492 | use the blank identifier to discard the irrelevant value. |
| 2493 | </p> |
| 2494 | |
| 2495 | <pre> |
| 2496 | if _, err := os.Stat(path); os.IsNotExist(err) { |
| 2497 | fmt.Printf("%s does not exist\n", path) |
| 2498 | } |
| 2499 | </pre> |
| 2500 | |
| 2501 | <p> |
| 2502 | Occasionally you'll see code that discards the error value in order |
| 2503 | to ignore the error; this is terrible practice. Always check error returns; |
| 2504 | they're provided for a reason. |
| 2505 | </p> |
| 2506 | |
| 2507 | <pre> |
| 2508 | // Bad! This code will crash if path does not exist. |
| 2509 | fi, _ := os.Stat(path) |
| 2510 | if fi.IsDir() { |
| 2511 | fmt.Printf("%s is a directory\n", path) |
| 2512 | } |
| 2513 | </pre> |
| 2514 | |
| 2515 | <h3 id="blank_unused">Unused imports and variables</h3> |
| 2516 | |
| 2517 | <p> |
| 2518 | It is an error to import a package or to declare a variable without using it. |
| 2519 | Unused imports bloat the program and slow compilation, |
| 2520 | while a variable that is initialized but not used is at least |
| 2521 | a wasted computation and perhaps indicative of a |
| 2522 | larger bug. |
| 2523 | When a program is under active development, however, |
| 2524 | unused imports and variables often arise and it can |
| 2525 | be annoying to delete them just to have the compilation proceed, |
| 2526 | only to have them be needed again later. |
| 2527 | The blank identifier provides a workaround. |
| 2528 | </p> |
| 2529 | <p> |
| 2530 | This half-written program has two unused imports |
| 2531 | (<code>fmt</code> and <code>io</code>) |
| 2532 | and an unused variable (<code>fd</code>), |
| 2533 | so it will not compile, but it would be nice to see if the |
| 2534 | code so far is correct. |
| 2535 | </p> |
| 2536 | {{code "/doc/progs/eff_unused1.go" `/package/` `$`}} |
| 2537 | <p> |
| 2538 | To silence complaints about the unused imports, use a |
| 2539 | blank identifier to refer to a symbol from the imported package. |
| 2540 | Similarly, assigning the unused variable <code>fd</code> |
| 2541 | to the blank identifier will silence the unused variable error. |
| 2542 | This version of the program does compile. |
| 2543 | </p> |
| 2544 | {{code "/doc/progs/eff_unused2.go" `/package/` `$`}} |
| 2545 | |
| 2546 | <p> |
| 2547 | By convention, the global declarations to silence import errors |
| 2548 | should come right after the imports and be commented, |
| 2549 | both to make them easy to find and as a reminder to clean things up later. |
| 2550 | </p> |
| 2551 | |
| 2552 | <h3 id="blank_import">Import for side effect</h3> |
| 2553 | |
| 2554 | <p> |
| 2555 | An unused import like <code>fmt</code> or <code>io</code> in the |
| 2556 | previous example should eventually be used or removed: |
| 2557 | blank assignments identify code as a work in progress. |
| 2558 | But sometimes it is useful to import a package only for its |
| 2559 | side effects, without any explicit use. |
| 2560 | For example, during its <code>init</code> function, |
| 2561 | the <code><a href="/pkg/net/http/pprof/">net/http/pprof</a></code> |
| 2562 | package registers HTTP handlers that provide |
| 2563 | debugging information. It has an exported API, but |
| 2564 | most clients need only the handler registration and |
| 2565 | access the data through a web page. |
| 2566 | To import the package only for its side effects, rename the package |
| 2567 | to the blank identifier: |
| 2568 | </p> |
| 2569 | <pre> |
| 2570 | import _ "net/http/pprof" |
| 2571 | </pre> |
| 2572 | <p> |
| 2573 | This form of import makes clear that the package is being |
| 2574 | imported for its side effects, because there is no other possible |
| 2575 | use of the package: in this file, it doesn't have a name. |
| 2576 | (If it did, and we didn't use that name, the compiler would reject the program.) |
| 2577 | </p> |
| 2578 | |
| 2579 | <h3 id="blank_implements">Interface checks</h3> |
| 2580 | |
| 2581 | <p> |
| 2582 | As we saw in the discussion of <a href="#interfaces_and_types">interfaces</a> above, |
| 2583 | a type need not declare explicitly that it implements an interface. |
| 2584 | Instead, a type implements the interface just by implementing the interface's methods. |
| 2585 | In practice, most interface conversions are static and therefore checked at compile time. |
| 2586 | For example, passing an <code>*os.File</code> to a function |
| 2587 | expecting an <code>io.Reader</code> will not compile unless |
| 2588 | <code>*os.File</code> implements the <code>io.Reader</code> interface. |
| 2589 | </p> |
| 2590 | |
| 2591 | <p> |
| 2592 | Some interface checks do happen at run-time, though. |
| 2593 | One instance is in the <code><a href="/pkg/encoding/json/">encoding/json</a></code> |
| 2594 | package, which defines a <code><a href="/pkg/encoding/json/#Marshaler">Marshaler</a></code> |
| 2595 | interface. When the JSON encoder receives a value that implements that interface, |
| 2596 | the encoder invokes the value's marshaling method to convert it to JSON |
| 2597 | instead of doing the standard conversion. |
| 2598 | The encoder checks this property at run time with a <a href="#interface_conversions">type assertion</a> like: |
| 2599 | </p> |
| 2600 | |
| 2601 | <pre> |
| 2602 | m, ok := val.(json.Marshaler) |
| 2603 | </pre> |
| 2604 | |
| 2605 | <p> |
| 2606 | If it's necessary only to ask whether a type implements an interface, without |
| 2607 | actually using the interface itself, perhaps as part of an error check, use the blank |
| 2608 | identifier to ignore the type-asserted value: |
| 2609 | </p> |
| 2610 | |
| 2611 | <pre> |
| 2612 | if _, ok := val.(json.Marshaler); ok { |
| 2613 | fmt.Printf("value %v of type %T implements json.Marshaler\n", val, val) |
| 2614 | } |
| 2615 | </pre> |
| 2616 | |
| 2617 | <p> |
| 2618 | One place this situation arises is when it is necessary to guarantee within the package implementing the type that |
| 2619 | it actually satisfies the interface. |
| 2620 | If a type—for example, |
| 2621 | <code><a href="/pkg/encoding/json/#RawMessage">json.RawMessage</a></code>—needs |
| 2622 | a custom JSON representation, it should implement |
| 2623 | <code>json.Marshaler</code>, but there are no static conversions that would |
| 2624 | cause the compiler to verify this automatically. |
| 2625 | If the type inadvertently fails to satisfy the interface, the JSON encoder will still work, |
| 2626 | but will not use the custom implementation. |
| 2627 | To guarantee that the implementation is correct, |
| 2628 | a global declaration using the blank identifier can be used in the package: |
| 2629 | </p> |
| 2630 | <pre> |
| 2631 | var _ json.Marshaler = (*RawMessage)(nil) |
| 2632 | </pre> |
| 2633 | <p> |
| 2634 | In this declaration, the assignment involving a conversion of a |
| 2635 | <code>*RawMessage</code> to a <code>Marshaler</code> |
| 2636 | requires that <code>*RawMessage</code> implements <code>Marshaler</code>, |
| 2637 | and that property will be checked at compile time. |
| 2638 | Should the <code>json.Marshaler</code> interface change, this package |
| 2639 | will no longer compile and we will be on notice that it needs to be updated. |
| 2640 | </p> |
| 2641 | |
| 2642 | <p> |
| 2643 | The appearance of the blank identifier in this construct indicates that |
| 2644 | the declaration exists only for the type checking, |
| 2645 | not to create a variable. |
| 2646 | Don't do this for every type that satisfies an interface, though. |
| 2647 | By convention, such declarations are only used |
| 2648 | when there are no static conversions already present in the code, |
| 2649 | which is a rare event. |
| 2650 | </p> |
| 2651 | |
| 2652 | |
| 2653 | <h2 id="embedding">Embedding</h2> |
| 2654 | |
| 2655 | <p> |
| 2656 | Go does not provide the typical, type-driven notion of subclassing, |
| 2657 | but it does have the ability to “borrow” pieces of an |
| 2658 | implementation by <em>embedding</em> types within a struct or |
| 2659 | interface. |
| 2660 | </p> |
| 2661 | <p> |
| 2662 | Interface embedding is very simple. |
| 2663 | We've mentioned the <code>io.Reader</code> and <code>io.Writer</code> interfaces before; |
| 2664 | here are their definitions. |
| 2665 | </p> |
| 2666 | <pre> |
| 2667 | type Reader interface { |
| 2668 | Read(p []byte) (n int, err error) |
| 2669 | } |
| 2670 | |
| 2671 | type Writer interface { |
| 2672 | Write(p []byte) (n int, err error) |
| 2673 | } |
| 2674 | </pre> |
| 2675 | <p> |
| 2676 | The <code>io</code> package also exports several other interfaces |
| 2677 | that specify objects that can implement several such methods. |
| 2678 | For instance, there is <code>io.ReadWriter</code>, an interface |
| 2679 | containing both <code>Read</code> and <code>Write</code>. |
| 2680 | We could specify <code>io.ReadWriter</code> by listing the |
| 2681 | two methods explicitly, but it's easier and more evocative |
| 2682 | to embed the two interfaces to form the new one, like this: |
| 2683 | </p> |
| 2684 | <pre> |
| 2685 | // ReadWriter is the interface that combines the Reader and Writer interfaces. |
| 2686 | type ReadWriter interface { |
| 2687 | Reader |
| 2688 | Writer |
| 2689 | } |
| 2690 | </pre> |
| 2691 | <p> |
| 2692 | This says just what it looks like: A <code>ReadWriter</code> can do |
| 2693 | what a <code>Reader</code> does <em>and</em> what a <code>Writer</code> |
| 2694 | does; it is a union of the embedded interfaces (which must be disjoint |
| 2695 | sets of methods). |
| 2696 | Only interfaces can be embedded within interfaces. |
| 2697 | </p> |
| 2698 | <p> |
| 2699 | The same basic idea applies to structs, but with more far-reaching |
| 2700 | implications. The <code>bufio</code> package has two struct types, |
| 2701 | <code>bufio.Reader</code> and <code>bufio.Writer</code>, each of |
| 2702 | which of course implements the analogous interfaces from package |
| 2703 | <code>io</code>. |
| 2704 | And <code>bufio</code> also implements a buffered reader/writer, |
| 2705 | which it does by combining a reader and a writer into one struct |
| 2706 | using embedding: it lists the types within the struct |
| 2707 | but does not give them field names. |
| 2708 | </p> |
| 2709 | <pre> |
| 2710 | // ReadWriter stores pointers to a Reader and a Writer. |
| 2711 | // It implements io.ReadWriter. |
| 2712 | type ReadWriter struct { |
| 2713 | *Reader // *bufio.Reader |
| 2714 | *Writer // *bufio.Writer |
| 2715 | } |
| 2716 | </pre> |
| 2717 | <p> |
| 2718 | The embedded elements are pointers to structs and of course |
| 2719 | must be initialized to point to valid structs before they |
| 2720 | can be used. |
| 2721 | The <code>ReadWriter</code> struct could be written as |
| 2722 | </p> |
| 2723 | <pre> |
| 2724 | type ReadWriter struct { |
| 2725 | reader *Reader |
| 2726 | writer *Writer |
| 2727 | } |
| 2728 | </pre> |
| 2729 | <p> |
| 2730 | but then to promote the methods of the fields and to |
| 2731 | satisfy the <code>io</code> interfaces, we would also need |
| 2732 | to provide forwarding methods, like this: |
| 2733 | </p> |
| 2734 | <pre> |
| 2735 | func (rw *ReadWriter) Read(p []byte) (n int, err error) { |
| 2736 | return rw.reader.Read(p) |
| 2737 | } |
| 2738 | </pre> |
| 2739 | <p> |
| 2740 | By embedding the structs directly, we avoid this bookkeeping. |
| 2741 | The methods of embedded types come along for free, which means that <code>bufio.ReadWriter</code> |
| 2742 | not only has the methods of <code>bufio.Reader</code> and <code>bufio.Writer</code>, |
| 2743 | it also satisfies all three interfaces: |
| 2744 | <code>io.Reader</code>, |
| 2745 | <code>io.Writer</code>, and |
| 2746 | <code>io.ReadWriter</code>. |
| 2747 | </p> |
| 2748 | <p> |
| 2749 | There's an important way in which embedding differs from subclassing. When we embed a type, |
| 2750 | the methods of that type become methods of the outer type, |
| 2751 | but when they are invoked the receiver of the method is the inner type, not the outer one. |
| 2752 | In our example, when the <code>Read</code> method of a <code>bufio.ReadWriter</code> is |
| 2753 | invoked, it has exactly the same effect as the forwarding method written out above; |
| 2754 | the receiver is the <code>reader</code> field of the <code>ReadWriter</code>, not the |
| 2755 | <code>ReadWriter</code> itself. |
| 2756 | </p> |
| 2757 | <p> |
| 2758 | Embedding can also be a simple convenience. |
| 2759 | This example shows an embedded field alongside a regular, named field. |
| 2760 | </p> |
| 2761 | <pre> |
| 2762 | type Job struct { |
| 2763 | Command string |
| 2764 | *log.Logger |
| 2765 | } |
| 2766 | </pre> |
| 2767 | <p> |
| 2768 | The <code>Job</code> type now has the <code>Log</code>, <code>Logf</code> |
| 2769 | and other |
| 2770 | methods of <code>*log.Logger</code>. We could have given the <code>Logger</code> |
| 2771 | a field name, of course, but it's not necessary to do so. And now, once |
| 2772 | initialized, we can |
| 2773 | log to the <code>Job</code>: |
| 2774 | </p> |
| 2775 | <pre> |
| 2776 | job.Log("starting now...") |
| 2777 | </pre> |
| 2778 | <p> |
| 2779 | The <code>Logger</code> is a regular field of the <code>Job</code> struct, |
| 2780 | so we can initialize it in the usual way inside the constructor for <code>Job</code>, like this, |
| 2781 | </p> |
| 2782 | <pre> |
| 2783 | func NewJob(command string, logger *log.Logger) *Job { |
| 2784 | return &Job{command, logger} |
| 2785 | } |
| 2786 | </pre> |
| 2787 | <p> |
| 2788 | or with a composite literal, |
| 2789 | </p> |
| 2790 | <pre> |
| 2791 | job := &Job{command, log.New(os.Stderr, "Job: ", log.Ldate)} |
| 2792 | </pre> |
| 2793 | <p> |
| 2794 | If we need to refer to an embedded field directly, the type name of the field, |
| 2795 | ignoring the package qualifier, serves as a field name, as it did |
| 2796 | in the <code>Read</code> method of our <code>ReaderWriter</code> struct. |
| 2797 | Here, if we needed to access the |
| 2798 | <code>*log.Logger</code> of a <code>Job</code> variable <code>job</code>, |
| 2799 | we would write <code>job.Logger</code>, |
| 2800 | which would be useful if we wanted to refine the methods of <code>Logger</code>. |
| 2801 | </p> |
| 2802 | <pre> |
| 2803 | func (job *Job) Logf(format string, args ...interface{}) { |
| 2804 | job.Logger.Logf("%q: %s", job.Command, fmt.Sprintf(format, args...)) |
| 2805 | } |
| 2806 | </pre> |
| 2807 | <p> |
| 2808 | Embedding types introduces the problem of name conflicts but the rules to resolve |
| 2809 | them are simple. |
| 2810 | First, a field or method <code>X</code> hides any other item <code>X</code> in a more deeply |
| 2811 | nested part of the type. |
| 2812 | If <code>log.Logger</code> contained a field or method called <code>Command</code>, the <code>Command</code> field |
| 2813 | of <code>Job</code> would dominate it. |
| 2814 | </p> |
| 2815 | <p> |
| 2816 | Second, if the same name appears at the same nesting level, it is usually an error; |
| 2817 | it would be erroneous to embed <code>log.Logger</code> if the <code>Job</code> struct |
| 2818 | contained another field or method called <code>Logger</code>. |
| 2819 | However, if the duplicate name is never mentioned in the program outside the type definition, it is OK. |
| 2820 | This qualification provides some protection against changes made to types embedded from outside; there |
| 2821 | is no problem if a field is added that conflicts with another field in another subtype if neither field |
| 2822 | is ever used. |
| 2823 | </p> |
| 2824 | |
| 2825 | |
| 2826 | <h2 id="concurrency">Concurrency</h2> |
| 2827 | |
| 2828 | <h3 id="sharing">Share by communicating</h3> |
| 2829 | |
| 2830 | <p> |
| 2831 | Concurrent programming is a large topic and there is space only for some |
| 2832 | Go-specific highlights here. |
| 2833 | </p> |
| 2834 | <p> |
| 2835 | Concurrent programming in many environments is made difficult by the |
| 2836 | subtleties required to implement correct access to shared variables. Go encourages |
| 2837 | a different approach in which shared values are passed around on channels |
| 2838 | and, in fact, never actively shared by separate threads of execution. |
| 2839 | Only one goroutine has access to the value at any given time. |
| 2840 | Data races cannot occur, by design. |
| 2841 | To encourage this way of thinking we have reduced it to a slogan: |
| 2842 | </p> |
| 2843 | <blockquote> |
| 2844 | Do not communicate by sharing memory; |
| 2845 | instead, share memory by communicating. |
| 2846 | </blockquote> |
| 2847 | <p> |
| 2848 | This approach can be taken too far. Reference counts may be best done |
| 2849 | by putting a mutex around an integer variable, for instance. But as a |
| 2850 | high-level approach, using channels to control access makes it easier |
| 2851 | to write clear, correct programs. |
| 2852 | </p> |
| 2853 | <p> |
| 2854 | One way to think about this model is to consider a typical single-threaded |
| 2855 | program running on one CPU. It has no need for synchronization primitives. |
| 2856 | Now run another such instance; it too needs no synchronization. Now let those |
| 2857 | two communicate; if the communication is the synchronizer, there's still no need |
| 2858 | for other synchronization. Unix pipelines, for example, fit this model |
| 2859 | perfectly. Although Go's approach to concurrency originates in Hoare's |
| 2860 | Communicating Sequential Processes (CSP), |
| 2861 | it can also be seen as a type-safe generalization of Unix pipes. |
| 2862 | </p> |
| 2863 | |
| 2864 | <h3 id="goroutines">Goroutines</h3> |
| 2865 | |
| 2866 | <p> |
| 2867 | They're called <em>goroutines</em> because the existing |
| 2868 | terms—threads, coroutines, processes, and so on—convey |
| 2869 | inaccurate connotations. A goroutine has a simple model: it is a |
| 2870 | function executing concurrently with other goroutines in the same |
| 2871 | address space. It is lightweight, costing little more than the |
| 2872 | allocation of stack space. |
| 2873 | And the stacks start small, so they are cheap, and grow |
| 2874 | by allocating (and freeing) heap storage as required. |
| 2875 | </p> |
| 2876 | <p> |
| 2877 | Goroutines are multiplexed onto multiple OS threads so if one should |
| 2878 | block, such as while waiting for I/O, others continue to run. Their |
| 2879 | design hides many of the complexities of thread creation and |
| 2880 | management. |
| 2881 | </p> |
| 2882 | <p> |
| 2883 | Prefix a function or method call with the <code>go</code> |
| 2884 | keyword to run the call in a new goroutine. |
| 2885 | When the call completes, the goroutine |
| 2886 | exits, silently. (The effect is similar to the Unix shell's |
| 2887 | <code>&</code> notation for running a command in the |
| 2888 | background.) |
| 2889 | </p> |
| 2890 | <pre> |
| 2891 | go list.Sort() // run list.Sort concurrently; don't wait for it. |
| 2892 | </pre> |
| 2893 | <p> |
| 2894 | A function literal can be handy in a goroutine invocation. |
| 2895 | </p> |
| 2896 | <pre> |
| 2897 | func Announce(message string, delay time.Duration) { |
| 2898 | go func() { |
| 2899 | time.Sleep(delay) |
| 2900 | fmt.Println(message) |
| 2901 | }() // Note the parentheses - must call the function. |
| 2902 | } |
| 2903 | </pre> |
| 2904 | <p> |
| 2905 | In Go, function literals are closures: the implementation makes |
| 2906 | sure the variables referred to by the function survive as long as they are active. |
| 2907 | </p> |
| 2908 | <p> |
| 2909 | These examples aren't too practical because the functions have no way of signaling |
| 2910 | completion. For that, we need channels. |
| 2911 | </p> |
| 2912 | |
| 2913 | <h3 id="channels">Channels</h3> |
| 2914 | |
| 2915 | <p> |
| 2916 | Like maps, channels are allocated with <code>make</code>, and |
| 2917 | the resulting value acts as a reference to an underlying data structure. |
| 2918 | If an optional integer parameter is provided, it sets the buffer size for the channel. |
| 2919 | The default is zero, for an unbuffered or synchronous channel. |
| 2920 | </p> |
| 2921 | <pre> |
| 2922 | ci := make(chan int) // unbuffered channel of integers |
| 2923 | cj := make(chan int, 0) // unbuffered channel of integers |
| 2924 | cs := make(chan *os.File, 100) // buffered channel of pointers to Files |
| 2925 | </pre> |
| 2926 | <p> |
| 2927 | Unbuffered channels combine communication—the exchange of a value—with |
| 2928 | synchronization—guaranteeing that two calculations (goroutines) are in |
| 2929 | a known state. |
| 2930 | </p> |
| 2931 | <p> |
| 2932 | There are lots of nice idioms using channels. Here's one to get us started. |
| 2933 | In the previous section we launched a sort in the background. A channel |
| 2934 | can allow the launching goroutine to wait for the sort to complete. |
| 2935 | </p> |
| 2936 | <pre> |
| 2937 | c := make(chan int) // Allocate a channel. |
| 2938 | // Start the sort in a goroutine; when it completes, signal on the channel. |
| 2939 | go func() { |
| 2940 | list.Sort() |
| 2941 | c <- 1 // Send a signal; value does not matter. |
| 2942 | }() |
| 2943 | doSomethingForAWhile() |
| 2944 | <-c // Wait for sort to finish; discard sent value. |
| 2945 | </pre> |
| 2946 | <p> |
| 2947 | Receivers always block until there is data to receive. |
| 2948 | If the channel is unbuffered, the sender blocks until the receiver has |
| 2949 | received the value. |
| 2950 | If the channel has a buffer, the sender blocks only until the |
| 2951 | value has been copied to the buffer; if the buffer is full, this |
| 2952 | means waiting until some receiver has retrieved a value. |
| 2953 | </p> |
| 2954 | <p> |
| 2955 | A buffered channel can be used like a semaphore, for instance to |
| 2956 | limit throughput. In this example, incoming requests are passed |
| 2957 | to <code>handle</code>, which sends a value into the channel, processes |
| 2958 | the request, and then receives a value from the channel |
| 2959 | to ready the “semaphore” for the next consumer. |
| 2960 | The capacity of the channel buffer limits the number of |
| 2961 | simultaneous calls to <code>process</code>. |
| 2962 | </p> |
| 2963 | <pre> |
| 2964 | var sem = make(chan int, MaxOutstanding) |
| 2965 | |
| 2966 | func handle(r *Request) { |
| 2967 | sem <- 1 // Wait for active queue to drain. |
| 2968 | process(r) // May take a long time. |
| 2969 | <-sem // Done; enable next request to run. |
| 2970 | } |
| 2971 | |
| 2972 | func Serve(queue chan *Request) { |
| 2973 | for { |
| 2974 | req := <-queue |
| 2975 | go handle(req) // Don't wait for handle to finish. |
| 2976 | } |
| 2977 | } |
| 2978 | </pre> |
| 2979 | |
| 2980 | <p> |
| 2981 | Once <code>MaxOutstanding</code> handlers are executing <code>process</code>, |
| 2982 | any more will block trying to send into the filled channel buffer, |
| 2983 | until one of the existing handlers finishes and receives from the buffer. |
| 2984 | </p> |
| 2985 | |
| 2986 | <p> |
| 2987 | This design has a problem, though: <code>Serve</code> |
| 2988 | creates a new goroutine for |
| 2989 | every incoming request, even though only <code>MaxOutstanding</code> |
| 2990 | of them can run at any moment. |
| 2991 | As a result, the program can consume unlimited resources if the requests come in too fast. |
| 2992 | We can address that deficiency by changing <code>Serve</code> to |
| 2993 | gate the creation of the goroutines. |
| 2994 | Here's an obvious solution, but beware it has a bug we'll fix subsequently: |
| 2995 | </p> |
| 2996 | |
| 2997 | <pre> |
| 2998 | func Serve(queue chan *Request) { |
| 2999 | for req := range queue { |
| 3000 | sem <- 1 |
| 3001 | go func() { |
| 3002 | process(req) // Buggy; see explanation below. |
| 3003 | <-sem |
| 3004 | }() |
| 3005 | } |
| 3006 | }</pre> |
| 3007 | |
| 3008 | <p> |
| 3009 | The bug is that in a Go <code>for</code> loop, the loop variable |
| 3010 | is reused for each iteration, so the <code>req</code> |
| 3011 | variable is shared across all goroutines. |
| 3012 | That's not what we want. |
| 3013 | We need to make sure that <code>req</code> is unique for each goroutine. |
| 3014 | Here's one way to do that, passing the value of <code>req</code> as an argument |
| 3015 | to the closure in the goroutine: |
| 3016 | </p> |
| 3017 | |
| 3018 | <pre> |
| 3019 | func Serve(queue chan *Request) { |
| 3020 | for req := range queue { |
| 3021 | sem <- 1 |
| 3022 | go func(req *Request) { |
| 3023 | process(req) |
| 3024 | <-sem |
| 3025 | }(req) |
| 3026 | } |
| 3027 | }</pre> |
| 3028 | |
| 3029 | <p> |
| 3030 | Compare this version with the previous to see the difference in how |
| 3031 | the closure is declared and run. |
| 3032 | Another solution is just to create a new variable with the same |
| 3033 | name, as in this example: |
| 3034 | </p> |
| 3035 | |
| 3036 | <pre> |
| 3037 | func Serve(queue chan *Request) { |
| 3038 | for req := range queue { |
| 3039 | req := req // Create new instance of req for the goroutine. |
| 3040 | sem <- 1 |
| 3041 | go func() { |
| 3042 | process(req) |
| 3043 | <-sem |
| 3044 | }() |
| 3045 | } |
| 3046 | }</pre> |
| 3047 | |
| 3048 | <p> |
| 3049 | It may seem odd to write |
| 3050 | </p> |
| 3051 | |
| 3052 | <pre> |
| 3053 | req := req |
| 3054 | </pre> |
| 3055 | |
| 3056 | <p> |
| 3057 | but it's a legal and idiomatic in Go to do this. |
| 3058 | You get a fresh version of the variable with the same name, deliberately |
| 3059 | shadowing the loop variable locally but unique to each goroutine. |
| 3060 | </p> |
| 3061 | |
| 3062 | <p> |
| 3063 | Going back to the general problem of writing the server, |
| 3064 | another approach that manages resources well is to start a fixed |
| 3065 | number of <code>handle</code> goroutines all reading from the request |
| 3066 | channel. |
| 3067 | The number of goroutines limits the number of simultaneous |
| 3068 | calls to <code>process</code>. |
| 3069 | This <code>Serve</code> function also accepts a channel on which |
| 3070 | it will be told to exit; after launching the goroutines it blocks |
| 3071 | receiving from that channel. |
| 3072 | </p> |
| 3073 | |
| 3074 | <pre> |
| 3075 | func handle(queue chan *Request) { |
| 3076 | for r := range queue { |
| 3077 | process(r) |
| 3078 | } |
| 3079 | } |
| 3080 | |
| 3081 | func Serve(clientRequests chan *Request, quit chan bool) { |
| 3082 | // Start handlers |
| 3083 | for i := 0; i < MaxOutstanding; i++ { |
| 3084 | go handle(clientRequests) |
| 3085 | } |
| 3086 | <-quit // Wait to be told to exit. |
| 3087 | } |
| 3088 | </pre> |
| 3089 | |
| 3090 | <h3 id="chan_of_chan">Channels of channels</h3> |
| 3091 | <p> |
| 3092 | One of the most important properties of Go is that |
| 3093 | a channel is a first-class value that can be allocated and passed |
| 3094 | around like any other. A common use of this property is |
| 3095 | to implement safe, parallel demultiplexing. |
| 3096 | </p> |
| 3097 | <p> |
| 3098 | In the example in the previous section, <code>handle</code> was |
| 3099 | an idealized handler for a request but we didn't define the |
| 3100 | type it was handling. If that type includes a channel on which |
| 3101 | to reply, each client can provide its own path for the answer. |
| 3102 | Here's a schematic definition of type <code>Request</code>. |
| 3103 | </p> |
| 3104 | <pre> |
| 3105 | type Request struct { |
| 3106 | args []int |
| 3107 | f func([]int) int |
| 3108 | resultChan chan int |
| 3109 | } |
| 3110 | </pre> |
| 3111 | <p> |
| 3112 | The client provides a function and its arguments, as well as |
| 3113 | a channel inside the request object on which to receive the answer. |
| 3114 | </p> |
| 3115 | <pre> |
| 3116 | func sum(a []int) (s int) { |
| 3117 | for _, v := range a { |
| 3118 | s += v |
| 3119 | } |
| 3120 | return |
| 3121 | } |
| 3122 | |
| 3123 | request := &Request{[]int{3, 4, 5}, sum, make(chan int)} |
| 3124 | // Send request |
| 3125 | clientRequests <- request |
| 3126 | // Wait for response. |
| 3127 | fmt.Printf("answer: %d\n", <-request.resultChan) |
| 3128 | </pre> |
| 3129 | <p> |
| 3130 | On the server side, the handler function is the only thing that changes. |
| 3131 | </p> |
| 3132 | <pre> |
| 3133 | func handle(queue chan *Request) { |
| 3134 | for req := range queue { |
| 3135 | req.resultChan <- req.f(req.args) |
| 3136 | } |
| 3137 | } |
| 3138 | </pre> |
| 3139 | <p> |
| 3140 | There's clearly a lot more to do to make it realistic, but this |
| 3141 | code is a framework for a rate-limited, parallel, non-blocking RPC |
| 3142 | system, and there's not a mutex in sight. |
| 3143 | </p> |
| 3144 | |
| 3145 | <h3 id="parallel">Parallelization</h3> |
| 3146 | <p> |
| 3147 | Another application of these ideas is to parallelize a calculation |
| 3148 | across multiple CPU cores. If the calculation can be broken into |
| 3149 | separate pieces that can execute independently, it can be parallelized, |
| 3150 | with a channel to signal when each piece completes. |
| 3151 | </p> |
| 3152 | <p> |
| 3153 | Let's say we have an expensive operation to perform on a vector of items, |
| 3154 | and that the value of the operation on each item is independent, |
| 3155 | as in this idealized example. |
| 3156 | </p> |
| 3157 | <pre> |
| 3158 | type Vector []float64 |
| 3159 | |
| 3160 | // Apply the operation to v[i], v[i+1] ... up to v[n-1]. |
| 3161 | func (v Vector) DoSome(i, n int, u Vector, c chan int) { |
| 3162 | for ; i < n; i++ { |
| 3163 | v[i] += u.Op(v[i]) |
| 3164 | } |
| 3165 | c <- 1 // signal that this piece is done |
| 3166 | } |
| 3167 | </pre> |
| 3168 | <p> |
| 3169 | We launch the pieces independently in a loop, one per CPU. |
| 3170 | They can complete in any order but it doesn't matter; we just |
| 3171 | count the completion signals by draining the channel after |
| 3172 | launching all the goroutines. |
| 3173 | </p> |
| 3174 | <pre> |
| 3175 | const NCPU = 4 // number of CPU cores |
| 3176 | |
| 3177 | func (v Vector) DoAll(u Vector) { |
| 3178 | c := make(chan int, NCPU) // Buffering optional but sensible. |
| 3179 | for i := 0; i < NCPU; i++ { |
| 3180 | go v.DoSome(i*len(v)/NCPU, (i+1)*len(v)/NCPU, u, c) |
| 3181 | } |
| 3182 | // Drain the channel. |
| 3183 | for i := 0; i < NCPU; i++ { |
| 3184 | <-c // wait for one task to complete |
| 3185 | } |
| 3186 | // All done. |
| 3187 | } |
| 3188 | |
| 3189 | </pre> |
| 3190 | |
| 3191 | <p> |
| 3192 | The current implementation of the Go runtime |
| 3193 | will not parallelize this code by default. |
| 3194 | It dedicates only a single core to user-level processing. An |
| 3195 | arbitrary number of goroutines can be blocked in system calls, but |
| 3196 | by default only one can be executing user-level code at any time. |
| 3197 | It should be smarter and one day it will be smarter, but until it |
| 3198 | is if you want CPU parallelism you must tell the run-time |
| 3199 | how many goroutines you want executing code simultaneously. There |
| 3200 | are two related ways to do this. Either run your job with environment |
| 3201 | variable <code>GOMAXPROCS</code> set to the number of cores to use |
| 3202 | or import the <code>runtime</code> package and call |
| 3203 | <code>runtime.GOMAXPROCS(NCPU)</code>. |
| 3204 | A helpful value might be <code>runtime.NumCPU()</code>, which reports the number |
| 3205 | of logical CPUs on the local machine. |
| 3206 | Again, this requirement is expected to be retired as the scheduling and run-time improve. |
| 3207 | </p> |
| 3208 | |
| 3209 | <p> |
| 3210 | Be sure not to confuse the ideas of concurrency—structuring a program |
| 3211 | as independently executing components—and parallelism—executing |
| 3212 | calculations in parallel for efficiency on multiple CPUs. |
| 3213 | Although the concurrency features of Go can make some problems easy |
| 3214 | to structure as parallel computations, Go is a concurrent language, |
| 3215 | not a parallel one, and not all parallelization problems fit Go's model. |
| 3216 | For a discussion of the distinction, see the talk cited in |
| 3217 | <a href="//blog.golang.org/2013/01/concurrency-is-not-parallelism.html">this |
| 3218 | blog post</a>. |
| 3219 | |
| 3220 | <h3 id="leaky_buffer">A leaky buffer</h3> |
| 3221 | |
| 3222 | <p> |
| 3223 | The tools of concurrent programming can even make non-concurrent |
| 3224 | ideas easier to express. Here's an example abstracted from an RPC |
| 3225 | package. The client goroutine loops receiving data from some source, |
| 3226 | perhaps a network. To avoid allocating and freeing buffers, it keeps |
| 3227 | a free list, and uses a buffered channel to represent it. If the |
| 3228 | channel is empty, a new buffer gets allocated. |
| 3229 | Once the message buffer is ready, it's sent to the server on |
| 3230 | <code>serverChan</code>. |
| 3231 | </p> |
| 3232 | <pre> |
| 3233 | var freeList = make(chan *Buffer, 100) |
| 3234 | var serverChan = make(chan *Buffer) |
| 3235 | |
| 3236 | func client() { |
| 3237 | for { |
| 3238 | var b *Buffer |
| 3239 | // Grab a buffer if available; allocate if not. |
| 3240 | select { |
| 3241 | case b = <-freeList: |
| 3242 | // Got one; nothing more to do. |
| 3243 | default: |
| 3244 | // None free, so allocate a new one. |
| 3245 | b = new(Buffer) |
| 3246 | } |
| 3247 | load(b) // Read next message from the net. |
| 3248 | serverChan <- b // Send to server. |
| 3249 | } |
| 3250 | } |
| 3251 | </pre> |
| 3252 | <p> |
| 3253 | The server loop receives each message from the client, processes it, |
| 3254 | and returns the buffer to the free list. |
| 3255 | </p> |
| 3256 | <pre> |
| 3257 | func server() { |
| 3258 | for { |
| 3259 | b := <-serverChan // Wait for work. |
| 3260 | process(b) |
| 3261 | // Reuse buffer if there's room. |
| 3262 | select { |
| 3263 | case freeList <- b: |
| 3264 | // Buffer on free list; nothing more to do. |
| 3265 | default: |
| 3266 | // Free list full, just carry on. |
| 3267 | } |
| 3268 | } |
| 3269 | } |
| 3270 | </pre> |
| 3271 | <p> |
| 3272 | The client attempts to retrieve a buffer from <code>freeList</code>; |
| 3273 | if none is available, it allocates a fresh one. |
| 3274 | The server's send to <code>freeList</code> puts <code>b</code> back |
| 3275 | on the free list unless the list is full, in which case the |
| 3276 | buffer is dropped on the floor to be reclaimed by |
| 3277 | the garbage collector. |
| 3278 | (The <code>default</code> clauses in the <code>select</code> |
| 3279 | statements execute when no other case is ready, |
| 3280 | meaning that the <code>selects</code> never block.) |
| 3281 | This implementation builds a leaky bucket free list |
| 3282 | in just a few lines, relying on the buffered channel and |
| 3283 | the garbage collector for bookkeeping. |
| 3284 | </p> |
| 3285 | |
| 3286 | <h2 id="errors">Errors</h2> |
| 3287 | |
| 3288 | <p> |
| 3289 | Library routines must often return some sort of error indication to |
| 3290 | the caller. |
| 3291 | As mentioned earlier, Go's multivalue return makes it |
| 3292 | easy to return a detailed error description alongside the normal |
| 3293 | return value. |
| 3294 | It is good style to use this feature to provide detailed error information. |
| 3295 | For example, as we'll see, <code>os.Open</code> doesn't |
| 3296 | just return a <code>nil</code> pointer on failure, it also returns an |
| 3297 | error value that describes what went wrong. |
| 3298 | </p> |
| 3299 | |
| 3300 | <p> |
| 3301 | By convention, errors have type <code>error</code>, |
| 3302 | a simple built-in interface. |
| 3303 | </p> |
| 3304 | <pre> |
| 3305 | type error interface { |
| 3306 | Error() string |
| 3307 | } |
| 3308 | </pre> |
| 3309 | <p> |
| 3310 | A library writer is free to implement this interface with a |
| 3311 | richer model under the covers, making it possible not only |
| 3312 | to see the error but also to provide some context. |
| 3313 | As mentioned, alongside the usual <code>*os.File</code> |
| 3314 | return value, <code>os.Open</code> also returns an |
| 3315 | error value. |
| 3316 | If the file is opened successfully, the error will be <code>nil</code>, |
| 3317 | but when there is a problem, it will hold an |
| 3318 | <code>os.PathError</code>: |
| 3319 | </p> |
| 3320 | <pre> |
| 3321 | // PathError records an error and the operation and |
| 3322 | // file path that caused it. |
| 3323 | type PathError struct { |
| 3324 | Op string // "open", "unlink", etc. |
| 3325 | Path string // The associated file. |
| 3326 | Err error // Returned by the system call. |
| 3327 | } |
| 3328 | |
| 3329 | func (e *PathError) Error() string { |
| 3330 | return e.Op + " " + e.Path + ": " + e.Err.Error() |
| 3331 | } |
| 3332 | </pre> |
| 3333 | <p> |
| 3334 | <code>PathError</code>'s <code>Error</code> generates |
| 3335 | a string like this: |
| 3336 | </p> |
| 3337 | <pre> |
| 3338 | open /etc/passwx: no such file or directory |
| 3339 | </pre> |
| 3340 | <p> |
| 3341 | Such an error, which includes the problematic file name, the |
| 3342 | operation, and the operating system error it triggered, is useful even |
| 3343 | if printed far from the call that caused it; |
| 3344 | it is much more informative than the plain |
| 3345 | "no such file or directory". |
| 3346 | </p> |
| 3347 | |
| 3348 | <p> |
| 3349 | When feasible, error strings should identify their origin, such as by having |
| 3350 | a prefix naming the operation or package that generated the error. For example, in package |
| 3351 | <code>image</code>, the string representation for a decoding error due to an |
| 3352 | unknown format is "image: unknown format". |
| 3353 | </p> |
| 3354 | |
| 3355 | <p> |
| 3356 | Callers that care about the precise error details can |
| 3357 | use a type switch or a type assertion to look for specific |
| 3358 | errors and extract details. For <code>PathErrors</code> |
| 3359 | this might include examining the internal <code>Err</code> |
| 3360 | field for recoverable failures. |
| 3361 | </p> |
| 3362 | |
| 3363 | <pre> |
| 3364 | for try := 0; try < 2; try++ { |
| 3365 | file, err = os.Create(filename) |
| 3366 | if err == nil { |
| 3367 | return |
| 3368 | } |
| 3369 | if e, ok := err.(*os.PathError); ok && e.Err == syscall.ENOSPC { |
| 3370 | deleteTempFiles() // Recover some space. |
| 3371 | continue |
| 3372 | } |
| 3373 | return |
| 3374 | } |
| 3375 | </pre> |
| 3376 | |
| 3377 | <p> |
| 3378 | The second <code>if</code> statement here is another <a href="#interface_conversions">type assertion</a>. |
| 3379 | If it fails, <code>ok</code> will be false, and <code>e</code> |
| 3380 | will be <code>nil</code>. |
| 3381 | If it succeeds, <code>ok</code> will be true, which means the |
| 3382 | error was of type <code>*os.PathError</code>, and then so is <code>e</code>, |
| 3383 | which we can examine for more information about the error. |
| 3384 | </p> |
| 3385 | |
| 3386 | <h3 id="panic">Panic</h3> |
| 3387 | |
| 3388 | <p> |
| 3389 | The usual way to report an error to a caller is to return an |
| 3390 | <code>error</code> as an extra return value. The canonical |
| 3391 | <code>Read</code> method is a well-known instance; it returns a byte |
| 3392 | count and an <code>error</code>. But what if the error is |
| 3393 | unrecoverable? Sometimes the program simply cannot continue. |
| 3394 | </p> |
| 3395 | |
| 3396 | <p> |
| 3397 | For this purpose, there is a built-in function <code>panic</code> |
| 3398 | that in effect creates a run-time error that will stop the program |
| 3399 | (but see the next section). The function takes a single argument |
| 3400 | of arbitrary type—often a string—to be printed as the |
| 3401 | program dies. It's also a way to indicate that something impossible has |
| 3402 | happened, such as exiting an infinite loop. |
| 3403 | </p> |
| 3404 | |
| 3405 | |
| 3406 | <pre> |
| 3407 | // A toy implementation of cube root using Newton's method. |
| 3408 | func CubeRoot(x float64) float64 { |
| 3409 | z := x/3 // Arbitrary initial value |
| 3410 | for i := 0; i < 1e6; i++ { |
| 3411 | prevz := z |
| 3412 | z -= (z*z*z-x) / (3*z*z) |
| 3413 | if veryClose(z, prevz) { |
| 3414 | return z |
| 3415 | } |
| 3416 | } |
| 3417 | // A million iterations has not converged; something is wrong. |
| 3418 | panic(fmt.Sprintf("CubeRoot(%g) did not converge", x)) |
| 3419 | } |
| 3420 | </pre> |
| 3421 | |
| 3422 | <p> |
| 3423 | This is only an example but real library functions should |
| 3424 | avoid <code>panic</code>. If the problem can be masked or worked |
| 3425 | around, it's always better to let things continue to run rather |
| 3426 | than taking down the whole program. One possible counterexample |
| 3427 | is during initialization: if the library truly cannot set itself up, |
| 3428 | it might be reasonable to panic, so to speak. |
| 3429 | </p> |
| 3430 | |
| 3431 | <pre> |
| 3432 | var user = os.Getenv("USER") |
| 3433 | |
| 3434 | func init() { |
| 3435 | if user == "" { |
| 3436 | panic("no value for $USER") |
| 3437 | } |
| 3438 | } |
| 3439 | </pre> |
| 3440 | |
| 3441 | <h3 id="recover">Recover</h3> |
| 3442 | |
| 3443 | <p> |
| 3444 | When <code>panic</code> is called, including implicitly for run-time |
| 3445 | errors such as indexing a slice out of bounds or failing a type |
| 3446 | assertion, it immediately stops execution of the current function |
| 3447 | and begins unwinding the stack of the goroutine, running any deferred |
| 3448 | functions along the way. If that unwinding reaches the top of the |
| 3449 | goroutine's stack, the program dies. However, it is possible to |
| 3450 | use the built-in function <code>recover</code> to regain control |
| 3451 | of the goroutine and resume normal execution. |
| 3452 | </p> |
| 3453 | |
| 3454 | <p> |
| 3455 | A call to <code>recover</code> stops the unwinding and returns the |
| 3456 | argument passed to <code>panic</code>. Because the only code that |
| 3457 | runs while unwinding is inside deferred functions, <code>recover</code> |
| 3458 | is only useful inside deferred functions. |
| 3459 | </p> |
| 3460 | |
| 3461 | <p> |
| 3462 | One application of <code>recover</code> is to shut down a failing goroutine |
| 3463 | inside a server without killing the other executing goroutines. |
| 3464 | </p> |
| 3465 | |
| 3466 | <pre> |
| 3467 | func server(workChan <-chan *Work) { |
| 3468 | for work := range workChan { |
| 3469 | go safelyDo(work) |
| 3470 | } |
| 3471 | } |
| 3472 | |
| 3473 | func safelyDo(work *Work) { |
| 3474 | defer func() { |
| 3475 | if err := recover(); err != nil { |
| 3476 | log.Println("work failed:", err) |
| 3477 | } |
| 3478 | }() |
| 3479 | do(work) |
| 3480 | } |
| 3481 | </pre> |
| 3482 | |
| 3483 | <p> |
| 3484 | In this example, if <code>do(work)</code> panics, the result will be |
| 3485 | logged and the goroutine will exit cleanly without disturbing the |
| 3486 | others. There's no need to do anything else in the deferred closure; |
| 3487 | calling <code>recover</code> handles the condition completely. |
| 3488 | </p> |
| 3489 | |
| 3490 | <p> |
| 3491 | Because <code>recover</code> always returns <code>nil</code> unless called directly |
| 3492 | from a deferred function, deferred code can call library routines that themselves |
| 3493 | use <code>panic</code> and <code>recover</code> without failing. As an example, |
| 3494 | the deferred function in <code>safelyDo</code> might call a logging function before |
| 3495 | calling <code>recover</code>, and that logging code would run unaffected |
| 3496 | by the panicking state. |
| 3497 | </p> |
| 3498 | |
| 3499 | <p> |
| 3500 | With our recovery pattern in place, the <code>do</code> |
| 3501 | function (and anything it calls) can get out of any bad situation |
| 3502 | cleanly by calling <code>panic</code>. We can use that idea to |
| 3503 | simplify error handling in complex software. Let's look at an |
| 3504 | idealized version of a <code>regexp</code> package, which reports |
| 3505 | parsing errors by calling <code>panic</code> with a local |
| 3506 | error type. Here's the definition of <code>Error</code>, |
| 3507 | an <code>error</code> method, and the <code>Compile</code> function. |
| 3508 | </p> |
| 3509 | |
| 3510 | <pre> |
| 3511 | // Error is the type of a parse error; it satisfies the error interface. |
| 3512 | type Error string |
| 3513 | func (e Error) Error() string { |
| 3514 | return string(e) |
| 3515 | } |
| 3516 | |
| 3517 | // error is a method of *Regexp that reports parsing errors by |
| 3518 | // panicking with an Error. |
| 3519 | func (regexp *Regexp) error(err string) { |
| 3520 | panic(Error(err)) |
| 3521 | } |
| 3522 | |
| 3523 | // Compile returns a parsed representation of the regular expression. |
| 3524 | func Compile(str string) (regexp *Regexp, err error) { |
| 3525 | regexp = new(Regexp) |
| 3526 | // doParse will panic if there is a parse error. |
| 3527 | defer func() { |
| 3528 | if e := recover(); e != nil { |
| 3529 | regexp = nil // Clear return value. |
| 3530 | err = e.(Error) // Will re-panic if not a parse error. |
| 3531 | } |
| 3532 | }() |
| 3533 | return regexp.doParse(str), nil |
| 3534 | } |
| 3535 | </pre> |
| 3536 | |
| 3537 | <p> |
| 3538 | If <code>doParse</code> panics, the recovery block will set the |
| 3539 | return value to <code>nil</code>—deferred functions can modify |
| 3540 | named return values. It will then check, in the assignment |
| 3541 | to <code>err</code>, that the problem was a parse error by asserting |
| 3542 | that it has the local type <code>Error</code>. |
| 3543 | If it does not, the type assertion will fail, causing a run-time error |
| 3544 | that continues the stack unwinding as though nothing had interrupted |
| 3545 | it. |
| 3546 | This check means that if something unexpected happens, such |
| 3547 | as an index out of bounds, the code will fail even though we |
| 3548 | are using <code>panic</code> and <code>recover</code> to handle |
| 3549 | parse errors. |
| 3550 | </p> |
| 3551 | |
| 3552 | <p> |
| 3553 | With error handling in place, the <code>error</code> method (because it's a |
| 3554 | method bound to a type, it's fine, even natural, for it to have the same name |
| 3555 | as the builtin <code>error</code> type) |
| 3556 | makes it easy to report parse errors without worrying about unwinding |
| 3557 | the parse stack by hand: |
| 3558 | </p> |
| 3559 | |
| 3560 | <pre> |
| 3561 | if pos == 0 { |
| 3562 | re.error("'*' illegal at start of expression") |
| 3563 | } |
| 3564 | </pre> |
| 3565 | |
| 3566 | <p> |
| 3567 | Useful though this pattern is, it should be used only within a package. |
| 3568 | <code>Parse</code> turns its internal <code>panic</code> calls into |
| 3569 | <code>error</code> values; it does not expose <code>panics</code> |
| 3570 | to its client. That is a good rule to follow. |
| 3571 | </p> |
| 3572 | |
| 3573 | <p> |
| 3574 | By the way, this re-panic idiom changes the panic value if an actual |
| 3575 | error occurs. However, both the original and new failures will be |
| 3576 | presented in the crash report, so the root cause of the problem will |
| 3577 | still be visible. Thus this simple re-panic approach is usually |
| 3578 | sufficient—it's a crash after all—but if you want to |
| 3579 | display only the original value, you can write a little more code to |
| 3580 | filter unexpected problems and re-panic with the original error. |
| 3581 | That's left as an exercise for the reader. |
| 3582 | </p> |
| 3583 | |
| 3584 | |
| 3585 | <h2 id="web_server">A web server</h2> |
| 3586 | |
| 3587 | <p> |
| 3588 | Let's finish with a complete Go program, a web server. |
| 3589 | This one is actually a kind of web re-server. |
| 3590 | Google provides a service at |
| 3591 | <a href="http://chart.apis.google.com">http://chart.apis.google.com</a> |
| 3592 | that does automatic formatting of data into charts and graphs. |
| 3593 | It's hard to use interactively, though, |
| 3594 | because you need to put the data into the URL as a query. |
| 3595 | The program here provides a nicer interface to one form of data: given a short piece of text, |
| 3596 | it calls on the chart server to produce a QR code, a matrix of boxes that encode the |
| 3597 | text. |
| 3598 | That image can be grabbed with your cell phone's camera and interpreted as, |
| 3599 | for instance, a URL, saving you typing the URL into the phone's tiny keyboard. |
| 3600 | </p> |
| 3601 | <p> |
| 3602 | Here's the complete program. |
| 3603 | An explanation follows. |
| 3604 | </p> |
| 3605 | {{code "/doc/progs/eff_qr.go" `/package/` `$`}} |
| 3606 | <p> |
| 3607 | The pieces up to <code>main</code> should be easy to follow. |
| 3608 | The one flag sets a default HTTP port for our server. The template |
| 3609 | variable <code>templ</code> is where the fun happens. It builds an HTML template |
| 3610 | that will be executed by the server to display the page; more about |
| 3611 | that in a moment. |
| 3612 | </p> |
| 3613 | <p> |
| 3614 | The <code>main</code> function parses the flags and, using the mechanism |
| 3615 | we talked about above, binds the function <code>QR</code> to the root path |
| 3616 | for the server. Then <code>http.ListenAndServe</code> is called to start the |
| 3617 | server; it blocks while the server runs. |
| 3618 | </p> |
| 3619 | <p> |
| 3620 | <code>QR</code> just receives the request, which contains form data, and |
| 3621 | executes the template on the data in the form value named <code>s</code>. |
| 3622 | </p> |
| 3623 | <p> |
| 3624 | The template package <code>html/template</code> is powerful; |
| 3625 | this program just touches on its capabilities. |
| 3626 | In essence, it rewrites a piece of HTML text on the fly by substituting elements derived |
| 3627 | from data items passed to <code>templ.Execute</code>, in this case the |
| 3628 | form value. |
| 3629 | Within the template text (<code>templateStr</code>), |
| 3630 | double-brace-delimited pieces denote template actions. |
| 3631 | The piece from <code>{{html "{{if .}}"}}</code> |
| 3632 | to <code>{{html "{{end}}"}}</code> executes only if the value of the current data item, called <code>.</code> (dot), |
| 3633 | is non-empty. |
| 3634 | That is, when the string is empty, this piece of the template is suppressed. |
| 3635 | </p> |
| 3636 | <p> |
| 3637 | The two snippets <code>{{html "{{.}}"}}</code> say to show the data presented to |
| 3638 | the template—the query string—on the web page. |
| 3639 | The HTML template package automatically provides appropriate escaping so the |
| 3640 | text is safe to display. |
| 3641 | </p> |
| 3642 | <p> |
| 3643 | The rest of the template string is just the HTML to show when the page loads. |
| 3644 | If this is too quick an explanation, see the <a href="/pkg/html/template/">documentation</a> |
| 3645 | for the template package for a more thorough discussion. |
| 3646 | </p> |
| 3647 | <p> |
| 3648 | And there you have it: a useful web server in a few lines of code plus some |
| 3649 | data-driven HTML text. |
| 3650 | Go is powerful enough to make a lot happen in a few lines. |
| 3651 | </p> |
| 3652 | |
| 3653 | <!-- |
| 3654 | TODO |
| 3655 | <pre> |
| 3656 | verifying implementation |
| 3657 | type Color uint32 |
| 3658 | |
| 3659 | // Check that Color implements image.Color and image.Image |
| 3660 | var _ image.Color = Black |
| 3661 | var _ image.Image = Black |
| 3662 | </pre> |
| 3663 | --> |
| 3664 | |