1Curio
2=====
3
4Curio is a coroutine-based library for concurrent Python systems
5programming using async/await. It provides standard programming
6abstractions such as as tasks, sockets, files, locks, and queues as
7well as some advanced features such as support for structured
8concurrency. It works on Unix and Windows and has zero dependencies.
9You'll find it to be familiar, small, fast, and fun.
10
11Curio is Different
12------------------
13One of the most important ideas from software architecture is the
14"separation of concerns." This can take many forms such as utilizing
15abstraction layers, object oriented programming, aspects, higher-order
16functions, and so forth. However, another effective form of it exists
17in the idea of separating execution environments. For example, "user
18mode" versus "kernel mode" in operating systems. This is the
19underlying idea in Curio, but applied to "asynchronous" versus
20"synchronous" execution.
21
22A fundamental problem with asynchronous code is that it involves a
23completely different evaluation model that doesn't compose well with
24ordinary applications or with other approaches to concurrency such as
25thread programing. Although the addition of "async/await" to Python
26helps clarify such code, "async" libraries still tend to be a confused
27mess of functionality that mix asynchronous and synchronous
28functionality together in the same environment--often bolting it all
29together with an assortment of hacks that try to sort out all of
30associated API confusion.
31
32Curio strictly separates asynchronous code from synchronous code.
33Specifically, *all* functionality related to the asynchronous
34environment utilizes "async/await" features and syntax--without
35exception. Moreover, interactions between async and sync code is
36carefully managed through a small set of simple mechanisms such as
37events and queues. As a result, Curio is small, fast, and
38significantly easier to reason about.
39
40A Simple Example
41-----------------
42
43Here is a concurrent TCP echo server directly implemented using sockets:
44
45.. code:: python
46
47 # echoserv.py
48
49 from curio import run, spawn
50 from curio.socket import *
51
52 async def echo_server(address):
53 sock = socket(AF_INET, SOCK_STREAM)
54 sock.setsockopt(SOL_SOCKET, SO_REUSEADDR, 1)
55 sock.bind(address)
56 sock.listen(5)
57 print('Server listening at', address)
58 async with sock:
59 while True:
60 client, addr = await sock.accept()
61 await spawn(echo_client, client, addr, daemon=True)
62
63 async def echo_client(client, addr):
64 print('Connection from', addr)
65 async with client:
66 while True:
67 data = await client.recv(100000)
68 if not data:
69 break
70 await client.sendall(data)
71 print('Connection closed')
72
73 if __name__ == '__main__':
74 run(echo_server, ('',25000))
75
76If you've done network programming with threads, it looks almost
77identical. Moreover, it can handle thousands of clients even though no
78threads are being used inside.
79
80Core Features
81-------------
82
83Curio supports standard synchronization primitives (events, locks,
84recursive locks, semaphores, and condition variables), queues,
85subprocesses, as well as running tasks in threads and processes. The
86task model fully supports cancellation, task groups, timeouts,
87monitoring, and other features critical to writing reliable code.
88
89Read the `official documentation <https://curio.readthedocs.io>`_ for
90more in-depth coverage. The `tutorial
91<https://curio.readthedocs.io/en/latest/tutorial.html>`_ is a good
92starting point. The `howto
93<https://curio.readthedocs.io/en/latest/howto.html>`_ describes how to
94carry out common programming tasks.
95
96Talks Related to Curio
97----------------------
98
99Concepts related to Curio's design and general issues related to async
100programming have been described by Curio's creator, `David Beazley <https://www.dabeaz.com>`_, in
101various conference talks and tutorials:
102
103* `Build Your Own Async <https://www.youtube.com/watch?v=Y4Gt3Xjd7G8>`_, Workshop talk by David Beazley at PyCon India, 2019.
104
105* `The Other Async (Threads + Asyncio = Love) <https://www.youtube.com/watch?v=x1ndXuw7S0s>`_, Keynote talk by David Beazley at PyGotham, 2017.
106
107* `Fear and Awaiting in Async <https://www.youtube.com/watch?v=E-1Y4kSsAFc>`_, Keynote talk by David Beazley at PyOhio 2016.
108
109* `Topics of Interest (Async) <https://www.youtube.com/watch?v=ZzfHjytDceU>`_, Keynote talk by David Beazley at Python Brasil 2015.
110
111* `Python Concurrency from the Ground Up (LIVE) <https://www.youtube.com/watch?v=MCs5OvhV9S4>`_, talk by David Beazley at PyCon 2015.
112
113Questions and Answers
114---------------------
115
116**Q: What is the point of the Curio project?**
117
118A: Curio is async programming, reimagined as something smaller, faster, and easier
119to reason about. It is meant to be both educational and practical.
120
121**Q: Is Curio implemented using asyncio?**
122
123A: No. Curio is a standalone library directly created from low-level I/O primitives.
124
125**Q: Is Curio meant to be a clone of asyncio?**
126
127A: No. Although Curio provides a significant amount of overlapping
128functionality, the API is different. Compatibility with other
129libaries is not a goal.
130
131**Q: Is Curio meant to be compatible with other async libraries?**
132
133A: No. Curio is a stand-alone project that emphasizes a certain
134software architecture based on separation of environments. Other
135libraries have largely ignored this concept, preferring to simply
136provide variations on the existing approach found in asyncio.
137
138**Q: Can Curio interoperate with other event loops?**
139
140A: It depends on what you mean by the word "interoperate." Curio's
141preferred mechanism of communication with the external world is a
142queue. It is possible to communicate between Curio, threads, and
143other event loops using queues.
144
145**Q: How fast is Curio?**
146
147A: Curio's primary goal is to be an async library that is minimal and
148understandable. Performance is not the primary concern. That said, in
149rough benchmarking of a simple echo server, Curio is more than twice
150as fast as comparable code using coroutines in ``asyncio`` or
151``trio``. This was last measured on OS-X using Python 3.9. Keep in
152mind there is a lot more to overall application performance than the
153performance of a simple echo server so your mileage might
154vary. However, as a runtime environment, Curio doesn't introduce a lot of
155extra overhead. See the ``examples/benchmark`` directory for various
156testing programs.
157
158**Q: What is the future of Curio?**
159
160A: Curio should be viewed as a library of basic programming
161primitives. At this time, it is considered to be
162feature-complete--meaning that it is not expected to sprout many new
163capabilities. It may be updated from time to time to fix bugs or
164support new versions of Python.
165
166**Q: Can I contribute?**
167
168A: Curio is not a community-based project seeking developers
169or maintainers. However, having it work reliably is important. If you've
170found a bug or have an idea for making it better, please
171file an `issue <https://github.com/dabeaz/curio>`_.
172
173Contributors
174------------
175
176The following people contributed ideas to early stages of the Curio project:
177Brett Cannon, Nathaniel Smith, Alexander Zhukov, Laura Dickinson, and Sandeep Gupta.
178
179Who
180---
181Curio is the creation of David Beazley (@dabeaz) who is also
182responsible for its maintenance. http://www.dabeaz.com
183
184P.S.
185----
186If you want to learn more about concurrent programming more generally, you should
187come take a `course <https://www.dabeaz.com/courses.html>`_!
188
189.. |--| unicode:: U+2013 .. en dash
190.. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace
191 :trim:
192
193
194
195