syncworker

package
v0.8.0-dev.2 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

Documentation

Overview

Package syncworker isolates subtitle-sync computation in a supervised one-shot child process (P13). Sync is the engine's most memory-intensive work (PCM decode + alignment inside a 1 GiB no-swap container); running it in a same-binary `subflux sync-worker` child means a memory blowup is killed by the kernel OOM killer as the LARGEST-badness process — the fat child — while the server keeps serving. One job per process, versioned JSON over stdin/stdout, kill-on-cancel, concurrency-one admission.

The protocol carries the raw inputs of the two heavy strategies (reference-based and audio-based sync) and returns a wire copy of subsync.SyncResult. Both sides convert to/from the real subsync types, so the parent applies the SAME Applied()/ShouldApply() logic it always did — no duplicated decision rules on the wire.

Index

Constants

This section is empty.

Variables

View Source
var ErrAdmissionRefused = errors.New("sync job admission refused")

ErrAdmissionRefused reports that the admission hook refused the run (a cancel won the race before the worker spawned).

Functions

func RunWorker

func RunWorker(ctx context.Context, stdin io.Reader, stdout io.Writer) int

RunWorker executes exactly one sync job read from stdin and writes the response to stdout. Called by the hidden `subflux sync-worker` subcommand. The exit code reflects PROTOCOL health only (0 even when the sync found nothing); the parent judges the job by the JSON response. ctx cancellation (parent kill, signal) aborts the underlying ffmpeg/alignment work.

Types

type AdmissionHook added in v0.5.0

type AdmissionHook func() bool

AdmissionHook is invoked exactly once, at acquisition of the single execution slot and before the worker spawns. Returning false REFUSES the admission: the slot is released, no work runs, and the job reports OutcomeCancelled. A nil hook admits unconditionally.

type Client

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

Client runs sync jobs in supervised one-shot `subflux sync-worker` child processes. It implements syncing.SyncExec, so the Syncer, the engine's audio fallback, and the manual sync handlers all route their heavy computation through it transparently.

Admission is concurrency-one (the P13 queue, subsuming the sync-semaphore side finding): a season sync of N episodes runs at most one alignment at a time, and manual jobs queue behind automatic ones. Failure is degradation, never escalation: a worker death (OOM kill, crash, timeout) is WARN-logged and reported as a no-change result — the subtitle stays unsynced, the download proceeds, the server keeps serving.

func NewClient

func NewClient() (*Client, error)

NewClient builds the process-isolation client. It resolves the current executable once; construction fails only when the running binary's path cannot be determined (in which case the caller should fall back to in-process sync).

func NewInProcess added in v0.5.0

func NewInProcess() *Client

NewInProcess builds a Client whose jobs run inside THIS process instead of a child: the fallback for when the running executable's path cannot be resolved. Same admission slot, budget, and typed outcomes; no process isolation (the pre-P13 posture — an OOM takes the server with it).

func (*Client) Audio

func (c *Client) Audio(ctx context.Context, data []byte, videoPath, subtitlePath string) subsync.SyncResult

Audio implements syncing.SyncExec: audio-based sync in a worker. A thin projection of the typed core, like Reference.

func (*Client) Reference

func (c *Client) Reference(ctx context.Context, data []byte, videoPath, lang string, minConf float64) subsync.SyncResult

Reference implements syncing.SyncExec: reference-track sync in a worker. A thin projection of the typed core — every non-result outcome degrades to the documented no-change result.

func (*Client) RunAudio added in v0.5.0

func (c *Client) RunAudio(ctx context.Context, data []byte, videoPath, subtitlePath string, hook AdmissionHook) RunOutcome

RunAudio runs one audio-sync job through the typed core: admission on the single slot (hook at acquisition), unconditional budget, typed outcome.

type Outcome added in v0.5.0

type Outcome string

Outcome discriminates how one worker job ended, each by its own NAMED signal: the budget timer's cause sentinel, the job context, or the process exit state. Nothing is inferred from error text.

const (
	// OutcomeResult: the worker delivered a versioned JSON response with
	// exit 0 and no job error.
	OutcomeResult Outcome = "result"
	// OutcomeTimeout: the analysis budget (maxWorkerRuntime) fired —
	// identified by its own cause sentinel, never inferred from ctx.Err.
	OutcomeTimeout Outcome = "timeout"
	// OutcomeCancelled: the job context was cancelled (stop request,
	// shutdown), or the admission hook refused the run.
	OutcomeCancelled Outcome = "cancelled"
)

Job outcomes.

type RunOutcome added in v0.5.0

type RunOutcome struct {
	Err     error
	Outcome Outcome
	Result  subsync.SyncResult
}

RunOutcome is the typed core's answer. Result is meaningful only for OutcomeResult; Err carries the timeout/cancel/crash detail.

Jump to

Keyboard shortcuts

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