├── cover.png ├── frontpage.png ├── gopherref.pdf ├── gopherref.epub ├── epub_metadata.xml ├── README.md ├── preamble.tex ├── title.tex ├── gopherref.tex ├── Makefile ├── process.sh ├── mkfile ├── credits.tex ├── consolidate.go ├── concurrency.tex ├── defer.tex ├── writing.tex ├── gobs.tex ├── error_handling.tex └── effective.tex /cover.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gokyle/gopherref/HEAD/cover.png -------------------------------------------------------------------------------- /frontpage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gokyle/gopherref/HEAD/frontpage.png -------------------------------------------------------------------------------- /gopherref.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gokyle/gopherref/HEAD/gopherref.pdf -------------------------------------------------------------------------------- /gopherref.epub: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gokyle/gopherref/HEAD/gopherref.epub -------------------------------------------------------------------------------- /epub_metadata.xml: -------------------------------------------------------------------------------- 1 | en-US 2 | Go Developer's Reference 3 | Kyle Isom 4 | application/epub+zip 5 | eBook version of several of the Go docs. 6 | http://www.golang.org 7 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## gopherref 2 | 3 | I'm working to typeset and produce an ebook version of the Go language 4 | docs - 5 | 6 | * the Go language specification 7 | * Writing Go Code 8 | * Effective Go 9 | 10 | Additionally, I'll consider adding any CS papers that I think would be 11 | particularly useful for Go devs to read as well. 12 | -------------------------------------------------------------------------------- /preamble.tex: -------------------------------------------------------------------------------- 1 | \usepackage[margin=0.75in]{geometry} 2 | \usepackage{fancyvrb} 3 | \usepackage[greek,english]{babel} 4 | \usepackage{iwona,palatino} 5 | \usepackage[OT1]{fontenc} 6 | \usepackage{textcomp} 7 | \usepackage{lmodern} 8 | \usepackage{hyperref} 9 | \usepackage{xltxtra} 10 | \usepackage{graphicx} 11 | 12 | \newcommand{\HRule}{\rule{\linewidth}{0.5mm}} 13 | \defaultfontfeatures{Ligatures=TeX} 14 | -------------------------------------------------------------------------------- /title.tex: -------------------------------------------------------------------------------- 1 | \begin{titlepage} 2 | 3 | \begin{center} 4 | 5 | 6 | % Upper part of the page 7 | \includegraphics[width=0.15\textwidth]{./frontpage}\\[1cm] 8 | 9 | 10 | % Title 11 | \HRule \\[0.4cm] 12 | { \huge \bfseries Go Developer's Reference}\\[0.4cm] 13 | 14 | \HRule \\[1.5cm] 15 | 16 | % Author and supervisor 17 | \emph{Typesetter:}\\Kyle Isom 18 | \vfill 19 | 20 | % Bottom of the page 21 | {\large \today} 22 | 23 | \end{center} 24 | 25 | \end{titlepage} 26 | -------------------------------------------------------------------------------- /gopherref.tex: -------------------------------------------------------------------------------- 1 | \documentclass{book} 2 | \title{Gopher Reference} 3 | \author{typeset by Kyle Isom} 4 | \input{preamble} 5 | 6 | \begin{document} 7 | \input{title} 8 | \frontmatter 9 | \clearpage 10 | \setcounter{tocdepth}{0} 11 | \tableofcontents 12 | \clearpage 13 | 14 | \mainmatter 15 | \input{writing} 16 | \input{effective} 17 | \input{error_handling} 18 | \input{defer} 19 | \input{concurrency} 20 | \input{gobs} 21 | \input{spec} 22 | 23 | \backmatter 24 | \input{credits} 25 | 26 | \end{document} 27 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | PDFGEN := xelatex 2 | VIEWER := open 3 | SOURCE := gopherref 4 | CHAPTERS := preamble.tex spec.tex writing.tex effective.tex title.tex credits.tex 5 | 6 | all: pdf view 7 | 8 | pdf: $(SOURCE).pdf 9 | 10 | $(SOURCE).pdf: $(SOURCE).tex $(CHAPTERS) 11 | xelatex $(SOURCE).tex 12 | xelatex $(SOURCE).tex 13 | $(PDFGEN) $(SOURCE).tex 14 | 15 | view: $(SOURCE).pdf 16 | $(VIEWER) $(SOURCE).pdf 17 | 18 | clean: 19 | rm -rf *.log *.aux *.*\~ *.toc *.out 20 | 21 | distclean: clean 22 | rm -f *.pdf *.epub 23 | 24 | .PHONY: all pdf clean 25 | 26 | 27 | -------------------------------------------------------------------------------- /process.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | OUT=${1-"effective_go.tex"} 4 | if [ -e ${OUT} ]; then 5 | echo "[+] removing existing file ${OUT}" 6 | rm ${OUT} 7 | fi 8 | 9 | if [ ! -e ${OUT}.orig -o ! -s ${OUT}.orig ]; then 10 | echo "[+] generating original" 11 | pandoc -o ${OUT} /usr/local/Cellar/go/1.0.3/doc/${OUT%.tex}.html 12 | mv ${OUT} ${OUT}.orig 13 | fi 14 | 15 | sed -e 's|\\subsection|\\section*|g' \ 16 | -e 's|\\subsubsection|\\subsection*|g' \ 17 | -e 's|\\begin{verbatim}|\\begin{Verbatim}[frame=single]|g' \ 18 | -e 's|\\end{verbatim}|\\end{Verbatim}|g' \ 19 | -e 's|\\hyperref\[..*\]{\(..*\)}|\1|' \ 20 | ${OUT}.orig > $OUT 21 | -------------------------------------------------------------------------------- /mkfile: -------------------------------------------------------------------------------- 1 | TARG=gopherref 2 | CHAPTERS=preamble.tex \ 3 | title.tex \ 4 | writing.tex \ 5 | effective.tex \ 6 | error_handling.tex \ 7 | defer.tex \ 8 | concurrency.tex \ 9 | gobs.tex \ 10 | spec.tex \ 11 | credits.tex 12 | 13 | all:V:pdf epub 14 | 15 | pdf:V:$TARG.pdf 16 | 17 | # some of the image and TOC stuff in LaTeX works best when you process the 18 | # file twice. 19 | $TARG.pdf::$TARG.tex $CHAPTERS 20 | xelatex $TARG.tex 21 | xelatex $TARG.tex 22 | 23 | epub:V:$TARG.epub 24 | 25 | $TARG.epub::$TARG.tex $CHAPTERS 26 | go run consolidate.go -i $TARG.tex -o ${TARG}_epub.tex 27 | pandoc --toc --epub-cover-image=cover.png \ 28 | --epub-metadata=epub_metadata.xml -o \ 29 | $TARG.epub ${TARG}_epub.tex 30 | rm ${TARG}_epub.tex 31 | 32 | # this is for OS X 33 | view:V:$TARG.pdf 34 | open $TARG.pdf 35 | 36 | clean:V: 37 | rm -f *.log *.aux *.out *.toc 38 | 39 | nuke:V:clean 40 | rm -f *.pdf *.dvi *.epub 41 | -------------------------------------------------------------------------------- /credits.tex: -------------------------------------------------------------------------------- 1 | \cleardoublepage 2 | \phantomsection 3 | \addcontentsline{toc}{chapter}{Credits} 4 | 5 | \chapter*{Credits} 6 | 7 | All of these documents are taken from the \href{http://golang.org}{Go homepage}: 8 | 9 | \begin{itemize} 10 | \item \href{http://golang.org/doc/code.html}{"How to Write Go Code"}: 11 | \url{http://golang.org/doc/code.html} 12 | \item \href{http://golang.org/doc/effective_go.html}{"Effective Go"}: 13 | \url{http://golang.org/doc/effective_go.html} 14 | \item \href{http://golang.org/ref/spec}{"The Go Language Specification"}: 15 | \url{http://golang.org/ref/spec} 16 | \end{itemize} 17 | 18 | The Gopher that appears on the cover is from the \verb|docs/gopher| directory 19 | in the source packages\\ 20 | (\verb|docs/gopher/frontpage.png|). 21 | 22 | The title page was developed from the template from the 23 | \href{https://en.wikibooks.org/wiki/LaTeX/Title_Creation}{"Title Creation"} 24 | section of the \href{https://en.wikibooks.org/wiki/LaTeX}{\LaTeX wikibook}. 25 | 26 | \subsection*{See Also} 27 | \begin{itemize} 28 | \item \href{http://thestandardlibrary.com/go.html}{Go, The Standard Library} 29 | (\url{http://thestandardlibrary.com/go.html}) by 30 | \href{http://verboselogging.com/}{Daniel Huckstep}, covers the Go standard 31 | library in great detail. It is supported by excellent code examples. 32 | \end{itemize} 33 | -------------------------------------------------------------------------------- /consolidate.go: -------------------------------------------------------------------------------- 1 | // consolidate a LaTeX top-level source file into a single file in preparation 2 | // for running through pandoc to generate an ePub. 3 | package main 4 | 5 | /* 6 | Copyright (c) 2012 Kyle Isom 7 | 8 | Permission to use, copy, modify, and distribute this software for any 9 | purpose with or without fee is hereby granted, provided that the 10 | above copyright notice and this permission notice appear in all 11 | copies. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL 14 | WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED 15 | WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE 16 | AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL 17 | DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA 18 | OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 19 | TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 20 | PERFORMANCE OF THIS SOFTWARE. 21 | */ 22 | 23 | import ( 24 | "bufio" 25 | "flag" 26 | "fmt" 27 | "io" 28 | "io/ioutil" 29 | "os" 30 | "regexp" 31 | ) 32 | 33 | var inFileName, outFileName string 34 | var includeFile = regexp.MustCompile("^\\s*\\\\input{(.*)}$") 35 | var endNewline = regexp.MustCompile("\n$") 36 | 37 | func main() { 38 | outFN := flag.String("o", "gopherref_c.tex", "output file name") 39 | inFN := flag.String("i", "gopherref.tex", "input file name") 40 | flag.Parse() 41 | outFileName = *outFN 42 | inFileName = *inFN 43 | 44 | inFile, err := os.Open(inFileName) 45 | if err != nil { 46 | fmt.Println("[!] couldn't open ", inFileName) 47 | os.Exit(1) 48 | } 49 | 50 | buf := bufio.NewReader(inFile) 51 | 52 | fullLine := []byte{} 53 | for { 54 | line, isPrefix, err := buf.ReadLine() 55 | 56 | if err == io.EOF { 57 | break 58 | } else if err != nil { 59 | fmt.Printf("[!] unrecoverable error reading %s: %s\n", 60 | inFileName, err.Error()) 61 | os.Exit(1) 62 | } 63 | fullLine = append(fullLine, line...) 64 | if isPrefix { 65 | continue 66 | } 67 | if includeFile.Match(fullLine) { 68 | includeFile := includeFile.ReplaceAll(fullLine, []byte("$1.tex")) 69 | fullLine, err = ioutil.ReadFile(string(includeFile)) 70 | if err != nil { 71 | fmt.Printf("[!] unrecoverable error reading %s: %s\n", 72 | inFileName, err.Error()) 73 | os.Exit(1) 74 | } 75 | 76 | } 77 | appendFile(outFileName, fullLine) 78 | fullLine = []byte{} 79 | } 80 | } 81 | 82 | func appendFile(fileName string, line []byte) { 83 | file, err := os.OpenFile(fileName, os.O_WRONLY|os.O_APPEND, 0600) 84 | if err != nil && os.IsNotExist(err) { 85 | file, err = os.Create(fileName) 86 | } 87 | 88 | if err != nil { 89 | fmt.Printf("[+] unrecoverable error writing %s: %s\n", 90 | fileName, err.Error()) 91 | } 92 | defer file.Close() 93 | 94 | _, err = file.Write(line) 95 | if err != nil { 96 | fmt.Printf("[+] unrecoverable error writing %s: %s\n", 97 | fileName, err.Error()) 98 | } 99 | } 100 | -------------------------------------------------------------------------------- /concurrency.tex: -------------------------------------------------------------------------------- 1 | \cleardoublepage 2 | \phantomsection 3 | \addcontentsline{toc}{chapter}{Go Concurrency Patterns} 4 | \chapter*{Go Concurrency Patterns} 5 | \section*{Timing out, moving on} 6 | 7 | Concurrent programming has its own idioms. A good example is timeouts. 8 | Although Go's channels do not support them directly, they are easy to 9 | implement. Say we want to receive from the channel \texttt{ch}, but want 10 | to wait at most one second for the value to arrive. We would start by 11 | creating a signalling channel and launching a goroutine that sleeps 12 | before sending on the channel: 13 | 14 | \begin{Verbatim}[frame=single] 15 | timeout := make(chan bool, 1) 16 | go func() { 17 | time.Sleep(1 * time.Second) 18 | timeout <- true 19 | }() 20 | \end{Verbatim} 21 | 22 | We can then use a \texttt{select} statement to receive from either 23 | \texttt{ch} or \texttt{timeout}. If nothing arrives on \texttt{ch} after 24 | one second, the timeout case is selected and the attempt to read from 25 | \texttt{ch} is abandoned. 26 | 27 | \begin{Verbatim}[frame=single] 28 | select { 29 | case <-ch: 30 | // a read from ch has occurred 31 | case <-timeout: 32 | // the read from ch has timed out 33 | } 34 | \end{Verbatim} 35 | 36 | The \texttt{timeout} channel is buffered with space for 1 value, 37 | allowing the timeout goroutine to send to the channel and then exit. The 38 | goroutine doesn't know (or care) whether the value is received. This 39 | means the goroutine won't hang around forever if the \texttt{ch} receive 40 | happens before the timeout is reached. The \texttt{timeout} channel will 41 | eventually be deallocated by the garbage collector. 42 | 43 | (In this example we used \texttt{time.Sleep} to demonstrate the 44 | mechanics of goroutines and channels. In real programs you should use 45 | \texttt{ time.After}, a function that returns a channel and sends on 46 | that channel after the specified duration.) 47 | 48 | Let's look at another variation of this pattern. In this example we have 49 | a program that reads from multiple replicated databases simultaneously. 50 | The program needs only one of the answers, and it should accept the 51 | answer that arrives first. 52 | 53 | The function \texttt{Query} takes a slice of database connections and a 54 | \texttt{query} string. It queries each of the databases in parallel and 55 | returns the first response it receives: 56 | 57 | \begin{Verbatim}[frame=single] 58 | func Query(conns []Conn, query string) Result { 59 | ch := make(chan Result, 1) 60 | for _, conn := range conns { 61 | go func(c Conn) { 62 | select { 63 | case ch <- c.DoQuery(query): 64 | default: 65 | } 66 | }(conn) 67 | } 68 | return <-ch 69 | } 70 | \end{Verbatim} 71 | 72 | In this example, the closure does a non-blocking send, which it achieves 73 | by using the send operation in \texttt{select} statement with a 74 | \texttt{default} case. If the send cannot go through immediately the 75 | default case will be selected. Making the send non-blocking guarantees 76 | that none of the goroutines launched in the loop will hang around. 77 | However, if the result arrives before the main function has made it to 78 | the receive, the send could fail since no one is ready. 79 | 80 | This problem is a textbook example of what is known as a 81 | \href{https://en.wikipedia.org/wiki/Race\_condition}{race condition}, 82 | but the fix is trivial. We just make sure to buffer the channel 83 | \texttt{ch} (by adding the buffer length as the second argument to 84 | \href{/pkg/builtin/\#make}{make}), guaranteeing that the first send has 85 | a place to put the value. This ensures the send will always succeed, and 86 | the first value to arrive will be retrieved regardless of the order of 87 | execution. 88 | 89 | These two examples demonstrate the simplicity with which Go can express 90 | complex interactions between goroutines. 91 | -------------------------------------------------------------------------------- /defer.tex: -------------------------------------------------------------------------------- 1 | \cleardoublepage 2 | \phantomsection 3 | \addcontentsline{toc}{chapter}{Defer, Panic, and Recover} 4 | \chapter*{Defer, Panic and Recover} 5 | 6 | Go has the usual mechanisms for control flow: if, for, switch, goto. It 7 | also has the go statement to run code in a separate goroutine. Here I'd 8 | like to discuss some of the less common ones: defer, panic, and recover. 9 | 10 | A \textbf{defer statement} pushes a function call onto a list. The list 11 | of saved calls is executed after the surrounding function returns. Defer 12 | is commonly used to simplify functions that perform various clean-up 13 | actions. 14 | 15 | For example, let's look at a function that opens two files and copies 16 | the contents of one file to the other: 17 | 18 | \begin{Verbatim}[frame=single] 19 | func CopyFile(dstName, srcName string) (written int64, err error) { 20 | src, err := os.Open(srcName) 21 | if err != nil { 22 | return 23 | } 24 | 25 | dst, err := os.Create(dstName) 26 | if err != nil { 27 | return 28 | } 29 | 30 | written, err = io.Copy(dst, src) 31 | dst.Close() 32 | src.Close() 33 | return 34 | } 35 | \end{Verbatim} 36 | 37 | This works, but there is a bug. If the call to os.Create fails, the 38 | function will return without closing the source file. This can be easily 39 | remedied by putting a call to src.Close before the second return 40 | statement, but if the function were more complex the problem might not 41 | be so easily noticed and resolved. By introducing defer statements we 42 | can ensure that the files are always closed: 43 | 44 | \begin{Verbatim}[frame=single] 45 | func CopyFile(dstName, srcName string) (written int64, err error) { 46 | src, err := os.Open(srcName) 47 | if err != nil { 48 | return 49 | } 50 | defer src.Close() 51 | 52 | dst, err := os.Create(dstName) 53 | if err != nil { 54 | return 55 | } 56 | defer dst.Close() 57 | 58 | return io.Copy(dst, src) 59 | } 60 | \end{Verbatim} 61 | 62 | Defer statements allow us to think about closing each file right after 63 | opening it, guaranteeing that, regardless of the number of return 64 | statements in the function, the files \emph{will} be closed. 65 | 66 | The behavior of defer statements is straightforward and predictable. 67 | There are three simple rules: 68 | 69 | 1. \emph{A deferred function's arguments are evaluated when the defer 70 | statement is evaluated.} 71 | 72 | In this example, the expression ``i'' is evaluated when the Println call 73 | is deferred. The deferred call will print ``0'' after the function 74 | returns. 75 | 76 | \begin{Verbatim}[frame=single] 77 | func a() { 78 | i := 0 79 | defer fmt.Println(i) 80 | i++ 81 | return 82 | } 83 | \end{Verbatim} 84 | 85 | 2. \emph{Deferred function calls are executed in Last In First Out 86 | order}after\emph{the surrounding function returns.} 87 | 88 | This function prints ``3210'': 89 | 90 | \begin{Verbatim}[frame=single] 91 | func b() { 92 | for i := 0; i < 4; i++ { 93 | defer fmt.Print(i) 94 | } 95 | } 96 | \end{Verbatim} 97 | 98 | 3. \emph{Deferred functions may read and assign to the returning 99 | function's named return values.} 100 | 101 | In this example, a deferred function increments the return value i 102 | \emph{after} the surrounding function returns. Thus, this function 103 | returns 2: 104 | 105 | \begin{Verbatim}[frame=single] 106 | func c() (i int) { 107 | defer func() { i++ }() 108 | return 1 109 | } 110 | \end{Verbatim} 111 | 112 | This is convenient for modifying the error return value of a function; 113 | we will see an example of this shortly. 114 | 115 | \textbf{Panic} is a built-in function that stops the ordinary flow of 116 | control and begins \emph{panicking}. When the function F calls panic, 117 | execution of F stops, any deferred functions in F are executed normally, 118 | and then F returns to its caller. To the caller, F then behaves like a 119 | call to panic. The process continues up the stack until all functions in 120 | the current goroutine have returned, at which point the program crashes. 121 | Panics can be initiated by invoking panic directly. They can also be 122 | caused by runtime errors, such as out-of-bounds array accesses. 123 | 124 | \textbf{Recover} is a built-in function that regains control of a 125 | panicking goroutine. Recover is only useful inside deferred functions. 126 | During normal execution, a call to recover will return nil and have no 127 | other effect. If the current goroutine is panicking, a call to recover 128 | will capture the value given to panic and resume normal execution. 129 | 130 | Here's an example program that demonstrates the mechanics of panic and 131 | defer: 132 | 133 | \begin{Verbatim}[frame=single] 134 | package main 135 | 136 | import "fmt" 137 | import "io" // OMIT 138 | import "os" // OMIT 139 | 140 | func main() { 141 | f() 142 | fmt.Println("Returned normally from f.") 143 | } 144 | 145 | func f() { 146 | defer func() { 147 | if r := recover(); r != nil { 148 | fmt.Println("Recovered in f", r) 149 | } 150 | }() 151 | fmt.Println("Calling g.") 152 | g(0) 153 | fmt.Println("Returned normally from g.") 154 | } 155 | 156 | func g(i int) { 157 | if i > 3 { 158 | fmt.Println("Panicking!") 159 | panic(fmt.Sprintf("%v", i)) 160 | } 161 | defer fmt.Println("Defer in g", i) 162 | fmt.Println("Printing in g", i) 163 | g(i + 1) 164 | } 165 | 166 | // STOP OMIT 167 | 168 | // Revised version. 169 | func CopyFile(dstName, srcName string) (written int64, err error) { 170 | src, err := os.Open(srcName) 171 | if err != nil { 172 | return 173 | } 174 | defer src.Close() 175 | 176 | dst, err := os.Create(dstName) 177 | if err != nil { 178 | return 179 | } 180 | defer dst.Close() 181 | 182 | return io.Copy(dst, src) 183 | } 184 | \end{Verbatim} 185 | 186 | The function g takes the int i, and panics if i is greater than 3, or 187 | else it calls itself with the argument i+1. The function f defers a 188 | function that calls recover and prints the recovered value (if it is 189 | non-nil). Try to picture what the output of this program might be before 190 | reading on. 191 | 192 | The program will output: 193 | 194 | \begin{Verbatim}[frame=single] 195 | Calling g. 196 | Printing in g 0 197 | Printing in g 1 198 | Printing in g 2 199 | Printing in g 3 200 | Panicking! 201 | Defer in g 3 202 | Defer in g 2 203 | Defer in g 1 204 | Defer in g 0 205 | Recovered in f 4 206 | Returned normally from f. 207 | \end{Verbatim} 208 | 209 | If we remove the deferred function from f the panic is not recovered and 210 | reaches the top of the goroutine's call stack, terminating the program. 211 | This modified program will output: 212 | 213 | \begin{Verbatim}[frame=single] 214 | Calling g. 215 | Printing in g 0 216 | Printing in g 1 217 | Printing in g 2 218 | Printing in g 3 219 | Panicking! 220 | Defer in g 3 221 | Defer in g 2 222 | Defer in g 1 223 | Defer in g 0 224 | panic: 4 225 | 226 | panic PC=0x2a9cd8 227 | [stack trace omitted] 228 | \end{Verbatim} 229 | 230 | For a real-world example of \textbf{panic} and \textbf{recover}, see the 231 | \href{http://golang.org/pkg/encoding/json/}{json package} from the Go standard library. 232 | It decodes JSON-encoded data with a set of recursive functions. When 233 | malformed JSON is encountered, the parser calls panic to unwind the 234 | stack to the top-level function call, which recovers from the panic and 235 | returns an appropriate error value (see the `error' and `unmarshal' 236 | methods of the decodeState type in 237 | \href{http://golang.org/src/pkg/encoding/json/decode.go}{decode.go}). 238 | 239 | The convention in the Go libraries is that even when a package uses 240 | panic internally, its external API still presents explicit error return 241 | values. 242 | 243 | Other uses of \textbf{defer} (beyond the file.Close example given 244 | earlier) include releasing a mutex: 245 | 246 | \begin{Verbatim}[frame=single] 247 | mu.Lock() 248 | defer mu.Unlock() 249 | \end{Verbatim} 250 | 251 | printing a footer: 252 | 253 | \begin{Verbatim}[frame=single] 254 | printHeader() 255 | defer printFooter() 256 | \end{Verbatim} 257 | 258 | and more. 259 | 260 | In summary, the defer statement (with or without panic and recover) 261 | provides an unusual and powerful mechanism for control flow. It can be 262 | used to model a number of features implemented by special-purpose 263 | structures in other programming languages. Try it out. 264 | -------------------------------------------------------------------------------- /writing.tex: -------------------------------------------------------------------------------- 1 | \cleardoublepage 2 | \phantomsection 3 | \addcontentsline{toc}{chapter}{How to Write Go Code} 4 | \chapter*{How to Write Go Code} 5 | 6 | \section *{Introduction} 7 | This document demonstrates the development of a simple Go package 8 | and introduces the \href{http://golang.org/cmd/go/}{go} command, 9 | the standard way to fetch, build, and install Go packages and 10 | commands. 11 | 12 | \section*{Code organization} 13 | \subsection*{GOPATH and workspaces} 14 | 15 | One of Go's design goals is to make writing software easier. To 16 | that end, the go command doesn't use Makefiles or other configuration 17 | files to guide program construction. Instead, it uses the source 18 | code to find dependencies and determine build conditions. This means 19 | your source code and build scripts are always in sync; they are one 20 | and the same. 21 | 22 | The one thing you must do is set a \verb|GOPATH| environment variable. 23 | \verb|GOPATH| tells the go command (and other related tools) where to find 24 | and install the Go packages on your system. 25 | 26 | \verb|GOPATH| is a list of paths. It shares the syntax of your 27 | system's \verb|PATH| environment variable. A typical \verb|GOPATH| 28 | on a Unix system might look like this: 29 | 30 | \begin{Verbatim}[frame=single] 31 | GOPATH=/home/user/ext:/home/user/mygo 32 | \end{Verbatim} 33 | 34 | (On a Windows system use semicolons as the path separator instead of colons.) 35 | 36 | Each path in the list (in this case \verb|/home/user/ext| or 37 | \verb|/home/user/mygo|) specifies the location of a \textit{workspace}. 38 | A workspace contains Go source files and their associated package 39 | objects, and command executables. It has a prescribed structure of 40 | three subdirectories: 41 | 42 | \begin{itemize} 43 | \item \verb|src| contains Go source files, 44 | \item \verb|pkg| contains compiled package objects, and 45 | \item \verb|bin| contains executable commands. 46 | \end{itemize} 47 | 48 | Subdirectories of the \verb|src| directory hold independent packages, 49 | and all source files (\verb|.go, .c, .h, and .s|) in each subdirectory 50 | are elements of that subdirectory's package. 51 | 52 | When building a program that imports the package "\verb|widget|" 53 | the \verb|go| command looks for \verb|src/pkg/widget| inside the 54 | Go root, and then—if the package source isn't found there—it searches 55 | for \verb|src/widget| inside each workspace in order. 56 | 57 | Multiple workspaces can offer some flexibility and convenience, but 58 | for now we'll concern ourselves with only a single workspace. 59 | 60 | Let's work through a simple example. First, create a \verb|$HOME/mygo| 61 | directory and its \verb|src| subdirectory: 62 | 63 | \begin{Verbatim}[frame=single] 64 | $ mkdir -p $HOME/mygo/src # create a place to put source code 65 | \end{Verbatim} 66 | 67 | Next, set it as the \verb|GOPATH|. You should also add the \verb|bin| 68 | subdirectory to your \verb|PATH| environment variable so that you 69 | can run the commands therein without specifying their full path. 70 | To do this, add the following lines to \verb|$HOME/.profile| (or 71 | equivalent): 72 | 73 | \begin{Verbatim}[frame=single] 74 | export GOPATH=$HOME/mygo 75 | export PATH=$PATH:$HOME/mygo/bin 76 | \end{Verbatim} 77 | 78 | \subsection*{Import paths} 79 | The standard packages are given short import paths such as "\verb|fmt|" 80 | and "\verb|net/http|" for convenience. For your own projects, it 81 | is important to choose a base import path that is unlikely to collide 82 | with future additions to the standard library or other external 83 | libraries. 84 | 85 | The best way to choose an import path is to use the location of 86 | your version control repository. For instance, if your source 87 | repository is at \verb|example.com| or \verb|code.google.com/p/example|, 88 | you should begin your package paths with that URL, as in 89 | "\verb|example.com/foo/bar|" or "\verb|code.google.com/p/example/foo/bar|". 90 | Using this convention, the \verb|go| command can automatically check 91 | out and build the source code by its import path alone. 92 | 93 | If you don't intend to install your code in this way, you should 94 | at least use a unique prefix like "\verb|widgets/|", as in 95 | "\verb|widgets/foo/bar|". A good rule is to use a prefix such as 96 | your company or project name, since it is unlikely to be used by 97 | another group. 98 | 99 | We'll use example/ as our base import path: 100 | 101 | \begin{Verbatim}[frame=single] 102 | $ mkdir -p $GOPATH/src/example 103 | \end{Verbatim} 104 | 105 | \subsection*{Package names} 106 | The first statement in a Go source file should be 107 | 108 | \begin{Verbatim}[frame=single] 109 | package name 110 | \end{Verbatim} 111 | 112 | where \textit{name} is the package's default name for imports. (All 113 | files in a package must use the same \textit{name}.) 114 | 115 | Go's convention is that the package name is the last element of the 116 | import path: the package imported as "\verb|crypto/rot13|" should 117 | be named \verb|rot13|. There is no requirement that package names 118 | be unique across all packages linked into a single binary, only 119 | that the import paths (their full file names) be unique. 120 | 121 | Create a new package under \verb|example| called \verb|newmath|: 122 | 123 | \begin{Verbatim}[frame=single] 124 | $ cd $GOPATH/src/example 125 | $ mkdir newmath 126 | \end{Verbatim} 127 | 128 | Then create a file named \verb|$GOPATH/src/example/newmath/sqrt.go| 129 | containing the following Go code: 130 | 131 | \begin{Verbatim}[frame=single] 132 | // Package newmath is a trivial example package. 133 | package newmath 134 | 135 | // Sqrt returns an approximation to the square root of x. 136 | func Sqrt(x float64) float64 { 137 | // This is a terrible implementation. 138 | // Real code should import "math" and use math.Sqrt. 139 | z := 0.0 140 | for i := 0; i < 1000; i++ { 141 | z -= (z*z - x) / (2 * x) 142 | } 143 | return z 144 | } 145 | \end{Verbatim} 146 | 147 | This package is imported by the path name of the directory it's in, 148 | starting after the \verb|src| component: 149 | 150 | \begin{Verbatim}[frame=single] 151 | import "example/newmath" 152 | \end{Verbatim} 153 | 154 | See \href{http://golang.org/doc/effective_go.html#names}{Effective 155 | Go} to learn more about Go's naming conventions. 156 | 157 | \section*{Building and Installing} 158 | The \verb|go| command comprises several subcommands, the most central 159 | being \verb|install|. Running \verb|go install| \textit{importpath} 160 | builds and installs a package and its dependencies. 161 | 162 | To "install a package" means to write the package object or executable 163 | command to the \verb|pkg| or \verb|bin| subdirectory of the workspace 164 | in which the source resides. 165 | 166 | \subsection*{Building a package} 167 | 168 | To build and install the newmath package, type 169 | 170 | \begin{Verbatim}[frame=single] 171 | $ go install example/newmath 172 | \end{Verbatim} 173 | 174 | This command will produce no output if the package and its dependencies 175 | are built and installed correctly. 176 | 177 | As a convenience, the \verb|go| command will assume the current 178 | directory if no import path is specified on the command line. This 179 | sequence of commands has the same effect as the one above: 180 | 181 | \begin{Verbatim}[frame=single] 182 | $ cd $GOPATH/src/example/newmath 183 | $ go install 184 | \end{Verbatim} 185 | 186 | The resulting workspace directory tree (assuming we're running Linux 187 | on a 64-bit system) looks like this: 188 | 189 | \begin{Verbatim}[frame=single] 190 | pkg/ 191 | linux_amd64/ 192 | example/ 193 | newmath.a # package object 194 | src/ 195 | example/ 196 | newmath/ 197 | sqrt.go # package source 198 | \end{Verbatim} 199 | 200 | \subsection*{Building a command} 201 | The \verb|go| command treats code belonging to package main as an 202 | executable command and installs the package binary to the \verb|GOPATH|'s 203 | \verb|bin| subdirectory. 204 | 205 | Add a command named \verb|hello| to the source tree. First create 206 | the \verb|example/hello| directory: 207 | 208 | \begin{Verbatim}[frame=single] 209 | $ cd $GOPATH/src/example 210 | $ mkdir hello 211 | \end{Verbatim} 212 | 213 | Then create the file \verb|$GOPATH/src/example/hello/hello.go| 214 | containing the following Go code. 215 | 216 | \begin{Verbatim}[frame=single] 217 | // Hello is a trivial example of a main package. 218 | package main 219 | 220 | import ( 221 | "example/newmath" 222 | "fmt" 223 | ) 224 | 225 | func main() { 226 | fmt.Printf("Hello, world. Sqrt(2) = %v\n", newmath.Sqrt(2)) 227 | } 228 | \end{Verbatim} 229 | 230 | Next, run \verb|go install|, which builds and installs the binary 231 | to \verb|$GOPATH/bin| (or \verb|$GOBIN|, if set; to simplify 232 | presentation, this document assumes \verb|GOBIN| is unset): 233 | 234 | \begin{Verbatim}[frame=single] 235 | $ go install example/hello 236 | \end{Verbatim} 237 | 238 | To run the program, invoke it by name as you would any other command: 239 | 240 | \begin{Verbatim}[frame=single] 241 | $ $GOPATH/bin/hello 242 | Hello, world. Sqrt(2) = 1.414213562373095 243 | \end{Verbatim} 244 | 245 | If you added \verb|$HOME/mygo/bin| to your \verb|PATH|, you may 246 | omit the path to the executable: 247 | 248 | \begin{Verbatim}[frame=single] 249 | $ hello 250 | Hello, world. Sqrt(2) = 1.414213562373095 251 | \end{Verbatim} 252 | 253 | The workspace directory tree now looks like this: 254 | 255 | \begin{Verbatim}[frame=single] 256 | bin/ 257 | hello # command executable 258 | pkg/ 259 | linux_amd64/ 260 | example/ 261 | newmath.a # package object 262 | src/ 263 | example/ 264 | hello/ 265 | hello.go # command source 266 | newmath/ 267 | sqrt.go # package source 268 | \end{Verbatim} 269 | 270 | The \verb|go| command also provides a \verb|build| command, which 271 | is like \verb|install| except it builds all objects in a temporary 272 | directory and does not install them under \verb|pkg| or \verb|bin|. 273 | When building a command an executable named after the last element 274 | of the import path is written to the current directory. When building 275 | a package, \verb|go build| serves merely to test that the package 276 | and its dependencies can be built. (The resulting package object 277 | is thrown away.) 278 | 279 | \section*{Testing} 280 | Go has a lightweight test framework composed of the \verb|go test| 281 | command and the \verb|testing| package. 282 | 283 | You write a test by creating a file with a name ending in \verb|_test.go| 284 | that contains functions named \verb|TestXXX| with signature 285 | \verb|func (t *testing.T)|. The test framework runs each such function; 286 | if the function calls a failure function such as \verb|t.Error| or 287 | \verb|t.Fail|, the test is considered to have failed. 288 | 289 | Add a test to the \verb|newmath| package by creating the file 290 | \verb|$GOPATH/src/example/newmath/sqrt_test.go| containing the 291 | following Go code. 292 | 293 | \begin{Verbatim}[frame=single] 294 | package newmath 295 | 296 | import "testing" 297 | 298 | func TestSqrt(t *testing.T) { 299 | const in, out = 4, 2 300 | if x := Sqrt(in); x != out { 301 | t.Errorf("Sqrt(%v) = %v, want %v", in, x, out) 302 | } 303 | } 304 | \end{Verbatim} 305 | 306 | Now run the test with \verb|go test|: 307 | 308 | \begin{Verbatim}[frame=single] 309 | $ go test example/newmath 310 | ok example/newmath 0.165s 311 | \end{Verbatim} 312 | 313 | Run go help test and see the \href{http://golang.org/pkg/testing/}{testing 314 | package documentation} for more detail. 315 | 316 | \section*{Remote packages} 317 | An import path can describe how to obtain the package source code 318 | using a revision control system such as Git or Mercurial. The go 319 | command uses this property to automatically fetch packages from 320 | remote repositories. For instance, the examples described in this 321 | document are also kept in a Mercurial repository hosted at Google 322 | Code, code.google.com/p/go.example. If you include the repository 323 | URL in the package's import path, \verb|go get| will fetch, build, 324 | and install it automatically: 325 | 326 | \begin{Verbatim}[frame=single] 327 | $ go get code.google.com/p/go.example/hello 328 | $ $GOPATH/bin/hello 329 | Hello, world. Sqrt(2) = 1.414213562373095 330 | \end{Verbatim} 331 | 332 | If the specified package is not present in a workspace, go get will 333 | place it inside the first workspace specified by \verb|GOPATH|. (If 334 | the package does already exist, \verb|go get| skips the remote fetch 335 | and behaves the same as \verb|go install|.) 336 | 337 | After issuing the above \verb|go geti| command, the workspace 338 | directory tree should now now look like this: 339 | 340 | \begin{Verbatim}[frame=single] 341 | bin/ 342 | hello # command executable 343 | pkg/ 344 | linux_amd64/ 345 | code.google.com/p/go.example/ 346 | newmath.a # package object 347 | example/ 348 | newmath.a # package object 349 | src/ 350 | code.google.com/p/go.example/ 351 | hello/ 352 | hello.go # command source 353 | newmath/ 354 | sqrt.go # package source 355 | sqrt_test.go # test source 356 | example/ 357 | hello/ 358 | hello.go # command source 359 | newmath/ 360 | sqrt.go # package source 361 | sqrt_test.go # test source 362 | \end{Verbatim} 363 | 364 | The \verb|hello| command hosted at Google Code depends on the 365 | \verb|newmath| package within the same repository. The imports in 366 | \verb|hello.go| file use the same import path convention, so the 367 | \verb|go get| command is able to locate and install the dependent 368 | package, too. 369 | 370 | \begin{Verbatim}[frame=single] 371 | import "code.google.com/p/go.example/newmath" 372 | \end{Verbatim} 373 | 374 | This convention is the easiest way to make your Go packages available 375 | for others to use. The \href{http://godashboard.appspot.com/}{Go 376 | Project Dashboard} is a list of external Go projects including 377 | programs and libraries. 378 | 379 | For more information on using remote repositories with the \verb|go| 380 | command, see \verb|go help remote|. 381 | 382 | \section*{Further reading} 383 | 384 | See \href{http://golang.org/doc/effective_go.html}{Effective Go} 385 | for tips on writing clear, idiomatic Go code. 386 | 387 | \noindent Take \href{http://tour.golang.org/}{A Tour of Go} to learn the 388 | language proper. 389 | 390 | \noindent Visit the \href{http://golang.org/doc/#articles}{documentation page} 391 | for a set of in-depth articles about the Go language and its libraries 392 | and tools. 393 | -------------------------------------------------------------------------------- /gobs.tex: -------------------------------------------------------------------------------- 1 | \cleardoublepage 2 | \phantomsection 3 | \addcontentsline{toc}{chapter}{Gobs of Data} 4 | \chapter*{Gobs of Data} 5 | 6 | To transmit a data structure across a network or to store it in a 7 | file, it must be encoded and then decoded again. There are many 8 | encodings available, of course: \href{http://www.json.org/}{JSON}, 9 | \href{http://www.w3.org/XML/}{XML}, Google's 10 | \href{http://code.google.com/p/protobuf}{protocol buffers}, and 11 | more. And now there's another, provided by Go's 12 | \href{http://golang.org/pkg/encoding/gob/}{gob} package. 13 | 14 | Why define a new encoding? It's a lot of work and redundant at that. 15 | Why not just use one of the existing formats? Well, for one thing, 16 | we do! Go has \href{http://golang.org/pkg/}{packages} supporting 17 | all the encodings just mentioned (the 18 | \href{http://code.google.com/p/goprotobuf}{protocol buffer package} 19 | is in a separate repository but it's one of the most frequently 20 | downloaded). And for many purposes, including communicating with 21 | tools and systems written in other languages, they're the right 22 | choice. 23 | 24 | But for a Go-specific environment, such as communicating between two 25 | servers written in Go, there's an opportunity to build something much 26 | easier to use and possibly more efficient. 27 | 28 | Gobs work with the language in a way that an externally-defined, 29 | language-independent encoding cannot. At the same time, there are 30 | lessons to be learned from the existing systems. 31 | 32 | \section*{Goals} 33 | 34 | The gob package was designed with a number of goals in mind. 35 | 36 | First, and most obvious, it had to be very easy to use. First, because 37 | Go has reflection, there is no need for a separate interface definition 38 | language or ``protocol compiler''. The data structure itself is all the 39 | package should need to figure out how to encode and decode it. On the 40 | other hand, this approach means that gobs will never work as well with 41 | other languages, but that's OK: gobs are unashamedly Go-centric. 42 | 43 | Efficiency is also important. Textual representations, exemplified by 44 | XML and JSON, are too slow to put at the center of an efficient 45 | communications network. A binary encoding is necessary. 46 | 47 | Gob streams must be self-describing. Each gob stream, read from the 48 | beginning, contains sufficient information that the entire stream can be 49 | parsed by an agent that knows nothing a priori about its contents. This 50 | property means that you will always be able to decode a gob stream 51 | stored in a file, even long after you've forgotten what data it 52 | represents. 53 | 54 | There were also some things to learn from our experiences with Google 55 | protocol buffers. 56 | 57 | \section*{Protocol buffer misfeatures} 58 | 59 | Protocol buffers had a major effect on the design of gobs, but have 60 | three features that were deliberately avoided. (Leaving aside the 61 | property that protocol buffers aren't self-describing: if you don't know 62 | the data definition used to encode a protocol buffer, you might not be 63 | able to parse it.) 64 | 65 | First, protocol buffers only work on the data type we call a struct in 66 | Go. You can't encode an integer or array at the top level, only a struct 67 | with fields inside it. That seems a pointless restriction, at least in 68 | Go. If all you want to send is an array of integers, why should you have 69 | to put it into a struct first? 70 | 71 | Next, a protocol buffer definition may specify that fields \texttt{T.x} 72 | and \texttt{T.y} are required to be present whenever a value of type 73 | \texttt{T} is encoded or decoded. Although such required fields may seem 74 | like a good idea, they are costly to implement because the codec must 75 | maintain a separate data structure while encoding and decoding, to be 76 | able to report when required fields are missing. They're also a 77 | maintenance problem. Over time, one may want to modify the data 78 | definition to remove a required field, but that may cause existing 79 | clients of the data to crash. It's better not to have them in the 80 | encoding at all. (Protocol buffers also have optional fields. But if we 81 | don't have required fields, all fields are optional and that's that. 82 | There will be more to say about optional fields a little later.) 83 | 84 | The third protocol buffer misfeature is default values. If a protocol 85 | buffer omits the value for a ``defaulted'' field, then the decoded 86 | structure behaves as if the field were set to that value. This idea 87 | works nicely when you have getter and setter methods to control access 88 | to the field, but is harder to handle cleanly when the container is just 89 | a plain idiomatic struct. Required fields are also tricky to implement: 90 | where does one define the default values, what types do they have (is 91 | text UTF-8? uninterpreted bytes? how many bits in a float?) and despite 92 | the apparent simplicity, there were a number of complications in their 93 | design and implementation for protocol buffers. We decided to leave them 94 | out of gobs and fall back to Go's trivial but effective defaulting rule: 95 | unless you set something otherwise, it has the ``zero value'' for that 96 | type - and it doesn't need to be transmitted. 97 | 98 | So gobs end up looking like a sort of generalized, simplified protocol 99 | buffer. How do they work? 100 | 101 | \section*{Values} 102 | 103 | The encoded gob data isn't about \texttt{int8}s and \texttt{uint16}s. 104 | Instead, somewhat analogous to constants in Go, its integer values are 105 | abstract, sizeless numbers, either signed or unsigned. When you encode 106 | an \texttt{int8}, its value is transmitted as an unsized, 107 | variable-length integer. When you encode an \texttt{int64}, its value is 108 | also transmitted as an unsized, variable-length integer. (Signed and 109 | unsigned are treated distinctly, but the same unsized-ness applies to 110 | unsigned values too.) If both have the value 7, the bits sent on the 111 | wire will be identical. When the receiver decodes that value, it puts it 112 | into the receiver's variable, which may be of arbitrary integer type. 113 | Thus an encoder may send a 7 that came from an \texttt{int8}, but the 114 | receiver may store it in an \texttt{int64}. This is fine: the value is 115 | an integer and as a long as it fits, everything works. (If it doesn't 116 | fit, an error results.) This decoupling from the size of the variable 117 | gives some flexibility to the encoding: we can expand the type of the 118 | integer variable as the software evolves, but still be able to decode 119 | old data. 120 | 121 | This flexibility also applies to pointers. Before transmission, all 122 | pointers are flattened. Values of type \texttt{int8}, \texttt{*int8}, 123 | \texttt{**int8}, \texttt{****int8}, etc. are all transmitted as an 124 | integer value, which may then be stored in \texttt{int} of any size, or 125 | \texttt{*int}, or \texttt{******int}, etc. Again, this allows for 126 | flexibility. 127 | 128 | Flexibility also happens because, when decoding a struct, only those 129 | fields that are sent by the encoder are stored in the destination. Given 130 | the value 131 | 132 | \begin{Verbatim}[frame=single] 133 | type T struct { X, Y, Z int } // Only exported fields are encoded and decoded. 134 | var t = T{X: 7, Y: 0, Z: 8} 135 | \end{Verbatim} 136 | 137 | the encoding of \texttt{t} sends only the 7 and 8. Because it's zero, 138 | the value of \texttt{Y} isn't even sent; there's no need to send a zero 139 | value. 140 | 141 | The receiver could instead decode the value into this structure: 142 | 143 | \begin{Verbatim}[frame=single] 144 | type U struct{ X, Y *int8 } // Note: pointers to int8s 145 | var u U 146 | \end{Verbatim} 147 | 148 | and acquire a value of \texttt{u} with only \texttt{X} set (to the 149 | address of an \texttt{int8} variable set to 7); the \texttt{Z} field is 150 | ignored - where would you put it? When decoding structs, fields are 151 | matched by name and compatible type, and only fields that exist in both 152 | are affected. This simple approach finesses the ``optional field'' 153 | problem: as the type \texttt{T} evolves by adding fields, out of date 154 | receivers will still function with the part of the type they recognize. 155 | Thus gobs provide the important result of optional fields - 156 | extensibility - without any additional mechanism or notation. 157 | 158 | From integers we can build all the other types: bytes, strings, arrays, 159 | slices, maps, even floats. Floating-point values are represented by 160 | their IEEE 754 floating-point bit pattern, stored as an integer, which 161 | works fine as long as you know their type, which we always do. By the 162 | way, that integer is sent in byte-reversed order because common values 163 | of floating-point numbers, such as small integers, have a lot of zeros 164 | at the low end that we can avoid transmitting. 165 | 166 | One nice feature of gobs that Go makes possible is that they allow you 167 | to define your own encoding by having your type satisfy the 168 | \href{http://golang.org/pkg/encoding/gob/\#GobEncoder}{GobEncoder} and 169 | \href{http://golang.org/pkg/encoding/gob/\#GobDecoder}{GobDecoder} interfaces, in a 170 | manner analogous to the \href{http://golang.org/pkg/encoding/json/}{JSON} package's 171 | \href{http://golang.org/pkg/encoding/json/\#Marshaler}{Marshaler} and 172 | \href{http://golang.org/pkg/encoding/json/\#Unmarshaler}{Unmarshaler} and also to the 173 | \href{http://golang.org/pkg/fmt/\#Stringer}{Stringer} interface from 174 | \href{http://golang.org/pkg/fmt/}{package fmt}. This facility makes it possible to 175 | represent special features, enforce constraints, or hide secrets when 176 | you transmit data. See the \href{http://golang.org/pkg/encoding/gob/}{documentation} for 177 | details. 178 | 179 | \section*{Types on the wire} 180 | 181 | The first time you send a given type, the gob package includes in the 182 | data stream a description of that type. In fact, what happens is that 183 | the encoder is used to encode, in the standard gob encoding format, an 184 | internal struct that describes the type and gives it a unique number. 185 | (Basic types, plus the layout of the type description structure, are 186 | predefined by the software for bootstrapping.) After the type is 187 | described, it can be referenced by its type number. 188 | 189 | Thus when we send our first type \texttt{T}, the gob encoder sends a 190 | description of \texttt{T} and tags it with a type number, say 127. All 191 | values, including the first, are then prefixed by that number, so a 192 | stream of \texttt{T} values looks like: 193 | 194 | \begin{Verbatim}[frame=single] 195 | ("define type id" 127, definition of type T)(127, T value)(127, T value), ... 196 | \end{Verbatim} 197 | 198 | These type numbers make it possible to describe recursive types and send 199 | values of those types. Thus gobs can encode types such as trees: 200 | 201 | \begin{Verbatim}[frame=single] 202 | type Node struct { 203 | Value int 204 | Left, Right *Node 205 | } 206 | \end{Verbatim} 207 | 208 | (It's an exercise for the reader to discover how the zero-defaulting 209 | rule makes this work, even though gobs don't represent pointers.) 210 | 211 | With the type information, a gob stream is fully self-describing except 212 | for the set of bootstrap types, which is a well-defined starting point. 213 | 214 | \section*{Compiling a machine} 215 | 216 | The first time you encode a value of a given type, the gob package 217 | builds a little interpreted machine specific to that data type. It uses 218 | reflection on the type to construct that machine, but once the machine 219 | is built it does not depend on reflection. The machine uses package 220 | unsafe and some trickery to convert the data into the encoded bytes at 221 | high speed. It could use reflection and avoid unsafe, but would be 222 | significantly slower. (A similar high-speed approach is taken by the 223 | protocol buffer support for Go, whose design was influenced by the 224 | implementation of gobs.) Subsequent values of the same type use the 225 | already-compiled machine, so they can be encoded right away. 226 | 227 | Decoding is similar but harder. When you decode a value, the gob package 228 | holds a byte slice representing a value of a given encoder-defined type 229 | to decode, plus a Go value into which to decode it. The gob package 230 | builds a machine for that pair: the gob type sent on the wire crossed 231 | with the Go type provided for decoding. Once that decoding machine is 232 | built, though, it's again a reflectionless engine that uses unsafe 233 | methods to get maximum speed. 234 | 235 | \section*{Use} 236 | 237 | There's a lot going on under the hood, but the result is an efficient, 238 | easy-to-use encoding system for transmitting data. Here's a complete 239 | example showing differing encoded and decoded types. Note how easy it is 240 | to send and receive values; all you need to do is present values and 241 | variables to the \href{http://golang.org/pkg/encoding/gob/}{gob package} and it does all 242 | the work. 243 | 244 | \begin{Verbatim}[frame=single] 245 | package main 246 | 247 | import ( 248 | "bytes" 249 | "encoding/gob" 250 | "fmt" 251 | "log" 252 | ) 253 | 254 | type P struct { 255 | X, Y, Z int 256 | Name string 257 | } 258 | 259 | type Q struct { 260 | X, Y *int32 261 | Name string 262 | } 263 | 264 | func main() { 265 | // Initialize the encoder and decoder. Normally enc and dec would be 266 | // bound to network connections and the encoder and decoder would 267 | // run in different processes. 268 | var network bytes.Buffer // Stand-in for a network connection 269 | enc := gob.NewEncoder(&network) // Will write to network. 270 | dec := gob.NewDecoder(&network) // Will read from network. 271 | // Encode (send) the value. 272 | err := enc.Encode(P{3, 4, 5, "Pythagoras"}) 273 | if err != nil { 274 | log.Fatal("encode error:", err) 275 | } 276 | // Decode (receive) the value. 277 | var q Q 278 | err = dec.Decode(&q) 279 | if err != nil { 280 | log.Fatal("decode error:", err) 281 | } 282 | fmt.Printf("%q: {%d,%d}\n", q.Name, *q.X, *q.Y) 283 | } 284 | \end{Verbatim} 285 | 286 | You can compile and run this example code in the 287 | \href{http://play.golang.org/p/\_-OJV-rwMq}{Go Playground}. 288 | 289 | The \href{http://golang.org/pkg/net/rpc/}{rpc package} builds on 290 | gobs to turn this encode/decode automation into transport for method 291 | calls across the network. That's a subject for another article. 292 | 293 | \textbf{Details} 294 | 295 | The \href{http://golang.org/pkg/encoding/gob/}{gob package 296 | documentation}, especially the file 297 | \href{http://golang.org/src/pkg/encoding/gob/doc.go}{doc.go}, expands 298 | on many of the details described here and includes a full worked 299 | example showing how the encoding represents data. If you are 300 | interested in the innards of the gob implementation, that's a good 301 | place to start. 302 | -------------------------------------------------------------------------------- /error_handling.tex: -------------------------------------------------------------------------------- 1 | \cleardoublepage 2 | \phantomsection 3 | \addcontentsline{toc}{chapter}{Error Handling and Go} 4 | \chapter*{Error Handling and Go} 5 | 6 | If you have written any Go code you have probably encountered the 7 | built-in \texttt{error} type. Go code uses \texttt{error} values to 8 | indicate an abnormal state. For example, the \texttt{os.Open} function 9 | returns a non-nil \texttt{error} value when it fails to open a file. 10 | 11 | \begin{Verbatim}[frame=single] 12 | func Open(name string) (file *File, err error) 13 | \end{Verbatim} 14 | 15 | The following code uses \texttt{os.Open} to open a file. If an error 16 | occurs it calls \texttt{log.Fatal} to print the error message and stop. 17 | 18 | \begin{Verbatim}[frame=single] 19 | f, err := os.Open("filename.ext") 20 | if err != nil { 21 | log.Fatal(err) 22 | } 23 | // do something with the open *File f 24 | \end{Verbatim} 25 | 26 | You can get a lot done in Go knowing just this about the \texttt{error} 27 | type, but in this article we'll take a closer look at \texttt{error} and 28 | discuss some good practices for error handling in Go. 29 | 30 | \textbf{The error type} 31 | 32 | The \texttt{error} type is an interface type. An \texttt{error} variable 33 | represents any value that can describe itself as a string. Here is the 34 | interface's declaration: 35 | 36 | \begin{Verbatim}[frame=single] 37 | type error interface { 38 | Error() string 39 | } 40 | \end{Verbatim} 41 | 42 | The \texttt{error} type, as with all built in types, is 43 | \href{http://golang.org/doc/go\_spec.html\#Predeclared\_identifiers}{predeclared} in the 44 | \href{http://golang.org/doc/go\_spec.html\#Blocks}{universe block}. 45 | 46 | The most commonly-used \texttt{error} implementation is the 47 | \href{http://golang.org/pkg/errors/}{errors} package's unexported \texttt{errorString} 48 | type. 49 | 50 | \begin{Verbatim}[frame=single] 51 | // errorString is a trivial implementation of error. 52 | type errorString struct { 53 | s string 54 | } 55 | 56 | func (e *errorString) Error() string { 57 | return e.s 58 | } 59 | \end{Verbatim} 60 | 61 | You can construct one of these values with the \texttt{errors.New} 62 | function. It takes a string that it converts to an 63 | \texttt{errors.errorString} and returns as an \texttt{error} value. 64 | 65 | \begin{Verbatim}[frame=single] 66 | // New returns an error that formats as the given text. 67 | func New(text string) error { 68 | return &errorString{text} 69 | } 70 | \end{Verbatim} 71 | 72 | Here's how you might use \texttt{errors.New}: 73 | 74 | \begin{Verbatim}[frame=single] 75 | func Sqrt(f float64) (float64, error) { 76 | if f < 0 { 77 | return 0, errors.New("math: square root of negative number") 78 | } 79 | // implementation 80 | } 81 | \end{Verbatim} 82 | 83 | A caller passing a negative argument to \texttt{Sqrt} receives a non-nil 84 | \texttt{error} value (whose concrete representation is an 85 | \texttt{errors.errorString} value). The caller can access the error 86 | string (``math: square root of\ldots{}'') by calling the 87 | \texttt{error}'s \texttt{Error} method, or by just printing it: 88 | 89 | \begin{Verbatim}[frame=single] 90 | f, err := Sqrt(-1) 91 | if err != nil { 92 | fmt.Println(err) 93 | } 94 | \end{Verbatim} 95 | 96 | The \href{http://golang.org/pkg/fmt/}{fmt} package formats an 97 | \texttt{error} value by calling its \texttt{Error() string} method. 98 | 99 | It is the error implementation's responsibility to summarize the 100 | context. The error returned by \texttt{os.Open} formats as ``open 101 | /etc/passwd: permission denied,'' not just ``permission denied.'' 102 | The error returned by our \texttt{Sqrt} is missing information about 103 | the invalid argument. 104 | 105 | To add that information, a useful function is the \texttt{fmt} 106 | package's \texttt{Errorf}. It formats a string according to 107 | \texttt{Printf}'s rules and returns it as an \texttt{error} created 108 | by \texttt{errors.New}. 109 | 110 | \begin{Verbatim}[frame=single] 111 | if f < 0 { 112 | return 0, fmt.Errorf("math: square root of negative number %g", f) 113 | } 114 | \end{Verbatim} 115 | 116 | In many cases \texttt{fmt.Errorf} is good enough, but since 117 | \texttt{error} is an interface, you can use arbitrary data structures as 118 | error values, to allow callers to inspect the details of the error. 119 | 120 | For instance, our hypothetical callers might want to recover the invalid 121 | argument passed to \texttt{Sqrt}. We can enable that by defining a new 122 | error implementation instead of using \texttt{errors.errorString}: 123 | 124 | \begin{Verbatim}[frame=single] 125 | type NegativeSqrtError float64 126 | 127 | func (f NegativeSqrtError) Error() string { 128 | return fmt.Sprintf("math: square root of negative number %g", float64(f)) 129 | } 130 | \end{Verbatim} 131 | 132 | A sophisticated caller can then use a 133 | \href{http://golang.org/doc/go\_spec.html\#Type\_assertions}{type 134 | assertion} to check for a \texttt{NegativeSqrtError} and handle it 135 | specially, while callers that just pass the error to \texttt{fmt.Println} 136 | or \texttt{log.Fatal} will see no change in behavior. 137 | 138 | As another example, the \href{http://golang.org/pkg/encoding/json/}{json} 139 | package specifies a \texttt{SyntaxError} type that the \texttt{json.Decode} 140 | function returns when it encounters a syntax error parsing a JSON 141 | blob. 142 | 143 | \begin{Verbatim}[frame=single] 144 | type SyntaxError struct { 145 | msg string // description of error 146 | Offset int64 // error occurred after reading Offset bytes 147 | } 148 | 149 | func (e *SyntaxError) Error() string { return e.msg } 150 | \end{Verbatim} 151 | 152 | The \texttt{Offset} field isn't even shown in the default formatting of 153 | the error, but callers can use it to add file and line information to 154 | their error messages: 155 | 156 | \begin{Verbatim}[frame=single] 157 | if err := dec.Decode(&val); err != nil { 158 | if serr, ok := err.(*json.SyntaxError); ok { 159 | line, col := findLine(f, serr.Offset) 160 | return fmt.Errorf("%s:%d:%d: %v", f.Name(), line, col, err) 161 | } 162 | return err 163 | } 164 | \end{Verbatim} 165 | 166 | (This is a slightly simplified version of some 167 | \href{http://camlistore.org/code/?p=camlistore.git;a=blob;f=lib/go/camli/jsonconfig/eval.go\#l68}{actual 168 | code} from the \href{http://camlistore.org}{Camlistore} project.) 169 | 170 | The \texttt{error} interface requires only a \texttt{Error} method; 171 | specific error implementations might have additional methods. For 172 | instance, the \href{http://golang.org/pkg/net/}{net} package returns errors of type 173 | \texttt{error}, following the usual convention, but some of the error 174 | implementations have additional methods defined by the 175 | \texttt{net.Error} interface: 176 | 177 | \begin{Verbatim}[frame=single] 178 | package net 179 | 180 | type Error interface { 181 | error 182 | Timeout() bool // Is the error a timeout? 183 | Temporary() bool // Is the error temporary? 184 | } 185 | \end{Verbatim} 186 | 187 | Client code can test for a \texttt{net.Error} with a type assertion and 188 | then distinguish transient network errors from permanent ones. For 189 | instance, a web crawler might sleep and retry when it encounters a 190 | temporary error and give up otherwise. 191 | 192 | \begin{Verbatim}[frame=single] 193 | if nerr, ok := err.(net.Error); ok && nerr.Temporary() { 194 | time.Sleep(1e9) 195 | continue 196 | } 197 | if err != nil { 198 | log.Fatal(err) 199 | } 200 | \end{Verbatim} 201 | 202 | \section*{Simplifying repetitive error handling} 203 | 204 | In Go, error handling is important. The language's design and 205 | conventions encourage you to explicitly check for errors where they 206 | occur (as distinct from the convention in other languages of throwing 207 | exceptions and sometimes catching them). In some cases this makes Go 208 | code verbose, but fortunately there are some techniques you can use to 209 | minimize repetitive error handling. 210 | 211 | Consider an \href{http://code.google.com/appengine/docs/go/}{App Engine} 212 | application with an HTTP handler that retrieves a record from the 213 | datastore and formats it with a template. 214 | 215 | \begin{Verbatim}[frame=single] 216 | func init() { 217 | http.HandleFunc("/view", viewRecord) 218 | } 219 | 220 | func viewRecord(w http.ResponseWriter, r *http.Request) { 221 | c := appengine.NewContext(r) 222 | key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil) 223 | record := new(Record) 224 | if err := datastore.Get(c, key, record); err != nil { 225 | http.Error(w, err.Error(), 500) 226 | return 227 | } 228 | if err := viewTemplate.Execute(w, record); err != nil { 229 | http.Error(w, err.Error(), 500) 230 | } 231 | } 232 | \end{Verbatim} 233 | 234 | This function handles errors returned by the \texttt{datastore.Get} 235 | function and \texttt{viewTemplate}'s \texttt{Execute} method. In both 236 | cases, it presents a simple error message to the user with the HTTP 237 | status code 500 (``Internal Server Error''). This looks like a 238 | manageable amount of code, but add some more HTTP handlers and you 239 | quickly end up with many copies of identical error handling code. 240 | 241 | To reduce the repetition we can define our own HTTP \texttt{appHandler} 242 | type that includes an \texttt{error} return value: 243 | 244 | \begin{Verbatim}[frame=single] 245 | type appHandler func(http.ResponseWriter, *http.Request) error 246 | \end{Verbatim} 247 | 248 | Then we can change our \texttt{viewRecord} function to return errors: 249 | 250 | \begin{Verbatim}[frame=single] 251 | func viewRecord(w http.ResponseWriter, r *http.Request) error { 252 | c := appengine.NewContext(r) 253 | key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil) 254 | record := new(Record) 255 | if err := datastore.Get(c, key, record); err != nil { 256 | return err 257 | } 258 | return viewTemplate.Execute(w, record) 259 | } 260 | \end{Verbatim} 261 | 262 | This is simpler than the original version, but the 263 | \href{http://golang.org/pkg/net/http/}{http} package doesn't understand functions that 264 | return \texttt{error}. To fix this we can implement the 265 | \texttt{http.Handler} interface's \texttt{ServeHTTP} method on 266 | \texttt{appHandler}: 267 | 268 | \begin{Verbatim}[frame=single] 269 | func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { 270 | if err := fn(w, r); err != nil { 271 | http.Error(w, err.Error(), 500) 272 | } 273 | } 274 | \end{Verbatim} 275 | 276 | The \texttt{ServeHTTP} method calls the \texttt{appHandler} function and 277 | displays the returned error (if any) to the user. Notice that the 278 | method's receiver, \texttt{fn}, is a function. (Go can do that!) The 279 | method invokes the function by calling the receiver in the expression 280 | \texttt{fn(w, r)}. 281 | 282 | Now when registering \texttt{viewRecord} with the http package we use 283 | the \texttt{Handle} function (instead of \texttt{HandleFunc}) as 284 | \texttt{appHandler} is an \texttt{http.Handler} (not an 285 | \texttt{http.HandlerFunc}). 286 | 287 | \begin{Verbatim}[frame=single] 288 | func init() { 289 | http.Handle("/view", appHandler(viewRecord)) 290 | } 291 | \end{Verbatim} 292 | 293 | With this basic error handling infrastructure in place, we can make it 294 | more user friendly. Rather than just displaying the error string, it 295 | would be better to give the user a simple error message with an 296 | appropriate HTTP status code, while logging the full error to the App 297 | Engine developer console for debugging purposes. 298 | 299 | To do this we create an \texttt{appError} struct containing an 300 | \texttt{error} and some other fields: 301 | 302 | \begin{Verbatim}[frame=single] 303 | type appError struct { 304 | Error error 305 | Message string 306 | Code int 307 | } 308 | \end{Verbatim} 309 | 310 | Next we modify the appHandler type to return \texttt{*appError} values: 311 | 312 | \begin{Verbatim}[frame=single] 313 | type appHandler func(http.ResponseWriter, *http.Request) *appError 314 | \end{Verbatim} 315 | 316 | (It's usually a mistake to pass back the concrete type of an error 317 | rather than \texttt{error}, for reasons discussed in 318 | \href{http://golang.org/doc/go\_faq.html\#nil\_error}{the Go FAQ}, but it's the right 319 | thing to do here because \texttt{ServeHTTP} is the only place that sees 320 | the value and uses its contents.) 321 | 322 | And make \texttt{appHandler}'s \texttt{ServeHTTP} method display the 323 | \texttt{appError}'s \texttt{Message} to the user with the correct HTTP 324 | status \texttt{Code} and log the full \texttt{Error} to the developer 325 | console: 326 | 327 | \begin{Verbatim}[frame=single] 328 | func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { 329 | if e := fn(w, r); e != nil { // e is *appError, not os.Error. 330 | c := appengine.NewContext(r) 331 | c.Errorf("%v", e.Error) 332 | http.Error(w, e.Message, e.Code) 333 | } 334 | } 335 | \end{Verbatim} 336 | 337 | Finally, we update \texttt{viewRecord} to the new function signature and 338 | have it return more context when it encounters an error: 339 | 340 | \begin{Verbatim}[frame=single] 341 | func viewRecord(w http.ResponseWriter, r *http.Request) *appError { 342 | c := appengine.NewContext(r) 343 | key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil) 344 | record := new(Record) 345 | if err := datastore.Get(c, key, record); err != nil { 346 | return &appError{err, "Record not found", 404} 347 | } 348 | if err := viewTemplate.Execute(w, record); err != nil { 349 | return &appError{err, "Can't display record", 500} 350 | } 351 | return nil 352 | } 353 | \end{Verbatim} 354 | 355 | This version of \texttt{viewRecord} is the same length as the original, 356 | but now each of those lines has specific meaning and we are providing a 357 | friendlier user experience. 358 | 359 | It doesn't end there; we can further improve the error handling in our 360 | application. Some ideas: 361 | 362 | \begin{itemize} 363 | \item 364 | give the error handler a pretty HTML template, 365 | \item 366 | make debugging easier by writing the stack trace to the HTTP response 367 | when the user is an administrator, 368 | \item 369 | write a constructor function for \texttt{appError} that stores the 370 | stack trace for easier debugging, 371 | \item 372 | recover from panics inside the \texttt{appHandler}, logging the error 373 | to the console as ``Critical,'' while telling the user ``a serious 374 | error has occurred.'' This is a nice touch to avoid exposing the user 375 | to inscrutable error messages caused by programming errors. See the 376 | \href{defer\_panic\_recover.html}{Defer, Panic, and Recover} article 377 | for more details. 378 | \end{itemize} 379 | 380 | \section*{Conclusion} 381 | 382 | Proper error handling is an essential requirement of good software. By 383 | employing the techniques described in this post you should be able to 384 | write more reliable and succinct Go code. 385 | -------------------------------------------------------------------------------- /effective.tex: -------------------------------------------------------------------------------- 1 | \cleardoublepage 2 | \phantomsection 3 | \addcontentsline{toc}{chapter}{Effective Go} 4 | \chapter*{Effective Go} 5 | 6 | \section*{Introduction} 7 | 8 | Go is a new language. Although it borrows ideas from existing languages, 9 | it has unusual properties that make effective Go programs different in 10 | character from programs written in its relatives. A straightforward 11 | translation of a C++ or Java program into Go is unlikely to produce a 12 | satisfactory result---Java programs are written in Java, not Go. On the 13 | other hand, thinking about the problem from a Go perspective could 14 | produce a successful but quite different program. In other words, to 15 | write Go well, it's important to understand its properties and idioms. 16 | It's also important to know the established conventions for programming 17 | in Go, such as naming, formatting, program construction, and so on, so 18 | that programs you write will be easy for other Go programmers to 19 | understand. 20 | 21 | This document gives tips for writing clear, idiomatic Go code. It 22 | augments the \href{/ref/spec}{language specification}, the 23 | \href{http://tour.golang.org/}{Tour of Go}, and 24 | \href{/doc/code.html}{How to Write Go Code}, all of which you should 25 | read first. 26 | 27 | \subsection*{Examples} 28 | 29 | The \href{/src/pkg/}{Go package sources} are intended to serve not only 30 | as the core library but also as examples of how to use the language. If 31 | you have a question about how to approach a problem or how something 32 | might be implemented, they can provide answers, ideas and background. 33 | 34 | \section*{Formatting} 35 | 36 | Formatting issues are the most contentious but the least consequential. 37 | People can adapt to different formatting styles but it's better if they 38 | don't have to, and less time is devoted to the topic if everyone adheres 39 | to the same style. The problem is how to approach this Utopia without a 40 | long prescriptive style guide. 41 | 42 | With Go we take an unusual approach and let the machine take care of 43 | most formatting issues. The \texttt{gofmt} program (also available as 44 | \texttt{go fmt}, which operates at the package level rather than source 45 | file level) reads a Go program and emits the source in a standard style 46 | of indentation and vertical alignment, retaining and if necessary 47 | reformatting comments. If you want to know how to handle some new layout 48 | situation, run \texttt{gofmt}; if the answer doesn't seem right, 49 | rearrange your program (or file a bug about \texttt{gofmt}), don't work 50 | around it. 51 | 52 | As an example, there's no need to spend time lining up the comments on 53 | the fields of a structure. \texttt{Gofmt} will do that for you. Given 54 | the declaration 55 | 56 | \begin{Verbatim}[frame=single] 57 | type T struct { 58 | name string // name of the object 59 | value int // its value 60 | } 61 | \end{Verbatim} 62 | 63 | \texttt{gofmt} will line up the columns: 64 | 65 | \begin{Verbatim}[frame=single] 66 | type T struct { 67 | name string // name of the object 68 | value int // its value 69 | } 70 | \end{Verbatim} 71 | 72 | All Go code in the standard packages has been formatted with 73 | \texttt{gofmt}. 74 | 75 | Some formatting details remain. Very briefly, 76 | 77 | \begin{description} 78 | \item[Indentation] 79 | We use tabs for indentation and \texttt{gofmt} emits them by default. 80 | Use spaces only if you must. 81 | \item[Line length] 82 | Go has no line length limit. Don't worry about overflowing a punched 83 | card. If a line feels too long, wrap it and indent with an extra tab. 84 | \item[Parentheses] 85 | Go needs fewer parentheses: control structures (\texttt{if}, 86 | \texttt{for}, \texttt{switch}) do not have parentheses in their syntax. 87 | Also, the operator precedence hierarchy is shorter and clearer, so 88 | 89 | \begin{Verbatim}[frame=single] 90 | x<<8 + y<<16 91 | \end{Verbatim} 92 | 93 | means what the spacing implies. 94 | \end{description} 95 | 96 | \section*{Commentary} 97 | 98 | Go provides C-style \texttt{/* */} block comments and C++-style 99 | \texttt{//} line comments. Line comments are the norm; block comments 100 | appear mostly as package comments and are also useful to disable large 101 | swaths of code. 102 | 103 | The program---and web server---\texttt{godoc} processes Go source files 104 | to extract documentation about the contents of the package. Comments 105 | that appear before top-level declarations, with no intervening newlines, 106 | are extracted along with the declaration to serve as explanatory text 107 | for the item. The nature and style of these comments determines the 108 | quality of the documentation \texttt{godoc} produces. 109 | 110 | Every package should have a \emph{package comment}, a block comment 111 | preceding the package clause. For multi-file packages, the package 112 | comment only needs to be present in one file, and any one will do. The 113 | package comment should introduce the package and provide information 114 | relevant to the package as a whole. It will appear first on the 115 | \texttt{godoc} page and should set up the detailed documentation that 116 | follows. 117 | 118 | \begin{Verbatim}[frame=single] 119 | /* 120 | Package regexp implements a simple library for 121 | regular expressions. 122 | 123 | The syntax of the regular expressions accepted is: 124 | 125 | regexp: 126 | concatenation { '|' concatenation } 127 | concatenation: 128 | { closure } 129 | closure: 130 | term [ '*' | '+' | '?' ] 131 | term: 132 | '^' 133 | '$' 134 | '.' 135 | character 136 | '[' [ '^' ] character-ranges ']' 137 | '(' regexp ')' 138 | */ 139 | package regexp 140 | \end{Verbatim} 141 | 142 | If the package is simple, the package comment can be brief. 143 | 144 | \begin{Verbatim}[frame=single] 145 | // Package path implements utility routines for 146 | // manipulating slash-separated filename paths. 147 | \end{Verbatim} 148 | 149 | Comments do not need extra formatting such as banners of stars. The 150 | generated output may not even be presented in a fixed-width font, so 151 | don't depend on spacing for alignment---\texttt{godoc}, like 152 | \texttt{gofmt}, takes care of that. The comments are uninterpreted plain 153 | text, so HTML and other annotations such as \texttt{\_this\_} will 154 | reproduce \emph{verbatim} and should not be used. Depending on the 155 | context, \texttt{godoc} might not even reformat comments, so make sure 156 | they look good straight up: use correct spelling, punctuation, and 157 | sentence structure, fold long lines, and so on. 158 | 159 | Inside a package, any comment immediately preceding a top-level 160 | declaration serves as a \emph{doc comment} for that declaration. Every 161 | exported (capitalized) name in a program should have a doc comment. 162 | 163 | Doc comments work best as complete sentences, which allow a wide variety 164 | of automated presentations. The first sentence should be a one-sentence 165 | summary that starts with the name being declared. 166 | 167 | \begin{Verbatim}[frame=single] 168 | // Compile parses a regular expression and returns, if successful, a Regexp 169 | // object that can be used to match against text. 170 | func Compile(str string) (regexp *Regexp, err error) { 171 | \end{Verbatim} 172 | 173 | Go's declaration syntax allows grouping of declarations. A single doc 174 | comment can introduce a group of related constants or variables. Since 175 | the whole declaration is presented, such a comment can often be 176 | perfunctory. 177 | 178 | \begin{Verbatim}[frame=single] 179 | // Error codes returned by failures to parse an expression. 180 | var ( 181 | ErrInternal = errors.New("regexp: internal error") 182 | ErrUnmatchedLpar = errors.New("regexp: unmatched '('") 183 | ErrUnmatchedRpar = errors.New("regexp: unmatched ')'") 184 | ... 185 | ) 186 | \end{Verbatim} 187 | 188 | Even for private names, grouping can also indicate relationships between 189 | items, such as the fact that a set of variables is protected by a mutex. 190 | 191 | \begin{Verbatim}[frame=single] 192 | var ( 193 | countLock sync.Mutex 194 | inputCount uint32 195 | outputCount uint32 196 | errorCount uint32 197 | ) 198 | \end{Verbatim} 199 | 200 | \section*{Names} 201 | 202 | Names are as important in Go as in any other language. In some cases 203 | they even have semantic effect: for instance, the visibility of a name 204 | outside a package is determined by whether its first character is upper 205 | case. It's therefore worth spending a little time talking about naming 206 | conventions in Go programs. 207 | 208 | \subsection*{Package names} 209 | 210 | When a package is imported, the package name becomes an accessor for the 211 | contents. After 212 | 213 | \begin{Verbatim}[frame=single] 214 | import "bytes" 215 | \end{Verbatim} 216 | 217 | the importing package can talk about \texttt{bytes.Buffer}. It's helpful 218 | if everyone using the package can use the same name to refer to its 219 | contents, which implies that the package name should be good: short, 220 | concise, evocative. By convention, packages are given lower case, 221 | single-word names; there should be no need for underscores or mixedCaps. 222 | Err on the side of brevity, since everyone using your package will be 223 | typing that name. And don't worry about collisions \emph{a priori}. The 224 | package name is only the default name for imports; it need not be unique 225 | across all source code, and in the rare case of a collision the 226 | importing package can choose a different name to use locally. In any 227 | case, confusion is rare because the file name in the import determines 228 | just which package is being used. 229 | 230 | Another convention is that the package name is the base name of its 231 | source directory; the package in \texttt{src/pkg/encoding/base64} is 232 | imported as \texttt{"encoding/base64"} but has name \texttt{base64}, not 233 | \texttt{encoding\_base64} and not \texttt{encodingBase64}. 234 | 235 | The importer of a package will use the name to refer to its contents 236 | (the \texttt{import .} notation is intended mostly for tests and other 237 | unusual situations and should be avoided unless necessary), so exported 238 | names in the package can use that fact to avoid stutter. For instance, 239 | the buffered reader type in the \texttt{bufio} package is called 240 | \texttt{Reader}, not \texttt{BufReader}, because users see it as 241 | \texttt{bufio.Reader}, which is a clear, concise name. Moreover, because 242 | imported entities are always addressed with their package name, 243 | \texttt{bufio.Reader} does not conflict with \texttt{io.Reader}. 244 | Similarly, the function to make new instances of 245 | \texttt{ring.Ring}---which is the definition of a \emph{constructor} in 246 | Go---would normally be called \texttt{NewRing}, but since \texttt{Ring} 247 | is the only type exported by the package, and since the package is 248 | called \texttt{ring}, it's called just \texttt{New}, which clients of 249 | the package see as \texttt{ring.New}. Use the package structure to help 250 | you choose good names. 251 | 252 | Another short example is \texttt{once.Do}; \texttt{once.Do(setup)} reads 253 | well and would not be improved by writing 254 | \texttt{once.DoOrWaitUntilDone(setup)}. Long names don't automatically 255 | make things more readable. If the name represents something intricate or 256 | subtle, it's usually better to write a helpful doc comment than to 257 | attempt to put all the information into the name. 258 | 259 | \subsection*{Getters} 260 | 261 | Go doesn't provide automatic support for getters and setters. There's 262 | nothing wrong with providing getters and setters yourself, and it's 263 | often appropriate to do so, but it's neither idiomatic nor necessary to 264 | put \texttt{Get} into the getter's name. If you have a field called 265 | \texttt{owner} (lower case, unexported), the getter method should be 266 | called \texttt{Owner} (upper case, exported), not \texttt{GetOwner}. The 267 | use of upper-case names for export provides the hook to discriminate the 268 | field from the method. A setter function, if needed, will likely be 269 | called \texttt{SetOwner}. Both names read well in practice: 270 | 271 | \begin{Verbatim}[frame=single] 272 | owner := obj.Owner() 273 | if owner != user { 274 | obj.SetOwner(user) 275 | } 276 | \end{Verbatim} 277 | 278 | \subsection*{Interface names} 279 | 280 | By convention, one-method interfaces are named by the method name plus 281 | the -er suffix: \texttt{Reader}, \texttt{Writer}, \texttt{Formatter} 282 | etc. 283 | 284 | There are a number of such names and it's productive to honor them and 285 | the function names they capture. \texttt{Read}, \texttt{Write}, 286 | \texttt{Close}, \texttt{Flush}, \texttt{String} and so on have canonical 287 | signatures and meanings. To avoid confusion, don't give your method one 288 | of those names unless it has the same signature and meaning. Conversely, 289 | if your type implements a method with the same meaning as a method on a 290 | well-known type, give it the same name and signature; call your 291 | string-converter method \texttt{String} not \texttt{ToString}. 292 | 293 | \subsection*{MixedCaps} 294 | 295 | Finally, the convention in Go is to use \texttt{MixedCaps} or 296 | \texttt{mixedCaps} rather than underscores to write multiword names. 297 | 298 | \section*{Semicolons} 299 | 300 | Like C, Go's formal grammar uses semicolons to terminate statements; 301 | unlike C, those semicolons do not appear in the source. Instead the 302 | lexer uses a simple rule to insert semicolons automatically as it scans, 303 | so the input text is mostly free of them. 304 | 305 | The rule is this. If the last token before a newline is an identifier 306 | (which includes words like \texttt{int} and \texttt{float64}), a basic 307 | literal such as a number or string constant, or one of the tokens 308 | 309 | \begin{Verbatim}[frame=single] 310 | break continue fallthrough return ++ -- ) } 311 | \end{Verbatim} 312 | 313 | the lexer always inserts a semicolon after the token. This could be 314 | summarized as, ``if the newline comes after a token that could end a 315 | statement, insert a semicolon''. 316 | 317 | A semicolon can also be omitted immediately before a closing brace, so a 318 | statement such as 319 | 320 | \begin{Verbatim}[frame=single] 321 | go func() { for { dst <- <-src } }() 322 | \end{Verbatim} 323 | 324 | needs no semicolons. Idiomatic Go programs have semicolons only in 325 | places such as \texttt{for} loop clauses, to separate the initializer, 326 | condition, and continuation elements. They are also necessary to 327 | separate multiple statements on a line, should you write code that way. 328 | 329 | One caveat. You should never put the opening brace of a control 330 | structure (\texttt{if}, \texttt{for}, \texttt{switch}, or 331 | \texttt{select}) on the next line. If you do, a semicolon will be 332 | inserted before the brace, which could cause unwanted effects. Write 333 | them like this 334 | 335 | \begin{Verbatim}[frame=single] 336 | if i < f() { 337 | g() 338 | } 339 | \end{Verbatim} 340 | 341 | not like this 342 | 343 | \begin{Verbatim}[frame=single] 344 | if i < f() // wrong! 345 | { // wrong! 346 | g() 347 | } 348 | \end{Verbatim} 349 | 350 | \section*{Control structures} 351 | 352 | The control structures of Go are related to those of C but differ in 353 | important ways. There is no \texttt{do} or \texttt{while} loop, only a 354 | slightly generalized \texttt{for}; \texttt{switch} is more flexible; 355 | \texttt{if} and \texttt{switch} accept an optional initialization 356 | statement like that of \texttt{for}; and there are new control 357 | structures including a type switch and a multiway communications 358 | multiplexer, \texttt{select}. The syntax is also slightly different: 359 | there are no parentheses and the bodies must always be brace-delimited. 360 | 361 | \subsection*{If} 362 | 363 | In Go a simple \texttt{if} looks like this: 364 | 365 | \begin{Verbatim}[frame=single] 366 | if x > 0 { 367 | return y 368 | } 369 | \end{Verbatim} 370 | 371 | Mandatory braces encourage writing simple \texttt{if} statements on 372 | multiple lines. It's good style to do so anyway, especially when the 373 | body contains a control statement such as a \texttt{return} or 374 | \texttt{break}. 375 | 376 | Since \texttt{if} and \texttt{switch} accept an initialization 377 | statement, it's common to see one used to set up a local variable. 378 | 379 | \begin{Verbatim}[frame=single] 380 | if err := file.Chmod(0664); err != nil { 381 | log.Print(err) 382 | return err 383 | } 384 | \end{Verbatim} 385 | 386 | In the Go libraries, you'll find that when an \texttt{if} statement 387 | doesn't flow into the next statement---that is, the body ends in 388 | \texttt{break}, \texttt{continue}, \texttt{goto}, or 389 | \texttt{return}---the unnecessary \texttt{else} is omitted. 390 | 391 | \begin{Verbatim}[frame=single] 392 | f, err := os.Open(name) 393 | if err != nil { 394 | return err 395 | } 396 | codeUsing(f) 397 | \end{Verbatim} 398 | 399 | This is an example of a common situation where code must guard against a 400 | sequence of error conditions. The code reads well if the successful flow 401 | of control runs down the page, eliminating error cases as they arise. 402 | Since error cases tend to end in \texttt{return} statements, the 403 | resulting code needs no \texttt{else} statements. 404 | 405 | \begin{Verbatim}[frame=single] 406 | f, err := os.Open(name) 407 | if err != nil { 408 | return err 409 | } 410 | d, err := f.Stat() 411 | if err != nil { 412 | f.Close() 413 | return err 414 | } 415 | codeUsing(f, d) 416 | \end{Verbatim} 417 | 418 | \subsection*{Redeclaration} 419 | 420 | An aside: The last example in the previous section demonstrates a detail 421 | of how the \texttt{:=} short declaration form works. The declaration 422 | that calls \texttt{os.Open} reads, 423 | 424 | \begin{Verbatim}[frame=single] 425 | f, err := os.Open(name) 426 | \end{Verbatim} 427 | 428 | This statement declares two variables, \texttt{f} and \texttt{err}. A 429 | few lines later, the call to \texttt{f.Stat} reads, 430 | 431 | \begin{Verbatim}[frame=single] 432 | d, err := f.Stat() 433 | \end{Verbatim} 434 | 435 | which looks as if it declares \texttt{d} and \texttt{err}. Notice, 436 | though, that \texttt{err} appears in both statements. This duplication 437 | is legal: \texttt{err} is declared by the first statement, but only 438 | \emph{re-assigned} in the second. This means that the call to 439 | \texttt{f.Stat} uses the existing \texttt{err} variable declared above, 440 | and just gives it a new value. 441 | 442 | In a \texttt{:=} declaration a variable \texttt{v} may appear even if it 443 | has already been declared, provided: 444 | 445 | \begin{itemize} 446 | \item 447 | this declaration is in the same scope as the existing declaration of 448 | \texttt{v} (if \texttt{v} is already declared in an outer scope, the 449 | declaration will create a new variable), 450 | \item 451 | the corresponding value in the initialization is assignable to 452 | \texttt{v}, and 453 | \item 454 | there is at least one other variable in the declaration that is being 455 | declared anew. 456 | \end{itemize} 457 | 458 | This unusual property is pure pragmatism, making it easy to use a single 459 | \texttt{err} value, for example, in a long \texttt{if-else} chain. 460 | You'll see it used often. 461 | 462 | \subsection*{For} 463 | 464 | The Go \texttt{for} loop is similar to---but not the same as---C's. It 465 | unifies \texttt{for} and \texttt{while} and there is no 466 | \texttt{do-while}. There are three forms, only one of which has 467 | semicolons. 468 | 469 | \begin{Verbatim}[frame=single] 470 | // Like a C for 471 | for init; condition; post { } 472 | 473 | // Like a C while 474 | for condition { } 475 | 476 | // Like a C for(;;) 477 | for { } 478 | \end{Verbatim} 479 | 480 | Short declarations make it easy to declare the index variable right in 481 | the loop. 482 | 483 | \begin{Verbatim}[frame=single] 484 | sum := 0 485 | for i := 0; i < 10; i++ { 486 | sum += i 487 | } 488 | \end{Verbatim} 489 | 490 | If you're looping over an array, slice, string, or map, or reading from 491 | a channel, a \texttt{range} clause can manage the loop. 492 | 493 | \begin{Verbatim}[frame=single] 494 | for key, value := range oldMap { 495 | newMap[key] = value 496 | } 497 | \end{Verbatim} 498 | 499 | If you only need the first item in the range (the key or index), drop 500 | the second: 501 | 502 | \begin{Verbatim}[frame=single] 503 | for key := range m { 504 | if expired(key) { 505 | delete(m, key) 506 | } 507 | } 508 | \end{Verbatim} 509 | 510 | If you only need the second item in the range (the value), use the 511 | \emph{blank identifier}, an underscore, to discard the first: 512 | 513 | \begin{Verbatim}[frame=single] 514 | sum := 0 515 | for _, value := range array { 516 | sum += value 517 | } 518 | \end{Verbatim} 519 | 520 | For strings, the \texttt{range} does more work for you, breaking out 521 | individual Unicode characters by parsing the UTF-8. Erroneous encodings 522 | consume one byte and produce the replacement rune U+FFFD. The loop 523 | 524 | \begin{Verbatim}[frame=single] 525 | for pos, char := range "日本語" { 526 | fmt.Printf("character %c starts at byte position %d\n", char, pos) 527 | } 528 | \end{Verbatim} 529 | 530 | prints 531 | 532 | \begin{Verbatim}[frame=single] 533 | character 日 starts at byte position 0 534 | character 本 starts at byte position 3 535 | character 語 starts at byte position 6 536 | \end{Verbatim} 537 | 538 | Finally, Go has no comma operator and \texttt{++} and \texttt{-{}-} are 539 | statements not expressions. Thus if you want to run multiple variables 540 | in a \texttt{for} you should use parallel assignment. 541 | 542 | \begin{Verbatim}[frame=single] 543 | // Reverse a 544 | for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 { 545 | a[i], a[j] = a[j], a[i] 546 | } 547 | \end{Verbatim} 548 | 549 | \subsection*{Switch} 550 | 551 | Go's \texttt{switch} is more general than C's. The expressions need not 552 | be constants or even integers, the cases are evaluated top to bottom 553 | until a match is found, and if the \texttt{switch} has no expression it 554 | switches on \texttt{true}. It's therefore possible---and idiomatic---to 555 | write an \texttt{if}-\texttt{else}-\texttt{if}-\texttt{else} chain as a 556 | \texttt{switch}. 557 | 558 | \begin{Verbatim}[frame=single] 559 | func unhex(c byte) byte { 560 | switch { 561 | case '0' <= c && c <= '9': 562 | return c - '0' 563 | case 'a' <= c && c <= 'f': 564 | return c - 'a' + 10 565 | case 'A' <= c && c <= 'F': 566 | return c - 'A' + 10 567 | } 568 | return 0 569 | } 570 | \end{Verbatim} 571 | 572 | There is no automatic fall through, but cases can be presented in 573 | comma-separated lists. 574 | 575 | \begin{Verbatim}[frame=single] 576 | func shouldEscape(c byte) bool { 577 | switch c { 578 | case ' ', '?', '&', '=', '#', '+', '%': 579 | return true 580 | } 581 | return false 582 | } 583 | \end{Verbatim} 584 | 585 | Here's a comparison routine for byte arrays that uses two 586 | \texttt{switch} statements: 587 | 588 | \begin{Verbatim}[frame=single] 589 | // Compare returns an integer comparing the two byte arrays, 590 | // lexicographically. 591 | // The result will be 0 if a == b, -1 if a < b, and +1 if a > b 592 | func Compare(a, b []byte) int { 593 | for i := 0; i < len(a) && i < len(b); i++ { 594 | switch { 595 | case a[i] > b[i]: 596 | return 1 597 | case a[i] < b[i]: 598 | return -1 599 | } 600 | } 601 | switch { 602 | case len(a) < len(b): 603 | return -1 604 | case len(a) > len(b): 605 | return 1 606 | } 607 | return 0 608 | } 609 | \end{Verbatim} 610 | 611 | A switch can also be used to discover the dynamic type of an interface 612 | variable. Such a \emph{type switch} uses the syntax of a type assertion 613 | with the keyword \texttt{type} inside the parentheses. If the switch 614 | declares a variable in the expression, the variable will have the 615 | corresponding type in each clause. 616 | 617 | \begin{Verbatim}[frame=single] 618 | switch t := interfaceValue.(type) { 619 | default: 620 | fmt.Printf("unexpected type %T", t) // %T prints type 621 | case bool: 622 | fmt.Printf("boolean %t\n", t) 623 | case int: 624 | fmt.Printf("integer %d\n", t) 625 | case *bool: 626 | fmt.Printf("pointer to boolean %t\n", *t) 627 | case *int: 628 | fmt.Printf("pointer to integer %d\n", *t) 629 | } 630 | \end{Verbatim} 631 | 632 | \section*{Functions} 633 | 634 | \subsection*{Multiple return values} 635 | 636 | One of Go's unusual features is that functions and methods can return 637 | multiple values. This form can be used to improve on a couple of clumsy 638 | idioms in C programs: in-band error returns (such as \texttt{-1} for 639 | \texttt{EOF}) and modifying an argument. 640 | 641 | In C, a write error is signaled by a negative count with the error code 642 | secreted away in a volatile location. In Go, \texttt{Write} can return a 643 | count \emph{and} an error: ``Yes, you wrote some bytes but not all of 644 | them because you filled the device''. The signature of 645 | \texttt{File.Write} in package \texttt{os} is: 646 | 647 | \begin{Verbatim}[frame=single] 648 | func (file *File) Write(b []byte) (n int, err error) 649 | \end{Verbatim} 650 | 651 | and as the documentation says, it returns the number of bytes written 652 | and a non-nil \texttt{error} when \texttt{n} \texttt{!=} 653 | \texttt{len(b)}. This is a common style; see the section on error 654 | handling for more examples. 655 | 656 | A similar approach obviates the need to pass a pointer to a return value 657 | to simulate a reference parameter. Here's a simple-minded function to 658 | grab a number from a position in a byte array, returning the number and 659 | the next position. 660 | 661 | \begin{Verbatim}[frame=single] 662 | func nextInt(b []byte, i int) (int, int) { 663 | for ; i < len(b) && !isDigit(b[i]); i++ { 664 | } 665 | x := 0 666 | for ; i < len(b) && isDigit(b[i]); i++ { 667 | x = x*10 + int(b[i])-'0' 668 | } 669 | return x, i 670 | } 671 | \end{Verbatim} 672 | 673 | You could use it to scan the numbers in an input array \texttt{a} like 674 | this: 675 | 676 | \begin{Verbatim}[frame=single] 677 | for i := 0; i < len(a); { 678 | x, i = nextInt(a, i) 679 | fmt.Println(x) 680 | } 681 | \end{Verbatim} 682 | 683 | \subsection*{Named result parameters} 684 | 685 | The return or result ``parameters'' of a Go function can be given names 686 | and used as regular variables, just like the incoming parameters. When 687 | named, they are initialized to the zero values for their types when the 688 | function begins; if the function executes a \texttt{return} statement 689 | with no arguments, the current values of the result parameters are used 690 | as the returned values. 691 | 692 | The names are not mandatory but they can make code shorter and clearer: 693 | they're documentation. If we name the results of \texttt{nextInt} it 694 | becomes obvious which returned \texttt{int} is which. 695 | 696 | \begin{Verbatim}[frame=single] 697 | func nextInt(b []byte, pos int) (value, nextPos int) { 698 | \end{Verbatim} 699 | 700 | Because named results are initialized and tied to an unadorned return, 701 | they can simplify as well as clarify. Here's a version of 702 | \texttt{io.ReadFull} that uses them well: 703 | 704 | \begin{Verbatim}[frame=single] 705 | func ReadFull(r Reader, buf []byte) (n int, err error) { 706 | for len(buf) > 0 && err == nil { 707 | var nr int 708 | nr, err = r.Read(buf) 709 | n += nr 710 | buf = buf[nr:] 711 | } 712 | return 713 | } 714 | \end{Verbatim} 715 | 716 | \subsection*{Defer} 717 | 718 | Go's \texttt{defer} statement schedules a function call (the 719 | \emph{deferred} function) to be run immediately before the function 720 | executing the \texttt{defer} returns. It's an unusual but effective way 721 | to deal with situations such as resources that must be released 722 | regardless of which path a function takes to return. The canonical 723 | examples are unlocking a mutex or closing a file. 724 | 725 | \begin{Verbatim}[frame=single] 726 | // Contents returns the file's contents as a string. 727 | func Contents(filename string) (string, error) { 728 | f, err := os.Open(filename) 729 | if err != nil { 730 | return "", err 731 | } 732 | defer f.Close() // f.Close will run when we're finished. 733 | 734 | var result []byte 735 | buf := make([]byte, 100) 736 | for { 737 | n, err := f.Read(buf[0:]) 738 | result = append(result, buf[0:n]...) // append is discussed later. 739 | if err != nil { 740 | if err == io.EOF { 741 | break 742 | } 743 | return "", err // f will be closed if we return here. 744 | } 745 | } 746 | return string(result), nil // f will be closed if we return here. 747 | } 748 | \end{Verbatim} 749 | 750 | Deferring a call to a function such as \texttt{Close} has two 751 | advantages. First, it guarantees that you will never forget to close the 752 | file, a mistake that's easy to make if you later edit the function to 753 | add a new return path. Second, it means that the close sits near the 754 | open, which is much clearer than placing it at the end of the function. 755 | 756 | The arguments to the deferred function (which include the receiver if 757 | the function is a method) are evaluated when the \emph{defer} executes, 758 | not when the \emph{call} executes. Besides avoiding worries about 759 | variables changing values as the function executes, this means that a 760 | single deferred call site can defer multiple function executions. Here's 761 | a silly example. 762 | 763 | \begin{Verbatim}[frame=single] 764 | for i := 0; i < 5; i++ { 765 | defer fmt.Printf("%d ", i) 766 | } 767 | \end{Verbatim} 768 | 769 | Deferred functions are executed in LIFO order, so this code will cause 770 | \texttt{4 3 2 1 0} to be printed when the function returns. A more 771 | plausible example is a simple way to trace function execution through 772 | the program. We could write a couple of simple tracing routines like 773 | this: 774 | 775 | \begin{Verbatim}[frame=single] 776 | func trace(s string) { fmt.Println("entering:", s) } 777 | func untrace(s string) { fmt.Println("leaving:", s) } 778 | 779 | // Use them like this: 780 | func a() { 781 | trace("a") 782 | defer untrace("a") 783 | // do something.... 784 | } 785 | \end{Verbatim} 786 | 787 | We can do better by exploiting the fact that arguments to deferred 788 | functions are evaluated when the \texttt{defer} executes. The tracing 789 | routine can set up the argument to the untracing routine. This example: 790 | 791 | \begin{Verbatim}[frame=single] 792 | func trace(s string) string { 793 | fmt.Println("entering:", s) 794 | return s 795 | } 796 | 797 | func un(s string) { 798 | fmt.Println("leaving:", s) 799 | } 800 | 801 | func a() { 802 | defer un(trace("a")) 803 | fmt.Println("in a") 804 | } 805 | 806 | func b() { 807 | defer un(trace("b")) 808 | fmt.Println("in b") 809 | a() 810 | } 811 | 812 | func main() { 813 | b() 814 | } 815 | \end{Verbatim} 816 | 817 | prints 818 | 819 | \begin{Verbatim}[frame=single] 820 | entering: b 821 | in b 822 | entering: a 823 | in a 824 | leaving: a 825 | leaving: b 826 | \end{Verbatim} 827 | 828 | For programmers accustomed to block-level resource management from other 829 | languages, \texttt{defer} may seem peculiar, but its most interesting 830 | and powerful applications come precisely from the fact that it's not 831 | block-based but function-based. In the section on \texttt{panic} and 832 | \texttt{recover} we'll see another example of its possibilities. 833 | 834 | \section*{Data} 835 | 836 | \subsection*{Allocation with \texttt{new}} 837 | 838 | Go has two allocation primitives, the built-in functions \texttt{new} 839 | and \texttt{make}. They do different things and apply to different 840 | types, which can be confusing, but the rules are simple. Let's talk 841 | about \texttt{new} first. It's a built-in function that allocates 842 | memory, but unlike its namesakes in some other languages it does not 843 | \emph{initialize} the memory, it only \emph{zeros} it. That is, 844 | \texttt{new(T)} allocates zeroed storage for a new item of type 845 | \texttt{T} and returns its address, a value of type \texttt{*T}. In Go 846 | terminology, it returns a pointer to a newly allocated zero value of 847 | type \texttt{T}. 848 | 849 | Since the memory returned by \texttt{new} is zeroed, it's helpful to 850 | arrange when designing your data structures that the zero value of each 851 | type can be used without further initialization. This means a user of 852 | the data structure can create one with \texttt{new} and get right to 853 | work. For example, the documentation for \texttt{bytes.Buffer} states 854 | that "the zero value for \texttt{Buffer} is an empty buffer ready to 855 | use." Similarly, \texttt{sync.Mutex} does not have an explicit 856 | constructor or \texttt{Init} method. Instead, the zero value for a 857 | \texttt{sync.Mutex} is defined to be an unlocked mutex. 858 | 859 | The zero-value-is-useful property works transitively. Consider this type 860 | declaration. 861 | 862 | \begin{Verbatim}[frame=single] 863 | type SyncedBuffer struct { 864 | lock sync.Mutex 865 | buffer bytes.Buffer 866 | } 867 | \end{Verbatim} 868 | 869 | Values of type \texttt{SyncedBuffer} are also ready to use immediately 870 | upon allocation or just declaration. In the next snippet, both 871 | \texttt{p} and \texttt{v} will work correctly without further 872 | arrangement. 873 | 874 | \begin{Verbatim}[frame=single] 875 | p := new(SyncedBuffer) // type *SyncedBuffer 876 | var v SyncedBuffer // type SyncedBuffer 877 | \end{Verbatim} 878 | 879 | \subsection*{Constructors and composite literals} 880 | 881 | Sometimes the zero value isn't good enough and an initializing 882 | constructor is necessary, as in this example derived from package 883 | \texttt{os}. 884 | 885 | \begin{Verbatim}[frame=single] 886 | func NewFile(fd int, name string) *File { 887 | if fd < 0 { 888 | return nil 889 | } 890 | f := new(File) 891 | f.fd = fd 892 | f.name = name 893 | f.dirinfo = nil 894 | f.nepipe = 0 895 | return f 896 | } 897 | \end{Verbatim} 898 | 899 | There's a lot of boiler plate in there. We can simplify it using a 900 | \emph{composite literal}, which is an expression that creates a new 901 | instance each time it is evaluated. 902 | 903 | \begin{Verbatim}[frame=single] 904 | func NewFile(fd int, name string) *File { 905 | if fd < 0 { 906 | return nil 907 | } 908 | f := File{fd, name, nil, 0} 909 | return &f 910 | } 911 | \end{Verbatim} 912 | 913 | Note that, unlike in C, it's perfectly OK to return the address of a 914 | local variable; the storage associated with the variable survives after 915 | the function returns. In fact, taking the address of a composite literal 916 | allocates a fresh instance each time it is evaluated, so we can combine 917 | these last two lines. 918 | 919 | \begin{Verbatim}[frame=single] 920 | return &File{fd, name, nil, 0} 921 | \end{Verbatim} 922 | 923 | The fields of a composite literal are laid out in order and must all be 924 | present. However, by labeling the elements explicitly as 925 | \emph{field}\texttt{:}\emph{value} pairs, the initializers can appear in 926 | any order, with the missing ones left as their respective zero values. 927 | Thus we could say 928 | 929 | \begin{Verbatim}[frame=single] 930 | return &File{fd: fd, name: name} 931 | \end{Verbatim} 932 | 933 | As a limiting case, if a composite literal contains no fields at all, it 934 | creates a zero value for the type. The expressions \texttt{new(File)} 935 | and \texttt{\&File\{\}} are equivalent. 936 | 937 | Composite literals can also be created for arrays, slices, and maps, 938 | with the field labels being indices or map keys as appropriate. In these 939 | examples, the initializations work regardless of the values of 940 | \texttt{Enone}, \texttt{Eio}, and \texttt{Einval}, as long as they are 941 | distinct. 942 | 943 | \begin{Verbatim}[frame=single] 944 | a := [...]string {Enone: "no error", Eio: "Eio", Einval: "invalid argument"} 945 | s := []string {Enone: "no error", Eio: "Eio", Einval: "invalid argument"} 946 | m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"} 947 | \end{Verbatim} 948 | 949 | \subsection*{Allocation with \texttt{make}} 950 | 951 | Back to allocation. The built-in function 952 | \texttt{make(T, }\emph{args}\texttt{)} serves a purpose different from 953 | \texttt{new(T)}. It creates slices, maps, and channels only, and it 954 | returns an \emph{initialized} (not \emph{zeroed}) value of type 955 | \texttt{T} (not \texttt{*T}). The reason for the distinction is that 956 | these three types are, under the covers, references to data structures 957 | that must be initialized before use. A slice, for example, is a 958 | three-item descriptor containing a pointer to the data (inside an 959 | array), the length, and the capacity, and until those items are 960 | initialized, the slice is \texttt{nil}. For slices, maps, and channels, 961 | \texttt{make} initializes the internal data structure and prepares the 962 | value for use. For instance, 963 | 964 | \begin{Verbatim}[frame=single] 965 | make([]int, 10, 100) 966 | \end{Verbatim} 967 | 968 | allocates an array of 100 ints and then creates a slice structure with 969 | length 10 and a capacity of 100 pointing at the first 10 elements of the 970 | array. (When making a slice, the capacity can be omitted; see the 971 | section on slices for more information.) In contrast, 972 | \texttt{new({[}{]}int)} returns a pointer to a newly allocated, zeroed 973 | slice structure, that is, a pointer to a \texttt{nil} slice value. 974 | 975 | These examples illustrate the difference between \texttt{new} and 976 | \texttt{make}. 977 | 978 | \begin{Verbatim}[frame=single] 979 | var p *[]int = new([]int) // allocates slice structure; *p == nil; rarely useful 980 | var v []int = make([]int, 100) // the slice v now refers to a new array of 100 ints 981 | 982 | // Unnecessarily complex: 983 | var p *[]int = new([]int) 984 | *p = make([]int, 100, 100) 985 | 986 | // Idiomatic: 987 | v := make([]int, 100) 988 | \end{Verbatim} 989 | 990 | Remember that \texttt{make} applies only to maps, slices and channels 991 | and does not return a pointer. To obtain an explicit pointer allocate 992 | with \texttt{new}. 993 | 994 | \subsection*{Arrays} 995 | 996 | Arrays are useful when planning the detailed layout of memory and 997 | sometimes can help avoid allocation, but primarily they are a building 998 | block for slices, the subject of the next section. To lay the foundation 999 | for that topic, here are a few words about arrays. 1000 | 1001 | There are major differences between the ways arrays work in Go and C. In 1002 | Go, 1003 | 1004 | \begin{itemize} 1005 | \item 1006 | Arrays are values. Assigning one array to another copies all the 1007 | elements. 1008 | \item 1009 | In particular, if you pass an array to a function, it will receive a 1010 | \emph{copy} of the array, not a pointer to it. 1011 | \item 1012 | The size of an array is part of its type. The types 1013 | \texttt{{[}10{]}int} and \texttt{{[}20{]}int} are distinct. 1014 | \end{itemize} 1015 | 1016 | The value property can be useful but also expensive; if you want C-like 1017 | behavior and efficiency, you can pass a pointer to the array. 1018 | 1019 | \begin{Verbatim}[frame=single] 1020 | func Sum(a *[3]float64) (sum float64) { 1021 | for _, v := range *a { 1022 | sum += v 1023 | } 1024 | return 1025 | } 1026 | 1027 | array := [...]float64{7.0, 8.5, 9.1} 1028 | x := Sum(&array) // Note the explicit address-of operator 1029 | \end{Verbatim} 1030 | 1031 | But even this style isn't idiomatic Go. Slices are. 1032 | 1033 | \subsection*{Slices} 1034 | 1035 | Slices wrap arrays to give a more general, powerful, and convenient 1036 | interface to sequences of data. Except for items with explicit dimension 1037 | such as transformation matrices, most array programming in Go is done 1038 | with slices rather than simple arrays. 1039 | 1040 | Slices are \emph{reference types}, which means that if you assign one 1041 | slice to another, both refer to the same underlying array. For instance, 1042 | if a function takes a slice argument, changes it makes to the elements 1043 | of the slice will be visible to the caller, analogous to passing a 1044 | pointer to the underlying array. A \texttt{Read} function can therefore 1045 | accept a slice argument rather than a pointer and a count; the length 1046 | within the slice sets an upper limit of how much data to read. Here is 1047 | the signature of the \texttt{Read} method of the \texttt{File} type in 1048 | package \texttt{os}: 1049 | 1050 | \begin{Verbatim}[frame=single] 1051 | func (file *File) Read(buf []byte) (n int, err error) 1052 | \end{Verbatim} 1053 | 1054 | The method returns the number of bytes read and an error value, if any. 1055 | To read into the first 32 bytes of a larger buffer \texttt{b}, 1056 | \emph{slice} (here used as a verb) the buffer. 1057 | 1058 | \begin{Verbatim}[frame=single] 1059 | n, err := f.Read(buf[0:32]) 1060 | \end{Verbatim} 1061 | 1062 | Such slicing is common and efficient. In fact, leaving efficiency aside 1063 | for the moment, the following snippet would also read the first 32 bytes 1064 | of the buffer. 1065 | 1066 | \begin{Verbatim}[frame=single] 1067 | var n int 1068 | var err error 1069 | for i := 0; i < 32; i++ { 1070 | nbytes, e := f.Read(buf[i:i+1]) // Read one byte. 1071 | if nbytes == 0 || e != nil { 1072 | err = e 1073 | break 1074 | } 1075 | n += nbytes 1076 | } 1077 | \end{Verbatim} 1078 | 1079 | The length of a slice may be changed as long as it still fits within the 1080 | limits of the underlying array; just assign it to a slice of itself. The 1081 | \emph{capacity} of a slice, accessible by the built-in function 1082 | \texttt{cap}, reports the maximum length the slice may assume. Here is a 1083 | function to append data to a slice. If the data exceeds the capacity, 1084 | the slice is reallocated. The resulting slice is returned. The function 1085 | uses the fact that \texttt{len} and \texttt{cap} are legal when applied 1086 | to the \texttt{nil} slice, and return 0. 1087 | 1088 | \begin{Verbatim}[frame=single] 1089 | func Append(slice, data[]byte) []byte { 1090 | l := len(slice) 1091 | if l + len(data) > cap(slice) { // reallocate 1092 | // Allocate double what's needed, for future growth. 1093 | newSlice := make([]byte, (l+len(data))*2) 1094 | // The copy function is predeclared and works for any slice type. 1095 | copy(newSlice, slice) 1096 | slice = newSlice 1097 | } 1098 | slice = slice[0:l+len(data)] 1099 | for i, c := range data { 1100 | slice[l+i] = c 1101 | } 1102 | return slice 1103 | } 1104 | \end{Verbatim} 1105 | 1106 | We must return the slice afterwards because, although \texttt{Append} 1107 | can modify the elements of \texttt{slice}, the slice itself (the 1108 | run-time data structure holding the pointer, length, and capacity) is 1109 | passed by value. 1110 | 1111 | The idea of appending to a slice is so useful it's captured by the 1112 | \texttt{append} built-in function. To understand that function's design, 1113 | though, we need a little more information, so we'll return to it later. 1114 | 1115 | \hyperdef{}{maps}{\subsection*{Maps}\label{maps}} 1116 | 1117 | Maps are a convenient and powerful built-in data structure to associate 1118 | values of different types. The key can be of any type for which the 1119 | equality operator is defined, such as integers, floating point and 1120 | complex numbers, strings, pointers, interfaces (as long as the dynamic 1121 | type supports equality), structs and arrays. Slices cannot be used as 1122 | map keys, because equality is not defined on them. Like slices, maps are 1123 | a reference type. If you pass a map to a function that changes the 1124 | contents of the map, the changes will be visible in the caller. 1125 | 1126 | Maps can be constructed using the usual composite literal syntax with 1127 | colon-separated key-value pairs, so it's easy to build them during 1128 | initialization. 1129 | 1130 | \begin{Verbatim}[frame=single] 1131 | var timeZone = map[string] int { 1132 | "UTC": 0*60*60, 1133 | "EST": -5*60*60, 1134 | "CST": -6*60*60, 1135 | "MST": -7*60*60, 1136 | "PST": -8*60*60, 1137 | } 1138 | \end{Verbatim} 1139 | 1140 | Assigning and fetching map values looks syntactically just like doing 1141 | the same for arrays except that the index doesn't need to be an integer. 1142 | 1143 | \begin{Verbatim}[frame=single] 1144 | offset := timeZone["EST"] 1145 | \end{Verbatim} 1146 | 1147 | An attempt to fetch a map value with a key that is not present in the 1148 | map will return the zero value for the type of the entries in the map. 1149 | For instance, if the map contains integers, looking up a non-existent 1150 | key will return \texttt{0}. A set can be implemented as a map with value 1151 | type \texttt{bool}. Set the map entry to \texttt{true} to put the value 1152 | in the set, and then test it by simple indexing. 1153 | 1154 | \begin{Verbatim}[frame=single] 1155 | attended := map[string] bool { 1156 | "Ann": true, 1157 | "Joe": true, 1158 | ... 1159 | } 1160 | 1161 | if attended[person] { // will be false if person is not in the map 1162 | fmt.Println(person, "was at the meeting") 1163 | } 1164 | \end{Verbatim} 1165 | 1166 | Sometimes you need to distinguish a missing entry from a zero value. Is 1167 | there an entry for \texttt{"UTC"} or is that zero value because it's not 1168 | in the map at all? You can discriminate with a form of multiple 1169 | assignment. 1170 | 1171 | \begin{Verbatim}[frame=single] 1172 | var seconds int 1173 | var ok bool 1174 | seconds, ok = timeZone[tz] 1175 | \end{Verbatim} 1176 | 1177 | For obvious reasons this is called the ``comma ok'' idiom. In this 1178 | example, if \texttt{tz} is present, \texttt{seconds} will be set 1179 | appropriately and \texttt{ok} will be true; if not, \texttt{seconds} 1180 | will be set to zero and \texttt{ok} will be false. Here's a function 1181 | that puts it together with a nice error report: 1182 | 1183 | \begin{Verbatim}[frame=single] 1184 | func offset(tz string) int { 1185 | if seconds, ok := timeZone[tz]; ok { 1186 | return seconds 1187 | } 1188 | log.Println("unknown time zone:", tz) 1189 | return 0 1190 | } 1191 | \end{Verbatim} 1192 | 1193 | To test for presence in the map without worrying about the actual value, 1194 | you can use the blank identifier (\texttt{\_}). The blank identifier can 1195 | be assigned or declared with any value of any type, with the value 1196 | discarded harmlessly. For testing just presence in a map, use the blank 1197 | identifier in place of the usual variable for the value. 1198 | 1199 | \begin{Verbatim}[frame=single] 1200 | _, present := timeZone[tz] 1201 | \end{Verbatim} 1202 | 1203 | To delete a map entry, use the \texttt{delete} built-in function, whose 1204 | arguments are the map and the key to be deleted. It's safe to do this 1205 | this even if the key is already absent from the map. 1206 | 1207 | \begin{Verbatim}[frame=single] 1208 | delete(timeZone, "PDT") // Now on Standard Time 1209 | \end{Verbatim} 1210 | 1211 | \subsection*{Printing} 1212 | 1213 | Formatted printing in Go uses a style similar to C's \texttt{printf} 1214 | family but is richer and more general. The functions live in the 1215 | \texttt{fmt} package and have capitalized names: \texttt{fmt.Printf}, 1216 | \texttt{fmt.Fprintf}, \texttt{fmt.Sprintf} and so on. The string 1217 | functions (\texttt{Sprintf} etc.) return a string rather than filling in 1218 | a provided buffer. 1219 | 1220 | You don't need to provide a format string. For each of \texttt{Printf}, 1221 | \texttt{Fprintf} and \texttt{Sprintf} there is another pair of 1222 | functions, for instance \texttt{Print} and \texttt{Println}. These 1223 | functions do not take a format string but instead generate a default 1224 | format for each argument. The \texttt{Println} versions also insert a 1225 | blank between arguments and append a newline to the output while the 1226 | \texttt{Print} versions add blanks only if the operand on neither side 1227 | is a string. In this example each line produces the same output. 1228 | 1229 | \begin{Verbatim}[frame=single] 1230 | fmt.Printf("Hello %d\n", 23) 1231 | fmt.Fprint(os.Stdout, "Hello ", 23, "\n") 1232 | fmt.Println("Hello", 23) 1233 | fmt.Println(fmt.Sprint("Hello ", 23)) 1234 | \end{Verbatim} 1235 | 1236 | As mentioned in the \href{http://tour.golang.org}{Tour}, 1237 | \texttt{fmt.Fprint} and friends take as a first argument any object that 1238 | implements the \texttt{io.Writer} interface; the variables 1239 | \texttt{os.Stdout} and \texttt{os.Stderr} are familiar instances. 1240 | 1241 | Here things start to diverge from C. First, the numeric formats such as 1242 | \texttt{\%d} do not take flags for signedness or size; instead, the 1243 | printing routines use the type of the argument to decide these 1244 | properties. 1245 | 1246 | \begin{Verbatim}[frame=single] 1247 | var x uint64 = 1<<64 - 1 1248 | fmt.Printf("%d %x; %d %x\n", x, x, int64(x), int64(x)) 1249 | \end{Verbatim} 1250 | 1251 | prints 1252 | 1253 | \begin{Verbatim}[frame=single] 1254 | 18446744073709551615 ffffffffffffffff; -1 -1 1255 | \end{Verbatim} 1256 | 1257 | If you just want the default conversion, such as decimal for integers, 1258 | you can use the catchall format \texttt{\%v} (for ``value''); the result 1259 | is exactly what \texttt{Print} and \texttt{Println} would produce. 1260 | Moreover, that format can print \emph{any} value, even arrays, structs, 1261 | and maps. Here is a print statement for the time zone map defined in the 1262 | previous section. 1263 | 1264 | \begin{Verbatim}[frame=single] 1265 | fmt.Printf("%v\n", timeZone) // or just fmt.Println(timeZone) 1266 | \end{Verbatim} 1267 | 1268 | which gives output 1269 | 1270 | \begin{Verbatim}[frame=single] 1271 | map[CST:-21600 PST:-28800 EST:-18000 UTC:0 MST:-25200] 1272 | \end{Verbatim} 1273 | 1274 | For maps the keys may be output in any order, of course. When printing a 1275 | struct, the modified format \texttt{\%+v} annotates the fields of the 1276 | structure with their names, and for any value the alternate format 1277 | \texttt{\%\#v} prints the value in full Go syntax. 1278 | 1279 | \begin{Verbatim}[frame=single] 1280 | type T struct { 1281 | a int 1282 | b float64 1283 | c string 1284 | } 1285 | t := &T{ 7, -2.35, "abc\tdef" } 1286 | fmt.Printf("%v\n", t) 1287 | fmt.Printf("%+v\n", t) 1288 | fmt.Printf("%#v\n", t) 1289 | fmt.Printf("%#v\n", timeZone) 1290 | \end{Verbatim} 1291 | 1292 | prints 1293 | 1294 | \begin{Verbatim}[frame=single] 1295 | &{7 -2.35 abc def} 1296 | &{a:7 b:-2.35 c:abc def} 1297 | &main.T{a:7, b:-2.35, c:"abc\tdef"} 1298 | map[string] int{"CST":-21600, "PST":-28800, "EST":-18000, "UTC":0, "MST":-25200} 1299 | \end{Verbatim} 1300 | 1301 | (Note the ampersands.) That quoted string format is also available 1302 | through \texttt{\%q} when applied to a value of type \texttt{string} or 1303 | \texttt{{[}{]}byte}; the alternate format \texttt{\%\#q} will use 1304 | backquotes instead if possible. Also, \texttt{\%x} works on strings and 1305 | arrays of bytes as well as on integers, generating a long hexadecimal 1306 | string, and with a space in the format (\texttt{\%~x}) it puts spaces 1307 | between the bytes. 1308 | 1309 | Another handy format is \texttt{\%T}, which prints the \emph{type} of a 1310 | value. 1311 | 1312 | \begin{Verbatim}[frame=single] 1313 | fmt.Printf("%T\n", timeZone) 1314 | \end{Verbatim} 1315 | 1316 | prints 1317 | 1318 | \begin{Verbatim}[frame=single] 1319 | map[string] int 1320 | \end{Verbatim} 1321 | 1322 | If you want to control the default format for a custom type, all that's 1323 | required is to define a method with the signature 1324 | \texttt{String() string} on the type. For our simple type \texttt{T}, 1325 | that might look like this. 1326 | 1327 | \begin{Verbatim}[frame=single] 1328 | func (t *T) String() string { 1329 | return fmt.Sprintf("%d/%g/%q", t.a, t.b, t.c) 1330 | } 1331 | fmt.Printf("%v\n", t) 1332 | \end{Verbatim} 1333 | 1334 | to print in the format 1335 | 1336 | \begin{Verbatim}[frame=single] 1337 | 7/-2.35/"abc\tdef" 1338 | \end{Verbatim} 1339 | 1340 | (If you need to print \emph{values} of type \texttt{T} as well as 1341 | pointers to \texttt{T}, the receiver for \texttt{String} must be of 1342 | value type; this example used a pointer because that's more efficient 1343 | and idiomatic for struct types. See the section below on 1344 | pointers vs. value receivers for more information.) 1345 | 1346 | Our \texttt{String} method is able to call \texttt{Sprintf} because the 1347 | print routines are fully reentrant and can be used recursively. We can 1348 | even go one step further and pass a print routine's arguments directly 1349 | to another such routine. The signature of \texttt{Printf} uses the type 1350 | \texttt{...interface\{\}} for its final argument to specify that an 1351 | arbitrary number of parameters (of arbitrary type) can appear after the 1352 | format. 1353 | 1354 | \begin{Verbatim}[frame=single] 1355 | func Printf(format string, v ...interface{}) (n int, err error) { 1356 | \end{Verbatim} 1357 | 1358 | Within the function \texttt{Printf}, \texttt{v} acts like a variable of 1359 | type \texttt{{[}{]}interface\{\}} but if it is passed to another 1360 | variadic function, it acts like a regular list of arguments. Here is the 1361 | implementation of the function \texttt{log.Println} we used above. It 1362 | passes its arguments directly to \texttt{fmt.Sprintln} for the actual 1363 | formatting. 1364 | 1365 | \begin{Verbatim}[frame=single] 1366 | // Println prints to the standard logger in the manner of fmt.Println. 1367 | func Println(v ...interface{}) { 1368 | std.Output(2, fmt.Sprintln(v...)) // Output takes parameters (int, string) 1369 | } 1370 | \end{Verbatim} 1371 | 1372 | We write \texttt{...} after \texttt{v} in the nested call to 1373 | \texttt{Sprintln} to tell the compiler to treat \texttt{v} as a list of 1374 | arguments; otherwise it would just pass \texttt{v} as a single slice 1375 | argument. 1376 | 1377 | There's even more to printing than we've covered here. See the 1378 | \texttt{godoc} documentation for package \texttt{fmt} for the details. 1379 | 1380 | By the way, a \texttt{...} parameter can be of a specific type, for 1381 | instance \texttt{...int} for a min function that chooses the least of a 1382 | list of integers: 1383 | 1384 | \begin{Verbatim}[frame=single] 1385 | func Min(a ...int) int { 1386 | min := int(^uint(0) >> 1) // largest int 1387 | for _, i := range a { 1388 | if i < min { 1389 | min = i 1390 | } 1391 | } 1392 | return min 1393 | } 1394 | \end{Verbatim} 1395 | 1396 | \subsection*{Append} 1397 | 1398 | Now we have the missing piece we needed to explain the design of the 1399 | \texttt{append} built-in function. The signature of \texttt{append} is 1400 | different from our custom \texttt{Append} function above. Schematically, 1401 | it's like this: 1402 | 1403 | \begin{Verbatim}[frame=single] 1404 | func append(slice []T, elements...T) []T 1405 | \end{Verbatim} 1406 | 1407 | where \emph{T} is a placeholder for any given type. You can't actually 1408 | write a function in Go where the type \texttt{T} is determined by the 1409 | caller. That's why \texttt{append} is built in: it needs support from 1410 | the compiler. 1411 | 1412 | What \texttt{append} does is append the elements to the end of the slice 1413 | and return the result. The result needs to be returned because, as with 1414 | our hand-written \texttt{Append}, the underlying array may change. This 1415 | simple example 1416 | 1417 | \begin{Verbatim}[frame=single] 1418 | x := []int{1,2,3} 1419 | x = append(x, 4, 5, 6) 1420 | fmt.Println(x) 1421 | \end{Verbatim} 1422 | 1423 | prints \texttt{{[}1 2 3 4 5 6{]}}. So \texttt{append} works a little 1424 | like \texttt{Printf}, collecting an arbitrary number of arguments. 1425 | 1426 | But what if we wanted to do what our \texttt{Append} does and append a 1427 | slice to a slice? Easy: use \texttt{...} at the call site, just as we 1428 | did in the call to \texttt{Output} above. This snippet produces 1429 | identical output to the one above. 1430 | 1431 | \begin{Verbatim}[frame=single] 1432 | x := []int{1,2,3} 1433 | y := []int{4,5,6} 1434 | x = append(x, y...) 1435 | fmt.Println(x) 1436 | \end{Verbatim} 1437 | 1438 | Without that \texttt{...}, it wouldn't compile because the types would 1439 | be wrong; \texttt{y} is not of type \texttt{int}. 1440 | 1441 | \section*{Initialization} 1442 | 1443 | Although it doesn't look superficially very different from 1444 | initialization in C or C++, initialization in Go is more powerful. 1445 | Complex structures can be built during initialization and the ordering 1446 | issues between initialized objects in different packages are handled 1447 | correctly. 1448 | 1449 | \subsection*{Constants} 1450 | 1451 | Constants in Go are just that---constant. They are created at compile 1452 | time, even when defined as locals in functions, and can only be numbers, 1453 | strings or booleans. Because of the compile-time restriction, the 1454 | expressions that define them must be constant expressions, evaluatable 1455 | by the compiler. For instance, \texttt{1\textless{}\textless{}3} is a 1456 | constant expression, while \texttt{math.Sin(math.Pi/4)} is not because 1457 | the function call to \texttt{math.Sin} needs to happen at run time. 1458 | 1459 | In Go, enumerated constants are created using the \texttt{iota} 1460 | enumerator. Since \texttt{iota} can be part of an expression and 1461 | expressions can be implicitly repeated, it is easy to build intricate 1462 | sets of values. 1463 | 1464 | \{\{code ``/doc/progs/eff\_bytesize.go'' `/\^{}type ByteSize/` 1465 | `/\^{}\textbackslash{})/`\}\} 1466 | 1467 | The ability to attach a method such as \texttt{String} to a type makes 1468 | it possible for such values to format themselves automatically for 1469 | printing, even as part of a general type. 1470 | 1471 | \{\{code ``/doc/progs/eff\_bytesize.go'' `/\^{}func.*ByteSize.*String/` 1472 | `/\^{}\}/`\}\} 1473 | 1474 | The expression \texttt{YB} prints as \texttt{1.00YB}, while 1475 | \texttt{ByteSize(1e13)} prints as \texttt{9.09TB}. 1476 | 1477 | Note that it's fine to call \texttt{Sprintf} and friends in the 1478 | implementation of \texttt{String} methods, but beware of recurring into 1479 | the \texttt{String} method through the nested \texttt{Sprintf} call 1480 | using a string format (\texttt{\%s}, \texttt{\%q}, \texttt{\%v}, 1481 | \texttt{\%x} or \texttt{\%X}). The \texttt{ByteSize} implementation of 1482 | \texttt{String} is safe because it calls \texttt{Sprintf} with 1483 | \texttt{\%f}. 1484 | 1485 | \subsection*{Variables} 1486 | 1487 | Variables can be initialized just like constants but the initializer can 1488 | be a general expression computed at run time. 1489 | 1490 | \begin{Verbatim}[frame=single] 1491 | var ( 1492 | HOME = os.Getenv("HOME") 1493 | USER = os.Getenv("USER") 1494 | GOROOT = os.Getenv("GOROOT") 1495 | ) 1496 | \end{Verbatim} 1497 | 1498 | \subsection*{The init function} 1499 | 1500 | Finally, each source file can define its own niladic \texttt{init} 1501 | function to set up whatever state is required. (Actually each file can 1502 | have multiple \texttt{init} functions.) And finally means finally: 1503 | \texttt{init} is called after all the variable declarations in the 1504 | package have evaluated their initializers, and those are evaluated only 1505 | after all the imported packages have been initialized. 1506 | 1507 | Besides initializations that cannot be expressed as declarations, a 1508 | common use of \texttt{init} functions is to verify or repair correctness 1509 | of the program state before real execution begins. 1510 | 1511 | \begin{Verbatim}[frame=single] 1512 | func init() { 1513 | if USER == "" { 1514 | log.Fatal("$USER not set") 1515 | } 1516 | if HOME == "" { 1517 | HOME = "/usr/" + USER 1518 | } 1519 | if GOROOT == "" { 1520 | GOROOT = HOME + "/go" 1521 | } 1522 | // GOROOT may be overridden by --goroot flag on command line. 1523 | flag.StringVar(&GOROOT, "goroot", GOROOT, "Go root directory") 1524 | } 1525 | \end{Verbatim} 1526 | 1527 | \section*{Methods} 1528 | 1529 | \subsection*{Pointers vs. Values} 1530 | 1531 | Methods can be defined for any named type that is not a pointer or an 1532 | interface; the receiver does not have to be a struct. 1533 | 1534 | In the discussion of slices above, we wrote an \texttt{Append} function. 1535 | We can define it as a method on slices instead. To do this, we first 1536 | declare a named type to which we can bind the method, and then make the 1537 | receiver for the method a value of that type. 1538 | 1539 | \begin{Verbatim}[frame=single] 1540 | type ByteSlice []byte 1541 | 1542 | func (slice ByteSlice) Append(data []byte) []byte { 1543 | // Body exactly the same as above 1544 | } 1545 | \end{Verbatim} 1546 | 1547 | This still requires the method to return the updated slice. We can 1548 | eliminate that clumsiness by redefining the method to take a 1549 | \emph{pointer} to a \texttt{ByteSlice} as its receiver, so the method 1550 | can overwrite the caller's slice. 1551 | 1552 | \begin{Verbatim}[frame=single] 1553 | func (p *ByteSlice) Append(data []byte) { 1554 | slice := *p 1555 | // Body as above, without the return. 1556 | *p = slice 1557 | } 1558 | \end{Verbatim} 1559 | 1560 | In fact, we can do even better. If we modify our function so it looks 1561 | like a standard \texttt{Write} method, like this, 1562 | 1563 | \begin{Verbatim}[frame=single] 1564 | func (p *ByteSlice) Write(data []byte) (n int, err error) { 1565 | slice := *p 1566 | // Again as above. 1567 | *p = slice 1568 | return len(data), nil 1569 | } 1570 | \end{Verbatim} 1571 | 1572 | then the type \texttt{*ByteSlice} satisfies the standard interface 1573 | \texttt{io.Writer}, which is handy. For instance, we can print into one. 1574 | 1575 | \begin{Verbatim}[frame=single] 1576 | var b ByteSlice 1577 | fmt.Fprintf(&b, "This hour has %d days\n", 7) 1578 | \end{Verbatim} 1579 | 1580 | We pass the address of a \texttt{ByteSlice} because only 1581 | \texttt{*ByteSlice} satisfies \texttt{io.Writer}. The rule about 1582 | pointers vs. values for receivers is that value methods can be invoked 1583 | on pointers and values, but pointer methods can only be invoked on 1584 | pointers. This is because pointer methods can modify the receiver; 1585 | invoking them on a copy of the value would cause those modifications to 1586 | be discarded. 1587 | 1588 | By the way, the idea of using \texttt{Write} on a slice of bytes is 1589 | implemented by \texttt{bytes.Buffer}. 1590 | 1591 | \section*{Interfaces and other types} 1592 | 1593 | \subsection*{Interfaces} 1594 | 1595 | Interfaces in Go provide a way to specify the behavior of an object: if 1596 | something can do \emph{this}, then it can be used \emph{here}. We've 1597 | seen a couple of simple examples already; custom printers can be 1598 | implemented by a \texttt{String} method while \texttt{Fprintf} can 1599 | generate output to anything with a \texttt{Write} method. Interfaces 1600 | with only one or two methods are common in Go code, and are usually 1601 | given a name derived from the method, such as \texttt{io.Writer} for 1602 | something that implements \texttt{Write}. 1603 | 1604 | A type can implement multiple interfaces. For instance, a collection can 1605 | be sorted by the routines in package \texttt{sort} if it implements 1606 | \texttt{sort.Interface}, which contains \texttt{Len()}, 1607 | \texttt{Less(i, j int) bool}, and \texttt{Swap(i, j int)}, and it could 1608 | also have a custom formatter. In this contrived example 1609 | \texttt{Sequence} satisfies both. 1610 | 1611 | \{\{code ``/doc/progs/eff\_sequence.go'' `/\^{}type/` ``\$''\}\} 1612 | 1613 | \subsection*{Conversions} 1614 | 1615 | The \texttt{String} method of \texttt{Sequence} is recreating the work 1616 | that \texttt{Sprint} already does for slices. We can share the effort if 1617 | we convert the \texttt{Sequence} to a plain \texttt{{[}{]}int} before 1618 | calling \texttt{Sprint}. 1619 | 1620 | \begin{Verbatim}[frame=single] 1621 | func (s Sequence) String() string { 1622 | sort.Sort(s) 1623 | return fmt.Sprint([]int(s)) 1624 | } 1625 | \end{Verbatim} 1626 | 1627 | The conversion causes \texttt{s} to be treated as an ordinary slice and 1628 | therefore receive the default formatting. Without the conversion, 1629 | \texttt{Sprint} would find the \texttt{String} method of 1630 | \texttt{Sequence} and recur indefinitely. Because the two types 1631 | (\texttt{Sequence} and \texttt{{[}{]}int}) are the same if we ignore the 1632 | type name, it's legal to convert between them. The conversion doesn't 1633 | create a new value, it just temporarily acts as though the existing 1634 | value has a new type. (There are other legal conversions, such as from 1635 | integer to floating point, that do create a new value.) 1636 | 1637 | It's an idiom in Go programs to convert the type of an expression to 1638 | access a different set of methods. As an example, we could use the 1639 | existing type \texttt{sort.IntSlice} to reduce the entire example to 1640 | this: 1641 | 1642 | \begin{Verbatim}[frame=single] 1643 | type Sequence []int 1644 | 1645 | // Method for printing - sorts the elements before printing 1646 | func (s Sequence) String() string { 1647 | sort.IntSlice(s).Sort() 1648 | return fmt.Sprint([]int(s)) 1649 | } 1650 | \end{Verbatim} 1651 | 1652 | Now, instead of having \texttt{Sequence} implement multiple interfaces 1653 | (sorting and printing), we're using the ability of a data item to be 1654 | converted to multiple types (\texttt{Sequence}, \texttt{sort.IntSlice} 1655 | and \texttt{{[}{]}int}), each of which does some part of the job. That's 1656 | more unusual in practice but can be effective. 1657 | 1658 | \subsection*{Generality} 1659 | 1660 | If a type exists only to implement an interface and has no exported 1661 | methods beyond that interface, there is no need to export the type 1662 | itself. Exporting just the interface makes it clear that it's the 1663 | behavior that matters, not the implementation, and that other 1664 | implementations with different properties can mirror the behavior of the 1665 | original type. It also avoids the need to repeat the documentation on 1666 | every instance of a common method. 1667 | 1668 | In such cases, the constructor should return an interface value rather 1669 | than the implementing type. As an example, in the hash libraries both 1670 | \texttt{crc32.NewIEEE} and \texttt{adler32.New} return the interface 1671 | type \texttt{hash.Hash32}. Substituting the CRC-32 algorithm for 1672 | Adler-32 in a Go program requires only changing the constructor call; 1673 | the rest of the code is unaffected by the change of algorithm. 1674 | 1675 | A similar approach allows the streaming cipher algorithms in the various 1676 | \texttt{crypto} packages to be separated from the block ciphers they 1677 | chain together. The \texttt{Block} interface in the 1678 | \texttt{crypto/cipher} package specifies the behavior of a block cipher, 1679 | which provides encryption of a single block of data. Then, by analogy 1680 | with the \texttt{bufio} package, cipher packages that implement this 1681 | interface can be used to construct streaming ciphers, represented by the 1682 | \texttt{Stream} interface, without knowing the details of the block 1683 | encryption. 1684 | 1685 | The \texttt{crypto/cipher} interfaces look like this: 1686 | 1687 | \begin{Verbatim}[frame=single] 1688 | type Block interface { 1689 | BlockSize() int 1690 | Encrypt(src, dst []byte) 1691 | Decrypt(src, dst []byte) 1692 | } 1693 | 1694 | type Stream interface { 1695 | XORKeyStream(dst, src []byte) 1696 | } 1697 | \end{Verbatim} 1698 | 1699 | Here's the definition of the counter mode (CTR) stream, which turns a 1700 | block cipher into a streaming cipher; notice that the block cipher's 1701 | details are abstracted away: 1702 | 1703 | \begin{Verbatim}[frame=single] 1704 | // NewCTR returns a Stream that encrypts/decrypts using the given Block in 1705 | // counter mode. The length of iv must be the same as the Block's block size. 1706 | func NewCTR(block Block, iv []byte) Stream 1707 | \end{Verbatim} 1708 | 1709 | \texttt{NewCTR} applies not just to one specific encryption algorithm 1710 | and data source but to any implementation of the \texttt{Block} 1711 | interface and any \texttt{Stream}. Because they return interface values, 1712 | replacing CTR encryption with other encryption modes is a localized 1713 | change. The constructor calls must be edited, but because the 1714 | surrounding code must treat the result only as a \texttt{Stream}, it 1715 | won't notice the difference. 1716 | 1717 | \subsection*{Interfaces and methods} 1718 | 1719 | Since almost anything can have methods attached, almost anything can 1720 | satisfy an interface. One illustrative example is in the \texttt{http} 1721 | package, which defines the \texttt{Handler} interface. Any object that 1722 | implements \texttt{Handler} can serve HTTP requests. 1723 | 1724 | \begin{Verbatim}[frame=single] 1725 | type Handler interface { 1726 | ServeHTTP(ResponseWriter, *Request) 1727 | } 1728 | \end{Verbatim} 1729 | 1730 | \texttt{ResponseWriter} is itself an interface that provides access to 1731 | the methods needed to return the response to the client. Those methods 1732 | include the standard \texttt{Write} method, so an 1733 | \texttt{http.ResponseWriter} can be used wherever an \texttt{io.Writer} 1734 | can be used. \texttt{Request} is a struct containing a parsed 1735 | representation of the request from the client. 1736 | 1737 | For brevity, let's ignore POSTs and assume HTTP requests are always 1738 | GETs; that simplification does not affect the way the handlers are set 1739 | up. Here's a trivial but complete implementation of a handler to count 1740 | the number of times the page is visited. 1741 | 1742 | \begin{Verbatim}[frame=single] 1743 | // Simple counter server. 1744 | type Counter struct { 1745 | n int 1746 | } 1747 | 1748 | func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) { 1749 | ctr.n++ 1750 | fmt.Fprintf(w, "counter = %d\n", ctr.n) 1751 | } 1752 | \end{Verbatim} 1753 | 1754 | (Keeping with our theme, note how \texttt{Fprintf} can print to an 1755 | \texttt{http.ResponseWriter}.) For reference, here's how to attach such 1756 | a server to a node on the URL tree. 1757 | 1758 | \begin{Verbatim}[frame=single] 1759 | import "net/http" 1760 | ... 1761 | ctr := new(Counter) 1762 | http.Handle("/counter", ctr) 1763 | \end{Verbatim} 1764 | 1765 | But why make \texttt{Counter} a struct? An integer is all that's needed. 1766 | (The receiver needs to be a pointer so the increment is visible to the 1767 | caller.) 1768 | 1769 | \begin{Verbatim}[frame=single] 1770 | // Simpler counter server. 1771 | type Counter int 1772 | 1773 | func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) { 1774 | *ctr++ 1775 | fmt.Fprintf(w, "counter = %d\n", *ctr) 1776 | } 1777 | \end{Verbatim} 1778 | 1779 | What if your program has some internal state that needs to be notified 1780 | that a page has been visited? Tie a channel to the web page. 1781 | 1782 | \begin{Verbatim}[frame=single] 1783 | // A channel that sends a notification on each visit. 1784 | // (Probably want the channel to be buffered.) 1785 | type Chan chan *http.Request 1786 | 1787 | func (ch Chan) ServeHTTP(w http.ResponseWriter, req *http.Request) { 1788 | ch <- req 1789 | fmt.Fprint(w, "notification sent") 1790 | } 1791 | \end{Verbatim} 1792 | 1793 | Finally, let's say we wanted to present on \texttt{/args} the arguments 1794 | used when invoking the server binary. It's easy to write a function to 1795 | print the arguments. 1796 | 1797 | \begin{Verbatim}[frame=single] 1798 | func ArgServer() { 1799 | for _, s := range os.Args { 1800 | fmt.Println(s) 1801 | } 1802 | } 1803 | \end{Verbatim} 1804 | 1805 | How do we turn that into an HTTP server? We could make 1806 | \texttt{ArgServer} a method of some type whose value we ignore, but 1807 | there's a cleaner way. Since we can define a method for any type except 1808 | pointers and interfaces, we can write a method for a function. The 1809 | \texttt{http} package contains this code: 1810 | 1811 | \begin{Verbatim}[frame=single] 1812 | // The HandlerFunc type is an adapter to allow the use of 1813 | // ordinary functions as HTTP handlers. If f is a function 1814 | // with the appropriate signature, HandlerFunc(f) is a 1815 | // Handler object that calls f. 1816 | type HandlerFunc func(ResponseWriter, *Request) 1817 | 1818 | // ServeHTTP calls f(c, req). 1819 | func (f HandlerFunc) ServeHTTP(w ResponseWriter, req *Request) { 1820 | f(w, req) 1821 | } 1822 | \end{Verbatim} 1823 | 1824 | \texttt{HandlerFunc} is a type with a method, \texttt{ServeHTTP}, so 1825 | values of that type can serve HTTP requests. Look at the implementation 1826 | of the method: the receiver is a function, \texttt{f}, and the method 1827 | calls \texttt{f}. That may seem odd but it's not that different from, 1828 | say, the receiver being a channel and the method sending on the channel. 1829 | 1830 | To make \texttt{ArgServer} into an HTTP server, we first modify it to 1831 | have the right signature. 1832 | 1833 | \begin{Verbatim}[frame=single] 1834 | // Argument server. 1835 | func ArgServer(w http.ResponseWriter, req *http.Request) { 1836 | for _, s := range os.Args { 1837 | fmt.Fprintln(w, s) 1838 | } 1839 | } 1840 | \end{Verbatim} 1841 | 1842 | \texttt{ArgServer} now has same signature as \texttt{HandlerFunc}, so it 1843 | can be converted to that type to access its methods, just as we 1844 | converted \texttt{Sequence} to \texttt{IntSlice} to access 1845 | \texttt{IntSlice.Sort}. The code to set it up is concise: 1846 | 1847 | \begin{Verbatim}[frame=single] 1848 | http.Handle("/args", http.HandlerFunc(ArgServer)) 1849 | \end{Verbatim} 1850 | 1851 | When someone visits the page \texttt{/args}, the handler installed at 1852 | that page has value \texttt{ArgServer} and type \texttt{HandlerFunc}. 1853 | The HTTP server will invoke the method \texttt{ServeHTTP} of that type, 1854 | with \texttt{ArgServer} as the receiver, which will in turn call 1855 | \texttt{ArgServer} (via the invocation \texttt{f(c, req)} inside 1856 | \texttt{HandlerFunc.ServeHTTP}). The arguments will then be displayed. 1857 | 1858 | In this section we have made an HTTP server from a struct, an integer, a 1859 | channel, and a function, all because interfaces are just sets of 1860 | methods, which can be defined for (almost) any type. 1861 | 1862 | \section*{Embedding} 1863 | 1864 | Go does not provide the typical, type-driven notion of subclassing, but 1865 | it does have the ability to ``borrow'' pieces of an implementation by 1866 | \emph{embedding} types within a struct or interface. 1867 | 1868 | Interface embedding is very simple. We've mentioned the 1869 | \texttt{io.Reader} and \texttt{io.Writer} interfaces before; here are 1870 | their definitions. 1871 | 1872 | \begin{Verbatim}[frame=single] 1873 | type Reader interface { 1874 | Read(p []byte) (n int, err error) 1875 | } 1876 | 1877 | type Writer interface { 1878 | Write(p []byte) (n int, err error) 1879 | } 1880 | \end{Verbatim} 1881 | 1882 | The \texttt{io} package also exports several other interfaces that 1883 | specify objects that can implement several such methods. For instance, 1884 | there is \texttt{io.ReadWriter}, an interface containing both 1885 | \texttt{Read} and \texttt{Write}. We could specify 1886 | \texttt{io.ReadWriter} by listing the two methods explicitly, but it's 1887 | easier and more evocative to embed the two interfaces to form the new 1888 | one, like this: 1889 | 1890 | \begin{Verbatim}[frame=single] 1891 | // ReadWriter is the interface that combines the Reader and Writer interfaces. 1892 | type ReadWriter interface { 1893 | Reader 1894 | Writer 1895 | } 1896 | \end{Verbatim} 1897 | 1898 | This says just what it looks like: A \texttt{ReadWriter} can do what a 1899 | \texttt{Reader} does \emph{and} what a \texttt{Writer} does; it is a 1900 | union of the embedded interfaces (which must be disjoint sets of 1901 | methods). Only interfaces can be embedded within interfaces. 1902 | 1903 | The same basic idea applies to structs, but with more far-reaching 1904 | implications. The \texttt{bufio} package has two struct types, 1905 | \texttt{bufio.Reader} and \texttt{bufio.Writer}, each of which of course 1906 | implements the analogous interfaces from package \texttt{io}. And 1907 | \texttt{bufio} also implements a buffered reader/writer, which it does 1908 | by combining a reader and a writer into one struct using embedding: it 1909 | lists the types within the struct but does not give them field names. 1910 | 1911 | \begin{Verbatim}[frame=single] 1912 | // ReadWriter stores pointers to a Reader and a Writer. 1913 | // It implements io.ReadWriter. 1914 | type ReadWriter struct { 1915 | *Reader // *bufio.Reader 1916 | *Writer // *bufio.Writer 1917 | } 1918 | \end{Verbatim} 1919 | 1920 | The embedded elements are pointers to structs and of course must be 1921 | initialized to point to valid structs before they can be used. The 1922 | \texttt{ReadWriter} struct could be written as 1923 | 1924 | \begin{Verbatim}[frame=single] 1925 | type ReadWriter struct { 1926 | reader *Reader 1927 | writer *Writer 1928 | } 1929 | \end{Verbatim} 1930 | 1931 | but then to promote the methods of the fields and to satisfy the 1932 | \texttt{io} interfaces, we would also need to provide forwarding 1933 | methods, like this: 1934 | 1935 | \begin{Verbatim}[frame=single] 1936 | func (rw *ReadWriter) Read(p []byte) (n int, err error) { 1937 | return rw.reader.Read(p) 1938 | } 1939 | \end{Verbatim} 1940 | 1941 | By embedding the structs directly, we avoid this bookkeeping. The 1942 | methods of embedded types come along for free, which means that 1943 | \texttt{bufio.ReadWriter} not only has the methods of 1944 | \texttt{bufio.Reader} and \texttt{bufio.Writer}, it also satisfies all 1945 | three interfaces: \texttt{io.Reader}, \texttt{io.Writer}, and 1946 | \texttt{io.ReadWriter}. 1947 | 1948 | There's an important way in which embedding differs from subclassing. 1949 | When we embed a type, the methods of that type become methods of the 1950 | outer type, but when they are invoked the receiver of the method is the 1951 | inner type, not the outer one. In our example, when the \texttt{Read} 1952 | method of a \texttt{bufio.ReadWriter} is invoked, it has exactly the 1953 | same effect as the forwarding method written out above; the receiver is 1954 | the \texttt{reader} field of the \texttt{ReadWriter}, not the 1955 | \texttt{ReadWriter} itself. 1956 | 1957 | Embedding can also be a simple convenience. This example shows an 1958 | embedded field alongside a regular, named field. 1959 | 1960 | \begin{Verbatim}[frame=single] 1961 | type Job struct { 1962 | Command string 1963 | *log.Logger 1964 | } 1965 | \end{Verbatim} 1966 | 1967 | The \texttt{Job} type now has the \texttt{Log}, \texttt{Logf} and other 1968 | methods of \texttt{*log.Logger}. We could have given the \texttt{Logger} 1969 | a field name, of course, but it's not necessary to do so. And now, once 1970 | initialized, we can log to the \texttt{Job}: 1971 | 1972 | \begin{Verbatim}[frame=single] 1973 | job.Log("starting now...") 1974 | \end{Verbatim} 1975 | 1976 | The \texttt{Logger} is a regular field of the struct and we can 1977 | initialize it in the usual way with a constructor, 1978 | 1979 | \begin{Verbatim}[frame=single] 1980 | func NewJob(command string, logger *log.Logger) *Job { 1981 | return &Job{command, logger} 1982 | } 1983 | \end{Verbatim} 1984 | 1985 | or with a composite literal, 1986 | 1987 | \begin{Verbatim}[frame=single] 1988 | job := &Job{command, log.New(os.Stderr, "Job: ", log.Ldate)} 1989 | \end{Verbatim} 1990 | 1991 | If we need to refer to an embedded field directly, the type name of the 1992 | field, ignoring the package qualifier, serves as a field name. If we 1993 | needed to access the \texttt{*log.Logger} of a \texttt{Job} variable 1994 | \texttt{job}, we would write \texttt{job.Logger}. This would be useful 1995 | if we wanted to refine the methods of \texttt{Logger}. 1996 | 1997 | \begin{Verbatim}[frame=single] 1998 | func (job *Job) Logf(format string, args ...interface{}) { 1999 | job.Logger.Logf("%q: %s", job.Command, fmt.Sprintf(format, args...)) 2000 | } 2001 | \end{Verbatim} 2002 | 2003 | Embedding types introduces the problem of name conflicts but the rules 2004 | to resolve them are simple. First, a field or method \texttt{X} hides 2005 | any other item \texttt{X} in a more deeply nested part of the type. If 2006 | \texttt{log.Logger} contained a field or method called \texttt{Command}, 2007 | the \texttt{Command} field of \texttt{Job} would dominate it. 2008 | 2009 | Second, if the same name appears at the same nesting level, it is 2010 | usually an error; it would be erroneous to embed \texttt{log.Logger} if 2011 | the \texttt{Job} struct contained another field or method called 2012 | \texttt{Logger}. However, if the duplicate name is never mentioned in 2013 | the program outside the type definition, it is OK. This qualification 2014 | provides some protection against changes made to types embedded from 2015 | outside; there is no problem if a field is added that conflicts with 2016 | another field in another subtype if neither field is ever used. 2017 | 2018 | \section*{Concurrency} 2019 | 2020 | \subsection*{Share by communicating} 2021 | 2022 | Concurrent programming is a large topic and there is space only for some 2023 | Go-specific highlights here. 2024 | 2025 | Concurrent programming in many environments is made difficult by the 2026 | subtleties required to implement correct access to shared variables. Go 2027 | encourages a different approach in which shared values are passed around 2028 | on channels and, in fact, never actively shared by separate threads of 2029 | execution. Only one goroutine has access to the value at any given time. 2030 | Data races cannot occur, by design. To encourage this way of thinking we 2031 | have reduced it to a slogan: 2032 | 2033 | \begin{quote} 2034 | Do not communicate by sharing memory; instead, share memory by 2035 | communicating. 2036 | \end{quote} 2037 | 2038 | This approach can be taken too far. Reference counts may be best done by 2039 | putting a mutex around an integer variable, for instance. But as a 2040 | high-level approach, using channels to control access makes it easier to 2041 | write clear, correct programs. 2042 | 2043 | One way to think about this model is to consider a typical 2044 | single-threaded program running on one CPU. It has no need for 2045 | synchronization primitives. Now run another such instance; it too needs 2046 | no synchronization. Now let those two communicate; if the communication 2047 | is the synchronizer, there's still no need for other synchronization. 2048 | Unix pipelines, for example, fit this model perfectly. Although Go's 2049 | approach to concurrency originates in Hoare's Communicating Sequential 2050 | Processes (CSP), it can also be seen as a type-safe generalization of 2051 | Unix pipes. 2052 | 2053 | \subsection*{Goroutines} 2054 | 2055 | They're called \emph{goroutines} because the existing terms---threads, 2056 | coroutines, processes, and so on---convey inaccurate connotations. A 2057 | goroutine has a simple model: it is a function executing concurrently 2058 | with other goroutines in the same address space. It is lightweight, 2059 | costing little more than the allocation of stack space. And the stacks 2060 | start small, so they are cheap, and grow by allocating (and freeing) 2061 | heap storage as required. 2062 | 2063 | Goroutines are multiplexed onto multiple OS threads so if one should 2064 | block, such as while waiting for I/O, others continue to run. Their 2065 | design hides many of the complexities of thread creation and management. 2066 | 2067 | Prefix a function or method call with the \texttt{go} keyword to run the 2068 | call in a new goroutine. When the call completes, the goroutine exits, 2069 | silently. (The effect is similar to the Unix shell's \texttt{\&} 2070 | notation for running a command in the background.) 2071 | 2072 | \begin{Verbatim}[frame=single] 2073 | go list.Sort() // run list.Sort concurrently; don't wait for it. 2074 | \end{Verbatim} 2075 | 2076 | A function literal can be handy in a goroutine invocation. 2077 | 2078 | \begin{Verbatim}[frame=single] 2079 | func Announce(message string, delay time.Duration) { 2080 | go func() { 2081 | time.Sleep(delay) 2082 | fmt.Println(message) 2083 | }() // Note the parentheses - must call the function. 2084 | } 2085 | \end{Verbatim} 2086 | 2087 | In Go, function literals are closures: the implementation makes sure the 2088 | variables referred to by the function survive as long as they are 2089 | active. 2090 | 2091 | These examples aren't too practical because the functions have no way of 2092 | signaling completion. For that, we need channels. 2093 | 2094 | \subsection*{Channels} 2095 | 2096 | Like maps, channels are a reference type and are allocated with 2097 | \texttt{make}. If an optional integer parameter is provided, it sets the 2098 | buffer size for the channel. The default is zero, for an unbuffered or 2099 | synchronous channel. 2100 | 2101 | \begin{Verbatim}[frame=single] 2102 | ci := make(chan int) // unbuffered channel of integers 2103 | cj := make(chan int, 0) // unbuffered channel of integers 2104 | cs := make(chan *os.File, 100) // buffered channel of pointers to Files 2105 | \end{Verbatim} 2106 | 2107 | Channels combine communication---the exchange of a value---with 2108 | synchronization---guaranteeing that two calculations (goroutines) are in 2109 | a known state. 2110 | 2111 | There are lots of nice idioms using channels. Here's one to get us 2112 | started. In the previous section we launched a sort in the background. A 2113 | channel can allow the launching goroutine to wait for the sort to 2114 | complete. 2115 | 2116 | \begin{Verbatim}[frame=single] 2117 | c := make(chan int) // Allocate a channel. 2118 | // Start the sort in a goroutine; when it completes, signal on the channel. 2119 | go func() { 2120 | list.Sort() 2121 | c <- 1 // Send a signal; value does not matter. 2122 | }() 2123 | doSomethingForAWhile() 2124 | <-c // Wait for sort to finish; discard sent value. 2125 | \end{Verbatim} 2126 | 2127 | Receivers always block until there is data to receive. If the channel is 2128 | unbuffered, the sender blocks until the receiver has received the value. 2129 | If the channel has a buffer, the sender blocks only until the value has 2130 | been copied to the buffer; if the buffer is full, this means waiting 2131 | until some receiver has retrieved a value. 2132 | 2133 | A buffered channel can be used like a semaphore, for instance to limit 2134 | throughput. In this example, incoming requests are passed to 2135 | \texttt{handle}, which sends a value into the channel, processes the 2136 | request, and then receives a value from the channel. The capacity of the 2137 | channel buffer limits the number of simultaneous calls to 2138 | \texttt{process}. 2139 | 2140 | \begin{Verbatim}[frame=single] 2141 | var sem = make(chan int, MaxOutstanding) 2142 | 2143 | func handle(r *Request) { 2144 | sem <- 1 // Wait for active queue to drain. 2145 | process(r) // May take a long time. 2146 | <-sem // Done; enable next request to run. 2147 | } 2148 | 2149 | func Serve(queue chan *Request) { 2150 | for { 2151 | req := <-queue 2152 | go handle(req) // Don't wait for handle to finish. 2153 | } 2154 | } 2155 | \end{Verbatim} 2156 | 2157 | Here's the same idea implemented by starting a fixed number of 2158 | \texttt{handle} goroutines all reading from the request channel. The 2159 | number of goroutines limits the number of simultaneous calls to 2160 | \texttt{process}. This \texttt{Serve} function also accepts a channel on 2161 | which it will be told to exit; after launching the goroutines it blocks 2162 | receiving from that channel. 2163 | 2164 | \begin{Verbatim}[frame=single] 2165 | func handle(queue chan *Request) { 2166 | for r := range queue { 2167 | process(r) 2168 | } 2169 | } 2170 | 2171 | func Serve(clientRequests chan *Request, quit chan bool) { 2172 | // Start handlers 2173 | for i := 0; i < MaxOutstanding; i++ { 2174 | go handle(clientRequests) 2175 | } 2176 | <-quit // Wait to be told to exit. 2177 | } 2178 | \end{Verbatim} 2179 | 2180 | \subsection*{Channels of channels} 2181 | 2182 | One of the most important properties of Go is that a channel is a 2183 | first-class value that can be allocated and passed around like any 2184 | other. A common use of this property is to implement safe, parallel 2185 | demultiplexing. 2186 | 2187 | In the example in the previous section, \texttt{handle} was an idealized 2188 | handler for a request but we didn't define the type it was handling. If 2189 | that type includes a channel on which to reply, each client can provide 2190 | its own path for the answer. Here's a schematic definition of type 2191 | \texttt{Request}. 2192 | 2193 | \begin{Verbatim}[frame=single] 2194 | type Request struct { 2195 | args []int 2196 | f func([]int) int 2197 | resultChan chan int 2198 | } 2199 | \end{Verbatim} 2200 | 2201 | The client provides a function and its arguments, as well as a channel 2202 | inside the request object on which to receive the answer. 2203 | 2204 | \begin{Verbatim}[frame=single] 2205 | func sum(a []int) (s int) { 2206 | for _, v := range a { 2207 | s += v 2208 | } 2209 | return 2210 | } 2211 | 2212 | request := &Request{[]int{3, 4, 5}, sum, make(chan int)} 2213 | // Send request 2214 | clientRequests <- request 2215 | // Wait for response. 2216 | fmt.Printf("answer: %d\n", <-request.resultChan) 2217 | \end{Verbatim} 2218 | 2219 | On the server side, the handler function is the only thing that changes. 2220 | 2221 | \begin{Verbatim}[frame=single] 2222 | func handle(queue chan *Request) { 2223 | for req := range queue { 2224 | req.resultChan <- req.f(req.args) 2225 | } 2226 | } 2227 | \end{Verbatim} 2228 | 2229 | There's clearly a lot more to do to make it realistic, but this code is 2230 | a framework for a rate-limited, parallel, non-blocking RPC system, and 2231 | there's not a mutex in sight. 2232 | 2233 | \subsection*{Parallelization} 2234 | 2235 | Another application of these ideas is to parallelize a calculation 2236 | across multiple CPU cores. If the calculation can be broken into 2237 | separate pieces that can execute independently, it can be parallelized, 2238 | with a channel to signal when each piece completes. 2239 | 2240 | Let's say we have an expensive operation to perform on a vector of 2241 | items, and that the value of the operation on each item is independent, 2242 | as in this idealized example. 2243 | 2244 | \begin{Verbatim}[frame=single] 2245 | type Vector []float64 2246 | 2247 | // Apply the operation to v[i], v[i+1] ... up to v[n-1]. 2248 | func (v Vector) DoSome(i, n int, u Vector, c chan int) { 2249 | for ; i < n; i++ { 2250 | v[i] += u.Op(v[i]) 2251 | } 2252 | c <- 1 // signal that this piece is done 2253 | } 2254 | \end{Verbatim} 2255 | 2256 | We launch the pieces independently in a loop, one per CPU. They can 2257 | complete in any order but it doesn't matter; we just count the 2258 | completion signals by draining the channel after launching all the 2259 | goroutines. 2260 | 2261 | \begin{Verbatim}[frame=single] 2262 | const NCPU = 4 // number of CPU cores 2263 | 2264 | func (v Vector) DoAll(u Vector) { 2265 | c := make(chan int, NCPU) // Buffering optional but sensible. 2266 | for i := 0; i < NCPU; i++ { 2267 | go v.DoSome(i*len(v)/NCPU, (i+1)*len(v)/NCPU, u, c) 2268 | } 2269 | // Drain the channel. 2270 | for i := 0; i < NCPU; i++ { 2271 | <-c // wait for one task to complete 2272 | } 2273 | // All done. 2274 | } 2275 | \end{Verbatim} 2276 | 2277 | The current implementation of the Go runtime will not parallelize this 2278 | code by default. It dedicates only a single core to user-level 2279 | processing. An arbitrary number of goroutines can be blocked in system 2280 | calls, but by default only one can be executing user-level code at any 2281 | time. It should be smarter and one day it will be smarter, but until it 2282 | is if you want CPU parallelism you must tell the run-time how many 2283 | goroutines you want executing code simultaneously. There are two related 2284 | ways to do this. Either run your job with environment variable 2285 | \texttt{GOMAXPROCS} set to the number of cores to use or import the 2286 | \texttt{runtime} package and call \texttt{runtime.GOMAXPROCS(NCPU)}. A 2287 | helpful value might be \texttt{runtime.NumCPU()}, which reports the 2288 | number of logical CPUs on the local machine. Again, this requirement is 2289 | expected to be retired as the scheduling and run-time improve. 2290 | 2291 | \subsection*{A leaky buffer} 2292 | 2293 | The tools of concurrent programming can even make non-concurrent ideas 2294 | easier to express. Here's an example abstracted from an RPC package. The 2295 | client goroutine loops receiving data from some source, perhaps a 2296 | network. To avoid allocating and freeing buffers, it keeps a free list, 2297 | and uses a buffered channel to represent it. If the channel is empty, a 2298 | new buffer gets allocated. Once the message buffer is ready, it's sent 2299 | to the server on \texttt{serverChan}. 2300 | 2301 | \begin{Verbatim}[frame=single] 2302 | var freeList = make(chan *Buffer, 100) 2303 | var serverChan = make(chan *Buffer) 2304 | 2305 | func client() { 2306 | for { 2307 | var b *Buffer 2308 | // Grab a buffer if available; allocate if not. 2309 | select { 2310 | case b = <-freeList: 2311 | // Got one; nothing more to do. 2312 | default: 2313 | // None free, so allocate a new one. 2314 | b = new(Buffer) 2315 | } 2316 | load(b) // Read next message from the net. 2317 | serverChan <- b // Send to server. 2318 | } 2319 | } 2320 | \end{Verbatim} 2321 | 2322 | The server loop receives each message from the client, processes it, and 2323 | returns the buffer to the free list. 2324 | 2325 | \begin{Verbatim}[frame=single] 2326 | func server() { 2327 | for { 2328 | b := <-serverChan // Wait for work. 2329 | process(b) 2330 | // Reuse buffer if there's room. 2331 | select { 2332 | case freeList <- b: 2333 | // Buffer on free list; nothing more to do. 2334 | default: 2335 | // Free list full, just carry on. 2336 | } 2337 | } 2338 | } 2339 | \end{Verbatim} 2340 | 2341 | The client attempts to retrieve a buffer from \texttt{freeList}; if none 2342 | is available, it allocates a fresh one. The server's send to 2343 | \texttt{freeList} puts \texttt{b} back on the free list unless the list 2344 | is full, in which case the buffer is dropped on the floor to be 2345 | reclaimed by the garbage collector. (The \texttt{default} clauses in the 2346 | \texttt{select} statements execute when no other case is ready, meaning 2347 | that the \texttt{selects} never block.) This implementation builds a 2348 | leaky bucket free list in just a few lines, relying on the buffered 2349 | channel and the garbage collector for bookkeeping. 2350 | 2351 | \section*{Errors} 2352 | 2353 | Library routines must often return some sort of error indication to the 2354 | caller. As mentioned earlier, Go's multivalue return makes it easy to 2355 | return a detailed error description alongside the normal return value. 2356 | By convention, errors have type \texttt{error}, a simple built-in 2357 | interface. 2358 | 2359 | \begin{Verbatim}[frame=single] 2360 | type error interface { 2361 | Error() string 2362 | } 2363 | \end{Verbatim} 2364 | 2365 | A library writer is free to implement this interface with a richer model 2366 | under the covers, making it possible not only to see the error but also 2367 | to provide some context. For example, \texttt{os.Open} returns an 2368 | \texttt{os.PathError}. 2369 | 2370 | \begin{Verbatim}[frame=single] 2371 | // PathError records an error and the operation and 2372 | // file path that caused it. 2373 | type PathError struct { 2374 | Op string // "open", "unlink", etc. 2375 | Path string // The associated file. 2376 | Err error // Returned by the system call. 2377 | } 2378 | 2379 | func (e *PathError) Error() string { 2380 | return e.Op + " " + e.Path + ": " + e.Err.Error() 2381 | } 2382 | \end{Verbatim} 2383 | 2384 | \texttt{PathError}'s \texttt{Error} generates a string like this: 2385 | 2386 | \begin{Verbatim}[frame=single] 2387 | open /etc/passwx: no such file or directory 2388 | \end{Verbatim} 2389 | 2390 | Such an error, which includes the problematic file name, the operation, 2391 | and the operating system error it triggered, is useful even if printed 2392 | far from the call that caused it; it is much more informative than the 2393 | plain ``no such file or directory''. 2394 | 2395 | When feasible, error strings should identify their origin, such as by 2396 | having a prefix naming the package that generated the error. For 2397 | example, in package \texttt{image}, the string representation for a 2398 | decoding error due to an unknown format is ``image: unknown format''. 2399 | 2400 | Callers that care about the precise error details can use a type switch 2401 | or a type assertion to look for specific errors and extract details. For 2402 | \texttt{PathErrors} this might include examining the internal 2403 | \texttt{Err} field for recoverable failures. 2404 | 2405 | \begin{Verbatim}[frame=single] 2406 | for try := 0; try < 2; try++ { 2407 | file, err = os.Create(filename) 2408 | if err == nil { 2409 | return 2410 | } 2411 | if e, ok := err.(*os.PathError); ok && e.Err == syscall.ENOSPC { 2412 | deleteTempFiles() // Recover some space. 2413 | continue 2414 | } 2415 | return 2416 | } 2417 | \end{Verbatim} 2418 | 2419 | The second \texttt{if} statement here is idiomatic Go. The type 2420 | assertion \texttt{err.(*os.PathError)} is checked with the ``comma 2421 | ok'' idiom (mentioned earlier in the context of examining maps). 2422 | If the type assertion fails, \texttt{ok} will be false, and \texttt{e} 2423 | will be \texttt{nil}. If it succeeds, \texttt{ok} will be true, 2424 | which means the error was of type \texttt{*os.PathError}, and then 2425 | so is \texttt{e}, which we can examine for more information about 2426 | the error. 2427 | 2428 | \subsection*{Panic} 2429 | 2430 | The usual way to report an error to a caller is to return an 2431 | \texttt{error} as an extra return value. The canonical \texttt{Read} 2432 | method is a well-known instance; it returns a byte count and an 2433 | \texttt{error}. But what if the error is unrecoverable? Sometimes the 2434 | program simply cannot continue. 2435 | 2436 | For this purpose, there is a built-in function \texttt{panic} that in 2437 | effect creates a run-time error that will stop the program (but see the 2438 | next section). The function takes a single argument of arbitrary 2439 | type---often a string---to be printed as the program dies. It's also a 2440 | way to indicate that something impossible has happened, such as exiting 2441 | an infinite loop. In fact, the compiler recognizes a \texttt{panic} at 2442 | the end of a function and suppresses the usual check for a 2443 | \texttt{return} statement. 2444 | 2445 | \begin{Verbatim}[frame=single] 2446 | // A toy implementation of cube root using Newton's method. 2447 | func CubeRoot(x float64) float64 { 2448 | z := x/3 // Arbitrary initial value 2449 | for i := 0; i < 1e6; i++ { 2450 | prevz := z 2451 | z -= (z*z*z-x) / (3*z*z) 2452 | if veryClose(z, prevz) { 2453 | return z 2454 | } 2455 | } 2456 | // A million iterations has not converged; something is wrong. 2457 | panic(fmt.Sprintf("CubeRoot(%g) did not converge", x)) 2458 | } 2459 | \end{Verbatim} 2460 | 2461 | This is only an example but real library functions should avoid 2462 | \texttt{panic}. If the problem can be masked or worked around, it's 2463 | always better to let things continue to run rather than taking down the 2464 | whole program. One possible counterexample is during initialization: if 2465 | the library truly cannot set itself up, it might be reasonable to panic, 2466 | so to speak. 2467 | 2468 | \begin{Verbatim}[frame=single] 2469 | var user = os.Getenv("USER") 2470 | 2471 | func init() { 2472 | if user == "" { 2473 | panic("no value for $USER") 2474 | } 2475 | } 2476 | \end{Verbatim} 2477 | 2478 | \subsection*{Recover} 2479 | 2480 | When \texttt{panic} is called, including implicitly for run-time errors 2481 | such as indexing an array out of bounds or failing a type assertion, it 2482 | immediately stops execution of the current function and begins unwinding 2483 | the stack of the goroutine, running any deferred functions along the 2484 | way. If that unwinding reaches the top of the goroutine's stack, the 2485 | program dies. However, it is possible to use the built-in function 2486 | \texttt{recover} to regain control of the goroutine and resume normal 2487 | execution. 2488 | 2489 | A call to \texttt{recover} stops the unwinding and returns the argument 2490 | passed to \texttt{panic}. Because the only code that runs while 2491 | unwinding is inside deferred functions, \texttt{recover} is only useful 2492 | inside deferred functions. 2493 | 2494 | One application of \texttt{recover} is to shut down a failing goroutine 2495 | inside a server without killing the other executing goroutines. 2496 | 2497 | \begin{Verbatim}[frame=single] 2498 | func server(workChan <-chan *Work) { 2499 | for work := range workChan { 2500 | go safelyDo(work) 2501 | } 2502 | } 2503 | 2504 | func safelyDo(work *Work) { 2505 | defer func() { 2506 | if err := recover(); err != nil { 2507 | log.Println("work failed:", err) 2508 | } 2509 | }() 2510 | do(work) 2511 | } 2512 | \end{Verbatim} 2513 | 2514 | In this example, if \texttt{do(work)} panics, the result will be logged 2515 | and the goroutine will exit cleanly without disturbing the others. 2516 | There's no need to do anything else in the deferred closure; calling 2517 | \texttt{recover} handles the condition completely. 2518 | 2519 | Because \texttt{recover} always returns \texttt{nil} unless called 2520 | directly from a deferred function, deferred code can call library 2521 | routines that themselves use \texttt{panic} and \texttt{recover} without 2522 | failing. As an example, the deferred function in \texttt{safelyDo} might 2523 | call a logging function before calling \texttt{recover}, and that 2524 | logging code would run unaffected by the panicking state. 2525 | 2526 | With our recovery pattern in place, the \texttt{do} function (and 2527 | anything it calls) can get out of any bad situation cleanly by calling 2528 | \texttt{panic}. We can use that idea to simplify error handling in 2529 | complex software. Let's look at an idealized excerpt from the 2530 | \texttt{regexp} package, which reports parsing errors by calling 2531 | \texttt{panic} with a local error type. Here's the definition of 2532 | \texttt{Error}, an \texttt{error} method, and the \texttt{Compile} 2533 | function. 2534 | 2535 | \begin{Verbatim}[frame=single] 2536 | // Error is the type of a parse error; it satisfies the error interface. 2537 | type Error string 2538 | func (e Error) Error() string { 2539 | return string(e) 2540 | } 2541 | 2542 | // error is a method of *Regexp that reports parsing errors by 2543 | // panicking with an Error. 2544 | func (regexp *Regexp) error(err string) { 2545 | panic(Error(err)) 2546 | } 2547 | 2548 | // Compile returns a parsed representation of the regular expression. 2549 | func Compile(str string) (regexp *Regexp, err error) { 2550 | regexp = new(Regexp) 2551 | // doParse will panic if there is a parse error. 2552 | defer func() { 2553 | if e := recover(); e != nil { 2554 | regexp = nil // Clear return value. 2555 | err = e.(Error) // Will re-panic if not a parse error. 2556 | } 2557 | }() 2558 | return regexp.doParse(str), nil 2559 | } 2560 | \end{Verbatim} 2561 | 2562 | If \texttt{doParse} panics, the recovery block will set the return value 2563 | to \texttt{nil}---deferred functions can modify named return values. It 2564 | then will then check, in the assignment to \texttt{err}, that the 2565 | problem was a parse error by asserting that it has the local type 2566 | \texttt{Error}. If it does not, the type assertion will fail, causing a 2567 | run-time error that continues the stack unwinding as though nothing had 2568 | interrupted it. This check means that if something unexpected happens, 2569 | such as an array index out of bounds, the code will fail even though we 2570 | are using \texttt{panic} and \texttt{recover} to handle user-triggered 2571 | errors. 2572 | 2573 | With error handling in place, the \texttt{error} method makes it easy to 2574 | report parse errors without worrying about unwinding the parse stack by 2575 | hand. 2576 | 2577 | Useful though this pattern is, it should be used only within a package. 2578 | \texttt{Parse} turns its internal \texttt{panic} calls into 2579 | \texttt{error} values; it does not expose \texttt{panics} to its client. 2580 | That is a good rule to follow. 2581 | 2582 | By the way, this re-panic idiom changes the panic value if an actual 2583 | error occurs. However, both the original and new failures will be 2584 | presented in the crash report, so the root cause of the problem will 2585 | still be visible. Thus this simple re-panic approach is usually 2586 | sufficient---it's a crash after all---but if you want to display only 2587 | the original value, you can write a little more code to filter 2588 | unexpected problems and re-panic with the original error. That's left as 2589 | an exercise for the reader. 2590 | 2591 | \section*{A web server} 2592 | 2593 | Let's finish with a complete Go program, a web server. This one is 2594 | actually a kind of web re-server. Google provides a service at 2595 | \href{http://chart.apis.google.com}{http://chart.apis.google.com} that 2596 | does automatic formatting of data into charts and graphs. It's hard to 2597 | use interactively, though, because you need to put the data into the URL 2598 | as a query. The program here provides a nicer interface to one form of 2599 | data: given a short piece of text, it calls on the chart server to 2600 | produce a QR code, a matrix of boxes that encode the text. That image 2601 | can be grabbed with your cell phone's camera and interpreted as, for 2602 | instance, a URL, saving you typing the URL into the phone's tiny 2603 | keyboard. 2604 | 2605 | Here's the complete program. An explanation follows. 2606 | 2607 | \{\{code ``/doc/progs/eff\_qr.go''\}\} 2608 | 2609 | The pieces up to \texttt{main} should be easy to follow. The one flag 2610 | sets a default HTTP port for our server. The template variable 2611 | \texttt{templ} is where the fun happens. It builds an HTML template that 2612 | will be executed by the server to display the page; more about that in a 2613 | moment. 2614 | 2615 | The \texttt{main} function parses the flags and, using the mechanism we 2616 | talked about above, binds the function \texttt{QR} to the root path for 2617 | the server. Then \texttt{http.ListenAndServe} is called to start the 2618 | server; it blocks while the server runs. 2619 | 2620 | \texttt{QR} just receives the request, which contains form data, and 2621 | executes the template on the data in the form value named \texttt{s}. 2622 | 2623 | The template package \texttt{html/template} is powerful; this program 2624 | just touches on its capabilities. In essence, it rewrites a piece of 2625 | HTML text on the fly by substituting elements derived from data items 2626 | passed to \texttt{templ.Execute}, in this case the form value. Within 2627 | the template text (\texttt{templateStr}), double-brace-delimited pieces 2628 | denote template actions. The piece from 2629 | \texttt{\{\{html "\{\{if .\}\}"\}\}} to 2630 | \texttt{\{\{html "\{\{end\}\}"\}\}} executes only if the value of the 2631 | current data item, called \texttt{.} (dot), is non-empty. That is, when 2632 | the string is empty, this piece of the template is suppressed. 2633 | 2634 | The two snippets \texttt{\{\{html "\{\{.\}\}"\}\}} say to show the data 2635 | presented to the template---the query string---on the web page. The HTML 2636 | template package automatically provides appropriate escaping so the text 2637 | is safe to display. 2638 | 2639 | The rest of the template string is just the HTML to show when the page 2640 | loads. If this is too quick an explanation, see the 2641 | \href{/pkg/html/template/}{documentation} for the template package for a 2642 | more thorough discussion. 2643 | 2644 | And there you have it: a useful web server in a few lines of code plus 2645 | some data-driven HTML text. Go is powerful enough to make a lot happen 2646 | in a few lines. 2647 | --------------------------------------------------------------------------------