Documentation refactoring. No code changes. (0.40.5)
This commit is contained in:
parent
a47660edc7
commit
63545ed918
136 changed files with 374 additions and 3163 deletions
220
web/documentation/asyncio/asyncio.md
Normal file
220
web/documentation/asyncio/asyncio.md
Normal file
|
|
@ -0,0 +1,220 @@
|
|||
---
|
||||
layout: page
|
||||
published: true
|
||||
noToc: false
|
||||
noComments: false
|
||||
noDate: false
|
||||
title: Fun - Async I/O ("asyncio") in Fun
|
||||
subtitle: Async I/O primitives and patterns, non-blocking sockets, fd polling, examples, and best practices.
|
||||
description: Async I/O primitives and patterns, non-blocking sockets, fd polling, examples, and best practices.
|
||||
permalink: /documentation/asyncio/
|
||||
lang: en
|
||||
tags:
|
||||
- async
|
||||
- asyncio
|
||||
- best
|
||||
- blocking
|
||||
- examples
|
||||
- non
|
||||
- patterns
|
||||
- polling
|
||||
- practices
|
||||
- primitives
|
||||
- sockets
|
||||
---
|
||||
|
||||
|
||||
This guide explains the new asynchronous I/O primitives in Fun and how to use them to build non-blocking network and file descriptor workflows. It covers the core concepts, available helpers, common patterns, and runnable examples from the repository.
|
||||
|
||||
## What is asyncio in Fun?
|
||||
|
||||
In Fun, "asyncio" refers to event-driven, non-blocking I/O built around file descriptor readiness. Instead of blocking on reads/writes, you:
|
||||
- Put descriptors (sockets, pipes, etc.) into non-blocking mode
|
||||
- Wait for them to become readable/writable using polling helpers
|
||||
- Perform small, incremental reads/writes when the OS signals readiness
|
||||
|
||||
This lets a single Fun script handle many concurrent connections efficiently without threads, and keeps UIs or other work responsive while I/O is in flight.
|
||||
|
||||
There is no special syntax (like async/await) — you compose ordinary control flow with a few focused opcodes and stdlib functions.
|
||||
|
||||
However, for more ergonomic, "await-like" workflows without changing the VM, a tiny cooperative scheduler is provided in the stdlib at lib/async/scheduler.fun. It lets you write small step functions that advance per tick and use await_read/await_write wrappers for readability.
|
||||
|
||||
## Building blocks
|
||||
|
||||
Core helpers wired into the VM (see src/vm/os/*):
|
||||
- fd_set_nonblock(fd, on) → 1/0: enable or disable O_NONBLOCK on a file descriptor
|
||||
- fd_poll_read(fd, timeout_ms) → int: >0 if fd is readable; 0 on timeout; <0 on error
|
||||
- fd_poll_write(fd, timeout_ms) → int: >0 if fd is writable; 0 on timeout; <0 on error
|
||||
|
||||
Common networking helpers from the stdlib:
|
||||
- tcp_connect(host, port) → fd: open a TCP connection; returns 0 on failure
|
||||
- sock_send(fd, data) → int: send bytes (may write only part in non-blocking mode)
|
||||
- sock_recv(fd, max_bytes) → string: receive up to max_bytes; empty string on EOF
|
||||
- sock_close(fd): close the descriptor
|
||||
|
||||
Tip: Always check return values. In non-blocking mode, partial writes and short reads are normal.
|
||||
|
||||
## Typical patterns
|
||||
|
||||
1) Connect and switch to non-blocking
|
||||
<pre>fd = tcp_connect(host, port)
|
||||
if (fd == 0)
|
||||
// handle connect error
|
||||
ok = fd_set_nonblock(fd, 1)
|
||||
if (ok == 0)
|
||||
// handle mode switch error
|
||||
</pre>
|
||||
2) Non-blocking write loop with readiness polling
|
||||
<pre>remaining = req
|
||||
while (len(remaining) > 0)
|
||||
wr = fd_poll_write(fd, 1000) // wait up to 1s
|
||||
if (wr < 0)
|
||||
// poll error; abort
|
||||
if (wr == 0)
|
||||
continue // timeout; try again
|
||||
n = sock_send(fd, remaining)
|
||||
if (n < 0)
|
||||
// send error; abort
|
||||
remaining = substr(remaining, n, len(remaining) - n)
|
||||
</pre>
|
||||
3) Non-blocking read-until-close
|
||||
<pre>buf = ""
|
||||
while (true)
|
||||
rd = fd_poll_read(fd, 2000) // wait up to 2s
|
||||
if (rd < 0)
|
||||
// poll error; break
|
||||
if (rd == 0)
|
||||
// timeout: try a read to detect EOF
|
||||
data = sock_recv(fd, 4096)
|
||||
if (len(data) == 0)
|
||||
break // likely closed
|
||||
buf = buf + data
|
||||
continue
|
||||
data = sock_recv(fd, 4096)
|
||||
if (len(data) == 0)
|
||||
break // closed
|
||||
buf = buf + data
|
||||
</pre>
|
||||
## Timeouts and responsiveness
|
||||
|
||||
- timeout_ms controls how long poll waits. Use small timeouts inside loops to interleave work across multiple sockets or tasks.
|
||||
- A timeout result (0) is not an error — treat it as an opportunity to perform other duties and try again later.
|
||||
- Negative results (<0) indicate OS-level errors from poll/select; handle or abort as appropriate.
|
||||
|
||||
## Working with multiple connections
|
||||
|
||||
To multiplex several sockets:
|
||||
- Keep per-connection state (outgoing buffer, accumulate incoming, progress markers)
|
||||
- Round-robin over connections, polling each for read/write readiness with short timeouts
|
||||
- Advance each state machine a little per iteration
|
||||
|
||||
Because Fun keeps the primitives low-level and explicit, you can build simple cooperative schedulers, connection pools, or protocol handlers directly in Fun code.
|
||||
|
||||
## Examples in the repository
|
||||
|
||||
- examples/io/async_http_client.fun — Minimal HTTP GET over non-blocking TCP using fd_poll_* helpers
|
||||
- examples/io/await_http_client.fun — Same goal, but written using lib/async/scheduler.fun with await_* helpers
|
||||
- examples/net/http_mt_server.fun — Multi-tenant HTTP server scaffold (compare patterns for concurrency)
|
||||
- examples/net/http_mt_server_cgi.fun — Server variant that dispatches CGI-like handlers
|
||||
- lib/net/http_cgi_server.fun — Library helpers used by the server examples
|
||||
|
||||
Run client example from a build tree:
|
||||
<pre>FUN_LIB_DIR=./lib ./build/fun examples/io/async_http_client.fun
|
||||
</pre>
|
||||
If installed system-wide, just:
|
||||
<pre>fun /usr/share/fun/examples/io/async_http_client.fun
|
||||
</pre>
|
||||
Or to try the await-style client using the cooperative scheduler:
|
||||
<pre>FUN_LIB_DIR=./lib ./build/fun examples/io/await_http_client.fun
|
||||
</pre>
|
||||
## Cooperative scheduler helpers (library-level)
|
||||
|
||||
The file lib/async/scheduler.fun provides a minimal cooperative scheduler built on the existing primitives. There is no VM-level suspension: each task is a small state machine advanced one step per tick. API summary:
|
||||
|
||||
- task_spawn(step_fn, state_map) → task_handle
|
||||
- Registers a task. step_fn is a function that takes a Map state; mutate state and set state.done = 1 when complete.
|
||||
- run_once() → 1
|
||||
- Performs one scheduling tick over all runnable tasks.
|
||||
- run_until_done() → 1
|
||||
- Repeats run_once() with a tiny sleep_ms(1) until all tasks finish.
|
||||
- await_read(fd, timeout_ms) → int
|
||||
- Wrapper over fd_poll_read; returns 1 if readable, 0 on timeout/EOF, -1 on error.
|
||||
- await_write(fd, timeout_ms) → int
|
||||
- Wrapper over fd_poll_write; returns 1 if writable, 0 on timeout, -1 on error.
|
||||
- yield() → 1
|
||||
- No-op helper to make intent explicit in step functions.
|
||||
- async_sleep_mark(state, ms) → 1
|
||||
- Mark the task to be skipped for roughly ms milliseconds; cleared automatically when it wakes.
|
||||
|
||||
Example skeleton using the scheduler:
|
||||
<pre>#include <async/scheduler.fun>
|
||||
|
||||
fun my_task_step(t)
|
||||
if (t.phase == nil)
|
||||
t.phase = 0
|
||||
|
||||
if (t.phase == 0)
|
||||
t.fd = tcp_connect("example.org", 80)
|
||||
if (t.fd == 0)
|
||||
t.done = 1
|
||||
return
|
||||
fd_set_nonblock(t.fd, 1)
|
||||
t.phase = 1
|
||||
return
|
||||
|
||||
if (t.phase == 1)
|
||||
if (await_write(t.fd, 50) == 1)
|
||||
sock_send(t.fd, "GET / HTTP/1.1\r\nHost: example.org\r\n\r\n")
|
||||
t.buf = ""
|
||||
t.phase = 2
|
||||
return
|
||||
|
||||
if (t.phase == 2)
|
||||
rd = await_read(t.fd, 100)
|
||||
if (rd < 0)
|
||||
t.done = 1
|
||||
return
|
||||
if (rd == 0)
|
||||
// try a small read to detect EOF
|
||||
data = sock_recv(t.fd, 4096)
|
||||
if (len(data) == 0)
|
||||
t.done = 1
|
||||
else
|
||||
t.buf = t.buf + data
|
||||
return
|
||||
// readable
|
||||
data = sock_recv(t.fd, 4096)
|
||||
if (len(data) == 0)
|
||||
t.done = 1
|
||||
else
|
||||
t.buf = t.buf + data
|
||||
return
|
||||
|
||||
task = task_spawn(my_task_step, {})
|
||||
run_until_done()
|
||||
</pre>
|
||||
This approach is 100% compatible with current runtimes and serves as a stepping stone towards potential future VM-level async/await opcodes.
|
||||
|
||||
## Error handling and cleanup
|
||||
|
||||
- Always close descriptors with sock_close(fd) when finished or on error paths.
|
||||
- Distinguish between timeout (wr/rd == 0), EOF (len(recv) == 0), and errors (wr/rd < 0 or send < 0).
|
||||
- For large payloads, design your loops to tolerate partial progress and resume cleanly.
|
||||
|
||||
## FAQ
|
||||
|
||||
Q: Is there an async/await syntax?
|
||||
A: Not at this time. The model is explicit non-blocking I/O with polling helpers. You can build lightweight schedulers on top if desired.
|
||||
|
||||
Q: Does this work on all platforms?
|
||||
A: The helpers map to portable OS facilities exposed by the VM. Details may vary by platform; see documentation/troubleshooting.md and open an issue if you hit differences.
|
||||
|
||||
Q: How do I integrate with the REPL?
|
||||
A: You can prototype small non-blocking fragments in the REPL, but full networking examples are easier to run as scripts.
|
||||
|
||||
## See also
|
||||
|
||||
- [../examples/](../examples/) — Running bundled examples
|
||||
- [../includes/](../includes/) — Include paths and library discovery
|
||||
- [../opcodes/](../opcodes/) — VM opcodes overview
|
||||
- [../troubleshooting/](../troubleshooting/) — Common issues and quick fixes
|
||||
Loading…
Add table
Add a link
Reference in a new issue