Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
51 commits
Select commit Hold shift + click to select a range
7ead5a3
feat(actor): preempt CPU-bound Lua actors with a tick budget
wolfy-j Oct 2, 2026
464097d
fix(actor): keep preemption and execution limits across process upgrade
wolfy-j Oct 3, 2026
36e2282
fix(lua): bound module top-level code and exhausted-step work under t…
wolfy-j Oct 3, 2026
d83d14f
test(lua): close the step-limit lease test process once
wolfy-j Oct 3, 2026
385ceef
fix(lua): deliver queued messages when a step exhausts its tick budget
wolfy-j Oct 3, 2026
2f497b4
fix(lua): run dependency chunks inside the budgeted main task
wolfy-j Oct 3, 2026
7490d48
chore(deps): go-lua with second-pass preemption fixes
wolfy-j Oct 3, 2026
1364424
fix(lua): run pending initializers in SyncExecute
wolfy-j Oct 3, 2026
2ee79a0
fix(lua): keep declared imports ahead of library global exports
wolfy-j Oct 3, 2026
c699b39
fix(lua): fix import aliases when library initialization completes
wolfy-j Oct 3, 2026
f4e0727
fix(actor): Stop cancels stuck processes through their published inca…
wolfy-j Oct 3, 2026
3c871c7
chore(deps): go-lua with third-pass preemption fixes
wolfy-j Oct 3, 2026
f0cdb0a
fix(actor): close a process exactly once on failed upgrade and reject…
wolfy-j Oct 3, 2026
0b7a725
fix(actor): bind yield completions to the dispatching incarnation
wolfy-j Oct 3, 2026
a60d829
fix(lua): drop completed initializers and one-shot callbacks from the…
wolfy-j Oct 3, 2026
9ee145b
fix(lua): clear a closed task's result and resume buffers
wolfy-j Oct 3, 2026
2de740f
fix(process): clear overflow yields when a step output resets
wolfy-j Oct 3, 2026
510c05e
test: measure goroutine, heap and reference release across preemption…
wolfy-j Oct 3, 2026
8bbc4e0
style: order imports in close ownership test
wolfy-j Oct 3, 2026
6d89b7c
chore(deps): go-lua with leak and pooling fixes
wolfy-j Oct 3, 2026
d96d880
fix(actor): publish a processor as Ready only once it is initialized
wolfy-j Oct 3, 2026
a8d37c7
chore(deps): go-lua with bounded call stack frames
wolfy-j Oct 3, 2026
82715d3
test(actor): check stale completions without relying on pool reuse
wolfy-j Oct 3, 2026
59f617b
fix(lua): count steps for processes without a step limit
wolfy-j Oct 3, 2026
52f0ba5
refactor(lua,actor): share initializer list creation, make enablePree…
wolfy-j Oct 3, 2026
a232141
test(actor): wait on completion signals instead of polling and sleeping
wolfy-j Oct 3, 2026
de32f7d
test(lua): assert actor closes after the scheduler stops
wolfy-j Oct 3, 2026
da5068b
refactor(api): read process entry options with Bag.GetBag
wolfy-j Oct 3, 2026
568fb0e
test(lua): cover tick budget boundaries and exhaustion at task end
wolfy-j Oct 3, 2026
f6a6dbf
test(lua): cover initializer retry and method lookup after initializers
wolfy-j Oct 3, 2026
8148686
test(actor): cover InjectQueue.IsEmpty
wolfy-j Oct 3, 2026
126e1b1
fix(api): reject non-map meta.options and accept nil execution options
wolfy-j Oct 3, 2026
73302e6
fix(actor): start a new yield epoch when an upgrade replaces the process
wolfy-j Oct 3, 2026
3dfc124
fix(actor): make a wake's generation check atomic with its state tran…
wolfy-j Oct 3, 2026
0ff9f4c
fix(actor): wake a parked worker for newly runnable work
wolfy-j Oct 3, 2026
f0facbe
fix(actor): Stop waits for processors whose admission is in progress
wolfy-j Oct 3, 2026
6d13c23
test(actor): assert a stale yield completion leaves the next process …
wolfy-j Oct 3, 2026
c694a18
style(actor): order scheduler and worker fields for alignment
wolfy-j Oct 3, 2026
59857e8
test(actor): drain the global queue without a lint suppression
wolfy-j Oct 3, 2026
2559ecf
chore(deps): go-lua with quality-pass fixes
wolfy-j Oct 3, 2026
a1a72f3
test(actor): drain the global queue in the loop condition
wolfy-j Oct 3, 2026
0ce0f68
fix(actor): wake pooled processors on cancellation and signal drain o…
wolfy-j Oct 3, 2026
ba3e3f6
fix(api): align process entry options with v2
wolfy-j Oct 3, 2026
0a697bd
docs(engine): describe when chunk environments seal import aliases
wolfy-j Oct 3, 2026
e9d639b
test: seeded chaos tests for the actor scheduler and Lua actors
wolfy-j Oct 3, 2026
7639538
test: bound chaos message supply and satisfy lint
wolfy-j Oct 3, 2026
7718405
test: back off chaos message rate instead of capping supply
wolfy-j Oct 3, 2026
78ea9cf
chore(deps): go-lua with matcher limits and differential-test fixes
wolfy-j Oct 3, 2026
307dd77
chore(deps): go-lua with overflow-safe integer numeric for
wolfy-j Oct 3, 2026
cf9ad76
fix(actor): bound admission shutdown and preserve upgrade ownership
wolfy-j Oct 5, 2026
ebc4848
test(actor): assert rejected admission cleanup using canonical PID key
wolfy-j Oct 5, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions api/process/errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@ const (
var (
ErrMaxProcessesExceeded = apierror.New(LimitExceeded, "max processes limit exceeded").WithRetryable(apierror.False)

// ErrStepLimitExceeded fails a process that exceeds its max_steps option.
ErrStepLimitExceeded = apierror.New(apierror.RateLimited, "process step limit exceeded").WithRetryable(apierror.False)

ErrProcessClosed = apierror.New(InvalidState, "process closed").WithRetryable(apierror.False)

ErrProcessNotFound = apierror.New(NotFound, "process not found").WithRetryable(apierror.False)
Expand Down
25 changes: 25 additions & 0 deletions api/process/preempt.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
// SPDX-License-Identifier: MPL-2.0

package process

// Preemptible is an optional interface for processes that can suspend a
// running step at a safepoint once they have used up their execution slice.
// A scheduler calls EnablePreemption once, when it admits the process, and
// the opt-in persists for the process's lifetime. It then runs the process
// again after Step reports StepPreempted; a process that was never enabled
// runs each step to a blocking point or completion.
type Preemptible interface {
EnablePreemption()
}

// StepAccounted is an optional interface for processes that count their
// scheduler steps against a limit. A scheduler carries the count from a
// process to its upgrade replacement so the limit covers the whole lifetime
// of the actor rather than each incarnation.
type StepAccounted interface {
// StepsUsed returns the number of steps taken so far.
StepsUsed() uint64
// ResumeStepCount sets the number of steps already taken. It is called
// after Init, before the first Step.
ResumeStepCount(used uint64)
}
18 changes: 18 additions & 0 deletions api/process/process_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -511,3 +511,21 @@ func (g *stubPIDGenerator) Generate(host pid.HostID) pid.PID {
result.Host = host
return result
}

type overflowCmd struct{ id dispatcher.CommandID }

func (c overflowCmd) CmdID() dispatcher.CommandID { return c.id }

// A reset output keeps no command references in its overflow buffer.
func TestStepOutputResetClearsOverflowYields(t *testing.T) {
var out StepOutput
for i := 0; i < MaxYields+3; i++ {
out.Yield(overflowCmd{id: dispatcher.CommandID(i)}, uint64(i))
}
out.Reset()
for i, y := range out.ext[:cap(out.ext)] {
if y.Cmd != nil {
t.Fatalf("overflow yield %d still references its command", i)
}
}
}
65 changes: 51 additions & 14 deletions api/process/queue.go
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,12 @@ type EventQueue struct {
events []Event
drainBuf []Event
generation atomic.Uint64
mu sync.Mutex
closed atomic.Bool
// yieldEpoch identifies the code incarnation whose yield tags are valid.
// It changes when a process is replaced in place, so completions of the
// replaced code cannot resume the replacement.
yieldEpoch atomic.Uint64
mu sync.Mutex
closed atomic.Bool
}

// messageTopicState is the accounting identity for one bounded topic
Expand Down Expand Up @@ -120,6 +124,12 @@ func (q *EventQueue) Push(e Event, gen uint64) bool {

// PushWithError preserves admission errors such as a full bounded mailbox.
func (q *EventQueue) PushWithError(e Event, gen uint64) error {
return q.push(e, gen, nil)
}

// push admits e when the generation, and the yield epoch if one is given,
// still match.
func (q *EventQueue) push(e Event, gen uint64, epoch *uint64) error {
// Fast path: check generation and closed without lock
if q.generation.Load() != gen {
return ErrProcessClosed
Expand All @@ -130,7 +140,7 @@ func (q *EventQueue) PushWithError(e Event, gen uint64) error {

q.mu.Lock()
// Recheck under lock
if q.generation.Load() != gen || q.closed.Load() {
if q.generation.Load() != gen || q.closed.Load() || (epoch != nil && q.yieldEpoch.Load() != *epoch) {
q.mu.Unlock()
return ErrProcessClosed
}
Expand All @@ -147,6 +157,26 @@ func (q *EventQueue) PushWithError(e Event, gen uint64) error {
return nil
}

// RetireYieldCompletions starts a new yield epoch for a process replaced in
// place: completers created before the call become inert and yield
// completions already queued are discarded. Messages and senders bound to the
// queue generation are unaffected.
func (q *EventQueue) RetireYieldCompletions() {
q.mu.Lock()
q.yieldEpoch.Add(1)
kept := q.events[:0]
for _, e := range q.events {
if e.Type == EventYieldComplete {
discardEvent(e)
} else {
kept = append(kept, e)
}
}
clear(q.events[len(kept):])
q.events = kept
q.mu.Unlock()
}

// SetAdmission installs an execution's ingress policy before publishing its
// queue to senders. Reset removes the old policy before a queue is reused.
func (q *EventQueue) SetAdmission(admission EventAdmission) {
Expand Down Expand Up @@ -523,16 +553,20 @@ func (q *EventQueue) discardPending() {
for i := range q.events {
e := &q.events[i]
q.retireEventTopicsLocked(*e)
if d, ok := e.Data.(EventDiscarder); ok {
d.DiscardEvent()
} else if e.Type == EventMessage {
if pkg, ok := e.Data.(*relay.Package); ok {
relay.ReleasePackage(pkg)
}
}
discardEvent(*e)
*e = Event{}
}
}

func discardEvent(e Event) {
if d, ok := e.Data.(EventDiscarder); ok {
d.DiscardEvent()
} else if e.Type == EventMessage {
if pkg, ok := e.Data.(*relay.Package); ok {
relay.ReleasePackage(pkg)
}
}
}
func (q *EventQueue) retireEventTopicsLocked(event Event) {
if event.Type != EventMessage {
return
Expand Down Expand Up @@ -560,33 +594,36 @@ type YieldScheduler interface {
}

// YieldCompleter delivers yield completion results to a queue.
// Bound to a specific generation - stale completers silently no-op.
// Bound to a specific generation and yield epoch - stale completers silently no-op.
// This breaks the direct reference to Processor, preventing races
// when processor is released to pool while handler goroutines are still running.
type YieldCompleter struct {
scheduler YieldScheduler
queue *EventQueue
gen uint64
epoch uint64
}

// NewYieldCompleter creates a completer bound to current queue generation.
// NewYieldCompleter creates a completer bound to the current queue generation
// and yield epoch.
func (q *EventQueue) NewYieldCompleter(sched YieldScheduler) *YieldCompleter {
return &YieldCompleter{
queue: q,
gen: q.generation.Load(),
epoch: q.yieldEpoch.Load(),
scheduler: sched,
}
}

// CompleteYield implements dispatcher.ResultReceiver.
// Safe to call from any goroutine - uses generation to detect staleness.
func (c *YieldCompleter) CompleteYield(tag uint64, data any, err error) {
if !c.queue.Push(Event{
if c.queue.push(Event{
Type: EventYieldComplete,
Tag: tag,
Data: data,
Error: err,
}, c.gen) {
}, c.gen, &c.epoch) != nil {
return
}

Expand Down
19 changes: 19 additions & 0 deletions api/process/queue_generation_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -100,3 +100,22 @@ func TestA05ResetDrainsStaleSignal(t *testing.T) {
default:
}
}

func TestRetireYieldCompletionsInvalidatesEarlierCompleters(t *testing.T) {
queue := NewEventQueue()
wake := &boundaryWakeRecorder{}
old := queue.NewYieldCompleter(wake)
old.CompleteYield(1, "queued-before", nil)
require.True(t, queue.PushDirect(Event{Type: EventMessage, Data: "message"}))

queue.RetireYieldCompletions()
fresh := queue.NewYieldCompleter(wake)
old.CompleteYield(1, "stale", nil)
fresh.CompleteYield(1, "fresh", nil)

events := queue.Drain()
require.Len(t, events, 2)
assert.Equal(t, EventMessage, events[0].Type, "messages survive")
assert.Equal(t, "fresh", events[1].Data)
assert.Equal(t, 2, wake.calls, "the retired completer does not wake")
}
36 changes: 36 additions & 0 deletions api/process/queue_retirement_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
// SPDX-License-Identifier: MPL-2.0

package process

import "testing"

type ownedCompletion struct{ discarded int }

func (c *ownedCompletion) DiscardEvent() { c.discarded++ }

func TestRetiredCompletionsReleaseOwnership(t *testing.T) {
q := NewEventQueue()
first, second, message := &ownedCompletion{}, &ownedCompletion{}, &ownedCompletion{}
gen := q.Generation()
for _, e := range []Event{
{Type: EventYieldComplete, Tag: 1, Data: first},
{Type: EventMessage, Data: message},
{Type: EventYieldComplete, Tag: 2, Data: second},
} {
if !q.Push(e, gen) {
t.Fatal("queue rejected event")
}
}
q.RetireYieldCompletions()
q.RetireYieldCompletions()
if first.discarded != 1 || second.discarded != 1 {
t.Fatalf("retired ownership: %d, %d; want once each", first.discarded, second.discarded)
}
if message.discarded != 0 || q.Generation() != gen {
t.Fatal("retirement changed message ownership or queue generation")
}
q.Close()
if first.discarded != 1 || second.discarded != 1 || message.discarded != 1 {
t.Fatal("close must discard only the retained message")
}
}
11 changes: 11 additions & 0 deletions api/process/step.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@ const (
StepDone
StepYield // has yields to dispatch, wait for completions
StepUpgrade // process requested upgrade, worker handles swap
// StepPreempted reports that the process used up its preemption budget
// and is ready to continue. The scheduler dispatches the step's yields
// and runs the process again after other ready work.
StepPreempted
)

// MaxYields is the maximum yields per step that fit in the fixed buffer.
Expand Down Expand Up @@ -97,10 +101,17 @@ func (o *StepOutput) Continue() {
o.status = StepContinue
}

// Preempt marks process as preempted: ready to continue once other ready
// work has had a turn.
func (o *StepOutput) Preempt() {
o.status = StepPreempted
}

// Reset clears output for reuse.
func (o *StepOutput) Reset() {
o.buf[0] = Yield{}
o.buf[1] = Yield{}
clear(o.ext)
o.ext = o.ext[:0]
o.count = 0
o.status = StepContinue
Expand Down
10 changes: 10 additions & 0 deletions api/runtime/context.go
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,16 @@ func GetFramePID(ctx context.Context) (pid.PID, bool) {
return pid.PID{}, false
}

// SetFrameLifecycleOptions sets the lifecycle options (attrs.Attributes) in
// the FrameContext. Returns error if no frame context or frame is sealed.
func SetFrameLifecycleOptions(ctx context.Context, opts any) error {
fc := ctxapi.FrameFromContext(ctx)
if fc == nil {
return ctxapi.ErrNoFrameContext
}
return fc.Set(FrameLifecycleOptionsKey, opts)
}

// GetFrameLifecycleOptions retrieves lifecycle options from the FrameContext.
// Returns nil if not found.
func GetFrameLifecycleOptions(ctx context.Context) any {
Expand Down
Loading
Loading