std::inout_ptr_t

来自cppreference.com
< cpp‎ | memory
 
 
工具库
通用工具
日期和时间
函数对象
格式化库 (C++20)
(C++11)
关系运算符 (C++20 中弃用)
整数比较函数
(C++20)(C++20)(C++20)
(C++20)
swap 与类型运算
(C++14)
(C++11)
(C++11)
(C++11)
(C++17)
常用词汇类型
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++17)
(C++23)
初等字符串转换
(C++17)
(C++17)
 
动态内存管理
未初始化内存算法
受约束的未初始化内存算法
分配器
垃圾收集支持
(C++11)(C++23 前)
(C++11)(C++23 前)
(C++11)(C++23 前)
(C++11)(C++23 前)
(C++11)(C++23 前)
(C++11)(C++23 前)



 
std::inout_ptr_t
 
在标头 <memory> 定义
template< class Smart, class Pointer, class... Args >
class inout_ptr_t;
(C++23 起)

inout_ptr_t 用于对通过 Pointer* (通常为某对象类型 TT** )或 void** 参数重设所有权的外来函数,适配智能指针之类的类型。

inout_ptr_t 在构造时捕获额外的实参,为前述的这种外来函数访问的结果提供存储,释放适配的 Smart 对象所保有的所有权,而最终在销毁时以该结果和捕获的实参重设适配的 Smart 对象。

inout_ptr_t 表现如同它拥有下列非静态数据成员:

  • 一个 Smart& 引用,在构造时绑定到被适配的对象,
  • Args... 中的每个 T 有一个 T 类型成员,它是在构造时捕获并在析构时用于重设的实参,以及
  • 适合在其内存储 Pointer 以及提供 void* 对象的成员子对象,其中 Pointervoid* 对象通常会暴露给用于重初始化的外来函数。

Smart 不是指针类型,则在适配的对象上至多调用一次 release() 。实现可以在构造函数内或调用 release() ,或在析构函数内若 Pointer 值非空则在重设前调用。

用户能通过在 Args... 中分别指定对象类型或引用类型,控制每个参数是按复制还是按引用捕获。

模板形参

Smart - 要适配的对象(常为智能指针)的类型
Pointer - 外来函数写入其结果所用的对象(常为裸指针)的类型
Args... - 用于重设适配的对象的捕获实参的类型
类型要求
-
Pointer 必须符合可空指针 (NullablePointer) 的要求。
-
Smartstd::shared_ptr 特化则程序非良构。

特化

不同于标准库中的大多数类模板,依赖于至少一个程序定义类型的 inout_ptr_t 程序定义特化不需要符合对主模板的要求。

此许可允许程序定义特化将存储于非标准智能指针内的裸指针暴露给外来函数。

成员函数

构造 inout_ptr_t
(公开成员函数)
operator=
[被删除](C++23)
inout_ptr_t 不可赋值
(公开成员函数)
重设适配的智能指针
(公开成员函数)
转换 inout_ptr_t 为用于输出的存储的地址
(公开成员函数)

非成员函数

(C++23)
以关联的智能指针和重设参数创建 inout_ptr_t
(函数模板)

注解

inout_ptr_t 期待外来函数释放被指向的 Pointer 的值所表示的所有权,然后重初始化它。禁止带 std::shared_ptr 的用法,因为这种操作要求独占所有权。

inout_ptr_t 的典型用法是由 std::inout_ptr 创建其临时对象,这会立即重设智能指针。例如,给定设置器函数和智能指针,分别以 int foreign_resetter(T**);std::unique_ptr<T, D> up; 声明,

if (int ec = foreign_resetter(std::inout_ptr(up)) {
    return ec;
}

粗略地等价于

T *raw_p = up.get();
up.release();
int ec = foreign_resetter(&raw_p);
up.reset(raw_p);
if (ec != 0) {
    return ec;
}

不推荐创建拥有自动存储期以外的存储期inout_ptr_t 对象,因为这种代码较可能产生悬垂引用并在析构时导致未定义行为。

捕获的参数常被打包到 std::tuple<Args...> 中。实现可能用不同的机制提供他们需要保有的 Pointervoid* 对象。

示例

参阅

(C++23)
与外来指针设置器交互,并在析构时重设智能指针
(类模板)
拥有独有对象所有权语义的智能指针
(类模板)
拥有共享对象所有权语义的智能指针
(类模板)