In the last lesson, we looked at various different cancellation strategies when it comes to using the signal channel in order to cancel our application depending on different circumstances. Whether it's running a ticker in order to produce events every second or every minute, or any other interval that we define, or if it's iterating over events and processing them one by one, cancelling once we've finished processing the event we're currently on. This concept, in both Go and other languages, is known as cancellation, and it's particularly important when it comes to working with concurrency, as being able to cancel tasks once they're in flight is something that can be rather useful.

So far, we've been implementing cancellation through the use of channels, be it the done channel that we use to let the application know that we had finished processing, or through the use of the signal.Notify function, passing in a channel that we can receive a signal event on. However, as I mentioned in the last lesson, Go actually has its own type dedicated to cancellation, which we're going to learn more about in this lesson. This type is the context type of the context package, which carries deadlines, cancellation signals, and other request scoped values across API boundaries between processes. The context type is incredibly powerful, and we'll look at some of the ways we can use it throughout this lesson.

For the meantime, however, to get an understanding of how the context type works, let's go ahead and make use of it when it comes to handling signals, instead of using a channel. In order to do so, let's go ahead and modify our ping command, which, if I go ahead and run, you'll see produces a ping every one second. This is done using the time.Ticker channel, and then once we receive a ctrl + c or a sigint, it will exit. Let's go ahead and replace this with instead using a context. To do so, we can use the notifyContext function of the signal package, which is very similar to the Notify function. However, rather than accepting a channel, it accepts a context.Context, as well as the variadic parameter of signals, and then returns a context and a context.CancelFunc.

We'll take a look at what both of these are in a second. For the meantime, however, we need to pass in a parent context. In order to do that, let's first go ahead and clean up this code by getting rid of our channel logic, just so that we can more clearly understand what is actually related to our context. Then to the begin, we can go ahead and call the signal.NotifyContext function, where we need to pass in a context.

To create a context is a little more tricky than you might initially think, but for good reason. Contexts themselves typically always have a parent context that they're associated with, which has the benefit of when you cancel a parent context, all of the children will be cancelled as well. We'll take a look at what that means more shortly. For the meantime, however, we currently don't have a parent context, so let's just go ahead and create one using the following:

ctx := context.Background()

If we take a look at the documentation for the Background context, the Background function returns a non-nil empty context. It is never cancelled, has no values, and has no deadline. It is typically used by the main function initialization and tests as the top level context for incoming requests. Therefore, because we're inside of the main function and we have no parent context, let's go ahead and define our first context as this context.Background. In fact, rather than capturing it in a variable, let's just go ahead and pass it in as the first parameter to our NotifyContext function, which accepts a parent as its first parameter.

Next, let's go ahead and define the signals we want to listen to, which in this case is the interrupt signal, as follows:

signal.NotifyContext(ctx, os.Interrupt)

With that, we can then go ahead and capture the two return values we receive. The first is our new context, which we can capture in ctx. This is the idiomatic name for contexts when it comes to Go. As for the second value of the NotifyContext function, just go ahead and ignore it for the moment. We will take a look at it later on, and you don't normally want to ignore this in production. However, for the meantime, let's just go ahead and set it to the blank identifier.

Now, with our context defined, how do we go about actually using it? Well, fortunately, if we take a look at the context type, it actually provides a method called Done, which returns a channel of empty struct. Basically, it has its own done channel. If we take a look at the documentation, you can see that Done returns a channel that's closed when work done on behalf of this context should be cancelled. Done may return nil if the context can never be cancelled, which isn't in this case. Successive calls to Done return the same value, and the close of the done channel may happen asynchronously after the channel function returns. Therefore, we can go ahead and just use this function in order to act as a sort of done channel for our code.

Therefore, let's go ahead and actually wait on this as follows:

<-ctx.Done()
fmt.Println("sigint received, closing down")

Lastly, let's go ahead and add in a return here as well, just so that we exit out of this loop when the ctx.Done() is called. Now, if I go ahead and run this code, it should work the exact same way we saw before - pinging once every one second due to our time.Ticker and printing out google.com. Additionally, if I go ahead and press CTRL+C to send sigint, you can see that our application closes as we receive the signal.

So far, this is operating the exact same way that we saw when it came to using our signal.Notify with a channel. However, now we have a lot more capabilities provided to us. For example, let's say we want to go ahead and cancel this function after five seconds. In order to do so using a channel, we would probably need to use yet another time.After.

time.After(time.Second * 5)

And we'll just go ahead and return and we'll print out as well. So finishing after five. Although in this case, it actually won't ever work. For example, if we go ahead and run this, you'll see even after five ticks, it's not cancelling. This is because we're creating a new time.After after each tick. So we have a bug. In order to fix this, we would need to define a channel here. I would say let's say ch or timeout, let's say is and assign it to the value of:

timeout := time.After(time.Second * 5)

Then we could go ahead and case on the timeout as follows:

case <-timeout:
  fmt.Println("finishing after five")

Now, when we run this code, we should see the application shut down after five seconds and we'll see five pings come through. There you go. Actually, we saw four, but that's okay. So as you can see, whilst it's possible to do this with using channels, we can also do this using our context. To show one way we can do it using our context, which is actually the incorrect way, let's go ahead and capture the second return value of the NotifyContext function, which we'll go ahead and store as cancel.

This second return value is of CancelFunc type, which is just a simple function. However, when we call this function, it will tell an operation or a context to abandon its work. Therefore, we can use this cancel function in order to cancel our code after, say, five seconds. Remember, this isn't the correct way to do this, but let's just take a look at it for example. So if we go ahead and call a go func again and let's go ahead and do a:

time.Sleep(time.Second * 5)

Then let's call the cancel function or better yet, we could just defer it here:

defer cancel()

Now, when I go ahead and run this code, you should see the code exit again after five seconds. However, this time it's doing it through the cancel function, which as you can see is taking place. Although our sigint received, closing down is not actually the correct reason. Therefore, let's go ahead and change this to be:

fmt.Println("cancel received, closing down")

Using the cancel function is a very powerful construct when it comes to contexts, as it allows you to not only cancel your current context, but also any child contexts that have been derived from your context as a parent.

To show what I mean, let's go ahead and create another context using the context.WithCancel function, which again takes a parent and returns a context.Context and a CancelFunc. Let's go ahead and pass in the context.Background and we'll call this parentCtx and parentCancel.

Then, for our notifyContext, let's go ahead and pass this parentCtx in as follows. Then, rather than calling our cancel function, let's go ahead and call the parentCancel function as follows. And we'll just ignore the cancel for the meantime, because we're not doing anything with it.

Now, when I go ahead and run this code, you'll see that once the parentCancel function is cancelled, the child is also cancelled as well, despite the fact that we're never actually calling the cancel function of the signal.NotifyContext. This is where some of the power of using contexts starts to come in, as you can define a parent context that can be cancelled by a global event, such as a signal interrupt, and it will propagate to any other child contexts that you may have in your application.

But why may you want to have any other child contexts? Well, for example, as we saw before, let's go ahead and get rid of the parent and go back to the current setup we had before. If you'll remember, I mentioned that cancelling a context this way, let's do context.Background, you'll remember that I said cancelling a context this way using a go func with a time.Sleep isn't the best way to have cancellation after a period of time.

This is because the context.Context package actually provides its own function for cancelling after a timeout. To show what this looks like, let's go ahead and add a deferred call to this cancel, given that we're not going to be using it directly. As a little hint, if you don't ever intend to use the cancel function, then it's a good idea just to add a deferred call to it to whichever function you're in, just so that it does cancel.

Also, one thing to note is that cancelling a context doesn't cancel the parent, it only cancels the children. We'll take a look at that shortly just to prove that that's the case. Okay, now that our code is in a good state, let's go ahead and add in an actual timeout. We can do this by creating another context, let's call this childCtx, and we'll call this childCancel as well. In this case, we'll set this to be the context.WithTimeout, which accepts a parent context and a time.Duration, and will cancel after the deadline.

Therefore, for the parent, let's go ahead and pass in the signal.NotifyContext, and we'll set a duration of:

time.Second * 5

In this case, let's go ahead and put a deferred to the childCancel as well, as follows. Now, instead of selecting on the done channel of our context, let's go ahead and select on the done channel of our childContext, which if we go ahead and run again, this time you should see it cancel after around five seconds, which it does.

However, one thing to note is that whilst the child has cancelled, the parent actually hasn't. To show what I mean, rather than returning early and looping forever, let's go ahead and actually put in a loop variable here so we can break out, break loop. Then after we've done our for loop and our child context is cancelled, let's just go ahead and wait on the parent context to see what happens here. And we can go ahead and say:

fmt.Println("sigint received")

Now, if we go ahead and run this code again using the go run command with google.com, after five seconds we should see the ping stop, but we'll be waiting for a control c before our application exits, which we can do by passing in sigint. As you can see, contexts allow you to structure your cancels in a parent-child way, which means you can do some pretty interesting things when it comes to your code, as well as cancelling certain tasks with a global cancellation taking place on a global event.

In this case, the signal.NotifyContext is the global event for all of our cancellation. But what else can we actually use the context type for? Well, the context type is actually very well supported when it comes to the Go standard library, and there are many different functions within the standard library that support context. In fact, if you're writing any code that performs long-running tasks or asynchronous operation with goroutines, then you should always be accepting a context as the first parameter.

To show what this looks like, if we take a look at our event processing function, if you remember, we were accepting as the first parameter a parameter of ch, which was our chan os.Signal. Instead, this would be a good candidate in order to pass in our context.Context. So let's go ahead and quickly make use of it. Getting rid of our channel and defining a context and a cancel as:

signal.NotifyContext(ctx, os.Interrupt)

Let's go ahead and replace this to instead accept a context, which will be of type context.Context. And we can go ahead and wait on the context.Done() as follows. And then we can pass this in. Now our code will work the exact same way, as we saw before, iterating over each event. But when we pass sigint, it'll cancel as we saw before.

When it comes to a code that accepts cancellation, be it asynchronous code or long-running code such as we have here, you should always pass in the context as the first parameter, as this is pretty much customary when it comes to Go. As I mentioned before, there are many different functions within the standard library that actually make use of this pattern, specifically those that deal with any asynchronous operations, be it network requests or the exec package that we've seen already.

To show this in action, if we head back on over to the code where we were executing the ping command, and we were using a channel in order to process the interrupt, let's again replace this with a call to a context. So:

context.CancelFunc(ctx)

And we'll do the signal.NotifyContext again, which is always a good parent context when it comes to command line applications in Go. And we'll do the os.Interrupt. And again, we'll have a deferred call to cancel. As we've seen before, we could go about using the context.Done() in order to just replace the existing flow we already had.

If we go ahead and take a look at the, for example, if we take a look at the exec package, as we've seen before, and take a look at the actual Cmd type, we've been creating this type using the Command function, where it takes the name of the command we want to pass in and the variadic parameter of arguments. However, you'll also notice there's another Command function called CommandContext, which takes a context.Context as its first parameter. If you look at the documentation, you can see CommandContext is like Command, but includes a context. And the provided context is used to interrupt the process by calling Command.Cancel() or os.Process.Kill() if the context becomes done before the command completes on its own.

Therefore, let's go ahead and replace our call to Command with a call to CommandContext, passing in the context as the first argument. Let's also remove the call to the process's signal. Now, if we go ahead and run this code, you can see it's calling the ping command as usual, but we can press control and c, and it will exit. In this event, you can see that because we're passing signal.Interrupt, then our application is also shutting down with sigint as well.

And not only this, but we also get the benefit of being able to use the other functions within the context package, such as the WithTimeout function, which allows us to pass in a time.Duration in order to timeout the context after a period of time. As you can see however, there are a few other functions we can use when it comes to contexts, such as the WithDeadline function, which is similar to the context.WithTimeout, but allows us to specify an actual time. So we could set this to be New Year's Eve of 2027 or something similar.

Additionally, we also have the WithCancel function, which we saw before, which will create a context that has a cancel function associated with it, which will allow us to cancel children but not cancel their parents. And there's the WithValue, which honestly is something I would only recommend in situations such as network requests or APIs, but it allows you to assign arbitrary key values to the context that you can pass in. This has some caveats with it and actually starts to break Go's type safety unless you do it properly. For command line applications I wouldn't really recommend using this, so we're not going to cover this function in the course.

If you want to know more about the WithCancel method, then you'll have to wait till my full-stack Go web application course comes out, where we will look at this a lot more. With that, we've managed to take a look at how we can use the context package when it comes to cancellation in Go, which is a much better construct for providing cancellation across Go routines, threads, and long-running processes.

Again, if you happen to be writing code that has long-running operations, then you'll want to accept a context.Context as a first parameter, as it's a good practice to get into and it allows your code to support cancellation. Even if you don't necessarily implement it in the first place, at least you have an API to be able to do so.

In the next lesson, we're going to apply everything that we've learned inside of this module and build an application that we can use to compile binaries for different platforms in Go, be it Windows, macOS or Linux, as well as supporting different architectures such as ARM and AMD64. Again, we're going to be applying everything that we've learned, especially when it comes to cancellation and contexts, ensuring that we cancel our code only once we've finished building the current binary.