Statistics
| Revision:

root / tmp / org.txm.statsengine.r.core.win32 / res / win32 / library / BH / include / boost / asio / posix / basic_descriptor.hpp @ 2486

History | View | Annotate | Download (16.9 kB)

1
//
2
// posix/basic_descriptor.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 BOOST_ASIO_POSIX_BASIC_DESCRIPTOR_HPP
12
#define BOOST_ASIO_POSIX_BASIC_DESCRIPTOR_HPP
13

    
14
#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15
# pragma once
16
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17

    
18
#include <boost/asio/detail/config.hpp>
19

    
20
#if defined(BOOST_ASIO_HAS_POSIX_STREAM_DESCRIPTOR) \
21
  || defined(GENERATING_DOCUMENTATION)
22

    
23
#include <boost/asio/basic_io_object.hpp>
24
#include <boost/asio/detail/throw_error.hpp>
25
#include <boost/asio/error.hpp>
26
#include <boost/asio/posix/descriptor_base.hpp>
27

    
28
#include <boost/asio/detail/push_options.hpp>
29

    
30
namespace boost {
31
namespace asio {
32
namespace posix {
33

    
34
/// Provides POSIX descriptor functionality.
35
/**
36
 * The posix::basic_descriptor class template provides the ability to wrap a
37
 * POSIX descriptor.
38
 *
39
 * @par Thread Safety
40
 * @e Distinct @e objects: Safe.@n
41
 * @e Shared @e objects: Unsafe.
42
 */
43
template <typename DescriptorService>
44
class basic_descriptor
45
  : public basic_io_object<DescriptorService>,
46
    public descriptor_base
47
{
48
public:
49
  /// (Deprecated: Use native_handle_type.) The native representation of a
50
  /// descriptor.
51
  typedef typename DescriptorService::native_handle_type native_type;
52

    
53
  /// The native representation of a descriptor.
54
  typedef typename DescriptorService::native_handle_type native_handle_type;
55

    
56
  /// A basic_descriptor is always the lowest layer.
57
  typedef basic_descriptor<DescriptorService> lowest_layer_type;
58

    
59
  /// Construct a basic_descriptor without opening it.
60
  /**
61
   * This constructor creates a descriptor without opening it.
62
   *
63
   * @param io_service The io_service object that the descriptor will use to
64
   * dispatch handlers for any asynchronous operations performed on the
65
   * descriptor.
66
   */
67
  explicit basic_descriptor(boost::asio::io_service& io_service)
68
    : basic_io_object<DescriptorService>(io_service)
69
  {
70
  }
71

    
72
  /// Construct a basic_descriptor on an existing native descriptor.
73
  /**
74
   * This constructor creates a descriptor object to hold an existing native
75
   * descriptor.
76
   *
77
   * @param io_service The io_service object that the descriptor will use to
78
   * dispatch handlers for any asynchronous operations performed on the
79
   * descriptor.
80
   *
81
   * @param native_descriptor A native descriptor.
82
   *
83
   * @throws boost::system::system_error Thrown on failure.
84
   */
85
  basic_descriptor(boost::asio::io_service& io_service,
86
      const native_handle_type& native_descriptor)
87
    : basic_io_object<DescriptorService>(io_service)
88
  {
89
    boost::system::error_code ec;
90
    this->get_service().assign(this->get_implementation(),
91
        native_descriptor, ec);
92
    boost::asio::detail::throw_error(ec, "assign");
93
  }
94

    
95
#if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
96
  /// Move-construct a basic_descriptor from another.
97
  /**
98
   * This constructor moves a descriptor from one object to another.
99
   *
100
   * @param other The other basic_descriptor object from which the move will
101
   * occur.
102
   *
103
   * @note Following the move, the moved-from object is in the same state as if
104
   * constructed using the @c basic_descriptor(io_service&) constructor.
105
   */
106
  basic_descriptor(basic_descriptor&& other)
107
    : basic_io_object<DescriptorService>(
108
        BOOST_ASIO_MOVE_CAST(basic_descriptor)(other))
109
  {
110
  }
111

    
112
  /// Move-assign a basic_descriptor from another.
113
  /**
114
   * This assignment operator moves a descriptor from one object to another.
115
   *
116
   * @param other The other basic_descriptor object from which the move will
117
   * occur.
118
   *
119
   * @note Following the move, the moved-from object is in the same state as if
120
   * constructed using the @c basic_descriptor(io_service&) constructor.
121
   */
122
  basic_descriptor& operator=(basic_descriptor&& other)
123
  {
124
    basic_io_object<DescriptorService>::operator=(
125
        BOOST_ASIO_MOVE_CAST(basic_descriptor)(other));
126
    return *this;
127
  }
128
#endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
129

    
130
  /// Get a reference to the lowest layer.
131
  /**
132
   * This function returns a reference to the lowest layer in a stack of
133
   * layers. Since a basic_descriptor cannot contain any further layers, it
134
   * simply returns a reference to itself.
135
   *
136
   * @return A reference to the lowest layer in the stack of layers. Ownership
137
   * is not transferred to the caller.
138
   */
139
  lowest_layer_type& lowest_layer()
140
  {
141
    return *this;
142
  }
143

    
144
  /// Get a const reference to the lowest layer.
145
  /**
146
   * This function returns a const reference to the lowest layer in a stack of
147
   * layers. Since a basic_descriptor cannot contain any further layers, it
148
   * simply returns a reference to itself.
149
   *
150
   * @return A const reference to the lowest layer in the stack of layers.
151
   * Ownership is not transferred to the caller.
152
   */
153
  const lowest_layer_type& lowest_layer() const
154
  {
155
    return *this;
156
  }
157

    
158
  /// Assign an existing native descriptor to the descriptor.
159
  /*
160
   * This function opens the descriptor to hold an existing native descriptor.
161
   *
162
   * @param native_descriptor A native descriptor.
163
   *
164
   * @throws boost::system::system_error Thrown on failure.
165
   */
166
  void assign(const native_handle_type& native_descriptor)
167
  {
168
    boost::system::error_code ec;
169
    this->get_service().assign(this->get_implementation(),
170
        native_descriptor, ec);
171
    boost::asio::detail::throw_error(ec, "assign");
172
  }
173

    
174
  /// Assign an existing native descriptor to the descriptor.
175
  /*
176
   * This function opens the descriptor to hold an existing native descriptor.
177
   *
178
   * @param native_descriptor A native descriptor.
179
   *
180
   * @param ec Set to indicate what error occurred, if any.
181
   */
182
  boost::system::error_code assign(const native_handle_type& native_descriptor,
183
      boost::system::error_code& ec)
184
  {
185
    return this->get_service().assign(
186
        this->get_implementation(), native_descriptor, ec);
187
  }
188

    
189
  /// Determine whether the descriptor is open.
190
  bool is_open() const
191
  {
192
    return this->get_service().is_open(this->implementation);
193
  }
194

    
195
  /// Close the descriptor.
196
  /**
197
   * This function is used to close the descriptor. Any asynchronous read or
198
   * write operations will be cancelled immediately, and will complete with the
199
   * boost::asio::error::operation_aborted error.
200
   *
201
   * @throws boost::system::system_error Thrown on failure. Note that, even if
202
   * the function indicates an error, the underlying descriptor is closed.
203
   */
204
  void close()
205
  {
206
    boost::system::error_code ec;
207
    this->get_service().close(this->get_implementation(), ec);
208
    boost::asio::detail::throw_error(ec, "close");
209
  }
210

    
211
  /// Close the descriptor.
212
  /**
213
   * This function is used to close the descriptor. Any asynchronous read or
214
   * write operations will be cancelled immediately, and will complete with the
215
   * boost::asio::error::operation_aborted error.
216
   *
217
   * @param ec Set to indicate what error occurred, if any. Note that, even if
218
   * the function indicates an error, the underlying descriptor is closed.
219
   */
220
  boost::system::error_code close(boost::system::error_code& ec)
221
  {
222
    return this->get_service().close(this->get_implementation(), ec);
223
  }
224

    
225
  /// (Deprecated: Use native_handle().) Get the native descriptor
226
  /// representation.
227
  /**
228
   * This function may be used to obtain the underlying representation of the
229
   * descriptor. This is intended to allow access to native descriptor
230
   * functionality that is not otherwise provided.
231
   */
232
  native_type native()
233
  {
234
    return this->get_service().native_handle(this->implementation);
235
  }
236

    
237
  /// Get the native descriptor representation.
238
  /**
239
   * This function may be used to obtain the underlying representation of the
240
   * descriptor. This is intended to allow access to native descriptor
241
   * functionality that is not otherwise provided.
242
   */
243
  native_handle_type native_handle()
244
  {
245
    return this->get_service().native_handle(this->implementation);
246
  }
247

    
248
  /// Release ownership of the native descriptor implementation.
249
  /**
250
   * This function may be used to obtain the underlying representation of the
251
   * descriptor. After calling this function, @c is_open() returns false. The
252
   * caller is responsible for closing the descriptor.
253
   *
254
   * All outstanding asynchronous read or write operations will finish
255
   * immediately, and the handlers for cancelled operations will be passed the
256
   * boost::asio::error::operation_aborted error.
257
   */
258
  native_handle_type release()
259
  {
260
    return this->get_service().release(this->implementation);
261
  }
262

    
263
  /// Cancel all asynchronous operations associated with the descriptor.
264
  /**
265
   * This function causes all outstanding asynchronous read or write operations
266
   * to finish immediately, and the handlers for cancelled operations will be
267
   * passed the boost::asio::error::operation_aborted error.
268
   *
269
   * @throws boost::system::system_error Thrown on failure.
270
   */
271
  void cancel()
272
  {
273
    boost::system::error_code ec;
274
    this->get_service().cancel(this->get_implementation(), ec);
275
    boost::asio::detail::throw_error(ec, "cancel");
276
  }
277

    
278
  /// Cancel all asynchronous operations associated with the descriptor.
279
  /**
280
   * This function causes all outstanding asynchronous read or write operations
281
   * to finish immediately, and the handlers for cancelled operations will be
282
   * passed the boost::asio::error::operation_aborted error.
283
   *
284
   * @param ec Set to indicate what error occurred, if any.
285
   */
286
  boost::system::error_code cancel(boost::system::error_code& ec)
287
  {
288
    return this->get_service().cancel(this->get_implementation(), ec);
289
  }
290

    
291
  /// Perform an IO control command on the descriptor.
292
  /**
293
   * This function is used to execute an IO control command on the descriptor.
294
   *
295
   * @param command The IO control command to be performed on the descriptor.
296
   *
297
   * @throws boost::system::system_error Thrown on failure.
298
   *
299
   * @sa IoControlCommand @n
300
   * boost::asio::posix::descriptor_base::bytes_readable @n
301
   * boost::asio::posix::descriptor_base::non_blocking_io
302
   *
303
   * @par Example
304
   * Getting the number of bytes ready to read:
305
   * @code
306
   * boost::asio::posix::stream_descriptor descriptor(io_service);
307
   * ...
308
   * boost::asio::posix::stream_descriptor::bytes_readable command;
309
   * descriptor.io_control(command);
310
   * std::size_t bytes_readable = command.get();
311
   * @endcode
312
   */
313
  template <typename IoControlCommand>
314
  void io_control(IoControlCommand& command)
315
  {
316
    boost::system::error_code ec;
317
    this->get_service().io_control(this->get_implementation(), command, ec);
318
    boost::asio::detail::throw_error(ec, "io_control");
319
  }
320

    
321
  /// Perform an IO control command on the descriptor.
322
  /**
323
   * This function is used to execute an IO control command on the descriptor.
324
   *
325
   * @param command The IO control command to be performed on the descriptor.
326
   *
327
   * @param ec Set to indicate what error occurred, if any.
328
   *
329
   * @sa IoControlCommand @n
330
   * boost::asio::posix::descriptor_base::bytes_readable @n
331
   * boost::asio::posix::descriptor_base::non_blocking_io
332
   *
333
   * @par Example
334
   * Getting the number of bytes ready to read:
335
   * @code
336
   * boost::asio::posix::stream_descriptor descriptor(io_service);
337
   * ...
338
   * boost::asio::posix::stream_descriptor::bytes_readable command;
339
   * boost::system::error_code ec;
340
   * descriptor.io_control(command, ec);
341
   * if (ec)
342
   * {
343
   *   // An error occurred.
344
   * }
345
   * std::size_t bytes_readable = command.get();
346
   * @endcode
347
   */
348
  template <typename IoControlCommand>
349
  boost::system::error_code io_control(IoControlCommand& command,
350
      boost::system::error_code& ec)
351
  {
352
    return this->get_service().io_control(
353
        this->get_implementation(), command, ec);
354
  }
355

    
356
  /// Gets the non-blocking mode of the descriptor.
357
  /**
358
   * @returns @c true if the descriptor's synchronous operations will fail with
359
   * boost::asio::error::would_block if they are unable to perform the requested
360
   * operation immediately. If @c false, synchronous operations will block
361
   * until complete.
362
   *
363
   * @note The non-blocking mode has no effect on the behaviour of asynchronous
364
   * operations. Asynchronous operations will never fail with the error
365
   * boost::asio::error::would_block.
366
   */
367
  bool non_blocking() const
368
  {
369
    return this->get_service().non_blocking(this->implementation);
370
  }
371

    
372
  /// Sets the non-blocking mode of the descriptor.
373
  /**
374
   * @param mode If @c true, the descriptor's synchronous operations will fail
375
   * with boost::asio::error::would_block if they are unable to perform the
376
   * requested operation immediately. If @c false, synchronous operations will
377
   * block until complete.
378
   *
379
   * @throws boost::system::system_error Thrown on failure.
380
   *
381
   * @note The non-blocking mode has no effect on the behaviour of asynchronous
382
   * operations. Asynchronous operations will never fail with the error
383
   * boost::asio::error::would_block.
384
   */
385
  void non_blocking(bool mode)
386
  {
387
    boost::system::error_code ec;
388
    this->get_service().non_blocking(this->get_implementation(), mode, ec);
389
    boost::asio::detail::throw_error(ec, "non_blocking");
390
  }
391

    
392
  /// Sets the non-blocking mode of the descriptor.
393
  /**
394
   * @param mode If @c true, the descriptor's synchronous operations will fail
395
   * with boost::asio::error::would_block if they are unable to perform the
396
   * requested operation immediately. If @c false, synchronous operations will
397
   * block until complete.
398
   *
399
   * @param ec Set to indicate what error occurred, if any.
400
   *
401
   * @note The non-blocking mode has no effect on the behaviour of asynchronous
402
   * operations. Asynchronous operations will never fail with the error
403
   * boost::asio::error::would_block.
404
   */
405
  boost::system::error_code non_blocking(
406
      bool mode, boost::system::error_code& ec)
407
  {
408
    return this->get_service().non_blocking(
409
        this->get_implementation(), mode, ec);
410
  }
411

    
412
  /// Gets the non-blocking mode of the native descriptor implementation.
413
  /**
414
   * This function is used to retrieve the non-blocking mode of the underlying
415
   * native descriptor. This mode has no effect on the behaviour of the
416
   * descriptor object's synchronous operations.
417
   *
418
   * @returns @c true if the underlying descriptor is in non-blocking mode and
419
   * direct system calls may fail with boost::asio::error::would_block (or the
420
   * equivalent system error).
421
   *
422
   * @note The current non-blocking mode is cached by the descriptor object.
423
   * Consequently, the return value may be incorrect if the non-blocking mode
424
   * was set directly on the native descriptor.
425
   */
426
  bool native_non_blocking() const
427
  {
428
    return this->get_service().native_non_blocking(this->implementation);
429
  }
430

    
431
  /// Sets the non-blocking mode of the native descriptor implementation.
432
  /**
433
   * This function is used to modify the non-blocking mode of the underlying
434
   * native descriptor. It has no effect on the behaviour of the descriptor
435
   * object's synchronous operations.
436
   *
437
   * @param mode If @c true, the underlying descriptor is put into non-blocking
438
   * mode and direct system calls may fail with boost::asio::error::would_block
439
   * (or the equivalent system error).
440
   *
441
   * @throws boost::system::system_error Thrown on failure. If the @c mode is
442
   * @c false, but the current value of @c non_blocking() is @c true, this
443
   * function fails with boost::asio::error::invalid_argument, as the
444
   * combination does not make sense.
445
   */
446
  void native_non_blocking(bool mode)
447
  {
448
    boost::system::error_code ec;
449
    this->get_service().native_non_blocking(
450
        this->get_implementation(), mode, ec);
451
    boost::asio::detail::throw_error(ec, "native_non_blocking");
452
  }
453

    
454
  /// Sets the non-blocking mode of the native descriptor implementation.
455
  /**
456
   * This function is used to modify the non-blocking mode of the underlying
457
   * native descriptor. It has no effect on the behaviour of the descriptor
458
   * object's synchronous operations.
459
   *
460
   * @param mode If @c true, the underlying descriptor is put into non-blocking
461
   * mode and direct system calls may fail with boost::asio::error::would_block
462
   * (or the equivalent system error).
463
   *
464
   * @param ec Set to indicate what error occurred, if any. If the @c mode is
465
   * @c false, but the current value of @c non_blocking() is @c true, this
466
   * function fails with boost::asio::error::invalid_argument, as the
467
   * combination does not make sense.
468
   */
469
  boost::system::error_code native_non_blocking(
470
      bool mode, boost::system::error_code& ec)
471
  {
472
    return this->get_service().native_non_blocking(
473
        this->get_implementation(), mode, ec);
474
  }
475

    
476
protected:
477
  /// Protected destructor to prevent deletion through this type.
478
  ~basic_descriptor()
479
  {
480
  }
481
};
482

    
483
} // namespace posix
484
} // namespace asio
485
} // namespace boost
486

    
487
#include <boost/asio/detail/pop_options.hpp>
488

    
489
#endif // defined(BOOST_ASIO_HAS_POSIX_STREAM_DESCRIPTOR)
490
       //   || defined(GENERATING_DOCUMENTATION)
491

    
492
#endif // BOOST_ASIO_POSIX_BASIC_DESCRIPTOR_HPP