17-02 共享队列管理
本章节描述共享队列管理接口，用于队列的创建、销毁、入队、出队及路由管理。
aclError acltdtCreateQueue(const acltdtQueueAttr *attr, uint32_t *qid)：创建队列。aclError acltdtDestroyQueue(uint32_t qid)：销毁通过acltdtCreateQueue接口创建的队列。aclError acltdtEnqueueData(uint32_t qid, const void *data, size_t dataSize, const void *userData, size_t userDataSize, int32_t timeout, uint32_t rsv)：向队列中添加数据。aclError acltdtDequeueData(uint32_t qid, void *data, size_t dataSize, size_t *retDataSize, void *userData, size_t userDataSize, int32_t timeout)：从队列中获取数据。aclError acltdtEnqueue(uint32_t qid, acltdtBuf buf, int32_t timeout)：向队列中添加数据，存放数据的内存必须调用acltdtAllocBuf接口申请。aclError acltdtDequeue(uint32_t qid, acltdtBuf *buf, int32_t timeout)：从队列中获取数据。aclError acltdtBindQueueRoutes(acltdtQueueRouteList *qRouteList)：当应用存在数据一对多分发时，通过本接口绑定队列间数据转发路由关系。aclError acltdtUnbindQueueRoutes(acltdtQueueRouteList *qRouteList)：解绑定数据队列路由关系。aclError acltdtQueryQueueRoutes(const acltdtQueueRouteQueryInfo *queryInfo, acltdtQueueRouteList *qRouteList)：根据指定条件查询数据队列路由关系。aclError acltdtGrantQueue(uint32_t qid, int32_t pid, uint32_t permission, int32_t timeout)：进程间需要共享队列信息时，可以调用本接口给其它进程授予队列相关的权限，例如Enqueue（指向队列中添加数据）权限、Dequeue（指从队列中获取数据）权限等。aclError acltdtAttachQueue(uint32_t qid, int32_t timeout, uint32_t *permission)：进程间需要共享队列信息时，在被授权的进程中调用本接口确认当前进程对队列有相应权限。
acltdtCreateQueue
aclError acltdtCreateQueue(const acltdtQueueAttr *attr, uint32_t *qid)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
创建队列。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| attr | 输入 | 队列属性配置信息的指针。类型定义请参见acltdtQueueAttr。 需提前调用acltdtCreateQueueAttr接口创建acltdtQueueAttr类型的数据，再调用acltdtSetQueueAttr接口设置队列属性值（例如，队列名）。 若该参数为nullptr时，则使用队列属性默认值，即队列名系统自动分配，队列深度默认为8。 |
| qid | 输出 | 队列ID的指针。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
acltdtDestroyQueue
aclError acltdtDestroyQueue(uint32_t qid)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
销毁通过acltdtCreateQueue接口创建的队列。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| qid | 输入 | 指定需销毁的队列。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
acltdtEnqueueData
aclError acltdtEnqueueData(uint32_t qid, const void *data, size_t dataSize, const void *userData, size_t userDataSize, int32_t timeout, uint32_t rsv)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
向队列中添加数据。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| qid | 输入 | 需要添加数据的队列。 队列需提前调用acltdtCreateQueue接口创建。 |
| data | 输入 | 内存数据指针，支持Host侧或Device侧的内存。 |
| dataSize | 输入 | 内存数据大小，单位为Byte。 |
| userData | 输入 | 用户自定义数据指针。 若用户没有自定义数据，则传nullptr。 |
| userDataSize | 输入 | 用户自定义数据大小（<=96Byte）。 若用户没有自定义数据，则传0。 |
| timeout | 输入 | 等待超时时间。当队列满时，如果向队列中添加数据，系统内部会根据设置的等待超时时间来决定如何处理。 该参数取值范围如下： - -1：阻塞方式，一直等待直到数据成功加入队列。 - 0：非阻塞方式（仅支持Device场景，Host场景无效），当队列满时，直接返回队列满这个错误，这时由用户自行设定重试间隔。 - >0：配置具体的超时时间，单位为毫秒。队列满时，等待达到超时时间后返回报错。超时时间受操作系统影响，一般偏差在操作系统的一个时间片内，例如，操作系统的一个时间片为4ms，用户设置的超时时间为1ms，则实际的超时时间在1ms到5ms范围内。在CPU负载高场景下，超时时间仍可能存在波动。 |
| rsv | 输入 | 预留参数，暂不支持。当前可设置为0。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
acltdtDequeueData
aclError acltdtDequeueData(uint32_t qid, void *data, size_t dataSize, size_t *retDataSize, void *userData, size_t userDataSize, int32_t timeout)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
从队列中获取数据。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| qid | 输入 | 需要从哪个队列中获取数据。 队列需提前调用acltdtCreateQueue接口创建。 |
| data | 输入&输出 | 内存数据指针。 支持Host侧或Device侧的内存。 |
| dataSize | 输入 | 内存数据大小，单位为Byte。 |
| retDataSize | 输出 | 返回实际数据大小，单位为Byte。 |
| userData | 输入&输出 | 用户自定义数据指针。 若用户没有自定义数据，则传nullptr。 |
| userDataSize | 输入 | 用户自定义数据大小（<=96Byte）。 若用户没有自定义数据，则传0。 |
| timeout | 输入 | 等待超时时间。当队列空时，如果从队列中获取数据，系统内部会根据设置的等待超时时间来决定如何处理。 该参数取值范围如下： - -1：阻塞方式，一直等待直到队列有数据后返回。 - 0：非阻塞方式（仅支持Device场景，Host场景无效），当队列空时，直接返回队列空这个错误，这时由用户自行设定重试间隔。 - >0：配置具体的超时时间，单位为毫秒。队列空时，等待达到超时时间后返回报错。超时时间受操作系统影响，一般偏差在操作系统的一个时间片内，例如，操作系统的一个时间片为4ms，用户设置的超时时间为1ms，则实际的超时时间在1ms到5ms范围内。在CPU负载高场景下，超时时间仍可能存在波动。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
acltdtEnqueue
aclError acltdtEnqueue(uint32_t qid, acltdtBuf buf, int32_t timeout)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
向队列中添加数据，存放数据的内存必须调用acltdtAllocBuf接口申请。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| qid | 输入 | 需要添加数据的队列。 队列需提前调用acltdtCreateQueue接口创建。 |
| buf | 输入 | 共享Buffer指针。类型定义请参见acltdtBuf。 该内存必须提前调用acltdtAllocBuf接口申请。 |
| timeout | 输入 | 等待超时时间。当队列满时，如果向队列中添加数据，系统内部会根据设置的等待超时时间来决定如何处理。 该参数取值范围如下： - -1：阻塞方式，一直等待直到数据成功加入队列。 - 0：非阻塞方式，当队列满时，直接返回队列满这个错误，这时由用户自行设定重试间隔。 - >0：配置具体的超时时间，单位为毫秒。队列满时，等待达到超时时间后返回报错。超时时间受操作系统影响，一般偏差在操作系统的一个时间片内，例如，操作系统的一个时间片为4ms，用户设置的超时时间为1ms，则实际的超时时间在1ms到5ms范围内。在CPU负载高场景下，超时时间仍可能存在波动。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
acltdtDequeue
aclError acltdtDequeue(uint32_t qid, acltdtBuf *buf, int32_t timeout)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
从队列中获取数据。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| qid | 输入 | 需要从哪个队列中获取数据。 队列需提前调用acltdtCreateQueue接口创建。 |
| buf | 输出 | 共享Buffer指针。类型定义请参见acltdtBuf。 |
| timeout | 输入 | 等待超时时间。当队列空时，如果从队列中获取数据，系统内部会根据设置的等待超时时间来决定如何处理。 该参数取值范围如下： - -1：阻塞方式，一直等待直到队列有数据后返回。 - 0：非阻塞方式，当队列空时，直接返回队列空这个错误，这时由用户自行设定重试间隔。 - >0：配置具体的超时时间，单位为毫秒。队列空时，等待达到超时时间后返回报错。超时时间受操作系统影响，一般偏差在操作系统的一个时间片内，例如，操作系统的一个时间片为4ms，用户设置的超时时间为1ms，则实际的超时时间在1ms到5ms范围内。在CPU负载高场景下，超时时间仍可能存在波动。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
acltdtBindQueueRoutes
aclError acltdtBindQueueRoutes(acltdtQueueRouteList *qRouteList)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
当应用存在数据一对多分发时，通过本接口绑定队列间数据转发路由关系。
如下图所示，可以建立两条路由关系Q1->Q2，Q1->Q3。数据一对多分发时，传递的共享Buffer数据是无锁的，消费者不能对数据进行inplace操作，如下图所示消费者1对共享数据的修改会导致消费者2访问的数据发生变化。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| qRouteList | 输入/输出 | 路由关系数组的指针，接口调用完成后返回路由绑定结果。类型定义请参见acltdtQueueRouteList。 需提前调用acltdtCreateQueueRouteList接口创建acltdtQueueRouteList类型的数据，再调用acltdtAddQueueRoute接口添加路由关系。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
只有当所有队列关系绑定成功且路由状态正常时，本接口才会返回成功；任何一条绑定失败，本接口返回失败，如果您需要知道具体哪个路由关系绑定失败，您可以先调用acltdtGetQueueRoute接口从路由关系数组中获取每一个路由关系，再调用acltdtGetQueueRouteParam接口查询绑定关系状态。
约束说明
- 系统内部会校验添加的队列路由关系是否成环，不允许成环。
- 不支持多线程并发调用。
acltdtUnbindQueueRoutes
aclError acltdtUnbindQueueRoutes(acltdtQueueRouteList *qRouteList)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
解绑定数据队列路由关系。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| qRouteList | 输入/输出 | 路由关系数组的指针，接口调用完成后返回路由解绑定结果。类型定义请参见acltdtQueueRouteList。 可先通过acltdtQueryQueueRoutes获取路由关系数组。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
只有当所有队列关系解绑定成功，本接口才会返回成功；任何一条解绑定失败，本接口返回失败，如果您需要知道具体哪个路由关系解绑定失败，您可以先调用acltdtGetQueueRoute接口从路由关系数组中获取每一个路由关系，再调用acltdtGetQueueRouteParam接口查询绑定关系状态。
acltdtQueryQueueRoutes
aclError acltdtQueryQueueRoutes(const acltdtQueueRouteQueryInfo *queryInfo, acltdtQueueRouteList *qRouteList)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
根据指定条件查询数据队列路由关系。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| queryInfo | 输入 | 查询条件的指针。类型定义请参见acltdtQueueRouteQueryInfo。 需提前调用acltdtCreateQueueRouteQueryInfo接口创建acltdtQueueRouteQueryInfo类型的数据。 |
| qRouteList | 输入&输出 | 路由关系数组的指针。类型定义请参见acltdtQueueRouteList。 需提前调用acltdtCreateQueueRouteList接口创建acltdtQueueRouteList类型的数据。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
acltdtGrantQueue
aclError acltdtGrantQueue(uint32_t qid, int32_t pid, uint32_t permission, int32_t timeout)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
进程间需要共享队列信息时，可以调用本接口给其它进程授予队列相关的权限，例如Enqueue（向队列中添加数据）权限、Dequeue（从队列中获取数据）权限等。
进程间传递队列相关信息时，安全性由用户保证。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| qid | 输入 | 队列ID。 |
| pid | 输入 | 被授权进程的ID。 |
| permission | 输入 | 权限标识（队列生产者/消费者）。 用户选择如下多个宏进行逻辑或（例如：ACL_TDT_QUEUE_PERMISSION_DEQUEUE | ACL_TDT_QUEUE_PERMISSION_ENQUEUE），作为permission参数值。每个宏表示某一权限，详细说明如下： - ACL_TDT_QUEUE_PERMISSION_MANAGE：表示队列的管理权限。 - ACL_TDT_QUEUE_PERMISSION_DEQUEUE：表示Dequeue权限。 - ACL_TDT_QUEUE_PERMISSION_ENQUEUE：表示Enqueue权限。 |
| timeout | 输入 | 等待超时时间，取值范围如下： - -1：阻塞方式，一直等待直到数据成功加入队列。 - 0：非阻塞方式，立即返回。 - >0：配置具体的超时时间，单位为毫秒，等达到超时时间后返回报错。超时时间受操作系统影响，一般偏差在操作系统的一个时间片内，例如，操作系统的一个时间片为4ms，用户设置的超时时间为1ms，则实际的超时时间在1ms到5ms范围内。在CPU负载高场景下，超时时间仍可能存在波动。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
acltdtAttachQueue
aclError acltdtAttachQueue(uint32_t qid, int32_t timeout, uint32_t *permission)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
进程间需要共享队列信息时，在被授权的进程中调用本接口确认当前进程对队列有相应权限。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| qid | 输入 | 队列ID。 |
| timeout | 输入 | 等待超时时间，取值范围如下： - -1：阻塞方式，一直等待直到数据成功加入队列。 - 0：非阻塞方式，立即返回。 - >0：配置具体的超时时间，单位为毫秒，等达到超时时间后返回报错。超时时间受操作系统影响，一般偏差在操作系统的一个时间片内，例如，操作系统的一个时间片为4ms，用户设置的超时时间为1ms，则实际的超时时间在1ms到5ms范围内。在CPU负载高场景下，超时时间仍可能存在波动。 |
| permission | 输出 | 权限标识。 - 根据输出参数值的最后一个bit位判断是否有管理权限，0就是没有，1就是有。 - 根据输出参数值的倒数第二个bit位判断是否有从队列中获取数据的权限，0就是没有，1就是有。 - 根据输出参数值的倒数第三个bit位判断是否有向队列中添加数据的权限，0就是没有，1就是有。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。