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