timeout

type AckResponse ¶

type AckResponse struct {
	actor.BaseMessage

	// Success indicates whether the operation succeeded.
	Success bool

	// Error contains an error message if Success is false.
	Error string
}

AckResponse acknowledges a schedule or cancel request.

func (m *AckResponse) MessageType() string

type Actor ¶

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

Actor is the timeout scheduling actor. It manages one-shot timers and recurring tickers, sending notifications when they fire.

All state lives only inside the actor's Receive goroutine. Clock callbacks Tell self with an internalTimerFired / internalTickFired message and the real state mutation happens when that message reaches Receive — there is no cross-goroutine map access, so no mutex.

Recurring ticks are implemented as a chain of one-shot timers: each fire delivers TickFiredMsg to the user callback and re-arms via AfterFunc. This gives "fixed-delay" semantics (the next tick is scheduled at handler-finish + interval) and avoids the burst-of-ticks catch-up behaviour of time.Ticker when a consumer is slow.

func NewActor() *Actor

func NewActorWithClock(clock Clock) *Actor

func (a *Actor) Receive(ctx context.Context, msg Msg) fn.Result[Resp]

func (a *Actor) Start(self actor.TellOnlyRef[Msg])

type CancelTimeoutRequest ¶

type CancelTimeoutRequest struct {
	actor.BaseMessage

	// ID is the unique identifier of the timeout to cancel.
	ID ID
}

CancelTimeoutRequest requests the timeout actor to cancel a pending timeout.

func (m *CancelTimeoutRequest) MessageType() string

type Clock ¶

type Clock interface {
	// Now returns the current time.
	Now() time.Time

	// AfterFunc schedules f to run after d. The returned Stoppable can
	// be used to cancel the pending call.
	AfterFunc(d time.Duration, f func()) Stoppable
}

Clock abstracts wall-clock time so tests can deterministically advance it. Production callers receive a RealClock implicitly via NewActor; tests instead pass a fake clock through NewActorWithClock and drive time forward step-by-step.

AfterFunc is the only scheduling primitive: recurring ticks are built on top of it as a chain of one-shots that re-arm from inside the actor's Receive method, so there is no need for a separate Ticker abstraction.

type ExpiredMsg ¶

type ExpiredMsg struct {
	actor.BaseMessage

	// ID is the unique identifier of the timeout that expired.
	ID ID
}

ExpiredMsg is sent back to the callback when a timeout expires. This message is also a valid Msg so it can be received by the rounds actor.

func (m *ExpiredMsg) MessageType() string

type ID ¶

type ID string

ID is a unique identifier for a scheduled timeout. This is intentionally generic so that it can be used by any component that needs timeout scheduling (e.g., rounds, sessions, etc.).

type Msg ¶

type Msg interface {
	actor.Message
	// contains filtered or unexported methods
}

Msg is the sealed interface for messages that can be sent to the TimeoutActor.

type RealClock ¶

type RealClock struct{}

RealClock is the production Clock implementation. It delegates to the standard library time package.

func (RealClock) AfterFunc(d time.Duration, f func()) Stoppable

func (RealClock) Now() time.Time

type Resp ¶

type Resp interface {
	actor.Message
	// contains filtered or unexported methods
}

Resp is the sealed interface for responses from the TimeoutActor.

type ScheduleRecurringTickRequest ¶

type ScheduleRecurringTickRequest struct {
	actor.BaseMessage

	// ID is the unique identifier for this recurring tick. It shares
	// the namespace with one-shot timeout IDs; CancelTimeoutRequest
	// works on either.
	ID ID

	// Interval is the cadence at which TickFiredMsg is delivered.
	Interval time.Duration

	// Callback receives a *TickFiredMsg on each tick.
	Callback actor.TellOnlyRef[*TickFiredMsg]
}

ScheduleRecurringTickRequest schedules a recurring tick that fires *TickFiredMsg to Callback at every Interval, until cancelled. Cancel uses the existing CancelTimeoutRequest keyed by ID. The first fire is at Interval (not immediate). Re-scheduling with the same ID stops the previous ticker.

func (m *ScheduleRecurringTickRequest) MessageType() string

type ScheduleTimeoutRequest ¶

type ScheduleTimeoutRequest struct {
	actor.BaseMessage

	// ID is the unique identifier for this timeout.
	ID ID

	// Duration is how long to wait before the timeout expires.
	Duration time.Duration

	// The timeout actor will send *ExpiredMsg to this reference.
	Callback actor.TellOnlyRef[*ExpiredMsg]
}

ScheduleTimeoutRequest requests the timeout actor to schedule a timeout. When the timeout expires, an ExpiredMsg will be sent to the Callback.

func (m *ScheduleTimeoutRequest) MessageType() string

type Stoppable ¶

type Stoppable interface {
	// Stop prevents the timer from firing. Returns true if the call
	// stops the timer, false if the timer has already fired or been
	// stopped.
	Stop() bool
}

Stoppable is a one-shot timer handle. *time.Timer satisfies this interface directly.

type TickFiredMsg ¶

type TickFiredMsg struct {
	actor.BaseMessage

	// ID is the recurring tick that fired.
	ID ID

	// FiredAt is the wall-clock time the tick was generated by the
	// scheduler. Under a fake clock this is the test's logical time.
	FiredAt time.Time
}

TickFiredMsg is delivered to a recurring callback on each tick.

func (m *TickFiredMsg) MessageType() string