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
- Variables
- func AppendKey(id ID) string
- func ConversationKey(id ID) string
- func DocAddress(def *DocDef, args DocArgs) string
- func DocumentKey(addressID string) string
- func EntryKey(id ID) string
- func IncarnationKey(id ID) string
- func IsNeedPublication(err error) bool
- func NewStorageRequestError(msg string) error
- func NewTypeError(message string) error
- func OwnedKey(node string) string
- func ReadAfterWriteOf(operation string) error
- func RecordAddressID(rec *jv.Object) string
- func RequestKey(conversationID ID, requestID string) string
- func ScopeKey(scope Scope) string
- func SubmissionKey(id ID) string
- func TaskKey(id ID) string
- type Address
- type Cancel
- type Change
- type ChangeKind
- type CommitResult
- type ContextRange
- type ConversationQuery
- type DocArgs
- type DocCopySource
- type DocDef
- type DocRevision
- type DroppedDoc
- type Ended
- type EntryQuery
- type Env
- type FailedError
- type ForkPolicy
- type Gate
- type HeldAdopter
- type History
- type HostDocValue
- type HostJob
- type ID
- type IndexSizes
- type JobTicks
- type LineRunner
- type Loop
- func (l *Loop) Bind(s *Session)
- func (l *Loop) Busy() bool
- func (l *Loop) Consumed() int
- func (l *Loop) Defer(fn func())
- func (l *Loop) DeferDone(done func(error), err error, late bool)
- func (l *Loop) DeferResumer(r Resumer)
- func (l *Loop) Idle() bool
- func (l *Loop) Kick()
- func (l *Loop) LateNext()
- func (l *Loop) Line(run func() error, done func(error))
- func (l *Loop) LineAfterTail(run func() error, done func(error))
- func (l *Loop) LineBare(run func() error)
- func (l *Loop) LineHost(grant func() error, done func(error)) *HostJob
- func (l *Loop) LineHostLead(grant func() error, done func(error), lead int) *HostJob
- func (l *Loop) LineInternal(run func() error, done func(error))
- func (l *Loop) LineMaintain(run func() error)
- func (l *Loop) LineRunnerAfterTail(r LineRunner)
- func (l *Loop) Macrotask(r Resumer)
- func (l *Loop) NextTick(fn func())
- func (l *Loop) NextTickResumer(r Resumer)
- func (l *Loop) OnComplete(fn func())
- func (l *Loop) OnJobEnd(end Resumer)
- func (l *Loop) Outstanding() int
- func (l *Loop) Parked() *NeedRead
- func (l *Loop) QueueAfterTail(j *job)
- func (l *Loop) QueueInternal(j *job)
- func (l *Loop) QueuedOrigins(f func(origin uint32))
- func (l *Loop) ReadLine(run func() error, done func(error))
- func (l *Loop) ReadLineLead(run func() error, done func(error), lead int)
- func (l *Loop) Restarted() bool
- func (l *Loop) Resume() error
- func (l *Loop) Run() error
- func (l *Loop) Until(d int) int
- func (l *Loop) Wait(n int, r Resumer)
- type NeedPublication
- type NeedRead
- type Ownership
- type Page
- type Part
- type PhaseInfo
- type PhaseOutcome
- type Point
- type Publication
- type ReadOnlyError
- type ReadRequest
- type RefusedError
- type ReportFrom
- type Resumer
- type Runtime
- func (r *Runtime) AbandonHost(tx *Tx, err error)
- func (r *Runtime) AbortOwned(id ID, then func(error))
- func (r *Runtime) BeginHost(span uint32, trace any) (tx *Tx, current *jv.Object, err error)
- func (r *Runtime) Commit(change func(tx *Tx, current *jv.Object) (next *jv.Object, err error), ...)
- func (r *Runtime) CommitDeferred(change func(tx *Tx, current *jv.Object) (next *jv.Object, err error), ...)
- func (r *Runtime) ConversationID() ID
- func (r *Runtime) Ended() bool
- func (r *Runtime) EndedError() error
- func (r *Runtime) Extension() string
- func (r *Runtime) FinishHost(tx *Tx, current, next *jv.Object) (*Publication, error)
- func (r *Runtime) GetTask(id ID, then func(*jv.Object, error))
- func (r *Runtime) MarkEndedByCrashes(message string)
- func (r *Runtime) Memo(name string, candidate any, then func(winner any, err error))
- func (r *Runtime) MemoGet(name string) (any, bool, error)
- func (r *Runtime) Now() (float64, error)
- func (r *Runtime) OnEnded(fn func())
- func (r *Runtime) Outcomes(ids []ID, then func([]*jv.Object, error))
- func (r *Runtime) OwnedTasks(then func([]*jv.Object, error))
- func (r *Runtime) Read(job func() error, then func(error))
- func (r *Runtime) Replay(name string)
- func (r *Runtime) Report(err error, from ...ReportFrom) error
- func (r *Runtime) ReportEnded()
- func (r *Runtime) Signal() *Cancel
- func (r *Runtime) SleepUntil(until float64, checkpoint any, then func(error))
- func (r *Runtime) Snapshot() Snapshot
- func (r *Runtime) Span() uint32
- func (r *Runtime) TaskID() ID
- func (r *Runtime) ToolCall(name, callID string)
- func (r *Runtime) WaitForTask(id ID, then func(rec *jv.Object, err error, waited bool))
- type Scheduler
- func (s *Scheduler) Abort(id ID, keepRestart bool, cancel *Cancel, then func(result string, err error))
- func (s *Scheduler) AbortConversation(conversationID ID, background bool, cancel *Cancel, then func(error))
- func (s *Scheduler) BlockedReason(rec *jv.Object) string
- func (s *Scheduler) Bound(taskID ID) *Cancel
- func (s *Scheduler) CloseWrites() []*jv.Object
- func (s *Scheduler) IdleState() (contexts, idleContexts, mismatches, fullChecks int)
- func (s *Scheduler) IndexSizes() IndexSizes
- func (s *Scheduler) Inspect(snapshot Snapshot) (scheduling string, tasks []TaskInspection, err error)
- func (s *Scheduler) IsIdle(conversationID ID) bool
- func (s *Scheduler) Join(then func())
- func (s *Scheduler) KeepContext(conversationID ID, r ContextRange, invocationEnded bool)
- func (s *Scheduler) KeptContext(conversationID ID) (ContextRange, bool)
- func (s *Scheduler) KeptEntry(conversationID, id ID) bool
- func (s *Scheduler) Open(done func(error))
- func (s *Scheduler) RegistryChanged()
- func (s *Scheduler) ReportSpan() uint32
- func (s *Scheduler) Resume()
- func (s *Scheduler) Seal()
- func (s *Scheduler) SetOnWake(fn func(w Wake))
- func (s *Scheduler) SpanOf(id ID) uint32
- func (s *Scheduler) WaitForIdle(conversationID ID, cancel *Cancel, then func(error))
- func (s *Scheduler) WaitForTask(id ID, cancel *Cancel, then func(rec *jv.Object, err error))
- func (s *Scheduler) WaitForTaskFound(id ID, cancel *Cancel, then func(rec *jv.Object, err error, waited bool))
- func (s *Scheduler) Wake() Wake
- func (s *Scheduler) WriteBack(records []*jv.Object) error
- type Scope
- type ScopeKind
- type Seq
- type Session
- func (s *Session) Abandon(tx *Tx, err error)
- func (s *Session) Admit() error
- func (s *Session) Begin(scope TxScope) (*Tx, error)
- func (s *Session) ChargeRead(n int)
- func (s *Session) Close()
- func (s *Session) ColdEntryAwaits() int
- func (s *Session) ColdMarkerAwaits() int
- func (s *Session) Commit(change func(tx *Tx) error, scope TxScope) (*Publication, error)
- func (s *Session) DocumentCacheSizes() (cached, idle int)
- func (s *Session) DocumentsAttached() int
- func (s *Session) Fail(err error)
- func (s *Session) Failure() error
- func (s *Session) Finish(tx *Tx) (*Publication, error)
- func (s *Session) HasUnrevealedLoads() bool
- func (s *Session) HeldDocuments() int
- func (s *Session) HoldsOutcome() (error, bool)
- func (s *Session) InJob() bool
- func (s *Session) KeepRecord(r hopcost.Record, id ID, rec *jv.Object)
- func (s *Session) KnownLatestEntryID(conversationID ID) (id ID, known bool)
- func (s *Session) LatestEntryID(conversationID ID) (id ID, ticks int, err error)
- func (s *Session) LatestHeadMarker(conversationID, atOrBefore ID) (marker *jv.Object, ticks int, err error)
- func (s *Session) Loaded(def *DocDef, args DocArgs) bool
- func (s *Session) LookupHeadMarker(conversationID, atOrBefore ID) (marker *jv.Object, known bool)
- func (s *Session) LookupLatestEntryID(conversationID ID) (id ID, known bool)
- func (s *Session) NextID() ID
- func (s *Session) NoteHeadMarker(conversationID, atOrBefore ID, marker *jv.Object)
- func (s *Session) NoteLatestEntryID(conversationID, id ID)
- func (s *Session) OnFailed(f func(error)) (remove func())
- func (s *Session) PeekTicks() int
- func (s *Session) PinDocument(def *DocDef, args DocArgs) (release func())
- func (s *Session) RecordAnswer(r hopcost.Record, id ID) hopcost.Cache
- func (s *Session) RunCommit(change func(tx *Tx) error, scope TxScope) (*Publication, error)
- func (s *Session) Seal()
- func (s *Session) SetHopProfile(p hopcost.Profile)
- func (s *Session) SettleCached() int
- func (s *Session) SettleReads() int
- func (s *Session) Snapshot(def *DocDef, args DocArgs) (*jv.Object, error)
- func (s *Session) SnapshotAsOf(def *DocDef, args DocArgs, at ID) (any, error)
- func (s *Session) StoreHolds() error
- func (s *Session) SubscribeClose(fn func())
- func (s *Session) SubscribeCommits(fn func(*Publication))
- func (s *Session) TailsSize() int
- func (s *Session) TakeDropped() []DroppedDoc
- func (s *Session) TakeTicks() int
- func (s *Session) TaskDocuments(taskID ID) (records []*jv.Object, known bool)
- func (s *Session) TaskDocumentsSize() int
- func (s *Session) Touch(key string) error
- func (s *Session) TouchEntries(conversationID ID) error
- func (s *Session) TouchRead(key string) error
- func (s *Session) UnloadDocuments() error
- func (s *Session) WriteTasks(records []*jv.Object) error
- func (s *Session) Writer() *Writer
- type Snapshot
- type Store
- type StoredDoc
- type SubmissionQuery
- type TaskDef
- type TaskImpl
- type TaskInspection
- type TaskOptions
- type TaskQuery
- type Telemetry
- type Tx
- func (tx *Tx) AppendEntry(conversationID ID, draft *jv.Object) (*jv.Object, error)
- func (tx *Tx) Await(n int)
- func (tx *Tx) Conversation(id ID) (*jv.Object, error)
- func (tx *Tx) ConversationCreated(id ID) bool
- func (tx *Tx) CreateConversation(own Ownership) (*jv.Object, error)
- func (tx *Tx) CreateRootConversation() (*jv.Object, error)
- func (tx *Tx) CreateSubmission(create *jv.Object) (*jv.Object, error)
- func (tx *Tx) CreateTask(def *TaskDef, input any, opts TaskOptions) (ID, error)
- func (tx *Tx) DeferWithin(ms float64)
- func (tx *Tx) Doc(def *DocDef, args DocArgs) (*delta.Obj, error)
- func (tx *Tx) DocEntry(def *DocDef, args DocArgs) int
- func (tx *Tx) DocRecordID(def *DocDef, args DocArgs) ID
- func (tx *Tx) Entry(id ID) (*jv.Object, error)
- func (tx *Tx) ForkConversation(parent, at ID, own Ownership) (*jv.Object, error)
- func (tx *Tx) HasTableWrite() bool
- func (tx *Tx) HostDoc(def *DocDef, args DocArgs, have DocRevision, holds bool) (HostDocValue, error)
- func (tx *Tx) LatestEntryID(conversationID ID) (ID, error)
- func (tx *Tx) LatestHeadMarker(conversationID ID) (*jv.Object, error)
- func (tx *Tx) LatestHeadMarkerAt(conversationID, atOrBefore ID) (*jv.Object, error)
- func (tx *Tx) PlaceSubmission(id, entry ID) error
- func (tx *Tx) RetireDoc(def *DocDef, args DocArgs) error
- func (tx *Tx) ScanConversations(q ConversationQuery, limit int, after ID) (Page, error)
- func (tx *Tx) ScanEntries(q EntryQuery, limit int, after ID) (Page, error)
- func (tx *Tx) ScanTasks(q TaskQuery, limit int, after ID) (Page, error)
- func (tx *Tx) SetDocOps(def *DocDef, args DocArgs, entry int, ops []delta.Op) error
- func (tx *Tx) SetTask(value *jv.Object) error
- func (tx *Tx) SettleSubmission(id ID, settlement *jv.Object) error
- func (tx *Tx) StagedConversations() []*jv.Object
- func (tx *Tx) StagedTasks() []*jv.Object
- func (tx *Tx) Submission(id ID) (*jv.Object, error)
- func (tx *Tx) SubmissionByRequest(conversationID ID, requestID string) (*jv.Object, error)
- func (tx *Tx) Task(id ID) (*jv.Object, error)
- func (tx *Tx) Ticks() int
- type TxScope
- type Wake
- type Write
- type WriteKind
- type Writer
Constants ¶
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 = "*" )
const ( StatusPending = "pending" StatusRunning = "running" StatusWaiting = "waiting" StatusSleeping = "sleeping" StatusCompleting = "completing" StatusTerminal = "terminal" )
TaskStatus values of a task's state.
const DefaultDocumentRetentionMs = 600_000
DefaultDocumentRetentionMs is Pi's default document retention: ten minutes, as for kept contexts.
const DefaultPersistWithinMs = 1_000
DefaultPersistWithinMs is the default window of a deferred commit, settings.progress.persistWithinMs (session.ts DEFAULT_PERSIST_WITHIN_MS).
Variables ¶
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.
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.
var Current = Point{Current: true}
Current is the point of the newest incarnation. Read-only.
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.
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 ¶
AppendKey is the newest entries of a conversation: appended blind, read by scans, the newest entry and head markers.
func DocAddress ¶
DocAddress returns the address a definition and arguments name; hosts key their per-transaction state by it.
func DocumentKey ¶
DocumentKey is a document address (addressID): its current incarnation, value and held changes.
func IncarnationKey ¶
IncarnationKey is a document incarnation, for reads by its ID.
func IsNeedPublication ¶
IsNeedPublication reports whether err is, or wraps, a *NeedPublication.
func NewStorageRequestError ¶
NewStorageRequestError is Pi's `new StorageRequestError(message)`.
func NewTypeError ¶
NewTypeError is a TypeError Pi throws with message; it matches ErrTypeError with errors.Is.
func OwnedKey ¶
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 ¶
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 ¶
RecordAddressID is the address ID of a document record: the address of every incarnation of one document.
func RequestKey ¶
RequestKey is the submission a conversation's request ID names.
Types ¶
type Address ¶
Address names a document: its kind, scope and, for a family member, its key.
func DocumentAddress ¶
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 ¶
AbortWith marks the signal aborted with reason (AbortController.abort(reason)); a signal keeps its first reason.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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
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) Wait ¶
func (g *Gate) Wait(fn func())
Wait calls fn once the gate is open, at once when it is.
func (*Gate) WaitResumer ¶
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 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.
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.
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 ¶
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 ¶
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 ¶
Busy reports whether a line job is queued, running, held or waiting for the host or for a publication.
func (*Loop) Consumed ¶
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 ¶
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 ¶
DeferResumer queues r.Resume as a microtask.
func (*Loop) Idle ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Outstanding is the number of jobs that started and have no outcome delivered yet (session.ts lineSizes.outstanding).
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Resume re-runs the parked job and continues; the host must have answered its reads.
func (*Loop) Run ¶
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 ¶
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).
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 ¶
IsNeedRead reports whether err is, or wraps, a *NeedRead.
type Ownership ¶
type Ownership struct {
// Task is the owning task; zero means ownerless.
Task ID
}
Ownership is how a created conversation is attributed.
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 ¶
Done reports whether the part's outcome settled: it was published, or never will be.
func (*Part) Err ¶
Err is the error the part's outcome settled with, nil when it was published and no failure rejected it after.
func (*Part) OnOutcome ¶
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 ¶
Answered is Started for the host's answer to the span hook, `{span, carrier?}`: a failed hook starts the phase without a span.
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 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 ¶
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 ¶
AbandonHost ends the host transaction of BeginHost without a commit.
func (*Runtime) AbortOwned ¶
AbortOwned aborts a task this task owns and calls then once it is terminal (scheduler.ts abortOwned).
func (*Runtime) BeginHost ¶
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 ¶
ConversationID is the task's conversation.
func (*Runtime) EndedError ¶
EndedError is the error of an operation of an ended invocation.
func (*Runtime) Extension ¶
Extension is the extension that installed the definition this invocation runs, as of its reservation; empty for a built-in task.
func (*Runtime) FinishHost ¶
FinishHost commits the host transaction of BeginHost: next, when not nil, is the state the task commits for itself.
func (*Runtime) MarkEndedByCrashes ¶
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 ¶
Memo stores candidate unless a memo of that name exists and returns the durable winner.
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) OwnedTasks ¶
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 ¶
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 ¶
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 ¶
Signal is aborted when the run is signalled by AbortTask, the Harness closes or the invocation ends.
func (*Runtime) SleepUntil ¶
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) Span ¶
Span is the handle of the span of the phase the runtime's invocation is running, 0 when it is in none.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
SetOnWake makes the scheduler tell fn each change of Wake instead of arming a timer for sleeping tasks.
func (*Scheduler) SpanOf ¶
SpanOf is the handle of the span of the phase task's invocation is running, 0 when it is in none.
func (*Scheduler) WaitForIdle ¶
WaitForIdle calls then when the conversation (0: every root) has no live non-background task or queued input below it.
func (*Scheduler) WaitForTask ¶
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 ¶
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.
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 ¶
New returns a Session over a store. nextID is the next unminted record ID and now the Harness clock.
func (*Session) Abandon ¶
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 ¶
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 ¶
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 ¶
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 ¶
ColdEntryAwaits is hopcost.ColdEntryAwaits of this Session.
func (*Session) ColdMarkerAwaits ¶
ColdMarkerAwaits is hopcost.ColdMarkerAwaits of this Session.
func (*Session) Commit ¶
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 ¶
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 ¶
DocumentsAttached is the number of incarnations an observer pins (session.ts documentCacheSizes.attached).
func (*Session) Fail ¶
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) 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 ¶
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 ¶
HeldDocuments is the number of incarnations with held changes (session.ts documentCacheSizes.held).
func (*Session) HoldsOutcome ¶
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) KeepRecord ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) NoteHeadMarker ¶
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 ¶
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 ¶
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 ¶
PeekTicks is the Change of the transaction callback that just succeeded, without clearing it: -1 when none ran.
func (*Session) PinDocument ¶
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 ¶
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 ¶
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 ¶
SetHopProfile names the Storage profile whose await ticks transactions are charged (open.storageProfile).
func (*Session) SettleCached ¶
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 ¶
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) SnapshotAsOf ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
TaskDocumentsSize is how many live tasks have their documents indexed (session.ts documentCacheSizes.taskDocuments).
func (*Session) Touch ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
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 SubmissionQuery ¶
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 ¶
AppendEntry stages a new entry. The draft's head may be the string "self".
func (*Tx) Await ¶
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 ¶
Conversation returns a committed conversation record, or nil.
func (*Tx) ConversationCreated ¶
ConversationCreated reports whether this transaction created the conversation (transaction.ts #createdConversationIds).
func (*Tx) CreateConversation ¶
CreateConversation stages a new conversation.
func (*Tx) CreateRootConversation ¶
CreateRootConversation stages the root conversation under its reserved ID.
func (*Tx) CreateSubmission ¶
CreateSubmission stages a submission; its record is {...create, id}.
func (*Tx) CreateTask ¶
CreateTask stages a pending task and returns its ID.
func (*Tx) DeferWithin ¶
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 ¶
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 ¶
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 ¶
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) ForkConversation ¶
ForkConversation stages a conversation that inherits the parent's history through the entry at.
func (*Tx) HasTableWrite ¶
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 ¶
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 ¶
LatestHeadMarker returns the newest head-marker entry of a conversation, or nil.
func (*Tx) LatestHeadMarkerAt ¶
LatestHeadMarkerAt returns the newest head-marker entry of a conversation at or before atOrBefore (0: any), or nil.
func (*Tx) PlaceSubmission ¶
PlaceSubmission stages the placement of a queued submission at an entry.
func (*Tx) ScanConversations ¶
ScanConversations scans committed conversations.
func (*Tx) ScanEntries ¶
ScanEntries scans committed entries visible from a conversation.
func (*Tx) SetDocOps ¶
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 ¶
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 ¶
SettleSubmission stages a settlement: status "done" with answer, or "unanswered" with reason and optional detail.
func (*Tx) StagedConversations ¶
StagedConversations returns the staged conversation records.
func (*Tx) StagedTasks ¶
StagedTasks returns the staged task records in staging order.
func (*Tx) Submission ¶
Submission returns a committed submission, or nil.
func (*Tx) SubmissionByRequest ¶
SubmissionByRequest returns the submission with the request ID, or nil.
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 ¶
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 Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer is the writer of one Session.
func (*Writer) Admit ¶
Admit registers a part's keys, queues it, and sends it at once unless a call is in flight.
func (*Writer) Drained ¶
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 ¶
Gate is the gate of the newest unpublished writer of key, or nil when it has none.
func (*Writer) Unpublished ¶
Unpublished is the number of keys with an unpublished writer.
Source Files
¶
- dochistory.go
- docs.go
- errorf.go
- gate.go
- growwrites.go
- held.go
- host.go
- index_sizes.go
- keys.go
- loop.go
- recordcache.go
- records.go
- retention.go
- runtime.go
- runtime_interrupted.go
- sched.go
- sched_context.go
- sched_graph.go
- sched_index.go
- sched_inspect.go
- sched_obs.go
- sched_region.go
- sched_run.go
- sched_types.go
- sched_wake.go
- session.go
- store.go
- tails.go
- taskdocs.go
- telemetry.go
- tx.go
- txdocs.go
- writer.go
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. |