onnxruntime源码解析之C接口简介

一、C接口

1. 简介

其他语言的接口都是在C接口的基础上，进一步的封装。

C的接口头文件为：onnxruntime_c_api.h

头文件内包含了详细的注释和说明。

总体上，除了一些数据结构的定义，C API 函数封装在如下结构体内，

struct OrtApi {
// 其中包含了一些函数指针，如下所示，
OrtStatus*(ORT_API_CALL* CreateStatus)(OrtErrorCode code, \
_In_ const char* msg)NO_EXCEPTION ORT_ALL_ARGS_NONNULL;
// ...
}

OrtApi的使用方式，一般是定义全局的指针OrtApi* g_ort;

然后，通过OrtGetApiBase()->GetApi(ORT_API_VERSION)获得struct Api*。

#include "onnxruntime_c_api.h"
OrtApi* g_ort = nullptr;

int main() {
　　g_ort = OrtGetApiBase()->GetApi(ORT_API_VERSION);
　　return 0;
}

ORT_API_VERSION是头文件中定义的全局的宏，必须与链接的libonnxruntime.so内的相同。否则，会发生运行时的错误。

这里的函数OrtGetApiBase()->GetApi每次返回的指针，是相同的。因此，可以定义全局指针g_ort，方便后续调用OrtApi内的函数指针。

调用函数指针的方式，与C++普通成员函数类似。唯一的差别是，C++成员函数的第一个参数是this指针。

2. Api定义方式

struct OrtApi结构体内的函数指针定义，包含了大量的注释和宏。

大体上容易阅读的，需要注意的是很多宏仅仅是说明的作用，并没有生成二进制代码。

例如，

// 这些宏仅仅用作说明，函数参数的意义。
// 用来标志参数是输入还是输出，等等。
#define _In_
#define _In_z_
#define _In_opt_
#define _In_opt_z_
#define _Out_
#define _Outptr_
#define _Out_opt_

以一个struct OrtApi内的实际函数接口为例，

  ORT_API2_STATUS(CreateEnv, OrtLoggingLevel log_severity_level, _In_ const char* logid, \
  _Outptr_ OrtEnv** out);

// 这里的ORT_API2_STATUS是个宏，展开后，如下所示，

_Check_return_ _Ret_maybenull_ OrtStatusPtr(ORT_API_CALL* CreateEnv)(OrtLoggingLevel log_severity_level, \
const char* logid, OrtEnv** out) NO_EXCEPTION ORT_MUST_USE_RESULT;

// 上面实际上定义了一个函数指针(* CreateEnv)，返回值是OrtStatusPtr
// 输入是(OrtLoggingLevel log_severity_level, const char* logid, OrtEnv** out)
// 其他下线开头的字符串，以及ORT_API_CALL
// 是一些说明性的宏，NO_EXCEPTION/ORT_MUST_USE_RESULT在不同平台下，不同的编译选项，有相对性的功能。

上述函数指针的调用方式是，

OrtEnv* my_ort_env;
auto current_ort_status = g_ort->CreateEnv(my_log_level, \
"my_log_id", &my_ort_env);