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 ¶
- Variables
- func Begin(id, name string, options ...timeline.StageOption) (timeline.StageHandle, error)
- func End(id, name string, stageErr error, options ...timeline.EndOption) error
- func Finish(id string, operationErr error) error
- func Read(ctx context.Context, id string) (timeline.Snapshot, error)
- func Record(id string, stage timeline.Stage) error
- func Start(id, operation string, attributes ...timeline.Attribute) error
- type Config
- type Manager
- func (m *Manager) Begin(id, name string, options ...timeline.StageOption) (timeline.StageHandle, error)
- func (m *Manager) BeginContext(ctx context.Context, id, name string, options ...timeline.StageOption) (context.Context, timeline.StageHandle, error)
- func (m *Manager) End(id, name string, stageErr error, options ...timeline.EndOption) error
- func (c *Manager) Evict(id string)
- func (m *Manager) Finish(id string, operationErr error) error
- func (c *Manager) Flush(ctx context.Context) error
- func (c *Manager) FlushID(ctx context.Context, id string) error
- func (m *Manager) NewWriter(id string, actor timeline.Actor) (*timeline.Recorder, error)
- func (c *Manager) Read(ctx context.Context, id string) (model.Snapshot, error)
- func (m *Manager) Record(id string, data timeline.Stage) error
- func (c *Manager) Shutdown(ctx context.Context) error
- func (m *Manager) Start(id, operation string, attributes ...timeline.Attribute) error
- func (c *Manager) Stats() Stats
- type Stats
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrAmbiguousStage = errors.New("timeline manager: multiple running stages share this name")
var ErrBufferFull = errors.New("timeline manager: pending save limit exceeded")
var ErrClosed = errors.New("timeline manager: shut down")
var ErrNoDefault = errors.New("timeline manager: no default installed")
var ErrStageNotFound = errors.New("timeline manager: stage not found")
Functions ¶
func Begin ¶
func Begin(id, name string, options ...timeline.StageOption) (timeline.StageHandle, 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 SetDefault ¶
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 ¶
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 ¶
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 ¶
Finish optionally records a result. It neither ends stages nor evicts cached data.
func (*Manager) Flush ¶
Flush waits for currently pending local facts. It neither discovers other processes' writes nor promises delivery of facts previously dropped.
func (*Manager) NewWriter ¶
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 ¶
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) Shutdown ¶
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.