io_asio_socket.h 16.1 KB
 Stephen Morris committed Feb 18, 2011 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 ``````// Copyright (C) 2010 Internet Systems Consortium, Inc. ("ISC") // // Permission to use, copy, modify, and/or distribute this software for any // purpose with or without fee is hereby granted, provided that the above // copyright notice and this permission notice appear in all copies. // // THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH // REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY // AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, // INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM // LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR // PERFORMANCE OF THIS SOFTWARE. #ifndef __IO_ASIO_SOCKET_H #define __IO_ASIO_SOCKET_H 1 // IMPORTANT NOTE: only very few ASIO headers files can be included in // this file. In particular, asio.hpp should never be included here. // See the description of the namespace below. #include // for some network system calls #include #include #include #include `````` chenzhengzhang committed Apr 14, 2011 29 ``````#include `````` Stephen Morris committed Feb 28, 2011 30 `````` `````` Stephen Morris committed Feb 18, 2011 31 32 33 ``````#include #include `````` Ocean Wang committed Apr 08, 2011 34 ``````namespace isc { `````` Stephen Morris committed Feb 18, 2011 35 36 37 38 39 40 41 42 43 44 45 ``````namespace asiolink { /// \brief Socket not open /// /// Thrown on an attempt to do read/write to a socket that is not open. class SocketNotOpen : public IOError { public: SocketNotOpen(const char* file, size_t line, const char* what) : IOError(file, line, what) {} }; `````` Stephen Morris committed Feb 28, 2011 46 ``````/// \brief Error setting socket options `````` Stephen Morris committed Feb 24, 2011 47 48 49 50 51 52 53 ``````/// /// Thrown if attempt to change socket options fails. class SocketSetError : public IOError { public: SocketSetError(const char* file, size_t line, const char* what) : IOError(file, line, what) {} }; `````` Stephen Morris committed Feb 18, 2011 54 `````` `````` Stephen Morris committed Feb 28, 2011 55 ``````/// \brief Buffer overflow `````` Stephen Morris committed Feb 25, 2011 56 57 58 59 60 61 62 63 64 ``````/// /// Thrown if an attempt is made to receive into an area beyond the end of /// the receive data buffer. class BufferOverflow : public IOError { public: BufferOverflow(const char* file, size_t line, const char* what) : IOError(file, line, what) {} }; `````` Stephen Morris committed Feb 18, 2011 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 ``````/// Forward declaration of an IOEndpoint class IOEndpoint; /// \brief I/O Socket with asynchronous operations /// /// This class is a wrapper for the ASIO socket classes such as /// \c ip::tcp::socket and \c ip::udp::socket. /// /// This is the basic IOSocket with additional operations - open, send, receive /// and close. Depending on how the asiolink code develops, it may be a /// temporary class: its main use is to add the template parameter needed for /// the derived classes UDPSocket and TCPSocket but without changing the /// signature of the more basic IOSocket class. /// /// We may revisit this decision when we generalize the wrapper and more /// modules use it. Also, at that point we may define a separate (visible) /// derived class for testing purposes rather than providing factory methods /// (i.e., getDummy variants below). /// /// TODO: Check if IOAsioSocket class is still needed /// /// \param C Template parameter identifying type of the callback object. template class IOAsioSocket : public IOSocket { /// /// \name Constructors and Destructor /// /// Note: The copy constructor and the assignment operator are /// intentionally defined as private, making this class non-copyable. //@{ private: IOAsioSocket(const IOAsioSocket& source); IOAsioSocket& operator=(const IOAsioSocket& source); protected: /// \brief The default constructor. /// /// This is intentionally defined as \c protected as this base class /// should never be instantiated (except as part of a derived class). IOAsioSocket() {} public: /// The destructor. virtual ~IOAsioSocket() {} //@} /// \brief Return the "native" representation of the socket. /// `````` Stephen Morris committed Feb 28, 2011 113 114 115 `````` /// In practice, this is the file descriptor of the socket for UNIX-like /// systems so the current implementation simply uses \c int as the type of /// the return value. We may have to need revisit this decision later. `````` Stephen Morris committed Feb 18, 2011 116 `````` /// `````` Stephen Morris committed Feb 28, 2011 117 118 119 120 121 122 123 `````` /// In general, the application should avoid using this method; it /// essentially discloses an implementation specific "handle" that can /// change the internal state of the socket (consider what would happen if /// the application closes it, for example). But we sometimes need to /// perform very low-level operations that requires the native /// representation. Passing the file descriptor to a different process is /// one example. This method is provided as a necessary evil for such `````` Jelte Jansen committed Mar 07, 2011 124 `````` /// limited purposes. `````` Stephen Morris committed Feb 18, 2011 125 126 127 128 `````` /// /// This method never throws an exception. /// /// \return The native representation of the socket. This is the socket `````` Stephen Morris committed Feb 28, 2011 129 `````` /// file descriptor for UNIX-like systems. `````` Stephen Morris committed Feb 18, 2011 130 131 132 133 134 135 136 137 138 `````` virtual int getNative() const = 0; /// \brief Return the transport protocol of the socket. /// /// Currently, it returns \c IPPROTO_UDP for UDP sockets, and /// \c IPPROTO_TCP for TCP sockets. /// /// This method never throws an exception. /// `````` Stephen Morris committed Feb 28, 2011 139 `````` /// \return \c IPPROTO_UDP for UDP sockets, \c IPPROTO_TCP for TCP sockets `````` Stephen Morris committed Feb 18, 2011 140 141 `````` virtual int getProtocol() const = 0; `````` Stephen Morris committed Feb 25, 2011 142 `````` /// \brief Is Open() synchronous? `````` Stephen Morris committed Feb 18, 2011 143 `````` /// `````` Stephen Morris committed Feb 28, 2011 144 145 146 147 `````` /// On a TCP socket, an "open" operation is a call to the socket's "open()" /// method followed by a connection to the remote system: it is an /// asynchronous operation. On a UDP socket, it is just a call to "open()" /// and completes synchronously. `````` Stephen Morris committed Feb 21, 2011 148 149 150 151 `````` /// /// For TCP, signalling of the completion of the operation is done by /// by calling the callback function in the normal way. This could be done /// for UDP (by posting en event on the event queue); however, that will `````` Stephen Morris committed Feb 25, 2011 152 153 154 155 156 `````` /// incur additional overhead in the most common case. So we give the /// caller the choice for calling this open() method synchronously or /// asynchronously. /// /// Owing to the way that the stackless coroutines are implemented, we need `````` Stephen Morris committed Feb 28, 2011 157 158 `````` /// to know _before_ executing the "open" function whether or not it is /// asynchronous. So this method is called to provide that information. `````` Stephen Morris committed Feb 25, 2011 159 160 161 162 `````` /// /// (The reason there is a need to know is because the call to open() passes /// in the state of the coroutine at the time the call is made. On an /// asynchronous I/O, we need to set the state to point to the statement `````` Stephen Morris committed Feb 28, 2011 163 164 165 166 167 `````` /// after the call to open() _before_ we pass the corouine to the open() /// call. Unfortunately, the macros that set the state of the coroutine /// also yield control - which we don't want to do if the open is /// synchronous. Hence we need to know before we make the call to open() /// whether that call will complete asynchronously.) `````` Stephen Morris committed Feb 25, 2011 168 169 170 171 172 173 `````` virtual bool isOpenSynchronous() const = 0; /// \brief Open AsioSocket /// /// Opens the socket for asynchronous I/O. The open will complete /// synchronously on UCP or asynchronously on TCP (in which case a callback `````` Stephen Morris committed Feb 28, 2011 174 `````` /// will be queued). `````` Stephen Morris committed Feb 18, 2011 175 176 `````` /// /// \param endpoint Pointer to the endpoint object. This is ignored for `````` Stephen Morris committed Feb 28, 2011 177 178 `````` /// a UDP socket (the target is specified in the send call), but /// should be of type TCPEndpoint for a TCP connection. `````` Stephen Morris committed Feb 21, 2011 179 `````` /// \param callback I/O Completion callback, called when the operation has `````` Stephen Morris committed Feb 28, 2011 180 181 `````` /// completed, but only if the operation was asynchronous. (It is /// ignored on a UDP socket.) `````` Stephen Morris committed Feb 25, 2011 182 `````` virtual void open(const IOEndpoint* endpoint, C& callback) = 0; `````` Stephen Morris committed Feb 18, 2011 183 184 185 186 187 188 189 190 191 192 193 194 `````` /// \brief Send Asynchronously /// /// This corresponds to async_send_to() for UDP sockets and async_send() /// for TCP. In both cases an endpoint argument is supplied indicating the /// target of the send - this is ignored for TCP. /// /// \param data Data to send /// \param length Length of data to send /// \param endpoint Target of the send /// \param callback Callback object. virtual void asyncSend(const void* data, size_t length, `````` Stephen Morris committed Feb 25, 2011 195 `````` const IOEndpoint* endpoint, C& callback) = 0; `````` Stephen Morris committed Feb 18, 2011 196 197 198 `````` /// \brief Receive Asynchronously /// `````` Stephen Morris committed Feb 28, 2011 199 `````` /// This corresponds to async_receive_from() for UDP sockets and `````` Stephen Morris committed Feb 18, 2011 200 201 202 203 204 205 `````` /// async_receive() for TCP. In both cases, an endpoint argument is /// supplied to receive the source of the communication. For TCP it will /// be filled in with details of the connection. /// /// \param data Buffer to receive incoming message /// \param length Length of the data buffer `````` Stephen Morris committed Mar 04, 2011 206 207 208 209 210 `````` /// \param offset Offset into buffer where data is to be put. Although the /// offset could be implied by adjusting "data" and "length" /// appropriately, using this argument allows data to be specified as /// "const void*" - the overhead of converting it to a pointer to a /// set of bytes is hidden away here. `````` Stephen Morris committed Feb 18, 2011 211 212 `````` /// \param endpoint Source of the communication /// \param callback Callback object `````` Stephen Morris committed Feb 25, 2011 213 214 `````` virtual void asyncReceive(void* data, size_t length, size_t offset, IOEndpoint* endpoint, C& callback) = 0; `````` Stephen Morris committed Feb 18, 2011 215 `````` `````` Stephen Morris committed Mar 04, 2011 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 `````` /// \brief Processes received data /// /// In the IOFetch code, data is received into a staging buffer before being /// copied into the target buffer. (This is because (a) we don't know how /// much data we will be receiving, so don't know how to size the output /// buffer and (b) TCP data is preceded by a two-byte count field that needs /// to be discarded before being returned to the user.) /// /// An additional consideration is that TCP data is not received in one /// I/O - it may take a number of I/Os - each receiving any non-zero number /// of bytes - to read the entire message. /// /// So the IOFetch code has to loop until it determines that all the data /// has been read. This is where this method comes in. It has several /// functions: /// /// - It checks if the received data is complete. /// - If data is not complete, decides if the next set of data is to go into /// the start of the staging buffer or at some offset into it. (This /// simplifies the case we could have in a TCP receive where the two-byte /// count field is received in one-byte chunks: we put off interpreting /// the count until we have all of it. The alternative - copying the /// data to the output buffer and interpreting the count from there - /// would require moving the data in the output buffer by two bytes before /// returning it to the caller.) /// - Copies data from the staging buffer into the output buffer. /// /// This functionality mainly applies to TCP receives. For UDP, all the /// data is received in one I/O, so this just copies the data into the /// output buffer. /// /// \param staging Pointer to the start of the staging buffer. /// \param length Amount of data in the staging buffer. /// \param cumulative Amount of data received before the staging buffer is /// processed (this includes the TCP count field if appropriate). /// The value should be set to zero before the receive loop is /// entered, and it will be updated by this method as required. /// \param offset Offset into the staging buffer where the next read should /// put the received data. It should be set to zero before the first /// call and may be updated by this method. /// \param expected Expected amount of data to be received. This is /// really the TCP count field and is set to that value when enough /// of a TCP message is received. It should be initialized to -1 /// before the first read is executed. /// \param outbuff Output buffer. Data in the staging buffer may be copied /// to this output buffer in the call. `````` Stephen Morris committed Feb 18, 2011 262 263 `````` /// /// \return true if the receive is complete, false if another receive is `````` Stephen Morris committed Mar 04, 2011 264 265 266 267 268 269 270 271 272 `````` /// needed. This is always true for UDP, but for TCP involves /// checking the amount of data received so far against the amount /// expected (as indicated by the two-byte count field). If this /// method returns false, another read should be queued and data /// should be read into the staging buffer at offset given by the /// "offset" parameter. virtual bool processReceivedData(const void* staging, size_t length, size_t& cumulative, size_t& offset, size_t& expected, `````` chenzhengzhang committed Apr 14, 2011 273 `````` isc::util::OutputBufferPtr& outbuff) = 0; `````` Stephen Morris committed Feb 28, 2011 274 `````` `````` Stephen Morris committed Feb 18, 2011 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 `````` /// \brief Cancel I/O On AsioSocket virtual void cancel() = 0; /// \brief Close socket virtual void close() = 0; }; #include "io_socket.h" /// \brief The \c DummyAsioSocket class is a concrete derived class of /// \c IOAsioSocket that is not associated with any real socket. /// /// This main purpose of this class is tests, where it may be desirable to /// instantiate an \c IOAsioSocket object without involving system resource /// allocation such as real network sockets. /// /// \param C Template parameter identifying type of the callback object. template class DummyAsioSocket : public IOAsioSocket { private: DummyAsioSocket(const DummyAsioSocket& source); DummyAsioSocket& operator=(const DummyAsioSocket& source); public: /// \brief Constructor from the protocol number. /// /// The protocol must validly identify a standard network protocol. /// For example, to specify TCP \c protocol must be \c IPPROTO_TCP. /// /// \param protocol The network protocol number for the socket. DummyAsioSocket(const int protocol) : protocol_(protocol) {} /// \brief A dummy derived method of \c IOAsioSocket::getNative(). /// /// \return Always returns -1 as the object is not associated with a real /// (native) socket. virtual int getNative() const { return (-1); } /// \brief A dummy derived method of \c IOAsioSocket::getProtocol(). /// /// \return Protocol socket was created with virtual int getProtocol() const { return (protocol_); } `````` Stephen Morris committed Feb 25, 2011 320 321 322 323 324 325 326 `````` /// \brief Is socket opening synchronous? /// /// \return true - it is for this class. bool isOpenSynchronous() const { return true; } `````` Stephen Morris committed Feb 18, 2011 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 `````` /// \brief Open AsioSocket /// /// A call that is a no-op on UDP sockets, this opens a connection to the /// system identified by the given endpoint. /// /// \param endpoint Unused /// \param callback Unused. ///false indicating that the operation completed synchronously. virtual bool open(const IOEndpoint*, C&) { return (false); } /// \brief Send Asynchronously /// /// Must be supplied as it is abstract in the base class. /// /// \param data Unused /// \param length Unused /// \param endpoint Unused /// \param callback Unused virtual void asyncSend(const void*, size_t, const IOEndpoint*, C&) { } /// \brief Receive Asynchronously /// /// Must be supplied as it is abstract in the base class. /// /// \param data Unused /// \param length Unused `````` Stephen Morris committed Feb 25, 2011 356 `````` /// \param offset Unused `````` Stephen Morris committed Feb 18, 2011 357 358 `````` /// \param endpoint Unused /// \param callback Unused `````` Stephen Morris committed Feb 24, 2011 359 360 361 `````` virtual void asyncReceive(void* data, size_t, size_t, IOEndpoint*, C&) { } `````` Stephen Morris committed Feb 18, 2011 362 363 `````` /// \brief Checks if the data received is complete. /// `````` Stephen Morris committed Mar 04, 2011 364 `````` /// \param staging Unused `````` Stephen Morris committed Feb 18, 2011 365 366 `````` /// \param length Unused /// \param cumulative Unused `````` Stephen Morris committed Mar 04, 2011 367 368 369 `````` /// \param offset Unused. /// \param expected Unused. /// \param outbuff Unused. `````` Stephen Morris committed Feb 18, 2011 370 371 `````` /// /// \return Always true `````` Stephen Morris committed Mar 04, 2011 372 373 374 `````` virtual bool receiveComplete(const void* staging, size_t length, size_t& cumulative, size_t& offset, size_t& expected, `````` chenzhengzhang committed Apr 14, 2011 375 `````` isc::util::OutputBufferPtr& outbuff) `````` Stephen Morris committed Feb 28, 2011 376 `````` { `````` Stephen Morris committed Mar 04, 2011 377 `````` return (true); `````` Stephen Morris committed Feb 28, 2011 378 `````` } `````` Stephen Morris committed Feb 18, 2011 379 `````` `````` Stephen Morris committed Mar 04, 2011 380 `````` `````` Stephen Morris committed Feb 18, 2011 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 `````` /// \brief Cancel I/O On AsioSocket /// /// Must be supplied as it is abstract in the base class. virtual void cancel() { } /// \brief Close socket /// /// Must be supplied as it is abstract in the base class. virtual void close() { } private: const int protocol_; }; } // namespace asiolink `````` Ocean Wang committed Apr 08, 2011 398 ``````} // namespace isc `````` Stephen Morris committed Feb 18, 2011 399 400 `````` #endif // __IO_ASIO_SOCKET_H``````