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
- Variables
- func RunWorker(ctx context.Context, stdin io.Reader, stdout io.Writer) int
- type AdmissionHook
- type Client
- func (c *Client) Audio(ctx context.Context, data []byte, videoPath, subtitlePath string) subsync.SyncResult
- func (c *Client) Reference(ctx context.Context, data []byte, videoPath, lang string, minConf float64) subsync.SyncResult
- func (c *Client) RunAudio(ctx context.Context, data []byte, videoPath, subtitlePath string, ...) RunOutcome
- type Outcome
- type Request
- type Response
- type RunOutcome
- type WireCue
- type WireSyncResult
Constants ¶
const ( // OpReference aligns subtitle data against an embedded reference track // (syncing.SyncAgainstReference). OpReference = "reference" // OpAudio aligns subtitle data against the audio track // (syncing.SyncFromAudio). OpAudio = "audio" )
Op names for Request.Op.
const ProtocolVersion = 1
ProtocolVersion guards the parent/child JSON contract. Parent and child are the same binary, so a mismatch can only mean the executable was replaced while a request was in flight (upgrade race); the child answers with an error response rather than guessing.
Variables ¶
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 ¶
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 ¶
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" // OutcomeCrash: everything else — non-zero exit, protocol error, spawn // failure, or a worker-reported job error. OutcomeCrash Outcome = "crash" )
Job outcomes.
type Request ¶
type Request struct {
Op string `json:"op"`
VideoPath string `json:"video_path"`
SubtitlePath string `json:"subtitle_path,omitempty"`
Lang string `json:"lang,omitempty"`
Data []byte `json:"data"`
Version int `json:"version"`
MinConfidence float64 `json:"min_confidence,omitempty"`
}
Request is the parent->child job description, one per process invocation.
type Response ¶
type Response struct {
Error string `json:"error,omitempty"`
Result WireSyncResult `json:"result"`
Version int `json:"version"`
}
Response is the child->parent result envelope. Error is set for protocol or infrastructure failures; strategy-level "no sync found" is NOT an error (it travels as a MethodNone result, exactly like the in-process calls).
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.