1 //
2 // use_future.hpp
3 // ~~~~~~~~~~~~~~
4 //
5 // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6 //
7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9 //
10 
11 #ifndef ASIO_USE_FUTURE_HPP
12 #define ASIO_USE_FUTURE_HPP
13 
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
15 # pragma once
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17 
18 #include "asio/detail/config.hpp"
19 #include <memory>
20 
21 #include "asio/detail/push_options.hpp"
22 
23 namespace asio {
24 
25 /// Class used to specify that an asynchronous operation should return a future.
26 /**
27  * The use_future_t class is used to indicate that an asynchronous operation
28  * should return a std::future object. A use_future_t object may be passed as a
29  * handler to an asynchronous operation, typically using the special value @c
30  * asio::use_future. For example:
31  *
32  * @code std::future<std::size_t> my_future
33  *   = my_socket.async_read_some(my_buffer, asio::use_future); @endcode
34  *
35  * The initiating function (async_read_some in the above example) returns a
36  * future that will receive the result of the operation. If the operation
37  * completes with an error_code indicating failure, it is converted into a
38  * system_error and passed back to the caller via the future.
39  */
40 template <typename Allocator = std::allocator<void> >
41 class use_future_t
42 {
43 public:
44   /// The allocator type. The allocator is used when constructing the
45   /// @c std::promise object for a given asynchronous operation.
46   typedef Allocator allocator_type;
47 
48   /// Construct using default-constructed allocator.
use_future_t()49   ASIO_CONSTEXPR use_future_t()
50   {
51   }
52 
53   /// Construct using specified allocator.
use_future_t(const Allocator & allocator)54   explicit use_future_t(const Allocator& allocator)
55     : allocator_(allocator)
56   {
57   }
58 
59 #if !defined(ASIO_NO_DEPRECATED)
60   /// (Deprecated: Use rebind().) Specify an alternate allocator.
61   template <typename OtherAllocator>
operator [](const OtherAllocator & allocator) const62   use_future_t<OtherAllocator> operator[](const OtherAllocator& allocator) const
63   {
64     return use_future_t<OtherAllocator>(allocator);
65   }
66 #endif // !defined(ASIO_NO_DEPRECATED)
67 
68   /// Specify an alternate allocator.
69   template <typename OtherAllocator>
rebind(const OtherAllocator & allocator) const70   use_future_t<OtherAllocator> rebind(const OtherAllocator& allocator) const
71   {
72     return use_future_t<OtherAllocator>(allocator);
73   }
74 
75   /// Obtain allocator.
get_allocator() const76   allocator_type get_allocator() const
77   {
78     return allocator_;
79   }
80 
81 private:
82   Allocator allocator_;
83 };
84 
85 /// A special value, similar to std::nothrow.
86 /**
87  * See the documentation for asio::use_future_t for a usage example.
88  */
89 #if defined(ASIO_HAS_CONSTEXPR) || defined(GENERATING_DOCUMENTATION)
90 constexpr use_future_t<> use_future;
91 #elif defined(ASIO_MSVC)
92 __declspec(selectany) use_future_t<> use_future;
93 #endif
94 
95 } // namespace asio
96 
97 #include "asio/detail/pop_options.hpp"
98 
99 #include "asio/impl/use_future.hpp"
100 
101 #endif // ASIO_USE_FUTURE_HPP
102