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にジョブがサブミットされてから完了するまでジョブのステータスが変わります。上記の例のような基本的なジョブでは以下の順番にジョブのステータスが変わります:
HQueueにジョブがサブミットされると、スケジュールキューにジョブが配置され、そこでクライアントマシンを 待ちます 。マシンが利用可能になるとジョブがマシンに割り当てられ、マシンがジョブのコマンドセットを 実行します 。ジョブのコマンドセットの実行がエラーなく終わると、ジョブは succeeded とマークが付けられます。
ジョブのステータスの完全なリストは、ジョブのステータスを参照してください。
親子関係 ¶
2つのジョブ間で、2番目のジョブが完了しないと1番目のジョブが実行できないような依存関係を設定することができます。この依存関係のことをHQueueでは親子関係と言います。例えば、ジョブAがジョブBに依存していれば、ジョブAがジョブBの 親 で、ジョブBがジョブAの 子 です。
単純な親子の例 ¶
Houdiniのシーンから X フレーム分のAVIビデオを作成すると仮定して、そのフレーム分のIFDファイルが既に生成されていれば、この作業は以下の操作で実行することができます:
-
Mantraを使ってIFDファイルからフレームをレンダリングします。
-
レンダリングした画像をビデオにエンコードします。
最初のステップでは、 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とマークされたジョブは、他のジョブが走っているマシンであろうとどのマシンでも走らせることができます。
ただし、 |
description |
文字列 |
ジョブの説明。 |
emailReasons |
文字列 |
ジョブの電子メール系プロパティは、HQueueサーバーが電子メールを送信するように設定されている場合にのみ適用されます。
サーバー設定のヘルプページの |
emailTo |
文字列 |
ジョブの電子メール系プロパティは、HQueueサーバーが電子メールを送信するように設定されている場合にのみ適用されます。
サーバー設定のヘルプページの |
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 |
整数 |
ジョブが失敗した後に成功しようと試みるのに自動的にスケジュールを変更する回数。 |
triesDifferentClient |
boolean |
タスクを自動的に別のクライアント上にスケジュール変更するかどうか。
このプロパティは |
resources |
辞書 |
ジョブで使用されるHQueueリソースの名前と使用される各リソースの度合いの値をペアにした辞書です。例えば、 |
ジョブプロパティの例 ¶
以下にいくつかのプロパティの使用方法を説明したジョブの仕様の例を載せています:
{ "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_MSG
とMSG
を定義しています。そのコマンドセットは直接これらの2つの変数を参照します。ジョブはsingle
タグとmaxHosts
とminHosts
のプロパティで定義されているように1台の専用マシンを必要とします。最後に“Hello World”を出力する1個の子ジョブを持ちます。
ジョブの条件 ¶
ジョブの条件は、HQueueスケジューラーにジョブを制限したクライアントマシンのセットに割り当てるように指示します。ジョブの条件はタイプ、名前、オペレータ、値を使って定義します。それらの条件を比較することで、ジョブを実行するマシンを決めます。クライアントマシンが設定した条件に すべて 合格すれば、そのマシンはそのジョブを実行することができます。
Note
ジョブは、そのジョブ自身の条件に加えてルートジョブの条件を自動的に継承します。
ジョブのinherit_conditions
プロパティをFalse
に設定することで、そのジョブがルートジョブの条件を継承しないようにすることができます。
以下にジョブの条件を設定する構成要素を説明します:
構成要素 |
説明 |
---|---|
type |
typeは何に対して条件を適用するのかを指定します。HQueueでは現時点でのクライアント条件のみをサポートするので、typeは常に“client”に設定しておきます。クライアントの条件は、ジョブをどのクライアントマシンに割り当てるのか決めます。 |
name |
テストするクライアントのプロパティの名前。対応している名前は以下の通り:
|
op |
条件の値に対してクライアントのアトリビュートをテストする時に使用する比較演算子です。対応している演算子は以下の通り:
|
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" }, ] }
ジョブのタグ ¶
ジョブのステータス ¶
以下にジョブのステータスとその説明のリストを載せます。
ステータス |
説明 |
---|---|
abandoned |
ジョブがクライアントマシンに割り当てられていますが、そのマシンはそのジョブの進捗状況やステータスを報告していません。これは、そのマシンが反応なし(要は、再起動、ハング)になると起こります。 |
cancelled |
ジョブがユーザによって中断されて、もはやスケジュールキューにありません。 |
failed |
ジョブが終了しましたが、コマンドセットの実行中またはその子ジョブの実行中にエラーが報告されました。 |
paused |
ジョブがユーザによって停止されました。ジョブが停止している間は、スケジューラーはジョブをクライアントマシンに割り当てません。ジョブが既にマシン上で実行中なら、その実行を停止します。 |
pausing |
ジョブがクライアントマシン上で実行中ですが、ユーザが実行を停止するように要求しました。HQueueサーバーはクライアントからのジョブを停止したことを確認した返事を待っています。 |
resuming |
ジョブがクライアントマシンに割り当てられていて、現在は停止していますが、ユーザによって実行を再開するように要求されています。HQueueサーバーはクライアントからのジョブを再開したことを確認した返事を待っています。 |
running |
ジョブがクライアントマシン上で実行されています。 |
running (X clients assigned) |
1つ以上の子ジョブが実行中で、子ジョブがX台のクライアントに割り当てられています。 |
succeeded |
ジョブが終了して、コマンド実行中にエラーが報告されませんでした。 |
waiting for resources |
ジョブを実行する準備ができていますが、利用可能なリソースを待っています。ここでいうリソースとは、 HQueueリソース, クライアントマシン, ジョブ条件が該当します。ジョブに子ジョブがない場合、そのジョブが待機中である正確な理由がツールチップに表示されます。 |
ジョブ変数 ¶
以下にジョブの環境で定義されているビルトイン、ランタイムの変数のリストを載せます。
環境変数 |
説明 |
---|---|
HQCLIENT |
ジョブを実行しているマシンのクライアントコードのフォルダパス。 |
HQCLIENTARCH |
ジョブを実行しているクライアントマシンのプラットフォーム。これはオペレーティングシステムとマシンのアーキテクチャで構成しています。以下の可能な値の簡単なリストを載せます:
|
HQHOSTS |
ジョブを実行しているマシン(s)の名前。 |
HQROOT |
HQueueに登録されているメインネットワークドライブのフォルダパス。 ネットワークフォルダの設定を参照してください。 |
HQSERVER |
HQueueサーバーのアドレス。これはHQueueサーバーのホスト名とサーバーが開くポート番号で構成しています。 |
JOBID |
現在のジョブのID。 |