session

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package session is the Durable core's Session layer: the Session line, the transaction that stages one atomic commit (conversations, entries, tasks, submissions and documents), the document cache, and the task scheduler.

It ports pi-durable's session/session.ts, session/transaction.ts, session/forks.ts and harness/scheduler.ts as a synchronous state machine: a commit callback runs to completion, a read the loaded state cannot answer returns a *NeedRead error and the callback restarts after the host answers, and no goroutine, clock, I/O or package-level mutable state exists.

Records are ordered JSON objects (package jv) so a rewritten record keeps the field order and unknown fields Pi's object spreads keep.

Index

Constants

View Source
const (
	// RootsKey is the ownerless conversations with live work below them, which global idle walks from.
	RootsKey = "roots"
	// IntentKey is the live tasks with cancellation intent: abort marks, and held outcomes other than completed.
	IntentKey = "intent"
	// AllKeys is every unpublished write: what a read that cannot be keyed, such as a scan, touches.
	AllKeys = "*"
)
View Source
const (
	StatusPending    = "pending"
	StatusRunning    = "running"
	StatusWaiting    = "waiting"
	StatusSleeping   = "sleeping"
	StatusCompleting = "completing"
	StatusTerminal   = "terminal"
)

TaskStatus values of a task's state.

View Source
const DefaultDocumentRetentionMs = 600_000

DefaultDocumentRetentionMs is Pi's default document retention: ten minutes, as for kept contexts.

View Source
const DefaultPersistWithinMs = 1_000

DefaultPersistWithinMs is the default window of a deferred commit, settings.progress.persistWithinMs (session.ts DEFAULT_PERSIST_WITHIN_MS).

Variables

View Source
var (
	// ErrReadAfterWrite is Pi's ReadAfterWrite.
	// Read-only: assigned once at initialization.
	ErrReadAfterWrite = errors.New("ReadAfterWrite")
	// ErrSealed reports use of a transaction after it settled.
	// Read-only: assigned once at initialization.
	ErrSealed = errors.New("Transaction has settled")
	// ErrSessionFailed is Pi's SessionFailed: the Session failed after a storage error, so nothing runs or commits any more.
	// Read-only: assigned once at initialization.
	ErrSessionFailed = errors.New("Session failed after a storage error; close and reopen it")
	// ErrReadOnlySession is Pi's ReadOnlySession: the Harness was opened read-only, and a commit with writes or a call that would run
	// tasks was refused.
	// Read-only: assigned once at initialization.
	ErrReadOnlySession = errors.New("ReadOnlySession")

	// ErrTypeError marks an error Pi throws as a TypeError.
	// Read-only: assigned once at initialization.
	ErrTypeError = errors.New("TypeError")
	// ErrStorageRequest is Pi's StorageRequestError: a Storage read the caller's request got wrong (an unknown conversation, an invalid cursor or scan
	// order, a document that keeps no history). It fails only that read, not the Session.
	// Read-only: assigned once at initialization.
	ErrStorageRequest = errors.New("StorageRequestError")
	// ErrClosed reports a closed Session.
	// Read-only: assigned once at initialization.
	ErrClosed = errors.New("Session is closed")
)

Error values of the Session layer, named as Pi names them.

View Source
var (
	// ErrHarnessClosed is Pi's closedError.
	// Read-only: assigned once at initialization.
	ErrHarnessClosed = errors.New("Harness is closed")
	// ErrAborted reports a cancelled wait.
	// Read-only: assigned once at initialization.
	ErrAborted = errors.New("The operation was aborted")
)

Task errors reported by the scheduler.

View Source
var Current = Point{Current: true}

Current is the point of the newest incarnation. Read-only.

View Source
var ErrHostNotGranted = errors.New("host job not granted")

ErrHostNotGranted is what the grant of a host job returns when it takes nothing (LineHost). Read-only: assigned once at initialization.

View Source
var ErrParked = errors.New("loop parked on a read")

ErrParked is returned by Run when a job waits for host reads. Read-only: assigned once at initialization.

Functions

func AppendKey

func AppendKey(id ID) string

AppendKey is the newest entries of a conversation: appended blind, read by scans, the newest entry and head markers.

func ConversationKey

func ConversationKey(id ID) string

ConversationKey is a conversation record.

func DocAddress

func DocAddress(def *DocDef, args DocArgs) string

DocAddress returns the address a definition and arguments name; hosts key their per-transaction state by it.

func DocumentKey

func DocumentKey(addressID string) string

DocumentKey is a document address (addressID): its current incarnation, value and held changes.

func EntryKey

func EntryKey(id ID) string

EntryKey is an entry record.

func IncarnationKey

func IncarnationKey(id ID) string

IncarnationKey is a document incarnation, for reads by its ID.

func IsNeedPublication

func IsNeedPublication(err error) bool

IsNeedPublication reports whether err is, or wraps, a *NeedPublication.

func NewStorageRequestError

func NewStorageRequestError(msg string) error

NewStorageRequestError is Pi's `new StorageRequestError(message)`.

func NewTypeError

func NewTypeError(message string) error

NewTypeError is a TypeError Pi throws with message; it matches ErrTypeError with errors.Is.

func OwnedKey

func OwnedKey(node string) string

OwnedKey is a node of the scheduler's ownership tree (a task ID, or "c" and a conversation ID): the live work listed below it. Written by task creation and a task becoming terminal for every node from the task's parent up to and including the nearest live task or the root conversation; read by every walk that expands the node.

func ReadAfterWriteOf

func ReadAfterWriteOf(operation string) error

ReadAfterWriteOf is Pi's ReadAfterWrite for an operation, such as "Tx.task()": a transaction read a table after its first table write, or admitted a submission (`submit(tx, draft)`) after it.

func RecordAddressID

func RecordAddressID(rec *jv.Object) string

RecordAddressID is the address ID of a document record: the address of every incarnation of one document.

func RequestKey

func RequestKey(conversationID ID, requestID string) string

RequestKey is the submission a conversation's request ID names.

func ScopeKey

func ScopeKey(scope Scope) string

ScopeKey is the incarnations alive in a scope: created and retired blind, read by scans and the task-document index.

func SubmissionKey

func SubmissionKey(id ID) string

SubmissionKey is a submission record.

func TaskKey

func TaskKey(id ID) string

TaskKey is a task record.

Types

type Address

type Address struct {
	Kind   string
	Scope  Scope
	Key    string
	Family bool
}

Address names a document: its kind, scope and, for a family member, its key.

func DocumentAddress

func DocumentAddress(def *DocDef, args DocArgs) Address

DocumentAddress returns the document address a definition and arguments name.

type Cancel

type Cancel struct {
	// Span is the host's handle of the span of the phase an invocation's signal belongs to, 0 outside a phase: the host effects the
	// phase starts run under it (Context.telemetry).
	Span uint32
	// contains filtered or unexported fields
}

Cancel is a cancellation signal: the AbortSignal of an invocation or of a caller's context.

func (*Cancel) Abort

func (c *Cancel) Abort()

Abort marks the signal aborted with the default reason (AbortController.abort()) and runs the registered hooks once.

func (*Cancel) AbortWith

func (c *Cancel) AbortWith(reason error)

AbortWith marks the signal aborted with reason (AbortController.abort(reason)); a signal keeps its first reason.

func (*Cancel) Aborted

func (c *Cancel) Aborted() bool

Aborted reports whether Abort ran.

func (*Cancel) Err

func (c *Cancel) Err() error

Err is the reason of an aborted signal (AbortSignal.throwIfAborted), or nil.

func (*Cancel) OnAbort

func (c *Cancel) OnAbort(fn func()) (remove func())

OnAbort registers fn to run on abort and returns a function that removes it.

type Change

type Change struct {
	Kind   ChangeKind
	Table  WriteKind // ChangeTable: the write's kind (its record is Record)
	Record *jv.Object
	// ConversationID is the conversation a document change belongs to (0: none).
	ConversationID ID
	Version        int
	Value          *jv.Object // nil: the document was retired
	Ops            []delta.Op
	Source         DocCopySource
}

Change is one published change of a commit: a table write, a document change or a document copy.

type ChangeKind

type ChangeKind uint8

ChangeKind is the kind of a published change.

const (
	ChangeTable ChangeKind = iota + 1
	ChangeDocument
	ChangeDocumentCopy
)

The published change kinds.

type CommitResult

type CommitResult struct {
	Stored     int
	Refused    error
	Adoption   error
	AdoptionAt int
}

CommitResult is what a Storage call stored: the number of durable batches, and why the next one was refused, if one was. Adoption is the error of the first stored batch the host's side of the call could not adopt (Transaction.adopt threw), AdoptionAt the batch's index in the call: that batch is durable, but its publication fails with it and adopts nothing.

type ContextRange

type ContextRange struct {
	Head, From, Tail ID
	Current          bool
}

ContextRange is the bounds of a kept context range: the entries from From (0: the first) to Tail visible from the conversation, under the head marker Head (0: none), whose head is From. A range that is Current reached the conversation's newest entry when it was read, so the entries of later commits extend it at their publication (advanceContexts); one cut off at an earlier entry is not.

type ConversationQuery

type ConversationQuery struct {
	OwnerConversationID ID
	OwnerTaskID         ID
	Descending          bool
}

ConversationQuery filters a conversation scan.

type DocArgs

type DocArgs struct {
	Owner ID     // conversation or task ID for those scopes
	Key   string // family member
	Seed  any    // family seed
}

DocArgs addresses a document of a definition.

type DocCopySource

type DocCopySource struct {
	ID ID
	At Point
}

DocCopySource is the document a fork copies and the point it is read at.

type DocDef

type DocDef struct {
	Kind    string
	Version int
	Scope   ScopeKind
	// History and Fork apply to conversation documents only.
	History History
	Fork    ForkPolicy
	// Family marks a keyed family; Initial then receives the member's seed.
	Family bool
	// Initial returns the value of a new document. seed is nil for a singleton.
	Initial func(seed any) *jv.Object
	// Migrate converts a value stored at an older version.
	Migrate func(value *jv.Object, from int) *jv.Object
	// HostInitial and HostMigrate replace Initial and Migrate when the definition's code runs in a host: an error (a
	// *NeedRead asks the host for the value) fails the call that needed it.
	HostInitial func(seed any) (*jv.Object, error)
	HostMigrate func(value *jv.Object, from int) (*jv.Object, error)
	// CheckpointWhen returns true to store an ordinary change as a base.
	CheckpointWhen func(value *jv.Object, ops []delta.Op, deltasSinceBase int) bool
}

DocDef defines a document kind: its scope and semantics, the stored shape version and the functions that create, migrate and checkpoint its value. A definition is immutable after construction and shared by every Session.

type DocRevision

type DocRevision struct {
	Epoch   uint64
	Adopted int
}

DocRevision names one value of a cached document incarnation: the incarnation (Epoch, never 0) and the number of changes adopted to it so far (Adopted). A host that kept the value of a revision asks for what changed since instead of the whole document.

type DroppedDoc

type DroppedDoc struct {
	ID      ID
	Address string
}

DroppedDoc is an incarnation that left the cache: its record and the address it is cached under.

type Ended

type Ended struct {
	// Part is the part the job admitted to the writer: stored (Writes), or held in memory (none); nil when it admitted none.
	Part *Part
	// Err is the error the body returned, nil for success.
	Err error
	// Read is set for a Session.readOnLine job (ReadLine): no change callback, settle or commit.
	Read bool
	// Ticks is what the job's transaction and settle charged in Pi's await ticks, for a host that counts no more of them than the Session does.
	Ticks JobTicks
}

Ended describes a line job whose body ended, for Elapsed.

type EntryQuery

type EntryQuery struct {
	ConversationID ID
	MinEntryID     ID   // 0: unbounded
	MaxEntryID     ID   // 0: unbounded
	Ascending      bool // the default order is descending
}

EntryQuery bounds an entry scan of one conversation, through its ancestry.

type Env

type Env struct {
	// Snapshot returns the current registry snapshot.
	Snapshot func() Snapshot
	// FreshSnapshot, when set, is the registry.snapshot() call of a step's decide (scheduler.ts:955), which runs user
	// code inside the step job: it returns a *NeedRead with no reads while the host is asked, and the Loop reruns the
	// job once the host answered. Unset, decide uses Snapshot.
	FreshSnapshot func() (Snapshot, error)
	// ContextRetentionMs is settings.contextRetentionMs: how long a conversation's kept context range outlives its idleness.
	ContextRetentionMs func() float64
	// ReleaseContext, when set, is told each conversation whose kept context range the scheduler drops for idleness
	// (scheduler.ts #settleIdle): what the core derived for it may go, as Pi's range does. It runs at an idle check, never
	// while a caller still reads a view of that conversation.
	ReleaseContext func(conversationID ID)
	// Report forwards a non-fatal failure to HarnessOptions.onReport; info says what happened (types.ts ReportInfo as
	// an object: type, and task, extension, reason, callback or conversationId where they apply).
	Report func(err error, info *jv.Object)
	// Telemetry records the spans and metrics of Pi's telemetry; nil when the Harness has none.
	Telemetry Telemetry
	// RestartLimit is settings.restartLimit, read at each use; nil selects the default.
	RestartLimit func() float64
	// LimitsRestarts reports whether the phases of tasks of a kind end the task themselves once it was cut off
	// settings.restartLimit times (the built-in tasks); the scheduler ends a task of any other kind faulted instead. nil: none.
	LimitsRestarts func(kind string) bool
	// BlockedChanged is told when blocked reasons may have changed without a commit: a registry change or a failed
	// migration (scheduler.ts #notifyBlocked).
	BlockedChanged func()
	// Now is the Harness clock.
	Now func() float64
	// Timer arms a background timer that calls fire at the Harness time at (a timer effect, ABI section 6) and returns its
	// cancel function: it only frees memory, and a host may keep none.
	Timer func(at float64, fire func()) (cancel func())
	// WakeTimer arms the timer that resumes the earliest sleeping task (a durable timer effect, ABI section 6): a host
	// that wakes its process itself keeps the object alarm at its time. Used while OnWake is nil.
	WakeTimer func(at float64, fire func()) (cancel func())
	// OnWake, when set (SetOnWake), replaces WakeTimer: the scheduler offers it each recomputed Wake (HarnessOptions.onWake)
	// and arms no timer for sleeping tasks. The host drops a value it already delivered.
	OnWake func(w Wake)
	// SettleOutcome runs in the transaction that settles a task with a
	// scheduler-written outcome (faulted or orphaned): harness.live.ts settleSchedulerOutcome.
	SettleOutcome func(tx *Tx, record *jv.Object, outcome *jv.Object) error
	// WithdrawInputs runs in the transaction that withdraws a conversation's
	// queued inputs (inbox.ts withdrawQueuedInputs).
	WithdrawInputs func(tx *Tx, conversationID ID) error
	// ReadTicks is the ticks the running line job's Storage reads have taken so far, and After runs then once a chain of n
	// hops ran: a reconcile a chain load schedules after its read starts when Pi's microtask does, not at the job's start.
	ReadTicks func() int
	// GateRead asks the host's Storage to run the Pi Storage read of method (task, conversation) that a chain load makes, so a Storage that
	// counts, holds or fails it sees it (scheduler.ts #loadChain); nil asks nothing. A line job that asked is told to wait for the answer
	// (*NeedRead) and runs again once the Storage answered; the Storage's own error is the chain load's.
	GateRead func(method string, id ID) error
	After    func(n int, then func())
}

Env connects the scheduler to its host.

type FailedError

type FailedError struct{ Cause error }

FailedError is what a call on a failed Session returns: Pi's SessionFailed, with the Storage error that failed the Session as its cause. Its message is fixed; the cause does not cross the host wire.

func (*FailedError) Error

func (e *FailedError) Error() string

func (*FailedError) Is

func (e *FailedError) Is(target error) bool

Is matches ErrSessionFailed.

func (*FailedError) Unwrap

func (e *FailedError) Unwrap() error

Unwrap returns the cause.

type ForkPolicy

type ForkPolicy string

ForkPolicy is how a conversation document behaves when its conversation is forked.

const (
	ForkAsOf    ForkPolicy = "asOf"
	ForkCurrent ForkPolicy = "current"
	ForkInitial ForkPolicy = "initial"
)

The fork policies.

type Gate

type Gate struct {
	// contains filtered or unexported fields
}

Gate opens once the part it belongs to is published or never will be; it never fails.

func (*Gate) Opened

func (g *Gate) Opened() bool

Opened reports whether the gate is open.

func (*Gate) Wait

func (g *Gate) Wait(fn func())

Wait calls fn once the gate is open, at once when it is.

func (*Gate) WaitResumer

func (g *Gate) WaitResumer(r Resumer)

WaitResumer resumes r once the gate is open, at once when it is, without a closure made for it.

type HeldAdopter

type HeldAdopter interface{ Adopted(err error) }

HeldAdopter is told the outcome of the host's adoption of a held commit: nil when it adopted it.

type History

type History string

History is how a conversation document keeps its past.

const (
	HistoryLatest     History = "latest"
	HistoryRewindable History = "rewindable"
)

The conversation document histories.

type HostDocValue

type HostDocValue struct {
	Value           any
	Ops             []delta.Op
	Incremental     bool
	Revision        DocRevision
	Tracked         bool
	DeltasSinceBase int
	Loaded          bool
}

HostDocValue is what HostDoc gives a host: the document's present content, or the operations since the revision the host holds, and for a stored document (Loaded) the number of deltas after its base (Pi's CheckpointInfo).

type HostJob

type HostJob struct {
	// contains filtered or unexported fields
}

HostJob is a line job whose change callback runs in the host, one operation per event (ABI section 8): the host's transaction of Pi's `session.commit(async (tx) => ...)`. It takes the line like any job; the host drives the transaction (Session.Begin, its operations, Session.Finish or Abandon), and End hands the Loop the end of the callback: the rest of the job (the settle, the part's admission, the line's release and the delivery of its outcome) follows as for a job whose body ran in the core, from the ticks the transaction charged.

func (*HostJob) End

func (h *HostJob) End(err error)

End is the end of the host's callback: err is what it threw or its commit failed with, nil when it succeeded and Session.Finish admitted what it staged. It must be called once the job took the line (grant ran).

type ID

type ID = int64

ID is the number of a conversation, entry, task, submission or document.

const RootConversationID ID = 1

RootConversationID is the reserved ID of the root conversation.

func TerminalTask

func TerminalTask(task *jv.Object) (ID, bool)

TerminalTask returns the ID of a task record and whether its status is terminal.

type IndexSizes

type IndexSizes struct{ Live, Settled, Edges, Below, Roots, Unloaded, DropQueue, Pins int }

IndexSizes are the sizes of the scheduler's ownership indexes, for tests that bound its memory (scheduler.ts indexSizes); the host replicates them into its synchronous getter.

type JobTicks

type JobTicks struct {
	Change int
	// SettleReads is the ticks of the settle's reads, SettleCached the replaced tasks the callback had read already, SettleOwners the ticks of
	// validateOwners (hopcost.Settle).
	SettleReads, SettleCached, SettleOwners int
	// Membership is the awaits of the commit's membershipKeys beyond the settle's: they delay its admission.
	Membership int
}

JobTicks is what the line job that ended charged, in Pi's await ticks (hopcost.Job): its change callback's (Change, -1 when no transaction ran) and the Storage reads and awaits of its settle.

type LineRunner

type LineRunner interface {
	RunJob() error
	DoneJob(err error)
}

LineRunner is a line job that is its own run and done: a struct holds the job's state in one allocation where closures would take several.

type Loop

type Loop struct {
	// Blocked reports that something outside the Loop holds the Session line (a host transaction, ABI section 8): queued line
	// jobs wait until it reports false and Kick runs them.
	Blocked func() bool
	// Admit, when set, is the admission check of a line job as it is enqueued (session.ts #assertUsable): a job it
	// rejects never runs, and its done receives the error as a microtask.
	Admit func() error
	// Elapsed, when set, is asked as each line job's body ends for Pi's duration of the job, in ticks from its start on the line: to the
	// resumption of `await change(tx)`, where the Session is checked healthy (callback), and to the return of its work (work): the
	// change callback's awaits and the settle's, for a commit (hopcost.Job.Return); a read job's (hopcost.ReadReturn). Without it the
	// work returns at once; a callback of 0 is not checked.
	Elapsed func(e Ended) (callback, work int)
	// StoreTicks, when set, is asked as the writer calls the Storage for the batches it sends, and returns the ticks from the call to the
	// Storage's read of its ID counter (hopcost.IDReadLead before the receipts; the ID a job mints until then is in the next ID the call
	// stores), to the Storage's receipts (the Loop commits the batches to the Session's Store then) and to the writer's resumption from
	// `await storage.commit(...)` (hopcost.StoreCallResume). Without it the Storage answers in the tick of the call. A
	// Session.CommitBatches takes the call instead.
	StoreTicks func(batches [][]Write) (read, receive, resume int)
	// Hops, when set, parks r on a chain of n hops and returns true; r.Resume runs once the chain ran, at once in the host's hopped step.
	// The host keeps r itself, not a closure over it, so a continuation that carries its own state (a job, an invocation) costs the
	// host no allocation.
	Hops func(n int, r Resumer) bool
	// Macro, when set, takes a macrotask (`setImmediate`): it runs r.Resume after the microtask queue drained, and reports true. Without
	// it the Loop runs it itself when Run has nothing else to run.
	Macro func(r Resumer) bool
	// Started, when set, runs as each line job starts.
	Started func()
	// Origin is the host async context of the code that is running (ABI section 5.4): Defer and the line capture it, and the
	// Loop makes it current again when it runs the item or job. 0 is none. Retain and Release, when set, are told of every
	// origin the line holds a job for, from the job's queuing to the end of its run.
	Origin          uint32
	Retain, Release func(origin uint32)
	// contains filtered or unexported fields
}

Loop is the core's stand-in for the JavaScript event loop and the Session line. Continuations that Pi runs as promise reactions or queueMicrotask callbacks run here as queue items in FIFO order; a commit job runs to completion in one item, so jobs serialize as they do on Pi's mutation line.

A job whose store read needs the host (*NeedRead) parks the Loop with that request: Run returns it, and after the host answered, Run resumes with the same job from the start. Nothing else runs while a job is parked, as nothing else runs while Pi's line awaits storage. A job that touches a key an unpublished commit writes (*NeedPublication) holds the line while it waits for that commit's publication, and then runs again from the start: the Pi callback goes on after its `await gate`.

Time passes in ticks, the microtask passes of the JavaScript loop. A line job's body runs at once, when the line is free; Pi's job takes Elapsed ticks to the point its `work` returns (session.ts #runCommit's admission of a commit to the writer, or its return), and the rest of the line's life of the job follows from the Session's own promise structure (hopcost): the line is free LineRelease ticks after the return, the writer stores the parts it admitted (StoreTicks) and publishes them in line order a macrotask apart, and each job's outcome is delivered in line order (the fences of session.ts #enqueue). Every wait is Wait: the host's Hops chain, or, without one, that many items of the microtask queue.

func (*Loop) Bind

func (l *Loop) Bind(s *Session)

Bind makes s the Session whose commits the line jobs of l make: l admits the part a job made to s's writer when the job's work returns, and delivers the job's outcome when the part is published; s's writer waits in l's ticks.

func (*Loop) Busy

func (l *Loop) Busy() bool

Busy reports whether a line job is queued, running, held or waiting for the host or for a publication.

func (*Loop) Consumed

func (l *Loop) Consumed() int

Consumed is the ticks of the running job's duration that passed before the touch it last waited at, in earlier runs of its body: Pi's callback ran them while it waited, so ticks the body schedules at an offset of the job's duration come that much earlier.

func (*Loop) Defer

func (l *Loop) Defer(fn func())

Defer queues fn as a microtask. When the array is full and at least half of it is spent front, the queued items move to the front instead of the array growing: the array stays proportional to what is queued, and each move is paid for by the items that ran since the last one.

func (*Loop) DeferDone

func (l *Loop) DeferDone(done func(error), err error, late bool)

DeferDone delivers done(err) as a microtask, a tick later when late, as the done of a job the Admit check rejected.

func (*Loop) DeferResumer

func (l *Loop) DeferResumer(r Resumer)

DeferResumer queues r.Resume as a microtask.

func (*Loop) Idle

func (l *Loop) Idle() bool

Idle reports whether the Loop has nothing queued and is not parked, and every outcome is delivered.

func (*Loop) Kick

func (l *Loop) Kick()

Kick starts the next line job after the holder of the line released it.

func (*Loop) LateNext

func (l *Loop) LateNext()

LateNext makes the next job queued through a Line method late: its done runs a tick after its delivery. runtime.commit is an async function that returns the promise of the commit, and its caller resumes a tick after the commit's resolution.

func (*Loop) Line

func (l *Loop) Line(run func() error, done func(error))

Line queues a job on the Session line. run is the job body; it restarts from scratch after a NeedRead or a NeedPublication. done receives the job's final error (nil on success) when its outcome is delivered.

func (*Loop) LineAfterTail

func (l *Loop) LineAfterTail(run func() error, done func(error))

LineAfterTail is Line for a commit job queued through `#enqueue` (session.ts :530-531): on an idle line it starts a tick later, as `this.#tail.then(job)` does on an already resolved tail.

func (*Loop) LineBare

func (l *Loop) LineBare(run func() error)

LineBare queues a job that only takes the line for someone else, a host transaction that holds it until Blocked reports false: it keeps its place in the line's order and takes no job duration of its own.

func (*Loop) LineHost

func (l *Loop) LineHost(grant func() error, done func(error)) *HostJob

LineHost queues a host job: grant runs when it takes the line (the host's callback may begin), and an error it returns ends the job at once (the Session is closed or failed, or the caller's signal was aborted). done receives the job's outcome, once it is delivered. grant returns ErrHostNotGranted for a transaction the host abandoned while it waited: the job takes nothing and has no outcome.

func (*Loop) LineHostLead

func (l *Loop) LineHostLead(grant func() error, done func(error), lead int) *HostJob

LineHostLead is LineHost whose done is called lead ticks (at most Delivery) before the tick its caller resumes: the host answers its caller's promise ahead of the caller's own resumption (a facade that lags the answer by lead ticks). The outcome is still delivered, and counted, at its own tick; a failure that poisons the job is decided when done is called.

func (*Loop) LineInternal

func (l *Loop) LineInternal(run func() error, done func(error))

LineInternal is Line for a job of the scheduler's own whose outcome goes only to scheduler code (session.ts commitInternal): when it admits no part and waits at no gate, its outcome is delivered as soon as it has one, ahead of the outcomes of the jobs before it.

func (*Loop) LineMaintain

func (l *Loop) LineMaintain(run func() error)

LineMaintain queues a job of the Session's own upkeep on the line (session.ts #maintain): it has no outcome to deliver, so no fence.

func (*Loop) LineRunnerAfterTail

func (l *Loop) LineRunnerAfterTail(r LineRunner)

LineRunnerAfterTail is LineAfterTail for a job that is its own run and done: r and the job are the two allocations of the queued job.

func (*Loop) Macrotask

func (l *Loop) Macrotask(r Resumer)

Macrotask runs r.Resume once the microtask queue drained and the macrotasks queued before it ran (`setImmediate`).

func (*Loop) NextTick

func (l *Loop) NextTick(fn func())

NextTick runs fn one tick later: the resumption of an `await` of an async function that returned in the tick the line job it awaited resolved (scheduler.ts #run awaits #step, which awaits commitWith). Without a host's hops it runs fn at once.

func (*Loop) NextTickResumer

func (l *Loop) NextTickResumer(r Resumer)

NextTickResumer is NextTick for a continuation that keeps its own state.

func (*Loop) OnComplete

func (l *Loop) OnComplete(fn func())

OnComplete runs fn when the running line job's outcome is delivered after a successful commit, right before its caller resumes, as the code that resumes after the awaited commit does. A job that runs again (a *NeedRead or *NeedPublication) drops what it asked for.

func (*Loop) OnJobEnd

func (l *Loop) OnJobEnd(end Resumer)

OnJobEnd calls end once the outcome of the job on the line settles (its commit published, or never to be); at once off the line.

func (*Loop) Outstanding

func (l *Loop) Outstanding() int

Outstanding is the number of jobs that started and have no outcome delivered yet (session.ts lineSizes.outstanding).

func (*Loop) Parked

func (l *Loop) Parked() *NeedRead

Parked returns the read request the Loop waits on, or nil.

func (*Loop) QueueAfterTail

func (l *Loop) QueueAfterTail(j *job)

QueueAfterTail is LineAfterTail for a job that is its own run and done: j.rn is set, and the job is queued by address.

func (*Loop) QueueInternal

func (l *Loop) QueueInternal(j *job)

QueueInternal is QueueAfterTail for a job of the scheduler's own whose outcome goes only to scheduler code (LineInternal).

func (*Loop) QueuedOrigins

func (l *Loop) QueuedOrigins(f func(origin uint32))

QueuedOrigins calls f with the origin of every microtask still queued: a Loop parked on a host answer keeps them across steps.

func (*Loop) ReadLine

func (l *Loop) ReadLine(run func() error, done func(error))

ReadLine queues a Session.readOnLine job (session.ts:105-115): a read-only job on the line, whose duration is its reads (Elapsed).

func (*Loop) ReadLineLead

func (l *Loop) ReadLineLead(run func() error, done func(error), lead int)

ReadLineLead is ReadLine whose done is called lead ticks (at most Delivery) before the tick its caller resumes: the host answers its caller's promise ahead of the caller's own resumption (a facade that lags the answer by lead ticks), as LineHostLead does for a transaction.

func (*Loop) Restarted

func (l *Loop) Restarted() bool

Restarted reports whether the body of the running job is running again, after a *NeedRead or a *NeedPublication ended an earlier run: what Pi checks once when a job starts (session.ts #runCommit throwIfAborted) is not checked again.

func (*Loop) Resume

func (l *Loop) Resume() error

Resume re-runs the parked job and continues; the host must have answered its reads.

func (*Loop) Run

func (l *Loop) Run() error

Run processes queued items until none remain: the microtask queue first, then, when it is empty, the macrotasks one at a time (a Macro hook takes them instead). A job parked on a host read holds the line only: what runs outside the line (a delivery of an earlier outcome, the writer) goes on, as it does in Pi while the job awaits its read. It returns ErrParked when a job is parked; call Resume after the host served the reads.

func (*Loop) Until

func (l *Loop) Until(d int) int

Until is the ticks from now to the tick d of the running job's duration. The body of a job runs at once, in the tick the job starts, which for a job that starts on an idle line is a tick before Pi's (the job's start); a body that runs again after a touch has spent the ticks the earlier run waited (Consumed).

func (*Loop) Wait

func (l *Loop) Wait(n int, r Resumer)

Wait runs r.Resume n ticks from now: after a chain of the host's hops, or, without one, n microtask passes; at once for n <= 0.

type NeedPublication

type NeedPublication struct {
	Gate *Gate
	At   int
	// Extra is the ticks the continuation takes beyond the publication's own (hopcost.GateResume): the gate of a read through gatedStore is
	// followed by `.then(read)`, whose promise adopts the read's.
	Extra int
}

NeedPublication is the error a read or a barrier returns when a key it touches has an unpublished writer (session.ts touch): the line job that returned it keeps the line while it waits, and runs again from its start once the part that writes the key is published or will never be (the job saw state that is stored by then, as Pi's continues after its `await gate`). At is the ticks the job had spent when it touched the key: Pi's callback ran them while it waited, so only the rest of its duration follows the publication.

func (*NeedPublication) Error

func (e *NeedPublication) Error() string

type NeedRead

type NeedRead struct {
	Reads []ReadRequest
}

NeedRead is the error a Store returns when the loaded state cannot answer a read. The callback that hit it is discarded and runs again after the host answers; Reads names what the host must fetch.

func IsNeedRead

func IsNeedRead(err error) (*NeedRead, bool)

IsNeedRead reports whether err is, or wraps, a *NeedRead.

func (*NeedRead) Error

func (e *NeedRead) Error() string

type Ownership

type Ownership struct {
	// Task is the owning task; zero means ownerless.
	Task ID
}

Ownership is how a created conversation is attributed.

type Page

type Page struct {
	Items []*jv.Object
	After ID
}

Page is one page of a scan. After is the cursor for the next page, 0 when none.

type Part

type Part struct {
	// Index is the line index of the job that admitted it: a failure it causes makes only later jobs' outcomes SessionFailed.
	Index int
	// Writes are the commit's writes, or nil for a commit held in memory (held.go).
	Writes []Write
	// Keys are the keys it writes: a read of one waits for its publication.
	Keys []string
	// Publish publishes it in memory, in line order, once it is durable (with its seq) or, held, once the parts before it are. A
	// non-nil result is its own failure at publication: memory could not adopt it. A part the Session made (newPart) has none: its kind
	// says how it is published.
	Publish func(seq Seq) error
	// Discard is called when it will never be published: it aborts what the part prepared.
	Discard func()
	// contains filtered or unexported fields
}

Part is one logical commit the line admitted: stored (Writes, never empty), or held in memory only (no Writes).

func (*Part) Done

func (p *Part) Done() bool

Done reports whether the part's outcome settled: it was published, or never will be.

func (*Part) Err

func (p *Part) Err() error

Err is the error the part's outcome settled with, nil when it was published and no failure rejected it after.

func (*Part) Gate

func (p *Part) Gate() *Gate

Gate is the gate that opens once the part is published or never will be.

func (*Part) OnOutcome

func (p *Part) OnOutcome(r Resumer)

OnOutcome resumes r once the part's outcome settles, at once when it did: Err is then its outcome.

func (*Part) Publication

func (p *Part) Publication() *Publication

Publication is what the part published, nil until it did, and for a part held in memory or one that stores no commit of its own.

type PhaseInfo

type PhaseInfo struct {
	Task    ID
	Kind    string
	Phase   string
	Abort   bool
	Resumed bool
	// Attempt is the checkpoint's attempt, when HasAttempt.
	Attempt    float64
	HasAttempt bool
	// Trace is the record's stored carrier, the span's parent; nil starts at the Harness's root.
	Trace any
	// Links are the record's creation-time carriers, given to the first invocation only (invocation.links).
	Links any
	// contains filtered or unexported fields
}

PhaseInfo is what the host needs to start the `pi.durable.phase` span of one phase invocation (scheduler.ts #phase). The host answers with Started, and the invocation runs the phase once it has.

func (*PhaseInfo) Answered

func (p *PhaseInfo) Answered(v any, err error)

Answered is Started for the host's answer to the span hook, `{span, carrier?}`: a failed hook starts the phase without a span.

func (*PhaseInfo) Started

func (p *PhaseInfo) Started(span uint32, carrier any)

Started is the host's answer to StartPhase: its handle of the span, and the span's carrier (propagation.inject(span)), which the tasks the phase creates inherit as their trace. The invocation runs its phase as the call returns.

type PhaseOutcome

type PhaseOutcome uint8

PhaseOutcome is the `outcome` attribute of a phase span: `next=<phase>`, waiting, sleeping, done, faulted or aborted.

const (
	PhaseNext PhaseOutcome = iota + 1
	PhaseWaiting
	PhaseSleeping
	PhaseDone
	PhaseFaulted
	PhaseAborted
)

Phase outcomes.

type Point

type Point struct {
	Current bool
	Seq     Seq
}

Point addresses a document at "current" or as of a commit sequence.

func AsOf

func AsOf(seq Seq) Point

AsOf is the point of commit seq.

type Publication

type Publication struct {
	Seq Seq
	// Changes is what the Session's own observers see: this commit's own changes. A deferred commit adopted in memory only
	// (Memory) has the document changes and no Seq.
	Changes []Change
	// Memory is set for a commit held in memory (held.go): it is not stored, and the commit listeners that follow the Storage
	// (the host's subscribeCommits) get nothing.
	// Span is the host's handle of the span of the commit's Context: where the commit's entry and settlement events go (TxScope.Span).
	Span   uint32
	Memory bool
	// Stored is every change one Storage transaction stored, tables included, when that differs from Changes: a commit that
	// also stored held changes of the documents it reads or writes (its document change carries the held operations first), or
	// a deadline's store of held documents (no Changes: nothing is shown again). Nil: it is Changes.
	Stored []Change
	// Created is the tasks the commit created, whose documents the Session then knows (taskdocs.go).
	Created []ID
}

Publication is what one applied commit changed.

func (*Publication) StoredChanges

func (p *Publication) StoredChanges() []Change

StoredChanges is what the Storage transaction of the publication stored.

type ReadOnlyError

type ReadOnlyError struct{ What string }

ReadOnlyError is Pi's ReadOnlySession (errors.ts): the refusal of what, such as "a commit with writes" or "running tasks".

func (*ReadOnlyError) Error

func (e *ReadOnlyError) Error() string

func (*ReadOnlyError) Is

func (e *ReadOnlyError) Is(target error) bool

Is matches ErrReadOnlySession.

type ReadRequest

type ReadRequest struct {
	Kind string
	Args []any
}

ReadRequest identifies one read of committed state the host must serve.

type RefusedError

type RefusedError struct{ Err error }

RefusedError wraps the error a Store's Commit returns when one of Durable's own checks refuses the batch (global IDs, document actions, copy resolution), run against the state before the batch writes anything: the batch is not durable, and the batches before it in the writer's call are. Any other error of Commit is an unknown outcome and fails the Session.

func (*RefusedError) Error

func (e *RefusedError) Error() string

func (*RefusedError) Unwrap

func (e *RefusedError) Unwrap() error

type ReportFrom

type ReportFrom struct{ Extension, Callback string }

ReportFrom is whose code a task's Report is about when not the task's own: an extension's (Extension, when known), or a host callback (Callback, a HostCallback name such as env or models).

type Resumer

type Resumer interface{ Resume() }

Resumer is a continuation that keeps its own state: the Loop runs it as a microtask (DeferResumer) or the host after a chain of hops (Loop.Hops) without a closure made for each use.

type Runtime

type Runtime struct {
	// contains filtered or unexported fields
}

Runtime is the facade a task phase handler uses, bound to one invocation (TaskRuntime of types.ts). Every operation fails once the invocation ended. Operations that Pi returns as promises take a continuation that runs as a microtask after the operation settles.

func (*Runtime) AbandonHost

func (r *Runtime) AbandonHost(tx *Tx, err error)

AbandonHost ends the host transaction of BeginHost without a commit.

func (*Runtime) AbortOwned

func (r *Runtime) AbortOwned(id ID, then func(error))

AbortOwned aborts a task this task owns and calls then once it is terminal (scheduler.ts abortOwned).

func (*Runtime) BeginHost

func (r *Runtime) BeginHost(span uint32, trace any) (tx *Tx, current *jv.Object, err error)

BeginHost opens a commit whose callback runs in the host, one operation per event (ABI section 8): the checks of Commit run now, at the moment the host's transaction takes the Session line, and the returned transaction is scoped to the task. The caller must hold the line until FinishHost or AbandonHost.

func (*Runtime) Commit

func (r *Runtime) Commit(change func(tx *Tx, current *jv.Object) (next *jv.Object, err error), then func(error))

Commit commits on the Session line after rereading the task. change may stage writes through tx and return the state the task commits for itself (nil leaves it unchanged). It fails when the task is terminal, the invocation ended, the Harness is closing or, in a run invocation, the task carries an abort mark.

func (*Runtime) CommitDeferred

func (r *Runtime) CommitDeferred(change func(tx *Tx, current *jv.Object) (next *jv.Object, err error), then func(error))

CommitDeferred is Commit with CommitOptions{persistence: {kind: "deferred"}} (harness/live.ts PROGRESS_COMMIT): a commit that changes only latest, initial-fork conversation documents is adopted in memory and stored later (held.go), by the Session's default window. A commit that returns a state is stored at once.

func (*Runtime) ConversationID

func (r *Runtime) ConversationID() ID

ConversationID is the task's conversation.

func (*Runtime) Ended

func (r *Runtime) Ended() bool

Ended reports whether the invocation ended.

func (*Runtime) EndedError

func (r *Runtime) EndedError() error

EndedError is the error of an operation of an ended invocation.

func (*Runtime) Extension

func (r *Runtime) Extension() string

Extension is the extension that installed the definition this invocation runs, as of its reservation; empty for a built-in task.

func (*Runtime) FinishHost

func (r *Runtime) FinishHost(tx *Tx, current, next *jv.Object) (*Publication, error)

FinishHost commits the host transaction of BeginHost: next, when not nil, is the state the task commits for itself.

func (*Runtime) GetTask

func (r *Runtime) GetTask(id ID, then func(*jv.Object, error))

GetTask returns a committed task record, or nil.

func (*Runtime) MarkEndedByCrashes

func (r *Runtime) MarkEndedByCrashes(message string)

MarkEndedByCrashes marks the terminal state the commit's change is about to return as ending its task for crashes: the scheduler reports it task_interrupted with message, whatever its outcome (scheduler.ts endedByCrashes). Call it inside the change.

func (*Runtime) Memo

func (r *Runtime) Memo(name string, candidate any, then func(winner any, err error))

Memo stores candidate unless a memo of that name exists and returns the durable winner.

func (*Runtime) MemoGet

func (r *Runtime) MemoGet(name string) (any, bool, error)

MemoGet reads a memo of this task.

func (*Runtime) Now

func (r *Runtime) Now() (float64, error)

Now is the Harness clock.

func (*Runtime) OnEnded

func (r *Runtime) OnEnded(fn func())

OnEnded runs fn when the invocation ends (scheduler.ts #end), or at once when it already has.

func (*Runtime) Outcomes

func (r *Runtime) Outcomes(ids []ID, then func([]*jv.Object, error))

Outcomes returns the outcomes of terminal tasks, in order.

func (*Runtime) OwnedTasks

func (r *Runtime) OwnedTasks(then func([]*jv.Object, error))

OwnedTasks calls then with copies of the live tasks this task owns directly, in ID order, whichever invocation created them (scheduler.ts ownedTasks): every live task is listed under its parent node, its owner task when it has one. Tasks in conversations it owns are not included. It fails when the invocation has ended.

func (*Runtime) Read

func (r *Runtime) Read(job func() error, then func(error))

Read runs job as a read-only job on the Session line (scheduler.ts #read with Session.readOnLine): it waits behind the commits already queued, so a read observes the state those commits left, and then calls then with its error. It fails when the invocation has ended, before and after the wait.

func (*Runtime) Replay

func (r *Runtime) Replay(name string)

Replay records that a nested tool call was answered from its stored result (tool.ts: the `pi.durable.replay` event).

func (*Runtime) Report

func (r *Runtime) Report(err error, from ...ReportFrom) error

Report forwards a non-fatal failure to the host with this task in its info: a task_error about the task's own code, or, with from, an extension_error about extension code it called, such as a section, or a host_error about a host callback, such as the environment builder (scheduler.ts runtime.report).

func (*Runtime) ReportEnded

func (r *Runtime) ReportEnded()

ReportEnded reports what the commit that just returned to the task ended it for, if it ended it for crashes: the commit of Commit when its done runs (the Loop), the host's transaction when the core answers its end.

func (*Runtime) Signal

func (r *Runtime) Signal() *Cancel

Signal is aborted when the run is signalled by AbortTask, the Harness closes or the invocation ends.

func (*Runtime) SleepUntil

func (r *Runtime) SleepUntil(until float64, checkpoint any, then func(error))

SleepUntil commits a sleep: the task holds no invocation until the Harness clock reaches until, then resumes at checkpoint. then runs once the sleep is stored, not when the time comes (scheduler.ts sleepUntil, a #gated #commitState).

func (*Runtime) Snapshot

func (r *Runtime) Snapshot() Snapshot

Snapshot is the registry snapshot of the current phase.

func (*Runtime) Span

func (r *Runtime) Span() uint32

Span is the handle of the span of the phase the runtime's invocation is running, 0 when it is in none.

func (*Runtime) TaskID

func (r *Runtime) TaskID() ID

TaskID is the running task.

func (*Runtime) ToolCall

func (r *Runtime) ToolCall(name, callID string)

ToolCall sets the called tool's name and call ID on the phase's span (tool.ts readCall).

func (*Runtime) WaitForTask

func (r *Runtime) WaitForTask(id ID, then func(rec *jv.Object, err error, waited bool))

WaitForTask resolves with the task's terminal record; it fails when the invocation ends first.

type Scheduler

type Scheduler struct {
	// contains filtered or unexported fields
}

Scheduler is pi-durable's TaskScheduler (harness/scheduler.ts) as a synchronous state machine over a Session and a Loop: it keeps the live tasks, reserves them for invocation, runs their phases through continuation-passing handlers, and settles ownership, abort and join rules.

func NewScheduler

func NewScheduler(sess *Session, loop *Loop, env Env) *Scheduler

NewScheduler returns a scheduler over the Session, on the Loop.

func (*Scheduler) Abort

func (s *Scheduler) Abort(id ID, keepRestart bool, cancel *Cancel, then func(result string, err error))

Abort marks a task for abort. then receives "marked" or "terminal"; for a task whose invocation runs, it is called after that invocation ended.

func (*Scheduler) AbortConversation

func (s *Scheduler) AbortConversation(conversationID ID, background bool, cancel *Cancel, then func(error))

AbortConversation marks every task below a conversation for abort and waits for idle; with background, background tasks too, waiting for each.

func (*Scheduler) BlockedReason

func (s *Scheduler) BlockedReason(rec *jv.Object) string

BlockedReason is why a live task cannot run here, if it cannot: its definition is missing (missing_task), too old (task_too_old), or failed to migrate (migration_failed); empty when it can. A running task, an abort-marked one, and one holding its outcome are never blocked (scheduler.ts blockedReason).

func (*Scheduler) Bound

func (s *Scheduler) Bound(taskID ID) *Cancel

Bound is the signal of an operation made through an invocation-bound handle (harness.ts boundConversation, withAbortSignal(binding.signal, ...)): the operation's line job checks it at start (session.ts:411 throwIfAborted). A task without a running invocation yields a signal already aborted as ended.

func (*Scheduler) CloseWrites

func (s *Scheduler) CloseWrites() []*jv.Object

CloseWrites is the records of the tasks the close stopped, as pending, to write back straight to Storage with nothing published, as a close is not a crash: the next open counts no restart for them (scheduler.ts join through session.ts writeAtClose). A live task that is running when the close ends is one this Harness reserved, since open writes every other running task back as pending: its invocation was stopped by the close, or its reservation settled while the close began. It reads the records as they stand now, so the write keeps what commits admitted before the seal wrote, such as an abort mark.

func (*Scheduler) IdleState

func (s *Scheduler) IdleState() (contexts, idleContexts, mismatches, fullChecks int)

IdleState is the kept contexts' idle state, computed on demand (scheduler.ts idleState, a diagnostic for tests): how many are kept and how many are idle, how many disagree with a full recompute (an idle period without idle, or idle without one; an expiry order that differs from the idle periods, or is not sorted), and how many idle checks covered every scope.

func (*Scheduler) IndexSizes

func (s *Scheduler) IndexSizes() IndexSizes

IndexSizes returns the sizes of the scheduler's ownership indexes.

func (*Scheduler) Inspect

func (s *Scheduler) Inspect(snapshot Snapshot) (scheduling string, tasks []TaskInspection, err error)

Inspect is scheduler.ts inspect: the scheduling state and every live task with its derived state. It runs no task code: a pending migration shows as pending with Migrates, and only a migration the scheduler already tried, or one that cannot exist, shows as failed. It first waits for every commit admitted before to be published (`await this.#published()`: the job runs again once they are, and the await of the settled promise costs one tick), then loads the scopes.

func (*Scheduler) IsIdle

func (s *Scheduler) IsIdle(conversationID ID) bool

IsIdle reports whether WaitForIdle(conversationID) answers at once: the Scheduler is open and the scope has no live task.

func (*Scheduler) Join

func (s *Scheduler) Join(then func())

Join calls then once every running invocation has ended.

func (*Scheduler) KeepContext

func (s *Scheduler) KeepContext(conversationID ID, r ContextRange, invocationEnded bool)

KeepContext keeps the range a runtime read returned unless the invocation ended, the Harness is closing, or a concurrent read already kept a newer range. A read of another, idle conversation starts or continues its retention period.

A range that is Current stays so only if the Session knows its tail as the conversation's newest entry now: a commit published since the read returned was not seen by advanceContexts, so a range that missed it must not be advanced.

func (*Scheduler) KeptContext

func (s *Scheduler) KeptContext(conversationID ID) (ContextRange, bool)

KeptContext returns the bounds of the range kept for the conversation.

func (*Scheduler) KeptEntry

func (s *Scheduler) KeptEntry(conversationID, id ID) bool

KeptEntry reports whether entry id lies within the range kept for the conversation: such an entry is committed and visible from it (scheduler.ts runtime.entry reads it from the kept range, rangeEntry).

func (*Scheduler) Open

func (s *Scheduler) Open(done func(error))

Open loads the live tasks in one commit, resets running tasks to pending and arms reconciliation. The scheduler observes the Session's commits from here on.

func (*Scheduler) RegistryChanged

func (s *Scheduler) RegistryChanged()

RegistryChanged is the registry subscription (scheduler.ts open): a new snapshot may change the blocked reasons, which the graph derives again at once, and may make blocked tasks runnable.

func (*Scheduler) ReportSpan

func (s *Scheduler) ReportSpan() uint32

ReportSpan is the span of the Context the report being delivered is made under (scheduler.ts #report's context), 0 for none: the host records the report event there. It is set only while Env.Report runs.

func (*Scheduler) Resume

func (s *Scheduler) Resume()

Resume enables scheduling, makes sleeping tasks that are due runnable (a host wakeup, such as an alarm, calls this), and starts any reservable task.

func (*Scheduler) Seal

func (s *Scheduler) Seal()

Seal stops scheduling: waiters reject, and the invocation signals abort in a microtask (signalInvocations).

func (*Scheduler) SetOnWake

func (s *Scheduler) SetOnWake(fn func(w Wake))

SetOnWake makes the scheduler tell fn each change of Wake instead of arming a timer for sleeping tasks.

func (*Scheduler) SpanOf

func (s *Scheduler) SpanOf(id ID) uint32

SpanOf is the handle of the span of the phase task's invocation is running, 0 when it is in none.

func (*Scheduler) WaitForIdle

func (s *Scheduler) WaitForIdle(conversationID ID, cancel *Cancel, then func(error))

WaitForIdle calls then when the conversation (0: every root) has no live non-background task or queued input below it.

func (*Scheduler) WaitForTask

func (s *Scheduler) WaitForTask(id ID, cancel *Cancel, then func(rec *jv.Object, err error))

WaitForTask calls then with the task's terminal record. A task that is not live is read from the store on the line.

func (*Scheduler) WaitForTaskFound

func (s *Scheduler) WaitForTaskFound(id ID, cancel *Cancel, then func(rec *jv.Object, err error, waited bool))

WaitForTaskFound is WaitForTask for a host caller: a read job on the line (readOnLine, scheduler.ts :306-316) whose caller returns `found.promise`. then reports whether the record came from a waiter the job registered (a live task, resolved by the terminal publication) or from the store (an already settled promise).

func (*Scheduler) Wake

func (s *Scheduler) Wake() Wake

Wake is scheduler.ts wake: synchronous, from memory; a task whose chain is not loaded yet counts as it would alone.

Wake runs after every commit, so its cost must not grow with the live tasks while one runs: the earliest sleep comes from the sleeping index, as wakeDue reads it, and the walk over the live tasks that looks for one that can run now (anyRunnable) is skipped when a running invocation or a reconcile pass with work already answers that. Walking every live task each time made ending a chain of 20,000 held tasks 20,000 walks of 20,000 records, each record a key search here, not the property read it is in scheduler.ts.

func (*Scheduler) WriteBack

func (s *Scheduler) WriteBack(records []*jv.Object) error

WriteBack writes the records CloseWrites returned; a *NeedPublication error means the writer has not published what the job waits for, and the job that called it runs again after it did.

type Scope

type Scope struct {
	Kind  ScopeKind
	Owner ID // conversation or task ID; zero for the session
}

Scope is the owner of a document: the Session, a conversation or a task.

type ScopeKind

type ScopeKind string

ScopeKind is the owner kind of a document.

const (
	ScopeSession      ScopeKind = "session"
	ScopeConversation ScopeKind = "conversation"
	ScopeTask         ScopeKind = "task"
)

The document scopes.

type Seq

type Seq = int64

Seq is the sequence of one storage commit.

type Session

type Session struct {

	// SweepJobs counts the sweep jobs queued on the line so far (documentCacheSizes.sweeps). EnqueueSweep queues a detached job on
	// the Session line (a *NeedPublication its job returns runs it again once the key's writer is published), Microtask runs fn as a
	// microtask, ArmTimer arms a host timer that calls fire at the time at, ArmForeground one that paces or resumes work (the
	// deadline of deferred commits); a Session without them keeps no sweep job or timer.
	SweepJobs     int
	EnqueueSweep  func(job func() error)
	Microtask     func(fn func())
	ArmTimer      func(at float64, fire func()) (cancel func())
	ArmForeground func(at float64, fire func()) (cancel func())
	// PersistWithin is the default window of a deferred commit in milliseconds, read at each use (settings.progress.persistWithinMs);
	// false means the default.
	PersistWithin func() (float64, bool)
	// holdOrder is the documents with held changes, in the order they were first held; each is pinned in
	// the cache until its changes are stored (held.go).
	// TrackDropped makes the Session list the incarnations that leave the cache (TakeDropped); dropped is the list.
	TrackDropped bool

	// DocumentRetention is the document retention in milliseconds read at each use (HarnessSettings.documentRetentionMs); nil or
	// a nil result means the default.
	DocumentRetention func() *float64

	// OnFail reports the storage error that failed the Session, once (session.ts fail).
	OnFail func(error)

	// CommitBatches, when set, is the Storage call of the writer: the host's Storage stores the batches in order and answers through
	// receive (a durability receipt per batch, in order) and done (the call's result, or the error of a call that rejected), in the tick
	// the writer resumes from `await storage.commit(...)`. Without it the writer commits batch by batch through the Store, and the Loop's
	// StoreTicks say when.
	CommitBatches func(batches [][]Write, nextID ID, receive func(index int, seq Seq), done func(CommitResult, error))
	// Publishing, when set, is the Storage's own scope for a publication (Pi's optional Storage.publishing): the writer calls it with each part's
	// publication before it runs it. Returning true says the host runs publish itself, once, later; the writer then goes on from there. Returning
	// false makes the writer publish directly (publish may also have been called already).
	Publishing func(publish func()) bool
	// HeldHost, when set, is the host's side of the adoption of a commit held in memory (Pi's Transaction.adoptHeld): the writer calls it
	// before it publishes the part, and publishes it, or fails the Session with the error, when done is told. done is told once, in the
	// step that carries the host's answer.
	HeldHost interface{ AdoptHeld(done HeldAdopter) }

	// MembershipKeys, when set, is the keys a commit writes besides its records' (Transaction.writeKeys): the Scheduler adds the ownership
	// memberships its task changes write (scheduler.ts membershipKeys). An error restarts the job (*NeedRead, *NeedPublication) or fails it.
	MembershipKeys func(tx *Tx) ([]string, error)

	// HostAdmits: the host admits calls itself, so the seal does not reject a call it admitted before the seal (assertUsable).
	HostAdmits bool
	// ReadOnly refuses every commit with writes and every scheduling call (HarnessOptions.readOnly): ReadOnlyError, before the store,
	// so the Session stays healthy.
	ReadOnly bool

	// ConversationCreated runs inside every transaction that creates or forks a
	// conversation, after the conversation record is staged. A plain Session
	// stages nothing; a Harness stages its built-in documents.
	ConversationCreated func(tx *Tx, record *jv.Object) error
	// contains filtered or unexported fields
}

Session is the Session kernel: the mutation line's committed-state cache and the commit procedure of session/session.ts. It is single-threaded; its owner serializes calls.

func New

func New(store Store, nextID ID, now func() float64) *Session

New returns a Session over a store. nextID is the next unminted record ID and now the Harness clock.

func (*Session) Abandon

func (s *Session) Abandon(tx *Tx, err error)

Abandon seals a transaction whose callback failed with err; it stages nothing. A restarting failure restores the ID counter, since the callback runs again from scratch.

func (*Session) Admit

func (s *Session) Admit() error

Admit is the admission check of an operation as it is enqueued on the Session line (session.ts #assertUsable in commitWith and readOnLine): it fails once the Session is closed or poisoned.

func (*Session) Begin

func (s *Session) Begin(scope TxScope) (*Tx, error)

Begin opens a transaction whose callback runs outside this call: a host drives it one operation at a time (ABI section 8) and ends it with Finish or Abandon. Commit is Begin, the callback, and Finish.

func (*Session) ChargeRead

func (s *Session) ChargeRead(n int)

ChargeRead charges n ticks of a read job's own awaits (a line job without a transaction).

func (*Session) Close

func (s *Session) Close()

Close seals the Session and drops its commit listeners and loaded documents, as the close job does after the Harness joined its invocations.

func (*Session) ColdEntryAwaits

func (s *Session) ColdEntryAwaits() int

ColdEntryAwaits is hopcost.ColdEntryAwaits of this Session.

func (*Session) ColdMarkerAwaits

func (s *Session) ColdMarkerAwaits() int

ColdMarkerAwaits is hopcost.ColdMarkerAwaits of this Session.

func (*Session) Commit

func (s *Session) Commit(change func(tx *Tx) error, scope TxScope) (*Publication, error)

Commit runs change on the Session line as one commit and returns the commit's publication when the commit was published as it was admitted (a Session without a Loop). A callback that errors stages nothing: the error is returned and IDs it minted stay consumed, as a rolled-back Pi callback leaves a gap. When any read returns a *NeedRead or a *NeedPublication the callback restarts from scratch after the host answered or the key's writer was published: Commit restores the ID counter and returns it. An empty write set commits nothing and returns a nil publication.

func (*Session) DocumentCacheSizes

func (s *Session) DocumentCacheSizes() (cached, idle int)

DocumentCacheSizes is the number of cached documents and how many of them are idle (session.ts documentCacheSizes); the rest are pinned by observers, and the core has none.

func (*Session) DocumentsAttached

func (s *Session) DocumentsAttached() int

DocumentsAttached is the number of incarnations an observer pins (session.ts documentCacheSizes.attached).

func (*Session) Fail

func (s *Session) Fail(err error)

Fail fails the Session with err, as a failing Storage call does (session.ts fail): the host's Storage rejected a commit it had adopted, which stays applied and published.

func (*Session) Failure

func (s *Session) Failure() error

Failure returns the first storage error that failed the Session, or nil.

func (*Session) Finish

func (s *Session) Finish(tx *Tx) (*Publication, error)

Finish settles a transaction whose callback succeeded and admits its writes to the writer, as the tail of Commit: the commit is stored and published by the writer, later. It returns the publication only when the writer published it before it returned.

func (*Session) HasUnrevealedLoads

func (s *Session) HasUnrevealedLoads() bool

revealLoads makes the documents the finished job loaded visible to Loaded. HasUnrevealedLoads reports whether a line job's loads wait for its publication to show (revealLoads has something to do).

func (*Session) HeldDocuments

func (s *Session) HeldDocuments() int

HeldDocuments is the number of incarnations with held changes (session.ts documentCacheSizes.held).

func (*Session) HoldsOutcome

func (s *Session) HoldsOutcome() (error, bool)

HoldsOutcome is the outcome of the store of held changes the job's earlier run admitted and waited for (a *NeedPublication runs the job again from the start): the error that settled it, nil when it was published, and false when this job admitted none. A job that guards its store with the Session's health calls it first, so a store that failed the Session is the job's error, as `await #storeHolds` rejects.

func (*Session) InJob

func (s *Session) InJob() bool

InJob reports whether a Loop line job body is running.

func (*Session) KeepRecord

func (s *Session) KeepRecord(r hopcost.Record, id ID, rec *jv.Object)

KeepRecord keeps the record a read that missed found (cached-storage.ts #keep): a conversation or a task; a submission read is passed through, kept only as a commit writes it.

func (*Session) KnownLatestEntryID

func (s *Session) KnownLatestEntryID(conversationID ID) (id ID, known bool)

KnownLatestEntryID is the newest entry ID of a conversation as known from the Session's commits right now, without reading and without changing the recency: known is false when it is not (and always for a read-only Session); 0 is no entry.

func (*Session) LatestEntryID

func (s *Session) LatestEntryID(conversationID ID) (id ID, ticks int, err error)

LatestEntryID is the newest entry ID visible from a conversation, 0 for none (session.ts latestEntryId); ticks is the awaits the read costs its caller.

func (*Session) LatestHeadMarker

func (s *Session) LatestHeadMarker(conversationID, atOrBefore ID) (marker *jv.Object, ticks int, err error)

LatestHeadMarker is the newest visible head marker of a conversation at or before atOrBefore (0: any), nil for none, known from the Session's own commits as LatestEntryID is (session.ts latestHeadMarker); ticks is the awaits the read costs its caller.

func (*Session) Loaded

func (s *Session) Loaded(def *DocDef, args DocArgs) bool

Loaded reports whether Snapshot would answer from the loaded-document cache (session.ts snapshot: a cached tracker of the definition's version), which Pi reads without a job on the Session line.

func (*Session) LookupHeadMarker

func (s *Session) LookupHeadMarker(conversationID, atOrBefore ID) (marker *jv.Object, known bool)

LookupHeadMarker is the newest visible head marker of a conversation at or before atOrBefore (0: any) as the Session knows it, nil for none; known is false when a Storage read is needed. The newest marker answers every cutoff at or after it, and no marker answers every cutoff.

func (*Session) LookupLatestEntryID

func (s *Session) LookupLatestEntryID(conversationID ID) (id ID, known bool)

LookupLatestEntryID is the newest entry ID visible from a conversation as the Session's commits and earlier reads know it, 0 for none; known is false when a Storage read is needed (always for a read-only Session). The conversation becomes the most recently used.

func (*Session) NextID

func (s *Session) NextID() ID

NextID returns the next unminted record ID.

func (*Session) NoteHeadMarker

func (s *Session) NoteHeadMarker(conversationID, atOrBefore ID, marker *jv.Object)

NoteHeadMarker keeps the head marker a Storage read found for atOrBefore, only when no newer entry can change it: no cutoff, or one at or after the newest entry known.

func (*Session) NoteLatestEntryID

func (s *Session) NoteLatestEntryID(conversationID, id ID)

NoteLatestEntryID keeps the newest entry ID a Storage read found. It is called on the Session line after the conversation's appends are published, so no unpublished commit can change it.

func (*Session) OnFailed

func (s *Session) OnFailed(f func(error)) (remove func())

OnFailed registers f to run once with the error that fails the Session, before the seal (a race against session.ts `failed`), and returns its removal. It never runs for a Session that has already failed: the caller reads Failure.

func (*Session) PeekTicks

func (s *Session) PeekTicks() int

PeekTicks is the Change of the transaction callback that just succeeded, without clearing it: -1 when none ran.

func (*Session) PinDocument

func (s *Session) PinDocument(def *DocDef, args DocArgs) (release func())

PinDocument keeps the cached incarnation of a document in the cache for one observer (session.ts #pinDocument): it leaves the idle order, and the returned release unpins it once; the incarnation is idle again after the last release, when it is still the cached one. It returns nil when the document is not cached.

func (*Session) RecordAnswer

func (s *Session) RecordAnswer(r hopcost.Record, id ID) hopcost.Cache

RecordAnswer is how the cache answers a client read of one record (storage.conversation(id), task(id), submission(id) on the line).

func (*Session) RunCommit

func (s *Session) RunCommit(change func(tx *Tx) error, scope TxScope) (*Publication, error)

RunCommit is the body of a commit job already admitted to the Session line (session.ts #runCommit): it checks only that the Session is healthy, so a job enqueued before Seal still commits.

func (*Session) Seal

func (s *Session) Seal()

Seal is the synchronous start of Session.close (session.ts close): admission closes, so later operations fail with ErrClosed when they are enqueued (Admit), and the close listeners run once. Jobs admitted before keep running.

func (*Session) SetHopProfile

func (s *Session) SetHopProfile(p hopcost.Profile)

SetHopProfile names the Storage profile whose await ticks transactions are charged (open.storageProfile).

func (*Session) SettleCached

func (s *Session) SettleCached() int

SettleCached is the replaced tasks the settle of the transaction being committed found already read by its callback: their committed read costs one tick, not a Storage read; 0 outside a commit.

func (*Session) SettleReads

func (s *Session) SettleReads() int

SettleReads is the ticks of the reads the settle of the transaction being committed made (hopcost.Settle); it is 0 outside a commit.

func (*Session) Snapshot

func (s *Session) Snapshot(def *DocDef, args DocArgs) (*jv.Object, error)

Snapshot returns the current value of a document, or nil when absent.

func (*Session) SnapshotAsOf

func (s *Session) SnapshotAsOf(def *DocDef, args DocArgs, at ID) (any, error)

SnapshotAsOf is Session.snapshotAsOf: the value of a conversation document as of the commit of entry at, which must be visible from the conversation, or nil when the document did not exist then.

func (*Session) StoreHolds

func (s *Session) StoreHolds() error

StoreHolds is Session #storeHolds over every hold: it stores the held changes of every held document in one Storage transaction, through the writer, on the line. It is a barrier: the holds are selected once every commit admitted before is published, and the call returns a *NeedPublication while it waits for that and for its own part, which runs the job again. Memory already has the changes, so only the Storage listeners see it, published as the writer publishes it. A failure fails the Session, as every Storage failure does.

func (*Session) SubscribeClose

func (s *Session) SubscribeClose(fn func())

SubscribeClose registers a listener that runs when Close begins.

func (*Session) SubscribeCommits

func (s *Session) SubscribeCommits(fn func(*Publication))

SubscribeCommits registers a synchronous post-adoption listener. It must not throw, block or call Session operations.

func (*Session) TailsSize

func (s *Session) TailsSize() int

TailsSize is how many conversations have their newest entry kept (session.ts documentCacheSizes.tails).

func (*Session) TakeDropped

func (s *Session) TakeDropped() []DroppedDoc

TakeDropped is the record IDs of the incarnations that left the cache since the last call, while TrackDropped is set: the host's copy of a document's value is only as long-lived as the core's cached document (session.ts keeps none of an evicted one).

func (*Session) TakeTicks

func (s *Session) TakeTicks() int

TakeTicks returns and clears the Change of the last transaction callback that succeeded on the line: the ticks of Pi's change callback for its Transaction method awaits and Scheduler wrapper (hopcost), -1 when none ran.

func (*Session) TaskDocuments

func (s *Session) TaskDocuments(taskID ID) (records []*jv.Object, known bool)

TaskDocuments is the current documents of a live task the Session created, ascending by ID; known is false for any other task, whose documents are scanned.

func (*Session) TaskDocumentsSize

func (s *Session) TaskDocumentsSize() int

TaskDocumentsSize is how many live tasks have their documents indexed (session.ts documentCacheSizes.taskDocuments).

func (*Session) Touch

func (s *Session) Touch(key string) error

Touch is session.ts touch: nil when key has no unpublished writer, else a *NeedPublication for its gate (for AllKeys, while anything is unpublished). A job's every read touches its key first, so it never observes state an earlier job admitted and the writer has not published.

func (*Session) TouchEntries

func (s *Session) TouchEntries(conversationID ID) error

TouchEntries is the wait of a read of a conversation's entries (keys.ts #afterEntries) for a host that serves it from its own mirror.

func (*Session) TouchRead

func (s *Session) TouchRead(key string) error

TouchRead is the wait of a read through the Session's gated Storage (keys.ts #after) for a host that serves the read from its own mirror: nil when key has no unpublished writer, else the *NeedPublication that runs the job again after.

func (*Session) UnloadDocuments

func (s *Session) UnloadDocuments() error

UnloadDocuments drops every cached document, held changes stored first; later access loads from the store. A *NeedPublication error means the held changes (or the commits before them) are not published yet: nothing was dropped, and the call is made again once they are.

func (*Session) WriteTasks

func (s *Session) WriteTasks(records []*jv.Object) error

WriteTasks writes complete task records straight to the Storage, through the writer, with nothing published and the records not stamped (session.ts writeAtClose). It runs on the line, after every commit admitted before is published; it writes nothing once the Session failed, and returns a *NeedPublication while its writes are stored, which runs the job again; a failing Storage fails the Session.

func (*Session) Writer

func (s *Session) Writer() *Writer

Writer is the Session's writer, whose parts the line admits (Loop).

type Snapshot

type Snapshot interface {
	Task(name string) *TaskImpl
}

Snapshot is a registry snapshot: the task definitions of one phase.

type Store

type Store interface {
	Conversation(id ID) (*jv.Object, error)
	ScanConversations(q ConversationQuery, limit int, after ID) (Page, error)
	// Entry returns the entry with its commit sequence.
	Entry(id ID) (*jv.Object, Seq, error)
	// EntryIn returns the entry when it is visible from the conversation.
	EntryIn(conversationID, id ID) (*jv.Object, Seq, error)
	// LatestHeadMarker returns the newest head-marker entry visible from the
	// conversation at or before atOrBefore (0: no bound), through fork ancestry.
	LatestHeadMarker(conversationID, atOrBefore ID) (*jv.Object, error)
	ScanEntries(q EntryQuery, limit int, after ID) (Page, error)
	Task(id ID) (*jv.Object, error)
	ScanTasks(q TaskQuery, limit int, after ID) (Page, error)
	Submission(id ID) (*jv.Object, error)
	ScanSubmissions(q SubmissionQuery, limit int, after ID) (Page, error)
	SubmissionByRequest(conversationID ID, requestID string) (*jv.Object, error)
	FindDocument(a Address, at Point) (*jv.Object, error)
	Document(id ID, at Point) (*StoredDoc, error)
	// ScanDocuments returns the documents of a scope alive at the point, optionally of one kind, ascending by ID.
	ScanDocuments(scope Scope, at Point, kind string, limit int, after ID) (Page, error)
	// Commit applies the writes as one atomic commit and returns its sequence;
	// nextID is the Session's next unminted ID, which the store keeps as
	// max(its stored next ID, nextID, the largest written ID + 1). A *RefusedError is a batch Durable's own checks refused; any other
	// error fails the Session.
	Commit(writes []Write, nextID ID) (Seq, error)
}

Store is the committed state a Session reads and the place it commits to.

Every read returns a nil record for an absent one. A read the loaded state cannot answer returns a *NeedRead. Commit never returns NeedRead. The Session reads through gatedStore, which touches the key of each read first (gate.go).

type StoredDoc

type StoredDoc struct {
	Record          *jv.Object
	Version         int
	Value           *jv.Object
	DeltasSinceBase int
}

StoredDoc is a document's materialized content at a point.

type SubmissionQuery

type SubmissionQuery struct {
	ConversationID ID
	Status         string
	Descending     bool
}

SubmissionQuery filters a submission scan.

type TaskDef

type TaskDef struct {
	Name    string
	Version int
	// Initial returns the first checkpoint for a new task's input.
	Initial func(input any) any
}

TaskDef is the part of a task definition the Session layer needs to create a task: its kind, its version and its first checkpoint. Phases, abort and migration belong to the scheduler.

type TaskImpl

type TaskImpl struct {
	Def TaskDef
	// Extension is the name of the extension that installed the definition; empty for a built-in task.
	Extension string
	// Migrate converts a record stored by an older version; nil when the
	// definition has none. It runs at reservation.
	Migrate func(input, checkpoint any, fromVersion int) (newInput, newCheckpoint any, err error)
	// MigrateAsync is Migrate for a definition whose migrate() is host code: it starts the migration and calls done once,
	// later, with its result. The scheduler asks again after done (it kicks), so a reservation that needed a migration
	// is retried with the answer in hand and never blocks the Session line on the host.
	MigrateAsync func(input, checkpoint any, fromVersion int, done func(newInput, newCheckpoint any, err error))
	// Phase runs the handler for the checkpoint's phase of a running task and
	// calls done once, with the handler's error or nil. The handler drives the
	// runtime and ends by committing durable progress.
	Phase func(rt *Runtime, task *jv.Object, done func(error))
	// Abort runs in a fresh invocation after an abort mark and must commit a
	// terminal outcome.
	Abort func(rt *Runtime, task *jv.Object, done func(error))
	// AbortReturnHops is the hops between the end of Abort's final commit job and `#runAbort`'s step enqueue when the
	// handler is an async function of Pi that awaits that commit: the commit's `#gated` await, the handler's own await and
	// its async return, then runAbort's await (scheduler.ts :1399-1411). A handler that runs in the host spends these hops
	// itself and leaves it zero.
	AbortReturnHops int
}

TaskImpl is an executable task definition registered in the registry.

type TaskInspection

type TaskInspection struct {
	Record *jv.Object
	// Kind is "running", "pending", "waiting", "sleeping", "completing" or "blocked".
	Kind     string
	Until    float64 // sleeping
	Migrates bool    // pending
	On       []ID    // waiting
	Reason   string  // blocked: missing_task, task_too_old, or migration_failed
	Err      error   // blocked with migration_failed: why, when known
}

TaskInspection is one live task with the state the scheduler derives for it (types.ts TaskInspection).

type TaskOptions

type TaskOptions struct {
	// OwnerTask is the owning task of a child task; zero for a conversation-owned task.
	OwnerTask ID
	// ConversationID defaults to the owner task's conversation or the transaction's bound conversation.
	ConversationID ID
	Background     bool
	// AbandonOnRestart marks a task its creator awaits only in memory: a later Harness abort-marks it with reason restart.
	AbandonOnRestart bool
	// Trace is the carrier the task's phase spans start under (types.ts TaskOptions.trace); nil inherits the creating
	// transaction's carrier (TxScope.Trace), and NoTrace stores none (`trace: "root"`).
	Trace   any
	NoTrace bool
	// Links are the immutable creation-time links of the task's first invocation (types.ts TaskOptions.links).
	Links []any
	// Submissions are the input submissions of a run (transaction.ts TaskCreationOptions.submissionIds): the first one's
	// carrier is the task's trace, and the carriers of the others are its links.
	Submissions []ID
	// Owned says the input and the initial checkpoint belong to the transaction (a host's operation parsed them for it and nothing
	// else holds them), so the record keeps them instead of copies: a 20,000-task commit would hold two more objects per task.
	Owned bool
}

TaskOptions are the creation options of a task (types.ts TaskOptions).

type TaskQuery

type TaskQuery struct {
	ConversationID ID
	Kind           string
	Status         string
	AbortRequested *bool
	Background     *bool
	Descending     bool
}

TaskQuery filters a task scan. Zero values leave a field unconstrained.

type Telemetry

type Telemetry interface {
	// StartPhase starts the invocation's span and calls p.Started with it.
	StartPhase(p *PhaseInfo)
	// EndPhase ends the phase span with its outcome. next is the checkpoint's phase of PhaseNext (`next=<phase>`); a
	// PhaseFaulted outcome names how the task ended (faulted, failed or orphaned: the status task_<ended>) and carries the
	// diagnostic message in full.
	EndPhase(span uint32, outcome PhaseOutcome, next, ended, message string)
	// Checkpoint is the `pi.durable.checkpoint` event of a commit that moved the running checkpoint to phase.
	Checkpoint(span uint32, phase string)
	// ToolCall sets the called tool's name and call ID on the span (tool.ts readCall).
	ToolCall(span uint32, name, callID string)
	// Replay is the `pi.durable.replay` event of a nested tool call answered from its stored result.
	Replay(span uint32, name string)
	// Active counts a task of kind in or out of `pi.durable.tasks.active`.
	Active(kind string, delta int)
}

Telemetry is the host's side of Pi's telemetry: the spans and metrics of `DURABLE_TELEMETRY_SCHEMA`. A scheduler without one records nothing (HarnessOptions.telemetry omitted). The core never holds a span: it names them by the handle the host answered StartPhase with, or was given by the call whose Context carries it (TxScope.Span).

type Tx

type Tx struct {
	// contains filtered or unexported fields
}

Tx stages one atomic commit. Every method must run inside the callback that received it; after the callback ends the transaction is sealed.

func (*Tx) AppendEntry

func (tx *Tx) AppendEntry(conversationID ID, draft *jv.Object) (*jv.Object, error)

AppendEntry stages a new entry. The draft's head may be the string "self".

func (*Tx) Await

func (tx *Tx) Await(n int)

Await charges the ticks of a callback's own `await` of Pi code that is not a Transaction method (hopcost: an async function without awaits of its own settles at once and its caller resumes one tick later).

func (*Tx) Conversation

func (tx *Tx) Conversation(id ID) (*jv.Object, error)

Conversation returns a committed conversation record, or nil.

func (*Tx) ConversationCreated

func (tx *Tx) ConversationCreated(id ID) bool

ConversationCreated reports whether this transaction created the conversation (transaction.ts #createdConversationIds).

func (*Tx) CreateConversation

func (tx *Tx) CreateConversation(own Ownership) (*jv.Object, error)

CreateConversation stages a new conversation.

func (*Tx) CreateRootConversation

func (tx *Tx) CreateRootConversation() (*jv.Object, error)

CreateRootConversation stages the root conversation under its reserved ID.

func (*Tx) CreateSubmission

func (tx *Tx) CreateSubmission(create *jv.Object) (*jv.Object, error)

CreateSubmission stages a submission; its record is {...create, id}.

func (*Tx) CreateTask

func (tx *Tx) CreateTask(def *TaskDef, input any, opts TaskOptions) (ID, error)

CreateTask stages a pending task and returns its ID.

func (*Tx) DeferWithin

func (tx *Tx) DeferWithin(ms float64)

DeferWithin marks the commit deferrable (durable CommitPersistence) with a window of ms milliseconds, negative for the Session's default: a transaction of a task invocation takes its scope from the task (Runtime.BeginHost).

func (*Tx) Doc

func (tx *Tx) Doc(def *DocDef, args DocArgs) (*delta.Obj, error)

Doc returns the draft of a document, creating the document when absent. A second call for the same address in one transaction returns the same draft.

func (*Tx) DocEntry

func (tx *Tx) DocEntry(def *DocDef, args DocArgs) int

DocEntry is the position of the document's latest entry in the transaction's documents: a host names the incarnation a draft belongs to by it, since a retired incarnation's draft outlives the new incarnation at its address.

func (*Tx) DocRecordID

func (tx *Tx) DocRecordID(def *DocDef, args DocArgs) ID

DocRecordID is the ID of the stored record a document's latest entry loaded, or 0 for a document this transaction creates: a host matches the Storage writes of a commit to the revisions its drafts prepared by it.

func (*Tx) Entry

func (tx *Tx) Entry(id ID) (*jv.Object, error)

Entry returns a committed entry, or nil.

func (*Tx) ForkConversation

func (tx *Tx) ForkConversation(parent, at ID, own Ownership) (*jv.Object, error)

ForkConversation stages a conversation that inherits the parent's history through the entry at.

func (*Tx) HasTableWrite

func (tx *Tx) HasTableWrite() bool

HasTableWrite reports whether a table write was staged, after which table reads (and a submission's admission) fail with ReadAfterWrite.

func (*Tx) HostDoc

func (tx *Tx) HostDoc(def *DocDef, args DocArgs, have DocRevision, holds bool) (HostDocValue, error)

HostDoc is Doc for a host that keeps its own draft (ABI section 8, `doc`): it acquires the document and returns the value the draft starts from. A host that keeps the values it read passes the revision it holds (the zero revision when it holds none): a document the transaction has not edited then comes with its revision, and with only the operations adopted since the held one when the Session still has them. The host's operations come back through SetDocOps.

func (*Tx) LatestEntryID

func (tx *Tx) LatestEntryID(conversationID ID) (ID, error)

LatestEntryID returns the newest entry ID visible from a conversation, 0 for none, known from the Session's commits when it can be (transaction.ts latestEntryId).

func (*Tx) LatestHeadMarker

func (tx *Tx) LatestHeadMarker(conversationID ID) (*jv.Object, error)

LatestHeadMarker returns the newest head-marker entry of a conversation, or nil.

func (*Tx) LatestHeadMarkerAt

func (tx *Tx) LatestHeadMarkerAt(conversationID, atOrBefore ID) (*jv.Object, error)

LatestHeadMarkerAt returns the newest head-marker entry of a conversation at or before atOrBefore (0: any), or nil.

func (*Tx) PlaceSubmission

func (tx *Tx) PlaceSubmission(id, entry ID) error

PlaceSubmission stages the placement of a queued submission at an entry.

func (*Tx) RetireDoc

func (tx *Tx) RetireDoc(def *DocDef, args DocArgs) error

RetireDoc retires a document at commit; an absent document is a no-op.

func (*Tx) ScanConversations

func (tx *Tx) ScanConversations(q ConversationQuery, limit int, after ID) (Page, error)

ScanConversations scans committed conversations.

func (*Tx) ScanEntries

func (tx *Tx) ScanEntries(q EntryQuery, limit int, after ID) (Page, error)

ScanEntries scans committed entries visible from a conversation.

func (*Tx) ScanTasks

func (tx *Tx) ScanTasks(q TaskQuery, limit int, after ID) (Page, error)

ScanTasks scans committed tasks.

func (*Tx) SetDocOps

func (tx *Tx) SetDocOps(def *DocDef, args DocArgs, entry int, ops []delta.Op) error

SetDocOps records the operations a host's tracker produced for the open draft of a document (ABI section 8, `doc.write`); settlement prepares the draft from them. A non-negative entry names the incarnation by DocEntry; a negative one the latest at the address.

func (*Tx) SetTask

func (tx *Tx) SetTask(value *jv.Object) error

SetTask stages a replacement of a task record, stamping start and end times. The staged record is a deep copy, as Pi's copyJson makes it, so the caller's value stays its own.

func (*Tx) SettleSubmission

func (tx *Tx) SettleSubmission(id ID, settlement *jv.Object) error

SettleSubmission stages a settlement: status "done" with answer, or "unanswered" with reason and optional detail.

func (*Tx) StagedConversations

func (tx *Tx) StagedConversations() []*jv.Object

StagedConversations returns the staged conversation records.

func (*Tx) StagedTasks

func (tx *Tx) StagedTasks() []*jv.Object

StagedTasks returns the staged task records in staging order.

func (*Tx) Submission

func (tx *Tx) Submission(id ID) (*jv.Object, error)

Submission returns a committed submission, or nil.

func (*Tx) SubmissionByRequest

func (tx *Tx) SubmissionByRequest(conversationID ID, requestID string) (*jv.Object, error)

SubmissionByRequest returns the submission with the request ID, or nil.

func (*Tx) Task

func (tx *Tx) Task(id ID) (*jv.Object, error)

Task returns the committed task record, or nil.

func (*Tx) Ticks

func (tx *Tx) Ticks() int

Ticks is Pi's await ticks the callback has spent so far (hopcost): where, in the job's duration, the code that runs now would run.

type TxScope

type TxScope struct {
	ConversationID ID
	TaskID         ID
	// Span is the host's handle of the span of the commit's Context (Context.telemetry): the commit's entry and settlement
	// events go to it. Zero is the NOOP span, which takes none (src/session/session.ts #publish).
	Span uint32
	// Trace is the carrier of that span (propagation.inject(span)): the trace of a task the commit creates without one.
	Trace any
	// Host marks a transaction whose callback runs in the host (ABI section 8): it cannot run again, so a Finish that returns a *NeedPublication
	// keeps the transaction's state and may be called again once the key is published.
	Host bool
	// Deferred marks the commit deferrable (durable CommitPersistence): see held.go. WithinMs is its window in milliseconds,
	// or negative for the Session's default (PersistWithin).
	Deferred bool
	WithinMs float64
}

TxScope binds a transaction to a conversation and a task: the default conversation of Tx.CreateTask and the task attributed to appended entries.

type Wake

type Wake struct {
	Active bool
	HasAt  bool
	At     float64
}

Wake is when the Session next needs a running process (scheduler.ts wake, Harness.wake): Active while some task can run now or is running, At for the earliest sleep not yet due.

type Write

type Write struct {
	Kind WriteKind
	// Record is the conversation, entry, task or submission record, or the
	// document record (DocumentCreate: no createdAt or retiredAt) of a create or copy.
	Record *jv.Object
	// ID is the document of a change or retire.
	ID      ID
	Version int
	// Base is true when the content is a complete value (create, or a change that stores a base).
	Base  bool
	Value *jv.Object // Base content
	Ops   []delta.Op // delta content
	// Source is the copied document of a WriteDocCopy.
	Source DocCopySource
}

Write is one storage write of a commit.

type WriteKind

type WriteKind uint8

WriteKind is the kind of a StorageWrite.

const (
	WriteConversation WriteKind = iota + 1
	WriteEntry
	WriteTask
	WriteSubmission
	WriteDocCreate
	WriteDocCopy
	WriteDocChange
	WriteDocRetire
)

The StorageWrite kinds, as pi-durable's StorageWrite union.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer is the writer of one Session.

func (*Writer) Admit

func (w *Writer) Admit(p *Part)

Admit registers a part's keys, queues it, and sends it at once unless a call is in flight.

func (*Writer) Busy

func (w *Writer) Busy() bool

Busy reports whether a part is queued or a call is in flight.

func (*Writer) Drained

func (w *Writer) Drained() *Gate

Drained is the gate that opens once every part admitted so far is published or never will be, or nil when there is none.

func (*Writer) Gate

func (w *Writer) Gate(key string) *Gate

Gate is the gate of the newest unpublished writer of key, or nil when it has none.

func (*Writer) Unpublished

func (w *Writer) Unpublished() int

Unpublished is the number of keys with an unpublished writer.

Directories

Path Synopsis
cmd
tgprobe command
Command tgprobe links the session layer's packages so the TinyGo build can prove they compile without reflection.
Command tgprobe links the session layer's packages so the TinyGo build can prove they compile without reflection.
Package hopcost derives, in microtask ticks, how long Pi's Storage adapters take, so the core can park a line job on a hops chain as long as Pi's job (ABI.md section 5.3).
Package hopcost derives, in microtask ticks, how long Pi's Storage adapters take, so the core can park a line job on a hops chain as long as Pi's job (ABI.md section 5.3).
Package sessiontest provides an in-memory session.Store that keeps all committed state, as pi-durable's MemoryStorage does.
Package sessiontest provides an in-memory session.Store that keeps all committed state, as pi-durable's MemoryStorage does.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL