nish/net/postgres-async
PgAsyncPool, PostgreSQL connections an async task awaits a query on, so a task's query waits on its socket while the executor runs the others.
import {
PG_ASYNC_CANCELLED,
PG_ASYNC_MAX_DEPTH,
PG_ASYNC_MAX_SIZE,
PG_ASYNC_MAX_STATEMENTS,
PG_ASYNC_UNSENT,
PG_ASYNC_UNSENT_CANCELLED,
PgAsyncParams,
PgAsyncPool,
PgAsyncResult,
pgAsyncAnswer,
pgAsyncClaim,
pgAsyncConnect,
pgAsyncDone,
pgAsyncPrepare,
pgAsyncQuery,
pgAsyncRelease,
pgAsyncSeat,
pgAsyncSend,
pgAsyncTurn,
} from "nish/net/postgres-async";
import { spawn } from "nish:async"
import { secret, wipe } from "nish:secret"
import { PgConfig, pgTarget } from "nish/net/postgres"
import {
PgAsyncParams, PgAsyncPool, pgAsyncClaim, pgAsyncConnect, pgAsyncQuery, pgAsyncRelease,
} from "nish/net/postgres-async"
const title = async (pool: PgAsyncPool, id: i32): Promise<void> => {
const ticket: i32 = await pgAsyncClaim(pool)
if (ticket < 0) {
return // no live connection, or none came free in time
}
const params = new PgAsyncParams()
params.int(id)
const r = await pgAsyncQuery(pool, ticket, "select title from article where id = $1", params)
pgAsyncRelease(pool, ticket, r.reusable)
if (r.ok() && r.rows > 0) {
console.log(r.text(0, 0))
}
}
export const main = async (): Promise<i32> => {
const config = new PgConfig()
config.user = "app"
const pool = new PgAsyncPool(4)
const password = secret(passwordBytes()) // the program's own source
const live: i32 = await pgAsyncConnect(pool, config, password, pgTarget("127.0.0.1", 5432))
wipe(password)
spawn(title(pool, 1))
spawn(title(pool, 2))
// ... and close the pool once the tasks are done: `pool.close()`.
return live === pool.size ? 0 : 1
}
pgAsyncAnswer
Builds the seat's answer, in the calling task's memory, from what pgAsyncTurn read, reading the rest of an answer past the pool's input from the socket, never past its ReadyForQuery.
pgAsyncClaim
Claims a free connection for the calling task, the whole of it: one with no pipelined statement in flight.
pgAsyncConnect
Connects every slot of pool that is not connected, one after another, and authenticates each on a PgConnection (startup, then SCRAM-SHA-256 or trust), which wipes its copy of the password once the proof is made and is then dropped.
pgAsyncDone
Spends the seat's ticket once its answer is built: the connection moves past the answer, the next seat in its order is served, and the tasks waiting for room are woken.
pgAsyncPrepare
Registers a statement the pipelined calls run by its number, prepared once on each connection, the first time a task sends it there.
pgAsyncQuery
Runs one statement on the ticket's connection: Parse, Bind (each parameter in text), Execute and Sync go out in one write, and the answer is read to its ReadyForQuery, waiting on the socket while other tasks run.
pgAsyncRelease
Gives a claimed connection back, or closes it when reusable is false, and wakes the tasks waiting for one; the ticket is spent either way, and a ticket that is not the slot's current claim (a second release, or one after close()) panics.
pgAsyncSeat
Takes a seat for one statement on a shared connection: the live one with the fewest statements in flight, below pool.depth, that no task claimed whole and no task is writing to.
pgAsyncSend
Writes the seat's statement: its Parse the first time the connection runs it, then Bind (each parameter in text), Execute and Sync, whole, waiting on the socket while other tasks run.
pgAsyncTurn
Waits for the seat's turn and reads its answer off the connection: the statements seated before it are answered first, to their own tasks, and what they read past their own answers begins this one.
PgAsyncParams
A query's parameters, in text, in the order $1, $2, ... name them.
PgAsyncPool
Authenticated PostgreSQL connections that spawned tasks share.
PgAsyncResult
One query's answer, in the task's own memory: its rows as text, its tag, and how it ended.
Why separate calls
A spawned task shares the pool with the function that
spawned it, and runs in memory of its own that is freed when it ends
(docs/LANGUAGE.md → "What spawn may pass"). So a call that writes into
the pool may allocate nothing, and one that allocates may not write into
it: pgAsyncClaim and pgAsyncRelease write only numbers into the pool,
and pgAsyncQuery only reads it, building its buffers, rows and strings in
the task's own memory. One async function doing all three would be
refused when a task calls it ("hands pool to ..., which may grow it").
The flow
pgAsyncConnect, in main or any function that is not a
spawned task, connects each slot and runs its startup and SCRAM exchange
on a PgConnection, which then wipes the password and is dropped: the
pool keeps only the authenticated socket, so it holds no Secret and a
task may be handed it. pgAsyncClaim gives a task a ticket for one free
connection; pgAsyncQuery writes Parse, Bind, Execute and Sync in one go
(the parameters in text, never spliced into the SQL), waits on writable
and readable for the socket while the executor runs the others, and reads
to the ReadyForQuery; pgAsyncRelease gives the connection back, or closes
it when the query left it unfit to reuse.
Pipelining
Many tasks may share one connection instead of claiming
it whole. pgAsyncPrepare registers a statement's SQL once, before the
tasks run, and each task then runs it in five calls:
const ticket: i32 = await pgAsyncSeat(pool, statement) // a place in a connection's order
if (ticket >= 0) {
const sent: i32 = await pgAsyncSend(pool, ticket, params) // Bind, Execute, Sync
const turn: i32 = await pgAsyncTurn(pool, ticket, sent) // the answers before it, then its own
const r = await pgAsyncAnswer(pool, ticket, turn) // its rows, in the task's memory
pgAsyncDone(pool, ticket, turn, r.reusable)
}
Up to pool.depth statements are in flight on a connection at once, and
its answers come back in the order they were sent; each task waits for the
answers before its own on the pool's wake and reads its own when its turn
comes, so one read often brings several. Each connection parses a
statement once, named, and sends only Bind and Execute after; a Parse the
server refused is sent again next time. Each statement has its own Sync, so
a statement the server refuses fails alone. A pipelined statement whose
task is cancelled before its answer is read fails alone too: its seat is
abandoned, and the next task to read the connection reads past that
answer. A connection is out of step when an answer behind which others
wait is lost (a socket error, a frame this module does not expect, an
abandoned answer that left a transaction open or changed a setting): every
statement behind it fails PG_ERR_CLOSED, and the connection closes once
the last is answered.
Its own encoder and framer
A query is encoded and its answer framed
here (pgAsyncEncode, pgAsyncRead), not by PgConnection or
PgCarrier: those keep their buffers and rows in objects that outlive a
query, which a task would have to grow inside the pool, and a
PgConnection holds the password as a Secret, which a task may not be
handed. The framer applies the same checks as PgConnection's (PG-28 in
docs/security/postgres.md).
Claiming
When every live connection is claimed or in use,
pgAsyncClaim (and pgAsyncSeat, when none has room) waits on the pool's
wake, a socket pair pgAsyncRelease and each answer read write a byte to,
until one is free or it has waited claimWaitMs in all; nothing polls on a
clock. A ticket names a slot and that slot's
claim: pgAsyncQuery and pgAsyncRelease panic on one that is not the
slot's current claim, so two tasks never share a connection and a
connection is given back once.
Reuse
A connection is given back only when its last query read to a
ReadyForQuery that says "idle" and changed no session setting: a query that
left a transaction open, a SET the server reported (a ParameterStatus),
a socket error, a frame this module does not expect, a reply past a cap,
or bytes after the ReadyForQuery closes it, so the next task never inherits
another's session or the rest of its answer.
Limits. PgAsyncPool's caps (maxMessage, maxColumns, maxRows,
maxResultBytes, claimWaitMs) bound what one query keeps; rows past
maxRows or maxResultBytes are read and dropped, and the query fails
with PG_ERR_TOO_BIG. pgAsyncConnect gives each connection at most
connectWaitMs (10 s) to connect and finish its startup. A query's wait
has no deadline of its own: a server that accepts and never answers holds
the task until it closes or the task is cancelled; bound a slow statement
with the server's statement_timeout too.
Cancellation
A task that is cancelled (nish:async's cancel, a
cancelAfter deadline, or nish/net/serve when the client hangs up, the
request's deadline passes or the server drains) stops waiting at once.
pgAsyncClaim and pgAsyncSeat answer PG_ASYNC_CANCELLED and take
nothing; a query
not yet sent fails with nothing written and its connection reusable; a
query cut off mid-answer fails with PG_ERR_CLOSED, socketError
PG_ASYNC_CANCELLED and reusable false, so the task's
pgAsyncRelease closes the connection, whose unread answer would put the
next task out of step. A pipelined statement (pgAsyncSeat) cancelled
after it was sent fails the same way but alone: its seat is abandoned, and
the task behind it, or the next to ask for a seat, reads its answer and
drops it, so the connection stays when that answer is a plain one. No
CancelRequest is sent: the server runs the statement on to its end (or,
for a released connection, until it sees the socket closed).
Memory
Run each query in a spawned task, as title does above: the
task's region, and every buffer, row and string the query built in it,
is freed when the task ends, so Arena.used() stays where it was across
thousands of queries. A query awaited outside a task, through a function
that is handed the pool, keeps what it built until an enclosing scope
ends (about 9 KB a query, measured while writing
tests/link/std_postgres_async_flat).
Errors
A query answers PG_CARRIER_DONE, or PG_CARRIER_FAILED with
failure a PG_ERR_* and socketError a negative errno, as
nish/net/postgres-carrier does: PG_ERR_NONE when the server refused the
statement (errorCode and errorMessage say why, and the connection is
reused), PG_ERR_CLOSED when the socket ended, a wait could not be made or
the task was cancelled (socketError PG_ASYNC_CANCELLED).
Programming errors (a ticket that is not a current claim, a size or a cap
out of range) panic.
tests/link/std_postgres_async runs one against a loopback backend;
tests/link/std_postgres_async_pipeline pipelines statements from many tasks;
tests/link/std_postgres_async_flat reads Arena.used() across thousands
of queries. Caps and findings: docs/security/postgres.md.
Written for this module; not ported from another implementation.
Functions
pgAsyncAnswer
Builds the seat's answer, in the calling task's memory, from what
pgAsyncTurn read, reading the rest of an answer past the pool's input
from the socket, never past its ReadyForQuery. A statement the server
refuses fails alone (each has its own Sync); one seated behind a refused
Parse fails with SQLSTATE 26000 and the next one parses again. A frame
this module does not expect or a cap past which it cannot be read fails it
with reusable false. It only reads the pool, so a spawned task may call
it.
const pgAsyncAnswer: (
pool: PgAsyncPool,
ticket: i32,
turn: i32,
) => Promise<PgAsyncResult>
poolPgAsyncPoolrequiredThe pool the ticket came from; a cap out of its range panics.
ticketi32required
The ticket pgAsyncTurn used; any other panics, as does a
ticket whose turn has not come.
turni32required
What pgAsyncTurn answered; one below 0 fails the answer
without reading, with PG_ERR_ENCODING for a parameter that could not be
sent and PG_ERR_CLOSED otherwise.
returnsPromise<PgAsyncResult>The answer; its reusable goes to pgAsyncDone.
pgAsyncClaim
Claims a free connection for the calling task, the whole of it: one with
no pipelined statement in flight. While every live one is busy it waits
until pgAsyncRelease or a pipelined answer frees one and wakes it, for at
most pool.claimWaitMs in all. A cancelled task claims nothing, so a
connection is never taken by a task that would close it at its first wait.
It writes only numbers into the pool, so a spawned task may call it.
const pgAsyncClaim: (pool: PgAsyncPool) => Promise<i32>
poolPgAsyncPoolrequiredThe pool.
returnsPromise<i32>
A ticket (0 or more) for pgAsyncQuery and then exactly one
pgAsyncRelease; PG_POOL_NONE (-1) when no slot is connected;
PG_CARRIER_FULL (-2) when none came free in time;
PG_ASYNC_CANCELLED (-3) when the calling task is cancelled, before or
while it waits.
pgAsyncConnect
Connects every slot of pool that is not connected, one after another,
and authenticates each on a PgConnection (startup, then SCRAM-SHA-256 or
trust), which wipes its copy of the password once the proof is made and
is then dropped. Call it from main or another function that is not a
spawned task: it holds the password. A slot that fails stays unconnected;
call it again to retry.
const pgAsyncConnect: (
pool: PgAsyncPool,
config: PgConfig,
password: Secret<u8[]>,
target: PgTarget,
) => Promise<i32>
poolPgAsyncPoolrequiredThe pool to fill.
configPgConfigrequiredThe startup parameters and caps for the handshake.
passwordSecret<u8[]>requiredThe role's password as UTF-8 bytes; copied for each connection, so the caller wipes its own afterwards.
targetPgTargetrequired
Where the server is, as pgTarget made it; a TCP host must
be a numeric address, and a target that failed panics.
returnsPromise<i32>The number of slots connected after the call.
pgAsyncDone
Spends the seat's ticket once its answer is built: the connection moves past the answer, the next seat in its order is served, and the tasks waiting for room are woken. A Parse that failed is sent again by the next seat that runs the statement; an answer that left the connection unfit fails the seats behind it, and the connection closes once the last of them is answered. It writes only numbers into the pool, so a spawned task may call it.
const pgAsyncDone: (
pool: PgAsyncPool,
ticket: i32,
turn: i32,
reusable: boolean,
) => void
poolPgAsyncPoolrequiredThe pool the ticket came from.
ticketi32required
The ticket pgAsyncAnswer used; it is spent here, and any
other panics.
turni32requiredWhat pgAsyncTurn answered.
reusablebooleanrequiredThe answer's reusable.
pgAsyncPrepare
Registers a statement the pipelined calls run by its number, prepared once
on each connection, the first time a task sends it there. Call it from
main or another function that is not a spawned task, before the tasks
start: it grows the pool.
const pgAsyncPrepare: (
pool: PgAsyncPool,
sql: string,
) => i32
poolPgAsyncPoolrequiredThe pool.
sqlstringrequiredOne statement, $1, $2, ... naming the parameters.
returnsi32
The statement's number for pgAsyncSeat, 0 or more; -1 when the
SQL holds a NUL or PG_ASYNC_MAX_STATEMENTS are registered already.
pgAsyncQuery
Runs one statement on the ticket's connection: Parse, Bind (each parameter in text), Execute and Sync go out in one write, and the answer is read to its ReadyForQuery, waiting on the socket while other tasks run. It only reads the pool; its buffers and the answer are the calling task's.
const pgAsyncQuery: (
pool: PgAsyncPool,
ticket: i32,
sql: string,
params: PgAsyncParams,
) => Promise<PgAsyncResult>
poolPgAsyncPoolrequiredThe pool the ticket came from; a cap out of its range panics.
ticketi32required
A ticket pgAsyncClaim answered and no pgAsyncRelease has
spent; any other panics.
sqlstringrequired
One statement, $1, $2, ... naming the parameters; a NUL in
it fails the query with PG_ERR_ENCODING without sending anything.
paramsPgAsyncParamsrequiredThe parameters, as many as the statement names; a NUL in a text one fails the query the same way.
returnsPromise<PgAsyncResult>The answer; its reusable goes to pgAsyncRelease.
pgAsyncRelease
Gives a claimed connection back, or closes it when reusable is false, and
wakes the tasks waiting for one; the ticket is spent either way, and a
ticket that is not the slot's current claim (a second release, or one after
close()) panics. It writes only numbers into the pool, so a spawned task
may call it.
const pgAsyncRelease: (
pool: PgAsyncPool,
ticket: i32,
reusable: boolean,
) => void
poolPgAsyncPoolrequiredThe pool the ticket came from.
ticketi32requiredThe ticket pgAsyncClaim answered.
reusablebooleanrequiredThe query's reusable; false closes the connection.
pgAsyncSeat
Takes a seat for one statement on a shared connection: the live one with
the fewest statements in flight, below pool.depth, that no task claimed
whole and no task is writing to. The seat fixes the statement's place in
the connection's order, so the calling task goes straight on, with no
other await between: pgAsyncSend writes the statement, pgAsyncTurn
waits for its answer, pgAsyncAnswer builds it and pgAsyncDone spends
the ticket. Until pgAsyncTurn no other seat on the connection is taken,
so the statements go out in the order of their seats. While no connection has room it waits until a seat
or a connection frees and wakes it, for at most pool.claimWaitMs in all;
waiting tasks are seated in the order they began to wait, the first as many
as there are seats free at once, and a task that has not waited is seated
only while none waits.
It writes only numbers into the pool, so a spawned task may call it.
const pgAsyncSeat: (
pool: PgAsyncPool,
statement: i32,
) => Promise<i32>
poolPgAsyncPoolrequiredThe pool.
statementi32required
A number pgAsyncPrepare answered; any other panics, as
does a pool.depth out of range.
returnsPromise<i32>
A ticket (0 or more) for pgAsyncSend, pgAsyncTurn,
pgAsyncAnswer and pgAsyncDone, each called once; PG_POOL_NONE (-1) when no slot is connected;
PG_CARRIER_FULL (-2) when no seat came free in time;
PG_ASYNC_CANCELLED (-3) when the calling task is cancelled, before or
while it waits.
pgAsyncSend
Writes the seat's statement: its Parse the first time the connection runs it, then Bind (each parameter in text), Execute and Sync, whole, waiting on the socket while other tasks run. It only reads the pool; its buffer is the calling task's.
const pgAsyncSend: (
pool: PgAsyncPool,
ticket: i32,
params: PgAsyncParams,
) => Promise<i32>
poolPgAsyncPoolrequiredThe pool the ticket came from.
ticketi32required
A ticket pgAsyncSeat answered and no pgAsyncDone has
spent; any other panics.
paramsPgAsyncParamsrequiredThe parameters, as many as the statement names; a NUL in one sends nothing.
returnsPromise<i32>
What to hand pgAsyncTurn: the bytes written, or
PG_ASYNC_UNSENT or PG_ASYNC_UNSENT_CANCELLED when nothing was, or
less than -15 when the write broke.
pgAsyncTurn
Waits for the seat's turn and reads its answer off the connection: the
statements seated before it are answered first, to their own tasks, and
what they read past their own answers begins this one. One read takes what
the socket holds, up to the pool's input, so the answers behind this one
often arrive with it. A lost connection (a socket error) fails this
statement and every one behind it. A task cancelled with its answer unread
fails alone: its seat is abandoned, and the next task to wait on the
connection reads past that answer, or loses the connection from it on when
the answer is not a plain one ending idle or is larger than the pool's
input. It writes only numbers into the pool, so a spawned task may call it;
pgAsyncAnswer then builds the answer in the task's memory.
const pgAsyncTurn: (
pool: PgAsyncPool,
ticket: i32,
sent: i32,
) => Promise<i32>
poolPgAsyncPoolrequiredThe pool the ticket came from; a cap out of its range panics.
ticketi32required
The ticket pgAsyncSeat answered and pgAsyncSend used;
any other panics.
senti32requiredWhat pgAsyncSend answered.
returnsPromise<i32>
What to hand pgAsyncAnswer and pgAsyncDone: 0 when the answer
is there to read, else less than 0 for a statement that failed unanswered.
Classes
PgAsyncParams
A query's parameters, in text, in the order $1, $2, ... name them. A
task builds its own; the values travel apart from the SQL, so none is ever
read as SQL.
class PgAsyncParams
| Member | |
|---|---|
new PgAsyncParams() |
No parameters yet. |
readonly nulls: boolean[] |
Whether each parameter is NULL. |
readonly values: string[] |
Each parameter's text, "" for a NULL. |
int(value: i32): void |
Adds an integer parameter, sent as its decimal text. |
none(): void |
Adds a NULL parameter. |
text(value: string): void |
Adds a text parameter. |
PgAsyncPool
Authenticated PostgreSQL connections that spawned tasks share. Build one
and connect it with pgAsyncConnect outside any task; tasks then claim,
query and release through the pgAsync* functions, and the owner calls
close() once they are done. It holds no secret: only sockets and numbers.
The arrays are the functions' bookkeeping, readable for a test or a status
page; a program writes none of them.
class PgAsyncPool
| Member | |
|---|---|
new PgAsyncPool(size: i32) |
A pool of size slots, none connected yet. A waiting task waits on a wake: one per turn lane, one for the pool and one per queue lane. Each opens its socket pair the first time a task waits on it; close() closes the pairs opened. |
readonly claimed: u8[] |
Each slot's state: 0 free, 1 claimed by a ticket. |
readonly claims: i32[] |
Each slot's claim count, the high part of its current ticket. |
claimWaitMs: i32 |
The most milliseconds pgAsyncClaim or pgAsyncSeat waits for a free connection before it answers PG_CARRIER_FULL. |
connects: i32 |
How many connections pgAsyncConnect made, in all. |
connectWaitMs: i32 |
The most milliseconds pgAsyncConnect gives one connection to connect and finish its startup before it closes it and moves on; 0 or less waits for as long as the server takes. |
depth: i32 |
The most statements pgAsyncSeat puts in flight on one connection at once, 1 to PG_ASYNC_MAX_DEPTH. |
readonly doomAt: i32[] |
Per slot: the first sequence number that is not served because the connection was lost, or -1. |
dropped: i32 |
How many connections were closed rather than given back: by pgAsyncRelease, or once a lost pipeline emptied. |
readonly fds: i32[] |
Each slot's socket, or -1 while it is not connected. |
readonly inAnswer: i32[] |
Per slot: where the answer in turn ends in inputs, past its ReadyForQuery, or -1 while it is not there whole. |
readonly inEnd: i32[] |
Per slot: where the unserved bytes in inputs end. |
readonly inParsed: u8[] |
Per slot: 1 when the answer in turn begins with a ParseComplete. |
readonly inputs: u8[][] |
Per slot: answer bytes read past the last statement served, at [inStart, inEnd). |
readonly inStart: i32[] |
Per slot: where the unserved bytes in inputs start. |
maxColumns: i32 |
The most columns a row may have, 1 to 65535; more fails the query with PG_ERR_TOO_BIG and closes the connection. |
maxMessage: i32 |
The largest message a query accepts, in bytes, 1024 to 2^30 - 1; a larger one fails it with PG_ERR_TOO_BIG and closes the connection. |
maxResultBytes: i32 |
The most bytes of rows a query keeps, 1024 to 2^30 - 1: each row costs its DataRow's length and 16 bytes a cell. A row past it is dropped with every later one, read through to the ReadyForQuery, and the query fails with PG_ERR_TOO_BIG. |
maxRows: i32 |
The most rows a query keeps, 1 to 2^24; later rows are read and dropped, and the query fails with PG_ERR_TOO_BIG. |
readonly nextSeq: i32[] |
Per slot: the sequence number the next seated statement takes. |
readonly prepared: u8[] |
Per slot and statement (slot * PG_ASYNC_MAX_STATEMENTS + statement): 1 once a Parse for it was sent on that connection. |
readonly seatAbandoned: u8[] |
Per seat: 0, or how far a seat whose task was cancelled with its answer unread has gone: 1 abandoned, 2 abandoned and its ticket spent, 3 its answer read past and its ticket not yet spent. |
readonly seatClaims: i32[] |
Per seat: its claim count, the high part of its current ticket. |
readonly seated: i32[] |
Per slot: the seats in use. |
readonly seatGone: u8[] |
Per queue number, modulo its length: 1 when its task stopped waiting before its turn. |
seatHead: i32 |
The queue number of the first task still waiting for a seat. Of the tasks waiting, in the order they began to wait, the first as many as there are free seats may each take one, and a task that has not waited takes none while any is queued. |
readonly seatParse: u8[] |
Per seat: 1 when its write carries the statement's Parse. |
readonly seatSeq: i32[] |
Per seat: its statement's sequence number on the connection. |
readonly seatStatement: i32[] |
Per seat: its statement. |
seatTail: i32 |
The queue number the next task to wait for a seat takes. |
readonly seatUsed: u8[] |
Per seat (slot * PG_ASYNC_MAX_DEPTH + k): 1 while a ticket holds it. |
readonly seatWaiting: u8[] |
Per seat: 1 while its task waits for its answer's turn. |
readonly served: i32[] |
Per slot: the sequence number whose answer is read next. |
readonly size: i32 |
The number of connection slots, fixed at construction. |
readonly skipping: u8[] |
Per slot: 1 while a task reads past an abandoned seat's answer. |
readonly statements: u8[][] |
Each statement pgAsyncPrepare registered: its SQL as UTF-8. |
turnWaits: i32 |
How many times pgAsyncTurn waited for the answers seated ahead of its own. |
readonly waiters: i32[] |
Per wake: the tasks waiting on it. |
waits: i32 |
How many times pgAsyncClaim or pgAsyncSeat waited because no live connection had room. |
readonly wakeBytes: u8[] |
The bytes a wake is rung with and read back into, so neither allocates. |
readonly wakePair: i32[] |
Where pgAsyncPark opens a wake's socket pair, so it does not allocate. |
readonly wakePending: u8[] |
Per wake: 1 while a byte is written and not yet read. |
readonly wakeRings: i32[] |
Per wake: how many bytes were written to it, wrapping; a waiter that sees it move was rung. |
readonly wakes: i32[] |
Per turn lane, then one for the pool, then one per queue lane: a socket pair whose read end a waiting task waits on, or -1. A pair is opened the first time a task waits on its wake, so a pool nobody waits on holds none. |
readonly wakeUnseen: i32[] |
Per wake: the tasks waiting when its byte was written that have not yet woken; it is read back at 0. |
readonly writing: u8[] |
Per slot: 1 while a seated statement has not yet been written whole. |
close(): void |
Ends every connection: a Terminate is offered to each socket, which is then closed, claimed or not, and closes the wakes. Call it once the tasks that hold tickets are done; a ticket used afterwards panics. |
live(): i32 |
The number of slots connected now, claimed or not. |
PgAsyncResult
One query's answer, in the task's own memory: its rows as text, its tag, and how it ended.
class PgAsyncResult
| Member | |
|---|---|
new PgAsyncResult() |
An answer with no rows that worked, until the query fills it in. |
code: i32 |
PG_CARRIER_DONE when the query worked, PG_CARRIER_FAILED when it did not. |
columns: i32 |
The number of columns in each row (the first row's; every row must match). |
errorCode: string |
The server's SQLSTATE when it refused the statement, e.g. 42P01. |
errorMessage: string |
The server's message when it refused the statement. |
failure: i32 |
When it failed: a PG_ERR_*, PG_ERR_NONE when the server refused the statement. |
readonly nulls: boolean[] |
Whether each kept cell is NULL, as values. |
reusable: boolean |
Whether the connection may serve another query: hand it to pgAsyncRelease. |
rows: i32 |
The number of rows kept. |
socketError: i32 |
When the socket failed: its negative errno, 0 when the server closed cleanly, PG_ASYNC_CANCELLED when the task was cancelled. |
tag: string |
The command tag, e.g. SELECT 2 or UPDATE 1; "" for an empty query. |
readonly values: string[] |
Every kept cell's text, row by row; "" for a NULL. |
int(row: i32, column: i32, fallback: i32): i32 |
A cell read as a decimal i32, or fallback when it is NULL or not one. |
isNull(row: i32, column: i32): boolean |
Whether a cell is NULL; panics on a row or column out of range. |
ok(): boolean |
Whether the query worked. |
text(row: i32, column: i32): string |
A cell's text, "" for a NULL; panics on a row or column out of range. |
Limits
16
PG_ASYNC_MAX_DEPTH: i32
The most statements one connection has in flight at once: PgAsyncPool.depth's ceiling.
64
PG_ASYNC_MAX_SIZE: i32
The most connections one PgAsyncPool holds.
64
PG_ASYNC_MAX_STATEMENTS: i32
The most statements pgAsyncPrepare registers on one pool.
Constants
-3
PG_ASYNC_CANCELLED: i32
The calling task was cancelled (nish:async's cancel, or a deadline set
with cancelAfter): pgAsyncClaim answers it in place of a ticket, and a
query cut off by it fails with PG_ERR_CLOSED and this as its
socketError, which no socket read or write answers.
-1
PG_ASYNC_UNSENT: i32
pgAsyncSend's answer for a statement it did not send because a parameter
holds a NUL; pgAsyncAnswer fails it with PG_ERR_ENCODING, and the
connection is reused.
-2
PG_ASYNC_UNSENT_CANCELLED: i32
pgAsyncSend's answer for a statement it did not send because the task was
cancelled; pgAsyncAnswer fails it with PG_ERR_CLOSED and
PG_ASYNC_CANCELLED, and the connection is reused.

