Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Asynch_IO.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Asynch_IO.h
00006  *
00007  *  $Id: Asynch_IO.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  This works on Win32 (#if defined (ACE_WIN32) && !defined
00010  *  (ACE_HAS_WINCE)) platforms and on POSIX4 platforms with <aio_*>
00011  *  routines (#if defined (ACE_HAS_AIO_CALLS))
00012  *
00013  *  On Win32 platforms, the implementation of
00014  *  <ACE_Asynch_Transmit_File> and <ACE_Asynch_Accept> are only
00015  *  supported if ACE_HAS_WINSOCK2 is defined or you are on WinNT 4.0
00016  *  or higher.
00017  *
00018  *  @author Irfan Pyarali <irfan@cs.wustl.edu>
00019  *  @author Tim Harrison <harrison@cs.wustl.edu>
00020  *  @author Alexander Babu Arulanthu <alex@cs.wustl.edu>
00021  *  @author Roger Tragin <r.tragin@computer.org>
00022  *  @author Alexander Libman <alibman@ihug.com.au>
00023  */
00024 //=============================================================================
00025 
00026 #ifndef ACE_ASYNCH_IO_H
00027 #define ACE_ASYNCH_IO_H
00028 #include "ace/pre.h"
00029 
00030 #include "ace/config-all.h"
00031 
00032 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00033 #pragma once
00034 #endif /* ACE_LACKS_PRAGMA_ONCE */
00035 
00036 #if (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)) || (defined (ACE_HAS_AIO_CALLS))
00037 
00038 #include "ace/OS.h"
00039 
00040 // Forward declarations
00041 class ACE_Proactor;
00042 class ACE_Handler;
00043 class ACE_Message_Block;
00044 class ACE_INET_Addr;
00045 class ACE_Addr;
00046 
00047 // Forward declarations
00048 class ACE_Asynch_Result_Impl;
00049 
00050 /**
00051  * @class ACE_Asynch_Result
00052  *
00053  * @brief An interface base class which allows users access to common
00054  * information related to an asynchronous operation.
00055  *
00056  * An interface base class from which you can obtain some basic
00057  * information like the number of bytes transferred, the ACT
00058  * associated with the asynchronous operation, indication of
00059  * success or failure, etc. Subclasses may want to store more
00060  * information that is particular to the asynchronous operation
00061  * it represents.
00062  */
00063 class ACE_Export ACE_Asynch_Result
00064 {
00065 
00066 public:
00067   /// Number of bytes transferred by the operation.
00068   size_t bytes_transferred (void) const;
00069 
00070   /// ACT associated with the operation.
00071   const void *act (void) const;
00072 
00073   /// Did the operation succeed?
00074   int success (void) const;
00075 
00076   /**
00077    * This is the ACT associated with the handle on which the
00078    * Asynch_Operation takes place.
00079    *
00080    * On WIN32, this returns the ACT associated with the handle when it
00081    * was registered with the I/O completion port.
00082    *
00083    * @@ This is not implemented for POSIX4 platforms. Returns 0.
00084    */
00085   const void *completion_key (void) const;
00086 
00087   /// Error value if the operation fails.
00088   u_long error (void) const;
00089 
00090   /**
00091    * On WIN32, this returns the event associated with the OVERLAPPED
00092    * structure.
00093    *
00094    * This returns ACE_INVALID_HANDLE on POSIX4-Unix platforms.
00095    */
00096   ACE_HANDLE event (void) const;
00097 
00098   /**
00099    * This really makes sense only when doing file I/O.
00100    *
00101    * On WIN32, these are represented in the OVERLAPPED datastructure.
00102    *
00103    * @@ On POSIX4-Unix, offset_high should be supported using
00104    *    aiocb64.
00105    */
00106   u_long offset (void) const;
00107   u_long offset_high (void) const;
00108 
00109   /**
00110    * Priority of the operation.
00111    *
00112    * On POSIX4-Unix, this is supported. Priority works like <nice> in
00113    * Unix. Negative values are not allowed. 0 means priority of the
00114    * operation same as the process priority. 1 means priority of the
00115    * operation is one less than process. And so forth.
00116    *
00117    * On Win32, this is a no-op.
00118    */
00119   int priority (void) const;
00120 
00121   /**
00122    * POSIX4 real-time signal number to be used for the
00123    * operation. <signal_number> ranges from ACE_SIGRTMIN to ACE_SIGRTMAX. By
00124    * default, ACE_SIGRTMIN is used to issue <aio_> calls. This is a no-op
00125    * on non-POSIX4 systems and returns 0.
00126    */
00127   int signal_number (void) const;
00128 
00129 
00130   /// Destructor.
00131   virtual ~ACE_Asynch_Result (void);
00132 
00133 protected:
00134   /// Constructor. This implementation will not be deleted.  The
00135   /// implementation will be deleted by the Proactor.
00136   ACE_Asynch_Result (ACE_Asynch_Result_Impl *implementation);
00137 
00138   /// Get the implementation class.
00139   ACE_Asynch_Result_Impl *implementation (void) const;
00140 
00141   /// Implementation class.
00142   ACE_Asynch_Result_Impl *implementation_;
00143 };
00144 
00145 // Forward declarations
00146 class ACE_Asynch_Operation_Impl;
00147 
00148 /**
00149  * @class ACE_Asynch_Operation
00150  *
00151  * @brief This is an interface base class for all asynch
00152  * operations. The resposiblility of this class is to forward
00153  * all methods to its delegation/implementation class, e.g.,
00154  * <ACE_WIN32_Asynch_Operation> or <ACE_POSIX_Asynch_Operation>.
00155  *
00156  * There are some attributes and functionality which is common
00157  * to all asychronous operations. The delegation classes of this
00158  * class will factor out this code.
00159  */
00160 class ACE_Export ACE_Asynch_Operation
00161 {
00162 
00163 public:
00164   /**
00165    * Initializes the factory with information which will be used with
00166    * each asynchronous call.  If (<handle> == ACE_INVALID_HANDLE),
00167    * <ACE_Handler::handle> will be called on the <handler> to get the
00168    * correct handle.
00169    */
00170   int open (ACE_Handler &handler,
00171             ACE_HANDLE handle,
00172             const void *completion_key,
00173             ACE_Proactor *proactor);
00174 
00175   /**
00176    * (Attempts to) cancel the asynchronous operation pending against
00177    * the <handle> registered with this Operation.
00178    *
00179    * All completion notifications for the I/O operations will occur
00180    * normally.
00181    *
00182    * = Return Values:
00183    *
00184    * -1 : Operation failed. (can get only in POSIX).
00185    *  0 : All the operations were cancelled.
00186    *  1 : All the operations were already finished in this
00187    *      handle. Unable to cancel them.
00188    *  2 : Atleast one of the requested operations cannot be
00189    *      cancelled.
00190    *
00191    * There is slight difference in the semantics between NT and POSIX
00192    * platforms which is given below.
00193    *
00194    * = Win32 :
00195    *
00196    *   cancels all pending accepts operations that were issued by the
00197    *   calling thread.  The function does not cancel asynchronous
00198    *   operations issued by other threads.
00199    *   All I/O operations that are canceled will complete with the
00200    *   error ERROR_OPERATION_ABORTED.
00201    *
00202    * = POSIX:
00203    *
00204    *   Attempts to cancel one or more asynchronous I/O requests
00205    *   currently outstanding against the <handle> registered in this
00206    *   operation.
00207    *   For requested operations that are successfully canceled, the
00208    *   associated  error  status is set to ECANCELED.
00209    */
00210   int cancel (void);
00211 
00212 
00213   // = Access methods.
00214 
00215   /// Return the underlying proactor.
00216   ACE_Proactor* proactor (void) const;
00217 
00218   /// Destructor.
00219   virtual ~ACE_Asynch_Operation (void);
00220 
00221 protected:
00222   /// Constructor.
00223   ACE_Asynch_Operation (void);
00224 
00225   /// Return the underlying implementation class.
00226   ACE_Asynch_Operation_Impl *implementation (void) const;
00227 
00228   /// Set the implementation class.
00229   void implementation (ACE_Asynch_Operation_Impl *implementation);
00230 
00231   /// Get a proactor for/from the user
00232   ACE_Proactor *get_proactor (ACE_Proactor *user_proactor,
00233                               ACE_Handler &handler) const;
00234 
00235   /// Implementation class.
00236   ACE_Asynch_Operation_Impl *implementation_;
00237 };
00238 
00239 // Forward declarations
00240 class ACE_Asynch_Read_Stream_Result_Impl;
00241 class ACE_Asynch_Read_Stream_Impl;
00242 
00243 /**
00244  * @class ACE_Asynch_Read_Stream
00245  *
00246  * @brief This class is a factory for starting off asynchronous reads
00247  * on a stream. This class forwards all methods to its
00248  * implementation class.
00249  *
00250  * Once <open> is called, multiple asynchronous <read>s can
00251  * started using this class.  An ACE_Asynch_Read_Stream::Result
00252  * will be passed back to the <handler> when the asynchronous
00253  * reads completes through the <ACE_Handler::handle_read_stream>
00254  * callback.
00255  */
00256 class ACE_Export ACE_Asynch_Read_Stream : public ACE_Asynch_Operation
00257 {
00258 
00259 public:
00260   /// A do nothing constructor.
00261   ACE_Asynch_Read_Stream (void);
00262 
00263   /// Destructor
00264   virtual ~ACE_Asynch_Read_Stream (void);
00265 
00266   /**
00267    * Initializes the factory with information which will be used with
00268    * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE),
00269    * <ACE_Handler::handle> will be called on the <handler> to get the
00270    * correct handle.
00271    */
00272   int open (ACE_Handler &handler,
00273             ACE_HANDLE handle = ACE_INVALID_HANDLE,
00274             const void *completion_key = 0,
00275             ACE_Proactor *proactor = 0);
00276 
00277   /**
00278    * This starts off an asynchronous read.  Upto <bytes_to_read> will
00279    * be read and stored in the <message_block>. <message_block>'s
00280    * <wr_ptr> will be updated to reflect the added bytes if the read
00281    * operation is successful completed. Priority of the
00282    * operation is specified by <priority>. On POSIX4-Unix, this is
00283    * supported. Works like <nice> in Unix. Negative values are not
00284    * allowed. 0 means priority of the operation same as the process
00285    * priority. 1 means priority of the operation is one less than
00286    * process. And so forth. On Win32, <priority> is a no-op.
00287    * <signal_number> is the POSIX4 real-time signal number to be used
00288    * for the operation. <signal_number> ranges from ACE_SIGRTMIN to
00289    * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems.
00290    */
00291   int read (ACE_Message_Block &message_block,
00292             size_t num_bytes_to_read,
00293             const void *act = 0,
00294             int priority = 0,
00295             int signal_number = ACE_SIGRTMIN);
00296 
00297 #if (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE) && (ACE_HAS_WINNT4) && (ACE_HAS_WINNT4 != 0))
00298   /**
00299   * Same as above but with scatter support, through chaining of composite
00300   * message blocks using the continuation field.
00301   */
00302   int readv (ACE_Message_Block &message_block,
00303              size_t num_bytes_to_read,
00304              const void *act = 0,
00305              int priority = 0,
00306              int signal_number = ACE_SIGRTMIN);
00307 #endif /* (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE) && (ACE_HAS_WINNT4) && (ACE_HAS_WINNT4 != 0)) */
00308 
00309   /// Return the underlying implementation class.
00310   ACE_Asynch_Read_Stream_Impl *implementation (void) const;
00311 
00312 protected:
00313   /// Set the implementation class.
00314   void implementation (ACE_Asynch_Read_Stream_Impl *implementation);
00315 
00316   /// Implementation class that all methods will be forwarded to.
00317   ACE_Asynch_Read_Stream_Impl *implementation_;
00318 
00319 public:
00320 /**
00321  * @class Result
00322  *
00323  * @brief This is the class which will be passed back to the
00324  * <handler> when the asynchronous read completes. This class
00325  * forwards all the methods to the implementation classes.
00326  *
00327  * This class has all the information necessary for the
00328  * <handler> to uniquiely identify the completion of the
00329  * asynchronous read.
00330  */
00331   class ACE_Export Result : public ACE_Asynch_Result
00332   {
00333 
00334     /// The concrete implementation result classes only construct this
00335     /// class.
00336     friend class ACE_POSIX_Asynch_Read_Stream_Result;
00337     friend class ACE_WIN32_Asynch_Read_Stream_Result;
00338 
00339   public:
00340     /// The number of bytes which were requested at the start of the
00341     /// asynchronous read.
00342     size_t bytes_to_read (void) const;
00343 
00344     /// Message block which contains the read data.
00345     ACE_Message_Block &message_block (void) const;
00346 
00347     /// I/O handle used for reading.
00348     ACE_HANDLE handle (void) const;
00349 
00350     /// Get the implementation class.
00351     ACE_Asynch_Read_Stream_Result_Impl *implementation (void) const;
00352 
00353   protected:
00354     /// Constructor.
00355     Result (ACE_Asynch_Read_Stream_Result_Impl *implementation);
00356 
00357     /// Destructor.
00358     virtual ~Result (void);
00359 
00360     /// The implementation class.
00361     ACE_Asynch_Read_Stream_Result_Impl *implementation_;
00362   };
00363 };
00364 
00365 // Forward declarations
00366 class ACE_Asynch_Write_Stream_Impl;
00367 class ACE_Asynch_Write_Stream_Result_Impl;
00368 
00369 /**
00370  * @class ACE_Asynch_Write_Stream
00371  *
00372  * @brief This class is a factory for starting off asynchronous writes
00373  * on a stream. This class forwards all methods to its
00374  * implementation class.
00375  *
00376  * Once <open> is called, multiple asynchronous <writes>s can
00377  * started using this class.  An ACE_Asynch_Write_Stream::Result
00378  * will be passed back to the <handler> when the asynchronous
00379  * write completes through the
00380  * <ACE_Handler::handle_write_stream> callback.
00381  */
00382 class ACE_Export ACE_Asynch_Write_Stream : public ACE_Asynch_Operation
00383 {
00384 
00385 public:
00386   /// A do nothing constructor.
00387   ACE_Asynch_Write_Stream (void);
00388 
00389   /// Destructor.
00390   virtual ~ACE_Asynch_Write_Stream (void);
00391 
00392   /**
00393    * Initializes the factory with information which will be used with
00394    * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE),
00395    * <ACE_Handler::handle> will be called on the <handler> to get the
00396    * correct handle.
00397    */
00398   int open (ACE_Handler &handler,
00399             ACE_HANDLE handle = ACE_INVALID_HANDLE,
00400             const void *completion_key = 0,
00401             ACE_Proactor *proactor = 0);
00402 
00403   /**
00404    * This starts off an asynchronous write.  Upto <bytes_to_write>
00405    * will be written from the <message_block>. Upon successful completion
00406    * of the write operation, <message_block>'s <rd_ptr> is updated to
00407    * reflect the data that was written. Priority of the
00408    * operation is specified by <priority>. On POSIX4-Unix, this is
00409    * supported. Works like <nice> in Unix. Negative values are not
00410    * allowed. 0 means priority of the operation same as the process
00411    * priority. 1 means priority of the operation is one less than
00412    * process. And so forth. On Win32, this argument is a no-op.
00413    * <signal_number> is the POSIX4 real-time signal number to be used
00414    * for the operation. <signal_number> ranges from ACE_SIGRTMIN to
00415    * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems.
00416    */
00417   int write (ACE_Message_Block &message_block,
00418              size_t bytes_to_write,
00419              const void *act = 0,
00420              int priority = 0,
00421              int signal_number = ACE_SIGRTMIN);
00422 
00423 #if (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE))
00424   /**
00425   * Same as above but with gather support, through chaining of composite
00426   * message blocks using the continuation field.
00427   */
00428   int writev (ACE_Message_Block &message_block,
00429               size_t bytes_to_write,
00430               const void *act = 0,
00431               int priority = 0,
00432               int signal_number = ACE_SIGRTMIN);
00433 #endif /* (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)) */
00434 
00435   /// Return the underlying implementation class.
00436   ACE_Asynch_Write_Stream_Impl *implementation (void) const;
00437 
00438 protected:
00439   /// Set the implementation class.
00440   void implementation (ACE_Asynch_Write_Stream_Impl *implementation);
00441 
00442   /// Implementation class that all methods will be forwarded to.
00443   ACE_Asynch_Write_Stream_Impl *implementation_;
00444 
00445 public:
00446 /**
00447  * @class Result
00448  *
00449  * @brief This is that class which will be passed back to the
00450  * <handler> when the asynchronous write completes. This class
00451  * forwards all the methods to the implementation class.
00452  *
00453  * This class has all the information necessary for the
00454  * <handler> to uniquiely identify the completion of the
00455  * asynchronous write.
00456  */
00457   class ACE_Export Result : public ACE_Asynch_Result
00458   {
00459 
00460     /// The concrete implementation result classes only construct this
00461     /// class.
00462     friend class ACE_POSIX_Asynch_Write_Stream_Result;
00463     friend class ACE_WIN32_Asynch_Write_Stream_Result;
00464 
00465   public:
00466     /// The number of bytes which were requested at the start of the
00467     /// asynchronous write.
00468     size_t bytes_to_write (void) const;
00469 
00470     /// Message block that contains the data to be written.
00471     ACE_Message_Block &message_block (void) const;
00472 
00473     /// I/O handle used for writing.
00474     ACE_HANDLE handle (void) const;
00475 
00476     /// Get the implementation class.
00477     ACE_Asynch_Write_Stream_Result_Impl *implementation (void) const;
00478 
00479   protected:
00480     /// Constructor.
00481     Result (ACE_Asynch_Write_Stream_Result_Impl *implementation);
00482 
00483     /// Destructor.
00484     virtual ~Result (void);
00485 
00486     /// Implementation class.
00487     ACE_Asynch_Write_Stream_Result_Impl *implementation_;
00488   };
00489 };
00490 
00491 // Forward declarations
00492 class ACE_Asynch_Read_File_Impl;
00493 class ACE_Asynch_Read_File_Result_Impl;
00494 
00495 /**
00496  * @class ACE_Asynch_Read_File
00497  *
00498  * @brief This class is a factory for starting off asynchronous reads
00499  * on a file. This class forwards all methods to its
00500  * implementation class.
00501  *
00502  * Once <open> is called, multiple asynchronous <read>s can
00503  * started using this class. An ACE_Asynch_Read_File::Result
00504  * will be passed back to the <handler> when the asynchronous
00505  * reads completes through the <ACE_Handler::handle_read_file>
00506  * callback.
00507  * This class differs slightly from ACE_Asynch_Read_Stream as it
00508  * allows the user to specify an offset for the read.
00509  */
00510 class ACE_Export ACE_Asynch_Read_File : public ACE_Asynch_Read_Stream
00511 {
00512 
00513 public:
00514   /// A do nothing constructor.
00515   ACE_Asynch_Read_File (void);
00516 
00517   /// Destructor.
00518   virtual ~ACE_Asynch_Read_File (void);
00519 
00520   /**
00521    * Initializes the factory with information which will be used with
00522    * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE),
00523    * <ACE_Handler::handle> will be called on the <handler> to get the
00524    * correct handle.
00525    */
00526   int open (ACE_Handler &handler,
00527             ACE_HANDLE handle = ACE_INVALID_HANDLE,
00528             const void *completion_key = 0,
00529             ACE_Proactor *proactor = 0);
00530 
00531   /**
00532    * This starts off an asynchronous read.  Upto <bytes_to_read> will
00533    * be read and stored in the <message_block>.  The read will start
00534    * at <offset> from the beginning of the file. Priority of the
00535    * operation is specified by <priority>. On POSIX4-Unix, this is
00536    * supported. Works like <nice> in Unix. Negative values are not
00537    * allowed. 0 means priority of the operation same as the process
00538    * priority. 1 means priority of the operation is one less than
00539    * process. And so forth. On Win32, this argument is a no-op.
00540    * <signal_number> is the POSIX4 real-time signal number to be used
00541    * for the operation. <signal_number> ranges from ACE_SIGRTMIN to
00542    * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems.
00543    */
00544   int read (ACE_Message_Block &message_block,
00545             size_t bytes_to_read,
00546             u_long offset = 0,
00547             u_long offset_high = 0,
00548             const void *act = 0,
00549             int priority = 0,
00550             int signal_number = ACE_SIGRTMIN);
00551 
00552 #if (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE))
00553   /**
00554   * Same as above but with scatter support, through chaining of composite
00555   * message blocks using the continuation field.
00556   * NOTE: In win32 Each data block payload must be at least the size of a system
00557   * memory page and must be aligned on a system memory page size boundary
00558   */
00559   int readv (ACE_Message_Block &message_block,
00560              size_t bytes_to_read,
00561              u_long offset = 0,
00562              u_long offset_high = 0,
00563              const void *act = 0,
00564              int priority = 0,
00565              int signal_number = ACE_SIGRTMIN);
00566 #endif /* (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)) */
00567 
00568   /// Return the underlying implementation class.
00569   ACE_Asynch_Read_File_Impl *implementation (void) const;
00570 
00571 protected:
00572   /// Set the implementation class.
00573   void implementation (ACE_Asynch_Read_File_Impl *implementation);
00574 
00575   /// Delegation/implementation class that all methods will be
00576   /// forwarded to.
00577   ACE_Asynch_Read_File_Impl *implementation_;
00578 
00579 public:
00580 /**
00581  * @class Result
00582  *
00583  * @brief This is that class which will be passed back to the
00584  * <handler> when the asynchronous read completes. This class
00585  * forwards all the methods to the implementation class.
00586  *
00587  * This class has all the information necessary for the
00588  * <handler> to uniquiely identify the completion of the
00589  * asynchronous read.
00590  * This class differs slightly from
00591  * ACE_Asynch_Read_Stream::Result as it calls back
00592  * <ACE_Handler::handle_read_file> on the <handler> instead of
00593  * <ACE_Handler::handle_read_stream>.  No additional state is
00594  * required by this class as ACE_Asynch_Result can store the
00595  * <offset>.
00596  */
00597   class ACE_Export Result : public ACE_Asynch_Read_Stream::Result
00598   {
00599 
00600     /// The concrete implementation result classes only construct this
00601     /// class.
00602     friend class ACE_POSIX_Asynch_Read_File_Result;
00603     friend class ACE_WIN32_Asynch_Read_File_Result;
00604 
00605   public:
00606     /// Get the implementation class.
00607     ACE_Asynch_Read_File_Result_Impl *implementation (void) const;
00608 
00609   protected:
00610     /// Constructor. This implementation will not be deleted.
00611     Result (ACE_Asynch_Read_File_Result_Impl *implementation);
00612 
00613     /// Destructor.
00614     virtual ~Result (void);
00615 
00616     /// The implementation class.
00617     ACE_Asynch_Read_File_Result_Impl *implementation_;
00618 
00619   private:
00620     /// Here just to provide an dummpy implementation, since the
00621     /// one auto generated by MSVC is flagged as infinitely recursive
00622     void operator= (Result &) {}
00623   };
00624 };
00625 
00626 // Forward declarations
00627 class ACE_Asynch_Write_File_Impl;
00628 class ACE_Asynch_Write_File_Result_Impl;
00629 
00630 /**
00631  * @class ACE_Asynch_Write_File
00632  *
00633  * @brief This class is a factory for starting off asynchronous writes
00634  * on a file. This class forwards all methods to its
00635  * implementation class.
00636  *
00637  * Once <open> is called, multiple asynchronous <write>s can be
00638  * started using this class.  A ACE_Asynch_Write_File::Result
00639  * will be passed back to the <handler> when the asynchronous
00640  * writes completes through the <ACE_Handler::handle_write_file>
00641  * callback.
00642  * This class differs slightly from ACE_Asynch_Write_Stream as
00643  * it allows the user to specify an offset for the write.
00644  */
00645 class ACE_Export ACE_Asynch_Write_File : public ACE_Asynch_Write_Stream
00646 {
00647 
00648 public:
00649   /// A do nothing constructor.
00650   ACE_Asynch_Write_File (void);
00651 
00652   /// Destructor.
00653   virtual ~ACE_Asynch_Write_File (void);
00654 
00655   /**
00656    * Initializes the factory with information which will be used with
00657    * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE),
00658    * <ACE_Handler::handle> will be called on the <handler> to get the
00659    * correct handle.
00660    */
00661   int open (ACE_Handler &handler,
00662             ACE_HANDLE handle = ACE_INVALID_HANDLE,
00663             const void *completion_key = 0,
00664             ACE_Proactor *proactor = 0);
00665 
00666   /**
00667    * This starts off an asynchronous write.  Upto <bytes_to_write>
00668    * will be written from the <message_block>, starting at the
00669    * block's <rd_ptr>.  The write will go to the file, starting
00670    * <offset> bytes from the beginning of the file. Priority of the
00671    * operation is specified by <priority>. On POSIX4-Unix, this is
00672    * supported. Works like <nice> in Unix. Negative values are not
00673    * allowed. 0 means priority of the operation same as the process
00674    * priority. 1 means priority of the operation is one less than
00675    * process. And so forth. On Win32, this is a no-op.
00676    * <signal_number> is the POSIX4 real-time signal number to be used
00677    * for the operation. <signal_number> ranges from ACE_SIGRTMIN to
00678    * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems.
00679    */
00680   int write (ACE_Message_Block &message_block,
00681              size_t bytes_to_write,
00682              u_long offset = 0,
00683              u_long offset_high = 0,
00684              const void *act = 0,
00685              int priority = 0,
00686              int signal_number = ACE_SIGRTMIN);
00687 
00688 #if (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE))
00689   /**
00690   * Same as above but with gather support, through chaining of composite
00691   * message blocks using the continuation field.
00692   * NOTE: In win32 Each data block payload must be at least the size of a system
00693   * memory page and must be aligned on a system memory page size boundary
00694   */
00695   int writev (ACE_Message_Block &message_block,
00696               size_t bytes_to_write,
00697               u_long offset = 0,
00698               u_long offset_high = 0,
00699               const void *act = 0,
00700               int priority = 0,
00701               int signal_number = ACE_SIGRTMIN);
00702 #endif /* (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)) */
00703 
00704   /// Return the underlying implementation class.
00705   ACE_Asynch_Write_File_Impl *implementation (void) const;
00706 
00707 protected:
00708   /// Set the implementation.
00709   void implementation (ACE_Asynch_Write_File_Impl *implementation);
00710 
00711   /// Implementation object.
00712   ACE_Asynch_Write_File_Impl *implementation_;
00713 
00714 public:
00715 /**
00716  * @class Result
00717  *
00718  * @brief This is that class which will be passed back to the
00719  * <handler> when the asynchronous write completes. This class
00720  * forwards all the methods to the implementation class.
00721  *
00722  * This class has all the information necessary for the
00723  * <handler> to uniquiely identify the completion of the
00724  * asynchronous write.
00725  * This class differs slightly from
00726  * ACE_Asynch_Write_Stream::Result as it calls back
00727  * <ACE_Handler::handle_write_file> on the <handler> instead
00728  * of <ACE_Handler::handle_write_stream>.  No additional state
00729  * is required by this class as ACE_Asynch_Result can store
00730  * the <offset>.
00731  */
00732   class ACE_Export Result : public ACE_Asynch_Write_Stream::Result
00733   {
00734 
00735     /// The concrete implementation result classes only construct this
00736     /// class.
00737     friend class ACE_POSIX_Asynch_Write_File_Result;
00738     friend class ACE_WIN32_Asynch_Write_File_Result;
00739 
00740   public:
00741     ///  Get the implementation class.
00742     ACE_Asynch_Write_File_Result_Impl *implementation (void) const;
00743 
00744   protected:
00745     /// Constructor. This implementation will not be deleted.
00746     Result (ACE_Asynch_Write_File_Result_Impl *implementation);
00747 
00748     /// Destructor.
00749     virtual ~Result (void);
00750 
00751     /// The implementation class.
00752     ACE_Asynch_Write_File_Result_Impl *implementation_;
00753 
00754   private:
00755     /// Here just to provide an dummpy implementation, since the
00756     /// one auto generated by MSVC is flagged as infinitely recursive
00757     void operator= (Result &) {};
00758   };
00759 };
00760 
00761 // Forward declarations
00762 class ACE_Asynch_Accept_Result_Impl;
00763 class ACE_Asynch_Accept_Impl;
00764 
00765 /**
00766  * @class ACE_Asynch_Accept
00767  *
00768  * @brief This class is a factory for starting off asynchronous accepts
00769  * on a listen handle. This class forwards all methods to its
00770  * implementation class.
00771  *
00772  * Once <open> is called, multiple asynchronous <accept>s can
00773  * started using this class.  A ACE_Asynch_Accept::Result will
00774  * be passed back to the <handler> when the asynchronous accept
00775  * completes through the <ACE_Handler::handle_accept>
00776  * callback.
00777  */
00778 class ACE_Export ACE_Asynch_Accept : public ACE_Asynch_Operation
00779 {
00780 
00781 public:
00782   /// A do nothing constructor.
00783   ACE_Asynch_Accept (void);
00784 
00785   /// Destructor.
00786   virtual ~ACE_Asynch_Accept (void);
00787 
00788   /**
00789    * Initializes the factory with information which will be used with
00790    * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE),
00791    * <ACE_Handler::handle> will be called on the <handler> to get the
00792    * correct handle.
00793    */
00794   int open (ACE_Handler &handler,
00795             ACE_HANDLE handle = ACE_INVALID_HANDLE,
00796             const void *completion_key = 0,
00797             ACE_Proactor *proactor = 0);
00798 
00799   /**
00800    * This starts off an asynchronous accept.  The asynchronous accept
00801    * call also allows any initial data to be returned to the
00802    * <handler>.  Upto <bytes_to_read> will be read and stored in the
00803    * <message_block>.  The <accept_handle> will be used for the
00804    * <accept> call.  If (<accept_handle> == INVALID_HANDLE), a new
00805    * handle will be created. Priority of the
00806    * operation is specified by <priority>. On POSIX4-Unix, this is
00807    * supported. Works like <nice> in Unix. Negative values are not
00808    * allowed. 0 means priority of the operation same as the process
00809    * priority. 1 means priority of the operation is one less than
00810    * process. And so forth. On Win32, this is a no-op.
00811    *
00812    * <message_block> must be specified. This is because the address of
00813    * the new connection is placed at the end of this buffer.
00814    * <signal_number> is the POSIX4 real-time signal number to be used
00815    * for the operation. <signal_number> ranges from ACE_SIGRTMIN to
00816    * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems.
00817    */
00818   int accept (ACE_Message_Block &message_block,
00819               size_t bytes_to_read,
00820               ACE_HANDLE accept_handle = ACE_INVALID_HANDLE,
00821               const void *act = 0,
00822               int priority = 0,
00823               int signal_number = ACE_SIGRTMIN);
00824 
00825   /// Return the underlying implementation class.
00826   ACE_Asynch_Accept_Impl *implementation (void) const;
00827 
00828 protected:
00829   /// Set the implementation class.
00830   void implementation (ACE_Asynch_Accept_Impl *implementation);
00831 
00832   /// Delegation/implementation class that all methods will be
00833   /// forwarded to.
00834   ACE_Asynch_Accept_Impl *implementation_;
00835 
00836 public:
00837 /**
00838  * @class Result
00839  *
00840  * @brief This is that class which will be passed back to the
00841  * <handler> when the asynchronous accept completes.
00842  *
00843  * This class has all the information necessary for the
00844  * <handler> to uniquiely identify the completion of the
00845  * asynchronous accept.
00846  */
00847   class ACE_Export Result : public ACE_Asynch_Result
00848   {
00849 
00850     /// The concrete implementation result classes only construct this
00851     /// class.
00852     friend class ACE_POSIX_Asynch_Accept_Result;
00853     friend class ACE_WIN32_Asynch_Accept_Result;
00854 
00855   public:
00856     /// The number of bytes which were requested at the start of the
00857     /// asynchronous accept.
00858     size_t bytes_to_read (void) const;
00859 
00860     /// Message block which contains the read data.
00861     ACE_Message_Block &message_block (void) const;
00862 
00863     /// I/O handle used for accepting new connections.
00864     ACE_HANDLE listen_handle (void) const;
00865 
00866     /// I/O handle for the new connection.
00867     ACE_HANDLE accept_handle (void) const;
00868 
00869     /// Get the implementation.
00870     ACE_Asynch_Accept_Result_Impl *implementation (void) const;
00871 
00872   protected:
00873     /// Contructor. Implementation will not be deleted.
00874     Result (ACE_Asynch_Accept_Result_Impl *implementation);
00875 
00876     /// Destructor.
00877     virtual ~Result (void);
00878 
00879     /// Impelmentation class.
00880     ACE_Asynch_Accept_Result_Impl *implementation_;
00881   };
00882 };
00883 // Forward declarations
00884 class ACE_Asynch_Connect_Result_Impl;
00885 class ACE_Asynch_Connect_Impl;
00886 
00887 /**
00888  * @class ACE_Asynch_Connect
00889  *
00890  * @brief This class is a factory for starting off asynchronous connects
00891  * This class forwards all methods to its implementation class.
00892  *
00893  * Once @c open is called, multiple asynchronous connect operationss can
00894  * started using this class.  A ACE_Asynch_Connect::Result will
00895  * be passed back to the associated ACE_Handler when the asynchronous connect
00896  * completes through the ACE_Handler::handle_connect() callback.
00897  */
00898 class ACE_Export ACE_Asynch_Connect : public ACE_Asynch_Operation
00899 {
00900 
00901 public:
00902   /// A do nothing constructor.
00903   ACE_Asynch_Connect (void);
00904 
00905   /// Destructor.
00906   virtual ~ACE_Asynch_Connect (void);
00907 
00908   /**
00909    * Initializes the factory with information which will be used with
00910    * each asynchronous call.
00911    *
00912    * @note @arg handle is ignored and should be @c ACE_INVALID_HANDLE.
00913    */
00914   int open (ACE_Handler &handler,
00915             ACE_HANDLE handle = ACE_INVALID_HANDLE,
00916             const void *completion_key = 0,
00917             ACE_Proactor *proactor = 0);
00918 
00919   /**
00920    * This starts off an asynchronous Connect.
00921    */
00922   int connect (ACE_HANDLE connect_handle,
00923                const ACE_Addr & remote_sap,
00924                const ACE_Addr & local_sap,
00925                int  reuse_addr,
00926                const void *act=0,
00927                int priority = 0,
00928                int signal_number = ACE_SIGRTMIN);
00929 
00930   /// Return the underlying implementation class.
00931   ACE_Asynch_Connect_Impl *implementation (void) const;
00932 
00933 protected:
00934   /// Set the implementation class.
00935   void implementation (ACE_Asynch_Connect_Impl *implementation);
00936 
00937   /// Delegation/implementation class that all methods will be
00938   /// forwarded to.
00939   ACE_Asynch_Connect_Impl *implementation_;
00940 
00941 public:
00942 /**
00943  * @class Result
00944  *
00945  * @brief This is that class which will be passed back to the
00946  * handler when the asynchronous connect completes.
00947  *
00948  * This class has all the information necessary for the
00949  * handler to uniquely identify the completion of the
00950  * asynchronous connect.
00951  */
00952   class ACE_Export Result : public ACE_Asynch_Result
00953   {
00954 
00955     /// The concrete implementation result classes only construct this
00956     /// class.
00957     friend class ACE_POSIX_Asynch_Connect_Result;
00958     friend class ACE_WIN32_Asynch_Connect_Result;
00959 
00960   public:
00961 
00962     /// I/O handle for the  connection.
00963     ACE_HANDLE connect_handle (void) const;
00964 
00965     /// Get the implementation.
00966     ACE_Asynch_Connect_Result_Impl *implementation (void) const;
00967 
00968   protected:
00969     /// Contructor. Implementation will not be deleted.
00970     Result (ACE_Asynch_Connect_Result_Impl *implementation);
00971 
00972     /// Destructor.
00973     virtual ~Result (void);
00974 
00975     /// Impelmentation class.
00976     ACE_Asynch_Connect_Result_Impl *implementation_;
00977   };
00978 };
00979 
00980 // Forward declarations
00981 class ACE_Asynch_Transmit_File_Result_Impl;
00982 class ACE_Asynch_Transmit_File_Impl;
00983 
00984 /**
00985  * @class ACE_Asynch_Transmit_File
00986  *
00987  * @brief This class is a factory for starting off asynchronous
00988  * transmit files on a stream.
00989  *
00990  * Once <open> is called, multiple asynchronous <transmit_file>s
00991  * can started using this class.  A
00992  * ACE_Asynch_Transmit_File::Result will be passed back to the
00993  * <handler> when the asynchronous transmit file completes
00994  * through the <ACE_Handler::handle_transmit_file> callback.
00995  * The transmit_file function transmits file data over a
00996  * connected network connection. The function uses the operating
00997  * system's cache manager to retrieve the file data. This
00998  * function provides high-performance file data transfer over
00999  * network connections.  This function would be of great use in
01000  * a Web Server, Image Server, etc.
01001  */
01002 class ACE_Export ACE_Asynch_Transmit_File : public ACE_Asynch_Operation
01003 {
01004 
01005 public:
01006   // Forward declarations
01007   class Header_And_Trailer;
01008 
01009   /// A do nothing constructor.
01010   ACE_Asynch_Transmit_File (void);
01011 
01012   /// Destructor.
01013   virtual ~ACE_Asynch_Transmit_File (void);
01014 
01015   /**
01016    * Initializes the factory with information which will be used with
01017    * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE),
01018    * <ACE_Handler::handle> will be called on the <handler> to get the
01019    * correct handle.
01020    */
01021   int open (ACE_Handler &handler,
01022             ACE_HANDLE handle = ACE_INVALID_HANDLE,
01023             const void *completion_key = 0,
01024             ACE_Proactor *proactor = 0);
01025 
01026   /**
01027    * This starts off an asynchronous transmit file.  The <file> is a
01028    * handle to an open file.  <header_and_trailer> is a pointer to a
01029    * data structure that contains pointers to data to send before and
01030    * after the file data is sent.  Set this parameter to 0 if you only
01031    * want to transmit the file data.  Upto <bytes_to_write> will be
01032    * written to the <socket>.  If you want to send the entire file,
01033    * let <bytes_to_write> = 0.  <bytes_per_send> is the size of each
01034    * block of data sent per send operation.  Please read the Win32
01035    * documentation on what the flags should be. Priority of the
01036    * operation is specified by <priority>. On POSIX4-Unix, this is
01037    * supported. Works like <nice> in Unix. Negative values are not
01038    * allowed. 0 means priority of the operation same as the process
01039    * priority. 1 means priority of the operation is one less than
01040    * process. And so forth. On Win32, this is a no-op.
01041    * <signal_number> is the POSIX4 real-time signal number to be used
01042    * for the operation. <signal_number> ranges from ACE_SIGRTMIN to
01043    * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems.
01044    */
01045   int transmit_file (ACE_HANDLE file,
01046                      Header_And_Trailer *header_and_trailer = 0,
01047                      size_t bytes_to_write = 0,
01048                      u_long offset = 0,
01049                      u_long offset_high = 0,
01050                      size_t bytes_per_send = 0,
01051                      u_long flags = 0,
01052                      const void *act = 0,
01053                      int priority = 0,
01054                      int signal_number = ACE_SIGRTMIN);
01055 
01056   /// Return the underlying implementation class.
01057   ACE_Asynch_Transmit_File_Impl *implementation (void) const;
01058 
01059 protected:
01060   /// Set the implementation.
01061   void implementation (ACE_Asynch_Transmit_File_Impl *);
01062 
01063   /// The implementation class.
01064   ACE_Asynch_Transmit_File_Impl *implementation_;
01065 
01066 public:
01067 /**
01068  * @class Result
01069  *
01070  * @brief This is that class which will be passed back to the
01071  * <handler> when the asynchronous transmit file completes.
01072  *
01073  * This class has all the information necessary for the
01074  * <handler> to uniquiely identify the completion of the
01075  * asynchronous transmit file.
01076  */
01077   class ACE_Export Result : public ACE_Asynch_Result
01078   {
01079 
01080     /// The concrete implementation result classes only construct this
01081     /// class.
01082     friend class ACE_POSIX_Asynch_Transmit_File_Result;
01083     friend class ACE_WIN32_Asynch_Transmit_File_Result;
01084 
01085   public:
01086     /// Socket used for transmitting the file.
01087     ACE_HANDLE socket (void) const;
01088 
01089     /// File from which the data is read.
01090     ACE_HANDLE file (void) const;
01091 
01092     /// Header and trailer data associated with this transmit file.
01093     Header_And_Trailer *header_and_trailer (void) const;
01094 
01095     /// The number of bytes which were requested at the start of the
01096     /// asynchronous transmit file.
01097     size_t bytes_to_write (void) const;
01098 
01099     /// Number of bytes per send requested at the start of the transmit
01100     /// file.
01101     size_t bytes_per_send (void) const;
01102 
01103     /// Flags which were passed into transmit file.
01104     u_long flags (void) const;
01105 
01106     /// Get the implementation class.
01107     ACE_Asynch_Transmit_File_Result_Impl *implementation (void) const;
01108 
01109   protected:
01110     /// Constructor.
01111     Result (ACE_Asynch_Transmit_File_Result_Impl *implementation);
01112 
01113     /// Destructor.
01114     virtual ~Result (void);
01115 
01116     /// The implementation class.
01117     ACE_Asynch_Transmit_File_Result_Impl *implementation_;
01118   };
01119 
01120 /**
01121  * @class Header_And_Trailer
01122  *
01123  * @brief The class defines a data structure that contains pointers
01124  * to data to send before and after the file data is sent.
01125  *
01126  * This class provides a wrapper over TRANSMIT_FILE_BUFFERS
01127  * and provided a consistent use of ACE_Message_Blocks.
01128  */
01129   class ACE_Export Header_And_Trailer
01130   {
01131 
01132   public:
01133     /// Constructor.
01134     Header_And_Trailer (ACE_Message_Block *header = 0,
01135                         size_t header_bytes = 0,
01136                         ACE_Message_Block *trailer = 0,
01137                         size_t trailer_bytes = 0);
01138 
01139     /// Destructor
01140     virtual ~Header_And_Trailer (void);
01141 
01142     /// This method allows all the member to be set in one fell swoop.
01143     void header_and_trailer (ACE_Message_Block *header = 0,
01144                              size_t header_bytes = 0,
01145                              ACE_Message_Block *trailer = 0,
01146                              size_t trailer_bytes = 0);
01147 
01148     /// Get header which goes before the file data.
01149     ACE_Message_Block *header (void) const;
01150 
01151     /// Set header which goes before the file data.
01152     void header (ACE_Message_Block *message_block);
01153 
01154     /// Get size of the header data.
01155     size_t header_bytes (void) const;
01156 
01157     /// Set size of the header data.
01158     void header_bytes (size_t bytes);
01159 
01160     /// Get trailer which goes after the file data.
01161     ACE_Message_Block *trailer (void) const;
01162 
01163     /// Set trailer which goes after the file data.
01164     void trailer (ACE_Message_Block *message_block);
01165 
01166     /// Get size of the trailer data.
01167     size_t trailer_bytes (void) const;
01168 
01169     /// Set size of the trailer data.
01170     void trailer_bytes (size_t bytes);
01171 
01172     /// Conversion routine.
01173     ACE_LPTRANSMIT_FILE_BUFFERS transmit_buffers (void);
01174 
01175   protected:
01176     /// Header data.
01177     ACE_Message_Block *header_;
01178 
01179     /// Size of header data.
01180     size_t header_bytes_;
01181 
01182     /// Trailer data.
01183     ACE_Message_Block *trailer_;
01184 
01185     /// Size of trailer data.
01186     size_t trailer_bytes_;
01187 
01188     /// Target data structure.
01189     ACE_TRANSMIT_FILE_BUFFERS transmit_buffers_;
01190   };
01191 };
01192 
01193 
01194 // Forward declarations
01195 class ACE_Asynch_Read_Dgram_Result_Impl;
01196 class ACE_Asynch_Read_Dgram_Impl;
01197 class ACE_Addr;
01198 
01199 /**
01200  * @class ACE_Asynch_Read_Dgram
01201  *
01202  * @brief This class is a factory for starting off asynchronous reads
01203  * on a UDP socket. This class forwards all methods to its
01204  * implementation class.
01205  *
01206  * Once <open> is called, multiple asynchronous <read>s can be
01207  * started using this class.  An ACE_Asynch_Read_Dgram::Result
01208  * will be passed back to the <handler> when the asynchronous
01209  * reads completes through the <ACE_Handler::handle_read_dgram>
01210  * callback.
01211  */
01212 class ACE_Export ACE_Asynch_Read_Dgram : public ACE_Asynch_Operation
01213 {
01214 
01215 public:
01216   /// A do nothing constructor.
01217   ACE_Asynch_Read_Dgram (void);
01218 
01219   /// Destructor
01220   virtual ~ACE_Asynch_Read_Dgram (void);
01221 
01222   /**
01223    * Initializes the factory with information which will be used with
01224    * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE),
01225    * <ACE_Handler::handle> will be called on the <handler> to get the
01226    * correct handle.
01227    */
01228   int open (ACE_Handler &handler,
01229             ACE_HANDLE handle = ACE_INVALID_HANDLE,
01230             const void *completion_key = 0,
01231             ACE_Proactor *proactor = 0);
01232 
01233   /** This starts off an asynchronous read.  Upto
01234    * <message_block->total_size()> will be read and stored in the
01235    * <message_block>.  <message_block>'s <wr_ptr> will be updated to reflect
01236    * the added bytes if the read operation is successfully completed.
01237    * Return code of 1 means immediate success and <number_of_bytes_recvd>
01238    * will contain number of bytes read.  The <ACE_Handler::handle_read_dgram>
01239    * method will still be called.  Return code of 0 means the IO will
01240    * complete proactively.  Return code of -1 means there was an error, use
01241    * errno to get the error code.
01242    *
01243    * Scatter/gather is supported on WIN32 by using the <message_block->cont()>
01244    * method.  Up to ACE_IOV_MAX <message_block>'s are supported.  Upto
01245    * <message_block->size()> bytes will be read into each <message block> for
01246    * a total of <message_block->total_size()> bytes.  All <message_block>'s
01247    * <wr_ptr>'s will be updated to reflect the added bytes for each
01248    * <message_block>
01249    *
01250    * Priority of the operation is specified by <priority>. On POSIX4-Unix,
01251    * this is supported. Works like <nice> in Unix. Negative values are not
01252    * allowed. 0 means priority of the operation same as the process
01253    * priority. 1 means priority of the operation is one less than
01254    * process. And so forth. On Win32, <priority> is a no-op.
01255    * <signal_number> is the POSIX4 real-time signal number to be used
01256    * for the operation. <signal_number> ranges from ACE_SIGRTMIN to
01257    * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems.
01258    */
01259   ssize_t recv (ACE_Message_Block *message_block,
01260                 size_t &number_of_bytes_recvd,
01261                 int flags,
01262                 int protocol_family = PF_INET,
01263                 const void *act = 0,
01264                 int priority = 0,
01265                 int signal_number = ACE_SIGRTMIN);
01266 
01267   /// Return the underlying implementation class.
01268   ACE_Asynch_Read_Dgram_Impl *implementation (void) const;
01269 
01270 protected:
01271   /// Set the implementation class.
01272   void implementation (ACE_Asynch_Read_Dgram_Impl *implementation);
01273 
01274   /// Implementation class that all methods will be forwarded to.
01275   ACE_Asynch_Read_Dgram_Impl *implementation_;
01276 
01277 public:
01278 /**
01279  * @class Result
01280  *
01281  * @brief This is the class which will be passed back to the
01282  * <handler> when the asynchronous read completes. This class
01283  * forwards all the methods to the implementation classes.
01284  *
01285  * This class has all the information necessary for the
01286  * <handler> to uniquiely identify the completion of the
01287  * asynchronous read.
01288  */
01289   class ACE_Export Result : public ACE_Asynch_Result
01290   {
01291 
01292     /// The concrete implementation result classes only construct this
01293     /// class.
01294     friend class ACE_POSIX_Asynch_Read_Dgram_Result;
01295     friend class ACE_WIN32_Asynch_Read_Dgram_Result;
01296 
01297   public:
01298 
01299     /// The number of bytes which were requested at the start of the
01300     /// asynchronous read.
01301     size_t bytes_to_read (void) const;
01302 
01303     /// Message block which contains the read data
01304     ACE_Message_Block *message_block (void) const;
01305 
01306     /// The flags used in the read
01307     int flags (void) const;
01308 
01309     /// The address of where the packet came from
01310     int remote_address (ACE_Addr& addr) const;
01311 
01312     /// I/O handle used for reading.
01313     ACE_HANDLE handle (void) const;
01314 
01315     /// Get the implementation class.
01316     ACE_Asynch_Read_Dgram_Result_Impl *implementation (void) const;
01317 
01318   protected:
01319     /// Constructor.
01320     Result (ACE_Asynch_Read_Dgram_Result_Impl *implementation);
01321 
01322     /// Destructor.
01323     virtual ~Result (void);
01324 
01325     /// The implementation class.
01326     ACE_Asynch_Read_Dgram_Result_Impl *implementation_;
01327   };
01328 };
01329 
01330 // Forward declarations
01331 class ACE_Asynch_Write_Dgram_Impl;
01332 class ACE_Asynch_Write_Dgram_Result_Impl;
01333 
01334 /**
01335  * @class ACE_Asynch_Write_Dgram
01336  *
01337  * @brief This class is a factory for starting off asynchronous writes
01338  * on a UDP socket. This class forwards all methods to its
01339  * implementation class.
01340  *
01341  * Once <open> is called, multiple asynchronous <writes>s can
01342  * started using this class.  An ACE_Asynch_Write_Dgram::Result
01343  * will be passed back to the <handler> when the asynchronous
01344  * write completes through the
01345  * <ACE_Handler::handle_write_dgram> callback.
01346  */
01347 class ACE_Export ACE_Asynch_Write_Dgram : public ACE_Asynch_Operation
01348 {
01349 
01350 public:
01351   /// A do nothing constructor.
01352   ACE_Asynch_Write_Dgram (void);
01353 
01354   /// Destructor.
01355   virtual ~ACE_Asynch_Write_Dgram (void);
01356 
01357   /**
01358    * Initializes the factory with information which will be used with
01359    * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE),
01360    * <ACE_Handler::handle> will be called on the <handler> to get the
01361    * correct handle.
01362    */
01363   int open (ACE_Handler &handler,
01364             ACE_HANDLE handle = ACE_INVALID_HANDLE,
01365             const void *completion_key = 0,
01366             ACE_Proactor *proactor = 0);
01367 
01368   /** This starts off an asynchronous send.  Upto
01369    * <message_block->total_length()> will be sent.  <message_block>'s
01370    * <rd_ptr> will be updated to reflect the sent bytes if the send operation
01371    * is successfully completed.
01372    * Return code of 1 means immediate success and <number_of_bytes_sent>
01373    * is updated to number of bytes sent.  The <ACE_Handler::handle_write_dgram>
01374    * method will still be called.  Return code of 0 means the IO will
01375    * complete proactively.  Return code of -1 means there was an error, use
01376    * errno to get the error code.
01377    *
01378    * Scatter/gather is supported on WIN32 by using the <message_block->cont()>
01379    * method.  Up to ACE_IOV_MAX <message_block>'s are supported.  Upto
01380    * <message_block->length()> bytes will be sent from each <message block>
01381    * for a total of <message_block->total_length()> bytes.  All
01382    * <message_block>'s <rd_ptr>'s will be updated to reflect the bytes sent
01383    * from each <message_block>.
01384    *
01385    * Priority of the operation is specified by <priority>. On POSIX4-Unix,
01386    * this is supported. Works like <nice> in Unix. Negative values are not
01387    * allowed. 0 means priority of the operation same as the process
01388    * priority. 1 means priority of the operation is one less than
01389    * process. And so forth. On Win32, this argument is a no-op.
01390    * <signal_number> is the POSIX4 real-time signal number to be used
01391    * for the operation. <signal_number> ranges from ACE_SIGRTMIN to
01392    * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems.
01393    */
01394   ssize_t send (ACE_Message_Block *message_block,
01395                 size_t &number_of_bytes_sent,
01396                 int flags,
01397                 const ACE_Addr& remote_addr,
01398                 const void *act = 0,
01399                 int priority = 0,
01400                 int signal_number = ACE_SIGRTMIN);
01401 
01402   /// Return the underlying implementation class.
01403   ACE_Asynch_Write_Dgram_Impl *implementation (void) const;
01404 
01405 protected:
01406   /// Set the implementation class.
01407   void implementation (ACE_Asynch_Write_Dgram_Impl *implementation);
01408 
01409   /// Implementation class that all methods will be forwarded to.
01410   ACE_Asynch_Write_Dgram_Impl *implementation_;
01411 
01412 public:
01413 /**
01414  * @class Result
01415  *
01416  * @brief This is that class which will be passed back to the
01417  * <handler> when the asynchronous write completes. This class
01418  * forwards all the methods to the implementation class.
01419  *
01420  * This class has all the information necessary for the
01421  * <handler> to uniquiely identify the completion of the
01422  * asynchronous write.
01423  */
01424   class ACE_Export Result : public ACE_Asynch_Result
01425   {
01426 
01427     /// The concrete implementation result classes only construct this
01428     /// class.
01429     friend class ACE_POSIX_Asynch_Write_Dgram_Result;
01430     friend class ACE_WIN32_Asynch_Write_Dgram_Result;
01431 
01432   public:
01433 
01434     /// The number of bytes which were requested at the start of the
01435     /// asynchronous write.
01436     size_t bytes_to_write (void) const;
01437 
01438     /// Message block which contains the sent data
01439     ACE_Message_Block *message_block (void) const;
01440 
01441     /// The flags using in the write
01442     int flags (void) const;
01443 
01444     /// I/O handle used for writing.
01445     ACE_HANDLE handle (void) const;
01446 
01447     /// Get the implementation class.
01448     ACE_Asynch_Write_Dgram_Result_Impl *implementation (void) const;
01449 
01450   protected:
01451     /// Constructor.
01452     Result (ACE_Asynch_Write_Dgram_Result_Impl *implementation);
01453 
01454     /// Destructor.
01455     virtual ~Result (void);
01456 
01457     /// Implementation class.
01458     ACE_Asynch_Write_Dgram_Result_Impl *implementation_;
01459   };
01460 };
01461 
01462 
01463 /**
01464  * @class ACE_Handler
01465  *
01466  * @brief This base class defines the interface for receiving the
01467  * results of asynchronous operations.
01468  *
01469  * Subclasses of this class will fill in appropriate methods.
01470  */
01471 class ACE_Export ACE_Handler
01472 {
01473 public:
01474   /// A do nothing constructor.
01475   ACE_Handler (void);
01476 
01477   /// A do nothing constructor which allows proactor to be set to <p>.
01478   ACE_Handler (ACE_Proactor *p);
01479 
01480   /// Virtual destruction.
01481   virtual ~ACE_Handler (void);
01482 
01483   /// This method will be called when an asynchronous read completes on
01484   /// a stream.
01485   virtual void handle_read_stream (const ACE_Asynch_Read_Stream::Result &result);
01486 
01487   /// This method will be called when an asynchronous write completes
01488   /// on a UDP socket.
01489   virtual void handle_write_dgram (const ACE_Asynch_Write_Dgram::Result &result);
01490 
01491   /// This method will be called when an asynchronous read completes on
01492   /// a UDP socket.
01493   virtual void handle_read_dgram (const ACE_Asynch_Read_Dgram::Result &result);
01494 
01495   /// This method will be called when an asynchronous write completes
01496   /// on a stream.
01497   virtual void handle_write_stream (const ACE_Asynch_Write_Stream::Result &result);
01498 
01499   /// This method will be called when an asynchronous read completes on
01500   /// a file.
01501   virtual void handle_read_file (const ACE_Asynch_Read_File::Result &result);
01502 
01503   /// This method will be called when an asynchronous write completes
01504   /// on a file.
01505   virtual void handle_write_file (const ACE_Asynch_Write_File::Result &result);
01506 
01507   /// This method will be called when an asynchronous accept completes.
01508   virtual void handle_accept (const ACE_Asynch_Accept::Result &result);
01509 
01510   /// This method will be called when an asynchronous connect completes.
01511   virtual void handle_connect (const ACE_Asynch_Connect::Result &result);
01512 
01513   /// This method will be called when an asynchronous transmit file
01514   /// completes.
01515   virtual void handle_transmit_file (const ACE_Asynch_Transmit_File::Result &result);
01516 
01517   /// Called when timer expires.  <tv> was the requested time value and
01518   /// <act> is the ACT passed when scheduling the timer.
01519   virtual void handle_time_out (const ACE_Time_Value &tv,
01520                                 const void *act = 0);
01521 
01522   /**
01523    * This is method works with the <run_event_loop> of the
01524    * ACE_Proactor. A special <Wake_Up_Completion> is used to wake up
01525    * all the threads that are blocking for completions.
01526    */
01527   virtual void handle_wakeup (void);
01528 
01529   /// Get the proactor associated with this handler.
01530   ACE_Proactor *proactor (void);
01531 
01532   /// Set the proactor.
01533   void proactor (ACE_Proactor *p);
01534 
01535   /**
01536    * Get the I/O handle used by this <handler>. This method will be
01537    * called by the ACE_Asynch_* classes when an ACE_INVALID_HANDLE is
01538    * passed to <open>.
01539    */
01540   virtual ACE_HANDLE handle (void) const;
01541 
01542   /// Set the ACE_HANDLE value for this Handler.
01543   virtual void handle (ACE_HANDLE);
01544 
01545 protected:
01546   /// The proactor associated with this handler.
01547   ACE_Proactor *proactor_;
01548 
01549   /// The ACE_HANDLE in use with this handler.
01550   ACE_HANDLE    handle_;
01551 };
01552 
01553 // Forward declarations
01554 class ACE_INET_Addr;
01555 
01556 // Forward declarations
01557 template <class HANDLER>
01558 class ACE_Asynch_Acceptor;
01559 
01560 /**
01561  * @class ACE_Service_Handler
01562  *
01563  * @brief This base class defines the interface for the
01564  * ACE_Asynch_Acceptor to call into when new connection are
01565  * accepted.
01566  *
01567  * Subclasses of this class will fill in appropriate methods to
01568  * define application specific behavior.
01569  */
01570 class ACE_Export ACE_Service_Handler : public ACE_Handler
01571 {
01572 
01573   /// The Acceptor is the factory and therefore should have special
01574   /// privileges.
01575   friend class ACE_Asynch_Acceptor<ACE_Service_Handler>;
01576 
01577 public:
01578   /// A do nothing constructor.
01579   ACE_Service_Handler (void);
01580 
01581   /// Virtual destruction.
01582   virtual ~ACE_Service_Handler (void);
01583 
01584   /**
01585    * <open> is called by ACE_Asynch_Acceptor to initialize a new
01586    * instance of ACE_Service_Handler that has been created after the
01587    * new connection is accepted. The handle for the new connection is
01588    * passed along with the initial data that may have shown up.
01589    */
01590   virtual void open (ACE_HANDLE new_handle,
01591                      ACE_Message_Block &message_block);
01592 
01593   // protected:
01594   // This should be corrected after the correct semantics of the
01595   // friend has been figured out.
01596 
01597   /// Called by ACE_Asynch_Acceptor to pass the addresses of the new
01598   /// connections.
01599   virtual void addresses (const ACE_INET_Addr &remote_address,
01600                           const ACE_INET_Addr &local_address);
01601 
01602   /// Called by ACE_Asynch_Acceptor to pass the act.
01603   virtual void act (const void *);
01604 };
01605 
01606 #endif /* ACE_WIN32 || ACE_HAS_AIO_CALLS*/
01607 #include "ace/post.h"
01608 #endif /* ACE_ASYNCH_IO_H */

Generated on Mon Jun 16 11:19:07 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002