Skip to content
Tutorials Center
My learning

Topics

Lesson 65 of 147 ยท Concurrency

Goroutines

Learn Go goroutines - the go keyword, how they differ from threads, why main must wait, sync.WaitGroup and wg.Go, loop variables, goroutine leaks and concurrency versus parallelism.

Most programs spend a lot of time waiting: for a disk, for a network reply, for the user. Programs also have independent jobs that could make progress at the same time, such as handling a thousand web requests or resizing a hundred images. Go makes this kind of work a built-in feature of the language. You start a function in the background with one keyword, go, and the runtime does the hard part.

A function running this way is called a goroutine. It is not an operating-system thread, it is much cheaper, and a single program can run hundreds of thousands of them. This lesson shows how to start goroutines, why you must wait for them, how sync.WaitGroup does that waiting, what goes wrong with loop variables and leaks, and how concurrency differs from parallelism. The next lesson adds channels, the tool goroutines use to talk to each other.

Starting a goroutine

Put go in front of any function or method call. The call starts running independently, and the current function continues immediately without waiting for it:

Go The go keyword and the exiting main

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Run it and you will most likely see only main is done, or nothing from the goroutine at all. The reason is the most important rule of this lesson: when main returns, the program ends, and every other goroutine is killed on the spot. The new goroutine had not even started printing yet. Starting a goroutine is cheap and fast, but it does not run before the next line of the caller; it is simply made ready to run.

Never rely on time.Sleep to "give a goroutine time to finish". It is slow when the delay is too long, and a bug when it is too short, because the right delay depends on the machine. Use a sync.WaitGroup or a channel to wait for exactly the work you started.

You can start any call as a goroutine, including a method call and a call to an anonymous function. An anonymous function is the most common form, because it lets the goroutine use variables from the surrounding code (a closure):

Go
go worker.Run()          // a method
go log.Println("hi")     // a standard library function

go func() {              // an anonymous function, called right away
	fmt.Println("inline goroutine")
}()

Notice the () after the closing brace. Without it you would only write a function value and never call it, and the compiler would reject the statement. As with defer, the function value and its arguments are evaluated immediately, in the goroutine that executes the go statement; only the call itself happens later, in the new goroutine.

Go Arguments are evaluated at the go statement

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The goroutine prints by argument: 1, because the value of n was copied when go ran. Arguments are passed like in any other call, by value (see pointers, values and functions).

Waiting with sync.WaitGroup

A sync.WaitGroup is a counter that lets one goroutine wait for others. It has three methods:

  • Add(n) raises the counter by n. Call it before you start the goroutines.
  • Done() lowers the counter by one. Each goroutine calls it when it finishes, normally with defer.
  • Wait() blocks until the counter is zero.
Go Waiting for several goroutines

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The output is always [0 1 4 9 16]. The goroutines may run in any order, but Wait returns only after all five called Done, and each one wrote to a different slice element, so there is no conflict. Two details matter:

  • Call wg.Add(1) in the loop, before the go statement. If you called Add inside the goroutine, Wait could run first, see a counter of zero and return too early.
  • Pass the group by pointer (or capture it in a closure). A WaitGroup must never be copied after first use; go vet reports copies.

wg.Go (Go 1.25)

The pattern "Add(1), start a goroutine, defer Done()" is so common that Go 1.25 added a method for it. wg.Go(f) does all three steps:

Go WaitGroup.Go, new in Go 1.25

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The function passed to wg.Go takes no arguments and returns nothing. If you need to hand it data, capture variables in the closure, as i and squares are captured above. On Go versions before 1.25 you would write the longer Add/Done form instead. The rest of this track uses wg.Go where it makes code shorter.

Goroutines and loop variables

Before Go 1.22, a classic bug lived here: all goroutines created in a for loop shared one loop variable, so they usually all saw its last value. Since Go 1.22 each iteration has its own copy of the variable, as described in for loops, and the bug is gone for modules that declare go 1.22 or newer.

Go Each iteration gets its own variable

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Every value from 0 to 4 shows up exactly once: [0 1 2 3 4]. I sorted the slice because the goroutines append in whatever order they happen to run; the sorting makes the output stable. The sync.Mutex is needed because several goroutines change the same slice, which is a data race otherwise; the sync package lesson explains mutexes in detail and data races shows what can go wrong without one.

Code that must also work with Go 1.21 or older used to write i := i at the top of the loop body. It is harmless in new code but no longer necessary. If a module's go.mod says go 1.21, the old shared-variable behavior still applies, because the loop semantics follow the language version in go.mod.

What a goroutine is

A goroutine is a function running on its own small stack that the Go runtime manages. Compared with an operating-system thread:

Goroutine OS thread
Initial stack about 2 KB, grows and shrinks as needed typically 1 to 8 MB reserved
Created by the Go runtime, in microseconds or less the kernel, much slower
Scheduled by Go's own scheduler, in user space the operating system
Switching cost very low higher (a kernel call)
Practical count hundreds of thousands thousands

The Go scheduler multiplexes many goroutines onto a small pool of OS threads. When a goroutine blocks (waiting for a channel, a lock, a network read or a sleep), the scheduler simply runs another one on the same thread. The scheduler internals lesson covers the details; for everyday programming the key point is that goroutines are cheap enough to create one per task.

You can see how cheap they are by starting a large number of them:

Go Ten thousand goroutines

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The program prints sum of 1..10000 = 50005000. It starts ten thousand goroutines and finishes almost instantly. atomic.Int64 makes the addition safe without a mutex; atomic operations explains it. The same program using ten thousand operating-system threads would be slow and heavy on memory.

Advantages and drawbacks

Why use goroutines, and what do they cost?

  • Cheap: a 2 KB stack and microsecond startup mean you can use one per task, even per request or per connection.
  • Simple model: code is written in ordinary sequential style; the runtime handles waiting and scheduling.
  • Use every core: the scheduler spreads runnable goroutines over all CPUs without any thread-pool code.
  • But: shared memory between goroutines creates data races unless you synchronize; a goroutine nobody waits for can leak; a panic in any goroutine that is not recovered crashes the whole program; and output order is not deterministic.

Goroutines do not return values

A go statement discards the function's results. If the goroutine's function returns a value, you cannot receive it with x := go f(); that is a syntax error. To get results out, write them into a variable that only that goroutine touches (like the slice slots above), or send them over a channel.

Panics also deserve a warning here. A panic in a goroutine that is not recovered crashes the whole program, not just that goroutine. A recover call in main cannot catch it, because each goroutine has its own call stack. If a goroutine may panic, recover inside that goroutine, as shown in panic and recover.

Go A goroutine that recovers from its own panic

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

job-a panics, the deferred function inside that goroutine catches it, and the program carries on. The two Wait calls make the order of output deterministic. A WaitGroup can be reused once its counter is back to zero.

Goroutine leaks

A goroutine that never finishes is a leak. Unlike memory that nothing points to, a blocked goroutine is never garbage collected, because the runtime cannot know that nobody will ever wake it. Leaked goroutines keep their stack and everything they reference alive, so a long-running server that leaks one goroutine per request slowly eats all its memory.

The usual causes are a goroutine waiting on a channel that nobody will ever send to or close, a goroutine waiting on a lock that is never released, and a loop with no exit condition. You can detect a leak by watching runtime.NumGoroutine():

Go Detecting a leaked goroutine

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The program reports extra goroutines: 3: three goroutines are stuck for good. runtime.Gosched() yields the processor so the new goroutines get a chance to start. In real code, the cure is to give every goroutine a way to stop: a channel it can receive from, or a context it checks for cancellation. A good rule is that whenever you write go, you should be able to say when and how that goroutine ends.

For more on how the runtime handles memory, see garbage collection.

Concurrency versus parallelism

These two words are often mixed up, and Go's designers distinguish them clearly:

  • Concurrency is about structure: a program is organized as several independent tasks that can make progress in overlapping time periods. A single cook can juggle several dishes by switching between them.
  • Parallelism is about execution: several tasks literally run at the same instant, which needs several CPU cores. Several cooks can work in parallel.

A concurrent program may or may not run in parallel. With one core, goroutines take turns; with eight cores, up to eight run simultaneously. The program is correct in both cases if it is written well. How many goroutines may run Go code at once is limited by GOMAXPROCS, which defaults to the number of available CPU cores. You rarely need to change it.

Concurrency helps most when tasks wait: network calls, disk, timers. For pure number crunching, adding goroutines beyond the number of cores does not make things faster, and splitting small jobs across goroutines can even be slower than a plain loop, because starting and coordinating goroutines has a cost. Measure before you parallelize.

Go Concurrent waiting overlaps

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Four fetches of 200 ms each would take about 800 ms one after another. Running them concurrently takes only about 200 ms in total, and the program confirms it with a comparison instead of printing the exact time (timings vary from run to run, so never print them as results). The speed-up comes from overlapping the waiting, which works even on a single core.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What usually happens when main starts a goroutine with go work() and then returns immediately?

    The program ends when main returns, and all remaining goroutines are stopped. Use a WaitGroup or a channel to wait for them.
  2. 2. Where should you call wg.Add(1) for a goroutine that you start in a loop?

    Add must run before Wait could observe a zero counter. Calling it inside the goroutine risks Wait returning before the goroutine has even registered itself. (wg.Go in Go 1.25 does this for you.)
  3. 3. What does this code do?

    result := go compute()

    go is a statement, not an expression, and the results of the called function are discarded. Send results through a channel or write them to memory the goroutine owns.
  4. 4. A goroutine panics and nothing recovers it. What happens?

    An unrecovered panic terminates the entire program. recover must be called in a deferred function inside the same goroutine.
  5. 5. Why is a goroutine blocked forever on a channel receive a problem?

    The garbage collector does not stop blocked goroutines, because it cannot know whether they will be woken later. Always give goroutines a way to finish.

Summary

  • go f(x) starts f in a new goroutine; the arguments are evaluated immediately, the call runs concurrently.
  • When main returns, the program ends and all other goroutines are killed, so always wait for work you start.
  • sync.WaitGroup waits for goroutines: Add before starting, Done when finished, Wait to block; wg.Go(f) (Go 1.25) combines the three steps.
  • Since Go 1.22, every loop iteration has its own variable, so goroutines started in a loop see their own copy.
  • Goroutines are cheap (about 2 KB to start), managed by Go's scheduler, and do not return values; use shared memory you own or channels.
  • An unrecovered panic in any goroutine crashes the whole program; recover inside the goroutine.
  • A goroutine that can never finish is a leak; give every goroutine an exit path.
  • Concurrency is structure, parallelism is simultaneous execution, and goroutines give you the first and, with several cores, the second.

Next: Channels shows how goroutines send values to each other safely.