InvokeOptions 结构体

InvokeOptions 结构体#

InvokeOptions Definition#

struct InvokeOptions {
    // 以 1/1000 cpu 核为单位
    int cpu;

    // 以 1MB 为单位
    int memory;

    // 除了 CPU 和内存之外的自定义资源
    std::unordered_map<std::string, float> customResources;

    // 自定义扩展
    std::unordered_map<std::string, std::string> customExtensions;

    // Pod 标签，仅在部署到 Kubernetes 时生效
    std::unordered_map<std::string, std::string> podLabels;

    std::vector<std::string> labels;

    std::unordered_map<std::string, std::string> affinity;

    size_t retryTimes = 0;

    bool (*retryChecker)(const Exception &e) noexcept = nullptr;

    size_t priority = 0;

    bool alwaysLocalMode = false;

    bool preferredPriority = true;

    bool preferredAntiOtherLabels = true;

    bool requiredPriority = false;

    std::string groupName = "";

    InstanceRange instanceRange;

    int recoverRetryTimes = 0;
    };

InvokeOptions 说明#

函数调用选项，用于指定调用资源等功能。

InvokeOptions 参数#

名称	类型	描述	默认值
cpu	int	指定 CPU 核心资源，以 1/1000 CPU 核为单位。	`500`
memory	int	指定内存资源，以 1MB 为单位。	`500`
customResources	std::unordered_map<std::string, float>	自定义资源，当前支持配置异构资源与磁盘资源。磁盘资源支持 “disk”，单位：GB 。异构资源支持 “GPU/XX/YY” 和 “NPU/XX/YY”， XX 为卡的型号，如 Ascend910B4，支持正则表达式。YY 可以是 count、HBM、latency、stream。
customExtensions	std::unordered_map<std::string, std::string>	用户自定义配置（例如函数并发性）。也用作 metrics 的用户自定义 tag，用于采集用户信息。
podLabels	std::unordered_map<std::string, std::string>	指定实例位置的 pod 标签（低可靠实例不支持配置）。仅在 Kubernetes 上部署时生效。
labels	std::vector<std::string>	用于函数实例的亲和、反亲和标签（格式如：”key” ， “key:value”）。
affinity	std::unordered_map<std::string, std::string>	定义函数实例调度的亲和性、反亲和性（待废弃）。
retryTime	size_t	无状态函数的重试次数。	`0`
retryChecker	bool (*)(const YR::Exception &e) noexcept	无状态函数的重试判断钩子，默认空（当 retryTimes = 0 时无效）。
priority	size_t	定义无状态函数的优先级。	`0`
alwaysLocalMode	bool	指定 cluster mode 强制在本地使用多线程运行用户函数（在 local mode 模式下不生效）。	`false`
preferredPriority	bool	是否开启优先级调度。开启后，当传入多个弱亲和条件，按顺序匹配打分，出现一个满足的即可调度成功。	`true`
requiredPriority	bool	是否开启优先级调度。开启后，当传入多个强亲和条件，按顺序匹配打分，当传入多个强亲和条件都不满足时，调度失败。	`false`
preferredAntiOtherLabels	bool	是否开启反亲和不可选资源。开启后，当传入多个弱亲和条件都不满足时，调度失败。	`true`
groupName	string	指定成组实例调度器 name，默认空。	`""`
instanceRange	InstanceRange	函数实例个数 Range 范围配置，用于配置调度/部署一组函数实例的范围。详见 struct-InstanceRange 。
recoverRetryTimes	int	实例最大恢复次数（当实例异常退出时，自动以最新状态恢复实例）。默认 `0`，即不进行自动恢复。注：并不保证所有指定的重试次数都会完成，存在不可恢复的异常场景时， openYuanrong会提前停止重试并抛出异常。	`0`

关于 retryTime 和 retryChecker#

注：无状态函数，以下由框架重试的错误码，不占用重试次数：

ERR_RESOURCE_NOT_ENOUGH
ERR_INSTANCE_NOT_FOUND
ERR_INSTANCE_EXITED

建议由用户决定是否重试的错误码：

ERR_USER_FUNCTION_EXCEPTION
ERR_REQUEST_BETWEEN_RUNTIME_BUS
ERR_INNER_COMMUNICATION
ERR_SHARED_MEMORY_LIMIT
EDERR_OPERATE_DISK_FAILED
ERR_INSUFFICIENT_DISK_SPACE

retryTime 和 retryChecker 暂时不支持有状态函数，否则会抛出异常。示例用法见 FunctionHandler::Options 。

关于 alwaysLocalMode#

在 cluster mode 模式下指定 alwaysLocalMode 为 true 来调用无状态函数时，生成的 ObjectRef 也是 local 的，可以通过 bool ObjectRef::IsLocal() const 方法检查。
在 cluster mode 模式下指定 alwaysLocalMode 为 true 来创建有状态函数时，已经确定了该有状态函数是否在本地多线程创建，后续的调用不再需要指定是否在本地执行。

当前不支持 Wait 、 Get 、 Cancel 接口以及 Invoke 参数调用时混用 local 和 cluster 的 ObjectRef ，否则抛出异常。当 cluster mode 初始化线程池为空但仍然调用了 alwaysLocalMode 的无状态或有状态函数，也会抛出异常。

关于 customExtensions#

customExtensions 表示用户自定义的配置，接收用户自定义的 key/value 键值对，常见的配置如下：

DELEGATE_DOWNLOAD配置#

key，std::string 类型	value，std::string 类型	描述
storage_type	存储服务类型	当前支持从 obs 下载(s3)
hostName	存储服务地址	obs 地址
bucketId	桶名	obs 桶名
objectId	对象名	obs 对象名
sha256	待下载的对象文件 sha256 值	通过 sha256 进行文件校验，确保下载文件完整性
temporaryAccessKey	访问 obs 桶的鉴权信息	访问 obs 桶的鉴权信息
temporarySecretKey	访问 obs 桶的鉴权信息	访问 obs 桶的鉴权信息
securityToken	访问 obs 桶的鉴权信息	访问 obs 桶的鉴权信息

customExtensions 中输入用户自定义 metrics tag 时：

YR::InvokeOptions opt;
opt.customExtensions.insert({"YR_Metrics", "{\"endpoint\":\"127.0.0.1\", \"project_id\":\"my_project_id\"}"});

键为 YR_Metrics，值为自定义 label 的 JSON 字符串：

Prometheus 中选择 metrics name 为 yr_app_instance_billing_invoke_latency，可在采集到的 invoke 信息中找到自定义 tag 信息：

yr_app_instance_billing_invoke_latency{
...
endpoint="127.0.0.1",
...}

关于 customResources#

配置磁盘资源#

customResources 所配置的磁盘资源，单位统一为 GB。

使用示例如下：

YR::InvokeOptions opt;
opt.customResources.insert({"disk", 10})

在调度任务成功执行后，openYuanrong支持用户进程通过读取环境变量 YR_DISK_MOUNT_POINT 来获取已分配磁盘的挂载路径信息。