ジョブの仕様の詳細

ジョブの仕様 ¶

すべての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ファイルが既に生成されていれば、この作業は以下の操作で実行することができます:

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とマークされたジョブは、他のジョブが走っているマシンであろうとどのマシンでも走らせることができます。ただし、`single`タグが付いたジョブが走っているマシンは例外です。詳細は、ジョブのタグを参照してください。
description	文字列	ジョブの説明。
emailReasons	文字列	`emailTo`プロパティで指定したアドレスに電子メールを送信する理由のカンマ区切りのリスト。このプロパティの値が空っぽまたは指定なしの場合、電子メールは送信されません。有効な理由は、'abandoned', 'cancelled', 'ejected', 'ejecting', 'failed', 'paused', 'pausing', 'priority changed', 'queued', 'rescheduled', 'resumed', 'resuming', 'runnable', 'running', 'succeeded' , 'waiting'です。ジョブの電子メール系プロパティは、HQueueサーバーが電子メールを送信するように設定されている場合にのみ適用されます。サーバー設定のヘルプページの`error_email_from`と`smtp_server`の設定変数を参照してください。
emailTo	文字列	`emailReasosn`プロパティで指定した理由に基づいて電子メールを送信する宛先のカンマ区切りのリスト。ジョブの電子メール系プロパティは、HQueueサーバーが電子メールを送信するように設定されている場合にのみ適用されます。サーバー設定のヘルプページの`error_email_from`と`smtp_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_MSGとMSGを定義しています。そのコマンドセットは直接これらの2つの変数を参照します。ジョブはsingleタグとmaxHostsとminHostsのプロパティで定義されているように1台の専用マシンを必要とします。最後に“Hello World”を出力する1個の子ジョブを持ちます。

ジョブの条件 ¶

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

Note

ジョブに独自の条件設定が定義されていない場合は、自動的にルートジョブの条件が継承されます。

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

構成要素	説明
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。

ジョブの仕様の詳細