Houdini 20.0 HQueue

ジョブの仕様の詳細

独自のジョブを投入したいユーザ向けに、ジョブの内部仕様に関する詳細を載せています。

On this page

ジョブの仕様

すべてのHQueueジョブはジョブのプロパティを含んだJSON構造の仕様で定義されています。ここに単純な例を載せます:

{ 
    "name": "Print Hello World",
}

この例では、まさにジョブ名のプロパティを1つ持つジョブを定義しています。この仕様では、nameプロパティだけが必要なので有効な構文ですが、ジョブは何か役に立つことをせず、クライアントマシンにジョブを割り当てても、すぐに終了して何もしないで成功します。

クライアントにタスクを実行させるには、commandプロパティを使ってコマンドセットを追加する必要があります。例:

{ 
    "name": "Print Hello World",
    "command" : "echo 'Hello World!'",
}

ジョブがクライアントマシンに割り当てられると、マシンのオペレーティングシステムにインストールされているデフォルトのシェルを使って“Hello World!”を出力します。

特定のシェルでコマンドを実行する場合は、以下のようにshellプロパティを追加します:

{ 
    "name": "Print Hello World",
    "command" : "echo 'Hello World!'",
    "shell" : "bash",
}

複数のコマンドを1つのコマンドとして連結してジョブに保存すれば、それらのコマンドを連続して実行することができます。例:

{ 
    "name": "Multiple Print Commands",
    "command" : "echo 'The First Command' && echo 'The Second Command'",
}

コマンドの連結の方法はシェルに依存しますが、コマンドを&&で分けたり、コマンドの終わりに;を付ければ、ほとんどの場合で機能します。

複雑なコマンドセットに関しては、スクリプトファイルにコマンドを記述して、commandプロパティでそのスクリプトファイルを指定するのが簡単です。例:

{ 
    "name": "Running a Script",
    "command" : "/path/to/myScript.sh",
}

ジョブの仕様で定義可能なジョブのプロパティの完全なリストは、ジョブのプロパティを参照してください。

ステータスの変化

HQueueジョブは、HQueueにジョブがサブミットされてから完了するまでジョブのステータスが変わります。上記の例のような基本的なジョブでは以下の順番にジョブのステータスが変わります:

waiting for machine → running → succeeded

HQueueにジョブがサブミットされると、スケジュールキューにジョブが配置され、そこでクライアントマシンを 待ちます 。マシンが利用可能になるとジョブがマシンに割り当てられ、マシンがジョブのコマンドセットを 実行します 。ジョブのコマンドセットの実行がエラーなく終わると、ジョブは succeeded とマークが付けられます。

ジョブのステータスの完全なリストは、ジョブのステータスを参照してください。

親子関係

2つのジョブ間で、2番目のジョブが完了しないと1番目のジョブが実行できないような依存関係を設定することができます。この依存関係のことをHQueueでは親子関係と言います。例えば、ジョブAがジョブBに依存していれば、ジョブAがジョブBの で、ジョブBがジョブAの です。

単純な親子の例

Houdiniのシーンから X フレーム分のAVIビデオを作成すると仮定して、そのフレーム分のIFDファイルが既に生成されていれば、この作業は以下の操作で実行することができます:

  1. Mantraを使ってIFDファイルからフレームをレンダリングします。

  2. レンダリングした画像をビデオにエンコードします。

最初のステップでは、 X 個のHQueueジョブ(1フレーム1ジョブでレンダリングするジョブ)を定義することができます。1フレームをレンダリングするジョブの仕様は以下のように記述します:

{ 
    "name": "Render Frame 1",
    "command": 
    """cd $HQROOT/houdini_distros/hfs;
       source houdini_setup;
       mantra < $HQROOT/path/to/ifds/frame0001.ifd"""

    "shell": "bash",
}

残りのフレームのジョブの仕様も同様です。

Mantraが画像を$HQROOT/path/to/output/frame*.png($HQROOTとはHQueueに登録したメインネットワークフォルダのマウントポイントのことです)にレンダリングすると仮定すると、エンコードのステップのジョブの仕様は以下のように記述します:

{ 
    "name": "Encode Video",
    "shell": "bash",
    "command": "myEncoderApp --input=$HQROOT/path/to/output/frame*.png --output=$HQROOT/path/to/output/myVideo.avi"
}

エンコーディングジョブはすべてのレンダリングジョブが完了した後に実行するので、エンコーディングジョブをレンダリングジョブの親にして依存関係を作成します。

依存関係を作成するには、エンコーディングジョブの仕様にchildrenジョブプロパティを使います。childrenプロパティは子ジョブの仕様のリストを受け取ります。

そのことから、エンコーディングジョブの仕様は以下のようになります:

{ 
    "name": "Encode Video",
    "shell": "bash",
    "command": "myEncoderApp --input=$HQROOT/path/to/output/frame*.png --output=$HQROOT/path/to/output/myVideo.avi",
    "children": [
        {
            "name": "Render Frame 1",
            "shell": "bash",
            "command": 
            """cd $HQROOT/houdini_distros/hfs;
               source houdini_setup;
               mantra < $HQROOT/path/to/ifds/frame0001.ifd"""
        },
            "name": "Render Frame 2",
            "shell": "bash",
            "command": 
            """cd $HQROOT/houdini_distros/hfs;
               source houdini_setup;
               mantra < $HQROOT/path/to/ifds/frame0002.ifd"""
        },
            "name": "Render Frame 3",
            "shell": "bash",
            "command": 
            """cd $HQROOT/houdini_distros/hfs;
               source houdini_setup;
               mantra < $HQROOT/path/to/ifds/frame0003.ifd"""
        },
        .............................

    ]

}

親のステータス

親ジョブのステータスは、その子ジョブのステータスに依存します。子ジョブが完了した時に、少なくとも1つの子ジョブが失敗していれば、親ジョブのステータスは failed に設定され、親ジョブのコマンドセットが実行されません。子ジョブがすべて成功すれば、親ジョブのステータスは waiting for machine に設定され、スケジュールキューに配置されて、そこでクライアントマシンを待ちます。

親ジョブ内から子ジョブをサブミットする

実行中のジョブ内から子ジョブをサブミットすることが可能です。これは、必要な子ジョブの数が親ジョブを実行するまで分からないときに必要になるときがあります。そのような場合では、必要な子ジョブの数を計算して、子ジョブの仕様をHQueueサーバーにサブミットする親ジョブにコマンドを追加することができます。

子ジョブをサブミットするには、newjob()Python API関数(Python APIを参照)を使用します。

以下にPythonスクリプトの例を載せます。このスクリプトは新しくジョブを作成して、それを子ジョブとして現在実行中のジョブに割り当てます:

# -*- coding: utf-8 -*-
import os
import xmlrpclib

# HQueueサーバーに接続します。
hq_server = xmlrpclib.ServerProxy("http://hq_server_hostname:5000")

# 子ジョブを定義します。
child_job_spec = { 
    "name": "The Child Job",
    "shell": "bash",
    "command": "echo 'Hello World!'" 
}

# 現在のジョブのIDを取得します。
# それは、HQueueがJOBID環境変数で自動的に定義します。
current_job_id = os.environ["JOBID"]

# ジョブをサーバーにサブミットします。
# newjob()は、ジョブのIDをリストで返します(同時に複数のジョブを渡す場合)。
job_ids = hq_server.newjob(child_job_spec, current_job_id)

スクリプトをファイルに保存するなら、ファイル名をcreateChild.pyとしましょう。次に、それを親ジョブのcommandプロパティに追加します。そうすると、親ジョブの仕様は以下のようになります:

{ 
    "name": "The Parent Job",
    "shell": "bash",
    "command": "python $HQROOT/path/to/scripts/createChild.py"
}

コマンドなしのジョブ

必要なプロパティがnameプロパティだけであれば、commandプロパティのないジョブを定義することが可能です。

コマンドなしのジョブは何も実行しませんが、時々役に立つ場合があります。例えば、ジョブをHQueueにサブミットするPythonスクリプトを記述する時に、コマンドなしのジョブを使えば、ファームに実際の作業の負担をさせることなくnewjob()のコールをテストすることができます。また、コマンドなしのジョブをいくつかの独立したジョブ(依存関係のあるジョブではなく)の“コンテナ”として使用することができます。これはHQueue Webインターフェースで体系化するメリットがあります。なぜなら、依存関係のある子ジョブで生成された作業を1個のジョブ下に表示することができるからです。

ジョブのプロパティ

以下にジョブの仕様に追加可能なプロパティのリストを載せます。

プロパティ名

プロパティのタイプ

プロパティの値

children

ジョブの仕様のリスト/タプル

子ジョブとしてサブミットして割り当てられるジョブの仕様。

childrenIds

整数のリスト/タプル

子ジョブとして割り当てられる既存ジョブのID。

command

文字列

割り当てたマシンで実行するシェルコマンドのセット。

conditions

文字列のリスト/タプル

ジョブを割り当てるマシンを選択する時にHQueueスケジューラーが従わなければならない条件。詳細は、ジョブの条件を参照してください。

cpus

整数

ジョブが使用するCPUの最小個数。デフォルトは1です。

Note

0 cpusとマークされたジョブは、他のジョブが走っているマシンであろうとどのマシンでも走らせることができます。 ただし、singleタグが付いたジョブが走っているマシンは例外です。 詳細は、ジョブのタグを参照してください。

description

文字列

ジョブの説明。

emailReasons

文字列

emailToプロパティで指定したアドレスに電子メールを送信する理由のカンマ区切りのリスト。このプロパティの値が空っぽまたは指定なしの場合、電子メールは送信されません。有効な理由は、'abandoned', 'cancelled', 'ejected', 'ejecting', 'failed', 'paused', 'pausing', 'priority changed', 'queued', 'rescheduled', 'resumed', 'resuming', 'runnable', 'running', 'succeeded' , 'waiting'です。

ジョブの電子メール系プロパティは、HQueueサーバーが電子メールを送信するように設定されている場合にのみ適用されます。 サーバー設定のヘルプページのerror_email_fromsmtp_serverの設定変数を参照してください。

emailTo

文字列

emailReasosnプロパティで指定した理由に基づいて電子メールを送信する宛先のカンマ区切りのリスト。

ジョブの電子メール系プロパティは、HQueueサーバーが電子メールを送信するように設定されている場合にのみ適用されます。 サーバー設定のヘルプページのerror_email_fromsmtp_serverの設定変数を参照してください。

environment

辞書

ジョブのコマンドセットを実行した時にクライアントの環境で定義する変数の辞書。辞書のキーと値は、変数名とその値に対応します。

host

文字列

ジョブが実行されるマシンのホスト名。このプロパティを設定しなかった場合は、任意のマシンでジョブが実行されます。

inherit_conditions

boolean

ジョブをルートジョブの条件に従わせるかどうか。ジョブ自体が条件を持っていれば、このプロパティは無視されます。デフォルトはTrueです。

onCancel

文字列

ジョブがクライアントマシンで実行中の時にキャンセルされた場合に実行する一連のシェルコマンド。

onError

文字列

ジョブが失敗した時に実行する一連のシェルコマンド。

onChildError

文字列

ジョブの子ジョブが失敗した場合に実行する一連のシェルコマンド。これらのコマンドは、すべての子ジョブが終了し、そのジョブがコマンドセットを実行した後に実行されます。ジョブが既にクライアントマシンに割り当てられている場合、そのジョブはそのクライアント上で継続され、そのクライアントを使ってonChildErrorコマンドが実行されることに注意してください。

onReschedule

string

ジョブのスケジュールが変更された場合に実行する一連のシェルコマンド。これらのコマンドは、ジョブが実行される前に実行されます。

onSuccess

文字列

ジョブが成功して完了した時に実行する一連のシェルコマンド。

maxHosts

整数

ジョブを割り当てることが許可されているクライアントマシンの最大数。デフォルトは1です。

maxTime

整数

ジョブの実行を許可する最大時間(秒)。ジョブがこの最大時間を超えると、自動的にHQueueでキャンセルされます。このプロパティを指定しなかった場合、または、0未満の時間に設定した場合、そのジョブには最大時間が設定されず、無期限に実行されることに注意してください。

minHosts

整数

ジョブを割り当てることが許可されているクライアントマシンの最小数。デフォルトは1です。

name

文字列

ジョブの名前。

priority

整数

ジョブの優先度。高い優先度のジョブが低い優先度のジョブよりも先にクライアントに割り当てられます。0が一番低い優先度です。デフォルトは0です。

shell

文字列

ジョブのコマンドセットを実行するときに使用するターミナルシェル。

submittedBy

文字列

ジョブをサブミットした人の名前。子ジョブに関しては、この値を指定しなかった場合は、親ジョブから名前を引き継ぎます。

tags

文字列のリスト/タプル

ジョブに適用するタグのリスト。タグは、ジョブが専用マシンを必要とするのか他の実行中のジョブとマシンを共有できるのか制御するために使用します。詳細は、ジョブのタグを参照してください。

triesLeft

整数

ジョブが失敗した後に成功しようと試みるのに自動的にスケジュールを変更する回数。triesLeftの回数の次にジョブが失敗すると、ジョブが failed とマークされます。デフォルト値は0です。

triesDifferentClient

boolean

タスクを自動的に別のクライアント上にスケジュール変更するかどうか。 このプロパティはjob.triesLeft > 0の時に役立ちます。デフォルトはFalseです。

resources

辞書

ジョブで使用されるHQueueリソースの名前と使用される各リソースの度合いの値をペアにした辞書です。例えば、{"sidefx.license.houdini": 1, "custom_one": 2}です。詳細は、リソースのヘルプページを参照してください。

ジョブプロパティの例

以下にいくつかのプロパティの使用方法を説明したジョブの仕様の例を載せています:

{ 
    "name": "The Main Job",
    "shell": "bash",
    "environment": { 
        "SHOW_MSG": "1", 
        "MSG": "Hello World!" 
    }, 
    "command":  
    """if [ $SHOW_MSG = 1 ]; then 
           echo $MSG; 
    fi""",
    "tags": [ "single" ], 
    "maxHosts": 1, 
    "minHosts": 1, 
    "priority": 0, 
    "children": [ 
        { 
            "name": "The Child Job",
            "shell": "bash",
            "command": "echo 'Hello World!'" 
        }
    ] 
}

上記の例では、優先度0の’The Main Job'という名前のジョブを定義しています。これはbashシェルを使ってコマンドセットを実行し、2つの環境変数SHOW_MSGMSGを定義しています。そのコマンドセットは直接これらの2つの変数を参照します。ジョブはsingleタグとmaxHostsminHostsのプロパティで定義されているように1台の専用マシンを必要とします。最後に“Hello World”を出力する1個の子ジョブを持ちます。

ジョブの条件

ジョブの条件は、HQueueスケジューラーにジョブを制限したクライアントマシンのセットに割り当てるように指示します。ジョブの条件はタイプ、名前、オペレータ、値を使って定義します。それらの条件を比較することで、ジョブを実行するマシンを決めます。クライアントマシンが設定した条件に すべて 合格すれば、そのマシンはそのジョブを実行することができます。

Note

ジョブは、そのジョブ自身の条件に加えてルートジョブの条件を自動的に継承します。 ジョブのinherit_conditionsプロパティをFalseに設定することで、そのジョブがルートジョブの条件を継承しないようにすることができます。

以下にジョブの条件を設定する構成要素を説明します:

構成要素

説明

type

typeは何に対して条件を適用するのかを指定します。HQueueでは現時点でのクライアント条件のみをサポートするので、typeは常に“client”に設定しておきます。クライアントの条件は、ジョブをどのクライアントマシンに割り当てるのか決めます。

name

テストするクライアントのプロパティの名前。対応している名前は以下の通り:

  • hostname - クライアントのホスト名に対してテストします。

  • hostname:name - クライアントのホスト名と名前に対してテストします。同一マシン上で複数クライアントを起動させたファームでは、同じホスト名のクライアント(要するに、同一マシン上で起動しているクライアント)間で特定のクライアントを指定するには、これを使用してください。

  • group - クライアントのグループのメンバーに対してテストします。

op

条件の値に対してクライアントのアトリビュートをテストする時に使用する比較演算子です。対応している演算子は以下の通り:

  • == - クライアントのアトリビュートが条件の値に一致すればtrueを返します。

  • != - クライアントのアトリビュートが条件の値に一致しなければtrueを返します。

  • in - クライアントのアトリビュートが条件の値のどれかに一致すればtrueを返します。この比較演算子を使用するときは、条件の値にカンマ区切りで複数の値を指定します。

  • not_in - クライアントのアトリビュートが条件の値のどれにも一致しなければtrueを返します。この比較演算子を使用するときは、条件の値にカンマ区切りで複数の値を指定します。

  • any - 廃止されました。代わりに“in”を使用してください。

value

設定したクライアントアトリビュートに対してテストする値。条件オペレータが“any”ならば、値はカンマで区切った複数アイテムのリストになります。

ジョブの条件の例

以下にジョブの仕様に条件を追加する方法を説明した例を載せます:

{
    "name": "A Job with Conditions",
    "shell": "bash",
    "command": "echo 'I should be running on either machine1 or machine2!'",
    "conditions": [
        { 
            "type" : "client", 
            "name": "hostname", 
            "op": "in", 
            "value": "machine1,machine2"
        },
    ]
}

上記の例では、クライアントマシンの名前が“machine1”または“machine2”のどれかにのみジョブを割り当てます。conditionsプロパティは、4つの構成要素で定義した辞書のリストであることに注目してください。

次の例では、“Simulation”グループのメンバーのクライアントマシンにのみジョブを割り当てる条件を設定する方法を説明しています:

{
    "name": "A Job for the Simulation Group",
    "shell": "bash",
    "command": "echo 'I should be running on a machine that is a member of the Simulation group!'",
    "conditions": [
        { 
            "type" : "client", 
            "name": "group", 
            "op": "==", 
            "value": "Simulation"
        },
    ]
}

ジョブのタグ

タグは、ジョブが専用マシンを必要とするのか他の実行中のジョブとマシンを共有できるのか制御するために使用します。タグを指定しなければ、マシンのCPUが十分ある限りジョブを実行するマシンを共有するようにジョブを設定します。

ジョブが専用マシンを必要とするように定義するなら、singleタグをtagsプロパティに追加します。 それ以外のジョブは、singleタグが付いたジョブを走らせているマシン上で走らなくなります。

独自のsingleタグを作成して、実行中のジョブのどのセットがマシンを共有して、どのセットが共有できないのか制御することもできます。 同じ独自のsingleタグが付いた2つのジョブは、同時に同じマシン上で走りません。

独自のsingleタグを作成するには、単純にsingleのタグ名に接尾辞を加えるだけです。

例えば、AとBの2つのジョブを作成して、それらのジョブにsingle:1という名前の独自singleタグを割り当てたとします。 そして、さらにCとDの2つのジョブを作成して、それらのジョブにsingle:2という別の名前の独自singleタグを割り当てたとします。 すると、ジョブAとBは同時に同じマシン上で実行することができず、同様にジョブCとDも同時に同じマシン上で実行することができません。 しかし、ジョブAまたはBはジョブCまたはDを実行しているマシン上では同時に実行することができます。逆も同様です。

ジョブのステータス

以下にジョブのステータスとその説明のリストを載せます。

ステータス

説明

abandoned

ジョブがクライアントマシンに割り当てられていますが、そのマシンはそのジョブの進捗状況やステータスを報告していません。これは、そのマシンが反応なし(要は、再起動、ハング)になると起こります。

cancelled

ジョブがユーザによって中断されて、もはやスケジュールキューにありません。

failed

ジョブが終了しましたが、コマンドセットの実行中またはその子ジョブの実行中にエラーが報告されました。

paused

ジョブがユーザによって停止されました。ジョブが停止している間は、スケジューラーはジョブをクライアントマシンに割り当てません。ジョブが既にマシン上で実行中なら、その実行を停止します。

pausing

ジョブがクライアントマシン上で実行中ですが、ユーザが実行を停止するように要求しました。HQueueサーバーはクライアントからのジョブを停止したことを確認した返事を待っています。

resuming

ジョブがクライアントマシンに割り当てられていて、現在は停止していますが、ユーザによって実行を再開するように要求されています。HQueueサーバーはクライアントからのジョブを再開したことを確認した返事を待っています。

running

ジョブがクライアントマシン上で実行されています。

running (X clients assigned)

1つ以上の子ジョブが実行中で、子ジョブがX台のクライアントに割り当てられています。

succeeded

ジョブが終了して、コマンド実行中にエラーが報告されませんでした。

waiting for resources

ジョブを実行する準備ができていますが、利用可能なリソースを待っています。ここでいうリソースとは、 HQueueリソース, クライアントマシン, ジョブ条件が該当します。ジョブに子ジョブがない場合、そのジョブが待機中である正確な理由がツールチップに表示されます。

ジョブ変数

以下にジョブの環境で定義されているビルトイン、ランタイムの変数のリストを載せます。

環境変数

説明

HQCLIENT

ジョブを実行しているマシンのクライアントコードのフォルダパス。

HQCLIENTARCH

ジョブを実行しているクライアントマシンのプラットフォーム。これはオペレーティングシステムとマシンのアーキテクチャで構成しています。以下の可能な値の簡単なリストを載せます:

  • linux-x86_64 → Linux 64ビット

  • macosx-arm64 → MacOS Silicon 64ビット

  • macosx-x86_64 → MacOS Intel 64ビット

  • windows-x86_64 → Windows 64ビット

HQHOSTS

ジョブを実行しているマシン(s)の名前。

HQROOT

HQueueに登録されているメインネットワークドライブのフォルダパス。

ネットワークフォルダの設定を参照してください。

HQSERVER

HQueueサーバーのアドレス。これはHQueueサーバーのホスト名とサーバーが開くポート番号で構成しています。

JOBID

現在のジョブのID。

HQueue

はじめよう

  • HQueueについて

    HQueueは多目的なジョブスケジューリングシステムです。このシステムを利用することで、レンダリング、シミュレーション、他の処理をリモートクライアント上に分散させることができます。

  • インストール

    基本的なHQueueファームのセットアップ方法。

  • 設定

    HQueueサーバーとクライアントのオプションを設定する方法。

  • ジョブを投入する方法

    ファーム上にワークを配置する方法。

ファームの管理

  • ジョブの管理

    ファーム上のジョブを閲覧/管理する方法。

  • クライアントの管理

    ウェブインターフェースまたはローカルログインを使って、クライアントマシンを追加/削除/再起動/管理する方法。

  • クライアントグループの管理

    ウェブインターフェースまたはローカルログインを使って、クライアントマシンのグループを作成/管理する方法。

  • ネットワークフォルダ

    Network Folder管理ページの使い方。

  • リソース

    各クライアントで利用可能なリソース(例えば、ライセンス)を指定することができるので、そのジョブを実行可能なクライアントに対してそのジョブのスケジュールを組むことができます。

  • ノート

    各クライアントとジョブには、情報を記載したノートを添付することができます。

次のステップ

  • ログ

    HQueueサーバーはサーバーエラーとスケジュールイベントのログを別々に記録し、各クライアントもログを生成します。

  • アンインストールする方法

    HQueueサーバーまたはクライアントのソフトウェアをアンインストールする方法。

  • FAQs

    よくある質問の回答。

導師レベル

  • Remote API

    ネットワーク上のHQueueサーバーに接続して関数をコールすることで、ジョブや他の情報を制御したり照会することができます。

  • ジョブの仕様の詳細

    独自のジョブを投入したいユーザ向けに、ジョブの内部仕様に関する詳細を載せています。

  • 複数クライアント、単一マシン

    単一マシン上で複数のHQueueクライアントを走らせる方法を説明したガイド。