Documentation
¶
Overview ¶
Package utxocond builds fixed-shape "(tx_id = ? AND output_idx = ?)" OR-list conditions for the UTxO block-apply UPDATEs (consume, collateral, reference inputs) used by the shared metadata store.
The block-apply path builds one such UPDATE per transaction, matching that transaction's consumed/collateral/reference inputs. Building the WHERE clause as a variable-length list of OR-ed placeholder pairs made the SQL text vary with the input count, so prepared statements could not be reused and thrashed on parse/prepare under dense sync (issue #2943).
Chunks pads each chunk's term count up to the next power of two by repeating the chunk's last ref. Because these UPDATEs match rows by an OR of composite keys, repeating a ref is idempotent: it does not change which rows match or how many rows are affected. Padding to powers of two bounds the number of distinct SQL shapes to about log2(maxTerms)+1 regardless of input count, so the prepared-statement cache can reuse them.
Index ¶
Constants ¶
const DefaultMaxTerms = 256
DefaultMaxTerms bounds the OR-terms per statement. Each term binds two parameters, so 256 terms is 512 parameters, comfortably under driver parameter limits (SQLite's default SQLITE_MAX_VARIABLE_NUMBER is 999, newer builds 32766; postgres/mysql are far higher). It is a power of two so a full chunk reuses the single largest SQL shape.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Chunk ¶
type Chunk struct {
// Condition is the parenthesized OR-list, e.g.
// "(tx_id = ? AND output_idx = ?) OR (tx_id = ? AND output_idx = ?)".
// Its term count is always a power of two and never exceeds the maxTerms
// passed to Chunks, so only a handful of distinct Condition strings are
// ever produced.
Condition string
// Args holds TxID, Idx pairs for every term including padding, in order:
// len(Args) == 2 * (padded term count).
Args []any
// Real is the number of leading terms that correspond to distinct input
// refs (the remainder are idempotent padding). Callers that verify an
// affected-row count should sum Real across chunks.
Real int
}
Chunk is one fixed-shape OR-list condition and its bound arguments.
func Chunks ¶
Chunks splits refs into chunks and pads each chunk's term count up to the next power of two (repeating the chunk's last ref). It returns nil for an empty input.
maxTerms is an upper bound on the padded term count, and so on the bound parameter count (two per term) of the statements callers build from a Chunk. Every padded term count is a power of two and must not exceed maxTerms, so the effective bound is maxTerms rounded down to a power of two: rounding down (never up) is what keeps the parameter count inside the caller's limit. The split boundary uses that same rounded value, so a chunk is never larger than the term count it is padded to. maxTerms values below 1 fall back to DefaultMaxTerms, which is already a power of two.
Source Files