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