The Hare programming language
git clone https://git.torresjrjr.com/hare.git
Log | Files | Refs | README | LICENSE

commit c83ea0ad8f75018700ce6942abd6e29988dfab5c
parent 021d33e70c674ce10d1d04c1f74a79ba21646ae0
Author: Drew DeVault <sir@cmpwn.com>
Date:   Tue, 19 Oct 2021 13:35:44 +0200

iobus: expand README

Signed-off-by: Drew DeVault <sir@cmpwn.com>

Miobus/README | 39++++++++++++++++++++++++++++++++++++++-
1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/iobus/README b/iobus/README @@ -1 +1,38 @@ -The iobus module implements a multiplexer for I/O operations. +The iobus module provides a multiplexer for asynchronous I/O operations. + +A [[bus]] object manages the submission of I/O operations to the host operating +system and maintains the state associated with these. The implementation is +abstracted over various backend implementations which are selected from based on +the host platform, such as io_uring or kqueue. + +The core of iobus is the event loop. The application using iobus will generally +follow these steps: + +- Create an iobus with [[new]], and optionally register a set of [[io::file]]s + or buffers with the bus using [[register_file]] or [[register_buffer]]. +- Create I/O handles (e.g. via [[read]]) and [[enqueue]] or [[submit]] them. +- Dispatch the bus with [[dispatch]], blocking until at least one operation is + complete and returning its [[result]]. +- Process the results of the completed I/O operation (e.g. with [[endread]]), + mark it as [[done]], then re-enter the event loop. + +The event loop will resemble the following: + + let bus = iobus::new(); + defer iobus::destroy(bus); + + // Prepare and submit/enqueue I/O handles as necessary + + for (true) { + const res = iobus::dispatch(); + // Dispatch the result back to the subsystem which created the + // handle, or allow callbacks to process it. + iobus::done(res); + }; + +It is the user's responsibility to ensure that each [[handle]]'s lifetime lasts +for the full duration of the I/O operation. The return value from [[read]] et al +is stack-allocated, and you may wish to pass this to "alloc" (freeing it later, +perhaps in the [[callback]] via [[handleof]]) to persist it. Alternative memory +management strategies may be more suited to your needs, this is left at the +programmer's discretion.