Update asyncio module for task-like execution (#6)

Add top-level run for coroutine kick-off.
Add asyncio.xawait for parallel execution.
Store everything but the return value in the coro stack.
Ensure coroutines have a stable parent that's yielded to on
return.
Remove unnecessary constCast in coro storage.
Clean up aio tests.
Update readme

Author: rsepassi

README.md

@@ -2,17 +2,7 @@
 
 Async Zig as a library using stackful asymmetric coroutines.
 
-* Stackful: each coroutine has an explicitly allocated stack and
-  suspends/yields preserve the entire call stack of the coroutine. An
-  ergonomic "stackless" implementation would require language support and
-  that's what we expect to see with Zig's async functionality.
-* Asymmetric: coroutines are nested such that there is a "caller"/"callee"
-  relationship, starting with a root coroutine per thread. The caller coroutine
-  is the parent such that upon completion of the callee (the child coroutine),
-  control will transfer to the caller. Intermediate yields/suspends transfer
-  control to the last resuming coroutine.
-
-Async IO is provided by [`libxev`][libxev].
+Supports async IO via [`libxev`][libxev].
 
 ---
 
@@ -23,18 +13,15 @@ supports {Linux, Mac} `aarch64`.*
 
 ## Current status
 
-*Updated 2023/09/06*
+*Updated 2023/09/08*
 
 Alpha, WIP.
 
-Further exploring (structured) concurrency and cooperative multitasking atop
-`libxev` using coroutines.
+Currently fleshing out async io atop `libxev`. See [TODOs](#TODO) for current work.
 
 ## Coroutine API
 
 ```
-stackAlloc(allocator, size)->[]u8
-remainingStackSize()->usize
 xcurrent()->*Coro
 xcurrentStorage(T)->*T
 xresume(*coro)
@@ -43,28 +30,38 @@ Coro
   init(*func, *stack, ?*storage)
   getStorage(T)
 CoroFunc(Fn)
-  init(.{args})
-  initPtr(&fn, .{args})
-  coro(*stack)->Coro
-  xresumeStart()->YieldT
-  xresume(inject)->YieldT
-  xresumeEnd(inject)->ReturnT
+  init()
+  coro(args, stack)->Coro
+  coroPtr(func, args, stack)->Coro
+  xnextStart(coro)->YieldT
+  xnext(coro, inject)->YieldT
+  xnextEnd(coro, inject)->ReturnT
   xyield(yield)->InjectT
-StackCoro
-  init(*func, .{args}, *stack)
-  frame(*func, coro)->CoroFunc(Fn)
+  xreturned(coro)->ReturnT
+
+# Stack utilities
+stackAlloc(allocator, size)->[]u8
+remainingStackSize()->usize
 ```
 
 ## Async IO API
 
-`libcoro.xev.aio` provides coroutine-friendly wrappers to all the [high-level
-async APIs][libxev-watchers] in [`libxev`][libxev].
+[`libcoro.asyncio`][aio] provides coroutine-based async IO functionality
+building upon the evented IO system of [`libxev`][libxev]. It provides
+coroutine-friendly wrappers to all the [high-level async
+APIs][libxev-watchers] in [`libxev`][libxev].
 
-See
-[`aio_test.zig`](https://github.com/rsepassi/zigcoro/blob/main/aio_test.zig)
-for usage examples.
+See [`test_aio.zig`][test-aio] for usage examples.
 
 ```
+# Run top-level coroutines in the event loop
+run
+runCoro
+
+# Concurrently run N coroutines and wait for all to complete
+xawait
+
+# IO
 sleep
 TCP
   accept
@@ -89,17 +86,11 @@ Async
   wait
 ```
 
-Stackful asymmetric coroutines provide a clean way of wrapping up async IO
-functionality, providing a programming model akin to threads (where the lightweight
-versions are variously called Coroutines, Green Threads, or Fibers). Calls to
-IO functionality are blocking from the perspective of the coroutine, but many
-coroutines can be running on the same thread.
+The IO functions are run from within a coroutine and appear as blocking, but
+internally they suspend so that other coroutines can progress.
 
-Under the hood, what's required is async IO functionality, such that a coroutine
-can submit work to be done, suspend, and then be resumed when the work is complete.
-Libraries like [libuv][libuv] and [libxev][libxev] provide cross-platform async IO,
-and this is a new Zig project, so why not depend on another new Zig project like
-libxev?
+To run several coroutines concurrently, create the coroutines and pass them
+to `asyncio.xawait`.
 
 ## Depend
 
@@ -116,15 +107,6 @@ const libcoro = b.dependency("zigcoro", .{}).module("libcoro");
 my_lib.addModule("libcoro", libcoro);
 ```
 
-## Coroutine Examples
-
-*TODO: Fill back in*
-
-* resume, suspend
-* storage
-* args, return
-* yield, inject
-
 ## Performance
 
 I've done some simple benchmarking on the cost of context switching and on
@@ -216,17 +198,38 @@ ns/ctxswitch: 233
 ...
 ```
 
+## Stackful asymmetric coroutines
+
+* Stackful: each coroutine has an explicitly allocated stack and
+  suspends/yields preserve the entire call stack of the coroutine. An
+  ergonomic "stackless" implementation would require language support and
+  that's what we expect to see with Zig's async functionality.
+* Asymmetric: coroutines are nested such that there is a "caller"/"callee"
+  relationship, starting with a root coroutine per thread. The caller coroutine
+  is the parent such that upon completion of the callee (the child coroutine),
+  control will transfer to the caller. Intermediate yields/suspends transfer
+  control to the last resuming coroutine.
+
+The wonderful 2009 paper ["Revisiting Coroutines"][coropaper] describes the
+power of stackful asymmetric coroutines in particular and their various
+applications, including nonblocking IO.
+
 ## Future work
 
 Contributions welcome.
 
+* Multi-threading support
+* Simple coro stack allocator, reusing stacks
 * Libraries
-  * (WIP) Task library: schedulers, futures, cancellation
+  * TLS, HTTP, WebSocket
+  * Actors
   * Recursive data structure iterators
   * Parsers
+* Alternative async IO loops (e.g. libuv)
 * Debugging
     * Coro names
     * Tracing tools
+    * Dependency graphs
     * Detect incomplete coroutines
     * ASAN, TSAN, Valgrind support
 * Make it so that it's as easy as possible to switch to Zig's async when it's
@@ -240,7 +243,11 @@ Contributions welcome.
 
 ### TODO
 
-* Revisit CoroFunc state machine:
+* Concurrent execution with async/await-like semantics and helpers
+  (waitAll, waitFirst, asReady, ...).
+* Cancellation and timeouts
+* Async iterators
+* Better coroutine error propagation
   * If a coroutine errors, it will be in the Done state and retval will be set
     to the error. The caller in that situation will have to test whether the
     coro is Done to call xreturned instead of xnext. The YieldT should probably
@@ -249,7 +256,8 @@ Contributions welcome.
 ## Inspirations
 
 * ["Revisiting Coroutines"][coropaper] by de Moura & Ierusalimschy
-* [Lua coroutines](https://www.lua.org/pil/9.1.html)
+* [Lua coroutines][lua-coro]
+* ["Structured Concurrency"][struccon] by Eric Niebler
 * https://github.com/edubart/minicoro
 * https://github.com/kurocha/coroutine
 * https://github.com/kprotty/zefi
@@ -260,3 +268,7 @@ Contributions welcome.
 [libxev]: https://github.com/mitchellh/libxev
 [libxev-watchers]: https://github.com/mitchellh/libxev/tree/main/src/watcher
 [libuv]: https://libuv.org
+[struccon]: https://ericniebler.com/2020/11/08/structured-concurrency
+[aio]: https://github.com/rsepassi/zigcoro/blob/main/src/asyncio.zig
+[test-aio]: https://github.com/rsepassi/zigcoro/blob/main/src/test_aio.zig
+[lua-coro]: https://www.lua.org/pil/9.1.html

benchmark.zig

@@ -28,9 +28,9 @@ fn contextSwitchBm() !void {
         {
             var test_coro = try libcoro.Coro.init(testFn, stack, null);
             for (0..num_bounces) |_| {
-                libcoro.xresume(&test_coro);
+                libcoro.xresume(test_coro);
             }
-            libcoro.xresume(&test_coro);
+            libcoro.xresume(test_coro);
         }
 
         num_bounces = 20_000_000;
@@ -39,14 +39,14 @@ fn contextSwitchBm() !void {
 
             const start = std.time.nanoTimestamp();
             for (0..num_bounces) |_| {
-                libcoro.xresume(&test_coro);
+                libcoro.xresume(test_coro);
             }
             const end = std.time.nanoTimestamp();
             const duration = end - start;
             const ns_per_bounce = @divFloor(duration, num_bounces * 2);
             std.debug.print("ns/ctxswitch: {d}\n", .{ns_per_bounce});
 
-            libcoro.xresume(&test_coro);
+            libcoro.xresume(test_coro);
         }
     }
 }
@@ -113,7 +113,7 @@ fn ncorosBm(num_coros: usize) !void {
     std.debug.print("Running {d} coroutines for {d} rounds\n", .{ num_coros, rounds });
 
     // number of coroutines benchmark
-    var coros = try allocator.alloc(libcoro.Coro, num_coros);
+    var coros = try allocator.alloc(*libcoro.Coro, num_coros);
     defer allocator.free(coros);
 
     var buf = try allocator.alloc(u8, num_coros * 1024 * 4);
@@ -130,7 +130,7 @@ fn ncorosBm(num_coros: usize) !void {
 
     var start = std.time.nanoTimestamp();
     for (0..rounds) |i| {
-        for (coros) |*coro| {
+        for (coros) |coro| {
             libcoro.xresume(coro);
         }
         if ((i + 1) % batching == 0) {

build.zig

@@ -8,7 +8,7 @@ pub fn build(b: *std.Build) !void {
 
     // Module
     const coro = b.addModule("libcoro", .{
-        .source_file = .{ .path = "src/coro.zig" },
+        .source_file = .{ .path = "src/main.zig" },
         .dependencies = &[_]std.Build.ModuleDependency{
             .{ .name = "xev", .module = xev },
         },