[new] Using the context Go package' #2513
Conversation
docs/development/go/go-context.md
Outdated
| The main purpose of the `context` package is to define the `Context` type and | ||
| support *cancellation*. This happens because there are times where you want to | ||
| abandon what you are doing but it an elegant way. However, it would be very helpful | ||
| to be able to include some extra information about your cancelling decisions and propagate |
There was a problem hiding this comment.
Not necessarily information about cancelling decisions! This Go blog post on contexts highlights the usefulness of Context objects as sets of key-value pairs for request-scoped values. Their use goes beyond providing information about why an operation was terminated (and in fact, given that cancellation occurs "above" the context that gets cancelled, it's not really clear that that would be a valid use case).
There was a problem hiding this comment.
Removed that information.
docs/development/go/go-context.md
Outdated
|
|
||
| If you take a look at the source code of the `context` package, you will realize that its | ||
| implementation is pretty simple — even the implementation of the `Context` type is pretty | ||
| simple, yet the `context` package is very important. |
There was a problem hiding this comment.
No need to emphasize that context is important, IMO - it's already been added as part of many stdlib functions. That much should be apparent to the audience.
docs/development/go/go-context.md
Outdated
| abandon what you are doing but it an elegant way. However, it would be very helpful | ||
| to be able to include some extra information about your cancelling decisions and propagate | ||
| the information in a standard and portable way. The `context` package defines the | ||
| `context.Context` type that can carry deadlines and cancellation signals between processes. |
There was a problem hiding this comment.
This sentence restates the opening paragraph sentence, but more importantly is closer to what context actually does: carrying information about process state across goroutines.
docs/development/go/go-context.md
Outdated
| implementation is pretty simple — even the implementation of the `Context` type is pretty | ||
| simple, yet the `context` package is very important. | ||
|
|
||
| The `Context` type is a Go *interface* with four methods, named `Deadline()`, `Done()`, |
There was a problem hiding this comment.
For brevity, you could also paste the definition of context.Context here. Go programmers are used to that. The Go blog post linked previously does that, for example.
| err error | ||
| } | ||
|
|
||
| func connect(c context.Context) error { |
There was a problem hiding this comment.
Now might be a good time to highlight that in packages that use contexts, convention is to pass them as the first argument to a function.
| fmt.Println("Error select:", err) | ||
| return err | ||
| } | ||
| fmt.Printf("Server Response: %s\n", realHTTPData) |
There was a problem hiding this comment.
Why not use the log package here? It's sort of a minor point, but helps readers get in the habit of privileging log over fmt for debugging.
There was a problem hiding this comment.
That is a good point - I want the reader to be able to see the output. I will include what you said as you are right about it.
| case ok := <-data: | ||
| err := ok.err | ||
| resp := ok.r | ||
| if err != nil { |
There was a problem hiding this comment.
+1 for actually including error handling in the code; lots of Go examples skip it for brevity and encourage poor habits in readers.
docs/development/go/go-context.md
Outdated
|
|
||
| ## Another use of Context | ||
|
|
||
| In this section of the guide you are going to learn how to pass values in a `Context`. |
There was a problem hiding this comment.
Good to highlight this, but with three caveats:
- The title is kind of awkward.
Another use of Contextsounds vague, when in reality this is about using contexts as key-value stores. - The section is pretty brief compared to the others. Explaining why a user might want to do this would be good.
- This section conflicts with the introductory statement that passing values into contexts is done to provide further information about why they were cancelled.
There was a problem hiding this comment.
- Changed the title
- The example is brief so the section is brief as well
- You are right about that :)
4 participants
No description provided.