engine

package
v0.8.7 Latest Latest
Warning

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

Go to latest
Published: Oct 21, 2026 License: Apache-2.0 Imports: 7 Imported by: 1

Documentation

Overview

Package engine owns the Engine — the central command router of the CQRS architecture. The Engine receives Commands from controllers, resolves the correct Domain from the Registry by GVK, and dispatches Handle. It is the only component that bridges the controller layer and the domain layer.

The Engine supports two execution modes:

  1. Synchronous (default) — Execute() dispatches directly to the Domain and returns the error to the caller (controller-runtime requeue path). This is the mode used in all current deployments.

  2. Async worker pool (optional) — Queue() enqueues Commands into a buffered channel; a configurable pool of goroutines drains it via workerLoop. This mode is opt-in via SetWorkers() and StartWorkers(), intended for high- throughput production deployments where controller goroutines should not block on Domain execution.

When no workers are configured (workers == 0), Queue() falls through to Execute() so callers need not distinguish between modes.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Engine

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

Engine routes Commands to the correct Domain and supports both synchronous and async execution modes. A single Engine instance is shared across all controllers registered with the manager.

func NewEngine

func NewEngine(registry *registry.Registry, logger logr.Logger) *Engine

NewEngine constructs an Engine bound to the given Registry and logger. The engine starts in synchronous mode (workers == 0). Call SetWorkers and StartWorkers to enable async execution.

func (*Engine) Execute

func (e *Engine) Execute(ctx context.Context, cmd command.Command) error

Execute dispatches a Command synchronously to the Domain registered for cmd.GVK. Returns an error if no Domain is registered or if Handle fails. The error propagates back to controller-runtime as a requeue signal.

func (*Engine) Queue

func (e *Engine) Queue(ctx context.Context, cmd command.Command) error

Queue enqueues a Command for async processing when workers > 0, or falls through to Execute when in synchronous mode. Blocks if the queue is full and returns ctx.Err() if the context is cancelled while waiting.

func (*Engine) SetWorkers

func (e *Engine) SetWorkers(n int)

SetWorkers configures the async worker pool size. Must be called before StartWorkers. Zero (default) keeps the Engine in synchronous mode.

func (*Engine) StartWorkers

func (e *Engine) StartWorkers()

StartWorkers spawns the configured number of async worker goroutines. No-op when workers == 0. Safe to call once at manager startup after SetWorkers.

func (*Engine) StopWorkers

func (e *Engine) StopWorkers(timeout time.Duration)

StopWorkers signals all worker goroutines to exit and waits for them to drain, up to the given timeout. Called during manager shutdown. No-op when workers == 0. Safe to call more than once.

Jump to

Keyboard shortcuts

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