Go context.AfterFunc Stop Does Not Wait for Callback Completion

The stop function returned by Go’s context.AfterFunc does not wait for a callback that has already started. A false result therefore marks a state boundary, not a completion barrier: the callback may be running concurrently when stop returns.

context.AfterFunc(ctx, f) associates f with cancellation of ctx. Cancellation starts f in its own goroutine. If the context is already canceled at registration time, the callback is started promptly in a new goroutine rather than being invoked synchronously by the caller.

Stop reports prevention, not completion

The returned function has this shape:

stop := context.AfterFunc(ctx, f)
stopped := stop()

A true result means the call prevented f from running through that association. A false result has two permitted states: cancellation has already caused f to start, or an earlier call already stopped the association.

Those states have different consequences for shared resources. In the first state, cleanup performed by f can still be in progress after stop returns. In the second, no callback execution is pending from that association. The Boolean result alone does not distinguish them.

This makes stop different from an operation that joins a goroutine. It changes or observes the callback association; it does not establish that callback work has finished.

Cancellation creates a concurrency boundary

Consider a callback that mutates a connection deadline:

finished := make(chan struct{})

stop := context.AfterFunc(ctx, func() {
    conn.SetReadDeadline(time.Now())
    close(finished)
})

n, err := conn.Read(buf)
if !stop() {
    <-finished
    conn.SetReadDeadline(time.Time{})
}

If cancellation wins the race with stop, waiting on finished creates an explicit completion edge before the deadline is reset. Without that coordination, the reset can race logically with the callback’s deadline mutation even though both operations are individually valid method calls.

The relevant boundary is not merely whether cancellation occurred. It is whether callback effects that matter to subsequent code have completed.

Multiple registrations remain independent

Several AfterFunc calls attached to the same context do not replace one another. Each registration has its own callback association and its own stop function:

stopA := context.AfterFunc(ctx, func() { releaseA() })
stopB := context.AfterFunc(ctx, func() { releaseB() })

Stopping stopA does not stop the callback associated with stopB. Once cancellation starts callbacks, their execution also has no implied ordering. Code that requires ordering between effects must encode that ordering separately.

This independence matters when several components attach cleanup or wakeup behavior to a shared request context. The context supplies the cancellation event, but it does not serialize the resulting callback work.

Already-canceled contexts remove the pending phase

Registration against an already-canceled context starts the callback in a new goroutine immediately. There is no interval in which application code can rely on the association remaining pending after AfterFunc returns.

That property makes patterns based on “register now, stop on the next line” inherently race-sensitive when the input context may already be canceled. The stop result remains authoritative for whether prevention succeeded, but a failed stop still provides no completion guarantee.

Callback completion needs a separate signal

When later operations depend on callback effects, completion requires explicit coordination such as a channel, a sync.WaitGroup, or another synchronization primitive owned by the callback and its consumer.

This separation keeps two concerns distinct. AfterFunc connects callback start to context cancellation. The returned stop function can sever that connection while it is still pending. Neither mechanism acts as a general lifecycle join once callback execution has begun.

The practical boundary is precise: a successful stop prevents the registered callback from starting through that association; an unsuccessful stop must not be treated as evidence that callback effects are complete.