std::out_ptr_t

template< class Smart, class Pointer, class... Args >
class out_ptr_t;

out_ptr_t используется для адаптации типов, таких как умные указатели, для внешних функций, которые выдают свои результаты через Pointer* (обычно T** для некоторого типа объекта T) или параметр void**.

out_ptr_t захватывает дополнительные аргументы при создании, предоставляет хранилище для результата, в который такая внешняя функция записывает, и, наконец, сбрасывает адаптированный объект Smart с результатом и захваченными аргументами при уничтожении.

out_ptr_t ведет себя так, как будто он содержит следующие нестатические данные-члены:

• ссылку на Smart&, которая привязана к адаптированному объекту при создании,
• для каждого T в Args..., член типа T, который является аргументом, захваченным при создании и используемым для сброса при уничтожении, и
• подобъект, подходящий для хранения Pointer внутри него и предоставления объекта void*, где объект Pointer или void* в общем случае предоставляется внешней функции для повторной инициализации.

Пользователи могут управлять тем, как каждый аргумент для сброса захватывается — по значению или по ссылке, указав тип объекта или тип ссылки в Args... соответственно.

Параметры шаблона

Специализации

В отличие от большинства шаблонов классов в стандартной библиотеке, пользовательские специализации 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*.

Пример

См. также