ACE/ace/WIN32_Proactor.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    WIN32_Proactor.h
   6  *
   7  *  @author Irfan Pyarali (irfan@cs.wustl.edu)
   8  *  @author Tim Harrison (harrison@cs.wustl.edu)
   9  *  @author Alexander Babu Arulanthu <alex@cs.wustl.edu>
  10  *  @author Roger Tragin <r.tragin@computer.org>
  11  *  @author Alexander Libman <alibman@ihug.com.au>
  12  */
  13 //=============================================================================
  14
  15 #ifndef ACE_WIN32_PROACTOR_H
  16 #define ACE_WIN32_PROACTOR_H
  17 #include /**/ "ace/pre.h"
  18
  19 #include /**/ "ace/config-all.h"
  20
  21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  22 #pragma once
  23 #endif /* ACE_LACKS_PRAGMA_ONCE */
  24
  25 #if defined (ACE_WIN32) && defined (ACE_HAS_WIN32_OVERLAPPED_IO)
  26 // WIN32 implementation of the Proactor.
  27
  28 #include "ace/WIN32_Asynch_IO.h"
  29 #include "ace/Event_Handler.h"
  30
  31 #include "ace/Proactor_Impl.h"
  32 #include "ace/Asynch_Pseudo_Task.h"
  33 #include "ace/Auto_Event.h"
  34
  35 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  36
  37 // Forward declarations.
  38 class ACE_WIN32_Asynch_Result;
  39 class ACE_WIN32_Proactor_Timer_Handler;
  40
  41 /**
  42  * @class ACE_WIN32_Proactor
  43  *
  44  * @brief A manager for asynchronous event demultiplexing on Win32.
  45  *
  46  * See the Proactor pattern description at
  47  * http://www.dre.vanderbilt.edu/~schmidt/PDF/proactor.pdf for more
  48  * details.
  49  */
  50 class ACE_Export ACE_WIN32_Proactor : public ACE_Proactor_Impl
  51 {
  52   friend class ACE_WIN32_Asynch_Connect;
  53
  54 public:
  55   /// A do nothing constructor.
  56   ACE_WIN32_Proactor (size_t number_of_threads = 0,
  57                       bool used_with_reactor_event_loop = false);
  58
  59   /// Virtual destruction.
  60   virtual ~ACE_WIN32_Proactor ();
  61
  62   /// Close the IO completion port.
  63   virtual int close ();
  64
  65   /// This method adds the @a handle to the I/O completion port. This
  66   /// function is a no-op function for Unix systems.
  67   virtual int register_handle (ACE_HANDLE handle,
  68                                const void *completion_key);
  69
  70   /**
  71    * Dispatch a single set of events.  If @a wait_time elapses before
  72    * any events occur, return 0.  Return 1 on success i.e., when a
  73    * completion is dispatched, non-zero (-1) on errors and errno is
  74    * set accordingly.
  75    */
  76   virtual int handle_events (ACE_Time_Value &wait_time);
  77
  78   /**
  79    * Block indefinitely until at least one event is dispatched.
  80    * Dispatch a single set of events. Return 1 on success i.e., when a
  81    * completion is dispatched, non-zero (-1) on errors and errno is
  82    * set accordingly.
  83    */
  84   virtual int handle_events ();
  85
  86   /**
  87    * Post a result to the completion port of the Proactor.  If errors
  88    * occur, the result will be deleted by this method.  If successful,
  89    * the result will be deleted by the Proactor when the result is
  90    * removed from the completion port.  Therefore, the result should
  91    * have been dynamically allocated and should be orphaned by the
  92    * user once this method is called.
  93    */
  94   virtual int post_completion (ACE_WIN32_Asynch_Result *result);
  95
  96   /// Add wakeup dispatch threads (reinit).
  97   int wake_up_dispatch_threads ();
  98
  99   /// Close all dispatch threads.
 100   int close_dispatch_threads (int wait);
 101
 102   /// Get number of thread used as a parameter to @c CreateIoCompletionPort.
 103   size_t number_of_threads () const;
 104
 105   /// Set number of thread used as a parameter to @c CreateIoCompletionPort.
 106   void number_of_threads (size_t threads);
 107
 108   /// Get the event handle.
 109   virtual ACE_HANDLE get_handle () const;
 110
 111   virtual ACE_Asynch_Read_Stream_Impl *create_asynch_read_stream ();
 112   virtual ACE_Asynch_Write_Stream_Impl *create_asynch_write_stream ();
 113   virtual ACE_Asynch_Read_File_Impl *create_asynch_read_file ();
 114   virtual ACE_Asynch_Write_File_Impl *create_asynch_write_file ();
 115   virtual ACE_Asynch_Read_Dgram_Impl *create_asynch_read_dgram ();
 116   virtual ACE_Asynch_Write_Dgram_Impl *create_asynch_write_dgram ();
 117   virtual ACE_Asynch_Accept_Impl *create_asynch_accept ();
 118   virtual ACE_Asynch_Connect_Impl *create_asynch_connect ();
 119   virtual ACE_Asynch_Transmit_File_Impl *create_asynch_transmit_file ();
 120
 121   // Methods used to create Asynch_IO_Result objects. We create the right
 122   // objects here in these methods.
 123
 124   virtual ACE_Asynch_Read_Stream_Result_Impl *create_asynch_read_stream_result (const ACE_Handler::Proxy_Ptr &handler_proxy,
 125                                                                                 ACE_HANDLE handle,
 126                                                                                 ACE_Message_Block &message_block,
 127                                                                                 size_t bytes_to_read,
 128                                                                                 const void* act,
 129                                                                                 ACE_HANDLE event,
 130                                                                                 int priority,
 131                                                                                 int signal_number = 0);
 132
 133   virtual ACE_Asynch_Write_Stream_Result_Impl *create_asynch_write_stream_result (const ACE_Handler::Proxy_Ptr &handler_proxy,
 134                                                                                   ACE_HANDLE handle,
 135                                                                                   ACE_Message_Block &message_block,
 136                                                                                   size_t bytes_to_write,
 137                                                                                   const void* act,
 138                                                                                   ACE_HANDLE event,
 139                                                                                   int priority,
 140                                                                                   int signal_number = 0);
 141
 142   virtual ACE_Asynch_Read_File_Result_Impl *create_asynch_read_file_result (const ACE_Handler::Proxy_Ptr &handler_proxy,
 143                                                                             ACE_HANDLE handle,
 144                                                                             ACE_Message_Block &message_block,
 145                                                                             size_t bytes_to_read,
 146                                                                             const void* act,
 147                                                                             u_long offset,
 148                                                                             u_long offset_high,
 149                                                                             ACE_HANDLE event,
 150                                                                             int priority,
 151                                                                             int signal_number = 0);
 152
 153   virtual ACE_Asynch_Write_File_Result_Impl *create_asynch_write_file_result (const ACE_Handler::Proxy_Ptr &handler_proxy,
 154                                                                               ACE_HANDLE handle,
 155                                                                               ACE_Message_Block &message_block,
 156                                                                               size_t bytes_to_write,
 157                                                                               const void* act,
 158                                                                               u_long offset,
 159                                                                               u_long offset_high,
 160                                                                               ACE_HANDLE event,
 161                                                                               int priority,
 162                                                                               int signal_number = 0);
 163
 164   /// Create the correct implementation class for ACE_Asynch_Read_Dgram::Result.
 165   virtual ACE_Asynch_Read_Dgram_Result_Impl *create_asynch_read_dgram_result (const ACE_Handler::Proxy_Ptr &handler_proxy,
 166                                                                               ACE_HANDLE handle,
 167                                                                               ACE_Message_Block *message_block,
 168                                                                               size_t bytes_to_read,
 169                                                                               int flags,
 170                                                                               int protocol_family,
 171                                                                               const void* act,
 172                                                                               ACE_HANDLE event,
 173                                                                               int priority,
 174                                                                               int signal_number = 0);
 175
 176   /// Create the correct implementation class for ACE_Asynch_Write_Dgram::Result.
 177   virtual ACE_Asynch_Write_Dgram_Result_Impl *create_asynch_write_dgram_result (const ACE_Handler::Proxy_Ptr &handler_proxy,
 178                                                                                 ACE_HANDLE handle,
 179                                                                                 ACE_Message_Block *message_block,
 180                                                                                 size_t bytes_to_write,
 181                                                                                 int flags,
 182                                                                                 const void* act,
 183                                                                                 ACE_HANDLE event,
 184                                                                                 int priority,
 185                                                                                 int signal_number = 0);
 186
 187   virtual ACE_Asynch_Accept_Result_Impl *create_asynch_accept_result (const ACE_Handler::Proxy_Ptr &handler_proxy,
 188                                                                       ACE_HANDLE listen_handle,
 189                                                                       ACE_HANDLE accept_handle,
 190                                                                       ACE_Message_Block &message_block,
 191                                                                       size_t bytes_to_read,
 192                                                                       const void* act,
 193                                                                       ACE_HANDLE event,
 194                                                                       int priority,
 195                                                                       int signal_number = 0);
 196
 197   virtual ACE_Asynch_Connect_Result_Impl *create_asynch_connect_result (const ACE_Handler::Proxy_Ptr &handler_proxy,
 198                                                                         ACE_HANDLE connect_handle,
 199                                                                         const void *act,
 200                                                                         ACE_HANDLE event,
 201                                                                         int priority,
 202                                                                         int signal_number = 0);
 203
 204
 205   virtual ACE_Asynch_Transmit_File_Result_Impl *create_asynch_transmit_file_result (const ACE_Handler::Proxy_Ptr &handler_proxy,
 206                                                                                     ACE_HANDLE socket,
 207                                                                                     ACE_HANDLE file,
 208                                                                                     ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer,
 209                                                                                     size_t bytes_to_write,
 210                                                                                     u_long offset,
 211                                                                                     u_long offset_high,
 212                                                                                     size_t bytes_per_send,
 213                                                                                     u_long flags,
 214                                                                                     const void *act,
 215                                                                                     ACE_HANDLE event,
 216                                                                                     int priority,
 217                                                                                     int signal_number = 0);
 218
 219   /// Create a timer result object which can be used with the Timer
 220   /// mechanism of the Proactor.
 221   virtual ACE_Asynch_Result_Impl *create_asynch_timer (const ACE_Handler::Proxy_Ptr &handler_proxy,
 222                                                        const void *act,
 223                                                        const ACE_Time_Value &tv,
 224                                                        ACE_HANDLE event,
 225                                                        int priority,
 226                                                        int signal_number = 0);
 227
 228 protected:
 229   /// Task to process pseudo-asynchronous operations
 230   ACE_Asynch_Pseudo_Task & get_asynch_pseudo_task ();
 231
 232   /// Called when object is signaled by OS (either via UNIX signals or
 233   /// when a Win32 object becomes signaled).
 234   virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0);
 235
 236   /// Called when object is removed from the ACE_Reactor.
 237   virtual int handle_close (ACE_HANDLE handle,
 238                             ACE_Reactor_Mask close_mask);
 239
 240   /**
 241    * Dispatch a single set of events.  If @a milli_seconds elapses
 242    * before any events occur, return 0. Return 1 if a completion is
 243    * dispatched. Return -1 on errors.
 244    */
 245   virtual int handle_events (unsigned long milli_seconds);
 246
 247   /// Protect against structured exceptions caused by user code when
 248   /// dispatching handles.
 249   void application_specific_code (ACE_WIN32_Asynch_Result *asynch_result,
 250                                   size_t bytes_transferred,
 251                                   const void *completion_key,
 252                                   u_long error);
 253
 254   /**
 255    * Post @a how_many completions to the completion port so that all
 256    * threads can wake up. This is used in conjunction with the
 257    * run_event_loop().
 258    */
 259   virtual int post_wakeup_completions (int how_many);
 260
 261   /// Handle for the completion port. Unix doesnt have completion
 262   /// ports.
 263   ACE_HANDLE completion_port_;
 264
 265   /// This number is passed to the @c CreateIOCompletionPort system
 266   /// call.
 267   DWORD number_of_threads_;
 268
 269   /// This event is used in conjunction with Reactor when we try to
 270  /// integrate the event loops of Reactor and the Proactor.
 271   ACE_Auto_Event event_;
 272
 273   /// Flag that indicates whether we are used in conjunction with
 274   /// Reactor.
 275   bool const used_with_reactor_event_loop_;
 276
 277   /// Handler to handle the wakeups. This works in conjunction with the
 278   /// ACE_Proactor::run_event_loop().
 279   ACE_Handler wakeup_handler_;
 280
 281   /// Pseudo-task for asynch connect ( NT/2000)
 282   /// In future should removed in XP with ConnectEx support
 283   ACE_Asynch_Pseudo_Task pseudo_task_;
 284 };
 285
 286 /**
 287  * @class ACE_WIN32_Asynch_Timer
 288  *
 289  * @brief This class is posted to the completion port when a timer
 290  * expires. When the complete method of this object is
 291  * called, the @a handler's handle_timeout method will be
 292  * called.
 293  */
 294 class ACE_WIN32_Asynch_Timer : public ACE_WIN32_Asynch_Result
 295 {
 296   /// The factory method for this class is with the POSIX_Proactor
 297   /// class.
 298   friend class ACE_WIN32_Proactor;
 299
 300 protected:
 301   /// Constructor.
 302   ACE_WIN32_Asynch_Timer (const ACE_Handler::Proxy_Ptr &handler_proxy,
 303                           const void *act,
 304                           const ACE_Time_Value &tv,
 305                           ACE_HANDLE event = ACE_INVALID_HANDLE,
 306                           int priority = 0,
 307                           int signal_number = 0);
 308
 309   /// This method calls the @a handler's handle_timeout method.
 310   virtual void complete (size_t bytes_transferred,
 311                          int success,
 312                          const void *completion_key,
 313                          u_long error = 0);
 314
 315   /// Time value requested by caller
 316   ACE_Time_Value time_;
 317 };
 318
 319 ACE_END_VERSIONED_NAMESPACE_DECL
 320
 321 #endif /* ACE_WIN32 */
 322 #include /**/ "ace/post.h"
 323 #endif /* ACE_PROACTOR_H */