README
¶
commit
Group commit (#803). Group[T] coalesces concurrent Do calls into one
flush: every caller contributes an item, one goroutine runs the flush over all
of them, and every caller receives that flush's verdict — N callers that each
need their item durable share one fsync.
group := commit.New(func(ctx context.Context, records []Record) error {
for _, r := range records {
if _, err := journal.Write(r.Bytes()); err != nil {
return err
}
}
return journal.Sync() // one fsync for the whole batch
}, commit.Config{MaxItems: 256, MaxWait: 0})
err := group.Do(ctx, record) // returns once the flush carrying record has run
A batch starts with its first item and gathers followers for MaxWait on
Config.Clock (a clock.ManualClock in tests), or until MaxItems. Flushes
run one at a time, in the order their batches started; a batch keeps
gathering while the one before it flushes, so with a zero MaxWait the
callers that arrive during one flush share the next.
A caller whose context ends before its flush returns ctx.Err() — and its
item is flushed all the same. Do after Close returns commit.Closed
(0.1.4.1); a panicking flush panics every participant.
stdlib-only, domain-neutral, kernel-layer. See CLAUDE.md for the contract.
Documentation
¶
Overview ¶
Package commit provides Group, a group commit: concurrent callers each contribute an item, one goroutine runs a flush over all of them, and every caller receives that flush's verdict. N callers that each need their item durable share one fsync where each would have paid its own.
It is the primitive between two the kernel already has. singleflight deduplicates IDENTICAL calls; batcher coalesces items asynchronously — Add returns before delivery and the caller never learns the flush's verdict. Here every caller blocks until the flush that carried its item has run, and gets its error.
A batch starts with its first item and gathers followers for MaxWait on an injected clock, or until MaxItems; flushes run one at a time, in the order their batches started, and a batch keeps gathering while the one before it flushes — with a zero MaxWait, coalescing comes from the flush's own duration. The flush runs on a goroutine of its own, with the first caller's context values and none of its cancellation: a caller that leaves gets its ctx.Err(), and its item is flushed all the same.
Stdlib-only and generic: one type parameter, one function. Range 0.1.4.* (ADR 0005 kernel block, #803).
Package commit — one batch: its items, the channels that order and publish it, and the verdict.
Package commit — the Config value type.
Package commit — declares the sentinel returned by Do after Close.
Index ¶
Constants ¶
const CodeCommitClosed errs.Code = 0x00_01_04_01 // 0.1.4.1
CodeCommitClosed identifies a Do call made after Close.
Variables ¶
var Closed = errs.Static(CodeCommitClosed, "COMMIT_CLOSED",
"The commit group is closed",
"internal/kernel/concur/commit: Do called after Close",
0,
0)
Closed is returned by Do once Close has run: the Group takes no more items, and every batch started before Close has been flushed.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// MaxItems seals a batch once it holds this many items: a full batch is
// flushed without waiting out MaxWait, and the next caller starts another.
// Zero or negative means no cap.
MaxItems int
// MaxWait is how long a batch gathers followers after its first item before
// it is flushed. Zero means no wait: the batch is flushed as soon as the
// one before it has been — coalescing then comes from the flushes' own
// duration. Negative is read as zero.
MaxWait time.Duration
// Clock is what MaxWait is waited on. nil means clock.System; a
// clock.ManualClock makes the gathering deterministic in a test.
Clock clock.Waiter
}
Config tunes a Group. The zero Config is usable: no item cap, no gathering wait — a batch is flushed as soon as the flush before it has finished, so the callers that arrived during one flush share the next.
type Group ¶
type Group[T any] struct { // contains filtered or unexported fields }
Group coalesces concurrent Group.Do calls into one flush: every caller contributes an item, one goroutine runs the flush over all of them, and every caller receives that flush's verdict. It is group commit — N callers that each need their item durable share one fsync, where each would have paid its own.
Safe for concurrent use. The zero value is NOT usable — construct with New.
func New ¶
New builds a Group that hands each batch of items to flush. A nil flush panics, at the call that made the mistake: there is nothing a Group could do with an item without one.
func (*Group[T]) Close ¶
func (g *Group[T]) Close()
Close refuses every later Do with Closed and returns once every batch already started has been flushed. It is idempotent.
func (*Group[T]) Do ¶
Do adds item to the batch being gathered — starting one if none is — and returns the verdict of the flush that carried it: every participant of a flush receives the same error, nil included.
A caller whose ctx ends before the flush returns ctx.Err() at once, and its item is STILL flushed: leaving is a departure, not a withdrawal, since the flush may already be writing it. The flush runs on a goroutine of its own, with the first participant's context values and none of its cancellation.
Do returns Closed once Close has run. If the flush panics, every participant panics with the same value.
Source Files