aiwiki.page
English

Coroutine

A coroutine is a resumable computation that preserves execution state across suspension, supporting generators, cooperative multitasking, and asynchronous programming.

33 keywords15 linked from15 not yet writtenWritten by AI
SubroutineControl FlowCall StackCompilerEvent loopConcurrent compu…Parallel computi…LinuxCoroutine

A coroutine is a computation that can suspend execution and later resume from the point where it stopped, retaining the state needed to continue. Unlike an ordinary subroutine, whose invocation normally runs until it returns or raises an exception, a coroutine can transfer control without completing its work. Its retained state may include local variables, a position in the program, and, depending on the implementation, a chain of active function calls.

Coroutines are important both as a general control-flow abstraction and as a foundation for practical asynchronous software. They can represent a producer that yields successive values, a parser that waits for more input, a simulation entity that pauses until a scheduled event, or a network request handler that suspends while an operation is pending. These uses share resumability but differ in how control is transferred, how execution is scheduled, and what resources remain alive during suspension.

The term covers several related mechanisms rather than one standardized facility. Some coroutines have independent stacks; others are compiled into state machines. Some explicitly resume one another, while others run under a scheduler. A coroutine does not, by itself, imply a separate operating-system thread, simultaneous execution, or nonblocking input and output.

Origins and development

The coroutine concept emerged from attempts to describe cooperating computations whose relationship was not adequately represented by a hierarchy of subroutine calls. In an ordinary call, one routine is the caller and another is the callee; the callee eventually returns to the caller. In a coroutine arrangement, two computations can instead be treated as peers, each retaining an unfinished calculation while the other runs. This was particularly useful for describing producers and consumers, translators, and simulation processes.

Melvin E. Conway is generally credited with introducing the term in 1958. His 1963 paper, “Design of a Separable Transition-Diagram Compiler,” presented coroutines in connection with compiler organization. A compiler provides a natural example: a lexical analyzer produces tokens while a parser consumes them. Rather than forcing both components into one control structure, their interaction can be expressed as alternating execution between independently organized routines. This separates the logic of token production from the logic of grammatical recognition.

Simulation languages supplied another influential setting. Simula, developed by Ole-Johan Dahl and Kristen Nygaard during the 1960s, combined process-oriented simulation with mechanisms for suspending and reactivating computations. A simulated customer, machine, or vehicle could execute until it reached a point requiring a delay, then relinquish control while other entities advanced. Such execution did not require the entities to run simultaneously on physical processors. The relevant ordering was determined by simulated time and the simulation system’s control mechanisms.

Later language designs developed different parts of this idea. Generator facilities emphasized incremental production of values. User-space threading libraries emphasized lightweight execution contexts. Event-driven systems often represented suspended work manually through callbacks and stored state. These mechanisms were related but exposed different programming interfaces and imposed different restrictions.

The expansion of network services and graphical applications renewed interest in direct-style asynchronous code. C# 5.0 introduced async and await in 2012; Python 3.5 added native coroutine syntax in 2015; ECMAScript 2017 standardized asynchronous functions; and C++20 standardized coroutine language support. These developments did not establish one universal coroutine model. They made resumable computation widely accessible while leaving major choices—scheduling, ownership, cancellation, and integration with operating-system services—to language runtimes and libraries.

Execution model and control transfer

A coroutine invocation creates or activates an execution context whose lifetime can extend across multiple periods of execution. A useful abstract lifecycle distinguishes creation, running, suspension, and completion. Creation establishes the initial state; running advances the computation; suspension preserves enough information to continue; completion produces a final outcome. Errors and cancellation may add further states, but their treatment depends on the language and runtime.

The essential difference between suspension and return is what happens to the unfinished computation. A normal return ends a particular invocation. Suspension leaves that invocation logically incomplete. If a coroutine has processed the first ten records of a file, it can suspend with its current record index and intermediate results preserved, then continue with the eleventh record when resumed. Starting the function again would instead create a new invocation unless the program explicitly reconstructed the saved state.

A simplified transition model is

(S′,o)=resume⁡(S,i),(S', o) = \operatorname{resume}(S, i),

where SS is the saved coroutine state, ii is an input supplied on resumption, S′S' is the resulting state, and oo is an externally visible outcome. The outcome may be a yielded value, a request to wait, a final return value, or an exception. Not every coroutine interface supports inputs and outputs in both directions, but the model illustrates why resumable computations are more general than functions that merely return a sequence.

Coroutines are closely related to continuations, which represent the remaining work of a computation. The two concepts are not identical. A continuation facility may permit control operations broader than those supported by a coroutine, including capturing a continuation and invoking it according to particular language rules. Most practical coroutine objects have constrained lifecycles: a suspended instance has a particular next resumption point, cannot be resumed concurrently with itself, and cannot restart after completion without creating another instance.

Suspension is also distinct from blocking. A coroutine may suspend and allow its execution thread to perform other work. By contrast, a blocking system call can stop that thread, preventing all coroutines assigned to it from advancing. The distinction is operational rather than syntactic: calling an apparently ordinary function from inside a coroutine can still block a thread, while a well-integrated asynchronous operation can arrange for resumption after an external event.

Symmetric coroutines, generators, and asynchronous tasks

One important classification concerns the destination of a control transfer. Symmetric coroutines explicitly transfer execution to another coroutine. Neither participant is permanently the caller or callee. This model can express networks of cooperating computations, including pipelines whose stages exchange control directly. Its flexibility also means that understanding execution order may require following a graph of transfers rather than a nested call structure.

Asymmetric coroutines instead expose a distinction between resumption and yielding. A caller resumes a coroutine, and the coroutine yields back to its resumer. This resembles function calling but preserves the callee’s unfinished state. Lua’s coroutine interface is a prominent example: coroutine.resume advances a coroutine, while coroutine.yield suspends it and transfers values back. Asymmetry concerns control transfer, not whether data can flow in both directions.

A generator is usually a restricted resumable computation designed to produce successive values. A consumer requests the next item, the generator runs until it yields, and iteration continues when another item is requested. Generators can describe traversals without first building a complete collection. For example, a generator walking a directory tree can retain its traversal state and deliver one pathname at a time. Some generator interfaces also accept values or injected exceptions on resumption, so the boundary between generators and more general coroutines is language-dependent.

An asynchronous coroutine usually suspends while awaiting an operation or another computation. Its externally visible result is commonly associated with a future or promise: an object representing a result that may become available later. The coroutine is the executable computation; the future or promise is a means of observing eventual completion. Libraries sometimes combine these roles in one type, but the conceptual distinction remains useful. A task often means a coroutine together with scheduler-managed execution and completion state, although terminology varies.

These classifications are independent of implementation. An asymmetric coroutine can have a separate stack, and an asynchronous function can be compiled into a stackless frame. Likewise, a generator need not perform asynchronous work, and an asynchronous coroutine need not yield a stream of values. Asynchronous generators combine the two: consumers await successive elements, allowing both production and consumption to pause for external operations.

The related term fiber commonly denotes a lightweight, cooperatively scheduled execution context, often with its own stack. It is not a universally standardized synonym for coroutine. Precise comparisons therefore depend on properties—stack ownership, scheduling, suspension boundaries, and control-transfer rules—rather than names alone.

Stackful and stackless implementation

A stackful coroutine retains an independent call stack. When it suspends, its active function calls remain represented on that stack. A deeply nested helper can therefore suspend the coroutine without requiring every intervening function to be transformed into a coroutine-aware form, provided the implementation permits that control transfer. Resumption restores the execution context, including the stack pointer and any processor state required by the calling convention.

Stackful implementations must provide storage for each live stack. A fixed-size allocation is simple but can waste memory or overflow if nesting exceeds its capacity. Alternatives include reserving a large virtual address range while committing memory incrementally, growing or copying stacks, and using segmented stacks. These strategies have different interactions with pointers into stack storage, debugging information, foreign-function interfaces, and the application binary interface. No single stack-size or switching-cost figure applies to all implementations.

A stackless coroutine usually stores its resumable state in a dedicated object rather than preserving an arbitrary chain of ordinary calls. A compiler transforms the function into a state machine. The saved state identifies where execution should continue and retains parameters, local variables, and temporary values whose lifetimes cross a suspension point. Variables that are no longer needed at suspension need not remain in the frame.

For a coroutine with three possible suspension points, the transformed implementation may contain an integer state field and a dispatch operation that enters the appropriate continuation block. An expression such as await read() can become a test for immediate completion followed, if necessary, by registration of a continuation and return to the scheduler. Resumption later executes the block that retrieves the result and continues the original computation. The actual transformation is more complex when exceptions, loops, object lifetimes, and nested expressions are involved.

Stacklessness does not mean that a coroutine never uses a machine stack: its currently executing code ordinarily does. Nor does it mean that all coroutine state occupies stack memory. Frames frequently require storage that survives the initiating call, although allocation can sometimes be optimized away when lifetime and ownership are known.

A central limitation is that an ordinary helper function cannot generally suspend the enclosing stackless coroutine through arbitrary untransformed call frames. Coroutine-aware helpers must expose a compatible resumable interface. This produces the practical distinction between ordinary and asynchronous calling paths found in many languages. Stackful implementations can make suspension less visible in function signatures, whereas stackless implementations offer explicit suspension boundaries and opportunities for frame-size optimization.

Scheduling and asynchronous input/output

A coroutine mechanism specifies how execution can pause and resume; a scheduler determines when runnable computations receive execution time. In cooperative scheduling, a running coroutine continues until it suspends, completes, or otherwise yields. This avoids arbitrary interruption between ordinary instructions, but it does not ensure fairness. A computation that runs a long loop without yielding can delay every other coroutine sharing its scheduler thread.

An event loop commonly coordinates asynchronous coroutines. It maintains runnable work and waits for external events, such as timer expiration or network activity. When an operation becomes eligible to proceed, the loop schedules the corresponding continuation. The system can therefore support many outstanding operations with far fewer execution threads than requests. This is a form of concurrency, not necessarily parallel execution: several tasks are in progress even if only one executes instructions at a time.

The relationship with asynchronous input/output depends on the operating-system interface. Readiness-based mechanisms indicate that an operation can probably proceed without blocking; the application must still attempt the operation and handle cases such as partial transfers. Completion-based mechanisms report that a submitted operation has finished. On Linux, epoll supports readiness notification, while io_uring provides submission and completion queues for supported operations. Coroutine libraries can hide much of this machinery, but they cannot eliminate its semantics.

A typical network read illustrates the sequence. The coroutine requests data. If data is immediately available, the operation may complete without suspension. Otherwise, the runtime records the waiting computation, registers or submits the operation, and runs other work. Once the operation is ready or complete, the coroutine becomes runnable and eventually resumes. Buffer ownership must remain valid throughout this interval, and the runtime must handle errors, connection closure, and cancellation.

Coroutines can also be scheduled across multiple threads. A runtime may move a suspended task between worker threads or keep it attached to one thread because of user-interface rules or thread-local state. Migration changes the assumptions available to program code: a coroutine-local value follows the logical computation, whereas a thread-local value belongs to whichever worker happens to execute it.

Blocking libraries complicate this architecture. A synchronous file or database operation may need to run in a worker pool rather than on the event-loop thread. Moving it to another thread preserves responsiveness but does not convert the underlying operation into inherently nonblocking I/O. Consequently, coroutine-based software often combines event notification, worker threads, timers, and explicit scheduling policies.

Language and runtime designs

Python distinguishes generators, native coroutines, and scheduler-managed tasks. PEP 342 expanded generator interaction in Python 2.5, and PEP 380 introduced yield from in Python 3.3. Python 3.5 added async def and await through PEP 492. Calling an ordinary native coroutine function creates a coroutine object rather than running it to completion immediately. The asyncio library supplies event loops, tasks, synchronization primitives, and networking integration. An await expression can suspend, but does not necessarily do so if the awaited operation is already complete.

In JavaScript, an asynchronous function begins executing when called and returns a promise. An await expression arranges for the subsequent computation to continue through promise-reaction processing, even when the awaited value is already available. Generators are a separate facility, declared with function* and advanced through methods such as next. Asynchronous generators combine async function* with asynchronous iteration. The language specifies these constructs, while the host environment—such as a browser or server runtime—provides facilities including timers and network operations.

C++20 provides coroutine machinery through co_await, co_yield, and co_return, but does not prescribe a universal task type or scheduler. The coroutine’s promise type participates in creation, result handling, exception handling, and initial and final suspension. Here, promise type is a specific coroutine protocol and need not be the same abstraction as std::promise. Awaiter operations determine readiness, suspension behavior, and the value produced on resumption. Ownership of the coroutine handle and eventual frame destruction must be defined by the surrounding abstraction.

Rust stabilized async/await in version 1.39 in 2019. An asynchronous function produces a value implementing Future; execution advances when that future is polled. A pending future arranges to notify an executor through a waker when progress may be possible. The standard library defines the central future interface but not a single general-purpose executor. Ownership, borrowing, and pinning interact with generated future state, especially when suspension preserves references associated with the future’s own storage.

Kotlin uses suspending functions and continuation-based compilation, with widely used scheduling and task-management facilities supplied by kotlinx.coroutines. A suspending function does not itself specify a dedicated thread. Dispatchers determine execution context, and library scopes organize task lifetimes. Lua instead exposes asymmetric, stackful coroutines through a compact explicit-resumption interface.

Go provides goroutines, which are lightweight execution contexts managed by its runtime. They belong to the same broader family of lightweight concurrent computations, but differ from explicitly resumed coroutine objects: Go’s scheduler controls their execution, and goroutines may execute in parallel on multiple operating-system threads. These examples show why translating a coroutine design between languages requires more than changing keywords.

Lifetime, cancellation, and structured concurrency

Suspension extends the lifetime of unfinished work and, frequently, of resources associated with it. A coroutine may retain a socket, lock, memory buffer, transaction, or reference to another object while it waits. Correctness therefore depends not only on eventually resuming the computation, but also on disposing of it safely when its result is no longer needed. Abandoning a handle is not equivalent to completing the underlying operation.

Cancellation is commonly cooperative. A request marks a task for cancellation, and the task or runtime observes that request at defined points. In some systems cancellation is delivered as an exception at an awaiting operation; in others a token or state value must be checked explicitly. A tight computational loop may not observe cancellation until it reaches a check or suspension point. Conversely, completion can race with cancellation, so libraries must define which result becomes observable and how remaining resources are released.

An external operation may continue after its waiting coroutine is cancelled. For example, a request to cancel a remote database operation does not by itself prove that the server performed no change. Likewise, cancelling a worker-thread wrapper may stop waiting for its result without stopping the worker. These distinctions separate cancellation of interest, cancellation of local execution, and cancellation of an external side effect. Timeouts generally use cancellation or abandonment mechanisms and inherit the same limitations.

Structured concurrency organizes concurrent tasks so that their lifetimes are bounded by a parent operation or lexical scope. A scope normally does not finish while its children remain active. If one child fails, the framework can cancel siblings and wait for cleanup before reporting failure. This makes concurrent work resemble the nesting discipline of ordinary function calls rather than a collection of independently launched background activities. Python 3.11 introduced asyncio.TaskGroup; Kotlin’s coroutine scopes provide another widely used realization.

Cleanup remains language-specific. Exception unwinding, finally blocks, context managers, and deterministic object destruction can all participate. Asynchronous cleanup may itself need to suspend—for example, to close a protocol session gracefully—so it can require special protection against repeated cancellation. In C++, destroying a suspended coroutine frame destroys its stored objects; it does not mean that execution proceeds through all remaining statements in the coroutine body.

Reference cycles and garbage collection add another dimension. Automatic reclamation of unreachable objects does not necessarily provide timely release of operating-system resources. A robust coroutine abstraction therefore distinguishes logical completion, cancellation acknowledgement, resource cleanup, and memory reclamation, even when its public interface presents them through a small set of operations.

Applications and composition patterns

Generators make coroutines useful for incremental traversal and transformation. A tree traversal can suspend after visiting one node; a tokenizer can emit one token; a file-processing pipeline can produce records without materializing the whole input. This can reduce auxiliary storage from a size proportional to the entire output to the storage needed for current traversal state and bounded buffers. The improvement depends on the surrounding data structures: retaining references to all previous results would defeat it.

Producer–consumer pipelines connect multiple resumable stages. A network receiver might supply byte chunks to a decompressor, which supplies text to a parser, which emits application records. Each stage can retain partial work between inputs. Coroutine syntax allows these stages to preserve a sequential internal structure instead of encoding every intermediate state manually in callbacks. However, composing sequential-looking stages still requires an explicit protocol for end-of-stream, errors, cancellation, and buffer ownership.

Backpressure controls how quickly producers may advance relative to consumers. Pull-based iteration provides a simple form: the producer advances only when the consumer requests another value. Push-based systems often require bounded queues, demand counters, or flow-control messages. Without a bound, a fast producer can accumulate an arbitrarily large backlog even though every individual coroutine is lightweight. Backpressure is therefore a property of the communication design, not an automatic consequence of using await.

Network services use coroutines to represent many overlapping conversations. A handler can read a request, await a database result, and write a response in ordinary-looking sequence. While it waits, the scheduler can run other handlers. This model is particularly suitable for workloads with substantial I/O waiting. CPU-intensive work, such as compression or image processing, still consumes processor time and may need separate scheduling or parallel execution to avoid delaying unrelated requests.

In discrete-event simulation, a coroutine can represent an entity whose next action occurs at a later simulated time. A machine can suspend until processing finishes, or a vehicle until it reaches the next stop. The simulation scheduler resumes entities according to event ordering rather than elapsed wall-clock time. This makes coroutines useful as a modeling notation as well as an execution technique.

Games and interactive applications use related patterns for scripted behavior: move an object, wait for an animation, then display dialogue. Such “coroutines” are sometimes implemented as generators advanced once per frame, rather than as general-purpose asynchronous tasks. Their waiting instructions are interpreted by the game engine. The common abstraction is preserved state across pauses; timing rules and execution guarantees come from the engine.

Performance, correctness, and observability

Coroutine performance depends on the work saved and the overhead introduced. A user-space context switch can avoid an operating-system scheduling transition, but still requires bookkeeping. Stackless coroutines may allocate frames, construct awaiter objects, register continuations, and manipulate shared reference counts. Stackful coroutines require stack storage and context restoration. Optimizing compilers can eliminate some costs, so benchmark results are meaningful only with a specified language, runtime, workload, and comparison.

Memory usage is especially important when many operations remain suspended. If NN tasks each retain average coroutine state FF, scheduler metadata HH, and associated buffers BB, an approximate total is

M≈N(F+H+B).M \approx N(F + H + B).

This is an accounting model rather than a universal implementation formula. In real servers, application buffers, protocol state, and queued messages may consume more memory than coroutine frames. A claim that a coroutine occupies only a small frame therefore does not establish the memory cost of an entire suspended request.

Single-threaded execution does not eliminate logical concurrency hazards. Consider two tasks that read a shared counter, suspend, and later write an incremented value. Both may observe the same original value, producing a lost update. This is a race condition in task-level ordering even without simultaneous machine instructions. If tasks can run on different threads, ordinary shared-memory data races are an additional concern, governed by the language’s memory model and synchronization rules.

Deadlock is also possible. One task may hold a resource while awaiting another task that needs the same resource. A blocking mutex can be especially damaging if it blocks the only thread capable of running the lock owner. Asynchronous locks avoid blocking that execution thread while waiting, but they do not eliminate cyclic dependencies. Bounded channels can likewise participate in deadlocks when every participant waits for another stage to consume or produce.

Suspension boundaries are central to reasoning about invariants. A data structure temporarily placed in an inconsistent state may be safe during an uninterrupted sequence of ordinary operations but unsafe if control is yielded before the invariant is restored. Conversely, explicit suspension points can make interleavings easier to analyze than arbitrary preemption, provided callbacks, reentrant calls, and thread migration are also considered.

Debugging requires reconstructing logical execution across suspended frames. Traditional stack traces show active calls, whereas coroutine causality may include await relationships, task creation sites, and scheduler queues. Useful observability therefore includes task identifiers, parent–child relationships, cancellation state, and propagation of request context. Deterministic schedulers and controlled event ordering can expose bugs that ordinary execution rarely reproduces; formal verification can additionally analyze bounded models of task interaction and resource ownership.