diff --git a/_content/blog/context-and-structs.md b/_content/blog/context-and-structs.md index f93032fa..d9191665 100644 --- a/_content/blog/context-and-structs.md +++ b/_content/blog/context-and-structs.md @@ -5,7 +5,6 @@ by: - Jean de Klerk, Matt T. Proud tags: - context -- cancelation - cancellation --- @@ -70,7 +69,7 @@ The `(*Worker).Fetch` and `(*Worker).Process` method both use a context stored i The API is also much more confusing to users compared to the pass-as-argument approach. Users might ask themselves: -- Since `New` takes a `context.Context`, is the constructor doing work that needs cancelation or deadlines? +- Since `New` takes a `context.Context`, is the constructor doing work that needs cancellation or deadlines? - Does the `context.Context` passed in to `New` apply to work in `(*Worker).Fetch` and `(*Worker).Process`? Neither? One but not the other? The API would need a good deal of documentation to explicitly tell the user exactly what the `context.Context` is used for. The user might also have to read code rather than being able to rely on the structure of the API conveys. @@ -142,6 +141,6 @@ func (c *Client) CallContext(ctx context.Context) error { Context makes it easy to propagate important cross-library and cross-API information down a calling stack. But, it must be used consistently and clearly in order to remain comprehensible, easy to debug, and effective. -When passed as the first argument in a method rather than stored in a struct type, users can take full advantage of its extensibility in order to build a powerful tree of cancelation, deadline, and metadata information through the call stack. And, best of all, its scope is clearly understood when it's passed in as an argument, leading to clear comprehension and debuggability up and down the stack. +When passed as the first argument in a method rather than stored in a struct type, users can take full advantage of its extensibility in order to build a powerful tree of cancellation, deadline, and metadata information through the call stack. And, best of all, its scope is clearly understood when it's passed in as an argument, leading to clear comprehension and debuggability up and down the stack. When designing an API with context, remember the advice: pass `context.Context` in as an argument; don't store it in structs. diff --git a/_content/blog/context.md b/_content/blog/context.md index a5c004c9..c3f5c780 100644 --- a/_content/blog/context.md +++ b/_content/blog/context.md @@ -5,7 +5,6 @@ by: - Sameer Ajmani tags: - concurrency -- cancelation - cancellation - context summary: An introduction to the Go context package. @@ -24,7 +23,7 @@ request should exit quickly so the system can reclaim any resources they are using. At Google, we developed a `context` package that makes it easy to pass -request-scoped values, cancelation signals, and deadlines across API boundaries +request-scoped values, cancellation signals, and deadlines across API boundaries to all the goroutines involved in handling a request. The package is publicly available as [context](/pkg/context). @@ -40,15 +39,15 @@ The core of the `context` package is the `Context` type: (This description is condensed; the [godoc](/pkg/context) is authoritative.) -The `Done` method returns a channel that acts as a cancelation signal to +The `Done` method returns a channel that acts as a cancellation signal to functions running on behalf of the `Context`: when the channel is closed, the functions should abandon their work and return. The `Err` method returns an error indicating why the `Context` was canceled. -The [Pipelines and Cancelation](/blog/pipelines) article discusses the `Done` +The [Pipelines and Cancellation](/blog/pipelines) article discusses the `Done` channel idiom in more detail. A `Context` does _not_ have a `Cancel` method for the same reason the `Done` -channel is receive-only: the function receiving a cancelation signal is usually +channel is receive-only: the function receiving a cancellation signal is usually not the one that sends the signal. In particular, when a parent operation starts goroutines for sub-operations, those sub-operations should not be able to cancel the parent. @@ -204,9 +203,9 @@ In [gorilla.go](context/gorilla/gorilla.go), we provide a `Context` implementation whose `Value` method returns the values associated with a specific HTTP request in the Gorilla package. -Other packages have provided cancelation support similar to `Context`. +Other packages have provided cancellation support similar to `Context`. For example, [Tomb](https://godoc.org/gopkg.in/tomb.v2) provides a `Kill` -method that signals cancelation by closing a `Dying` channel. +method that signals cancellation by closing a `Dying` channel. `Tomb` also provides methods to wait for those goroutines to exit, similar to `sync.WaitGroup`. In [tomb.go](context/tomb/tomb.go), we provide a `Context` implementation that @@ -219,13 +218,13 @@ At Google, we require that Go programmers pass a `Context` parameter as the first argument to every function on the call path between incoming and outgoing requests. This allows Go code developed by many different teams to interoperate well. -It provides simple control over timeouts and cancelation and ensures that +It provides simple control over timeouts and cancellation and ensures that critical values like security credentials transit Go programs properly. Server frameworks that want to build on `Context` should provide implementations of `Context` to bridge between their packages and those that expect a `Context` parameter. Their client libraries would then accept a `Context` from the calling code. -By establishing a common interface for request-scoped data and cancelation, +By establishing a common interface for request-scoped data and cancellation, `Context` makes it easier for package developers to share code for creating scalable services. diff --git a/_content/blog/context/interface.go b/_content/blog/context/interface.go index 838c7da8..ff585039 100644 --- a/_content/blog/context/interface.go +++ b/_content/blog/context/interface.go @@ -1,10 +1,11 @@ +//go:build OMIT // +build OMIT package context import "time" -// A Context carries a deadline, cancelation signal, and request-scoped values +// A Context carries a deadline, cancellation signal, and request-scoped values // across API boundaries. Its methods are safe for simultaneous use by multiple // goroutines. type Context interface { diff --git a/_content/blog/context/server/server.go b/_content/blog/context/server/server.go index ebee9a1b..68bf37a4 100644 --- a/_content/blog/context/server/server.go +++ b/_content/blog/context/server/server.go @@ -1,3 +1,4 @@ +//go:build OMIT // +build OMIT // The server program issues Google search requests and demonstrates the use of diff --git a/_content/blog/go1.7.md b/_content/blog/go1.7.md index b843314c..85ee695b 100644 --- a/_content/blog/go1.7.md +++ b/_content/blog/go1.7.md @@ -38,7 +38,7 @@ Over the past few years, the [golang.org/x/net/context](https://godoc.org/golang package has proven to be essential to many Go applications. Contexts are used to great effect in applications related to networking, infrastructure, and microservices (such as [Kubernetes](http://kubernetes.io/) and [Docker](https://www.docker.com/)). -They make it easy to enable cancelation, timeouts, and passing request-scoped data. +They make it easy to enable cancellation, timeouts, and passing request-scoped data. To make use of contexts within the standard library and to encourage more extensive use, the package has been moved from the [x/net](https://godoc.org/golang.org/x/net/context/) repository to the standard library as the [context](/pkg/context/) package. diff --git a/_content/blog/go1.8.md b/_content/blog/go1.8.md index 655fa0e1..fdafce7c 100644 --- a/_content/blog/go1.8.md +++ b/_content/blog/go1.8.md @@ -29,7 +29,7 @@ The HTTP server also adds support for [graceful shutdown](/doc/go1.8#http_shutdo allowing servers to minimize downtime by shutting down only after serving all requests that are in flight. [Contexts](/pkg/context/) (added to the standard library in Go 1.7) -provide a cancelation and timeout mechanism. +provide a cancellation and timeout mechanism. Go 1.8 [adds](/doc/go1.8#more_context) support for contexts in more parts of the standard library, including the [`database/sql`](/pkg/database/sql) and [`net`](/pkg/net) packages and [`Server.Shutdown`](http://beta.golang.org/pkg/net/http/#Server.Shutdown) in the `net/http` package. diff --git a/_content/blog/pandemic.md b/_content/blog/pandemic.md index f6e10a92..f72b8e87 100644 --- a/_content/blog/pandemic.md +++ b/_content/blog/pandemic.md @@ -33,7 +33,7 @@ and our plans for Go itself. The Go community thrives on in-person conferences and meetups. We had anticipated 35 conferences this year and thousands of meetups, nearly all of which have -now changed, been postponed, or been cancelled. +now changed, been postponed, or been canceled. We’ll keep the [conferences wiki page](https://github.com/golang/go/wiki/Conferences) updated as plans change. @@ -76,7 +76,7 @@ for companies that want help adopting Go. That in-person teaching is crucial to bringing new gophers into the community; we’re incredibly grateful to the trainers for the work they do. -Unfortunately, on-site training contracts have all been cancelled +Unfortunately, on-site training contracts have all been canceled for the next few months, and the trainers in our community have lost their primary (or sole) source of income. We encourage companies to consider virtual training diff --git a/_content/doc/database/cancel-operations.md b/_content/doc/database/cancel-operations.md index f11508b9..d01efc7a 100644 --- a/_content/doc/database/cancel-operations.md +++ b/_content/doc/database/cancel-operations.md @@ -1,11 +1,11 @@ You can manage in-progress operations by using Go [`context.Context`](https://pkg.go.dev/context#Context). A `Context` is a standard Go data value that can report whether the overall operation it -represents has been cancelled and is no longer needed. By passing a +represents has been canceled and is no longer needed. By passing a `context.Context` across function calls and services in your application, those can stop working early and return an error when their processing is no longer needed. For more about `Context`, see @@ -21,10 +21,10 @@ For example, you might want to: Many APIs for Go developers include methods that take a `Context` argument, making it easier for you to use `Context` throughout your application. -### Cancelling database operations after a timeout {#timeout_cancel} +### Canceling database operations after a timeout {#timeout_cancel} You can use a `Context` to set a timeout or deadline after which an operation -will be cancelled. To derive a `Context` with a timeout or deadline, call +will be canceled. To derive a `Context` with a timeout or deadline, call [`context.WithTimeout`](https://pkg.go.dev/context#WithTimeout) or [`context.WithDeadline`](https://pkg.go.dev/context#WithDeadline). @@ -50,13 +50,13 @@ func QueryWithTimeout(ctx context.Context) { ``` When one context is derived from an outer context, as `queryCtx` is derived -from `ctx` in this example, if the outer context is cancelled, then the derived -context is automatically cancelled as well. For example, in HTTP servers, the +from `ctx` in this example, if the outer context is canceled, then the derived +context is automatically canceled as well. For example, in HTTP servers, the `http.Request.Context` method returns a context associated with the request. -That context is cancelled if the HTTP client disconnects or cancels the HTTP +That context is canceled if the HTTP client disconnects or cancels the HTTP request (possible in HTTP/2). Passing an HTTP request’s context to `QueryWithTimeout` above would cause the database query to stop early _either_ -if the overall HTTP request was cancelled or if the query took more than five +if the overall HTTP request was canceled or if the query took more than five seconds. **Note:** Always defer a call to the `cancel` function that's returned when you diff --git a/_content/doc/database/change-data.md b/_content/doc/database/change-data.md index 97b7b814..10630d15 100644 --- a/_content/doc/database/change-data.md +++ b/_content/doc/database/change-data.md @@ -11,7 +11,7 @@ instead. For more, see [Querying a database](/doc/database/querying). An `ExecContext` method works as an `Exec` method does, but with an additional `context.Context` argument, as described in -[Cancelling in-progress operations](/doc/database/cancel-operations). +[Canceling in-progress operations](/doc/database/cancel-operations). Code in the following example uses [`DB.Exec`](https://pkg.go.dev/database/sql#DB.Exec) to execute a diff --git a/_content/doc/database/execute-transactions.md b/_content/doc/database/execute-transactions.md index c81105d7..e1bd3538 100644 --- a/_content/doc/database/execute-transactions.md +++ b/_content/doc/database/execute-transactions.md @@ -105,8 +105,8 @@ for an album. Along the way, the code will: This example uses `Tx` methods that take a `context.Context` argument. This makes it possible for the function's execution – including database operations --- to be cancelled if it runs too long or the client connection closes. For -more, see [Cancelling in-progress operations](/doc/database/cancel-operations). +-- to be canceled if it runs too long or the client connection closes. For +more, see [Canceling in-progress operations](/doc/database/cancel-operations). ``` // CreateOrder creates an order for an album and returns the new order ID. diff --git a/_content/doc/database/index.md b/_content/doc/database/index.md index 05ac9c4f..ab545133 100644 --- a/_content/doc/database/index.md +++ b/_content/doc/database/index.md @@ -70,7 +70,7 @@ propagate a cancellation request through your application to the function executing an SQL statement, ensuring that resources are freed up if they're no longer needed. -For more, see [Cancelling in-progress operations](/doc/database/cancel-operations). +For more, see [Canceling in-progress operations](/doc/database/cancel-operations). ### Managed connection pool {#connection_pool} @@ -78,7 +78,7 @@ When you use the `sql.DB` database handle, you're connecting with a built-in connection pool that creates and disposes of connections according to your code's needs. A handle through `sql.DB` is the most common way to do database access with Go. For more, see -[Opening a database handle](/doc/database/open-handle). +[Opening a database handle](/doc/database/open-handle). The `database/sql` package manages the connection pool for you. However, for more advanced needs, you can set connection pool properties as described in diff --git a/_content/doc/database/querying.md b/_content/doc/database/querying.md index 92e6a59f..c36bea6b 100644 --- a/_content/doc/database/querying.md +++ b/_content/doc/database/querying.md @@ -34,7 +34,7 @@ look up data by a unique ID. If multiple rows are returned by the query, the `Scan` method discards all but the first. `QueryRowContext` works like `QueryRow` but with a `context.Context` argument. -For more, see [Cancelling in-progress operations](/doc/database/cancel-operations). +For more, see [Canceling in-progress operations](/doc/database/cancel-operations). The following example uses a query to find out if there's enough inventory to support a purchase. The SQL statement returns `true` if there's enough, `false` @@ -122,7 +122,7 @@ rows using [`Rows.Next`](https://pkg.go.dev/database/sql#Rows.Next). Each iteration calls `Scan` to copy column values into variables. `QueryContext` works like `Query` but with a `context.Context` argument. For -more, see [Cancelling in-progress operations](/doc/database/cancel-operations). +more, see [Canceling in-progress operations](/doc/database/cancel-operations). The following example executes a query to return the albums by a specified artist. The albums are returned in an `sql.Rows`. The code uses diff --git a/_content/doc/go1.7.html b/_content/doc/go1.7.html index 949fa489..575f5f88 100644 --- a/_content/doc/go1.7.html +++ b/_content/doc/go1.7.html @@ -299,13 +299,13 @@ To avoid confusion with the new -tests check, the old, unadvertised

The vet command also has a new check, -lostcancel, which detects failure to call the -cancelation function returned by the WithCancel, +cancellation function returned by the WithCancel, WithTimeout, and WithDeadline functions in Go 1.7's new context package (see below). Failure to call the function prevents the new Context -from being reclaimed until its parent is cancelled. -(The background context is never cancelled.) +from being reclaimed until its parent is canceled. +(The background context is never canceled.)

Go tool dist

@@ -388,7 +388,7 @@ substantial stack size fluctuation, or large package-level variables.

Go 1.7 moves the golang.org/x/net/context package into the standard library as context. -This allows the use of contexts for cancelation, timeouts, and passing +This allows the use of contexts for cancellation, timeouts, and passing request-scoped data in other standard library packages, including net, diff --git a/_content/doc/go1.8.html b/_content/doc/go1.8.html index 8fce957e..fc5b1803 100644 --- a/_content/doc/go1.8.html +++ b/_content/doc/go1.8.html @@ -86,7 +86,7 @@ On OpenBSD, Go now requires OpenBSD 5.9 or later.

The Plan 9 port's networking support is now much more complete and matches the behavior of Unix and Windows with respect to deadlines -and cancelation. For Plan 9 kernel requirements, see the +and cancellation. For Plan 9 kernel requirements, see the Plan 9 wiki page.

@@ -889,7 +889,7 @@ crypto/x509: return error for missing SerialNumber (CL 27238)

The new Context query methods work for all drivers, but - Context cancelation is not responsive unless the driver has been + Context cancellation is not responsive unless the driver has been updated to use them. The other features require driver support in database/sql/driver. Driver authors should review the new interfaces. Users of existing diff --git a/_content/doc/index.html b/_content/doc/index.html index a9d5e464..03d95cb9 100644 --- a/_content/doc/index.html +++ b/_content/doc/index.html @@ -151,7 +151,7 @@ including Commit and Rollback, as well as methods you use to perform common database operations.

-

Cancelling in-progress database operations

+

Canceling in-progress database operations

Using context.Context, you can have your application's function calls and services stop working early and diff --git a/_content/doc/tutorial/database-access.md b/_content/doc/tutorial/database-access.md index cd0cfb8f..3718180c 100644 --- a/_content/doc/tutorial/database-access.md +++ b/_content/doc/tutorial/database-access.md @@ -12,7 +12,7 @@ for a quick introduction. The [`database/sql`](https://pkg.go.dev/database/sql) package you'll be using includes types and functions for connecting to databases, executing -transactions, cancelling an operation in progress, and more. For more details +transactions, canceling an operation in progress, and more. For more details on using the package, see [Accessing databases](/doc/database/index). @@ -785,4 +785,4 @@ func addAlbum(alb Album) (int64, error) { } return id, nil } -``` \ No newline at end of file +``` diff --git a/_content/talks/2014/gotham-context.slide b/_content/talks/2014/gotham-context.slide index 1325b7ae..51ae3b8f 100644 --- a/_content/talks/2014/gotham-context.slide +++ b/_content/talks/2014/gotham-context.slide @@ -1,4 +1,4 @@ -Cancelation, Context, and Plumbing +Cancellation, Context, and Plumbing GothamGo 2014 Sameer Ajmani @@ -22,7 +22,7 @@ Handler code needs access to request-specific values: When the request completes or times out, its work should be canceled. -* Cancelation +* Cancellation Abandon work when the caller no longer needs the result. @@ -32,27 +32,27 @@ Abandon work when the caller no longer needs the result. Efficiently canceling unneeded work saves resources. -* Cancelation is advisory +* Cancellation is advisory -Cancelation does not stop execution or trigger panics. +Cancellation does not stop execution or trigger panics. -Cancelation informs code that its work is no longer needed. +Cancellation informs code that its work is no longer needed. -Code checks for cancelation and decides what to do: +Code checks for cancellation and decides what to do: shut down, clean up, return errors. -* Cancelation is transitive +* Cancellation is transitive .image gotham-context/transitive.svg -* Cancelation affects all APIs on the request path +* Cancellation affects all APIs on the request path -Network protocols support cancelation. +Network protocols support cancellation. - HTTP: close the connection - RPC: send a control message -APIs above network need cancelation, too. +APIs above network need cancellation, too. - Database clients - Network file system clients @@ -60,13 +60,13 @@ APIs above network need cancelation, too. And all the layers atop those, up to the UI. -*Goal:* provide a uniform cancelation API that works across package boundaries. +*Goal:* provide a uniform cancellation API that works across package boundaries. -* Cancelation APIs +* Cancellation APIs -Many Go APIs support cancelation and deadlines already. +Many Go APIs support cancellation and deadlines already. -Go APIs are synchronous, so cancelation comes from another goroutine. +Go APIs are synchronous, so cancellation comes from another goroutine. Method on the connection or client object: @@ -84,7 +84,7 @@ Method on the request object: // goroutine #2 req.Cancel() -* Cancelation APIs (continued) +* Cancellation APIs (continued) Method on the pending result object: @@ -97,7 +97,7 @@ Method on the pending result object: pending.Cancel() -Different cancelation APIs in each package are a headache. +Different cancellation APIs in each package are a headache. We need one that's independent of package or transport: @@ -109,7 +109,7 @@ We need one that's independent of package or transport: * Context -A `Context` carries a cancelation signal and request-scoped values to all functions running on behalf of the same task. It's safe for concurrent access. +A `Context` carries a cancellation signal and request-scoped values to all functions running on behalf of the same task. It's safe for concurrent access. .code gotham-context/interface.go /type Context/,/^}/ @@ -163,7 +163,7 @@ Using `close` requires care. Contexts carry request-scoped values across API boundaries. - deadline -- cancelation signal +- cancellation signal - security credentials - distributed trace IDs - operation priority @@ -322,7 +322,7 @@ More to do here. * Conclusion -Cancelation needs a uniform API across package boundaries. +Cancellation needs a uniform API across package boundaries. Retrofitting code is hard, but Go is tool-friendly. diff --git a/_content/talks/2014/gotham-context/interface.go b/_content/talks/2014/gotham-context/interface.go index 51450c58..6f8bb08f 100644 --- a/_content/talks/2014/gotham-context/interface.go +++ b/_content/talks/2014/gotham-context/interface.go @@ -1,10 +1,11 @@ +//go:build ignore && OMIT // +build ignore,OMIT package context import "time" -// A Context carries a deadline, cancelation signal, and request-scoped values +// A Context carries a deadline, cancellation signal, and request-scoped values // across API boundaries. Its methods are safe for simultaneous use by multiple // goroutines. type Context interface { diff --git a/_content/talks/2015/gotham-grpc.slide b/_content/talks/2015/gotham-grpc.slide index 7415de0c..7642b5d6 100644 --- a/_content/talks/2015/gotham-grpc.slide +++ b/_content/talks/2015/gotham-grpc.slide @@ -64,7 +64,7 @@ Ten languages: *C*, *Java*, *Go*, C++, Node.js, Python, Ruby, Objective-C, PHP, IDL: *Proto3* Transport: *HTTP2* -[[http://golang.org/x/net/context][golang.org/x/net/context]] for deadlines, cancelation, and request-scoped values +[[http://golang.org/x/net/context][golang.org/x/net/context]] for deadlines, cancellation, and request-scoped values [[http://golang.org/x/net/trace][golang.org/x/net/trace]] for real-time request traces and connection logging * gRPC users @@ -123,7 +123,7 @@ Transport: *HTTP2* RPCs block but can be canceled using a Context. -gRPC propagates cancelation from client to server. +gRPC propagates cancellation from client to server. * Backend code @@ -182,7 +182,7 @@ gRPC cancels the remaining `backend.Search` RPCs by via `ctx`: * Demo client --mode=watch - Active stream traces -- Cancelation +- Cancellation * Client code @@ -216,7 +216,7 @@ gRPC cancels the remaining `backend.Search` RPCs by via `ctx`: * gRPC extends the Go programming model over the network -Go gRPC works smoothly with goroutines, channels, and cancelation. +Go gRPC works smoothly with goroutines, channels, and cancellation. It is an excellent fit for building parallel, distributed, and streaming systems. @@ -228,7 +228,7 @@ It is an excellent fit for building parallel, distributed, and streaming systems - [[https://github.com/golang/protobuf][github.com/golang/protobuf]] - Protocol buffers - [[http://golang.org/x/net/http2][golang.org/x/net/http2]] - HTTP2 - [[http://golang.org/x/net/trace][golang.org/x/net/trace]] - Request traces and event logs -- [[http://golang.org/x/net/context][golang.org/x/net/context]] - Cancelation and request-scoped data +- [[http://golang.org/x/net/context][golang.org/x/net/context]] - Cancellation and request-scoped data - [[http://blog.golang.org/pipelines][blog.golang.org/pipelines]] - Streaming data pipelines *Thanks*to* Qi Zhao, David Symonds, Brad Fitzpatrick, and the rest. diff --git a/internal/play/proxy.go b/internal/play/proxy.go index c61a83af..443b8999 100644 --- a/internal/play/proxy.go +++ b/internal/play/proxy.go @@ -98,7 +98,7 @@ func compile(w http.ResponseWriter, r *http.Request) { func makeCompileRequest(ctx context.Context, backend string, req *Request, res *Response) error { reqJ, err := json.Marshal(req) if err != nil { - return fmt.Errorf("marshalling request: %v", err) + return fmt.Errorf("marshaling request: %v", err) } hReq, _ := http.NewRequest("POST", "https://"+backend+"/compile", bytes.NewReader(reqJ)) hReq.Header.Set("Content-Type", "application/json") @@ -116,7 +116,7 @@ func makeCompileRequest(ctx context.Context, backend string, req *Request, res * } if err := json.NewDecoder(r.Body).Decode(res); err != nil { - return fmt.Errorf("unmarshalling response: %v", err) + return fmt.Errorf("unmarshaling response: %v", err) } return nil }