This article's use of external links may not follow Wikipedia's policies or guidelines. Please improve this article by removing excessive or inappropriate external links, and converting useful links where appropriate into footnote references. (April 2024) (Learn how and when to remove this message)

Coroutines are computer program components that allow execution to be suspended and resumed, generalizing subroutines for cooperative multitasking. Coroutines are well-suited for implementing familiar program components such as cooperative tasks, exceptions, event loops, iterators, infinite lists and pipes.

They have been described as "functions whose execution you can pause".[1]

Melvin Conway coined the term coroutine in 1958 when he applied it to the construction of an assembly program.[2] The first published explanation of the coroutine appeared later, in 1963.[3]

Definition and types

There is no single precise definition of coroutine. In 1980 Christopher D. Marlin[4] summarized two widely-acknowledged fundamental characteristics of a coroutine:

  1. the values of data local to a coroutine persist between successive calls;
  2. the execution of a coroutine is suspended as control leaves it, only to carry on where it left off when control re-enters the coroutine at some later stage.

Besides that, a coroutine implementation has 3 features:

  1. the control-transfer mechanism. asymmetric coroutines usually provide keywords like yield and resume. Programmers cannot freely choose which frame to yield to. The runtime only yields to the nearest caller of the current coroutine. On the other hand, in symmetric coroutines, programmers must specify a yield destination.
  2. whether coroutines are provided in the language as first-class objects, which can be freely manipulated by the programmer, or as constrained constructs;
  3. whether a coroutine is able to suspend its execution from within nested function calls. Such a coroutine is a stackful coroutine. One to the contrary is called stackless coroutines, where unless marked as coroutine, a regular function can't use the keyword yield.

Revisiting Coroutines[5] published in 2009 proposed term full coroutine to denote one that supports first-class coroutine and is stackful. Full Coroutines deserve their own name in that they have the same expressive power as one-shot continuations and delimited continuations. Full coroutines are either symmetric or asymmetric. Importantly, whether a coroutine is symmetric or asymmetric has no bearing on how expressive it can be as they are equally as expressive, though full coroutines are more expressive than non-full coroutines. While their expressive power is the same, asymmetrical coroutines more closely resemble routine based control structures in the sense that control is always passed back to the invoker, which programmers may find more familiar.

Comparison with


Subroutines are special cases of coroutines.[6] When subroutines are invoked, execution begins at the start, and once a subroutine exits, it is finished; an instance of a subroutine only returns once, and does not hold state between invocations. By contrast, coroutines can exit by calling other coroutines, which may later return to the point where they were invoked in the original coroutine; from the coroutine's point of view, it is not exiting but calling another coroutine.[6] Thus, a coroutine instance holds state, and varies between invocations; there can be multiple instances of a given coroutine at once. The difference between calling another coroutine by means of "yielding" to it and simply calling another routine (which then, also, would return to the original point), is that the relationship between two coroutines which yield to each other is not that of caller-callee, but instead symmetric.

Any subroutine can be translated to a coroutine which does not call yield.[7]

Here is a simple example of how coroutines can be useful. Suppose you have a consumer-producer relationship where one routine creates items and adds them to a queue and another removes items from the queue and uses them. For reasons of efficiency, you want to add and remove several items at once. The code might look like this:

var q := new queue

coroutine produce
        while q is not full
            create some new items
            add the items to q
        yield to consume

coroutine consume
        while q is not empty
            remove some items from q
            use the items
        yield to produce

call produce

The queue is then completely filled or emptied before yielding control to the other coroutine using the yield command. The further coroutines calls are starting right after the yield, in the outer coroutine loop.

Although this example is often used as an introduction to multithreading, two threads are not needed for this: the yield statement can be implemented by a jump directly from one routine into the other.


Coroutines are very similar to threads. However, coroutines are cooperatively multitasked, whereas threads are typically preemptively multitasked. Coroutines provide concurrency, because they allow tasks to be performed out of order or in a changeable order, without changing the overall outcome, but they do not provide parallelism, because they do not execute multiple tasks simultaneously. The advantages of coroutines over threads are that they may be used in a hard-realtime context (switching between coroutines need not involve any system calls or any blocking calls whatsoever), there is no need for synchronization primitives such as mutexes, semaphores, etc. in order to guard critical sections, and there is no need for support from the operating system.

It is possible to implement coroutines using preemptively-scheduled threads, in a way that will be transparent to the calling code, but some of the advantages (particularly the suitability for hard-realtime operation and relative cheapness of switching between them) will be lost.


Main article: Generator (computer programming)

Generators, also known as semicoroutines,[8] are a subset of coroutines. Specifically, while both can yield multiple times, suspending their execution and allowing re-entry at multiple entry points, they differ in coroutines' ability to control where execution continues immediately after they yield, while generators cannot, instead transferring control back to the generator's caller.[9] That is, since generators are primarily used to simplify the writing of iterators, the yield statement in a generator does not specify a coroutine to jump to, but rather passes a value back to a parent routine.

However, it is still possible to implement coroutines on top of a generator facility, with the aid of a top-level dispatcher routine (a trampoline, essentially) that passes control explicitly to child generators identified by tokens passed back from the generators:

var q := new queue

generator produce
        while q is not full
            create some new items
            add the items to q

generator consume
        while q is not empty
            remove some items from q
            use the items

subroutine dispatcher
    var d := new dictionary(generatoriterator)
    d[produce] := start produce
    d[consume] := start consume
    var current := produce
        call current
        current := next d[current]

call dispatcher

A number of implementations of coroutines for languages with generator support but no native coroutines (e.g. Python[10] before 2.5) use this or a similar model.

Mutual recursion

Further information: Mutual recursion

Using coroutines for state machines or concurrency is similar to using mutual recursion with tail calls, as in both cases the control changes to a different one of a set of routines. However, coroutines are more flexible and generally more efficient. Since coroutines yield rather than return, and then resume execution rather than restarting from the beginning, they are able to hold state, both variables (as in a closure) and execution point, and yields are not limited to being in tail position; mutually recursive subroutines must either use shared variables or pass state as parameters. Further, each mutually recursive call of a subroutine requires a new stack frame (unless tail call elimination is implemented), while passing control between coroutines uses the existing contexts and can be implemented simply by a jump.

Common uses

Coroutines are useful to implement the following:

Native support

Coroutines originated as an assembly language method, but are supported in some high-level programming languages.

Since continuations can be used to implement coroutines, programming languages that support them can also quite easily support coroutines.


As of 2003, many of the most popular programming languages, including C and its derivatives, do not have built-in support for coroutines within the language or their standard libraries. This is, in large part, due to the limitations of stack-based subroutine implementation. An exception is the C++ library Boost.Context, part of boost libraries, which supports context swapping on ARM, MIPS, PowerPC, SPARC and x86 on POSIX, Mac OS X and Windows. Coroutines can be built upon Boost.Context.

In situations where a coroutine would be the natural implementation of a mechanism, but is not available, the typical response is to use a closure – a subroutine with state variables (static variables, often boolean flags) to maintain an internal state between calls, and to transfer control to the correct point. Conditionals within the code result in the execution of different code paths on successive calls, based on the values of the state variables. Another typical response is to implement an explicit state machine in the form of a large and complex switch statement or via a goto statement, particularly a computed goto. Such implementations are considered difficult to understand and maintain, and a motivation for coroutine support.

Threads, and to a lesser extent fibers, are an alternative to coroutines in mainstream programming environments today. Threads provide facilities for managing the real-time cooperative interaction of simultaneously executing pieces of code. Threads are widely available in environments that support C (and are supported natively in many other modern languages), are familiar to many programmers, and are usually well-implemented, well-documented and well-supported. However, as they solve a large and difficult problem they include many powerful and complex facilities and have a correspondingly difficult learning curve. As such, when a coroutine is all that is needed, using a thread can be overkill.

One important difference between threads and coroutines is that threads are typically preemptively scheduled while coroutines are not. Because threads can be rescheduled at any instant and can execute concurrently, programs using threads must be careful about locking. In contrast, because coroutines can only be rescheduled at specific points in the program and do not execute concurrently, programs using coroutines can often avoid locking entirely. This property is also cited as a benefit of event-driven or asynchronous programming.

Since fibers are cooperatively scheduled, they provide an ideal base for implementing coroutines above.[23] However, system support for fibers is often lacking compared to that for threads.


In order to implement general-purpose coroutines, a second call stack must be obtained, which is a feature not directly supported by the C language. A reliable (albeit platform-specific) way to achieve this is to use a small amount of inline assembly to explicitly manipulate the stack pointer during initial creation of the coroutine. This is the approach recommended by Tom Duff in a discussion on its relative merits vs. the method used by Protothreads.[24][non-primary source needed] On platforms which provide the POSIX sigaltstack system call, a second call stack can be obtained by calling a springboard function from within a signal handler[25][26] to achieve the same goal in portable C, at the cost of some extra complexity. C libraries complying to POSIX or the Single Unix Specification (SUSv3) provided such routines as getcontext, setcontext, makecontext and swapcontext, but these functions were declared obsolete in POSIX 1.2008.[27]

Once a second call stack has been obtained with one of the methods listed above, the setjmp and longjmp functions in the standard C library can then be used to implement the switches between coroutines. These functions save and restore, respectively, the stack pointer, program counter, callee-saved registers, and any other internal state as required by the ABI, such that returning to a coroutine after having yielded restores all the state that would be restored upon returning from a function call. Minimalist implementations, which do not piggyback off the setjmp and longjmp functions, may achieve the same result via a small block of inline assembly which swaps merely the stack pointer and program counter, and clobbers all other registers. This can be significantly faster, as setjmp and longjmp must conservatively store all registers which may be in use according to the ABI, whereas the clobber method allows the compiler to store (by spilling to the stack) only what it knows is actually in use.

Due to the lack of direct language support, many authors have written their own libraries for coroutines which hide the above details. Russ Cox's libtask library[28] is a good example of this genre. It uses the context functions if they are provided by the native C library; otherwise it provides its own implementations for ARM, PowerPC, Sparc, and x86. Other notable implementations include libpcl,[29] coro,[30] lthread,[31] libCoroutine,[32] libconcurrency,[33] libcoro,[34] ribs2,[35] libdill.,[36] libaco,[37] and libco.[26]

In addition to the general approach above, several attempts have been made to approximate coroutines in C with combinations of subroutines and macros. Simon Tatham's contribution,[38] based on Duff's device, is a notable example of the genre, and is the basis for Protothreads and similar implementations.[39] In addition to Duff's objections,[24] Tatham's own comments provide a frank evaluation of the limitations of this approach: "As far as I know, this is the worst piece of C hackery ever seen in serious production code."[38] The main shortcomings of this approximation are that, in not maintaining a separate stack frame for each coroutine, local variables are not preserved across yields from the function, it is not possible to have multiple entries to the function, and control can only be yielded from the top-level routine.[24]



C# 2.0 added semi-coroutine (generator) functionality through the iterator pattern and yield keyword.[44][45] C# 5.0 includes await syntax support. In addition:


Cloroutine is a third-party library providing support for stackless coroutines in Clojure. It's implemented as a macro, statically splitting an arbitrary code block on arbitrary var calls and emitting the coroutine as a stateful function.


D implements coroutines as its standard library class Fiber A generator makes it trivial to expose a fiber function as an input range, making any fiber compatible with existing range algorithms.


Go has a built-in concept of "goroutines", which are lightweight, independent processes managed by the Go runtime. A new goroutine can be started using the "go" keyword. Each goroutine has a variable-size stack which can be expanded as needed. Goroutines generally communicate using Go's built-in channels.[46][47][48][49]


There are several implementations for coroutines in Java. Despite the constraints imposed by Java's abstractions, the JVM does not preclude the possibility.[50] There are four general methods used, but two break bytecode portability among standards-compliant JVMs.



Kotlin implements coroutines as part of a first-party library.


Lua has supported first-class stackful asymmetric coroutines since version 5.0 (2003),[52] in the standard library coroutine.[53][54]


Modula-2 as defined by Wirth implements coroutines as part of the standard SYSTEM library.

The procedure NEWPROCESS() fills in a context given a code block and space for a stack as parameters, and the procedure TRANSFER() transfers control to a coroutine given the coroutine's context as its parameter.


The Mono Common Language Runtime has support for continuations,[55] from which coroutines can be built.

.NET Framework

During the development of the .NET Framework 2.0, Microsoft extended the design of the Common Language Runtime (CLR) hosting APIs to handle fiber-based scheduling with an eye towards its use in fiber-mode for SQL server.[56] Before release, support for the task switching hook ICLRTask::SwitchOut was removed due to time constraints.[57] Consequently, the use of the fiber API to switch tasks is currently not a viable option in the .NET Framework.[needs update]


OCaml supports coroutines through its Thread module.[58] These coroutines provide concurrency without parallelism, and are scheduled preemptively on a single operating system thread. Since OCaml 5.0, green threads are also available; provided by different modules.


Coroutines are natively implemented in all Raku backends.[59]




Racket provides native continuations, with a trivial implementation of coroutines provided in the official package catalog. Implementation by S. De Gabrielle



Since Scheme provides full support for continuations, implementing coroutines is nearly trivial, requiring only that a queue of continuations be maintained.


Since, in most Smalltalk environments, the execution stack is a first-class citizen, coroutines can be implemented without additional library or VM support.

Tool Command Language (Tcl)

Since version 8.6, the Tool Command Language supports coroutines in the core language. [62]


Vala implements native support for coroutines. They are designed to be used with a Gtk Main Loop, but can be used alone if care is taken to ensure that the end callback will never have to be called before doing, at least, one yield.

Assembly languages

Machine-dependent assembly languages often provide direct methods for coroutine execution. For example, in MACRO-11, the assembly language of the PDP-11 family of minicomputers, the "classic" coroutine switch is effected by the instruction "JSR PC,@(SP)+", which jumps to the address popped from the stack and pushes the current (i.e that of the next) instruction address onto the stack. On VAXen (in VAX MACRO) the comparable instruction is "JSB @(SP)+". Even on a Motorola 6809 there is the instruction "JSR [,S++]"; note the "++", as 2 bytes (of address) are popped from the stack. This instruction is much used in the (standard) 'monitor' Assist 09.

See also


  1. ^ "How the heck does async/await work in Python 3.5?". Tall, Snarky Canadian. 2016-02-11. Retrieved 2023-01-10.
  2. ^ Knuth, Donald Ervin (1997). Fundamental Algorithms (PDF). The Art of Computer Programming. Vol. 1 (3rd ed.). Addison-Wesley. Section 1.4.5: History and Bibliography, pp. 229. ISBN 978-0-201-89683-1. Archived (PDF) from the original on 2019-10-21.
  3. ^ Conway, Melvin E. (July 1963). "Design of a Separable Transition-diagram Compiler" (PDF). Communications of the ACM. 6 (7). ACM: 396–408. doi:10.1145/366663.366704. ISSN 0001-0782. S2CID 10559786 – via ACM Digital Library.
  4. ^ Marlin, Christopher (1980). Coroutines: A Programming Methodology, a Language Design and an Implementation. Springer. ISBN 3-540-10256-6.
  5. ^ Ana Lucia de Moura; Roberto Ierusalimschy (2009). "Revisiting Coroutines". ACM Transactions on Programming Languages and Systems. 31 (2): 1–31. CiteSeerX doi:10.1145/1462166.1462167. S2CID 9918449.
  6. ^ a b Knuth, Donald Ervin (1997). Fundamental Algorithms. The Art of Computer Programming. Vol. 1 (3rd ed.). Addison-Wesley. Section 1.4.2: Coroutines, pp. 193–200. ISBN 978-0-201-89683-1.
  7. ^ Perlis, Alan J. (September 1982). "Epigrams on programming". ACM SIGPLAN Notices. 17 (9): 7–13. doi:10.1145/947955.1083808. S2CID 20512767. Archived from the original on January 17, 1999. 6. Symmetry is a complexity reducing concept (co-routines include sub-routines); seek it everywhere
  8. ^ Anthony Ralston (2000). Encyclopedia of computer science. Nature Pub. Group. ISBN 978-1-56159-248-7. Retrieved 11 May 2013.
  9. ^ See for example The Python Language Reference " 5.2.10. Yield expressions]":
    "All of this makes generator functions quite similar to coroutines; they yield multiple times, they have more than one entry point and their execution can be suspended. The only difference is that a generator function cannot control where should the execution continue after it yields; the control is always transferred to the generator's caller."
  10. ^ Mertz, David (July 1, 2002). "Generator-based State Machines". Charming Python. IBM developerWorks. Archived from the original on February 28, 2009. Retrieved Feb 2, 2011.
  11. ^ "Coroutine: Type-safe coroutines using lightweight session types".
  12. ^ "Co-routines in Haskell".
  13. ^ "The Coroutines Module (coroutines.hhf)". HLA Standard Library Manual.
  14. ^ "New in JavaScript 1.7". Archived from the original on 2009-03-08. Retrieved 2018-06-18.
  15. ^ "Julia Manual - Control Flow - Tasks (aka Coroutines)".
  16. ^ "What's New in Kotlin 1.1".
  17. ^ "Lua 5.2 Reference Manual".
  18. ^ "Python async/await Tutorial". Stack Abuse. December 17, 2015.
  19. ^ "8. Compound statements — Python 3.8.0 documentation".
  20. ^ "Gather and/or Coroutines". 2012-12-19.
  21. ^ Dahl, O.J.; Hoare, C.A.R., eds. (1972). "Hierarchical Program Structures". Structured Programming. London, UK: Academic Press. pp. 175–220. ISBN 978-0-12-200550-3.
  22. ^ McCartney, J. "Rethinking the Computer Music Programming Language: SuperCollider". Computer Music Journal, 26(4):61-68. MIT Press, 2002.
  23. ^ Implementing Coroutines for .NET by Wrapping the Unmanaged Fiber API Archived 2008-09-07 at the Wayback Machine, Ajai Shankar, MSDN Magazine
  24. ^ a b c "Coroutines in C – brainwagon". 5 March 2005.
  25. ^ Ralf S. Engelschall (18–23 June 2000). Portable Multithreading – The Signal Stack Trick For User-Space Thread Creation (PS). USENIX Annual Technical Conference. San Diego, USA.
  26. ^ a b "libco".[permanent dead link]
  27. ^ "getcontext(3) - Linux manual page".
  28. ^ - Russ Cox's libtask coroutine library for FreeBSD, Linux, Mac OS X, and SunOS
  29. ^ Portable Coroutine Library - C library using POSIX/SUSv3 facilities
  30. ^ Archived 2006-01-10 at the Wayback Machine - Edgar Toernig's coro library for x86, Linux & FreeBSD
  31. ^ - lthread is a multicore/multithread coroutine library written in C
  32. ^ "libcoroutine: A portable coroutine implementation". Archived from the original on 2019-11-12. Retrieved 2013-09-06. for FreeBSD, Linux, OS X PPC and x86, SunOS, Symbian and others
  33. ^ "libconcurrency - A scalable concurrency library for C". a simple C library for portable stack-switching coroutines
  34. ^ "libcoro: C-library that implements coroutines (cooperative multitasking) in a portable fashion". used as the basis for the Coro perl module.
  35. ^ "RIBS (Robust Infrastructure for Backend Systems) version 2: aolarchive/ribs2". August 13, 2019 – via GitHub.
  36. ^ "libdill". Archived from the original on 2019-12-02. Retrieved 2019-10-21.
  37. ^ "A blazing fast and lightweight C asymmetric coroutine library 💎 ⛅🚀⛅🌞: hnes/libaco". October 21, 2019 – via GitHub.
  38. ^ a b Simon Tatham (2000). "Coroutines in C".
  39. ^ "Stackless coroutine implementation in C and C++: jsseldenthuis/coroutine". March 18, 2019 – via GitHub.
  40. ^ - Technical specification for coroutines
  41. ^ - Current compiler support for standard coroutines
  42. ^ - Open Source and Mozy: The Debut of Mozy Code
  43. ^ - EricWF: Coroutines are now in Clang Trunk! Working on the Libc++ implementation now.
  44. ^ Wagner, Bill (11 November 2021). "Iterators". C# documentation. Microsoft – via Microsoft Learn.
  45. ^ Wagner, Bill (13 February 2023). "The history of C#". C# documentation. Microsoft. C# version 2.0 – via Microsoft Learn.
  46. ^ "Goroutines - Effective Go". Retrieved 2022-11-28.
  47. ^ "Go statements - The Go Specification". Retrieved 2022-11-28.
  48. ^ "Goroutines - A Tour of Go". Retrieved 2022-11-28.
  49. ^ "Frequently Asked Questions (FAQ) - The Go Programming Language".
  50. ^ Lukas Stadler (2009). "JVM Continuations" (PDF). JVM Language Summit.
  51. ^ Remi Forax (19 November 2009). "Holy crap: JVM has coroutine/continuation/fiber etc". Archived from the original on 19 March 2015.
  52. ^ "Lua version history".
  53. ^ de Moura, Ana Lúcia; Rodriguez, Noemi; Ierusalimschy, Roberto. "Coroutines in Lua" (PDF). Retrieved 24 April 2023.
  54. ^ de Moura, Ana Lúcia; Rodriguez, Noemi; Ierusalimschy, Roberto (2004). "Coroutines in Lua". Journal of Universal Computer Science. 10 (7): 901--924.
  55. ^ Mono Continuations
  56. ^ , Chris Brumme, cbrumme's WebLog
  57. ^ kexugit (15 September 2005). "Fiber mode is gone..." Retrieved 2021-06-08.
  58. ^ "The threads library".
  59. ^ "RFC #31".
  60. ^ "What's New in Python 3.7". Retrieved 10 September 2021.
  61. ^ "semi-coroutines". Archived from the original on October 24, 2007.
  62. ^ "coroutine manual page - Tcl Built-In Commands". Retrieved 2016-06-27.
  63. ^ Ritchie, Dennis M. (1980). "The evolution of the unix time-sharing system". Language Design and Programming Methodology. Lecture Notes in Computer Science. Vol. 79. pp. 25–35. doi:10.1007/3-540-09745-7_2. ISBN 978-3-540-09745-7. S2CID 571269. Archived from the original on 2015-04-08. Retrieved 2011-01-26.

Further reading