Houdini 20.5 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 3 you can connect to the server using the xmlrpc.client library (In Python 2 this was called xmlrpclib). XML/RPC clients are available in other languages, however we will limit ourselves to showing Python on this page.

import xmlrpc.client

# Connect to the HQueue server
hq = xmlrpc.client.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 ConnectionRefusedError:
    print("HQueue server is not available")

Note

Check the XML/RPC client library documentation to see what kind of exceptions it will raise.

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

  • Submit a new job:

    # Define a job that 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 xmlrpc.client

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

Client API

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 scheduling 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 jobs

    How to view and manage jobs on the farm.

  • Managing clients

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

  • Managing client groups

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

  • Network Folders

    How to use the Network Folder management page.

  • 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.

  • Notes

    Each client and job can have informational notes attached.

Next steps

  • Logging

    HQueue stores separate logs for server 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