content: wrap long lines using new program wrap.go
Wrapping long lines will make diffs easier to read
for the eventual conversion to Markdown.
For golang/go#33955.
Change-Id: Ibcc1b5a84ccc9144b5fcdc9266f2da3e2cf3c5a3
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222839
Reviewed-by: Ian Lance Taylor <iant@golang.org>
diff --git a/content/4years.article b/content/4years.article
index d6d2cad..4122617 100644
--- a/content/4years.article
+++ b/content/4years.article
@@ -28,47 +28,131 @@
But where is the interest coming from?
-The open source community has embraced Go, with our community wiki listing [[https://golang.org/wiki/Projects][hundreds of Go projects]]. Some popular ones:
+The open source community has embraced Go,
+with our community wiki listing [[https://golang.org/wiki/Projects][hundreds of Go projects]]. Some popular ones:
-- [[http://docker.io][Docker]] is a tool for packaging and running applications in lightweight containers. Docker makes it easy to isolate, package, and deploy applications, and is beloved by system administrators. Its creator Solomon Hykes cited Go's standard library, concurrency primitives, and ease of deployment as key factors, and said "To put it simply, if Docker had not been written in Go, it would not have been as successful."
+- [[http://docker.io][Docker]] is a tool for packaging and running applications
+ in lightweight containers.
+ Docker makes it easy to isolate, package,
+ and deploy applications, and is beloved by system administrators.
+ Its creator Solomon Hykes cited Go's standard library,
+ concurrency primitives, and ease of deployment as key factors,
+ and said "To put it simply, if Docker had not been written in Go,
+ it would not have been as successful."
-- [[http://packer.io][Packer]] is a tool for automating the creation of machine images for deployment to virtual machines or cloud services. Its author, Mitchell Hashimoto, is now working on another Go project, [[http://www.serfdom.io/][serf]], a decentralized discovery service. Like Docker, these projects help with management of large-scale, cluster-based services.
+- [[http://packer.io][Packer]] is a tool for automating the creation of
+ machine images for deployment to virtual machines or cloud services.
+ Its author, Mitchell Hashimoto, is now working on another Go project,
+ [[http://www.serfdom.io/][serf]], a decentralized discovery service.
+ Like Docker, these projects help with management of large-scale,
+ cluster-based services.
-- [[http://bit.ly][Bitly]]'s [[http://bitly.github.io/nsq/][NSQ]] is a realtime distributed messaging platform designed for fault-tolerance and high-availability, and is used in production at bitly and a bunch of other companies.
+- [[http://bit.ly][Bitly]]'s [[http://bitly.github.io/nsq/][NSQ]] is a realtime
+ distributed messaging platform designed for fault-tolerance and high-availability,
+ and is used in production at bitly and a bunch of other companies.
-- [[http://canonical.com/][Canonical]]'s [[https://juju.ubuntu.com/][JuJu]] infrastructure automation system was rewritten in Go. Project lead Gustavo Niemeyer said "It's not a single aspect of Go that makes it a compelling choice, but rather the careful organization of well-crafted small pieces."
+- [[http://canonical.com/][Canonical]]'s [[https://juju.ubuntu.com/][JuJu]]
+ infrastructure automation system was rewritten in Go.
+ Project lead Gustavo Niemeyer said "It's not a single aspect of Go that
+ makes it a compelling choice,
+ but rather the careful organization of well-crafted small pieces."
-- The [[https://github.com/goraft/raft][raft]] package provides an implementation of the [[https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf][Raft]] distributed consensus protocol. It is the basis of Go projects like [[https://github.com/coreos/etcd][etcd]] and [[https://github.com/skynetservices/skydns][SkyDNS]].
+- The [[https://github.com/goraft/raft][raft]] package provides an implementation
+ of the [[https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf][Raft]]
+ distributed consensus protocol.
+ It is the basis of Go projects like [[https://github.com/coreos/etcd][etcd]]
+ and [[https://github.com/skynetservices/skydns][SkyDNS]].
-- Other popular projects include [[https://github.com/biogo/biogo][biogo]], the [[http://www.gorillatoolkit.org/][Gorilla Web Toolkit]], [[https://github.com/golang/groupcache][groupcache]], Mozilla's [[https://github.com/mozilla-services/heka][heka]], the [[https://github.com/cznic/kv][kv]] and [[https://github.com/cznic/ql][ql]] lightweight storage systems, and the [[http://skydb.io/][Sky]] behavioral database.
+- Other popular projects include [[https://github.com/biogo/biogo][biogo]],
+ the [[http://www.gorillatoolkit.org/][Gorilla Web Toolkit]],
+ [[https://github.com/golang/groupcache][groupcache]],
+ Mozilla's [[https://github.com/mozilla-services/heka][heka]],
+ the [[https://github.com/cznic/kv][kv]] and [[https://github.com/cznic/ql][ql]]
+ lightweight storage systems,
+ and the [[http://skydb.io/][Sky]] behavioral database.
-But this is just the tip of the iceberg. The number of high-quality open source Go projects is phenomenal. Prolific Go hacker [[http://xph.us/software/][Keith Rarick]] put it well: "The state of the Go ecosystem after only four years is astounding. Compare Go in 2013 to Python in 1995 or Java in 1999. Or C++ in 1987!"
+But this is just the tip of the iceberg. The number of high-quality open
+source Go projects is phenomenal.
+Prolific Go hacker [[http://xph.us/software/][Keith Rarick]] put it well:
+"The state of the Go ecosystem after only four years is astounding.
+Compare Go in 2013 to Python in 1995 or Java in 1999. Or C++ in 1987!"
-Businesses are enjoying Go, too. The [[https://golang.org/wiki/GoUsers][Go Users wiki page]] lists dozens of success stories (and if you use Go, please add yourself to it). Some examples:
+Businesses are enjoying Go, too. The [[https://golang.org/wiki/GoUsers][Go Users wiki page]]
+lists dozens of success stories (and if you use Go,
+please add yourself to it). Some examples:
-- [[https://blog.cloudflare.com/go-at-cloudflare][CloudFlare]] built their distributed DNS service entirely with Go, and are in the process of migrating their gigabytes-per-minute logging infrastructure to the language. Programmer John Graham-Cumming said "We've found Go to be the perfect match for our needs: the combination of familiar syntax, a powerful type system, a strong network library and built-in concurrency means that more and more projects are being built here in Go."
+- [[https://blog.cloudflare.com/go-at-cloudflare][CloudFlare]] built their
+ distributed DNS service entirely with Go,
+ and are in the process of migrating their gigabytes-per-minute logging infrastructure to the language.
+ Programmer John Graham-Cumming said "We've found Go to be the perfect match for our needs:
+ the combination of familiar syntax, a powerful type system,
+ a strong network library and built-in concurrency means that more and more
+ projects are being built here in Go."
-- [[http://soundcloud.com][SoundCloud]] is an audio distribution service that has "dozens of [[http://backstage.soundcloud.com/2012/07/go-at-soundcloud/][systems in Go]], touching almost every part of the site, and in many cases powering features from top to bottom." Engineer Peter Bourgon said "Go demonstrates that the cruft that burdens other languages and ecosystems—stuff that developers have learned to deal with, often in anger—is simply not a necessary part of modern programming. With Go, I have a straightforward and non-adversarial relationship with my tools, from development to production."
+- [[http://soundcloud.com][SoundCloud]] is an audio distribution service
+ that has "dozens of [[http://backstage.soundcloud.com/2012/07/go-at-soundcloud/][systems in Go]],
+ touching almost every part of the site, and in many cases powering features
+ from top to bottom." Engineer Peter Bourgon said "Go demonstrates that the
+ cruft that burdens other languages and ecosystems—stuff that developers
+ have learned to deal with,
+ often in anger—is simply not a necessary part of modern programming.
+ With Go, I have a straightforward and non-adversarial relationship with my tools,
+ from development to production."
-- The [[https://ngrok.com/][ngrok]] service allows web developers to provide remote access to their development environments. Its author Alan Shreve said that "ngrok's success as a project is due in no small part to choosing Go as the implementation language," citing Go's HTTP libraries, efficiency, cross-platform compatibility, and ease of deployment as the major benefits.
+- The [[https://ngrok.com/][ngrok]] service allows web developers to provide
+ remote access to their development environments.
+ Its author Alan Shreve said that "ngrok's success as a project is due in
+ no small part to choosing Go as the implementation language," citing Go's HTTP libraries,
+ efficiency, cross-platform compatibility,
+ and ease of deployment as the major benefits.
-- [[http://poptip.com][Poptip]] provides social analytics services, and product engineer Andy Bonventre said "What started as an experiment in writing a single service in Go turned into moving almost our entire infrastructure over to it. What I love about Go the most is not necessarily the features of the language, but the focus on tooling, testing, and other elements that make writing large applications much more manageable."
+- [[http://poptip.com][Poptip]] provides social analytics services,
+ and product engineer Andy Bonventre said "What started as an experiment
+ in writing a single service in Go turned into moving almost our entire infrastructure over to it.
+ What I love about Go the most is not necessarily the features of the language,
+ but the focus on tooling, testing, and other elements that make writing
+ large applications much more manageable."
-- Music collaboration startup [[http://splice.com][Splice]] chose to build their service with Go. Co-founder Matt Aimonetti said "We seriously studied and considered many programming languages, but Go's simplicity, efficiency, philosophy and community won us over."
+- Music collaboration startup [[http://splice.com][Splice]] chose to build
+ their service with Go.
+ Co-founder Matt Aimonetti said "We seriously studied and considered many
+ programming languages,
+ but Go's simplicity, efficiency, philosophy and community won us over."
-- And, of course, engineering teams across Google are moving to Go. Engineer Matt Welsh recently [[http://matt-welsh.blogspot.com.au/2013/08/rewriting-large-production-system-in-go.html][shared his experience]] rewriting a large production service in Go. Other notable public examples include YouTube's [[https://github.com/youtube/vitess][vitess project]] and [[https://talks.golang.org/2013/oscon-dl.slide][dl.google.com]]. We hope to share more stories like these soon.
+- And, of course, engineering teams across Google are moving to Go.
+ Engineer Matt Welsh recently [[http://matt-welsh.blogspot.com.au/2013/08/rewriting-large-production-system-in-go.html][shared his experience]]
+ rewriting a large production service in Go.
+ Other notable public examples include YouTube's [[https://github.com/youtube/vitess][vitess project]]
+ and [[https://talks.golang.org/2013/oscon-dl.slide][dl.google.com]].
+ We hope to share more stories like these soon.
-In September 2012, [[http://apcera.com/][Apcera]] CEO Derek Collison [[https://twitter.com/derekcollison/status/245522124666716160][predicted]] that "Go will become the dominant language for systems work in [Infastructure-as-a-Service], Orchestration, and [Platform-as-a-Service] in 24 months." Looking at the list above, it's easy to believe that prediction.
+In September 2012, [[http://apcera.com/][Apcera]] CEO Derek Collison [[https://twitter.com/derekcollison/status/245522124666716160][predicted]]
+that "Go will become the dominant language for systems work in [Infastructure-as-a-Service],
+Orchestration, and [Platform-as-a-Service] in 24 months." Looking at the list above,
+it's easy to believe that prediction.
-So how can you get involved? Whether you're a seasoned Go programmer or just Go-curious, there are many ways to get started in the Go community:
+So how can you get involved? Whether you're a seasoned Go programmer or just Go-curious,
+there are many ways to get started in the Go community:
-- [[https://blog.golang.org/getthee-to-go-meetup][Join your nearest Go User Group]], where your local gophers meet to share their knowledge and experience. These groups are popping up all over the world. I have personally spoken at Go groups in Amsterdam, Berlin, Gothenburg, London, Moscow, Munich, New York City, Paris, San Francisco, Seoul, Stockholm, Sydney, Tokyo, and Warsaw; but there are [[https://golang.org/wiki/GoUserGroups][many more]]!
+- [[https://blog.golang.org/getthee-to-go-meetup][Join your nearest Go User Group]],
+ where your local gophers meet to share their knowledge and experience.
+ These groups are popping up all over the world.
+ I have personally spoken at Go groups in Amsterdam,
+ Berlin, Gothenburg, London, Moscow, Munich,
+ New York City, Paris, San Francisco, Seoul,
+ Stockholm, Sydney, Tokyo, and Warsaw;
+ but there are [[https://golang.org/wiki/GoUserGroups][many more]]!
-- Create or contribute to an open source Go project (or [[https://golang.org/doc/contribute.html][to Go itself]]). (And if you're building something, we'd love to hear from you on the [[http://groups.google.com/group/golang-nuts][Go mailing list]].)
+- Create or contribute to an open source Go project (or [[https://golang.org/doc/contribute.html][to Go itself]]).
+ (And if you're building something, we'd love to hear from you on the [[http://groups.google.com/group/golang-nuts][Go mailing list]].)
-- If you're in Europe in February 2014, come along to the [[https://code.google.com/p/go-wiki/wiki/Fosdem2014][Go Devroom]] at [[https://fosdem.org/2014/][FOSDEM 2014]].
+- If you're in Europe in February 2014, come along to the [[https://code.google.com/p/go-wiki/wiki/Fosdem2014][Go Devroom]]
+ at [[https://fosdem.org/2014/][FOSDEM 2014]].
-- Attend [[http://gophercon.com][GopherCon]], the first major Go conference, in Denver in April 2014. The event is organized by the [[http://www.gopheracademy.com][Gopher Academy]], who also run a [[http://www.gopheracademy.com/jobs][Go job board]].
+- Attend [[http://gophercon.com][GopherCon]],
+ the first major Go conference, in Denver in April 2014.
+ The event is organized by the [[http://www.gopheracademy.com][Gopher Academy]],
+ who also run a [[http://www.gopheracademy.com/jobs][Go job board]].
The Go team has been amazed by the growth of the Go community over the past
four years. We are thrilled to see so many great things being built with Go,
diff --git a/content/8years.article b/content/8years.article
index 4af0fd6..78876ca 100644
--- a/content/8years.article
+++ b/content/8years.article
@@ -71,7 +71,8 @@
Go Bridge and Women Who Go.
This year we had two significant firsts for the Go project. We had our first
-[[https://blog.golang.org/contributors-summit][contributor summit]] where people from across the Go community came together to
+[[https://blog.golang.org/contributors-summit][contributor summit]] where
+people from across the Go community came together to
discuss the needs and future of the Go project. Shortly after, we had the
first [[https://blog.golang.org/contributor-workshop][Go contributor workshop]]
where hundreds of people came to make their first Go contribution.
@@ -87,23 +88,47 @@
thousands of additional applications and libraries at [[https://github.com/avelino/awesome-go][awesome-go]]. Here are
just a handful of the most popular:
-- [[https://mobyproject.org/][Moby]] (formerly Docker) is a tool for packaging and running applications in lightweight containers. Its creator Solomon Hykes cited Go's standard library, concurrency primitives, and ease of deployment as key factors, and said "To put it simply, if Docker had not been written in Go, it would not have been as successful."
+- [[https://mobyproject.org/][Moby]] (formerly Docker) is a tool for packaging
+ and running applications in lightweight containers.
+ Its creator Solomon Hykes cited Go's standard library,
+ concurrency primitives, and ease of deployment as key factors,
+ and said "To put it simply, if Docker had not been written in Go,
+ it would not have been as successful."
-- [[https://kubernetes.io/][Kubernetes]] is a system for automating deployment, scaling and management of containerized applications. Initially designed by Google and used in the Google cloud, Kubernetes now is a critical part of every major cloud offering.
+- [[https://kubernetes.io/][Kubernetes]] is a system for automating deployment,
+ scaling and management of containerized applications.
+ Initially designed by Google and used in the Google cloud,
+ Kubernetes now is a critical part of every major cloud offering.
-- [[https://gohugo.io/][Hugo]] is now the most popular open-source static website engine. With its amazing speed and flexibility, Hugo makes building websites fun again. According to [[https://w3techs.com/technologies/overview/content_management/all][w3techs]], Hugo now has nearly 3x the usage of Jekyll, the former leader.
+- [[https://gohugo.io/][Hugo]] is now the most popular open-source static website engine.
+ With its amazing speed and flexibility, Hugo makes building websites fun again.
+ According to [[https://w3techs.com/technologies/overview/content_management/all][w3techs]],
+ Hugo now has nearly 3x the usage of Jekyll, the former leader.
-- [[https://prometheus.io/][Prometheus]] is an open source monitoring solution and time series database that powers metrics and alerting designed to be the system you go to during an outage to allow you to quickly diagnose problems.
+- [[https://prometheus.io/][Prometheus]] is an open source monitoring solution
+ and time series database that powers metrics and alerting designed to be
+ the system you go to during an outage to allow you to quickly diagnose problems.
-- [[https://grafana.com/][Grafana]] is an open source, feature-rich metrics dashboard and graph editor for Graphite, Elasticsearch, OpenTSDB, Prometheus and InfluxDB.
+- [[https://grafana.com/][Grafana]] is an open source,
+ feature-rich metrics dashboard and graph editor for Graphite,
+ Elasticsearch, OpenTSDB, Prometheus and InfluxDB.
- [[https://getlantern.org/][Lantern]] delivers fast, reliable and secure access to blocked websites and apps.
-- [[https://syncthing.net/][Syncthing]] is an open-source cross platform peer-to-peer continuous file synchronization application
+- [[https://syncthing.net/][Syncthing]] is an open-source cross platform
+ peer-to-peer continuous file synchronization application
-- [[https://keybase.io/][Keybase]] is a new and free security app for mobile phones and computers. Think of it as an open source Dropbox & Slack with end-to-end encryption public-key cryptography.
+- [[https://keybase.io/][Keybase]] is a new and free security app for mobile
+ phones and computers.
+ Think of it as an open source Dropbox & Slack with end-to-end encryption
+ public-key cryptography.
-- [[https://github.com/junegunn/fzf][Fzf]] is an interactive Unix filter for command-line that can be used with any list; files, command history, processes, hostnames, bookmarks, git commits, etc. Fzf supports Unix, macOS and has beta support for Windows. It also can operate as a vim plugin.
+- [[https://github.com/junegunn/fzf][Fzf]] is an interactive Unix filter
+ for command-line that can be used with any list;
+ files, command history, processes, hostnames,
+ bookmarks, git commits, etc.
+ Fzf supports Unix, macOS and has beta support for Windows.
+ It also can operate as a vim plugin.
Many of these authors have said that their projects would not exist without
Go. Some like Kubernetes and Docker created entirely new solutions. Others
diff --git a/content/a-new-go-api-for-protocol-buffers.article b/content/a-new-go-api-for-protocol-buffers.article
index 9e8d6eb..5230db7 100644
--- a/content/a-new-go-api-for-protocol-buffers.article
+++ b/content/a-new-go-api-for-protocol-buffers.article
@@ -207,11 +207,20 @@
- `github.com/golang/protobuf@v1.3.4` is the most recent pre-APIv2 version of APIv1.
-- `github.com/golang/protobuf@v1.4.0` is a version of APIv1 implemented in terms of APIv2. The API is the same, but the underlying implementation is backed by the new one. This version contains functions to convert between the APIv1 and APIv2 `proto.Message` interfaces to ease the transition between the two.
+- `github.com/golang/protobuf@v1.4.0` is a version of APIv1 implemented in terms of APIv2.
+ The API is the same, but the underlying implementation is backed by the new one.
+ This version contains functions to convert between the APIv1 and APIv2 `proto.Message`
+ interfaces to ease the transition between the two.
-- `google.golang.org/protobuf@v1.20.0` is APIv2. This module depends upon `github.com/golang/protobuf@v1.4.0`, so any program which uses APIv2 will automatically pick a version of APIv1 which integrates with it.
+- `google.golang.org/protobuf@v1.20.0` is APIv2.
+ This module depends upon `github.com/golang/protobuf@v1.4.0`,
+ so any program which uses APIv2 will automatically pick a version of APIv1
+ which integrates with it.
-(Why start at version `v1.20.0`? To provide clarity. We do not anticipate APIv1 to ever reach `v1.20.0`, so the version number alone should be enough to unambiguously differentiate between APIv1 and APIv2.)
+(Why start at version `v1.20.0`? To provide clarity.
+We do not anticipate APIv1 to ever reach `v1.20.0`,
+so the version number alone should be enough to unambiguously differentiate
+between APIv1 and APIv2.)
We intend to maintain support for APIv1 indefinitely.
diff --git a/content/advanced-go-concurrency-patterns.article b/content/advanced-go-concurrency-patterns.article
index 10970f2..c3f1eab 100644
--- a/content/advanced-go-concurrency-patterns.article
+++ b/content/advanced-go-concurrency-patterns.article
@@ -6,10 +6,21 @@
* Introduction
-At Google I/O a year ago Rob Pike presented [[https://talks.golang.org/2012/concurrency.slide][_Go_Concurrency_Patterns_]], an introduction to Go's concurrency model. Last week, at I/O 2013, Go team member Sameer Ajmani continued the story with [[http://talks.golang.org/2013/advconc.slide][_Advanced_Go_Concurrency_Patterns_]], an in-depth look at a real concurrent programming problem. The talk shows how to detect and avoid deadlocks and race conditions, and demonstrates the implementation of deadlines, cancellation, and more. For those who want to take their Go programming to the next level, this is a must-see.
+At Google I/O a year ago Rob Pike presented [[https://talks.golang.org/2012/concurrency.slide][_Go_Concurrency_Patterns_]],
+an introduction to Go's concurrency model.
+Last week, at I/O 2013, Go team member Sameer Ajmani continued the story
+with [[http://talks.golang.org/2013/advconc.slide][_Advanced_Go_Concurrency_Patterns_]],
+an in-depth look at a real concurrent programming problem.
+The talk shows how to detect and avoid deadlocks and race conditions,
+and demonstrates the implementation of deadlines,
+cancellation, and more.
+For those who want to take their Go programming to the next level, this is a must-see.
.iframe //www.youtube.com/embed/QDDwwePbDtw?rel=0 309 549
-The slides are [[https://talks.golang.org/2013/advconc.slide][available here]] (use the left and right arrows to navigate).
+The slides are [[https://talks.golang.org/2013/advconc.slide][available here]]
+(use the left and right arrows to navigate).
-The slides were produced with [[https://godoc.org/golang.org/x/tools/present][the present tool]], and the runnable code snippets are powered by the [[http://play.golang.org/][Go Playground]]. The source code for this talk is in [[https://github.com/golang/talks/tree/master/content/2013/advconc][the go.talks sub-repository]].
+The slides were produced with [[https://godoc.org/golang.org/x/tools/present][the present tool]],
+and the runnable code snippets are powered by the [[http://play.golang.org/][Go Playground]].
+The source code for this talk is in [[https://github.com/golang/talks/tree/master/content/2013/advconc][the go.talks sub-repository]].
diff --git a/content/building-stathat-with-go.article b/content/building-stathat-with-go.article
index 81479ec..ccf3daa 100644
--- a/content/building-stathat-with-go.article
+++ b/content/building-stathat-with-go.article
@@ -6,11 +6,24 @@
* Introduction
-My name is Patrick Crosby and I'm the founder of a company called Numerotron. We recently released [[http://www.stathat.com][StatHat]]. This post is about why we chose to develop StatHat in [[https://golang.org][Go]], including details about how we are using Go.
+My name is Patrick Crosby and I'm the founder of a company called Numerotron.
+We recently released [[http://www.stathat.com][StatHat]].
+This post is about why we chose to develop StatHat in [[https://golang.org][Go]],
+including details about how we are using Go.
-[[http://www.stathat.com][StatHat]] is a tool to track statistics and events in your code. Everyone from HTML designers to backend engineers can use StatHat easily, as it supports sending stats from HTML, JavaScript, Go, and twelve other languages.
+[[http://www.stathat.com][StatHat]] is a tool to track statistics and events in your code.
+Everyone from HTML designers to backend engineers can use StatHat easily,
+as it supports sending stats from HTML, JavaScript,
+Go, and twelve other languages.
-You send your numbers to StatHat; it generates beautiful, fully-embeddable graphs of your data. StatHat will alert you when specified triggers occur, send you daily email reports, and much more. So instead of spending time writing tracking or reporting tools for your application, you can concentrate on the code. While you do the real work, StatHat remains intensely vigilant, like an eagle in its mountaintop nest, or a babysitter on meth.
+You send your numbers to StatHat; it generates beautiful,
+fully-embeddable graphs of your data.
+StatHat will alert you when specified triggers occur,
+send you daily email reports, and much more.
+So instead of spending time writing tracking or reporting tools for your application,
+you can concentrate on the code.
+While you do the real work, StatHat remains intensely vigilant,
+like an eagle in its mountaintop nest, or a babysitter on meth.
Here's an example of a StatHat graph of the temperature in NYC, Chicago, and San Francisco:
@@ -18,11 +31,30 @@
* Architecture Overview
-StatHat consists of two main services: incoming statistic/event API calls and the web application for viewing and analyzing stats. We wanted to keep these as separate as possible to isolate the data collection from the data interaction. We did this for many reasons, but one major reason is that we anticipate handling a ton of automated incoming API HTTP requests and would thus have different optimization strategies for the API service than a web application interacting with humans.
+StatHat consists of two main services: incoming statistic/event API calls
+and the web application for viewing and analyzing stats.
+We wanted to keep these as separate as possible to isolate the data collection
+from the data interaction.
+We did this for many reasons, but one major reason is that we anticipate
+handling a ton of automated incoming API HTTP requests and would thus have
+different optimization strategies for the API service than a web application
+interacting with humans.
.image building-stathat-with-go_stathat_architecture.png
-The web application service is multi-tiered. The web server processes all requests and sends them to an interactor layer. For simple tasks, the interactor will handle generating any necessary data. For complex tasks, the interactor relies on multiple application servers to handle tasks like generating graphs or analyzing data sets. After the interactor is finished, the web server sends the result to a presenter. The presenter responds to the HTTP request with either HTML or JSON. We can horizontally scale the web, API, application servers, and databases as the demand for services grows and changes over time. There is no single point of failure as each application server has multiple copies running. The interactor layer allows us to have different interfaces to the system: http, command line, automated tests, mobile API. StatHat uses MySQL for data storage.
+The web application service is multi-tiered.
+The web server processes all requests and sends them to an interactor layer.
+For simple tasks, the interactor will handle generating any necessary data.
+For complex tasks, the interactor relies on multiple application servers
+to handle tasks like generating graphs or analyzing data sets.
+After the interactor is finished, the web server sends the result to a presenter.
+The presenter responds to the HTTP request with either HTML or JSON.
+We can horizontally scale the web, API, application servers,
+and databases as the demand for services grows and changes over time.
+There is no single point of failure as each application server has multiple copies running.
+The interactor layer allows us to have different interfaces to the system:
+http, command line, automated tests, mobile API.
+StatHat uses MySQL for data storage.
* Choosing Go
@@ -48,43 +80,108 @@
We evaluated many popular and not-so-popular web technologies and ended up choosing to develop it in Go.
-When Go was released in November 2009, I immediately installed it and loved the fast compilation times, goroutines, channels, garbage collection, and all the packages that were available. I was especially pleased with how few lines of code my applications were using. I soon experimented with making a web app called [[http://langalot.com/][Langalot]] that concurrently searched through five foreign language dictionaries as you typed in a query. It was blazingly fast. I put it online and it's been running since February, 2010.
+When Go was released in November 2009, I immediately installed it and loved
+the fast compilation times,
+goroutines, channels, garbage collection,
+and all the packages that were available.
+I was especially pleased with how few lines of code my applications were using.
+I soon experimented with making a web app called [[http://langalot.com/][Langalot]]
+that concurrently searched through five foreign language dictionaries as
+you typed in a query.
+It was blazingly fast. I put it online and it's been running since February, 2010.
The following sections detail how Go meets StatHat's requirements and our experience using Go to solve our problems.
* Runtime
-We use the standard Go [[https://golang.org/pkg/http/][http package]] for our API and web app servers. All requests first go through Nginx and any non-file requests are proxied to the Go-powered http servers. The backend servers are all written in Go and use the [[https://golang.org/pkg/rpc/][rpc package]] to communicate with the frontend.
+We use the standard Go [[https://golang.org/pkg/http/][http package]] for
+our API and web app servers.
+All requests first go through Nginx and any non-file requests are proxied
+to the Go-powered http servers.
+The backend servers are all written in Go and use the [[https://golang.org/pkg/rpc/][rpc package]]
+to communicate with the frontend.
* Templating
-We built a template system using the standard [[https://golang.org/pkg/template/][template package]]. Our system adds layouts, some common formatting functions, and the ability to recompile templates on-the-fly during development. We are very pleased with the performance and functionality of the Go templates.
+We built a template system using the standard [[https://golang.org/pkg/template/][template package]].
+Our system adds layouts, some common formatting functions,
+and the ability to recompile templates on-the-fly during development.
+We are very pleased with the performance and functionality of the Go templates.
* Tinkering
-In a previous job, I worked on a video game called Throne of Darkness that was written in C++. We had a few header files that, when modified, required a full rebuild of the entire system, 20-30 minutes long. If anyone ever changed `Character.h`, he would be subject to the wrath of every other programmer. Besides this suffering, it also slowed down development time significantly.
+In a previous job, I worked on a video game called Throne of Darkness that was written in C++.
+We had a few header files that, when modified,
+required a full rebuild of the entire system, 20-30 minutes long.
+If anyone ever changed `Character.h`, he would be subject to the wrath of
+every other programmer.
+Besides this suffering, it also slowed down development time significantly.
-Since then, I've always tried to choose technologies that allowed fast, frequent tinkering. With Go, compilation time is a non-issue. We can recompile the entire system in seconds, not minutes. The development web server starts instantly, tests complete in a few seconds. As mentioned previously, templates are recompiled as they change. The result is that the StatHat system is very easy to work with, and the compiler is not a bottleneck.
+Since then, I've always tried to choose technologies that allowed fast, frequent tinkering.
+With Go, compilation time is a non-issue.
+We can recompile the entire system in seconds, not minutes.
+The development web server starts instantly,
+tests complete in a few seconds.
+As mentioned previously, templates are recompiled as they change.
+The result is that the StatHat system is very easy to work with,
+and the compiler is not a bottleneck.
* RPC
-Since StatHat is a multi-tiered system, we wanted an RPC layer so that all communication was standard. With Go, we are using the [[https://golang.org/pkg/rpc/][rpc package]] and the [[https://golang.org/pkg/gob/][gob package]] for encoding Go objects. In Go, the RPC server just takes any Go object and registers its exported methods. There is no need for an intermediary interface description language. We've found it very easy to use and many of our core application servers are under 300 lines of code.
+Since StatHat is a multi-tiered system, we wanted an RPC layer so that all
+communication was standard.
+With Go, we are using the [[https://golang.org/pkg/rpc/][rpc package]] and
+the [[https://golang.org/pkg/gob/][gob package]] for encoding Go objects.
+In Go, the RPC server just takes any Go object and registers its exported methods.
+There is no need for an intermediary interface description language.
+We've found it very easy to use and many of our core application servers
+are under 300 lines of code.
* Libraries
-We don't want to spend time rewriting libraries for things like SSL, database drivers, JSON/XML parsers. Although Go is a young language, it has a lot of system packages and a growing number of user-contributed packages. With only a few exceptions, we have found Go packages for everything we have needed.
+We don't want to spend time rewriting libraries for things like SSL,
+database drivers, JSON/XML parsers.
+Although Go is a young language, it has a lot of system packages and a growing
+number of user-contributed packages.
+With only a few exceptions, we have found Go packages for everything we have needed.
* Open source
-In our experience, it has been invaluable to work with open source tools. If something is going awry, it is immensely helpful to be able to examine the source through every layer and not have any black boxes. Having the code for the language, web server, packages, and tools allows us to understand how every piece of the system works. Everything in Go is open source. In the Go codebase, we frequently read the tests as they often give great examples of how to use packages and language features.
+In our experience, it has been invaluable to work with open source tools.
+If something is going awry, it is immensely helpful to be able to examine
+the source through every layer and not have any black boxes.
+Having the code for the language, web server,
+packages, and tools allows us to understand how every piece of the system works.
+Everything in Go is open source. In the Go codebase,
+we frequently read the tests as they often give great examples of how to
+use packages and language features.
* Performance
-People rely on StatHat for up to the minute analysis of their data and we need the system to be as responsive as possible. In our tests, Go's performance blew away most of the competition. We tested it against Rails, Sinatra, OpenResty, and Node. StatHat has always monitored itself by tracking all kinds of performance metrics about requests, the duration of certain tasks, the amount of memory in use. Because of this, we were able to easily evaluate different technologies. We've also taken advantage of the benchmark performance testing features of the Go testing package.
+People rely on StatHat for up to the minute analysis of their data and we
+need the system to be as responsive as possible.
+In our tests, Go's performance blew away most of the competition.
+We tested it against Rails, Sinatra, OpenResty, and Node.
+StatHat has always monitored itself by tracking all kinds of performance
+metrics about requests,
+the duration of certain tasks, the amount of memory in use.
+Because of this, we were able to easily evaluate different technologies.
+We've also taken advantage of the benchmark performance testing features
+of the Go testing package.
* Application-Level Concurrency
-In a former life, I was the CTO at OkCupid. My experience there using OKWS taught me the importance of async programming, especially when it comes to dynamic web applications. There is no reason you should ever do something like this synchronously: load a user from the database, then find their stats, then find their alerts. These should all be done concurrently, yet surprisingly, many popular frameworks have no async support. Go supports this at the language level without any callback spaghetti. StatHat uses goroutines extensively to run multiple functions concurrently and channels for sharing data between goroutines.
+In a former life, I was the CTO at OkCupid.
+My experience there using OKWS taught me the importance of async programming,
+especially when it comes to dynamic web applications.
+There is no reason you should ever do something like this synchronously:
+load a user from the database, then find their stats,
+then find their alerts.
+These should all be done concurrently, yet surprisingly,
+many popular frameworks have no async support.
+Go supports this at the language level without any callback spaghetti.
+StatHat uses goroutines extensively to run multiple functions concurrently
+and channels for sharing data between goroutines.
* Hosting and Deployment
@@ -98,12 +195,24 @@
- Database
-There are at least two of each type of server, and they are in different zones for high availability. Adding a new server to the mix takes just a couple of minutes.
+There are at least two of each type of server,
+and they are in different zones for high availability.
+Adding a new server to the mix takes just a couple of minutes.
-To deploy, we first build the entire system into a time-stamped directory. Our packaging script builds the Go applications, compresses the CSS and JS files, and copies all the scripts and configuration files. This directory is then distributed to all the servers, so they all have an identical distribution. A script on each server queries its EC2 tags and determines what it is responsible for running and starts/stops/restarts any services. We frequently only deploy to a subset of the servers.
+To deploy, we first build the entire system into a time-stamped directory.
+Our packaging script builds the Go applications,
+compresses the CSS and JS files, and copies all the scripts and configuration files.
+This directory is then distributed to all the servers,
+so they all have an identical distribution.
+A script on each server queries its EC2 tags and determines what it is responsible
+for running and starts/stops/restarts any services.
+We frequently only deploy to a subset of the servers.
* More
-For more information on StatHat, please visit [[http://www.stathat.com][stathat.com]]. We are releasing some of the Go code we've written. Go to [[http://www.stathat.com/src][www.stathat.com/src]] for all of the open source StatHat projects.
+For more information on StatHat, please visit [[http://www.stathat.com][stathat.com]].
+We are releasing some of the Go code we've written.
+Go to [[http://www.stathat.com/src][www.stathat.com/src]] for all of the
+open source StatHat projects.
To learn more about Go, visit [[https://golang.org/][golang.org]].
diff --git a/content/c-go-cgo.article b/content/c-go-cgo.article
index 19a01f3..2ee6e92 100644
--- a/content/c-go-cgo.article
+++ b/content/c-go-cgo.article
@@ -6,9 +6,11 @@
* Introduction
-Cgo lets Go packages call C code. Given a Go source file written with some special features, cgo outputs Go and C files that can be combined into a single Go package.
+Cgo lets Go packages call C code. Given a Go source file written with some special features,
+cgo outputs Go and C files that can be combined into a single Go package.
-To lead with an example, here's a Go package that provides two functions - `Random` and `Seed` - that wrap C's `random` and `srandom` functions.
+To lead with an example, here's a Go package that provides two functions -
+`Random` and `Seed` - that wrap C's `random` and `srandom` functions.
package rand
@@ -27,11 +29,20 @@
Let's look at what's happening here, starting with the import statement.
-The `rand` package imports `"C"`, but you'll find there's no such package in the standard Go library. That's because `C` is a "pseudo-package", a special name interpreted by cgo as a reference to C's name space.
+The `rand` package imports `"C"`, but you'll find there's no such package
+in the standard Go library.
+That's because `C` is a "pseudo-package",
+a special name interpreted by cgo as a reference to C's name space.
-The `rand` package contains four references to the `C` package: the calls to `C.random` and `C.srandom`, the conversion `C.uint(i)`, and the `import` statement.
+The `rand` package contains four references to the `C` package:
+the calls to `C.random` and `C.srandom`, the conversion `C.uint(i)`,
+and the `import` statement.
-The `Random` function calls the standard C library's `random` function and returns the result. In C, `random` returns a value of the C type `long`, which cgo represents as the type `C.long`. It must be converted to a Go type before it can be used by Go code outside this package, using an ordinary Go type conversion:
+The `Random` function calls the standard C library's `random` function and returns the result.
+In C, `random` returns a value of the C type `long`,
+which cgo represents as the type `C.long`.
+It must be converted to a Go type before it can be used by Go code outside this package,
+using an ordinary Go type conversion:
func Random() int {
return int(C.random())
@@ -44,13 +55,17 @@
return int(r)
}
-The `Seed` function does the reverse, in a way. It takes a regular Go `int`, converts it to the C `unsigned`int` type, and passes it to the C function `srandom`.
+The `Seed` function does the reverse, in a way.
+It takes a regular Go `int`, converts it to the C `unsigned`int` type,
+and passes it to the C function `srandom`.
func Seed(i int) {
C.srandom(C.uint(i))
}
-Note that cgo knows the `unsigned`int` type as `C.uint`; see the [[https://golang.org/cmd/cgo][cgo documentation]] for a complete list of these numeric type names.
+Note that cgo knows the `unsigned`int` type as `C.uint`;
+see the [[https://golang.org/cmd/cgo][cgo documentation]] for a complete
+list of these numeric type names.
The one detail of this example we haven't examined yet is the comment above the `import` statement.
@@ -59,9 +74,19 @@
*/
import "C"
-Cgo recognizes this comment. Any lines starting with `#cgo` followed by a space character are removed; these become directives for cgo. The remaining lines are used as a header when compiling the C parts of the package. In this case those lines are just a single `#include` statement, but they can be almost any C code. The `#cgo` directives are used to provide flags for the compiler and linker when building the C parts of the package.
+Cgo recognizes this comment. Any lines starting with `#cgo` followed by
+a space character are removed;
+these become directives for cgo.
+The remaining lines are used as a header when compiling the C parts of the package.
+In this case those lines are just a single `#include` statement,
+but they can be almost any C code.
+The `#cgo` directives are used to provide flags for the compiler and linker
+when building the C parts of the package.
-There is a limitation: if your program uses any `//export` directives, then the C code in the comment may only include declarations (`extern`int`f();`), not definitions (`int`f()`{`return`1;`}`). You can use `//export` directives to make Go functions accessible to C code.
+There is a limitation: if your program uses any `//export` directives,
+then the C code in the comment may only include declarations (`extern`int`f();`),
+not definitions (`int`f()`{`return`1;`}`).
+You can use `//export` directives to make Go functions accessible to C code.
The `#cgo` and `//export` directives are documented in the [[https://golang.org/cmd/cgo/][cgo documentation]].
@@ -69,9 +94,12 @@
Unlike Go, C doesn't have an explicit string type. Strings in C are represented by a zero-terminated array of chars.
-Conversion between Go and C strings is done with the `C.CString`, `C.GoString`, and `C.GoStringN` functions. These conversions make a copy of the string data.
+Conversion between Go and C strings is done with the `C.CString`,
+`C.GoString`, and `C.GoStringN` functions.
+These conversions make a copy of the string data.
-This next example implements a `Print` function that writes a string to standard output using C's `fputs` function from the `stdio` library:
+This next example implements a `Print` function that writes a string to
+standard output using C's `fputs` function from the `stdio` library:
package print
@@ -86,9 +114,17 @@
C.free(unsafe.Pointer(cs))
}
-Memory allocations made by C code are not known to Go's memory manager. When you create a C string with `C.CString` (or any C memory allocation) you must remember to free the memory when you're done with it by calling `C.free`.
+Memory allocations made by C code are not known to Go's memory manager.
+When you create a C string with `C.CString` (or any C memory allocation)
+you must remember to free the memory when you're done with it by calling `C.free`.
-The call to `C.CString` returns a pointer to the start of the char array, so before the function exits we convert it to an [[https://golang.org/pkg/unsafe/#Pointer][`unsafe.Pointer`]] and release the memory allocation with `C.free`. A common idiom in cgo programs is to [[https://golang.org/doc/articles/defer_panic_recover.html][`defer`]] the free immediately after allocating (especially when the code that follows is more complex than a single function call), as in this rewrite of `Print`:
+The call to `C.CString` returns a pointer to the start of the char array,
+so before the function exits we convert it to an [[https://golang.org/pkg/unsafe/#Pointer][`unsafe.Pointer`]]
+and release the memory allocation with `C.free`.
+A common idiom in cgo programs is to [[https://golang.org/doc/articles/defer_panic_recover.html][`defer`]]
+the free immediately after allocating (especially when the code that follows
+is more complex than a single function call),
+as in this rewrite of `Print`:
func Print(s string) {
cs := C.CString(s)
@@ -98,10 +134,16 @@
* Building cgo packages
-To build cgo packages, just use [[https://golang.org/cmd/go/#Compile_packages_and_dependencies][`go`build`]] or [[https://golang.org/cmd/go/#Compile_and_install_packages_and_dependencies][`go`install`]] as usual. The go tool recognizes the special `"C"` import and automatically uses cgo for those files.
+To build cgo packages, just use [[https://golang.org/cmd/go/#Compile_packages_and_dependencies][`go`build`]]
+or [[https://golang.org/cmd/go/#Compile_and_install_packages_and_dependencies][`go`install`]] as usual.
+The go tool recognizes the special `"C"` import and automatically uses cgo for those files.
* More cgo resources
-The [[https://golang.org/cmd/cgo/][cgo command]] documentation has more detail about the C pseudo-package and the build process. The [[https://golang.org/misc/cgo/][cgo examples]] in the Go tree demonstrate more advanced concepts.
+The [[https://golang.org/cmd/cgo/][cgo command]] documentation has more
+detail about the C pseudo-package and the build process.
+The [[https://golang.org/misc/cgo/][cgo examples]] in the Go tree demonstrate
+more advanced concepts.
-Finally, if you're curious as to how all this works internally, take a look at the introductory comment of the runtime package's [[https://golang.org/src/runtime/cgocall.go][cgocall.go]].
+Finally, if you're curious as to how all this works internally,
+take a look at the introductory comment of the runtime package's [[https://golang.org/src/runtime/cgocall.go][cgocall.go]].
diff --git a/content/concurrency-is-not-parallelism.article b/content/concurrency-is-not-parallelism.article
index 19c7cb6..41563e9 100644
--- a/content/concurrency-is-not-parallelism.article
+++ b/content/concurrency-is-not-parallelism.article
@@ -6,14 +6,26 @@
* Introduction
-If there's one thing most people know about Go, is that it is designed for concurrency. No introduction to Go is complete without a demonstration of its goroutines and channels.
+If there's one thing most people know about Go,
+is that it is designed for concurrency.
+No introduction to Go is complete without a demonstration of its goroutines and channels.
-But when people hear the word _concurrency_ they often think of _parallelism_, a related but quite distinct concept. In programming, concurrency is the _composition_ of independently executing processes, while parallelism is the simultaneous _execution_ of (possibly related) computations. Concurrency is about _dealing_with_ lots of things at once. Parallelism is about _doing_ lots of things at once.
+But when people hear the word _concurrency_ they often think of _parallelism_,
+a related but quite distinct concept.
+In programming, concurrency is the _composition_ of independently executing processes,
+while parallelism is the simultaneous _execution_ of (possibly related) computations.
+Concurrency is about _dealing_with_ lots of things at once.
+Parallelism is about _doing_ lots of things at once.
-To clear up this conflation, Rob Pike gave a talk at [[http://heroku.com/][Heroku]]'s [[http://waza.heroku.com/][Waza]] conference entitled _Concurrency_is_not_parallelism_, and a video recording of the talk was released a few months ago.
+To clear up this conflation, Rob Pike gave a talk at [[http://heroku.com/][Heroku]]'s
+[[http://waza.heroku.com/][Waza]] conference entitled _Concurrency_is_not_parallelism_,
+and a video recording of the talk was released a few months ago.
.iframe //player.vimeo.com/video/49718712?badge=0 281 500
-The slides are available at [[https://talks.golang.org/2012/waza.slide][talks.golang.org]] (use the left and right arrow keys to navigate).
+The slides are available at [[https://talks.golang.org/2012/waza.slide][talks.golang.org]]
+(use the left and right arrow keys to navigate).
-To learn about Go's concurrency primitives, watch [[http://www.youtube.com/watch?v=f6kdp27TYZs][Go concurrency patterns]] ([[https://talks.golang.org/2012/concurrency.slide][slides]]).
+To learn about Go's concurrency primitives,
+watch [[http://www.youtube.com/watch?v=f6kdp27TYZs][Go concurrency patterns]]
+([[https://talks.golang.org/2012/concurrency.slide][slides]]).
diff --git a/content/constants.article b/content/constants.article
index 7258aa9..36c4edc 100644
--- a/content/constants.article
+++ b/content/constants.article
@@ -14,8 +14,10 @@
* Background: C
-In the early days of thinking about Go, we talked about a number of problems caused by the way C and its descendants let you mix and match numeric types.
-Many mysterious bugs, crashes, and portability problems are caused by expressions that combine integers of different sizes and "signedness".
+In the early days of thinking about Go, we talked about a number of problems
+caused by the way C and its descendants let you mix and match numeric types.
+Many mysterious bugs, crashes, and portability problems are caused by expressions
+that combine integers of different sizes and "signedness".
Although to a seasoned C programmer the result of a calculation like
unsigned int u = 1e9;
@@ -29,7 +31,9 @@
Nasty bugs lurk here.
-C has a set of rules called "the usual arithmetic conversions" and it is an indicator of their subtlety that they have changed over the years (introducing yet more bugs, retroactively).
+C has a set of rules called "the usual arithmetic conversions" and it is
+an indicator of their subtlety that they have changed over the years (introducing
+yet more bugs, retroactively).
When designing Go, we decided to avoid this minefield by mandating that there is _no_ mixing of numeric types.
If you want to add `i` and `u`, you must be explicit about what you want the result to be.
@@ -38,20 +42,27 @@
var u uint
var i int
-you can write either `uint(i)+u` or `i+int(u)`, with both the meaning and type of the addition clearly expressed, but unlike in C you cannot write `i+u`.
+you can write either `uint(i)+u` or `i+int(u)`,
+with both the meaning and type of the addition clearly expressed,
+but unlike in C you cannot write `i+u`.
You can't even mix `int` and `int32`, even when `int` is a 32-bit type.
This strictness eliminates a common cause of bugs and other failures.
It is a vital property of Go.
-But it has a cost: it sometimes requires programmers to decorate their code with clumsy numeric conversions to express their meaning clearly.
+But it has a cost: it sometimes requires programmers to decorate their code
+with clumsy numeric conversions to express their meaning clearly.
And what about constants?
Given the declarations above, what would make it legal to write `i` `=` `0` or `u` `=` `0`?
What is the _type_ of `0`?
It would be unreasonable to require constants to have type conversions in simple contexts such as `i` `=` `int(0)`.
-We soon realized the answer lay in making numeric constants work differently from how they behave in other C-like languages.
-After much thinking and experimentation, we came up with a design that we believe feels right almost always, freeing the programmer from converting constants all the time yet being able to write things like `math.Sqrt(2)` without being chided by the compiler.
+We soon realized the answer lay in making numeric constants work differently
+from how they behave in other C-like languages.
+After much thinking and experimentation, we came up with a design that we
+believe feels right almost always,
+freeing the programmer from converting constants all the time yet being
+able to write things like `math.Sqrt(2)` without being chided by the compiler.
In short, constants in Go just work, most of the time anyway.
Let's see how that happens.
@@ -61,37 +72,47 @@
First, a quick definition.
In Go, `const` is a keyword introducing a name for a scalar value such as `2` or `3.14159` or `"scrumptious"`.
Such values, named or otherwise, are called _constants_ in Go.
-Constants can also be created by expressions built from constants, such as `2+3` or `2+3i` or `math.Pi/2` or `("go"+"pher")`.
+Constants can also be created by expressions built from constants,
+such as `2+3` or `2+3i` or `math.Pi/2` or `("go"+"pher")`.
-Some languages don't have constants, and others have a more general definition of constant or application of the word `const`.
-In C and C++, for instance, `const` is a type qualifier that can codify more intricate properties of more intricate values.
+Some languages don't have constants, and others have a more general definition
+of constant or application of the word `const`.
+In C and C++, for instance, `const` is a type qualifier that can codify
+more intricate properties of more intricate values.
But in Go, a constant is just a simple, unchanging value, and from here on we're talking only about Go.
* String constants
-There are many kinds of numeric constants—integers, floats, runes, signed, unsigned, imaginary, complex—so let's start with a simpler form of constant: strings.
-String constants are easy to understand and provide a smaller space in which to explore the type issues of constants in Go.
+There are many kinds of numeric constants—integers,
+floats, runes, signed, unsigned, imaginary,
+complex—so let's start with a simpler form of constant: strings.
+String constants are easy to understand and provide a smaller space in which
+to explore the type issues of constants in Go.
A string constant encloses some text between double quotes.
-(Go also has raw string literals, enclosed by backquotes ``````, but for the purpose of this discussion they have all the same properties.)
+(Go also has raw string literals, enclosed by backquotes ``````,
+but for the purpose of this discussion they have all the same properties.)
Here is a string constant:
"Hello, 世界"
-(For much more detail about the representation and interpretation of strings, see [[https://blog.golang.org/strings][this blog post]].)
+(For much more detail about the representation and interpretation of strings,
+see [[https://blog.golang.org/strings][this blog post]].)
What type does this string constant have?
The obvious answer is `string`, but that is _wrong_.
-This is an _untyped_string_constant_, which is to say it is a constant textual value that does not yet have a fixed type.
+This is an _untyped_string_constant_, which is to say it is a constant textual
+value that does not yet have a fixed type.
Yes, it's a string, but it's not a Go value of type `string`.
It remains an untyped string constant even when given a name:
const hello = "Hello, 世界"
After this declaration, `hello` is also an untyped string constant.
-An untyped constant is just a value, one not yet given a defined type that would force it to obey the strict rules that prevent combining differently typed values.
+An untyped constant is just a value, one not yet given a defined type that
+would force it to obey the strict rules that prevent combining differently typed values.
It is this notion of an _untyped_ constant that makes it possible for us to use constants in Go with great freedom.
@@ -119,7 +140,9 @@
.play -edit constants/string4.go /START/,/STOP/
-Returning to our _untyped_ string constant, it has the helpful property that, since it has no type, assigning it to a typed variable does not cause a type error.
+Returning to our _untyped_ string constant,
+it has the helpful property that, since it has no type,
+assigning it to a typed variable does not cause a type error.
That is, we can write
m = "Hello, 世界"
@@ -128,10 +151,13 @@
m = hello
-because, unlike the typed constants `typedHello` and `myStringHello`, the untyped constants `"Hello,`世界"` and `hello` _have_no_type_.
+because, unlike the typed constants `typedHello` and `myStringHello`,
+the untyped constants `"Hello,`世界"` and `hello` _have_no_type_.
Assigning them to a variable of any type compatible with strings works without error.
-These untyped string constants are strings, of course, so they can only be used where a string is allowed, but they do not have _type_ `string`.
+These untyped string constants are strings,
+of course, so they can only be used where a string is allowed,
+but they do not have _type_ `string`.
* Default type
@@ -140,7 +166,8 @@
str := "Hello, 世界"
and by now you might be asking, "if the constant is untyped, how does `str` get a type in this variable declaration?"
-The answer is that an untyped constant has a default type, an implicit type that it transfers to a value if a type is needed where none is provided.
+The answer is that an untyped constant has a default type,
+an implicit type that it transfers to a value if a type is needed where none is provided.
For untyped string constants, that default type is obviously `string`, so
str := "Hello, 世界"
@@ -153,9 +180,14 @@
var str string = "Hello, 世界"
-One way to think about untyped constants is that they live in a kind of ideal space of values, a space less restrictive than Go's full type system.
-But to do anything with them, we need to assign them to variables, and when that happens the _variable_ (not the constant itself) needs a type, and the constant can tell the variable what type it should have.
-In this example, `str` becomes a value of type `string` because the untyped string constant gives the declaration its default type, `string`.
+One way to think about untyped constants is that they live in a kind of
+ideal space of values,
+a space less restrictive than Go's full type system.
+But to do anything with them, we need to assign them to variables,
+and when that happens the _variable_ (not the constant itself) needs a type,
+and the constant can tell the variable what type it should have.
+In this example, `str` becomes a value of type `string` because the untyped
+string constant gives the declaration its default type, `string`.
In such a declaration, a variable is declared with a type and initial value.
Sometimes when we use a constant, however, the destination of the value is not so clear.
@@ -172,7 +204,8 @@
to pass as an argument, and the concrete type stored for that argument is the default type of the constant.
This process is analogous to what we saw earlier when declaring an initialized value using an untyped string constant.
-You can see the result in this example, which uses the format `%v` to print the value and `%T` to print the type of the value being passed to `fmt.Printf`:
+You can see the result in this example, which uses the format `%v` to print
+the value and `%T` to print the type of the value being passed to `fmt.Printf`:
.play -edit constants/default2.go /START/,/STOP/
@@ -180,10 +213,12 @@
.play -edit constants/default3.go /START/,/STOP/
-(For more information about how interface values work, see the first sections of [[https://blog.golang.org/laws-of-reflection][this blog post]].)
+(For more information about how interface values work,
+see the first sections of [[https://blog.golang.org/laws-of-reflection][this blog post]].)
In summary, a typed constant obeys all the rules of typed values in Go.
-On the other hand, an untyped constant does not carry a Go type in the same way and can be mixed and matched more freely.
+On the other hand, an untyped constant does not carry a Go type in the same
+way and can be mixed and matched more freely.
It does, however, have a default type that is exposed when, and only when, no other type information is available.
* Default type determined by syntax
@@ -191,7 +226,9 @@
The default type of an untyped constant is determined by its syntax.
For string constants, the only possible implicit type is `string`.
For [[https://golang.org/ref/spec#Numeric_types][numeric constants]], the implicit type has more variety.
-Integer constants default to `int`, floating-point constants `float64`, rune constants to `rune` (an alias for `int32`), and imaginary constants to `complex128`.
+Integer constants default to `int`, floating-point constants `float64`,
+rune constants to `rune` (an alias for `int32`),
+and imaginary constants to `complex128`.
Here's our canonical print statement used repeatedly to show the default types in action:
.play -edit constants/syntax.go /START/,/STOP/
@@ -235,7 +272,8 @@
.play -edit constants/float3.go /Println/
The error is, "constant 1.00000e+1000 overflows float64", which is true.
-But `Huge` might be useful: we can use it in expressions with other constants and use the value of those expressions if the result
+But `Huge` might be useful: we can use it in expressions with other constants
+and use the value of those expressions if the result
can be represented in the range of a `float64`.
The statement,
@@ -243,24 +281,29 @@
prints `10`, as one would expect.
-In a related way, floating-point constants may have very high precision, so that arithmetic involving them is more accurate.
+In a related way, floating-point constants may have very high precision,
+so that arithmetic involving them is more accurate.
The constants defined in the [[https://golang.org/pkg/math][math]] package are given with many more digits than are
available in a `float64`. Here is the definition of `math.Pi`:
Pi = 3.14159265358979323846264338327950288419716939937510582097494459
-When that value is assigned to a variable, some of the precision will be lost; the assignment will create the `float64` (or `float32`)
+When that value is assigned to a variable,
+some of the precision will be lost;
+the assignment will create the `float64` (or `float32`)
value closest to the high-precision value. This snippet
.play -edit constants/float5.go /START/,/STOP/
prints `3.141592653589793`.
-Having so many digits available means that calculations like `Pi/2` or other more intricate evaluations can carry more precision
+Having so many digits available means that calculations like `Pi/2` or other
+more intricate evaluations can carry more precision
until the result is assigned, making calculations involving constants easier to write without losing precision.
It also means that there is no occasion in which the floating-point corner cases like infinities,
soft underflows, and `NaNs` arise in constant expressions.
-(Division by a constant zero is a compile-time error, and when everything is a number there's no such thing as "not a number".)
+(Division by a constant zero is a compile-time error,
+and when everything is a number there's no such thing as "not a number".)
* Complex numbers
@@ -271,7 +314,8 @@
The default type of a complex number is `complex128`, the larger-precision version composed of two `float64` values.
-For clarity in our example, we wrote out the full expression `(0.0+1.0i)`, but this value can be shortened to `0.0+1.0i`,
+For clarity in our example, we wrote out the full expression `(0.0+1.0i)`,
+but this value can be shortened to `0.0+1.0i`,
`1.0i` or even `1i`.
Let's play a trick.
@@ -288,7 +332,8 @@
.play -edit constants/complex2.go /START/,/STOP/
prints `complex128:` `(2+0i)`.
-But numerically, `Two` can be stored in a scalar floating-point number, a `float64` or `float32`, with no loss of information.
+But numerically, `Two` can be stored in a scalar floating-point number,
+a `float64` or `float32`, with no loss of information.
Thus we can assign `Two` to a `float64`, either in an initialization or an assignment, without problems:
.play -edit constants/complex3.go /START/,/STOP/
@@ -300,7 +345,8 @@
* Integers
At last we come to integers.
-They have more moving parts—[[https://golang.org/ref/spec#Numeric_types][many sizes, signed or unsigned, and more]]—but they play by the same rules.
+They have more moving parts—[[https://golang.org/ref/spec#Numeric_types][many sizes, signed or unsigned, and more]]—but
+they play by the same rules.
For the last time, here is our familiar example, using just `int` this time:
.play -edit constants/int1.go /START/,/STOP/
@@ -312,27 +358,36 @@
uintptr
(plus the aliases `byte` for `uint8` and `rune` for `int32`).
-That's a lot, but the pattern in the way constants work should be familiar enough by now that you can see how things will play out.
+That's a lot, but the pattern in the way constants work should be familiar
+enough by now that you can see how things will play out.
-As mentioned above, integers come in a couple of forms and each form has its own default type: `int` for simple constants like `123` or `0xFF` or `-14`
+As mentioned above, integers come in a couple of forms and each form has
+its own default type:
+`int` for simple constants like `123` or `0xFF` or `-14`
and `rune` for quoted characters like 'a', '世' or '\r'.
No constant form has as its default type an unsigned integer type.
-However, the flexibility of untyped constants means we can initialize unsigned integer variables using simple constants as long as we are clear about the type.
+However, the flexibility of untyped constants means we can initialize unsigned
+integer variables using simple constants as long as we are clear about the type.
It's analogous to how we can initialize a `float64` using a complex number with zero imaginary part.
-Here are several different ways to initialize a `uint`; all are equivalent, but all must mention the type explicitly for the result to be unsigned.
+Here are several different ways to initialize a `uint`;
+all are equivalent, but all must mention the type explicitly for the result to be unsigned.
var u uint = 17
var u = uint(17)
u := uint(17)
-Similarly to the range issue mentioned in the section on floating-point values, not all integer values can fit in all integer types.
-There are two problems that might arise: the value might be too large, or it might be a negative value being assigned to an unsigned integer type.
-For instance, `int8` has range -128 through 127, so constants outside of that range can never be assigned to a variable of type `int8`:
+Similarly to the range issue mentioned in the section on floating-point values,
+not all integer values can fit in all integer types.
+There are two problems that might arise: the value might be too large,
+or it might be a negative value being assigned to an unsigned integer type.
+For instance, `int8` has range -128 through 127,
+so constants outside of that range can never be assigned to a variable of type `int8`:
.play -edit constants/int2.go /var/
-Similarly, `uint8`, also known as `byte`, has range 0 through 255, so a large or negative constant cannot be assigned to a `uint8`:
+Similarly, `uint8`, also known as `byte`,
+has range 0 through 255, so a large or negative constant cannot be assigned to a `uint8`:
.play -edit constants/int3.go /var/
@@ -362,7 +417,8 @@
.play -edit constants/exercise1.go /const/
-but that is illegal because -1 cannot be represented by an unsigned variable; `-1` is not in the range of unsigned values.
+but that is illegal because -1 cannot be represented by an unsigned variable;
+`-1` is not in the range of unsigned values.
A conversion won't help either, for the same reason:
.play -edit constants/exercise2.go /const/
@@ -373,11 +429,13 @@
.play -edit constants/exercise3.go /START/,/STOP/
-but only because `v` is a variable; if we made `v` a constant, even an untyped constant, we'd be back in forbidden territory:
+but only because `v` is a variable; if we made `v` a constant,
+even an untyped constant, we'd be back in forbidden territory:
.play -edit constants/exercise4.go /START/,/STOP/
-We return to our previous approach, but instead of `-1` we try `^0`, the bitwise negation of an arbitrary number of zero bits.
+We return to our previous approach, but instead of `-1` we try `^0`,
+the bitwise negation of an arbitrary number of zero bits.
But that fails too, for a similar reason:
In the space of numeric values,
`^0` represents an infinite number of ones, so we lose information if we assign that to any fixed-size integer:
@@ -401,13 +459,17 @@
(on the [[https://blog.golang.org/playground][playground]], it's 32),
this constant correctly represents the largest value a variable of type `uint` can hold.
-If you understand the analysis that got us to this result, you understand all the important points about constants in Go.
+If you understand the analysis that got us to this result,
+you understand all the important points about constants in Go.
* Numbers
-The concept of untyped constants in Go means that all the numeric constants, whether integer, floating-point, complex, or even character values,
+The concept of untyped constants in Go means that all the numeric constants,
+whether integer, floating-point, complex,
+or even character values,
live in a kind of unified space.
-It's when we bring them to the computational world of variables, assignments, and operations that the actual types matter.
+It's when we bring them to the computational world of variables,
+assignments, and operations that the actual types matter.
But as long as we stay in the world of numeric constants, we can mix and match values as we like.
All these constants have numeric value 1:
@@ -419,7 +481,8 @@
'b' - 'a'
1.0+3i-3.0i
-Therefore, although they have different implicit default types, written as untyped constants they can be assigned to a variable of any integer type:
+Therefore, although they have different implicit default types,
+written as untyped constants they can be assigned to a variable of any integer type:
.play -edit constants/numbers1.go /START/,/STOP/
@@ -432,7 +495,8 @@
which yields 145.5, which is pointless except to prove a point.
But the real point of these rules is flexibility.
-That flexibility means that, despite the fact that in Go it is illegal in the same expression to mix floating-point and integer variables,
+That flexibility means that, despite the fact that in Go it is illegal in
+the same expression to mix floating-point and integer variables,
or even `int` and `int32` variables, it is fine to write
sqrt2 := math.Sqrt(2)
diff --git a/content/debugging-go-code-status-report.article b/content/debugging-go-code-status-report.article
index 0706d14..9da89e1 100644
--- a/content/debugging-go-code-status-report.article
+++ b/content/debugging-go-code-status-report.article
@@ -6,9 +6,18 @@
* Introduction
-When it comes to debugging, nothing beats a few strategic print statements to inspect variables or a well-placed panic to obtain a stack trace. However, sometimes you’re missing either the patience or the source code, and in those cases a good debugger can be invaluable. That's why over the past few releases we have been improving the support in Go’s gc linker (6l, 8l) for GDB, the GNU debugger.
+When it comes to debugging, nothing beats a few strategic print statements
+to inspect variables or a well-placed panic to obtain a stack trace.
+However, sometimes you’re missing either the patience or the source code,
+and in those cases a good debugger can be invaluable.
+That's why over the past few releases we have been improving the support
+in Go’s gc linker (6l,
+8l) for GDB, the GNU debugger.
-In the latest release (2010-11-02), the 6l and 8l linkers emit DWARF3 debugging information when writing ELF (Linux, FreeBSD) or Mach-O (Mac OS X) binaries. The DWARF code is rich enough to let you do the following:
+In the latest release (2010-11-02), the 6l and 8l linkers emit DWARF3 debugging
+information when writing ELF (Linux,
+FreeBSD) or Mach-O (Mac OS X) binaries.
+The DWARF code is rich enough to let you do the following:
- load a Go program in GDB version 7.x,
- list all Go, C, and assembly source files by line (parts of the Go runtime are written in C and assembly),
@@ -18,10 +27,28 @@
There are still some inconveniences:
-- The emitted DWARF code is unreadable by the GDB version 6.x that ships with Mac OS X. We would gladly accept patches to make the DWARF output compatible with the standard OS X GDB, but until that’s fixed you’ll need to download, build, and install GDB 7.x to use it under OS X. The source can be found at [[http://sourceware.org/gdb/download/][http://sourceware.org/gdb/download/]]. Due to the particulars of OS X you’ll need to install the binary on a local file system with `chgrp`procmod` and `chmod`g+s`.
-- Names are qualified with a package name and, as GDB doesn't understand Go packages, you must reference each item by its full name. For example, the variable named `v` in package `main` must be referred to as `'main.v'`, in single quotes. A consequence of this is that tab completion of variable and function names does not work.
-- Lexical scoping information is somewhat obfuscated. If there are multiple variables of the same name, the nth instance will have a suffix of the form ‘#n’. We plan to fix this, but it will require some changes to the data exchanged between the compiler and linker.
-- Slice and string variables are represented as their underlying structure in the runtime library. They will look something like `{data`=`0x2aaaaab3e320,`len`=`1,`cap`=`1}.` For slices, you must dereference the data pointer to inspect the elements.
+- The emitted DWARF code is unreadable by the GDB version 6.x that ships with Mac OS X.
+ We would gladly accept patches to make the DWARF output compatible with
+ the standard OS X GDB,
+ but until that’s fixed you’ll need to download,
+ build, and install GDB 7.x to use it under OS X.
+ The source can be found at [[http://sourceware.org/gdb/download/][http://sourceware.org/gdb/download/]].
+ Due to the particulars of OS X you’ll need to install the binary on a
+ local file system with `chgrp`procmod` and `chmod`g+s`.
+- Names are qualified with a package name and,
+ as GDB doesn't understand Go packages, you must reference each item by its full name.
+ For example, the variable named `v` in package `main` must be referred to
+ as `'main.v'`, in single quotes.
+ A consequence of this is that tab completion of variable and function names does not work.
+- Lexical scoping information is somewhat obfuscated.
+ If there are multiple variables of the same name,
+ the nth instance will have a suffix of the form ‘#n’.
+ We plan to fix this, but it will require some changes to the data exchanged
+ between the compiler and linker.
+- Slice and string variables are represented as their underlying structure
+ in the runtime library.
+ They will look something like `{data`=`0x2aaaaab3e320,`len`=`1,`cap`=`1}.` For slices,
+ you must dereference the data pointer to inspect the elements.
Some things don't work yet:
@@ -29,6 +56,10 @@
- Only Go variables are annotated with type information; the runtime's C variables are not.
- Windows and ARM binaries do not contain DWARF debugging information and, as such, cannot be inspected with GDB.
-Over the coming months we intend to address these issues, either by changing the compiler and linker or by using the Python extensions to GDB. In the meantime, we hope that Go programmers will benefit from having better access to this well-known debugging tool.
+Over the coming months we intend to address these issues,
+either by changing the compiler and linker or by using the Python extensions to GDB.
+In the meantime, we hope that Go programmers will benefit from having better
+access to this well-known debugging tool.
-P.S. The DWARF information can also be read by tools other than GDB. For example, on Linux you can use it with the sysprof system-wide profiler.
+P.S. The DWARF information can also be read by tools other than GDB.
+For example, on Linux you can use it with the sysprof system-wide profiler.
diff --git a/content/debugging-go-programs-with-gnu-debugger.article b/content/debugging-go-programs-with-gnu-debugger.article
index 6988636..2df3997 100644
--- a/content/debugging-go-programs-with-gnu-debugger.article
+++ b/content/debugging-go-programs-with-gnu-debugger.article
@@ -6,7 +6,13 @@
* Introduction
-Last year we [[https://blog.golang.org/2010/11/debugging-go-code-status-report.html][reported]] that Go's [[https://golang.org/cmd/gc/][gc]]/[[https://golang.org/cmd/6l/][ld]] toolchain produces DWARFv3 debugging information that can be read by the GNU Debugger (GDB). Since then, work has continued steadily on improving support for debugging Go code with GDB.
-Among the improvements are the ability to inspect goroutines and to print native Go data types, including structs, slices, strings, maps, interfaces, and channels.
+Last year we [[https://blog.golang.org/2010/11/debugging-go-code-status-report.html][reported]]
+that Go's [[https://golang.org/cmd/gc/][gc]]/[[https://golang.org/cmd/6l/][ld]]
+toolchain produces DWARFv3 debugging information that can be read by the GNU Debugger (GDB).
+Since then, work has continued steadily on improving support for debugging Go code with GDB.
+Among the improvements are the ability to inspect goroutines and to print
+native Go data types,
+including structs, slices, strings, maps,
+interfaces, and channels.
To learn more about Go and GDB, see the [[https://golang.org/doc/debugging_with_gdb.html][Debugging with GDB]] article.
diff --git a/content/debugging-what-you-deploy.article b/content/debugging-what-you-deploy.article
index b197359..9d1fde8 100644
--- a/content/debugging-what-you-deploy.article
+++ b/content/debugging-what-you-deploy.article
@@ -6,35 +6,73 @@
* Introduction
-Go 1.11 and Go 1.12 make significant progress toward allowing developers to debug the same optimized binaries that they deploy to production.
+Go 1.11 and Go 1.12 make significant progress toward allowing developers
+to debug the same optimized binaries that they deploy to production.
-As the Go compiler has become increasingly aggressive in producing faster binaries, we've lost ground in debuggability. In Go 1.10, users needed to disable optimizations entirely in order to have a good debugging experience from interactive tools like Delve. But users shouldn’t have to trade performance for debuggability, especially when running production services. If your problem is occurring in production, you need to debug it in production, and that shouldn’t require deploying unoptimized binaries.
+As the Go compiler has become increasingly aggressive in producing faster binaries,
+we've lost ground in debuggability.
+In Go 1.10, users needed to disable optimizations entirely in order to have
+a good debugging experience from interactive tools like Delve.
+But users shouldn’t have to trade performance for debuggability,
+especially when running production services.
+If your problem is occurring in production,
+you need to debug it in production, and that shouldn’t require deploying
+unoptimized binaries.
-For Go 1.11 and 1.12, we focused on improving the debugging experience on optimized binaries (the default setting of the Go compiler). Improvements include
+For Go 1.11 and 1.12, we focused on improving the debugging experience on
+optimized binaries (the default setting of the Go compiler).
+Improvements include
- More accurate value inspection, in particular for arguments at function entry;
-- More precisely identifying statement boundaries so that stepping is less jumpy and breakpoints more often land where the programmer expects;
-- And preliminary support for Delve to call Go functions (goroutines and garbage collection make this trickier than it is in C and C++).
+- More precisely identifying statement boundaries so that stepping is less
+ jumpy and breakpoints more often land where the programmer expects;
+- And preliminary support for Delve to call Go functions (goroutines and
+ garbage collection make this trickier than it is in C and C++).
* Debugging optimized code with Delve
-[[https://github.com/go-delve/delve][Delve]] is a debugger for Go on x86 supporting both Linux and macOS. Delve is aware of goroutines and other Go features and provides one of the best Go debugging experiences. Delve is also the debugging engine behind [[https://www.jetbrains.com/go/][GoLand]], [[https://code.visualstudio.com/][VS Code]], and [[https://github.com/fatih/vim-go][Vim]].
+[[https://github.com/go-delve/delve][Delve]] is a debugger for Go on x86
+supporting both Linux and macOS.
+Delve is aware of goroutines and other Go features and provides one of the
+best Go debugging experiences.
+Delve is also the debugging engine behind [[https://www.jetbrains.com/go/][GoLand]],
+[[https://code.visualstudio.com/][VS Code]],
+and [[https://github.com/fatih/vim-go][Vim]].
-Delve normally rebuilds the code it is debugging with `-gcflags`"all=-N`-l"`, which disables inlining and most optimizations. To debug optimized code with delve, first build the optimized binary, then use `dlv`exec`your_program` to debug it. Or, if you have a core file from a crash, you can examine it with `dlv`core`your_program`your_core`. With 1.12 and the latest Delve releases, you should be able to examine many variables, even in optimized binaries.
+Delve normally rebuilds the code it is debugging with `-gcflags`"all=-N`-l"`,
+which disables inlining and most optimizations.
+To debug optimized code with delve, first build the optimized binary,
+then use `dlv`exec`your_program` to debug it.
+Or, if you have a core file from a crash,
+you can examine it with `dlv`core`your_program`your_core`.
+With 1.12 and the latest Delve releases, you should be able to examine many variables,
+even in optimized binaries.
* Improved value inspection
-When debugging optimized binaries produced by Go 1.10, variable values were usually completely unavailable. In contrast, starting with Go 1.11, variables can usually be examined even in optimized binaries, unless they’ve been optimized away completely. In Go 1.11 the compiler began emitting DWARF location lists so debuggers can track variables as they move in and out of registers and reconstruct complex objects that are split across different registers and stack slots.
+When debugging optimized binaries produced by Go 1.10,
+variable values were usually completely unavailable.
+In contrast, starting with Go 1.11, variables can usually be examined even
+in optimized binaries,
+unless they’ve been optimized away completely.
+In Go 1.11 the compiler began emitting DWARF location lists so debuggers
+can track variables as they move in and out of registers and reconstruct
+complex objects that are split across different registers and stack slots.
* Improved stepping
-This shows an example of stepping through a simple function in a debugger in 1.10, with flaws (skipped and repeated lines) highlighted by red arrows.
+This shows an example of stepping through a simple function in a debugger in 1.10,
+with flaws (skipped and repeated lines) highlighted by red arrows.
.image debugging-what-you-deploy.svg _ 450
-Flaws like this make it easy to lose track of where you are when stepping through a program and interfere with hitting breakpoints.
+Flaws like this make it easy to lose track of where you are when stepping
+through a program and interfere with hitting breakpoints.
-Go 1.11 and 1.12 record statement boundary information and do a better job of tracking source line numbers through optimizations and inlining. As a result, in Go 1.12, stepping through this code stops on every line and does so in the order you would expect.
+Go 1.11 and 1.12 record statement boundary information and do a better job
+of tracking source line numbers through optimizations and inlining.
+As a result, in Go 1.12, stepping through this code stops on every line
+and does so in the order you would expect.
* Function calls
@@ -48,12 +86,30 @@
* The path forward
-Go 1.12 is a step toward a better debugging experience for optimized binaries and we have plans to improve it even further.
+Go 1.12 is a step toward a better debugging experience for optimized binaries
+and we have plans to improve it even further.
-There are fundamental tradeoffs between debuggability and performance, so we’re focusing on the highest-priority debugging defects, and working to collect automated metrics to monitor our progress and catch regressions.
+There are fundamental tradeoffs between debuggability and performance,
+so we’re focusing on the highest-priority debugging defects,
+and working to collect automated metrics to monitor our progress and catch regressions.
-We’re focusing on generating correct information for debuggers about variable locations, so if a variable can be printed, it is printed correctly. We’re also looking at making variable values available more of the time, particularly at key points like call sites, though in many cases improving this would require slowing down program execution. Finally, we’re working on improving stepping: we’re focusing on the order of stepping with panics, the order of stepping around loops, and generally trying to follow source order where possible.
+We’re focusing on generating correct information for debuggers about variable locations,
+so if a variable can be printed, it is printed correctly.
+We’re also looking at making variable values available more of the time,
+particularly at key points like call sites,
+though in many cases improving this would require slowing down program execution.
+Finally, we’re working on improving stepping:
+we’re focusing on the order of stepping with panics,
+the order of stepping around loops, and generally trying to follow source
+order where possible.
* A note on macOS support
-Go 1.11 started compressing debug information to reduce binary sizes. This is natively supported by Delve, but neither LLDB nor GDB support compressed debug info on macOS. If you are using LLDB or GDB, there are two workarounds: build binaries with `-ldflags=-compressdwarf=false`, or use [[https://godoc.org/golang.org/x/tools/cmd/splitdwarf][splitdwarf]] (`go`get`golang.org/x/tools/cmd/splitdwarf`) to decompress the debug information in an existing binary.
+Go 1.11 started compressing debug information to reduce binary sizes.
+This is natively supported by Delve, but neither LLDB nor GDB support compressed
+debug info on macOS.
+If you are using LLDB or GDB, there are two workarounds:
+build binaries with `-ldflags=-compressdwarf=false`,
+or use [[https://godoc.org/golang.org/x/tools/cmd/splitdwarf][splitdwarf]]
+(`go`get`golang.org/x/tools/cmd/splitdwarf`) to decompress the debug information
+in an existing binary.
diff --git a/content/defer-panic-and-recover.article b/content/defer-panic-and-recover.article
index 2c4018c..8bea0ab 100644
--- a/content/defer-panic-and-recover.article
+++ b/content/defer-panic-and-recover.article
@@ -6,10 +6,16 @@
* Introduction
-Go has the usual mechanisms for control flow: if, for, switch, goto. It also has the go statement to run code in a separate goroutine. Here I'd like to discuss some of the less common ones: defer, panic, and recover.
+Go has the usual mechanisms for control flow:
+if, for, switch, goto.
+It also has the go statement to run code in a separate goroutine.
+Here I'd like to discuss some of the less common ones:
+defer, panic, and recover.
-A *defer*statement* pushes a function call onto a list. The list of saved calls is executed after the surrounding function returns. Defer is commonly used to simplify functions that perform various clean-up actions.
+A *defer*statement* pushes a function call onto a list.
+The list of saved calls is executed after the surrounding function returns.
+Defer is commonly used to simplify functions that perform various clean-up actions.
For example, let's look at a function that opens two files and copies the contents of one file to the other:
@@ -32,7 +38,12 @@
return
}
-This works, but there is a bug. If the call to os.Create fails, the function will return without closing the source file. This can be easily remedied by putting a call to src.Close before the second return statement, but if the function were more complex the problem might not be so easily noticed and resolved. By introducing defer statements we can ensure that the files are always closed:
+This works, but there is a bug. If the call to os.Create fails,
+the function will return without closing the source file.
+This can be easily remedied by putting a call to src.Close before the second return statement,
+but if the function were more complex the problem might not be so easily
+noticed and resolved.
+By introducing defer statements we can ensure that the files are always closed:
func CopyFile(dstName, srcName string) (written int64, err error) {
@@ -51,13 +62,16 @@
return io.Copy(dst, src)
}
-Defer statements allow us to think about closing each file right after opening it, guaranteeing that, regardless of the number of return statements in the function, the files _will_ be closed.
+Defer statements allow us to think about closing each file right after opening it,
+guaranteeing that, regardless of the number of return statements in the function,
+the files _will_ be closed.
The behavior of defer statements is straightforward and predictable. There are three simple rules:
1. _A_deferred_function's_arguments_are_evaluated_when_the_defer_statement_is_evaluated._
-In this example, the expression "i" is evaluated when the Println call is deferred. The deferred call will print "0" after the function returns.
+In this example, the expression "i" is evaluated when the Println call is deferred.
+The deferred call will print "0" after the function returns.
func a() {
@@ -80,7 +94,9 @@
3. _Deferred_functions_may_read_and_assign_to_the_returning_function's_named_return_values._
-In this example, a deferred function increments the return value i _after_ the surrounding function returns. Thus, this function returns 2:
+In this example, a deferred function increments the return value i _after_
+the surrounding function returns.
+Thus, this function returns 2:
func c() (i int) {
defer func() { i++ }()
@@ -91,10 +107,23 @@
This is convenient for modifying the error return value of a function; we will see an example of this shortly.
-*Panic* is a built-in function that stops the ordinary flow of control and begins _panicking_. When the function F calls panic, execution of F stops, any deferred functions in F are executed normally, and then F returns to its caller. To the caller, F then behaves like a call to panic. The process continues up the stack until all functions in the current goroutine have returned, at which point the program crashes. Panics can be initiated by invoking panic directly. They can also be caused by runtime errors, such as out-of-bounds array accesses.
+*Panic* is a built-in function that stops the ordinary flow of control and begins _panicking_.
+When the function F calls panic, execution of F stops,
+any deferred functions in F are executed normally,
+and then F returns to its caller.
+To the caller, F then behaves like a call to panic.
+The process continues up the stack until all functions in the current goroutine have returned,
+at which point the program crashes.
+Panics can be initiated by invoking panic directly.
+They can also be caused by runtime errors,
+such as out-of-bounds array accesses.
-*Recover* is a built-in function that regains control of a panicking goroutine. Recover is only useful inside deferred functions. During normal execution, a call to recover will return nil and have no other effect. If the current goroutine is panicking, a call to recover will capture the value given to panic and resume normal execution.
+*Recover* is a built-in function that regains control of a panicking goroutine.
+Recover is only useful inside deferred functions.
+During normal execution, a call to recover will return nil and have no other effect.
+If the current goroutine is panicking, a call to recover will capture the
+value given to panic and resume normal execution.
Here's an example program that demonstrates the mechanics of panic and defer:
@@ -130,7 +159,11 @@
}
-The function g takes the int i, and panics if i is greater than 3, or else it calls itself with the argument i+1. The function f defers a function that calls recover and prints the recovered value (if it is non-nil). Try to picture what the output of this program might be before reading on.
+The function g takes the int i, and panics if i is greater than 3,
+or else it calls itself with the argument i+1.
+The function f defers a function that calls recover and prints the recovered
+value (if it is non-nil).
+Try to picture what the output of this program might be before reading on.
The program will output:
@@ -151,7 +184,10 @@
-If we remove the deferred function from f the panic is not recovered and reaches the top of the goroutine's call stack, terminating the program. This modified program will output:
+If we remove the deferred function from f the panic is not recovered and
+reaches the top of the goroutine's call stack,
+terminating the program.
+This modified program will output:
Calling g.
@@ -171,9 +207,17 @@
-For a real-world example of *panic* and *recover*, see the [[https://golang.org/pkg/encoding/json/][json package]] from the Go standard library. It encodes an interface with a set of recursive functions. If an error occurs when traversing the value, panic is called to unwind the stack to the top-level function call, which recovers from the panic and returns an appropriate error value (see the 'error' and 'marshal' methods of the encodeState type in [[https://golang.org/src/pkg/encoding/json/encode.go][encode.go]]).
+For a real-world example of *panic* and *recover*,
+see the [[https://golang.org/pkg/encoding/json/][json package]] from the
+Go standard library.
+It encodes an interface with a set of recursive functions.
+If an error occurs when traversing the value,
+panic is called to unwind the stack to the top-level function call,
+which recovers from the panic and returns an appropriate error value (see
+the 'error' and 'marshal' methods of the encodeState type in [[https://golang.org/src/pkg/encoding/json/encode.go][encode.go]]).
-The convention in the Go libraries is that even when a package uses panic internally, its external API still presents explicit error return values.
+The convention in the Go libraries is that even when a package uses panic internally,
+its external API still presents explicit error return values.
Other uses of *defer* (beyond the file.Close example given earlier) include releasing a mutex:
@@ -194,4 +238,7 @@
and more.
-In summary, the defer statement (with or without panic and recover) provides an unusual and powerful mechanism for control flow. It can be used to model a number of features implemented by special-purpose structures in other programming languages. Try it out.
+In summary, the defer statement (with or without panic and recover) provides
+an unusual and powerful mechanism for control flow.
+It can be used to model a number of features implemented by special-purpose
+structures in other programming languages. Try it out.
diff --git a/content/error-handling-and-go.article b/content/error-handling-and-go.article
index 95aed00..07d84d5 100644
--- a/content/error-handling-and-go.article
+++ b/content/error-handling-and-go.article
@@ -6,11 +6,15 @@
* Introduction
-If you have written any Go code you have probably encountered the built-in `error` type. Go code uses `error` values to indicate an abnormal state. For example, the `os.Open` function returns a non-nil `error` value when it fails to open a file.
+If you have written any Go code you have probably encountered the built-in `error` type.
+Go code uses `error` values to indicate an abnormal state.
+For example, the `os.Open` function returns a non-nil `error` value when
+it fails to open a file.
func Open(name string) (file *File, err error)
-The following code uses `os.Open` to open a file. If an error occurs it calls `log.Fatal` to print the error message and stop.
+The following code uses `os.Open` to open a file.
+If an error occurs it calls `log.Fatal` to print the error message and stop.
f, err := os.Open("filename.ext")
if err != nil {
@@ -18,19 +22,26 @@
}
// do something with the open *File f
-You can get a lot done in Go knowing just this about the `error` type, but in this article we'll take a closer look at `error` and discuss some good practices for error handling in Go.
+You can get a lot done in Go knowing just this about the `error` type,
+but in this article we'll take a closer look at `error` and discuss some
+good practices for error handling in Go.
* The error type
-The `error` type is an interface type. An `error` variable represents any value that can describe itself as a string. Here is the interface's declaration:
+The `error` type is an interface type. An `error` variable represents any
+value that can describe itself as a string.
+Here is the interface's declaration:
type error interface {
Error() string
}
-The `error` type, as with all built in types, is [[https://golang.org/doc/go_spec.html#Predeclared_identifiers][predeclared]] in the [[https://golang.org/doc/go_spec.html#Blocks][universe block]].
+The `error` type, as with all built in types,
+is [[https://golang.org/doc/go_spec.html#Predeclared_identifiers][predeclared]]
+in the [[https://golang.org/doc/go_spec.html#Blocks][universe block]].
-The most commonly-used `error` implementation is the [[https://golang.org/pkg/errors/][errors]] package's unexported `errorString` type.
+The most commonly-used `error` implementation is the [[https://golang.org/pkg/errors/][errors]]
+package's unexported `errorString` type.
// errorString is a trivial implementation of error.
type errorString struct {
@@ -41,7 +52,9 @@
return e.s
}
-You can construct one of these values with the `errors.New` function. It takes a string that it converts to an `errors.errorString` and returns as an `error` value.
+You can construct one of these values with the `errors.New` function.
+It takes a string that it converts to an `errors.errorString` and returns
+as an `error` value.
// New returns an error that formats as the given text.
func New(text string) error {
@@ -57,7 +70,11 @@
// implementation
}
-A caller passing a negative argument to `Sqrt` receives a non-nil `error` value (whose concrete representation is an `errors.errorString` value). The caller can access the error string ("math: square root of...") by calling the `error`'s `Error` method, or by just printing it:
+A caller passing a negative argument to `Sqrt` receives a non-nil `error`
+value (whose concrete representation is an `errors.errorString` value).
+The caller can access the error string ("math:
+square root of...") by calling the `error`'s `Error` method,
+or by just printing it:
f, err := Sqrt(-1)
if err != nil {
@@ -66,17 +83,27 @@
The [[https://golang.org/pkg/fmt/][fmt]] package formats an `error` value by calling its `Error()`string` method.
-It is the error implementation's responsibility to summarize the context. The error returned by `os.Open` formats as "open /etc/passwd: permission denied," not just "permission denied." The error returned by our `Sqrt` is missing information about the invalid argument.
+It is the error implementation's responsibility to summarize the context.
+The error returned by `os.Open` formats as "open /etc/passwd:
+permission denied," not just "permission denied." The error returned by
+our `Sqrt` is missing information about the invalid argument.
-To add that information, a useful function is the `fmt` package's `Errorf`. It formats a string according to `Printf`'s rules and returns it as an `error` created by `errors.New`.
+To add that information, a useful function is the `fmt` package's `Errorf`.
+It formats a string according to `Printf`'s rules and returns it as an `error`
+created by `errors.New`.
if f < 0 {
return 0, fmt.Errorf("math: square root of negative number %g", f)
}
-In many cases `fmt.Errorf` is good enough, but since `error` is an interface, you can use arbitrary data structures as error values, to allow callers to inspect the details of the error.
+In many cases `fmt.Errorf` is good enough,
+but since `error` is an interface, you can use arbitrary data structures as error values,
+to allow callers to inspect the details of the error.
-For instance, our hypothetical callers might want to recover the invalid argument passed to `Sqrt`. We can enable that by defining a new error implementation instead of using `errors.errorString`:
+For instance, our hypothetical callers might want to recover the invalid
+argument passed to `Sqrt`.
+We can enable that by defining a new error implementation instead of using
+`errors.errorString`:
type NegativeSqrtError float64
@@ -84,9 +111,14 @@
return fmt.Sprintf("math: square root of negative number %g", float64(f))
}
-A sophisticated caller can then use a [[https://golang.org/doc/go_spec.html#Type_assertions][type assertion]] to check for a `NegativeSqrtError` and handle it specially, while callers that just pass the error to `fmt.Println` or `log.Fatal` will see no change in behavior.
+A sophisticated caller can then use a [[https://golang.org/doc/go_spec.html#Type_assertions][type assertion]]
+to check for a `NegativeSqrtError` and handle it specially,
+while callers that just pass the error to `fmt.Println` or `log.Fatal` will
+see no change in behavior.
-As another example, the [[https://golang.org/pkg/encoding/json/][json]] package specifies a `SyntaxError` type that the `json.Decode` function returns when it encounters a syntax error parsing a JSON blob.
+As another example, the [[https://golang.org/pkg/encoding/json/][json]]
+package specifies a `SyntaxError` type that the `json.Decode` function returns
+when it encounters a syntax error parsing a JSON blob.
type SyntaxError struct {
msg string // description of error
@@ -95,7 +127,8 @@
func (e *SyntaxError) Error() string { return e.msg }
-The `Offset` field isn't even shown in the default formatting of the error, but callers can use it to add file and line information to their error messages:
+The `Offset` field isn't even shown in the default formatting of the error,
+but callers can use it to add file and line information to their error messages:
if err := dec.Decode(&val); err != nil {
if serr, ok := err.(*json.SyntaxError); ok {
@@ -105,9 +138,14 @@
return err
}
-(This is a slightly simplified version of some [[https://github.com/camlistore/go4/blob/03efcb870d84809319ea509714dd6d19a1498483/jsonconfig/eval.go#L123-L135][actual code]] from the [[http://camlistore.org][Camlistore]] project.)
+(This is a slightly simplified version of some [[https://github.com/camlistore/go4/blob/03efcb870d84809319ea509714dd6d19a1498483/jsonconfig/eval.go#L123-L135][actual code]]
+from the [[http://camlistore.org][Camlistore]] project.)
-The `error` interface requires only a `Error` method; specific error implementations might have additional methods. For instance, the [[https://golang.org/pkg/net/][net]] package returns errors of type `error`, following the usual convention, but some of the error implementations have additional methods defined by the `net.Error` interface:
+The `error` interface requires only a `Error` method;
+specific error implementations might have additional methods.
+For instance, the [[https://golang.org/pkg/net/][net]] package returns errors of type `error`,
+following the usual convention, but some of the error implementations have
+additional methods defined by the `net.Error` interface:
package net
@@ -117,7 +155,10 @@
Temporary() bool // Is the error temporary?
}
-Client code can test for a `net.Error` with a type assertion and then distinguish transient network errors from permanent ones. For instance, a web crawler might sleep and retry when it encounters a temporary error and give up otherwise.
+Client code can test for a `net.Error` with a type assertion and then distinguish
+transient network errors from permanent ones.
+For instance, a web crawler might sleep and retry when it encounters a temporary
+error and give up otherwise.
if nerr, ok := err.(net.Error); ok && nerr.Temporary() {
time.Sleep(1e9)
@@ -129,9 +170,15 @@
* Simplifying repetitive error handling
-In Go, error handling is important. The language's design and conventions encourage you to explicitly check for errors where they occur (as distinct from the convention in other languages of throwing exceptions and sometimes catching them). In some cases this makes Go code verbose, but fortunately there are some techniques you can use to minimize repetitive error handling.
+In Go, error handling is important. The language's design and conventions
+encourage you to explicitly check for errors where they occur (as distinct
+from the convention in other languages of throwing exceptions and sometimes catching them).
+In some cases this makes Go code verbose,
+but fortunately there are some techniques you can use to minimize repetitive error handling.
-Consider an [[https://cloud.google.com/appengine/docs/go/][App Engine]] application with an HTTP handler that retrieves a record from the datastore and formats it with a template.
+Consider an [[https://cloud.google.com/appengine/docs/go/][App Engine]]
+application with an HTTP handler that retrieves a record from the datastore
+and formats it with a template.
func init() {
http.HandleFunc("/view", viewRecord)
@@ -150,7 +197,13 @@
}
}
-This function handles errors returned by the `datastore.Get` function and `viewTemplate`'s `Execute` method. In both cases, it presents a simple error message to the user with the HTTP status code 500 ("Internal Server Error"). This looks like a manageable amount of code, but add some more HTTP handlers and you quickly end up with many copies of identical error handling code.
+This function handles errors returned by the `datastore.Get` function and
+`viewTemplate`'s `Execute` method.
+In both cases, it presents a simple error message to the user with the HTTP
+status code 500 ("Internal Server Error").
+This looks like a manageable amount of code,
+but add some more HTTP handlers and you quickly end up with many copies
+of identical error handling code.
To reduce the repetition we can define our own HTTP `appHandler` type that includes an `error` return value:
@@ -168,7 +221,11 @@
return viewTemplate.Execute(w, record)
}
-This is simpler than the original version, but the [[https://golang.org/pkg/net/http/][http]] package doesn't understand functions that return `error`. To fix this we can implement the `http.Handler` interface's `ServeHTTP` method on `appHandler`:
+This is simpler than the original version,
+but the [[https://golang.org/pkg/net/http/][http]] package doesn't understand
+functions that return `error`.
+To fix this we can implement the `http.Handler` interface's `ServeHTTP`
+method on `appHandler`:
func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if err := fn(w, r); err != nil {
@@ -176,15 +233,25 @@
}
}
-The `ServeHTTP` method calls the `appHandler` function and displays the returned error (if any) to the user. Notice that the method's receiver, `fn`, is a function. (Go can do that!) The method invokes the function by calling the receiver in the expression `fn(w,`r)`.
+The `ServeHTTP` method calls the `appHandler` function and displays the
+returned error (if any) to the user.
+Notice that the method's receiver, `fn`, is a function.
+(Go can do that!) The method invokes the function by calling the receiver
+in the expression `fn(w,`r)`.
-Now when registering `viewRecord` with the http package we use the `Handle` function (instead of `HandleFunc`) as `appHandler` is an `http.Handler` (not an `http.HandlerFunc`).
+Now when registering `viewRecord` with the http package we use the `Handle`
+function (instead of `HandleFunc`) as `appHandler` is an `http.Handler`
+(not an `http.HandlerFunc`).
func init() {
http.Handle("/view", appHandler(viewRecord))
}
-With this basic error handling infrastructure in place, we can make it more user friendly. Rather than just displaying the error string, it would be better to give the user a simple error message with an appropriate HTTP status code, while logging the full error to the App Engine developer console for debugging purposes.
+With this basic error handling infrastructure in place,
+we can make it more user friendly.
+Rather than just displaying the error string,
+it would be better to give the user a simple error message with an appropriate HTTP status code,
+while logging the full error to the App Engine developer console for debugging purposes.
To do this we create an `appError` struct containing an `error` and some other fields:
@@ -198,9 +265,14 @@
type appHandler func(http.ResponseWriter, *http.Request) *appError
-(It's usually a mistake to pass back the concrete type of an error rather than `error`, for reasons discussed in [[https://golang.org/doc/go_faq.html#nil_error][the Go FAQ]], but it's the right thing to do here because `ServeHTTP` is the only place that sees the value and uses its contents.)
+(It's usually a mistake to pass back the concrete type of an error rather than `error`,
+for reasons discussed in [[https://golang.org/doc/go_faq.html#nil_error][the Go FAQ]],
+but it's the right thing to do here because `ServeHTTP` is the only place
+that sees the value and uses its contents.)
-And make `appHandler`'s `ServeHTTP` method display the `appError`'s `Message` to the user with the correct HTTP status `Code` and log the full `Error` to the developer console:
+And make `appHandler`'s `ServeHTTP` method display the `appError`'s `Message`
+to the user with the correct HTTP status `Code` and log the full `Error`
+to the developer console:
func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if e := fn(w, r); e != nil { // e is *appError, not os.Error.
@@ -210,7 +282,8 @@
}
}
-Finally, we update `viewRecord` to the new function signature and have it return more context when it encounters an error:
+Finally, we update `viewRecord` to the new function signature and have it
+return more context when it encounters an error:
func viewRecord(w http.ResponseWriter, r *http.Request) *appError {
c := appengine.NewContext(r)
@@ -225,7 +298,9 @@
return nil
}
-This version of `viewRecord` is the same length as the original, but now each of those lines has specific meaning and we are providing a friendlier user experience.
+This version of `viewRecord` is the same length as the original,
+but now each of those lines has specific meaning and we are providing a
+friendlier user experience.
It doesn't end there; we can further improve the error handling in our application. Some ideas:
@@ -235,8 +310,15 @@
- write a constructor function for `appError` that stores the stack trace for easier debugging,
-- recover from panics inside the `appHandler`, logging the error to the console as "Critical," while telling the user "a serious error has occurred." This is a nice touch to avoid exposing the user to inscrutable error messages caused by programming errors. See the [[https://golang.org/doc/articles/defer_panic_recover.html][Defer, Panic, and Recover]] article for more details.
+- recover from panics inside the `appHandler`,
+ logging the error to the console as "Critical," while telling the user "a
+ serious error has occurred." This is a nice touch to avoid exposing the
+ user to inscrutable error messages caused by programming errors.
+ See the [[https://golang.org/doc/articles/defer_panic_recover.html][Defer, Panic, and Recover]]
+ article for more details.
* Conclusion
-Proper error handling is an essential requirement of good software. By employing the techniques described in this post you should be able to write more reliable and succinct Go code.
+Proper error handling is an essential requirement of good software.
+By employing the techniques described in this post you should be able to
+write more reliable and succinct Go code.
diff --git a/content/first-class-functions-in-go-and-new-go.article b/content/first-class-functions-in-go-and-new-go.article
index 1458b83..29cab3a 100644
--- a/content/first-class-functions-in-go-and-new-go.article
+++ b/content/first-class-functions-in-go-and-new-go.article
@@ -6,6 +6,12 @@
* Introduction
-Programmers new to Go are often surprised by its support for function types, functions as values, and closures. The [[https://golang.org/doc/codewalk/functions/][First Class Functions in Go]] code walk demonstrates these features with a simulation of the dice game [[http://en.wikipedia.org/wiki/Pig_(dice)][Pig]]. It is a pretty program that uses the language to great effect, and a fun read for Go beginners and veterans alike.
+Programmers new to Go are often surprised by its support for function types,
+functions as values, and closures.
+The [[https://golang.org/doc/codewalk/functions/][First Class Functions in Go]]
+code walk demonstrates these features with a simulation of the dice game
+[[http://en.wikipedia.org/wiki/Pig_(dice)][Pig]].
+It is a pretty program that uses the language to great effect,
+and a fun read for Go beginners and veterans alike.
More resources are available at [[https://golang.org/doc/docs.html][golang.org]].
diff --git a/content/from-zero-to-go-launching-on-google.article b/content/from-zero-to-go-launching-on-google.article
index 0d95ef9..fc47fd9 100644
--- a/content/from-zero-to-go-launching-on-google.article
+++ b/content/from-zero-to-go-launching-on-google.article
@@ -8,21 +8,52 @@
_This_article_was_written_by_Reinaldo_Aguiar,_a_software_engineer_from_the_Search_team_at_Google._He_shares_his_experience_developing_his_first_Go_program_and_launching_it_to_an_audience_of_millions_-_all_in_one_day!_
-I was recently given the opportunity to collaborate on a small but highly visible "20% project": the [[http://www.google.com/logos/2011/thanksgiving.html][Thanksgiving 2011 Google Doodle]]. The doodle features a turkey produced by randomly combining different styles of head, wings, feathers and legs. The user can customize it by clicking on the different parts of the turkey. This interactivity is implemented in the browser by a combination of JavaScript, CSS and of course HTML, creating turkeys on the fly.
+I was recently given the opportunity to collaborate on a small but highly
+visible "20% project":
+the [[http://www.google.com/logos/2011/thanksgiving.html][Thanksgiving 2011 Google Doodle]].
+The doodle features a turkey produced by randomly combining different styles of head,
+wings, feathers and legs.
+The user can customize it by clicking on the different parts of the turkey.
+This interactivity is implemented in the browser by a combination of JavaScript,
+CSS and of course HTML, creating turkeys on the fly.
.image from-zero-to-go-launching-on-google_image00.png
-Once the user has created a personalized turkey it can be shared with friends and family by posting to Google+. Clicking a "Share" button (not pictured here) creates in the user's Google+ stream a post containing a snapshot of the turkey. The snapshot is a single image that matches the turkey the user created.
+Once the user has created a personalized turkey it can be shared with friends
+and family by posting to Google+.
+Clicking a "Share" button (not pictured here) creates in the user's Google+
+stream a post containing a snapshot of the turkey.
+The snapshot is a single image that matches the turkey the user created.
-With 13 alternatives for each of 8 parts of the turkey (heads, pairs of legs, distinct feathers, etc.) there are more than than 800 million possible snapshot images that could be generated. To pre-compute them all is clearly infeasible. Instead, we must generate the snapshots on the fly. Combining that problem with a need for immediate scalability and high availability, the choice of platform is obvious: Google App Engine!
+With 13 alternatives for each of 8 parts of the turkey (heads,
+pairs of legs, distinct feathers, etc.) there are more than than 800 million
+possible snapshot images that could be generated.
+To pre-compute them all is clearly infeasible.
+Instead, we must generate the snapshots on the fly.
+Combining that problem with a need for immediate scalability and high availability,
+the choice of platform is obvious: Google App Engine!
-The next thing we needed to decide was which App Engine runtime to use. Image manipulation tasks are CPU-bound, so performance is the deciding factor in this case.
+The next thing we needed to decide was which App Engine runtime to use.
+Image manipulation tasks are CPU-bound, so performance is the deciding factor in this case.
-To make an informed decision we ran a test. We quickly prepared a couple of equivalent demo apps for the new [[http://code.google.com/appengine/docs/python/python27/newin27.html][Python 2.7 runtime]] (which provides [[http://www.pythonware.com/products/pil/][PIL]], a C-based imaging library) and the Go runtime. Each app generates an image composed of several small images, encodes the image as a JPEG, and sends the JPEG data as the HTTP response. The Python 2.7 app served requests with a median latency of 65 milliseconds, while the Go app ran with a median latency of just 32 milliseconds.
+To make an informed decision we ran a test.
+We quickly prepared a couple of equivalent demo apps for the new [[http://code.google.com/appengine/docs/python/python27/newin27.html][Python 2.7 runtime]]
+(which provides [[http://www.pythonware.com/products/pil/][PIL]],
+a C-based imaging library) and the Go runtime.
+Each app generates an image composed of several small images,
+encodes the image as a JPEG, and sends the JPEG data as the HTTP response.
+The Python 2.7 app served requests with a median latency of 65 milliseconds,
+while the Go app ran with a median latency of just 32 milliseconds.
This problem therefore seemed the perfect opportunity to try the experimental Go runtime.
-I had no previous experience with Go and the timeline was tight: two days to be production ready. This was intimidating, but I saw it as an opportunity to test Go from a different, often overlooked angle: development velocity. How fast can a person with no Go experience pick it up and build something that performs and scales?
+I had no previous experience with Go and the timeline was tight:
+two days to be production ready.
+This was intimidating, but I saw it as an opportunity to test Go from a different,
+often overlooked angle:
+development velocity.
+How fast can a person with no Go experience pick it up and build something
+that performs and scales?
* Design
@@ -32,19 +63,29 @@
.image from-zero-to-go-launching-on-google_image01.jpg
-A valid request URL might look like this: `http://google-turkey.appspot.com/thumb/20332620][http://google-turkey.appspot.com/thumb/20332620`
+A valid request URL might look like this:
+`http://google-turkey.appspot.com/thumb/20332620][http://google-turkey.appspot.com/thumb/20332620`
-The alphanumeric string that follows "/thumb/" indicates (in hexadecimal) which choice to draw for each layout element, as illustrated by this image:
+The alphanumeric string that follows "/thumb/" indicates (in hexadecimal)
+which choice to draw for each layout element,
+as illustrated by this image:
.image from-zero-to-go-launching-on-google_image03.png
-The program's request handler parses the URL to determine which element is selected for each component, draws the appropriate images on top of the background image, and serves the result as a JPEG.
+The program's request handler parses the URL to determine which element
+is selected for each component,
+draws the appropriate images on top of the background image,
+and serves the result as a JPEG.
-If an error occurs, a default image is served. There's no point serving an error page because the user will never see it - the browser is almost certainly loading this URL into an image tag.
+If an error occurs, a default image is served.
+There's no point serving an error page because the user will never see it -
+the browser is almost certainly loading this URL into an image tag.
* Implementation
-In the package scope we declare some data structures to describe the elements of the turkey, the location of the corresponding images, and where they should be drawn on the background image.
+In the package scope we declare some data structures to describe the elements of the turkey,
+the location of the corresponding images,
+and where they should be drawn on the background image.
var (
// dirs maps each layout element to its location on disk.
@@ -77,9 +118,12 @@
}
)
-The geometry of the points above was calculated by measuring the actual location and size of each layout element within the image.
+The geometry of the points above was calculated by measuring the actual
+location and size of each layout element within the image.
-Loading the images from disk on each request would be wasteful repetition, so we load all 106 images (13 * 8 elements + 1 background + 1 default) into global variables upon receipt of the first request.
+Loading the images from disk on each request would be wasteful repetition,
+so we load all 106 images (13 * 8 elements + 1 background + 1 default) into
+global variables upon receipt of the first request.
var (
// elements maps each layout element to its images.
@@ -123,7 +167,8 @@
- Return the image to user by writing the JPEG directly to the HTTP response writer.
-Should any error occur, we serve the defaultImage to the user and log the error to the App Engine dashboard for later analysis.
+Should any error occur, we serve the defaultImage to the user and log the
+error to the App Engine dashboard for later analysis.
Here's the code for the request handler with explanatory comments:
@@ -181,23 +226,48 @@
jpeg.Encode(w, m, &imageQuality)
}
-For brevity, I've omitted several helper functions from these code listings. See the [[http://code.google.com/p/go-thanksgiving/source/browse/][source code]] for the full scoop.
+For brevity, I've omitted several helper functions from these code listings.
+See the [[http://code.google.com/p/go-thanksgiving/source/browse/][source code]] for the full scoop.
* Performance
.image from-zero-to-go-launching-on-google_image02.png
-This chart - taken directly from the App Engine dashboard - shows average request latency during launch. As you can see, even under load it never exceeds 60 ms, with a median latency of 32 milliseconds. This is wicked fast, considering that our request handler is doing image manipulation and encoding on the fly.
+This chart - taken directly from the App Engine dashboard - shows average
+request latency during launch.
+As you can see, even under load it never exceeds 60 ms,
+with a median latency of 32 milliseconds.
+This is wicked fast, considering that our request handler is doing image
+manipulation and encoding on the fly.
* Conclusions
-I found Go's syntax to be intuitive, simple and clean. I have worked a lot with interpreted languages in the past, and although Go is instead a statically typed and compiled language, writing this app felt more like working with a dynamic, interpreted language.
+I found Go's syntax to be intuitive, simple and clean.
+I have worked a lot with interpreted languages in the past,
+and although Go is instead a statically typed and compiled language,
+writing this app felt more like working with a dynamic,
+interpreted language.
-The development server provided with the [[http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Go][SDK]] quickly recompiles the program after any change, so I could iterate as fast as I would with an interpreted language. It's dead simple, too - it took less than a minute to set up my development environment.
+The development server provided with the [[http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Go][SDK]]
+quickly recompiles the program after any change,
+so I could iterate as fast as I would with an interpreted language.
+It's dead simple, too - it took less than a minute to set up my development environment.
-Go's great documentation also helped me put this together fast. The docs are generated from the source code, so each function's documentation links directly to the associated source code. This not only allows the developer to understand very quickly what a particular function does but also encourages the developer to dig into the package implementation, making it easier to learn good style and conventions.
+Go's great documentation also helped me put this together fast.
+The docs are generated from the source code,
+so each function's documentation links directly to the associated source code.
+This not only allows the developer to understand very quickly what a particular
+function does but also encourages the developer to dig into the package implementation,
+making it easier to learn good style and conventions.
-In writing this application I used just three resources: App Engine's [[http://code.google.com/appengine/docs/go/gettingstarted/helloworld.html][Hello World Go example]], [[https://golang.org/pkg/][the Go packages documentation]], and [[https://blog.golang.org/2011/09/go-imagedraw-package.html][a blog post showcasing the Draw package]]. Thanks to the rapid iteration made possible by the development server and the language itself, I was able to pick up the language and build a super fast, production ready, doodle generator in less than 24 hours.
+In writing this application I used just three resources:
+App Engine's [[http://code.google.com/appengine/docs/go/gettingstarted/helloworld.html][Hello World Go example]],
+[[https://golang.org/pkg/][the Go packages documentation]],
+and [[https://blog.golang.org/2011/09/go-imagedraw-package.html][a blog post showcasing the Draw package]].
+Thanks to the rapid iteration made possible by the development server and
+the language itself,
+I was able to pick up the language and build a super fast,
+production ready, doodle generator in less than 24 hours.
Download the full app source code (including images) at [[http://code.google.com/p/go-thanksgiving/source/browse/][the Google Code project]].
diff --git a/content/gccgo-in-gcc-471.article b/content/gccgo-in-gcc-471.article
index d239f4b..6c90a93 100644
--- a/content/gccgo-in-gcc-471.article
+++ b/content/gccgo-in-gcc-471.article
@@ -6,20 +6,64 @@
* Introduction
-The Go language has always been defined by a [[https://golang.org/ref/spec][spec]], not an implementation. The Go team has written two different compilers that implement that spec: gc and gccgo. Having two different implementations helps ensure that the spec is complete and correct: when the compilers disagree, we fix the spec, and change one or both compilers accordingly. Gc is the original compiler, and the go tool uses it by default. Gccgo is a different implementation with a different focus, and in this post we’ll take a closer look at it.
+The Go language has always been defined by a [[https://golang.org/ref/spec][spec]],
+not an implementation.
+The Go team has written two different compilers that implement that spec: gc and gccgo.
+Having two different implementations helps ensure that the spec is complete and correct:
+when the compilers disagree, we fix the spec,
+and change one or both compilers accordingly.
+Gc is the original compiler, and the go tool uses it by default.
+Gccgo is a different implementation with a different focus,
+and in this post we’ll take a closer look at it.
-Gccgo is distributed as part of GCC, the GNU Compiler Collection. GCC supports several different frontends for different languages; gccgo is a Go frontend connected to the GCC backend. The Go frontend is separate from the GCC project and is designed to be able to connect to other compiler backends, but currently only supports GCC.
+Gccgo is distributed as part of GCC, the GNU Compiler Collection.
+GCC supports several different frontends for different languages;
+gccgo is a Go frontend connected to the GCC backend.
+The Go frontend is separate from the GCC project and is designed to be able
+to connect to other compiler backends,
+but currently only supports GCC.
-Compared to gc, gccgo is slower to compile code but supports more powerful optimizations, so a CPU-bound program built by gccgo will usually run faster. All the optimizations implemented in GCC over the years are available, including inlining, loop optimizations, vectorization, instruction scheduling, and more. While it does not always produce better code, in some cases programs compiled with gccgo can run 30% faster.
+Compared to gc, gccgo is slower to compile code but supports more powerful optimizations,
+so a CPU-bound program built by gccgo will usually run faster.
+All the optimizations implemented in GCC over the years are available,
+including inlining, loop optimizations, vectorization,
+instruction scheduling, and more.
+While it does not always produce better code,
+in some cases programs compiled with gccgo can run 30% faster.
-The gc compiler supports only the most popular processors: x86 (32-bit and 64-bit) and ARM. Gccgo, however, supports all the processors that GCC supports. Not all those processors have been thoroughly tested for gccgo, but many have, including x86 (32-bit and 64-bit), SPARC, MIPS, PowerPC and even Alpha. Gccgo has also been tested on operating systems that the gc compiler does not support, notably Solaris.
+The gc compiler supports only the most popular processors:
+x86 (32-bit and 64-bit) and ARM.
+Gccgo, however, supports all the processors that GCC supports.
+Not all those processors have been thoroughly tested for gccgo,
+but many have, including x86 (32-bit and 64-bit),
+SPARC, MIPS, PowerPC and even Alpha.
+Gccgo has also been tested on operating systems that the gc compiler does
+not support, notably Solaris.
-Gccgo provides the standard, complete Go library. Many of the core features of the Go runtime are the same in both gccgo and gc, including the goroutine scheduler, channels, the memory allocator, and the garbage collector. Gccgo supports splitting goroutine stacks as the gc compiler does, but currently only on x86 (32-bit or 64-bit) and only when using the gold linker (on other processors, each goroutine will have a large stack, and a deep series of function calls may run past the end of the stack and crash the program).
+Gccgo provides the standard, complete Go library.
+Many of the core features of the Go runtime are the same in both gccgo and gc,
+including the goroutine scheduler, channels,
+the memory allocator, and the garbage collector.
+Gccgo supports splitting goroutine stacks as the gc compiler does,
+but currently only on x86 (32-bit or 64-bit) and only when using the gold
+linker (on other processors,
+each goroutine will have a large stack, and a deep series of function calls
+may run past the end of the stack and crash the program).
-Gccgo distributions do not yet include a version of the go command. However, if you install the go command from a standard Go release, it already supports gccgo via the `-compiler` option: go build `-compiler`gccgo`myprog`. The tools used for calls between Go and C/C++, cgo and SWIG, also support gccgo.
+Gccgo distributions do not yet include a version of the go command.
+However, if you install the go command from a standard Go release,
+it already supports gccgo via the `-compiler` option:
+go build `-compiler`gccgo`myprog`.
+The tools used for calls between Go and C/C++,
+cgo and SWIG, also support gccgo.
We have put the Go frontend under the same BSD license as the rest of the Go
tools. You can download the source code for the frontend at the
-[[https://github.com/golang/gofrontend][gofrontend project]]. Note that when the Go frontend is linked with the GCC backend to make gccgo, GCC’s GPL license takes precedence.
+[[https://github.com/golang/gofrontend][gofrontend project]].
+Note that when the Go frontend is linked with the GCC backend to make gccgo,
+GCC’s GPL license takes precedence.
-The latest release of GCC, 4.7.1, includes gccgo with support for Go 1. If you need better performance for CPU-bound Go programs, or you need to support processors or operating systems that the gc compiler does not support, gccgo might be the answer.
+The latest release of GCC, 4.7.1, includes gccgo with support for Go 1.
+If you need better performance for CPU-bound Go programs,
+or you need to support processors or operating systems that the gc compiler does not support,
+gccgo might be the answer.
diff --git a/content/gcdk-whats-new-in-march-2019.article b/content/gcdk-whats-new-in-march-2019.article
index b67a096..29bff99 100644
--- a/content/gcdk-whats-new-in-march-2019.article
+++ b/content/gcdk-whats-new-in-march-2019.article
@@ -5,11 +5,21 @@
* Introduction
-Last July, we [[https://blog.golang.org/go-cloud][introduced]] the [[https://gocloud.dev][Go Cloud Development Kit]] (previously referred to as simply "Go Cloud"), an open source project building libraries and tools to improve the experience of developing for the cloud with Go. We've made a lot of progress since then -- thank you to early contributors! We look forward to growing the Go CDK community of users and contributors, and are excited to work closely with early adopters.
+Last July, we [[https://blog.golang.org/go-cloud][introduced]] the [[https://gocloud.dev][Go Cloud Development Kit]]
+(previously referred to as simply "Go Cloud"),
+an open source project building libraries and tools to improve the experience
+of developing for the cloud with Go.
+We've made a lot of progress since then -- thank you to early contributors!
+We look forward to growing the Go CDK community of users and contributors,
+and are excited to work closely with early adopters.
* Portable APIs
-Our first initiative is a set of portable APIs for common cloud services. You write your application using these APIs, and then deploy it on any combination of providers, including AWS, GCP, Azure, on-premise, or on a single developer machine for testing. Additional providers can be added by implementing an interface.
+Our first initiative is a set of portable APIs for common cloud services.
+You write your application using these APIs,
+and then deploy it on any combination of providers,
+including AWS, GCP, Azure, on-premise, or on a single developer machine for testing.
+Additional providers can be added by implementing an interface.
These portable APIs are a great fit if any of the following are true:
@@ -18,20 +28,39 @@
- You want portability across multiple clouds.
- You are creating a new Go application that will use cloud services.
-Unlike traditional approaches where you would need to write new application code for each cloud provider, with the Go CDK you write your application code once using our portable APIs to access the set of services listed below. Then, you can run your application on any supported cloud with minimal config changes.
+Unlike traditional approaches where you would need to write new application
+code for each cloud provider,
+with the Go CDK you write your application code once using our portable
+APIs to access the set of services listed below.
+Then, you can run your application on any supported cloud with minimal config changes.
Our current set of APIs includes:
-- [[https://godoc.org/gocloud.dev/blob][blob]], for persistence of blob data. Supported providers include: AWS S3, Google Cloud Storage (GCS), Azure Storage, the filesystem, and in-memory.
-- [[https://godoc.org/gocloud.dev/pubsub][pubsub]] for publishing/subscribing of messages to a topic. Supported providers include: Amazon SNS/SQS, Google Pub/Sub, Azure Service Bus, RabbitMQ, and in-memory.
-- [[https://godoc.org/gocloud.dev/runtimevar][runtimevar]], for watching external configuration variables. Supported providers include AWS Parameter Store, Google Runtime Configurator, etcd, and the filesystem.
-- [[https://godoc.org/gocloud.dev/secrets][secrets]], for encryption/decryption. Supported providers include AWS KMS, GCP KMS, Hashicorp Vault, and local symmetric keys.
+- [[https://godoc.org/gocloud.dev/blob][blob]],
+ for persistence of blob data.
+ Supported providers include: AWS S3, Google Cloud Storage (GCS),
+ Azure Storage, the filesystem, and in-memory.
+- [[https://godoc.org/gocloud.dev/pubsub][pubsub]] for publishing/subscribing
+ of messages to a topic.
+ Supported providers include: Amazon SNS/SQS,
+ Google Pub/Sub, Azure Service Bus, RabbitMQ, and in-memory.
+- [[https://godoc.org/gocloud.dev/runtimevar][runtimevar]],
+ for watching external configuration variables.
+ Supported providers include AWS Parameter Store,
+ Google Runtime Configurator, etcd, and the filesystem.
+- [[https://godoc.org/gocloud.dev/secrets][secrets]],
+ for encryption/decryption.
+ Supported providers include AWS KMS, GCP KMS,
+ Hashicorp Vault, and local symmetric keys.
- Helpers for connecting to cloud SQL providers. Supported providers include AWS RDS and Google Cloud SQL.
- We are also working on a document storage API (e.g. MongoDB, DynamoDB, Firestore).
* Feedback
-We hope you're as excited about the Go CDK as we are -- check out our [[https://godoc.org/gocloud.dev][godoc]], walk through our [[https://github.com/google/go-cloud/tree/master/samples/tutorial][tutorial]], and use the Go CDK in your application(s). We'd love to hear your ideas for other APIs and API providers you'd like to see.
+We hope you're as excited about the Go CDK as we are -- check out our [[https://godoc.org/gocloud.dev][godoc]],
+walk through our [[https://github.com/google/go-cloud/tree/master/samples/tutorial][tutorial]],
+and use the Go CDK in your application(s).
+We'd love to hear your ideas for other APIs and API providers you'd like to see.
If you're digging into Go CDK please share your experiences with us:
diff --git a/content/getthee-to-go-meetup.article b/content/getthee-to-go-meetup.article
index d2f586a..6f12947 100644
--- a/content/getthee-to-go-meetup.article
+++ b/content/getthee-to-go-meetup.article
@@ -6,10 +6,27 @@
* Introduction
-Last week, David Symonds and I each gave talks at Sydney's Go meetup, [[http://www.meetup.com/golang-syd/][golang-syd]]. Dave spoke about [[http://talks.godoc.org/github.com/dsymonds/talks/2013-feb-golang-syd/golang-syd.slide][Go API design in the context of Protocol Buffers]], and I discussed some neat tricks in the construction of [[http://talks.godoc.org/github.com/nf/streak/talk.slide][a small command-line program]]. The presentations were short but provoked some good questions and interesting discussion. Of the 50-odd attendees, most were regular Go programmers and a fair chunk write Go code professionally. It was a fun night.
+Last week, David Symonds and I each gave talks at Sydney's Go meetup,
+[[http://www.meetup.com/golang-syd/][golang-syd]].
+Dave spoke about [[http://talks.godoc.org/github.com/dsymonds/talks/2013-feb-golang-syd/golang-syd.slide][Go API design in the context of Protocol Buffers]],
+and I discussed some neat tricks in the construction of [[http://talks.godoc.org/github.com/nf/streak/talk.slide][a small command-line program]].
+The presentations were short but provoked some good questions and interesting discussion.
+Of the 50-odd attendees, most were regular Go programmers and a fair chunk
+write Go code professionally. It was a fun night.
-It would have been great to see you there but, statistically, you're not from Sydney. Despair not, however, as there are likely some people in your area who either run a Go meetup or want to start one.
+It would have been great to see you there but,
+statistically, you're not from Sydney.
+Despair not, however, as there are likely some people in your area who either
+run a Go meetup or want to start one.
-The Go wiki lists [[https://golang.org/wiki/GoUserGroups][Go user groups]] around the world, so if there's one nearby you should consider going along to the next event.
+The Go wiki lists [[https://golang.org/wiki/GoUserGroups][Go user groups]] around the world,
+so if there's one nearby you should consider going along to the next event.
-If not, why not start your own? To gauge interest, ask around in the [[https://plus.google.com/communities/114112804251407510571][Go+ Community]] and the [[http://groups.google.com/group/golang-nuts][golang-nuts mailing list]], and take a look at this [[http://golang.meetup.com/all/][list of people]] waiting for a Go meetup in their area. Once you have a few people interested - and at least one person willing to present something - pick a venue and set a date. If you build it, they will come.
+If not, why not start your own? To gauge interest,
+ask around in the [[https://plus.google.com/communities/114112804251407510571][Go+ Community]] and
+the [[http://groups.google.com/group/golang-nuts][golang-nuts mailing list]], and
+take a look at this [[http://golang.meetup.com/all/][list of people]] waiting
+for a Go meetup in their area.
+Once you have a few people interested - and at least one person willing
+to present something - pick a venue and set a date.
+If you build it, they will come.
diff --git a/content/getting-to-know-go-community.article b/content/getting-to-know-go-community.article
index 9b51ab3..fc2db7a 100644
--- a/content/getting-to-know-go-community.article
+++ b/content/getting-to-know-go-community.article
@@ -6,9 +6,15 @@
* Introduction
-Over the past couple of years Go has attracted a lot of users and contributors, and I've had a great time meeting and talking with many of you. However, for every Gopher I know there are dozens I know nothing about. In order to address this imbalance I've prepared a survey for Go users everywhere.
+Over the past couple of years Go has attracted a lot of users and contributors,
+and I've had a great time meeting and talking with many of you.
+However, for every Gopher I know there are dozens I know nothing about.
+In order to address this imbalance I've prepared a survey for Go users everywhere.
-The survey is short. It asks about you, your involvement with Go, and and your interest in Go-related events. Among other things, this data will help myself and the rest of the Go team plan future Go events and schedule conference appearances.
+The survey is short. It asks about you, your involvement with Go,
+and and your interest in Go-related events.
+Among other things, this data will help myself and the rest of the Go team
+plan future Go events and schedule conference appearances.
Please take a minute to [[https://docs.google.com/spreadsheet/viewform?hl=en_US&formkey=dFdxOTU1Mm92VFA3eHdkekFPamJjUnc6MQ#gid=0][complete the survey now]].
diff --git a/content/gif-decoder-exercise-in-go-interfaces.article b/content/gif-decoder-exercise-in-go-interfaces.article
index 6e63817..9d58e57 100644
--- a/content/gif-decoder-exercise-in-go-interfaces.article
+++ b/content/gif-decoder-exercise-in-go-interfaces.article
@@ -6,9 +6,14 @@
* Introduction
-At the Google I/O conference in San Francisco on May 10, 2011, we announced that the Go language is now available on Google App Engine. Go is the first language to be made available on App Engine that compiles directly to machine code, which makes it a good choice for CPU-intensive tasks such as image manipulation.
+At the Google I/O conference in San Francisco on May 10,
+2011, we announced that the Go language is now available on Google App Engine.
+Go is the first language to be made available on App Engine that compiles
+directly to machine code,
+which makes it a good choice for CPU-intensive tasks such as image manipulation.
-In that vein, we demonstrated a program called [[http://moustach-io.appspot.com/][Moustachio]] that makes it easy to improve a picture such as this one:
+In that vein, we demonstrated a program called [[http://moustach-io.appspot.com/][Moustachio]]
+that makes it easy to improve a picture such as this one:
.image gif-decoder-exercise-in-go-interfaces_image00.jpg
@@ -16,29 +21,66 @@
.image gif-decoder-exercise-in-go-interfaces_image02.jpg
-All the graphical processing, including rendering the antialiased moustache, is done by a Go program running on App Engine. (The source is available at [[http://code.google.com/p/appengine-go/source/browse/example/moustachio/][the appengine-go project]].)
+All the graphical processing, including rendering the antialiased moustache,
+is done by a Go program running on App Engine.
+(The source is available at [[http://code.google.com/p/appengine-go/source/browse/example/moustachio/][the appengine-go project]].)
-Although most images on the web—at least those likely to be moustachioed—are JPEGs, there are countless other formats floating around, and it seemed reasonable for Moustachio to accept uploaded images in a few of them. JPEG and PNG decoders already existed in the Go image library, but the venerable GIF format was not represented, so we decided to write a GIF decoder in time for the announcement. That decoder contains a few pieces that demonstrate how Go's interfaces make some problems easier to solve. The rest of this blog post describes a couple of instances.
+Although most images on the web—at least those likely to be moustachioed—are JPEGs,
+there are countless other formats floating around,
+and it seemed reasonable for Moustachio to accept uploaded images in a few of them.
+JPEG and PNG decoders already existed in the Go image library,
+but the venerable GIF format was not represented,
+so we decided to write a GIF decoder in time for the announcement.
+That decoder contains a few pieces that demonstrate how Go's interfaces
+make some problems easier to solve.
+The rest of this blog post describes a couple of instances.
* The GIF format
-First, a quick tour of the GIF format. A GIF image file is _paletted_, that is, each pixel value is an index into a fixed color map that is included in the file. The GIF format dates from a time when there were usually no more than 8 bits per pixel on the display, and a color map was used to convert the limited set of values into the RGB (red, green, blue) triples needed to light the screen. (This is in contrast to a JPEG, for example, which has no color map because the encoding represents the distinct color signals separately.)
+First, a quick tour of the GIF format. A GIF image file is _paletted_,
+that is, each pixel value is an index into a fixed color map that is included in the file.
+The GIF format dates from a time when there were usually no more than 8
+bits per pixel on the display,
+and a color map was used to convert the limited set of values into the RGB (red,
+green, blue) triples needed to light the screen.
+(This is in contrast to a JPEG, for example,
+which has no color map because the encoding represents the distinct color
+signals separately.)
A GIF image can contain anywhere from 1 to 8 bits per pixel, inclusive, but 8 bits per pixel is the most common.
-Simplifying somewhat, a GIF file contains a header defining the pixel depth and image dimensions, a color map (256 RGB triples for an 8-bit image), and then the pixel data. The pixel data is stored as a one-dimensional bit stream, compressed using the LZW algorithm, which is quite effective for computer-generated graphics although not so good for photographic imagery. The compressed data is then broken into length-delimited blocks with a one-byte count (0-255) followed by that many bytes:
+Simplifying somewhat, a GIF file contains a header defining the pixel depth
+and image dimensions,
+a color map (256 RGB triples for an 8-bit image),
+and then the pixel data.
+The pixel data is stored as a one-dimensional bit stream,
+compressed using the LZW algorithm, which is quite effective for computer-generated
+graphics although not so good for photographic imagery.
+The compressed data is then broken into length-delimited blocks with a one-byte
+count (0-255) followed by that many bytes:
.image gif-decoder-exercise-in-go-interfaces_image03.gif
* Deblocking the pixel data
-To decode GIF pixel data in Go, we can use the LZW decompressor from the `compress/lzw` package. It has a NewReader function that returns an object that, as [[https://golang.org/pkg/compress/lzw/#NewReader][the documentation]] says, "satisfies reads by decompressing the data read from r":
+To decode GIF pixel data in Go, we can use the LZW decompressor from the
+`compress/lzw` package.
+It has a NewReader function that returns an object that,
+as [[https://golang.org/pkg/compress/lzw/#NewReader][the documentation]] says,
+"satisfies reads by decompressing the data read from r":
func NewReader(r io.Reader, order Order, litWidth int) io.ReadCloser
-Here `order` defines the bit-packing order and `litWidth` is the word size in bits, which for a GIF file corresponds to the pixel depth, typically 8.
+Here `order` defines the bit-packing order and `litWidth` is the word size in bits,
+which for a GIF file corresponds to the pixel depth, typically 8.
-But we can't just give `NewReader` the input file as its first argument because the decompressor needs a stream of bytes but the GIF data is a stream of blocks that must be unpacked. To address this problem, we can wrap the input `io.Reader` with some code to deblock it, and make that code again implement `Reader`. In other words, we put the deblocking code into the `Read` method of a new type, which we call `blockReader`.
+But we can't just give `NewReader` the input file as its first argument
+because the decompressor needs a stream of bytes but the GIF data is a stream
+of blocks that must be unpacked.
+To address this problem, we can wrap the input `io.Reader` with some code to deblock it,
+and make that code again implement `Reader`.
+In other words, we put the deblocking code into the `Read` method of a new type,
+which we call `blockReader`.
Here's the data structure for a `blockReader`.
@@ -48,7 +90,11 @@
tmp [256]byte // Storage for slice.
}
-The reader, `r`, will be the source of the image data, perhaps a file or HTTP connection. The `slice` and `tmp` fields will be used to manage the deblocking. Here's the `Read` method in its entirety. It's a nice example of the use of slices and arrays in Go.
+The reader, `r`, will be the source of the image data,
+perhaps a file or HTTP connection.
+The `slice` and `tmp` fields will be used to manage the deblocking.
+Here's the `Read` method in its entirety.
+It's a nice example of the use of slices and arrays in Go.
1 func (b *blockReader) Read(p []byte) (int, os.Error) {
2 if len(p) == 0 {
@@ -72,27 +118,54 @@
20 return n, nil
21 }
-Lines 2-4 are just a sanity check: if there's no place to put data, return zero. That should never happen, but it's good to be safe.
+Lines 2-4 are just a sanity check: if there's no place to put data, return zero.
+That should never happen, but it's good to be safe.
-Line 5 asks if there's data left over from a previous call by checking the length of `b.slice`. If there isn't, the slice will have length zero and we need to read the next block from `r`.
+Line 5 asks if there's data left over from a previous call by checking the
+length of `b.slice`.
+If there isn't, the slice will have length zero and we need to read the
+next block from `r`.
-A GIF block starts with a byte count, read on line 6. If the count is zero, GIF defines this to be a terminating block, so we return `EOF` on line 11.
+A GIF block starts with a byte count, read on line 6.
+If the count is zero, GIF defines this to be a terminating block,
+so we return `EOF` on line 11.
-Now we know we should read `blockLen` bytes, so we point `b.slice` to the first `blockLen` bytes of `b.tmp` and then use the helper function `io.ReadFull` to read that many bytes. That function will return an error if it can't read exactly that many bytes, which should never happen. Otherwise we have `blockLen` bytes ready to read.
+Now we know we should read `blockLen` bytes,
+so we point `b.slice` to the first `blockLen` bytes of `b.tmp` and then
+use the helper function `io.ReadFull` to read that many bytes.
+That function will return an error if it can't read exactly that many bytes,
+which should never happen.
+Otherwise we have `blockLen` bytes ready to read.
-Lines 18-19 copy the data from `b.slice` to the caller's buffer. We are implementing `Read`, not `ReadFull`, so we are allowed to return fewer than the requested number of bytes. That makes it easy: we just copy the data from `b.slice` to the caller's buffer (`p`), and the return value from copy is the number of bytes transferred. Then we reslice `b.slice` to drop the first `n` bytes, ready for the next call.
+Lines 18-19 copy the data from `b.slice` to the caller's buffer.
+We are implementing `Read`, not `ReadFull`,
+so we are allowed to return fewer than the requested number of bytes.
+That makes it easy: we just copy the data from `b.slice` to the caller's buffer (`p`),
+and the return value from copy is the number of bytes transferred.
+Then we reslice `b.slice` to drop the first `n` bytes,
+ready for the next call.
-It's a nice technique in Go programming to couple a slice (`b.slice`) to an array (`b.tmp`). In this case, it means `blockReader` type's `Read` method never does any allocations. It also means we don't need to keep a count around (it's implicit in the slice length), and the built-in `copy` function guarantees we never copy more than we should. (For more about slices, see [[https://blog.golang.org/2011/01/go-slices-usage-and-internals.html][this post from the Go Blog]].)
+It's a nice technique in Go programming to couple a slice (`b.slice`) to an array (`b.tmp`).
+In this case, it means `blockReader` type's `Read` method never does any allocations.
+It also means we don't need to keep a count around (it's implicit in the slice length),
+and the built-in `copy` function guarantees we never copy more than we should.
+(For more about slices, see [[https://blog.golang.org/2011/01/go-slices-usage-and-internals.html][this post from the Go Blog]].)
-Given the `blockReader` type, we can unblock the image data stream just by wrapping the input reader, say a file, like this:
+Given the `blockReader` type, we can unblock the image data stream just
+by wrapping the input reader,
+say a file, like this:
deblockingReader := &blockReader{r: imageFile}
-This wrapping turns a block-delimited GIF image stream into a simple stream of bytes accessible by calls to the `Read` method of the `blockReader`.
+This wrapping turns a block-delimited GIF image stream into a simple stream
+of bytes accessible by calls to the `Read` method of the `blockReader`.
* Connecting the pieces
-With `blockReader` implemented and the LZW compressor available from the library, we have all the pieces we need to decode the image data stream. We stitch them together with this thunderclap, straight from the code:
+With `blockReader` implemented and the LZW compressor available from the library,
+we have all the pieces we need to decode the image data stream.
+We stitch them together with this thunderclap,
+straight from the code:
lzwr := lzw.NewReader(&blockReader{r: d.r}, lzw.LSB, int(litWidth))
if _, err = io.ReadFull(lzwr, m.Pix); err != nil {
@@ -101,17 +174,36 @@
That's it.
-The first line creates a `blockReader` and passes it to `lzw.NewReader` to create a decompressor. Here `d.r` is the `io.Reader` holding the image data, `lzw.LSB` defines the byte order in the LZW decompressor, and `litWidth` is the pixel depth.
+The first line creates a `blockReader` and passes it to `lzw.NewReader`
+to create a decompressor.
+Here `d.r` is the `io.Reader` holding the image data,
+`lzw.LSB` defines the byte order in the LZW decompressor,
+and `litWidth` is the pixel depth.
-Given the decompressor, the second line calls `io.ReadFull` to decompress the data and store it in the image, `m.Pix`. When `ReadFull` returns, the image data is decompressed and stored in the image, `m`, ready to be displayed.
+Given the decompressor, the second line calls `io.ReadFull` to decompress
+the data and store it in the image, `m.Pix`.
+When `ReadFull` returns, the image data is decompressed and stored in the image,
+`m`, ready to be displayed.
This code worked first time. Really.
-We could avoid the temporary variable `lzwr` by placing the `NewReader` call into the argument list for `ReadFull`, just as we built the `blockReader` inside the call to `NewReader`, but that might be packing too much into a single line of code.
+We could avoid the temporary variable `lzwr` by placing the `NewReader`
+call into the argument list for `ReadFull`,
+just as we built the `blockReader` inside the call to `NewReader`,
+but that might be packing too much into a single line of code.
* Conclusion
-Go's interfaces make it easy to construct software by assembling piece parts like this to restructure data. In this example, we implemented GIF decoding by chaining together a deblocker and a decompressor using the `io.Reader` interface, analogous to a type-safe Unix pipeline. Also, we wrote the deblocker as an (implicit) implementation of a `Reader` interface, which then required no extra declaration or boilerplate to fit it into the processing pipeline. It's hard to implement this decoder so compactly yet cleanly and safely in most languages, but the interface mechanism plus a few conventions make it almost natural in Go.
+Go's interfaces make it easy to construct software by assembling piece parts
+like this to restructure data.
+In this example, we implemented GIF decoding by chaining together a deblocker
+and a decompressor using the `io.Reader` interface,
+analogous to a type-safe Unix pipeline.
+Also, we wrote the deblocker as an (implicit) implementation of a `Reader` interface,
+which then required no extra declaration or boilerplate to fit it into the
+processing pipeline.
+It's hard to implement this decoder so compactly yet cleanly and safely in most languages,
+but the interface mechanism plus a few conventions make it almost natural in Go.
That deserves another picture, a GIF this time:
diff --git a/content/go-11-is-released.article b/content/go-11-is-released.article
index 18e2839..7f55938 100644
--- a/content/go-11-is-released.article
+++ b/content/go-11-is-released.article
@@ -10,21 +10,46 @@
.image go-11-is-released_gopherbiplane5.jpg
-In March last year we released Go 1.0, and since then we have released three minor "point releases". The point releases were made to fix only critical issues, so the Go 1.0.3 you use today is still, in essence, the Go 1.0 we released in March 2012.
+In March last year we released Go 1.0, and since then we have released three
+minor "point releases".
+The point releases were made to fix only critical issues,
+so the Go 1.0.3 you use today is still, in essence,
+the Go 1.0 we released in March 2012.
Go 1.1 includes many improvements over 1.0.
-The most significant improvements are performance-related. We have made optimizations in the compiler and linker, garbage collector, goroutine scheduler, map implementation, and parts of the standard library. It is likely that your Go code will run noticeably faster when built with Go 1.1.
+The most significant improvements are performance-related.
+We have made optimizations in the compiler and linker,
+garbage collector, goroutine scheduler, map implementation,
+and parts of the standard library.
+It is likely that your Go code will run noticeably faster when built with Go 1.1.
-There are some minor changes to the language itself, two of which are worth singling out here: the [[https://golang.org/doc/go1.1#return][changes to return requirements]] will lead to more succinct and correct programs, and the introduction of [[https://golang.org/doc/go1.1#method_values][method values]] provides an expressive way to bind a method to its receiver as a function value.
+There are some minor changes to the language itself,
+two of which are worth singling out here:
+the [[https://golang.org/doc/go1.1#return][changes to return requirements]] will
+lead to more succinct and correct programs,
+and the introduction of [[https://golang.org/doc/go1.1#method_values][method values]] provides
+an expressive way to bind a method to its receiver as a function value.
-Concurrent programming is safer in Go 1.1 with the addition of a race detector for finding memory synchronization errors in your programs. We will discuss the race detector more in an upcoming article, but for now [[https://golang.org/doc/articles/race_detector.html][the manual]] is a great place to get started.
+Concurrent programming is safer in Go 1.1 with the addition of a race
+detector for finding memory synchronization errors in your programs.
+We will discuss the race detector more in an upcoming article,
+but for now [[https://golang.org/doc/articles/race_detector.html][the manual]] is
+a great place to get started.
-The tools and standard library have been improved and expanded. You can read the full story in the [[https://golang.org/doc/go1.1][release notes]].
+The tools and standard library have been improved and expanded.
+You can read the full story in the [[https://golang.org/doc/go1.1][release notes]].
-As per our [[https://golang.org/doc/go1compat.html][compatibility guidelines]], Go 1.1 remains compatible with Go 1.0 and we recommend all Go users upgrade to the new release.
+As per our [[https://golang.org/doc/go1compat.html][compatibility guidelines]],
+Go 1.1 remains compatible with Go 1.0 and we recommend all Go users upgrade to the new release.
-All this would not have been possible without the help of our contributors from the open source community. Since Go 1.0, the core received more than 2600 commits from 161 people outside Google. Thank you everyone for your time and effort. In particular, we would like to thank Shenghou Ma, Rémy Oudompheng, Dave Cheney, Mikio Hara, Alex Brainman, Jan Ziak, and Daniel Morsing for their outstanding contributions.
+All this would not have been possible without the help of our contributors from
+the open source community.
+Since Go 1.0, the core received more than 2600 commits from 161 people outside Google.
+Thank you everyone for your time and effort.
+In particular, we would like to thank Shenghou Ma,
+Rémy Oudompheng, Dave Cheney, Mikio Hara,
+Alex Brainman, Jan Ziak, and Daniel Morsing for their outstanding contributions.
To grab the new release, follow the usual [[https://golang.org/doc/install][installation instructions]]. Happy hacking!
diff --git a/content/go-and-google-app-engine.article b/content/go-and-google-app-engine.article
index a2f32ef..ec0f3ca 100644
--- a/content/go-and-google-app-engine.article
+++ b/content/go-and-google-app-engine.article
@@ -10,20 +10,66 @@
* Introduction
-Google’s App Engine provides a reliable, scalable, easy way to build and deploy applications for the web. Over a hundred thousand apps are hosted at appspot.com and custom domains using the App Engine infrastructure. Originally written for Python apps, in 2009 the system added a Java runtime. And today, at Google I/O, we’re thrilled to announce that Go will be next. It’s marked as an experimental App Engine feature for now, because it’s early days, but both the App Engine and Go teams are very excited about this milestone.
+Google’s App Engine provides a reliable,
+scalable, easy way to build and deploy applications for the web.
+Over a hundred thousand apps are hosted at appspot.com and custom domains
+using the App Engine infrastructure.
+Originally written for Python apps, in 2009 the system added a Java runtime.
+And today, at Google I/O, we’re thrilled to announce that Go will be next.
+It’s marked as an experimental App Engine feature for now,
+because it’s early days, but both the App Engine and Go teams are very
+excited about this milestone.
-By early days, we mean that it’s still rolling out. As of today, the App Engine SDK for Go is [[http://code.google.com/p/googleappengine/downloads/list][available for download]], and we will soon enable deployment of Go apps into the App Engine hosting infrastructure. Today, through the SDK, you’ll be able to write web apps, learn about the APIs (and the language, if it’s new to you), and run your web app locally. Once full deployment is enabled, it’ll be easy to push your app to Google’s cloud.
+By early days, we mean that it’s still rolling out.
+As of today, the App Engine SDK for Go is [[http://code.google.com/p/googleappengine/downloads/list][available for download]],
+and we will soon enable deployment of Go apps into the App Engine hosting infrastructure.
+Today, through the SDK, you’ll be able to write web apps,
+learn about the APIs (and the language, if it’s new to you),
+and run your web app locally.
+Once full deployment is enabled, it’ll be easy to push your app to Google’s cloud.
-One of the cool but less obvious things about this news is that it provides a very easy way to play with Go. You don’t even need to have Go installed beforehand because the SDK is fully self-contained. Just download the SDK, unzip it, and start coding. Moreover, the SDK’s “dev app server” means you don’t even need to run the compiler yourself; everything is delightfully automatic.
+One of the cool but less obvious things about this news is that it provides
+a very easy way to play with Go.
+You don’t even need to have Go installed beforehand because the SDK is
+fully self-contained.
+Just download the SDK, unzip it, and start coding.
+Moreover, the SDK’s “dev app server” means you don’t even need to
+run the compiler yourself;
+everything is delightfully automatic.
-What you’ll find in the SDK is many of the standard App Engine APIs, custom designed in good Go style, including Datastore, Blobstore, URL Fetch, Mail, Users, and so on. More APIs will be added as the environment develops. The runtime provides the full Go language and almost all the standard libraries, except for a few things that don’t make sense in the App Engine environment. For instance, there is no `unsafe` package and the `syscall` package is trimmed. (The implementation uses an expanded version of the setup in the [[https://golang.org/doc/play/][Go Playground]] on [[https://golang.org/][golang.org]].)
+What you’ll find in the SDK is many of the standard App Engine APIs,
+custom designed in good Go style, including Datastore,
+Blobstore, URL Fetch, Mail, Users, and so on.
+More APIs will be added as the environment develops.
+The runtime provides the full Go language and almost all the standard libraries,
+except for a few things that don’t make sense in the App Engine environment.
+For instance, there is no `unsafe` package and the `syscall` package is trimmed.
+(The implementation uses an expanded version of the setup in the [[https://golang.org/doc/play/][Go Playground]]
+on [[https://golang.org/][golang.org]].)
-Also, although goroutines and channels are present, when a Go app runs on App Engine only one thread is run in a given instance. That is, all goroutines run in a single operating system thread, so there is no CPU parallelism available for a given client request. We expect this restriction will be lifted at some point.
+Also, although goroutines and channels are present,
+when a Go app runs on App Engine only one thread is run in a given instance.
+That is, all goroutines run in a single operating system thread,
+so there is no CPU parallelism available for a given client request.
+We expect this restriction will be lifted at some point.
-Despite these minor restrictions, it’s the real language: Code is deployed in source form and compiled in the cloud using the 64-bit x86 compiler (6g), making it the first true compiled language that runs on App Engine. Go on App Engine makes it possible to deploy efficient, CPU-intensive web applications.
+Despite these minor restrictions, it’s the real language:
+Code is deployed in source form and compiled in the cloud using the 64-bit x86 compiler (6g),
+making it the first true compiled language that runs on App Engine.
+Go on App Engine makes it possible to deploy efficient,
+CPU-intensive web applications.
-If you want to know more, read the [[http://code.google.com/appengine/docs/go/][documentation]] (start with “[[http://code.google.com/appengine/docs/go/gettingstarted/][Getting Started]]”). The libraries and SDK are open source, hosted at [[http://code.google.com/p/appengine-go/][http://code.google.com/p/appengine-go/]]. We’ve created a new [[http://groups.google.com/group/google-appengine-go][google-appengine-go]] mailing list; feel free to contact us there with App Engine-specific questions. The [[http://code.google.com/p/googleappengine/issues/list][issue tracker for App Engine]] is the place for reporting issues related to the new Go SDK.
+If you want to know more, read the [[http://code.google.com/appengine/docs/go/][documentation]]
+(start with “[[http://code.google.com/appengine/docs/go/gettingstarted/][Getting Started]]”).
+The libraries and SDK are open source, hosted at [[http://code.google.com/p/appengine-go/][http://code.google.com/p/appengine-go/]].
+We’ve created a new [[http://groups.google.com/group/google-appengine-go][google-appengine-go]] mailing list;
+feel free to contact us there with App Engine-specific questions.
+The [[http://code.google.com/p/googleappengine/issues/list][issue tracker for App Engine]]
+is the place for reporting issues related to the new Go SDK.
-The Go App Engine SDK is [[http://code.google.com/p/googleappengine/downloads/list][available]] for Linux and Mac OS X (10.5 or greater); we hope a Windows version will also be available soon.
+The Go App Engine SDK is [[http://code.google.com/p/googleappengine/downloads/list][available]]
+for Linux and Mac OS X (10.5 or greater);
+we hope a Windows version will also be available soon.
-We’d like to offer our thanks for all the help and enthusiasm we received from Google’s App Engine team in making this happen.
+We’d like to offer our thanks for all the help and enthusiasm we received
+from Google’s App Engine team in making this happen.
diff --git a/content/go-and-google-cloud-platform.article b/content/go-and-google-cloud-platform.article
index 4299960..2da1591 100644
--- a/content/go-and-google-cloud-platform.article
+++ b/content/go-and-google-cloud-platform.article
@@ -5,7 +5,13 @@
* Introduction
-In 2011 we announced the [[https://developers.google.com/appengine/docs/go/overview][Go runtime for App Engine]]. Since then, we have continued to improve the Go App Engine experience, and generally improved Go support for the Google Cloud Platform. For instance, the [[http://code.google.com/p/google-api-go-client][google-api-go-client]] provides a Go interface to a range of Google's public APis, including Compute Engine, Cloud Storage, BigQuery, Drive, and many more.
+In 2011 we announced the [[https://developers.google.com/appengine/docs/go/overview][Go runtime for App Engine]].
+Since then, we have continued to improve the Go App Engine experience,
+and generally improved Go support for the Google Cloud Platform.
+For instance, the [[http://code.google.com/p/google-api-go-client][google-api-go-client]] provides
+a Go interface to a range of Google's public APis,
+including Compute Engine, Cloud Storage, BigQuery,
+Drive, and many more.
Learn more by watching these talks from Google I/O this year:
diff --git a/content/go-app-engine-sdk-155-released.article b/content/go-app-engine-sdk-155-released.article
index dbe8dd5..2666a77 100644
--- a/content/go-app-engine-sdk-155-released.article
+++ b/content/go-app-engine-sdk-155-released.article
@@ -6,20 +6,37 @@
* Introduction
-Today we released version 1.5.5 the Go App Engine SDK. You can download it from the [[http://code.google.com/appengine/downloads.html][App Engine downloads page]].
+Today we released version 1.5.5 the Go App Engine SDK.
+You can download it from the [[http://code.google.com/appengine/downloads.html][App Engine downloads page]].
-This release includes changes and improvements to the App Engine APIs and brings the supporting Go tool chain to [[https://golang.org/doc/devel/release.html#r60][release.r60.2]] (the current stable release). Also included in this release are the [[https://golang.org/cmd/godoc/][godoc]], [[https://golang.org/cmd/gofmt/][gofmt]], and [[https://golang.org/cmd/gofix/][gofix]] tools from the Go tool chain. They can be found in the root directory of the SDK.
+This release includes changes and improvements to the App Engine APIs and
+brings the supporting Go tool chain to [[https://golang.org/doc/devel/release.html#r60][release.r60.2]]
+(the current stable release).
+Also included in this release are the [[https://golang.org/cmd/godoc/][godoc]],
+[[https://golang.org/cmd/gofmt/][gofmt]],
+and [[https://golang.org/cmd/gofix/][gofix]] tools from the Go tool chain.
+They can be found in the root directory of the SDK.
-Some changes made in this release are backwards-incompatible, so we have incremented the SDK `api_version` to 3. Existing apps will require code changes when migrating to `api_version` 3.
+Some changes made in this release are backwards-incompatible,
+so we have incremented the SDK `api_version` to 3.
+Existing apps will require code changes when migrating to `api_version` 3.
-The gofix tool that ships with the SDK has been customized with App Engine-specific modules. It can be used to automatically update Go apps to work with the latest appengine packages and the updated Go standard library. To update your apps, run:
+The gofix tool that ships with the SDK has been customized with App Engine-specific modules.
+It can be used to automatically update Go apps to work with the latest appengine
+packages and the updated Go standard library.
+To update your apps, run:
/path/to/sdk/gofix /path/to/your/app
-The SDK now includes the appengine package source code, so you can use the local godoc to read App Engine API documentation:
+The SDK now includes the appengine package source code,
+so you can use the local godoc to read App Engine API documentation:
/path/to/sdk/godoc appengine/datastore Get
-*Important*note:* We have deprecated `api_version` 2. Go apps that use `api_version` 2 will stop working after 16 December 2011. Please update your apps to use `api_version` 3 before then.
+*Important*note:* We have deprecated `api_version` 2.
+Go apps that use `api_version` 2 will stop working after 16 December 2011.
+Please update your apps to use `api_version` 3 before then.
-See the [[http://code.google.com/p/googleappengine/wiki/SdkForGoReleaseNotes][release notes]] for a full list of changes. Please direct any questions about the new SDK to the [[http://groups.google.com/group/google-appengine-go][Go App Engine discussion group]].
+See the [[http://code.google.com/p/googleappengine/wiki/SdkForGoReleaseNotes][release notes]]
+for a full list of changes.
+Please direct any questions about the new SDK to the [[http://groups.google.com/group/google-appengine-go][Go App Engine discussion group]].
diff --git a/content/go-at-google-io-2011-videos.article b/content/go-at-google-io-2011-videos.article
index 50dc6f2..909bfa9 100644
--- a/content/go-at-google-io-2011-videos.article
+++ b/content/go-at-google-io-2011-videos.article
@@ -6,17 +6,27 @@
* Introduction
-The Go team had a great time at Google I/O 2011. It was a pleasure to meet so many programmers who share our enthusiasm for Go, and to share our work of the past few months. For those of you that couldn’t be there in person, you can now watch videos of our two Go presentations on YouTube.
+The Go team had a great time at Google I/O 2011.
+It was a pleasure to meet so many programmers who share our enthusiasm for Go,
+and to share our work of the past few months.
+For those of you that couldn’t be there in person,
+you can now watch videos of our two Go presentations on YouTube.
* Writing Web Apps in Go
-In “[[http://www.youtube.com/watch?v=-i0hat7pdpk][Writing Web Apps in Go]]” we announce the [[https://blog.golang.org/2011/05/go-and-google-app-engine.html][Go runtime for Google App Engine]] and walk through the development and deployment of [[http://moustach-io.appspot.com/][Moustachio]], the first Go App Engine app.
+In “[[http://www.youtube.com/watch?v=-i0hat7pdpk][Writing Web Apps in Go]]”
+we announce the [[https://blog.golang.org/2011/05/go-and-google-app-engine.html][Go runtime for Google App Engine]]
+and walk through the development and deployment of [[http://moustach-io.appspot.com/][Moustachio]],
+the first Go App Engine app.
.iframe //www.youtube.com/embed/-i0hat7pdpk 349 560
(See the [[https://golang.org/doc/talks/io2011/Writing_Web_Apps_in_Go.pdf][presentation slides]].)
-The [[https://code.google.com/p/appengine-go/source/browse/example/moustachio][source code]] for Moustachio is available as part of [[http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Go][the SDK]] along with some other examples, such as this [[http://mandelbrot-tiles.appspot.com/][Mandelbrot demo]].
+The [[https://code.google.com/p/appengine-go/source/browse/example/moustachio][source code]]
+for Moustachio is available as part of [[http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Go][the SDK]]
+along with some other examples,
+such as this [[http://mandelbrot-tiles.appspot.com/][Mandelbrot demo]].
Most important, this talk features the debut of the plush gopher.
@@ -26,8 +36,11 @@
* Real World Go
-“[[http://www.youtube.com/watch?v=7QDVRowyUQA][Real World Go]]”, presented at [[http://io-bootcamp.com][I/O Bootcamp]], gives a brief introduction to Go and four case studies of its use in solving real problems:
-- [[http://heroku.com][Heroku]] with [[https://github.com/ha/doozerd][Doozer]], a highly available consistent data store,
+“[[http://www.youtube.com/watch?v=7QDVRowyUQA][Real World Go]]”,
+presented at [[http://io-bootcamp.com][I/O Bootcamp]],
+gives a brief introduction to Go and four case studies of its use in solving real problems:
+- [[http://heroku.com][Heroku]] with [[https://github.com/ha/doozerd][Doozer]],
+ a highly available consistent data store,
- [[http://mroffice.org/telephony.html][MROffice Dialer]], a VOIP system for call centers,
diff --git a/content/go-at-heroku.article b/content/go-at-heroku.article
index b2785b7..6663b6c 100644
--- a/content/go-at-heroku.article
+++ b/content/go-at-heroku.article
@@ -8,20 +8,65 @@
* Introduction
-_This_week’s_blog_post_is_written_by_ [[http://xph.us/][_Keith_Rarick_]] _and_ [[http://itsbonus.heroku.com/][_Blake_Mizerany_]], _systems_engineers_at_ [[http://www.heroku.com/][Heroku]]. _In_their_own_words,_they_"eat,_drink,_and_sleep_distributed_systems."_Here_they_discuss_their_experiences_using_Go._
+_This_week’s_blog_post_is_written_by_ [[http://xph.us/][_Keith_Rarick_]]
+_and_ [[http://itsbonus.heroku.com/][_Blake_Mizerany_]],
+_systems_engineers_at_ [[http://www.heroku.com/][Heroku]].
+_In_their_own_words,_they_"eat,_drink,_and_sleep_distributed_systems."_Here_they_discuss_their_experiences_using_Go._
-A big problem that comes with building distributed systems is the coordination of physical servers. Each server needs to know various facts about the system as a whole. This critical data includes locks, configuration data, and so on, and it must be consistent and available even during data store failures, so we need a data store with solid consistency guarantees. Our solution to this problem is [[http://xph.us/2011/04/13/introducing-doozer.html][Doozer]], a new, consistent, highly-available data store written in Go.
+A big problem that comes with building distributed systems is the coordination
+of physical servers.
+Each server needs to know various facts about the system as a whole.
+This critical data includes locks, configuration data,
+and so on, and it must be consistent and available even during data store failures,
+so we need a data store with solid consistency guarantees.
+Our solution to this problem is [[http://xph.us/2011/04/13/introducing-doozer.html][Doozer]],
+a new, consistent, highly-available data store written in Go.
-At Doozer's core is [[http://en.wikipedia.org/wiki/Paxos_(computer_science)][Paxos]], a family of protocols for solving consensus in an unreliable network of unreliable nodes. While Paxos is essential to running a fault-tolerant system, it is notorious for being difficult to implement. Even example implementations that can be found online are complex and hard to follow, despite being simplified for educational purposes. Existing production systems have a reputation for being worse.
+At Doozer's core is [[http://en.wikipedia.org/wiki/Paxos_(computer_science)][Paxos]],
+a family of protocols for solving consensus in an unreliable network of unreliable nodes.
+While Paxos is essential to running a fault-tolerant system,
+it is notorious for being difficult to implement.
+Even example implementations that can be found online are complex and hard to follow,
+despite being simplified for educational purposes.
+Existing production systems have a reputation for being worse.
-Fortunately, Go's concurrency primitives made the task much easier. Paxos is defined in terms of independent, concurrent processes that communicate via passing messages. In Doozer, these processes are implemented as goroutines, and their communications as channel operations. In the same way that garbage collectors improve upon malloc and free, we found that [[https://blog.golang.org/2010/07/share-memory-by-communicating.html][goroutines and channels]] improve upon the lock-based approach to concurrency. These tools let us avoid complex bookkeeping and stay focused on the problem at hand. We are still amazed at how few lines of code it took to achieve something renowned for being difficult.
+Fortunately, Go's concurrency primitives made the task much easier.
+Paxos is defined in terms of independent,
+concurrent processes that communicate via passing messages.
+In Doozer, these processes are implemented as goroutines,
+and their communications as channel operations.
+In the same way that garbage collectors improve upon malloc and free,
+we found that [[https://blog.golang.org/2010/07/share-memory-by-communicating.html][goroutines and channels]]
+improve upon the lock-based approach to concurrency.
+These tools let us avoid complex bookkeeping and stay focused on the problem at hand.
+We are still amazed at how few lines of code it took to achieve something
+renowned for being difficult.
-The standard packages in Go were another big win for Doozer. The Go team is very pragmatic about what goes into them. For instance, a package we quickly found useful was [[https://golang.org/pkg/websocket/][websocket]]. Once we had a working data store, we needed an easy way to introspect it and visualize activity. Using the websocket package, Keith was able to add the web viewer on his train ride home and without requiring external dependencies. This is a real testament to how well Go mixes systems and application programming.
+The standard packages in Go were another big win for Doozer.
+The Go team is very pragmatic about what goes into them.
+For instance, a package we quickly found useful was [[https://golang.org/pkg/websocket/][websocket]].
+Once we had a working data store, we needed an easy way to introspect it
+and visualize activity.
+Using the websocket package, Keith was able to add the web viewer on his
+train ride home and without requiring external dependencies.
+This is a real testament to how well Go mixes systems and application programming.
-One of our favorite productivity gains was provided by Go's source formatter: [[https://golang.org/cmd/gofmt/][gofmt]]. We never argued over where to put a curly-brace, tabs vs. spaces, or if we should align assignments. We simply agreed that the buck stopped at the default output from gofmt.
+One of our favorite productivity gains was provided by Go's source formatter:
+[[https://golang.org/cmd/gofmt/][gofmt]].
+We never argued over where to put a curly-brace,
+tabs vs. spaces, or if we should align assignments.
+We simply agreed that the buck stopped at the default output from gofmt.
-Deploying Doozer was satisfyingly simple. Go builds statically linked binaries which means Doozer has no external dependencies; it's a single file that can be copied to any machine and immediately launched to join a cluster of running Doozers.
+Deploying Doozer was satisfyingly simple.
+Go builds statically linked binaries which means Doozer has no external dependencies;
+it's a single file that can be copied to any machine and immediately launched
+to join a cluster of running Doozers.
-Finally, Go's maniacal focus on simplicity and orthogonality aligns with our view of software engineering. Like the Go team, we are pragmatic about what features go into Doozer. We sweat the details, preferring to change an existing feature instead of introducing a new one. In this sense, Go is a perfect match for Doozer.
+Finally, Go's maniacal focus on simplicity and orthogonality aligns with
+our view of software engineering.
+Like the Go team, we are pragmatic about what features go into Doozer.
+We sweat the details, preferring to change an existing feature instead of
+introducing a new one.
+In this sense, Go is a perfect match for Doozer.
We already have future projects in mind for Go. Doozer is just the start of much bigger system.
diff --git a/content/go-at-io-frequently-asked-questions.article b/content/go-at-io-frequently-asked-questions.article
index fb36f84..9b7d009 100644
--- a/content/go-at-io-frequently-asked-questions.article
+++ b/content/go-at-io-frequently-asked-questions.article
@@ -6,28 +6,68 @@
* Introduction
-Among the high-profile product launches at Google I/O last week, our small team gave presentations to packed rooms and met many present and future Go programmers. It was especially gratifying to meet with so many people who, after learning a bit about Go, were excited by the potential benefits (both immediate and long-term) they could gain from using it.
+Among the high-profile product launches at Google I/O last week,
+our small team gave presentations to packed rooms and met many present and
+future Go programmers.
+It was especially gratifying to meet with so many people who,
+after learning a bit about Go, were excited by the potential benefits (both
+immediate and long-term) they could gain from using it.
We were asked a lot of good questions during I/O, and in this post I'd like to recap and expand upon some of them.
How suitable is Go for production systems?
-Go is ready and stable now. We are pleased to report that Google is using Go for some production systems, and they are performing well. Of course there is still room for improvement - that's why we're continuing to work on the language, libraries, tools, and runtime.
+Go is ready and stable now. We are pleased to report that Google is using
+Go for some production systems,
+and they are performing well.
+Of course there is still room for improvement - that's why we're continuing
+to work on the language,
+libraries, tools, and runtime.
Do you have plans to implement generics?
-Many proposals for generics-like features have been mooted both publicly and internally, but as yet we haven't found a proposal that is consistent with the rest of the language. We think that one of Go's key strengths is its simplicity, so we are wary of introducing new features that might make the language more difficult to understand. Additionally, the more Go code we write (and thus the better we learn how to write Go code ourselves), the less we feel the need for such a language feature.
+Many proposals for generics-like features have been mooted both publicly and internally,
+but as yet we haven't found a proposal that is consistent with the rest of the language.
+We think that one of Go's key strengths is its simplicity,
+so we are wary of introducing new features that might make the language
+more difficult to understand.
+Additionally, the more Go code we write (and thus the better we learn how
+to write Go code ourselves),
+the less we feel the need for such a language feature.
Do you have any plans to support GPU programming?
-We don't have any immediate plans to do this, but as Go is architecture-agnostic it's quite possible. The ability to launch a goroutine that runs on a different processor architecture, and to use channels to communicate between goroutines running on separate architectures, seem like good ideas.
+We don't have any immediate plans to do this,
+but as Go is architecture-agnostic it's quite possible.
+The ability to launch a goroutine that runs on a different processor architecture,
+and to use channels to communicate between goroutines running on separate architectures,
+seem like good ideas.
Are there plans to support Go under App Engine?
-Both the Go and App Engine teams would like to see this happen. As always, it is a question of resources and priorities as to if and when it will become a reality.
+Both the Go and App Engine teams would like to see this happen.
+As always, it is a question of resources and priorities as to if and when
+it will become a reality.
Are there plans to support Go under Android?
-Both Go compilers support ARM code generation, so it is possible. While we think Go would be a great language for writing mobile applications, Android support is not something that's being actively worked on.
+Both Go compilers support ARM code generation, so it is possible.
+While we think Go would be a great language for writing mobile applications,
+Android support is not something that's being actively worked on.
What can I use Go for?
-Go was designed with systems programming in mind. Servers, clients, databases, caches, balancers, distributors - these are applications Go is obviously useful for, and this is how we have begun to use it within Google. However, since Go's open-source release, the community has found a diverse range of applications for the language. From web apps to games to graphics tools, Go promises to shine as a general-purpose programming language. The potential is only limited by library support, which is improving at a tremendous rate. Additionally, educators have expressed interest in using Go to teach programming, citing its succinct syntax and consistency as well-suited to the task.
+Go was designed with systems programming in mind.
+Servers, clients, databases, caches, balancers,
+distributors - these are applications Go is obviously useful for,
+and this is how we have begun to use it within Google.
+However, since Go's open-source release, the community has found a diverse
+range of applications for the language.
+From web apps to games to graphics tools,
+Go promises to shine as a general-purpose programming language.
+The potential is only limited by library support,
+which is improving at a tremendous rate.
+Additionally, educators have expressed interest in using Go to teach programming,
+citing its succinct syntax and consistency as well-suited to the task.
-Thanks to everyone who attended our presentations, or came to talk with us at Office Hours. We hope to see you again at future events.
+Thanks to everyone who attended our presentations,
+or came to talk with us at Office Hours.
+We hope to see you again at future events.
-The video of [[http://code.google.com/events/io/2010/sessions/go-programming.html][Rob and Russ' talk]] will be uploaded to YouTube within the next week, and will then be posted on this blog.
+The video of [[http://code.google.com/events/io/2010/sessions/go-programming.html][Rob and Russ' talk]]
+will be uploaded to YouTube within the next week,
+and will then be posted on this blog.
diff --git a/content/go-becomes-more-stable.article b/content/go-becomes-more-stable.article
index 17325e4..011346b 100644
--- a/content/go-becomes-more-stable.article
+++ b/content/go-becomes-more-stable.article
@@ -6,16 +6,44 @@
* Introduction
-The Go project is moving fast. As we learn more about Go we are compelled to change our tools, libraries, and occasionally even the language itself. We permit backward-incompatible changes so that we can learn from, rather than immortalize, our mistakes. We believe flexibility at this stage of Go’s development is essential to the project’s development and, ultimately, its longevity.
+The Go project is moving fast. As we learn more about Go we are compelled
+to change our tools,
+libraries, and occasionally even the language itself.
+We permit backward-incompatible changes so that we can learn from,
+rather than immortalize, our mistakes.
+We believe flexibility at this stage of Go’s development is essential
+to the project’s development and,
+ultimately, its longevity.
-Since Go's launch we have been making releases approximately once a week. Accompanying each release are [[https://golang.org/doc/devel/release.html][notes describing what changed]], with any backwards-incompatible changes signposted. Questions I hear often are "Is Go stable? How can I be sure that I won’t have to update my Go code every week?" The answer to those questions are now "Yes," and "You won't."
+Since Go's launch we have been making releases approximately once a week.
+Accompanying each release are [[https://golang.org/doc/devel/release.html][notes describing what changed]],
+with any backwards-incompatible changes signposted.
+Questions I hear often are "Is Go stable? How can I be sure that I won’t
+have to update my Go code every week?" The answer to those questions are
+now "Yes," and "You won't."
-With this week’s release we’re introducing a new release tagging scheme. We intend to continue with our weekly releases, but have renamed the existing tags from `release` to `weekly`. The `release` tag will now be applied to one hand-picked stable release each month or two. This more relaxed release schedule should make life easier for the average Go programmer.
+With this week’s release we’re introducing a new release tagging scheme.
+We intend to continue with our weekly releases,
+but have renamed the existing tags from `release` to `weekly`.
+The `release` tag will now be applied to one hand-picked stable release each month or two.
+This more relaxed release schedule should make life easier for the average Go programmer.
-Users will still need to update their code periodically (this is the cost of using a young language) but with less frequency. An additional benefit is that by tagging stable releases less often we can put more effort into automating updates. To this end we have introduced gofix, a tool that will help you update your code.
+Users will still need to update their code periodically (this is the cost
+of using a young language) but with less frequency.
+An additional benefit is that by tagging stable releases less often we can
+put more effort into automating updates.
+To this end we have introduced gofix, a tool that will help you update your code.
-The revision formerly tagged `release.2011-03-07.1` (now `weekly.2011-03-07.1`) has been nominated our first stable release, and has been given the tag `release.r56`. As we tag each stable release we will post an announcement to the new [[http://groups.google.com/group/golang-announce][golang-announce]] mailing list. (Why not [[http://groups.google.com/group/golang-announce/subscribe][subscribe now]]?)
+The revision formerly tagged `release.2011-03-07.1` (now `weekly.2011-03-07.1`)
+has been nominated our first stable release,
+and has been given the tag `release.r56`.
+As we tag each stable release we will post an announcement to the new [[http://groups.google.com/group/golang-announce][golang-announce]] mailing list.
+(Why not [[http://groups.google.com/group/golang-announce/subscribe][subscribe now]]?)
-What’s the upshot of all this? You can continue to keep your Go installation updated using `hg`update`release`, but now you should only need to update when we tag a new stable release. If you wish to stay at the leading edge, you should switch to the weekly tag with `hg`update`weekly`.
+What’s the upshot of all this? You can continue to keep your Go installation
+updated using `hg`update`release`,
+but now you should only need to update when we tag a new stable release.
+If you wish to stay at the leading edge, you should switch to the weekly
+tag with `hg`update`weekly`.
Happy coding!
diff --git a/content/go-cloud.article b/content/go-cloud.article
index 84206dc..01ef8aa 100644
--- a/content/go-cloud.article
+++ b/content/go-cloud.article
@@ -7,29 +7,76 @@
* Introduction
-Today, the Go team at Google is releasing a new open source project, [[https://github.com/google/go-cloud][Go Cloud]], a library and tools for developing on the [[https://cloud.google.com/open-cloud/][open cloud]]. With this project, we aim to make Go the language of choice for developers building portable cloud applications.
+Today, the Go team at Google is releasing a new open source project,
+[[https://github.com/google/go-cloud][Go Cloud]],
+a library and tools for developing on the [[https://cloud.google.com/open-cloud/][open cloud]].
+With this project, we aim to make Go the language of choice for developers
+building portable cloud applications.
This post explains why we started this project, the details of how Go Cloud works, and how to get involved.
* Why portable cloud programming? Why now?
-We estimate there are now [[https://research.swtch.com/gophercount][over one million]] Go developers worldwide. Go powers many of the most critical cloud infrastructure projects, including Kubernetes, Istio, and Docker. Companies like Lyft, Capital One, Netflix and [[https://github.com/golang/go/wiki/GoUsers][many more]] are depending on Go in production. Over the years, we've found that developers love Go for cloud development because of its efficiency, productivity, built-in concurrency, and low latency.
+We estimate there are now [[https://research.swtch.com/gophercount][over one million]]
+Go developers worldwide.
+Go powers many of the most critical cloud infrastructure projects,
+including Kubernetes, Istio, and Docker.
+Companies like Lyft, Capital One, Netflix and [[https://github.com/golang/go/wiki/GoUsers][many more]]
+are depending on Go in production.
+Over the years, we've found that developers love Go for cloud development
+because of its efficiency,
+productivity, built-in concurrency, and low latency.
-As part of our work to support Go's rapid growth, we have been interviewing teams who work with Go to understand how they use the language and how the Go ecosystem can improve further. One common theme with many organizations is the need for portability across cloud providers. These teams want to deploy robust applications in [[https://en.wikipedia.org/wiki/Cloud_computing#Multicloud][multi-cloud]] and [[https://en.wikipedia.org/wiki/Cloud_computing#Hybrid_cloud][hybrid-cloud]] environments, and migrate their workloads between cloud providers without significant changes to their code.
+As part of our work to support Go's rapid growth,
+we have been interviewing teams who work with Go to understand how they
+use the language and how the Go ecosystem can improve further.
+One common theme with many organizations is the need for portability across cloud providers.
+These teams want to deploy robust applications in [[https://en.wikipedia.org/wiki/Cloud_computing#Multicloud][multi-cloud]]
+and [[https://en.wikipedia.org/wiki/Cloud_computing#Hybrid_cloud][hybrid-cloud]] environments,
+and migrate their workloads between cloud providers without significant
+changes to their code.
-To achieve this, some teams attempt to decouple their applications from provider-specific APIs in order to produce simpler and more portable code. However the short-term pressure to ship features means teams often sacrifice longer-term efforts toward portability. As a result, most Go applications running in the cloud are tightly coupled to their initial cloud provider.
+To achieve this, some teams attempt to decouple their applications from
+provider-specific APIs in order to produce simpler and more portable code.
+However the short-term pressure to ship features means teams often sacrifice
+longer-term efforts toward portability.
+As a result, most Go applications running in the cloud are tightly coupled
+to their initial cloud provider.
-As an alternative, teams can use Go Cloud, a set of open generic cloud APIs, to write simpler and more portable cloud applications. Go Cloud also sets the foundation for an ecosystem of portable cloud libraries to be built on top of these generic APIs. Go Cloud makes it possible for teams to meet their feature development goals while also preserving the long-term flexibility for multi-cloud and hybrid-cloud architectures. Go Cloud applications can also migrate to the cloud providers that best meet their needs.
+As an alternative, teams can use Go Cloud,
+a set of open generic cloud APIs, to write simpler and more portable cloud applications.
+Go Cloud also sets the foundation for an ecosystem of portable cloud libraries
+to be built on top of these generic APIs.
+Go Cloud makes it possible for teams to meet their feature development goals
+while also preserving the long-term flexibility for multi-cloud and hybrid-cloud architectures.
+Go Cloud applications can also migrate to the cloud providers that best meet their needs.
* What is Go Cloud?
-We have identified common services used by cloud applications and have created generic APIs to work across cloud providers. Today, Go Cloud is launching with blob storage, MySQL database access, runtime configuration, and an HTTP server configured with request logging, tracing, and health checking. Go Cloud offers support for Google Cloud Platform (GCP) and Amazon Web Services (AWS). We plan to work with cloud industry partners and the Go community to add support for additional cloud providers very soon.
+We have identified common services used by cloud applications and have created
+generic APIs to work across cloud providers.
+Today, Go Cloud is launching with blob storage,
+MySQL database access, runtime configuration,
+and an HTTP server configured with request logging,
+tracing, and health checking.
+Go Cloud offers support for Google Cloud Platform (GCP) and Amazon Web Services (AWS).
+We plan to work with cloud industry partners and the Go community to add
+support for additional cloud providers very soon.
-Go Cloud aims to develop vendor-neutral generic APIs for the most-used services across cloud providers such that deploying a Go application on another cloud is simple and easy. Go Cloud also lays the foundation for other open source projects to write cloud libraries that work across providers. Community feedback, from all types of developers at all levels, will inform the priority of future APIs in Go Cloud.
+Go Cloud aims to develop vendor-neutral generic APIs for the most-used services
+across cloud providers such that deploying a Go application on another cloud is simple and easy.
+Go Cloud also lays the foundation for other open source projects to write
+cloud libraries that work across providers.
+Community feedback, from all types of developers at all levels,
+will inform the priority of future APIs in Go Cloud.
* How does it work?
-At the core of Go Cloud is a collection of generic APIs for portable cloud programming. Let's look at an example of using blob storage. You can use the generic type [[https://godoc.org/github.com/google/go-cloud/blob#Bucket][`*blob.Bucket`]] to copy a file from a local disk to a cloud provider. Let's start by opening an S3 bucket using the included [[https://godoc.org/github.com/google/go-cloud/blob/s3blob][s3blob package]]:
+At the core of Go Cloud is a collection of generic APIs for portable cloud programming.
+Let's look at an example of using blob storage.
+You can use the generic type [[https://godoc.org/github.com/google/go-cloud/blob#Bucket][`*blob.Bucket`]]
+to copy a file from a local disk to a cloud provider.
+Let's start by opening an S3 bucket using the included [[https://godoc.org/github.com/google/go-cloud/blob/s3blob][s3blob package]]:
// setupBucket opens an AWS bucket.
func setupBucket(ctx context.Context) (*blob.Bucket, error) {
@@ -44,7 +91,10 @@
return s3blob.OpenBucket(ctx, sess, "go-cloud-bucket")
}
-Once a program has a `*blob.Bucket`, it can create a `*blob.Writer`, which implements `io.Writer`. From there, the program can use the `*blob.Writer` to write data to the bucket, checking that `Close` does not report an error.
+Once a program has a `*blob.Bucket`, it can create a `*blob.Writer`,
+which implements `io.Writer`.
+From there, the program can use the `*blob.Writer` to write data to the bucket,
+checking that `Close` does not report an error.
ctx := context.Background()
b, err := setupBucket(ctx)
@@ -67,7 +117,12 @@
log.Fatalf("Failed to close: %v", err)
}
-Notice how the logic of using the bucket does not refer to AWS S3. Go Cloud makes swapping out cloud storage a matter of changing the function used to open the `*blob.Bucket`. The application could instead use Google Cloud Storage by constructing a `*blob.Bucket` using [[https://godoc.org/github.com/google/go-cloud/blob/gcsblob#OpenBucket][`gcsblob.OpenBucket`]] without changing the code that copies the file:
+Notice how the logic of using the bucket does not refer to AWS S3.
+Go Cloud makes swapping out cloud storage a matter of changing the function
+used to open the `*blob.Bucket`.
+The application could instead use Google Cloud Storage by constructing a
+`*blob.Bucket` using [[https://godoc.org/github.com/google/go-cloud/blob/gcsblob#OpenBucket][`gcsblob.OpenBucket`]]
+without changing the code that copies the file:
// setupBucket opens a GCS bucket.
func setupBucket(ctx context.Context) (*blob.Bucket, error) {
@@ -84,16 +139,44 @@
return gcsblob.OpenBucket(ctx, "go-cloud-bucket", c)
}
-While different steps are needed to access buckets on different cloud providers, the resulting type used by your application is the same: `*blob.Bucket`. This isolates application code from cloud-specific code. To increase interoperability with existing Go libraries, Go Cloud leverages established interfaces like `io.Writer`, `io.Reader`, and `*sql.DB`.
+While different steps are needed to access buckets on different cloud providers,
+the resulting type used by your application is the same: `*blob.Bucket`.
+This isolates application code from cloud-specific code.
+To increase interoperability with existing Go libraries,
+Go Cloud leverages established interfaces like `io.Writer`,
+`io.Reader`, and `*sql.DB`.
-The setup code needed to access cloud services tends to follow a pattern: higher abstractions are constructed from more basic abstractions. While you could write this code by hand, Go Cloud automates this with *Wire*, a tool that generates cloud-specific setup code for you. The [[https://github.com/google/go-cloud/tree/master/wire][Wire documentation]] explains how to install and use the tool and the [[https://github.com/google/go-cloud/tree/master/samples/guestbook][Guestbook sample]] shows Wire in action.
+The setup code needed to access cloud services tends to follow a pattern:
+higher abstractions are constructed from more basic abstractions.
+While you could write this code by hand, Go Cloud automates this with *Wire*,
+a tool that generates cloud-specific setup code for you.
+The [[https://github.com/google/go-cloud/tree/master/wire][Wire documentation]]
+explains how to install and use the tool and the [[https://github.com/google/go-cloud/tree/master/samples/guestbook][Guestbook sample]]
+shows Wire in action.
* How can I get involved and learn more?
-To get started, we recommend following [[https://github.com/google/go-cloud/tree/master/samples/tutorial][the tutorial]] and then trying to build an application yourself. If you're already using AWS or GCP, you can try migrating parts of your existing application to use Go Cloud. If you're using a different cloud provider or an on-premise service, you can extend Go Cloud to support it by implementing the driver interfaces (like [[https://godoc.org/github.com/google/go-cloud/blob/driver#Bucket][`driver.Bucket`]]).
+To get started, we recommend following [[https://github.com/google/go-cloud/tree/master/samples/tutorial][the tutorial]]
+and then trying to build an application yourself.
+If you're already using AWS or GCP, you can try migrating parts of your
+existing application to use Go Cloud.
+If you're using a different cloud provider or an on-premise service,
+you can extend Go Cloud to support it by implementing the driver interfaces
+(like [[https://godoc.org/github.com/google/go-cloud/blob/driver#Bucket][`driver.Bucket`]]).
-We appreciate any and all input you have about your experience. [[https://github.com/google/go-cloud][Go Cloud's]] development is conducted on GitHub. We are looking forward to contributions, including pull requests. [[https://github.com/google/go-cloud/issues/new][File an issue]] to tell us what could be better or what future APIs the project should support. For updates and discussion about the project, join [[https://groups.google.com/forum/#!forum/go-cloud][the project's mailing list]].
+We appreciate any and all input you have about your experience.
+[[https://github.com/google/go-cloud][Go Cloud's]] development is conducted on GitHub.
+We are looking forward to contributions, including pull requests.
+[[https://github.com/google/go-cloud/issues/new][File an issue]] to tell
+us what could be better or what future APIs the project should support.
+For updates and discussion about the project,
+join [[https://groups.google.com/forum/#!forum/go-cloud][the project's mailing list]].
-The project requires contributors to sign the same Contributor License Agreement as that of the Go project. Read the [[https://github.com/google/go-cloud/blob/master/CONTRIBUTING.md][contribution guidelines]] for more details. Please note, Go Cloud is covered by the Go [[https://github.com/google/go-cloud/blob/master/CODE_OF_CONDUCT.md][Code of Conduct]].
+The project requires contributors to sign the same Contributor License Agreement
+as that of the Go project.
+Read the [[https://github.com/google/go-cloud/blob/master/CONTRIBUTING.md][contribution guidelines]] for more details.
+Please note, Go Cloud is covered by the Go [[https://github.com/google/go-cloud/blob/master/CODE_OF_CONDUCT.md][Code of Conduct]].
-Thank you for taking the time to learn about Go Cloud. We are excited to work with you to make Go the language of choice for developers building portable cloud applications.
+Thank you for taking the time to learn about Go Cloud.
+We are excited to work with you to make Go the language of choice for developers
+building portable cloud applications.
diff --git a/content/go-concurrency-patterns-timing-out-and.article b/content/go-concurrency-patterns-timing-out-and.article
index 93411fd..0789006 100644
--- a/content/go-concurrency-patterns-timing-out-and.article
+++ b/content/go-concurrency-patterns-timing-out-and.article
@@ -6,7 +6,13 @@
* Introduction
-Concurrent programming has its own idioms. A good example is timeouts. Although Go's channels do not support them directly, they are easy to implement. Say we want to receive from the channel `ch`, but want to wait at most one second for the value to arrive. We would start by creating a signalling channel and launching a goroutine that sleeps before sending on the channel:
+Concurrent programming has its own idioms.
+A good example is timeouts. Although Go's channels do not support them directly,
+they are easy to implement.
+Say we want to receive from the channel `ch`,
+but want to wait at most one second for the value to arrive.
+We would start by creating a signalling channel and launching a goroutine
+that sleeps before sending on the channel:
timeout := make(chan bool, 1)
go func() {
@@ -14,7 +20,9 @@
timeout <- true
}()
-We can then use a `select` statement to receive from either `ch` or `timeout`. If nothing arrives on `ch` after one second, the timeout case is selected and the attempt to read from ch is abandoned.
+We can then use a `select` statement to receive from either `ch` or `timeout`.
+If nothing arrives on `ch` after one second,
+the timeout case is selected and the attempt to read from ch is abandoned.
select {
case <-ch:
@@ -23,13 +31,24 @@
// the read from ch has timed out
}
-The `timeout` channel is buffered with space for 1 value, allowing the timeout goroutine to send to the channel and then exit. The goroutine doesn't know (or care) whether the value is received. This means the goroutine won't hang around forever if the `ch` receive happens before the timeout is reached. The `timeout` channel will eventually be deallocated by the garbage collector.
+The `timeout` channel is buffered with space for 1 value,
+allowing the timeout goroutine to send to the channel and then exit.
+The goroutine doesn't know (or care) whether the value is received.
+This means the goroutine won't hang around forever if the `ch` receive happens
+before the timeout is reached.
+The `timeout` channel will eventually be deallocated by the garbage collector.
-(In this example we used `time.Sleep` to demonstrate the mechanics of goroutines and channels. In real programs you should use ` [[https://golang.org/pkg/time/#After][time.After]]`, a function that returns a channel and sends on that channel after the specified duration.)
+(In this example we used `time.Sleep` to demonstrate the mechanics of goroutines and channels.
+In real programs you should use ` [[https://golang.org/pkg/time/#After][time.After]]`,
+a function that returns a channel and sends on that channel after the specified duration.)
-Let's look at another variation of this pattern. In this example we have a program that reads from multiple replicated databases simultaneously. The program needs only one of the answers, and it should accept the answer that arrives first.
+Let's look at another variation of this pattern.
+In this example we have a program that reads from multiple replicated databases simultaneously.
+The program needs only one of the answers,
+and it should accept the answer that arrives first.
-The function `Query` takes a slice of database connections and a `query` string. It queries each of the databases in parallel and returns the first response it receives:
+The function `Query` takes a slice of database connections and a `query` string.
+It queries each of the databases in parallel and returns the first response it receives:
func Query(conns []Conn, query string) Result {
ch := make(chan Result)
@@ -44,8 +63,20 @@
return <-ch
}
-In this example, the closure does a non-blocking send, which it achieves by using the send operation in `select` statement with a `default` case. If the send cannot go through immediately the default case will be selected. Making the send non-blocking guarantees that none of the goroutines launched in the loop will hang around. However, if the result arrives before the main function has made it to the receive, the send could fail since no one is ready.
+In this example, the closure does a non-blocking send,
+which it achieves by using the send operation in `select` statement with a `default` case.
+If the send cannot go through immediately the default case will be selected.
+Making the send non-blocking guarantees that none of the goroutines launched
+in the loop will hang around.
+However, if the result arrives before the main function has made it to the receive,
+the send could fail since no one is ready.
-This problem is a textbook example of what is known as a [[https://en.wikipedia.org/wiki/Race_condition][race condition]], but the fix is trivial. We just make sure to buffer the channel `ch` (by adding the buffer length as the second argument to [[https://golang.org/pkg/builtin/#make][make]]), guaranteeing that the first send has a place to put the value. This ensures the send will always succeed, and the first value to arrive will be retrieved regardless of the order of execution.
+This problem is a textbook example of what is known as a [[https://en.wikipedia.org/wiki/Race_condition][race condition]],
+but the fix is trivial.
+We just make sure to buffer the channel `ch` (by adding the buffer length
+as the second argument to [[https://golang.org/pkg/builtin/#make][make]]),
+guaranteeing that the first send has a place to put the value.
+This ensures the send will always succeed,
+and the first value to arrive will be retrieved regardless of the order of execution.
These two examples demonstrate the simplicity with which Go can express complex interactions between goroutines.
diff --git a/content/go-fmt-your-code.article b/content/go-fmt-your-code.article
index ea6cd13..7b560d7 100644
--- a/content/go-fmt-your-code.article
+++ b/content/go-fmt-your-code.article
@@ -12,15 +12,21 @@
- easier to *write*: never worry about minor formatting concerns while hacking away,
-- easier to *read*: when all code looks the same you need not mentally convert others' formatting style into something you can understand.
+- easier to *read*: when all code looks the same you need not mentally convert
+ others' formatting style into something you can understand.
-- easier to *maintain*: mechanical changes to the source don't cause unrelated changes to the file's formatting; diffs show only the real changes.
+- easier to *maintain*: mechanical changes to the source don't cause unrelated
+ changes to the file's formatting;
+ diffs show only the real changes.
- *uncontroversial*: never have a debate about spacing or brace position ever again!
* Format your code
-We recently conducted a survey of Go packages in the wild and found that about 70% of them are formatted according to gofmt's rules. This was more than expected - and thanks to everyone who uses gofmt - but it would be great to close the gap.
+We recently conducted a survey of Go packages in the wild and found that
+about 70% of them are formatted according to gofmt's rules.
+This was more than expected - and thanks to everyone who uses gofmt - but
+it would be great to close the gap.
To format your code, you can use the gofmt tool directly:
@@ -30,33 +36,66 @@
go fmt path/to/your/package
-To help keep your code in the canonical style, the Go repository contains hooks for editors and version control systems that make it easy to run gofmt on your code.
+To help keep your code in the canonical style,
+the Go repository contains hooks for editors and version control systems
+that make it easy to run gofmt on your code.
-For Vim users, the [[https://github.com/fatih/vim-go][Vim plugin for Go]] includes the :Fmt command that runs gofmt on the current buffer.
+For Vim users, the [[https://github.com/fatih/vim-go][Vim plugin for Go]]
+includes the :Fmt command that runs gofmt on the current buffer.
-For emacs users, [[https://github.com/dominikh/go-mode.el][go-mode.el]] provides a gofmt-before-save hook that can be installed by adding this line to your .emacs file:
+For emacs users, [[https://github.com/dominikh/go-mode.el][go-mode.el]]
+provides a gofmt-before-save hook that can be installed by adding this line
+to your .emacs file:
(add-hook 'before-save-hook #'gofmt-before-save)
-For Eclipse or Sublime Text users, the [[https://github.com/GoClipse/goclipse][GoClipse]] and [[https://github.com/DisposaBoy/GoSublime][GoSublime]] projects add a gofmt facility to those editors.
+For Eclipse or Sublime Text users, the [[https://github.com/GoClipse/goclipse][GoClipse]]
+and [[https://github.com/DisposaBoy/GoSublime][GoSublime]] projects add
+a gofmt facility to those editors.
-And for Git aficionados, the [[https://github.com/golang/go/blob/release-branch.go1.1/misc/git/pre-commit][misc/git/pre-commit script]] is a pre-commit hook that prevents incorrectly-formatted Go code from being committed. If you use Mercurial, the [[https://bitbucket.org/fhs/hgstyle/overview][hgstyle plugin]] provides a gofmt pre-commit hook.
+And for Git aficionados, the [[https://github.com/golang/go/blob/release-branch.go1.1/misc/git/pre-commit][misc/git/pre-commit script]]
+is a pre-commit hook that prevents incorrectly-formatted Go code from being committed.
+If you use Mercurial, the [[https://bitbucket.org/fhs/hgstyle/overview][hgstyle plugin]]
+provides a gofmt pre-commit hook.
* Mechanical source transformation
-One of the greatest virtues of machine-formatted code is that it can be transformed mechanically without generating unrelated formatting noise in the diffs. Mechanical transformation is invaluable when working with large code bases, as it is both more comprehensive and less error prone than making wide-sweeping changes by hand. Indeed, when working at scale (like we do at Google) it often isn't practical to make these kinds of changes manually.
+One of the greatest virtues of machine-formatted code is that it can be
+transformed mechanically without generating unrelated formatting noise in the diffs.
+Mechanical transformation is invaluable when working with large code bases,
+as it is both more comprehensive and less error prone than making wide-sweeping changes by hand.
+Indeed, when working at scale (like we do at Google) it often isn't practical
+to make these kinds of changes manually.
-The easiest way to mechanically manipulate Go code is with gofmt's -r flag. The flag specifies a rewrite rule of the form
+The easiest way to mechanically manipulate Go code is with gofmt's -r flag.
+The flag specifies a rewrite rule of the form
pattern -> replacement
-where both pattern and replacement are valid Go expressions. In the pattern, single-character lowercase identifiers serve as wildcards matching arbitrary sub-expressions, and those expressions are substituted for the same identifiers in the replacement.
+where both pattern and replacement are valid Go expressions.
+In the pattern, single-character lowercase identifiers serve as wildcards
+matching arbitrary sub-expressions,
+and those expressions are substituted for the same identifiers in the replacement.
-For example, this[[https://golang.org/cl/7038051][ recent change]] to the Go core rewrote some uses of [[https://golang.org/pkg/bytes/#Compare][bytes.Compare]] to use the more efficient [[https://golang.org/pkg/bytes/#Equal][bytes.Equal]]. The contributor made the change using just two gofmt invocations:
+For example, this[[https://golang.org/cl/7038051][ recent change]] to the
+Go core rewrote some uses of [[https://golang.org/pkg/bytes/#Compare][bytes.Compare]]
+to use the more efficient [[https://golang.org/pkg/bytes/#Equal][bytes.Equal]].
+The contributor made the change using just two gofmt invocations:
gofmt -r 'bytes.Compare(a, b) == 0 -> bytes.Equal(a, b)'
gofmt -r 'bytes.Compare(a, b) != 0 -> !bytes.Equal(a, b)'
-Gofmt also enables [[https://golang.org/cmd/fix/][gofix]], which can make arbitrarily complex source transformations. Gofix was an invaluable tool during the early days when we regularly made breaking changes to the language and libraries. For example, before Go 1 the built-in error interface didn't exist and the convention was to use the os.Error type. When we [[https://golang.org/doc/go1.html#errors][introduced error]], we provided a gofix module that rewrote all references to os.Error and its associated helper functions to use error and the new [[https://golang.org/pkg/errors/][errors package]]. It would have been daunting to attempt by hand, but with the code in a standard format it was relatively easy to prepare, execute, and review this change which touched almost all Go code in existence.
+Gofmt also enables [[https://golang.org/cmd/fix/][gofix]],
+which can make arbitrarily complex source transformations.
+Gofix was an invaluable tool during the early days when we regularly made
+breaking changes to the language and libraries.
+For example, before Go 1 the built-in error interface didn't exist and the
+convention was to use the os.Error type.
+When we [[https://golang.org/doc/go1.html#errors][introduced error]],
+we provided a gofix module that rewrote all references to os.Error and its
+associated helper functions to use error and the new [[https://golang.org/pkg/errors/][errors package]].
+It would have been daunting to attempt by hand,
+but with the code in a standard format it was relatively easy to prepare,
+execute, and review this change which touched almost all Go code in existence.
For more about gofix, see [[https://blog.golang.org/introducing-gofix][this article]].
diff --git a/content/go-fonts.article b/content/go-fonts.article
index 24cd131..8996237 100644
--- a/content/go-fonts.article
+++ b/content/go-fonts.article
@@ -17,7 +17,8 @@
the release of a family of high-quality [[https://en.wikipedia.org/wiki/Windows_Glyph_List_4][WGL4]] TrueType fonts,
created by the [[http://bigelowandholmes.typepad.com/][Bigelow & Holmes]] type foundry specifically for the Go project.
-The font family, called Go (naturally), includes proportional- and fixed-width faces in normal, bold, and italic renderings.
+The font family, called Go (naturally), includes proportional- and fixed-width faces in normal,
+bold, and italic renderings.
The fonts have been tested for technical uses, particularly programming.
Go source code looks particularly good when displayed in Go fonts, as its name implies, with things like
punctuation characters easily distinguishable and operators lined up and placed consistently:
@@ -269,17 +270,27 @@
* References
-[1] Morris, R. A., Aquilante, K., Yager, D., & Bigelow, C. (2002, May). P‐13: Serifs Slow RSVP Reading at Very Small Sizes, but Don't Matter at Larger Sizes. In SID Symposium Digest of Technical Papers (Vol. 33, No. 1, pp. 244-247). Blackwell Publishing Ltd.
+[1] Morris, R. A., Aquilante, K., Yager, D., & Bigelow, C.
+(2002, May). P‐13: Serifs Slow RSVP Reading at Very Small Sizes,
+but Don't Matter at Larger Sizes.
+In SID Symposium Digest of Technical Papers (Vol.
+33, No. 1, pp. 244-247). Blackwell Publishing Ltd.
-[2] Bryan Reimer et al. (2014) “Assessing the impact of typeface design in a text-rich automotive user interface”, Ergonomics, 57:11, 1643-1658.
+[2] Bryan Reimer et al. (2014) “Assessing the impact of typeface design
+in a text-rich automotive user interface”,
+Ergonomics, 57:11, 1643-1658.
http://www.tandfonline.com/doi/abs/10.1080/00140139.2014.940000
-[3] Adrian Frutiger - Typefaces: The Complete Works. H. Osterer and P. Stamm, editors. Birkhäuser, Basel, 2009, page 257.
+[3] Adrian Frutiger - Typefaces: The Complete Works.
+H. Osterer and P. Stamm, editors. Birkhäuser,
+Basel, 2009, page 257.
-[4] Legge, G. E., & Bigelow, C. A. (2011). Does print size matter for reading? A review of findings from vision science and typography. Journal of Vision, 11(5), 8-8. http://jov.arvojournals.org/article.aspx?articleid=2191906
+[4] Legge, G. E., & Bigelow, C. A. (2011).
+Does print size matter for reading? A review of findings from vision science and typography.
+Journal of Vision, 11(5), 8-8. http://jov.arvojournals.org/article.aspx?articleid=2191906
[5] Charles Bigelow. "Oh, oh, zero!" TUGboat, Volume 34 (2013), No. 2.
diff --git a/content/go-for-app-engine-is-now-generally.article b/content/go-for-app-engine-is-now-generally.article
index 1674722..d1a2ac1 100644
--- a/content/go-for-app-engine-is-now-generally.article
+++ b/content/go-for-app-engine-is-now-generally.article
@@ -6,13 +6,28 @@
* Introduction
-The Go and App Engine teams are excited to announce that the Go runtime for App Engine is now generally available. This means you can take that Go app you've been working on (or meaning to work on) and deploy it to App Engine right now with the new [[http://code.google.com/appengine/downloads.html][1.5.2 SDK]].
+The Go and App Engine teams are excited to announce that the Go runtime
+for App Engine is now generally available.
+This means you can take that Go app you've been working on (or meaning to
+work on) and deploy it to App Engine right now with the new [[http://code.google.com/appengine/downloads.html][1.5.2 SDK]].
-Since we announced the Go runtime at Google I/O we have continued to [[http://code.google.com/p/googleappengine/wiki/SdkForGoReleaseNotes][improve and extend]] Go support for the App Engine APIs and have added the Channels API. The Go Datastore API now supports transactions and ancestor queries, too. See the [[https://code.google.com/appengine/docs/go/][Go App Engine documentation]] for all the details.
+Since we announced the Go runtime at Google I/O we have continued to [[http://code.google.com/p/googleappengine/wiki/SdkForGoReleaseNotes][improve and extend]]
+Go support for the App Engine APIs and have added the Channels API.
+The Go Datastore API now supports transactions and ancestor queries, too.
+See the [[https://code.google.com/appengine/docs/go/][Go App Engine documentation]]
+for all the details.
-For those who have been using the Go SDK already, please note that the 1.5.2 release introduces `api_version` 2. This is because the new SDK is based on Go `release.r58.1` (the current stable version of Go) and is not backwards compatible with the previous release. Existing apps may require changes as per the [[https://golang.org/doc/devel/release.html#r58][r58 release notes]]. Once you've updated your code, you should redeploy your app with the line `api_version:`2` in its `app.yaml` file. Apps written against `api_version` 1 will stop working after the 18th of August.
+For those who have been using the Go SDK already,
+please note that the 1.5.2 release introduces `api_version` 2.
+This is because the new SDK is based on Go `release.r58.1` (the current
+stable version of Go) and is not backwards compatible with the previous release.
+Existing apps may require changes as per the [[https://golang.org/doc/devel/release.html#r58][r58 release notes]].
+Once you've updated your code, you should redeploy your app with the line
+`api_version:`2` in its `app.yaml` file.
+Apps written against `api_version` 1 will stop working after the 18th of August.
-Finally, we owe a huge thanks to our trusted testers and their many bug reports. Their help was invaluable in reaching this important milestone.
+Finally, we owe a huge thanks to our trusted testers and their many bug reports.
+Their help was invaluable in reaching this important milestone.
_The_fastest_way_to_get_started_with_Go_on_App_Engine_is_with_the_ [[http://code.google.com/appengine/docs/go/gettingstarted/][_Getting_Started_guide_]].
diff --git a/content/go-image-package.article b/content/go-image-package.article
index 347c597..2626864 100644
--- a/content/go-image-package.article
+++ b/content/go-image-package.article
@@ -6,11 +6,20 @@
* Introduction
-The [[https://golang.org/pkg/image/][image]] and [[https://golang.org/pkg/image/color/][image/color]] packages define a number of types: `color.Color` and `color.Model` describe colors, `image.Point` and `image.Rectangle` describe basic 2-D geometry, and `image.Image` brings the two concepts together to represent a rectangular grid of colors. A [[https://golang.org/doc/articles/image_draw.html][separate article]] covers image composition with the [[https://golang.org/pkg/image/draw/][image/draw]] package.
+The [[https://golang.org/pkg/image/][image]] and [[https://golang.org/pkg/image/color/][image/color]]
+packages define a number of types:
+`color.Color` and `color.Model` describe colors,
+`image.Point` and `image.Rectangle` describe basic 2-D geometry,
+and `image.Image` brings the two concepts together to represent a rectangular grid of colors.
+A [[https://golang.org/doc/articles/image_draw.html][separate article]]
+covers image composition with the [[https://golang.org/pkg/image/draw/][image/draw]] package.
* Colors and Color Models
-[[https://golang.org/pkg/image/color/#Color][Color]] is an interface that defines the minimal method set of any type that can be considered a color: one that can be converted to red, green, blue and alpha values. The conversion may be lossy, such as converting from CMYK or YCbCr color spaces.
+[[https://golang.org/pkg/image/color/#Color][Color]] is an interface that
+defines the minimal method set of any type that can be considered a color:
+one that can be converted to red, green, blue and alpha values.
+The conversion may be lossy, such as converting from CMYK or YCbCr color spaces.
type Color interface {
// RGBA returns the alpha-premultiplied red, green, blue and alpha values
@@ -20,7 +29,17 @@
RGBA() (r, g, b, a uint32)
}
-There are three important subtleties about the return values. First, the red, green and blue are alpha-premultiplied: a fully saturated red that is also 25% transparent is represented by RGBA returning a 75% r. Second, the channels have a 16-bit effective range: 100% red is represented by RGBA returning an r of 65535, not 255, so that converting from CMYK or YCbCr is not as lossy. Third, the type returned is `uint32`, even though the maximum value is 65535, to guarantee that multiplying two values together won't overflow. Such multiplications occur when blending two colors according to an alpha mask from a third color, in the style of [[https://en.wikipedia.org/wiki/Alpha_compositing][Porter and Duff's]] classic algebra:
+There are three important subtleties about the return values.
+First, the red, green and blue are alpha-premultiplied:
+a fully saturated red that is also 25% transparent is represented by RGBA returning a 75% r.
+Second, the channels have a 16-bit effective range:
+100% red is represented by RGBA returning an r of 65535,
+not 255, so that converting from CMYK or YCbCr is not as lossy.
+Third, the type returned is `uint32`, even though the maximum value is 65535,
+to guarantee that multiplying two values together won't overflow.
+Such multiplications occur when blending two colors according to an alpha
+mask from a third color,
+in the style of [[https://en.wikipedia.org/wiki/Alpha_compositing][Porter and Duff's]] classic algebra:
dstr, dstg, dstb, dsta := dst.RGBA()
srcr, srcg, srcb, srca := src.RGBA()
@@ -30,17 +49,34 @@
// The calculation for green, blue and alpha is similar.
dstr = (dstr*(M-m) + srcr*m) / M
-The last line of that code snippet would have been more complicated if we worked with non-alpha-premultiplied colors, which is why `Color` uses alpha-premultiplied values.
+The last line of that code snippet would have been more complicated if we
+worked with non-alpha-premultiplied colors,
+which is why `Color` uses alpha-premultiplied values.
-The image/color package also defines a number of concrete types that implement the `Color` interface. For example, [[https://golang.org/pkg/image/color/#RGBA][`RGBA`]] is a struct that represents the classic "8 bits per channel" color.
+The image/color package also defines a number of concrete types that implement
+the `Color` interface.
+For example, [[https://golang.org/pkg/image/color/#RGBA][`RGBA`]] is a struct
+that represents the classic "8 bits per channel" color.
type RGBA struct {
R, G, B, A uint8
}
-Note that the `R` field of an `RGBA` is an 8-bit alpha-premultiplied color in the range [0, 255]. `RGBA` satisfies the `Color` interface by multiplying that value by 0x101 to generate a 16-bit alpha-premultiplied color in the range [0, 65535]. Similarly, the [[https://golang.org/pkg/image/color/#NRGBA][`NRGBA`]] struct type represents an 8-bit non-alpha-premultiplied color, as used by the PNG image format. When manipulating an `NRGBA`'s fields directly, the values are non-alpha-premultiplied, but when calling the `RGBA` method, the return values are alpha-premultiplied.
+Note that the `R` field of an `RGBA` is an 8-bit alpha-premultiplied color
+in the range [0, 255].
+`RGBA` satisfies the `Color` interface by multiplying that value by 0x101
+to generate a 16-bit alpha-premultiplied color in the range [0, 65535].
+Similarly, the [[https://golang.org/pkg/image/color/#NRGBA][`NRGBA`]] struct
+type represents an 8-bit non-alpha-premultiplied color,
+as used by the PNG image format.
+When manipulating an `NRGBA`'s fields directly,
+the values are non-alpha-premultiplied, but when calling the `RGBA` method,
+the return values are alpha-premultiplied.
-A [[https://golang.org/pkg/image/color/#Model][`Model`]] is simply something that can convert `Color`s to other `Color`s, possibly lossily. For example, the `GrayModel` can convert any `Color` to a desaturated [[https://golang.org/pkg/image/color/#Gray][`Gray`]]. A `Palette` can convert any `Color` to one from a limited palette.
+A [[https://golang.org/pkg/image/color/#Model][`Model`]] is simply something
+that can convert `Color`s to other `Color`s, possibly lossily.
+For example, the `GrayModel` can convert any `Color` to a desaturated [[https://golang.org/pkg/image/color/#Gray][`Gray`]].
+A `Palette` can convert any `Color` to one from a limited palette.
type Model interface {
Convert(c Color) Color
@@ -50,7 +86,10 @@
* Points and Rectangles
-A [[https://golang.org/pkg/image/#Point][`Point`]] is an (x, y) co-ordinate on the integer grid, with axes increasing right and down. It is neither a pixel nor a grid square. A `Point` has no intrinsic width, height or color, but the visualizations below use a small colored square.
+A [[https://golang.org/pkg/image/#Point][`Point`]] is an (x,
+y) co-ordinate on the integer grid, with axes increasing right and down.
+It is neither a pixel nor a grid square. A `Point` has no intrinsic width,
+height or color, but the visualizations below use a small colored square.
type Point struct {
X, Y int
@@ -60,15 +99,26 @@
p := image.Point{2, 1}
-A [[https://golang.org/pkg/image/#Rectangle][`Rectangle`]] is an axis-aligned rectangle on the integer grid, defined by its top-left and bottom-right `Point`. A `Rectangle` also has no intrinsic color, but the visualizations below outline rectangles with a thin colored line, and call out their `Min` and `Max` `Point`s.
+A [[https://golang.org/pkg/image/#Rectangle][`Rectangle`]] is an axis-aligned
+rectangle on the integer grid,
+defined by its top-left and bottom-right `Point`.
+A `Rectangle` also has no intrinsic color,
+but the visualizations below outline rectangles with a thin colored line,
+and call out their `Min` and `Max` `Point`s.
type Rectangle struct {
Min, Max Point
}
-For convenience, `image.Rect(x0,`y0,`x1,`y1)` is equivalent to `image.Rectangle{image.Point{x0,`y0},`image.Point{x1,`y1}}`, but is much easier to type.
+For convenience, `image.Rect(x0,`y0,`x1,`y1)` is equivalent to `image.Rectangle{image.Point{x0,`y0},`image.Point{x1,`y1}}`,
+but is much easier to type.
-A `Rectangle` is inclusive at the top-left and exclusive at the bottom-right. For a `Point`p` and a `Rectangle`r`, `p.In(r)` if and only if `r.Min.X`<=`p.X`&&`p.X`<`r.Max.X`, and similarly for `Y`. This is analogous to how a slice `s[i0:i1]` is inclusive at the low end and exclusive at the high end. (Unlike arrays and slices, a `Rectangle` often has a non-zero origin.)
+A `Rectangle` is inclusive at the top-left and exclusive at the bottom-right.
+For a `Point`p` and a `Rectangle`r`, `p.In(r)` if and only if `r.Min.X`<=`p.X`&&`p.X`<`r.Max.X`,
+and similarly for `Y`.
+This is analogous to how a slice `s[i0:i1]` is inclusive at the low end
+and exclusive at the high end.
+(Unlike arrays and slices, a `Rectangle` often has a non-zero origin.)
.image go-image-package_image-package-02.png
@@ -76,7 +126,8 @@
// Dx and Dy return a rectangle's width and height.
fmt.Println(r.Dx(), r.Dy(), image.Pt(0, 0).In(r)) // prints 3 4 false
-Adding a `Point` to a `Rectangle` translates the `Rectangle`. Points and Rectangles are not restricted to be in the bottom-right quadrant.
+Adding a `Point` to a `Rectangle` translates the `Rectangle`.
+Points and Rectangles are not restricted to be in the bottom-right quadrant.
.image go-image-package_image-package-03.png
@@ -91,11 +142,17 @@
// Size returns a rectangle's width and height, as a Point.
fmt.Printf("%#v\n", r.Size()) // prints image.Point{X:2, Y:1}
-Points and Rectangles are passed and returned by value. A function that takes a `Rectangle` argument will be as efficient as a function that takes two `Point` arguments, or four `int` arguments.
+Points and Rectangles are passed and returned by value.
+A function that takes a `Rectangle` argument will be as efficient as a function
+that takes two `Point` arguments,
+or four `int` arguments.
* Images
-An [[https://golang.org/pkg/image/#Image][Image]] maps every grid square in a `Rectangle` to a `Color` from a `Model`. "The pixel at (x, y)" refers to the color of the grid square defined by the points (x, y), (x+1, y), (x+1, y+1) and (x, y+1).
+An [[https://golang.org/pkg/image/#Image][Image]] maps every grid square
+in a `Rectangle` to a `Color` from a `Model`.
+"The pixel at (x, y)" refers to the color of the grid square defined by the points (x,
+y), (x+1, y), (x+1, y+1) and (x, y+1).
type Image interface {
// ColorModel returns the Image's color model.
@@ -109,7 +166,11 @@
At(x, y int) color.Color
}
-A common mistake is assuming that an `Image`'s bounds start at (0, 0). For example, an animated GIF contains a sequence of Images, and each `Image` after the first typically only holds pixel data for the area that changed, and that area doesn't necessarily start at (0, 0). The correct way to iterate over an `Image` m's pixels looks like:
+A common mistake is assuming that an `Image`'s bounds start at (0, 0).
+For example, an animated GIF contains a sequence of Images,
+and each `Image` after the first typically only holds pixel data for the area that changed,
+and that area doesn't necessarily start at (0, 0).
+The correct way to iterate over an `Image` m's pixels looks like:
b := m.Bounds()
for y := b.Min.Y; y < b.Max.Y; y++ {
@@ -118,13 +179,19 @@
}
}
-`Image` implementations do not have to be based on an in-memory slice of pixel data. For example, a [[https://golang.org/pkg/image/#Uniform][`Uniform`]] is an `Image` of enormous bounds and uniform color, whose in-memory representation is simply that color.
+`Image` implementations do not have to be based on an in-memory slice of pixel data.
+For example, a [[https://golang.org/pkg/image/#Uniform][`Uniform`]] is an
+`Image` of enormous bounds and uniform color,
+whose in-memory representation is simply that color.
type Uniform struct {
C color.Color
}
-Typically, though, programs will want an image based on a slice. Struct types like [[https://golang.org/pkg/image/#RGBA][`RGBA`]] and [[https://golang.org/pkg/image/#Gray][`Gray`]] (which other packages refer to as `image.RGBA` and `image.Gray`) hold slices of pixel data and implement the `Image` interface.
+Typically, though, programs will want an image based on a slice.
+Struct types like [[https://golang.org/pkg/image/#RGBA][`RGBA`]] and [[https://golang.org/pkg/image/#Gray][`Gray`]]
+(which other packages refer to as `image.RGBA` and `image.Gray`) hold slices
+of pixel data and implement the `Image` interface.
type RGBA struct {
// Pix holds the image's pixels, in R, G, B, A order. The pixel at
@@ -141,9 +208,15 @@
m := image.NewRGBA(image.Rect(0, 0, 640, 480))
m.Set(5, 5, color.RGBA{255, 0, 0, 255})
-If you're reading or writing a lot of pixel data, it can be more efficient, but more complicated, to access these struct type's `Pix` field directly.
+If you're reading or writing a lot of pixel data,
+it can be more efficient, but more complicated,
+to access these struct type's `Pix` field directly.
-The slice-based `Image` implementations also provide a `SubImage` method, which returns an `Image` backed by the same array. Modifying the pixels of a sub-image will affect the pixels of the original image, analogous to how modifying the contents of a sub-slice `s[i0:i1]` will affect the contents of the original slice `s`.
+The slice-based `Image` implementations also provide a `SubImage` method,
+which returns an `Image` backed by the same array.
+Modifying the pixels of a sub-image will affect the pixels of the original image,
+analogous to how modifying the contents of a sub-slice `s[i0:i1]` will affect
+the contents of the original slice `s`.
.image go-image-package_image-package-05.png
@@ -152,11 +225,18 @@
fmt.Println(m0.Bounds().Dx(), m1.Bounds().Dx()) // prints 8, 4
fmt.Println(m0.Stride == m1.Stride) // prints true
-For low-level code that works on an image's `Pix` field, be aware that ranging over `Pix` can affect pixels outside an image's bounds. In the example above, the pixels covered by `m1.Pix` are shaded in blue. Higher-level code, such as the `At` and `Set` methods or the [[https://golang.org/pkg/image/draw/][image/draw package]], will clip their operations to the image's bounds.
+For low-level code that works on an image's `Pix` field,
+be aware that ranging over `Pix` can affect pixels outside an image's bounds.
+In the example above, the pixels covered by `m1.Pix` are shaded in blue.
+Higher-level code, such as the `At` and `Set` methods or the [[https://golang.org/pkg/image/draw/][image/draw package]],
+will clip their operations to the image's bounds.
* Image Formats
-The standard package library supports a number of common image formats, such as GIF, JPEG and PNG. If you know the format of a source image file, you can decode from an [[https://golang.org/pkg/io/#Reader][`io.Reader`]] directly.
+The standard package library supports a number of common image formats,
+such as GIF, JPEG and PNG.
+If you know the format of a source image file,
+you can decode from an [[https://golang.org/pkg/io/#Reader][`io.Reader`]] directly.
import (
"image/jpeg"
@@ -173,7 +253,13 @@
return png.Encode(w, img)
}
-If you have image data of unknown format, the [[https://golang.org/pkg/image/#Decode][`image.Decode`]] function can detect the format. The set of recognized formats is constructed at run time and is not limited to those in the standard package library. An image format package typically registers its format in an init function, and the main package will "underscore import" such a package solely for the side effect of format registration.
+If you have image data of unknown format,
+the [[https://golang.org/pkg/image/#Decode][`image.Decode`]] function can detect the format.
+The set of recognized formats is constructed at run time and is not limited
+to those in the standard package library.
+An image format package typically registers its format in an init function,
+and the main package will "underscore import" such a package solely for
+the side effect of format registration.
import (
"image"
diff --git a/content/go-imagedraw-package.article b/content/go-imagedraw-package.article
index a7a864e..2e9dade 100644
--- a/content/go-imagedraw-package.article
+++ b/content/go-imagedraw-package.article
@@ -6,26 +6,71 @@
* Introduction
-[[https://golang.org/pkg/image/draw/][Package image/draw]] defines only one operation: drawing a source image onto a destination image, through an optional mask image. This one operation is surprisingly versatile and can perform a number of common image manipulation tasks elegantly and efficiently.
+[[https://golang.org/pkg/image/draw/][Package image/draw]] defines only one operation:
+drawing a source image onto a destination image,
+through an optional mask image.
+This one operation is surprisingly versatile and can perform a number of
+common image manipulation tasks elegantly and efficiently.
-Composition is performed pixel by pixel in the style of the Plan 9 graphics library and the X Render extension. The model is based on the classic "Compositing Digital Images" paper by Porter and Duff, with an additional mask parameter: `dst`=`(src`IN`mask)`OP`dst`. For a fully opaque mask, this reduces to the original Porter-Duff formula: `dst`=`src`OP`dst`. In Go, a nil mask image is equivalent to an infinitely sized, fully opaque mask image.
+Composition is performed pixel by pixel in the style of the Plan 9 graphics
+library and the X Render extension.
+The model is based on the classic "Compositing Digital Images" paper by Porter and Duff,
+with an additional mask parameter:
+`dst`=`(src`IN`mask)`OP`dst`.
+For a fully opaque mask, this reduces to the original Porter-Duff formula: `dst`=`src`OP`dst`.
+In Go, a nil mask image is equivalent to an infinitely sized,
+fully opaque mask image.
-The Porter-Duff paper presented [[http://www.w3.org/TR/SVGCompositing/examples/compop-porterduff-examples.png][12 different composition operators]], but with an explicit mask, only 2 of these are needed in practice: source-over-destination and source. In Go, these operators are represented by the `Over` and `Src` constants. The `Over` operator performs the natural layering of a source image over a destination image: the change to the destination image is smaller where the source (after masking) is more transparent (that is, has lower alpha). The `Src` operator merely copies the source (after masking) with no regard for the destination image's original content. For fully opaque source and mask images, the two operators produce the same output, but the `Src` operator is usually faster.
+The Porter-Duff paper presented [[http://www.w3.org/TR/SVGCompositing/examples/compop-porterduff-examples.png][12 different composition operators]],
+but with an explicit mask, only 2 of these are needed in practice:
+source-over-destination and source.
+In Go, these operators are represented by the `Over` and `Src` constants.
+The `Over` operator performs the natural layering of a source image over
+a destination image:
+the change to the destination image is smaller where the source (after masking)
+is more transparent (that is, has lower alpha).
+The `Src` operator merely copies the source (after masking) with no regard
+for the destination image's original content.
+For fully opaque source and mask images, the two operators produce the same output,
+but the `Src` operator is usually faster.
* Geometric Alignment
-Composition requires associating destination pixels with source and mask pixels. Obviously, this requires destination, source and mask images, and a composition operator, but it also requires specifying what rectangle of each image to use. Not every drawing should write to the entire destination: when updating an animating image, it is more efficient to only draw the parts of the image that have changed. Not every drawing should read from the entire source: when using a sprite that combines many small images into one large one, only a part of the image is needed. Not every drawing should read from the entire mask: a mask image that collects a font's glyphs is similar to a sprite. Thus, drawing also needs to know three rectangles, one for each image. Since each rectangle has the same width and height, it suffices to pass a destination rectangle `r` and two points `sp` and `mp`: the source rectangle is equal to `r` translated so that `r.Min` in the destination image aligns with `sp` in the source image, and similarly for `mp`. The effective rectangle is also clipped to each image's bounds in their respective co-ordinate space.
+Composition requires associating destination pixels with source and mask pixels.
+Obviously, this requires destination, source and mask images,
+and a composition operator, but it also requires specifying what rectangle
+of each image to use.
+Not every drawing should write to the entire destination:
+when updating an animating image, it is more efficient to only draw the
+parts of the image that have changed.
+Not every drawing should read from the entire source:
+when using a sprite that combines many small images into one large one,
+only a part of the image is needed.
+Not every drawing should read from the entire mask:
+a mask image that collects a font's glyphs is similar to a sprite.
+Thus, drawing also needs to know three rectangles, one for each image.
+Since each rectangle has the same width and height,
+it suffices to pass a destination rectangle `r` and two points `sp` and `mp`:
+the source rectangle is equal to `r` translated so that `r.Min` in the destination
+image aligns with `sp` in the source image,
+and similarly for `mp`.
+The effective rectangle is also clipped to each image's bounds in their
+respective co-ordinate space.
.image go-imagedraw-package_20.png
-The [[https://golang.org/pkg/image/draw/#DrawMask][`DrawMask`]] function takes seven arguments, but an explicit mask and mask-point are usually unnecessary, so the [[https://golang.org/pkg/image/draw/#Draw][`Draw`]] function takes five:
+The [[https://golang.org/pkg/image/draw/#DrawMask][`DrawMask`]] function
+takes seven arguments,
+but an explicit mask and mask-point are usually unnecessary,
+so the [[https://golang.org/pkg/image/draw/#Draw][`Draw`]] function takes five:
// Draw calls DrawMask with a nil mask.
func Draw(dst Image, r image.Rectangle, src image.Image, sp image.Point, op Op)
func DrawMask(dst Image, r image.Rectangle, src image.Image, sp image.Point,
mask image.Image, mp image.Point, op Op)
-The destination image must be mutable, so the image/draw package defines a [[https://golang.org/pkg/image/draw/#Image][`draw.Image`]] interface which has a `Set` method.
+The destination image must be mutable, so the image/draw package defines
+a [[https://golang.org/pkg/image/draw/#Image][`draw.Image`]] interface which has a `Set` method.
type Image interface {
image.Image
@@ -35,7 +80,12 @@
* Filling a Rectangle
-To fill a rectangle with a solid color, use an `image.Uniform` source. The `ColorImage` type re-interprets a `Color` as a practically infinite-sized `Image` of that color. For those familiar with the design of Plan 9's draw library, there is no need for an explicit "repeat bit" in Go's slice-based image types; the concept is subsumed by `Uniform`.
+To fill a rectangle with a solid color, use an `image.Uniform` source.
+The `ColorImage` type re-interprets a `Color` as a practically infinite-sized
+`Image` of that color.
+For those familiar with the design of Plan 9's draw library,
+there is no need for an explicit "repeat bit" in Go's slice-based image types;
+the concept is subsumed by `Uniform`.
// image.ZP is the zero point -- the origin.
draw.Draw(dst, r, &image.Uniform{c}, image.ZP, draw.Src)
@@ -46,7 +96,9 @@
blue := color.RGBA{0, 0, 255, 255}
draw.Draw(m, m.Bounds(), &image.Uniform{blue}, image.ZP, draw.Src)
-To reset an image to transparent (or black, if the destination image's color model cannot represent transparency), use `image.Transparent`, which is an `image.Uniform`:
+To reset an image to transparent (or black,
+if the destination image's color model cannot represent transparency),
+use `image.Transparent`, which is an `image.Uniform`:
draw.Draw(m, m.Bounds(), image.Transparent, image.ZP, draw.Src)
@@ -56,7 +108,9 @@
* Copying an Image
-To copy from a rectangle `sr` in the source image to a rectangle starting at a point `dp` in the destination, convert the source rectangle into the destination image's co-ordinate space:
+To copy from a rectangle `sr` in the source image to a rectangle starting
+at a point `dp` in the destination,
+convert the source rectangle into the destination image's co-ordinate space:
r := image.Rectangle{dp, dp.Add(sr.Size())}
draw.Draw(dst, r, src, sr.Min, draw.Src)
@@ -76,7 +130,11 @@
* Scrolling an Image
-Scrolling an image is just copying an image to itself, with different destination and source rectangles. Overlapping destination and source images are perfectly valid, just as Go's built-in copy function can handle overlapping destination and source slices. To scroll an image m by 20 pixels:
+Scrolling an image is just copying an image to itself,
+with different destination and source rectangles.
+Overlapping destination and source images are perfectly valid,
+just as Go's built-in copy function can handle overlapping destination and source slices.
+To scroll an image m by 20 pixels:
b := m.Bounds()
p := image.Pt(0, 20)
@@ -91,7 +149,11 @@
* Converting an Image to RGBA
-The result of decoding an image format might not be an `image.RGBA`: decoding a GIF results in an `image.Paletted`, decoding a JPEG results in a `ycbcr.YCbCr`, and the result of decoding a PNG depends on the image data. To convert any image to an `image.RGBA`:
+The result of decoding an image format might not be an `image.RGBA`:
+decoding a GIF results in an `image.Paletted`,
+decoding a JPEG results in a `ycbcr.YCbCr`,
+and the result of decoding a PNG depends on the image data.
+To convert any image to an `image.RGBA`:
b := src.Bounds()
m := image.NewRGBA(image.Rect(0, 0, b.Dx(), b.Dy()))
@@ -132,7 +194,10 @@
* Drawing Font Glyphs
-To draw a font glyph in blue starting from a point `p`, draw with an `image.ColorImage` source and an `image.Alpha`mask`. For simplicity, we aren't performing any sub-pixel positioning or rendering, or correcting for a font's height above a baseline.
+To draw a font glyph in blue starting from a point `p`,
+draw with an `image.ColorImage` source and an `image.Alpha`mask`.
+For simplicity, we aren't performing any sub-pixel positioning or rendering,
+or correcting for a font's height above a baseline.
src := &image.Uniform{color.RGBA{0, 0, 255, 255}}
mask := theGlyphImageForAFont()
@@ -144,4 +209,17 @@
* Performance
-The image/draw package implementation demonstrates how to provide an image manipulation function that is both general purpose, yet efficient for common cases. The `DrawMask` function takes arguments of interface types, but immediately makes type assertions that its arguments are of specific struct types, corresponding to common operations like drawing one `image.RGBA` image onto another, or drawing an `image.Alpha` mask (such as a font glyph) onto an `image.RGBA` image. If a type assertion succeeds, that type information is used to run a specialized implementation of the general algorithm. If the assertions fail, the fallback code path uses the generic `At` and `Set` methods. The fast-paths are purely a performance optimization; the resultant destination image is the same either way. In practice, only a small number of special cases are necessary to support typical applications.
+The image/draw package implementation demonstrates how to provide an image
+manipulation function that is both general purpose,
+yet efficient for common cases.
+The `DrawMask` function takes arguments of interface types,
+but immediately makes type assertions that its arguments are of specific struct types,
+corresponding to common operations like drawing one `image.RGBA` image onto another,
+or drawing an `image.Alpha` mask (such as a font glyph) onto an `image.RGBA` image.
+If a type assertion succeeds, that type information is used to run a specialized
+implementation of the general algorithm.
+If the assertions fail, the fallback code path uses the generic `At` and `Set` methods.
+The fast-paths are purely a performance optimization;
+the resultant destination image is the same either way.
+In practice, only a small number of special cases are necessary to support
+typical applications.
diff --git a/content/go-maps-in-action.article b/content/go-maps-in-action.article
index cc6d62c..70fbb8d 100644
--- a/content/go-maps-in-action.article
+++ b/content/go-maps-in-action.article
@@ -6,7 +6,10 @@
* Introduction
-One of the most useful data structures in computer science is the hash table. Many hash table implementations exist with varying properties, but in general they offer fast lookups, adds, and deletes. Go provides a built-in map type that implements a hash table.
+One of the most useful data structures in computer science is the hash table.
+Many hash table implementations exist with varying properties,
+but in general they offer fast lookups, adds, and deletes.
+Go provides a built-in map type that implements a hash table.
* Declaration and initialization
@@ -14,17 +17,29 @@
map[KeyType]ValueType
-where `KeyType` may be any type that is [[https://golang.org/ref/spec#Comparison_operators][comparable]] (more on this later), and `ValueType` may be any type at all, including another map!
+where `KeyType` may be any type that is [[https://golang.org/ref/spec#Comparison_operators][comparable]]
+(more on this later),
+and `ValueType` may be any type at all, including another map!
This variable `m` is a map of string keys to int values:
var m map[string]int
-Map types are reference types, like pointers or slices, and so the value of `m` above is `nil`; it doesn't point to an initialized map. A nil map behaves like an empty map when reading, but attempts to write to a nil map will cause a runtime panic; don't do that. To initialize a map, use the built in `make` function:
+Map types are reference types, like pointers or slices,
+and so the value of `m` above is `nil`;
+it doesn't point to an initialized map.
+A nil map behaves like an empty map when reading,
+but attempts to write to a nil map will cause a runtime panic; don't do that.
+To initialize a map, use the built in `make` function:
m = make(map[string]int)
-The `make` function allocates and initializes a hash map data structure and returns a map value that points to it. The specifics of that data structure are an implementation detail of the runtime and are not specified by the language itself. In this article we will focus on the _use_ of maps, not their implementation.
+The `make` function allocates and initializes a hash map data structure
+and returns a map value that points to it.
+The specifics of that data structure are an implementation detail of the
+runtime and are not specified by the language itself.
+In this article we will focus on the _use_ of maps,
+not their implementation.
* Working with maps
@@ -36,7 +51,8 @@
i := m["route"]
-If the requested key doesn't exist, we get the value type's _zero_value_. In this case the value type is `int`, so the zero value is `0`:
+If the requested key doesn't exist, we get the value type's _zero_value_.
+In this case the value type is `int`, so the zero value is `0`:
j := m["root"]
// j == 0
@@ -55,7 +71,10 @@
i, ok := m["route"]
-In this statement, the first value (`i`) is assigned the value stored under the key `"route"`. If that key doesn't exist, `i` is the value type's zero value (`0`). The second value (`ok`) is a `bool` that is `true` if the key exists in the map, and `false` if not.
+In this statement, the first value (`i`) is assigned the value stored under the key `"route"`.
+If that key doesn't exist, `i` is the value type's zero value (`0`).
+The second value (`ok`) is a `bool` that is `true` if the key exists in
+the map, and `false` if not.
To test for a key without retrieving the value, use an underscore in place of the first value:
@@ -84,13 +103,25 @@
It can be convenient that a map retrieval yields a zero value when the key is not present.
-For instance, a map of boolean values can be used as a set-like data structure (recall that the zero value for the boolean type is false). This example traverses a linked list of `Nodes` and prints their values. It uses a map of `Node` pointers to detect cycles in the list.
+For instance, a map of boolean values can be used as a set-like data structure
+(recall that the zero value for the boolean type is false).
+This example traverses a linked list of `Nodes` and prints their values.
+It uses a map of `Node` pointers to detect cycles in the list.
.code go-maps-in-action/list.go /START/,/END/
-The expression `visited[n]` is `true` if `n` has been visited, or `false` if `n` is not present. There's no need to use the two-value form to test for the presence of `n` in the map; the zero value default does it for us.
+The expression `visited[n]` is `true` if `n` has been visited,
+or `false` if `n` is not present.
+There's no need to use the two-value form to test for the presence of `n` in the map;
+the zero value default does it for us.
-Another instance of helpful zero values is a map of slices. Appending to a nil slice just allocates a new slice, so it's a one-liner to append a value to a map of slices; there's no need to check if the key exists. In the following example, the slice people is populated with `Person` values. Each `Person` has a `Name` and a slice of Likes. The example creates a map to associate each like with a slice of people that like it.
+Another instance of helpful zero values is a map of slices.
+Appending to a nil slice just allocates a new slice,
+so it's a one-liner to append a value to a map of slices;
+there's no need to check if the key exists.
+In the following example, the slice people is populated with `Person` values.
+Each `Person` has a `Name` and a slice of Likes.
+The example creates a map to associate each like with a slice of people that like it.
.code go-maps-in-action/people.go /START1/,/END1/
@@ -102,21 +133,39 @@
.code go-maps-in-action/people.go /bacon/
-Note that since both range and len treat a nil slice as a zero-length slice, these last two examples will work even if nobody likes cheese or bacon (however unlikely that may be).
+Note that since both range and len treat a nil slice as a zero-length slice,
+these last two examples will work even if nobody likes cheese or bacon (however
+unlikely that may be).
* Key types
-As mentioned earlier, map keys may be of any type that is comparable. The [[https://golang.org/ref/spec#Comparison_operators][language spec]] defines this precisely, but in short, comparable types are boolean, numeric, string, pointer, channel, and interface types, and structs or arrays that contain only those types. Notably absent from the list are slices, maps, and functions; these types cannot be compared using `==`, and may not be used as map keys.
+As mentioned earlier, map keys may be of any type that is comparable.
+The [[https://golang.org/ref/spec#Comparison_operators][language spec]]
+defines this precisely,
+but in short, comparable types are boolean,
+numeric, string, pointer, channel, and interface types,
+and structs or arrays that contain only those types.
+Notably absent from the list are slices, maps, and functions;
+these types cannot be compared using `==`,
+and may not be used as map keys.
-It's obvious that strings, ints, and other basic types should be available as map keys, but perhaps unexpected are struct keys. Struct can be used to key data by multiple dimensions. For example, this map of maps could be used to tally web page hits by country:
+It's obvious that strings, ints, and other basic types should be available as map keys,
+but perhaps unexpected are struct keys.
+Struct can be used to key data by multiple dimensions.
+For example, this map of maps could be used to tally web page hits by country:
hits := make(map[string]map[string]int)
-This is map of string to (map of `string` to `int`). Each key of the outer map is the path to a web page with its own inner map. Each inner map key is a two-letter country code. This expression retrieves the number of times an Australian has loaded the documentation page:
+This is map of string to (map of `string` to `int`).
+Each key of the outer map is the path to a web page with its own inner map.
+Each inner map key is a two-letter country code.
+This expression retrieves the number of times an Australian has loaded the documentation page:
n := hits["/doc/"]["au"]
-Unfortunately, this approach becomes unwieldy when adding data, as for any given outer key you must check if the inner map exists, and create it if needed:
+Unfortunately, this approach becomes unwieldy when adding data,
+as for any given outer key you must check if the inner map exists,
+and create it if needed:
func add(m map[string]map[string]int, path, country string) {
mm, ok := m[path]
@@ -135,7 +184,8 @@
}
hits := make(map[Key]int)
-When an Vietnamese person visits the home page, incrementing (and possibly creating) the appropriate counter is a one-liner:
+When an Vietnamese person visits the home page,
+incrementing (and possibly creating) the appropriate counter is a one-liner:
hits[Key{"/", "vn"}]++
@@ -145,9 +195,14 @@
* Concurrency
-[[https://golang.org/doc/faq#atomic_maps][Maps are not safe for concurrent use]]: it's not defined what happens when you read and write to them simultaneously. If you need to read from and write to a map from concurrently executing goroutines, the accesses must be mediated by some kind of synchronization mechanism. One common way to protect maps is with [[https://golang.org/pkg/sync/#RWMutex][sync.RWMutex]].
+[[https://golang.org/doc/faq#atomic_maps][Maps are not safe for concurrent use]]:
+it's not defined what happens when you read and write to them simultaneously.
+If you need to read from and write to a map from concurrently executing goroutines,
+the accesses must be mediated by some kind of synchronization mechanism.
+One common way to protect maps is with [[https://golang.org/pkg/sync/#RWMutex][sync.RWMutex]].
-This statement declares a `counter` variable that is an anonymous struct containing a map and an embedded `sync.RWMutex`.
+This statement declares a `counter` variable that is an anonymous struct
+containing a map and an embedded `sync.RWMutex`.
var counter = struct{
sync.RWMutex
@@ -170,7 +225,9 @@
* Iteration order
-When iterating over a map with a range loop, the iteration order is not specified and is not guaranteed to be the same from one iteration to the next.
+When iterating over a map with a range loop,
+the iteration order is not specified and is not guaranteed to be the same
+from one iteration to the next.
If you require a stable iteration order you must maintain a separate data structure that specifies that order.
This example uses a separate sorted slice of keys to print a `map[int]string` in key order:
diff --git a/content/go-one-year-ago-today.article b/content/go-one-year-ago-today.article
index 041da76..9391919 100644
--- a/content/go-one-year-ago-today.article
+++ b/content/go-one-year-ago-today.article
@@ -6,36 +6,141 @@
* Introduction
-On the 10th of November 2009 we launched the Go project: an open-source programming language with a focus on simplicity and efficiency. The intervening year has seen a great many developments both in the Go project itself and in its community.
+On the 10th of November 2009 we launched the Go project:
+an open-source programming language with a focus on simplicity and efficiency.
+The intervening year has seen a great many developments both in the Go project
+itself and in its community.
-We set out to build a language for systems programming - the kinds of programs one might typically write in C or C++ - and we were surprised by Go’s utility as a general purpose language. We had anticipated interest from C, C++, and Java programmers, but the flurry of interest from users of dynamically-typed languages like Python and JavaScript was unexpected. Go’s combination of native compilation, static typing, memory management, and lightweight syntax seemed to strike a chord with a broad cross-section of the programming community.
+We set out to build a language for systems programming - the kinds of programs
+one might typically write in C or C++ - and we were surprised by Go’s
+utility as a general purpose language.
+We had anticipated interest from C, C++, and Java programmers,
+but the flurry of interest from users of dynamically-typed languages like
+Python and JavaScript was unexpected.
+Go’s combination of native compilation,
+static typing, memory management, and lightweight syntax seemed to strike
+a chord with a broad cross-section of the programming community.
-That cross-section grew to become a dedicated community of enthusiastic Go coders. Our [[http://groups.google.com/group/golang-nuts][mailing list]] has over 3,800 members, with around 1,500 posts each month. The project has over 130 [[https://golang.org/CONTRIBUTORS][contributors]] (people who have submitted code or documentation), and of the 2,800 commits since launch almost one third were contributed by programmers outside the core team. To get all that code into shape, nearly 14,000 emails were exchanged on our [[http://groups.google.com/group/golang-dev][development mailing list]].
+That cross-section grew to become a dedicated community of enthusiastic Go coders.
+Our [[http://groups.google.com/group/golang-nuts][mailing list]] has over 3,800 members,
+with around 1,500 posts each month.
+The project has over 130 [[https://golang.org/CONTRIBUTORS][contributors]]
+(people who have submitted code or documentation),
+and of the 2,800 commits since launch almost one third were contributed
+by programmers outside the core team.
+To get all that code into shape, nearly 14,000 emails were exchanged on
+our [[http://groups.google.com/group/golang-dev][development mailing list]].
-Those numbers reflect a labor whose fruits are evident in the project’s code base. The compilers have improved substantially, with faster and more efficient code generation, more than one hundred reported bugs fixed, and support for a widening range of operating systems and architectures. The Windows port is approaching completion thanks to a dedicated group of contributors (one of whom became our first non-Google committer to the project). The ARM port has also made great progress, recently reaching the milestone of passing all tests.
+Those numbers reflect a labor whose fruits are evident in the project’s code base.
+The compilers have improved substantially,
+with faster and more efficient code generation,
+more than one hundred reported bugs fixed,
+and support for a widening range of operating systems and architectures.
+The Windows port is approaching completion thanks to a dedicated group of
+contributors (one of whom became our first non-Google committer to the project).
+The ARM port has also made great progress,
+recently reaching the milestone of passing all tests.
-The Go tool set has been expanded and improved. The Go documentation tool, [[https://golang.org/cmd/godoc/][godoc]], now supports the documentation of other source trees (you can browse and search your own code) and provides a [[https://golang.org/doc/codewalk/]["code walk"]] interface for presenting tutorial materials (among many more improvements). [[https://golang.org/cmd/goinstall/][Goinstall]] , a new package management tool, allows users to install and update external packages with a single command. [[https://golang.org/cmd/gofmt/][Gofmt]], the Go pretty-printer, now makes syntactic simplifications where possible. [[https://golang.org/misc/goplay/][Goplay]], a web-based “compile-as-you-type” tool, is a convenient way to experiment with Go for those times when you don’t have access to the [[https://golang.org/doc/play/][Go Playground]].
+The Go tool set has been expanded and improved.
+The Go documentation tool, [[https://golang.org/cmd/godoc/][godoc]],
+now supports the documentation of other source trees (you can browse and
+search your own code) and provides a [[https://golang.org/doc/codewalk/]["code walk"]]
+interface for presenting tutorial materials (among many more improvements).
+[[https://golang.org/cmd/goinstall/][Goinstall]] ,
+a new package management tool, allows users to install and update external
+packages with a single command.
+[[https://golang.org/cmd/gofmt/][Gofmt]],
+the Go pretty-printer, now makes syntactic simplifications where possible.
+[[https://golang.org/misc/goplay/][Goplay]],
+a web-based “compile-as-you-type” tool,
+is a convenient way to experiment with Go for those times when you don’t
+have access to the [[https://golang.org/doc/play/][Go Playground]].
-The standard library has grown by over 42,000 lines of code and includes 20 new [[https://golang.org/pkg/][packages]]. Among the additions are the [[https://golang.org/pkg/image/jpeg/][jpeg]], [[https://golang.org/pkg/rpc/jsonrpc/][jsonrpc]], [[https://golang.org/pkg/mime/][mime]], [[https://golang.org/pkg/netchan/][netchan]], and [[https://golang.org/pkg/smtp/][smtp]] packages, as well as a slew of new [[https://golang.org/pkg/crypto/][cryptography]] packages. More generally, the standard library has been continuously refined and revised as our understanding of Go’s idioms deepens.
+The standard library has grown by over 42,000 lines of code and includes
+20 new [[https://golang.org/pkg/][packages]].
+Among the additions are the [[https://golang.org/pkg/image/jpeg/][jpeg]],
+[[https://golang.org/pkg/rpc/jsonrpc/][jsonrpc]],
+[[https://golang.org/pkg/mime/][mime]], [[https://golang.org/pkg/netchan/][netchan]],
+and [[https://golang.org/pkg/smtp/][smtp]] packages,
+as well as a slew of new [[https://golang.org/pkg/crypto/][cryptography]] packages.
+More generally, the standard library has been continuously refined and revised
+as our understanding of Go’s idioms deepens.
-The debugging story has gotten better, too. Recent improvements to the DWARF output of the gc compilers make the GNU debugger, GDB, useful for Go binaries, and we’re actively working on making that debugging information more complete. (See the [[https://blog.golang.org/2010/11/debugging-go-code-status-report.html][ recent blog post]] for details.)
+The debugging story has gotten better, too.
+Recent improvements to the DWARF output of the gc compilers make the GNU debugger,
+GDB, useful for Go binaries, and we’re actively working on making that
+debugging information more complete.
+(See the [[https://blog.golang.org/2010/11/debugging-go-code-status-report.html][ recent blog post]] for details.)
-It’s now easier than ever to link against existing libraries written in languages other than Go. Go support is in the most recent [[http://www.swig.org/][SWIG]] release, version 2.0.1, making it easier to link against C and C++ code, and our [[https://golang.org/cmd/cgo/][cgo]] tool has seen many fixes and improvements.
+It’s now easier than ever to link against existing libraries written in
+languages other than Go.
+Go support is in the most recent [[http://www.swig.org/][SWIG]] release,
+version 2.0.1, making it easier to link against C and C++ code,
+and our [[https://golang.org/cmd/cgo/][cgo]] tool has seen many fixes and improvements.
-[[https://golang.org/doc/gccgo_install.html][Gccgo]], the Go front end for the GNU C Compiler, has kept pace with the gc compiler as a parallel Go implementation. It now has a working garbage collector, and has been accepted into the GCC core. We’re now working toward making [[http://code.google.com/p/gofrontend/][gofrontend]] available as a BSD-licensed Go compiler front end, fully decoupled from GCC.
+[[https://golang.org/doc/gccgo_install.html][Gccgo]],
+the Go front end for the GNU C Compiler, has kept pace with the gc compiler
+as a parallel Go implementation.
+It now has a working garbage collector, and has been accepted into the GCC core.
+We’re now working toward making [[http://code.google.com/p/gofrontend/][gofrontend]]
+available as a BSD-licensed Go compiler front end,
+fully decoupled from GCC.
-Outside the Go project itself Go is starting to be used to build real software. There are more than 200 Go programs and libraries listed on our [[http://godashboard.appspot.com/project][Project dashboard]], and hundreds more on [[http://code.google.com/hosting/search?q=label:Go][Google Code]] and [[https://github.com/search?q=language:Go][Github]]. On our mailing list and IRC channel you can find coders from around the world who use Go for their programming projects. (See our [[https://blog.golang.org/2010/10/real-go-projects-smarttwitter-and-webgo.html][guest blog post]] from last month for a real-world example.) Internally at Google there are several teams that choose Go for building production software, and we have received reports from other companies that are developing sizable systems in Go. We have also been in touch with several educators who are using Go as a teaching language.
+Outside the Go project itself Go is starting to be used to build real software.
+There are more than 200 Go programs and libraries listed on our [[http://godashboard.appspot.com/project][Project dashboard]],
+and hundreds more on [[http://code.google.com/hosting/search?q=label:Go][Google Code]]
+and [[https://github.com/search?q=language:Go][Github]].
+On our mailing list and IRC channel you can find coders from around the
+world who use Go for their programming projects.
+(See our [[https://blog.golang.org/2010/10/real-go-projects-smarttwitter-and-webgo.html][guest blog post]]
+from last month for a real-world example.) Internally at Google there are
+several teams that choose Go for building production software,
+and we have received reports from other companies that are developing sizable systems in Go.
+We have also been in touch with several educators who are using Go as a teaching language.
-The language itself has grown and matured, too. In the past year we have received many feature requests. But Go is a small language, and we’ve worked hard to ensure that any new feature strikes the right compromise between simplicity and utility. Since the launch we have made a number of language changes, many of which were driven by feedback from the community.
+The language itself has grown and matured, too.
+In the past year we have received many feature requests.
+But Go is a small language, and we’ve worked hard to ensure that any new
+feature strikes the right compromise between simplicity and utility.
+Since the launch we have made a number of language changes,
+many of which were driven by feedback from the community.
- Semicolons are now optional in almost all instances. [[https://golang.org/doc/go_spec.html#Semicolons][spec]]
-- The new built-in functions `copy` and `append` make management of slices more efficient and straightforward. [[https://golang.org/doc/go_spec.html#Appending_and_copying_slices][spec]]
-- The upper and lower bounds may be omitted when making a sub-slice. This means that `s[:]` is shorthand for `s[0:len(s)]`. [[https://golang.org/doc/go_spec.html#Slices][spec]]
-- The new built-in function `recover` complements `panic` and `defer` as an error handling mechanism. [[https://blog.golang.org/2010/08/defer-panic-and-recover.html][blog]], [[https://golang.org/doc/go_spec.html#Handling_panics][spec]]
-- The new complex number types (`complex`, `complex64`, and `complex128`) simplify certain mathematical operations. [[https://golang.org/doc/go_spec.html#Complex_numbers][spec]], [[https://golang.org/doc/go_spec.html#Imaginary_literals][spec]]
-- The composite literal syntax permits the omission of redundant type information (when specifying two-dimensional arrays, for example). [[https://golang.org/doc/devel/release.html#2010-10-27][release.2010-10-27]], [[https://golang.org/doc/go_spec.html#Composite_literals][spec]]
-- A general syntax for variable function arguments (`...T`) and their propagation (`v...`) is now specified. [[https://golang.org/doc/go_spec.html#Function_Types][spec]], [[https://golang.org/doc/go_spec.html#Passing_arguments_to_..._parameters][ spec]], [[https://golang.org/doc/devel/release.html#2010-09-29][release.2010-09-29]]
+- The new built-in functions `copy` and `append` make management of slices
+ more efficient and straightforward.
+ [[https://golang.org/doc/go_spec.html#Appending_and_copying_slices][spec]]
+- The upper and lower bounds may be omitted when making a sub-slice.
+ This means that `s[:]` is shorthand for `s[0:len(s)]`.
+ [[https://golang.org/doc/go_spec.html#Slices][spec]]
+- The new built-in function `recover` complements `panic` and `defer` as
+ an error handling mechanism.
+ [[https://blog.golang.org/2010/08/defer-panic-and-recover.html][blog]],
+ [[https://golang.org/doc/go_spec.html#Handling_panics][spec]]
+- The new complex number types (`complex`,
+ `complex64`, and `complex128`) simplify certain mathematical operations.
+ [[https://golang.org/doc/go_spec.html#Complex_numbers][spec]],
+ [[https://golang.org/doc/go_spec.html#Imaginary_literals][spec]]
+- The composite literal syntax permits the omission of redundant type information
+ (when specifying two-dimensional arrays, for example).
+ [[https://golang.org/doc/devel/release.html#2010-10-27][release.2010-10-27]],
+ [[https://golang.org/doc/go_spec.html#Composite_literals][spec]]
+- A general syntax for variable function arguments (`...T`) and their propagation
+ (`v...`) is now specified.
+ [[https://golang.org/doc/go_spec.html#Function_Types][spec]],
+ [[https://golang.org/doc/go_spec.html#Passing_arguments_to_..._parameters][ spec]],
+ [[https://golang.org/doc/devel/release.html#2010-09-29][release.2010-09-29]]
-Go is certainly ready for production use, but there is still room for improvement. Our focus for the immediate future is making Go programs faster and more efficient in the context of high performance systems. This means improving the garbage collector, optimizing generated code, and improving the core libraries. We’re also exploring some further additions to the type system to make generic programming easier. A lot has happened in a year; it’s been both thrilling and satisfying. We hope that this coming year will be even more fruitful than the last.
+Go is certainly ready for production use,
+but there is still room for improvement.
+Our focus for the immediate future is making Go programs faster and more
+efficient in the context of high performance systems.
+This means improving the garbage collector,
+optimizing generated code, and improving the core libraries.
+We’re also exploring some further additions to the type system to make
+generic programming easier.
+A lot has happened in a year; it’s been both thrilling and satisfying.
+We hope that this coming year will be even more fruitful than the last.
-_If_you’ve_been_meaning_to_get_[back]_into_Go,_now_is_a_great_time_to_do_so!_Check_out_the_ [[https://golang.org/doc/docs.html][_Documentation_]] _and_ [[https://golang.org/doc/install.html][_Getting_Started_]] _pages_for_more_information,_or_just_go_nuts_in_the_ [[https://golang.org/doc/play/][_Go_Playground_]].
+_If_you’ve_been_meaning_to_get_[back]_into_Go,_now_is_a_great_time_to_do_so!_Check_out_the_
+[[https://golang.org/doc/docs.html][_Documentation_]] _and_ [[https://golang.org/doc/install.html][_Getting_Started_]]
+_pages_for_more_information,_or_just_go_nuts_in_the_ [[https://golang.org/doc/play/][_Go_Playground_]].
diff --git a/content/go-programming-language-turns-two.article b/content/go-programming-language-turns-two.article
index 2e749bd..5b20144 100644
--- a/content/go-programming-language-turns-two.article
+++ b/content/go-programming-language-turns-two.article
@@ -6,18 +6,64 @@
* Introduction
-Two years ago a small team at Google went public with their fledgling project - the Go Programming Language. They presented a language spec, two compilers, a modest standard library, some novel tools, and plenty of accurate (albeit succinct) documentation. They watched with excitement as programmers around the world began to play with Go. The team continued to iterate and improve on what they had built, and were gradually joined by dozens - and then hundreds - of programmers from the open source community.
-The Go Authors went on to produce lots of libraries, new tools, and reams of [[https://golang.org/doc/docs.html][documentation]]. They celebrated a successful year in the public eye with a [[https://blog.golang.org/2010/11/go-one-year-ago-today.html][blog post]] last November that concluded "Go is certainly ready for production use, but there is still room for improvement. Our focus for the immediate future is making Go programs faster and more efficient in the context of high performance systems."
+Two years ago a small team at Google went public with their fledgling project -
+the Go Programming Language.
+They presented a language spec, two compilers,
+a modest standard library, some novel tools,
+and plenty of accurate (albeit succinct) documentation.
+They watched with excitement as programmers around the world began to play with Go.
+The team continued to iterate and improve on what they had built,
+and were gradually joined by dozens - and then hundreds - of programmers
+from the open source community.
+The Go Authors went on to produce lots of libraries,
+new tools, and reams of [[https://golang.org/doc/docs.html][documentation]].
+They celebrated a successful year in the public eye with a [[https://blog.golang.org/2010/11/go-one-year-ago-today.html][blog post]]
+last November that concluded "Go is certainly ready for production use,
+but there is still room for improvement.
+Our focus for the immediate future is making Go programs faster and more
+efficient in the context of high performance systems."
-Today is the second anniversary of Go's release, and Go is faster and more stable than ever. Careful tuning of Go's code generators, concurrency primitives, garbage collector, and core libraries have increased the performance of Go programs, and native support for [[https://blog.golang.org/2011/06/profiling-go-programs.html][profiling]] and [[http://blog.golang.org/2011/10/debugging-go-programs-with-gnu-debugger.html][debugging]] makes it easier to detect and remove performance issues in user code. Go is also now easier to learn with [[http://tour.golang.org/][A Tour of Go]], an interactive tutorial you can take from the comfort of your web browser.
+Today is the second anniversary of Go's release,
+and Go is faster and more stable than ever.
+Careful tuning of Go's code generators, concurrency primitives,
+garbage collector, and core libraries have increased the performance of Go programs,
+and native support for [[https://blog.golang.org/2011/06/profiling-go-programs.html][profiling]]
+and [[http://blog.golang.org/2011/10/debugging-go-programs-with-gnu-debugger.html][debugging]]
+makes it easier to detect and remove performance issues in user code.
+Go is also now easier to learn with [[http://tour.golang.org/][A Tour of Go]],
+an interactive tutorial you can take from the comfort of your web browser.
-This year we introduced the experimental [[http://code.google.com/appengine/docs/go/][Go runtime]] for Google's App Engine platform, and we have been steadily increasing the Go runtime's support for App Engine's APIs. Just this week we released [[http://code.google.com/appengine/downloads.html][version 1.6.0]] of the Go App Engine SDK, which includes support for [[http://code.google.com/appengine/docs/go/backends/overview.html][backends]] (long-running processes), finer control over datastore indexes, and various other improvements. Today, the Go runtime is near feature parity with - and is a viable alternative to - the Python and Java runtimes. In fact, we now serve [[https://golang.org/][golang.org]] by running a version of [[https://golang.org/cmd/godoc/][godoc]] on the App Engine service.
+This year we introduced the experimental [[http://code.google.com/appengine/docs/go/][Go runtime]]
+for Google's App Engine platform,
+and we have been steadily increasing the Go runtime's support for App Engine's APIs.
+Just this week we released [[http://code.google.com/appengine/downloads.html][version 1.6.0]]
+of the Go App Engine SDK,
+which includes support for [[http://code.google.com/appengine/docs/go/backends/overview.html][backends]]
+(long-running processes),
+finer control over datastore indexes, and various other improvements.
+Today, the Go runtime is near feature parity with - and is a viable alternative
+to - the Python and Java runtimes.
+In fact, we now serve [[https://golang.org/][golang.org]] by running a version
+of [[https://golang.org/cmd/godoc/][godoc]] on the App Engine service.
-While 2010 was a year of discovery and experimentation, 2011 was a year of fine tuning and planning for the future. This year we issued several "[[https://golang.org/doc/devel/release.html][release]]" versions of Go that were more reliable and better supported than weekly snapshots. We also introduced [[https://golang.org/cmd/gofix/][gofix]] to take the pain out of migrating to newer releases. Furthermore, last month we announced a [[https://blog.golang.org/2011/10/preview-of-go-version-1.html][plan for Go version 1]] - a release that will be supported for years to come. Work toward Go 1 is already underway and you can observe our progress by the latest weekly snapshot at [[http://weekly.golang.org/pkg/][weekly.golang.org]].
+While 2010 was a year of discovery and experimentation,
+2011 was a year of fine tuning and planning for the future.
+This year we issued several "[[https://golang.org/doc/devel/release.html][release]]"
+versions of Go that were more reliable and better supported than weekly snapshots.
+We also introduced [[https://golang.org/cmd/gofix/][gofix]] to take the
+pain out of migrating to newer releases.
+Furthermore, last month we announced a [[https://blog.golang.org/2011/10/preview-of-go-version-1.html][plan for Go version 1]] -
+a release that will be supported for years to come.
+Work toward Go 1 is already underway and you can observe our progress by
+the latest weekly snapshot at [[http://weekly.golang.org/pkg/][weekly.golang.org]].
-The plan is to launch Go 1 in early 2012. We hope to bring the Go App Engine runtime out of "experimental" status at the same time.
+The plan is to launch Go 1 in early 2012.
+We hope to bring the Go App Engine runtime out of "experimental" status at the same time.
-But that's not all. 2011 was an exciting year for the gopher, too. He has manifested himself as a plush toy (a highly prized gift at Google I/O and other Go talks) and in vinyl form (received by every attendee at OSCON and now available at the [[http://www.googlestore.com/Fun/Go+Gopher+Figurine.axd][Google Store]]).
+But that's not all. 2011 was an exciting year for the gopher, too.
+He has manifested himself as a plush toy (a highly prized gift at Google
+I/O and other Go talks) and in vinyl form (received by every attendee at
+OSCON and now available at the [[http://www.googlestore.com/Fun/Go+Gopher+Figurine.axd][Google Store]]).
.image go-programming-language-turns-two_gophers.jpg
diff --git a/content/go-slices-usage-and-internals.article b/content/go-slices-usage-and-internals.article
index d4c8dc5..5a9b890 100644
--- a/content/go-slices-usage-and-internals.article
+++ b/content/go-slices-usage-and-internals.article
@@ -6,20 +6,31 @@
* Introduction
-Go's slice type provides a convenient and efficient means of working with sequences of typed data. Slices are analogous to arrays in other languages, but have some unusual properties. This article will look at what slices are and how they are used.
+Go's slice type provides a convenient and efficient means of working with
+sequences of typed data.
+Slices are analogous to arrays in other languages,
+but have some unusual properties.
+This article will look at what slices are and how they are used.
* Arrays
-The slice type is an abstraction built on top of Go's array type, and so to understand slices we must first understand arrays.
+The slice type is an abstraction built on top of Go's array type,
+and so to understand slices we must first understand arrays.
-An array type definition specifies a length and an element type. For example, the type `[4]int` represents an array of four integers. An array's size is fixed; its length is part of its type (`[4]int` and `[5]int` are distinct, incompatible types). Arrays can be indexed in the usual way, so the expression `s[n]` accesses the nth element, starting from zero.
+An array type definition specifies a length and an element type.
+For example, the type `[4]int` represents an array of four integers.
+An array's size is fixed; its length is part of its type (`[4]int` and `[5]int` are distinct,
+incompatible types).
+Arrays can be indexed in the usual way, so the expression `s[n]` accesses
+the nth element, starting from zero.
var a [4]int
a[0] = 1
i := a[0]
// i == 1
-Arrays do not need to be initialized explicitly; the zero value of an array is a ready-to-use array whose elements are themselves zeroed:
+Arrays do not need to be initialized explicitly;
+the zero value of an array is a ready-to-use array whose elements are themselves zeroed:
// a[2] == 0, the zero value of the int type
@@ -27,7 +38,14 @@
.image go-slices-usage-and-internals_slice-array.png
-Go's arrays are values. An array variable denotes the entire array; it is not a pointer to the first array element (as would be the case in C). This means that when you assign or pass around an array value you will make a copy of its contents. (To avoid the copy you could pass a _pointer_ to the array, but then that's a pointer to an array, not an array.) One way to think about arrays is as a sort of struct but with indexed rather than named fields: a fixed-size composite value.
+Go's arrays are values. An array variable denotes the entire array;
+it is not a pointer to the first array element (as would be the case in C).
+This means that when you assign or pass around an array value you will make
+a copy of its contents.
+(To avoid the copy you could pass a _pointer_ to the array,
+but then that's a pointer to an array, not an array.) One way to think about
+arrays is as a sort of struct but with indexed rather than named fields:
+a fixed-size composite value.
An array literal can be specified like so:
@@ -41,9 +59,13 @@
* Slices
-Arrays have their place, but they're a bit inflexible, so you don't see them too often in Go code. Slices, though, are everywhere. They build on arrays to provide great power and convenience.
+Arrays have their place, but they're a bit inflexible,
+so you don't see them too often in Go code.
+Slices, though, are everywhere. They build on arrays to provide great power and convenience.
-The type specification for a slice is `[]T`, where `T` is the type of the elements of the slice. Unlike an array type, a slice type has no specified length.
+The type specification for a slice is `[]T`,
+where `T` is the type of the elements of the slice.
+Unlike an array type, a slice type has no specified length.
A slice literal is declared just like an array literal, except you leave out the element count:
@@ -53,13 +75,17 @@
func make([]T, len, cap) []T
-where T stands for the element type of the slice to be created. The `make` function takes a type, a length, and an optional capacity. When called, `make` allocates an array and returns a slice that refers to that array.
+where T stands for the element type of the slice to be created.
+The `make` function takes a type, a length,
+and an optional capacity.
+When called, `make` allocates an array and returns a slice that refers to that array.
var s []byte
s = make([]byte, 5, 5)
// s == []byte{0, 0, 0, 0, 0}
-When the capacity argument is omitted, it defaults to the specified length. Here's a more succinct version of the same code:
+When the capacity argument is omitted, it defaults to the specified length.
+Here's a more succinct version of the same code:
s := make([]byte, 5)
@@ -72,7 +98,10 @@
The zero value of a slice is `nil`. The `len` and `cap` functions will both return 0 for a nil slice.
-A slice can also be formed by "slicing" an existing slice or array. Slicing is done by specifying a half-open range with two indices separated by a colon. For example, the expression `b[1:4]` creates a slice including elements 1 through 3 of `b` (the indices of the resulting slice will be 0 through 2).
+A slice can also be formed by "slicing" an existing slice or array.
+Slicing is done by specifying a half-open range with two indices separated by a colon.
+For example, the expression `b[1:4]` creates a slice including elements
+1 through 3 of `b` (the indices of the resulting slice will be 0 through 2).
b := []byte{'g', 'o', 'l', 'a', 'n', 'g'}
// b[1:4] == []byte{'o', 'l', 'a'}, sharing the same storage as b
@@ -90,7 +119,9 @@
* Slice internals
-A slice is a descriptor of an array segment. It consists of a pointer to the array, the length of the segment, and its capacity (the maximum length of the segment).
+A slice is a descriptor of an array segment.
+It consists of a pointer to the array, the length of the segment,
+and its capacity (the maximum length of the segment).
.image go-slices-usage-and-internals_slice-struct.png
@@ -98,7 +129,11 @@
.image go-slices-usage-and-internals_slice-1.png
-The length is the number of elements referred to by the slice. The capacity is the number of elements in the underlying array (beginning at the element referred to by the slice pointer). The distinction between length and capacity will be made clear as we walk through the next few examples.
+The length is the number of elements referred to by the slice.
+The capacity is the number of elements in the underlying array (beginning
+at the element referred to by the slice pointer).
+The distinction between length and capacity will be made clear as we walk
+through the next few examples.
As we slice `s`, observe the changes in the slice data structure and their relation to the underlying array:
@@ -106,7 +141,11 @@
.image go-slices-usage-and-internals_slice-2.png
-Slicing does not copy the slice's data. It creates a new slice value that points to the original array. This makes slice operations as efficient as manipulating array indices. Therefore, modifying the _elements_ (not the slice itself) of a re-slice modifies the elements of the original slice:
+Slicing does not copy the slice's data. It creates a new slice value that
+points to the original array.
+This makes slice operations as efficient as manipulating array indices.
+Therefore, modifying the _elements_ (not the slice itself) of a re-slice
+modifies the elements of the original slice:
d := []byte{'r', 'o', 'a', 'd'}
e := d[2:]
@@ -121,11 +160,20 @@
.image go-slices-usage-and-internals_slice-3.png
-A slice cannot be grown beyond its capacity. Attempting to do so will cause a runtime panic, just as when indexing outside the bounds of a slice or array. Similarly, slices cannot be re-sliced below zero to access earlier elements in the array.
+A slice cannot be grown beyond its capacity.
+Attempting to do so will cause a runtime panic,
+just as when indexing outside the bounds of a slice or array.
+Similarly, slices cannot be re-sliced below zero to access earlier elements in the array.
* Growing slices (the copy and append functions)
-To increase the capacity of a slice one must create a new, larger slice and copy the contents of the original slice into it. This technique is how dynamic array implementations from other languages work behind the scenes. The next example doubles the capacity of `s` by making a new slice, `t`, copying the contents of `s` into `t`, and then assigning the slice value `t` to `s`:
+To increase the capacity of a slice one must create a new,
+larger slice and copy the contents of the original slice into it.
+This technique is how dynamic array implementations from other languages
+work behind the scenes.
+The next example doubles the capacity of `s` by making a new slice,
+`t`, copying the contents of `s` into `t`,
+and then assigning the slice value `t` to `s`:
t := make([]byte, len(s), (cap(s)+1)*2) // +1 in case cap(s) == 0
for i := range s {
@@ -133,11 +181,17 @@
}
s = t
-The looping piece of this common operation is made easier by the built-in copy function. As the name suggests, copy copies data from a source slice to a destination slice. It returns the number of elements copied.
+The looping piece of this common operation is made easier by the built-in copy function.
+As the name suggests, copy copies data from a source slice to a destination slice.
+It returns the number of elements copied.
func copy(dst, src []T) int
-The `copy` function supports copying between slices of different lengths (it will copy only up to the smaller number of elements). In addition, `copy` can handle source and destination slices that share the same underlying array, handling overlapping slices correctly.
+The `copy` function supports copying between slices of different lengths
+(it will copy only up to the smaller number of elements).
+In addition, `copy` can handle source and destination slices that share
+the same underlying array,
+handling overlapping slices correctly.
Using `copy`, we can simplify the code snippet above:
@@ -145,7 +199,9 @@
copy(t, s)
s = t
-A common operation is to append data to the end of a slice. This function appends byte elements to a slice of bytes, growing the slice if necessary, and returns the updated slice value:
+A common operation is to append data to the end of a slice.
+This function appends byte elements to a slice of bytes,
+growing the slice if necessary, and returns the updated slice value:
func AppendByte(slice []byte, data ...byte) []byte {
m := len(slice)
@@ -167,13 +223,20 @@
p = AppendByte(p, 7, 11, 13)
// p == []byte{2, 3, 5, 7, 11, 13}
-Functions like `AppendByte` are useful because they offer complete control over the way the slice is grown. Depending on the characteristics of the program, it may be desirable to allocate in smaller or larger chunks, or to put a ceiling on the size of a reallocation.
+Functions like `AppendByte` are useful because they offer complete control
+over the way the slice is grown.
+Depending on the characteristics of the program,
+it may be desirable to allocate in smaller or larger chunks,
+or to put a ceiling on the size of a reallocation.
-But most programs don't need complete control, so Go provides a built-in `append` function that's good for most purposes; it has the signature
+But most programs don't need complete control,
+so Go provides a built-in `append` function that's good for most purposes;
+it has the signature
func append(s []T, x ...T) []T
-The `append` function appends the elements `x` to the end of the slice `s`, and grows the slice if a greater capacity is needed.
+The `append` function appends the elements `x` to the end of the slice `s`,
+and grows the slice if a greater capacity is needed.
a := make([]int, 1)
// a == []int{0}
@@ -187,7 +250,8 @@
a = append(a, b...) // equivalent to "append(a, b[0], b[1], b[2])"
// a == []string{"John", "Paul", "George", "Ringo", "Pete"}
-Since the zero value of a slice (`nil`) acts like a zero-length slice, you can declare a slice variable and then append to it in a loop:
+Since the zero value of a slice (`nil`) acts like a zero-length slice,
+you can declare a slice variable and then append to it in a loop:
// Filter returns a new slice holding only
// the elements of s that satisfy fn()
@@ -203,9 +267,14 @@
* A possible "gotcha"
-As mentioned earlier, re-slicing a slice doesn't make a copy of the underlying array. The full array will be kept in memory until it is no longer referenced. Occasionally this can cause the program to hold all the data in memory when only a small piece of it is needed.
+As mentioned earlier, re-slicing a slice doesn't make a copy of the underlying array.
+The full array will be kept in memory until it is no longer referenced.
+Occasionally this can cause the program to hold all the data in memory when
+only a small piece of it is needed.
-For example, this `FindDigits` function loads a file into memory and searches it for the first group of consecutive numeric digits, returning them as a new slice.
+For example, this `FindDigits` function loads a file into memory and searches
+it for the first group of consecutive numeric digits,
+returning them as a new slice.
var digitRegexp = regexp.MustCompile("[0-9]+")
@@ -214,7 +283,11 @@
return digitRegexp.Find(b)
}
-This code behaves as advertised, but the returned `[]byte` points into an array containing the entire file. Since the slice references the original array, as long as the slice is kept around the garbage collector can't release the array; the few useful bytes of the file keep the entire contents in memory.
+This code behaves as advertised, but the returned `[]byte` points into an
+array containing the entire file.
+Since the slice references the original array,
+as long as the slice is kept around the garbage collector can't release the array;
+the few useful bytes of the file keep the entire contents in memory.
To fix this problem one can copy the interesting data to a new slice before returning it:
@@ -226,8 +299,16 @@
return c
}
-A more concise version of this function could be constructed by using `append`. This is left as an exercise for the reader.
+A more concise version of this function could be constructed by using `append`.
+This is left as an exercise for the reader.
* Further Reading
-[[https://golang.org/doc/effective_go.html][Effective Go]] contains an in-depth treatment of [[https://golang.org/doc/effective_go.html#slices][slices]] and [[https://golang.org/doc/effective_go.html#arrays][arrays]], and the Go [[https://golang.org/doc/go_spec.html][language specification]] defines [[https://golang.org/doc/go_spec.html#Slice_types][slices]] and their [[https://golang.org/doc/go_spec.html#Length_and_capacity][associated]] [[https://golang.org/doc/go_spec.html#Making_slices_maps_and_channels][helper]] [[https://golang.org/doc/go_spec.html#Appending_and_copying_slices][functions]].
+[[https://golang.org/doc/effective_go.html][Effective Go]] contains an in-depth
+treatment of [[https://golang.org/doc/effective_go.html#slices][slices]]
+and [[https://golang.org/doc/effective_go.html#arrays][arrays]],
+and the Go [[https://golang.org/doc/go_spec.html][language specification]]
+defines [[https://golang.org/doc/go_spec.html#Slice_types][slices]] and
+their [[https://golang.org/doc/go_spec.html#Length_and_capacity][associated]]
+[[https://golang.org/doc/go_spec.html#Making_slices_maps_and_channels][helper]]
+[[https://golang.org/doc/go_spec.html#Appending_and_copying_slices][functions]].
diff --git a/content/go-updates-in-app-engine-171.article b/content/go-updates-in-app-engine-171.article
index a1b0b69..c51a026 100644
--- a/content/go-updates-in-app-engine-171.article
+++ b/content/go-updates-in-app-engine-171.article
@@ -6,16 +6,38 @@
* Introduction
-This week we released version 1.7.1 of the App Engine SDK. It includes some significant updates specific to the App Engine runtime for Go.
+This week we released version 1.7.1 of the App Engine SDK.
+It includes some significant updates specific to the App Engine runtime for Go.
-The [[https://developers.google.com/appengine/docs/go/memcache/reference][memcache package]] has had some additions to its [[https://developers.google.com/appengine/docs/go/memcache/reference#Codec][Codec]] convenience type. The SetMulti, AddMulti, CompareAndSwap, and CompareAndSwapMulti methods make it easier to store and update encoded data in the [[https://developers.google.com/appengine/docs/go/memcache/overview][Memcache Service]].
+The [[https://developers.google.com/appengine/docs/go/memcache/reference][memcache package]] has
+had some additions to its [[https://developers.google.com/appengine/docs/go/memcache/reference#Codec][Codec]] convenience type.
+The SetMulti, AddMulti, CompareAndSwap, and CompareAndSwapMulti methods
+make it easier to store and update encoded data in the [[https://developers.google.com/appengine/docs/go/memcache/overview][Memcache Service]].
-The [[https://developers.google.com/appengine/docs/go/tools/uploadingdata][bulkloader tool]] can now be used with Go apps, allowing users to upload and download datastore records in bulk. This is useful for backups and offline processing, and a great help when migrating Python or Java apps to the Go runtime.
+The [[https://developers.google.com/appengine/docs/go/tools/uploadingdata][bulkloader tool]] can
+now be used with Go apps,
+allowing users to upload and download datastore records in bulk.
+This is useful for backups and offline processing,
+and a great help when migrating Python or Java apps to the Go runtime.
-The [[https://developers.google.com/appengine/docs/go/images/overview][Images Service]] is now available to Go users. The new [[https://developers.google.com/appengine/docs/go/images/reference][appengine/image package]] supports serving images directly from Blobstore and resizing or cropping those images on the fly. Note that this is not the full image service as provided by the Python and Java SDKs, as much of the equivalent functionality is available in the [[https://golang.org/pkg/image/][standard Go image package]] and external packages such as [[http://code.google.com/p/graphics-go/][graphics-go]].
+The [[https://developers.google.com/appengine/docs/go/images/overview][Images Service]] is
+now available to Go users.
+The new [[https://developers.google.com/appengine/docs/go/images/reference][appengine/image package]] supports serving
+images directly from Blobstore and resizing or cropping those images on the fly.
+Note that this is not the full image service as provided by the Python and Java SDKs,
+as much of the equivalent functionality is available in the [[https://golang.org/pkg/image/][standard Go image package]] and
+external packages such as [[http://code.google.com/p/graphics-go/][graphics-go]].
-The new [[https://developers.google.com/appengine/docs/go/backends/runtime#RunInBackground][runtime.RunInBackground]] function allows backend requests to spawn a new request independent of the initial request. These can run in the background as long as the backend stays alive.
+The new [[https://developers.google.com/appengine/docs/go/backends/runtime#RunInBackground][runtime.RunInBackground]] function
+allows backend requests to spawn a new request independent of the initial request.
+These can run in the background as long as the backend stays alive.
-Finally, we have filled in some missing functionality: the [[https://developers.google.com/appengine/docs/go/xmpp/reference][xmpp package]] now supports sending presence updates and chat invitations and retrieving the presence state of another user, and the [[https://developers.google.com/appengine/docs/go/users/reference][user package]] supports authenticating clients with OAuth.
+Finally, we have filled in some missing functionality:
+the [[https://developers.google.com/appengine/docs/go/xmpp/reference][xmpp package]] now
+supports sending presence updates and chat invitations and retrieving the
+presence state of another user,
+and the [[https://developers.google.com/appengine/docs/go/users/reference][user package]] supports
+authenticating clients with OAuth.
-You can grab the new SDK from the [[https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_for_Go][App Engine downloads page]] and browse the [[https://developers.google.com/appengine/docs/go][updated documentation]].
+You can grab the new SDK from the [[https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_for_Go][App Engine downloads page]] and
+browse the [[https://developers.google.com/appengine/docs/go][updated documentation]].
diff --git a/content/go-version-1-is-released.article b/content/go-version-1-is-released.article
index c7bd526..c415f87 100644
--- a/content/go-version-1-is-released.article
+++ b/content/go-version-1-is-released.article
@@ -7,22 +7,67 @@
* Introduction
.image go-version-1-is-released_gophermega.jpg
-Today marks a major milestone in the development of the Go programming language. We're announcing Go version 1, or Go 1 for short, which defines a language and a set of core libraries to provide a stable foundation for creating reliable products, projects, and publications.
+Today marks a major milestone in the development of the Go programming language.
+We're announcing Go version 1, or Go 1 for short,
+which defines a language and a set of core libraries to provide a stable
+foundation for creating reliable products,
+projects, and publications.
-Go 1 is the first release of Go that is available in supported binary distributions. They are available for Linux, FreeBSD, Mac OS X and, we are thrilled to announce, Windows.
+Go 1 is the first release of Go that is available in supported binary distributions.
+They are available for Linux, FreeBSD, Mac OS X and,
+we are thrilled to announce, Windows.
-The driving motivation for Go 1 is stability for its users. People who write Go 1 programs can be confident that those programs will continue to compile and run without change, in many environments, on a time scale of years. Similarly, authors who write books about Go 1 can be sure that their examples and explanations will be helpful to readers today and into the future.
+The driving motivation for Go 1 is stability for its users.
+People who write Go 1 programs can be confident that those programs will
+continue to compile and run without change,
+in many environments, on a time scale of years.
+Similarly, authors who write books about Go 1 can be sure that their examples
+and explanations will be helpful to readers today and into the future.
-Forward compatibility is part of stability. Code that compiles in Go 1 should, with few exceptions, continue to compile and run throughout the lifetime of that version, even as we issue updates and bug fixes such as Go version 1.1, 1.2, and so on. The [[https://golang.org/doc/go1compat.html][Go 1 compatibility document]] explains the compatibility guidelines in more detail.
+Forward compatibility is part of stability.
+Code that compiles in Go 1 should, with few exceptions,
+continue to compile and run throughout the lifetime of that version,
+even as we issue updates and bug fixes such as Go version 1.1, 1.2, and so on.
+The [[https://golang.org/doc/go1compat.html][Go 1 compatibility document]]
+explains the compatibility guidelines in more detail.
-Go 1 is a representation of Go as it is used today, not a major redesign. In its planning, we focused on cleaning up problems and inconsistencies and improving portability. There had long been many changes to Go that we had designed and prototyped but not released because they were backwards-incompatible. Go 1 incorporates these changes, which provide significant improvements to the language and libraries but sometimes introduce incompatibilities for old programs. Fortunately, the [[https://golang.org/cmd/go/#Run_go_tool_fix_on_packages][go fix]] tool can automate much of the work needed to bring programs up to the Go 1 standard.
+Go 1 is a representation of Go as it is used today,
+not a major redesign.
+In its planning, we focused on cleaning up problems and inconsistencies
+and improving portability.
+There had long been many changes to Go that we had designed and prototyped
+but not released because they were backwards-incompatible.
+Go 1 incorporates these changes, which provide significant improvements
+to the language and libraries but sometimes introduce incompatibilities for old programs.
+Fortunately, the [[https://golang.org/cmd/go/#Run_go_tool_fix_on_packages][go fix]]
+tool can automate much of the work needed to bring programs up to the Go 1 standard.
-Go 1 introduces changes to the language (such as new types for [[https://golang.org/doc/go1.html#rune][Unicode characters]] and [[https://golang.org/doc/go1.html#errors][errors]]) and the standard library (such as the new [[https://golang.org/doc/go1.html#time][time package]] and renamings in the [[https://golang.org/doc/go1.html#strconv][strconv package]]). Also, the package hierarchy has been rearranged to group related items together, such as moving the networking facilities, for instance the [[https://golang.org/pkg/net/rpc/][rpc package]], into subdirectories of net. A complete list of changes is documented in the [[https://golang.org/doc/go1.html][Go 1 release notes]]. That document is an essential reference for programmers migrating code from earlier versions of Go.
+Go 1 introduces changes to the language (such as new types for [[https://golang.org/doc/go1.html#rune][Unicode characters]]
+and [[https://golang.org/doc/go1.html#errors][errors]]) and the standard
+library (such as the new [[https://golang.org/doc/go1.html#time][time package]]
+and renamings in the [[https://golang.org/doc/go1.html#strconv][strconv package]]).
+Also, the package hierarchy has been rearranged to group related items together,
+such as moving the networking facilities,
+for instance the [[https://golang.org/pkg/net/rpc/][rpc package]],
+into subdirectories of net.
+A complete list of changes is documented in the [[https://golang.org/doc/go1.html][Go 1 release notes]].
+That document is an essential reference for programmers migrating code from
+earlier versions of Go.
-We also restructured the Go tool suite around the new [[https://golang.org/doc/go1.html#cmd_go][go command]], a program for fetching, building, installing and maintaining Go code. The go command eliminates the need for Makefiles to write Go code because it uses the Go program source itself to derive the build instructions. No more build scripts!
+We also restructured the Go tool suite around the new [[https://golang.org/doc/go1.html#cmd_go][go command]],
+a program for fetching, building, installing and maintaining Go code.
+The go command eliminates the need for Makefiles to write Go code because
+it uses the Go program source itself to derive the build instructions.
+No more build scripts!
-Finally, the release of Go 1 triggers a new release of the [[https://developers.google.com/appengine/docs/go][Google App Engine SDK]]. A similar process of revision and stabilization has been applied to the App Engine libraries, providing a base for developers to build programs for App Engine that will run for years.
+Finally, the release of Go 1 triggers a new release of the [[https://developers.google.com/appengine/docs/go][Google App Engine SDK]].
+A similar process of revision and stabilization has been applied to the
+App Engine libraries,
+providing a base for developers to build programs for App Engine that will run for years.
-Go 1 is the result of a major effort by the core Go team and our many contributors from the open source community. We thank everyone who helped make this happen.
+Go 1 is the result of a major effort by the core Go team and our many contributors
+from the open source community.
+We thank everyone who helped make this happen.
-There has never been a better time to be a Go programmer. Everything you need to get started is at [[https://golang.org/][golang.org]].
+There has never been a better time to be a Go programmer.
+Everything you need to get started is at [[https://golang.org/][golang.org]].
diff --git a/content/go-whats-new-in-march-2010.article b/content/go-whats-new-in-march-2010.article
index b14ebbc..572a58f 100644
--- a/content/go-whats-new-in-march-2010.article
+++ b/content/go-whats-new-in-march-2010.article
@@ -5,20 +5,62 @@
* Introduction
-Welcome to the official Go Blog. We, the Go team, hope to use this blog to keep the world up-to-date on the development of the Go programming language and the growing ecosystem of libraries and applications surrounding it.
+Welcome to the official Go Blog. We, the Go team,
+hope to use this blog to keep the world up-to-date on the development of
+the Go programming language and the growing ecosystem of libraries and applications surrounding it.
-It's been a few months since we launched (November last year), so let's talk about what's been happening in Go World since then.
+It's been a few months since we launched (November last year),
+so let's talk about what's been happening in Go World since then.
-The core team at Google has continued to develop the language, compilers, packages, tools, and documentation. The compilers now produce code that is in some cases between 2x and an order of magnitude faster than at release. We have put together some graphs of a selection of [[http://godashboard.appspot.com/benchmarks][Benchmarks]], and the [[http://godashboard.appspot.com/][Build Status]] page tracks the reliability of each changeset submitted to the repository.
+The core team at Google has continued to develop the language,
+compilers, packages, tools, and documentation.
+The compilers now produce code that is in some cases between 2x and an order
+of magnitude faster than at release.
+We have put together some graphs of a selection of [[http://godashboard.appspot.com/benchmarks][Benchmarks]],
+and the [[http://godashboard.appspot.com/][Build Status]] page tracks the
+reliability of each changeset submitted to the repository.
-We have made syntax changes to make the language more concise, regular, and flexible. Semicolons have been [[http://groups.google.com/group/golang-nuts/t/5ee32b588d10f2e9][almost entirely removed]] from the language. The [[https://golang.org/doc/go_spec.html#Function_types][...T syntax]] makes it simpler to handle an arbitrary number of typed function parameters. The syntax x[lo:] is now shorthand for x[lo:len(x)]. Go also now natively supports complex numbers. See the [[https://golang.org/doc/devel/release.html][release notes]] for more.
+We have made syntax changes to make the language more concise,
+regular, and flexible.
+Semicolons have been [[http://groups.google.com/group/golang-nuts/t/5ee32b588d10f2e9][almost entirely removed]] from the language.
+The [[https://golang.org/doc/go_spec.html#Function_types][...T syntax]]
+makes it simpler to handle an arbitrary number of typed function parameters.
+The syntax x[lo:] is now shorthand for x[lo:len(x)].
+Go also now natively supports complex numbers.
+See the [[https://golang.org/doc/devel/release.html][release notes]] for more.
-[[https://golang.org/cmd/godoc/][Godoc]] now provides better support for third-party libraries, and a new tool - [[https://golang.org/cmd/goinstall][goinstall]] - has been released to make it easy to install them. Additionally, we've started working on a package tracking system to make it easier to find what you need. You can view the beginnings of this on the [[http://godashboard.appspot.com/package][Packages page]].
+[[https://golang.org/cmd/godoc/][Godoc]] now provides better support for
+third-party libraries,
+and a new tool - [[https://golang.org/cmd/goinstall][goinstall]] - has been
+released to make it easy to install them.
+Additionally, we've started working on a package tracking system to make
+it easier to find what you need.
+You can view the beginnings of this on the [[http://godashboard.appspot.com/package][Packages page]].
-More than 40,000 lines of code have been added to [[https://golang.org/pkg/][the standard library]], including many entirely new packages, a sizable portion written by external contributors.
+More than 40,000 lines of code have been added to [[https://golang.org/pkg/][the standard library]],
+including many entirely new packages, a sizable portion written by external contributors.
-Speaking of third parties, since launch a vibrant community has flourished on our [[http://groups.google.com/group/golang-nuts/][mailing list]] and irc channel (#go-nuts on freenode). We have officially added [[https://golang.org/CONTRIBUTORS][more than 50 people]] to the project. Their contributions range from bug fixes and documentation corrections to core packages and support for additional operating systems (Go is now supported under FreeBSD, and a [[http://code.google.com/p/go/wiki/WindowsPort][Windows port]] is underway). We regard these community contributions our greatest success so far.
+Speaking of third parties, since launch a vibrant community has flourished
+on our [[http://groups.google.com/group/golang-nuts/][mailing list]] and
+irc channel (#go-nuts on freenode).
+We have officially added [[https://golang.org/CONTRIBUTORS][more than 50 people]] to the project.
+Their contributions range from bug fixes and documentation corrections to
+core packages and support for additional operating systems (Go is now supported under FreeBSD,
+and a [[http://code.google.com/p/go/wiki/WindowsPort][Windows port]] is underway).
+We regard these community contributions our greatest success so far.
-We've received some good reviews, too. This [[http://www.pcworld.idg.com.au/article/337773/google_go_captures_developers_imaginations/][recent article in PC World]] summarized the enthusiasm surrounding the project. Several bloggers have begun documenting their experiences in the language (see [[http://golang.tumblr.com/][here]], [[http://www.infi.nl/blog/view/id/47][here]], and [[http://freecella.blogspot.com/2010/01/gospecify-basic-setup-of-projects.html][here]] for example) The general reaction of our users has been very positive; one first-timer remarked [[https://groups.google.com/group/golang-nuts/browse_thread/thread/5fabdd59f8562ed2]["I came away extremely impressed. Go walks an elegant line between simplicity and power."]]
+We've received some good reviews, too. This [[http://www.pcworld.idg.com.au/article/337773/google_go_captures_developers_imaginations/][recent article in PC World]]
+summarized the enthusiasm surrounding the project.
+Several bloggers have begun documenting their experiences in the language
+(see [[http://golang.tumblr.com/][here]],
+[[http://www.infi.nl/blog/view/id/47][here]],
+and [[http://freecella.blogspot.com/2010/01/gospecify-basic-setup-of-projects.html][here]]
+for example) The general reaction of our users has been very positive;
+one first-timer remarked [[https://groups.google.com/group/golang-nuts/browse_thread/thread/5fabdd59f8562ed2]["I came away extremely impressed. Go walks an elegant line between simplicity and power."]]
-As to the future: we have listened to the myriad voices telling us what they need, and are now focused on getting Go ready for the prime time. We are improving the garbage collector, runtime scheduler, tools, and standard libraries, as well as exploring new language features. 2010 will be an exciting year for Go, and we look forward to collaborating with the community to make it a successful one.
+As to the future: we have listened to the myriad voices telling us what they need,
+and are now focused on getting Go ready for the prime time.
+We are improving the garbage collector, runtime scheduler,
+tools, and standard libraries, as well as exploring new language features.
+2010 will be an exciting year for Go, and we look forward to collaborating
+with the community to make it a successful one.
diff --git a/content/go-wins-2010-bossie-award.article b/content/go-wins-2010-bossie-award.article
index 1f35c2c..fa79e54 100644
--- a/content/go-wins-2010-bossie-award.article
+++ b/content/go-wins-2010-bossie-award.article
@@ -5,8 +5,22 @@
* Introduction
-The Go project has been awarded a [[http://www.infoworld.com/d/open-source/bossie-awards-2010-the-best-open-source-application-development-software-140¤t=2&last=1][Bossie Award]] for "best open source application development software." The [[http://www.infoworld.com/d/open-source/bossie-awards-2010-the-best-open-source-software-the-year-115][Bossie Awards]] have been given each year since 2007 by [[http://infoworld.com/][InfoWorld]] to recognize the best Open Source projects. Their citation reads:
+The Go project has been awarded a [[http://www.infoworld.com/d/open-source/bossie-awards-2010-the-best-open-source-application-development-software-140¤t=2&last=1][Bossie Award]]
+for "best open source application development software." The [[http://www.infoworld.com/d/open-source/bossie-awards-2010-the-best-open-source-software-the-year-115][Bossie Awards]]
+have been given each year since 2007 by [[http://infoworld.com/][InfoWorld]]
+to recognize the best Open Source projects.
+Their citation reads:
-Google's Go language tries to restore simplicity to programming. It does away with numerous constructs that have crept into all OO languages by re-imagining how to simplify and improve the conversation between a developer and the code. Go provides garbage collection, type safety, memory safety, and built-in support for concurrency and for Unicode characters. In addition, it compiles (fast!) to binaries for multiple platforms. Go is still in development (new features are being added) and it has limitations, notably poor support for Windows. But it shows a new, exciting direction in programming languages.
+Google's Go language tries to restore simplicity to programming.
+It does away with numerous constructs that have crept into all OO languages
+by re-imagining how to simplify and improve the conversation between a developer and the code.
+Go provides garbage collection, type safety,
+memory safety, and built-in support for concurrency and for Unicode characters.
+In addition, it compiles (fast!) to binaries for multiple platforms.
+Go is still in development (new features are being added) and it has limitations,
+notably poor support for Windows.
+But it shows a new, exciting direction in programming languages.
-The Go team are pleased to accept this award. It reflects not only our hard work, but also the efforts of the growing community of Go developers to whom we must extend our sincere thanks.
+The Go team are pleased to accept this award.
+It reflects not only our hard work, but also the efforts of the growing
+community of Go developers to whom we must extend our sincere thanks.
diff --git a/content/go1.11.article b/content/go1.11.article
index 75bc400..558d7cf 100644
--- a/content/go1.11.article
+++ b/content/go1.11.article
@@ -11,17 +11,25 @@
Today the Go team is happy to announce the release of Go 1.11.
You can get it from the [[https://golang.org/dl/][download page]].
-There are many changes and improvements to the toolchain, runtime, and libraries, but two features stand out as being especially exciting: modules and WebAssembly support.
+There are many changes and improvements to the toolchain,
+runtime, and libraries, but two features stand out as being especially exciting:
+modules and WebAssembly support.
-This release adds preliminary support for a [[https://golang.org/doc/go1.11#modules][new concept called “modules,”]] an alternative to GOPATH with integrated support for versioning and package distribution.
-Module support is considered experimental, and there are still a few rough edges to smooth out, so please make liberal use of the [[https://golang.org/issue/new][issue tracker]].
+This release adds preliminary support for a [[https://golang.org/doc/go1.11#modules][new concept called “modules,”]]
+an alternative to GOPATH with integrated support for versioning and package distribution.
+Module support is considered experimental,
+and there are still a few rough edges to smooth out,
+so please make liberal use of the [[https://golang.org/issue/new][issue tracker]].
Go 1.11 also adds an experimental port to [[https://golang.org/doc/go1.11#wasm][WebAssembly]] (`js/wasm`).
This allows programmers to compile Go programs to a binary format compatible with four major web browsers.
-You can read more about WebAssembly (abbreviated “Wasm”) at [[https://webassembly.org/][webassembly.org]] and see [[https://golang.org/wiki/WebAssembly][this wiki page]] on how to get started with using Wasm with Go.
+You can read more about WebAssembly (abbreviated “Wasm”) at [[https://webassembly.org/][webassembly.org]]
+and see [[https://golang.org/wiki/WebAssembly][this wiki page]] on how to
+get started with using Wasm with Go.
Special thanks to [[https://github.com/neelance][Richard Musiol]] for contributing the WebAssembly port!
-We also want to thank everyone who contributed to this release by writing code, filing bugs, providing feedback, and/or testing the betas and release candidates.
+We also want to thank everyone who contributed to this release by writing code,
+filing bugs, providing feedback, and/or testing the betas and release candidates.
Your contributions and diligence helped to ensure that Go 1.11 is as bug-free as possible.
That said, if you do notice any problems, please [[https://golang.org/issues/new][file an issue]].
diff --git a/content/gobs-of-data.article b/content/gobs-of-data.article
index fc82bbf..21a9dca 100644
--- a/content/gobs-of-data.article
+++ b/content/gobs-of-data.article
@@ -6,92 +6,245 @@
* Introduction
-To transmit a data structure across a network or to store it in a file, it must be encoded and then decoded again. There are many encodings available, of course: [[http://www.json.org/][JSON]], [[http://www.w3.org/XML/][XML]], Google's [[http://code.google.com/p/protobuf][protocol buffers]], and more. And now there's another, provided by Go's [[https://golang.org/pkg/encoding/gob/][gob]] package.
+To transmit a data structure across a network or to store it in a file,
+it must be encoded and then decoded again.
+There are many encodings available, of course:
+[[http://www.json.org/][JSON]], [[http://www.w3.org/XML/][XML]],
+Google's [[http://code.google.com/p/protobuf][protocol buffers]], and more.
+And now there's another, provided by Go's [[https://golang.org/pkg/encoding/gob/][gob]] package.
-Why define a new encoding? It's a lot of work and redundant at that. Why not just use one of the existing formats? Well, for one thing, we do! Go has [[https://golang.org/pkg/][packages]] supporting all the encodings just mentioned (the [[http://github.com/golang/protobuf][protocol buffer package]] is in a separate repository but it's one of the most frequently downloaded). And for many purposes, including communicating with tools and systems written in other languages, they're the right choice.
+Why define a new encoding? It's a lot of work and redundant at that.
+Why not just use one of the existing formats? Well,
+for one thing, we do!
+Go has [[https://golang.org/pkg/][packages]] supporting all the encodings
+just mentioned (the [[http://github.com/golang/protobuf][protocol buffer package]]
+is in a separate repository but it's one of the most frequently downloaded).
+And for many purposes, including communicating with tools and systems written in other languages,
+they're the right choice.
-But for a Go-specific environment, such as communicating between two servers written in Go, there's an opportunity to build something much easier to use and possibly more efficient.
+But for a Go-specific environment, such as communicating between two servers written in Go,
+there's an opportunity to build something much easier to use and possibly more efficient.
-Gobs work with the language in a way that an externally-defined, language-independent encoding cannot. At the same time, there are lessons to be learned from the existing systems.
+Gobs work with the language in a way that an externally-defined,
+language-independent encoding cannot.
+At the same time, there are lessons to be learned from the existing systems.
* Goals
The gob package was designed with a number of goals in mind.
-First, and most obvious, it had to be very easy to use. First, because Go has reflection, there is no need for a separate interface definition language or "protocol compiler". The data structure itself is all the package should need to figure out how to encode and decode it. On the other hand, this approach means that gobs will never work as well with other languages, but that's OK: gobs are unashamedly Go-centric.
+First, and most obvious, it had to be very easy to use.
+First, because Go has reflection, there is no need for a separate interface
+definition language or "protocol compiler".
+The data structure itself is all the package should need to figure out how
+to encode and decode it.
+On the other hand, this approach means that gobs will never work as well
+with other languages, but that's OK:
+gobs are unashamedly Go-centric.
-Efficiency is also important. Textual representations, exemplified by XML and JSON, are too slow to put at the center of an efficient communications network. A binary encoding is necessary.
+Efficiency is also important. Textual representations,
+exemplified by XML and JSON, are too slow to put at the center of an efficient
+communications network.
+A binary encoding is necessary.
-Gob streams must be self-describing. Each gob stream, read from the beginning, contains sufficient information that the entire stream can be parsed by an agent that knows nothing a priori about its contents. This property means that you will always be able to decode a gob stream stored in a file, even long after you've forgotten what data it represents.
+Gob streams must be self-describing. Each gob stream,
+read from the beginning, contains sufficient information that the entire
+stream can be parsed by an agent that knows nothing a priori about its contents.
+This property means that you will always be able to decode a gob stream stored in a file,
+even long after you've forgotten what data it represents.
There were also some things to learn from our experiences with Google protocol buffers.
* Protocol buffer misfeatures
-Protocol buffers had a major effect on the design of gobs, but have three features that were deliberately avoided. (Leaving aside the property that protocol buffers aren't self-describing: if you don't know the data definition used to encode a protocol buffer, you might not be able to parse it.)
+Protocol buffers had a major effect on the design of gobs,
+but have three features that were deliberately avoided.
+(Leaving aside the property that protocol buffers aren't self-describing:
+if you don't know the data definition used to encode a protocol buffer,
+you might not be able to parse it.)
-First, protocol buffers only work on the data type we call a struct in Go. You can't encode an integer or array at the top level, only a struct with fields inside it. That seems a pointless restriction, at least in Go. If all you want to send is an array of integers, why should you have to put it into a struct first?
+First, protocol buffers only work on the data type we call a struct in Go.
+You can't encode an integer or array at the top level,
+only a struct with fields inside it.
+That seems a pointless restriction, at least in Go.
+If all you want to send is an array of integers,
+why should you have to put it into a struct first?
-Next, a protocol buffer definition may specify that fields `T.x` and `T.y` are required to be present whenever a value of type `T` is encoded or decoded. Although such required fields may seem like a good idea, they are costly to implement because the codec must maintain a separate data structure while encoding and decoding, to be able to report when required fields are missing. They're also a maintenance problem. Over time, one may want to modify the data definition to remove a required field, but that may cause existing clients of the data to crash. It's better not to have them in the encoding at all. (Protocol buffers also have optional fields. But if we don't have required fields, all fields are optional and that's that. There will be more to say about optional fields a little later.)
+Next, a protocol buffer definition may specify that fields `T.x` and `T.y`
+are required to be present whenever a value of type `T` is encoded or decoded.
+Although such required fields may seem like a good idea,
+they are costly to implement because the codec must maintain a separate
+data structure while encoding and decoding,
+to be able to report when required fields are missing.
+They're also a maintenance problem. Over time,
+one may want to modify the data definition to remove a required field,
+but that may cause existing clients of the data to crash.
+It's better not to have them in the encoding at all.
+(Protocol buffers also have optional fields.
+But if we don't have required fields, all fields are optional and that's that.
+There will be more to say about optional fields a little later.)
-The third protocol buffer misfeature is default values. If a protocol buffer omits the value for a "defaulted" field, then the decoded structure behaves as if the field were set to that value. This idea works nicely when you have getter and setter methods to control access to the field, but is harder to handle cleanly when the container is just a plain idiomatic struct. Required fields are also tricky to implement: where does one define the default values, what types do they have (is text UTF-8? uninterpreted bytes? how many bits in a float?) and despite the apparent simplicity, there were a number of complications in their design and implementation for protocol buffers. We decided to leave them out of gobs and fall back to Go's trivial but effective defaulting rule: unless you set something otherwise, it has the "zero value" for that type - and it doesn't need to be transmitted.
+The third protocol buffer misfeature is default values.
+If a protocol buffer omits the value for a "defaulted" field,
+then the decoded structure behaves as if the field were set to that value.
+This idea works nicely when you have getter and setter methods to control
+access to the field,
+but is harder to handle cleanly when the container is just a plain idiomatic struct.
+Required fields are also tricky to implement:
+where does one define the default values,
+what types do they have (is text UTF-8? uninterpreted bytes? how many bits
+in a float?) and despite the apparent simplicity,
+there were a number of complications in their design and implementation
+for protocol buffers.
+We decided to leave them out of gobs and fall back to Go's trivial but effective defaulting rule:
+unless you set something otherwise, it has the "zero value" for that type -
+and it doesn't need to be transmitted.
So gobs end up looking like a sort of generalized, simplified protocol buffer. How do they work?
* Values
-The encoded gob data isn't about types like `int8` and `uint16`. Instead, somewhat analogous to constants in Go, its integer values are abstract, sizeless numbers, either signed or unsigned. When you encode an `int8`, its value is transmitted as an unsized, variable-length integer. When you encode an `int64`, its value is also transmitted as an unsized, variable-length integer. (Signed and unsigned are treated distinctly, but the same unsized-ness applies to unsigned values too.) If both have the value 7, the bits sent on the wire will be identical. When the receiver decodes that value, it puts it into the receiver's variable, which may be of arbitrary integer type. Thus an encoder may send a 7 that came from an `int8`, but the receiver may store it in an `int64`. This is fine: the value is an integer and as a long as it fits, everything works. (If it doesn't fit, an error results.) This decoupling from the size of the variable gives some flexibility to the encoding: we can expand the type of the integer variable as the software evolves, but still be able to decode old data.
+The encoded gob data isn't about types like `int8` and `uint16`.
+Instead, somewhat analogous to constants in Go,
+its integer values are abstract, sizeless numbers,
+either signed or unsigned.
+When you encode an `int8`, its value is transmitted as an unsized,
+variable-length integer.
+When you encode an `int64`, its value is also transmitted as an unsized,
+variable-length integer.
+(Signed and unsigned are treated distinctly,
+but the same unsized-ness applies to unsigned values too.) If both have the value 7,
+the bits sent on the wire will be identical.
+When the receiver decodes that value, it puts it into the receiver's variable,
+which may be of arbitrary integer type.
+Thus an encoder may send a 7 that came from an `int8`,
+but the receiver may store it in an `int64`.
+This is fine: the value is an integer and as a long as it fits, everything works.
+(If it doesn't fit, an error results.) This decoupling from the size of
+the variable gives some flexibility to the encoding:
+we can expand the type of the integer variable as the software evolves,
+but still be able to decode old data.
-This flexibility also applies to pointers. Before transmission, all pointers are flattened. Values of type `int8`, `*int8`, `**int8`, `****int8`, etc. are all transmitted as an integer value, which may then be stored in `int` of any size, or `*int`, or `******int`, etc. Again, this allows for flexibility.
+This flexibility also applies to pointers.
+Before transmission, all pointers are flattened.
+Values of type `int8`, `*int8`, `**int8`,
+`****int8`, etc. are all transmitted as an integer value,
+which may then be stored in `int` of any size,
+or `*int`, or `******int`, etc.
+Again, this allows for flexibility.
-Flexibility also happens because, when decoding a struct, only those fields that are sent by the encoder are stored in the destination. Given the value
+Flexibility also happens because, when decoding a struct,
+only those fields that are sent by the encoder are stored in the destination. Given the value
type T struct{ X, Y, Z int } // Only exported fields are encoded and decoded.
var t = T{X: 7, Y: 0, Z: 8}
-the encoding of `t` sends only the 7 and 8. Because it's zero, the value of `Y` isn't even sent; there's no need to send a zero value.
+the encoding of `t` sends only the 7 and 8.
+Because it's zero, the value of `Y` isn't even sent;
+there's no need to send a zero value.
The receiver could instead decode the value into this structure:
type U struct{ X, Y *int8 } // Note: pointers to int8s
var u U
-and acquire a value of `u` with only `X` set (to the address of an `int8` variable set to 7); the `Z` field is ignored - where would you put it? When decoding structs, fields are matched by name and compatible type, and only fields that exist in both are affected. This simple approach finesses the "optional field" problem: as the type `T` evolves by adding fields, out of date receivers will still function with the part of the type they recognize. Thus gobs provide the important result of optional fields - extensibility - without any additional mechanism or notation.
+and acquire a value of `u` with only `X` set (to the address of an `int8` variable set to 7);
+the `Z` field is ignored - where would you put it? When decoding structs,
+fields are matched by name and compatible type,
+and only fields that exist in both are affected.
+This simple approach finesses the "optional field" problem:
+as the type `T` evolves by adding fields,
+out of date receivers will still function with the part of the type they recognize.
+Thus gobs provide the important result of optional fields - extensibility -
+without any additional mechanism or notation.
-From integers we can build all the other types: bytes, strings, arrays, slices, maps, even floats. Floating-point values are represented by their IEEE 754 floating-point bit pattern, stored as an integer, which works fine as long as you know their type, which we always do. By the way, that integer is sent in byte-reversed order because common values of floating-point numbers, such as small integers, have a lot of zeros at the low end that we can avoid transmitting.
+From integers we can build all the other types:
+bytes, strings, arrays, slices, maps, even floats.
+Floating-point values are represented by their IEEE 754 floating-point bit pattern,
+stored as an integer, which works fine as long as you know their type, which we always do.
+By the way, that integer is sent in byte-reversed order because common values
+of floating-point numbers,
+such as small integers, have a lot of zeros at the low end that we can avoid transmitting.
-One nice feature of gobs that Go makes possible is that they allow you to define your own encoding by having your type satisfy the [[https://golang.org/pkg/encoding/gob/#GobEncoder][GobEncoder]] and [[https://golang.org/pkg/encoding/gob/#GobDecoder][GobDecoder]] interfaces, in a manner analogous to the [[https://golang.org/pkg/encoding/json/][JSON]] package's [[https://golang.org/pkg/encoding/json/#Marshaler][Marshaler]] and [[https://golang.org/pkg/encoding/json/#Unmarshaler][Unmarshaler]] and also to the [[https://golang.org/pkg/fmt/#Stringer][Stringer]] interface from [[https://golang.org/pkg/fmt/][package fmt]]. This facility makes it possible to represent special features, enforce constraints, or hide secrets when you transmit data. See the [[https://golang.org/pkg/encoding/gob/][documentation]] for details.
+One nice feature of gobs that Go makes possible is that they allow you to
+define your own encoding by having your type satisfy the [[https://golang.org/pkg/encoding/gob/#GobEncoder][GobEncoder]]
+and [[https://golang.org/pkg/encoding/gob/#GobDecoder][GobDecoder]] interfaces,
+in a manner analogous to the [[https://golang.org/pkg/encoding/json/][JSON]]
+package's [[https://golang.org/pkg/encoding/json/#Marshaler][Marshaler]]
+and [[https://golang.org/pkg/encoding/json/#Unmarshaler][Unmarshaler]] and
+also to the [[https://golang.org/pkg/fmt/#Stringer][Stringer]] interface
+from [[https://golang.org/pkg/fmt/][package fmt]].
+This facility makes it possible to represent special features,
+enforce constraints, or hide secrets when you transmit data.
+See the [[https://golang.org/pkg/encoding/gob/][documentation]] for details.
* Types on the wire
-The first time you send a given type, the gob package includes in the data stream a description of that type. In fact, what happens is that the encoder is used to encode, in the standard gob encoding format, an internal struct that describes the type and gives it a unique number. (Basic types, plus the layout of the type description structure, are predefined by the software for bootstrapping.) After the type is described, it can be referenced by its type number.
+The first time you send a given type, the gob package includes in the data
+stream a description of that type.
+In fact, what happens is that the encoder is used to encode,
+in the standard gob encoding format, an internal struct that describes the
+type and gives it a unique number.
+(Basic types, plus the layout of the type description structure,
+are predefined by the software for bootstrapping.) After the type is described,
+it can be referenced by its type number.
-Thus when we send our first type `T`, the gob encoder sends a description of `T` and tags it with a type number, say 127. All values, including the first, are then prefixed by that number, so a stream of `T` values looks like:
+Thus when we send our first type `T`, the gob encoder sends a description
+of `T` and tags it with a type number, say 127.
+All values, including the first, are then prefixed by that number,
+so a stream of `T` values looks like:
("define type id" 127, definition of type T)(127, T value)(127, T value), ...
-These type numbers make it possible to describe recursive types and send values of those types. Thus gobs can encode types such as trees:
+These type numbers make it possible to describe recursive types and send
+values of those types.
+Thus gobs can encode types such as trees:
type Node struct {
Value int
Left, Right *Node
}
-(It's an exercise for the reader to discover how the zero-defaulting rule makes this work, even though gobs don't represent pointers.)
+(It's an exercise for the reader to discover how the zero-defaulting rule makes this work,
+even though gobs don't represent pointers.)
-With the type information, a gob stream is fully self-describing except for the set of bootstrap types, which is a well-defined starting point.
+With the type information, a gob stream is fully self-describing except
+for the set of bootstrap types,
+which is a well-defined starting point.
* Compiling a machine
-The first time you encode a value of a given type, the gob package builds a little interpreted machine specific to that data type. It uses reflection on the type to construct that machine, but once the machine is built it does not depend on reflection. The machine uses package unsafe and some trickery to convert the data into the encoded bytes at high speed. It could use reflection and avoid unsafe, but would be significantly slower. (A similar high-speed approach is taken by the protocol buffer support for Go, whose design was influenced by the implementation of gobs.) Subsequent values of the same type use the already-compiled machine, so they can be encoded right away.
+The first time you encode a value of a given type,
+the gob package builds a little interpreted machine specific to that data type.
+It uses reflection on the type to construct that machine,
+but once the machine is built it does not depend on reflection.
+The machine uses package unsafe and some trickery to convert the data into
+the encoded bytes at high speed.
+It could use reflection and avoid unsafe,
+but would be significantly slower.
+(A similar high-speed approach is taken by the protocol buffer support for Go,
+whose design was influenced by the implementation of gobs.) Subsequent values
+of the same type use the already-compiled machine,
+so they can be encoded right away.
[Update: As of Go 1.4, package unsafe is no longer use by the gob package, with a modest performance drop.]
-Decoding is similar but harder. When you decode a value, the gob package holds a byte slice representing a value of a given encoder-defined type to decode, plus a Go value into which to decode it. The gob package builds a machine for that pair: the gob type sent on the wire crossed with the Go type provided for decoding. Once that decoding machine is built, though, it's again a reflectionless engine that uses unsafe methods to get maximum speed.
+Decoding is similar but harder. When you decode a value,
+the gob package holds a byte slice representing a value of a given encoder-defined type to decode,
+plus a Go value into which to decode it.
+The gob package builds a machine for that pair:
+the gob type sent on the wire crossed with the Go type provided for decoding.
+Once that decoding machine is built, though,
+it's again a reflectionless engine that uses unsafe methods to get maximum speed.
* Use
-There's a lot going on under the hood, but the result is an efficient, easy-to-use encoding system for transmitting data. Here's a complete example showing differing encoded and decoded types. Note how easy it is to send and receive values; all you need to do is present values and variables to the [[https://golang.org/pkg/encoding/gob/][gob package]] and it does all the work.
+There's a lot going on under the hood, but the result is an efficient,
+easy-to-use encoding system for transmitting data.
+Here's a complete example showing differing encoded and decoded types.
+Note how easy it is to send and receive values;
+all you need to do is present values and variables to the [[https://golang.org/pkg/encoding/gob/][gob package]]
+and it does all the work.
package main
@@ -135,8 +288,15 @@
You can compile and run this example code in the [[http://play.golang.org/p/_-OJV-rwMq][Go Playground]].
-The [[https://golang.org/pkg/net/rpc/][rpc package]] builds on gobs to turn this encode/decode automation into transport for method calls across the network. That's a subject for another article.
+The [[https://golang.org/pkg/net/rpc/][rpc package]] builds on gobs to turn
+this encode/decode automation into transport for method calls across the network.
+That's a subject for another article.
* Details
-The [[https://golang.org/pkg/encoding/gob/][gob package documentation]], especially the file [[https://golang.org/src/pkg/encoding/gob/doc.go][doc.go]], expands on many of the details described here and includes a full worked example showing how the encoding represents data. If you are interested in the innards of the gob implementation, that's a good place to start.
+The [[https://golang.org/pkg/encoding/gob/][gob package documentation]],
+especially the file [[https://golang.org/src/pkg/encoding/gob/doc.go][doc.go]],
+expands on many of the details described here and includes a full worked
+example showing how the encoding represents data.
+If you are interested in the innards of the gob implementation,
+that's a good place to start.
diff --git a/content/godoc-documenting-go-code.article b/content/godoc-documenting-go-code.article
index e9ad9ff..89df534 100644
--- a/content/godoc-documenting-go-code.article
+++ b/content/godoc-documenting-go-code.article
@@ -6,34 +6,77 @@
* Introduction
-The Go project takes documentation seriously. Documentation is a huge part of making software accessible and maintainable. Of course it must be well-written and accurate, but it also must be easy to write and to maintain. Ideally, it should be coupled to the code itself so the documentation evolves along with the code. The easier it is for programmers to produce good documentation, the better for everyone.
+The Go project takes documentation seriously.
+Documentation is a huge part of making software accessible and maintainable.
+Of course it must be well-written and accurate,
+but it also must be easy to write and to maintain.
+Ideally, it should be coupled to the code itself so the documentation evolves
+along with the code.
+The easier it is for programmers to produce good documentation,
+the better for everyone.
-To that end, we have developed the [[https://golang.org/cmd/godoc/][godoc]] documentation tool. This article describes godoc's approach to documentation, and explains how you can use our conventions and tools to write good documentation for your own projects.
+To that end, we have developed the [[https://golang.org/cmd/godoc/][godoc]] documentation tool.
+This article describes godoc's approach to documentation,
+and explains how you can use our conventions and tools to write good documentation
+for your own projects.
-Godoc parses Go source code - including comments - and produces documentation as HTML or plain text. The end result is documentation tightly coupled with the code it documents. For example, through godoc's web interface you can navigate from a function's [[https://golang.org/pkg/strings/#HasPrefix][documentation]] to its [[https://golang.org/src/pkg/strings/strings.go#L493][implementation]] with one click.
+Godoc parses Go source code - including comments - and produces documentation
+as HTML or plain text.
+The end result is documentation tightly coupled with the code it documents.
+For example, through godoc's web interface you can navigate from a function's
+[[https://golang.org/pkg/strings/#HasPrefix][documentation]] to its [[https://golang.org/src/pkg/strings/strings.go#L493][implementation]] with one click.
-Godoc is conceptually related to Python's [[http://www.python.org/dev/peps/pep-0257/][Docstring]] and Java's [[http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html][Javadoc]], but its design is simpler. The comments read by godoc are not language constructs (as with Docstring) nor must they have their own machine-readable syntax (as with Javadoc). Godoc comments are just good comments, the sort you would want to read even if godoc didn't exist.
+Godoc is conceptually related to Python's [[http://www.python.org/dev/peps/pep-0257/][Docstring]]
+and Java's [[http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html][Javadoc]],
+but its design is simpler.
+The comments read by godoc are not language constructs (as with Docstring)
+nor must they have their own machine-readable syntax (as with Javadoc).
+Godoc comments are just good comments, the sort you would want to read even
+if godoc didn't exist.
-The convention is simple: to document a type, variable, constant, function, or even a package, write a regular comment directly preceding its declaration, with no intervening blank line. Godoc will then present that comment as text alongside the item it documents. For example, this is the documentation for the `fmt` package's [[https://golang.org/pkg/fmt/#Fprint][`Fprint`]] function:
+The convention is simple: to document a type,
+variable, constant, function, or even a package,
+write a regular comment directly preceding its declaration,
+with no intervening blank line.
+Godoc will then present that comment as text alongside the item it documents.
+For example, this is the documentation for the `fmt` package's [[https://golang.org/pkg/fmt/#Fprint][`Fprint`]] function:
// Fprint formats using the default formats for its operands and writes to w.
// Spaces are added between operands when neither is a string.
// It returns the number of bytes written and any write error encountered.
func Fprint(w io.Writer, a ...interface{}) (n int, err error) {
-Notice this comment is a complete sentence that begins with the name of the element it describes. This important convention allows us to generate documentation in a variety of formats, from plain text to HTML to UNIX man pages, and makes it read better when tools truncate it for brevity, such as when they extract the first line or sentence.
+Notice this comment is a complete sentence that begins with the name of
+the element it describes.
+This important convention allows us to generate documentation in a variety of formats,
+from plain text to HTML to UNIX man pages,
+and makes it read better when tools truncate it for brevity,
+such as when they extract the first line or sentence.
-Comments on package declarations should provide general package documentation. These comments can be short, like the [[https://golang.org/pkg/sort/][`sort`]] package's brief description:
+Comments on package declarations should provide general package documentation.
+These comments can be short, like the [[https://golang.org/pkg/sort/][`sort`]]
+package's brief description:
// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort
-They can also be detailed like the [[https://golang.org/pkg/encoding/gob/][gob package]]'s overview. That package uses another convention for packages that need large amounts of introductory documentation: the package comment is placed in its own file, [[https://golang.org/src/pkg/encoding/gob/doc.go][doc.go]], which contains only those comments and a package clause.
+They can also be detailed like the [[https://golang.org/pkg/encoding/gob/][gob package]]'s overview.
+That package uses another convention for packages that need large amounts
+of introductory documentation:
+the package comment is placed in its own file,
+[[https://golang.org/src/pkg/encoding/gob/doc.go][doc.go]],
+which contains only those comments and a package clause.
-When writing package comments of any size, keep in mind that their first sentence will appear in godoc's [[https://golang.org/pkg/][package list]].
+When writing package comments of any size,
+keep in mind that their first sentence will appear in godoc's [[https://golang.org/pkg/][package list]].
-Comments that are not adjacent to a top-level declaration are omitted from godoc's output, with one notable exception. Top-level comments that begin with the word `"BUG(who)”` are recognized as known bugs, and included in the "Bugs” section of the package documentation. The "who” part should be the user name of someone who could provide more information. For example, this is a known issue from the [[https://golang.org/pkg/bytes/#pkg-note-BUG][bytes package]]:
+Comments that are not adjacent to a top-level declaration are omitted from godoc's output,
+with one notable exception.
+Top-level comments that begin with the word `"BUG(who)”` are recognized as known bugs,
+and included in the "Bugs” section of the package documentation.
+The "who” part should be the user name of someone who could provide more information.
+For example, this is a known issue from the [[https://golang.org/pkg/bytes/#pkg-note-BUG][bytes package]]:
// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
@@ -47,14 +90,23 @@
There are a few formatting rules that Godoc uses when converting comments to HTML:
-- Subsequent lines of text are considered part of the same paragraph; you must leave a blank line to separate paragraphs.
+- Subsequent lines of text are considered part of the same paragraph;
+ you must leave a blank line to separate paragraphs.
-- Pre-formatted text must be indented relative to the surrounding comment text (see gob's [[https://golang.org/src/pkg/encoding/gob/doc.go][doc.go]] for an example).
+- Pre-formatted text must be indented relative to the surrounding comment
+ text (see gob's [[https://golang.org/src/pkg/encoding/gob/doc.go][doc.go]] for an example).
- URLs will be converted to HTML links; no special markup is necessary.
Note that none of these rules requires you to do anything out of the ordinary.
-In fact, the best thing about godoc's minimal approach is how easy it is to use. As a result, a lot of Go code, including all of the standard library, already follows the conventions.
+In fact, the best thing about godoc's minimal approach is how easy it is to use.
+As a result, a lot of Go code, including all of the standard library,
+already follows the conventions.
-Your own code can present good documentation just by having comments as described above. Any Go packages installed inside `$GOROOT/src/pkg` and any `GOPATH` work spaces will already be accessible via godoc's command-line and HTTP interfaces, and you can specify additional paths for indexing via the `-path` flag or just by running `"godoc`."` in the source directory. See the [[https://golang.org/cmd/godoc/][godoc documentation]] for more details.
+Your own code can present good documentation just by having comments as described above.
+Any Go packages installed inside `$GOROOT/src/pkg` and any `GOPATH` work
+spaces will already be accessible via godoc's command-line and HTTP interfaces,
+and you can specify additional paths for indexing via the `-path` flag or
+just by running `"godoc`."` in the source directory.
+See the [[https://golang.org/cmd/godoc/][godoc documentation]] for more details.
diff --git a/content/gopher.article b/content/gopher.article
index 5bb4339..3084655 100644
--- a/content/gopher.article
+++ b/content/gopher.article
@@ -10,21 +10,32 @@
.image gopher/header.jpg
-The Go gopher is an iconic mascot and one of the most distinctive features of the Go project. In this post we'll talk about its origins, evolution, and behavior.
+The Go gopher is an iconic mascot and one of the most distinctive features of the Go project.
+In this post we'll talk about its origins,
+evolution, and behavior.
-About 15 years ago—long before the Go project—the gopher first appeared as a promotion for the [[https://wfmu.org/][WFMU radio station]] in New Jersey. [[http://reneefrench.blogspot.com][Renee French]] was commissioned to design a T-shirt for an annual fundraiser and out came the gopher.
+About 15 years ago—long before the Go project—the gopher first appeared as
+a promotion for the [[https://wfmu.org/][WFMU radio station]] in New Jersey.
+[[http://reneefrench.blogspot.com][Renee French]] was commissioned to
+design a T-shirt for an annual fundraiser and out came the gopher.
.image gopher/wfmu.jpg
-The gopher next made an appearance at Bell Labs, as Bob Flandrena's [[https://research.swtch.com/face][avatar]] in the Bell Labs mail system. Other Renee drawings became avatars for ken, r, rsc, and others. (Of course, Peter Weinberger's was his own [[http://spinroot.com/pico/pjw.html][iconic face]].)
+The gopher next made an appearance at Bell Labs,
+as Bob Flandrena's [[https://research.swtch.com/face][avatar]] in the Bell Labs mail system.
+Other Renee drawings became avatars for ken, r, rsc, and others.
+(Of course, Peter Weinberger's was his own [[http://spinroot.com/pico/pjw.html][iconic face]].)
.image gopher/avatars.png
-Another Bell Labs activity led to Renee creating [[https://9p.io/plan9/glenda.html][Glenda]], the Plan 9 mascot, a distant cousin of the WFMU gopher.
+Another Bell Labs activity led to Renee creating [[https://9p.io/plan9/glenda.html][Glenda]],
+the Plan 9 mascot, a distant cousin of the WFMU gopher.
.image gopher/glenda.png
-When we started the Go project we needed a logo, and Renee volunteered to draw it. It was featured on the first Go T-shirt and the Google Code site.
+When we started the Go project we needed a logo,
+and Renee volunteered to draw it.
+It was featured on the first Go T-shirt and the Google Code site.
.image gopher/logo.png
@@ -34,7 +45,11 @@
(The gopher has no name, and is called just the "Go gopher".)
-For the [[https://www.youtube.com/watch?v=-i0hat7pdpk#t=24m40s][launch]] of the [[https://developers.google.com/appengine/docs/go][Go App Engine runtime]] at Google I/O 2011 we engaged [[http://squishable.com][Squishable]] to manufacture the plush gophers. This was the first time the gopher was colored blue and appeared in three dimensions. The first prototype was kinda hairy:
+For the [[https://www.youtube.com/watch?v=-i0hat7pdpk#t=24m40s][launch]]
+of the [[https://developers.google.com/appengine/docs/go][Go App Engine runtime]] at
+Google I/O 2011 we engaged [[http://squishable.com][Squishable]] to manufacture the plush gophers.
+This was the first time the gopher was colored blue and appeared in three dimensions.
+The first prototype was kinda hairy:
.image gopher/prototype.jpg
@@ -42,25 +57,43 @@
.image gopher/plush.jpg
-Around the same time, Renee roughed out a gopher in clay. This inspired a refined sculpture that became a vinyl figurine made by [[http://www.kidrobot.com/][Kidrobot]]. The vinyls were first distributed at OSCON 2011.
+Around the same time, Renee roughed out a gopher in clay.
+This inspired a refined sculpture that became a vinyl figurine made by [[http://www.kidrobot.com/][Kidrobot]].
+The vinyls were first distributed at OSCON 2011.
.image gopher/vinyl.jpg
-The gopher therefore exists in many forms, but has always been Renee's creation. It stands for the Go project and Go programmers everywhere, and is one of the most popular things in the Go world.
+The gopher therefore exists in many forms,
+but has always been Renee's creation.
+It stands for the Go project and Go programmers everywhere,
+and is one of the most popular things in the Go world.
The Go gopher is a character; a unique creation. Not any old gopher, just as Snoopy is not any old cartoon dog.
-The [[https://golang.org/doc/gopher/][gopher images]] are Creative Commons Attribution 3.0 licensed. That means you can play with the images but you must give credit to their creator (Renee French) wherever they are used.
+The [[https://golang.org/doc/gopher/][gopher images]] are Creative Commons
+Attribution 3.0 licensed.
+That means you can play with the images but you must give credit to their
+creator (Renee French) wherever they are used.
Here are a few gopher adaptations that people have used as mascots for user group mascots and similar organizations.
.image gopher/usergroups.png
-They're cute and we like them, but by the Creative Commons rules the groups should give Renee credit, perhaps as a mention on the user group web site.
+They're cute and we like them, but by the Creative Commons rules the groups
+should give Renee credit,
+perhaps as a mention on the user group web site.
-The vinyl and plush gophers are copyrighted designs; accept no substitutes! But how can you get one? Their natural habitat is near high concentrations of Go programmers, and their worldwide population is growing. They may be purchased from the [[https://www.googlemerchandisestore.com/Google+Redesign/Fun/Go+Gopher+Blue+Squishable.axd?cid=1399][Google Store]], although the supply can be irregular. (These elusive creatures have been spotted in all [[http://www.flickr.com/photos/pinkhamsters/sets/72157627910426064/][kinds]] [[https://plus.google.com/107966629974328136037/posts/TcFA9zHzQB8][of]] [[https://twitter.com/goroutine][places]].)
+The vinyl and plush gophers are copyrighted designs;
+accept no substitutes!
+But how can you get one? Their natural habitat is near high concentrations of Go programmers,
+and their worldwide population is growing.
+They may be purchased from the [[https://www.googlemerchandisestore.com/Google+Redesign/Fun/Go+Gopher+Blue+Squishable.axd?cid=1399][Google Store]],
+although the supply can be irregular.
+(These elusive creatures have been spotted in all [[http://www.flickr.com/photos/pinkhamsters/sets/72157627910426064/][kinds]] [[https://plus.google.com/107966629974328136037/posts/TcFA9zHzQB8][of]] [[https://twitter.com/goroutine][places]].)
-Perhaps the best way to get a gopher is to catch one in the wild at a Go conference. There are two big chances this year: [[http://gophercon.com/][GopherCon]] (Denver, April 24-26) and [[http://dotgo.eu][dotGo]] (Paris, October 10).
+Perhaps the best way to get a gopher is to catch one in the wild at a Go conference.
+There are two big chances this year: [[http://gophercon.com/][GopherCon]] (Denver,
+April 24-26) and [[http://dotgo.eu][dotGo]] (Paris, October 10).
.image gopher/portrait.jpg
diff --git a/content/gophercon.article b/content/gophercon.article
index 4777b78..e7d8931 100644
--- a/content/gophercon.article
+++ b/content/gophercon.article
@@ -19,13 +19,17 @@
Two keynotes framed the conference:
-- Rob Pike's opening talk [[https://www.youtube.com/watch?v=VoS7DsT1rdM]["Hello, Gophers!"]] ([[https://talks.golang.org/2014/hellogophers.slide][slides]]) discusses the history of Go by walking through two of the first Go programs.
-- Andrew Gerrand's closing talk [[https://www.youtube.com/watch?v=dKGmK_Z1Zl0]["Go for gophers"]] ([[https://talks.golang.org/2014/go4gophers.slide][slides]]) explains the Go design philosophy through the lens of his personal experience learning the language.
+- Rob Pike's opening talk [[https://www.youtube.com/watch?v=VoS7DsT1rdM]["Hello, Gophers!"]] ([[https://talks.golang.org/2014/hellogophers.slide][slides]])
+ discusses the history of Go by walking through two of the first Go programs.
+- Andrew Gerrand's closing talk [[https://www.youtube.com/watch?v=dKGmK_Z1Zl0]["Go for gophers"]] ([[https://talks.golang.org/2014/go4gophers.slide][slides]]) explains
+ the Go design philosophy through the lens of his personal experience learning the language.
One talk that resonated with members of the Go team was Peter Bourgon's
[[https://www.youtube.com/watch?v=Y1-RLAl7iOI]["Best practices for Production Environments"]]
([[http://peter.bourgon.org/go-in-production/][notes]]).
-From deployment to dependency management, it answers many frequently asked questions about Go use in the real world and is a must-see for anyone serious about building systems in Go.
+From deployment to dependency management,
+it answers many frequently asked questions about Go use in the real world
+and is a must-see for anyone serious about building systems in Go.
But, really, you should just [[http://confreaks.com/events/gophercon2014][watch them all]].
They're great.
@@ -45,7 +49,10 @@
It was a thrill to see the many different ways people are using the language.
It was also great to put faces to many of the names we know well through their contributions to the project.
-We would like to extend our thanks and congratulations to the GopherCon organizers (Brian Ketelsen and Erik St. Martin), the excellent speakers, and the tireless volunteers that pitched in to make the event such a success.
+We would like to extend our thanks and congratulations to the GopherCon
+organizers (Brian Ketelsen and Erik St.
+Martin), the excellent speakers, and the tireless volunteers that pitched
+in to make the event such a success.
We look forward to GopherCon 2015, which promises to be bigger and better still.
But if you really can't wait, we'll see you at [[http://www.dotgo.eu/][dotGo]] in Paris on the 10th of October!
diff --git a/content/gophercon2015.article b/content/gophercon2015.article
index c25bd3b..9dae87b 100644
--- a/content/gophercon2015.article
+++ b/content/gophercon2015.article
@@ -20,34 +20,56 @@
[[http://gophercon.com/schedule/8july/][Day 1]]:
-- Go, Open Source, Community — Russ Cox ([[https://www.youtube.com/watch?v=XvZOdpd_9tc][video]]) ([[https://blog.golang.org/open-source][text]])
-- Go kit: A Standard Library for Distributed Programming — Peter Bourgon ([[https://www.youtube.com/watch?v=1AjaZi4QuGo][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Go%20kit/go-kit.pdf][slides]])
-- Delve Into Go — Derek Parker ([[https://www.youtube.com/watch?v=InG72scKPd4][video]]) ([[http://go-talks.appspot.com/github.com/derekparker/talks/gophercon-2015/delve-into-go.slide][slides]])
-- How a complete beginner learned Go as her first backend language in 5 weeks — Audrey Lim ([[https://www.youtube.com/watch?v=fZh8uCInEfw][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Audrey%20Lim%20-%20How%20a%20Complete%20Beginner%20Picked%20Up%20Go%20as%20Her%20First%20Backend%20Language%20in%205%20weeks/audreylim_slides.pdf][slides]])
-- A Practical Guide to Preventing Deadlocks and Leaks in Go — Richard Fliam ([[https://www.youtube.com/watch?v=3EW1hZ8DVyw][video]])
-- Go GC: Solving the Latency Problem — Rick Hudson ([[https://www.youtube.com/watch?v=aiv1JOfMjm0][video]]) ([[https://talks.golang.org/2015/go-gc.pdf][slides]])
-- Simplicity and Go — Katherine Cox-Buday ([[https://www.youtube.com/watch?v=S6mEo_FHZ5Y][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Katherine%20Cox-Buday:%20Simplicity%20%26%20Go/Simplicity%20%26%20Go.pdf][slides]])
-- Rebuilding Parse.com in Go - an opinionated rewrite — Abhishek Kona ([[https://www.youtube.com/watch?v=_f9LS-OWfeA][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Abhishek%20Kona%20Rewriting%20Parse%20in%20GO/myslides.pdf][slides]])
-- Prometheus: Designing and Implementing a Modern Monitoring Solution in Go — Björn Rabenstein ([[https://www.youtube.com/watch?v=1V7eJ0jN8-E][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Bj%C3%B6rn%20Rabenstein%20-%20Prometheus/slides.pdf][slides]])
+- Go, Open Source, Community — Russ Cox ([[https://www.youtube.com/watch?v=XvZOdpd_9tc][video]])
+ ([[https://blog.golang.org/open-source][text]])
+- Go kit: A Standard Library for Distributed Programming — Peter Bourgon
+ ([[https://www.youtube.com/watch?v=1AjaZi4QuGo][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Go%20kit/go-kit.pdf][slides]])
+- Delve Into Go — Derek Parker ([[https://www.youtube.com/watch?v=InG72scKPd4][video]])
+ ([[http://go-talks.appspot.com/github.com/derekparker/talks/gophercon-2015/delve-into-go.slide][slides]])
+- How a complete beginner learned Go as her first backend language in 5
+ weeks — Audrey Lim ([[https://www.youtube.com/watch?v=fZh8uCInEfw][video]])
+ ([[https://github.com/gophercon/2015-talks/blob/master/Audrey%20Lim%20-%20How%20a%20Complete%20Beginner%20Picked%20Up%20Go%20as%20Her%20First%20Backend%20Language%20in%205%20weeks/audreylim_slides.pdf][slides]])
+- A Practical Guide to Preventing Deadlocks and Leaks in Go — Richard
+ Fliam ([[https://www.youtube.com/watch?v=3EW1hZ8DVyw][video]])
+- Go GC: Solving the Latency Problem — Rick Hudson ([[https://www.youtube.com/watch?v=aiv1JOfMjm0][video]])
+ ([[https://talks.golang.org/2015/go-gc.pdf][slides]])
+- Simplicity and Go — Katherine Cox-Buday ([[https://www.youtube.com/watch?v=S6mEo_FHZ5Y][video]])
+ ([[https://github.com/gophercon/2015-talks/blob/master/Katherine%20Cox-Buday:%20Simplicity%20%26%20Go/Simplicity%20%26%20Go.pdf][slides]])
+- Rebuilding Parse.com in Go - an opinionated rewrite — Abhishek Kona
+ ([[https://www.youtube.com/watch?v=_f9LS-OWfeA][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Abhishek%20Kona%20Rewriting%20Parse%20in%20GO/myslides.pdf][slides]])
+- Prometheus: Designing and Implementing a Modern Monitoring Solution in
+ Go — Björn Rabenstein ([[https://www.youtube.com/watch?v=1V7eJ0jN8-E][video]])
+ ([[https://github.com/gophercon/2015-talks/blob/master/Bj%C3%B6rn%20Rabenstein%20-%20Prometheus/slides.pdf][slides]])
- What Could Go Wrong? — Kevin Cantwell ([[https://www.youtube.com/watch?v=VC3QXZ-x5yI][video]])
-- The Roots of Go — Baishampayan Ghose ([[https://www.youtube.com/watch?v=0hPOopcJ8-E][video]]) ([[https://speakerdeck.com/bg/the-roots-of-go][slides]])
+- The Roots of Go — Baishampayan Ghose ([[https://www.youtube.com/watch?v=0hPOopcJ8-E][video]])
+ ([[https://speakerdeck.com/bg/the-roots-of-go][slides]])
[[http://gophercon.com/schedule/9july/][Day 2]]:
-- The Evolution of Go — Robert Griesemer ([[https://www.youtube.com/watch?v=0ReKdcpNyQg][video]]) ([[https://talks.golang.org/2015/gophercon-goevolution.slide][slides]])
-- Static Code Analysis Using SSA — Ben Johnson ([[https://www.youtube.com/watch?v=D2-gaMvWfQY][video]]) ([[https://speakerdeck.com/benbjohnson/static-code-analysis-using-ssa][slides]])
-- Go on Mobile — Hana Kim ([[https://www.youtube.com/watch?v=sQ6-HyPxHKg][video]]) ([[https://talks.golang.org/2015/gophercon-go-on-mobile.slide][slides]])
-- Go Dynamic Tools — Dmitry Vyukov ([[https://www.youtube.com/watch?v=a9xrxRsIbSU][video]]) ([[https://talks.golang.org/2015/dynamic-tools.slide][slides]])
-- Embrace the Interface — Tomás Senart ([[https://www.youtube.com/watch?v=xyDkyFjzFVc][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Tom%C3%A1s%20Senart%20-%20Embrace%20the%20Interface/ETI.pdf][slides]])
-- Uptime: Building Resilient Services with Go — Blake Caldwell ([[https://www.youtube.com/watch?v=PyBJQA4clfc][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Blake%20Caldwell%20-%20Uptime:%20Building%20Resilient%20Services%20with%20Go/2015-GopherCon-Talk-Uptime.pdf][slides]])
-- Cayley: Building a Graph Database — Barak Michener ([[https://www.youtube.com/watch?v=-9kWbPmSyCI][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Barak%20Michener%20-%20Cayley:%20Building%20a%20Graph%20Database/Cayley%20-%20Building%20a%20Graph%20Database.pdf][slides]])
+- The Evolution of Go — Robert Griesemer ([[https://www.youtube.com/watch?v=0ReKdcpNyQg][video]])
+ ([[https://talks.golang.org/2015/gophercon-goevolution.slide][slides]])
+- Static Code Analysis Using SSA — Ben Johnson ([[https://www.youtube.com/watch?v=D2-gaMvWfQY][video]])
+ ([[https://speakerdeck.com/benbjohnson/static-code-analysis-using-ssa][slides]])
+- Go on Mobile — Hana Kim ([[https://www.youtube.com/watch?v=sQ6-HyPxHKg][video]])
+ ([[https://talks.golang.org/2015/gophercon-go-on-mobile.slide][slides]])
+- Go Dynamic Tools — Dmitry Vyukov ([[https://www.youtube.com/watch?v=a9xrxRsIbSU][video]])
+ ([[https://talks.golang.org/2015/dynamic-tools.slide][slides]])
+- Embrace the Interface — Tomás Senart ([[https://www.youtube.com/watch?v=xyDkyFjzFVc][video]])
+ ([[https://github.com/gophercon/2015-talks/blob/master/Tom%C3%A1s%20Senart%20-%20Embrace%20the%20Interface/ETI.pdf][slides]])
+- Uptime: Building Resilient Services with Go — Blake Caldwell ([[https://www.youtube.com/watch?v=PyBJQA4clfc][video]])
+ ([[https://github.com/gophercon/2015-talks/blob/master/Blake%20Caldwell%20-%20Uptime:%20Building%20Resilient%20Services%20with%20Go/2015-GopherCon-Talk-Uptime.pdf][slides]])
+- Cayley: Building a Graph Database — Barak Michener ([[https://www.youtube.com/watch?v=-9kWbPmSyCI][video]])
+ ([[https://github.com/gophercon/2015-talks/blob/master/Barak%20Michener%20-%20Cayley:%20Building%20a%20Graph%20Database/Cayley%20-%20Building%20a%20Graph%20Database.pdf][slides]])
- Code Generation For The Sake Of Consistency — Sarah Adams ([[https://www.youtube.com/watch?v=kGAgHwfjg1s][video]])
-- The Many Faces of Struct Tags — Sam Helman and Kyle Erf ([[https://www.youtube.com/watch?v=_SCRvMunkdA][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Sam%20Helman%20%26%20Kyle%20Erf%20-%20The%20Many%20Faces%20of%20Struct%20Tags/StructTags.pdf][slides]])
+- The Many Faces of Struct Tags — Sam Helman and Kyle Erf ([[https://www.youtube.com/watch?v=_SCRvMunkdA][video]])
+ ([[https://github.com/gophercon/2015-talks/blob/master/Sam%20Helman%20%26%20Kyle%20Erf%20-%20The%20Many%20Faces%20of%20Struct%20Tags/StructTags.pdf][slides]])
- Betting the Company on Go and Winning — Kelsey Hightower ([[https://www.youtube.com/watch?v=wqVbLlHqAeY][video]])
-- How Go Was Made — Andrew Gerrand ([[https://www.youtube.com/watch?v=0ht89TxZZnk][video]]) ([[https://talks.golang.org/2015/how-go-was-made.slide][slides]])
+- How Go Was Made — Andrew Gerrand ([[https://www.youtube.com/watch?v=0ht89TxZZnk][video]])
+ ([[https://talks.golang.org/2015/how-go-was-made.slide][slides]])
The [[http://gophercon.com/schedule/10july/][hack day]] was also a ton of fun,
-with hours of [[https://www.youtube.com/playlist?list=PL2ntRZ1ySWBeHqlHM8DmvS8axgbrpvF9b][lightning talks]] and a range of activities from programming robots
+with hours of [[https://www.youtube.com/playlist?list=PL2ntRZ1ySWBeHqlHM8DmvS8axgbrpvF9b][lightning talks]]
+and a range of activities from programming robots
to a Magic: the Gathering tournament.
Huge thanks to the event organizers Brian Ketelsen and Eric St. Martin and
diff --git a/content/gos-declaration-syntax.article b/content/gos-declaration-syntax.article
index fb7136f..bb1d18f 100644
--- a/content/gos-declaration-syntax.article
+++ b/content/gos-declaration-syntax.article
@@ -6,41 +6,59 @@
* Introduction
-Newcomers to Go wonder why the declaration syntax is different from the tradition established in the C family. In this post we'll compare the two approaches and explain why Go's declarations look as they do.
+Newcomers to Go wonder why the declaration syntax is different from the
+tradition established in the C family.
+In this post we'll compare the two approaches and explain why Go's declarations look as they do.
* C syntax
-First, let's talk about C syntax. C took an unusual and clever approach to declaration syntax. Instead of describing the types with special syntax, one writes an expression involving the item being declared, and states what type that expression will have. Thus
+First, let's talk about C syntax. C took an unusual and clever approach
+to declaration syntax.
+Instead of describing the types with special syntax,
+one writes an expression involving the item being declared,
+and states what type that expression will have. Thus
int x;
-declares x to be an int: the expression 'x' will have type int. In general, to figure out how to write the type of a new variable, write an expression involving that variable that evaluates to a basic type, then put the basic type on the left and the expression on the right.
+declares x to be an int: the expression 'x' will have type int.
+In general, to figure out how to write the type of a new variable,
+write an expression involving that variable that evaluates to a basic type,
+then put the basic type on the left and the expression on the right.
Thus, the declarations
int *p;
int a[3];
-state that p is a pointer to int because '*p' has type int, and that a is an array of ints because a[3] (ignoring the particular index value, which is punned to be the size of the array) has type int.
+state that p is a pointer to int because '*p' has type int,
+and that a is an array of ints because a[3] (ignoring the particular index value,
+which is punned to be the size of the array) has type int.
-What about functions? Originally, C's function declarations wrote the types of the arguments outside the parens, like this:
+What about functions? Originally, C's function declarations wrote the types
+of the arguments outside the parens, like this:
int main(argc, argv)
int argc;
char *argv[];
{ /* ... */ }
-Again, we see that main is a function because the expression main(argc, argv) returns an int. In modern notation we'd write
+Again, we see that main is a function because the expression main(argc,
+argv) returns an int.
+In modern notation we'd write
int main(int argc, char *argv[]) { /* ... */ }
but the basic structure is the same.
-This is a clever syntactic idea that works well for simple types but can get confusing fast. The famous example is declaring a function pointer. Follow the rules and you get this:
+This is a clever syntactic idea that works well for simple types but can get confusing fast.
+The famous example is declaring a function pointer.
+Follow the rules and you get this:
int (*fp)(int a, int b);
-Here, fp is a pointer to a function because if you write the expression (*fp)(a, b) you'll call a function that returns int. What if one of fp's arguments is itself a function?
+Here, fp is a pointer to a function because if you write the expression (*fp)(a,
+b) you'll call a function that returns int.
+What if one of fp's arguments is itself a function?
int (*fp)(int (*ff)(int x, int y), int b)
@@ -54,7 +72,9 @@
char *argv[]
-so you drop the name from the middle of its declaration to construct its type. It's not obvious, though, that you declare something of type char *[] by putting its name in the middle.
+so you drop the name from the middle of its declaration to construct its type.
+It's not obvious, though, that you declare something of type char *[] by
+putting its name in the middle.
And look what happens to fp's declaration if you don't name the parameters:
@@ -64,39 +84,55 @@
int (*)(int, int)
-it's not exactly clear that it's a function pointer declaration at all. And what if the return type is a function pointer?
+it's not exactly clear that it's a function pointer declaration at all.
+And what if the return type is a function pointer?
int (*(*fp)(int (*)(int, int), int))(int, int)
It's hard even to see that this declaration is about fp.
-You can construct more elaborate examples but these should illustrate some of the difficulties that C's declaration syntax can introduce.
+You can construct more elaborate examples but these should illustrate some
+of the difficulties that C's declaration syntax can introduce.
-There's one more point that needs to be made, though. Because type and declaration syntax are the same, it can be difficult to parse expressions with types in the middle. This is why, for instance, C casts always parenthesize the type, as in
+There's one more point that needs to be made, though.
+Because type and declaration syntax are the same,
+it can be difficult to parse expressions with types in the middle.
+This is why, for instance, C casts always parenthesize the type, as in
(int)M_PI
* Go syntax
-Languages outside the C family usually use a distinct type syntax in declarations. Although it's a separate point, the name usually comes first, often followed by a colon. Thus our examples above become something like (in a fictional but illustrative language)
+Languages outside the C family usually use a distinct type syntax in declarations.
+Although it's a separate point, the name usually comes first,
+often followed by a colon.
+Thus our examples above become something like (in a fictional but illustrative language)
x: int
p: pointer to int
a: array[3] of int
-These declarations are clear, if verbose - you just read them left to right. Go takes its cue from here, but in the interests of brevity it drops the colon and removes some of the keywords:
+These declarations are clear, if verbose - you just read them left to right.
+Go takes its cue from here, but in the interests of brevity it drops the
+colon and removes some of the keywords:
x int
p *int
a [3]int
-There is no direct correspondence between the look of [3]int and how to use a in an expression. (We'll come back to pointers in the next section.) You gain clarity at the cost of a separate syntax.
+There is no direct correspondence between the look of [3]int and how to
+use a in an expression.
+(We'll come back to pointers in the next section.) You gain clarity at the
+cost of a separate syntax.
-Now consider functions. Let's transcribe the declaration for main as it would read in Go, although the real main function in Go takes no arguments:
+Now consider functions. Let's transcribe the declaration for main as it would read in Go,
+although the real main function in Go takes no arguments:
func main(argc int, argv []string) int
-Superficially that's not much different from C, other than the change from `char` arrays to strings, but it reads well from left to right:
+Superficially that's not much different from C,
+other than the change from `char` arrays to strings,
+but it reads well from left to right:
function main takes an int and a slice of strings and returns an int.
@@ -104,7 +140,9 @@
func main(int, []string) int
-One merit of this left-to-right style is how well it works as the types become more complex. Here's a declaration of a function variable (analogous to a function pointer in C):
+One merit of this left-to-right style is how well it works as the types
+become more complex.
+Here's a declaration of a function variable (analogous to a function pointer in C):
f func(func(int,int) int, int) int
@@ -112,7 +150,8 @@
f func(func(int,int) int, int) func(int, int) int
-It still reads clearly, from left to right, and it's always obvious which name is being declared - the name comes first.
+It still reads clearly, from left to right,
+and it's always obvious which name is being declared - the name comes first.
The distinction between type and expression syntax makes it easy to write and invoke closures in Go:
@@ -120,12 +159,17 @@
* Pointers
-Pointers are the exception that proves the rule. Notice that in arrays and slices, for instance, Go's type syntax puts the brackets on the left of the type but the expression syntax puts them on the right of the expression:
+Pointers are the exception that proves the rule.
+Notice that in arrays and slices, for instance,
+Go's type syntax puts the brackets on the left of the type but the expression
+syntax puts them on the right of the expression:
var a []int
x = a[1]
-For familiarity, Go's pointers use the * notation from C, but we could not bring ourselves to make a similar reversal for pointer types. Thus pointers work like this
+For familiarity, Go's pointers use the * notation from C,
+but we could not bring ourselves to make a similar reversal for pointer types.
+Thus pointers work like this
var p *int
x = *p
@@ -140,7 +184,10 @@
var p ^int
x = p^
-and perhaps we should have (and chosen another operator for xor), because the prefix asterisk on both types and expressions complicates things in a number of ways. For instance, although one can write
+and perhaps we should have (and chosen another operator for xor),
+because the prefix asterisk on both types and expressions complicates things
+in a number of ways.
+For instance, although one can write
[]int("hi")
@@ -150,10 +197,13 @@
Had we been willing to give up * as pointer syntax, those parentheses would be unnecessary.
-So Go's pointer syntax is tied to the familiar C form, but those ties mean that we cannot break completely from using parentheses to disambiguate types and expressions in the grammar.
+So Go's pointer syntax is tied to the familiar C form,
+but those ties mean that we cannot break completely from using parentheses
+to disambiguate types and expressions in the grammar.
Overall, though, we believe Go's type syntax is easier to understand than C's, especially when things get complicated.
* Notes
-Go's declarations read left to right. It's been pointed out that C's read in a spiral! See [[http://c-faq.com/decl/spiral.anderson.html][ The "Clockwise/Spiral Rule"]] by David Anderson.
+Go's declarations read left to right. It's been pointed out that C's read in a spiral!
+See [[http://c-faq.com/decl/spiral.anderson.html][ The "Clockwise/Spiral Rule"]] by David Anderson.
diff --git a/content/gothamgo.article b/content/gothamgo.article
index 79a78b8..e5e5575 100644
--- a/content/gothamgo.article
+++ b/content/gothamgo.article
@@ -6,7 +6,8 @@
* Introduction
-Last November more than two hundred gophers from all across the United States got together for the first full-day Go conference in New York City.
+Last November more than two hundred gophers from all across the United States
+got together for the first full-day Go conference in New York City.
The diverse speaker lineup included university students, industry experts, and Go team members.
@@ -14,22 +15,50 @@
.image gothamgo/gothamgo.jpg _ 600
-- [[http://vimeo.com/115728346][Launching into Go]] _by_Kathy_Spardlin_ - a CockroachDB contributor provides pointers for people getting started with Go.
-- [[http://vimeo.com/115782573][Error Handling]] _by_ [[https://twitter.com/goinggodotnet][_Bill_Kennedy_]] - ideas on how to use the Go error interface.
-- [[http://vimeo.com/115776445][7 common mistakes in Go and how to avoid them]] _by_ [[https://twitter.com/spf13][_Steve_Francia_]] - the author of some popular Go libraries shares his experience.
-- [[http://vimeo.com/115309491][Cancellation, Context, and Plumbing]] _by_ [[https://twitter.com/sajma][_Sameer_Ajmani_]] - the Google NYC Go team lead explains how cancellation works in Go, and how we're retrofitting the Google code base to use it.
-- [[http://vimeo.com/115940605][Dethorning Package Management]] _by_ [[https://twitter.com/krarick][_Keith_Rarick_]] - the creator of godep talks about how to manage your dependencies well.
-- [[http://vimeo.com/115940590][Everything You've Always Wanted to Know About Go Web Apps (But were afraid to ask)]] _by_ [[https://twitter.com/markbates][_Mark_Bates_]] - a survey of Go packages for building web apps, and insights into why there are so few Go "frameworks".
-- [[http://vimeo.com/116215450][Building high-performance database applications using Aerospike]] _by_Chris_Stivers_ - a principal engineer at Aerospike shares his experiences building scalable applications.
-- [[http://vimeo.com/115307069][The state of Go on the Android platform]] _by_ [[https://twitter.com/davidcrawshaw][_David_Crawshaw_]] - the leader of the Go on mobile platforms project tells us what’s coming up and shows a working demo.
-- [[http://vimeo.com/116108566][Mutexes and Locks]] _by_ [[https://twitter.com/frazelledazzell][_Jessie_Frazelle_]] - a member of the Docker core team tells us about concurrency and what to do when things go wrong.
-- [[http://vimeo.com/115618722][Gobot.io]] _by_ [[https://twitter.com/deadprogram][_Ron_Evans_]] - awesome robots controlled by Go, with demos!
-- [[http://vimeo.com/114941260][Doing Go]] _by_ [[https://twitter.com/bryanl][_Bryan_Liles_]] - a DigitalOcean engineer delivers a hilarious comedy routine that happens to be about Go.
-- [[http://vimeo.com/115308225][Things I learned teaching Go]] _by_ [[https://twitter.com/francesc][_Francesc_Campoy_]] - the Developer Advocate for the Go team shares his experience teaching Go and some advice on how to become a better gopher.
+- [[http://vimeo.com/115728346][Launching into Go]] _by_Kathy_Spardlin_ -
+ a CockroachDB contributor provides pointers for people getting started with Go.
+- [[http://vimeo.com/115782573][Error Handling]] _by_ [[https://twitter.com/goinggodotnet][_Bill_Kennedy_]] -
+ ideas on how to use the Go error interface.
+- [[http://vimeo.com/115776445][7 common mistakes in Go and how to avoid them]] _by_
+ [[https://twitter.com/spf13][_Steve_Francia_]] - the author of some popular
+ Go libraries shares his experience.
+- [[http://vimeo.com/115309491][Cancellation, Context, and Plumbing]] _by_
+ [[https://twitter.com/sajma][_Sameer_Ajmani_]] - the Google NYC Go team
+ lead explains how cancellation works in Go,
+ and how we're retrofitting the Google code base to use it.
+- [[http://vimeo.com/115940605][Dethorning Package Management]] _by_ [[https://twitter.com/krarick][_Keith_Rarick_]] -
+ the creator of godep talks about how to manage your dependencies well.
+- [[http://vimeo.com/115940590][Everything You've Always Wanted to Know About Go Web Apps (But were afraid to ask)]]
+ _by_ [[https://twitter.com/markbates][_Mark_Bates_]] - a survey of Go packages
+ for building web apps,
+ and insights into why there are so few Go "frameworks".
+- [[http://vimeo.com/116215450][Building high-performance database applications using Aerospike]]
+ _by_Chris_Stivers_ - a principal engineer at Aerospike shares his experiences
+ building scalable applications.
+- [[http://vimeo.com/115307069][The state of Go on the Android platform]]
+ _by_ [[https://twitter.com/davidcrawshaw][_David_Crawshaw_]] - the leader
+ of the Go on mobile platforms project tells us what’s coming up and shows a working demo.
+- [[http://vimeo.com/116108566][Mutexes and Locks]] _by_ [[https://twitter.com/frazelledazzell][_Jessie_Frazelle_]] -
+ a member of the Docker core team tells us about concurrency and what to
+ do when things go wrong.
+- [[http://vimeo.com/115618722][Gobot.io]] _by_ [[https://twitter.com/deadprogram][_Ron_Evans_]] -
+ awesome robots controlled by Go, with demos!
+- [[http://vimeo.com/114941260][Doing Go]] _by_ [[https://twitter.com/bryanl][_Bryan_Liles_]] -
+ a DigitalOcean engineer delivers a hilarious comedy routine that happens to be about Go.
+- [[http://vimeo.com/115308225][Things I learned teaching Go]] _by_ [[https://twitter.com/francesc][_Francesc_Campoy_]] -
+ the Developer Advocate for the Go team shares his experience teaching Go
+ and some advice on how to become a better gopher.
Two more talks come from the Go meetup in New York City, which met the day before GothamGo:
-- [[http://vimeo.com/114975899][Benchmarking Go]] _by_ [[https://twitter.com/bbulkow][_Brian_Bulkowski_]] - the founder of Aerospike talks about profiling tools for Go and Linux, and micro benchmarks for goroutines, channels, buffers, and and other Go features.
-- [[http://vimeo.com/114736889][Go Static Analysis Tools]] _by_Alan_Donovan_ - a member of the Go team at Google NY gives a guided tour of several static analysis tools designed to help Go programmers understand, navigate , and refactor their code.
+- [[http://vimeo.com/114975899][Benchmarking Go]] _by_ [[https://twitter.com/bbulkow][_Brian_Bulkowski_]] -
+ the founder of Aerospike talks about profiling tools for Go and Linux,
+ and micro benchmarks for goroutines, channels,
+ buffers, and and other Go features.
+- [[http://vimeo.com/114736889][Go Static Analysis Tools]] _by_Alan_Donovan_ -
+ a member of the Go team at Google NY gives a guided tour of several static
+ analysis tools designed to help Go programmers understand,
+ navigate , and refactor their code.
-Make sure to have a look at all of those in preparation for the [[https://fosdem.org/][FOSDEM]] Go devroom FOSDEM in Brussels (Belgium) and [[http://www.gophercon.in/][gophercon.in]] in Bengaluru (India).
+Make sure to have a look at all of those in preparation for the [[https://fosdem.org/][FOSDEM]] Go
+devroom FOSDEM in Brussels (Belgium) and [[http://www.gophercon.in/][gophercon.in]] in Bengaluru (India).
diff --git a/content/gouk15.article b/content/gouk15.article
index 9b20398..513c500 100644
--- a/content/gouk15.article
+++ b/content/gouk15.article
@@ -18,19 +18,28 @@
Main track:
-- Stupid Gopher Tricks, by [[https://twitter.com/enneff][Andrew Gerrand]] ([[https://www.youtube.com/watch?v=UECh7X07m6E&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Complex Concurrency Patterns in Go, by [[https://twitter.com/eapache][Evan Huus]] ([[https://www.youtube.com/watch?v=2HOO5gIgyMg&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Code Analysis [no reading required], by [[https://twitter.com/francesc][Francesc Campoy]] ([[https://www.youtube.com/watch?v=oorX84tBMqo&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Go kit: a toolkit for microservices [[https://twitter.com/peterbourgon][Peter Bourgon]] ([[https://www.youtube.com/watch?v=aL6sd4d4hxk&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Dependency Management Conundrum, by [[https://twitter.com/goinggodotnet][William Kennedy]] ([[https://www.youtube.com/watch?v=CdhucJShJU8&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
+- Stupid Gopher Tricks, by [[https://twitter.com/enneff][Andrew Gerrand]]
+ ([[https://www.youtube.com/watch?v=UECh7X07m6E&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
+- Complex Concurrency Patterns in Go, by [[https://twitter.com/eapache][Evan Huus]]
+ ([[https://www.youtube.com/watch?v=2HOO5gIgyMg&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
+- Code Analysis [no reading required], by [[https://twitter.com/francesc][Francesc Campoy]]
+ ([[https://www.youtube.com/watch?v=oorX84tBMqo&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
+- Go kit: a toolkit for microservices [[https://twitter.com/peterbourgon][Peter Bourgon]]
+ ([[https://www.youtube.com/watch?v=aL6sd4d4hxk&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
+- Dependency Management Conundrum, by [[https://twitter.com/goinggodotnet][William Kennedy]]
+ ([[https://www.youtube.com/watch?v=CdhucJShJU8&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
Side track:
- Building APIs, by [[https://twitter.com/matryer][Mat Ryer]] ([[https://www.youtube.com/watch?v=tIm8UkSf6RA&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Building a Bank with Go, by [[https://twitter.com/mattheath][Matt Heath]] ([[https://www.youtube.com/watch?v=cFJkLfujOts&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- CockroachDB: Make Data Easy, by [[https://twitter.com/bendarnell][Ben Darnell]] ([[https://www.youtube.com/watch?v=33oqpLmQ3LE&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Understanding memory allocation in Go, by [[https://twitter.com/DeanElbaz][Dean Elbaz]] ([[https://www.youtube.com/watch?v=zjoieOpy5hE&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Whispered Secrets, by [[https://twitter.com/feyeleanor][Eleanor McHugh]] ([[https://www.youtube.com/watch?v=ViBRx-F4Z2U&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
+- Building a Bank with Go, by [[https://twitter.com/mattheath][Matt Heath]]
+ ([[https://www.youtube.com/watch?v=cFJkLfujOts&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
+- CockroachDB: Make Data Easy, by [[https://twitter.com/bendarnell][Ben Darnell]]
+ ([[https://www.youtube.com/watch?v=33oqpLmQ3LE&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
+- Understanding memory allocation in Go, by [[https://twitter.com/DeanElbaz][Dean Elbaz]]
+ ([[https://www.youtube.com/watch?v=zjoieOpy5hE&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
+- Whispered Secrets, by [[https://twitter.com/feyeleanor][Eleanor McHugh]]
+ ([[https://www.youtube.com/watch?v=ViBRx-F4Z2U&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
Finally [[https://twitter.com/dgryski][Damian Gryski]] took the stage for the
closing keynote ([[https://www.youtube.com/watch?v=IiSyFc10Jj0&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]]),
diff --git a/content/introducing-go-playground.article b/content/introducing-go-playground.article
index 5fed8ae..34fdcca 100644
--- a/content/introducing-go-playground.article
+++ b/content/introducing-go-playground.article
@@ -6,11 +6,31 @@
* Introduction
-If you visit [[https://golang.org/][golang.org]] today you'll see our new look. We have given the site a new coat of paint and reorganized its content to make it easier to find. These changes are also reflected in the web interface of [[https://golang.org/cmd/godoc/][godoc]], the Go documentation tool.
+If you visit [[https://golang.org/][golang.org]] today you'll see our new look.
+We have given the site a new coat of paint and reorganized its content to
+make it easier to find.
+These changes are also reflected in the web interface of [[https://golang.org/cmd/godoc/][godoc]],
+the Go documentation tool.
But the real news is a prominent new feature: the [[https://golang.org/][Go Playground]].
.image introducing-go-playground_Untitled.png
-The Playground allows anyone with a web browser to write Go code that we immediately compile, link, and run on our servers. There are a few example programs to get you started (see the "Examples" drop-down). We hope that this will give curious programmers an opportunity to try the language before [[https://golang.org/doc/install.html][installing it]], and experienced Go users a convenient place in which to experiment. Beyond the front page, this functionality has the potential to make our reference and tutorial materials more engaging. We hope to extend its use in the near future.
+The Playground allows anyone with a web browser to write Go code that we
+immediately compile,
+link, and run on our servers.
+There are a few example programs to get you started (see the "Examples" drop-down).
+We hope that this will give curious programmers an opportunity to try the
+language before [[https://golang.org/doc/install.html][installing it]],
+and experienced Go users a convenient place in which to experiment.
+Beyond the front page, this functionality has the potential to make our
+reference and tutorial materials more engaging.
+We hope to extend its use in the near future.
-Of course, there are some limitations to the kinds of programs you can run in the Playground. We can't simply accept arbitrary code and run it on our servers without restrictions. The programs build and run in a sandbox with a reduced standard library; the only communication your program has to the outside world is via standard output, and there are limits to CPU and memory use. As such, consider this just a taste of the wonderful world of Go; to have the full experience you'll need to [[https://golang.org/doc/install.html][download it yourself]].
-If you've been meaning to try Go but never got around to it, why not visit [[https://golang.org/][golang.org]] to try it right now?
+Of course, there are some limitations to the kinds of programs you can run in the Playground.
+We can't simply accept arbitrary code and run it on our servers without restrictions.
+The programs build and run in a sandbox with a reduced standard library;
+the only communication your program has to the outside world is via standard output,
+and there are limits to CPU and memory use.
+As such, consider this just a taste of the wonderful world of Go;
+to have the full experience you'll need to [[https://golang.org/doc/install.html][download it yourself]].
+If you've been meaning to try Go but never got around to it,
+why not visit [[https://golang.org/][golang.org]] to try it right now?
diff --git a/content/introducing-gofix.article b/content/introducing-gofix.article
index 5b42b5b..ebe4e55 100644
--- a/content/introducing-gofix.article
+++ b/content/introducing-gofix.article
@@ -6,15 +6,57 @@
* Introduction
-The next Go release will include significant API changes in several fundamental Go packages. Code that [[http://codereview.appspot.com/4239076][implements an HTTP server handler]], [[http://codereview.appspot.com/4244055][calls `net.Dial`]], [[http://codereview.appspot.com/4357052][calls `os.Open`]], or [[http://codereview.appspot.com/4281055][uses the reflect package]] will not build unless it is updated to use the new APIs. Now that our releases are [[https://blog.golang.org/2011/03/go-becomes-more-stable.html][more stable and less frequent]], this will be a common situation. Each of these API changes happened in a different weekly snapshot and might have been manageable on its own; together, however, they represent a significant amount of manual effort to update existing code.
+The next Go release will include significant API changes in several fundamental Go packages.
+Code that [[http://codereview.appspot.com/4239076][implements an HTTP server handler]],
+[[http://codereview.appspot.com/4244055][calls `net.Dial`]],
+[[http://codereview.appspot.com/4357052][calls `os.Open`]],
+or [[http://codereview.appspot.com/4281055][uses the reflect package]] will
+not build unless it is updated to use the new APIs.
+Now that our releases are [[https://blog.golang.org/2011/03/go-becomes-more-stable.html][more stable and less frequent]],
+this will be a common situation.
+Each of these API changes happened in a different weekly snapshot and might
+have been manageable on its own;
+together, however, they represent a significant amount of manual effort
+to update existing code.
-[[https://golang.org/cmd/fix/][Gofix]] is a new tool that reduces the amount of effort it takes to update existing code. It reads a program from a source file, looks for uses of old APIs, rewrites them to use the current API, and writes the program back to the file. Not all API changes preserve all the functionality of an old API, so gofix cannot always do a perfect job. When gofix cannot rewrite a use of an old API, it prints a warning giving the file name and line number of the use, so that a developer can examine and rewrite the code. Gofix takes care of the easy, repetitive, tedious changes, so that a developer can focus on the ones that truly merit attention.
+[[https://golang.org/cmd/fix/][Gofix]] is a new tool that reduces the amount
+of effort it takes to update existing code.
+It reads a program from a source file, looks for uses of old APIs,
+rewrites them to use the current API, and writes the program back to the file.
+Not all API changes preserve all the functionality of an old API,
+so gofix cannot always do a perfect job.
+When gofix cannot rewrite a use of an old API,
+it prints a warning giving the file name and line number of the use,
+so that a developer can examine and rewrite the code.
+Gofix takes care of the easy, repetitive,
+tedious changes, so that a developer can focus on the ones that truly merit attention.
-Each time we make a significant API change we’ll add code to gofix to take care of the conversion, as much as mechanically possible. When you update to a new Go release and your code no longer builds, just run gofix on your source directory.
+Each time we make a significant API change we’ll add code to gofix to
+take care of the conversion,
+as much as mechanically possible.
+When you update to a new Go release and your code no longer builds,
+just run gofix on your source directory.
-You can extend gofix to support changes to your own APIs. The gofix program is a simple driver around plugins called fixes that each handle a particular API change. Right now, writing a new fix requires doing some scanning and rewriting of the go/ast syntax tree, usually in proportion to how complex the API changes are. If you want to explore, the [[https://go.googlesource.com/go/+/go1/src/cmd/fix/netdial.go][`netdialFix`]], [[https://go.googlesource.com/go/+/go1/src/cmd/fix/osopen.go][`osopenFix`]], [[https://go.googlesource.com/go/+/go1/src/cmd/fix/httpserver.go][`httpserverFix`]], and [[https://go.googlesource.com/go/+/go1/src/cmd/fix/reflect.go][`reflectFix`]] are all illustrative examples, in increasing order of complexity.
+You can extend gofix to support changes to your own APIs.
+The gofix program is a simple driver around plugins called fixes that each
+handle a particular API change.
+Right now, writing a new fix requires doing some scanning and rewriting
+of the go/ast syntax tree,
+usually in proportion to how complex the API changes are.
+If you want to explore, the [[https://go.googlesource.com/go/+/go1/src/cmd/fix/netdial.go][`netdialFix`]],
+[[https://go.googlesource.com/go/+/go1/src/cmd/fix/osopen.go][`osopenFix`]],
+[[https://go.googlesource.com/go/+/go1/src/cmd/fix/httpserver.go][`httpserverFix`]],
+and [[https://go.googlesource.com/go/+/go1/src/cmd/fix/reflect.go][`reflectFix`]]
+are all illustrative examples,
+in increasing order of complexity.
-We write Go code too, of course, and our code is just as affected by these API changes as yours. Typically, we write the gofix support at the same time as the API change and then use gofix to rewrite the uses in the main source tree. We use gofix to update other Go code bases and our personal projects. We even use gofix to update Google’s internal source tree when it is time to build against a new Go release.
+We write Go code too, of course, and our code is just as affected by these
+API changes as yours.
+Typically, we write the gofix support at the same time as the API change
+and then use gofix to rewrite the uses in the main source tree.
+We use gofix to update other Go code bases and our personal projects.
+We even use gofix to update Google’s internal source tree when it is time
+to build against a new Go release.
As an example, gofix can rewrite code like [[http://codereview.appspot.com/4353043/diff/10001/src/pkg/fmt/print.go#newcode657][this snippet from `fmt/print.go`]]:
@@ -48,8 +90,24 @@
// ...
}
-Nearly every line above changed in some small way. The changes involved in the rewrite are extensive but nearly entirely mechanical, just the kind of thing that computers are great at doing.
+Nearly every line above changed in some small way.
+The changes involved in the rewrite are extensive but nearly entirely mechanical,
+just the kind of thing that computers are great at doing.
-Gofix is possible because Go has support in its standard libraries for [[https://golang.org/pkg/go/parser][parsing Go source files into syntax trees]] and also for [[https://golang.org/pkg/go/printer][printing those syntax trees back to Go source code]]. Importantly, the Go printing library prints a program in the official format (typically enforced via the gofmt tool), allowing gofix to make mechanical changes to Go programs without causing spurious formatting changes. In fact, one of the key motivations for creating gofmt—perhaps second only to avoiding debates about where a particular brace belongs—was to simplify the creation of tools that rewrite Go programs, as gofix does.
+Gofix is possible because Go has support in its standard libraries for [[https://golang.org/pkg/go/parser][parsing Go source files into syntax trees]]
+and also for [[https://golang.org/pkg/go/printer][printing those syntax trees back to Go source code]].
+Importantly, the Go printing library prints a program in the official format
+(typically enforced via the gofmt tool),
+allowing gofix to make mechanical changes to Go programs without causing
+spurious formatting changes.
+In fact, one of the key motivations for creating gofmt—perhaps second
+only to avoiding debates about where a particular brace belongs—was to
+simplify the creation of tools that rewrite Go programs, as gofix does.
-Gofix has already made itself indispensable. In particular, the recent reflect changes would have been unpalatable without automated conversion, and the reflect API badly needed to be redone. Gofix gives us the ability to fix mistakes or completely rethink package APIs without worrying about the cost of converting existing code. We hope you find gofix as useful and convenient as we have.
+Gofix has already made itself indispensable.
+In particular, the recent reflect changes would have been unpalatable without
+automated conversion,
+and the reflect API badly needed to be redone.
+Gofix gives us the ability to fix mistakes or completely rethink package
+APIs without worrying about the cost of converting existing code.
+We hope you find gofix as useful and convenient as we have.
diff --git a/content/io2014.article b/content/io2014.article
index d115acb..c0b945d 100644
--- a/content/io2014.article
+++ b/content/io2014.article
@@ -20,8 +20,10 @@
On the Monday, more than 200 gophers gathered at the Google office in San
Francisco to hear a series of talks:
-- The State of Go, ([[https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVQm9tdncxWnJGUTQ/edit][slides]] and [[http://www.hakkalabs.co/articles/state-go][video]]) by Andrew Gerrand.
-- I was wrong, again! ([[https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVTTUwS25qaFlzMGs/edit][slides]] and [[http://www.hakkalabs.co/articles/why-we-use-go][video]]), by Derek Collison.
+- The State of Go, ([[https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVQm9tdncxWnJGUTQ/edit][slides]]
+ and [[http://www.hakkalabs.co/articles/state-go][video]]) by Andrew Gerrand.
+- I was wrong, again! ([[https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVTTUwS25qaFlzMGs/edit][slides]]
+ and [[http://www.hakkalabs.co/articles/why-we-use-go][video]]), by Derek Collison.
- Go at Splice ([[https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVZklnNnJITlhSbXc/edit][slides]]), by Matt Aimonetti
- Quick testing with quick ([[https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVVElmOHpwamp4aTA/edit][slides]]), by Evan Shaw
- Something about Go (no slides), by Blake Mizerany.
@@ -48,20 +50,27 @@
soon.
- Organizing Go Code, by David Crawshaw. ([[https://talks.golang.org/2014/organizeio.slide#1][slides]])
-- Testing Techniques, by Andrew Gerrand. ([[https://www.youtube.com/watch?v=ndmB0bj7eyw][video]] and [[https://talks.golang.org/2014/testing.slide#1][slides]])
+- Testing Techniques, by Andrew Gerrand. ([[https://www.youtube.com/watch?v=ndmB0bj7eyw][video]]
+ and [[https://talks.golang.org/2014/testing.slide#1][slides]])
- Go for Java Developers, by Francesc Campoy. ([[https://talks.golang.org/2014/go4java.slide#1][slides]])
-- Camlistore: Android, ARM, App Engine, Everywhere, by Brad Fitzpatrick. ([[https://talks.golang.org/2014/camlistore.slide#1][slides]])
+- Camlistore: Android, ARM, App Engine, Everywhere,
+ by Brad Fitzpatrick.
+ ([[https://talks.golang.org/2014/camlistore.slide#1][slides]])
- Go Compilation Complexities, by Ian Lance Taylor. ([[https://talks.golang.org/2014/compiling.slide#1][slides]])
-- SourceGraph: a Code Search Engine in Go, by Quinn Slack. ([[https://youtu.be/-DpKaoPz8l8][video]] and [[https://go-talks.appspot.com/github.com/sourcegraph/talks/google-io-2014/gio2014.slide#1][slides]])
+- SourceGraph: a Code Search Engine in Go,
+ by Quinn Slack. ([[https://youtu.be/-DpKaoPz8l8][video]] and [[https://go-talks.appspot.com/github.com/sourcegraph/talks/google-io-2014/gio2014.slide#1][slides]])
We also organized Q&A sessions and lightning talks by members of the Go
community:
- [[https://twitter.com/bradrydzewski][Brad Rydzewski]] talked about his project [[https://drone.io/][drone.io]].
-- [[https://twitter.com/barakmich][Barak Michener]] presented [[https://github.com/google/cayley][Cayley]], an open source graph database.
+- [[https://twitter.com/barakmich][Barak Michener]] presented [[https://github.com/google/cayley][Cayley]],
+ an open source graph database.
- [[https://twitter.com/mattetti][Matt Aimonetti]] discussed how Go is used at [[https://splice.com/][Splice]].
-- [[https://twitter.com/ssougou][Sugu Sougoumarane]] talked about how [[https://github.com/youtube/vitess][vitess]] solved scalability problems at YouTube. ([[https://youtu.be/midJ6b1LkA0][video]])
+- [[https://twitter.com/ssougou][Sugu Sougoumarane]] talked about how [[https://github.com/youtube/vitess][vitess]] solved
+ scalability problems at YouTube.
+ ([[https://youtu.be/midJ6b1LkA0][video]])
** The Go code lab
diff --git a/content/ismmkeynote.article b/content/ismmkeynote.article
index 00ef826..2e1f91d 100644
--- a/content/ismmkeynote.article
+++ b/content/ismmkeynote.article
@@ -5,13 +5,28 @@
rlh@golang.org
* Abstract
-This is the transcript from the keynote I gave at the International Symposium on Memory Management (ISMM) on June 18, 2018. For the past 25 years ISMM has been the premier venue for publishing memory management and garbage collection papers and it was an honor to have been invited to give the keynote.
+This is the transcript from the keynote I gave at the International Symposium
+on Memory Management (ISMM) on June 18, 2018.
+For the past 25 years ISMM has been the premier venue for publishing memory
+management and garbage collection papers and it was an honor to have been
+invited to give the keynote.
** Abstract
-The Go language features, goals, and use cases have forced us to rethink the entire garbage collection stack and have led us to a surprising place. The journey has been exhilarating. This talk describes our journey. It is a journey motivated by open source and Google's production demands. Included are side hikes into dead end box canyons where numbers guided us home. This talk will provide insight into the how and the why of our journey, where we are in 2018, and Go's preparation for the next part of the journey.
+The Go language features, goals, and use cases have forced us to rethink
+the entire garbage collection stack and have led us to a surprising place.
+The journey has been exhilarating. This talk describes our journey.
+It is a journey motivated by open source and Google's production demands.
+Included are side hikes into dead end box canyons where numbers guided us home.
+This talk will provide insight into the how and the why of our journey,
+where we are in 2018, and Go's preparation for the next part of the journey.
** Bio
-Richard L. Hudson (Rick) is best known for his work in memory management including the invention of the Train, Sapphire, and Mississippi Delta algorithms as well as GC stack maps which enabled garbage collection in statically typed languages such as Modula-3, Java, C#, and Go. Rick is currently a member of Google's Go team where he is working on Go's garbage collection and runtime issues.
+Richard L. Hudson (Rick) is best known for his work in memory management
+including the invention of the Train,
+Sapphire, and Mississippi Delta algorithms as well as GC stack maps which
+enabled garbage collection in statically typed languages such as Modula-3, Java, C#, and Go.
+Rick is currently a member of Google's Go team where he is working on Go's
+garbage collection and runtime issues.
Contact: rlh@golang.org
@@ -23,17 +38,25 @@
Rick Hudson here.
-This is a talk about the Go runtime and in particular the garbage collector. I have about 45 or 50 minutes of prepared material and after that we will have time for discussion and I'll be around so feel free to come up afterwards.
+This is a talk about the Go runtime and in particular the garbage collector.
+I have about 45 or 50 minutes of prepared material and after that we will
+have time for discussion and I'll be around so feel free to come up afterwards.
.image ismmkeynote/image24.png
Before I get started I want to acknowledge some people.
-A lot of the good stuff in the talk was done by Austin Clements. Other people on the Cambridge Go team, Russ, Than, Cherry, and David have been an engaging, exciting, and fun group to work with.
+A lot of the good stuff in the talk was done by Austin Clements.
+Other people on the Cambridge Go team, Russ,
+Than, Cherry, and David have been an engaging,
+exciting, and fun group to work with.
-We also want to thank the 1.6 million Go users worldwide for giving us interesting problems to solve. Without them a lot of these problems would never come to light.
+We also want to thank the 1.6 million Go users worldwide for giving us interesting problems to solve.
+Without them a lot of these problems would never come to light.
-And finally I want to acknowledge Renee French for all these nice Gophers that she has been producing over the years. You will see several of them throughout the talk.
+And finally I want to acknowledge Renee French for all these nice Gophers
+that she has been producing over the years.
+You will see several of them throughout the talk.
.image ismmkeynote/image38.png
@@ -41,25 +64,45 @@
.image ismmkeynote/image32.png
-Well first of all Go programs have hundreds of thousands of stacks. They are managed by the Go scheduler and are always preempted at GC safepoints. The Go scheduler multiplexes Go routines onto OS threads which hopefully run with one OS thread per HW thread. We manage the stacks and their size by copying them and updating pointers in the stack. It's a local operation so it scales fairly well.
+Well first of all Go programs have hundreds of thousands of stacks.
+They are managed by the Go scheduler and are always preempted at GC safepoints.
+The Go scheduler multiplexes Go routines onto OS threads which hopefully
+run with one OS thread per HW thread.
+We manage the stacks and their size by copying them and updating pointers in the stack.
+It's a local operation so it scales fairly well.
.image ismmkeynote/image22.png
-The next thing that is important is the fact that Go is a value-oriented language in the tradition of C-like systems languages rather than reference-oriented language in the tradition of most managed runtime languages. For example, this shows how a type from the tar package is laid out in memory. All of the fields are embedded directly in the Reader value. This gives programmers more control over memory layout when they need it. One can collocate fields that have related values which helps with cache locality.
+The next thing that is important is the fact that Go is a value-oriented
+language in the tradition of C-like systems languages rather than reference-oriented
+language in the tradition of most managed runtime languages.
+For example, this shows how a type from the tar package is laid out in memory.
+All of the fields are embedded directly in the Reader value.
+This gives programmers more control over memory layout when they need it.
+One can collocate fields that have related values which helps with cache locality.
-Value-orientation also helps with the foreign function interfaces. We have a fast FFI with C and C++. Obviously Google has a tremendous number of facilities available but they are written in C++. Go couldn't wait to reimplement all of these things in Go so Go had to have access to these systems through the foreign function interface.
+Value-orientation also helps with the foreign function interfaces.
+We have a fast FFI with C and C++. Obviously Google has a tremendous number
+of facilities available but they are written in C++.
+Go couldn't wait to reimplement all of these things in Go so Go had to have
+access to these systems through the foreign function interface.
-This one design decision has led to some of the more amazing things that have to go on with the runtime. It is probably the most important thing that differentiates Go from other GCed languages.
+This one design decision has led to some of the more amazing things that
+have to go on with the runtime.
+It is probably the most important thing that differentiates Go from other GCed languages.
.image ismmkeynote/image60.png
-Of course Go can have pointers and in fact they can have interior pointers. Such pointers keep the entire value live and they are fairly common.
+Of course Go can have pointers and in fact they can have interior pointers.
+Such pointers keep the entire value live and they are fairly common.
.image ismmkeynote/image29.png
We also have a way ahead of time compilation system so the binary contains the entire runtime.
-There is no JIT recompilation. There are pluses and minuses to this. First of all, reproducibility of program execution is a lot easier which makes moving forward with compiler improvements much faster.
+There is no JIT recompilation. There are pluses and minuses to this.
+First of all, reproducibility of program execution is a lot easier which
+makes moving forward with compiler improvements much faster.
On the sad side of it we don't have the chance to do feedback optimizations as you would with a JITed system.
@@ -67,9 +110,24 @@
.image ismmkeynote/image13.png
-Go comes with two knobs to control the GC. The first one is GCPercent. Basically this is a knob that adjusts how much CPU you want to use and how much memory you want to use. The default is 100 which means that half the heap is dedicated to live memory and half the heap is dedicated to allocation. You can modify this in either direction.
+Go comes with two knobs to control the GC.
+The first one is GCPercent. Basically this is a knob that adjusts how much
+CPU you want to use and how much memory you want to use.
+The default is 100 which means that half the heap is dedicated to live memory
+and half the heap is dedicated to allocation.
+You can modify this in either direction.
-MaxHeap, which is not yet released but is being used and evaluated internally, lets the programmer set what the maximum heap size should be. Out of memory, OOMs, are tough on Go; temporary spikes in memory usage should be handled by increasing CPU costs, not by aborting. Basically if the GC sees memory pressure it informs the application that it should shed load. Once things are back to normal the GC informs the application that it can go back to its regular load. MaxHeap also provides a lot more flexibility in scheduling. Instead of always being paranoid about how much memory is available the runtime can size the heap up to the MaxHeap.
+MaxHeap, which is not yet released but is being used and evaluated internally,
+lets the programmer set what the maximum heap size should be.
+Out of memory, OOMs, are tough on Go; temporary spikes in memory usage should
+be handled by increasing CPU costs, not by aborting.
+Basically if the GC sees memory pressure it informs the application that
+it should shed load.
+Once things are back to normal the GC informs the application that it can
+go back to its regular load.
+MaxHeap also provides a lot more flexibility in scheduling.
+Instead of always being paranoid about how much memory is available the
+runtime can size the heap up to the MaxHeap.
This wraps up our discussion on the pieces of Go that are important to the garbage collector.
@@ -79,9 +137,12 @@
.image ismmkeynote/image59.png
-So it's 2014. If Go does not solve this GC latency problem somehow then Go isn't going to be successful. That was clear.
+So it's 2014. If Go does not solve this GC latency problem somehow then
+Go isn't going to be successful. That was clear.
-Other new languages were facing the same problem. Languages like Rust went a different way but we are going to talk about the path that Go took.
+Other new languages were facing the same problem.
+Languages like Rust went a different way but we are going to talk about
+the path that Go took.
Why is latency so important?
@@ -89,11 +150,24 @@
The math is completely unforgiving on this.
-A 99%ile isolated GC latency service level objective (SLO), such as 99% of the time a GC cycle takes < 10ms, just simply doesn't scale. What matters is latency during an entire session or through the course of using an app many times in a day. Assume a session that browses several web pages ends up making 100 server requests during a session or it makes 20 requests and you have 5 sessions packed up during the day. In that situation only 37% of users will have a consistent sub 10ms experience across the entire session.
+A 99%ile isolated GC latency service level objective (SLO),
+such as 99% of the time a GC cycle takes < 10ms,
+just simply doesn't scale.
+What matters is latency during an entire session or through the course of
+using an app many times in a day.
+Assume a session that browses several web pages ends up making 100 server
+requests during a session or it makes 20 requests and you have 5 sessions
+packed up during the day.
+In that situation only 37% of users will have a consistent sub 10ms experience
+across the entire session.
-If you want 99% of those users to have a sub 10ms experience, as we are suggesting, the math says you really need to target 4 9s or the 99.99%ile.
+If you want 99% of those users to have a sub 10ms experience,
+as we are suggesting, the math says you really need to target 4 9s or the 99.99%ile.
-So it's 2014 and Jeff Dean had just come out with his paper called 'The Tail at Scale' which this digs into this further. It was being widely read around Google since it had serious ramifications for Google going forward and trying to scale at Google scale.
+So it's 2014 and Jeff Dean had just come out with his paper called 'The
+Tail at Scale' which this digs into this further.
+It was being widely read around Google since it had serious ramifications
+for Google going forward and trying to scale at Google scale.
We call this problem the tyranny of the 9s.
@@ -103,35 +177,67 @@
A lot of things were being done in 2014.
-If you want 10 answers ask for several more and take the first 10 and those are the answers you put on your search page. If the request exceeds 50%ile reissue or forward the request to another server. If GC is about to run, refuse new requests or forward the requests to another server until GC is done. And so forth and so on.
+If you want 10 answers ask for several more and take the first 10 and those
+are the answers you put on your search page.
+If the request exceeds 50%ile reissue or forward the request to another server.
+If GC is about to run, refuse new requests or forward the requests to another
+server until GC is done.
+And so forth and so on.
-All these are workarounds come from very clever people with very real problems but they didn't tackle the root problem of GC latency. At Google scale we had to tackle the root problem. Why?
+All these are workarounds come from very clever people with very real problems
+but they didn't tackle the root problem of GC latency.
+At Google scale we had to tackle the root problem. Why?
.image ismmkeynote/image48.png
Redundancy wasn't going to scale, redundancy costs a lot. It costs new server farms.
-We hoped we could solve this problem and saw it as an opportunity to improve the server ecosystem and in the process save some of the endangered corn fields and give some kernel of corn the chance to be knee high by the fourth of July and reach its full potential.
+We hoped we could solve this problem and saw it as an opportunity to improve
+the server ecosystem and in the process save some of the endangered corn
+fields and give some kernel of corn the chance to be knee high by the fourth
+of July and reach its full potential.
.image ismmkeynote/image56.png
-So here is the 2014 SLO. Yes, it was true that I was sandbagging, I was new on the team, it was a new process to me, and I didn't want to over promise.
+So here is the 2014 SLO. Yes, it was true that I was sandbagging,
+I was new on the team, it was a new process to me,
+and I didn't want to over promise.
Furthermore presentations about GC latency in other languages were just plain scary.
.image ismmkeynote/image67.png
-The original plan was to do a read barrier free concurrent copying GC. That was the long term plan. There was a lot of uncertainty about the overhead of read barriers so Go wanted to avoid them.
+The original plan was to do a read barrier free concurrent copying GC.
+That was the long term plan. There was a lot of uncertainty about the overhead
+of read barriers so Go wanted to avoid them.
-But short term 2014 we had to get our act together. We had to convert all of the runtime and compiler to Go. They were written in C at the time. No more C, no long tail of bugs due to C coders not understanding GC but having a cool idea about how to copy strings. We also needed something quickly and focused on latency but the performance hit had to be less than the speedups provided by the compiler. So we were limited. We had basically a year of compiler performance improvements that we could eat up by making the GC concurrent. But that was it. We couldn't slow down Go programs. That would have been untenable in 2014.
+But short term 2014 we had to get our act together.
+We had to convert all of the runtime and compiler to Go.
+They were written in C at the time. No more C,
+no long tail of bugs due to C coders not understanding GC but having a cool
+idea about how to copy strings.
+We also needed something quickly and focused on latency but the performance
+hit had to be less than the speedups provided by the compiler.
+So we were limited. We had basically a year of compiler performance improvements
+that we could eat up by making the GC concurrent.
+But that was it. We couldn't slow down Go programs.
+That would have been untenable in 2014.
.image ismmkeynote/image28.png
So we backed off a bit. We weren't going to do the copying part.
-The decision was to do a tri-color concurrent algorithm. Earlier in my career Eliot Moss and I had done the journal proofs showing that Dijkstra's algorithm worked with multiple application threads. We also showed we could knock off the STW problems, and we had proofs that it could be done.
+The decision was to do a tri-color concurrent algorithm.
+Earlier in my career Eliot Moss and I had done the journal proofs showing
+that Dijkstra's algorithm worked with multiple application threads.
+We also showed we could knock off the STW problems,
+and we had proofs that it could be done.
-We were also concerned about compiler speed, that is the code the compiler generated. If we kept the write barrier turned off most of the time the compiler optimizations would be minimally impacted and the compiler team could move forward rapidly. Go also desperately needed short term success in 2015.
+We were also concerned about compiler speed,
+that is the code the compiler generated.
+If we kept the write barrier turned off most of the time the compiler optimizations
+would be minimally impacted and the compiler team could move forward rapidly.
+Go also desperately needed short term success in 2015.
.image ismmkeynote/image55.png
@@ -139,77 +245,148 @@
We went with a size segregated span. Interior pointers were a problem.
-The garbage collector needs to efficiently find the start of the object. If it knows the size of the objects in a span it simply rounds down to that size and that will be the start of the object.
+The garbage collector needs to efficiently find the start of the object.
+If it knows the size of the objects in a span it simply rounds down to that
+size and that will be the start of the object.
Of course size segregated spans have some other advantages.
-Low fragmentation: Experience with C, besides Google's TCMalloc and Hoard, I was intimately involved with Intel's Scalable Malloc and that work gave us confidence that fragmentation was not going to be a problem with non-moving allocators.
+Low fragmentation: Experience with C, besides Google's TCMalloc and Hoard,
+I was intimately involved with Intel's Scalable Malloc and that work gave
+us confidence that fragmentation was not going to be a problem with non-moving allocators.
-Internal structures: We fully understood and had experience with them. We understood how to do size segregated spans, we understood how to do low or zero contention allocation paths.
+Internal structures: We fully understood and had experience with them.
+We understood how to do size segregated spans,
+we understood how to do low or zero contention allocation paths.
-Speed: Non-copy did not concern us, allocation admittedly might be slower but still in the order of C. It might not be as fast as bump pointer but that was OK.
+Speed: Non-copy did not concern us, allocation admittedly might be slower
+but still in the order of C.
+It might not be as fast as bump pointer but that was OK.
-We also had this foreign function interface issue. If we didn't move our objects then we didn't have to deal with the long tail of bugs you might encounter if you had a moving collector as you attempt to pin objects and put levels of indirection between C and the Go object you are working with.
+We also had this foreign function interface issue.
+If we didn't move our objects then we didn't have to deal with the long
+tail of bugs you might encounter if you had a moving collector as you attempt
+to pin objects and put levels of indirection between C and the Go object
+you are working with.
.image ismmkeynote/image5.png
-The next design choice was where to put the object's metadata. We needed to have some information about the objects since we didn't have headers. Mark bits are kept on the side and used for marking as well as allocation. Each word has 2 bits associated with it to tell you if it was a scalar or a pointer inside that word. It also encoded whether there were more pointers in the object so we could stop scanning objects sooner than later. We also had an extra bit encoding that we could use as an extra mark bit or to do other debugging things. This was really valuable for getting this stuff running and finding bugs.
+The next design choice was where to put the object's metadata.
+We needed to have some information about the objects since we didn't have headers.
+Mark bits are kept on the side and used for marking as well as allocation.
+Each word has 2 bits associated with it to tell you if it was a scalar or
+a pointer inside that word.
+It also encoded whether there were more pointers in the object so we could
+stop scanning objects sooner than later.
+We also had an extra bit encoding that we could use as an extra mark bit
+or to do other debugging things.
+This was really valuable for getting this stuff running and finding bugs.
.image ismmkeynote/image19.png
-So what about write barriers? The write barrier is on only during the GC. At other times the compiled code loads a global variable and looks at it. Since the GC was typically off the hardware correctly speculates to branch around the write barrier. When we are inside the GC that variable is different, and the write barrier is responsible for ensuring that no reachable objects get lost during the tri-color operations.
+So what about write barriers? The write barrier is on only during the GC.
+At other times the compiled code loads a global variable and looks at it.
+Since the GC was typically off the hardware correctly speculates to branch
+around the write barrier.
+When we are inside the GC that variable is different,
+and the write barrier is responsible for ensuring that no reachable objects
+get lost during the tri-color operations.
.image ismmkeynote/image50.png
-The other piece of this code is the GC Pacer. It is some of the great work that Austin did. It is basically based on a feedback loop that determines when to best start a GC cycle. If the system is in a steady state and not in a phase change, marking will end just about the time memory runs out.
+The other piece of this code is the GC Pacer.
+It is some of the great work that Austin did.
+It is basically based on a feedback loop that determines when to best start a GC cycle.
+If the system is in a steady state and not in a phase change,
+marking will end just about the time memory runs out.
-That might not be the case so the Pacer also has to monitor the marking progress and ensure allocation doesn't overrun the concurrent marking.
+That might not be the case so the Pacer also has to monitor the marking
+progress and ensure allocation doesn't overrun the concurrent marking.
-If need be, the Pacer slows down allocation while speeding up marking. At a high level the Pacer stops the Goroutine, which is doing a lot of the allocation, and puts it to work doing marking. The amount of work is proportional to the Goroutine's allocation. This speeds up the garbage collector while slowing down the mutator.
+If need be, the Pacer slows down allocation while speeding up marking.
+At a high level the Pacer stops the Goroutine,
+which is doing a lot of the allocation, and puts it to work doing marking.
+The amount of work is proportional to the Goroutine's allocation.
+This speeds up the garbage collector while slowing down the mutator.
-When all of this is done the Pacer takes what it has learnt from this GC cycle as well as previous ones and projects when to start the next GC.
+When all of this is done the Pacer takes what it has learnt from this GC
+cycle as well as previous ones and projects when to start the next GC.
It does much more than this but that is the basic approach.
-The math is absolutely fascinating, ping me for the design docs. If you are doing a concurrent GC you really owe it to yourself to look at this math and see if it's the same as your math. If you have any suggestions let us know.
+The math is absolutely fascinating, ping me for the design docs.
+If you are doing a concurrent GC you really owe it to yourself to look at
+this math and see if it's the same as your math.
+If you have any suggestions let us know.
-[[https://golang.org/s/go15gcpacing][*Go 1.5 concurrent garbage collector pacing]] and [[https://github.com/golang/proposal/blob/master/design/14951-soft-heap-limit.md][Proposal: Separate soft and hard heap size goal]]
+[[https://golang.org/s/go15gcpacing][*Go 1.5 concurrent garbage collector pacing]]
+and [[https://github.com/golang/proposal/blob/master/design/14951-soft-heap-limit.md][Proposal: Separate soft and hard heap size goal]]
.image ismmkeynote/image40.png
-Yes, so we had successes, lots of them. A younger crazier Rick would have taken some of these graphs and tattooed them on my shoulder I was so proud of them.
+Yes, so we had successes, lots of them. A younger crazier Rick would have
+taken some of these graphs and tattooed them on my shoulder I was so proud of them.
.image ismmkeynote/image20.png
-This is a series of graphs that was done for a production server at Twitter. We of course had nothing to do with that production server. Brian Hatfield did these measurements and oddly enough tweeted about them.
+This is a series of graphs that was done for a production server at Twitter.
+We of course had nothing to do with that production server.
+Brian Hatfield did these measurements and oddly enough tweeted about them.
-On the Y axis we have GC latency in milliseconds. On the X axis we have time. Each of the points is a stop the world pause time during that GC.
+On the Y axis we have GC latency in milliseconds.
+On the X axis we have time. Each of the points is a stop the world pause
+time during that GC.
-On our first release, which was in August of 2015, we saw a drop from around 300 - 400 milliseconds down to 30 or 40 milliseconds. This was good, order of magnitude good.
+On our first release, which was in August of 2015,
+we saw a drop from around 300 - 400 milliseconds down to 30 or 40 milliseconds.
+This was good, order of magnitude good.
We are going to change the Y-axis here radically from 0 to 400 milliseconds down to 0 to 50 milliseconds.
.image ismmkeynote/image54.png
-This is 6 months later. The improvement was largely due to systematically eliminating all the O(heap) things we were doing during the stop the world time. This was our second order of magnitude improvement as we went from 40 milliseconds down to 4 or 5.
+This is 6 months later. The improvement was largely due to systematically
+eliminating all the O(heap) things we were doing during the stop the world time.
+This was our second order of magnitude improvement as we went from 40 milliseconds down to 4 or 5.
.image ismmkeynote/image1.png
-There were some bugs in there that we had to clean up and we did this during a minor release 1.6.3. This dropped latency down to well under 10 milliseconds, which was our SLO.
+There were some bugs in there that we had to clean up and we did this during
+a minor release 1.6.3.
+This dropped latency down to well under 10 milliseconds, which was our SLO.
We are about to change our Y-axis again, this time down to 0 to 5 milliseconds.
.image ismmkeynote/image68.png
-So here we are, this is August of 2016, a year after the first release. Again we kept knocking off these O(heap size) stop the world processes. We are talking about an 18Gbyte heap here. We had much larger heaps and as we knocked off these O(heap size) stop the world pauses, the size of the heap could obviously grow considerable without impacting latency. So this was a bit of a help in 1.7.
+So here we are, this is August of 2016, a year after the first release.
+Again we kept knocking off these O(heap size) stop the world processes.
+We are talking about an 18Gbyte heap here.
+We had much larger heaps and as we knocked off these O(heap size) stop the world pauses,
+the size of the heap could obviously grow considerable without impacting latency.
+So this was a bit of a help in 1.7.
.image ismmkeynote/image58.png
-The next release was in March of 2017. We had the last of our large latency drops which was due to figuring out how to avoid the stop the world stack scanning at the end of the GC cycle. That dropped us into the sub-millisecond range. Again the Y axis is about to change to 1.5 milliseconds and we see our third order of magnitude improvement.
+The next release was in March of 2017. We had the last of our large latency
+drops which was due to figuring out how to avoid the stop the world stack
+scanning at the end of the GC cycle.
+That dropped us into the sub-millisecond range.
+Again the Y axis is about to change to 1.5 milliseconds and we see our third
+order of magnitude improvement.
.image ismmkeynote/image45.png
-The August 2017 release saw little improvement. We know what is causing the remaining pauses. The SLO whisper number here is around 100-200 microseconds and we will push towards that. If you see anything over a couple hundred microseconds then we really want to talk to you and figure out whether it fits into the stuff we know about or whether it is something new we haven't looked into. In any case there seems to be little call for lower latency. It is important to note these latency levels can happen for a wide variety of non-GC reasons and as the saying goes "You don't have to be faster than the bear, you just have to be faster than the guy next to you."
+The August 2017 release saw little improvement.
+We know what is causing the remaining pauses.
+The SLO whisper number here is around 100-200 microseconds and we will push towards that.
+If you see anything over a couple hundred microseconds then we really want
+to talk to you and figure out whether it fits into the stuff we know about
+or whether it is something new we haven't looked into.
+In any case there seems to be little call for lower latency.
+It is important to note these latency levels can happen for a wide variety
+of non-GC reasons and as the saying goes "You don't have to be faster than the bear,
+you just have to be faster than the guy next to you."
There was no substantial change in the Feb'18 1.10 release just some clean-up and chasing corner cases.
@@ -227,11 +404,14 @@
The Pacer had gotten much better so we looked to see minimal GC assists in a steady state.
-We were pretty happy with this. Again this is not an SLA but an SLO so it's an objective, not an agreement, since we can't control such things as the OS.
+We were pretty happy with this. Again this is not an SLA but an SLO so it's an objective,
+not an agreement, since we can't control such things as the OS.
.image ismmkeynote/image64.png
-That's the good stuff. Let's shift and start talking about our failures. These are our scars; they are sort of like tattoos and everyone gets them. Anyway they come with better stories so let's do some of those stories.
+That's the good stuff. Let's shift and start talking about our failures.
+These are our scars; they are sort of like tattoos and everyone gets them.
+Anyway they come with better stories so let's do some of those stories.
.image ismmkeynote/image46.png
@@ -241,11 +421,17 @@
So what does this mean?
-Goroutines are lightweight threads that look like Gophers, so here we have two Goroutines. They share some stuff such as the two blue objects there in the middle. They have their own private stacks and their own selection of private objects. Say the guy on the left wants to share the green object.
+Goroutines are lightweight threads that look like Gophers,
+so here we have two Goroutines.
+They share some stuff such as the two blue objects there in the middle.
+They have their own private stacks and their own selection of private objects.
+Say the guy on the left wants to share the green object.
.image ismmkeynote/image9.png
-The goroutine puts it in the shared area so the other Goroutine can access it. They can hook it to something in the shared heap or assign it to a global variable and the other Goroutine can see it.
+The goroutine puts it in the shared area so the other Goroutine can access it.
+They can hook it to something in the shared heap or assign it to a global
+variable and the other Goroutine can see it.
.image ismmkeynote/image26.png
@@ -253,51 +439,95 @@
.image ismmkeynote/image14.png
-As you know you can't take your objects with you when you die. You can't take your stack either. The stack is actually empty at this time and the objects are unreachable so you can simply reclaim them.
+As you know you can't take your objects with you when you die.
+You can't take your stack either. The stack is actually empty at this time
+and the objects are unreachable so you can simply reclaim them.
.image ismmkeynote/image2.png
-The important thing here is that all actions were local and did not require any global synchronization. This is fundamentally different than approaches like a generational GC, and the hope was that the scaling we would get from not having to do that synchronization would be sufficient for us to have a win.
+The important thing here is that all actions were local and did not require
+any global synchronization.
+This is fundamentally different than approaches like a generational GC,
+and the hope was that the scaling we would get from not having to do that
+synchronization would be sufficient for us to have a win.
.image ismmkeynote/image27.png
-The other issue that was going on with this system was that the write barrier was always on. Whenever there was a write, we would have to see if it was writing a pointer to a private object into a public object. If so, we would have to make the referent object public and then do a transitive walk of reachable objects making sure they were also public. That was a pretty expensive write barrier that could cause many cache misses.
+The other issue that was going on with this system was that the write barrier was always on.
+Whenever there was a write, we would have to see if it was writing a pointer
+to a private object into a public object.
+If so, we would have to make the referent object public and then do a transitive
+walk of reachable objects making sure they were also public.
+That was a pretty expensive write barrier that could cause many cache misses.
.image ismmkeynote/image30.png
That said, wow, we had some pretty good successes.
-This is an end-to-end RPC benchmark. The mislabeled Y axis goes from 0 to 5 milliseconds (lower is better), anyway that is just what it is. The X axis is basically the ballast or how big the in-core database is.
+This is an end-to-end RPC benchmark. The mislabeled Y axis goes from 0 to
+5 milliseconds (lower is better),
+anyway that is just what it is.
+The X axis is basically the ballast or how big the in-core database is.
-As you can see if you have ROC on and not a lot of sharing, things actually scale quite nicely. If you don't have ROC on it wasn't nearly as good.
+As you can see if you have ROC on and not a lot of sharing,
+things actually scale quite nicely.
+If you don't have ROC on it wasn't nearly as good.
.image ismmkeynote/image35.png
-But that wasn't good enough, we also had to make sure that ROC didn't slow down other pieces of the system. At that point there was a lot of concern about our compiler and we could not slow down our compilers. Unfortunately the compilers were exactly the programs that ROC did not do well at. We were seeing 30, 40, 50% and more slowdowns and that was unacceptable. Go is proud of how fast its compiler is so we couldn't slow the compiler down, certainly not this much.
+But that wasn't good enough, we also had to make sure that ROC didn't slow
+down other pieces of the system.
+At that point there was a lot of concern about our compiler and we could
+not slow down our compilers.
+Unfortunately the compilers were exactly the programs that ROC did not do well at.
+We were seeing 30, 40, 50% and more slowdowns and that was unacceptable.
+Go is proud of how fast its compiler is so we couldn't slow the compiler down,
+certainly not this much.
.image ismmkeynote/image61.png
-We then went and looked at some other programs. These are our performance benchmarks. We have a corpus of 200 or 300 benchmarks and these were the ones the compiler folks had decided were important for them to work on and improve. These weren't selected by the GC folks at all. The numbers were uniformly bad and ROC wasn't going to become a winner.
+We then went and looked at some other programs.
+These are our performance benchmarks. We have a corpus of 200 or 300 benchmarks
+and these were the ones the compiler folks had decided were important for
+them to work on and improve.
+These weren't selected by the GC folks at all.
+The numbers were uniformly bad and ROC wasn't going to become a winner.
.image ismmkeynote/image44.png
-It's true we scaled but we only had 4 to 12 hardware thread system so we couldn't overcome the write barrier tax. Perhaps in the future when we have 128 core systems and Go is taking advantage of them, the scaling properties of ROC might be a win. When that happens we might come back and revisit this, but for now ROC was a losing proposition.
+It's true we scaled but we only had 4 to 12 hardware thread system so we
+couldn't overcome the write barrier tax.
+Perhaps in the future when we have 128 core systems and Go is taking advantage of them,
+the scaling properties of ROC might be a win.
+When that happens we might come back and revisit this,
+but for now ROC was a losing proposition.
.image ismmkeynote/image66.png
-So what were we going to do next? Let's try the generational GC. It's an oldie but a goodie. ROC didn't work so let's go back to stuff we have a lot more experience with.
+So what were we going to do next? Let's try the generational GC.
+It's an oldie but a goodie. ROC didn't work so let's go back to stuff we
+have a lot more experience with.
.image ismmkeynote/image41.png
-We weren't going to give up our latency, we weren't going to give up the fact that we were non-moving. So we needed a non-moving generational GC.
+We weren't going to give up our latency, we weren't going to give up the
+fact that we were non-moving.
+So we needed a non-moving generational GC.
.image ismmkeynote/image27.png
-So could we do this? Yes, but with a generational GC, the write barrier is always on. When the GC cycle is running we use the same write barrier we use today, but when GC is off we use a fast GC write barrier that buffers the pointers and then flushes the buffer to a card mark table when it overflows.
+So could we do this? Yes, but with a generational GC,
+the write barrier is always on.
+When the GC cycle is running we use the same write barrier we use today,
+but when GC is off we use a fast GC write barrier that buffers the pointers
+and then flushes the buffer to a card mark table when it overflows.
.image ismmkeynote/image4.png
-So how is this going to work in a non-moving situation? Here is the mark / allocation map. Basically you maintain a current pointer. When you are allocating you look for the next zero and when you find that zero you allocate an object in that space.
+So how is this going to work in a non-moving situation? Here is the mark / allocation map.
+Basically you maintain a current pointer.
+When you are allocating you look for the next zero and when you find that
+zero you allocate an object in that space.
.image ismmkeynote/image51.png
@@ -305,11 +535,15 @@
.image ismmkeynote/image17.png
-You continue until at some point it is time to do a generation GC. You will notice that if there is a one in the mark/allocation vector then that object was alive at the last GC so it is mature. If it is zero and you reach it then you know it is young.
+You continue until at some point it is time to do a generation GC.
+You will notice that if there is a one in the mark/allocation vector then
+that object was alive at the last GC so it is mature.
+If it is zero and you reach it then you know it is young.
.image ismmkeynote/image53.png
-So how do you do promoting. If you find something marked with a 1 pointing to something marked with a 0 then you promote the referent simply by setting that zero to a one.
+So how do you do promoting. If you find something marked with a 1 pointing
+to something marked with a 0 then you promote the referent simply by setting that zero to a one.
.image ismmkeynote/image49.png
You have to do a transitive walk to make sure all reachable objects are promoted.
@@ -320,11 +554,16 @@
.image ismmkeynote/image62.png
-Finally, to finish your generational GC cycle you simply set the current pointer back to the start of the vector and you can continue. All the zeros weren't reached during that GC cycle so are free and can be reused. As many of you know this is called 'sticky bits' and was invented by Hans Boehm and his colleagues.
+Finally, to finish your generational GC cycle you simply set the current
+pointer back to the start of the vector and you can continue.
+All the zeros weren't reached during that GC cycle so are free and can be reused.
+As many of you know this is called 'sticky bits' and was invented by Hans
+Boehm and his colleagues.
.image ismmkeynote/image21.png
-So what did the performance look like? It wasn't bad for the large heaps. These were the benchmarks that the GC should do well on. This was all good.
+So what did the performance look like? It wasn't bad for the large heaps.
+These were the benchmarks that the GC should do well on. This was all good.
.image ismmkeynote/image65.png
@@ -332,53 +571,119 @@
.image ismmkeynote/image43.png
-The write barrier was fast but it simply wasn't fast enough. Furthermore it was hard to optimize for. For example, write barrier elision can happen if there is an initializing write between when the object was allocated and the next safepoint. But we were having to move to a system where we have a GC safepoint at every instruction so there really wasn't any write barrier that we could elide going forward.
+The write barrier was fast but it simply wasn't fast enough.
+Furthermore it was hard to optimize for. For example,
+write barrier elision can happen if there is an initializing write between
+when the object was allocated and the next safepoint.
+But we were having to move to a system where we have a GC safepoint at every
+instruction so there really wasn't any write barrier that we could elide going forward.
.image ismmkeynote/image47.png
-We also had escape analysis and it was getting better and better. Remember the value-oriented stuff we were talking about? Instead of passing a pointer to a function we would pass the actual value. Because we were passing a value, escape analysis would only have to do intraprocedural escape analysis and not interprocedural analysis.
+We also had escape analysis and it was getting better and better.
+Remember the value-oriented stuff we were talking about? Instead of passing
+a pointer to a function we would pass the actual value.
+Because we were passing a value, escape analysis would only have to do intraprocedural
+escape analysis and not interprocedural analysis.
Of course in the case where a pointer to the local object escapes, the object would be heap allocated.
-It isn't that the generational hypothesis isn't true for Go, it's just that the young objects live and die young on the stack. The result is that generational collection is much less effective than you might find in other managed runtime languages.
+It isn't that the generational hypothesis isn't true for Go,
+it's just that the young objects live and die young on the stack.
+The result is that generational collection is much less effective than you
+might find in other managed runtime languages.
.image ismmkeynote/image10.png
-So these forces against the write barrier were starting to gather. Today, our compiler is much better than it was in 2014. Escape analysis is picking up a lot of those objects and sticking them on the stack-objects that the generational collector would have helped with. We started creating tools to help our users find objects that escaped and if it was minor they could make changes to the code and help the compiler allocate on the stack.
+So these forces against the write barrier were starting to gather.
+Today, our compiler is much better than it was in 2014.
+Escape analysis is picking up a lot of those objects and sticking them on
+the stack-objects that the generational collector would have helped with.
+We started creating tools to help our users find objects that escaped and
+if it was minor they could make changes to the code and help the compiler
+allocate on the stack.
-Users are getting more clever about embracing value-oriented approaches and the number of pointers is being reduced. Arrays and maps hold values and not pointers to structs. Everything is good.
+Users are getting more clever about embracing value-oriented approaches
+and the number of pointers is being reduced.
+Arrays and maps hold values and not pointers to structs. Everything is good.
But that's not the main compelling reason why write barriers in Go have an uphill fight going forward.
.image ismmkeynote/image8.png
-Let's look at this graph. It's just an analytical graph of mark costs. Each line represents a different application that might have a mark cost. Say your mark cost is 20%, which is pretty high but it's possible. The red line is 10%, which is still high. The lower line is 5% which is about what a write barrier costs these days. So what happens if you double the heap size? That's the point on the right. The cumulative cost of the mark phase drops considerably since GC cycles are less frequent. The write barrier costs are constant so the cost of increasing the heap size will drive that marking cost underneath the cost of the write barrier.
+Let's look at this graph. It's just an analytical graph of mark costs.
+Each line represents a different application that might have a mark cost.
+Say your mark cost is 20%, which is pretty high but it's possible.
+The red line is 10%, which is still high.
+The lower line is 5% which is about what a write barrier costs these days.
+So what happens if you double the heap size? That's the point on the right.
+The cumulative cost of the mark phase drops considerably since GC cycles are less frequent.
+The write barrier costs are constant so the cost of increasing the heap
+size will drive that marking cost underneath the cost of the write barrier.
.image ismmkeynote/image39.png
-Here is a more common cost for a write barrier, which is 4%, and we see that even with that we can drive the cost of the mark barrier down below the cost of the write barrier by simply increasing the heap size.
+Here is a more common cost for a write barrier,
+which is 4%, and we see that even with that we can drive the cost of the
+mark barrier down below the cost of the write barrier by simply increasing the heap size.
-The real value of generational GC is that, when looking at GC times, the write barrier costs are ignored since they are smeared across the mutator. This is generational GC's great advantage, it greatly reduces the long STW times of full GC cycles but it doesn't necessarily improve throughput. Go doesn't have this stop the world problem so it had to look more closely at the throughput problems and that is what we did.
+The real value of generational GC is that,
+when looking at GC times, the write barrier costs are ignored since they
+are smeared across the mutator.
+This is generational GC's great advantage,
+it greatly reduces the long STW times of full GC cycles but it doesn't necessarily improve throughput.
+Go doesn't have this stop the world problem so it had to look more closely
+at the throughput problems and that is what we did.
.image ismmkeynote/image23.png
-That's a lot of failure and with such failure comes food and lunch. I'm doing my usual whining "Gee wouldn't this be great if it wasn't for the write barrier."
+That's a lot of failure and with such failure comes food and lunch.
+I'm doing my usual whining "Gee wouldn't this be great if it wasn't for the write barrier."
-Meanwhile Austin has just spent an hour talking to some of the HW GC folks at Google and he was saying we should talk to them and try and figure out how to get HW GC support that might help. Then I started telling war stories about zero-fill cache lines, restartable atomic sequences, and other things that didn't fly when I was working for a large hardware company. Sure we got some stuff into a chip called the Itanium, but we couldn't get them into the more popular chips of today. So the moral of the story is simply to use the HW we have.
+Meanwhile Austin has just spent an hour talking to some of the HW GC folks
+at Google and he was saying we should talk to them and try and figure out
+how to get HW GC support that might help.
+Then I started telling war stories about zero-fill cache lines,
+restartable atomic sequences, and other things that didn't fly when I was
+working for a large hardware company.
+Sure we got some stuff into a chip called the Itanium,
+but we couldn't get them into the more popular chips of today.
+So the moral of the story is simply to use the HW we have.
Anyway that got us talking, what about something crazy?
.image ismmkeynote/image25.png
-What about card marking without a write barrier? It turns out that Austin has these files and he writes into these files all of his crazy ideas that for some reason he doesn't tell me about. I figure it is some sort of therapeutic thing. I used to do the same thing with Eliot. New ideas are easily smashed and one needs to protect them and make them stronger before you let them out into the world. Well anyway he pulls this idea out.
+What about card marking without a write barrier? It turns out that Austin
+has these files and he writes into these files all of his crazy ideas that
+for some reason he doesn't tell me about.
+I figure it is some sort of therapeutic thing.
+I used to do the same thing with Eliot. New ideas are easily smashed and
+one needs to protect them and make them stronger before you let them out into the world.
+Well anyway he pulls this idea out.
-The idea is that you maintain a hash of mature pointers in each card. If pointers are written into a card, the hash will change and the card will be considered marked. This would trade the cost of write barrier off for cost of hashing.
+The idea is that you maintain a hash of mature pointers in each card.
+If pointers are written into a card, the hash will change and the card will
+be considered marked.
+This would trade the cost of write barrier off for cost of hashing.
.image ismmkeynote/image31.png
But more importantly it's hardware aligned.
-Today's modern architectures have AES (Advanced Encryption Standard) instructions. One of those instructions can do encryption-grade hashing and with encryption-grade hashing we don't have to worry about collisions if we also follow standard encryption policies. So hashing is not going to cost us much but we have to load up what we are going to hash. Fortunately we are walking through memory sequentially so we get really good memory and cache performance. If you have a DIMM and you hit sequential addresses, then it's a win because they will be faster than hitting random addresses. The hardware prefetchers will kick in and that will also help. Anyway we have 50 years, 60 years of designing hardware to run Fortran, to run C, and to run the SPECint benchmarks. It's no surprise that the result is hardware that runs this kind of stuff fast.
+Today's modern architectures have AES (Advanced Encryption Standard) instructions.
+One of those instructions can do encryption-grade hashing and with encryption-grade
+hashing we don't have to worry about collisions if we also follow standard
+encryption policies.
+So hashing is not going to cost us much but we have to load up what we are going to hash.
+Fortunately we are walking through memory sequentially so we get really
+good memory and cache performance.
+If you have a DIMM and you hit sequential addresses,
+then it's a win because they will be faster than hitting random addresses.
+The hardware prefetchers will kick in and that will also help.
+Anyway we have 50 years, 60 years of designing hardware to run Fortran,
+to run C, and to run the SPECint benchmarks.
+It's no surprise that the result is hardware that runs this kind of stuff fast.
.image ismmkeynote/image12.png
@@ -386,7 +691,18 @@
.image ismmkeynote/image18.png
-We then said what does it look like for the performance benchmark? Not so good, a couple of outliers. But now we have moved the write barrier from always being on in the mutator to running as part of the GC cycle. Now making a decision about whether we are going to do a generational GC is delayed until the start of the GC cycle. We have more control there since we have localized the card work. Now that we have the tools we can turn it over to the Pacer, and it could do a good job of dynamically cutting off programs that fall to the right and do not benefit from generational GC. But is this going to win going forward? We have to know or at least think about what hardware is going to look like going forward.
+We then said what does it look like for the performance benchmark? Not so good,
+a couple of outliers.
+But now we have moved the write barrier from always being on in the mutator
+to running as part of the GC cycle.
+Now making a decision about whether we are going to do a generational GC
+is delayed until the start of the GC cycle.
+We have more control there since we have localized the card work.
+Now that we have the tools we can turn it over to the Pacer,
+and it could do a good job of dynamically cutting off programs that fall
+to the right and do not benefit from generational GC.
+But is this going to win going forward? We have to know or at least think
+about what hardware is going to look like going forward.
.image ismmkeynote/image52.png
@@ -394,40 +710,87 @@
.image ismmkeynote/image11.png
-Let's take a look at this graph. This is your classic Moore's law graph. You have a log scale on the Y axis showing the number of transistors in a single chip. The X-axis is the years between 1971 and 2016. I will note that these are the years when someone somewhere predicted that Moore's law was dead.
+Let's take a look at this graph. This is your classic Moore's law graph.
+You have a log scale on the Y axis showing the number of transistors in a single chip.
+The X-axis is the years between 1971 and 2016.
+I will note that these are the years when someone somewhere predicted that
+Moore's law was dead.
-Dennard scaling had ended frequency improvements ten years or so ago. New processes are taking longer to ramp. So instead of 2 years they are now 4 years or more. So it's pretty clear that we are entering an era of the slowing of Moore's law.
+Dennard scaling had ended frequency improvements ten years or so ago.
+New processes are taking longer to ramp. So instead of 2 years they are
+now 4 years or more.
+So it's pretty clear that we are entering an era of the slowing of Moore's law.
Let's just look at the chips in the red circle. These are the chips that are the best at sustaining Moore's law.
-They are chips where the logic is increasingly simple and duplicated many times. Lots of identical cores, multiple memory controllers and caches, GPUs, TPUs, and so forth.
+They are chips where the logic is increasingly simple and duplicated many times.
+Lots of identical cores, multiple memory controllers and caches,
+GPUs, TPUs, and so forth.
-As we continue to simplify and increase duplication we asymptotically end up with a couple of wires, a transistor, and a capacitor. In other words a DRAM memory cell.
+As we continue to simplify and increase duplication we asymptotically end
+up with a couple of wires,
+a transistor, and a capacitor.
+In other words a DRAM memory cell.
Put another way, we think that doubling memory is going to be a better value than doubling cores.
-[[http://www.kurzweilai.net/ask-ray-the-future-of-moores-law][Original graph]] at www.kurzweilai.net/ask-ray-the-future-of-moores-law.
+[[http://www.kurzweilai.net/ask-ray-the-future-of-moores-law][Original graph]]
+at www.kurzweilai.net/ask-ray-the-future-of-moores-law.
.image ismmkeynote/image57.png
-Let's look at another graph focused on DRAM. These are numbers from a recent PhD thesis from CMU. If we look at this we see that Moore's law is the blue line. The red line is capacity and it seems to be following Moore's law. Oddly enough I saw a graph that goes all the way back to 1939 when we were using drum memory and that capacity and Moore's law were chugging along together so this graph has been going on for a long time, certainly longer than probably anybody in this room has been alive.
+Let's look at another graph focused on DRAM.
+These are numbers from a recent PhD thesis from CMU.
+If we look at this we see that Moore's law is the blue line.
+The red line is capacity and it seems to be following Moore's law.
+Oddly enough I saw a graph that goes all the way back to 1939 when we were
+using drum memory and that capacity and Moore's law were chugging along
+together so this graph has been going on for a long time,
+certainly longer than probably anybody in this room has been alive.
-If we compare this graph to CPU frequency or the various Moore's-law-is-dead graphs, we are led to the conclusion that memory, or at least chip capacity, will follow Moore's law longer than CPUs. Bandwidth, the yellow line, is related not only to the frequency of the memory but also to the number of pins one can get off of the chip so it's not keeping up as well but it's not doing badly.
+If we compare this graph to CPU frequency or the various Moore's-law-is-dead graphs,
+we are led to the conclusion that memory,
+or at least chip capacity, will follow Moore's law longer than CPUs.
+Bandwidth, the yellow line, is related not only to the frequency of the
+memory but also to the number of pins one can get off of the chip so it's
+not keeping up as well but it's not doing badly.
-Latency, the green line, is doing very poorly, though I will note that latency for sequential accesses does better than latency for random access.
+Latency, the green line, is doing very poorly,
+though I will note that latency for sequential accesses does better than
+latency for random access.
-(Data from "Understanding and Improving the Latency of DRAM-Based Memory Systems Submitted in partial fulfillment of the requirements for the degree of Doctor of Philosophy in Electrical and Computer Engineering Kevin K. Chang M.S., Electrical & Computer Engineering, Carnegie Mellon University B.S., Electrical & Computer Engineering, Carnegie Mellon University Carnegie Mellon University Pittsburgh, PA May, 2017". See [[http://repository.cmu.edu/cgi/viewcontent.cgi?article%3D1946%26context%3Ddissertations&sa=D&ust=1531164842660000][Kevin K. Chang's thesis.]] The original graph in the introduction was not in a form that I could draw a Moore's law line on it easily so I changed the X-axis to be more uniform.)
+(Data from "Understanding and Improving the Latency of DRAM-Based Memory
+Systems Submitted in partial fulfillment of the requirements for the degree
+of Doctor of Philosophy in Electrical and Computer Engineering Kevin K.
+Chang M.S., Electrical & Computer Engineering,
+Carnegie Mellon University B.S., Electrical & Computer Engineering,
+Carnegie Mellon University Carnegie Mellon University Pittsburgh, PA May, 2017".
+See [[http://repository.cmu.edu/cgi/viewcontent.cgi?article%3D1946%26context%3Ddissertations&sa=D&ust=1531164842660000][Kevin K. Chang's thesis.]]
+The original graph in the introduction was not in a form that I could draw
+a Moore's law line on it easily so I changed the X-axis to be more uniform.)
.image ismmkeynote/image15.png
-Let's go to where the rubber meets the road. This is actual DRAM pricing and it has generally declined from 2005 to 2016. I chose 2005 since that is around the time when Dennard scaling ended and along with it frequency improvements.
+Let's go to where the rubber meets the road.
+This is actual DRAM pricing and it has generally declined from 2005 to 2016.
+I chose 2005 since that is around the time when Dennard scaling ended and
+along with it frequency improvements.
-If you look at the red circle, which is basically the time our work to reduce Go's GC latency has been going on, we see that for the first couple of years prices did well. Lately, not so good, as demand has exceeded supply leading to price increases over the last two years. Of course, transistors haven't gotten bigger and in some cases chip capacity has increased so this is driven by market forces. RAMBUS and other chip manufacturers say that moving forward we will see our next process shrink in the 2019-2020 time frame.
+If you look at the red circle, which is basically the time our work to reduce
+Go's GC latency has been going on,
+we see that for the first couple of years prices did well.
+Lately, not so good, as demand has exceeded supply leading to price increases
+over the last two years.
+Of course, transistors haven't gotten bigger and in some cases chip capacity
+has increased so this is driven by market forces.
+RAMBUS and other chip manufacturers say that moving forward we will see
+our next process shrink in the 2019-2020 time frame.
-I will refrain from speculating on global market forces in the memory industry beyond noting that pricing is cyclic and in the long term supply has a tendency to meet demand.
+I will refrain from speculating on global market forces in the memory industry
+beyond noting that pricing is cyclic and in the long term supply has a tendency to meet demand.
Long term, it is our belief that memory pricing will drop at a rate that is much faster than CPU pricing.
@@ -435,11 +798,20 @@
.image ismmkeynote/image37.png
-Let's look at this other line. Gee it would be nice if we were on this line. This is the SSD line. It is doing a better job of keeping prices low. The material physics of these chips is much more complicated that with DRAM. The logic is more complex, instead of a one transistor per cell there are half a dozen or so.
+Let's look at this other line. Gee it would be nice if we were on this line.
+This is the SSD line. It is doing a better job of keeping prices low.
+The material physics of these chips is much more complicated that with DRAM.
+The logic is more complex, instead of a one transistor per cell there are half a dozen or so.
-Going forward there is a line between DRAM and SSD where NVRAM such as Intel's 3D XPoint and Phase Change Memory (PCM) will live. Over the next decade increased availability of this type of memory is likely to become more mainstream and this will only reinforce the idea that adding memory is the cheap way to add value to our servers.
+Going forward there is a line between DRAM and SSD where NVRAM such as Intel's
+3D XPoint and Phase Change Memory (PCM) will live.
+Over the next decade increased availability of this type of memory is likely
+to become more mainstream and this will only reinforce the idea that adding
+memory is the cheap way to add value to our servers.
-More importantly we can expect to see other competing alternatives to DRAM. I won't pretend to know which one will be favored in five or ten years but the competition will be fierce and heap memory will move closer to the highlighted blue SSD line here.
+More importantly we can expect to see other competing alternatives to DRAM.
+I won't pretend to know which one will be favored in five or ten years but
+the competition will be fierce and heap memory will move closer to the highlighted blue SSD line here.
All of this reinforces our decision to avoid always-on barriers in favor of increasing memory.
@@ -449,15 +821,25 @@
.image ismmkeynote/image42.png
-We intend to make the runtime more flexible and robust as we look at corner cases that come in from our users. The hope is to tighten the scheduler down and get better determinism and fairness but we don't want to sacrifice any of our performance.
+We intend to make the runtime more flexible and robust as we look at corner
+cases that come in from our users.
+The hope is to tighten the scheduler down and get better determinism and
+fairness but we don't want to sacrifice any of our performance.
-We also do not intend to increase the GC API surface. We've had almost a decade now and we have two knobs and that feels about right. There is not an application that is important enough for us to add a new flag.
+We also do not intend to increase the GC API surface.
+We've had almost a decade now and we have two knobs and that feels about right.
+There is not an application that is important enough for us to add a new flag.
-We will also be looking into how to improve our already pretty good escape analysis and optimize for Go's value-oriented programming. Not only in the programming but in the tools we provide our users.
+We will also be looking into how to improve our already pretty good escape
+analysis and optimize for Go's value-oriented programming.
+Not only in the programming but in the tools we provide our users.
-Algorithmically, we will focus on parts of the design space that minimize the use of barriers, particularly those that are turned on all the time.
+Algorithmically, we will focus on parts of the design space that minimize
+the use of barriers,
+particularly those that are turned on all the time.
-Finally, and most importantly, we hope to ride Moore's law's tendency to favor RAM over CPU certainly for the next 5 years and hopefully for the next decade.
+Finally, and most importantly, we hope to ride Moore's law's tendency to
+favor RAM over CPU certainly for the next 5 years and hopefully for the next decade.
So that's it. Thank you.
diff --git a/content/json-and-go.article b/content/json-and-go.article
index 95ab377..8e4dfcd 100644
--- a/content/json-and-go.article
+++ b/content/json-and-go.article
@@ -6,9 +6,16 @@
* Introduction
-JSON (JavaScript Object Notation) is a simple data interchange format. Syntactically it resembles the objects and lists of JavaScript. It is most commonly used for communication between web back-ends and JavaScript programs running in the browser, but it is used in many other places, too. Its home page, [[http://json.org][json.org]], provides a wonderfully clear and concise definition of the standard.
+JSON (JavaScript Object Notation) is a simple data interchange format.
+Syntactically it resembles the objects and lists of JavaScript.
+It is most commonly used for communication between web back-ends and JavaScript
+programs running in the browser,
+but it is used in many other places, too.
+Its home page, [[http://json.org][json.org]],
+provides a wonderfully clear and concise definition of the standard.
-With the [[https://golang.org/pkg/encoding/json/][json package]] it's a snap to read and write JSON data from your Go programs.
+With the [[https://golang.org/pkg/encoding/json/][json package]] it's a
+snap to read and write JSON data from your Go programs.
* Encoding
@@ -38,7 +45,9 @@
Only data structures that can be represented as valid JSON will be encoded:
-- JSON objects only support strings as keys; to encode a Go map type it must be of the form `map[string]T` (where `T` is any Go type supported by the json package).
+- JSON objects only support strings as keys;
+ to encode a Go map type it must be of the form `map[string]T` (where `T`
+ is any Go type supported by the json package).
- Channel, complex, and function types cannot be encoded.
@@ -46,7 +55,9 @@
- Pointers will be encoded as the values they point to (or 'null' if the pointer is `nil`).
-The json package only accesses the exported fields of struct types (those that begin with an uppercase letter). Therefore only the the exported fields of a struct will be present in the JSON output.
+The json package only accesses the exported fields of struct types (those
+that begin with an uppercase letter).
+Therefore only the the exported fields of a struct will be present in the JSON output.
* Decoding
@@ -62,7 +73,10 @@
err := json.Unmarshal(b, &m)
-If `b` contains valid JSON that fits in `m`, after the call `err` will be `nil` and the data from `b` will have been stored in the struct `m`, as if by an assignment like:
+If `b` contains valid JSON that fits in `m`,
+after the call `err` will be `nil` and the data from `b` will have been
+stored in the struct `m`,
+as if by an assignment like:
m = Message{
Name: "Alice",
@@ -70,9 +84,13 @@
Time: 1294706395881547000,
}
-How does `Unmarshal` identify the fields in which to store the decoded data? For a given JSON key `"Foo"`, `Unmarshal` will look through the destination struct's fields to find (in order of preference):
+How does `Unmarshal` identify the fields in which to store the decoded data?
+For a given JSON key `"Foo"`,
+`Unmarshal` will look through the destination struct's fields to find (in
+order of preference):
-- An exported field with a tag of `"Foo"` (see the [[https://golang.org/ref/spec#Struct_types][Go spec]] for more on struct tags),
+- An exported field with a tag of `"Foo"` (see the [[https://golang.org/ref/spec#Struct_types][Go spec]]
+ for more on struct tags),
- An exported field named `"Foo"`, or
@@ -84,13 +102,20 @@
var m Message
err := json.Unmarshal(b, &m)
-`Unmarshal` will decode only the fields that it can find in the destination type. In this case, only the Name field of m will be populated, and the Food field will be ignored. This behavior is particularly useful when you wish to pick only a few specific fields out of a large JSON blob. It also means that any unexported fields in the destination struct will be unaffected by `Unmarshal`.
+`Unmarshal` will decode only the fields that it can find in the destination type.
+In this case, only the Name field of m will be populated,
+and the Food field will be ignored.
+This behavior is particularly useful when you wish to pick only a few specific
+fields out of a large JSON blob.
+It also means that any unexported fields in the destination struct will
+be unaffected by `Unmarshal`.
But what if you don't know the structure of your JSON data beforehand?
* Generic JSON with interface{}
-The `interface{}` (empty interface) type describes an interface with zero methods. Every Go type implements at least zero methods and therefore satisfies the empty interface.
+The `interface{}` (empty interface) type describes an interface with zero methods.
+Every Go type implements at least zero methods and therefore satisfies the empty interface.
The empty interface serves as a general container type:
@@ -142,7 +167,8 @@
var f interface{}
err := json.Unmarshal(b, &f)
-At this point the Go value in `f` would be a map whose keys are strings and whose values are themselves stored as empty interface values:
+At this point the Go value in `f` would be a map whose keys are strings
+and whose values are themselves stored as empty interface values:
f = map[string]interface{}{
"Name": "Wednesday",
@@ -157,7 +183,8 @@
m := f.(map[string]interface{})
-We can then iterate through the map with a range statement and use a type switch to access its values as their concrete types:
+We can then iterate through the map with a range statement and use a type
+switch to access its values as their concrete types:
for k, v := range m {
switch vv := v.(type) {
@@ -190,7 +217,14 @@
var m FamilyMember
err := json.Unmarshal(b, &m)
-Unmarshaling that data into a `FamilyMember` value works as expected, but if we look closely we can see a remarkable thing has happened. With the var statement we allocated a `FamilyMember` struct, and then provided a pointer to that value to `Unmarshal`, but at that time the `Parents` field was a `nil` slice value. To populate the `Parents` field, `Unmarshal` allocated a new slice behind the scenes. This is typical of how `Unmarshal` works with the supported reference types (pointers, slices, and maps).
+Unmarshaling that data into a `FamilyMember` value works as expected,
+but if we look closely we can see a remarkable thing has happened.
+With the var statement we allocated a `FamilyMember` struct,
+and then provided a pointer to that value to `Unmarshal`,
+but at that time the `Parents` field was a `nil` slice value.
+To populate the `Parents` field, `Unmarshal` allocated a new slice behind the scenes.
+This is typical of how `Unmarshal` works with the supported reference types
+(pointers, slices, and maps).
Consider unmarshaling into this data structure:
@@ -198,25 +232,40 @@
Bar *Bar
}
-If there were a `Bar` field in the JSON object, `Unmarshal` would allocate a new `Bar` and populate it. If not, `Bar` would be left as a `nil` pointer.
+If there were a `Bar` field in the JSON object,
+`Unmarshal` would allocate a new `Bar` and populate it.
+If not, `Bar` would be left as a `nil` pointer.
-From this a useful pattern arises: if you have an application that receives a few distinct message types, you might define "receiver" structure like
+From this a useful pattern arises: if you have an application that receives
+a few distinct message types,
+you might define "receiver" structure like
type IncomingMessage struct {
Cmd *Command
Msg *Message
}
-and the sending party can populate the `Cmd` field and/or the `Msg` field of the top-level JSON object, depending on the type of message they want to communicate. `Unmarshal`, when decoding the JSON into an `IncomingMessage` struct, will only allocate the data structures present in the JSON data. To know which messages to process, the programmer need simply test that either `Cmd` or `Msg` is not `nil`.
+and the sending party can populate the `Cmd` field and/or the `Msg` field
+of the top-level JSON object,
+depending on the type of message they want to communicate.
+`Unmarshal`, when decoding the JSON into an `IncomingMessage` struct,
+will only allocate the data structures present in the JSON data.
+To know which messages to process, the programmer need simply test that
+either `Cmd` or `Msg` is not `nil`.
* Streaming Encoders and Decoders
-The json package provides `Decoder` and `Encoder` types to support the common operation of reading and writing streams of JSON data. The `NewDecoder` and `NewEncoder` functions wrap the [[https://golang.org/pkg/io/#Reader][`io.Reader`]] and [[https://golang.org/pkg/io/#Writer][`io.Writer`]] interface types.
+The json package provides `Decoder` and `Encoder` types to support the common
+operation of reading and writing streams of JSON data.
+The `NewDecoder` and `NewEncoder` functions wrap the [[https://golang.org/pkg/io/#Reader][`io.Reader`]]
+and [[https://golang.org/pkg/io/#Writer][`io.Writer`]] interface types.
func NewDecoder(r io.Reader) *Decoder
func NewEncoder(w io.Writer) *Encoder
-Here's an example program that reads a series of JSON objects from standard input, removes all but the `Name` field from each object, and then writes the objects to standard output:
+Here's an example program that reads a series of JSON objects from standard input,
+removes all but the `Name` field from each object,
+and then writes the objects to standard output:
package main
@@ -246,8 +295,12 @@
}
}
-Due to the ubiquity of Readers and Writers, these `Encoder` and `Decoder` types can be used in a broad range of scenarios, such as reading and writing to HTTP connections, WebSockets, or files.
+Due to the ubiquity of Readers and Writers,
+these `Encoder` and `Decoder` types can be used in a broad range of scenarios,
+such as reading and writing to HTTP connections,
+WebSockets, or files.
* References
-For more information see the [[https://golang.org/pkg/encoding/json/][json package documentation]]. For an example usage of json see the source files of the [[https://golang.org/pkg/net/rpc/jsonrpc/][jsonrpc package]].
+For more information see the [[https://golang.org/pkg/encoding/json/][json package documentation]].
+For an example usage of json see the source files of the [[https://golang.org/pkg/net/rpc/jsonrpc/][jsonrpc package]].
diff --git a/content/json-rpc-tale-of-interfaces.article b/content/json-rpc-tale-of-interfaces.article
index 2bc3c28..3ccabc7 100644
--- a/content/json-rpc-tale-of-interfaces.article
+++ b/content/json-rpc-tale-of-interfaces.article
@@ -6,9 +6,16 @@
* Introduction
-Here we present an example where Go's [[https://golang.org/doc/effective_go.html#interfaces_and_types][interfaces]] made it easy to refactor some existing code to make it more flexible and extensible. Originally, the standard library's [[https://golang.org/pkg/net/rpc/][RPC package]] used a custom wire format called [[https://golang.org/pkg/encoding/gob/][gob]]. For a particular application, we wanted to use [[https://golang.org/pkg/encoding/json/][JSON]] as an alternate wire format.
+Here we present an example where Go's [[https://golang.org/doc/effective_go.html#interfaces_and_types][interfaces]]
+made it easy to refactor some existing code to make it more flexible and extensible.
+Originally, the standard library's [[https://golang.org/pkg/net/rpc/][RPC package]]
+used a custom wire format called [[https://golang.org/pkg/encoding/gob/][gob]].
+For a particular application, we wanted to use [[https://golang.org/pkg/encoding/json/][JSON]]
+as an alternate wire format.
-We first defined a pair of interfaces to describe the functionality of the existing wire format, one for the client, and one for the server (depicted below).
+We first defined a pair of interfaces to describe the functionality of the
+existing wire format,
+one for the client, and one for the server (depicted below).
type ServerCodec interface {
ReadRequestHeader(*Request) error
@@ -17,7 +24,8 @@
Close() error
}
-On the server side, we then changed two internal function signatures to accept the `ServerCodec` interface instead of our existing `gob.Encoder`. Here's one of them:
+On the server side, we then changed two internal function signatures to
+accept the `ServerCodec` interface instead of our existing `gob.Encoder`. Here's one of them:
func sendResponse(sending *sync.Mutex, req *Request,
reply interface{}, enc *gob.Encoder, errmsg string)
@@ -27,10 +35,26 @@
func sendResponse(sending *sync.Mutex, req *Request,
reply interface{}, enc ServerCodec, errmsg string)
-We then wrote a trivial `gobServerCodec` wrapper to reproduce the original functionality. From there it is simple to build a `jsonServerCodec`.
+We then wrote a trivial `gobServerCodec` wrapper to reproduce the original functionality.
+From there it is simple to build a `jsonServerCodec`.
-After some similar changes to the client side, this was the full extent of the work we needed to do on the RPC package. This whole exercise took about 20 minutes! After tidying up and testing the new code, the [[https://github.com/golang/go/commit/dcff89057bc0e0d7cb14cf414f2df6f5fb1a41ec][final changeset]] was submitted.
+After some similar changes to the client side,
+this was the full extent of the work we needed to do on the RPC package.
+This whole exercise took about 20 minutes!
+After tidying up and testing the new code,
+the [[https://github.com/golang/go/commit/dcff89057bc0e0d7cb14cf414f2df6f5fb1a41ec][final changeset]] was submitted.
-In an inheritance-oriented language like Java or C++, the obvious path would be to generalize the RPC class, and create JsonRPC and GobRPC subclasses. However, this approach becomes tricky if you want to make a further generalization orthogonal to that hierarchy. (For example, if you were to implement an alternate RPC standard). In our Go package, we took a route that is both conceptually simpler and requires less code be written or changed.
+In an inheritance-oriented language like Java or C++,
+the obvious path would be to generalize the RPC class,
+and create JsonRPC and GobRPC subclasses.
+However, this approach becomes tricky if you want to make a further generalization
+orthogonal to that hierarchy.
+(For example, if you were to implement an alternate RPC standard).
+In our Go package, we took a route that is both conceptually simpler and
+requires less code be written or changed.
-A vital quality for any codebase is maintainability. As needs change, it is essential to adapt your code easily and cleanly, lest it become unwieldy to work with. We believe Go's lightweight, composition-oriented type system provides a means of structuring code that scales.
+A vital quality for any codebase is maintainability.
+As needs change, it is essential to adapt your code easily and cleanly,
+lest it become unwieldy to work with.
+We believe Go's lightweight, composition-oriented type system provides a
+means of structuring code that scales.
diff --git a/content/laws-of-reflection.article b/content/laws-of-reflection.article
index 103ae73..10cd663 100644
--- a/content/laws-of-reflection.article
+++ b/content/laws-of-reflection.article
@@ -6,24 +6,40 @@
* Introduction
-Reflection in computing is the ability of a program to examine its own structure, particularly through types; it's a form of metaprogramming. It's also a great source of confusion.
+Reflection in computing is the ability of a program to examine its own structure,
+particularly through types;
+it's a form of metaprogramming.
+It's also a great source of confusion.
-In this article we attempt to clarify things by explaining how reflection works in Go. Each language's reflection model is different (and many languages don't support it at all), but this article is about Go, so for the rest of this article the word "reflection" should be taken to mean "reflection in Go".
+In this article we attempt to clarify things by explaining how reflection works in Go.
+Each language's reflection model is different (and many languages don't support it at all),
+but this article is about Go, so for the rest of this article the word "reflection"
+should be taken to mean "reflection in Go".
* Types and interfaces
Because reflection builds on the type system, let's start with a refresher about types in Go.
-Go is statically typed. Every variable has a static type, that is, exactly one type known and fixed at compile time: `int`, `float32`, `*MyType`, `[]byte`, and so on. If we declare
+Go is statically typed. Every variable has a static type,
+that is, exactly one type known and fixed at compile time:
+`int`, `float32`, `*MyType`, `[]byte`, and so on. If we declare
type MyInt int
var i int
var j MyInt
-then `i` has type `int` and `j` has type `MyInt`. The variables `i` and `j` have distinct static types and, although they have the same underlying type, they cannot be assigned to one another without a conversion.
+then `i` has type `int` and `j` has type `MyInt`.
+The variables `i` and `j` have distinct static types and,
+although they have the same underlying type,
+they cannot be assigned to one another without a conversion.
-One important category of type is interface types, which represent fixed sets of methods. An interface variable can store any concrete (non-interface) value as long as that value implements the interface's methods. A well-known pair of examples is `io.Reader` and `io.Writer`, the types `Reader` and `Writer` from the [[https://golang.org/pkg/io/][io package]]:
+One important category of type is interface types,
+which represent fixed sets of methods.
+An interface variable can store any concrete (non-interface) value as long
+as that value implements the interface's methods.
+A well-known pair of examples is `io.Reader` and `io.Writer`,
+the types `Reader` and `Writer` from the [[https://golang.org/pkg/io/][io package]]:
// Reader is the interface that wraps the basic Read method.
type Reader interface {
@@ -35,7 +51,10 @@
Write(p []byte) (n int, err error)
}
-Any type that implements a `Read` (or `Write`) method with this signature is said to implement `io.Reader` (or `io.Writer`). For the purposes of this discussion, that means that a variable of type `io.Reader` can hold any value whose type has a `Read` method:
+Any type that implements a `Read` (or `Write`) method with this signature
+is said to implement `io.Reader` (or `io.Writer`).
+For the purposes of this discussion, that means that a variable of type
+`io.Reader` can hold any value whose type has a `Read` method:
var r io.Reader
r = os.Stdin
@@ -43,7 +62,9 @@
r = new(bytes.Buffer)
// and so on
-It's important to be clear that whatever concrete value `r` may hold, `r`'s type is always `io.Reader`: Go is statically typed and the static type of `r` is `io.Reader`.
+It's important to be clear that whatever concrete value `r` may hold,
+`r`'s type is always `io.Reader`:
+Go is statically typed and the static type of `r` is `io.Reader`.
An extremely important example of an interface type is the empty interface:
@@ -51,15 +72,26 @@
It represents the empty set of methods and is satisfied by any value at all, since any value has zero or more methods.
-Some people say that Go's interfaces are dynamically typed, but that is misleading. They are statically typed: a variable of interface type always has the same static type, and even though at run time the value stored in the interface variable may change type, that value will always satisfy the interface.
+Some people say that Go's interfaces are dynamically typed,
+but that is misleading.
+They are statically typed: a variable of interface type always has the same static type,
+and even though at run time the value stored in the interface variable may change type,
+that value will always satisfy the interface.
We need to be precise about all this because reflection and interfaces are closely related.
* The representation of an interface
-Russ Cox has written a [[https://research.swtch.com/2009/12/go-data-structures-interfaces.html][ detailed blog post]] about the representation of interface values in Go. It's not necessary to repeat the full story here, but a simplified summary is in order.
+Russ Cox has written a [[https://research.swtch.com/2009/12/go-data-structures-interfaces.html][ detailed blog post]]
+about the representation of interface values in Go.
+It's not necessary to repeat the full story here,
+but a simplified summary is in order.
-A variable of interface type stores a pair: the concrete value assigned to the variable, and that value's type descriptor. To be more precise, the value is the underlying concrete data item that implements the interface and the type describes the full type of that item. For instance, after
+A variable of interface type stores a pair:
+the concrete value assigned to the variable,
+and that value's type descriptor.
+To be more precise, the value is the underlying concrete data item that
+implements the interface and the type describes the full type of that item. For instance, after
var r io.Reader
tty, err := os.OpenFile("/dev/tty", os.O_RDWR, 0)
@@ -68,23 +100,43 @@
}
r = tty
-`r` contains, schematically, the (value, type) pair, (`tty`, `*os.File`). Notice that the type `*os.File` implements methods other than `Read`; even though the interface value provides access only to the `Read` method, the value inside carries all the type information about that value. That's why we can do things like this:
+`r` contains, schematically, the (value, type) pair,
+(`tty`, `*os.File`).
+Notice that the type `*os.File` implements methods other than `Read`;
+even though the interface value provides access only to the `Read` method,
+the value inside carries all the type information about that value.
+That's why we can do things like this:
var w io.Writer
w = r.(io.Writer)
-The expression in this assignment is a type assertion; what it asserts is that the item inside `r` also implements `io.Writer`, and so we can assign it to `w`. After the assignment, `w` will contain the pair (`tty`, `*os.File`). That's the same pair as was held in `r`. The static type of the interface determines what methods may be invoked with an interface variable, even though the concrete value inside may have a larger set of methods.
+The expression in this assignment is a type assertion;
+what it asserts is that the item inside `r` also implements `io.Writer`,
+and so we can assign it to `w`.
+After the assignment, `w` will contain the pair (`tty`, `*os.File`).
+That's the same pair as was held in `r`. The static type of the interface
+determines what methods may be invoked with an interface variable,
+even though the concrete value inside may have a larger set of methods.
Continuing, we can do this:
var empty interface{}
empty = w
-and our empty interface value `empty` will again contain that same pair, (`tty`, `*os.File`). That's handy: an empty interface can hold any value and contains all the information we could ever need about that value.
+and our empty interface value `empty` will again contain that same pair,
+(`tty`, `*os.File`).
+That's handy: an empty interface can hold any value and contains all the
+information we could ever need about that value.
-(We don't need a type assertion here because it's known statically that `w` satisfies the empty interface. In the example where we moved a value from a `Reader` to a `Writer`, we needed to be explicit and use a type assertion because `Writer`'s methods are not a subset of `Reader`'s.)
+(We don't need a type assertion here because it's known statically that
+`w` satisfies the empty interface.
+In the example where we moved a value from a `Reader` to a `Writer`,
+we needed to be explicit and use a type assertion because `Writer`'s methods
+are not a subset of `Reader`'s.)
-One important detail is that the pair inside an interface always has the form (value, concrete type) and cannot have the form (value, interface type). Interfaces do not hold interface values.
+One important detail is that the pair inside an interface always has the form (value,
+concrete type) and cannot have the form (value, interface type).
+Interfaces do not hold interface values.
Now we're ready to reflect.
@@ -92,7 +144,15 @@
* 1. Reflection goes from interface value to reflection object.
-At the basic level, reflection is just a mechanism to examine the type and value pair stored inside an interface variable. To get started, there are two types we need to know about in [[https://golang.org/pkg/reflect/][package reflect]]: [[https://golang.org/pkg/reflect/#Type][Type]] and [[https://golang.org/pkg/reflect/#Value][Value]]. Those two types give access to the contents of an interface variable, and two simple functions, called `reflect.TypeOf` and `reflect.ValueOf`, retrieve `reflect.Type` and `reflect.Value` pieces out of an interface value. (Also, from the `reflect.Value` it's easy to get to the `reflect.Type`, but let's keep the `Value` and `Type` concepts separate for now.)
+At the basic level, reflection is just a mechanism to examine the type and
+value pair stored inside an interface variable.
+To get started, there are two types we need to know about in [[https://golang.org/pkg/reflect/][package reflect]]:
+[[https://golang.org/pkg/reflect/#Type][Type]] and [[https://golang.org/pkg/reflect/#Value][Value]].
+Those two types give access to the contents of an interface variable,
+and two simple functions, called `reflect.TypeOf` and `reflect.ValueOf`,
+retrieve `reflect.Type` and `reflect.Value` pieces out of an interface value.
+(Also, from the `reflect.Value` it's easy to get to the `reflect.Type`,
+but let's keep the `Value` and `Type` concepts separate for now.)
Let's start with `TypeOf`:
@@ -112,14 +172,22 @@
type: float64
-You might be wondering where the interface is here, since the program looks like it's passing the `float64` variable `x`, not an interface value, to `reflect.TypeOf`. But it's there; as [[https://golang.org/pkg/reflect/#TypeOf][godoc reports]], the signature of `reflect.TypeOf` includes an empty interface:
+You might be wondering where the interface is here,
+since the program looks like it's passing the `float64` variable `x`,
+not an interface value, to `reflect.TypeOf`.
+But it's there; as [[https://golang.org/pkg/reflect/#TypeOf][godoc reports]],
+the signature of `reflect.TypeOf` includes an empty interface:
// TypeOf returns the reflection Type of the value in the interface{}.
func TypeOf(i interface{}) Type
-When we call `reflect.TypeOf(x)`, `x` is first stored in an empty interface, which is then passed as the argument; `reflect.TypeOf` unpacks that empty interface to recover the type information.
+When we call `reflect.TypeOf(x)`, `x` is first stored in an empty interface,
+which is then passed as the argument;
+`reflect.TypeOf` unpacks that empty interface to recover the type information.
-The `reflect.ValueOf` function, of course, recovers the value (from here on we'll elide the boilerplate and focus just on the executable code):
+The `reflect.ValueOf` function, of course,
+recovers the value (from here on we'll elide the boilerplate and focus just
+on the executable code):
var x float64 = 3.4
fmt.Println("value:", reflect.ValueOf(x).String())
@@ -128,10 +196,19 @@
value: <float64 Value>
-(We call the `String` method explicitly because by default the `fmt` package digs into a `reflect.Value` to show the concrete value inside.
+(We call the `String` method explicitly because by default the `fmt` package
+digs into a `reflect.Value` to show the concrete value inside.
The `String` method does not.)
-Both `reflect.Type` and `reflect.Value` have lots of methods to let us examine and manipulate them. One important example is that `Value` has a `Type` method that returns the `Type` of a `reflect.Value`. Another is that both `Type` and `Value` have a `Kind` method that returns a constant indicating what sort of item is stored: `Uint`, `Float64`, `Slice`, and so on. Also methods on `Value` with names like `Int` and `Float` let us grab values (as `int64` and `float64`) stored inside:
+Both `reflect.Type` and `reflect.Value` have lots of methods to let us examine
+and manipulate them.
+One important example is that `Value` has a `Type` method that returns the
+`Type` of a `reflect.Value`.
+Another is that both `Type` and `Value` have a `Kind` method that returns
+a constant indicating what sort of item is stored:
+`Uint`, `Float64`, `Slice`, and so on.
+Also methods on `Value` with names like `Int` and `Float` let us grab values
+(as `int64` and `float64`) stored inside:
var x float64 = 3.4
v := reflect.ValueOf(x)
@@ -145,9 +222,17 @@
kind is float64: true
value: 3.4
-There are also methods like `SetInt` and `SetFloat` but to use them we need to understand settability, the subject of the third law of reflection, discussed below.
+There are also methods like `SetInt` and `SetFloat` but to use them we need
+to understand settability,
+the subject of the third law of reflection, discussed below.
-The reflection library has a couple of properties worth singling out. First, to keep the API simple, the "getter" and "setter" methods of `Value` operate on the largest type that can hold the value: `int64` for all the signed integers, for instance. That is, the `Int` method of `Value` returns an `int64` and the `SetInt` value takes an `int64`; it may be necessary to convert to the actual type involved:
+The reflection library has a couple of properties worth singling out.
+First, to keep the API simple, the "getter" and "setter" methods of `Value`
+operate on the largest type that can hold the value:
+`int64` for all the signed integers, for instance.
+That is, the `Int` method of `Value` returns an `int64` and the `SetInt`
+value takes an `int64`;
+it may be necessary to convert to the actual type involved:
var x uint8 = 'x'
v := reflect.ValueOf(x)
@@ -155,13 +240,19 @@
fmt.Println("kind is uint8: ", v.Kind() == reflect.Uint8) // true.
x = uint8(v.Uint()) // v.Uint returns a uint64.
-The second property is that the `Kind` of a reflection object describes the underlying type, not the static type. If a reflection object contains a value of a user-defined integer type, as in
+The second property is that the `Kind` of a reflection object describes
+the underlying type,
+not the static type.
+If a reflection object contains a value of a user-defined integer type, as in
type MyInt int
var x MyInt = 7
v := reflect.ValueOf(x)
-the `Kind` of `v` is still `reflect.Int`, even though the static type of `x` is `MyInt`, not `int`. In other words, the `Kind` cannot discriminate an int from a `MyInt` even though the `Type` can.
+the `Kind` of `v` is still `reflect.Int`,
+even though the static type of `x` is `MyInt`, not `int`.
+In other words, the `Kind` cannot discriminate an int from a `MyInt` even
+though the `Type` can.
* The second law of reflection
@@ -169,7 +260,9 @@
Like physical reflection, reflection in Go generates its own inverse.
-Given a `reflect.Value` we can recover an interface value using the `Interface` method; in effect the method packs the type and value information back into an interface representation and returns the result:
+Given a `reflect.Value` we can recover an interface value using the `Interface` method;
+in effect the method packs the type and value information back into an interface
+representation and returns the result:
// Interface returns v's value as an interface{}.
func (v Value) Interface() interface{}
@@ -181,11 +274,18 @@
to print the `float64` value represented by the reflection object `v`.
-We can do even better, though. The arguments to `fmt.Println`, `fmt.Printf` and so on are all passed as empty interface values, which are then unpacked by the `fmt` package internally just as we have been doing in the previous examples. Therefore all it takes to print the contents of a `reflect.Value` correctly is to pass the result of the `Interface` method to the formatted print routine:
+We can do even better, though. The arguments to `fmt.Println`,
+`fmt.Printf` and so on are all passed as empty interface values,
+which are then unpacked by the `fmt` package internally just as we have
+been doing in the previous examples.
+Therefore all it takes to print the contents of a `reflect.Value` correctly
+is to pass the result of the `Interface` method to the formatted print routine:
fmt.Println(v.Interface())
-(Why not `fmt.Println(v)`? Because `v` is a `reflect.Value`; we want the concrete value it holds.) Since our value is a `float64`, we can even use a floating-point format if we want:
+(Why not `fmt.Println(v)`? Because `v` is a `reflect.Value`;
+we want the concrete value it holds.) Since our value is a `float64`,
+we can even use a floating-point format if we want:
fmt.Printf("value is %7.1e\n", v.Interface())
@@ -193,9 +293,12 @@
3.4e+00
-Again, there's no need to type-assert the result of `v.Interface()` to `float64`; the empty interface value has the concrete value's type information inside and `Printf` will recover it.
+Again, there's no need to type-assert the result of `v.Interface()` to `float64`;
+the empty interface value has the concrete value's type information inside
+and `Printf` will recover it.
-In short, the `Interface` method is the inverse of the `ValueOf` function, except that its result is always of static type `interface{}`.
+In short, the `Interface` method is the inverse of the `ValueOf` function,
+except that its result is always of static type `interface{}`.
Reiterating: Reflection goes from interface values to reflection objects and back again.
@@ -215,7 +318,10 @@
panic: reflect.Value.SetFloat using unaddressable value
-The problem is not that the value `7.1` is not addressable; it's that `v` is not settable. Settability is a property of a reflection `Value`, and not all reflection `Values` have it.
+The problem is not that the value `7.1` is not addressable;
+it's that `v` is not settable.
+Settability is a property of a reflection `Value`,
+and not all reflection `Values` have it.
The `CanSet` method of `Value` reports the settability of a `Value`; in our case,
@@ -229,26 +335,43 @@
It is an error to call a `Set` method on an non-settable `Value`. But what is settability?
-Settability is a bit like addressability, but stricter. It's the property that a reflection object can modify the actual storage that was used to create the reflection object. Settability is determined by whether the reflection object holds the original item. When we say
+Settability is a bit like addressability, but stricter.
+It's the property that a reflection object can modify the actual storage
+that was used to create the reflection object.
+Settability is determined by whether the reflection object holds the original item. When we say
var x float64 = 3.4
v := reflect.ValueOf(x)
-we pass a copy of `x` to `reflect.ValueOf`, so the interface value created as the argument to `reflect.ValueOf` is a copy of `x`, not `x` itself. Thus, if the statement
+we pass a copy of `x` to `reflect.ValueOf`,
+so the interface value created as the argument to `reflect.ValueOf` is a
+copy of `x`, not `x` itself.
+Thus, if the statement
v.SetFloat(7.1)
-were allowed to succeed, it would not update `x`, even though `v` looks like it was created from `x`. Instead, it would update the copy of `x` stored inside the reflection value and `x` itself would be unaffected. That would be confusing and useless, so it is illegal, and settability is the property used to avoid this issue.
+were allowed to succeed, it would not update `x`,
+even though `v` looks like it was created from `x`.
+Instead, it would update the copy of `x` stored inside the reflection value
+and `x` itself would be unaffected.
+That would be confusing and useless, so it is illegal,
+and settability is the property used to avoid this issue.
-If this seems bizarre, it's not. It's actually a familiar situation in unusual garb. Think of passing `x` to a function:
+If this seems bizarre, it's not. It's actually a familiar situation in unusual garb.
+Think of passing `x` to a function:
f(x)
-We would not expect `f` to be able to modify `x` because we passed a copy of `x`'s value, not `x` itself. If we want `f` to modify `x` directly we must pass our function the address of `x` (that is, a pointer to `x`):
+We would not expect `f` to be able to modify `x` because we passed a copy
+of `x`'s value, not `x` itself.
+If we want `f` to modify `x` directly we must pass our function the address
+of `x` (that is, a pointer to `x`):
f(&x)
-This is straightforward and familiar, and reflection works the same way. If we want to modify `x` by reflection, we must give the reflection library a pointer to the value we want to modify.
+This is straightforward and familiar, and reflection works the same way.
+If we want to modify `x` by reflection, we must give the reflection library
+a pointer to the value we want to modify.
Let's do that. First we initialize `x` as usual and then create a reflection value that points to it, called `p`.
@@ -262,7 +385,10 @@
type of p: *float64
settability of p: false
-The reflection object `p` isn't settable, but it's not `p` we want to set, it's (in effect) `*p`. To get to what `p` points to, we call the `Elem` method of `Value`, which indirects through the pointer, and save the result in a reflection `Value` called `v`:
+The reflection object `p` isn't settable,
+but it's not `p` we want to set, it's (in effect) `*p`.
+To get to what `p` points to, we call the `Elem` method of `Value`,
+which indirects through the pointer, and save the result in a reflection `Value` called `v`:
v := p.Elem()
fmt.Println("settability of v:", v.CanSet())
@@ -282,13 +408,27 @@
7.1
7.1
-Reflection can be hard to understand but it's doing exactly what the language does, albeit through reflection `Types` and `Values` that can disguise what's going on. Just keep in mind that reflection Values need the address of something in order to modify what they represent.
+Reflection can be hard to understand but it's doing exactly what the language does,
+albeit through reflection `Types` and `Values` that can disguise what's going on.
+Just keep in mind that reflection Values need the address of something in
+order to modify what they represent.
* Structs
-In our previous example `v` wasn't a pointer itself, it was just derived from one. A common way for this situation to arise is when using reflection to modify the fields of a structure. As long as we have the address of the structure, we can modify its fields.
+In our previous example `v` wasn't a pointer itself,
+it was just derived from one.
+A common way for this situation to arise is when using reflection to modify
+the fields of a structure.
+As long as we have the address of the structure,
+we can modify its fields.
-Here's a simple example that analyzes a struct value, `t`. We create the reflection object with the address of the struct because we'll want to modify it later. Then we set `typeOfT` to its type and iterate over the fields using straightforward method calls (see [[https://golang.org/pkg/reflect/][package reflect]] for details). Note that we extract the names of the fields from the struct type, but the fields themselves are regular `reflect.Value` objects.
+Here's a simple example that analyzes a struct value, `t`.
+We create the reflection object with the address of the struct because we'll
+want to modify it later.
+Then we set `typeOfT` to its type and iterate over the fields using straightforward
+method calls (see [[https://golang.org/pkg/reflect/][package reflect]] for details).
+Note that we extract the names of the fields from the struct type,
+but the fields themselves are regular `reflect.Value` objects.
type T struct {
A int
@@ -308,7 +448,9 @@
0: A int = 23
1: B string = skidoo
-There's one more point about settability introduced in passing here: the field names of `T` are upper case (exported) because only exported fields of a struct are settable.
+There's one more point about settability introduced in passing here:
+the field names of `T` are upper case (exported) because only exported fields
+of a struct are settable.
Because `s` contains a settable reflection object, we can modify the fields of the structure.
@@ -320,7 +462,9 @@
t is now {77 Sunset Strip}
-If we modified the program so that `s` was created from `t`, not `&t`, the calls to `SetInt` and `SetString` would fail as the fields of `t` would not be settable.
+If we modified the program so that `s` was created from `t`,
+not `&t`, the calls to `SetInt` and `SetString` would fail as the fields
+of `t` would not be settable.
* Conclusion
@@ -332,6 +476,12 @@
- To modify a reflection object, the value must be settable.
-Once you understand these laws reflection in Go becomes much easier to use, although it remains subtle. It's a powerful tool that should be used with care and avoided unless strictly necessary.
+Once you understand these laws reflection in Go becomes much easier to use,
+although it remains subtle.
+It's a powerful tool that should be used with care and avoided unless strictly necessary.
-There's plenty more to reflection that we haven't covered — sending and receiving on channels, allocating memory, using slices and maps, calling methods and functions — but this post is long enough. We'll cover some of those topics in a later article.
+There's plenty more to reflection that we haven't covered — sending and
+receiving on channels,
+allocating memory, using slices and maps,
+calling methods and functions — but this post is long enough.
+We'll cover some of those topics in a later article.
diff --git a/content/learn-go-from-your-browser.article b/content/learn-go-from-your-browser.article
index a3cd470..8458c09 100644
--- a/content/learn-go-from-your-browser.article
+++ b/content/learn-go-from-your-browser.article
@@ -6,10 +6,16 @@
* Introduction
-We are excited to announce [[https://tour.golang.org/][A Tour of Go]], a guided tour of the Go programming language you can run from your browser.
+We are excited to announce [[https://tour.golang.org/][A Tour of Go]],
+a guided tour of the Go programming language you can run from your browser.
-The tour is hands-on, demonstrating the language through code samples that you can modify, compile, and run from the tour itself. (The technology behind the [[https://golang.org/doc/play/][Go Playground]] does the work.)
+The tour is hands-on, demonstrating the language through code samples that you can modify,
+compile, and run from the tour itself.
+(The technology behind the [[https://golang.org/doc/play/][Go Playground]] does the work.)
-The tour has three sections. The first section covers basic syntax and data structures; the second discusses methods and interfaces; and the third introduces Go's concurrency primitives. Each section concludes with a few exercises so you can practice what you've learned.
+The tour has three sections. The first section covers basic syntax and data structures;
+the second discusses methods and interfaces;
+and the third introduces Go's concurrency primitives.
+Each section concludes with a few exercises so you can practice what you've learned.
So, what are you waiting for? [[https://tour.golang.org/][Get started now!]]
diff --git a/content/migrating-to-go-modules.article b/content/migrating-to-go-modules.article
index 975e706..3e5fbc5 100644
--- a/content/migrating-to-go-modules.article
+++ b/content/migrating-to-go-modules.article
@@ -13,11 +13,22 @@
- Part 3 — [[/publishing-go-modules][Publishing Go Modules]]
- Part 4 — [[/v2-go-modules][Go Modules: v2 and Beyond]]
-Go projects use a wide variety of dependency management strategies. [[https://golang.org/cmd/go/#hdr-Vendor_Directories][Vendoring]] tools such as [[https://github.com/golang/dep][dep]] and [[https://github.com/Masterminds/glide][glide]] are popular, but they have wide differences in behavior and don't always work well together. Some projects store their entire GOPATH directory in a single Git repository. Others simply rely on `go`get` and expect fairly recent versions of dependencies to be installed in GOPATH.
+Go projects use a wide variety of dependency management strategies.
+[[https://golang.org/cmd/go/#hdr-Vendor_Directories][Vendoring]] tools such
+as [[https://github.com/golang/dep][dep]] and [[https://github.com/Masterminds/glide][glide]] are popular,
+but they have wide differences in behavior and don't always work well together.
+Some projects store their entire GOPATH directory in a single Git repository.
+Others simply rely on `go`get` and expect fairly recent versions of dependencies
+to be installed in GOPATH.
-Go's module system, introduced in Go 1.11, provides an official dependency management solution built into the `go` command. This article describes tools and techniques for converting a project to modules.
+Go's module system, introduced in Go 1.11,
+provides an official dependency management solution built into the `go` command.
+This article describes tools and techniques for converting a project to modules.
-Please note: if your project is already tagged at v2.0.0 or higher, you will need to update your module path when you add a `go.mod` file. We'll explain how to do that without breaking your users in a future article focused on v2 and beyond.
+Please note: if your project is already tagged at v2.0.0 or higher,
+you will need to update your module path when you add a `go.mod` file.
+We'll explain how to do that without breaking your users in a future article
+focused on v2 and beyond.
* Migrating to Go modules in your project
@@ -27,7 +38,8 @@
- An established Go project with a non-modules dependency manager.
- An established Go project without any dependency manager.
-The first case is covered in [[https://blog.golang.org/using-go-modules][Using Go Modules]]; we'll address the latter two in this post.
+The first case is covered in [[https://blog.golang.org/using-go-modules][Using Go Modules]];
+we'll address the latter two in this post.
* With a dependency manager
@@ -65,9 +77,15 @@
require rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca
$
-`go`mod`init` creates a new go.mod file and automatically imports dependencies from `Godeps.json`, `Gopkg.lock`, or a number of [[https://go.googlesource.com/go/+/362625209b6cd2bc059b6b0a67712ddebab312d9/src/cmd/go/internal/modconv/modconv.go#9][other supported formats]]. The argument to `go`mod`init` is the module path, the location where the module may be found.
+`go`mod`init` creates a new go.mod file and automatically imports dependencies from `Godeps.json`,
+`Gopkg.lock`, or a number of [[https://go.googlesource.com/go/+/362625209b6cd2bc059b6b0a67712ddebab312d9/src/cmd/go/internal/modconv/modconv.go#9][other supported formats]].
+The argument to `go`mod`init` is the module path,
+the location where the module may be found.
-This is a good time to pause and run `go`build`./...` and `go`test`./...` before continuing. Later steps may modify your `go.mod` file, so if you prefer to take an iterative approach, this is the closest your `go.mod` file will be to your pre-modules dependency specification.
+This is a good time to pause and run `go`build`./...` and `go`test`./...` before continuing.
+Later steps may modify your `go.mod` file,
+so if you prefer to take an iterative approach,
+this is the closest your `go.mod` file will be to your pre-modules dependency specification.
$ go mod tidy
go: downloading rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca
@@ -77,7 +95,14 @@
rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca/go.mod h1:qTv7/COck+e2FymRvadv62gMdZztPaShugOCi3I+8D8=
$
-`go`mod`tidy` finds all the packages transitively imported by packages in your module. It adds new module requirements for packages not provided by any known module, and it removes requirements on modules that don't provide any imported packages. If a module provides packages that are only imported by projects that haven't migrated to modules yet, the module requirement will be marked with an `//`indirect` comment. It is always good practice to run `go`mod`tidy` before committing a `go.mod` file to version control.
+`go`mod`tidy` finds all the packages transitively imported by packages in your module.
+It adds new module requirements for packages not provided by any known module,
+and it removes requirements on modules that don't provide any imported packages.
+If a module provides packages that are only imported by projects that haven't
+migrated to modules yet,
+the module requirement will be marked with an `//`indirect` comment.
+It is always good practice to run `go`mod`tidy` before committing a `go.mod`
+file to version control.
Let's finish by making sure the code builds and tests pass:
@@ -86,7 +111,14 @@
[...]
$
-Note that other dependency managers may specify dependencies at the level of individual packages or entire repositories (not modules), and generally do not recognize the requirements specified in the `go.mod` files of dependencies. Consequently, you may not get exactly the same version of every package as before, and there's some risk of upgrading past breaking changes. Therefore, it's important to follow the above commands with an audit of the resulting dependencies. To do so, run
+Note that other dependency managers may specify dependencies at the level
+of individual packages or entire repositories (not modules),
+and generally do not recognize the requirements specified in the `go.mod`
+files of dependencies.
+Consequently, you may not get exactly the same version of every package as before,
+and there's some risk of upgrading past breaking changes.
+Therefore, it's important to follow the above commands with an audit of
+the resulting dependencies. To do so, run
$ go list -m all
go: finding rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca
@@ -94,7 +126,13 @@
rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca
$
-and compare the resulting versions with your old dependency management file to ensure that the selected versions are appropriate. If you find a version that wasn't what you wanted, you can find out why using `go`mod`why`-m` and/or `go`mod`graph`, and upgrade or downgrade to the correct version using `go`get`. (If the version you request is older than the version that was previously selected, `go`get` will downgrade other dependencies as needed to maintain compatibility.) For example,
+and compare the resulting versions with your old dependency management file
+to ensure that the selected versions are appropriate.
+If you find a version that wasn't what you wanted,
+you can find out why using `go`mod`why`-m` and/or `go`mod`graph`,
+and upgrade or downgrade to the correct version using `go`get`.
+(If the version you request is older than the version that was previously selected,
+`go`get` will downgrade other dependencies as needed to maintain compatibility.) For example,
$ go mod why -m rsc.io/binaryregexp
[...]
@@ -118,9 +156,16 @@
go 1.12
$
-Without a configuration file from a previous dependency manager, `go`mod`init` will create a `go.mod` file with only the `module` and `go` directives. In this example, we set the module path to `golang.org/x/blog` because that is its [[https://golang.org/cmd/go/#hdr-Remote_import_paths][custom import path]]. Users may import packages with this path, and we must be careful not to change it.
+Without a configuration file from a previous dependency manager,
+`go`mod`init` will create a `go.mod` file with only the `module` and `go` directives.
+In this example, we set the module path to `golang.org/x/blog` because that
+is its [[https://golang.org/cmd/go/#hdr-Remote_import_paths][custom import path]].
+Users may import packages with this path,
+and we must be careful not to change it.
-The `module` directive declares the module path, and the `go` directive declares the expected version of the Go language used to compile the code within the module.
+The `module` directive declares the module path,
+and the `go` directive declares the expected version of the Go language
+used to compile the code within the module.
Next, run `go`mod`tidy` to add the module's dependencies:
@@ -161,7 +206,10 @@
[...]
$
-`go`mod`tidy` added module requirements for all the packages transitively imported by packages in your module and built a `go.sum` with checksums for each library at a specific version. Let's finish by making sure the code still builds and tests still pass:
+`go`mod`tidy` added module requirements for all the packages transitively
+imported by packages in your module and built a `go.sum` with checksums
+for each library at a specific version.
+Let's finish by making sure the code still builds and tests still pass:
$ go build ./...
$ go test ./...
@@ -174,21 +222,43 @@
? golang.org/x/blog/support/racy [no test files]
$
-Note that when `go`mod`tidy` adds a requirement, it adds the latest version of the module. If your `GOPATH` included an older version of a dependency that subsequently published a breaking change, you may see errors in `go`mod`tidy`, `go`build`, or `go`test`. If this happens, try downgrading to an older version with `go`get` (for example, `go`get`github.com/broken/module@v1.1.0`), or take the time to make your module compatible with the latest version of each dependency.
+Note that when `go`mod`tidy` adds a requirement,
+it adds the latest version of the module.
+If your `GOPATH` included an older version of a dependency that subsequently
+published a breaking change,
+you may see errors in `go`mod`tidy`, `go`build`, or `go`test`.
+If this happens, try downgrading to an older version with `go`get` (for example,
+`go`get`github.com/broken/module@v1.1.0`),
+or take the time to make your module compatible with the latest version of each dependency.
** Tests in module mode
Some tests may need tweaks after migrating to Go modules.
-If a test needs to write files in the package directory, it may fail when the package directory is in the module cache, which is read-only. In particular, this may cause `go`test`all` to fail. The test should copy files it needs to write to a temporary directory instead.
+If a test needs to write files in the package directory,
+it may fail when the package directory is in the module cache, which is read-only.
+In particular, this may cause `go`test`all` to fail.
+The test should copy files it needs to write to a temporary directory instead.
-If a test relies on relative paths (`../package-in-another-module`) to locate and read files in another package, it will fail if the package is in another module, which will be located in a versioned subdirectory of the module cache or a path specified in a `replace` directive. If this is the case, you may need to copy the test inputs into your module, or convert the test inputs from raw files to data embedded in `.go` source files.
+If a test relies on relative paths (`../package-in-another-module`) to locate
+and read files in another package,
+it will fail if the package is in another module,
+which will be located in a versioned subdirectory of the module cache or
+a path specified in a `replace` directive.
+If this is the case, you may need to copy the test inputs into your module,
+or convert the test inputs from raw files to data embedded in `.go` source files.
-If a test expects `go` commands within the test to run in GOPATH mode, it may fail. If this is the case, you may need to add a `go.mod` file to the source tree to be tested, or set `GO111MODULE=off` explicitly.
+If a test expects `go` commands within the test to run in GOPATH mode, it may fail.
+If this is the case, you may need to add a `go.mod` file to the source tree to be tested,
+or set `GO111MODULE=off` explicitly.
* Publishing a release
-Finally, you should tag and publish a release version for your new module. This is optional if you haven't released any versions yet, but without an official release, downstream users will depend on specific commits using [[https://golang.org/cmd/go/#hdr-Pseudo_versions][pseudo-versions]], which may be more difficult to support.
+Finally, you should tag and publish a release version for your new module.
+This is optional if you haven't released any versions yet,
+but without an official release, downstream users will depend on specific
+commits using [[https://golang.org/cmd/go/#hdr-Pseudo_versions][pseudo-versions]],
+which may be more difficult to support.
$ git tag v1.2.0
$ git push origin v1.2.0
@@ -204,16 +274,45 @@
* Imports and canonical module paths
-Each module declares its module path in its `go.mod` file. Each `import` statement that refers to a package within the module must have the module path as a prefix of the package path. However, the `go` command may encounter a repository containing the module through many different [[https://golang.org/cmd/go/#hdr-Remote_import_paths][remote import paths]]. For example, both `golang.org/x/lint` and `github.com/golang/lint` resolve to repositories containing the code hosted at [[https://go.googlesource.com/lint][go.googlesource.com/lint]]. The [[https://go.googlesource.com/lint/+/refs/heads/master/go.mod][`go.mod` file]] contained in that repository declares its path to be `golang.org/x/lint`, so only that path corresponds to a valid module.
+Each module declares its module path in its `go.mod` file.
+Each `import` statement that refers to a package within the module must
+have the module path as a prefix of the package path.
+However, the `go` command may encounter a repository containing the module
+through many different [[https://golang.org/cmd/go/#hdr-Remote_import_paths][remote import paths]].
+For example, both `golang.org/x/lint` and `github.com/golang/lint` resolve
+to repositories containing the code hosted at [[https://go.googlesource.com/lint][go.googlesource.com/lint]].
+The [[https://go.googlesource.com/lint/+/refs/heads/master/go.mod][`go.mod` file]]
+contained in that repository declares its path to be `golang.org/x/lint`,
+so only that path corresponds to a valid module.
-Go 1.4 provided a mechanism for declaring canonical import paths using [[https://golang.org/cmd/go/#hdr-Import_path_checking][`//`import` comments]], but package authors did not always provide them. As a result, code written prior to modules may have used a non-canonical import path for a module without surfacing an error for the mismatch. When using modules, the import path must match the canonical module path, so you may need to update `import` statements: for example, you may need to change `import`"github.com/golang/lint"` to `import`"golang.org/x/lint"`.
+Go 1.4 provided a mechanism for declaring canonical import paths using [[https://golang.org/cmd/go/#hdr-Import_path_checking][`//`import` comments]],
+but package authors did not always provide them.
+As a result, code written prior to modules may have used a non-canonical
+import path for a module without surfacing an error for the mismatch.
+When using modules, the import path must match the canonical module path,
+so you may need to update `import` statements:
+for example, you may need to change `import`"github.com/golang/lint"` to
+`import`"golang.org/x/lint"`.
-Another scenario in which a module's canonical path may differ from its repository path occurs for Go modules at major version 2 or higher. A Go module with a major version above 1 must include a major-version suffix in its module path: for example, version `v2.0.0` must have the suffix `/v2`. However, `import` statements may have referred to the packages within the module _without_ that suffix. For example, non-module users of `github.com/russross/blackfriday/v2` at `v2.0.1` may have imported it as `github.com/russross/blackfriday` instead, and will need to update the import path to include the `/v2` suffix.
+Another scenario in which a module's canonical path may differ from its
+repository path occurs for Go modules at major version 2 or higher.
+A Go module with a major version above 1 must include a major-version suffix in its module path:
+for example, version `v2.0.0` must have the suffix `/v2`.
+However, `import` statements may have referred to the packages within the
+module _without_ that suffix.
+For example, non-module users of `github.com/russross/blackfriday/v2` at
+`v2.0.1` may have imported it as `github.com/russross/blackfriday` instead,
+and will need to update the import path to include the `/v2` suffix.
* Conclusion
-Converting to Go modules should be a straightforward process for most users. Occasional issues may arise due to non-canonical import paths or breaking changes within a dependency. Future posts will explore [[/publishing-go-modules][publishing new versions]], v2 and beyond, and ways to debug strange situations.
+Converting to Go modules should be a straightforward process for most users.
+Occasional issues may arise due to non-canonical import paths or breaking
+changes within a dependency.
+Future posts will explore [[/publishing-go-modules][publishing new versions]],
+v2 and beyond, and ways to debug strange situations.
-To provide feedback and help shape the future of dependency management in Go, please send us [[https://golang.org/issue/new][bug reports]] or [[https://golang.org/wiki/ExperienceReports][experience reports]].
+To provide feedback and help shape the future of dependency management in Go,
+please send us [[https://golang.org/issue/new][bug reports]] or [[https://golang.org/wiki/ExperienceReports][experience reports]].
Thanks for all your feedback and help improving modules.
diff --git a/content/new-talk-and-tutorials.article b/content/new-talk-and-tutorials.article
index d7cbc4f..3b74ca2 100644
--- a/content/new-talk-and-tutorials.article
+++ b/content/new-talk-and-tutorials.article
@@ -5,8 +5,21 @@
* Introduction
-Rob Pike recently gave a talk at Stanford's [[http://www.stanford.edu/class/ee380/][Computer Systems Colloquium]] (EE380). Titled [[http://www.stanford.edu/class/ee380/Abstracts/100428.html][_Another_Go_at_Language_Design_]], the presentation gives an overview of the itches Go was built to scratch, and how Go addresses those problems. You can view [[https://www.youtube.com/watch?v=7VcArS4Wpqk][a video stream of the talk]], and [[http://www.stanford.edu/class/ee380/Abstracts/100428-pike-stanford.pdf][download the slides]].
+Rob Pike recently gave a talk at Stanford's [[http://www.stanford.edu/class/ee380/][Computer Systems Colloquium]] (EE380).
+Titled [[http://www.stanford.edu/class/ee380/Abstracts/100428.html][_Another_Go_at_Language_Design_]],
+the presentation gives an overview of the itches Go was built to scratch,
+and how Go addresses those problems.
+You can view [[https://www.youtube.com/watch?v=7VcArS4Wpqk][a video stream of the talk]],
+and [[http://www.stanford.edu/class/ee380/Abstracts/100428-pike-stanford.pdf][download the slides]].
-Last week's release included a code lab, [[https://golang.org/doc/codelab/wiki/][Writing Web Applications]], that details the construction of a simple wiki program. It is a practical introduction to some fundamental Go concepts, and the first of a series of Go code labs.
+Last week's release included a code lab, [[https://golang.org/doc/codelab/wiki/][Writing Web Applications]],
+that details the construction of a simple wiki program.
+It is a practical introduction to some fundamental Go concepts,
+and the first of a series of Go code labs.
-Lastly, we are often asked "How do Go packages work?" It's easier to show than to explain, so I put together a [[http://www.youtube.com/watch?v=jDWBJOXs_iI][Go Packages screen cast]] that demonstrates the process of writing, building, installing, and redistributing Go packages. I hope to post more of these covering a variety of Go programming topics to the [[http://youtube.com/gocoding][gocoding YouTube channel]] in the near future.
+Lastly, we are often asked "How do Go packages work?" It's easier to show than to explain,
+so I put together a [[http://www.youtube.com/watch?v=jDWBJOXs_iI][Go Packages screen cast]]
+that demonstrates the process of writing,
+building, installing, and redistributing Go packages.
+I hope to post more of these covering a variety of Go programming topics
+to the [[http://youtube.com/gocoding][gocoding YouTube channel]] in the near future.
diff --git a/content/organizing-go-code.article b/content/organizing-go-code.article
index 49fd728..5be76a0 100644
--- a/content/organizing-go-code.article
+++ b/content/organizing-go-code.article
@@ -6,48 +6,116 @@
* Introduction
-Go code is organized differently to that of other languages. This post discusses how to name and package the elements of your Go program to best serve its users.
+Go code is organized differently to that of other languages.
+This post discusses how to name and package the elements of your Go program
+to best serve its users.
* Choose good names
-The names you choose affect how you think about your code, so take care when naming your package and its exported identifiers.
+The names you choose affect how you think about your code,
+so take care when naming your package and its exported identifiers.
-A package's name provides context for its contents. For instance, the [[https://golang.org/pkg/bytes/][bytes package]] from the standard library exports the `Buffer` type. On its own, the name `Buffer` isn't very descriptive, but when combined with its package name its meaning becomes clear: `bytes.Buffer`. If the package had a less descriptive name, like `util`, the buffer would likely acquire the longer and clumsier name `util.BytesBuffer`.
+A package's name provides context for its contents.
+For instance, the [[https://golang.org/pkg/bytes/][bytes package]] from
+the standard library exports the `Buffer` type.
+On its own, the name `Buffer` isn't very descriptive,
+but when combined with its package name its meaning becomes clear: `bytes.Buffer`.
+If the package had a less descriptive name,
+like `util`, the buffer would likely acquire the longer and clumsier name `util.BytesBuffer`.
-Don't be shy about renaming things as you work. As you spend time with your program you will better understand how its pieces fit together and, therefore, what their names should be. There's no need to lock yourself into early decisions. (The [[https://golang.org/cmd/gofmt/][gofmt command]] has a `-r` flag that provides a syntax-aware search and replace, making large-scale refactoring easier.)
+Don't be shy about renaming things as you work.
+As you spend time with your program you will better understand how its pieces fit together and,
+therefore, what their names should be.
+There's no need to lock yourself into early decisions.
+(The [[https://golang.org/cmd/gofmt/][gofmt command]] has a `-r` flag that
+provides a syntax-aware search and replace,
+making large-scale refactoring easier.)
-A good name is the most important part of a software interface: the name is the first thing every client of the code will see. A well-chosen name is therefore the starting point for good documentation. Many of the following practices result organically from good naming.
+A good name is the most important part of a software interface:
+the name is the first thing every client of the code will see.
+A well-chosen name is therefore the starting point for good documentation.
+Many of the following practices result organically from good naming.
* Choose a good import path (make your package "go get"-able)
-An import path is the string with which users import a package. It specifies the directory (relative to `$GOROOT/src/pkg` or `$GOPATH/src`) in which the package's source code resides.
+An import path is the string with which users import a package.
+It specifies the directory (relative to `$GOROOT/src/pkg` or `$GOPATH/src`)
+in which the package's source code resides.
-Import paths should be globally unique, so use the path of your source repository as its base. For instance, the `websocket` package from the `go.net` sub-repository has an import path of `"golang.org/x/net/websocket"`. The Go project owns the path `"github.com/golang"`, so that path cannot be used by another author for a different package. Because the repository URL and import path are one and the same, the `go`get` command can fetch and install the package automatically.
+Import paths should be globally unique, so use the path of your source repository as its base.
+For instance, the `websocket` package from the `go.net` sub-repository has
+an import path of `"golang.org/x/net/websocket"`.
+The Go project owns the path `"github.com/golang"`,
+so that path cannot be used by another author for a different package.
+Because the repository URL and import path are one and the same,
+the `go`get` command can fetch and install the package automatically.
-If you don't use a hosted source repository, choose some unique prefix such as a domain, company, or project name. As an example, the import path of all Google's internal Go code starts with the string `"google"`.
+If you don't use a hosted source repository,
+choose some unique prefix such as a domain,
+company, or project name.
+As an example, the import path of all Google's internal Go code starts with
+the string `"google"`.
-The last element of the import path is typically the same as the package name. For instance, the import path `"net/http"` contains package `http`. This is not a requirement - you can make them different if you like - but you should follow the convention for predictability's sake: a user might be surprised that import `"foo/bar"` introduces the identifier `quux` into the package name space.
+The last element of the import path is typically the same as the package name.
+For instance, the import path `"net/http"` contains package `http`.
+This is not a requirement - you can make them different if you like - but
+you should follow the convention for predictability's sake:
+a user might be surprised that import `"foo/bar"` introduces the identifier
+`quux` into the package name space.
-Sometimes people set `GOPATH` to the root of their source repository and put their packages in directories relative to the repository root, such as `"src/my/package"`. On one hand, this keeps the import paths short (`"my/package"` instead of `"github.com/me/project/my/package"`), but on the other it breaks `go`get` and forces users to re-set their `GOPATH` to use the package. Don't do this.
+Sometimes people set `GOPATH` to the root of their source repository and
+put their packages in directories relative to the repository root,
+such as `"src/my/package"`.
+On one hand, this keeps the import paths short (`"my/package"` instead of
+`"github.com/me/project/my/package"`),
+but on the other it breaks `go`get` and forces users to re-set their `GOPATH`
+to use the package. Don't do this.
* Minimize the exported interface
-Your code is likely composed of many small pieces of useful code, and so it is tempting to expose much of that functionality in your package's exported interface. Resist that urge!
+Your code is likely composed of many small pieces of useful code,
+and so it is tempting to expose much of that functionality in your package's
+exported interface. Resist that urge!
-The larger the interface you provide, the more you must support. Users will quickly come to depend on every type, function, variable, and constant you export, creating an implicit contract that you must honor in perpetuity or risk breaking your users' programs. In preparing Go 1 we carefully reviewed the standard library's exported interfaces and removed the parts we weren't ready to commit to. You should take similar care when distributing your own libraries.
+The larger the interface you provide, the more you must support.
+Users will quickly come to depend on every type,
+function, variable, and constant you export,
+creating an implicit contract that you must honor in perpetuity or risk
+breaking your users' programs.
+In preparing Go 1 we carefully reviewed the standard library's exported
+interfaces and removed the parts we weren't ready to commit to.
+You should take similar care when distributing your own libraries.
If in doubt, leave it out!
* What to put into a package
-It is easy to just throw everything into a "grab bag" package, but this dilutes the meaning of the package name (as it must encompass a lot of functionality) and forces the users of small parts of the package to compile and link a lot of unrelated code.
+It is easy to just throw everything into a "grab bag" package,
+but this dilutes the meaning of the package name (as it must encompass a
+lot of functionality) and forces the users of small parts of the package
+to compile and link a lot of unrelated code.
-On the other hand, it is also easy to go overboard in splitting your code into small packages, in which case you will likely becomes bogged down in interface design, rather than just getting the job done.
+On the other hand, it is also easy to go overboard in splitting your code
+into small packages,
+in which case you will likely becomes bogged down in interface design,
+rather than just getting the job done.
-Look to the Go standard libraries as a guide. Some of its packages are large and some are small. For instance, the [[https://golang.org/pkg/net/http/][http package]] comprises 17 go source files (excluding tests) and exports 109 identifiers, and the [[https://golang.org/pkg/hash/][hash package]] consists of one file that exports just three declarations. There is no hard and fast rule; both approaches are appropriate given their context.
+Look to the Go standard libraries as a guide.
+Some of its packages are large and some are small.
+For instance, the [[https://golang.org/pkg/net/http/][http package]] comprises
+17 go source files (excluding tests) and exports 109 identifiers,
+and the [[https://golang.org/pkg/hash/][hash package]] consists of one file
+that exports just three declarations.
+There is no hard and fast rule; both approaches are appropriate given their context.
-With that said, package main is often larger than other packages. Complex commands contain a lot of code that is of little use outside the context of the executable, and often it's simpler to just keep it all in the one place. For instance, the go tool is more than 12000 lines spread across [[https://golang.org/src/cmd/go/][34 files]].
+With that said, package main is often larger than other packages.
+Complex commands contain a lot of code that is of little use outside the
+context of the executable,
+and often it's simpler to just keep it all in the one place.
+For instance, the go tool is more than 12000 lines spread across [[https://golang.org/src/cmd/go/][34 files]].
* Document your code
-Good documentation is an essential quality of usable and maintainable code. Read the [[https://golang.org/doc/articles/godoc_documenting_go_code.html][Godoc: documenting Go code]] article to learn how to write good doc comments.
+Good documentation is an essential quality of usable and maintainable code.
+Read the [[https://golang.org/doc/articles/godoc_documenting_go_code.html][Godoc: documenting Go code]]
+article to learn how to write good doc comments.
diff --git a/content/oscon.article b/content/oscon.article
index 4f6854e..8e929f8 100644
--- a/content/oscon.article
+++ b/content/oscon.article
@@ -12,21 +12,33 @@
On Monday you'll have the chance to learn Go in these two tutorials:
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34395][Getting Started with Go]] by [[http://twitter.com/spf13][Steve Francia]] (MongoDB) at 9:00am on Monday, 07/21/2014
+- [[http://www.oscon.com/oscon2014/public/schedule/detail/34395][Getting Started with Go]]
+ by [[http://twitter.com/spf13][Steve Francia]] (MongoDB) at 9:00am on Monday, 07/21/2014
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34267][A Quick Introduction to System Tools Programming with Go]] by [[http://twitter.com/macmceniry][Chris McEniry]] (Sony Network Entertainment) at 1:30pm on Monday, 07/21/2014
+- [[http://www.oscon.com/oscon2014/public/schedule/detail/34267][A Quick Introduction to System Tools Programming with Go]]
+ by [[http://twitter.com/macmceniry][Chris McEniry]] (Sony Network Entertainment)
+ at 1:30pm on Monday, 07/21/2014
During the rest of the week you can hear how different projects use Go:
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34371][A Recovering Java Developer Learns to Go]] by [[http://twitter.com/mstine][Matt Stine]] (Pivotal) at 1:40pm on Tuesday, 07/22/2014
+- [[http://www.oscon.com/oscon2014/public/schedule/detail/34371][A Recovering Java Developer Learns to Go]]
+ by [[http://twitter.com/mstine][Matt Stine]] (Pivotal) at 1:40pm on Tuesday, 07/22/2014
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34299][Painless Data Storage with MongoDB and Go]] by [[http://twitter.com/spf13][Steve Francia]] (MongoDB) and [[http://twitter.com/gniemeyer][Gustavo Niemeyer]] (Canonical) at 1:40pm on Tuesday, 07/22/2014
+- [[http://www.oscon.com/oscon2014/public/schedule/detail/34299][Painless Data Storage with MongoDB and Go]]
+ by [[http://twitter.com/spf13][Steve Francia]] (MongoDB) and [[http://twitter.com/gniemeyer][Gustavo Niemeyer]]
+ (Canonical) at 1:40pm on Tuesday, 07/22/2014
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/37795][Gophers with Hammers: Fun with Parsing and Generating Go]] by [[http://twitter.com/offbymany][Josh Bleecher Snyder]] (PayPal) at 2:30pm on Tuesday, 07/22/2014
+- [[http://www.oscon.com/oscon2014/public/schedule/detail/37795][Gophers with Hammers: Fun with Parsing and Generating Go]]
+ by [[http://twitter.com/offbymany][Josh Bleecher Snyder]] (PayPal) at 2:30pm
+ on Tuesday, 07/22/2014
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34047][Go for Object Oriented Programmers (or OO Programming without Objects)]] by [[http://twitter.com/spf13][Steve Francia]] (MongoDB) at 4:10pm on Wednesday, 07/23/2014
+- [[http://www.oscon.com/oscon2014/public/schedule/detail/34047][Go for Object Oriented Programmers (or OO Programming without Objects)]]
+ by [[http://twitter.com/spf13][Steve Francia]] (MongoDB) at 4:10pm on
+ Wednesday, 07/23/2014
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34509][Inside the Go Tour]] by [[http://twitter.com/francesc][Francesc Campoy Flores]] (Google Inc.) at 11:50am on Thursday, 07/24/2014
+- [[http://www.oscon.com/oscon2014/public/schedule/detail/34509][Inside the Go Tour]]
+ by [[http://twitter.com/francesc][Francesc Campoy Flores]] (Google Inc.)
+ at 11:50am on Thursday, 07/24/2014
And if you have any questions come to the
[[http://www.oscon.com/oscon2014/public/schedule/detail/37075][Go office hours]]
diff --git a/content/pipelines.article b/content/pipelines.article
index febc0c4..de145a1 100644
--- a/content/pipelines.article
+++ b/content/pipelines.article
@@ -307,6 +307,12 @@
Further reading:
-- [[https://talks.golang.org/2012/concurrency.slide#1][Go Concurrency Patterns]] ([[https://www.youtube.com/watch?v=f6kdp27TYZs][video]]) presents the basics of Go's concurrency primitives and several ways to apply them.
-- [[https://blog.golang.org/advanced-go-concurrency-patterns][Advanced Go Concurrency Patterns]] ([[http://www.youtube.com/watch?v=QDDwwePbDtw][video]]) covers more complex uses of Go's primitives, especially `select`.
-- Douglas McIlroy's paper [[https://swtch.com/~rsc/thread/squint.pdf][Squinting at Power Series]] shows how Go-like concurrency provides elegant support for complex calculations.
+- [[https://talks.golang.org/2012/concurrency.slide#1][Go Concurrency Patterns]]
+ ([[https://www.youtube.com/watch?v=f6kdp27TYZs][video]]) presents the basics
+ of Go's concurrency primitives and several ways to apply them.
+- [[https://blog.golang.org/advanced-go-concurrency-patterns][Advanced Go Concurrency Patterns]]
+ ([[http://www.youtube.com/watch?v=QDDwwePbDtw][video]]) covers more complex
+ uses of Go's primitives,
+ especially `select`.
+- Douglas McIlroy's paper [[https://swtch.com/~rsc/thread/squint.pdf][Squinting at Power Series]]
+ shows how Go-like concurrency provides elegant support for complex calculations.
diff --git a/content/playground.article b/content/playground.article
index 8e676e8..c1eb6e5 100644
--- a/content/playground.article
+++ b/content/playground.article
@@ -34,8 +34,13 @@
The playground service has three parts:
-- A back end that runs on Google's servers. It receives RPC requests, compiles the user program using the gc tool chain, executes the user program, and returns the program output (or compilation errors) as the RPC response.
-- A front end that runs on [[https://cloud.google.com/appengine/docs/go/][Google App Engine]]. It receives HTTP requests from the client and makes corresponding RPC requests to the back end. It also does some caching.
+- A back end that runs on Google's servers.
+ It receives RPC requests, compiles the user program using the gc tool chain,
+ executes the user program, and returns the program output (or compilation
+ errors) as the RPC response.
+- A front end that runs on [[https://cloud.google.com/appengine/docs/go/][Google App Engine]].
+ It receives HTTP requests from the client and makes corresponding RPC requests to the back end.
+ It also does some caching.
- A JavaScript client that implements the user interface and makes HTTP requests to the front end.
@@ -119,7 +124,8 @@
program believes that time has passed, when in fact the sleep was nearly
instantaneous.
-These changes to the scheduler can be found in [[https://golang.org/cl/73110043][`proc.c`]] and [[https://golang.org/cl/73110043][`time.goc`]].
+These changes to the scheduler can be found in [[https://golang.org/cl/73110043][`proc.c`]]
+and [[https://golang.org/cl/73110043][`time.goc`]].
Fake time fixes the issue of resource exhaustion on the back end, but what
about the program output? It would be odd to see a program that sleeps run to
@@ -234,7 +240,9 @@
There are several implementations of the interface:
- regular files and devices (such as `/dev/random`) are represented by [[https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go#L58][`fsysFile`]],
-- standard input, output, and error are instances of [[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L216][`naclFile`]], which uses system calls to interact with the actual files (these are a playground program's only way to interact with the outside world),
+- standard input, output, and error are instances of [[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L216][`naclFile`]],
+ which uses system calls to interact with the actual files (these are a playground
+ program's only way to interact with the outside world),
- network sockets have their own implementation, discussed in the next section.
@@ -257,7 +265,8 @@
and protocols, and so on.
The implementation can be found in [[https://github.com/golang/go/blob/master/src/syscall/net_nacl.go][`net_nacl.go`]].
-A good place to start reading is [[https://github.com/golang/go/blob/master/src/syscall/net_nacl.go#L461][`netFile`]], the network socket implementation of the `fileImpl` interface.
+A good place to start reading is [[https://github.com/golang/go/blob/master/src/syscall/net_nacl.go#L461][`netFile`]],
+the network socket implementation of the `fileImpl` interface.
* The front end
diff --git a/content/preview-of-go-version-1.article b/content/preview-of-go-version-1.article
index bb7d26f..48a9224 100644
--- a/content/preview-of-go-version-1.article
+++ b/content/preview-of-go-version-1.article
@@ -6,14 +6,42 @@
* Introduction
-We want to be able to provide a stable base for people using Go. People should be able to write Go programs and expect that they will continue to compile and run without change, on a timescale of years. Similarly, people should be able to write books about Go, be able to say which version of Go the book is describing, and have that version number still be meaningful much later. None of these properties is true for Go today.
+We want to be able to provide a stable base for people using Go.
+People should be able to write Go programs and expect that they will continue
+to compile and run without change,
+on a timescale of years.
+Similarly, people should be able to write books about Go,
+be able to say which version of Go the book is describing,
+and have that version number still be meaningful much later.
+None of these properties is true for Go today.
-We propose to issue a Go release early next year that will be called “Go version 1”, Go 1 for short, that will be the first Go release to be stable in this way. Code that compiles in Go version 1 should, with few exceptions, continue to compile throughout the lifetime of that version, as we issue updates and bug fixes such as Go version 1.1, 1.2, and so on. It will also be maintained with fixes for bugs and security flaws even as other versions may evolve. Also, production environments such as Google App Engine will support it for an extended time.
+We propose to issue a Go release early next year that will be called “Go version 1”,
+Go 1 for short, that will be the first Go release to be stable in this way.
+Code that compiles in Go version 1 should,
+with few exceptions, continue to compile throughout the lifetime of that version,
+as we issue updates and bug fixes such as Go version 1.1, 1.2, and so on.
+It will also be maintained with fixes for bugs and security flaws even as
+other versions may evolve.
+Also, production environments such as Google App Engine will support it
+for an extended time.
-Go version 1 will be a stable language with stable libraries. Other than critical fixes, changes made to the library and packages for versions 1.1, 1.2 and so on may add functionality but will not break existing Go version 1 programs.
+Go version 1 will be a stable language with stable libraries.
+Other than critical fixes, changes made to the library and packages for versions 1.1,
+1.2 and so on may add functionality but will not break existing Go version 1 programs.
-Our goal is for Go 1 to be a stable version of today’s Go, not a wholesale rethinking of the language. In particular, we are explicitly resisting any efforts to design new language features “by committee.”
+Our goal is for Go 1 to be a stable version of today’s Go,
+not a wholesale rethinking of the language.
+In particular, we are explicitly resisting any efforts to design new language
+features “by committee.”
-However, there are various changes to the Go language and packages that we have intended for some time and prototyped but have not deployed yet, primarily because they are significant and backwards-incompatible. If Go 1 is to be long-lasting, it is important that we plan, announce, implement, and test these changes as part of the preparation of Go 1, rather than delay them until after it is released and thereby introduce divergence that contradicts our goals.
+However, there are various changes to the Go language and packages that
+we have intended for some time and prototyped but have not deployed yet,
+primarily because they are significant and backwards-incompatible.
+If Go 1 is to be long-lasting, it is important that we plan,
+announce, implement, and test these changes as part of the preparation of Go 1,
+rather than delay them until after it is released and thereby introduce
+divergence that contradicts our goals.
-Today, we are publishing our preliminary [[https://docs.google.com/document/pub?id=1ny8uI-_BHrDCZv_zNBSthNKAMX_fR_0dc6epA6lztRE][plan for Go 1]] for feedback from the Go community. If you have feedback, please reply to the [[http://groups.google.com/group/golang-nuts/browse_thread/thread/badc4f323431a4f6][thread on the golang-nuts mailing list]].
+Today, we are publishing our preliminary [[https://docs.google.com/document/pub?id=1ny8uI-_BHrDCZv_zNBSthNKAMX_fR_0dc6epA6lztRE][plan for Go 1]]
+for feedback from the Go community.
+If you have feedback, please reply to the [[http://groups.google.com/group/golang-nuts/browse_thread/thread/badc4f323431a4f6][thread on the golang-nuts mailing list]].
diff --git a/content/publishing-go-modules.article b/content/publishing-go-modules.article
index 8edc5e3..6036b70 100644
--- a/content/publishing-go-modules.article
+++ b/content/publishing-go-modules.article
@@ -97,9 +97,14 @@
A semantic version has the form `vMAJOR.MINOR.PATCH`.
-- Increment the `MAJOR` version when you make a [[https://golang.org/doc/go1compat][backwards incompatible]] change to the public API of your module. This should only be done when absolutely necessary.
-- Increment the `MINOR` version when you make a backwards compatible change to the API, like changing dependencies or adding a new function, method, struct field, or type.
-- Increment the `PATCH` version after making minor changes that don't affect your module's public API or dependencies, like fixing a bug.
+- Increment the `MAJOR` version when you make a [[https://golang.org/doc/go1compat][backwards incompatible]]
+ change to the public API of your module.
+ This should only be done when absolutely necessary.
+- Increment the `MINOR` version when you make a backwards compatible change to the API,
+ like changing dependencies or adding a new function,
+ method, struct field, or type.
+- Increment the `PATCH` version after making minor changes that don't affect
+ your module's public API or dependencies, like fixing a bug.
You can specify pre-release versions by appending a hyphen and dot separated
identifiers (for example, `v1.0.1-alpha` or `v2.2.2-beta.2`). Normal releases
@@ -197,7 +202,9 @@
The standard library's `strings` package is a prime example of maintaining
backwards compatibility at the cost of API consistency.
-- [[https://godoc.org/strings#Split][`Split`]] slices a string into all substrings separated by a separator and returns a slice of the substrings between those separators.
+- [[https://godoc.org/strings#Split][`Split`]] slices a string into all
+ substrings separated by a separator and returns a slice of the substrings
+ between those separators.
- [[https://godoc.org/strings#SplitN][`SplitN`]] can be used to control the number of substrings to return.
However, [[https://godoc.org/strings#Replace][`Replace`]] took a count of how
diff --git a/content/qihoo.article b/content/qihoo.article
index 57994da..ccd16bc 100644
--- a/content/qihoo.article
+++ b/content/qihoo.article
@@ -46,20 +46,33 @@
Here are a few tweaks we made and key take-aways:
-- Replace short connections with persistent ones (using a connection pool), to reduce creation of buffers and objects during communication.
+- Replace short connections with persistent ones (using a connection pool),
+ to reduce creation of buffers and objects during communication.
- Use Objects and Memory pools appropriately, to reduce the load on the GC.
.image qihoo/image00.png
-- Use a Task Pool, a mechanism with a group of long-lived goroutines consuming global task or message queues sent by connection goroutines, to replace short-lived goroutines.
+- Use a Task Pool, a mechanism with a group of long-lived goroutines consuming
+ global task or message queues sent by connection goroutines,
+ to replace short-lived goroutines.
-- Monitor and control goroutine numbers in the program. The lack of control can cause unbearable burden on the GC, imposed by surges in goroutines due to uninhibited acceptance of external requests, as RPC invocations sent to inner servers may block goroutines recently created.
+- Monitor and control goroutine numbers in the program.
+ The lack of control can cause unbearable burden on the GC,
+ imposed by surges in goroutines due to uninhibited acceptance of external requests,
+ as RPC invocations sent to inner servers may block goroutines recently created.
-- Remember to add [[https://golang.org/pkg/net/#Conn][read and write deadlines]] to connections when under a mobile network; otherwise, it may lead to goroutine blockage. Apply it properly and with caution when under a LAN network, otherwise your RPC communication efficiency will be hurt.
+- Remember to add [[https://golang.org/pkg/net/#Conn][read and write deadlines]]
+ to connections when under a mobile network;
+ otherwise, it may lead to goroutine blockage.
+ Apply it properly and with caution when under a LAN network,
+ otherwise your RPC communication efficiency will be hurt.
- Use Pipeline (under Full Duplex feature of TCP) to enhance the communication efficiency of RPC framework.
-As a result, we successfully launched three iterations of our architecture, and two iterations of our RPC framework even with limited human resources. This can all attributed to the development convenience of Go. Below you can find the up-to-date system architecture:
+As a result, we successfully launched three iterations of our architecture,
+and two iterations of our RPC framework even with limited human resources.
+This can all attributed to the development convenience of Go.
+Below you can find the up-to-date system architecture:
.image qihoo/image01.png
diff --git a/content/real-go-projects-smarttwitter-and-webgo.article b/content/real-go-projects-smarttwitter-and-webgo.article
index 912cf7e..2c79ac7 100644
--- a/content/real-go-projects-smarttwitter-and-webgo.article
+++ b/content/real-go-projects-smarttwitter-and-webgo.article
@@ -6,18 +6,66 @@
* Introduction
-_This_week's_article_is_written_by_ [[http://www.hoisie.com/][_Michael_Hoisie_]]. _A_programmer_based_in_San_Francisco,_he_is_one_of_Go's_early_adopters_and_the_author_of_several_popular_Go_libraries._He_describes_his_experiences_using_Go:_
+_This_week's_article_is_written_by_ [[http://www.hoisie.com/][_Michael_Hoisie_]].
+_A_programmer_based_in_San_Francisco,_he_is_one_of_Go's_early_adopters_and_the_author_of_several_popular_Go_libraries._He_describes_his_experiences_using_Go:_
-I was introduced to Go by a post on [[http://news.ycombinator.com/][Hacker News]]. About an hour later I was hooked. At the time I was working at a web start-up, and had been developing internal testing apps in Python. Go offered speed, better concurrency support, and sane Unicode handling, so I was keen to port my programs to the language. At that time there wasn't an easy way to write web apps in Go, so I decided to build a simple web framework, [[http://github.com/hoisie/web.go][web.go]]. It was modeled after a popular Python framework, [[http://webpy.org/][web.py]], which I had worked with previously. While working on web.go I got involved in the Go community, submitted a bunch of bug reports, and hacked on some standard library packages (mainly [[https://golang.org/pkg/http/][http]] and [[https://golang.org/pkg/json/][json]]).
+I was introduced to Go by a post on [[http://news.ycombinator.com/][Hacker News]].
+About an hour later I was hooked. At the time I was working at a web start-up,
+and had been developing internal testing apps in Python.
+Go offered speed, better concurrency support,
+and sane Unicode handling, so I was keen to port my programs to the language.
+At that time there wasn't an easy way to write web apps in Go,
+so I decided to build a simple web framework,
+[[http://github.com/hoisie/web.go][web.go]].
+It was modeled after a popular Python framework,
+[[http://webpy.org/][web.py]], which I had worked with previously.
+While working on web.go I got involved in the Go community,
+submitted a bunch of bug reports, and hacked on some standard library packages
+(mainly [[https://golang.org/pkg/http/][http]] and [[https://golang.org/pkg/json/][json]]).
-After a few weeks I noticed that web.go was getting attention at Github. This was surprising because I'd never really promoted the project. I think there's a niche for simple, fast web applications, and I think Go can fill it.
+After a few weeks I noticed that web.go was getting attention at Github.
+This was surprising because I'd never really promoted the project.
+I think there's a niche for simple, fast web applications,
+and I think Go can fill it.
-One weekend I decided to write a simple Facebook application: it would re-post your Twitter status updates to your Facebook profile. There is an official Twitter application to do this, but it re-posts everything, creating noise in your Facebook feed. My application allowed you to filter retweets, mentions, hashtags, replies, and more. This turned into [[http://www.facebook.com/apps/application.php?id=135488932982][Smart Twitter]], which currently has nearly 90,000 users.
+One weekend I decided to write a simple Facebook application:
+it would re-post your Twitter status updates to your Facebook profile.
+There is an official Twitter application to do this,
+but it re-posts everything, creating noise in your Facebook feed.
+My application allowed you to filter retweets,
+mentions, hashtags, replies, and more.
+This turned into [[http://www.facebook.com/apps/application.php?id=135488932982][Smart Twitter]],
+which currently has nearly 90,000 users.
-The entire program is written in Go, and uses [[https://redis.io/][Redis]] as its storage back-end. It is very fast and robust. It currently processes about two dozen tweets per second, and makes heavy use of Go's channels. It runs on a single Virtual Private Server instance with 2GB of RAM, which has no problem handling the load. Smart Twitter uses very little CPU time, and is almost entirely memory-bound as the entire database is kept in memory. At any given time there are around 10 goroutines running concurrently: one accepting HTTP connections, another reading from the Twitter Streaming API, a couple for error handling, and the rest either processing web requests or re-posting incoming tweets.
+The entire program is written in Go, and uses [[https://redis.io/][Redis]]
+as its storage back-end.
+It is very fast and robust. It currently processes about two dozen tweets per second,
+and makes heavy use of Go's channels.
+It runs on a single Virtual Private Server instance with 2GB of RAM,
+which has no problem handling the load.
+Smart Twitter uses very little CPU time, and is almost entirely memory-bound
+as the entire database is kept in memory.
+At any given time there are around 10 goroutines running concurrently:
+one accepting HTTP connections, another reading from the Twitter Streaming API,
+a couple for error handling, and the rest either processing web requests
+or re-posting incoming tweets.
-Smart Twitter also spawned other open-source Go projects: [[http://github.com/hoisie/mustache.go][mustache.go]], [[http://github.com/hoisie/redis.go][redis.go]], and [[http://github.com/hoisie/twitterstream][twitterstream]].
+Smart Twitter also spawned other open-source Go projects:
+[[http://github.com/hoisie/mustache.go][mustache.go]],
+[[http://github.com/hoisie/redis.go][redis.go]],
+and [[http://github.com/hoisie/twitterstream][twitterstream]].
-I see a lot of work left to do on web.go. For instance, I'd like to add better support for streaming connections, websockets, route filters, better support in shared hosts, and improving the documentation. I recently left the start-up to do software freelancing, and I'm planning to use Go where possible. This means I'll probably use it as a back end for personal apps, as well as for clients that like working with cutting edge technology.
+I see a lot of work left to do on web.go.
+For instance, I'd like to add better support for streaming connections,
+websockets, route filters, better support in shared hosts,
+and improving the documentation.
+I recently left the start-up to do software freelancing,
+and I'm planning to use Go where possible.
+This means I'll probably use it as a back end for personal apps,
+as well as for clients that like working with cutting edge technology.
-Finally, I'd like to thank the Go team for all their effort. Go is a wonderful platform and I think it has a bright future. I hope to see the language grow around the needs of the community. There's a lot of interesting stuff happening in the community, and I look forward to seeing what people can hack together with the language.
+Finally, I'd like to thank the Go team for all their effort.
+Go is a wonderful platform and I think it has a bright future.
+I hope to see the language grow around the needs of the community.
+There's a lot of interesting stuff happening in the community,
+and I look forward to seeing what people can hack together with the language.
diff --git a/content/share-memory-by-communicating.article b/content/share-memory-by-communicating.article
index bd3a37e..01c7426 100644
--- a/content/share-memory-by-communicating.article
+++ b/content/share-memory-by-communicating.article
@@ -6,13 +6,28 @@
* Introduction
-Traditional threading models (commonly used when writing Java, C++, and Python programs, for example) require the programmer to communicate between threads using shared memory. Typically, shared data structures are protected by locks, and threads will contend over those locks to access the data. In some cases, this is made easier by the use of thread-safe data structures such as Python's Queue.
+Traditional threading models (commonly used when writing Java,
+C++, and Python programs, for example) require the programmer to communicate
+between threads using shared memory.
+Typically, shared data structures are protected by locks,
+and threads will contend over those locks to access the data.
+In some cases, this is made easier by the use of thread-safe data structures
+such as Python's Queue.
-Go's concurrency primitives - goroutines and channels - provide an elegant and distinct means of structuring concurrent software. (These concepts have an [[https://swtch.com/~rsc/thread/][interesting history]] that begins with C. A. R. Hoare's [[http://www.usingcsp.com/][Communicating Sequential Processes]].) Instead of explicitly using locks to mediate access to shared data, Go encourages the use of channels to pass references to data between goroutines. This approach ensures that only one goroutine has access to the data at a given time. The concept is summarized in the document [[https://golang.org/doc/effective_go.html][Effective Go]] (a must-read for any Go programmer):
+Go's concurrency primitives - goroutines and channels - provide an elegant
+and distinct means of structuring concurrent software.
+(These concepts have an [[https://swtch.com/~rsc/thread/][interesting history]] that begins with C.
+A. R. Hoare's [[http://www.usingcsp.com/][Communicating Sequential Processes]].)
+Instead of explicitly using locks to mediate access to shared data,
+Go encourages the use of channels to pass references to data between goroutines.
+This approach ensures that only one goroutine has access to the data at a given time.
+The concept is summarized in the document [[https://golang.org/doc/effective_go.html][Effective Go]]
+(a must-read for any Go programmer):
_Do_not_communicate_by_sharing_memory;_instead,_share_memory_by_communicating._
-Consider a program that polls a list of URLs. In a traditional threading environment, one might structure its data like so:
+Consider a program that polls a list of URLs.
+In a traditional threading environment, one might structure its data like so:
type Resource struct {
url string
@@ -59,9 +74,15 @@
}
}
-This function is about a page long, and requires more detail to make it complete. It doesn't even include the URL polling logic (which, itself, would only be a few lines), nor will it gracefully handle exhausting the pool of Resources.
+This function is about a page long, and requires more detail to make it complete.
+It doesn't even include the URL polling logic (which,
+itself, would only be a few lines), nor will it gracefully handle exhausting
+the pool of Resources.
-Let's take a look at the same functionality implemented using Go idiom. In this example, Poller is a function that receives Resources to be polled from an input channel, and sends them to an output channel when they're done.
+Let's take a look at the same functionality implemented using Go idiom.
+In this example, Poller is a function that receives Resources to be polled
+from an input channel,
+and sends them to an output channel when they're done.
type Resource string
@@ -74,6 +95,11 @@
}
}
-The delicate logic from the previous example is conspicuously absent, and our Resource data structure no longer contains bookkeeping data. In fact, all that's left are the important parts. This should give you an inkling as to the power of these simple language features.
+The delicate logic from the previous example is conspicuously absent,
+and our Resource data structure no longer contains bookkeeping data.
+In fact, all that's left are the important parts.
+This should give you an inkling as to the power of these simple language features.
-There are many omissions from the above code snippets. For a walkthrough of a complete, idiomatic Go program that uses these ideas, see the Codewalk [[https://golang.org/doc/codewalk/sharemem/][_Share_Memory_By_Communicating_]].
+There are many omissions from the above code snippets.
+For a walkthrough of a complete, idiomatic Go program that uses these ideas,
+see the Codewalk [[https://golang.org/doc/codewalk/sharemem/][_Share_Memory_By_Communicating_]].
diff --git a/content/spotlight-on-external-go-libraries.article b/content/spotlight-on-external-go-libraries.article
index 8747a1d..ef7c810 100644
--- a/content/spotlight-on-external-go-libraries.article
+++ b/content/spotlight-on-external-go-libraries.article
@@ -6,17 +6,53 @@
* Introduction
-While the Go authors have been working hard at improving Go's standard library, the greater community has created a growing ecosystem of external libraries. In this post we look at some popular Go libraries and how they can be used.
+While the Go authors have been working hard at improving Go's standard library,
+the greater community has created a growing ecosystem of external libraries.
+In this post we look at some popular Go libraries and how they can be used.
-[[http://labix.org/mgo][Mgo]] (pronounced "mango") is a MongoDB database driver. [[http://www.mongodb.org/][MongoDB]] is a [[http://en.wikipedia.org/wiki/Document-oriented_database][document-oriented database]] with a long list of features suitable for [[http://www.mongodb.org/display/DOCS/Use%2BCases][a broad range of uses]]. The mgo package provides a rich, idiomatic Go API for working with MongoDB, from basic operations such as inserting and updating records to the more advanced [[http://www.mongodb.org/display/DOCS/MapReduce][MapReduce]] and [[http://www.mongodb.org/display/DOCS/GridFS][GridFS]] features. Mgo has a bunch of cool features including automated cluster discovery and result pre-fetching - see the [[http://labix.org/mgo][mgo homepage]] for details and example code. For working with large data sets Go, MongoDB, and mgo are a powerful combination.
+[[http://labix.org/mgo][Mgo]] (pronounced "mango") is a MongoDB database driver.
+[[http://www.mongodb.org/][MongoDB]] is a [[http://en.wikipedia.org/wiki/Document-oriented_database][document-oriented database]]
+with a long list of features suitable for [[http://www.mongodb.org/display/DOCS/Use%2BCases][a broad range of uses]].
+The mgo package provides a rich, idiomatic Go API for working with MongoDB,
+from basic operations such as inserting and updating records to the more
+advanced [[http://www.mongodb.org/display/DOCS/MapReduce][MapReduce]] and
+[[http://www.mongodb.org/display/DOCS/GridFS][GridFS]] features.
+Mgo has a bunch of cool features including automated cluster discovery and
+result pre-fetching - see the [[http://labix.org/mgo][mgo homepage]] for
+details and example code.
+For working with large data sets Go, MongoDB,
+and mgo are a powerful combination.
-[[https://github.com/dchest/authcookie][Authcookie]] is a web library for generating and verifying user authentication cookies. It allows web servers to hand out cryptographically secure tokens tied to a specific user that will expire after a specified time period. It has a simple API that makes it straightforward to add authentication to existing web applications. See the [[https://github.com/dchest/authcookie/blob/master/README.md][README file]] for details and example code.
+[[https://github.com/dchest/authcookie][Authcookie]] is a web library for
+generating and verifying user authentication cookies.
+It allows web servers to hand out cryptographically secure tokens tied to
+a specific user that will expire after a specified time period.
+It has a simple API that makes it straightforward to add authentication
+to existing web applications.
+See the [[https://github.com/dchest/authcookie/blob/master/README.md][README file]]
+for details and example code.
-[[http://code.google.com/p/go-charset][Go-charset]] provides support for converting between Go's standard UTF-8 encoding and a variety of character sets. The go-charset package implements a translating io.Reader and io.Writer so you can wrap existing Readers and Writers (such as network connections or file descriptors), making it easy to communicate with systems that use other character encodings.
+[[http://code.google.com/p/go-charset][Go-charset]] provides support for
+converting between Go's standard UTF-8 encoding and a variety of character sets.
+The go-charset package implements a translating io.Reader and io.Writer
+so you can wrap existing Readers and Writers (such as network connections
+or file descriptors),
+making it easy to communicate with systems that use other character encodings.
-[[https://github.com/madari/go-socket.io][Go-socket.io]] is a Go implementation of [[http://socket.io/][Socket.IO]], a client/server API that allows web servers to push messages to web browsers. Depending on the capabilities of the user's browser, Socket.IO uses the best transport for the connection, be it modern websockets, AJAX long polling, or some [[http://socket.io/#transports][other mechanism]]. Go-socket.io bridges the gap between Go servers and rich JavaScript clients for a wide range of browsers. To get a feel for go-socket.io see the [[https://github.com/madari/go-socket.io/blob/master/example/example.go][chat server example]].
+[[https://github.com/madari/go-socket.io][Go-socket.io]] is a Go implementation
+of [[http://socket.io/][Socket.IO]],
+a client/server API that allows web servers to push messages to web browsers.
+Depending on the capabilities of the user's browser,
+Socket.IO uses the best transport for the connection,
+be it modern websockets, AJAX long polling,
+or some [[http://socket.io/#transports][other mechanism]].
+Go-socket.io bridges the gap between Go servers and rich JavaScript clients
+for a wide range of browsers.
+To get a feel for go-socket.io see the [[https://github.com/madari/go-socket.io/blob/master/example/example.go][chat server example]].
-It's worth mentioning that these packages are [[https://golang.org/cmd/goinstall/][goinstallable]]. With an up-to-date Go [[https://golang.org/doc/install.html][installation]] you can install them all with a single command:
+It's worth mentioning that these packages are [[https://golang.org/cmd/goinstall/][goinstallable]].
+With an up-to-date Go [[https://golang.org/doc/install.html][installation]]
+you can install them all with a single command:
goinstall launchpad.net/mgo \
github.com/dchest/authcookie \
@@ -34,8 +70,11 @@
)
-Also, as they are now a part of the local Go system, we can inspect their documentation with [[https://golang.org/cmd/godoc/][godoc]]:
+Also, as they are now a part of the local Go system,
+we can inspect their documentation with [[https://golang.org/cmd/godoc/][godoc]]:
godoc launchpad.net/mgo Database # see docs for Database type
-Of course, this is just the tip of the iceberg; there are more great Go libraries listed on the [[http://godashboard.appspot.com/package][package dashboard]] and many more to come.
+Of course, this is just the tip of the iceberg;
+there are more great Go libraries listed on the [[http://godashboard.appspot.com/package][package dashboard]]
+and many more to come.
diff --git a/content/survey2016-results.article b/content/survey2016-results.article
index 1c75f56..b4092c4 100644
--- a/content/survey2016-results.article
+++ b/content/survey2016-results.article
@@ -21,7 +21,8 @@
We also asked about the kinds of programs people write in Go.
63% of respondents write command-line programs, 60% write API or RPC services, and 52% write web services.
-Like in the previous question, most made multiple choices, with 85% choosing two or more and 72% choosing three or more.
+Like in the previous question, most made multiple choices,
+with 85% choosing two or more and 72% choosing three or more.
We asked about people’s expertise and preference among programming languages.
@@ -87,26 +88,33 @@
Users most agreed that Go’s performance meets their needs (57:1 ratio agree versus disagree),
that they are able to quickly find answers to their questions (20:1),
and that they are able to effectively use Go’s concurrency features (14:1).
-On the other hand, users least agreed that they are able to effectively debug uses of Go’s concurrency features (2.7:1).
+On the other hand, users least agreed that they are able to effectively
+debug uses of Go’s concurrency features (2.7:1).
Users mostly agreed that they were able to quickly find libraries they need (7.5:1).
When asked what libraries are still missing, the most common request by far was a library for writing GUIs.
Another popular topic was requests around data processing, analytics, and numerical and scientific computing.
-Of the 30% of users who suggested ways to improve Go’s documentation, the most common suggestion by far was more examples.
+Of the 30% of users who suggested ways to improve Go’s documentation,
+the most common suggestion by far was more examples.
-The primary sources for Go news are the Go blog, Reddit’s /r/golang and Twitter; there may be some bias here since these are also how the survey was announced.
+The primary sources for Go news are the Go blog,
+Reddit’s /r/golang and Twitter;
+there may be some bias here since these are also how the survey was announced.
-The primary sources for finding answers to Go questions are the Go web site, Stack Overflow, and reading source code directly.
+The primary sources for finding answers to Go questions are the Go web site,
+Stack Overflow, and reading source code directly.
.html survey2016/effective.html
* The Go Project
55% of respondents expressed interest in contributing in some way to the Go community and projects.
-Unfortunately, relatively few agreed that they felt welcome to do so (3.3:1) and even fewer felt that the process was clear (1.3:1).
-In 2017, we intend to work on improving the contribution process and to continue to work to make all contributors feel welcome.
+Unfortunately, relatively few agreed that they felt welcome to do so (3.3:1)
+and even fewer felt that the process was clear (1.3:1).
+In 2017, we intend to work on improving the contribution process and to
+continue to work to make all contributors feel welcome.
Respondents agree that they are confident in the leadership of the Go project (9:1),
but they agree much less that the project leadership understands their needs (2.6:1),
@@ -128,7 +136,8 @@
In particular, India, China, and Japan each accounted for about 5% of the site visits to golang.org in 2016
but only 3%, 2%, and 1% of survey responses.
-An important part of a community is making everyone feel welcome, especially people from under-represented demographics.
+An important part of a community is making everyone feel welcome,
+especially people from under-represented demographics.
We asked an optional question about identification across a few diversity groups.
37% of respondents left the question blank and 12% of respondents chose “I prefer not to answer”,
so we cannot make many broad conclusions from the data.
diff --git a/content/survey2018-results.article b/content/survey2018-results.article
index 4830c0f..5ba4a1f 100644
--- a/content/survey2018-results.article
+++ b/content/survey2018-results.article
@@ -8,26 +8,51 @@
* Thank you
.html survey2018/style.html
-This post summarizes the results of our 2018 user survey and draws comparisons between the results of our prior surveys from [[https://blog.golang.org/survey2016-results][2016]] and [[https://blog.golang.org/survey2017-results][2017]].
+This post summarizes the results of our 2018 user survey and draws comparisons
+between the results of our prior surveys from [[https://blog.golang.org/survey2016-results][2016]]
+and [[https://blog.golang.org/survey2017-results][2017]].
-This year we had 5,883 survey respondents from 103 different countries. We are grateful to everyone who provided their feedback through this survey to help shape the future of Go. Thank you!
+This year we had 5,883 survey respondents from 103 different countries.
+We are grateful to everyone who provided their feedback through this survey
+to help shape the future of Go. Thank you!
* Summary of findings
-- For the first time, *half*of*survey*respondents*are*now*using*Go*as*part*of*their*daily*routine*. This year also saw significant increases in the number of respondents who develop in Go as part of their jobs and use Go outside of work responsibilities.
-- The most *common*uses*for*Go*remain*API/RPC*services*and*CLI*tools*. Automation tasks, while not as common as CLI tools and API services, are a fast-growing area for Go.
-- *Web*development*remains*the*most*common*domain* that survey respondents work in, but *DevOps*showed*the*highest*year-over-year*growth* and is now the second most common domain.
-- A large majority of survey respondents said *Go*is*their*most-preferred*programming*language*, despite generally feeling less proficient with it than at least one other language.
+- For the first time, *half*of*survey*respondents*are*now*using*Go*as*part*of*their*daily*routine*.
+ This year also saw significant increases in the number of respondents who
+ develop in Go as part of their jobs and use Go outside of work responsibilities.
+- The most *common*uses*for*Go*remain*API/RPC*services*and*CLI*tools*.
+ Automation tasks, while not as common as CLI tools and API services,
+ are a fast-growing area for Go.
+- *Web*development*remains*the*most*common*domain* that survey respondents work in,
+ but *DevOps*showed*the*highest*year-over-year*growth* and is now the second most common domain.
+- A large majority of survey respondents said *Go*is*their*most-preferred*programming*language*,
+ despite generally feeling less proficient with it than at least one other language.
- *VS*Code*and*GoLand*are*surging*in*popularity* and are now the most popular code editors among survey respondents.
-- Highlighting the portable nature of Go, *many*Go*developers*use*more*than*one*primary*OS* for development. Linux and macOS are particularly popular, with a large majority of survey respondents using one or both of these operating systems to write Go code.
-- Survey respondents appear to be *shifting*away*from*on-prem*Go*deployments* and moving towards containers and serverless cloud deployments.
-- The majority of respondents said they feel welcome in the Go community, and most ideas for improving the Go community specifically focus on *improving*the*experience*of*newcomers*.
+- Highlighting the portable nature of Go,
+ *many*Go*developers*use*more*than*one*primary*OS* for development.
+ Linux and macOS are particularly popular,
+ with a large majority of survey respondents using one or both of these operating
+ systems to write Go code.
+- Survey respondents appear to be *shifting*away*from*on-prem*Go*deployments*
+ and moving towards containers and serverless cloud deployments.
+- The majority of respondents said they feel welcome in the Go community,
+ and most ideas for improving the Go community specifically focus on *improving*the*experience*of*newcomers*.
Read on for all of the details.
* Programming background
-This year's results show a significant increase in the number of survey respondents who are paid to write Go as part of their jobs (68% → 72%), continuing a year-over-year trend that has been growing since our first survey in 2016. We also see an increase in the number of respondents who program in Go outside of work (64% → 70%). For the first time, the number of survey respondents who write in Go as part of their daily routine reached 50% (up from 44% in 2016). These findings suggests companies are continuing to embrace Go for professional software development at a consistent pace, and that Go's general popularity with developers remains strong.
+This year's results show a significant increase in the number of survey
+respondents who are paid to write Go as part of their jobs (68% → 72%),
+continuing a year-over-year trend that has been growing since our first survey in 2016.
+We also see an increase in the number of respondents who program in Go outside
+of work (64% → 70%).
+For the first time, the number of survey respondents who write in Go as
+part of their daily routine reached 50% (up from 44% in 2016).
+These findings suggests companies are continuing to embrace Go for professional
+software development at a consistent pace,
+and that Go's general popularity with developers remains strong.
#This year we saw an 8-point increase in the number of respondents who program in other languages at work. The majority of these developers (55%) still program in Go as part of their daily routine, and an additional 31% program in Go weekly. This suggests there is a sizable (and growing) audience of Go developers whose work involves switching between multiple languages; , and may be dealing with a difficult mental context switch due to syntactic and semantic language differences. Indeed, participants reported that one of their challenges to using Go was "differences from familiar languages/ecosystems", as we'll discuss in the _Attitudes_towards_Go_ section below.
@@ -42,21 +67,67 @@
#.image survey2018/fig3.svg _ 600
#.caption Figure 3
-To better understand where developers use Go, we broke responses down into three groups: 1) people who are using Go both in and outside of work, 2) people who use Go professionally but not outside of work, and 3) people who only write Go outside of their job responsibilities. Nearly half (46%) of respondents write Go code both professionally and on their own time (a 10-point increase since 2017), while the remaining respondents are closely split between either only writing Go at work, or only writing Go outside of work. The large percentage of respondents who both use Go at work and choose to use it outside of work suggests that the language appeals to developers who do not view software engineering as a day job: they also choose to hack on code outside of work responsibilities, and (as evidenced by 85% of respondents saying they'd prefer Go for their next project, see section _Attitudes_towards_Go_ below) Go is the top language they'd prefer to use for these non-work-related projects.
+To better understand where developers use Go,
+we broke responses down into three groups:
+1) people who are using Go both in and outside of work,
+2) people who use Go professionally but not outside of work,
+and 3) people who only write Go outside of their job responsibilities.
+Nearly half (46%) of respondents write Go code both professionally and on
+their own time (a 10-point increase since 2017),
+while the remaining respondents are closely split between either only writing Go at work,
+or only writing Go outside of work.
+The large percentage of respondents who both use Go at work and choose to
+use it outside of work suggests that the language appeals to developers
+who do not view software engineering as a day job:
+they also choose to hack on code outside of work responsibilities,
+and (as evidenced by 85% of respondents saying they'd prefer Go for their next project,
+see section _Attitudes_towards_Go_ below) Go is the top language they'd
+prefer to use for these non-work-related projects.
.image survey2018/fig4.svg _ 600
#.caption Figure 4
-When asked how long they've been using Go, participants' answers are strongly trending upward over time, with a higher percentage of responses in the 2-4 and 4+ year buckets each year. This is expected for a newer programming language, and we're glad to see that the percentage of respondents who are new to Go is dropping more slowly than the percentage of respondents who have been using Go for 2+ years is increasing, as this suggests that developers are not dropping out of the ecosystem after initially learning the language.
+When asked how long they've been using Go,
+participants' answers are strongly trending upward over time,
+with a higher percentage of responses in the 2-4 and 4+ year buckets each year.
+This is expected for a newer programming language,
+and we're glad to see that the percentage of respondents who are new to
+Go is dropping more slowly than the percentage of respondents who have been
+using Go for 2+ years is increasing,
+as this suggests that developers are not dropping out of the ecosystem after
+initially learning the language.
.image survey2018/fig5.svg _ 600
#.caption Figure 5
-As in prior years, Go ranks at the top of respondents' preferred languages and languages in which they have expertise. A majority of respondents (69%) claimed expertise in 5 different languages, highlighting that their attitudes towards Go are influenced by experiences with other programming stacks. The charts below are sorted by the number of respondents who ranked each language as their most preferred/understood (the darkest blue bars), which highlights three interesting bits:
+As in prior years, Go ranks at the top of respondents' preferred languages
+and languages in which they have expertise.
+A majority of respondents (69%) claimed expertise in 5 different languages,
+highlighting that their attitudes towards Go are influenced by experiences
+with other programming stacks.
+The charts below are sorted by the number of respondents who ranked each
+language as their most preferred/understood (the darkest blue bars),
+which highlights three interesting bits:
-- While about ⅓ of respondents consider Go to be the language in which they have the most expertise, twice that many respondents consider it their most preferred programming language. So even though many respondents feel they haven't become as proficient with Go as with some other language, they still frequently prefer to develop with Go.
-- Few survey respondents rank Rust as a language in which they have expertise (6.8%), yet 19% rank it as a top preferred language, indicating a high level of interest in Rust among this audience.
-- Only three languages have more respondents who say they prefer the language than say they have expertise with it: Rust (2.41:1 ratio of preference:expertise), Kotlin (1.95:1), and Go (1.02:1). Higher preference than expertise implies interest—but little direct experience—in a language, while lower preference than expertise numbers suggests barriers to proficient use. Ratios near 1.0 suggest that most developers are able to work effectively _and_ enjoyably with a given language. This data is corroborated by [[https://insights.stackoverflow.com/survey/2018/#most-loved-dreaded-and-wanted][Stack Overflow's 2018 developer survey]], which also found Rust, Kotlin, and Go to be among the most-preferred programming languages.
+- While about ⅓ of respondents consider Go to be the language in which
+ they have the most expertise,
+ twice that many respondents consider it their most preferred programming language.
+ So even though many respondents feel they haven't become as proficient with
+ Go as with some other language,
+ they still frequently prefer to develop with Go.
+- Few survey respondents rank Rust as a language in which they have expertise (6.8%),
+ yet 19% rank it as a top preferred language,
+ indicating a high level of interest in Rust among this audience.
+- Only three languages have more respondents who say they prefer the language
+ than say they have expertise with it:
+ Rust (2.41:1 ratio of preference:expertise),
+ Kotlin (1.95:1), and Go (1.02:1).
+ Higher preference than expertise implies interest—but little direct experience—in a language,
+ while lower preference than expertise numbers suggests barriers to proficient use.
+ Ratios near 1.0 suggest that most developers are able to work effectively
+ _and_ enjoyably with a given language.
+ This data is corroborated by [[https://insights.stackoverflow.com/survey/2018/#most-loved-dreaded-and-wanted][Stack Overflow's 2018 developer survey]],
+ which also found Rust, Kotlin, and Go to be among the most-preferred programming languages.
.image survey2018/fig6.svg _ 600
#.caption Figure 6
@@ -67,40 +138,108 @@
* Development domains
-Survey respondents reported working on a median of three different domains, with a large majority (72%) working in 2-5 different areas. Web development is the most prevalent at 65%, and it increased its dominance as the primary area survey respondents work in (up from 61% last year): web development has been the most common domain for Go development since 2016. This year DevOps noticeably increased, from 36% to 41% of respondents, taking over the number two spot from Systems Programming. We did not find any domains with lower usage in 2018 than in 2017, suggesting that respondents are adopting Go for a wider variety of projects, rather than shifting usage from one domain to another.
+Survey respondents reported working on a median of three different domains,
+with a large majority (72%) working in 2-5 different areas.
+Web development is the most prevalent at 65%,
+and it increased its dominance as the primary area survey respondents work
+in (up from 61% last year):
+web development has been the most common domain for Go development since 2016.
+This year DevOps noticeably increased, from 36% to 41% of respondents,
+taking over the number two spot from Systems Programming.
+We did not find any domains with lower usage in 2018 than in 2017,
+suggesting that respondents are adopting Go for a wider variety of projects,
+rather than shifting usage from one domain to another.
.image survey2018/fig8.svg _ 600
#.caption Figure 8
-Since 2016, the top two uses of Go have been writing API/RPC services and developing CLI applications. While CLI usage has remained stable at 63% for three years, API/RPC usage has increased from 60% in 2016 to 65% in 2017 to 73% today. These domains play to core strengths of Go and are both central to cloud-native software development, so we expect them to remain two of the primary scenarios for Go developers into the future. The percentage of respondents who write web services that directly return HTML has steadily dropped while API/RPC usage has increased, suggesting some migration to the API/RPC model for web services. Another year-over-year trend suggests that automation is also a growing area for Go, with 38% of respondents now using Go for scripts and automation tasks (up from 31% in 2016).
+Since 2016, the top two uses of Go have been writing API/RPC services and
+developing CLI applications.
+While CLI usage has remained stable at 63% for three years,
+API/RPC usage has increased from 60% in 2016 to 65% in 2017 to 73% today.
+These domains play to core strengths of Go and are both central to cloud-native
+software development,
+so we expect them to remain two of the primary scenarios for Go developers into the future.
+The percentage of respondents who write web services that directly return
+HTML has steadily dropped while API/RPC usage has increased,
+suggesting some migration to the API/RPC model for web services.
+Another year-over-year trend suggests that automation is also a growing area for Go,
+with 38% of respondents now using Go for scripts and automation tasks (up from 31% in 2016).
.image survey2018/fig9.svg _ 600
#.caption Figure 9
-To better understand the contexts in which developers are using Go, we added a question about Go adoption across different industries. Perhaps unsurprisingly for a relatively new language, over half of survey respondents work in companies in the _Internet/web_services_ and _Software_ categories (i.e., tech companies). The only other industries with >3% responses were _Finance,_banking,_or_insurance_ and _Media,_advertising,_publishing,_or_entertainment_. (In the chart below, we've condensed all of the categories with response rates below 3% into the "Other" category.) We'll continue tracking Go's adoption across industries to better understand developer needs outside of technology companies.
+To better understand the contexts in which developers are using Go,
+we added a question about Go adoption across different industries.
+Perhaps unsurprisingly for a relatively new language,
+over half of survey respondents work in companies in the _Internet/web_services_
+and _Software_ categories (i.e., tech companies).
+The only other industries with >3% responses were _Finance,_banking,_or_insurance_
+and _Media,_advertising,_publishing,_or_entertainment_.
+(In the chart below, we've condensed all of the categories with response
+rates below 3% into the "Other" category.) We'll continue tracking Go's
+adoption across industries to better understand developer needs outside
+of technology companies.
.image survey2018/fig10.svg _ 600
#.caption Figure 10
* Attitudes towards Go
-This year we added a question asking "How likely are you to recommend Go to a friend or colleague?" to calculate our [[https://en.wikipedia.org/wiki/Net_Promoter][Net Promoter Score]]. This score attempts to measure how many more "promoters" a product has than "detractors" and ranges from -100 to 100; a positive value suggests most people are likely to recommend using a product, while negative values suggest most people are likely to recommend against using it. Our 2018 score is 61 (68% promoters - 7% detractors) and will serve as a baseline to help us gauge community sentiment towards the Go ecosystem over time.
+This year we added a question asking "How likely are you to recommend Go
+to a friend or colleague?" to calculate our [[https://en.wikipedia.org/wiki/Net_Promoter][Net Promoter Score]].
+This score attempts to measure how many more "promoters" a product has than
+"detractors" and ranges from -100 to 100;
+a positive value suggests most people are likely to recommend using a product,
+while negative values suggest most people are likely to recommend against using it.
+Our 2018 score is 61 (68% promoters - 7% detractors) and will serve as a
+baseline to help us gauge community sentiment towards the Go ecosystem over time.
.image survey2018/fig11.svg _ 600
#.caption Figure 11
-In addition to NPS, we asked several questions about developer satisfaction with Go. Overall, survey respondents indicated a high level of satisfaction, consistent with prior years. Large majorities say they are happy with Go (89%), would prefer to use Go for their next project (85%), and feel that it is working well for their team (66%), while a plurality feel that Go is at least somewhat critical to their company's success (44%). While all of these metrics showed an increase in 2017, they remained mostly stable this year. (The wording of the first question changed in 2018 from "_I_would_recommend_using_Go_to_others_" to "_Overall,_I'm_happy_with_Go_", so those results are not directly comparable.)
+In addition to NPS, we asked several questions about developer satisfaction with Go.
+Overall, survey respondents indicated a high level of satisfaction,
+consistent with prior years.
+Large majorities say they are happy with Go (89%),
+would prefer to use Go for their next project (85%),
+and feel that it is working well for their team (66%),
+while a plurality feel that Go is at least somewhat critical to their company's success (44%).
+While all of these metrics showed an increase in 2017,
+they remained mostly stable this year.
+(The wording of the first question changed in 2018 from "_I_would_recommend_using_Go_to_others_"
+to "_Overall,_I'm_happy_with_Go_",
+so those results are not directly comparable.)
#We also looked at only the respondents who _strongly_ agreed with each statement and found the same pattern: increases in 2017, stabilizing in 2018.
.image survey2018/fig12.svg _ 600
#.caption Figure 12
-Given the strong sentiment towards preferring Go for future development, we want to understand what prevents developers from doing so. These remained largely unchanged since last year: about ½ of survey respondents work on existing projects written in other languages, and ⅓ work on a team or project that prefers to use a different language. Missing language features and libraries round out the most common reasons respondents did not use Go more. We also asked about the biggest challenges developers face while using Go; unlike most of our survey questions, respondents could type in anything they wished to answer this question. We analyzed the results via machine learning to identify common themes and counting the number of responses that supported each theme. The top three major challenges we identified are:
+Given the strong sentiment towards preferring Go for future development,
+we want to understand what prevents developers from doing so.
+These remained largely unchanged since last year:
+about ½ of survey respondents work on existing projects written in other languages,
+and ⅓ work on a team or project that prefers to use a different language.
+Missing language features and libraries round out the most common reasons
+respondents did not use Go more.
+We also asked about the biggest challenges developers face while using Go;
+unlike most of our survey questions, respondents could type in anything
+they wished to answer this question.
+We analyzed the results via machine learning to identify common themes and
+counting the number of responses that supported each theme.
+The top three major challenges we identified are:
-- Package management (e.g., "Keeping up with vendoring", "dependency / packet [sic] management / vendoring not unified")
-- Differences from more familiar programming languages (e.g., "syntax close to C-languages with slightly different semantics makes me look up references somewhat more than I'd like", "coworkers who come from non-Go backgrounds trying to use Go as a version of their previous language but with channels and Goroutines")
-- Lack of generics (e.g., "Lack of generics makes it difficult to persuade people who have not tried Go that they would find it efficient.", "Hard to build richer abstractions (want generics)")
+- Package management (e.g., "Keeping up with vendoring",
+ "dependency / packet [sic] management / vendoring not unified")
+- Differences from more familiar programming languages (e.g.,
+ "syntax close to C-languages with slightly different semantics makes me
+ look up references somewhat more than I'd like",
+ "coworkers who come from non-Go backgrounds trying to use Go as a version
+ of their previous language but with channels and Goroutines")
+- Lack of generics (e.g., "Lack of generics makes it difficult to persuade
+ people who have not tried Go that they would find it efficient.",
+ "Hard to build richer abstractions (want generics)")
.image survey2018/fig13.svg _ 600
#.caption Figure 13
@@ -108,11 +247,31 @@
.image survey2018/fig14.svg _ 600
#.caption Figure 14
-This year we added several questions about developer satisfaction with different aspects of Go. Survey respondents were very satisfied with Go applications' CPU performance (46:1, meaning 46 respondents said they were satisfied for every 1 respondent who said they were not satisfied), build speed (37:1), and application memory utilization (32:1). Responses for application debuggability (3.2:1) and binary size (6.4:1), however, suggest room for improvement.
+This year we added several questions about developer satisfaction with different aspects of Go.
+Survey respondents were very satisfied with Go applications' CPU performance (46:1,
+meaning 46 respondents said they were satisfied for every 1 respondent who
+said they were not satisfied),
+build speed (37:1), and application memory utilization (32:1).
+Responses for application debuggability (3.2:1) and binary size (6.4:1),
+however, suggest room for improvement.
-The dissatisfaction with binary size largely comes from developers building CLIs, only 30% of whom are satisfied with the size of Go's generated binaries. For all other types of applications, however, developer satisfaction was > 50%, and binary size was consistently ranked at the bottom of the list of important factors.
+The dissatisfaction with binary size largely comes from developers building CLIs,
+only 30% of whom are satisfied with the size of Go's generated binaries.
+For all other types of applications, however,
+developer satisfaction was > 50%, and binary size was consistently ranked
+at the bottom of the list of important factors.
-Debuggability, conversely, stands out when we look at how respondents ranked the importance of each aspect; 44% of respondents ranked debuggability as their most or second-most important aspect, but only 36% were satisfied with the current state of Go debugging. Debuggability was consistently rated about as important as memory usage and build speed but with significantly lower satisfaction levels, and this pattern held true regardless of the type of software respondents were building. The two most recent Go releases, Go 1.11 and 1.12, both contained significant improvements to debuggability. We plan to investigate how developers debug Go applications in more depth this year, with a goal of improving the overall debugging experience for Go developers.
+Debuggability, conversely, stands out when we look at how respondents ranked
+the importance of each aspect;
+44% of respondents ranked debuggability as their most or second-most important aspect,
+but only 36% were satisfied with the current state of Go debugging.
+Debuggability was consistently rated about as important as memory usage
+and build speed but with significantly lower satisfaction levels,
+and this pattern held true regardless of the type of software respondents were building.
+The two most recent Go releases, Go 1.11 and 1.12,
+both contained significant improvements to debuggability.
+We plan to investigate how developers debug Go applications in more depth this year,
+with a goal of improving the overall debugging experience for Go developers.
.image survey2018/fig15.svg _ 600
#.caption Figure 15
@@ -122,14 +281,42 @@
* Development environments
-We asked respondents which operating systems they primarily use when writing Go code. A majority (65%) of respondents said they use Linux, 50% use macOS, and 18% use Windows, consistent with last year. This year we also looked at how many respondents develop on multiple OSes vs. a single OS. Linux and macOS remain the clear leaders, with 81% of respondents developing on some mix of these two systems. Only 3% of respondents evenly split their time between all three OSes. Overall, 41% of respondents use multiple operating systems for Go development, highlighting the cross-platform nature of Go.
+We asked respondents which operating systems they primarily use when writing Go code.
+A majority (65%) of respondents said they use Linux,
+50% use macOS, and 18% use Windows, consistent with last year.
+This year we also looked at how many respondents develop on multiple OSes vs. a single OS.
+Linux and macOS remain the clear leaders,
+with 81% of respondents developing on some mix of these two systems.
+Only 3% of respondents evenly split their time between all three OSes.
+Overall, 41% of respondents use multiple operating systems for Go development,
+highlighting the cross-platform nature of Go.
.image survey2018/fig16.svg _ 600
#.caption Figure 16
-Last year, VS Code edged out Vim as the most popular Go editor among survey respondents. This year it significantly expanded its lead to become the preferred editor for over ⅓ of our survey respondents (up from 27% last year). GoLand also experienced strong growth and is now the second most-preferred editor at 22%, swapping places with Vim (down to 17%). The surging popularity of VS Code and GoLand appear to be coming at the expense of Sublime Text and Atom. Vim also saw the number of respondents ranking it their top choice drop, but it remains the most popular second-choice editor at 14%. Interestingly, we found no differences in the level of satisfaction respondents reported for their editor(s) of choice.
+Last year, VS Code edged out Vim as the most popular Go editor among survey respondents.
+This year it significantly expanded its lead to become the preferred editor
+for over ⅓ of our survey respondents (up from 27% last year).
+GoLand also experienced strong growth and is now the second most-preferred editor at 22%,
+swapping places with Vim (down to 17%).
+The surging popularity of VS Code and GoLand appear to be coming at the
+expense of Sublime Text and Atom.
+Vim also saw the number of respondents ranking it their top choice drop,
+but it remains the most popular second-choice editor at 14%.
+Interestingly, we found no differences in the level of satisfaction respondents
+reported for their editor(s) of choice.
-We also asked respondents what would most improve Go support in their preferred editor. Like the "biggest challenge" question above, participants could write in their own response rather than select from a multiple-choice list. A thematic analysis on the responses revealed that _improved_debugging_support_ (e.g., "Live debugging", "Integrated debugging", "Even better debugging") was the most-common request, followed by _improved_code_completion_ (e.g., "autocomplete performance and quality", "smarter autocomplete"). Other requests include better integration with Go's CLI toolchain, better support for modules/packages, and general performance improvements.
+We also asked respondents what would most improve Go support in their preferred editor.
+Like the "biggest challenge" question above,
+participants could write in their own response rather than select from a
+multiple-choice list.
+A thematic analysis on the responses revealed that _improved_debugging_support_ (e.g.,
+"Live debugging", "Integrated debugging",
+"Even better debugging") was the most-common request,
+followed by _improved_code_completion_ (e.g.,
+"autocomplete performance and quality", "smarter autocomplete").
+Other requests include better integration with Go's CLI toolchain,
+better support for modules/packages, and general performance improvements.
.image survey2018/fig17.svg _ 600
#.caption Figure 17
@@ -137,26 +324,68 @@
.image survey2018/fig18.svg _ 600
#.caption Figure 18
-This year we also added a question asking which deployment architectures are most important to Go developers. Unsurprisingly, survey respondents overwhelmingly view x86/x86-64 as their top deployment platform (76% of respondents listed it as their most important deployment architecture, and 84% had it in their top 3). The ranking of the second- and third-choice architectures, however, is informative: there is significant interest in ARM64 (45%), WebAssembly (30%), and ARM (22%), but very little interest in other platforms.
+This year we also added a question asking which deployment architectures
+are most important to Go developers.
+Unsurprisingly, survey respondents overwhelmingly view x86/x86-64 as their
+top deployment platform (76% of respondents listed it as their most important
+deployment architecture,
+and 84% had it in their top 3).
+The ranking of the second- and third-choice architectures,
+however, is informative:
+there is significant interest in ARM64 (45%),
+WebAssembly (30%), and ARM (22%), but very little interest in other platforms.
.image survey2018/fig19.svg _ 600
#.caption Figure 19
* Deployments and services
-For 2018 we see a continuation of the trend from on-prem to cloud hosting for both Go and non-Go deployments. The percentage of survey respondents who deploy Go applications to on-prem servers dropped from 43% → 32%, mirroring the 46% → 36% drop reported for non-Go deployments. The cloud services which saw the highest year-over-year growth include AWS Lambda (4% → 11% for Go, 10% → 15% non-Go) and Google Kubernetes Engine (8% → 12% for Go, 5% → 10% non-Go), suggesting that serverless and containers are becoming increasingly popular deployment platforms. This service growth appears to be driven by respondents who had already adopted cloud services, however, as we found no meaningful growth in the percentage of respondents who deploy to at least one cloud service this year (55% → 56%). We also see steady growth in Go deployments to GCP since 2016, increasing from 12% → 19% of respondents.
+For 2018 we see a continuation of the trend from on-prem to cloud hosting
+for both Go and non-Go deployments.
+The percentage of survey respondents who deploy Go applications to on-prem
+servers dropped from 43% → 32%,
+mirroring the 46% → 36% drop reported for non-Go deployments.
+The cloud services which saw the highest year-over-year growth include AWS
+Lambda (4% → 11% for Go,
+10% → 15% non-Go) and Google Kubernetes Engine (8% → 12% for Go,
+5% → 10% non-Go), suggesting that serverless and containers are becoming
+increasingly popular deployment platforms.
+This service growth appears to be driven by respondents who had already
+adopted cloud services,
+however, as we found no meaningful growth in the percentage of respondents
+who deploy to at least one cloud service this year (55% → 56%).
+We also see steady growth in Go deployments to GCP since 2016,
+increasing from 12% → 19% of respondents.
.image survey2018/fig20.svg _ 600
#.caption Figure 20
-Perhaps correlated with the decrease in on-prem deployments, this year we saw cloud storage become the second-most used service by survey respondents, increasing from 32% → 44%. Authentication & federation services also saw a significant increase (26% → 33%). The primary service survey respondents access from Go remains open-source relational databases, which ticked up from 61% → 65% of respondents. As the below chart shows, service usage increased across the board.
+Perhaps correlated with the decrease in on-prem deployments,
+this year we saw cloud storage become the second-most used service by survey respondents,
+increasing from 32% → 44%.
+Authentication & federation services also saw a significant increase (26% → 33%).
+The primary service survey respondents access from Go remains open-source
+relational databases,
+which ticked up from 61% → 65% of respondents.
+As the below chart shows, service usage increased across the board.
.image survey2018/fig21.svg _ 600
#.caption Figure 21
* Go community
-The top community sources for finding answers to Go questions continue to be Stack Overflow (23% of respondents marked it as their top source), Go web sites (18% for godoc.org, 14% for golang.org), and reading source code (8% for source code generally, 4% for GitHub specifically). The order remains largely consistent with prior years. The primary sources for Go news remain the Go blog, Reddit's r/golang, Twitter, and Hacker News. These were also the primary distribution methods for this survey, however, so there is likely some bias in this result. In the two charts below, we've grouped sources used by less than < 5% of respondents into the "Other" category.
+The top community sources for finding answers to Go questions continue to
+be Stack Overflow (23% of respondents marked it as their top source),
+Go web sites (18% for godoc.org, 14% for golang.org),
+and reading source code (8% for source code generally,
+4% for GitHub specifically).
+The order remains largely consistent with prior years.
+The primary sources for Go news remain the Go blog,
+Reddit's r/golang, Twitter, and Hacker News.
+These were also the primary distribution methods for this survey,
+however, so there is likely some bias in this result.
+In the two charts below, we've grouped sources used by less than < 5% of
+respondents into the "Other" category.
.image survey2018/fig24.svg _ 600
#.caption Figure 24
@@ -164,7 +393,15 @@
.image survey2018/fig25.svg _ 600
#.caption Figure 25
-This year, 55% of survey respondents said they have or are interested in contributing to the Go community, slightly down from 59% last year. Because the two most common areas for contribution (the standard library and official Go tools) require interacting with the core Go team, we suspect this decrease may be related to a dip in the percentage of participants who agreed with the statements "I feel comfortable approaching the Go project leadership with questions and feedback" (30% → 25%) and "I am confident in the leadership of Go (54% → 46%).
+This year, 55% of survey respondents said they have or are interested in
+contributing to the Go community,
+slightly down from 59% last year.
+Because the two most common areas for contribution (the standard library
+and official Go tools) require interacting with the core Go team,
+we suspect this decrease may be related to a dip in the percentage of participants
+who agreed with the statements "I feel comfortable approaching the Go project
+leadership with questions and feedback" (30% → 25%) and "I am confident
+in the leadership of Go (54% → 46%).
.image survey2018/fig26.svg _ 600
#.caption Figure 26
@@ -172,22 +409,59 @@
.image survey2018/fig27.svg _ 600
#.caption Figure 27
-An important aspect of community is helping everyone feel welcome, especially people from traditionally under-represented demographics. To better understand this, we asked an optional question about identification across several under-represented groups. In 2017 we saw year-over-year increases across the board. For 2018, we saw a similar percentage of respondents (12%) identify as part of an under-represented group, and this was paired with a significant decrease in the percentage of respondents who do *not* identify as part of an under-represented group. In 2017, for every person who identified as part of an under-represented group, 3.5 people identified as not part of an under-represented group (3.5:1 ratio). In 2018 that ratio improved to 3.08:1. This suggests that the Go community is at least retaining the same proportions of under-represented members, and may even be increasing.
+An important aspect of community is helping everyone feel welcome,
+especially people from traditionally under-represented demographics.
+To better understand this, we asked an optional question about identification
+across several under-represented groups.
+In 2017 we saw year-over-year increases across the board.
+For 2018, we saw a similar percentage of respondents (12%) identify as part
+of an under-represented group,
+and this was paired with a significant decrease in the percentage of respondents
+who do *not* identify as part of an under-represented group.
+In 2017, for every person who identified as part of an under-represented group,
+3.5 people identified as not part of an under-represented group (3.5:1 ratio).
+In 2018 that ratio improved to 3.08:1. This suggests that the Go community
+is at least retaining the same proportions of under-represented members,
+and may even be increasing.
.image survey2018/fig28.svg _ 600
#.caption Figure 28
-Maintaining a healthy community is extremely important to the Go project, so for the past three years we've been measuring the extent to which developers feel welcome in the Go community. This year we saw a drop in the percentage of survey respondents who agree with the statement "I feel welcome in the Go community", from 66% → 59%.
+Maintaining a healthy community is extremely important to the Go project,
+so for the past three years we've been measuring the extent to which developers
+feel welcome in the Go community.
+This year we saw a drop in the percentage of survey respondents who agree
+with the statement "I feel welcome in the Go community", from 66% → 59%.
-To better understand this decrease, we looked more closely at who reported feeling less welcome. Among traditionally under-represented groups, fewer people reported feeling unwelcome in 2018, suggesting that outreach in that area has been helpful. Instead, we found a linear relationship between the length of time someone has used Go and how welcome they feel: newer Go developers felt significantly less welcome (at 50%) than developers with 1-2 years of experience (62%), who in turn felt less welcome than developers with a few years of experience (73%). This interpretation of the data is supported by responses to the question "What changes would make the Go community more welcoming?". Respondents' comments can be broadly grouped into four categories:
+To better understand this decrease, we looked more closely at who reported
+feeling less welcome.
+Among traditionally under-represented groups,
+fewer people reported feeling unwelcome in 2018,
+suggesting that outreach in that area has been helpful.
+Instead, we found a linear relationship between the length of time someone
+has used Go and how welcome they feel:
+newer Go developers felt significantly less welcome (at 50%) than developers
+with 1-2 years of experience (62%),
+who in turn felt less welcome than developers with a few years of experience (73%).
+This interpretation of the data is supported by responses to the question
+"What changes would make the Go community more welcoming?".
+Respondents' comments can be broadly grouped into four categories:
-- Reduce a perception of elitism, especially for newcomers to Go (e.g., "less dismissiveness", "Less defensiveness and hubris")
-- Increase transparency at the leadership level (e.g., "Future direction and planning discussions", "Less top down leadership", "More democratic")
-- Increase introductory resources (e.g., "A more clear introduction for contributors", "Fun challenges to learn best practices")
-- More events and meetups, with a focus on covering a larger geographic area (e.g., "More meetups & social events", "Events in more cities")
+- Reduce a perception of elitism, especially for newcomers to Go (e.g.,
+ "less dismissiveness", "Less defensiveness and hubris")
+- Increase transparency at the leadership level (e.g.,
+ "Future direction and planning discussions",
+ "Less top down leadership", "More democratic")
+- Increase introductory resources (e.g., "A more clear introduction for contributors",
+ "Fun challenges to learn best practices")
+- More events and meetups, with a focus on covering a larger geographic area (e.g.,
+ "More meetups & social events", "Events in more cities")
-This feedback is very helpful and gives us concrete areas we can focus on to improve the experience of being a Go developer. While it doesn't represent a large percentage of our user base, we take this feedback very seriously and are working on improving each area.
+This feedback is very helpful and gives us concrete areas we can focus on
+to improve the experience of being a Go developer.
+While it doesn't represent a large percentage of our user base,
+we take this feedback very seriously and are working on improving each area.
.image survey2018/fig22.svg _ 600
#.caption Figure 22
@@ -197,4 +471,8 @@
* Conclusion
-We hope you've enjoyed seeing the results of our 2018 developer survey. These results are impacting our 2019 planning, and in the coming months we'll share some ideas with you to address specific issues and needs the community has highlighted for us. Once again, thank you to everyone who contributed to this survey!
+We hope you've enjoyed seeing the results of our 2018 developer survey.
+These results are impacting our 2019 planning,
+and in the coming months we'll share some ideas with you to address specific
+issues and needs the community has highlighted for us.
+Once again, thank you to everyone who contributed to this survey!
diff --git a/content/survey2019.article b/content/survey2019.article
index b589c77..1d8ef4a 100644
--- a/content/survey2019.article
+++ b/content/survey2019.article
@@ -7,10 +7,29 @@
* Help shape the future of Go
-Since 2016, thousands of Gophers around the world have helped the Go project by sharing your thoughts via our annual Go Developer Survey. Your feedback has played an enormous role in driving changes to our language, ecosystem, and community, including [[https://about.sourcegraph.com/go/gophercon-2019-go-pls-stop-breaking-my-editor][the gopls language server]], new [[https://blog.golang.org/go1.13-errors][error-handling mechanics]], the [[https://blog.golang.org/module-mirror-launch][module mirror]], and so much more from the latest [[https://blog.golang.org/go1.13][Go 1.13 release]]. And of course, we publicly share [[https://blog.golang.org/survey2016-results][each]] [[https://blog.golang.org/survey2017-results][year's]] [[https://blog.golang.org/survey2018-results][results]], so we can all benefit from the community's insights.
+Since 2016, thousands of Gophers around the world have helped the Go project
+by sharing your thoughts via our annual Go Developer Survey.
+Your feedback has played an enormous role in driving changes to our language,
+ecosystem, and community, including [[https://about.sourcegraph.com/go/gophercon-2019-go-pls-stop-breaking-my-editor][the gopls language server]],
+new [[https://blog.golang.org/go1.13-errors][error-handling mechanics]],
+the [[https://blog.golang.org/module-mirror-launch][module mirror]],
+and so much more from the latest [[https://blog.golang.org/go1.13][Go 1.13 release]].
+And of course, we publicly share [[https://blog.golang.org/survey2016-results][each]]
+[[https://blog.golang.org/survey2017-results][year's]] [[https://blog.golang.org/survey2018-results][results]],
+so we can all benefit from the community's insights.
-Today we are launching the 2019 Go Developer Survey. We'd love to hear from everyone who uses Go, used to use Go, or is interested in using Go, to help ensure the language, community, and ecosystem fit the needs of the people closest to it. Please help us shape Go's future by participating in this 15-minute survey by December 15th: [[https://google.qualtrics.com/jfe/form/SV_b1xqnBCMpZAhJZ3][Take the 2019 Go Developer Survey]].
+Today we are launching the 2019 Go Developer Survey.
+We'd love to hear from everyone who uses Go,
+used to use Go, or is interested in using Go,
+to help ensure the language, community, and ecosystem fit the needs of the
+people closest to it.
+Please help us shape Go's future by participating in this 15-minute survey by December 15th:
+[[https://google.qualtrics.com/jfe/form/SV_b1xqnBCMpZAhJZ3][Take the 2019 Go Developer Survey]].
* Spread the word!
-We need as many Gophers as possible to participate in this survey to help us better understand our global user base. We'd be grateful if you would spread the word by sharing this post on your social network feeds, around the office, at meet-ups, and in other communities. Thank you!
+We need as many Gophers as possible to participate in this survey to help
+us better understand our global user base.
+We'd be grateful if you would spread the word by sharing this post on your
+social network feeds,
+around the office, at meet-ups, and in other communities. Thank you!
diff --git a/content/the-app-engine-sdk-and-workspaces-gopath.article b/content/the-app-engine-sdk-and-workspaces-gopath.article
index f2fcb40..0bf3fbf 100644
--- a/content/the-app-engine-sdk-and-workspaces-gopath.article
+++ b/content/the-app-engine-sdk-and-workspaces-gopath.article
@@ -6,13 +6,34 @@
* Introduction
-When we released Go 1 we introduced the [[https://golang.org/cmd/go/][go tool]] and, with it, the concept of workspaces. Workspaces (specified by the GOPATH environment variable) are a convention for organizing code that simplifies fetching, building, and installing Go packages. If you're not familiar with workspaces, please read [[https://golang.org/doc/code.html][this article]] or watch [[http://www.youtube.com/watch?v=XCsL89YtqCs][this screencast]] before reading on.
+When we released Go 1 we introduced the [[https://golang.org/cmd/go/][go tool]] and,
+with it, the concept of workspaces.
+Workspaces (specified by the GOPATH environment variable) are a convention
+for organizing code that simplifies fetching,
+building, and installing Go packages.
+If you're not familiar with workspaces, please read [[https://golang.org/doc/code.html][this article]]
+or watch [[http://www.youtube.com/watch?v=XCsL89YtqCs][this screencast]] before reading on.
-Until recently, the tools in the App Engine SDK were not aware of workspaces. Without workspaces the "[[https://golang.org/cmd/go/#hdr-Download_and_install_packages_and_dependencies][go get]]" command cannot function, and so app authors had to install and update their app dependencies manually. It was a pain.
+Until recently, the tools in the App Engine SDK were not aware of workspaces.
+Without workspaces the "[[https://golang.org/cmd/go/#hdr-Download_and_install_packages_and_dependencies][go get]]"
+command cannot function,
+and so app authors had to install and update their app dependencies manually. It was a pain.
-This has all changed with version 1.7.4 of the App Engine SDK. The [[https://developers.google.com/appengine/docs/go/tools/devserver][dev_appserver]] and [[https://developers.google.com/appengine/docs/go/tools/uploadinganapp][appcfg]] tools are now workspace-aware. When running locally or uploading an app, these tools now search for dependencies in the workspaces specified by the GOPATH environment variable. This means you can now use "go get" while building App Engine apps, and switch between normal Go programs and App Engine apps without changing your environment or habits.
+This has all changed with version 1.7.4 of the App Engine SDK.
+The [[https://developers.google.com/appengine/docs/go/tools/devserver][dev_appserver]]
+and [[https://developers.google.com/appengine/docs/go/tools/uploadinganapp][appcfg]]
+tools are now workspace-aware.
+When running locally or uploading an app,
+these tools now search for dependencies in the workspaces specified by the
+GOPATH environment variable.
+This means you can now use "go get" while building App Engine apps,
+and switch between normal Go programs and App Engine apps without changing
+your environment or habits.
-For example, let's say you want to build an app that uses OAuth 2.0 to authenticate with a remote service. A popular OAuth 2.0 library for Go is the [[https://godoc.org/golang.org/x/oauth2][oauth2]] package, which you can install to your workspace with this command:
+For example, let's say you want to build an app that uses OAuth 2.0 to authenticate
+with a remote service.
+A popular OAuth 2.0 library for Go is the [[https://godoc.org/golang.org/x/oauth2][oauth2]] package,
+which you can install to your workspace with this command:
go get golang.org/x/oauth2
@@ -20,15 +41,29 @@
import "golang.org/x/oauth2"
-Now, whether running your app with the dev_appserver or deploying it with appcfg, the tools will find the oauth package in your workspace. It just works.
+Now, whether running your app with the dev_appserver or deploying it with appcfg,
+the tools will find the oauth package in your workspace. It just works.
* Hybrid stand-alone/App Engine apps
-The Go App Engine SDK builds on Go's standard [[https://golang.org/pkg/net/http/][net/http]] package to serve web requests and, as a result, many Go web servers can be run on App Engine with only a few changes. For example, [[https://golang.org/cmd/godoc/][godoc]] is included in the Go distribution as a stand-alone program, but it can also run as an App Engine app (godoc serves [[https://golang.org/][golang.org]] from App Engine).
+The Go App Engine SDK builds on Go's standard [[https://golang.org/pkg/net/http/][net/http]]
+package to serve web requests and,
+as a result, many Go web servers can be run on App Engine with only a few changes.
+For example, [[https://golang.org/cmd/godoc/][godoc]] is included in the
+Go distribution as a stand-alone program,
+but it can also run as an App Engine app (godoc serves [[https://golang.org/][golang.org]] from App Engine).
-But wouldn't it be nice if you could write a program that is both a stand-alone web server and an App Engine app? By using [[https://golang.org/pkg/go/build/#hdr-Build_Constraints][build constraints]], you can.
+But wouldn't it be nice if you could write a program that is both a stand-alone
+web server and an App Engine app? By using [[https://golang.org/pkg/go/build/#hdr-Build_Constraints][build constraints]], you can.
-Build constraints are line comments that determine whether a file should be included in a package. They are most often used in code that handles a variety of operating systems or processor architectures. For instance, the [[https://golang.org/pkg/path/filepath/][path/filepath]] package includes the file [[https://golang.org/src/pkg/path/filepath/symlink.go][symlink.go]], which specifies a build constraint to ensure that it is not built on Windows systems (which do not have symbolic links):
+Build constraints are line comments that determine whether a file should
+be included in a package.
+They are most often used in code that handles a variety of operating systems
+or processor architectures.
+For instance, the [[https://golang.org/pkg/path/filepath/][path/filepath]]
+package includes the file [[https://golang.org/src/pkg/path/filepath/symlink.go][symlink.go]],
+which specifies a build constraint to ensure that it is not built on Windows
+systems (which do not have symbolic links):
// +build !windows
@@ -42,7 +77,13 @@
are ignored by the App Engine SDK, while the go tool will happily build them.
-The [[http://code.google.com/p/goprotobuf/][goprotobuf]] library uses this mechanism to provide two implementations of a key part of its encode/decode machinery: [[http://code.google.com/p/goprotobuf/source/browse/proto/pointer_unsafe.go][pointer_unsafe.go]] is the faster version that cannot be used on App Engine because it uses the [[https://golang.org/pkg/unsafe/][unsafe package]], while [[http://code.google.com/p/goprotobuf/source/browse/proto/pointer_reflect.go][pointer_reflect.go]] is a slower version that avoids unsafe by using the [[https://golang.org/pkg/reflect/][reflect package]] instead.
+The [[http://code.google.com/p/goprotobuf/][goprotobuf]] library uses this
+mechanism to provide two implementations of a key part of its encode/decode machinery:
+[[http://code.google.com/p/goprotobuf/source/browse/proto/pointer_unsafe.go][pointer_unsafe.go]]
+is the faster version that cannot be used on App Engine because it uses
+the [[https://golang.org/pkg/unsafe/][unsafe package]],
+while [[http://code.google.com/p/goprotobuf/source/browse/proto/pointer_reflect.go][pointer_reflect.go]]
+is a slower version that avoids unsafe by using the [[https://golang.org/pkg/reflect/][reflect package]] instead.
Let's take a simple Go web server and turn it into a hybrid app. This is main.go:
@@ -64,7 +105,10 @@
Build this with the go tool and you'll get a stand-alone web server executable.
-The App Engine infrastructure provides its own main function that runs its equivalent to ListenAndServe. To convert main.go to an App Engine app, drop the call to ListenAndServe and register the handler in an init function (which runs before main). This is app.go:
+The App Engine infrastructure provides its own main function that runs its
+equivalent to ListenAndServe.
+To convert main.go to an App Engine app, drop the call to ListenAndServe
+and register the handler in an init function (which runs before main). This is app.go:
package main
@@ -81,11 +125,17 @@
fmt.Fprint(w, "Hello!")
}
-To make this a hybrid app, we need to split it into an App Engine-specific part, an stand-alone binary-specific part, and the parts common to both versions. In this case, there is no App Engine-specific part, so we split it into just two files:
+To make this a hybrid app, we need to split it into an App Engine-specific part,
+an stand-alone binary-specific part, and the parts common to both versions.
+In this case, there is no App Engine-specific part,
+so we split it into just two files:
-app.go specifies and registers the handler function. It is identical to the code listing above, and requires no build constraints as it should be included in all versions of the program.
+app.go specifies and registers the handler function.
+It is identical to the code listing above,
+and requires no build constraints as it should be included in all versions of the program.
-main.go runs the web server. It includes the "!appengine" build constraint, as it must only included when building the stand-alone binary.
+main.go runs the web server. It includes the "!appengine" build constraint,
+as it must only included when building the stand-alone binary.
// +build !appengine
@@ -101,4 +151,5 @@
* Conclusions
-We hope these changes will make it easier to work on apps with external dependencies, and to maintain code bases that contain both stand-alone programs and App Engine apps.
+We hope these changes will make it easier to work on apps with external dependencies,
+and to maintain code bases that contain both stand-alone programs and App Engine apps.
diff --git a/content/the-path-to-go-1.article b/content/the-path-to-go-1.article
index 345cf93..1bb1f5f 100644
--- a/content/the-path-to-go-1.article
+++ b/content/the-path-to-go-1.article
@@ -6,10 +6,19 @@
* Introduction
-In July 2012, Rob Pike and I presented a talk at OSCON titled _The_path_to_Go_1_. In it we explain how Go 1 came to be, and outline the process by which Go was refined and stabilized to become the clean, consistent programming environment that it is today. We present the major highlights of the release and discuss the details behind some specific libraries and tools.
+In July 2012, Rob Pike and I presented a talk at OSCON titled _The_path_to_Go_1_.
+In it we explain how Go 1 came to be, and outline the process by which Go
+was refined and stabilized to become the clean,
+consistent programming environment that it is today.
+We present the major highlights of the release and discuss the details behind
+some specific libraries and tools.
.iframe //www.youtube.com/embed/bj9T2c2Xk_s 309 550
The slides for the talk are [[https://talks.golang.org/2012/go1.slide][available here]].
-It's almost a year since we cut Go 1.0 and we are now busy preparing Go 1.1. The release will include performance improvements to the gc compiler, garbage collector, and goroutine scheduler, some standard library additions, and many bug fixes and other improvements. Stay tuned, as we hope to release Go 1.1 in the coming weeks.
+It's almost a year since we cut Go 1.0 and we are now busy preparing Go 1.1.
+The release will include performance improvements to the gc compiler,
+garbage collector, and goroutine scheduler,
+some standard library additions, and many bug fixes and other improvements.
+Stay tuned, as we hope to release Go 1.1 in the coming weeks.
diff --git a/content/third-party-libraries-goprotobuf-and.article b/content/third-party-libraries-goprotobuf-and.article
index df80991..afdd586 100644
--- a/content/third-party-libraries-goprotobuf-and.article
+++ b/content/third-party-libraries-goprotobuf-and.article
@@ -6,11 +6,22 @@
* Introduction
-On March 24, Rob Pike announced [[http://code.google.com/p/goprotobuf/][goprotobuf]], the Go bindings of Google's data interchange format [[http://code.google.com/apis/protocolbuffers/docs/overview.html][Protocol Buffers]], called protobufs for short. With this announcement, Go joins C++, Java, and Python as languages providing official protobuf implementations. This marks an important milestone in enabling the interoperability between existing systems and those built in Go.
+On March 24, Rob Pike announced [[http://code.google.com/p/goprotobuf/][goprotobuf]],
+the Go bindings of Google's data interchange format [[http://code.google.com/apis/protocolbuffers/docs/overview.html][Protocol Buffers]],
+called protobufs for short.
+With this announcement, Go joins C++, Java,
+and Python as languages providing official protobuf implementations.
+This marks an important milestone in enabling the interoperability between
+existing systems and those built in Go.
-The goprotobuf project consists of two parts: a 'protocol compiler plugin' that generates Go source files that, once compiled, can access and manage protocol buffers; and a Go package that implements run-time support for encoding (marshaling), decoding (unmarshaling), and accessing protocol buffers.
+The goprotobuf project consists of two parts:
+a 'protocol compiler plugin' that generates Go source files that,
+once compiled, can access and manage protocol buffers;
+and a Go package that implements run-time support for encoding (marshaling),
+decoding (unmarshaling), and accessing protocol buffers.
-To use goprotobuf, you first need to have both Go and [[http://code.google.com/p/protobuf/][protobuf]] installed. You can then install the 'proto' package with [[https://golang.org/cmd/goinstall/][goinstall]]:
+To use goprotobuf, you first need to have both Go and [[http://code.google.com/p/protobuf/][protobuf]] installed.
+You can then install the 'proto' package with [[https://golang.org/cmd/goinstall/][goinstall]]:
goinstall goprotobuf.googlecode.com/hg/proto
@@ -21,6 +32,15 @@
For more detail see the project's [[http://code.google.com/p/goprotobuf/source/browse/README][README]] file.
-This is one of a growing list of third-party [[http://godashboard.appspot.com/package][Go projects]]. Since the announcement of goprotobuf, the X Go bindings have been spun off from the standard library to the [[http://code.google.com/p/x-go-binding/][x-go-binding]] project, and work has begun on a [[http://www.freetype.org/][Freetype]] port, [[http://code.google.com/p/freetype-go/][freetype-go]]. Other popular third-party projects include the lightweight web framework [[http://github.com/hoisie/web.go][web.go]], and the Go GTK bindings [[http://github.com/mattn/go-gtk][gtk-go]].
+This is one of a growing list of third-party [[http://godashboard.appspot.com/package][Go projects]].
+Since the announcement of goprotobuf, the X Go bindings have been spun off
+from the standard library to the [[http://code.google.com/p/x-go-binding/][x-go-binding]] project,
+and work has begun on a [[http://www.freetype.org/][Freetype]] port,
+[[http://code.google.com/p/freetype-go/][freetype-go]].
+Other popular third-party projects include the lightweight web framework
+[[http://github.com/hoisie/web.go][web.go]],
+and the Go GTK bindings [[http://github.com/mattn/go-gtk][gtk-go]].
-We wish to encourage the development of other useful packages by the open source community. If you're working on something, don't keep it to yourself - let us know through our mailing list [[http://groups.google.com/group/golang-nuts][golang-nuts]].
+We wish to encourage the development of other useful packages by the open source community.
+If you're working on something, don't keep it to yourself - let us know
+through our mailing list [[http://groups.google.com/group/golang-nuts][golang-nuts]].
diff --git a/content/two-go-talks-lexical-scanning-in-go-and.article b/content/two-go-talks-lexical-scanning-in-go-and.article
index bbd372f..2965af0 100644
--- a/content/two-go-talks-lexical-scanning-in-go-and.article
+++ b/content/two-go-talks-lexical-scanning-in-go-and.article
@@ -8,14 +8,25 @@
On Tuesday night Rob Pike and Andrew Gerrand each presented at the [[http://www.sydney-gtug.org/][Sydney Google Technology User Group]].
-Rob's talk, "[[http://www.youtube.com/watch?v=HxaD_trXwRE][Lexical Scanning in Go]]", discusses the design of a particularly interesting and idiomatic piece of Go code, the lexer component of the new [[https://golang.org/pkg/exp/template/][template package.]]
+Rob's talk, "[[http://www.youtube.com/watch?v=HxaD_trXwRE][Lexical Scanning in Go]]",
+discusses the design of a particularly interesting and idiomatic piece of Go code,
+the lexer component of the new [[https://golang.org/pkg/exp/template/][template package.]]
.iframe //www.youtube.com/embed/HxaD_trXwRE 345 560
-The slides are [[http://cuddle.googlecode.com/hg/talk/lex.html][available here]]. The new template package is available as [[https://golang.org/pkg/exp/template/][exp/template]] in Go release r59. In a future release it will replace the old template package.
+The slides are [[http://cuddle.googlecode.com/hg/talk/lex.html][available here]].
+The new template package is available as [[https://golang.org/pkg/exp/template/][exp/template]] in Go release r59.
+In a future release it will replace the old template package.
-Andrew's talk, "[[http://www.youtube.com/watch?v=HQtLRqqB-Kk][Cuddle: an App Engine Demo]]", describes the construction of a simple real-time chat application that uses App Engine's [[http://code.google.com/appengine/docs/go/datastore/overview.html][Datastore]], [[http://code.google.com/appengine/docs/go/channel/overview.html][Channel]], and [[http://code.google.com/appengine/docs/go/datastore/memcache.html][Memcache]] APIs. It also includes a question and answer session that covers [[http://code.google.com/appengine/docs/go/gettingstarted/][Go for App Engine]] and Go more generally.
+Andrew's talk, "[[http://www.youtube.com/watch?v=HQtLRqqB-Kk][Cuddle: an App Engine Demo]]",
+describes the construction of a simple real-time chat application that uses
+App Engine's [[http://code.google.com/appengine/docs/go/datastore/overview.html][Datastore]],
+[[http://code.google.com/appengine/docs/go/channel/overview.html][Channel]],
+and [[http://code.google.com/appengine/docs/go/datastore/memcache.html][Memcache]] APIs.
+It also includes a question and answer session that covers [[http://code.google.com/appengine/docs/go/gettingstarted/][Go for App Engine]]
+and Go more generally.
.iframe //www.youtube.com/embed/HQtLRqqB-Kk 345 560
-The slides are [[http://cuddle.googlecode.com/hg/talk/index.html][available here]]. The code is available at the [[http://code.google.com/p/cuddle/][cuddle Google Code project]].
+The slides are [[http://cuddle.googlecode.com/hg/talk/index.html][available here]].
+The code is available at the [[http://code.google.com/p/cuddle/][cuddle Google Code project]].
diff --git a/content/two-recent-go-articles.article b/content/two-recent-go-articles.article
index c006fe8..f6acc05 100644
--- a/content/two-recent-go-articles.article
+++ b/content/two-recent-go-articles.article
@@ -10,7 +10,11 @@
* Go at Google
-In October last year, Rob Pike presented a keynote at the ACM [[http://splashcon.org/2012/][SPLASH]] conference in Tucson. The talk, titled [[https://talks.golang.org/2012/splash.slide][Go at Google]], was a comprehensive discussion of the motivations behind Go. Rob later expanded on his talk to produce an essay titled [[http://talks.golang.org/2012/splash.article][Go at Google: Language Design in the Service of Software Engineering]]. Here is the abstract:
+In October last year, Rob Pike presented a keynote at the ACM [[http://splashcon.org/2012/][SPLASH]] conference in Tucson.
+The talk, titled [[https://talks.golang.org/2012/splash.slide][Go at Google]],
+was a comprehensive discussion of the motivations behind Go.
+Rob later expanded on his talk to produce an essay titled [[http://talks.golang.org/2012/splash.article][Go at Google: Language Design in the Service of Software Engineering]].
+Here is the abstract:
The Go programming language was conceived in late 2007 as an
answer to some of the problems we were seeing developing
@@ -35,12 +39,24 @@
systems grow, and robustness across the boundaries between
components.
-This article explains how these issues were addressed while building an efficient, compiled programming language that feels lightweight and pleasant. Examples and explanations will be taken from the real-world problems faced at Google.
+This article explains how these issues were addressed while building an efficient,
+compiled programming language that feels lightweight and pleasant.
+Examples and explanations will be taken from the real-world problems faced at Google.
-If you have wondered about the design decisions behind Go, you may find your questions answered by [[https://talks.golang.org/2012/splash.article][the essay]]. It is recommended reading for both new and experienced Go programmers.
+If you have wondered about the design decisions behind Go,
+you may find your questions answered by [[https://talks.golang.org/2012/splash.article][the essay]].
+It is recommended reading for both new and experienced Go programmers.
* Go at the Google Developers Academy
-At Google I/O 2012 the Google Developers team [[http://googledevelopers.blogspot.com.au/2012/06/google-launches-new-developer-education.html][launched]] the [[https://developers.google.com/academy/][Google Developers Academy]], a program that provides training materials on Google technologies. Go is one of those technologies and we're pleased to announce the first GDA article featuring Go front and center:
+At Google I/O 2012 the Google Developers team [[http://googledevelopers.blogspot.com.au/2012/06/google-launches-new-developer-education.html][launched]] the [[https://developers.google.com/academy/][Google Developers Academy]],
+a program that provides training materials on Google technologies.
+Go is one of those technologies and we're pleased to announce the first
+GDA article featuring Go front and center:
-[[https://developers.google.com/appengine/training/go-plus-appengine/][Getting Started with Go, App Engine and Google+ API]] is an introduction to writing web applications in Go. It demonstrates how to build and deploy App Engine applications and make calls to the Google+ API using the Google APIs Go Client. This is a great entry point for Go programmers eager to get started with Google's developer ecosystem.
+[[https://developers.google.com/appengine/training/go-plus-appengine/][Getting Started with Go, App Engine and Google+ API]] is
+an introduction to writing web applications in Go.
+It demonstrates how to build and deploy App Engine applications and make
+calls to the Google+ API using the Google APIs Go Client.
+This is a great entry point for Go programmers eager to get started with
+Google's developer ecosystem.
diff --git a/content/two-recent-go-talks.article b/content/two-recent-go-talks.article
index 8e72336..0ae7120 100644
--- a/content/two-recent-go-talks.article
+++ b/content/two-recent-go-talks.article
@@ -6,15 +6,24 @@
* Introduction
-Late last year I wrote a couple of Go talks and presented them at [[http://thestrangeloop.com/][Strange Loop]], [[http://oredev.com][Øredev]], and various other venues. The talks are designed to give insight into the practice of Go programming, each describing the construction of a real program and demonstrating the power and depth of the Go language and its libraries and tools.
+Late last year I wrote a couple of Go talks and presented them at [[http://thestrangeloop.com/][Strange Loop]],
+[[http://oredev.com][Øredev]], and various other venues.
+The talks are designed to give insight into the practice of Go programming,
+each describing the construction of a real program and demonstrating the
+power and depth of the Go language and its libraries and tools.
The following videos are, in my opinion, the best recordings of these talks.
* Go: a simple programming environment
-Go is a general-purpose language that bridges the gap between efficient statically typed languages and productive dynamic language. But it’s not just the language that makes Go special – Go has broad and consistent standard libraries and powerful but simple tools.
+Go is a general-purpose language that bridges the gap between efficient
+statically typed languages and productive dynamic language.
+But it’s not just the language that makes Go special – Go has broad
+and consistent standard libraries and powerful but simple tools.
-This talk gives an introduction to Go, followed by a tour of some real programs that demonstrate the power, scope, and simplicity of the Go programming environment.
+This talk gives an introduction to Go, followed by a tour of some real programs
+that demonstrate the power,
+scope, and simplicity of the Go programming environment.
.iframe //player.vimeo.com/video/53221558?badge=0 281 500
@@ -22,7 +31,14 @@
* Go: code that grows with grace
-One of Go's key design goals is code adaptability; that it should be easy to take a simple design and build upon it in a clean and natural way. In this talk I describe a simple "chat roulette" server that matches pairs of incoming TCP connections, and then use Go's concurrency mechanisms, interfaces, and standard library to extend it with a web interface and other features. While the function of the program changes dramatically, Go's flexibility preserves the original design as it grows.
+One of Go's key design goals is code adaptability;
+that it should be easy to take a simple design and build upon it in a clean and natural way.
+In this talk I describe a simple "chat roulette" server that matches pairs
+of incoming TCP connections,
+and then use Go's concurrency mechanisms,
+interfaces, and standard library to extend it with a web interface and other features.
+While the function of the program changes dramatically,
+Go's flexibility preserves the original design as it grows.
.iframe //player.vimeo.com/video/53221560?badge=0 281 500
diff --git a/content/upcoming-google-io-go-events.article b/content/upcoming-google-io-go-events.article
index 30868bf..472ea34 100644
--- a/content/upcoming-google-io-go-events.article
+++ b/content/upcoming-google-io-go-events.article
@@ -5,12 +5,25 @@
* Introduction
-[[https://googleblog.blogspot.com/2010/01/google-io-2010-now-open-for.html][Google I/O 2010]] is happening next week at the Moscone Centre in San Francisco. Those of you with tickets will be able to catch some of the Go team both at I/O and at Bootcamp. In reverse-chronological order:
+[[https://googleblog.blogspot.com/2010/01/google-io-2010-now-open-for.html][Google I/O 2010]]
+is happening next week at the Moscone Centre in San Francisco.
+Those of you with tickets will be able to catch some of the Go team both
+at I/O and at Bootcamp.
+In reverse-chronological order:
-Rob Pike and Russ Cox will be presenting a [[https://www.youtube.com/watch?v=jgVhBThJdXc][Go Programming]] talk on Thursday at 10.15am. This session takes a detailed look at how Go differs from other languages in a practical sense. Through a series of examples, they will demonstrate various features of Go and the ways in which they affect program design.
+Rob Pike and Russ Cox will be presenting a [[https://www.youtube.com/watch?v=jgVhBThJdXc][Go Programming]]
+talk on Thursday at 10.15am.
+This session takes a detailed look at how Go differs from other languages
+in a practical sense.
+Through a series of examples, they will demonstrate various features of
+Go and the ways in which they affect program design.
-Several members of the Go team will be at the Go cube during Office Hours on Wednesday between 12pm and 2:30pm. Come by to have your Go questions answered by the experts.
+Several members of the Go team will be at the Go cube during Office Hours
+on Wednesday between 12pm and 2:30pm.
+Come by to have your Go questions answered by the experts.
-At Bootcamp on Tuesday at 4.15pm, Andrew Gerrand will be giving an introductory talk about Go. The session will give an overview of the problems that motivated us to build a new language, and the ways in which Go addresses those problems.
+At Bootcamp on Tuesday at 4.15pm, Andrew Gerrand will be giving an introductory talk about Go.
+The session will give an overview of the problems that motivated us to build a new language,
+and the ways in which Go addresses those problems.
If you're coming to I/O, we look forward to seeing you there!
diff --git a/content/wire.article b/content/wire.article
index 6e72025..40b8f33 100644
--- a/content/wire.article
+++ b/content/wire.article
@@ -5,41 +5,101 @@
* Overview
-The Go team recently [[https://blog.golang.org/go-cloud][announced]] the open source project [[https://github.com/google/go-cloud][Go Cloud]], with portable Cloud APIs and tools for [[https://cloud.google.com/open-cloud/][open cloud]] development. This post goes into more detail about Wire, a dependency injection tool used in Go Cloud.
+The Go team recently [[https://blog.golang.org/go-cloud][announced]] the
+open source project [[https://github.com/google/go-cloud][Go Cloud]],
+with portable Cloud APIs and tools for [[https://cloud.google.com/open-cloud/][open cloud]] development.
+This post goes into more detail about Wire,
+a dependency injection tool used in Go Cloud.
* What problem does Wire solve?
-[[https://en.wikipedia.org/wiki/Dependency_injection][Dependency injection]] is a standard technique for producing flexible and loosely coupled code, by explicitly providing components with all of the dependencies they need to work. In Go, this often takes the form of passing dependencies to constructors:
+[[https://en.wikipedia.org/wiki/Dependency_injection][Dependency injection]]
+is a standard technique for producing flexible and loosely coupled code,
+by explicitly providing components with all of the dependencies they need to work.
+In Go, this often takes the form of passing dependencies to constructors:
// NewUserStore returns a UserStore that uses cfg and db as dependencies.
func NewUserStore(cfg *Config, db *mysql.DB) (*UserStore, error) {...}
-This technique works great at small scale, but larger applications can have a complex graph of dependencies, resulting in a big block of initialization code that's order-dependent but otherwise not very interesting. It's often hard to break up this code cleanly, especially because some dependencies are used multiple times. Replacing one implementation of a service with another can be painful because it involves modifying the dependency graph by adding a whole new set of dependencies (and their dependencies...), and removing unused old ones. In practice, making changes to initialization code in applications with large dependency graphs is tedious and slow.
+This technique works great at small scale,
+but larger applications can have a complex graph of dependencies,
+resulting in a big block of initialization code that's order-dependent but
+otherwise not very interesting.
+It's often hard to break up this code cleanly,
+especially because some dependencies are used multiple times.
+Replacing one implementation of a service with another can be painful because
+it involves modifying the dependency graph by adding a whole new set of
+dependencies (and their dependencies...),
+and removing unused old ones.
+In practice, making changes to initialization code in applications with
+large dependency graphs is tedious and slow.
-Dependency injection tools like Wire aim to simplify the management of initialization code. You describe your services and their dependencies, either as code or as configuration, then Wire processes the resulting graph to figure out ordering and how to pass each service what it needs. Make changes to an application's dependencies by changing a function signature or adding or removing an initializer, and then let Wire do the tedious work of generating initialization code for the entire dependency graph.
+Dependency injection tools like Wire aim to simplify the management of initialization code.
+You describe your services and their dependencies,
+either as code or as configuration, then Wire processes the resulting graph
+to figure out ordering and how to pass each service what it needs.
+Make changes to an application's dependencies by changing a function signature
+or adding or removing an initializer,
+and then let Wire do the tedious work of generating initialization code
+for the entire dependency graph.
* Why is this part of Go Cloud?
-Go Cloud's goal is to make it easier to write portable Cloud applications by providing idiomatic Go APIs for useful Cloud services. For example, [[https://godoc.org/github.com/google/go-cloud/blob][blob.Bucket]] provides a storage API with implementations for Amazon's S3 and Google Cloud Storage (GCS); applications written using `blob.Bucket` can swap implementations without changing their application logic. However, the initialization code is inherently provider-specific, and each provider has a different set of dependencies.
+Go Cloud's goal is to make it easier to write portable Cloud applications
+by providing idiomatic Go APIs for useful Cloud services.
+For example, [[https://godoc.org/github.com/google/go-cloud/blob][blob.Bucket]]
+provides a storage API with implementations for Amazon's S3 and Google Cloud Storage (GCS);
+applications written using `blob.Bucket` can swap implementations without
+changing their application logic.
+However, the initialization code is inherently provider-specific,
+and each provider has a different set of dependencies.
-For example, [[https://godoc.org/github.com/google/go-cloud/blob/gcsblob#OpenBucket][constructing a GCS `blob.Bucket`]] requires a `gcp.HTTPClient`, which eventually requires `google.Credentials`, while [[https://godoc.org/github.com/google/go-cloud/blob/s3blob][constructing one for S3]] requires an `aws.Config`, which eventually requires AWS credentials. Thus, updating an application to use a different `blob.Bucket` implementation involves exactly the kind of tedious update to the dependency graph that we described above. The driving use case for Wire is to make it easy to swap implementations of Go Cloud portable APIs, but it's also a general-purpose tool for dependency injection.
+For example, [[https://godoc.org/github.com/google/go-cloud/blob/gcsblob#OpenBucket][constructing a GCS `blob.Bucket`]]
+requires a `gcp.HTTPClient`,
+which eventually requires `google.Credentials`,
+while [[https://godoc.org/github.com/google/go-cloud/blob/s3blob][constructing one for S3]]
+requires an `aws.Config`,
+which eventually requires AWS credentials.
+Thus, updating an application to use a different `blob.Bucket` implementation
+involves exactly the kind of tedious update to the dependency graph that we described above.
+The driving use case for Wire is to make it easy to swap implementations
+of Go Cloud portable APIs,
+but it's also a general-purpose tool for dependency injection.
* Hasn't this been done already?
-There are a number of dependency injection frameworks out there. For Go, [[https://github.com/uber-go/dig][Uber's dig]] and [[https://github.com/facebookgo/inject][Facebook's inject]] both use reflection to do runtime dependency injection. Wire was primarily inspired by Java's [[https://google.github.io/dagger/][Dagger 2]], and uses code generation rather than reflection or [[https://en.wikipedia.org/wiki/Service_locator_pattern][service locators]].
+There are a number of dependency injection frameworks out there.
+For Go, [[https://github.com/uber-go/dig][Uber's dig]] and [[https://github.com/facebookgo/inject][Facebook's inject]]
+both use reflection to do runtime dependency injection.
+Wire was primarily inspired by Java's [[https://google.github.io/dagger/][Dagger 2]],
+and uses code generation rather than reflection or [[https://en.wikipedia.org/wiki/Service_locator_pattern][service locators]].
We think this approach has several advantages:
-- Runtime dependency injection can be hard to follow and debug when the dependency graph gets complex. Using code generation means that the initialization code that's executed at runtime is regular, idiomatic Go code that's easy to understand and debug. Nothing is obfuscated by an intervening framework doing "magic". In particular, problems like forgetting a dependency become compile-time errors, not run-time errors.
-- Unlike [[https://en.wikipedia.org/wiki/Service_locator_pattern][service locators]], there's no need to make up arbitrary names or keys to register services. Wire uses Go types to connect components with their dependencies.
-- It's easier to avoid dependency bloat. Wire's generated code will only import the dependencies you need, so your binary won't have unused imports. Runtime dependency injectors can't identify unused dependencies until runtime.
+- Runtime dependency injection can be hard to follow and debug when the
+ dependency graph gets complex.
+ Using code generation means that the initialization code that's executed
+ at runtime is regular,
+ idiomatic Go code that's easy to understand and debug.
+ Nothing is obfuscated by an intervening framework doing "magic".
+ In particular, problems like forgetting a dependency become compile-time errors,
+ not run-time errors.
+- Unlike [[https://en.wikipedia.org/wiki/Service_locator_pattern][service locators]],
+ there's no need to make up arbitrary names or keys to register services.
+ Wire uses Go types to connect components with their dependencies.
+- It's easier to avoid dependency bloat. Wire's generated code will only
+ import the dependencies you need,
+ so your binary won't have unused imports.
+ Runtime dependency injectors can't identify unused dependencies until runtime.
- Wire's dependency graph is knowable statically, which provides opportunities for tooling and visualization.
* How does it work?
Wire has two basic concepts: providers and injectors.
-_Providers_ are ordinary Go functions that "provide" values given their dependencies, which are described simply as parameters to the function. Here's some sample code that defines three providers:
+_Providers_ are ordinary Go functions that "provide" values given their dependencies,
+which are described simply as parameters to the function.
+Here's some sample code that defines three providers:
// NewUserStore is the same function we saw above; it is a provider for UserStore,
// with dependencies on *Config and *mysql.DB.
@@ -51,11 +111,16 @@
// NewDB is a provider for *mysql.DB based on some connection info.
func NewDB(info *ConnectionInfo) (*mysql.DB, error) {...}
-Providers that are commonly used together can be grouped into `ProviderSets`. For example, it's common to use a default `*Config` when creating a `*UserStore`, so we can group `NewUserStore` and `NewDefaultConfig` in a `ProviderSet`:
+Providers that are commonly used together can be grouped into `ProviderSets`.
+For example, it's common to use a default `*Config` when creating a `*UserStore`,
+so we can group `NewUserStore` and `NewDefaultConfig` in a `ProviderSet`:
var UserStoreSet = wire.ProviderSet(NewUserStore, NewDefaultConfig)
-_Injectors_ are generated functions that call providers in dependency order. You write the injector's signature, including any needed inputs as arguments, and insert a call to `wire.Build` with the list of providers or provider sets that are needed to construct the end result:
+_Injectors_ are generated functions that call providers in dependency order.
+You write the injector's signature, including any needed inputs as arguments,
+and insert a call to `wire.Build` with the list of providers or provider
+sets that are needed to construct the end result:
func initUserStore() (*UserStore, error) {
// We're going to get an error, because NewDB requires a *ConnectionInfo
@@ -70,7 +135,10 @@
wire.go:2:10: inject initUserStore: no provider found for ConnectionInfo (required by provider of *mysql.DB)
wire: generate failed
-Oops! We didn't include a `ConnectionInfo` or tell Wire how to build one. Wire helpfully tells us the line number and types involved. We can either add a provider for it to `wire.Build`, or add it as an argument:
+Oops! We didn't include a `ConnectionInfo` or tell Wire how to build one.
+Wire helpfully tells us the line number and types involved.
+We can either add a provider for it to `wire.Build`,
+or add it as an argument:
func initUserStore(info ConnectionInfo) (*UserStore, error) {
wire.Build(UserStoreSet, NewDB)
@@ -97,14 +165,30 @@
return userStore, nil
}
-Any non-injector declarations are copied into the generated file. There is no dependency on Wire at runtime: all of the written code is just normal Go code.
+Any non-injector declarations are copied into the generated file.
+There is no dependency on Wire at runtime:
+all of the written code is just normal Go code.
-As you can see, the output is very close to what a developer would write themselves. This was a trivial example with just three components, so writing the initializer by hand wouldn't be too painful, but Wire saves a lot of manual toil for components and applications with more complex dependency graphs.
+As you can see, the output is very close to what a developer would write themselves.
+This was a trivial example with just three components,
+so writing the initializer by hand wouldn't be too painful,
+but Wire saves a lot of manual toil for components and applications with
+more complex dependency graphs.
* How can I get involved and learn more?
-The [[https://github.com/google/wire/blob/master/README.md][Wire README]] goes into more detail about how to use Wire and its more advanced features. There's also a [[https://github.com/google/wire/tree/master/_tutorial][tutorial]] that walks through using Wire in a simple application.
+The [[https://github.com/google/wire/blob/master/README.md][Wire README]]
+goes into more detail about how to use Wire and its more advanced features.
+There's also a [[https://github.com/google/wire/tree/master/_tutorial][tutorial]]
+that walks through using Wire in a simple application.
-We appreciate any input you have about your experience with Wire! [[https://github.com/google/wire][Wire's]] development is conducted on GitHub, so you can [[https://github.com/google/wire/issues/new/choose][file an issue]] to tell us what could be better. For updates and discussion about the project, join [[https://groups.google.com/forum/#!forum/go-cloud][the Go Cloud mailing list]].
+We appreciate any input you have about your experience with Wire!
+[[https://github.com/google/wire][Wire's]] development is conducted on GitHub,
+so you can [[https://github.com/google/wire/issues/new/choose][file an issue]]
+to tell us what could be better.
+For updates and discussion about the project,
+join [[https://groups.google.com/forum/#!forum/go-cloud][the Go Cloud mailing list]].
-Thank you for taking the time to learn about Go Cloud's Wire. We’re excited to work with you to make Go the language of choice for developers building portable cloud applications.
+Thank you for taking the time to learn about Go Cloud's Wire.
+We’re excited to work with you to make Go the language of choice for developers
+building portable cloud applications.
diff --git a/content/wrap.go b/content/wrap.go
new file mode 100644
index 0000000..316eb91
--- /dev/null
+++ b/content/wrap.go
@@ -0,0 +1,189 @@
+// Copyright 2020 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// +build ignore
+
+// Wrap wraps long lines intelligently.
+//
+// Usage:
+//
+// go run wrap.go [-w] [file ...]
+//
+// By default, wrap prints the line-wrapped version of the input files to standard output.
+// If no input file is listed, standard input is used.
+//
+// The -w flag causes wrap to update the files in place, overwriting each with its
+// line-wrapped equivalent. Wrap leaves the file unchanged if only a few lines
+// need wrapping.
+//
+// Examples
+//
+// go run -w wrap.go your.article
+// go run -w wrap.go *.article
+//
+package main
+
+import (
+ "flag"
+ "fmt"
+ "io"
+ "io/ioutil"
+ "log"
+ "os"
+ "strings"
+)
+
+func usage() {
+ fmt.Fprintf(os.Stderr, "usage: wrap [-w] [file ...]\n")
+ os.Exit(2)
+}
+
+var writeBack = flag.Bool("w", false, "write conversions back to original files")
+var exitStatus = 0
+
+func main() {
+ log.SetPrefix("wrap: ")
+ log.SetFlags(0)
+ flag.Usage = usage
+ flag.Parse()
+
+ args := flag.Args()
+ if len(args) == 0 {
+ if *writeBack {
+ log.Fatalf("cannot use -w with standard input")
+ }
+ convert(os.Stdin, "")
+ return
+ }
+
+ for _, arg := range args {
+ f, err := os.Open(arg)
+ if err != nil {
+ log.Print(err)
+ exitStatus = 1
+ continue
+ }
+ target := ""
+ if *writeBack {
+ target = arg
+ }
+ err = convert(f, target)
+ f.Close()
+ if err != nil {
+ log.Print(err)
+ exitStatus = 1
+ }
+ }
+ os.Exit(exitStatus)
+}
+
+// convert reads content from r and line-wraps it.
+// If target is the empty string, convert writes the wrapped result to standard output.
+// If target is non-empty and there were more than a few line wraps needed,
+// convert writes the result to the file named by target.
+func convert(r io.Reader, target string) error {
+ data, err := ioutil.ReadAll(r)
+ if err != nil {
+ return err
+ }
+ changes := 0
+ lines := strings.Split(string(data), "\n")
+ for i, line := range lines {
+ if len(line) < 80 {
+ continue
+ }
+ switch line[0] {
+ case '.', '#', ':', '\t', ' ':
+ continue
+ }
+ w := wrap(line)
+ if line != w {
+ if strings.HasPrefix(line, "- ") {
+ w = strings.Replace(w, "\n", "\n ", -1)
+ }
+ changes += strings.Count(w, "\n")
+ lines[i] = w
+ }
+ }
+ wrapped := []byte(strings.Join(lines, "\n"))
+
+ if target == "" {
+ os.Stdout.Write(wrapped)
+ return nil
+ }
+
+ // Don't rewrite if not much changed.
+ if changes < 5 {
+ return nil
+ }
+ return ioutil.WriteFile(target, wrapped, 0666)
+}
+
+func wrap(text string) string {
+ if len(text) < 120 {
+ return text
+ }
+ // Wrap after sentence boundaries when possible.
+ // See https://rhodesmill.org/brandon/2012/one-sentence-per-line/.
+ // Note: wrapAt guarantees line[i] == ' '.
+ text = wrapAt(text, func(line string, i int) bool {
+ return i > 40 && i+20 < len(line) &&
+ (line[i-1] == '.' || line[i-1] == '!') && (line[i+1] == ' ' || !('a' <= line[i+1] && line[i+1] <= 'z'))
+ })
+
+ // Wrap after phrase boundaries next.
+ text = wrapAt(text, func(line string, i int) bool {
+ return i > 40 && i+20 < len(line) && (line[i-1] == ';' || line[i-1] == ':')
+ })
+ text = wrapAt(text, func(line string, i int) bool {
+ return i > 40 && i+20 < len(line) && line[i-1] == ','
+ })
+
+ // Wrap long lines that are left at spaces.
+ text = wrapAt(text, func(line string, i int) bool {
+ return i > 70 && i+20 < len(line)
+ })
+
+ return text
+}
+
+// wrapAt wraps long lines in text, returning the result.
+// It calls canWrapAt(line, start, i) to ask whether the given line
+// should be wrapped just before offset i; line[i] is known to be a space.
+func wrapAt(text string, canWrapAt func(line string, i int) bool) string {
+ lines := strings.Split(text, "\n")
+ for i, line := range lines {
+ var out string
+ start := 0
+ brackets := 0
+ for i := 0; i < len(line); {
+ if line[i] == '[' {
+ brackets++
+ }
+ if line[i] == ']' {
+ brackets--
+ }
+ if brackets == 0 && line[i] == ' ' && i+1 < len(line) && line[i+1] != '-' && canWrapAt(line[start:], i-start) {
+ out += trimRight(line[start:i]) + "\n"
+ i++
+ for i < len(line) && line[i] == ' ' {
+ i++
+ }
+ start = i
+ continue
+ }
+ i++
+ }
+ out += trimRight(line[start:])
+ lines[i] = out
+ }
+ return strings.Join(lines, "\n")
+}
+
+func trimRight(s string) string {
+ for len(s) > 0 && (s[len(s)-1] == ' ' || s[len(s)-1] == '\t') {
+ s = s[:len(s)-1]
+ }
+ return s
+}
diff --git a/content/writing-scalable-app-engine.article b/content/writing-scalable-app-engine.article
index cf020d2..c5ca023 100644
--- a/content/writing-scalable-app-engine.article
+++ b/content/writing-scalable-app-engine.article
@@ -6,12 +6,27 @@
* Introduction
-Back in May, we [[https://blog.golang.org/2011/05/go-and-google-app-engine.html][announced]] the Go runtime for App Engine. Since then, we've opened it up for everyone to use, added many new APIs, and improved performance. We have been thrilled by all the interesting ways that people are using Go on App Engine.
-One of the key benefits of the Go runtime, apart from working in a fantastic language, is that it has high performance. Go applications compile to native code, with no interpreter or virtual machine getting between your program and the machine.
+Back in May, we [[https://blog.golang.org/2011/05/go-and-google-app-engine.html][announced]]
+the Go runtime for App Engine.
+Since then, we've opened it up for everyone to use,
+added many new APIs, and improved performance.
+We have been thrilled by all the interesting ways that people are using Go on App Engine.
+One of the key benefits of the Go runtime,
+apart from working in a fantastic language,
+is that it has high performance.
+Go applications compile to native code, with no interpreter or virtual machine
+getting between your program and the machine.
-Making your web application fast is important because it is well known that a web site's latency has a measurable impact on user happiness, and [[https://googlewebmastercentral.blogspot.com/2010/04/using-site-speed-in-web-search-ranking.html][Google web search uses it as a ranking factor]]. Also announced in May was that App Engine would be [[http://googleappengine.blogspot.com/2011/05/year-ahead-for-google-app-engine.html][leaving its Preview status]] and transitioning to a [[https://www.google.com/enterprise/cloud/appengine/pricing.html][new pricing model]], providing another reason to write efficient App Engine applications.
+Making your web application fast is important because it is well known that
+a web site's latency has a measurable impact on user happiness,
+and [[https://googlewebmastercentral.blogspot.com/2010/04/using-site-speed-in-web-search-ranking.html][Google web search uses it as a ranking factor]].
+Also announced in May was that App Engine would be [[http://googleappengine.blogspot.com/2011/05/year-ahead-for-google-app-engine.html][leaving its Preview status]]
+and transitioning to a [[https://www.google.com/enterprise/cloud/appengine/pricing.html][new pricing model]],
+providing another reason to write efficient App Engine applications.
-To make it easier for Go developers using App Engine to write highly efficient, scalable applications, we recently updated some existing App Engine articles to include snippets of Go source code and to link to relevant Go documentation.
+To make it easier for Go developers using App Engine to write highly efficient,
+scalable applications, we recently updated some existing App Engine articles
+to include snippets of Go source code and to link to relevant Go documentation.
- [[http://code.google.com/appengine/articles/scaling/overview.html][Best practices for writing scalable applications]]
