Documentation
¶
Overview ¶
Package auxreq Auxiliary request client for executor-runner binding.
Index ¶
- Constants
- Variables
- func NewClient(exec func() ExecutorRunner) auxiliary.Client
- type BackgroundScheduler
- func (s *BackgroundScheduler) Await(ctx context.Context, id auxiliary.JobID) (out lipapi.Collected, err error)
- func (s *BackgroundScheduler) BindRunner(runner ExecutorRunner) auxiliary.BackgroundClient
- func (s *BackgroundScheduler) Close() error
- func (s *BackgroundScheduler) Forget(id auxiliary.JobID)
- func (s *BackgroundScheduler) Poll(ctx context.Context, id auxiliary.JobID) (auxiliary.PollResult, error)
- func (s *BackgroundScheduler) SubmitCollect(ctx context.Context, req auxiliary.Request, opts auxiliary.SubmitOptions) (auxiliary.JobID, error)
- type BackgroundSchedulerConfig
- type Client
- type ExecutorRunner
- type SchedulerConfig
Constants ¶
const MaxDetachedAuxiliaryRoleBytes = 128
MaxDetachedAuxiliaryRoleBytes bounds trusted role metadata before it enters a detached execution context. Roles are classification tokens, not content.
Variables ¶
var ( // ErrQueueFull means the bounded scheduler cannot admit another distinct job. ErrQueueFull = errors.New("auxreq: background queue is full") // ErrSchedulerClosed means no new work is admitted after process shutdown starts. ErrSchedulerClosed = errors.New("auxreq: background scheduler is closed") // ErrInvalidCoalesceKey prevents uncommitted or otherwise unkeyed work from // entering the billable background scheduler. ErrInvalidCoalesceKey = errors.New("auxreq: empty coalescing key") // ErrInvalidJobID means Await was given an empty identifier. ErrInvalidJobID = errors.New("auxreq: empty job id") // ErrJobNotFound means a result was forgotten or evicted from bounded retention. ErrJobNotFound = errors.New("auxreq: job result not found") // ErrResultTooLarge means collection exceeded the scheduler's result byte bound. ErrResultTooLarge = errors.New("auxreq: collected result exceeds configured bound") )
var ErrInvalidDetachedRole = errors.New("auxreq: invalid detached auxiliary role")
Functions ¶
func NewClient ¶
func NewClient(exec func() ExecutorRunner) auxiliary.Client
NewClient wraps a lazily resolved executor pointer so [runtimebundle.Build] can bind the snapshot before the executor value exists.
Types ¶
type BackgroundScheduler ¶
type BackgroundScheduler struct {
// contains filtered or unexported fields
}
BackgroundScheduler owns a fixed worker pool and a bounded result registry for process-scoped auxiliary collection. It is intentionally not a generic task runner: jobs contain only a canonical auxiliary request and a captured ExecutorRunner.
func NewBackgroundClient ¶
func NewBackgroundClient(root context.Context, runner func() ExecutorRunner, cfg SchedulerConfig) (*BackgroundScheduler, error)
NewBackgroundClient is a convenience constructor with the SDK capability's name. It preserves the concrete scheduler for callers that need Close.
func NewBackgroundScheduler ¶
func NewBackgroundScheduler(root context.Context, runner func() ExecutorRunner, cfg SchedulerConfig) (*BackgroundScheduler, error)
NewBackgroundScheduler creates a process-owned collector. The runner provider is consulted synchronously on each accepted direct submission; workers use the captured runner and never acquire a later generation. Use BindRunner when a generation snapshot needs an immutable client view.
func (*BackgroundScheduler) Await ¶
func (s *BackgroundScheduler) Await(ctx context.Context, id auxiliary.JobID) (out lipapi.Collected, err error)
Await waits for a bounded result without inheriting the worker's lifetime.
func (*BackgroundScheduler) BindRunner ¶
func (s *BackgroundScheduler) BindRunner(runner ExecutorRunner) auxiliary.BackgroundClient
BindRunner returns a generation-bound view over the process-owned scheduler. The view contains no worker, queue, or result state of its own. Its runner is immutable for the lifetime of the view; Await and Forget continue to use the scheduler's process-owned result registry.
func (*BackgroundScheduler) Close ¶
func (s *BackgroundScheduler) Close() error
Close stops admission, cancels worker contexts, joins all workers, and drains any jobs that were still buffered so every retained pin is released.
func (*BackgroundScheduler) Forget ¶
func (s *BackgroundScheduler) Forget(id auxiliary.JobID)
Forget removes a result (or prevents a pending result from being retained) from the bounded registry. Active work still owns its submit-time pin until terminal worker completion.
func (*BackgroundScheduler) Poll ¶
func (s *BackgroundScheduler) Poll(ctx context.Context, id auxiliary.JobID) (auxiliary.PollResult, error)
Poll inspects a background job without blocking. It distinguishes pending, completed, failed, and not-found/expired states, clones completed results defensively, and does not consume or forget the job.
func (*BackgroundScheduler) SubmitCollect ¶
func (s *BackgroundScheduler) SubmitCollect(ctx context.Context, req auxiliary.Request, opts auxiliary.SubmitOptions) (auxiliary.JobID, error)
SubmitCollect synchronously captures the current executor and generation pin, then transfers both into the bounded queue. Parent cancellation after this handoff does not cancel worker execution.
type BackgroundSchedulerConfig ¶
type BackgroundSchedulerConfig = SchedulerConfig
BackgroundSchedulerConfig is an additive name for callers that prefer the capability's full name.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client implements auxiliary.Client by delegating to the runtime executor (design §7).
type ExecutorRunner ¶
type ExecutorRunner interface {
Execute(ctx context.Context, call *lipapi.Call) (lipapi.EventStream, error)
}
ExecutorRunner is satisfied by *runtime.Executor for auxiliary delegation.
type SchedulerConfig ¶
type SchedulerConfig struct {
Workers int
QueueCapacity int
MaxResults int
ResultTTL time.Duration
JobTimeout time.Duration
MaxResultBytes int
// Now supplies scheduler bookkeeping time. Production uses time.Now; tests
// may provide a deterministic clock without sleeping.
Now func() time.Time
}
SchedulerConfig bounds all process-local background state. Zero values use conservative defaults; negative values are rejected.
Source Files