Synopsis
All jobs in Qube! have a consistent structure. It is through this structure the Supervisor is able to communicate to the Worker the appropriate instructions for executing a job.
Job Type
The job's type is the mechanism by which Qube! indicates to the Worker what it should do with the job. When the Worker receives the job object from the Supervisor, it looks through its library of types to find one that matches. If it finds a match, it will examine the type's configuration file for guidance on which module to load in order to execute the job.Since the type is vital to the Worker correctly identifying an execution module, it is a mandatory job component. The qbsub
command will automatically set the type for you. If you are developing your own job types, it will become more important to explicitly set the job's type before submitting itFor example, a job with type "command line" will have discrete strings for each agenda item that will be run at a command prompt (e.g. "dir
", "ls
", "cinema4D -frame 1 5 1 -render /path/to/file.c4d
"). A job with type "maya" will, instead, store a discrete set of instructions for Maya for each agenda item that will be run at a mel prompt. In the case of the former, the application is launched when the agenda item starts and then exits when the agenda item is complete. In the case of the latter, the application is launched when the instance starts, but then does not exit until all agenda items in the job have been completed (either by this instance and/or others).
Job ID
Once a job has been submitted and accepted by the Supervisor, it is assigned an ID. The ID is unique to the job, and serves two purposes: it helps the Supervisor keep track of each job individually, and without any other priority information, the Supervisor can dispatch jobs in chronological ("first-come, first-served") order based upon the ID.
Job Parameters
Job parameters act as instructions to the Qube! Supervisor to help it determine how best to dispatch the job to the Workers. Each job can have any of several job parameters. From the command line, qbsub
will automatically create default parameters for your job submissions, in case you don't want or need to specify them. In the case of the CPUs parameter, qbsub
will submit a job with a default of 1The parameters are simply the values used in the submission dialog (or through the API or command line).
Job Package
...
Since each job type module is executed in exactly the same way by the Worker, there must be some way to communicate to the Worker how to execute it in the specific way you need. The package is how that is done. In general, the package is a generic data structure, included in the job object, that can be accessed by the Worker's backend job module and used by that module to set up the job.
The size and contents of the job package will vary between job types. In the case of jobs submitted via qbsub, the package will likely contain a simple command in the package variable "cmdline." However, in the case of a sophisticated rendering application, the package may contain the name of the scene and dozens of global values specific to the jobThe job package contains parameters that are specific to the application that is being rendered. For example, with a cmdline job, the package will contain the command to be executed and possibly the frame range. For a maya job, the package will contain the frame range, and things like the path to the maya scene file, the output path (if specified), the thread count, etc. Every job will have a package, but every package may be different, both in number and type of variables.
Job Agenda
The job agenda contains a number of discrete items – often frames – that are transmitted by the Supervisor to the Worker on an "as needed" basis. The agenda usually contains a name, which is often sufficient for most purposes. Each agenda item can contain a package, much like the job itself.Separating out the list of work to be done from the job itself at execution time can improve efficiency. Workers can ask for work as quickly as they can complete it. If a Worker fails to complete a work item, it can be easily reassigned to another Worker. Adding more CPUs to a job simply increases the number of possible work items executed simultaneously.An angeda could be considered synonymous with a task.
Job Callbacks
Callbacks are one of the most powerful features of Qube!, enabling it to perform well beyond other similar render farm management systems. Any event that takes place in the system can trigger the Supervisor to perform a series of actions; some are internal like activating a dormant job, others are external like sending out an email message .Unfortunately, a full discussion of the nuts and bolts of callbacks is beyond the scope of this document. While callbacks are mostly the province of the Qube! developer, as we will see, you can still take advantage of Qube!'s callback features, without actually creating a callback yourself.or executing a python script.
Instances
In reality, a job is a large data structure that contains all the information the Supervisor needs to monitor, control, and dispatch a task for a remote host. The actual execution of that task is performed by the Worker by what we call an instance (previously, these were called subjobs).
The instance contains all the relevant information relating to the actual execution of the job. Virtually all information regarding job execution is in reality instance information. Since the instance is a part of the job, the job acts as the clearing house for information about a job, including the instance. While that aspect of the job/instance relationship can sometime seem confusing, it becomes more evident with practice.
The best way to try to understand how instances relate to jobs is to work with them. The Worker will execute the instance by loading the type's module and running it with the appropriate package information.
All jobs must execute with at least one instance. Adding additional instances will cause the job to load the same module with the same package information. Now, this is often a desired outcome. You may want to run the same command on each host in your compute farm. However, if you don't want the same job to execute multiple times, you probably want to consider using the agenda to give each instance a little something different to perform. In other words, a worker runs one or more job instances in parallel and each instance runs one or more agenda items (typically frames) in series.