D.4.3. Шаблон класса std::packaged_task

Шаблон класса std::packaged_task упаковывает функцию или другой допускающий вызов объект, так что при вызове функции через экземпляр std::packaged_task результат сохраняется в виде асинхронного результата, который может быть получен с помощью объекта std::future.

Экземпляры std::packaged_task удовлетворяют требованиям концепций MoveConstructible и MoveAssignable, но не CopyConstructible и CopyAssignable.

Определение класса

template<typename FunctionType>

class packaged_task; // не определен

template<typename ResultType, typename... ArgTypes>

class packaged_task<ResultType(ArgTypes...)> {

public:

packaged_task() noexcept;

packaged_task(packaged_task&&) noexcept;

~packaged_task();

packaged_task& operator=(packaged_task&&) noexcept;

packaged_task(packaged_task const&) = delete;

packaged_task& operator=(packaged_task const&) = delete;

void swap(packaged_task&) noexcept;

template<typename Callable>

explicit packaged_task(Callable&& func);

template<typename Callable, typename Allocator>

packaged_task(

std::allocator_arg_t, const Allocator&, Callable&&);

bool valid() const noexcept;

std::future<ResultType> get_future();

void operator()(ArgTypes...);

void make_ready_at_thread_exit(ArgTypes...); void reset();

};

STD::PACKAGED_TASK , КОНСТРУКТОР ПО УМОЛЧАНИЮ

Конструирует объект std::packaged_task.

Объявление

packaged_task() noexcept;

Результат

Конструирует экземпляр std::packaged_task, с которым не ассоциировала ни задача, ни асинхронный результат.

Исключения

Нет.

STD::PACKAGED_TASK , КОНСТРУИРОВАНИЕ ИЗ ДОПУСКАЮЩЕГО ВЫЗОВ ОБЪЕКТА

Конструирует экземпляр std::packaged_task, с которым ассоциированы задача и асинхронный результат.

Объявление

template<typename Callable>

packaged_task(Callable&& func);

Предусловия

Должно быть допустимо выражение func(args...), где каждый элемент args-i в списке args... должен быть значением соответственного типа ArgTypes-i в списке ArgTypes.... Возвращаемое значение должно допускать преобразование в тип ResultType.

Результат

Конструирует экземпляр std::packaged_task, с которым ассоциированы еще не готовый асинхронный результат типа ResultType и задача типа Callable, полученная копированием func.

Исключения

Исключение типа std::bad_alloc, если конструктор не смог выделить память для асинхронного результата. Любое исключение, возбуждаемое копирующим или перемещающим конструктором Callable.

STD::PACKAGED_TASK , КОНСТРУИРОВАНИЕ ИЗ ДОПУСКАЮЩЕГО ВЫЗОВ ОБЪЕКТА С РАСПРЕДЕЛИТЕЛЕМ

Конструирует экземпляр std::packaged_task, с которым ассоциированы задача и асинхронный результат, применяя предоставленный распределитель для выделения памяти под асинхронный результат и задачу

Объявление

template<typename Allocator, typename Callable>

packaged_task(

std::allocator_arg_t, Allocator const& alloc, Callable&& func);

Предусловия

Должно быть допустимо выражение func(args...), где каждый элемент args-i в списке args... должен быть значением соответственного типа ArgTypes-i в списке ArgTypes.... Возвращаемое значение должно допускать преобразование в тип ResultType.

Результат

Конструирует экземпляр std::packaged_task, с которым ассоциированы еще не готовый асинхронный результат типа ResultType и задача типа Callable, полученная копированием func. Память под асинхронный результат и задачу выделяется с помощью распределителя alloc или его копии.

Исключения

Любое исключение, возбуждаемое распределителем в случае неудачной попытки выделить память под асинхронный результат или задачу. Любое исключение, возбуждаемое копирующим или перемещающим конструктором Callable.

STD::PACKAGED_TASK , ПЕРЕМЕЩАЮЩИЙ КОНСТРУКТОР

Конструирует один объект std::packaged_task из другого, передавая владение асинхронным результатом и задачей, ассоциированными с объектом other, вновь сконструированному.

Объявление

packaged_task(packaged_task&& other) noexcept;

Результат

Конструирует новый экземпляр std::packaged_task.

Постусловия

Асинхронный результат и задача, которые были ассоциированы с объектом other до вызова конструктора, ассоциируются со вновь сконструированным объектом std::packaged_task. С объектом other больше не связан никакой асинхронный результат.

Исключения

Нет.

STD::PACKAGED_TASK , ПЕРЕМЕЩАЮЩИЙ ОПЕРАТОР ПРИСВАИВАНИЯ

Передает владение ассоциированным асинхронным результатом от одного объекта std::packaged_task другому.

Объявление

packaged_task& operator=(packaged_task&& other) noexcept;

Результат

Передает владение асинхронным результатом и задачей, ассоциированными с объектом other, объекту *this и отбрасывает ранее ассоциированный асинхронный результат, как если бы было выполнено предложение std::packaged_task(other).swap(*this).

Постусловия

Асинхронный результат и задача, которые были ассоциированы с объектом other до вызова перемещающего оператора присваивания, ассоциируются с *this. С объектом other больше не связан никакой асинхронный результат.

Возвращаемое значение

*this

Исключения

Нет.

STD::PACKAGED_TASK::SWAP , ФУНКЦИЯ-ЧЛЕН

Обменивает владение асинхронными результатами, ассоциированными с двумя объектами std::packaged_task.

Объявление

void swap(packaged_task& other) noexcept;

Результат

Обменивает владение асинхронными результатами и задачами, ассоциированными с объектами other и *this.

Постусловия

Асинхронный результат и задача, которые были ассоциированы с объектом other до вызова swap (если таковые действительно были), ассоциируются с *this. Асинхронный результат и задача, которые были ассоциировать с объектом *this до вызова swap (если таковые действительно были), ассоциируются с other.

Исключения

Нет.

STD::PACKAGED_TASK , ДЕСТРУКТОР

Уничтожает объект std::packaged_task.

Объявление

~packaged_task();

Результат

Уничтожает *this. Если с *this ассоциирован асинхронный результат и в этом результате не хранится задача или исключение, то результат становится готов, причем в него помещается исключение std::future_error с кодом ошибки std::future_errc::broken_promise.

Исключения

Нет.

STD::PACKAGED_TASK::GET_FUTURE , ФУНКЦИЯ-ЧЛЕН

Извлекает экземпляр std::future для асинхронного результата, ассоциированного с *this.

Объявление

std::future<ResultType> get_future();

Предусловия

С *this ассоциирован асинхронный результат.

Возвращаемое значение

Экземпляр std::future для асинхронного результата, ассоциированного с *this.

Исключения

Исключение типа std::future_error с кодом ошибки std::future_errc::future_already_retrieved, если объект std::future уже был получен для этого асинхронного результата с помощью предшествующего обращения к get_future().

STD::PACKAGED_TASK::RESET , ФУНКЦИЯ-ЧЛЕН

Ассоциирует экземпляр std::packaged_task с новым асинхронным результатом для той же задачи.

Объявление

void reset();

Предусловия

С *this ассоциирована асинхронная задача.

Результат

Эквивалентно *this = packaged_task(std::move(f)), где f ― хранимая задача, ассоциированная с *this.

Исключения

Исключение типа std::bad_alloc, если не удалось выделить память для нового асинхронного результата.

STD::PACKAGED_TASK::VALID , ФУНКЦИЯ-ЧЛЕН

Проверяет, ассоциированы ли с *this задача и асинхронный результат.

Объявление

bool valid() const noexcept;

Возвращаемое значение

true, если с *this ассоциированы задача и асинхронный результат, иначе false.

Исключения

Нет.

STD::PACKAGED_TASK::OPERATOR() , ОПЕРАТОР ВЫЗОВА

Вызывает задачу, ассоциированную с экземпляром std::packaged_task, и сохраняет возвращенное ей значение или исключение в ассоциированном асинхронном результате.

Объявление

void operator()(ArgTypes... args);

Предусловия

С *this ассоциирована задача.

Результат

Вызывает ассоциированную задачу, как если бы было выполнено предложение INVOKE(func, args...). Если вызов завершается нормально, то сохраняет возвращенное значение в асинхронном результате, ассоциированном с *this. Если задача возбуждает исключение, то сохраняет это исключение в асинхронном результате, ассоциированном с *this.

Постусловия

Асинхронный результат, ассоциированный с *this, готов и содержит значение или исключение. Все потоки, ожидающие асинхронного результата, разблокируются.

Исключения

Исключение типа std::future_error с кодом ошибки std::future_errc::promise_already_satisfied, если в асинхронном результате уже находится значение или исключение.

Синхронизация

Успешное обращение к оператору вызова синхронизируется-с обращением к std::future<ResultType>::get() или std::shared_future<ResultType>::get(), которое извлекает хранимое значение или исключение.

STD::PACKAGED_TASK::MAKE_READY_AT_THREAD_EXIT , ФУНКЦИЯ-ЧЛЕН

Вызывает задачу, ассоциированную с экземпляром std::packaged_task, и сохраняет возвращенное ей значение или исключение в ассоциированном асинхронном результате, но не делает этот результат готовым раньше момента завершения потока.

Объявление

void make_ready_at_thread_exit(ArgTypes... args);

Предусловия

С *this ассоциирована задача.

Результат

Вызывает ассоциированную задачу, как если бы было выполнено предложение INVOKE(func, args...). Если вызов завершается нормально, то сохраняет возвращенное значение в асинхронном результате, ассоциированном с *this. Если задача возбуждает исключение, то сохраняет это исключение в асинхронном результате, ассоциированном с *this. Планирует перевод ассоциированного асинхронного результата в состояние готовности в момент завершения потока.

Постусловия

Асинхронный результат, ассоциированный с *this, содержит значение или исключение, но не является готовым до завершения текущего потока. Все потоки, ожидающие асинхронного результата, будут разблокированы, когда текущий поток завершится.

Исключения

Исключение типа std::future_error с кодом ошибки std::future_errc::promise_already_satisfied, если в асинхронном результате уже находится значение или исключение. Исключение типа std::future_error с кодом ошибки std::future_errc::no_state, если с *this не ассоциировано асинхронное состояние. Синхронизация

Завершение потока, в котором была успешно вызвала функция make_ready_at_thread_exit(), синхронизируется-с обращением к std::future<ResultType>::get() или std::shared_future<ResultType>::get(), которое извлекает хранимое значение или исключение.