libs/asio/doc/requirements/SocketAcceptorService.qbk

   1 [/
   2  / Copyright (c) 2003-2017 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section:SocketAcceptorService Socket acceptor service requirements]
   9
  10 A socket acceptor service must meet the requirements for an [link
  11 boost_asio.reference.IoObjectService I/O object service], as well as the
  12 additional requirements listed below.
  13
  14 In the table below, `X` denotes a socket acceptor service class for protocol
  15 [link boost_asio.reference.Protocol `Protocol`], `a` and `ao` denote values of type
  16 `X`, `b` and `c` denote values of type `X::implementation_type`, `p` denotes a
  17 value of type `Protocol`, `n` denotes a value of type `X::native_handle_type`,
  18 `e` denotes a value of type `Protocol::endpoint`, `ec` denotes a value of type
  19 `error_code`, `s` denotes a value meeting [link
  20 boost_asio.reference.SettableSocketOption `SettableSocketOption`] requirements, `g`
  21 denotes a value meeting [link boost_asio.reference.GettableSocketOption
  22 `GettableSocketOption`] requirements, `i` denotes a value meeting [link
  23 boost_asio.reference.IoControlCommand `IoControlCommand`] requirements, `k` denotes a
  24 value of type `basic_socket<Protocol, SocketService>` where `SocketService` is
  25 a type meeting [link boost_asio.reference.SocketService socket service] requirements,
  26 `ah` denotes a value meeting [link boost_asio.reference.AcceptHandler
  27 `AcceptHandler`] requirements, and `u` and `v` denote identifiers.
  28
  29 [table SocketAcceptorService requirements
  30   [[expression] [return type] [assertion/note\npre/post-condition]]
  31   [
  32     [`X::native_handle_type`]
  33     []
  34     [
  35       The implementation-defined native representation of a socket acceptor.
  36       Must satisfy the requirements of `CopyConstructible` types (C++ Std,
  37       20.1.3), and the requirements of `Assignable` types (C++ Std, 23.1).
  38     ]
  39   ]
  40   [
  41     [`a.construct(b);`]
  42     []
  43     [
  44       From [link boost_asio.reference.IoObjectService IoObjectService]
  45       requirements.\n
  46       post: `!a.is_open(b)`.
  47     ]
  48   ]
  49   [
  50     [`a.destroy(b);`]
  51     []
  52     [
  53       From [link boost_asio.reference.IoObjectService IoObjectService]
  54       requirements. Implicitly cancels asynchronous operations, as if by calling
  55       `a.close(b, ec)`.
  56     ]
  57   ]
  58   [
  59     [``
  60       a.move_construct(b, c);
  61     ``]
  62     []
  63     [
  64       From [link boost_asio.reference.IoObjectService IoObjectService] requirements.
  65       The underlying native representation is moved from `c` to `b`.
  66     ]
  67   ]
  68   [
  69     [``
  70       a.move_assign(b, ao, c);
  71     ``]
  72     []
  73     [
  74       From [link boost_asio.reference.IoObjectService IoObjectService] requirements.
  75       Implicitly cancels asynchronous operations associated with `b`, as if by
  76       calling `a.close(b, ec)`. Then the underlying native representation is
  77       moved from `c` to `b`.
  78     ]
  79   ]
  80   [
  81     [``
  82       a.open(b, p, ec);
  83     ``]
  84     [`error_code`]
  85     [
  86       pre: `!a.is_open(b)`.\n
  87       post: `!!ec || a.is_open(b)`.
  88     ]
  89   ]
  90   [
  91     [``
  92       a.assign(b, p, n, ec);
  93     ``]
  94     [`error_code`]
  95     [
  96       pre: `!a.is_open(b)`.\n
  97       post: `!!ec || a.is_open(b)`.
  98     ]
  99   ]
 100   [
 101     [``
 102       a.is_open(b);
 103     ``]
 104     [`bool`]
 105     [
 106     ]
 107   ]
 108   [
 109     [``
 110       const X& u = a;
 111       const X::implementation_type& v = b;
 112       u.is_open(v);
 113     ``]
 114     [`bool`]
 115     [
 116     ]
 117   ]
 118   [
 119     [``
 120       a.close(b, ec);
 121     ``]
 122     [`error_code`]
 123     [
 124       If `a.is_open()` is true, causes any outstanding asynchronous operations
 125       to complete as soon as possible. Handlers for cancelled operations shall
 126       be passed the error code `error::operation_aborted`.\n
 127       post: `!a.is_open(b)`.
 128     ]
 129   ]
 130   [
 131     [``
 132       a.native_handle(b);
 133     ``]
 134     [`X::native_handle_type`]
 135     [
 136     ]
 137   ]
 138   [
 139     [``
 140       a.cancel(b, ec);
 141     ``]
 142     [`error_code`]
 143     [
 144       pre: `a.is_open(b)`.\n
 145       Causes any outstanding asynchronous operations to complete as soon as
 146       possible. Handlers for cancelled operations shall be passed the error
 147       code `error::operation_aborted`.
 148     ]
 149   ]
 150   [
 151     [``
 152       a.set_option(b, s, ec);
 153     ``]
 154     [`error_code`]
 155     [
 156       pre: `a.is_open(b)`.
 157     ]
 158   ]
 159   [
 160     [``
 161       a.get_option(b, g, ec);
 162     ``]
 163     [`error_code`]
 164     [
 165       pre: `a.is_open(b)`.
 166     ]
 167   ]
 168   [
 169     [``
 170       const X& u = a;
 171       const X::implementation_type& v = b;
 172       u.get_option(v, g, ec);
 173     ``]
 174     [`error_code`]
 175     [
 176       pre: `a.is_open(b)`.
 177     ]
 178   ]
 179   [
 180     [``
 181       a.io_control(b, i, ec);
 182     ``]
 183     [`error_code`]
 184     [
 185       pre: `a.is_open(b)`.
 186     ]
 187   ]
 188   [
 189     [``
 190       const typename Protocol::endpoint& u = e;
 191       a.bind(b, u, ec);
 192     ``]
 193     [`error_code`]
 194     [
 195       pre: `a.is_open(b)`.
 196     ]
 197   ]
 198   [
 199     [``
 200       a.local_endpoint(b, ec);
 201     ``]
 202     [`Protocol::endpoint`]
 203     [
 204       pre: `a.is_open(b)`.
 205     ]
 206   ]
 207   [
 208     [``
 209       const X& u = a;
 210       const X::implementation_type& v = b;
 211       u.local_endpoint(v, ec);
 212     ``]
 213     [`Protocol::endpoint`]
 214     [
 215       pre: `a.is_open(b)`.
 216     ]
 217   ]
 218   [
 219     [``
 220       a.accept(b, k, &e, ec);
 221     ``]
 222     [`error_code`]
 223     [
 224       pre: `a.is_open(b) && !k.is_open()`.\n
 225       post: `k.is_open()`
 226     ]
 227   ]
 228   [
 229     [``
 230       a.accept(b, k, 0, ec);
 231     ``]
 232     [`error_code`]
 233     [
 234       pre: `a.is_open(b) && !k.is_open()`.\n
 235       post: `k.is_open()`
 236     ]
 237   ]
 238   [
 239     [``
 240       a.async_accept(b, k, &e, ah);
 241     ``]
 242     []
 243     [
 244       pre: `a.is_open(b) && !k.is_open()`.\n
 245       Initiates an asynchronous accept operation that is performed via the
 246       `io_service` object `a.get_io_service()` and behaves according to [link
 247       boost_asio.reference.asynchronous_operations asynchronous operation]
 248       requirements.\n\n
 249       The program must ensure the objects `k` and `e` are valid until the
 250       handler for the asynchronous operation is invoked.
 251     ]
 252   ]
 253   [
 254     [``
 255       a.async_accept(b, k, 0, ah);
 256     ``]
 257     []
 258     [
 259       pre: `a.is_open(b) && !k.is_open()`.\n
 260       Initiates an asynchronous accept operation that is performed via the
 261       `io_service` object `a.get_io_service()` and behaves according to [link
 262       boost_asio.reference.asynchronous_operations asynchronous operation]
 263       requirements.\n\n
 264       The program must ensure the object `k` is valid until the handler for the
 265       asynchronous operation is invoked.
 266     ]
 267   ]
 268 ]
 269
 270 [endsect]