Job Submit Plugin API

Overview

This document describes Slurm job submit plugins and the API that defines them. It is intended as a resource to programmers wishing to write their own Slurm job submit plugins. This is version 100 of the API.
このドキュメントでは、Slurmジョブ送信プラグインとそれらを定義するAPIについて説明します。独自のSlurmジョブ送信プラグインを作成したいプログラマーへのリソースとして意図されています。これはAPIのバージョン100です。

Slurm job submit plugins must conform to the Slurm Plugin API with the following specifications:
Slurmジョブ送信プラグインは、次の仕様のSlurm Plugin APIに準拠している必要があります。

const char plugin_name[]="full text name"

A free-formatted ASCII text string that identifies the plugin.
プラグインを識別する自由形式のASCIIテキスト文字列。

const char plugin_type[]="major/minor"

The major type must be "job_submit." The minor type can be any suitable name for the type of job submission package. We include samples in the Slurm distribution for
主なタイプは「job_submit」である必要があります。マイナータイプは、ジョブ送信パッケージのタイプに適した任意の名前にすることができます。サンプルをSlurmディストリビューションに含めます。

• all_partitions — Set default partition to all partitions on the cluster.
  all_partitions —デフォルトのパーティションをクラスター上のすべてのパーティションに設定します。
  
• defaults — Set default values for job submission or modify requests.
  defaults —ジョブの送信またはリクエストの変更のデフォルト値を設定します。
  
• logging — Log select job submission and modification parameters.
  ロギング—ジョブのサブミットと変更のパラメータを選択して記録します。
  
• lua — Interface to Lua scripts implementing these functions (actually a slight variation of them). Sample Lua scripts can be found with the Slurm distribution in the directory contribs/lua. The default installation location of the Lua scripts is the same location as the Slurm configuration file, slurm.conf.
  lua —これらの機能を実装するLuaスクリプトへのインターフェース（実際にはそれらのわずかなバリエーション）。Luaスクリプトのサンプルは、Slurmディストリビューションのcontribs / luaディレクトリにあります。Luaスクリプトのデフォルトのインストール場所は、Slurm構成ファイルslurm.confと同じ場所です。
  
• partition — Sets a job's default partition based upon job submission parameters and available partitions.
  partition —ジョブ送信パラメータと使用可能なパーティションに基づいて、ジョブのデフォルトパーティションを設定します。
  

const uint32_t plugin_version
If specified, identifies the version of Slurm used to build this plugin and any attempt to load the plugin from a different version of Slurm will result in an error.
指定した場合、このプラグインのビルドに使用されたSlurmのバージョンを識別し、異なるバージョンのSlurmからプラグインをロードしようとすると、エラーが発生します。
If not specified, then the plugin may be loaded by Slurm commands and daemons from any version, however this may result in difficult to diagnose failures due to changes in the arguments to plugin functions or changes in other Slurm functions used by the plugin.
指定されていない場合、プラグインはSlurmコマンドとデーモンによって任意のバージョンから読み込まれる可能性がありますが、プラグイン関数の引数の変更やプラグインで使用される他のSlurm関数の変更が原因で、障害の診断が困難になる可能性があります。

Slurm can be configured to use multiple job_submit plugins if desired, however the lua plugin will only execute one lua script named "job_submit.lua" located in the default script directory (typically the subdirectory "etc" of the installation directory).
Slurmは、必要に応じて複数のjob_submitプラグインを使用するように構成できますが、luaプラグインは、デフォルトのスクリプトディレクトリ（通常、インストールディレクトリのサブディレクトリ "etc"）にある "job_submit.lua"という名前の1つのluaスクリプトのみを実行します。

API Functions

All of the following functions are required. Functions which are not implemented must be stubbed.
以下の機能がすべて必要です。実装されていない関数はスタブする必要があります。

int init (void)

Description:
Called when the plugin is loaded, before any other functions are called. Put global initialization here.
プラグインがロードされたとき、他の関数が呼び出される前に呼び出されます。ここにグローバル初期化を配置します。

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

void fini (void)

Description:
Called when the plugin is removed. Clear any allocated storage here.
プラグインが削除されたときに呼び出されます。ここで割り当て済みのストレージをすべてクリアします。

Returns: None.

Note: These init and fini functions are not the same as those described in the dlopen (3) system library. The C run-time system co-opts those symbols for its own initialization. The system _init() is called before the Slurm init(), and the Slurm fini() is called before the system's _fini().
注：これらのinitおよびfini関数は、dlopen（3）システムライブラリで説明されているものと同じではありません。Cランタイムシステムは、これらのシンボルを独自の初期化用にco-optします。システムの_init（）はSlurm init（）の前に呼び出され、Slurm fini（）はシステムの_fini（）の前に呼び出されます。

int job_submit(struct job_descriptor *job_desc, uint32_t submit_uid, char **error_msg)

Description:
This function is called by the slurmctld daemon with job submission parameters supplied by the salloc, sbatch or srun command. It can be used to log and/or modify the job parameters supplied by the user as desired. Note that this function has access to the slurmctld's global data structures, for example to examine the available partitions, reservations, etc.
この関数は、slurmctldデーモンによって呼び出され、salloc、sbatch、またはsrunコマンドによって提供されるジョブ送信パラメーターが指定されます。必要に応じて、ユーザーが指定したジョブパラメータをログに記録したり変更したりするために使用できます。この関数は、slurmctldのグローバルデータ構造にアクセスできることに注意してください。たとえば、利用可能なパーティションや予約などを調べることができます。

Arguments:
job_desc (input/output) the job allocation request specifications.
submit_uid (input) user ID initiating the request.
error_msg (output) If the argument is not null, then a plugin generated error message can be stored here. The error message is expected to have allocated memory which Slurm will release using the xfree function. The error message is always propagated to the caller, no matter the return code.
job_desc（入力/出力）ジョブ割り当て要求の仕様.submit_uid（入力）要求を開始するユーザーID.error_msg（出力）引数がnullでない場合、プラグインで生成されたエラーメッセージをここに格納できます。エラーメッセージには、Slurmがxfree関数を使用して解放するメモリが割り当てられていると予想されます。エラーメッセージは、リターンコードに関係なく、常に呼び出し元に伝播されます。

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int job_modify(struct job_descriptor *job_desc, job_record_t *job_ptr, uint32_t modify_uid)

Description:
This function is called by the slurmctld daemon with job modification parameters supplied by the scontrol or sview command. It can be used to log and/or modify the job parameters supplied by the user as desired. Note that this function has access to the slurmctld's global data structures, for example to examine the available partitions, reservations, etc.
この関数は、scontrolコマンドまたはsviewコマンドによって提供されるジョブ変更パラメーターを使用して、slurmctldデーモンによって呼び出されます。必要に応じて、ユーザーが指定したジョブパラメータをログに記録したり変更したりするために使用できます。この関数は、slurmctldのグローバルデータ構造にアクセスできることに注意してください。たとえば、利用可能なパーティションや予約などを調べることができます。

Arguments:
job_desc (input/output) the job allocation request specifications.
job_desc（入力/出力）ジョブ割り振り要求仕様。

job_ptr (input/output) slurmctld daemon's current data structure for the job to be modified.
job_ptr（入力/出力）slurmctldデーモンの変更するジョブの現在のデータ構造。

modify_uid (input) user ID initiating the request.
要求を開始するmodify_uid（入力）ユーザーID。

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

Lua Functions

The Lua functions differ slightly from those implemented in C for better ease of use. Sample Lua scripts can be found with the Slurm distribution in the directory contribs/lua. The default installation location of the Lua scripts is the same location as the Slurm configuration file, slurm.conf. Reading and writing of job environment variables using Lua is possible by referencing the environment variables as a data structure containing named elements. For example:
Lua関数は、使いやすさのためにCで実装されているものとは少し異なります。Luaスクリプトのサンプルは、Slurmディストリビューションのcontribs / luaディレクトリにあります。Luaスクリプトのデフォルトのインストール場所は、Slurm構成ファイルslurm.confと同じ場所です。Luaを使用したジョブ環境変数の読み取りと書き込みは、名前付き要素を含むデータ構造として環境変数を参照することで可能です。例えば：

if (job_desc.environment.LANGUAGE == "en_US") then
....

int slurm_job_submit(job_desc_msg_t *job_desc, List part_list, uint32_t submit_uid)

Description:
This function is called by the slurmctld daemon with job submission parameters supplied by the salloc, sbatch or srun command. It can be used to log and/or modify the job parameters supplied by the user as desired. Note that this function has access to the slurmctld's global data structures, for example to examine the available partitions, reservations, etc.
この関数は、slurmctldデーモンによって呼び出され、salloc、sbatch、またはsrunコマンドによって提供されるジョブ送信パラメーターが指定されます。必要に応じて、ユーザーが指定したジョブパラメータをログに記録したり変更したりするために使用できます。この関数は、slurmctldのグローバルデータ構造にアクセスできることに注意してください。たとえば、利用可能なパーティションや予約などを調べることができます。

Arguments:
job_desc (input/output) the job allocation request specifications.
job_desc（入力/出力）ジョブ割り振り要求仕様。

part_list (input) List of pointer to partitions which this user is authorized to use.
part_list（入力）このユーザーが使用を許可されているパーティションへのポインターのリスト。

submit_uid (input) user ID initiating the request.
submit_uid（入力）要求を開始するユーザーID。

Returns:
slurm.SUCCESS — Job submission accepted by plugin.
slurm.SUCCESS —プラグインによって受け入れられたジョブの送信。

slurm.FAILURE — Job submission rejected due to error (Deprecated in 19.05).
slurm.FAILURE —エラーが原因でジョブの送信が拒否されました（19.05で非推奨）。

slurm.ERROR — Job submission rejected due to error.
slurm.ERROR —エラーが原因でジョブの送信が拒否されました。

slurm.ESLURM_ACCESS_DENIED — Job submission rejected due to access denied.
slurm.ESLURM_ACCESS_DENIED —アクセスが拒否されたため、ジョブの送信が拒否されました。

slurm.ESLURM_ACCOUNTING_POLICY — Job submission rejected due to accounting policy.
slurm.ESLURM_ACCOUNTING_POLICY —アカウンティングポリシーが原因でジョブの送信が拒否されました。

slurm.ESLURM_INVALID_ACCOUNT — Job submission rejected due to invalid account.
slurm.ESLURM_INVALID_ACCOUNT —アカウントが無効なため、ジョブの送信が拒否されました。

slurm.ESLURM_INVALID_LICENSES — Job submission rejected due to access licenses.
slurm.ESLURM_INVALID_LICENSES —アクセスライセンスが原因でジョブの送信が拒否されました。

slurm.ESLURM_INVALID_TIME_LIMIT — Job submission rejected due to invalid time limit.
slurm.ESLURM_INVALID_TIME_LIMIT —時間制限が無効なため、ジョブの送信が拒否されました。

slurm.ESLURM_JOB_MISSING_SIZE_SPECIFICATION — Job submission rejected due to missing size specification.
slurm.ESLURM_JOB_MISSING_SIZE_SPECIFICATION —サイズ指定がないためにジョブの送信が拒否されました。

slurm.ESLURM_MISSING_TIME_LIMIT — Job submission rejected due to missing time limit.
slurm.ESLURM_MISSING_TIME_LIMIT —時間制限がないためにジョブの送信が拒否されました。

int slurm_job_modify(job_desc_msg_t *job_desc, job_record_t *job_ptr, List part_list, int modify_uid)

Description:
This function is called by the slurmctld daemon with job modification parameters supplied by the scontrol or sview command. It can be used to log and/or modify the job parameters supplied by the user as desired. Note that this function has access to the slurmctld's global data structures, for example to examine the available partitions, reservations, etc.
この関数は、scontrolコマンドまたはsviewコマンドによって提供されるジョブ変更パラメーターを使用して、slurmctldデーモンによって呼び出されます。必要に応じて、ユーザーが指定したジョブパラメータをログに記録したり変更したりするために使用できます。この関数は、slurmctldのグローバルデータ構造にアクセスできることに注意してください。たとえば、利用可能なパーティションや予約などを調べることができます。

Arguments:
job_desc (input/output) the job allocation request specifications.
job_desc（入力/出力）ジョブ割り振り要求仕様。

job_ptr (input/output) slurmctld daemon's current data structure for the job to be modified.
job_ptr（入力/出力）slurmctldデーモンの変更するジョブの現在のデータ構造。

part_list (input) List of pointer to partitions which this user is authorized to use.
part_list（入力）このユーザーが使用を許可されているパーティションへのポインターのリスト。

modify_uid (input) user ID initiating the request.
要求を開始するmodify_uid（入力）ユーザーID。

Returns:
Returns from job_modify() are the same as the returns from job_submit().
job_modify（）からの戻りは、job_submit（）からの戻りと同じです。

Lua Job Attributes

The available job attributes change occasionally with different versions of Slurm. To find the job attributes that are available for the version of Slurm you're using, go to the SchedMD github page, and navigate to src/plugins/job_submit/lua/job_submit_lua.c. _job_rec_field() contains the list of attributes available for the job_record (e.g. current record in Slurm). _get_job_req_field() contains the list of attributes available for the job_descriptor (e.g. submission or modification request).
使用可能なジョブ属性は、Slurmのバージョンによって異なる場合があります。使用しているSlurmのバージョンで使用できるジョブ属性を見つけるには、SchedMD githubページに移動し、src / plugins / job_submit / lua / job_submit_lua.cに移動します。_job_rec_field（）には、job_record（たとえば、Slurmの現在のレコード）で使用可能な属性のリストが含まれています。_get_job_req_field（）には、job_descriptorに使用できる属性のリストが含まれています（送信要求や変更要求など）。

Building

Generally using a LUA interface for a job submit plugin is best: It is simple to write and maintain with minimal dependencies upon the Slurm data structures. However using C does provide a mechanism to get more information than available using LUA including full access to all of the data structures and functions in the slurmctld daemon. The simplest way to build a C program would be to just replace one of the job submit plugins included in the Slurm distribution with your own code (i.e. use a patch with your own code). Then just build and install Slurm with that new code. Building a new plugin outside of the Slurm distribution is possible, but far more complex. It also requires access to a multitude of Slurm header files as shown in the procedure below.
一般に、ジョブサブミットプラグインにはLUAインターフェイスを使用するのが最適です。Slurmデータ構造への依存を最小限に抑えて記述および保守するのは簡単です。ただし、Cを使用すると、slurmctldデーモンのすべてのデータ構造と機能へのフルアクセスを含め、LUAを使用して入手できるよりも多くの情報を取得するメカニズムが提供されます。Cプログラムを構築する最も簡単な方法は、Slurmディストリビューションに含まれているジョブ送信プラグインの1つを独自のコードで置き換えることです（つまり、独自のコードでパッチを使用する）。次に、その新しいコードでSlurmをビルドしてインストールします。Slurmディストリビューションの外部で新しいプラグインをビルドすることは可能ですが、はるかに複雑です。また、以下の手順に示すように、多数のSlurmヘッダーファイルにアクセスする必要があります。

# Example:
# The Slurm source is in ~/SLURM/slurm.git
# The Slurm build directory is ~/SLURM/slurm.build
# The plugin build is to take place in the directory
#   "~/SLURM/my_submit"
# The installation location is "/usr/local"

# Build Slurm from ~/SLURM/slurm.build
# (or at least run "~/SLURM/slurm.git/configure")

# Set up your plugin files
cd ~/SLURM
mkdir my_submit
cd my_submit
mkdir .libs
mkdir .deps
# Create your plugin code
vi job_submit_mine.c

# Copy up a dependency file
cp ~/SLURM/slurm.build/src/plugins/job_submit/partition/.deps/job_submit_partition.Plo \
   .deps/job_submit_mine.Plo

# Compile
gcc -DHAVE_CONFIG_H -I~/SLURM/slurm.build -I~/slurm.git \
   -g -O2 -pthread -fno-gcse -Werror -Wall -g -O0       \
   -fno-strict-aliasing -MT job_submit_mine.lo          \
   -MD -MP -MF .deps/job_submit_mine.Tpo                \
   -c job_submit_mine.c -o .libs/job_submit_mine.o

# Some clean up
mv -f .deps/job_submit_mine.Tpo .deps/job_submit_mine.Plo
rm -fr .libs/job_submit_mine.a .libs/job_submit_mine.la \
   .libs/job_submit_mine.lai job_submit_mine.so

# Link
gcc -shared -fPIC -DPIC .libs/job_submit_mine.o -O2         \
   -pthread -O0 -pthread -Wl,-soname -Wl,job_submit_mine.so \
   -o job_submit_mine.so

# Install
cp job_submit_mine.so file \
   /usr/local/lib/slurm/job_submit_mine.so