Documentation
¶
Overview ¶
Package scheduler owns the durable per-session scheduled-task list and the interval contract the model-facing scheduler Tools share.
The store follows the plan store's private-file discipline: a private subdirectory of the session's own state directory, mode 0700 with a 0600 file, an atomic replace, a bounded size, and a versioned schema. The firing loop belongs to the Coding Runtime; this package owns only the record, the interval, and the store.
Index ¶
- Constants
- Variables
- func IntervalHuman(seconds int64) string
- func NextFireAfter(next time.Time, interval time.Duration, now time.Time) time.Time
- func ParseInterval(value string) (int64, error)
- type CreateRequest
- type Options
- type Store
- func (s *Store) Advance(ctx context.Context, id string, nextFireAt time.Time) error
- func (s *Store) Create(ctx context.Context, request CreateRequest) (Task, error)
- func (s *Store) Delete(ctx context.Context, id string) (bool, error)
- func (s *Store) Dir() string
- func (s *Store) List(ctx context.Context) ([]Task, error)
- func (s *Store) Load(ctx context.Context) error
- func (s *Store) Now() time.Time
- func (s *Store) RecordFire(ctx context.Context, id string, childID string, firedAt time.Time, ...) (Task, error)
- func (s *Store) SessionID() string
- func (s *Store) Update(ctx context.Context, id string, patch UpdateRequest) (Task, error)
- type Task
- type UpdateRequest
Constants ¶
const ( // DefaultMaxBytes bounds the task file. The list is small and is always read // whole, so a damaged file cannot force an unbounded allocation. DefaultMaxBytes int64 = 1 << 20 )
The store's private-file contract, matching the plan store's discipline.
const MinimumIntervalSeconds int64 = 60
MinimumIntervalSeconds is the floor every parsed interval is raised to.
Variables ¶
var ( // ErrInvalid identifies a refused scheduler request. ErrInvalid = errors.New("coding scheduler: invalid request") // ErrUnsafe identifies a filesystem object or record that violates the // private-store contract. ErrUnsafe = errors.New("coding scheduler: unsafe scheduler store") // ErrUnsupported means the platform cannot provide the required guarantees. ErrUnsupported = errors.New("coding scheduler: unsupported platform") // ErrTaskNotFound means no scheduled task carries the requested id. ErrTaskNotFound = errors.New("coding scheduler: no scheduled task with that id") )
var ErrInvalidInterval = errors.New("coding scheduler: invalid interval")
ErrInvalidInterval identifies an interval string this package refuses.
Functions ¶
func IntervalHuman ¶
IntervalHuman renders seconds as the reference's human form: "every 5 minutes", "every 1 hour", "every 2 days", "every 45 seconds".
func NextFireAfter ¶
NextFireAfter returns the first scheduled time strictly after now, advancing from the task's own next fire so the schedule keeps its phase. A next fire already in the past is skipped forward to the next future occurrence rather than replayed, so an overdue task fires once instead of once per missed interval.
func ParseInterval ¶
ParseInterval parses an interval of the form "<digits><s|m|h|d>" into seconds, tolerating surrounding whitespace. An empty value, a zero value, an unknown suffix, or a product that overflows is refused; a value below the 60-second floor is raised to it.
Types ¶
type CreateRequest ¶
type CreateRequest struct {
Prompt string
IntervalSeconds int64
Recurring bool
Durable bool
FireImmediately bool
}
CreateRequest is one task to add.
type Options ¶
type Options struct {
// Now returns the current time; nil uses time.Now.
Now func() time.Time
// After returns a channel that receives one value once the duration
// elapses; nil uses time.After. It is the loop's timer seam, so a test can
// advance time and observe a fire instead of waiting an interval.
After func(time.Duration) <-chan time.Time
// MaxBytes bounds the task file; zero uses DefaultMaxBytes.
MaxBytes int64
}
Options configure one session's scheduler store and its firing loop.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store owns one session's durable scheduled-task list. It is the single owner: the Tools, the firing loop, and the surfaces all read and write it, and it decides what a restart keeps — a durable task is reloaded, a session-only one is dropped.
func NewStoreAt ¶
NewStoreAt opens (creating when needed) the private scheduler directory under the session's own state directory. It does not read the task file; call Load to reload the durable tasks.
func (*Store) Advance ¶
Advance moves one task's next fire without recording a child, for a fire that could not start one. The task stays scheduled and nothing is reported.
func (*Store) Create ¶
Create adds one task and returns it. A fire_immediately task is due at once; every other task waits one interval.
func (*Store) Load ¶
Load reads the durable tasks and drops every session-only task, so a restart keeps only what was marked durable. A missing file is an empty list.
func (*Store) Now ¶
Now returns the store's current time, so the firing loop and the Tools share one clock.
func (*Store) RecordFire ¶
func (s *Store) RecordFire( ctx context.Context, id string, childID string, firedAt time.Time, nextFireAt time.Time, ) (Task, error)
RecordFire records the child one fire started and advances the schedule in the same durable write. A task that fires is removed when it is not recurring, and the removal is durable before the fire is reported, so a restart cannot fire it twice.
type Task ¶
type Task struct {
ID string `json:"id"`
Prompt string `json:"prompt"`
IntervalSecs int64 `json:"interval_seconds"`
Recurring bool `json:"recurring"`
Durable bool `json:"durable"`
CreatedAt time.Time `json:"created_at"`
// LastFiredAt is zero until the first fire.
LastFiredAt time.Time `json:"last_fired_at,omitzero"`
// NextFireAt is the authoritative schedule. A fire advances it from its own
// previous value, so the phase survives a late or a skipped fire.
NextFireAt time.Time `json:"next_fire_at"`
// LastChildID is the child the task's last fire started. The next fire is
// skipped while that child still runs.
LastChildID string `json:"last_child_id,omitempty"`
}
Task is one durable scheduled task. Every task pips records is recurring: a scheduled task keeps firing until it is deleted.
type UpdateRequest ¶
UpdateRequest patches one task in place. A nil field is left unchanged.