std::out_ptr_t
| Определено в заголовочном файле <memory>
|
||
template< class Smart, class Pointer, class... Args > class out_ptr_t; |
(начиная с C++23) | |
out_ptr_t используется для адаптации типов, таких как умные указатели, для внешних функций, которые выводят свои результаты через Pointer* (обычно T** для некоторого типа объекта T) или параметр void**.
out_ptr_t захватывает дополнительные аргументы при построении, обеспечивает хранилище для результата, в который записывается такая вышеупомянутая внешняя функция, и, наконец, сбрасывает адаптированный объект Smart с результатом и захваченными аргументами, когда он уничтожается.
out_ptr_t ведёт себя так, как будто он содержит следующие нестатические элементы данных:
- ссылка
Smart&, которая привязывается к адаптированному объекту при построении, - для каждого
TвArgs...элемент типаT, который является аргументом, захваченным при построении и используемым для сброса при уничтожении, и - подобъект-элемент, подходящий для хранения в нём
Pointerи предоставления объектаvoid*, где объектPointerилиvoid*обычно открывается внешней функции для повторной инициализации.
Пользователи могут контролировать, захватывается ли каждый аргумент для сброса копией или ссылкой, указав тип объекта или тип ссылки в Args... соответственно.
Параметры шаблона
| Smart | — | тип объекта (обычно умный указатель) для адаптации |
| Pointer | — | тип объекта (обычно сырой указатель), в который внешняя функция записывает свой результат |
| Args... | — | тип захваченных аргументов, используемых для сброса адаптированного объекта |
| Требования к типам | ||
-Pointer должен соответствовать требованиям NullablePointer.
| ||
-Программа некорректна, если Smart является специализацией std::shared_ptr и sizeof...(Args) == 0.
| ||
Специализации
В отличие от большинства шаблонов классов в стандартной библиотеке, программно-определяемые специализации out_ptr_t, которые зависят по крайней мере от одного программно-определяемого типа, не обязательно должны соответствовать требованиям основного шаблона.
Эта разрешение позволяет программно-определяемой специализации предоставлять сырой указатель, хранящийся в нестандартном умном указателе, внешним функциям.
Функции-элементы
(C++23) |
создаёт out_ptr_t (public функция-элемент) |
operator= [удалено](C++23) |
out_ptr_t не может быть присвоен (public функция-элемент) |
(C++23) |
сбрасывает адаптированный умный указатель (public функция-элемент) |
преобразует out_ptr_t в адрес хранилища для вывода (public функция-элемент) |
Функции, не являющиеся элементами
(C++23) |
создаёт out_ptr_t с ассоциированным умным указателем и сбрасывает аргументы (шаблон функции) |
Примечание
out_ptr_t ожидает, что сторонние функции не используют значение, на которое указывает Pointer, а только повторно инициализируют его. Значение умного указателя до адаптации не используется.
Типичное использование out_ptr_t это создание временных объектов с помощью std::out_ptr, что немедленно сбрасывает адаптированный умный указатель. Например, учитывая функцию установки и умный указатель соответствующего типа, объявленные с помощью int foreign_setter(T**); и std::unique_ptr<T, D> up; соответственно,
int foreign_setter(T**);
std::unique_ptr<T, D> up;
if (int ec = foreign_setter(std::out_ptr(up)))
return ec;
примерно эквивалентно
int foreign_setter(T**);
std::unique_ptr<T, D> up;
T* raw_p{};
int ec = foreign_setter(&raw_p);
up.reset(raw_p);
if (ec != 0)
return ec;
Не рекомендуется создавать объект out_ptr_t с длительностью хранения отличной от длительности автоматического хранения, поскольку такой код, скорее всего, создаст висячие ссылки и приведёт к неопределённому поведению при уничтожении.
out_ptr_t запрещает использование, которое сбрасывало бы std::shared_ptr без указания средства удаления, потому что оно вызвало бы std::shared_ptr::reset и заменило бы пользовательское средство удаления позже.
Захваченные аргументы обычно упаковываются в std::tuple<Args...>. Реализации могут использовать другой механизм для предоставления объекта Pointer или void*, который им необходим.
| Макрос Тестирования функциональности | Значение | Стандарт | Функциональность |
|---|---|---|---|
__cpp_lib_out_ptr |
202106L |
(C++23) | std::out_ptr, std::inout_ptr
|
Пример
| Этот раздел не завершён Причина: нет примера |
Смотрите также
(C++23) |
взаимодействует с внешними установщиками указателей, получает начальное значение указателя из умного указателя и сбрасывает его при уничтожении (шаблон класса) |
(C++11) |
умный указатель с уникальной семантикой владения объектом (шаблон класса) |
(C++11) |
умный указатель с семантикой владения разделяемым объектом (шаблон класса) |
