hare

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

commit 5f07cb9ab596705a42fba176e8183e42272fb42e
parent f54c20b2dec06cc862b429f642ea10bb52b0a478
Author: Drew DeVault <sir@cmpwn.com>
Date:   Mon, 25 Oct 2021 16:50:41 +0200

iobus: improve pool docs

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

Diffstat:
Miobus/io_uring/pool.ha | 27+++++++++++++++++++++------
1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/iobus/io_uring/pool.ha b/iobus/io_uring/pool.ha @@ -10,9 +10,24 @@ export type pool = struct { export type buffer = u16; -// Creates a new buffer pool for use with read operations. The buffer argument -// must be a slice whose length is divisible by bufsz, thus providing a buffer -// pool of N buffers where N is len(buffer) / bufsz. +// Creates a new buffer pool for use with read operations. The user can request +// pool use for an I/O request via [[setpool]], and the host will select a +// suitable buffer from the pool to perform the read request. The selected +// buffer can be determined from the [[result]] using [[getbuffer]]. The user +// should, after processing the results of the I/O operation, return the buffer +// to the pool with [[release]]. If no buffers were available, [[endread]] (or +// whichever "end" function is appropriate) will return [[nobuffers]]; in this +// case the user should release some buffers and re-submit the read later. +// +// The utility of this functionality is that the user may submit more reads than +// they have buffers allocated. For instance, a network server may allocate a +// pool of X buffers for reads, and submit reads for Y client connections, where +// X < Y. This allows the server software to support more connections without a +// corresponding increase in RAM utilization, albiet at the cost of limiting +// active connections to the number of available buffers. +// +// The buffer argument must be a slice whose length is divisible by bufsz, thus +// providing a buffer pool of N buffers where N is len(buffer) / bufsz. export fn newpool( bus: *bus, buffer: []u8, @@ -52,14 +67,14 @@ export fn setpool(handle: *handle, pool: pool) void = { // // Note that I/O operations which completed with an error condition will not // have a buffer assigned, even if [[setpool]] was called for the original -// handle. You must test for errors prior to calling [[getbuffer]] to avoid an -// assertion failure. +// handle. You must thus test for errors prior to calling [[getbuffer]], or risk +// causing an assertion failure. export fn getbuffer(pool: *pool, result: result) (buffer, []u8) = { let buf: buffer = io_uring::get_buffer_id(result); return (buf, pool.buffer[(buf * pool.bufsz)..((buf + 1) * pool.bufsz)]); }; -// Returns a buffer from [[getbuffer]] back to the buffer pool. +// Returns a buffer from [[getbuffer]] back to the buffer pool for future reads. export fn release(pool: *pool, buf: buffer) (void | queuefull) = { let sqe = getsqe(pool.bus)?; io_uring::provide_buffers(sqe, pool.group,