memoryschedule

package
v0.7.2 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 9 Imported by: 0

README

Memory Schedule

arkoren.dev/core/service/schedule/memoryschedule is an in-process implementation of the Arkoren schedule.Driver contract, built on time.AfterFunc. It runs recurring entries and deferred jobs. It is single-process only: every replica runs every entry. Deferred timers are discarded when Run stops, and all work is lost on process exit. Submissions accepted while stopped or draining wait for a later raw-driver Run.

It is included in go get arkoren.dev/core. Import "arkoren.dev/core/service/schedule/memoryschedule", pass memoryschedule.New() to schedule.New, and register entries before running the scheduler. See the memory scheduler setup.

To test code that defers jobs, use scheduletest.Fake. To test timing, run the driver inside testing/synctest.

Cancellation and ownership

Defer copies accepted payload bytes, including jobs submitted before Run. An already-canceled submission returns the context error and no ID without scheduling. An already-canceled Cancel returns the context error without removing work. Cancellation after acceptance does not revoke a job; request removal with a live-context Cancel instead. Cancel cannot interrupt a dispatch that has already started.

Canceling Run stops timer admission and discards queued timers, then waits for admitted executions. Those execution contexts keep values but not the runner's deadline or cancellation. The driver has no drain timeout: a handler waiting only for its detached context can keep Run blocked indefinitely. Entry timeout defaults to unlimited, so set a positive cooperative timeout and bound I/O when work needs an execution deadline. Deferred task handlers own their own I/O bounds.

The application defaults to a 30-second runner-wait budget before continuing with cleanup. That budget does not kill executions, and is not a hard total shutdown deadline: cleanup and telemetry receive separate minimum budgets. Do not assume application cleanup means scheduler work has finished.

Another Run is rejected with the existing ErrAlreadyRunning identity until the first has finished draining. Once it returns, the raw driver can run again; a schedule.Scheduler facade remains single-use. New deferred submissions during draining remain pending for a later raw-driver Run.

Documentation

Overview

Package memoryschedule provides an in-process schedule.Driver for local development and single-replica deployments. It is single-process only: every replica runs every entry. Pending work from a running generation is discarded when its timers stop, and all work is lost on process exit. It uses the time package, so tests can run it inside testing/synctest.

New accepts Builder callbacks for its shared logger. They run directly once in order on one fresh draft. Nil entries panic; nil/empty slice expansion supplies no edits. Retained drafts cannot change the driver after publication.

scheduler := schedule.New(memoryschedule.New())
compose.Run(scheduler.Run)

Cancellation stops admission and drains already-started work on contexts detached from runner cancellation. Draining has no driver timeout. Entry timeout defaults to unlimited; set a positive cooperative execution timeout and bound task I/O rather than expecting cancellation of Run to stop handlers. Application shutdown can time out its runner wait and proceed to cleanup while an execution remains active. Concurrent Run is rejected through drain. Submissions accepted after timer admission closes wait pending for a later Run.

Index

Constants

This section is empty.

Variables

View Source
var ErrAlreadyRunning = errors.New("memory schedule driver is already running")

ErrAlreadyRunning is returned when Run is called while another Run is active. The original Run retains ownership while draining executions as well as while scheduling timers. This driver-specific identity remains stable; the facade separately uses schedule.ErrRunning to reject repeated Scheduler.Run calls.

if err := driver.Run(ctx, entries, dispatch); errors.Is(err, memoryschedule.ErrAlreadyRunning) {
	return err
}

Functions

This section is empty.

Types

type Builder

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

Builder edits an in-process driver's construction draft. New copies its logger selection; retaining the draft cannot reconfigure a published driver.

driver := memoryschedule.New(func(scheduler *memoryschedule.Builder) {
	scheduler.Logger(slog.Default())
})

func (*Builder) Logger

func (scheduler *Builder) Logger(value *slog.Logger) *Builder

Logger selects the shared run logger without logging or starting timers. A final nil selects slog.Default in New. It returns the same draft.

driver := memoryschedule.New(func(scheduler *memoryschedule.Builder) {
	scheduler.Logger(slog.Default())
})

type BuilderFunc

type BuilderFunc = func(*Builder)

BuilderFunc edits the fresh draft used by New without starting timers. Callbacks run synchronously once in order; supplied nil callbacks panic. Later edits through a retained draft do not replace the driver's logger.

Example:

policy := memoryschedule.BuilderFunc(func(scheduler *memoryschedule.Builder) {
	scheduler.Logger(slog.Default())
})
driver := memoryschedule.New(policy)

type Driver

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

Driver implements schedule.Driver with timers in memoryschedule.

It is single-process only: every replica that runs it runs every entry. Queued timers are discarded when Run stops; all work is lost on process exit. Submissions accepted while stopped or draining wait pending for a later Run. Construction starts no timers; one Run owns timing and drains admitted work.

driver := memoryschedule.New()
scheduler := schedule.New(driver)
compose.Run(scheduler.Run)

func New

func New(configure ...BuilderFunc) *Driver

New creates an in-process driver without starting timers. Callbacks run directly once in order on one fresh draft; nil entries panic and expanded nil/empty slices omit edits. Publication detaches retained drafts.

driver := memoryschedule.New(func(scheduler *memoryschedule.Builder) {
	scheduler.Logger(slog.Default())
})

func (*Driver) Cancel

func (driver *Driver) Cancel(ctx context.Context, id string) error

Cancel removes the deferred job with the given id. An unknown id is not an error. A context canceled before mutation returns its error without removing pending work. Cancel does not interrupt a dispatch that has already started.

if err := driver.Cancel(ctx, id); err != nil {
	return err
}

func (*Driver) Defer

func (driver *Driver) Defer(ctx context.Context, job schedule.Job) (string, error)

Defer stores job until its time. Before Run it is kept pending and armed when Run starts. A job whose time has passed fires as soon as possible. Payload bytes are copied before acceptance, including for pending jobs. A context canceled before acceptance returns its error and an empty ID without scheduling. Cancellation after acceptance does not remove the job; use Cancel. During draining, new submissions wait pending for a later Run.

id, err := driver.Defer(ctx, schedule.Job{
	Name:    "remind",
	Payload: []byte(`"hello"`),
	At:      due,
})
if err != nil {
	return err
}
fmt.Println(id)

func (*Driver) Run

func (driver *Driver) Run(ctx context.Context, entries []schedule.Entry, dispatch schedule.Dispatch) error

Run schedules entries and deferred jobs, and blocks until ctx is done. It then stops all timers, waits for runs in flight, and returns nil. A second concurrent call returns ErrAlreadyRunning. This guard remains active through draining. After Run returns, the driver can be run again; a Scheduler facade itself remains single-use.

Runner cancellation stops timer admission, not executions. Their contexts retain values but no runner deadline or cancellation. Draining has no driver timeout: default entry timeouts are unlimited. Handlers must finish through application work or a positive schedule.EntryBuilder.Timeout. A handler waiting only for its detached context can prevent Run from returning; timeouts require the execution to cooperate with its context. Application shutdown bounds its own runner wait, not this execution lifetime, and can proceed to cleanup while work remains. No forced termination occurs.

if err := driver.Run(ctx, scheduler.Entries(), dispatch); err != nil {
	return err
}

Jump to

Keyboard shortcuts

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