接口文档

说明：

• c/c++版本插件以c动态库方式实现. 插件接口依据不同类型的服务特性(会话/非会话,同步/异步等)提供了较为丰富的接口集, 用户在集成过程中可按需实现服务对应的部分接口即可
• 运行过程中无需调用的其他接口也需空实现以便导出接口符号, 防止插件load过程失败
• c/c++插件共提供12个接口，其中包含插件的初始化/资源操作/会话操作/非会话操作等相关接口，对于大部分服务类型，仅需实现其中部分接口即可. 如下对相关接口进行说明

wrapperInit

类型定义：pConfig
          typedef struct ParamList{
          char* key;
          char* value;
          unsigned int vlen;
          struct ParamList* next;
        }* pConfig;

配置示例：
        “common.lic” = “10”
        “resource./resource/wfst.bin” = “WFST”

接口示例：
             int maxLic = 10; // default concurrency
             std::map<kernelInst, bool/*idle*/> hdlCache;
             int WrapperAPI wrapperInit(pConfig cfg){
                  while(cfg){
                          printf(“key:%s, value:%s\n”, cfg->key, cfg->value);
                          If (strcmp(cfg->key, “common.lic”) == 0){
                                  maxLic = atoi(cfg->value);
                           }
                            cfg = cfg->next;
                  }
                    // 插件实例管理-预申请
                    for (int i=0; i< maxLic ){
                             kernelInst inst = new kernelInst;
                             hdlCache[inst] = true;
                      }
                      return 0;
                }

示例输出：
              > key:common.lic, value:10
              > key:resource./home/wfst.bin, value:WFST

wrapperFini

接口示例

int WrapperAPI wrapperFini(){
      std::map<kernelInst, bool>::iterator ite = hdlCache.begin();
      for ( ; ite != hdlCache.end()  ; ite++){
               delete ite->first;
          }
          return 0;
    }

wrapperError

接口示例：
         static const struct errPair {
                 int err;
                 const char* desc;
          } errPairArr[] = {
                  {10010, “instance not enough”}，
                  {10011, “input invalid data”},
          }; 

             const char* WrapperAPI wrapperError(int errNum){
                    int errSize = sizeof(errPairArr) / sizeof(errPair);
                    for (int i=0; i < errSize; i++){
                             If (errPairArr[i].err == errNum){
                                      return errPairArr[i].desc;
                              }
                     }
                     return “general error”;
             }
     调用示例：
             printf(“err: %s\n”, wrapperError(10010));
             printf(“err: %s\n”, wrapperError(10011));
     示例输出：
             > err: instance not enough
             > err: input invalid data

wrapperLoadRes_

类型定义：
      typedef struct DataList{
          char*   key;            // 数据标识
          void*   data;           // 数据实体
          unsigned int len;       // 数据长度
          char* desc;             // 数据描述
          char* encoding;         // 数据编码
          DataType    type;       // 数据类型
          DataStatus status;      // 数据状态
          struct DataList* next;  // 链表指针
      }*  pDataList;

补充说明： (1). 资源加载接口实参perData链表长度固定为1. (2). 资源加载场景，仅使用部分成员标记数据：perData->data，perData->len，perData->type 其他成员为无效数据，无需读取.

wrapperUnloadRes

wrapperCreate

类型定义：
      typedef struct ParamList{
          char* key;
          char* value;
          unsigned int vlen;
          struct ParamList* next;
      }* pParamList;

      // 回调接口，用于异步模式回传内核响应结果
      // handle：wrapperCreate接口返回的插件实例句柄.
      // respData：插件输出的会话请求计算结果.
      typedef int(*wrapperCallback)(const void* handle, pDataList respData);

     接口示例：
          (1). 同步模式：外部加载器通过wrapperRead接口获取结果
           const void* WrapperAPI wrapperCreate(pParamList params, wrapperCallback cb, unsigned int psrIds[], int psrCnt, int* errNum){ 
                   // hdlCache lock
                  std::map<kernelInst, bool>::iterator ite = hdlCache.begin();
                  for ( ; ite != hdlCache.end()  ; ite++){
                           If (ite->second){
                                    ite->second = false; *errNum = 0;
                                    // hdlCache unlock
                                    return (void*)ite->first;
                            }
                  }
                  // hdlCache unlock
                    *errNum = 10010;
                     return NULL;
                }

      (2). 异步模式：插件通过调用加载器回调接口cb返回结果.
      // func1
         wrapperCallback funcCB;
         const void* WrapperAPI wrapperCreate(pParamList params, wrapperCallback cb, unsigned int psrIds[], int psrCnt, int* errNum){
                  // hdlCache lock
                     std::map<kernelInst, bool>::iterator ite = hdlCache.begin();
                     for ( ; ite != hdlCache.end()  ; ite++){
                              If (ite->second){
                                       ite->second = false; *errNum = 0;
                                        // hdlCache unlock
                                           funcCB = cb;
                                           return (void*)ite->first;
                                              }
                      }
                       // hdlCache unlock
                         *errNum = 10010;
                          return NULL;
      }

                // func2, internal private function
                   Int kernelCalc(kernelInst inst){
                           pDataList  result = inst->calc(inputData);
                           funcCB(inst, result);
                           return 0;
                       }

补充说明： (1). 若会话为同步模式，插件需实现create|write|read|destroy配套接口.(当前仅支持同步模式) (2). 若会话为异步模式，插件需实现create|write|destroy接口，结果回传通过回调cb进行返回同步. (3). 会话模式对应平台AI能力上线流程中的接口类型：websocket

wrapperWrite

接口示例：

         int WrapperAPI wrapperWrite(const void\* handle, pDataList reqData){
                             kernelInst inst = (kernelInst)handle;
                             //插件写入计算数据
                             int ret = Inst->dataWrite(reqData);
                             return ret;
                               }

​

补充说明：

(1). 用户请求上传的分块数据可能在加载器中进行合并

(2). 对于单个具体插件实例，加载器单线程调用写数据接口，保证写入数据有序

wrapperRead

接口示例：
        int WrapperAPI wrapperRead(const void* handle, pDataList* respData){
                kernelInst inst = (kernelInst)handle;
                // 插件查询计算结果
                int ret = Inst->queryResult(respData);
                return ret;
             }
调用示例：
       (1). 实时结果模式：会话过程中每次写数据后调用读接口查询实时结果
       int aigesCall(){
                void* inst = wrapperCreate();
                while(!input.end()){
                         wrapperWrite(inst, input);
                         wrapperRead(inst, output);
                 }
                  while(!output.end()){
                          wrapperRead(inst, output);
                  }
                   return 0;
        }
       (2). 非实时结果模式：会话过程中所有数据完整写入后调用读接口
       int aigesCall(){
               void* inst = wrapperCreate();
               while(!input.end()){
                       wrapperWrite(inst, input);
               }
                while(!output.end()){
                        wrapperRead(inst, output);
                }
                 return 0;
            }

补充说明：

(1). 对于单个具体插件实例，加载器单线程调用读数据接口

(2). 结果respData内存空间由插件申请及维护，可于destroy时释放

(3). 一期加载器仅支持实时结果读取模式

_wrapperDestroy

接口示例：

int WrapperAPI wrapperDestroy(const void\* handle){
        // hdlCache lock;
        std::map<kernelInst, bool>::iterator ite = hdlCache.find(handle);
        If (ite != hdlCache.end()){
                   ite->second = true;
         }
          // hdlCache unlock;
           return 0;
       }

wrapperExec

类型定义：

typedef struct ParamList{
    char* key;
    char* value;
    unsigned int vlen;
    struct ParamList* next;
} pParamList;

接口示例：

int WrapperAPI wrapperExec(pParamList params, pDataList reqData, pDataList*respData){
       return kernel->calc(params, reqData, respData);
}

补充说明：

(1). 结果respData内存空间由插件申请及维护，于wrapperExecFree时释放

(2). 非会话模式对应平台AI能力上线流程中的接口类型：http

wrapperExecFree

接口示例：

int WrapperAPI wrapperExecFree(pDataList* respData){
        return kernel->release(respData);
}

wrapperExecAsync

类型定义：

typedef int(*wrapperCallback)(const void* handle, pDataList respData);

接口示例：

// func1
int WrapperAPI wrapperExecAsync(const char* handle, pParamList params, pDataList reqData, wrapperCallback callback, int timeout){
        return = kernel->produce(handle, params, reqData, callback, timeout);
}


// func2, internal private function
Int kernelAsyncCalc(){
      handle, params, reqData, callback, timeout = kernel->consume();
      respData = kernel->calc(params, reqData, timeout);
      return callback(handle, respData);
}

补充说明

对应不同插件引擎的服务模式，插件仅需实现上述部分接口即可正常提供服务，其他接口可做空实现处理. 如下以不同服务模式进行说明.

注：

1. 通用接口wrapperInit/wrapperFini/wrapperError，各类服务模式插件均需实现

2. 个性化接口wrapperLoadRes/wrapperUnloadRes由各类服务模式插件按需实现