PrEp 插件 API

概述

本文档描述了 Slurm PrEp —— "Pr"olog 和 "Ep"ilog 的缩写 —— 插件 API。它旨在为希望编写自己的 Slurm prep 插件的程序员提供资源。

prep 插件 API 的目的是提供一个原生 C 接口，以便使用传统上用于 Prolog、Epilog、PrologSlurmctld 和 EpilogSlurmctld 脚本的相同钩子。这些接口现在通过 prep/script 插件实现，该插件是开发其他插件的良好示例。

Slurm PrEp 插件必须符合 Slurm 插件 API 的以下规范：

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

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

const char plugin_type[]="主/次"

主类型必须是 "prep"。次类型可以是任何适合的 prep 插件类型名称。

const uint32_t plugin_version

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

如果需要，Slurm 可以通过 PrEpPlugins 配置选项配置为使用多个 prep 插件。额外的插件应以逗号分隔。请注意，如果未设置该选项，则默认情况下加载 prep/script 插件，但如果已明确设置，则不会加载。因此，如果您设置了该选项，并且仍打算使用 Prolog、Epilog、PrologSlurmctld 和/或 EpilogSlurmctld 选项，您需要确保同时设置您的额外插件和 prep/script。

在开发 prep_p_prolog_slurmctld() 或 prep_p_epilog_slurmctld() 接口时必须特别小心。这些函数在 slurmctld 持有多个内部锁时被调用，需要快速返回，否则 slurmctld 的响应能力和系统吞吐量将受到影响。对于简单的日志记录，这不是必需的，"async" 选项可以保持为 false。但是，特别是对于与外部 API 通信或生成额外进程的任何内容，强烈建议首先制作所需的任何作业记录详细信息的本地副本，然后生成一个单独的处理线程 —— 默认情况下，该线程不会继承任何 slurmctld 锁 —— 以继续处理。您必须将异步返回值设置为 true，并在线程退出之前调用相应的 prolog_slurmctld_callback() 或 epilog_slurmctld_callback() 函数。这些回调在 slurmctld 启动时通过 prep_p_register_callbacks() 调用提供，并且这些函数指针应在您的插件中本地缓存。

API 函数

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

int init(void)

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

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

void fini(void)

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

返回: 无。

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

void prep_p_register_callbacks(prep_callbacks_t *callbacks)

描述:
此函数由 slurmctld 调用，以传递用于与 prep_p_prolog_slurmctld() 和 prep_p_epilog_slurmctld() 接口进行异步操作的函数指针地址。如果使用异步操作，则必须保存这些指针，否则此函数可以是一个空存根。

参数:
callbacks (输入) 包含用于在 slurmctld 内部进行异步操作的函数指针

返回: 无。

int prep_p_prolog(job_env_t *job_env, slurm_cred_t *cred)

描述:
在作业的第一个步骤在计算节点上开始之前，以 root 身份在 slurmd 内部调用。

参数:
job_env (输入) 来自步骤启动请求的详细信息
cred (输入) 启动凭证，包含由 slurmctld 签名的额外可验证启动详细信息

返回:
SLURM_SUCCESS 表示成功，或
SLURM_ERROR 表示失败，将导致作业失败。

int prep_p_epilog(job_env_t *job_env, slurm_cred_t *cred)

描述:
在所有作业步骤完成后，以 root 身份在 slurmd 内部调用。

参数:
job_env (输入) 来自步骤启动请求的详细信息
cred (输入) 启动凭证，包含由 slurmctld 签名的额外可验证启动详细信息

返回:
SLURM_SUCCESS 表示成功，或
SLURM_ERROR 表示失败，将导致作业失败。

int prep_p_prolog_slurmctld(job_record_t *job_ptr, bool *async)

描述:
在作业启动之前，在 slurmctld 内部调用。

参数:
job_ptr (输入) 原始作业记录
async (输出) 如果此接口生成了一个必须在作业开始执行之前完成的单独处理线程，则设置为 true

返回:
SLURM_SUCCESS 表示成功，或
SLURM_ERROR 表示失败，将导致作业失败。

int prep_p_epilog_slurmctld(job_record_t *job_ptr, bool *async)

描述:
在作业终止时，在 slurmctld 内部调用。

参数:
job_ptr (输入) 原始作业记录
async (输出) 如果此接口生成了一个必须在作业标记为完成之前完成的单独处理线程，则设置为 true

返回:
SLURM_SUCCESS 表示成功，或
SLURM_ERROR 表示失败，将导致作业失败。

最后修改于 2023 年 4 月 18 日