MNN/docs/cpp/Interpreter.md

# Interpreter
```cpp
class Interpreter
```

## 枚举类
### SessionMode
```cpp
enum SessionMode {
    Session_Debug = 0,
    Session_Release = 1,
    Session_Input_Inside = 2,
    Session_Input_User = 3,
    Session_Output_Inside = 4,
    Session_Output_User = 5,
    Session_Resize_Direct = 6,
    Session_Resize_Defer = 7,
    Session_Backend_Fix = 8,
    Session_Backend_Auto = 9,
};
```

| value | name |      说明         |
|:------|:-----|:-----------------|
| 0 | `Session_Debug` | 可以执行callback函数，并获取Op信息(*默认*) |
| 1 | `Session_Release` | 不可执行callback函数 |
| 2 | `Session_Input_Inside` | 输入由session申请(*默认*) |
| 3 | `Session_Input_User` | 输入由用户申请 |
| 4 | `Session_Output_Inside` | 输出依赖于session不可单独使用 |
| 5 | `Session_Output_User` | 输出不依赖于session可单独使用 |
| 6 | `Session_Resize_Direct` | 在创建Session时执行resize(*默认*) |
| 7 | `Session_Resize_Defer` | 在创建Session时不执行resize |
| 8 | `Session_Backend_Fix` | 使用用户指定的后端，后端不支持时回退CPU |
| 9 | `Session_Backend_Auto` | 根据算子类型自动选择后端 |

---
### ErrorCode
```cpp
enum ErrorCode {
    NO_ERROR           = 0,
    OUT_OF_MEMORY      = 1,
    NOT_SUPPORT        = 2,
    COMPUTE_SIZE_ERROR = 3,
    NO_EXECUTION       = 4,
    INVALID_VALUE      = 5,
    INPUT_DATA_ERROR = 10,
    CALL_BACK_STOP   = 11,
    TENSOR_NOT_SUPPORT = 20,
    TENSOR_NEED_DIVIDE = 21,
};
```

| value | name |      说明         |
|:------|:-----|:-----------------|
| 0 | `NO_ERROR` | 没有错误，执行成功  |
| 1 | `OUT_OF_MEMORY` | 内存不足，无法申请内存 |
| 2 | `NOT_SUPPORT` | 有不支持的OP |
| 3 | `COMPUTE_SIZE_ERROR` | 形状计算出错 |
| 4 | `NO_EXECUTION` | 创建执行时出错 |
| 10 | `INPUT_DATA_ERROR` | 输入数据出错 |
| 11 | `CALL_BACK_STOP` | 用户callback函数退出 |
| 20 | `TENSOR_NOT_SUPPORT` | resize出错 |
| 21 | `TENSOR_NEED_DIVIDE` | resize出错 |

---
### SessionInfoCode
```cpp
enum SessionInfoCode {
    MEMORY = 0,
    FLOPS = 1,
    BACKENDS = 2,
    RESIZE_STATUS = 3,
    ALL
};
```

| value | name |      说明         |
|:-----|:-----|:-----------------|
| 0 | `MEMORY` | 会话的内存占用大小，MB计算，浮点类型数据 |
| 1 | `FLOPS` | 会话的计算量，flops，浮点数据类型 |
| 2 | `BACKENDS` | 会话的后端数目，个数是config数量加1 |
| 3 | `RESIZE_STATUS` | resize的状态，数据是int类型，0表示就绪，1表示需要分配内存，2表示需要resize |
|   | `ALL` | 以上所有信息 |

---
### HintMode
```cpp
enum HintMode {
    MAX_TUNING_NUMBER = 0,
};
```

| value | name |      说明         |
|:-----|:-----|:-----------------|
| 0 | `MAX_TUNING_NUMBER` | GPU下tuning的最大OP数 |

## 成员函数

---
### Interpreter
该构造函数禁止使用，创建对象请使用`createFromFile`

---
### ~Interpreter
析构函数

---
### createFromFile
```cpp
static Interpreter* createFromFile(const char* file);
```
从文件加载模型，加载`.mnn`模型文件创建一个MNN解释器，返回一个解释器对象

参数：
- `file` MNN模型所放置的完整文件路径

返回：创建成功则返回创建的解释器对象指针，失败就返回`nullptr`

---
### createFromBuffer
```cpp
static Interpreter* createFromBuffer(const void* buffer, size_t size)
```
从内存加载模型，根据指定内存地址与大小，从内存中创建一个计时器对象

参数：
- `buffer` 模型文件内存中的数据指针
- `size`  模型文件字节数大小

返回：创建成功则返回创建的解释器对象指针，失败就返回`nullptr`

---
### destroy
```cpp
static void destroy(Interpreter* net);
```
释放指定的解释器对象

参数：
- `net` 需要释放的解释器对象

返回：`void`

---
### setSessionMode
```cpp
void setSessionMode(SessionMode mode);
```
设置模型推理时回话的执行模式，参考[SessionMode](./Interpreter.html#sessionmode)

*该函数需在`createSession`前调用*

参数：
- `mode` 回话的执行模式

返回：`void`

---
### setCacheFile
```cpp
void setCacheFile(const char* cacheFile, size_t keySize = 128);
```
设置缓存文件，缓存文件在GPU模式下用来存储Kernel与Op信息；执行该函数，在`runSession`前会从缓存文件中加载信息；在`runSession`后会将相关信息写入缓存文件中

*该函数需在`createSession`前调用*

参数：
- `cacheFile` 缓存文件名
- `keySize` 保留参数，现在未使用

返回：`void`

---
### setExternalFile
```cpp
void setExternalFile(const char* file, size_t flag = 128);
```
设置额外文件，额外文件是指存储了模型中权重，常量等数据的文件，在创建`Session`时会从该文件中加载权重等数据。

*该函数需在`createSession`前调用*

参数：
- `file` 额外文件名
- `flag` 保留参数，现在未使用

返回：`void`

---
### updateCacheFile
```cpp
ErrorCode updateCacheFile(Session *session, int flag = 0);
```
更新缓存文件，在最近的一次`resizeSession`中如果修改了缓存信息，就写入到缓存文件中；如果没有修改缓存信息，就什么都不做

*该函数需在`resizeSession`前调用*

参数：
- `session` 要更新的缓存会话
- `flag` 保留参数，现在未使用

返回：更新缓存的[错误码](Interpreter.html#errorcode)

---
### setSessionHint
```cpp
void setSessionHint(HintMode mode, int value);
```
设置会话的额外执行信息，使用[HintMode](Interpreter.html#hintmode)来描述额外信息的类型

*该函数需在`createSession`前调用*

参数：
- `mode` 额外信息的类型
- `value` 额外信息的数值

返回：`void`

---
### createRuntime
```cpp
static RuntimeInfo createRuntime(const std::vector<ScheduleConfig>& configs);
```
根据配置创建一个Runtime，默认情况下，在`createSession`时对应create单独一个Runtime。对于串行的一系列模型，可以先单独创建Runtime，然后在各Session创建时传入，使各模型用共享同样的运行时资源（对CPU而言为线程池、内存池，对GPU而言Kernel池等）；`RuntimeInfo`的定义如下：
```cpp
typedef std::pair<std::map<MNNForwardType, std::shared_ptr<Runtime>>, std::shared_ptr<Runtime>> RuntimeInfo;
```

参数：
- `configs` 调度信息

返回：创建的运行时信息，可以用于创建`Session`

---
### createSession
```cpp
Session* createSession(const ScheduleConfig& config);
Session* createSession(const ScheduleConfig& config, const RuntimeInfo& runtime);
```
根据配置或根据用户指定的运行时信息创建会话`Session`
- 当仅传入`config`时会根据`config`信息创建`Runtime`
- 当传入`runtime`时则使用用户传入的`Runtime`

参数：
- `config` 调度信息
- `runtime` 执行信息

返回：创建的会话`Session`

---
### createMultiPathSession
```cpp
Session* createMultiPathSession(const std::vector<ScheduleConfig>& configs);
Session* createMultiPathSession(const std::vector<ScheduleConfig>& configs, const RuntimeInfo& runtime);
```
根据多个配置创建多段计算路径的会话
- 当仅传入`config`时会根据`config`信息创建`Runtime`
- 当传入`runtime`时则使用用户传入的`Runtime`

参数：
- `configs` 多个调度信息

返回：创建的会话`Session`

---
### releaseSession
```cpp
bool releaseSession(Session* session);
```
释放指定的`Session`

参数：
- `session` 待释放的`Session`

返回：是否成功释放该`Session`

---
### resizeSession
```cpp
void resizeSession(Session* session);
void resizeSession(Session* session, int needRelloc);
```
为session分配内存，进行推理准备工作；该函数一般配合`resizeTensor`一起调用，修改Tensor输入形状后对应整个推理过程中的内存分配也需要修改

参数：
- `session` 改变输入形状后需要重新分配内存的Session对象
- `needRelloc` 是否重新分配内存，如果为0则只进行形状计算不进行内存分配

返回：`void`

---
### releaseModel
```cpp
void releaseModel();
```
当不再需要执行`createSession`和`resizeSession`的时候，可以调用此函数释放解释器中持有的模型资源，会释放模型文件大小的内存

参数：
- `void`

返回：`void`

---
### getModelBuffer
```cpp
std::pair<const void*, size_t> getModelBuffer() const;
```
获取模型模型的内存数据指针和内存大小，方便用户存储模型

参数：
- `void`

返回：内存数据指针和内存大小

---
### getModelVersion
```cpp
const char* getModelVersion() const;
```
获取模型的版本信息，以字符串的形式返回

参数：
- `void`

返回：模型的版本信息，类似：`"2.0.0"`

---
### updateSessionToModel
```cpp
ErrorCode updateSessionToModel(Session* session);
```
将`Session`中`Tensor`的数据更新Model中的常量数据

参数：
- `session` 需要更新的会话

返回：更新数据的[错误码](Interpreter.html#errorcode)

---
### runSession
```cpp
ErrorCode runSession(Session* session) const;
```
运行session执行模型推理，返回对应的error code，需要根据错误码来判断后续是否成功执行模型推理

参数：
- `session` 执行推理的Session对象

返回：执行推理的[错误码](Interpreter.html#errorcode)

---
### runSessionWithCallBack
```cpp
ErrorCode runSessionWithCallBack(const Session* session, const TensorCallBack& before, const TensorCallBack& end, bool sync = false) const;
```
该函数本质上与`runSession`一致，但是提供了用户hook函数的接口，在运行session做网络推理，每层推理前前后会执行的`before`和`end`并根据返回值来决定是否继续执行

参数：
- `session` 执行推理的Session对象
- `before` 每层推理前执行的回调函数，类型为
  ```cpp
  std::function<bool(const std::vector<Tensor*>&, const std::string& /*opName*/)>
  ```
- `end` 每层推理后执行的回调函数，类型同上
- `sync` 是否同步等待执行完成

返回：执行推理的[错误码](Interpreter.html#errorcode)

---
### runSessionWithCallBackInfo
```cpp
ErrorCode runSessionWithCallBackInfo(const Session* session, const TensorCallBackWithInfo& before,
                                     const TensorCallBackWithInfo& end, bool sync = false) const;
```
该函数与`runSessionWithCallBack`相似，但是回调函数中增加了Op的类型和计算量信息，可以用来评估模型的计算量

参数：
- `session` 执行推理的Session对象
- `before` 每层推理前执行的回调函数，类型为
  ```cpp
  std::function<bool(const std::vector<Tensor*>&, const OperatorInfo*)>
  ```
- `end` 每层推理后执行的回调函数，类型同上
- `sync` 是否同步等待执行完成

返回：执行推理的[错误码](Interpreter.html#errorcode)

---
### getSessionInput
```cpp
Tensor* getSessionInput(const Session* session, const char* name);
```
根据`name`返回模型指定会话的输入tensor；如果没有指定tensor名称，则返回第一个输入tensor

参数：
- `session` 持有推理会话数据的Session对象
- `name` Tensor的名称

返回：输入Tensor对象

---
### getSessionOutput
```cpp
Tensor* getSessionOutput(const Session* session, const char* name);
```
根据`name`返回模型指定会话的输出tensor；如果没有指定tensor名称，则返回第一个输出tensor

参数：
- `session` 持有推理会话数据的Session对象
- `name` Tensor的名称

返回：输出Tensor对象

---
### getSessionInfo
```cpp
bool getSessionInfo(const Session* session, SessionInfoCode code, void* ptr);
```
根据指定类型获取`Session`的信息

参数：
- `session` 要获取信息的Session对象
- `code` 获取的信息类型，使用[SessionInfoCode](Interpreter.html#sessioninfocode)
- `ptr` 将信息存储在该指针中

返回：是否支持获取`code`类型的信息

---
### getSessionOutputAll
```cpp
const std::map<std::string, Tensor*>& getSessionOutputAll(const Session* session) const;
```
返回模型指定会话的所有的输出tensor

参数：
- `session` 持有推理会话数据的Session对象

返回：所有的输出Tensor的名称和指针

---
### getSessionInputAll
```cpp
const std::map<std::string, Tensor*>& getSessionInputAll(const Session* session) const;
```
返回模型指定会话的所有的输入tensor

参数：
- `session` 持有推理会话数据的Session对象

返回：所有的输入Tensor的名称和指针

---
### resizeTensor
```cpp
void resizeTensor(Tensor* tensor, const std::vector<int>& dims);
```
改变tensor形状，并重新分配内存

参数：
- `tensor` 需要改变形状的Tensor对象，一般为输入tensor
- `dims` 新的形状
- `batch,channel,height,width` 新的形状各维度

返回：`void`

---
### getBackend
```cpp
const Backend* getBackend(const Session* session, const Tensor* tensor) const;
```
获取指定`tensor`创建时使用的后端`Backend`；可以在代码中使用该函数来判断当前`Session`的推理实际使用什么后端。

参数：
- `session` tensor相关的会话
- `tensor` 被创建的tensor

返回：创建指定tensor的后端，可能为`nullptr`

---
### bizCode
```cpp
const char* bizCode() const;
```
获取创建该解释器的模型中的`bizCode`

参数：
- `void`

返回：模型中的`bizCode`

---
### uuid
```cpp
const char* uuid() const;
```
获取创建该解释器的模型中的`uuid`

参数：
- `void`

返回：模型中的`uuid`