manager

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Example
package main

import (
	"context"
	"fmt"

	"github.com/compforge/go-stdx/timeline/manager"
	timelinestore "github.com/compforge/go-stdx/timeline/store"
)

func main() {
	m, err := manager.New(timelinestore.NewMemoryStore(), manager.Config{MaxTimelines: 1024})
	if err != nil {
		panic(err)
	}
	previous := manager.SetDefault(m)
	defer manager.SetDefault(previous)
	defer m.Shutdown(context.Background())

	// Stage recording needs neither Start nor Finish.
	if _, err := manager.Begin("task-42", "prepare_files"); err != nil {
		panic(err)
	}
	if err := manager.End("task-42", "prepare_files", nil); err != nil {
		panic(err)
	}
	snapshot, err := manager.Read(context.Background(), "task-42")
	if err != nil {
		panic(err)
	}
	fmt.Println(snapshot.Status, snapshot.Stages[0].Status)
}
Output:
unknown succeeded

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrAmbiguousStage = errors.New("timeline manager: multiple running stages share this name")
View Source
var ErrBufferFull = errors.New("timeline manager: pending save limit exceeded")
View Source
var ErrClosed = errors.New("timeline manager: shut down")
View Source
var ErrNoDefault = errors.New("timeline manager: no default installed")
View Source
var ErrStageNotFound = errors.New("timeline manager: stage not found")

Functions

func Begin

func Begin(id, name string, options ...timeline.StageOption) (timeline.StageHandle, error)

func End

func End(id, name string, stageErr error, options ...timeline.EndOption) error

func Finish

func Finish(id string, operationErr error) error

func Read

func Read(ctx context.Context, id string) (timeline.Snapshot, error)

func Record

func Record(id string, stage timeline.Stage) error

func Start

func Start(id, operation string, attributes ...timeline.Attribute) error

Types

type Config

type Config struct {
	MaxTimelines        int           // default 1024 cached documents
	FlushInterval       time.Duration // default 1s between background saves
	ExportTimeout       time.Duration // default 5s for each Store read/merge
	MaxPendingTimelines int           // default 1024, including evicted documents awaiting a final save
	MaxPendingUpdates   int           // default 1024 per document, before coalescing a save batch
	// OnError reports save failures outside locks. It must return promptly and
	// must not call Shutdown. Default: slog with the timeline ID, without data.
	OnError func(id string, err error)
}

Config bounds cache capacity and backend calls. Zero fields select defaults.

type Manager

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

Manager owns the policy joining ttlcache and Store. Writes acknowledge memory acceptance; Flush is the optional persistence checkpoint. This is a best-effort cache, without durable delivery or cross-process consistency. spec: Eviction schedules one final bounded save. Failure is reported and the buffer is released, so an unavailable Store cannot pin memory indefinitely.

func New

func New(backend store.Store, config Config) (*Manager, error)

func SetDefault

func SetDefault(m *Manager) *Manager

SetDefault installs the process Manager and returns the previous one. Install before producers start; replacement neither moves state nor shuts down either instance. Tests changing the default must run serially and restore it.

func (*Manager) Begin

func (m *Manager) Begin(id, name string, options ...timeline.StageOption) (timeline.StageHandle, error)

Begin records a running stage. Same-name parallel stages are allowed; retain their handles to disambiguate completion.

func (*Manager) BeginContext

func (m *Manager) BeginContext(ctx context.Context, id, name string, options ...timeline.StageOption) (context.Context, timeline.StageHandle, error)

BeginContext preserves cancellation/deadlines and inherits parents only from the same timeline. Explicit parent options override the inherited reference.

func (*Manager) End

func (m *Manager) End(id, name string, stageErr error, options ...timeline.EndOption) error

End completes the uniquely named running stage, restoring it on a cache miss. A rejected admission leaves it running and available for retry.

func (*Manager) Evict

func (c *Manager) Evict(id string)

Evict releases a cached copy and schedules its final best-effort save. Later access loads persistent state; an unsaved last update may be absent from it.

func (*Manager) Finish

func (m *Manager) Finish(id string, operationErr error) error

Finish optionally records a result. It neither ends stages nor evicts cached data.

func (*Manager) Flush

func (c *Manager) Flush(ctx context.Context) error

Flush waits for currently pending local facts. It neither discovers other processes' writes nor promises delivery of facts previously dropped.

func (*Manager) FlushID

func (c *Manager) FlushID(ctx context.Context, id string) error

func (*Manager) NewWriter

func (m *Manager) NewWriter(id string, actor timeline.Actor) (*timeline.Recorder, error)

NewWriter creates an actor-scoped recorder. Its writes use the same cache; recording may load Store on a miss. Keep each stage owned by one recorder.

func (*Manager) Read

func (c *Manager) Read(ctx context.Context, id string) (model.Snapshot, error)

Read returns the latest cached view, loading from Store on a miss. It does not wait for a save, and a warm cache may lag behind another process's writes. The returned snapshot owns its data. A closed cache reads Store directly.

func (*Manager) Record

func (m *Manager) Record(id string, data timeline.Stage) error

Record accepts a completed source interval, preserving times and Actor.

func (*Manager) Shutdown

func (c *Manager) Shutdown(ctx context.Context) error

Shutdown stops loading/writing, cancels background IO, then attempts to drain with the caller's context. Failed final saves are counted and released. Reads remain available directly from Store while the application keeps it open.

func (*Manager) Start

func (m *Manager) Start(id, operation string, attributes ...timeline.Attribute) error

Start optionally records the operation beginning. Identical repeats preserve its stored timestamp, including after a cache miss. Stages never require Start.

func (*Manager) Stats

func (c *Manager) Stats() Stats

type Stats

type Stats struct {
	CachedTimelines  int
	PendingTimelines int
	PendingUpdates   int
	DroppedUpdates   uint64
	RejectedUpdates  uint64
}

Stats reports process-local cache and save-buffer health. Counts do not describe durable completeness across processes.

Jump to

Keyboard shortcuts

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