作业提交插件 API

概述

本文档描述了 Slurm 作业提交插件及其定义的 API。它旨在为希望编写自己 Slurm 作业提交插件的程序员提供资源。此 API 的版本为 100。

Slurm 作业提交插件必须符合 Slurm 插件 API，具体规格如下：

const char plugin_name[]="完整 文本 名称"

一个自由格式的 ASCII 文本字符串，用于标识插件。

const char plugin_type[]="主要/次要"

主要类型必须为 "job_submit." 次要类型可以是任何适合的作业提交包名称。 我们在 Slurm 分发中包含了一些示例：

• all_partitions — 将默认分区设置为集群上的所有分区。
• defaults — 设置作业提交的默认值或修改请求。
• logging — 记录选择的作业提交和修改参数。
• lua — 接口到 Lua 脚本，实现这些功能（实际上是它们的轻微变体）。示例 Lua 脚本可以在 Slurm 分发的 contribs/lua 目录中找到。Lua 脚本必须命名为 "job_submit.lua"，并且必须位于默认配置目录中（通常是安装目录的 "etc" 子目录）。如果配置的 lua 脚本无效，Slurmctld 在启动时将会致命。如果在 slurmctld 运行时脚本损坏或被删除，Slurm 将回退到之前有效的脚本版本。 警告：slurmctld 在持有内部锁时运行此脚本，并且此脚本一次只能运行一个副本。这会阻塞 slurmctld 中的大多数并发。因此，此脚本应尽快完成。
• partition — 根据作业提交参数和可用分区设置作业的默认分区。
• pbs — 将 PBS 作业提交选项转换为 Slurm 等效选项（如果可能）。
• require_timelimit — 强制作业提交指定时间限制。

const uint32_t plugin_version
如果指定，标识用于构建此插件的 Slurm 版本，尝试从不同版本的 Slurm 加载插件将导致错误。 如果未指定，则插件可以由任何版本的 Slurm 命令和守护进程加载，但这可能会导致由于插件函数参数或插件使用的其他 Slurm 函数的变化而导致难以诊断的故障。

如果需要，Slurm 可以配置为使用多个 job_submit 插件，但 lua 插件只会执行一个名为 "job_submit.lua" 的 lua 脚本，该脚本位于默认脚本目录中（通常是安装目录的 "etc" 子目录）。

API 函数

以下所有函数都是必需的。未实现的函数必须是存根。

int init (void)

描述:
当插件加载时调用，在调用任何其他函数之前。将全局初始化放在这里。

返回:
SLURM_SUCCESS 表示成功，或
SLURM_ERROR 表示失败。

void fini (void)

描述:
当插件被移除时调用。清除任何分配的存储。

返回: 无。

注意: 这些 init 和 fini 函数与 dlopen (3) 系统库中描述的不同。 C 运行时系统会占用这些符号进行其自身的初始化。 系统 _init() 在 Slurm 的 init() 之前被调用，而 Slurm 的 fini() 在系统的 _fini() 之前被调用。

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

描述:
此函数由 slurmctld 守护进程调用，使用用户提供的作业提交参数，无论使用何种命令（例如 salloc、sbatch、slurmrestd）。只有显式定义的值会被表示。对于在提交时未定义的值，slurm.NO_VAL/16/64 或 nil 将被设置。它可以用于记录和/或修改用户提供的作业参数。请注意，此函数可以访问 slurmctld 的全局数据结构，例如检查可用的分区、预留等。

参数:
job_desc （输入/输出）作业分配请求规格，在设置作业默认值之前。
submit_uid （输入）发起请求的用户 ID。
error_msg （输出）如果参数不为 null，则可以在此处存储插件生成的错误消息。错误消息应具有分配的内存，Slurm 将使用 xfree 函数释放。错误消息始终会传播给调用者，无论返回代码如何。

返回:
SLURM_SUCCESS 表示成功，或
SLURM_ERROR 表示失败。

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

描述:
此函数由 slurmctld 守护进程调用，使用用户提供的作业修改参数，无论使用何种命令（例如 scontrol、sview、slurmrestd）。它可以用于记录和/或修改用户提供的作业参数。请注意，此函数可以访问 slurmctld 的全局数据结构，例如检查可用的分区、预留等。

参数:
job_desc （输入/输出）作业分配请求规格，在设置作业默认值之前。
job_ptr （输入/输出）slurmctld 守护进程当前的作业数据结构。
modify_uid （输入）发起请求的用户 ID。

返回:
SLURM_SUCCESS 表示成功，或
SLURM_ERROR 表示失败。

Lua 函数

Lua 函数与 C 中实现的函数略有不同，以便于使用。示例 Lua 脚本可以在 Slurm 分发的 contribs/lua 目录中找到。Lua 脚本的默认安装位置与 Slurm 配置文件 slurm.conf 相同。 使用 Lua 读取和写入作业环境变量是可能的，通过将环境变量引用为包含命名元素的数据结构。

注意: 只有 sbatch 将环境发送到 slurmctld。salloc 和 srun 不会将环境发送到 slurmctld，因此 job_desc.environment 在这些作业的 job_submit 插件中不可用。

例如：

...
	-- job_desc.environment 仅在批处理作业中可用。
	if (job_desc.script) then
		if (job_desc.environment ~= nil) then
			if (job_desc.environment["FOO"] ~= nil) then
				slurm.log_user("找到环境 FOO=%s",
					       job_desc.environment["FOO"])
			end
		end
	end
...

注意: 要获取/设置所有类型作业的环境，另一种方法是使用 CliFilterPlugins。

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

描述:
此函数由 slurmctld 守护进程调用，使用用户提供的作业提交参数，无论使用何种命令（例如 salloc、sbatch、slurmrestd）。只有显式定义的值会被表示。对于在提交时未定义的值，slurm.NO_VAL/16/64 或 nil 将被设置。它可以用于记录和/或修改用户提供的作业参数。请注意，此函数可以访问 slurmctld 的全局数据结构，例如检查可用的分区、预留等。

参数:
job_desc （输入/输出）作业分配请求规格。
part_list （输入）指向用户被授权使用的分区的指针列表。
submit_uid （输入）发起请求的用户 ID。

返回:
slurm.SUCCESS — 插件接受的作业提交。
slurm.FAILURE — 由于错误而拒绝的作业提交（在 19.05 中弃用）。
slurm.ERROR — 由于错误而拒绝的作业提交。
slurm.ESLURM_* — 由于错误而拒绝的作业提交，错误由 slurm/slurm_errno.h 和 src/common/slurm_errno.c 定义。

注意: 由于 job_desc 仅包含用户指定的值，因此未定义的值可以通过检查 nil 或相应的 slurm.NO_VAL/16/64 来识别。这允许站点应用策略，例如要求用户定义节点数量，如下面的示例：

...
	-- 必须在提交时定义节点数量
	if (job_desc.max_nodes == slurm.NO_VAL) then
		slurm.log_user("未指定最大节点数，请指定节点数")
		return slurm.ERROR
	end
...

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

描述:
此函数由 slurmctld 守护进程调用，使用用户提供的作业修改参数，无论使用何种命令（例如 scontrol、sview、slurmrestd）。它可以用于记录和/或修改用户提供的作业参数。请注意，此函数可以访问 slurmctld 的全局数据结构，例如检查可用的分区、预留等。

参数:
job_desc （输入/输出）作业分配请求规格。
job_ptr （输入/输出）slurmctld 守护进程当前的作业数据结构。
part_list （输入）指向用户被授权使用的分区的指针列表。
modify_uid （输入）发起请求的用户 ID。

返回:
job_modify() 的返回值与 job_submit() 的返回值相同。

Lua 作业属性

可用的作业属性会随着不同版本的 Slurm 而变化。要查找您使用的 Slurm 版本可用的作业属性，请访问 SchedMD github 页面。导航到 src/lua/slurm_lua.c 并查找函数 slurm_lua_job_record_field()，该函数包含可用于 job_record（例如 Slurm 中的当前记录）的属性列表。 导航到 src/plugins/job_submit/lua/job_submit_lua.c 并查找函数 _get_job_req_field()，该函数包含可用于 job_descriptor（例如提交或修改请求）的属性列表。

构建

通常，使用 LUA 接口进行作业提交插件是最佳选择： 它简单易写且维护，依赖于 Slurm 数据结构的最小。 然而，使用 C 确实提供了一种机制，可以获取比使用 LUA 更多的信息，包括对 slurmctld 守护进程中所有数据结构和函数的完全访问。 构建 C 程序的最简单方法是用您自己的代码替换 Slurm 分发中包含的一个作业提交插件（即使用补丁与您自己的代码）。 然后只需构建并安装带有新代码的 Slurm。 在 Slurm 分发之外构建新插件是可能的，但要复杂得多。 它还需要访问大量的 Slurm 头文件，如下面的过程所示。

1. 您需要至少部分构建 Slurm。必须执行 "configure" 命令以构建构建目录中的 "config.h" 文件。
2. 在某处创建一个本地目录以构建您的文件。 还要创建名为 ".libs" 和 ".deps" 的子目录。
3. 从另一个作业提交插件的 ".deps" 目录（在构建过程中生成）中复制一个 ".deps/job_submit_*Plo" 文件到您的本地 ".deps" 子目录中。 根据需要重命名文件以反映您的插件名称（例如，将 "job_submit_partition.Plo" 重命名为 "job_submit_mine.Plo"）。
4. 编译并链接您的插件。根据您的构建环境，这些选项可能会有所不同。检查用于构建其他作业提交插件的选项，并根据需要修改下面的示例。
5. 安装插件。

# 示例：
# Slurm 源代码位于 ~/SLURM/slurm.git
# Slurm 构建目录位于 ~/SLURM/slurm.build
# 插件构建将在目录中进行
#   "~/SLURM/my_submit"
# 安装位置为 "/usr/local"

# 从 ~/SLURM/slurm.build 构建 Slurm
# （或至少运行 "~/SLURM/slurm.git/configure"）

# 设置您的插件文件
cd ~/SLURM
mkdir my_submit
cd my_submit
mkdir .libs
mkdir .deps
# 创建您的插件代码
vi job_submit_mine.c

# 复制一个依赖文件
cp ~/SLURM/slurm.build/src/plugins/job_submit/partition/.deps/job_submit_partition.Plo \
   .deps/job_submit_mine.Plo

# 编译
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

# 一些清理
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

# 链接
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

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

最后修改于 2024 年 10 月 30 日