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*, который им нужно хранить.

Пример

См. также