Job Submit Plugin API

Overview

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

Slurm job submit plugins must conform to the Slurm Plugin API with the following specifications:
Slurmジョブ送信プラグインは、次の仕様のSlurmプラグイン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.
メジャータイプは「job_submit」である必要があります。マイナータイプは、ジョブ送信パッケージのタイプに適した名前にすることができます。
We include samples in the Slurm distribution for
の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).
  lua —これらの関数を実装するLuaスクリプトへのインターフェース（実際にはそれらのわずかなバリエーション）。
  Sample Lua scripts can be found with the Slurm distribution in the directory contribs/lua.
  サンプルのLuaスクリプトは、ディレクトリcontribs / luaのSlurmディストリビューションにあります。
  The default installation location of the Lua scripts is the same location as the Slurm configuration file, slurm.conf.
  Luaスクリプトのデフォルトのインストール場所は、Slurm構成ファイルslurm.confと同じ場所です。
  
• partition — Sets a job's default partition based upon job submission parameters and available partitions.
  パーティション—ジョブ送信パラメータと使用可能なパーティションに基づいてジョブのデフォルトパーティションを設定します。
  

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」という名前のluaスクリプトを1つだけ実行します。

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.
注：これらのinitおよびfini関数は、dlopen（3）システムライブラリで説明されているものと同じではありません。
The C run-time system co-opts those symbols for its own initialization.
Cランタイムシステムは、独自の初期化のためにこれらのシンボルを採用します。
The system _init() is called before the Slurm init(), and the Slurm fini() is called before the system's _fini().
システム_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.
この関数は、salloc、sbatch、またはsrunコマンドによって提供されるジョブ送信パラメーターを使用してslurmctldデーモンによって呼び出されます。
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のグローバルデータ構造にアクセスできることに注意してください。たとえば、使用可能なパーティションや予約などを調べることができます。

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

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

error_msg (output) If the argument is not null, then a plugin generated error message can be stored here.
error_msg（出力）引数がnullでない場合、プラグインで生成されたエラーメッセージをここに保存できます。
The error message is expected to have allocated memory which Slurm will release using the xfree function.
エラーメッセージには、Slurmがxfree関数を使用して解放するメモリが割り当てられていると予想されます。
The error message is always propagated to the caller, no matter the return code.
エラーメッセージは、リターンコードに関係なく、常に呼び出し元に伝播されます。

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.
この関数は、scontrolまたはsviewコマンドによって提供されるジョブ変更パラメーターを使用してslurmctldデーモンによって呼び出されます。
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のグローバルデータ構造にアクセスできることに注意してください。たとえば、使用可能なパーティションや予約などを調べることができます。

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.
Lua関数は、使いやすさを向上させるために、Cで実装されている関数とは少し異なります。
Sample Lua scripts can be found with the Slurm distribution in the directory contribs/lua.
サンプルのLuaスクリプトは、ディレクトリcontribs / luaのSlurmディストリビューションにあります。
The default installation location of the Lua scripts is the same location as the Slurm configuration file, slurm.conf.
Luaスクリプトのデフォルトのインストール場所は、Slurm構成ファイル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.
Luaを使用したジョブ環境変数の読み取りと書き込みは、名前付き要素を含むデータ構造として環境変数を参照することで可能です。
For example:
例えば：

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.
この関数は、salloc、sbatch、またはsrunコマンドによって提供されるジョブ送信パラメーターを使用してslurmctldデーモンによって呼び出されます。
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のグローバルデータ構造にアクセスできることに注意してください。たとえば、使用可能なパーティションや予約などを調べることができます。

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.
この関数は、scontrolまたはsviewコマンドによって提供されるジョブ変更パラメーターを使用してslurmctldデーモンによって呼び出されます。
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のグローバルデータ構造にアクセスできることに注意してください。たとえば、使用可能なパーティションや予約などを調べることができます。

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.
使用可能なジョブ属性は、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.
使用しているSlurmのバージョンで使用可能なジョブ属性を見つけるには、SchedMD githubページに移動し、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).
_job_rec_field（）には、job_recordで使用可能な属性のリストが含まれています（例：Slurmの現在のレコード）。
_get_job_req_field() contains the list of attributes available for the job_descriptor (e.g. submission or modification request).
_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.
一般に、ジョブ送信プラグインにLUAインターフェースを使用するのが最善です。Slurmデータ構造への依存を最小限に抑えて、記述と保守を行うのは簡単です。
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.
ただし、Cを使用すると、slurmctldデーモンのすべてのデータ構造と関数へのフルアクセスなど、LUAを使用して利用できるよりも多くの情報を取得するメカニズムが提供されます。
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).
Cプログラムを構築する最も簡単な方法は、Slurmディストリビューションに含まれているジョブ送信プラグインの1つを独自のコードに置き換えることです（つまり、独自のコードでパッチを使用します）。
Then just build and install Slurm with that new code.
次に、その新しいコードを使用してSlurmをビルドしてインストールします。
Building a new plugin outside of the Slurm distribution is possible, but far more complex.
Slurmディストリビューションの外部で新しいプラグインを構築することは可能ですが、はるかに複雑です。
It also requires access to a multitude of Slurm header files as shown in the procedure below.
また、以下の手順に示すように、多数の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