Houdini 18.0 HQueue

Remote API package

You can connect to the HQueue server over the network and call functions to manipulate and query jobs and other information.

On this page

Overview

You can call functions on the Hqueue server through an XML/RPC client (from the same machine or over the network). You can use the server’s API to submit or query jobs.

XML/RPC is a simple language-agnostic standard for translating function calls and return values into HTTP requests and responses. Python comes with a built-in XML/RPC client library, so you don’t actually need to know anything about the protocol, it is simply the underlying technology that makes remote calls possible.

You can also connect and call functions on HQueue clients, however the API is quite limited.

Connecting to the server

In Python you can connect to the server using the xmlrpclib client library. (XML/RPC clients are available in other languages, however we will limit ourselves to showing Python on this page.)

import xmlrpclib

# Connect to the HQueue server
hq = xmlrpclib.ServerProxy("http://hq_server_hostname:5000")

The returned object acts as a proxy for the remote API: you can call function attributes on the object as if you were calling functions inside the remote HQueue server. See the list of available functions below.

If the connection is not valid, trying to call a function on the proxy will raise an exception:

try:
    hq.ping()
except:
    print("HQueue server is not working")

The following examples show how you call functions on the proxy object:

  • Submit a new job:

    # Define a job which renders an image from an IFD using Mantra.
    job_spec = {
        "name": "Render My Image",
        "shell": "bash",
        "command": (
            "cd $HQROOT/houdini_distros/hfs;"
            " source houdini_setup;"
            " mantra < $HQROOT/path/to/ifds/some_frame.ifd"
        )
    }
    
    job_ids = hq.newjob(job_spec)
    
  • You can use the Job ID(s) returned by newjob() to query job progress using getJob():

    job = hq_server.getJob(job_ids[0], ["progress", "status"])
    status = job["status"]
    
    print("The job status is", status)
    if status in hq.getRunningJobStatusNames():
        print("{:.2f}% complete".format(job["progress"] * 100.0))
    

Connecting to clients

HQueue clients also act as an XML/RPC API server. This allows you to call functions that force the client to send a heartbeat to the server, or cause the client to exit.

import xmlrpclib

# Connect to the HQueue client.
hq_client = xmlrpclib.ServerProxy("http://hq_client_hostname:5001")

The client API has two functions:

wakeup()

Wake up the client if it is sleeping and force it to send a hearbeat to the server.

terminate()

Request the client to terminate. Terminating a client results in the following:

  • Any paused jobs on the client are canceled.

  • New jobs cannot be assigned to the client.

  • Any jobs currently running on the client continue executing until they are complete.

  • The client is removed from the list of clients in the HQueue server.

  • Once all jobs on the client are finished, the client process exits.

Server API

Queue

Clients

Client groups

Job management

Job queries

Meta

Resources

See resources for more information.

Configuration

Notes

See how to use notes for more information.

Deprecated functions

HQueue

Getting started

  • About HQueue

    HQueue is a general-purpose job management system. You can use it to distribute renders, simulations, and other work to remote clients.

  • Installation

    How to set up a basic HQueue farm.

  • Configuration

    How to set configuration options for the HQueue server and clients.

  • How to submit jobs

    How to put work on the farm.

Managing the farm

  • Managing clients

    How to use the web interface or local logins to add, remove, restart, and manage client machines.

  • Managing jobs

    How to view and manage jobs on the farm.

  • Managing client groups

    How to use the web interface or local logins to create and manage groups of client machines.

  • Notes

    Each client and job can have informational notes attached.

  • Resources

    You can specify what resources (such as licenses) are available on each client, so jobs can be scheduled on clients where they can run.

  • Network Folders

    How to use the Network Folder management page.

Next steps

  • Logging

    Hqueue stores separate logs for errors and scheduling events, and each client also generates a log.

  • Uninstalling

    How to uninstall the HQueue server or client software.

  • FAQs

    Answers to frequently asked questions.

Guru level

  • Remote API

    You can connect to the HQueue server over the network and call functions to manipulate and query jobs and other information.

  • Jobs specification details

    More detail on the internals of a job specification for users who want to submit custom jobs.

  • Switching to MySQL (Linux only)

    You can optionally configure HQueue to use MySQL instead of SQLite on Linux.