D.4.4. Шаблон класса std::promise
Шаблон класса std::promise предоставляет средства для установки асинхронного результата, который может быть получен в другом потоке с помощью экземпляра std::future.
Параметр ResultType — это тип значения, сохраняемого в асинхронном результате.
Объект std::future, ассоциированный с асинхронным результатом конкретного экземпляра std::promise, можно получить путем обращения к функции-члену get_future(). В асинхронный результат записывается либо значение типа ResultType функцией-членом set_value(), либо исключение функцией-членом set_exception().
Экземпляры std::promise удовлетворяют требованиям концепций MoveConstructible и MoveAssignable, но не CopyConstructible или CopyAssignable.
Определение класса
template<typename ResultType>
class promise {
public:
promise();
promise(promise&&) noexcept;
~promise();
promise& operator=(promise&&) noexcept;
template<typename Allocator>
promise(std::allocator_arg_t, Allocator const&);
promise(promise const&) = delete;
promise& operator=(promise const&) = delete;
void swap(promise&) noexcept;
std::future<ResultType> get_future();
void set_value(see description);
void set_exception(std::exception_ptr p);
};
STD::PROMISE , КОНСТРУКТОР ПО УМОЛЧАНИЮ
Конструирует объект std::promise.
Объявление
promise();
Результат
Конструирует экземпляр std::promise, с которым ассоциировал неготовый асинхронный результат типа ResultType.
Исключения
Исключение типа std::bad_alloc, если конструктор не смог выделить память для асинхронного результата.
STD::PROMISE , КОНСТРУКТОР С РАСПРЕДЕЛИТЕЛЕМ
Конструирует экземпляр std::promise, применяя предоставленный распределитель для выделения памяти под ассоциированный асинхронный результат.
Объявление
template<typename Allocator>
promise(std::allocator_arg_t, Allocator const& alloc);
Результат
Конструирует экземпляр std::promise, с которым ассоциировал неготовый асинхронный результат типа ResultType. Память под асинхронный результат выделяется с помощью распределителя alloc.
Исключения
Любое исключение, возбуждаемое распределителем в случае неудачной попытки выделить память под асинхронный результат.
STD::PROMISE , ПЕРЕМЕЩАЮЩИЙ КОНСТРУКТОР
Конструирует один объект std::promise из другого, передавая владение асинхронным результатом от объекта other вновь сконструированному.
Объявление
promise(promise&& other) noexcept;
Результат
Конструирует новый экземпляр std::promise.
Постусловия
Асинхронный результат, который был ассоциирован с объектом other до вызова конструктор, ассоциируется с вновь сконструированным объектом std::promise. С объектом other больше не ассоциирован никакой асинхронный результат.
Исключения
Нет.
STD::PROMISE , ПЕРЕМЕЩАЮЩИЙ ОПЕРАТОР ПРИСВАИВАНИЯ
Передает владение асинхронным результатом, ассоциированным с объектом std::promise, другому объекту.
Объявление
promise& operator=(promise&& other) noexcept;
Результат
Передает владение асинхронным результатом, ассоциированным с *this. Если с *this уже был ассоциирован асинхронный результат, то результат становится готов, причем в него помещается исключение std::future_error с кодом ошибки std::future_errc::broken_promise.
Постусловия
Асинхронный результат, который был ассоциирован с объектом other до вызова перемещающего оператора присваивания, ассоциируется с *this. С объектом other больше не ассоциирован никакой асинхронный результат.
Возвращаемое значение
*this
Исключения
Нет.
STD::PROMISE::SWAP , ФУНКЦИЯ-ЧЛЕН
Обменивает владение асинхронными результатами, ассоциированными с двумя объектами std::promise.
Объявление
void swap(promise& other);
Результат
Обменивает владение асинхронными результатами, ассоциированными с объектами other и *this.
Постусловия
Асинхронный результат, который был ассоциирован с объектом other до вызова swap (если таковой действительно был), ассоциируется с *this. Асинхронный результат, который был ассоциирован с объектом *this до вызова swap (если таковой действительно был), ассоциируется с other.
Исключения
Нет.
STD::PROMISE , ДЕСТРУКТОР
Уничтожает объект std::promise.
Объявление
~promise();
Результат
Уничтожает *this. Если с *this ассоциирован асинхронный результат и в этом результате не хранится задача или исключение, то результат становится готов, причем в него помещается исключение std::future_error с кодом ошибки std::future_errc::broken_promise.
Исключения
Нет.
STD::PROMISE::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::PROMISE::SET_VALUE , ФУНКЦИЯ-ЧЛЕН
Сохраняет значение в асинхронном результате, ассоциированном с *this.
Объявление
void promise<void>::set_value();
void promise<R&>::set_value(R& r);
void promise<R>::set_value(R const& r);
void promise<R>::set_value(R&& r);
Предусловия
С *this ассоциирован асинхронный результат.
Результат
Сохраняет r в асинхронном результате, ассоциированном с *this, если ResultType — не void.
Постусловия
Асинхронный результат, ассоциированный с *this, готов и содержит значение. Все потоки, ожидающие асинхронного результата, разблокируются.
Исключения
Исключение типа std::future_error с кодом ошибки std::future_errc::promise_already_satisfied, если в асинхронном результате уже находится значение или исключение. Любое исключение, возбужденное копирующим или перемещающим конструктором r.
Синхронизация
Обращения к set_value(), set_value_at_thread_exit(), set_exception() и set_exception_at_thread_exit() сериализуются. Успешное обращение к set_value() происходит-раньше обращения к функции std::future<ResultType>::get() или std::shared_future<ResultType>::get(), которая извлекает сохраненное значение.
STD::PROMISE::SET_VALUE_AT_THREAD_EXIT , ФУНКЦИЯ-ЧЛЕН
Сохраняет значение в асинхронном результате, ассоциированном с *this, но не делает этот результат готовым раньше момента завершения потока.
Объявление
void promise<void>::set_value_at_thread_exit();
void promise<R&>::set_value_at_thread_exit(R& r);
void promise<R>::set_value_at_thread_exit(R const& r);
void promise<R>::set_value_at_thread_exit(R&& r);
Предусловия
С *this ассоциирован асинхронный результат.
Результат
Сохраняет r в асинхронном результате, ассоциированном с *this, если ResultType — не void. Помечает, что в асинхронном результате хранится значение. Планирует перевод ассоциированного асинхронного результата в состояние готовности в момент завершения потока.
Постусловия
Асинхронный результат, ассоциированный с *this, содержит значение, но не является готовым до завершения текущего потока. Все потоки, ожидающие асинхронного результата, будут разблокированы, когда текущий поток завершится.
Исключения
Исключение типа std::future_error с кодом ошибки std::future_errc::promise_already_satisfied, если в асинхронном результате уже находится значение или исключение. Любое исключение, возбужденное копирующим или перемещающим конструктором r.
Синхронизация
Обращения к set_value(), set_value_at_thread_exit(), set_exception() и set_exception_at_thread_exit() сериализуются. Успешное обращение к set_value() происходит-раньше обращения к функции std::future<ResultType>::get() или std::shared_future<ResultType>::get(), которая извлекает сохраненное значение.
STD::PROMISE::SET_EXCEPTION , ФУНКЦИЯ-ЧЛЕН КЛАССА
Сохраняет исключение в асинхронном результате, ассоциированном с *this.
Объявление
void set_exception(std::exception_ptr e);
Предусловия
С *this ассоциирован асинхронный результат. (bool)e равно true.
Результат
Сохраняет e в асинхронном результате, ассоциированном с *this.
Постусловия
Асинхронный результат, ассоциированный с *this, готов и содержит исключение. Все потоки, ожидающие асинхронного результата, разблокируются.
Исключения
Исключение типа std::future_error с кодом ошибки std::future_errc::promise_already_satisfied, если в асинхронном результате уже находится значение или исключение.
Синхронизация
Обращения к set_value(), set_value_at_thread_exit(), set_exception() и set_exception_at_thread_exit() сериализуются. Успешное обращение к set_value() происходит-раньше обращения к функции std::future<ResultType>::get() или std::shared_future<ResultType>::get(), которая извлекает сохраненное исключение.
STD::PROMISE::SET_EXCEPTION_AT_THREAD_EXIT, ФУНКЦИЯ-ЧЛЕН
Сохраняет исключение в асинхронном результате, ассоциированном с *this, но не делает этот результат готовым раньше момента завершения потока.
Объявление
void set_exception_at_thread_exit(std::exception_ptr e);
Предусловия
С *this ассоциирован асинхронный результат, (bool)e равно true.
Результат
Сохраняет e в асинхронном результате, ассоциированном с *this. Планирует перевод ассоциированного асинхронного результата в состояние готовности в момент завершения потока.
Постусловия
Асинхронный результат, ассоциированный с *this, содержит исключение, но не является готовым до завершения текущего потока. Все потоки, ожидающие асинхронного результата, будут разблокированы, когда текущий поток завершится. Исключения
Исключение типа std::future_error с кодом ошибки std::future_errc::promise_already_satisfied, если в асинхронном результате уже находится значение или исключение.
Синхронизация
Обращения к set_value(), set_value_at_thread_exit(), set_exception() и set_exception_at_thread_exit() сериализуются. Успешное обращение к set_value() происходит-раньше обращения к функции std::future<ResultType>::get() или std::shared_future<ResultType>::get(), которая извлекает сохраненное исключение.