Difference between revisions of "cpp/thread/future"
From cppreference.com
m (langlinks) |
Andreas Krug (Talk | contribs) m (fmt) |
||
| Line 2: | Line 2: | ||
{{cpp/thread/future/navbar}} | {{cpp/thread/future/navbar}} | ||
{{dcl begin}} | {{dcl begin}} | ||
| − | {{dcl header | future}} | + | {{dcl header|future}} |
| − | {{dcl | num=1 | since=c++11 | | + | {{dcl|num=1|since=c++11| |
template< class T > class future; | template< class T > class future; | ||
}} | }} | ||
| − | {{dcl | num=2 | since=c++11 | | + | {{dcl|num=2|since=c++11| |
template< class T > class future<T&>; | template< class T > class future<T&>; | ||
}} | }} | ||
| − | {{dcl | num=3 | since=c++11 | | + | {{dcl|num=3|since=c++11| |
| − | template<> | + | template<> class future<void>; |
}} | }} | ||
{{dcl end}} | {{dcl end}} | ||
| Line 18: | Line 18: | ||
* An asynchronous operation (created via {{lc|std::async}}, {{lc|std::packaged_task}}, or {{lc|std::promise}}) can provide a {{tt|std::future}} object to the creator of that asynchronous operation. | * An asynchronous operation (created via {{lc|std::async}}, {{lc|std::packaged_task}}, or {{lc|std::promise}}) can provide a {{tt|std::future}} object to the creator of that asynchronous operation. | ||
| − | * The creator of the asynchronous operation can then use a variety of methods to query, wait for, or extract a value from the {{tt|std::future}}. | + | * The creator of the asynchronous operation can then use a variety of methods to query, wait for, or extract a value from the {{tt|std::future}}. These methods may block if the asynchronous operation has not yet provided a value. |
| − | * When the asynchronous operation is ready to send a result to the creator, it can do so by modifying ''shared state'' (e.g. {{lc|std::promise::set_value}}) that is linked to the creator's | + | * When the asynchronous operation is ready to send a result to the creator, it can do so by modifying ''shared state'' (e.g. {{lc|std::promise::set_value}}) that is linked to the creator's {{tt|std::future}}. |
Note that {{tt|std::future}} references shared state that is not shared with any other asynchronous return objects (as opposed to {{lc|std::shared_future}}). | Note that {{tt|std::future}} references shared state that is not shared with any other asynchronous return objects (as opposed to {{lc|std::shared_future}}). | ||
| Line 26: | Line 26: | ||
===Member functions=== | ===Member functions=== | ||
{{dsc begin}} | {{dsc begin}} | ||
| − | {{dsc inc | cpp/thread/future/dsc constructor | future}} | + | {{dsc inc|cpp/thread/future/dsc constructor|future}} |
| − | {{dsc inc | cpp/thread/future/dsc destructor}} | + | {{dsc inc|cpp/thread/future/dsc destructor}} |
| − | {{dsc inc | cpp/thread/future/dsc operator{{=}}}} | + | {{dsc inc|cpp/thread/future/dsc operator{{=}}}} |
| − | {{dsc inc | cpp/thread/future/dsc share}} | + | {{dsc inc|cpp/thread/future/dsc share}} |
| − | {{dsc h2 | Getting the result}} | + | {{dsc h2|Getting the result}} |
| − | {{dsc inc | cpp/thread/future/dsc get | future}} | + | {{dsc inc|cpp/thread/future/dsc get|future}} |
| − | {{dsc h2 | State}} | + | {{dsc h2|State}} |
| − | {{dsc inc | cpp/thread/future/dsc valid | future}} | + | {{dsc inc|cpp/thread/future/dsc valid|future}} |
| − | {{dsc inc | cpp/thread/future/dsc wait | future}} | + | {{dsc inc|cpp/thread/future/dsc wait|future}} |
| − | {{dsc inc | cpp/thread/future/dsc wait_for | future}} | + | {{dsc inc|cpp/thread/future/dsc wait_for|future}} |
| − | {{dsc inc | cpp/thread/future/dsc wait_until | future}} | + | {{dsc inc|cpp/thread/future/dsc wait_until|future}} |
{{dsc end}} | {{dsc end}} | ||
===Examples=== | ===Examples=== | ||
{{example | {{example | ||
| − | | code= | + | |code= |
| − | + | ||
#include <future> | #include <future> | ||
| + | #include <iostream> | ||
#include <thread> | #include <thread> | ||
| Line 52: | Line 52: | ||
// future from a packaged_task | // future from a packaged_task | ||
std::packaged_task<int()> task([]{ return 7; }); // wrap the function | std::packaged_task<int()> task([]{ return 7; }); // wrap the function | ||
| − | std::future<int> f1 = task.get_future(); | + | std::future<int> f1 = task.get_future(); // get a future |
std::thread t(std::move(task)); // launch on a thread | std::thread t(std::move(task)); // launch on a thread | ||
| Line 61: | Line 61: | ||
std::promise<int> p; | std::promise<int> p; | ||
std::future<int> f3 = p.get_future(); | std::future<int> f3 = p.get_future(); | ||
| − | std::thread( [&p]{ p.set_value_at_thread_exit(9); }).detach(); | + | std::thread([&p]{ p.set_value_at_thread_exit(9); }).detach(); |
std::cout << "Waiting..." << std::flush; | std::cout << "Waiting..." << std::flush; | ||
| Line 71: | Line 71: | ||
t.join(); | t.join(); | ||
} | } | ||
| − | | output= | + | |output= |
Waiting...Done! | Waiting...Done! | ||
Results are: 7 8 9 | Results are: 7 8 9 | ||
| Line 78: | Line 78: | ||
====Example with exceptions==== | ====Example with exceptions==== | ||
{{example | {{example | ||
| − | + | |code= | |
| − | + | ||
| − | + | ||
#include <future> | #include <future> | ||
| + | #include <iostream> | ||
| + | #include <thread> | ||
int main() | int main() | ||
| Line 88: | Line 88: | ||
std::future<int> f = p.get_future(); | std::future<int> f = p.get_future(); | ||
| − | std::thread t([&p]{ | + | std::thread t([&p] |
| − | try { | + | { |
| + | try | ||
| + | { | ||
// code that may throw | // code that may throw | ||
throw std::runtime_error("Example"); | throw std::runtime_error("Example"); | ||
| − | } catch(...) { | + | } |
| − | try { | + | catch (...) |
| + | { | ||
| + | try | ||
| + | { | ||
// store anything thrown in the promise | // store anything thrown in the promise | ||
p.set_exception(std::current_exception()); | p.set_exception(std::current_exception()); | ||
| − | } catch(...) {} // set_exception() may throw too | + | } |
| + | catch (...) {} // set_exception() may throw too | ||
} | } | ||
}); | }); | ||
| − | try { | + | try |
| + | { | ||
std::cout << f.get(); | std::cout << f.get(); | ||
| − | } catch(const std::exception& e) { | + | } |
| + | catch (const std::exception& e) | ||
| + | { | ||
std::cout << "Exception from the thread: " << e.what() << '\n'; | std::cout << "Exception from the thread: " << e.what() << '\n'; | ||
} | } | ||
t.join(); | t.join(); | ||
} | } | ||
| − | + | |output= | |
Exception from the thread: Example | Exception from the thread: Example | ||
}} | }} | ||
| − | |||
===See also=== | ===See also=== | ||
{{dsc begin}} | {{dsc begin}} | ||
| − | {{dsc inc | cpp/thread/dsc async}} | + | {{dsc inc|cpp/thread/dsc async}} |
| − | {{dsc inc | cpp/thread/dsc shared_future}} | + | {{dsc inc|cpp/thread/dsc shared_future}} |
{{dsc end}} | {{dsc end}} | ||
{{langlinks|de|es|fr|it|ja|pt|ru|zh}} | {{langlinks|de|es|fr|it|ja|pt|ru|zh}} | ||
Revision as of 10:21, 11 October 2023
| Defined in header <future>
|
||
| template< class T > class future; |
(1) | (since C++11) |
| template< class T > class future<T&>; |
(2) | (since C++11) |
| template<> class future<void>; |
(3) | (since C++11) |
The class template std::future provides a mechanism to access the result of asynchronous operations:
- An asynchronous operation (created via std::async, std::packaged_task, or std::promise) can provide a
std::futureobject to the creator of that asynchronous operation.
- The creator of the asynchronous operation can then use a variety of methods to query, wait for, or extract a value from the
std::future. These methods may block if the asynchronous operation has not yet provided a value.
- When the asynchronous operation is ready to send a result to the creator, it can do so by modifying shared state (e.g. std::promise::set_value) that is linked to the creator's
std::future.
Note that std::future references shared state that is not shared with any other asynchronous return objects (as opposed to std::shared_future).
Contents |
Member functions
| constructs the future object (public member function) | |
| destructs the future object (public member function) | |
| moves the future object (public member function) | |
| transfers the shared state from *this to a shared_future and returns it (public member function) | |
Getting the result | |
| returns the result (public member function) | |
State | |
| checks if the future has a shared state (public member function) | |
| waits for the result to become available (public member function) | |
| waits for the result, returns if it is not available for the specified timeout duration (public member function) | |
| waits for the result, returns if it is not available until specified time point has been reached (public member function) | |
Examples
Run this code
#include <future> #include <iostream> #include <thread> int main() { // future from a packaged_task std::packaged_task<int()> task([]{ return 7; }); // wrap the function std::future<int> f1 = task.get_future(); // get a future std::thread t(std::move(task)); // launch on a thread // future from an async() std::future<int> f2 = std::async(std::launch::async, []{ return 8; }); // future from a promise std::promise<int> p; std::future<int> f3 = p.get_future(); std::thread([&p]{ p.set_value_at_thread_exit(9); }).detach(); std::cout << "Waiting..." << std::flush; f1.wait(); f2.wait(); f3.wait(); std::cout << "Done!\nResults are: " << f1.get() << ' ' << f2.get() << ' ' << f3.get() << '\n'; t.join(); }
Output:
Waiting...Done! Results are: 7 8 9
Example with exceptions
Run this code
#include <future> #include <iostream> #include <thread> int main() { std::promise<int> p; std::future<int> f = p.get_future(); std::thread t([&p] { try { // code that may throw throw std::runtime_error("Example"); } catch (...) { try { // store anything thrown in the promise p.set_exception(std::current_exception()); } catch (...) {} // set_exception() may throw too } }); try { std::cout << f.get(); } catch (const std::exception& e) { std::cout << "Exception from the thread: " << e.what() << '\n'; } t.join(); }
Output:
Exception from the thread: Example
See also
| (C++11) |
runs a function asynchronously (potentially in a new thread) and returns a std::future that will hold the result (function template) |
| (C++11) |
waits for a value (possibly referenced by other futures) that is set asynchronously (class template) |
