|
Packit |
63bb0d |
// Package jobqueue provides a generic interface to a simple job queue.
|
|
Packit |
63bb0d |
//
|
|
Packit |
63bb0d |
// Jobs are pushed to the queue with Enqueue(). Workers call Dequeue() to
|
|
Packit |
63bb0d |
// receive a job and FinishJob() to report one as finished.
|
|
Packit |
63bb0d |
//
|
|
Packit |
63bb0d |
// Each job has a type and arguments corresponding to this type. These are
|
|
Packit |
63bb0d |
// opaque to the job queue, but it mandates that the arguments must be
|
|
Packit |
63bb0d |
// serializable to JSON. Similarly, a job's result has opaque result arguments
|
|
Packit |
63bb0d |
// that are determined by its type.
|
|
Packit |
63bb0d |
//
|
|
Packit |
63bb0d |
// A job can have dependencies. It is not run until all its dependencies have
|
|
Packit |
63bb0d |
// finished.
|
|
Packit |
63bb0d |
package jobqueue
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
import (
|
|
Packit |
63bb0d |
"context"
|
|
Packit Service |
509fd4 |
"encoding/json"
|
|
Packit |
63bb0d |
"errors"
|
|
Packit |
63bb0d |
"time"
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
"github.com/google/uuid"
|
|
Packit |
63bb0d |
)
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
// JobQueue is an interface to a simple job queue. It is safe for concurrent use.
|
|
Packit |
63bb0d |
type JobQueue interface {
|
|
Packit |
63bb0d |
// Enqueues a job.
|
|
Packit |
63bb0d |
//
|
|
Packit |
63bb0d |
// `args` must be JSON-serializable and fit the given `jobType`, i.e., a worker
|
|
Packit |
63bb0d |
// that is running that job must know the format of `args`.
|
|
Packit |
63bb0d |
//
|
|
Packit |
63bb0d |
// All dependencies must already exist, but the job isn't run until all of them
|
|
Packit |
63bb0d |
// have finished.
|
|
Packit |
63bb0d |
//
|
|
Packit |
63bb0d |
// Returns the id of the new job, or an error.
|
|
Packit |
63bb0d |
Enqueue(jobType string, args interface{}, dependencies []uuid.UUID) (uuid.UUID, error)
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
// Dequeues a job, blocking until one is available.
|
|
Packit |
63bb0d |
//
|
|
Packit |
63bb0d |
// Waits until a job with a type of any of `jobTypes` is available, or `ctx` is
|
|
Packit |
63bb0d |
// canceled.
|
|
Packit |
63bb0d |
//
|
|
Packit Service |
509fd4 |
// Returns the job's id, dependencies, type, and arguments, or an error. Arguments
|
|
Packit Service |
509fd4 |
// can be unmarshaled to the type given in Enqueue().
|
|
Packit Service |
509fd4 |
Dequeue(ctx context.Context, jobTypes []string) (uuid.UUID, []uuid.UUID, string, json.RawMessage, error)
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
// Mark the job with `id` as finished. `result` must fit the associated
|
|
Packit |
63bb0d |
// job type and must be serializable to JSON.
|
|
Packit |
63bb0d |
FinishJob(id uuid.UUID, result interface{}) error
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
// Cancel a job. Does nothing if the job has already finished.
|
|
Packit |
63bb0d |
CancelJob(id uuid.UUID) error
|
|
Packit |
63bb0d |
|
|
Packit Service |
509fd4 |
// If the job has finished, returns the result as raw JSON.
|
|
Packit Service |
509fd4 |
//
|
|
Packit |
63bb0d |
// Returns the current status of the job, in the form of three times:
|
|
Packit |
63bb0d |
// queued, started, and finished. `started` and `finished` might be the
|
|
Packit |
63bb0d |
// zero time (check with t.IsZero()), when the job is not running or
|
|
Packit |
63bb0d |
// finished, respectively.
|
|
Packit |
63bb0d |
//
|
|
Packit Service |
509fd4 |
// Lastly, the IDs of the jobs dependencies are returned.
|
|
Packit Service |
509fd4 |
JobStatus(id uuid.UUID) (result json.RawMessage, queued, started, finished time.Time, canceled bool, deps []uuid.UUID, err error)
|
|
Packit Service |
3a6627 |
|
|
Packit Service |
3a6627 |
// Job returns all the parameters that define a job (everything provided during Enqueue).
|
|
Packit Service |
3a6627 |
Job(id uuid.UUID) (jobType string, args json.RawMessage, dependencies []uuid.UUID, err error)
|
|
Packit |
63bb0d |
}
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
var (
|
|
Packit |
63bb0d |
ErrNotExist = errors.New("job does not exist")
|
|
Packit |
63bb0d |
ErrNotRunning = errors.New("job is not running")
|
|
Packit |
63bb0d |
ErrCanceled = errors.New("job ws canceled")
|
|
Packit |
63bb0d |
)
|