zigcoro

[mighty portal]

https://github.com/rsepassi/zigcoro

An implementation of stackful asymmetric coroutines in Zig (and some assembly).

Allows for 3 kinds of usage: suspend/resume, yield/next (coroutine-based generators), and async/await.

Supports Mac, Linux, and Windows, x86_64 and aarch64 (x86_64 under CI on GitHub).

Planning on hooking this up with libuv or libxev soon so that I can start using async/await-like code before (stackless) async lands.

Was fun learning some simple assembly and exploring how clean and powerful coroutines can be. Curious to hear what you think, if you see places where things can be improved, or if you'd like to see or contribute some features. It's my second Zig library, so any and all comments welcome!

[neat quail]

@echo pier :)

[next python]

more coroutines libs

lel

[heavy bolt]

Looking neat, but I dont understand the Performance section:
I am looking at "2 coroutines millions of times." and suddently at the bottom comes up "Verified that a Linux box with ~400GB of memory can spawn and swap between 100M simple coroutines without issue."

I guess that are 2 different benchmark setups you did, which would be nice to be explicit about.
Also, it would be very nice, if the user could reproduce the benchmarks.

[mighty portal]

Thanks! I updated the performance section to separate out the 2 benchmarks and provide the command for the second one (number of coroutines) (previously there was just the command for the context switch cost). Let me know what you think. https://github.com/rsepassi/zigcoro#performance

[heavy bolt]

Looking good.

Thanks for making it understandable and reproducible.

[mighty portal]

for sure! thanks for taking a look

[mighty portal]

v0.2 (https://github.com/rsepassi/zigcoro) now wraps async IO functionality provided by libxev (https://github.com/mitchellh/libxev).

Check out the tests for usage: https://github.com/rsepassi/zigcoro/blob/main/aio_test.zig.

[next python]

i have my own in my game engine, is fun seeing other takes

[mighty portal]

sweet. have a link? coros plus asyncio give "Fibers", i.e. lightweight threads. next bit i'm thinking about is how to cleanly enable parallel io so that you can launch a bunch of stuff and wait for its completion (either asReady or waitAll). seems like a FiberPool and Futures of some kind might be the way to go. not sure yet, but would be curious about others' takes.

[low idol]

a quick question i am quite curious about..
how did you embed assembly in the library?
the gcc asm syntax is quite confusing to me, so i wonder how you solved that :)

[echo pier]

u just do it: https://github.com/kprotty/zefi/blob/main/src/fiber.zig
in their case though, they @embedFile https://github.com/rsepassi/zigcoro/blob/main/coro_base.zig#L11

[low idol]

aaaa that's good to know. Tysm 🥰

[mighty portal]

Update: v0.3.0 provides asyncio.run to run a coroutine from the top-level and asyncio.xawait to launch and await several coroutines concurrently. Starting to feel pretty close to async/await.

[mighty portal]

Update: v0.4.0 has an API that lines up with Zig's 0.10.1/expected async API. I wrote up what the translation would look like here: https://github.com/rsepassi/zigcoro#switching-to-zigs-asyncawait. Seems to me like it'd be a trivial switch, but I wonder if I'm missing anything; would be nice to get another pair of eyes on it. @echo pier you seem to be Zig's concurrency king :), would love to get your thoughts if you end up taking a look.

[echo pier]

this looks like a nice api (might steal it for zefi). Although i think youd need to have xsuspend take a function to call for the suspend block

[mighty portal]

thanks! yeah, go for it. seeming like we can really get started with stackful async/await and have it be a trivial swap later. on suspend blocks: yeah, i suppose that's a missing feature in zigcoro right now...let me see what i can do.

i haven't needed it, even when integrating with the libxev event loop, so i'm not really sure what it's use case is...

the v0.10.1 documentation (https://ziglang.org/documentation/0.10.1/#Resuming-from-Suspend-Blocks) talks about using the block to grab the frame pointer and stash it somewhere for later resume, but it doesn't seem necessary to have a block to do that. with the libxev integration, i grab the frame pointer, stash it, and then suspend.

but for completeness/parity, it'd be nice to support it...

[echo pier]

without it, i believe you can only have single threaded event loops:

store(xframe())
// here: another thread could xload() then xresume() before xsuspend()
xsuspend()

the block runs after the coroutine state has been suspended/set so its ok to resume it in the block without racing (so thats where youd store the frame)

guess you could also technically have xasync/xresume hold a lock on the frame while its running to prevent that (but thats kinda inefficient)

[mighty portal]

hmm...yeah i haven't yet considered multi-threading in detail. i suppose having the discipline of only stashing frames in suspend blocks ensures that you can't resume a still-running coroutine...

[echo pier]

thinking about it more, it could actually be solved with a single atomic u8, instead of a suspend block or lock

[mighty portal]

exactly what i was thinking!

the coro status could be atomic

CoroStatus is currently enum { Start, Suspended, Active, Done }

just because you have a frame pointer doesn't mean it's safe to resume the coro. so the suspend block doesn't really seem to buy you anything safety wise.

[echo pier]

xresumes try to CAS it from suspend->active or from active->notified (new state). When a suspend ends, it either transitions from active->suspended, or notified->active and resumes itself again (to account for any racing xresumes)

[mighty portal]

is the new state needed for functionality? seems like we could just make the invariant that xresume only works if status is Start/Suspended. on resume, atomic swap to Active. on suspend, atomic swap to Suspended. on completion, atomic swap to Done. error otherwise.

and if you want to wait, you can wait

[echo pier]

If so, you have to make sure xresume() is only called on a suspended frame, which you cant in ^ this situation without external synchronization or a suspend block

suspend block grants you MT-safe resumes without synchronization
lock grants you same but with synchronization and potential thread blocking
atomic u8 grants you same with synchronization but non-blocking

[mighty portal]

hmm...so is it illegal/compile error to call @frame outside of a suspend block? also even with that, there's no guarantees on the frame pointer lifetime. i.e. you can stash that somewhere and then at runtime illegally call resume on a frame that can't be resumed. what did 0.10 do in that case? runtime error?

[echo pier]

you can call frame outside suspend block i.e. single threaded event loops or even to implement frame-local (like threadlocal) state. The lifetime issue also occurs without a suspend block (e.g. xresume(xframe())). In 0.10, its designated as UB to do that, but similar to undefined being 0xaaaaa, it added some atomic checks to print out an error to try and help debugging

[mighty portal]

ok, i think i'm seeing. the suspend block allows for the communication to another thread to be guaranteed to be after suspend. that way you don't need any additional work to check if the frame is resumable.

[echo pier]

yea, guaranteed to be resumable in the block. I think it can be implemented with like an extra function pointer on a stackful coroutine thats called after xsuspend() switches stacks. Or tail called in the stack switching logic itself

https://github.com/golang/go/blob/master/src/runtime/proc.go#L381
https://github.com/golang/go/blob/master/src/runtime/proc.go#L3738

tbh, you could just say dont use lib in multi-threaded setting. Could reserve threads for thread pools which are stackless coroutines or straight data parallelism, and stackful concurrency for single thread event loops

[mighty portal]

yeah, for now the lib is definitely only usable single-threaded, which is fine bc libxev is single-threaded (i.e. all completion callbacks run on the loop thread)

but i'd like to make things usable multi-threaded; at first, without coro migration, and then later with

let me see what i can do with suspend blocks...seems like i could smuggle a couple pointers to the resumer (function pointer, data pointer) and then call the fn if present. so the block would run in the resumer's coroutine.

will report back soon.

[mighty portal]

@echo pier https://github.com/rsepassi/zigcoro/pull/7

[mint cape]

wow "all vector registers are call-clobbered" is a great decision for those of us who want to jump between stacks

[mighty portal]

? are they? i don't have it tested but in the aarch64 assembly, we do preserve the fp/vec registers: https://github.com/rsepassi/zigcoro/blob/main/src/coro_aarch64.s#L8-L12

section 5.1.2 here: https://c9x.me/compile/bib/abi-arm64.pdf

and for x86, the vector/fp registers are caller-saved, not callee-saved https://gitlab.com/x86-psABIs/x86-64-ABI

(am i misreading your snark? lmk if there's functionality that you'd like to see)

@mint cape

i believe for x86 microsoft it's the same

[mighty portal]

wait sorry, lied about microsoft, but my previous self did the right thing https://github.com/rsepassi/zigcoro/blob/main/src/coro_x86_64_windows.s

https://learn.microsoft.com/en-us/cpp/build/x64-calling-convention?view=msvc-170#callercallee-saved-registers

windows requires the callee to save the vec registers, and zigcoro does that

[mighty portal]

@echo pier Cleaned up xsuspendBlock with anytype so that the caller doesn't need to see the anyopaques https://github.com/rsepassi/zigcoro/blob/a6569a895f3559b8da9775039e348f3a31d5ee4b/src/coro.zig#L133

[mighty portal]

v0.5.0 adds Channels to allow for communicating between coroutines.

https://github.com/rsepassi/zigcoro

[mint cape]

sorry, no snark and no feature requests, I meant it's just great that switching can be so cheap in sysv abi.

[austere condor]

is the CoroT stuff meant to be public? its documented and the functions are public but not the struct itself