| Let's Go | |
| ---- | |
| Rob Pike | |
| ---- | |
| (September 14, 2008) | |
| This document is a tutorial introduction to the basics of the Go systems programming | |
| language, intended for programmers familiar with C or C++. It is not a comprehensive | |
| guide to the language; at the moment the document closest to that is the draft | |
| specification: | |
| /doc/go_spec.html | |
| To check out the compiler and tools and be ready to run Go programs, see | |
| /doc/go_setup.html | |
| The presentation proceeds through a series of modest programs to illustrate | |
| key features of the language. All the programs work (at time of writing) and are | |
| checked in at | |
| /doc/progs | |
| Program snippets are annotated with the line number in the original file; for | |
| cleanliness, blank lines remain blank. | |
| Hello, World | |
| ---- | |
| Let's start in the usual way: | |
| --PROG progs/helloworld.go | |
| Every Go source file declares which package it's part of using a "package" statement. | |
| The "main" package's "main" function is where the program starts running (after | |
| any initialization). | |
| Function declarations are introduced with the "func" keyword. | |
| Notice that string constants can contain Unicode characters, encoded in UTF-8. | |
| Go is defined to accept UTF-8 input. Strings are arrays of bytes, usually used | |
| to store Unicode strings represented in UTF-8. | |
| The built-in function "print()" has been used during the early stages of | |
| development of the language but is not guaranteed to last. Here's a better version of the | |
| program that doesn't depend on "print()": | |
| --PROG progs/helloworld2.go | |
| This version imports the ''os'' package to acess its "Stdout" variable, of type | |
| "*OS.FD". The "import" statement is a declaration: it names the identifier ("OS") | |
| that will be used to access members of the package imported from the file ("os"), | |
| found in the current directory or in a standard location. | |
| Given "OS.Stdout" we can use its "WriteString" method to print the string. | |
| The comment convention is the same as in C++: | |
| /* ... */ | |
| // ... | |
| Echo | |
| ---- | |
| Next up, here's a version of the Unix utility "echo(1)": | |
| --PROG progs/echo.go | |
| It's still fairly small but it's doing a number of new things. In the last example, | |
| we saw "func" introducing a function. The keywords "var", "const", and "type" | |
| (not used yet) also introduce declarations, as does "import". | |
| Notice that we can group declarations of the same sort into | |
| parenthesized, semicolon-separated lists if we want, as on lines 3-6 and 10-13. | |
| But it's not necessary to do so; we could have said | |
| const Space = " " | |
| const Newline = "\n" | |
| Semicolons aren't needed here; in fact, semicolons are unnecessary after any | |
| top-level declaration, even though they are needed as separators <i>within</i> | |
| a parenthesized list of declarations. | |
| Having imported the "Flag" package, line 8 creates a global variable to hold | |
| the value of echo's -n flag. (The nil hides a nice feature not needed here; | |
| see the source in "src/lib/flag.go" for details). | |
| In "main.main", we parse the arguments (line 16) and then create a local | |
| string variable we will use to build the output. | |
| The declaration statement has the form | |
| var s string = ""; | |
| This is the "var" keyword, followed by the name of the variable, followed by | |
| its type, followed by an equals sign and an initial value for the variable. | |
| Go tries to be terse, and this declaration could be shortened. Since the | |
| string constant is of type string, we don't have to tell the compiler that. | |
| We could write | |
| var s = ""; | |
| or we could go even shorter and write the idiom | |
| s := ""; | |
| The := operator is used a lot in Go to represent an initializing declaration. | |
| (For those who know Limbo, its := construct is the same, but notice | |
| that Go has no colon after the name in a full "var" declaration.) | |
| And there's one in the "for" clause on the next line: | |
| --PROG progs/echo.go /for/ | |
| The "Flag" package has parsed the arguments and left the non-flag arguments | |
| in a list that can be iterated over in the obvious way. | |
| The Go "for" statement differs from that of C in a number of ways. First, | |
| it's the only looping construct; there is no "while" or "do". Second, | |
| there are no parentheses on the clause, but the braces on the body | |
| are mandatory. (The same applies to the "if" statement.) Later examples | |
| will show some other ways "for" can be written. | |
| The body of the loop builds up the string "s" by appending (using +=) | |
| the flags and separating spaces. After the loop, if the "-n" flag is not | |
| set, it appends a newline, and then writes the result. | |
| Notice that "main.main" is a niladic function with no return type. | |
| It's defined that way. Falling off the end of "main.main" means | |
| ''success''; if you want to signal erroneous return, use | |
| sys.exit(1) | |
| The "sys" package is built in and contains some essentials for getting | |
| started; for instance, "sys.argc()" and "sys.argv(int)" are used by the | |
| "Flag" package to access the arguments. | |
| An Interlude about Types | |
| ---- | |
| Go has some familiar types such as "int" and "float", which represent | |
| values of the ''appropriate'' size for the machine. It also defines | |
| specifically-sized types such as "int8", "float64", and so on, plus | |
| unsigned integer types such as "uint", "uint32", etc. And then there | |
| is a "byte" synonym for "uint8", which is the element type for | |
| strings. | |
| Speaking of "string", that's a built-in type as well. Strings are | |
| <i>immutable values</i> -- they are not just arrays of "byte" values. | |
| Once you've built a string <i>value</i>, you can't change it, although | |
| of course you can change a string <i>variable</i> simply by | |
| reassigning it. This snippet from "strings.go" is legal code: | |
| --PROG progs/strings.go /hello/ /ciao/ | |
| However the following statements are illegal because they would modify | |
| a "string" value: | |
| s[0] = 'x'; | |
| (*p)[1] = 'y'; | |
| In C++ terms, Go strings are a bit like "const strings", while pointers | |
| to strings are analogous to "const string" references. | |
| Yes, there are pointers. However, Go simplifies their use a little; | |
| read on. | |
| Arrays are declared like this: | |
| var array_of_int [10]int; | |
| Arrays, like strings, are values, but they are mutable. This differs | |
| from C, in which "array_of_int" would be usable as a pointer to "int". | |
| In Go, since arrays are values, it's meaningful (and useful) to talk | |
| about pointers to arrays. | |
| The size of the array is part of its type; however, one can declare | |
| an <i>open array</i> variable, to which one can assign any array value | |
| with the same element type. | |
| (At the moment, only <i>pointers</i> to open arrays are implemented.) | |
| Thus one can write this function (from "sum.go"): | |
| --PROG progs/sum.go /sum/ /^}/ | |
| and invoke it like this: | |
| --PROG progs/sum.go /1,2,3/ | |
| Note how the return type ("int") is defined for "sum()" by stating it | |
| after the parameter list. Also observe that although the argument | |
| is a pointer to an array, we can index it directly ("a[i]" not "(*a)[i]"). | |
| The expression "[]int{1,2,3}" -- a type followed by a brace-bounded expression | |
| -- is a constructor for a value, in this case an array of "int". We pass it | |
| to "sum()" by taking its address. | |
| The built-in function "len()" appeared there too - it works on strings, | |
| arrays, and maps, which can be built like this: | |
| m := map[string] int {"one":1 , "two":2} | |
| At least for now, maps are <i>always</i> pointers, so in this example | |
| "m" has type "*map[string]int". This may change. | |
| You can also create a map (or anything else) with the built-in "new()" | |
| function: | |
| m := new(map[string] int) | |
| The "new()" function always returns a pointer, an address for the object | |
| it creates. | |
| An Interlude about Constants | |
| ---- | |
| Although integers come in lots of sizes in Go, integer constants do not. | |
| There are no constants like "0ll" or "0x0UL". Instead, integer | |
| constants are evaluated as ideal, large-precision values that | |
| can overflow only when they are assigned to an integer variable with | |
| too little precision to represent the value. | |
| const hard_eight = (1 << 100) >> 97 // legal | |
| There are nuances that deserve redirection to the legalese of the | |
| language specification but here are some illustrative examples: | |
| var a uint64 = 0 // a has type uint64, value 0 | |
| a := uint64(0) // equivalent; uses a "conversion" | |
| i := 0x1234 // i gets default type: int | |
| var j int = 1e6 // legal - 1000000 is representable in an int | |
| x := 1.5 // a float | |
| i3div2 = 3/2 // integer division - result is 1 | |
| f3div2 = 3./2. // floating point division - result is 1.5 | |
| Conversions only work for simple cases such as converting ints of one | |
| sign or size to another, and between ints and floats, plus a few other | |
| simple cases. There are no automatic conversions of any kind in Go, | |
| other than that of making constants have concrete size and type when | |
| assigned to a variable. | |
| An I/O Package | |
| ---- | |
| Next we'll look at a simple package for doing file I/O with the usual | |
| sort of open/close/read/write interface. Here's the start of "fd.go": | |
| --PROG progs/fd.go /package/ /^}/ | |
| The first line declares the name of the package -- "fd" for ''file descriptor'' -- | |
| and then we import the low-level, external "syscall" package, which provides | |
| a primitive interface to the underlying operating system's calls. | |
| Next is a type definition: the "type" keyword introduces a type declaration, | |
| in this case a data structure called "FD". | |
| To make things a little more interesting, our "FD" includes the name of the file | |
| that the file descriptor refers to. The "export" keyword makes the declared | |
| structure visible to users of the package. | |
| Now we can write what is often called a factory: | |
| --PROG progs/fd.go /NewFD/ /^}/ | |
| This returns a pointer to a new "FD" structure with the file descriptor and name | |
| filled in. We can use it to construct some familiar, exported variables of type "*FD": | |
| --PROG progs/fd.go /export.var/ /^.$/ | |
| The "NewFD" function was not exported because it's internal. The proper factory | |
| to use is "Open": | |
| --PROG progs/fd.go /func.Open/ /^}/ | |
| There are a number of new things in these few lines. First, "Open" returns | |
| multiple values, an "FD" and an "errno" (Unix error number). We declare the | |
| multi-value return as a parenthesized list of declarations. "Syscall.open" | |
| also has a multi-value return, which we can grab with the multi-variable | |
| declaration on line 27; it declares "r" and "e" to hold the two values, | |
| both of type "int64" (although you'd have to look at the "syscall" package | |
| to see that). Finally, line 28 returns two values: a pointer to the new "FD" | |
| and the return code. If "Syscall.open" failed, the file descriptor "r" will | |
| be negative and "NewFD" will return "nil". | |
| Now that we can build "FDs", we can write methods to use them. To declare | |
| a method of a type, we define a function to have an explicit receiver | |
| of that type, placed | |
| in parentheses before the function name. Here are some methods for "FD", | |
| each of which declares a receiver variable "fd". | |
| --PROG progs/fd.go /Close/ END | |
| There is no implicit "this" and the receiver variable must be used to access | |
| members of the structure. Methods are not declared within | |
| the "struct" declaration itself. The "struct" declaration defines only data members. | |
| Finally, we can use our new package: | |
| --PROG progs/helloworld3.go | |
| and run the program: | |
| % helloworld3 | |
| hello, world | |
| can't open file; errno=2 | |
| % | |
| Rotting cats | |
| ---- | |
| Building on the FD package, here's a simple version of the Unix utility "cat(1)", "progs/cat.go": | |
| --PROG progs/cat.go | |
| By now this should be easy to follow, but the "switch" statement introduces some | |
| new features. Like a "for" loop, an "if" or "switch" can include an | |
| initialization statement. The "switch" on line 12 uses one to create variables | |
| "nr" and "er" to hold the return values from "fd.Read()". (The "if" on line 19 | |
| has the same idea.) The "switch" statement is general: it evaluates the cases | |
| from top to bottom looking for the first case that matches the value; the | |
| case expressions don't need to be constants or even integers, as long as | |
| they all have the same type. | |
| Since the "switch" value is just "true", we could leave it off -- as is also true | |
| in a "for" statement, a missing value means "true". In fact, such a "switch" | |
| is a form of "if-else" chain. | |
| Line 19 calls "Write()" by slicing (a pointer to) the array, creating a | |
| <i>reference slice</i>. | |
| Now let's make a variant of "cat" that optionally does "rot13" on its input. | |
| It's easy to do by just processing the bytes, but instead we will exploit | |
| Go's notion of an <i>interface</i>. | |
| The "cat()" subroutine uses only two methods of "fd": "Read()" and "Name()", | |
| so let's start by defining an interface that has exactly those two methods. | |
| Here is code from "progs/cat_rot13.go": | |
| --PROG progs/cat_rot13.go /type.Reader/ /^}/ | |
| Any type that implements the two methods of "Reader" -- regardless of whatever | |
| other methods the type may also contain -- is said to <i>implement</i> the | |
| interface. Since "FD.FD" implements these methods, it implements the | |
| "Reader" interface. We could tweak the "cat" subroutine to accept a "Reader" | |
| instead of a "*FD.FD" and it would work just fine, but let's embellish a little | |
| first by writing a second type that implements "Reader", one that wraps an | |
| existing "Reader" and does "rot13" on the data. To do this, we just define | |
| the type and implement the methods and with no other bookkeeping, | |
| we have a second implementation of the "Reader" interface. | |
| --PROG progs/cat_rot13.go /type.Rot13/ /end.of.Rot13/ | |
| (The "rot13" function called on line 38 is trivial and not worth reproducing.) | |
| To use the new feature, we define a flag: | |
| --PROG progs/cat_rot13.go /rot13_flag/ | |
| and use it from within a mostly unchanged "cat()" function: | |
| --PROG progs/cat_rot13.go /func.cat/ /^}/ | |
| (We could also do the wrapping in "main" and leave "cat()" mostly alone, except | |
| for changing the type of the argument.) | |
| Lines 53 and 54 set it all up: If the "rot13" flag is true, wrap the "Reader" | |
| we received into a "Rot13" and proceed. Note that the interface variables | |
| are values, not pointers: the argument is of type "Reader", not "*Reader", | |
| even though under the covers it holds a pointer to a "struct". | |
| Here it is in action: | |
| <pre> | |
| % echo abcdefghijklmnopqrstuvwxyz | ./cat | |
| abcdefghijklmnopqrstuvwxyz | |
| % echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13 | |
| nopqrstuvwxyzabcdefghijklm | |
| % | |
| </pre> | |
| Fans of dependency injection may take cheer from how easily interfaces | |
| allow us to substitute the implementation of a file descriptor. | |
| Interfaces are a distinct feature of Go. An interface is implemented by a | |
| type if the type implements all the methods declared in the interface. | |
| This means | |
| that a type may implement an arbitrary number of different interfaces. | |
| There is no type hierarchy; things can be much more <i>ad hoc</i>, | |
| as we saw with "rot13". "FD.FD" implements "Reader"; it could also | |
| implement a "Writer", or any other interface built from its methods that | |
| fits the current situation. Consider the <i>empty interface</i> | |
| <pre> | |
| type interface Empty {} | |
| </pre> | |
| <i>Every</i> type implements the empty interface, which makes it | |
| useful for things like containers. | |
| Sorting | |
| ---- | |
| As another example of interfaces, consider this simple sort algorithm, | |
| taken from "progs/sort.go": | |
| --PROG progs/sort.go /func.Sort/ /^}/ | |
| The code needs only three methods, which we wrap into "SortInterface": | |
| --PROG progs/sort.go /interface/ /^}/ | |
| We can apply "Sort" to any type that implements "len", "less", and "swap". | |
| The "sort" package includes the necessary methods to allow sorting of | |
| arrays of integers, strings, etc.; here's the code for arrays of "int": | |
| --PROG progs/sort.go /type.*IntArray/ /swap/ | |
| And now a routine to test it out, from "progs/sortmain.go". This | |
| uses a function in the "sort" package, omitted here for brevity, | |
| to test that the result is sorted. | |
| --PROG progs/sortmain.go /func.ints/ /^}/ | |
| If we have a new type we want to be able to sort, all we need to do is | |
| to implement the three methods for that type, like this: | |
| --PROG progs/sortmain.go /type.Day/ /swap/ | |
| Prime numbers | |
| ---- | |
| Now we come to processes and communication -- concurrent programming. | |
| It's a big subject so to be brief we assume some familiarity with the topic. | |
| A classic program in the style is the prime sieve of Eratosthenes. | |
| It works by taking a stream of all the natural numbers, and introducing | |
| a sequence of filters, one for each prime, to winnow the multiples of | |
| that prime. At each step we have a sequence of filters of the primes | |
| so far, and the next number to pop out is the next prime, which triggers | |
| the creation of the next filter in the chain. | |
| Here's a flow diagram; each box represents a filter element whose | |
| creation is triggered by the first number that flowed from the | |
| elements before it. | |
| <br> | |
| <img src='sieve.gif'> | |
| <br> | |
| To create a stream of integers, we use a Go <i>channel</i>, which, | |
| borrowing from CSP's descendants, represents a communications | |
| channel that can connect two concurrent computations. | |
| In Go, channel variables are | |
| always pointers to channels -- it's the object they point to that | |
| does the communication. | |
| Here is the first function in "progs/sieve.go": | |
| --PROG progs/sieve.go /Send/ /^}/ | |
| The function "Generate" sends the sequence 2, 3, 4, 5, ... to its | |
| argument channel, "ch", using the binary communications operator "<-". | |
| Channels block, so if there's no recipient for the the value on "ch", | |
| the send operation will wait until one becomes available. | |
| The "Filter" function has three arguments: an input channel, an output | |
| channel, and a prime number. It copies values from the input to the | |
| output, discarding anything divisible by the prime. The unary communications | |
| operator "<-" (receive) retrieves the next value on the channel. | |
| --PROG progs/sieve.go /Copy/ /^}/ | |
| The generator and filters execute concurrently. Go has | |
| its own model of process/threads/light-weight processes/coroutines, | |
| so to avoid notational confusion we'll call concurrently executing | |
| computations in Go <i>goroutines</i>. To start a goroutine, | |
| invoke the function, prefixing the call with the keyword "go"; | |
| this starts the function running in parallel with the current | |
| computation but in the same address space: | |
| go sum(huge_array); // calculate sum in the background | |
| If you want to know when the calculation is done, pass a channel | |
| on which it can report back: | |
| ch := new(chan int); | |
| go sum(huge_array, ch); | |
| // ... do something else for a while | |
| result := <-ch; // wait for, and retrieve, result | |
| Back to our prime sieve. Here's how the sieve pipeline is stitched | |
| together: | |
| --PROG progs/sieve.go /func.main/ /^}/ | |
| Line 23 creates the initial channel to pass to "Generate", which it | |
| then starts up. As each prime pops out of the channel, a new "Filter" | |
| is added to the pipeline and <i>its</i> output becomes the new value | |
| of "ch". | |
| The sieve program can be tweaked to use a pattern common | |
| in this style of programming. Here is a variant version | |
| of "Generate", from "progs/sieve1.go": | |
| --PROG progs/sieve1.go /func.Generate/ /^}/ | |
| This version does all the setup internally. It creates the output | |
| channel, launches a goroutine internally using a function literal, and | |
| returns the channel to the caller. It is a factory for concurrent | |
| execution, starting the goroutine and returning its connection. | |
| The same | |
| change can be made to "Filter": | |
| --PROG progs/sieve1.go /func.Filter/ /^}/ | |
| The "Sieve" function's main loop becomes simpler and clearer as a | |
| result, and while we're at it let's turn it into a factory too: | |
| --PROG progs/sieve1.go /func.Sieve/ /^}/ | |
| Now "main"'s interface to the prime sieve is a channel of primes: | |
| --PROG progs/sieve1.go /func.main/ /^}/ | |
| Multiplexing | |
| ---- | |
| With channels, it's possible to serve multiple independent client goroutines without | |
| writing an actual multiplexer. The trick is to send the server a channel in the message, | |
| which it will then use to reply to the original sender. | |
| A realistic client-server program is a lot of code, so here is a very simple substitute | |
| to illustrate the idea. It starts by defining a "Request" type, which embeds a channel | |
| that will be used for the reply. | |
| --PROG progs/server.go /type.Request/ /^}/ | |
| The server will be trivial: it will do simple binary operations on integers. Here's the | |
| code that invokes the operation and responds to the request: | |
| --PROG progs/server.go /type.BinOp/ /^}/ | |
| The "Server" routine loops forever, receiving requests and, to avoid blocking due to | |
| a long-running operation, starting a goroutine to do the actual work. | |
| --PROG progs/server.go /func.Server/ /^}/ | |
| We construct a server in a familiar way, starting it up and returning a channel to | |
| connect to it: | |
| --PROG progs/server.go /func.StartServer/ /^}/ | |
| Here's a simple test. It starts a server with an addition operator, and sends out | |
| lots of requests but doesn't wait for the reply. Only after all the requests are sent | |
| does it check the results. | |
| --PROG progs/server.go /func.main/ /^}/ | |
| One annoyance with this program is that it doesn't exit cleanly; when "main" returns | |
| there are a number of lingering goroutines blocked on communication. To solve this, | |
| we provide a second, "quit" channel to the server: | |
| --PROG progs/server1.go /func.StartServer/ /^}/ | |
| It passes the quit channel to the "Server" function, which uses it like this: | |
| --PROG progs/server1.go /func.Server/ /^}/ | |
| Inside "Server", a "select" statement chooses which of the multiple communications | |
| listed by its cases can proceed. If all are blocked, it waits until one can proceed; if | |
| multiple can proceed, it chooses one at random. In this instance, the "select" allows | |
| the server to honor requests until it receives a quit message, at which point it | |
| returns, terminating its execution. | |
| All that's left is to strobe the "quit" channel | |
| at the end of main: | |
| --PROG progs/server1.go /adder,.quit/ | |
| ... | |
| --PROG progs/server1.go /quit....true/ | |
| There's a lot more to Go programming and concurrent programming in general but this | |
| quick tour should give you some of the basics. |