D.4.1. Шаблон класса std::future
Шаблон класса std::future предоставляет средства для ожидания результата асинхронной операции, начатой в другом потоке, и используется в сочетании с шаблонами классов std::promise и std::packaged_task и шаблоном функции std::async, которая применяется для возврата асинхронного результата. В каждый момент времени только один экземпляр std::future может ссылаться на данный асинхронный результат.
Экземпляры std::future удовлетворяют требованиям концепций MoveConstructible и MoveAssignable, но не концепций CopyConstructible и CopyAssignable.
Определение класса
template<typename ResultType>
class future {
public:
future() noexcept;
future(future&&) noexcept;
future& operator=(future&&) noexcept;
~future();
future(future const&) = delete;
future& operator=(future const&) = delete;
shared_future<ResultType> share();
bool valid() const noexcept;
см. описание get();
void wait();
template<typename Rep, typename Period>
future_status wait_for(
std::chrono::duration<Rep, Period> const& relative_time);
template<typename Clock, typename Duration>
future_status wait_until(
std::chrono::time_point<Clock, Duration> const& absolute_time);
};
STD::FUTURE , КОНСТРУКТОР ПО УМОЛЧАНИЮ
Конструирует объект std::future, с которым не связан асинхронный результат.
Объявление
future() noexcept;
Результат
Конструирует новый экземпляр std::future.
Постусловия
valid() возвращает false.
Исключения
Нет.
STD::FUTURE , ПЕРЕМЕЩАЮЩИЙ КОНСТРУКТОР
Конструирует объект std::future, передавая владение асинхронным результатом от другого объекта std::future вновь сконструированному.
Объявление
future(future&& other) noexcept;
Результат
Конструирует новый экземпляр std::future путем перемещения содержимого объекта other.
Постусловия
Асинхронный результат, ассоциированный с объектом other перед вызовом конструктора, ассоциируется с вновь сконструированным объектом std::future. С объектом other больше не ассоциирован никакой асинхронный результат. Функция this->valid() возвращает то же значение, которое возвращала функция other.valid() перед вызовом конструктора. Функция other.valid() возвращает false.
Исключения
Нет.
STD::FUTURE , ПЕРЕМЕЩАЮЩИЙ ОПЕРАТОР ПРИСВАИВАНИЯ
Передает владение асинхронным результатом, ассоциированным с объектом std::future, другому объекту.
Объявление
future(future&& other) noexcept;
Результат
Передает владение асинхронным состоянием между экземплярами std::future.
Постусловия
Асинхронный результат, ассоциированный с объектом other перед вызовом оператора, ассоциируется с *this. Объект *this перестаёт быть владельцем своего прежнего асинхронного состояния (если оно было с ним ассоциировано), и если эта ссылка на асинхронное состояние была последней, то оно уничтожается. Функция this->valid() возвращает то же значение, которое возвращала функция other, valid() перед вызовом оператора. Функция other.valid() возвращает false.
Исключения
Нет.
STD::FUTURE , ДЕСТРУКТОР
Уничтожает объект std::future.
Объявление
~future();
Результат
Уничтожает *this. Если с *this была ассоциирована последняя ссылка на асинхронный результат (при условии, что с *this вообще что-то ассоциировано), то этот асинхронный результат уничтожается.
Исключения
Нет.
STD::FUTURE::SHARE , ФУНКЦИЯ-ЧЛЕН
Конструирует новый экземпляр std::shared_future и передаёт ему владение асинхронным результатом, ассоциированным с *this.
Объявление
shared_future<ResultType> share();
Результат
Эквивалентно shared_future<ResultType>(std::move(*this)).
Постусловия
Асинхронный результат, ассоциированный с объектом *this перед вызовом share() (если с ним что-то было ассоциировано), ассоциируется с вновь сконструированным экземпляром std::shared_future. Функция this->valid() возвращает false.
Исключения
Нет.
STD::FUTURE::VALID , ФУНКЦИЯ-ЧЛЕН
Проверяет, ассоциирован ли с экземпляром std::future асинхронный результат. Объявление
bool valid() const noexcept;
Возвращаемое значение
true, если с *this ассоциирован асинхронный результат, иначе false.
Исключения
Нет.
STD::FUTURE::WAIT , ФУНКЦИЯ-ЧЛЕН
Если состояние, ассоциированное с *this, содержит отложенную функцию, то эта функция вызывается. В противном случае ждет, пока будет готов асинхронный результат, ассоциированный с данным экземпляром std::future.
Объявление
void wait();
Предусловия
this->valid() должно возвращать true.
Результат
Если ассоциированное состояние содержит отложенную функцию, то вызывает эту функцию и сохраняет возвращенное ей значение или объект-исключение в виде асинхронного результата. В противном случае блокирует поток до момента готовности асинхронного результата, ассоциированного с *this.
Исключения
Нет.
STD::FUTURE::WAIT_FOR , ФУНКЦИЯ-ЧЛЕН
Ждет, когда будет готов асинхронный результат, ассоциированный с данным экземпляром std::future, или истечет заданное время.
Объявление
template<typename Rep, typename Period>
future_status wait_for(
std::chrono::duration<Rep, Period> const& relative_time);
Предусловия
this->valid() должно возвращать true.
Результат
Если асинхронный результат, ассоциированный с *this, содержит отложенную функцию, полученную обращением к std::async, и эта функция, еще не начала исполняться, то возвращает управление немедленно без блокирования потока. В противном случае блокирует поток до момента готовности асинхронного результата, ассоциированного с *this, или до истечения времени, заданного в аргументе relative_time.
Возвращаемое значение
std::future_status::deferred, если асинхронный результат, ассоциированный с *this, содержит отложенную функцию, полученную обращением к std::async, и эта функция, еще не начала исполняться. std::future_status::ready, если асинхронный результат, ассоциированный с *this, готов, std::future_status::timeout, если истекло время, заданное в аргументе relative_time.
Примечание. Поток может быть заблокирован на время, превышающее указанное. Если возможно, время измеряется по стабильным часам.
Исключения
Нет.
STD::FUTURE::WAIT_UNTIL , ФУНКЦИЯ-ЧЛЕН
Ждет, когда будет готов асинхронный результат, ассоциированный с данным экземпляром std::future, или наступит заданный момент времени.
Объявление
template<typename Clock, typename Duration>
future_status wait_until(
std::chrono::time_point<Clock, Duration> const& absolute_time);
Предусловия
this->valid() должно возвращать true.
Результат
Если асинхронный результат, ассоциированный с *this, содержит отложенную функцию, полученную обращением к std::async, и эта функция, еще не начала исполняться, то возвращает управление немедленно без блокирования потока. В противном случае блокирует поток до момента готовности асинхронного результата, ассоциированного с *this, или до момента, когда функция Clock::now() вернет время, большее или равное absolute_time.
Возвращаемое значение
std::future_status::deferred, если асинхронный результат, ассоциированный с *this, содержит отложенную функцию, полученную обращением к std::async, и эта функция, еще не начала исполняться. std::future_status::ready, если асинхронный результат, ассоциированный с *this, готов, std::future_status::timeout, если Clock::now() вернула время, большее или равное absolute_time.
Примечание. Не дается никаких гарантий относительно того, сколько времени будет блокирован вызывающий поток. Гарантируется лишь, что если функция вернула std::future_status::timeout, то значение, возвращенное Clock::now(), больше или равно absolute_time в точке, где поток разблокировался.
Исключения
Нет.
STD::FUTURE::GET , ФУНКЦИЯ-ЧЛЕН
Если ассоциированное состояние содержит отложенную функцию, полученную в результате обращения к std::async, то вызывает эту функцию и возвращает результат. В противном случае ждет готовности асинхронного результата, ассоциированного с экземпляром std::future, а затем либо возвращает сохраненное в нем значение, либо возбуждает сохраненное в нем исключение.
Объявление
void future<void>::get();
R& future<R&>::get();
R future<R>::get();
Предусловия
this->valid() должно возвращать true.
Результат
Если состояние, ассоциированное с *this, содержит отложенную функцию, то вызывает эту функцию и возвращает результат или возбуждает хранящееся исключение. В противном случае блокирует поток до момента готовности асинхронного результата, ассоциированного с *this. Если в результате хранится исключение, возбуждает его, иначе возвращает хранящееся значение.
Возвращаемое значение
Если ассоциированное состояние содержит отложенную функцию, то возвращает результат вызова этой функции. Иначе, если ResultType — void, то функция просто возвращает управление. Если ResultType — R& для некоторого типа R, то возвращает хранящуюся ссылку. Иначе возвращает хранящееся значение.
Исключения
Исключение, возбужденное отложенной функцией или сохраненное в асинхронном результате (если таковое имеется).
Постусловие
this->valid() == false