Unbuffered and Buffered Channels

Output:

send completed after 100ms
received order 2 after 100ms
Copy

In the first half, main sends immediately but the receiving goroutine is asleep, so the send waits 100 ms. In the second half, main receives immediately but the sending goroutine is asleep, so the receive waits 100 ms. Neither side can finish an operation on an unbuffered channel without the other side.

Buffered Channels

A channel with a capacity greater than zero is called a buffered channel (a channel with room to store a fixed number of values). Its storage, the buffer, is a first-in, first-out queue: values are received in the order they were sent. A send waits only when the buffer is full, and a receive waits only when the buffer is empty.

The difference shows clearly when the receiver is slower than the sender. In the program below, a receiving goroutine takes 100 ms to prepare each of three orders. The deliver function runs the same exchange twice, once on an unbuffered channel and once on a channel with a capacity of three.

Output:

capacity 0: sender free after 200ms
capacity 0: all orders ready after 300ms
capacity 3: sender free after 0s
capacity 3: all orders ready after 300ms
Copy

With no buffer, the sender hands over order 1 at 0 ms, order 2 at 100 ms, and order 3 at 200 ms. It is free only after 200 ms. With a buffer of three, all three sends complete without waiting and the sender is free immediately. The receiver finishes at 300 ms in both cases, because the buffer changes when the sender may continue, not how fast the receiver works.

len and cap

The built-in function cap returns the capacity of a channel, and len returns the number of values currently in its buffer. For an unbuffered channel, both are always zero.

Output:

len 0 cap 3
len 2 cap 3
received order 1
len 1 cap 3
Copy

The two sends in main complete without any receiving goroutine, because the buffer has room. The receive takes order 1, the value sent first, and leaves one value in the buffer.

The value of len is correct only at the instant it is read. When other goroutines send and receive on the same channel, the count can change before the next line runs. Code such as if len(ch) < cap(ch) { ch <- v } can therefore still wait, because another goroutine may fill the last slot between the check and the send. Use len for logging and measurements, not to decide whether an operation will wait.

Deadlock: A Send Nobody Receives

A send on an unbuffered channel waits for a receiver. If no goroutine will ever receive, the send waits forever. A state in which no goroutine can make progress is called a deadlock. When every goroutine in the program is waiting in this way, the Go runtime detects it and stops the program with a fatal error.

func main() {
	orders := make(chan string)
	orders <- "order 1" // no goroutine will ever receive this value
	fmt.Println("sent")
}
Copy

Run as a complete program, this main prints:

fatal error: all goroutines are asleep - deadlock!

goroutine 1 [chan send]:
main.main()
Copy

The line goroutine 1 [chan send] says that the main goroutine was waiting in a channel send. A buffered channel gives the same error once its buffer is full. Sending four values into make(chan string, 3) with no receiver stops on the fourth send.

The runtime reports a deadlock only when every goroutine is blocked. If one goroutine waits forever on a channel while others keep running, nothing is printed, and that goroutine simply never ends. A buffer does not fix a program that has no receiver either. It only postpones the moment when the sender starts waiting.

Comparing the Two Kinds

Choose an unbuffered channel when the sender needs to know that the value was received. Choose a buffered channel when the sender may continue before the receiver has taken each value, up to a known limit. The capacity should come from a reason, such as the number of results you expect. It should not be a guess made to stop a deadlock.

Key Takeaways

• A channel carries values of one type from one goroutine to another, in the order they were sent.
• On an unbuffered channel, a send and a receive each wait until the other side is ready.
• On a buffered channel, a send waits only when the buffer is full, and a receive waits only when it is empty.
• len reports how many values are in the buffer at one instant, and cap reports the capacity.
• A send or receive that can never complete blocks its goroutine forever. If all goroutines block, the runtime stops with a deadlock error.

A channel passes values between two goroutines, and its capacity sets how many values the sender may send before the receiver takes them. With no capacity, sender and receiver must both be ready for every value. With a capacity of n, the sender may be up to n values ahead.