Documentation
¶
Overview ¶
Package queue provides a simple job queue for processing media jobs.
Index ¶
- Variables
- type JobHandler
- type Queue
- func (q *Queue) Adopt(job *clip.Job)
- func (q *Queue) AssignOwnerless(owner int)
- func (q *Queue) Cancel(id string) bool
- func (q *Queue) CountActive(owner int) int
- func (q *Queue) Delete(id string)
- func (q *Queue) Done() <-chan struct{}
- func (q *Queue) Edit(id string, edit clip.Edit, output string, save func(*clip.Job) error) (*clip.Job, bool, error)
- func (q *Queue) EditAndRegenerate(id string, edit clip.Edit, output string, save func(*clip.Job) error) (*clip.Job, bool, error)
- func (q *Queue) GetAllJobs() []*clip.Job
- func (q *Queue) GetJob(id string) *clip.Job
- func (q *Queue) Reinstate(job *clip.Job)
- func (q *Queue) Requeue(job *clip.Job) error
- func (q *Queue) Restore(job *clip.Job)
- func (q *Queue) SetFailureFunc(fn clip.DescribeFunc)
- func (q *Queue) SetOutputBytes(id string, bytes int64) *clip.Job
- func (q *Queue) SetOutputFormat(id string, format clip.Format) *clip.Job
- func (q *Queue) SetProgress(id string, percent int) *clip.Job
- func (q *Queue) SetSDRFormat(id string, format clip.Format) *clip.Job
- func (q *Queue) SetShared(id string, shared bool) *clip.Job
- func (q *Queue) SetStage(id string, stage clip.Stage) *clip.Job
- func (q *Queue) SetStatusFunc(fn StatusFunc)
- func (q *Queue) SetWindow(id string, start, duration time.Duration) *clip.Job
- func (q *Queue) Start(ctx context.Context)
- func (q *Queue) Stop()
- func (q *Queue) Submit(job *clip.Job) error
- func (q *Queue) TrackProgress(id string, percent float64)
- type StatusFunc
Constants ¶
This section is empty.
Variables ¶
var ErrJobActive = errors.New("a job with this id is already active")
ErrJobActive is returned when a job is submitted while one with the same id is already queued or running.
var ErrJobNotFound = errors.New("job not found")
ErrJobNotFound is returned when an edit names a job the queue does not have.
var ErrJobPanicked = errors.New("job handler panicked")
ErrJobPanicked is recorded against a job whose handler panicked.
var ErrQueueStopped = errors.New("queue is stopped")
ErrQueueStopped is returned when a job is submitted to a stopped queue.
Functions ¶
This section is empty.
Types ¶
type JobHandler ¶
JobHandler is a function that handles jobs.
type Queue ¶
type Queue struct {
// contains filtered or unexported fields
}
Queue represents a job queue.
The queue owns a copy of every job it is handed. Waiting jobs are held as ids in submission order, so queueing never blocks, and a worker renders a snapshot of the entry while the entry itself only changes under the lock.
func NewQueue ¶
func NewQueue(workers int, handler JobHandler) *Queue
NewQueue creates a new job queue.
Parameters:
- workers: How many jobs may run at once.
- handler: Invoked for each job.
Returns:
- queue: A queue ready to Start.
func (*Queue) Adopt ¶ added in v0.4.0
Adopt registers a copy of a job unless the queue already holds one, so a stored record never replaces an entry another caller has just changed.
Parameters:
- job: The clip to track without running.
func (*Queue) AssignOwnerless ¶ added in v0.4.0
AssignOwnerless gives every clip that belongs to nobody to an account.
The installation's first owner takes over the clips made before owners were recorded, which storage has already handed over, so nothing is reported.
Parameters:
- owner: The plex.tv id of the account.
func (*Queue) Cancel ¶
Cancel stops a pending or processing job.
Parameters:
- id: The clip to cancel.
Returns:
- canceled: True when a pending or processing job was canceled.
func (*Queue) CountActive ¶ added in v0.4.0
CountActive counts an owner's jobs waiting or rendering.
Parameters:
- owner: The plex.tv id of the account the jobs belong to.
Returns:
- active: How many of the owner's jobs are pending or processing.
func (*Queue) Delete ¶
Delete removes a job from the in-memory map.
A waiting job leaves the line, and a running one is canceled and tombstoned, so its worker writes nothing back. A report of this job already under way finishes first, so it cannot write the job back after the caller deletes its row.
Parameters:
- id: The clip to remove.
func (*Queue) Done ¶
func (q *Queue) Done() <-chan struct{}
Done returns a channel that is closed when the queue is stopped.
Returns:
- done: Closed on teardown.
func (*Queue) Edit ¶ added in v0.4.0
func (q *Queue) Edit( id string, edit clip.Edit, output string, save func(*clip.Job) error, ) (*clip.Job, bool, error)
Edit applies a change to a job and saves it.
A job being rendered only accepts a change that leaves its file the same, such as a new name. A waiting job is edited in place, so the worker that takes it renders the new values. A job whose type changed is queued again in the same step, and only once the save succeeds. The save is ordered with the queue's status reports, and a failed save leaves the job as it was.
Parameters:
- id: The job to change.
- edit: The change to apply.
- output: Where the job renders to once its type is edit.Type.
- save: Writes the edited job. It runs without the queue lock.
Returns:
- job: A copy of the edited job.
- queued: True when the edit queued the job again, because its type changed and it was not already waiting.
- err: ErrJobNotFound, ErrJobActive when a rendering job would render differently, ErrQueueStopped when a job that has to be queued cannot be, or the save's error.
func (*Queue) EditAndRegenerate ¶ added in v0.4.0
func (q *Queue) EditAndRegenerate( id string, edit clip.Edit, output string, save func(*clip.Job) error, ) (*clip.Job, bool, error)
EditAndRegenerate edits a job and queues it to render again.
It applies the change and saves it. It refuses a job being rendered, whatever the change, and otherwise behaves as Edit.
Parameters:
- id: The job to change.
- edit: The change to apply.
- output: Where the job renders to once its type is edit.Type.
- save: Writes the edited job. It runs without the queue lock.
Returns:
- job: A copy of the edited job.
- queued: True unless the job was already waiting, where the worker that takes it renders the new values anyway.
- err: ErrJobNotFound, ErrJobActive when the job is rendering, ErrQueueStopped when the queue has stopped, or the save's error.
func (*Queue) GetAllJobs ¶
GetAllJobs returns every job, newest first.
Returns:
- jobs: Copies of every registered job.
func (*Queue) GetJob ¶
GetJob gets a job by ID, as a copy.
Parameters:
- id: The clip to read.
Returns:
- job: A copy of the job, nil when the queue does not have it.
func (*Queue) Reinstate ¶
Reinstate puts a job back after a delete that could not be completed.
The job comes back canceled, so a later start does not resume a render the delete stopped. A job a worker still holds is settled by that worker, which records the same cancellation.
Parameters:
- job: The job as it was before the delete.
func (*Queue) Requeue ¶
Requeue puts an idle job back on the queue for another attempt.
The job is reset to pending in place, so the caller's copy matches the queued one.
Parameters:
- job: The clip to run again.
Returns:
- err: ErrJobActive when a worker holds the job or it is already waiting, ErrQueueStopped when the queue has stopped.
func (*Queue) Restore ¶
Restore registers a copy of a job without enqueueing it.
Parameters:
- job: The clip to track without running.
func (*Queue) SetFailureFunc ¶ added in v0.4.0
func (q *Queue) SetFailureFunc(fn clip.DescribeFunc)
SetFailureFunc registers how a failed render is described on its card.
Until one is set, a failure shows the error's own text.
Parameters:
- fn: The describer, or nil to show the error's own text.
func (*Queue) SetOutputBytes ¶ added in v0.4.0
SetOutputBytes records how many bytes a finished render's files take.
Parameters:
- id: The clip.
- bytes: The size of the clip's file and its SDR version together.
Returns:
- job: The updated job, nil when the queue no longer has it.
func (*Queue) SetOutputFormat ¶ added in v0.4.0
SetOutputFormat records what a render's own file holds once it is published, and reports it.
Parameters:
- id: The clip being rendered.
- format: What the published file holds.
Returns:
- job: The updated job, nil when the queue no longer has it.
func (*Queue) SetProgress ¶
SetProgress records how far a render has got and reports it.
Parameters:
- id: The clip being rendered.
- percent: Progress so far.
Returns:
- job: The updated job, nil when the queue no longer has it.
func (*Queue) SetSDRFormat ¶ added in v0.4.0
SetSDRFormat records what a render's SDR version holds once it is published, or the zero format when it has none, and reports it.
Parameters:
- id: The clip being rendered.
- format: What the SDR version holds.
Returns:
- job: The updated job, nil when the queue no longer has it.
func (*Queue) SetShared ¶ added in v0.4.0
SetShared records whether a job's clip is shared with the installation's other users, and reports it.
Parameters:
- id: The clip.
- shared: Whether it is shared.
Returns:
- job: The updated job, nil when the queue no longer has it.
func (*Queue) SetStage ¶ added in v0.4.0
SetStage records that a render moved on to another encode, whose progress starts again from zero, and reports it.
Parameters:
- id: The clip being rendered.
- stage: The encode now running.
Returns:
- job: The updated job, nil when the queue no longer has it.
func (*Queue) SetStatusFunc ¶
func (q *Queue) SetStatusFunc(fn StatusFunc)
SetStatusFunc registers a callback invoked on job status changes.
Parameters:
- fn: The callback, or nil to stop reporting.
func (*Queue) SetWindow ¶ added in v0.4.0
SetWindow records where a render's clip starts in its source and how long it runs, and reports it.
A copied clip starts on the keyframe before its start mark, so its window is recorded once its file is published.
Parameters:
- id: The clip being rendered.
- start: Where the clip starts in its source.
- duration: How long the clip runs.
Returns:
- job: The updated job, nil when the queue no longer has it.
func (*Queue) Start ¶
Start starts the job queue workers.
Parameters:
- ctx: Lifetime for the queue and for every job.
func (*Queue) Submit ¶
Submit submits a copy of a job to the queue.
It never waits on a worker.
Parameters:
- job: The clip to queue.
Returns:
- err: ErrJobActive when the id is already queued or running, ErrQueueStopped when the queue has stopped.
func (*Queue) TrackProgress ¶ added in v0.4.0
TrackProgress records a running encode's exact percent without reporting it.
It also records the whole percent the exact one rounds down to. Reads see each step a slow encode takes between the reports Queue.SetProgress makes.
Parameters:
- id: The clip being rendered.
- percent: Progress so far, not rounded.
type StatusFunc ¶
StatusFunc is called with a copy of a job whenever its status or progress changes.
Source Files