In Go, what is the difference between context.WithTimeout and context.WithDeadline?

## The two constructors `context.Context` is Go's standard way to carry a cancellation signal down a call chain. Two of its constructors attach a *time* to that signal: ```go func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) ``` `WithTimeout` takes a **duration** - a length of time, such as `2*time.Second`. `WithDeadline` takes a **`time.Time`** - a specific instant, such as `time.Now().Add(2*time.Second)` or a timestamp parsed out of an incoming request. That is the entire difference. The standard library documents `WithTimeout(parent, d)` as being equivalent to `WithDeadline(parent, time.Now().Add(d))`, and that is how it is implemented. ## What both of them give you Both return two values: the derived context and a `context.CancelFunc`. - **The derived context** has a `Done()` channel that closes when the instant arrives (or when the parent is cancelled, or when you call the cancel function - whichever happens first). - After `Done()` closes because the time ran out, `ctx.Err()` returns `context.DeadlineExceeded`. If it closed because someone called the cancel function instead, `Err()` returns `context.Canceled`. Before it closes, `Err()` is nil. - `ctx.Deadline()` returns `(deadline time.Time, ok bool)`. On a context built by either constructor `ok` is true and `deadline` is the instant. On a context with no deadline anywhere in its chain - `context.Background()`, for example - `ok` is false and the `time.Time` is the zero value. - The `CancelFunc` should be called, normally with `defer cancel()`, even though the deadline will fire on its own. Calling it releases the timer and detaches the child from its parent immediately; dropping it keeps both alive until the deadline passes, which on a long-lived parent is a slow leak. `go vet`'s `lostcancel` check exists precisely to catch a cancel function that is never called. ## Which one to reach for **Use `WithTimeout` when you are granting a fresh budget.** "This call gets 2 seconds" is a duration, and writing it as a duration is the honest expression. The clock starts at the moment of the call, not when the surrounding request arrived, which is exactly what you want for a locally scoped operation. **Use `WithDeadline` when the instant already exists somewhere else.** Typical cases: an RPC framing that carries an absolute expiry, a batch that must be finished before a downstream job starts at 04:00, or code that reads `parent.Deadline()` and wants to derive a slightly earlier instant so it can reserve a few hundred milliseconds to write an error response. Recomputing that as a duration means measuring `time.Until(instant)` and then having `WithTimeout` add it back to `time.Now()` - two conversions where zero were needed, and two chances to lose milliseconds. The distinction matters most when a value is *transported*. A duration is only meaningful relative to when it was created; ship "2 seconds" across a network hop and the receiver has no idea how much of it the wire already ate. An absolute instant survives the trip (modulo clock skew between the two machines, which is why real systems usually send the remaining duration on the wire and convert back to a deadline on arrival). ## The relationship between the two Because `WithTimeout` is literally `WithDeadline` with the arithmetic done for you, everything true of one is true of the other: the same derivation tree, the same `Err()` values, the same requirement to call cancel, and the same fact that a derived context can only ever make the effective deadline **earlier** than the parent's, never later. ## Common confusions - *"The timeout starts when the request arrives."* No - it starts when you call `WithTimeout`. Any work done before that call is outside the budget you just granted. - *"If a timeout is set, I do not need the cancel function."* You still do; see above. - *"The deadline kills the goroutine doing the work."* It does not. Nothing in Go stops a goroutine from the outside. A context deadline closes a channel and sets an error; work stops only because some code checks `ctx.Done()` or `ctx.Err()`, or because the ctx was handed to a library that does. - *"WithDeadline takes a duration."* It takes a `time.Time`. Passing `2*time.Second` there does not compile - a small mercy, since the two argument types make the mistake impossible to ship.