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(), которое извлекает хранимое значение или исключение.