1 | // |
2 | // windows/basic_object_handle.hpp |
3 | // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
4 | // |
5 | // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com) |
6 | // Copyright (c) 2011 Boris Schaeling (boris@highscore.de) |
7 | // |
8 | // Distributed under the Boost Software License, Version 1.0. (See accompanying |
9 | // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
10 | // |
11 | |
12 | #ifndef BOOST_ASIO_WINDOWS_BASIC_OBJECT_HANDLE_HPP |
13 | #define BOOST_ASIO_WINDOWS_BASIC_OBJECT_HANDLE_HPP |
14 | |
15 | #if defined(_MSC_VER) && (_MSC_VER >= 1200) |
16 | # pragma once |
17 | #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) |
18 | |
19 | #include <boost/asio/detail/config.hpp> |
20 | |
21 | #if defined(BOOST_ASIO_HAS_WINDOWS_OBJECT_HANDLE) \ |
22 | || defined(GENERATING_DOCUMENTATION) |
23 | |
24 | #include <boost/asio/detail/throw_error.hpp> |
25 | #include <boost/asio/error.hpp> |
26 | #include <boost/asio/windows/basic_handle.hpp> |
27 | #include <boost/asio/windows/object_handle_service.hpp> |
28 | |
29 | #include <boost/asio/detail/push_options.hpp> |
30 | |
31 | namespace boost { |
32 | namespace asio { |
33 | namespace windows { |
34 | |
35 | /// Provides object-oriented handle functionality. |
36 | /** |
37 | * The windows::basic_object_handle class template provides asynchronous and |
38 | * blocking object-oriented handle functionality. |
39 | * |
40 | * @par Thread Safety |
41 | * @e Distinct @e objects: Safe.@n |
42 | * @e Shared @e objects: Unsafe. |
43 | */ |
44 | template <typename ObjectHandleService = object_handle_service> |
45 | class basic_object_handle |
46 | : public basic_handle<ObjectHandleService> |
47 | { |
48 | public: |
49 | /// The native representation of a handle. |
50 | typedef typename ObjectHandleService::native_handle_type native_handle_type; |
51 | |
52 | /// Construct a basic_object_handle without opening it. |
53 | /** |
54 | * This constructor creates an object handle without opening it. |
55 | * |
56 | * @param io_service The io_service object that the object handle will use to |
57 | * dispatch handlers for any asynchronous operations performed on the handle. |
58 | */ |
59 | explicit basic_object_handle(boost::asio::io_service& io_service) |
60 | : basic_handle<ObjectHandleService>(io_service) |
61 | { |
62 | } |
63 | |
64 | /// Construct a basic_object_handle on an existing native handle. |
65 | /** |
66 | * This constructor creates an object handle object to hold an existing native |
67 | * handle. |
68 | * |
69 | * @param io_service The io_service object that the object handle will use to |
70 | * dispatch handlers for any asynchronous operations performed on the handle. |
71 | * |
72 | * @param native_handle The new underlying handle implementation. |
73 | * |
74 | * @throws boost::system::system_error Thrown on failure. |
75 | */ |
76 | basic_object_handle(boost::asio::io_service& io_service, |
77 | const native_handle_type& native_handle) |
78 | : basic_handle<ObjectHandleService>(io_service, native_handle) |
79 | { |
80 | } |
81 | |
82 | #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) |
83 | /// Move-construct a basic_object_handle from another. |
84 | /** |
85 | * This constructor moves an object handle from one object to another. |
86 | * |
87 | * @param other The other basic_object_handle object from which the move will |
88 | * occur. |
89 | * |
90 | * @note Following the move, the moved-from object is in the same state as if |
91 | * constructed using the @c basic_object_handle(io_service&) constructor. |
92 | */ |
93 | basic_object_handle(basic_object_handle&& other) |
94 | : basic_handle<ObjectHandleService>( |
95 | BOOST_ASIO_MOVE_CAST(basic_object_handle)(other)) |
96 | { |
97 | } |
98 | |
99 | /// Move-assign a basic_object_handle from another. |
100 | /** |
101 | * This assignment operator moves an object handle from one object to another. |
102 | * |
103 | * @param other The other basic_object_handle object from which the move will |
104 | * occur. |
105 | * |
106 | * @note Following the move, the moved-from object is in the same state as if |
107 | * constructed using the @c basic_object_handle(io_service&) constructor. |
108 | */ |
109 | basic_object_handle& operator=(basic_object_handle&& other) |
110 | { |
111 | basic_handle<ObjectHandleService>::operator=( |
112 | BOOST_ASIO_MOVE_CAST(basic_object_handle)(other)); |
113 | return *this; |
114 | } |
115 | #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) |
116 | |
117 | /// Perform a blocking wait on the object handle. |
118 | /** |
119 | * This function is used to wait for the object handle to be set to the |
120 | * signalled state. This function blocks and does not return until the object |
121 | * handle has been set to the signalled state. |
122 | * |
123 | * @throws boost::system::system_error Thrown on failure. |
124 | */ |
125 | void wait() |
126 | { |
127 | boost::system::error_code ec; |
128 | this->get_service().wait(this->get_implementation(), ec); |
129 | boost::asio::detail::throw_error(ec, "wait" ); |
130 | } |
131 | |
132 | /// Perform a blocking wait on the object handle. |
133 | /** |
134 | * This function is used to wait for the object handle to be set to the |
135 | * signalled state. This function blocks and does not return until the object |
136 | * handle has been set to the signalled state. |
137 | * |
138 | * @param ec Set to indicate what error occurred, if any. |
139 | */ |
140 | void wait(boost::system::error_code& ec) |
141 | { |
142 | this->get_service().wait(this->get_implementation(), ec); |
143 | } |
144 | |
145 | /// Start an asynchronous wait on the object handle. |
146 | /** |
147 | * This function is be used to initiate an asynchronous wait against the |
148 | * object handle. It always returns immediately. |
149 | * |
150 | * @param handler The handler to be called when the object handle is set to |
151 | * the signalled state. Copies will be made of the handler as required. The |
152 | * function signature of the handler must be: |
153 | * @code void handler( |
154 | * const boost::system::error_code& error // Result of operation. |
155 | * ); @endcode |
156 | * Regardless of whether the asynchronous operation completes immediately or |
157 | * not, the handler will not be invoked from within this function. Invocation |
158 | * of the handler will be performed in a manner equivalent to using |
159 | * boost::asio::io_service::post(). |
160 | */ |
161 | template <typename WaitHandler> |
162 | BOOST_ASIO_INITFN_RESULT_TYPE(WaitHandler, |
163 | void (boost::system::error_code)) |
164 | async_wait(BOOST_ASIO_MOVE_ARG(WaitHandler) handler) |
165 | { |
166 | return this->get_service().async_wait(this->get_implementation(), |
167 | BOOST_ASIO_MOVE_CAST(WaitHandler)(handler)); |
168 | } |
169 | }; |
170 | |
171 | } // namespace windows |
172 | } // namespace asio |
173 | } // namespace boost |
174 | |
175 | #include <boost/asio/detail/pop_options.hpp> |
176 | |
177 | #endif // defined(BOOST_ASIO_HAS_WINDOWS_OBJECT_HANDLE) |
178 | // || defined(GENERATING_DOCUMENTATION) |
179 | |
180 | #endif // BOOST_ASIO_WINDOWS_BASIC_OBJECT_HANDLE_HPP |
181 | |