PR_PushIOLayer

在堆栈上添加一层。

语法

#include <prio.h>

PRStatus PR_PushIOLayer(
  PRFileDesc *stack,
  PRDescIdentity id,
  PRFileDesc *layer);

参数

该函数具有以下参数

stack

指向一个表示堆栈的 PRFileDesc 对象的指针。

id

堆栈上层之上的层的 PRDescIdentity 对象，新层将添加到该层之上。

layer

指向一个表示要添加到堆栈的新层的 PRFileDesc 对象的指针。

返回值

该函数返回以下值之一

  • 如果层成功推送到堆栈上，则返回 PR_SUCCESS。

  • 如果层未成功推送到堆栈上，则返回 PR_FAILURE。使用 PR_GetError 获取有关失败原因的更多信息。

描述

任何时候都可以将一个层的 文件描述符（可能使用 PR_CreateIOLayerStub 分配）推送到现有的文件描述符堆栈上。新层插入到堆栈中，正好位于由 id 指定的标识的层之上。

即使 id 参数指示堆栈的最顶层，描述原始堆栈的文件描述符的值也不会改变。换句话说，在函数返回后，stack 继续指向堆栈的顶部。

注意事项

即使在将层推送到堆栈顶部时，也通过交换正在推送的文件描述符的内容和堆栈当前顶层文件描述符的内容来实现保持指向堆栈的指针。

目的是即使有人（可能是暗中）推入其他层，指向堆栈的指针也仍然是堆栈的标识。一些细微的影响

  • 调用方 layer 参数指向的存储的所有权被放弃给运行时。在运行时拥有该对象时，不允许通过该指针访问该对象。访问该对象的正确机制是通过调用 PR_GetIdentitiesLayer 获取指向它的指针。

  • 调用方对象的內容被交换到另一个容器中，包括对对象析构函数的引用。如果原始容器使用与运行时使用的不同的机制分配，则运行时默认调用层的析构函数将失败（PR_CreateIOLayerStub 用于分配层对象和模板实现）。当堆栈关闭时，将对所有层调用析构函数（参见 PR_Close）。如果容器通过某些方法而不是 PR_CreateIOLayerStub 分配，则可能需要在调用 PR_Close 之前从堆栈中弹出层（按推送的相反顺序）。