Mario Škrlec

How can you simplify the Context package in Go, and what is its purpose? In this article, I'll guide you step by step and explain how to use the Context package. 

Simplifying context in Go - Prototyped



In Go, we use the Context package for cancellations and
passing values between different application services. Basic knowledge of
goroutines would be helpful for a better understanding of this article.

When I created my first goroutine in Go, I stumbled upon a question. What if
this goroutine has a bug and never finishes? The rest of my program might keep
on running oblivious of a goroutine that never finishes. The simplest example of
this situation is a simple “throwaway” goroutine that runs an infinite loop.



package main

import "fmt"

func main() {
  // some "heavy" computation data, 3 entries are only
  // as an example
  dataSet := []string{"apple", "orange", "peach"}

  go func(data []string) {
    // heavy computation that might take a long time and contain a bug
  }(dataSet)

  // the rest of the program goes here and continues
  // to run independent of our goroutine above

  fmt.Println("The rest of our program runs and runs")
}

The above example is not complete but I hope you understand what I'm trying to
do. Our “throwaway” goroutine might or might not process data successfully. It
might enter an infinite loop or cause an error. The rest of our code would not
know what happened.

There are multiple ways to solve this problem. One of them is to use a channel
to send a signal to our main thread that this goroutine is taking too long and
that it should be cancelled.



package main

import "fmt"
import "time"

func main() {
  stopCh := make(chan bool)

  go func(stopCh chan bool) {
    // simulate long processing
    for {
      select {
        case <-time.After(2 * time.Second):
          fmt.Println("This operation is taking too long. Cancelling...")
          stopCh<- true
      }
    }
  }(stopCh)

  <-stopCh
}


Pretty straightforward. We are using a channel to signal to our main thread that
this goroutine is taking too long. But the same thing can be done with context
and that is exactly why the context package exists.



package main

import "fmt"
import "context"
import "time"

func main() {
  ctx, cancel := context.WithTimeout(context.Background(), 2 * time.Second)
  // it is always a good practice to cancel the context when
  // we are done with it
  defer cancel()

  go func() {
    // simulate long processing
    for {
      select {
        case <-time.After(2 * time.Second):
          fmt.Println("This operation is taking too long. Cancelling...")
          cancel()
          return
      }
    }
  }()

  select {
    case <-ctx.Done():
        fmt.Println("Context has been cancelled")
  }
}


If you concluded that the context package is a wrapper around a channel to which
you react, you would be right. You could easily recreate the context package on
your own, but the context package is part of the Go SDK and it is preferable to
use it. Also, this package is used by many libraries out there including the 
httppackage, among others.

Context interface
type Context interface {
	Deadline() (deadline time.Time, ok bool)
	Done() <-chan struct{}
	Err() error
	Value(key interface{}) interface{}
}


Every time you create a new context you get a type that conforms to this
interface. The real implementation of context is hidden in this package and
behind this interface. These are the factory types of contexts that you can
create:

 1. context.TODO
 2. context.Background
 3. context.WithCancel
 4. context.WithValue
 5. context.WithTimeout
 6. context.WithDeadline

The first context types that we will look at are the context.TODO and 
context.Background

context.TODO and context.Background
These types of contexts do nothing. It's as if you haven't even created them.
Their only use is that you pass some function a context but you don't plan to do
anything with that context. A throwaway context. Use this context when you don't
plan to do anything with it but some API that you are using requires that you
pass it a context.

It is also very important to say that, if a function requires you to pass a
context, it is for a good reason. This could be an HTTP request, a connection to
a database or a query to the database. HTTP can hang and database queries could
take some time. It is good practice that you pass a context in these situations
since they protect you from breaking your program. 

For example:

func main() {
	ctx := context.TODO()
	req, _ := http.NewRequest(http.MethodGet, "<http://google.com>", nil)

	client := &http.Client{}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println("Request failed:", err)
		return
	}
  
	fmt.Println("Status: ", res.StatusCode)
}


The Question from this piece of code is, how long will this request take? Sure,
we're calling Google but even Google is not immune from some downtime. A better
solution is to create a context that will tell us when this request is taking
too long (or at least what we think “too long” is) so we can react to it. A
better solution is to implement a timeout context and react when that timeout
exceeds. We will go back to this example when we talk about some other types of
contexts.

Back to context.TODO(). Under the hood, this context is of type *emptyCtx and it
returns empty values for every function in the Context interface. But this
context uses a different purpose. It serves as the parent context for some more
useful context types. context.Background() is equal to context.TODO. When
researching for this blog post, the only difference is semantics. With
context.Background(), you are signaling to other developers that you should do
something with this context, but from the context package source code, they are
the same. If you disagree, leave a comment.



var (
	background = new(emptyCtx)
	todo       = new(emptyCtx)
)

// Background returns a non-nil, empty Context. It is never canceled, has no
// values, and has no deadline. It is typically used by the main function,
// initialization, and tests, and as the top-level Context for incoming
// requests.
func Background() Context {
	return background
}

// TODO returns a non-nil, empty Context. Code should use context.TODO when
// it's unclear which Context to use or it is not yet available (because the
// surrounding function has not yet been extended to accept a Context
// parameter).
func TODO() Context {
	return todo
}


Let's dive into some more interesting uses of the context package.

Parent context and canceling
context.TODO and context.Background are types that are used as parent context
for other, more useful types of contexts. The first one we will take a look at
is the cancel context and its uses.

context.WithCancel()
Let's say you create a goroutine worker that does something very expensive for
your CPU. If the work that it is doing is no longer required, you would like it
to stop so it does not waste any resources. Normally, you would do this with
regular channels.



package main

import (
	"fmt"
	"time"
)

func main() {
	// a channel to tell the goroutine to stop
	// what it is doing
	stopCh := make(chan bool)
	collectIntegers := func(stop chan bool) <-chan int {
		dst := make(chan int)
		n := 1
		go func() {
			for {
				select {
				case <-stop:
					close(dst)
					return
				case dst <- n:
					n++
				}
			}
		}()

		return dst
	}

	ciCh := collectIntegers(stopCh)
	time.AfterFunc(2*time.Second, func() {
		i := <-ciCh
		stopCh <- true
		close(stopCh)
		fmt.Println(fmt.Sprintf("%d integers collected", i))
	})

	// block here until AfterFunc runs
	for _ = range ciCh {}
}


The code is pretty straightforward. We are using a channel to signal to the
goroutine to stop working after 2 seconds. Now let's try this with a canceller
context.



package main

import (
  "context"
  "fmt"
  "time"
)

func main() {
	collectIntegers := func(ctx context.Context) <-chan int {
		dst := make(chan int)
		n := 1
		go func() {
			for {
				select {
				// listen here to react when cancel() function is called
				case <-ctx.Done():
					close(dst)
					return
				case dst <- n:
					n++
				}
			}
		}()

		return dst
	}

	ctx, cancel := context.WithCancel(context.Background())
	ciCh := collectIntegers(ctx)
	time.AfterFunc(2*time.Second, func() {
		i := <-ciCh
		// when cancel() is called, done channel inside the context is closed
		cancel()
		fmt.Println(fmt.Sprintf("%d integers collected", i))
	})

	// block here until AfterFunc runs
	for _ = range ciCh {
	}
}


From the documentation:

Calling the CancelFunc cancels the child and its children, removes the parent's
reference to the child, and stops any associated timers. Failing to call the
CancelFunc leaks the child and its children until the parent is canceled or the
timer fires.

So, when we called cancel(), select case for ctx.Done()was fulfilled and we
could return from the goroutine.

A very important thing to say here is that you always defer cancel(). From the 
official Go blog [https://go.dev/doc/database/cancel-operations]:

Always defer a call to the cancel function that’s returned when you create a new
Context with a timeout or deadline. This releases resources held by the new
Context when the containing function exits

Parent <-> Child relationship
Contexts work based on a parent-child relationship. When you create a context
from another context, that created context is said to be derived from the parent
context. If you cancel the parent context, all of its children are canceled as
well. You can create as many derived contexts as you like. Here, we are creating
2 derived contexts and canceling the parent context. After the parent is
canceled, the child is canceled as well.



package main

import (
  "context"
  "fmt"
  "sync"
  "time"
)

func main() {
	parent := context.Background()

	ctx2, cancelCtx2 := context.WithCancel(parent)
	ctx3, _ := context.WithCancel(ctx2)

	wg := sync.WaitGroup{}
	wg.Add(2)
	go func() {
		for {
			select {
			case <-ctx2.Done():
				fmt.Println("ctx2 is done")
				wg.Done()
				return
			}
		}
	}()

	go func() {
		for {
			select {
			case <-ctx3.Done():
				fmt.Println("ctx3 is done")
				wg.Done()
				return
			}
		}
	}()

	time.AfterFunc(1*time.Second, func() {
		cancelCtx2()
	})

	wg.Wait()
}


As you can see, the first ones to be cancelled are the children. The last one to
be cancelled is the parent.

Timers -> context.WithTimeout and context.WithDeadline
WithTimeout and WithDeadline and contexts that are set to automatically cancel
when some time expires or reaches, depending on the type. They are essentially
the same, but WithDeadline receives time. Time while WithTimeout accepts time.
Duration but returns a WithDeadline context. 

From the source code:



func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
	return WithDeadline(parent, time.Now().Add(timeout))
}


WithDeadline can be set to expire at some future date and time. For example, the
code below takes whatever date and time you are reading this and expires in 2
seconds in the future.



package main

import (
  "context"
  "fmt"
  "time"
)

func main() {
	now := time.Now()
	fmt.Println(fmt.Sprintf("Current date and time is: %s", now.Format("02.01.2006 15:04:05")))
	ctx, cancel := context.WithDeadline(context.Background(), now.Add(2*time.Second))
	defer cancel()

	wait := make(chan bool)
	go func(ctx context.Context, wait chan bool) {
		for {
			select {
			case <-ctx.Done():
				wait <- false
				fmt.Println(fmt.Sprintf("Deadline is reached on: %s", time.Now().Format("02.01.2006 15:04:05")))
				return
			}
		}
	}(ctx, wait)

	<-wait
	fmt.Println("Main thread has waited long enough!")
}


As I said, WithTimeout is the same as WithDeadline, but it only accepts a time.
Duration time. The code above could be written in the same way WithTimeout:



package main

import (
  "context"
  "fmt"
  "time"
)

func main() {
	ctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(2 * time.Second))
	defer cancel()

	wait := make(chan bool)
	go func(ctx context.Context, wait chan bool) {
		for {
			select {
			case <-ctx.Done():
				wait <- false
				fmt.Println("Deadline reached!")
				return
			}
		}
	}(ctx, wait)

	<-wait
	fmt.Println("Main thread has waited long enough!")
}


Conclusion
Context package is great for concurrency patterns and essential to learn well
since most of the libraries that are dealing with some kind of timers or future
resolutions use context. This includes database connections, HTTP requests, etc…

Check out this article on the Rebel Source
[https://rebelsource.dev/blog/simplifying-context-in-go/ThfP01rPE] website where
you can run and edit the code examples. 

If you would like to know more about this package here are a few useful links:

 * Context package official documentation [https://pkg.go.dev/context]
 * Official Go blog post about concurrency and context
   [https://go.dev/blog/context]
 * Great blog post about context type safety
   [https://blog.khanacademy.org/statically-typed-context-in-go/] 

Thank you for your the time to read this blog! Feel free to share your thoughts
about this topic and drop us an email at hello@prototyp.digital
[/detecting-network-state-with-javascript/hello@prototyp.digital].

Development

Simplifying context in Go

Follow this tutorial to find out how to add internationalization (i18n) to a Gatsby project, and how to configure it to also work with client-only routes. 

Adding internationalization to client-only routes in Gatsby-Prototyped

Adding internationalization (i18n) to a Gatsby project with gatsby-plugin-intl
[https://www.gatsbyjs.com/plugins/gatsby-plugin-intl/] is simple as installing
any other Gatsby plugin and configuring it. Once set up, plugin generates a i18n
route for every page and for every language that is added in the plugin config.

For example, if we have 10 pages (static routes) and have 3 languages, i18n
plugin creates 30 routes (HTML files) total. If the configured languages are en
(English), de (German), hr (Croatian) and if we look at the src/pages/about.js
route component, we’ll get the following routes when we run or build our
project:


 * en/about
 * de/about
 * hr/about


With redirect option enabled in the plugin, Gatsby does default redirects from a
non-i18n routes to a default-i18n routes. Meaning that if a user requests an
about page without any i18n specified in the URL, they will be redirected to a
default i18n route. If the default is English, user will be redirected to
 en/about.
This is how the i18n plugin handles static routes (public pages). What about the
client-only routes?

Client-only routes

Client-only routes are protected routes that are not directly accessible. Gatsby
doesn’t build any static assets for these routes, including HTML files.
Client-only routes are useful when building a page that requires authorization
or if the page content heavily depends on the API response. These pages only
exist on the client-side.
In Gatsby, client-only routes rely on a custom Router that handles
authorization. Here is the example of src/app/app.js where a custom Router
component is called and client-only routes are defined.

import React from "react"
import { Router } from "@reach/router"
import Login from "../app/login"
import Register from "../app/register"
import Layout from "../components/layout"

const App = () => (
    <Layout>
      <Router>
        <Login path={`/app/login`} />
        <Register path={`/app/register`} />
      </Router>
    </Layout>
  )

export default App

Issue with i18n plugin and client-only routes

Gatsby is aware of the client-only router and will include these client-only
pages on build time, but it will only create a JavaScript assets that are needed
to build the pages dynamically. Our app.js will handle routing and path
matching. 
Plugin is not aware that these routes exist, so these routes won’t work out the
box with our i18n plugin. Keep in mind that the gatsby-plugin-intl adds i18n
prefixes to routes en/, de/, etc. Even though we have added a /app/login and
/app/register paths in our router, the real paths have those i18n prefixes.

But we don’t want to manually add those when we creates the sites. We might need
to support more languages in the future and we’ll need to add more pages. That
is why we want to create them programmatically on build time and let Gatsby take
care of it.

Adding i18n support to client-only routes

First we need to instruct Gatsby how to build pages that are included in the
client-only routes (in the src/app folder). We’ll do that by adding the
following code to gatsby-node.js.

exports.onCreatePage = ({ page, actions }) => {
  const { createPage } = actions
  // notice the addition of .*
  if (page.path.match(/^\/.*\/app/)) {
    // notice page.context.language
    page.matchPath = `/${page.context.language}/app/*`
    createPage(page)
  }
}




And we need to make a slight adjustment to our Router in src/app/app.js
component. 



import React from "react"
import { Router } from "@reach/router"
import Login from "../app/login"
import Register from "../app/register"
import Layout from "../components/layout"
const App = () => (
  <Layout>
    <Router basepath="/:lang/app">
      <Login path={`/login`} />
      <Register path={`/register`} />
    </Router>
  </Layout>
)
export default App

With this solution, we can add as many new client-only routes and new languages
as we want and Gatsby will know how to handle the new routes. All components and
paths that are references within this Router component will be included on the
build time.

Thank you for taking the time to read this post.  I would like to hear your
thoughts on this issue, so let me know if you’ve encountered a similar issue on
your project and how you’ve solved it.

Feel free to share your thoughts in the comments or drop us an email at 
hello@prototyp.digital. 😄

AuthorMario Škrlec

Start a Project