ACE/ace/Asynch_Acceptor.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Asynch_Acceptor.h
   6  *
   7  *  @author Irfan Pyarali (irfan@cs.wustl.edu)
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_ASYNCH_ACCEPTOR_H
  12 #define ACE_ASYNCH_ACCEPTOR_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include /**/ "ace/config-all.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #if defined (ACE_HAS_WIN32_OVERLAPPED_IO) || defined (ACE_HAS_AIO_CALLS)
  22 // This only works on platforms that support async i/o.
  23
  24 #include "ace/Default_Constants.h"
  25 #include "ace/Asynch_IO.h"
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 // Forward declarations
  30 class ACE_Message_Block;
  31 class ACE_INET_Addr;
  32
  33 /**
  34  * @class ACE_Asynch_Acceptor
  35  *
  36  * @brief This class is an example of the Acceptor Pattern.  This class
  37  * will accept new connections and create new HANDLER to handle
  38  * the new connections.
  39  *
  40  * Unlike the ACE_Acceptor, however, this class is designed to
  41  * be used asynchronously.
  42  */
  43 template <class HANDLER>
  44 class ACE_Asynch_Acceptor : public ACE_Handler
  45 {
  46 public:
  47   /// A do nothing constructor.
  48   ACE_Asynch_Acceptor (void);
  49
  50   /// Virtual destruction
  51   virtual ~ACE_Asynch_Acceptor (void);
  52
  53   /**
  54    * @c open starts one or more asynchronous accept requests on a
  55    * @a address. Each accept operation may optionally read an
  56    * initial buffer from the new connection when accepted.
  57    *
  58    * @param address The address to listen/accept connections on.
  59    *                If the address does not specify a port, a random
  60    *                port is selected and bound.
  61    * @param bytes_to_read Optional, specifies the maximum number of bytes
  62    *                to read with the accept. The buffer for the initial
  63    *                data is allocated internally and passed to the
  64    *                @c ACE_Service_Handler::open() hook method. It is
  65    *                legitimate only during the @c open() method and must
  66    *                be copied if required after @c open() returns.
  67    *                This pre-read function works only on Windows.
  68    * @param pass_addresses Optional, a non-zero value indicates that
  69    *                the local and peer addresses should be passed to the
  70    *                associated @c ACE_Service_Handler::addresses() method
  71    *                after any call to @c validate_new_connection() and prior
  72    *                to the @c open() hook method call.
  73    * @param backlog Optional, defaulting to @c ACE_DEFAULT_ASYNCH_BACKLOG (which
  74    *                can be adjusted in your platform's @c config.h file).
  75    *                Specifies the listening backlog for the listening socket.
  76    * @param reuse_addr Optional, indicates whether the @c SO_REUSEADDR
  77    *                option is set on the listening socket or not.
  78    * @param proactor Optional, pointer to the @c ACE_Proactor to use for
  79    *                demultiplexing asynchronous accepts. If 0, the
  80    *                process's singleton @c ACE_Proactor is used.
  81    * @param validate_new_connection Optional, if true, this object's
  82    *                @c validate_connection() method is called after
  83    *                the accept completes, but before the service handler's
  84    *                @c open() hook method is called. If @c
  85    *                validate_connection() returns -1, the newly-accepted
  86    *                socket is immediately closed, and the @c addresses()
  87    *                method is not called.
  88    * @param reissue_accept Optional, if non-zero (the default), a new
  89    *                asynchronous accept operation is started after each
  90    *                completion, whether the completion is for success or
  91    *                failure, and whether or not a successfully-accepted
  92    *                connection is subsequently refused.
  93    * @param number_of_initial_accepts Optional, the number of asynchronous
  94    *                accepts that are started immediately. If -1 (the
  95    *                default), the value of @a backlog is used.
  96    *
  97    * @note On Windows, the peer address is only available at the time
  98    *       the connection is accepted.  Therefore, if you require the peer
  99    *       address on Windows, do not rely on the
 100    *       @c ACE_SOCK::get_remote_addr() method - it won't work. You must
 101    *       supply a non-zero value for @a pass_addresses and obtain the
 102    *       peer address in the @c ACE_Service_Handler::addresses() method.
 103    *
 104    * @see ACE_INET_Addr
 105    * @see ACE_Service_Handler
 106    */
 107   virtual int open (const ACE_INET_Addr &address,
 108                     size_t bytes_to_read = 0,
 109                     bool pass_addresses = false,
 110                     int backlog = ACE_DEFAULT_ASYNCH_BACKLOG,
 111                     int reuse_addr = 1,
 112                     ACE_Proactor *proactor = 0,
 113                     bool validate_new_connection = false,
 114                     int reissue_accept = 1,
 115                     int number_of_initial_accepts = -1);
 116
 117   /// Get the underlying handle.
 118   virtual ACE_HANDLE get_handle (void) const;
 119
 120   /**
 121    * Set the underlying listen handle. It is the user's responsibility
 122    * to make sure that the old listen handle has been appropriately
 123    * closed and the all outstanding asynchronous operations have
 124    * either completed or have been canceled on the old listen handle.
 125    */
 126   virtual int set_handle (ACE_HANDLE handle);
 127
 128   /// This initiates a new asynchronous accept operation.
 129   /**
 130    * You need only call this method if the @a reissue_accept argument
 131    * passed to @c open() was 0.
 132    */
 133   virtual int accept (size_t bytes_to_read = 0, const void *act = 0);
 134
 135   /**
 136    * Cancels all pending accepts operations issued by this object.
 137    *
 138    * @note On Windows, only accept operations initiated by the calling thread
 139    *       are canceled.
 140    */
 141   virtual int cancel (void);
 142
 143   /**
 144    * Template method to validate peer before service is opened.
 145    * This method is called after a new connection is accepted if the
 146    * @a validate_connection argument to @c open() was non-zero or
 147    * the @c validate_new_connection() method is called to turn this
 148    * feature on.  The default implementation returns 0.  Users can
 149    * reimplement this method to perform validation of the peer
 150    * using it's address, running an authentication procedure (such as
 151    * SSL) or anything else necessary or desireable. The return value
 152    * from this method determines whether or not ACE will continue
 153    * opening the service or abort the connection.
 154    *
 155    * @param result    Result of the connection acceptance.
 156    * @param remote    Peer's address.
 157    * @param local     Local address connection was accepted at.
 158    *
 159    * @retval  -1  ACE_Asynch_Acceptor will close the connection, and
 160    *              the service will not be opened.
 161    * @retval  0   Service opening will proceeed.
 162    */
 163   virtual int validate_connection (const ACE_Asynch_Accept::Result& result,
 164                                    const ACE_INET_Addr &remote,
 165                                    const ACE_INET_Addr& local);
 166
 167   /**
 168    * Template method for deciding whether to reissue accept.
 169    *
 170    * This hook method is called after each accept completes to decide if
 171    * another accept should be initiated. If the method returns a non-zero
 172    * value, another accept is initiated.
 173    *
 174    * The default implementation always returns the value passed as the
 175    * @c open() method's @a reissue_accept argument. That value can also
 176    * be changed using the @c reissue_accept() method.
 177    */
 178   virtual int should_reissue_accept (void);
 179
 180   //
 181   // These are low level tweaking methods
 182   //
 183
 184   /// Get flag that indicates if parsing and passing of addresses to
 185   /// the service_handler is necessary.
 186   virtual bool pass_addresses (void) const;
 187
 188   /// Set flag that indicates if parsing and passing of addresses to
 189   /// the service_handler is necessary.
 190   virtual void pass_addresses (bool new_value);
 191
 192   /// Get flag that indicates if address validation is required.
 193   virtual bool validate_new_connection (void) const;
 194
 195   /// Set flag that indicates if address validation is required.
 196   virtual void validate_new_connection (bool new_value);
 197
 198   /// Get flag that indicates if a new accept should be reissued when a accept
 199   /// completes.
 200   virtual int reissue_accept (void) const;
 201
 202   /// Set flag that indicates if a new accept should be reissued when a accept
 203   /// completes.
 204   virtual void reissue_accept (int new_value);
 205
 206   /// Get bytes to be read with the <accept> call.
 207   virtual size_t bytes_to_read (void) const;
 208
 209   /// Set bytes to be read with the <accept> call.
 210   virtual void bytes_to_read (size_t new_value);
 211
 212 protected:
 213
 214   /// This is called when an outstanding accept completes.
 215   virtual void handle_accept (const ACE_Asynch_Accept::Result &result);
 216
 217   /// Return the listen handle.
 218   ACE_HANDLE handle (void) const;
 219   /// Set the listen handle.
 220   void handle (ACE_HANDLE h);
 221
 222   /// This parses the address from read buffer.
 223   void parse_address (const ACE_Asynch_Accept::Result &result,
 224                       ACE_INET_Addr &remote_address,
 225                       ACE_INET_Addr &local_address);
 226
 227   /// Return the asynch accept object.
 228   ACE_Asynch_Accept &asynch_accept (void);
 229
 230   /**
 231    * This is the template method used to create new handler.
 232    * Subclasses must overwrite this method if a new handler creation
 233    * strategy is required.
 234    */
 235   virtual HANDLER *make_handler (void);
 236
 237 private:
 238   /// Handle used to listen for new connections.
 239   ACE_HANDLE listen_handle_;
 240
 241   /// Asynch_Accept used to make life easier :-)
 242   ACE_Asynch_Accept asynch_accept_;
 243
 244   /// Flag that indicates if parsing of addresses is necessary.
 245   bool pass_addresses_;
 246
 247   /// Flag that indicates if address validation is required.
 248   bool validate_new_connection_;
 249
 250   /// Flag that indicates if a new accept should be reissued when a
 251   /// accept completes.
 252   int reissue_accept_;
 253
 254   /// Bytes to be read with the <accept> call.
 255   size_t bytes_to_read_;
 256
 257   /// Address family used to open this object. Obtained from @a address passed
 258   /// to @c open().
 259   int addr_family_;
 260 };
 261
 262 ACE_END_VERSIONED_NAMESPACE_DECL
 263
 264 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 265 #include "ace/Asynch_Acceptor.cpp"
 266 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 267
 268 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 269 #pragma implementation ("Asynch_Acceptor.cpp")
 270 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 271
 272 #endif /* ACE_HAS_WIN32_OVERLAPPED_IO || ACE_HAS_AIO_CALLS */
 273 #include /**/ "ace/post.h"
 274 #endif /* ACE_ASYNCH_ACCEPTOR_H */