diff options
| author | coryan <coryan@ae88bc3d-4319-0410-8dbf-d08b4c9d3795> | 2000-11-01 22:17:39 +0000 |
|---|---|---|
| committer | coryan <coryan@ae88bc3d-4319-0410-8dbf-d08b4c9d3795> | 2000-11-01 22:17:39 +0000 |
| commit | 53284e215e3d3351a7d7e9c4b68f14b427fb4377 (patch) | |
| tree | 97236ece363cff48fd287c780db4290da39b02cb | |
| parent | 7b7c52ad2abd228138ba1a948d5e28bf6dc3b880 (diff) | |
| download | ATCD-53284e215e3d3351a7d7e9c4b68f14b427fb4377.tar.gz | |
ChangeLogTag:Wed Nov 1 14:11:48 2000 Carlos O'Ryan <coryan@uci.edu>
287 files changed, 29090 insertions, 25654 deletions
diff --git a/ChangeLog b/ChangeLog index 5a4aa90ffbf..16d0a20e553 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,9 +1,16 @@ +Wed Nov 1 14:11:48 2000 Carlos O'Ryan <coryan@uci.edu> + + * ace/*.h: + Change all the header files to generate better docs with + Doxygen. Thanks to Darrell for his wonderful script to automate + this process. + Tue Oct 31 19:01:19 2000 Douglas C. Schmidt <schmidt@ace.cs.wustl.edu> - * netsvcs/lib/Client_Logging_Handler.cpp (handle_input): Added - a comment explaining why we don't go to heroic lengths to recv() - all the data if it fails after the second recv(). Thanks to - Steve Sivier <Steven.Sivier@Eng.Sun.COM> for motivating this. + * netsvcs/lib/Client_Logging_Handler.cpp (handle_input): Added + a comment explaining why we don't go to heroic lengths to recv() + all the data if it fails after the second recv(). Thanks to + Steve Sivier <Steven.Sivier@Eng.Sun.COM> for motivating this. Tue Oct 31 14:21:11 2000 David L. Levine <levine@cs.wustl.edu> diff --git a/ChangeLogs/ChangeLog-02a b/ChangeLogs/ChangeLog-02a index 5a4aa90ffbf..16d0a20e553 100644 --- a/ChangeLogs/ChangeLog-02a +++ b/ChangeLogs/ChangeLog-02a @@ -1,9 +1,16 @@ +Wed Nov 1 14:11:48 2000 Carlos O'Ryan <coryan@uci.edu> + + * ace/*.h: + Change all the header files to generate better docs with + Doxygen. Thanks to Darrell for his wonderful script to automate + this process. + Tue Oct 31 19:01:19 2000 Douglas C. Schmidt <schmidt@ace.cs.wustl.edu> - * netsvcs/lib/Client_Logging_Handler.cpp (handle_input): Added - a comment explaining why we don't go to heroic lengths to recv() - all the data if it fails after the second recv(). Thanks to - Steve Sivier <Steven.Sivier@Eng.Sun.COM> for motivating this. + * netsvcs/lib/Client_Logging_Handler.cpp (handle_input): Added + a comment explaining why we don't go to heroic lengths to recv() + all the data if it fails after the second recv(). Thanks to + Steve Sivier <Steven.Sivier@Eng.Sun.COM> for motivating this. Tue Oct 31 14:21:11 2000 David L. Levine <levine@cs.wustl.edu> diff --git a/ChangeLogs/ChangeLog-03a b/ChangeLogs/ChangeLog-03a index 5a4aa90ffbf..16d0a20e553 100644 --- a/ChangeLogs/ChangeLog-03a +++ b/ChangeLogs/ChangeLog-03a @@ -1,9 +1,16 @@ +Wed Nov 1 14:11:48 2000 Carlos O'Ryan <coryan@uci.edu> + + * ace/*.h: + Change all the header files to generate better docs with + Doxygen. Thanks to Darrell for his wonderful script to automate + this process. + Tue Oct 31 19:01:19 2000 Douglas C. Schmidt <schmidt@ace.cs.wustl.edu> - * netsvcs/lib/Client_Logging_Handler.cpp (handle_input): Added - a comment explaining why we don't go to heroic lengths to recv() - all the data if it fails after the second recv(). Thanks to - Steve Sivier <Steven.Sivier@Eng.Sun.COM> for motivating this. + * netsvcs/lib/Client_Logging_Handler.cpp (handle_input): Added + a comment explaining why we don't go to heroic lengths to recv() + all the data if it fails after the second recv(). Thanks to + Steve Sivier <Steven.Sivier@Eng.Sun.COM> for motivating this. Tue Oct 31 14:21:11 2000 David L. Levine <levine@cs.wustl.edu> diff --git a/ace/ACE.h b/ace/ACE.h index 6e316049eb2..4e52189602b 100644 --- a/ace/ACE.h +++ b/ace/ACE.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ACE.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file ACE.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_ACE_H #define ACE_ACE_H @@ -34,97 +31,102 @@ class ACE_Time_Value; class ACE_Message_Block; +/** + * @class ACE + * + * @brief Contains value added ACE methods that extend the behavior + * of the UNIX and Win32 OS calls. + * + * This class consolidates all these ACE static methods in a + * single place in order to manage the namespace better. These + * methods are put here rather than in ACE_OS in order to + * separate concerns. + */ class ACE_Export ACE : public ACE_Flag_Manip, public ACE_Handle_Ops, public ACE_Lib_Find, public ACE_Init_ACE, public ACE_Sock_Connect { - // = TITLE - // Contains value added ACE methods that extend the behavior - // of the UNIX and Win32 OS calls. - // - // = DESCRIPTION - // This class consolidates all these ACE static methods in a - // single place in order to manage the namespace better. These - // methods are put here rather than in ACE_OS in order to - // separate concerns. ACE_CLASS_IS_NAMESPACE (ACE); public: // = ACE version information. + /// E.g., the "4" in ACE 4.3.19. static u_int major_version (void); - // E.g., the "4" in ACE 4.3.19. + /// E.g., the "3" in ACE 4.3.19. static u_int minor_version (void); - // E.g., the "3" in ACE 4.3.19. + /// E.g., the "19" in ACE 4.3.19. + /// Returns 0 for "stable" (non-beta) releases. static u_int beta_version (void); - // E.g., the "19" in ACE 4.3.19. Returns 0 for "stable" (non-beta) releases. // = C++ compiler version information. + /// E.g., the "SunPro C++" in SunPro C++ 4.32.0 static const ACE_TCHAR * compiler_name (void); - // E.g., the "SunPro C++" in SunPro C++ 4.32.0 + /// E.g., the "4" in SunPro C++ 4.32.0 static u_int compiler_major_version (void); - // E.g., the "4" in SunPro C++ 4.32.0 + /// E.g., the "32" in SunPro C++ 4.32.0 static u_int compiler_minor_version (void); - // E.g., the "32" in SunPro C++ 4.32.0 + /// E.g., the "0" in SunPro C++ 4.32.0 static u_int compiler_beta_version (void); - // E.g., the "0" in SunPro C++ 4.32.0 + /// Check if error indicates the process being out of handles (file + /// descriptors). static int out_of_handles (int error); - // Check if error indicates the process being out of handles (file - // descriptors). - - // = I/O operations. - - // = Notes on common parameters: - // - // <handle> is the connected endpoint that will be used for I/O. - // - // <buf> is the buffer to write from or receive into. - // - // <len> is the number of bytes to transfer. - // - // The <timeout> parameter in the following methods indicates how - // long to blocking trying to transfer data. If <timeout> == 0, - // then the call behaves as a normal send/recv call, i.e., for - // blocking sockets, the call will block until action is possible; - // for non-blocking sockets, EWOULDBLOCK will be returned if no - // action is immediately possible. - // - // If <timeout> != 0, the call will wait until the relative time - // specified in *<timeout> elapses. - // - // The "_n()" I/O methods keep looping until all the data has been - // transferred. These methods also work for sockets in non-blocking - // mode i.e., they keep looping on EWOULDBLOCK. <timeout> is used - // to make sure we keep making progress, i.e., the same timeout - // value is used for every I/O operation in the loop and the timeout - // is not counted down. - // - // The return values for the "*_n()" methods match the return values - // from the non "_n()" methods and are specified as follows: - // - // - On complete transfer, the number of bytes transferred is returned. - // - On timeout, -1 is returned, errno == ETIME. - // - On error, -1 is returned, errno is set to appropriate error. - // - On EOF, 0 is returned, errno is irrelevant. - // - // On partial transfers, i.e., if any data is transferred before - // timeout/error/EOF, <bytes_transferred> will contain the number of - // bytes transferred. - // - // Methods with <iovec> parameter are I/O vector variants of the I/O - // operations. - // - // Methods with the extra <flags> argument will always result in - // <send> getting called. Methods without the extra <flags> argument - // will result in <send> getting called on Win32 platforms, and - // <write> getting called on non-Win32 platforms. + /** + * @name I/O operations + * + * Notes on common parameters: + * + * <handle> is the connected endpoint that will be used for I/O. + * + * <buf> is the buffer to write from or receive into. + * + * <len> is the number of bytes to transfer. + * + * The <timeout> parameter in the following methods indicates how + * long to blocking trying to transfer data. If <timeout> == 0, + * then the call behaves as a normal send/recv call, i.e., for + * blocking sockets, the call will block until action is possible; + * for non-blocking sockets, EWOULDBLOCK will be returned if no + * action is immediately possible. + * + * If <timeout> != 0, the call will wait until the relative time + * specified in *<timeout> elapses. + * + * The "_n()" I/O methods keep looping until all the data has been + * transferred. These methods also work for sockets in non-blocking + * mode i.e., they keep looping on EWOULDBLOCK. <timeout> is used + * to make sure we keep making progress, i.e., the same timeout + * value is used for every I/O operation in the loop and the timeout + * is not counted down. + * + * The return values for the "*_n()" methods match the return values + * from the non "_n()" methods and are specified as follows: + * + * - On complete transfer, the number of bytes transferred is returned. + * - On timeout, -1 is returned, errno == ETIME. + * - On error, -1 is returned, errno is set to appropriate error. + * - On EOF, 0 is returned, errno is irrelevant. + * + * On partial transfers, i.e., if any data is transferred before + * timeout/error/EOF, <bytes_transferred> will contain the number of + * bytes transferred. + * + * Methods with <iovec> parameter are I/O vector variants of the I/O + * operations. + * + * Methods with the extra <flags> argument will always result in + * <send> getting called. Methods without the extra <flags> argument + * will result in <send> getting called on Win32 platforms, and + * <write> getting called on non-Win32 platforms. + */ + //@{ static ssize_t recv (ACE_HANDLE handle, void *buf, size_t len, @@ -183,8 +185,8 @@ public: const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0); + /// Varargs variant. static ssize_t recv (ACE_HANDLE handle, size_t n, ...); - // Varargs variant. static ssize_t recvv (ACE_HANDLE handle, iovec *iov, @@ -260,8 +262,8 @@ public: const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0); + /// Varargs variant. static ssize_t send (ACE_HANDLE handle, size_t n, ...); - // Varargs variant. static ssize_t sendv (ACE_HANDLE handle, const iovec *iov, @@ -300,56 +302,67 @@ public: const iovec *iov, int iovcnt, size_t *bytes_transferred = 0); + //@} + /** + * Wait up to <timeout> amount of time to passively establish a + * connection. This method doesn't perform the <accept>, it just + * does the timed wait... + */ static int handle_timed_accept (ACE_HANDLE listener, ACE_Time_Value *timeout, int restart); - // Wait up to <timeout> amount of time to passively establish a - // connection. This method doesn't perform the <accept>, it just - // does the timed wait... + /** + * Wait up to <timeout> amount of time to complete an actively + * established non-blocking connection. If <is_tli> is non-0 then + * we are being called by a TLI wrapper (which behaves slightly + * differently from a socket wrapper). + */ static ACE_HANDLE handle_timed_complete (ACE_HANDLE listener, const ACE_Time_Value *timeout, int is_tli = 0); - // Wait up to <timeout> amount of time to complete an actively - // established non-blocking connection. If <is_tli> is non-0 then - // we are being called by a TLI wrapper (which behaves slightly - // differently from a socket wrapper). + /** + * Reset the limit on the number of open handles. If <new_limit> == + * -1 set the limit to the maximum allowable. Otherwise, set it to + * be the value of <new_limit>. + */ static int set_handle_limit (int new_limit = -1); - // Reset the limit on the number of open handles. If <new_limit> == - // -1 set the limit to the maximum allowable. Otherwise, set it to - // be the value of <new_limit>. + /** + * Returns the maximum number of open handles currently permitted in + * this process. This maximum may be extended using + * <ACE::set_handle_limit>. + */ static int max_handles (void); - // Returns the maximum number of open handles currently permitted in - // this process. This maximum may be extended using - // <ACE::set_handle_limit>. // = String functions #if !defined (ACE_HAS_WINCE) + /** + * Return a dynamically allocated duplicate of <str>, substituting + * the environment variable if <str[0] == '$'>. Note that the + * pointer is allocated with <ACE_OS::malloc> and must be freed by + * <ACE_OS::free>. + */ static ACE_TCHAR *strenvdup (const ACE_TCHAR *str); - // Return a dynamically allocated duplicate of <str>, substituting - // the environment variable if <str[0] == '$'>. Note that the - // pointer is allocated with <ACE_OS::malloc> and must be freed by - // <ACE_OS::free>. #endif /* ACE_HAS_WINCE */ + /// Returns a pointer to the "end" of the string, i.e., the character + /// past the '\0'. static const char *strend (const char *s); - // Returns a pointer to the "end" of the string, i.e., the character - // past the '\0'. + /// This method is just like <strdup>, except that it uses <operator + /// new> rather than <malloc>. static char *strnew (const char *s); - // This method is just like <strdup>, except that it uses <operator - // new> rather than <malloc>. + /// Create a fresh new copy of <str>, up to <n> chars long. Uses + /// <ACE_OS::malloc> to allocate the new string. static char *strndup (const char *str, size_t n); - // Create a fresh new copy of <str>, up to <n> chars long. Uses - // <ACE_OS::malloc> to allocate the new string. + /// Create a fresh new copy of <str>, up to <n> chars long. Uses + /// <ACE_OS::malloc> to allocate the new string. static char *strnnew (const char *str, size_t n); - // Create a fresh new copy of <str>, up to <n> chars long. Uses - // <ACE_OS::malloc> to allocate the new string. #if defined (ACE_HAS_WCHAR) static const wchar_t *strend (const wchar_t *s); @@ -362,187 +375,207 @@ public: #endif /* ACE_HAS_WCHAR */ + /** + * On Win32 returns <pathname> if it already ends in ".exe," + * otherwise returns a dynamically allocated buffer containing + * "<pathname>.exe". Always returns <pathname> on UNIX. + */ static const ACE_TCHAR *execname (const ACE_TCHAR *pathname); - // On Win32 returns <pathname> if it already ends in ".exe," - // otherwise returns a dynamically allocated buffer containing - // "<pathname>.exe". Always returns <pathname> on UNIX. + /** + * Returns the "basename" of a <pathname> separated by <delim>. For + * instance, the basename of "/tmp/foo.cpp" is "foo.cpp" when + * <delim> is '/'. + */ static const ACE_TCHAR *basename (const ACE_TCHAR *pathname, ACE_TCHAR delim = ACE_DIRECTORY_SEPARATOR_CHAR); - // Returns the "basename" of a <pathname> separated by <delim>. For - // instance, the basename of "/tmp/foo.cpp" is "foo.cpp" when - // <delim> is '/'. + /** + * Returns the "dirname" of a <pathname>. For instance, the dirname + * of "/tmp/foo.cpp" is "/tmp" when <delim> is '/'. If <pathname> + * has no <delim> ".\0" is returned. This method does not modify + * <pathname> and is not reentrant. + */ static const ACE_TCHAR *dirname (const ACE_TCHAR *pathname, ACE_TCHAR delim = ACE_DIRECTORY_SEPARATOR_CHAR); - // Returns the "dirname" of a <pathname>. For instance, the dirname - // of "/tmp/foo.cpp" is "/tmp" when <delim> is '/'. If <pathname> - // has no <delim> ".\0" is returned. This method does not modify - // <pathname> and is not reentrant. + /** + * Returns the current timestamp in the form + * "hour:minute:second:microsecond." The month, day, and year are + * also stored in the beginning of the date_and_time array. Returns + * 0 if unsuccessful, else returns pointer to beginning of the + * "time" portion of <day_and_time>. + */ static ACE_TCHAR *timestamp (ACE_TCHAR date_and_time[], int time_len); - // Returns the current timestamp in the form - // "hour:minute:second:microsecond." The month, day, and year are - // also stored in the beginning of the date_and_time array. Returns - // 0 if unsuccessful, else returns pointer to beginning of the - // "time" portion of <day_and_time>. + /** + * if <avoid_zombies> == 0 call <ACE_OS::fork> directly, else create + * an orphan process that's inherited by the init process; init + * cleans up when the orphan process terminates so we don't create + * zombies. + */ static pid_t fork (const ACE_TCHAR *program_name = ACE_LIB_TEXT ("<unknown>"), int avoid_zombies = 0); - // if <avoid_zombies> == 0 call <ACE_OS::fork> directly, else create - // an orphan process that's inherited by the init process; init - // cleans up when the orphan process terminates so we don't create - // zombies. + /** + * Become a daemon process using the algorithm in Richard Stevens + * "Advanced Programming in the UNIX Environment." If + * <close_all_handles> is non-zero then all open file handles are + * closed. + */ static int daemonize (const ACE_TCHAR pathname[] = ACE_LIB_TEXT ("/"), int close_all_handles = ACE_DEFAULT_CLOSE_ALL_HANDLES, const ACE_TCHAR program_name[] = ACE_LIB_TEXT ("<unknown>")); - // Become a daemon process using the algorithm in Richard Stevens - // "Advanced Programming in the UNIX Environment." If - // <close_all_handles> is non-zero then all open file handles are - // closed. // = Shield us from Win32's inability to select on STDIN. // = Miscelleous functions. + /// Rounds the request to a multiple of the page size. static size_t round_to_pagesize (off_t length); - // Rounds the request to a multiple of the page size. + /// Rounds the request to a multiple of the allocation granularity. static size_t round_to_allocation_granularity (off_t len); - // Rounds the request to a multiple of the allocation granularity. // @@ UNICODE what about buffer? + /// Format buffer into printable format. This is useful for + /// debugging. static int format_hexdump (const char *buffer, int size, ACE_TCHAR *obuf, int obuf_sz); - // Format buffer into printable format. This is useful for - // debugging. + /// Computes the hash value of <str> using the "Hash PJW" routine. static u_long hash_pjw (const char *str); - // Computes the hash value of <str> using the "Hash PJW" routine. + /// Computes the hash value of <str> using the "Hash PJW" routine. static u_long hash_pjw (const char *str, size_t len); - // Computes the hash value of <str> using the "Hash PJW" routine. #if defined (ACE_HAS_WCHAR) + /// Computes the hash value of <str> using the "Hash PJW" routine. static u_long hash_pjw (const wchar_t *str); - // Computes the hash value of <str> using the "Hash PJW" routine. + /// Computes the hash value of <str> using the "Hash PJW" routine. static u_long hash_pjw (const wchar_t *str, size_t len); - // Computes the hash value of <str> using the "Hash PJW" routine. #endif /* ACE_HAS_WCHAR */ + /// Computes the ISO 8802-3 standard 32 bits CRC for the string + /// (not for a file). static u_long crc32 (const char *str); - // Computes the ISO 8802-3 standard 32 bits CRC for the string - // (not for a file). + /// Computes the ISO 8802-3 standard 32 bits CRC for the given + /// buffer (the length is included in the CRC). static u_long crc32 (const char *buf, ACE_UINT32 len); - // Computes the ISO 8802-3 standard 32 bits CRC for the given - // buffer (the length is included in the CRC). + /// Euclid's greatest common divisor algorithm. static u_long gcd (u_long x, u_long y); - // Euclid's greatest common divisor algorithm. + /// Calculates the minimum enclosing frame size for the given values. static u_long minimum_frame_size (u_long period1, u_long period2); - // Calculates the minimum enclosing frame size for the given values. + /** + * Function that can burn up noticeable CPU time: brute-force + * determination of whether number "n" is prime. Returns 0 if + * it is prime, or the smallest factor if it is not prime. min_factor + * and max_factor can be used to partition the work among threads. + * For just one thread, typical values are 2 and n/2. + */ static u_long is_prime (const u_long n, const u_long min_factor, const u_long max_factor); - // Function that can burn up noticeable CPU time: brute-force - // determination of whether number "n" is prime. Returns 0 if - // it is prime, or the smallest factor if it is not prime. min_factor - // and max_factor can be used to partition the work among threads. - // For just one thread, typical values are 2 and n/2. + /// Map troublesome win32 errno values to values that standard C + /// strerr function understands. Thank you Microsoft. static int map_errno (int error); - // Map troublesome win32 errno values to values that standard C - // strerr function understands. Thank you Microsoft. + /// Returns a string containing the error message corresponding to a + /// WinSock error. This works around an omission in the Win32 API... static const ACE_TCHAR *sock_error (int error); - // Returns a string containing the error message corresponding to a - // WinSock error. This works around an omission in the Win32 API... + /** + * Checks if process with <pid> is still alive. Returns 1 if it is + * still alive, 0 if it isn't alive, and -1 if something weird + * happened. + */ static int process_active (pid_t pid); - // Checks if process with <pid> is still alive. Returns 1 if it is - // still alive, 0 if it isn't alive, and -1 if something weird - // happened. + /** + * Terminate the process abruptly with id <pid>. On Win32 platforms + * this uses <TerminateProcess> and on POSIX platforms is uses + * <kill> with the -9 (SIGKILL) signal, which cannot be caught or + * ignored. Note that this call is potentially dangerous to use + * since the process being terminated may not have a chance to + * cleanup before it shuts down. + */ static int terminate_process (pid_t pid); - // Terminate the process abruptly with id <pid>. On Win32 platforms - // this uses <TerminateProcess> and on POSIX platforms is uses - // <kill> with the -9 (SIGKILL) signal, which cannot be caught or - // ignored. Note that this call is potentially dangerous to use - // since the process being terminated may not have a chance to - // cleanup before it shuts down. + /** + * This method uses process id and object pointer to come up with a + * machine wide unique name. The process ID will provide uniqueness + * between processes on the same machine. The "this" pointer of the + * <object> will provide uniqueness between other "live" objects in + * the same process. The uniqueness of this name is therefore only + * valid for the life of <object>. + */ static void unique_name (const void *object, ACE_TCHAR *name, size_t length); - // This method uses process id and object pointer to come up with a - // machine wide unique name. The process ID will provide uniqueness - // between processes on the same machine. The "this" pointer of the - // <object> will provide uniqueness between other "live" objects in - // the same process. The uniqueness of this name is therefore only - // valid for the life of <object>. + /// Computes the base 2 logarithm of <num>. static u_long log2 (u_long num); - // Computes the base 2 logarithm of <num>. + /// Hex conversion utility. static ACE_TCHAR nibble2hex (u_int n); - // Hex conversion utility. + /// Convert a hex character to its byte representation. static u_char hex2byte (ACE_TCHAR c); - // Convert a hex character to its byte representation. // = Set/get the debug level. static char debug (void); static void debug (char d); + /// Timed wait for handle to get read ready. static int handle_read_ready (ACE_HANDLE handle, const ACE_Time_Value *timeout); - // Timed wait for handle to get read ready. + /// Timed wait for handle to get write ready. static int handle_write_ready (ACE_HANDLE handle, const ACE_Time_Value *timeout); - // Timed wait for handle to get write ready. + /// Timed wait for handle to get exception ready. static int handle_exception_ready (ACE_HANDLE handle, const ACE_Time_Value *timeout); - // Timed wait for handle to get exception ready. + /// Timed wait for handle to get read, write, or exception ready. static int handle_ready (ACE_HANDLE handle, const ACE_Time_Value *timeout, int read_ready, int write_ready, int exception_ready); - // Timed wait for handle to get read, write, or exception ready. + /// Wait for <timeout> before proceeding to a <recv> operation. + /// <val> keeps track of whether we're in non-blocking mode or not. static int enter_recv_timedwait (ACE_HANDLE handle, const ACE_Time_Value *timeout, int &val); - // Wait for <timeout> before proceeding to a <recv> operation. - // <val> keeps track of whether we're in non-blocking mode or not. + /// Wait for <timeout> before proceeding to a <send> operation. + /// <val> keeps track of whether we're in non-blocking mode or not. static int enter_send_timedwait (ACE_HANDLE handle, const ACE_Time_Value* timeout, int &val); - // Wait for <timeout> before proceeding to a <send> operation. - // <val> keeps track of whether we're in non-blocking mode or not. + /// This makes sure that <handle> is set into non-blocking mode. + /// <val> keeps track of whether were in non-blocking mode or not. static void record_and_set_non_blocking_mode (ACE_HANDLE handle, int &val); - // This makes sure that <handle> is set into non-blocking mode. - // <val> keeps track of whether were in non-blocking mode or not. + /// Cleanup after a timed operation, restore the appropriate + /// non-blocking status of <handle>. static void restore_non_blocking_mode (ACE_HANDLE handle, int val); - // Cleanup after a timed operation, restore the appropriate - // non-blocking status of <handle>. private: @@ -666,20 +699,20 @@ private: const ACE_Time_Value *timeout, size_t *bytes_transferred); + /// Size of a VM page. static size_t pagesize_; - // Size of a VM page. + /// Size of allocation granularity. static size_t allocation_granularity_; - // Size of allocation granularity. + /// CRC table. static u_long crc_table_[]; - // CRC table. + /// Hex characters. static const ACE_TCHAR hex_chars_[]; - // Hex characters. + /// Are we debugging ACE? static char debug_; - // Are we debugging ACE? }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/ARGV.h b/ace/ARGV.h index 233c818c3b5..9f2e501a982 100644 --- a/ace/ARGV.h +++ b/ace/ARGV.h @@ -1,18 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ARGV.h -// -// = AUTHOR -// Doug Schmidt, Everett Anderson -// -// ============================================================================ + +//============================================================================= +/** + * @file ARGV.h + * + * $Id$ + * + * @author Doug Schmidt + * @author Everett Anderson + */ +//============================================================================= + #ifndef ACE_ARGUMENT_VECTOR_H #define ACE_ARGUMENT_VECTOR_H @@ -26,126 +24,141 @@ #include "ace/Containers.h" +/** + * @class ACE_ARGV + * + * @brief Transforms a string <buf> into an <argv> style vector of + * strings or an <argv> style vector of string <buf>, performing + * environment variable substitutions if necessary. + */ class ACE_Export ACE_ARGV { - // = TITLE - // Transforms a string <buf> into an <argv> style vector of - // strings or an <argv> style vector of string <buf>, performing - // environment variable substitutions if necessary. public: // = Initialization and termination. + /** + * Converts <buf> into an <argv>-style vector of strings. If + * <substitute_env_args> is enabled then we'll substitute the + * environment variables for each $ENV encountered in the string. + * The subscript and <argv> operations are not allowed on an + * ACE_ARGV created this way. + */ ACE_ARGV (const ACE_TCHAR buf[], int substitute_env_args = 1); - // Converts <buf> into an <argv>-style vector of strings. If - // <substitute_env_args> is enabled then we'll substitute the - // environment variables for each $ENV encountered in the string. - // The subscript and <argv> operations are not allowed on an - // ACE_ARGV created this way. + /** + * Converts <argv> into a linear string. If <substitute_env_args> + * is enabled then we'll substitute the environment variables for + * each $ENV encountered in the string. The <buf> operation is not + * allowed on an ACE_ARGV created this way. + */ ACE_ARGV (ACE_TCHAR *argv[], int substitute_env_args = 1); - // Converts <argv> into a linear string. If <substitute_env_args> - // is enabled then we'll substitute the environment variables for - // each $ENV encountered in the string. The <buf> operation is not - // allowed on an ACE_ARGV created this way. + /** + * Creates an ACE_ARGV which is the concatenation of the first_argv + * and the second argv. The argv arguments should be null pointer + * terminated. + */ ACE_ARGV (ACE_TCHAR *first_argv[], ACE_TCHAR *second_argv[], int substitute_env_args =1); - // Creates an ACE_ARGV which is the concatenation of the first_argv - // and the second argv. The argv arguments should be null pointer - // terminated. + /** + * Entry point for creating an ACE_TCHAR *[] command line + * iteratively via the <add> method. When this constructor is used, + * the <ITERATIVE> state is enabled. The <argv> and <buf> methods + * are allowed, and the result is recreated when called multiple + * times. The subscript operator is not allowed. + */ ACE_ARGV (int substitute_env_args = 1); - // Entry point for creating an ACE_TCHAR *[] command line - // iteratively via the <add> method. When this constructor is used, - // the <ITERATIVE> state is enabled. The <argv> and <buf> methods - // are allowed, and the result is recreated when called multiple - // times. The subscript operator is not allowed. + /// Destructor. ~ACE_ARGV (void); - // Destructor. // = Accessor arguments. + /// Returns the <index>th string in the ARGV array. const ACE_TCHAR *operator[] (size_t index); - // Returns the <index>th string in the ARGV array. + /** + * Returns the <argv> array. Caller should not delete this memory + * since the <ARGV> destructor will delete it. If the caller + * modifies the array in the iterative mode, the changes are not + * saved to the queue. + */ ACE_TCHAR **argv (void); - // Returns the <argv> array. Caller should not delete this memory - // since the <ARGV> destructor will delete it. If the caller - // modifies the array in the iterative mode, the changes are not - // saved to the queue. + /// Returns <argc>. size_t argc (void) const; - // Returns <argc>. + /// Returns the <buf>. Caller should not delete this memory since + /// the <ARGV> destructor will delete it. const ACE_TCHAR *buf (void); - // Returns the <buf>. Caller should not delete this memory since - // the <ARGV> destructor will delete it. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /// Add another argument. This only works in the <ITERATIVE> state. + /// Returns -1 on failure and 0 on success. int add (const ACE_TCHAR *next_arg); - // Add another argument. This only works in the <ITERATIVE> state. - // Returns -1 on failure and 0 on success. + /** + * Add another <argv> array. The <argv> parameter must be NULL + * terminated. This only works in the <ITERATIVE> state. Returns + * -1 on failure and 0 on success. + */ int add (ACE_TCHAR *argv[]); - // Add another <argv> array. The <argv> parameter must be NULL - // terminated. This only works in the <ITERATIVE> state. Returns - // -1 on failure and 0 on success. + /// What state is this ACE_ARGV in? int state (void) const; - // What state is this ACE_ARGV in? // These are the states possible via the different constructors. enum States { + /// ACE_ARGV converts buf[] to ACE_TCHAR *argv[] TO_STRING = 1, - // ACE_ARGV converts buf[] to ACE_TCHAR *argv[] + /// ACE_ARGV converts ACE_TCHAR *argv[] to buf[] TO_PTR_ARRAY = 2, - // ACE_ARGV converts ACE_TCHAR *argv[] to buf[] + /// Builds buf[] or ACE_TCHAR *argv[] iteratively with <add>. ITERATIVE = 3 - // Builds buf[] or ACE_TCHAR *argv[] iteratively with <add>. }; private: + /// Creates buf_ from the queue, deletes previous buf_. int create_buf_from_queue (void); - // Creates buf_ from the queue, deletes previous buf_. + /// Converts buf_ into the ACE_TCHAR *argv[] format. int string_to_argv (void); - // Converts buf_ into the ACE_TCHAR *argv[] format. + /// Returns the string created from argv in buf and + /// returns the number of arguments. int argv_to_string (ACE_TCHAR **argv, ACE_TCHAR *&buf); - // Returns the string created from argv in buf and - // returns the number of arguments. + /// Replace args with environment variable values? int substitute_env_args_; - // Replace args with environment variable values? + /// Current state marker. int state_; - // Current state marker. + /// Number of arguments in the ARGV array. size_t argc_; - // Number of arguments in the ARGV array. + /// The array of string arguments. ACE_TCHAR **argv_; - // The array of string arguments. + /// Buffer containing the <argv> contents. ACE_TCHAR *buf_; - // Buffer containing the <argv> contents. + /// Total length of the arguments in the queue, not counting + /// separating spaces size_t length_; - // Total length of the arguments in the queue, not counting - // separating spaces + /// Queue which keeps user supplied arguments. This is only + /// active in the "iterative" mode. ACE_Unbounded_Queue<ACE_TCHAR *> queue_; - // Queue which keeps user supplied arguments. This is only - // active in the "iterative" mode. }; #if defined (__ACE_INLINE__) diff --git a/ace/ATM_Acceptor.h b/ace/ATM_Acceptor.h index 0c093c40ce5..173be1ad532 100644 --- a/ace/ATM_Acceptor.h +++ b/ace/ATM_Acceptor.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ATM_Acceptor.h -// -// = AUTHOR -// Joe Hoffert -// -// ============================================================================ + +//============================================================================= +/** + * @file ATM_Acceptor.h + * + * $Id$ + * + * @author Joe Hoffert + */ +//============================================================================= + #ifndef ACE_ATM_ACCEPTOR_H #define ACE_ATM_ACCEPTOR_H @@ -41,34 +38,36 @@ typedef ACE_SOCK_Acceptor ATM_Acceptor; typedef ACE_TLI_Acceptor ATM_Acceptor; #endif // ACE_HAS_FORE_ATM_WS2 || ACE_HAS_LINUX_ATM +/** + * @class ACE_ATM_Acceptor + * + * @brief Defines the member functions for ACE_ATM_Acceptor abstraction. + * + * This class wraps up the ACE_SOCK_Acceptor and ACE_TLI_Acceptor + * to make the mechanism for the ATM protocol transparent. + */ class ACE_Export ACE_ATM_Acceptor { - // = TITLE - // Defines the member functions for ACE_ATM_Acceptor abstraction. - // - // = DESCRIPTION - // This class wraps up the ACE_SOCK_Acceptor and ACE_TLI_Acceptor - // to make the mechanism for the ATM protocol transparent. public: // = Initialization and termination methods. + /// Default constructor. ACE_ATM_Acceptor (void); - // Default constructor. ~ACE_ATM_Acceptor (); + /// Initiate a passive mode connection. ACE_ATM_Acceptor (const ACE_Addr &remote_sap, int backlog = ACE_DEFAULT_BACKLOG, ACE_ATM_Params params = ACE_ATM_Params()); - // Initiate a passive mode connection. + /// Initiate a passive mode socket. ACE_HANDLE open (const ACE_Addr &remote_sap, int backlog = ACE_DEFAULT_BACKLOG, ACE_ATM_Params params = ACE_ATM_Params()); - // Initiate a passive mode socket. + /// Close down the acceptor and release resources. int close (void); - // Close down the acceptor and release resources. // = Passive connection acceptance method. @@ -84,18 +83,18 @@ public: // block forever, a <timeout> of {0, 0} means poll. <restart> == 1 // means "restart if interrupted." + /// Get the local address currently listening on int get_local_addr( ACE_ATM_Addr &local_addr ); - // Get the local address currently listening on // = Meta-type info typedef ACE_ATM_Addr PEER_ADDR; typedef ACE_ATM_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: ATM_Acceptor acceptor_; @@ -108,4 +107,3 @@ private: #endif /* ACE_HAS_ATM */ #include "ace/post.h" #endif /* ACE_ATM_ACCEPTOR_H */ - diff --git a/ace/ATM_Addr.h b/ace/ATM_Addr.h index f36d386aed7..639d2f71e0c 100644 --- a/ace/ATM_Addr.h +++ b/ace/ATM_Addr.h @@ -1,17 +1,14 @@ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ATM_Addr.h -// -// = AUTHOR -// Joe Hoffert <joeh@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file ATM_Addr.h + * + * $Id$ + * + * @author Joe Hoffert <joeh@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_ATM_ADDR_H #define ACE_ATM_ADDR_H @@ -30,21 +27,26 @@ typedef ATMSAPAddress ATM_Addr; #define FORE_NAME_SPACE NS_ALL typedef struct sockaddr_atm ATM_Addr; #elif defined (ACE_HAS_LINUX_ATM) + #include "atm.h" + //pbrandao:as Linux has this 2 structs separeted we "link it" here typedef struct _linux_atm_addr { struct sockaddr_atmsvc sockaddratmsvc; - struct atm_sap atmsap; + struct atm_sap atmsap; } ATM_Addr; #else typedef int ATM_Addr; #endif /* ACE_HAS_FORE_ATM_XTI/ACE_HAS_FORE_ATM_WS2/ACE_HAS_LINUX_ATM */ +/** + * @class ACE_ATM_Addr + * + * @brief Defines the ATM domain address family address format. + */ class ACE_Export ACE_ATM_Addr : public ACE_Addr { - // = TITLE - // Defines the ATM domain address family address format. public: // Constants used for ATM options static const long LINE_RATE; @@ -53,98 +55,113 @@ public: static const int DEFAULT_SELECTOR; // = Initialization methods. + /// Default constructor. ACE_ATM_Addr (unsigned char selector = DEFAULT_SELECTOR); - // Default constructor. + /// Copy constructor. ACE_ATM_Addr (const ACE_ATM_Addr &, unsigned char selector = DEFAULT_SELECTOR); - // Copy constructor. + /** + * Creates an <ACE_ATM_Addr> from an ATMSAPAddress structure. This + * is vendor specific (FORE systems). May need to change when other + * vendors are supported. + */ ACE_ATM_Addr (const ATM_Addr *, unsigned char selector = DEFAULT_SELECTOR); - // Creates an <ACE_ATM_Addr> from an ATMSAPAddress structure. This - // is vendor specific (FORE systems). May need to change when other - // vendors are supported. + /** + * Initializes an <ACE_ATM_Addr> from the <sap> which can be + * "atm-address" (e.g., + * "47.0005.80.ffe100.0000.f20f.2200.0020480694f9.00") or "hostname" + * (e.g., "frisbee.cs.wustl.edu"). + */ ACE_ATM_Addr (const ACE_TCHAR sap[], unsigned char selector = DEFAULT_SELECTOR); - // Initializes an <ACE_ATM_Addr> from the <sap> which can be - // "atm-address" (e.g., - // "47.0005.80.ffe100.0000.f20f.2200.0020480694f9.00") or "hostname" - // (e.g., "frisbee.cs.wustl.edu"). + /// Default dtor. ~ACE_ATM_Addr (void); - // Default dtor. // = Initialization methods (useful after object construction). + /// Default initialization for non-address values (e.g., + /// t_atm_sap_addr.SVE_tag_addr, t_atm_sap_addr.SVE_tag_selector) void init (unsigned char selector = DEFAULT_SELECTOR); - // Default initialization for non-address values (e.g., - // t_atm_sap_addr.SVE_tag_addr, t_atm_sap_addr.SVE_tag_selector) + /// Initializes from another <ACE_ATM_Addr>. int set (const ACE_ATM_Addr &, unsigned char selector = DEFAULT_SELECTOR); - // Initializes from another <ACE_ATM_Addr>. + /** + * Initializes an <ACE_ATM_Addr> from an ATMSAPAddress/sockaddr_atm + * structure. This is vendor specific (FORE systems). May need to + * change when other vendors are supported. + */ int set (const ATM_Addr *, unsigned char selector = DEFAULT_SELECTOR); - // Initializes an <ACE_ATM_Addr> from an ATMSAPAddress/sockaddr_atm - // structure. This is vendor specific (FORE systems). May need to - // change when other vendors are supported. + /** + * Initializes an <ACE_ATM_Addr> from the <sap> which can be + * "atm-address" (e.g., + * "47.0005.80.ffe100.0000.f20f.2200.0020480694f9.00") or "hostname" + * (e.g., "frisbee.cs.wustl.edu"). + */ int set (const ACE_TCHAR sap[], unsigned char selector = DEFAULT_SELECTOR); - // Initializes an <ACE_ATM_Addr> from the <sap> which can be - // "atm-address" (e.g., - // "47.0005.80.ffe100.0000.f20f.2200.0020480694f9.00") or "hostname" - // (e.g., "frisbee.cs.wustl.edu"). + /** + * Initializes an <ACE_ATM_Addr> from the <sap> which can be + * "atm-address" (e.g., + * "47.0005.80.ffe100.0000.f20f.2200.0020480694f9.00") or "hostname" + * (e.g., "frisbee.cs.wustl.edu"). + */ virtual int string_to_addr (const ACE_TCHAR sap[]); - // Initializes an <ACE_ATM_Addr> from the <sap> which can be - // "atm-address" (e.g., - // "47.0005.80.ffe100.0000.f20f.2200.0020480694f9.00") or "hostname" - // (e.g., "frisbee.cs.wustl.edu"). - virtual int addr_to_string (ACE_TCHAR addr[], + /** + * Return the character representation of the ATM address (e.g., + * "47.0005.80.ffe100.0000.f20f.2200.0020480694f9.00") storing it in + * the <addr> (which is assumed to be <addrlen> bytes long). This + * version is reentrant. Returns -1 if the <addrlen> of the <addr> + * is too small, else 0. + */ + virtual int addr_to_string (ACE_TCHAR addr[], size_t addrlen) const; - // Return the character representation of the ATM address (e.g., - // "47.0005.80.ffe100.0000.f20f.2200.0020480694f9.00") storing it in - // the <addr> (which is assumed to be <addrlen> bytes long). This - // version is reentrant. Returns -1 if the <addrlen> of the <addr> - // is too small, else 0. + /** + * Return the character representation of the ATM address (e.g., + * "47.0005.80.ffe100.0000.f20f.2200.0020480694f9.00"). Returns -1 + * if the <size> of the <buffer> is too small, else 0.(This version + * is non-reentrant since it returns a pointer to a static data + * area.) + */ const ACE_TCHAR *addr_to_string (void) const; - // Return the character representation of the ATM address (e.g., - // "47.0005.80.ffe100.0000.f20f.2200.0020480694f9.00"). Returns -1 - // if the <size> of the <buffer> is too small, else 0.(This version - // is non-reentrant since it returns a pointer to a static data - // area.) + /// Return a pointer to the underlying network address. virtual void *get_addr (void) const; - // Return a pointer to the underlying network address. + /// Set a pointer to the address. virtual void set_addr (void *, int); - // Set a pointer to the address. + /// Return the selector for network address. unsigned char get_selector (void) const; - // Return the selector for network address. + /// Set the selector for the network address. void set_selector (unsigned char); - // Set the selector for the network address. + /** + * Compare two addresses for equality. The addresses are considered + * equal if they contain the same ATM address. Q: Is there any + * other check for equality needed for ATM? + */ int operator == (const ACE_ATM_Addr &SAP) const; - // Compare two addresses for equality. The addresses are considered - // equal if they contain the same ATM address. Q: Is there any - // other check for equality needed for ATM? + /// Compare two addresses for inequality. int operator != (const ACE_ATM_Addr &SAP) const; - // Compare two addresses for inequality. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. - + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. // char *construct_options (ACE_HANDLE fd, // int qos_kb, @@ -152,8 +169,6 @@ public: // long *optsize); // // Construct options for ATM connections -protected: - private: ATM_Addr atm_addr_; }; @@ -164,4 +179,3 @@ private: #include "ace/post.h" #endif /* ACE_ATM_ADDR_H */ - diff --git a/ace/ATM_Connector.h b/ace/ATM_Connector.h index b5f31b94325..b518a5ea383 100644 --- a/ace/ATM_Connector.h +++ b/ace/ATM_Connector.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ATM_Connector.h -// -// = AUTHOR -// Joe Hoffert -// -// ============================================================================ + +//============================================================================= +/** + * @file ATM_Connector.h + * + * $Id$ + * + * @author Joe Hoffert + */ +//============================================================================= + #ifndef ACE_ATM_CONNECTOR_H #define ACE_ATM_CONNECTOR_H @@ -36,16 +33,35 @@ typedef ACE_SOCK_Connector ATM_Connector; typedef ACE_XTI_ATM_Mcast ATM_Connector; #endif -class ACE_Export ACE_ATM_Connector +/** + * @class ACE_ATM_Connector + * + * @brief Defines an active connection factory for the ACE_ATM C++ + * wrappers. + */ +class ACE_Export ACE_ATM_Connector { - // = TITLE - // Defines an active connection factory for the ACE_ATM C++ - // wrappers. public: // = Initialization methods. + /// Default constructor. ACE_ATM_Connector (void); - // Default constructor. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <params> are the parameters needed for either socket + * or XTI/ATM connections. The <timeout> is the amount of time to + * wait to connect. If it's 0 then we block indefinitely. If + * *timeout == {0, 0} then the connection is done using non-blocking + * mode. In this case, if the connection can't be made immediately + * the value of -1 is returned with <errno == EWOULDBLOCK>. If + * *timeout > {0, 0} then this is the amount of time to wait before + * timing out. If the time expires before the connection is made + * <errno == ETIME>. The <local_sap> is the value of local address + * to bind to. If it's the default value of <ACE_ATM_Addr::sap_any> then + * the user is letting the OS do the binding. If <reuse_addr> == 1 + * then the <local_addr> is reused, even if it hasn't been cleanedup yet. + */ ACE_ATM_Connector (ACE_ATM_Stream &new_stream, const ACE_ATM_Addr &remote_sap, ACE_ATM_Params params = ACE_ATM_Params(), @@ -59,21 +75,23 @@ public: int flags = O_RDWR, #endif /* ACE_WIN32 */ int perms = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <params> are the parameters needed for either socket - // or XTI/ATM connections. The <timeout> is the amount of time to - // wait to connect. If it's 0 then we block indefinitely. If - // *timeout == {0, 0} then the connection is done using non-blocking - // mode. In this case, if the connection can't be made immediately - // the value of -1 is returned with <errno == EWOULDBLOCK>. If - // *timeout > {0, 0} then this is the amount of time to wait before - // timing out. If the time expires before the connection is made - // <errno == ETIME>. The <local_sap> is the value of local address - // to bind to. If it's the default value of <ACE_ATM_Addr::sap_any> then - // the user is letting the OS do the binding. If <reuse_addr> == 1 - // then the <local_addr> is reused, even if it hasn't been cleanedup yet. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <params> are the parameters needed for either socket + * or XTI/ATM connections. The <timeout> is the amount of time to + * wait to connect. If it's 0 then we block indefinitely. If + * *timeout == {0, 0} then the connection is done using non-blocking + * mode. In this case, if the connection can't be made immediately + * the value of -1 is returned with <errno == EWOULDBLOCK>. If + * *timeout > {0, 0} then this is the amount of time to wait before + * timing out. If the time expires before the connection is made + * <errno == ETIME>. The <local_sap> is the value of local address + * to bind to. If it's the default value of <ACE_ATM_Addr::sap_any> then + * the user is letting the OS do the binding. If <reuse_addr> == 1 + * then the <local_addr> is reused, even if it hasn't been cleanedup yet. + */ int connect (ACE_ATM_Stream &new_stream, const ACE_ATM_Addr &remote_sap, ACE_ATM_Params params = ACE_ATM_Params(), @@ -88,52 +106,43 @@ public: int flags = O_RDWR, #endif /* ACE_WIN32 */ int perms = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <params> are the parameters needed for either socket - // or XTI/ATM connections. The <timeout> is the amount of time to - // wait to connect. If it's 0 then we block indefinitely. If - // *timeout == {0, 0} then the connection is done using non-blocking - // mode. In this case, if the connection can't be made immediately - // the value of -1 is returned with <errno == EWOULDBLOCK>. If - // *timeout > {0, 0} then this is the amount of time to wait before - // timing out. If the time expires before the connection is made - // <errno == ETIME>. The <local_sap> is the value of local address - // to bind to. If it's the default value of <ACE_ATM_Addr::sap_any> then - // the user is letting the OS do the binding. If <reuse_addr> == 1 - // then the <local_addr> is reused, even if it hasn't been cleanedup yet. + /** + * Try to complete a non-blocking connection. + * If connection completion is successful then <new_stream> contains + * the connected ACE_SOCK_Stream. If <remote_sap> is non-NULL then it + * will contain the address of the connected peer. + */ int complete (ACE_ATM_Stream &new_stream, ACE_ATM_Addr *remote_sap, ACE_Time_Value *tv); - // Try to complete a non-blocking connection. - // If connection completion is successful then <new_stream> contains - // the connected ACE_SOCK_Stream. If <remote_sap> is non-NULL then it - // will contain the address of the connected peer. //int add_leaf (ACE_ATM_Stream ¤t_stream, // const ACE_Addr &remote_sap, // ACE_INT32 leaf_id, // ACE_Time_Value *timeout = 0); + + /** + * Actively add a leaf to the root (i.e., point-to-multipoint). The + * <remote_sap> is the address of the leaf that we + * are trying to add. + */ int add_leaf (ACE_ATM_Stream ¤t_stream, const ACE_Addr &remote_sap, ACE_ATM_QoS &qos); - // Actively add a leaf to the root (i.e., point-to-multipoint). The - // <remote_sap> is the address of the leaf that we - // are trying to add. + /// Resets any event associations on this handle int reset_new_handle (ACE_HANDLE handle); - // Resets any event associations on this handle // = Meta-type info typedef ACE_ATM_Addr PEER_ADDR; typedef ACE_ATM_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: ATM_Connector connector_; @@ -146,4 +155,3 @@ private: #endif /* ACE_HAS_ATM */ #include "ace/post.h" #endif /* ACE_ATM_CONNECTOR_H */ - diff --git a/ace/ATM_Params.h b/ace/ATM_Params.h index 9c8fb6de383..5544bd3afcd 100644 --- a/ace/ATM_Params.h +++ b/ace/ATM_Params.h @@ -1,17 +1,14 @@ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ATM_Params.h -// -// = AUTHOR -// Joe Hoffert <joeh@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file ATM_Params.h + * + * $Id$ + * + * @author Joe Hoffert <joeh@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_ATM_PARAMS_H #define ACE_ATM_PARAMS_H @@ -49,12 +46,22 @@ typedef int Param_Info; typedef int Param_Udata; #endif /* ACE_HAS_FORE_ATM_XTI || ACE_HAS_FORE_ATM_WS2 || ACE_HAS_LINUX_ATM */ +/** + * @class ACE_ATM_Params + * + * @brief Wrapper class that simplifies the information passed to the ATM + * enabled <ACE_ATM_Connector> class. + */ class ACE_Export ACE_ATM_Params { - // = TITLE - // Wrapper class that simplifies the information passed to the ATM - // enabled <ACE_ATM_Connector> class. public: + /** + * Initialize the data members. This class combines options from + * ACE_SOCK_Connector (<protocol_family>, <protocol>, <type>, + * <protocol_info>, <group>, and <flags>) and + * ACE_TLI_Connector (<device>, <info>, <rw_flag>, <oflag>, and <udata>) + * so that either mechanism can be used transparently for ATM. + */ ACE_ATM_Params (int rw_flag = 1, const char device[] = ACE_XTI_ATM_DEVICE, Param_Info *info = 0, @@ -62,7 +69,7 @@ public: int oflag = O_RDWR, int protocol_family = AF_ATM, int protocol = ATM_PROTOCOL_DEFAULT, - int type = + int type = #if defined (ACE_HAS_LINUX_ATM) SOCK_DGRAM, #else @@ -70,107 +77,102 @@ public: #endif /* ACE_HAS_LINUX_ATM */ ACE_Protocol_Info *protocol_info = 0, ACE_SOCK_GROUP g = 0, - u_long flags - = ACE_FLAG_MULTIPOINT_C_ROOT + u_long flags + = ACE_FLAG_MULTIPOINT_C_ROOT | ACE_FLAG_MULTIPOINT_D_ROOT, // connector by default int reuse_addr = 0); - // Initialize the data members. This class combines options from - // ACE_SOCK_Connector (<protocol_family>, <protocol>, <type>, - // <protocol_info>, <group>, and <flags>) and - // ACE_TLI_Connector (<device>, <info>, <rw_flag>, <oflag>, and <udata>) - // so that either mechanism can be used transparently for ATM. ~ACE_ATM_Params (); + /// Get/set protocol family. int get_protocol_family (void) const; void set_protocol_family (int); - // Get/set protocol family. + /// Get/set protocol. int get_protocol (void) const; void set_protocol (int); - // Get/set protocol. + /// Get/set type. int get_type (void) const; void set_type (int); - // Get/set type. + /// Get/set protocol info. ACE_Protocol_Info *get_protocol_info( void ); void set_protocol_info( ACE_Protocol_Info *); - // Get/set protocol info. + /// Get/set socket group. ACE_SOCK_GROUP get_sock_group( void ); void set_sock_group( ACE_SOCK_GROUP ); - // Get/set socket group. + /// Get/set socket flags. u_long get_flags( void ); void set_flags( u_long ); - // Get/set socket flags. + /// Get/set reuse_addr flag. int get_reuse_addr (void) const; void set_reuse_addr (int); - // Get/set reuse_addr flag. + /// Get device. const char* get_device (void) const; - // Get device. + /// Get/set info. Param_Info* get_info (void) const; void set_info (Param_Info *); - // Get/set info. + /// Get/set r/w flag. int get_rw_flag (void) const; void set_rw_flag (int); - // Get/set r/w flag. + /// Get/set user data. Param_Udata* get_user_data (void) const; void set_user_data (Param_Udata*); - // Get/set user data. + /// /set open flag. int get_oflag (void) const; void set_oflag (int); - // /set open flag. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Protocol family for sockets connections. int protocol_family_; - // Protocol family for sockets connections. + /// Protocol for sockets connections. int protocol_; - // Protocol for sockets connections. + /// Type for opening sockets. int type_; - // Type for opening sockets. + /// Information about the protocol. ACE_Protocol_Info *protocol_info_; - // Information about the protocol. + /// Socket group used (for sockets only). ACE_SOCK_GROUP group_; - // Socket group used (for sockets only). + /// Flags for sockets (for sockets only). u_long flags_; - // Flags for sockets (for sockets only). + /// Flag for reusing address for opening sockets. int reuse_addr_; - // Flag for reusing address for opening sockets. + /// Device name for XTI/ATM connections. const char *device_; - // Device name for XTI/ATM connections. + /// Info for XTI/ATM connections. Param_Info *info_; - // Info for XTI/ATM connections. + /// R/W flag for XTI/ATM connections. int rw_flag_; - // R/W flag for XTI/ATM connections. + /// User data for XTI/ATM connections. Param_Udata *udata_; - // User data for XTI/ATM connections. + /// Open flag for XTI/ATM connections. int oflag_; - // Open flag for XTI/ATM connections. }; #if defined (__ACE_INLINE__) @@ -180,4 +182,3 @@ private: #endif /* ACE_HAS_ATM */ #include "ace/post.h" #endif /* ACE_ATM_PARAMS_H */ - diff --git a/ace/ATM_QoS.h b/ace/ATM_QoS.h index 95a8831ec46..2b94534a8b1 100644 --- a/ace/ATM_QoS.h +++ b/ace/ATM_QoS.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ATM_QoS.h -// -// = AUTHOR -// Joe Hoffert -// -// ============================================================================ + +//============================================================================= +/** + * @file ATM_QoS.h + * + * $Id$ + * + * @author Joe Hoffert + */ +//============================================================================= + #ifndef ACE_ATM_QoS_H #define ACE_ATM_QoS_H @@ -39,15 +36,17 @@ typedef struct atm_qos ATM_QoS; typedef int ATM_QoS; #endif /* ACE_HAS_FORE_ATM_WS2 || ACE_HAS_FORE_ATM_XTI || ACE_HAS_LINUX_ATM */ +/** + * @class ACE_ATM_QoS + * + * @brief Define the QoS parameters for ATM + * + * This class wraps up QoS parameters for both ATM/XTI and + * ATM/WinSock2 to make the mechanism for the ATM protocol + * transparent. + */ class ACE_Export ACE_ATM_QoS { - // = TITLE - // Define the QoS parameters for ATM - // - // = DESCRIPTION - // This class wraps up QoS parameters for both ATM/XTI and - // ATM/WinSock2 to make the mechanism for the ATM protocol - // transparent. public: // Constants used for ATM options static const long LINE_RATE; @@ -57,39 +56,39 @@ public: static const int DEFAULT_PKT_SIZE; // = Initializattion and termination methods. + /// Default constructor. ACE_ATM_QoS(int = DEFAULT_PKT_SIZE); - // Default constructor. + /// Constructor with a CBR rate. ACE_ATM_QoS(int, int = DEFAULT_PKT_SIZE); - // Constructor with a CBR rate. ~ACE_ATM_QoS (); + /// Set the rate. void set_rate (ACE_HANDLE, int, int); - // Set the rate. + /// Set CBR rate in cells per second. void set_cbr_rate (int, int = DEFAULT_PKT_SIZE); - // Set CBR rate in cells per second. + /// Get ATM_QoS struct. ATM_QoS get_qos (void); - // Get ATM_QoS struct. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Construct QoS options. char* construct_options(ACE_HANDLE, int, int, long*); - // Construct QoS options. private: ATM_QoS qos_; @@ -102,4 +101,3 @@ private: #endif /* ACE_HAS_ATM */ #include "ace/post.h" #endif /* ACE_ATM_QoS_H */ - diff --git a/ace/ATM_Stream.h b/ace/ATM_Stream.h index 85efd040c86..f9dd3741f96 100644 --- a/ace/ATM_Stream.h +++ b/ace/ATM_Stream.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ATM_Stream.h -// -// = AUTHOR -// Joe Hoffert -// -// ============================================================================ + +//============================================================================= +/** + * @file ATM_Stream.h + * + * $Id$ + * + * @author Joe Hoffert + */ +//============================================================================= + #ifndef ACE_ATM_STREAM_H #define ACE_ATM_STREAM_H @@ -35,56 +32,59 @@ typedef ACE_SOCK_Stream ATM_Stream; typedef ACE_TLI_Stream ATM_Stream; #endif +/** + * @class ACE_ATM_Stream + * + * @brief Defines the member functions for ACE_ATM_Stream abstraction. + */ class ACE_Export ACE_ATM_Stream { - // = TITLE - // Defines the member functions for ACE_ATM_Stream abstraction. public: // = Initialization and termination methods. + /// Default constructor. ACE_ATM_Stream (void); - // Default constructor. // = ATM-specific open and shutdown operations. + /// open the stream. + /// Close down and release resources. int open (ACE_ATM_Params params = ACE_ATM_Params()); - // open the stream. int close (void); - // Close down and release resources. + /// Get the underlying handle. ACE_HANDLE get_handle (void) const; - // Get the underlying handle. + /// Get the underlying stream. ATM_Stream& get_stream (void); - // Get the underlying stream. + /// Get the name of the connected host. char* get_peer_name (void) const; - // Get the name of the connected host. + /// Get the VPI and VCI of the stream. int get_vpi_vci (ACE_UINT16 &vpi, ACE_UINT16 &vci) const; - // Get the VPI and VCI of the stream. + /// Recv an n byte buffer from the connected transport mechanism. ssize_t recv (void *buf, size_t n, int *flags = 0) const; - // Recv an n byte buffer from the connected transport mechanism. + /// Send exactly n bytes to the connected transport mechanism. ssize_t send_n (const void *buf, size_t n, int flags) const; - // Send exactly n bytes to the connected transport mechanism. // = Meta-type info typedef ACE_ATM_Addr PEER_ADDR; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Typedef'd to the appropriate stream mechanism above. ATM_Stream stream_; - // Typedef'd to the appropriate stream mechanism above. }; #if defined (__ACE_INLINE__) @@ -94,4 +94,3 @@ private: #endif /* ACE_HAS_ATM */ #include "ace/post.h" #endif /* ACE_ATM_STREAM_H */ - diff --git a/ace/Acceptor.h b/ace/Acceptor.h index f1643d41d15..60e31c49959 100644 --- a/ace/Acceptor.h +++ b/ace/Acceptor.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Acceptor.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Acceptor.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_ACCEPTOR_H #define ACE_ACCEPTOR_H @@ -28,183 +25,205 @@ #include "ace/Svc_Handler.h" #include "ace/Strategies.h" +/** + * @class ACE_Acceptor + * + * @brief Abstract factory for creating a service handler + * (SVC_HANDLER), accepting into the SVC_HANDLER, and + * activating the SVC_HANDLER. + * + * Implements the basic strategy for passively establishing + * connections with clients. An ACE_Acceptor is parameterized + * by concrete types that conform to the interfaces of + * PEER_ACCEPTOR and SVC_HANDLER. The PEER_ACCEPTOR is + * instantiated with a transport mechanism that passively + * establishes connections. The SVC_HANDLER is instantiated + * with a concrete type that performs the application-specific + * service. An ACE_Acceptor inherits from ACE_Service_Object, + * which in turn inherits from ACE_Event_Handler. This enables + * the ACE_Reactor to dispatch the ACE_Acceptor's handle_input + * method when connection events occur. The handle_input method + * performs the ACE_Acceptor's default creation, connection + * establishment, and service activation strategies. These + * strategies can be overridden by subclasses individually or as + * a group. + */ template <class SVC_HANDLER, ACE_PEER_ACCEPTOR_1> class ACE_Acceptor : public ACE_Service_Object { - // = TITLE - // Abstract factory for creating a service handler - // (SVC_HANDLER), accepting into the SVC_HANDLER, and - // activating the SVC_HANDLER. - // - // = DESCRIPTION - // Implements the basic strategy for passively establishing - // connections with clients. An ACE_Acceptor is parameterized - // by concrete types that conform to the interfaces of - // PEER_ACCEPTOR and SVC_HANDLER. The PEER_ACCEPTOR is - // instantiated with a transport mechanism that passively - // establishes connections. The SVC_HANDLER is instantiated - // with a concrete type that performs the application-specific - // service. An ACE_Acceptor inherits from ACE_Service_Object, - // which in turn inherits from ACE_Event_Handler. This enables - // the ACE_Reactor to dispatch the ACE_Acceptor's handle_input - // method when connection events occur. The handle_input method - // performs the ACE_Acceptor's default creation, connection - // establishment, and service activation strategies. These - // strategies can be overridden by subclasses individually or as - // a group. public: // = Initialization and termination methods. + /// "Do-nothing" constructor. ACE_Acceptor (ACE_Reactor * = 0, int use_select = 1); - // "Do-nothing" constructor. + /** + * Initialize and register <this> with the Reactor and listen for + * connection requests at the designated <local_addr>. <flags> + * indicates how <SVC_HANDLER>'s should be initialized prior to + * being activated. Right now, the only flag that is processed is + * <ACE_NONBLOCK>, which enabled non-blocking I/O on the + * <SVC_HANDLER> when it is opened. If <use_select> is non-zero + * then <select> is used to determine when to break out of the + * <accept> loop. <reuse_addr> is passed down to the + * <PEER_ACCEPTOR>. If it is non-zero this will allow the OS to + * reuse this listen port. + */ ACE_Acceptor (const ACE_PEER_ACCEPTOR_ADDR &local_addr, ACE_Reactor * = ACE_Reactor::instance (), int flags = 0, int use_select = 1, int reuse_addr = 1); - // Initialize and register <this> with the Reactor and listen for - // connection requests at the designated <local_addr>. <flags> - // indicates how <SVC_HANDLER>'s should be initialized prior to - // being activated. Right now, the only flag that is processed is - // <ACE_NONBLOCK>, which enabled non-blocking I/O on the - // <SVC_HANDLER> when it is opened. If <use_select> is non-zero - // then <select> is used to determine when to break out of the - // <accept> loop. <reuse_addr> is passed down to the - // <PEER_ACCEPTOR>. If it is non-zero this will allow the OS to - // reuse this listen port. + /** + * Initialize and register <this> with the Reactor and listen for + * connection requests at the designated <local_addr>. <flags> + * indicates how <SVC_HANDLER>'s should be initialized prior to + * being activated. Right now, the only flag that is processed is + * <ACE_NONBLOCK>, which enabled non-blocking I/O on the + * <SVC_HANDLER> when it is opened. If <use_select> is non-zero + * then <select> is used to determine when to break out of the + * <accept> loop. <reuse_addr> is passed down to the + * <PEER_ACCEPTOR>. If it is non-zero this will allow the OS to + * reuse this listen port. + */ int open (const ACE_PEER_ACCEPTOR_ADDR &, ACE_Reactor * = ACE_Reactor::instance (), int flags = 0, int use_select = 1, int reuse_addr = 1); - // Initialize and register <this> with the Reactor and listen for - // connection requests at the designated <local_addr>. <flags> - // indicates how <SVC_HANDLER>'s should be initialized prior to - // being activated. Right now, the only flag that is processed is - // <ACE_NONBLOCK>, which enabled non-blocking I/O on the - // <SVC_HANDLER> when it is opened. If <use_select> is non-zero - // then <select> is used to determine when to break out of the - // <accept> loop. <reuse_addr> is passed down to the - // <PEER_ACCEPTOR>. If it is non-zero this will allow the OS to - // reuse this listen port. + /// Close down the Acceptor's resources. virtual ~ACE_Acceptor (void); - // Close down the Acceptor's resources. + /// Return the underlying PEER_ACCEPTOR object. virtual operator ACE_PEER_ACCEPTOR &() const; - // Return the underlying PEER_ACCEPTOR object. + /// Return the underlying PEER_ACCEPTOR object. virtual ACE_PEER_ACCEPTOR &acceptor (void) const; - // Return the underlying PEER_ACCEPTOR object. + /// Returns the listening acceptor's <ACE_HANDLE>. virtual ACE_HANDLE get_handle (void) const; - // Returns the listening acceptor's <ACE_HANDLE>. + /// Close down the Acceptor virtual int close (void); - // Close down the Acceptor + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = The following three methods define the Acceptor's strategies // for creating, accepting, and activating SVC_HANDLER's, // respectively. + /** + * Bridge method for creating a SVC_HANDLER. The default is to + * create a new <SVC_HANDLER> if <sh> == 0, else <sh> is unchanged. + * However, subclasses can override this policy to perform + * SVC_HANDLER creation in any way that they like (such as creating + * subclass instances of SVC_HANDLER, using a singleton, dynamically + * linking the handler, etc.). Returns -1 on failure, else 0. + */ virtual int make_svc_handler (SVC_HANDLER *&sh); - // Bridge method for creating a SVC_HANDLER. The default is to - // create a new <SVC_HANDLER> if <sh> == 0, else <sh> is unchanged. - // However, subclasses can override this policy to perform - // SVC_HANDLER creation in any way that they like (such as creating - // subclass instances of SVC_HANDLER, using a singleton, dynamically - // linking the handler, etc.). Returns -1 on failure, else 0. + /** + * Bridge method for accepting the new connection into the + * <svc_handler>. The default behavior delegates to the + * PEER_ACCEPTOR::accept. + */ virtual int accept_svc_handler (SVC_HANDLER *svc_handler); - // Bridge method for accepting the new connection into the - // <svc_handler>. The default behavior delegates to the - // PEER_ACCEPTOR::accept. + /** + * Bridge method for activating a <svc_handler> with the appropriate + * concurrency strategy. The default behavior of this method is to + * activate the SVC_HANDLER by calling its <open> method (which + * allows the SVC_HANDLER to define its own concurrency strategy). + * However, subclasses can override this strategy to do more + * sophisticated concurrency activations (such as making the + * SVC_HANDLER as an "active object" via multi-threading or + * multi-processing). + */ virtual int activate_svc_handler (SVC_HANDLER *svc_handler); - // Bridge method for activating a <svc_handler> with the appropriate - // concurrency strategy. The default behavior of this method is to - // activate the SVC_HANDLER by calling its <open> method (which - // allows the SVC_HANDLER to define its own concurrency strategy). - // However, subclasses can override this strategy to do more - // sophisticated concurrency activations (such as making the - // SVC_HANDLER as an "active object" via multi-threading or - // multi-processing). // = Demultiplexing hooks. + /// Perform termination activities when <this> is removed from the + /// <reactor>. virtual int handle_close (ACE_HANDLE = ACE_INVALID_HANDLE, ACE_Reactor_Mask = ACE_Event_Handler::ALL_EVENTS_MASK); - // Perform termination activities when <this> is removed from the - // <reactor>. + /// Accepts all pending connections from clients, and creates and + /// activates SVC_HANDLERs. virtual int handle_input (ACE_HANDLE); - // Accepts all pending connections from clients, and creates and - // activates SVC_HANDLERs. // = Dynamic linking hooks. + /// Default version does no work and returns -1. Must be overloaded + /// by application developer to do anything meaningful. virtual int init (int argc, ACE_TCHAR *argv[]); - // Default version does no work and returns -1. Must be overloaded - // by application developer to do anything meaningful. + /// Calls <handle_close>. virtual int fini (void); - // Calls <handle_close>. + /// Default version returns address info in <buf>. virtual int info (ACE_TCHAR **buf, size_t) const; - // Default version returns address info in <buf>. public: // = Service management hooks. + /// This method calls <Reactor::suspend>. virtual int suspend (void); - // This method calls <Reactor::suspend>. + /// This method calls <Reactor::resume>. virtual int resume (void); - // This method calls <Reactor::resume>. protected: + /// Concrete factory for accepting connections from clients... ACE_PEER_ACCEPTOR peer_acceptor_; - // Concrete factory for accepting connections from clients... + /** + * Flags that indicate how <SVC_HANDLER>'s should be initialized + * prior to being activated. Right now, the only flag that is + * processed is <ACE_NONBLOCK>, which enabled non-blocking I/O on + * the <SVC_HANDLER> when it is opened. + */ int flags_; - // Flags that indicate how <SVC_HANDLER>'s should be initialized - // prior to being activated. Right now, the only flag that is - // processed is <ACE_NONBLOCK>, which enabled non-blocking I/O on - // the <SVC_HANDLER> when it is opened. + /// Flag that indicates whether it shall use <select> in the + /// <accept>-loop. int use_select_; - // Flag that indicates whether it shall use <select> in the - // <accept>-loop. }; +/** + * @class ACE_Strategy_Acceptor + * + * @brief Abstract factory for creating a service handler + * (SVC_HANDLER), accepting into the SVC_HANDLER, and activating + * the SVC_HANDLER. + * + * Implements a flexible and extensible set of strategies for + * passively establishing connections with clients. There are + * three main strategies: (1) creating a SVC_HANDLER, (2) + * passively accepting a new connection from a client into the + * SVC_HANDLER, and (3) activating the SVC_HANDLER with a + * particular concurrency mechanism. + */ template <class SVC_HANDLER, ACE_PEER_ACCEPTOR_1> class ACE_Strategy_Acceptor : public ACE_Acceptor <SVC_HANDLER, ACE_PEER_ACCEPTOR_2> { - // = TITLE - // Abstract factory for creating a service handler - // (SVC_HANDLER), accepting into the SVC_HANDLER, and activating - // the SVC_HANDLER. - // - // = DESCRIPTION - // Implements a flexible and extensible set of strategies for - // passively establishing connections with clients. There are - // three main strategies: (1) creating a SVC_HANDLER, (2) - // passively accepting a new connection from a client into the - // SVC_HANDLER, and (3) activating the SVC_HANDLER with a - // particular concurrency mechanism. public: // = Initialization and termination methods. + /// Default constructor. ACE_Strategy_Acceptor (const ACE_TCHAR service_name[] = 0, const ACE_TCHAR service_description[] = 0, int use_select = 1); - // Default constructor. + /** + * Initialize the appropriate strategies for creation, passive + * connection acceptance, and concurrency, and then register <this> + * with the Reactor and listen for connection requests at the + * designated <local_addr>. + */ ACE_Strategy_Acceptor (const ACE_PEER_ACCEPTOR_ADDR &local_addr, ACE_Reactor * = ACE_Reactor::instance (), ACE_Creation_Strategy<SVC_HANDLER> * = 0, @@ -214,11 +233,13 @@ public: const ACE_TCHAR service_name[] = 0, const ACE_TCHAR service_description[] = 0, int use_select = 1); - // Initialize the appropriate strategies for creation, passive - // connection acceptance, and concurrency, and then register <this> - // with the Reactor and listen for connection requests at the - // designated <local_addr>. + /** + * Initialize the appropriate strategies for creation, passive + * connection acceptance, and concurrency, and then register <this> + * with the Reactor and listen for connection requests at the + * designated <local_addr>. + */ int open (const ACE_PEER_ACCEPTOR_ADDR &, ACE_Reactor * = ACE_Reactor::instance (), ACE_Creation_Strategy<SVC_HANDLER> * = 0, @@ -228,83 +249,85 @@ public: const ACE_TCHAR *service_name = 0, const ACE_TCHAR *service_description = 0, int use_select = 1); - // Initialize the appropriate strategies for creation, passive - // connection acceptance, and concurrency, and then register <this> - // with the Reactor and listen for connection requests at the - // designated <local_addr>. + /// Close down the Strategy_Acceptor's resources. virtual ~ACE_Strategy_Acceptor (void); - // Close down the Strategy_Acceptor's resources. + /// Return the underlying PEER_ACCEPTOR object. virtual operator ACE_PEER_ACCEPTOR &() const; - // Return the underlying PEER_ACCEPTOR object. + /// Return the underlying PEER_ACCEPTOR object. virtual ACE_PEER_ACCEPTOR &acceptor (void) const; - // Return the underlying PEER_ACCEPTOR object. + /// Returns the listening acceptor's <ACE_HANDLE>. virtual ACE_HANDLE get_handle (void) const; - // Returns the listening acceptor's <ACE_HANDLE>. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Service management hooks. + /// This method delegates to the <Scheduling_Strategy>'s <suspend> + /// method. virtual int suspend (void); - // This method delegates to the <Scheduling_Strategy>'s <suspend> - // method. + /// This method delegates to the <Scheduling_Strategy>'s <resume> + /// method. virtual int resume (void); - // This method delegates to the <Scheduling_Strategy>'s <resume> - // method. + /// Calls <handle_close> when dynamically unlinked. virtual int fini (void); - // Calls <handle_close> when dynamically unlinked. + /// Default version returns address info in <buf>. virtual int info (ACE_TCHAR **buf, size_t) const; - // Default version returns address info in <buf>. // = The following three methods define the <Acceptor>'s strategies // for creating, accepting, and activating <SVC_HANDLER>'s, // respectively. + /** + * Bridge method for creating a <SVC_HANDLER>. The strategy for + * creating a <SVC_HANDLER> are configured into the Acceptor via + * it's <creation_strategy_>. The default is to create a new + * <SVC_HANDLER> if <sh> == 0, else <sh> is unchanged. However, + * subclasses can override this policy to perform <SVC_HANDLER> + * creation in any way that they like (such as creating subclass + * instances of <SVC_HANDLER>, using a singleton, dynamically + * linking the handler, etc.). Returns -1 on failure, else 0. + */ virtual int make_svc_handler (SVC_HANDLER *&); - // Bridge method for creating a <SVC_HANDLER>. The strategy for - // creating a <SVC_HANDLER> are configured into the Acceptor via - // it's <creation_strategy_>. The default is to create a new - // <SVC_HANDLER> if <sh> == 0, else <sh> is unchanged. However, - // subclasses can override this policy to perform <SVC_HANDLER> - // creation in any way that they like (such as creating subclass - // instances of <SVC_HANDLER>, using a singleton, dynamically - // linking the handler, etc.). Returns -1 on failure, else 0. + /** + * Bridge method for accepting the new connection into the + * <SVC_HANDLER>. The default behavior delegates to the + * <PEER_ACCEPTOR::accept> in the <Acceptor_Strategy>. + */ virtual int accept_svc_handler (SVC_HANDLER *svc_handler); - // Bridge method for accepting the new connection into the - // <SVC_HANDLER>. The default behavior delegates to the - // <PEER_ACCEPTOR::accept> in the <Acceptor_Strategy>. + /** + * Bridge method for activating a <SVC_HANDLER> with the appropriate + * concurrency strategy. The default behavior of this method is to + * activate the <SVC_HANDLER> by calling its <open> method (which + * allows the <SVC_HANDLER> to define its own concurrency strategy). + * However, subclasses can override this strategy to do more + * sophisticated concurrency activations (such as creating the + * <SVC_HANDLER> as an "active object" via multi-threading or + * multi-processing). + */ virtual int activate_svc_handler (SVC_HANDLER *svc_handler); - // Bridge method for activating a <SVC_HANDLER> with the appropriate - // concurrency strategy. The default behavior of this method is to - // activate the <SVC_HANDLER> by calling its <open> method (which - // allows the <SVC_HANDLER> to define its own concurrency strategy). - // However, subclasses can override this strategy to do more - // sophisticated concurrency activations (such as creating the - // <SVC_HANDLER> as an "active object" via multi-threading or - // multi-processing). // = Demultiplexing hooks. + /// Perform termination activities when <this> is removed from the + /// <Reactor>. virtual int handle_close (ACE_HANDLE = ACE_INVALID_HANDLE, ACE_Reactor_Mask = ACE_Event_Handler::ALL_EVENTS_MASK); - // Perform termination activities when <this> is removed from the - // <Reactor>. + /// Handle SIGINT. virtual int handle_signal (int signum, siginfo_t *, ucontext_t *); - // Handle SIGINT. // = These data members are "logically private" but are put in the // protected part in case subclasses want to access them. @@ -317,206 +340,214 @@ protected: // = Strategy objects. + /// Creation strategy for an Acceptor. CREATION_STRATEGY *creation_strategy_; - // Creation strategy for an Acceptor. + /// 1 if <Acceptor> created the creation strategy and thus should + /// delete it, else 0. int delete_creation_strategy_; - // 1 if <Acceptor> created the creation strategy and thus should - // delete it, else 0. + /// Accept strategy for an <Acceptor>. ACCEPT_STRATEGY *accept_strategy_; - // Accept strategy for an <Acceptor>. + /// 1 if <Acceptor> created the accept strategy and thus should delete + /// it, else 0. int delete_accept_strategy_; - // 1 if <Acceptor> created the accept strategy and thus should delete - // it, else 0. + /// Concurrency strategy for an <Acceptor>. CONCURRENCY_STRATEGY *concurrency_strategy_; - // Concurrency strategy for an <Acceptor>. + /// 1 if <Acceptor> created the concurrency strategy and thus should + /// delete it, else 0. int delete_concurrency_strategy_; - // 1 if <Acceptor> created the concurrency strategy and thus should - // delete it, else 0. + /// Scheduling strategy for an <Acceptor>. SCHEDULING_STRATEGY *scheduling_strategy_; - // Scheduling strategy for an <Acceptor>. + /// 1 if <Acceptor> created the scheduling strategy and thus should + /// delete it, else 0. int delete_scheduling_strategy_; - // 1 if <Acceptor> created the scheduling strategy and thus should - // delete it, else 0. // = Service information objects. + /// Name of the service. ACE_TCHAR *service_name_; - // Name of the service. + /// Description of the service. ACE_TCHAR *service_description_; - // Description of the service. + /// Port number for the server. u_short service_port_; - // Port number for the server. + /// Address that the <Strategy_Acceptor> uses to listen for + /// connections. ACE_PEER_ACCEPTOR_ADDR service_addr_; - // Address that the <Strategy_Acceptor> uses to listen for - // connections. }; +/** + * @class ACE_Oneshot_Acceptor + * + * @brief Generic factory for passively connecting clients and creating + * exactly one service handler (SVC_HANDLER). + * + * This class works similarly to the regular <ACE_Acceptor>, + * with the following differences: + * 1. This class doesn't automagically register <this> with the + * <ACE_Reactor> since it expects to have its <accept> method + * called directly. However, it stashes the <ACE_Reactor> + * pointer away in case it's needed later to finish accepting + * a connection asynchronously. + * 2. The class doesn't need an <ACE_Creation_Strategy> (since + * the user supplies the SVC_HANDLER) or an + * <ACE_Accept_Strategy> (since this class only accepts one + * connection and then removes all traces of itself from the + * <ACE_Reactor> if it was registered for asynchronous + * accepts). + */ template <class SVC_HANDLER, ACE_PEER_ACCEPTOR_1> class ACE_Oneshot_Acceptor : public ACE_Service_Object { - // = TITLE - // Generic factory for passively connecting clients and creating - // exactly one service handler (SVC_HANDLER). - // - // = DESCRIPTION - // This class works similarly to the regular <ACE_Acceptor>, - // with the following differences: - // - // 1. This class doesn't automagically register <this> with the - // <ACE_Reactor> since it expects to have its <accept> method - // called directly. However, it stashes the <ACE_Reactor> - // pointer away in case it's needed later to finish accepting - // a connection asynchronously. - // - // 2. The class doesn't need an <ACE_Creation_Strategy> (since - // the user supplies the SVC_HANDLER) or an - // <ACE_Accept_Strategy> (since this class only accepts one - // connection and then removes all traces of itself from the - // <ACE_Reactor> if it was registered for asynchronous - // accepts). public: // = Initialization and termination methods. + /// Constructor. ACE_Oneshot_Acceptor (void); - // Constructor. + /** + * Initialize the appropriate strategies for concurrency and then + * open the <peer_acceptor> at the designated <local_addr>. Note + * that unlike the <ACE_Acceptor> and <ACE_Strategy_Acceptor>, this + * method does NOT register <this> acceptor with the <reactor> at + * this point -- it just stashes the <reactor> away in case it's + * needed later. + */ ACE_Oneshot_Acceptor (const ACE_PEER_ACCEPTOR_ADDR &local_addr, ACE_Reactor *reactor = ACE_Reactor::instance (), ACE_Concurrency_Strategy<SVC_HANDLER> * = 0); - // Initialize the appropriate strategies for concurrency and then - // open the <peer_acceptor> at the designated <local_addr>. Note - // that unlike the <ACE_Acceptor> and <ACE_Strategy_Acceptor>, this - // method does NOT register <this> acceptor with the <reactor> at - // this point -- it just stashes the <reactor> away in case it's - // needed later. + /** + * Initialize the appropriate strategies for concurrency and then + * open the <peer_acceptor> at the designated <local_addr>. Note + * that unlike the <ACE_Acceptor> and <ACE_Strategy_Acceptor>, this + * method does NOT register <this> acceptor with the <reactor> at + * this point -- it just stashes the <reactor> away in case it's + * needed later. + */ int open (const ACE_PEER_ACCEPTOR_ADDR &, ACE_Reactor *reactor = ACE_Reactor::instance (), ACE_Concurrency_Strategy<SVC_HANDLER> * = 0); - // Initialize the appropriate strategies for concurrency and then - // open the <peer_acceptor> at the designated <local_addr>. Note - // that unlike the <ACE_Acceptor> and <ACE_Strategy_Acceptor>, this - // method does NOT register <this> acceptor with the <reactor> at - // this point -- it just stashes the <reactor> away in case it's - // needed later. + /// Close down the <Oneshot_Acceptor>. virtual ~ACE_Oneshot_Acceptor (void); - // Close down the <Oneshot_Acceptor>. // = Explicit factory operation. + /// Create a <SVC_HANDLER>, accept the connection into the + /// <SVC_HANDLER>, and activate the <SVC_HANDLER>. virtual int accept (SVC_HANDLER * = 0, ACE_PEER_ACCEPTOR_ADDR *remote_addr = 0, const ACE_Synch_Options &synch_options = ACE_Synch_Options::defaults, int restart = 1, int reset_new_handle = 0); - // Create a <SVC_HANDLER>, accept the connection into the - // <SVC_HANDLER>, and activate the <SVC_HANDLER>. + /// Cancel a oneshot acceptor that was started asynchronously. virtual int cancel (void); - // Cancel a oneshot acceptor that was started asynchronously. + /// Return the underlying <PEER_ACCEPTOR> object. virtual operator ACE_PEER_ACCEPTOR &() const; - // Return the underlying <PEER_ACCEPTOR> object. + /// Return the underlying <PEER_ACCEPTOR> object. virtual ACE_PEER_ACCEPTOR &acceptor (void) const; - // Return the underlying <PEER_ACCEPTOR> object. + /// Close down the <Oneshot_Acceptor>. virtual int close (void); - // Close down the <Oneshot_Acceptor>. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /** + * Bridge method for activating a <svc_handler> with the appropriate + * concurrency strategy. Default behavior is to activate the + * <SVC_HANDLER> as a "passive object." However, subclasses can + * override this strategy to do more sophisticated concurrency + * activations (such as creating the <SVC_HANDLER> as an "active + * object" via multi-threading or multi-processing). + */ virtual int activate_svc_handler (SVC_HANDLER *svc_handler); - // Bridge method for activating a <svc_handler> with the appropriate - // concurrency strategy. Default behavior is to activate the - // <SVC_HANDLER> as a "passive object." However, subclasses can - // override this strategy to do more sophisticated concurrency - // activations (such as creating the <SVC_HANDLER> as an "active - // object" via multi-threading or multi-processing). + /// Factors out the code shared between the <accept> and + /// <handle_input> methods. int shared_accept (SVC_HANDLER *svc_handler, ACE_PEER_ACCEPTOR_ADDR *remote_addr, ACE_Time_Value *timeout, int restart, int reset_new_handle); - // Factors out the code shared between the <accept> and - // <handle_input> methods. // = Demultiplexing hooks. + /// Returns the listening acceptor's <ACE_HANDLE>. virtual ACE_HANDLE get_handle (void) const; - // Returns the listening acceptor's <ACE_HANDLE>. + /// Perform termination activities when <this> is removed from the + /// <reactor>. virtual int handle_close (ACE_HANDLE = ACE_INVALID_HANDLE, ACE_Reactor_Mask = ACE_Event_Handler::ALL_EVENTS_MASK); - // Perform termination activities when <this> is removed from the - // <reactor>. + /// Accept one connection from a client and activates the + /// SVC_HANDLER. virtual int handle_input (ACE_HANDLE); - // Accept one connection from a client and activates the - // SVC_HANDLER. + /// Called when an acceptor times out... virtual int handle_timeout (const ACE_Time_Value &tv, const void *arg); - // Called when an acceptor times out... // = Dynamic linking hooks. + /// Default version does no work and returns -1. Must be overloaded + /// by application developer to do anything meaningful. virtual int init (int argc, ACE_TCHAR *argv[]); - // Default version does no work and returns -1. Must be overloaded - // by application developer to do anything meaningful. + /// Default version does no work and returns -1. Must be overloaded + /// by application developer to do anything meaningful. virtual int fini (void); - // Default version does no work and returns -1. Must be overloaded - // by application developer to do anything meaningful. + /// Default version returns address info in <buf>. virtual int info (ACE_TCHAR **, size_t) const; - // Default version returns address info in <buf>. // = Service management hooks. + /// Default version does no work and returns -1. Must be overloaded + /// by application developer to do anything meaningful. virtual int suspend (void); - // Default version does no work and returns -1. Must be overloaded - // by application developer to do anything meaningful. + /// Default version does no work and returns -1. Must be overloaded + /// by application developer to do anything meaningful. virtual int resume (void); - // Default version does no work and returns -1. Must be overloaded - // by application developer to do anything meaningful. private: + /** + * Insert ourselves into the <ACE_Reactor> so that we can continue + * accepting this connection asynchronously. This method should NOT + * be called by developers directly. + */ int register_handler (SVC_HANDLER *svc_handler, const ACE_Synch_Options &options, int restart); - // Insert ourselves into the <ACE_Reactor> so that we can continue - // accepting this connection asynchronously. This method should NOT - // be called by developers directly. + /// Hold the svc_handler_ across asynchrony boundaries. SVC_HANDLER *svc_handler_; - // Hold the svc_handler_ across asynchrony boundaries. + /// Hold the restart flag across asynchrony boundaries. int restart_; - // Hold the restart flag across asynchrony boundaries. + /// Factory that establishes connections passively. ACE_PEER_ACCEPTOR peer_acceptor_; - // Factory that establishes connections passively. + /// Concurrency strategy for an Acceptor. ACE_Concurrency_Strategy<SVC_HANDLER> *concurrency_strategy_; - // Concurrency strategy for an Acceptor. + /// 1 if Acceptor created the concurrency strategy and thus should + /// delete it, else 0. int delete_concurrency_strategy_; - // 1 if Acceptor created the concurrency strategy and thus should - // delete it, else 0. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/Activation_Queue.h b/ace/Activation_Queue.h index 3ad3ac04b0d..1e988753808 100644 --- a/ace/Activation_Queue.h +++ b/ace/Activation_Queue.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Activation_Queue.h -// -// = AUTHOR -// Andres Kruse <Andres.Kruse@cern.ch> and Douglas C. Schmidt -// <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Activation_Queue.h + * + * $Id$ + * + * @author Andres Kruse <Andres.Kruse@cern.ch> + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_ACTIVATION_QUEUE_H #define ACE_ACTIVATION_QUEUE_H @@ -29,25 +26,27 @@ #include "ace/Method_Request.h" // Be compatible with the terminology in the POSA2 book! -#define ACE_Activation_List ACE_Activation_Queue - +#define ACE_Activation_List ACE_Activation_Queue + +/** + * @class ACE_Activation_Queue + * + * @brief Reifies a method into a request. Subclasses typically + * represent necessary state and behavior. + * + * A <Method_Request> is inserted in the <Activation_Queue>, + * where it is subsequently removed by the <Scheduler>, which + * invokes its <call> method.. + */ class ACE_Export ACE_Activation_Queue { - // = TITLE - // Reifies a method into a request. Subclasses typically - // represent necessary state and behavior. - // - // = DESCRIPTION - // A <Method_Request> is inserted in the <Activation_Queue>, - // where it is subsequently removed by the <Scheduler>, which - // invokes its <call> method.. public: // = Initialization and termination methods. + /// Constructor. ACE_Activation_Queue (ACE_Message_Queue<ACE_SYNCH> *new_queue = 0); - // Constructor. + /// Destructor. virtual ~ACE_Activation_Queue (void); - // Destructor. // = Activate Queue operations. @@ -58,35 +57,35 @@ public: // or if the time specified in timeout elapses, (in which case errno // = EWOULDBLOCK). + /// Dequeue the next available <Method_Request>. ACE_Method_Request *dequeue (ACE_Time_Value *tv = 0); - // Dequeue the next available <Method_Request>. + /// Enqueue the <Method_Request> in priority order. The priority is + /// determined by the <priority> method of the <new_message_request>. int enqueue (ACE_Method_Request *new_method_request, ACE_Time_Value *tv = 0); - // Enqueue the <Method_Request> in priority order. The priority is - // determined by the <priority> method of the <new_message_request>. + /// Get the current number of method objects in the queue. int method_count (void) const; - // Get the current number of method objects in the queue. + /// Returns 1 if the queue is empty, 0 otherwise. int is_empty (void) const; - // Returns 1 if the queue is empty, 0 otherwise. + /// Returns 1 if the queue is full, 0 otherwise. int is_full (void) const; - // Returns 1 if the queue is full, 0 otherwise. + /// Dump the state of an request. void dump (void) const; - // Dump the state of an request. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Stores the <Method_Requests>. ACE_Message_Queue<ACE_SYNCH> *queue_; - // Stores the <Method_Requests>. + /// Keeps track of whether we need to delete the queue. int delete_queue_; - // Keeps track of whether we need to delete the queue. }; #if defined (__ACE_INLINE__) @@ -95,4 +94,3 @@ protected: #include "ace/post.h" #endif /* ACE_ACTIVATION_QUEUE_H */ - diff --git a/ace/Active_Map_Manager.h b/ace/Active_Map_Manager.h index 7395cf68f9d..1911e6c7e2e 100644 --- a/ace/Active_Map_Manager.h +++ b/ace/Active_Map_Manager.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Active_Map_Manager.h -// -// = AUTHOR -// Irfan Pyarali -// -// ============================================================================ + +//============================================================================= +/** + * @file Active_Map_Manager.h + * + * $Id$ + * + * @author Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_ACTIVE_MAP_MANAGER_H #define ACE_ACTIVE_MAP_MANAGER_H @@ -24,74 +21,78 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Active_Map_Manager_Key + * + * @brief Key used in the Active Object Map. + * + * This key keeps information of the index and the generation + * count of the slot it represents. Since the index information + * is part of the key, lookups are super fast and predictable, + */ class ACE_Export ACE_Active_Map_Manager_Key { - // = TITLE - // Key used in the Active Object Map. - // - // = DESCRIPTION - // This key keeps information of the index and the generation - // count of the slot it represents. Since the index information - // is part of the key, lookups are super fast and predictable, public: + /// Default constructor. ACE_Active_Map_Manager_Key (void); - // Default constructor. + /** + * Constructor given the <slot_index> and <slot_generation> number. + * This is useful once the user has somehow recovered the + * <slot_index> and <slot_generation> number from the client. + */ ACE_Active_Map_Manager_Key (ACE_UINT32 slot_index, ACE_UINT32 slot_generation); - // Constructor given the <slot_index> and <slot_generation> number. - // This is useful once the user has somehow recovered the - // <slot_index> and <slot_generation> number from the client. + /// Get/Set the <slot_index>. ACE_UINT32 slot_index (void) const; void slot_index (ACE_UINT32 i); - // Get/Set the <slot_index>. + /// Get/Set the <slot_generation> number. ACE_UINT32 slot_generation (void) const; void slot_generation (ACE_UINT32 g); - // Get/Set the <slot_generation> number. + /// Size required to store information about active key. static size_t size (void); - // Size required to store information about active key. + /// Recover state of active key from <data>. User must make sure + /// that <data> encoded using the <encode> method. void decode (const void *data); - // Recover state of active key from <data>. User must make sure - // that <data> encoded using the <encode> method. + /// Encode state of the active key into <data>. <data> must be as + /// big as the value returned from <size>. void encode (void *data) const; - // Encode state of the active key into <data>. <data> must be as - // big as the value returned from <size>. + /// Compare keys. int operator== (const ACE_Active_Map_Manager_Key &rhs) const; int operator!= (const ACE_Active_Map_Manager_Key &rhs) const; - // Compare keys. // = This really should be protected but because of template // friends, they are not. + /// Increment the <slot_generation> number. void increment_slot_generation_count (void); - // Increment the <slot_generation> number. private: + /** + * @brief Data for the Active Object Map Key. + * + * This separate structure makes it easier to manage copying + * the index and the generation to and from the user buffer. + * + */ struct key_data { - // = TITLE - // Data for the Active Object Map Key. - // - // = DESCRIPTION - // This separate structure makes it easier to manage copying - // the index and the generation to and from the user buffer. - + /// Slot index in the active map. ACE_UINT32 slot_index_; - // Slot index in the active map. + /// Slot generation number of <slot_index_> slot in the active map. ACE_UINT32 slot_generation_; - // Slot generation number of <slot_index_> slot in the active map. }; + /// Data for the Active Object Map Key. key_data key_data_; - // Data for the Active Object Map Key. }; #if defined (__ACE_INLINE__) diff --git a/ace/Active_Map_Manager_T.h b/ace/Active_Map_Manager_T.h index 860f1168f3a..b91d2fec51a 100644 --- a/ace/Active_Map_Manager_T.h +++ b/ace/Active_Map_Manager_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Active_Map_Manager_T.h -// -// = AUTHOR -// Irfan Pyarali -// -// ============================================================================ + +//============================================================================= +/** + * @file Active_Map_Manager_T.h + * + * $Id$ + * + * @author Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_ACTIVE_MAP_MANAGER_T_H #define ACE_ACTIVE_MAP_MANAGER_T_H @@ -25,16 +22,18 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Active_Map_Manager + * + * @brief Define a map abstraction that associates system generated + * keys with user specified values. + * + * Since the key is system generated, searches are very fast and + * take a constant amount of time. + */ template <class T> class ACE_Active_Map_Manager : public ACE_Map_Manager<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> { - // = TITLE - // Define a map abstraction that associates system generated - // keys with user specified values. - // - // = DESCRIPTION - // Since the key is system generated, searches are very fast and - // take a constant amount of time. public: // = Traits. @@ -50,128 +49,138 @@ public: typedef REVERSE_ITERATOR reverse_iterator; // = Initialization and termination methods. + /// Initialize a <Active_Map_Manager> with the <ACE_DEFAULT_MAP_SIZE>. ACE_Active_Map_Manager (ACE_Allocator *alloc = 0); - // Initialize a <Active_Map_Manager> with the <ACE_DEFAULT_MAP_SIZE>. + /// Initialize a <Active_Map_Manager> with <size> entries. ACE_Active_Map_Manager (size_t size, ACE_Allocator *alloc = 0); - // Initialize a <Active_Map_Manager> with <size> entries. + /// Close down a <Active_Map_Manager> and release dynamically + /// allocated resources. ~ACE_Active_Map_Manager (void); - // Close down a <Active_Map_Manager> and release dynamically - // allocated resources. + /// Initialize a <Active_Map_Manager> with size <length>. int open (size_t length = ACE_DEFAULT_MAP_SIZE, ACE_Allocator *alloc = 0); - // Initialize a <Active_Map_Manager> with size <length>. + /// Close down a <Active_Map_Manager> and release dynamically + /// allocated resources. int close (void); - // Close down a <Active_Map_Manager> and release dynamically - // allocated resources. + /// Add <value> to the map, and the corresponding key produced by the + /// Active_Map_Manager is returned through <key>. int bind (const T &value, ACE_Active_Map_Manager_Key &key); - // Add <value> to the map, and the corresponding key produced by the - // Active_Map_Manager is returned through <key>. + /// Add <value> to the map. The user does not care about the + /// corresponding key produced by the Active_Map_Manager. int bind (const T &value); - // Add <value> to the map. The user does not care about the - // corresponding key produced by the Active_Map_Manager. + /** + * Reserves a slot in the internal structure and returns the key and + * a pointer to the value. User should place their <value> into + * <*internal_value>. This method is useful in reducing the number + * of copies required in some cases. Note that <internal_value> is + * only a temporary pointer and will change when the map resizes. + * Therefore, the user should use the pointer immediately and not + * hold on to it. + */ int bind (ACE_Active_Map_Manager_Key &key, T *&internal_value); - // Reserves a slot in the internal structure and returns the key and - // a pointer to the value. User should place their <value> into - // <*internal_value>. This method is useful in reducing the number - // of copies required in some cases. Note that <internal_value> is - // only a temporary pointer and will change when the map resizes. - // Therefore, the user should use the pointer immediately and not - // hold on to it. + /// Reassociate <key> with <value>. The function fails if <key> is + /// not in the map. int rebind (const ACE_Active_Map_Manager_Key &key, const T &value); - // Reassociate <key> with <value>. The function fails if <key> is - // not in the map. + /** + * Reassociate <key> with <value>, storing the old value into the + * "out" parameter <old_value>. The function fails if <key> is not + * in the map. + */ int rebind (const ACE_Active_Map_Manager_Key &key, const T &value, T &old_value); - // Reassociate <key> with <value>, storing the old value into the - // "out" parameter <old_value>. The function fails if <key> is not - // in the map. + /** + * Reassociate <key> with <value>, storing the old key and value + * into the "out" parameter <old_key> and <old_value>. The function + * fails if <key> is not in the map. + */ int rebind (const ACE_Active_Map_Manager_Key &key, const T &value, ACE_Active_Map_Manager_Key &old_key, T &old_value); - // Reassociate <key> with <value>, storing the old key and value - // into the "out" parameter <old_key> and <old_value>. The function - // fails if <key> is not in the map. + /// Locate <value> associated with <key>. int find (const ACE_Active_Map_Manager_Key &key, T &value) const; - // Locate <value> associated with <key>. + /// Is <key> in the map? int find (const ACE_Active_Map_Manager_Key &key) const; - // Is <key> in the map? + /** + * Locate <value> associated with <key>. The value is returned via + * <internal_value> and hence a copy is saved. Note that + * <internal_value> is only a temporary pointer and will change when + * the map resizes. Therefore, the user should use the pointer + * immediately and not hold on to it. + */ int find (const ACE_Active_Map_Manager_Key &key, T *&internal_value) const; - // Locate <value> associated with <key>. The value is returned via - // <internal_value> and hence a copy is saved. Note that - // <internal_value> is only a temporary pointer and will change when - // the map resizes. Therefore, the user should use the pointer - // immediately and not hold on to it. // Creates a key. User should place their <value> into // <*internal_value>. This method is useful in reducing the number // of copies required in some cases. + /// Remove <key> from the map. int unbind (const ACE_Active_Map_Manager_Key &key); - // Remove <key> from the map. + /// Remove <key> from the map, and return the <value> associated with + /// <key>. int unbind (const ACE_Active_Map_Manager_Key &key, T &value); - // Remove <key> from the map, and return the <value> associated with - // <key>. + /** + * Locate <value> associated with <key>. The value is returned via + * <internal_value> and hence a copy is saved. Note that + * <internal_value> is only a temporary pointer and will change when + * the map resizes or when this slot is reused. Therefore, the user + * should use the pointer immediately and not hold on to it. + */ int unbind (const ACE_Active_Map_Manager_Key &key, T *&internal_value); - // Locate <value> associated with <key>. The value is returned via - // <internal_value> and hence a copy is saved. Note that - // <internal_value> is only a temporary pointer and will change when - // the map resizes or when this slot is reused. Therefore, the user - // should use the pointer immediately and not hold on to it. + /// Return the current size of the map. size_t current_size (void) const; - // Return the current size of the map. + /// Return the total size of the map. size_t total_size (void) const; - // Return the total size of the map. + /// Returns a key that cannot be found in the map. static const ACE_Active_Map_Manager_Key npos (void); - // Returns a key that cannot be found in the map. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL styled iterator factory functions. + /// Return forward iterator. ACE_Map_Iterator<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> begin (void); ACE_Map_Iterator<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> end (void); - // Return forward iterator. + /// Return reverse iterator. ACE_Map_Reverse_Iterator<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> rbegin (void); ACE_Map_Reverse_Iterator<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> rend (void); - // Return reverse iterator. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Private base class typedef ACE_Map_Manager<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> ACE_AMM_BASE; - // Private base class private: diff --git a/ace/Addr.h b/ace/Addr.h index 98802b3aa12..6db4eaa14eb 100644 --- a/ace/Addr.h +++ b/ace/Addr.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Addr.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Addr.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_ADDR_H #define ACE_ADDR_H @@ -24,81 +21,84 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Addr + * + * @brief Defines the base class for the "address family independent" + * address format. + */ class ACE_Export ACE_Addr { - // = TITLE - // Defines the base class for the "address family independent" - // address format. public: // = Initialization and termination methods. + /// Initializes instance variables. ACE_Addr (int type = -1, int size = -1); - // Initializes instance variables. + /// Destructor. virtual ~ACE_Addr (void); - // Destructor. // = Get/set the size of the address. + /// Return the size of the address. int get_size (void) const; - // Return the size of the address. + /// Sets the size of the address. void set_size (int size); - // Sets the size of the address. // = Get/set the type of the address. + /// Get the type of the address. int get_type (void) const; - // Get the type of the address. + /// Set the type of the address. void set_type (int type); - // Set the type of the address. + /// Return a pointer to the address. virtual void *get_addr (void) const; - // Return a pointer to the address. + /// Set a pointer to the address. virtual void set_addr (void *, int len); - // Set a pointer to the address. // = Equality/inequality tests + /// Check for address equality. int operator == (const ACE_Addr &sap) const; - // Check for address equality. + /// Check for address inequality. int operator != (const ACE_Addr &sap) const; - // Check for address inequality. + /// Initializes instance variables. void base_set (int type, int size); - // Initializes instance variables. #if defined (ACE_HAS_BROKEN_SAP_ANY) + /// Wild-card address. static const ACE_Addr &sap_any (void); - // Wild-card address. // This #define works around broken C++ compilers... #define sap_any sap_any() #else + /// Wild-card address. static const ACE_Addr sap_any; - // Wild-card address. #endif /* ACE_HAS_BROKEN_SAP_ANY */ + /// Returns a hash value. This should be overwritten by a subclass + /// which can produce a better hash value. virtual u_long hash (void) const; - // Returns a hash value. This should be overwritten by a subclass - // which can produce a better hash value. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// e.g., AF_UNIX, AF_INET, AF_SPIPE, etc. int addr_type_; - // e.g., AF_UNIX, AF_INET, AF_SPIPE, etc. + /// Number of bytes in the address. int addr_size_; - // Number of bytes in the address. }; #if defined (__ACE_INLINE__) diff --git a/ace/Arg_Shifter.h b/ace/Arg_Shifter.h index 4ae9b7a1262..2e61342d97f 100644 --- a/ace/Arg_Shifter.h +++ b/ace/Arg_Shifter.h @@ -1,18 +1,15 @@ // This may look like C, but it's really -*- C++ -*- -// $Id$ - -// ======================================================================== -// -// = LIBRARY -// ace -// -// = FILENAME -// Arg_Shifter.h -// -// = AUTHOR -// Seth Widoff -// -// ======================================================================== + +//============================================================================= +/** + * @file Arg_Shifter.h + * + * $Id$ + * + * @author Seth Widoff + */ +//============================================================================= + #ifndef ACE_ARG_SHIFTER_H #define ACE_ARG_SHIFTER_H @@ -21,146 +18,154 @@ #include "ace/OS.h" +/** + * @class ACE_Arg_Shifter + * + * @brief This ADT shifts known args to the back of the argv vector, so + * deeper levels of argument parsing can locate the yet + * unprocessed arguments at the beginning of the vector. + * + * The <ACE_Arg_Shifter> copies the pointers of the argv vector + * into a temporary array. As the <ACE_Arg_Shifter> iterates over + * the temp, is places known arguments in the rear of the argv + * and unknown ones in the beginning. So, after having visited + * all the arguments in the temp vector, <ACE_Arg_Shifter> has + * placed all the unknown arguments in their original order at + * the front of argv. + */ class ACE_Export ACE_Arg_Shifter { - // = TITLE - // This ADT shifts known args to the back of the argv vector, so - // deeper levels of argument parsing can locate the yet - // unprocessed arguments at the beginning of the vector. - // - // = DESCRIPTION - // The <ACE_Arg_Shifter> copies the pointers of the argv vector - // into a temporary array. As the <ACE_Arg_Shifter> iterates over - // the temp, is places known arguments in the rear of the argv - // and unknown ones in the beginning. So, after having visited - // all the arguments in the temp vector, <ACE_Arg_Shifter> has - // placed all the unknown arguments in their original order at - // the front of argv. public: // = Initialization and termination methods. + /** + * Initialize the <ACE_Arg_Shifter> to the vector over which to + * iterate, also providing the temporary array if the client doesn't + * want the arg_shifter to dynamically allocate its own. If internal + * dynamic allocation fails, the <ACE_Arg_Shifter> will set all the + * indices to the end of the vector, forbidding iteration. Following + * iteration over argv, the argc value will contain the number of + * unconsumed arguments. + */ ACE_Arg_Shifter (int& argc, ACE_TCHAR **argv, ACE_TCHAR **temp = 0); - // Initialize the <ACE_Arg_Shifter> to the vector over which to - // iterate, also providing the temporary array if the client doesn't - // want the arg_shifter to dynamically allocate its own. If internal - // dynamic allocation fails, the <ACE_Arg_Shifter> will set all the - // indices to the end of the vector, forbidding iteration. Following - // iteration over argv, the argc value will contain the number of - // unconsumed arguments. + /// Destructor. ~ACE_Arg_Shifter (void); - // Destructor. + /// Get the current head of the vector. ACE_TCHAR *get_current (void) const; - // Get the current head of the vector. + /** + * If the <flag> matches the current_arg of arg shifter + * this method will attempt to return the associated + * parameter value + * + * Safe to call without checking that a current arg exists + * + * In the following examples, a pointer to the char* "value" is ret + * + * eg: main -foobar value, main -FooBar value + * main -FOOBARvalue + * + * all of the above will all match the <flag> == -FooBar + * and will return a char* to "value" + * + * main -foobar 4 would succeed and return a char* to "4" + * main -foobar -4 does not succeed (-4 is not a parameter) + * but instead, would return 0 + * + * 0 is returned: + * If the current argument does not match flag + * If there is no parameter found after a 'matched' flag + * + * If the flag is matched and the flag and paramter DO NOT RUN + * together, the flag is consumed, the parameter is returned, + * and the new current argument is the parameter value. + * ie '-foobarflag VALUE' leaves the new cur arg == "VALUE" + * + * If the flag is matched and the flag and parameter RUN + * together '-foobarflagVALUE', the flag is NOT consumed + * and the cur arg is left pointing to the entire flag/value pair + */ ACE_TCHAR *get_the_parameter (const ACE_TCHAR* flag); - // If the <flag> matches the current_arg of arg shifter - // this method will attempt to return the associated - // parameter value - // - // Safe to call without checking that a current arg exists - // - // In the following examples, a pointer to the char* "value" is ret - // - // eg: main -foobar value, main -FooBar value - // main -FOOBARvalue - // - // all of the above will all match the <flag> == -FooBar - // and will return a char* to "value" - // - // main -foobar 4 would succeed and return a char* to "4" - // main -foobar -4 does not succeed (-4 is not a parameter) - // but instead, would return 0 - // - // 0 is returned: - // If the current argument does not match flag - // If there is no parameter found after a 'matched' flag - // - // If the flag is matched and the flag and paramter DO NOT RUN - // together, the flag is consumed, the parameter is returned, - // and the new current argument is the parameter value. - // ie '-foobarflag VALUE' leaves the new cur arg == "VALUE" - // - // If the flag is matched and the flag and parameter RUN - // together '-foobarflagVALUE', the flag is NOT consumed - // and the cur arg is left pointing to the entire flag/value pair + /** + * Check if the current argument matches (case insensitive) <flag> + * + * ------------------------------------------------------------ + * + * Case A: Perfect Match (case insensitive) + * 0 is returned. + * + * ie: when current_arg = "-foobar" or "-FOOBAR" or "-fooBAR" + * this->cur_arg_strncasecmp ("-FooBar); + * will return 0 + * + * ------------------------------------------------------------ + * + * Case B: Perfect Match (case insensitive) but the current_arg + * is longer than the flag. Returns a number equal to the index + * in the char* indicating the start of the extra characters + * + * ie: when current_arg = "-foobar98023" + * this->cur_arg_strncasecmp ("-FooBar); + * will return 7 + * + * Notice: this number will always be > 0 + * + * ------------------------------------------------------------ + * + * Case C: If neither of Case A or B is met (no match) + * then -1 is returned + */ int cur_arg_strncasecmp (const ACE_TCHAR *flag); - // Check if the current argument matches (case insensitive) <flag> - // - // ------------------------------------------------------------ - // - // Case A: Perfect Match (case insensitive) - // 0 is returned. - // - // ie: when current_arg = "-foobar" or "-FOOBAR" or "-fooBAR" - // this->cur_arg_strncasecmp ("-FooBar); - // will return 0 - // - // ------------------------------------------------------------ - // - // Case B: Perfect Match (case insensitive) but the current_arg - // is longer than the flag. Returns a number equal to the index - // in the char* indicating the start of the extra characters - // - // ie: when current_arg = "-foobar98023" - // this->cur_arg_strncasecmp ("-FooBar); - // will return 7 - // - // Notice: this number will always be > 0 - // - // ------------------------------------------------------------ - // - // Case C: If neither of Case A or B is met (no match) - // then -1 is returned + /// Consume <number> argument(s) by sticking them/it on the end of + /// the vector. int consume_arg (int number = 1); - // Consume <number> argument(s) by sticking them/it on the end of - // the vector. + /// Place <number> arguments in the same relative order ahead of the + /// known arguemnts in the vector. int ignore_arg (int number = 1); - // Place <number> arguments in the same relative order ahead of the - // known arguemnts in the vector. + /// Returns the number of args left to see in the vector. int is_anything_left (void) const; - // Returns the number of args left to see in the vector. + /// Returns 1 if there's a next item in the vector and it begins with + /// '-'. int is_option_next (void) const; - // Returns 1 if there's a next item in the vector and it begins with - // '-'. + /// Returns 1 if there's a next item in the vector and it doesn't + /// begin with '-'. int is_parameter_next (void) const; - // Returns 1 if there's a next item in the vector and it doesn't - // begin with '-'. + /// Returns the number of irrelevant args seen. int num_ignored_args (void) const; - // Returns the number of irrelevant args seen. private: + /// The size of the argument vector. int& argc_; - // The size of the argument vector. + /// The size of argv_. int total_size_; - // The size of argv_. + /// The temporary array over which we traverse. ACE_TCHAR **temp_; - // The temporary array over which we traverse. + /// The array in which the arguments are reordered. ACE_TCHAR **argv_; - // The array in which the arguments are reordered. + /// The element in <temp_> we're currently examining. int current_index_; - // The element in <temp_> we're currently examining. + /// The index of <argv_> in which we'll stick the next unknown + /// argument. int back_; - // The index of <argv_> in which we'll stick the next unknown - // argument. + /// The index of <argv_> in which we'll stick the next known + /// argument. int front_; - // The index of <argv_> in which we'll stick the next known - // argument. }; #include "ace/post.h" diff --git a/ace/Array.h b/ace/Array.h index b095ba726d0..f1d17ad9822 100644 --- a/ace/Array.h +++ b/ace/Array.h @@ -1,22 +1,19 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Array.h -// -// = DESCRIPTION -// NOTE: this file has been deprecated and will soon go away. You -// should directly include "Containers_T.h" instead. -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ +//============================================================================= +/** + * @file Array.h + * + * $Id$ + * + * NOTE: this file has been deprecated and will soon go away. You + * should directly include "Containers_T.h" instead. + * + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_ARRAY_H #define ACE_ARRAY_H diff --git a/ace/Asynch_Acceptor.h b/ace/Asynch_Acceptor.h index 28bdff62967..835ed63ec5b 100644 --- a/ace/Asynch_Acceptor.h +++ b/ace/Asynch_Acceptor.h @@ -1,17 +1,14 @@ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Asynch_Acceptor.h -// -// = AUTHOR -// Irfan Pyarali (irfan@cs.wustl.edu) -// -// ============================================================================ + +//============================================================================= +/** + * @file Asynch_Acceptor.h + * + * $Id$ + * + * @author Irfan Pyarali (irfan@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_ASYNCH_ACCEPTOR_H #define ACE_ASYNCH_ACCEPTOR_H @@ -32,24 +29,44 @@ class ACE_Message_Block; class ACE_INET_Addr; +/** + * @class ACE_Asynch_Acceptor + * + * @brief This class is an example of the Acceptor Pattern. This class + * will accept new connections and create new HANDLER to handle + * the new connections. + * + * Unlike the <ACE_Acceptor>, however, this class is designed to + * be used asynchronously. + */ template <class HANDLER> class ACE_Asynch_Acceptor : public ACE_Handler { - // = TITLE - // This class is an example of the Acceptor Pattern. This class - // will accept new connections and create new HANDLER to handle - // the new connections. - // - // = DESCRIPTION - // Unlike the <ACE_Acceptor>, however, this class is designed to - // be used asynchronously. public: + /// A do nothing constructor. ACE_Asynch_Acceptor (void); - // A do nothing constructor. + /// Virtual destruction virtual ~ACE_Asynch_Acceptor (void); - // Virtual destruction + /** + * This starts the listening process at the port specified by + * <address>. ACE_Asynch_Acceptor initiates the AcceptEx calls with + * <bytes_to_read>. The buffer for the initial data will be created + * by ACE_Asynch_Acceptor. This buffer will be passed to the + * handler in the <ACE_Service_Handler::open> callback. If this + * buffer is required past the <open> callback, the + * ACE_Service_Handler must copy the data. If the <pass_addresses> + * flag is set, ACE_Asynch_Acceptor will call + * <ACE_Service_Handler::addresses> before calling + * <ACE_Service_Handler::open>. The <backlog> parameter specifies + * the listen backlog and the outstanding AcceptEx calls. + * <number_of_initial_accepts> is the number of asynchronous accepts + * that are started at the end of <open>. If + * <number_of_initial_accepts> is -1, then + * <number_of_initial_accepts> is set to <backlog> and hence + * <backlog> number of asynchronous accepts are started. + */ virtual int open (const ACE_INET_Addr &address, size_t bytes_to_read = 0, int pass_addresses = 0, @@ -59,114 +76,108 @@ public: int validate_new_connection = 0, int reissue_accept = 1, int number_of_initial_accepts = -1); - // This starts the listening process at the port specified by - // <address>. ACE_Asynch_Acceptor initiates the AcceptEx calls with - // <bytes_to_read>. The buffer for the initial data will be created - // by ACE_Asynch_Acceptor. This buffer will be passed to the - // handler in the <ACE_Service_Handler::open> callback. If this - // buffer is required past the <open> callback, the - // ACE_Service_Handler must copy the data. If the <pass_addresses> - // flag is set, ACE_Asynch_Acceptor will call - // <ACE_Service_Handler::addresses> before calling - // <ACE_Service_Handler::open>. The <backlog> parameter specifies - // the listen backlog and the outstanding AcceptEx calls. - // <number_of_initial_accepts> is the number of asynchronous accepts - // that are started at the end of <open>. If - // <number_of_initial_accepts> is -1, then - // <number_of_initial_accepts> is set to <backlog> and hence - // <backlog> number of asynchronous accepts are started. + /// Get the underlying handle. virtual ACE_HANDLE get_handle (void) const; - // Get the underlying handle. + /** + * Set the underlying listen handle. It is the user's responsibility + * to make sure that the old listen handle has been appropriately + * closed and the all outstanding asynchronous operations have + * either completed or have been canceled on the old listen handle. + */ virtual void set_handle (ACE_HANDLE handle); - // Set the underlying listen handle. It is the user's responsibility - // to make sure that the old listen handle has been appropriately - // closed and the all outstanding asynchronous operations have - // either completed or have been canceled on the old listen handle. + /// This initiates a new asynchronous accept through the <AcceptEx> + /// call. virtual int accept (size_t bytes_to_read = 0, const void *act = 0); - // This initiates a new asynchronous accept through the <AcceptEx> - // call. + /** + * This cancels all pending accepts operations that were issued by + * the calling thread. The function does not cancel accept + * operations issued by other threads. + */ virtual int cancel (void); - // This cancels all pending accepts operations that were issued by - // the calling thread. The function does not cancel accept - // operations issued by other threads. + /** + * Template method for address validation. + * + * Default implemenation always validates the remote address. + */ virtual int validate_new_connection (const ACE_INET_Addr &remote_address); - // Template method for address validation. - // - // Default implemenation always validates the remote address. + /** + * Template method for deciding whether to reissue accept. + * + * Default implemenation always returns this->reissue_accept_. + */ virtual int should_reissue_accept (void); - // Template method for deciding whether to reissue accept. - // - // Default implemenation always returns this->reissue_accept_. // // These are low level tweaking methods // + /// Set and get flag that indicates if parsing and passing of + /// addresses to the service_handler is necessary. virtual int pass_addresses (void) const; virtual void pass_addresses (int new_value); - // Set and get flag that indicates if parsing and passing of - // addresses to the service_handler is necessary. + /// Set and get flag that indicates if address validation is + /// required. virtual int validate_new_connection (void) const; virtual void validate_new_connection (int new_value); - // Set and get flag that indicates if address validation is - // required. + /// Set and get flag that indicates if a new accept should be + /// reissued when a accept completes. virtual int reissue_accept (void) const; virtual void reissue_accept (int new_value); - // Set and get flag that indicates if a new accept should be - // reissued when a accept completes. + /// Set and get bytes to be read with the <accept> call. virtual int bytes_to_read (void) const; virtual void bytes_to_read (int new_value); - // Set and get bytes to be read with the <accept> call. + /// This is required by the AcceptEx call. static size_t address_size (void); - // This is required by the AcceptEx call. protected: + /// This is called when an outstanding accept completes. virtual void handle_accept (const ACE_Asynch_Accept::Result &result); - // This is called when an outstanding accept completes. + /// Return the listen handle. ACE_HANDLE handle (void) const; - // Return the listen handle. + /// This parses the address from read buffer. void parse_address (const ACE_Asynch_Accept::Result &result, ACE_INET_Addr &remote_address, ACE_INET_Addr &local_address); - // This parses the address from read buffer. + /** + * This is the template method used to create new handler. + * Subclasses must overwrite this method if a new handler creation + * strategy is required. + */ virtual HANDLER *make_handler (void); - // This is the template method used to create new handler. - // Subclasses must overwrite this method if a new handler creation - // strategy is required. private: + /// Handle used to listen for new connections. ACE_HANDLE listen_handle_; - // Handle used to listen for new connections. + /// <Asynch_Accept> used to make life easier :-) ACE_Asynch_Accept asynch_accept_; - // <Asynch_Accept> used to make life easier :-) + /// Flag that indicates if parsing of addresses is necessary. int pass_addresses_; - // Flag that indicates if parsing of addresses is necessary. + /// Flag that indicates if address validation is required. int validate_new_connection_; - // Flag that indicates if address validation is required. + /// Flag that indicates if a new accept should be reissued when a + /// accept completes. int reissue_accept_; - // Flag that indicates if a new accept should be reissued when a - // accept completes. + /// Bytes to be read with the <accept> call. int bytes_to_read_; - // Bytes to be read with the <accept> call. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) @@ -180,4 +191,3 @@ private: #endif /* ACE_WIN32 || ACE_HAS_AIO_CALLS */ #include "ace/post.h" #endif /* ACE_ASYNCH_ACCEPTOR_H */ - diff --git a/ace/Asynch_IO.h b/ace/Asynch_IO.h index 344563e6aa0..024830db2cf 100644 --- a/ace/Asynch_IO.h +++ b/ace/Asynch_IO.h @@ -1,29 +1,27 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// = FILENAME -// Asynch_IO.h -// -// = DESCRIPTION -// This works on Win32 (#if defined (ACE_WIN32) && !defined -// (ACE_HAS_WINCE)) platforms and on POSIX4 platforms with <aio_*> -// routines (#if defined (ACE_HAS_AIO_CALLS)) -// -// On Win32 platforms, the implementation of -// <ACE_Asynch_Transmit_File> and <ACE_Asynch_Accept> are only -// supported if ACE_HAS_WINSOCK2 is defined or you are on WinNT 4.0 -// or higher. -// -// = AUTHOR -// Irfan Pyarali <irfan@cs.wustl.edu>, -// Tim Harrison <harrison@cs.wustl.edu> and -// Alexander Babu Arulanthu <alex@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Asynch_IO.h + * + * $Id$ + * + * This works on Win32 (#if defined (ACE_WIN32) && !defined + * (ACE_HAS_WINCE)) platforms and on POSIX4 platforms with <aio_*> + * routines (#if defined (ACE_HAS_AIO_CALLS)) + * + * On Win32 platforms, the implementation of + * <ACE_Asynch_Transmit_File> and <ACE_Asynch_Accept> are only + * supported if ACE_HAS_WINSOCK2 is defined or you are on WinNT 4.0 + * or higher. + * + * + * @author Irfan Pyarali <irfan@cs.wustl.edu> + * @author Tim Harrison <harrison@cs.wustl.edu> + * @author Alexander Babu Arulanthu <alex@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_ASYNCH_IO_H #define ACE_ASYNCH_IO_H @@ -46,288 +44,306 @@ class ACE_INET_Addr; // Forward declarations class ACE_Asynch_Result_Impl; +/** + * @class ACE_Asynch_Result + * + * @brief An interface base class which allows users access to common + * information related to an asynchronous operation. + * + * An interface base class from which you can obtain some basic + * information like the number of bytes transferred, the ACT + * associated with the asynchronous operation, indication of + * success or failure, etc. Subclasses may want to store more + * information that is particular to the asynchronous operation + * it represents. + */ class ACE_Export ACE_Asynch_Result { - // = TITLE - // - // An interface base class which allows users access to common - // information related to an asynchronous operation. - // - // = DESCRIPTION - // - // An interface base class from which you can obtain some basic - // information like the number of bytes transferred, the ACT - // associated with the asynchronous operation, indication of - // success or failure, etc. Subclasses may want to store more - // information that is particular to the asynchronous operation - // it represents. public: + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This is the ACT associated with the handle on which the + * Asynch_Operation takes place. + * + * On WIN32, this returns the ACT associated with the handle when it + * was registered with the I/O completion port. + * + * @@ This is not implemented for POSIX4 platforms. Returns 0. + */ const void *completion_key (void) const; - // This is the ACT associated with the handle on which the - // Asynch_Operation takes place. - // - // On WIN32, this returns the ACT associated with the handle when it - // was registered with the I/O completion port. - // - // @@ This is not implemented for POSIX4 platforms. Returns 0. + /// Error value if the operation fails. u_long error (void) const; - // Error value if the operation fails. + /** + * On WIN32, this returns the event associated with the OVERLAPPED + * structure. + * + * This returns ACE_INVALID_HANDLE on POSIX4-Unix platforms. + */ ACE_HANDLE event (void) const; - // On WIN32, this returns the event associated with the OVERLAPPED - // structure. - // - // This returns ACE_INVALID_HANDLE on POSIX4-Unix platforms. + /** + * This really makes sense only when doing file I/O. + * + * On WIN32, these are represented in the OVERLAPPED datastructure. + * + * @@ On POSIX4-Unix, offset_high should be supported using + * aiocb64. + */ u_long offset (void) const; u_long offset_high (void) const; - // This really makes sense only when doing file I/O. - // - // On WIN32, these are represented in the OVERLAPPED datastructure. - // - // @@ On POSIX4-Unix, offset_high should be supported using - // aiocb64. + /** + * Priority of the operation. + * + * On POSIX4-Unix, this is supported. Priority works like <nice> in + * Unix. Negative values are not allowed. 0 means priority of the + * operation same as the process priority. 1 means priority of the + * operation is one less than process. And so forth. + * + * On Win32, this is a no-op. + */ int priority (void) const; - // Priority of the operation. - // - // On POSIX4-Unix, this is supported. Priority works like <nice> in - // Unix. Negative values are not allowed. 0 means priority of the - // operation same as the process priority. 1 means priority of the - // operation is one less than process. And so forth. - // - // On Win32, this is a no-op. - + + /** + * POSIX4 real-time signal number to be used for the + * operation. <signal_number> ranges from ACE_SIGRTMIN to ACE_SIGRTMAX. By + * default, ACE_SIGRTMIN is used to issue <aio_> calls. This is a no-op + * on non-POSIX4 systems and returns 0. + */ int signal_number (void) const; - // POSIX4 real-time signal number to be used for the - // operation. <signal_number> ranges from ACE_SIGRTMIN to ACE_SIGRTMAX. By - // default, ACE_SIGRTMIN is used to issue <aio_> calls. This is a no-op - // on non-POSIX4 systems and returns 0. + /// Destructor. virtual ~ACE_Asynch_Result (void); - // Destructor. protected: + /// Constructor. This implementation will not be deleted. The + /// implementation will be deleted by the Proactor. ACE_Asynch_Result (ACE_Asynch_Result_Impl *implementation); - // Constructor. This implementation will not be deleted. The - // implementation will be deleted by the Proactor. + /// Get the implementation class. ACE_Asynch_Result_Impl *implementation (void) const; - // Get the implementation class. - + + /// Implementation class. ACE_Asynch_Result_Impl *implementation_; - // Implementation class. }; // Forward declarations class ACE_Asynch_Operation_Impl; +/** + * @class ACE_Asynch_Operation + * + * @brief This is an interface base class for all asynch + * operations. The resposiblility of this class is to forward + * all methods to its delegation/implementation class, e.g., + * <ACE_WIN32_Asynch_Operation> or <ACE_POSIX_Asynch_Operation>. + * + * There are some attributes and functionality which is common + * to all asychronous operations. The delegation classes of this + * class will factor out this code. + */ class ACE_Export ACE_Asynch_Operation { - // = TITLE - // - // This is an interface base class for all asynch - // operations. The resposiblility of this class is to forward - // all methods to its delegation/implementation class, e.g., - // <ACE_WIN32_Asynch_Operation> or <ACE_POSIX_Asynch_Operation>. - // - // = DESCRIPTION - // - // There are some attributes and functionality which is common - // to all asychronous operations. The delegation classes of this - // class will factor out this code. public: + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * (Attempts to) cancel the asynchronous operation pending against + * the <handle> registered with this Operation. + * + * All completion notifications for the I/O operations will occur + * normally. + * + * = Return Values: + * + * -1 : Operation failed. (can get only in POSIX). + * 0 : All the operations were cancelled. + * 1 : All the operations were already finished in this + * handle. Unable to cancel them. + * 2 : Atleast one of the requested operations cannot be + * cancelled. + * + * There is slight difference in the semantics between NT and POSIX + * platforms which is given below. + * + * = Win32 : + * + * cancels all pending accepts operations that were issued by the + * calling thread. The function does not cancel asynchronous + * operations issued by other threads. + * All I/O operations that are canceled will complete with the + * error ERROR_OPERATION_ABORTED. + * + * = POSIX: + * + * Attempts to cancel one or more asynchronous I/O requests + * currently outstanding against the <handle> registered in this + * operation. + * For requested operations that are successfully canceled, the + * associated error status is set to ECANCELED. + */ int cancel (void); - // (Attempts to) cancel the asynchronous operation pending against - // the <handle> registered with this Operation. - // - // All completion notifications for the I/O operations will occur - // normally. - // - // = Return Values: - // - // -1 : Operation failed. (can get only in POSIX). - // 0 : All the operations were cancelled. - // 1 : All the operations were already finished in this - // handle. Unable to cancel them. - // 2 : Atleast one of the requested operations cannot be - // cancelled. - // - // There is slight difference in the semantics between NT and POSIX - // platforms which is given below. - // - // = Win32 : - // - // cancels all pending accepts operations that were issued by the - // calling thread. The function does not cancel asynchronous - // operations issued by other threads. - // All I/O operations that are canceled will complete with the - // error ERROR_OPERATION_ABORTED. - // - // = POSIX: - // - // Attempts to cancel one or more asynchronous I/O requests - // currently outstanding against the <handle> registered in this - // operation. - // For requested operations that are successfully canceled, the - // associated error status is set to ECANCELED. - - + + // = Access methods. + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. + /// Destructor. virtual ~ACE_Asynch_Operation (void); - // Destructor. protected: + /// Constructor. ACE_Asynch_Operation (void); - // Constructor. + /// Return the underlying implementation class. ACE_Asynch_Operation_Impl *implementation (void) const; - // Return the underlying implementation class. + /// Set the implementation class. void implementation (ACE_Asynch_Operation_Impl *implementation); - // Set the implementation class. - + + /// Get a proactor for/from the user ACE_Proactor *get_proactor (ACE_Proactor *user_proactor, ACE_Handler &handler) const; - // Get a proactor for/from the user + /// Implementation class. ACE_Asynch_Operation_Impl *implementation_; - // Implementation class. }; // Forward declarations class ACE_Asynch_Read_Stream_Result_Impl; class ACE_Asynch_Read_Stream_Impl; +/** + * @class ACE_Asynch_Read_Stream + * + * @brief This class is a factory for starting off asynchronous reads + * on a stream. This class forwards all methods to its + * implementation class. + * + * Once <open> is called, multiple asynchronous <read>s can + * started using this class. An ACE_Asynch_Read_Stream::Result + * will be passed back to the <handler> when the asynchronous + * reads completes through the <ACE_Handler::handle_read_stream> + * callback. + */ class ACE_Export ACE_Asynch_Read_Stream : public ACE_Asynch_Operation { - // = TITLE - // - // This class is a factory for starting off asynchronous reads - // on a stream. This class forwards all methods to its - // implementation class. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <read>s can - // started using this class. An ACE_Asynch_Read_Stream::Result - // will be passed back to the <handler> when the asynchronous - // reads completes through the <ACE_Handler::handle_read_stream> - // callback. public: + /// A do nothing constructor. ACE_Asynch_Read_Stream (void); - // A do nothing constructor. + /// Destructor virtual ~ACE_Asynch_Read_Stream (void); - // Destructor + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle = ACE_INVALID_HANDLE, const void *completion_key = 0, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * This starts off an asynchronous read. Upto <bytes_to_read> will + * be read and stored in the <message_block>. <message_block>'s + * <wr_ptr> will be updated to reflect the added bytes if the read + * operation is successful completed. Priority of the + * operation is specified by <priority>. On POSIX4-Unix, this is + * supported. Works like <nice> in Unix. Negative values are not + * allowed. 0 means priority of the operation same as the process + * priority. 1 means priority of the operation is one less than + * process. And so forth. On Win32, <priority> is a no-op. + * <signal_number> is the POSIX4 real-time signal number to be used + * for the operation. <signal_number> ranges from ACE_SIGRTMIN to + * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + */ int read (ACE_Message_Block &message_block, u_long bytes_to_read, const void *act = 0, int priority = 0, int signal_number = ACE_SIGRTMIN); - // This starts off an asynchronous read. Upto <bytes_to_read> will - // be read and stored in the <message_block>. <message_block>'s - // <wr_ptr> will be updated to reflect the added bytes if the read - // operation is successful completed. Priority of the - // operation is specified by <priority>. On POSIX4-Unix, this is - // supported. Works like <nice> in Unix. Negative values are not - // allowed. 0 means priority of the operation same as the process - // priority. 1 means priority of the operation is one less than - // process. And so forth. On Win32, <priority> is a no-op. - // <signal_number> is the POSIX4 real-time signal number to be used - // for the operation. <signal_number> ranges from ACE_SIGRTMIN to - // ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + /// Return the underlying implementation class. ACE_Asynch_Read_Stream_Impl *implementation (void) const; - // Return the underlying implementation class. protected: + /// Set the implementation class. void implementation (ACE_Asynch_Read_Stream_Impl *implementation); - // Set the implementation class. + /// Implementation class that all methods will be forwarded to. ACE_Asynch_Read_Stream_Impl *implementation_; - // Implementation class that all methods will be forwarded to. public: +/** + * @class Result + * + * @brief This is the class which will be passed back to the + * <handler> when the asynchronous read completes. This class + * forwards all the methods to the implementation classes. + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous read. + */ class ACE_Export Result : public ACE_Asynch_Result { - // = TITLE - // - // This is the class which will be passed back to the - // <handler> when the asynchronous read completes. This class - // forwards all the methods to the implementation classes. - // - // = DESCRIPTION - // - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous read. - + + /// The concrete implementation result classes only construct this + /// class. friend class ACE_POSIX_Asynch_Read_Stream_Result; friend class ACE_WIN32_Asynch_Read_Stream_Result; - // The concrete implementation result classes only construct this - // class. public: + /// The number of bytes which were requested at the start of the + /// asynchronous read. u_long bytes_to_read (void) const; - // The number of bytes which were requested at the start of the - // asynchronous read. + /// Message block which contains the read data. ACE_Message_Block &message_block (void) const; - // Message block which contains the read data. + /// I/O handle used for reading. ACE_HANDLE handle (void) const; - // I/O handle used for reading. + /// Get the implementation class. ACE_Asynch_Read_Stream_Result_Impl *implementation (void) const; - // Get the implementation class. - + protected: + /// Constructor. Result (ACE_Asynch_Read_Stream_Result_Impl *implementation); - // Constructor. - + + /// Destructor. virtual ~Result (void); - // Destructor. + /// The implementation class. ACE_Asynch_Read_Stream_Result_Impl *implementation_; - // The implementation class. }; }; @@ -335,151 +351,169 @@ public: class ACE_Asynch_Write_Stream_Impl; class ACE_Asynch_Write_Stream_Result_Impl; +/** + * @class ACE_Asynch_Write_Stream + * + * @brief This class is a factory for starting off asynchronous writes + * on a stream. This class forwards all methods to its + * implementation class. + * + * Once <open> is called, multiple asynchronous <writes>s can + * started using this class. An ACE_Asynch_Write_Stream::Result + * will be passed back to the <handler> when the asynchronous + * write completes through the + * <ACE_Handler::handle_write_stream> callback. + */ class ACE_Export ACE_Asynch_Write_Stream : public ACE_Asynch_Operation { - // = TITLE - // - // This class is a factory for starting off asynchronous writes - // on a stream. This class forwards all methods to its - // implementation class. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <writes>s can - // started using this class. An ACE_Asynch_Write_Stream::Result - // will be passed back to the <handler> when the asynchronous - // write completes through the - // <ACE_Handler::handle_write_stream> callback. public: + /// A do nothing constructor. ACE_Asynch_Write_Stream (void); - // A do nothing constructor. + /// Destructor. virtual ~ACE_Asynch_Write_Stream (void); - // Destructor. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle = ACE_INVALID_HANDLE, const void *completion_key = 0, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * This starts off an asynchronous write. Upto <bytes_to_write> + * will be written from the <message_block>. Upon successful completion + * of the write operation, <message_block>'s <rd_ptr> is updated to + * reflect the data that was written. Priority of the + * operation is specified by <priority>. On POSIX4-Unix, this is + * supported. Works like <nice> in Unix. Negative values are not + * allowed. 0 means priority of the operation same as the process + * priority. 1 means priority of the operation is one less than + * process. And so forth. On Win32, this argument is a no-op. + * <signal_number> is the POSIX4 real-time signal number to be used + * for the operation. <signal_number> ranges from ACE_SIGRTMIN to + * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + */ int write (ACE_Message_Block &message_block, u_long bytes_to_write, const void *act = 0, int priority = 0, int signal_number = ACE_SIGRTMIN); - // This starts off an asynchronous write. Upto <bytes_to_write> - // will be written from the <message_block>. Upon successful completion - // of the write operation, <message_block>'s <rd_ptr> is updated to - // reflect the data that was written. Priority of the - // operation is specified by <priority>. On POSIX4-Unix, this is - // supported. Works like <nice> in Unix. Negative values are not - // allowed. 0 means priority of the operation same as the process - // priority. 1 means priority of the operation is one less than - // process. And so forth. On Win32, this argument is a no-op. - // <signal_number> is the POSIX4 real-time signal number to be used - // for the operation. <signal_number> ranges from ACE_SIGRTMIN to - // ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + /// Return the underlying implementation class. ACE_Asynch_Write_Stream_Impl *implementation (void) const; - // Return the underlying implementation class. protected: + /// Set the implementation class. void implementation (ACE_Asynch_Write_Stream_Impl *implementation); - // Set the implementation class. + /// Implementation class that all methods will be forwarded to. ACE_Asynch_Write_Stream_Impl *implementation_; - // Implementation class that all methods will be forwarded to. public: +/** + * @class + * + * @brief This is that class which will be passed back to the + * <handler> when the asynchronous write completes. This class + * forwards all the methods to the implementation class. + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous write. + */ class ACE_Export Result : public ACE_Asynch_Result { - // = TITLE - // - // This is that class which will be passed back to the - // <handler> when the asynchronous write completes. This class - // forwards all the methods to the implementation class. - // - // = DESCRIPTION - // - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous write. + /// The concrete implementation result classes only construct this + /// class. friend class ACE_POSIX_Asynch_Write_Stream_Result; friend class ACE_WIN32_Asynch_Write_Stream_Result; - // The concrete implementation result classes only construct this - // class. public: + /// The number of bytes which were requested at the start of the + /// asynchronous write. u_long bytes_to_write (void) const; - // The number of bytes which were requested at the start of the - // asynchronous write. + /// Message block that contains the data to be written. ACE_Message_Block &message_block (void) const; - // Message block that contains the data to be written. + /// I/O handle used for writing. ACE_HANDLE handle (void) const; - // I/O handle used for writing. + /// Get the implementation class. ACE_Asynch_Write_Stream_Result_Impl *implementation (void) const; - // Get the implementation class. - + protected: + /// Constrcutor. Result (ACE_Asynch_Write_Stream_Result_Impl *implementation); - // Constrcutor. - + + /// Destructor. virtual ~Result (void); - // Destructor. + /// Implementation class. ACE_Asynch_Write_Stream_Result_Impl *implementation_; - // Implementation class. }; -}; +}; // Forward declarations class ACE_Asynch_Read_File_Impl; class ACE_Asynch_Read_File_Result_Impl; +/** + * @class ACE_Asynch_Read_File + * + * @brief This class is a factory for starting off asynchronous reads + * on a file. This class forwards all methods to its + * implementation class. + * + * Once <open> is called, multiple asynchronous <read>s can + * started using this class. An ACE_Asynch_Read_File::Result + * will be passed back to the <handler> when the asynchronous + * reads completes through the <ACE_Handler::handle_read_file> + * callback. + * This class differs slightly from ACE_Asynch_Read_Stream as it + * allows the user to specify an offset for the read. + */ class ACE_Export ACE_Asynch_Read_File : public ACE_Asynch_Read_Stream { - // = TITLE - // - // This class is a factory for starting off asynchronous reads - // on a file. This class forwards all methods to its - // implementation class. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <read>s can - // started using this class. An ACE_Asynch_Read_File::Result - // will be passed back to the <handler> when the asynchronous - // reads completes through the <ACE_Handler::handle_read_file> - // callback. - // - // This class differs slightly from ACE_Asynch_Read_Stream as it - // allows the user to specify an offset for the read. public: + /// A do nothing constructor. ACE_Asynch_Read_File (void); - // A do nothing constructor. + /// Destructor. virtual ~ACE_Asynch_Read_File (void); - // Destructor. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle = ACE_INVALID_HANDLE, const void *completion_key = 0, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. - + + /** + * This starts off an asynchronous read. Upto <bytes_to_read> will + * be read and stored in the <message_block>. The read will start + * at <offset> from the beginning of the file. Priority of the + * operation is specified by <priority>. On POSIX4-Unix, this is + * supported. Works like <nice> in Unix. Negative values are not + * allowed. 0 means priority of the operation same as the process + * priority. 1 means priority of the operation is one less than + * process. And so forth. On Win32, this argument is a no-op. + * <signal_number> is the POSIX4 real-time signal number to be used + * for the operation. <signal_number> ranges from ACE_SIGRTMIN to + * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + */ int read (ACE_Message_Block &message_block, u_long bytes_to_read, u_long offset = 0, @@ -487,69 +521,57 @@ public: const void *act = 0, int priority = 0, int signal_number = ACE_SIGRTMIN); - // This starts off an asynchronous read. Upto <bytes_to_read> will - // be read and stored in the <message_block>. The read will start - // at <offset> from the beginning of the file. Priority of the - // operation is specified by <priority>. On POSIX4-Unix, this is - // supported. Works like <nice> in Unix. Negative values are not - // allowed. 0 means priority of the operation same as the process - // priority. 1 means priority of the operation is one less than - // process. And so forth. On Win32, this argument is a no-op. - // <signal_number> is the POSIX4 real-time signal number to be used - // for the operation. <signal_number> ranges from ACE_SIGRTMIN to - // ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + /// Return the underlying implementation class. ACE_Asynch_Read_File_Impl *implementation (void) const; - // Return the underlying implementation class. protected: + /// Set the implementation class. void implementation (ACE_Asynch_Read_File_Impl *implementation); - // Set the implementation class. - + + /// Delegation/implementation class that all methods will be + /// forwarded to. ACE_Asynch_Read_File_Impl *implementation_; - // Delegation/implementation class that all methods will be - // forwarded to. public: +/** + * @class Result + * + * @brief This is that class which will be passed back to the + * <handler> when the asynchronous read completes. This class + * forwards all the methods to the implementation class. + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous read. + * This class differs slightly from + * ACE_Asynch_Read_Stream::Result as it calls back + * <ACE_Handler::handle_read_file> on the <handler> instead of + * <ACE_Handler::handle_read_stream>. No additional state is + * required by this class as ACE_Asynch_Result can store the + * <offset>. + */ class ACE_Export Result : public ACE_Asynch_Read_Stream::Result { - // = TITLE - // - // This is that class which will be passed back to the - // <handler> when the asynchronous read completes. This class - // forwards all the methods to the implementation class. - // - // = DESCRIPTION - // - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous read. - // - // This class differs slightly from - // ACE_Asynch_Read_Stream::Result as it calls back - // <ACE_Handler::handle_read_file> on the <handler> instead of - // <ACE_Handler::handle_read_stream>. No additional state is - // required by this class as ACE_Asynch_Result can store the - // <offset>. + /// The concrete implementation result classes only construct this + /// class. friend class ACE_POSIX_Asynch_Read_File_Result; friend class ACE_WIN32_Asynch_Read_File_Result; - // The concrete implementation result classes only construct this - // class. - + public: + /// Get the implementation class. ACE_Asynch_Read_File_Result_Impl *implementation (void) const; - // Get the implementation class. protected: + /// Constructor. This implementation will not be deleted. Result (ACE_Asynch_Read_File_Result_Impl *implementation); - // Constructor. This implementation will not be deleted. + /// Destructor. virtual ~Result (void); - // Destructor. - + + /// The implementation class. ACE_Asynch_Read_File_Result_Impl *implementation_; - // The implementation class. }; }; @@ -557,41 +579,55 @@ public: class ACE_Asynch_Write_File_Impl; class ACE_Asynch_Write_File_Result_Impl; +/** + * @class ACE_Asynch_Write_File + * + * @brief This class is a factory for starting off asynchronous writes + * on a file. This class forwards all methods to its + * implementation class. + * + * Once <open> is called, multiple asynchronous <write>s can be + * started using this class. A ACE_Asynch_Write_File::Result + * will be passed back to the <handler> when the asynchronous + * writes completes through the <ACE_Handler::handle_write_file> + * callback. + * This class differs slightly from ACE_Asynch_Write_Stream as + * it allows the user to specify an offset for the write. + */ class ACE_Export ACE_Asynch_Write_File : public ACE_Asynch_Write_Stream { - // = TITLE - // - // This class is a factory for starting off asynchronous writes - // on a file. This class forwards all methods to its - // implementation class. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <write>s can be - // started using this class. A ACE_Asynch_Write_File::Result - // will be passed back to the <handler> when the asynchronous - // writes completes through the <ACE_Handler::handle_write_file> - // callback. - // - // This class differs slightly from ACE_Asynch_Write_Stream as - // it allows the user to specify an offset for the write. public: + /// A do nothing constructor. ACE_Asynch_Write_File (void); - // A do nothing constructor. + /// Destructor. virtual ~ACE_Asynch_Write_File (void); - // Destructor. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle = ACE_INVALID_HANDLE, const void *completion_key = 0, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * This starts off an asynchronous write. Upto <bytes_to_write> + * will be write and stored in the <message_block>. The write will + * start at <offset> from the beginning of the file. Priority of the + * operation is specified by <priority>. On POSIX4-Unix, this is + * supported. Works like <nice> in Unix. Negative values are not + * allowed. 0 means priority of the operation same as the process + * priority. 1 means priority of the operation is one less than + * process. And so forth. On Win32, this is a no-op. + * <signal_number> is the POSIX4 real-time signal number to be used + * for the operation. <signal_number> ranges from ACE_SIGRTMIN to + * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + */ int write (ACE_Message_Block &message_block, u_long bytes_to_write, u_long offset = 0, @@ -599,68 +635,56 @@ public: const void *act = 0, int priority = 0, int signal_number = ACE_SIGRTMIN); - // This starts off an asynchronous write. Upto <bytes_to_write> - // will be write and stored in the <message_block>. The write will - // start at <offset> from the beginning of the file. Priority of the - // operation is specified by <priority>. On POSIX4-Unix, this is - // supported. Works like <nice> in Unix. Negative values are not - // allowed. 0 means priority of the operation same as the process - // priority. 1 means priority of the operation is one less than - // process. And so forth. On Win32, this is a no-op. - // <signal_number> is the POSIX4 real-time signal number to be used - // for the operation. <signal_number> ranges from ACE_SIGRTMIN to - // ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + /// Return the underlying implementation class. ACE_Asynch_Write_File_Impl *implementation (void) const; - // Return the underlying implementation class. protected: + /// Set the implementation. void implementation (ACE_Asynch_Write_File_Impl *implementation); - // Set the implementation. + /// Implementation object. ACE_Asynch_Write_File_Impl *implementation_; - // Implementation object. public: +/** + * @class Result + * + * @brief This is that class which will be passed back to the + * <handler> when the asynchronous write completes. This class + * forwards all the methods to the implementation class. + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous write. + * This class differs slightly from + * ACE_Asynch_Write_Stream::Result as it calls back + * <ACE_Handler::handle_write_file> on the <handler> instead + * of <ACE_Handler::handle_write_stream>. No additional state + * is required by this class as ACE_Asynch_Result can store + * the <offset>. + */ class ACE_Export Result : public ACE_Asynch_Write_Stream::Result { - // = TITLE - // - // This is that class which will be passed back to the - // <handler> when the asynchronous write completes. This class - // forwards all the methods to the implementation class. - // - // = DESCRIPTION - // - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous write. - // - // This class differs slightly from - // ACE_Asynch_Write_Stream::Result as it calls back - // <ACE_Handler::handle_write_file> on the <handler> instead - // of <ACE_Handler::handle_write_stream>. No additional state - // is required by this class as ACE_Asynch_Result can store - // the <offset>. - + + /// The concrete implementation result classes only construct this + /// class. friend class ACE_POSIX_Asynch_Write_File_Result; friend class ACE_WIN32_Asynch_Write_File_Result; - // The concrete implementation result classes only construct this - // class. public: + /// Get the implementation class. ACE_Asynch_Write_File_Result_Impl *implementation (void) const; - // Get the implementation class. - + protected: + /// Constructor. This implementation will not be deleted. Result (ACE_Asynch_Write_File_Result_Impl *implementation); - // Constructor. This implementation will not be deleted. + /// Destructor. virtual ~Result (void); - // Destructor. + /// The implementation class. ACE_Asynch_Write_File_Result_Impl *implementation_; - // The implementation class. }; }; @@ -668,118 +692,122 @@ public: class ACE_Asynch_Accept_Result_Impl; class ACE_Asynch_Accept_Impl; +/** + * @class ACE_Asynch_Accept + * + * @brief This class is a factory for starting off asynchronous accepts + * on a listen handle. This class forwards all methods to its + * implementation class. + * + * Once <open> is called, multiple asynchronous <accept>s can + * started using this class. A ACE_Asynch_Accept::Result will + * be passed back to the <handler> when the asynchronous accept + * completes through the <ACE_Handler::handle_accept> + * callback. + */ class ACE_Export ACE_Asynch_Accept : public ACE_Asynch_Operation { - // = TITLE - // - // This class is a factory for starting off asynchronous accepts - // on a listen handle. This class forwards all methods to its - // implementation class. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <accept>s can - // started using this class. A ACE_Asynch_Accept::Result will - // be passed back to the <handler> when the asynchronous accept - // completes through the <ACE_Handler::handle_accept> - // callback. public: + /// A do nothing constructor. ACE_Asynch_Accept (void); - // A do nothing constructor. + /// Destructor. virtual ~ACE_Asynch_Accept (void); - // Destructor. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle = ACE_INVALID_HANDLE, const void *completion_key = 0, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. - + + /** + * This starts off an asynchronous accept. The asynchronous accept + * call also allows any initial data to be returned to the + * <handler>. Upto <bytes_to_read> will be read and stored in the + * <message_block>. The <accept_handle> will be used for the + * <accept> call. If (<accept_handle> == INVALID_HANDLE), a new + * handle will be created. Priority of the + * operation is specified by <priority>. On POSIX4-Unix, this is + * supported. Works like <nice> in Unix. Negative values are not + * allowed. 0 means priority of the operation same as the process + * priority. 1 means priority of the operation is one less than + * process. And so forth. On Win32, this is a no-op. + * + * <message_block> must be specified. This is because the address of + * the new connection is placed at the end of this buffer. + * <signal_number> is the POSIX4 real-time signal number to be used + * for the operation. <signal_number> ranges from ACE_SIGRTMIN to + * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + */ int accept (ACE_Message_Block &message_block, u_long bytes_to_read, ACE_HANDLE accept_handle = ACE_INVALID_HANDLE, const void *act = 0, int priority = 0, int signal_number = ACE_SIGRTMIN); - // This starts off an asynchronous accept. The asynchronous accept - // call also allows any initial data to be returned to the - // <handler>. Upto <bytes_to_read> will be read and stored in the - // <message_block>. The <accept_handle> will be used for the - // <accept> call. If (<accept_handle> == INVALID_HANDLE), a new - // handle will be created. Priority of the - // operation is specified by <priority>. On POSIX4-Unix, this is - // supported. Works like <nice> in Unix. Negative values are not - // allowed. 0 means priority of the operation same as the process - // priority. 1 means priority of the operation is one less than - // process. And so forth. On Win32, this is a no-op. - // - // <message_block> must be specified. This is because the address of - // the new connection is placed at the end of this buffer. - // <signal_number> is the POSIX4 real-time signal number to be used - // for the operation. <signal_number> ranges from ACE_SIGRTMIN to - // ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + /// Return the underlying implementation class. ACE_Asynch_Accept_Impl *implementation (void) const; - // Return the underlying implementation class. protected: + /// Set the implementation class. void implementation (ACE_Asynch_Accept_Impl *implementation); - // Set the implementation class. + /// Delegation/implementation class that all methods will be + /// forwarded to. ACE_Asynch_Accept_Impl *implementation_; - // Delegation/implementation class that all methods will be - // forwarded to. public: +/** + * @class Result + * + * @brief This is that class which will be passed back to the + * <handler> when the asynchronous accept completes. + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous accept. + */ class ACE_Export Result : public ACE_Asynch_Result { - // = TITLE - // - // This is that class which will be passed back to the - // <handler> when the asynchronous accept completes. - // - // = DESCRIPTION - // - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous accept. + /// The concrete implementation result classes only construct this + /// class. friend class ACE_POSIX_Asynch_Accept_Result; friend class ACE_WIN32_Asynch_Accept_Result; - // The concrete implementation result classes only construct this - // class. - + public: + /// The number of bytes which were requested at the start of the + /// asynchronous accept. u_long bytes_to_read (void) const; - // The number of bytes which were requested at the start of the - // asynchronous accept. + /// Message block which contains the read data. ACE_Message_Block &message_block (void) const; - // Message block which contains the read data. + /// I/O handle used for accepting new connections. ACE_HANDLE listen_handle (void) const; - // I/O handle used for accepting new connections. + /// I/O handle for the new connection. ACE_HANDLE accept_handle (void) const; - // I/O handle for the new connection. + /// Get the implementation. ACE_Asynch_Accept_Result_Impl *implementation (void) const; - // Get the implementation. - + protected: + /// Contructor. Implementation will not be deleted. Result (ACE_Asynch_Accept_Result_Impl *implementation); - // Contructor. Implementation will not be deleted. - + + /// Destructor. virtual ~Result (void); - // Destructor. + /// Impelmentation class. ACE_Asynch_Accept_Result_Impl *implementation_; - // Impelmentation class. }; }; @@ -787,47 +815,67 @@ public: class ACE_Asynch_Transmit_File_Result_Impl; class ACE_Asynch_Transmit_File_Impl; +/** + * @class ACE_Asynch_Transmit_File + * + * @brief This class is a factory for starting off asynchronous + * transmit files on a stream. + * + * Once <open> is called, multiple asynchronous <transmit_file>s + * can started using this class. A + * ACE_Asynch_Transmit_File::Result will be passed back to the + * <handler> when the asynchronous transmit file completes + * through the <ACE_Handler::handle_transmit_file> callback. + * The transmit_file function transmits file data over a + * connected network connection. The function uses the operating + * system's cache manager to retrieve the file data. This + * function provides high-performance file data transfer over + * network connections. This function would be of great use in + * a Web Server, Image Server, etc. + */ class ACE_Export ACE_Asynch_Transmit_File : public ACE_Asynch_Operation { - // = TITLE - // - // This class is a factory for starting off asynchronous - // transmit files on a stream. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <transmit_file>s - // can started using this class. A - // ACE_Asynch_Transmit_File::Result will be passed back to the - // <handler> when the asynchronous transmit file completes - // through the <ACE_Handler::handle_transmit_file> callback. - // - // The transmit_file function transmits file data over a - // connected network connection. The function uses the operating - // system's cache manager to retrieve the file data. This - // function provides high-performance file data transfer over - // network connections. This function would be of great use in - // a Web Server, Image Server, etc. public: // Forward declarations class Header_And_Trailer; - + + /// A do nothing constructor. ACE_Asynch_Transmit_File (void); - // A do nothing constructor. + /// Destructor. virtual ~ACE_Asynch_Transmit_File (void); - // Destructor. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle = ACE_INVALID_HANDLE, const void *completion_key = 0, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. - + + /** + * This starts off an asynchronous transmit file. The <file> is a + * handle to an open file. <header_and_trailer> is a pointer to a + * data structure that contains pointers to data to send before and + * after the file data is sent. Set this parameter to 0 if you only + * want to transmit the file data. Upto <bytes_to_write> will be + * written to the <socket>. If you want to send the entire file, + * let <bytes_to_write> = 0. <bytes_per_send> is the size of each + * block of data sent per send operation. Please read the Win32 + * documentation on what the flags should be. Priority of the + * operation is specified by <priority>. On POSIX4-Unix, this is + * supported. Works like <nice> in Unix. Negative values are not + * allowed. 0 means priority of the operation same as the process + * priority. 1 means priority of the operation is one less than + * process. And so forth. On Win32, this is a no-op. + * <signal_number> is the POSIX4 real-time signal number to be used + * for the operation. <signal_number> ranges from ACE_SIGRTMIN to + * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + */ int transmit_file (ACE_HANDLE file, Header_And_Trailer *header_and_trailer = 0, u_long bytes_to_write = 0, @@ -838,218 +886,207 @@ public: const void *act = 0, int priority = 0, int signal_number = ACE_SIGRTMIN); - // This starts off an asynchronous transmit file. The <file> is a - // handle to an open file. <header_and_trailer> is a pointer to a - // data structure that contains pointers to data to send before and - // after the file data is sent. Set this parameter to 0 if you only - // want to transmit the file data. Upto <bytes_to_write> will be - // written to the <socket>. If you want to send the entire file, - // let <bytes_to_write> = 0. <bytes_per_send> is the size of each - // block of data sent per send operation. Please read the Win32 - // documentation on what the flags should be. Priority of the - // operation is specified by <priority>. On POSIX4-Unix, this is - // supported. Works like <nice> in Unix. Negative values are not - // allowed. 0 means priority of the operation same as the process - // priority. 1 means priority of the operation is one less than - // process. And so forth. On Win32, this is a no-op. - // <signal_number> is the POSIX4 real-time signal number to be used - // for the operation. <signal_number> ranges from ACE_SIGRTMIN to - // ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. + /// Return the underlying implementation class. ACE_Asynch_Transmit_File_Impl *implementation (void) const; - // Return the underlying implementation class. protected: + /// Set the implementation. void implementation (ACE_Asynch_Transmit_File_Impl *); - // Set the implementation. + /// The implementation class. ACE_Asynch_Transmit_File_Impl *implementation_; - // The implementation class. public: +/** + * @class Result + * + * @brief This is that class which will be passed back to the + * <handler> when the asynchronous transmit file completes. + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous transmit file. + */ class ACE_Export Result : public ACE_Asynch_Result { - // = TITLE - // - // This is that class which will be passed back to the - // <handler> when the asynchronous transmit file completes. - // - // = DESCRIPTION - // - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous transmit file. + /// The concrete implementation result classes only construct this + /// class. friend class ACE_POSIX_Asynch_Transmit_File_Result; friend class ACE_WIN32_Asynch_Transmit_File_Result; - // The concrete implementation result classes only construct this - // class. - + public: + /// Socket used for transmitting the file. ACE_HANDLE socket (void) const; - // Socket used for transmitting the file. + /// File from which the data is read. ACE_HANDLE file (void) const; - // File from which the data is read. + /// Header and trailer data associated with this transmit file. Header_And_Trailer *header_and_trailer (void) const; - // Header and trailer data associated with this transmit file. - + + /// The number of bytes which were requested at the start of the + /// asynchronous transmit file. u_long bytes_to_write (void) const; - // The number of bytes which were requested at the start of the - // asynchronous transmit file. - + + /// Number of bytes per send requested at the start of the transmit + /// file. u_long bytes_per_send (void) const; - // Number of bytes per send requested at the start of the transmit - // file. - + + /// Flags which were passed into transmit file. u_long flags (void) const; - // Flags which were passed into transmit file. + /// Get the implementation class. ACE_Asynch_Transmit_File_Result_Impl *implementation (void) const; - // Get the implementation class. - + protected: + /// Constructor. Result (ACE_Asynch_Transmit_File_Result_Impl *implementation); - // Constructor. + /// Destructor. virtual ~Result (void); - // Destructor. - + + /// The implementation class. ACE_Asynch_Transmit_File_Result_Impl *implementation_; - // The implementation class. }; +/** + * @class Header_And_Trailer + * + * @brief The class defines a data structure that contains pointers + * to data to send before and after the file data is sent. + * + * This class provides a wrapper over TRANSMIT_FILE_BUFFERS + * and provided a consistent use of ACE_Message_Blocks. + */ class ACE_Export Header_And_Trailer { - // = TITLE - // - // The class defines a data structure that contains pointers - // to data to send before and after the file data is sent. - // - // = DESCRIPTION - // - // This class provides a wrapper over TRANSMIT_FILE_BUFFERS - // and provided a consistent use of ACE_Message_Blocks. public: + /// Constructor. Header_And_Trailer (ACE_Message_Block *header = 0, u_long header_bytes = 0, ACE_Message_Block *trailer = 0, u_long trailer_bytes = 0); - // Constructor. - + + /// Destructor virtual ~Header_And_Trailer (void); - // Destructor + /// This method allows all the member to be set in one fell swoop. void header_and_trailer (ACE_Message_Block *header = 0, u_long header_bytes = 0, ACE_Message_Block *trailer = 0, u_long trailer_bytes = 0); - // This method allows all the member to be set in one fell swoop. + /// Header which goes before the file data. ACE_Message_Block *header (void) const; void header (ACE_Message_Block *message_block); - // Header which goes before the file data. + /// Size of the header data. u_long header_bytes (void) const; void header_bytes (u_long bytes); - // Size of the header data. + /// Trailer which goes after the file data. ACE_Message_Block *trailer (void) const; void trailer (ACE_Message_Block *message_block); - // Trailer which goes after the file data. + /// Size of the trailer data. u_long trailer_bytes (void) const; void trailer_bytes (u_long bytes); - // Size of the trailer data. + /// Conversion routine. ACE_LPTRANSMIT_FILE_BUFFERS transmit_buffers (void); - // Conversion routine. protected: + /// Header data. ACE_Message_Block *header_; - // Header data. + /// Size of header data. u_long header_bytes_; - // Size of header data. + /// Trailer data. ACE_Message_Block *trailer_; - // Trailer data. + /// Size of trailer data. u_long trailer_bytes_; - // Size of trailer data. + /// Target data structure. ACE_TRANSMIT_FILE_BUFFERS transmit_buffers_; - // Target data structure. }; }; +/** + * @class ACE_Handler + * + * @brief This base class defines the interface for receiving the + * results of asynchronous operations. + * + * Subclasses of this class will fill in appropriate methods. + */ class ACE_Export ACE_Handler { - // = TITLE - // This base class defines the interface for receiving the - // results of asynchronous operations. - // - // = DESCRIPTION - // Subclasses of this class will fill in appropriate methods. public: + /// A do nothing constructor. ACE_Handler (void); - // A do nothing constructor. + /// A do nothing constructor which allows proactor to be set to <p>. ACE_Handler (ACE_Proactor *p); - // A do nothing constructor which allows proactor to be set to <p>. + /// Virtual destruction. virtual ~ACE_Handler (void); - // Virtual destruction. + /// This method will be called when an asynchronous read completes on + /// a stream. virtual void handle_read_stream (const ACE_Asynch_Read_Stream::Result &result); - // This method will be called when an asynchronous read completes on - // a stream. + /// This method will be called when an asynchronous write completes + /// on a stream. virtual void handle_write_stream (const ACE_Asynch_Write_Stream::Result &result); - // This method will be called when an asynchronous write completes - // on a stream. + /// This method will be called when an asynchronous read completes on + /// a file. virtual void handle_read_file (const ACE_Asynch_Read_File::Result &result); - // This method will be called when an asynchronous read completes on - // a file. + /// This method will be called when an asynchronous write completes + /// on a file. virtual void handle_write_file (const ACE_Asynch_Write_File::Result &result); - // This method will be called when an asynchronous write completes - // on a file. + /// This method will be called when an asynchronous accept completes. virtual void handle_accept (const ACE_Asynch_Accept::Result &result); - // This method will be called when an asynchronous accept completes. + /// This method will be called when an asynchronous transmit file + /// completes. virtual void handle_transmit_file (const ACE_Asynch_Transmit_File::Result &result); - // This method will be called when an asynchronous transmit file - // completes. + /// Called when timer expires. <tv> was the requested time value and + /// <act> is the ACT passed when scheduling the timer. virtual void handle_time_out (const ACE_Time_Value &tv, const void *act = 0); - // Called when timer expires. <tv> was the requested time value and - // <act> is the ACT passed when scheduling the timer. + /** + * This is method works with the <run_event_loop> of the + * ACE_Proactor. A special <Wake_Up_Completion> is used to wake up + * all the threads that are blocking for completions. + */ virtual void handle_wakeup (void); - // This is method works with the <run_event_loop> of the - // ACE_Proactor. A special <Wake_Up_Completion> is used to wake up - // all the threads that are blocking for completions. + /// Get the proactor associated with this handler. ACE_Proactor *proactor (void); - // Get the proactor associated with this handler. + /// Set the proactor. void proactor (ACE_Proactor *p); - // Set the proactor. + /** + * Get the I/O handle used by this <handler>. This method will be + * called by the ACE_Asynch_* classes when an ACE_INVALID_HANDLE is + * passed to <open>. + */ virtual ACE_HANDLE handle (void) const; - // Get the I/O handle used by this <handler>. This method will be - // called by the ACE_Asynch_* classes when an ACE_INVALID_HANDLE is - // passed to <open>. protected: + /// The proactor associated with this handler. ACE_Proactor *proactor_; - // The proactor associated with this handler. }; // Forward declarations @@ -1059,48 +1096,50 @@ class ACE_INET_Addr; template <class HANDLER> class ACE_Asynch_Acceptor; +/** + * @class ACE_Service_Handler + * + * @brief This base class defines the interface for the + * ACE_Asynch_Acceptor to call into when new connection are + * accepted. + * + * Subclasses of this class will fill in appropriate methods to + * define application specific behavior. + */ class ACE_Export ACE_Service_Handler : public ACE_Handler { - // = TITLE - // - // This base class defines the interface for the - // ACE_Asynch_Acceptor to call into when new connection are - // accepted. - // - // = DESCRIPTION - // - // Subclasses of this class will fill in appropriate methods to - // define application specific behavior. - + + /// The Acceptor is the factory and therefore should have special + /// privileges. friend class ACE_Asynch_Acceptor<ACE_Service_Handler>; - // The Acceptor is the factory and therefore should have special - // privileges. - + public: + /// A do nothing constructor. ACE_Service_Handler (void); - // A do nothing constructor. + /// Virtual destruction. virtual ~ACE_Service_Handler (void); - // Virtual destruction. + /** + * <open> is called by ACE_Asynch_Acceptor to initialize a new + * instance of ACE_Service_Handler that has been created after the a + * new connection is accepted. The handle for the new connection is + * passed along with an initial data that may have shown up. + */ virtual void open (ACE_HANDLE new_handle, ACE_Message_Block &message_block); - // <open> is called by ACE_Asynch_Acceptor to initialize a new - // instance of ACE_Service_Handler that has been created after the a - // new connection is accepted. The handle for the new connection is - // passed along with an initial data that may have shown up. // protected: // This should be corrected after the correct semantics of the // friend has been figured out. + /// Called by ACE_Asynch_Acceptor to pass the addresses of the new + /// connections. virtual void addresses (const ACE_INET_Addr &remote_address, const ACE_INET_Addr &local_address); - // Called by ACE_Asynch_Acceptor to pass the addresses of the new - // connections. + /// Called by ACE_Asynch_Acceptor to pass the act. virtual void act (const void *); - // Called by ACE_Asynch_Acceptor to pass the act. }; #endif /* ACE_WIN32 || ACE_HAS_AIO_CALLS*/ diff --git a/ace/Asynch_IO_Impl.h b/ace/Asynch_IO_Impl.h index db2a6bc475d..4d698eac064 100644 --- a/ace/Asynch_IO_Impl.h +++ b/ace/Asynch_IO_Impl.h @@ -1,29 +1,23 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// -// ace -// -// = FILENAME -// -// Asynch_IO_Impl.h -// -// = DESCRIPTION -// -// This class contains asbtract base classes for all the concrete -// implementation classes for the various asynchronous operations -// that are used with the Praoctor. -// -// = AUTHOR -// -// Irfan Pyarali (irfan@cs.wustl.edu), -// Tim Harrison (harrison@cs.wustl.edu) and -// Alexander Babu Arulanthu <alex@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Asynch_IO_Impl.h + * + * $Id$ + * + * + * This class contains asbtract base classes for all the concrete + * implementation classes for the various asynchronous operations + * that are used with the Praoctor. + * + * + * @author Irfan Pyarali (irfan@cs.wustl.edu) + * @author Tim Harrison (harrison@cs.wustl.edu) + * @author Alexander Babu Arulanthu <alex@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_ASYNCH_IO_IMPL_H #define ACE_ASYNCH_IO_IMPL_H @@ -42,223 +36,236 @@ // Forward declaration. class ACE_Proactor_Impl; +/** + * @class ACE_Asynch_Result_Impl + * + * @brief Abstract base class for the all the classes that provide + * concrete implementations for ACE_Asynch_Result. + * + */ class ACE_Export ACE_Asynch_Result_Impl { - // = TITLE - // - // Abstract base class for the all the classes that provide - // concrete implementations for ACE_Asynch_Result. - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Result_Impl (void); + /// Number of bytes transferred by the operation. virtual u_long bytes_transferred (void) const = 0; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. virtual const void *act (void) const = 0; - // ACT associated with the operation. + /// Did the operation succeed? virtual int success (void) const = 0; - // Did the operation succeed? + /// This ACT is not the same as the ACT associated with the + /// asynchronous operation. virtual const void *completion_key (void) const = 0; - // This ACT is not the same as the ACT associated with the - // asynchronous operation. + /// Error value if the operation fail. virtual u_long error (void) const = 0; - // Error value if the operation fail. + /// Event associated with the OVERLAPPED structure. virtual ACE_HANDLE event (void) const = 0; - // Event associated with the OVERLAPPED structure. + /// This really make sense only when doing file I/O. virtual u_long offset (void) const = 0; virtual u_long offset_high (void) const = 0; - // This really make sense only when doing file I/O. + /// Priority of the operation. virtual int priority (void) const = 0; - // Priority of the operation. + /** + * POSIX4 real-time signal number to be used for the + * operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By + * default, SIGRTMIN is used to issue <aio_> calls. This is a no-op + * on non-POSIX4 systems and returns 0. + */ virtual int signal_number (void) const = 0; - // POSIX4 real-time signal number to be used for the - // operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By - // default, SIGRTMIN is used to issue <aio_> calls. This is a no-op - // on non-POSIX4 systems and returns 0. // protected: // // These two should really be protected. But sometimes it // simplifies code to be able to "fake" a result. Use carefully. + /// This is called when the asynchronous operation completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error = 0) = 0; - // This is called when the asynchronous operation completes. + /// Post <this> to the Proactor's completion port. virtual int post_completion (ACE_Proactor_Impl *proactor) = 0; - // Post <this> to the Proactor's completion port. protected: + /// Do-nothing constructor. ACE_Asynch_Result_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Operation_Impl + * + * @brief Abstract base class for all the concrete implementation + * classes that provide different implementations for the + * ACE_Asynch_Operation. + */ class ACE_Export ACE_Asynch_Operation_Impl { - // = TITLE - // - // Abstract base class for all the concrete implementation - // classes that provide different implementations for the - // ACE_Asynch_Operation. public: virtual ~ACE_Asynch_Operation_Impl (void); + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ virtual int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor) = 0; - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * This cancels all pending accepts operations that were issued by + * the calling thread. The function does not cancel asynchronous + * operations issued by other threads. + */ virtual int cancel (void) = 0; - // This cancels all pending accepts operations that were issued by - // the calling thread. The function does not cancel asynchronous - // operations issued by other threads. // = Access methods. + /// Return the underlying proactor. virtual ACE_Proactor* proactor (void) const = 0; - // Return the underlying proactor. protected: + /// Do-nothing constructor. ACE_Asynch_Operation_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Read_Stream_Impl + * + * @brief Abstract base class for all the concrete implementation + * classes that provide different implementations for the + * ACE_Asynch_Read_Stream + * + */ class ACE_Export ACE_Asynch_Read_Stream_Impl : public virtual ACE_Asynch_Operation_Impl { - // = TITLE - // - // Abstract base class for all the concrete implementation - // classes that provide different implementations for the - // ACE_Asynch_Read_Stream - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Read_Stream_Impl (void); + /// This starts off an asynchronous read. Upto <bytes_to_read> will + /// be read and stored in the <message_block>. virtual int read (ACE_Message_Block &message_block, u_long bytes_to_read, const void *act, int priority, int signal_number) = 0; - // This starts off an asynchronous read. Upto <bytes_to_read> will - // be read and stored in the <message_block>. protected: + /// Do-nothing constructor. ACE_Asynch_Read_Stream_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Read_Stream_Result_Impl + * + * @brief Abstract base class for all the concrete implementation + * classes that provide different implementations for the + * ACE_Asynch_Read_Stream::Result class. + * + */ class ACE_Export ACE_Asynch_Read_Stream_Result_Impl : public virtual ACE_Asynch_Result_Impl { - // = TITLE - // - // Abstract base class for all the concrete implementation - // classes that provide different implementations for the - // ACE_Asynch_Read_Stream::Result class. - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Read_Stream_Result_Impl (void); + /// The number of bytes which were requested at the start of the + /// asynchronous read. virtual u_long bytes_to_read (void) const = 0; - // The number of bytes which were requested at the start of the - // asynchronous read. + /// Message block which contains the read data. virtual ACE_Message_Block &message_block (void) const = 0; - // Message block which contains the read data. + /// I/O handle used for reading. virtual ACE_HANDLE handle (void) const = 0; - // I/O handle used for reading. protected: + /// Do-nothing constructor. ACE_Asynch_Read_Stream_Result_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Write_Stream_Impl + * + * @brief Abstract base class for all the concrete implementation + * classes that provide different implementations for the + * ACE_Asynch_Write_Stream class. + * + */ class ACE_Export ACE_Asynch_Write_Stream_Impl : public virtual ACE_Asynch_Operation_Impl { - // = TITLE - // - // Abstract base class for all the concrete implementation - // classes that provide different implementations for the - // ACE_Asynch_Write_Stream class. - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Write_Stream_Impl (void); + /// This starts off an asynchronous write. Upto <bytes_to_write> + /// will be written from the <message_block>. virtual int write (ACE_Message_Block &message_block, u_long bytes_to_write, const void *act, int priority, int signal_number) = 0; - // This starts off an asynchronous write. Upto <bytes_to_write> - // will be written from the <message_block>. protected: + /// Do-nothing constructor. ACE_Asynch_Write_Stream_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Write_Stream_Result_Impl + * + * @brief Abstract base class for all the concrete implementation + * classes that provide different implementations for the + * ACE_Asynch_Write_Stream::Result. + * + */ class ACE_Export ACE_Asynch_Write_Stream_Result_Impl : public virtual ACE_Asynch_Result_Impl { - // = TITLE - // - // Abstract base class for all the concrete implementation - // classes that provide different implementations for the - // ACE_Asynch_Write_Stream::Result. - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Write_Stream_Result_Impl (void); + /// The number of bytes which were requested at the start of the + /// asynchronous write. virtual u_long bytes_to_write (void) const = 0; - // The number of bytes which were requested at the start of the - // asynchronous write. + /// Message block that contains the data to be written. virtual ACE_Message_Block &message_block (void) const = 0; - // Message block that contains the data to be written. + /// I/O handle used for writing. virtual ACE_HANDLE handle (void) const = 0; - // I/O handle used for writing. protected: + /// Do-nothing constructor. ACE_Asynch_Write_Stream_Result_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Read_File_Impl + * + * @brief Abstract base class for all the concrete implementation + * classes that provide different implementations for the + * ACE_Asynch_Read_File::Result. + * + */ class ACE_Export ACE_Asynch_Read_File_Impl : public virtual ACE_Asynch_Read_Stream_Impl { - // = TITLE - // - // Abstract base class for all the concrete implementation - // classes that provide different implementations for the - // ACE_Asynch_Read_File::Result. - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Read_File_Impl (void); + /** + * This starts off an asynchronous read. Upto <bytes_to_read> will + * be read and stored in the <message_block>. The read will start + * at <offset> from the beginning of the file. + */ virtual int read (ACE_Message_Block &message_block, u_long bytes_to_read, u_long offset, @@ -266,57 +273,60 @@ public: const void *act, int priority, int signal_number) = 0; - // This starts off an asynchronous read. Upto <bytes_to_read> will - // be read and stored in the <message_block>. The read will start - // at <offset> from the beginning of the file. // We don;t need to redefine the following function again because it // has already been defined in ACE_Asynch_Read_Stream_Impl. But we // still need it here to supress a overwriting pure virtual function // warning in KAI compiler. + /// This starts off an asynchronous read. Upto <bytes_to_read> will + /// be read and stored in the <message_block>. virtual int read (ACE_Message_Block &message_block, u_long bytes_to_read, const void *act, int priority, int signal_number) = 0; - // This starts off an asynchronous read. Upto <bytes_to_read> will - // be read and stored in the <message_block>. protected: + /// Do-nothing constructor. ACE_Asynch_Read_File_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Read_File_Result_Impl + * + * @brief This is the abstract base class for all the concrete + * implementation classes for ACE_Asynch_Read_File::Result. + * + */ class ACE_Export ACE_Asynch_Read_File_Result_Impl : public virtual ACE_Asynch_Read_Stream_Result_Impl { - // = TITLE - // This is the abstract base class for all the concrete - // implementation classes for ACE_Asynch_Read_File::Result. - // - // = DESCRIPTION - // public: + /// Destructor. virtual ~ACE_Asynch_Read_File_Result_Impl (void); - // Destructor. protected: + /// Do-nothing constructor. ACE_Asynch_Read_File_Result_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Write_File_Impl + * + * @brief Abstract base class for all the concrete implementation + * classes that provide different implementations for the + * ACE_Asynch_Write_File. + * + */ class ACE_Export ACE_Asynch_Write_File_Impl : public virtual ACE_Asynch_Write_Stream_Impl { - // = TITLE - // - // Abstract base class for all the concrete implementation - // classes that provide different implementations for the - // ACE_Asynch_Write_File. - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Write_File_Impl (void); + /** + * This starts off an asynchronous write. Upto <bytes_to_write> + * will be write and stored in the <message_block>. The write will + * start at <offset> from the beginning of the file. + */ virtual int write (ACE_Message_Block &message_block, u_long bytes_to_write, u_long offset, @@ -324,123 +334,123 @@ public: const void *act, int priority, int signal_number) = 0; - // This starts off an asynchronous write. Upto <bytes_to_write> - // will be write and stored in the <message_block>. The write will - // start at <offset> from the beginning of the file. // We don;t need to redefine the following function again because it // has already been defined in ACE_Asynch_Write_Stream_Impl. But we // still need it here to supress a overwriting pure virtual function // warning in KAI compiler. + /// This starts off an asynchronous write. Upto <bytes_to_write> + /// will be written from the <message_block>. virtual int write (ACE_Message_Block &message_block, u_long bytes_to_write, const void *act, int priority, int signal_number) = 0; - // This starts off an asynchronous write. Upto <bytes_to_write> - // will be written from the <message_block>. protected: + /// Do-nothing constructor. ACE_Asynch_Write_File_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Write_File_Result_Impl + * + * @brief This is the abstract base class for all the concrete + * implementation classes that provide different implementations + * for the ACE_Asynch_Write_File::Result. + * + */ class ACE_Export ACE_Asynch_Write_File_Result_Impl : public virtual ACE_Asynch_Write_Stream_Result_Impl { - // = TITLE - // - // This is the abstract base class for all the concrete - // implementation classes that provide different implementations - // for the ACE_Asynch_Write_File::Result. - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Write_File_Result_Impl (void); protected: + /// Do-nothing constructor. ACE_Asynch_Write_File_Result_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Accept_Impl + * + * @brief Abstract base class for all the concrete implementation + * classes that provide different implementations for the + * ACE_Asynch_Accept. + * + */ class ACE_Export ACE_Asynch_Accept_Impl : public virtual ACE_Asynch_Operation_Impl { - // = TITLE - // - // Abstract base class for all the concrete implementation - // classes that provide different implementations for the - // ACE_Asynch_Accept. - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Accept_Impl (void); + /** + * This starts off an asynchronous accept. The asynchronous accept + * call also allows any initial data to be returned to the + * <handler>. Upto <bytes_to_read> will be read and stored in the + * <message_block>. The <accept_handle> will be used for the + * <accept> call. If (<accept_handle> == INVALID_HANDLE), a new + * handle will be created. + * + * <message_block> must be specified. This is because the address of + * the new connection is placed at the end of this buffer. + */ virtual int accept (ACE_Message_Block &message_block, u_long bytes_to_read, ACE_HANDLE accept_handle, const void *act, int priority, int signal_number) = 0; - // This starts off an asynchronous accept. The asynchronous accept - // call also allows any initial data to be returned to the - // <handler>. Upto <bytes_to_read> will be read and stored in the - // <message_block>. The <accept_handle> will be used for the - // <accept> call. If (<accept_handle> == INVALID_HANDLE), a new - // handle will be created. - // - // <message_block> must be specified. This is because the address of - // the new connection is placed at the end of this buffer. protected: + /// Do-nothing constructor. ACE_Asynch_Accept_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Accept_Result_Impl + * + * @brief Abstract base class for all the concrete implementation + * classes that provide different implementations for the + * ACE_Asynch_Accept. + * + */ class ACE_Export ACE_Asynch_Accept_Result_Impl : public virtual ACE_Asynch_Result_Impl { - // = TITLE - // - // Abstract base class for all the concrete implementation - // classes that provide different implementations for the - // ACE_Asynch_Accept. - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Accept_Result_Impl (void); + /// The number of bytes which were requested at the start of the + /// asynchronous accept. virtual u_long bytes_to_read (void) const = 0; - // The number of bytes which were requested at the start of the - // asynchronous accept. + /// Message block which contains the read data. virtual ACE_Message_Block &message_block (void) const = 0; - // Message block which contains the read data. + /// I/O handle used for accepting new connections. virtual ACE_HANDLE listen_handle (void) const = 0; - // I/O handle used for accepting new connections. + /// I/O handle for the new connection. virtual ACE_HANDLE accept_handle (void) const = 0; - // I/O handle for the new connection. protected: + /// Do-nothing constructor. ACE_Asynch_Accept_Result_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Transmit_File_Impl + * + * @brief Abstract base class for all the concrete implementation + * classes that provide different implementations for the + * ACE_Asynch_Transmit_File. + * + */ class ACE_Asynch_Transmit_File_Impl : public virtual ACE_Asynch_Operation_Impl { - // = TITLE - // - // Abstract base class for all the concrete implementation - // classes that provide different implementations for the - // ACE_Asynch_Transmit_File. - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Transmit_File_Impl (void); + /// This starts off an asynchronous transmit file. virtual int transmit_file (ACE_HANDLE file, ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer, u_long bytes_to_write, @@ -451,49 +461,48 @@ public: const void *act, int priority, int signal_number) = 0; - // This starts off an asynchronous transmit file. protected: + /// Do-nothing constructor. ACE_Asynch_Transmit_File_Impl (void); - // Do-nothing constructor. }; +/** + * @class ACE_Asynch_Transmit_File_Result_Impl + * + * @brief Abstract base class for all the concrete implementation + * classes that provide different implementations for the + * ACE_Asynch_Transmit_File::Result. + * + */ class ACE_Export ACE_Asynch_Transmit_File_Result_Impl : public virtual ACE_Asynch_Result_Impl { - // = TITLE - // - // Abstract base class for all the concrete implementation - // classes that provide different implementations for the - // ACE_Asynch_Transmit_File::Result. - // - // = DESCRIPTION - // public: virtual ~ACE_Asynch_Transmit_File_Result_Impl (void); + /// Socket used for transmitting the file. virtual ACE_HANDLE socket (void) const = 0; - // Socket used for transmitting the file. + /// File from which the data is read. virtual ACE_HANDLE file (void) const = 0; - // File from which the data is read. + /// Header and trailer data associated with this transmit file. virtual ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer (void) const = 0; - // Header and trailer data associated with this transmit file. + /// The number of bytes which were requested at the start of the + /// asynchronous transmit file. virtual u_long bytes_to_write (void) const = 0; - // The number of bytes which were requested at the start of the - // asynchronous transmit file. + /// Number of bytes per send requested at the start of the transmit + /// file. virtual u_long bytes_per_send (void) const = 0; - // Number of bytes per send requested at the start of the transmit - // file. + /// Flags which were passed into transmit file. virtual u_long flags (void) const = 0; - // Flags which were passed into transmit file. protected: + /// Do-nothing constructor. ACE_Asynch_Transmit_File_Result_Impl (void); - // Do-nothing constructor. }; #if defined (__ACE_INLINE__) diff --git a/ace/Auto_IncDec_T.h b/ace/Auto_IncDec_T.h index 39a8818ae81..f2a10e498f8 100644 --- a/ace/Auto_IncDec_T.h +++ b/ace/Auto_IncDec_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -//============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Auto_IncDec_T.h -// -// = AUTHOR -// Edan Ayal <EdanA@cti2.com> -// -//============================================================================ +//============================================================================= +/** + * @file Auto_IncDec_T.h + * + * $Id$ + * + * @author Edan Ayal <EdanA@cti2.com> + */ +//============================================================================= + #ifndef ACE_AUTO_INCDEC_T_H #define ACE_AUTO_INCDEC_T_H @@ -24,33 +21,35 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Auto_IncDec + * + * @brief This class automatically increments and decrements a + * parameterized counter. + * + * This data structure is meant to be used within a method, + * function, or scope. The actual parameter given for the + * <ACE_SAFELY_INCREMENTABLE_DECREMENTABLE> template parameter + * must provide at least opertaors ++ and --. + */ template <class ACE_SAFELY_INCREMENTABLE_DECREMENTABLE> class ACE_Auto_IncDec { - // = TITLE - // This class automatically increments and decrements a - // parameterized counter. - // - // = DESCRIPTION - // This data structure is meant to be used within a method, - // function, or scope. The actual parameter given for the - // <ACE_SAFELY_INCREMENTABLE_DECREMENTABLE> template parameter - // must provide at least opertaors ++ and --. public: // = Initialization and termination methods. + /// Implicitly increment the counter. ACE_Auto_IncDec (ACE_SAFELY_INCREMENTABLE_DECREMENTABLE &counter); - // Implicitly increment the counter. + /// Implicitly decrement the counter. ~ACE_Auto_IncDec (void); - // Implicitly decrement the counter. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. protected: + /// Reference to the <ACE_SAFELY_INCREMENTABLE_DECREMENTABLE> counter + /// we're incrementing/decrementing. ACE_SAFELY_INCREMENTABLE_DECREMENTABLE &counter_; - // Reference to the <ACE_SAFELY_INCREMENTABLE_DECREMENTABLE> counter - // we're incrementing/decrementing. private: // = Prevent assignment and initialization. diff --git a/ace/Auto_Ptr.h b/ace/Auto_Ptr.h index a6fe119eb12..104e917d9aa 100644 --- a/ace/Auto_Ptr.h +++ b/ace/Auto_Ptr.h @@ -1,20 +1,18 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Auto_Ptr.h -// -// = AUTHOR -// Doug Schmidt and Irfan Pyarali, based on code from Jack Reeves -// (jack@fx.com) and Dr. Harald M. Mueller -// (mueller@garwein.hai.siemens.co.at) -// -// ============================================================================ + +//============================================================================= +/** + * @file Auto_Ptr.h + * + * $Id$ + * + * @author Doug Schmidt + * @author and Irfan Pyarali + * @author Jack Reeves (jack@fx.com) + * @author Dr. Harald M. Mueller (mueller@garwein.hai.siemens.co.at) + */ +//============================================================================= + #ifndef ACE_AUTO_PTR_H #define ACE_AUTO_PTR_H @@ -26,12 +24,15 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Auto_Basic_Ptr + * + * @brief Implements the draft C++ standard auto_ptr abstraction. + * This class allows one to work on non-object (basic) types + */ template <class X> class ACE_Auto_Basic_Ptr { - // = TITLE - // Implements the draft C++ standard auto_ptr abstraction. - // This class allows one to work on non-object (basic) types public: // = Initialization and termination methods ACE_EXPLICIT ACE_Auto_Basic_Ptr (X *p = 0) : p_ (p) {} @@ -46,11 +47,11 @@ public: X *release (void); void reset (X *p = 0); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: X *p_; @@ -66,11 +67,14 @@ using std::auto_ptr; #endif /* ACE_USES_STD_NAMESPACE_FOR_STDCPP_LIB */ #else /* ACE_HAS_STANDARD_CPP_LIBRARY */ +/** + * @class auto_ptr + * + * @brief Implements the draft C++ standard auto_ptr abstraction. + */ template <class X> class auto_ptr : public ACE_Auto_Basic_Ptr <X> { - // = TITLE - // Implements the draft C++ standard auto_ptr abstraction. public: // = Initialization and termination methods ACE_EXPLICIT auto_ptr (X *p = 0) : ACE_Auto_Basic_Ptr<X> (p) {} @@ -80,14 +84,17 @@ public: #endif /* ACE_HAS_STANDARD_CPP_LIBRARY */ +/** + * @class ACE_Auto_Basic_Array_Ptr + * + * @brief Implements an extension to the draft C++ standard auto_ptr + * abstraction. This class allows one to work on non-object + * (basic) types that must be treated as an array, e.g., + * deallocated via "delete [] foo". + */ template<class X> class ACE_Auto_Basic_Array_Ptr { - // = TITLE - // Implements an extension to the draft C++ standard auto_ptr - // abstraction. This class allows one to work on non-object - // (basic) types that must be treated as an array, e.g., - // deallocated via "delete [] foo". public: // = Initialization and termination methods. ACE_EXPLICIT ACE_Auto_Basic_Array_Ptr (X *p = 0) : p_ (p) {} @@ -103,25 +110,28 @@ public: X *release (void); void reset (X *p = 0); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: X *p_; }; +/** + * @class ACE_Auto_Array_Ptr + * + * @brief Implements an extension to the draft C++ standard auto_ptr + * abstraction. + */ template<class X> class ACE_Auto_Array_Ptr : public ACE_Auto_Basic_Array_Ptr<X> { - // = TITLE - // Implements an extension to the draft C++ standard auto_ptr - // abstraction. public: // = Initialization and termination methods. - ACE_EXPLICIT ACE_Auto_Array_Ptr (X *p = 0) + ACE_EXPLICIT ACE_Auto_Array_Ptr (X *p = 0) : ACE_Auto_Basic_Array_Ptr<X> (p) {} X *operator-> () const; diff --git a/ace/Base_Thread_Adapter.h b/ace/Base_Thread_Adapter.h index 1890f83f7c4..14dca42a50b 100644 --- a/ace/Base_Thread_Adapter.h +++ b/ace/Base_Thread_Adapter.h @@ -1,17 +1,14 @@ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Base_Thread_Adapter.h -// -// = AUTHOR -// Carlos O'Ryan <coryan@uci.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Base_Thread_Adapter.h + * + * $Id$ + * + * @author Nanbor Wang <nanbor@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_BASE_THREAD_ADAPTER_H #define ACE_BASE_THREAD_ADAPTER_H @@ -33,45 +30,51 @@ extern "C" void ace_thread_adapter (unsigned long args); extern "C" ACE_Export void *ace_thread_adapter (void *args); #endif /* ACE_PSOS */ +/** + * @class ACE_OS_Thread_Descriptor + * + * @brief Parent class of all ACE_Thread_Descriptor classes. + * = + * Container for ACE_Thread_Descriptor members that are + * used in ACE_OS. + */ class ACE_OS_Export ACE_OS_Thread_Descriptor { - // = TITLE - // Parent class of all ACE_Thread_Descriptor classes. - // - // = - // Container for ACE_Thread_Descriptor members that are - // used in ACE_OS. public: + /// Get the thread creation flags. long flags (void) const; - // Get the thread creation flags. protected: + /// For use by ACE_Thread_Descriptor. ACE_OS_Thread_Descriptor (long flags = 0); - // For use by ACE_Thread_Descriptor. + /** + * Keeps track of whether this thread was created "detached" or not. + * If a thread is *not* created detached then if someone calls + * <ACE_Thread_Manager::wait>, we need to join with that thread (and + * close down the handle). + */ long flags_; - // Keeps track of whether this thread was created "detached" or not. - // If a thread is *not* created detached then if someone calls - // <ACE_Thread_Manager::wait>, we need to join with that thread (and - // close down the handle). }; +/** + * @class ACE_Base_Thread_Adapter + * + * @brief Base class for all the Thread_Adapters. + * + * Converts a C++ function into a function <ace_thread_adapter> + * function that can be called from a thread creation routine + * (e.g., <pthread_create> or <_beginthreadex>) that expects an + * extern "C" entry point. This class also makes it possible to + * transparently provide hooks to register a thread with an + * <ACE_Thread_Manager>. + * This class is used in <ACE_OS::thr_create>. In general, the + * thread that creates an object of this class is different from + * the thread that calls <invoke> on this object. Therefore, + * the <invoke> method is responsible for deleting itself. + */ class ACE_OS_Export ACE_Base_Thread_Adapter { - // = TITLE - // Base class for all the Thread_Adapters. - // - // = DESCRIPTION - // Converts a C++ function into a function <ace_thread_adapter> - // function that can be called from a thread creation routine - // (e.g., <pthread_create> or <_beginthreadex>) that expects an - // extern "C" entry point. This class also makes it possible to - // transparently provide hooks to register a thread with an - // <ACE_Thread_Manager>. - // This class is used in <ACE_OS::thr_create>. In general, the - // thread that creates an object of this class is different from - // the thread that calls <invoke> on this object. Therefore, - // the <invoke> method is responsible for deleting itself. public: ACE_Base_Thread_Adapter (ACE_THR_FUNC user_func, void *arg, @@ -81,75 +84,77 @@ public: , ACE_SEH_EXCEPT_HANDLER selector = 0 , ACE_SEH_EXCEPT_HANDLER handler = 0 # endif /* ACE_HAS_WIN32_STRUCTURAL_EXCEPTIONS */ + /// Constructor. ); - // Constructor. + /// Virtual method invoked by the thread entry point. virtual void *invoke (void) = 0; - // Virtual method invoked by the thread entry point. + /// Accessor for the C entry point function to the OS thread creation + /// routine. ACE_THR_C_FUNC entry_point (void); - // Accessor for the C entry point function to the OS thread creation - // routine. + /// Invoke the close_log_msg_hook, if it is present static void close_log_msg (void); - // Invoke the close_log_msg_hook, if it is present + /// Invoke the sync_log_msg_hook, if it is present static void sync_log_msg (const ACE_TCHAR *prog_name); - // Invoke the sync_log_msg_hook, if it is present + /// Invoke the thr_desc_log_msg_hook, if it is present static ACE_OS_Thread_Descriptor *thr_desc_log_msg (void); - // Invoke the thr_desc_log_msg_hook, if it is present protected: + /// Destructor, making it private ensures that objects of this class + /// are allocated on the heap. virtual ~ACE_Base_Thread_Adapter (void); - // Destructor, making it private ensures that objects of this class - // are allocated on the heap. + /// Inherit the logging features if the parent thread has an + /// <ACE_Log_Msg>. void inherit_log_msg (void); - // Inherit the logging features if the parent thread has an - // <ACE_Log_Msg>. private: + /// The hooks to inherit and cleanup the Log_Msg attributes static ACE_INIT_LOG_MSG_HOOK init_log_msg_hook_; static ACE_INHERIT_LOG_MSG_HOOK inherit_log_msg_hook_; static ACE_CLOSE_LOG_MSG_HOOK close_log_msg_hook_; static ACE_SYNC_LOG_MSG_HOOK sync_log_msg_hook_; static ACE_THR_DESC_LOG_MSG_HOOK thr_desc_log_msg_hook_; - // The hooks to inherit and cleanup the Log_Msg attributes + /// Set the Log_Msg hooks static void set_log_msg_hooks (ACE_INIT_LOG_MSG_HOOK init_hook, ACE_INHERIT_LOG_MSG_HOOK inherit_hook, ACE_CLOSE_LOG_MSG_HOOK close_hook, ACE_SYNC_LOG_MSG_HOOK sync_hook, ACE_THR_DESC_LOG_MSG_HOOK thr_desc); - // Set the Log_Msg hooks + /// Allow the ACE_Log_Msg class to set its hooks. friend class ACE_Log_Msg; - // Allow the ACE_Log_Msg class to set its hooks. protected: + /// Thread startup function passed in by the user (C++ linkage). ACE_THR_FUNC user_func_; - // Thread startup function passed in by the user (C++ linkage). + /// Argument to thread startup function. void *arg_; - // Argument to thread startup function. + /// Entry point to the underlying OS thread creation call (C + /// linkage). ACE_THR_C_FUNC entry_point_; - // Entry point to the underlying OS thread creation call (C - // linkage). + /** + * Optional thread descriptor. Passing this pointer in will force + * the spawned thread to cache this location in <Log_Msg> and wait + * until <Thread_Manager> fills in all information in thread + * descriptor. + */ ACE_OS_Thread_Descriptor *thr_desc_; - // Optional thread descriptor. Passing this pointer in will force - // the spawned thread to cache this location in <Log_Msg> and wait - // until <Thread_Manager> fills in all information in thread - // descriptor. + /// The ACE_Log_Msg attributes. ACE_OS_Log_Msg_Attributes log_msg_attributes_; - // The ACE_Log_Msg attributes. + /// Friend declaration to avoid compiler warning: only defines a private + /// destructor and has no friends. friend class ACE_Thread_Adapter_Has_Private_Destructor; - // Friend declaration to avoid compiler warning: only defines a private - // destructor and has no friends. }; # if defined (ACE_HAS_INLINED_OSCALLS) diff --git a/ace/Based_Pointer_Repository.h b/ace/Based_Pointer_Repository.h index 7873daaacd7..2b14c52fa9f 100644 --- a/ace/Based_Pointer_Repository.h +++ b/ace/Based_Pointer_Repository.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Based_Pointer_Repository.h -// -// = AUTHOR -// Dietrich Quehl <Dietrich.Quehl@med.siemens.de> and -// Douglas C. Schmidt <schmidt@.cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Based_Pointer_Repository.h + * + * $Id$ + * + * @author Dietrich Quehl <Dietrich.Quehl@med.siemens.de> + * @author Douglas C. Schmidt <schmidt@.cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_BASED_POINTER_REPOSITORY_H #define ACE_BASED_POINTER_REPOSITORY_H @@ -24,11 +21,14 @@ // Forward decl., using the "Cheshire Cat" technique. class ACE_Based_Pointer_Repository_Rep; +/** + * @class ACE_Based_Pointer_Repository + * + * @brief Maps pointers to the base address of the region to which each + * pointer belongs. + */ class ACE_Export ACE_Based_Pointer_Repository { - // = TITLE - // Maps pointers to the base address of the region to which each - // pointer belongs. public: // = Use <ACE_Null_Mutex> to allow locking while iterating. @@ -37,30 +37,32 @@ public: ~ACE_Based_Pointer_Repository (void); // = Search structure methods. - int find (void *addr, + /** + * Return the appropriate <base_addr> region that contains <addr>. + * Returns 1 on success and 0 if the <addr> isn't contained in any + * <base_addr> region. + */ + int find (void *addr, void *&base_addr); - // Return the appropriate <base_addr> region that contains <addr>. - // Returns 1 on success and 0 if the <addr> isn't contained in any - // <base_addr> region. + /// Bind a new entry to the repository or update the size of an + /// existing entry. Returns 0 on success and -1 on failure. int bind (void *addr, size_t size); - // Bind a new entry to the repository or update the size of an - // existing entry. Returns 0 on success and -1 on failure. + /// Unbind from the repository the <base_addr> that <addr> is + /// contained within. int unbind (void *addr); - // Unbind from the repository the <base_addr> that <addr> is - // contained within. private: + /// Use the "Cheshire-Cat" technique to hide the implementation in + /// order to avoid circular #include dependencies. ACE_Based_Pointer_Repository_Rep *rep_; - // Use the "Cheshire-Cat" technique to hide the implementation in - // order to avoid circular #include dependencies. }; #include "ace/Singleton.h" -// Provide a Singleton access point to the based pointer repository. +/// Provide a Singleton access point to the based pointer repository. typedef ACE_Singleton<ACE_Based_Pointer_Repository, ACE_SYNCH_RW_MUTEX> ACE_BASED_POINTER_REPOSITORY; diff --git a/ace/Based_Pointer_T.h b/ace/Based_Pointer_T.h index 3ae2f0cc833..e06f6b3b692 100644 --- a/ace/Based_Pointer_T.h +++ b/ace/Based_Pointer_T.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Based_Pointer_T.h -// -// = AUTHOR -// Dietrich Quehl <Dietrich.Quehl@med.siemens.de> and -// Douglas C. Schmidt <schmidt@.cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Based_Pointer_T.h + * + * $Id$ + * + * @author Dietrich Quehl <Dietrich.Quehl@med.siemens.de> + * @author Douglas C. Schmidt <schmidt@.cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_BASED_POINTER_T_H #define ACE_BASED_POINTER_T_H @@ -29,148 +26,156 @@ #pragma warning(disable: 4284) #endif /* _MSC_VER */ +/** + * @class ACE_Based_Pointer_Basic + * + * @brief A proxy that keeps track of the relative offset of a "pointer" + * from its base address. + * This class makes it possible to transparently use "pointers" in + * shared memory as easily as programming with pointers to local + * memory. In particular, we don't need to ensure that the base + * addresses of all the pointers are mapped into separate + * processes at the same absolute memory base address. + */ template <class CONCRETE> class ACE_Based_Pointer_Basic { - // = TITLE - // A proxy that keeps track of the relative offset of a "pointer" - // from its base address. - // - // This class makes it possible to transparently use "pointers" in - // shared memory as easily as programming with pointers to local - // memory. In particular, we don't need to ensure that the base - // addresses of all the pointers are mapped into separate - // processes at the same absolute memory base address. public: + /** + * This constructor initializes the <base_offset_> by asking the + * <ACE_BASED_POINTER_REPOSITORY> Singleton for the base address of + * the memory region within which it is instantiated. Two results + * are possible: + * + * 1. An <ACE_*_Memory_Pool> has stored a base address/size pair and the + * new based-pointer instance is located between the base address and + * the base address + size - 1. In this case, the repository + * returns the base address. + * + * 2. No suitable address/size pair was found. The repository + * assumes an address in the regular (not mapped) virtual address + * space of the process and returns 0. In this case, the + * based-pointer uses its address as an offset to it's base + * address 0. + */ ACE_Based_Pointer_Basic (void); - // This constructor initializes the <base_offset_> by asking the - // <ACE_BASED_POINTER_REPOSITORY> Singleton for the base address of - // the memory region within which it is instantiated. Two results - // are possible: - // - // 1. An <ACE_*_Memory_Pool> has stored a base address/size pair and the - // new based-pointer instance is located between the base address and - // the base address + size - 1. In this case, the repository - // returns the base address. - // - // 2. No suitable address/size pair was found. The repository - // assumes an address in the regular (not mapped) virtual address - // space of the process and returns 0. In this case, the - // based-pointer uses its address as an offset to it's base - // address 0. + /** + * Initialize this object using the <initial> pointer. This + * constructor initializes the <base_offset_> by asking the + * <ACE_BASED_POINTER_REPOSITORY> Singleton for the base address of + * the memory region within which it is instantiated. Two results + * are possible: + * + * 1. An <ACE_*_Memory_Pool> has stored a base address/size pair and the + * new based-pointer instance is located between the base address and + * the base address + size - 1. In this case, the repository + * returns the base address. + * + * 2. No suitable address/size pair was found. The repository + * assumes an address in the regular (not mapped) virtual address + * space of the process and returns 0. In this case, the + * based-pointer uses its address as an offset to it's base + * address 0. + */ ACE_Based_Pointer_Basic (CONCRETE *initial); - // Initialize this object using the <initial> pointer. This - // constructor initializes the <base_offset_> by asking the - // <ACE_BASED_POINTER_REPOSITORY> Singleton for the base address of - // the memory region within which it is instantiated. Two results - // are possible: - // - // 1. An <ACE_*_Memory_Pool> has stored a base address/size pair and the - // new based-pointer instance is located between the base address and - // the base address + size - 1. In this case, the repository - // returns the base address. - // - // 2. No suitable address/size pair was found. The repository - // assumes an address in the regular (not mapped) virtual address - // space of the process and returns 0. In this case, the - // based-pointer uses its address as an offset to it's base - // address 0. + /// Copy constructor. ACE_Based_Pointer_Basic (const ACE_Based_Pointer_Basic<CONCRETE> &); - // Copy constructor. + /// Constructor for know base address. <o> is only used to + /// resolve overload ambiguity. ACE_Based_Pointer_Basic (const void *base_addr, int o); - // Constructor for know base address. <o> is only used to - // resolve overload ambiguity. + /// Pseudo-assignment operator. void operator = (CONCRETE *from); - // Pseudo-assignment operator. + /// Pseudo-assignment operator. void operator = (const ACE_Based_Pointer_Basic<CONCRETE> &); - // Pseudo-assignment operator. + /// Dereference operator. CONCRETE operator * (void) const; - // Dereference operator. + /// Less than operator. int operator < (const ACE_Based_Pointer_Basic<CONCRETE> &) const; - // Less than operator. + /// Less than or equal operator. int operator <= (const ACE_Based_Pointer_Basic<CONCRETE> &) const; - // Less than or equal operator. + /// Greater than operator. int operator > (const ACE_Based_Pointer_Basic<CONCRETE> &) const; - // Greater than operator. + /// Greater than or equal operator. int operator >= (const ACE_Based_Pointer_Basic<CONCRETE> &) const; - // Greater than or equal operator. + /// Equality operator. int operator == (const ACE_Based_Pointer_Basic<CONCRETE> &) const; - // Equality operator. + /// Inequality operator. int operator != (const ACE_Based_Pointer_Basic<CONCRETE> &) const; - // Inequality operator. + /// Subscript operator. CONCRETE operator [](int index) const; - // Subscript operator. + /// Increment operator. void operator+= (int index); - // Increment operator. + /// Returns the underlying memory address of the smart pointer. operator CONCRETE *() const; - // Returns the underlying memory address of the smart pointer. + /// Returns the underlying memory address of the smart pointer. CONCRETE *addr (void) const; - // Returns the underlying memory address of the smart pointer. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /// Dump the state of the object. void dump (void) const; - // Dump the state of the object. protected: long target_; + /// Keep track of our offset from the base pointer. long base_offset_; - // Keep track of our offset from the base pointer. }; +/** + * @class ACE_Based_Pointer + * + * @brief A smart proxy that keeps track of the relative offset of a + * "pointer" from its base address. + * + * This class makes it possible to transparently use "pointers" in + * shared memory as easily as programming with pointers to local + * memory by overloading the C++ delegation operator ->(). + */ template <class CONCRETE> class ACE_Based_Pointer : public ACE_Based_Pointer_Basic<CONCRETE> { - // = TITLE - // A smart proxy that keeps track of the relative offset of a - // "pointer" from its base address. - // - // = DESCRIPTION - // This class makes it possible to transparently use "pointers" in - // shared memory as easily as programming with pointers to local - // memory by overloading the C++ delegation operator ->(). public: // = Initialization method. + /// Constructor. See constructor for <ACE_Based_Pointer_Basic> for + /// details. ACE_Based_Pointer (void); - // Constructor. See constructor for <ACE_Based_Pointer_Basic> for - // details. + /// Initialize this object using the <initial> pointer. ACE_Based_Pointer (CONCRETE *initial); - // Initialize this object using the <initial> pointer. + /// Initialize this object with known <base_addr>. <o> is + /// only used to resolve overload ambiguity. ACE_Based_Pointer (const void *base_addr, int o); - // Initialize this object with known <base_addr>. <o> is - // only used to resolve overload ambiguity. + /// Copy constructor (not implemented yet). ACE_Based_Pointer (const ACE_Based_Pointer<CONCRETE> &); - // Copy constructor (not implemented yet). + /// Assignment operator. void operator = (const ACE_Based_Pointer<CONCRETE> &); - // Assignment operator. + /// Pseudo-assignment operator. void operator = (CONCRETE *from); - // Pseudo-assignment operator. + /// The C++ "delegation operator". CONCRETE *operator-> (void); - // The C++ "delegation operator". }; #if defined (__ACE_INLINE__) diff --git a/ace/Basic_Stats.h b/ace/Basic_Stats.h index da7e0dd1acf..722c92ae355 100644 --- a/ace/Basic_Stats.h +++ b/ace/Basic_Stats.h @@ -1,17 +1,14 @@ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Basic_Stats.h -// -// = AUTHOR -// Carlos O'Ryan <coryan@uci.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Basic_Stats.h + * + * $Id$ + * + * @author Carlos O'Ryan <coryan@uci.edu> + */ +//============================================================================= + #ifndef ACE_BASIC_STATS_H #define ACE_BASIC_STATS_H @@ -65,14 +62,19 @@ private: /// The minimum value ACE_UINT64 min_; + /// The number of the sample that had the minimum value ACE_UINT32 min_at_; + /// The maximum value ACE_UINT64 max_; + /// The number of the sample that had the maximum value ACE_UINT32 max_at_; + /// The sum of all the values ACE_UINT64 sum_; + /// The sum of the square of all the values ACE_UINT64 sum2_; }; diff --git a/ace/Basic_Types.h b/ace/Basic_Types.h index 2ce0a275ec8..0dbf2435daf 100644 --- a/ace/Basic_Types.h +++ b/ace/Basic_Types.h @@ -1,49 +1,46 @@ // -*- C++ -*- -// -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Basic_Types.h -// -// = AUTHORS -// David L. Levine -// -// = DESCRIPTION -// #defines the list of preprocessor macros below. The config.h file can -// pre-define any of these to short-cut the definitions. This is usually -// only necessary if the preprocessor does all of its math using integers. -// -// Sizes of built-in types: -// ACE_SIZEOF_CHAR -// ACE_SIZEOF_WCHAR -// ACE_SIZEOF_SHORT -// ACE_SIZEOF_INT -// ACE_SIZEOF_LONG -// ACE_SIZEOF_LONG_LONG -// ACE_SIZEOF_VOID_P -// ACE_SIZEOF_FLOAT -// ACE_SIZEOF_DOUBLE -// ACE_SIZEOF_LONG_DOUBLE -// -// Wrappers for built-in types of specific sizes: -// ACE_USHORT16 /* For backward compatibility. Use ACE_UINT16 instead. */ -// ACE_INT16 -// ACE_UINT16 -// ACE_INT32 -// ACE_UINT32 -// ACE_UINT64 -// (Note: ACE_INT64 is not defined, because there is no ACE_LongLong for -// platforms that don't have a native 8-byte integer type.) -// -// Byte-order (endian-ness) determination: -// ACE_BYTE_ORDER, to either ACE_BIG_ENDIAN or ACE_LITTLE_ENDIAN -// -// ============================================================================ + +//============================================================================= +/** + * @file Basic_Types.h + * + * $Id$ + * + * @author David L. Levine + * + * #defines the list of preprocessor macros below. The config.h file can + * pre-define any of these to short-cut the definitions. This is usually + * only necessary if the preprocessor does all of its math using integers. + * + * Sizes of built-in types: + * - ACE_SIZEOF_CHAR + * - ACE_SIZEOF_WCHAR + * - ACE_SIZEOF_SHORT + * - ACE_SIZEOF_INT + * - ACE_SIZEOF_LONG + * - ACE_SIZEOF_LONG_LONG + * - ACE_SIZEOF_VOID_P + * - ACE_SIZEOF_FLOAT + * - ACE_SIZEOF_DOUBLE + * - ACE_SIZEOF_LONG_DOUBLE + * + * Wrappers for built-in types of specific sizes: + * - ACE_USHORT16 (For backward compatibility. Use ACE_UINT16 instead.) + * - ACE_INT16 + * - ACE_UINT16 + * - ACE_INT32 + * - ACE_UINT32 + * - ACE_UINT64 + * (Note: ACE_INT64 is not defined, because there is no ACE_LongLong for + * platforms that don't have a native 8-byte integer type.) + * + * Byte-order (endian-ness) determination: + * ACE_BYTE_ORDER, to either ACE_BIG_ENDIAN or ACE_LITTLE_ENDIAN + * + * + */ +//============================================================================= + #ifndef ACE_BASIC_TYPES_H # define ACE_BASIC_TYPES_H @@ -260,19 +257,21 @@ typedef ACE_UINT16 ACE_USHORT16; // If the platform lacks a long long, define one. # if defined (ACE_LACKS_LONGLONG_T) +/** + * @class ACE_U_LongLong + * + * @brief Unsigned long long for platforms that don't have one. + * + * Provide our own unsigned long long. This is intended to be + * use with ACE_High_Res_Timer, so the division operator assumes + * that the quotient fits into a u_long. + * Please note that the constructor takes (optionally) two values. + * The high one contributes 0x100000000 times its value. So, + * for example, (0, 2) is _not_ 20000000000, but instead + * 0x200000000. To emphasize this, the default values are expressed + * in hex, and output () dumps the value in hex. + */ class ACE_Export ACE_U_LongLong - // = TITLE - // Unsigned long long for platforms that don't have one. - // - // = DESCRIPTION - // Provide our own unsigned long long. This is intended to be - // use with ACE_High_Res_Timer, so the division operator assumes - // that the quotient fits into a u_long. - // Please note that the constructor takes (optionally) two values. - // The high one contributes 0x100000000 times its value. So, - // for example, (0, 2) is _not_ 20000000000, but instead - // 0x200000000. To emphasize this, the default values are expressed - // in hex, and output () dumps the value in hex. { public: // = Initialization and termination methods. @@ -347,8 +346,8 @@ typedef ACE_UINT16 ACE_USHORT16; # endif /* ACE_SIZEOF_INT != 4 */ // = Helper methods. + /// Outputs the value to the FILE, in hex. void output (FILE * = stdout) const; - // Outputs the value to the FILE, in hex. ACE_UINT32 hi (void) const; ACE_UINT32 lo (void) const; @@ -379,22 +378,23 @@ typedef ACE_UINT16 ACE_USHORT16; // order to minimize the extent of the data_ struct. It's // only used here; the .i and .cpp files use the accessors. + /// Internal utility function to hide access through struct. const ACE_UINT32 &h_ () const { return data_.hi_; } - // Internal utility function to hide access through struct. + /// Internal utility function to hide access through struct. ACE_UINT32 &h_ () { return data_.hi_; } - // Internal utility function to hide access through struct. + /// Internal utility function to hide access through struct. const ACE_UINT32 &l_ () const { return data_.lo_; } - // Internal utility function to hide access through struct. + /// Internal utility function to hide access through struct. ACE_UINT32 &l_ () { return data_.lo_; } - // Internal utility function to hide access through struct. // NOTE: the above four accessors are inlined here in // order to minimize the extent of the data_ struct. It's // only used here; the .i and .cpp files use the accessors. + /// These functions are used to implement multiplication. ACE_UINT32 ul_shift (ACE_UINT32 a, ACE_UINT32 c_in, ACE_UINT32 *c_out); ACE_U_LongLong ull_shift (ACE_U_LongLong a, ACE_UINT32 c_in, ACE_UINT32 *c_out); @@ -402,7 +402,6 @@ typedef ACE_UINT16 ACE_USHORT16; ACE_UINT32 *carry); ACE_U_LongLong ull_mult (ACE_U_LongLong a, ACE_UINT32 b, ACE_UINT32 *carry); - // These functions are used to implement multiplication. }; typedef ACE_U_LongLong ACE_UINT64; diff --git a/ace/CDR_Base.h b/ace/CDR_Base.h index 159334dd9fb..9a8c16cccfe 100644 --- a/ace/CDR_Base.h +++ b/ace/CDR_Base.h @@ -1,31 +1,29 @@ // -*- C++ -*- -// -// $Id$ - -// ==================================================================== -// -// = LIBRARY -// ACE -// -// = FILENAME -// CDR_Base.h -// -// = DESCRIPTION -// ACE Common Data Representation (CDR) basic types. -// -// The current implementation assumes that the host has 1-byte, -// 2-byte and 4-byte integral types, and that it has single -// precision and double precision IEEE floats. -// Those assumptions are pretty good these days, with Crays being -// the only known exception. -// -// = AUTHORS -// Aniruddha Gokhale <gokhale@cs.wustl.edu> and Carlos O'Ryan -// <coryan@cs.wustl.edu> for the original implementation in TAO. -// ACE version by Jeff Parsons <parsons@cs.wustl.edu> -// and Istvan Buki <istvan.buki@euronet.be>. -// -// ===================================================================== + +//============================================================================= +/** + * @file CDR_Base.h + * + * $Id$ + * + * ACE Common Data Representation (CDR) basic types. + * + * The current implementation assumes that the host has 1-byte, + * 2-byte and 4-byte integral types, and that it has single + * precision and double precision IEEE floats. + * Those assumptions are pretty good these days, with Crays being + * the only known exception. + * + * + * @author TAO version by + * @author Aniruddha Gokhale <gokhale@cs.wustl.edu> + * @author Carlos O'Ryan<coryan@cs.wustl.edu> + * @author ACE version by + * @author Jeff Parsons <parsons@cs.wustl.edu> + * @author Istvan Buki <istvan.buki@euronet.be> + */ +//============================================================================= + #ifndef ACE_CDR_BASE_H #define ACE_CDR_BASE_H @@ -41,12 +39,14 @@ #include "ace/Basic_Types.h" #include "ace/Message_Block.h" +/** + * @class ACE_CDR + * + * @brief Keep constants and some routines common to both Output and + * Input CDR streams. + */ class ACE_Export ACE_CDR { - // = TITLE - // Keep constants and some routines common to both Output and - // Input CDR streams. - // public: // = Constants defined by the CDR protocol. // By defining as many of these constants as possible as enums we @@ -69,30 +69,38 @@ public: SHORT_ALIGN = 2, LONG_ALIGN = 4, LONGLONG_ALIGN = 8, + /// @note the CORBA LongDouble alignment requirements do not + /// match its size... LONGDOUBLE_ALIGN = 8, - // Note how the CORBA LongDouble alignment requirements do not - // match its size... + /// Maximal CDR 1.1 alignment: "quad precision" FP (i.e. "CDR::Long + /// double", size as above). MAX_ALIGNMENT = 8, - // Maximal CDR 1.1 alignment: "quad precision" FP (i.e. "CDR::Long - // double", size as above). + /// The default buffer size. + /** + * @todo We want to add options to control this + * default value, so this constant should be read as the default + * default value ;-) + */ DEFAULT_BUFSIZE = ACE_DEFAULT_CDR_BUFSIZE, - // The default buffer size. - // @@ TODO We want to add options to control this - // default value, so this constant should be read as the default - // default value ;-) + /// The buffer size grows exponentially until it reaches this size; + /// afterwards it grows linearly using the next constant EXP_GROWTH_MAX = ACE_DEFAULT_CDR_EXP_GROWTH_MAX, - // The buffer size grows exponentially until it reaches this size; - // afterwards it grows linearly using the next constant + /// Once exponential growth is ruled out the buffer size increases + /// in chunks of this size, note that this constants have the same + /// value right now, but it does not need to be so. LINEAR_GROWTH_CHUNK = ACE_DEFAULT_CDR_LINEAR_GROWTH_CHUNK - // Once exponential growth is ruled out the buffer size increases - // in chunks of this size, note that this constants have the same - // value right now, but it does not need to be so. }; + /** + * Do byte swapping for each basic IDL type size. There exist only + * routines to put byte, halfword (2 bytes), word (4 bytes), + * doubleword (8 bytes) and quadword (16 byte); because those are + * the IDL basic type sizes. + */ static void swap_2 (const char *orig, char *target); static void swap_4 (const char *orig, char *target); static void swap_8 (const char *orig, char *target); @@ -109,39 +117,39 @@ public: static void swap_16_array (const char *orig, char *target, size_t length); - // Do byte swapping for each basic IDL type size. There exist only - // routines to put byte, halfword (2 bytes), word (4 bytes), - // doubleword (8 bytes) and quadword (16 byte); because those are - // the IDL basic type sizes. + /// Align the message block to ACE_CDR::MAX_ALIGNMENT, + /// set by the CORBA spec at 8 bytes. static void mb_align (ACE_Message_Block *mb); - // Align the message block to ACE_CDR::MAX_ALIGNMENT, - // set by the CORBA spec at 8 bytes. + /** + * Compute the size of the smallest buffer that can contain at least + * <minsize> bytes. + * To understand how a "best fit" is computed look at the + * algorithm in the code. + * Basically the buffers grow exponentially, up to a certain point, + * then the buffer size grows linearly. + * The advantage of this algorithm is that is rapidly grows to a + * large value, but does not explode at the end. + */ static size_t first_size (size_t minsize); - // Compute the size of the smallest buffer that can contain at least - // <minsize> bytes. - // To understand how a "best fit" is computed look at the - // algorithm in the code. - // Basically the buffers grow exponentially, up to a certain point, - // then the buffer size grows linearly. - // The advantage of this algorithm is that is rapidly grows to a - // large value, but does not explode at the end. + /// Compute not the smallest, but the second smallest buffer that + /// will fir <minsize> bytes. static size_t next_size (size_t minsize); - // Compute not the smallest, but the second smallest buffer that - // will fir <minsize> bytes. + /** + * Increase the capacity of mb to contain at least <minsize> bytes. + * If <minsize> is zero the size is increased by an amount at least + * large enough to contain any of the basic IDL types. Return -1 on + * failure, 0 on success. + */ static int grow (ACE_Message_Block *mb, size_t minsize); - // Increase the capacity of mb to contain at least <minsize> bytes. - // If <minsize> is zero the size is increased by an amount at least - // large enough to contain any of the basic IDL types. Return -1 on - // failure, 0 on success. + /// Copy a message block chain into a single message block, + /// preserving the alignment of the original stream. static void consolidate (ACE_Message_Block *dst, const ACE_Message_Block *src); - // Copy a message block chain into a single message block, - // preserving the alignment of the original stream. static size_t total_length (const ACE_Message_Block *begin, const ACE_Message_Block *end); diff --git a/ace/CDR_Stream.h b/ace/CDR_Stream.h index d3b20949475..ef3ffd7ef6b 100644 --- a/ace/CDR_Stream.h +++ b/ace/CDR_Stream.h @@ -1,37 +1,36 @@ // -*- C++ -*- -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// CDR_Stream.h -// -// = DESCRIPTION -// ACE Common Data Representation (CDR) marshaling and demarshaling -// classes. -// -// This implementation was inspired in the CDR class in SunSoft's -// IIOP engine, but has a completely different implementation and a -// different interface too. -// -// The current implementation assumes that the host has 1-byte, -// 2-byte and 4-byte integral types, and that it has single -// precision and double precision IEEE floats. -// Those assumptions are pretty good these days, with Crays beign -// the only known exception. -// -// = AUTHORS -// Aniruddha Gokhale <gokhale@cs.wustl.edu> and Carlos O'Ryan -// <coryan@cs.wustl.edu> for the original implementation in TAO. -// ACE version by Jeff Parsons <parsons@cs.wustl.edu> -// and Istvan Buki <istvan.buki@euronet.be>. -// Codeset translation by Jim Rogers (jrogers@viasoft.com) and -// Carlos O'Ryan <coryan@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file CDR_Stream.h + * + * $Id$ + * + * ACE Common Data Representation (CDR) marshaling and demarshaling + * classes. + * + * This implementation was inspired in the CDR class in SunSoft's + * IIOP engine, but has a completely different implementation and a + * different interface too. + * + * The current implementation assumes that the host has 1-byte, + * 2-byte and 4-byte integral types, and that it has single + * precision and double precision IEEE floats. + * Those assumptions are pretty good these days, with Crays beign + * the only known exception. + * + * + * @author TAO version by + * @author Aniruddha Gokhale <gokhale@cs.wustl.edu> + * @author Carlos O'Ryan<coryan@cs.wustl.edu> + * @author ACE version by + * @author Jeff Parsons <parsons@cs.wustl.edu> + * @author Istvan Buki <istvan.buki@euronet.be> + * @author Codeset translation by + * @author Jim Rogers <jrogers@viasoft.com> + */ +//============================================================================= + #ifndef ACE_CDR_STREAM_H #define ACE_CDR_STREAM_H @@ -52,37 +51,42 @@ class ACE_CString; class ACE_InputCDR; +/** + * @class ACE_OutputCDR + * + * @brief A CDR stream for writing, i.e. for marshalling. + * + * This class is based on the the CORBA spec for Java (98-02-29), + * java class omg.org.CORBA.portable.OutputStream. It diverts in + * a few ways: + * + Operations taking arrays don't have offsets, because in C++ + * it is easier to describe an array starting from x+offset. + * + Operations return an error status, because exceptions are + * not widely available in C++ (yet). + */ class ACE_Export ACE_OutputCDR { - // = TITLE - // A CDR stream for writing, i.e. for marshalling. - // - // = DESCRIPTION - // This class is based on the the CORBA spec for Java (98-02-29), - // java class omg.org.CORBA.portable.OutputStream. It diverts in - // a few ways: - // + Operations taking arrays don't have offsets, because in C++ - // it is easier to describe an array starting from x+offset. - // + Operations return an error status, because exceptions are - // not widely available in C++ (yet). - // public: + /** + * The Codeset translators need access to some private members to + * efficiently marshal arrays + * For reading from an output CDR stream. + */ friend class ACE_Char_Codeset_Translator; friend class ACE_WChar_Codeset_Translator; - // The Codeset translators need access to some private members to - // efficiently marshal arrays friend class ACE_InputCDR; - // For reading from an output CDR stream. + /// Default constructor, allocates <size> bytes in the internal + /// buffer, if <size> == 0 it allocates the default size. ACE_OutputCDR (size_t size = 0, int byte_order = ACE_CDR_BYTE_ORDER, ACE_Allocator* buffer_allocator = 0, ACE_Allocator* data_block_allocator = 0, size_t memcpy_tradeoff = ACE_DEFAULT_CDR_MEMCPY_TRADEOFF); - // Default constructor, allocates <size> bytes in the internal - // buffer, if <size> == 0 it allocates the default size. + /// Build a CDR stream with an initial buffer, it will *not* remove + /// <data>, since it did not allocated it. ACE_OutputCDR (char *data, size_t size, int byte_order = ACE_CDR_BYTE_ORDER, @@ -90,22 +94,22 @@ public: ACE_Allocator* data_block_allocator = 0, size_t memcpy_tradeoff= ACE_DEFAULT_CDR_MEMCPY_TRADEOFF); - // Build a CDR stream with an initial buffer, it will *not* remove - // <data>, since it did not allocated it. + /// Build a CDR stream with an initial Message_Block chain, it will + /// *not* remove <data>, since it did not allocate it. ACE_OutputCDR (ACE_Message_Block *data, int byte_order = ACE_CDR_BYTE_ORDER, size_t memcpy_tradeoff= ACE_DEFAULT_CDR_MEMCPY_TRADEOFF); - // Build a CDR stream with an initial Message_Block chain, it will - // *not* remove <data>, since it did not allocate it. + /// destructor ~ACE_OutputCDR (void); - // destructor - // = Special types. - // These are needed for insertion and extraction of booleans, - // octets, chars, and bounded strings. + /** + * Disambiguate overload when inserting booleans, octets, chars, and + * bounded strings. + */ + //@{ @name Helper classes struct ACE_Export from_boolean { @@ -150,9 +154,10 @@ public: ACE_CDR::ULong bound_; ACE_CDR::Boolean nocopy_; }; + //@} - // = We have one method per basic IDL type.... - // They return 0 on failure and 1 on success. + // Return 0 on failure and 1 on success. + //@{ @name Write operations ACE_CDR::Boolean write_boolean (ACE_CDR::Boolean x); ACE_CDR::Boolean write_char (ACE_CDR::Char x); ACE_CDR::Boolean write_wchar (ACE_CDR::WChar x); @@ -167,7 +172,7 @@ public: ACE_CDR::Boolean write_double (const ACE_CDR::Double &x); ACE_CDR::Boolean write_longdouble (const ACE_CDR::LongDouble &x); - // = For string we offer methods that accept a precomputed length. + /// For string we offer methods that accept a precomputed length. ACE_CDR::Boolean write_string (const ACE_CDR::Char *x); ACE_CDR::Boolean write_string (ACE_CDR::ULong len, const ACE_CDR::Char *x); @@ -175,10 +180,12 @@ public: ACE_CDR::Boolean write_wstring (const ACE_CDR::WChar *x); ACE_CDR::Boolean write_wstring (ACE_CDR::ULong length, const ACE_CDR::WChar *x); + //@} - // = We add one method to write arrays of basic IDL types. - // Note: the portion written starts at <x> and ends at <x + length>. - // The length is *NOT* stored into the CDR stream. + /// Note: the portion written starts at <x> and ends + /// at <x + length>. + /// The length is *NOT* stored into the CDR stream. + //@{ @name Array write operations ACE_CDR::Boolean write_boolean_array (const ACE_CDR::Boolean *x, ACE_CDR::ULong length); ACE_CDR::Boolean write_char_array (const ACE_CDR::Char *x, @@ -206,12 +213,15 @@ public: ACE_CDR::Boolean write_longdouble_array (const ACE_CDR::LongDouble* x, ACE_CDR::ULong length); + /// Write an octet array contained inside a MB, this can be optimized + /// to minimize copies. ACE_CDR::Boolean write_octet_array_mb (const ACE_Message_Block* mb); - // Write an octet array contained inside a MB, this can be optimized - // to minimize copies. + //@} - // = We have one method per basic IDL type.... - // They return 0 on failure and 1 on success. + /** + * Return 0 on failure and 1 on success. + */ + //@{ @name Append contents of own CDR stream to another ACE_CDR::Boolean append_boolean (ACE_InputCDR &); ACE_CDR::Boolean append_char (ACE_InputCDR &); ACE_CDR::Boolean append_wchar (ACE_InputCDR &); @@ -228,55 +238,64 @@ public: ACE_CDR::Boolean append_wstring (ACE_InputCDR &); ACE_CDR::Boolean append_string (ACE_InputCDR &); + //@} + /// Returns 0 if an error has ocurred, the only expected error is to + /// run out of memory. int good_bit (void) const; - // Returns 0 if an error has ocurred, the only expected error is to - // run out of memory. + /// Reuse the CDR stream to write on the old buffer. void reset (void); - // Reuse the CDR stream to write on the old buffer. + /// Add the length of each message block in the chain. size_t total_length (void) const; - // Add the length of each message block in the chain. + /** + * Return the start of the message block chain for this CDR stream. + * NOTE: The complete CDR stream is represented by a chain of + * message blocks. + */ const ACE_Message_Block *begin (void) const; - // Return the start of the message block chain for this CDR stream. - // NOTE: The complete CDR stream is represented by a chain of - // message blocks. + /// Return the last message in the chain that is is use. const ACE_Message_Block *end (void) const; - // Return the last message in the chain that is is use. + /// Return the <current_> message block in chain. const ACE_Message_Block *current (void) const; - // Return the <current_> message block in chain. + /// Access the underlying buffer (read only). const char *buffer (void) const; - // Access the underlying buffer (read only). + /** + * Return the start and size of the internal buffer. NOTE: This + * methods only return information about the first block in the + * chain. + */ size_t length (void) const; - // Return the start and size of the internal buffer. NOTE: This - // methods only return information about the first block in the - // chain. + /** + * Utility function to allow the user more flexibility. + * Pads the stream up to the nearest <alignment>-byte boundary. + * Argument MUST be a power of 2. + * Returns 0 on success and -1 on failure. + */ int align_write_ptr (size_t alignment); - // Utility function to allow the user more flexibility. - // Pads the stream up to the nearest <alignment>-byte boundary. - // Argument MUST be a power of 2. - // Returns 0 on success and -1 on failure. + /// Access the codeset translators. They can be nil! ACE_Char_Codeset_Translator *char_translator (void) const; ACE_WChar_Codeset_Translator *wchar_translator (void) const; - // Access the codeset translators. They can be nil! + /** + * Return alignment of the wr_ptr(), with respect to the start of + * the CDR stream. This is not the same as the alignment of + * current->wr_ptr()! + */ size_t current_alignment (void) const; - // Return alignment of the wr_ptr(), with respect to the start of - // the CDR stream. This is not the same as the alignment of - // current->wr_ptr()! private: + /// disallow copying... ACE_OutputCDR (const ACE_OutputCDR& rhs); ACE_OutputCDR& operator= (const ACE_OutputCDR& rhs); - // disallow copying... ACE_CDR::Boolean write_1 (const ACE_CDR::Octet *x); ACE_CDR::Boolean write_2 (const ACE_CDR::UShort *x); @@ -284,171 +303,189 @@ private: ACE_CDR::Boolean write_8 (const ACE_CDR::ULongLong *x); ACE_CDR::Boolean write_16 (const ACE_CDR::LongDouble *x); + /** + * write an array of <length> elements, each of <size> bytes and the + * start aligned at a multiple of <align>. The elements are assumed + * to be packed with the right alignment restrictions. It is mostly + * designed for buffers of the basic types. + * + * This operation uses <memcpy>; as explained above it is expected + * that using assignment is faster that <memcpy> for one element, + * but for several elements <memcpy> should be more efficient, it + * could be interesting to find the break even point and optimize + * for that case, but that would be too platform dependent. + */ ACE_CDR::Boolean write_array (const void *x, size_t size, size_t align, ACE_CDR::ULong length); - // write an array of <length> elements, each of <size> bytes and the - // start aligned at a multiple of <align>. The elements are assumed - // to be packed with the right alignment restrictions. It is mostly - // designed for buffers of the basic types. - // - // This operation uses <memcpy>; as explained above it is expected - // that using assignment is faster that <memcpy> for one element, - // but for several elements <memcpy> should be more efficient, it - // could be interesting to find the break even point and optimize - // for that case, but that would be too platform dependent. + /** + * Returns (in <buf>) the next position in the buffer aligned to + * <size>, it advances the Message_Block wr_ptr past the data + * (i.e. <buf> + <size>). If necessary it grows the Message_Block + * buffer. Sets the good_bit to 0 and returns a -1 on failure. + */ int adjust (size_t size, char *&buf); - // Returns (in <buf>) the next position in the buffer aligned to - // <size>, it advances the Message_Block wr_ptr past the data - // (i.e. <buf> + <size>). If necessary it grows the Message_Block - // buffer. Sets the good_bit to 0 and returns a -1 on failure. + /// As above, but now the size and alignment requirements may be + /// different. int adjust (size_t size, size_t align, char *&buf); - // As above, but now the size and alignment requirements may be - // different. + /** + * Grow the CDR stream. When it returns <buf> contains a pointer to + * memory in the CDR stream, with at least <size> bytes ahead of it + * and aligned to an <align> boundary. It moved the <wr_ptr> to <buf + * + size>. + */ int grow_and_adjust (size_t size, size_t align, char *&buf); - // Grow the CDR stream. When it returns <buf> contains a pointer to - // memory in the CDR stream, with at least <size> bytes ahead of it - // and aligned to an <align> boundary. It moved the <wr_ptr> to <buf - // + size>. + /// If non-zero then this stream is writing in non-native byte order, + /// this is only meaningful if ACE_ENABLE_SWAP_ON_WRITE is defined. int do_byte_swap (void) const; - // If non-zero then this stream is writing in non-native byte order, - // this is only meaningful if ACE_ENABLE_SWAP_ON_WRITE is defined. private: + /// The start of the chain of message blocks. ACE_Message_Block start_; - // The start of the chain of message blocks. + /// The current block in the chain were we are writing. ACE_Message_Block *current_; - // The current block in the chain were we are writing. + /** + * Is the current block writable. When we steal a buffer from the + * user and just chain it into the message block we are not supposed + * to write on it, even if it is past the start and end of the + * buffer. + */ int current_is_writable_; - // Is the current block writable. When we steal a buffer from the - // user and just chain it into the message block we are not supposed - // to write on it, even if it is past the start and end of the - // buffer. + /** + * The current alignment as measured from the start of the buffer. + * Usually this coincides with the alignment of the buffer in + * memory, but, when we chain another buffer this "quasi invariant" + * is broken. + * The current_alignment is used to readjust the buffer following + * the stolen message block. + */ size_t current_alignment_; - // The current alignment as measured from the start of the buffer. - // Usually this coincides with the alignment of the buffer in - // memory, but, when we chain another buffer this "quasi invariant" - // is broken. - // The current_alignment is used to readjust the buffer following - // the stolen message block. + /** + * If not zero swap bytes at writing so the created CDR stream byte + * order does *not* match the machine byte order. The motivation + * for such a beast is that in some setting a few (fast) machines + * can be serving hundreds of slow machines with the opposite byte + * order, so it makes sense (as a load balancing device) to put the + * responsability in the writers. THIS IS NOT A STANDARD IN CORBA, + * USE AT YOUR OWN RISK + */ int do_byte_swap_; - // If not zero swap bytes at writing so the created CDR stream byte - // order does *not* match the machine byte order. The motivation - // for such a beast is that in some setting a few (fast) machines - // can be serving hundreds of slow machines with the opposite byte - // order, so it makes sense (as a load balancing device) to put the - // responsability in the writers. THIS IS NOT A STANDARD IN CORBA, - // USE AT YOUR OWN RISK + /// Set to 0 when an error ocurrs. int good_bit_; - // Set to 0 when an error ocurrs. + /// Break-even point for copying. size_t memcpy_tradeoff_; - // Break-even point for copying. protected: + /// If not nil, invoke for translation of character and string data. ACE_Char_Codeset_Translator *char_translator_; ACE_WChar_Codeset_Translator *wchar_translator_; - // If not nil, invoke for translation of character and string data. }; // **************************************************************** +/** + * @class ACE_InputCDR + * + * @brief A CDR stream for reading, i.e. for demarshalling. + * + * This class is based on the the CORBA spec for Java (98-02-29), + * java class omg.org.CORBA.portable.InputStream. It diverts in a + * few ways: + * + Operations to retrieve basic types take parameters by + * reference. + * + Operations taking arrays don't have offsets, because in C++ + * it is easier to describe an array starting from x+offset. + * + Operations return an error status, because exceptions are + * not widely available in C++ (yet). + */ class ACE_Export ACE_InputCDR { - // = TITLE - // A CDR stream for reading, i.e. for demarshalling. - // - // = DESCRIPTION - // This class is based on the the CORBA spec for Java (98-02-29), - // java class omg.org.CORBA.portable.InputStream. It diverts in a - // few ways: - // + Operations to retrieve basic types take parameters by - // reference. - // + Operations taking arrays don't have offsets, because in C++ - // it is easier to describe an array starting from x+offset. - // + Operations return an error status, because exceptions are - // not widely available in C++ (yet). - // public: + /// The translator need privileged access to efficiently demarshal + /// arrays and the such friend class ACE_Char_Codeset_Translator; friend class ACE_WChar_Codeset_Translator; - // The translator need privileged access to efficiently demarshal - // arrays and the such + /** + * Create an input stream from an arbitrary buffer, care must be + * exercised wrt alignment, because this contructor will *not* work + * if the buffer is unproperly aligned. + */ ACE_InputCDR (const char *buf, size_t bufsiz, int byte_order = ACE_CDR_BYTE_ORDER); - // Create an input stream from an arbitrary buffer, care must be - // exercised wrt alignment, because this contructor will *not* work - // if the buffer is unproperly aligned. + /// Create an empty input stream. The caller is responsible for + /// putting the right data and providing the right alignment. ACE_InputCDR (size_t bufsiz, int byte_order = ACE_CDR_BYTE_ORDER); - // Create an empty input stream. The caller is responsible for - // putting the right data and providing the right alignment. + /// Create an input stream from an ACE_Message_Block ACE_InputCDR (const ACE_Message_Block *data, int byte_order = ACE_CDR_BYTE_ORDER); - // Create an input stream from an ACE_Message_Block + /// Create an input stream from an ACE_Data_Block ACE_InputCDR (ACE_Data_Block *data, int byte_order = ACE_CDR_BYTE_ORDER); - // Create an input stream from an ACE_Data_Block + /** + * These make a copy of the current stream state, but do not copy + * the internal buffer, so the same stream can be read multiple + * times efficiently. + */ ACE_InputCDR (const ACE_InputCDR& rhs); ACE_InputCDR& operator= (const ACE_InputCDR& rhs); - // These make a copy of the current stream state, but do not copy - // the internal buffer, so the same stream can be read multiple - // times efficiently. + /// When interpreting indirected TypeCodes it is useful to make a + /// "copy" of the stream starting in the new position. ACE_InputCDR (const ACE_InputCDR& rhs, size_t size, ACE_CDR::Long offset); - // When interpreting indirected TypeCodes it is useful to make a - // "copy" of the stream starting in the new position. + /// This creates an encapsulated stream, the first byte must be (per + /// the spec) the byte order of the encapsulation. ACE_InputCDR (const ACE_InputCDR& rhs, size_t size); - // This creates an encapsulated stream, the first byte must be (per - // the spec) the byte order of the encapsulation. + /// Create an input CDR from an output CDR. ACE_InputCDR (const ACE_OutputCDR& rhs, ACE_Allocator* buffer_allocator = 0, ACE_Allocator* data_block_allocator = 0); - // Create an input CDR from an output CDR. + /// Helper class to transfer the contents from one input CDR to + /// another without requiring any extra memory allocations, data + /// copies or too many temporaries. struct ACE_Export Transfer_Contents { - // Helper class to transfer the contents from one input CDR to - // another without requiring any extra memory allocations, data - // copies or too many temporaries. Transfer_Contents (ACE_InputCDR &rhs); ACE_InputCDR &rhs_; }; + /// Transfer the contents from <rhs> to a new CDR ACE_InputCDR (Transfer_Contents rhs); - // Transfer the contents from <rhs> to a new CDR + /// Destructor ~ACE_InputCDR (void); - // Destructor - // = Special types. - // These extract octets, chars, booleans, and bounded strings + /// Disambiguate overloading when extracting octets, chars, + /// booleans, and bounded strings + //@{ @name Helper classes struct ACE_Export to_boolean { @@ -489,9 +526,12 @@ public: ACE_CDR::WChar *&val_; ACE_CDR::ULong bound_; }; + //@} - // = We have one method per basic IDL type.... - // They return 0 on failure and 1 on success. + /** + * Return 0 on failure and 1 on success. + */ + //@{ @name Read basic IDL types ACE_CDR::Boolean read_boolean (ACE_CDR::Boolean& x); ACE_CDR::Boolean read_char (ACE_CDR::Char &x); ACE_CDR::Boolean read_wchar (ACE_CDR::WChar& x); @@ -509,11 +549,14 @@ public: ACE_CDR::Boolean read_string (ACE_CDR::Char *&x); ACE_CDR::Boolean read_string (ACE_CString &x); ACE_CDR::Boolean read_wstring (ACE_CDR::WChar*& x); - - // = One method for each basic type... - // The buffer <x> must be large enough to contain <length> - // elements. - // They return -1 on failure and 0 on success. + //@} + + /** + * The buffer <x> must be large enough to contain <length> + * elements. + * Return -1 on failure and 0 on success. + */ + //@{ @name Read basic IDL types arrays ACE_CDR::Boolean read_boolean_array (ACE_CDR::Boolean* x, ACE_CDR::ULong length); ACE_CDR::Boolean read_char_array (ACE_CDR::Char *x, @@ -540,9 +583,12 @@ public: ACE_CDR::ULong length); ACE_CDR::Boolean read_longdouble_array (ACE_CDR::LongDouble* x, ACE_CDR::ULong length); + //@} - // = We have one method per basic IDL type.... - // They return 0 on failure and 1 on success. + /** + * Return 0 on failure and 1 on success. + */ + //@{ @name Skip elements ACE_CDR::Boolean skip_boolean (void); ACE_CDR::Boolean skip_char (void); ACE_CDR::Boolean skip_wchar (void); @@ -556,93 +602,104 @@ public: ACE_CDR::Boolean skip_float (void); ACE_CDR::Boolean skip_double (void); ACE_CDR::Boolean skip_longdouble (void); + //@} + /** + * The next field must be a string, this method skips it. It is + * useful in parsing a TypeCode. + * Return 0 on failure and 1 on success. + */ ACE_CDR::Boolean skip_wstring (void); ACE_CDR::Boolean skip_string (void); - // The next field must be a string, this method skips it. It is - // useful in parsing a TypeCode. - // Return 0 on failure and 1 on success. + /// Skip <n> bytes in the CDR stream. + /// Return 0 on failure and 1 on success. ACE_CDR::Boolean skip_bytes (size_t n); - // Skip <n> bytes in the CDR stream. - // Return 0 on failure and 1 on success. + /// returns zero if a problem has been detected. int good_bit (void) const; - // returns zero if a problem has been detected. + /** + * Return the start of the message block chain for this CDR stream. + * NOTE: In the current implementation the chain has length 1, but + * we are planning to change that. + */ const ACE_Message_Block* start (void) const; - // Return the start of the message block chain for this CDR stream. - // NOTE: In the current implementation the chain has length 1, but - // we are planning to change that. // = The following functions are useful to read the contents of the // CDR stream from a socket or file. + /** + * Grow the internal buffer, reset <rd_ptr> to the first byte in the + * new buffer that is properly aligned, and set <wr_ptr> to <rd_ptr> + * + newsize + */ int grow (size_t newsize); - // Grow the internal buffer, reset <rd_ptr> to the first byte in the - // new buffer that is properly aligned, and set <wr_ptr> to <rd_ptr> - // + newsize + /** + * After reading and partially parsing the contents the user can + * detect a change in the byte order, this method will let him + * change it. + */ void reset_byte_order (int byte_order); - // After reading and partially parsing the contents the user can - // detect a change in the byte order, this method will let him - // change it. + /// Re-initialize the CDR stream, copying the contents of the chain + /// of message_blocks starting from <data>. void reset (const ACE_Message_Block *data, int byte_order); - // Re-initialize the CDR stream, copying the contents of the chain - // of message_blocks starting from <data>. + /// Steal the contents from the currect CDR. ACE_Message_Block *steal_contents (void); - // Steal the contents from the currect CDR. + /// Steal the contents of <cdr> and make a shallow copy into this + /// stream. void steal_from (ACE_InputCDR &cdr); - // Steal the contents of <cdr> and make a shallow copy into this - // stream. + /// Re-initialize the CDR stream, forgetting about the old contents + /// of the stream and allocating a new buffer (from the allocators). void reset_contents (void); - // Re-initialize the CDR stream, forgetting about the old contents - // of the stream and allocating a new buffer (from the allocators). + /// Returns the current position for the rd_ptr.... char* rd_ptr (void); - // Returns the current position for the rd_ptr.... + /// Return how many bytes are left in the stream. size_t length (void) const; - // Return how many bytes are left in the stream. + /** + * Utility function to allow the user more flexibility. + * Skips up to the nearest <alignment>-byte boundary. + * Argument MUST be a power of 2. + * Returns 0 on success and -1 on failure. + */ int align_read_ptr (size_t alignment); - // Utility function to allow the user more flexibility. - // Skips up to the nearest <alignment>-byte boundary. - // Argument MUST be a power of 2. - // Returns 0 on success and -1 on failure. + /// If non-zero then this stream is writing in non-native byte order, + /// this is only meaningful if ACE_ENABLE_SWAP_ON_WRITE is defined. int do_byte_swap (void) const; - // If non-zero then this stream is writing in non-native byte order, - // this is only meaningful if ACE_ENABLE_SWAP_ON_WRITE is defined. + /// If <do_byte_swap> returns 1, this returns ACE_CDR_BYTE_ORDER else + /// it returns ~ACE_CDR_BYTE_ORDER. int byte_order (void) const; - // If <do_byte_swap> returns 1, this returns ACE_CDR_BYTE_ORDER else - // it returns ~ACE_CDR_BYTE_ORDER. + /// Access the codeset translators. They can be nil! ACE_Char_Codeset_Translator *char_translator (void) const; ACE_WChar_Codeset_Translator *wchar_translator (void) const; - // Access the codeset translators. They can be nil! protected: + /// The start of the chain of message blocks, even though in the + /// current version the chain always has length 1. ACE_Message_Block start_; - // The start of the chain of message blocks, even though in the - // current version the chain always has length 1. + /// The CDR stream byte order does not match the one on the machine, + /// swapping is needed while reading. int do_byte_swap_; - // The CDR stream byte order does not match the one on the machine, - // swapping is needed while reading. + /// set to 0 when an error occurs. int good_bit_; - // set to 0 when an error occurs. + /// If not nil, invoke for translation of character and string data. ACE_Char_Codeset_Translator *char_translator_; ACE_WChar_Codeset_Translator *wchar_translator_; - // If not nil, invoke for translation of character and string data. private: ACE_CDR::Boolean read_1 (ACE_CDR::Octet *x); @@ -658,141 +715,151 @@ private: // alignment requirements of CDR streams and implement the // operations using asignment. + /** + * Read an array of <length> elements, each of <size> bytes and the + * start aligned at a multiple of <align>. The elements are assumed + * to be packed with the right alignment restrictions. It is mostly + * designed for buffers of the basic types. + * + * This operation uses <memcpy>; as explained above it is expected + * that using assignment is faster that <memcpy> for one element, + * but for several elements <memcpy> should be more efficient, it + * could be interesting to find the break even point and optimize + * for that case, but that would be too platform dependent. + */ ACE_CDR::Boolean read_array (void* x, size_t size, size_t align, ACE_CDR::ULong length); - // Read an array of <length> elements, each of <size> bytes and the - // start aligned at a multiple of <align>. The elements are assumed - // to be packed with the right alignment restrictions. It is mostly - // designed for buffers of the basic types. - // - // This operation uses <memcpy>; as explained above it is expected - // that using assignment is faster that <memcpy> for one element, - // but for several elements <memcpy> should be more efficient, it - // could be interesting to find the break even point and optimize - // for that case, but that would be too platform dependent. + /// Move the rd_ptr ahead by <offset> bytes. void rd_ptr (size_t offset); - // Move the rd_ptr ahead by <offset> bytes. + /// Points to the continuation field of the current message block. char* end (void); - // Points to the continuation field of the current message block. + /** + * Returns (in <buf>) the next position in the buffer aligned to + * <size>, it advances the Message_Block rd_ptr past the data + * (i.e. <buf> + <size>). Sets the good_bit to 0 and returns a -1 + * on failure. + */ int adjust (size_t size, char *&buf); - // Returns (in <buf>) the next position in the buffer aligned to - // <size>, it advances the Message_Block rd_ptr past the data - // (i.e. <buf> + <size>). Sets the good_bit to 0 and returns a -1 - // on failure. + /// As above, but now the size and alignment requirements may be + /// different. int adjust (size_t size, size_t align, char *&buf); - // As above, but now the size and alignment requirements may be - // different. }; // **************************************************************** +/** + * @class ACE_Char_Codeset_Translator + * + * @brief Codeset translation routines common to both Output and Input + * CDR streams. + * + * This class is a base class for defining codeset translation + * routines to handle the character set translations required by + * both CDR Input streams and CDR Output streams. + */ class ACE_Export ACE_Char_Codeset_Translator { - // = TITLE - // Codeset translation routines common to both Output and Input - // CDR streams. - // - // = DESCRIPTION - // This class is a base class for defining codeset translation - // routines to handle the character set translations required by - // both CDR Input streams and CDR Output streams. - // public: + /// Read a single character from the stream, converting from the + /// stream codeset to the native codeset virtual ACE_CDR::Boolean read_char (ACE_InputCDR&, ACE_CDR::Char&) = 0; - // Read a single character from the stream, converting from the - // stream codeset to the native codeset + /// Read a string from the stream, including the length, converting + /// the characters from the stream codeset to the native codeset virtual ACE_CDR::Boolean read_string (ACE_InputCDR&, ACE_CDR::Char *&) = 0; - // Read a string from the stream, including the length, converting - // the characters from the stream codeset to the native codeset + /// Read an array of characters from the stream, converting the + /// characters from the stream codeset to the native codeset. virtual ACE_CDR::Boolean read_char_array (ACE_InputCDR&, ACE_CDR::Char*, ACE_CDR::ULong) = 0; - // Read an array of characters from the stream, converting the - // characters from the stream codeset to the native codeset. + /// Write a single character to the stream, converting from the + /// native codeset to the stream codeset virtual ACE_CDR::Boolean write_char (ACE_OutputCDR&, ACE_CDR::Char) = 0; - // Write a single character to the stream, converting from the - // native codeset to the stream codeset + /// Write a string to the stream, including the length, converting + /// from the native codeset to the stream codeset virtual ACE_CDR::Boolean write_string (ACE_OutputCDR&, ACE_CDR::ULong, const ACE_CDR::Char*) = 0; - // Write a string to the stream, including the length, converting - // from the native codeset to the stream codeset + /// Write an array of characters to the stream, converting from the + /// native codeset to the stream codeset virtual ACE_CDR::Boolean write_char_array (ACE_OutputCDR&, const ACE_CDR::Char*, ACE_CDR::ULong) = 0; - // Write an array of characters to the stream, converting from the - // native codeset to the stream codeset protected: + /// Children have access to low-level routines because they cannot + /// use read_char or something similar (it would recurse). ACE_CDR::Boolean read_1 (ACE_InputCDR& input, ACE_CDR::Octet *x); ACE_CDR::Boolean write_1 (ACE_OutputCDR& output, const ACE_CDR::Octet *x); - // Children have access to low-level routines because they cannot - // use read_char or something similar (it would recurse). + /// Efficiently read <length> elements of size <size> each from + /// <input> into <x>; the data must be aligned to <align>. ACE_CDR::Boolean read_array (ACE_InputCDR& input, void* x, size_t size, size_t align, ACE_CDR::ULong length); - // Efficiently read <length> elements of size <size> each from - // <input> into <x>; the data must be aligned to <align>. + /** + * Efficiently write <length> elements of size <size> from <x> into + * <output>. Before inserting the elements enough padding is added + * to ensure that the elements will be aligned to <align> in the + * stream. + */ ACE_CDR::Boolean write_array (ACE_OutputCDR& output, const void *x, size_t size, size_t align, ACE_CDR::ULong length); - // Efficiently write <length> elements of size <size> from <x> into - // <output>. Before inserting the elements enough padding is added - // to ensure that the elements will be aligned to <align> in the - // stream. + /** + * Exposes the stream implementation of <adjust>, this is useful in + * many cases to minimize memory allocations during marshaling. + * On success <buf> will contain a contiguous area in the CDR stream + * that can hold <size> bytes aligned to <align>. + * Results + */ int adjust (ACE_OutputCDR& out, size_t size, size_t align, char *&buf); - // Exposes the stream implementation of <adjust>, this is useful in - // many cases to minimize memory allocations during marshaling. - // On success <buf> will contain a contiguous area in the CDR stream - // that can hold <size> bytes aligned to <align>. - // Results + /// Used by derived classes to set errors in the CDR stream. void good_bit (ACE_OutputCDR& out, int bit); - // Used by derived classes to set errors in the CDR stream. }; // **************************************************************** +/** + * @class ACE_WChar_Codeset_Translator + * + * @brief Codeset translation routines common to both Output and Input + * CDR streams. + * + * This class is a base class for defining codeset translation + * routines to handle the character set translations required by + * both CDR Input streams and CDR Output streams. + */ class ACE_Export ACE_WChar_Codeset_Translator { - // = TITLE - // Codeset translation routines common to both Output and Input - // CDR streams. - // - // = DESCRIPTION - // This class is a base class for defining codeset translation - // routines to handle the character set translations required by - // both CDR Input streams and CDR Output streams. - // public: virtual ACE_CDR::Boolean read_wchar (ACE_InputCDR&, ACE_CDR::WChar&) = 0; @@ -811,6 +878,8 @@ public: ACE_CDR::ULong) = 0; protected: + /// Children have access to low-level routines because they cannot + /// use read_char or something similar (it would recurse). ACE_CDR::Boolean read_1 (ACE_InputCDR& input, ACE_CDR::Octet *x); ACE_CDR::Boolean read_2 (ACE_InputCDR& input, @@ -823,39 +892,41 @@ protected: const ACE_CDR::UShort *x); ACE_CDR::Boolean write_4 (ACE_OutputCDR& output, const ACE_CDR::ULong *x); - // Children have access to low-level routines because they cannot - // use read_char or something similar (it would recurse). + /// Efficiently read <length> elements of size <size> each from + /// <input> into <x>; the data must be aligned to <align>. ACE_CDR::Boolean read_array (ACE_InputCDR& input, void* x, size_t size, size_t align, ACE_CDR::ULong length); - // Efficiently read <length> elements of size <size> each from - // <input> into <x>; the data must be aligned to <align>. + /** + * Efficiently write <length> elements of size <size> from <x> into + * <output>. Before inserting the elements enough padding is added + * to ensure that the elements will be aligned to <align> in the + * stream. + */ ACE_CDR::Boolean write_array (ACE_OutputCDR& output, const void *x, size_t size, size_t align, ACE_CDR::ULong length); - // Efficiently write <length> elements of size <size> from <x> into - // <output>. Before inserting the elements enough padding is added - // to ensure that the elements will be aligned to <align> in the - // stream. + /** + * Exposes the stream implementation of <adjust>, this is useful in + * many cases to minimize memory allocations during marshaling. + * On success <buf> will contain a contiguous area in the CDR stream + * that can hold <size> bytes aligned to <align>. + * Results + */ int adjust (ACE_OutputCDR& out, size_t size, size_t align, char *&buf); - // Exposes the stream implementation of <adjust>, this is useful in - // many cases to minimize memory allocations during marshaling. - // On success <buf> will contain a contiguous area in the CDR stream - // that can hold <size> bytes aligned to <align>. - // Results + /// Used by derived classes to set errors in the CDR stream. void good_bit (ACE_OutputCDR& out, int bit); - // Used by derived classes to set errors in the CDR stream. }; // @@ These operators should not be inlined since they force SString.h diff --git a/ace/CORBA_Handler.h b/ace/CORBA_Handler.h index 5efe99f729e..658567f5ddf 100644 --- a/ace/CORBA_Handler.h +++ b/ace/CORBA_Handler.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// CORBA_Handler.h -// -// = AUTHOR -// Douglas C. Schmidt (schmidt@cs.wustl.edu) and -// Irfan Pyarali (irfan@wuerl.wustl.edu). -// -// ============================================================================ + +//============================================================================= +/** + * @file CORBA_Handler.h + * + * $Id$ + * + * @author Douglas C. Schmidt (schmidt@cs.wustl.edu) + * @author Irfan Pyarali (irfan@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_CORBA_HANDLER_H #define ACE_CORBA_HANDLER_H @@ -35,60 +32,68 @@ #undef EXCEPTIONS #undef WANT_ORBIX_FDS +/** + * @class ACE_CORBA_Handler + * + * @brief Handle Orbix requests in conjunction with ACE. + * + * Note, do *NOT* inherit from this class! Instead, use the + * <ACE_MT_CORBA_HAndler> and <ACE_ST_CORBA_Handler> as + * Singletons. + */ class ACE_Export ACE_CORBA_Handler : public ACE_Service_Object { - // = TITLE - // Handle Orbix requests in conjunction with ACE. - // - // = DESCRIPTION - // Note, do *NOT* inherit from this class! Instead, use the - // <ACE_MT_CORBA_HAndler> and <ACE_ST_CORBA_Handler> as - // Singletons. public: // = Activation and deactivation methods. + /** + * Activate and register <service_name> with the Orbix daemon. If + * <marker_name> and <service_location> are != 0 then do a "putit" + * to register this service with orbixd. This method also + * increments the reference count of active services using the + * ACE_ST_CORBA_Handler. + */ virtual int activate_service (const char *service_name, const char *marker_name = 0, const char *service_location = 0); - // Activate and register <service_name> with the Orbix daemon. If - // <marker_name> and <service_location> are != 0 then do a "putit" - // to register this service with orbixd. This method also - // increments the reference count of active services using the - // ACE_ST_CORBA_Handler. + /** + * Decrement the reference count and free up all the + * resources if this is the last service to be using + * the ACE_ST_CORBA_Handler... + */ virtual int deactivate_service (const char *service_name = 0, const char *marker_name = 0); - // Decrement the reference count and free up all the - // resources if this is the last service to be using - // the ACE_ST_CORBA_Handler... + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Make this into an "abstract" class... ACE_CORBA_Handler (void); - // Make this into an "abstract" class... + /// Note virtual destructor... virtual ~ACE_CORBA_Handler (void); - // Note virtual destructor... + /** + * Register <service_name> by doing a "putit" to register the + * <service_name> using the <marker_name> at <service_location> with + * orbixd. + */ virtual int register_service (const char *service_name, const char *marker_name, const char *service_location); - // Register <service_name> by doing a "putit" to register the - // <service_name> using the <marker_name> at <service_location> with - // orbixd. + /// Register <service_name> by doing a "putit" to register + /// <service_name> using the <marker_name> with orbixd. virtual int remove_service (const char *service_name, const char *marker_name = 0); - // Register <service_name> by doing a "putit" to register - // <service_name> using the <marker_name> with orbixd. + /// Keep track of the number of active CORBA_Handlers. ssize_t reference_count_; - // Keep track of the number of active CORBA_Handlers. private: // = Disallow assignment and initialization. @@ -96,71 +101,73 @@ private: const ACE_CORBA_Handler &operator= (const ACE_CORBA_Handler &rhs); }; +/** + * @class ACE_ST_CORBA_Handler + * + * @brief Handle single-threaded Orbix requests in conjunction with the + * <ACE_Reactor>. + * + * You should NOT use this class unless you've got a VERY old + * version of Orbix that only supports single-threading. If + * you're using a more recent version of Orbix use the + * <ACE_MT_CORBA_Handler>. + */ class ACE_Export ACE_ST_CORBA_Handler : public ACE_CORBA_Handler { - // = TITLE - // Handle single-threaded Orbix requests in conjunction with the - // <ACE_Reactor>. - // - // = DESCRIPTION - // You should NOT use this class unless you've got a VERY old - // version of Orbix that only supports single-threading. If - // you're using a more recent version of Orbix use the - // <ACE_MT_CORBA_Handler>. public: // = Singleton access point. + /// Returns a Singleton. static ACE_CORBA_Handler *instance (void); - // Returns a Singleton. // = Demuxing hook. + /// Process the next Orbix event. virtual int handle_input (ACE_HANDLE); - // Process the next Orbix event. // = Dynamic linking hooks. + /// Atomically suspend all the threads associated with the <thr_mgr>. virtual int suspend (void); - // Atomically suspend all the threads associated with the <thr_mgr>. + /// Atomically resume all the threads associated with the <thr_mgr>. virtual int resume (void); - // Atomically resume all the threads associated with the <thr_mgr>. // = Iterations dictate # of <processNextEvent> calls per-callback. + /// Get the current iteration. size_t iterations (void); - // Get the current iteration. + /// Set the current iteration. void iterations (size_t); - // Set the current iteration. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Preinitialize any descriptors that Orbix is using. This is + /// called in <instance>. void get_orbix_descriptors (void); - // Preinitialize any descriptors that Orbix is using. This is - // called in <instance>. + /// Constructors (ensure Singleton...). ACE_ST_CORBA_Handler (void); - // Constructors (ensure Singleton...). + /// Destructor cleans up resources. virtual ~ACE_ST_CORBA_Handler (void); - // Destructor cleans up resources. + /// Insert a descriptor into the ACE_Reactor that Orbix has just added. static void insert_handle (ACE_HANDLE); - // Insert a descriptor into the ACE_Reactor that Orbix has just added. + /// Remove a descriptor from the ACE_Reactor that Orbix has just deleted. static void remove_handle (ACE_HANDLE); - // Remove a descriptor from the ACE_Reactor that Orbix has just deleted. + /// Clean up the singleton at program rundown. static void instance_cleaner (void *object, void *param); - // Clean up the singleton at program rundown. + /// ACE_ST_CORBA_Handler is a singleton object. static ACE_ST_CORBA_Handler *instance_; - // ACE_ST_CORBA_Handler is a singleton object. + /// Number of iterations to process per <processNextEvent> call. size_t iterations_; - // Number of iterations to process per <processNextEvent> call. // If the user has complete control of all Orbix callback processing and // really, really knows how to handle all of the involved interworkings, @@ -178,72 +185,72 @@ protected: #if defined (ACE_HAS_MT_ORBIX) && (ACE_HAS_MT_ORBIX != 0) +/** + * @class ACE_MT_CORBA_Handler + * + * @brief Handle multi-threaded Orbix requests in conjunction with the + * <ACE_Reactor>. + * + * If you are using MT-Orbix (which has been the default Orbix + * for years) you should use this class rather than + * <ACE_ST_CORBA_Handler>. See + * www.cs.wustl.edu/~schmidt/COOTS-96.ps.gz + * for an explanation of what this class does for Orbix. + */ class ACE_Export ACE_MT_CORBA_Handler : public ACE_CORBA_Handler, public ACE_CORBA_1 (ThreadFilter) { - // = TITLE - // Handle multi-threaded Orbix requests in conjunction with the - // <ACE_Reactor>. - // - // = DESCRIPTION - // If you are using MT-Orbix (which has been the default Orbix - // for years) you should use this class rather than - // <ACE_ST_CORBA_Handler>. See - // - // www.cs.wustl.edu/~schmidt/COOTS-96.ps.gz - // - // for an explanation of what this class does for Orbix. public: // = Singleton access point. + /// Returns a Singleton. static ACE_CORBA_Handler *instance (void); - // Returns a Singleton. // = Demuxing hook. + /// Process the next Orbix event. virtual int handle_input (ACE_HANDLE); - // Process the next Orbix event. // = Threading hook. + /// Set the Thread_Manager used by ACE_MT_CORBA_Handler void thr_mgr (ACE_Thread_Manager *tm); - // Set the Thread_Manager used by ACE_MT_CORBA_Handler + /// Get the Thread_Manager used by ACE_MT_CORBA_Handler ACE_Thread_Manager *thr_mgr (void) const; - // Get the Thread_Manager used by ACE_MT_CORBA_Handler // = Dynamic linking hooks. + /// Atomically suspend all the threads associated with the <thr_mgr>. virtual int suspend (void); - // Atomically suspend all the threads associated with the <thr_mgr>. + /// Atomically resume all the threads associated with the <thr_mgr>. virtual int resume (void); - // Atomically resume all the threads associated with the <thr_mgr>. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// function executed by new thread static void *process_events (void *); - // function executed by new thread + /// Constructors (ensure Singleton...). ACE_MT_CORBA_Handler (void); - // Constructors (ensure Singleton...). + /// Destructor cleans up resources. virtual ~ACE_MT_CORBA_Handler (void); - // Destructor cleans up resources. + /// Take the incoming request and pass it to <handle_input> through + /// the Reactor. virtual int inRequestPreMarshal (ACE_CORBA_1 (Request) &r, ACE_CORBA_1 (Environment) &IT_env = ACE_CORBA_1 (default_environment)); - // Take the incoming request and pass it to <handle_input> through - // the Reactor. + /// ACE_MT_CORBA_Handler is a singleton object. static ACE_MT_CORBA_Handler *instance_; - // ACE_MT_CORBA_Handler is a singleton object. + /// Event demultiplexor used by ACE_ST_CORBA_Handler. ACE_Thread_Manager *thr_mgr_; - // Event demultiplexor used by ACE_ST_CORBA_Handler. + /// Used to send CORBA::Requests through the server ACE_Pipe pipe_; - // Used to send CORBA::Requests through the server }; #endif /* ACE_HAS_MT_ORBIX */ diff --git a/ace/CORBA_Ref.h b/ace/CORBA_Ref.h index e469dabb718..9010c8c82fd 100644 --- a/ace/CORBA_Ref.h +++ b/ace/CORBA_Ref.h @@ -1,22 +1,20 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// CORBA_Ref.h -// -// = AUTHOR -// Irfan Pyarali (irfan@wuerl.wustl.edu). -// Tim Harrison (harrison@cs.wustl.edu) -// -// = DESCRIPTION -// A wrapper for helping with Orbix object references. -// -// ============================================================================ + +//============================================================================= +/** + * @file CORBA_Ref.h + * + * $Id$ + * + * @author Irfan Pyarali (irfan@wuerl.wustl.edu) + * @author Tim Harrison (harrison@cs.wustl.edu) + * + * A wrapper for helping with Orbix object references. + * + * + */ +//============================================================================= + #ifndef ACE_CORBA_REF_H #define ACE_CORBA_REF_H @@ -28,44 +26,46 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_CORBA_Ref + * + * @brief A wrapper for helping with Orbix object references. + * + * <ACE_CORBA_Ref> is parameterized by the type of orbix object + * reference to be used. The construtor, operator=, and the + * destructor of <ACE_CORBA_Ref> perform implicit duplicates and + * releases in order to help make the use of Orbix object + * references transparent. + */ template <class CORBA_REF> class ACE_CORBA_Ref { - // = TITLE - // A wrapper for helping with Orbix object references. - // - // = DESCRIPTION - // <ACE_CORBA_Ref> is parameterized by the type of orbix object - // reference to be used. The construtor, operator=, and the - // destructor of <ACE_CORBA_Ref> perform implicit duplicates and - // releases in order to help make the use of Orbix object - // references transparent. public: + /// Null construction. ACE_CORBA_Ref (void); - // Null construction. + /// Contruction with an orbix ref. + /// performs a <CORBA_REF::_duplicate>. ACE_CORBA_Ref (CORBA_REF *ref); - // Contruction with an orbix ref. - // performs a <CORBA_REF::_duplicate>. + /// Assignment performs a <CORBA_REF::_duplicate>. CORBA_REF *operator= (CORBA_REF *ref); - // Assignment performs a <CORBA_REF::_duplicate>. + /// Type operator operator CORBA_REF *(void) const; - // Type operator + /// Smart pointer to forward all CORBA_REF calls to the underlying + /// Orbix reference. CORBA_REF *operator-> (void) const; - // Smart pointer to forward all CORBA_REF calls to the underlying - // Orbix reference. + /// Pointer comparison. int operator== (CORBA_REF *) const; - // Pointer comparison. + /// Pointer comparison. int operator!= (CORBA_REF *) const; - // Pointer comparison. + /// Destruction: calls <CORBA_REF::_release>. ~ACE_CORBA_Ref (void); - // Destruction: calls <CORBA_REF::_release>. private: CORBA_REF *ref_; diff --git a/ace/CORBA_macros.h b/ace/CORBA_macros.h index e5ba16c9062..cee5b5bbdaf 100644 --- a/ace/CORBA_macros.h +++ b/ace/CORBA_macros.h @@ -1,24 +1,19 @@ // $Id$ // ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// CORBA_macros.h -// -// = DESCRIPTION -// Writing code that is portable between platforms with or without -// native C++ exceptions is hard. The following macros offer some -// help on this task, mostly oriented to making the ORB code and the -// IDL generated code portable. -// -// = AUTHOR -// Nanbor Wang <nanbor@cs.wustl.edu> -// Based on the original <tao/try_macros.h> implementation by -// Aniruddha Gokhale <gokhale@sahyadri.research.bell-labs.com> -// Carlos O'Ryan <coryan@cs.wustl.edu>, et al. +/** + * @file CORBA_macros.h + * + * Writing code that is portable between platforms with or without + * native C++ exceptions is hard. The following macros offer some + * help on this task, mostly oriented to making the ORB code and the + * IDL generated code portable. + * + * @author Nanbor Wang <nanbor@cs.wustl.edu> + * @author Based on the original <tao/try_macros.h> implementation by + * @author Aniruddha Gokhale <gokhale@sahyadri.research.bell-labs.com> + * @author Carlos O'Ryan <coryan@cs.wustl.edu>, et al. + */ // ============================================================================ // Macros for handling CORBA exceptions. diff --git a/ace/Cache_Map_Manager_T.h b/ace/Cache_Map_Manager_T.h index bb9c070e40a..8286d914bff 100644 --- a/ace/Cache_Map_Manager_T.h +++ b/ace/Cache_Map_Manager_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Cache_Map_Manager.h -// -// = AUTHOR -// Kirthika Parameswaran <kirthika@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Cache_Map_Manager.h + * + * $Id$ + * + * @author Kirthika Parameswaran <kirthika@cs.wustl.edu> + */ +//============================================================================= + #ifndef CACHE_MAP_MANAGER_T_H #define CACHE_MAP_MANAGER_T_H @@ -53,23 +50,24 @@ class ACE_Cache_Map_Reverse_Iterator; // For linkers that cant grok long names. #define ACE_Cache_Map_Manager ACMM +/** + * @class ACE_Cache_Map_Manager + * + * @brief Defines a abstraction that will purge entries from a map. + * + * The <ACE_Cache_Map_Manager> will manage the map it contains + * and provide purging on demand from the map. The strategy for + * caching is decided by the user and provided to the Cache + * Manager. The Cache Manager acts as a agent and communicates + * between the Map and the Strategy for purging entries from the + * map. + * No locking mechanism provided since locking at this level + * isn't efficient. Locking has to be provided by the + * application. + */ template <ACE_T1> class ACE_Cache_Map_Manager { - // = TITLE - // Defines a abstraction that will purge entries from a map. - // - // = DESCRIPTION - // The <ACE_Cache_Map_Manager> will manage the map it contains - // and provide purging on demand from the map. The strategy for - // caching is decided by the user and provided to the Cache - // Manager. The Cache Manager acts as a agent and communicates - // between the Map and the Strategy for purging entries from the - // map. - // - // No locking mechanism provided since locking at this level - // isn't efficient. Locking has to be provided by the - // application. public: // = Traits. @@ -100,134 +98,150 @@ public: #endif /* ACE_HAS_BROKEN_EXTENDED_TEMPLATES */ + /** + * The actual value mapped to the key in the map. The <attributes> + * are used by the strategy and is transparent to the user of this + * class. + */ typedef ACE_Pair<VALUE, ATTRIBUTES> CACHE_VALUE; - // The actual value mapped to the key in the map. The <attributes> - // are used by the strategy and is transparent to the user of this - // class. // = Initialization and termination methods. + /// Initialize a <Cache_Map_Manager> with <caching_strategy> and + /// <size> entries. ACE_Cache_Map_Manager (CACHING_STRATEGY &caching_strategy, size_t size = ACE_DEFAULT_MAP_SIZE, ACE_Allocator *alloc = 0); - // Initialize a <Cache_Map_Manager> with <caching_strategy> and - // <size> entries. + /// Close down a <Cache_Map_Manager> and release dynamically allocated + /// resources. virtual ~ACE_Cache_Map_Manager (void); - // Close down a <Cache_Map_Manager> and release dynamically allocated - // resources. + /// Initialize a cache with size <length>. int open (size_t length = ACE_DEFAULT_MAP_SIZE, ACE_Allocator *alloc = 0); - // Initialize a cache with size <length>. + /// Close down a cache and release dynamically allocated resources. int close (void); - // Close down a cache and release dynamically allocated resources. + /** + * Associate <key> with <value>. If <key> is already in the MAP + * then the ENTRY is not changed. Returns 0 if a new entry is bound + * successfully, returns 1 if an attempt is made to bind an existing + * entry, and returns -1 if failures occur. + */ int bind (const KEY &key, const VALUE &value); - // Associate <key> with <value>. If <key> is already in the MAP - // then the ENTRY is not changed. Returns 0 if a new entry is bound - // successfully, returns 1 if an attempt is made to bind an existing - // entry, and returns -1 if failures occur. + /** + * Lookup entry<key,value> in the cache. If it is not found, returns -1. + * If the <key> is located in the MAP object, the CACHING_STRATEGY is + * notified of it via notify_find (int result, ATTRIBUTES &attribute). + * If notify_find also returns 0 (success), then this function returns + * 0 (success) and sets the cached value in <value>. + */ int find (const KEY &key, VALUE &value); - // Lookup entry<key,value> in the cache. If it is not found, returns -1. - // If the <key> is located in the MAP object, the CACHING_STRATEGY is - // notified of it via notify_find (int result, ATTRIBUTES &attribute). - // If notify_find also returns 0 (success), then this function returns - // 0 (success) and sets the cached value in <value>. + /** + * Lookup entry<key,value> in the cache. If it is not found, returns -1. + * If the <key> is located in the MAP object, the CACHING_STRATEGY is + * notified of it via notify_find (int result, ATTRIBUTES &attribute). + * If notify_find also returns 0 (success), then this function returns + * 0 (success). + */ int find (const KEY &key); - // Lookup entry<key,value> in the cache. If it is not found, returns -1. - // If the <key> is located in the MAP object, the CACHING_STRATEGY is - // notified of it via notify_find (int result, ATTRIBUTES &attribute). - // If notify_find also returns 0 (success), then this function returns - // 0 (success). + /** + * Reassociate the <key> with <value>. If the <key> already exists + * in the cache then returns 1, on a new bind returns 0 and returns + * -1 in case of any failures. + */ int rebind (const KEY &key, const VALUE &value); - // Reassociate the <key> with <value>. If the <key> already exists - // in the cache then returns 1, on a new bind returns 0 and returns - // -1 in case of any failures. + /** + * Reassociate <key> with <value>, storing the old value into the + * "out" parameter <old_value>. The function fails if <key> is not + * in the cache for caches that do not allow user specified keys. + * However, for caches that allow user specified keys, if the key is + * not in the cache, a new <key>/<value> association is created. + */ int rebind (const KEY &key, const VALUE &value, VALUE &old_value); - // Reassociate <key> with <value>, storing the old value into the - // "out" parameter <old_value>. The function fails if <key> is not - // in the cache for caches that do not allow user specified keys. - // However, for caches that allow user specified keys, if the key is - // not in the cache, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old key and value + * into the "out" parameters <old_key> and <old_value>. The + * function fails if <key> is not in the cache for caches that do + * not allow user specified keys. However, for caches that allow + * user specified keys, if the key is not in the cache, a new + * <key>/<value> association is created. + */ int rebind (const KEY &key, const VALUE &value, KEY &old_key, VALUE &old_value); - // Reassociate <key> with <value>, storing the old key and value - // into the "out" parameters <old_key> and <old_value>. The - // function fails if <key> is not in the cache for caches that do - // not allow user specified keys. However, for caches that allow - // user specified keys, if the key is not in the cache, a new - // <key>/<value> association is created. + /** + * Associate <key> with <value> if and only if <key> is not in the + * cache. If <key> is already in the cache, then the <value> + * parameter is overwritten with the existing value in the + * cache. Returns 0 if a new <key>/<value> association is created. + * Returns 1 if an attempt is made to bind an existing entry. This + * function fails for maps that do not allow user specified keys. + */ int trybind (const KEY &key, VALUE &value); - // Associate <key> with <value> if and only if <key> is not in the - // cache. If <key> is already in the cache, then the <value> - // parameter is overwritten with the existing value in the - // cache. Returns 0 if a new <key>/<value> association is created. - // Returns 1 if an attempt is made to bind an existing entry. This - // function fails for maps that do not allow user specified keys. + /// Remove <key> from the cache. int unbind (const KEY &key); - // Remove <key> from the cache. + /// Remove <key> from the cache, and return the <value> associated with + /// <key>. int unbind (const KEY &key, VALUE &value); - // Remove <key> from the cache, and return the <value> associated with - // <key>. + /// Remove entries from the cache depending upon the strategy. int purge (void); - // Remove entries from the cache depending upon the strategy. + /// Return the current size of the cache. size_t current_size (void) const; - // Return the current size of the cache. + /// Return the total size of the cache. size_t total_size (void) const; - // Return the total size of the cache. + /// Dumps the state of the object. void dump (void) const; - // Dumps the state of the object. #if !defined (ACE_HAS_BROKEN_EXTENDED_TEMPLATES) // = STL styled iterator factory functions. + /// Return forward iterator. ITERATOR begin (void); ITERATOR end (void); - // Return forward iterator. + /// Return reverse iterator. REVERSE_ITERATOR rbegin (void); REVERSE_ITERATOR rend (void); - // Return reverse iterator. #endif /* ACE_HAS_BROKEN_EXTENDED_TEMPLATES */ + /// The map managed by the Cache_Map_Manager. MAP &map (void); - // The map managed by the Cache_Map_Manager. + /// The caching strategy used on the cache. CACHING_STRATEGY &caching_strategy (void); - // The caching strategy used on the cache. protected: + /// The underlying map which needs to be cached. MAP map_; - // The underlying map which needs to be cached. + /// The strategy to be followed for caching entries in the map. CACHING_STRATEGY &caching_strategy_; - // The strategy to be followed for caching entries in the map. private: @@ -239,151 +253,155 @@ private: #if !defined (ACE_HAS_BROKEN_EXTENDED_TEMPLATES) +/** + * @class ACE_Cache_Map_Iterator + * + * @brief Defines a iterator for the Cache_Map_Manager. + * + * Implementation to be provided by the iterator of the map + * managed by the ACE_Cache_Map_Manager. + */ template <class KEY, class VALUE, class IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES> class ACE_Cache_Map_Iterator { - // = TITLE - // Defines a iterator for the Cache_Map_Manager. - // - // = DESCRIPTION - // Implementation to be provided by the iterator of the map - // managed by the ACE_Cache_Map_Manager. public: // = Traits. + /// The actual value mapped to the key in the cache. The <attributes> + /// are used by the strategy and is transperant to the cache user. typedef ACE_Reference_Pair<KEY, VALUE> value_type; typedef ACE_Pair <VALUE, ATTRIBUTES> CACHE_VALUE; - // The actual value mapped to the key in the cache. The <attributes> - // are used by the strategy and is transperant to the cache user. // = Initialisation and termination methods. ACE_Cache_Map_Iterator (const IMPLEMENTATION &iterator_impl); + /// Copy constructor. ACE_Cache_Map_Iterator (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs); - // Copy constructor. virtual ~ACE_Cache_Map_Iterator (void); // = Iteration methods. + /// assignment operator. ACE_Cache_Map_Iterator <KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator= (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs); - // assignment operator. + /// Comparision operators. int operator== (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const; int operator!= (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const; - // Comparision operators. + /// Returns a reference to the internal element <this> is pointing + /// to. ACE_Reference_Pair<KEY, VALUE> operator* (void) const; - // Returns a reference to the internal element <this> is pointing - // to. // = STL styled iteration, compare, and reference functions. + /// Prefix advance ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator++ (void); - // Prefix advance + /// Postfix advance. ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator++ (int); - // Postfix advance. + /// Prefix reverse. ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator-- (void); - // Prefix reverse. + /// Postfix reverse. ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator-- (int); - // Postfix reverse. + /// Returns the iterator of the internal map in the custody of the + /// Cache_Map_Manager. IMPLEMENTATION &iterator_implementation (void); - // Returns the iterator of the internal map in the custody of the - // Cache_Map_Manager. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// The actual iterator which iterates internally on the map + /// belonging to the Cache_Map_Manager. IMPLEMENTATION iterator_implementation_; - // The actual iterator which iterates internally on the map - // belonging to the Cache_Map_Manager. }; +/** + * @class ACE_Cache_Map_Reverse_Iterator + * + * @brief Defines a reverse iterator for the Cache_Map_Manager. + * + * Implementation to be provided by the reverse iterator of the map + * managed by thr Cache_Map_manager. + */ template <class KEY, class VALUE, class REVERSE_IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES> class ACE_Cache_Map_Reverse_Iterator { - // = TITLE - // Defines a reverse iterator for the Cache_Map_Manager. - // - // = DESCRIPTION - // Implementation to be provided by the reverse iterator of the map - // managed by thr Cache_Map_manager. public: // = Traits. + /// The actual value mapped to the key in the cache. The <attributes> + /// are used by the strategy and is transperant to the cache user. typedef ACE_Reference_Pair<KEY, VALUE> value_type; typedef ACE_Pair <VALUE, ATTRIBUTES> CACHE_VALUE; - // The actual value mapped to the key in the cache. The <attributes> - // are used by the strategy and is transperant to the cache user. // = Initialisation and termination methods. ACE_Cache_Map_Reverse_Iterator (const REVERSE_IMPLEMENTATION &iterator_impl); + /// Copy constructor. ACE_Cache_Map_Reverse_Iterator (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs); - // Copy constructor. ~ACE_Cache_Map_Reverse_Iterator (void); // = Iteration methods. + /// Assignment operator. ACE_Cache_Map_Reverse_Iterator <KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator= (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs); - // Assignment operator. + /// Comparision operators. int operator== (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const; int operator!= (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const; - // Comparision operators. + /// Returns a reference to the internal element <this> is pointing + /// to. ACE_Reference_Pair<KEY, VALUE> operator* (void) const; - // Returns a reference to the internal element <this> is pointing - // to. // = STL styled iteration, compare, and reference functions. + /// Prefix advance ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator++ (void); - // Prefix advance + /// Postfix advance. ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator++ (int); - // Postfix advance. + /// Prefix reverse. ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator-- (void); - // Prefix reverse. + /// Postfix reverse. ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator-- (int); - // Postfix reverse. + /// Returns the iterator of the internal map in the custody of the + /// Cache_Map_Manager. REVERSE_IMPLEMENTATION &iterator_implementation (void); - // Returns the iterator of the internal map in the custody of the - // Cache_Map_Manager. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// The actual iterator which iterates internally on the map + /// belonging to the Cache_Map_Manager. REVERSE_IMPLEMENTATION reverse_iterator_implementation_; - // The actual iterator which iterates internally on the map - // belonging to the Cache_Map_Manager. }; #endif /* ACE_HAS_BROKEN_EXTENDED_TEMPLATES */ diff --git a/ace/Cached_Connect_Strategy_T.h b/ace/Cached_Connect_Strategy_T.h index 0198253c17d..9c3050c0937 100644 --- a/ace/Cached_Connect_Strategy_T.h +++ b/ace/Cached_Connect_Strategy_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Cached_Connect_Strategy_T.h -// -// = AUTHOR -// Kirthika Parameswaran <kirthika@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Cached_Connect_Strategy_T.h + * + * $Id$ + * + * @author Kirthika Parameswaran <kirthika@cs.wustl.edu> + */ +//============================================================================= + #ifndef CACHED_CONNECT_STRATEGY_T_H #define CACHED_CONNECT_STRATEGY_T_H @@ -34,44 +31,48 @@ // For linkers which cant grok long names... #define ACE_Cached_Connect_Strategy_Ex ACCSE +/** + * @class ACE_Cached_Connect_Strategy_Ex + * + * @brief A connection strategy which caches connections to peers + * (represented by <SVC_HANDLER> instances), thereby allowing + * subsequent re-use of unused, but available, connections. + * + * <Cached_Connect_Strategy> is intended to be used as a + * plug-in connection strategy for <ACE_Strategy_Connector>. + * It's added value is re-use of established connections and + * tweaking the role of the cache as per the caching strategy. + */ template <class SVC_HANDLER, ACE_PEER_CONNECTOR_1, class CACHING_STRATEGY, class ATTRIBUTES, class MUTEX> class ACE_Cached_Connect_Strategy_Ex : public ACE_Cached_Connect_Strategy<SVC_HANDLER, ACE_PEER_CONNECTOR_2, MUTEX> { - // = TITLE - // A connection strategy which caches connections to peers - // (represented by <SVC_HANDLER> instances), thereby allowing - // subsequent re-use of unused, but available, connections. - // - // = DESCRIPTION - // <Cached_Connect_Strategy> is intended to be used as a - // plug-in connection strategy for <ACE_Strategy_Connector>. - // It's added value is re-use of established connections and - // tweaking the role of the cache as per the caching strategy. public: + /// Constructor ACE_Cached_Connect_Strategy_Ex (CACHING_STRATEGY &caching_s, ACE_Creation_Strategy<SVC_HANDLER> *cre_s = 0, ACE_Concurrency_Strategy<SVC_HANDLER> *con_s = 0, ACE_Recycling_Strategy<SVC_HANDLER> *rec_s = 0, MUTEX *lock = 0, int delete_lock = 0); - // Constructor + /// Destructor virtual ~ACE_Cached_Connect_Strategy_Ex (void); - // Destructor + /// Explicit purging of connection entries from the connection cache. virtual int purge_connections (void); - // Explicit purging of connection entries from the connection cache. + /// Mark as closed (non-locking version). This is used during the cleanup of the + /// connections purged. virtual int mark_as_closed_i (const void *recycling_act); - // Mark as closed (non-locking version). This is used during the cleanup of the - // connections purged. + /** + * Since g++ version < 2.8 arent happy with templates, this special + * method had to be devised to avoid memory leaks and perform + * cleanup of the <connection_cache_>. + */ void cleanup (void); - // Since g++ version < 2.8 arent happy with templates, this special - // method had to be devised to avoid memory leaks and perform - // cleanup of the <connection_cache_>. // = Typedefs for managing the map typedef ACE_Refcounted_Hash_Recyclable<ACE_PEER_CONNECTOR_ADDR> @@ -108,24 +109,24 @@ public: protected: + /// Find an idle handle. int find (ACE_Refcounted_Hash_Recyclable<ACE_PEER_CONNECTOR_ADDR> &search_addr, ACE_Hash_Map_Entry<ACE_Refcounted_Hash_Recyclable<ACE_PEER_CONNECTOR_ADDR>, ACE_Pair<SVC_HANDLER *, ATTRIBUTES> > *&entry); - // Find an idle handle. + /// Remove from cache (non-locking version). virtual int purge_i (const void *recycling_act); - // Remove from cache (non-locking version). + /// Add to cache (non-locking version). virtual int cache_i (const void *recycling_act); - // Add to cache (non-locking version). + /// Get/Set <recycle_state> (non-locking version). virtual int recycle_state_i (const void *recycling_act, ACE_Recyclable_State new_state); virtual ACE_Recyclable_State recycle_state_i (const void *recycling_act) const; - // Get/Set <recycle_state> (non-locking version). + /// Cleanup hint and reset <*act_holder> to zero if <act_holder != 0>. virtual int cleanup_hint_i (const void *recycling_act, void **act_holder); - // Cleanup hint and reset <*act_holder> to zero if <act_holder != 0>. // = Helpers int check_hint_i (SVC_HANDLER *&sh, @@ -157,6 +158,15 @@ protected: int perms, int &found); + /** + * Connection of the svc_handler with the remote host. This method + * also encapsulates the connection done with auto_purging under the + * hood. If the connect failed due to the process running out of + * file descriptors then, auto_purging of some connections are done + * from the CONNECTION_CACHE. This frees the descriptors which get + * used in the connect process and hence the connect operation can + * succeed. + */ virtual int cached_connect (SVC_HANDLER *&sh, const ACE_PEER_CONNECTOR_ADDR &remote_addr, ACE_Time_Value *timeout, @@ -164,16 +174,9 @@ protected: int reuse_addr, int flags, int perms); - // Connection of the svc_handler with the remote host. This method - // also encapsulates the connection done with auto_purging under the - // hood. If the connect failed due to the process running out of - // file descriptors then, auto_purging of some connections are done - // from the CONNECTION_CACHE. This frees the descriptors which get - // used in the connect process and hence the connect operation can - // succeed. + /// Table that maintains the cache of connected <SVC_HANDLER>s. CONNECTION_CACHE connection_cache_; - // Table that maintains the cache of connected <SVC_HANDLER>s. }; ///////////////////////////////////////////////////////////////////////////// @@ -181,25 +184,29 @@ protected: // For linkers which cant grok long names... #define ACE_Bounded_Cached_Connect_Strategy ABCCS -template <class SVC_HANDLER, ACE_PEER_CONNECTOR_1, class CACHING_STRATEGY, class ATTRIBUTES, class MUTEX> -class ACE_Bounded_Cached_Connect_Strategy : public - ACE_Cached_Connect_Strategy_Ex<SVC_HANDLER, ACE_PEER_CONNECTOR_2, CACHING_STRATEGY, ATTRIBUTES, MUTEX> - { - // = TITLE - // A connection strategy which caches connections to peers - // (represented by <SVC_HANDLER> instances), thereby allowing - // subsequent re-use of unused, but available, connections. - // This strategy should be used when the cache is bounded by - // maximum size. - // - // = DESCRIPTION - // <Bounded_Cached_Connect_Strategy> is intended to be used as a - // plug-in connection strategy for <ACE_Strategy_Connector>. - // It's added value is re-use of established connections and - // tweaking the role of the cache as per the caching strategy. - // Thanks to Edan Ayal <edana@bandwiz.com> for contributing this - // class and Susan Liebeskind <shl@janis.gtri.gatech.edu> for - // brainstorming about it. +/** + * @class ACE_Bounded_Cached_Connect_Strategy + * + * @brief A connection strategy which caches connections to peers + * (represented by <SVC_HANDLER> instances), thereby allowing + * subsequent re-use of unused, but available, connections. + * This strategy should be used when the cache is bounded by + * maximum size. + * + * <Bounded_Cached_Connect_Strategy> is intended to be used as a + * plug-in connection strategy for <ACE_Strategy_Connector>. + * It's added value is re-use of established connections and + * tweaking the role of the cache as per the caching strategy. + * Thanks to Edan Ayal <edana@bandwiz.com> for contributing this + * class and Susan Liebeskind <shl@janis.gtri.gatech.edu> for + * brainstorming about it. + */ +template <class SVC_HANDLER, ACE_PEER_CONNECTOR_1, + class CACHING_STRATEGY, class ATTRIBUTES, + class MUTEX> + class ACE_Bounded_Cached_Connect_Strategy + : public ACE_Cached_Connect_Strategy_Ex<SVC_HANDLER, ACE_PEER_CONNECTOR_2, CACHING_STRATEGY, ATTRIBUTES, MUTEX> +{ typedef ACE_Cached_Connect_Strategy_Ex<SVC_HANDLER, ACE_PEER_CONNECTOR_2, CACHING_STRATEGY, ATTRIBUTES, MUTEX> CCSEBASE; @@ -210,6 +217,7 @@ class ACE_Bounded_Cached_Connect_Strategy : public public: + /// Constructor ACE_Bounded_Cached_Connect_Strategy (size_t max_size, CACHING_STRATEGY &caching_s, ACE_Creation_Strategy<SVC_HANDLER> *cre_s = 0, @@ -217,13 +225,12 @@ class ACE_Bounded_Cached_Connect_Strategy : public ACE_Recycling_Strategy<SVC_HANDLER> *rec_s = 0, MUTEX *lock = 0, int delete_lock = 0); - // Constructor + /// Destructor virtual ~ACE_Bounded_Cached_Connect_Strategy (void); - // Destructor + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: @@ -238,8 +245,8 @@ class ACE_Bounded_Cached_Connect_Strategy : public ACE_Pair<SVC_HANDLER *, ATTRIBUTES> > *&entry, int &found); + /// max items in the cache, used as a bound for the creation of svc_handlers. size_t max_size_; - // max items in the cache, used as a bound for the creation of svc_handlers. }; diff --git a/ace/Caching_Strategies_T.h b/ace/Caching_Strategies_T.h index 8fd8c86aa06..5871d5b397e 100644 --- a/ace/Caching_Strategies_T.h +++ b/ace/Caching_Strategies_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Caching_Strategies_T.h -// -// = AUTHOR -// Kirthika Parameswaran <kirthika@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Caching_Strategies_T.h + * + * $Id$ + * + * @author Kirthika Parameswaran <kirthika@cs.wustl.edu> + */ +//============================================================================= + #ifndef CACHING_STRATEGIES_H #define CACHING_STRATEGIES_H @@ -33,23 +30,25 @@ // For linkers that cant grok long names. #define ACE_Caching_Strategy ACS +/** + * @class ACE_Caching_Strategy + * + * @brief This class is an abstract base class for a caching strategy. + * + * This class consists of all the interfaces a caching strategy should have and + * is used in association with the ACE_Caching_Strategy_Adaptor. + */ template <class ATTRIBUTES, class CACHING_UTILITY> class ACE_Caching_Strategy { - // = TITLE - // This class is an abstract base class for a caching strategy. - // - // = DESCRIPTION - // This class consists of all the interfaces a caching strategy should have and - // is used in association with the ACE_Caching_Strategy_Adaptor. public: + /// Destructor. virtual ~ACE_Caching_Strategy (void); - // Destructor. + /// Accessor method for the timer attributes. virtual ATTRIBUTES attributes (void) = 0; - // Accessor method for the timer attributes. // = Accessor methods for the percentage of entries to purge. virtual double purge_percent (void) = 0; @@ -57,66 +56,68 @@ public: // = Strategy related Operations + /// This method acts as a notification about the CONTAINERs bind + /// method call. virtual int notify_bind (int result, const ATTRIBUTES &attr) = 0; - // This method acts as a notification about the CONTAINERs bind - // method call. + /// This method acts as a notification about the CONTAINERs find + /// method call virtual int notify_find (int result, ATTRIBUTES &attr) = 0; - // This method acts as a notification about the CONTAINERs find - // method call + /// This method acts as a notification about the CONTAINERs unbind + /// method call virtual int notify_unbind (int result, const ATTRIBUTES &attr) = 0; - // This method acts as a notification about the CONTAINERs unbind - // method call + /// This method acts as a notification about the CONTAINERs trybind + /// method call virtual int notify_trybind (int result, ATTRIBUTES &attr) = 0; - // This method acts as a notification about the CONTAINERs trybind - // method call + /// This method acts as a notification about the CONTAINERs rebind + /// method call virtual int notify_rebind (int result, const ATTRIBUTES &attr) = 0; - // This method acts as a notification about the CONTAINERs rebind - // method call + /// Purge the cache. virtual CACHING_UTILITY &caching_utility (void) = 0; - // Purge the cache. + /// Dumps the state of the object. virtual void dump (void) const = 0; - // Dumps the state of the object. }; ////////////////////////////////////////////////////////////////////////// #define ACE_Caching_Strategy_Adapter ACSA +/** + * @class ACE_Caching_Strategy_Adapter + * + * @brief This class follows the Adaptor pattern and is used to provide + * External Polymorphism by deriving from ACE_Caching_Strategy. + * + * This class simply delegates all requests to the + * IMPLEMNETATION object within. This class should be passed in + * place of the the abstract base ACE_Caching_Strategy class as + * part of the External Polymorphism pattern. + */ template <class ATTRIBUTES, class CACHING_UTILITY, class IMPLEMENTATION> class ACE_Caching_Strategy_Adapter : public ACE_Caching_Strategy<ATTRIBUTES, CACHING_UTILITY> { - // = TITLE - // This class follows the Adaptor pattern and is used to provide - // External Polymorphism by deriving from ACE_Caching_Strategy. - // - // = DESCRIPTION - // This class simply delegates all requests to the - // IMPLEMNETATION object within. This class should be passed in - // place of the the abstract base ACE_Caching_Strategy class as - // part of the External Polymorphism pattern. public: + /// Constructor. ACE_Caching_Strategy_Adapter (IMPLEMENTATION *implementation = 0, int delete_implementation = 0); - // Constructor. + /// Destructor. ~ACE_Caching_Strategy_Adapter (void); - // Destructor. + /// Accessor method for the timer attributes. ATTRIBUTES attributes (void); - // Accessor method for the timer attributes. // = Accessor methods for the percentage of entries to purge. double purge_percent (void); @@ -124,73 +125,74 @@ public: // = Strategy related Operations + /// This method acts as a notification about the CONTAINERs bind + /// method call. int notify_bind (int result, const ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs bind - // method call. + /// This method acts as a notification about the CONTAINERs find + /// method call int notify_find (int result, ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs find - // method call + /// This method acts as a notification about the CONTAINERs unbind + /// method call int notify_unbind (int result, const ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs unbind - // method call + /// This method acts as a notification about the CONTAINERs trybind + /// method call int notify_trybind (int result, ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs trybind - // method call + /// This method acts as a notification about the CONTAINERs rebind + /// method call int notify_rebind (int result, const ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs rebind - // method call + /// Accessor to the implementation. IMPLEMENTATION &implementation (void); - // Accessor to the implementation. + /// Purge the cache. CACHING_UTILITY &caching_utility (void); - // Purge the cache. + /// Dumps the state of the object. void dump (void) const; - // Dumps the state of the object. private: + /// Implementation class. IMPLEMENTATION *implementation_; - // Implementation class. + /// Do we need to delete the implementation? int delete_implementation_; - // Do we need to delete the implementation? }; ////////////////////////////////////////////////////////////////////////// #define ACE_LRU_Caching_Strategy ALRU +/** + * @class ACE_LRU_Caching_Strategy + * + * @brief Defines a Least Recently Used strategy which will decide on + * the item to be removed from the cache. + * + * This is a strategy which makes use of a virtual timer which + * is updated whenever an item is inserted or looked up in the + * container. When the need of purging entries arises, the items + * with the lowest timer values are removed. + * Explanation of the template parameter list: + * CONTAINER is any map with entries of type <KEY, VALUE>. + * The ATTRIBUTES are the deciding factor for purging of entries + * and should logically be included with the VALUE. Some ways of + * doing this are: As being a member of the VALUE or VALUE being + * ACE_Pair<x, ATTRIBUTES>. The CACHING_UTILITY is the + * class which can be plugged in and which decides the entries + * to purge. + */ template <class ATTRIBUTES, class CACHING_UTILITY> class ACE_LRU_Caching_Strategy { - // = TITLE - // Defines a Least Recently Used strategy which will decide on - // the item to be removed from the cache. - // - // = DESCRIPTION - // This is a strategy which makes use of a virtual timer which - // is updated whenever an item is inserted or looked up in the - // container. When the need of purging entries arises, the items - // with the lowest timer values are removed. - // - // Explanation of the template parameter list: - // CONTAINER is any map with entries of type <KEY, VALUE>. - // The ATTRIBUTES are the deciding factor for purging of entries - // and should logically be included with the VALUE. Some ways of - // doing this are: As being a member of the VALUE or VALUE being - // ACE_Pair<x, ATTRIBUTES>. The CACHING_UTILITY is the - // class which can be plugged in and which decides the entries - // to purge. public: @@ -199,17 +201,19 @@ public: // = Initialisation and termination. + /** + * The <container> is the map in which the entries reside. The + * timer attribute is initialed to zero in this constructor. And + * the <purge_percent> field denotes the percentage of the entries + * in the cache which can be purged automagically and by default is + * set to 10%. + */ ACE_LRU_Caching_Strategy (void); - // The <container> is the map in which the entries reside. The - // timer attribute is initialed to zero in this constructor. And - // the <purge_percent> field denotes the percentage of the entries - // in the cache which can be purged automagically and by default is - // set to 10%. // = Operations of the strategy. + /// Accessor method for the timer attributes. ATTRIBUTES attributes (void); - // Accessor method for the timer attributes. // = Accessor methods for the percentage of entries to purge. double purge_percent (void); @@ -218,76 +222,77 @@ public: // = Strategy related Operations + /// This method acts as a notification about the CONTAINERs bind + /// method call. int notify_bind (int result, const ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs bind - // method call. + /// This method acts as a notification about the CONTAINERs find + /// method call int notify_find (int result, ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs find - // method call + /// This method acts as a notification about the CONTAINERs unbind + /// method call int notify_unbind (int result, const ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs unbind - // method call + /// This method acts as a notification about the CONTAINERs trybind + /// method call int notify_trybind (int result, ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs trybind - // method call + /// This method acts as a notification about the CONTAINERs rebind + /// method call int notify_rebind (int result, const ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs rebind - // method call + /// Purge the cache. CACHING_UTILITY &caching_utility (void); - // Purge the cache. + /// Dumps the state of the object. void dump (void) const; - // Dumps the state of the object. private: + /// This element is the one which is the deciding factor for purging + /// of an ITEM. ATTRIBUTES timer_; - // This element is the one which is the deciding factor for purging - // of an ITEM. + /// The level about which the purging will happen automagically. double purge_percent_; - // The level about which the purging will happen automagically. + /// This is the helper class which will decide and expunge entries + /// from the cache. CACHING_UTILITY caching_utility_; - // This is the helper class which will decide and expunge entries - // from the cache. }; ////////////////////////////////////////////////////////////////////////// #define ACE_LFU_Caching_Strategy ALFU +/** + * @class ACE_LFU_Caching_Strategy + * + * @brief Defines a Least Frequently Used strategy for which will decide on + * the item to be removed from the cache. + * + * A attribute is tagged to each item which increments whenever + * the item is bound or looked up in the cache. Thus it denotes + * the frequency of use. According to the value of the attribute + * the item is removed from the CONTAINER i.e cache. + * Explanation of the template parameter list: + * CONTAINER is any map with entries of type <KEY, VALUE>. + * The ATTRIBUTES are the deciding factor for purging of entries + * and should logically be included with the VALUE. Some ways of + * doing this are: As being a member of the VALUE or VALUE being + * ACE_Pair<x, ATTRIBUTES>. The CACHING_UTILITY is the + * class which can be plugged in and which decides the entries + * to purge. + */ template <class ATTRIBUTES, class CACHING_UTILITY> class ACE_LFU_Caching_Strategy { - // = TITLE - // Defines a Least Frequently Used strategy for which will decide on - // the item to be removed from the cache. - // - // = DESCRIPTION - // A attribute is tagged to each item which increments whenever - // the item is bound or looked up in the cache. Thus it denotes - // the frequency of use. According to the value of the attribute - // the item is removed from the CONTAINER i.e cache. - // - // Explanation of the template parameter list: - // CONTAINER is any map with entries of type <KEY, VALUE>. - // The ATTRIBUTES are the deciding factor for purging of entries - // and should logically be included with the VALUE. Some ways of - // doing this are: As being a member of the VALUE or VALUE being - // ACE_Pair<x, ATTRIBUTES>. The CACHING_UTILITY is the - // class which can be plugged in and which decides the entries - // to purge. public: @@ -296,17 +301,19 @@ public: // = Initialisation and termination methods. + /** + * The <container> is the map in which the entries reside. The + * timer attribute is initialed to zero in this constructor. And + * the <purge_percent> field denotes the percentage of the entries + * in the cache which can be purged automagically and by default is + * set to 10%. + */ ACE_LFU_Caching_Strategy (void); - // The <container> is the map in which the entries reside. The - // timer attribute is initialed to zero in this constructor. And - // the <purge_percent> field denotes the percentage of the entries - // in the cache which can be purged automagically and by default is - // set to 10%. // = Strategy methods. + /// Access the attributes. ATTRIBUTES attributes (void); - // Access the attributes. // = Accessor methods for the percentage of entries to purge. double purge_percent (void); @@ -315,68 +322,69 @@ public: // = Strategy related Operations + /// This method acts as a notification about the CONTAINERs bind + /// method call. int notify_bind (int result, const ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs bind - // method call. + /// Lookup notification. int notify_find (int result, ATTRIBUTES &attr); - // Lookup notification. + /// This method acts as a notification about the CONTAINERs unbind + /// method call int notify_unbind (int result, const ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs unbind - // method call + /// This method acts as a notification about the CONTAINERs trybind + /// method call int notify_trybind (int result, ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs trybind - // method call + /// This method acts as a notification about the CONTAINERs rebind + /// method call int notify_rebind (int result, const ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs rebind - // method call + /// Purge the cache. CACHING_UTILITY &caching_utility (void); - // Purge the cache. + /// Dumps the state of the object. void dump (void) const; - // Dumps the state of the object. private: + /// The level about which the purging will happen automagically. double purge_percent_; - // The level about which the purging will happen automagically. + /// This is the helper class which will decide and expunge entries + /// from the cache. CACHING_UTILITY caching_utility_; - // This is the helper class which will decide and expunge entries - // from the cache. }; ///////////////////////////////////////////////////////////// #define ACE_FIFO_Caching_Strategy AFIFO +/** + * @class ACE_FIFO_Caching_Strategy + * + * @brief The First In First Out strategy is implemented wherein each + * item is ordered. + * + * The order tag of each item is used to decide the item to be + * removed from the cache. The items with least order are removed. + * Explanation of the template parameter list: + * CONTAINER is any map with entries of type <KEY, VALUE>. + * The ATTRIBUTES are the deciding factor for purging of entries + * and should logically be included with the VALUE. Some ways of + * doing this are: As being a member of the VALUE or VALUE being + * ACE_Pair<x, ATTRIBUTES>. The CACHING_UTILITY is the + * class which can be plugged in and which decides the entries + * to purge. + */ template<class ATTRIBUTES, class CACHING_UTILITY> class ACE_FIFO_Caching_Strategy { - // = TITLE - // The First In First Out strategy is implemented wherein each - // item is ordered. - // - // = DESCRIPTION - // The order tag of each item is used to decide the item to be - // removed from the cache. The items with least order are removed. - // - // Explanation of the template parameter list: - // CONTAINER is any map with entries of type <KEY, VALUE>. - // The ATTRIBUTES are the deciding factor for purging of entries - // and should logically be included with the VALUE. Some ways of - // doing this are: As being a member of the VALUE or VALUE being - // ACE_Pair<x, ATTRIBUTES>. The CACHING_UTILITY is the - // class which can be plugged in and which decides the entries - // to purge. public: @@ -384,17 +392,19 @@ public: // = Initialisation and termination. + /** + * The <container> is the map in which the entries reside. The + * timer attribute is initialed to zero in this constructor. And + * the <purge_percent> field denotes the percentage of the entries + * in the cache which can be purged automagically and by default is + * set to 10%. + */ ACE_FIFO_Caching_Strategy (void); - // The <container> is the map in which the entries reside. The - // timer attribute is initialed to zero in this constructor. And - // the <purge_percent> field denotes the percentage of the entries - // in the cache which can be purged automagically and by default is - // set to 10%. // = Strategy methods. + /// Accessor method. ATTRIBUTES attributes (void); - // Accessor method. // = Accessor methods for the percentage of entries to purge. double purge_percent (void); @@ -403,62 +413,64 @@ public: // = Strategy related Operations + /// Notification for an item getting bound into the cache. int notify_bind (int result, const ATTRIBUTES &attr); - // Notification for an item getting bound into the cache. + /// This method acts as a notification about the CONTAINERs find + /// method call int notify_find (int result, ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs find - // method call + /// This method acts as a notification about the CONTAINERs unbind + /// method call int notify_unbind (int result, const ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs unbind - // method call + /// This method acts as a notification about the CONTAINERs trybind + /// method call int notify_trybind (int result, ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs trybind - // method call + /// Notification for an item getting bound again into the cache. int notify_rebind (int result, const ATTRIBUTES &attr); - // Notification for an item getting bound again into the cache. + /// Purge the cache. CACHING_UTILITY &caching_utility (void); - // Purge the cache. + /// Dumps the state of the object. void dump (void) const; - // Dumps the state of the object. private: + /// The order is the deciding factor for the item to be removed from + /// the cache. ATTRIBUTES order_; - // The order is the deciding factor for the item to be removed from - // the cache. + /// The level about which the purging will happen automagically. double purge_percent_; - // The level about which the purging will happen automagically. + /// This is the helper class which will decide and expunge entries + /// from the cache. CACHING_UTILITY caching_utility_; - // This is the helper class which will decide and expunge entries - // from the cache. }; ////////////////////////////////////////////////////////////////////// #define ACE_Null_Caching_Strategy ANULL +/** + * @class ACE_Null_Caching_Strategy + * + * @brief The is a special caching strategy which doesnt have the purging + * feature. + * + * No purging provided. To be used when purging might be too expensive + * an operation. + */ template<class ATTRIBUTES, class CACHING_UTILITY> class ACE_Null_Caching_Strategy { - // = TITLE - // The is a special caching strategy which doesnt have the purging - // feature. - // - // = DESCRIPTION - // No purging provided. To be used when purging might be too expensive - // an operation. public: @@ -467,8 +479,8 @@ public: // = Strategy methods. All are NO_OP methods!!! + /// Accessor method. ATTRIBUTES attributes (void); - // Accessor method. // = Accessor methods for the percentage of entries to purge. double purge_percent (void); @@ -477,40 +489,40 @@ public: // = Strategy related Operations + /// Notification for an item getting bound into the cache. int notify_bind (int result, const ATTRIBUTES &attr); - // Notification for an item getting bound into the cache. + /// This method acts as a notification about the CONTAINERs find + /// method call int notify_find (int result, ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs find - // method call + /// This method acts as a notification about the CONTAINERs unbind + /// method call int notify_unbind (int result, const ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs unbind - // method call + /// This method acts as a notification about the CONTAINERs trybind + /// method call int notify_trybind (int result, ATTRIBUTES &attr); - // This method acts as a notification about the CONTAINERs trybind - // method call + /// Notification for an item getting bound again into the cache. int notify_rebind (int result, const ATTRIBUTES &attr); - // Notification for an item getting bound again into the cache. + /// Purge the cache. CACHING_UTILITY &caching_utility (void); - // Purge the cache. + /// Dumps the state of the object. void dump (void) const; - // Dumps the state of the object. private: + /// This is the helper class which will decide and expunge entries + /// from the cache. CACHING_UTILITY caching_utility_; - // This is the helper class which will decide and expunge entries - // from the cache. }; #if defined (__ACE_INLINE__) diff --git a/ace/Caching_Utility_T.h b/ace/Caching_Utility_T.h index 17db3a5b081..3714215f148 100644 --- a/ace/Caching_Utility_T.h +++ b/ace/Caching_Utility_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Caching_Utility_T.h -// -// = AUTHOR -// Kirthika Parameswaran <kirthika@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Caching_Utility_T.h + * + * $Id$ + * + * @author Kirthika Parameswaran <kirthika@cs.wustl.edu> + */ +//============================================================================= + #ifndef CACHING_UTILITY_H #define CACHING_UTILITY_H @@ -29,21 +26,23 @@ // For linkers that cant grok long names. #define ACE_Pair_Caching_Utility APUTIL +/** + * @class ACE_Pair_Caching_Utility + * + * @brief Defines a helper class for the Caching Strategies. + * + * This class defines the methods commonly used by the different + * caching strategies. For instance: <clear_cache> method which + * decides and purges the entry from the container. Note: This + * class helps in the caching_strategies using a container + * containing entries of <KEY, ACE_Pair<VALUE, attributes>> + * kind. The attributes helps in deciding the entries to be + * purged. The Cleanup_Strategy is the callback class to which the + * entries to be cleaned up will be delegated. + */ template <class KEY, class VALUE, class CONTAINER, class ITERATOR, class ATTRIBUTES> class ACE_Pair_Caching_Utility { - // = TITLE - // Defines a helper class for the Caching Strategies. - // - // = DESCRIPTION - // This class defines the methods commonly used by the different - // caching strategies. For instance: <clear_cache> method which - // decides and purges the entry from the container. Note: This - // class helps in the caching_strategies using a container - // containing entries of <KEY, ACE_Pair<VALUE, attributes>> - // kind. The attributes helps in deciding the entries to be - // purged. The Cleanup_Strategy is the callback class to which the - // entries to be cleaned up will be delegated. public: typedef ACE_Cleanup_Strategy<KEY, VALUE, CONTAINER> CLEANUP_STRATEGY; @@ -53,8 +52,8 @@ public: // Constructor. + /// Destructor. ~ACE_Pair_Caching_Utility (void); - // Destructor. int clear_cache (CONTAINER &container, double purge_percent); @@ -65,37 +64,39 @@ public: protected: + /// Find the entry with minimum caching attributes. void minimum (CONTAINER &container, KEY *&key_to_remove, VALUE *&value_to_remove); - // Find the entry with minimum caching attributes. + /// The cleanup strategy which can be used to destroy the entries of + /// the container. CLEANUP_STRATEGY *cleanup_strategy_; - // The cleanup strategy which can be used to destroy the entries of - // the container. + /// Whether the cleanup_strategy should be destroyed or not. int delete_cleanup_strategy_; - // Whether the cleanup_strategy should be destroyed or not. }; //////////////////////////////////////////////////////////////////////////////// #define ACE_Recyclable_Handler_Caching_Utility ARHUTIL +/** + * @class ACE_Recyclable_Handler_Caching_Utility + * + * @brief Defines a helper class for the Caching Strategies. + * + * This class defines the methods commonly used by the different + * caching strategies. For instance: <clear_cache> method which + * decides and purges the entry from the container. Note: This + * class helps in the caching_strategies using a container + * containing entries of <KEY, Svc_Handler> kind. The attributes + * helps in deciding the entries to be purged. The + * Cleanup_Strategy is the callback class to which the entries to + * be cleaned up will be delegated. + */ template <class KEY, class VALUE, class CONTAINER, class ITERATOR, class ATTRIBUTES> class ACE_Recyclable_Handler_Caching_Utility { - // = TITLE - // Defines a helper class for the Caching Strategies. - // - // = DESCRIPTION - // This class defines the methods commonly used by the different - // caching strategies. For instance: <clear_cache> method which - // decides and purges the entry from the container. Note: This - // class helps in the caching_strategies using a container - // containing entries of <KEY, Svc_Handler> kind. The attributes - // helps in deciding the entries to be purged. The - // Cleanup_Strategy is the callback class to which the entries to - // be cleaned up will be delegated. public: @@ -107,49 +108,53 @@ public: // Constructor. + /// Destructor. ~ACE_Recyclable_Handler_Caching_Utility (void); - // Destructor. + /** + * Purge entries from the <container>. The Cleanup_Strategy will do + * the actual job of cleanup once the entries to be cleaned up are + * decided. + */ int clear_cache (CONTAINER &container, double purge_percent); - // Purge entries from the <container>. The Cleanup_Strategy will do - // the actual job of cleanup once the entries to be cleaned up are - // decided. protected: + /// Find the entry with minimum caching attributes. void minimum (CONTAINER &container, KEY *&key_to_remove, VALUE *&value_to_remove); - // Find the entry with minimum caching attributes. + /// This is the default Cleanup Strategy for this utility. CLEANUP_STRATEGY_BASE *cleanup_strategy_; - // This is the default Cleanup Strategy for this utility. + /// Whether the cleanup_strategy should be destroyed or not. int delete_cleanup_strategy_; - // Whether the cleanup_strategy should be destroyed or not. }; -//////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////// #define ACE_Refcounted_Recyclable_Handler_Caching_Utility ARRHUTIL +/** + * @class ACE_Refcounted_Recyclable_Handler_Caching_Utility + * + * @brief Defines a helper class for the Caching Strategies. + * + * This class defines the methods commonly used by the different + * caching strategies. For instance: clear_cache () method which + * decides and purges the entry from the container. Note: This + * class helps in the caching_strategies using a container + * containing entries of <Refcounted_KEY, + * Recyclable_Connection_Handler> kind. The attributes helps in + * deciding the entries to be purged. The Cleanup_Strategy is the + * callback class to which the entries to be cleaned up will be + * delegated. + */ template <class KEY, class VALUE, class CONTAINER, class ITERATOR, class ATTRIBUTES> class ACE_Refcounted_Recyclable_Handler_Caching_Utility { - // = TITLE - // Defines a helper class for the Caching Strategies. - // - // = DESCRIPTION - // This class defines the methods commonly used by the different - // caching strategies. For instance: clear_cache () method which - // decides and purges the entry from the container. Note: This - // class helps in the caching_strategies using a container - // containing entries of <Refcounted_KEY, - // Recyclable_Connection_Handler> kind. The attributes helps in - // deciding the entries to be purged. The Cleanup_Strategy is the - // callback class to which the entries to be cleaned up will be - // delegated. public: @@ -161,138 +166,154 @@ public: // Constructor. + /// Destructor. ~ACE_Refcounted_Recyclable_Handler_Caching_Utility (void); - // Destructor. + /** + * Purge entries from the <container>. The Cleanup_Strategy will do + * the actual job of cleanup once the entries to be cleaned up are + * decided. + */ int clear_cache (CONTAINER &container, double purge_percent); - // Purge entries from the <container>. The Cleanup_Strategy will do - // the actual job of cleanup once the entries to be cleaned up are - // decided. protected: + /// Find the entry with minimum caching attributes. void minimum (CONTAINER &container, KEY *&key_to_remove, VALUE *&value_to_remove); - // Find the entry with minimum caching attributes. + /// This is the default Cleanup Strategy for this utility. CLEANUP_STRATEGY_BASE *cleanup_strategy_; - // This is the default Cleanup Strategy for this utility. + /// Whether the cleanup_strategy should be destroyed or not. int delete_cleanup_strategy_; - // Whether the cleanup_strategy should be destroyed or not. + /** + * This figure denotes the number of entries are there in the + * container which have been marked as closed already but might + * not have been unbound from the container. + */ size_t marked_as_closed_entries_; - // This figure denotes the number of entries are there in the - // container which have been marked as closed already but might - // not have been unbound from the container. }; //////////////////////////////////////////////////////////////////////////////////////// +/** + * @class ACE_Handler_Caching_Utility + * + * @brief Defines a helper class for the Caching Strategies. + * + * This class defines the methods commonly used by the different + * caching strategies. For instance: <clear_cache> method which + * decides and purges the entry from the container. Note: This + * class helps in the caching_strategies using a container + * containing entries of <KEY, HANDLER> kind where the HANDLER + * contains the caching attributes which help in deciding the + * entries to be purged. The Cleanup_Strategy is the callback + * class to which the entries to be cleaned up will be delegated. + */ template <class KEY, class VALUE, class CONTAINER, class ITERATOR, class ATTRIBUTES> class ACE_Handler_Caching_Utility { - // = TITLE - // Defines a helper class for the Caching Strategies. - // - // = DESCRIPTION - // This class defines the methods commonly used by the different - // caching strategies. For instance: <clear_cache> method which - // decides and purges the entry from the container. Note: This - // class helps in the caching_strategies using a container - // containing entries of <KEY, HANDLER> kind where the HANDLER - // contains the caching attributes which help in deciding the - // entries to be purged. The Cleanup_Strategy is the callback - // class to which the entries to be cleaned up will be delegated. public: typedef ACE_Handler_Cleanup_Strategy<KEY, VALUE, CONTAINER> CLEANUP_STRATEGY; typedef ACE_Cleanup_Strategy<KEY, VALUE, CONTAINER> CLEANUP_STRATEGY_BASE; + /// Constructor. ACE_Handler_Caching_Utility (ACE_Cleanup_Strategy<KEY, VALUE, CONTAINER> *cleanup_strategy = 0, int delete_cleanup_strategy = 0); - // Constructor. + /// Destructor. ~ACE_Handler_Caching_Utility (void); - // Destructor. + /** + * Purge entries from the <container>. The Cleanup_Strategy will do + * the actual job of cleanup once the entries to be cleaned up are + * decided. + */ int clear_cache (CONTAINER &container, double purge_percent); - // Purge entries from the <container>. The Cleanup_Strategy will do - // the actual job of cleanup once the entries to be cleaned up are - // decided. protected: + /** + * Find the entry with minimum caching attributes. This is handler + * specific since this utility is to be used very specifically for + * handler who have caching_attributes for server side acched + * connection management. + */ void minimum (CONTAINER &container, KEY *&key_to_remove, VALUE *&value_to_remove); - // Find the entry with minimum caching attributes. This is handler - // specific since this utility is to be used very specifically for - // handler who have caching_attributes for server side acched - // connection management. + /// The cleanup strategy which can be used to destroy the entries of + /// the container. CLEANUP_STRATEGY_BASE *cleanup_strategy_; - // The cleanup strategy which can be used to destroy the entries of - // the container. + /// Whether the cleanup_strategy should be destroyed or not. int delete_cleanup_strategy_; - // Whether the cleanup_strategy should be destroyed or not. }; /////////////////////////////////////////////////////////////////////////// #define ACE_Null_Caching_Utility ANUTIL +/** + * @class ACE_Null_Caching_Utility + * + * @brief Defines a dummy helper class for the Caching Strategies. + * + * This class defines the methods commonly used by the different + * caching strategies. For instance: <clear_cache> method which + * decides and purges the entry from the container. Note: This + * class is be used with the Null_Caching_Strategy. The + * Cleanup_Strategy is the callback class to which the entries to + * be cleaned up will be delegated. + */ template <class KEY, class VALUE, class CONTAINER, class ITERATOR, class ATTRIBUTES> class ACE_Null_Caching_Utility { - // = TITLE - // Defines a dummy helper class for the Caching Strategies. - // - // = DESCRIPTION - // This class defines the methods commonly used by the different - // caching strategies. For instance: <clear_cache> method which - // decides and purges the entry from the container. Note: This - // class is be used with the Null_Caching_Strategy. The - // Cleanup_Strategy is the callback class to which the entries to - // be cleaned up will be delegated. public: typedef ACE_Null_Cleanup_Strategy<KEY, VALUE, CONTAINER> CLEANUP_STRATEGY; typedef ACE_Cleanup_Strategy<KEY, VALUE, CONTAINER> CLEANUP_STRATEGY_BASE; + /// Constructor. ACE_Null_Caching_Utility (ACE_Cleanup_Strategy<KEY, VALUE, CONTAINER> *cleanup_strategy = 0, int delete_cleanup_strategy = 0); - // Constructor. + /// Destructor. ~ACE_Null_Caching_Utility (void); - // Destructor. + /** + * Purge entries from the <container>. The Cleanup_Strategy will do + * the actual job of cleanup once the entries to be cleaned up are + * decided. NOte: Here it is a no-op. + */ int clear_cache (CONTAINER &container, double purge_percent); - // Purge entries from the <container>. The Cleanup_Strategy will do - // the actual job of cleanup once the entries to be cleaned up are - // decided. NOte: Here it is a no-op. protected: + /** + * Find the entry with minimum caching attributes. This is handler + * specific since this utility is to be used very specifically for + * handler who have caching_attributes for server side acched + * connection management.Note: Here it is a no-op. + */ void minimum (CONTAINER &container, KEY *&key_to_remove, VALUE *&value_to_remove); - // Find the entry with minimum caching attributes. This is handler - // specific since this utility is to be used very specifically for - // handler who have caching_attributes for server side acched - // connection management.Note: Here it is a no-op. + /// The cleanup strategy which can be used to destroy the entries of + /// the container. CLEANUP_STRATEGY_BASE *cleanup_strategy_; - // The cleanup strategy which can be used to destroy the entries of - // the container. + /// Whether the cleanup_strategy should be destroyed or not. int delete_cleanup_strategy_; - // Whether the cleanup_strategy should be destroyed or not. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/Capabilities.h b/ace/Capabilities.h index 83510eb9810..03fc25242e6 100644 --- a/ace/Capabilities.h +++ b/ace/Capabilities.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Capabilities.h -// -// = AUTHOR -// Arturo Montes <mitosys@colomsat.net.co> -// -// ============================================================================ + +//============================================================================= +/** + * @file Capabilities.h + * + * $Id$ + * + * @author Arturo Montes <mitosys@colomsat.net.co> + */ +//============================================================================= + #ifndef ACE_CAPABILITIES_H #define ACE_CAPABILITIES_H @@ -28,16 +25,18 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_CapEntry + * + * @brief This class is the base class for all ACE Capabilities entry + * subclasses. + * + * This class is not instantiable and does not provide accessors + * or methods. If you want to add a new kind of attribute you + * subclasses of this class and dynamic cast to proper subclass. + */ class ACE_Export ACE_CapEntry { - // = TITLE - // This class is the base class for all ACE Capabilities entry - // subclasses. - // - // = DESCRIPTION - // This class is not instantiable and does not provide accessors - // or methods. If you want to add a new kind of attribute you - // subclasses of this class and dynamic cast to proper subclass. public: virtual ~ACE_CapEntry (void); @@ -54,14 +53,16 @@ protected: int captype_; }; +/** + * @class ACE_IntCapEntry + * + * @brief This class implement the ACE Integer Capability subclass. + * + * This is a container class for ACE Capabilities integer container + * values. + */ class ACE_Export ACE_IntCapEntry : public ACE_CapEntry { - // = TITLE - // This class implement the ACE Integer Capability subclass. - // - // = DESCRIPTION - // This is a container class for ACE Capabilities integer container - // values. public: ACE_IntCapEntry (int val); int getval (void) const; @@ -70,14 +71,16 @@ protected: int val_; }; +/** + * @class ACE_StringCapEntry + * + * @brief This class implement the ACE String Capability subclass. + * + * This is a container class for ACE Capabilities String container + * values. + */ class ACE_Export ACE_StringCapEntry : public ACE_CapEntry { - // = TITLE - // This class implement the ACE String Capability subclass. - // - // = DESCRIPTION - // This is a container class for ACE Capabilities String container - // values. public: ACE_StringCapEntry (const ACE_TString &val); ACE_TString getval (void) const; @@ -86,14 +89,16 @@ protected: ACE_TString val_; }; +/** + * @class ACE_BoolCapEntry + * + * @brief This class implement the ACE Bool Capability subclass. + * + * This is a container class for ACE Capabilities bool container + * values. + */ class ACE_Export ACE_BoolCapEntry : public ACE_CapEntry { - // = TITLE - // This class implement the ACE Bool Capability subclass. - // - // = DESCRIPTION - // This is a container class for ACE Capabilities bool container - // values. public: ACE_BoolCapEntry (int val); int getval (void) const; @@ -102,66 +107,68 @@ protected: int val_; }; +/** + * @class ACE_Capabilities + * + * @brief This class implement the ACE Capabilities. + * + * This is a container class for ACE Capabilities + * values. Currently exist three different capability values: + * <ACE_IntCapEntry> (integer), <ACE_BoolCapEntry> (bool) and + * <ACE_StringCapEntry> (String). An <ACE_Capabilities> is a + * unordered set of pair = (<String>, <ACE_CapEntry> *). Where + * the first component is the name of capability and the second + * component is a pointer to the capability value container. A + * <FILE> is a container for <ACE_Capabilities>, the + * <ACE_Capabilities> has a name in the file, as a termcap file. + */ class ACE_Export ACE_Capabilities { - // = TITLE - // This class implement the ACE Capabilities. - // - // = DESCRIPTION - // This is a container class for ACE Capabilities - // values. Currently exist three different capability values: - // <ACE_IntCapEntry> (integer), <ACE_BoolCapEntry> (bool) and - // <ACE_StringCapEntry> (String). An <ACE_Capabilities> is a - // unordered set of pair = (<String>, <ACE_CapEntry> *). Where - // the first component is the name of capability and the second - // component is a pointer to the capability value container. A - // <FILE> is a container for <ACE_Capabilities>, the - // <ACE_Capabilities> has a name in the file, as a termcap file. public: + /// The Constructor ACE_Capabilities (void); - // The Constructor + /// The Destructor ~ACE_Capabilities(void); - // The Destructor public: + /// Get a string entry. int getval (const ACE_TCHAR *ent, ACE_TString &val); - // Get a string entry. + /// Get an integer entry. int getval (const ACE_TCHAR *ent, int &val); - // Get an integer entry. + /// Get the ACE_Capabilities name from FILE fname and load the + /// associated capabitily entries in map. int getent (const ACE_TCHAR *fname, const ACE_TCHAR *name); - // Get the ACE_Capabilities name from FILE fname and load the - // associated capabitily entries in map. protected: // Parse an integer property + /// Parse a string property const ACE_TCHAR *parse (const ACE_TCHAR *buf, int &cap); - // Parse a string property + /// Fill the ACE_Capabilities with description in ent. const ACE_TCHAR *parse (const ACE_TCHAR *buf, ACE_TString &cap); - // Fill the ACE_Capabilities with description in ent. + /// Parse a cap entry int fillent(const ACE_TCHAR *ent); - // Parse a cap entry + /// Get a line from FILE input stream int parseent (const ACE_TCHAR *name, ACE_TCHAR *line); - // Get a line from FILE input stream + /// Is a valid entry int getline (FILE* fp, ACE_TString &line); - // Is a valid entry + /// Reset the set of capabilities int is_entry (const ACE_TCHAR *name, const ACE_TCHAR *line); - // Reset the set of capabilities + /// Atributes. void resetcaps (void); - // Atributes. private: + /// This is the set of ACE_CapEntry. ACE_Hash_Map_Manager<ACE_TString, ACE_CapEntry *, ACE_Null_Mutex> caps_; - // This is the set of ACE_CapEntry. }; #if defined (ACE_IS_SPLITTING) diff --git a/ace/Cleanup_Strategies_T.h b/ace/Cleanup_Strategies_T.h index 1dd43239e27..337e30bd9fe 100644 --- a/ace/Cleanup_Strategies_T.h +++ b/ace/Cleanup_Strategies_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Cleanup_Strategies_T.h -// -// = AUTHOR -// Kirthika Parameswaran <kirthika@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Cleanup_Strategies_T.h + * + * $Id$ + * + * @author Kirthika Parameswaran <kirthika@cs.wustl.edu> + */ +//============================================================================= + #ifndef CLEANUP_STRATEGIES_H #define CLEANUP_STRATEGIES_H @@ -27,106 +24,116 @@ // For linkers that cant grok long names. #define ACE_Cleanup_Strategy ACLE +/** + * @class ACE_Cleanup_Strategy + * + * @brief Defines a default strategy to be followed for cleaning up + * entries from a map which is the container. + * + * By default the entry to be cleaned up is removed from the + * container. + */ template <class KEY, class VALUE, class CONTAINER> class ACE_Cleanup_Strategy { - // = TITLE - // Defines a default strategy to be followed for cleaning up - // entries from a map which is the container. - // - // = DESCRIPTION - // By default the entry to be cleaned up is removed from the - // container. public: + /// The method which will do the cleanup of the entry in the container. virtual int cleanup (CONTAINER &container, KEY *key, VALUE *value); - // The method which will do the cleanup of the entry in the container. }; ////////////////////////////////////////////////////////////////////// #define ACE_Recyclable_Handler_Cleanup_Strategy ARHCLE +/** + * @class ACE_Recyclable_Handler_Cleanup_Strategy + * + * @brief Defines a strategy to be followed for cleaning up + * entries which are svc_handlers from a container. + * + * The entry to be cleaned up is removed from the container. + * Here, since we are dealing with svc_handlers specifically, we + * perform a couple of extra operations. Note: To be used when + * the handler is recyclable. + */ template <class KEY, class VALUE, class CONTAINER> class ACE_Recyclable_Handler_Cleanup_Strategy : public ACE_Cleanup_Strategy<KEY, VALUE, CONTAINER> { - // = TITLE - // Defines a strategy to be followed for cleaning up - // entries which are svc_handlers from a container. - // - // = DESCRIPTION - // The entry to be cleaned up is removed from the container. - // Here, since we are dealing with svc_handlers specifically, we - // perform a couple of extra operations. Note: To be used when - // the handler is recyclable. public: + /// The method which will do the cleanup of the entry in the container. virtual int cleanup (CONTAINER &container, KEY *key, VALUE *value); - // The method which will do the cleanup of the entry in the container. }; ////////////////////////////////////////////////////////////////////// #define ACE_Refcounted_Recyclable_Handler_Cleanup_Strategy ARRHCLE +/** + * @class ACE_Refcounted_Recyclable_Handler_Cleanup_Strategy + * + * @brief Defines a strategy to be followed for cleaning up + * entries which are svc_handlers from a container. + * + * The entry to be cleaned up is removed from the container. + * Here, since we are dealing with recyclable svc_handlers with + * addresses which are refcountable specifically, we perform a + * couple of extra operations and do so without any locking. + */ template <class KEY, class VALUE, class CONTAINER> class ACE_Refcounted_Recyclable_Handler_Cleanup_Strategy : public ACE_Cleanup_Strategy<KEY, VALUE, CONTAINER> { - // = TITLE - // Defines a strategy to be followed for cleaning up - // entries which are svc_handlers from a container. - // - // = DESCRIPTION - // The entry to be cleaned up is removed from the container. - // Here, since we are dealing with recyclable svc_handlers with - // addresses which are refcountable specifically, we perform a - // couple of extra operations and do so without any locking. public: + /// The method which will do the cleanup of the entry in the container. virtual int cleanup (CONTAINER &container, KEY *key, VALUE *value); - // The method which will do the cleanup of the entry in the container. }; ////////////////////////////////////////////////////////////////////// +/** + * @class ACE_Handler_Cleanup_Strategy + * + * @brief Defines a strategy to be followed for cleaning up + * entries which are svc_handlers from a container. + * + * The entry to be cleaned up is removed from the container. + * Here, since we are dealing with svc_handlers specifically, we + * perform a couple of extra operations. Note: This cleanup strategy + * should be used in the case when the handler has the caching + * attributes. + */ template <class KEY, class VALUE, class CONTAINER> class ACE_Handler_Cleanup_Strategy : public ACE_Cleanup_Strategy<KEY, VALUE, CONTAINER> { - // = TITLE - // Defines a strategy to be followed for cleaning up - // entries which are svc_handlers from a container. - // - // = DESCRIPTION - // The entry to be cleaned up is removed from the container. - // Here, since we are dealing with svc_handlers specifically, we - // perform a couple of extra operations. Note: This cleanup strategy - // should be used in the case when the handler has the caching - // attributes. public: + /// The method which will do the cleanup of the entry in the container. virtual int cleanup (CONTAINER &container, KEY *key, VALUE *value); - // The method which will do the cleanup of the entry in the container. }; ////////////////////////////////////////////////////////////////////// #define ACE_Null_Cleanup_Strategy ANCLE +/** + * @class ACE_Null_Cleanup_Strategy + * + * @brief Defines a do-nothing implementation of the cleanup strategy. + * + * This class simply does nothing at all! Can be used to nullify + * the effect of the Cleanup Strategy. + */ template <class KEY, class VALUE, class CONTAINER> class ACE_Null_Cleanup_Strategy : public ACE_Cleanup_Strategy<KEY, VALUE, CONTAINER> { - // = TITLE - // Defines a do-nothing implementation of the cleanup strategy. - // - // = DESCRIPTION - // This class simply does nothing at all! Can be used to nullify - // the effect of the Cleanup Strategy. public: + /// The dummy cleanup method. virtual int cleanup (CONTAINER &container, KEY *key, VALUE *value); - // The dummy cleanup method. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/Codeset_IBM1047.h b/ace/Codeset_IBM1047.h index abb40517eb1..4be02944c3f 100644 --- a/ace/Codeset_IBM1047.h +++ b/ace/Codeset_IBM1047.h @@ -1,22 +1,19 @@ // -*- C++ -*- -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Codeset_IBM1047.cpp -// -// = DESCRIPTION -// Declares the arrays required to convert between ISO8859 (aka -// Latin/1) and IBM1047 (aka EBCDIC). -// -// = AUTHOR -// Jim Rogers (jrogers@viasoft.com) -// -// ============================================================================ + +//============================================================================= +/** + * @file Codeset_IBM1047.cpp + * + * $Id$ + * + * Declares the arrays required to convert between ISO8859 (aka + * Latin/1) and IBM1047 (aka EBCDIC). + * + * + * @author Jim Rogers (jrogers@viasoft.com) + */ +//============================================================================= + #ifndef ACE_CODESET_IMB1047_H #define ACE_CODESET_IMB1047_H @@ -37,23 +34,23 @@ extern ACE_Export char ACE_from_IBM1047[257]; // **************************************************************** +/** + * @class ACE_IBM1047_ISO8859 + * + * @brief Codeset translation specialization. + * + * This class performs the codeset translation: + * - Native: IBM_1047 (i.e. EBCDIC) + * - Stream: ISO-8859 (i.e. Latin/1) + */ class ACE_Export ACE_IBM1047_ISO8859 : public ACE_Char_Codeset_Translator { - // = TITLE - // Codeset translation specialization. - // - // = DESCRIPTION - // This class performs the codeset translation: - // - // Native: IBM_1047 (i.e. EBCDIC) - // Stream: ISO-8859 (i.e. Latin/1) - // public: + /// A do nothing constructor. ACE_IBM1047_ISO8859 (void); - // A do nothing constructor. + /// Virtual destruction virtual ~ACE_IBM1047_ISO8859 (void); - // Virtual destruction // = Documented in $ACE_ROOT/ace/CDR_Stream.h virtual ACE_CDR::Boolean read_char (ACE_InputCDR &, @@ -73,23 +70,23 @@ public: ACE_CDR::ULong); }; +/** + * @class ACE_ISO8859_IBM1047 + * + * @brief Codeset translation specialization. + * + * This class performs the codeset translation: + * - Native: ISO-8859 (i.e. Latin/1) + * - Stream: IBM-1047 (i.e. EBCDIC) + */ class ACE_Export ACE_ISO8859_IBM1047 : public ACE_Char_Codeset_Translator { - // = TITLE - // Codeset translation specialization. - // - // = DESCRIPTION - // This class performs the codeset translation: - // - // Native: ISO-8859 (i.e. Latin/1) - // Stream: IBM-1047 (i.e. EBCDIC) - // public: + /// A do nothing constructor. ACE_ISO8859_IBM1047 (void); - // A do nothing constructor. + /// Virtual destruction virtual ~ACE_ISO8859_IBM1047 (void); - // Virtual destruction // = Documented in $ACE_ROOT/ace/CDR_Stream.h virtual ACE_CDR::Boolean read_char (ACE_InputCDR &, diff --git a/ace/Configuration.h b/ace/Configuration.h index 29bb206b86a..0a6702901ea 100644 --- a/ace/Configuration.h +++ b/ace/Configuration.h @@ -1,33 +1,22 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Configuration.h -// -// = AUTHOR -// Chris Hafey <chris@stentorsoft.com> -// -// = DESCRIPTION -// The ACE configuration API provides a portable abstraction for -// program configuration. The API supports a tree based hierarchy -// of configuration sections. Each section contains other sections -// or values. Values may contain string, unsigned integer and -// binary data. -// -// = TODO -// - Add locking for thread safety. -// - Need to investigate what happens if memory mapped file gets mapped to -// a location different than it was created with. -// - Add dynamic buffer when importing. currently it will not allow -// importing of values greater than a fixed ammount (4096 bytes) -// - Replace unsigned int with a type that is fixed accross platforms. -// -// ============================================================================ + +//============================================================================= +/** + * @file Configuration.h + * + * $Id$ + * + * @author Chris Hafey <chris@stentorsoft.com> + * + * The ACE configuration API provides a portable abstraction for + * program configuration. The API supports a tree based hierarchy + * of configuration sections. Each section contains other sections + * or values. Values may contain string, unsigned integer and + * binary data. + * + */ +//============================================================================= + #ifndef ACE_CONFIGURATION_H #define ACE_CONFIGURATION_H @@ -52,24 +41,35 @@ #define ACE_DEFAULT_CONFIG_SECTION_SIZE 16 #endif /* ACE_DEFAULT_CONFIG_SECTION_SIZE */ +/** + * @class ACE_Section_Key_Internal + * + * @brief A base class for internal handles to section keys for + * configuration implementations + * + * Implementations subclass this base class to represent a + * section key. + * + * @todo + * - Add locking for thread safety. + * - Need to investigate what happens if memory mapped file gets mapped to + * a location different than it was created with. + * - Add dynamic buffer when importing. currently it will not allow + * importing of values greater than a fixed ammount (4096 bytes) + * - Replace unsigned int with a type that is fixed accross platforms. + * + */ class ACE_Export ACE_Section_Key_Internal { - // = TITLE - // A base class for internal handles to section keys for - // configuration implementations - // - // = DESCRIPTION - // Implementations subclass this base class to represent a - // section key. public: + /// Virtual destructor, make sure descendants are virtual! virtual ~ACE_Section_Key_Internal (void); - // Virtual destructor, make sure descendants are virtual! + /// Increment reference count virtual int add_ref (void); - // Increment reference count + /// Decrement reference count. Will delete this if count gets to 0 virtual int dec_ref (void); - // Decrement reference count. Will delete this if count gets to 0 protected: ACE_Section_Key_Internal (void); ACE_Section_Key_Internal (const ACE_Section_Key_Internal& rhs); @@ -78,46 +78,51 @@ protected: u_int ref_count_; }; + /** + * @class ACE_Configuration_Section_Key + * + * @brief Referenced counted wrapper for <ACE_Section_Key_Internal>. + * + * Reference counted wrapper class for the abstract internal + * section key. A user gets one of these to represent a section + * in the configuration database. + */ class ACE_Export ACE_Configuration_Section_Key { - // = TITLE - // Referenced counted wrapper for <ACE_Section_Key_Internal>. - // - // = DESCRIPTION - // Reference counted wrapper class for the abstract internal - // section key. A user gets one of these to represent a section - // in the configuration database. friend class ACE_Configuration; public: + /// Default ctor ACE_Configuration_Section_Key (void); - // Default ctor + /// ctor based on a pointer to a concrete internal key, does an + /// add_ref on <key>. ACE_EXPLICIT ACE_Configuration_Section_Key (ACE_Section_Key_Internal *key); - // ctor based on a pointer to a concrete internal key, does an - // add_ref on <key>. + /// Copy ctor, does an add_ref on rhs.key_. ACE_Configuration_Section_Key (const ACE_Configuration_Section_Key &rhs); - // Copy ctor, does an add_ref on rhs.key_. + /// destructor, does a <dec_ref> on <key_>. ~ACE_Configuration_Section_Key (void); - // destructor, does a <dec_ref> on <key_>. + /// assignment operator, does a <dec_ref> on <key_> and <add_ref> to + /// <rhs.key_> ACE_Configuration_Section_Key & operator= (const ACE_Configuration_Section_Key &rhs); - // assignment operator, does a <dec_ref> on <key_> and <add_ref> to - // <rhs.key_> private: ACE_Section_Key_Internal *key_; }; +/** + * @class ACE_Configuration + * + * @brief Base class for configuration databases + * + * This class provides an interface for configuration databases. + */ class ACE_Export ACE_Configuration { - // = TITLE - // Base class for configuration databases - // - // = DESCRIPTION - // This class provides an interface for configuration databases. public: + /// Enumeration for the various types of values we can store. enum VALUETYPE { STRING, @@ -125,138 +130,151 @@ public: BINARY, INVALID }; - // Enumeration for the various types of values we can store. + /// destructor virtual ~ACE_Configuration (void); - // destructor + /// Returns the root section of this configuration. virtual const ACE_Configuration_Section_Key& root_section (void); - // Returns the root section of this configuration. + /** + * Finds a <sub_section> in <base> and places the resulting key in + * <result>. If create is non zero, the sub_section will be created + * if it doesn't exist + */ virtual int open_section (const ACE_Configuration_Section_Key &base, const ACE_TCHAR *sub_section, int create, ACE_Configuration_Section_Key& result) = 0; - // Finds a <sub_section> in <base> and places the resulting key in - // <result>. If create is non zero, the sub_section will be created - // if it doesn't exist + /// Removes the <sub_section> from <key>. If recursive is non zero, + /// any subkeys below <sub_section> are remove as well. virtual int remove_section (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *sub_section, int recursive) = 0; - // Removes the <sub_section> from <key>. If recursive is non zero, - // any subkeys below <sub_section> are remove as well. + /** + * method to enumerate through the <name> and <type> of values in a + * <key>. To begin iteration, <index> must be zero. to continue + * iteration, invoke enumerate_values again while incrementing + * index. Each iteration will return the <name> of the value and + * its <type>. This method returns 0 on success, <0 on error and 1 + * when there are no more values to iterate through. Note - you may + * not delete or add values while enumerating. If you need to do + * this, you start the enumeration over again. + */ virtual int enumerate_values (const ACE_Configuration_Section_Key& key, int index, ACE_TString& name, VALUETYPE& type) = 0; - // method to enumerate through the <name> and <type> of values in a - // <key>. To begin iteration, <index> must be zero. to continue - // iteration, invoke enumerate_values again while incrementing - // index. Each iteration will return the <name> of the value and - // its <type>. This method returns 0 on success, <0 on error and 1 - // when there are no more values to iterate through. Note - you may - // not delete or add values while enumerating. If you need to do - // this, you start the enumeration over again. + /** + * method to enumerate through the <name> subsections in <key>. To + * begin iteration, <index> must zero. to continue iteration, invoke + * enumerate_sections again while incrementing index. Each + * iteration will return the <name> of the sub section. This method + * returns 0 on success, <0 on error and 1 when there are no more + * subsections to iterate through. Note - you may not delete or add + * values while enumerating. If you need to do this, you start the + * enumeration over again. + */ virtual int enumerate_sections (const ACE_Configuration_Section_Key& key, int index, ACE_TString& name) = 0; - // method to enumerate through the <name> subsections in <key>. To - // begin iteration, <index> must zero. to continue iteration, invoke - // enumerate_sections again while incrementing index. Each - // iteration will return the <name> of the sub section. This method - // returns 0 on success, <0 on error and 1 when there are no more - // subsections to iterate through. Note - you may not delete or add - // values while enumerating. If you need to do this, you start the - // enumeration over again. + /// sets the value in <key> with <name> to a string of <value> virtual int set_string_value (const ACE_Configuration_Section_Key& key, const ACE_TCHAR* name, const ACE_TString& value) = 0; - // sets the value in <key> with <name> to a string of <value> + /// sets the value in <key> with <name> to an integer of <value> virtual int set_integer_value (const ACE_Configuration_Section_Key& key, const ACE_TCHAR* name, u_int value) = 0; - // sets the value in <key> with <name> to an integer of <value> + /// sets the value in <key> with <name> to binary data of <data> with + /// <length>. virtual int set_binary_value (const ACE_Configuration_Section_Key& key, const ACE_TCHAR* name, const void* data, u_int length) = 0; - // sets the value in <key> with <name> to binary data of <data> with - // <length>. + /// gets the string value of <name> from <key> and places it in + /// <value>. Returns non zero on error (if value is not a string). virtual int get_string_value (const ACE_Configuration_Section_Key& key, const ACE_TCHAR* name, ACE_TString& value) = 0; - // gets the string value of <name> from <key> and places it in - // <value>. Returns non zero on error (if value is not a string). + /// gets the integer value of <name> from <key> and places it in + /// <value>. Returns non zero on error (if value is not an integer). virtual int get_integer_value (const ACE_Configuration_Section_Key& key, const ACE_TCHAR* name, u_int& value) = 0; - // gets the integer value of <name> from <key> and places it in - // <value>. Returns non zero on error (if value is not an integer). + /** + * gets the binary value of <name> from <key> and places a copy in + * <data> and sets <length> to the length of the data. caller is + * responsible for deleting <data>. Returns non zero on error (if + * value is not binary). + */ virtual int get_binary_value (const ACE_Configuration_Section_Key& key, const ACE_TCHAR* name, void*& data, u_int& length) = 0; - // gets the binary value of <name> from <key> and places a copy in - // <data> and sets <length> to the length of the data. caller is - // responsible for deleting <data>. Returns non zero on error (if - // value is not binary). + /** + * checks to see if an entry of <name> is in <key> and places the + * data type in <type>. Returns 0 on success (entry is found), + * -1 on error + */ virtual int find_value(const ACE_Configuration_Section_Key& key, const ACE_TCHAR* name, VALUETYPE& type) = 0; - // checks to see if an entry of <name> is in <key> and places the - // data type in <type>. Returns 0 on success (entry is found), - // -1 on error + /// Removes the the value <name> from <key>. returns non zero on + /// error. virtual int remove_value (const ACE_Configuration_Section_Key& key, const ACE_TCHAR* name) = 0; - // Removes the the value <name> from <key>. returns non zero on - // error. + /** + * Expands <path_in> to <key_out> from <key>. If create is true, + * the subsections are created. Returns 0 on success, non zero on + * error The path consists of sections separated by the backslash + * '\'. + */ int expand_path (const ACE_Configuration_Section_Key& key, const ACE_TString& path_in, ACE_Configuration_Section_Key& key_out, int create = 1); - // Expands <path_in> to <key_out> from <key>. If create is true, - // the subsections are created. Returns 0 on success, non zero on - // error The path consists of sections separated by the backslash - // '\'. + /// Exports the configuration database to filename. If <filename> is + /// alredy present, it is overwritten. virtual int export_config (const ACE_TCHAR* filename); - // Exports the configuration database to filename. If <filename> is - // alredy present, it is overwritten. + /// Imports the configuration database from filename. Any existing + /// data is not removed. virtual int import_config (const ACE_TCHAR* filename); - // Imports the configuration database from filename. Any existing - // data is not removed. protected: + /// Default ctor ACE_Configuration (void); - // Default ctor + /// resolves the internal key from a section key ACE_Section_Key_Internal* get_internal_key (const ACE_Configuration_Section_Key& key); - // resolves the internal key from a section key + /** + * tests to see if <name> is valid. <name> must be < 255 characters + * and not contain the path separator '\', brackets [] or = (maybe + * just restrict to alphanumeric?) returns non zero if name is not + * valid + */ int validate_name (const ACE_TCHAR* name); - // tests to see if <name> is valid. <name> must be < 255 characters - // and not contain the path separator '\', brackets [] or = (maybe - // just restrict to alphanumeric?) returns non zero if name is not - // valid + /// Used when exporting a configuration to a file int export_section (const ACE_Configuration_Section_Key& section, const ACE_TString& path, FILE* out); - // Used when exporting a configuration to a file // Not used ACE_Configuration (const ACE_Configuration& rhs); @@ -266,46 +284,52 @@ protected: #if defined (ACE_WIN32) +/** + * @class ACE_Section_Key_Win32 + * + * @brief The Win32 registry implementation of an internal section key. + * + * Holds the HKEY for a section (registry key). + */ class ACE_Export ACE_Section_Key_Win32 : public ACE_Section_Key_Internal { - // = TITLE - // The Win32 registry implementation of an internal section key. - // - // = DESCRIPTION - // Holds the HKEY for a section (registry key). public: + /// constructor based on an HKEY ACE_Section_Key_Win32 (HKEY hKey); - // constructor based on an HKEY HKEY hKey_; protected: + /// destructor - invokes <RegCloseKey> virtual ~ACE_Section_Key_Win32 (void); - // destructor - invokes <RegCloseKey> // Not used ACE_Section_Key_Win32 (const ACE_Section_Key_Win32& rhs); ACE_Section_Key_Win32& operator= (const ACE_Section_Key_Win32& rhs); }; +/** + * @class ACE_Configuration_Win32Registry + * + * @brief The win32 registry implementation of a configuration database + * + * The win32 implementation basically makes calls through to the + * registry functions. The API is very similar so very little + * work must be done + */ class ACE_Export ACE_Configuration_Win32Registry : public ACE_Configuration { - // = TITLE - // The win32 registry implementation of a configuration database - // - // = DESCRIPTION - // The win32 implementation basically makes calls through to the - // registry functions. The API is very similar so very little - // work must be done public: + /** + * constructor for registry configuration database. hKey is the + * base registry key to attach to. This class takes ownership of + * hKey, it will invoke <RegCloseKey> on it upon destruction. + */ ACE_EXPLICIT ACE_Configuration_Win32Registry (HKEY hKey); - // constructor for registry configuration database. hKey is the - // base registry key to attach to. This class takes ownership of - // hKey, it will invoke <RegCloseKey> on it upon destruction. + /// destructor virtual ~ACE_Configuration_Win32Registry (void); - // destructor virtual int open_section (const ACE_Configuration_Section_Key& base, const ACE_TCHAR* sub_section, @@ -355,24 +379,26 @@ public: const ACE_TCHAR* name, VALUETYPE& type); + /// Removes the the value <name> from <key>. returns non zero on error virtual int remove_value (const ACE_Configuration_Section_Key& key, const ACE_TCHAR* name); - // Removes the the value <name> from <key>. returns non zero on error + /** + * This method traverses <path> through <hKey>. It is useful when + * you want the HKEY for a specific registry key, especially when + * initializing this implementation. Caller is responsible for + * closeing this key when it is no longer used. If create is 1 + * (default) the keys are create if they don't already exist. + * Returns 0 on error + */ static HKEY resolve_key (HKEY hKey, const ACE_TCHAR* path, int create = 1); - // This method traverses <path> through <hKey>. It is useful when - // you want the HKEY for a specific registry key, especially when - // initializing this implementation. Caller is responsible for - // closeing this key when it is no longer used. If create is 1 - // (default) the keys are create if they don't already exist. - // Returns 0 on error protected: + /// Gets the HKEY for a configuration section int load_key (const ACE_Configuration_Section_Key& key, HKEY& hKey); - // Gets the HKEY for a configuration section // Not used ACE_Configuration_Win32Registry (void); @@ -390,42 +416,44 @@ typedef ACE_Allocator_Adapter <ACE_Malloc <ACE_LOCAL_MEMORY_POOL, ACE_SYNCH_MUTEX> > HEAP_ALLOCATOR; +/** + * @class ACE_Configuration_ExtId + * + * @brief External ID for the section and value hash + * + * Contains a pointer to the section or value name. + */ class ACE_Export ACE_Configuration_ExtId { - // = TITLE - // External ID for the section and value hash - // - // = DESCRIPTION - // Contains a pointer to the section or value name. public: + /// defeault ctor ACE_Configuration_ExtId (void); - // defeault ctor + /// named constructor ACE_EXPLICIT ACE_Configuration_ExtId (const ACE_TCHAR* name); - // named constructor + /// copy ctor ACE_Configuration_ExtId (const ACE_Configuration_ExtId& rhs); - // copy ctor + /// destructor ~ACE_Configuration_ExtId (void); - // destructor + /// assignment operator ACE_Configuration_ExtId& operator= (const ACE_Configuration_ExtId& rhs); - // assignment operator + /// Equality comparison operator (must match name_). int operator== (const ACE_Configuration_ExtId &rhs) const; - // Equality comparison operator (must match name_). + /// Inequality comparison operator. int operator!= (const ACE_Configuration_ExtId &rhs) const; - // Inequality comparison operator. + /// Frees the name of the value. needed since we don't know the + /// allocator name_ was created in void free (ACE_Allocator* allocator); - // Frees the name of the value. needed since we don't know the - // allocator name_ was created in + /// <hash> function is required in order for this class to be usable by + /// ACE_Hash_Map_Manager. u_long hash (void) const; - // <hash> function is required in order for this class to be usable by - // ACE_Hash_Map_Manager. // = Data members. @@ -446,48 +474,52 @@ typedef ACE_Hash_Map_Manager_Ex<ACE_Configuration_ExtId, typedef ACE_Hash_Map_Entry<ACE_Configuration_ExtId, int> SUBSECTION_ENTRY; +/** + * @class ACE_Configuration_Value_IntId + * + * @brief The section hash table internal value class + * + * This class is present as the internal portion of a section's + * value hash table It may store string, integer or binary data. + */ class ACE_Export ACE_Configuration_Value_IntId { - // = TITLE - // The section hash table internal value class - // - // = DESCRIPTION - // This class is present as the internal portion of a section's - // value hash table It may store string, integer or binary data. public: + /// default constructor ACE_Configuration_Value_IntId (void); - // default constructor + /// string constructor, takes ownership of string ACE_EXPLICIT ACE_Configuration_Value_IntId (ACE_TCHAR* string); - // string constructor, takes ownership of string + /// integer constructor ACE_EXPLICIT ACE_Configuration_Value_IntId (u_int integer); - // integer constructor + /// binary constructor, takes ownership of data ACE_Configuration_Value_IntId (void* data, u_int length); - // binary constructor, takes ownership of data + /// copy ctor ACE_Configuration_Value_IntId (const ACE_Configuration_Value_IntId& rhs); - // copy ctor + /// destructor ~ACE_Configuration_Value_IntId (void); - // destructor + /// Assignment operator ACE_Configuration_Value_IntId& operator= ( const ACE_Configuration_Value_IntId& rhs); - // Assignment operator void free (ACE_Allocator* allocator); // = Data members. + /** + * points to the string value or binary data or IS the integer + * (XXX need to change this since sizeof (u_int) is + * not the same accross different platforms) + * Length is only used when type_ == BINARY + */ ACE_Configuration::VALUETYPE type_; void* data_; - // points to the string value or binary data or IS the integer - // (XXX need to change this since sizeof (u_int) is - // not the same accross different platforms) u_int length_; - // Length is only used when type_ == BINARY }; typedef ACE_Hash_Map_With_Allocator<ACE_Configuration_ExtId, @@ -503,33 +535,35 @@ typedef ACE_Hash_Map_Entry<ACE_Configuration_ExtId, ACE_Configuration_Value_IntId> VALUE_ENTRY; +/** + * @class ACE_Configuration_Section_IntId + * + * @brief The internal ID for a section hash table + * + * Contains a hash table containing value name/values + */ class ACE_Export ACE_Configuration_Section_IntId { - // = TITLE - // The internal ID for a section hash table - // - // = DESCRIPTION - // Contains a hash table containing value name/values public: + /// default ctor ACE_Configuration_Section_IntId (void); - // default ctor + /// named ctor ACE_EXPLICIT ACE_Configuration_Section_IntId (VALUE_MAP* value_hash_map, SUBSECTION_MAP* section_hash_map); - // named ctor + /// copy ctor ACE_Configuration_Section_IntId (const ACE_Configuration_Section_IntId& rhs); - // copy ctor + /// destructor ~ACE_Configuration_Section_IntId (void); - // destructor + /// asignment operator ACE_Configuration_Section_IntId& operator= ( const ACE_Configuration_Section_IntId& rhs); - // asignment operator + /// frees the hash table and all its values void free (ACE_Allocator* allocator); - // frees the hash table and all its values // = Data Members. VALUE_MAP* value_hash_map_; @@ -549,61 +583,65 @@ typedef ACE_Hash_Map_Entry<ACE_Configuration_ExtId, ACE_Configuration_Section_IntId> SECTION_ENTRY; +/** + * @class ACE_Configuration_Section_Key_Heap + * + * @brief Internal section key class for heap based configuration + * database. + * + * Contains a value iterator and full path name of section. + */ class ACE_Export ACE_Configuration_Section_Key_Heap : public ACE_Section_Key_Internal { - // = TITLE - // Internal section key class for heap based configuration - // database. - // - // = DESCRIPTION - // Contains a value iterator and full path name of section. public: + /// constructor based on the full path of the section ACE_Configuration_Section_Key_Heap (const ACE_TCHAR* path); - // constructor based on the full path of the section + ///the path itself ACE_TCHAR* path_; - //the path itself + /// The value iterator VALUE_HASH::ITERATOR* value_iter_; - // The value iterator + /// The sub section iterator SUBSECTION_HASH::ITERATOR* section_iter_; - // The sub section iterator protected: + /// destructor - will delete the iterators virtual ~ACE_Configuration_Section_Key_Heap (void); - // destructor - will delete the iterators // Not used ACE_Configuration_Section_Key_Heap (const ACE_Configuration_Section_Key_Heap& rhs); ACE_Configuration_Section_Key_Heap& operator= (const ACE_Configuration_Section_Key_Heap& rhs); }; +/** + * @class ACE_Configuration_Heap + * + * @brief The concrete implementation of a allocator based + * configuration database + * + * This class uses ACE's Allocators to manage a memory + * representation of a configuraiton database. A persistent heap + * may be used to store configurations persistently + */ class ACE_Export ACE_Configuration_Heap : public ACE_Configuration { - // = TITLE - // The concrete implementation of a allocator based - // configuration database - // - // = DESCRIPTION - // This class uses ACE's Allocators to manage a memory - // representation of a configuraiton database. A persistent heap - // may be used to store configurations persistently public: + /// Default ctor ACE_Configuration_Heap (void); - // Default ctor + /// destructor virtual ~ACE_Configuration_Heap (void); - // destructor + /// opens a configuration based on a file name int open (const ACE_TCHAR* file_name, void* base_address = ACE_DEFAULT_BASE_ADDR, int default_map_size = ACE_DEFAULT_CONFIG_SECTION_SIZE); - // opens a configuration based on a file name + /// opens a heap based configuration int open (int default_map_size = ACE_DEFAULT_CONFIG_SECTION_SIZE); - // opens a heap based configuration virtual int open_section (const ACE_Configuration_Section_Key& base, const ACE_TCHAR* sub_section, @@ -652,22 +690,22 @@ public: const ACE_TCHAR* name, VALUETYPE& type); + /// Removes the the value <name> from <key>. returns non zero on error virtual int remove_value (const ACE_Configuration_Section_Key& key, const ACE_TCHAR* name); - // Removes the the value <name> from <key>. returns non zero on error private: + /// adds a new section int add_section (const ACE_Configuration_Section_Key& base, const ACE_TCHAR* sub_section, ACE_Configuration_Section_Key& result); - // adds a new section + /// Helper for the <open> method. int create_index (void); - // Helper for the <open> method. + /// Helper for <create_index> method: places hash table into an + /// allocated space. int create_index_helper (void *buffer); - // Helper for <create_index> method: places hash table into an - // allocated space. int value_open_helper (size_t hash_table_size, void *buffer); diff --git a/ace/Connector.h b/ace/Connector.h index acac1b5cb1c..e09c7e52208 100644 --- a/ace/Connector.h +++ b/ace/Connector.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Connector.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Connector.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_CONNECTOR_H #define ACE_CONNECTOR_H @@ -29,15 +26,17 @@ #include "ace/Svc_Handler.h" #include "ace/Strategies.h" +/** + * @class ACE_Svc_Tuple + * + * @brief Holds the ACE_Svc_Handler and its argument and + * <ACE_Timer_Handle> until an asynchronous connection completes. + * + * This is a no-brainer... + */ template <class SVC_HANDLER> class ACE_Svc_Tuple { - // = TITLE - // Holds the ACE_Svc_Handler and its argument and - // <ACE_Timer_Handle> until an asynchronous connection completes. - // - // = DESCRIPTION - // This is a no-brainer... public: // = Initialization methods. ACE_Svc_Tuple (SVC_HANDLER *, @@ -49,64 +48,66 @@ public: SVC_HANDLER *svc_handler (void); // = Get/set handle. + /// Get handle. + /// Set handle. ACE_HANDLE handle (void); - // Get handle. void handle (ACE_HANDLE); - // Set handle. // = Get/set argument. + /// Get argument. + /// Set argument. const void *arg (void); - // Get argument. void arg (const void *); - // Set argument. // = Set/get timer cancellation handle. + /// Get cancellation id. + /// Set cancellation id. long cancellation_id (void); - // Get cancellation id. void cancellation_id (long timer_id); - // Set cancellation id. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Associated SVC_HANDLER. SVC_HANDLER *svc_handler_; - // Associated SVC_HANDLER. + /// IPC <HANDLE> that we are trying to connect. ACE_HANDLE handle_; - // IPC <HANDLE> that we are trying to connect. + /// Associated argument. const void *arg_; - // Associated argument. + /// Associated cancellation id. long cancellation_id_; - // Associated cancellation id. }; +/** + * @class ACE_Connector + * + * @brief Generic factory for actively connecting clients and creating + * service handlers (SVC_HANDLERs). + * + * Implements the strategy for actively establishing connections + * with clients. An ACE_Connector is parameterized by concrete + * types that conform to the interfaces of PEER_CONNECTOR and + * SVC_HANDLER. The PEER_CONNECTOR is instantiated with a + * transport mechanism that passively establishes connections. + * The SVC_HANDLER is instantiated with a concrete type that + * performs the application-specific service. An ACE_Connector + * inherits from ACE_Service_Object, which in turn inherits from + * ACE_Event_Handler. This enables the ACE_Reactor to dispatch + * the ACE_Connector's handle_output method when connections + * complete asynchronously. The handle_output method performs + * the connector's active connection establishment and service + * activation strategy. + */ template <class SVC_HANDLER, ACE_PEER_CONNECTOR_1> class ACE_Connector : public ACE_Service_Object { - // = TITLE - // Generic factory for actively connecting clients and creating - // service handlers (SVC_HANDLERs). - // - // = DESCRIPTION - // Implements the strategy for actively establishing connections - // with clients. An ACE_Connector is parameterized by concrete - // types that conform to the interfaces of PEER_CONNECTOR and - // SVC_HANDLER. The PEER_CONNECTOR is instantiated with a - // transport mechanism that passively establishes connections. - // The SVC_HANDLER is instantiated with a concrete type that - // performs the application-specific service. An ACE_Connector - // inherits from ACE_Service_Object, which in turn inherits from - // ACE_Event_Handler. This enables the ACE_Reactor to dispatch - // the ACE_Connector's handle_output method when connections - // complete asynchronously. The handle_output method performs - // the connector's active connection establishment and service - // activation strategy. public: // = Initialization and termination methods. @@ -115,29 +116,44 @@ public: typedef ACE_PEER_CONNECTOR_ADDR ACE_PEER_ADDR_TYPEDEF; #endif /* ACE_HAS_TYPENAME_KEYWORD */ - typedef ACE_TYPENAME _ACE_PEER_CONNECTOR::PEER_ADDR + typedef ACE_TYPENAME _ACE_PEER_CONNECTOR::PEER_ADDR ACE_TYPENAME_ACE_PEER_CONNECTOR_PEER_ADDR; + /** + * Initialize a connector. <flags> indicates how <SVC_HANDLER>'s + * should be initialized prior to being activated. Right now, the + * only flag that is processed is <ACE_NONBLOCK>, which enabled + * non-blocking I/O on the <SVC_HANDLER> when it is opened. + */ ACE_Connector (ACE_Reactor *r = ACE_Reactor::instance (), int flags = 0); - // Initialize a connector. <flags> indicates how <SVC_HANDLER>'s - // should be initialized prior to being activated. Right now, the - // only flag that is processed is <ACE_NONBLOCK>, which enabled - // non-blocking I/O on the <SVC_HANDLER> when it is opened. + /** + * Initialize a connector. <flags> indicates how <SVC_HANDLER>'s + * should be initialized prior to being activated. Right now, the + * only flag that is processed is <ACE_NONBLOCK>, which enabled + * non-blocking I/O on the <SVC_HANDLER> when it is opened. + */ virtual int open (ACE_Reactor *r = ACE_Reactor::instance (), int flags = 0); - // Initialize a connector. <flags> indicates how <SVC_HANDLER>'s - // should be initialized prior to being activated. Right now, the - // only flag that is processed is <ACE_NONBLOCK>, which enabled - // non-blocking I/O on the <SVC_HANDLER> when it is opened. + /// Shutdown a connector and release resources. virtual ~ACE_Connector (void); - // Shutdown a connector and release resources. // = Connection establishment methods. + /** + * Initiate connection of <svc_handler> to peer at <remote_addr> + * using <synch_options>. If the caller wants to designate the + * selected <local_addr> they can (and can also insist that the + * <local_addr> be reused by passing a value <reuse_addr> == + * 1). <flags> and <perms> can be used to pass any flags that are + * needed to perform specific operations such as opening a file + * within connect with certain permissions. If the connection fails + * the <close> hook on the <svc_handler> will be called + * automatically to prevent resource leaks. + */ virtual int connect (SVC_HANDLER *&svc_handler, const ACE_PEER_CONNECTOR_ADDR &remote_addr, const ACE_Synch_Options &synch_options = ACE_Synch_Options::defaults, @@ -146,16 +162,17 @@ public: int reuse_addr = 0, int flags = O_RDWR, int perms = 0); - // Initiate connection of <svc_handler> to peer at <remote_addr> - // using <synch_options>. If the caller wants to designate the - // selected <local_addr> they can (and can also insist that the - // <local_addr> be reused by passing a value <reuse_addr> == - // 1). <flags> and <perms> can be used to pass any flags that are - // needed to perform specific operations such as opening a file - // within connect with certain permissions. If the connection fails - // the <close> hook on the <svc_handler> will be called - // automatically to prevent resource leaks. + /** + * This is a variation on the previous <connect> method. On cached + * connectors the <svc_handler_hint> variable can be used as a hint + * for future lookups. Since this variable is modified in the + * context of the internal cache its use is thread-safe. But the + * actual svc_handler for the current connection is returned in the + * second parameter <svc_handler>. If the connection fails the + * <close> hook on the <svc_handler> will be called automatically to + * prevent resource leaks. + */ virtual int connect (SVC_HANDLER *&svc_handler_hint, SVC_HANDLER *&svc_handler, const ACE_PEER_CONNECTOR_ADDR &remote_addr, @@ -165,42 +182,38 @@ public: int reuse_addr = 0, int flags = O_RDWR, int perms = 0); - // This is a variation on the previous <connect> method. On cached - // connectors the <svc_handler_hint> variable can be used as a hint - // for future lookups. Since this variable is modified in the - // context of the internal cache its use is thread-safe. But the - // actual svc_handler for the current connection is returned in the - // second parameter <svc_handler>. If the connection fails the - // <close> hook on the <svc_handler> will be called automatically to - // prevent resource leaks. + /** + * Initiate connection of <n> <svc_handlers> to peers at + * <remote_addrs> using <synch_options>. Returns -1 if failure + * occurs and 0 otherwise. If <failed_svc_handlers> is non-NULL, a + * 1 is placed in the corresponding index of <failed_svc_handler> + * for each <svc_handlers[i]> that failed to connect, else a 0 is + * placed in that index. + */ virtual int connect_n (size_t n, SVC_HANDLER *svc_handlers[], ACE_PEER_CONNECTOR_ADDR remote_addrs[], ACE_TCHAR *failed_svc_handlers = 0, const ACE_Synch_Options &synch_options = ACE_Synch_Options::defaults); - // Initiate connection of <n> <svc_handlers> to peers at - // <remote_addrs> using <synch_options>. Returns -1 if failure - // occurs and 0 otherwise. If <failed_svc_handlers> is non-NULL, a - // 1 is placed in the corresponding index of <failed_svc_handler> - // for each <svc_handlers[i]> that failed to connect, else a 0 is - // placed in that index. + /** + * Cancel a <svc_handler> that was started asynchronously. Note that + * this is the only case when the Connector does not actively close + * the <svc_handler>. It is left up to the caller of <cancel> to + * decide the fate of the <svc_handler>. + */ virtual int cancel (SVC_HANDLER *svc_handler); - // Cancel a <svc_handler> that was started asynchronously. Note that - // this is the only case when the Connector does not actively close - // the <svc_handler>. It is left up to the caller of <cancel> to - // decide the fate of the <svc_handler>. + /// Close down the Connector virtual int close (void); - // Close down the Connector + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Helpful typedefs. @@ -218,15 +231,22 @@ protected: // = The following two methods define the Connector's strategies for // creating, connecting, and activating SVC_HANDLER's, respectively. + /** + * Bridge method for creating a SVC_HANDLER. The default is to + * create a new SVC_HANDLER only if <sh> == 0, else <sh> is + * unchanged. However, subclasses can override this policy to + * perform SVC_HANDLER creation in any way that they like (such as + * creating subclass instances of SVC_HANDLER, using a singleton, + * dynamically linking the handler, etc.). Returns -1 if failure, + * else 0. + */ virtual int make_svc_handler (SVC_HANDLER *&sh); - // Bridge method for creating a SVC_HANDLER. The default is to - // create a new SVC_HANDLER only if <sh> == 0, else <sh> is - // unchanged. However, subclasses can override this policy to - // perform SVC_HANDLER creation in any way that they like (such as - // creating subclass instances of SVC_HANDLER, using a singleton, - // dynamically linking the handler, etc.). Returns -1 if failure, - // else 0. + /** + * Bridge method for connecting the <svc_handler> to the + * <remote_addr>. The default behavior delegates to the + * <PEER_CONNECTOR::connect>. + */ virtual int connect_svc_handler (SVC_HANDLER *&svc_handler, const ACE_PEER_CONNECTOR_ADDR &remote_addr, ACE_Time_Value *timeout, @@ -242,71 +262,73 @@ protected: int reuse_addr, int flags, int perms); - // Bridge method for connecting the <svc_handler> to the - // <remote_addr>. The default behavior delegates to the - // <PEER_CONNECTOR::connect>. + /** + * Bridge method for activating a <svc_handler> with the appropriate + * concurrency strategy. The default behavior of this method is to + * activate the SVC_HANDLER by calling its <open> method (which + * allows the SVC_HANDLER to define its own concurrency strategy). + * However, subclasses can override this strategy to do more + * sophisticated concurrency activations (such as creating the + * SVC_HANDLER as an "active object" via multi-threading or + * multi-processing). + */ virtual int activate_svc_handler (SVC_HANDLER *svc_handler); - // Bridge method for activating a <svc_handler> with the appropriate - // concurrency strategy. The default behavior of this method is to - // activate the SVC_HANDLER by calling its <open> method (which - // allows the SVC_HANDLER to define its own concurrency strategy). - // However, subclasses can override this strategy to do more - // sophisticated concurrency activations (such as creating the - // SVC_HANDLER as an "active object" via multi-threading or - // multi-processing). + /// Called by ACE_Reactor when asynchronous connections fail. virtual int handle_input (ACE_HANDLE); - // Called by ACE_Reactor when asynchronous connections fail. + /// Called by ACE_Reactor when asynchronous connections succeed. virtual int handle_output (ACE_HANDLE); - // Called by ACE_Reactor when asynchronous connections succeed. + /// Called by ACE_Reactor when asynchronous connections complete (on + /// some platforms only). virtual int handle_exception (ACE_HANDLE fd = ACE_INVALID_HANDLE); - // Called by ACE_Reactor when asynchronous connections complete (on - // some platforms only). // = Dynamic linking hooks. + /// Default version does no work and returns -1. Must be overloaded + /// by application developer to do anything meaningful. virtual int init (int argc, ACE_TCHAR *argv[]); - // Default version does no work and returns -1. Must be overloaded - // by application developer to do anything meaningful. + /// Calls <handle_close> to shutdown the Connector gracefully. virtual int fini (void); - // Calls <handle_close> to shutdown the Connector gracefully. + /// Default version returns address info in <buf>. virtual int info (ACE_TCHAR **, size_t) const; - // Default version returns address info in <buf>. // = Demultiplexing hooks. + /** + * Terminate the Client ACE_Connector by iterating over any + * unconnected ACE_Svc_Handler's and removing them from the + * ACE_Reactor. + */ virtual int handle_close (ACE_HANDLE = ACE_INVALID_HANDLE, ACE_Reactor_Mask = ACE_Event_Handler::ALL_EVENTS_MASK); - // Terminate the Client ACE_Connector by iterating over any - // unconnected ACE_Svc_Handler's and removing them from the - // ACE_Reactor. + /// This method is called if a connection times out before + /// completing. virtual int handle_timeout (const ACE_Time_Value &tv, const void *arg); - // This method is called if a connection times out before - // completing. // = Service management hooks. + /// Default version does no work and returns -1. Must be overloaded + /// by application developer to do anything meaningful. virtual int suspend (void); - // Default version does no work and returns -1. Must be overloaded - // by application developer to do anything meaningful. + /// Default version does no work and returns -1. Must be overloaded + /// by application developer to do anything meaningful. virtual int resume (void); - // Default version does no work and returns -1. Must be overloaded - // by application developer to do anything meaningful. + /// Creates and inserts an ACE_Svc_Tuple into the <handler_map_>. + /// so that we can continue accepting this connection asynchronously. int create_AST (SVC_HANDLER *, const ACE_Synch_Options &); - // Creates and inserts an ACE_Svc_Tuple into the <handler_map_>. - // so that we can continue accepting this connection asynchronously. + /// Cleanup the <handler_map_> and returns the appropriate + /// ACE_Svc_Tuple (which is 0 if there is no associated tuple). int cleanup_AST (ACE_HANDLE, AST *&); - // Cleanup the <handler_map_> and returns the appropriate - // ACE_Svc_Tuple (which is 0 if there is no associated tuple). + /// Implementation the <connect> methods. virtual int connect_i (SVC_HANDLER *&svc_handler, SVC_HANDLER **sh_copy, const ACE_PEER_CONNECTOR_ADDR &remote_addr, @@ -315,76 +337,85 @@ protected: int reuse_addr, int flags, int perms); - // Implementation the <connect> methods. + /// Lookup table that maps an I/O handle to a SVC_HANDLER *. MAP_MANAGER handler_map_; - // Lookup table that maps an I/O handle to a SVC_HANDLER *. private: + /// This is the concrete connector factory (it keeps no state so the + /// <ACE_Connector> is reentrant). ACE_PEER_CONNECTOR connector_; - // This is the concrete connector factory (it keeps no state so the - // <ACE_Connector> is reentrant). + /// Keeps track of whether we are in the process of closing (required + /// to avoid circular calls to <handle_close>). char closing_; - // Keeps track of whether we are in the process of closing (required - // to avoid circular calls to <handle_close>). + /** + * Flags that indicate how <SVC_HANDLER>'s should be initialized + * prior to being activated. Right now, the only flag that is + * processed is <ACE_NONBLOCK>, which enabled non-blocking I/O on + * the <SVC_HANDLER> when it is opened. + */ int flags_; - // Flags that indicate how <SVC_HANDLER>'s should be initialized - // prior to being activated. Right now, the only flag that is - // processed is <ACE_NONBLOCK>, which enabled non-blocking I/O on - // the <SVC_HANDLER> when it is opened. }; +/** + * @class ACE_Strategy_Connector + * + * @brief Abstract factory for creating a service handler + * (SVC_HANDLER), connecting the SVC_HANDLER, and activating the + * SVC_HANDLER. + * + * Implements a flexible and extensible set of strategies for + * actively establishing connections with clients. There are + * three main strategies: (1) creating a SVC_HANDLER, (2) + * actively connecting a new connection from a client into the + * SVC_HANDLER, and (3) activating the SVC_HANDLER with a + * particular concurrency mechanism. + */ template <class SVC_HANDLER, ACE_PEER_CONNECTOR_1> class ACE_Strategy_Connector : public ACE_Connector <SVC_HANDLER, ACE_PEER_CONNECTOR_2> { - // = TITLE - // Abstract factory for creating a service handler - // (SVC_HANDLER), connecting the SVC_HANDLER, and activating the - // SVC_HANDLER. - // - // = DESCRIPTION - // Implements a flexible and extensible set of strategies for - // actively establishing connections with clients. There are - // three main strategies: (1) creating a SVC_HANDLER, (2) - // actively connecting a new connection from a client into the - // SVC_HANDLER, and (3) activating the SVC_HANDLER with a - // particular concurrency mechanism. public: + /** + * Initialize a connector. <flags> indicates how <SVC_HANDLER>'s + * should be initialized prior to being activated. Right now, the + * only flag that is processed is <ACE_NONBLOCK>, which enabled + * non-blocking I/O on the <SVC_HANDLER> when it is opened. + */ ACE_Strategy_Connector (ACE_Reactor *r = ACE_Reactor::instance (), ACE_Creation_Strategy<SVC_HANDLER> * = 0, ACE_Connect_Strategy<SVC_HANDLER, ACE_PEER_CONNECTOR_2> * = 0, ACE_Concurrency_Strategy<SVC_HANDLER> * = 0, int flags = 0); - // Initialize a connector. <flags> indicates how <SVC_HANDLER>'s - // should be initialized prior to being activated. Right now, the - // only flag that is processed is <ACE_NONBLOCK>, which enabled - // non-blocking I/O on the <SVC_HANDLER> when it is opened. + /** + * Initialize a connector. <flags> indicates how <SVC_HANDLER>'s + * should be initialized prior to being activated. Right now, the + * only flag that is processed is <ACE_NONBLOCK>, which enabled + * non-blocking I/O on the <SVC_HANDLER> when it is opened. + * Default strategies would be created and used. + */ virtual int open (ACE_Reactor *r, int flags); - // Initialize a connector. <flags> indicates how <SVC_HANDLER>'s - // should be initialized prior to being activated. Right now, the - // only flag that is processed is <ACE_NONBLOCK>, which enabled - // non-blocking I/O on the <SVC_HANDLER> when it is opened. - // Default strategies would be created and used. + /** + * Initialize a connector. <flags> indicates how <SVC_HANDLER>'s + * should be initialized prior to being activated. Right now, the + * only flag that is processed is <ACE_NONBLOCK>, which enabled + * non-blocking I/O on the <SVC_HANDLER> when it is opened. + */ virtual int open (ACE_Reactor *r = ACE_Reactor::instance (), ACE_Creation_Strategy<SVC_HANDLER> * = 0, ACE_Connect_Strategy<SVC_HANDLER, ACE_PEER_CONNECTOR_2> * = 0, ACE_Concurrency_Strategy<SVC_HANDLER> * = 0, int flags = 0); - // Initialize a connector. <flags> indicates how <SVC_HANDLER>'s - // should be initialized prior to being activated. Right now, the - // only flag that is processed is <ACE_NONBLOCK>, which enabled - // non-blocking I/O on the <SVC_HANDLER> when it is opened. + /// Shutdown a connector and release resources. virtual ~ACE_Strategy_Connector (void); - // Shutdown a connector and release resources. + /// Close down the Connector virtual int close (void); - // Close down the Connector // = Define some useful typedefs traits. typedef ACE_Creation_Strategy<SVC_HANDLER> @@ -406,17 +437,24 @@ protected: // for creating, connecting, and activating <SVC_HANDLER>'s, // respectively. + /** + * Bridge method for creating a <SVC_HANDLER>. The strategy for + * creating a <SVC_HANDLER> are configured into the Connector via + * it's <creation_strategy_>. The default is to create a new + * <SVC_HANDLER> only if <sh> == 0, else <sh> is unchanged. + * However, subclasses can override this policy to perform + * <SVC_HANDLER> creation in any way that they like (such as + * creating subclass instances of <SVC_HANDLER>, using a singleton, + * dynamically linking the handler, etc.). Returns -1 if failure, + * else 0. + */ virtual int make_svc_handler (SVC_HANDLER *&sh); - // Bridge method for creating a <SVC_HANDLER>. The strategy for - // creating a <SVC_HANDLER> are configured into the Connector via - // it's <creation_strategy_>. The default is to create a new - // <SVC_HANDLER> only if <sh> == 0, else <sh> is unchanged. - // However, subclasses can override this policy to perform - // <SVC_HANDLER> creation in any way that they like (such as - // creating subclass instances of <SVC_HANDLER>, using a singleton, - // dynamically linking the handler, etc.). Returns -1 if failure, - // else 0. + /** + * Bridge method for connecting the new connection into the + * <SVC_HANDLER>. The default behavior delegates to the + * <PEER_CONNECTOR::connect> in the <Connect_Strategy>. + */ virtual int connect_svc_handler (SVC_HANDLER *&sh, const ACE_PEER_CONNECTOR_ADDR &remote_addr, ACE_Time_Value *timeout, @@ -424,10 +462,17 @@ protected: int reuse_addr, int flags, int perms); - // Bridge method for connecting the new connection into the - // <SVC_HANDLER>. The default behavior delegates to the - // <PEER_CONNECTOR::connect> in the <Connect_Strategy>. + /** + * Bridge method for connecting the new connection into the + * <SVC_HANDLER>. The default behavior delegates to the + * <PEER_CONNECTOR::connect> in the <Connect_Strategy>. + * <sh_copy> is used to obtain a copy of the <sh> pointer, but that + * can be kept in the stack; the motivation is a bit too long to + * include here, but basically we want to modify <sh> safely, using + * the internal locks in the Connect_Strategy, while saving a TSS + * copy in <sh_copy>, usually located in the stack. + */ virtual int connect_svc_handler (SVC_HANDLER *&sh, SVC_HANDLER *&sh_copy, const ACE_PEER_CONNECTOR_ADDR &remote_addr, @@ -436,47 +481,41 @@ protected: int reuse_addr, int flags, int perms); - // Bridge method for connecting the new connection into the - // <SVC_HANDLER>. The default behavior delegates to the - // <PEER_CONNECTOR::connect> in the <Connect_Strategy>. - // <sh_copy> is used to obtain a copy of the <sh> pointer, but that - // can be kept in the stack; the motivation is a bit too long to - // include here, but basically we want to modify <sh> safely, using - // the internal locks in the Connect_Strategy, while saving a TSS - // copy in <sh_copy>, usually located in the stack. + /** + * Bridge method for activating a <SVC_HANDLER> with the appropriate + * concurrency strategy. The default behavior of this method is to + * activate the <SVC_HANDLER> by calling its <open> method (which + * allows the <SVC_HANDLER> to define its own concurrency strategy). + * However, subclasses can override this strategy to do more + * sophisticated concurrency activations (such as creating the + * <SVC_HANDLER> as an "active object" via multi-threading or + * multi-processing). + */ virtual int activate_svc_handler (SVC_HANDLER *svc_handler); - // Bridge method for activating a <SVC_HANDLER> with the appropriate - // concurrency strategy. The default behavior of this method is to - // activate the <SVC_HANDLER> by calling its <open> method (which - // allows the <SVC_HANDLER> to define its own concurrency strategy). - // However, subclasses can override this strategy to do more - // sophisticated concurrency activations (such as creating the - // <SVC_HANDLER> as an "active object" via multi-threading or - // multi-processing). // = Strategy objects. + /// Creation strategy for an <Connector>. CREATION_STRATEGY *creation_strategy_; - // Creation strategy for an <Connector>. + /// 1 if <Connector> created the creation strategy and thus should + /// delete it, else 0. int delete_creation_strategy_; - // 1 if <Connector> created the creation strategy and thus should - // delete it, else 0. + /// Connect strategy for a <Connector>. CONNECT_STRATEGY *connect_strategy_; - // Connect strategy for a <Connector>. + /// 1 if <Connector> created the connect strategy and thus should + /// delete it, else 0. int delete_connect_strategy_; - // 1 if <Connector> created the connect strategy and thus should - // delete it, else 0. + /// Concurrency strategy for an <Connector>. CONCURRENCY_STRATEGY *concurrency_strategy_; - // Concurrency strategy for an <Connector>. + /// 1 if <Connector> created the concurrency strategy and thus should + /// delete it, else 0. int delete_concurrency_strategy_; - // 1 if <Connector> created the concurrency strategy and thus should - // delete it, else 0. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/Containers.h b/ace/Containers.h index 46512fe9836..1807c6f1273 100644 --- a/ace/Containers.h +++ b/ace/Containers.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Containers.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Containers.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_CONTAINERS_H #define ACE_CONTAINERS_H @@ -35,11 +32,14 @@ class ACE_Double_Linked_List_Iterator; template <class T> class ACE_Double_Linked_List_Reverse_Iterator; +/** + * @class ACE_DLList_Node + * + * @brief Base implementation of element in a DL list. Needed for + * ACE_Double_Linked_List. + */ class ACE_Export ACE_DLList_Node { - // = TITLE - // Base implementation of element in a DL list. Needed for - // ACE_Double_Linked_List. public: friend class ACE_Double_Linked_List<ACE_DLList_Node>; friend class ACE_Double_Linked_List_Iterator_Base<ACE_DLList_Node>; @@ -51,8 +51,8 @@ public: ACE_DLList_Node *p = 0); ~ACE_DLList_Node (void); + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. void *item_; diff --git a/ace/Containers_T.h b/ace/Containers_T.h index aac5f1115ac..5f21d5fd841 100644 --- a/ace/Containers_T.h +++ b/ace/Containers_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Containers_T.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Containers_T.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_CONTAINERS_T_H #define ACE_CONTAINERS_T_H @@ -29,142 +26,158 @@ class ACE_Allocator; +/** + * @class ACE_Bounded_Stack + * + * @brief Implement a generic LIFO abstract data type. + * + * This implementation of a Stack uses a bounded array + * that is allocated dynamically. + */ template <class T> class ACE_Bounded_Stack { - // = TITLE - // Implement a generic LIFO abstract data type. - // - // = DESCRIPTION - // This implementation of a Stack uses a bounded array - // that is allocated dynamically. public: // = Initialization, assignemnt, and termination methods. + /// Initialize a new stack so that it is empty. + /// The copy constructor (performs initialization). ACE_Bounded_Stack (size_t size); - // Initialize a new stack so that it is empty. ACE_Bounded_Stack (const ACE_Bounded_Stack<T> &s); - // The copy constructor (performs initialization). + /// Assignment operator (performs assignment). void operator= (const ACE_Bounded_Stack<T> &s); - // Assignment operator (performs assignment). + /// Perform actions needed when stack goes out of scope. ~ACE_Bounded_Stack (void); - // Perform actions needed when stack goes out of scope. // = Classic Stack operations. + /** + * Place a new item on top of the stack. Returns -1 if the stack + * is already full, 0 if the stack is not already full, and -1 if + * failure occurs. + */ int push (const T &new_item); - // Place a new item on top of the stack. Returns -1 if the stack - // is already full, 0 if the stack is not already full, and -1 if - // failure occurs. + /** + * Remove and return the top stack item. Returns -1 if the stack is + * already empty, 0 if the stack is not already empty, and -1 if + * failure occurs. + */ int pop (T &item); - // Remove and return the top stack item. Returns -1 if the stack is - // already empty, 0 if the stack is not already empty, and -1 if - // failure occurs. + /** + * Return top stack item without removing it. Returns -1 if the + * stack is already empty, 0 if the stack is not already empty, and + * -1 if failure occurs. + */ int top (T &item) const; - // Return top stack item without removing it. Returns -1 if the - // stack is already empty, 0 if the stack is not already empty, and - // -1 if failure occurs. // = Check boundary conditions. + /// Returns 1 if the container is empty, otherwise returns 0. int is_empty (void) const; - // Returns 1 if the container is empty, otherwise returns 0. + /// Returns 1 if the container is full, otherwise returns 0. int is_full (void) const; - // Returns 1 if the container is full, otherwise returns 0. + /// The number of items in the stack. size_t size (void) const; - // The number of items in the stack. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Size of the dynamically allocated data. size_t size_; - // Size of the dynamically allocated data. + /// Keeps track of the current top of stack. size_t top_; - // Keeps track of the current top of stack. + /// Holds the stack's contents. T *stack_; - // Holds the stack's contents. }; //---------------------------------------- +/** + * @class ACE_Fixed_Stack + * + * @brief Implement a generic LIFO abstract data type. + * + * This implementation of a Stack uses a fixed array + * with the size fixed at instantiation time. + */ template <class T, size_t ACE_SIZE> class ACE_Fixed_Stack { - // = TITLE - // Implement a generic LIFO abstract data type. - // - // = DESCRIPTION - // This implementation of a Stack uses a fixed array - // with the size fixed at instantiation time. public: // = Initialization, assignemnt, and termination methods. + /// Initialize a new stack so that it is empty. ACE_Fixed_Stack (void); - // Initialize a new stack so that it is empty. + /// The copy constructor (performs initialization). ACE_Fixed_Stack (const ACE_Fixed_Stack<T, ACE_SIZE> &s); - // The copy constructor (performs initialization). + /// Assignment operator (performs assignment). void operator= (const ACE_Fixed_Stack<T, ACE_SIZE> &s); - // Assignment operator (performs assignment). + /// Perform actions needed when stack goes out of scope. ~ACE_Fixed_Stack (void); - // Perform actions needed when stack goes out of scope. // = Classic Stack operations. + /** + * Place a new item on top of the stack. Returns -1 if the stack + * is already full, 0 if the stack is not already full, and -1 if + * failure occurs. + */ int push (const T &new_item); - // Place a new item on top of the stack. Returns -1 if the stack - // is already full, 0 if the stack is not already full, and -1 if - // failure occurs. + /** + * Remove and return the top stack item. Returns -1 if the stack is + * already empty, 0 if the stack is not already empty, and -1 if + * failure occurs. + */ int pop (T &item); - // Remove and return the top stack item. Returns -1 if the stack is - // already empty, 0 if the stack is not already empty, and -1 if - // failure occurs. + /** + * Return top stack item without removing it. Returns -1 if the + * stack is already empty, 0 if the stack is not already empty, and + * -1 if failure occurs. + */ int top (T &item) const; - // Return top stack item without removing it. Returns -1 if the - // stack is already empty, 0 if the stack is not already empty, and - // -1 if failure occurs. // = Check boundary conditions. + /// Returns 1 if the container is empty, otherwise returns 0. int is_empty (void) const; - // Returns 1 if the container is empty, otherwise returns 0. + /// Returns 1 if the container is full, otherwise returns 0. int is_full (void) const; - // Returns 1 if the container is full, otherwise returns 0. + /// The number of items in the stack. size_t size (void) const; - // The number of items in the stack. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Size of the allocated data. size_t size_; - // Size of the allocated data. + /// Keeps track of the current top of stack. size_t top_; - // Keeps track of the current top of stack. + /// Holds the stack's contents. T stack_[ACE_SIZE]; - // Holds the stack's contents. }; //---------------------------------------- @@ -179,11 +192,14 @@ template <class T> class ACE_Unbounded_Stack_Iterator; template <class T> class ACE_Ordered_MultiSet; template <class T> class ACE_Ordered_MultiSet_Iterator; +/** + * @class ACE_Node + * + * @brief Implementation element in a Queue, Set, and Stack. + */ template<class T> class ACE_Node { - // = TITLE - // Implementation element in a Queue, Set, and Stack. public: friend class ACE_Unbounded_Queue<T>; friend class ACE_Unbounded_Queue_Iterator<T>; @@ -193,8 +209,8 @@ public: friend class ACE_Unbounded_Stack_Iterator<T>; # if ! defined (ACE_HAS_BROKEN_NOOP_DTORS) + /// This isn't necessary, but it keeps some compilers happy. ~ACE_Node (void); - // This isn't necessary, but it keeps some compilers happy. # endif /* ! defined (ACE_HAS_BROKEN_NOOP_DTORS) */ private: @@ -203,26 +219,29 @@ private: ACE_Node (ACE_Node<T> *n = 0, int = 0); ACE_Node (const ACE_Node<T> &n); + /// Pointer to next element in the list of <ACE_Node>s. ACE_Node<T> *next_; - // Pointer to next element in the list of <ACE_Node>s. + /// Current value of the item in this node. T item_; - // Current value of the item in this node. }; +/** + * @class ACE_DNode + * + * @brief Implementation element in a bilinked list. + */ template<class T> class ACE_DNode { - // = TITLE - // Implementation element in a bilinked list. friend class ACE_Ordered_MultiSet<T>; friend class ACE_Ordered_MultiSet_Iterator<T>; public: # if ! defined (ACE_HAS_BROKEN_NOOP_DTORS) + /// This isn't necessary, but it keeps some compilers happy. ~ACE_DNode (void); - // This isn't necessary, but it keeps some compilers happy. # endif /* ! defined (ACE_HAS_BROKEN_NOOP_DTORS) */ private: @@ -230,29 +249,31 @@ private: // = Initialization methods ACE_DNode (const T &i, ACE_DNode<T> *n = 0, ACE_DNode<T> *p = 0); + /// Pointer to next element in the list of <ACE_DNode>s. ACE_DNode<T> *next_; - // Pointer to next element in the list of <ACE_DNode>s. + /// Pointer to previous element in the list of <ACE_DNode>s. ACE_DNode<T> *prev_; - // Pointer to previous element in the list of <ACE_DNode>s. + /// Current value of the item in this node. T item_; - // Current value of the item in this node. }; +/** + * @class ACE_Unbounded_Stack + * + * @brief Implement a generic LIFO abstract data type. + * + * This implementation of an unbounded Stack uses a linked list. + * If you use the <insert> or <remove> methods you should keep + * in mind that duplicate entries aren't allowed. In general, + * therefore, you should avoid the use of these methods since + * they aren't really part of the ADT stack. + */ template <class T> class ACE_Unbounded_Stack { - // = TITLE - // Implement a generic LIFO abstract data type. - // - // = DESCRIPTION - // This implementation of an unbounded Stack uses a linked list. - // If you use the <insert> or <remove> methods you should keep - // in mind that duplicate entries aren't allowed. In general, - // therefore, you should avoid the use of these methods since - // they aren't really part of the ADT stack. public: friend class ACE_Unbounded_Stack_Iterator<T>; @@ -260,177 +281,193 @@ public: typedef ACE_Unbounded_Stack_Iterator<T> ITERATOR; // = Initialization, assignemnt, and termination methods. + /// Initialize a new stack so that it is empty. Use user defined + /// allocation strategy if specified. ACE_Unbounded_Stack (ACE_Allocator *alloc = 0); - // Initialize a new stack so that it is empty. Use user defined - // allocation strategy if specified. + /// The copy constructor (performs initialization). ACE_Unbounded_Stack (const ACE_Unbounded_Stack<T> &s); - // The copy constructor (performs initialization). + /// Assignment operator (performs assignment). void operator= (const ACE_Unbounded_Stack<T> &s); - // Assignment operator (performs assignment). + /// Perform actions needed when stack goes out of scope. ~ACE_Unbounded_Stack (void); - // Perform actions needed when stack goes out of scope. // = Classic Stack operations. + /** + * Place a new item on top of the stack. Returns -1 if the stack + * is already full, 0 if the stack is not already full, and -1 if + * failure occurs. + */ int push (const T &new_item); - // Place a new item on top of the stack. Returns -1 if the stack - // is already full, 0 if the stack is not already full, and -1 if - // failure occurs. + /** + * Remove and return the top stack item. Returns -1 if the stack is + * already empty, 0 if the stack is not already empty, and -1 if + * failure occurs. + */ int pop (T &item); - // Remove and return the top stack item. Returns -1 if the stack is - // already empty, 0 if the stack is not already empty, and -1 if - // failure occurs. + /** + * Return top stack item without removing it. Returns -1 if the + * stack is already empty, 0 if the stack is not already empty, and + * -1 if failure occurs. + */ int top (T &item) const; - // Return top stack item without removing it. Returns -1 if the - // stack is already empty, 0 if the stack is not already empty, and - // -1 if failure occurs. // = Check boundary conditions. + /// Returns 1 if the container is empty, otherwise returns 0. int is_empty (void) const; - // Returns 1 if the container is empty, otherwise returns 0. + /// Returns 1 if the container is full, otherwise returns 0. int is_full (void) const; - // Returns 1 if the container is full, otherwise returns 0. // = Auxiliary methods (not strictly part of the Stack ADT). + /** + * Insert <new_item> into the Stack at the head (but doesn't allow + * duplicates). Returns -1 if failures occur, 1 if item is already + * present (i.e., no duplicates are allowed), else 0. + */ int insert (const T &new_item); - // Insert <new_item> into the Stack at the head (but doesn't allow - // duplicates). Returns -1 if failures occur, 1 if item is already - // present (i.e., no duplicates are allowed), else 0. + /// Remove <item> from the Stack. Returns 0 if it removes the item, + /// -1 if it can't find the item, and -1 if a failure occurs. int remove (const T &item); - // Remove <item> from the Stack. Returns 0 if it removes the item, - // -1 if it can't find the item, and -1 if a failure occurs. + /// Finds if <item> occurs the set. Returns 0 if finds, else -1. int find (const T &item) const; - // Finds if <item> occurs the set. Returns 0 if finds, else -1. + /// The number of items in the stack. size_t size (void) const; - // The number of items in the stack. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Delete all the nodes in the stack. void delete_all_nodes (void); - // Delete all the nodes in the stack. + /// Copy all nodes from <s> to <this>. void copy_all_nodes (const ACE_Unbounded_Stack<T> &s); - // Copy all nodes from <s> to <this>. + /// Head of the linked list of Nodes. ACE_Node<T> *head_; - // Head of the linked list of Nodes. + /// Current size of the stack. size_t cur_size_; - // Current size of the stack. + /// Allocation strategy of the stack. ACE_Allocator *allocator_; - // Allocation strategy of the stack. }; +/** + * @class ACE_Unbounded_Stack_Iterator + * + * @brief Implement an iterator over an unbounded Stack. + */ template <class T> class ACE_Unbounded_Stack_Iterator { - // = TITLE - // Implement an iterator over an unbounded Stack. public: // = Initialization method. + /// Move to the first element in the <stack>. ACE_Unbounded_Stack_Iterator (ACE_Unbounded_Stack<T> &stack); - // Move to the first element in the <stack>. // = Iteration methods. + /// Pass back the <next_item> that hasn't been seen in the Stack. + /// Returns 0 when all items have been seen, else 1. int next (T *&next_item); - // Pass back the <next_item> that hasn't been seen in the Stack. - // Returns 0 when all items have been seen, else 1. + /// Move forward by one element in the Stack. Returns 0 when all the + /// items in the Stack have been seen, else 1. int advance (void); - // Move forward by one element in the Stack. Returns 0 when all the - // items in the Stack have been seen, else 1. + /// Move to the first element in the Stack. Returns 0 if the + /// Stack is empty, else 1. int first (void); - // Move to the first element in the Stack. Returns 0 if the - // Stack is empty, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to the current node in the iteration. ACE_Node<T> *current_; - // Pointer to the current node in the iteration. + /// Pointer to the Stack we're iterating over. ACE_Unbounded_Stack<T> &stack_; - // Pointer to the Stack we're iterating over. }; template <class T> class ACE_Unbounded_Queue; +/** + * @class ACE_Unbounded_Queue_Iterator + * + * @brief Implement an iterator over an unbounded queue. + */ template <class T> class ACE_Unbounded_Queue_Iterator { - // = TITLE - // Implement an iterator over an unbounded queue. public: // = Initialization method. ACE_Unbounded_Queue_Iterator (ACE_Unbounded_Queue<T> &q, int end = 0); // = Iteration methods. + /// Pass back the <next_item> that hasn't been seen in the queue. + /// Returns 0 when all items have been seen, else 1. int next (T *&next_item); - // Pass back the <next_item> that hasn't been seen in the queue. - // Returns 0 when all items have been seen, else 1. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the queue have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the queue have been seen, else 1. + /// Move to the first element in the queue. Returns 0 if the + /// queue is empty, else 1. int first (void); - // Move to the first element in the queue. Returns 0 if the - // queue is empty, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to the current node in the iteration. ACE_Node<T> *current_; - // Pointer to the current node in the iteration. + /// Pointer to the queue we're iterating over. ACE_Unbounded_Queue<T> &queue_; - // Pointer to the queue we're iterating over. }; +/** + * @class ACE_Unbounded_Queue + * + * @brief A Queue of "infinite" length. + * + * This implementation of an unbounded queue uses a circular + * linked list with a dummy node. + */ template <class T> class ACE_Unbounded_Queue { - // = TITLE - // A Queue of "infinite" length. - // - // = DESCRIPTION - // This implementation of an unbounded queue uses a circular - // linked list with a dummy node. public: friend class ACE_Unbounded_Queue_Iterator<T>; @@ -438,319 +475,343 @@ public: typedef ACE_Unbounded_Queue_Iterator<T> ITERATOR; // = Initialization and termination methods. + /// construction. Use user specified allocation strategy + /// if specified. ACE_Unbounded_Queue (ACE_Allocator *alloc = 0); - // construction. Use user specified allocation strategy - // if specified. + /// Copy constructor. ACE_Unbounded_Queue (const ACE_Unbounded_Queue<T> &); - // Copy constructor. + /// Assignment operator. void operator= (const ACE_Unbounded_Queue<T> &); - // Assignment operator. + /// construction. ~ACE_Unbounded_Queue (void); - // construction. // = Check boundary conditions. + /// Returns 1 if the container is empty, otherwise returns 0. int is_empty (void) const; - // Returns 1 if the container is empty, otherwise returns 0. + /// Returns 1 if the container is full, otherwise returns 0. int is_full (void) const; - // Returns 1 if the container is full, otherwise returns 0. // = Classic queue operations. + /// Adds <new_item> to the tail of the queue. Returns 0 on success, + /// -1 on failure. int enqueue_tail (const T &new_item); - // Adds <new_item> to the tail of the queue. Returns 0 on success, - // -1 on failure. + /// Adds <new_item> to the head of the queue. Returns 0 on success, + /// -1 on failure. int enqueue_head (const T &new_item); - // Adds <new_item> to the head of the queue. Returns 0 on success, - // -1 on failure. + /// Removes and returns the first <item> on the queue. Returns 0 on + /// success, -1 if the queue was empty. int dequeue_head (T &item); - // Removes and returns the first <item> on the queue. Returns 0 on - // success, -1 if the queue was empty. // = Additional utility methods. + /// Reset the <ACE_Unbounded_Queue> to be empty and release all its + /// dynamically allocated resources. void reset (void); - // Reset the <ACE_Unbounded_Queue> to be empty and release all its - // dynamically allocated resources. + /// Get the <slot>th element in the set. Returns -1 if the element + /// isn't in the range {0..<size> - 1}, else 0. int get (T *&item, size_t slot = 0) const; - // Get the <slot>th element in the set. Returns -1 if the element - // isn't in the range {0..<size> - 1}, else 0. + /** + * Set the <slot>th element in the set. Will pad out the set with + * empty nodes if <slot> is beyond the range {0..<size> - 1}. + * Returns -1 on failure, 0 if <slot> isn't initially in range, and + * 0 otherwise. + */ int set (const T &item, size_t slot); - // Set the <slot>th element in the set. Will pad out the set with - // empty nodes if <slot> is beyond the range {0..<size> - 1}. - // Returns -1 on failure, 0 if <slot> isn't initially in range, and - // 0 otherwise. + /// The number of items in the queue. size_t size (void) const; - // The number of items in the queue. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL-styled unidirectional iterator factory. ACE_Unbounded_Queue_Iterator<T> begin (void); ACE_Unbounded_Queue_Iterator<T> end (void); + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Delete all the nodes in the queue. void delete_nodes (void); - // Delete all the nodes in the queue. + /// Copy nodes into this queue. void copy_nodes (const ACE_Unbounded_Queue<T> &); - // Copy nodes into this queue. + /// Pointer to the dummy node in the circular linked Queue. ACE_Node<T> *head_; - // Pointer to the dummy node in the circular linked Queue. + /// Current size of the queue. size_t cur_size_; - // Current size of the queue. + /// Allocation Strategy of the queue. ACE_Allocator *allocator_; - // Allocation Strategy of the queue. }; template <class T> class ACE_Double_Linked_List; +/** + * @class ACE_Double_Linked_List_Iterator_Base + * + * @brief Implements a common base class for iterators for a double + * linked list ADT + */ template <class T> class ACE_Double_Linked_List_Iterator_Base { - // = TITLE - // Implements a common base class for iterators for a double - // linked list ADT public: // = Iteration methods. + /// Passes back the <entry> under the iterator. Returns 0 if the + /// iteration has completed, otherwise 1 int next (T *&) const; - // Passes back the <entry> under the iterator. Returns 0 if the - // iteration has completed, otherwise 1 + /** + * Return the address of next (current) unvisited item in the list. + * 0 if there is no more element available. + * DEPRECATED + */ T *next (void) const; - // Return the address of next (current) unvisited item in the list. - // 0 if there is no more element available. - // DEPRECATED + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// STL-like iterator dereference operator: returns a reference + /// to the node underneath the iterator. T & operator* (void) const ; - // STL-like iterator dereference operator: returns a reference - // to the node underneath the iterator. + /** + * Retasks the iterator to iterate over a new + * Double_Linked_List. This allows clients to reuse an iterator + * without incurring the constructor overhead. If you do use this, + * be aware that if there are more than one reference to this + * iterator, the other "clients" may be very bothered when their + * iterator changes. @@ Here be dragons. Comments? + */ void reset (ACE_Double_Linked_List<T> &); - // Retasks the iterator to iterate over a new - // Double_Linked_List. This allows clients to reuse an iterator - // without incurring the constructor overhead. If you do use this, - // be aware that if there are more than one reference to this - // iterator, the other "clients" may be very bothered when their - // iterator changes. @@ Here be dragons. Comments? + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Initialization methods. + /// Constructor ACE_Double_Linked_List_Iterator_Base (ACE_Double_Linked_List<T> &); - // Constructor + /// Copy constructor. ACE_Double_Linked_List_Iterator_Base (const ACE_Double_Linked_List_Iterator_Base<T> &iter); - // Copy constructor. // = Iteration methods. + /** + * Move to the first element of the list. Returns 0 if the list is + * empty, else 1. Note: the head of the ACE_DLList is actually a + * null entry, so the first element is actually the 2n'd entry + */ int go_head (void); - // Move to the first element of the list. Returns 0 if the list is - // empty, else 1. Note: the head of the ACE_DLList is actually a - // null entry, so the first element is actually the 2n'd entry + /// Move to the last element of the list. Returns 0 if the list is + /// empty, else 1. int go_tail (void); - // Move to the last element of the list. Returns 0 if the list is - // empty, else 1. + /** + * Check if we reach the end of the list. Can also be used to get + * the *current* element in the list. Return the address of the + * current item if there are still elements left , 0 if we run out + * of element. + */ T *not_done (void) const ; - // Check if we reach the end of the list. Can also be used to get - // the *current* element in the list. Return the address of the - // current item if there are still elements left , 0 if we run out - // of element. + /// Advance to the next element in the list. Return the address of the + /// next element if there are more, 0 otherwise. T *do_advance (void); - // Advance to the next element in the list. Return the address of the - // next element if there are more, 0 otherwise. + /// Retreat to the previous element in the list. Return the address + /// of the previous element if there are more, 0 otherwise. T *do_retreat (void); - // Retreat to the previous element in the list. Return the address - // of the previous element if there are more, 0 otherwise. + /// Dump the state of an object. void dump_i (void) const; - // Dump the state of an object. + /// Remember where we are. T *current_; - // Remember where we are. ACE_Double_Linked_List<T> *dllist_; }; +/** + * @class ACE_Double_Linked_List_Iterator + * + * @brief Implements an iterator for a double linked list ADT + * + * Iterate thru the double-linked list. This class provides + * an interface that let users access the internal element + * addresses directly. Notice <class T> must delcare + * ACE_Double_Linked_List<T>, + * ACE_Double_Linked_List_Iterator_Base <T> and + * ACE_Double_Linked_List_Iterator as friend classes and class T + * should also have data members T* next_ and T* prev_. + */ template <class T> class ACE_Double_Linked_List_Iterator : public ACE_Double_Linked_List_Iterator_Base <T> { - // = TITLE - // Implements an iterator for a double linked list ADT - // - // = DESCRIPTION - // Iterate thru the double-linked list. This class provides - // an interface that let users access the internal element - // addresses directly. Notice <class T> must delcare - // ACE_Double_Linked_List<T>, - // ACE_Double_Linked_List_Iterator_Base <T> and - // ACE_Double_Linked_List_Iterator as friend classes and class T - // should also have data members T* next_ and T* prev_. public: // = Initialization method. ACE_Double_Linked_List_Iterator (ACE_Double_Linked_List<T> &); + /** + * Retasks the iterator to iterate over a new + * Double_Linked_List. This allows clients to reuse an iterator + * without incurring the constructor overhead. If you do use this, + * be aware that if there are more than one reference to this + * iterator, the other "clients" may be very bothered when their + * iterator changes. + * @@ Here be dragons. Comments? + */ void reset (ACE_Double_Linked_List<T> &); - // Retasks the iterator to iterate over a new - // Double_Linked_List. This allows clients to reuse an iterator - // without incurring the constructor overhead. If you do use this, - // be aware that if there are more than one reference to this - // iterator, the other "clients" may be very bothered when their - // iterator changes. - // @@ Here be dragons. Comments? + /// Move to the first element in the list. Returns 0 if the + /// list is empty, else 1. int first (void); - // Move to the first element in the list. Returns 0 if the - // list is empty, else 1. + /// Move forward by one element in the list. Returns 0 when all the + /// items in the list have been seen, else 1. int advance (void); - // Move forward by one element in the list. Returns 0 when all the - // items in the list have been seen, else 1. + /** + * Advance the iterator while removing the original item from the + * list. Return a pointer points to the original (removed) item. + * If <dont_remove> equals 0, this function behaves like <advance> + * but return 0 (NULL) instead. + */ T* advance_and_remove (int dont_remove); - // Advance the iterator while removing the original item from the - // list. Return a pointer points to the original (removed) item. - // If <dont_remove> equals 0, this function behaves like <advance> - // but return 0 (NULL) instead. // = STL-style iteration methods + /// Prefix advance. ACE_Double_Linked_List_Iterator<T> & operator++ (void); - // Prefix advance. + /// Postfix advance. ACE_Double_Linked_List_Iterator<T> operator++ (int); - // Postfix advance. + /// Prefix reverse. ACE_Double_Linked_List_Iterator<T> & operator-- (void); - // Prefix reverse. + /// Postfix reverse. ACE_Double_Linked_List_Iterator<T> operator-- (int); - // Postfix reverse. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Double_Linked_List_Reverse_Iterator + * + * @brief Implements a reverse iterator for a double linked list ADT + * + * Iterate backwards over the double-linked list. This class + * provide an interface that let users access the internal + * element addresses directly, which seems to break the + * encapsulation. Notice <class T> must delcare + * ACE_Double_Linked_List<T>, + * ACE_Double_Linked_List_Iterator_Base <T> and + * ACE_Double_Linked_List_Iterator as friend classes and class T + * should also have data members T* next_ and T* prev_. + */ template <class T> class ACE_Double_Linked_List_Reverse_Iterator : public ACE_Double_Linked_List_Iterator_Base <T> { - // = TITLE - // Implements a reverse iterator for a double linked list ADT - // - // = DESCRIPTION - // Iterate backwards over the double-linked list. This class - // provide an interface that let users access the internal - // element addresses directly, which seems to break the - // encapsulation. Notice <class T> must delcare - // ACE_Double_Linked_List<T>, - // ACE_Double_Linked_List_Iterator_Base <T> and - // ACE_Double_Linked_List_Iterator as friend classes and class T - // should also have data members T* next_ and T* prev_. public: // = Initialization method. ACE_Double_Linked_List_Reverse_Iterator (ACE_Double_Linked_List<T> &); + /** + * Retasks the iterator to iterate over a new + * Double_Linked_List. This allows clients to reuse an iterator + * without incurring the constructor overhead. If you do use this, + * be aware that if there are more than one reference to this + * iterator, the other "clients" may be very bothered when their + * iterator changes. + * @@ Here be dragons. Comments? + */ void reset (ACE_Double_Linked_List<T> &); - // Retasks the iterator to iterate over a new - // Double_Linked_List. This allows clients to reuse an iterator - // without incurring the constructor overhead. If you do use this, - // be aware that if there are more than one reference to this - // iterator, the other "clients" may be very bothered when their - // iterator changes. - // @@ Here be dragons. Comments? + /// Move to the first element in the list. Returns 0 if the + /// list is empty, else 1. int first (void); - // Move to the first element in the list. Returns 0 if the - // list is empty, else 1. + /// Move forward by one element in the list. Returns 0 when all the + /// items in the list have been seen, else 1. int advance (void); - // Move forward by one element in the list. Returns 0 when all the - // items in the list have been seen, else 1. + /** + * Advance the iterator while removing the original item from the + * list. Return a pointer points to the original (removed) item. + * If <dont_remove> equals 0, this function behaves like <advance> + * but return 0 (NULL) instead. + */ T* advance_and_remove (int dont_remove); - // Advance the iterator while removing the original item from the - // list. Return a pointer points to the original (removed) item. - // If <dont_remove> equals 0, this function behaves like <advance> - // but return 0 (NULL) instead. // = STL-style iteration methods + /// Prefix advance. ACE_Double_Linked_List_Reverse_Iterator<T> & operator++ (void); - // Prefix advance. + /// Postfix advance. ACE_Double_Linked_List_Reverse_Iterator<T> operator++ (int); - // Postfix advance. + /// Prefix reverse. ACE_Double_Linked_List_Reverse_Iterator<T> & operator-- (void); - // Prefix reverse. + /// Postfix reverse. ACE_Double_Linked_List_Reverse_Iterator<T> operator-- (int); - // Postfix reverse. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Double_Linked_List + * + * @brief A double-linked list implementation. + * + * This implementation of an unbounded double-linked list uses a + * circular linked list with a dummy node. It is pretty much + * like the <ACE_Unbounded_Queue> except that it allows removing + * of a specific element from a specific location. + * Notice that this class is an implementation of a very simply + * data structure.is *NOT* a container class. You can use the + * class to implement other contains classes but it is *NOT* a + * general purpose container class. + * The parameter class *MUST* has members T* prev and T* next + * and users of this class are responsible to follow the general + * rules of using double-linked lists to maintaining the list + * integrities. + * If you need a double linked container class, check out the + * DLList class in this file. + */ template <class T> class ACE_Double_Linked_List { - // = TITLE - // A double-linked list implementation. - // - // = DESCRIPTION - // This implementation of an unbounded double-linked list uses a - // circular linked list with a dummy node. It is pretty much - // like the <ACE_Unbounded_Queue> except that it allows removing - // of a specific element from a specific location. - // - // Notice that this class is an implementation of a very simply - // data structure.is *NOT* a container class. You can use the - // class to implement other contains classes but it is *NOT* a - // general purpose container class. - // - // The parameter class *MUST* has members T* prev and T* next - // and users of this class are responsible to follow the general - // rules of using double-linked lists to maintaining the list - // integrities. - // - // If you need a double linked container class, check out the - // DLList class in this file. public: friend class ACE_Double_Linked_List_Iterator_Base<T>; friend class ACE_Double_Linked_List_Iterator<T>; @@ -761,102 +822,112 @@ public: typedef ACE_Double_Linked_List_Reverse_Iterator<T> REVERSE_ITERATOR; // = Initialization and termination methods. + /// construction. Use user specified allocation strategy + /// if specified. ACE_Double_Linked_List (ACE_Allocator *alloc = 0); - // construction. Use user specified allocation strategy - // if specified. + /// Copy constructor. ACE_Double_Linked_List (ACE_Double_Linked_List<T> &); - // Copy constructor. + /// Assignment operator. void operator= (ACE_Double_Linked_List<T> &); - // Assignment operator. + /// Destructor. ~ACE_Double_Linked_List (void); - // Destructor. // = Check boundary conditions. + /// Returns 1 if the container is empty, otherwise returns 0. int is_empty (void) const; - // Returns 1 if the container is empty, otherwise returns 0. + /// Returns 1 if the container is full, otherwise returns 0. int is_full (void) const; - // Returns 1 if the container is full, otherwise returns 0. // = Classic queue operations. + /// Adds <new_item> to the tail of the list. Returns the new item + /// that was inserted. T *insert_tail (T *new_item); - // Adds <new_item> to the tail of the list. Returns the new item - // that was inserted. + /// Adds <new_item> to the head of the list.Returns the new item that + /// was inserted. T *insert_head (T *new_item); - // Adds <new_item> to the head of the list.Returns the new item that - // was inserted. + /** + * Removes and returns the first <item> in the list. Returns + * internal node's address on success, 0 if the queue was empty. + * This method will *not* free the internal node. + */ T* delete_head (void); - // Removes and returns the first <item> in the list. Returns - // internal node's address on success, 0 if the queue was empty. - // This method will *not* free the internal node. + /** + * Removes and returns the last <item> in the list. Returns + * internal nodes's address on success, 0 if the queue was + * empty. This method will *not* free the internal node. + */ T *delete_tail (void); - // Removes and returns the last <item> in the list. Returns - // internal nodes's address on success, 0 if the queue was - // empty. This method will *not* free the internal node. // = Additional utility methods. + /** + * Reset the <ACE_Double_Linked_List> to be empty. + * Notice that since no one is interested in the items within, + * This operation will delete all items. + */ void reset (void); - // Reset the <ACE_Double_Linked_List> to be empty. - // Notice that since no one is interested in the items within, - // This operation will delete all items. + /// Get the <slot>th element in the set. Returns -1 if the element + /// isn't in the range {0..<size> - 1}, else 0. int get (T *&item, size_t slot = 0); - // Get the <slot>th element in the set. Returns -1 if the element - // isn't in the range {0..<size> - 1}, else 0. + /// The number of items in the queue. size_t size (void) const; - // The number of items in the queue. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Use DNode address directly. int remove (T *n); - // Use DNode address directly. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Delete all the nodes in the list. void delete_nodes (void); - // Delete all the nodes in the list. + /// Copy nodes into this list. void copy_nodes (ACE_Double_Linked_List<T> &); - // Copy nodes into this list. + /// Setup header pointer. Called after we create the head node in ctor. void init_head (void); - // Setup header pointer. Called after we create the head node in ctor. + /** + * Insert a <new_element> into the list. It will be added before + * or after <old_item>. Default is to insert the new item *after* + * <head_>. Return 0 if succeed, -1 if error occured. + */ int insert_element (T *new_item, int before = 0, T *old_item = 0); - // Insert a <new_element> into the list. It will be added before - // or after <old_item>. Default is to insert the new item *after* - // <head_>. Return 0 if succeed, -1 if error occured. + /** + * Remove an <item> from the list. Return 0 if succeed, -1 otherwise. + * Notice that this function checks if item is <head_> and either its + * <next_> or <prev_> is NULL. The function resets item's <next_> and + * <prev_> to 0 to prevent clobbering the double-linked list if a user + * tries to remove the same node again. + */ int remove_element (T *item); - // Remove an <item> from the list. Return 0 if succeed, -1 otherwise. - // Notice that this function checks if item is <head_> and either its - // <next_> or <prev_> is NULL. The function resets item's <next_> and - // <prev_> to 0 to prevent clobbering the double-linked list if a user - // tries to remove the same node again. + /// Head of the circular double-linked list. T *head_; - // Head of the circular double-linked list. + /// Size of this list. size_t size_; - // Size of this list. + /// Allocation Strategy of the queue. ACE_Allocator *allocator_; - // Allocation Strategy of the queue. }; @@ -878,16 +949,18 @@ typedef ACE_Double_Linked_List<ACE_DLList_Node> ACE_DLList_Base; // replacing all references to the base classes with their actual // type. Matt Braun (6/15/99) +/** + * @class ACE_DLList + * + * @brief A double-linked list container class. + * + * This implementation uses ACE_Double_Linked_List to perform + * the logic behind this container class. It delegates all of its + * calls to ACE_Double_Linked_List. + */ template <class T> class ACE_DLList : public ACE_DLList_Base { - // = TITLE - // A double-linked list container class. - // - // = DESCRIPTION - // This implementation uses ACE_Double_Linked_List to perform - // the logic behind this container class. It delegates all of its - // calls to ACE_Double_Linked_List. friend class ACE_DLList_Node; friend class ACE_Double_Linked_List_Iterator<T>; @@ -896,59 +969,63 @@ class ACE_DLList : public ACE_DLList_Base public: + /// Delegates to ACE_Double_Linked_List. void operator= (ACE_DLList<T> &l); - // Delegates to ACE_Double_Linked_List. // = Classic queue operations. + /// Delegates to ACE_Double_Linked_List. T *insert_tail (T *new_item); - // Delegates to ACE_Double_Linked_List. + /// Delegates to ACE_Double_Linked_List. T *insert_head (T *new_item); - // Delegates to ACE_Double_Linked_List. + /// Delegates to ACE_Double_Linked_List. T *delete_head (void); - // Delegates to ACE_Double_Linked_List. + /// Delegates to ACE_Double_Linked_List. T *delete_tail (void); - // Delegates to ACE_Double_Linked_List. // = Additional utility methods. + /** + * Delegates to <ACE_Double_Linked_List>, but where + * <ACE_Double_Linked_List> returns the node as the item, this get + * returns the contents of the node in item. + */ int get (T *&item, size_t slot = 0); - // Delegates to <ACE_Double_Linked_List>, but where - // <ACE_Double_Linked_List> returns the node as the item, this get - // returns the contents of the node in item. + /// Delegates to ACE_Double_Linked_List. void dump (void) const; - // Delegates to ACE_Double_Linked_List. + /// Delegates to ACE_Double_Linked_List. int remove (ACE_DLList_Node *n); - // Delegates to ACE_Double_Linked_List. // = Initialization and termination methods. + /// Delegates to ACE_Double_Linked_List. ACE_DLList (ACE_Allocator *alloc = 0); - // Delegates to ACE_Double_Linked_List. + /// Delegates to ACE_Double_Linked_List. ACE_DLList (ACE_DLList<T> &l); - // Delegates to ACE_Double_Linked_List. + /// Deletes the list starting from the head. ~ACE_DLList (void); - // Deletes the list starting from the head. }; +/** + * @class ACE_DLList_Iterator + * + * @brief A double-linked list container class iterator. + * + * This implementation uses ACE_Double_Linked_List_Iterator to + * perform the logic behind this container class. It delegates + * all of its calls to ACE_Double_Linked_List_Iterator. + */ template <class T> class ACE_DLList_Iterator : public ACE_Double_Linked_List_Iterator <ACE_DLList_Node> { - // = TITLE - // A double-linked list container class iterator. - // - // = DESCRIPTION - // This implementation uses ACE_Double_Linked_List_Iterator to - // perform the logic behind this container class. It delegates - // all of its calls to ACE_Double_Linked_List_Iterator. friend class ACE_DLList<T>; friend class ACE_DLList_Node; @@ -958,50 +1035,56 @@ public: // = Initialization method. ACE_DLList_Iterator (ACE_DLList<T> &l); + /** + * Retasks the iterator to iterate over a new + * Double_Linked_List. This allows clients to reuse an iterator + * without incurring the constructor overhead. If you do use this, + * be aware that if there are more than one reference to this + * iterator, the other "clients" may be very bothered when their + * iterator changes. + * @@ Here be dragons. Comments? + */ void reset (ACE_DLList<T> &l); - // Retasks the iterator to iterate over a new - // Double_Linked_List. This allows clients to reuse an iterator - // without incurring the constructor overhead. If you do use this, - // be aware that if there are more than one reference to this - // iterator, the other "clients" may be very bothered when their - // iterator changes. - // @@ Here be dragons. Comments? // = Iteration methods. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Pass back the <next_item> that hasn't been seen in the Stack. + /// Returns 0 when all items have been seen, else 1. int next (T *&); - // Pass back the <next_item> that hasn't been seen in the Stack. - // Returns 0 when all items have been seen, else 1. + /** + * Delegates to ACE_Double_Linked_List_Iterator, except that whereas + * the Double_Linked_List version of next returns the node, this next + * returns the contents of the node + * DEPRECATED + */ T *next (void) const; - // Delegates to ACE_Double_Linked_List_Iterator, except that whereas - // the Double_Linked_List version of next returns the node, this next - // returns the contents of the node - // DEPRECATED + /// Removes the current item (i.e., <next>) from the list. int remove (void); - // Removes the current item (i.e., <next>) from the list. + /// Delegates to ACE_Double_Linked_List_Iterator. void dump (void) const; - // Delegates to ACE_Double_Linked_List_Iterator. private: ACE_DLList<T> *list_; }; +/** + * @class ACE_DLList_Reverse_Iterator + * + * @brief A double-linked list container class iterator. + * + * This implementation uses ACE_Double_Linked_List_Iterator to + * perform the logic behind this container class. It delegates + * all of its calls to ACE_Double_Linked_List_Iterator. + */ template <class T> class ACE_DLList_Reverse_Iterator : public ACE_Double_Linked_List_Reverse_Iterator <ACE_DLList_Node> { - // = TITLE - // A double-linked list container class iterator. - // - // = DESCRIPTION - // This implementation uses ACE_Double_Linked_List_Iterator to - // perform the logic behind this container class. It delegates - // all of its calls to ACE_Double_Linked_List_Iterator. friend class ACE_DLList<T>; friend class ACE_DLList_Node; @@ -1011,104 +1094,111 @@ public: // = Initialization method. ACE_DLList_Reverse_Iterator (ACE_DLList<T> &l); + /** + * Retasks the iterator to iterate over a new + * Double_Linked_List. This allows clients to reuse an iterator + * without incurring the constructor overhead. If you do use this, + * be aware that if there are more than one reference to this + * iterator, the other "clients" may be very bothered when their + * iterator changes. + * @@ Here be dragons. Comments? + */ void reset (ACE_DLList<T> &l); - // Retasks the iterator to iterate over a new - // Double_Linked_List. This allows clients to reuse an iterator - // without incurring the constructor overhead. If you do use this, - // be aware that if there are more than one reference to this - // iterator, the other "clients" may be very bothered when their - // iterator changes. - // @@ Here be dragons. Comments? // = Iteration methods. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Pass back the <next_item> that hasn't been seen in the Stack. + /// Returns 0 when all items have been seen, else 1. int next (T *&); - // Pass back the <next_item> that hasn't been seen in the Stack. - // Returns 0 when all items have been seen, else 1. + /// Delegates to ACE_Double_Linked_List_Iterator. + /// DEPRECATED T *next (void) const; - // Delegates to ACE_Double_Linked_List_Iterator. - // DEPRECATED + /// Removes the current item (i.e., <next>) from the list. int remove (void); - // Removes the current item (i.e., <next>) from the list. + /// Delegates to ACE_Double_Linked_List_Iterator. void dump (void) const; - // Delegates to ACE_Double_Linked_List_Iterator. private: ACE_DLList<T> *list_; }; +/** + * @class ACE_Unbounded_Set_Iterator + * + * @brief Implement an iterator over an unbounded set. + */ template <class T> class ACE_Unbounded_Set_Iterator { - // = TITLE - // Implement an iterator over an unbounded set. public: // = Initialization method. ACE_Unbounded_Set_Iterator (ACE_Unbounded_Set<T> &s, int end = 0); // = Iteration methods. + /// Pass back the <next_item> that hasn't been seen in the Set. + /// Returns 0 when all items have been seen, else 1. int next (T *&next_item); - // Pass back the <next_item> that hasn't been seen in the Set. - // Returns 0 when all items have been seen, else 1. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Move to the first element in the set. Returns 0 if the + /// set is empty, else 1. int first (void); - // Move to the first element in the set. Returns 0 if the - // set is empty, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL styled iteration, compare, and reference functions. + /// Postfix advance. ACE_Unbounded_Set_Iterator<T> operator++ (int); - // Postfix advance. + /// Prefix advance. ACE_Unbounded_Set_Iterator<T>& operator++ (void); - // Prefix advance. + /// Returns a reference to the interal element <this> is pointing to. T& operator* (void); - // Returns a reference to the interal element <this> is pointing to. + /// Check if two iterators point to the same position int operator== (const ACE_Unbounded_Set_Iterator<T> &) const; int operator!= (const ACE_Unbounded_Set_Iterator<T> &) const; - // Check if two iterators point to the same position + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to the current node in the iteration. ACE_Node<T> *current_; - // Pointer to the current node in the iteration. + /// Pointer to the set we're iterating over. ACE_Unbounded_Set<T> *set_; - // Pointer to the set we're iterating over. }; +/** + * @class ACE_Unbounded_Set + * + * @brief Implement a simple unordered set of <T> of unbounded size. + * + * This implementation of an unordered set uses a circular + * linked list with a dummy node. This implementation does not + * allow duplicates, but it maintains FIFO ordering of insertions. + */ template <class T> class ACE_Unbounded_Set { - // = TITLE - // Implement a simple unordered set of <T> of unbounded size. - // - // = DESCRIPTION - // This implementation of an unordered set uses a circular - // linked list with a dummy node. This implementation does not - // allow duplicates, but it maintains FIFO ordering of insertions. public: friend class ACE_Unbounded_Set_Iterator<T>; @@ -1117,137 +1207,145 @@ public: typedef ACE_Unbounded_Set_Iterator<T> iterator; // = Initialization and termination methods. + /// Constructor. Use user specified allocation strategy + /// if specified. ACE_Unbounded_Set (ACE_Allocator *alloc = 0); - // Constructor. Use user specified allocation strategy - // if specified. + /// Copy constructor. ACE_Unbounded_Set (const ACE_Unbounded_Set<T> &); - // Copy constructor. + /// Assignment operator. void operator= (const ACE_Unbounded_Set<T> &); - // Assignment operator. + /// Destructor. ~ACE_Unbounded_Set (void); - // Destructor. // = Check boundary conditions. + /// Returns 1 if the container is empty, otherwise returns 0. int is_empty (void) const; - // Returns 1 if the container is empty, otherwise returns 0. + /// Returns 1 if the container is full, otherwise returns 0. int is_full (void) const; - // Returns 1 if the container is full, otherwise returns 0. // = Classic unordered set operations. + /** + * Insert <new_item> into the set (doesn't allow duplicates). + * Returns -1 if failures occur, 1 if item is already present, else + * 0. + */ int insert (const T &new_item); - // Insert <new_item> into the set (doesn't allow duplicates). - // Returns -1 if failures occur, 1 if item is already present, else - // 0. + /** + * Remove first occurrence of <item> from the set. Returns 0 if + * it removes the item, -1 if it can't find the item, and -1 if a + * failure occurs. + */ int remove (const T &item); - // Remove first occurrence of <item> from the set. Returns 0 if - // it removes the item, -1 if it can't find the item, and -1 if a - // failure occurs. + /// Finds if <item> occurs in the set. Returns 0 if find succeeds, + /// else -1. int find (const T &item) const; - // Finds if <item> occurs in the set. Returns 0 if find succeeds, - // else -1. + /// Size of the set. size_t size (void) const; - // Size of the set. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Reset the <ACE_Unbounded_Set> to be empty. void reset (void); - // Reset the <ACE_Unbounded_Set> to be empty. // = STL-styled unidirectional iterator factory. ACE_Unbounded_Set_Iterator<T> begin (void); ACE_Unbounded_Set_Iterator<T> end (void); + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Insert <item> at the tail of the set (doesn't check for + /// duplicates). int insert_tail (const T &item); - // Insert <item> at the tail of the set (doesn't check for - // duplicates). + /// Delete all the nodes in the Set. void delete_nodes (void); - // Delete all the nodes in the Set. + /// Copy nodes into this set. void copy_nodes (const ACE_Unbounded_Set<T> &); - // Copy nodes into this set. + /// Head of the linked list of Nodes. ACE_Node<T> *head_; - // Head of the linked list of Nodes. + /// Current size of the set. size_t cur_size_; - // Current size of the set. + /// Allocation strategy of the set. ACE_Allocator *allocator_; - // Allocation strategy of the set. }; // Forward declaration. template <class T, size_t ACE_SIZE> class ACE_Fixed_Set; +/** + * @class ACE_Fixed_Set_Iterator + * + * @brief Interates through an unordered set. + * + * This implementation of an unordered set uses a fixed array. + * Allows deletions while iteration is occurring. + */ template <class T, size_t ACE_SIZE> class ACE_Fixed_Set_Iterator { - // = TITLE - // Interates through an unordered set. - // - // = DESCRIPTION - // This implementation of an unordered set uses a fixed array. - // Allows deletions while iteration is occurring. public: // = Initialization method. ACE_Fixed_Set_Iterator (ACE_Fixed_Set<T, ACE_SIZE> &s); // = Iteration methods. + /// Pass back the <next_item> that hasn't been seen in the Set. + /// Returns 0 when all items have been seen, else 1. int next (T *&next_item); - // Pass back the <next_item> that hasn't been seen in the Set. - // Returns 0 when all items have been seen, else 1. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Move to the first element in the set. Returns 0 if the + /// set is empty, else 1. int first (void); - // Move to the first element in the set. Returns 0 if the - // set is empty, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Set we are iterating over. ACE_Fixed_Set<T, ACE_SIZE> &s_; - // Set we are iterating over. + /// How far we've advanced over the set. ssize_t next_; - // How far we've advanced over the set. }; +/** + * @class ACE_Fixed_Set + * + * @brief Implement a simple unordered set of <T> with maximum <ACE_SIZE>. + * + * This implementation of an unordered set uses a fixed array. + * This implementation does not allow duplicates... + */ template <class T, size_t ACE_SIZE> class ACE_Fixed_Set { - // = TITLE - // Implement a simple unordered set of <T> with maximum <ACE_SIZE>. - // - // = DESCRIPTION - // This implementation of an unordered set uses a fixed array. - // This implementation does not allow duplicates... public: friend class ACE_Fixed_Set_Iterator<T, ACE_SIZE>; @@ -1255,49 +1353,53 @@ public: typedef ACE_Fixed_Set_Iterator<T, ACE_SIZE> ITERATOR; // = Initialization and termination methods. + /// Constructor. ACE_Fixed_Set (void); - // Constructor. + /// Copy constructor. ACE_Fixed_Set (const ACE_Fixed_Set<T, ACE_SIZE> &); - // Copy constructor. + /// Assignment operator. void operator= (const ACE_Fixed_Set<T, ACE_SIZE> &); - // Assignment operator. + /// Destructor. ~ACE_Fixed_Set (void); - // Destructor. // = Check boundary conditions. + /// Returns 1 if the container is empty, otherwise returns 0. int is_empty (void) const; - // Returns 1 if the container is empty, otherwise returns 0. + /// Returns 1 if the container is full, otherwise returns 0. int is_full (void) const; - // Returns 1 if the container is full, otherwise returns 0. // = Classic unordered set operations. + /** + * Insert <new_item> into the set (doesn't allow duplicates). + * Returns -1 if failures occur, 1 if item is already present, else + * 0. + */ int insert (const T &new_item); - // Insert <new_item> into the set (doesn't allow duplicates). - // Returns -1 if failures occur, 1 if item is already present, else - // 0. + /** + * Remove first occurrence of <item> from the set. Returns 0 if + * it removes the item, -1 if it can't find the item, and -1 if a + * failure occurs. + */ int remove (const T &item); - // Remove first occurrence of <item> from the set. Returns 0 if - // it removes the item, -1 if it can't find the item, and -1 if a - // failure occurs. + /// Finds if <item> occurs in the set. Returns 0 if finds, else -1. int find (const T &item) const; - // Finds if <item> occurs in the set. Returns 0 if finds, else -1. + /// Size of the set. size_t size (void) const; - // Size of the set. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: struct @@ -1310,71 +1412,75 @@ private: } search_structure_[ACE_SIZE]; // Holds the contents of the set. + /// Current size of the set. size_t cur_size_; - // Current size of the set. + /// Maximum size of the set. size_t max_size_; - // Maximum size of the set. }; // Forward declaration. template <class T> class ACE_Bounded_Set; +/** + * @class ACE_Bounded_Set_Iterator + * + * @brief Interates through an unordered set. + * + * This implementation of an unordered set uses a Bounded array. + * Allows deletions while iteration is occurring. + */ template <class T> class ACE_Bounded_Set_Iterator { - // = TITLE - // Interates through an unordered set. - // - // = DESCRIPTION - // This implementation of an unordered set uses a Bounded array. - // Allows deletions while iteration is occurring. public: // = Initialization method. ACE_Bounded_Set_Iterator (ACE_Bounded_Set<T> &s); // = Iteration methods. + /// Pass back the <next_item> that hasn't been seen in the Set. + /// Returns 0 when all items have been seen, else 1. int next (T *&next_item); - // Pass back the <next_item> that hasn't been seen in the Set. - // Returns 0 when all items have been seen, else 1. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Move to the first element in the set. Returns 0 if the + /// set is empty, else 1. int first (void); - // Move to the first element in the set. Returns 0 if the - // set is empty, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Set we are iterating over. ACE_Bounded_Set<T> &s_; - // Set we are iterating over. + /// How far we've advanced over the set. ssize_t next_; - // How far we've advanced over the set. }; +/** + * @class ACE_Bounded_Set + * + * @brief Implement a simple unordered set of <T> with maximum + * set at creation time. + * + * This implementation of an unordered set uses a Bounded array. + * This implementation does not allow duplicates... + */ template <class T> class ACE_Bounded_Set { - // = TITLE - // Implement a simple unordered set of <T> with maximum - // set at creation time. - // - // = DESCRIPTION - // This implementation of an unordered set uses a Bounded array. - // This implementation does not allow duplicates... public: friend class ACE_Bounded_Set_Iterator<T>; @@ -1387,52 +1493,56 @@ public: }; // = Initialization and termination methods. + /// Constructor. ACE_Bounded_Set (void); - // Constructor. + /// Constructor. ACE_Bounded_Set (size_t size); - // Constructor. + /// Copy constructor. ACE_Bounded_Set (const ACE_Bounded_Set<T> &); - // Copy constructor. + /// Assignment operator. void operator= (const ACE_Bounded_Set<T> &); - // Assignment operator. + /// Destructor ~ACE_Bounded_Set (void); - // Destructor // = Check boundary conditions. + /// Returns 1 if the container is empty, otherwise returns 0. int is_empty (void) const; - // Returns 1 if the container is empty, otherwise returns 0. + /// Returns 1 if the container is full, otherwise returns 0. int is_full (void) const; - // Returns 1 if the container is full, otherwise returns 0. // = Classic unordered set operations. + /** + * Insert <new_item> into the set (doesn't allow duplicates). + * Returns -1 if failures occur, 1 if item is already present, else + * 0. + */ int insert (const T &new_item); - // Insert <new_item> into the set (doesn't allow duplicates). - // Returns -1 if failures occur, 1 if item is already present, else - // 0. + /** + * Remove first occurrence of <item> from the set. Returns 0 if it + * removes the item, -1 if it can't find the item, and -1 if a + * failure occurs. + */ int remove (const T &item); - // Remove first occurrence of <item> from the set. Returns 0 if it - // removes the item, -1 if it can't find the item, and -1 if a - // failure occurs. + /// Finds if <item> occurs in the set. Returns 0 if finds, else -1. int find (const T &item) const; - // Finds if <item> occurs in the set. Returns 0 if finds, else -1. + /// Size of the set. size_t size (void) const; - // Size of the set. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: struct Search_Structure @@ -1444,24 +1554,27 @@ private: // Keeps track of whether this item is in use or not. }; + /// Holds the contents of the set. Search_Structure *search_structure_; - // Holds the contents of the set. + /// Current size of the set. size_t cur_size_; - // Current size of the set. + /// Maximum size of the set. size_t max_size_; - // Maximum size of the set. }; +/** + * @class ACE_Ordered_MultiSet_Iterator + * + * @brief Implement a bidirectional iterator over an ordered multiset. + * This class template requires that < operator semantics be + * defined for the parameterized type <T>, but does not impose + * any restriction on how that ordering operator is implemented. + */ template <class T> class ACE_Ordered_MultiSet_Iterator { - // = TITLE - // Implement a bidirectional iterator over an ordered multiset. - // This class template requires that < operator semantics be - // defined for the parameterized type <T>, but does not impose - // any restriction on how that ordering operator is implemented. public: friend class ACE_Ordered_MultiSet<T>; @@ -1470,58 +1583,60 @@ public: // = Iteration methods. + /// Pass back the <next_item> that hasn't been seen in the ordered multiset. + /// Returns 0 when all items have been seen, else 1. int next (T *&next_item) const; - // Pass back the <next_item> that hasn't been seen in the ordered multiset. - // Returns 0 when all items have been seen, else 1. + /// Repositions the iterator at the first item in the ordered multiset + /// Returns 0 if the list is empty else 1. int first (void); - // Repositions the iterator at the first item in the ordered multiset - // Returns 0 if the list is empty else 1. + /// Repositions the iterator at the last item in the ordered multiset + /// Returns 0 if the list is empty else 1. int last (void); - // Repositions the iterator at the last item in the ordered multiset - // Returns 0 if the list is empty else 1. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Move backward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int retreat (void); - // Move backward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to the current node in the iteration. ACE_DNode<T> *current_; - // Pointer to the current node in the iteration. + /// Pointer to the set we're iterating over. ACE_Ordered_MultiSet<T> &set_; - // Pointer to the set we're iterating over. }; +/** + * @class ACE_Ordered_MultiSet + * + * @brief Implement a simple ordered multiset of <T> of unbounded size. + * This class template requires that < operator semantics be + * defined for the parameterized type <T>, but does not impose + * any restriction on how that ordering operator is implemented. + * + * This implementation of an unordered set uses a circular + * linked list with a dummy node. This implementation does not + * allow duplicates, but it maintains FIFO ordering of + * insertions. + */ template <class T> class ACE_Ordered_MultiSet { - // = TITLE - // Implement a simple ordered multiset of <T> of unbounded size. - // This class template requires that < operator semantics be - // defined for the parameterized type <T>, but does not impose - // any restriction on how that ordering operator is implemented. - // - // = DESCRIPTION - // This implementation of an unordered set uses a circular - // linked list with a dummy node. This implementation does not - // allow duplicates, but it maintains FIFO ordering of - // insertions. public: friend class ACE_Ordered_MultiSet_Iterator<T>; @@ -1529,95 +1644,103 @@ public: typedef ACE_Ordered_MultiSet_Iterator<T> ITERATOR; // = Initialization and termination methods. + /// Constructor. Use user specified allocation strategy + /// if specified. ACE_Ordered_MultiSet (ACE_Allocator *alloc = 0); - // Constructor. Use user specified allocation strategy - // if specified. + /// Copy constructor. ACE_Ordered_MultiSet (const ACE_Ordered_MultiSet<T> &); - // Copy constructor. + /// Destructor. ~ACE_Ordered_MultiSet (void); - // Destructor. + /// Assignment operator. void operator= (const ACE_Ordered_MultiSet<T> &); - // Assignment operator. // = Check boundary conditions. + /// Returns 1 if the container is empty, otherwise returns 0. int is_empty (void) const; - // Returns 1 if the container is empty, otherwise returns 0. + /// Size of the set. size_t size (void) const; - // Size of the set. // = Classic unordered set operations. + /// Insert <new_item> into the ordered multiset. + /// Returns -1 if failures occur, else 0. int insert (const T &new_item); - // Insert <new_item> into the ordered multiset. - // Returns -1 if failures occur, else 0. + /** + * Insert <new_item> into the ordered multiset, starting its search at + * the node pointed to by the iterator, and if insetion was successful, + * updates the iterator to point to the newly inserted node. + * Returns -1 if failures occur, else 0. + */ int insert (const T &new_item, ITERATOR &iter); - // Insert <new_item> into the ordered multiset, starting its search at - // the node pointed to by the iterator, and if insetion was successful, - // updates the iterator to point to the newly inserted node. - // Returns -1 if failures occur, else 0. + /// Remove first occurrence of <item> from the set. Returns 0 if + /// it removes the item, -1 if it can't find the item. int remove (const T &item); - // Remove first occurrence of <item> from the set. Returns 0 if - // it removes the item, -1 if it can't find the item. + /** + * Finds first occurrance of <item> in the multiset, using the iterator's + * current position as a hint to improve performance. If find succeeds, + * it positions the iterator at that node and returns 0, or if it cannot + * locate the node, it leaves the iterator alone and just returns -1. + */ int find (const T &item, ITERATOR &iter) const; - // Finds first occurrance of <item> in the multiset, using the iterator's - // current position as a hint to improve performance. If find succeeds, - // it positions the iterator at that node and returns 0, or if it cannot - // locate the node, it leaves the iterator alone and just returns -1. + /// Reset the <ACE_Ordered_MultiSet> to be empty. void reset (void); - // Reset the <ACE_Ordered_MultiSet> to be empty. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /** + * Insert <item>, starting its search at the position given, + * and if successful updates the passed pointer to point to + * the newly inserted item's node. + */ int insert_from (const T &item, ACE_DNode<T> *start_position, ACE_DNode<T> **new_position); - // Insert <item>, starting its search at the position given, - // and if successful updates the passed pointer to point to - // the newly inserted item's node. + /** + * looks for first occurance of <item> in the ordered set, using the + * passed starting position as a hint: if there is such an instance, it + * updates the new_position pointer to point to this node and returns 0; + * if there is no such node, then if there is a node before where the + * item would have been, it updates the new_position pointer to point + * to this node and returns -1; if there is no such node, then if there + * is a node after where the item would have been, it updates the + * new_position pointer to point to this node (or 0 if there is no such + * node) and returns 1; + */ int locate (const T &item, ACE_DNode<T> *start_position, ACE_DNode<T> *&new_position) const; - // looks for first occurance of <item> in the ordered set, using the - // passed starting position as a hint: if there is such an instance, it - // updates the new_position pointer to point to this node and returns 0; - // if there is no such node, then if there is a node before where the - // item would have been, it updates the new_position pointer to point - // to this node and returns -1; if there is no such node, then if there - // is a node after where the item would have been, it updates the - // new_position pointer to point to this node (or 0 if there is no such - // node) and returns 1; + /// Delete all the nodes in the Set. void delete_nodes (void); - // Delete all the nodes in the Set. + /// Copy nodes into this set. void copy_nodes (const ACE_Ordered_MultiSet<T> &); - // Copy nodes into this set. + /// Head of the bilinked list of Nodes. ACE_DNode<T> *head_; - // Head of the bilinked list of Nodes. + /// Head of the bilinked list of Nodes. ACE_DNode<T> *tail_; - // Head of the bilinked list of Nodes. + /// Current size of the set. size_t cur_size_; - // Current size of the set. + /// Allocation strategy of the set. ACE_Allocator *allocator_; - // Allocation strategy of the set. }; // **************************************************************** @@ -1625,17 +1748,18 @@ private: // Forward declaration. template <class T> class ACE_Array_Iterator; +/** + * @class ACE_Array_Base + * + * @brief Implement a simple dynamic array + * + * This parametric class implements a simple dynamic array; + * resizing must be controlled by the user. No comparison or find + * operations are implemented. + */ template<class T> class ACE_Array_Base { - // = TITLE - // Implement a simple dynamic array - // - // = DESCRIPTION - // This parametric class implements a simple dynamic array; - // resizing must be controlled by the user. No comparison or find - // operations are implemented. - // public: // Define a "trait" @@ -1644,104 +1768,118 @@ public: // = Initialization and termination methods. + /// Dynamically create an uninitialized array. ACE_Array_Base (size_t size = 0, ACE_Allocator *alloc = 0); - // Dynamically create an uninitialized array. + /// Dynamically initialize the entire array to the <default_value>. ACE_Array_Base (size_t size, const T &default_value, ACE_Allocator *alloc = 0); - // Dynamically initialize the entire array to the <default_value>. + /** + * The copy constructor performs initialization by making an exact + * copy of the contents of parameter <s>, i.e., *this == s will + * return true. + */ ACE_Array_Base (const ACE_Array_Base<T> &s); - // The copy constructor performs initialization by making an exact - // copy of the contents of parameter <s>, i.e., *this == s will - // return true. + /** + * Assignment operator performs an assignment by making an exact + * copy of the contents of parameter <s>, i.e., *this == s will + * return true. Note that if the <max_size_> of <array_> is >= than + * <s.max_size_> we can copy it without reallocating. However, if + * <max_size_> is < <s.max_size_> we must delete the <array_>, + * reallocate a new <array_>, and then copy the contents of <s>. + */ void operator= (const ACE_Array_Base<T> &s); - // Assignment operator performs an assignment by making an exact - // copy of the contents of parameter <s>, i.e., *this == s will - // return true. Note that if the <max_size_> of <array_> is >= than - // <s.max_size_> we can copy it without reallocating. However, if - // <max_size_> is < <s.max_size_> we must delete the <array_>, - // reallocate a new <array_>, and then copy the contents of <s>. + /// Clean up the array (e.g., delete dynamically allocated memory). ~ACE_Array_Base (void); - // Clean up the array (e.g., delete dynamically allocated memory). // = Set/get methods. + /// Set item in the array at location <slot>. Doesn't + /// perform range checking. T &operator [] (size_t slot); - // Set item in the array at location <slot>. Doesn't - // perform range checking. + /// Get item in the array at location <slot>. Doesn't + /// perform range checking. const T &operator [] (size_t slot) const; - // Get item in the array at location <slot>. Doesn't - // perform range checking. + /// Set an item in the array at location <slot>. Returns + /// -1 if <slot> is not in range, else returns 0. int set (const T &new_item, size_t slot); - // Set an item in the array at location <slot>. Returns - // -1 if <slot> is not in range, else returns 0. + /** + * Get an item in the array at location <slot>. Returns -1 if + * <slot> is not in range, else returns 0. Note that this function + * copies the item. If you want to avoid the copy, you can use + * the const operator [], but then you'll be responsible for range checking. + */ int get (T &item, size_t slot) const; - // Get an item in the array at location <slot>. Returns -1 if - // <slot> is not in range, else returns 0. Note that this function - // copies the item. If you want to avoid the copy, you can use - // the const operator [], but then you'll be responsible for range checking. + /// Returns the <cur_size_> of the array. size_t size (void) const; - // Returns the <cur_size_> of the array. + /** + * Changes the size of the array to match <new_size>. + * It copies the old contents into the new array. + * Return -1 on failure. + */ int size (size_t new_size); - // Changes the size of the array to match <new_size>. - // It copies the old contents into the new array. - // Return -1 on failure. + /// Returns the <max_size_> of the array. size_t max_size (void) const; - // Returns the <max_size_> of the array. + /** + * Changes the size of the array to match <new_size>. + * It copies the old contents into the new array. + * Return -1 on failure. + * It does not affect new_size + */ int max_size (size_t new_size); - // Changes the size of the array to match <new_size>. - // It copies the old contents into the new array. - // Return -1 on failure. - // It does not affect new_size private: + /// Returns 1 if <slot> is within range, i.e., 0 >= <slot> < + /// <cur_size_>, else returns 0. int in_range (size_t slot) const; - // Returns 1 if <slot> is within range, i.e., 0 >= <slot> < - // <cur_size_>, else returns 0. + /// Maximum size of the array, i.e., the total number of <T> elements + /// in <array_>. size_t max_size_; - // Maximum size of the array, i.e., the total number of <T> elements - // in <array_>. + /** + * Current size of the array. This starts out being == to + * <max_size_>. However, if we are assigned a smaller array, then + * <cur_size_> will become less than <max_size_>. The purpose of + * keeping track of both sizes is to avoid reallocating memory if we + * don't have to. + */ size_t cur_size_; - // Current size of the array. This starts out being == to - // <max_size_>. However, if we are assigned a smaller array, then - // <cur_size_> will become less than <max_size_>. The purpose of - // keeping track of both sizes is to avoid reallocating memory if we - // don't have to. + /// Pointer to the array's storage buffer. T *array_; - // Pointer to the array's storage buffer. + /// Allocation strategy of the ACE_Array_Base. ACE_Allocator *allocator_; - // Allocation strategy of the ACE_Array_Base. friend class ACE_Array_Iterator<T>; }; // **************************************************************** +/** + * @class ACE_Array + * + * @brief Implement a dynamic array class. + * + * This class extends ACE_Array_Base, it provides comparison + * operators. + */ template <class T> class ACE_Array : public ACE_Array_Base<T> { - // = TITLE - // Implement a dynamic array class. - // - // = DESCRIPTION - // This class extends ACE_Array_Base, it provides comparison - // operators. public: // Define a "trait" typedef T TYPE; @@ -1752,81 +1890,91 @@ public: // = Initialization and termination methods. + /// Dynamically create an uninitialized array. ACE_Array (size_t size = 0, ACE_Allocator* alloc = 0); - // Dynamically create an uninitialized array. + /// Dynamically initialize the entire array to the <default_value>. ACE_Array (size_t size, const T &default_value, ACE_Allocator* alloc = 0); - // Dynamically initialize the entire array to the <default_value>. + /** + * The copy constructor performs initialization by making an exact + * copy of the contents of parameter <s>, i.e., *this == s will + * return true. + */ ACE_Array (const ACE_Array<T> &s); - // The copy constructor performs initialization by making an exact - // copy of the contents of parameter <s>, i.e., *this == s will - // return true. + /** + * Assignment operator performs an assignment by making an exact + * copy of the contents of parameter <s>, i.e., *this == s will + * return true. Note that if the <max_size_> of <array_> is >= than + * <s.max_size_> we can copy it without reallocating. However, if + * <max_size_> is < <s.max_size_> we must delete the <array_>, + * reallocate a new <array_>, and then copy the contents of <s>. + */ void operator= (const ACE_Array<T> &s); - // Assignment operator performs an assignment by making an exact - // copy of the contents of parameter <s>, i.e., *this == s will - // return true. Note that if the <max_size_> of <array_> is >= than - // <s.max_size_> we can copy it without reallocating. However, if - // <max_size_> is < <s.max_size_> we must delete the <array_>, - // reallocate a new <array_>, and then copy the contents of <s>. // = Compare operators + /** + * Compare this array with <s> for equality. Two arrays are equal + * if their <size>'s are equal and all the elements from 0 .. <size> + * are equal. + */ int operator== (const ACE_Array<T> &s) const; - // Compare this array with <s> for equality. Two arrays are equal - // if their <size>'s are equal and all the elements from 0 .. <size> - // are equal. + /** + * Compare this array with <s> for inequality such that <*this> != + * <s> is always the complement of the boolean return value of + * <*this> == <s>. + */ int operator!= (const ACE_Array<T> &s) const; - // Compare this array with <s> for inequality such that <*this> != - // <s> is always the complement of the boolean return value of - // <*this> == <s>. }; +/** + * @class ACE_Array_Iterator + * + * @brief Implement an iterator over an ACE_Array. + * + * This iterator is safe in the face of array element deletions. + * But it is NOT safe if the array is resized (via the ACE_Array + * assignment operator) during iteration. That would be very + * odd, and dangerous. + */ template <class T> class ACE_Array_Iterator { - // = TITLE - // Implement an iterator over an ACE_Array. - // - // = DESCRIPTION - // This iterator is safe in the face of array element deletions. - // But it is NOT safe if the array is resized (via the ACE_Array - // assignment operator) during iteration. That would be very - // odd, and dangerous. public: // = Initialization method. ACE_Array_Iterator (ACE_Array_Base<T> &); // = Iteration methods. + /// Pass back the <next_item> that hasn't been seen in the Array. + /// Returns 0 when all items have been seen, else 1. int next (T *&next_item); - // Pass back the <next_item> that hasn't been seen in the Array. - // Returns 0 when all items have been seen, else 1. + /// Move forward by one element in the Array. Returns 0 when all the + /// items in the Array have been seen, else 1. int advance (void); - // Move forward by one element in the Array. Returns 0 when all the - // items in the Array have been seen, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to the current item in the iteration. u_int current_; - // Pointer to the current item in the iteration. + /// Pointer to the Array we're iterating over. ACE_Array_Base<T> &array_; - // Pointer to the Array we're iterating over. }; #if defined (__ACE_INLINE__) diff --git a/ace/DEV.h b/ace/DEV.h index 7dea7fed39f..46213ececdf 100644 --- a/ace/DEV.h +++ b/ace/DEV.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// DEV.h -// -// = AUTHOR -// Gerhard Lenzer -// -// ============================================================================ +//============================================================================= +/** + * @file DEV.h + * + * $Id$ + * + * @author Gerhard Lenzer + */ +//============================================================================= + #ifndef ACE_DEV_H #define ACE_DEV_H @@ -39,29 +36,34 @@ #define ACE_DEV_STREAM ACE_DEV_Stream, ACE_DEV_Addr #endif /* ACE_TEMPLATE_TYPEDEFS */ +/** + * @class ACE_DEV + * + * @brief Defines the member functions for the base class of the + * ACE_DEV abstraction. + */ class ACE_Export ACE_DEV : public ACE_IO_SAP { - // = TITLE - // Defines the member functions for the base class of the - // ACE_DEV abstraction. public: + /// Close down the DEVICE int close (void); - // Close down the DEVICE + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /** + * Disable signal <signum> + * This is here to prevent Win32 from + * disabling SPIPE using socket calls + */ int disable (int signum) const ; - // Disable signal <signum> - // This is here to prevent Win32 from - // disabling SPIPE using socket calls protected: + /// Ensure that this class is an abstract base class ACE_DEV (void); - // Ensure that this class is an abstract base class }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/DEV_Addr.h b/ace/DEV_Addr.h index 1e2ba1609ae..a270004ea31 100644 --- a/ace/DEV_Addr.h +++ b/ace/DEV_Addr.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// DEV_Addr.h -// -// = AUTHOR -// Gerhard Lenzer and Douglas C. Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file DEV_Addr.h + * + * $Id$ + * + * @author Gerhard Lenzer and Douglas C. Schmidt + */ +//============================================================================= + #ifndef ACE_DEV_ADDR_H #define ACE_DEV_ADDR_H @@ -26,54 +23,57 @@ #include "ace/ACE.h" +/** + * @class ACE_DEV_Addr + * + * @brief Defines device address family address format. + */ class ACE_Export ACE_DEV_Addr : public ACE_Addr { - // = TITLE - // Defines device address family address format. public: // = Initialization methods. + /// Default constructor. ACE_DEV_Addr (void); - // Default constructor. + /// Copy constructor. ACE_DEV_Addr (const ACE_DEV_Addr &sa); - // Copy constructor. + /// Acts like a copy constructor. int set (const ACE_DEV_Addr &sa); - // Acts like a copy constructor. + /// Create a ACE_DEV_Addr from a device name. ACE_EXPLICIT ACE_DEV_Addr (const ACE_TCHAR *devname); - // Create a ACE_DEV_Addr from a device name. + /// Create a ACE_Addr from a ACE_DEV pathname. void set (const ACE_TCHAR *devname); - // Create a ACE_Addr from a ACE_DEV pathname. + /// Assignment operator. ACE_DEV_Addr &operator= (const ACE_DEV_Addr &); - // Assignment operator. + /// Return a pointer to the address. virtual void *get_addr (void) const; - // Return a pointer to the address. + /// Transform the current address into string format. virtual int addr_to_string (ACE_TCHAR *addr, size_t) const; - // Transform the current address into string format. + /// Compare two addresses for equality. int operator == (const ACE_DEV_Addr &SAP) const; - // Compare two addresses for equality. + /// Compare two addresses for inequality. int operator != (const ACE_DEV_Addr &SAP) const; - // Compare two addresses for inequality. + /// Return the path name used for the rendezvous point. const ACE_TCHAR *get_path_name (void) const; - // Return the path name used for the rendezvous point. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Name of the device. ACE_TCHAR devname_[MAXNAMLEN + 1]; - // Name of the device. }; #if defined (__ACE_INLINE__) diff --git a/ace/DEV_Connector.h b/ace/DEV_Connector.h index bd2c7ad93ab..83aafe6fe83 100644 --- a/ace/DEV_Connector.h +++ b/ace/DEV_Connector.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// DEV_Connector.h -// -// = AUTHOR -// Gerhard Lenzer and Douglas C. Schmidt -// -// ============================================================================ +//============================================================================= +/** + * @file DEV_Connector.h + * + * $Id$ + * + * @author Gerhard Lenzer and Douglas C. Schmidt + */ +//============================================================================= + #ifndef ACE_DEV_CONNECTOR_H #define ACE_DEV_CONNECTOR_H @@ -25,14 +22,34 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ -class ACE_Export ACE_DEV_Connector +/** + * @class ACE_DEV_Connector + * + * @brief Defines an active connection factory for the ACE_DEV wrappers. + */ +class ACE_Export ACE_DEV_Connector { - // = TITLE - // Defines an active connection factory for the ACE_DEV wrappers. public: + /// Default constructor. ACE_DEV_Connector (void); - // Default constructor. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + * The <flags> and <perms> arguments are passed down to the <open> + * method. + */ ACE_DEV_Connector (ACE_DEV_IO &new_io, const ACE_DEV_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -40,22 +57,24 @@ public: int reuse_addr = 0, int flags = O_RDWR, int perms = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. - // The <flags> and <perms> arguments are passed down to the <open> - // method. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + * The <flags> and <perms> arguments are passed down to the <open> + * method. + */ int connect (ACE_DEV_IO &new_io, const ACE_DEV_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -63,30 +82,15 @@ public: int reuse_addr = 0, int flags = O_RDWR, int perms = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. - // The <flags> and <perms> arguments are passed down to the <open> - // method. + /// Resets any event associations on this handle int reset_new_handle (ACE_HANDLE handle); - // Resets any event associations on this handle + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. // = Meta-type info typedef ACE_DEV_Addr PEER_ADDR; diff --git a/ace/DEV_IO.h b/ace/DEV_IO.h index 85410750b01..3e5ed037bbf 100644 --- a/ace/DEV_IO.h +++ b/ace/DEV_IO.h @@ -1,18 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// DEV_IO.h -// -// = AUTHOR -// Gerhard Lenzer and Douglas C. Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file DEV_IO.h + * + * $Id$ + * + * @author Gerhard Lenzer + @ @author Douglas C. Schmidt + */ +//============================================================================= + #ifndef ACE_DEV_IO_H #define ACE_DEV_IO_H @@ -26,99 +24,106 @@ #include "ace/DEV_Addr.h" +/** + * @class ACE_DEV_IO + * + * @brief Read/Write operations on Devices. + */ class ACE_Export ACE_DEV_IO : public ACE_DEV { - // = TITLE - // Read/Write operations on Devices. public: friend class ACE_DEV_Connector; + /// Default constructor. ACE_DEV_IO (void); - // Default constructor. // = Various send operations. + /// send upto <n> bytes in <buf>. ssize_t send (const void *buf, size_t n) const; - // send upto <n> bytes in <buf>. + /// Recv upto <n> bytes in <buf>. ssize_t recv (void *buf, size_t n) const; - // Recv upto <n> bytes in <buf>. + /// Send n bytes, keep trying until n are sent. ssize_t send_n (const void *buf, size_t n) const; - // Send n bytes, keep trying until n are sent. + /// Recv n bytes, keep trying until n are received. ssize_t recv_n (void *buf, size_t n) const; - // Recv n bytes, keep trying until n are received. #if defined (ACE_HAS_STREAM_PIPES) + /// Recv bytes via STREAM pipes using "band" mode. ssize_t recv (ACE_Str_Buf *cntl, ACE_Str_Buf *data, int *band, int *flags) const; - // Recv bytes via STREAM pipes using "band" mode. + /// Send bytes via STREAM pipes using "band" mode. ssize_t send (const ACE_Str_Buf *cntl, const ACE_Str_Buf *data, int band, int flags) const; - // Send bytes via STREAM pipes using "band" mode. + /// Recv <cntl> and <data> via STREAM pipes. ssize_t recv (ACE_Str_Buf *cntl, ACE_Str_Buf *data, int *flags) const; - // Recv <cntl> and <data> via STREAM pipes. + /// Send <cntl> and <data> via STREAM pipes. ssize_t send (const ACE_Str_Buf *cntl, const ACE_Str_Buf *data, int flags = 0) const; - // Send <cntl> and <data> via STREAM pipes. #endif /* ACE_HAS_STREAM_PIPES */ + /// Send iovecs via <::writev>. ssize_t send (const iovec iov[], size_t n) const; - // Send iovecs via <::writev>. + /// Recv iovecs via <::readv>. ssize_t recv (iovec iov[], size_t n) const; - // Recv iovecs via <::readv>. + /** + * Send N char *ptrs and int lengths. Note that the char *'s + * precede the ints (basically, an varargs version of writev). The + * count N is the *total* number of trailing arguments, *not* a + * couple of the number of tuple pairs! + */ ssize_t send (size_t n, ...) const; - // Send N char *ptrs and int lengths. Note that the char *'s - // precede the ints (basically, an varargs version of writev). The - // count N is the *total* number of trailing arguments, *not* a - // couple of the number of tuple pairs! + /** + * This is an interface to ::readv, that doesn't use the struct + * iovec explicitly. The ... can be passed as an arbitrary number + * of (char *ptr, int len) tuples. However, the count N is the + * *total* number of trailing arguments, *not* a couple of the + * number of tuple pairs! + */ ssize_t recv (size_t n, ...) const; - // This is an interface to ::readv, that doesn't use the struct - // iovec explicitly. The ... can be passed as an arbitrary number - // of (char *ptr, int len) tuples. However, the count N is the - // *total* number of trailing arguments, *not* a couple of the - // number of tuple pairs! + /// Send <n> bytes via Win32 WriteFile using overlapped I/O. ssize_t send (const void *buf, size_t n, ACE_OVERLAPPED *overlapped) const; - // Send <n> bytes via Win32 WriteFile using overlapped I/O. + /// Recv <n> bytes via Win32 ReadFile using overlapped I/O. ssize_t recv (void *buf, size_t n, ACE_OVERLAPPED *overlapped) const; - // Recv <n> bytes via Win32 ReadFile using overlapped I/O. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = The following two methods are no-ops to keep the // <ACE_Connector> happy. + /// Return the local endpoint address. int get_local_addr (ACE_DEV_Addr &) const; - // Return the local endpoint address. + /// Return the address of the remotely connected peer (if there is + /// one). int get_remote_addr (ACE_DEV_Addr &) const; - // Return the address of the remotely connected peer (if there is - // one). + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. // = Meta-type info typedef ACE_DEV_Addr PEER_ADDR; private: + /// Address of device we are connected to. ACE_DEV_Addr addr_; - // Address of device we are connected to. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/DLL.h b/ace/DLL.h index e1cbe76f70d..2a870fa08c1 100644 --- a/ace/DLL.h +++ b/ace/DLL.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// DLL.h -// -// = AUTHOR -// Kirthika Parameswaran <kirthika@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file DLL.h + * + * $Id$ + * + * @author Kirthika Parameswaran <kirthika@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_DLL_H #define ACE_DLL_H @@ -24,80 +21,90 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_DLL + * + * @brief Provides an abstract interface for handling various DLL + * operations. + * + * This class is an wrapper over the various methods for utilizing + * a dynamically linked library (DLL), which is called a shared + * library on some platforms. Operations <open>, <close>, and + * <symbol> have been implemented to help opening/closing and + * extracting symbol information from a DLL, respectively. + */ class ACE_Export ACE_DLL { - // = TITLE - // Provides an abstract interface for handling various DLL - // operations. - // - // = DESCRIPTION - // This class is an wrapper over the various methods for utilizing - // a dynamically linked library (DLL), which is called a shared - // library on some platforms. Operations <open>, <close>, and - // <symbol> have been implemented to help opening/closing and - // extracting symbol information from a DLL, respectively. public: // = Initialization and termination methods. + /// Default constructor. By default, the <close> operation on the + /// object will be invoked before it is destroyed. ACE_DLL (int close_on_destruction = 1); - // Default constructor. By default, the <close> operation on the - // object will be invoked before it is destroyed. + /** + * This constructor opens and dynamically links <dll_name>. The + * default mode is <RTLD_LAZY>, which loads identifier symbols but + * not the symbols for functions, which are loaded dynamically + * on-demand. Other supported modes include: <RTLD_NOW>, which + * performs all necessary relocations when <dll_name> is first + * loaded and <RTLD_GLOBAL>, which makes symbols available for + * relocation processing of any other DLLs. + */ ACE_DLL (const ACE_TCHAR *dll_name, int open_mode = ACE_DEFAULT_SHLIB_MODE, int close_on_destruction = 1); - // This constructor opens and dynamically links <dll_name>. The - // default mode is <RTLD_LAZY>, which loads identifier symbols but - // not the symbols for functions, which are loaded dynamically - // on-demand. Other supported modes include: <RTLD_NOW>, which - // performs all necessary relocations when <dll_name> is first - // loaded and <RTLD_GLOBAL>, which makes symbols available for - // relocation processing of any other DLLs. + /** + * This method opens and dynamically links <dll_name>. The default + * mode is <RTLD_LAZY>, which loads identifier symbols but not the + * symbols for functions, which are loaded dynamically on-demand. + * Other supported modes include: <RTLD_NOW>, which performs all + * necessary relocations when <dll_name> is first loaded and + * <RTLD_GLOBAL>, which makes symbols available for relocation + * processing of any other DLLs. Returns -1 on failure and 0 on + * success. + */ int open (const ACE_TCHAR *dll_name, int open_mode = ACE_DEFAULT_SHLIB_MODE, int close_on_destruction = 1); - // This method opens and dynamically links <dll_name>. The default - // mode is <RTLD_LAZY>, which loads identifier symbols but not the - // symbols for functions, which are loaded dynamically on-demand. - // Other supported modes include: <RTLD_NOW>, which performs all - // necessary relocations when <dll_name> is first loaded and - // <RTLD_GLOBAL>, which makes symbols available for relocation - // processing of any other DLLs. Returns -1 on failure and 0 on - // success. + /// Call to close the DLL object. int close (void); - // Call to close the DLL object. + /** + * Called when the DLL object is destroyed -- invokes <close> if the + * <close_on_destruction> flag is set in the constructor or <open> + * method. + */ ~ACE_DLL (void); - // Called when the DLL object is destroyed -- invokes <close> if the - // <close_on_destruction> flag is set in the constructor or <open> - // method. + /// If <symbol_name> is in the symbol table of the DLL a pointer to + /// the <symbol_name> is returned. Otherwise, returns 0. void *symbol (const ACE_TCHAR *symbol_name); - // If <symbol_name> is in the symbol table of the DLL a pointer to - // the <symbol_name> is returned. Otherwise, returns 0. + /// Returns a pointer to a string explaining why <symbol> or <open> + /// failed. ACE_TCHAR *error (void); - // Returns a pointer to a string explaining why <symbol> or <open> - // failed. + /** + * Return the handle to the caller. If <become_owner> is non-0 then + * caller assumes ownership of the handle and the <ACE_DLL> object + * won't call <close> when it goes out of scope, even if + * <close_on_destruction> is set. + */ ACE_SHLIB_HANDLE get_handle (int become_owner = 0); - // Return the handle to the caller. If <become_owner> is non-0 then - // caller assumes ownership of the handle and the <ACE_DLL> object - // won't call <close> when it goes out of scope, even if - // <close_on_destruction> is set. + /// Set the handle for the DLL object. By default, the <close> operation on the + /// object will be invoked before it is destroyed. int set_handle (ACE_SHLIB_HANDLE handle, int close_on_destruction = 1); - // Set the handle for the DLL object. By default, the <close> operation on the - // object will be invoked before it is destroyed. private: + /// This is a handle to the DLL. ACE_SHLIB_HANDLE handle_; - // This is a handle to the DLL. + /// This flag keeps track of whether we should close the handle + /// automatically when the destructor runs. int close_on_destruction_; - // This flag keeps track of whether we should close the handle - // automatically when the destructor runs. // = Disallow copying and assignment since we don't handle these. ACE_UNIMPLEMENTED_FUNC (ACE_DLL (const ACE_DLL &)) diff --git a/ace/Date_Time.h b/ace/Date_Time.h index 7f3ff51f57b..c7eba7452a4 100644 --- a/ace/Date_Time.h +++ b/ace/Date_Time.h @@ -1,20 +1,18 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ACE_Date_Time.h -// -// = AUTHOR -// Tim Harrison (harrison@cs.wustl.edu) (and he's darn proud of -// this ;-)) -// Well he shouldn't be, no const accessors, tsck, tsck, tsck ;-) -// -// ============================================================================ + +//============================================================================= +/** + * @file ACE_Date_Time.h + * + * $Id$ + * + * @author Tim Harrison (harrison@cs.wustl.edu) (and he's darn proud + of this ;-)) + + * Well he shouldn't be no const accessors tsck tsck tsck ;-) + */ +//============================================================================= + #ifndef ACE_DATE_TIME_H #define ACE_DATE_TIME_H @@ -26,12 +24,16 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Date_Time + * + * @brief System independent representation of date and time. + */ class ACE_Export ACE_Date_Time { - // = TITLE - // System independent representation of date and time. public: // constructor with init values, no check for validy + /// Set/get portions of ACE_Date_Time, no check for validity. ACE_Date_Time (long day = 0, long month = 0, long year = 0, @@ -39,49 +41,48 @@ public: long minute = 0, long second = 0, long microsec = 0); - // Set/get portions of ACE_Date_Time, no check for validity. + /// Get day. long day (void) const; - // Get day. + /// Set day. void day (long day); - // Set day. + /// Get month. long month (void) const; - // Get month. + /// Set month. void month (long month); - // Set month. + /// Get year. long year (void) const; - // Get year. + /// Set year. void year (long year); - // Set year. + /// Get hour. long hour (void) const; - // Get hour. + /// Set hour. void hour (long hour); - // Set hour. + /// Get minute. long minute (void) const; - // Get minute. + /// Set minute. void minute (long minute); - // Set minute. + /// Get second. long second (void) const; - // Get second. + /// Set second. void second (long second); - // Set second. + /// Get microsec. long microsec (void) const; - // Get microsec. + /// Set microsec. void microsec (long microsec); - // Set microsec. private: long day_; diff --git a/ace/Dirent.h b/ace/Dirent.h index 5dc59c63ae0..d4d09845f44 100644 --- a/ace/Dirent.h +++ b/ace/Dirent.h @@ -1,21 +1,18 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Dirent.h -// -// = DESCRIPTION -// Define a portable directory-entry manipulation interface. -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Dirent.h + * + * $Id$ + * + * Define a portable directory-entry manipulation interface. + * + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_DIRENT_H #define ACE_DIRENT_H @@ -27,78 +24,89 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Dirent + * + * @brief Define a portable UNIX directory-entry iterator. + */ class ACE_Export ACE_Dirent { - // = TITLE - // Define a portable UNIX directory-entry iterator. public: // = Initialization and termination methods. + /// Default constructor. ACE_Dirent (void); - // Default constructor. + /// Constructor calls <opendir> ACE_EXPLICIT ACE_Dirent (const ACE_TCHAR *dirname); - // Constructor calls <opendir> + /// Opens the directory named by filename and associates a directory + /// stream with it. int open (const ACE_TCHAR *filename); - // Opens the directory named by filename and associates a directory - // stream with it. + /// Destructor calls <closedir>. ~ACE_Dirent (void); - // Destructor calls <closedir>. + /// Closes the directory stream and frees the DIR structure. void close (void); - // Closes the directory stream and frees the DIR structure. // = Iterator methods. + /** + * Returns a pointer to a structure representing the directory entry + * at the current position in the directory stream to which dirp + * refers, and positions the directory stream at the next entry, + * except on read-only filesystems. It returns a NULL pointer upon + * reaching the end of the directory stream, or upon detecting an + * invalid location in the directory. <readdir> shall not return + * directory entries containing empty names. It is unspecified + * whether entries are returned for dot or dot-dot. The pointer + * returned by <readdir> points to data that may be overwritten by + * another call to <readdir> on the same directory stream. This + * data shall not be overwritten by another call to <readdir> on a + * different directory stream. <readdir> may buffer several + * directory entries per actual read operation; <readdir> marks for + * update the st_atime field of the directory each time the + * directory is actually read. + */ dirent *read (void); - // Returns a pointer to a structure representing the directory entry - // at the current position in the directory stream to which dirp - // refers, and positions the directory stream at the next entry, - // except on read-only filesystems. It returns a NULL pointer upon - // reaching the end of the directory stream, or upon detecting an - // invalid location in the directory. <readdir> shall not return - // directory entries containing empty names. It is unspecified - // whether entries are returned for dot or dot-dot. The pointer - // returned by <readdir> points to data that may be overwritten by - // another call to <readdir> on the same directory stream. This - // data shall not be overwritten by another call to <readdir> on a - // different directory stream. <readdir> may buffer several - // directory entries per actual read operation; <readdir> marks for - // update the st_atime field of the directory each time the - // directory is actually read. + /** + * Has the equivalent functionality as <readdir> except that an + * <entry> and <result> buffer must be supplied by the caller to + * store the result. + */ int read (struct dirent *entry, struct dirent **result); - // Has the equivalent functionality as <readdir> except that an - // <entry> and <result> buffer must be supplied by the caller to - // store the result. // = Manipulators. + /// Returns the current location associated with the directory + /// stream. long tell (void); - // Returns the current location associated with the directory - // stream. + /** + * Sets the position of the next <readdir> operation on the + * directory stream. The new position reverts to the position + * associated with the directory stream at the time the <telldir> + * operation that provides loc was performed. Values returned by + * <telldir> are good only for the lifetime of the DIR pointer from + * which they are derived. If the directory is closed and then + * reopened, the <telldir> value may be invalidated due to + * undetected directory compaction. It is safe to use a previous + * <telldir> value immediately after a call to <opendir> and before + * any calls to readdir. + */ void seek (long loc); - // Sets the position of the next <readdir> operation on the - // directory stream. The new position reverts to the position - // associated with the directory stream at the time the <telldir> - // operation that provides loc was performed. Values returned by - // <telldir> are good only for the lifetime of the DIR pointer from - // which they are derived. If the directory is closed and then - // reopened, the <telldir> value may be invalidated due to - // undetected directory compaction. It is safe to use a previous - // <telldir> value immediately after a call to <opendir> and before - // any calls to readdir. + /** + * Resets the position of the directory stream to the beginning of + * the directory. It also causes the directory stream to refer to + * the current state of the corresponding directory, as a call to + * <opendir> would. + */ void rewind (void); - // Resets the position of the directory stream to the beginning of - // the directory. It also causes the directory stream to refer to - // the current state of the corresponding directory, as a call to - // <opendir> would. private: + /// Pointer to the directory stream. DIR *dirp_; - // Pointer to the directory stream. }; #if defined (__ACE_INLINE__) diff --git a/ace/Dump.h b/ace/Dump.h index 5c1ea0f357d..742e2c649e9 100644 --- a/ace/Dump.h +++ b/ace/Dump.h @@ -1,52 +1,49 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Dump.h -// -// = DESCRIPTION -// -// A prototype mechanism that allow all ACE objects to be registered -// with a central in-memory "database" that can dump the state of all -// live ACE objects (e.g., from within a debugger). -// -// To turn on this feature simply compile with -DACE_NDEBUG -// -// There are several interesting aspects to this design: -// -// 1. It uses the External Polymorphism pattern to avoid having to -// derive all ACE classes from a common base class that has virtual -// methods (this is crucial to avoid unnecessary overhead). In -// addition, there is no additional space added to ACE objects -// (this is crucial to maintain binary layout compatibility). -// -// 2. This mechanism can be conditionally compiled in order to -// completely disable this feature entirely. Moreover, by -// using macros there are relatively few changes to ACE code. -// -// 3. This mechanism copes with single-inheritance hierarchies of -// dumpable classes. In such cases we typically want only one -// dump, corresponding to the most derived instance. Thanks to -// Christian Millour (chris@etca.fr) for illustrating how to do -// this. Note, however, that this scheme doesn't generalize to -// work with multiple-inheritance or virtual base classes. -// -// Future work includes: -// -// 1. Using a dynamic object table rather than a static table -// -// 2. Adding support to allow particular classes of objects to -// be selectively dumped. -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Dump.h + * + * $Id$ + * + * + * A prototype mechanism that allow all ACE objects to be registered + * with a central in-memory "database" that can dump the state of all + * live ACE objects (e.g., from within a debugger). + * + * To turn on this feature simply compile with -DACE_NDEBUG + * + * There are several interesting aspects to this design: + * + * 1. It uses the External Polymorphism pattern to avoid having to + * derive all ACE classes from a common base class that has virtual + * methods (this is crucial to avoid unnecessary overhead). In + * addition, there is no additional space added to ACE objects + * (this is crucial to maintain binary layout compatibility). + * + * 2. This mechanism can be conditionally compiled in order to + * completely disable this feature entirely. Moreover, by + * using macros there are relatively few changes to ACE code. + * + * 3. This mechanism copes with single-inheritance hierarchies of + * dumpable classes. In such cases we typically want only one + * dump, corresponding to the most derived instance. Thanks to + * Christian Millour (chris@etca.fr) for illustrating how to do + * this. Note, however, that this scheme doesn't generalize to + * work with multiple-inheritance or virtual base classes. + * + * Future work includes: + * + * 1. Using a dynamic object table rather than a static table + * + * 2. Adding support to allow particular classes of objects to + * be selectively dumped. + * + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_DUMP_H #define ACE_DUMP_H @@ -58,66 +55,76 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Dumpable + * + * @brief Base class that defines a uniform interface for all object + * dumping. + */ class ACE_Export ACE_Dumpable { - // = TITLE - // Base class that defines a uniform interface for all object - // dumping. public: friend class ACE_ODB; friend class ACE_Dumpable_Ptr; + /// Constructor. ACE_Dumpable (const void *); - // Constructor. + /// This pure virtual method must be filled in by a subclass. virtual void dump (void) const = 0; - // This pure virtual method must be filled in by a subclass. protected: virtual ~ACE_Dumpable (void); private: + /// Pointer to the object that is being stored. const void *this_; - // Pointer to the object that is being stored. }; +/** + * @class ACE_Dumpable_Ptr + * + * @brief A smart pointer stored in the in-memory object database + * ACE_ODB. The pointee (if any) is deleted when reassigned. + */ class ACE_Export ACE_Dumpable_Ptr { - // = TITLE - // A smart pointer stored in the in-memory object database - // ACE_ODB. The pointee (if any) is deleted when reassigned. public: ACE_Dumpable_Ptr (const ACE_Dumpable *dumper = 0); const ACE_Dumpable *operator->() const; void operator= (const ACE_Dumpable *dumper) const; private: + /// "Real" pointer to the underlying abstract base class + /// pointer that does the real work. const ACE_Dumpable *dumper_; - // "Real" pointer to the underlying abstract base class - // pointer that does the real work. }; +/** + * @class ACE_ODB + * + * @brief This is the object database (ODB) that keeps track of all + * live ACE objects. + */ class ACE_Export ACE_ODB { - // = TITLE - // This is the object database (ODB) that keeps track of all - // live ACE objects. public: - enum {MAX_TABLE_SIZE = 100000}; // This is clearly inadequate and should be dynamic... + /// @todo This is clearly inadequate and should be dynamic... + enum {MAX_TABLE_SIZE = 100000}; + /// Iterates through the entire set of registered objects and + /// dumps their state. void dump_objects (void); - // Iterates through the entire set of registered objects and - // dumps their state. + /// Add the tuple <dumper, this_> to the list of registered ACE objects. void register_object (const ACE_Dumpable *dumper); - // Add the tuple <dumper, this_> to the list of registered ACE objects. + /// Use <this_> to locate and remove the associated <dumper> from the + /// list of registered ACE objects. void remove_object (const void *this_); - // Use <this_> to locate and remove the associated <dumper> from the - // list of registered ACE objects. + /// Interface to the Singleton instance of the object database. static ACE_ODB *instance (void); - // Interface to the Singleton instance of the object database. private: ACE_ODB (void); // Ensure we have a Singleton... @@ -140,15 +147,15 @@ private: Tuple (void) : dumper_(0) {} }; + /// Singleton instance of this class. static ACE_ODB *instance_; - // Singleton instance of this class. + /// The current implementation is very simple-minded and will be + /// changed to be dynamic. Tuple object_table_[ACE_ODB::MAX_TABLE_SIZE]; - // The current implementation is very simple-minded and will be - // changed to be dynamic. + /// Current size of <object_table_>. int current_size_; - // Current size of <object_table_>. }; // Include the templates classes at this point. diff --git a/ace/Dump_T.h b/ace/Dump_T.h index 88b2765f721..f9856353797 100644 --- a/ace/Dump_T.h +++ b/ace/Dump_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Dump.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ +//============================================================================= +/** + * @file Dump.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_DUMP_T_H #define ACE_DUMP_T_H @@ -24,34 +21,36 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Dumpable_Adapter + * + * @brief This class inherits the interface of the abstract ACE_Dumpable + * class and is instantiated with the implementation of the + * concrete component class <class Concrete>. + * + * This design is similar to the Adapter and Decorator patterns + * from the ``Gang of Four'' book. Note that <class Concrete> + * need not inherit from a common class since ACE_Dumpable + * provides the uniform virtual interface! + */ template <class Concrete> class ACE_Dumpable_Adapter : public ACE_Dumpable { - // = TITLE - // This class inherits the interface of the abstract ACE_Dumpable - // class and is instantiated with the implementation of the - // concrete component class <class Concrete>. - // - // = DESCRIPTION - // This design is similar to the Adapter and Decorator patterns - // from the ``Gang of Four'' book. Note that <class Concrete> - // need not inherit from a common class since ACE_Dumpable - // provides the uniform virtual interface! public: // = Initialization and termination methods. ACE_Dumpable_Adapter (const Concrete *t); ~ACE_Dumpable_Adapter (void); + /// Concrete dump method (simply delegates to the <dump> method of + /// <class Concrete>). virtual void dump (void) const; - // Concrete dump method (simply delegates to the <dump> method of - // <class Concrete>). + /// Delegate to methods in the Concrete class. Concrete *operator->() const; - // Delegate to methods in the Concrete class. private: + /// Pointer to <this> of <class Concrete>. const Concrete *this_; - // Pointer to <this> of <class Concrete>. }; // Some useful macros for conditionally compiling this feature... diff --git a/ace/Dynamic.h b/ace/Dynamic.h index 3d16a9a8ca7..1e7bea317b2 100644 --- a/ace/Dynamic.h +++ b/ace/Dynamic.h @@ -1,18 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Dynamic.h -// -// = AUTHOR -// Doug Schmidt and Irfan Pyrarli. -// -// ============================================================================ +//============================================================================= +/** + * @file Dynamic.h + * + * $Id$ + * + * @author Doug Schmidt + * @author Irfan Pyarali. + */ +//============================================================================= + #ifndef ACE_DYNAMIC_H #define ACE_DYNAMIC_H @@ -27,40 +25,46 @@ #include "ace/Synch_T.h" #include "ace/Singleton.h" +/** + * @class ACE_Dynamic + * + * @brief Checks to see if an object was dynamically allocated. + * + * This class holds the pointer in a thread-safe manner between + * the call to operator new and the call to the constructor. + */ class ACE_Export ACE_Dynamic { - // = TITLE - // Checks to see if an object was dynamically allocated. - // - // = DESCRIPTION - // This class holds the pointer in a thread-safe manner between - // the call to operator new and the call to the constructor. public: // = Initialization and termination method. + /// Constructor. ACE_Dynamic (void); - // Constructor. + /// Destructor. ~ACE_Dynamic (void); - // Destructor. + /** + * Sets a flag that indicates that the object was dynamically + * created. This method is usually called in operator new and then + * checked and reset in the constructor. + */ void set (void); - // Sets a flag that indicates that the object was dynamically - // created. This method is usually called in operator new and then - // checked and reset in the constructor. + /// 1 if we were allocated dynamically, else 0. int is_dynamic (void); - // 1 if we were allocated dynamically, else 0. + /// Resets state flag. void reset (void); - // Resets state flag. static ACE_Dynamic *instance (void); private: + /** + * Flag that indicates that the object was dynamically created. This + * method is usually called in operator new and then checked and + * reset in the constructor. + */ int is_dynamic_; - // Flag that indicates that the object was dynamically created. This - // method is usually called in operator new and then checked and - // reset in the constructor. }; #if defined (__ACE_INLINE__) diff --git a/ace/Dynamic_Service.h b/ace/Dynamic_Service.h index b06f73b2ec3..6411c1eb790 100644 --- a/ace/Dynamic_Service.h +++ b/ace/Dynamic_Service.h @@ -1,18 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Dynamic_Service.h -// -// = AUTHOR -// Prashant Jain, Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Dynamic_Service.h + * + * $Id$ + * + * @author Prashant Jain + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_DYNAMIC_SERVICE_H #define ACE_DYNAMIC_SERVICE_H @@ -20,22 +18,24 @@ #include "ace/OS.h" +/** + * @class ACE_Dynamic_Service + * + * @brief Provides a general interface to retrieve arbitrary objects + * from the ACE service repository. + * + * Uses "name" for lookup in the ACE service repository. Obtains + * the object and returns it as the appropriate type. + */ template <class SERVICE> class ACE_Dynamic_Service { - // = TITLE - // Provides a general interface to retrieve arbitrary objects - // from the ACE service repository. - // - // = DESCRIPTION - // Uses "name" for lookup in the ACE service repository. Obtains - // the object and returns it as the appropriate type. public: + /// Return instance using <name> to search the Service_Repository. static SERVICE *instance (const ACE_TCHAR *name); - // Return instance using <name> to search the Service_Repository. + /// Dump the current state of the object. void dump (void) const; - // Dump the current state of the object. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/Env_Value_T.h b/ace/Env_Value_T.h index 0005d734c1f..c38e5deac86 100644 --- a/ace/Env_Value_T.h +++ b/ace/Env_Value_T.h @@ -1,19 +1,19 @@ /* This may look like C, but it's really -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = DESCRIPTION -// Template to encapsulate getting a value from an environment variable -// and using a supplied default value if not in the environment. -// -// = AUTHOR -// Chris Cleeland (derived from work by Carlos O'Ryan) -// -// ============================================================================ + +//============================================================================= +/** + * @file Env_Value_T.h + * + * $Id$ + * + * Template to encapsulate getting a value from an environment variable + * and using a supplied default value if not in the environment. + * + * + * @author Chris Cleeland (derived from work by Carlos O'Ryan) + */ +//============================================================================= + #ifndef ACE_ENV_VALUE_T_H #define ACE_ENV_VALUE_T_H @@ -25,45 +25,48 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Env_Value + * + * @brief Enviroment Variable Value + * + * Reads a variable from the user enviroment, providing a default + * value. + * = AUTHOR + * Chris Cleeland, Carlos O'Ryan + */ template <class T> class ACE_Env_Value { - // = TITLE - // Enviroment Variable Value - // - // = DESCRIPTION - // Reads a variable from the user enviroment, providing a default - // value. - // - // = AUTHOR - // Chris Cleeland, Carlos O'Ryan public: + /** + * Default constructor which isn't bound to a specific environment + * variable name or a default value. Before being useful it must + * <open>'d. + */ ACE_Env_Value (void); - // Default constructor which isn't bound to a specific environment - // variable name or a default value. Before being useful it must - // <open>'d. + /// Constructor that calls <open>. ACE_Env_Value (const ACE_TCHAR *varname, const T &vardefault); - // Constructor that calls <open>. + /// Destroy the value. ~ACE_Env_Value (void); - // Destroy the value. + /// Returns the value as type T. operator T (void); - // Returns the value as type T. + /// The constructor, read <varname> from the enviroment, using + /// <vardefault> as its value if it is not defined. void open (const ACE_TCHAR *varname, const T &defval); - // The constructor, read <varname> from the enviroment, using - // <vardefault> as its value if it is not defined. + /// Returns the name of the variable being tracked. const ACE_TCHAR *varname (void) const; - // Returns the name of the variable being tracked. private: + /// Disallow copying and assignment. ACE_UNIMPLEMENTED_FUNC (ACE_Env_Value(const ACE_Env_Value<T> &)) ACE_UNIMPLEMENTED_FUNC (ACE_Env_Value<T> operator=(const ACE_Env_Value<T> &)) - // Disallow copying and assignment. void fetch_value (void); diff --git a/ace/Event_Handler.h b/ace/Event_Handler.h index 0f2f719960c..3d62528e38f 100644 --- a/ace/Event_Handler.h +++ b/ace/Event_Handler.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Event_Handler.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Event_Handler.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_EVENT_HANDLER_H #define ACE_EVENT_HANDLER_H @@ -32,16 +29,18 @@ class ACE_Process; typedef u_long ACE_Reactor_Mask; +/** + * @class ACE_Event_Handler + * + * @brief Provides an abstract interface for handling various types of + * I/O, timer, and signal events. + * + * Subclasses read/write input/output on an I/O descriptor, + * handle an exception raised on an I/O descriptor, handle a + * timer's expiration, or handle a signal. + */ class ACE_Export ACE_Event_Handler { - // = TITLE - // Provides an abstract interface for handling various types of - // I/O, timer, and signal events. - // - // = DESCRIPTION - // Subclasses read/write input/output on an I/O descriptor, - // handle an exception raised on an I/O descriptor, handle a - // timer's expiration, or handle a signal. public: enum { @@ -78,50 +77,52 @@ public: DONT_CALL = (1 << 9) }; + /// Destructor is virtual to enable proper cleanup. virtual ~ACE_Event_Handler (void); - // Destructor is virtual to enable proper cleanup. + /// Get the I/O handle. + /// Set the I/O handle. virtual ACE_HANDLE get_handle (void) const; - // Get the I/O handle. virtual void set_handle (ACE_HANDLE); - // Set the I/O handle. // = Get/set priority // Priorities run from MIN_PRIORITY (which is the "lowest priority") // to MAX_PRIORITY (which is the "highest priority"). + /// Get the priority of the Event_Handler. + /// Set the priority of the Event_Handler. virtual int priority (void) const; - // Get the priority of the Event_Handler. virtual void priority (int priority); - // Set the priority of the Event_Handler. + /// Called when input events occur (e.g., connection or data). virtual int handle_input (ACE_HANDLE fd = ACE_INVALID_HANDLE); - // Called when input events occur (e.g., connection or data). + /// Called when output events are possible (e.g., flow control + /// abates). virtual int handle_output (ACE_HANDLE fd = ACE_INVALID_HANDLE); - // Called when output events are possible (e.g., flow control - // abates). + /// Called when execption events occur (e.g., SIGURG). virtual int handle_exception (ACE_HANDLE fd = ACE_INVALID_HANDLE); - // Called when execption events occur (e.g., SIGURG). + /** + * Called when timer expires. <current_time> represents the current + * time that the <Event_Handler> was selected for timeout + * dispatching and <act> is the asynchronous completion token that + * was passed in when <schedule_timer> was invoked. + */ virtual int handle_timeout (const ACE_Time_Value ¤t_time, const void *act = 0); - // Called when timer expires. <current_time> represents the current - // time that the <Event_Handler> was selected for timeout - // dispatching and <act> is the asynchronous completion token that - // was passed in when <schedule_timer> was invoked. + /// Called when a process exits. virtual int handle_exit (ACE_Process *); - // Called when a process exits. + /// Called when object is removed from the <ACE_Reactor>. virtual int handle_close (ACE_HANDLE handle, ACE_Reactor_Mask close_mask); - // Called when object is removed from the <ACE_Reactor>. + /// Called when object is signaled by OS (either via UNIX signals or + /// when a Win32 object becomes signaled). virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0); - // Called when object is signaled by OS (either via UNIX signals or - // when a Win32 object becomes signaled). virtual int handle_qos (ACE_HANDLE = ACE_INVALID_HANDLE); virtual int handle_group_qos (ACE_HANDLE = ACE_INVALID_HANDLE); @@ -131,63 +132,70 @@ public: virtual ACE_Reactor *reactor (void) const; #if !defined (ACE_HAS_WINCE) + /** + * Used to read from non-socket ACE_HANDLEs in our own thread to + * work around Win32 limitations that don't allow us to <select> on + * non-sockets (such as ACE_STDIN). This is commonly used in + * situations where the Reactor is used to demultiplex read events + * on ACE_STDIN on UNIX. Note that <event_handler> must be a + * subclass of <ACE_Event_Handler>. If the <get_handle> method of + * this event handler returns <ACE_INVALID_HANDLE> we default to + * reading from ACE_STDIN. + */ static void *read_adapter (void *event_handler); - // Used to read from non-socket ACE_HANDLEs in our own thread to - // work around Win32 limitations that don't allow us to <select> on - // non-sockets (such as ACE_STDIN). This is commonly used in - // situations where the Reactor is used to demultiplex read events - // on ACE_STDIN on UNIX. Note that <event_handler> must be a - // subclass of <ACE_Event_Handler>. If the <get_handle> method of - // this event handler returns <ACE_INVALID_HANDLE> we default to - // reading from ACE_STDIN. + /** + * Abstracts away from the differences between Win32 and ACE with + * respect to reading from ACE_STDIN (which is non-<select>'able on + * Win32. + */ static int register_stdin_handler (ACE_Event_Handler *eh, ACE_Reactor *reactor, ACE_Thread_Manager *thr_mgr, int flags = THR_DETACHED); - // Abstracts away from the differences between Win32 and ACE with - // respect to reading from ACE_STDIN (which is non-<select>'able on - // Win32. + /// Performs the inverse of the <register_stdin_handler> method. static int remove_stdin_handler (ACE_Reactor *reactor, ACE_Thread_Manager *thr_mgr); - // Performs the inverse of the <register_stdin_handler> method. #endif /* ACE_HAS_WINCE */ protected: + /// Force ACE_Event_Handler to be an abstract base class. ACE_Event_Handler (ACE_Reactor * = 0, int priority = ACE_Event_Handler::LO_PRIORITY); - // Force ACE_Event_Handler to be an abstract base class. private: + /// Priority of this Event_Handler. int priority_; - // Priority of this Event_Handler. // = Pointers to the various event demultiplexors. ACE_Reactor *reactor_; }; +/** + * @class ACE_Notification_Buffer + * + * @brief Simple wrapper for passing <ACE_Event_Handler *>s and + * <ACE_Reactor_Mask>s between threads. + */ class ACE_Export ACE_Notification_Buffer { - // = TITLE - // Simple wrapper for passing <ACE_Event_Handler *>s and - // <ACE_Reactor_Mask>s between threads. public: ACE_Notification_Buffer (void); ACE_Notification_Buffer (ACE_Event_Handler *eh, ACE_Reactor_Mask mask); + /// Default dtor. ~ACE_Notification_Buffer (void); - // Default dtor. + /// Pointer to the Event_Handler that will be dispatched + /// by the main event loop. ACE_Event_Handler *eh_; - // Pointer to the Event_Handler that will be dispatched - // by the main event loop. + /// Mask that indicates which method to call. ACE_Reactor_Mask mask_; - // Mask that indicates which method to call. }; #if defined (__ACE_INLINE__) diff --git a/ace/Event_Handler_T.h b/ace/Event_Handler_T.h index 0ba36bf27ac..92d54b7dffe 100644 --- a/ace/Event_Handler_T.h +++ b/ace/Event_Handler_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Event_Handler_T.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Event_Handler_T.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_EVENT_HANDLER_T_H #define ACE_EVENT_HANDLER_T_H @@ -26,45 +23,45 @@ #if defined (ACE_HAS_TEMPLATE_TYPEDEFS) +/** + * @class ACE_Event_Handler_T + * + * @brief Enable a class that doesn't inherit from the + * ACE_Event_Handler to be incorporated into the ACE_Reactor + * framework. Thanks to Greg Lavender (g.lavender@isode.com) + * for sharing this idea. + * + * It is sometimes the case that an application has a hierarchy + * of operation dispatcher classes that have their own + * inheritance hierarchy but also would like to integrate with + * the ACE_Reactor. Rather than adopt a "mixin" approach, it is + * often cleaner to define a template as a subclass of + * ACE_Event_Handler and paramterize it with an operation + * dispatcher type. + * When constructing an instantiation of the ACE_Event_Handler_T + * object, a set of pointers to member functions must be + * provided so that when one of the handle_* methods is called + * by the ACE_Reactor, the appropriate method is called on the + * underlying operations object. This is done since in some + * cases it is useful to map any event that happens to the same + * method on an object. + * The ACE_Event_Handler_T template is instantiated by an + * operations object and registered with the ACE_Reactor, and it + * then calls the appropriate op_handler. So, it's basically + * just another level of indirection in event dispatching. The + * coupling betweent the ultimate handler of the event and the + * ACE_Event_Handler class is relaxed a bit by have this + * intermediate <op_handler_> object of type <T> around. The + * client object can then dynamically change the bindings for + * the various handlers so that during the life of one of the + * operation objects, it can change how it wants events to be + * handled. It just instantiates a new instance of the template + * with different bindings and reregisters this new object with + * the ACE_Reactor. + */ template <class T> class ACE_Event_Handler_T : public ACE_Event_Handler { - // = TITLE - // Enable a class that doesn't inherit from the - // ACE_Event_Handler to be incorporated into the ACE_Reactor - // framework. Thanks to Greg Lavender (g.lavender@isode.com) - // for sharing this idea. - // - // = DESCRIPTION - // It is sometimes the case that an application has a hierarchy - // of operation dispatcher classes that have their own - // inheritance hierarchy but also would like to integrate with - // the ACE_Reactor. Rather than adopt a "mixin" approach, it is - // often cleaner to define a template as a subclass of - // ACE_Event_Handler and paramterize it with an operation - // dispatcher type. - // - // When constructing an instantiation of the ACE_Event_Handler_T - // object, a set of pointers to member functions must be - // provided so that when one of the handle_* methods is called - // by the ACE_Reactor, the appropriate method is called on the - // underlying operations object. This is done since in some - // cases it is useful to map any event that happens to the same - // method on an object. - // - // The ACE_Event_Handler_T template is instantiated by an - // operations object and registered with the ACE_Reactor, and it - // then calls the appropriate op_handler. So, it's basically - // just another level of indirection in event dispatching. The - // coupling betweent the ultimate handler of the event and the - // ACE_Event_Handler class is relaxed a bit by have this - // intermediate <op_handler_> object of type <T> around. The - // client object can then dynamically change the bindings for - // the various handlers so that during the life of one of the - // operation objects, it can change how it wants events to be - // handled. It just instantiates a new instance of the template - // with different bindings and reregisters this new object with - // the ACE_Reactor. public: // = Typedefs to simplify pointer-to-member-function registration. @@ -72,18 +69,19 @@ public: typedef ACE_HANDLE (T::*GET_HANDLE) (void) const; typedef void (T::*SET_HANDLE) (ACE_HANDLE); + /// Handle I/O events. typedef int (T::*IO_HANDLER) (ACE_HANDLE); - // Handle I/O events. + /// Handle timeout events. typedef int (T::*TO_HANDLER) (const ACE_Time_Value &, const void *); - // Handle timeout events. + /// Handle close events. typedef int (T::*CL_HANDLER) (ACE_HANDLE, ACE_Reactor_Mask); - // Handle close events. + /// = Initialization and termination methods. typedef int (T::*SIG_HANDLER) (ACE_HANDLE, siginfo_t*, ucontext_t*); - // = Initialization and termination methods. + /// Initialize the op_handler. ACE_Event_Handler_T (T *op_handler, int delete_handler, GET_HANDLE get_handle = 0, @@ -94,10 +92,9 @@ public: IO_HANDLER output = 0, SET_HANDLE set_handle = 0, IO_HANDLER except = 0); - // Initialize the op_handler. + /// Close down and delete the <op_handler> ~ACE_Event_Handler_T (void); - // Close down and delete the <op_handler> // = Override all the ACE_Event_Handler methods. @@ -141,33 +138,33 @@ public: SIG_HANDLER sig_handler (void); void sig_handler (SIG_HANDLER); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Pointer to the object that handles all the delegated operations. T *op_handler_; - // Pointer to the object that handles all the delegated operations. // = Handle input, output, and exception events. IO_HANDLER input_handler_; IO_HANDLER output_handler_; IO_HANDLER except_handler_; + /// Handle timeout events. TO_HANDLER to_handler_; - // Handle timeout events. + /// Handle close events. CL_HANDLER cl_handler_; - // Handle close events. + /// Handle signal events. SIG_HANDLER sig_handler_; - // Handle signal events. + /// Keeps track of whether we need to delete the handler in the + /// destructor. int delete_handler_; - // Keeps track of whether we need to delete the handler in the - // destructor. // = Get/set underlying handle. SET_HANDLE set_handle_; diff --git a/ace/FIFO.h b/ace/FIFO.h index 7732405695d..bd8ea10d2f2 100644 --- a/ace/FIFO.h +++ b/ace/FIFO.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// FIFO.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file FIFO.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_FIFO_H #define ACE_FIFO_H @@ -25,51 +22,53 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_FIFO + * + * @brief Abstract base class for UNIX FIFOs + * + * UNIX FIFOs are also known Named Pipes, which are totally + * unrelated to Win32 Named Pipes. If you want to use a local + * IPC mechanism that will be portable to both UNIX and Win32, + * take a look at the <ACE_SPIPE_*> classes. + */ class ACE_Export ACE_FIFO : public ACE_IPC_SAP { - // = TITLE - // Abstract base class for UNIX FIFOs - // - // = DESCRIPTION - // UNIX FIFOs are also known Named Pipes, which are totally - // unrelated to Win32 Named Pipes. If you want to use a local - // IPC mechanism that will be portable to both UNIX and Win32, - // take a look at the <ACE_SPIPE_*> classes. public: + /// Open up the named pipe on the <rendezvous> in accordance with the + /// flags. int open (const ACE_TCHAR *rendezvous, int flags, int perms, LPSECURITY_ATTRIBUTES sa = 0); - // Open up the named pipe on the <rendezvous> in accordance with the - // flags. + /// Close down the ACE_FIFO without removing the rendezvous point. int close (void); - // Close down the ACE_FIFO without removing the rendezvous point. + /// Close down the ACE_FIFO and remove the rendezvous point from the + /// file system. int remove (void); - // Close down the ACE_FIFO and remove the rendezvous point from the - // file system. + /// Return the local address of this endpoint. int get_local_addr (const ACE_TCHAR *&rendezvous) const; - // Return the local address of this endpoint. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Make these protected to ensure that the class is "abstract." + /// Default constructor. ACE_FIFO (void); - // Default constructor. + /// Open up the named pipe on the <rendezvous> in accordance with the + /// flags. ACE_FIFO (const ACE_TCHAR *rendezvous, int flags, int perms, LPSECURITY_ATTRIBUTES sa = 0); - // Open up the named pipe on the <rendezvous> in accordance with the - // flags. private: + /// Rendezvous point in the file system. ACE_TCHAR rendezvous_[MAXPATHLEN + 1]; - // Rendezvous point in the file system. }; #if defined (__ACE_INLINE__) diff --git a/ace/FIFO_Recv.h b/ace/FIFO_Recv.h index c035343fb60..6767cf4ab7b 100644 --- a/ace/FIFO_Recv.h +++ b/ace/FIFO_Recv.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// FIFO_Recv.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file FIFO_Recv.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_FIFO_RECV_H #define ACE_FIFO_RECV_H @@ -24,48 +21,51 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_FIFO_Recv + * + * @brief Receiver side of the bytestream C++ wrapper for UNIX + * FIFOs. + */ class ACE_Export ACE_FIFO_Recv : public ACE_FIFO { - // = TITLE - // Receiver side of the bytestream C++ wrapper for UNIX - // FIFOs. public: // = Initialization methods. + /// Default constructor. ACE_FIFO_Recv (void); - // Default constructor. + /// Open up a bytestream named pipe for reading. ACE_FIFO_Recv (const ACE_TCHAR *rendezvous, int flags = O_CREAT | O_RDONLY, int perms = ACE_DEFAULT_FILE_PERMS, int persistent = 1, LPSECURITY_ATTRIBUTES sa = 0); - // Open up a bytestream named pipe for reading. + /// Open up a bytestream named pipe for reading. int open (const ACE_TCHAR *rendezvous, int flags = O_CREAT | O_RDONLY, int perms = ACE_DEFAULT_FILE_PERMS, int persistent = 1, LPSECURITY_ATTRIBUTES sa = 0); - // Open up a bytestream named pipe for reading. + /// Close down the named pipe. int close (void); - // Close down the named pipe. + /// Recv <buf> of up to <len> bytes. ssize_t recv (void *buf, size_t len); - // Recv <buf> of up to <len> bytes. + /// Recv <buf> of exactly <len> bytes (block until done). ssize_t recv_n (void *buf, size_t len); - // Recv <buf> of exactly <len> bytes (block until done). + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Auxiliary handle that is used to implement persistent FIFOs. ACE_HANDLE aux_handle_; - // Auxiliary handle that is used to implement persistent FIFOs. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/FIFO_Recv_Msg.h b/ace/FIFO_Recv_Msg.h index 4cc19ff2675..3920e063630 100644 --- a/ace/FIFO_Recv_Msg.h +++ b/ace/FIFO_Recv_Msg.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// FIFO_Recv_Msg.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file FIFO_Recv_Msg.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_FIFO_RECV_MSG_H #define ACE_FIFO_RECV_MSG_H @@ -24,53 +21,56 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_FIFO_Recv_Msg + * + * @brief Receiver side for the record oriented C++ wrapper for UNIX FIFOs. + */ class ACE_Export ACE_FIFO_Recv_Msg : public ACE_FIFO_Recv { - // = TITLE - // Receiver side for the record oriented C++ wrapper for UNIX FIFOs. public: // = Initialization methods. + /// Default constructor. ACE_FIFO_Recv_Msg (void); - // Default constructor. + /// Open up a record-oriented named pipe for reading. ACE_FIFO_Recv_Msg (const ACE_TCHAR *rendezvous, int flags = O_CREAT | O_RDONLY, int perms = ACE_DEFAULT_FILE_PERMS, int persistent = 1, LPSECURITY_ATTRIBUTES sa = 0); - // Open up a record-oriented named pipe for reading. + /// Open up a record-oriented named pipe for reading. int open (const ACE_TCHAR *rendezvous, int flags = O_CREAT | O_RDONLY, int perms = ACE_DEFAULT_FILE_PERMS, int persistent = 1, LPSECURITY_ATTRIBUTES sa = 0); - // Open up a record-oriented named pipe for reading. + /// Recv <msg> as an ACE_Str_Buf. ssize_t recv (ACE_Str_Buf &msg); - // Recv <msg> as an ACE_Str_Buf. + /// Recv <msg> as a buffer. ssize_t recv (void *buf, size_t len); - // Recv <msg> as a buffer. #if defined (ACE_HAS_STREAM_PIPES) + /// Recv <data> and <cntl> message via Stream pipes. ssize_t recv (ACE_Str_Buf *data, ACE_Str_Buf *cntl, int *flags); - // Recv <data> and <cntl> message via Stream pipes. + /// Recv <data> and <cntl> message via Stream pipes in "band" mode. ssize_t recv (int *band, ACE_Str_Buf *data, ACE_Str_Buf *cntl, int *flags); - // Recv <data> and <cntl> message via Stream pipes in "band" mode. #endif /* ACE_HAS_STREAM_PIPES */ + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/FIFO_Send.h b/ace/FIFO_Send.h index a9733f8d478..7c870454b82 100644 --- a/ace/FIFO_Send.h +++ b/ace/FIFO_Send.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// FIFO_Send.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ +//============================================================================= +/** + * @file FIFO_Send.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_FIFO_SEND_H #define ACE_FIFO_SEND_H @@ -24,38 +21,41 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_FIFO_Send + * + * @brief Sender side for the bytestream C++ wrapper for UNIX FIFOs + */ class ACE_Export ACE_FIFO_Send : public ACE_FIFO { - // = TITLE - // Sender side for the bytestream C++ wrapper for UNIX FIFOs public: // = Initialization methods. + /// Default constructor. ACE_FIFO_Send (void); - // Default constructor. + /// Open up a bytestream named pipe for writing. ACE_FIFO_Send (const ACE_TCHAR *rendezvous, int flags = O_WRONLY, int perms = ACE_DEFAULT_FILE_PERMS, LPSECURITY_ATTRIBUTES sa = 0); - // Open up a bytestream named pipe for writing. + /// Open up a bytestream named pipe for writing. int open (const ACE_TCHAR *rendezvous, int flags = O_WRONLY, int perms = ACE_DEFAULT_FILE_PERMS, LPSECURITY_ATTRIBUTES sa = 0); - // Open up a bytestream named pipe for writing. + /// Send <buf> of up to <len> bytes. ssize_t send (const void *buf, size_t len); - // Send <buf> of up to <len> bytes. + /// Send <buf> of exactly <len> bytes (block until done). ssize_t send_n (const void *buf, size_t len); - // Send <buf> of exactly <len> bytes (block until done). + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/FIFO_Send_Msg.h b/ace/FIFO_Send_Msg.h index 0ed9ce9a707..cc4ae785e41 100644 --- a/ace/FIFO_Send_Msg.h +++ b/ace/FIFO_Send_Msg.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// FIFO_Send_Msg.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file FIFO_Send_Msg.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_FIFO_SEND_MSG_H #define ACE_FIFO_SEND_MSG_H @@ -24,52 +21,55 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_FIFO_Send_Msg + * + * @brief Sender side for the Record oriented C++ wrapper for UNIX + * FIFOs. + */ class ACE_Export ACE_FIFO_Send_Msg : public ACE_FIFO_Send { - // = TITLE - // Sender side for the Record oriented C++ wrapper for UNIX - // FIFOs. public: // = Initialization methods. + /// Default constructor. ACE_FIFO_Send_Msg (void); - // Default constructor. + /// Open up a record-oriented named pipe for writing. ACE_FIFO_Send_Msg (const ACE_TCHAR *rendezvous, int flags = O_WRONLY, int perms = ACE_DEFAULT_FILE_PERMS, LPSECURITY_ATTRIBUTES sa = 0); - // Open up a record-oriented named pipe for writing. + /// Open up a record-oriented named pipe for writing. int open (const ACE_TCHAR *rendezvous, int flags = O_WRONLY, int perms = ACE_DEFAULT_FILE_PERMS, LPSECURITY_ATTRIBUTES sa = 0); - // Open up a record-oriented named pipe for writing. + /// Send <buf> of up to <len> bytes. ssize_t send (const ACE_Str_Buf &msg); - // Send <buf> of up to <len> bytes. + /// Send <buf> of exactly <len> bytes (block until done). ssize_t send (const void *buf, size_t len); - // Send <buf> of exactly <len> bytes (block until done). #if defined (ACE_HAS_STREAM_PIPES) + /// Send <data> and <cntl> message via Stream pipes. ssize_t send (const ACE_Str_Buf *data, const ACE_Str_Buf *cntl = 0, int flags = 0); - // Send <data> and <cntl> message via Stream pipes. + /// Send <data> and <cntl> message via Stream pipes in "band" mode. ssize_t send (int band, const ACE_Str_Buf *data, const ACE_Str_Buf *cntl = 0, int flags = MSG_BAND); - // Send <data> and <cntl> message via Stream pipes in "band" mode. #endif /* ACE_HAS_STREAM_PIPES */ + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/FILE.h b/ace/FILE.h index 92f60ab7abb..a06351b86d3 100644 --- a/ace/FILE.h +++ b/ace/FILE.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// FILE.h -// -// = AUTHOR -// Gerhard Lenzer -// -// ============================================================================ + +//============================================================================= +/** + * @file FILE.h + * + * $Id$ + * + * @author Gerhard Lenzer + */ +//============================================================================= + #ifndef ACE_FILE_H #define ACE_FILE_H @@ -39,91 +36,101 @@ #define ACE_FILE_STREAM ACE_FILE_IO, ACE_FILE_Addr #endif /* ACE_TEMPLATE_TYPEDEFS */ +/** + * @class ACE_FILE_Info + * + * @brief Abstracts basic OS FILE information. + */ class ACE_Export ACE_FILE_Info { - // = TITLE - // Abstracts basic OS FILE information. public: + /// mode of file mode_t mode_; - // mode of file + /// no of links nlink_t nlink_; - // no of links + /// size of file off_t size_; - // size of file }; +/** + * @class ACE_FILE + * + * @brief Defines the core methods of the <ACE_FILE> abstraction. + */ class ACE_Export ACE_FILE : public ACE_IO_SAP { - // = TITLE - // Defines the core methods of the <ACE_FILE> abstraction. public: + /// Close the <ACE_FILE> handle without removing the <ACE_FILE> from + /// the file system. int close (void); - // Close the <ACE_FILE> handle without removing the <ACE_FILE> from - // the file system. - + + /// Close and remove the <ACE_FILE> from the file system. int remove (void); - // Close and remove the <ACE_FILE> from the file system. + /// Remove the <ACE_FILE> from the file system without closing the + /// <ACE_FILE> handle. int unlink (void); - // Remove the <ACE_FILE> from the file system without closing the - // <ACE_FILE> handle. + /// Get information on this <ACE_FILE>. int get_info (ACE_FILE_Info *finfo); - // Get information on this <ACE_FILE>. + /// Get information on this <ACE_FILE>. int get_info (ACE_FILE_Info &finfo); - // Get information on this <ACE_FILE>. + /// Set filesize to length byte. int truncate (off_t length); - // Set filesize to length byte. + /** + * Sets the file pointer as follows: + * o If <whence> is <SEEK_SET>, the pointer is set to <offset> + * bytes. + * + * o If <whence> is <SEEK_CUR>, the pointer is set to its + * current location plus <offset>. + * + * o If <whence> is <SEEK_END>, the pointer is set to the size + * of the file plus offset. + * Same as <seek>, but <position> is deprecated. + */ off_t seek (off_t offset, int whence = SEEK_CUR); - // Sets the file pointer as follows: - // o If <whence> is <SEEK_SET>, the pointer is set to <offset> - // bytes. - // - // o If <whence> is <SEEK_CUR>, the pointer is set to its - // current location plus <offset>. - // - // o If <whence> is <SEEK_END>, the pointer is set to the size - // of the file plus offset. off_t position (long offset, int startpos); - // Same as <seek>, but <position> is deprecated. + /// Return an offset for the file handle. off_t tell (void); - // Return an offset for the file handle. + /// Same as <tell>, but <position> is deprecated. off_t position (void); - // Same as <tell>, but <position> is deprecated. + /** + * Disable signal <signum> + * This is here to prevent Win32 from + * disabling SPIPE using socket calls + */ int disable (int signum) const ; - // Disable signal <signum> - // This is here to prevent Win32 from - // disabling SPIPE using socket calls + /// Return the local endpoint address in the referenced <ACE_Addr>. + /// Returns 0 if successful, else -1. int get_local_addr (ACE_Addr &) const; - // Return the local endpoint address in the referenced <ACE_Addr>. - // Returns 0 if successful, else -1. + /// Return the same thing as <get_local_addr>. int get_remote_addr (ACE_Addr &) const; - // Return the same thing as <get_local_addr>. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Ensure that this class is only created by the + /// <ACE_FILE_Connector>. ACE_FILE (void); - // Ensure that this class is only created by the - // <ACE_FILE_Connector>. + /// File we are "connected" with... ACE_FILE_Addr addr_; - // File we are "connected" with... }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/FILE_Addr.h b/ace/FILE_Addr.h index 29d696bfab2..b0307e6f856 100644 --- a/ace/FILE_Addr.h +++ b/ace/FILE_Addr.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// FILE_Addr.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file FILE_Addr.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_FILE_ADDR_H #define ACE_FILE_ADDR_H @@ -26,55 +23,58 @@ #include "ace/Flag_Manip.h" +/** + * @class ACE_FILE_Addr + * + * @brief Defines the FILE address family address format. + */ class ACE_Export ACE_FILE_Addr : public ACE_Addr { - // = TITLE - // Defines the FILE address family address format. public: // = Initialization methods. + /// Default constructor. ACE_FILE_Addr (void); - // Default constructor. + /// Copy constructor. ACE_FILE_Addr (const ACE_FILE_Addr &sa); - // Copy constructor. + /// Acts like a copy constructor. If <sa> == ACE_Addr::sap_any then + /// create a temporary filename using <ACE_OS::mktemp>. int set (const ACE_FILE_Addr &sa); - // Acts like a copy constructor. If <sa> == ACE_Addr::sap_any then - // create a temporary filename using <ACE_OS::mktemp>. + /// Create a ACE_FILE_Addr from a pathname. ACE_EXPLICIT ACE_FILE_Addr (const ACE_TCHAR *filename); - // Create a ACE_FILE_Addr from a pathname. + /// Create a ACE_FILE_Addr from a pathname. int set (const ACE_TCHAR *filename); - // Create a ACE_FILE_Addr from a pathname. + /// Assignment operator. ACE_FILE_Addr &operator= (const ACE_FILE_Addr &); - // Assignment operator. + /// Return a pointer to the address. virtual void *get_addr (void) const; - // Return a pointer to the address. + /// Transform the current address into string format. virtual int addr_to_string (ACE_TCHAR *addr, size_t) const; - // Transform the current address into string format. + /// Compare two addresses for equality. int operator == (const ACE_FILE_Addr &SAP) const; - // Compare two addresses for equality. + /// Compare two addresses for inequality. int operator != (const ACE_FILE_Addr &SAP) const; - // Compare two addresses for inequality. + /// Return the path name used for the rendezvous point. const ACE_TCHAR *get_path_name (void) const; - // Return the path name used for the rendezvous point. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Name of the file. ACE_TCHAR filename_[MAXNAMLEN + 1]; - // Name of the file. }; #if defined (__ACE_INLINE__) diff --git a/ace/FILE_Connector.h b/ace/FILE_Connector.h index d9ffbd5569b..be78d11770d 100644 --- a/ace/FILE_Connector.h +++ b/ace/FILE_Connector.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// FILE_Connector.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ +//============================================================================= +/** + * @file FILE_Connector.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_FILE_CONNECTOR_H #define ACE_FILE_CONNECTOR_H @@ -25,15 +22,34 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_FILE_Connector + * + * @brief Defines an active connection factory for the ACE_FILE wrappers. + */ class ACE_Export ACE_FILE_Connector { - // = TITLE - // Defines an active connection factory for the ACE_FILE wrappers. public: // = Initialization methods. + /// Default constructor. ACE_FILE_Connector (void); - // Default constructor. + /** + * Actively ``connect'' and produce a <new_io> <ACE_FILE_IO> object + * if things go well. The <remote_sap> is the file that we are + * trying to create/open. If it's the default value of + * <ACE_Addr::sap_any> then the user is letting the OS create the + * filename (via <ACE_OS::mktemp>). The <timeout> is the amount of + * time to wait to create/open the file. If it's 0 then we block + * indefinitely. If *timeout == {0, 0} then the file is created + * using non-blocking mode. In this case, if the create/open can't + * be done immediately the value of -1 is returned with <errno == + * EWOULDBLOCK>. If *timeout > {0, 0} then this is the amount of + * time to wait before timing out. If the time expires before the + * connection is made <errno == ETIME>. The <local_sap> and + * <reuse_addr> parameters are ignored. The <flags> and <perms> + * arguments are passed down to the <ACE_OS::open> method. + */ ACE_FILE_Connector (ACE_FILE_IO &new_io, const ACE_FILE_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -41,21 +57,23 @@ public: int reuse_addr = 0, int flags = O_RDWR | O_CREAT, int perms = ACE_DEFAULT_FILE_PERMS); - // Actively ``connect'' and produce a <new_io> <ACE_FILE_IO> object - // if things go well. The <remote_sap> is the file that we are - // trying to create/open. If it's the default value of - // <ACE_Addr::sap_any> then the user is letting the OS create the - // filename (via <ACE_OS::mktemp>). The <timeout> is the amount of - // time to wait to create/open the file. If it's 0 then we block - // indefinitely. If *timeout == {0, 0} then the file is created - // using non-blocking mode. In this case, if the create/open can't - // be done immediately the value of -1 is returned with <errno == - // EWOULDBLOCK>. If *timeout > {0, 0} then this is the amount of - // time to wait before timing out. If the time expires before the - // connection is made <errno == ETIME>. The <local_sap> and - // <reuse_addr> parameters are ignored. The <flags> and <perms> - // arguments are passed down to the <ACE_OS::open> method. + /** + * Actively ``connect'' and produce a <new_io> <ACE_FILE_IO> object + * if things go well. The <remote_sap> is the file that we are + * trying to create/open. If it's the default value of + * <ACE_Addr::sap_any> then the user is letting the OS create the + * filename (via <ACE_OS::mktemp>). The <timeout> is the amount of + * time to wait to create/open the file. If it's 0 then we block + * indefinitely. If *timeout == {0, 0} then the file is created + * using non-blocking mode. In this case, if the create/open can't + * be done immediately the value of -1 is returned with <errno == + * EWOULDBLOCK>. If *timeout > {0, 0} then this is the amount of + * time to wait before timing out. If the time expires before the + * connection is made <errno == ETIME>. The <local_sap> and + * <reuse_addr> parameters are ignored. The <flags> and <perms> + * arguments are passed down to the <ACE_OS::open> method. + */ int connect (ACE_FILE_IO &new_io, const ACE_FILE_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -63,29 +81,15 @@ public: int reuse_addr = 0, int flags = O_RDWR | O_CREAT, int perms = ACE_DEFAULT_FILE_PERMS); - // Actively ``connect'' and produce a <new_io> <ACE_FILE_IO> object - // if things go well. The <remote_sap> is the file that we are - // trying to create/open. If it's the default value of - // <ACE_Addr::sap_any> then the user is letting the OS create the - // filename (via <ACE_OS::mktemp>). The <timeout> is the amount of - // time to wait to create/open the file. If it's 0 then we block - // indefinitely. If *timeout == {0, 0} then the file is created - // using non-blocking mode. In this case, if the create/open can't - // be done immediately the value of -1 is returned with <errno == - // EWOULDBLOCK>. If *timeout > {0, 0} then this is the amount of - // time to wait before timing out. If the time expires before the - // connection is made <errno == ETIME>. The <local_sap> and - // <reuse_addr> parameters are ignored. The <flags> and <perms> - // arguments are passed down to the <ACE_OS::open> method. + /// Resets any event associations on this handle int reset_new_handle (ACE_HANDLE handle); - // Resets any event associations on this handle + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. // = Meta-type "trait" information. typedef ACE_FILE_Addr PEER_ADDR; diff --git a/ace/FILE_IO.h b/ace/FILE_IO.h index d390c0cb5ce..155d1f9a0c4 100644 --- a/ace/FILE_IO.h +++ b/ace/FILE_IO.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// FILE_IO.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file FILE_IO.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_FILE_IO_H #define ACE_FILE_IO_H @@ -29,109 +26,118 @@ // Used in the FILE_IO.h file... #include "ace/ACE.h" +/** + * @class ACE_FILE_IO + * + * @brief Read/Write operations on Files + */ class ACE_Export ACE_FILE_IO : public ACE_FILE { - // = TITLE - // Read/Write operations on Files public: friend class ACE_FILE_Connector; // = Initialization method. + /// Default constructor. ACE_FILE_IO (void); - // Default constructor. + /// send upto <n> bytes in <buf>. ssize_t send (const void *buf, size_t n) const; - // send upto <n> bytes in <buf>. + /// Recv upto <n> bytes in <buf>. ssize_t recv (void *buf, size_t n) const; - // Recv upto <n> bytes in <buf>. + /// Send n bytes, keep trying until n are sent. ssize_t send_n (const void *buf, size_t n) const; - // Send n bytes, keep trying until n are sent. + /// Recv n bytes, keep trying until n are received. ssize_t recv_n (void *buf, size_t n) const; - // Recv n bytes, keep trying until n are received. #if defined (ACE_HAS_STREAM_PIPES) + /// Send bytes via STREAM pipes. ssize_t send (const ACE_Str_Buf *cntl, const ACE_Str_Buf *data, int flags = 0) const; - // Send bytes via STREAM pipes. + /// Recv bytes via STREAM pipes. ssize_t recv (ACE_Str_Buf *cntl, ACE_Str_Buf *data, int *flags) const; - // Recv bytes via STREAM pipes. + /// Send bytes via STREAM pipes using "band" mode. ssize_t send (const ACE_Str_Buf *cntl, const ACE_Str_Buf *data, int band, int flags) const; - // Send bytes via STREAM pipes using "band" mode. + /// Recv bytes via STREAM pipes using "band" mode. ssize_t recv (ACE_Str_Buf *cntl, ACE_Str_Buf *data, int *band, int *flags) const; - // Recv bytes via STREAM pipes using "band" mode. #endif /* ACE_HAS_STREAM_PIPES */ + /// Send iovecs via <::writev>. ssize_t send (const iovec iov[], size_t n) const; - // Send iovecs via <::writev>. + /// Recv iovecs via <::readv>. ssize_t recv (iovec iov[], size_t n) const; - // Recv iovecs via <::readv>. + /** + * Send N char *ptrs and int lengths. Note that the char *'s + * precede the ints (basically, an varargs version of writev). The + * count N is the *total* number of trailing arguments, *not* a + * couple of the number of tuple pairs! + */ ssize_t send (size_t n, ...) const; - // Send N char *ptrs and int lengths. Note that the char *'s - // precede the ints (basically, an varargs version of writev). The - // count N is the *total* number of trailing arguments, *not* a - // couple of the number of tuple pairs! + /** + * This is an interface to ::readv, that doesn't use the struct + * iovec explicitly. The ... can be passed as an arbitrary number + * of (char *ptr, int len) tuples. However, the count N is the + * *total* number of trailing arguments, *not* a couple of the + * number of tuple pairs! + */ ssize_t recv (size_t n, ...) const; - // This is an interface to ::readv, that doesn't use the struct - // iovec explicitly. The ... can be passed as an arbitrary number - // of (char *ptr, int len) tuples. However, the count N is the - // *total* number of trailing arguments, *not* a couple of the - // number of tuple pairs! + /// Send <n> bytes via Win32 WriteFile using overlapped I/O. ssize_t send (const void *buf, size_t n, ACE_OVERLAPPED *overlapped) const; - // Send <n> bytes via Win32 WriteFile using overlapped I/O. + /// Recv <n> bytes via Win32 ReadFile using overlapped I/O. ssize_t recv (void *buf, size_t n, ACE_OVERLAPPED *overlapped) const; - // Recv <n> bytes via Win32 ReadFile using overlapped I/O. + /// Send an <iovec> of size <n> to the file. ssize_t sendv (const iovec iov[], size_t n) const; - // Send an <iovec> of size <n> to the file. + /** + * Allows a client to read from a file without having to provide a + * buffer to read. This method determines how much data is in the + * file, allocates a buffer of this size, reads in the data, and + * returns the number of bytes read. The caller is responsible for + * deleting the member in the <iov_base> field of <io_vec> using + * delete [] io_vec->iov_base. + */ ssize_t recvv (iovec *io_vec); - // Allows a client to read from a file without having to provide a - // buffer to read. This method determines how much data is in the - // file, allocates a buffer of this size, reads in the data, and - // returns the number of bytes read. The caller is responsible for - // deleting the member in the <iov_base> field of <io_vec> using - // delete [] io_vec->iov_base. + /// Send an <iovec> of size <n> to the file. Will block until all + /// bytes are sent or an error occurs. ssize_t sendv_n (const iovec iov[], size_t n) const; - // Send an <iovec> of size <n> to the file. Will block until all - // bytes are sent or an error occurs. + /// Receive an <iovec> of size <n> to the file. ssize_t recvv_n (iovec iov[], size_t n) const; - // Receive an <iovec> of size <n> to the file. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. // = Meta-type info typedef ACE_FILE_Addr PEER_ADDR; diff --git a/ace/File_Lock.h b/ace/File_Lock.h index 1cce6e4370b..f1d438e5734 100644 --- a/ace/File_Lock.h +++ b/ace/File_Lock.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// File_Lock.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file File_Lock.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_FILE_LOCK_H #define ACE_FILE_LOCK_H @@ -24,102 +21,120 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_File_Lock + * + * @brief A wrapper around the UNIX file locking mechanism. + * + * Allows us to "adapt" the UNIX file locking mechanisms to work + * with all of our Guard stuff... + */ class ACE_Export ACE_File_Lock { - // = TITLE - // A wrapper around the UNIX file locking mechanism. - // - // = DESCRIPTION - // Allows us to "adapt" the UNIX file locking mechanisms to work - // with all of our Guard stuff... public: + /** + * Set the <handle_> of the File_Lock to <handle>. Note that this + * constructor assumes ownership of the <handle> and will close it + * down in <remove>. If you want the <handle> stays open when + * <remove> is called make sure to call <dup> on the <handle> before + * closing it. + */ ACE_File_Lock (ACE_HANDLE handle = ACE_INVALID_HANDLE); - // Set the <handle_> of the File_Lock to <handle>. Note that this - // constructor assumes ownership of the <handle> and will close it - // down in <remove>. If you want the <handle> stays open when - // <remove> is called make sure to call <dup> on the <handle> before - // closing it. + /// Open the <filename> with <flags> and <mode> and set the result to + /// <handle_>. ACE_File_Lock (const ACE_TCHAR *filename, int flags, mode_t mode = 0); - // Open the <filename> with <flags> and <mode> and set the result to - // <handle_>. + /// Open the <filename> with <flags> and <mode> and set the result to + /// <handle_>. int open (const ACE_TCHAR *filename, int flags, mode_t mode = 0); - // Open the <filename> with <flags> and <mode> and set the result to - // <handle_>. + /// Remove a File lock by releasing it and closing down the <handle_>. ~ACE_File_Lock (void); - // Remove a File lock by releasing it and closing down the <handle_>. + /// Remove a File lock by releasing it and closing down the + /// <handle_>. If <unlink_file> is non-0 then we unlink the file. int remove (int unlink_file = 1); - // Remove a File lock by releasing it and closing down the - // <handle_>. If <unlink_file> is non-0 then we unlink the file. + /** + * Note, for interface uniformity with other synchronization + * wrappers we include the <acquire> method. This is implemented as + * a write-lock to be on the safe-side... + */ int acquire (short whence = 0, off_t start = 0, off_t len = 1); - // Note, for interface uniformity with other synchronization - // wrappers we include the <acquire> method. This is implemented as - // a write-lock to be on the safe-side... + /** + * Note, for interface uniformity with other synchronization + * wrappers we include the <tryacquire> method. This is implemented + * as a write-lock to be on the safe-side... Returns -1 on failure. + * If we "failed" because someone else already had the lock, <errno> + * is set to <EBUSY>. + */ int tryacquire (short whence = 0, off_t start = 0, off_t len = 1); - // Note, for interface uniformity with other synchronization - // wrappers we include the <tryacquire> method. This is implemented - // as a write-lock to be on the safe-side... Returns -1 on failure. - // If we "failed" because someone else already had the lock, <errno> - // is set to <EBUSY>. + /// Unlock a readers/writer lock. int release (short whence = 0, off_t start = 0, off_t len = 1); - // Unlock a readers/writer lock. + /// Acquire a write lock, but block if any readers or a + /// writer hold the lock. int acquire_write (short whence = 0, off_t start = 0, off_t len = 1); - // Acquire a write lock, but block if any readers or a - // writer hold the lock. + /** + * Conditionally acquire a write lock (i.e., won't block). Returns + * -1 on failure. If we "failed" because someone else already had + * the lock, <errno> is set to <EBUSY>. + */ int tryacquire_write (short whence = 0, off_t start = 0, off_t len = 1); - // Conditionally acquire a write lock (i.e., won't block). Returns - // -1 on failure. If we "failed" because someone else already had - // the lock, <errno> is set to <EBUSY>. + /** + * Conditionally upgrade to a write lock (i.e., won't block). Returns + * -1 on failure. If we "failed" because someone else already had + * the lock, <errno> is set to <EBUSY>. + */ int tryacquire_write_upgrade (short whence = 0, off_t start = 0, off_t len = 1); - // Conditionally upgrade to a write lock (i.e., won't block). Returns - // -1 on failure. If we "failed" because someone else already had - // the lock, <errno> is set to <EBUSY>. + /** + * Acquire a read lock, but block if a writer hold the lock. + * Returns -1 on failure. If we "failed" because someone else + * already had the lock, <errno> is set to <EBUSY>. + */ int acquire_read (short whence = 0, off_t start = 0, off_t len = 1); - // Acquire a read lock, but block if a writer hold the lock. - // Returns -1 on failure. If we "failed" because someone else - // already had the lock, <errno> is set to <EBUSY>. + /** + * Conditionally acquire a read lock (i.e., won't block). Returns + * -1 on failure. If we "failed" because someone else already had + * the lock, <errno> is set to <EBUSY>. + */ int tryacquire_read (short whence = 0, off_t start = 0, off_t len = 1); - // Conditionally acquire a read lock (i.e., won't block). Returns - // -1 on failure. If we "failed" because someone else already had - // the lock, <errno> is set to <EBUSY>. + /// Get underlying <ACE_HANDLE> for the file. ACE_HANDLE get_handle (void); - // Get underlying <ACE_HANDLE> for the file. + /** + * Set underlying <ACE_HANDLE>. Note that this method assumes + * ownership of the <handle> and will close it down in <remove>. If + * you want the <handle> to stay open when <remove> is called make + * sure to call <dup> on the <handle> before closing it. You are + * responsible for the closing the existing <handle> before + * overwriting it. + */ void set_handle (ACE_HANDLE); - // Set underlying <ACE_HANDLE>. Note that this method assumes - // ownership of the <handle> and will close it down in <remove>. If - // you want the <handle> to stay open when <remove> is called make - // sure to call <dup> on the <handle> before closing it. You are - // responsible for the closing the existing <handle> before - // overwriting it. + /// Dump state of the object. void dump (void) const; - // Dump state of the object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Locking structure for OS record locks. ACE_OS::ace_flock_t lock_; - // Locking structure for OS record locks. + /// Keeps track of whether <remove> has been called yet to avoid + /// multiple <remove> calls, e.g., explicitly and implicitly in the int removed_; - // Keeps track of whether <remove> has been called yet to avoid - // multiple <remove> calls, e.g., explicitly and implicitly in the // destructor. This flag isn't protected by a lock, so make sure // that you don't have multiple threads simultaneously calling // <remove> on the same object, which is a bad idea anyway... diff --git a/ace/Filecache.h b/ace/Filecache.h index ceff9a43128..d7870691c01 100644 --- a/ace/Filecache.h +++ b/ace/Filecache.h @@ -1,19 +1,15 @@ /* -*- c++ -*- */ -// Hey, Emacs! This is a C++ file! -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Filecache.h -// -// = AUTHOR -// James Hu -// -// ============================================================================ + +//============================================================================= +/** + * @file Filecache.h + * + * $Id$ + * + * @author James Hu + */ +//============================================================================= + #ifndef ACE_FILECACHE_H #define ACE_FILECACHE_H @@ -37,44 +33,40 @@ enum ACE_Filecache_Flag class ACE_Filecache_Object; +/** + * @class ACE_Filecache_Handle + * + * @brief Abstraction over a real file. This is meant to be the entry + * point into the Cached Virtual Filesystem. + * + * This is a cached filesystem implementation based loosely on the + * implementation of JAWS_File. The interfaces will be nearly the + * same. The under-the-hood implementation should hopefully be a + * much faster thing. + * These will be given their own implementations later. For now, we + * borrow the implementation provided by JAWS. + * On creation, the cache is checked, and reference count is + * incremented. On destruction, reference count is decremented. If + * the reference count is 0, the file is removed from the cache. + * E.g. 1, + * { + * ACE_Filecache_Handle foo("foo.html"); + * this->peer ().send (foo.address (), foo.size ()); + * } + * E.g. 2, + * { + * ACE_Filecache_Handle foo("foo.html"); + * io->transmitfile (foo.handle (), this->peer ().handle ()); + * } + * E.g. 3, + * { + * ACE_Filecache_Handle foo("foo.html", content_length); + * this->peer ().recv (foo.address (), content_length); + * } + * TODO: + */ class ACE_Export ACE_Filecache_Handle { - // = TITLE - // Abstraction over a real file. This is meant to be the entry - // point into the Cached Virtual Filesystem. - // - // = DESCRIPTION - // This is a cached filesystem implementation based loosely on the - // implementation of JAWS_File. The interfaces will be nearly the - // same. The under-the-hood implementation should hopefully be a - // much faster thing. - // - // These will be given their own implementations later. For now, we - // borrow the implementation provided by JAWS. - // - // On creation, the cache is checked, and reference count is - // incremented. On destruction, reference count is decremented. If - // the reference count is 0, the file is removed from the cache. - // - // E.g. 1, - // { - // ACE_Filecache_Handle foo("foo.html"); - // this->peer ().send (foo.address (), foo.size ()); - // } - // - // E.g. 2, - // { - // ACE_Filecache_Handle foo("foo.html"); - // io->transmitfile (foo.handle (), this->peer ().handle ()); - // } - // - // E.g. 3, - // { - // ACE_Filecache_Handle foo("foo.html", content_length); - // this->peer ().recv (foo.address (), content_length); - // } - // - // TODO: // (1) Get rid of the useless copying of files when reading. Although // it does make sure the file you send isn't being changed, it doesn't @@ -93,42 +85,44 @@ class ACE_Export ACE_Filecache_Handle // public: + /// Query cache for file, and acquire it. Assumes the file is being + /// opened for reading. ACE_Filecache_Handle (const ACE_TCHAR *filename, ACE_Filecache_Flag mapit = ACE_MAPIT); - // Query cache for file, and acquire it. Assumes the file is being - // opened for reading. + /** + * Create new entry, and acquire it. Presence of SIZE assumes the + * file is being opened for writing. If SIZE is zero, assumes the + * file is to be removed from the cache. + */ ACE_Filecache_Handle (const ACE_TCHAR *filename, int size, ACE_Filecache_Flag mapit = ACE_MAPIT); - // Create new entry, and acquire it. Presence of SIZE assumes the - // file is being opened for writing. If SIZE is zero, assumes the - // file is to be removed from the cache. + /// Closes any open handles, release acquired file. ~ACE_Filecache_Handle (void); - // Closes any open handles, release acquired file. + /// Base address of memory mapped file. void *address (void) const; - // Base address of memory mapped file. + /// A handle (e.g., UNIX file descriptor, or NT file handle). ACE_HANDLE handle (void) const; - // A handle (e.g., UNIX file descriptor, or NT file handle). + /// Any associated error in handle creation and acquisition. int error (void) const; - // Any associated error in handle creation and acquisition. + /// The size of the file. size_t size (void) const; - // The size of the file. protected: + /// Default do nothing constructor. Prevent it from being called. ACE_Filecache_Handle (void); - // Default do nothing constructor. Prevent it from being called. + /// Common initializations for constructors. void init (void); - // Common initializations for constructors. public: - // = These come from ACE_Filecache_Object, which is an internal class. + /// These come from ACE_Filecache_Object, which is an internal class. enum { ACE_SUCCESS = 0, @@ -141,11 +135,11 @@ public: }; private: + /// A reference to the low level instance. ACE_Filecache_Object *file_; - // A reference to the low level instance. + /// A <dup>'d version of the one from <file_>. ACE_HANDLE handle_; - // A <dup>'d version of the one from <file_>. int mapit_; }; @@ -164,36 +158,39 @@ typedef ACE_Hash_Map_Manager<ACE_TString, ACE_Filecache_Object *, ACE_Null_Mutex ACE_Filecache_Hash; #endif /* ACE_HAS_TEMPLATE_SPECIALIZATION */ +/** + * @class ACE_Filecache + * + * @brief A hash table holding the information about entry point into + * the Cached Virtual Filesystem. On insertion, the reference + * count is incremented. On destruction, reference count is + * decremented. + */ class ACE_Export ACE_Filecache { - // = TITLE - // A hash table holding the information about entry point into - // the Cached Virtual Filesystem. On insertion, the reference - // count is incremented. On destruction, reference count is - // decremented. public: + /// Singleton pattern. static ACE_Filecache *instance (void); - // Singleton pattern. ~ACE_Filecache (void); + /// Returns 0 if the file associated with ``filename'' is in the cache, + /// or -1 if not. int find (const ACE_TCHAR *filename); - // Returns 0 if the file associated with ``filename'' is in the cache, - // or -1 if not. + /// Return the file associated with ``filename'' if it is in the cache, + /// or create if not. ACE_Filecache_Object *fetch (const ACE_TCHAR *filename, int mapit = 1); - // Return the file associated with ``filename'' if it is in the cache, - // or create if not. + /// Remove the file associated with ``filename'' from the cache. ACE_Filecache_Object *remove (const ACE_TCHAR *filename); - // Remove the file associated with ``filename'' from the cache. + /// Create a new Filecache_Object, returns it. ACE_Filecache_Object *create (const ACE_TCHAR *filename, int size); - // Create a new Filecache_Object, returns it. + /// Release an acquired Filecache_Object, returns it again or NULL if it + /// was deleted. ACE_Filecache_Object *finish (ACE_Filecache_Object *&new_file); - // Release an acquired Filecache_Object, returns it again or NULL if it - // was deleted. protected: ACE_Filecache_Object *insert_i (const ACE_TCHAR *filename, @@ -208,95 +205,98 @@ public: enum { + /// For this stupid implementation, use an array. Someday, use a + /// balanced search tree, or real hash table. ACE_DEFAULT_VIRTUAL_FILESYSTEM_TABLE_SIZE = 512, - // For this stupid implementation, use an array. Someday, use a - // balanced search tree, or real hash table. + /// This determines the highwater mark in megabytes for the cache. + /// This will be ignored for now. ACE_DEFAULT_VIRTUAL_FILESYSTEM_CACHE_SIZE = 20 - // This determines the highwater mark in megabytes for the cache. - // This will be ignored for now. }; protected: + /// Prevent it from being called. ACE_Filecache (void); - // Prevent it from being called. private: int size_; + /// The hash table ACE_Filecache_Hash hash_; - // The hash table + /// The reference to the instance static ACE_Filecache *cvf_; - // The reference to the instance // = Synchronization variables. ACE_SYNCH_RW_MUTEX hash_lock_[ACE_DEFAULT_VIRTUAL_FILESYSTEM_TABLE_SIZE]; ACE_SYNCH_RW_MUTEX file_lock_[ACE_DEFAULT_VIRTUAL_FILESYSTEM_TABLE_SIZE]; }; +/** + * @class ACE_Filecache_Object + * + * @brief Abstraction over a real file. This is what the Virtual + * Filesystem contains. This class is not intended for general + * consumption. Please consult a physician before attempting to + * use this class. + */ class ACE_Export ACE_Filecache_Object { - // = TITLE - // Abstraction over a real file. This is what the Virtual - // Filesystem contains. This class is not intended for general - // consumption. Please consult a physician before attempting to - // use this class. public: friend class ACE_Filecache; + /// Creates a file for reading. ACE_Filecache_Object (const ACE_TCHAR *filename, ACE_SYNCH_RW_MUTEX &lock, LPSECURITY_ATTRIBUTES sa = 0, int mapit = 1); - // Creates a file for reading. + /// Creates a file for writing. ACE_Filecache_Object (const ACE_TCHAR *filename, int size, ACE_SYNCH_RW_MUTEX &lock, LPSECURITY_ATTRIBUTES sa = 0); - // Creates a file for writing. + /// Only if reference count is zero should this be called. ~ACE_Filecache_Object (void); - // Only if reference count is zero should this be called. + /// Increment the reference_count_. int acquire (void); - // Increment the reference_count_. + /// Decrement the reference_count_. int release (void); - // Decrement the reference_count_. // = error_ accessors int error (void) const; int error (int error_value, const ACE_TCHAR *s = ACE_LIB_TEXT ("ACE_Filecache_Object")); + /// filename_ accessor const ACE_TCHAR *filename (void) const; - // filename_ accessor + /// handle_ accessor. ACE_HANDLE handle (void) const; - // handle_ accessor. + /// Base memory address for memory mapped file. void *address (void) const; - // Base memory address for memory mapped file. + /// size_ accessor. size_t size (void) const; - // size_ accessor. + /// True if file on disk is newer than cached file. int update (void) const; - // True if file on disk is newer than cached file. protected: + /// Prevent from being called. ACE_Filecache_Object (void); - // Prevent from being called. + /// Common initialization code, void init (void); - // Common initialization code, private: + /// Internal error logging method, no locking. int error_i (int error_value, const ACE_TCHAR *s = ACE_LIB_TEXT ("ACE_Filecache_Object")); - // Internal error logging method, no locking. public: @@ -318,34 +318,34 @@ public: }; private: + /// The temporary file name and the real file name. The real file is + /// copied into the temporary file for safety reasons. ACE_TCHAR *tempname_; ACE_TCHAR filename_[MAXPATHLEN + 1]; - // The temporary file name and the real file name. The real file is - // copied into the temporary file for safety reasons. + /// mmap_ holds the memory mapped version of the temporary file. + /// handle_ is the descriptor to the temporary file. ACE_Mem_Map mmap_; ACE_HANDLE handle_; - // mmap_ holds the memory mapped version of the temporary file. - // handle_ is the descriptor to the temporary file. + /// Used to compare against the real file to test if an update is needed. struct stat stat_; size_t size_; - // Used to compare against the real file to test if an update is needed. + /// Status indicators. int action_; int error_; - // Status indicators. + /// If set to 1, means the object is flagged for removal. int stale_; - // If set to 1, means the object is flagged for removal. + /// Security attribute object. LPSECURITY_ATTRIBUTES sa_; - // Security attribute object. + /// lock_ provides a bookkeeping mechanism for users of this object. + /// junklock_ is the default initializer ACE_SYNCH_RW_MUTEX junklock_; ACE_SYNCH_RW_MUTEX &lock_; - // lock_ provides a bookkeeping mechanism for users of this object. - // junklock_ is the default initializer }; diff --git a/ace/FlReactor.h b/ace/FlReactor.h index f13a731c978..20d2ad5e34d 100644 --- a/ace/FlReactor.h +++ b/ace/FlReactor.h @@ -1,24 +1,19 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// FlReactor.h -// -// = AUTHOR -// Carlos O'Ryan <coryan@cs.wustl.edu> -// -// Based in part in the ACE_XtReactor implementation by: -// -// Eric C. Newton's <ecn@clark.net>, -// Kirill Rybaltchenko <Kirill.Rybaltchenko@cern.ch>, and -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file FlReactor.h + * + * $Id$ + * + * @author Carlos O'Ryan <coryan@cs.wustl.edu> + * @author Based in part in the ACE_XtReactor implementation by + * @author Eric C. Newton's <ecn@clark.net> + * @author Kirill Rybaltchenko <Kirill.Rybaltchenko@cern.ch> + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_FLREACTOR_H #define ACE_FLREACTOR_H @@ -32,20 +27,21 @@ #if defined (ACE_HAS_FL) +/** + * @class ACE_FlReactor + * + * @brief A Reactor implementation that uses the Fast-Light (FL) toolkit + * for event demultiplexing. This will let us integrate the FL + * toolkit with ACE and/or TAO. + * + * As many other GUI toolkits FL supports a minimal set of + * callbacks to handle event demultiplexing, namely simple methods + * to add file descriptors to the event demuxing set or timeout + * events. This class adapts this simple mechanisms so they are + * compatible with ACE's Reactor. + */ class ACE_Export ACE_FlReactor : public ACE_Select_Reactor { - // = TITLE - // A Reactor implementation that uses the Fast-Light (FL) toolkit - // for event demultiplexing. This will let us integrate the FL - // toolkit with ACE and/or TAO. - // - // = DESCRIPTION - // As many other GUI toolkits FL supports a minimal set of - // callbacks to handle event demultiplexing, namely simple methods - // to add file descriptors to the event demuxing set or timeout - // events. This class adapts this simple mechanisms so they are - // compatible with ACE's Reactor. - // public: // = Initialization and termination methods. @@ -59,7 +55,7 @@ public: const void *arg, const ACE_Time_Value &delta_time, const ACE_Time_Value &interval); - virtual int reset_timer_interval (long timer_id, + virtual int reset_timer_interval (long timer_id, const ACE_Time_Value &interval); virtual int cancel_timer (ACE_Event_Handler *handler, int dont_call_handle_close = 1); @@ -69,40 +65,40 @@ public: protected: // = Register timers/handles with Fl. + /// Register a single <handler>. virtual int register_handler_i (ACE_HANDLE handle, ACE_Event_Handler *handler, ACE_Reactor_Mask mask); - // Register a single <handler>. + /// Register a set of <handlers>. virtual int register_handler_i (const ACE_Handle_Set &handles, ACE_Event_Handler *handler, ACE_Reactor_Mask mask); - // Register a set of <handlers>. + /// Remove the <handler> associated with this <handle>. virtual int remove_handler_i (ACE_HANDLE handle, ACE_Reactor_Mask mask); - // Remove the <handler> associated with this <handle>. + /// Remove a set of <handles>. virtual int remove_handler_i (const ACE_Handle_Set &handles, ACE_Reactor_Mask); - // Remove a set of <handles>. + /// Wait for events to occur. virtual int wait_for_multiple_events (ACE_Select_Reactor_Handle_Set &, ACE_Time_Value *); - // Wait for events to occur. private: + /// This method ensures there's an Fl timeout for the first timeout + /// in the Reactor's Timer_Queue. void reset_timeout (void); - // This method ensures there's an Fl timeout for the first timeout - // in the Reactor's Timer_Queue. // = Integrate with the FL callback function mechanism. static void fl_io_proc (int fd, void*); static void fl_timeout_proc (void*); + /// Deny access since member-wise won't work... ACE_FlReactor (const ACE_FlReactor &); ACE_FlReactor &operator = (const ACE_FlReactor &); - // Deny access since member-wise won't work... }; #if defined(__ACE_INLINE__) diff --git a/ace/Flag_Manip.h b/ace/Flag_Manip.h index 52d5a7b83f3..82222bad913 100644 --- a/ace/Flag_Manip.h +++ b/ace/Flag_Manip.h @@ -1,17 +1,17 @@ -// $Id$ -// ======================================================================== +//============================================================================= +/** + * @file ACE_Flag_Manip.h + * + * $Id$ + * + * This class includes the functions used for the Flag Manipulation. + * + * + * @author Priyanka Gontla <pgontla@ece.uci.edu> + */ +//============================================================================= -// FILENAME -// ACE_Flag_Manip.h -// -// DESCRIPTION -// This class includes the functions used for the Flag Manipulation. -// -// AUTHOR -// Priyanka Gontla <pgontla@ece.uci.edu> - -// ======================================================================= #ifndef ACE_FLAG_MANIP_H #define ACE_FLAG_MANIP_H @@ -28,16 +28,16 @@ class ACE_Export ACE_Flag_Manip public: // = Set/get/clear various flags related to I/O HANDLE. + /// Set flags associated with <handle>. static int set_flags (ACE_HANDLE handle, int flags); - // Set flags associated with <handle>. + /// Clear flags associated with <handle>. static int clr_flags (ACE_HANDLE handle, int flags); - // Clear flags associated with <handle>. + /// Return the current setting of flags associated with <handle>. static int get_flags (ACE_HANDLE handle); - // Return the current setting of flags associated with <handle>. }; diff --git a/ace/Free_List.h b/ace/Free_List.h index 41650439d1c..dbde47da788 100644 --- a/ace/Free_List.h +++ b/ace/Free_List.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Free_List.h -// -// = AUTHOR -// Darrell Brunsch (brunsch@cs.wustl.edu) -// -// ============================================================================ + + +//============================================================================= +/** + * @file Free_List.h + * + * $Id$ + * + * @author Darrell Brunsch (brunsch@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_FREE_LIST_H #define ACE_FREE_LIST_H @@ -27,103 +24,109 @@ #include "ace/Synch_T.h" +/** + * @class ACE_Free_List + * + * @brief Implements a free list. + * + * This class maintains a free list of nodes of type T. + */ template <class T> class ACE_Free_List { - // = TITLE - // Implements a free list. - // - // = DESCRIPTION - // This class maintains a free list of nodes of type T. public: + /// Destructor - removes all the elements from the free_list. virtual ~ACE_Free_List (void); - // Destructor - removes all the elements from the free_list. + /// Inserts an element onto the free list (if it isn't past the high + /// water mark). virtual void add (T *element) = 0; - // Inserts an element onto the free list (if it isn't past the high - // water mark). + /// Takes a element off the freelist and returns it. It creates + /// <inc> new elements if the size is at or below the low water mark. virtual T *remove (void) = 0; - // Takes a element off the freelist and returns it. It creates - // <inc> new elements if the size is at or below the low water mark. + /// Returns the current size of the free list. virtual size_t size (void) = 0; - // Returns the current size of the free list. + /// Resizes the free list to <newsize>. virtual void resize (size_t newsize) = 0; - // Resizes the free list to <newsize>. }; +/** + * @class ACE_Locked_Free_List + * + * @brief Implements a free list. + * + * This class maintains a free list of nodes of type T. It + * depends on the type T having a <get_next> and <set_next> + * method. It maintains a mutex so the freelist can be used in + * a multithreaded program . + */ template <class T, class ACE_LOCK> class ACE_Locked_Free_List : public ACE_Free_List<T> { - // = TITLE - // Implements a free list. - // - // = DESCRIPTION - // This class maintains a free list of nodes of type T. It - // depends on the type T having a <get_next> and <set_next> - // method. It maintains a mutex so the freelist can be used in - // a multithreaded program . public: // = Initialization and termination. + /** + * Constructor takes a <mode> (i.e., ACE_FREE_LIST_WITH_POOL or + * ACE_PURE_FREE_LIST), a count of the number of nodes to + * <prealloc>, a low and high water mark (<lwm> and <hwm>) that + * indicate when to allocate more nodes, an increment value (<inc>) + * that indicates how many nodes to allocate when the list must + * grow. + */ ACE_Locked_Free_List (int mode = ACE_FREE_LIST_WITH_POOL, size_t prealloc = ACE_DEFAULT_FREE_LIST_PREALLOC, size_t lwm = ACE_DEFAULT_FREE_LIST_LWM, size_t hwm = ACE_DEFAULT_FREE_LIST_HWM, size_t inc = ACE_DEFAULT_FREE_LIST_INC); - // Constructor takes a <mode> (i.e., ACE_FREE_LIST_WITH_POOL or - // ACE_PURE_FREE_LIST), a count of the number of nodes to - // <prealloc>, a low and high water mark (<lwm> and <hwm>) that - // indicate when to allocate more nodes, an increment value (<inc>) - // that indicates how many nodes to allocate when the list must - // grow. + /// Destructor - removes all the elements from the free_list. virtual ~ACE_Locked_Free_List (void); - // Destructor - removes all the elements from the free_list. + /// Inserts an element onto the free list (if it isn't past the high + /// water mark). virtual void add (T *element); - // Inserts an element onto the free list (if it isn't past the high - // water mark). + /// Takes a element off the freelist and returns it. It creates + /// <inc> new elements if the size is at or below the low water mark. virtual T *remove (void); - // Takes a element off the freelist and returns it. It creates - // <inc> new elements if the size is at or below the low water mark. + /// Returns the current size of the free list. virtual size_t size (void); - // Returns the current size of the free list. + /// Resizes the free list to <newsize>. virtual void resize (size_t newsize); - // Resizes the free list to <newsize>. protected: + /// Allocates <n> extra nodes for the freelist. virtual void alloc (size_t n); - // Allocates <n> extra nodes for the freelist. + /// Removes and frees <n> nodes from the freelist. virtual void dealloc (size_t n); - // Removes and frees <n> nodes from the freelist. + /// Free list operation mode, either ACE_FREE_LIST_WITH_POOL or + /// ACE_PURE_FREE_LIST. int mode_; - // Free list operation mode, either ACE_FREE_LIST_WITH_POOL or - // ACE_PURE_FREE_LIST. + /// Pointer to the first node in the freelist. T *free_list_; - // Pointer to the first node in the freelist. + /// Low water mark. size_t lwm_; - // Low water mark. + /// High water mark. size_t hwm_; - // High water mark. + /// Increment value. size_t inc_; - // Increment value. + /// Keeps track of the size of the list. size_t size_; - // Keeps track of the size of the list. + /// Synchronization variable for <ACE_Timer_Queue>. ACE_LOCK mutex_; - // Synchronization variable for <ACE_Timer_Queue>. private: // = Don't allow these operations for now. diff --git a/ace/Functor.h b/ace/Functor.h index bce51209ff6..7eb6333016e 100644 --- a/ace/Functor.h +++ b/ace/Functor.h @@ -1,39 +1,32 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Functor.h -// -// = DESCRIPTION -// Non-templatized classes and class template specializations for -// implementing function objects that are used in various places -// in ACE. There are currently two major categories of function -// objects in ACE: GoF Command Pattern objects, and STL-style -// functors for comparison of container elements. The command objects -// are invoked via an execute () method, while the STL-style functors are -// invoked via an operator() () method. -// Non-templatized classes for implementing the GoF Command Pattern, -// also known as functors or function objects. -// -// = AUTHOR -// Chris Gill <cdgill@cs.wustl.edu> -// -// Based on Command Pattern implementations originally done by -// -// Carlos O'Ryan <coryan@cs.wustl.edu> and -// Douglas C. Schmidt <schmidt@cs.wustl.edu> and -// Sergio Flores-Gaitan <sergio@cs.wustl.edu> -// -// and on STL-style functor implementations originally done by -// -// Irfan Pyarali <irfan@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Functor.h + * + * $Id$ + * + * Non-templatized classes and class template specializations for + * implementing function objects that are used in various places + * in ACE. There are currently two major categories of function + * objects in ACE: GoF Command Pattern objects, and STL-style + * functors for comparison of container elements. The command objects + * are invoked via an execute () method, while the STL-style functors are + * invoked via an operator() () method. + * Non-templatized classes for implementing the GoF Command Pattern, + * also known as functors or function objects. + * + * + * @author Chris Gill <cdgill@cs.wustl.edu> + * @author Based on Command Pattern implementations originally done by + * @author Carlos O'Ryan <coryan@cs.wustl.edu> + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + * @author Sergio Flores-Gaitan <sergio@cs.wustl.edu> + * @author and on STL-style functor implementations originally done by + * @author Irfan Pyarali <irfan@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_FUNCTOR_H #define ACE_FUNCTOR_H @@ -49,30 +42,34 @@ // GOF Command Pattern Classes and Template Specializations // ////////////////////////////////////////////////////////////// +/** + * @class ACE_Command_Base + * + * @brief Defines an abstract class that allows us to invoke commands + * without knowing anything about the implementation. + * + * This class declares an interface to execute a command + * independent of the effect of the command, or the objects used + * to implement it. + */ class ACE_Export ACE_Command_Base { - // = TITLE - // Defines an abstract class that allows us to invoke commands - // without knowing anything about the implementation. - // - // = DESCRIPTION - // This class declares an interface to execute a command - // independent of the effect of the command, or the objects used - // to implement it. public: // = Initialization and termination methods. + /// Default constructor. ACE_Command_Base (void); - // Default constructor. + /// Virtaul destructor. virtual ~ACE_Command_Base (void); - // Virtaul destructor. + /** + * Invokes the method encapsulated by the command, passing along the + * passed argument (if any). Users of classes derived from this + * class must ensure that the resulting invocation can tolerate a + * null void pointer being passed, or otherwise ensure that this + * will never occur. + */ virtual int execute (void *arg = 0) = 0; - // Invokes the method encapsulated by the command, passing along the - // passed argument (if any). Users of classes derived from this - // class must ensure that the resulting invocation can tolerate a - // null void pointer being passed, or otherwise ensure that this - // will never occur. }; //////////////////////////////////////////////////////////// @@ -87,154 +84,196 @@ template <class TYPE> class ACE_Equal_To; template <class TYPE> class ACE_Less_Than; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Hash<char> + * + * @brief Function object for hashing a char + */ class ACE_Export ACE_Hash<char> { - // = TITLE - // Function object for hashing a char public: + /// Simply returns t u_long operator () (char t) const; - // Simply returns t }; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Hash<signed + * + * @brief Function object for hashing a signed char + */ class ACE_Export ACE_Hash<signed char> { - // = TITLE - // Function object for hashing a signed char public: + /// Simply returns t u_long operator () (signed char t) const; - // Simply returns t }; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Hash<unsigned + * + * @brief Function object for hashing an unsigned char + */ class ACE_Export ACE_Hash<unsigned char> { - // = TITLE - // Function object for hashing an unsigned char public: + /// Simply returns t u_long operator () (unsigned char t) const; - // Simply returns t }; // @@ ADD HASHES FOR ACE TYPES ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Hash<ACE_INT16> + * + * @brief Function object for hashing a 16-bit signed number + */ class ACE_Export ACE_Hash<ACE_INT16> { - // = TITLE - // Function object for hashing a 16-bit signed number public: + /// Simply returns t u_long operator () (ACE_INT16 t) const; - // Simply returns t }; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Hash<ACE_UINT16> + * + * @brief Function object for hashing a 16-bit unsigned number + */ class ACE_Export ACE_Hash<ACE_UINT16> { - // = TITLE - // Function object for hashing a 16-bit unsigned number public: + /// Simply returns t u_long operator () (ACE_UINT16 t) const; - // Simply returns t }; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Hash<ACE_INT32> + * + * @brief Function object for hashing a 32-bit signed number + */ class ACE_Export ACE_Hash<ACE_INT32> { - // = TITLE - // Function object for hashing a 32-bit signed number public: + /// Simply returns t u_long operator () (ACE_INT32 t) const; - // Simply returns t }; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Hash<ACE_UINT32> + * + * @brief Function object for hashing a 32-bit unsigned number + */ class ACE_Export ACE_Hash<ACE_UINT32> { - // = TITLE - // Function object for hashing a 32-bit unsigned number public: + /// Simply returns t u_long operator () (ACE_UINT32 t) const; - // Simply returns t }; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Hash<ACE_UINT64> + * + * @brief Function object for hashing a 64-bit unsigned number + */ class ACE_Export ACE_Hash<ACE_UINT64> { - // = TITLE - // Function object for hashing a 64-bit unsigned number public: + /// Simply returns t u_long operator () (ACE_UINT64 t) const; - // Simply returns t }; // @@ DONE ADDING HASHES FOR ACE TYPES ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Hash<const + * + * @brief Function object for hashing a const string + */ class ACE_Export ACE_Hash<const ACE_TCHAR *> { - // = TITLE - // Function object for hashing a const string public: + /// Calls ACE::hash_pjw u_long operator () (const ACE_TCHAR *t) const; - // Calls ACE::hash_pjw }; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Hash<ACE_TCHAR + * + * @brief Function object for hashing a string + */ class ACE_Export ACE_Hash<ACE_TCHAR *> { - // = TITLE - // Function object for hashing a string public: + /// Calls ACE::hash_pjw u_long operator () (const ACE_TCHAR *t) const; - // Calls ACE::hash_pjw }; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Equal_To<const + * + * @brief Function object for determining whether two const strings are equal. + */ class ACE_Export ACE_Equal_To<const ACE_TCHAR *> { - // = TITLE - // Function object for determining whether two const strings are equal. public: + /// Simply calls ACE_OS::strcmp int operator () (const ACE_TCHAR *lhs, const ACE_TCHAR *rhs) const; - // Simply calls ACE_OS::strcmp }; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Equal_To<ACE_TCHAR + * + * @brief Function object for determining whether two non-const + * strings are equal. + */ class ACE_Export ACE_Equal_To<ACE_TCHAR *> { - // = TITLE - // Function object for determining whether two non-const - // strings are equal. public: + /// Simply calls ACE_OS::strcmp int operator () (const ACE_TCHAR *lhs, const ACE_TCHAR *rhs) const; - // Simply calls ACE_OS::strcmp }; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Less_Than<const + * + * @brief Function object for determining whether the first const string + * is less than the second const string. + */ class ACE_Export ACE_Less_Than<const ACE_TCHAR *> { - // = TITLE - // Function object for determining whether the first const string - // is less than the second const string. public: + /// Simply calls ACE_OS::strcmp int operator () (const ACE_TCHAR *lhs, const ACE_TCHAR *rhs) const; - // Simply calls ACE_OS::strcmp }; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Less_Than<ACE_TCHAR + * + * @brief Function object for determining whether the first string + * is less than the second string. + */ class ACE_Export ACE_Less_Than<ACE_TCHAR *> { - // = TITLE - // Function object for determining whether the first string - // is less than the second string. public: + /// Simply calls ACE_OS::strcmp int operator () (const ACE_TCHAR *lhs, const ACE_TCHAR *rhs) const; - // Simply calls ACE_OS::strcmp }; #if defined (__ACE_INLINE__) diff --git a/ace/Functor_T.h b/ace/Functor_T.h index d3a59fa7749..32101c32abe 100644 --- a/ace/Functor_T.h +++ b/ace/Functor_T.h @@ -1,37 +1,30 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Functor_T.h -// -// = DESCRIPTION -// Templatized classes for implementing function objects that are -// used in various places in ACE. There are currently two major -// categories of function objects in ACE: GOF Command Pattern -// objects, and STL-style functors for comparison of container -// elements. The command objects are invoked via an <execute> -// method, while the STL-style functors are invoked via an -// <operator()> method. -// -// = AUTHOR -// Chris Gill <cdgill@cs.wustl.edu> -// -// Based on Command Pattern implementations originally done by -// -// Carlos O'Ryan <coryan@cs.wustl.edu>, -// Douglas C. Schmidt <schmidt@cs.wustl.edu>, and -// Sergio Flores-Gaitan <sergio@cs.wustl.edu> -// -// and on STL-style functor implementations originally done by -// -// Irfan Pyarali <irfan@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Functor_T.h + * + * $Id$ + * + * Templatized classes for implementing function objects that are + * used in various places in ACE. There are currently two major + * categories of function objects in ACE: GOF Command Pattern + * objects, and STL-style functors for comparison of container + * elements. The command objects are invoked via an <execute> + * method, while the STL-style functors are invoked via an + * <operator()> method. + * + * + * @author Chris Gill <cdgill@cs.wustl.edu> + * @author Based on Command Pattern implementations originally done by + * @author Carlos O'Ryan <coryan@cs.wustl.edu> + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + * @author Sergio Flores-Gaitan <sergio@cs.wustl.edu> + * @author and on STL-style functor implementations originally done by + * @author Irfan Pyarali <irfan@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_FUNCTOR_T_H #define ACE_FUNCTOR_T_H @@ -47,85 +40,99 @@ // GOF Command Pattern Templates // /////////////////////////////////// +/** + * @class ACE_Command_Callback + * + * @brief Defines a class template that allows us to invoke a GOF + * command style callback to an object without knowing anything + * about the object except its type. + * + * This class declares an interface to execute operations, + * binding a RECEIVER object with an ACTION. The RECEIVER knows + * how to implement the operation. A class can invoke operations + * without knowing anything about it, or how it was implemented. + */ template <class RECEIVER, class ACTION> class ACE_Command_Callback : public ACE_Command_Base { - // = TITLE - // Defines a class template that allows us to invoke a GOF - // command style callback to an object without knowing anything - // about the object except its type. - // - // = DESCRIPTION - // This class declares an interface to execute operations, - // binding a RECEIVER object with an ACTION. The RECEIVER knows - // how to implement the operation. A class can invoke operations - // without knowing anything about it, or how it was implemented. public: + /// Constructor: sets the <receiver_> of the Command to recvr, and the + /// <action_> of the Command to <action>. ACE_Command_Callback (RECEIVER &recvr, ACTION action); - // Constructor: sets the <receiver_> of the Command to recvr, and the - // <action_> of the Command to <action>. + /// Virtual destructor. virtual ~ACE_Command_Callback (void); - // Virtual destructor. + /// Invokes the method <action_> from the object <receiver_>. virtual int execute (void *arg = 0); - // Invokes the method <action_> from the object <receiver_>. private: + /// Object where the method resides. RECEIVER &receiver_; - // Object where the method resides. + /// Method that is going to be invoked. ACTION action_; - // Method that is going to be invoked. }; ///////////////////////////////// // STL-style Functor Templates // ///////////////////////////////// +/** + * @class ACE_Hash + * + * @brief Function object for hashing + */ template <class TYPE> class ACE_Hash { - // = TITLE - // Function object for hashing public: + /// Simply calls t.hash () u_long operator () (const TYPE &t) const; - // Simply calls t.hash () }; +/** + * @class ACE_Pointer_Hash + * + * @brief Function object for hashing pointers + */ template <class TYPE> class ACE_Pointer_Hash { - // = TITLE - // Function object for hashing pointers public: + /// Simply returns t. u_long operator () (TYPE t) const; - // Simply returns t. }; +/** + * @class ACE_Equal_To + * + * @brief Function object for comparing two objects of + * the given type for equality. + */ template <class TYPE> class ACE_Equal_To { - // = TITLE - // Function object for comparing two objects of - // the given type for equality. public: + /// Simply calls operator== int operator () (const TYPE &lhs, const TYPE &rhs) const; - // Simply calls operator== }; +/** + * @class ACE_Less_Than + * + * @brief Function object for determining whether the first object of + * the given type is less than the second object of the same + * type. + */ template <class TYPE> class ACE_Less_Than { - // = TITLE - // Function object for determining whether the first object of - // the given type is less than the second object of the same - // type. public: + /// Simply calls operator< int operator () (const TYPE &lhs, const TYPE &rhs) const; - // Simply calls operator< }; #if defined (__ACE_INLINE__) diff --git a/ace/Future.h b/ace/Future.h index 9aaf6362c66..0faf9578d61 100644 --- a/ace/Future.h +++ b/ace/Future.h @@ -1,21 +1,18 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Future.h -// -// = AUTHOR (S) -// Andres Kruse <Andres.Kruse@cern.ch>, -// Douglas C. Schmidt <schmidt@cs.wustl.edu>, -// Per Andersson <Per.Andersson@hfera.ericsson.se>, and -// John Tucker <jtucker@infoglide.com> -// -// ============================================================================ + +//============================================================================= +/** + * @file Future.h + * + * $Id$ + * + * @author Andres Kruse <Andres.Kruse@cern.ch> + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + * @author Per Andersson <Per.Andersson@hfera.ericsson.se> + * @author and John Tucker <jtucker@infoglide.com> + */ +//============================================================================= + #ifndef ACE_FUTURE_H #define ACE_FUTURE_H @@ -37,17 +34,20 @@ template <class T> class ACE_Future_Observer; template <class T> class ACE_Future_Rep; template <class T> class ACE_Future; +/** + * @class ACE_Future_Holder + * + * @brief Implementation of object which has holds ACE_Future. + */ template <class T> class ACE_Export ACE_Future_Holder { - // = TITLE - // Implementation of object which has holds ACE_Future. public: ACE_Future_Holder (const ACE_Future<T> &future); ~ACE_Future_Holder (void); + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. ACE_Future<T> item_; @@ -55,133 +55,150 @@ protected: ACE_Future_Holder (void); }; +/** + * @class ACE_Future_Observer + * + * @brief ACE_Future_Observer<T> + * + * An ACE_Future_Observer object implements an object that is + * subscribed with an ACE_Future object so that it may be + * notified when the value of the ACE_Future object is + * written to by a writer thread. + * It uses the Observer pattern + */ template <class T> class ACE_Future_Observer { - // = TITLE - // ACE_Future_Observer<T> - // - // = DESCRIPTION - // An ACE_Future_Observer object implements an object that is - // subscribed with an ACE_Future object so that it may be - // notified when the value of the ACE_Future object is - // written to by a writer thread. - // - // It uses the Observer pattern public: // = Destructor virtual ~ACE_Future_Observer (void); + /// Called by the ACE_Future in which we are subscribed to when + /// its value is written to. virtual void update (const ACE_Future<T> &future) = 0; - // Called by the ACE_Future in which we are subscribed to when - // its value is written to. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Constructor ACE_Future_Observer (void); }; +/** + * @class ACE_Future_Rep + * + * @brief ACE_Future_Rep<T> + * + * An ACE_Future_Rep<T> object encapsules a pointer to an object + * of class T which is the result of an asynchronous method + * invocation. It is pointed to by ACE_Future<T> object[s] and + * only accessible through them. + */ template <class T> class ACE_Future_Rep { - // = TITLE - // ACE_Future_Rep<T> - // - // = DESCRIPTION - // An ACE_Future_Rep<T> object encapsules a pointer to an object - // of class T which is the result of an asynchronous method - // invocation. It is pointed to by ACE_Future<T> object[s] and - // only accessible through them. private: friend class ACE_Future<T>; + /** + * Set the result value. The specified <caller> represents the + * future that invoked this <set> method, which is used to notify + * the list of future observers. Returns 0 for success, -1 on error. + * This function only has an effect the first time it is called for + * the object. Subsequent calls return 0 (success) but have no effect. + */ int set (const T &r, ACE_Future<T> &caller); - // Set the result value. The specified <caller> represents the - // future that invoked this <set> method, which is used to notify - // the list of future observers. Returns 0 for success, -1 on error. - // This function only has an effect the first time it is called for - // the object. Subsequent calls return 0 (success) but have no effect. + /// Wait up to <tv> time to get the <value>. Note that <tv> must be + /// specified in absolute time rather than relative time. int get (T &value, ACE_Time_Value *tv); - // Wait up to <tv> time to get the <value>. Note that <tv> must be - // specified in absolute time rather than relative time. + /** + * Attaches the specified observer to a subject (i.e. the + * <ACE_Future_Rep>). The update method of the specified subject will + * be invoked with a copy of the written-to <ACE_Future> as input when + * the result gets set. + * + * Returns 0 if the observer is successfully attached, 1 if the + * observer is already attached, and -1 if failures occur. + */ int attach (ACE_Future_Observer<T> *observer, ACE_Future<T> &caller); - // Attaches the specified observer to a subject (i.e. the - // <ACE_Future_Rep>). The update method of the specified subject will - // be invoked with a copy of the written-to <ACE_Future> as input when - // the result gets set. - // - // Returns 0 if the observer is successfully attached, 1 if the - // observer is already attached, and -1 if failures occur. + /** + * Detaches the specified observer from a subject (i.e. the + * <ACE_Future_Rep>). The update method of the specified subject will + * not be invoked when the <ACE_Future_Rep>s result gets set. Returns + * 1 if the specified observer was actually attached to the subject + * prior to this call and 0 if was not. + * + * Returns 0 if the observer was successfully detached, and -1 if the + * observer was not attached in the first place. + */ int detach (ACE_Future_Observer<T> *observer); - // Detaches the specified observer from a subject (i.e. the - // <ACE_Future_Rep>). The update method of the specified subject will - // not be invoked when the <ACE_Future_Rep>s result gets set. Returns - // 1 if the specified observer was actually attached to the subject - // prior to this call and 0 if was not. - // - // Returns 0 if the observer was successfully detached, and -1 if the - // observer was not attached in the first place. + /** + * Type conversion. will block forever until the result is + * available. Note that this method is going away in a subsequent + * release since it doesn't distinguish between failure results and + * success results (exceptions should be used, but they aren't + * portable...). The <get> method should be used instead since it + * separates the error value from the result, and also permits + * timeouts. + */ operator T (); - // Type conversion. will block forever until the result is - // available. Note that this method is going away in a subsequent - // release since it doesn't distinguish between failure results and - // success results (exceptions should be used, but they aren't - // portable...). The <get> method should be used instead since it - // separates the error value from the result, and also permits - // timeouts. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. // = Encapsulate reference count and object lifetime of instances. // These methods must go after the others to work around a bug with // Borland's C++ Builder... + /// Create a ACE_Future_Rep<T> and initialize the reference count. static ACE_Future_Rep<T> *create (void); - // Create a ACE_Future_Rep<T> and initialize the reference count. + /** + * Increase the reference count and return argument. Uses the + * attribute "value_ready_mutex_" to synchronize reference count + * updating. + * + * Precondition (rep != 0). + */ static ACE_Future_Rep<T> *attach (ACE_Future_Rep<T> *&rep); - // Increase the reference count and return argument. Uses the - // attribute "value_ready_mutex_" to synchronize reference count - // updating. - // - // Precondition (rep != 0). + /** + * Decreases the reference count and and deletes rep if there are no + * more references to rep. + * + * Precondition (rep != 0) + */ static void detach (ACE_Future_Rep<T> *&rep); - // Decreases the reference count and and deletes rep if there are no - // more references to rep. - // - // Precondition (rep != 0) + /** + * Decreases the rep's reference count and and deletes rep if there + * are no more references to rep. Then assigns new_rep to rep. + * + * Precondition (rep != 0 && new_rep != 0) + */ static void assign (ACE_Future_Rep<T> *&rep, ACE_Future_Rep<T> *new_rep); - // Decreases the rep's reference count and and deletes rep if there - // are no more references to rep. Then assigns new_rep to rep. - // - // Precondition (rep != 0 && new_rep != 0) + /// Is result available? int ready (void); - // Is result available? + /// Pointer to the result. T *value_; - // Pointer to the result. + /// Reference count. int ref_count_; - // Reference count. typedef ACE_Future_Observer<T> OBSERVER; @@ -189,8 +206,8 @@ private: typedef ACE_Unbounded_Set<OBSERVER *> OBSERVER_COLLECTION; + /// Keep a list of ACE_Future_Observers unread by client's reader thread. OBSERVER_COLLECTION observer_collection_; - // Keep a list of ACE_Future_Observers unread by client's reader thread. // = Condition variable and mutex that protect the <value_>. ACE_Condition_Thread_Mutex value_ready_; @@ -202,123 +219,140 @@ private: ~ACE_Future_Rep (void); }; +/** + * @class ACE_Future + * + * @brief This class implements a ``single write, multiple read'' + * pattern that can be used to return results from asynchronous + * method invocations. + */ template <class T> class ACE_Future { - // = TITLE - // This class implements a ``single write, multiple read'' - // pattern that can be used to return results from asynchronous - // method invocations. public: // = Initialization and termination methods. + /// Constructor. ACE_Future (void); - // Constructor. + /// Copy constructor binds <this> and <r> to the same + /// <ACE_Future_Rep>. An <ACE_Future_Rep> is created if necessary. ACE_Future (const ACE_Future<T> &r); - // Copy constructor binds <this> and <r> to the same - // <ACE_Future_Rep>. An <ACE_Future_Rep> is created if necessary. + /// Constructor that initialises an <ACE_Future> to point to the + /// result <r> immediately. ACE_Future (const T &r); - // Constructor that initialises an <ACE_Future> to point to the - // result <r> immediately. + /// Destructor. ~ACE_Future (void); - // Destructor. + /// Assignment operator that binds <this> and <r> to the same + /// <ACE_Future_Rep>. An <ACE_Future_Rep> is created if necessary. void operator = (const ACE_Future<T> &r); - // Assignment operator that binds <this> and <r> to the same - // <ACE_Future_Rep>. An <ACE_Future_Rep> is created if necessary. + /// Cancel an <ACE_Future> and assign the value <r>. It is used if a + /// client does not want to wait for <T> to be produced. int cancel (const T &r); - // Cancel an <ACE_Future> and assign the value <r>. It is used if a - // client does not want to wait for <T> to be produced. + /** + * Cancel an <ACE_Future>. Put the future into its initial + * state. Returns 0 on succes and -1 on failure. It is now possible + * to reuse the ACE_Future<T>. But remember, the ACE_Future<T> + * is now bound to a new ACE_Future_Rep<T>. + */ int cancel (void); - // Cancel an <ACE_Future>. Put the future into its initial - // state. Returns 0 on succes and -1 on failure. It is now possible - // to reuse the ACE_Future<T>. But remember, the ACE_Future<T> - // is now bound to a new ACE_Future_Rep<T>. + /** + * Equality operator that returns 1 if both ACE_Future<T> objects + * point to the same ACE_Future_Rep<T> object. Attention: It also + * returns 1 if both objects have just been instantiated and not + * used yet. + */ int operator == (const ACE_Future<T> &r) const; - // Equality operator that returns 1 if both ACE_Future<T> objects - // point to the same ACE_Future_Rep<T> object. Attention: It also - // returns 1 if both objects have just been instantiated and not - // used yet. + /// Inequality operator, which is the opposite of equality. int operator != (const ACE_Future<T> &r) const; - // Inequality operator, which is the opposite of equality. + /** + * Make the result available. Is used by the server thread to give + * the result to all waiting clients. Returns 0 for success, -1 on failure. + * This function only has an effect the first time it is called for + * the object (actually, the first time the underlying ACE_Future_Rep has a + * value assigned to it). Subsequent calls return 0 (success) but have no + * effect. + */ int set (const T &r); - // Make the result available. Is used by the server thread to give - // the result to all waiting clients. Returns 0 for success, -1 on failure. - // This function only has an effect the first time it is called for - // the object (actually, the first time the underlying ACE_Future_Rep has a - // value assigned to it). Subsequent calls return 0 (success) but have no - // effect. + /// Wait up to <tv> time to get the <value>. Note that <tv> must be + /// specified in absolute time rather than relative time. int get (T &value, ACE_Time_Value *tv = 0); - // Wait up to <tv> time to get the <value>. Note that <tv> must be - // specified in absolute time rather than relative time. + /** + * Type conversion, which obtains the result of the asynchronous + * method invocation. Will block forever. Note that this method is + * going away in a subsequent release since it doesn't distinguish + * between failure results and success results (exceptions should be + * used, but they aren't portable...). The <get> method should be + * used instead since it separates the error value from the result, + * and also permits timeouts. + */ operator T (); - // Type conversion, which obtains the result of the asynchronous - // method invocation. Will block forever. Note that this method is - // going away in a subsequent release since it doesn't distinguish - // between failure results and success results (exceptions should be - // used, but they aren't portable...). The <get> method should be - // used instead since it separates the error value from the result, - // and also permits timeouts. + /// Check if the result is available. int ready (void); - // Check if the result is available. + /** + * Attaches the specified observer to a subject (i.e. the + * <ACE_Future>). The update method of the specified subject will be + * invoked with a copy of the associated <ACE_Future> as input when + * the result gets set. If the result is already set when this + * method gets invoked, then the update method of the specified + * subject will be invoked immediately. + * + * Returns 0 if the observer is successfully attached, 1 if the + * observer is already attached, and -1 if failures occur. + */ int attach (ACE_Future_Observer<T> *observer); - // Attaches the specified observer to a subject (i.e. the - // <ACE_Future>). The update method of the specified subject will be - // invoked with a copy of the associated <ACE_Future> as input when - // the result gets set. If the result is already set when this - // method gets invoked, then the update method of the specified - // subject will be invoked immediately. - // - // Returns 0 if the observer is successfully attached, 1 if the - // observer is already attached, and -1 if failures occur. + /** + * Detaches the specified observer from a subject (i.e. the + * <ACE_Future_Rep>). The update method of the specified subject will + * not be invoked when the <ACE_Future_Reps> result gets set. Returns + * 1 if the specified observer was actually attached to the subject + * prior to this call and 0 if was not. + * + * Returns 0 if the observer was successfully detached, and -1 if the + * observer was not attached in the first place. + */ int detach (ACE_Future_Observer<T> *observer); - // Detaches the specified observer from a subject (i.e. the - // <ACE_Future_Rep>). The update method of the specified subject will - // not be invoked when the <ACE_Future_Reps> result gets set. Returns - // 1 if the specified observer was actually attached to the subject - // prior to this call and 0 if was not. - // - // Returns 0 if the observer was successfully detached, and -1 if the - // observer was not attached in the first place. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /** + * Get the underlying <ACE_Future_Rep>*. Note that this method should + * rarely, if ever, be used and that modifying the undlerlying <ACE_Future_Rep>* + * should be done with extreme caution. + */ ACE_Future_Rep<T> *get_rep (void); - // Get the underlying <ACE_Future_Rep>*. Note that this method should - // rarely, if ever, be used and that modifying the undlerlying <ACE_Future_Rep>* - // should be done with extreme caution. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Do not allow new operator. void *operator new (size_t nbytes); - // Do not allow new operator. + /// Do not allow delete operator void operator delete (void *); - // Do not allow delete operator + /// Do not allow address-of operator. void operator & (); - // Do not allow address-of operator. // the ACE_Future_Rep + /// Protect operations on the <Future>. typedef ACE_Future_Rep<T> FUTURE_REP; FUTURE_REP *future_rep_; - // Protect operations on the <Future>. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/Future_Set.h b/ace/Future_Set.h index eaecada4dc3..17bda22c188 100644 --- a/ace/Future_Set.h +++ b/ace/Future_Set.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Future_Set.h -// -// = AUTHOR (S) -// John Tucker <jtucker@infoglide.com> -// -// ============================================================================ + +//============================================================================= +/** + * @file Future_Set.h + * + * $Id$ + * + * @author John Tucker <jtucker@infoglide.com> + */ +//============================================================================= + #ifndef ACE_FUTURE_SET_H #define ACE_FUTURE_SET_H @@ -29,50 +26,57 @@ #if defined (ACE_HAS_THREADS) +/** + * @class ACE_Future_Set + * + * @brief This class implements a mechanism which allows the values of + * a collections of <ACE_Future> objects to be accessed by + * reader threads as they become available. + */ template <class T> class ACE_Future_Set : public ACE_Future_Observer<T> { - // = TITLE - // This class implements a mechanism which allows the values of - // a collections of <ACE_Future> objects to be accessed by - // reader threads as they become available. public: // = Initialization and termination methods. + /// Constructor. ACE_Future_Set (ACE_Message_Queue<ACE_SYNCH> *future_notification_queue_ = 0); - // Constructor. + /// Destructor. ~ACE_Future_Set (void); - // Destructor. + /// Return 1 if their are no <ACE_Future> objects left on its queue and + /// 0 otherwise int is_empty (void) const; - // Return 1 if their are no <ACE_Future> objects left on its queue and - // 0 otherwise + /** + * Enqueus the given <ACE_Future> into this objects queue when it is + * readable. + * + * Returns 0 if the future is successfully inserted, 1 if the + * future is already inserted, and -1 if failures occur. + */ int insert (ACE_Future<T> &future); - // Enqueus the given <ACE_Future> into this objects queue when it is - // readable. - // - // Returns 0 if the future is successfully inserted, 1 if the - // future is already inserted, and -1 if failures occur. + /** + * Wait up to <tv> time to get the <value>. Note that <tv> must be + * specified in absolute time rather than relative time.); get the + * next <ACE_Future> that is readable. If <tv> = 0, the will block + * forever. + * + * If a readable future becomes available, then the input result + * will be assigned with it and 1 will will be returned. If the set + * is empty, then 0 is returned. + */ int next_readable (ACE_Future<T> &result, ACE_Time_Value *tv = 0); - // Wait up to <tv> time to get the <value>. Note that <tv> must be - // specified in absolute time rather than relative time.); get the - // next <ACE_Future> that is readable. If <tv> = 0, the will block - // forever. - // - // If a readable future becomes available, then the input result - // will be assigned with it and 1 will will be returned. If the set - // is empty, then 0 is returned. + /// Called by the <ACE_Future> subject in which we are subscribed to + /// when its value is written to. virtual void update (const ACE_Future<T> &future); - // Called by the <ACE_Future> subject in which we are subscribed to - // when its value is written to. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: // = Disallow these operations. @@ -95,16 +99,16 @@ private: FUTURE_REP_COMPARE, ACE_Null_Mutex> FUTURE_HASH_MAP; + /// Map of <ACE_Futures>, subjects, which have not been written to by + /// client's writer thread. FUTURE_HASH_MAP future_map_; - // Map of <ACE_Futures>, subjects, which have not been written to by - // client's writer thread. + /// Message queue for notifying the reader thread of <ACE_Futures> which + /// have been written to by client's writer thread. ACE_Message_Queue<ACE_SYNCH> *future_notification_queue_; - // Message queue for notifying the reader thread of <ACE_Futures> which - // have been written to by client's writer thread. + /// Keeps track of whether we need to delete the message queue. int delete_queue_; - // Keeps track of whether we need to delete the message queue. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/Get_Opt.h b/ace/Get_Opt.h index e645328f0a9..c8d9921e8e9 100644 --- a/ace/Get_Opt.h +++ b/ace/Get_Opt.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Get_Opt.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Get_Opt.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_GET_OPT_H #define ACE_GET_OPT_H @@ -24,109 +21,121 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Get_Opt + * + * @brief Iterator for parsing command-line arguments. + * + * This is a C++ wrapper for getopt(3c). + */ class ACE_Export ACE_Get_Opt { - // = TITLE - // Iterator for parsing command-line arguments. - // - // = DESCRIPTION - // This is a C++ wrapper for getopt(3c). public: + /** + * Initialize the internal data when the first call is made. Start + * processing options with <argv>-element 0 + <skip_argv0>; the + * sequence of previously skipped non-option <argv>-elements is + * empty. + * + * <optstring> is a string containing the legitimate option + * characters. A colon in <optstring> means that the previous + * character is an option that wants an argument. The argument is + * taken from the rest of the current <argv>-element, or from the + * following <argv>-element, and returned in <optarg>. + * + * If an option character is seen that is not listed in <optstring>, + * return '?' after printing an error message. If you set <opterr> + * to zero, the error message is suppressed but we still return '?'. + * + * If a char in <optstring> is followed by a colon, that means it + * wants an arg, so the following text in the same <argv>-element, + * or the text of the following <argv>-element, is returned in + * <optarg>. + */ ACE_Get_Opt (int argc, ACE_TCHAR **argv, const ACE_TCHAR *optstring, int skip_argv0 = 1, int report_errors = 0); - // Initialize the internal data when the first call is made. Start - // processing options with <argv>-element 0 + <skip_argv0>; the - // sequence of previously skipped non-option <argv>-elements is - // empty. - // - // <optstring> is a string containing the legitimate option - // characters. A colon in <optstring> means that the previous - // character is an option that wants an argument. The argument is - // taken from the rest of the current <argv>-element, or from the - // following <argv>-element, and returned in <optarg>. - // - // If an option character is seen that is not listed in <optstring>, - // return '?' after printing an error message. If you set <opterr> - // to zero, the error message is suppressed but we still return '?'. - // - // If a char in <optstring> is followed by a colon, that means it - // wants an arg, so the following text in the same <argv>-element, - // or the text of the following <argv>-element, is returned in - // <optarg>. + /// Default dtor. ~ACE_Get_Opt (void); - // Default dtor. + /** + * Scan elements of <argv> (whose length is <argc>) for option + * characters given in <optstring>. + * + * If an element of <argv> starts with '-', and is not exactly "-" + * or "--", then it is an option element. The characters of this + * element (aside from the initial '-') are option characters. If + * <operator()> is called repeatedly, it returns successively each + * of the option characters from each of the option elements. + * + * If <operator()> finds another option character, it returns that + * character, updating <optind> and <nextchar> so that the next call + * to <operator()> can resume the scan with the following option + * character or <argv>-element. + * + * If there are no more option characters, <operator()> returns + * <EOF>. Then <optind> is the index in <argv> of the first + * <argv>-element that is not an option. (The <argv>-elements have + * been permuted so that those that are not options now come last.) + */ int operator () (void); - // Scan elements of <argv> (whose length is <argc>) for option - // characters given in <optstring>. - // - // If an element of <argv> starts with '-', and is not exactly "-" - // or "--", then it is an option element. The characters of this - // element (aside from the initial '-') are option characters. If - // <operator()> is called repeatedly, it returns successively each - // of the option characters from each of the option elements. - // - // If <operator()> finds another option character, it returns that - // character, updating <optind> and <nextchar> so that the next call - // to <operator()> can resume the scan with the following option - // character or <argv>-element. - // - // If there are no more option characters, <operator()> returns - // <EOF>. Then <optind> is the index in <argv> of the first - // <argv>-element that is not an option. (The <argv>-elements have - // been permuted so that those that are not options now come last.) // = Public data members (should be hidden...). + /** + * For communication from <operator()> to the caller. When + * <operator()> finds an option that takes an argument, the argument + * value is returned here. + */ ACE_TCHAR *optarg; - // For communication from <operator()> to the caller. When - // <operator()> finds an option that takes an argument, the argument - // value is returned here. + /** + * Index in <argv> of the next element to be scanned. This is used + * for communication to and from the caller and for communication + * between successive calls to <operator()>. On entry to + * <operator()>, zero means this is the first call; initialize. + * + * When <get_opt> returns <EOF>, this is the index of the first of + * the non-option elements that the caller should itself scan. + * + * Otherwise, <optind> communicates from one call to the next how + * much of <argv> has been scanned so far. + */ int optind; - // Index in <argv> of the next element to be scanned. This is used - // for communication to and from the caller and for communication - // between successive calls to <operator()>. On entry to - // <operator()>, zero means this is the first call; initialize. - // - // When <get_opt> returns <EOF>, this is the index of the first of - // the non-option elements that the caller should itself scan. - // - // Otherwise, <optind> communicates from one call to the next how - // much of <argv> has been scanned so far. + /// Callers store zero here to inhibit the error message for + /// unrecognized options. int opterr; - // Callers store zero here to inhibit the error message for - // unrecognized options. + /// Holds the <argc> count. int argc_; - // Holds the <argc> count. + /// Holds the <argv> pointer. ACE_TCHAR **argv_; - // Holds the <argv> pointer. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /** + * The next char to be scanned in the option-element in which the + * last option character we returned was found. This allows us to + * pick up the scan where we left off. + * + * If this is zero, or a null string, it means resume the scan + * by advancing to the next <argv>-element. + */ ACE_TCHAR *nextchar_; - // The next char to be scanned in the option-element in which the - // last option character we returned was found. This allows us to - // pick up the scan where we left off. - // - // If this is zero, or a null string, it means resume the scan - // by advancing to the next <argv>-element. + /// Holds the option string. const ACE_TCHAR *optstring_; - // Holds the option string. }; #if defined (__ACE_INLINE__) diff --git a/ace/Handle_Gobbler.h b/ace/Handle_Gobbler.h index 6cf11614e76..69b298e18ee 100644 --- a/ace/Handle_Gobbler.h +++ b/ace/Handle_Gobbler.h @@ -1,18 +1,15 @@ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Handle_Gobbler.h -// -// = AUTHOR -// Kirthika Parameswaran <kirthika@cs.wustl.edu> -// Irfan Pyarali <irfan@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Handle_Gobbler.h + * + * $Id$ + * + * @author Kirthika Parameswaran <kirthika@cs.wustl.edu> + * @author Irfan Pyarali <irfan@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_HANDLE_GOBBLER_H #define ACE_HANDLE_GOBBLER_H @@ -26,37 +23,41 @@ #include "ace/Containers_T.h" +/** + * @class ACE_Handle_Gobbler + * + * @brief This class gobbles up handles. + * + * This is useful when we need to control the number of handles + * available for a process. This class is mostly used for + * testing purposes. + */ class ACE_Handle_Gobbler { - // = TITLE - // This class gobbles up handles. - // - // = DESCRIPTION - // This is useful when we need to control the number of handles - // available for a process. This class is mostly used for - // testing purposes. public: + /// Destructor. Cleans up any remaining handles. inline ~ACE_Handle_Gobbler (void); - // Destructor. Cleans up any remaining handles. + /** + * Handles are opened continously until the process runs out of + * them, and then <n_handles_to_keep_available> handles are closed + * (freed) thereby making them usable in the future. + */ inline int consume_handles (size_t n_handles_to_keep_available); - // Handles are opened continously until the process runs out of - // them, and then <n_handles_to_keep_available> handles are closed - // (freed) thereby making them usable in the future. + /// Free up <n_handles>. inline int free_handles (size_t n_handles); - // Free up <n_handles>. + /// All remaining handles are closed. inline void close_remaining_handles (void); - // All remaining handles are closed. private: typedef ACE_Unbounded_Set<ACE_HANDLE> HANDLE_SET; + /// The container which holds the open descriptors. HANDLE_SET handle_set_; - // The container which holds the open descriptors. }; #include "ace/Handle_Gobbler.i" diff --git a/ace/Handle_Ops.h b/ace/Handle_Ops.h index c97d620cf05..73149677edc 100644 --- a/ace/Handle_Ops.h +++ b/ace/Handle_Ops.h @@ -1,16 +1,17 @@ -// $Id$ - -// ======================================================================== -// LIBRARY -// ACE.so -// -// DESCRIPTION -// This class consolidates the operations on the Handles. -// -// AUTHOR -// Priyanka Gontla <pgontla@ece.uci.edu> -// -// ========================================================================= + +//============================================================================= +/** + * @file Handle_Ops.h + * + * $Id$ + * + * This class consolidates the operations on the Handles. + * + * + * @author Priyanka Gontla <pgontla@ece.uci.edu> + */ +//============================================================================= + #ifndef ACE_HANDLE_OPS_H #define ACE_HANDLE_OPS_H @@ -20,16 +21,18 @@ class ACE_Export ACE_Handle_Ops { - public: - // = Operations on HANDLEs. +public: + // = Operations on HANDLEs. + /** + * Wait up to <timeout> amount of time to actively open a device. + * This method doesn't perform the <connect>, it just does the timed + * wait... + */ static ACE_HANDLE handle_timed_open (ACE_Time_Value *timeout, const ACE_TCHAR *name, int flags, int perms); - // Wait up to <timeout> amount of time to actively open a device. - // This method doesn't perform the <connect>, it just does the timed - // wait... }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/Handle_Set.h b/ace/Handle_Set.h index aacb7609b05..7dff63fb650 100644 --- a/ace/Handle_Set.h +++ b/ace/Handle_Set.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Handle_Set.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Handle_Set.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_HANDLE_SET_H #define ACE_HANDLE_SET_H @@ -24,16 +21,18 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Handle_Set + * + * @brief C++ wrapper facade for the socket <fd_set> abstraction. + * + * This abstraction is a very efficient wrapper facade over + * <fd_set>. In particular, no range checking is performed, so + * it's important not to set or clear bits that are outside the + * <ACE_DEFAULT_SELECT_REACTOR_SIZE>. + */ class ACE_Export ACE_Handle_Set { - // = TITLE - // C++ wrapper facade for the socket <fd_set> abstraction. - // - // = DESCRIPTION - // This abstraction is a very efficient wrapper facade over - // <fd_set>. In particular, no range checking is performed, so - // it's important not to set or clear bits that are outside the - // <ACE_DEFAULT_SELECT_REACTOR_SIZE>. public: friend class ACE_Handle_Set_Iterator; @@ -45,82 +44,88 @@ public: }; // = Initialization methods. + /// Constructor, initializes the bitmask to all 0s. ACE_Handle_Set (void); - // Constructor, initializes the bitmask to all 0s. + /** + * Constructor, initializes the handle set from a given mask. + * <ACE_FD_SET_TYPE> is a <typedef> based on the platform's native + * type used for masks passed to <select>. + */ ACE_Handle_Set (const ACE_FD_SET_TYPE &mask); - // Constructor, initializes the handle set from a given mask. - // <ACE_FD_SET_TYPE> is a <typedef> based on the platform's native - // type used for masks passed to <select>. #if defined (ACE_HAS_WINCE) + /// Default dtor. ~ACE_Handle_Set (void); - // Default dtor. #endif /* ACE_HAS_WINCE */ // = Methods for manipulating bitsets. + /// Initialize the bitmask to all 0s and reset the associated fields. void reset (void); - // Initialize the bitmask to all 0s and reset the associated fields. + /** + * Checks whether <handle> is enabled. No range checking is + * performed so <handle> must be less than + * <ACE_DEFAULT_SELECT_REACTOR_SIZE>. + */ int is_set (ACE_HANDLE handle) const; - // Checks whether <handle> is enabled. No range checking is - // performed so <handle> must be less than - // <ACE_DEFAULT_SELECT_REACTOR_SIZE>. + /// Enables the <handle>. No range checking is performed so <handle> + /// must be less than <ACE_DEFAULT_SELECT_REACTOR_SIZE>. void set_bit (ACE_HANDLE handle); - // Enables the <handle>. No range checking is performed so <handle> - // must be less than <ACE_DEFAULT_SELECT_REACTOR_SIZE>. + /// Disables the <handle>. No range checking is performed so + /// <handle> must be less than <ACE_DEFAULT_SELECT_REACTOR_SIZE>. void clr_bit (ACE_HANDLE handle); - // Disables the <handle>. No range checking is performed so - // <handle> must be less than <ACE_DEFAULT_SELECT_REACTOR_SIZE>. + /// Returns a count of the number of enabled bits. int num_set (void) const; - // Returns a count of the number of enabled bits. + /// Returns the number of the large bit. ACE_HANDLE max_set (void) const; - // Returns the number of the large bit. + /** + * Rescan the underlying <fd_set> up to handle <max> to find the new + * <max_handle> (highest bit set) and <size> (how many bits set) values. + * This is useful for evaluating the changes after the handle set has + * been manipulated in some way other than member functions; for example, + * after <select> modifies the <fd_set>. + */ void sync (ACE_HANDLE max); - // Rescan the underlying <fd_set> up to handle <max> to find the new - // <max_handle> (highest bit set) and <size> (how many bits set) values. - // This is useful for evaluating the changes after the handle set has - // been manipulated in some way other than member functions; for example, - // after <select> modifies the <fd_set>. + /// Returns a pointer to the underlying <fd_set>. Returns 0 if + /// there are no handle bits set (<size_> == 0). operator fd_set *(); - // Returns a pointer to the underlying <fd_set>. Returns 0 if - // there are no handle bits set (<size_> == 0). + /// Returns a pointer to the underlying <fd_set>. Returns 0 if + /// there are no handle bits set (<size_> == 0). fd_set *fdset (void); - // Returns a pointer to the underlying <fd_set>. Returns 0 if - // there are no handle bits set (<size_> == 0). #if defined (ACE_HAS_BIG_FD_SET) + /// Assignment operator optimizes for cases where <size_> == 0. ACE_Handle_Set & operator= (const ACE_Handle_Set &); - // Assignment operator optimizes for cases where <size_> == 0. #endif /* ACE_HAS_BIG_FD_SET */ + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Size of the set, i.e., a count of the number of enabled bits. int size_; - // Size of the set, i.e., a count of the number of enabled bits. + /// Current max handle. ACE_HANDLE max_handle_; - // Current max handle. #if defined (ACE_HAS_BIG_FD_SET) + /// Current min handle. ACE_HANDLE min_handle_; - // Current min handle. #endif /* ACE_HAS_BIG_FD_SET */ + /// Bitmask. fd_set mask_; - // Bitmask. enum { @@ -131,55 +136,60 @@ private: NBITS = 256 }; + /// Counts the number of bits enabled in N. Uses a table lookup to + /// speed up the count. static int count_bits (u_long n); - // Counts the number of bits enabled in N. Uses a table lookup to - // speed up the count. #if defined (ACE_HAS_BIG_FD_SET) + /// Find the position of the bit counting from right to left. static int bitpos (u_long bit); - // Find the position of the bit counting from right to left. #endif /* ACE_HAS_BIG_FD_SET */ + /// Resets the <max_handle_> after a clear of the original + /// <max_handle_>. void set_max (ACE_HANDLE max); - // Resets the <max_handle_> after a clear of the original - // <max_handle_>. + /// Table that maps bytes to counts of the enabled bits in each value + /// from 0 to 255. static const char nbits_[NBITS]; - // Table that maps bytes to counts of the enabled bits in each value - // from 0 to 255. }; +/** + * @class ACE_Handle_Set_Iterator + * + * @brief Iterator for the <ACE_Handle_Set> abstraction. + */ class ACE_Export ACE_Handle_Set_Iterator { - // = TITLE - // Iterator for the <ACE_Handle_Set> abstraction. public: + /// Constructor. ACE_Handle_Set_Iterator (const ACE_Handle_Set &hs); - // Constructor. + /// Default dtor. ~ACE_Handle_Set_Iterator (void); - // Default dtor. + /** + * "Next" operator. Returns the next unseen <ACE_HANDLE> in the + * <Handle_Set> up to <handle_set_.max_handle_>). When all the + * handles have been seen returns <ACE_INVALID_HANDLE>. Advances + * the iterator automatically, so you need not call <operator++> + * (which is now obsolete). + */ ACE_HANDLE operator () (void); - // "Next" operator. Returns the next unseen <ACE_HANDLE> in the - // <Handle_Set> up to <handle_set_.max_handle_>). When all the - // handles have been seen returns <ACE_INVALID_HANDLE>. Advances - // the iterator automatically, so you need not call <operator++> - // (which is now obsolete). + /// This is a no-op and no longer does anything. It's only here for + /// backwards compatibility. void operator++ (void); - // This is a no-op and no longer does anything. It's only here for - // backwards compatibility. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// The <Handle_Set> we are iterating through. const ACE_Handle_Set &handles_; - // The <Handle_Set> we are iterating through. #if defined (ACE_WIN32) u_int handle_index_; @@ -191,20 +201,20 @@ private: #endif /* ACE_WIN32 */ // Index of the bit we're examining in the current <word_num_> word. + /// Number of the word we're iterating over (typically between 0..7). int word_num_; - // Number of the word we're iterating over (typically between 0..7). #if defined (ACE_HAS_BIG_FD_SET) + /// Number max of the words with a possible bit on. int word_max_; - // Number max of the words with a possible bit on. #endif /* ACE_HAS_BIG_FD_SET */ #if !defined (ACE_WIN32) && !defined (ACE_HAS_BIG_FD_SET) + /// Value of the bits in the word we're iterating on. fd_mask word_val_; - // Value of the bits in the word we're iterating on. #elif !defined (ACE_WIN32) && defined (ACE_HAS_BIG_FD_SET) + /// Value of the bits in the word we're iterating on. u_long word_val_; - // Value of the bits in the word we're iterating on. #endif /* !ACE_WIN32 && !ACE_HAS_BIG_FD_SET */ }; diff --git a/ace/Hash_Cache_Map_Manager_T.h b/ace/Hash_Cache_Map_Manager_T.h index ca3ba4239d6..34eb4b0ef19 100644 --- a/ace/Hash_Cache_Map_Manager_T.h +++ b/ace/Hash_Cache_Map_Manager_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Hash_Cache_Map_Manager.h -// -// = AUTHOR -// Kirthika Parameswaran <kirthika@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Hash_Cache_Map_Manager.h + * + * $Id$ + * + * @author Kirthika Parameswaran <kirthika@cs.wustl.edu> + */ +//============================================================================= + #ifndef HASH_CACHE_MAP_MANAGER_T_H #define HASH_CACHE_MAP_MANAGER_T_H @@ -49,137 +46,156 @@ class ACE_Allocator; // For linkers that cant grok long names. #define ACE_Hash_Cache_Map_Manager AHCMM + /** + * @class ACE_Hash_Cache_Map_Manager + * + * @brief Defines a abstraction which will purge entries from a map. + * The map considered is the ACE_Hash_Map_Manager_Ex. + * + * The Hash_Cache_Map_Manager will manage the map it contains + * and provide purging on demand from the map. The strategy for + * caching is decided by the user and provided to the Cache + * Manager. The Cache Manager acts as a agent and communicates + * between the Map and the Strategy for purging entries from the + * map. To tap the optimal methods like find(key,value,entry) + * present in the ACE_Hash_Map_Manager, + * Hash_Cache_Map_Manager provides extra functionality on top + * of the Cache_Map_Manager. + * No locking mechanism provided since locking at this level + * isnt efficient. Locking has to be provided by the + * application. + */ template <class KEY, class VALUE, class HASH_KEY, class COMPARE_KEYS, class CACHING_STRATEGY, class ATTRIBUTES> class ACE_Hash_Cache_Map_Manager : public ACE_CACHE_MAP_MANAGER { - // = TITLE - // Defines a abstraction which will purge entries from a map. - // The map considered is the ACE_Hash_Map_Manager_Ex. - // - // = DESCRIPTION - // The Hash_Cache_Map_Manager will manage the map it contains - // and provide purging on demand from the map. The strategy for - // caching is decided by the user and provided to the Cache - // Manager. The Cache Manager acts as a agent and communicates - // between the Map and the Strategy for purging entries from the - // map. To tap the optimal methods like find(key,value,entry) - // present in the ACE_Hash_Map_Manager, - // Hash_Cache_Map_Manager provides extra functionality on top - // of the Cache_Map_Manager. - // - // No locking mechanism provided since locking at this level - // isnt efficient. Locking has to be provided by the - // application. public: + /** + * The actual value mapped to the key in the map. The <attributes> + * are used by the strategy and is transparent to the user of this + * class. + */ typedef ACE_Pair<VALUE, ATTRIBUTES> CACHE_VALUE; typedef ACE_Hash_Map_Manager_Ex<KEY, CACHE_VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> HASH_MAP; typedef ACE_Hash_Map_Entry<KEY, CACHE_VALUE> CACHE_ENTRY; typedef KEY key_type; typedef VALUE mapped_type; - // The actual value mapped to the key in the map. The <attributes> - // are used by the strategy and is transparent to the user of this - // class. // = Initialization and termination methods. + /// Initialize a <Hash_Cache_Map_Manager> with <size> entries. ACE_Hash_Cache_Map_Manager (CACHING_STRATEGY &caching_s, size_t size = ACE_DEFAULT_MAP_SIZE, ACE_Allocator *alloc = 0); - // Initialize a <Hash_Cache_Map_Manager> with <size> entries. + /// Close down a <Cache_Map_Manager> and release dynamically allocated + /// resources. ~ACE_Hash_Cache_Map_Manager (void); - // Close down a <Cache_Map_Manager> and release dynamically allocated - // resources. + /** + * Associate <key> with <value>. If <key> is already in the + * MAP then the ENTRY is not changed. Returns 0 if a new entry is + * bound successfully, returns 1 if an attempt is made to bind an + * existing entry, and returns -1 if failures occur. + */ int bind (const KEY &key, const VALUE &value); - // Associate <key> with <value>. If <key> is already in the - // MAP then the ENTRY is not changed. Returns 0 if a new entry is - // bound successfully, returns 1 if an attempt is made to bind an - // existing entry, and returns -1 if failures occur. + /** + * Same as a normal bind, except the cache entry is also passed back + * to the caller. The entry in this case will either be the newly + * created entry, or the existing one. + */ int bind (const KEY &key, const VALUE &value, CACHE_ENTRY *&entry); - // Same as a normal bind, except the cache entry is also passed back - // to the caller. The entry in this case will either be the newly - // created entry, or the existing one. + /// Loopkup entry<key,value> in the cache. int find (const KEY &key, VALUE &value); - // Loopkup entry<key,value> in the cache. + /// Is <key> in the cache? int find (const KEY &key); - // Is <key> in the cache? + /// Obtain the entry when the find succeeds. int find (const KEY &key, CACHE_ENTRY *&entry); - // Obtain the entry when the find succeeds. + /** + * Reassociate the <key> with <value>. If the <key> already exists + * in the cache then returns 1, on a new bind returns 0 and returns + * -1 in case of any failures. + */ int rebind (const KEY &key, const VALUE &value); - // Reassociate the <key> with <value>. If the <key> already exists - // in the cache then returns 1, on a new bind returns 0 and returns - // -1 in case of any failures. + /** + * Reassociate <key> with <value>, storing the old value into the + * "out" parameter <old_value>. The function fails if <key> is not + * in the cache for caches that do not allow user specified keys. + * However, for caches that allow user specified keys, if the key is + * not in the cache, a new <key>/<value> association is created. + */ int rebind (const KEY &key, const VALUE &value, VALUE &old_value); - // Reassociate <key> with <value>, storing the old value into the - // "out" parameter <old_value>. The function fails if <key> is not - // in the cache for caches that do not allow user specified keys. - // However, for caches that allow user specified keys, if the key is - // not in the cache, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old key and value + * into the "out" parameters <old_key> and <old_value>. The + * function fails if <key> is not in the cache for caches that do not + * allow user specified keys. However, for caches that allow user + * specified keys, if the key is not in the cache, a new <key>/<value> + * association is created. + */ int rebind (const KEY &key, const VALUE &value, KEY &old_key, VALUE &old_value); - // Reassociate <key> with <value>, storing the old key and value - // into the "out" parameters <old_key> and <old_value>. The - // function fails if <key> is not in the cache for caches that do not - // allow user specified keys. However, for caches that allow user - // specified keys, if the key is not in the cache, a new <key>/<value> - // association is created. + /** + * Same as a normal rebind, except the cache entry is also passed back + * to the caller. The entry in this case will either be the newly + * created entry, or the existing one. + */ int rebind (const KEY &key, const VALUE &value, CACHE_ENTRY *&entry); - // Same as a normal rebind, except the cache entry is also passed back - // to the caller. The entry in this case will either be the newly - // created entry, or the existing one. + /** + * Associate <key> with <value> if and only if <key> is not in the + * cache. If <key> is already in the cache, then the <value> parameter + * is overwritten with the existing value in the cache. Returns 0 if a + * new <key>/<value> association is created. Returns 1 if an + * attempt is made to bind an existing entry. This function fails + * for maps that do not allow user specified keys. + */ int trybind (const KEY &key, VALUE &value); - // Associate <key> with <value> if and only if <key> is not in the - // cache. If <key> is already in the cache, then the <value> parameter - // is overwritten with the existing value in the cache. Returns 0 if a - // new <key>/<value> association is created. Returns 1 if an - // attempt is made to bind an existing entry. This function fails - // for maps that do not allow user specified keys. + /** + * Same as a normal trybind, except the cache entry is also passed + * back to the caller. The entry in this case will either be the + * newly created entry, or the existing one. + */ int trybind (const KEY &key, VALUE &value, CACHE_ENTRY *&entry); - // Same as a normal trybind, except the cache entry is also passed - // back to the caller. The entry in this case will either be the - // newly created entry, or the existing one. + /// Remove <key> from the cache. int unbind (const KEY &key); - // Remove <key> from the cache. + /// Remove <key> from the cache, and return the <value> associated with + /// <key>. int unbind (const KEY &key, VALUE &value); - // Remove <key> from the cache, and return the <value> associated with - // <key>. + /// Remove entry from map. int unbind (CACHE_ENTRY *entry); - // Remove entry from map. protected: + /// Base class. typedef ACE_CACHE_MAP_MANAGER ACE_HCMM_BASE; - // Base class. }; diff --git a/ace/Hash_Map_Manager.h b/ace/Hash_Map_Manager.h index 2d674f647d8..83738c7fea4 100644 --- a/ace/Hash_Map_Manager.h +++ b/ace/Hash_Map_Manager.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Hash_Map_Manager.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ +//============================================================================= +/** + * @file Hash_Map_Manager.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_HASH_MAP_MANAGER_H #define ACE_HASH_MAP_MANAGER_H diff --git a/ace/Hash_Map_Manager_T.h b/ace/Hash_Map_Manager_T.h index af5a8b1ac41..606a545044b 100644 --- a/ace/Hash_Map_Manager_T.h +++ b/ace/Hash_Map_Manager_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Hash_Map_Manager_T.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Hash_Map_Manager_T.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_HASH_MAP_MANAGER_T_H #define ACE_HASH_MAP_MANAGER_T_H @@ -26,42 +23,45 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Hash_Map_Entry + * + * @brief Define an entry in the hash table. + */ template <class EXT_ID, class INT_ID> class ACE_Hash_Map_Entry { - // = TITLE - // Define an entry in the hash table. public: // = Initialization and termination methods. + /// Constructor. ACE_Hash_Map_Entry (const EXT_ID &ext_id, const INT_ID &int_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *next = 0, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *prev = 0); - // Constructor. + /// Constructor. ACE_Hash_Map_Entry (ACE_Hash_Map_Entry<EXT_ID, INT_ID> *next, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *prev); - // Constructor. # if ! defined (ACE_HAS_BROKEN_NOOP_DTORS) + /// Destructor. ~ACE_Hash_Map_Entry (void); - // Destructor. #endif /* ! defined (ACE_HAS_BROKEN_NOOP_DTORS) */ + /// Key used to look up an entry. EXT_ID ext_id_; - // Key used to look up an entry. + /// The contents of the entry itself. INT_ID int_id_; - // The contents of the entry itself. + /// Pointer to the next item in the bucket of overflow nodes. ACE_Hash_Map_Entry<EXT_ID, INT_ID> *next_; - // Pointer to the next item in the bucket of overflow nodes. + /// Pointer to the prev item in the bucket of overflow nodes. ACE_Hash_Map_Entry<EXT_ID, INT_ID> *prev_; - // Pointer to the prev item in the bucket of overflow nodes. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. }; // Forward decl. @@ -83,22 +83,22 @@ class ACE_Hash_Map_Bucket_Iterator; // Forward decl. class ACE_Allocator; +/** + * @class ACE_Hash_Map_Manager_Ex + * + * @brief Define a map abstraction that efficiently associates + * <EXT_ID>s with <INT_ID>s. + * + * This implementation of a map uses a hash table. Key hashing + * is achieved through the HASH_KEY object and key comparison is + * achieved through the COMPARE_KEYS object. + * This class uses an <ACE_Allocator> to allocate memory. The + * user can make this a persistent class by providing an + * <ACE_Allocator> with a persistable memory pool. + */ template <class EXT_ID, class INT_ID, class HASH_KEY, class COMPARE_KEYS, class ACE_LOCK> class ACE_Hash_Map_Manager_Ex { - // = TITLE - // Define a map abstraction that efficiently associates - // <EXT_ID>s with <INT_ID>s. - // - // = DESCRIPTION - // - // This implementation of a map uses a hash table. Key hashing - // is achieved through the HASH_KEY object and key comparison is - // achieved through the COMPARE_KEYS object. - // - // This class uses an <ACE_Allocator> to allocate memory. The - // user can make this a persistent class by providing an - // <ACE_Allocator> with a persistable memory pool. public: friend class ACE_Hash_Map_Iterator_Base_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK>; friend class ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK>; @@ -126,419 +126,453 @@ public: // = Initialization and termination methods. + /// Initialize a <Hash_Map_Manager_Ex> with default size. ACE_Hash_Map_Manager_Ex (ACE_Allocator *alloc = 0); - // Initialize a <Hash_Map_Manager_Ex> with default size. + /// Initialize a <Hash_Map_Manager_Ex> with size <length>. ACE_Hash_Map_Manager_Ex (size_t size, ACE_Allocator *alloc = 0); - // Initialize a <Hash_Map_Manager_Ex> with size <length>. + /// Initialize a <Hash_Map_Manager_Ex> with <size> elements. int open (size_t size = ACE_DEFAULT_MAP_SIZE, ACE_Allocator *alloc = 0); - // Initialize a <Hash_Map_Manager_Ex> with <size> elements. + /// Close down a <Hash_Map_Manager_Ex> and release dynamically allocated + /// resources. int close (void); - // Close down a <Hash_Map_Manager_Ex> and release dynamically allocated - // resources. + /// Removes all the entries in <Map_Manager_Ex>. int unbind_all (void); - // Removes all the entries in <Map_Manager_Ex>. + /// Initialize a <Hash_Map_Manager_Ex> with size <length>. ~ACE_Hash_Map_Manager_Ex (void); - // Initialize a <Hash_Map_Manager_Ex> with size <length>. + /** + * Associate <ext_id> with <int_id>. If <ext_id> is already in the + * map then the <ACE_Hash_Map_Entry> is not changed. Returns 0 if a + * new entry is bound successfully, returns 1 if an attempt is made + * to bind an existing entry, and returns -1 if failures occur. + */ int bind (const EXT_ID &item, const INT_ID &int_id); - // Associate <ext_id> with <int_id>. If <ext_id> is already in the - // map then the <ACE_Hash_Map_Entry> is not changed. Returns 0 if a - // new entry is bound successfully, returns 1 if an attempt is made - // to bind an existing entry, and returns -1 if failures occur. + /** + * Same as a normal bind, except the map entry is also passed back + * to the caller. The entry in this case will either be the newly + * created entry, or the existing one. + */ int bind (const EXT_ID &ext_id, const INT_ID &int_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry); - // Same as a normal bind, except the map entry is also passed back - // to the caller. The entry in this case will either be the newly - // created entry, or the existing one. + /** + * Associate <ext_id> with <int_id> if and only if <ext_id> is not + * in the map. If <ext_id> is already in the map then the <int_id> + * parameter is assigned the existing value in the map. Returns 0 + * if a new entry is bound successfully, returns 1 if an attempt is + * made to bind an existing entry, and returns -1 if failures occur. + */ int trybind (const EXT_ID &ext_id, INT_ID &int_id); - // Associate <ext_id> with <int_id> if and only if <ext_id> is not - // in the map. If <ext_id> is already in the map then the <int_id> - // parameter is assigned the existing value in the map. Returns 0 - // if a new entry is bound successfully, returns 1 if an attempt is - // made to bind an existing entry, and returns -1 if failures occur. + /** + * Same as a normal trybind, except the map entry is also passed + * back to the caller. The entry in this case will either be the + * newly created entry, or the existing one. + */ int trybind (const EXT_ID &ext_id, INT_ID &int_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry); - // Same as a normal trybind, except the map entry is also passed - // back to the caller. The entry in this case will either be the - // newly created entry, or the existing one. + /** + * Reassociate <ext_id> with <int_id>. If <ext_id> is not in the + * map then behaves just like <bind>. Returns 0 if a new entry is + * bound successfully, returns 1 if an existing entry was rebound, + * and returns -1 if failures occur. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id); - // Reassociate <ext_id> with <int_id>. If <ext_id> is not in the - // map then behaves just like <bind>. Returns 0 if a new entry is - // bound successfully, returns 1 if an existing entry was rebound, - // and returns -1 if failures occur. + /** + * Same as a normal rebind, except the map entry is also passed back + * to the caller. The entry in this case will either be the newly + * created entry, or the existing one. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry); - // Same as a normal rebind, except the map entry is also passed back - // to the caller. The entry in this case will either be the newly - // created entry, or the existing one. + /** + * Associate <ext_id> with <int_id>. If <ext_id> is not in the map + * then behaves just like <bind>. Otherwise, store the old value of + * <int_id> into the "out" parameter and rebind the new parameters. + * Returns 0 if a new entry is bound successfully, returns 1 if an + * existing entry was rebound, and returns -1 if failures occur. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, INT_ID &old_int_id); - // Associate <ext_id> with <int_id>. If <ext_id> is not in the map - // then behaves just like <bind>. Otherwise, store the old value of - // <int_id> into the "out" parameter and rebind the new parameters. - // Returns 0 if a new entry is bound successfully, returns 1 if an - // existing entry was rebound, and returns -1 if failures occur. + /** + * Same as a normal rebind, except the map entry is also passed back + * to the caller. The entry in this case will either be the newly + * created entry, or the existing one. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, INT_ID &old_int_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry); - // Same as a normal rebind, except the map entry is also passed back - // to the caller. The entry in this case will either be the newly - // created entry, or the existing one. + /** + * Associate <ext_id> with <int_id>. If <ext_id> is not in the map + * then behaves just like <bind>. Otherwise, store the old values + * of <ext_id> and <int_id> into the "out" parameters and rebind the + * new parameters. This is very useful if you need to have an + * atomic way of updating <ACE_Hash_Map_Entrys> and you also need + * full control over memory allocation. Returns 0 if a new entry is + * bound successfully, returns 1 if an existing entry was rebound, + * and returns -1 if failures occur. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, EXT_ID &old_ext_id, INT_ID &old_int_id); - // Associate <ext_id> with <int_id>. If <ext_id> is not in the map - // then behaves just like <bind>. Otherwise, store the old values - // of <ext_id> and <int_id> into the "out" parameters and rebind the - // new parameters. This is very useful if you need to have an - // atomic way of updating <ACE_Hash_Map_Entrys> and you also need - // full control over memory allocation. Returns 0 if a new entry is - // bound successfully, returns 1 if an existing entry was rebound, - // and returns -1 if failures occur. + /** + * Same as a normal rebind, except the map entry is also passed back + * to the caller. The entry in this case will either be the newly + * created entry, or the existing one. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, EXT_ID &old_ext_id, INT_ID &old_int_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry); - // Same as a normal rebind, except the map entry is also passed back - // to the caller. The entry in this case will either be the newly - // created entry, or the existing one. + /// Locate <ext_id> and pass out parameter via <int_id>. If found, + /// return 0, returns -1 if not found. int find (const EXT_ID &ext_id, INT_ID &int_id) const; - // Locate <ext_id> and pass out parameter via <int_id>. If found, - // return 0, returns -1 if not found. + /// Returns 0 if the <ext_id> is in the mapping, otherwise -1. int find (const EXT_ID &ext_id) const; - // Returns 0 if the <ext_id> is in the mapping, otherwise -1. + /// Locate <ext_id> and pass out parameter via <entry>. If found, + /// return 0, returns -1 if not found. int find (const EXT_ID &ext_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry) const; - // Locate <ext_id> and pass out parameter via <entry>. If found, - // return 0, returns -1 if not found. + /** + * Unbind (remove) the <ext_id> from the map. Don't return the + * <int_id> to the caller (this is useful for collections where the + * <int_id>s are *not* dynamically allocated...) + */ int unbind (const EXT_ID &ext_id); - // Unbind (remove) the <ext_id> from the map. Don't return the - // <int_id> to the caller (this is useful for collections where the - // <int_id>s are *not* dynamically allocated...) + /// Break any association of <ext_id>. Returns the value of <int_id> + /// in case the caller needs to deallocate memory. int unbind (const EXT_ID &ext_id, INT_ID &int_id); - // Break any association of <ext_id>. Returns the value of <int_id> - // in case the caller needs to deallocate memory. + /// Remove entry from map. int unbind (ACE_Hash_Map_Entry<EXT_ID, INT_ID> *entry); - // Remove entry from map. + /// Return the current size of the map. size_t current_size (void) const; - // Return the current size of the map. + /// Return the total size of the map. size_t total_size (void) const; - // Return the total size of the map. + /** + * Returns a reference to the underlying <ACE_LOCK>. This makes it + * possible to acquire the lock explicitly, which can be useful in + * some cases if you instantiate the <ACE_Atomic_Op> with an + * <ACE_Recursive_Mutex> or <ACE_Process_Mutex>, or if you need to + * guard the state of an iterator. NOTE: the right name would be + * <lock>, but HP/C++ will choke on that! + */ ACE_LOCK &mutex (void); - // Returns a reference to the underlying <ACE_LOCK>. This makes it - // possible to acquire the lock explicitly, which can be useful in - // some cases if you instantiate the <ACE_Atomic_Op> with an - // <ACE_Recursive_Mutex> or <ACE_Process_Mutex>, or if you need to - // guard the state of an iterator. NOTE: the right name would be - // <lock>, but HP/C++ will choke on that! + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL styled iterator factory functions. + /// Return forward iterator. ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> begin (void); ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> end (void); - // Return forward iterator. + /// Return reverse iterator. ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> rbegin (void); ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> rend (void); - // Return reverse iterator. protected: // = The following methods do the actual work. + /// Returns 1 if <id1> == <id2>, else 0. This is defined as a + /// separate method to facilitate template specialization. int equal (const EXT_ID &id1, const EXT_ID &id2); - // Returns 1 if <id1> == <id2>, else 0. This is defined as a - // separate method to facilitate template specialization. + /// Compute the hash value of the <ext_id>. This is defined as a + /// separate method to facilitate template specialization. u_long hash (const EXT_ID &ext_id); - // Compute the hash value of the <ext_id>. This is defined as a - // separate method to facilitate template specialization. // = These methods assume locks are held by private methods. + /// Performs bind. Must be called with locks held. int bind_i (const EXT_ID &ext_id, const INT_ID &int_id); - // Performs bind. Must be called with locks held. + /// Performs bind. Must be called with locks held. int bind_i (const EXT_ID &ext_id, const INT_ID &int_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry); - // Performs bind. Must be called with locks held. + /// Performs trybind. Must be called with locks held. int trybind_i (const EXT_ID &ext_id, INT_ID &int_id); - // Performs trybind. Must be called with locks held. + /// Performs trybind. Must be called with locks held. int trybind_i (const EXT_ID &ext_id, INT_ID &int_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry); - // Performs trybind. Must be called with locks held. + /// Performs rebind. Must be called with locks held. int rebind_i (const EXT_ID &ext_id, const INT_ID &int_id); - // Performs rebind. Must be called with locks held. + /// Performs rebind. Must be called with locks held. int rebind_i (const EXT_ID &ext_id, const INT_ID &int_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry); - // Performs rebind. Must be called with locks held. + /// Performs rebind. Must be called with locks held. int rebind_i (const EXT_ID &ext_id, const INT_ID &int_id, INT_ID &old_int_id); - // Performs rebind. Must be called with locks held. + /// Performs rebind. Must be called with locks held. int rebind_i (const EXT_ID &ext_id, const INT_ID &int_id, INT_ID &old_int_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry); - // Performs rebind. Must be called with locks held. + /// Performs rebind. Must be called with locks held. int rebind_i (const EXT_ID &ext_id, const INT_ID &int_id, EXT_ID &old_ext_id, INT_ID &old_int_id); - // Performs rebind. Must be called with locks held. + /// Performs rebind. Must be called with locks held. int rebind_i (const EXT_ID &ext_id, const INT_ID &int_id, EXT_ID &old_ext_id, INT_ID &old_int_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry); - // Performs rebind. Must be called with locks held. + /// Performs a find of <int_id> using <ext_id> as the key. Must be + /// called with locks held. int find_i (const EXT_ID &ext_id, INT_ID &int_id); - // Performs a find of <int_id> using <ext_id> as the key. Must be - // called with locks held. + /// Performs a find using <ext_id> as the key. Must be called with + /// locks held. int find_i (const EXT_ID &ext_id); - // Performs a find using <ext_id> as the key. Must be called with - // locks held. + /// Performs a find using <ext_id> as the key. Must be called with + /// locks held. int find_i (const EXT_ID &ext_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry); - // Performs a find using <ext_id> as the key. Must be called with - // locks held. + /// Performs unbind. Must be called with locks held. int unbind_i (const EXT_ID &ext_id, INT_ID &int_id); - // Performs unbind. Must be called with locks held. + /// Performs unbind. Must be called with locks held. int unbind_i (const EXT_ID &ext_id); - // Performs unbind. Must be called with locks held. + /// Performs unbind. Must be called with locks held. int unbind_i (ACE_Hash_Map_Entry<EXT_ID, INT_ID> *entry); - // Performs unbind. Must be called with locks held. + /** + * Resize the map. Must be called with locks held. Note, that this + * method should never be called more than once or else all the + * hashing will get screwed up as the size will change. + */ int create_buckets (size_t size); - // Resize the map. Must be called with locks held. Note, that this - // method should never be called more than once or else all the - // hashing will get screwed up as the size will change. + /// Close down a <Map_Manager_Ex>. Must be called with + /// locks held. int close_i (void); - // Close down a <Map_Manager_Ex>. Must be called with - // locks held. + /// Removes all the entries in <Map_Manager_Ex>. Must be called with + /// locks held. int unbind_all_i (void); - // Removes all the entries in <Map_Manager_Ex>. Must be called with - // locks held. + /// Pointer to a memory allocator. ACE_Allocator *allocator_; - // Pointer to a memory allocator. + /// Synchronization variable for the MT_SAFE <ACE_Hash_Map_Manager_Ex>. ACE_LOCK lock_; - // Synchronization variable for the MT_SAFE <ACE_Hash_Map_Manager_Ex>. + /// Function object used for hashing keys. HASH_KEY hash_key_; - // Function object used for hashing keys. + /// Function object used for comparing keys. COMPARE_KEYS compare_keys_; - // Function object used for comparing keys. private: + /// Returns the <ACE_Hash_Map_Entry> that corresponds to <ext_id>. int shared_find (const EXT_ID &ext_id, ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry, u_long &loc); - // Returns the <ACE_Hash_Map_Entry> that corresponds to <ext_id>. + /** + * Array of <ACE_Hash_Map_Entry> *s, each of which points to an + * <ACE_Hash_Map_Entry> that serves as the beginning of a linked + * list of <EXT_ID>s that hash to that bucket. + */ ACE_Hash_Map_Entry<EXT_ID, INT_ID> *table_; - // Array of <ACE_Hash_Map_Entry> *s, each of which points to an - // <ACE_Hash_Map_Entry> that serves as the beginning of a linked - // list of <EXT_ID>s that hash to that bucket. + /// Total size of the hash table. size_t total_size_; - // Total size of the hash table. + /// Current number of entries in the table (note that this can be + /// larger than <total_size_> due to the bucket chaining). size_t cur_size_; - // Current number of entries in the table (note that this can be - // larger than <total_size_> due to the bucket chaining). }; +/** + * @class ACE_Hash_Map_Iterator_Base_Ex + * + * @brief Base iterator for the <ACE_Hash_Map_Manager_Ex> + * + * This class factors out common code from its templatized + * subclasses. + */ template <class EXT_ID, class INT_ID, class HASH_KEY, class COMPARE_KEYS, class ACE_LOCK> class ACE_Hash_Map_Iterator_Base_Ex { - // = TITLE - // Base iterator for the <ACE_Hash_Map_Manager_Ex> - // - // = DESCRIPTION - // This class factors out common code from its templatized - // subclasses. public: // = Initialization method. + /// Contructor. If head != 0, the iterator constructed is positioned + /// at the head of the map, it is positioned at the end otherwise. ACE_Hash_Map_Iterator_Base_Ex (ACE_Hash_Map_Manager_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &mm, int head); - // Contructor. If head != 0, the iterator constructed is positioned - // at the head of the map, it is positioned at the end otherwise. // = ITERATION methods. + /// Pass back the next <entry> that hasn't been seen in the Set. + /// Returns 0 when all items have been seen, else 1. int next (ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&next_entry) const; - // Pass back the next <entry> that hasn't been seen in the Set. - // Returns 0 when all items have been seen, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Returns a reference to the interal element <this> is pointing to. ACE_Hash_Map_Entry<EXT_ID, INT_ID>& operator* (void) const; - // Returns a reference to the interal element <this> is pointing to. + /// Returns reference the Hash_Map_Manager_Ex that is being iterated + /// over. ACE_Hash_Map_Manager_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK>& map (void); - // Returns reference the Hash_Map_Manager_Ex that is being iterated - // over. + /// Check if two iterators point to the same position int operator== (const ACE_Hash_Map_Iterator_Base_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &) const; int operator!= (const ACE_Hash_Map_Iterator_Base_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &) const; - // Check if two iterators point to the same position + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Move forward by one element in the set. Returns 0 when there's + /// no more item in the set after the current items, else 1. int forward_i (void); - // Move forward by one element in the set. Returns 0 when there's - // no more item in the set after the current items, else 1. + /// Move backward by one element in the set. Returns 0 when there's + /// no more item in the set before the current item, else 1. int reverse_i (void); - // Move backward by one element in the set. Returns 0 when there's - // no more item in the set before the current item, else 1. + /// Dump the state of an object. void dump_i (void) const; - // Dump the state of an object. + /// Map we are iterating over. ACE_Hash_Map_Manager_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> *map_man_; - // Map we are iterating over. + /// Keeps track of how far we've advanced in the table. ssize_t index_; - // Keeps track of how far we've advanced in the table. + /// Keeps track of how far we've advanced in a linked list in each + /// table slot. ACE_Hash_Map_Entry<EXT_ID, INT_ID> *next_; - // Keeps track of how far we've advanced in a linked list in each - // table slot. }; +/** + * @class ACE_Hash_Map_Iterator_Ex + * + * @brief Forward iterator for the <ACE_Hash_Map_Manager_Ex>. + * + * This class does not perform any internal locking of the + * <ACE_Hash_Map_Manager_Ex> it is iterating upon since locking is + * inherently inefficient and/or error-prone within an STL-style + * iterator. If you require locking, you can explicitly use an + * <ACE_Guard> or <ACE_Read_Guard> on the <ACE_Hash_Map_Manager_Ex>'s + * internal lock, which is accessible via its <mutex> method. + */ template <class EXT_ID, class INT_ID, class HASH_KEY, class COMPARE_KEYS, class ACE_LOCK> class ACE_Hash_Map_Iterator_Ex : public ACE_Hash_Map_Iterator_Base_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> { - // = TITLE - // Forward iterator for the <ACE_Hash_Map_Manager_Ex>. - // - // = DESCRIPTION - // This class does not perform any internal locking of the - // <ACE_Hash_Map_Manager_Ex> it is iterating upon since locking is - // inherently inefficient and/or error-prone within an STL-style - // iterator. If you require locking, you can explicitly use an - // <ACE_Guard> or <ACE_Read_Guard> on the <ACE_Hash_Map_Manager_Ex>'s - // internal lock, which is accessible via its <mutex> method. public: // = Initialization method. ACE_Hash_Map_Iterator_Ex (ACE_Hash_Map_Manager_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &mm, int tail = 0); + // = Iteration methods. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL styled iteration, compare, and reference functions. + /// Prefix advance. ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &operator++ (void); - // Prefix advance. + /// Postfix advance. ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> operator++ (int); - // Postfix advance. + /// Prefix reverse. ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &operator-- (void); - // Prefix reverse. + /// Postfix reverse. ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> operator-- (int); - // Postfix reverse. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Hash_Map_Bucket_Iterator + * + * @brief Forward iterator for the <ACE_Hash_Map_Manager_Ex> which only + * traverses a particular bucket. The particular bucket is + * specified by the <EXT_ID> parameter specified in the + * constructor. + * + * This class does not perform any internal locking of the + * <ACE_Hash_Map_Manager_Ex> it is iterating upon since locking + * is inherently inefficient and/or error-prone within an + * STL-style iterator. If you require locking, you can + * explicitly use an <ACE_Guard> or <ACE_Read_Guard> on the + * <ACE_Hash_Map_Manager_Ex>'s internal lock, which is + * accessible via its <mutex> method. + * Note that this iterator cannot be created by calling a method + * on the map, since this would require + */ template <class EXT_ID, class INT_ID, class HASH_KEY, class COMPARE_KEYS, class ACE_LOCK> class ACE_Hash_Map_Bucket_Iterator { - // = TITLE - // Forward iterator for the <ACE_Hash_Map_Manager_Ex> which only - // traverses a particular bucket. The particular bucket is - // specified by the <EXT_ID> parameter specified in the - // constructor. - // - // = DESCRIPTION - // This class does not perform any internal locking of the - // <ACE_Hash_Map_Manager_Ex> it is iterating upon since locking - // is inherently inefficient and/or error-prone within an - // STL-style iterator. If you require locking, you can - // explicitly use an <ACE_Guard> or <ACE_Read_Guard> on the - // <ACE_Hash_Map_Manager_Ex>'s internal lock, which is - // accessible via its <mutex> method. - // - // Note that this iterator cannot be created by calling a method - // on the map, since this would require public: // = Initialization method. ACE_Hash_Map_Bucket_Iterator (ACE_Hash_Map_Manager_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &mm, @@ -547,114 +581,117 @@ public: // = STL styled iteration, compare, and reference functions. + /// Prefix advance. ACE_Hash_Map_Bucket_Iterator<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &operator++ (void); - // Prefix advance. + /// Postfix advance. ACE_Hash_Map_Bucket_Iterator<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> operator++ (int); - // Postfix advance. + /// Prefix reverse. ACE_Hash_Map_Bucket_Iterator<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &operator-- (void); - // Prefix reverse. + /// Postfix reverse. ACE_Hash_Map_Bucket_Iterator<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> operator-- (int); - // Postfix reverse. + /// Returns a reference to the interal element <this> is pointing to. ACE_Hash_Map_Entry<EXT_ID, INT_ID>& operator* (void) const; - // Returns a reference to the interal element <this> is pointing to. + /// Returns reference the Hash_Map_Manager_Ex that is being iterated + /// over. ACE_Hash_Map_Manager_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK>& map (void); - // Returns reference the Hash_Map_Manager_Ex that is being iterated - // over. + /// Check if two iterators point to the same position int operator== (const ACE_Hash_Map_Bucket_Iterator<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &) const; int operator!= (const ACE_Hash_Map_Bucket_Iterator<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &) const; - // Check if two iterators point to the same position protected: + /// Move forward by one element in the set. Returns 0 when there's + /// no more item in the set after the current items, else 1. int forward_i (void); - // Move forward by one element in the set. Returns 0 when there's - // no more item in the set after the current items, else 1. + /// Move backward by one element in the set. Returns 0 when there's + /// no more item in the set before the current item, else 1. int reverse_i (void); - // Move backward by one element in the set. Returns 0 when there's - // no more item in the set before the current item, else 1. + /// Map we are iterating over. ACE_Hash_Map_Manager_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> *map_man_; - // Map we are iterating over. + /// Keeps track of how far we've advanced in the table. ssize_t index_; - // Keeps track of how far we've advanced in the table. + /// Keeps track of how far we've advanced in a linked list in each + /// table slot. ACE_Hash_Map_Entry<EXT_ID, INT_ID> *next_; - // Keeps track of how far we've advanced in a linked list in each - // table slot. }; +/** + * @class ACE_Hash_Map_Reverse_Iterator_Ex + * + * @brief Reverse iterator for the <ACE_Hash_Map_Manager_Ex>. + * + * This class does not perform any internal locking of the + * <ACE_Hash_Map_Manager_Ex> it is iterating upon since locking is + * inherently inefficient and/or error-prone within an STL-style + * iterator. If you require locking, you can explicitly use an + * <ACE_Guard> or <ACE_Read_Guard> on the <ACE_Hash_Map_Manager_Ex>'s + * internal lock, which is accessible via its <mutex> method. + */ template <class EXT_ID, class INT_ID, class HASH_KEY, class COMPARE_KEYS, class ACE_LOCK> class ACE_Hash_Map_Reverse_Iterator_Ex : public ACE_Hash_Map_Iterator_Base_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> { - // = TITLE - // Reverse iterator for the <ACE_Hash_Map_Manager_Ex>. - // - // = DESCRIPTION - // This class does not perform any internal locking of the - // <ACE_Hash_Map_Manager_Ex> it is iterating upon since locking is - // inherently inefficient and/or error-prone within an STL-style - // iterator. If you require locking, you can explicitly use an - // <ACE_Guard> or <ACE_Read_Guard> on the <ACE_Hash_Map_Manager_Ex>'s - // internal lock, which is accessible via its <mutex> method. public: // = Initialization method. ACE_Hash_Map_Reverse_Iterator_Ex (ACE_Hash_Map_Manager_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &mm, int head = 0); + // = Iteration methods. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL styled iteration, compare, and reference functions. + /// Prefix reverse. ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &operator++ (void); - // Prefix reverse. + /// Postfix reverse. ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> operator++ (int); - // Postfix reverse. + /// Prefix advance. ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> &operator-- (void); - // Prefix advance. + /// Postfix advance. ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> operator-- (int); - // Postfix advance. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Hash_Map_Manager + * + * @brief Wrapper for backward compatibility. + * + * This implementation of a map uses a hash table. This class + * expects that the <EXT_ID> contains a method called <hash>. + * In addition, the <EXT_ID> must support <operator==>. Both of + * these constraints can be alleviated via template + * specialization, as shown in the $ACE_ROOT/tests/Conn_Test.cpp + * test. + */ template <class EXT_ID, class INT_ID, class ACE_LOCK> class ACE_Hash_Map_Manager : public ACE_Hash_Map_Manager_Ex<EXT_ID, INT_ID, ACE_Hash<EXT_ID>, ACE_Equal_To<EXT_ID>, ACE_LOCK> { - // = TITLE - // Wrapper for backward compatibility. - // - // = DESCRIPTION - // - // This implementation of a map uses a hash table. This class - // expects that the <EXT_ID> contains a method called <hash>. - // In addition, the <EXT_ID> must support <operator==>. Both of - // these constraints can be alleviated via template - // specialization, as shown in the $ACE_ROOT/tests/Conn_Test.cpp - // test. - // public: + /// Initialize a <Hash_Map_Manager> with default size. ACE_Hash_Map_Manager (ACE_Allocator *alloc = 0); - // Initialize a <Hash_Map_Manager> with default size. + /// Initialize a <Hash_Map_Manager> with size <length>. ACE_Hash_Map_Manager (size_t size, ACE_Allocator *alloc = 0); - // Initialize a <Hash_Map_Manager> with size <length>. // = The following two are necessary for template specialization of // ACE_Hash_Map_Manager to work. @@ -662,43 +699,47 @@ public: u_long hash (const EXT_ID &ext_id); }; +/** + * @class ACE_Hash_Map_Iterator + * + * @brief Wrapper for backward compatibility. + */ template <class EXT_ID, class INT_ID, class ACE_LOCK> class ACE_Hash_Map_Iterator : public ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, ACE_Hash<EXT_ID>, ACE_Equal_To<EXT_ID>, ACE_LOCK> { - // = TITLE - // Wrapper for backward compatibility. - // public: // = Initialization method. + /// Construct from map ACE_Hash_Map_Iterator (ACE_Hash_Map_Manager<EXT_ID, INT_ID, ACE_LOCK> &mm, int tail = 0); - // Construct from map + /// Construct from base ACE_Hash_Map_Iterator (const ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, ACE_Hash<EXT_ID>, ACE_Equal_To<EXT_ID>, ACE_LOCK> &base); - // Construct from base + /// Assignment from base ACE_Hash_Map_Iterator<EXT_ID, INT_ID, ACE_LOCK> & operator= (const ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, ACE_Hash<EXT_ID>, ACE_Equal_To<EXT_ID>, ACE_LOCK> &base); - // Assignment from base }; +/** + * @class ACE_Hash_Map_Reverse_Iterator + * + * @brief Wrapper for backward compatibility. + */ template <class EXT_ID, class INT_ID, class ACE_LOCK> class ACE_Hash_Map_Reverse_Iterator : public ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, ACE_Hash<EXT_ID>, ACE_Equal_To<EXT_ID>, ACE_LOCK> { - // = TITLE - // Wrapper for backward compatibility. - // public: // = Initialization method. ACE_Hash_Map_Reverse_Iterator (ACE_Hash_Map_Manager<EXT_ID, INT_ID, ACE_LOCK> &mm, int head = 0); + /// Construct from base ACE_Hash_Map_Reverse_Iterator (const ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, ACE_Hash<EXT_ID>, ACE_Equal_To<EXT_ID>, ACE_LOCK> &base); - // Construct from base + /// Assignment from base ACE_Hash_Map_Reverse_Iterator<EXT_ID, INT_ID, ACE_LOCK> & operator= (const ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, ACE_Hash<EXT_ID>, ACE_Equal_To<EXT_ID>, ACE_LOCK> &base); - // Assignment from base }; #if defined (__ACE_INLINE__) diff --git a/ace/Hash_Map_With_Allocator_T.h b/ace/Hash_Map_With_Allocator_T.h index 4799edf38ce..c1c5c712ce6 100644 --- a/ace/Hash_Map_With_Allocator_T.h +++ b/ace/Hash_Map_With_Allocator_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Hash_Map_With_Allocator_T.h -// -// = AUTHOR -// Marina Spivak <marina@cs.wustl.edu> and -// Irfan Pyarali <irfan@cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Hash_Map_With_Allocator_T.h + * + * $Id$ + * + * @author Marina Spivak <marina@cs.wustl.edu> + * @author Irfan Pyarali <irfan@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_HASH_MAP_WITH_ALLOCATOR_T_H #define ACE_HASH_MAP_WITH_ALLOCATOR_T_H @@ -24,35 +21,37 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Hash_Map_With_Allocator + * + * @brief This class is a thin wrapper around ACE_Hash_Map_Manager, + * which comes handy when ACE_Hash_Map_Manager is to be used with a + * non-nil ACE_Allocator. This wrapper insures that the appropriate + * allocator is in place for every operation that accesses or + * updates the hash map. + * + * If we use ACE_Hash_Map_Manager with a shared memory allocator + * (or memory-mapped file allocator, for example), the allocator + * pointer used by ACE_Hash_Map_Manager gets stored with it, in + * shared memory (or memory-mapped file). Naturally, this will + * cause horrible problems, since only the first process to set + * that pointer will be guaranteed the address of the allocator + * is meaningful! That is why we need this wrapper, which + * insures that appropriate allocator pointer is in place for + * each call. + * + */ template <class EXT_ID, class INT_ID> class ACE_Hash_Map_With_Allocator : public ACE_Hash_Map_Manager<EXT_ID, INT_ID, ACE_Null_Mutex> { - // = TITLE - // This class is a thin wrapper around ACE_Hash_Map_Manager, - // which comes handy when ACE_Hash_Map_Manager is to be used with a - // non-nil ACE_Allocator. This wrapper insures that the appropriate - // allocator is in place for every operation that accesses or - // updates the hash map. - // - // = DESCRIPTION - // If we use ACE_Hash_Map_Manager with a shared memory allocator - // (or memory-mapped file allocator, for example), the allocator - // pointer used by ACE_Hash_Map_Manager gets stored with it, in - // shared memory (or memory-mapped file). Naturally, this will - // cause horrible problems, since only the first process to set - // that pointer will be guaranteed the address of the allocator - // is meaningful! That is why we need this wrapper, which - // insures that appropriate allocator pointer is in place for - // each call. - // public: + /// Constructor. ACE_Hash_Map_With_Allocator (ACE_Allocator *alloc); - // Constructor. + /// Constructor that specifies hash table size. ACE_Hash_Map_With_Allocator (size_t size, ACE_Allocator *alloc); - // Constructor that specifies hash table size. // = The following methods are Proxies to the corresponding methods // in <ACE_Hash_Map_Manager>. Each method sets the allocator to @@ -67,7 +66,7 @@ public: int unbind (const EXT_ID &, INT_ID &, ACE_Allocator *alloc); - + int unbind (const EXT_ID &, ACE_Allocator *alloc); @@ -81,9 +80,9 @@ public: INT_ID &, ACE_Allocator *alloc); + /// Returns 0 if the <ext_id> is in the mapping, otherwise -1. int find (const EXT_ID &, ACE_Allocator *alloc); - // Returns 0 if the <ext_id> is in the mapping, otherwise -1. int close (ACE_Allocator *alloc); }; diff --git a/ace/High_Res_Timer.h b/ace/High_Res_Timer.h index 5c1d2435d9c..19626a7d298 100644 --- a/ace/High_Res_Timer.h +++ b/ace/High_Res_Timer.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// High_Res_Timer.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file High_Res_Timer.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_HIGH_RES_TIMER_H #define ACE_HIGH_RES_TIMER_H @@ -24,62 +21,62 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_High_Res_Timer + * + * @brief A high resolution timer class wrapper that encapsulates + * OS-specific high-resolution timers, such as those found on + * Solaris, AIX, Win32/Pentium, and VxWorks. + * + * Most of the member functions don't return values. The only + * reason that one would fail is if high-resolution time isn't + * supported on the platform. To avoid impacting performance + * and complicating the interface, in that case, + * <ACE_OS::gettimeofday> is used instead. + * The global scale factor is required for platforms that have + * high-resolution timers that return units other than + * microseconds, such as clock ticks. It is represented as a + * static u_long, can only be accessed through static methods, + * and is used by all instances of High Res Timer. The member + * functions that return or print times use the global scale + * factor. They divide the "time" that they get from + * <ACE_OS::gethrtime> by global_scale_factor_ to obtain the + * time in microseconds. Its units are therefore 1/microsecond. + * On Solaris, a scale factor of 1000 should be used because its + * high-resolution timer returns nanoseconds. However, on Intel + * platforms, we use RDTSC which returns the number of clock + * ticks since system boot. For a 200MHz cpu, each clock tick + * is 1/200 of a microsecond; the global_scale_factor_ should + * therefore be 200. + * NOTE: the elapsed time calculations in the print methods use + * ACE_hrtime_t values. Those methods do _not_ check for overflow! + * NOTE: Gabe <begeddov@proaxis.com> raises this issue regarding + * <ACE_OS::gethrtime>: on multi-processors, the processor that + * you query for your <timer.stop> value might not be the one + * you queried for <timer.start>. Its not clear how much + * divergence there would be, if any. + * This issue is not mentioned in the Solaris 2.5.1 gethrtime + * man page. + */ class ACE_Export ACE_High_Res_Timer { - // = TITLE - // A high resolution timer class wrapper that encapsulates - // OS-specific high-resolution timers, such as those found on - // Solaris, AIX, Win32/Pentium, and VxWorks. - // - // = DESCRIPTION - // Most of the member functions don't return values. The only - // reason that one would fail is if high-resolution time isn't - // supported on the platform. To avoid impacting performance - // and complicating the interface, in that case, - // <ACE_OS::gettimeofday> is used instead. - // - // The global scale factor is required for platforms that have - // high-resolution timers that return units other than - // microseconds, such as clock ticks. It is represented as a - // static u_long, can only be accessed through static methods, - // and is used by all instances of High Res Timer. The member - // functions that return or print times use the global scale - // factor. They divide the "time" that they get from - // <ACE_OS::gethrtime> by global_scale_factor_ to obtain the - // time in microseconds. Its units are therefore 1/microsecond. - // On Solaris, a scale factor of 1000 should be used because its - // high-resolution timer returns nanoseconds. However, on Intel - // platforms, we use RDTSC which returns the number of clock - // ticks since system boot. For a 200MHz cpu, each clock tick - // is 1/200 of a microsecond; the global_scale_factor_ should - // therefore be 200. - // - // NOTE: the elapsed time calculations in the print methods use - // ACE_hrtime_t values. Those methods do _not_ check for overflow! - // - // NOTE: Gabe <begeddov@proaxis.com> raises this issue regarding - // <ACE_OS::gethrtime>: on multi-processors, the processor that - // you query for your <timer.stop> value might not be the one - // you queried for <timer.start>. Its not clear how much - // divergence there would be, if any. - // - // This issue is not mentioned in the Solaris 2.5.1 gethrtime - // man page. public: // = Initialization method. + /** + * global_scale_factor_ is set to <gsf>. All High_Res_Timers use + * global_scale_factor_. This allows applications to set the scale + * factor just once for all High_Res_Timers. Check + * High_Res_Timer.cpp for the default global_scale_factors for + * several platforms. For many platforms (e.g., Solaris), the + * global_scale_factor_ is set to 1000 so that <scale_factor> need + * not be set. Careful, a <scale_factor> of 0 will cause division + * by zero exceptions. + */ static void global_scale_factor (ACE_UINT32 gsf); - // global_scale_factor_ is set to <gsf>. All High_Res_Timers use - // global_scale_factor_. This allows applications to set the scale - // factor just once for all High_Res_Timers. Check - // High_Res_Timer.cpp for the default global_scale_factors for - // several platforms. For many platforms (e.g., Solaris), the - // global_scale_factor_ is set to 1000 so that <scale_factor> need - // not be set. Careful, a <scale_factor> of 0 will cause division - // by zero exceptions. + /// Returns the global_scale_factor. static ACE_UINT32 global_scale_factor (void); - // Returns the global_scale_factor. // On Win32, QueryPerformanceFrequency is used as a base for the global // scale factor. The value this returns is often too small to be usefully @@ -92,152 +89,166 @@ public: # define ACE_HR_SCALE_CONVERSION (ACE_ONE_SECOND_IN_USECS) #endif /* ACE_WIN32 */ - static int get_env_global_scale_factor (const ACE_TCHAR *env + /** + * Sets the global_scale_factor to the value in the <env> + * environment variable. Returns 0 on success, -1 on failure. Note + * if <env> points to string "0" (value zero), this call will fail. + * This is basically a no-op on CE because there is no concept of + * environment variable on CE. + */ + static int get_env_global_scale_factor (const ACE_TCHAR *env = ACE_LIB_TEXT ("ACE_SCALE_FACTOR")); - // Sets the global_scale_factor to the value in the <env> - // environment variable. Returns 0 on success, -1 on failure. Note - // if <env> points to string "0" (value zero), this call will fail. - // This is basically a no-op on CE because there is no concept of - // environment variable on CE. + /** + * Set (and return, for info) the global scale factor by sleeping + * for <usec> and counting the number of intervening clock cycles. + * Average over <iterations> of <usec> each. On some platforms, + * such as Pentiums, this is called automatically during the first + * ACE_High_Res_Timer construction with the default parameter + * values. An application can override that by calling calibrate + * with any desired parameter values _prior_ to constructing the + * first ACE_High_Res_Timer instance. + */ static ACE_UINT32 calibrate (const ACE_UINT32 usec = 500000, const u_int iterations = 10); - // Set (and return, for info) the global scale factor by sleeping - // for <usec> and counting the number of intervening clock cycles. - // Average over <iterations> of <usec> each. On some platforms, - // such as Pentiums, this is called automatically during the first - // ACE_High_Res_Timer construction with the default parameter - // values. An application can override that by calling calibrate - // with any desired parameter values _prior_ to constructing the - // first ACE_High_Res_Timer instance. + /// Initialize the timer. ACE_High_Res_Timer (void); - // Initialize the timer. + /// dtor. ~ACE_High_Res_Timer (void); - // dtor. + /// Reinitialize the timer. void reset (void); - // Reinitialize the timer. + /// Start timing. void start (const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME); - // Start timing. + /// Stop timing. void stop (const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME); - // Stop timing. + /// Set <tv> to the number of microseconds elapsed. void elapsed_time (ACE_Time_Value &tv) const; - // Set <tv> to the number of microseconds elapsed. + /// Set <nanoseconds> to the number of nanoseconds elapsed. void elapsed_time (ACE_hrtime_t &nanoseconds) const; - // Set <nanoseconds> to the number of nanoseconds elapsed. #if defined (ACE_HAS_POSIX_TIME) + /// Returns the elapsed (stop - start) time in a struct timespec + /// (sec, nsec). void elapsed_time (struct timespec &) const; - // Returns the elapsed (stop - start) time in a struct timespec - // (sec, nsec). #endif /* ACE_HAS_POSIX_TIME */ + /// Sets <usecs> to the elapsed (stop - start) time in microseconds. void elapsed_microseconds (ACE_hrtime_t &usecs) const; - // Sets <usecs> to the elapsed (stop - start) time in microseconds. + /// Start incremental timing. void start_incr (const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME); - // Start incremental timing. + /// Stop incremental timing. void stop_incr (const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME); - // Stop incremental timing. + /// Set <tv> to the number of microseconds elapsed between all calls + /// to start_incr and stop_incr. void elapsed_time_incr (ACE_Time_Value &tv) const; - // Set <tv> to the number of microseconds elapsed between all calls - // to start_incr and stop_incr. + /// Set <nsec> to the number of nanoseconds elapsed between all calls + /// to start_incr and stop_incr. void elapsed_time_incr (ACE_hrtime_t &nanoseconds) const; - // Set <nsec> to the number of nanoseconds elapsed between all calls - // to start_incr and stop_incr. #if !defined (ACE_HAS_WINCE) // @@ WINCE These two functions are currently not supported on Windows CE. // However, we should probably use the handle and ACE_Log_Msg to // print out the result. + /// Print total time. NOTE: only use <print_total> if incremental + /// timings had been used! void print_total (const ACE_TCHAR *message, const int iterations = 1, ACE_HANDLE handle = ACE_STDOUT) const; - // Print total time. NOTE: only use <print_total> if incremental - // timings had been used! + /// Print average time. void print_ave (const ACE_TCHAR *message, const int iterations = 1, ACE_HANDLE handle = ACE_STDOUT) const; - // Print average time. #endif /* !ACE_HAS_WINCE */ + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /** + * Get the current "time" as the high resolution counter at this time. + * This is intended to be useful for supplying to a ACE_Timer_Queue + * as the gettimeofday function, thereby basing the timer calculations + * on the high res timer rather than wall clock time. + */ static ACE_Time_Value gettimeofday_hr (void); - // Get the current "time" as the high resolution counter at this time. - // This is intended to be useful for supplying to a ACE_Timer_Queue - // as the gettimeofday function, thereby basing the timer calculations - // on the high res timer rather than wall clock time. + /** + * THIS FUNCTION IS DEPRECATED. PLEASE USE <ACE_OS::gettimeofday> + * INSTEAD! Calls <ACE_High_Res_Timer::hrtime_to_tv> passing + * <ACE_OS::gethrtime>. This function can be used to parameterize + * objects such as <ACE_Timer_Queue::gettimeofday>. If + * <global_scale_factor_> is not set, and we're on a platform that + * requires <global_scale_factor_> (e.g., Win32), + * ACE_OS::gettimeofday will be used instead of <ACE_OS::gethrtime>. + * This allows applications on Intel to use <High_Res_Timer> even + * when <global_scale_factor> is not set. However, setting the + * <global_scale_factor_> appropriately will result in the finest + * resolution possible. + */ static ACE_Time_Value gettimeofday (const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME); - // THIS FUNCTION IS DEPRECATED. PLEASE USE <ACE_OS::gettimeofday> - // INSTEAD! Calls <ACE_High_Res_Timer::hrtime_to_tv> passing - // <ACE_OS::gethrtime>. This function can be used to parameterize - // objects such as <ACE_Timer_Queue::gettimeofday>. If - // <global_scale_factor_> is not set, and we're on a platform that - // requires <global_scale_factor_> (e.g., Win32), - // ACE_OS::gettimeofday will be used instead of <ACE_OS::gethrtime>. - // This allows applications on Intel to use <High_Res_Timer> even - // when <global_scale_factor> is not set. However, setting the - // <global_scale_factor_> appropriately will result in the finest - // resolution possible. + /// Converts an <hrt> to <tv> using global_scale_factor_. static void hrtime_to_tv (ACE_Time_Value &tv, const ACE_hrtime_t hrt); - // Converts an <hrt> to <tv> using global_scale_factor_. #if defined (linux) + /** + * This is used to find out the Mhz of the machine for the scale + * factor. If there are any problems getting it, we just return 1 + * (the default). + */ static ACE_UINT32 get_cpuinfo (void); - // This is used to find out the Mhz of the machine for the scale - // factor. If there are any problems getting it, we just return 1 - // (the default). #endif /* defined (linux) */ private: + /** + * For internal use: gets the high-resolution time using + * <ACE_OS::gethrtime>. Except on platforms that require that the + * <global_scale_factor_> be set, such as ACE_WIN32, uses the + * low-resolution clock if the <global_scale_factor_> has not been + * set. + */ static ACE_hrtime_t gettime (const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME); - // For internal use: gets the high-resolution time using - // <ACE_OS::gethrtime>. Except on platforms that require that the - // <global_scale_factor_> be set, such as ACE_WIN32, uses the - // low-resolution clock if the <global_scale_factor_> has not been - // set. + /// Starting time. ACE_hrtime_t start_; - // Starting time. + /// Ending time. ACE_hrtime_t end_; - // Ending time. + /// Total elapsed time. ACE_hrtime_t total_; - // Total elapsed time. + /// Start time of incremental timing. ACE_hrtime_t start_incr_; - // Start time of incremental timing. + /// Converts ticks to microseconds. That is, ticks / + /// global_scale_factor_ == microseconds. static ACE_UINT32 global_scale_factor_; - // Converts ticks to microseconds. That is, ticks / - // global_scale_factor_ == microseconds. + /** + * Indicates the status of the global scale factor, + * 0 = hasn't been set + * 1 = been set + * -1 = HR timer not supported + */ static int global_scale_factor_status_; - // Indicates the status of the global scale factor, - // 0 = hasn't been set - // 1 = been set - // -1 = HR timer not supported }; #if defined (__ACE_INLINE__) diff --git a/ace/INET_Addr.h b/ace/INET_Addr.h index fbb9f42527f..4e14ea6c1a9 100644 --- a/ace/INET_Addr.h +++ b/ace/INET_Addr.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// INET_Addr.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file INET_Addr.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_INET_ADDR_H #define ACE_INET_ADDR_H @@ -26,52 +23,61 @@ #include "ace/Addr.h" +/** + * @class ACE_INET_Addr + * + * @brief Defines a C++ wrapper facade for the Internet domain address + * family format. + */ class ACE_Export ACE_INET_Addr : public ACE_Addr { - // = TITLE - // Defines a C++ wrapper facade for the Internet domain address - // family format. public: // = Initialization methods. + /// Default constructor. ACE_INET_Addr (void); - // Default constructor. + /// Copy constructor. ACE_INET_Addr (const ACE_INET_Addr &); - // Copy constructor. + /// Creates an <ACE_INET_Addr> from a sockaddr_in structure. ACE_INET_Addr (const sockaddr_in *, int len); - // Creates an <ACE_INET_Addr> from a sockaddr_in structure. + /// Creates an <ACE_INET_Addr> from a <port_number> and the remote + /// <host_name>. ACE_INET_Addr (u_short port_number, const char host_name[]); - // Creates an <ACE_INET_Addr> from a <port_number> and the remote - // <host_name>. + /** + * Initializes an <ACE_INET_Addr> from the <address>, which can be + * "ip-number:port-number" (e.g., "tango.cs.wustl.edu:1234" or + * "128.252.166.57:1234"). If there is no ':' in the <address> it + * is assumed to be a port number, with the IP address being + * INADDR_ANY. + */ ACE_EXPLICIT ACE_INET_Addr (const char address[]); - // Initializes an <ACE_INET_Addr> from the <address>, which can be - // "ip-number:port-number" (e.g., "tango.cs.wustl.edu:1234" or - // "128.252.166.57:1234"). If there is no ':' in the <address> it - // is assumed to be a port number, with the IP address being - // INADDR_ANY. + /** + * Creates an <ACE_INET_Addr> from a <port_number> and an Internet + * <ip_addr>. This method assumes that <port_number> and <ip_addr> + * are in host byte order. + */ ACE_INET_Addr (u_short port_number, ACE_UINT32 ip_addr = INADDR_ANY); - // Creates an <ACE_INET_Addr> from a <port_number> and an Internet - // <ip_addr>. This method assumes that <port_number> and <ip_addr> - // are in host byte order. + /// Uses <getservbyname> to create an <ACE_INET_Addr> from a + /// <port_name>, the remote <host_name>, and the <protocol>. ACE_INET_Addr (const char port_name[], const char host_name[], const char protocol[] = "tcp"); - // Uses <getservbyname> to create an <ACE_INET_Addr> from a - // <port_name>, the remote <host_name>, and the <protocol>. + /** + * Uses <getservbyname> to create an <ACE_INET_Addr> from a + * <port_name>, an Internet <ip_addr>, and the <protocol>. This + * method assumes that <ip_addr> is in host byte order. + */ ACE_INET_Addr (const char port_name[], ACE_UINT32 ip_addr, const char protocol[] = "tcp"); - // Uses <getservbyname> to create an <ACE_INET_Addr> from a - // <port_name>, an Internet <ip_addr>, and the <protocol>. This - // method assumes that <ip_addr> is in host byte order. #if defined (ACE_HAS_WCHAR) ACE_INET_Addr (u_short port_number, @@ -88,56 +94,64 @@ public: const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp")); #endif /* ACE_HAS_WCHAR */ + /// Default dtor. ~ACE_INET_Addr (void); - // Default dtor. // = Direct initialization methods. // These methods are useful after the object has been constructed. + /// Initializes from another <ACE_INET_Addr>. int set (const ACE_INET_Addr &); - // Initializes from another <ACE_INET_Addr>. + /** + * Initializes an <ACE_INET_Addr> from a <port_number> and the + * remote <host_name>. If <encode> is enabled then <port_number> is + * converted into network byte order, otherwise it is assumed to be + * in network byte order already and are passed straight through. + */ int set (u_short port_number, const char host_name[], int encode = 1); - // Initializes an <ACE_INET_Addr> from a <port_number> and the - // remote <host_name>. If <encode> is enabled then <port_number> is - // converted into network byte order, otherwise it is assumed to be - // in network byte order already and are passed straight through. + /** + * Initializes an <ACE_INET_Addr> from a <port_number> and an + * Internet <ip_addr>. If <encode> is enabled then <port_number> + * and <ip_addr> are converted into network byte order, otherwise + * they are assumed to be in network byte order already and are + * passed straight through. + */ int set (u_short port_number, ACE_UINT32 ip_addr = INADDR_ANY, int encode = 1); - // Initializes an <ACE_INET_Addr> from a <port_number> and an - // Internet <ip_addr>. If <encode> is enabled then <port_number> - // and <ip_addr> are converted into network byte order, otherwise - // they are assumed to be in network byte order already and are - // passed straight through. + /// Uses <getservbyname> to initialize an <ACE_INET_Addr> from a + /// <port_name>, the remote <host_name>, and the <protocol>. int set (const char port_name[], const char host_name[], const char protocol[] = "tcp"); - // Uses <getservbyname> to initialize an <ACE_INET_Addr> from a - // <port_name>, the remote <host_name>, and the <protocol>. + /** + * Uses <getservbyname> to initialize an <ACE_INET_Addr> from a + * <port_name>, an <ip_addr>, and the <protocol>. This assumes that + * <ip_addr> is already in network byte order. + */ int set (const char port_name[], ACE_UINT32 ip_addr, const char protocol[] = "tcp"); - // Uses <getservbyname> to initialize an <ACE_INET_Addr> from a - // <port_name>, an <ip_addr>, and the <protocol>. This assumes that - // <ip_addr> is already in network byte order. + /** + * Initializes an <ACE_INET_Addr> from the <addr>, which can be + * "ip-number:port-number" (e.g., "tango.cs.wustl.edu:1234" or + * "128.252.166.57:1234"). If there is no ':' in the <address> it + * is assumed to be a port number, with the IP address being + * INADDR_ANY. + */ int set (const char addr[]); - // Initializes an <ACE_INET_Addr> from the <addr>, which can be - // "ip-number:port-number" (e.g., "tango.cs.wustl.edu:1234" or - // "128.252.166.57:1234"). If there is no ':' in the <address> it - // is assumed to be a port number, with the IP address being - // INADDR_ANY. + /// Creates an <ACE_INET_Addr> from a sockaddr_in structure. int set (const sockaddr_in *, int len); - // Creates an <ACE_INET_Addr> from a sockaddr_in structure. #if defined (ACE_HAS_WCHAR) int set (u_short port_number, @@ -155,30 +169,34 @@ public: int set (const wchar_t addr[]); #endif /* ACE_HAS_WCHAR */ + /// Return a pointer to the underlying network address. virtual void *get_addr (void) const; - // Return a pointer to the underlying network address. + /// Set a pointer to the address. virtual void set_addr (void *, int len); - // Set a pointer to the address. + /** + * Transform the current <ACE_INET_Addr> address into string format. + * If <ipaddr_format> is non-0 this produces "ip-number:port-number" + * (e.g., "128.252.166.57:1234"), whereas if <ipaddr_format> is 0 + * this produces "ip-name:port-number" (e.g., + * "tango.cs.wustl.edu:1234"). Returns -1 if the <size> of the + * <buffer> is too small, else 0. + */ virtual int addr_to_string (ACE_TCHAR buffer[], size_t size, int ipaddr_format = 1) const; - // Transform the current <ACE_INET_Addr> address into string format. - // If <ipaddr_format> is non-0 this produces "ip-number:port-number" - // (e.g., "128.252.166.57:1234"), whereas if <ipaddr_format> is 0 - // this produces "ip-name:port-number" (e.g., - // "tango.cs.wustl.edu:1234"). Returns -1 if the <size> of the - // <buffer> is too small, else 0. + /** + * Initializes an <ACE_INET_Addr> from the <address>, which can be + * "ip-addr:port-number" (e.g., "tango.cs.wustl.edu:1234"), + * "ip-addr:port-name" (e.g., "tango.cs.wustl.edu:telnet"), + * "ip-number:port-number" (e.g., "128.252.166.57:1234"), or + * "ip-number:port-name" (e.g., "128.252.166.57:telnet"). If there + * is no ':' in the <address> it is assumed to be a port number, + * with the IP address being INADDR_ANY. + */ virtual int string_to_addr (const char address[]); - // Initializes an <ACE_INET_Addr> from the <address>, which can be - // "ip-addr:port-number" (e.g., "tango.cs.wustl.edu:1234"), - // "ip-addr:port-name" (e.g., "tango.cs.wustl.edu:telnet"), - // "ip-number:port-number" (e.g., "128.252.166.57:1234"), or - // "ip-number:port-name" (e.g., "128.252.166.57:telnet"). If there - // is no ':' in the <address> it is assumed to be a port number, - // with the IP address being INADDR_ANY. #if defined (ACE_HAS_WCHAR) /* @@ -187,64 +205,72 @@ public: #endif /* ACE_HAS_WCHAR */ + /** + * Sets the port number without affecting the host name. If + * <encode> is enabled then <port_number> is converted into network + * byte order, otherwise it is assumed to be in network byte order + * already and are passed straight through. + */ void set_port_number (u_short, int encode = 1); - // Sets the port number without affecting the host name. If - // <encode> is enabled then <port_number> is converted into network - // byte order, otherwise it is assumed to be in network byte order - // already and are passed straight through. + /// Return the port number, converting it into host byte order. u_short get_port_number (void) const; - // Return the port number, converting it into host byte order. + /** + * Return the character representation of the name of the host, + * storing it in the <hostname> (which is assumed to be + * <hostnamelen> bytes long). This version is reentrant. + */ int get_host_name (char hostname[], size_t hostnamelen) const; - // Return the character representation of the name of the host, - // storing it in the <hostname> (which is assumed to be - // <hostnamelen> bytes long). This version is reentrant. #if defined (ACE_HAS_WCHAR) int get_host_name (wchar_t hostname[], size_t hostnamelen) const; #endif /* ACE_HAS_WCHAR */ + /** + * Return the character representation of the hostname (this version + * is non-reentrant since it returns a pointer to a static data + * area). + */ const char *get_host_name (void) const; - // Return the character representation of the hostname (this version - // is non-reentrant since it returns a pointer to a static data - // area). + /// Return the "dotted decimal" Internet address. const char *get_host_addr (void) const; - // Return the "dotted decimal" Internet address. + /// Return the 4-byte IP address, converting it into host byte + /// order. ACE_UINT32 get_ip_address (void) const; - // Return the 4-byte IP address, converting it into host byte - // order. + /** + * Returns true if <this> is less than <rhs>. In this context, + * "less than" is defined in terms of IP address and TCP port + * number. This operator makes it possible to use <ACE_INET_Addr>s + * in STL maps. + */ int operator < (const ACE_INET_Addr &rhs); - // Returns true if <this> is less than <rhs>. In this context, - // "less than" is defined in terms of IP address and TCP port - // number. This operator makes it possible to use <ACE_INET_Addr>s - // in STL maps. + /// Compare two addresses for equality. The addresses are considered + /// equal if they contain the same IP address and port number. int operator == (const ACE_INET_Addr &SAP) const; - // Compare two addresses for equality. The addresses are considered - // equal if they contain the same IP address and port number. + /// Compare two addresses for inequality. int operator != (const ACE_INET_Addr &SAP) const; - // Compare two addresses for inequality. + /// Computes and returns hash value. virtual u_long hash (void) const; - // Computes and returns hash value. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Underlying representation. sockaddr_in inet_addr_; - // Underlying representation. }; #if defined (__ACE_INLINE__) diff --git a/ace/IOStream.h b/ace/IOStream.h index 721d1eafe53..3846640acda 100644 --- a/ace/IOStream.h +++ b/ace/IOStream.h @@ -1,19 +1,16 @@ // -*- C++ -*- -// -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// IOStream.h -// -// = AUTHOR -// James CE Johnson <jcej@lads.com> and Jim Crossley <jim@lads.com> -// -// ============================================================================ +//============================================================================= +/** + * @file IOStream.h + * + * $Id$ + * + * @author James CE Johnson <jcej@lads.com> + * @author Jim Crossley <jim@lads.com> + */ +//============================================================================= + #ifndef ACE_IOSTREAM_H #define ACE_IOSTREAM_H @@ -81,139 +78,137 @@ public: #endif /* ACE_HAS_STRING_CLASS */ +/** + * @class ACE_Streambuf + * + * @brief Create your custom streambuf by providing and ACE_*_Stream + * object to this template. I have tested it with + * ACE_SOCK_Stream and it should work fine for others as well. + * + * For any iostream object, the real work is done by the + * underlying streambuf class. That is what we create here. + * A streambuf has an internal buffer area into which data is + * read and written as the iostream requests and provides data. + * At some point during the read process, the iostream will + * realize that the streambuf has no more data. The underflow + * function of the streambuf is then called. + * Likewise, during the write process, the iostream will + * eventually notice that the streabuf's buffer has become full + * and will invoke the overflow function. + * The empty/full state of the read/write "buffers" are + * controled by two sets pointers. One set is dedicated to + * read, the other to write. These pointers, in turn, reference + * a common buffer that is to be shared by both read and write + * operations. It is this common buffer to which data is + * written and from which it is read. + * The common buffer is used by functions of the streambuf as + * well as the iostream. Because of this and the fact that it + * is "shared" by both read and write operators, there is a + * danger of data corruption if read and write operations are + * allowed to take place "at the same time". + * To prevent data corruption, we manipulate the read and write + * pointer sets so that the streambuf is in either a read-mode + * or write-mode at all times and can never be in both modes at + * the same time. + * In the constructor: set the read and write sets to NULL This + * causes the underflow or overflow operators to be invoked at + * the first IO activity of the iostream. + * In the underflow function we arrange for the common buffer to + * reference our read buffer and for the write pointer set to be + * disabled. If a write operation is performed by the iostream + * this will cause the overflow function to be invoked. + * In the overflow function we arrange for the common buffer to + * reference our write buffer and for the read pointer set to be + * disabled. This causes the underflow function to be invoked + * when the iostream "changes our mode". + * The overflow function will also invoke the send_n function to + * flush the buffered data to our peer. Similarly, the sync and + * syncout functions will cause send_n to be invoked to send the + * data. + * Since socket's and the like do not support seeking, there can + * be no method for "syncing" the input. However, since we + * maintain separate read/write buffers, no data is lost by + * "syncing" the input. It simply remains buffered. + */ class ACE_Export ACE_Streambuf : public streambuf { - // = TITLE - // Create your custom streambuf by providing and ACE_*_Stream - // object to this template. I have tested it with - // ACE_SOCK_Stream and it should work fine for others as well. - // - // = DESCRIPTION - // For any iostream object, the real work is done by the - // underlying streambuf class. That is what we create here. - // - // A streambuf has an internal buffer area into which data is - // read and written as the iostream requests and provides data. - // At some point during the read process, the iostream will - // realize that the streambuf has no more data. The underflow - // function of the streambuf is then called. - // - // Likewise, during the write process, the iostream will - // eventually notice that the streabuf's buffer has become full - // and will invoke the overflow function. - // - // The empty/full state of the read/write "buffers" are - // controled by two sets pointers. One set is dedicated to - // read, the other to write. These pointers, in turn, reference - // a common buffer that is to be shared by both read and write - // operations. It is this common buffer to which data is - // written and from which it is read. - // - // The common buffer is used by functions of the streambuf as - // well as the iostream. Because of this and the fact that it - // is "shared" by both read and write operators, there is a - // danger of data corruption if read and write operations are - // allowed to take place "at the same time". - // - // To prevent data corruption, we manipulate the read and write - // pointer sets so that the streambuf is in either a read-mode - // or write-mode at all times and can never be in both modes at - // the same time. - // - // In the constructor: set the read and write sets to NULL This - // causes the underflow or overflow operators to be invoked at - // the first IO activity of the iostream. - // - // In the underflow function we arrange for the common buffer to - // reference our read buffer and for the write pointer set to be - // disabled. If a write operation is performed by the iostream - // this will cause the overflow function to be invoked. - // - // In the overflow function we arrange for the common buffer to - // reference our write buffer and for the read pointer set to be - // disabled. This causes the underflow function to be invoked - // when the iostream "changes our mode". - // - // The overflow function will also invoke the send_n function to - // flush the buffered data to our peer. Similarly, the sync and - // syncout functions will cause send_n to be invoked to send the - // data. - // - // Since socket's and the like do not support seeking, there can - // be no method for "syncing" the input. However, since we - // maintain separate read/write buffers, no data is lost by - // "syncing" the input. It simply remains buffered. public: + /** + * If the default allocation strategey were used the common buffer + * would be deleted when the object destructs. Since we are + * providing separate read/write buffers, it is up to us to manage + * their memory. + */ virtual ~ACE_Streambuf (void); - // If the default allocation strategey were used the common buffer - // would be deleted when the object destructs. Since we are - // providing separate read/write buffers, it is up to us to manage - // their memory. + /// Get the current Time_Value pointer and provide a new one. ACE_Time_Value *recv_timeout (ACE_Time_Value *tv = NULL); - // Get the current Time_Value pointer and provide a new one. + /** + * Use this to allocate a new/different buffer for put operations. + * If you do not provide a buffer pointer, one will be allocated. + * That is the preferred method. If you do provide a buffer, the + * size must match that being used by the get buffer. If + * successful, you will receive a pointer to the current put buffer. + * It is your responsibility to delete this memory when you are done + * with it. + */ char *reset_put_buffer (char *newBuffer = NULL, u_int _streambuf_size = 0, u_int _pptr = 0 ); - // Use this to allocate a new/different buffer for put operations. - // If you do not provide a buffer pointer, one will be allocated. - // That is the preferred method. If you do provide a buffer, the - // size must match that being used by the get buffer. If - // successful, you will receive a pointer to the current put buffer. - // It is your responsibility to delete this memory when you are done - // with it. + /// Return the number of bytes to be 'put' onto the stream media. + /// pbase + put_avail = pptr u_int put_avail (void); - // Return the number of bytes to be 'put' onto the stream media. - // pbase + put_avail = pptr + /** + * Use this to allocate a new/different buffer for get operations. + * If you do not provide a buffer pointer, one will be allocated. + * That is the preferred method. If you do provide a buffer, the + * size must match that being used by the put buffer. If + * successful, you will receive a pointer to the current get buffer. + * It is your responsibility to delete this memory when you are done + * with it. + */ char *reset_get_buffer (char *newBuffer = NULL, u_int _streambuf_size = 0, u_int _gptr = 0, u_int _egptr = 0); - // Use this to allocate a new/different buffer for get operations. - // If you do not provide a buffer pointer, one will be allocated. - // That is the preferred method. If you do provide a buffer, the - // size must match that being used by the put buffer. If - // successful, you will receive a pointer to the current get buffer. - // It is your responsibility to delete this memory when you are done - // with it. + /// Return the number of bytes not yet gotten. eback + get_waiting = + /// gptr u_int get_waiting (void); - // Return the number of bytes not yet gotten. eback + get_waiting = - // gptr + /// Return the number of bytes in the get area (includes some already + /// gotten); eback + get_avail = egptr u_int get_avail (void); - // Return the number of bytes in the get area (includes some already - // gotten); eback + get_avail = egptr + /// Query the streambuf for the size of its buffers. u_int streambuf_size (void); - // Query the streambuf for the size of its buffers. + /// Did we take an error because of an IO operation timeout? Note: + /// Invoking this resets the flag. u_char timeout (void); - // Did we take an error because of an IO operation timeout? Note: - // Invoking this resets the flag. protected: ACE_Streambuf (u_int streambuf_size, int io_mode); + /// Sync both input and output. See syncin/syncout below for + /// descriptions. virtual int sync (void); - // Sync both input and output. See syncin/syncout below for - // descriptions. // = Signatures for the underflow/overflow discussed above. virtual int underflow (void); + /// The overflow function receives the character which caused the + /// overflow. virtual int overflow (int = EOF); - // The overflow function receives the character which caused the - // overflow. + /// Resets the <base> pointer and streambuf mode. This is used + /// internally when get/put buffers are allocatd. void reset_base (void); - // Resets the <base> pointer and streambuf mode. This is used - // internally when get/put buffers are allocatd. protected: // = Two pointer sets for manipulating the read/write areas. @@ -231,50 +226,62 @@ protected: const u_char get_mode_; const u_char put_mode_; + /// mode tells us if we're working for an istream, ostream, or + /// iostream. int mode_; - // mode tells us if we're working for an istream, ostream, or - // iostream. + /// This defines the size of the input and output buffers. It can be + /// set by the object constructor. const u_int streambuf_size_; - // This defines the size of the input and output buffers. It can be - // set by the object constructor. + /// Did we take an error because of an IO operation timeout? u_char timeout_; - // Did we take an error because of an IO operation timeout? + /// We want to allow the user to provide Time_Value pointers to + /// prevent infinite blocking while waiting to receive data. ACE_Time_Value recv_timeout_value_; ACE_Time_Value *recv_timeout_; - // We want to allow the user to provide Time_Value pointers to - // prevent infinite blocking while waiting to receive data. + /** + * syncin is called when the input needs to be synced with the + * source file. In a filebuf, this results in the <seek> system + * call being used. We can't do that on socket-like connections, so + * this does basically nothing. That's safe because we have a + * separate read buffer to maintain the already-read data. In a + * filebuf, the single common buffer is used forcing the <seek> + * call. + */ int syncin (void); - // syncin is called when the input needs to be synced with the - // source file. In a filebuf, this results in the <seek> system - // call being used. We can't do that on socket-like connections, so - // this does basically nothing. That's safe because we have a - // separate read buffer to maintain the already-read data. In a - // filebuf, the single common buffer is used forcing the <seek> - // call. + /// syncout is called when the output needs to be flushed. This is + /// easily done by calling the peer's send_n function. int syncout (void); - // syncout is called when the output needs to be flushed. This is - // easily done by calling the peer's send_n function. + /// flushbuf is the worker of syncout. It is a separate function + /// because it gets used sometimes in different context. int flushbuf (void); - // flushbuf is the worker of syncout. It is a separate function - // because it gets used sometimes in different context. + /** + * fillbuf is called in a couple of places. This is the worker of + * underflow. It will attempt to fill the read buffer from the + * peer. + */ int fillbuf (void); - // fillbuf is called in a couple of places. This is the worker of - // underflow. It will attempt to fill the read buffer from the - // peer. + /** + * Used by fillbuf and others to get exactly one byte from the peer. + * recv_n is used to be sure we block until something is available. + * It is virtual because we really need to override it for + * datagram-derived objects. + */ virtual int get_one_byte (void); - // Used by fillbuf and others to get exactly one byte from the peer. - // recv_n is used to be sure we block until something is available. - // It is virtual because we really need to override it for - // datagram-derived objects. + /** + * Stream connections and "unconnected connections" (ie -- + * datagrams) need to work just a little differently. We derive + * custom Streambuf objects for them and provide these functions at + * that time. + */ virtual ssize_t send (char *buf, ssize_t len) = 0; virtual ssize_t recv (char *buf, @@ -288,10 +295,6 @@ protected: ssize_t len, int flags = 0, ACE_Time_Value *tv = NULL) = 0; - // Stream connections and "unconnected connections" (ie -- - // datagrams) need to work just a little differently. We derive - // custom Streambuf objects for them and provide these functions at - // that time. virtual ACE_HANDLE get_handle (void); diff --git a/ace/IOStream_T.h b/ace/IOStream_T.h index 361c5c4669e..b853cd0f1f8 100644 --- a/ace/IOStream_T.h +++ b/ace/IOStream_T.h @@ -1,23 +1,20 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// IOStream_T.h -// -// = AUTHOR -// James CE Johnson <jcej@lads.com> and Jim Crossley <jim@lads.com> -// -// = NOTE -// This file should not be #included directly by application code. -// Instead, it should #include "ace/IOStream.h". That's because -// we only put some conditional compilations in that file. -// -// ============================================================================ + +//============================================================================= +/** + * @file IOStream_T.h + * + * $Id$ + * + * @author James CE Johnson <jcej@lads.com> + * @author Jim Crossley <jim@lads.com> + * + * This file should not be #included directly by application + * code. Instead, it should #include "ace/IOStream.h". That's because + * we only put some conditional compilations in that file. + */ +//============================================================================= + #ifndef ACE_IOSTREAM_T_H #define ACE_IOSTREAM_T_H @@ -43,13 +40,15 @@ template <class STREAM> class ACE_Streambuf_T : public ACE_Streambuf { public: + /** + * We will be given a STREAM by the iostream object which creates + * us. See the ACE_IOStream template for how that works. Like + * other streambuf objects, we can be input-only, output-only or + * both. + */ ACE_Streambuf_T (STREAM *peer, u_int streambuf_size = ACE_STREAMBUF_SIZE, int io_mode = ios::in | ios::out); - // We will be given a STREAM by the iostream object which creates - // us. See the ACE_IOStream template for how that works. Like - // other streambuf objects, we can be input-only, output-only or - // both. virtual ssize_t send (char *buf, ssize_t len); @@ -70,78 +69,82 @@ public: protected: virtual ACE_HANDLE get_handle (void); + /// This will be our ACE_SOCK_Stream or similar object. STREAM *peer_; - // This will be our ACE_SOCK_Stream or similar object. }; +/** + * @class ACE_IOStream + * + * @brief A template adapter for creating an iostream-like object using + * an ACE IPC Stream for the actual I/O. Iostreams use an + * underlying streambuf object for the IO interface. The + * iostream class and derivatives provide you with a host of + * convenient operators that access the streambuf. + * + * We inherit all characteristics of iostream and your <STREAM> + * class. When you create a new class from this template, you + * can use it anywhere you would have used your original + * <STREAM> class. + * To create an iostream for your favorite ACE IPC class (e.g., + * <ACE_SOCK_Stream>), feed that class to this template's + * <STREAM> parameter, e.g., + * typedef ACE_Svc_Handler<ACE_SOCK_iostream, + * ACE_INET_Addr, ACE_NULL_SYNCH> + * Service_Handler; + * Because the operators in the iostream class are not virtual, + * you cannot easily provide overloads in your custom + * ACE_IOStream classes. To make these things work correctly, + * you need to overload ALL operators of the ACE_IOStream you + * create. I've attempted to do that here to make things easier + * for you but there are no guarantees. + * In the iostream.cpp file is an example of why it is necessary + * to overload all of the get/put operators when you want to + * customize only one or two. + */ template <class STREAM> class ACE_IOStream : public iostream, public STREAM { - // = TITLE - // A template adapter for creating an iostream-like object using - // an ACE IPC Stream for the actual I/O. Iostreams use an - // underlying streambuf object for the IO interface. The - // iostream class and derivatives provide you with a host of - // convenient operators that access the streambuf. - // - // = DESCRIPTION - // We inherit all characteristics of iostream and your <STREAM> - // class. When you create a new class from this template, you - // can use it anywhere you would have used your original - // <STREAM> class. - // - // To create an iostream for your favorite ACE IPC class (e.g., - // <ACE_SOCK_Stream>), feed that class to this template's - // <STREAM> parameter, e.g., - // - // typedef ACE_Svc_Handler<ACE_SOCK_iostream, - // ACE_INET_Addr, ACE_NULL_SYNCH> - // Service_Handler; - // - // Because the operators in the iostream class are not virtual, - // you cannot easily provide overloads in your custom - // ACE_IOStream classes. To make these things work correctly, - // you need to overload ALL operators of the ACE_IOStream you - // create. I've attempted to do that here to make things easier - // for you but there are no guarantees. - // - // In the iostream.cpp file is an example of why it is necessary - // to overload all of the get/put operators when you want to - // customize only one or two. public: // = Initialization and termination methods. ACE_IOStream (STREAM &stream, u_int streambuf_size = ACE_STREAMBUF_SIZE); + /** + * The default constructor. This will initiailze your STREAM and + * then setup the iostream baseclass to use a custom streambuf based + * on STREAM. + */ ACE_IOStream (u_int streambuf_size = ACE_STREAMBUF_SIZE); - // The default constructor. This will initiailze your STREAM and - // then setup the iostream baseclass to use a custom streambuf based - // on STREAM. + /// We have to get rid of the <streambuf_> ourselves since we gave it + /// to the <iostream> base class; virtual ~ACE_IOStream (void); - // We have to get rid of the <streambuf_> ourselves since we gave it - // to the <iostream> base class; + /// The only ambituity in the multiple inheritance is the <close> + /// function. virtual int close (void); - // The only ambituity in the multiple inheritance is the <close> - // function. + /** + * Returns 1 if we're at the end of the <STREAM>, i.e., if the + * connection has closed down or an error has occurred, else 0. + * Under the covers, <eof> calls the streambuf's <timeout> function + * which will reset the timeout flag. As as result, you should save + * the return of <eof> and check it instead of calling <eof> + * successively. + */ int eof (void) const; - // Returns 1 if we're at the end of the <STREAM>, i.e., if the - // connection has closed down or an error has occurred, else 0. - // Under the covers, <eof> calls the streambuf's <timeout> function - // which will reset the timeout flag. As as result, you should save - // the return of <eof> and check it instead of calling <eof> - // successively. #if defined (ACE_HAS_STRING_CLASS) + /** + * A simple string operator. The base <iostream> has them for char* + * but that isn't always the best thing for a <String>. If we don't + * provide our own here, we may not get what we want. + */ virtual ACE_IOStream<STREAM> &operator>> (ACE_IOStream_String &v); - // A simple string operator. The base <iostream> has them for char* - // but that isn't always the best thing for a <String>. If we don't - // provide our own here, we may not get what we want. + /// The converse of the <String::put> operator. virtual ACE_IOStream<STREAM> &operator<< (ACE_IOStream_String &v); - // The converse of the <String::put> operator. #endif /* ACE_HAS_STRING_CLASS */ // = Using the macros to provide get/set operators. @@ -209,14 +212,14 @@ public: virtual void osfx (void) { iostream::osfx (); } #endif /* ACE_LACKS_IOSTREAM_FX */ + /// Allow the programmer to provide a timeout for read operations. + /// Give it a pointer to NULL to block forever. ACE_IOStream<STREAM> & operator>> (ACE_Time_Value *&tv); - // Allow the programmer to provide a timeout for read operations. - // Give it a pointer to NULL to block forever. protected: + /// This is where all of the action takes place. The streambuf_ is + /// the interface to the underlying STREAM. ACE_Streambuf_T<STREAM> *streambuf_; - // This is where all of the action takes place. The streambuf_ is - // the interface to the underlying STREAM. private: // = Private methods. @@ -232,20 +235,22 @@ private: ACE_UNIMPLEMENTED_FUNC (ssize_t recv_n (...)) }; +/** + * @class ACE_SOCK_Dgram_SC + * + * @brief "Dgram_SC" is short for "Datagram Self-Contained." + * + * Datagrams don't have the notion of a "peer". Each send and + * receive on a datagram can go to a different peer if you want. + * If you're using datagrams for stream activity, you probably + * want 'em all to go to (and come from) the same place. That's + * what this class is for. Here, we keep an address object so + * that we can remember who last sent us data. When we write + * back, we're then able to write back to that same address. + */ template <class STREAM> class ACE_SOCK_Dgram_SC : public STREAM { - // = TITLE - // "Dgram_SC" is short for "Datagram Self-Contained." - // - // = DESCRIPTION - // Datagrams don't have the notion of a "peer". Each send and - // receive on a datagram can go to a different peer if you want. - // If you're using datagrams for stream activity, you probably - // want 'em all to go to (and come from) the same place. That's - // what this class is for. Here, we keep an address object so - // that we can remember who last sent us data. When we write - // back, we're then able to write back to that same address. public: ACE_SOCK_Dgram_SC (void); ACE_SOCK_Dgram_SC (STREAM &source, diff --git a/ace/IO_Cntl_Msg.h b/ace/IO_Cntl_Msg.h index 8e8e4380dd9..549becfa70d 100644 --- a/ace/IO_Cntl_Msg.h +++ b/ace/IO_Cntl_Msg.h @@ -1,88 +1,94 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// IO_Cntl_Msg.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file IO_Cntl_Msg.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_IO_CNTL_MSG_H #define ACE_IO_CNTL_MSG_H #include "ace/pre.h" +/** + * @class ACE_IO_Cntl_Msg + * + * @brief Data format for IOCTL messages + */ class ACE_Export ACE_IO_Cntl_Msg { - // = TITLE - // Data format for IOCTL messages public: enum { - SET_LWM = 1, // Set the low water mark. - GET_LWM = 2, // Get the low water mark. - SET_HWM = 3, // Set the high water mark. - GET_HWM = 4, // Get the high water mark. - MOD_LINK = 5, // Link modules - MOD_UNLINK = 6 // Unlink modules + /// Set the low water mark. + SET_LWM = 1, + /// Get the low water mark. + GET_LWM = 2, + /// Set the high water mark. + SET_HWM = 3, + /// Get the high water mark. + GET_HWM = 4, + /// Link modules + MOD_LINK = 5, + /// Unlink modules + MOD_UNLINK = 6 }; typedef u_short ACE_IO_Cntl_Cmds; // = Initialization method. + /// Initialize the control message. ACE_IO_Cntl_Msg (ACE_IO_Cntl_Cmds c) { this->cmd_ = c; } - // Initialize the control message. // = Get/set methods + /// Get command. ACE_IO_Cntl_Cmds cmd (void) { return this->cmd_; } - // Get command. + /// Set command. void cmd (ACE_IO_Cntl_Cmds c) { this->cmd_ = c; } - // Set command. + /// Get count. size_t count (void) { return this->count_; } - // Get count. + /// Set count. void count (size_t c) { this->count_ = c; } - // Set count. + /// Get error. int error (void) { return this->error_; } - // Get error. + /// Set error. void error (int e) { this->error_ = e; } - // Set error. + /// Get return value. int rval (void) { return this->rval_; } - // Get return value. + /// Set return value. void rval (int r) { this->rval_ = r; } - // Set return value. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Command. ACE_IO_Cntl_Cmds cmd_; - // Command. + /// Count. size_t count_; - // Count. + /// Error. int error_; - // Error. + /// Return value int rval_; - // Return value }; #include "ace/post.h" diff --git a/ace/IO_SAP.h b/ace/IO_SAP.h index f6b0e430a64..4cc1d5cda84 100644 --- a/ace/IO_SAP.h +++ b/ace/IO_SAP.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// IO_SAP.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file IO_SAP.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_IO_SAP_H #define ACE_IO_SAP_H @@ -24,57 +21,65 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_IO_SAP + * + * @brief Defines the methods for the base class of the <ACE_IO_SAP> + * abstraction, which includes <ACE_FILE> and <ACE_DEV>. + */ class ACE_Export ACE_IO_SAP { - // = TITLE - // Defines the methods for the base class of the <ACE_IO_SAP> - // abstraction, which includes <ACE_FILE> and <ACE_DEV>. public: enum { - INVALID_HANDLE = -1 // Be consistent with Winsock + /// Be consistent with Winsock + INVALID_HANDLE = -1 }; + /// Default dtor. ~ACE_IO_SAP (void); - // Default dtor. + /// Interface for ioctl. int control (int cmd, void *) const; - // Interface for ioctl. // = Common I/O handle options related to files. + /** + * Enable asynchronous I/O (ACE_SIGIO), urgent data (ACE_SIGURG), + * non-blocking I/O (ACE_NONBLOCK), or close-on-exec (ACE_CLOEXEC), + * which is passed as the <value>. + */ int enable (int value) const; - // Enable asynchronous I/O (ACE_SIGIO), urgent data (ACE_SIGURG), - // non-blocking I/O (ACE_NONBLOCK), or close-on-exec (ACE_CLOEXEC), - // which is passed as the <value>. + /** + * Disable asynchronous I/O (ACE_SIGIO), urgent data (ACE_SIGURG), + * non-blocking I/O (ACE_NONBLOCK), or close-on-exec (ACE_CLOEXEC), + * which is passed as the <value>. + */ int disable (int value) const; - // Disable asynchronous I/O (ACE_SIGIO), urgent data (ACE_SIGURG), - // non-blocking I/O (ACE_NONBLOCK), or close-on-exec (ACE_CLOEXEC), - // which is passed as the <value>. + /// Get the underlying handle. ACE_HANDLE get_handle (void) const; - // Get the underlying handle. + /// Set the underlying handle. void set_handle (ACE_HANDLE handle); - // Set the underlying handle. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Ensure that ACE_IO_SAP is an abstract base class. ACE_IO_SAP (void); - // Ensure that ACE_IO_SAP is an abstract base class. private: + /// Underlying I/O handle. ACE_HANDLE handle_; - // Underlying I/O handle. + /// Cache the process ID. static pid_t pid_; - // Cache the process ID. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/IPC_SAP.h b/ace/IPC_SAP.h index 2bc74c66ec2..e337a653340 100644 --- a/ace/IPC_SAP.h +++ b/ace/IPC_SAP.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// IPC_SAP.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file IPC_SAP.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_IPC_SAP_H #define ACE_IPC_SAP_H @@ -24,53 +21,60 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_IPC_SAP + * + * @brief Defines the member functions for the base class of the + * ACE_IPC_SAP abstraction. + */ class ACE_Export ACE_IPC_SAP { - // = TITLE - // Defines the member functions for the base class of the - // ACE_IPC_SAP abstraction. public: + /// Default dtor. ~ACE_IPC_SAP (void); - // Default dtor. + /// Interface for ioctl. int control (int cmd, void *) const; - // Interface for ioctl. // = Common I/O handle options related to sockets. + /** + * Enable asynchronous I/O (ACE_SIGIO), urgent data (ACE_SIGURG), + * non-blocking I/O (ACE_NONBLOCK), or close-on-exec (ACE_CLOEXEC), + * which is passed as the <value>. + */ int enable (int value) const; - // Enable asynchronous I/O (ACE_SIGIO), urgent data (ACE_SIGURG), - // non-blocking I/O (ACE_NONBLOCK), or close-on-exec (ACE_CLOEXEC), - // which is passed as the <value>. + /** + * Disable asynchronous I/O (ACE_SIGIO), urgent data (ACE_SIGURG), + * non-blocking I/O (ACE_NONBLOCK), or close-on-exec (ACE_CLOEXEC), + * which is passed as the <value>. + */ int disable (int value) const; - // Disable asynchronous I/O (ACE_SIGIO), urgent data (ACE_SIGURG), - // non-blocking I/O (ACE_NONBLOCK), or close-on-exec (ACE_CLOEXEC), - // which is passed as the <value>. + /// Get the underlying handle. ACE_HANDLE get_handle (void) const; - // Get the underlying handle. + /// Set the underlying handle. void set_handle (ACE_HANDLE handle); - // Set the underlying handle. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Ensure that ACE_IPC_SAP is an abstract base class. + /// Default constructor. ACE_IPC_SAP (void); - // Default constructor. private: + /// Underlying I/O handle. ACE_HANDLE handle_; - // Underlying I/O handle. + /// Cache the process ID. static pid_t pid_; - // Cache the process ID. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/Init_ACE.h b/ace/Init_ACE.h index 19ec9dd5fbd..4e2ed9285c5 100644 --- a/ace/Init_ACE.h +++ b/ace/Init_ACE.h @@ -1,4 +1,17 @@ -// $Id$ + +//============================================================================= +/** + * @file Init_ACE.h + * + * $Id$ + * + * This class consolidates the operations on the Handles. + * + * + * @author Priyanka Gontla <pgontla@ece.uci.edu> + */ +//============================================================================= + #ifndef ACE_INIT_ACE_H #define ACE_INIT_ACE_H @@ -10,31 +23,38 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Init_ACE + * + * @brief Initialize ACE library services. Can be called only once + * per program invocation. + * + */ class ACE_Export ACE_Init_ACE { - - // DESCRIPTION: This class implements the fucntions for the - // initialization and shutting down ACE. - // These functions are called only once per ACE - // invokation. - public: - // Initialize ACE library services. Can be called only once per - // program invocation. +public: + /// Returns 0 on success, -1 on failure, and 1 if it had already been called. + /** + * This class implements the fucntions for the initialization and + * shutting down ACE. These functions are called only once per ACE + * invokation. + */ static int init (void); - // Returns 0 on success, -1 on failure, and 1 if it had already been called. - // Shut down ACE library services. Can be called only once per - // program invocation. + /// Returns 0 on success, -1 on failure, and 1 if it had already been called. + /** + * Shut down ACE library services. Can be called only once per + * program invocation. + */ static int fini (void); - // Returns 0 on success, -1 on failure, and 1 if it had already been called. - - private: +private: + /** + * Counter to match <init>/<fini> calls. <init> must increment it; + * <fini> must decrement it. <fini> then does nothing until it + * reaches 0. + */ static u_int init_fini_count_; - // Counter to match <init>/<fini> calls. <init> must increment it; - // <fini> must decrement it. <fini> then does nothing until it - // reaches 0. - }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/LOCK_SOCK_Acceptor.h b/ace/LOCK_SOCK_Acceptor.h index eaa16fc4e49..720664e65ff 100644 --- a/ace/LOCK_SOCK_Acceptor.h +++ b/ace/LOCK_SOCK_Acceptor.h @@ -1,17 +1,14 @@ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// LOCK_SOCK_Acceptor.h -// -// = AUTHOR -// James Hu and Irfan Pyarali -// -// ============================================================================ + +//============================================================================= +/** + * @file LOCK_SOCK_Acceptor.h + * + * $Id$ + * + * @author James Hu and Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_LOCK_SOCK_ACCEPTOR_H #define ACE_LOCK_SOCK_ACCEPTOR_H @@ -23,32 +20,34 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_LOCK_SOCK_Acceptor + * + * @brief Specialize <ACE_SOCK_Acceptor> to lock around <accept>; + * + * This class is necessary since some OS platforms (e.g., + * Solaris 2.5) do not allow multiple threads/processes to + * simultaneously call <accept> on the same listen-mode + * port/socket. Thus, we need to protect against multiple + * concurrent accesses by using the appropriate type of lock. + */ template <class ACE_LOCK> class ACE_LOCK_SOCK_Acceptor : public ACE_SOCK_Acceptor { - // = TITLE - // Specialize <ACE_SOCK_Acceptor> to lock around <accept>; - // - // = DESCRIPTION - // This class is necessary since some OS platforms (e.g., - // Solaris 2.5) do not allow multiple threads/processes to - // simultaneously call <accept> on the same listen-mode - // port/socket. Thus, we need to protect against multiple - // concurrent accesses by using the appropriate type of lock. public: + /// Accept the connection under the control of the <ACE_LOCK>. int accept (ACE_SOCK_Stream &new_stream, ACE_Addr *remote_addr = 0, ACE_Time_Value *timeout = 0, int restart = 1, int reset_new_handle = 0) const; - // Accept the connection under the control of the <ACE_LOCK>. + /// Return a reference to the lock. ACE_LOCK &lock (void); - // Return a reference to the lock. protected: + /// Type of locking mechanism. ACE_LOCK lock_; - // Type of locking mechanism. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/LSOCK.h b/ace/LSOCK.h index bdbc3003d47..b307e99e2e0 100644 --- a/ace/LSOCK.h +++ b/ace/LSOCK.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// LSOCK.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file LSOCK.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_LOCAL_SOCK_H #define ACE_LOCAL_SOCK_H @@ -26,46 +23,49 @@ #if !defined (ACE_LACKS_UNIX_DOMAIN_SOCKETS) +/** + * @class ACE_LSOCK + * + * @brief Create a Local ACE_SOCK, which is used for passing file + * descriptors. + */ class ACE_Export ACE_LSOCK { - // = TITLE - // Create a Local ACE_SOCK, which is used for passing file - // descriptors. public: #if defined (ACE_HAS_MSG) + /// Send an open FD to another process. int send_handle (const ACE_HANDLE handle) const; - // Send an open FD to another process. + /// Recv an open FD from another process. int recv_handle (ACE_HANDLE &handles, char *pbuf = 0, int *len = 0) const; - // Recv an open FD from another process. #endif /* ACE_HAS_MSG */ + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Ensure that ACE_LSOCK is an abstract base class + /// Default constructor. ACE_LSOCK (void); - // Default constructor. + /// Initialize based on <handle> ACE_LSOCK (ACE_HANDLE handle); - // Initialize based on <handle> + /// Get handle. ACE_HANDLE get_handle (void) const; - // Get handle. + /// Set handle. void set_handle (ACE_HANDLE handle); - // Set handle. private: + /// An auxiliary handle used to avoid virtual base classes... ACE_HANDLE aux_handle_; - // An auxiliary handle used to avoid virtual base classes... }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/LSOCK_Acceptor.h b/ace/LSOCK_Acceptor.h index 873cf98ec30..d205b37114c 100644 --- a/ace/LSOCK_Acceptor.h +++ b/ace/LSOCK_Acceptor.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// LSOCK_Aceeptor.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file LSOCK_Aceeptor.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_LOCAL_SOCK_ACCEPTOR_H #define ACE_LOCAL_SOCK_ACCEPTOR_H @@ -32,57 +29,60 @@ // Forward decl. class ACE_Reactor; +/** + * @class ACE_LSOCK_Acceptor + * + * @brief Defines the format and interface for the acceptor side of the + * local ACE_SOCK ACE_Stream. + */ class ACE_Export ACE_LSOCK_Acceptor : public ACE_SOCK_Acceptor { - // = TITLE - // Defines the format and interface for the acceptor side of the - // local ACE_SOCK ACE_Stream. public: // = Initialization methods. + /// Default constructor. ACE_LSOCK_Acceptor (void); - // Default constructor. + /// Initiate a passive mode socket. ACE_LSOCK_Acceptor (const ACE_Addr &local_sap, int reuse_addr = 0, int protocol_family = PF_UNIX, int backlog = ACE_DEFAULT_BACKLOG, int protocol = 0); - // Initiate a passive mode socket. + /// Initiate a passive mode socket. int open (const ACE_Addr &local_sap, int reuse_addr = 0, int protocol_family = PF_UNIX, int backlog = ACE_DEFAULT_BACKLOG, int protocol = 0); - // Initiate a passive mode socket. + /// Accept a new data transfer connection. int accept (ACE_LSOCK_Stream &new_ipc_sap, ACE_Addr * = 0, ACE_Time_Value *timeout = 0, int restart = 1, int reset_new_handle = 0) const; - // Accept a new data transfer connection. + /// Close down the ACE_LSOCK and remove the rendezvous point from the + /// file system. int remove (void); - // Close down the ACE_LSOCK and remove the rendezvous point from the - // file system. + /// Return the local endpoint address. int get_local_addr (ACE_Addr &) const; - // Return the local endpoint address. // = Meta-type info typedef ACE_UNIX_Addr PEER_ADDR; typedef ACE_LSOCK_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Address of our rendezvous point. ACE_UNIX_Addr local_addr_; - // Address of our rendezvous point. }; #endif /* ACE_LACKS_UNIX_DOMAIN_SOCKETS */ diff --git a/ace/LSOCK_CODgram.h b/ace/LSOCK_CODgram.h index 919d3f26c05..f9bbf138654 100644 --- a/ace/LSOCK_CODgram.h +++ b/ace/LSOCK_CODgram.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// LSOCK_CODgram.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file LSOCK_CODgram.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_LOCAL_SOCK_CODGRAM_H #define ACE_LOCAL_SOCK_CODGRAM_H @@ -29,39 +26,42 @@ #if !defined (ACE_LACKS_UNIX_DOMAIN_SOCKETS) +/** + * @class ACE_LSOCK_CODgram + * + * @brief Defines the member functions for the <ACE_LSOCK> connected + * datagram abstraction. + */ class ACE_Export ACE_LSOCK_CODgram : public ACE_SOCK_CODgram, public ACE_LSOCK { - // = TITLE - // Defines the member functions for the <ACE_LSOCK> connected - // datagram abstraction. public: // = Initialization methods. + /// Default constructor. ACE_LSOCK_CODgram (void); - // Default constructor. + /// Initiate a connected-datagram. ACE_LSOCK_CODgram (const ACE_Addr &remote_sap, const ACE_Addr &local_sap = ACE_Addr::sap_any, int protocol_family = PF_UNIX, int protocol = 0); - // Initiate a connected-datagram. + /// Initiate a connected-datagram. int open (const ACE_Addr &remote_sap, const ACE_Addr &local_sap = ACE_Addr::sap_any, int protocol_family = PF_UNIX, int protocol = 0); - // Initiate a connected-datagram. + /// Get underlying handle. ACE_HANDLE get_handle (void) const; - // Get underlying handle. + /// Set underlying handle. void set_handle (ACE_HANDLE); - // Set underlying handle. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/LSOCK_Connector.h b/ace/LSOCK_Connector.h index a7f2f6bceb7..aabd9c46f97 100644 --- a/ace/LSOCK_Connector.h +++ b/ace/LSOCK_Connector.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// LSOCK_Connector.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ +//============================================================================= +/** + * @file LSOCK_Connector.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_LOCAL_SOCK_CONNECTOR_H #define ACE_LOCAL_SOCK_CONNECTOR_H @@ -29,16 +26,34 @@ #if !defined (ACE_LACKS_UNIX_DOMAIN_SOCKETS) +/** + * @class ACE_LSOCK_Connector + * + * @brief Defines the format and interface for the connector side of + * the <ACE_LSOCK_Stream>. + */ class ACE_Export ACE_LSOCK_Connector : public ACE_SOCK_Connector { - // = TITLE - // Defines the format and interface for the connector side of - // the <ACE_LSOCK_Stream>. public: // = Initialization methods. + /// Default constructor. ACE_LSOCK_Connector (void); - // Default constructor. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + */ ACE_LSOCK_Connector (ACE_LSOCK_Stream &new_stream, const ACE_UNIX_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -48,20 +63,22 @@ public: int perms = 0, int protocol_family = PF_UNIX, int protocol = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + */ int connect (ACE_LSOCK_Stream &new_stream, const ACE_UNIX_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -71,29 +88,16 @@ public: int perms = 0, int protcol_family = PF_UNIX, int protocol = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. // = Meta-type info typedef ACE_UNIX_Addr PEER_ADDR; typedef ACE_LSOCK_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/LSOCK_Dgram.h b/ace/LSOCK_Dgram.h index 723cc924430..0bc90cf3008 100644 --- a/ace/LSOCK_Dgram.h +++ b/ace/LSOCK_Dgram.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// LSOCK_Dgram.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + + +//============================================================================= +/** + * @file LSOCK_Dgram.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_LOCAL_SOCK_DGRAM_H #define ACE_LOCAL_SOCK_DGRAM_H @@ -29,36 +26,39 @@ #if !defined (ACE_LACKS_UNIX_DOMAIN_SOCKETS) +/** + * @class ACE_LSOCK_Dgram + * + * @brief Create a Local ACE_SOCK datagram. + */ class ACE_Export ACE_LSOCK_Dgram : public ACE_SOCK_Dgram, public ACE_LSOCK { - // = TITLE - // Create a Local ACE_SOCK datagram. public: // = Initialization methods. + /// Default constructor. ACE_LSOCK_Dgram (void); - // Default constructor. + /// Initiate a local dgram. ACE_LSOCK_Dgram (const ACE_Addr &local, int protocol_family = PF_UNIX, int protocol = 0); - // Initiate a local dgram. + /// Initiate a local dgram. int open (const ACE_Addr &local, int protocol_family = PF_UNIX, int protocol = 0); - // Initiate a local dgram. + /// Get handle. ACE_HANDLE get_handle (void) const; - // Get handle. + /// Set handle. void set_handle (ACE_HANDLE); - // Set handle. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/LSOCK_Stream.h b/ace/LSOCK_Stream.h index 1784193d204..51382e2f5dd 100644 --- a/ace/LSOCK_Stream.h +++ b/ace/LSOCK_Stream.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// LSOCK_Stream.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file LSOCK_Stream.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_LOCAL_SOCK_STREAM_H #define ACE_LOCAL_SOCK_STREAM_H @@ -29,43 +26,46 @@ #if !defined (ACE_LACKS_UNIX_DOMAIN_SOCKETS) +/** + * @class ACE_LSOCK_Stream + * + * @brief Create a Local ACE_SOCK stream. + */ class ACE_Export ACE_LSOCK_Stream : public ACE_SOCK_Stream, public ACE_LSOCK { - // = TITLE - // Create a Local ACE_SOCK stream. public: // = Send/recv methods. + /// Send iovecs via <::writev>. ssize_t send_msg (const iovec iov[], size_t n, ACE_HANDLE handle); - // Send iovecs via <::writev>. + /// Send iovecs via <::writev>. ssize_t recv_msg (iovec iov[], size_t n, ACE_HANDLE &handle); - // Send iovecs via <::writev>. + /// Get handle. ACE_HANDLE get_handle (void) const; - // Get handle. + /// Overrides set_handle from the base classes. void set_handle (ACE_HANDLE fd); - // Overrides set_handle from the base classes. // = Meta-type info typedef ACE_UNIX_Addr PEER_ADDR; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /// This method simply returns the "local" addr. int get_local_addr (ACE_Addr &) const; - // This method simply returns the "local" addr. + /// This method returns the "local" addr since it's the same value + /// for UNIX domain sockets. int get_remote_addr (ACE_Addr &) const; - // This method returns the "local" addr since it's the same value - // for UNIX domain sockets. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/Lib_Find.h b/ace/Lib_Find.h index 5466fbdf955..d2f275b122a 100644 --- a/ace/Lib_Find.h +++ b/ace/Lib_Find.h @@ -1,4 +1,14 @@ -// $Id$ + +//============================================================================= +/** + * @file Lib_Find.h + * + * $Id$ + * + * @author Priyanka Gontla <pgontla@ece.uci.edu> + */ +//============================================================================= + #ifndef ACE_LIB_FIND_H #define ACE_LIB_FINE_H @@ -6,72 +16,85 @@ #include "ace/OS.h" +/** + * @class ACE_Lib_Find + * + * This class includes all the static function calls needed to search + * and open shared libraries. + */ class ACE_Export ACE_Lib_Find { - // Description: This class includes all the static function calls - // needed to search and open shared libraries. - public: // = Methods for searching and opening shared libraries. + /** + * Finds the file <filename> either using an absolute path or using + * a relative path in conjunction with ACE_LD_SEARCH_PATH (e.g., + * $LD_LIBRARY_PATH on UNIX or $PATH on Win32). This function will + * add appropriate suffix (e.g., .dll on Win32 or .so on UNIX) + * according to the OS platform. In addition, this function will + * apply the appropriate prefix (e.g., "lib" on UNIX and "" on + * Win32) if the <filename> doesn't match directly. + */ static int ldfind (const ACE_TCHAR *filename, ACE_TCHAR *pathname, size_t maxlen); - // Finds the file <filename> either using an absolute path or using - // a relative path in conjunction with ACE_LD_SEARCH_PATH (e.g., - // $LD_LIBRARY_PATH on UNIX or $PATH on Win32). This function will - // add appropriate suffix (e.g., .dll on Win32 or .so on UNIX) - // according to the OS platform. In addition, this function will - // apply the appropriate prefix (e.g., "lib" on UNIX and "" on - // Win32) if the <filename> doesn't match directly. + /** + * Uses <ldopen> to locate and open the appropriate <filename> and + * returns a pointer to the file, else it returns a NULL + * pointer. <type> specifies how the file should be open. + */ static FILE *ldopen (const ACE_TCHAR *filename, const ACE_TCHAR *type); - // Uses <ldopen> to locate and open the appropriate <filename> and - // returns a pointer to the file, else it returns a NULL - // pointer. <type> specifies how the file should be open. + /** + * Transforms <entry_point> into a form that can be located in a + * dynamic library using <dlsym>. For example, with Win32/Borland + * extern "C" functions which use the default calling convention + * have a '_' prepended. Always returns a buffer that has been + * dynamically allocated using <operator new>. + */ static ACE_TCHAR *ldname (const ACE_TCHAR *entry_point); - // Transforms <entry_point> into a form that can be located in a - // dynamic library using <dlsym>. For example, with Win32/Borland - // extern "C" functions which use the default calling convention - // have a '_' prepended. Always returns a buffer that has been - // dynamically allocated using <operator new>. + /** + * Returns the temporary directory including the trailing slash in + * <buffer>. Returns -1 for an error or if the buffer_len is not + * long enough. + */ static int get_temp_dir (ACE_TCHAR *buffer, size_t buffer_len); - // Returns the temporary directory including the trailing slash in - // <buffer>. Returns -1 for an error or if the buffer_len is not - // long enough. + /// Opening the temp file. File is automagically unlinked when it is + /// closed. This is useful for have temp files. static ACE_HANDLE open_temp_file (const ACE_TCHAR *name, int mode, int perm = 0); - // Opening the temp file. File is automagically unlinked when it is - // closed. This is useful for have temp files. // @@ Though the following functions dont come under the same category as // above, these are used only in the functions in this class. So it makes // more sense to move these functions too to this class. // + /// Replace all instances of <search> in <s> with <replace>. Returns + /// the number of replacements made. static size_t strrepl (char *s, char search, char replace); - // Replace all instances of <search> in <s> with <replace>. Returns - // the number of replacements made. + /** + * Splits string <s> into pieces separated by the string <token>. + * <next_start> is an opaque cookie handed back by the call to store + * its state for the next invocation, thus making it re-entrant. + * This operates very similar to Perl's <split> function except that + * it returns pieces one at a time instead of into an array. + */ static char *strsplit_r (char *s, const char *token, char *&next_start); - // Splits string <s> into pieces separated by the string <token>. - // <next_start> is an opaque cookie handed back by the call to store - // its state for the next invocation, thus making it re-entrant. - // This operates very similar to Perl's <split> function except that - // it returns pieces one at a time instead of into an array. #if defined (ACE_HAS_WCHAR) + /// As strrepl, but for wide characters. static size_t strrepl (wchar_t *s, wchar_t search, wchar_t replace); - // As strrepl, but for wide characters. + /// As strsplit_r, but for wide characters. static wchar_t *strsplit_r (wchar_t *s, const wchar_t *token, wchar_t *&next_start); - // As strsplit_r, but for wide characters. #endif /* ACE_HAS_WCHAR */ }; diff --git a/ace/Local_Name_Space.h b/ace/Local_Name_Space.h index edf83a69771..ae847f15644 100644 --- a/ace/Local_Name_Space.h +++ b/ace/Local_Name_Space.h @@ -1,20 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Local_Name_Space.h -// -// = AUTHOR -// Prashant Jain (pjain@cs.wustl.edu), Irfan Pyarali -// (irfan@wuerl.wustl.edu), and Douglas C. Schmidt -// (schmidt@cs.wustl.edu). -// -// ============================================================================ + +//============================================================================= +/** + * @file Local_Name_Space.h + * + * $Id$ + * + * @author Prashant Jain (pjain@cs.wustl.edu) + * @author Irfan Pyarali (irfan@wuerl.wustl.edu) + * @author and Douglas C. Schmidt (schmidt@cs.wustl.edu). + */ +//============================================================================= + #ifndef ACE_LOCAL_NAME_SPACE_H #define ACE_LOCAL_NAME_SPACE_H @@ -30,89 +27,94 @@ #include "ace/Malloc_T.h" #include "ace/Synch.h" +/** + * @class ACE_NS_String + * + * @brief This class and ACE_NS_Internal are used as Adapters to work + * with the Map_Manager. + * + * In order to work correctly, this class must be able to + * convert back and forth with <ACE_WStrings>. Note that this + * class must not have a destructor since otherwise we'll have + * problems... + */ class ACE_Export ACE_NS_String { - // = TITLE - // This class and ACE_NS_Internal are used as Adapters to work - // with the Map_Manager. - // - // = DESCRIPTION - // In order to work correctly, this class must be able to - // convert back and forth with <ACE_WStrings>. Note that this - // class must not have a destructor since otherwise we'll have - // problems... public: // = Initialization. + /// Default "no-op" constructor. ACE_NS_String (void); - // Default "no-op" constructor. + /// Initialization method. ACE_NS_String (ACE_USHORT16 *dst, const ACE_USHORT16 *src, size_t len); - // Initialization method. + /// Converts an ACE_WString to an ACE_NS_String; ACE_NS_String (const ACE_WString &); - // Converts an ACE_WString to an ACE_NS_String; + /// Converts an ACE_NS_String to fresh copy of an ACE_WString; operator ACE_WString () const; - // Converts an ACE_NS_String to fresh copy of an ACE_WString; + /// Return the ASCII character representation. char *char_rep (void) const; - // Return the ASCII character representation. + /// Matches on substrings. int strstr (const ACE_NS_String &) const; - // Matches on substrings. + /// Compare an ACE_NS_String. int operator == (const ACE_NS_String &) const; - // Compare an ACE_NS_String. + /// Compare an ACE_NS_String. int operator != (const ACE_NS_String &) const; - // Compare an ACE_NS_String. + /// Returns length of the string size_t len (void) const; - // Returns length of the string + /// Returns the underlying representation. ACE_USHORT16 *fast_rep (void) const; - // Returns the underlying representation. + /// Returns a hash value for this string. size_t hash (void) const; - // Returns a hash value for this string. private: + /// Length of the string. size_t len_; - // Length of the string. + /// This actually points into shared/persistent memory. ACE_USHORT16 *rep_; - // This actually points into shared/persistent memory. }; +/** + * @class ACE_NS_Internal + * + * @brief This class and ACE_NS_String are used as Adapters to work + * with the Map_Manager. + */ class ACE_Export ACE_NS_Internal { - // = TITLE - // This class and ACE_NS_String are used as Adapters to work - // with the Map_Manager. public: + /// No-op constructor. ACE_NS_Internal (void); - // No-op constructor. + /// Constructor. ACE_NS_Internal (ACE_NS_String &value, const char *type); - // Constructor. + /// Compare an ACE_NS_Internal int operator == (const ACE_NS_Internal &) const; - // Compare an ACE_NS_Internal + /// Return value. ACE_NS_String value (void); - // Return value. + /// Return type. const char *type (void); - // Return type. private: + /// Contains the value of the string. ACE_NS_String value_; - // Contains the value of the string. + /// Contains the type of the string. const char *type_; - // Contains the type of the string. }; // Include the ACE_Local_Name_Space templates stuff at this point. diff --git a/ace/Local_Name_Space_T.h b/ace/Local_Name_Space_T.h index 5fce9307b7a..49360538e1c 100644 --- a/ace/Local_Name_Space_T.h +++ b/ace/Local_Name_Space_T.h @@ -1,20 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Local_Name_Space_T.h -// -// = AUTHOR -// Prashant Jain (pjain@cs.wustl.edu), Irfan Pyarali -// (irfan@wuerl.wustl.edu), and Douglas C. Schmidt -// (schmidt@cs.wustl.edu). -// -// ============================================================================ + +//============================================================================= +/** + * @file Local_Name_Space_T.h + * + * $Id$ + * + * @author Prashant Jain (pjain@cs.wustl.edu) + * @author Irfan Pyarali (irfan@wuerl.wustl.edu) + * @author and Douglas C. Schmidt (schmidt@cs.wustl.edu). + */ +//============================================================================= + #ifndef ACE_LOCAL_NAME_SPACE_T_H #define ACE_LOCAL_NAME_SPACE_T_H @@ -47,23 +44,25 @@ typedef ACE_Map_Iterator<ACE_NS_String, ACE_NS_Internal, ACE_Null_Mutex> MAP_ITE typedef ACE_Map_Entry <ACE_NS_String, ACE_NS_Internal> MAP_ENTRY; #endif /* 0 */ +/** + * @class ACE_Name_Space_Map + * + * @brief This class serves as a Proxy that ensures our process always + * has the appropriate allocator in place for every operation + * that accesses or updates the Map Manager. + * + * We need this class because otherwise the ALLOCATOR + * pointer will be stored in the Map_Manager that resides within + * shared memory. Naturally, this will cause horrible problems + * since only the first process to set that pointer will be + * guaranteed the address of the ALLOCATOR is meaningful! + */ template <class ALLOCATOR> class ACE_Name_Space_Map : public MAP_MANAGER { - // = TITLE - // This class serves as a Proxy that ensures our process always - // has the appropriate allocator in place for every operation - // that accesses or updates the Map Manager. - // - // = DESCRIPTION - // We need this class because otherwise the ALLOCATOR - // pointer will be stored in the Map_Manager that resides within - // shared memory. Naturally, this will cause horrible problems - // since only the first process to set that pointer will be - // guaranteed the address of the ALLOCATOR is meaningful! public: + /// Constructor. ACE_Name_Space_Map (ALLOCATOR *alloc); - // Constructor. // = The following methods are Proxies to the underlying methods // provided by <ACE_Hash_Map_Manager>. When they are called, they @@ -90,114 +89,128 @@ public: int close (ALLOCATOR *alloc); }; +/** + * @class ACE_Local_Name_Space + * + * @brief Maintaining accesses Local Name Server Database. Allows to + * add NameBindings, change them, remove them and resolve + * NameBindings. + * + * Manages a Naming Service for a local name space which + * includes bindings for node_local and host_local naming + * contexts. All strings are stored in wide character format. + * A Name Binding consists of a name (that's the key), a value + * string and an optional type string (no wide chars). + */ template <ACE_MEM_POOL_1, class ACE_LOCK> class ACE_Local_Name_Space : public ACE_Name_Space { - // = TITLE - // Maintaining accesses Local Name Server Database. Allows to - // add NameBindings, change them, remove them and resolve - // NameBindings. - // - // = DESCRIPTION - // Manages a Naming Service for a local name space which - // includes bindings for node_local and host_local naming - // contexts. All strings are stored in wide character format. - // A Name Binding consists of a name (that's the key), a value - // string and an optional type string (no wide chars). public: // = Initialization and termination methods. + /// "Do-nothing" constructor. ACE_Local_Name_Space (void); - // "Do-nothing" constructor. + /** + * Specifies the scope of this namespace, opens and memory-maps the + * associated file (if accessible) or contacts the dedicated name + * server process for NET_LOCAL namespace. + */ ACE_Local_Name_Space (ACE_Naming_Context::Context_Scope_Type scope_in, ACE_Name_Options *name_options); - // Specifies the scope of this namespace, opens and memory-maps the - // associated file (if accessible) or contacts the dedicated name - // server process for NET_LOCAL namespace. + /** + * Specifies the scope of this namespace, opens and memory-maps the + * associated file (if accessible) or contacts the dedicated name + * server process for NET_LOCAL namespace. + */ int open (ACE_Naming_Context::Context_Scope_Type scope_in); - // Specifies the scope of this namespace, opens and memory-maps the - // associated file (if accessible) or contacts the dedicated name - // server process for NET_LOCAL namespace. + /// destructor, do some cleanup :TBD: last dtor should "compress" + /// file ~ACE_Local_Name_Space (void); - // destructor, do some cleanup :TBD: last dtor should "compress" - // file + /// Bind a new name to a naming context (Wide character strings). virtual int bind (const ACE_WString &name, const ACE_WString &value, const char *type = ""); - // Bind a new name to a naming context (Wide character strings). + /** + * Overwrite the value or type of an existing name in a + * ACE_Local_Name_Space or bind a new name to the context, if it + * didn't exist yet. (Wide charcter strings interface). + */ virtual int rebind (const ACE_WString &name, const ACE_WString &value, const char *type = ""); - // Overwrite the value or type of an existing name in a - // ACE_Local_Name_Space or bind a new name to the context, if it - // didn't exist yet. (Wide charcter strings interface). + /// Delete a name from a ACE_Local_Name_Space (Wide charcter strings + /// Interface). virtual int unbind (const ACE_WString &name); virtual int unbind_i (const ACE_WString &name); - // Delete a name from a ACE_Local_Name_Space (Wide charcter strings - // Interface). + /// Get value and type of a given name binding (Wide chars). The + /// caller is responsible for deleting <type>! virtual int resolve (const ACE_WString &name, ACE_WString &value, char *&type); virtual int resolve_i (const ACE_WString &name, ACE_WString &value, char *&type); - // Get value and type of a given name binding (Wide chars). The - // caller is responsible for deleting <type>! + /// Get a set of names matching a specified pattern (wchars). Matching + /// means the names must begin with the pattern string. virtual int list_names (ACE_WSTRING_SET &set, const ACE_WString &pattern); virtual int list_names_i (ACE_WSTRING_SET &set, const ACE_WString &pattern); - // Get a set of names matching a specified pattern (wchars). Matching - // means the names must begin with the pattern string. + /// Get a set of values matching a specified pattern (wchars). Matching + /// means the values must begin with the pattern string. virtual int list_values (ACE_WSTRING_SET &set, const ACE_WString &pattern); virtual int list_values_i (ACE_WSTRING_SET &set, const ACE_WString &pattern); - // Get a set of values matching a specified pattern (wchars). Matching - // means the values must begin with the pattern string. + /// Get a set of types matching a specified pattern (wchars). Matching + /// means the types must begin with the pattern string. virtual int list_types (ACE_WSTRING_SET &set, const ACE_WString &pattern); virtual int list_types_i (ACE_WSTRING_SET &set, const ACE_WString &pattern); - // Get a set of types matching a specified pattern (wchars). Matching - // means the types must begin with the pattern string. + /** + * Get a set of names matching a specified pattern (wchars). Matching + * means the names must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_name_entries (ACE_BINDING_SET &set, const ACE_WString &pattern); virtual int list_name_entries_i (ACE_BINDING_SET &set, const ACE_WString &pattern); - // Get a set of names matching a specified pattern (wchars). Matching - // means the names must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of values matching a specified pattern (wchars). Matching + * means the values must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_value_entries (ACE_BINDING_SET &set, const ACE_WString &pattern); virtual int list_value_entries_i (ACE_BINDING_SET &set, const ACE_WString &pattern); - // Get a set of values matching a specified pattern (wchars). Matching - // means the values must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of types matching a specified pattern (wchars). Matching + * means the types must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_type_entries (ACE_BINDING_SET &set, const ACE_WString &pattern); virtual int list_type_entries_i (ACE_BINDING_SET &set, const ACE_WString &pattern); - // Get a set of types matching a specified pattern (wchars). Matching - // means the types must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /// Dump the state of the object virtual void dump (void) const; virtual void dump_i (void) const; - // Dump the state of the object // = I just know this is going to cause problems on some platform... typedef ACE_Allocator_Adapter <ACE_Malloc <ACE_MEM_POOL_2, ACE_LOCK> > @@ -205,41 +218,41 @@ public: private: #if defined (ACE_WIN32) + /// Remap the backing store int remap (EXCEPTION_POINTERS *ep); - // Remap the backing store #endif /* ACE_WIN32 */ + /// Factor out code from <bind> and <rebind>. int shared_bind (const ACE_WString &name, const ACE_WString &value, const char *type, int rebind); int shared_bind_i (const ACE_WString &name, const ACE_WString &value, const char *type, int rebind); - // Factor out code from <bind> and <rebind>. + /// Allocate the appropriate type of map manager that stores the + /// key/value binding. int create_manager (void); int create_manager_i (void); - // Allocate the appropriate type of map manager that stores the - // key/value binding. + /// Pointer to the allocator ALLOCATOR *allocator_; - // Pointer to the allocator + /// Pointer to the allocated map manager. ACE_Name_Space_Map <ALLOCATOR> *name_space_map_; - // Pointer to the allocated map manager. + /// Scope of this naming context (e.g., PROC_LOCAL, NODE_LOCAL, or + /// NET_LOCAL). ACE_Naming_Context::Context_Scope_Type ns_scope_; - // Scope of this naming context (e.g., PROC_LOCAL, NODE_LOCAL, or - // NET_LOCAL). + /// Keep track of the options such as database name etc ACE_Name_Options *name_options_; - // Keep track of the options such as database name etc + /// Name of the file used as the backing store. ACE_TCHAR context_file_[MAXPATHLEN + MAXNAMELEN]; - // Name of the file used as the backing store. + /// Synchronization variable. ACE_LOCK *lock_; - // Synchronization variable. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/Local_Tokens.h b/ace/Local_Tokens.h index f06215cca67..b11d03f06f1 100644 --- a/ace/Local_Tokens.h +++ b/ace/Local_Tokens.h @@ -1,48 +1,46 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Local_Tokens.h -// -// = AUTHOR -// Karl-Heinz Dorn <kdorn@erlh.siemens.de>, -// Douglas C. Schmidt <schmidt@cs.wustl.edu>, and -// Tim Harrison <harrison@cs.wustl.edu> -// -// = DESCRIPTION -// This file contains definitions for the following classes: -// -// public: -// 7. ACE_Token_Proxy -// 8. ACE_Null_Token : public ACE_Token_Proxy -// 9. ACE_Local_Mutex : public ACE_Token_Proxy -// *. ACE_Local_RLock : public ACE_Local_Mutex -// &. ACE_Local_WLock : public ACE_Local_Mutex -// private: -// 1. ACE_TOKEN_CONST -// 3. ACE_TPQ_Entry -// b. ACE_TSS_TPQ_Entry -// c. ACE_TPQ_Iterator -// 4. ACE_Token_Proxy_Queue -// 5. ACE_Tokens -// 6. ACE_Mutex_Token : public ACE_Tokens -// 12. ACE_RW_Token : public ACE_Tokens -// a. ACE_Token_Name -// -// Note that the locking classes defined in this file are *not* -// intended to be used as general-purpose synchronization -// mechanisms, such as mutexes or semaphores. Instead, you should -// use the <ACE_Recursive_Thread_Mutex>, <ACE_Thread_Mutex>, -// <ACE_Thread_Semaphore>, etc., that are defined in -// $ACE_ROOT/ace/Synch.h and $ACE_ROOT/ace/Synch_T.h or the -// <ACE_Token> that's defined in $ACE_ROOT/ace/Token.h. -// -// ============================================================================ + +//============================================================================= +/** + * @file Local_Tokens.h + * + * $Id$ + * + * @author Karl-Heinz Dorn <kdorn@erlh.siemens.de> + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + * @author and Tim Harrison <harrison@cs.wustl.edu> + * + * This file contains definitions for the following classes: + * + * public: + * 7. ACE_Token_Proxy + * 8. ACE_Null_Token : public ACE_Token_Proxy + * 9. ACE_Local_Mutex : public ACE_Token_Proxy + * *. ACE_Local_RLock : public ACE_Local_Mutex + * &. ACE_Local_WLock : public ACE_Local_Mutex + * private: + * 1. ACE_TOKEN_CONST + * 3. ACE_TPQ_Entry + * b. ACE_TSS_TPQ_Entry + * c. ACE_TPQ_Iterator + * 4. ACE_Token_Proxy_Queue + * 5. ACE_Tokens + * 6. ACE_Mutex_Token : public ACE_Tokens + * 12. ACE_RW_Token : public ACE_Tokens + * a. ACE_Token_Name + * + * Note that the locking classes defined in this file are *not* + * intended to be used as general-purpose synchronization + * mechanisms, such as mutexes or semaphores. Instead, you should + * use the <ACE_Recursive_Thread_Mutex>, <ACE_Thread_Mutex>, + * <ACE_Thread_Semaphore>, etc., that are defined in + * $ACE_ROOT/ace/Synch.h and $ACE_ROOT/ace/Synch_T.h or the + * <ACE_Token> that's defined in $ACE_ROOT/ace/Token.h. + * + * + */ +//============================================================================= + #ifndef ACE_LOCAL_MUTEX_H #define ACE_LOCAL_MUTEX_H @@ -64,15 +62,17 @@ #endif /* !(defined (ACE_HAS_THREADS) && defined (ACE_HAS_THREAD_SPECIFIC_STORAGE)) */ // 1. +/** + * @class ACE_TOKEN_CONST + * + * @brief Not a public interface. + * + * Constant definitions and typdefs for Token library. Mostly, + * this class is necessary to fight the compiler with order of + * declaration errors. + */ class ACE_Export ACE_TOKEN_CONST { - // = TITLE - // Not a public interface. - // - // = DESCRIPTION - // Constant definitions and typdefs for Token library. Mostly, - // this class is necessary to fight the compiler with order of - // declaration errors. public: #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) // ACE platform supports some form of threading. @@ -90,32 +90,34 @@ public: class ACE_Token_Proxy; // 3.. +/** + * @class ACE_TPQ_Entry + * + * @brief Token Proxy Queue entry. Used in the ACE_Token_Proxy_Queue + * + * Not a public interface. + */ class ACE_Export ACE_TPQ_Entry { - // = TITLE - // Token Proxy Queue entry. Used in the ACE_Token_Proxy_Queue - // - // = DESCRIPTION - // Not a public interface. friend class ACE_Token_Manager; public: typedef void (*PTVF) (void *); + /// Null constructor. ACE_TPQ_Entry (void); - // Null constructor. + /// Construction. ACE_TPQ_Entry (const ACE_Token_Proxy *proxy, const ACE_TCHAR *client_id); - // Construction. + /// Copy constructor. ACE_TPQ_Entry (const ACE_TPQ_Entry &rhs); - // Copy constructor. + /// Death. ~ACE_TPQ_Entry (void); - // Death. + /// Copy operator use by the queue. void operator= (const ACE_TPQ_Entry &rhs); - // Copy operator use by the queue. // = Set/get top of the queue. ACE_Token_Proxy *proxy (void) const; @@ -129,51 +131,51 @@ public: const ACE_TCHAR *client_id (void) const; void client_id (const ACE_TCHAR *); + /// Returns 1 if <id> == client id. Does not check for <id> == 0. int equal_client_id (const ACE_TCHAR *id); - // Returns 1 if <id> == client id. Does not check for <id> == 0. + /// One method for arg and sleep_hook. void set (void (*sleep_hook)(void *)); - // One method for arg and sleep_hook. // = Set/get sleep hook of the entry. void sleep_hook (void (*sh)(void *)); PTVF sleep_hook (void) const; + /// Call the sleep hook function or method passing arg. void call_sleep_hook (void); - // Call the sleep hook function or method passing arg. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. // = Used to block the thread if an acquire fails with EWOULDBLOCK. ACE_TOKEN_CONST::COND_VAR cond_var_; ACE_TOKEN_CONST::MUTEX lock_; + /// Pointer to next in list. ACE_TPQ_Entry *next_; - // Pointer to next in list. // = Get/set whether this client is blocked waiting for a token. int waiting (void) const; void waiting (int w); private: + /// This client is waiting for a token. int waiting_; - // This client is waiting for a token. + /// Proxy. ACE_Token_Proxy *proxy_; - // Proxy. + /// Nesting level. int nesting_level_; - // Nesting level. + /// Arg. void *arg_; - // Arg. + /// Client id. ACE_TCHAR client_id_[ACE_MAXCLIENTIDLEN]; - // Client id. + /// Sleep hook. void (*sleep_hook_)(void *); - // Sleep hook. }; // b.. @@ -183,30 +185,32 @@ typedef ACE_TPQ_Entry ACE_TPQ_ENTRY; typedef ACE_TSS<ACE_TPQ_Entry> ACE_TPQ_ENTRY; #endif /* ACE_NO_TSS_TOKENS */ +/** + * @class ACE_TSS_TPQ_Entry + * + * @brief ACE_TSS_TPQ_Entry + * + * Not a public interface. + */ class ACE_Export ACE_TSS_TPQ_Entry : public ACE_TPQ_ENTRY { - // = TITLE - // ACE_TSS_TPQ_Entry - // - // = DESCRIPTION - // Not a public interface. public: + /// These are passed to the constructor of ACE_TPQ_Entry in + /// make_TSS_TYPE ACE_TSS_TPQ_Entry (const ACE_Token_Proxy *proxy, const ACE_TCHAR *client_id); - // These are passed to the constructor of ACE_TPQ_Entry in - // make_TSS_TYPE + /// Destructor. virtual ~ACE_TSS_TPQ_Entry (void); - // Destructor. + /// Allows us to pass args to the construction of the TSS object. virtual ACE_TPQ_Entry *make_TSS_TYPE (void) const; - // Allows us to pass args to the construction of the TSS object. + /// Operator overloading and inheritence don't mix. operator ACE_TPQ_Entry *(void); - // Operator overloading and inheritence don't mix. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. #if defined (ACE_NO_TSS_TOKENS) ACE_TPQ_Entry *operator-> (void) @@ -216,507 +220,536 @@ public: #endif /* ACE_NO_TSS_TOKENS */ private: + /// Private: should not be used ACE_TSS_TPQ_Entry (const ACE_TSS_TPQ_Entry &); void operator= (const ACE_TSS_TPQ_Entry &); - // Private: should not be used // = These are passed to the constructor of ACE_TPQ_Entry in // make_TSS_TYPE + /// Proxy. + /// Client_id. const ACE_Token_Proxy *proxy_; - // Proxy. const ACE_TCHAR *client_id_; - // Client_id. }; class ACE_Token_Proxy_Queue; // c.. +/** + * @class ACE_TPQ_Iterator + * + * @brief Iterates through ACE_Token_Proxy_Queues. + * + * Not a public interface. + */ class ACE_Export ACE_TPQ_Iterator { - // = TITLE - // Iterates through ACE_Token_Proxy_Queues. - // - // = DESCRIPTION - // Not a public interface. public: + /// Construction. ACE_TPQ_Iterator (ACE_Token_Proxy_Queue &q); - // Construction. + /// Destructor. ~ACE_TPQ_Iterator (void); - // Destructor. + /// Pass back the <next_item>. int next (ACE_TPQ_Entry *&next_item); - // Pass back the <next_item>. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Move forward by one element in the queue. void advance (void); - // Move forward by one element in the queue. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. private: ACE_TPQ_Entry *current_; }; // 4.. +/** + * @class ACE_Token_Proxy_Queue + * + * @brief Token waiter list. + * + * Not a public interface. + * This queue holds all the token proxies waiting for ownership + * of a token. Along with the proxy reference, it also stores + * the nesting level, client id, and a magic cookie from the + * proxy. This queue stores the ACE_TPQ_Entries by pointer + * values. It DOES NOT make copies. Thus, the user is + * responsible to ensure that the TPQ's stick around. This is + * motivated by the need to reduce dynamic memory allocation. + */ class ACE_Export ACE_Token_Proxy_Queue { - // = TITLE - // Token waiter list. - // - // = DESCRIPTION - // Not a public interface. - // - // This queue holds all the token proxies waiting for ownership - // of a token. Along with the proxy reference, it also stores - // the nesting level, client id, and a magic cookie from the - // proxy. This queue stores the ACE_TPQ_Entries by pointer - // values. It DOES NOT make copies. Thus, the user is - // responsible to ensure that the TPQ's stick around. This is - // motivated by the need to reduce dynamic memory allocation. public: friend class ACE_TPQ_Iterator; + /// Construction. ACE_Token_Proxy_Queue (void); - // Construction. + /// Destructor ~ACE_Token_Proxy_Queue (void); - // Destructor + /** + * Enqueue a proxy, nesting level, client_id, and a magic cookie at + * the given position in the list. If the position is -1, we + * enqueue at the end of the list (I think). + */ void enqueue (ACE_TPQ_Entry* new_entry, int position); - // Enqueue a proxy, nesting level, client_id, and a magic cookie at - // the given position in the list. If the position is -1, we - // enqueue at the end of the list (I think). + /// Top of the queue. const ACE_TPQ_Entry* head (void); - // Top of the queue. // int member (const ACE_TCHAR *id); // Is this id in the waiter list? + /// Remove the top waiter. void dequeue (void); - // Remove the top waiter. + /// Remove the waiter whose proxy ref matches remove_me. void remove (const ACE_TPQ_Entry *remove_me); - // Remove the waiter whose proxy ref matches remove_me. + /// The number of waiters. int size (void); - // The number of waiters. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. protected: + /** + * Head. + * Tail. + * Size. + */ ACE_TPQ_Entry *head_; - // Head. ACE_TPQ_Entry *tail_; - // Tail. int size_; - // Size. }; // 5.. +/** + * @class ACE_Tokens + * + * @brief Abstract representation of ACE tokens. + * + * Not a public interface. + * Currently, I don't see a reason for providing an abstract + * interface at this level of the library. As of yet, no one + * uses <ACE_Tokens< derivatives through this abstract interface + * except for <ACE_Token_Manager>. It only uses the statistical + * methods which are shared by all Tokens. For that reason, it + * still makes since to have a common base class. However, + * acquire, renew, and release do not need to have matching + * interfaces throughout all Tokens. + * To add a new type of token (e.g. semaphore), this class must + * be subtyped to define the new semantics. See + * <ACE_Token_Manager> for details. + */ class ACE_Export ACE_Tokens { - // = TITLE - // Abstract representation of ACE tokens. - // - // = DESCRIPTION - // Not a public interface. - // - // Currently, I don't see a reason for providing an abstract - // interface at this level of the library. As of yet, no one - // uses <ACE_Tokens< derivatives through this abstract interface - // except for <ACE_Token_Manager>. It only uses the statistical - // methods which are shared by all Tokens. For that reason, it - // still makes since to have a common base class. However, - // acquire, renew, and release do not need to have matching - // interfaces throughout all Tokens. - // - // To add a new type of token (e.g. semaphore), this class must - // be subtyped to define the new semantics. See - // <ACE_Token_Manager> for details. public: + /// Null constructor. ACE_Tokens (void); - // Null constructor. + /// Destructor virtual ~ACE_Tokens (void); - // Destructor + /// No implementation. virtual int acquire (ACE_TPQ_Entry *caller, int ignore_deadlock, int notify) = 0; - // No implementation. + /// No implementation. virtual int tryacquire (ACE_TPQ_Entry *caller) = 0; - // No implementation. + /// No implementation. virtual int renew (ACE_TPQ_Entry *caller, int requeue_position) = 0; - // No implementation. + /// No implementation. virtual int release (ACE_TPQ_Entry *caller) = 0; - // No implementation. + /// Move the caller to the front of the waiter list. This is for use + /// with remote mutexes and shadow mutexes. void make_owner (ACE_TPQ_Entry *caller); - // Move the caller to the front of the waiter list. This is for use - // with remote mutexes and shadow mutexes. + /// Remove the caller from the waiter list. void remove (ACE_TPQ_Entry *caller); - // Remove the caller from the waiter list. // = Accessor methods. + /// Stack of owners. typedef ACE_Unbounded_Stack<ACE_TPQ_Entry *> OWNER_STACK; - // Stack of owners. + /// Returns a stack of the current owners. Returns -1 on error, 0 on + /// success. If <id> is non-zero, returns 1 if id is an owner. virtual int owners (OWNER_STACK &o, const ACE_TCHAR *id) = 0; - // Returns a stack of the current owners. Returns -1 on error, 0 on - // success. If <id> is non-zero, returns 1 if id is an owner. + /// Returns 1 if <id> is waiting for this token. 0 otherwise. virtual int is_waiting_for (const ACE_TCHAR *id) = 0; - // Returns 1 if <id> is waiting for this token. 0 otherwise. + /// Returns 1 if <id> is an owner of this token. 0 otherwise. virtual int is_owner (const ACE_TCHAR *id) = 0; - // Returns 1 if <id> is an owner of this token. 0 otherwise. + /// Return the queue of waiters. virtual ACE_Token_Proxy_Queue *waiters (void); - // Return the queue of waiters. + /// Return the number of proxies that are currently waiting to get + /// the token. virtual int no_of_waiters (void); - // Return the number of proxies that are currently waiting to get - // the token. + /// The current owner. const ACE_TCHAR *owner_id (void); - // The current owner. + /// Token name. const ACE_TCHAR* name (void); - // Token name. // = Reference counting. These are only called by the // Token_Manager. void inc_reference (void); int dec_reference (void); + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /** + * These are the Token types supported by the library at ship time. + * There is no restriction on the number of Token types added by + * "3rd parties." These are only necessary for the Token Server. + */ enum TOKEN_TYPES { MUTEX, RWLOCK }; - // These are the Token types supported by the library at ship time. - // There is no restriction on the number of Token types added by - // "3rd parties." These are only necessary for the Token Server. + /** + * Provides a manual RTTI mechanism. This method is used only by + * ACE_Token_Request so that the type of a token can be sent to a + * remote Token Server. + */ virtual int type (void) const = 0; - // Provides a manual RTTI mechanism. This method is used only by - // ACE_Token_Request so that the type of a token can be sent to a - // remote Token Server. // = The following methods allow the deadlock detection algorithm to // check if this token has been visited. + /// Mark or unmark the token as visited. void visit (int v); - // Mark or unmark the token as visited. + /// Check if the token has been visited. int visited (void); - // Check if the token has been visited. + /// All the data of the current owner. ACE_TPQ_Entry *owner (void); - // All the data of the current owner. protected: + /// For the deadlock detection algorithm. int visited_; - // For the deadlock detection algorithm. + /// Reference count. int reference_count_; - // Reference count. + /// List of client's owning and waiting the token. ACE_Token_Proxy_Queue waiters_; - // List of client's owning and waiting the token. + /// Name of token. ACE_TCHAR token_name_[ACE_MAXTOKENNAMELEN]; - // Name of token. }; class ACE_Local_Mutex; // 6.. +/** + * @class ACE_Mutex_Token + * + * @brief Class that acquires, renews, and releases a process-local + * synchronization token. + * + * Not a public interface. + * This class is a more general-purpose synchronization mechanism + * than SunOS 5.x mutexes. For example, it implements "recursive + * mutex" semantics, where a thread that owns the token can + * reacquire it without deadlocking. In addition, threads that + * are blocked awaiting the token are serviced in strict FIFO + * order as other threads release the token (SunOS 5.x mutexes + * don't strictly enforce an acquisition order). + */ class ACE_Export ACE_Mutex_Token : public ACE_Tokens { - // = TITLE - // Class that acquires, renews, and releases a process-local - // synchronization token. - // - // = DESCRIPTION - // Not a public interface. - // - // This class is a more general-purpose synchronization mechanism - // than SunOS 5.x mutexes. For example, it implements "recursive - // mutex" semantics, where a thread that owns the token can - // reacquire it without deadlocking. In addition, threads that - // are blocked awaiting the token are serviced in strict FIFO - // order as other threads release the token (SunOS 5.x mutexes - // don't strictly enforce an acquisition order). public: + /// life ACE_EXPLICIT ACE_Mutex_Token (const ACE_TCHAR* name); - // life + /// death virtual ~ACE_Mutex_Token (void); - // death // = Synchronization operations. // With acquire, renew, and release, the caller must be specified so // that multiple proxies (e.g. ACE_Local_Mutex) can use the same // token. + /** + * Returns 0 on success, -1 on failure with <ACE_Log_Msg::errnum> as + * the reason. If errnum == EWOULDBLOCK, and notify == 1, + * <ACE_Token_Proxy::sleep_hook> has been called on the current + * owner of the token. If ignore_deadlock is passed as 1 and errnum + * == EDEADLK, then deadlock was detected via ace_token_manager. + */ virtual int acquire (ACE_TPQ_Entry *caller, int ignore_deadlock, int notify); - // Returns 0 on success, -1 on failure with <ACE_Log_Msg::errnum> as - // the reason. If errnum == EWOULDBLOCK, and notify == 1, - // <ACE_Token_Proxy::sleep_hook> has been called on the current - // owner of the token. If ignore_deadlock is passed as 1 and errnum - // == EDEADLK, then deadlock was detected via ace_token_manager. + /// same as acquire, but fails if would block virtual int tryacquire (ACE_TPQ_Entry *caller); - // same as acquire, but fails if would block + /** + * An optimized method that efficiently reacquires the token if no + * other threads are waiting. This is useful for situations where + * you don't want to degrade the quality of service if there are + * other threads waiting to get the token. If <requeue_position> == + * -1 and there are other threads waiting to obtain the token we are + * queued at the end of the list of waiters. If <requeue_position> + * > -1 then it indicates how many entries to skip over before + * inserting our thread into the list of waiters (e.g., + * <requeue_position> == 0 means "insert at front of the queue"). + * Renew has the rather odd semantics such that if there are other + * waiting threads it will give up the token even if the + * nesting_level_ > 1. I'm not sure if this is really the right + * thing to do (since it makes it possible for shared data to be + * changed unexpectedly) so use with caution... Returns 0 on + * success, -1 on failure with <ACE_Log_Msg::errnum> as the reason. + * If errnum == EWOULDBLOCK, and notify == 1, + * <ACE_Token_Proxy::sleep_hook> has been called on the current + * owner of the token. + */ virtual int renew (ACE_TPQ_Entry *caller, int requeue_position); - // An optimized method that efficiently reacquires the token if no - // other threads are waiting. This is useful for situations where - // you don't want to degrade the quality of service if there are - // other threads waiting to get the token. If <requeue_position> == - // -1 and there are other threads waiting to obtain the token we are - // queued at the end of the list of waiters. If <requeue_position> - // > -1 then it indicates how many entries to skip over before - // inserting our thread into the list of waiters (e.g., - // <requeue_position> == 0 means "insert at front of the queue"). - // Renew has the rather odd semantics such that if there are other - // waiting threads it will give up the token even if the - // nesting_level_ > 1. I'm not sure if this is really the right - // thing to do (since it makes it possible for shared data to be - // changed unexpectedly) so use with caution... Returns 0 on - // success, -1 on failure with <ACE_Log_Msg::errnum> as the reason. - // If errnum == EWOULDBLOCK, and notify == 1, - // <ACE_Token_Proxy::sleep_hook> has been called on the current - // owner of the token. + /** + * Relinquish the token. If there are any waiters then the next one + * in line gets it. If the caller is not the owner, caller is + * removed from the waiter list. + */ virtual int release (ACE_TPQ_Entry *caller); - // Relinquish the token. If there are any waiters then the next one - // in line gets it. If the caller is not the owner, caller is - // removed from the waiter list. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// Returns ACE_Tokens::MUTEX. virtual int type (void) const; - // Returns ACE_Tokens::MUTEX. + /// Returns a stack of the current owners. Returns -1 on error, 0 on + /// success. If <id> is non-zero, returns 1 if id is an owner. virtual int owners (OWNER_STACK &o, const ACE_TCHAR *id); - // Returns a stack of the current owners. Returns -1 on error, 0 on - // success. If <id> is non-zero, returns 1 if id is an owner. + /// Returns 1 if <id> is waiting for this token. 0 otherwise. virtual int is_waiting_for (const ACE_TCHAR *id); - // Returns 1 if <id> is waiting for this token. 0 otherwise. + /// Returns 1 if <id> is an owner of this token. 0 otherwise. virtual int is_owner (const ACE_TCHAR *id); - // Returns 1 if <id> is an owner of this token. 0 otherwise. private: + /// ACE_Mutex_Token used to lock internal data structures. ACE_TOKEN_CONST::MUTEX lock_; - // ACE_Mutex_Token used to lock internal data structures. }; // 12.. +/** + * @class ACE_RW_Token + * + * @brief Class that acquires, renews, and releases a process-local + * synchronization token. + * + * Not a public interface. + * This class is a more general-purpose synchronization mechanism + * than SunOS 5.x mutexes. For example, it implements "recursive + * mutex" semantics, where a thread that owns the token can + * reacquire it without deadlocking. In addition, threads that are + * blocked awaiting the token are serviced in strict FIFO order as + * other threads release the token (SunOS 5.x mutexes don't strictly + * enforce an acquisition order). + */ class ACE_Export ACE_RW_Token : public ACE_Tokens { - // = TITLE - // Class that acquires, renews, and releases a process-local - // synchronization token. - // - // = DESCRIPTION - // Not a public interface. - // - // This class is a more general-purpose synchronization mechanism - // than SunOS 5.x mutexes. For example, it implements "recursive - // mutex" semantics, where a thread that owns the token can - // reacquire it without deadlocking. In addition, threads that are - // blocked awaiting the token are serviced in strict FIFO order as - // other threads release the token (SunOS 5.x mutexes don't strictly - // enforce an acquisition order). public: + /// Life. ACE_EXPLICIT ACE_RW_Token (const ACE_TCHAR* name); - // Life. + /// Death. virtual ~ACE_RW_Token (void); - // Death. // = Synchronization operations. // With acquire, renew, and release, the caller must be specified so // that multiple proxies (e.g. ACE_Local_Mutex) can use the same // token. + /** + * Returns 0 on success, -1 on failure with <ACE_Log_Msg::errnum> as + * the reason. If errnum == EWOULDBLOCK, and notify == 1, + * <ACE_Token_Proxy::sleep_hook> has been called on the current + * owner of the token. If ignore_deadlock is passed as 1 and errnum + * == EDEADLK, then deadlock was detected via ace_token_manager. + */ virtual int acquire (ACE_TPQ_Entry *caller, int ignore_deadlock, int notify); - // Returns 0 on success, -1 on failure with <ACE_Log_Msg::errnum> as - // the reason. If errnum == EWOULDBLOCK, and notify == 1, - // <ACE_Token_Proxy::sleep_hook> has been called on the current - // owner of the token. If ignore_deadlock is passed as 1 and errnum - // == EDEADLK, then deadlock was detected via ace_token_manager. + /// same as acquire except fails on would block virtual int tryacquire (ACE_TPQ_Entry *caller); - // same as acquire except fails on would block + /** + * An optimized method that efficiently reacquires the token if no + * other threads are waiting. This is useful for situations where + * you don't want to degrade the quality of service if there are + * other threads waiting to get the token. If <requeue_position> == + * -1 and there are other threads waiting to obtain the token we are + * queued at the end of the list of waiters. If <requeue_position> + * > -1 then it indicates how many entries to skip over before + * inserting our thread into the list of waiters (e.g., + * <requeue_position> == 0 means "insert at front of the queue"). + * Renew has the rather odd semantics such that if there are other + * waiting threads it will give up the token even if the + * nesting_level_ > 1. I'm not sure if this is really the right + * thing to do (since it makes it possible for shared data to be + * changed unexpectedly) so use with caution... Returns 0 on + * success, -1 on failure with <ACE_Log_Msg::errnum> as the reason. + * If errnum == EWOULDBLOCK, and notify == 1, + * <ACE_Token_Proxy::sleep_hook> has been called on the current + * owner of the token. + */ virtual int renew (ACE_TPQ_Entry *caller, int requeue_position); - // An optimized method that efficiently reacquires the token if no - // other threads are waiting. This is useful for situations where - // you don't want to degrade the quality of service if there are - // other threads waiting to get the token. If <requeue_position> == - // -1 and there are other threads waiting to obtain the token we are - // queued at the end of the list of waiters. If <requeue_position> - // > -1 then it indicates how many entries to skip over before - // inserting our thread into the list of waiters (e.g., - // <requeue_position> == 0 means "insert at front of the queue"). - // Renew has the rather odd semantics such that if there are other - // waiting threads it will give up the token even if the - // nesting_level_ > 1. I'm not sure if this is really the right - // thing to do (since it makes it possible for shared data to be - // changed unexpectedly) so use with caution... Returns 0 on - // success, -1 on failure with <ACE_Log_Msg::errnum> as the reason. - // If errnum == EWOULDBLOCK, and notify == 1, - // <ACE_Token_Proxy::sleep_hook> has been called on the current - // owner of the token. + /** + * Relinquish the token. If there are any waiters then the next one + * in line gets it. If the caller is not the owner, caller is + * removed from the waiter list. + */ virtual int release (ACE_TPQ_Entry *caller); - // Relinquish the token. If there are any waiters then the next one - // in line gets it. If the caller is not the owner, caller is - // removed from the waiter list. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// These are the types that proxies can be. enum PROXY_TYPE { READER, WRITER }; - // These are the types that proxies can be. + /// Returns READER or WRITER. virtual int type (void) const; - // Returns READER or WRITER. + /// Returns a stack of the current owners. Returns -1 on error, 0 on + /// success. If <id> is non-zero, returns 1 if id is an owner. virtual int owners (OWNER_STACK &o, const ACE_TCHAR *id); - // Returns a stack of the current owners. Returns -1 on error, 0 on - // success. If <id> is non-zero, returns 1 if id is an owner. + /// Returns 1 if <id> is waiting for this token. 0 otherwise. virtual int is_waiting_for (const ACE_TCHAR *id); - // Returns 1 if <id> is waiting for this token. 0 otherwise. + /// Returns 1 if <id> is an owner of this token. 0 otherwise. virtual int is_owner (const ACE_TCHAR *id); - // Returns 1 if <id> is an owner of this token. 0 otherwise. protected: + /// the number of waiting writers. int num_writers_; - // the number of waiting writers. + /// ACE_Mutex_Token used to lock internal data structures. ACE_TOKEN_CONST::MUTEX lock_; - // ACE_Mutex_Token used to lock internal data structures. + /// Sets the new owner. void notify_new_owner (ACE_TPQ_Entry *caller); - // Sets the new owner. }; // a.. +/** + * @class ACE_Token_Name + * + * @brief Allows Token_Manger to identify tokens. + * + * For now, this is just a string. We need a string class + * anyway to use in <ACE_Map_Manager>. Having this class + * (instead of <ACE_SString>) allows us to easily change if + * needed. For instance, we may choose to identify tokens by + * name and *type* in the future. + */ class ACE_Export ACE_Token_Name { - // = TITLE - // Allows Token_Manger to identify tokens. - // - // = DESCRIPTION - // For now, this is just a string. We need a string class - // anyway to use in <ACE_Map_Manager>. Having this class - // (instead of <ACE_SString>) allows us to easily change if - // needed. For instance, we may choose to identify tokens by - // name and *type* in the future. public: + /// Construction. ACE_Token_Name (const ACE_TCHAR *token_name = 0); - // Construction. + /// Copy construction. ACE_Token_Name (const ACE_Token_Name &rhs); - // Copy construction. + /// Death. virtual ~ACE_Token_Name (void); - // Death. + /// Copy. void operator= (const ACE_Token_Name &rhs); - // Copy. + /// Comparison. int operator== (const ACE_Token_Name &rhs) const; - // Comparison. + /// Token name. const ACE_TCHAR *name (void) const; - // Token name. + /// Token name. void name (const ACE_TCHAR *new_name); - // Token name. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. private: + /// Name of the token. ACE_TCHAR token_name_[ACE_MAXTOKENNAMELEN]; - // Name of the token. }; // 7.. +/** + * @class ACE_Token_Proxy + * + * @brief Abstract representation of ACE tokens. + * + * Interface for all Tokens in ACE. This class implements the + * synchronization needed for tokens (condition variables etc.) + * The algorithms for the operations (acquire, release, etc.) + * operate on the generic ACE_Tokens interface. Thus, the _type_ + * of token (mutex, rwlock) can be set at construction of + * ACE_Token_Proxy. You can use all Tokens in ACE through the + * ACE_Token_Proxy by passing the proper values at construction. + * Alternatively, there are class definitions which "know" how to + * do this (ACE_Local_Mutex, ACE_Local_RLock, ACE_Local_WLock). + * To add a new type of token (e.g. semaphore), this class is not + * changed. See ACE_Token_Manager for details. + * Tokens (e.g. ACE_Mutex_Token) assume that it can always call + * <ACE_Token_Proxy::token_acquired> on a new token owner. This + * is not a problem for synchronous use of token proxies (that is, + * when acquires block until successful.) However, for + * implementations of the Token Server, which may use asynch + * operations, the proxy can not go away after an acquire until + * the token is acquired. This is not really a problem, but + * should be understood. + */ class ACE_Export ACE_Token_Proxy { - // = TITLE - // Abstract representation of ACE tokens. - // - // = DESCRIPTION - // Interface for all Tokens in ACE. This class implements the - // synchronization needed for tokens (condition variables etc.) - // The algorithms for the operations (acquire, release, etc.) - // operate on the generic ACE_Tokens interface. Thus, the _type_ - // of token (mutex, rwlock) can be set at construction of - // ACE_Token_Proxy. You can use all Tokens in ACE through the - // ACE_Token_Proxy by passing the proper values at construction. - // Alternatively, there are class definitions which "know" how to - // do this (ACE_Local_Mutex, ACE_Local_RLock, ACE_Local_WLock). - // - // To add a new type of token (e.g. semaphore), this class is not - // changed. See ACE_Token_Manager for details. - // - // Tokens (e.g. ACE_Mutex_Token) assume that it can always call - // <ACE_Token_Proxy::token_acquired> on a new token owner. This - // is not a problem for synchronous use of token proxies (that is, - // when acquires block until successful.) However, for - // implementations of the Token Server, which may use asynch - // operations, the proxy can not go away after an acquire until - // the token is acquired. This is not really a problem, but - // should be understood. public: friend class ACE_Token_Manager; friend class ACE_Token_Invariant_Manager; // For testing. // Initialization and termination methods. + /// Construction. ACE_Token_Proxy (void); - // Construction. + /// Death. virtual ~ACE_Token_Proxy (void); - // Death. + /** + * <name> is the string uniquely identifying the token. + * <ignore_deadlock> can be 1 to disable deadlock notifications. + * <debug> prints debug messages. + */ virtual int open (const ACE_TCHAR *name, int ignore_deadlock = 0, int debug = 0); - // <name> is the string uniquely identifying the token. - // <ignore_deadlock> can be 1 to disable deadlock notifications. - // <debug> prints debug messages. // = The following methods have implementations which are // independent of the token semantics (mutex, rwlock, etc.) They @@ -725,314 +758,334 @@ public: // etc.) This allows reuse of the blocking code as well as having // multiple proxies to the same token. + /// Calls acquire on the token. Blocks the calling thread if would + /// block. virtual int acquire (int notify = 0, void (*sleep_hook)(void *) = 0, ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Calls acquire on the token. Blocks the calling thread if would - // block. + /// Calls renew on the token. Blocks the calling thread if would + /// block. virtual int renew (int requeue_position = -1, ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Calls renew on the token. Blocks the calling thread if would - // block. + /// Calls renew on the token. virtual int tryacquire (void (*sleep_hook)(void *) = 0); - // Calls renew on the token. + /// Calls release on the token. virtual int release (ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Calls release on the token. + /// Calls remove on the token. virtual int remove (ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Calls remove on the token. + /// Since the locking mechanism doesn't support read locks then this + /// just calls <acquire>. virtual int acquire_read (int notify = 0, void (*sleep_hook)(void *) = 0, ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Since the locking mechanism doesn't support read locks then this - // just calls <acquire>. + /// Since the locking mechanism doesn't support write locks then this + /// just calls <acquire>. virtual int acquire_write (int notify = 0, void (*sleep_hook)(void *) = 0, ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Since the locking mechanism doesn't support write locks then this - // just calls <acquire>. + /// Since the locking mechanism doesn't support read locks then this + /// just calls <tryacquire>. virtual int tryacquire_read (void (*sleep_hook)(void *) = 0); - // Since the locking mechanism doesn't support read locks then this - // just calls <tryacquire>. + /// Since the locking mechanism doesn't support write locks then this + /// just calls <tryacquire>. virtual int tryacquire_write (void (*sleep_hook)(void *) = 0); - // Since the locking mechanism doesn't support write locks then this - // just calls <tryacquire>. // = Utility methods. + /// Get the client id of the proxy. This is implemented as + /// thread-specific data. virtual const ACE_TCHAR *client_id (void) const; - // Get the client id of the proxy. This is implemented as - // thread-specific data. + /** + * Set the client_id for the calling thread. I strongly recommend + * that this not be used unless you really know what you're doing. + * I use this in the Token Server, and it caused many headaches. + */ virtual void client_id (const ACE_TCHAR *client_id); - // Set the client_id for the calling thread. I strongly recommend - // that this not be used unless you really know what you're doing. - // I use this in the Token Server, and it caused many headaches. + /** + * Return the name of the token. This is important for use within + * the token servers (local and remote) as well as with token + * collections. So, all derivations of ACE_Token_Proxy must be able to + * stringify some name. The name must uniquely identify a token. + * So, for instance, the token within the reactor should probably be + * called "Reactor Token." + */ virtual const ACE_TCHAR *name (void) const; - // Return the name of the token. This is important for use within - // the token servers (local and remote) as well as with token - // collections. So, all derivations of ACE_Token_Proxy must be able to - // stringify some name. The name must uniquely identify a token. - // So, for instance, the token within the reactor should probably be - // called "Reactor Token." + /** + * This should really be called <someone_waiting>. This is called + * by ACE_Token_xx's when another proxy enters the waiting list and + * requests that the current token holder be notified. + */ virtual void sleep_hook (void); - // This should really be called <someone_waiting>. This is called - // by ACE_Token_xx's when another proxy enters the waiting list and - // requests that the current token holder be notified. + /// This is called when a queued (waiting) proxy is removed from the + /// waiters list and given the token. virtual void token_acquired (ACE_TPQ_Entry *); - // This is called when a queued (waiting) proxy is removed from the - // waiters list and given the token. + /// the client id of the current token holder virtual const ACE_TCHAR *owner_id (void); - // the client id of the current token holder + /// Return a dynamically allocated clone of the derived class. virtual ACE_Token_Proxy *clone (void) const = 0; - // Return a dynamically allocated clone of the derived class. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /** + * This method can be used be Tokens (e.g. Readers/Writer Tokens) to + * distinguish between Proxy types. For instance a Reader proxy + * should return a different type value than a Writer proxy. The + * default implementation returns 0. + */ virtual int type (void) const; - // This method can be used be Tokens (e.g. Readers/Writer Tokens) to - // distinguish between Proxy types. For instance a Reader proxy - // should return a different type value than a Writer proxy. The - // default implementation returns 0. protected: + /// Duplication. ACE_Token_Proxy (const ACE_Token_Proxy &); - // Duplication. + /// If this is set, we ignore deadlock. int ignore_deadlock_; - // If this is set, we ignore deadlock. + /// Print a bunch of debug messages. int debug_; - // Print a bunch of debug messages. + /// Reference to the actual logical token. Many ACE_Local_Mutex + /// proxies can reference the same ACE_Mutex_Token. ACE_Tokens *token_; - // Reference to the actual logical token. Many ACE_Local_Mutex - // proxies can reference the same ACE_Mutex_Token. + /// Handles cond_var waits. int handle_options (ACE_Synch_Options &options, ACE_TOKEN_CONST::COND_VAR &cv); - // Handles cond_var waits. + /// Waiter info used for asynchronous transactions. ACE_TSS_TPQ_Entry waiter_; - // Waiter info used for asynchronous transactions. + /// Make the correct type of ACE_Tokens. This is called by the Token + /// Manager. virtual ACE_Tokens *create_token (const ACE_TCHAR *name) = 0; - // Make the correct type of ACE_Tokens. This is called by the Token - // Manager. }; // 8.. +/** + * @class ACE_Null_Token + * + * @brief No op class for nonthreaded platform protocols. + */ class ACE_Export ACE_Null_Token : public ACE_Token_Proxy { - // = TITLE - // No op class for nonthreaded platform protocols. public: #if defined (ACE_LACKS_INLINE_FUNCTIONS) // @@ Hopefully, we can remove this ridicules ifdef when CE's compiler becomes more normal. + /// Construction. ACE_Null_Token (void); - // Construction. + /// Destructor ~ACE_Null_Token (void); - // Destructor #endif /* ACE_LACKS_INLINE_FUNCTION */ + /// Acquire. virtual int acquire (int /* notify */ = 0, void (* /* sleep_hook */ )(void *) = 0, ACE_Synch_Options & /* options */ = ACE_Synch_Options::defaults) { return 0; } - // Acquire. + /// Renew. virtual int renew (int /* requeue_position */ = -1, ACE_Synch_Options & /* options */ = ACE_Synch_Options::defaults) { return 0; } - // Renew. + /// Try acquire. virtual int tryacquire (void (* /* sleep_hook */)(void *) = 0) { return 0; } - // Try acquire. + /// Release. virtual int release (ACE_Synch_Options & /* options */ = ACE_Synch_Options::defaults) { return 0; } - // Release. + /// Remove. virtual int remove (ACE_Synch_Options & /* options */ = ACE_Synch_Options::defaults) { return 0; } - // Remove. + /// Return a dynamically allocated clone of the derived class. virtual ACE_Token_Proxy *clone (void) const { return new ACE_Null_Token; } - // Return a dynamically allocated clone of the derived class. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// Do not allow the Token Manager to create us. virtual ACE_Tokens *create_token (const ACE_TCHAR *) { return 0; } - // Do not allow the Token Manager to create us. }; // 9.. +/** + * @class ACE_Local_Mutex + * + * @brief Class that acquires, renews, and releases a synchronization + * token local to the process. + * + * This class is a more general-purpose synchronization mechanism + * than SunOS 5.x mutexes. For example, it implements "recursive + * mutex" semantics, where a thread that owns the token can + * reacquire it without deadlocking. In addition, threads that + * are blocked awaiting the token are serviced in strict FIFO + * order as other threads release the token (SunOS 5.x mutexes + * don't strictly enforce an acquisition order). Lastly, + * ACE_Local_Mutex performs deadlock detection on acquire calls. + * The interfaces for acquire, tryacquire, renew, release, + * etc. are defined in ACE_Token_Proxy. The semantics for + * ACE_Local_Mutex are that of a mutex. + */ class ACE_Export ACE_Local_Mutex : public ACE_Token_Proxy { - // = TITLE - // Class that acquires, renews, and releases a synchronization - // token local to the process. - // - // = DESCRIPTION - // This class is a more general-purpose synchronization mechanism - // than SunOS 5.x mutexes. For example, it implements "recursive - // mutex" semantics, where a thread that owns the token can - // reacquire it without deadlocking. In addition, threads that - // are blocked awaiting the token are serviced in strict FIFO - // order as other threads release the token (SunOS 5.x mutexes - // don't strictly enforce an acquisition order). Lastly, - // ACE_Local_Mutex performs deadlock detection on acquire calls. - // - // The interfaces for acquire, tryacquire, renew, release, - // etc. are defined in ACE_Token_Proxy. The semantics for - // ACE_Local_Mutex are that of a mutex. public: + /** + * <token_name> uniquely id's the token. + * <ignore_deadlock> will allow deadlock to occur (useful for + * testing). <debug> prints a bunch of messages. + */ ACE_Local_Mutex (const ACE_TCHAR *token_name = 0, int ignore_deadlock = 0, int debug = 0); - // <token_name> uniquely id's the token. - // <ignore_deadlock> will allow deadlock to occur (useful for - // testing). <debug> prints a bunch of messages. + /// Destructor ~ACE_Local_Mutex (void); - // Destructor + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// Return deep copy. virtual ACE_Token_Proxy *clone (void) const; - // Return deep copy. protected: + /// Return a new ACE_Local_Mutex. virtual ACE_Tokens *create_token (const ACE_TCHAR *name); - // Return a new ACE_Local_Mutex. }; // *. +/** + * @class ACE_Local_RLock + * + * @brief Class that acquires, renews, and releases a readers lock that + * is local to the process. + * + * This class implements the reader interface to canonical + * readers/writer locks. Multiple readers can hold the lock + * simultaneously when no writers have the lock. Alternatively, + * when a writer holds the lock, no other participants (readers + * or writers) may hold the lock. This class is a more + * general-purpose synchronization mechanism than SunOS 5.x + * RLocks. For example, it implements "recursive RLock" + * semantics, where a thread that owns the token can reacquire it + * without deadlocking. In addition, threads that are blocked + * awaiting the token are serviced in strict FIFO order as other + * threads release the token (SunOS 5.x RLockes don't strictly + * enforce an acquisition order). + * The interfaces for acquire, tryacquire, renew, release, + * etc. are defined in ACE_Token_Proxy. The semantics for + * ACE_Local_RLock are that of a readers/writers lock. Acquire + * for this class implies a reader acquisition. That is, + * multiple clients may acquire a lock for read only. + */ class ACE_Export ACE_Local_RLock : public ACE_Token_Proxy { - // = TITLE - // Class that acquires, renews, and releases a readers lock that - // is local to the process. - // - // = DESCRIPTION - // This class implements the reader interface to canonical - // readers/writer locks. Multiple readers can hold the lock - // simultaneously when no writers have the lock. Alternatively, - // when a writer holds the lock, no other participants (readers - // or writers) may hold the lock. This class is a more - // general-purpose synchronization mechanism than SunOS 5.x - // RLocks. For example, it implements "recursive RLock" - // semantics, where a thread that owns the token can reacquire it - // without deadlocking. In addition, threads that are blocked - // awaiting the token are serviced in strict FIFO order as other - // threads release the token (SunOS 5.x RLockes don't strictly - // enforce an acquisition order). - // - // The interfaces for acquire, tryacquire, renew, release, - // etc. are defined in ACE_Token_Proxy. The semantics for - // ACE_Local_RLock are that of a readers/writers lock. Acquire - // for this class implies a reader acquisition. That is, - // multiple clients may acquire a lock for read only. public: // = Initialization and termination. + /** + * <token_name> uniquely id's the token. + * <ignore_deadlock> will allow deadlock to occur (useful for + * testing). <debug> prints a bunch of messages. + */ ACE_Local_RLock (const ACE_TCHAR *token_name = 0, int ignore_deadlock = 0, int debug = 0); - // <token_name> uniquely id's the token. - // <ignore_deadlock> will allow deadlock to occur (useful for - // testing). <debug> prints a bunch of messages. + /// Destructor ~ACE_Local_RLock (void); - // Destructor + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// Returns ACE_RW_Token::RLOCK. virtual int type (void) const; - // Returns ACE_RW_Token::RLOCK. + /// Return deep copy. virtual ACE_Token_Proxy *clone (void) const; - // Return deep copy. protected: + /// Return a new ACE_Local_Mutex. virtual ACE_Tokens *create_token (const ACE_TCHAR *name); - // Return a new ACE_Local_Mutex. }; // *. +/** + * @class ACE_Local_WLock + * + * @brief Class that acquires, renews, and releases a writer lock that + * is local to the process. + * + * This class implements the writer interface to canonical + * readers/writer locks. Multiple readers can hold the lock + * simultaneously when no writers have the lock. Alternatively, + * when a writer holds the lock, no other participants (readers + * or writers) may hold the lock. This class is a more + * general-purpose synchronization mechanism than SunOS 5.x + * WLock. For example, it implements "recursive WLock" + * semantics, where a thread that owns the token can reacquire it + * without deadlocking. In addition, threads that are blocked + * awaiting the token are serviced in strict FIFO order as other + * threads release the token (SunOS 5.x WLocks don't strictly + * enforce an acquisition order). + * The interfaces for acquire, tryacquire, renew, release, + * etc. are defined in ACE_Token_Proxy. The semantics for + * ACE_Local_WLock are that of a readers/writers lock. Acquire + * for this class implies a writer acquisition. That is, only + * one client may hold the lock for writing. + */ class ACE_Export ACE_Local_WLock : public ACE_Token_Proxy { - // = TITLE - // Class that acquires, renews, and releases a writer lock that - // is local to the process. - // - // = DESCRIPTION - // This class implements the writer interface to canonical - // readers/writer locks. Multiple readers can hold the lock - // simultaneously when no writers have the lock. Alternatively, - // when a writer holds the lock, no other participants (readers - // or writers) may hold the lock. This class is a more - // general-purpose synchronization mechanism than SunOS 5.x - // WLock. For example, it implements "recursive WLock" - // semantics, where a thread that owns the token can reacquire it - // without deadlocking. In addition, threads that are blocked - // awaiting the token are serviced in strict FIFO order as other - // threads release the token (SunOS 5.x WLocks don't strictly - // enforce an acquisition order). - // - // The interfaces for acquire, tryacquire, renew, release, - // etc. are defined in ACE_Token_Proxy. The semantics for - // ACE_Local_WLock are that of a readers/writers lock. Acquire - // for this class implies a writer acquisition. That is, only - // one client may hold the lock for writing. public: // = Initialization and termination. + /** + * <token_name> uniquely id's the token. + * <ignore_deadlock> will allow deadlock to occur (useful for + * testing). <debug> prints a bunch of messages. + */ ACE_Local_WLock (const ACE_TCHAR *token_name = 0, int ignore_deadlock = 0, int debug = 0); - // <token_name> uniquely id's the token. - // <ignore_deadlock> will allow deadlock to occur (useful for - // testing). <debug> prints a bunch of messages. + /// Destructor ~ACE_Local_WLock (void); - // Destructor + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// Returns ACE_RW_Token::WLOCK. virtual int type (void) const; - // Returns ACE_RW_Token::WLOCK. + /// Return deep copy. virtual ACE_Token_Proxy *clone (void) const; - // Return deep copy. protected: + /// Return a new ACE_Local_Mutex. ACE_Tokens *create_token (const ACE_TCHAR *name); - // Return a new ACE_Local_Mutex. }; #if defined (__ACE_INLINE__) diff --git a/ace/Log_Msg.h b/ace/Log_Msg.h index 74336ddd441..08650b8bcd1 100644 --- a/ace/Log_Msg.h +++ b/ace/Log_Msg.h @@ -1,18 +1,15 @@ // -*- C++ -*- -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Log_Msg.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Log_Msg.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_LOG_MSG_H #define ACE_LOG_MSG_H @@ -120,178 +117,187 @@ class ACE_Log_Msg_Callback; // Forward declaration class ACE_Thread_Descriptor; +/** + * @class ACE_Log_Msg + * + * @brief Provides a variable length argument message logging + * abstraction. + * + * This class is very flexible since it allows formatted error + * messages to be printed in a thread-safe manner to stderr or a + * distributed logger. Moreover, the message is kept in a + * thread-specific storage location (i.e. there is one ACE_Log_Msg + * object per thread), which can be used to communicate errors + * between framework methods and callers. + * A message is logged by the log() method, only if the message + * priority is currently enabled. The ACE_Log_Msg class uses + * two priority masks to control its logging behavior. The + * <priority_mask_> object attribute is thread specific and + * specifies the priority levels logged by the thread. The + * <process_priority_mask_> class attribute is not thread + * specific and specifies the priority levels that will be + * logged by all threads in the process. By default, all + * levels are enabled for <priority_mask_> and all levels + * are disabled for <process_priority_mask_> (i.e. each thread + * determines which priority levels will be logged). Both + * priority masks can be modified using the priority_mask() + * method of this class. + */ class ACE_Export ACE_Log_Msg { - // = TITLE - // Provides a variable length argument message logging - // abstraction. - // - // = DESCRIPTION - // This class is very flexible since it allows formatted error - // messages to be printed in a thread-safe manner to stderr or a - // distributed logger. Moreover, the message is kept in a - // thread-specific storage location (i.e. there is one ACE_Log_Msg - // object per thread), which can be used to communicate errors - // between framework methods and callers. - // - // A message is logged by the log() method, only if the message - // priority is currently enabled. The ACE_Log_Msg class uses - // two priority masks to control its logging behavior. The - // <priority_mask_> object attribute is thread specific and - // specifies the priority levels logged by the thread. The - // <process_priority_mask_> class attribute is not thread - // specific and specifies the priority levels that will be - // logged by all threads in the process. By default, all - // levels are enabled for <priority_mask_> and all levels - // are disabled for <process_priority_mask_> (i.e. each thread - // determines which priority levels will be logged). Both - // priority masks can be modified using the priority_mask() - // method of this class. public: // Logger Flags. enum { + /// Write messages to stderr. STDERR = 1, - // Write messages to stderr. + /// Write messages to the local client logger deamon. LOGGER = 2, - // Write messages to the local client logger deamon. + /// Write messages to the ostream * stored in thread-specific + /// storage. OSTREAM = 4, - // Write messages to the ostream * stored in thread-specific - // storage. + /// Write messages to the callback object. MSG_CALLBACK = 8, - // Write messages to the callback object. + /// Display messages in a verbose manner. VERBOSE = 16, - // Display messages in a verbose manner. + /// Display messages in a less verbose manner (i.e., only print + /// information that can change between calls). VERBOSE_LITE = 32, - // Display messages in a less verbose manner (i.e., only print - // information that can change between calls). + /// Do not print messages at all (just leave in thread-specific + /// storage for later inspection). SILENT = 64 - // Do not print messages at all (just leave in thread-specific - // storage for later inspection). }; // = Initialization and termination routines. + /// Returns a pointer to the Singleton. static ACE_Log_Msg *instance (void); - // Returns a pointer to the Singleton. + /// Returns non-null if an ACE_Log_Msg exists for the calling thread. static int exists (void); - // Returns non-null if an ACE_Log_Msg exists for the calling thread. + /// Clears the flag from the default priority mask used to + /// initialize ACE_Log_Msg instances. static void disable_debug_messages (ACE_Log_Priority priority = LM_DEBUG); - // Clears the flag from the default priority mask used to - // initialize ACE_Log_Msg instances. + /// Sets the flag in the default priority mask used to initialize + /// ACE_Log_Msg instances. static void enable_debug_messages (ACE_Log_Priority priority = LM_DEBUG); - // Sets the flag in the default priority mask used to initialize - // ACE_Log_Msg instances. + /// Initialize logger. ACE_Log_Msg (void); - // Initialize logger. + /// cleanup logger. ~ACE_Log_Msg (void); - // cleanup logger. + /** + * Initialize the ACE error handling facility. <prog_name> is the + * name of the executable program. <flags> are a bitwise-or of + * options flags passed to the Logger (see the enum above for the valid + * values). If the <LOGGER> bit in <flags> is enabled then + * <logger_key> is the name of ACE_FIFO rendezvous point where the + * local client logger daemon is listening for logging messages. + */ int open (const ACE_TCHAR *prog_name, u_long options_flags = ACE_Log_Msg::STDERR, const ACE_TCHAR *logger_key = 0); - // Initialize the ACE error handling facility. <prog_name> is the - // name of the executable program. <flags> are a bitwise-or of - // options flags passed to the Logger (see the enum above for the valid - // values). If the <LOGGER> bit in <flags> is enabled then - // <logger_key> is the name of ACE_FIFO rendezvous point where the - // local client logger daemon is listening for logging messages. // = Set/get the options flags. + /** + * Enable the bits in the logger's options flags. + * Disable the bits in the logger's options flags. + * Return the bits in the logger's options flags. + */ void set_flags (u_long f); - // Enable the bits in the logger's options flags. void clr_flags (u_long f); - // Disable the bits in the logger's options flags. u_long flags (void); - // Return the bits in the logger's options flags. // = Allow apps to acquire and release internal synchronization lock. // This lock is used internally by the <ACE_Log_Msg> implementation. // By exporting the lock, applications can hold the lock atomically // over a number of calls to <ACE_Log_Msg>. + /// Acquire the internal lock. + /// Release the internal lock. int acquire (void); - // Acquire the internal lock. int release (void); - // Release the internal lock. + /// Call after doing a <fork> to resynchronize the process id and + /// <program_name> variables. void sync (const ACE_TCHAR *program_name); - // Call after doing a <fork> to resynchronize the process id and - // <program_name> variables. // = Set/get methods. Note that these are non-static and thus will // be thread-specific. + /// Set the result of the operation status (by convention, -1 means + /// error). void op_status (int status); - // Set the result of the operation status (by convention, -1 means - // error). + /// Get the result of the operation status (by convention, -1 means + /// error). int op_status (void); - // Get the result of the operation status (by convention, -1 means - // error). + /// Set the value of the errnum (by convention this corresponds to + /// errno). void errnum (int); - // Set the value of the errnum (by convention this corresponds to - // errno). + /// Get the value of the errnum (by convention this corresponds to + /// errno). int errnum (void); - // Get the value of the errnum (by convention this corresponds to - // errno). + /// Set the line number where an error occurred. void linenum (int); - // Set the line number where an error occurred. + /// Get the line number where an error occurred. int linenum (void); - // Get the line number where an error occurred. + /// Set the file name where an error occurred. void file (const ACE_TCHAR *); - // Set the file name where an error occurred. + /// Get the file name where an error occurred. const ACE_TCHAR *file (void); - // Get the file name where an error occurred. + /// Set the message that describes what type of error occurred. void msg (const ACE_TCHAR *); - // Set the message that describes what type of error occurred. + /// Get the message that describes what type of error occurred. const ACE_TCHAR *msg (void); - // Get the message that describes what type of error occurred. + /// Set the field that indicates whether interrupted calls should be + /// restarted. void restart (int); - // Set the field that indicates whether interrupted calls should be - // restarted. + /// Get the field that indicates whether interrupted calls should be + /// restarted. int restart (void); - // Get the field that indicates whether interrupted calls should be - // restarted. // = Notice that the following two function is equivalent to // "void msg_ostream (HANDLE)" and "HANDLE msg_ostream (void)" // on Windows CE. There is no <iostream.h> support on CE. + /// Update the ostream without overwriting the delete_ostream_ flag. void msg_ostream (ACE_OSTREAM_TYPE *); - // Update the ostream without overwriting the delete_ostream_ flag. + /** + * delete_stream == 1, forces Log_Msg.h to delete the stream in + * its own ~dtor (assumes control of the stream) + * use only with proper ostream (eg: fstream), not (cout, cerr) + */ void msg_ostream (ACE_OSTREAM_TYPE *, int delete_ostream); - // delete_stream == 1, forces Log_Msg.h to delete the stream in - // its own ~dtor (assumes control of the stream) - // use only with proper ostream (eg: fstream), not (cout, cerr) + /// Get the ostream that is used to print error messages. ACE_OSTREAM_TYPE *msg_ostream (void) const; - // Get the ostream that is used to print error messages. + /** + * Set a new callback object and return the existing callback to + * allow "chaining". Note that <ACE_Log_Msg_Callback>s are not + * inherited when spawning a new thread, so you'll need to reset + * them in each thread. + */ ACE_Log_Msg_Callback *msg_callback (ACE_Log_Msg_Callback *c); ACE_Log_Msg_Callback *msg_callback (void) const; - // Set a new callback object and return the existing callback to - // allow "chaining". Note that <ACE_Log_Msg_Callback>s are not - // inherited when spawning a new thread, so you'll need to reset - // them in each thread. // = Nesting depth increment and decrement. int inc (void); @@ -305,27 +311,29 @@ public: int trace_active (void); void trace_active (int value); + /// Get the TSS thread descriptor. ACE_Thread_Descriptor *thr_desc (void) const; - // Get the TSS thread descriptor. + /** + * Set the TSS thread descriptor. This method will call + * td->acquire_release to block execution until this call + * return. + */ void thr_desc (ACE_Thread_Descriptor *td); - // Set the TSS thread descriptor. This method will call - // td->acquire_release to block execution until this call - // return. #if defined (ACE_HAS_WIN32_STRUCTURAL_EXCEPTIONS) && !defined(ACE_HAS_LASTEST_AND_GREATEST) // These functions are disabled with ACE_HAS_LATEST_AND_GREATEST // because the *semantics* have changed (they objects are no longer // TSS). + /// Get/Set TSS exception action. + /// NOTE: The action is no longer TSS, they are global! ACE_SEH_EXCEPT_HANDLER seh_except_selector (void); ACE_SEH_EXCEPT_HANDLER seh_except_selector (ACE_SEH_EXCEPT_HANDLER); - // Get/Set TSS exception action. - // NOTE: The action is no longer TSS, they are global! + /// Get/Set TSS exception handler. + /// NOTE: The handler is no longer TSS, they are global! ACE_SEH_EXCEPT_HANDLER seh_except_handler (void); ACE_SEH_EXCEPT_HANDLER seh_except_handler (ACE_SEH_EXCEPT_HANDLER); - // Get/Set TSS exception handler. - // NOTE: The handler is no longer TSS, they are global! #endif /* ACE_HAS_WIN32_STRUCTURAL_EXCEPTIONS && ! ACE_HAS_GREATES_AND_LATEST*/ // = Stop/start/query tracing status on a per-thread basis... @@ -340,38 +348,43 @@ public: } MASK_TYPE; // = Get/set the priority mask. + /// Get the current <ACE_Log_Priority> mask. + /// Set the <ACE_Log_Priority> mask, returns original mask. u_long priority_mask (MASK_TYPE = THREAD); - // Get the current <ACE_Log_Priority> mask. u_long priority_mask (u_long, MASK_TYPE = THREAD); - // Set the <ACE_Log_Priority> mask, returns original mask. + /// Return true if the requested priority is enabled. int log_priority_enabled (ACE_Log_Priority log_priority); - // Return true if the requested priority is enabled. + /// Return true if the requested priority is enabled. int log_priority_enabled (ACE_Log_Priority log_priority, const char *, ...); - // Return true if the requested priority is enabled. #if defined (ACE_USES_WCHAR) // We are not using ACE_TCHAR for this since ACE_HEX_DUMP // doesn't take in a ACE_TCHAR. log_hexdump takes in a char // string, so this must be able to take in a char string even // when using ACE_USES_WCHAR. + /// Return true if the requested priority is enabled. int log_priority_enabled (ACE_Log_Priority log_priority, const wchar_t *, ...); - // Return true if the requested priority is enabled. #endif /* ACE_USES_WCHAR */ + /// Optimize reading of the pid (avoids a system call if the value is + /// cached...). pid_t getpid (void) const; - // Optimize reading of the pid (avoids a system call if the value is - // cached...). // = Set/get the name of the local host. const ACE_TCHAR *local_host (void) const; void local_host (const ACE_TCHAR *); + /** + * Set the line number, file name, operational status, error number, + * restart flag, ostream, and the callback object. This combines + * all the other set methods into a single method. + */ void set (const ACE_TCHAR *file, int line, int op_status = -1, @@ -379,166 +392,181 @@ public: int restart = 1, ACE_OSTREAM_TYPE *os = 0, ACE_Log_Msg_Callback *c = 0); - // Set the line number, file name, operational status, error number, - // restart flag, ostream, and the callback object. This combines - // all the other set methods into a single method. + /// These values are only actually set if the requested priority is + /// enabled. void conditional_set (const ACE_TCHAR *file, int line, int op_status, int errnum); - // These values are only actually set if the requested priority is - // enabled. + /** + * Format a message to the thread-safe ACE logging mechanism. Valid + * options (prefixed by '%', as in printf format strings) include: + * + 'A': print an ACE_timer_t value (which could be either double or ACE_UINT32.) + * + 'a': exit the program at this point (var-argument is the exit status!) + * + 'c': print a character + * + 'i', 'd': print a decimal number + * + 'I', indent according to nesting depth + * + 'e', 'E', 'f', 'F', 'g', 'G': print a double + * + 'l', print line number where an error occurred. + * + 'm': Return the message corresponding to errno value, e.g., as done by strerror() + * + 'N': print file name where the error occurred. + * + 'n': print the name of the program (or "<unknown>" if not set) + * + 'o': print as an octal number + * + 'P': print out the current process id + * + 'p': print out the appropriate errno message from sys_errlist, e.g., as done by perror() + * + 'Q': print out the uint64 number + * + 'r': call the function pointed to by the corresponding argument + * + 'R': print return status + * + 'S': print out the appropriate _sys_siglist entry corresponding to var-argument. + * + 's': print out a character string + * + 'T': print timestamp in hour:minute:sec:usec format. + * + 'D': print timestamp in month/day/year hour:minute:sec:usec format. + * + 't': print thread id (1 if single-threaded) + * + 'u': print as unsigned int + * + 'W': print out a wide (Unicode) character string (currently Win32 only). + * + 'X', 'x': print as a hex number + * + '%': print out a single percent sign, '%' + */ ssize_t log (ACE_Log_Priority priority, const ACE_TCHAR *format, ...); - // Format a message to the thread-safe ACE logging mechanism. Valid - // options (prefixed by '%', as in printf format strings) include: - // 'A': print an ACE_timer_t value (which could be either double or ACE_UINT32.) - // 'a': exit the program at this point (var-argument is the exit status!) - // 'c': print a character - // 'i', 'd': print a decimal number - // 'I', indent according to nesting depth - // 'e', 'E', 'f', 'F', 'g', 'G': print a double - // 'l', print line number where an error occurred. - // 'm': Return the message corresponding to errno value, e.g., as done by strerror() - // 'N': print file name where the error occurred. - // 'n': print the name of the program (or "<unknown>" if not set) - // 'o': print as an octal number - // 'P': print out the current process id - // 'p': print out the appropriate errno message from sys_errlist, e.g., as done by perror() - // 'Q': print out the uint64 number - // 'r': call the function pointed to by the corresponding argument - // 'R': print return status - // 'S': print out the appropriate _sys_siglist entry corresponding to var-argument. - // 's': print out a character string - // 'T': print timestamp in hour:minute:sec:usec format. - // 'D': print timestamp in month/day/year hour:minute:sec:usec format. - // 't': print thread id (1 if single-threaded) - // 'u': print as unsigned int - // 'W': print out a wide (Unicode) character string (currently Win32 only). - // 'X', 'x': print as a hex number - // '%': print out a single percent sign, '%' + /** + * An alternative logging mechanism that makes it possible to + * integrate variable argument lists from other logging mechanisms + * into the ACE mechanism. + */ ssize_t log (const ACE_TCHAR *format, ACE_Log_Priority priority, va_list argp); - // An alternative logging mechanism that makes it possible to - // integrate variable argument lists from other logging mechanisms - // into the ACE mechanism. + /// Log a custom built log record to the currently enabled logging + /// sinks. ssize_t log (ACE_Log_Record &log_record, int suppress_stderr = 0); - // Log a custom built log record to the currently enabled logging - // sinks. + /** + * Method to log hex dump. This is useful for debugging. Calls + * <log> to do the actual print, but formats first to make the chars + * printable. + */ int log_hexdump (ACE_Log_Priority log_priority, const char *buffer, int size, const ACE_TCHAR *text = 0); - // Method to log hex dump. This is useful for debugging. Calls - // <log> to do the actual print, but formats first to make the chars - // printable. static void init_hook (ACE_OS_Log_Msg_Attributes &attributes # if defined (ACE_HAS_WIN32_STRUCTURAL_EXCEPTIONS) , ACE_SEH_EXCEPT_HANDLER selector = 0 , ACE_SEH_EXCEPT_HANDLER handler = 0 # endif /* ACE_HAS_WIN32_STRUCTURAL_EXCEPTIONS */ + /** + * Init hook, create a Log_Msg_Attribute object, initialize its + * attributes from the TSS Log_Msg and save the object in the + * <attributes> argument + */ ); - // Init hook, create a Log_Msg_Attribute object, initialize its - // attributes from the TSS Log_Msg and save the object in the - // <attributes> argument + /** + * Inherit hook, the <attributes> field is a Log_Msg_Attribute + * object, invoke the <inherit_log_msg> method on it, then destroy + * it and set the <attribute> argument to 0 + */ static void inherit_hook (ACE_OS_Thread_Descriptor *thr_desc, ACE_OS_Log_Msg_Attributes &attributes); - // Inherit hook, the <attributes> field is a Log_Msg_Attribute - // object, invoke the <inherit_log_msg> method on it, then destroy - // it and set the <attribute> argument to 0 + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Status of operation (-1 means failure, >= 0 means success). int status_; - // Status of operation (-1 means failure, >= 0 means success). + /// Type of error that occurred (see <sys/errno.h>). int errnum_; - // Type of error that occurred (see <sys/errno.h>). + /// Line number where the error occurred. int linenum_; - // Line number where the error occurred. + /// File where the error occurred. ACE_TCHAR file_[MAXPATHLEN + 1]; - // File where the error occurred. + /// The error message. ACE_TCHAR msg_[ACE_Log_Record::MAXLOGMSGLEN]; - // The error message. + /// Indicates whether we should restart system calls that are + /// interrupted. int restart_; - // Indicates whether we should restart system calls that are - // interrupted. + /// The ostream where logging messages can be written. ACE_OSTREAM_TYPE *ostream_; - // The ostream where logging messages can be written. + /// The callback object. ACE_Log_Msg_Callback *msg_callback_; - // The callback object. + /// Depth of the nesting for printing traces. int trace_depth_; - // Depth of the nesting for printing traces. + /// Are we already within an ACE_Trace constructor call? int trace_active_; - // Are we already within an ACE_Trace constructor call? + /// Are we allowing tracing in this thread? int tracing_enabled_; - // Are we allowing tracing in this thread? + /// Are we deleting this ostream? int delete_ostream_; - // Are we deleting this ostream? + /** + * If we're running in the context of an <ACE_Thread_Manager> this + * will point to the thread descriptor adapter which holds the + * thread descriptor of the thread. This can be used to repidly + * access all thread data kept in <ACE_Thread_Descriptor>. + */ ACE_Thread_Descriptor *thr_desc_; - // If we're running in the context of an <ACE_Thread_Manager> this - // will point to the thread descriptor adapter which holds the - // thread descriptor of the thread. This can be used to repidly - // access all thread data kept in <ACE_Thread_Descriptor>. + /** + * Keeps track of all the per-thread <ACE_Log_Priority> values that + * are currently enabled. Default is for all logging priorities to + * be _disabled_. + */ u_long priority_mask_; - // Keeps track of all the per-thread <ACE_Log_Priority> values that - // are currently enabled. Default is for all logging priorities to - // be _disabled_. // = The following fields are *not* kept in thread-specific storage. // We only want one instance for the entire process! + /** + * Keeps track of all the per-process <ACE_Log_Priority> values that + * are currently enabled. Default is for all logging priorities to + * be enabled. + */ static u_long process_priority_mask_; - // Keeps track of all the per-process <ACE_Log_Priority> values that - // are currently enabled. Default is for all logging priorities to - // be enabled. + /// Records the program name. static const ACE_TCHAR *program_name_; - // Records the program name. + /// Name of the local host (used when printing messages). static const ACE_TCHAR *local_host_; - // Name of the local host (used when printing messages). + /// Process id of the current process. static pid_t pid_; - // Process id of the current process. + /// Options flags. static u_long flags_; - // Options flags. + /// Offset of msg_[]. static int msg_off_; - // Offset of msg_[]. + /** + * Number of existing Log_Msg instances; when 0, delete program/host + * names + * Priority mask to use for each new instance + */ static int instance_count_; - // Number of existing Log_Msg instances; when 0, delete program/host - // names static u_long default_priority_mask_; - // Priority mask to use for each new instance // Anonymous struct since there will only be one instance. This // struct keeps information stored away in case we actually end up @@ -560,14 +588,14 @@ private: # endif /* ACE_HAS_THREAD_SPECIFIC_STORAGE || ACE_HAS_TSS_EMULATION */ #endif /* ACE_MT_SAFE */ + /// For cleanup, at program termination. static void close (void); - // For cleanup, at program termination. + /// Decouple the OS layer from the Log_Msg layer. static void sync_hook (const ACE_TCHAR *prg_name); - // Decouple the OS layer from the Log_Msg layer. + /// Return the TSS singleton thread descriptor static ACE_OS_Thread_Descriptor *thr_desc_hook (void); - // Return the TSS singleton thread descriptor friend void ACE_OS::cleanup_tss (const u_int); diff --git a/ace/Log_Msg_Backend.h b/ace/Log_Msg_Backend.h index b87c771cacd..73e90d8b8ff 100644 --- a/ace/Log_Msg_Backend.h +++ b/ace/Log_Msg_Backend.h @@ -1,18 +1,15 @@ // -*- C++ -*- -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Log_Msg_Backend.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Log_Msg_Backend.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_LOG_MSG_BACKEND_H #define ACE_LOG_MSG_BACKEND_H @@ -26,8 +23,10 @@ class ACE_Log_Record; -/// Define the interface for ACE_Log_Msg backend strategies. /** + * @class ACE_Log_Msg_Backend + * + * @brief Define the interface for ACE_Log_Msg backend strategies. * * The ACE_Log_Msg class can log to multiple backend strategies, for * example, some send messages to a remote logger, others dump to a diff --git a/ace/Log_Msg_Callback.h b/ace/Log_Msg_Callback.h index 5ad448371be..b1f262108b1 100644 --- a/ace/Log_Msg_Callback.h +++ b/ace/Log_Msg_Callback.h @@ -1,18 +1,15 @@ // -*- C++ -*- -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Log_Msg_Callback.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Log_Msg_Callback.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_LOG_MSG_CALLBACK_H #define ACE_LOG_MSG_CALLBACK_H @@ -26,8 +23,10 @@ class ACE_Log_Record; -/// An interface class used to get logging callbacks. /** + * @class ACE_Log_Msg_Callback + * + * @brief An interface class used to get logging callbacks. * * Users who are interested in getting the logging messages * directly, can subclass this interface and override the log() @@ -47,13 +46,10 @@ class ACE_Log_Record; * callback object per Log_Msg object. Moreover, * <ACE_Log_Msg_Callbacks> are not inherited when a new thread * is spawned, so you'll need to reset these in each new thread. + * */ class ACE_Export ACE_Log_Msg_Callback { - // = TITLE - // - // - // = DESCRIPTION public: /// No-op virtual destructor. virtual ~ACE_Log_Msg_Callback (void); diff --git a/ace/Log_Msg_IPC.h b/ace/Log_Msg_IPC.h index 8d40b5098f4..9990f0b5997 100644 --- a/ace/Log_Msg_IPC.h +++ b/ace/Log_Msg_IPC.h @@ -1,18 +1,15 @@ // -*- C++ -*- -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Log_Msg_IPC.h -// -// = AUTHOR -// Carlos O'Ryan -// -// ============================================================================ +//============================================================================= +/** + * @file Log_Msg_IPC.h + * + * $Id$ + * + * @author Carlos O'Ryan + */ +//============================================================================= + #ifndef ACE_LOG_MSG_LOGGER_H #define ACE_LOG_MSG_LOGGER_H diff --git a/ace/Log_Priority.h b/ace/Log_Priority.h index 393458aced3..c0740f7effe 100644 --- a/ace/Log_Priority.h +++ b/ace/Log_Priority.h @@ -1,77 +1,74 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Log_Priority.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Log_Priority.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_LOG_PRIORITY_H #define ACE_LOG_PRIORITY_H #include "ace/pre.h" +/** + * @brief This data type indicates the relative priorities of the + * logging messages, from lowest to highest priority. + * + * These values are defined using powers of two so that it's + * possible to form a mask to turn them on or off dynamically. + */ enum ACE_Log_Priority { - // = TITLE - // This data type indicates the relative priorities of the - // logging messages, from lowest to highest priority. - // - // = DESCRIPTION - // These values are defined using powers of two so that it's - // possible to form a mask to turn them on or off dynamically. // = Note, this first argument *must* start at 1! + /// Shutdown the logger (decimal 1). LM_SHUTDOWN = 01, - // Shutdown the logger (decimal 1). + /// Messages indicating function-calling sequence (decimal 2). LM_TRACE = 02, - // Messages indicating function-calling sequence (decimal 2). + /// Messages that contain information normally of use only when + /// debugging a program (decimal 4). LM_DEBUG = 04, - // Messages that contain information normally of use only when - // debugging a program (decimal 4). + /// Informational messages (decimal 8). LM_INFO = 010, - // Informational messages (decimal 8). + /// Conditions that are not error conditions, but that may require + /// special handling (decimal 16). LM_NOTICE = 020, - // Conditions that are not error conditions, but that may require - // special handling (decimal 16). + /// Warning messages (decimal 32). LM_WARNING = 040, - // Warning messages (decimal 32). + /// Initialize the logger (decimal 64). LM_STARTUP = 0100, - // Initialize the logger (decimal 64). + /// Error messages (decimal 128). LM_ERROR = 0200, - // Error messages (decimal 128). + /// Critical conditions, such as hard device errors (decimal 256). LM_CRITICAL = 0400, - // Critical conditions, such as hard device errors (decimal 256). + /// A condition that should be corrected immediately, such as a + /// corrupted system database (decimal 512). LM_ALERT = 01000, - // A condition that should be corrected immediately, such as a - // corrupted system database (decimal 512). + /// A panic condition. This is normally broadcast to all users + /// (decimal 1024). LM_EMERGENCY = 02000, - // A panic condition. This is normally broadcast to all users - // (decimal 1024). + /// The maximum logging priority. LM_MAX = LM_EMERGENCY, - // The maximum logging priority. - // Do not use!! This enum value ensures that the underlying - // integral type for this enum is at least 32 bits. + /// Do not use!! This enum value ensures that the underlying + /// integral type for this enum is at least 32 bits. LM_ENSURE_32_BITS = 0x7FFFFFFF }; diff --git a/ace/Log_Record.h b/ace/Log_Record.h index f30c4baa6de..a356ed23486 100644 --- a/ace/Log_Record.h +++ b/ace/Log_Record.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Log_Record.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Log_Record.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + // These need to go outside of the #ifdef to avoid problems with // circular dependencies... @@ -28,11 +25,10 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/// Defines the structure of an ACE logging record. class ACE_Export ACE_Log_Record { public: - // = TITLE - // Defines the structure of an ACE logging record. enum { @@ -52,22 +48,26 @@ public: }; // = Initialization + /** + * Create a <Log_Record> and set its priority, time stamp, and + * process id. + * Create a <Log_Record> and set its priority, time stamp, and + * process id. + */ ACE_Log_Record (void); ACE_Log_Record (ACE_Log_Priority lp, long time_stamp, long pid); - // Create a <Log_Record> and set its priority, time stamp, and - // process id. ACE_Log_Record (ACE_Log_Priority lp, const ACE_Time_Value &time_stamp, long pid); - // Create a <Log_Record> and set its priority, time stamp, and - // process id. + /// Default dtor. ~ACE_Log_Record (void); - // Default dtor. + /// Write the contents of the logging record to the appropriate + /// <FILE>. int print (const ACE_TCHAR host_name[], u_long verbose_flag, #if !defined (ACE_HAS_WINCE) @@ -75,15 +75,13 @@ public: #else FILE *fp); #endif /* ACE_HAS_WINCE */ - // Write the contents of the logging record to the appropriate - // <FILE>. #if !defined (ACE_LACKS_IOSTREAM_TOTALLY) + /// Write the contents of the logging record to the appropriate + /// <ostream>. int print (const ACE_TCHAR host_name[], u_long verbose_flag, ostream &stream); - // Write the contents of the logging record to the appropriate - // <ostream>. #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */ int format_msg (const ACE_TCHAR host_name[], @@ -91,99 +89,105 @@ public: ACE_TCHAR *verbose_msg); #if defined (ACE_HAS_WINCE) + /// For Windows CE, the default is to log messages to a preset + /// window. int print (const ACE_TCHAR host_name[], u_long verbose_flag, ACE_CE_Bridge *log_ = 0); - // For Windows CE, the default is to log messages to a preset - // window. #endif /* defined (ACE_HAS_WINCE) */ + /** + * Returns a character array with the string form of the + * <ACE_Log_Priority> parameter. This is used for the verbose + * printing format. + */ static const ACE_TCHAR *priority_name (ACE_Log_Priority p); - // Returns a character array with the string form of the - // <ACE_Log_Priority> parameter. This is used for the verbose - // printing format. // = Marshall/demarshall + /// Encode the <Log_Record> for transmission on the network. void encode (void); - // Encode the <Log_Record> for transmission on the network. + /// Decode the <Log_Record> received from the network. void decode (void); - // Decode the <Log_Record> received from the network. // = Set/get methods + /// Get the type of the <Log_Record>. long type (void) const; - // Get the type of the <Log_Record>. + /// Set the type of the <Log_Record>. void type (long); - // Set the type of the <Log_Record>. + /** + * Get the priority of the <Log_Record> <type_>. This is computed + * as the base 2 logarithm of <type_> (which must be a power of 2, + * as defined by the enums in <ACE_Log_Priority>). + */ u_long priority (void) const; - // Get the priority of the <Log_Record> <type_>. This is computed - // as the base 2 logarithm of <type_> (which must be a power of 2, - // as defined by the enums in <ACE_Log_Priority>). + /// Set the priority of the <Log_Record> <type_> (which must be a + /// power of 2, as defined by the enums in <ACE_Log_Priority>). void priority (u_long num); - // Set the priority of the <Log_Record> <type_> (which must be a - // power of 2, as defined by the enums in <ACE_Log_Priority>). + /// Get the length of the <Log_Record>. long length (void) const; - // Get the length of the <Log_Record>. + /// Set the length of the <Log_Record>. void length (long); - // Set the length of the <Log_Record>. + /// Get the time stamp of the <Log_Record>. const ACE_Time_Value &time_stamp (void) const; - // Get the time stamp of the <Log_Record>. + /// Set the time stamp of the <Log_Record>. void time_stamp (const ACE_Time_Value &); - // Set the time stamp of the <Log_Record>. + /// Get the process id of the <Log_Record>. long pid (void) const; - // Get the process id of the <Log_Record>. + /// Set the process id of the <Log_Record>. void pid (long); - // Set the process id of the <Log_Record>. + /// Get the message data of the <Log_Record>. ACE_TCHAR *msg_data (void); - // Get the message data of the <Log_Record>. + /// Set the message data of the <Log_Record>. void msg_data (const ACE_TCHAR *data); - // Set the message data of the <Log_Record>. + /// Set the size of the message data of the <Log_Record>. void msg_data_len (size_t len); - // Set the size of the message data of the <Log_Record>. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Round up to the alignment restrictions. void round_up (void); - // Round up to the alignment restrictions. + /** + * Total length of the logging record in bytes. This field *must* + * come first in order for various IPC framing mechanisms to work + * correctly. In addition, the field must be an ACE_INT32 in order + * to be passed portably across platforms. + */ ACE_INT32 length_; - // Total length of the logging record in bytes. This field *must* - // come first in order for various IPC framing mechanisms to work - // correctly. In addition, the field must be an ACE_INT32 in order - // to be passed portably across platforms. + /// Type of logging record. long type_; - // Type of logging record. + /// Time that the logging record was generated. ACE_Time_Value time_stamp_; - // Time that the logging record was generated. + /// Id of process that generated the logging record. long pid_; - // Id of process that generated the logging record. + /// Logging record data ACE_TCHAR msg_data_[MAXLOGMSGLEN]; - // Logging record data + /// Symbolic names for the <ACE_Log_Priority> enums. static const ACE_TCHAR *priority_names_[]; - // Symbolic names for the <ACE_Log_Priority> enums. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/Logging_Strategy.h b/ace/Logging_Strategy.h index 0544ecf571a..d411fc7ef58 100644 --- a/ace/Logging_Strategy.h +++ b/ace/Logging_Strategy.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Logging_Strategy.h -// -// = AUTHOR -// Prashant Jain <pjain@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Logging_Strategy.h + * + * $Id$ + * + * @author Prashant Jain <pjain@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_LOGGING_STRATEGY_H #define ACE_LOGGING_STRATEGY_H @@ -28,72 +25,75 @@ #define ACE_DEFAULT_MAX_LOGFILE_SIZE 16384 /* KB */ #endif /* ACE_DEFAULT_MAX_LOGFILE_SIZE */ +/** + * @class ACE_Logging_Strategy + * + * @brief This class provides the hooks to control the output produced + * by any of the network services. + * + * Depending upon when this service is invoked and with what + * flags, the output of other network services can be + * controlled. The output can be streamed to stderr, to a file, + * to a logging daemon, or it can be set to be "silent". + * If logging records are output to a file, the file can be set + * to a maximum size and repeatedly split into new files. The + * log file size can be limited at any logging point (i.e., + * application, client logging daemon, or server logging daemon) + * by specifying the -i <sample_interval_in_secs> and -m + * <max_size_in_KB> options for the Logging_Strategy class in a + * svc.conf file. + */ class ACE_Export ACE_Logging_Strategy : public ACE_Service_Object { - // = TITLE - // This class provides the hooks to control the output produced - // by any of the network services. - // - // = DESCRIPTION - // Depending upon when this service is invoked and with what - // flags, the output of other network services can be - // controlled. The output can be streamed to stderr, to a file, - // to a logging daemon, or it can be set to be "silent". - // - // If logging records are output to a file, the file can be set - // to a maximum size and repeatedly split into new files. The - // log file size can be limited at any logging point (i.e., - // application, client logging daemon, or server logging daemon) - // by specifying the -i <sample_interval_in_secs> and -m - // <max_size_in_KB> options for the Logging_Strategy class in a - // svc.conf file. public: + /// Constructor. ACE_Logging_Strategy (void); - // Constructor. + /// Dynamic linking initialization hook. virtual int init (int argc, ACE_TCHAR *argv[]); - // Dynamic linking initialization hook. + /// Dynamic linking termination hook. virtual int fini (void); - // Dynamic linking termination hook. + /** + * Timeout handler which tests logfile size. If the current logfile + * size exceeds <max_size_>, the current logfile is closed, saved to + * logfile.old, and a new logfile is reopened. + */ virtual int handle_timeout (const ACE_Time_Value& tv, const void* arg); - // Timeout handler which tests logfile size. If the current logfile - // size exceeds <max_size_>, the current logfile is closed, saved to - // logfile.old, and a new logfile is reopened. + /// Parse svc.conf arguments. int parse_args (int argc, ACE_TCHAR *argv[]); - // Parse svc.conf arguments. private: + /// Tokenize to set all the flags void tokenize (ACE_TCHAR *flag_string); - // Tokenize to set all the flags + /// Tokenize to set priorities (either process or thread one). void priorities (ACE_TCHAR *priority_string, ACE_Log_Msg::MASK_TYPE mask); - // Tokenize to set priorities (either process or thread one). + /// Current thread's priority mask set by <priorities> u_long thread_priority_mask_; - // Current thread's priority mask set by <priorities> + /// Process-wide priority mask set by <priorities> u_long process_priority_mask_; - // Process-wide priority mask set by <priorities> + /// Flags we keep track of. u_long flags_; - // Flags we keep track of. + /// File name we're logging to. ACE_TCHAR *filename_; - // File name we're logging to. + /// If non-0 then wipeout the logfile, otherwise append to it. int wipeout_logfile_; - // If non-0 then wipeout the logfile, otherwise append to it. + /// If non-zero, sampling interval (in secs) at which maximum logfile + /// size is checked, otherwise logfile size can grow indefinitely. u_long interval_; - // If non-zero, sampling interval (in secs) at which maximum logfile - // size is checked, otherwise logfile size can grow indefinitely. + /// Maximum logfile size (in KB). u_long max_size_; - // Maximum logfile size (in KB). }; ACE_FACTORY_DECLARE (ACE, ACE_Logging_Strategy) diff --git a/ace/MEM_Acceptor.h b/ace/MEM_Acceptor.h index 63603fbdbbd..4c74af00d3c 100644 --- a/ace/MEM_Acceptor.h +++ b/ace/MEM_Acceptor.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// MEM_Aceeptor.h -// -// = AUTHOR -// Nanbor Wang <nanbor@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file MEM_Acceptor.h + * + * $Id$ + * + * @author Nanbor Wang <nanbor@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_MEM_ACCEPTOR_H #define ACE_MEM_ACCEPTOR_H @@ -30,84 +27,90 @@ // Forward decl. class ACE_Reactor; +/** + * @class ACE_MEM_Acceptor + * + * @brief Defines the format and interface for the acceptor side of the + * local mmap stream. + * + * This class should be modified to prevent user passing a + * non-localhost endpoint as the acceptor listen point because + * it doesn't make any sense at all to make the listening + * endpoint visible (or connectable) anywhere outside of this + * machine. However, the type of endpoint is left as <ACE_Addr> + * so we can later changed to use UNIX sockets with mmap stream + * if so desired. (Currently, using UNIX socket with this class + * will not work.) + */ class ACE_Export ACE_MEM_Acceptor : public ACE_SOCK_Acceptor { - // = TITLE - // Defines the format and interface for the acceptor side of the - // local mmap stream. - // - // = DESCRIPTION - // This class should be modified to prevent user passing a - // non-localhost endpoint as the acceptor listen point because - // it doesn't make any sense at all to make the listening - // endpoint visible (or connectable) anywhere outside of this - // machine. However, the type of endpoint is left as <ACE_Addr> - // so we can later changed to use UNIX sockets with mmap stream - // if so desired. (Currently, using UNIX socket with this class - // will not work.) public: // = Initialization methods. + /// Default constructor. ACE_MEM_Acceptor (void); - // Default constructor. + /// destructor. ~ACE_MEM_Acceptor (void); - // destructor. + /// Initiate a passive mode socket. ACE_MEM_Acceptor (const ACE_MEM_Addr &remote_sap, int reuse_addr = 0, int backlog = ACE_DEFAULT_BACKLOG, int protocol = 0); - // Initiate a passive mode socket. + /** + * Initialize a passive-mode BSD-style acceptor socket (no QoS). + * <local_sap> is the address that we're going to listen for + * connections on. If <reuse_addr> is 1 then we'll use the + * <SO_REUSEADDR> to reuse this address. Returns 0 on success and + * -1 on failure. + */ int open (const ACE_MEM_Addr &local_sap, int reuse_addr = 0, int backlog = ACE_DEFAULT_BACKLOG, int protocol = 0); - // Initialize a passive-mode BSD-style acceptor socket (no QoS). - // <local_sap> is the address that we're going to listen for - // connections on. If <reuse_addr> is 1 then we'll use the - // <SO_REUSEADDR> to reuse this address. Returns 0 on success and - // -1 on failure. + /// Accept a new data transfer connection. int accept (ACE_MEM_Stream &new_ipc_sap, ACE_MEM_Addr *remote_addr = 0, ACE_Time_Value *timeout = 0, int restart = 1, int reset_new_handle = 0); - // Accept a new data transfer connection. + /// Perform operations that must occur after <ACE_OS::accept> is + /// called. int shared_accept_finish (ACE_MEM_Stream new_stream, int in_blocking_mode, int reset_new_handle) const; - // Perform operations that must occur after <ACE_OS::accept> is - // called. + /** + * Accessor/mutator of mmap filename prefix. By default, the + * <mmap_prefix_> is not set and the mmap filename is + * ${(TMP|TEMP)}//ACE_MEM_Acceptor_(port-number)_(&stream), + * otherwise, it is <mmap_prefix_>_(port-number)_(&stream), + * <mmap_prefix_> should include _absolute_ path so the connector + * within the same host can located the mmap file. Example: + * /tmp/mmapfile. + */ const ACE_TCHAR *mmap_prefix (void) const; void mmap_prefix (ACE_TCHAR *prefix); - // Accessor/mutator of mmap filename prefix. By default, the - // <mmap_prefix_> is not set and the mmap filename is - // ${(TMP|TEMP)}//ACE_MEM_Acceptor_(port-number)_(&stream), - // otherwise, it is <mmap_prefix_>_(port-number)_(&stream), - // <mmap_prefix_> should include _absolute_ path so the connector - // within the same host can located the mmap file. Example: - // /tmp/mmapfile. + /// Return the local endpoint address in the referenced <ACE_Addr>. + /// Returns 0 if successful, else -1. int get_local_addr (ACE_MEM_Addr &) const; - // Return the local endpoint address in the referenced <ACE_Addr>. - // Returns 0 if successful, else -1. + /// Accessor to the mmap options. ACE_MEM_SAP::MALLOC_OPTIONS& malloc_options (void); - // Accessor to the mmap options. // = Meta-type info typedef ACE_MEM_Addr PEER_ADDR; typedef ACE_MEM_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = The following methods should not be accessable externally @@ -141,13 +144,13 @@ protected: int reset_new_handle = 0) const; private: + /// The filename prefix of the created mmap files. It should + /// contains the absolute path name of the file. ACE_TCHAR *mmap_prefix_; - // The filename prefix of the created mmap files. It should - // contains the absolute path name of the file. + /// A cached MALLOC_OPTIONS. MEM_Accaptor use it to create the shared + /// mamory malloc upon every incoming connection. ACE_MEM_SAP::MALLOC_OPTIONS malloc_options_; - // A cached MALLOC_OPTIONS. MEM_Accaptor use it to create the shared - // mamory malloc upon every incoming connection. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/MEM_Addr.h b/ace/MEM_Addr.h index 743587e9a62..a9cfea3f5d4 100644 --- a/ace/MEM_Addr.h +++ b/ace/MEM_Addr.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// MEM_Addr.h -// -// = AUTHOR -// Nanbor Wang <nanbor@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file MEM_Addr.h + * + * $Id$ + * + * @author Nanbor Wang <nanbor@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_MEM_ADDR_H #define ACE_MEM_ADDR_H @@ -26,115 +23,122 @@ #include "ace/INET_Addr.h" +/** + * @class ACE_MEM_Addr + * + * @brief Defines a C++ wrapper facade for the shared memory transport + * address family format. + */ class ACE_Export ACE_MEM_Addr : public ACE_Addr { - // = TITLE - // Defines a C++ wrapper facade for the shared memory transport - // address family format. public: // = Initialization methods. + /// Default constructor. ACE_MEM_Addr (void); - // Default constructor. + /// Copy constructor. ACE_MEM_Addr (const ACE_MEM_Addr &); - // Copy constructor. + /// Creates an <ACE_INET_Addr> from a <port_number> and the remote + /// <host_name>. ACE_MEM_Addr (u_short port_number); - // Creates an <ACE_INET_Addr> from a <port_number> and the remote - // <host_name>. + /// Creates an <ACE_INET_Addr> from a <port_name>. ACE_EXPLICIT ACE_MEM_Addr (const ACE_TCHAR port_name[]); - // Creates an <ACE_INET_Addr> from a <port_name>. + /// Default dtor. ~ACE_MEM_Addr (void); - // Default dtor. // = Direct initialization methods. + /// default initialization routine. int initialize_local (u_short port); - // default initialization routine. + /// Check if <sap> designate an enpoint withing the same host. int same_host (const ACE_INET_Addr& sap); - // Check if <sap> designate an enpoint withing the same host. // These methods are useful after the object has been constructed. + /** + * Initializes an <ACE_INET_Addr> from a <port_number> and the + * remote <host_name>. If <encode> is enabled then <port_number> is + * converted into network byte order, otherwise it is assumed to be + * in network byte order already and are passed straight through. + */ int set (u_short port_number, int encode = 1); - // Initializes an <ACE_INET_Addr> from a <port_number> and the - // remote <host_name>. If <encode> is enabled then <port_number> is - // converted into network byte order, otherwise it is assumed to be - // in network byte order already and are passed straight through. + /// Uses <getservbyname> to initialize an <ACE_INET_Addr> from a + /// <port_name>, the remote <host_name>, and the <protocol>. int set (const ACE_TCHAR port_name[]); - // Uses <getservbyname> to initialize an <ACE_INET_Addr> from a - // <port_name>, the remote <host_name>, and the <protocol>. + /// Return a pointer to the underlying network address. virtual void *get_addr (void) const; - // Return a pointer to the underlying network address. + /// Set a pointer to the address. virtual void set_addr (void *, int len); - // Set a pointer to the address. + /// Transform the external <ACE_INET_Addr> address into string + /// format. virtual int addr_to_string (ACE_TCHAR buffer[], size_t size, int ipaddr_format = 1) const; - // Transform the external <ACE_INET_Addr> address into string - // format. + /// Initializes the external <ACE_INET_Addr> from the <address>. virtual int string_to_addr (const ACE_TCHAR address[]); - // Initializes the external <ACE_INET_Addr> from the <address>. + /// Sets the port number. void set_port_number (u_short, int encode = 1); - // Sets the port number. + /// Return the port number, converting it into host byte order. u_short get_port_number (void) const; - // Return the port number, converting it into host byte order. + /// Return the character representation of the hostname. int get_host_name (ACE_TCHAR hostname[], size_t hostnamelen) const; - // Return the character representation of the hostname. + /** + * Return the character representation of the hostname (this version + * is non-reentrant since it returns a pointer to a static data + * area). + */ const char *get_host_name (void) const; - // Return the character representation of the hostname (this version - // is non-reentrant since it returns a pointer to a static data - // area). + /// Return the "dotted decimal" external address. const char *get_host_addr (void) const; - // Return the "dotted decimal" external address. + /// Return the 4-byte external IP address, converting it into host byte + /// order. ACE_UINT32 get_ip_address (void) const; - // Return the 4-byte external IP address, converting it into host byte - // order. const ACE_INET_Addr &get_remote_addr (void) const; const ACE_INET_Addr &get_local_addr (void) const; + /// Compare two addresses for equality. The addresses are considered + /// equal if they contain the same IP address and port number. int operator == (const ACE_MEM_Addr &SAP) const; int operator == (const ACE_INET_Addr &SAP) const; - // Compare two addresses for equality. The addresses are considered - // equal if they contain the same IP address and port number. + /// Compare two addresses for inequality. int operator != (const ACE_MEM_Addr &SAP) const; int operator != (const ACE_INET_Addr &SAP) const; - // Compare two addresses for inequality. + /// Computes and returns hash value. virtual u_long hash (void) const; - // Computes and returns hash value. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// External INET addr used for identifying host. ACE_INET_Addr external_; - // External INET addr used for identifying host. + /// Internal INET addr for accepting/connecting. ACE_INET_Addr internal_; - // Internal INET addr for accepting/connecting. }; #if defined (__ACE_INLINE__) diff --git a/ace/MEM_Connector.h b/ace/MEM_Connector.h index 10a5f9ade73..68338c8bb67 100644 --- a/ace/MEM_Connector.h +++ b/ace/MEM_Connector.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// MEM_Connector.h -// -// = AUTHOR -// Nanbor Wang <nanbor@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file MEM_Connector.h + * + * $Id$ + * + * @author Nanbor Wang <nanbor@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_MEM_CONNECTOR_H #define ACE_MEM_CONNECTOR_H @@ -27,16 +24,34 @@ #include "ace/MEM_Stream.h" #include "ace/MEM_Addr.h" +/** + * @class ACE_MEM_Connector + * + * @brief Defines the format and interface for the connector side of + * the <ACE_MEM_Stream>. + */ class ACE_Export ACE_MEM_Connector : public ACE_SOCK_Connector { - // = TITLE - // Defines the format and interface for the connector side of - // the <ACE_MEM_Stream>. public: // = Initialization methods. + /// Default constructor. ACE_MEM_Connector (void); - // Default constructor. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <0> then the user is letting the OS do the + * binding. If <reuse_addr> == 1 then the <local_addr> is reused, + * even if it hasn't been cleanedup yet. + */ ACE_MEM_Connector (ACE_MEM_Stream &new_stream, const ACE_INET_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -45,20 +60,22 @@ public: int flags = 0, int perms = 0, int protocol = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <0> then the user is letting the OS do the - // binding. If <reuse_addr> == 1 then the <local_addr> is reused, - // even if it hasn't been cleanedup yet. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <0> then the user is letting the OS do the + * binding. If <reuse_addr> == 1 then the <local_addr> is reused, + * even if it hasn't been cleanedup yet. + */ int connect (ACE_MEM_Stream &new_stream, const ACE_INET_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -67,40 +84,27 @@ public: int flags = 0, int perms = 0, int protocol = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <0> then the user is letting the OS do the - // binding. If <reuse_addr> == 1 then the <local_addr> is reused, - // even if it hasn't been cleanedup yet. + /// Accessor to underlying malloc options. ACE_MEM_SAP::MALLOC_OPTIONS &malloc_options (void); - // Accessor to underlying malloc options. // = Meta-type info typedef ACE_INET_Addr PEER_ADDR; typedef ACE_MEM_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// The acceptor address this connector is connecting to. ACE_MEM_Addr address_; - // The acceptor address this connector is connecting to. + /// A cached MALLOC_OPTIONS that the MEM_Connector used to initialize + /// the shared memory malloc update connection establishment. ACE_MEM_SAP::MALLOC_OPTIONS malloc_options_; - // A cached MALLOC_OPTIONS that the MEM_Connector used to initialize - // the shared memory malloc update connection establishment. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/MEM_IO.h b/ace/MEM_IO.h index 445cdfc70c7..9dcecaf4f5e 100644 --- a/ace/MEM_IO.h +++ b/ace/MEM_IO.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// MEM_IO.h -// -// = AUTHOR -// Nanbor Wang <nanbor@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file MEM_IO.h + * + * $Id$ + * + * @author Nanbor Wang <nanbor@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_MEM_IO_H #define ACE_MEM_IO_H @@ -27,132 +24,144 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_MEM_IO + * + * @brief Defines the methods for the ACE shared memeory wrapper I/O + * routines (e.g., send/recv). + * The shared memory transport uses ACE_SOCK_* class to + * implement the signaling mechanism so we can easily use the + * new mechanism with the Reactor pattern (which uses select + * under the hood.) + * ACE_MEM_Acceptor and ACE_MEM_Connector are used to establish + * connections. When a connection is established, + * ACE_MEM_Acceptor creates the MMAP file for data exchange and + * sends the location of the file (complete path name) to + * ACE_MEM_Connector thru the socket. ACE_MEM_Connector then + * reads the location of the file off the socket and opens up + * the same MMAP file. ACE_MEM_Stream at each side then + * contains a reference to the ACE_Mallo object using the same + * MMAP file. + * When sending information using methods provided in this + * class, ACE_MEM_IO requests a chunk of memory from the + * MALLOC_TYPE object, copy the data into the shared memory and + * send the memory offset (from the start of the ACE_Malloc) + * across the socket. This action also servers as a signal to + * the other end. The receiving side then reverses the + * procedures and copies the information into user buffer. + */ class ACE_Export ACE_MEM_IO : public ACE_SOCK, public ACE_MEM_SAP { - // = TITLE - // Defines the methods for the ACE shared memeory wrapper I/O - // routines (e.g., send/recv). - // - // The shared memory transport uses ACE_SOCK_* class to - // implement the signaling mechanism so we can easily use the - // new mechanism with the Reactor pattern (which uses select - // under the hood.) - // - // ACE_MEM_Acceptor and ACE_MEM_Connector are used to establish - // connections. When a connection is established, - // ACE_MEM_Acceptor creates the MMAP file for data exchange and - // sends the location of the file (complete path name) to - // ACE_MEM_Connector thru the socket. ACE_MEM_Connector then - // reads the location of the file off the socket and opens up - // the same MMAP file. ACE_MEM_Stream at each side then - // contains a reference to the ACE_Mallo object using the same - // MMAP file. - // - // When sending information using methods provided in this - // class, ACE_MEM_IO requests a chunk of memory from the - // MALLOC_TYPE object, copy the data into the shared memory and - // send the memory offset (from the start of the ACE_Malloc) - // across the socket. This action also servers as a signal to - // the other end. The receiving side then reverses the - // procedures and copies the information into user buffer. public: // = Initialization and termination methods. + /// Constructor. ACE_MEM_IO (void); - // Constructor. + /// Destructor. ~ACE_MEM_IO (void); - // Destructor. + /// Send an <n> byte buffer to the other process using shm_malloc_ + /// connected thru the socket. ssize_t send (const void *buf, size_t n, int flags) ; - // Send an <n> byte buffer to the other process using shm_malloc_ - // connected thru the socket. + /// Recv an <n> byte buffer from the shm_malloc_ thru connected socket. ssize_t recv (void *buf, size_t n, int flags) ; - // Recv an <n> byte buffer from the shm_malloc_ thru connected socket. + /// Send an <n> byte buffer to the other process using shm_malloc_ + /// connected thru the socket. ssize_t send (const void *buf, size_t n) ; - // Send an <n> byte buffer to the other process using shm_malloc_ - // connected thru the socket. + /// Recv an <n> byte buffer from the shm_malloc_ thru connected socket. ssize_t recv (void *buf, size_t n) ; - // Recv an <n> byte buffer from the shm_malloc_ thru connected socket. + /** + * Wait to to <timeout> amount of time to send up to <n> bytes into + * <buf> from <handle> (uses the <send> call). If <send> times out + * a -1 is returned with <errno == ETIME>. If it succeeds the + * number of bytes sent is returned. + */ ssize_t send (const void *buf, size_t n, int flags, const ACE_Time_Value *timeout); - // Wait to to <timeout> amount of time to send up to <n> bytes into - // <buf> from <handle> (uses the <send> call). If <send> times out - // a -1 is returned with <errno == ETIME>. If it succeeds the - // number of bytes sent is returned. + /** + * Wait up to <timeout> amount of time to receive up to <n> bytes + * into <buf> from <handle> (uses the <recv> call). If <recv> times + * out a -1 is returned with <errno == ETIME>. If it succeeds the + * number of bytes received is returned. + */ ssize_t recv (void *buf, size_t n, int flags, const ACE_Time_Value *timeout); - // Wait up to <timeout> amount of time to receive up to <n> bytes - // into <buf> from <handle> (uses the <recv> call). If <recv> times - // out a -1 is returned with <errno == ETIME>. If it succeeds the - // number of bytes received is returned. + /** + * Wait to to <timeout> amount of time to send up to <n> bytes into + * <buf> from <handle> (uses the <send> call). If <send> times out + * a -1 is returned with <errno == ETIME>. If it succeeds the + * number of bytes sent is returned. + */ ssize_t send (const void *buf, size_t n, const ACE_Time_Value *timeout); - // Wait to to <timeout> amount of time to send up to <n> bytes into - // <buf> from <handle> (uses the <send> call). If <send> times out - // a -1 is returned with <errno == ETIME>. If it succeeds the - // number of bytes sent is returned. + /** + * Wait up to <timeout> amount of time to receive up to <n> bytes + * into <buf> from <handle> (uses the <recv> call). If <recv> times + * out a -1 is returned with <errno == ETIME>. If it succeeds the + * number of bytes received is returned. + */ ssize_t recv (void *buf, size_t n, const ACE_Time_Value *timeout); - // Wait up to <timeout> amount of time to receive up to <n> bytes - // into <buf> from <handle> (uses the <recv> call). If <recv> times - // out a -1 is returned with <errno == ETIME>. If it succeeds the - // number of bytes received is returned. + /** + * Wait to to <timeout> amount of time to send the <message_block>. + * If <send> times out a -1 is returned with <errno == ETIME>. If + * it succeeds the number of bytes sent is returned. + */ ssize_t send (const ACE_Message_Block *message_block, const ACE_Time_Value *timeout); - // Wait to to <timeout> amount of time to send the <message_block>. - // If <send> times out a -1 is returned with <errno == ETIME>. If - // it succeeds the number of bytes sent is returned. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /// Return the local endpoint port number. Returns 0 if successful, + /// else -1. /* int get_local_port (u_short &) const; - // Return the local endpoint port number. Returns 0 if successful, - // else -1. + /// Return the port number of the remotely connected peer (if there + /// is one). Returns 0 if successful, else -1. int get_remote_port (u_short &) const; - // Return the port number of the remotely connected peer (if there - // is one). Returns 0 if successful, else -1. */ protected: + /** + * Fetch location of next available data into <recv_buffer_>. + * As this operation read the address of the data off the socket + * using ACE::recv, <timeout> only applies to ACE::recv. + */ ssize_t fetch_recv_buf (int flags, const ACE_Time_Value *timeout = 0); - // Fetch location of next available data into <recv_buffer_>. - // As this operation read the address of the data off the socket - // using ACE::recv, <timeout> only applies to ACE::recv. private: + /// Internal pointer for support recv/send. void *recv_buffer_; - // Internal pointer for support recv/send. + /// Record the current total buffer size of <recv_buffer_>. ssize_t buf_size_; - // Record the current total buffer size of <recv_buffer_>. + /// Record the current read pointer location in <recv_buffer_>. ssize_t cur_offset_; - // Record the current read pointer location in <recv_buffer_>. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/MEM_SAP.h b/ace/MEM_SAP.h index ba9dc33f615..853b3dd8772 100644 --- a/ace/MEM_SAP.h +++ b/ace/MEM_SAP.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// MEM_SAP.h -// -// = AUTHOR -// Nanbor Wang <nanbor@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file MEM_SAP.h + * + * $Id$ + * + * @author Nanbor Wang <nanbor@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_MEM_SAP_H #define ACE_MEM_SAP_H @@ -26,73 +23,82 @@ #include "ace/Process_Mutex.h" +/** + * @class ACE_MEM_SAP + * + * @brief Defines the methods of shared memory management for + * shared memory transport. + */ class ACE_Export ACE_MEM_SAP { - // = TITLE - // Defines the methods of shared memory management for - // shared memory transport. public: // = Initialization and termination methods. + /// I'll just hardcode this for mmap for now. #if (ACE_HAS_POSITION_INDEPENDENT_POINTERS == 1) typedef ACE_Malloc_T<ACE_MMAP_MEMORY_POOL, ACE_Process_Mutex, ACE_PI_Control_Block> MALLOC_TYPE; #else typedef ACE_Malloc_T<ACE_MMAP_MEMORY_POOL, ACE_Process_Mutex, ACE_Control_Block> MALLOC_TYPE; #endif /* ACE_HAS_POSITION_INDEPENDENT_POINTERS == 1 */ typedef ACE_MMAP_Memory_Pool_Options MALLOC_OPTIONS; - // I'll just hardcode this for mmap for now. + /// Destructor. ~ACE_MEM_SAP (void); - // Destructor. + /// request a buffer of size <size>. Return 0 if the <shm_malloc_> is + /// not initialized. void *acquire_buffer (const ssize_t size); - // request a buffer of size <size>. Return 0 if the <shm_malloc_> is - // not initialized. + /// release a buffer pointed by <buf>. Return -1 if the <shm_malloc_> + /// is not initialized. int release_buffer (void *buf); - // release a buffer pointed by <buf>. Return -1 if the <shm_malloc_> - // is not initialized. + /** + * Set the length of buf (containing information) to <n> bytes. + * Return the offset of the <buf> relative to the base address. + * <buf> must be acquired by <get_buffer> method. Return -1 if the + * <shm_malloc_> is not initialized. + */ off_t set_buf_len (void *buf, size_t n); - // Set the length of buf (containing information) to <n> bytes. - // Return the offset of the <buf> relative to the base address. - // <buf> must be acquired by <get_buffer> method. Return -1 if the - // <shm_malloc_> is not initialized. + /** + * Convert the buffer offset <off> to absolute address to <buf>. + * Return the size of valid information containing in the <buf>, + * -1 if <shm_malloc_> is not initialized. + */ ssize_t get_buf_len (const off_t off, void *&buf); - // Convert the buffer offset <off> to absolute address to <buf>. - // Return the size of valid information containing in the <buf>, - // -1 if <shm_malloc_> is not initialized. + /// Remove the shared resouce (mmap file) used by us. int remove (void); - // Remove the shared resouce (mmap file) used by us. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Class initializing methods to create/connect to a shared memory pool. + /** + * Create a new shm_malloc object. Return 0 if succeed and -1 + * otherwise. This method should only be called from an acceptor + * class that wants to create a new memory pool for inter process + * communication. + */ int create_shm_malloc (const ACE_TCHAR *name, MALLOC_OPTIONS *options = 0); - // Create a new shm_malloc object. Return 0 if succeed and -1 - // otherwise. This method should only be called from an acceptor - // class that wants to create a new memory pool for inter process - // communication. + /// Close down the share memory pool. If <remove> != 0, then the + /// mmap file will also get removed. int close_shm_malloc (const int remove = 0); - // Close down the share memory pool. If <remove> != 0, then the - // mmap file will also get removed. + /// Data exchange channel. MALLOC_TYPE *shm_malloc_; - // Data exchange channel. + /// Constructor. Prevent this class from being instantiated. ACE_MEM_SAP (void); - // Constructor. Prevent this class from being instantiated. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/MEM_Stream.h b/ace/MEM_Stream.h index 5aeff9e1190..1fdc9a910aa 100644 --- a/ace/MEM_Stream.h +++ b/ace/MEM_Stream.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// MEM_Stream.h -// -// = AUTHOR -// Nanbor Wang <nanbor@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file MEM_Stream.h + * + * $Id$ + * + * @author Nanbor Wang <nanbor@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_MEM_STREAM_H #define ACE_MEM_STREAM_H @@ -29,95 +26,108 @@ class ACE_MEM_Acceptor; class ACE_MEM_Connector; +/** + * @class ACE_MEM_Stream + * + * @brief Defines the methods in the <ACE_MEM_Stream> abstraction. + * + * This adds additional wrapper methods atop the <ACE_MEM_IO> + * class. + */ class ACE_Export ACE_MEM_Stream : public ACE_MEM_IO { - // = TITLE - // Defines the methods in the <ACE_MEM_Stream> abstraction. - // - // = DESCRIPTION - // This adds additional wrapper methods atop the <ACE_MEM_IO> - // class. public: friend class ACE_MEM_Acceptor; friend class ACE_MEM_Connector; // Initialization and termination methods. + /// Constructor. ACE_MEM_Stream (void); - // Constructor. + /// Constructor (sets the underlying <ACE_HANDLE> with <h>). ACE_MEM_Stream (ACE_HANDLE h); - // Constructor (sets the underlying <ACE_HANDLE> with <h>). + /// Destructor. ~ACE_MEM_Stream (void); - // Destructor. //= The following two methods use write and read system calls. + /// Send n bytes, keep trying until n are sent. + /// Recv n bytes, keep trying until n are received. ssize_t send_n (const void *buf, int n); - // Send n bytes, keep trying until n are sent. ssize_t recv_n (void *buf, int n); - // Recv n bytes, keep trying until n are received. // = The following two methods use the send and recv system calls. + /// Send n bytes, keep trying until n are sent. + /// Recv n bytes, keep trying until n are received. ssize_t send_n (const void *buf, int n, int flags); - // Send n bytes, keep trying until n are sent. ssize_t recv_n (void *buf, int n, int flags); - // Recv n bytes, keep trying until n are received. -/* +#if 0 + /** + * Try to send exactly <len> bytes into <buf> from <handle> (uses + * the <send> call). If <send> blocks for longer than <timeout> the + * number of bytes actually sent is returned with <errno == ETIME>. + * If a timeout does not occur, <send_n> return <len> (i.e., the + * number of bytes requested to be sent). + */ ssize_t send_n (const void *buf, size_t len, int flags, const ACE_Time_Value *timeout); - // Try to send exactly <len> bytes into <buf> from <handle> (uses - // the <send> call). If <send> blocks for longer than <timeout> the - // number of bytes actually sent is returned with <errno == ETIME>. - // If a timeout does not occur, <send_n> return <len> (i.e., the - // number of bytes requested to be sent). + /** + * Try to recv exactly <len> bytes into <buf> from <handle> (uses + * the <ACE::recv_n> call). The <ACE_Time_Value> indicates how long + * to blocking trying to receive. If <timeout> == 0, the caller + * will block until action is possible, else will wait until the + * relative time specified in *<timeout> elapses). If <recv> blocks + * for longer than <timeout> the number of bytes actually read is + * returned with <errno == ETIME>. If a timeout does not occur, + * <recv_n> return <len> (i.e., the number of bytes requested to be + * read). + */ ssize_t recv_n (void *buf, size_t len, int flags, const ACE_Time_Value *timeout); - // Try to recv exactly <len> bytes into <buf> from <handle> (uses - // the <ACE::recv_n> call). The <ACE_Time_Value> indicates how long - // to blocking trying to receive. If <timeout> == 0, the caller - // will block until action is possible, else will wait until the - // relative time specified in *<timeout> elapses). If <recv> blocks - // for longer than <timeout> the number of bytes actually read is - // returned with <errno == ETIME>. If a timeout does not occur, - // <recv_n> return <len> (i.e., the number of bytes requested to be - // read). + /** + * Send an <iovec> of size <n> to the connected socket (uses + * <ACE::sendv_n>). Will block until all bytes are sent or an error + * occurs. + */ ssize_t sendv_n (const iovec iov[], size_t n) const; - // Send an <iovec> of size <n> to the connected socket (uses - // <ACE::sendv_n>). Will block until all bytes are sent or an error - // occurs. + /// Receive an <iovec> of size <n> to the connected socket. ssize_t recvv_n (iovec iov[], size_t n) const; - // Receive an <iovec> of size <n> to the connected socket. -*/ +#endif /* 0 */ + // = Selectively close endpoints. + + /// Close down the reader. int close_reader (void); - // Close down the reader. + + /// Close down the writer. int close_writer (void); - // Close down the writer. + /** + * Close down the socket (we need this to make things work correctly + * on Win32, which requires use to do a <close_writer> before doing + * the close to avoid losing data). + */ int close (void); - // Close down the socket (we need this to make things work correctly - // on Win32, which requires use to do a <close_writer> before doing - // the close to avoid losing data). // = Meta-type info typedef ACE_Addr PEER_ADDR; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/Makefile b/ace/Makefile index ae00f6f926e..30f3d75120a 100644 --- a/ace/Makefile +++ b/ace/Makefile @@ -576,7 +576,7 @@ endif # GHS # DO NOT PUT ANYTHING AFTER THIS LINE, IT WILL GO AWAY. -.obj/Basic_Types.o .obj/Basic_Types.o .obj/Basic_Types.o .obj/Basic_Types.o: Basic_Types.cpp \ +.obj/Basic_Types.o .obj/Basic_Types.so .shobj/Basic_Types.o .shobj/Basic_Types.so: Basic_Types.cpp \ OS.h \ pre.h \ config-all.h \ @@ -607,7 +607,8 @@ endif # GHS OS.i \ Template_Instantiations.cpp -.obj/OS.o .obj/OS.o .obj/OS.o .obj/OS.o: OS.cpp OS.h \ +.obj/OS.o .obj/OS.so .shobj/OS.o .shobj/OS.so: OS.cpp \ + OS.h \ pre.h \ config-all.h \ config.h \ @@ -644,7 +645,7 @@ endif # GHS Base_Thread_Adapter.inl \ OS_Thread_Adapter.inl -.obj/OS_Dirent.o .obj/OS_Dirent.o .obj/OS_Dirent.o .obj/OS_Dirent.o: OS_Dirent.cpp \ +.obj/OS_Dirent.o .obj/OS_Dirent.so .shobj/OS_Dirent.o .shobj/OS_Dirent.so: OS_Dirent.cpp \ OS_Dirent.h \ pre.h \ config-all.h \ @@ -663,7 +664,7 @@ endif # GHS OS_String.h \ OS_String.inl -.obj/OS_Memory.o .obj/OS_Memory.o .obj/OS_Memory.o .obj/OS_Memory.o: OS_Memory.cpp \ +.obj/OS_Memory.o .obj/OS_Memory.so .shobj/OS_Memory.o .shobj/OS_Memory.so: OS_Memory.cpp \ OS_Memory.h \ pre.h \ config-all.h \ @@ -680,7 +681,7 @@ endif # GHS OS_Export.h \ OS_Memory.inl -.obj/OS_String.o .obj/OS_String.o .obj/OS_String.o .obj/OS_String.o: OS_String.cpp \ +.obj/OS_String.o .obj/OS_String.so .shobj/OS_String.o .shobj/OS_String.so: OS_String.cpp \ OS_String.h \ pre.h \ config-all.h \ @@ -699,7 +700,7 @@ endif # GHS OS_Memory.h \ OS_Memory.inl -.obj/OS_TLI.o .obj/OS_TLI.o .obj/OS_TLI.o .obj/OS_TLI.o: OS_TLI.cpp \ +.obj/OS_TLI.o .obj/OS_TLI.so .shobj/OS_TLI.o .shobj/OS_TLI.so: OS_TLI.cpp \ OS_TLI.h \ pre.h \ config-all.h \ @@ -716,7 +717,7 @@ endif # GHS OS_Export.h \ OS_TLI.inl -.obj/Base_Thread_Adapter.o .obj/Base_Thread_Adapter.o .obj/Base_Thread_Adapter.o .obj/Base_Thread_Adapter.o: Base_Thread_Adapter.cpp \ +.obj/Base_Thread_Adapter.o .obj/Base_Thread_Adapter.so .shobj/Base_Thread_Adapter.o .shobj/Base_Thread_Adapter.so: Base_Thread_Adapter.cpp \ Base_Thread_Adapter.h \ pre.h \ OS_Log_Msg_Attributes.h \ @@ -750,7 +751,7 @@ endif # GHS Trace.h \ OS.i -.obj/OS_Thread_Adapter.o .obj/OS_Thread_Adapter.o .obj/OS_Thread_Adapter.o .obj/OS_Thread_Adapter.o: OS_Thread_Adapter.cpp \ +.obj/OS_Thread_Adapter.o .obj/OS_Thread_Adapter.so .shobj/OS_Thread_Adapter.o .shobj/OS_Thread_Adapter.so: OS_Thread_Adapter.cpp \ OS_Thread_Adapter.h \ pre.h \ Base_Thread_Adapter.h \ @@ -787,7 +788,7 @@ endif # GHS Trace.h \ OS.i -.obj/OS_Log_Msg_Attributes.o .obj/OS_Log_Msg_Attributes.o .obj/OS_Log_Msg_Attributes.o .obj/OS_Log_Msg_Attributes.o: OS_Log_Msg_Attributes.cpp \ +.obj/OS_Log_Msg_Attributes.o .obj/OS_Log_Msg_Attributes.so .shobj/OS_Log_Msg_Attributes.o .shobj/OS_Log_Msg_Attributes.so: OS_Log_Msg_Attributes.cpp \ OS_Log_Msg_Attributes.h \ pre.h \ config-all.h \ @@ -805,7 +806,7 @@ endif # GHS OS_Export.h \ OS_Log_Msg_Attributes.inl -.obj/Thread_Hook.o .obj/Thread_Hook.o .obj/Thread_Hook.o .obj/Thread_Hook.o: Thread_Hook.cpp \ +.obj/Thread_Hook.o .obj/Thread_Hook.so .shobj/Thread_Hook.o .shobj/Thread_Hook.so: Thread_Hook.cpp \ Thread_Hook.h \ pre.h \ config-all.h \ @@ -836,7 +837,7 @@ endif # GHS Trace.h \ OS.i -.obj/Sched_Params.o .obj/Sched_Params.o .obj/Sched_Params.o .obj/Sched_Params.o: Sched_Params.cpp \ +.obj/Sched_Params.o .obj/Sched_Params.so .shobj/Sched_Params.o .shobj/Sched_Params.so: Sched_Params.cpp \ Sched_Params.h \ pre.h \ OS.h \ @@ -868,7 +869,8 @@ endif # GHS OS.i \ Sched_Params.i -.obj/ACE.o .obj/ACE.o .obj/ACE.o .obj/ACE.o: ACE.cpp ACE.h \ +.obj/ACE.o .obj/ACE.so .shobj/ACE.o .shobj/ACE.so: ACE.cpp \ + ACE.h \ pre.h \ OS.h \ config-all.h \ @@ -968,7 +970,7 @@ endif # GHS Message_Block_T.i \ Message_Block_T.cpp -.obj/Init_ACE.o .obj/Init_ACE.o .obj/Init_ACE.o .obj/Init_ACE.o: Init_ACE.cpp \ +.obj/Init_ACE.o .obj/Init_ACE.so .shobj/Init_ACE.o .shobj/Init_ACE.so: Init_ACE.cpp \ Init_ACE.h \ pre.h \ OS.h \ @@ -1005,7 +1007,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Flag_Manip.o .obj/Flag_Manip.o .obj/Flag_Manip.o .obj/Flag_Manip.o: Flag_Manip.cpp Flag_Manip.h \ +.obj/Flag_Manip.o .obj/Flag_Manip.so .shobj/Flag_Manip.o .shobj/Flag_Manip.so: Flag_Manip.cpp Flag_Manip.h \ pre.h OS.h \ config-all.h \ config.h \ @@ -1036,7 +1038,7 @@ endif # GHS OS.i \ Flag_Manip.i -.obj/Handle_Ops.o .obj/Handle_Ops.o .obj/Handle_Ops.o .obj/Handle_Ops.o: Handle_Ops.cpp \ +.obj/Handle_Ops.o .obj/Handle_Ops.so .shobj/Handle_Ops.o .shobj/Handle_Ops.so: Handle_Ops.cpp \ Handle_Ops.h \ pre.h \ OS.h \ @@ -1068,7 +1070,7 @@ endif # GHS OS.i \ Handle_Ops.i -.obj/Lib_Find.o .obj/Lib_Find.o .obj/Lib_Find.o .obj/Lib_Find.o: Lib_Find.cpp \ +.obj/Lib_Find.o .obj/Lib_Find.so .shobj/Lib_Find.o .shobj/Lib_Find.so: Lib_Find.cpp \ Lib_Find.h \ pre.h \ OS.h \ @@ -1106,7 +1108,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Sock_Connect.o .obj/Sock_Connect.o .obj/Sock_Connect.o .obj/Sock_Connect.o: Sock_Connect.cpp \ +.obj/Sock_Connect.o .obj/Sock_Connect.so .shobj/Sock_Connect.o .shobj/Sock_Connect.so: Sock_Connect.cpp \ Sock_Connect.h \ pre.h \ OS.h \ @@ -1163,7 +1165,7 @@ endif # GHS Auto_Ptr.i \ Auto_Ptr.cpp -.obj/Malloc_Instantiations.o .obj/Malloc_Instantiations.o .obj/Malloc_Instantiations.o .obj/Malloc_Instantiations.o: Malloc_Instantiations.cpp \ +.obj/Malloc_Instantiations.o .obj/Malloc_Instantiations.so .shobj/Malloc_Instantiations.o .shobj/Malloc_Instantiations.so: Malloc_Instantiations.cpp \ Malloc.h \ pre.h \ ACE.h \ @@ -1251,7 +1253,7 @@ endif # GHS SV_Semaphore_Complex.i \ Memory_Pool.i -.obj/Active_Map_Manager.o .obj/Active_Map_Manager.o .obj/Active_Map_Manager.o .obj/Active_Map_Manager.o: Active_Map_Manager.cpp \ +.obj/Active_Map_Manager.o .obj/Active_Map_Manager.so .shobj/Active_Map_Manager.o .shobj/Active_Map_Manager.so: Active_Map_Manager.cpp \ Active_Map_Manager.h \ pre.h \ OS.h \ @@ -1368,7 +1370,7 @@ endif # GHS Active_Map_Manager_T.i \ Active_Map_Manager_T.cpp -.obj/Arg_Shifter.o .obj/Arg_Shifter.o .obj/Arg_Shifter.o .obj/Arg_Shifter.o: Arg_Shifter.cpp \ +.obj/Arg_Shifter.o .obj/Arg_Shifter.so .shobj/Arg_Shifter.o .shobj/Arg_Shifter.so: Arg_Shifter.cpp \ Arg_Shifter.h \ pre.h \ OS.h \ @@ -1399,7 +1401,7 @@ endif # GHS Trace.h \ OS.i -.obj/ARGV.o .obj/ARGV.o .obj/ARGV.o .obj/ARGV.o: ARGV.cpp \ +.obj/ARGV.o .obj/ARGV.so .shobj/ARGV.o .shobj/ARGV.so: ARGV.cpp \ ARGV.h \ pre.h \ ACE.h \ @@ -1489,7 +1491,7 @@ endif # GHS Memory_Pool.i \ ARGV.i -.obj/Capabilities.o .obj/Capabilities.o .obj/Capabilities.o .obj/Capabilities.o: Capabilities.cpp \ +.obj/Capabilities.o .obj/Capabilities.so .shobj/Capabilities.o .shobj/Capabilities.so: Capabilities.cpp \ Map_Manager.h \ pre.h \ OS.h \ @@ -1612,7 +1614,7 @@ endif # GHS Hash_Map_Manager_T.cpp \ Capabilities.i -.obj/Containers.o .obj/Containers.o .obj/Containers.o .obj/Containers.o: Containers.cpp \ +.obj/Containers.o .obj/Containers.so .shobj/Containers.o .shobj/Containers.so: Containers.cpp \ OS.h \ pre.h \ config-all.h \ @@ -1700,7 +1702,7 @@ endif # GHS SV_Semaphore_Complex.i \ Memory_Pool.i -.obj/Configuration.o .obj/Configuration.o .obj/Configuration.o .obj/Configuration.o: Configuration.cpp \ +.obj/Configuration.o .obj/Configuration.so .shobj/Configuration.o .shobj/Configuration.so: Configuration.cpp \ Configuration.h \ pre.h \ ACE.h \ @@ -1822,7 +1824,7 @@ endif # GHS Hash_Map_With_Allocator_T.i \ Hash_Map_With_Allocator_T.cpp -.obj/Dirent.o .obj/Dirent.o .obj/Dirent.o .obj/Dirent.o: Dirent.cpp \ +.obj/Dirent.o .obj/Dirent.so .shobj/Dirent.o .shobj/Dirent.so: Dirent.cpp \ Dirent.h \ pre.h \ OS_Dirent.h \ @@ -1860,7 +1862,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Dynamic.o .obj/Dynamic.o .obj/Dynamic.o .obj/Dynamic.o: Dynamic.cpp \ +.obj/Dynamic.o .obj/Dynamic.so .shobj/Dynamic.o .shobj/Dynamic.so: Dynamic.cpp \ Dynamic.h \ pre.h \ ACE.h \ @@ -1930,7 +1932,7 @@ endif # GHS Managed_Object.cpp \ Dynamic.i -.obj/Functor.o .obj/Functor.o .obj/Functor.o .obj/Functor.o: Functor.cpp \ +.obj/Functor.o .obj/Functor.so .shobj/Functor.o .shobj/Functor.so: Functor.cpp \ Functor_T.h \ pre.h \ Functor.h \ @@ -1977,7 +1979,7 @@ endif # GHS Functor_T.i \ Functor_T.cpp -.obj/Get_Opt.o .obj/Get_Opt.o .obj/Get_Opt.o .obj/Get_Opt.o: Get_Opt.cpp \ +.obj/Get_Opt.o .obj/Get_Opt.so .shobj/Get_Opt.o .shobj/Get_Opt.so: Get_Opt.cpp \ Get_Opt.h \ pre.h \ ACE.h \ @@ -2027,7 +2029,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Hash_Map_Manager.o .obj/Hash_Map_Manager.o .obj/Hash_Map_Manager.o .obj/Hash_Map_Manager.o: Hash_Map_Manager.cpp \ +.obj/Hash_Map_Manager.o .obj/Hash_Map_Manager.so .shobj/Hash_Map_Manager.o .shobj/Hash_Map_Manager.so: Hash_Map_Manager.cpp \ Hash_Map_Manager.h \ pre.h \ OS.h \ @@ -2145,7 +2147,7 @@ endif # GHS Reactor_Impl.h \ Svc_Conf_Tokens.h -.obj/High_Res_Timer.o .obj/High_Res_Timer.o .obj/High_Res_Timer.o .obj/High_Res_Timer.o: High_Res_Timer.cpp \ +.obj/High_Res_Timer.o .obj/High_Res_Timer.so .shobj/High_Res_Timer.o .shobj/High_Res_Timer.so: High_Res_Timer.cpp \ High_Res_Timer.h \ pre.h \ ACE.h \ @@ -2244,7 +2246,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Method_Request.o .obj/Method_Request.o .obj/Method_Request.o .obj/Method_Request.o: Method_Request.cpp \ +.obj/Method_Request.o .obj/Method_Request.so .shobj/Method_Request.o .shobj/Method_Request.so: Method_Request.cpp \ Method_Request.h \ pre.h \ OS.h \ @@ -2275,7 +2277,7 @@ endif # GHS Trace.h \ OS.i -.obj/Object_Manager.o .obj/Object_Manager.o .obj/Object_Manager.o .obj/Object_Manager.o: Object_Manager.cpp \ +.obj/Object_Manager.o .obj/Object_Manager.so .shobj/Object_Manager.o .shobj/Object_Manager.so: Object_Manager.cpp \ Object_Manager.h \ pre.h \ OS.h \ @@ -2416,7 +2418,7 @@ endif # GHS SOCK_Acceptor.i \ Service_Manager.i -.obj/Profile_Timer.o .obj/Profile_Timer.o .obj/Profile_Timer.o .obj/Profile_Timer.o: Profile_Timer.cpp \ +.obj/Profile_Timer.o .obj/Profile_Timer.so .shobj/Profile_Timer.o .shobj/Profile_Timer.so: Profile_Timer.cpp \ Profile_Timer.h \ pre.h \ ACE.h \ @@ -2463,7 +2465,7 @@ endif # GHS High_Res_Timer.i \ Profile_Timer.i -.obj/Registry.o .obj/Registry.o .obj/Registry.o .obj/Registry.o: Registry.cpp \ +.obj/Registry.o .obj/Registry.so .shobj/Registry.o .shobj/Registry.so: Registry.cpp \ Registry.h \ pre.h \ OS.h \ @@ -2494,7 +2496,7 @@ endif # GHS Trace.h \ OS.i -.obj/SString.o .obj/SString.o .obj/SString.o .obj/SString.o: SString.cpp \ +.obj/SString.o .obj/SString.so .shobj/SString.o .shobj/SString.so: SString.cpp \ Malloc.h \ pre.h \ ACE.h \ @@ -2606,7 +2608,7 @@ endif # GHS Auto_Ptr.i \ Auto_Ptr.cpp -.obj/Stats.o .obj/Stats.o .obj/Stats.o .obj/Stats.o: Stats.cpp \ +.obj/Stats.o .obj/Stats.so .shobj/Stats.o .shobj/Stats.so: Stats.cpp \ Stats.h \ pre.h \ ACE.h \ @@ -2698,7 +2700,7 @@ endif # GHS Basic_Stats.inl \ Stats.i -.obj/Sample_History.o .obj/Sample_History.o .obj/Sample_History.o .obj/Sample_History.o: Sample_History.cpp \ +.obj/Sample_History.o .obj/Sample_History.so .shobj/Sample_History.o .shobj/Sample_History.so: Sample_History.cpp \ Sample_History.h \ pre.h \ config-all.h \ @@ -2738,7 +2740,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Basic_Stats.o .obj/Basic_Stats.o .obj/Basic_Stats.o .obj/Basic_Stats.o: Basic_Stats.cpp \ +.obj/Basic_Stats.o .obj/Basic_Stats.so .shobj/Basic_Stats.o .shobj/Basic_Stats.so: Basic_Stats.cpp \ Basic_Stats.h \ pre.h \ config-all.h \ @@ -2776,7 +2778,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/System_Time.o .obj/System_Time.o .obj/System_Time.o .obj/System_Time.o: System_Time.cpp \ +.obj/System_Time.o .obj/System_Time.so .shobj/System_Time.o .shobj/System_Time.so: System_Time.cpp \ System_Time.h \ pre.h \ OS.h \ @@ -2865,7 +2867,7 @@ endif # GHS SV_Semaphore_Complex.i \ Memory_Pool.i -.obj/Time_Request_Reply.o .obj/Time_Request_Reply.o .obj/Time_Request_Reply.o .obj/Time_Request_Reply.o: Time_Request_Reply.cpp \ +.obj/Time_Request_Reply.o .obj/Time_Request_Reply.so .shobj/Time_Request_Reply.o .shobj/Time_Request_Reply.so: Time_Request_Reply.cpp \ Time_Request_Reply.h \ pre.h \ Time_Value.h \ @@ -2918,7 +2920,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Timeprobe.o .obj/Timeprobe.o .obj/Timeprobe.o .obj/Timeprobe.o: Timeprobe.cpp \ +.obj/Timeprobe.o .obj/Timeprobe.so .shobj/Timeprobe.o .shobj/Timeprobe.so: Timeprobe.cpp \ OS.h \ pre.h \ config-all.h \ @@ -2948,7 +2950,7 @@ endif # GHS Trace.h \ OS.i -.obj/Timer_Hash.o .obj/Timer_Hash.o .obj/Timer_Hash.o .obj/Timer_Hash.o: Timer_Hash.cpp \ +.obj/Timer_Hash.o .obj/Timer_Hash.so .shobj/Timer_Hash.o .shobj/Timer_Hash.so: Timer_Hash.cpp \ Timer_Hash.h \ pre.h \ Timer_Hash_T.h \ @@ -3051,7 +3053,7 @@ endif # GHS Timer_List_T.h \ Timer_List_T.cpp -.obj/Timer_Heap.o .obj/Timer_Heap.o .obj/Timer_Heap.o .obj/Timer_Heap.o: Timer_Heap.cpp \ +.obj/Timer_Heap.o .obj/Timer_Heap.so .shobj/Timer_Heap.o .shobj/Timer_Heap.so: Timer_Heap.cpp \ Timer_Heap.h \ pre.h \ Timer_Heap_T.h \ @@ -3148,7 +3150,7 @@ endif # GHS Signal.i \ Timer_Heap_T.cpp -.obj/Timer_List.o .obj/Timer_List.o .obj/Timer_List.o .obj/Timer_List.o: Timer_List.cpp \ +.obj/Timer_List.o .obj/Timer_List.so .shobj/Timer_List.o .shobj/Timer_List.so: Timer_List.cpp \ Timer_List.h \ pre.h \ Timer_List_T.h \ @@ -3245,7 +3247,7 @@ endif # GHS Signal.i \ Timer_List_T.cpp -.obj/Timer_Queue.o .obj/Timer_Queue.o .obj/Timer_Queue.o .obj/Timer_Queue.o: Timer_Queue.cpp \ +.obj/Timer_Queue.o .obj/Timer_Queue.so .shobj/Timer_Queue.o .shobj/Timer_Queue.so: Timer_Queue.cpp \ Containers.h \ pre.h \ OS.h \ @@ -3340,7 +3342,7 @@ endif # GHS Timer_Queue_T.i \ Timer_Queue_T.cpp -.obj/Timer_Wheel.o .obj/Timer_Wheel.o .obj/Timer_Wheel.o .obj/Timer_Wheel.o: Timer_Wheel.cpp \ +.obj/Timer_Wheel.o .obj/Timer_Wheel.so .shobj/Timer_Wheel.o .shobj/Timer_Wheel.so: Timer_Wheel.cpp \ Timer_Wheel.h \ pre.h \ Timer_Wheel_T.h \ @@ -3439,7 +3441,7 @@ endif # GHS High_Res_Timer.h \ High_Res_Timer.i -.obj/Filecache.o .obj/Filecache.o .obj/Filecache.o .obj/Filecache.o: Filecache.cpp \ +.obj/Filecache.o .obj/Filecache.so .shobj/Filecache.o .shobj/Filecache.so: Filecache.cpp \ Filecache.h \ pre.h \ Mem_Map.h \ @@ -3563,7 +3565,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Dump.o .obj/Dump.o .obj/Dump.o .obj/Dump.o: Dump.cpp \ +.obj/Dump.o .obj/Dump.so .shobj/Dump.o .shobj/Dump.so: Dump.cpp \ Synch_T.h \ pre.h \ Synch.h \ @@ -3631,7 +3633,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Log_Msg.o .obj/Log_Msg.o .obj/Log_Msg.o .obj/Log_Msg.o: Log_Msg.cpp \ +.obj/Log_Msg.o .obj/Log_Msg.so .shobj/Log_Msg.o .shobj/Log_Msg.so: Log_Msg.cpp \ config-all.h \ pre.h \ config.h \ @@ -3748,7 +3750,7 @@ endif # GHS Time_Value.h \ SOCK_Connector.i -.obj/Log_Msg_Callback.o .obj/Log_Msg_Callback.o .obj/Log_Msg_Callback.o .obj/Log_Msg_Callback.o: Log_Msg_Callback.cpp \ +.obj/Log_Msg_Callback.o .obj/Log_Msg_Callback.so .shobj/Log_Msg_Callback.o .shobj/Log_Msg_Callback.so: Log_Msg_Callback.cpp \ Log_Msg_Callback.h \ pre.h \ config-all.h \ @@ -3763,7 +3765,7 @@ endif # GHS ace_wchar.h \ ace_wchar.inl -.obj/Log_Msg_Backend.o .obj/Log_Msg_Backend.o .obj/Log_Msg_Backend.o .obj/Log_Msg_Backend.o: Log_Msg_Backend.cpp \ +.obj/Log_Msg_Backend.o .obj/Log_Msg_Backend.so .shobj/Log_Msg_Backend.o .shobj/Log_Msg_Backend.so: Log_Msg_Backend.cpp \ Log_Msg_Backend.h \ pre.h \ config-all.h \ @@ -3778,7 +3780,7 @@ endif # GHS ace_wchar.h \ ace_wchar.inl -.obj/Log_Msg_IPC.o .obj/Log_Msg_IPC.o .obj/Log_Msg_IPC.o .obj/Log_Msg_IPC.o: Log_Msg_IPC.cpp \ +.obj/Log_Msg_IPC.o .obj/Log_Msg_IPC.so .shobj/Log_Msg_IPC.o .shobj/Log_Msg_IPC.so: Log_Msg_IPC.cpp \ Log_Msg_IPC.h \ pre.h \ Log_Msg_Backend.h \ @@ -3841,7 +3843,7 @@ endif # GHS Log_Priority.h \ Log_Record.i -.obj/Log_Record.o .obj/Log_Record.o .obj/Log_Record.o .obj/Log_Record.o: Log_Record.cpp \ +.obj/Log_Record.o .obj/Log_Record.so .shobj/Log_Record.o .shobj/Log_Record.so: Log_Record.cpp \ Log_Record.h \ OS.h \ pre.h \ @@ -3889,7 +3891,7 @@ endif # GHS Sock_Connect.i \ ACE.i -.obj/Logging_Strategy.o .obj/Logging_Strategy.o .obj/Logging_Strategy.o .obj/Logging_Strategy.o: Logging_Strategy.cpp \ +.obj/Logging_Strategy.o .obj/Logging_Strategy.so .shobj/Logging_Strategy.o .shobj/Logging_Strategy.so: Logging_Strategy.cpp \ Get_Opt.h \ pre.h \ ACE.h \ @@ -3996,7 +3998,7 @@ endif # GHS Shared_Object.i \ Service_Object.i -.obj/Trace.o .obj/Trace.o .obj/Trace.o .obj/Trace.o: Trace.cpp \ +.obj/Trace.o .obj/Trace.so .shobj/Trace.o .shobj/Trace.so: Trace.cpp \ config-all.h \ pre.h \ config.h \ @@ -4032,7 +4034,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Activation_Queue.o .obj/Activation_Queue.o .obj/Activation_Queue.o .obj/Activation_Queue.o: Activation_Queue.cpp \ +.obj/Activation_Queue.o .obj/Activation_Queue.so .shobj/Activation_Queue.o .shobj/Activation_Queue.so: Activation_Queue.cpp \ Activation_Queue.h \ pre.h \ Synch_T.h \ @@ -4189,7 +4191,7 @@ endif # GHS Method_Request.h \ Activation_Queue.i -.obj/Process.o .obj/Process.o .obj/Process.o .obj/Process.o: Process.cpp \ +.obj/Process.o .obj/Process.so .shobj/Process.o .shobj/Process.so: Process.cpp \ OS.h \ pre.h \ config-all.h \ @@ -4283,7 +4285,7 @@ endif # GHS Memory_Pool.i \ ARGV.i -.obj/Process_Manager.o .obj/Process_Manager.o .obj/Process_Manager.o .obj/Process_Manager.o: Process_Manager.cpp \ +.obj/Process_Manager.o .obj/Process_Manager.so .shobj/Process_Manager.o .shobj/Process_Manager.so: Process_Manager.cpp \ Synch_T.h \ pre.h \ Synch.h \ @@ -4394,7 +4396,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Synch.o .obj/Synch.o .obj/Synch.o .obj/Synch.o: Synch.cpp \ +.obj/Synch.o .obj/Synch.so .shobj/Synch.o .shobj/Synch.so: Synch.cpp \ Thread.h \ pre.h \ ACE.h \ @@ -4454,7 +4456,7 @@ endif # GHS Log_Priority.h \ Log_Record.i -.obj/Synch_Options.o .obj/Synch_Options.o .obj/Synch_Options.o .obj/Synch_Options.o: Synch_Options.cpp \ +.obj/Synch_Options.o .obj/Synch_Options.so .shobj/Synch_Options.o .shobj/Synch_Options.so: Synch_Options.cpp \ Synch_Options.h \ pre.h \ ACE.h \ @@ -4498,7 +4500,7 @@ endif # GHS ACE.i \ Synch_Options.i -.obj/Process_Semaphore.o .obj/Process_Semaphore.o .obj/Process_Semaphore.o .obj/Process_Semaphore.o: Process_Semaphore.cpp \ +.obj/Process_Semaphore.o .obj/Process_Semaphore.so .shobj/Process_Semaphore.o .shobj/Process_Semaphore.so: Process_Semaphore.cpp \ Process_Semaphore.h \ pre.h \ Synch.h \ @@ -4564,7 +4566,7 @@ endif # GHS SV_Semaphore_Complex.i \ Process_Semaphore.inl -.obj/Process_Mutex.o .obj/Process_Mutex.o .obj/Process_Mutex.o .obj/Process_Mutex.o: Process_Mutex.cpp \ +.obj/Process_Mutex.o .obj/Process_Mutex.so .shobj/Process_Mutex.o .shobj/Process_Mutex.so: Process_Mutex.cpp \ Process_Mutex.h \ pre.h \ config-all.h \ @@ -4630,7 +4632,7 @@ endif # GHS Log_Priority.h \ Log_Record.i -.obj/RW_Process_Mutex.o .obj/RW_Process_Mutex.o .obj/RW_Process_Mutex.o .obj/RW_Process_Mutex.o: RW_Process_Mutex.cpp \ +.obj/RW_Process_Mutex.o .obj/RW_Process_Mutex.so .shobj/RW_Process_Mutex.o .shobj/RW_Process_Mutex.so: RW_Process_Mutex.cpp \ RW_Process_Mutex.h \ pre.h \ File_Lock.h \ @@ -4670,7 +4672,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/File_Lock.o .obj/File_Lock.o .obj/File_Lock.o .obj/File_Lock.o: File_Lock.cpp \ +.obj/File_Lock.o .obj/File_Lock.so .shobj/File_Lock.o .shobj/File_Lock.so: File_Lock.cpp \ File_Lock.h \ pre.h \ OS.h \ @@ -4708,7 +4710,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Thread.o .obj/Thread.o .obj/Thread.o .obj/Thread.o: Thread.cpp \ +.obj/Thread.o .obj/Thread.so .shobj/Thread.o .shobj/Thread.so: Thread.cpp \ Thread.h \ pre.h \ ACE.h \ @@ -4758,7 +4760,7 @@ endif # GHS Thread_Adapter.inl \ Thread.i -.obj/Thread_Manager.o .obj/Thread_Manager.o .obj/Thread_Manager.o .obj/Thread_Manager.o: Thread_Manager.cpp \ +.obj/Thread_Manager.o .obj/Thread_Manager.so .shobj/Thread_Manager.o .shobj/Thread_Manager.so: Thread_Manager.cpp \ Synch_T.h \ pre.h \ Synch.h \ @@ -4864,7 +4866,7 @@ endif # GHS Thread_Control.h \ Thread_Control.inl -.obj/Thread_Adapter.o .obj/Thread_Adapter.o .obj/Thread_Adapter.o .obj/Thread_Adapter.o: Thread_Adapter.cpp \ +.obj/Thread_Adapter.o .obj/Thread_Adapter.so .shobj/Thread_Adapter.o .shobj/Thread_Adapter.so: Thread_Adapter.cpp \ Thread_Adapter.h \ pre.h \ Base_Thread_Adapter.h \ @@ -4966,7 +4968,7 @@ endif # GHS Thread_Control.inl \ Thread_Hook.h -.obj/Thread_Exit.o .obj/Thread_Exit.o .obj/Thread_Exit.o .obj/Thread_Exit.o: Thread_Exit.cpp \ +.obj/Thread_Exit.o .obj/Thread_Exit.so .shobj/Thread_Exit.o .shobj/Thread_Exit.so: Thread_Exit.cpp \ Thread_Exit.h \ pre.h \ config-all.h \ @@ -5034,7 +5036,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Thread_Control.o .obj/Thread_Control.o .obj/Thread_Control.o .obj/Thread_Control.o: Thread_Control.cpp \ +.obj/Thread_Control.o .obj/Thread_Control.so .shobj/Thread_Control.o .shobj/Thread_Control.so: Thread_Control.cpp \ config-all.h \ pre.h \ config.h \ @@ -5134,7 +5136,7 @@ endif # GHS Managed_Object.cpp \ Thread_Manager.i -.obj/Token.o .obj/Token.o .obj/Token.o .obj/Token.o: Token.cpp \ +.obj/Token.o .obj/Token.so .shobj/Token.o .shobj/Token.so: Token.cpp \ Thread.h \ pre.h \ ACE.h \ @@ -5196,7 +5198,7 @@ endif # GHS Log_Record.i \ Token.i -.obj/Event_Handler.o .obj/Event_Handler.o .obj/Event_Handler.o .obj/Event_Handler.o: Event_Handler.cpp \ +.obj/Event_Handler.o .obj/Event_Handler.so .shobj/Event_Handler.o .shobj/Event_Handler.so: Event_Handler.cpp \ Event_Handler.h \ pre.h \ ACE.h \ @@ -5311,7 +5313,7 @@ endif # GHS Managed_Object.cpp \ Thread_Manager.i -.obj/FlReactor.o .obj/FlReactor.o .obj/FlReactor.o .obj/FlReactor.o: FlReactor.cpp \ +.obj/FlReactor.o .obj/FlReactor.so .shobj/FlReactor.o .shobj/FlReactor.so: FlReactor.cpp \ FlReactor.h \ pre.h \ Select_Reactor.h \ @@ -5425,7 +5427,7 @@ endif # GHS Timer_Heap_T.cpp \ Select_Reactor_T.i -.obj/Handle_Set.o .obj/Handle_Set.o .obj/Handle_Set.o .obj/Handle_Set.o: Handle_Set.cpp \ +.obj/Handle_Set.o .obj/Handle_Set.so .shobj/Handle_Set.o .shobj/Handle_Set.so: Handle_Set.cpp \ Handle_Set.h \ pre.h \ ACE.h \ @@ -5475,7 +5477,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Msg_WFMO_Reactor.o .obj/Msg_WFMO_Reactor.o .obj/Msg_WFMO_Reactor.o .obj/Msg_WFMO_Reactor.o: Msg_WFMO_Reactor.cpp \ +.obj/Msg_WFMO_Reactor.o .obj/Msg_WFMO_Reactor.so .shobj/Msg_WFMO_Reactor.o .shobj/Msg_WFMO_Reactor.so: Msg_WFMO_Reactor.cpp \ Msg_WFMO_Reactor.h \ pre.h \ WFMO_Reactor.h \ @@ -5631,7 +5633,7 @@ endif # GHS WFMO_Reactor.i \ Msg_WFMO_Reactor.i -.obj/POSIX_Proactor.o .obj/POSIX_Proactor.o .obj/POSIX_Proactor.o .obj/POSIX_Proactor.o: POSIX_Proactor.cpp \ +.obj/POSIX_Proactor.o .obj/POSIX_Proactor.so .shobj/POSIX_Proactor.o .shobj/POSIX_Proactor.so: POSIX_Proactor.cpp \ POSIX_Proactor.h \ Proactor_Impl.h \ pre.h \ @@ -5663,7 +5665,7 @@ endif # GHS Trace.h \ OS.i -.obj/Priority_Reactor.o .obj/Priority_Reactor.o .obj/Priority_Reactor.o .obj/Priority_Reactor.o: Priority_Reactor.cpp \ +.obj/Priority_Reactor.o .obj/Priority_Reactor.so .shobj/Priority_Reactor.o .shobj/Priority_Reactor.so: Priority_Reactor.cpp \ Priority_Reactor.h \ pre.h \ Containers.h \ @@ -5777,7 +5779,7 @@ endif # GHS Timer_Heap_T.cpp \ Select_Reactor_T.i -.obj/Proactor.o .obj/Proactor.o .obj/Proactor.o .obj/Proactor.o: Proactor.cpp \ +.obj/Proactor.o .obj/Proactor.so .shobj/Proactor.o .shobj/Proactor.so: Proactor.cpp \ Proactor.h \ pre.h \ OS.h \ @@ -5943,7 +5945,7 @@ endif # GHS Stream_Modules.h \ Stream_Modules.cpp -.obj/Reactor.o .obj/Reactor.o .obj/Reactor.o .obj/Reactor.o: Reactor.cpp \ +.obj/Reactor.o .obj/Reactor.so .shobj/Reactor.o .shobj/Reactor.so: Reactor.cpp \ Reactor.h \ pre.h \ Handle_Set.h \ @@ -6114,7 +6116,7 @@ endif # GHS TP_Reactor.h \ TP_Reactor.i -.obj/Select_Reactor.o .obj/Select_Reactor.o .obj/Select_Reactor.o .obj/Select_Reactor.o: Select_Reactor.cpp \ +.obj/Select_Reactor.o .obj/Select_Reactor.so .shobj/Select_Reactor.o .shobj/Select_Reactor.so: Select_Reactor.cpp \ Select_Reactor.h \ pre.h \ Select_Reactor_T.h \ @@ -6227,7 +6229,7 @@ endif # GHS Timer_Heap_T.cpp \ Select_Reactor_T.i -.obj/Select_Reactor_Base.o .obj/Select_Reactor_Base.o .obj/Select_Reactor_Base.o .obj/Select_Reactor_Base.o: Select_Reactor_Base.cpp \ +.obj/Select_Reactor_Base.o .obj/Select_Reactor_Base.so .shobj/Select_Reactor_Base.o .shobj/Select_Reactor_Base.so: Select_Reactor_Base.cpp \ Select_Reactor_Base.h \ pre.h \ Signal.h \ @@ -6354,7 +6356,7 @@ endif # GHS Timer_Heap_T.h \ Timer_Heap_T.cpp -.obj/SUN_Proactor.o .obj/SUN_Proactor.o .obj/SUN_Proactor.o .obj/SUN_Proactor.o: SUN_Proactor.cpp \ +.obj/SUN_Proactor.o .obj/SUN_Proactor.so .shobj/SUN_Proactor.o .shobj/SUN_Proactor.so: SUN_Proactor.cpp \ SUN_Proactor.h \ POSIX_Proactor.h \ Proactor_Impl.h \ @@ -6387,7 +6389,7 @@ endif # GHS Trace.h \ OS.i -.obj/TP_Reactor.o .obj/TP_Reactor.o .obj/TP_Reactor.o .obj/TP_Reactor.o: TP_Reactor.cpp \ +.obj/TP_Reactor.o .obj/TP_Reactor.so .shobj/TP_Reactor.o .shobj/TP_Reactor.so: TP_Reactor.cpp \ TP_Reactor.h \ pre.h \ Select_Reactor.h \ @@ -6502,7 +6504,7 @@ endif # GHS Select_Reactor_T.i \ TP_Reactor.i -.obj/TkReactor.o .obj/TkReactor.o .obj/TkReactor.o .obj/TkReactor.o: TkReactor.cpp \ +.obj/TkReactor.o .obj/TkReactor.so .shobj/TkReactor.o .shobj/TkReactor.so: TkReactor.cpp \ Synch_T.h \ pre.h \ Synch.h \ @@ -6634,7 +6636,7 @@ endif # GHS Timer_Heap_T.cpp \ Select_Reactor_T.i -.obj/WFMO_Reactor.o .obj/WFMO_Reactor.o .obj/WFMO_Reactor.o .obj/WFMO_Reactor.o: WFMO_Reactor.cpp \ +.obj/WFMO_Reactor.o .obj/WFMO_Reactor.so .shobj/WFMO_Reactor.o .shobj/WFMO_Reactor.so: WFMO_Reactor.cpp \ WFMO_Reactor.h \ pre.h \ Signal.h \ @@ -6791,7 +6793,7 @@ endif # GHS Timer_Heap_T.h \ Timer_Heap_T.cpp -.obj/XtReactor.o .obj/XtReactor.o .obj/XtReactor.o .obj/XtReactor.o: XtReactor.cpp \ +.obj/XtReactor.o .obj/XtReactor.so .shobj/XtReactor.o .shobj/XtReactor.so: XtReactor.cpp \ Synch_T.h \ pre.h \ Synch.h \ @@ -6923,7 +6925,7 @@ endif # GHS Timer_Heap_T.cpp \ Select_Reactor_T.i -.obj/QtReactor.o .obj/QtReactor.o .obj/QtReactor.o .obj/QtReactor.o: QtReactor.cpp \ +.obj/QtReactor.o .obj/QtReactor.so .shobj/QtReactor.o .shobj/QtReactor.so: QtReactor.cpp \ QtReactor.h \ pre.h \ Select_Reactor.h \ @@ -7037,7 +7039,7 @@ endif # GHS Timer_Heap_T.cpp \ Select_Reactor_T.i -.obj/Asynch_IO.o .obj/Asynch_IO.o .obj/Asynch_IO.o .obj/Asynch_IO.o: Asynch_IO.cpp \ +.obj/Asynch_IO.o .obj/Asynch_IO.so .shobj/Asynch_IO.o .shobj/Asynch_IO.so: Asynch_IO.cpp \ Asynch_IO.h \ pre.h \ OS.h \ @@ -7068,7 +7070,7 @@ endif # GHS Trace.h \ OS.i -.obj/Asynch_IO_Impl.o .obj/Asynch_IO_Impl.o .obj/Asynch_IO_Impl.o .obj/Asynch_IO_Impl.o: Asynch_IO_Impl.cpp \ +.obj/Asynch_IO_Impl.o .obj/Asynch_IO_Impl.so .shobj/Asynch_IO_Impl.o .shobj/Asynch_IO_Impl.so: Asynch_IO_Impl.cpp \ OS.h \ pre.h \ config-all.h \ @@ -7099,7 +7101,7 @@ endif # GHS OS.i \ Asynch_IO_Impl.h -.obj/POSIX_Asynch_IO.o .obj/POSIX_Asynch_IO.o .obj/POSIX_Asynch_IO.o .obj/POSIX_Asynch_IO.o: POSIX_Asynch_IO.cpp \ +.obj/POSIX_Asynch_IO.o .obj/POSIX_Asynch_IO.so .shobj/POSIX_Asynch_IO.o .shobj/POSIX_Asynch_IO.so: POSIX_Asynch_IO.cpp \ POSIX_Asynch_IO.h \ OS.h \ pre.h \ @@ -7130,7 +7132,7 @@ endif # GHS Trace.h \ OS.i -.obj/Strategies.o .obj/Strategies.o .obj/Strategies.o .obj/Strategies.o: Strategies.cpp \ +.obj/Strategies.o .obj/Strategies.so .shobj/Strategies.o .shobj/Strategies.so: Strategies.cpp \ Reactor.h \ pre.h \ Handle_Set.h \ @@ -7284,7 +7286,7 @@ endif # GHS WFMO_Reactor.i \ Strategies.i -.obj/IPC_SAP.o .obj/IPC_SAP.o .obj/IPC_SAP.o .obj/IPC_SAP.o: IPC_SAP.cpp \ +.obj/IPC_SAP.o .obj/IPC_SAP.so .shobj/IPC_SAP.o .shobj/IPC_SAP.so: IPC_SAP.cpp \ IPC_SAP.h \ pre.h \ Flag_Manip.h \ @@ -7324,7 +7326,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/LSOCK.o .obj/LSOCK.o .obj/LSOCK.o .obj/LSOCK.o: LSOCK.cpp \ +.obj/LSOCK.o .obj/LSOCK.so .shobj/LSOCK.o .shobj/LSOCK.so: LSOCK.cpp \ LSOCK.h \ pre.h \ SOCK.h \ @@ -7383,7 +7385,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/LSOCK_Acceptor.o .obj/LSOCK_Acceptor.o .obj/LSOCK_Acceptor.o .obj/LSOCK_Acceptor.o: LSOCK_Acceptor.cpp \ +.obj/LSOCK_Acceptor.o .obj/LSOCK_Acceptor.so .shobj/LSOCK_Acceptor.o .shobj/LSOCK_Acceptor.so: LSOCK_Acceptor.cpp \ LSOCK_Acceptor.h \ pre.h \ SOCK_Acceptor.h \ @@ -7454,7 +7456,7 @@ endif # GHS LSOCK.i \ LSOCK_Stream.i -.obj/LSOCK_CODgram.o .obj/LSOCK_CODgram.o .obj/LSOCK_CODgram.o .obj/LSOCK_CODgram.o: LSOCK_CODgram.cpp \ +.obj/LSOCK_CODgram.o .obj/LSOCK_CODgram.so .shobj/LSOCK_CODgram.o .shobj/LSOCK_CODgram.so: LSOCK_CODgram.cpp \ LSOCK_CODgram.h \ pre.h \ LSOCK.h \ @@ -7519,7 +7521,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/LSOCK_Connector.o .obj/LSOCK_Connector.o .obj/LSOCK_Connector.o .obj/LSOCK_Connector.o: LSOCK_Connector.cpp \ +.obj/LSOCK_Connector.o .obj/LSOCK_Connector.so .shobj/LSOCK_Connector.o .shobj/LSOCK_Connector.so: LSOCK_Connector.cpp \ LSOCK_Connector.h \ pre.h \ SOCK_Connector.h \ @@ -7591,7 +7593,7 @@ endif # GHS LSOCK_Stream.i \ LSOCK_Connector.i -.obj/LSOCK_Dgram.o .obj/LSOCK_Dgram.o .obj/LSOCK_Dgram.o .obj/LSOCK_Dgram.o: LSOCK_Dgram.cpp \ +.obj/LSOCK_Dgram.o .obj/LSOCK_Dgram.so .shobj/LSOCK_Dgram.o .shobj/LSOCK_Dgram.so: LSOCK_Dgram.cpp \ LSOCK_Dgram.h \ pre.h \ SOCK_Dgram.h \ @@ -7654,7 +7656,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/LSOCK_Stream.o .obj/LSOCK_Stream.o .obj/LSOCK_Stream.o .obj/LSOCK_Stream.o: LSOCK_Stream.cpp \ +.obj/LSOCK_Stream.o .obj/LSOCK_Stream.so .shobj/LSOCK_Stream.o .shobj/LSOCK_Stream.so: LSOCK_Stream.cpp \ LSOCK_Stream.h \ pre.h \ SOCK_Stream.h \ @@ -7721,7 +7723,7 @@ endif # GHS LSOCK.i \ LSOCK_Stream.i -.obj/SOCK.o .obj/SOCK.o .obj/SOCK.o .obj/SOCK.o: SOCK.cpp \ +.obj/SOCK.o .obj/SOCK.so .shobj/SOCK.o .shobj/SOCK.so: SOCK.cpp \ SOCK.h \ pre.h \ ACE.h \ @@ -7778,7 +7780,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/SOCK_Acceptor.o .obj/SOCK_Acceptor.o .obj/SOCK_Acceptor.o .obj/SOCK_Acceptor.o: SOCK_Acceptor.cpp \ +.obj/SOCK_Acceptor.o .obj/SOCK_Acceptor.so .shobj/SOCK_Acceptor.o .shobj/SOCK_Acceptor.so: SOCK_Acceptor.cpp \ SOCK_Acceptor.h \ pre.h \ SOCK_Stream.h \ @@ -7854,7 +7856,7 @@ endif # GHS Atomic_Op.i \ Synch_T.cpp -.obj/SOCK_CODgram.o .obj/SOCK_CODgram.o .obj/SOCK_CODgram.o .obj/SOCK_CODgram.o: SOCK_CODgram.cpp \ +.obj/SOCK_CODgram.o .obj/SOCK_CODgram.so .shobj/SOCK_CODgram.o .shobj/SOCK_CODgram.so: SOCK_CODgram.cpp \ SOCK_CODgram.h \ pre.h \ SOCK_IO.h \ @@ -7915,7 +7917,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/SOCK_Connector.o .obj/SOCK_Connector.o .obj/SOCK_Connector.o .obj/SOCK_Connector.o: SOCK_Connector.cpp \ +.obj/SOCK_Connector.o .obj/SOCK_Connector.so .shobj/SOCK_Connector.o .shobj/SOCK_Connector.so: SOCK_Connector.cpp \ SOCK_Connector.h \ pre.h \ SOCK_Stream.h \ @@ -7979,7 +7981,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/SOCK_Dgram.o .obj/SOCK_Dgram.o .obj/SOCK_Dgram.o .obj/SOCK_Dgram.o: SOCK_Dgram.cpp \ +.obj/SOCK_Dgram.o .obj/SOCK_Dgram.so .shobj/SOCK_Dgram.o .shobj/SOCK_Dgram.so: SOCK_Dgram.cpp \ SOCK_Dgram.h \ pre.h \ SOCK.h \ @@ -8052,7 +8054,7 @@ endif # GHS Log_Priority.h \ Log_Record.i -.obj/SOCK_Dgram_Bcast.o .obj/SOCK_Dgram_Bcast.o .obj/SOCK_Dgram_Bcast.o .obj/SOCK_Dgram_Bcast.o: SOCK_Dgram_Bcast.cpp \ +.obj/SOCK_Dgram_Bcast.o .obj/SOCK_Dgram_Bcast.so .shobj/SOCK_Dgram_Bcast.o .shobj/SOCK_Dgram_Bcast.so: SOCK_Dgram_Bcast.cpp \ SOCK_Dgram_Bcast.h \ pre.h \ INET_Addr.h \ @@ -8113,7 +8115,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/SOCK_Dgram_Mcast.o .obj/SOCK_Dgram_Mcast.o .obj/SOCK_Dgram_Mcast.o .obj/SOCK_Dgram_Mcast.o: SOCK_Dgram_Mcast.cpp \ +.obj/SOCK_Dgram_Mcast.o .obj/SOCK_Dgram_Mcast.so .shobj/SOCK_Dgram_Mcast.o .shobj/SOCK_Dgram_Mcast.so: SOCK_Dgram_Mcast.cpp \ SOCK_Dgram_Mcast.h \ pre.h \ SOCK_Dgram.h \ @@ -8168,7 +8170,7 @@ endif # GHS SOCK_Dgram.i \ SOCK_Dgram_Mcast.i -.obj/SOCK_IO.o .obj/SOCK_IO.o .obj/SOCK_IO.o .obj/SOCK_IO.o: SOCK_IO.cpp \ +.obj/SOCK_IO.o .obj/SOCK_IO.so .shobj/SOCK_IO.o .shobj/SOCK_IO.so: SOCK_IO.cpp \ SOCK_IO.h \ pre.h \ SOCK.h \ @@ -8223,7 +8225,7 @@ endif # GHS Handle_Set.h \ Handle_Set.i -.obj/SOCK_Stream.o .obj/SOCK_Stream.o .obj/SOCK_Stream.o .obj/SOCK_Stream.o: SOCK_Stream.cpp \ +.obj/SOCK_Stream.o .obj/SOCK_Stream.so .shobj/SOCK_Stream.o .shobj/SOCK_Stream.so: SOCK_Stream.cpp \ SOCK_Stream.h \ pre.h \ SOCK_IO.h \ @@ -8278,7 +8280,7 @@ endif # GHS SOCK_IO.i \ SOCK_Stream.i -.obj/Addr.o .obj/Addr.o .obj/Addr.o .obj/Addr.o: Addr.cpp \ +.obj/Addr.o .obj/Addr.so .shobj/Addr.o .shobj/Addr.so: Addr.cpp \ Addr.h \ pre.h \ OS.h \ @@ -8316,7 +8318,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/ATM_Addr.o .obj/ATM_Addr.o .obj/ATM_Addr.o .obj/ATM_Addr.o: ATM_Addr.cpp \ +.obj/ATM_Addr.o .obj/ATM_Addr.so .shobj/ATM_Addr.o .shobj/ATM_Addr.so: ATM_Addr.cpp \ ATM_Addr.h \ pre.h \ ACE.h \ @@ -8368,7 +8370,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/ATM_Acceptor.o .obj/ATM_Acceptor.o .obj/ATM_Acceptor.o .obj/ATM_Acceptor.o: ATM_Acceptor.cpp \ +.obj/ATM_Acceptor.o .obj/ATM_Acceptor.so .shobj/ATM_Acceptor.o .shobj/ATM_Acceptor.so: ATM_Acceptor.cpp \ ATM_Acceptor.h \ pre.h \ Time_Value.h \ @@ -8419,7 +8421,7 @@ endif # GHS ATM_Params.h \ ATM_QoS.h -.obj/ATM_Connector.o .obj/ATM_Connector.o .obj/ATM_Connector.o .obj/ATM_Connector.o: ATM_Connector.cpp \ +.obj/ATM_Connector.o .obj/ATM_Connector.so .shobj/ATM_Connector.o .shobj/ATM_Connector.so: ATM_Connector.cpp \ Handle_Set.h \ pre.h \ ACE.h \ @@ -8471,7 +8473,7 @@ endif # GHS ATM_Params.h \ ATM_QoS.h -.obj/ATM_Params.o .obj/ATM_Params.o .obj/ATM_Params.o .obj/ATM_Params.o: ATM_Params.cpp \ +.obj/ATM_Params.o .obj/ATM_Params.so .shobj/ATM_Params.o .shobj/ATM_Params.so: ATM_Params.cpp \ ATM_Params.h \ pre.h \ ACE.h \ @@ -8514,7 +8516,7 @@ endif # GHS Sock_Connect.i \ ACE.i -.obj/ATM_QoS.o .obj/ATM_QoS.o .obj/ATM_QoS.o .obj/ATM_QoS.o: ATM_QoS.cpp \ +.obj/ATM_QoS.o .obj/ATM_QoS.so .shobj/ATM_QoS.o .shobj/ATM_QoS.so: ATM_QoS.cpp \ ATM_QoS.h \ pre.h \ ACE.h \ @@ -8557,7 +8559,7 @@ endif # GHS Sock_Connect.i \ ACE.i -.obj/ATM_Stream.o .obj/ATM_Stream.o .obj/ATM_Stream.o .obj/ATM_Stream.o: ATM_Stream.cpp \ +.obj/ATM_Stream.o .obj/ATM_Stream.so .shobj/ATM_Stream.o .shobj/ATM_Stream.so: ATM_Stream.cpp \ ATM_Stream.h \ pre.h \ ATM_Addr.h \ @@ -8605,7 +8607,7 @@ endif # GHS ATM_Addr.i \ ATM_Params.h -.obj/XTI_ATM_Mcast.o .obj/XTI_ATM_Mcast.o .obj/XTI_ATM_Mcast.o .obj/XTI_ATM_Mcast.o: XTI_ATM_Mcast.cpp \ +.obj/XTI_ATM_Mcast.o .obj/XTI_ATM_Mcast.so .shobj/XTI_ATM_Mcast.o .shobj/XTI_ATM_Mcast.so: XTI_ATM_Mcast.cpp \ XTI_ATM_Mcast.h \ pre.h \ TLI_Connector.h \ @@ -8665,7 +8667,8 @@ endif # GHS ATM_Addr.h \ ATM_Addr.i -.obj/DEV.o .obj/DEV.o .obj/DEV.o .obj/DEV.o: DEV.cpp DEV.h \ +.obj/DEV.o .obj/DEV.so .shobj/DEV.o .shobj/DEV.so: DEV.cpp \ + DEV.h \ pre.h \ IO_SAP.h \ Flag_Manip.h \ @@ -8717,7 +8720,7 @@ endif # GHS Malloc_Base.h \ DEV.i -.obj/DEV_Addr.o .obj/DEV_Addr.o .obj/DEV_Addr.o .obj/DEV_Addr.o: DEV_Addr.cpp \ +.obj/DEV_Addr.o .obj/DEV_Addr.so .shobj/DEV_Addr.o .shobj/DEV_Addr.so: DEV_Addr.cpp \ DEV_Addr.h \ pre.h \ Addr.h \ @@ -8772,7 +8775,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/DEV_Connector.o .obj/DEV_Connector.o .obj/DEV_Connector.o .obj/DEV_Connector.o: DEV_Connector.cpp \ +.obj/DEV_Connector.o .obj/DEV_Connector.so .shobj/DEV_Connector.o .shobj/DEV_Connector.so: DEV_Connector.cpp \ DEV_Connector.h \ pre.h \ DEV_IO.h \ @@ -8835,7 +8838,7 @@ endif # GHS OS_Log_Msg_Attributes.inl \ DEV_Connector.i -.obj/DEV_IO.o .obj/DEV_IO.o .obj/DEV_IO.o .obj/DEV_IO.o: DEV_IO.cpp \ +.obj/DEV_IO.o .obj/DEV_IO.so .shobj/DEV_IO.o .shobj/DEV_IO.so: DEV_IO.cpp \ DEV_IO.h \ pre.h \ DEV.h \ @@ -8896,7 +8899,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/FIFO.o .obj/FIFO.o .obj/FIFO.o .obj/FIFO.o: FIFO.cpp \ +.obj/FIFO.o .obj/FIFO.so .shobj/FIFO.o .shobj/FIFO.so: FIFO.cpp \ FIFO.h \ pre.h \ IPC_SAP.h \ @@ -8948,7 +8951,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/FIFO_Recv.o .obj/FIFO_Recv.o .obj/FIFO_Recv.o .obj/FIFO_Recv.o: FIFO_Recv.cpp \ +.obj/FIFO_Recv.o .obj/FIFO_Recv.so .shobj/FIFO_Recv.o .shobj/FIFO_Recv.so: FIFO_Recv.cpp \ FIFO_Recv.h \ pre.h \ FIFO.h \ @@ -9002,7 +9005,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/FIFO_Recv_Msg.o .obj/FIFO_Recv_Msg.o .obj/FIFO_Recv_Msg.o .obj/FIFO_Recv_Msg.o: FIFO_Recv_Msg.cpp \ +.obj/FIFO_Recv_Msg.o .obj/FIFO_Recv_Msg.so .shobj/FIFO_Recv_Msg.o .shobj/FIFO_Recv_Msg.so: FIFO_Recv_Msg.cpp \ FIFO_Recv_Msg.h \ pre.h \ FIFO_Recv.h \ @@ -9058,7 +9061,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/FIFO_Send.o .obj/FIFO_Send.o .obj/FIFO_Send.o .obj/FIFO_Send.o: FIFO_Send.cpp \ +.obj/FIFO_Send.o .obj/FIFO_Send.so .shobj/FIFO_Send.o .shobj/FIFO_Send.so: FIFO_Send.cpp \ FIFO_Send.h \ pre.h \ FIFO.h \ @@ -9112,7 +9115,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/FIFO_Send_Msg.o .obj/FIFO_Send_Msg.o .obj/FIFO_Send_Msg.o .obj/FIFO_Send_Msg.o: FIFO_Send_Msg.cpp \ +.obj/FIFO_Send_Msg.o .obj/FIFO_Send_Msg.so .shobj/FIFO_Send_Msg.o .shobj/FIFO_Send_Msg.so: FIFO_Send_Msg.cpp \ FIFO_Send_Msg.h \ pre.h \ FIFO_Send.h \ @@ -9168,7 +9171,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/FILE_Addr.o .obj/FILE_Addr.o .obj/FILE_Addr.o .obj/FILE_Addr.o: FILE_Addr.cpp \ +.obj/FILE_Addr.o .obj/FILE_Addr.so .shobj/FILE_Addr.o .shobj/FILE_Addr.so: FILE_Addr.cpp \ FILE_Addr.h \ pre.h \ Addr.h \ @@ -9223,7 +9226,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/FILE.o .obj/FILE.o .obj/FILE.o .obj/FILE.o: FILE.cpp \ +.obj/FILE.o .obj/FILE.so .shobj/FILE.o .shobj/FILE.so: FILE.cpp \ FILE.h \ pre.h \ IO_SAP.h \ @@ -9276,7 +9279,7 @@ endif # GHS Malloc_Base.h \ FILE.i -.obj/FILE_Connector.o .obj/FILE_Connector.o .obj/FILE_Connector.o .obj/FILE_Connector.o: FILE_Connector.cpp \ +.obj/FILE_Connector.o .obj/FILE_Connector.so .shobj/FILE_Connector.o .shobj/FILE_Connector.so: FILE_Connector.cpp \ FILE_Connector.h \ pre.h \ FILE_IO.h \ @@ -9339,7 +9342,7 @@ endif # GHS OS_Log_Msg_Attributes.inl \ FILE_Connector.i -.obj/FILE_IO.o .obj/FILE_IO.o .obj/FILE_IO.o .obj/FILE_IO.o: FILE_IO.cpp \ +.obj/FILE_IO.o .obj/FILE_IO.so .shobj/FILE_IO.o .shobj/FILE_IO.so: FILE_IO.cpp \ FILE_IO.h \ pre.h \ FILE.h \ @@ -9400,7 +9403,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/INET_Addr.o .obj/INET_Addr.o .obj/INET_Addr.o .obj/INET_Addr.o: INET_Addr.cpp \ +.obj/INET_Addr.o .obj/INET_Addr.so .shobj/INET_Addr.o .shobj/INET_Addr.so: INET_Addr.cpp \ INET_Addr.h \ pre.h \ ACE.h \ @@ -9452,7 +9455,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/IO_SAP.o .obj/IO_SAP.o .obj/IO_SAP.o .obj/IO_SAP.o: IO_SAP.cpp \ +.obj/IO_SAP.o .obj/IO_SAP.so .shobj/IO_SAP.o .shobj/IO_SAP.so: IO_SAP.cpp \ IO_SAP.h \ pre.h \ Flag_Manip.h \ @@ -9492,7 +9495,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/IOStream.o .obj/IOStream.o .obj/IOStream.o .obj/IOStream.o: IOStream.cpp \ +.obj/IOStream.o .obj/IOStream.so .shobj/IOStream.o .shobj/IOStream.so: IOStream.cpp \ IOStream.h \ pre.h \ OS.h \ @@ -9544,7 +9547,7 @@ endif # GHS IOStream_T.i \ IOStream_T.cpp -.obj/Pipe.o .obj/Pipe.o .obj/Pipe.o .obj/Pipe.o: Pipe.cpp \ +.obj/Pipe.o .obj/Pipe.so .shobj/Pipe.o .shobj/Pipe.so: Pipe.cpp \ Pipe.h \ pre.h \ ACE.h \ @@ -9612,7 +9615,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Signal.o .obj/Signal.o .obj/Signal.o .obj/Signal.o: Signal.cpp \ +.obj/Signal.o .obj/Signal.so .shobj/Signal.o .shobj/Signal.so: Signal.cpp \ Synch_T.h \ pre.h \ Synch.h \ @@ -9705,7 +9708,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/SPIPE_Addr.o .obj/SPIPE_Addr.o .obj/SPIPE_Addr.o .obj/SPIPE_Addr.o: SPIPE_Addr.cpp \ +.obj/SPIPE_Addr.o .obj/SPIPE_Addr.so .shobj/SPIPE_Addr.o .shobj/SPIPE_Addr.so: SPIPE_Addr.cpp \ SPIPE_Addr.h \ pre.h \ Addr.h \ @@ -9754,7 +9757,7 @@ endif # GHS SString.i \ Malloc_Base.h -.obj/SPIPE.o .obj/SPIPE.o .obj/SPIPE.o .obj/SPIPE.o: SPIPE.cpp \ +.obj/SPIPE.o .obj/SPIPE.so .shobj/SPIPE.o .shobj/SPIPE.so: SPIPE.cpp \ SPIPE.h \ pre.h \ IPC_SAP.h \ @@ -9807,7 +9810,7 @@ endif # GHS Malloc_Base.h \ SPIPE.i -.obj/SPIPE_Acceptor.o .obj/SPIPE_Acceptor.o .obj/SPIPE_Acceptor.o .obj/SPIPE_Acceptor.o: SPIPE_Acceptor.cpp \ +.obj/SPIPE_Acceptor.o .obj/SPIPE_Acceptor.so .shobj/SPIPE_Acceptor.o .shobj/SPIPE_Acceptor.so: SPIPE_Acceptor.cpp \ SPIPE_Acceptor.h \ pre.h \ SPIPE_Stream.h \ @@ -9869,7 +9872,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/SPIPE_Connector.o .obj/SPIPE_Connector.o .obj/SPIPE_Connector.o .obj/SPIPE_Connector.o: SPIPE_Connector.cpp \ +.obj/SPIPE_Connector.o .obj/SPIPE_Connector.so .shobj/SPIPE_Connector.o .shobj/SPIPE_Connector.so: SPIPE_Connector.cpp \ SPIPE_Connector.h \ pre.h \ SPIPE_Stream.h \ @@ -9932,7 +9935,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/SPIPE_Stream.o .obj/SPIPE_Stream.o .obj/SPIPE_Stream.o .obj/SPIPE_Stream.o: SPIPE_Stream.cpp \ +.obj/SPIPE_Stream.o .obj/SPIPE_Stream.so .shobj/SPIPE_Stream.o .shobj/SPIPE_Stream.so: SPIPE_Stream.cpp \ SPIPE_Stream.h \ pre.h \ SPIPE.h \ @@ -9987,7 +9990,7 @@ endif # GHS SPIPE.i \ SPIPE_Stream.i -.obj/SV_Message.o .obj/SV_Message.o .obj/SV_Message.o .obj/SV_Message.o: SV_Message.cpp \ +.obj/SV_Message.o .obj/SV_Message.so .shobj/SV_Message.o .shobj/SV_Message.so: SV_Message.cpp \ SV_Message.h \ pre.h \ ACE.h \ @@ -10031,7 +10034,7 @@ endif # GHS ACE.i \ SV_Message.i -.obj/SV_Message_Queue.o .obj/SV_Message_Queue.o .obj/SV_Message_Queue.o .obj/SV_Message_Queue.o: SV_Message_Queue.cpp \ +.obj/SV_Message_Queue.o .obj/SV_Message_Queue.so .shobj/SV_Message_Queue.o .shobj/SV_Message_Queue.so: SV_Message_Queue.cpp \ SV_Message_Queue.h \ pre.h \ ACE.h \ @@ -10083,7 +10086,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/SV_Semaphore_Complex.o .obj/SV_Semaphore_Complex.o .obj/SV_Semaphore_Complex.o .obj/SV_Semaphore_Complex.o: SV_Semaphore_Complex.cpp \ +.obj/SV_Semaphore_Complex.o .obj/SV_Semaphore_Complex.so .shobj/SV_Semaphore_Complex.o .shobj/SV_Semaphore_Complex.so: SV_Semaphore_Complex.cpp \ SV_Semaphore_Complex.h \ pre.h \ SV_Semaphore_Simple.h \ @@ -10135,7 +10138,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/SV_Semaphore_Simple.o .obj/SV_Semaphore_Simple.o .obj/SV_Semaphore_Simple.o .obj/SV_Semaphore_Simple.o: SV_Semaphore_Simple.cpp \ +.obj/SV_Semaphore_Simple.o .obj/SV_Semaphore_Simple.so .shobj/SV_Semaphore_Simple.o .shobj/SV_Semaphore_Simple.so: SV_Semaphore_Simple.cpp \ SV_Semaphore_Simple.h \ pre.h \ ACE.h \ @@ -10185,7 +10188,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/SV_Shared_Memory.o .obj/SV_Shared_Memory.o .obj/SV_Shared_Memory.o .obj/SV_Shared_Memory.o: SV_Shared_Memory.cpp \ +.obj/SV_Shared_Memory.o .obj/SV_Shared_Memory.so .shobj/SV_Shared_Memory.o .shobj/SV_Shared_Memory.so: SV_Shared_Memory.cpp \ SV_Shared_Memory.h \ pre.h \ ACE.h \ @@ -10235,7 +10238,8 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/TLI.o .obj/TLI.o .obj/TLI.o .obj/TLI.o: TLI.cpp TLI.h \ +.obj/TLI.o .obj/TLI.so .shobj/TLI.o .shobj/TLI.so: TLI.cpp \ + TLI.h \ pre.h \ IPC_SAP.h \ Flag_Manip.h \ @@ -10277,7 +10281,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/TLI_Acceptor.o .obj/TLI_Acceptor.o .obj/TLI_Acceptor.o .obj/TLI_Acceptor.o: TLI_Acceptor.cpp \ +.obj/TLI_Acceptor.o .obj/TLI_Acceptor.so .shobj/TLI_Acceptor.o .shobj/TLI_Acceptor.so: TLI_Acceptor.cpp \ TLI_Acceptor.h \ pre.h \ TLI.h \ @@ -10335,7 +10339,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/TLI_Connector.o .obj/TLI_Connector.o .obj/TLI_Connector.o .obj/TLI_Connector.o: TLI_Connector.cpp \ +.obj/TLI_Connector.o .obj/TLI_Connector.so .shobj/TLI_Connector.o .shobj/TLI_Connector.so: TLI_Connector.cpp \ Handle_Set.h \ pre.h \ ACE.h \ @@ -10394,7 +10398,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/TLI_Stream.o .obj/TLI_Stream.o .obj/TLI_Stream.o .obj/TLI_Stream.o: TLI_Stream.cpp \ +.obj/TLI_Stream.o .obj/TLI_Stream.so .shobj/TLI_Stream.o .shobj/TLI_Stream.so: TLI_Stream.cpp \ TLI_Stream.h \ pre.h \ TLI.h \ @@ -10444,7 +10448,7 @@ endif # GHS ACE.i \ INET_Addr.i -.obj/TTY_IO.o .obj/TTY_IO.o .obj/TTY_IO.o .obj/TTY_IO.o: TTY_IO.cpp \ +.obj/TTY_IO.o .obj/TTY_IO.so .shobj/TTY_IO.o .shobj/TTY_IO.so: TTY_IO.cpp \ TTY_IO.h \ OS.h \ pre.h \ @@ -10508,7 +10512,7 @@ endif # GHS OS_Log_Msg_Attributes.inl \ DEV_Connector.i -.obj/UNIX_Addr.o .obj/UNIX_Addr.o .obj/UNIX_Addr.o .obj/UNIX_Addr.o: UNIX_Addr.cpp \ +.obj/UNIX_Addr.o .obj/UNIX_Addr.so .shobj/UNIX_Addr.o .shobj/UNIX_Addr.so: UNIX_Addr.cpp \ UNIX_Addr.h \ pre.h \ Addr.h \ @@ -10560,7 +10564,7 @@ endif # GHS ACE.i \ UNIX_Addr.i -.obj/UPIPE_Acceptor.o .obj/UPIPE_Acceptor.o .obj/UPIPE_Acceptor.o .obj/UPIPE_Acceptor.o: UPIPE_Acceptor.cpp \ +.obj/UPIPE_Acceptor.o .obj/UPIPE_Acceptor.so .shobj/UPIPE_Acceptor.o .shobj/UPIPE_Acceptor.so: UPIPE_Acceptor.cpp \ UPIPE_Acceptor.h \ pre.h \ UPIPE_Stream.h \ @@ -10744,7 +10748,7 @@ endif # GHS SPIPE_Stream.i \ UPIPE_Acceptor.i -.obj/UPIPE_Connector.o .obj/UPIPE_Connector.o .obj/UPIPE_Connector.o .obj/UPIPE_Connector.o: UPIPE_Connector.cpp \ +.obj/UPIPE_Connector.o .obj/UPIPE_Connector.so .shobj/UPIPE_Connector.o .shobj/UPIPE_Connector.so: UPIPE_Connector.cpp \ UPIPE_Connector.h \ pre.h \ UPIPE_Stream.h \ @@ -10927,7 +10931,7 @@ endif # GHS SPIPE_Stream.i \ UPIPE_Connector.i -.obj/UPIPE_Stream.o .obj/UPIPE_Stream.o .obj/UPIPE_Stream.o .obj/UPIPE_Stream.o: UPIPE_Stream.cpp \ +.obj/UPIPE_Stream.o .obj/UPIPE_Stream.so .shobj/UPIPE_Stream.o .shobj/UPIPE_Stream.so: UPIPE_Stream.cpp \ UPIPE_Stream.h \ pre.h \ Stream.h \ @@ -11106,7 +11110,7 @@ endif # GHS UPIPE_Addr.h \ UPIPE_Stream.i -.obj/MEM_Acceptor.o .obj/MEM_Acceptor.o .obj/MEM_Acceptor.o .obj/MEM_Acceptor.o: MEM_Acceptor.cpp \ +.obj/MEM_Acceptor.o .obj/MEM_Acceptor.so .shobj/MEM_Acceptor.o .shobj/MEM_Acceptor.so: MEM_Acceptor.cpp \ MEM_Acceptor.h \ pre.h \ SOCK_Acceptor.h \ @@ -11241,7 +11245,7 @@ endif # GHS MEM_Addr.i \ MEM_Acceptor.i -.obj/MEM_Addr.o .obj/MEM_Addr.o .obj/MEM_Addr.o .obj/MEM_Addr.o: MEM_Addr.cpp \ +.obj/MEM_Addr.o .obj/MEM_Addr.so .shobj/MEM_Addr.o .shobj/MEM_Addr.so: MEM_Addr.cpp \ MEM_Addr.h \ pre.h \ ACE.h \ @@ -11295,7 +11299,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/MEM_Connector.o .obj/MEM_Connector.o .obj/MEM_Connector.o .obj/MEM_Connector.o: MEM_Connector.cpp \ +.obj/MEM_Connector.o .obj/MEM_Connector.so .shobj/MEM_Connector.o .shobj/MEM_Connector.so: MEM_Connector.cpp \ MEM_Connector.h \ pre.h \ SOCK_Connector.h \ @@ -11430,7 +11434,7 @@ endif # GHS MEM_Addr.i \ MEM_Connector.i -.obj/MEM_IO.o .obj/MEM_IO.o .obj/MEM_IO.o .obj/MEM_IO.o: MEM_IO.cpp \ +.obj/MEM_IO.o .obj/MEM_IO.so .shobj/MEM_IO.o .shobj/MEM_IO.so: MEM_IO.cpp \ MEM_IO.h \ pre.h \ SOCK.h \ @@ -11554,7 +11558,7 @@ endif # GHS Handle_Set.h \ Handle_Set.i -.obj/MEM_SAP.o .obj/MEM_SAP.o .obj/MEM_SAP.o .obj/MEM_SAP.o: MEM_SAP.cpp \ +.obj/MEM_SAP.o .obj/MEM_SAP.so .shobj/MEM_SAP.o .shobj/MEM_SAP.so: MEM_SAP.cpp \ MEM_SAP.h \ pre.h \ PI_Malloc.h \ @@ -11660,7 +11664,7 @@ endif # GHS Process_Mutex.inl \ MEM_SAP.i -.obj/MEM_Stream.o .obj/MEM_Stream.o .obj/MEM_Stream.o .obj/MEM_Stream.o: MEM_Stream.cpp \ +.obj/MEM_Stream.o .obj/MEM_Stream.so .shobj/MEM_Stream.o .shobj/MEM_Stream.so: MEM_Stream.cpp \ MEM_Stream.h \ pre.h \ MEM_IO.h \ @@ -11784,7 +11788,8 @@ endif # GHS MEM_IO.i \ MEM_Stream.i -.obj/DLL.o .obj/DLL.o .obj/DLL.o .obj/DLL.o: DLL.cpp DLL.h \ +.obj/DLL.o .obj/DLL.so .shobj/DLL.o .shobj/DLL.so: DLL.cpp \ + DLL.h \ pre.h \ OS.h \ config-all.h \ @@ -11832,7 +11837,7 @@ endif # GHS Sock_Connect.i \ ACE.i -.obj/Parse_Node.o .obj/Parse_Node.o .obj/Parse_Node.o .obj/Parse_Node.o: Parse_Node.cpp \ +.obj/Parse_Node.o .obj/Parse_Node.so .shobj/Parse_Node.o .shobj/Parse_Node.so: Parse_Node.cpp \ Service_Config.h \ pre.h \ Service_Object.h \ @@ -11998,7 +12003,7 @@ endif # GHS Parse_Node.h \ Parse_Node.i -.obj/Service_Config.o .obj/Service_Config.o .obj/Service_Config.o .obj/Service_Config.o: Service_Config.cpp \ +.obj/Service_Config.o .obj/Service_Config.so .shobj/Service_Config.o .shobj/Service_Config.so: Service_Config.cpp \ Svc_Conf.h \ pre.h \ Obstack.h \ @@ -12151,7 +12156,7 @@ endif # GHS Managed_Object.cpp \ Thread_Manager.i -.obj/Service_Manager.o .obj/Service_Manager.o .obj/Service_Manager.o .obj/Service_Manager.o: Service_Manager.cpp \ +.obj/Service_Manager.o .obj/Service_Manager.so .shobj/Service_Manager.o .shobj/Service_Manager.so: Service_Manager.cpp \ Get_Opt.h \ pre.h \ ACE.h \ @@ -12325,7 +12330,7 @@ endif # GHS Process_Mutex.inl \ WFMO_Reactor.i -.obj/Service_Object.o .obj/Service_Object.o .obj/Service_Object.o .obj/Service_Object.o: Service_Object.cpp \ +.obj/Service_Object.o .obj/Service_Object.so .shobj/Service_Object.o .shobj/Service_Object.so: Service_Object.cpp \ Service_Types.h \ pre.h \ Service_Object.h \ @@ -12393,7 +12398,7 @@ endif # GHS Log_Record.i \ Service_Types.i -.obj/Service_Repository.o .obj/Service_Repository.o .obj/Service_Repository.o .obj/Service_Repository.o: Service_Repository.cpp \ +.obj/Service_Repository.o .obj/Service_Repository.so .shobj/Service_Repository.o .shobj/Service_Repository.so: Service_Repository.cpp \ Service_Repository.h \ pre.h \ Service_Types.h \ @@ -12468,7 +12473,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Service_Types.o .obj/Service_Types.o .obj/Service_Types.o .obj/Service_Types.o: Service_Types.cpp \ +.obj/Service_Types.o .obj/Service_Types.so .shobj/Service_Types.o .shobj/Service_Types.so: Service_Types.cpp \ Service_Types.h \ pre.h \ Service_Object.h \ @@ -12636,7 +12641,7 @@ endif # GHS Stream.i \ Stream.cpp -.obj/Service_Templates.o .obj/Service_Templates.o .obj/Service_Templates.o .obj/Service_Templates.o: Service_Templates.cpp \ +.obj/Service_Templates.o .obj/Service_Templates.so .shobj/Service_Templates.o .shobj/Service_Templates.so: Service_Templates.cpp \ Service_Templates.h \ pre.h \ Svc_Conf.h \ @@ -12813,7 +12818,7 @@ endif # GHS Stream.i \ Stream.cpp -.obj/Shared_Object.o .obj/Shared_Object.o .obj/Shared_Object.o .obj/Shared_Object.o: Shared_Object.cpp \ +.obj/Shared_Object.o .obj/Shared_Object.so .shobj/Shared_Object.o .shobj/Shared_Object.so: Shared_Object.cpp \ Shared_Object.h \ pre.h \ ACE.h \ @@ -12857,7 +12862,7 @@ endif # GHS ACE.i \ Shared_Object.i -.obj/Svc_Conf_l.o .obj/Svc_Conf_l.o .obj/Svc_Conf_l.o .obj/Svc_Conf_l.o: Svc_Conf_l.cpp \ +.obj/Svc_Conf_l.o .obj/Svc_Conf_l.so .shobj/Svc_Conf_l.o .shobj/Svc_Conf_l.so: Svc_Conf_l.cpp \ OS.h \ pre.h \ config-all.h \ @@ -12973,7 +12978,7 @@ endif # GHS Service_Types.i \ Parse_Node.i -.obj/Svc_Conf_y.o .obj/Svc_Conf_y.o .obj/Svc_Conf_y.o .obj/Svc_Conf_y.o: Svc_Conf_y.cpp \ +.obj/Svc_Conf_y.o .obj/Svc_Conf_y.so .shobj/Svc_Conf_y.o .shobj/Svc_Conf_y.so: Svc_Conf_y.cpp \ ARGV.h \ pre.h \ ACE.h \ @@ -13148,7 +13153,7 @@ endif # GHS Stream.i \ Stream.cpp -.obj/CDR_Base.o .obj/CDR_Base.o .obj/CDR_Base.o .obj/CDR_Base.o: CDR_Base.cpp \ +.obj/CDR_Base.o .obj/CDR_Base.so .shobj/CDR_Base.o .shobj/CDR_Base.so: CDR_Base.cpp \ CDR_Base.h \ pre.h \ config-all.h \ @@ -13243,7 +13248,7 @@ endif # GHS Message_Block_T.cpp \ CDR_Base.inl -.obj/CDR_Stream.o .obj/CDR_Stream.o .obj/CDR_Stream.o .obj/CDR_Stream.o: CDR_Stream.cpp \ +.obj/CDR_Stream.o .obj/CDR_Stream.so .shobj/CDR_Stream.o .shobj/CDR_Stream.so: CDR_Stream.cpp \ CDR_Stream.h \ pre.h \ CDR_Base.h \ @@ -13342,7 +13347,7 @@ endif # GHS SString.h \ SString.i -.obj/Codeset_IBM1047.o .obj/Codeset_IBM1047.o .obj/Codeset_IBM1047.o .obj/Codeset_IBM1047.o: Codeset_IBM1047.cpp \ +.obj/Codeset_IBM1047.o .obj/Codeset_IBM1047.so .shobj/Codeset_IBM1047.o .shobj/Codeset_IBM1047.so: Codeset_IBM1047.cpp \ Codeset_IBM1047.h \ pre.h \ config-all.h \ @@ -13357,7 +13362,7 @@ endif # GHS ace_wchar.h \ ace_wchar.inl -.obj/Message_Block.o .obj/Message_Block.o .obj/Message_Block.o .obj/Message_Block.o: Message_Block.cpp \ +.obj/Message_Block.o .obj/Message_Block.so .shobj/Message_Block.o .shobj/Message_Block.so: Message_Block.cpp \ Message_Block.h \ ACE.h \ pre.h \ @@ -13451,7 +13456,7 @@ endif # GHS Message_Block_T.cpp \ Timeprobe.h -.obj/Message_Queue.o .obj/Message_Queue.o .obj/Message_Queue.o .obj/Message_Queue.o: Message_Queue.cpp \ +.obj/Message_Queue.o .obj/Message_Queue.so .shobj/Message_Queue.o .shobj/Message_Queue.so: Message_Queue.cpp \ Message_Queue.h \ pre.h \ Message_Block.h \ @@ -13605,7 +13610,7 @@ endif # GHS Strategies.i \ Message_Queue.i -.obj/Task.o .obj/Task.o .obj/Task.o .obj/Task.o: Task.cpp \ +.obj/Task.o .obj/Task.so .shobj/Task.o .shobj/Task.so: Task.cpp \ Task.h \ pre.h \ Service_Object.h \ @@ -13769,7 +13774,7 @@ endif # GHS Stream_Modules.h \ Stream_Modules.cpp -.obj/Based_Pointer_Repository.o .obj/Based_Pointer_Repository.o .obj/Based_Pointer_Repository.o .obj/Based_Pointer_Repository.o: Based_Pointer_Repository.cpp \ +.obj/Based_Pointer_Repository.o .obj/Based_Pointer_Repository.so .shobj/Based_Pointer_Repository.o .shobj/Based_Pointer_Repository.so: Based_Pointer_Repository.cpp \ Map_Manager.h \ pre.h \ OS.h \ @@ -13890,7 +13895,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Malloc.o .obj/Malloc.o .obj/Malloc.o .obj/Malloc.o: Malloc.cpp \ +.obj/Malloc.o .obj/Malloc.so .shobj/Malloc.o .shobj/Malloc.so: Malloc.cpp \ Malloc.h \ pre.h \ ACE.h \ @@ -13983,7 +13988,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/PI_Malloc.o .obj/PI_Malloc.o .obj/PI_Malloc.o .obj/PI_Malloc.o: PI_Malloc.cpp \ +.obj/PI_Malloc.o .obj/PI_Malloc.so .shobj/PI_Malloc.o .shobj/PI_Malloc.so: PI_Malloc.cpp \ PI_Malloc.h \ pre.h \ ACE.h \ @@ -14087,7 +14092,7 @@ endif # GHS Process_Mutex.h \ Process_Mutex.inl -.obj/Malloc_Allocator.o .obj/Malloc_Allocator.o .obj/Malloc_Allocator.o .obj/Malloc_Allocator.o: Malloc_Allocator.cpp \ +.obj/Malloc_Allocator.o .obj/Malloc_Allocator.so .shobj/Malloc_Allocator.o .shobj/Malloc_Allocator.so: Malloc_Allocator.cpp \ Malloc_Allocator.h \ pre.h \ ACE.h \ @@ -14155,7 +14160,7 @@ endif # GHS Atomic_Op.i \ Synch_T.cpp -.obj/Mem_Map.o .obj/Mem_Map.o .obj/Mem_Map.o .obj/Mem_Map.o: Mem_Map.cpp \ +.obj/Mem_Map.o .obj/Mem_Map.so .shobj/Mem_Map.o .shobj/Mem_Map.so: Mem_Map.cpp \ Mem_Map.h \ pre.h \ ACE.h \ @@ -14205,7 +14210,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Memory_Pool.o .obj/Memory_Pool.o .obj/Memory_Pool.o .obj/Memory_Pool.o: Memory_Pool.cpp \ +.obj/Memory_Pool.o .obj/Memory_Pool.so .shobj/Memory_Pool.o .shobj/Memory_Pool.so: Memory_Pool.cpp \ Memory_Pool.h \ pre.h \ ACE.h \ @@ -14308,7 +14313,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Obstack.o .obj/Obstack.o .obj/Obstack.o .obj/Obstack.o: Obstack.cpp \ +.obj/Obstack.o .obj/Obstack.so .shobj/Obstack.o .shobj/Obstack.so: Obstack.cpp \ Obstack.h \ pre.h \ Malloc.h \ @@ -14398,7 +14403,7 @@ endif # GHS Memory_Pool.i \ Obstack.i -.obj/Read_Buffer.o .obj/Read_Buffer.o .obj/Read_Buffer.o .obj/Read_Buffer.o: Read_Buffer.cpp \ +.obj/Read_Buffer.o .obj/Read_Buffer.so .shobj/Read_Buffer.o .shobj/Read_Buffer.so: Read_Buffer.cpp \ Read_Buffer.h \ pre.h \ ACE.h \ @@ -14509,7 +14514,7 @@ endif # GHS Reactor_Impl.h \ Svc_Conf_Tokens.h -.obj/Shared_Memory.o .obj/Shared_Memory.o .obj/Shared_Memory.o .obj/Shared_Memory.o: Shared_Memory.cpp \ +.obj/Shared_Memory.o .obj/Shared_Memory.so .shobj/Shared_Memory.o .shobj/Shared_Memory.so: Shared_Memory.cpp \ Shared_Memory.h \ pre.h \ ACE.h \ @@ -14552,7 +14557,7 @@ endif # GHS Sock_Connect.i \ ACE.i -.obj/Shared_Memory_MM.o .obj/Shared_Memory_MM.o .obj/Shared_Memory_MM.o .obj/Shared_Memory_MM.o: Shared_Memory_MM.cpp \ +.obj/Shared_Memory_MM.o .obj/Shared_Memory_MM.so .shobj/Shared_Memory_MM.o .shobj/Shared_Memory_MM.so: Shared_Memory_MM.cpp \ Shared_Memory_MM.h \ pre.h \ Shared_Memory.h \ @@ -14599,7 +14604,7 @@ endif # GHS Mem_Map.i \ Shared_Memory_MM.i -.obj/Shared_Memory_SV.o .obj/Shared_Memory_SV.o .obj/Shared_Memory_SV.o .obj/Shared_Memory_SV.o: Shared_Memory_SV.cpp \ +.obj/Shared_Memory_SV.o .obj/Shared_Memory_SV.so .shobj/Shared_Memory_SV.o .shobj/Shared_Memory_SV.so: Shared_Memory_SV.cpp \ Shared_Memory_SV.h \ pre.h \ Shared_Memory.h \ @@ -14646,7 +14651,7 @@ endif # GHS SV_Shared_Memory.i \ Shared_Memory_SV.i -.obj/Local_Tokens.o .obj/Local_Tokens.o .obj/Local_Tokens.o .obj/Local_Tokens.o: Local_Tokens.cpp \ +.obj/Local_Tokens.o .obj/Local_Tokens.so .shobj/Local_Tokens.o .shobj/Local_Tokens.so: Local_Tokens.cpp \ Thread.h \ pre.h \ ACE.h \ @@ -14764,7 +14769,7 @@ endif # GHS Token_Manager.h \ Token_Manager.i -.obj/Remote_Tokens.o .obj/Remote_Tokens.o .obj/Remote_Tokens.o .obj/Remote_Tokens.o: Remote_Tokens.cpp \ +.obj/Remote_Tokens.o .obj/Remote_Tokens.so .shobj/Remote_Tokens.o .shobj/Remote_Tokens.so: Remote_Tokens.cpp \ Remote_Tokens.h \ pre.h \ INET_Addr.h \ @@ -14908,7 +14913,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Token_Collection.o .obj/Token_Collection.o .obj/Token_Collection.o .obj/Token_Collection.o: Token_Collection.cpp \ +.obj/Token_Collection.o .obj/Token_Collection.so .shobj/Token_Collection.o .shobj/Token_Collection.so: Token_Collection.cpp \ Token_Collection.h \ pre.h \ Map_Manager.h \ @@ -15026,7 +15031,7 @@ endif # GHS Local_Tokens.i \ Token_Collection.i -.obj/Token_Invariants.o .obj/Token_Invariants.o .obj/Token_Invariants.o .obj/Token_Invariants.o: Token_Invariants.cpp \ +.obj/Token_Invariants.o .obj/Token_Invariants.so .shobj/Token_Invariants.o .shobj/Token_Invariants.so: Token_Invariants.cpp \ Token_Invariants.h \ pre.h \ Synch.h \ @@ -15148,7 +15153,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Token_Manager.o .obj/Token_Manager.o .obj/Token_Manager.o .obj/Token_Manager.o: Token_Manager.cpp \ +.obj/Token_Manager.o .obj/Token_Manager.so .shobj/Token_Manager.o .shobj/Token_Manager.so: Token_Manager.cpp \ Token_Manager.h \ pre.h \ Synch.h \ @@ -15271,7 +15276,7 @@ endif # GHS Managed_Object.i \ Managed_Object.cpp -.obj/Token_Request_Reply.o .obj/Token_Request_Reply.o .obj/Token_Request_Reply.o .obj/Token_Request_Reply.o: Token_Request_Reply.cpp \ +.obj/Token_Request_Reply.o .obj/Token_Request_Reply.so .shobj/Token_Request_Reply.o .shobj/Token_Request_Reply.so: Token_Request_Reply.cpp \ Token_Request_Reply.h \ pre.h \ Local_Tokens.h \ @@ -15390,7 +15395,7 @@ endif # GHS Time_Value.h \ Token_Request_Reply.i -.obj/CORBA_Handler.o .obj/CORBA_Handler.o .obj/CORBA_Handler.o .obj/CORBA_Handler.o: CORBA_Handler.cpp \ +.obj/CORBA_Handler.o .obj/CORBA_Handler.so .shobj/CORBA_Handler.o .shobj/CORBA_Handler.so: CORBA_Handler.cpp \ CORBA_Handler.h \ pre.h \ Service_Config.h \ @@ -15512,7 +15517,7 @@ endif # GHS Singleton.cpp \ Thread_Manager.i -.obj/CORBA_Ref.o .obj/CORBA_Ref.o .obj/CORBA_Ref.o .obj/CORBA_Ref.o: CORBA_Ref.cpp \ +.obj/CORBA_Ref.o .obj/CORBA_Ref.so .shobj/CORBA_Ref.o .shobj/CORBA_Ref.so: CORBA_Ref.cpp \ CORBA_Ref.h \ pre.h \ ACE.h \ @@ -15562,7 +15567,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Local_Name_Space.o .obj/Local_Name_Space.o .obj/Local_Name_Space.o .obj/Local_Name_Space.o: Local_Name_Space.cpp \ +.obj/Local_Name_Space.o .obj/Local_Name_Space.so .shobj/Local_Name_Space.o .shobj/Local_Name_Space.so: Local_Name_Space.cpp \ ACE.h \ pre.h \ OS.h \ @@ -15712,7 +15717,7 @@ endif # GHS File_Lock.inl \ RW_Process_Mutex.inl -.obj/Name_Proxy.o .obj/Name_Proxy.o .obj/Name_Proxy.o .obj/Name_Proxy.o: Name_Proxy.cpp \ +.obj/Name_Proxy.o .obj/Name_Proxy.so .shobj/Name_Proxy.o .shobj/Name_Proxy.so: Name_Proxy.cpp \ Name_Proxy.h \ pre.h \ INET_Addr.h \ @@ -15841,7 +15846,7 @@ endif # GHS Synch_Options.i \ Name_Request_Reply.h -.obj/Name_Request_Reply.o .obj/Name_Request_Reply.o .obj/Name_Request_Reply.o .obj/Name_Request_Reply.o: Name_Request_Reply.cpp \ +.obj/Name_Request_Reply.o .obj/Name_Request_Reply.so .shobj/Name_Request_Reply.o .shobj/Name_Request_Reply.so: Name_Request_Reply.cpp \ Name_Request_Reply.h \ pre.h \ Time_Value.h \ @@ -15894,7 +15899,7 @@ endif # GHS OS_Log_Msg_Attributes.h \ OS_Log_Msg_Attributes.inl -.obj/Name_Space.o .obj/Name_Space.o .obj/Name_Space.o .obj/Name_Space.o: Name_Space.cpp \ +.obj/Name_Space.o .obj/Name_Space.so .shobj/Name_Space.o .shobj/Name_Space.so: Name_Space.cpp \ Name_Space.h \ pre.h \ ACE.h \ @@ -16024,7 +16029,7 @@ endif # GHS Synch_Options.i \ Name_Request_Reply.h -.obj/Naming_Context.o .obj/Naming_Context.o .obj/Naming_Context.o .obj/Naming_Context.o: Naming_Context.cpp \ +.obj/Naming_Context.o .obj/Naming_Context.so .shobj/Naming_Context.o .shobj/Naming_Context.so: Naming_Context.cpp \ Get_Opt.h \ pre.h \ ACE.h \ @@ -16178,7 +16183,7 @@ endif # GHS File_Lock.inl \ RW_Process_Mutex.inl -.obj/Registry_Name_Space.o .obj/Registry_Name_Space.o .obj/Registry_Name_Space.o .obj/Registry_Name_Space.o: Registry_Name_Space.cpp \ +.obj/Registry_Name_Space.o .obj/Registry_Name_Space.so .shobj/Registry_Name_Space.o .shobj/Registry_Name_Space.so: Registry_Name_Space.cpp \ Registry_Name_Space.h \ pre.h \ OS.h \ @@ -16209,7 +16214,7 @@ endif # GHS Trace.h \ OS.i -.obj/Remote_Name_Space.o .obj/Remote_Name_Space.o .obj/Remote_Name_Space.o .obj/Remote_Name_Space.o: Remote_Name_Space.cpp \ +.obj/Remote_Name_Space.o .obj/Remote_Name_Space.so .shobj/Remote_Name_Space.o .shobj/Remote_Name_Space.so: Remote_Name_Space.cpp \ Remote_Name_Space.h \ pre.h \ ACE.h \ @@ -16343,7 +16348,7 @@ endif # GHS Auto_Ptr.i \ Auto_Ptr.cpp -.obj/SOCK_Dgram_Mcast_QoS.o .obj/SOCK_Dgram_Mcast_QoS.o .obj/SOCK_Dgram_Mcast_QoS.o .obj/SOCK_Dgram_Mcast_QoS.o: SOCK_Dgram_Mcast_QoS.cpp \ +.obj/SOCK_Dgram_Mcast_QoS.o .obj/SOCK_Dgram_Mcast_QoS.so .shobj/SOCK_Dgram_Mcast_QoS.o .shobj/SOCK_Dgram_Mcast_QoS.so: SOCK_Dgram_Mcast_QoS.cpp \ SOCK_Dgram_Mcast_QoS.h \ pre.h \ SOCK_Dgram_Mcast.h \ @@ -16447,7 +16452,7 @@ endif # GHS Memory_Pool.i \ SOCK_Dgram_Mcast_QoS.i -.obj/QoS_Session_Impl.o .obj/QoS_Session_Impl.o .obj/QoS_Session_Impl.o .obj/QoS_Session_Impl.o: QoS_Session_Impl.cpp \ +.obj/QoS_Session_Impl.o .obj/QoS_Session_Impl.so .shobj/QoS_Session_Impl.o .shobj/QoS_Session_Impl.so: QoS_Session_Impl.cpp \ SOCK.h \ pre.h \ ACE.h \ @@ -16547,7 +16552,7 @@ endif # GHS QoS_Session_Impl.h \ QoS_Session_Impl.i -.obj/QoS_Session_Factory.o .obj/QoS_Session_Factory.o .obj/QoS_Session_Factory.o .obj/QoS_Session_Factory.o: QoS_Session_Factory.cpp \ +.obj/QoS_Session_Factory.o .obj/QoS_Session_Factory.so .shobj/QoS_Session_Factory.o .shobj/QoS_Session_Factory.so: QoS_Session_Factory.cpp \ QoS_Session_Factory.h \ pre.h \ QoS_Session.h \ @@ -16643,7 +16648,7 @@ endif # GHS QoS_Session_Impl.h \ QoS_Session_Impl.i -.obj/QoS_Manager.o .obj/QoS_Manager.o .obj/QoS_Manager.o .obj/QoS_Manager.o: QoS_Manager.cpp \ +.obj/QoS_Manager.o .obj/QoS_Manager.so .shobj/QoS_Manager.o .shobj/QoS_Manager.so: QoS_Manager.cpp \ QoS_Manager.h \ pre.h \ Addr.h \ @@ -16736,7 +16741,7 @@ endif # GHS SV_Semaphore_Complex.i \ Memory_Pool.i -.obj/QoS_Decorator.o .obj/QoS_Decorator.o .obj/QoS_Decorator.o .obj/QoS_Decorator.o: QoS_Decorator.cpp \ +.obj/QoS_Decorator.o .obj/QoS_Decorator.so .shobj/QoS_Decorator.o .shobj/QoS_Decorator.so: QoS_Decorator.cpp \ QoS_Decorator.h \ pre.h \ Reactor.h \ diff --git a/ace/Malloc.h b/ace/Malloc.h index 584587e487f..deec257078d 100644 --- a/ace/Malloc.h +++ b/ace/Malloc.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Malloc.h -// -// = AUTHOR -// Doug Schmidt and Irfan Pyarali -// -// ============================================================================ + +//============================================================================= +/** + * @file Malloc.h + * + * $Id$ + * + * @author Doug Schmidt and Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_MALLOC_H #define ACE_MALLOC_H @@ -200,21 +197,20 @@ typedef ACE_Atomic_Op<ACE_PROCESS_MUTEX, int> ACE_INT; ***********************************************************/ +/// This keeps stats on the usage of the memory manager. struct ACE_Export ACE_Malloc_Stats -// TITLE -// This keeps stats on the usage of the memory manager. { ACE_Malloc_Stats (void); void dump (void) const; + /// Coarse-grained unit of allocation. ACE_INT nchunks_; - // Coarse-grained unit of allocation. + /// Fine-grained unit of allocation. ACE_INT nblocks_; - // Fine-grained unit of allocation. + /// Number of blocks in use ACE_INT ninuse_; - // Number of blocks in use }; #define ACE_MALLOC_STATS(X) X #else @@ -244,40 +240,45 @@ struct ACE_Export ACE_Malloc_Stats : (((ACE_MALLOC_PADDING / ACE_MALLOC_ALIGN) + 1) \ * ACE_MALLOC_ALIGN)) +/** + * @class ACE_Control_Block + * + * @brief This information is stored in memory allocated by the <Memory_Pool>. + * + * This class defines the "old" control block class for use in + * ACE_Malloc_T. This control block implementation is + * considerable more efficient than the "position independent" + * one below (ACE_PI_Control_Block) but if you are going to use + * it to construct a ACE_Malloc_T and access the memory from + * several different processes, you must "map" the underlying + * memory pool to the same address. + */ class ACE_Export ACE_Control_Block { - // = TITLE - // This information is stored in memory allocated by the <Memory_Pool>. - // - // = DESCRIPTION - // This class defines the "old" control block class for use in - // ACE_Malloc_T. This control block implementation is - // considerable more efficient than the "position independent" - // one below (ACE_PI_Control_Block) but if you are going to use - // it to construct a ACE_Malloc_T and access the memory from - // several different processes, you must "map" the underlying - // memory pool to the same address. public: + /** + * @class ACE_Malloc_Header + * + * @brief This is the control block header. It's used by <ACE_Malloc> + * to keep track of each chunk of data when it's in the free + * list or in use. + */ class ACE_Export ACE_Malloc_Header { - // = TITLE - // This is the control block header. It's used by <ACE_Malloc> - // to keep track of each chunk of data when it's in the free - // list or in use. public: ACE_Malloc_Header (void); + /// Points to next block if on free list. ACE_Malloc_Header *next_block_; - // Points to next block if on free list. + /// Initialize a malloc header pointer. static void init_ptr (ACE_Malloc_Header **ptr, ACE_Malloc_Header *init, void *base_addr); - // Initialize a malloc header pointer. + /// Size of this header control block. size_t size_; - // Size of this header control block. #if defined (ACE_MALLOC_PADDING_SIZE) && (ACE_MALLOC_PADDING_SIZE == 0) // No padding required. @@ -290,62 +291,64 @@ public: long padding_[ACE_MALLOC_PADDING_SIZE < 1 ? 1 : ACE_MALLOC_PADDING_SIZE]; #endif /* ACE_MALLOC_PADDING_SIZE && ACE_MALLOC_PADDING_SIZE == 0 */ + /// Dump the state of the object. void dump (void) const; - // Dump the state of the object. }; + /** + * @class ACE_Name_Node + * + * @brief This class supports "named memory regions" within <ACE_Malloc>. + * + * Internally, the named memory regions are stored as a + * doubly-linked list within the <Memory_Pool>. This makes + * it easy to iterate over the items in the list in both FIFO + * and LIFO order. + */ class ACE_Export ACE_Name_Node { - // = TITLE - // This class supports "named memory regions" within <ACE_Malloc>. - // - // = DESCRIPTION - // Internally, the named memory regions are stored as a - // doubly-linked list within the <Memory_Pool>. This makes - // it easy to iterate over the items in the list in both FIFO - // and LIFO order. public: // = Initialization methods. + /// Constructor. ACE_Name_Node (const char *name, char *name_ptr, char *pointer, ACE_Name_Node *head); - // Constructor. + /// Copy constructor. ACE_Name_Node (const ACE_Name_Node &); - // Copy constructor. + /// Constructor. ACE_Name_Node (void); - // Constructor. + /// Constructor. ~ACE_Name_Node (void); - // Constructor. + /// Initialize a name node pointer. static void init_ptr (ACE_Name_Node **ptr, ACE_Name_Node *init, void *base_addr); - // Initialize a name node pointer. + /// Return a pointer to the name of this node. const char *name (void) const; - // Return a pointer to the name of this node. + /// Assign a name; void name (const char *); - // Assign a name; + /// Name of the Node. char *name_; - // Name of the Node. + /// Pointer to the contents. char *pointer_; - // Pointer to the contents. + /// Pointer to the next node in the doubly-linked list. ACE_Name_Node *next_; - // Pointer to the next node in the doubly-linked list. + /// Pointer to the previous node in the doubly-linked list. ACE_Name_Node *prev_; - // Pointer to the previous node in the doubly-linked list. + /// Dump the state of the object. void dump (void) const; - // Dump the state of the object. }; static void print_alignment_info (void); diff --git a/ace/Malloc_Allocator.h b/ace/Malloc_Allocator.h index be5c0a69eae..ad848c2966a 100644 --- a/ace/Malloc_Allocator.h +++ b/ace/Malloc_Allocator.h @@ -1,15 +1,14 @@ -// $Id$ - -// ========================================================================= -// FILENAME -// Malloc_Allocator.h -// -// DESCRIPTION -// -// -// AUTHOR -// Priyanka Gontla <pgontla@ece.uci.edu> -// ========================================================================== + +//============================================================================= +/** + * @file Malloc_Allocator.h + * + * $Id$ + * + * @author Priyanka Gontla <pgontla@ece.uci.edu> + */ +//============================================================================= + #ifndef MALLOC_ALLOCATOR_H #define MALLOC_ALLOCATOR_H @@ -35,41 +34,42 @@ typedef ACE_Atomic_Op<ACE_PROCESS_MUTEX, int> ACE_INT; +/// This keeps stats on the usage of the memory manager. struct ACE_Export ACE_Malloc_Stats -// TITLE -// This keeps stats on the usage of the memory manager. { ACE_Malloc_Stats (void); void dump (void) const; + /// Coarse-grained unit of allocation. ACE_INT nchunks_; - // Coarse-grained unit of allocation. + /// Fine-grained unit of allocation. ACE_INT nblocks_; - // Fine-grained unit of allocation. + /// Number of blocks in use ACE_INT ninuse_; - // Number of blocks in use }; #define ACE_MALLOC_STATS(X) X #else #define ACE_MALLOC_STATS(X) #endif /* ACE_HAS_MALLOC_STATS */ +/** + * @class ACE_New_Allocator + * + * @brief Defines a class that provided a simple implementation of + * memory allocation. + * + * This class uses the new/delete operators to allocate and free + * up memory. Please note that the only methods that are + * supported are malloc and free. All other methods are no-ops. + * If you require this functionality, please use: + * ACE_Allocator_Adapter <ACE_Malloc <ACE_LOCAL_MEMORY_POOL, + * MUTEX> > This will allow you to use the added functionality + * of bind/find/etc. while using the new/delete operators. + */ class ACE_Export ACE_New_Allocator : public ACE_Allocator { - // = TITLE - // Defines a class that provided a simple implementation of - // memory allocation. - // - // = DESCRIPTION - // This class uses the new/delete operators to allocate and free - // up memory. Please note that the only methods that are - // supported are malloc and free. All other methods are no-ops. - // If you require this functionality, please use: - // ACE_Allocator_Adapter <ACE_Malloc <ACE_LOCAL_MEMORY_POOL, - // MUTEX> > This will allow you to use the added functionality - // of bind/find/etc. while using the new/delete operators. public: virtual void *malloc (size_t nbytes); virtual void *calloc (size_t nbytes, char initial_value = '\0'); @@ -96,21 +96,23 @@ private: // <ACE_Allocator::instance> implementation for explanation. }; +/** + * @class ACE_Static_Allocator_Base + * + * @brief Defines a class that provided a highly optimized memory + * management scheme for allocating memory statically. + * + * This class manages a fixed-size <POOL_SIZE> of memory. Every + * time <malloc>/<calloc> is called, it simply moves an internal + * index forward and returns a pointer to the requested chunk. + * All memory is allocated statically (typically via the + * <ACE_Static_Allocator> template) and <free> is a no-op. This + * behavior is useful for use-cases where all the memory + * allocation needs are known in advance and no deletions ever + * occur. + */ class ACE_Export ACE_Static_Allocator_Base : public ACE_Allocator { - // = TITLE - // Defines a class that provided a highly optimized memory - // management scheme for allocating memory statically. - // - // = DESCRIPTION - // This class manages a fixed-size <POOL_SIZE> of memory. Every - // time <malloc>/<calloc> is called, it simply moves an internal - // index forward and returns a pointer to the requested chunk. - // All memory is allocated statically (typically via the - // <ACE_Static_Allocator> template) and <free> is a no-op. This - // behavior is useful for use-cases where all the memory - // allocation needs are known in advance and no deletions ever - // occur. public: ACE_Static_Allocator_Base (char *buffer, size_t size); virtual void *malloc (size_t nbytes); @@ -134,17 +136,17 @@ public: virtual void dump (void) const; protected: + /// Don't allow direct instantiations of this class. ACE_Static_Allocator_Base (void); - // Don't allow direct instantiations of this class. + /// Pointer to the buffer. char *buffer_; - // Pointer to the buffer. + /// Size of the buffer. size_t size_; - // Size of the buffer. + /// Pointer to the current offset in the <buffer_>. size_t offset_; - // Pointer to the current offset in the <buffer_>. }; #if defined (__ACE_INLINE__) diff --git a/ace/Malloc_Base.h b/ace/Malloc_Base.h index 52537ad3a85..89df21cac2e 100644 --- a/ace/Malloc_Base.h +++ b/ace/Malloc_Base.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Malloc_Base.h -// -// = AUTHOR -// Doug Schmidt and Irfan Pyarali -// -// ============================================================================ + +//============================================================================= +/** + * @file Malloc_Base.h + * + * $Id$ + * + * @author Doug Schmidt and Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_MALLOC_BASE_H #define ACE_MALLOC_BASE_H @@ -20,122 +17,133 @@ // The definition of this class is located in Malloc.cpp. +/** + * @class ACE_Allocator + * + * @brief Interface for a dynamic memory allocator that uses inheritance + * and dynamic binding to provide extensible mechanisms for + * allocating and deallocating memory. + */ class ACE_Export ACE_Allocator { - // = TITLE - // Interface for a dynamic memory allocator that uses inheritance - // and dynamic binding to provide extensible mechanisms for - // allocating and deallocating memory. public: // = Memory Management + /// Get pointer to a default <ACE_Allocator>. static ACE_Allocator *instance (void); - // Get pointer to a default <ACE_Allocator>. + /// Set pointer to a process-wide <ACE_Allocator> and return existing + /// pointer. static ACE_Allocator *instance (ACE_Allocator *); - // Set pointer to a process-wide <ACE_Allocator> and return existing - // pointer. + /// Delete the dynamically allocated Singleton static void close_singleton (void); - // Delete the dynamically allocated Singleton + /// "No-op" constructor (needed to make certain compilers happy). ACE_Allocator (void); - // "No-op" constructor (needed to make certain compilers happy). + /// Virtual destructor virtual ~ACE_Allocator (void); - // Virtual destructor + /// Allocate <nbytes>, but don't give them any initial value. virtual void *malloc (size_t nbytes) = 0; - // Allocate <nbytes>, but don't give them any initial value. + /// Allocate <nbytes>, giving them <initial_value>. virtual void *calloc (size_t nbytes, char initial_value = '\0') = 0; - // Allocate <nbytes>, giving them <initial_value>. + /// Allocate <n_elem> each of size <elem_size>, giving them + /// <initial_value>. virtual void *calloc (size_t n_elem, size_t elem_size, char initial_value = '\0') = 0; - // Allocate <n_elem> each of size <elem_size>, giving them - // <initial_value>. + /// Free <ptr> (must have been allocated by <ACE_Allocator::malloc>). virtual void free (void *ptr) = 0; - // Free <ptr> (must have been allocated by <ACE_Allocator::malloc>). + /// Remove any resources associated with this memory manager. virtual int remove (void) = 0; - // Remove any resources associated with this memory manager. // = Map manager like functions + /** + * Associate <name> with <pointer>. If <duplicates> == 0 then do + * not allow duplicate <name>/<pointer> associations, else if + * <duplicates> != 0 then allow duplicate <name>/<pointer> + * assocations. Returns 0 if successfully binds (1) a previously + * unbound <name> or (2) <duplicates> != 0, returns 1 if trying to + * bind a previously bound <name> and <duplicates> == 0, else + * returns -1 if a resource failure occurs. + */ virtual int bind (const char *name, void *pointer, int duplicates = 0) = 0; - // Associate <name> with <pointer>. If <duplicates> == 0 then do - // not allow duplicate <name>/<pointer> associations, else if - // <duplicates> != 0 then allow duplicate <name>/<pointer> - // assocations. Returns 0 if successfully binds (1) a previously - // unbound <name> or (2) <duplicates> != 0, returns 1 if trying to - // bind a previously bound <name> and <duplicates> == 0, else - // returns -1 if a resource failure occurs. + /** + * Associate <name> with <pointer>. Does not allow duplicate + * <name>/<pointer> associations. Returns 0 if successfully binds + * (1) a previously unbound <name>, 1 if trying to bind a previously + * bound <name>, or returns -1 if a resource failure occurs. When + * this call returns <pointer>'s value will always reference the + * void * that <name> is associated with. Thus, if the caller needs + * to use <pointer> (e.g., to free it) a copy must be maintained by + * the caller. + */ virtual int trybind (const char *name, void *&pointer) = 0; - // Associate <name> with <pointer>. Does not allow duplicate - // <name>/<pointer> associations. Returns 0 if successfully binds - // (1) a previously unbound <name>, 1 if trying to bind a previously - // bound <name>, or returns -1 if a resource failure occurs. When - // this call returns <pointer>'s value will always reference the - // void * that <name> is associated with. Thus, if the caller needs - // to use <pointer> (e.g., to free it) a copy must be maintained by - // the caller. + /// Locate <name> and pass out parameter via pointer. If found, + /// return 0, Returns -1 if failure occurs. virtual int find (const char *name, void *&pointer) = 0; - // Locate <name> and pass out parameter via pointer. If found, - // return 0, Returns -1 if failure occurs. + /// returns 0 if the name is in the mapping. -1, otherwise. virtual int find (const char *name) = 0; - // returns 0 if the name is in the mapping. -1, otherwise. + /// Unbind (remove) the name from the map. Don't return the pointer + /// to the caller virtual int unbind (const char *name) = 0; - // Unbind (remove) the name from the map. Don't return the pointer - // to the caller + /// Break any association of name. Returns the value of pointer in + /// case the caller needs to deallocate memory. virtual int unbind (const char *name, void *&pointer) = 0; - // Break any association of name. Returns the value of pointer in - // case the caller needs to deallocate memory. // = Protection and "sync" (i.e., flushing memory to persistent // backing store). + /** + * Sync <len> bytes of the memory region to the backing store + * starting at <this->base_addr_>. If <len> == -1 then sync the + * whole region. + */ virtual int sync (ssize_t len = -1, int flags = MS_SYNC) = 0; - // Sync <len> bytes of the memory region to the backing store - // starting at <this->base_addr_>. If <len> == -1 then sync the - // whole region. + /// Sync <len> bytes of the memory region to the backing store + /// starting at <addr_>. virtual int sync (void *addr, size_t len, int flags = MS_SYNC) = 0; - // Sync <len> bytes of the memory region to the backing store - // starting at <addr_>. + /** + * Change the protection of the pages of the mapped region to <prot> + * starting at <this->base_addr_> up to <len> bytes. If <len> == -1 + * then change protection of all pages in the mapped region. + */ virtual int protect (ssize_t len = -1, int prot = PROT_RDWR) = 0; - // Change the protection of the pages of the mapped region to <prot> - // starting at <this->base_addr_> up to <len> bytes. If <len> == -1 - // then change protection of all pages in the mapped region. + /// Change the protection of the pages of the mapped region to <prot> + /// starting at <addr> up to <len> bytes. virtual int protect (void *addr, size_t len, int prot = PROT_RDWR) = 0; - // Change the protection of the pages of the mapped region to <prot> - // starting at <addr> up to <len> bytes. #if defined (ACE_HAS_MALLOC_STATS) + /// Dump statistics of how malloc is behaving. virtual void print_stats (void) const = 0; - // Dump statistics of how malloc is behaving. #endif /* ACE_HAS_MALLOC_STATS */ + /// Dump the state of the object. virtual void dump (void) const = 0; - // Dump the state of the object. private: // DO NOT ADD ANY STATE (DATA MEMBERS) TO THIS CLASS!!!! See the // <ACE_Allocator::instance> implementation for explanation. + /// Pointer to a process-wide <ACE_Allocator> instance. static ACE_Allocator *allocator_; - // Pointer to a process-wide <ACE_Allocator> instance. + /// Must delete the <allocator_> if non-0. static int delete_allocator_; - // Must delete the <allocator_> if non-0. }; #include "ace/post.h" diff --git a/ace/Malloc_T.h b/ace/Malloc_T.h index 1101271d405..b4b70df28df 100644 --- a/ace/Malloc_T.h +++ b/ace/Malloc_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Malloc_T.h -// -// = AUTHOR -// Doug Schmidt and Irfan Pyarali -// -// ============================================================================ + +//============================================================================= +/** + * @file Malloc_T.h + * + * $Id$ + * + * @author Doug Schmidt and Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_MALLOC_T_H #define ACE_MALLOC_T_H @@ -29,81 +26,92 @@ #include "ace/Malloc_Allocator.h" #include "ace/Free_List.h" +/** + * @class ACE_Cached_Mem_Pool_Node + * + * @brief <ACE_Cached_Mem_Pool_Node> keeps unused memory within a free + * list. + * + * The length of a piece of unused memory must be greater than + * sizeof (void*). This makes sense because we'll waste even + * more memory if we keep them in a separate data structure. + * This class should really be placed within the next class + * <ACE_Cached_Allocator>. But this can't be done due to C++ + * compiler portability problems. + */ template <class T> class ACE_Cached_Mem_Pool_Node { - // = TITLE - // <ACE_Cached_Mem_Pool_Node> keeps unused memory within a free - // list. - // - // = DESCRIPTION - // The length of a piece of unused memory must be greater than - // sizeof (void*). This makes sense because we'll waste even - // more memory if we keep them in a separate data structure. - // This class should really be placed within the next class - // <ACE_Cached_Allocator>. But this can't be done due to C++ - // compiler portability problems. public: + /// return the address of free memory. T *addr (void); - // return the address of free memory. + /// get the next ACE_Cached_Mem_Pool_Node in a list. ACE_Cached_Mem_Pool_Node<T> *get_next (void); - // get the next ACE_Cached_Mem_Pool_Node in a list. + /// set the next ACE_Cached_Mem_Pool_Node. void set_next (ACE_Cached_Mem_Pool_Node<T> *ptr); - // set the next ACE_Cached_Mem_Pool_Node. private: + /** + * Since memory is not used when placed in a free list, + * we can use it to maintain the structure of free list. + * I was using union to hide the fact of overlapping memory + * usage. However, that cause problem on MSVC. So, I now turn + * back to hack this with casting. + */ ACE_Cached_Mem_Pool_Node<T> *next_; - // Since memory is not used when placed in a free list, - // we can use it to maintain the structure of free list. - // I was using union to hide the fact of overlapping memory - // usage. However, that cause problem on MSVC. So, I now turn - // back to hack this with casting. }; +/** + * @class ACE_Cached_Allocator + * + * @brief Create a cached memory poll with <n_chunks> chunks each with + * sizeof (TYPE) size. + * + * This class enables caching of dynamically allocated, + * fixed-sized classes. + */ template <class T, class ACE_LOCK> class ACE_Cached_Allocator : public ACE_New_Allocator { - // = TITLE - // Create a cached memory poll with <n_chunks> chunks each with - // sizeof (TYPE) size. - // - // = DESCRIPTION - // This class enables caching of dynamically allocated, - // fixed-sized classes. public: + /// Create a cached memory poll with <n_chunks> chunks + /// each with sizeof (TYPE) size. ACE_Cached_Allocator (size_t n_chunks); - // Create a cached memory poll with <n_chunks> chunks - // each with sizeof (TYPE) size. + /// clear things up. ~ACE_Cached_Allocator (void); - // clear things up. + /** + * Get a chunk of memory from free store. Note that <nbytes> is + * only checked to make sure that it's <= to sizeof T, and is + * otherwise ignored since <malloc> always returns a pointer to an + * item of sizeof (T). + */ void *malloc (size_t nbytes = sizeof (T)); - // Get a chunk of memory from free store. Note that <nbytes> is - // only checked to make sure that it's <= to sizeof T, and is - // otherwise ignored since <malloc> always returns a pointer to an - // item of sizeof (T). + /// return a chunk of memory back to free store. void free (void *); - // return a chunk of memory back to free store. private: + /// remember how we allocate the memory in the first place so + /// we can clear things up later. char *pool_; - // remember how we allocate the memory in the first place so - // we can clear things up later. + /// Maintain a cached memory free list. ACE_Locked_Free_List<ACE_Cached_Mem_Pool_Node<T>, ACE_LOCK> free_list_; - // Maintain a cached memory free list. }; +/** + * @class ACE_Allocator_Adapter + * + * @brief This class is an Adapter that allows the <ACE_Allocator> to + * use the <Malloc> class below. + */ template <class MALLOC> class ACE_Allocator_Adapter : public ACE_Allocator { - // = TITLE - // This class is an Adapter that allows the <ACE_Allocator> to - // use the <Malloc> class below. public: // Trait. typedef MALLOC ALLOCATOR; @@ -145,113 +153,123 @@ public: // Constructor (this has to be inline to avoid bugs with some C++ compilers. #endif /* ACE_HAS_WCHAR */ + /// Destructor. virtual ~ACE_Allocator_Adapter (void); - // Destructor. // = Memory Management + /// Allocate <nbytes>, but don't give them any initial value. virtual void *malloc (size_t nbytes); - // Allocate <nbytes>, but don't give them any initial value. + /// Allocate <nbytes>, giving them all an <initial_value>. virtual void *calloc (size_t nbytes, char initial_value = '\0'); - // Allocate <nbytes>, giving them all an <initial_value>. + /// Allocate <n_elem> each of size <elem_size>, giving them + /// <initial_value>. virtual void *calloc (size_t n_elem, size_t elem_size, char initial_value = '\0'); - // Allocate <n_elem> each of size <elem_size>, giving them - // <initial_value>. + /// Free <ptr> (must have been allocated by <ACE_Allocator::malloc>). virtual void free (void *ptr); - // Free <ptr> (must have been allocated by <ACE_Allocator::malloc>). + /// Remove any resources associated with this memory manager. virtual int remove (void); - // Remove any resources associated with this memory manager. // = Map manager like functions + /** + * Associate <name> with <pointer>. If <duplicates> == 0 then do + * not allow duplicate <name>/<pointer> associations, else if + * <duplicates> != 0 then allow duplicate <name>/<pointer> + * assocations. Returns 0 if successfully binds (1) a previously + * unbound <name> or (2) <duplicates> != 0, returns 1 if trying to + * bind a previously bound <name> and <duplicates> == 0, else + * returns -1 if a resource failure occurs. + */ virtual int bind (const char *name, void *pointer, int duplicates = 0); - // Associate <name> with <pointer>. If <duplicates> == 0 then do - // not allow duplicate <name>/<pointer> associations, else if - // <duplicates> != 0 then allow duplicate <name>/<pointer> - // assocations. Returns 0 if successfully binds (1) a previously - // unbound <name> or (2) <duplicates> != 0, returns 1 if trying to - // bind a previously bound <name> and <duplicates> == 0, else - // returns -1 if a resource failure occurs. + /** + * Associate <name> with <pointer>. Does not allow duplicate + * <name>/<pointer> associations. Returns 0 if successfully binds + * (1) a previously unbound <name>, 1 if trying to bind a previously + * bound <name>, or returns -1 if a resource failure occurs. When + * this call returns <pointer>'s value will always reference the + * void * that <name> is associated with. Thus, if the caller needs + * to use <pointer> (e.g., to free it) a copy must be maintained by + * the caller. + */ virtual int trybind (const char *name, void *&pointer); - // Associate <name> with <pointer>. Does not allow duplicate - // <name>/<pointer> associations. Returns 0 if successfully binds - // (1) a previously unbound <name>, 1 if trying to bind a previously - // bound <name>, or returns -1 if a resource failure occurs. When - // this call returns <pointer>'s value will always reference the - // void * that <name> is associated with. Thus, if the caller needs - // to use <pointer> (e.g., to free it) a copy must be maintained by - // the caller. + /// Locate <name> and pass out parameter via pointer. If found, + /// return 0, Returns -1 if <name> isn't found. virtual int find (const char *name, void *&pointer); - // Locate <name> and pass out parameter via pointer. If found, - // return 0, Returns -1 if <name> isn't found. + /// Returns 0 if the name is in the mapping and -1 if not. virtual int find (const char *name); - // Returns 0 if the name is in the mapping and -1 if not. + /// Unbind (remove) the name from the map. Don't return the pointer + /// to the caller virtual int unbind (const char *name); - // Unbind (remove) the name from the map. Don't return the pointer - // to the caller + /// Break any association of name. Returns the value of pointer in + /// case the caller needs to deallocate memory. virtual int unbind (const char *name, void *&pointer); - // Break any association of name. Returns the value of pointer in - // case the caller needs to deallocate memory. // = Protection and "sync" (i.e., flushing data to backing store). + /** + * Sync <len> bytes of the memory region to the backing store + * starting at <this->base_addr_>. If <len> == -1 then sync the + * whole region. + */ virtual int sync (ssize_t len = -1, int flags = MS_SYNC); - // Sync <len> bytes of the memory region to the backing store - // starting at <this->base_addr_>. If <len> == -1 then sync the - // whole region. + /// Sync <len> bytes of the memory region to the backing store + /// starting at <addr_>. virtual int sync (void *addr, size_t len, int flags = MS_SYNC); - // Sync <len> bytes of the memory region to the backing store - // starting at <addr_>. + /** + * Change the protection of the pages of the mapped region to <prot> + * starting at <this->base_addr_> up to <len> bytes. If <len> == -1 + * then change protection of all pages in the mapped region. + */ virtual int protect (ssize_t len = -1, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <this->base_addr_> up to <len> bytes. If <len> == -1 - // then change protection of all pages in the mapped region. + /// Change the protection of the pages of the mapped region to <prot> + /// starting at <addr> up to <len> bytes. virtual int protect (void *addr, size_t len, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <addr> up to <len> bytes. + /// Returns the underlying allocator. ALLOCATOR &alloc (void); - // Returns the underlying allocator. #if defined (ACE_HAS_MALLOC_STATS) + /// Dump statistics of how malloc is behaving. virtual void print_stats (void) const; - // Dump statistics of how malloc is behaving. #endif /* ACE_HAS_MALLOC_STATS */ + /// Dump the state of the object. virtual void dump (void) const; - // Dump the state of the object. private: + /// ALLOCATOR instance, which is owned by the adapter. ALLOCATOR allocator_; - // ALLOCATOR instance, which is owned by the adapter. }; +/** + * @class ACE_Static_Allocator + * + * @brief Defines a class that provided a highly optimized memory + * management scheme for allocating memory statically. + * + * This class allocates a fixed-size <POOL_SIZE> of memory and + * uses the <ACE_Static_Allocator_Base> class implementations of + * <malloc> and <calloc> to optimize memory allocation from this + * pool. + */ template <size_t POOL_SIZE> class ACE_Static_Allocator : public ACE_Static_Allocator_Base { - // = TITLE - // Defines a class that provided a highly optimized memory - // management scheme for allocating memory statically. - // - // = DESCRIPTION - // This class allocates a fixed-size <POOL_SIZE> of memory and - // uses the <ACE_Static_Allocator_Base> class implementations of - // <malloc> and <calloc> to optimize memory allocation from this - // pool. public: ACE_Static_Allocator (void) : ACE_Static_Allocator_Base (pool_, POOL_SIZE) @@ -260,8 +278,8 @@ public: } private: + /// Pool contents. char pool_[POOL_SIZE]; - // Pool contents. }; // Forward declaration. @@ -275,18 +293,20 @@ class ACE_Malloc_LIFO_Iterator_T; template <ACE_MEM_POOL_1, class ACE_LOCK, class ACE_CB> class ACE_Malloc_FIFO_Iterator_T; +/** + * @class ACE_Malloc_T + * + * @brief Define a C++ class that uses parameterized types to provide + * an extensible mechanism for encapsulating various of dynamic + * memory management strategies. + * + * This class can be configured flexibly with different + * MEMORY_POOL strategies and different types of ACE_LOCK + * strategies. + */ template <ACE_MEM_POOL_1, class ACE_LOCK, class ACE_CB> class ACE_Malloc_T { - // = TITLE - // Define a C++ class that uses parameterized types to provide - // an extensible mechanism for encapsulating various of dynamic - // memory management strategies. - // - // = DESCRIPTION - // This class can be configured flexibly with different - // MEMORY_POOL strategies and different types of ACE_LOCK - // strategies. public: friend class ACE_Malloc_LIFO_Iterator_T<ACE_MEM_POOL_2, ACE_LOCK, ACE_CB>; friend class ACE_Malloc_FIFO_Iterator_T<ACE_MEM_POOL_2, ACE_LOCK, ACE_CB>; @@ -296,292 +316,320 @@ public: typedef ACE_TYPENAME ACE_CB::ACE_Malloc_Header MALLOC_HEADER; // = Initialization and termination methods. + /** + * Initialize ACE_Malloc. This constructor passes <pool_name> to + * initialize the memory pool, and uses <ACE::basename> to + * automatically extract out the name used for the underlying lock + * name (if necessary). + */ ACE_Malloc_T (const ACE_TCHAR *pool_name = 0); - // Initialize ACE_Malloc. This constructor passes <pool_name> to - // initialize the memory pool, and uses <ACE::basename> to - // automatically extract out the name used for the underlying lock - // name (if necessary). + /** + * Initialize ACE_Malloc. This constructor passes <pool_name> to + * initialize the memory pool, and uses <lock_name> to automatically + * extract out the name used for the underlying lock name (if + * necessary). In addition, <options> is passed through to + * initialize the underlying memory pool. + */ ACE_Malloc_T (const ACE_TCHAR *pool_name, const ACE_TCHAR *lock_name, const ACE_MEM_POOL_OPTIONS *options = 0); - // Initialize ACE_Malloc. This constructor passes <pool_name> to - // initialize the memory pool, and uses <lock_name> to automatically - // extract out the name used for the underlying lock name (if - // necessary). In addition, <options> is passed through to - // initialize the underlying memory pool. #if !defined (ACE_HAS_TEMPLATE_TYPEDEFS) + /// This is necessary to work around template bugs with certain C++ + /// compilers. ACE_Malloc_T (const ACE_TCHAR *pool_name, const ACE_TCHAR *lock_name, const void *options = 0); - // This is necessary to work around template bugs with certain C++ - // compilers. #endif /* ACE_HAS_TEMPLATE_TYPEDEFS */ + /// Destructor ~ACE_Malloc_T (void); - // Destructor + /// Releases resources allocated by <ACE_Malloc>. int remove (void); - // Releases resources allocated by <ACE_Malloc>. // = Memory management + /// Allocate <nbytes>, but don't give them any initial value. void *malloc (size_t nbytes); - // Allocate <nbytes>, but don't give them any initial value. + /// Allocate <nbytes>, giving them <initial_value>. void *calloc (size_t nbytes, char initial_value = '\0'); - // Allocate <nbytes>, giving them <initial_value>. + /// Allocate <n_elem> each of size <elem_size>, giving them + /// <initial_value>. void *calloc (size_t n_elem, size_t elem_size, char initial_value = '\0'); - // Allocate <n_elem> each of size <elem_size>, giving them - // <initial_value>. + /// Deallocate memory pointed to by <ptr>, which must have been + /// allocated previously by <this->malloc>. void free (void *ptr); - // Deallocate memory pointed to by <ptr>, which must have been - // allocated previously by <this->malloc>. + /// Returns a reference to the underlying memory pool. MEMORY_POOL &memory_pool (void); - // Returns a reference to the underlying memory pool. // = Map manager like functions + /** + * Associate <name> with <pointer>. If <duplicates> == 0 then do + * not allow duplicate <name>/<pointer> associations, else if + * <duplicates> != 0 then allow duplicate <name>/<pointer> + * assocations. Returns 0 if successfully binds (1) a previously + * unbound <name> or (2) <duplicates> != 0, returns 1 if trying to + * bind a previously bound <name> and <duplicates> == 0, else + * returns -1 if a resource failure occurs. + */ int bind (const char *name, void *pointer, int duplicates = 0); - // Associate <name> with <pointer>. If <duplicates> == 0 then do - // not allow duplicate <name>/<pointer> associations, else if - // <duplicates> != 0 then allow duplicate <name>/<pointer> - // assocations. Returns 0 if successfully binds (1) a previously - // unbound <name> or (2) <duplicates> != 0, returns 1 if trying to - // bind a previously bound <name> and <duplicates> == 0, else - // returns -1 if a resource failure occurs. + /** + * Associate <name> with <pointer>. Does not allow duplicate + * <name>/<pointer> associations. Returns 0 if successfully binds + * (1) a previously unbound <name>, 1 if trying to bind a previously + * bound <name>, or returns -1 if a resource failure occurs. When + * this call returns <pointer>'s value will always reference the + * void * that <name> is associated with. Thus, if the caller needs + * to use <pointer> (e.g., to free it) a copy must be maintained by + * the caller. + */ int trybind (const char *name, void *&pointer); - // Associate <name> with <pointer>. Does not allow duplicate - // <name>/<pointer> associations. Returns 0 if successfully binds - // (1) a previously unbound <name>, 1 if trying to bind a previously - // bound <name>, or returns -1 if a resource failure occurs. When - // this call returns <pointer>'s value will always reference the - // void * that <name> is associated with. Thus, if the caller needs - // to use <pointer> (e.g., to free it) a copy must be maintained by - // the caller. + /// Locate <name> and pass out parameter via <pointer>. If found, + /// return 0, returns -1 if failure occurs. int find (const char *name, void *&pointer); - // Locate <name> and pass out parameter via <pointer>. If found, - // return 0, returns -1 if failure occurs. + /// Returns 0 if <name> is in the mapping. -1, otherwise. int find (const char *name); - // Returns 0 if <name> is in the mapping. -1, otherwise. + /** + * Unbind (remove) the name from the map. Don't return the pointer + * to the caller. If you want to remove all occurrences of <name> + * you'll need to call this method multiple times until it fails... + */ int unbind (const char *name); - // Unbind (remove) the name from the map. Don't return the pointer - // to the caller. If you want to remove all occurrences of <name> - // you'll need to call this method multiple times until it fails... + /** + * Unbind (remove) one association of <name> to <pointer>. Returns + * the value of pointer in case the caller needs to deallocate + * memory. If you want to remove all occurrences of <name> you'll + * need to call this method multiple times until it fails... + */ int unbind (const char *name, void *&pointer); - // Unbind (remove) one association of <name> to <pointer>. Returns - // the value of pointer in case the caller needs to deallocate - // memory. If you want to remove all occurrences of <name> you'll - // need to call this method multiple times until it fails... // = Protection and "sync" (i.e., flushing data to backing store). + /** + * Sync <len> bytes of the memory region to the backing store + * starting at <this->base_addr_>. If <len> == -1 then sync the + * whole region. + */ int sync (ssize_t len = -1, int flags = MS_SYNC); - // Sync <len> bytes of the memory region to the backing store - // starting at <this->base_addr_>. If <len> == -1 then sync the - // whole region. + /// Sync <len> bytes of the memory region to the backing store + /// starting at <addr_>. int sync (void *addr, size_t len, int flags = MS_SYNC); - // Sync <len> bytes of the memory region to the backing store - // starting at <addr_>. + /** + * Change the protection of the pages of the mapped region to <prot> + * starting at <this->base_addr_> up to <len> bytes. If <len> == -1 + * then change protection of all pages in the mapped region. + */ int protect (ssize_t len = -1, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <this->base_addr_> up to <len> bytes. If <len> == -1 - // then change protection of all pages in the mapped region. + /// Change the protection of the pages of the mapped region to <prot> + /// starting at <addr> up to <len> bytes. int protect (void *addr, size_t len, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <addr> up to <len> bytes. + /** + * Returns a count of the number of available chunks that can hold + * <size> byte allocations. Function can be used to determine if you + * have reached a water mark. This implies a fixed amount of allocated + * memory. + * + * @param size - the chunk size of that you would like a count of + * @return function returns the number of chunks of the given size + * that would fit in the currently allocated memory. + */ ssize_t avail_chunks (size_t size) const; - // Returns a count of the number of available chunks that can hold - // <size> byte allocations. Function can be used to determine if you - // have reached a water mark. This implies a fixed amount of allocated - // memory. - // - // @param size - the chunk size of that you would like a count of - // @return function returns the number of chunks of the given size - // that would fit in the currently allocated memory. #if defined (ACE_HAS_MALLOC_STATS) + /// Dump statistics of how malloc is behaving. void print_stats (void) const; - // Dump statistics of how malloc is behaving. #endif /* ACE_HAS_MALLOC_STATS */ + /// Returns a pointer to the lock used to provide mutual exclusion to + /// an <ACE_Malloc> allocator. ACE_LOCK &mutex (void); - // Returns a pointer to the lock used to provide mutual exclusion to - // an <ACE_Malloc> allocator. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Initialize the Malloc pool. int open (void); - // Initialize the Malloc pool. + /// Associate <name> with <pointer>. Assumes that locks are held by + /// callers. int shared_bind (const char *name, void *pointer); - // Associate <name> with <pointer>. Assumes that locks are held by - // callers. + /** + * Try to locate <name>. If found, return the associated + * <ACE_Name_Node>, else returns 0 if can't find the <name>. + * Assumes that locks are held by callers. Remember to cast the + * return value to ACE_CB::ACE_Name_Node*. + */ void *shared_find (const char *name); - // Try to locate <name>. If found, return the associated - // <ACE_Name_Node>, else returns 0 if can't find the <name>. - // Assumes that locks are held by callers. Remember to cast the - // return value to ACE_CB::ACE_Name_Node*. + /// Allocate memory. Assumes that locks are held by callers. void *shared_malloc (size_t nbytes); - // Allocate memory. Assumes that locks are held by callers. + /// Deallocate memory. Assumes that locks are held by callers. void shared_free (void *ptr); - // Deallocate memory. Assumes that locks are held by callers. + /// Pointer to the control block that is stored in memory controlled + /// by <MEMORY_POOL>. ACE_CB *cb_ptr_; - // Pointer to the control block that is stored in memory controlled - // by <MEMORY_POOL>. + /// Pool of memory used by <ACE_Malloc> to manage its freestore. MEMORY_POOL memory_pool_; - // Pool of memory used by <ACE_Malloc> to manage its freestore. + /// Lock that ensures mutual exclusion for the <MEMORY_POOL>. ACE_LOCK lock_; - // Lock that ensures mutual exclusion for the <MEMORY_POOL>. }; +/** + * @class ACE_Malloc_LIFO_Iterator_T + * + * @brief LIFO iterator for names stored in Malloc'd memory. + * + * Does not support deletions while iteration is occurring. + */ template <ACE_MEM_POOL_1, class ACE_LOCK, class ACE_CB> class ACE_Malloc_LIFO_Iterator_T { - // = TITLE - // LIFO iterator for names stored in Malloc'd memory. - // - // = DESCRIPTION - // Does not support deletions while iteration is occurring. public: typedef ACE_TYPENAME ACE_CB::ACE_Name_Node NAME_NODE; typedef ACE_TYPENAME ACE_CB::ACE_Malloc_Header MALLOC_HEADER; // = Initialization method. + /// if <name> = 0 it will iterate through everything else only + /// through those entries whose <name> match. ACE_Malloc_LIFO_Iterator_T (ACE_Malloc_T<ACE_MEM_POOL_2, ACE_LOCK, ACE_CB> &malloc, const char *name = 0); - // if <name> = 0 it will iterate through everything else only - // through those entries whose <name> match. ~ACE_Malloc_LIFO_Iterator_T (void); // = Iteration methods. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Pass back the next <entry> in the set that hasn't yet been + /// visited. Returns 0 when all items have been seen, else 1. int next (void *&next_entry); - // Pass back the next <entry> in the set that hasn't yet been - // visited. Returns 0 when all items have been seen, else 1. + /** + * Pass back the next <entry> (and the <name> associated with it) in + * the set that hasn't yet been visited. Returns 0 when all items + * have been seen, else 1. + */ int next (void *&next_entry, const char *&name); - // Pass back the next <entry> (and the <name> associated with it) in - // the set that hasn't yet been visited. Returns 0 when all items - // have been seen, else 1. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Malloc we are iterating over. ACE_Malloc_T<ACE_MEM_POOL_2, ACE_LOCK, ACE_CB> &malloc_; - // Malloc we are iterating over. + /// Keeps track of how far we've advanced... NAME_NODE *curr_; - // Keeps track of how far we've advanced... + /// Lock Malloc for the lifetime of the iterator. ACE_Read_Guard<ACE_LOCK> guard_; - // Lock Malloc for the lifetime of the iterator. + /// Name that we are searching for. const char *name_; - // Name that we are searching for. }; +/** + * @class ACE_Malloc_FIFO_Iterator_T + * + * @brief FIFO iterator for names stored in Malloc'd memory. + * + * Does not support deletions while iteration is occurring. + */ template <ACE_MEM_POOL_1, class ACE_LOCK, class ACE_CB> class ACE_Malloc_FIFO_Iterator_T { - // = TITLE - // FIFO iterator for names stored in Malloc'd memory. - // - // = DESCRIPTION - // Does not support deletions while iteration is occurring. public: typedef ACE_TYPENAME ACE_CB::ACE_Name_Node NAME_NODE; typedef ACE_TYPENAME ACE_CB::ACE_Malloc_Header MALLOC_HEADER; // = Initialization method. + /// if <name> = 0 it will iterate through everything else only + /// through those entries whose <name> match. ACE_Malloc_FIFO_Iterator_T (ACE_Malloc_T<ACE_MEM_POOL_2, ACE_LOCK, ACE_CB> &malloc, const char *name = 0); - // if <name> = 0 it will iterate through everything else only - // through those entries whose <name> match. ~ACE_Malloc_FIFO_Iterator_T (void); // = Iteration methods. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Pass back the next <entry> in the set that hasn't yet been + /// visited. Returns 0 when all items have been seen, else 1. int next (void *&next_entry); - // Pass back the next <entry> in the set that hasn't yet been - // visited. Returns 0 when all items have been seen, else 1. + /** + * Pass back the next <entry> (and the <name> associated with it) in + * the set that hasn't yet been visited. Returns 0 when all items + * have been seen, else 1. + */ int next (void *&next_entry, const char *&name); - // Pass back the next <entry> (and the <name> associated with it) in - // the set that hasn't yet been visited. Returns 0 when all items - // have been seen, else 1. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Go to the starting element that was inserted first. Returns 0 + /// when there is no item in the set, else 1. int start (void); - // Go to the starting element that was inserted first. Returns 0 - // when there is no item in the set, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Malloc we are iterating over. ACE_Malloc_T<ACE_MEM_POOL_2, ACE_LOCK, ACE_CB> &malloc_; - // Malloc we are iterating over. + /// Keeps track of how far we've advanced... NAME_NODE *curr_; - // Keeps track of how far we've advanced... + /// Lock Malloc for the lifetime of the iterator. ACE_Read_Guard<ACE_LOCK> guard_; - // Lock Malloc for the lifetime of the iterator. + /// Name that we are searching for. const char *name_; - // Name that we are searching for. }; template <ACE_MEM_POOL_1, class ACE_LOCK> @@ -589,27 +637,31 @@ class ACE_Malloc : public ACE_Malloc_T<ACE_MEM_POOL_2, ACE_LOCK, ACE_Control_Blo { public: // = Initialization and termination methods. + /** + * Initialize ACE_Malloc. This constructor passes <pool_name> to + * initialize the memory pool, and uses <ACE::basename> to + * automatically extract out the name used for the underlying lock + * name (if necessary). + */ ACE_Malloc (const ACE_TCHAR *pool_name = 0); - // Initialize ACE_Malloc. This constructor passes <pool_name> to - // initialize the memory pool, and uses <ACE::basename> to - // automatically extract out the name used for the underlying lock - // name (if necessary). + /** + * Initialize ACE_Malloc. This constructor passes <pool_name> to + * initialize the memory pool, and uses <lock_name> to automatically + * extract out the name used for the underlying lock name (if + * necessary). In addition, <options> is passed through to + * initialize the underlying memory pool. + */ ACE_Malloc (const ACE_TCHAR *pool_name, const ACE_TCHAR *lock_name, const ACE_MEM_POOL_OPTIONS *options = 0); - // Initialize ACE_Malloc. This constructor passes <pool_name> to - // initialize the memory pool, and uses <lock_name> to automatically - // extract out the name used for the underlying lock name (if - // necessary). In addition, <options> is passed through to - // initialize the underlying memory pool. #if !defined (ACE_HAS_TEMPLATE_TYPEDEFS) + /// This is necessary to work around template bugs with certain C++ + /// compilers. ACE_Malloc (const ACE_TCHAR *pool_name, const ACE_TCHAR *lock_name, const void *options = 0); - // This is necessary to work around template bugs with certain C++ - // compilers. #endif /* ACE_HAS_TEMPLATE_TYPEDEFS */ }; @@ -618,10 +670,10 @@ class ACE_Malloc_LIFO_Iterator : public ACE_Malloc_LIFO_Iterator_T<ACE_MEM_POOL_ { public: // = Initialization method. + /// if <name> = 0 it will iterate through everything else only + /// through those entries whose <name> match. ACE_Malloc_LIFO_Iterator (ACE_Malloc<ACE_MEM_POOL_2, ACE_LOCK> &malloc, const char *name = 0); - // if <name> = 0 it will iterate through everything else only - // through those entries whose <name> match. }; template <ACE_MEM_POOL_1, class ACE_LOCK> @@ -629,10 +681,10 @@ class ACE_Malloc_FIFO_Iterator : public ACE_Malloc_FIFO_Iterator_T<ACE_MEM_POOL_ { public: // = Initialization method. + /// if <name> = 0 it will iterate through everything else only + /// through those entries whose <name> match. ACE_Malloc_FIFO_Iterator (ACE_Malloc<ACE_MEM_POOL_2, ACE_LOCK> &malloc, const char *name = 0); - // if <name> = 0 it will iterate through everything else only - // through those entries whose <name> match. }; #if defined (__ACE_INLINE__) diff --git a/ace/Managed_Object.h b/ace/Managed_Object.h index d5b8eb71d8d..7b96dd8fdaa 100644 --- a/ace/Managed_Object.h +++ b/ace/Managed_Object.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Managed_Object.h -// -// = AUTHORS -// David L. Levine -// -// ============================================================================ + +//============================================================================= +/** + * @file Managed_Object.h + * + * $Id$ + * + * @author David L. Levine + */ +//============================================================================= + #ifndef ACE_MANAGED_OBJECT_H #define ACE_MANAGED_OBJECT_H @@ -26,78 +23,78 @@ #include "ace/Object_Manager.h" +/** + * @class ACE_Cleanup_Adapter + * + * @brief Adapter for ACE_Cleanup objects that allows them to be readily + * managed by the ACE_Object_Manager. + * + * This template class adapts an object of any type to be an + * ACE_Cleanup object. The object can then be destroyed + * type-safely by the ACE_Object_Manager. This class is + * typically used to replace a cast; but, it's a bit cleaner and + * allows insertion of, say, run-time type identification + * internally if desired. + */ template <class TYPE> class ACE_Cleanup_Adapter : public ACE_Cleanup { - // = TITLE - // Adapter for ACE_Cleanup objects that allows them to be readily - // managed by the ACE_Object_Manager. - // - // = DESCRIPTION - // This template class adapts an object of any type to be an - // ACE_Cleanup object. The object can then be destroyed - // type-safely by the ACE_Object_Manager. This class is - // typically used to replace a cast; but, it's a bit cleaner and - // allows insertion of, say, run-time type identification - // internally if desired. public: + /// Default constructor. ACE_Cleanup_Adapter (void); - // Default constructor. + /// Virtual destructor, needed by some compilers for vtable placement. virtual ~ACE_Cleanup_Adapter (void); - // Virtual destructor, needed by some compilers for vtable placement. + /// Accessor for contained object. TYPE &object (void); - // Accessor for contained object. private: + /// Contained object. TYPE object_; - // Contained object. }; +/** + * @class ACE_Managed_Object + * + * @brief Wrapper for interface to allocate an object managed by the + * ACE_Object_Manager. + * + * This template class wraps an interface that is used to + * allocate and access an object that is managed by the + * ACE_Object_Manager. Because static template member functions + * are not supported by some compilers, it is a separate + * (template) class. + * This interface is typically used to replace a static object + * with one that is dynamically allocated. It helps to avoid + * problems with order of static object + * construction/destruction. Managed objects won't be allocated + * until needed, but should be allocated when first needed. And + * they are destroyed in the reverse order of construction. + * <get_preallocated_object> accesses a "preallocated" object, + * i.e., one that is identified by a value in the + * ACE_Object_Manager:: Preallocated_Object enum. These objects + * are used internally by the ACE library. + * Hooks are provided for the application to preallocate objects + * via the same mechanism. + * ACE_APPLICATION_PREALLOCATED_OBJECT_DECLARATIONS can be used + * to define enum values; + * ACE_APPLICATION_PREALLOCATED_OBJECT_DEFINITIONS can be used + * to define the corresponding objects. The format of the ACE + * internal library definitions should be followed. And + * similarly, ACE_APPLICATION_PREALLOCATED_ARRAY_DECLARATIONS + * and ACE_APPLICATION_PREALLOCATED_ARRAY_DEFINITIONS can be + * used to preallocate arrays. + * By default, preallocation uses dynamic allocation. The + * preallocated objects and arrays are allocated off the heap in + * the ACE_Object_Manager constructor. To statically place the + * preallocated objects in program global data instead of on the + * heap, #define ACE_HAS_STATIC_PREALLOCATION prior to building + * the ACE library. + */ template <class TYPE> class ACE_Managed_Object { - // = TITLE - // Wrapper for interface to allocate an object managed by the - // ACE_Object_Manager. - // - // = DESCRIPTION - // This template class wraps an interface that is used to - // allocate and access an object that is managed by the - // ACE_Object_Manager. Because static template member functions - // are not supported by some compilers, it is a separate - // (template) class. - // - // This interface is typically used to replace a static object - // with one that is dynamically allocated. It helps to avoid - // problems with order of static object - // construction/destruction. Managed objects won't be allocated - // until needed, but should be allocated when first needed. And - // they are destroyed in the reverse order of construction. - // - // <get_preallocated_object> accesses a "preallocated" object, - // i.e., one that is identified by a value in the - // ACE_Object_Manager:: Preallocated_Object enum. These objects - // are used internally by the ACE library. - // - // Hooks are provided for the application to preallocate objects - // via the same mechanism. - // ACE_APPLICATION_PREALLOCATED_OBJECT_DECLARATIONS can be used - // to define enum values; - // ACE_APPLICATION_PREALLOCATED_OBJECT_DEFINITIONS can be used - // to define the corresponding objects. The format of the ACE - // internal library definitions should be followed. And - // similarly, ACE_APPLICATION_PREALLOCATED_ARRAY_DECLARATIONS - // and ACE_APPLICATION_PREALLOCATED_ARRAY_DEFINITIONS can be - // used to preallocate arrays. - // - // By default, preallocation uses dynamic allocation. The - // preallocated objects and arrays are allocated off the heap in - // the ACE_Object_Manager constructor. To statically place the - // preallocated objects in program global data instead of on the - // heap, #define ACE_HAS_STATIC_PREALLOCATION prior to building - // the ACE library. public: static TYPE *get_preallocated_object (ACE_Object_Manager::Preallocated_Object id) { diff --git a/ace/Map.h b/ace/Map.h index 28445cf4356..a8334f72cb6 100644 --- a/ace/Map.h +++ b/ace/Map.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Map.h -// -// = AUTHOR -// Irfan Pyarali -// -// ============================================================================ +//============================================================================= +/** + * @file Map.h + * + * $Id$ + * + * @author Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_MAP_H #define ACE_MAP_H diff --git a/ace/Map_Manager.h b/ace/Map_Manager.h index bbeba53473e..3a497cdb8b4 100644 --- a/ace/Map_Manager.h +++ b/ace/Map_Manager.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Map_Manager.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Map_Manager.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_MAP_MANAGER_H #define ACE_MAP_MANAGER_H @@ -30,51 +27,54 @@ // Forward declaration. class ACE_Allocator; +/** + * @class ACE_Map_Entry + * + * @brief An entry in the Map. + */ template <class EXT_ID, class INT_ID> class ACE_Map_Entry { - // = TITLE - // An entry in the Map. public: # if ! defined (ACE_HAS_BROKEN_NOOP_DTORS) + /// We need this destructor to keep some compilers from complaining. + /// It's just a no-op, however. ~ACE_Map_Entry (void); - // We need this destructor to keep some compilers from complaining. - // It's just a no-op, however. # endif /* ! defined (ACE_HAS_BROKEN_NOOP_DTORS) */ + /// Key used to look up an entry. EXT_ID ext_id_; - // Key used to look up an entry. + /// The contents of the entry itself. INT_ID int_id_; - // The contents of the entry itself. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. // = These are really private, but unfortunately template friends // are not portable. + /// Get/Set next entry. size_t next (void) const; void next (size_t n); - // Get/Set next entry. + /// Get/Set prev entry. size_t prev (void) const; void prev (size_t p); - // Get/Set prev entry. + /// Keeps track of the next entry. size_t next_; - // Keeps track of the next entry. + /// Keeps track of the previous entry. size_t prev_; - // Keeps track of the previous entry. #if defined (ACE_HAS_LAZY_MAP_MANAGER) + /// Is this entry free? int free_; - // Is this entry free? #endif /* ACE_HAS_LAZY_MAP_MANAGER */ @@ -92,25 +92,25 @@ class ACE_Map_Iterator; template <class EXT_ID, class INT_ID, class ACE_LOCK> class ACE_Map_Reverse_Iterator; +/** + * @class ACE_Map_Manager + * + * @brief Define a map abstraction that associates <EXT_ID>s with + * <INT_ID>s. + * + * The <EXT_ID> must support <operator==>. This constraint can + * be alleviated via template specialization, as shown in the + * $ACE_ROOT/tests/Conn_Test.cpp test. + * This class uses an <ACE_Allocator> to allocate memory. The + * user can make this a persistant class by providing an + * <ACE_Allocator> with a persistable memory pool. + * This implementation of a map uses an array, which is searched + * linearly. For more efficient searching you should use the + * <ACE_Hash_Map_Manager>. + */ template <class EXT_ID, class INT_ID, class ACE_LOCK> class ACE_Map_Manager { - // = TITLE - // Define a map abstraction that associates <EXT_ID>s with - // <INT_ID>s. - // - // = DESCRIPTION - // The <EXT_ID> must support <operator==>. This constraint can - // be alleviated via template specialization, as shown in the - // $ACE_ROOT/tests/Conn_Test.cpp test. - // - // This class uses an <ACE_Allocator> to allocate memory. The - // user can make this a persistant class by providing an - // <ACE_Allocator> with a persistable memory pool. - // - // This implementation of a map uses an array, which is searched - // linearly. For more efficient searching you should use the - // <ACE_Hash_Map_Manager>. public: friend class ACE_Map_Iterator_Base<EXT_ID, INT_ID, ACE_LOCK>; friend class ACE_Map_Iterator<EXT_ID, INT_ID, ACE_LOCK>; @@ -127,118 +127,132 @@ public: typedef ACE_Map_Reverse_Iterator<EXT_ID, INT_ID, ACE_LOCK> reverse_iterator; // = Initialization and termination methods. + /// Initialize a <Map_Manager> with the <ACE_DEFAULT_MAP_SIZE>. ACE_Map_Manager (ACE_Allocator *alloc = 0); - // Initialize a <Map_Manager> with the <ACE_DEFAULT_MAP_SIZE>. + /// Initialize a <Map_Manager> with <size> entries. ACE_Map_Manager (size_t size, ACE_Allocator *alloc = 0); - // Initialize a <Map_Manager> with <size> entries. + /// Initialize a <Map_Manager> with size <length>. int open (size_t length = ACE_DEFAULT_MAP_SIZE, ACE_Allocator *alloc = 0); - // Initialize a <Map_Manager> with size <length>. + /// Close down a <Map_Manager> and release dynamically allocated + /// resources. int close (void); - // Close down a <Map_Manager> and release dynamically allocated - // resources. + /// Close down a <Map_Manager> and release dynamically allocated + /// resources. ~ACE_Map_Manager (void); - // Close down a <Map_Manager> and release dynamically allocated - // resources. + /** + * Associate <ext_id> with <int_id>. If <ext_id> is already in the + * map then the <Map_Entry> is not changed. Returns 0 if a new + * entry is bound successfully, returns 1 if an attempt is made to + * bind an existing entry, and returns -1 if failures occur. + */ int bind (const EXT_ID &ext_id, const INT_ID &int_id); - // Associate <ext_id> with <int_id>. If <ext_id> is already in the - // map then the <Map_Entry> is not changed. Returns 0 if a new - // entry is bound successfully, returns 1 if an attempt is made to - // bind an existing entry, and returns -1 if failures occur. + /** + * Reassociate <ext_id> with <int_id>. If <ext_id> is not in the + * map then behaves just like <bind>. Otherwise, store the old + * values of <ext_id> and <int_id> into the "out" parameters and + * rebind the new parameters. This is very useful if you need to + * have an atomic way of updating <Map_Entries> and you also need + * full control over memory allocation. Returns 0 if a new entry is + * bound successfully, returns 1 if an existing entry was rebound, + * and returns -1 if failures occur. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, EXT_ID &old_ext_id, INT_ID &old_int_id); - // Reassociate <ext_id> with <int_id>. If <ext_id> is not in the - // map then behaves just like <bind>. Otherwise, store the old - // values of <ext_id> and <int_id> into the "out" parameters and - // rebind the new parameters. This is very useful if you need to - // have an atomic way of updating <Map_Entries> and you also need - // full control over memory allocation. Returns 0 if a new entry is - // bound successfully, returns 1 if an existing entry was rebound, - // and returns -1 if failures occur. + /** + * Reassociate <ext_id> with <int_id>. If <ext_id> is not in the + * map then behaves just like <bind>. Otherwise, store the old + * values of <int_id> into the "out" parameter and rebind the new + * parameters. Returns 0 if a new entry is bound successfully, + * returns 1 if an existing entry was rebound, and returns -1 if + * failures occur. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, INT_ID &old_int_id); - // Reassociate <ext_id> with <int_id>. If <ext_id> is not in the - // map then behaves just like <bind>. Otherwise, store the old - // values of <int_id> into the "out" parameter and rebind the new - // parameters. Returns 0 if a new entry is bound successfully, - // returns 1 if an existing entry was rebound, and returns -1 if - // failures occur. + /// Reassociate <ext_id> with <int_id>. Old values in the map are + /// ignored. int rebind (const EXT_ID &ext_id, const INT_ID &int_id); - // Reassociate <ext_id> with <int_id>. Old values in the map are - // ignored. + /** + * Associate <ext_id> with <int_id> if and only if <ext_id> is not + * in the map. If <ext_id> is already in the map then the <int_id> + * parameter is overwritten with the existing value in the map + * Returns 0 if a new entry is bound successfully, returns 1 if an + * attempt is made to bind an existing entry, and returns -1 if + * failures occur. + */ int trybind (const EXT_ID &ext_id, INT_ID &int_id); - // Associate <ext_id> with <int_id> if and only if <ext_id> is not - // in the map. If <ext_id> is already in the map then the <int_id> - // parameter is overwritten with the existing value in the map - // Returns 0 if a new entry is bound successfully, returns 1 if an - // attempt is made to bind an existing entry, and returns -1 if - // failures occur. + /// Locate <ext_id> and pass out parameter via <int_id>. If found, + /// returns and non-negative integer; returns -1 if not found. int find (const EXT_ID &ext_id, INT_ID &int_id) const; - // Locate <ext_id> and pass out parameter via <int_id>. If found, - // returns and non-negative integer; returns -1 if not found. + /// Returns a non-negative integer if the <ext_id> is in the mapping, otherwise -1. int find (const EXT_ID &ext_id) const; - // Returns a non-negative integer if the <ext_id> is in the mapping, otherwise -1. + /** + * Unbind (remove) the <ext_id> from the map. Don't return the + * <int_id> to the caller (this is useful for collections where the + * <int_id>s are *not* dynamically allocated...) Returns 0 if + * successful, else -1. + */ int unbind (const EXT_ID &ext_id); - // Unbind (remove) the <ext_id> from the map. Don't return the - // <int_id> to the caller (this is useful for collections where the - // <int_id>s are *not* dynamically allocated...) Returns 0 if - // successful, else -1. + /** + * Break any association of <ext_id>. Returns the value of <int_id> + * in case the caller needs to deallocate memory. Returns 0 if + * successful, else -1. + */ int unbind (const EXT_ID &ext_id, INT_ID &int_id); - // Break any association of <ext_id>. Returns the value of <int_id> - // in case the caller needs to deallocate memory. Returns 0 if - // successful, else -1. + /// Return the current size of the map. size_t current_size (void) const; - // Return the current size of the map. + /// Return the total size of the map. size_t total_size (void) const; - // Return the total size of the map. + /** + * Returns a reference to the underlying <ACE_LOCK>. This makes it + * possible to acquire the lock explicitly, which can be useful in + * some cases if you instantiate the <ACE_Atomic_Op> with an + * <ACE_Recursive_Mutex> or <ACE_Process_Mutex>, or if you need to + * guard the state of an iterator. NOTE: the right name would be + * <lock>, but HP/C++ will choke on that! + */ ACE_LOCK &mutex (void); - // Returns a reference to the underlying <ACE_LOCK>. This makes it - // possible to acquire the lock explicitly, which can be useful in - // some cases if you instantiate the <ACE_Atomic_Op> with an - // <ACE_Recursive_Mutex> or <ACE_Process_Mutex>, or if you need to - // guard the state of an iterator. NOTE: the right name would be - // <lock>, but HP/C++ will choke on that! + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL styled iterator factory functions. + /// Return forward iterator. ACE_Map_Iterator<EXT_ID, INT_ID, ACE_LOCK> begin (void); ACE_Map_Iterator<EXT_ID, INT_ID, ACE_LOCK> end (void); - // Return forward iterator. + /// Return reverse iterator. ACE_Map_Reverse_Iterator<EXT_ID, INT_ID, ACE_LOCK> rbegin (void); ACE_Map_Reverse_Iterator<EXT_ID, INT_ID, ACE_LOCK> rend (void); - // Return reverse iterator. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: @@ -247,133 +261,135 @@ protected: // These methods assume that the locks are held by the private // methods. + /// Performs the binding of <ext_id> to <int_id>. Must be called + /// with locks held. int bind_i (const EXT_ID &ext_id, const INT_ID &int_id); - // Performs the binding of <ext_id> to <int_id>. Must be called - // with locks held. + /// Bind an entry (without finding first). Must be called with locks + /// held. int shared_bind (const EXT_ID &ext_id, const INT_ID &int_id); - // Bind an entry (without finding first). Must be called with locks - // held. + /// Performs a rebinding of <ext_it> to <int_id>. Also, recovers old + /// values. Must be called with locks held. int rebind_i (const EXT_ID &ext_id, const INT_ID &int_id, EXT_ID &old_ext_id, INT_ID &old_int_id); - // Performs a rebinding of <ext_it> to <int_id>. Also, recovers old - // values. Must be called with locks held. + /// Performs a rebinding of <ext_it> to <int_id>. Also, recovers old + /// values. Must be called with locks held. int rebind_i (const EXT_ID &ext_id, const INT_ID &int_id, INT_ID &old_int_id); - // Performs a rebinding of <ext_it> to <int_id>. Also, recovers old - // values. Must be called with locks held. + /// Performs a rebinding of <ext_it> to <int_id>. Must be called + /// with locks held. int rebind_i (const EXT_ID &ext_id, const INT_ID &int_id); - // Performs a rebinding of <ext_it> to <int_id>. Must be called - // with locks held. + /// Performs a conditional bind of <int_id> using <ext_id> as the + /// key. Must be called with locks held. int trybind_i (const EXT_ID &ext_id, INT_ID &int_id); - // Performs a conditional bind of <int_id> using <ext_id> as the - // key. Must be called with locks held. + /// Performs a find of <int_id> using <ext_id> as the key. Must be + /// called with locks held. int find_i (const EXT_ID &ext_id, INT_ID &int_id); - // Performs a find of <int_id> using <ext_id> as the key. Must be - // called with locks held. + /// Performs a find using <ext_id> as the key. Must be called with + /// locks held. int find_and_return_index (const EXT_ID &ext_id, size_t &slot); - // Performs a find using <ext_id> as the key. Must be called with - // locks held. + /// Performs an unbind of <int_id> using <ext_id> as the key. Must + /// be called with locks held. int unbind_i (const EXT_ID &ext_id, INT_ID &int_id); - // Performs an unbind of <int_id> using <ext_id> as the key. Must - // be called with locks held. + /// Performs an unbind using <ext_id> as the key. Must be called + /// with locks held. int unbind_i (const EXT_ID &ext_id); - // Performs an unbind using <ext_id> as the key. Must be called - // with locks held. + /// Performs an unbind using <ext_id> as the key. Must be called + /// with locks held. int unbind_and_return_index (const EXT_ID &ext_id, size_t &slot); - // Performs an unbind using <ext_id> as the key. Must be called - // with locks held. + /// Resize the map. Must be called with locks held. int resize_i (size_t size); - // Resize the map. Must be called with locks held. + /// Close down a <Map_Manager>. Must be called with locks held. int close_i (void); - // Close down a <Map_Manager>. Must be called with locks held. + /// Returns 1 if <id1> == <id2>, else 0. This is defined as a + /// separate method to facilitate template specialization. int equal (const EXT_ID &id1, const EXT_ID &id2); - // Returns 1 if <id1> == <id2>, else 0. This is defined as a - // separate method to facilitate template specialization. + /// This function returns the new size of the Map Manager. This + /// function is called when we run out of room and need to resize. size_t new_size (void); - // This function returns the new size of the Map Manager. This - // function is called when we run out of room and need to resize. + /// Explicitly call the destructors and free up the + /// <search_structure_>. void free_search_structure (void); - // Explicitly call the destructors and free up the - // <search_structure_>. + /// Id of the free list sentinel. size_t free_list_id (void) const; - // Id of the free list sentinel. + /// Id of the occupied list sentinel. size_t occupied_list_id (void) const; - // Id of the occupied list sentinel. + /// Finds the next free slot. int next_free (size_t &slot); - // Finds the next free slot. + /// Move from free list to occupied list. void move_from_free_list_to_occupied_list (size_t slot); - // Move from free list to occupied list. + /// Move from occupied list to free list. void move_from_occupied_list_to_free_list (size_t slot); - // Move from occupied list to free list. #if defined (ACE_HAS_LAZY_MAP_MANAGER) + /** + * In the case of lazy map managers, the movement of free slots from + * the occupied list to the free list is delayed until we run out of + * free slots in the free list. This function goes through the + * entire occupied list, moving free slots to the free list. + */ void move_all_free_slots_from_occupied_list (void); - // In the case of lazy map managers, the movement of free slots from - // the occupied list to the free list is delayed until we run out of - // free slots in the free list. This function goes through the - // entire occupied list, moving free slots to the free list. #endif /* ACE_HAS_LAZY_MAP_MANAGER */ + /// Move helper. void shared_move (size_t slot, ACE_Map_Entry<EXT_ID, INT_ID> ¤t_list, size_t current_list_id, ACE_Map_Entry<EXT_ID, INT_ID> &new_list, size_t new_list_id); - // Move helper. + /// Pointer to a memory allocator. ACE_Allocator *allocator_; - // Pointer to a memory allocator. + /// Synchronization variable for the MT_SAFE <ACE_Map_Manager>. ACE_LOCK lock_; - // Synchronization variable for the MT_SAFE <ACE_Map_Manager>. + /// Implement the Map as a resizeable array of <ACE_Map_Entry>. ACE_Map_Entry<EXT_ID, INT_ID> *search_structure_; - // Implement the Map as a resizeable array of <ACE_Map_Entry>. + /// Total number of elements in this->search_structure_. size_t total_size_; - // Total number of elements in this->search_structure_. + /// Current size of the map. size_t cur_size_; - // Current size of the map. + /// Free list. ACE_Map_Entry<EXT_ID, INT_ID> free_list_; - // Free list. + /// Occupied list. ACE_Map_Entry<EXT_ID, INT_ID> occupied_list_; - // Occupied list. enum { @@ -391,76 +407,80 @@ private: ACE_UNIMPLEMENTED_FUNC (ACE_Map_Manager (const ACE_Map_Manager<EXT_ID, INT_ID, ACE_LOCK> &)) }; +/** + * @class ACE_Map_Iterator_Base + * + * @brief Iterator for the <ACE_Map_Manager>. + * + * This class factors out common code from its templatized + * subclasses. + */ template <class EXT_ID, class INT_ID, class ACE_LOCK> class ACE_Map_Iterator_Base { - // = TITLE - // Iterator for the <ACE_Map_Manager>. - // - // = DESCRIPTION - // This class factors out common code from its templatized - // subclasses. public: // = Initialization method. + /// Contructor. If head != 0, the iterator constructed is positioned + /// at the head of the map, it is positioned at the end otherwise. ACE_Map_Iterator_Base (ACE_Map_Manager <EXT_ID, INT_ID, ACE_LOCK> &mm); - // Contructor. If head != 0, the iterator constructed is positioned - // at the head of the map, it is positioned at the end otherwise. // = Iteration methods. + /// Pass back the next <entry> that hasn't been seen in the Set. + /// Returns 0 when all items have been seen, else 1. int next (ACE_Map_Entry<EXT_ID, INT_ID> *&next_entry) const; - // Pass back the next <entry> that hasn't been seen in the Set. - // Returns 0 when all items have been seen, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Returns a reference to the interal element <this> is pointing to. ACE_Map_Entry<EXT_ID, INT_ID>& operator* (void) const; - // Returns a reference to the interal element <this> is pointing to. + /// Returns reference the Map_Manager that is being iterated + /// over. ACE_Map_Manager<EXT_ID, INT_ID, ACE_LOCK>& map (void); - // Returns reference the Map_Manager that is being iterated - // over. + /// Check if two iterators point to the same position int operator== (const ACE_Map_Iterator_Base<EXT_ID, INT_ID, ACE_LOCK> &) const; int operator!= (const ACE_Map_Iterator_Base<EXT_ID, INT_ID, ACE_LOCK> &) const; - // Check if two iterators point to the same position + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Move forward by one element in the set. Returns 0 when there's + /// no more item in the set after the current items, else 1. int forward_i (void); - // Move forward by one element in the set. Returns 0 when there's - // no more item in the set after the current items, else 1. + /// Move backware by one element in the set. Returns 0 when there's + /// no more item in the set before the current item, else 1. int reverse_i (void); - // Move backware by one element in the set. Returns 0 when there's - // no more item in the set before the current item, else 1. + /// Dump the state of an object. void dump_i (void) const; - // Dump the state of an object. + /// Map we are iterating over. ACE_Map_Manager <EXT_ID, INT_ID, ACE_LOCK> *map_man_; - // Map we are iterating over. + /// Keeps track of how far we've advanced... size_t next_; - // Keeps track of how far we've advanced... }; +/** + * @class ACE_Map_Iterator + * + * @brief Forward iterator for the <ACE_Map_Manager>. + * + * This class does not perform any internal locking of the + * <ACE_Map_Manager> it is iterating upon since locking is + * inherently inefficient and/or error-prone within an STL-style + * iterator. If you require locking, you can explicitly use an + * <ACE_Guard> or <ACE_Read_Guard> on the <ACE_Map_Manager>'s + * internal lock, which is accessible via its <mutex> method. + */ template <class EXT_ID, class INT_ID, class ACE_LOCK> class ACE_Map_Iterator : public ACE_Map_Iterator_Base<EXT_ID, INT_ID, ACE_LOCK> { - // = TITLE - // Forward iterator for the <ACE_Map_Manager>. - // - // = DESCRIPTION - // This class does not perform any internal locking of the - // <ACE_Map_Manager> it is iterating upon since locking is - // inherently inefficient and/or error-prone within an STL-style - // iterator. If you require locking, you can explicitly use an - // <ACE_Guard> or <ACE_Read_Guard> on the <ACE_Map_Manager>'s - // internal lock, which is accessible via its <mutex> method. public: // = Initialization method. ACE_Map_Iterator (ACE_Map_Manager <EXT_ID, INT_ID, ACE_LOCK> &mm, @@ -468,44 +488,46 @@ public: // = Iteration methods. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL styled iteration, compare, and reference functions. + /// Prefix advance. ACE_Map_Iterator<EXT_ID, INT_ID, ACE_LOCK> &operator++ (void); - // Prefix advance. + /// Postfix advance. ACE_Map_Iterator<EXT_ID, INT_ID, ACE_LOCK> operator++ (int); - // Postfix advance. + /// Prefix reverse. ACE_Map_Iterator<EXT_ID, INT_ID, ACE_LOCK> &operator-- (void); - // Prefix reverse. + /// Postfix reverse. ACE_Map_Iterator<EXT_ID, INT_ID, ACE_LOCK> operator-- (int); - // Postfix reverse. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Map_Reverse_Iterator + * + * @brief Reverse Iterator for the <ACE_Map_Manager>. + * + * This class does not perform any internal locking of the + * <ACE_Map_Manager> it is iterating upon since locking is + * inherently inefficient and/or error-prone within an STL-style + * iterator. If you require locking, you can explicitly use an + * <ACE_Guard> or <ACE_Read_Guard> on the <ACE_Map_Manager>'s + * internal lock, which is accessible via its <mutex> method. + */ template <class EXT_ID, class INT_ID, class ACE_LOCK> class ACE_Map_Reverse_Iterator : public ACE_Map_Iterator_Base<EXT_ID, INT_ID, ACE_LOCK> { - // = TITLE - // Reverse Iterator for the <ACE_Map_Manager>. - // - // = DESCRIPTION - // This class does not perform any internal locking of the - // <ACE_Map_Manager> it is iterating upon since locking is - // inherently inefficient and/or error-prone within an STL-style - // iterator. If you require locking, you can explicitly use an - // <ACE_Guard> or <ACE_Read_Guard> on the <ACE_Map_Manager>'s - // internal lock, which is accessible via its <mutex> method. public: // = Initialization method. ACE_Map_Reverse_Iterator (ACE_Map_Manager <EXT_ID, INT_ID, ACE_LOCK> &mm, @@ -513,29 +535,29 @@ public: // = Iteration methods. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL styled iteration, compare, and reference functions. + /// Prefix reverse. ACE_Map_Reverse_Iterator<EXT_ID, INT_ID, ACE_LOCK> &operator++ (void); - // Prefix reverse. + /// Postfix reverse. ACE_Map_Reverse_Iterator<EXT_ID, INT_ID, ACE_LOCK> operator++ (int); - // Postfix reverse. + /// Prefix advance. ACE_Map_Reverse_Iterator<EXT_ID, INT_ID, ACE_LOCK> &operator-- (void); - // Prefix advance. + /// Postfix advance. ACE_Map_Reverse_Iterator<EXT_ID, INT_ID, ACE_LOCK> operator-- (int); - // Postfix advance. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if defined (__ACE_INLINE__) diff --git a/ace/Map_T.h b/ace/Map_T.h index 7d970d198b4..b5a43b303c3 100644 --- a/ace/Map_T.h +++ b/ace/Map_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Map_T.h -// -// = AUTHOR -// Irfan Pyarali <irfan@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Map_T.h + * + * $Id$ + * + * @author Irfan Pyarali <irfan@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_MAP_T_H #define ACE_MAP_T_H @@ -28,224 +25,237 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Noop_Key_Generator + * + * @brief Defines a noop key generator. + */ template <class T> class ACE_Noop_Key_Generator { - // = TITLE - // Defines a noop key generator. public: + /// Functor method: generates a new key. int operator () (T &); - // Functor method: generates a new key. }; +/** + * @class ACE_Incremental_Key_Generator + * + * @brief Defines a simple incremental key generator. + * + * Generates a new key of type T by incrementing current + * value. Requirements on T are: + * - Constructor that accepts 0 in the constructor. + * - Prefix increment. + * - Assignment. + * Note that a primitive types such as u_long, int, etc., are + * suitable for this class. + */ template <class T> class ACE_Incremental_Key_Generator { - // = TITLE - // Defines a simple incremental key generator. - // - // = DESCRIPTION - // Generates a new key of type T by incrementing current - // value. Requirements on T are: - // - // - Constructor that accepts 0 in the constructor. - // - Prefix increment. - // - Assignment. - // - // Note that a primitive types such as u_long, int, etc., are - // suitable for this class. public: + /// Constructor. ACE_Incremental_Key_Generator (void); - // Constructor. + /// Functor method: generates a new key. int operator () (T &t); - // Functor method: generates a new key. + /// Returns the current value. T& current_value (void); - // Returns the current value. protected: + /// Current value. T t_; - // Current value. }; +/** + * @class ACE_Iterator_Impl + * + * @brief Defines a abstract iterator. + * + * Implementation to be provided by subclasses. + */ template <class T> class ACE_Iterator_Impl { - // = TITLE - // Defines a abstract iterator. - // - // = DESCRIPTION - // Implementation to be provided by subclasses. public: + /// Destructor. virtual ~ACE_Iterator_Impl (void); - // Destructor. + /// Clone. virtual ACE_Iterator_Impl<T> *clone (void) const = 0; - // Clone. + /// Comparison. virtual int compare (const ACE_Iterator_Impl<T> &rhs) const = 0; - // Comparison. + /// Dereference. virtual T dereference (void) const = 0; - // Dereference. + /// Advance. virtual void plus_plus (void) = 0; - // Advance. + /// Reverse. virtual void minus_minus (void) = 0; - // Reverse. }; +/** + * @class ACE_Reverse_Iterator_Impl + * + * @brief Defines a abstract reverse iterator. + * + * Implementation to be provided by subclasses. + */ template <class T> class ACE_Reverse_Iterator_Impl { - // = TITLE - // Defines a abstract reverse iterator. - // - // = DESCRIPTION - // Implementation to be provided by subclasses. public: + /// Destructor. virtual ~ACE_Reverse_Iterator_Impl (void); - // Destructor. + /// Clone. virtual ACE_Reverse_Iterator_Impl<T> *clone (void) const = 0; - // Clone. + /// Comparison. virtual int compare (const ACE_Reverse_Iterator_Impl<T> &rhs) const = 0; - // Comparison. + /// Dereference. virtual T dereference (void) const = 0; - // Dereference. + /// Advance. virtual void plus_plus (void) = 0; - // Advance. + /// Reverse. virtual void minus_minus (void) = 0; - // Reverse. }; +/** + * @class ACE_Iterator + * + * @brief Defines the iterator interface. + * + * Implementation to be provided by forwarding. + */ template <class T> class ACE_Iterator { - // = TITLE - // Defines the iterator interface. - // - // = DESCRIPTION - // Implementation to be provided by forwarding. public: // = Traits. typedef T value_type; typedef ACE_Iterator_Impl<T> implementation; + /// Constructor. ACE_Iterator (ACE_Iterator_Impl<T> *impl); - // Constructor. + /// Copy constructor. ACE_Iterator (const ACE_Iterator<T> &rhs); - // Copy constructor. + /// Destructor. ~ACE_Iterator (void); - // Destructor. + /// Assignment operator. ACE_Iterator<T> &operator= (const ACE_Iterator<T> &rhs); - // Assignment operator. + /// Comparison operators. int operator== (const ACE_Iterator<T> &rhs) const; int operator!= (const ACE_Iterator<T> &rhs) const; - // Comparison operators. + /// Dereference operator. T operator *() const; - // Dereference operator. + /// Prefix advance. ACE_Iterator<T> &operator++ (void); - // Prefix advance. + /// Postfix advance. ACE_Iterator<T> operator++ (int); - // Postfix advance. + /// Prefix reverse. ACE_Iterator<T> &operator-- (void); - // Prefix reverse. + /// Postfix reverse. ACE_Iterator<T> operator-- (int); - // Postfix reverse. + /// Accessor to implementation object. ACE_Iterator_Impl<T> &impl (void); - // Accessor to implementation object. protected: + /// Implementation pointer. ACE_Iterator_Impl<T> *implementation_; - // Implementation pointer. }; +/** + * @class ACE_Reverse_Iterator + * + * @brief Defines the reverse iterator interface. + * + * Implementation to be provided by forwarding. + */ template <class T> class ACE_Reverse_Iterator { - // = TITLE - // Defines the reverse iterator interface. - // - // = DESCRIPTION - // Implementation to be provided by forwarding. public: // = Traits. typedef T value_type; typedef ACE_Reverse_Iterator_Impl<T> implementation; + /// Constructor. ACE_Reverse_Iterator (ACE_Reverse_Iterator_Impl<T> *impl); - // Constructor. + /// Copy constructor. ACE_Reverse_Iterator (const ACE_Reverse_Iterator<T> &rhs); - // Copy constructor. + /// Destructor. ~ACE_Reverse_Iterator (void); - // Destructor. + /// Assignment operator. ACE_Reverse_Iterator<T> &operator= (const ACE_Reverse_Iterator<T> &rhs); - // Assignment operator. + /// Comparison operators. int operator== (const ACE_Reverse_Iterator<T> &rhs) const; int operator!= (const ACE_Reverse_Iterator<T> &rhs) const; - // Comparison operators. + /// Dereference operator. T operator *() const; - // Dereference operator. + /// Prefix advance. ACE_Reverse_Iterator<T> &operator++ (void); - // Prefix advance. + /// Postfix advance. ACE_Reverse_Iterator<T> operator++ (int); - // Postfix advance. + /// Prefix reverse. ACE_Reverse_Iterator<T> &operator-- (void); - // Prefix reverse. + /// Postfix reverse. ACE_Reverse_Iterator<T> operator-- (int); - // Postfix reverse. + /// Accessor to implementation object. ACE_Reverse_Iterator_Impl<T> &impl (void); - // Accessor to implementation object. protected: + /// Implementation pointer. ACE_Reverse_Iterator_Impl<T> *implementation_; - // Implementation pointer. }; +/** + * @class ACE_Map + * + * @brief Defines a map interface. + * + * Implementation to be provided by subclasses. + */ template <class KEY, class VALUE> class ACE_Map { - // = TITLE - // Defines a map interface. - // - // = DESCRIPTION - // Implementation to be provided by subclasses. public: // = Traits. @@ -264,136 +274,152 @@ public: typedef ACE_Reverse_Iterator_Impl<value_type> reverse_iterator_implementation; + /// Close down and release dynamically allocated resources. virtual ~ACE_Map (void); - // Close down and release dynamically allocated resources. + /// Initialize a <Map> with size <length>. virtual int open (size_t length = ACE_DEFAULT_MAP_SIZE, ACE_Allocator *alloc = 0) = 0; - // Initialize a <Map> with size <length>. + /// Close down a <Map> and release dynamically allocated resources. virtual int close (void) = 0; - // Close down a <Map> and release dynamically allocated resources. + /** + * Add <key>/<value> pair to the map. If <key> is already in the + * map then no changes are made and 1 is returned. Returns 0 on a + * successful addition. This function fails for maps that do not + * allow user specified keys. <key> is an "in" parameter. + */ virtual int bind (const KEY &key, const VALUE &value) = 0; - // Add <key>/<value> pair to the map. If <key> is already in the - // map then no changes are made and 1 is returned. Returns 0 on a - // successful addition. This function fails for maps that do not - // allow user specified keys. <key> is an "in" parameter. + /** + * Add <key>/<value> pair to the map. <key> is an "inout" parameter + * and maybe modified/extended by the map to add additional + * information. To recover original key, call the <recover_key> + * method. + */ virtual int bind_modify_key (const VALUE &value, KEY &key) = 0; - // Add <key>/<value> pair to the map. <key> is an "inout" parameter - // and maybe modified/extended by the map to add additional - // information. To recover original key, call the <recover_key> - // method. + /** + * Add <value> to the map, and the corresponding key produced by the + * Map is returned through <key> which is an "out" parameter. For + * maps that do not naturally produce keys, the map adapters will + * use the <KEY_GENERATOR> class to produce a key. However, the + * users are responsible for not jeopardizing this key production + * scheme by using user specified keys with keys produced by the key + * generator. + */ virtual int bind_create_key (const VALUE &value, KEY &key) = 0; - // Add <value> to the map, and the corresponding key produced by the - // Map is returned through <key> which is an "out" parameter. For - // maps that do not naturally produce keys, the map adapters will - // use the <KEY_GENERATOR> class to produce a key. However, the - // users are responsible for not jeopardizing this key production - // scheme by using user specified keys with keys produced by the key - // generator. + /** + * Add <value> to the map. The user does not care about the + * corresponding key produced by the Map. For maps that do not + * naturally produce keys, the map adapters will use the + * <KEY_GENERATOR> class to produce a key. However, the users are + * responsible for not jeopardizing this key production scheme by + * using user specified keys with keys produced by the key + * generator. + */ virtual int bind_create_key (const VALUE &value) = 0; - // Add <value> to the map. The user does not care about the - // corresponding key produced by the Map. For maps that do not - // naturally produce keys, the map adapters will use the - // <KEY_GENERATOR> class to produce a key. However, the users are - // responsible for not jeopardizing this key production scheme by - // using user specified keys with keys produced by the key - // generator. + /// Recovers the original key potentially modified by the map during + /// <bind_modify_key>. virtual int recover_key (const KEY &modified_key, KEY &original_key) = 0; - // Recovers the original key potentially modified by the map during - // <bind_modify_key>. + /** + * Reassociate <key> with <value>. The function fails if <key> is + * not in the map for maps that do not allow user specified keys. + * However, for maps that allow user specified keys, if the key is + * not in the map, a new <key>/<value> association is created. + */ virtual int rebind (const KEY &key, const VALUE &value) = 0; - // Reassociate <key> with <value>. The function fails if <key> is - // not in the map for maps that do not allow user specified keys. - // However, for maps that allow user specified keys, if the key is - // not in the map, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old value into the + * "out" parameter <old_value>. The function fails if <key> is not + * in the map for maps that do not allow user specified keys. + * However, for maps that allow user specified keys, if the key is + * not in the map, a new <key>/<value> association is created. + */ virtual int rebind (const KEY &key, const VALUE &value, VALUE &old_value) = 0; - // Reassociate <key> with <value>, storing the old value into the - // "out" parameter <old_value>. The function fails if <key> is not - // in the map for maps that do not allow user specified keys. - // However, for maps that allow user specified keys, if the key is - // not in the map, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old key and value + * into the "out" parameters <old_key> and <old_value>. The + * function fails if <key> is not in the map for maps that do not + * allow user specified keys. However, for maps that allow user + * specified keys, if the key is not in the map, a new <key>/<value> + * association is created. + */ virtual int rebind (const KEY &key, const VALUE &value, KEY &old_key, VALUE &old_value) = 0; - // Reassociate <key> with <value>, storing the old key and value - // into the "out" parameters <old_key> and <old_value>. The - // function fails if <key> is not in the map for maps that do not - // allow user specified keys. However, for maps that allow user - // specified keys, if the key is not in the map, a new <key>/<value> - // association is created. + /** + * Associate <key> with <value> if and only if <key> is not in the + * map. If <key> is already in the map, then the <value> parameter + * is overwritten with the existing value in the map. Returns 0 if a + * new <key>/<value> association is created. Returns 1 if an + * attempt is made to bind an existing entry. This function fails + * for maps that do not allow user specified keys. + */ virtual int trybind (const KEY &key, VALUE &value) = 0; - // Associate <key> with <value> if and only if <key> is not in the - // map. If <key> is already in the map, then the <value> parameter - // is overwritten with the existing value in the map. Returns 0 if a - // new <key>/<value> association is created. Returns 1 if an - // attempt is made to bind an existing entry. This function fails - // for maps that do not allow user specified keys. + /// Locate <value> associated with <key>. virtual int find (const KEY &key, VALUE &value) = 0; - // Locate <value> associated with <key>. + /// Is <key> in the map? virtual int find (const KEY &key) = 0; - // Is <key> in the map? + /// Remove <key> from the map. virtual int unbind (const KEY &key) = 0; - // Remove <key> from the map. + /// Remove <key> from the map, and return the <value> associated with + /// <key>. virtual int unbind (const KEY &key, VALUE &value) = 0; - // Remove <key> from the map, and return the <value> associated with - // <key>. + /// Return the current size of the map. virtual size_t current_size (void) const = 0; - // Return the current size of the map. + /// Return the total size of the map. virtual size_t total_size (void) const = 0; - // Return the total size of the map. + /// Dump the state of an object. virtual void dump (void) const = 0; - // Dump the state of an object. // = STL styled iterator factory functions. + /// Return forward iterator. iterator begin (void); iterator end (void); - // Return forward iterator. + /// Return reverse iterator. reverse_iterator rbegin (void); reverse_iterator rend (void); - // Return reverse iterator. protected: // = Protected no-op constructor. ACE_Map (void); + /// Return forward iterator. virtual ACE_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *begin_impl (void) = 0; virtual ACE_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *end_impl (void) = 0; - // Return forward iterator. + /// Return reverse iterator. virtual ACE_Reverse_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *rbegin_impl (void) = 0; virtual ACE_Reverse_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *rend_impl (void) = 0; - // Return reverse iterator. private: @@ -402,102 +428,108 @@ private: ACE_UNIMPLEMENTED_FUNC (ACE_Map (const ACE_Map<KEY, VALUE> &)) }; +/** + * @class ACE_Map_Impl_Iterator_Adapter + * + * @brief Defines a iterator implementation for the Map_Impl class. + * + * Implementation to be provided by <IMPLEMENTATION>. + */ template <class T, class IMPLEMENTATION, class ENTRY> class ACE_Map_Impl_Iterator_Adapter : public ACE_Iterator_Impl<T> { - // = TITLE - // Defines a iterator implementation for the Map_Impl class. - // - // = DESCRIPTION - // Implementation to be provided by <IMPLEMENTATION>. public: // = Traits. typedef IMPLEMENTATION implementation; + /// Constructor. ACE_Map_Impl_Iterator_Adapter (const IMPLEMENTATION &impl); - // Constructor. + /// Destructor. virtual ~ACE_Map_Impl_Iterator_Adapter (void); - // Destructor. + /// Clone. virtual ACE_Iterator_Impl<T> *clone (void) const; - // Clone. + /// Comparison. virtual int compare (const ACE_Iterator_Impl<T> &rhs) const; - // Comparison. + /// Dereference. virtual T dereference (void) const; - // Dereference. + /// Advance. virtual void plus_plus (void); - // Advance. + /// Reverse. virtual void minus_minus (void); - // Reverse. + /// Accessor to implementation object. IMPLEMENTATION &impl (void); - // Accessor to implementation object. protected: + /// All implementation details are forwarded to this class. IMPLEMENTATION implementation_; - // All implementation details are forwarded to this class. }; +/** + * @class ACE_Map_Impl_Reverse_Iterator_Adapter + * + * @brief Defines a reverse iterator implementation for the Map_Impl class. + * + * Implementation to be provided by IMPLEMENTATION. + */ template <class T, class IMPLEMENTATION, class ENTRY> class ACE_Map_Impl_Reverse_Iterator_Adapter : public ACE_Reverse_Iterator_Impl<T> { - // = TITLE - // Defines a reverse iterator implementation for the Map_Impl class. - // - // = DESCRIPTION - // Implementation to be provided by IMPLEMENTATION. public: // = Traits. typedef IMPLEMENTATION implementation; + /// Constructor. ACE_Map_Impl_Reverse_Iterator_Adapter (const IMPLEMENTATION &impl); - // Constructor. + /// Destructor. virtual ~ACE_Map_Impl_Reverse_Iterator_Adapter (void); - // Destructor. + /// Clone. virtual ACE_Reverse_Iterator_Impl<T> *clone (void) const; - // Clone. + /// Comparison. virtual int compare (const ACE_Reverse_Iterator_Impl<T> &rhs) const; - // Comparison. + /// Dereference. virtual T dereference (void) const; - // Dereference. + /// Advance. virtual void plus_plus (void); - // Advance. + /// Reverse. virtual void minus_minus (void); - // Reverse. + /// Accessor to implementation object. IMPLEMENTATION &impl (void); - // Accessor to implementation object. protected: + /// All implementation details are forwarded to this class. IMPLEMENTATION implementation_; - // All implementation details are forwarded to this class. }; +/** + * @class ACE_Map_Impl + * + * @brief Defines a map implementation. + * + * Implementation to be provided by <IMPLEMENTATION>. + */ template <class KEY, class VALUE, class IMPLEMENTATION, class ITERATOR, class REVERSE_ITERATOR, class ENTRY> class ACE_Map_Impl : public ACE_Map<KEY, VALUE> { - // = TITLE - // Defines a map implementation. - // - // = DESCRIPTION - // Implementation to be provided by <IMPLEMENTATION>. public: // = Traits. @@ -510,139 +542,155 @@ public: implementation; // = Initialization and termination methods. + /// Initialize with the <ACE_DEFAULT_MAP_SIZE>. ACE_Map_Impl (ACE_Allocator *alloc = 0); - // Initialize with the <ACE_DEFAULT_MAP_SIZE>. + /// Initialize with <size> entries. The <size> parameter is ignore + /// by maps for which an initialize size does not make sense. ACE_Map_Impl (size_t size, ACE_Allocator *alloc = 0); - // Initialize with <size> entries. The <size> parameter is ignore - // by maps for which an initialize size does not make sense. + /// Close down and release dynamically allocated resources. virtual ~ACE_Map_Impl (void); - // Close down and release dynamically allocated resources. + /// Initialize a <Map> with size <length>. virtual int open (size_t length = ACE_DEFAULT_MAP_SIZE, ACE_Allocator *alloc = 0); - // Initialize a <Map> with size <length>. + /// Close down a <Map> and release dynamically allocated resources. virtual int close (void); - // Close down a <Map> and release dynamically allocated resources. + /** + * Add <key>/<value> pair to the map. If <key> is already in the + * map then no changes are made and 1 is returned. Returns 0 on a + * successful addition. This function fails for maps that do not + * allow user specified keys. <key> is an "in" parameter. + */ virtual int bind (const KEY &key, const VALUE &value); - // Add <key>/<value> pair to the map. If <key> is already in the - // map then no changes are made and 1 is returned. Returns 0 on a - // successful addition. This function fails for maps that do not - // allow user specified keys. <key> is an "in" parameter. + /** + * Add <key>/<value> pair to the map. <key> is an "inout" parameter + * and maybe modified/extended by the map to add additional + * information. To recover original key, call the <recover_key> + * method. + */ virtual int bind_modify_key (const VALUE &value, KEY &key); - // Add <key>/<value> pair to the map. <key> is an "inout" parameter - // and maybe modified/extended by the map to add additional - // information. To recover original key, call the <recover_key> - // method. + /** + * Add <value> to the map, and the corresponding key produced by the + * Map is returned through <key> which is an "out" parameter. For + * maps that do not naturally produce keys, the map adapters will + * use the <KEY_GENERATOR> class to produce a key. However, the + * users are responsible for not jeopardizing this key production + * scheme by using user specified keys with keys produced by the key + * generator. + */ virtual int bind_create_key (const VALUE &value, KEY &key); - // Add <value> to the map, and the corresponding key produced by the - // Map is returned through <key> which is an "out" parameter. For - // maps that do not naturally produce keys, the map adapters will - // use the <KEY_GENERATOR> class to produce a key. However, the - // users are responsible for not jeopardizing this key production - // scheme by using user specified keys with keys produced by the key - // generator. + /** + * Add <value> to the map. The user does not care about the + * corresponding key produced by the Map. For maps that do not + * naturally produce keys, the map adapters will use the + * <KEY_GENERATOR> class to produce a key. However, the users are + * responsible for not jeopardizing this key production scheme by + * using user specified keys with keys produced by the key + * generator. + */ virtual int bind_create_key (const VALUE &value); - // Add <value> to the map. The user does not care about the - // corresponding key produced by the Map. For maps that do not - // naturally produce keys, the map adapters will use the - // <KEY_GENERATOR> class to produce a key. However, the users are - // responsible for not jeopardizing this key production scheme by - // using user specified keys with keys produced by the key - // generator. + /// Recovers the original key potentially modified by the map during + /// <bind_modify_key>. virtual int recover_key (const KEY &modified_key, KEY &original_key); - // Recovers the original key potentially modified by the map during - // <bind_modify_key>. + /** + * Reassociate <key> with <value>. The function fails if <key> is + * not in the map for maps that do not allow user specified keys. + * However, for maps that allow user specified keys, if the key is + * not in the map, a new <key>/<value> association is created. + */ virtual int rebind (const KEY &key, const VALUE &value); - // Reassociate <key> with <value>. The function fails if <key> is - // not in the map for maps that do not allow user specified keys. - // However, for maps that allow user specified keys, if the key is - // not in the map, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old value into the + * "out" parameter <old_value>. The function fails if <key> is not + * in the map for maps that do not allow user specified keys. + * However, for maps that allow user specified keys, if the key is + * not in the map, a new <key>/<value> association is created. + */ virtual int rebind (const KEY &key, const VALUE &value, VALUE &old_value); - // Reassociate <key> with <value>, storing the old value into the - // "out" parameter <old_value>. The function fails if <key> is not - // in the map for maps that do not allow user specified keys. - // However, for maps that allow user specified keys, if the key is - // not in the map, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old key and value + * into the "out" parameters <old_key> and <old_value>. The + * function fails if <key> is not in the map for maps that do not + * allow user specified keys. However, for maps that allow user + * specified keys, if the key is not in the map, a new <key>/<value> + * association is created. + */ virtual int rebind (const KEY &key, const VALUE &value, KEY &old_key, VALUE &old_value); - // Reassociate <key> with <value>, storing the old key and value - // into the "out" parameters <old_key> and <old_value>. The - // function fails if <key> is not in the map for maps that do not - // allow user specified keys. However, for maps that allow user - // specified keys, if the key is not in the map, a new <key>/<value> - // association is created. + /** + * Associate <key> with <value> if and only if <key> is not in the + * map. If <key> is already in the map, then the <value> parameter + * is overwritten with the existing value in the map. Returns 0 if a + * new <key>/<value> association is created. Returns 1 if an + * attempt is made to bind an existing entry. This function fails + * for maps that do not allow user specified keys. + */ virtual int trybind (const KEY &key, VALUE &value); - // Associate <key> with <value> if and only if <key> is not in the - // map. If <key> is already in the map, then the <value> parameter - // is overwritten with the existing value in the map. Returns 0 if a - // new <key>/<value> association is created. Returns 1 if an - // attempt is made to bind an existing entry. This function fails - // for maps that do not allow user specified keys. + /// Locate <value> associated with <key>. virtual int find (const KEY &key, VALUE &value); - // Locate <value> associated with <key>. + /// Is <key> in the map? virtual int find (const KEY &key); - // Is <key> in the map? + /// Remove <key> from the map. virtual int unbind (const KEY &key); - // Remove <key> from the map. + /// Remove <key> from the map, and return the <value> associated with + /// <key>. virtual int unbind (const KEY &key, VALUE &value); - // Remove <key> from the map, and return the <value> associated with - // <key>. + /// Return the current size of the map. virtual size_t current_size (void) const; - // Return the current size of the map. + /// Return the total size of the map. virtual size_t total_size (void) const; - // Return the total size of the map. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Accessor to implementation object. IMPLEMENTATION &impl (void); - // Accessor to implementation object. protected: + /// All implementation details are forwarded to this class. IMPLEMENTATION implementation_; - // All implementation details are forwarded to this class. // = STL styled iterator factory functions. + /// Return forward iterator. virtual ACE_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *begin_impl (void); virtual ACE_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *end_impl (void); - // Return forward iterator. + /// Return reverse iterator. virtual ACE_Reverse_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *rbegin_impl (void); virtual ACE_Reverse_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *rend_impl (void); - // Return reverse iterator. private: @@ -651,102 +699,108 @@ private: ACE_UNIMPLEMENTED_FUNC (ACE_Map_Impl (const ACE_Map_Impl<KEY, VALUE, IMPLEMENTATION, ITERATOR, REVERSE_ITERATOR, ENTRY> &)) }; +/** + * @class ACE_Active_Map_Manager_Iterator_Adapter + * + * @brief Defines a iterator implementation for the Active_Map_Manager_Adapter. + * + * Implementation to be provided by ACE_Active_Map_Manager::iterator. + */ template <class T, class VALUE> class ACE_Active_Map_Manager_Iterator_Adapter : public ACE_Iterator_Impl<T> { - // = TITLE - // Defines a iterator implementation for the Active_Map_Manager_Adapter. - // - // = DESCRIPTION - // Implementation to be provided by ACE_Active_Map_Manager::iterator. public: // = Traits. typedef ACE_TYPENAME ACE_Active_Map_Manager<VALUE>::iterator implementation; + /// Constructor. ACE_Active_Map_Manager_Iterator_Adapter (const ACE_Map_Iterator<ACE_Active_Map_Manager_Key, VALUE, ACE_Null_Mutex> &impl); - // Constructor. + /// Destructor. virtual ~ACE_Active_Map_Manager_Iterator_Adapter (void); - // Destructor. + /// Clone. virtual ACE_Iterator_Impl<T> *clone (void) const; - // Clone. + /// Comparison. virtual int compare (const ACE_Iterator_Impl<T> &rhs) const; - // Comparison. + /// Dereference. virtual T dereference (void) const; - // Dereference. + /// Advance. virtual void plus_plus (void); - // Advance. + /// Reverse. virtual void minus_minus (void); - // Reverse. + /// Accessor to implementation object. ACE_Map_Iterator<ACE_Active_Map_Manager_Key, VALUE, ACE_Null_Mutex> &impl (void); - // Accessor to implementation object. protected: + /// All implementation details are forwarded to this class. ACE_Map_Iterator<ACE_Active_Map_Manager_Key, VALUE, ACE_Null_Mutex> implementation_; - // All implementation details are forwarded to this class. }; +/** + * @class ACE_Active_Map_Manager_Reverse_Iterator_Adapter + * + * @brief Defines a reverse iterator implementation for the Active_Map_Manager_Adapter. + * + * Implementation to be provided by ACE_Active_Map_Manager::reverse_iterator. + */ template <class T, class VALUE> class ACE_Active_Map_Manager_Reverse_Iterator_Adapter : public ACE_Reverse_Iterator_Impl<T> { - // = TITLE - // Defines a reverse iterator implementation for the Active_Map_Manager_Adapter. - // - // = DESCRIPTION - // Implementation to be provided by ACE_Active_Map_Manager::reverse_iterator. public: // = Traits. typedef ACE_TYPENAME ACE_Active_Map_Manager<VALUE>::reverse_iterator implementation; + /// Constructor. ACE_Active_Map_Manager_Reverse_Iterator_Adapter (const ACE_Map_Reverse_Iterator<ACE_Active_Map_Manager_Key, VALUE, ACE_Null_Mutex> &impl); - // Constructor. + /// Destructor. virtual ~ACE_Active_Map_Manager_Reverse_Iterator_Adapter (void); - // Destructor. + /// Clone. virtual ACE_Reverse_Iterator_Impl<T> *clone (void) const; - // Clone. + /// Comparison. virtual int compare (const ACE_Reverse_Iterator_Impl<T> &rhs) const; - // Comparison. + /// Dereference. virtual T dereference (void) const; - // Dereference. + /// Advance. virtual void plus_plus (void); - // Advance. + /// Reverse. virtual void minus_minus (void); - // Reverse. + /// Accessor to implementation object. ACE_Map_Reverse_Iterator<ACE_Active_Map_Manager_Key, VALUE, ACE_Null_Mutex> &impl (void); - // Accessor to implementation object. protected: + /// All implementation details are forwarded to this class. ACE_Map_Reverse_Iterator<ACE_Active_Map_Manager_Key, VALUE, ACE_Null_Mutex> implementation_; - // All implementation details are forwarded to this class. }; +/** + * @class ACE_Active_Map_Manager_Adapter + * + * @brief Defines a map implementation. + * + * Implementation to be provided by <ACE_Active_Map_Manager>. + */ template <class KEY, class VALUE, class KEY_ADAPTER> class ACE_Active_Map_Manager_Adapter : public ACE_Map<KEY, VALUE> { - // = TITLE - // Defines a map implementation. - // - // = DESCRIPTION - // Implementation to be provided by <ACE_Active_Map_Manager>. public: // = Traits. @@ -760,153 +814,169 @@ public: implementation; // = Initialization and termination methods. + /// Initialize with the <ACE_DEFAULT_MAP_SIZE>. ACE_Active_Map_Manager_Adapter (ACE_Allocator *alloc = 0); - // Initialize with the <ACE_DEFAULT_MAP_SIZE>. + /// Initialize with <size> entries. The <size> parameter is ignore + /// by maps for which an initialize size does not make sense. ACE_Active_Map_Manager_Adapter (size_t size, ACE_Allocator *alloc = 0); - // Initialize with <size> entries. The <size> parameter is ignore - // by maps for which an initialize size does not make sense. + /// Close down and release dynamically allocated resources. virtual ~ACE_Active_Map_Manager_Adapter (void); - // Close down and release dynamically allocated resources. + /// Initialize a <Map> with size <length>. virtual int open (size_t length = ACE_DEFAULT_MAP_SIZE, ACE_Allocator *alloc = 0); - // Initialize a <Map> with size <length>. + /// Close down a <Map> and release dynamically allocated resources. virtual int close (void); - // Close down a <Map> and release dynamically allocated resources. + /** + * Add <key>/<value> pair to the map. If <key> is already in the + * map then no changes are made and 1 is returned. Returns 0 on a + * successful addition. This function fails for maps that do not + * allow user specified keys. <key> is an "in" parameter. + */ virtual int bind (const KEY &key, const VALUE &value); - // Add <key>/<value> pair to the map. If <key> is already in the - // map then no changes are made and 1 is returned. Returns 0 on a - // successful addition. This function fails for maps that do not - // allow user specified keys. <key> is an "in" parameter. + /** + * Add <key>/<value> pair to the map. <key> is an "inout" parameter + * and maybe modified/extended by the map to add additional + * information. To recover original key, call the <recover_key> + * method. + */ virtual int bind_modify_key (const VALUE &value, KEY &key); - // Add <key>/<value> pair to the map. <key> is an "inout" parameter - // and maybe modified/extended by the map to add additional - // information. To recover original key, call the <recover_key> - // method. + /** + * Add <value> to the map, and the corresponding key produced by the + * Map is returned through <key> which is an "out" parameter. For + * maps that do not naturally produce keys, the map adapters will + * use the <KEY_GENERATOR> class to produce a key. However, the + * users are responsible for not jeopardizing this key production + * scheme by using user specified keys with keys produced by the key + * generator. + */ virtual int bind_create_key (const VALUE &value, KEY &key); - // Add <value> to the map, and the corresponding key produced by the - // Map is returned through <key> which is an "out" parameter. For - // maps that do not naturally produce keys, the map adapters will - // use the <KEY_GENERATOR> class to produce a key. However, the - // users are responsible for not jeopardizing this key production - // scheme by using user specified keys with keys produced by the key - // generator. + /** + * Add <value> to the map. The user does not care about the + * corresponding key produced by the Map. For maps that do not + * naturally produce keys, the map adapters will use the + * <KEY_GENERATOR> class to produce a key. However, the users are + * responsible for not jeopardizing this key production scheme by + * using user specified keys with keys produced by the key + * generator. + */ virtual int bind_create_key (const VALUE &value); - // Add <value> to the map. The user does not care about the - // corresponding key produced by the Map. For maps that do not - // naturally produce keys, the map adapters will use the - // <KEY_GENERATOR> class to produce a key. However, the users are - // responsible for not jeopardizing this key production scheme by - // using user specified keys with keys produced by the key - // generator. + /// Recovers the original key potentially modified by the map during + /// <bind_modify_key>. virtual int recover_key (const KEY &modified_key, KEY &original_key); - // Recovers the original key potentially modified by the map during - // <bind_modify_key>. + /** + * Reassociate <key> with <value>. The function fails if <key> is + * not in the map for maps that do not allow user specified keys. + * However, for maps that allow user specified keys, if the key is + * not in the map, a new <key>/<value> association is created. + */ virtual int rebind (const KEY &key, const VALUE &value); - // Reassociate <key> with <value>. The function fails if <key> is - // not in the map for maps that do not allow user specified keys. - // However, for maps that allow user specified keys, if the key is - // not in the map, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old value into the + * "out" parameter <old_value>. The function fails if <key> is not + * in the map for maps that do not allow user specified keys. + * However, for maps that allow user specified keys, if the key is + * not in the map, a new <key>/<value> association is created. + */ virtual int rebind (const KEY &key, const VALUE &value, VALUE &old_value); - // Reassociate <key> with <value>, storing the old value into the - // "out" parameter <old_value>. The function fails if <key> is not - // in the map for maps that do not allow user specified keys. - // However, for maps that allow user specified keys, if the key is - // not in the map, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old key and value + * into the "out" parameters <old_key> and <old_value>. The + * function fails if <key> is not in the map for maps that do not + * allow user specified keys. However, for maps that allow user + * specified keys, if the key is not in the map, a new <key>/<value> + * association is created. + */ virtual int rebind (const KEY &key, const VALUE &value, KEY &old_key, VALUE &old_value); - // Reassociate <key> with <value>, storing the old key and value - // into the "out" parameters <old_key> and <old_value>. The - // function fails if <key> is not in the map for maps that do not - // allow user specified keys. However, for maps that allow user - // specified keys, if the key is not in the map, a new <key>/<value> - // association is created. + /** + * Associate <key> with <value> if and only if <key> is not in the + * map. If <key> is already in the map, then the <value> parameter + * is overwritten with the existing value in the map. Returns 0 if a + * new <key>/<value> association is created. Returns 1 if an + * attempt is made to bind an existing entry. This function fails + * for maps that do not allow user specified keys. + */ virtual int trybind (const KEY &key, VALUE &value); - // Associate <key> with <value> if and only if <key> is not in the - // map. If <key> is already in the map, then the <value> parameter - // is overwritten with the existing value in the map. Returns 0 if a - // new <key>/<value> association is created. Returns 1 if an - // attempt is made to bind an existing entry. This function fails - // for maps that do not allow user specified keys. + /// Locate <value> associated with <key>. virtual int find (const KEY &key, VALUE &value); - // Locate <value> associated with <key>. + /// Is <key> in the map? virtual int find (const KEY &key); - // Is <key> in the map? + /// Remove <key> from the map. virtual int unbind (const KEY &key); - // Remove <key> from the map. + /// Remove <key> from the map, and return the <value> associated with + /// <key>. virtual int unbind (const KEY &key, VALUE &value); - // Remove <key> from the map, and return the <value> associated with - // <key>. + /// Return the current size of the map. virtual size_t current_size (void) const; - // Return the current size of the map. + /// Return the total size of the map. virtual size_t total_size (void) const; - // Return the total size of the map. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Accessor to implementation object. ACE_Active_Map_Manager<ACE_Pair<KEY, VALUE> > &impl (void); - // Accessor to implementation object. + /// Accessor to key adapter. KEY_ADAPTER &key_adapter (void); - // Accessor to key adapter. protected: + /// Find helper. virtual int find (const KEY &key, expanded_value *&internal_value); - // Find helper. + /// Unbind helper. virtual int unbind (const KEY &key, expanded_value *&internal_value); - // Unbind helper. + /// All implementation details are forwarded to this class. ACE_Active_Map_Manager<ACE_Pair<KEY, VALUE> > implementation_; - // All implementation details are forwarded to this class. + /// Adapts between the user key and the Active_Map_Manager_Key. KEY_ADAPTER key_adapter_; - // Adapts between the user key and the Active_Map_Manager_Key. // = STL styled iterator factory functions. + /// Return forward iterator. virtual ACE_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *begin_impl (void); virtual ACE_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *end_impl (void); - // Return forward iterator. + /// Return reverse iterator. virtual ACE_Reverse_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *rbegin_impl (void); virtual ACE_Reverse_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *rend_impl (void); - // Return reverse iterator. private: @@ -915,102 +985,108 @@ private: ACE_UNIMPLEMENTED_FUNC (ACE_Active_Map_Manager_Adapter (const ACE_Active_Map_Manager_Adapter<KEY, VALUE, KEY_ADAPTER> &)) }; +/** + * @class ACE_Hash_Map_Manager_Ex_Iterator_Adapter + * + * @brief Defines a iterator implementation for the Hash_Map_Manager_Adapter. + * + * Implementation to be provided by ACE_Hash_Map_Manager_Ex::iterator. + */ template <class T, class KEY, class VALUE, class HASH_KEY, class COMPARE_KEYS> class ACE_Hash_Map_Manager_Ex_Iterator_Adapter : public ACE_Iterator_Impl<T> { - // = TITLE - // Defines a iterator implementation for the Hash_Map_Manager_Adapter. - // - // = DESCRIPTION - // Implementation to be provided by ACE_Hash_Map_Manager_Ex::iterator. public: // = Traits. typedef ACE_TYPENAME ACE_Hash_Map_Manager_Ex<KEY, VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex>::iterator implementation; + /// Constructor. ACE_Hash_Map_Manager_Ex_Iterator_Adapter (const ACE_Hash_Map_Iterator_Ex<KEY, VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> &impl); - // Constructor. + /// Destructor. virtual ~ACE_Hash_Map_Manager_Ex_Iterator_Adapter (void); - // Destructor. + /// Clone. virtual ACE_Iterator_Impl<T> *clone (void) const; - // Clone. + /// Comparison. virtual int compare (const ACE_Iterator_Impl<T> &rhs) const; - // Comparison. + /// Dereference. virtual T dereference (void) const; - // Dereference. + /// Advance. virtual void plus_plus (void); - // Advance. + /// Reverse. virtual void minus_minus (void); - // Reverse. + /// Accessor to implementation object. ACE_Hash_Map_Iterator_Ex<KEY, VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> &impl (void); - // Accessor to implementation object. protected: + /// All implementation details are forwarded to this class. ACE_Hash_Map_Iterator_Ex<KEY, VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> implementation_; - // All implementation details are forwarded to this class. }; +/** + * @class ACE_Hash_Map_Manager_Ex_Reverse_Iterator_Adapter + * + * @brief Defines a reverse iterator implementation for the Hash_Map_Manager_Adapter. + * + * Implementation to be provided by ACE_Hash_Map_Manager_Ex::reverse_iterator. + */ template <class T, class KEY, class VALUE, class HASH_KEY, class COMPARE_KEYS> class ACE_Hash_Map_Manager_Ex_Reverse_Iterator_Adapter : public ACE_Reverse_Iterator_Impl<T> { - // = TITLE - // Defines a reverse iterator implementation for the Hash_Map_Manager_Adapter. - // - // = DESCRIPTION - // Implementation to be provided by ACE_Hash_Map_Manager_Ex::reverse_iterator. public: // = Traits. typedef ACE_TYPENAME ACE_Hash_Map_Manager_Ex<KEY, VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex>::reverse_iterator implementation; + /// Constructor. ACE_Hash_Map_Manager_Ex_Reverse_Iterator_Adapter (const ACE_Hash_Map_Reverse_Iterator_Ex<KEY, VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> &impl); - // Constructor. + /// Destructor. virtual ~ACE_Hash_Map_Manager_Ex_Reverse_Iterator_Adapter (void); - // Destructor. + /// Clone. virtual ACE_Reverse_Iterator_Impl<T> *clone (void) const; - // Clone. + /// Comparison. virtual int compare (const ACE_Reverse_Iterator_Impl<T> &rhs) const; - // Comparison. + /// Dereference. virtual T dereference (void) const; - // Dereference. + /// Advance. virtual void plus_plus (void); - // Advance. + /// Reverse. virtual void minus_minus (void); - // Reverse. + /// Accessor to implementation object. ACE_Hash_Map_Reverse_Iterator_Ex<KEY, VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> &impl (void); - // Accessor to implementation object. protected: + /// All implementation details are forwarded to this class. ACE_Hash_Map_Reverse_Iterator_Ex<KEY, VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> implementation_; - // All implementation details are forwarded to this class. }; +/** + * @class ACE_Hash_Map_Manager_Ex_Adapter + * + * @brief Defines a map implementation. + * + * Implementation to be provided by <ACE_Hash_Map_Manager_Ex>. + */ template <class KEY, class VALUE, class HASH_KEY, class COMPARE_KEYS, class KEY_GENERATOR> class ACE_Hash_Map_Manager_Ex_Adapter : public ACE_Map<KEY, VALUE> { - // = TITLE - // Defines a map implementation. - // - // = DESCRIPTION - // Implementation to be provided by <ACE_Hash_Map_Manager_Ex>. public: // = Traits. @@ -1022,145 +1098,161 @@ public: implementation; // = Initialization and termination methods. + /// Initialize with the <ACE_DEFAULT_MAP_SIZE>. ACE_Hash_Map_Manager_Ex_Adapter (ACE_Allocator *alloc = 0); - // Initialize with the <ACE_DEFAULT_MAP_SIZE>. + /// Initialize with <size> entries. The <size> parameter is ignore + /// by maps for which an initialize size does not make sense. ACE_Hash_Map_Manager_Ex_Adapter (size_t size, ACE_Allocator *alloc = 0); - // Initialize with <size> entries. The <size> parameter is ignore - // by maps for which an initialize size does not make sense. + /// Close down and release dynamically allocated resources. virtual ~ACE_Hash_Map_Manager_Ex_Adapter (void); - // Close down and release dynamically allocated resources. + /// Initialize a <Map> with size <length>. virtual int open (size_t length = ACE_DEFAULT_MAP_SIZE, ACE_Allocator *alloc = 0); - // Initialize a <Map> with size <length>. + /// Close down a <Map> and release dynamically allocated resources. virtual int close (void); - // Close down a <Map> and release dynamically allocated resources. + /** + * Add <key>/<value> pair to the map. If <key> is already in the + * map then no changes are made and 1 is returned. Returns 0 on a + * successful addition. This function fails for maps that do not + * allow user specified keys. <key> is an "in" parameter. + */ virtual int bind (const KEY &key, const VALUE &value); - // Add <key>/<value> pair to the map. If <key> is already in the - // map then no changes are made and 1 is returned. Returns 0 on a - // successful addition. This function fails for maps that do not - // allow user specified keys. <key> is an "in" parameter. + /** + * Add <key>/<value> pair to the map. <key> is an "inout" parameter + * and maybe modified/extended by the map to add additional + * information. To recover original key, call the <recover_key> + * method. + */ virtual int bind_modify_key (const VALUE &value, KEY &key); - // Add <key>/<value> pair to the map. <key> is an "inout" parameter - // and maybe modified/extended by the map to add additional - // information. To recover original key, call the <recover_key> - // method. + /** + * Add <value> to the map, and the corresponding key produced by the + * Map is returned through <key> which is an "out" parameter. For + * maps that do not naturally produce keys, the map adapters will + * use the <KEY_GENERATOR> class to produce a key. However, the + * users are responsible for not jeopardizing this key production + * scheme by using user specified keys with keys produced by the key + * generator. + */ virtual int bind_create_key (const VALUE &value, KEY &key); - // Add <value> to the map, and the corresponding key produced by the - // Map is returned through <key> which is an "out" parameter. For - // maps that do not naturally produce keys, the map adapters will - // use the <KEY_GENERATOR> class to produce a key. However, the - // users are responsible for not jeopardizing this key production - // scheme by using user specified keys with keys produced by the key - // generator. + /** + * Add <value> to the map. The user does not care about the + * corresponding key produced by the Map. For maps that do not + * naturally produce keys, the map adapters will use the + * <KEY_GENERATOR> class to produce a key. However, the users are + * responsible for not jeopardizing this key production scheme by + * using user specified keys with keys produced by the key + * generator. + */ virtual int bind_create_key (const VALUE &value); - // Add <value> to the map. The user does not care about the - // corresponding key produced by the Map. For maps that do not - // naturally produce keys, the map adapters will use the - // <KEY_GENERATOR> class to produce a key. However, the users are - // responsible for not jeopardizing this key production scheme by - // using user specified keys with keys produced by the key - // generator. + /// Recovers the original key potentially modified by the map during + /// <bind_modify_key>. virtual int recover_key (const KEY &modified_key, KEY &original_key); - // Recovers the original key potentially modified by the map during - // <bind_modify_key>. + /** + * Reassociate <key> with <value>. The function fails if <key> is + * not in the map for maps that do not allow user specified keys. + * However, for maps that allow user specified keys, if the key is + * not in the map, a new <key>/<value> association is created. + */ virtual int rebind (const KEY &key, const VALUE &value); - // Reassociate <key> with <value>. The function fails if <key> is - // not in the map for maps that do not allow user specified keys. - // However, for maps that allow user specified keys, if the key is - // not in the map, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old value into the + * "out" parameter <old_value>. The function fails if <key> is not + * in the map for maps that do not allow user specified keys. + * However, for maps that allow user specified keys, if the key is + * not in the map, a new <key>/<value> association is created. + */ virtual int rebind (const KEY &key, const VALUE &value, VALUE &old_value); - // Reassociate <key> with <value>, storing the old value into the - // "out" parameter <old_value>. The function fails if <key> is not - // in the map for maps that do not allow user specified keys. - // However, for maps that allow user specified keys, if the key is - // not in the map, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old key and value + * into the "out" parameters <old_key> and <old_value>. The + * function fails if <key> is not in the map for maps that do not + * allow user specified keys. However, for maps that allow user + * specified keys, if the key is not in the map, a new <key>/<value> + * association is created. + */ virtual int rebind (const KEY &key, const VALUE &value, KEY &old_key, VALUE &old_value); - // Reassociate <key> with <value>, storing the old key and value - // into the "out" parameters <old_key> and <old_value>. The - // function fails if <key> is not in the map for maps that do not - // allow user specified keys. However, for maps that allow user - // specified keys, if the key is not in the map, a new <key>/<value> - // association is created. + /** + * Associate <key> with <value> if and only if <key> is not in the + * map. If <key> is already in the map, then the <value> parameter + * is overwritten with the existing value in the map. Returns 0 if a + * new <key>/<value> association is created. Returns 1 if an + * attempt is made to bind an existing entry. This function fails + * for maps that do not allow user specified keys. + */ virtual int trybind (const KEY &key, VALUE &value); - // Associate <key> with <value> if and only if <key> is not in the - // map. If <key> is already in the map, then the <value> parameter - // is overwritten with the existing value in the map. Returns 0 if a - // new <key>/<value> association is created. Returns 1 if an - // attempt is made to bind an existing entry. This function fails - // for maps that do not allow user specified keys. + /// Locate <value> associated with <key>. virtual int find (const KEY &key, VALUE &value); - // Locate <value> associated with <key>. + /// Is <key> in the map? virtual int find (const KEY &key); - // Is <key> in the map? + /// Remove <key> from the map. virtual int unbind (const KEY &key); - // Remove <key> from the map. + /// Remove <key> from the map, and return the <value> associated with + /// <key>. virtual int unbind (const KEY &key, VALUE &value); - // Remove <key> from the map, and return the <value> associated with - // <key>. + /// Return the current size of the map. virtual size_t current_size (void) const; - // Return the current size of the map. + /// Return the total size of the map. virtual size_t total_size (void) const; - // Return the total size of the map. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Accessor to implementation object. ACE_Hash_Map_Manager_Ex<KEY, VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> &impl (void); - // Accessor to implementation object. + /// Accessor to key generator. KEY_GENERATOR &key_generator (void); - // Accessor to key generator. protected: + /// All implementation details are forwarded to this class. ACE_Hash_Map_Manager_Ex<KEY, VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> implementation_; - // All implementation details are forwarded to this class. + /// Functor class used for generating key. KEY_GENERATOR key_generator_; - // Functor class used for generating key. // = STL styled iterator factory functions. + /// Return forward iterator. virtual ACE_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *begin_impl (void); virtual ACE_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *end_impl (void); - // Return forward iterator. + /// Return reverse iterator. virtual ACE_Reverse_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *rbegin_impl (void); virtual ACE_Reverse_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *rend_impl (void); - // Return reverse iterator. private: @@ -1169,102 +1261,108 @@ private: ACE_UNIMPLEMENTED_FUNC (ACE_Hash_Map_Manager_Ex_Adapter (const ACE_Hash_Map_Manager_Ex_Adapter<KEY, VALUE, HASH_KEY, COMPARE_KEYS, KEY_GENERATOR> &)) }; +/** + * @class ACE_Map_Manager_Iterator_Adapter + * + * @brief Defines a iterator implementation for the Map_Manager_Adapter. + * + * Implementation to be provided by ACE_Map_Manager::iterator. + */ template <class T, class KEY, class VALUE> class ACE_Map_Manager_Iterator_Adapter : public ACE_Iterator_Impl<T> { - // = TITLE - // Defines a iterator implementation for the Map_Manager_Adapter. - // - // = DESCRIPTION - // Implementation to be provided by ACE_Map_Manager::iterator. public: // = Traits. typedef ACE_TYPENAME ACE_Map_Manager<KEY, VALUE, ACE_Null_Mutex>::iterator implementation; + /// Constructor. ACE_Map_Manager_Iterator_Adapter (const ACE_Map_Iterator<KEY, VALUE, ACE_Null_Mutex> &impl); - // Constructor. + /// Destructor. virtual ~ACE_Map_Manager_Iterator_Adapter (void); - // Destructor. + /// Clone. virtual ACE_Iterator_Impl<T> *clone (void) const; - // Clone. + /// Comparison. virtual int compare (const ACE_Iterator_Impl<T> &rhs) const; - // Comparison. + /// Dereference. virtual T dereference (void) const; - // Dereference. + /// Advance. virtual void plus_plus (void); - // Advance. + /// Reverse. virtual void minus_minus (void); - // Reverse. + /// Accessor to implementation object. ACE_Map_Iterator<KEY, VALUE, ACE_Null_Mutex> &impl (void); - // Accessor to implementation object. protected: + /// All implementation details are forwarded to this class. ACE_Map_Iterator<KEY, VALUE, ACE_Null_Mutex> implementation_; - // All implementation details are forwarded to this class. }; +/** + * @class ACE_Map_Manager_Reverse_Iterator_Adapter + * + * @brief Defines a reverse iterator implementation for the Map Manager. + * + * Implementation to be provided by ACE_Map_Manager::reverse_iterator. + */ template <class T, class KEY, class VALUE> class ACE_Map_Manager_Reverse_Iterator_Adapter : public ACE_Reverse_Iterator_Impl<T> { - // = TITLE - // Defines a reverse iterator implementation for the Map Manager. - // - // = DESCRIPTION - // Implementation to be provided by ACE_Map_Manager::reverse_iterator. public: // = Traits. typedef ACE_TYPENAME ACE_Map_Manager<KEY, VALUE, ACE_Null_Mutex>::reverse_iterator implementation; + /// Constructor. ACE_Map_Manager_Reverse_Iterator_Adapter (const ACE_Map_Reverse_Iterator<KEY, VALUE, ACE_Null_Mutex> &impl); - // Constructor. + /// Destructor. virtual ~ACE_Map_Manager_Reverse_Iterator_Adapter (void); - // Destructor. + /// Clone. virtual ACE_Reverse_Iterator_Impl<T> *clone (void) const; - // Clone. + /// Comparison. virtual int compare (const ACE_Reverse_Iterator_Impl<T> &rhs) const; - // Comparison. + /// Dereference. virtual T dereference (void) const; - // Dereference. + /// Advance. virtual void plus_plus (void); - // Advance. + /// Reverse. virtual void minus_minus (void); - // Reverse. + /// Accessor to implementation object. ACE_Map_Reverse_Iterator<KEY, VALUE, ACE_Null_Mutex> &impl (void); - // Accessor to implementation object. protected: + /// All implementation details are forwarded to this class. ACE_Map_Reverse_Iterator<KEY, VALUE, ACE_Null_Mutex> implementation_; - // All implementation details are forwarded to this class. }; +/** + * @class ACE_Map_Manager_Adapter + * + * @brief Defines a map implementation. + * + * Implementation to be provided by <ACE_Map_Manager>. + */ template <class KEY, class VALUE, class KEY_GENERATOR> class ACE_Map_Manager_Adapter : public ACE_Map<KEY, VALUE> { - // = TITLE - // Defines a map implementation. - // - // = DESCRIPTION - // Implementation to be provided by <ACE_Map_Manager>. public: // = Traits. @@ -1276,145 +1374,161 @@ public: implementation; // = Initialization and termination methods. + /// Initialize with the <ACE_DEFAULT_MAP_SIZE>. ACE_Map_Manager_Adapter (ACE_Allocator *alloc = 0); - // Initialize with the <ACE_DEFAULT_MAP_SIZE>. + /// Initialize with <size> entries. The <size> parameter is ignore + /// by maps for which an initialize size does not make sense. ACE_Map_Manager_Adapter (size_t size, ACE_Allocator *alloc = 0); - // Initialize with <size> entries. The <size> parameter is ignore - // by maps for which an initialize size does not make sense. + /// Close down and release dynamically allocated resources. virtual ~ACE_Map_Manager_Adapter (void); - // Close down and release dynamically allocated resources. + /// Initialize a <Map> with size <length>. virtual int open (size_t length = ACE_DEFAULT_MAP_SIZE, ACE_Allocator *alloc = 0); - // Initialize a <Map> with size <length>. + /// Close down a <Map> and release dynamically allocated resources. virtual int close (void); - // Close down a <Map> and release dynamically allocated resources. + /** + * Add <key>/<value> pair to the map. If <key> is already in the + * map then no changes are made and 1 is returned. Returns 0 on a + * successful addition. This function fails for maps that do not + * allow user specified keys. <key> is an "in" parameter. + */ virtual int bind (const KEY &key, const VALUE &value); - // Add <key>/<value> pair to the map. If <key> is already in the - // map then no changes are made and 1 is returned. Returns 0 on a - // successful addition. This function fails for maps that do not - // allow user specified keys. <key> is an "in" parameter. + /** + * Add <key>/<value> pair to the map. <key> is an "inout" parameter + * and maybe modified/extended by the map to add additional + * information. To recover original key, call the <recover_key> + * method. + */ virtual int bind_modify_key (const VALUE &value, KEY &key); - // Add <key>/<value> pair to the map. <key> is an "inout" parameter - // and maybe modified/extended by the map to add additional - // information. To recover original key, call the <recover_key> - // method. + /** + * Add <value> to the map, and the corresponding key produced by the + * Map is returned through <key> which is an "out" parameter. For + * maps that do not naturally produce keys, the map adapters will + * use the <KEY_GENERATOR> class to produce a key. However, the + * users are responsible for not jeopardizing this key production + * scheme by using user specified keys with keys produced by the key + * generator. + */ virtual int bind_create_key (const VALUE &value, KEY &key); - // Add <value> to the map, and the corresponding key produced by the - // Map is returned through <key> which is an "out" parameter. For - // maps that do not naturally produce keys, the map adapters will - // use the <KEY_GENERATOR> class to produce a key. However, the - // users are responsible for not jeopardizing this key production - // scheme by using user specified keys with keys produced by the key - // generator. + /** + * Add <value> to the map. The user does not care about the + * corresponding key produced by the Map. For maps that do not + * naturally produce keys, the map adapters will use the + * <KEY_GENERATOR> class to produce a key. However, the users are + * responsible for not jeopardizing this key production scheme by + * using user specified keys with keys produced by the key + * generator. + */ virtual int bind_create_key (const VALUE &value); - // Add <value> to the map. The user does not care about the - // corresponding key produced by the Map. For maps that do not - // naturally produce keys, the map adapters will use the - // <KEY_GENERATOR> class to produce a key. However, the users are - // responsible for not jeopardizing this key production scheme by - // using user specified keys with keys produced by the key - // generator. + /// Recovers the original key potentially modified by the map during + /// <bind_modify_key>. virtual int recover_key (const KEY &modified_key, KEY &original_key); - // Recovers the original key potentially modified by the map during - // <bind_modify_key>. + /** + * Reassociate <key> with <value>. The function fails if <key> is + * not in the map for maps that do not allow user specified keys. + * However, for maps that allow user specified keys, if the key is + * not in the map, a new <key>/<value> association is created. + */ virtual int rebind (const KEY &key, const VALUE &value); - // Reassociate <key> with <value>. The function fails if <key> is - // not in the map for maps that do not allow user specified keys. - // However, for maps that allow user specified keys, if the key is - // not in the map, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old value into the + * "out" parameter <old_value>. The function fails if <key> is not + * in the map for maps that do not allow user specified keys. + * However, for maps that allow user specified keys, if the key is + * not in the map, a new <key>/<value> association is created. + */ virtual int rebind (const KEY &key, const VALUE &value, VALUE &old_value); - // Reassociate <key> with <value>, storing the old value into the - // "out" parameter <old_value>. The function fails if <key> is not - // in the map for maps that do not allow user specified keys. - // However, for maps that allow user specified keys, if the key is - // not in the map, a new <key>/<value> association is created. + /** + * Reassociate <key> with <value>, storing the old key and value + * into the "out" parameters <old_key> and <old_value>. The + * function fails if <key> is not in the map for maps that do not + * allow user specified keys. However, for maps that allow user + * specified keys, if the key is not in the map, a new <key>/<value> + * association is created. + */ virtual int rebind (const KEY &key, const VALUE &value, KEY &old_key, VALUE &old_value); - // Reassociate <key> with <value>, storing the old key and value - // into the "out" parameters <old_key> and <old_value>. The - // function fails if <key> is not in the map for maps that do not - // allow user specified keys. However, for maps that allow user - // specified keys, if the key is not in the map, a new <key>/<value> - // association is created. + /** + * Associate <key> with <value> if and only if <key> is not in the + * map. If <key> is already in the map, then the <value> parameter + * is overwritten with the existing value in the map. Returns 0 if a + * new <key>/<value> association is created. Returns 1 if an + * attempt is made to bind an existing entry. This function fails + * for maps that do not allow user specified keys. + */ virtual int trybind (const KEY &key, VALUE &value); - // Associate <key> with <value> if and only if <key> is not in the - // map. If <key> is already in the map, then the <value> parameter - // is overwritten with the existing value in the map. Returns 0 if a - // new <key>/<value> association is created. Returns 1 if an - // attempt is made to bind an existing entry. This function fails - // for maps that do not allow user specified keys. + /// Locate <value> associated with <key>. virtual int find (const KEY &key, VALUE &value); - // Locate <value> associated with <key>. + /// Is <key> in the map? virtual int find (const KEY &key); - // Is <key> in the map? + /// Remove <key> from the map. virtual int unbind (const KEY &key); - // Remove <key> from the map. + /// Remove <key> from the map, and return the <value> associated with + /// <key>. virtual int unbind (const KEY &key, VALUE &value); - // Remove <key> from the map, and return the <value> associated with - // <key>. + /// Return the current size of the map. virtual size_t current_size (void) const; - // Return the current size of the map. + /// Return the total size of the map. virtual size_t total_size (void) const; - // Return the total size of the map. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Accessor to implementation object. ACE_Map_Manager<KEY, VALUE, ACE_Null_Mutex> &impl (void); - // Accessor to implementation object. + /// Accessor to key generator. KEY_GENERATOR &key_generator (void); - // Accessor to key generator. protected: + /// All implementation details are forwarded to this class. ACE_Map_Manager<KEY, VALUE, ACE_Null_Mutex> implementation_; - // All implementation details are forwarded to this class. + /// Functor class used for generating key. KEY_GENERATOR key_generator_; - // Functor class used for generating key. // = STL styled iterator factory functions. + /// Return forward iterator. virtual ACE_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *begin_impl (void); virtual ACE_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *end_impl (void); - // Return forward iterator. + /// Return reverse iterator. virtual ACE_Reverse_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *rbegin_impl (void); virtual ACE_Reverse_Iterator_Impl<ACE_Reference_Pair<const KEY, VALUE> > *rend_impl (void); - // Return reverse iterator. private: diff --git a/ace/Mem_Map.h b/ace/Mem_Map.h index 7c6781c8ba6..8a0927fc418 100644 --- a/ace/Mem_Map.h +++ b/ace/Mem_Map.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Mem_Map.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Mem_Map.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_MEM_MAP_H #define ACE_MEM_MAP_H @@ -24,20 +21,24 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Mem_Map + * + * @brief C++ interface OS memory mapping system call. + * + * This class works with both the mmap(2) UNIX system and the + * Win32 family of memory mapping system calls. + */ class ACE_Export ACE_Mem_Map { - // = TITLE - // C++ interface OS memory mapping system call. - // - // = DESCRIPTION - // This class works with both the mmap(2) UNIX system and the - // Win32 family of memory mapping system calls. public: // = Initialization and termination methods. + /// Default constructor. ACE_Mem_Map (void); - // Default constructor. + /// Map a file from an open file descriptor <handle>. This function + /// will lookup the length of the file if it is not given. ACE_Mem_Map (ACE_HANDLE handle, int length = -1, int prot = PROT_RDWR, @@ -45,9 +46,8 @@ public: void *addr = 0, off_t offset = 0, LPSECURITY_ATTRIBUTES sa = 0); - // Map a file from an open file descriptor <handle>. This function - // will lookup the length of the file if it is not given. + /// Map a file specified by <file_name>. ACE_Mem_Map (const ACE_TCHAR *filename, int len = -1, int flags = O_RDWR | O_CREAT, @@ -57,8 +57,9 @@ public: void *addr = 0, off_t offset = 0, LPSECURITY_ATTRIBUTES sa = 0); - // Map a file specified by <file_name>. + /// Map a file from an open file descriptor <handle>. This function + /// will lookup the length of the file if it is not given. int map (ACE_HANDLE handle, int length = -1, int prot = PROT_RDWR, @@ -66,17 +67,16 @@ public: void *addr = 0, off_t offset = 0, LPSECURITY_ATTRIBUTES sa = 0); - // Map a file from an open file descriptor <handle>. This function - // will lookup the length of the file if it is not given. + /// Remap the file associated with <handle_>. int map (int length = -1, int prot = PROT_RDWR, int share = ACE_MAP_PRIVATE, void *addr = 0, off_t offset = 0, LPSECURITY_ATTRIBUTES sa = 0); - // Remap the file associated with <handle_>. + /// Map a file specified by <filename>. int map (const ACE_TCHAR *filename, int len = -1, int flags = O_RDWR | O_CREAT, @@ -86,106 +86,113 @@ public: void *addr = 0, off_t offset = 0, LPSECURITY_ATTRIBUTES sa = 0); - // Map a file specified by <filename>. + /// Destructor. ~ACE_Mem_Map (void); - // Destructor. + /// Open the file without mapping it. int open (const ACE_TCHAR *filename, int flags = O_RDWR | O_CREAT, int mode = ACE_DEFAULT_FILE_PERMS, LPSECURITY_ATTRIBUTES sa = 0); - // Open the file without mapping it. + /// Close down the <handle_> if necessary and unmap the mapping. int close (void); - // Close down the <handle_> if necessary and unmap the mapping. + /// Close down the <handle_> if necessary. int close_handle (void); - // Close down the <handle_> if necessary. + /** + * Close down the internal <file_mapping_> if necessary. This is + * mostly necessary on Win32, which has a different handle for + * file-mapping kernel object. + */ int close_filemapping_handle (void); - // Close down the internal <file_mapping_> if necessary. This is - // mostly necessary on Win32, which has a different handle for - // file-mapping kernel object. + /// This operator passes back the starting address of the mapped + /// file. int operator () (void *&addr); - // This operator passes back the starting address of the mapped - // file. + /// Return the base address. void *addr (void) const; - // Return the base address. + /// This function returns the number of bytes currently mapped in the + /// file. size_t size (void) const; - // This function returns the number of bytes currently mapped in the - // file. + /// Unmap the region starting at <base_addr_>. int unmap (int len = -1); - // Unmap the region starting at <base_addr_>. + /// Unmap the region starting at <addr_>. int unmap (void *addr, int len); - // Unmap the region starting at <addr_>. + /** + * Sync <len> bytes of the memory region to the backing store + * starting at <base_addr_>. If <len> == -1 then sync the whole + * region. + */ int sync (ssize_t len = -1, int flags = MS_SYNC); - // Sync <len> bytes of the memory region to the backing store - // starting at <base_addr_>. If <len> == -1 then sync the whole - // region. + /// Sync <len> bytes of the memory region to the backing store + /// starting at <addr_>. int sync (void *addr, size_t len, int flags = MS_SYNC); - // Sync <len> bytes of the memory region to the backing store - // starting at <addr_>. + /** + * Change the protection of the pages of the mapped region to <prot> + * starting at <base_addr_> up to <len> bytes. If <len> == -1 then + * change protection of all pages in the mapped region. + */ int protect (ssize_t len = -1, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <base_addr_> up to <len> bytes. If <len> == -1 then - // change protection of all pages in the mapped region. + /// Change the protection of the pages of the mapped region to <prot> + /// starting at <addr> up to <len> bytes. int protect (void *addr, size_t len, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <addr> up to <len> bytes. + /// Close and remove the file from the file system. int remove (void); - // Close and remove the file from the file system. + /// Hook into the underlying VM system. int advise (int behavior, int len = -1); - // Hook into the underlying VM system. + /// Return the underlying <handle_>. ACE_HANDLE handle (void) const; - // Return the underlying <handle_>. + /// Return the name of file that is mapped (if any). const ACE_TCHAR *filename (void) const; - // Return the name of file that is mapped (if any). + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Base address of the memory-mapped file. void *base_addr_; - // Base address of the memory-mapped file. + /// Name of the file that is mapped. ACE_TCHAR filename_[MAXPATHLEN + 1]; - // Name of the file that is mapped. + /// Length of the mapping. size_t length_; - // Length of the mapping. + /// HANDLE for the open file. ACE_HANDLE handle_; - // HANDLE for the open file. + /// HANDLE for the open mapping. ACE_HANDLE file_mapping_; - // HANDLE for the open mapping. #if defined (__Lynx__) + /// Flag to indicate that PROT_WRITE has been enabled. int write_enabled_; - // Flag to indicate that PROT_WRITE has been enabled. #endif /* __Lynx__ */ + /// Keeps track of whether we need to close the handle. This is set + /// if we opened the file. int close_handle_; - // Keeps track of whether we need to close the handle. This is set - // if we opened the file. + /// This method does the dirty work of actually calling ::mmap to map + /// the file into memory. int map_it (ACE_HANDLE handle, int len = -1, int prot = PROT_RDWR, @@ -193,8 +200,6 @@ private: void *addr = 0, off_t offset = 0, LPSECURITY_ATTRIBUTES sa = 0); - // This method does the dirty work of actually calling ::mmap to map - // the file into memory. // = Disallow copying and assignment. ACE_UNIMPLEMENTED_FUNC (ACE_Mem_Map (const ACE_Mem_Map &)) diff --git a/ace/Memory_Pool.h b/ace/Memory_Pool.h index 84966642406..657f7fd42f7 100644 --- a/ace/Memory_Pool.h +++ b/ace/Memory_Pool.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ACE_Memory_Pool.h -// -// = AUTHOR -// Doug Schmidt and Prashant Jain -// -// ============================================================================ + +//============================================================================= +/** + * @file ACE_Memory_Pool.h + * + * $Id$ + * + * @author Doug Schmidt and Prashant Jain + */ +//============================================================================= + #ifndef ACE_MEMORY_POOL_H #define ACE_MEMORY_POOL_H @@ -32,84 +29,95 @@ #endif /* !ACE_WIN32 */ #if !defined (ACE_LACKS_SBRK) +/** + * @class ACE_Sbrk_Memory_Pool_Options + * + * @brief Helper class for Sbrk Memory Pool constructor options. + * + * This should be a nested class, but that breaks too many + * compilers. + */ class ACE_Export ACE_Sbrk_Memory_Pool_Options { - // = TITLE - // Helper class for Sbrk Memory Pool constructor options. - // - // = DESCRIPTION - // This should be a nested class, but that breaks too many - // compilers. }; +/** + * @class ACE_Sbrk_Memory_Pool + * + * @brief Make a memory pool that is based on <sbrk(2)>. + */ class ACE_Export ACE_Sbrk_Memory_Pool { - // = TITLE - // Make a memory pool that is based on <sbrk(2)>. public: typedef ACE_Sbrk_Memory_Pool_Options OPTIONS; + /// Initialize the pool. ACE_Sbrk_Memory_Pool (const ACE_TCHAR *backing_store_name = 0, const OPTIONS *options = 0); - // Initialize the pool. virtual ~ACE_Sbrk_Memory_Pool (void); // = Implementor operations. + /// Ask system for initial chunk of local memory. virtual void *init_acquire (size_t nbytes, size_t &rounded_bytes, int &first_time); - // Ask system for initial chunk of local memory. + /// Acquire at least NBYTES from the memory pool. ROUNDED_BYTES is + /// the actual number of bytes allocated. virtual void *acquire (size_t nbytes, size_t &rounded_bytes); - // Acquire at least NBYTES from the memory pool. ROUNDED_BYTES is - // the actual number of bytes allocated. + /// Instruct the memory pool to release all of its resources. virtual int release (void); - // Instruct the memory pool to release all of its resources. + /** + * Sync <len> bytes of the memory region to the backing store + * starting at <this->base_addr_>. If <len> == -1 then sync the + * whole region. + */ virtual int sync (ssize_t len = -1, int flags = MS_SYNC); - // Sync <len> bytes of the memory region to the backing store - // starting at <this->base_addr_>. If <len> == -1 then sync the - // whole region. + /// Sync <len> bytes of the memory region to the backing store + /// starting at <addr_>. virtual int sync (void *addr, size_t len, int flags = MS_SYNC); - // Sync <len> bytes of the memory region to the backing store - // starting at <addr_>. + /** + * Change the protection of the pages of the mapped region to <prot> + * starting at <this->base_addr_> up to <len> bytes. If <len> == -1 + * then change protection of all pages in the mapped region. + */ virtual int protect (ssize_t len = -1, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <this->base_addr_> up to <len> bytes. If <len> == -1 - // then change protection of all pages in the mapped region. + /// Change the protection of the pages of the mapped region to <prot> + /// starting at <addr> up to <len> bytes. virtual int protect (void *addr, size_t len, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <addr> up to <len> bytes. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Implement the algorithm for rounding up the request to an + /// appropriate chunksize. virtual size_t round_up (size_t nbytes); - // Implement the algorithm for rounding up the request to an - // appropriate chunksize. }; #endif /* !ACE_LACKS_SBRK */ #if !defined (ACE_LACKS_SYSV_SHMEM) +/** + * @class ACE_Shared_Memory_Pool_Options + * + * @brief Helper class for Shared Memory Pool constructor options. + * + * This should be a nested class, but that breaks too many + * compilers. + */ class ACE_Export ACE_Shared_Memory_Pool_Options { - // = TITLE - // Helper class for Shared Memory Pool constructor options. - // - // = DESCRIPTION - // This should be a nested class, but that breaks too many - // compilers. public: // = Initialization method. ACE_Shared_Memory_Pool_Options (const char *base_addr = ACE_DEFAULT_BASE_ADDR, @@ -118,84 +126,93 @@ public: off_t minimum_bytes = 0, size_t segment_size = ACE_DEFAULT_SEGMENT_SIZE); + /// Base address of the memory-mapped backing store. const char *base_addr_; - // Base address of the memory-mapped backing store. + /// Number of shared memory segments to allocate. size_t max_segments_; - // Number of shared memory segments to allocate. + /// What the minimum bytes of the initial segment should be. off_t minimum_bytes_; - // What the minimum bytes of the initial segment should be. + /// File permissions to use when creating/opening a segment. size_t file_perms_; - // File permissions to use when creating/opening a segment. + /// Shared memory segment size. size_t segment_size_; - // Shared memory segment size. }; +/** + * @class ACE_Shared_Memory_Pool + * + * @brief Make a memory pool that is based on System V shared memory + * (shmget(2) etc.). This implementation allows memory to be + * shared between processes. + */ class ACE_Export ACE_Shared_Memory_Pool : public ACE_Event_Handler { - // = TITLE - // Make a memory pool that is based on System V shared memory - // (shmget(2) etc.). This implementation allows memory to be - // shared between processes. public: typedef ACE_Shared_Memory_Pool_Options OPTIONS; + /// Initialize the pool. ACE_Shared_Memory_Pool (const ACE_TCHAR *backing_store_name = 0, const OPTIONS *options = 0); - // Initialize the pool. virtual ~ACE_Shared_Memory_Pool (void); + /// Ask system for initial chunk of local memory. virtual void *init_acquire (size_t nbytes, size_t &rounded_bytes, int &first_time); - // Ask system for initial chunk of local memory. + /** + * Acquire at least NBYTES from the memory pool. ROUNDED_BYTES is + * the actual number of bytes allocated. Also acquires an internal + * semaphore that ensures proper serialization of Memory_Pool + * initialization across processes. + */ virtual void *acquire (size_t nbytes, size_t &rounded_bytes); - // Acquire at least NBYTES from the memory pool. ROUNDED_BYTES is - // the actual number of bytes allocated. Also acquires an internal - // semaphore that ensures proper serialization of Memory_Pool - // initialization across processes. + /// Instruct the memory pool to release all of its resources. virtual int release (void); - // Instruct the memory pool to release all of its resources. + /// Sync the memory region to the backing store starting at + /// <this->base_addr_>. virtual int sync (ssize_t len = -1, int flags = MS_SYNC); - // Sync the memory region to the backing store starting at - // <this->base_addr_>. + /// Sync the memory region to the backing store starting at <addr_>. virtual int sync (void *addr, size_t len, int flags = MS_SYNC); - // Sync the memory region to the backing store starting at <addr_>. + /** + * Change the protection of the pages of the mapped region to <prot> + * starting at <this->base_addr_> up to <len> bytes. If <len> == -1 + * then change protection of all pages in the mapped region. + */ virtual int protect (ssize_t len = -1, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <this->base_addr_> up to <len> bytes. If <len> == -1 - // then change protection of all pages in the mapped region. + /// Change the protection of the pages of the mapped region to <prot> + /// starting at <addr> up to <len> bytes. virtual int protect (void *addr, size_t len, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <addr> up to <len> bytes. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Implement the algorithm for rounding up the request to an + /// appropriate chunksize. virtual size_t round_up (size_t nbytes); - // Implement the algorithm for rounding up the request to an - // appropriate chunksize. + /** + * Commits a new shared memory segment if necessary after an + * <acquire> or a signal. <offset> is set to the new offset into + * the backing store. + */ virtual int commit_backing_store_name (size_t rounded_bytes, off_t &offset); - // Commits a new shared memory segment if necessary after an - // <acquire> or a signal. <offset> is set to the new offset into - // the backing store. // = Keeps track of all the segments being used. struct SHM_TABLE @@ -210,122 +227,137 @@ protected: // Is the segment currently used.; }; + /** + * Base address of the shared memory segment. If this has the value + * of 0 then the OS is free to select any address, otherwise this + * value is what the OS must try to use to map the shared memory + * segment. + */ void *base_addr_; - // Base address of the shared memory segment. If this has the value - // of 0 then the OS is free to select any address, otherwise this - // value is what the OS must try to use to map the shared memory - // segment. + /// File permissions to use when creating/opening a segment. size_t file_perms_; - // File permissions to use when creating/opening a segment. + /// Number of shared memory segments in the <SHM_TABLE> table. size_t max_segments_; - // Number of shared memory segments in the <SHM_TABLE> table. + /// What the minimim bytes of the initial segment should be. off_t minimum_bytes_; - // What the minimim bytes of the initial segment should be. + /// Shared memory segment size. size_t segment_size_; - // Shared memory segment size. + /// Base shared memory key for the segment. key_t base_shm_key_; - // Base shared memory key for the segment. + /// find the segment that contains the searchPtr virtual int find_seg (const void *const searchPtr, off_t &offset, size_t &counter); - // find the segment that contains the searchPtr + /// Determine how much memory is currently in use. virtual int in_use (off_t &offset, size_t &counter); - // Determine how much memory is currently in use. + /// Handles SIGSEGV. ACE_Sig_Handler signal_handler_; - // Handles SIGSEGV. + /// Handle SIGSEGV and SIGBUS signals to remap shared memory + /// properly. virtual int handle_signal (int signum, siginfo_t *, ucontext_t *); - // Handle SIGSEGV and SIGBUS signals to remap shared memory - // properly. }; #endif /* !ACE_LACKS_SYSV_SHMEM */ +/** + * @class ACE_Local_Memory_Pool_Options + * + * @brief Helper class for Local Memory Pool constructor options. + * + * This should be a nested class, but that breaks too many + * compilers. + */ class ACE_Export ACE_Local_Memory_Pool_Options { - // = TITLE - // Helper class for Local Memory Pool constructor options. - // - // = DESCRIPTION - // This should be a nested class, but that breaks too many - // compilers. }; +/** + * @class ACE_Local_Memory_Pool + * + * @brief Make a memory pool that is based on C++ new/delete. This is + * useful for integrating existing components that use new/delete + * into the ACE Malloc scheme... + */ class ACE_Export ACE_Local_Memory_Pool { - // = TITLE - // Make a memory pool that is based on C++ new/delete. This is - // useful for integrating existing components that use new/delete - // into the ACE Malloc scheme... public: typedef ACE_Local_Memory_Pool_Options OPTIONS; + /// Initialize the pool. ACE_Local_Memory_Pool (const ACE_TCHAR *backing_store_name = 0, const OPTIONS *options = 0); - // Initialize the pool. virtual ~ACE_Local_Memory_Pool (void); + /// Ask system for initial chunk of local memory. virtual void *init_acquire (size_t nbytes, size_t &rounded_bytes, int &first_time); - // Ask system for initial chunk of local memory. + /// Acquire at least NBYTES from the memory pool. ROUNDED_BYTES is + /// the actual number of bytes allocated. virtual void *acquire (size_t nbytes, size_t &rounded_bytes); - // Acquire at least NBYTES from the memory pool. ROUNDED_BYTES is - // the actual number of bytes allocated. + /// Instruct the memory pool to release all of its resources. virtual int release (void); - // Instruct the memory pool to release all of its resources. + /** + * Sync <len> bytes of the memory region to the backing store + * starting at <this->base_addr_>. If <len> == -1 then sync the + * whole region. + */ virtual int sync (ssize_t len = -1, int flags = MS_SYNC); - // Sync <len> bytes of the memory region to the backing store - // starting at <this->base_addr_>. If <len> == -1 then sync the - // whole region. + /// Sync <len> bytes of the memory region to the backing store + /// starting at <addr_>. virtual int sync (void *addr, size_t len, int flags = MS_SYNC); - // Sync <len> bytes of the memory region to the backing store - // starting at <addr_>. + /** + * Change the protection of the pages of the mapped region to <prot> + * starting at <this->base_addr_> up to <len> bytes. If <len> == -1 + * then change protection of all pages in the mapped region. + */ virtual int protect (ssize_t len = -1, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <this->base_addr_> up to <len> bytes. If <len> == -1 - // then change protection of all pages in the mapped region. + /// Change the protection of the pages of the mapped region to <prot> + /// starting at <addr> up to <len> bytes. virtual int protect (void *addr, size_t len, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <addr> up to <len> bytes. #if defined (ACE_WIN32) + /** + * Win32 Structural exception selector. The return value decides + * how to handle memory pool related structural exceptions. Returns + * 1, 0, or , -1. + */ virtual int seh_selector (void *); - // Win32 Structural exception selector. The return value decides - // how to handle memory pool related structural exceptions. Returns - // 1, 0, or , -1. #endif /* ACE_WIN32 */ + /** + * Try to extend the virtual address space so that <addr> is now + * covered by the address mapping. Always returns 0 since we can't + * remap a local memory pool. + */ virtual int remap (void *addr); - // Try to extend the virtual address space so that <addr> is now - // covered by the address mapping. Always returns 0 since we can't - // remap a local memory pool. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// List of memory that we have allocated. ACE_Unbounded_Set<char *> allocated_chunks_; - // List of memory that we have allocated. virtual size_t round_up (size_t nbytes); @@ -333,14 +365,16 @@ protected: // appropriate chunksize. }; +/** + * @class ACE_MMAP_Memory_Pool_Options + * + * @brief Helper class for MMAP Memory Pool constructor options. + * + * This should be a nested class, but that breaks too many + * compilers. + */ class ACE_Export ACE_MMAP_Memory_Pool_Options { - // = TITLE - // Helper class for MMAP Memory Pool constructor options. - // - // = DESCRIPTION - // This should be a nested class, but that breaks too many - // compilers. public: // = Initialization method. ACE_MMAP_Memory_Pool_Options (const void *base_addr = ACE_DEFAULT_BASE_ADDR, @@ -351,105 +385,118 @@ public: int guess_on_fault = 1, LPSECURITY_ATTRIBUTES sa = 0); + /// Base address of the memory-mapped backing store. const void *base_addr_; - // Base address of the memory-mapped backing store. + /// Must we use the <base_addr_> or can we let mmap(2) select it? int use_fixed_addr_; - // Must we use the <base_addr_> or can we let mmap(2) select it? + /// Should each page be written eagerly to avoid surprises later + /// on? int write_each_page_; - // Should each page be written eagerly to avoid surprises later - // on? + /// What the minimim bytes of the initial segment should be. off_t minimum_bytes_; - // What the minimim bytes of the initial segment should be. + /// Any special flags that need to be used for <mmap>. u_int flags_; - // Any special flags that need to be used for <mmap>. + /** + * Try to remap without knowing the faulting address. This + * parameter is ignored on platforms that know the faulting address + * (UNIX with SI_ADDR and Win32). + */ int guess_on_fault_; - // Try to remap without knowing the faulting address. This - // parameter is ignored on platforms that know the faulting address - // (UNIX with SI_ADDR and Win32). + /// Pointer to a security attributes object. Only used on NT. LPSECURITY_ATTRIBUTES sa_; - // Pointer to a security attributes object. Only used on NT. }; +/** + * @class ACE_MMAP_Memory_Pool + * + * @brief Make a memory pool that is based on <mmap(2)>. This + * implementation allows memory to be shared between processes. + */ class ACE_Export ACE_MMAP_Memory_Pool : public ACE_Event_Handler { - // = TITLE - // Make a memory pool that is based on <mmap(2)>. This - // implementation allows memory to be shared between processes. public: typedef ACE_MMAP_Memory_Pool_Options OPTIONS; // = Initialization and termination methods. + /// Initialize the pool. ACE_MMAP_Memory_Pool (const ACE_TCHAR *backing_store_name = 0, const OPTIONS *options = 0); - // Initialize the pool. virtual ~ACE_MMAP_Memory_Pool (void); + /// Ask system for initial chunk of shared memory. virtual void *init_acquire (size_t nbytes, size_t &rounded_bytes, int &first_time); - // Ask system for initial chunk of shared memory. + /** + * Acquire at least <nbytes> from the memory pool. <rounded_bytes> + * is the actual number of bytes allocated. Also acquires an + * internal semaphore that ensures proper serialization of + * <ACE_MMAP_Memory_Pool> initialization across processes. + */ virtual void *acquire (size_t nbytes, size_t &rounded_bytes); - // Acquire at least <nbytes> from the memory pool. <rounded_bytes> - // is the actual number of bytes allocated. Also acquires an - // internal semaphore that ensures proper serialization of - // <ACE_MMAP_Memory_Pool> initialization across processes. + /// Instruct the memory pool to release all of its resources. virtual int release (void); - // Instruct the memory pool to release all of its resources. + /// Sync the memory region to the backing store starting at + /// <this->base_addr_>. virtual int sync (ssize_t len = -1, int flags = MS_SYNC); - // Sync the memory region to the backing store starting at - // <this->base_addr_>. + /// Sync the memory region to the backing store starting at <addr_>. virtual int sync (void *addr, size_t len, int flags = MS_SYNC); - // Sync the memory region to the backing store starting at <addr_>. + /** + * Change the protection of the pages of the mapped region to <prot> + * starting at <this->base_addr_> up to <len> bytes. If <len> == -1 + * then change protection of all pages in the mapped region. + */ virtual int protect (ssize_t len = -1, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <this->base_addr_> up to <len> bytes. If <len> == -1 - // then change protection of all pages in the mapped region. + /// Change the protection of the pages of the mapped region to <prot> + /// starting at <addr> up to <len> bytes. virtual int protect (void *addr, size_t len, int prot = PROT_RDWR); - // Change the protection of the pages of the mapped region to <prot> - // starting at <addr> up to <len> bytes. #if defined (ACE_WIN32) + /** + * Win32 Structural exception selector. The return value decides + * how to handle memory pool related structural exceptions. Returns + * 1, 0, or , -1. + */ virtual int seh_selector (void *); - // Win32 Structural exception selector. The return value decides - // how to handle memory pool related structural exceptions. Returns - // 1, 0, or , -1. #endif /* ACE_WIN32 */ + /** + * Try to extend the virtual address space so that <addr> is now + * covered by the address mapping. The method succeeds and returns + * 0 if the backing store has adequate memory to cover this address. + * Otherwise, it returns -1. This method is typically called by a + * UNIX signal handler for SIGSEGV or a Win32 structured exception + * when another process has grown the backing store (and its + * mapping) and our process now incurs a fault because our mapping + * isn't in range (yet). + */ virtual int remap (void *addr); - // Try to extend the virtual address space so that <addr> is now - // covered by the address mapping. The method succeeds and returns - // 0 if the backing store has adequate memory to cover this address. - // Otherwise, it returns -1. This method is typically called by a - // UNIX signal handler for SIGSEGV or a Win32 structured exception - // when another process has grown the backing store (and its - // mapping) and our process now incurs a fault because our mapping - // isn't in range (yet). + /// Return the base address of this memory pool. virtual void *base_addr (void) const; - // Return the base address of this memory pool. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Implement the algorithm for rounding up the request to an @@ -457,147 +504,162 @@ protected: virtual size_t round_up (size_t nbytes); + /// Compute the new <map_size> of the backing store and commit the + /// memory. virtual int commit_backing_store_name (size_t rounded_bytes, off_t &map_size); - // Compute the new <map_size> of the backing store and commit the - // memory. + /// Memory map the file up to <map_size> bytes. virtual int map_file (off_t map_size); - // Memory map the file up to <map_size> bytes. + /// Handle SIGSEGV and SIGBUS signals to remap shared memory + /// properly. virtual int handle_signal (int signum, siginfo_t *, ucontext_t *); - // Handle SIGSEGV and SIGBUS signals to remap shared memory - // properly. + /// Handles SIGSEGV. ACE_Sig_Handler signal_handler_; - // Handles SIGSEGV. + /// Memory-mapping object. ACE_Mem_Map mmap_; - // Memory-mapping object. + /** + * Base of mapped region. If this has the value of 0 then the OS is + * free to select any address to map the file, otherwise this value + * is what the OS must try to use to mmap the file. + */ void *base_addr_; - // Base of mapped region. If this has the value of 0 then the OS is - // free to select any address to map the file, otherwise this value - // is what the OS must try to use to mmap the file. + /// Flags passed into <ACE_OS::mmap>. int flags_; - // Flags passed into <ACE_OS::mmap>. + /// Should we write a byte to each page to forceably allocate memory + /// for this backing store? int write_each_page_; - // Should we write a byte to each page to forceably allocate memory - // for this backing store? + /// What the minimum bytes of the initial segment should be. off_t minimum_bytes_; - // What the minimum bytes of the initial segment should be. + /// Name of the backing store where the shared memory pool is kept. ACE_TCHAR backing_store_name_[MAXPATHLEN + 1]; - // Name of the backing store where the shared memory pool is kept. + /** + * Try to remap without knowing the faulting address. This + * parameter is ignored on platforms that know the faulting address + * (UNIX with SI_ADDR and Win32). + */ int guess_on_fault_; - // Try to remap without knowing the faulting address. This - // parameter is ignored on platforms that know the faulting address - // (UNIX with SI_ADDR and Win32). + /// Security attributes object, only used on NT. LPSECURITY_ATTRIBUTES sa_; - // Security attributes object, only used on NT. }; +/** + * @class ACE_Lite_MMAP_Memory_Pool + * + * @brief Make a ``lighter-weight'' memory pool based <ACE_Mem_Map>. + * + * This implementation allows memory to be shared between + * processes. However, unlike the <ACE_MMAP_Memory_Pool> + * the <sync> methods are no-ops, which means that we don't pay + * for the price of flushing the memory to the backing store on + * every update. Naturally, this trades off increased + * performance for less reliability if the machine crashes. + */ class ACE_Export ACE_Lite_MMAP_Memory_Pool : public ACE_MMAP_Memory_Pool { - // = TITLE - // Make a ``lighter-weight'' memory pool based <ACE_Mem_Map>. - // - // = DESCRIPTION - // This implementation allows memory to be shared between - // processes. However, unlike the <ACE_MMAP_Memory_Pool> - // the <sync> methods are no-ops, which means that we don't pay - // for the price of flushing the memory to the backing store on - // every update. Naturally, this trades off increased - // performance for less reliability if the machine crashes. public: // = Initialization and termination methods. + /// Initialize the pool. ACE_Lite_MMAP_Memory_Pool (const ACE_TCHAR *backing_store_name = 0, const OPTIONS *options = 0); - // Initialize the pool. virtual ~ACE_Lite_MMAP_Memory_Pool (void); + /// Overwrite the default sync behavior with no-op virtual int sync (ssize_t len = -1, int flags = MS_SYNC); - // Overwrite the default sync behavior with no-op + /// Overwrite the default sync behavior with no-op virtual int sync (void *addr, size_t len, int flags = MS_SYNC); - // Overwrite the default sync behavior with no-op }; #if defined (ACE_WIN32) +/** + * @class ACE_Pagefile_Memory_Pool_Options + * + * @brief Helper class for Pagefile Memory Pool constructor options. + * + * This should be a nested class, but that breaks too many + * compilers. + */ class ACE_Export ACE_Pagefile_Memory_Pool_Options { - // = TITLE - // Helper class for Pagefile Memory Pool constructor options. - // - // = DESCRIPTION - // This should be a nested class, but that breaks too many - // compilers. public: // Initialization method. ACE_Pagefile_Memory_Pool_Options (void *base_addr = ACE_DEFAULT_PAGEFILE_POOL_BASE, size_t max_size = ACE_DEFAULT_PAGEFILE_POOL_SIZE); + /// Base address of the memory-mapped backing store. void *base_addr_; - // Base address of the memory-mapped backing store. + /// Maximum size the pool may grow. size_t max_size_; - // Maximum size the pool may grow. }; +/** + * @class ACE_Pagefile_Memory_Pool + * + * @brief Make a memory pool that is based on "anonymous" memory + * regions allocated from the Win32 page file. + */ class ACE_Export ACE_Pagefile_Memory_Pool { - // = TITLE - // Make a memory pool that is based on "anonymous" memory - // regions allocated from the Win32 page file. public: typedef ACE_Pagefile_Memory_Pool_Options OPTIONS; + /// Initialize the pool. ACE_Pagefile_Memory_Pool (const ACE_TCHAR *backing_store_name = 0, const OPTIONS *options = 0); - // Initialize the pool. + /// Ask system for initial chunk of shared memory. void *init_acquire (size_t nbytes, size_t &rounded_bytes, int &first_time); - // Ask system for initial chunk of shared memory. + /// Acquire at least <nbytes> from the memory pool. <rounded_bytes> + /// is the actual number of bytes allocated. void *acquire (size_t nbytes, size_t &rounded_bytes); - // Acquire at least <nbytes> from the memory pool. <rounded_bytes> - // is the actual number of bytes allocated. + /// Instruct the memory pool to release all of its resources. int release (void); - // Instruct the memory pool to release all of its resources. + /** + * Win32 Structural exception selector. The return value decides + * how to handle memory pool related structural exceptions. Returns + * 1, 0, or , -1. + */ virtual int seh_selector (void *); - // Win32 Structural exception selector. The return value decides - // how to handle memory pool related structural exceptions. Returns - // 1, 0, or , -1. + /** + * Try to extend the virtual address space so that <addr> is now + * covered by the address mapping. The method succeeds and returns + * 0 if the backing store has adequate memory to cover this address. + * Otherwise, it returns -1. This method is typically called by an + * exception handler for a Win32 structured exception when another + * process has grown the backing store (and its mapping) and our + * process now incurs a fault because our mapping isn't in range + * (yet). + */ int remap (void *addr); - // Try to extend the virtual address space so that <addr> is now - // covered by the address mapping. The method succeeds and returns - // 0 if the backing store has adequate memory to cover this address. - // Otherwise, it returns -1. This method is typically called by an - // exception handler for a Win32 structured exception when another - // process has grown the backing store (and its mapping) and our - // process now incurs a fault because our mapping isn't in range - // (yet). + /// Round up to system page size. size_t round_to_page_size (size_t nbytes); - // Round up to system page size. + /// Round up to the chunk size required by the operation system size_t round_to_chunk_size (size_t nbytes); - // Round up to the chunk size required by the operation system // = Don't need this methods here ... int sync (ssize_t = -1, int = MS_SYNC); @@ -608,43 +670,51 @@ public: protected: + /** + * Map portions or the entire pool into the local virtual address + * space. To do this, we compute the new <file_offset> of the + * backing store and commit the memory. + */ int map (int &firstTime, int appendBytes = 0); - // Map portions or the entire pool into the local virtual address - // space. To do this, we compute the new <file_offset> of the - // backing store and commit the memory. + /// Release the mapping. int unmap (void); - // Release the mapping. private: + /** + * @class Control_Block + * + * @brief Attributes that are meaningful in local storage only. + */ class Control_Block { - // = TITLE - // Attributes that are meaningful in local storage only. public: + /// required base address void *req_base_; - // required base address + /// Base address returned from system call void *mapped_base_; - // Base address returned from system call + /** + * @class Shared_Control_Block + * + * @brief Pool statistics + */ class Shared_Control_Block { - // = TITLE - // Pool statistics public: + /// Maximum size the pool may grow size_t max_size_; - // Maximum size the pool may grow + /// Size of mapped shared memory segment int mapped_size_; - // Size of mapped shared memory segment + /// Offset to mapped but not yet acquired address space int free_offset_; - // Offset to mapped but not yet acquired address space + /// Size of mapped but not yet acquired address space int free_size_; - // Size of mapped but not yet acquired address space }; Shared_Control_Block sh_; @@ -654,20 +724,20 @@ private: // free to select any address to map the file, otherwise this value // is what the OS must try to use to mmap the file. + /// Description of what our process mapped. Control_Block local_cb_; - // Description of what our process mapped. + /// Shared memory pool statistics. Control_Block *shared_cb_; - // Shared memory pool statistics. + /// File mapping handle. ACE_HANDLE object_handle_; - // File mapping handle. + /// System page size. size_t page_size_; - // System page size. + /// Name of the backing store where the shared memory pool is kept. ACE_TCHAR backing_store_name_[MAXPATHLEN]; - // Name of the backing store where the shared memory pool is kept. }; #endif /* ACE_WIN32 */ diff --git a/ace/Message_Block.h b/ace/Message_Block.h index 8df4d6fab40..a85356c5e11 100644 --- a/ace/Message_Block.h +++ b/ace/Message_Block.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Message_Block.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Message_Block.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #include "ace/ACE.h" @@ -31,64 +28,85 @@ class ACE_Data_Block; class ACE_Lock; class ACE_Time_Value; +/** + * @class ACE_Message_Block + * + * @brief Stores messages for use throughout ACE (particularly + * <ACE_Message_Queue>). + * + * An <ACE_Message_Block> is modeled after the message data + * structures used in System V STREAMS. Its purpose is to + * enable efficient manipulation of arbitrarily-large messages + * without much incurring memory copying overhead. Here are the + * main characteristics of an <ACE_Message_Block>: + * 1. Contains a pointer to a reference-counted + * <ACE_Data_Block>, which in turn points to the actual data + * buffer. This allows very flexible and efficient sharing of + * data by multiple <ACE_Message_Block>s. + * 2. One or more <ACE_Message_Blocks> can be linked to form a + * ``fragment chain.'' + * 3. <ACE_Message_Blocks> can be linked together by <prev_> and + * <next_> pointers to form a queue of messages (e.g., this is how + * <ACE_Message_Queue> works). + */ class ACE_Export ACE_Message_Block { - // = TITLE - // Stores messages for use throughout ACE (particularly - // <ACE_Message_Queue>). - // - // = DESCRIPTION - // An <ACE_Message_Block> is modeled after the message data - // structures used in System V STREAMS. Its purpose is to - // enable efficient manipulation of arbitrarily-large messages - // without much incurring memory copying overhead. Here are the - // main characteristics of an <ACE_Message_Block>: - // - // 1. Contains a pointer to a reference-counted - // <ACE_Data_Block>, which in turn points to the actual data - // buffer. This allows very flexible and efficient sharing of - // data by multiple <ACE_Message_Block>s. - // - // 2. One or more <ACE_Message_Blocks> can be linked to form a - // ``fragment chain.'' - // - // 3. <ACE_Message_Blocks> can be linked together by <prev_> and - // <next_> pointers to form a queue of messages (e.g., this is how - // <ACE_Message_Queue> works). public: friend class ACE_Data_Block; enum { - // = Data and protocol messages (regular and priority) - MB_DATA = 0x01, // regular data - MB_PROTO = 0x02, // protocol control - - // = Control messages (regular and priority) - MB_BREAK = 0x03, // line break - MB_PASSFP = 0x04, // pass file pointer - MB_EVENT = 0x05, // post an event to an event queue - MB_SIG = 0x06, // generate process signal - MB_IOCTL = 0x07, // ioctl; set/get params - MB_SETOPTS = 0x08, // set various stream head options - - // = Control messages (high priority; go to head of queue) - MB_IOCACK = 0x81, // acknowledge ioctl - MB_IOCNAK = 0x82, // negative ioctl acknowledge - MB_PCPROTO = 0x83, // priority proto message - MB_PCSIG = 0x84, // generate process signal - MB_READ = 0x85, // generate read notification - MB_FLUSH = 0x86, // flush your queues - MB_STOP = 0x87, // stop transmission immediately - MB_START = 0x88, // restart transmission after stop - MB_HANGUP = 0x89, // line disconnect - MB_ERROR = 0x8a, // fatal error used to set u.u_error - MB_PCEVENT = 0x8b, // post an event to an event queue - - // Message class masks - MB_NORMAL = 0x00, // Normal priority messages - MB_PRIORITY = 0x80, // High priority control messages - MB_USER = 0x200 // User-defined control messages + // = Data and proto + /// regular datacol messages (regular and priority) + MB_DATA = 0x01, + /// protocol control + MB_PROTO = 0x02, + + // = Control messag + /// line breakes (regular and priority) + MB_BREAK = 0x03, + /// pass file pointer + MB_PASSFP = 0x04, + /// post an event to an event queue + MB_EVENT = 0x05, + /// generate process signal + MB_SIG = 0x06, + /// ioctl; set/get params + MB_IOCTL = 0x07, + /// set various stream head options + MB_SETOPTS = 0x08, + + // = Control messag + /// acknowledge ioctles (high priority; go to head of queue) + MB_IOCACK = 0x81, + /// negative ioctl acknowledge + MB_IOCNAK = 0x82, + /// priority proto message + MB_PCPROTO = 0x83, + /// generate process signal + MB_PCSIG = 0x84, + /// generate read notification + MB_READ = 0x85, + /// flush your queues + MB_FLUSH = 0x86, + /// stop transmission immediately + MB_STOP = 0x87, + /// restart transmission after stop + MB_START = 0x88, + /// line disconnect + MB_HANGUP = 0x89, + /// fatal error used to set u.u_error + MB_ERROR = 0x8a, + /// post an event to an event queue + MB_PCEVENT = 0x8b, + + // Message class ma + /// Normal priority messagessks + MB_NORMAL = 0x00, + /// High priority control messages + MB_PRIORITY = 0x80, + /// User-defined control messages + MB_USER = 0x200 }; typedef int ACE_Message_Type; @@ -96,26 +114,52 @@ public: enum { - DONT_DELETE = 01, // Don't delete the data on exit since we don't own it. - USER_FLAGS = 0x1000 // user defined flags start here + /// Don't delete the data on exit since we don't own it. + DONT_DELETE = 01, + /// user defined flags start here + USER_FLAGS = 0x1000 }; // = Initialization and termination. + /// Create an empty message. ACE_Message_Block (ACE_Allocator *message_block_allocator = 0); - // Create an empty message. + /// Create an <ACE_Message_Block> that owns the <ACE_Data_Block> *. ACE_Message_Block (ACE_Data_Block *, ACE_Allocator *message_block_allocator = 0); - // Create an <ACE_Message_Block> that owns the <ACE_Data_Block> *. + /** + * Create a Message Block that assumes ownership of <data> without + * copying it (i.e., we don't delete it since we don't malloc it!). + * Note that the <size> of the <Message_Block> will be <size>, but + * the <length> will be 0 until <wr_ptr> is set. + */ ACE_Message_Block (const char *data, size_t size = 0, u_long priority = ACE_DEFAULT_MESSAGE_BLOCK_PRIORITY); - // Create a Message Block that assumes ownership of <data> without - // copying it (i.e., we don't delete it since we don't malloc it!). - // Note that the <size> of the <Message_Block> will be <size>, but - // the <length> will be 0 until <wr_ptr> is set. + /** + * Create an initialized message of type <type> containing <size> + * bytes. The <cont> argument initializes the continuation field in + * the <Message_Block>. If <data> == 0 then we create and own the + * <data>, using <allocator> to get the data if it's non-0. If + * <data> != 0 we assume ownership of the <data> (and don't delete + * it). If <locking_strategy> is non-0 then this is used to protect + * regions of code that access shared state (e.g., reference + * counting) from race conditions. Note that the <size> of the + * <Message_Block> will be <size>, but the <length> will be 0 until + * <wr_ptr> is set. + * The <data_block_allocator> is use to allocate the data blocks + * while the <allocator_strategy> is used to allocate the buffers + * contained by those. + * The <message_block_allocator> is used to allocate new + * <Message_Block> objects when a duplicate method is called. If + * a <message_block_allocator> is given, this <Message_Block> and + * future <Message_Block> objects created by duplicate will be free'ed + * into this allocator when they are released. Note: if you use this + * allocator, the <Message_Block> you created should have been created + * using this allocator because it will be released to the same allocator. + */ ACE_Message_Block (size_t size, ACE_Message_Type type = MB_DATA, ACE_Message_Block *cont = 0, @@ -127,34 +171,31 @@ public: const ACE_Time_Value &deadline_time = ACE_Time_Value::max_time, ACE_Allocator *data_block_allocator = 0, ACE_Allocator *message_block_allocator = 0); - // Create an initialized message of type <type> containing <size> - // bytes. The <cont> argument initializes the continuation field in - // the <Message_Block>. If <data> == 0 then we create and own the - // <data>, using <allocator> to get the data if it's non-0. If - // <data> != 0 we assume ownership of the <data> (and don't delete - // it). If <locking_strategy> is non-0 then this is used to protect - // regions of code that access shared state (e.g., reference - // counting) from race conditions. Note that the <size> of the - // <Message_Block> will be <size>, but the <length> will be 0 until - // <wr_ptr> is set. - // The <data_block_allocator> is use to allocate the data blocks - // while the <allocator_strategy> is used to allocate the buffers - // contained by those. - // The <message_block_allocator> is used to allocate new - // <Message_Block> objects when a duplicate method is called. If - // a <message_block_allocator> is given, this <Message_Block> and - // future <Message_Block> objects created by duplicate will be free'ed - // into this allocator when they are released. Note: if you use this - // allocator, the <Message_Block> you created should have been created - // using this allocator because it will be released to the same allocator. + /** + * Create a Message Block that assumes ownership of <data> (i.e., + * doesn't delete it since it didn't malloc it!). Note that the + * <size> of the <Message_Block> will be <size>, but the <length> + * will be 0 until <wr_ptr> is set. + */ int init (const char *data, size_t size = 0); - // Create a Message Block that assumes ownership of <data> (i.e., - // doesn't delete it since it didn't malloc it!). Note that the - // <size> of the <Message_Block> will be <size>, but the <length> - // will be 0 until <wr_ptr> is set. + /** + * Create an initialized message of type <type> containing <size> + * bytes. The <cont> argument initializes the continuation field in + * the <Message_Block>. If <data> == 0 then we create and own the + * <data>, using <allocator> to get the data if it's non-0. If + * <data> != 0 we assume ownership of the <data> (and don't delete + * it). If <locking_strategy> is non-0 then this is used to protect + * regions of code that access shared state (e.g., reference + * counting) from race conditions. Note that the <size> of the + * <Message_Block> will be <size>, but the <length> will be 0 until + * <wr_ptr> is set. + * The <data_block_allocator> is use to allocate the data blocks + * while the <allocator_strategy> is used to allocate the buffers + * contained by those. + */ int init (size_t size, ACE_Message_Type type = MB_DATA, ACE_Message_Block *cont = 0, @@ -166,258 +207,272 @@ public: const ACE_Time_Value &deadline_time = ACE_Time_Value::max_time, ACE_Allocator *data_block_allocator = 0, ACE_Allocator *message_block_allocator = 0); - // Create an initialized message of type <type> containing <size> - // bytes. The <cont> argument initializes the continuation field in - // the <Message_Block>. If <data> == 0 then we create and own the - // <data>, using <allocator> to get the data if it's non-0. If - // <data> != 0 we assume ownership of the <data> (and don't delete - // it). If <locking_strategy> is non-0 then this is used to protect - // regions of code that access shared state (e.g., reference - // counting) from race conditions. Note that the <size> of the - // <Message_Block> will be <size>, but the <length> will be 0 until - // <wr_ptr> is set. - // The <data_block_allocator> is use to allocate the data blocks - // while the <allocator_strategy> is used to allocate the buffers - // contained by those. + /** + * Delete all the resources held in the message. + * + * Note that <release> is designed to release the continuation + * chain; the destructor is not. See <release> for details. + */ virtual ~ACE_Message_Block (void); - // Delete all the resources held in the message. - // - // Note that <release> is designed to release the continuation - // chain; the destructor is not. See <release> for details. // = Message Type accessors and mutators. + /// Get type of the message. ACE_Message_Type msg_type (void) const; - // Get type of the message. + /// Set type of the message. void msg_type (ACE_Message_Type type); - // Set type of the message. + /// Find out what type of message this is. int is_data_msg (void) const; - // Find out what type of message this is. + /// Find out what class of message this is (there are two classes, + /// <normal> messages and <high-priority> messages). ACE_Message_Type msg_class (void) const; - // Find out what class of message this is (there are two classes, - // <normal> messages and <high-priority> messages). // = Message flag accessors and mutators. + /// Bitwise-or the <more_flags> into the existing message flags and + /// return the new value. Message_Flags set_flags (Message_Flags more_flags); - // Bitwise-or the <more_flags> into the existing message flags and - // return the new value. + /// Clear the message flag bits specified in <less_flags> and return + /// the new value. Message_Flags clr_flags (Message_Flags less_flags); - // Clear the message flag bits specified in <less_flags> and return - // the new value. + /// Get the current message flags. Message_Flags flags (void) const; - // Get the current message flags. + /// Get priority of the message. u_long msg_priority (void) const; - // Get priority of the message. + /// Set priority of the message. void msg_priority (u_long priority); - // Set priority of the message. + /// Get execution time associated with the message. const ACE_Time_Value &msg_execution_time (void) const; - // Get execution time associated with the message. + /// Set execution time associated with the message. void msg_execution_time (const ACE_Time_Value &et); - // Set execution time associated with the message. + /// Get absolute time of deadline associated with the message. const ACE_Time_Value &msg_deadline_time (void) const; - // Get absolute time of deadline associated with the message. + /// Set absolute time of deadline associated with the message. void msg_deadline_time (const ACE_Time_Value &dt); - // Set absolute time of deadline associated with the message. // = Deep copy and shallow copy methods. + /// Return an exact "deep copy" of the message, i.e., create fresh + /// new copies of all the Data_Blocks and continuations. virtual ACE_Message_Block *clone (Message_Flags mask = 0) const; - // Return an exact "deep copy" of the message, i.e., create fresh - // new copies of all the Data_Blocks and continuations. + /// Return a "shallow" copy that increments our reference count by 1. ACE_Message_Block *duplicate (void) const; - // Return a "shallow" copy that increments our reference count by 1. + /** + * Return a "shallow" copy that increments our reference count by 1. + * This is similar to CORBA's <_duplicate> method, which is useful + * if you want to eliminate lots of checks for NULL <mb> pointers + * before calling <_duplicate> on them. + */ static ACE_Message_Block *duplicate (const ACE_Message_Block *mb); - // Return a "shallow" copy that increments our reference count by 1. - // This is similar to CORBA's <_duplicate> method, which is useful - // if you want to eliminate lots of checks for NULL <mb> pointers - // before calling <_duplicate> on them. + /** + * Decrease the shared ACE_Data_Block's reference count by 1. If the + * ACE_Data_Block's reference count goes to 0, it is deleted. + * In all cases, this ACE_Message_Block is deleted - it must have come + * from the heap, or there will be trouble. + * + * <release> is designed to release the continuation chain; the + * destructor is not. If we make the destructor release the + * continuation chain by calling <release> or delete on the message + * blocks in the continuation chain, the following code will not + * work since the message block in the continuation chain is not off + * the heap: + * + * ACE_Message_Block mb1 (1024); + * ACE_Message_Block mb2 (1024); + * + * mb1.cont (&mb2); + * + * And hence, call <release> on a dynamically allocated message + * block. This will release all the message blocks in the + * continuation chain. If you call delete or let the message block + * fall off the stack, cleanup of the message blocks in the + * continuation chain becomes the responsibility of the user. + */ ACE_Message_Block *release (void); - // Decrease the shared ACE_Data_Block's reference count by 1. If the - // ACE_Data_Block's reference count goes to 0, it is deleted. - // In all cases, this ACE_Message_Block is deleted - it must have come - // from the heap, or there will be trouble. - // - // <release> is designed to release the continuation chain; the - // destructor is not. If we make the destructor release the - // continuation chain by calling <release> or delete on the message - // blocks in the continuation chain, the following code will not - // work since the message block in the continuation chain is not off - // the heap: - // - // ACE_Message_Block mb1 (1024); - // ACE_Message_Block mb2 (1024); - // - // mb1.cont (&mb2); - // - // And hence, call <release> on a dynamically allocated message - // block. This will release all the message blocks in the - // continuation chain. If you call delete or let the message block - // fall off the stack, cleanup of the message blocks in the - // continuation chain becomes the responsibility of the user. + /** + * This behaves like the non-static method <release>, except that it + * checks if <mb> is 0. This is similar to <CORBA::release>, which + * is useful if you want to eliminate lots of checks for NULL + * pointers before calling <release> on them. Returns <mb>. + */ static ACE_Message_Block *release (ACE_Message_Block *mb); - // This behaves like the non-static method <release>, except that it - // checks if <mb> is 0. This is similar to <CORBA::release>, which - // is useful if you want to eliminate lots of checks for NULL - // pointers before calling <release> on them. Returns <mb>. // = Operations on Message data + /** + * Copies <n> bytes from <buf> into the Message_Block starting at + * the <wr_ptr> offset. Return 0 and increment <wr_ptr> by <n> if + * the method succeeds. Returns -1 if the size of the message is + * too small, i.e., for this to work correct, <end> must be >= + * <wr_ptr>. + */ int copy (const char *buf, size_t n); - // Copies <n> bytes from <buf> into the Message_Block starting at - // the <wr_ptr> offset. Return 0 and increment <wr_ptr> by <n> if - // the method succeeds. Returns -1 if the size of the message is - // too small, i.e., for this to work correct, <end> must be >= - // <wr_ptr>. + /** + * Copies <buf> into the Message_Block starting at the <wr_ptr> + * offset. This call assumees that <buf> is NUL-terminated. Return + * 0 and increment <wr_ptr> by <ACE_OS::strlen (buf) + 1> if the + * method succeeds. Returns -1 if the size of the message is too + * small, i.e., for this to work correct, <end> must be >= <wr_ptr>. + */ int copy (const char *buf); - // Copies <buf> into the Message_Block starting at the <wr_ptr> - // offset. This call assumees that <buf> is NUL-terminated. Return - // 0 and increment <wr_ptr> by <ACE_OS::strlen (buf) + 1> if the - // method succeeds. Returns -1 if the size of the message is too - // small, i.e., for this to work correct, <end> must be >= <wr_ptr>. + /// Normalizes data in the top-level <Message_Block> to align with the base. void crunch (void); - // Normalizes data in the top-level <Message_Block> to align with the base. + /// Resets the Message Block data to contain nothing, i.e., sets the + /// read and write pointers to align with the base. void reset (void); - // Resets the Message Block data to contain nothing, i.e., sets the - // read and write pointers to align with the base. + /// Get message data. char *base (void) const; - // Get message data. + /// Set message data (doesn't reallocate). void base (char *data, size_t size, Message_Flags = DONT_DELETE); - // Set message data (doesn't reallocate). + /// Return a pointer to 1 past the end of the allocated data in a message. char *end (void) const; - // Return a pointer to 1 past the end of the allocated data in a message. + /** + * Return a pointer to 1 past the end of the allotted data in a message. + * Allotted data may be less than allocated data if a value smaller than + * capacity() to is passed to size(). + */ char *mark (void) const; - // Return a pointer to 1 past the end of the allotted data in a message. - // Allotted data may be less than allocated data if a value smaller than - // capacity() to is passed to size(). + /** + * Get the read pointer. + * Set the read pointer to <ptr>. + * Set the read pointer ahead <n> bytes. + */ char *rd_ptr (void) const; - // Get the read pointer. void rd_ptr (char *ptr); - // Set the read pointer to <ptr>. void rd_ptr (size_t n); - // Set the read pointer ahead <n> bytes. + /** + * Get the write pointer. + * Set the write pointer to <ptr>. + * Set the write pointer ahead <n> bytes. This is used to compute + * the <length> of a message. + */ char *wr_ptr (void) const; - // Get the write pointer. void wr_ptr (char *ptr); - // Set the write pointer to <ptr>. void wr_ptr (size_t n); - // Set the write pointer ahead <n> bytes. This is used to compute - // the <length> of a message. // = Message length is <wr_ptr> - <rd_ptr>. + /** + * Get the length of the message + * Set the length of the message + * Get the length of the <Message_Block>s, including chained + * <Message_Block>s. + */ size_t length (void) const; - // Get the length of the message void length (size_t n); - // Set the length of the message size_t total_length (void) const; - // Get the length of the <Message_Block>s, including chained - // <Message_Block>s. // = Set/get <Message_Block> size info. + /// Get the total number of bytes in all <Message_Block>s, including + /// chained <Message_Block>s. size_t total_size (void) const; - // Get the total number of bytes in all <Message_Block>s, including - // chained <Message_Block>s. + /// Get the number of bytes in the top-level <Message_Block> (i.e., + /// does not consider the bytes in chained <Message_Block>s). size_t size (void) const; - // Get the number of bytes in the top-level <Message_Block> (i.e., - // does not consider the bytes in chained <Message_Block>s). + /** + * Set the number of bytes in the top-level <Message_Block>, + * reallocating space if necessary. However, the <rd_ptr_> and + * <wr_ptr_> remain at the original offsets into the buffer, even if + * it is reallocated. Returns 0 if successful, else -1. + */ int size (size_t length); - // Set the number of bytes in the top-level <Message_Block>, - // reallocating space if necessary. However, the <rd_ptr_> and - // <wr_ptr_> remain at the original offsets into the buffer, even if - // it is reallocated. Returns 0 if successful, else -1. + /// Get the number of allocated bytes in all <Message_Block>, including + /// chained <Message_Block>s. size_t total_capacity (void) const; - // Get the number of allocated bytes in all <Message_Block>, including - // chained <Message_Block>s. + /// Get the number of allocated bytes in the top-level <Message_Block>. size_t capacity (void) const; - // Get the number of allocated bytes in the top-level <Message_Block>. + /// Get the number of bytes available after the <wr_ptr_> in the + /// top-level <Message_Block>. size_t space (void) const; - // Get the number of bytes available after the <wr_ptr_> in the - // top-level <Message_Block>. // = <ACE_Data_Block> methods. + /** + * Get a pointer to the data block. Note that the <ACE_Message_Block> + * still references the block; this call does not change the reference + * count. + */ ACE_Data_Block *data_block (void) const; - // Get a pointer to the data block. Note that the <ACE_Message_Block> - // still references the block; this call does not change the reference - // count. + /** + * Set a new data block pointer. The original <ACE_Data_Block> is released + * as a result of this call. If you need to keep the original block, call + * <replace_data_block> instead. Upon return, this <ACE_Message_Block> + * holds a pointer to the new <ACE_Data_Block>, taking over the reference + * you held on it prior to the call. + */ void data_block (ACE_Data_Block *); - // Set a new data block pointer. The original <ACE_Data_Block> is released - // as a result of this call. If you need to keep the original block, call - // <replace_data_block> instead. Upon return, this <ACE_Message_Block> - // holds a pointer to the new <ACE_Data_Block>, taking over the reference - // you held on it prior to the call. + /// Set a new data block pointer. A pointer to the original <ACE_Data_Block> + /// is returned, and not released (as it is with <data_block>). ACE_Data_Block *replace_data_block (ACE_Data_Block*); - // Set a new data block pointer. A pointer to the original <ACE_Data_Block> - // is returned, and not released (as it is with <data_block>). // = The continuation field chains together composite messages. + /// Get the continuation field. + /// Set the continuation field. ACE_Message_Block *cont (void) const; - // Get the continuation field. void cont (ACE_Message_Block *); - // Set the continuation field. // = Pointer to the <Message_Block> directly ahead in the <ACE_Message_Queue>. + /// Get link to next message. + /// Set link to next message. ACE_Message_Block *next (void) const; - // Get link to next message. void next (ACE_Message_Block *); - // Set link to next message. // = Pointer to the <Message_Block> directly behind in the <ACE_Message_Queue>. + /// Get link to prev message. + /// Set link to prev message. ACE_Message_Block *prev (void) const; - // Get link to prev message. void prev (ACE_Message_Block *); - // Set link to prev message. // = The locking strategy prevents race conditions. + /// Get the locking strategy. + /// Set a new locking strategy and return the hold one. ACE_Lock *locking_strategy (void); - // Get the locking strategy. ACE_Lock *locking_strategy (ACE_Lock *); - // Set a new locking strategy and return the hold one. + /// Get the current reference count. int reference_count (void) const; - // Get the current reference count. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Internal initialization methods. + /// Perform the actual initialization. ACE_Message_Block (size_t size, ACE_Message_Type type, ACE_Message_Block *cont, @@ -431,12 +486,12 @@ protected: ACE_Data_Block *db, ACE_Allocator *data_block_allocator, ACE_Allocator *message_block_allocator); - // Perform the actual initialization. + /// Internal release implementation + /// Returns 1 if the data block has to be destroyed. int release_i (ACE_Lock *lock); - // Internal release implementation - // Returns 1 if the data block has to be destroyed. + /// Perform the actual initialization. int init_i (size_t size, ACE_Message_Type type, ACE_Message_Block *cont, @@ -450,42 +505,41 @@ protected: ACE_Data_Block *db, ACE_Allocator *data_block_allocator, ACE_Allocator *message_block_allocator); - // Perform the actual initialization. + /// Pointer to beginning of next read. size_t rd_ptr_; - // Pointer to beginning of next read. + /// Pointer to beginning of next write. size_t wr_ptr_; - // Pointer to beginning of next write. + /// Priority of message. u_long priority_; - // Priority of message. #if defined (ACE_HAS_TIMED_MESSAGE_BLOCKS) + /// execution time associated with the message ACE_Time_Value execution_time_; - // execution time associated with the message + /// absolute deadline time for message ACE_Time_Value deadline_time_; - // absolute deadline time for message #endif /* ACE_HAS_TIMED_MESSAGE_BLOCKS */ // = Links to other ACE_Message_Block *s. + /// Pointer to next message block in the chain. ACE_Message_Block *cont_; - // Pointer to next message block in the chain. + /// Pointer to next message in the list. ACE_Message_Block *next_; - // Pointer to next message in the list. + /// Pointer to previous message in the list. ACE_Message_Block *prev_; - // Pointer to previous message in the list. + /// Pointer to the reference counted data structure that contains the + /// actual memory buffer. ACE_Data_Block *data_block_; - // Pointer to the reference counted data structure that contains the - // actual memory buffer. + /// The allocator used to destroy ourselves when release is called + /// and create new message blocks on duplicate. ACE_Allocator *message_block_allocator_; - // The allocator used to destroy ourselves when release is called - // and create new message blocks on duplicate. private: // = Disallow these operations for now (use <clone> instead). @@ -493,23 +547,26 @@ private: ACE_Message_Block (const ACE_Message_Block &); }; +/** + * @class ACE_Data_Block + * + * @brief Stores the data payload that is accessed via one or more + * <ACE_Message_Block>s. + * + * This data structure is reference counted to maximize + * sharing. It also contains the <locking_strategy_> (which + * protects the reference count from race conditions in + * concurrent programs) and the <allocation_strategy_> (which + * determines what memory pool is used to allocate the memory). + */ class ACE_Export ACE_Data_Block { - // = TITLE - // Stores the data payload that is accessed via one or more - // <ACE_Message_Block>s. - // - // = DESCRIPTION - // This data structure is reference counted to maximize - // sharing. It also contains the <locking_strategy_> (which - // protects the reference count from race conditions in - // concurrent programs) and the <allocation_strategy_> (which - // determines what memory pool is used to allocate the memory). public: // = Initialization and termination methods. + /// Default "do-nothing" constructor. ACE_Data_Block (void); - // Default "do-nothing" constructor. + /// Initialize. ACE_Data_Block (size_t size, ACE_Message_Block::ACE_Message_Type msg_type, const char *msg_data, @@ -517,146 +574,161 @@ public: ACE_Lock *locking_strategy, ACE_Message_Block::Message_Flags flags, ACE_Allocator *data_block_allocator); - // Initialize. + /// Delete all the resources held in the message. virtual ~ACE_Data_Block (void); - // Delete all the resources held in the message. + /// Get type of the message. ACE_Message_Block::ACE_Message_Type msg_type (void) const; - // Get type of the message. + /// Set type of the message. void msg_type (ACE_Message_Block::ACE_Message_Type type); - // Set type of the message. + /// Get message data pointer char *base (void) const; - // Get message data pointer + /// Set message data pointer (doesn't reallocate). void base (char *data, size_t size, ACE_Message_Block::Message_Flags mflags = ACE_Message_Block::DONT_DELETE); - // Set message data pointer (doesn't reallocate). + /// Return a pointer to 1 past the end of the allocated data in a message. char *end (void) const; - // Return a pointer to 1 past the end of the allocated data in a message. + /** + * Return a pointer to 1 past the end of the allotted data in a message. + * The allotted data may be less than allocated data if <size()> is passed + * an argument less than <capacity()>. + */ char *mark (void) const; - // Return a pointer to 1 past the end of the allotted data in a message. - // The allotted data may be less than allocated data if <size()> is passed - // an argument less than <capacity()>. // = Message size is the total amount of space alloted. + /// Get the total amount of allotted space in the message. The amount of + /// allotted space may be less than allocated space. size_t size (void) const; - // Get the total amount of allotted space in the message. The amount of - // allotted space may be less than allocated space. + /// Set the total amount of space in the message. Returns 0 if + /// successful, else -1. int size (size_t length); - // Set the total amount of space in the message. Returns 0 if - // successful, else -1. + /// Get the total amount of allocated space. size_t capacity (void) const; - // Get the total amount of allocated space. + /** + * Return an exact "deep copy" of the message, i.e., create fresh + * new copies of all the Data_Blocks and continuations. + * Notice that Data_Blocks can act as "Prototypes", i.e. derived + * classes can override this method and create instances of + * themselves. + */ virtual ACE_Data_Block *clone (ACE_Message_Block::Message_Flags mask = 0) const; - // Return an exact "deep copy" of the message, i.e., create fresh - // new copies of all the Data_Blocks and continuations. - // Notice that Data_Blocks can act as "Prototypes", i.e. derived - // classes can override this method and create instances of - // themselves. + /** + * As clone above, but it does not copy the contents of the buffer, + * i.e., create a new Data_Block of the same dynamic type, with the + * same allocator, locking_strategy, and with the same amount of + * storage available but the buffer is unitialized. + */ virtual ACE_Data_Block *clone_nocopy (ACE_Message_Block::Message_Flags mask = 0) const; - // As clone above, but it does not copy the contents of the buffer, - // i.e., create a new Data_Block of the same dynamic type, with the - // same allocator, locking_strategy, and with the same amount of - // storage available but the buffer is unitialized. + /// Return a "shallow" copy that increments our reference count by 1. ACE_Data_Block *duplicate (void); - // Return a "shallow" copy that increments our reference count by 1. + /** + * Decrease the shared reference count by 1. If the reference count + * is > 0 then return this; else if reference count == 0 then delete + * <this> and <mb> and return 0. Behavior is undefined if reference + * count < 0. + */ ACE_Data_Block *release (ACE_Lock *lock = 0); - // Decrease the shared reference count by 1. If the reference count - // is > 0 then return this; else if reference count == 0 then delete - // <this> and <mb> and return 0. Behavior is undefined if reference - // count < 0. // = Message flag accessors and mutators. + /// Bitwise-or the <more_flags> into the existing message flags and + /// return the new value. ACE_Message_Block::Message_Flags set_flags (ACE_Message_Block::Message_Flags more_flags); - // Bitwise-or the <more_flags> into the existing message flags and - // return the new value. + /// Clear the message flag bits specified in <less_flags> and return + /// the new value. ACE_Message_Block::Message_Flags clr_flags (ACE_Message_Block::Message_Flags less_flags); - // Clear the message flag bits specified in <less_flags> and return - // the new value. + /// Get the current message flags. ACE_Message_Block::Message_Flags flags (void) const; - // Get the current message flags. + /// Obtain the allocator strategy. ACE_Allocator *allocator_strategy (void) const; - // Obtain the allocator strategy. // = The locking strategy prevents race conditions. + /// Get the locking strategy. + /// Set a new locking strategy and return the hold one. ACE_Lock *locking_strategy (void); - // Get the locking strategy. ACE_Lock *locking_strategy (ACE_Lock *); - // Set a new locking strategy and return the hold one. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Get the current reference count. int reference_count (void) const; - // Get the current reference count. + /// Get the allocator used to create this object ACE_Allocator *data_block_allocator (void) const; - // Get the allocator used to create this object protected: + /// Internal release implementation ACE_Data_Block *release_i (void); - // Internal release implementation + /** + * Decrease the reference count, but don't delete the object. + * Returns 0 if the object should be removed. + * If <lock> is equal to the locking strategy then we assume that + * the lock is beign held by the current thread; this is used to + * release all the data blocks in a chain while holding a single + * lock. + */ friend class ACE_Message_Block; ACE_Data_Block *release_no_delete (ACE_Lock *lock); - // Decrease the reference count, but don't delete the object. - // Returns 0 if the object should be removed. - // If <lock> is equal to the locking strategy then we assume that - // the lock is beign held by the current thread; this is used to - // release all the data blocks in a chain while holding a single - // lock. + /// Type of message. ACE_Message_Block::ACE_Message_Type type_; - // Type of message. + /// Current size of message block. size_t cur_size_; - // Current size of message block. + /// Total size of buffer. size_t max_size_; - // Total size of buffer. + /// Misc flags (e.g., DONT_DELETE and USER_FLAGS). ACE_Message_Block::Message_Flags flags_; - // Misc flags (e.g., DONT_DELETE and USER_FLAGS). + /// Pointer to beginning of message payload. char *base_; - // Pointer to beginning of message payload. // = Strategies. + /** + * Pointer to the allocator defined for this <ACE_Data_Block>. Note + * that this pointer is shared by all owners of this + * <ACE_Data_Block>. + */ ACE_Allocator *allocator_strategy_; - // Pointer to the allocator defined for this <ACE_Data_Block>. Note - // that this pointer is shared by all owners of this - // <ACE_Data_Block>. + /** + * Pointer to the locking strategy defined for this + * <ACE_Data_Block>. This is used to protect regions of code that + * access shared <ACE_Data_Block> state. Note that this lock is + * shared by all owners of the <ACE_Data_Block>'s data. + */ ACE_Lock *locking_strategy_; - // Pointer to the locking strategy defined for this - // <ACE_Data_Block>. This is used to protect regions of code that - // access shared <ACE_Data_Block> state. Note that this lock is - // shared by all owners of the <ACE_Data_Block>'s data. + /** + * Reference count for this <ACE_Data_Block>, which is used to avoid + * deep copies (i.e., <clone>). Note that this pointer value is + * shared by all owners of the <Data_Block>'s data, i.e., all the + * <ACE_Message_Block>s. + */ int reference_count_; - // Reference count for this <ACE_Data_Block>, which is used to avoid - // deep copies (i.e., <clone>). Note that this pointer value is - // shared by all owners of the <Data_Block>'s data, i.e., all the - // <ACE_Message_Block>s. + /// The allocator use to destroy ourselves. ACE_Allocator *data_block_allocator_; - // The allocator use to destroy ourselves. private: // = Disallow these operations. @@ -664,25 +736,27 @@ private: ACE_Data_Block (const ACE_Data_Block &); }; +/** + * @class ACE_Dynamic_Message_Strategy + * + * @brief An abstract base class which provides dynamic priority + * evaluation methods for use by the <ACE_Dynamic_Message_Queue> + * class or any other class which needs to manage the priorities + * of a collection of <ACE_Message_Block>s dynamically. + * + * Methods for deadline and laxity based priority evaluation are + * provided. These methods assume a specific partitioning of + * the message priority number into a higher order dynamic bit + * field and a lower order static priority bit field. The + * default partitioning assumes an unsigned dynamic message + * priority field of 22 bits and an unsigned static message + * priority field of 10 bits. This corresponds to the initial + * values of the static class members. To provide a different + * partitioning, assign a different set of values to the static + * class memebers before using the static member functions. + */ class ACE_Export ACE_Dynamic_Message_Strategy { - // = TITLE - // An abstract base class which provides dynamic priority - // evaluation methods for use by the <ACE_Dynamic_Message_Queue> - // class or any other class which needs to manage the priorities - // of a collection of <ACE_Message_Block>s dynamically. - // - // = DESCRIPTION - // Methods for deadline and laxity based priority evaluation are - // provided. These methods assume a specific partitioning of - // the message priority number into a higher order dynamic bit - // field and a lower order static priority bit field. The - // default partitioning assumes an unsigned dynamic message - // priority field of 22 bits and an unsigned static message - // priority field of 10 bits. This corresponds to the initial - // values of the static class members. To provide a different - // partitioning, assign a different set of values to the static - // class memebers before using the static member functions. public: // = Message priority status @@ -692,146 +766,154 @@ public: enum Priority_Status { - PENDING = 0x01, // message can still make its deadline - LATE = 0x02, // message cannot make its deadline - BEYOND_LATE = 0x04, // message is so late its priority is undefined - ANY_STATUS = 0x07 // mask to match any priority status + /// message can still make its deadline + PENDING = 0x01, + /// message cannot make its deadline + LATE = 0x02, + /// message is so late its priority is undefined + BEYOND_LATE = 0x04, + /// mask to match any priority status + ANY_STATUS = 0x07 }; + /// ctor ACE_Dynamic_Message_Strategy (u_long static_bit_field_mask, u_long static_bit_field_shift, u_long dynamic_priority_max, u_long dynamic_priority_offset); - // ctor + /// virtual dtor virtual ~ACE_Dynamic_Message_Strategy (void); - // virtual dtor + /// Updates the message's priority and returns its priority status. Priority_Status priority_status (ACE_Message_Block &mb, const ACE_Time_Value &tv); - // Updates the message's priority and returns its priority status. + /// Get static bit field mask. u_long static_bit_field_mask (void); - // Get static bit field mask. + /// Set static bit field mask. void static_bit_field_mask (u_long); - // Set static bit field mask. + /// Get left shift value to make room for static bit field. u_long static_bit_field_shift (void); - // Get left shift value to make room for static bit field. + /// Set left shift value to make room for static bit field. void static_bit_field_shift (u_long); - // Set left shift value to make room for static bit field. + /// Get maximum supported priority value. u_long dynamic_priority_max (void); - // Get maximum supported priority value. + /// Set maximum supported priority value. void dynamic_priority_max (u_long); - // Set maximum supported priority value. + /// Get offset to boundary between signed range and unsigned range. u_long dynamic_priority_offset (void); - // Get offset to boundary between signed range and unsigned range. + /// Set offset to boundary between signed range and unsigned range. void dynamic_priority_offset (u_long); - // Set offset to boundary between signed range and unsigned range. + /// Dump the state of the strategy. virtual void dump (void) const; - // Dump the state of the strategy. protected: + /// Hook method for dynamic priority conversion. virtual void convert_priority (ACE_Time_Value &priority, const ACE_Message_Block &mb) = 0; - // Hook method for dynamic priority conversion. + /// This is a bit mask with all ones in the static bit field. u_long static_bit_field_mask_; - // This is a bit mask with all ones in the static bit field. + /** + * This is a left shift value to make room for static bit field: + * this value should be the logarithm base 2 of + * (static_bit_field_mask_ + 1). + */ u_long static_bit_field_shift_; - // This is a left shift value to make room for static bit field: - // this value should be the logarithm base 2 of - // (static_bit_field_mask_ + 1). + /// Maximum supported priority value. u_long dynamic_priority_max_; - // Maximum supported priority value. + /// Offset to boundary between signed range and unsigned range. u_long dynamic_priority_offset_; - // Offset to boundary between signed range and unsigned range. + /// Maximum late time value that can be represented. ACE_Time_Value max_late_; - // Maximum late time value that can be represented. + /// Minimum pending time value that can be represented. ACE_Time_Value min_pending_; - // Minimum pending time value that can be represented. + /// Time value by which to shift pending priority. ACE_Time_Value pending_shift_; - // Time value by which to shift pending priority. }; +/** + * @class ACE_Deadline_Message_Strategy + * + * @brief Deadline based message priority strategy. + * + * Assigns dynamic message priority according to time to deadline. The + * message priority is divided into high and low order bit fields. The + * high order bit field is used for dynamic message priority, which is + * updated whenever the convert_priority (...) method is called. The + * low order bit field is used for static message priority and is left + * unchanged. The partitioning of the priority value into high and low + * order bit fields is done according to the arguments passed to the + * strategy object's constructor. + */ class ACE_Export ACE_Deadline_Message_Strategy : public ACE_Dynamic_Message_Strategy { - // = TITLE - // Deadline based message priority strategy. - // - // = DESCRIPTION - // Assigns dynamic message priority according to time to deadline. The - // message priority is divided into high and low order bit fields. The - // high order bit field is used for dynamic message priority, which is - // updated whenever the convert_priority (...) method is called. The - // low order bit field is used for static message priority and is left - // unchanged. The partitioning of the priority value into high and low - // order bit fields is done according to the arguments passed to the - // strategy object's constructor. - // public: + /// Ctor, with all arguments defaulted. ACE_Deadline_Message_Strategy (u_long static_bit_field_mask = 0x3FFUL, // 2^(10) - 1 u_long static_bit_field_shift = 10, // 10 low order bits u_long dynamic_priority_max = 0x3FFFFFUL, // 2^(22)-1 u_long dynamic_priority_offset = 0x200000UL); // 2^(22-1) - // Ctor, with all arguments defaulted. + /// Virtual dtor. virtual ~ACE_Deadline_Message_Strategy (void); - // Virtual dtor. + /// Dynamic priority conversion function based on time to deadline. virtual void convert_priority (ACE_Time_Value &priority, const ACE_Message_Block &mb); - // Dynamic priority conversion function based on time to deadline. + /// Dump the state of the strategy. virtual void dump (void) const; - // Dump the state of the strategy. }; +/** + * @class ACE_Laxity_Message_Strategy + * + * @brief Laxity based message priority strategy. + * + * Assigns dynamic message priority according to laxity (time to + * deadline minus worst case execution time). The message priority is + * divided into high and low order bit fields. The high order + * bit field is used for dynamic message priority, which is + * updated whenever the convert_priority (...) method is called. The + * low order bit field is used for static message priority and is left + * unchanged. The partitioning of the priority value into high and low + * order bit fields is done according to the arguments passed to the + * strategy object's constructor. + */ class ACE_Export ACE_Laxity_Message_Strategy : public ACE_Dynamic_Message_Strategy { - // = TITLE - // Laxity based message priority strategy. - // - // = DESCRIPTION - // Assigns dynamic message priority according to laxity (time to - // deadline minus worst case execution time). The message priority is - // divided into high and low order bit fields. The high order - // bit field is used for dynamic message priority, which is - // updated whenever the convert_priority (...) method is called. The - // low order bit field is used for static message priority and is left - // unchanged. The partitioning of the priority value into high and low - // order bit fields is done according to the arguments passed to the - // strategy object's constructor. - // public: + /// Ctor, with all arguments defaulted. ACE_Laxity_Message_Strategy (u_long static_bit_field_mask = 0x3FFUL, // 2^(10) - 1 u_long static_bit_field_shift = 10, // 10 low order bits u_long dynamic_priority_max = 0x3FFFFFUL, // 2^(22)-1 u_long dynamic_priority_offset = 0x200000UL); // 2^(22-1) - // Ctor, with all arguments defaulted. + /// virtual dtor. virtual ~ACE_Laxity_Message_Strategy (void); - // virtual dtor. + /// Dynamic priority conversion function based on laxity. virtual void convert_priority (ACE_Time_Value &priority, const ACE_Message_Block &mb); - // Dynamic priority conversion function based on laxity. + /// Dump the state of the strategy. virtual void dump (void) const; - // Dump the state of the strategy. }; #if defined (__ACE_INLINE__) diff --git a/ace/Message_Block_T.h b/ace/Message_Block_T.h index 1aee946e693..93dc5505b8d 100644 --- a/ace/Message_Block_T.h +++ b/ace/Message_Block_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Message_Block_T.h -// -// = AUTHOR -// Doug Schmidt & Carlos O'Ryan -// -// ============================================================================ +//============================================================================= +/** + * @file Message_Block_T.h + * + * $Id$ + * + * @author Doug Schmidt & Carlos O'Ryan + */ +//============================================================================= + #ifndef ACE_MESSAGE_BLOCK_T_H #define ACE_MESSAGE_BLOCK_T_H @@ -24,43 +21,46 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Locked_Data_Block + * + * @brief A Data_Block with a concrete locking strategy. + * + * Data_Blocks can be parametric on the kind of lock they use; in + * many cases the lifetime of the lock is tied to the lifetime of + * the Data_Block itself. But since Data_Blocks are reference + * counted it is hard for users to control the lock lifetime. + * This class is parametric over the kind of lock used. + */ template <class ACE_LOCK> class ACE_Locked_Data_Block : public ACE_Data_Block { - // = TITLE - // A Data_Block with a concrete locking strategy. - // - // = DESCRIPTION - // Data_Blocks can be parametric on the kind of lock they use; in - // many cases the lifetime of the lock is tied to the lifetime of - // the Data_Block itself. But since Data_Blocks are reference - // counted it is hard for users to control the lock lifetime. - // This class is parametric over the kind of lock used. - // public: // = Initialization and termination methods. + /// Default "do-nothing" constructor. ACE_Locked_Data_Block (void); - // Default "do-nothing" constructor. + /// Initialize. ACE_Locked_Data_Block (size_t size, ACE_Message_Block::ACE_Message_Type msg_type, const char *msg_data, ACE_Allocator *allocator_strategy, ACE_Message_Block::Message_Flags flags, ACE_Allocator *data_block_allocator); - // Initialize. + /// Delete all the resources held in the message. virtual ~ACE_Locked_Data_Block (void); - // Delete all the resources held in the message. + /** + * Return an exact "deep copy" of the message, the dynamic type is + * ACE_Locked_Data_Block<> + * See the documentation in Message_Block.h for details. + */ virtual ACE_Data_Block *clone_nocopy (ACE_Message_Block::Message_Flags mask = 0) const; - // Return an exact "deep copy" of the message, the dynamic type is - // ACE_Locked_Data_Block<> - // See the documentation in Message_Block.h for details. private: + /// The lock ACE_LOCK lock_; - // The lock // = Disallow these operations. ACE_UNIMPLEMENTED_FUNC (ACE_Locked_Data_Block<ACE_LOCK> &operator= (const ACE_Locked_Data_Block<ACE_LOCK> &)) diff --git a/ace/Message_Queue.h b/ace/Message_Queue.h index ee3ee983a11..92ff36a3b58 100644 --- a/ace/Message_Queue.h +++ b/ace/Message_Queue.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Message_Queue.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Message_Queue.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_MESSAGE_QUEUE_H #define ACE_MESSAGE_QUEUE_H @@ -31,36 +28,38 @@ class ACE_Notification_Strategy; template <ACE_SYNCH_DECL> class ACE_Message_Queue_Iterator; template <ACE_SYNCH_DECL> class ACE_Message_Queue_Reverse_Iterator; +/** + * @class ACE_Message_Queue_Base + * + * @brief Workaround HP/C++ compiler bug with enums in templates. + * + * The ever lamest HP/C++ compiler seems to fail if enums are + * defined inside a template, hence we have to move them into a + * base class. + */ class ACE_Export ACE_Message_Queue_Base { - // = TITLE - // Workaround HP/C++ compiler bug with enums in templates. - // - // = DESCRIPTION - // The ever lamest HP/C++ compiler seems to fail if enums are - // defined inside a template, hence we have to move them into a - // base class. public: // = Default high and low water marks. enum { + /// Default high watermark (16 K). DEFAULT_HWM = 16 * 1024, - // Default high watermark (16 K). + /// Default low watermark (same as high water mark). DEFAULT_LWM = 16 * 1024, - // Default low watermark (same as high water mark). + /// Message queue was active before <activate> or <deactivate>. WAS_ACTIVE = 1, - // Message queue was active before <activate> or <deactivate>. + /// Message queue was inactive before <activate> or <deactivate>. WAS_INACTIVE = 2 - // Message queue was inactive before <activate> or <deactivate>. }; ACE_Message_Queue_Base (void); + /// Close down the message queue and release all resources. virtual int close (void) = 0; - // Close down the message queue and release all resources. + /// Close down the message queue and release all resources. virtual ~ACE_Message_Queue_Base (void); - // Close down the message queue and release all resources. // = Enqueue and dequeue methods. @@ -72,81 +71,95 @@ public: // which case <errno> == <EINTR>, or if the time specified in // timeout elapses (in which case <errno> == <EWOULDBLOCK>). + /** + * Retrieve the first <ACE_Message_Block> without removing it. Note + * that <timeout> uses <{absolute}> time rather than <{relative}> + * time. If the <timeout> elapses without receiving a message -1 is + * returned and <errno> is set to <EWOULDBLOCK>. If the queue is + * deactivated -1 is returned and <errno> is set to <ESHUTDOWN>. + * Otherwise, returns -1 on failure, else the number of items still + * on the queue. + */ virtual int peek_dequeue_head (ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0) = 0; - // Retrieve the first <ACE_Message_Block> without removing it. Note - // that <timeout> uses <{absolute}> time rather than <{relative}> - // time. If the <timeout> elapses without receiving a message -1 is - // returned and <errno> is set to <EWOULDBLOCK>. If the queue is - // deactivated -1 is returned and <errno> is set to <ESHUTDOWN>. - // Otherwise, returns -1 on failure, else the number of items still - // on the queue. + /** + * Enqueue a <ACE_Message_Block *> into the tail of the queue. + * Returns number of items in queue if the call succeeds or -1 + * otherwise. + * Enqueue a <ACE_Message_Block *> into the tail of the queue. + * Returns number of items in queue if the call succeeds or -1 + * otherwise. + */ virtual int enqueue_tail (ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0) = 0; - // Enqueue a <ACE_Message_Block *> into the tail of the queue. - // Returns number of items in queue if the call succeeds or -1 - // otherwise. virtual int enqueue (ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0) = 0; - // Enqueue a <ACE_Message_Block *> into the tail of the queue. - // Returns number of items in queue if the call succeeds or -1 - // otherwise. + /** + * Dequeue and return the <ACE_Message_Block *> at the head of the + * queue. Returns number of items in queue if the call succeeds or + * -1 otherwise. + * Dequeue and return the <ACE_Message_Block *> at the head of the + * queue. Returns number of items in queue if the call succeeds or + * -1 otherwise. + */ virtual int dequeue_head (ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0) = 0; - // Dequeue and return the <ACE_Message_Block *> at the head of the - // queue. Returns number of items in queue if the call succeeds or - // -1 otherwise. virtual int dequeue (ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0) = 0; - // Dequeue and return the <ACE_Message_Block *> at the head of the - // queue. Returns number of items in queue if the call succeeds or - // -1 otherwise. // = Check if queue is full/empty. + /// True if queue is full, else false. + /// True if queue is empty, else false. virtual int is_full (void) = 0; - // True if queue is full, else false. virtual int is_empty (void) = 0; - // True if queue is empty, else false. // = Queue statistic methods. + /** + * Number of total bytes on the queue, i.e., sum of the message + * block sizes. + * Number of total length on the queue, i.e., sum of the message + * block lengths. + * Number of total messages on the queue. + */ virtual size_t message_bytes (void) = 0; - // Number of total bytes on the queue, i.e., sum of the message - // block sizes. virtual size_t message_length (void) = 0; - // Number of total length on the queue, i.e., sum of the message - // block lengths. virtual size_t message_count (void) = 0; - // Number of total messages on the queue. // = Manual changes to these stats (used when queued message blocks // change size or lengths). + /** + * New value of the number of total bytes on the queue, i.e., sum of + * the message block sizes. + * New value of the number of total length on the queue, i.e., sum + * of the message block lengths. + */ virtual void message_bytes (size_t new_size) = 0; - // New value of the number of total bytes on the queue, i.e., sum of - // the message block sizes. virtual void message_length (size_t new_length) = 0; - // New value of the number of total length on the queue, i.e., sum - // of the message block lengths. // = Activation control methods. + /** + * Deactivate the queue and wakeup all threads waiting on the queue + * so they can continue. No messages are removed from the queue, + * however. Any other operations called until the queue is + * activated again will immediately return -1 with <errno> == + * ESHUTDOWN. Returns WAS_INACTIVE if queue was inactive before the + * call and WAS_ACTIVE if queue was active before the call. + */ virtual int deactivate (void) = 0; - // Deactivate the queue and wakeup all threads waiting on the queue - // so they can continue. No messages are removed from the queue, - // however. Any other operations called until the queue is - // activated again will immediately return -1 with <errno> == - // ESHUTDOWN. Returns WAS_INACTIVE if queue was inactive before the - // call and WAS_ACTIVE if queue was active before the call. + /** + * Reactivate the queue so that threads can enqueue and dequeue + * messages again. Returns WAS_INACTIVE if queue was inactive + * before the call and WAS_ACTIVE if queue was active before the + * call. + */ virtual int activate (void) = 0; - // Reactivate the queue so that threads can enqueue and dequeue - // messages again. Returns WAS_INACTIVE if queue was inactive - // before the call and WAS_ACTIVE if queue was active before the - // call. + /// Returns true if <deactivated_> is enabled. virtual int deactivated (void) = 0; - // Returns true if <deactivated_> is enabled. // = Get/set the notification strategy for the <Message_Queue> virtual ACE_Notification_Strategy *notification_strategy (void) = 0; @@ -154,11 +167,11 @@ public: // = Notification hook. + /// Dump the state of an object. virtual void dump (void) const = 0; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: // = Disallow these operations. @@ -175,38 +188,39 @@ typedef ACE_Message_Queue<ACE_SYNCH> ACE_DEFAULT_MESSAGE_QUEUE_TYPE; #if defined (VXWORKS) # include /**/ <msgQLib.h> +/** + * @class ACE_Message_Queue_Vx + * + * @brief Wrapper for VxWorks message queues. + * + * Specialization of ACE_Message_Queue to simply wrap VxWorks + * MsgQ. It does not use any synchronization, because it relies + * on the native MsgQ implementation to take care of that. The + * only system calls that it uses are VxWorks msgQLib calls, so + * it is suitable for use in interrupt service routines. + * NOTE: *Many* ACE_Message_Queue features are not supported with + * this specialization, including: + * * The two size arguments to the constructor and <open> are + * interpreted differently. The first is interpreted as the + * maximum number of bytes in a message. The second is + * interpreted as the maximum number of messages that can be + * queued. + * * <dequeue_head> *requires* that the ACE_Message_Block + * pointer argument point to an ACE_Message_Block that was + * allocated by the caller. It must be big enough to support + * the received message, without using continutation. The + * pointer argument is not modified. + * * Message priority. MSG_Q_FIFO is hard-coded. + * * enqueue method timeouts. + * * <peek_dequeue_head>. + * * <ACE_Message_Queue_Iterators>. + * * The ability to change low and high water marks after creation. + * * <Message_Block> chains. The continuation field of <ACE_Message_Block> + * * is ignored; only the first block of a fragment chain is + * * recognized. + */ class ACE_Message_Queue_Vx : public ACE_Message_Queue<ACE_NULL_SYNCH> { - // = TITLE - // Wrapper for VxWorks message queues. - // - // = DESCRIPTION - // Specialization of ACE_Message_Queue to simply wrap VxWorks - // MsgQ. It does not use any synchronization, because it relies - // on the native MsgQ implementation to take care of that. The - // only system calls that it uses are VxWorks msgQLib calls, so - // it is suitable for use in interrupt service routines. - // - // NOTE: *Many* ACE_Message_Queue features are not supported with - // this specialization, including: - // * The two size arguments to the constructor and <open> are - // interpreted differently. The first is interpreted as the - // maximum number of bytes in a message. The second is - // interpreted as the maximum number of messages that can be - // queued. - // * <dequeue_head> *requires* that the ACE_Message_Block - // pointer argument point to an ACE_Message_Block that was - // allocated by the caller. It must be big enough to support - // the received message, without using continutation. The - // pointer argument is not modified. - // * Message priority. MSG_Q_FIFO is hard-coded. - // * enqueue method timeouts. - // * <peek_dequeue_head>. - // * <ACE_Message_Queue_Iterators>. - // * The ability to change low and high water marks after creation. - // * <Message_Block> chains. The continuation field of <ACE_Message_Block> - // * is ignored; only the first block of a fragment chain is - // * recognized. public: // = Initialization and termination methods. ACE_Message_Queue_Vx (size_t max_messages, @@ -214,110 +228,116 @@ public: ACE_Notification_Strategy * = 0); // Create a message queue with all the defaults. + /// Create a message queue with all the defaults. virtual int open (size_t max_messages, size_t max_message_length, ACE_Notification_Strategy * = 0); - // Create a message queue with all the defaults. + /// Close down the message queue and release all resources. virtual int close (void); - // Close down the message queue and release all resources. + /// Close down the message queue and release all resources. virtual ~ACE_Message_Queue_Vx (void); - // Close down the message queue and release all resources. // = Queue statistic methods. + /** + * Number of total bytes on the queue, i.e., sum of the message + * block sizes. + * Number of total length on the queue, i.e., sum of the message + * block lengths. + * Number of total messages on the queue. + */ virtual size_t message_bytes (void); - // Number of total bytes on the queue, i.e., sum of the message - // block sizes. virtual size_t message_length (void); - // Number of total length on the queue, i.e., sum of the message - // block lengths. virtual size_t message_count (void); - // Number of total messages on the queue. // = Manual changes to these stats (used when queued message blocks // change size or lengths). + /** + * New value of the number of total bytes on the queue, i.e., sum of + * the message block sizes. + * New value of the number of total length on the queue, i.e., sum + * of the message block lengths. + */ virtual void message_bytes (size_t new_size); - // New value of the number of total bytes on the queue, i.e., sum of - // the message block sizes. virtual void message_length (size_t new_length); - // New value of the number of total length on the queue, i.e., sum - // of the message block lengths. // = Flow control routines + /** + * Get high watermark. + * Set high watermark. + * Get low watermark. + * Set low watermark. + */ virtual size_t high_water_mark (void); - // Get high watermark. virtual void high_water_mark (size_t hwm); - // Set high watermark. virtual size_t low_water_mark (void); - // Get low watermark. virtual void low_water_mark (size_t lwm); - // Set low watermark. // = Activation control methods. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Enqueue an <ACE_Message_Block *> in accordance with its priority. virtual int enqueue_i (ACE_Message_Block *new_item); - // Enqueue an <ACE_Message_Block *> in accordance with its priority. + /// Enqueue an <ACE_Message_Block *> at the end of the queue. virtual int enqueue_tail_i (ACE_Message_Block *new_item); - // Enqueue an <ACE_Message_Block *> at the end of the queue. + /// Enqueue an <ACE_Message_Block *> at the head of the queue. virtual int enqueue_head_i (ACE_Message_Block *new_item); - // Enqueue an <ACE_Message_Block *> at the head of the queue. + /// Dequeue and return the <ACE_Message_Block *> at the head of the + /// queue. virtual int dequeue_head_i (ACE_Message_Block *&first_item); - // Dequeue and return the <ACE_Message_Block *> at the head of the - // queue. // = Check the boundary conditions (assumes locks are held). + /// True if queue is full, else false. + /// True if queue is empty, else false. virtual int is_full_i (void); - // True if queue is full, else false. virtual int is_empty_i (void); - // True if queue is empty, else false. // = Implementation of public <activate>/<deactivate> methods above. // These methods assume locks are held. + /// Deactivate the queue. + /// Activate the queue. virtual int deactivate_i (void); - // Deactivate the queue. virtual int activate_i (void); - // Activate the queue. // = Helper methods to factor out common #ifdef code. + /// Wait for the queue to become non-full. virtual int wait_not_full_cond (ACE_Guard<ACE_Null_Mutex> &mon, ACE_Time_Value *tv); - // Wait for the queue to become non-full. + /// Wait for the queue to become non-empty. virtual int wait_not_empty_cond (ACE_Guard<ACE_Null_Mutex> &mon, ACE_Time_Value *tv); - // Wait for the queue to become non-empty. + /// Inform any threads waiting to enqueue that they can procede. virtual int signal_enqueue_waiters (void); - // Inform any threads waiting to enqueue that they can procede. + /// Inform any threads waiting to dequeue that they can procede. virtual int signal_dequeue_waiters (void); - // Inform any threads waiting to dequeue that they can procede. + /// Access the underlying msgQ. MSG_Q_ID msgq (void); - // Access the underlying msgQ. private: + /// Maximum number of messages that can be queued. int max_messages_; - // Maximum number of messages that can be queued. + /// Maximum message size, in bytes. int max_message_length_; - // Maximum message size, in bytes. + /// Native message queue options. int options_; - // Native message queue options. // = Disallow these operations. ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Message_Queue_Vx &)) @@ -330,108 +350,125 @@ private: #endif /* VXWORKS */ #if defined (ACE_WIN32) && (ACE_HAS_WINNT4 != 0) +/** + * @class ACE_Message_Queue_NT + * + * @brief Message Queue implementation using IO completion port on NT. + * + * Implementation of a strip-downed ACE_Message_Queue using NT's + * IO completion port mechanism. + * NOTE: *Many* ACE_Message_Queue features are not supported with + * this implementation, including: + * * <open> method have different signatures. + * * <dequeue_head> *requires* that the <ACE_Message_Block> + * pointer argument point to an <ACE_Message_Block> that was + * allocated by the caller. + * * <peek_dequeue_head>. + * * <ACE_Message_Queue_Iterators>. + * * No flow control. + */ class ACE_Export ACE_Message_Queue_NT : public ACE_Message_Queue_Base { - // = TITLE - // Message Queue implementation using IO completion port on NT. - // - // = DESCRIPTION - // Implementation of a strip-downed ACE_Message_Queue using NT's - // IO completion port mechanism. - // - // NOTE: *Many* ACE_Message_Queue features are not supported with - // this implementation, including: - // * <open> method have different signatures. - // * <dequeue_head> *requires* that the <ACE_Message_Block> - // pointer argument point to an <ACE_Message_Block> that was - // allocated by the caller. - // * <peek_dequeue_head>. - // * <ACE_Message_Queue_Iterators>. - // * No flow control. public: // = Initialization and termination methods. ACE_Message_Queue_NT (size_t max_threads = ACE_Message_Queue_Base::DEFAULT_HWM); + /** + * Initialize the Message Queue by creating a new NT I/O completion + * port. The first arguemnt specifies the number of threads + * released by the MQ that are allowed to run concurrently. Return + * 0 when succeeds, -1 otherwise. + */ virtual int open (size_t max_threads = ACE_Message_Queue_Base::DEFAULT_HWM); - // Initialize the Message Queue by creating a new NT I/O completion - // port. The first arguemnt specifies the number of threads - // released by the MQ that are allowed to run concurrently. Return - // 0 when succeeds, -1 otherwise. + /// Close down the underlying I/O completion port. You need to + /// re-open the MQ after this function is executed. virtual int close (void); - // Close down the underlying I/O completion port. You need to - // re-open the MQ after this function is executed. + /// Close down the message queue and release all resources. virtual ~ACE_Message_Queue_NT (void); - // Close down the message queue and release all resources. // = Enqueue and dequeue methods. + /** + * Enqueue an <ACE_Message_Block *> at the end of the queue. + * Returns -1 on failure, else the number of items still on the + * queue. + */ virtual int enqueue_tail (ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0); virtual int enqueue (ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0); - // Enqueue an <ACE_Message_Block *> at the end of the queue. - // Returns -1 on failure, else the number of items still on the - // queue. + /** + * Dequeue and return the <ACE_Message_Block *> at the head of the + * queue. Returns -1 on failure, else the number of items still on + * the queue. + */ virtual int dequeue_head (ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0); virtual int dequeue (ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0); - // Dequeue and return the <ACE_Message_Block *> at the head of the - // queue. Returns -1 on failure, else the number of items still on - // the queue. // = Check if queue is full/empty. + /** + * Always return false. + * True if queue is empty, else false. Notice the return value is + * only transient. + */ virtual int is_full (void); - // Always return false. virtual int is_empty (void); - // True if queue is empty, else false. Notice the return value is - // only transient. // = Queue statistic methods (transient.) + /** + * Number of total bytes on the queue, i.e., sum of the message + * block sizes. + * Number of total length on the queue, i.e., sum of the message + * block lengths. + * Number of total messages on the queue. + */ virtual size_t message_bytes (void); - // Number of total bytes on the queue, i.e., sum of the message - // block sizes. virtual size_t message_length (void); - // Number of total length on the queue, i.e., sum of the message - // block lengths. virtual size_t message_count (void); - // Number of total messages on the queue. // = Manual changes to these stats (used when queued message blocks // change size or lengths). + /** + * New value of the number of total bytes on the queue, i.e., sum of + * the message block sizes. + * New value of the number of total length on the queue, i.e., sum + * of the message block lengths. + */ virtual void message_bytes (size_t new_size); - // New value of the number of total bytes on the queue, i.e., sum of - // the message block sizes. virtual void message_length (size_t new_length); - // New value of the number of total length on the queue, i.e., sum - // of the message block lengths. + /// Get the max concurrent thread number. virtual size_t max_threads (void); - // Get the max concurrent thread number. // = Activation control methods. + /** + * Deactivate the queue and wakeup all threads waiting on the queue + * so they can continue. Messages already in the queue get removed. + * If there are more messages in the queue than there are threads + * waiting on the queue, the left over messages will not be removed. + * Any other enqueue/dequeue operations called until the queue is + * activated again will immediately return -1 with <errno> == + * ESHUTDOWN. Returns WAS_INACTIVE if queue was inactive before the + * call and WAS_ACTIVE if queue was active before the call. + */ virtual int deactivate (void); - // Deactivate the queue and wakeup all threads waiting on the queue - // so they can continue. Messages already in the queue get removed. - // If there are more messages in the queue than there are threads - // waiting on the queue, the left over messages will not be removed. - // Any other enqueue/dequeue operations called until the queue is - // activated again will immediately return -1 with <errno> == - // ESHUTDOWN. Returns WAS_INACTIVE if queue was inactive before the - // call and WAS_ACTIVE if queue was active before the call. + /** + * Reactivate the queue so that threads can enqueue and dequeue + * messages again. Returns WAS_INACTIVE if queue was inactive + * before the call and WAS_ACTIVE if queue was active before the + * call. + */ virtual int activate (void); - // Reactivate the queue so that threads can enqueue and dequeue - // messages again. Returns WAS_INACTIVE if queue was inactive - // before the call and WAS_ACTIVE if queue was active before the - // call. + /// Returns true if <deactivated_> is enabled. virtual int deactivated (void); - // Returns true if <deactivated_> is enabled. // = Not currently implemented... int peek_dequeue_head (ACE_Message_Block *&first_item, @@ -441,43 +478,45 @@ public: // = Notification hook. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Get the handle to the underlying completion port. virtual ACE_HANDLE completion_port (void); - // Get the handle to the underlying completion port. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: // = Internal states. + /// Maximum threads that can be released (and run) concurrently. size_t max_cthrs_; - // Maximum threads that can be released (and run) concurrently. + /// Current number of threads waiting to dequeue messages. size_t cur_thrs_; - // Current number of threads waiting to dequeue messages. + /// Current number of bytes in queue. size_t cur_bytes_; - // Current number of bytes in queue. + /// Current length of messages in queue. size_t cur_length_; - // Current length of messages in queue. + /// Current number of messages in the queue. size_t cur_count_; - // Current number of messages in the queue. + /** + * Synchronizer. This should really be an ACE_Recursive_Thread_Mutex + * but since this class is only supported on NT, it's okay to use + * ACE_Thread_Mutex here. + */ ACE_Thread_Mutex lock_; - // Synchronizer. This should really be an ACE_Recursive_Thread_Mutex - // but since this class is only supported on NT, it's okay to use - // ACE_Thread_Mutex here. + /// Indicates that the queue is inactive. int deactivated_; - // Indicates that the queue is inactive. + /// Underlying NT IoCompletionPort. ACE_HANDLE completion_port_; - // Underlying NT IoCompletionPort. // = Disallow these operations. ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Message_Queue_NT &)) diff --git a/ace/Message_Queue_T.h b/ace/Message_Queue_T.h index 51db6122ba6..f67a4c9fcb5 100644 --- a/ace/Message_Queue_T.h +++ b/ace/Message_Queue_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Message_Queue_T.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Message_Queue_T.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_MESSAGE_QUEUE_T_H #define ACE_MESSAGE_QUEUE_T_H @@ -32,19 +29,21 @@ class ACE_Message_Queue_Vx; class ACE_Message_Queue_NT; #endif /* ACE_WIN32 && ACE_HAS_WINNT4 != 0 */ +/** + * @class ACE_Message_Queue + * + * @brief A threaded message queueing facility, modeled after the + * queueing facilities in System V STREAMs. + * + * An <ACE_Message_Queue> is the central queueing facility for + * messages in the ASX framework. If <ACE_SYNCH_DECL> is + * <ACE_MT_SYNCH> then all operations are thread-safe. + * Otherwise, if it's <ACE_NULL_SYNCH> then there's no locking + * overhead. + */ template <ACE_SYNCH_DECL> class ACE_Message_Queue : public ACE_Message_Queue_Base { - // = TITLE - // A threaded message queueing facility, modeled after the - // queueing facilities in System V STREAMs. - // - // = DESCRIPTION - // An <ACE_Message_Queue> is the central queueing facility for - // messages in the ASX framework. If <ACE_SYNCH_DECL> is - // <ACE_MT_SYNCH> then all operations are thread-safe. - // Otherwise, if it's <ACE_NULL_SYNCH> then there's no locking - // overhead. public: friend class ACE_Message_Queue_Iterator<ACE_SYNCH_USE>; friend class ACE_Message_Queue_Reverse_Iterator<ACE_SYNCH_USE>; @@ -56,45 +55,49 @@ public: REVERSE_ITERATOR; // = Initialization and termination methods. + /** + * Initialize an <ACE_Message_Queue>. The <high_water_mark> + * determines how many bytes can be stored in a queue before it's + * considered "full." Supplier threads must block until the queue + * is no longer full. The <low_water_mark> determines how many + * bytes must be in the queue before supplier threads are allowed to + * enqueue additional <ACE_Message_Block>s. By default, the + * <high_water_mark> equals the <low_water_mark>, which means that + * suppliers will be able to enqueue new messages as soon as a + * consumer removes any message from the queue. Making the + * <low_water_mark> smaller than the <high_water_mark> forces + * consumers to drain more messages from the queue before suppliers + * can enqueue new messages, which can minimize the "silly window + * syndrome." + */ ACE_Message_Queue (size_t high_water_mark = ACE_Message_Queue_Base::DEFAULT_HWM, size_t low_water_mark = ACE_Message_Queue_Base::DEFAULT_LWM, ACE_Notification_Strategy * = 0); - // Initialize an <ACE_Message_Queue>. The <high_water_mark> - // determines how many bytes can be stored in a queue before it's - // considered "full." Supplier threads must block until the queue - // is no longer full. The <low_water_mark> determines how many - // bytes must be in the queue before supplier threads are allowed to - // enqueue additional <ACE_Message_Block>s. By default, the - // <high_water_mark> equals the <low_water_mark>, which means that - // suppliers will be able to enqueue new messages as soon as a - // consumer removes any message from the queue. Making the - // <low_water_mark> smaller than the <high_water_mark> forces - // consumers to drain more messages from the queue before suppliers - // can enqueue new messages, which can minimize the "silly window - // syndrome." + /** + * Initialize an <ACE_Message_Queue>. The <high_water_mark> + * determines how many bytes can be stored in a queue before it's + * considered "full." Supplier threads must block until the queue + * is no longer full. The <low_water_mark> determines how many + * bytes must be in the queue before supplier threads are allowed to + * enqueue additional <ACE_Message_Block>s. By default, the + * <high_water_mark> equals the <low_water_mark>, which means that + * suppliers will be able to enqueue new messages as soon as a + * consumer removes any message from the queue. Making the + * <low_water_mark> smaller than the <high_water_mark> forces + * consumers to drain more messages from the queue before suppliers + * can enqueue new messages, which can minimize the "silly window + * syndrome." + */ virtual int open (size_t hwm = ACE_Message_Queue_Base::DEFAULT_HWM, size_t lwm = ACE_Message_Queue_Base::DEFAULT_LWM, ACE_Notification_Strategy * = 0); - // Initialize an <ACE_Message_Queue>. The <high_water_mark> - // determines how many bytes can be stored in a queue before it's - // considered "full." Supplier threads must block until the queue - // is no longer full. The <low_water_mark> determines how many - // bytes must be in the queue before supplier threads are allowed to - // enqueue additional <ACE_Message_Block>s. By default, the - // <high_water_mark> equals the <low_water_mark>, which means that - // suppliers will be able to enqueue new messages as soon as a - // consumer removes any message from the queue. Making the - // <low_water_mark> smaller than the <high_water_mark> forces - // consumers to drain more messages from the queue before suppliers - // can enqueue new messages, which can minimize the "silly window - // syndrome." + /// Close down the message queue and release all resources. virtual int close (void); - // Close down the message queue and release all resources. + /// Close down the message queue and release all resources. virtual ~ACE_Message_Queue (void); - // Close down the message queue and release all resources. // = Enqueue and dequeue methods. @@ -105,152 +108,178 @@ public: // when a signal occurs, or if the time specified in timeout // elapses, (in which case errno = EWOULDBLOCK). + /** + * Retrieve the first <ACE_Message_Block> without removing it. Note + * that <timeout> uses <{absolute}> time rather than <{relative}> + * time. If the <timeout> elapses without receiving a message -1 is + * returned and <errno> is set to <EWOULDBLOCK>. If the queue is + * deactivated -1 is returned and <errno> is set to <ESHUTDOWN>. + * Otherwise, returns -1 on failure, else the number of items still + * on the queue. + */ virtual int peek_dequeue_head (ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0); - // Retrieve the first <ACE_Message_Block> without removing it. Note - // that <timeout> uses <{absolute}> time rather than <{relative}> - // time. If the <timeout> elapses without receiving a message -1 is - // returned and <errno> is set to <EWOULDBLOCK>. If the queue is - // deactivated -1 is returned and <errno> is set to <ESHUTDOWN>. - // Otherwise, returns -1 on failure, else the number of items still - // on the queue. + /** + * Enqueue an <ACE_Message_Block *> into the <Message_Queue> in + * accordance with its <msg_priority> (0 is lowest priority). FIFO + * order is maintained when messages of the same priority are + * inserted consecutively. Note that <timeout> uses <{absolute}> + * time rather than <{relative}> time. If the <timeout> elapses + * without receiving a message -1 is returned and <errno> is set to + * <EWOULDBLOCK>. If the queue is deactivated -1 is returned and + * <errno> is set to <ESHUTDOWN>. Otherwise, returns -1 on failure, + * else the number of items still on the queue. + */ virtual int enqueue_prio (ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0); - // Enqueue an <ACE_Message_Block *> into the <Message_Queue> in - // accordance with its <msg_priority> (0 is lowest priority). FIFO - // order is maintained when messages of the same priority are - // inserted consecutively. Note that <timeout> uses <{absolute}> - // time rather than <{relative}> time. If the <timeout> elapses - // without receiving a message -1 is returned and <errno> is set to - // <EWOULDBLOCK>. If the queue is deactivated -1 is returned and - // <errno> is set to <ESHUTDOWN>. Otherwise, returns -1 on failure, - // else the number of items still on the queue. + /** + * This is an alias for <enqueue_prio>. It's only here for + * backwards compatibility and will go away in a subsequent release. + * Please use <enqueue_prio> instead. Note that <timeout> uses + * <{absolute}> time rather than <{relative}> time. + */ virtual int enqueue (ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0); - // This is an alias for <enqueue_prio>. It's only here for - // backwards compatibility and will go away in a subsequent release. - // Please use <enqueue_prio> instead. Note that <timeout> uses - // <{absolute}> time rather than <{relative}> time. + /** + * Enqueue an <ACE_Message_Block *> at the end of the queue. Note + * that <timeout> uses <{absolute}> time rather than <{relative}> + * time. If the <timeout> elapses without receiving a message -1 is + * returned and <errno> is set to <EWOULDBLOCK>. If the queue is + * deactivated -1 is returned and <errno> is set to <ESHUTDOWN>. + * Otherwise, returns -1 on failure, else the number of items still + * on the queue. + */ virtual int enqueue_tail (ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0); - // Enqueue an <ACE_Message_Block *> at the end of the queue. Note - // that <timeout> uses <{absolute}> time rather than <{relative}> - // time. If the <timeout> elapses without receiving a message -1 is - // returned and <errno> is set to <EWOULDBLOCK>. If the queue is - // deactivated -1 is returned and <errno> is set to <ESHUTDOWN>. - // Otherwise, returns -1 on failure, else the number of items still - // on the queue. + /** + * Enqueue an <ACE_Message_Block *> at the head of the queue. Note + * that <timeout> uses <{absolute}> time rather than <{relative}> + * time. If the <timeout> elapses without receiving a message -1 is + * returned and <errno> is set to <EWOULDBLOCK>. If the queue is + * deactivated -1 is returned and <errno> is set to <ESHUTDOWN>. + * Otherwise, returns -1 on failure, else the number of items still + * on the queue. + */ virtual int enqueue_head (ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0); - // Enqueue an <ACE_Message_Block *> at the head of the queue. Note - // that <timeout> uses <{absolute}> time rather than <{relative}> - // time. If the <timeout> elapses without receiving a message -1 is - // returned and <errno> is set to <EWOULDBLOCK>. If the queue is - // deactivated -1 is returned and <errno> is set to <ESHUTDOWN>. - // Otherwise, returns -1 on failure, else the number of items still - // on the queue. + /// This method is an alias for the following <dequeue_head> method. virtual int dequeue (ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0); - // This method is an alias for the following <dequeue_head> method. + /** + * Dequeue and return the <ACE_Message_Block *> at the head of the + * queue. Note that <timeout> uses <{absolute}> time rather than + * <{relative}> time. If the <timeout> elapses without receiving a + * message -1 is returned and <errno> is set to <EWOULDBLOCK>. If + * the queue is deactivated -1 is returned and <errno> is set to + * <ESHUTDOWN>. Otherwise, returns -1 on failure, else the number + * of items still on the queue. + */ virtual int dequeue_head (ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0); - // Dequeue and return the <ACE_Message_Block *> at the head of the - // queue. Note that <timeout> uses <{absolute}> time rather than - // <{relative}> time. If the <timeout> elapses without receiving a - // message -1 is returned and <errno> is set to <EWOULDBLOCK>. If - // the queue is deactivated -1 is returned and <errno> is set to - // <ESHUTDOWN>. Otherwise, returns -1 on failure, else the number - // of items still on the queue. // = Check if queue is full/empty. + /// True if queue is full, else false. + /// True if queue is empty, else false. virtual int is_full (void); - // True if queue is full, else false. virtual int is_empty (void); - // True if queue is empty, else false. // = Queue statistic methods. + /** + * Number of total bytes on the queue, i.e., sum of the message + * block sizes. + * Number of total length on the queue, i.e., sum of the message + * block lengths. + * Number of total messages on the queue. + */ virtual size_t message_bytes (void); - // Number of total bytes on the queue, i.e., sum of the message - // block sizes. virtual size_t message_length (void); - // Number of total length on the queue, i.e., sum of the message - // block lengths. virtual size_t message_count (void); - // Number of total messages on the queue. // = Manual changes to these stats (used when queued message blocks // change size or lengths). + /** + * New value of the number of total bytes on the queue, i.e., sum of + * the message block sizes. + * New value of the number of total length on the queue, i.e., sum + * of the message block lengths. + */ virtual void message_bytes (size_t new_size); - // New value of the number of total bytes on the queue, i.e., sum of - // the message block sizes. virtual void message_length (size_t new_length); - // New value of the number of total length on the queue, i.e., sum - // of the message block lengths. // = Flow control methods. + /** + * Get high watermark. + * Set the high watermark, which determines how many bytes can be + * stored in a queue before it's considered "full." + */ virtual size_t high_water_mark (void); - // Get high watermark. virtual void high_water_mark (size_t hwm); - // Set the high watermark, which determines how many bytes can be - // stored in a queue before it's considered "full." + /** + * Get low watermark. + * Set the low watermark, which determines how many bytes must be in + * the queue before supplier threads are allowed to enqueue + * additional <ACE_Message_Block>s. + */ virtual size_t low_water_mark (void); - // Get low watermark. virtual void low_water_mark (size_t lwm); - // Set the low watermark, which determines how many bytes must be in - // the queue before supplier threads are allowed to enqueue - // additional <ACE_Message_Block>s. // = Activation control methods. + /** + * Deactivate the queue and wakeup all threads waiting on the queue + * so they can continue. No messages are removed from the queue, + * however. Any other operations called until the queue is + * activated again will immediately return -1 with <errno> == + * ESHUTDOWN. Returns WAS_INACTIVE if queue was inactive before the + * call and WAS_ACTIVE if queue was active before the call. + */ virtual int deactivate (void); - // Deactivate the queue and wakeup all threads waiting on the queue - // so they can continue. No messages are removed from the queue, - // however. Any other operations called until the queue is - // activated again will immediately return -1 with <errno> == - // ESHUTDOWN. Returns WAS_INACTIVE if queue was inactive before the - // call and WAS_ACTIVE if queue was active before the call. + /** + * Reactivate the queue so that threads can enqueue and dequeue + * messages again. Returns WAS_INACTIVE if queue was inactive + * before the call and WAS_ACTIVE if queue was active before the + * call. + */ virtual int activate (void); - // Reactivate the queue so that threads can enqueue and dequeue - // messages again. Returns WAS_INACTIVE if queue was inactive - // before the call and WAS_ACTIVE if queue was active before the - // call. + /// Returns true if <deactivated_> is enabled. virtual int deactivated (void); - // Returns true if <deactivated_> is enabled. // = Notification hook. + /** + * This hook is automatically invoked by <enqueue_head>, + * <enqueue_tail>, and <enqueue_prio> when a new item is inserted + * into the queue. Subclasses can override this method to perform + * specific notification strategies (e.g., signaling events for a + * <WFMO_Reactor>, notifying a <Reactor>, etc.). In a + * multi-threaded application with concurrent consumers, there is no + * guarantee that the queue will be still be non-empty by the time + * the notification occurs. + */ virtual int notify (void); - // This hook is automatically invoked by <enqueue_head>, - // <enqueue_tail>, and <enqueue_prio> when a new item is inserted - // into the queue. Subclasses can override this method to perform - // specific notification strategies (e.g., signaling events for a - // <WFMO_Reactor>, notifying a <Reactor>, etc.). In a - // multi-threaded application with concurrent consumers, there is no - // guarantee that the queue will be still be non-empty by the time - // the notification occurs. // = Get/set the notification strategy for the <Message_Queue> virtual ACE_Notification_Strategy *notification_strategy (void); virtual void notification_strategy (ACE_Notification_Strategy *s); + /// Returns a reference to the lock used by the <ACE_Message_Queue>. ACE_SYNCH_MUTEX_T &lock (void); - // Returns a reference to the lock used by the <ACE_Message_Queue>. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Routines that actually do the enqueueing and dequeueing. @@ -259,102 +288,102 @@ protected: // public methods. Since they are virtual, you can change the // queueing mechanism by subclassing from <ACE_Message_Queue>. + /// Enqueue an <ACE_Message_Block *> in accordance with its priority. virtual int enqueue_i (ACE_Message_Block *new_item); - // Enqueue an <ACE_Message_Block *> in accordance with its priority. + /// Enqueue an <ACE_Message_Block *> at the end of the queue. virtual int enqueue_tail_i (ACE_Message_Block *new_item); - // Enqueue an <ACE_Message_Block *> at the end of the queue. + /// Enqueue an <ACE_Message_Block *> at the head of the queue. virtual int enqueue_head_i (ACE_Message_Block *new_item); - // Enqueue an <ACE_Message_Block *> at the head of the queue. + /// Dequeue and return the <ACE_Message_Block *> at the head of the + /// queue. virtual int dequeue_head_i (ACE_Message_Block *&first_item); - // Dequeue and return the <ACE_Message_Block *> at the head of the - // queue. // = Check the boundary conditions (assumes locks are held). + /// True if queue is full, else false. virtual int is_full_i (void); - // True if queue is full, else false. + /// True if queue is empty, else false. virtual int is_empty_i (void); - // True if queue is empty, else false. // = Implementation of the public <activate> and <deactivate> methods. // These methods assume locks are held. + /// Deactivate the queue. virtual int deactivate_i (void); - // Deactivate the queue. + /// Activate the queue. virtual int activate_i (void); - // Activate the queue. // = Helper methods to factor out common #ifdef code. + /// Wait for the queue to become non-full. virtual int wait_not_full_cond (ACE_Guard<ACE_SYNCH_MUTEX_T> &mon, ACE_Time_Value *timeout); - // Wait for the queue to become non-full. + /// Wait for the queue to become non-empty. virtual int wait_not_empty_cond (ACE_Guard<ACE_SYNCH_MUTEX_T> &mon, ACE_Time_Value *timeout); - // Wait for the queue to become non-empty. + /// Inform any threads waiting to enqueue that they can procede. virtual int signal_enqueue_waiters (void); - // Inform any threads waiting to enqueue that they can procede. + /// Inform any threads waiting to dequeue that they can procede. virtual int signal_dequeue_waiters (void); - // Inform any threads waiting to dequeue that they can procede. + /// Pointer to head of ACE_Message_Block list. ACE_Message_Block *head_; - // Pointer to head of ACE_Message_Block list. + /// Pointer to tail of ACE_Message_Block list. ACE_Message_Block *tail_; - // Pointer to tail of ACE_Message_Block list. + /// Lowest number before unblocking occurs. size_t low_water_mark_; - // Lowest number before unblocking occurs. + /// Greatest number of bytes before blocking. size_t high_water_mark_; - // Greatest number of bytes before blocking. + /// Current number of bytes in the queue. size_t cur_bytes_; - // Current number of bytes in the queue. + /// Current length of messages in the queue. size_t cur_length_; - // Current length of messages in the queue. + /// Current number of messages in the queue. size_t cur_count_; - // Current number of messages in the queue. + /// Indicates that the queue is inactive. int deactivated_; - // Indicates that the queue is inactive. + /// The notification strategy used when a new message is enqueued. ACE_Notification_Strategy *notification_strategy_; - // The notification strategy used when a new message is enqueued. // = Synchronization primitives for controlling concurrent access. + /// Protect queue from concurrent access. ACE_SYNCH_MUTEX_T lock_; - // Protect queue from concurrent access. #if defined (ACE_HAS_OPTIMIZED_MESSAGE_QUEUE) + /// Used to make threads sleep until the queue is no longer empty. ACE_SYNCH_SEMAPHORE_T not_empty_cond_; - // Used to make threads sleep until the queue is no longer empty. + /// Used to make threads sleep until the queue is no longer full. ACE_SYNCH_SEMAPHORE_T not_full_cond_; - // Used to make threads sleep until the queue is no longer full. + /// Number of threads waiting to dequeue a <Message_Block>. size_t dequeue_waiters_; - // Number of threads waiting to dequeue a <Message_Block>. + /// Number of threads waiting to enqueue a <Message_Block>. size_t enqueue_waiters_; - // Number of threads waiting to enqueue a <Message_Block>. #else + /// Used to make threads sleep until the queue is no longer empty. ACE_SYNCH_CONDITION_T not_empty_cond_; - // Used to make threads sleep until the queue is no longer empty. + /// Used to make threads sleep until the queue is no longer full. ACE_SYNCH_CONDITION_T not_full_cond_; - // Used to make threads sleep until the queue is no longer full. #endif /* ACE_HAS_OPTIMIZED_MESSAGE_QUEUE */ private: @@ -364,154 +393,152 @@ private: ACE_UNIMPLEMENTED_FUNC (ACE_Message_Queue (const ACE_Message_Queue<ACE_SYNCH_USE> &)) }; +/** + * @class ACE_Message_Queue_Iterator + * + * @brief Iterator for the <ACE_Message_Queue>. + */ template <ACE_SYNCH_DECL> class ACE_Message_Queue_Iterator { - // = TITLE - // Iterator for the <ACE_Message_Queue>. public: // = Initialization method. ACE_Message_Queue_Iterator (ACE_Message_Queue <ACE_SYNCH_USE> &queue); // = Iteration methods. + /// Pass back the <entry> that hasn't been seen in the queue. + /// Returns 0 when all items have been seen, else 1. int next (ACE_Message_Block *&entry); - // Pass back the <entry> that hasn't been seen in the queue. - // Returns 0 when all items have been seen, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Move forward by one element in the queue. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the queue. Returns 0 when all the - // items in the set have been seen, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Message_Queue we are iterating over. ACE_Message_Queue <ACE_SYNCH_USE> &queue_; - // Message_Queue we are iterating over. + /// Keeps track of how far we've advanced... ACE_Message_Block *curr_; - // Keeps track of how far we've advanced... }; +/** + * @class ACE_Message_Queue_Reverse_Iterator + * + * @brief Reverse Iterator for the <ACE_Message_Queue>. + */ template <ACE_SYNCH_DECL> class ACE_Message_Queue_Reverse_Iterator { - // = TITLE - // Reverse Iterator for the <ACE_Message_Queue>. public: // = Initialization method. ACE_Message_Queue_Reverse_Iterator (ACE_Message_Queue <ACE_SYNCH_USE> &queue); // = Iteration methods. + /// Pass back the <entry> that hasn't been seen in the queue. + /// Returns 0 when all items have been seen, else 1. int next (ACE_Message_Block *&entry); - // Pass back the <entry> that hasn't been seen in the queue. - // Returns 0 when all items have been seen, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Move forward by one element in the queue. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the queue. Returns 0 when all the - // items in the set have been seen, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Message_Queue we are iterating over. ACE_Message_Queue <ACE_SYNCH_USE> &queue_; - // Message_Queue we are iterating over. + /// Keeps track of how far we've advanced... ACE_Message_Block *curr_; - // Keeps track of how far we've advanced... }; +/** + * @class ACE_Dynamic_Message_Queue + * + * @brief A derived class which adapts the <ACE_Message_Queue> + * class in order to maintain dynamic priorities for enqueued + * <ACE_Message_Blocks> and manage the queue order according + * to these dynamic priorities. + * + * The messages in the queue are managed so as to preserve + * a logical ordering with minimal overhead per enqueue and + * dequeue operation. For this reason, the actual order of + * messages in the linked list of the queue may differ from + * their priority order. As time passes, a message may change + * from pending status to late status, and eventually to beyond + * late status. To minimize reordering overhead under this + * design force, three separate boundaries are maintained + * within the linked list of messages. Messages are dequeued + * preferentially from the head of the pending portion, then + * the head of the late portion, and finally from the head + * of the beyond late portion. In this way, only the boundaries + * need to be maintained (which can be done efficiently, as + * aging messages maintain the same linked list order as they + * progress from one status to the next), with no reordering + * of the messages themselves, while providing correct priority + * ordered dequeueing semantics. + * Head and tail enqueue methods inherited from ACE_Message_Queue + * are made private to prevent out-of-order messages from confusing + * management of the various portions of the queue. Messages in + * the pending portion of the queue whose priority becomes late + * (according to the specific dynamic strategy) advance into + * the late portion of the queue. Messages in the late portion + * of the queue whose priority becomes later than can be represented + * advance to the beyond_late portion of the queue. These behaviors + * support a limited schedule overrun, with pending messages prioritized + * ahead of late messages, and late messages ahead of beyond late + * messages. These behaviors can be modified in derived classes by + * providing alternative definitions for the appropriate virtual methods. + * When filled with messages, the queue's linked list should look like: + * H T + * | | + * B - B - B - B - L - L - L - P - P - P - P - P + * | | | | | | + * BH BT LH LT PH PT + * Where the symbols are as follows: + * H = Head of the entire list + * T = Tail of the entire list + * B = Beyond late message + * BH = Beyond late messages Head + * BT = Beyond late messages Tail + * L = Late message + * LH = Late messages Head + * LT = Late messages Tail + * P = Pending message + * PH = Pending messages Head + * PT = Pending messages Tail + * Caveat: the virtual methods enqueue_tail, enqueue_head, + * and peek_dequeue_head have semantics for the static + * message queues that cannot be guaranteed for dynamic + * message queues. The peek_dequeue_head method just + * calls the base class method, while the two enqueue + * methods call the priority enqueue method. The + * order of messages in the dynamic queue is a function + * of message deadlines and how long they are in the + * queues. You can manipulate these in some cases to + * ensure the correct semantics, but that is not a + * very stable or portable approach (discouraged). + */ template <ACE_SYNCH_DECL> class ACE_Dynamic_Message_Queue : public ACE_Message_Queue<ACE_SYNCH_USE> { - // = TITLE - // A derived class which adapts the <ACE_Message_Queue> - // class in order to maintain dynamic priorities for enqueued - // <ACE_Message_Blocks> and manage the queue order according - // to these dynamic priorities. - // - // = DESCRIPTION - // - // The messages in the queue are managed so as to preserve - // a logical ordering with minimal overhead per enqueue and - // dequeue operation. For this reason, the actual order of - // messages in the linked list of the queue may differ from - // their priority order. As time passes, a message may change - // from pending status to late status, and eventually to beyond - // late status. To minimize reordering overhead under this - // design force, three separate boundaries are maintained - // within the linked list of messages. Messages are dequeued - // preferentially from the head of the pending portion, then - // the head of the late portion, and finally from the head - // of the beyond late portion. In this way, only the boundaries - // need to be maintained (which can be done efficiently, as - // aging messages maintain the same linked list order as they - // progress from one status to the next), with no reordering - // of the messages themselves, while providing correct priority - // ordered dequeueing semantics. - // - // Head and tail enqueue methods inherited from ACE_Message_Queue - // are made private to prevent out-of-order messages from confusing - // management of the various portions of the queue. Messages in - // the pending portion of the queue whose priority becomes late - // (according to the specific dynamic strategy) advance into - // the late portion of the queue. Messages in the late portion - // of the queue whose priority becomes later than can be represented - // advance to the beyond_late portion of the queue. These behaviors - // support a limited schedule overrun, with pending messages prioritized - // ahead of late messages, and late messages ahead of beyond late - // messages. These behaviors can be modified in derived classes by - // providing alternative definitions for the appropriate virtual methods. - // - // When filled with messages, the queue's linked list should look like: - // - // H T - // | | - // - // B - B - B - B - L - L - L - P - P - P - P - P - // - // | | | | | | - // BH BT LH LT PH PT - // - // Where the symbols are as follows: - // - // H = Head of the entire list - // T = Tail of the entire list - // B = Beyond late message - // BH = Beyond late messages Head - // BT = Beyond late messages Tail - // L = Late message - // LH = Late messages Head - // LT = Late messages Tail - // P = Pending message - // PH = Pending messages Head - // PT = Pending messages Tail - // - // Caveat: the virtual methods enqueue_tail, enqueue_head, - // and peek_dequeue_head have semantics for the static - // message queues that cannot be guaranteed for dynamic - // message queues. The peek_dequeue_head method just - // calls the base class method, while the two enqueue - // methods call the priority enqueue method. The - // order of messages in the dynamic queue is a function - // of message deadlines and how long they are in the - // queues. You can manipulate these in some cases to - // ensure the correct semantics, but that is not a - // very stable or portable approach (discouraged). - // public: // = Initialization and termination methods. ACE_Dynamic_Message_Queue (ACE_Dynamic_Message_Strategy & message_strategy, @@ -519,102 +546,114 @@ public: size_t lwm = ACE_Message_Queue_Base::DEFAULT_LWM, ACE_Notification_Strategy * = 0); + /// Close down the message queue and release all resources. virtual ~ACE_Dynamic_Message_Queue (void); - // Close down the message queue and release all resources. + /** + * Detach all messages with status given in the passed flags from + * the queue and return them by setting passed head and tail pointers + * to the linked list they comprise. This method is intended primarily + * as a means of periodically harvesting messages that have missed + * their deadlines, but is available in its most general form. All + * messages are returned in priority order, from head to tail, as of + * the time this method was called. + */ virtual int remove_messages (ACE_Message_Block *&list_head, ACE_Message_Block *&list_tail, u_int status_flags); - // Detach all messages with status given in the passed flags from - // the queue and return them by setting passed head and tail pointers - // to the linked list they comprise. This method is intended primarily - // as a means of periodically harvesting messages that have missed - // their deadlines, but is available in its most general form. All - // messages are returned in priority order, from head to tail, as of - // the time this method was called. + /** + * Dequeue and return the <ACE_Message_Block *> at the head of the + * queue. Returns -1 on failure, else the number of items still on + * the queue. + */ virtual int dequeue_head (ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0); - // Dequeue and return the <ACE_Message_Block *> at the head of the - // queue. Returns -1 on failure, else the number of items still on - // the queue. + /// Dump the state of the queue. virtual void dump (void) const; - // Dump the state of the queue. + /** + * just call priority enqueue method: tail enqueue semantics for dynamic + * message queues are unstable: the message may or may not be where + * it was placed after the queue is refreshed prior to the next + * enqueue or dequeue operation. + */ virtual int enqueue_tail (ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0); - // just call priority enqueue method: tail enqueue semantics for dynamic - // message queues are unstable: the message may or may not be where - // it was placed after the queue is refreshed prior to the next - // enqueue or dequeue operation. + /** + * just call priority enqueue method: head enqueue semantics for dynamic + * message queues are unstable: the message may or may not be where + * it was placed after the queue is refreshed prior to the next + * enqueue or dequeue operation. + */ virtual int enqueue_head (ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0); - // just call priority enqueue method: head enqueue semantics for dynamic - // message queues are unstable: the message may or may not be where - // it was placed after the queue is refreshed prior to the next - // enqueue or dequeue operation. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /** + * Enqueue an <ACE_Message_Block *> in accordance with its priority. + * priority may be *dynamic* or *static* or a combination or *both* + * It calls the priority evaluation function passed into the Dynamic + * Message Queue constructor to update the priorities of all + * enqueued messages. + */ virtual int enqueue_i (ACE_Message_Block *new_item); - // Enqueue an <ACE_Message_Block *> in accordance with its priority. - // priority may be *dynamic* or *static* or a combination or *both* - // It calls the priority evaluation function passed into the Dynamic - // Message Queue constructor to update the priorities of all - // enqueued messages. + /// enqueue a message in priority order within a given priority status sublist virtual int sublist_enqueue_i (ACE_Message_Block *new_item, const ACE_Time_Value ¤t_time, ACE_Message_Block *&sublist_head, ACE_Message_Block *&sublist_tail, ACE_Dynamic_Message_Strategy::Priority_Status status); - // enqueue a message in priority order within a given priority status sublist + /** + * Dequeue and return the <ACE_Message_Block *> at the head of the + * logical queue. Attempts first to dequeue from the pending + * portion of the queue, or if that is empty from the late portion, + * or if that is empty from the beyond late portion, or if that is + * empty just sets the passed pointer to zero and returns -1. + */ virtual int dequeue_head_i (ACE_Message_Block *&first_item); - // Dequeue and return the <ACE_Message_Block *> at the head of the - // logical queue. Attempts first to dequeue from the pending - // portion of the queue, or if that is empty from the late portion, - // or if that is empty from the beyond late portion, or if that is - // empty just sets the passed pointer to zero and returns -1. + /// Refresh the queue using the strategy + /// specific priority status function. virtual int refresh_queue (const ACE_Time_Value & current_time); - // Refresh the queue using the strategy - // specific priority status function. + /// Refresh the pending queue using the strategy + /// specific priority status function. virtual int refresh_pending_queue (const ACE_Time_Value & current_time); - // Refresh the pending queue using the strategy - // specific priority status function. + /// Refresh the late queue using the strategy + /// specific priority status function. virtual int refresh_late_queue (const ACE_Time_Value & current_time); - // Refresh the late queue using the strategy - // specific priority status function. + /// Pointer to head of the pending messages ACE_Message_Block *pending_head_; - // Pointer to head of the pending messages + /// Pointer to tail of the pending messages ACE_Message_Block *pending_tail_; - // Pointer to tail of the pending messages + /// Pointer to head of the late messages ACE_Message_Block *late_head_; - // Pointer to head of the late messages + /// Pointer to tail of the late messages ACE_Message_Block *late_tail_; - // Pointer to tail of the late messages + /// Pointer to head of the beyond late messages ACE_Message_Block *beyond_late_head_; - // Pointer to head of the beyond late messages + /// Pointer to tail of the beyond late messages ACE_Message_Block *beyond_late_tail_; - // Pointer to tail of the beyond late messages + /// Pointer to a dynamic priority evaluation function. ACE_Dynamic_Message_Strategy &message_strategy_; - // Pointer to a dynamic priority evaluation function. private: // = Disallow public access to these operations. @@ -625,35 +664,38 @@ private: // provide definitions for these (just call base class method), // but make them private so they're not accessible outside the class + /// private method to hide public base class method: just calls base class method virtual int peek_dequeue_head (ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0); - // private method to hide public base class method: just calls base class method }; +/** + * @class ACE_Message_Queue_Factory + * + * @brief ACE_Message_Queue_Factory is a static factory class template which + * provides a separate factory method for each of the major kinds of + * priority based message dispatching: static, earliest deadline first + * (EDF), and minimum laxity first (MLF). + * + * The ACE_Dynamic_Message_Queue class assumes responsibility for + * releasing the resources of the strategy with which it was + * constructed: the user of a message queue constructed by + * any of these factory methods is only responsible for + * ensuring destruction of the message queue itself. + */ template <ACE_SYNCH_DECL> class ACE_Message_Queue_Factory { - // = TITLE - // ACE_Message_Queue_Factory is a static factory class template which - // provides a separate factory method for each of the major kinds of - // priority based message dispatching: static, earliest deadline first - // (EDF), and minimum laxity first (MLF). - // - // = DESCRIPTION - // The ACE_Dynamic_Message_Queue class assumes responsibility for - // releasing the resources of the strategy with which it was - // constructed: the user of a message queue constructed by - // any of these factory methods is only responsible for - // ensuring destruction of the message queue itself. public: + /// factory method for a statically prioritized ACE_Message_Queue static ACE_Message_Queue<ACE_SYNCH_USE> * create_static_message_queue (size_t hwm = ACE_Message_Queue_Base::DEFAULT_HWM, size_t lwm = ACE_Message_Queue_Base::DEFAULT_LWM, ACE_Notification_Strategy * = 0); - // factory method for a statically prioritized ACE_Message_Queue + /// factory method for a dynamically prioritized (by time to deadline) ACE_Dynamic_Message_Queue static ACE_Dynamic_Message_Queue<ACE_SYNCH_USE> * create_deadline_message_queue (size_t hwm = ACE_Message_Queue_Base::DEFAULT_HWM, size_t lwm = ACE_Message_Queue_Base::DEFAULT_LWM, @@ -662,8 +704,8 @@ public: u_long static_bit_field_shift = 10, // 10 low order bits u_long dynamic_priority_max = 0x3FFFFFUL, // 2^(22)-1 u_long dynamic_priority_offset = 0x200000UL); // 2^(22-1) - // factory method for a dynamically prioritized (by time to deadline) ACE_Dynamic_Message_Queue + /// factory method for a dynamically prioritized (by laxity) ACE_Dynamic_Message_Queue static ACE_Dynamic_Message_Queue<ACE_SYNCH_USE> * create_laxity_message_queue (size_t hwm = ACE_Message_Queue_Base::DEFAULT_HWM, size_t lwm = ACE_Message_Queue_Base::DEFAULT_LWM, @@ -672,23 +714,22 @@ public: u_long static_bit_field_shift = 10, // 10 low order bits u_long dynamic_priority_max = 0x3FFFFFUL, // 2^(22)-1 u_long dynamic_priority_offset = 0x200000UL); // 2^(22-1) - // factory method for a dynamically prioritized (by laxity) ACE_Dynamic_Message_Queue #if defined (VXWORKS) + /// factory method for a wrapped VxWorks message queue static ACE_Message_Queue_Vx * create_Vx_message_queue (size_t max_messages, size_t max_message_length, ACE_Notification_Strategy *ns = 0); - // factory method for a wrapped VxWorks message queue #endif /* defined (VXWORKS) */ #if defined (ACE_WIN32) && (ACE_HAS_WINNT4 != 0) + /// factory method for a NT message queue. static ACE_Message_Queue_NT * create_NT_message_queue (size_t max_threads); - // factory method for a NT message queue. #endif /* ACE_WIN32 && ACE_HAS_WINNT4 != 0 */ }; diff --git a/ace/Method_Object.h b/ace/Method_Object.h index 5f992bb2d04..51d2896e05e 100644 --- a/ace/Method_Object.h +++ b/ace/Method_Object.h @@ -1,23 +1,20 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Method_Object.h -// -// = DESCRIPTION -// This file just #includes "ace/Method_Request.h" and is just here -// for backwards compatibility with earlier versions of ACE. -// Please don't use it directly since it may go away at some point. -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Method_Object.h + * + * $Id$ + * + * This file just #includes "ace/Method_Request.h" and is just here + * for backwards compatibility with earlier versions of ACE. + * Please don't use it directly since it may go away at some point. + * + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_METHOD_OBJECT_H #define ACE_METHOD_OBJECT_H diff --git a/ace/Method_Request.h b/ace/Method_Request.h index 69739e39ffe..a6fff914a46 100644 --- a/ace/Method_Request.h +++ b/ace/Method_Request.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Method_Request.h -// -// = AUTHOR -// Andres Kruse <Andres.Kruse@cern.ch> and Douglas C. Schmidt -// <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Method_Request.h + * + * $Id$ + * + * @author Andres Kruse <Andres.Kruse@cern.ch> + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_METHOD_REQUEST_H #define ACE_METHOD_REQUEST_H @@ -25,38 +22,40 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Method_Request + * + * @brief Reifies a method into a request. Subclasses provide + * the necessary state and behavior. + * + * A <Method_Request> is inserted in the <Activation_Queue>, + * where it is subsequently removed by a <Scheduler>, which + * invokes the <call> method. + */ class ACE_Export ACE_Method_Request { - // = TITLE - // Reifies a method into a request. Subclasses provide - // the necessary state and behavior. - // - // = DESCRIPTION - // A <Method_Request> is inserted in the <Activation_Queue>, - // where it is subsequently removed by a <Scheduler>, which - // invokes the <call> method. public: // = Initialization and termination methods. + /// Constructor. ACE_Method_Request (u_long priority = 0); - // Constructor. + /// Destructor. virtual ~ACE_Method_Request (void); - // Destructor. // = Accessors. + /// Get priority. u_long priority (void); - // Get priority. + /// Set priority. void priority (u_long); - // Set priority. // = Invocation method (must be overridden by subclasses). + /// Invoked when the <Method_Request> is scheduled to run. virtual int call (void) = 0; - // Invoked when the <Method_Request> is scheduled to run. protected: + /// The priority of the request. u_long priority_; - // The priority of the request. }; #include "ace/post.h" diff --git a/ace/Min_Max.h b/ace/Min_Max.h index 5d3617c9096..cac64b2dcbc 100644 --- a/ace/Min_Max.h +++ b/ace/Min_Max.h @@ -1,26 +1,22 @@ // -*- C++ -*- -// $Id$ + +//============================================================================= +/** + * @file Min_Max.h + * + * $Id$ + * + * Define an appropriate set of min()/max() functions using templates. + * + * + * @author Derek Dominish <Derek.Dominish@Australia.Boeing.com> + */ +//============================================================================= #ifndef ACE_MIN_MAX_H #define ACE_MIN_MAX_H #include "ace/pre.h" -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Min_Max.h -// -// = DESCRIPTION -// Define an appropriate set of min()/max() functions using templates. -// -// = AUTHOR -// Derek Dominish <Derek.Dominish@Australia.Boeing.com> -// -// ============================================================================ - # if !defined (ACE_LACKS_PRAGMA_ONCE) # pragma once # endif /* ACE_LACKS_PRAGMA_ONCE */ @@ -34,22 +30,22 @@ ace_min (const T &t1, const T &t2) } template <class T> -inline const T & -ace_max (const T &t1, const T &t2) +inline const T & +ace_max (const T &t1, const T &t2) { return t1 > t2 ? t1 : t2; } template <class T> inline const T & -ace_min (const T &t1, const T &t2, const T &t3) +ace_min (const T &t1, const T &t2, const T &t3) { return ace_min (ace_min (t1, t2), t3); } template <class T> inline const T & -ace_max (const T &t1, const T &t2, const T &t3) +ace_max (const T &t1, const T &t2, const T &t3) { return ace_max (ace_max (t1, t2), t3); } @@ -62,7 +58,7 @@ ace_range (const T &min, const T &max, const T &val) } # else // These macros should only be used if a C++ compiler can't grok the -// inline templates +// inline templates # define ace_min(a,b) (((b) > (a)) ? (a) : (b)) # define ace_max(a,b) (((a) > (b)) ? (a) : (b)) # define ace_range(a,b,c) (ace_min(ace_max((a), (c)), (b)) diff --git a/ace/Module.h b/ace/Module.h index 7a28201b83c..735220a55ba 100644 --- a/ace/Module.h +++ b/ace/Module.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Module.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Module.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_MODULE_H #define ACE_MODULE_H @@ -26,157 +23,172 @@ #include "ace/Task_T.h" +/** + * @class ACE_Module_Base + * + * @brief Workaround HP/C++ compiler bug with enums in templates. + * + * Certain C++ compilers, e.g., the HP/UX 10.x and 9.x compilers, + * seem to fail if enums are defined inside a template, hence we + * have to move them into a base class. + */ class ACE_Export ACE_Module_Base { - // = TITLE - // Workaround HP/C++ compiler bug with enums in templates. - // - // = DESCRIPTION - // Certain C++ compilers, e.g., the HP/UX 10.x and 9.x compilers, - // seem to fail if enums are defined inside a template, hence we - // have to move them into a base class. public: enum { + /// Indicates that <close> should not delete any Tasks. M_DELETE_NONE = 0, - // Indicates that <close> should not delete any Tasks. + /// Indicates that <close> should delete the writer Task. M_DELETE_READER = 1, - // Indicates that <close> should delete the writer Task. + /// Indicates that <close> should delete the reader Task. M_DELETE_WRITER = 2, - // Indicates that <close> should delete the reader Task. + /// Indicates that <close> deletes the Tasks. + /** + * Don't change this value without updating the same enum in class + * ACE_Stream... + * The <M_DELETE_READER> and <M_DELETE_WRITER> flags may be or'ed + * together. + */ M_DELETE = 3 - // Indicates that <close> deletes the Tasks. Don't change this - // value without updating the same enum in class ACE_Stream... - // The <M_DELETE_READER> and <M_DELETE_WRITER> flags may be or'ed - // together. }; }; +/** + * @class ACE_Module + * + * @brief An abstraction for managing a bi-directional flow of messages. + * + * This is based on the Module concept in System V Streams, + * which contains a pair of Tasks, one for handling upstream + * processing, one for handling downstream processing. In + * general, you shouldn't subclass from this class, but instead + * subclass from the <ACE_Task>. + */ template <ACE_SYNCH_DECL> class ACE_Module : public ACE_Module_Base { - // = TITLE - // An abstraction for managing a bi-directional flow of messages. - // - // = DESCRIPTION - // This is based on the Module concept in System V Streams, - // which contains a pair of Tasks, one for handling upstream - // processing, one for handling downstream processing. In - // general, you shouldn't subclass from this class, but instead - // subclass from the <ACE_Task>. public: friend class ACE_Shutup_GPlusPlus; // Turn off g++ warning // = Initialization and termination methods. + /// Create an empty Module. ACE_Module (void); - // Create an empty Module. + /// Shutdown the Module. ~ACE_Module (void); - // Shutdown the Module. + /// Create an initialized module with <module_name> as its identity + /// and <reader> and <writer> as its tasks. ACE_Module (const ACE_TCHAR *module_name, ACE_Task<ACE_SYNCH_USE> *writer = 0, ACE_Task<ACE_SYNCH_USE> *reader = 0, void *args = 0, int flags = M_DELETE); - // Create an initialized module with <module_name> as its identity - // and <reader> and <writer> as its tasks. + /** + * Create an initialized module with <module_name> as its identity + * and <reader> and <writer> as its tasks. Previously register + * reader or writers or closed down and deleted according to the + * value of flags_. Should not be called from within + * <ACE_Task::module_closed>. + */ int open (const ACE_TCHAR *module_name, ACE_Task<ACE_SYNCH_USE> *writer = 0, ACE_Task<ACE_SYNCH_USE> *reader = 0, void *a = 0, int flags = M_DELETE); - // Create an initialized module with <module_name> as its identity - // and <reader> and <writer> as its tasks. Previously register - // reader or writers or closed down and deleted according to the - // value of flags_. Should not be called from within - // <ACE_Task::module_closed>. + /** + * Close down the Module and its Tasks. The flags argument can be + * used to override the default behaviour, which depends on previous + * <flags> values in calls to c'tor, <open>, <reader>, and <writer>. + * A previous value M_DELETE[_XXX] can not be overridden. Should + * not be called from within <ACE_Task::module_closed>. + */ int close (int flags = M_DELETE_NONE); - // Close down the Module and its Tasks. The flags argument can be - // used to override the default behaviour, which depends on previous - // <flags> values in calls to c'tor, <open>, <reader>, and <writer>. - // A previous value M_DELETE[_XXX] can not be overridden. Should - // not be called from within <ACE_Task::module_closed>. // = ACE_Task manipulation routines + /// Get the writer task. ACE_Task<ACE_SYNCH_USE> *writer (void); - // Get the writer task. + /** + * Set the writer task. <flags> can be used to indicate that the + * module should delete the writer during a call to close or to the + * destructor. If a previous writer exists, it is closed. It may + * also be deleted, depending on the old flags_ value. Should not + * be called from within <ACE_Task::module_closed>. + */ void writer (ACE_Task<ACE_SYNCH_USE> *q, int flags = M_DELETE_WRITER); - // Set the writer task. <flags> can be used to indicate that the - // module should delete the writer during a call to close or to the - // destructor. If a previous writer exists, it is closed. It may - // also be deleted, depending on the old flags_ value. Should not - // be called from within <ACE_Task::module_closed>. + /// Get the reader task. ACE_Task<ACE_SYNCH_USE> *reader (void); - // Get the reader task. + /** + * Set the reader task. <flags> can be used to indicate that the + * module should delete the reader during a call to close or to the + * destructor. If a previous reader exists, it is closed. It may + * also be deleted, depending on the old flags_ value. Should not + * be called from within <ACE_Task::module_closed>. + */ void reader (ACE_Task<ACE_SYNCH_USE> *q, int flags = M_DELETE_READER); - // Set the reader task. <flags> can be used to indicate that the - // module should delete the reader during a call to close or to the - // destructor. If a previous reader exists, it is closed. It may - // also be deleted, depending on the old flags_ value. Should not - // be called from within <ACE_Task::module_closed>. + /// Set and get pointer to sibling <ACE_Task> in an <ACE_Module> ACE_Task<ACE_SYNCH_USE> *sibling (ACE_Task<ACE_SYNCH_USE> *orig); - // Set and get pointer to sibling <ACE_Task> in an <ACE_Module> // = Identify the module + /// Get the module name. + /// Set the module name. const ACE_TCHAR *name (void) const; - // Get the module name. void name (const ACE_TCHAR *); - // Set the module name. // = Argument to the Tasks. + /// Get the argument passed to the tasks. void *arg (void) const; - // Get the argument passed to the tasks. + /// Set the argument passed to the tasks. void arg (void *); - // Set the argument passed to the tasks. + /// Link to other modules in the ustream stack void link (ACE_Module<ACE_SYNCH_USE> *m); - // Link to other modules in the ustream stack + /// Get the next pointer to the module above in the stream. ACE_Module<ACE_SYNCH_USE> *next (void); - // Get the next pointer to the module above in the stream. + /// Set the next pointer to the module above in the stream. void next (ACE_Module<ACE_SYNCH_USE> *m); - // Set the next pointer to the module above in the stream. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Implements the close operation for either the reader or the + /// writer task (depending on <which>). int close_i (int which, int flags); - // Implements the close operation for either the reader or the - // writer task (depending on <which>). + /// Pair of Tasks that form the "read-side" and "write-side" of the + /// ACE_Module partitioning. ACE_Task<ACE_SYNCH_USE> *q_pair_[2]; - // Pair of Tasks that form the "read-side" and "write-side" of the - // ACE_Module partitioning. + /// Name of the ACE_Module. ACE_TCHAR name_[MAXNAMLEN + 1]; - // Name of the ACE_Module. + /// Next ACE_Module in the stack. ACE_Module<ACE_SYNCH_USE> *next_; - // Next ACE_Module in the stack. + /// Argument passed through to the reader and writer task when they + /// are opened. void *arg_; - // Argument passed through to the reader and writer task when they - // are opened. + /// Holds flags which are used to determine if the reader and writer + /// task have to be deleted on exit int flags_; - // Holds flags which are used to determine if the reader and writer - // task have to be deleted on exit }; #if defined (__ACE_INLINE__) diff --git a/ace/Msg_WFMO_Reactor.h b/ace/Msg_WFMO_Reactor.h index 1cfe2a7f211..827a51e0e0f 100644 --- a/ace/Msg_WFMO_Reactor.h +++ b/ace/Msg_WFMO_Reactor.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Msg_WFMO_Reactor.h -// -// = AUTHOR -// Beskrovny Evgeny <evgeny_beskrovny@icomverse.com> and -// Irfan Pyarali <irfan@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Msg_WFMO_Reactor.h + * + * $Id$ + * + * @author Beskrovny Evgeny <evgeny_beskrovny@icomverse.com> + * @author Irfan Pyarali <irfan@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_MSG_WFMO_REACTOR_H #define ACE_MSG_WFMO_REACTOR_H @@ -27,76 +24,84 @@ #if defined (ACE_WIN32) && !defined (ACE_LACKS_MSG_WFMO) +/** + * @class ACE_Msg_WFMO_Reactor + * + * @brief An OO event demultiplexor and event handler dispatcher for + * Win32 <MsgWaitForMultipleObjects>. + * + * The ACE_Msg_WFMO_Reactor is an OO event demultiplexor and + * event handler Reactor. It differs from <ACE_WFMO_Reactor> by + * its ability to react on Windows messages. It is needed when + * the task should serve also as a COM/DCOM server. + */ class ACE_Export ACE_Msg_WFMO_Reactor : public ACE_WFMO_Reactor { - // = TITLE - // An OO event demultiplexor and event handler dispatcher for - // Win32 <MsgWaitForMultipleObjects>. - // - // = DESCRIPTION - // The ACE_Msg_WFMO_Reactor is an OO event demultiplexor and - // event handler Reactor. It differs from <ACE_WFMO_Reactor> by - // its ability to react on Windows messages. It is needed when - // the task should serve also as a COM/DCOM server. public: // = Initialization and termination methods. + /// Initialize <ACE_Msg_WFMO_Reactor> with the default size. ACE_Msg_WFMO_Reactor (ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0); - // Initialize <ACE_Msg_WFMO_Reactor> with the default size. + /** + * Initialize <ACE_Msg_WFMO_Reactor> with size <size>. Two slots will be + * added to the <size> parameter which will store handles used for + * internal management purposes. + */ ACE_Msg_WFMO_Reactor (size_t size, int unused = 0, ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0); - // Initialize <ACE_Msg_WFMO_Reactor> with size <size>. Two slots will be - // added to the <size> parameter which will store handles used for - // internal management purposes. + /// Close down the ACE_Msg_WFMO_Reactor and release all of its resources. virtual ~ACE_Msg_WFMO_Reactor (void); - // Close down the ACE_Msg_WFMO_Reactor and release all of its resources. + /** + * This event loop driver blocks for up to <max_wait_time> before + * returning. It will return earlier if timer events, I/O events, + * window events, or signal events occur. Note that <max_wait_time> + * can be 0, in which case this method blocks indefinitely until + * events occur. + * + * <max_wait_time> is decremented to reflect how much time this call + * took. For instance, if a time value of 3 seconds is passed to + * handle_events and an event occurs after 2 seconds, + * <max_wait_time> will equal 1 second. This can be used if an + * application wishes to handle events for some fixed amount of + * time. + * + * <MsgWaitForMultipleObjects> is used as the demultiplexing call + * + * Returns the total number of <ACE_Event_Handler>s that were + * dispatched, 0 if the <max_wait_time> elapsed without dispatching + * any handlers, or -1 if an error occurs. + * + * The only difference between <alertable_handle_events> and + * <handle_events> is that in the alertable case, MWMO_ALERTABLE is + * passed to <MsgWaitForMultipleObjects> for the <bAlertable> + * option. + */ virtual int handle_events (ACE_Time_Value *max_wait_time = 0); virtual int alertable_handle_events (ACE_Time_Value *max_wait_time = 0); - // This event loop driver blocks for up to <max_wait_time> before - // returning. It will return earlier if timer events, I/O events, - // window events, or signal events occur. Note that <max_wait_time> - // can be 0, in which case this method blocks indefinitely until - // events occur. - // - // <max_wait_time> is decremented to reflect how much time this call - // took. For instance, if a time value of 3 seconds is passed to - // handle_events and an event occurs after 2 seconds, - // <max_wait_time> will equal 1 second. This can be used if an - // application wishes to handle events for some fixed amount of - // time. - // - // <MsgWaitForMultipleObjects> is used as the demultiplexing call - // - // Returns the total number of <ACE_Event_Handler>s that were - // dispatched, 0 if the <max_wait_time> elapsed without dispatching - // any handlers, or -1 if an error occurs. - // - // The only difference between <alertable_handle_events> and - // <handle_events> is that in the alertable case, MWMO_ALERTABLE is - // passed to <MsgWaitForMultipleObjects> for the <bAlertable> - // option. + /** + * This method is just like the one above, except the + * <max_wait_time> value is a reference and can therefore never be + * NULL. + */ virtual int handle_events (ACE_Time_Value &max_wait_time); virtual int alertable_handle_events (ACE_Time_Value &max_wait_time); - // This method is just like the one above, except the - // <max_wait_time> value is a reference and can therefore never be - // NULL. protected: + /// Wait for timer and I/O events to occur. virtual int wait_for_multiple_events (int timeout, int alertable); - // Wait for timer and I/O events to occur. + /// Check for activity on remaining handles. virtual DWORD poll_remaining_handles (size_t index); - // Check for activity on remaining handles. + /// Dispatches window messages. virtual int dispatch_window_messages (void); - // Dispatches window messages. }; #endif /* ACE_WIN32 && !ACE_LACKS_MSG_WFMO */ diff --git a/ace/Multiplexor.h b/ace/Multiplexor.h index 03ccf42285b..9e99d231681 100644 --- a/ace/Multiplexor.h +++ b/ace/Multiplexor.h @@ -1,23 +1,20 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Multiplexor.h -// -// = DESCRIPTION -// Define the ACE_Driver and ACE_Multiplexor container classes. -// Note that these classes have never been implemented due to lack -// of need. -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ +//============================================================================= +/** + * @file Multiplexor.h + * + * $Id$ + * + * Define the ACE_Driver and ACE_Multiplexor container classes. + * Note that these classes have never been implemented due to lack + * of need. + * + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_MULTIPLEXOR_H #define ACE_MULTIPLEXOR_H @@ -34,13 +31,13 @@ #if defined (ACE_HAS_THREADS) #if 0 +/** + * @class ACE_Driver + * + * + */ class ACE_Export ACE_Driver { - // = TITLE - // - // - // = DESCRIPTION - // public: ACE_Driver (void); ~ACE_Driver (void); @@ -50,12 +47,13 @@ public: virtual int unlink_from_below (ACE_Module *); }; +/** + * @class ACE_Multiplexor + * + * + */ class ACE_Export ACE_Multiplexor { - // = TITLE - // - // = DESCRIPTION - // public: // = Constructors and destructors ACE_Multiplexor (void); diff --git a/ace/NT_Service.h b/ace/NT_Service.h index 9f01164c623..0a17c04aed6 100644 --- a/ace/NT_Service.h +++ b/ace/NT_Service.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// NT_Service.h -// -// = AUTHOR -// Steve Huston <shuston@riverace.com> -// -// ============================================================================ +//============================================================================= +/** + * @file NT_Service.h + * + * $Id$ + * + * @author Steve Huston <shuston@riverace.com> + */ +//============================================================================= + #ifndef ACE_NT_SERVICE_H #define ACE_NT_SERVICE_H @@ -38,129 +35,145 @@ #define ACE_NT_SERVICE_START_TIMEOUT 5000 #endif /* ACE_NT_SERVICE_TIMEOUT */ +/** + * @class ACE_NT_Service + * + * @brief Provide the base class which defines the interface for controlling + * an NT service. + * + * NT Services can be implemented using the framework defined by + * the ACE_NT_Service class, and the macros defined in this file. + * Some quick refresher notes on NT Services: + * + * - The main program defines an array of entries describing the + * services offered. The ACE_NT_SERVICE_ENTRY macro can help with + * this. + * - For each service, a separate ServiceMain and Handler function + * need to be defined. These are taken care of by the + * ACE_NT_SERVICE_DEFINE macro. + * - When the main program/thread calls + * StartServiceCtrlDispatcher, NT creates a thread for each + * service, and runs the ServiceMain function for the service in + * that new thread. When that thread exits, the service is gone. + * + * To use this facility, you could derive a class from + * ACE_Service_Object (if you want to start via ACE's service + * configurator), or use any other class to run when the image + * starts (assuming that NT runs the image). You must set up an + * NT SERVICE_TABLE_ENTRY array to define your service(s). You + * can use the ACE_NT_SERVICE_... macros defined below for this. + * + * A SERVICE_TABLE might look like this: + * ACE_NT_SERVICE_REFERENCE(Svc1); // If service is in another file + * SERVICE_TABLE_ENTRY myServices[] = { + * ACE_NT_SERVICE_ENTRY ("MyNeatService", Svc1), + * { 0, 0 } }; + * + * In the file where your service(s) are implemented, use the + * ACE_NT_SERVICE_DEFINE macro to set up the following: + * 1. A pointer to the service's implementation object (must be derived + * from ACE_NT_Service). + * 2. The service's Handler function (forwards all requests to the + * ACE_NT_Service-derived object's handle_control function). + * 3. The service's ServiceMain function. Creates a new instance + * of the ACE_NT_Service-derived class SVCCLASS, unless one has + * been created already. + * + * If you are using all the default constructor values, you can + * let the generated ServiceMain function create the object, else + * you need to create it by hand before calling + * StartServiceCtrlDispatcher. Set the pointer so ServiceMain + * won't create another one. Another reason you may want to do + * the object creation yourself is if you want to also implement + * suspend and resume functions (the ones inherited from + * ACE_Service_Object) to do something intelligent to the services + * which are running, like call their handle_control functions to + * request suspend and resume actions, similar to what NT would do + * if a Services control panel applet would do if the user clicks + * on Suspend. + */ class ACE_Export ACE_NT_Service : public ACE_Task<ACE_MT_SYNCH> { - // = TITLE - // Provide the base class which defines the interface for controlling - // an NT service. - // - // = DESCRIPTION - // NT Services can be implemented using the framework defined by - // the ACE_NT_Service class, and the macros defined in this file. - // Some quick refresher notes on NT Services: - - // - The main program defines an array of entries describing the - // services offered. The ACE_NT_SERVICE_ENTRY macro can help with - // this. - // - For each service, a separate ServiceMain and Handler function - // need to be defined. These are taken care of by the - // ACE_NT_SERVICE_DEFINE macro. - // - When the main program/thread calls - // StartServiceCtrlDispatcher, NT creates a thread for each - // service, and runs the ServiceMain function for the service in - // that new thread. When that thread exits, the service is gone. - // - // To use this facility, you could derive a class from - // ACE_Service_Object (if you want to start via ACE's service - // configurator), or use any other class to run when the image - // starts (assuming that NT runs the image). You must set up an - // NT SERVICE_TABLE_ENTRY array to define your service(s). You - // can use the ACE_NT_SERVICE_... macros defined below for this. - // - // A SERVICE_TABLE might look like this: - // ACE_NT_SERVICE_REFERENCE(Svc1); // If service is in another file - // SERVICE_TABLE_ENTRY myServices[] = { - // ACE_NT_SERVICE_ENTRY ("MyNeatService", Svc1), - // { 0, 0 } }; - // - // In the file where your service(s) are implemented, use the - // ACE_NT_SERVICE_DEFINE macro to set up the following: - // 1. A pointer to the service's implementation object (must be derived - // from ACE_NT_Service). - // 2. The service's Handler function (forwards all requests to the - // ACE_NT_Service-derived object's handle_control function). - // 3. The service's ServiceMain function. Creates a new instance - // of the ACE_NT_Service-derived class SVCCLASS, unless one has - // been created already. - // - // If you are using all the default constructor values, you can - // let the generated ServiceMain function create the object, else - // you need to create it by hand before calling - // StartServiceCtrlDispatcher. Set the pointer so ServiceMain - // won't create another one. Another reason you may want to do - // the object creation yourself is if you want to also implement - // suspend and resume functions (the ones inherited from - // ACE_Service_Object) to do something intelligent to the services - // which are running, like call their handle_control functions to - // request suspend and resume actions, similar to what NT would do - // if a Services control panel applet would do if the user clicks - // on Suspend. + public: // = Initialization and termination methods. + /// Constructor primarily for use when running the service. ACE_NT_Service (DWORD start_timeout = ACE_NT_SERVICE_START_TIMEOUT, DWORD service_type = SERVICE_WIN32_OWN_PROCESS, DWORD controls_mask = SERVICE_ACCEPT_STOP); - // Constructor primarily for use when running the service. + /// Constructor primarily for use when inserting/removing/controlling + /// the service. ACE_NT_Service (const ACE_TCHAR *name, const ACE_TCHAR *desc = 0, DWORD start_timeout = ACE_NT_SERVICE_START_TIMEOUT, DWORD service_type = SERVICE_WIN32_OWN_PROCESS, DWORD controls_mask = SERVICE_ACCEPT_STOP); - // Constructor primarily for use when inserting/removing/controlling - // the service. virtual ~ACE_NT_Service (void); // = Functions to operate the service + /** + * Hook called to open the service. By default, will set the status + * to <START>_PENDING, <svc>, <wait>, then set the status to + * STOPPED. + */ virtual int open (void *args = 0); - // Hook called to open the service. By default, will set the status - // to <START>_PENDING, <svc>, <wait>, then set the status to - // STOPPED. + /** + * The actual service implementation. This function need not be overridden + * by applications that are just using SCM capabilities, but must be + * by subclasses when actually running the service. It is expected that + * this function will set the status to RUNNING. + */ virtual int svc (void); - // The actual service implementation. This function need not be overridden - // by applications that are just using SCM capabilities, but must be - // by subclasses when actually running the service. It is expected that - // this function will set the status to RUNNING. + /** + * This function is called in response to a request from the Service + * Dispatcher. It must interact with the <svc> function to effect the + * requested control operation. The default implementation handles + * all requests as follows: + * SERVICE_CONTROL_STOP: set stop pending, set cancel flag + * SERVICE_CONTROL_PAUSE: set pause pending, <suspend>, set paused + * SERVICE_CONTROL_CONTINUE: set continue pending, <resume>, set running + * SERVICE_CONTROL_INTERROGATE: reports current status + * SERVICE_CONTROL_SHUTDOWN: same as SERVICE_CONTROL_STOP. + */ virtual void handle_control (DWORD control_code); - // This function is called in response to a request from the Service - // Dispatcher. It must interact with the <svc> function to effect the - // requested control operation. The default implementation handles - // all requests as follows: - // SERVICE_CONTROL_STOP: set stop pending, set cancel flag - // SERVICE_CONTROL_PAUSE: set pause pending, <suspend>, set paused - // SERVICE_CONTROL_CONTINUE: set continue pending, <resume>, set running - // SERVICE_CONTROL_INTERROGATE: reports current status - // SERVICE_CONTROL_SHUTDOWN: same as SERVICE_CONTROL_STOP. + /// Set the svc_handle_ member. This is only a public function because + /// the macro-generated service function calls it. void svc_handle (const SERVICE_STATUS_HANDLE new_svc_handle); - // Set the svc_handle_ member. This is only a public function because - // the macro-generated service function calls it. // = Methods which can be used to do SCP-like functions. The first group // are used to register/insert and remove the service's definition in the // SCM registry. + /// Sets the name and description for the service. + /// If desc is 0, it takes the same value as name. void name (const ACE_TCHAR *name, const ACE_TCHAR *desc = 0); - // Sets the name and description for the service. - // If desc is 0, it takes the same value as name. + /// Get the service name. const ACE_TCHAR *name (void) const; - // Get the service name. + /// Get the service description. const ACE_TCHAR *desc (void) const; - // Get the service description. + /// Sets the host machine void host (const ACE_TCHAR *host); - // Sets the host machine + /// Get the host machine. const ACE_TCHAR *host (void) const; - // Get the host machine. + /** + * Insert (create) the service in the NT Service Control Manager, + * with the given creation values. exe_path defaults to the path name + * of the program that calls the function. All other 0-defaulted arguments + * pass 0 into the service creation, taking NT_specified defaults. + * Returns -1 on error, 0 on success. + */ int insert (DWORD start_type = SERVICE_DEMAND_START, DWORD error_control = SERVICE_ERROR_IGNORE, const ACE_TCHAR *exe_path = 0, @@ -169,22 +182,19 @@ public: const ACE_TCHAR *dependencies = 0, const ACE_TCHAR *account_name = 0, const ACE_TCHAR *password = 0); - // Insert (create) the service in the NT Service Control Manager, - // with the given creation values. exe_path defaults to the path name - // of the program that calls the function. All other 0-defaulted arguments - // pass 0 into the service creation, taking NT_specified defaults. - // Returns -1 on error, 0 on success. + /** + * Remove the service from the NT Service Control Manager. Returns -1 on + * error, 0 on success. This just affects the SCM and registry - the + * can and will keep running fine if it is already running. + */ int remove (void); - // Remove the service from the NT Service Control Manager. Returns -1 on - // error, 0 on success. This just affects the SCM and registry - the - // can and will keep running fine if it is already running. + /// Sets the startup type for the service. Returns -1 on error, 0 on success. int startup (DWORD startup); - // Sets the startup type for the service. Returns -1 on error, 0 on success. + /// Returns the current startup type. DWORD startup (void); - // Returns the current startup type. // = Methods which control the service's execution. @@ -215,98 +225,110 @@ public: // not configured to receive the request (this is most likely to // happen in the case of pause and continue). + /** + * Start the service (must have been inserted before). wait_time is + * the time to wait for the service to reach a steady state before + * returning. If it is 0, the function waits as long as it takes + * for the service to reach the 'running' state, or gets stuck in + * some other state, or exits. If <wait_time> is supplied, it is + * updated on return to hold the service's last reported wait hint. + * svc_state can be used to receive the state which the service + * settled in. If the value is 0, the service never ran. argc/argv + * are passed to the service's ServiceMain function when it starts. + * Returns 0 for success, -1 for error. + */ int start_svc (ACE_Time_Value *wait_time = 0, DWORD *svc_state = 0, DWORD argc = 0, const ACE_TCHAR **argv = 0); - // Start the service (must have been inserted before). wait_time is - // the time to wait for the service to reach a steady state before - // returning. If it is 0, the function waits as long as it takes - // for the service to reach the 'running' state, or gets stuck in - // some other state, or exits. If <wait_time> is supplied, it is - // updated on return to hold the service's last reported wait hint. - // svc_state can be used to receive the state which the service - // settled in. If the value is 0, the service never ran. argc/argv - // are passed to the service's ServiceMain function when it starts. - // Returns 0 for success, -1 for error. + /** + * Requests the service to stop. Will wait up to <wait_time> for + * the service to actually stop. If not specified, the function + * waits until the service either stops or gets stuck in some other + * state before it stops. If <svc_state> is specified, it receives + * the last reported state of the service. Returns 0 if the request + * was made successfully, -1 if not. + */ int stop_svc (ACE_Time_Value *wait_time = 0, DWORD *svc_state = 0); - // Requests the service to stop. Will wait up to <wait_time> for - // the service to actually stop. If not specified, the function - // waits until the service either stops or gets stuck in some other - // state before it stops. If <svc_state> is specified, it receives - // the last reported state of the service. Returns 0 if the request - // was made successfully, -1 if not. + /// Pause the service. int pause_svc (ACE_Time_Value *wait_time = 0, DWORD *svc_state = 0); - // Pause the service. + /// Continue the service. int continue_svc (ACE_Time_Value *wait_time = 0, DWORD *svc_state = 0); - // Continue the service. + /** + * Get the current state for the service. If <wait_hint> is not 0, + * it receives the service's reported wait hint. Note that this + * function returns 0 on failure (not -1 as is usual in ACE). A + * zero return would (probably) only be returned if there is either + * no service with the given name in the SCM database, or the caller + * does not have sufficient rights to access the service state. The + * set of valid service state values are all greater than 0. + */ DWORD state (ACE_Time_Value *wait_hint = 0); - // Get the current state for the service. If <wait_hint> is not 0, - // it receives the service's reported wait hint. Note that this - // function returns 0 on failure (not -1 as is usual in ACE). A - // zero return would (probably) only be returned if there is either - // no service with the given name in the SCM database, or the caller - // does not have sufficient rights to access the service state. The - // set of valid service state values are all greater than 0. + /// A version of <state> that returns -1 for failure, 0 for success. + /// The DWORD pointed to by pstate receives the state value. int state (DWORD *pstate, ACE_Time_Value *wait_hint = 0); - // A version of <state> that returns -1 for failure, 0 for success. - // The DWORD pointed to by pstate receives the state value. + /** + * Test access to the object's service in the SCM. The service must + * already have been inserted in the SCM database. This function + * has no affect on the service itself. Returns 0 if the specified + * access is allowed, -1 otherwise (either the access is denied, or + * there is a problem with the service's definition - check + * ACE_OS::last_error to get the specific error indication. + */ int test_access (DWORD desired_access = SERVICE_ALL_ACCESS); - // Test access to the object's service in the SCM. The service must - // already have been inserted in the SCM database. This function - // has no affect on the service itself. Returns 0 if the specified - // access is allowed, -1 otherwise (either the access is denied, or - // there is a problem with the service's definition - check - // ACE_OS::last_error to get the specific error indication. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: int report_status (DWORD new_status, DWORD time_hint = 0); + /** + * Return the svc_sc_handle_ member. If the member is null, it + * retrieves the handle from the Service Control Manager and caches + * it. + */ SC_HANDLE svc_sc_handle (void); - // Return the svc_sc_handle_ member. If the member is null, it - // retrieves the handle from the Service Control Manager and caches - // it. + /** + * Waits for the service to reach <desired_state> or get + * (apparently) stuck before it reaches that state. Will wait at + * most <wait_time> to get to the desired state. If <wait_time> is + * 0, then the function keeps waiting until the desired state is + * reached or the service doesn't update its state any further. The + * svc_status_ class member is updated upon return. NOTE - the + * timeout doesn't currently work - it always acts like + * ACE_Time_Value::zero is passed - it checks the state once but + * doesn't wait after that. + */ void wait_for_service_state (DWORD desired_state, ACE_Time_Value *wait_time); - // Waits for the service to reach <desired_state> or get - // (apparently) stuck before it reaches that state. Will wait at - // most <wait_time> to get to the desired state. If <wait_time> is - // 0, then the function keeps waiting until the desired state is - // reached or the service doesn't update its state any further. The - // svc_status_ class member is updated upon return. NOTE - the - // timeout doesn't currently work - it always acts like - // ACE_Time_Value::zero is passed - it checks the state once but - // doesn't wait after that. + /// Called by <handle_control> when a stop/shutdown was requested. virtual void stop_requested (DWORD control_code); - // Called by <handle_control> when a stop/shutdown was requested. + /// Called by <handle_control> when a pause was requested. virtual void pause_requested (DWORD control_code); - // Called by <handle_control> when a pause was requested. + /// Called by <handle_control> when a continue was requested. virtual void continue_requested (DWORD control_code); - // Called by <handle_control> when a continue was requested. + /// Called by <handle_control> when a interrogate was requested. virtual void interrogate_requested (DWORD control_code); - // Called by <handle_control> when a interrogate was requested. protected: - DWORD start_time_; - // Estimate of init time needed - SERVICE_STATUS_HANDLE svc_handle_; - // Service handle - doesn't need close. + /// Estimate of init time needed + /// Service handle - doesn't need close. + DWORD start_time_; + SERVICE_STATUS_HANDLE svc_handle_; SERVICE_STATUS svc_status_; + /// Service's SCM handle SC_HANDLE svc_sc_handle_; - // Service's SCM handle ACE_TCHAR *name_; ACE_TCHAR *desc_; ACE_TCHAR *host_; diff --git a/ace/Name_Proxy.h b/ace/Name_Proxy.h index 604062a1cce..234f7b93c49 100644 --- a/ace/Name_Proxy.h +++ b/ace/Name_Proxy.h @@ -1,22 +1,21 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Name_Proxy.h -// -// = DESCRIPTION -// Proxy for dealing with remote server process managing NET_LOCAL -// Name_Bindings. -// -// = AUTHOR -// Gerhard Lenzer, Douglas C. Schmidt, and Prashant Jain -// -// ============================================================================ + +//============================================================================= +/** + * @file Name_Proxy.h + * + * $Id$ + * + * Proxy for dealing with remote server process managing NET_LOCAL + * Name_Bindings. + * + * + * @author Gerhard Lenzer + * @author Douglas C. Schmidt + * @author and Prashant Jain + */ +//============================================================================= + #ifndef ACE_NAME_PROXY_H #define ACE_NAME_PROXY_H @@ -34,18 +33,20 @@ #include "ace/Synch_Options.h" #include "ace/Name_Request_Reply.h" +/** + * @class ACE_Name_Proxy + * + * @brief Proxy for dealing with remote server process managing NET_LOCAL + * NameBindings. + * + * Shields applications from details of interacting with the + * ACE_Name Server. + */ class ACE_Export ACE_Name_Proxy : public ACE_Event_Handler { - // = TITLE - // Proxy for dealing with remote server process managing NET_LOCAL - // NameBindings. - // - // = DESCRIPTION - // Shields applications from details of interacting with the - // ACE_Name Server. public: + /// Default constructor. ACE_Name_Proxy (void); - // Default constructor. // = Establish a binding with the ACE_Name Server. ACE_Name_Proxy (const ACE_INET_Addr &remote_addr, // Address of ACE_Name Server. @@ -56,34 +57,34 @@ public: ACE_Synch_Options& options = ACE_Synch_Options::defaults); + /// Perform the request and wait for the reply. int request_reply (ACE_Name_Request &request); - // Perform the request and wait for the reply. + /// Perform the request. int send_request (ACE_Name_Request &request); - // Perform the request. + /// Receive the reply. int recv_reply (ACE_Name_Request &reply); - // Receive the reply. + /// Obtain underlying handle. virtual ACE_HANDLE get_handle (void) const; - // Obtain underlying handle. + /// Close down the connection to the server. virtual ~ACE_Name_Proxy (void); - // Close down the connection to the server. + /// Dump the state of the object; void dump (void) const; - // Dump the state of the object; private: + /// ACE_Connector factory used to establish connections actively. ACE_SOCK_Connector connector_; - // ACE_Connector factory used to establish connections actively. + /// Connection to ACE_Name Server peer. ACE_SOCK_Stream peer_; - // Connection to ACE_Name Server peer. + /// Pointer to ACE_Reactor (used if we are run in "reactive-mode"). ACE_Reactor *reactor_; - // Pointer to ACE_Reactor (used if we are run in "reactive-mode"). }; #include "ace/post.h" diff --git a/ace/Name_Request_Reply.h b/ace/Name_Request_Reply.h index 8e1784083c4..efbf6b3dec0 100644 --- a/ace/Name_Request_Reply.h +++ b/ace/Name_Request_Reply.h @@ -1,22 +1,21 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Name_Request_Reply.h -// -// = DESCRIPTION -// Define the format used to exchange messages between the -// ACE_Name Server and its clients. -// -// = AUTHOR -// Gerhard Lenzer, Douglas C. Schmidt, and Prashant Jain -// -// ============================================================================ + +//============================================================================= +/** + * @file Name_Request_Reply.h + * + * $Id$ + * + * Define the format used to exchange messages between the + * ACE_Name Server and its clients. + * + * + * @author Gerhard Lenzer + * @author Douglas C. Schmidt + * @author and Prashant Jain + */ +//============================================================================= + #ifndef ACE_NAME_REQUEST_REPLY_H #define ACE_NAME_REQUEST_REPLY_H @@ -30,18 +29,20 @@ #include "ace/SString.h" +/** + * @class ACE_Name_Request + * + * @brief Message format for delivering requests to the ACE_Name Server. + * + * This class is implemented to minimize data copying. In + * particular, all marshaling is done in situ... + */ class ACE_Export ACE_Name_Request { - // = TITLE - // Message format for delivering requests to the ACE_Name Server. - // - // = DESCRIPTION - // This class is implemented to minimize data copying. In - // particular, all marshaling is done in situ... public: + /// Request message types. enum Constants { - // Request message types. BIND = 01, REBIND = 02, RESOLVE = 03, @@ -56,16 +57,19 @@ public: MAX_LIST = 3, // Mask for bitwise operation used for table lookup - OP_TABLE_MASK = 07, // Mask for lookup of operation - LIST_OP_MASK = 030, // Mask for lookup of list_operation + /// Mask for lookup of operation + OP_TABLE_MASK = 07, + /// Mask for lookup of list_operation + LIST_OP_MASK = 030, - // Class-specific constant values. + /// Class-specific constant values. MAX_NAME_LENGTH = MAXPATHLEN + 1 }; + /// Default constructor. ACE_Name_Request (void); - // Default constructor. + /// Create a <ACE_Name_Request> message. ACE_Name_Request (ACE_INT32 msg_type, // Type of request. const ACE_USHORT16 name[], // const size_t name_length, @@ -74,11 +78,10 @@ public: const char type[], const size_t type_length, ACE_Time_Value *timeout = 0); // Max time willing to wait for request. - // Create a <ACE_Name_Request> message. + /// Initialize length_ in order to ensure correct byte ordering + /// before a request is sent. void init (void); - // Initialize length_ in order to ensure correct byte ordering - // before a request is sent. // = Set/get the length of the encoded/decoded message. ACE_UINT32 length (void) const; @@ -120,14 +123,14 @@ public: ACE_UINT32 type_len (void) const; void type_len (ACE_UINT32); + /// Encode the message before transmission. int encode (void *&); - // Encode the message before transmission. + /// Decode message after reception. int decode (void); - // Decode message after reception. + /// Print out the values of the message for debugging purposes. void dump (void) const; - // Print out the values of the message for debugging purposes. private: // = The 5 fields in the <Transfer> struct are transmitted to the server. @@ -167,27 +170,29 @@ private: // followed by the <type_>. }; + /// Transfer buffer. Transfer transfer_; - // Transfer buffer. + /// Pointer to the beginning of the name in this->data_. ACE_USHORT16 *name_; - // Pointer to the beginning of the name in this->data_. + /// Pointer to the beginning of the value in this->data_; ACE_USHORT16 *value_; - // Pointer to the beginning of the value in this->data_; + /// Pointer to the beginning of the type in this->data_; char *type_; - // Pointer to the beginning of the type in this->data_; }; +/** + * @class ACE_Name_Reply + * + * @brief Message format for delivering replies from the ACE_Name Server. + * + * This class is implemented to minimize data copying. In + * particular, all marshaling is done in situ... + */ class ACE_Export ACE_Name_Reply { - // = TITLE - // Message format for delivering replies from the ACE_Name Server. - // - // = DESCRIPTION - // This class is implemented to minimize data copying. In - // particular, all marshaling is done in situ... public: enum Constants { @@ -195,15 +200,15 @@ public: MAX_NAME_LENGTH = MAXPATHLEN + 1 }; + /// Default constructor. ACE_Name_Reply (void); - // Default constructor. + /// Create a <ACE_Name_Reply> message. ACE_Name_Reply (ACE_UINT32 type, ACE_UINT32 err); // Type of reply. - // Create a <ACE_Name_Reply> message. + /// Initialize length_ in order to ensure correct byte ordering + /// before a reply is sent. void init (void); - // Initialize length_ in order to ensure correct byte ordering - // before a reply is sent. // = Set/get the length of the encoded/decoded message. ACE_UINT32 length (void) const; @@ -221,14 +226,14 @@ public: ACE_UINT32 errnum (void) const; void errnum (ACE_UINT32); + /// Encode the message before transfer. int encode (void *&); - // Encode the message before transfer. + /// Decode a message after reception. int decode (void); - // Decode a message after reception. + /// Print out the values of the message for debugging purposes. void dump (void) const; - // Print out the values of the message for debugging purposes. private: // = The 3 fields in the <Transfer> struct are transmitted to the server. @@ -247,8 +252,8 @@ private: // waiting for the name). }; + /// Transfer buffer. Transfer transfer_; - // Transfer buffer. }; #include "ace/post.h" diff --git a/ace/Name_Space.h b/ace/Name_Space.h index 97e7a7b954c..58ebeb110f6 100644 --- a/ace/Name_Space.h +++ b/ace/Name_Space.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Name_Space.h -// -// = AUTHOR -// Prashant Jain -// -// ============================================================================ + +//============================================================================= +/** + * @file Name_Space.h + * + * $Id$ + * + * @author Prashant Jain + */ +//============================================================================= + #ifndef ACE_NAME_SPACE_H #define ACE_NAME_SPACE_H @@ -30,40 +27,43 @@ typedef ACE_Unbounded_Set<ACE_WString> ACE_WSTRING_SET; +/** + * @class ACE_Name_Binding + * + * @brief Maintains a mapping from name to value and type. + */ class ACE_Export ACE_Name_Binding { - // = TITLE - // Maintains a mapping from name to value and type. public: // = Initialization and termination. + /// Main constructor that initializes all the fields. ACE_Name_Binding (const ACE_WString &n, const ACE_WString &v, const char *t); - // Main constructor that initializes all the fields. + /// Default constructor. ACE_Name_Binding (void); - // Default constructor. + /// Copy constructor. ACE_Name_Binding (const ACE_Name_Binding &); - // Copy constructor. + /// Assignment operator. void operator= (const ACE_Name_Binding &); - // Assignment operator. + /// Destructor. ~ACE_Name_Binding (void); - // Destructor. + /// Test for equality. int operator == (const ACE_Name_Binding &s) const; - // Test for equality. + /// Name of the binding. ACE_WString name_; - // Name of the binding. + /// Value of the binding. ACE_WString value_; - // Value of the binding. + /// Type of the binding. char *type_; - // Type of the binding. }; typedef ACE_Unbounded_Set<ACE_Name_Binding> ACE_BINDING_SET; @@ -72,79 +72,89 @@ typedef ACE_Unbounded_Set_Iterator<ACE_Name_Binding> ACE_BINDING_ITERATOR; typedef ACE_Unbounded_Set<ACE_WString> ACE_PWSTRING_SET; typedef ACE_Unbounded_Set_Iterator<ACE_WString> ACE_PWSTRING_ITERATOR; +/** + * @class ACE_Name_Space + * + * @brief Abstract base class that provides an abstract interface to + * the database without exposing any implemenation details. + * + * Manages a Naming Service Name Space. Provides the basic + * methods -- bind, unbind, rebind, find, and listnames. + */ class ACE_Export ACE_Name_Space { - // = TITLE - // Abstract base class that provides an abstract interface to - // the database without exposing any implemenation details. - // - // = DESCRIPTION - // Manages a Naming Service Name Space. Provides the basic - // methods -- bind, unbind, rebind, find, and listnames. public: + /// virtual destructor to ensure destructors of subclasses get + /// called. virtual ~ACE_Name_Space (void); - // virtual destructor to ensure destructors of subclasses get - // called. + /// Bind a new name to a naming context (Wide character strings). virtual int bind (const ACE_WString &name_in, const ACE_WString &value_in, const char *type_in = "") = 0; - // Bind a new name to a naming context (Wide character strings). + /** + * Overwrite the value or type of an existing name in a + * ACE_Name_Space or bind a new name to the context, if it didn't + * exist yet. (Wide charcter strings interface). + */ virtual int rebind (const ACE_WString &name_in, const ACE_WString &value_in, const char *type_in = "") = 0; - // Overwrite the value or type of an existing name in a - // ACE_Name_Space or bind a new name to the context, if it didn't - // exist yet. (Wide charcter strings interface). + /// Delete a name from a ACE_Name_Space (Wide charcter strings + /// Interface). virtual int unbind (const ACE_WString &name_in) = 0; - // Delete a name from a ACE_Name_Space (Wide charcter strings - // Interface). + /// Get value and type of a given name binding (Wide chars). The + /// caller is responsible for deleting both <value_out> and <type_out>! virtual int resolve (const ACE_WString &name_in, ACE_WString &value_out, char *&type_out) = 0; - // Get value and type of a given name binding (Wide chars). The - // caller is responsible for deleting both <value_out> and <type_out>! + /// Get a set of names matching a specified pattern (wchars). Matching + /// means the names must begin with the pattern string. virtual int list_names (ACE_WSTRING_SET &set_out, const ACE_WString &pattern_in) = 0; - // Get a set of names matching a specified pattern (wchars). Matching - // means the names must begin with the pattern string. + /// Get a set of values matching a specified pattern (wchars). Matching + /// means the values must begin with the pattern string. virtual int list_values (ACE_WSTRING_SET &set_out, const ACE_WString &pattern_in) = 0; - // Get a set of values matching a specified pattern (wchars). Matching - // means the values must begin with the pattern string. + /// Get a set of types matching a specified pattern (wchars). Matching + /// means the types must begin with the pattern string. virtual int list_types (ACE_WSTRING_SET &set_out, const ACE_WString &pattern_in) = 0; - // Get a set of types matching a specified pattern (wchars). Matching - // means the types must begin with the pattern string. + /** + * Get a set of names matching a specified pattern (wchars). Matching + * means the names must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_name_entries (ACE_BINDING_SET &set, const ACE_WString &pattern) = 0; - // Get a set of names matching a specified pattern (wchars). Matching - // means the names must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of values matching a specified pattern (wchars). Matching + * means the values must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_value_entries (ACE_BINDING_SET &set, const ACE_WString &pattern) = 0; - // Get a set of values matching a specified pattern (wchars). Matching - // means the values must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of types matching a specified pattern (wchars). Matching + * means the types must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_type_entries (ACE_BINDING_SET &set, const ACE_WString &pattern) = 0; - // Get a set of types matching a specified pattern (wchars). Matching - // means the types must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /// Dump the state of the object virtual void dump (void) const = 0; - // Dump the state of the object }; #include "ace/post.h" diff --git a/ace/Naming_Context.h b/ace/Naming_Context.h index 3ad1d4dbc5a..c50a8da49c0 100644 --- a/ace/Naming_Context.h +++ b/ace/Naming_Context.h @@ -1,18 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Naming_Context.h -// -// = AUTHOR -// Gerhard Lenzer, Douglas C. Schmidt, and Prashant Jain -// -// ============================================================================ + +//============================================================================= +/** + * @file Naming_Context.h + * + * $Id$ + * + * @author Gerhard Lenzer + * @author Douglas C. Schmidt + * @author and Prashant Jain + */ +//============================================================================= + #ifndef ACE_NAMING_CONTEXT_H #define ACE_NAMING_CONTEXT_H @@ -33,231 +32,261 @@ // Forward decl class ACE_Name_Options; +/** + * @class ACE_Naming_Context + * + * @brief Maintaining accesses Name Server Databases. Allows to add + * NameBindings, change them, remove them and resolve + * NameBindings + * + * Manages a Naming Service . That represents a persistent + * string to string mapping for different scopes. The scope of a + * ACE_Naming_Context may be either local for the calling + * process (Note : A process is hereby not identified by it's + * pid, but by it's argv[0]. So different processes (in UNIX + * syntax) may access the same NameBindings), global for all + * processes running on one host or global for all processes on + * the net (that know the address of the net name server + * socket). Strings may be plain character strings or Wide + * character strings. A Name Binding consists of a name string + * (that's the key), a value string and an optional type string + * (no wide chars). + */ class ACE_Export ACE_Naming_Context : public ACE_Service_Object { - // = TITLE - // Maintaining accesses Name Server Databases. Allows to add - // NameBindings, change them, remove them and resolve - // NameBindings - // - // = DESCRIPTION - // Manages a Naming Service . That represents a persistent - // string to string mapping for different scopes. The scope of a - // ACE_Naming_Context may be either local for the calling - // process (Note : A process is hereby not identified by it's - // pid, but by it's argv[0]. So different processes (in UNIX - // syntax) may access the same NameBindings), global for all - // processes running on one host or global for all processes on - // the net (that know the address of the net name server - // socket). Strings may be plain character strings or Wide - // character strings. A Name Binding consists of a name string - // (that's the key), a value string and an optional type string - // (no wide chars). public: enum Context_Scope_Type { - PROC_LOCAL, // Name lookup is local to the process. - NODE_LOCAL, // Name lookup is local to the node (host). - NET_LOCAL // Name lookup is local to the (sub)network. + /// Name lookup is local to the process. + PROC_LOCAL, + /// Name lookup is local to the node (host). + NODE_LOCAL, + /// Name lookup is local to the (sub)network. + NET_LOCAL }; // = Initialization and termination methods. + /// "Do-nothing" constructor. ACE_Naming_Context (void); - // "Do-nothing" constructor. + /** + * Specifies the scope of this namespace, opens and memory-maps the + * associated file (if accessible) or contacts the dedicated name + * server process for NET_LOCAL namespace. Note that <light> + * specifies whether or not we want to use + * ACE_Lite_MMap_Memory_Pool. By default we use ACE_MMap_Memory_Pool. + */ ACE_Naming_Context (Context_Scope_Type scope_in, int light = 0); - // Specifies the scope of this namespace, opens and memory-maps the - // associated file (if accessible) or contacts the dedicated name - // server process for NET_LOCAL namespace. Note that <light> - // specifies whether or not we want to use - // ACE_Lite_MMap_Memory_Pool. By default we use ACE_MMap_Memory_Pool. + /** + * Specifies the scope of this namespace, opens and memory-maps the + * associated file (if accessible) or contacts the dedicated name + * server process for NET_LOCAL namespace. Note that <light> + * specifies whether or not we want to use + * ACE_Lite_MMap_Memory_Pool. By default we use ACE_MMap_Memory_Pool. + */ int open (Context_Scope_Type scope_in = ACE_Naming_Context::PROC_LOCAL, int light = 0); - // Specifies the scope of this namespace, opens and memory-maps the - // associated file (if accessible) or contacts the dedicated name - // server process for NET_LOCAL namespace. Note that <light> - // specifies whether or not we want to use - // ACE_Lite_MMap_Memory_Pool. By default we use ACE_MMap_Memory_Pool. + /// Deletes the instance of Name Space. Must be called before + /// switching name spaces. int close (void); - // Deletes the instance of Name Space. Must be called before - // switching name spaces. + /// Release all resources. Gets called by destructor and fini. int close_down (void); - // Release all resources. Gets called by destructor and fini. + /// destructor, do some cleanup :TBD: last dtor should "compress" + /// file ~ACE_Naming_Context (void); - // destructor, do some cleanup :TBD: last dtor should "compress" - // file // = Dynamic initialization hooks. + /// Initialize name options and naming context when dynamically + /// linked. virtual int init (int argc, ACE_TCHAR *argv[]); - // Initialize name options and naming context when dynamically - // linked. + /// Close down the test when dynamically unlinked. virtual int fini (void); - // Close down the test when dynamically unlinked. + /// Returns information about this context. virtual int info (char **strp, size_t length) const; - // Returns information about this context. + /// Returns the ACE_Name_Options associated with the Naming_Context ACE_Name_Options *name_options (void); - // Returns the ACE_Name_Options associated with the Naming_Context + /// Bind a new name to a naming context (Wide character strings). int bind (const ACE_WString &name_in, const ACE_WString &value_in, const char *type_in = ""); - // Bind a new name to a naming context (Wide character strings). + /// Bind a new name to a naming context ( character strings). int bind (const char *name_in, const char *value_in, const char *type_in = ""); - // Bind a new name to a naming context ( character strings). + /** + * Overwrite the value or type of an existing name in a + * ACE_Naming_Context or bind a new name to the context, if it + * didn't exist yet. (Wide charcter strings interface). + */ int rebind (const ACE_WString &name_in, const ACE_WString &value_in, const char *type_in = ""); - // Overwrite the value or type of an existing name in a - // ACE_Naming_Context or bind a new name to the context, if it - // didn't exist yet. (Wide charcter strings interface). + /** + * Overwrite the value or type of an existing name in a + * ACE_Naming_Context or bind a new name to the context, if it + * didn't exist yet. ( charcter strings interface) + */ int rebind (const char *name_in, const char *value_in, const char *type_in = ""); - // Overwrite the value or type of an existing name in a - // ACE_Naming_Context or bind a new name to the context, if it - // didn't exist yet. ( charcter strings interface) + /// Delete a name from a ACE_Naming_Context (Wide charcter strings + /// Interface). int unbind (const ACE_WString &name_in); - // Delete a name from a ACE_Naming_Context (Wide charcter strings - // Interface). + /// Delete a name from a ACE_Naming_Context (character strings + /// interface). int unbind (const char *name_in); - // Delete a name from a ACE_Naming_Context (character strings - // interface). + /// Get value and type of a given name binding (Wide chars). The + /// caller is responsible for deleting both <value_out> and <type_out>! int resolve (const ACE_WString &name_in, ACE_WString &value_out, char *&type_out); - // Get value and type of a given name binding (Wide chars). The - // caller is responsible for deleting both <value_out> and <type_out>! + /** + * Get value and type of a given name binding (Wide chars output). + * The caller is responsible for deleting both <value_out> and + * <type_out>! + */ int resolve (const char *name_in, ACE_WString &value_out, char *&type_out); - // Get value and type of a given name binding (Wide chars output). - // The caller is responsible for deleting both <value_out> and - // <type_out>! + /// Get value and type of a given name binding ( chars ). The caller + /// is responsible for deleting both <value_out> and <type_out>! int resolve (const char *name_in, char *&value_out, char *&type_out); - // Get value and type of a given name binding ( chars ). The caller - // is responsible for deleting both <value_out> and <type_out>! + /// Get a set of names matching a specified pattern (wchars). Matching + /// means the names must begin with the pattern string. int list_names (ACE_PWSTRING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of names matching a specified pattern (wchars). Matching - // means the names must begin with the pattern string. + /// Get a set of names matching a specified pattern (chars). Matching + /// means the names must begin with the pattern string. int list_names (ACE_PWSTRING_SET &set_out, const char *pattern_in); - // Get a set of names matching a specified pattern (chars). Matching - // means the names must begin with the pattern string. + /// Get a set of values matching a specified pattern (wchars). Matching + /// means the values must begin with the pattern string. int list_values (ACE_PWSTRING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of values matching a specified pattern (wchars). Matching - // means the values must begin with the pattern string. + /// Get a set of values matching a specified pattern (chars). Matching + /// means the values must begin with the pattern string. int list_values (ACE_PWSTRING_SET &set_out, const char *pattern_in); - // Get a set of values matching a specified pattern (chars). Matching - // means the values must begin with the pattern string. + /// Get a set of types matching a specified pattern (wchars). Matching + /// means the types must begin with the pattern string. int list_types (ACE_PWSTRING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of types matching a specified pattern (wchars). Matching - // means the types must begin with the pattern string. + /// Get a set of types matching a specified pattern (chars). Matching + /// means the types must begin with the pattern string. int list_types (ACE_PWSTRING_SET &set_out, const char *pattern_in); - // Get a set of types matching a specified pattern (chars). Matching - // means the types must begin with the pattern string. + /** + * Get a set of names matching a specified pattern (wchars). Matching + * means the names must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_name_entries (ACE_BINDING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of names matching a specified pattern (wchars). Matching - // means the names must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of names matching a specified pattern (wchars). Matching + * means the names must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_name_entries (ACE_BINDING_SET &set_out, const char *pattern_in); - // Get a set of names matching a specified pattern (wchars). Matching - // means the names must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of values matching a specified pattern (wchars). Matching + * means the values must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_value_entries (ACE_BINDING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of values matching a specified pattern (wchars). Matching - // means the values must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of values matching a specified pattern (wchars). Matching + * means the values must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_value_entries (ACE_BINDING_SET &set_out, const char *pattern_in); - // Get a set of values matching a specified pattern (wchars). Matching - // means the values must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of types matching a specified pattern (wchars). Matching + * means the types must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_type_entries (ACE_BINDING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of types matching a specified pattern (wchars). Matching - // means the types must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of types matching a specified pattern (wchars). Matching + * means the types must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_type_entries (ACE_BINDING_SET &set_out, const char *pattern_in); - // Get a set of types matching a specified pattern (wchars). Matching - // means the types must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /// Dump the state of the object. void dump (void); - // Dump the state of the object. private: + /// Keep track of the options such as database name etc per Naming Context ACE_Name_Options *name_options_; - // Keep track of the options such as database name etc per Naming Context + /// Name space (can be either local or remote) dynamically bound. ACE_Name_Space *name_space_; - // Name space (can be either local or remote) dynamically bound. + /// Holds the local hostname. ACE_TCHAR hostname_[MAXHOSTNAMELEN + 1]; - // Holds the local hostname. + /// Holds name of net name server. const ACE_TCHAR *netnameserver_host_; - // Holds name of net name server. + /// Holds port number of the net name server. int netnameserver_port_; - // Holds port number of the net name server. + /// 1 if we're on the same local machine as the name server, else 0. int local (void); - // 1 if we're on the same local machine as the name server, else 0. }; +/** + * @class ACE_Name_Options + * + * @brief Manages the options for the ACE Name_Server. + */ class ACE_Export ACE_Name_Options { - // = TITLE - // Manages the options for the ACE Name_Server. public: // = Initialization and termination methods. ACE_Name_Options (void); ~ACE_Name_Options (void); + /// Parse arguments. void parse_args (int argc, ACE_TCHAR *argv[]); - // Parse arguments. // = Set/Get port number void nameserver_port (int port); @@ -291,42 +320,42 @@ public: int use_registry (void); void use_registry (int); + /// Return debug status int debug (void); - // Return debug status + /// Return verbose status int verbose (void); - // Return verbose status private: + /// Extra debugging info int debugging_; - // Extra debugging info + /// Extra verbose messages int verbosity_; - // Extra verbose messages + /// Use Win32 Registry int use_registry_; - // Use Win32 Registry + /// Port to connect to nameserver process. int nameserver_port_; - // Port to connect to nameserver process. + /// Hostname of nameserver. const ACE_TCHAR *nameserver_host_; - // Hostname of nameserver. + /// Directory to hold name_bindings. ACE_TCHAR *namespace_dir_; - // Directory to hold name_bindings. + /// Name of this process. const ACE_TCHAR *process_name_; - // Name of this process. + /// Name of the database that stores the name/value/type bindings. const ACE_TCHAR *database_; - // Name of the database that stores the name/value/type bindings. + /// Base address of the underlying allocator char *base_address_; - // Base address of the underlying allocator + /// The context in which the naming database will be created. ACE_Naming_Context::Context_Scope_Type context_; - // The context in which the naming database will be created. }; ACE_FACTORY_DECLARE (ACE, ACE_Naming_Context) @@ -1,19 +1,17 @@ // -*- C++ -*- -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// OS.h -// -// = AUTHOR -// Doug Schmidt <schmidt@cs.wustl.edu>, Jesper S. M|ller -// <stophph@diku.dk>, and a cast of thousands... -// -// ============================================================================ +//============================================================================= +/** + * @file OS.h + * + * $Id$ + * + * @author Doug Schmidt <schmidt@cs.wustl.edu> + * @author Jesper S. M|ller<stophph@diku.dk> + * @author and a cast of thousands... + */ +//============================================================================= + #ifndef ACE_OS_H #define ACE_OS_H @@ -31,26 +29,26 @@ #include "ace/OS_Memory.h" #include "ace/OS_TLI.h" -// States of a recyclable object. +/// States of a recyclable object. enum ACE_Recyclable_State { + /// Idle and can be purged. ACE_RECYCLABLE_IDLE_AND_PURGABLE, - // Idle and can be purged. + /// Idle but cannot be purged. ACE_RECYCLABLE_IDLE_BUT_NOT_PURGABLE, - // Idle but cannot be purged. + /// Can be purged, but is not idle (mostly for debugging). ACE_RECYCLABLE_PURGABLE_BUT_NOT_IDLE, - // Can be purged, but is not idle (mostly for debugging). + /// Busy (i.e., cannot be recycled or purged). ACE_RECYCLABLE_BUSY, - // Busy (i.e., cannot be recycled or purged). + /// Closed. ACE_RECYCLABLE_CLOSED, - // Closed. + /// Unknown state. ACE_RECYCLABLE_UNKNOWN - // Unknown state. }; #if !defined (ACE_DEFAULT_PAGEFILE_POOL_BASE) @@ -873,28 +871,28 @@ typedef struct timespec class ACE_Export ACE_PSOS_Time_t { public: + /// default ctor: date, time, and ticks all zeroed. ACE_PSOS_Time_t (void); - // default ctor: date, time, and ticks all zeroed. + /// ctor from a timespec_t ACE_PSOS_Time_t (const timespec_t& t); - // ctor from a timespec_t + /// type cast operator (to a timespec_t) operator timespec_t (); - // type cast operator (to a timespec_t) + /// static member function to get current system time static u_long get_system_time (ACE_PSOS_Time_t& t); - // static member function to get current system time + /// static member function to set current system time static u_long set_system_time (const ACE_PSOS_Time_t& t); - // static member function to set current system time # if defined (ACE_PSOSIM) + /// static member function to initialize system time, using UNIX calls static u_long init_simulator_time (void); - // static member function to initialize system time, using UNIX calls # endif /* ACE_PSOSIM */ + /// max number of ticks supported in a single system call static const u_long max_ticks; - // max number of ticks supported in a single system call private: // = Constants for prying info out of the pSOS time encoding. static const u_long year_mask; @@ -916,14 +914,14 @@ private: static const u_long err_illtime; // time out of range static const u_long err_illticks; // ticks out of range + /// date : year in bits 31-16, month in bits 15-8, day in bits 7-0 u_long date_; - // date : year in bits 31-16, month in bits 15-8, day in bits 7-0 + /// time : hour in bits 31-16, minutes in bits 15-8, seconds in bits 7-0 u_long time_; - // time : hour in bits 31-16, minutes in bits 15-8, seconds in bits 7-0 + /// ticks: number of system clock ticks (KC_TICKS2SEC-1 max) u_long ticks_; - // ticks: number of system clock ticks (KC_TICKS2SEC-1 max) } ; #endif /* ACE_PSOS_HAS_TIME */ @@ -1054,201 +1052,207 @@ ACE_Export ACE_Time_Value operator - (const ACE_Time_Value &tv1, // ------------------------------------------------------------------- +/** + * @class ACE_Time_Value + * + * @brief Operations on "timeval" structures. + * + * This class centralizes all the time related processing in + * ACE. These timers are typically used in conjunction with OS + * mechanisms like <select>, <poll>, or <cond_timedwait>. + * <ACE_Time_Value> makes the use of these mechanisms portable + * across OS platforms, + */ class ACE_Export ACE_Time_Value { - // = TITLE - // Operations on "timeval" structures. - // - // = DESCRIPTION - // This class centralizes all the time related processing in - // ACE. These timers are typically used in conjunction with OS - // mechanisms like <select>, <poll>, or <cond_timedwait>. - // <ACE_Time_Value> makes the use of these mechanisms portable - // across OS platforms, public: // = Useful constants. + /// Constant "0". static const ACE_Time_Value zero; - // Constant "0". + /** + * Constant for maximum time representable. Note that this time is + * not intended for use with <select> or other calls that may have + * *their own* implementation-specific maximum time representations. + * Its primary use is in time computations such as those used by the + * dynamic subpriority strategies in the <ACE_Dynamic_Message_Queue> + * class. + */ static const ACE_Time_Value max_time; - // Constant for maximum time representable. Note that this time is - // not intended for use with <select> or other calls that may have - // *their own* implementation-specific maximum time representations. - // Its primary use is in time computations such as those used by the - // dynamic subpriority strategies in the <ACE_Dynamic_Message_Queue> - // class. // = Initialization methods. + /// Default Constructor. ACE_Time_Value (void); - // Default Constructor. + /// Constructor. ACE_Time_Value (long sec, long usec = 0); - // Constructor. // = Methods for converting to/from various time formats. + /// Construct the <ACE_Time_Value> from a <timeval>. ACE_Time_Value (const struct timeval &t); - // Construct the <ACE_Time_Value> from a <timeval>. + /// Initializes the <ACE_Time_Value> object from a <timespec_t>. ACE_Time_Value (const timespec_t &t); - // Initializes the <ACE_Time_Value> object from a <timespec_t>. + /// Copy constructor. ACE_Time_Value (const ACE_Time_Value &tv); - // Copy constructor. # if defined (ACE_WIN32) + /// Initializes the ACE_Time_Value object from a Win32 FILETIME ACE_Time_Value (const FILETIME &ft); - // Initializes the ACE_Time_Value object from a Win32 FILETIME # endif /* ACE_WIN32 */ + /// Construct a <Time_Value> from two <long>s. void set (long sec, long usec); - // Construct a <Time_Value> from two <long>s. + /// Construct a <Time_Value> from a <double>, which is assumed to be + /// in second format, with any remainder treated as microseconds. void set (double d); - // Construct a <Time_Value> from a <double>, which is assumed to be - // in second format, with any remainder treated as microseconds. + /// Construct a <Time_Value> from a <timeval>. void set (const timeval &t); - // Construct a <Time_Value> from a <timeval>. + /// Initializes the <Time_Value> object from a <timespec_t>. void set (const timespec_t &t); - // Initializes the <Time_Value> object from a <timespec_t>. # if defined (ACE_WIN32) + /// Initializes the <Time_Value> object from a <timespec_t>. void set (const FILETIME &ft); - // Initializes the <Time_Value> object from a <timespec_t>. # endif /* ACE_WIN32 */ + /// Converts from <Time_Value> format into milli-seconds format. long msec (void) const; - // Converts from <Time_Value> format into milli-seconds format. + /// Converts from milli-seconds format into <Time_Value> format. void msec (long); - // Converts from milli-seconds format into <Time_Value> format. + /// Returns the value of the object as a <timespec_t>. operator timespec_t () const; - // Returns the value of the object as a <timespec_t>. + /// Returns the value of the object as a <timeval>. operator timeval () const; - // Returns the value of the object as a <timeval>. + /// Returns a pointer to the object as a <timeval>. operator const timeval *() const; - // Returns a pointer to the object as a <timeval>. # if defined (ACE_WIN32) + /// Returns the value of the object as a Win32 FILETIME. operator FILETIME () const; - // Returns the value of the object as a Win32 FILETIME. # endif /* ACE_WIN32 */ // = The following are accessor/mutator methods. + /// Get seconds. long sec (void) const; - // Get seconds. + /// Set seconds. void sec (long sec); - // Set seconds. + /// Get microseconds. long usec (void) const; - // Get microseconds. + /// Set microseconds. void usec (long usec); - // Set microseconds. // = The following arithmetic methods operate on <Time_Value>s. + /// Add <tv> to this. void operator += (const ACE_Time_Value &tv); - // Add <tv> to this. + /// Subtract <tv> to this. void operator -= (const ACE_Time_Value &tv); - // Subtract <tv> to this. + /// Multiply the time value by the <d> factor, which must be >= 0. ACE_Time_Value &operator *= (double d); - // Multiply the time value by the <d> factor, which must be >= 0. + /// Adds two ACE_Time_Value objects together, returns the sum. friend ACE_Export ACE_Time_Value operator + (const ACE_Time_Value &tv1, const ACE_Time_Value &tv2); - // Adds two ACE_Time_Value objects together, returns the sum. + /// Subtracts two ACE_Time_Value objects, returns the difference. friend ACE_Export ACE_Time_Value operator - (const ACE_Time_Value &tv1, const ACE_Time_Value &tv2); - // Subtracts two ACE_Time_Value objects, returns the difference. + /// True if tv1 < tv2. friend ACE_Export int operator < (const ACE_Time_Value &tv1, const ACE_Time_Value &tv2); - // True if tv1 < tv2. + /// True if tv1 > tv2. friend ACE_Export int operator > (const ACE_Time_Value &tv1, const ACE_Time_Value &tv2); - // True if tv1 > tv2. + /// True if tv1 <= tv2. friend ACE_Export int operator <= (const ACE_Time_Value &tv1, const ACE_Time_Value &tv2); - // True if tv1 <= tv2. + /// True if tv1 >= tv2. friend ACE_Export int operator >= (const ACE_Time_Value &tv1, const ACE_Time_Value &tv2); - // True if tv1 >= tv2. + /// True if tv1 == tv2. friend ACE_Export int operator == (const ACE_Time_Value &tv1, const ACE_Time_Value &tv2); - // True if tv1 == tv2. + /// True if tv1 != tv2. friend ACE_Export int operator != (const ACE_Time_Value &tv1, const ACE_Time_Value &tv2); - // True if tv1 != tv2. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. # if defined (ACE_WIN32) + /// Const time difference between FILETIME and POSIX time. static const DWORDLONG FILETIME_to_timval_skew; - // Const time difference between FILETIME and POSIX time. # endif /* ACE_WIN32 */ private: + /// Put the timevalue into a canonical form. void normalize (void); - // Put the timevalue into a canonical form. + /// Store the values as a <timeval>. timeval tv_; - // Store the values as a <timeval>. }; +/** + * @class ACE_Countdown_Time + * + * @brief Keeps track of the amount of elapsed time. + * + * This class has a side-effect on the <max_wait_time> -- every + * time the <stop> method is called the <max_wait_time> is + * updated. + */ class ACE_Export ACE_Countdown_Time { - // = TITLE - // Keeps track of the amount of elapsed time. - // - // = DESCRIPTION - // This class has a side-effect on the <max_wait_time> -- every - // time the <stop> method is called the <max_wait_time> is - // updated. public: // = Initialization and termination methods. + /// Cache the <max_wait_time> and call <start>. ACE_Countdown_Time (ACE_Time_Value *max_wait_time); - // Cache the <max_wait_time> and call <start>. + /// Call <stop>. ~ACE_Countdown_Time (void); - // Call <stop>. + /// Cache the current time and enter a start state. int start (void); - // Cache the current time and enter a start state. + /// Subtract the elapsed time from max_wait_time_ and enter a stopped + /// state. int stop (void); - // Subtract the elapsed time from max_wait_time_ and enter a stopped - // state. + /// Calls stop and then start. max_wait_time_ is modified by the + /// call to stop. int update (void); - // Calls stop and then start. max_wait_time_ is modified by the - // call to stop. private: ACE_Time_Value *max_wait_time_; // Maximum time we were willing to wait. + /// Beginning of the start time. ACE_Time_Value start_time_; - // Beginning of the start time. + /// Keeps track of whether we've already been stopped. int stopped_; - // Keeps track of whether we've already been stopped. }; # if defined (ACE_HAS_USING_KEYWORD) @@ -2011,25 +2015,28 @@ typedef pthread_mutex_t ACE_thread_mutex_t; # if !defined (ACE_HAS_STHREADS) # if !defined (ACE_HAS_POSIX_SEM) +/** + * @class ACE_sema_t + * + * @brief This is used to implement semaphores for platforms that support + * POSIX pthreads, but do *not* support POSIX semaphores, i.e., + * it's a different type than the POSIX <sem_t>. + */ class ACE_Export ACE_sema_t { - // = TITLE - // This is used to implement semaphores for platforms that support - // POSIX pthreads, but do *not* support POSIX semaphores, i.e., - // it's a different type than the POSIX <sem_t>. friend class ACE_OS; protected: + /// Serialize access to internal state. ACE_mutex_t lock_; - // Serialize access to internal state. + /// Block until there are no waiters. ACE_cond_t count_nonzero_; - // Block until there are no waiters. + /// Count of the semaphore. u_long count_; - // Count of the semaphore. + /// Number of threads that have called <ACE_OS::sema_wait>. u_long waiters_; - // Number of threads that have called <ACE_OS::sema_wait>. }; # endif /* !ACE_HAS_POSIX_SEM */ @@ -2268,19 +2275,22 @@ typedef HANDLE ACE_event_t; # if !defined (ACE_USES_WINCE_SEMA_SIMULATION) typedef HANDLE ACE_sema_t; # else +/** + * @class ACE_sema_t + * + * @brief Semaphore simulation for Windows CE. + */ class ACE_Export ACE_sema_t { - // = TITLE - // Semaphore simulation for Windows CE. public: + /// Serializes access to <count_>. ACE_thread_mutex_t lock_; - // Serializes access to <count_>. + /// This event is signaled whenever the count becomes non-zero. ACE_event_t count_nonzero_; - // This event is signaled whenever the count becomes non-zero. + /// Current count of the semaphore. u_int count_; - // Current count of the semaphore. }; # endif /* ACE_USES_WINCE_SEMA_SIMULATION */ @@ -2307,48 +2317,54 @@ public: # endif /* ACE_HAS_PTHREADS / STHREADS / PSOS / VXWORKS / WTHREADS */ # if defined (ACE_LACKS_COND_T) +/** + * @class ACE_cond_t + * + * @brief This structure is used to implement condition variables on + * platforms that lack it natively, such as VxWorks, pSoS, and + * Win32. + * + * At the current time, this stuff only works for threads + * within the same process. + */ class ACE_Export ACE_cond_t { - // = TITLE - // This structure is used to implement condition variables on - // platforms that lack it natively, such as VxWorks, pSoS, and - // Win32. - // - // = DESCRIPTION - // At the current time, this stuff only works for threads - // within the same process. public: friend class ACE_OS; + /// Returns the number of waiters. long waiters (void) const; - // Returns the number of waiters. protected: + /// Number of waiting threads. long waiters_; - // Number of waiting threads. + /// Serialize access to the waiters count. ACE_thread_mutex_t waiters_lock_; - // Serialize access to the waiters count. + /// Queue up threads waiting for the condition to become signaled. ACE_sema_t sema_; - // Queue up threads waiting for the condition to become signaled. # if defined (VXWORKS) || defined (ACE_PSOS) + /** + * A semaphore used by the broadcast/signal thread to wait for all + * the waiting thread(s) to wake up and be released from the + * semaphore. + */ ACE_sema_t waiters_done_; - // A semaphore used by the broadcast/signal thread to wait for all - // the waiting thread(s) to wake up and be released from the - // semaphore. # elif defined (ACE_WIN32) + /** + * An auto reset event used by the broadcast/signal thread to wait + * for the waiting thread(s) to wake up and get a chance at the + * semaphore. + */ HANDLE waiters_done_; - // An auto reset event used by the broadcast/signal thread to wait - // for the waiting thread(s) to wake up and get a chance at the - // semaphore. # else # error "Please implement this feature or check your config.h file!" # endif /* VXWORKS || ACE_PSOS */ + /// Keeps track of whether we were broadcasting or just signaling. size_t was_broadcast_; - // Keeps track of whether we were broadcasting or just signaling. }; struct ACE_Export ACE_condattr_t @@ -2367,15 +2383,18 @@ struct ACE_Export ACE_mutexattr_t # endif /* ACE_LACKS_COND_T */ # if defined (ACE_LACKS_RWLOCK_T) && !defined (ACE_HAS_PTHREADS_UNIX98_EXT) + +/** + * @class ACE_rwlock_t + * + * @brief This is used to implement readers/writer locks on NT, + * VxWorks, and POSIX pthreads. + * + * At the current time, this stuff only works for threads + * within the same process. + */ struct ACE_Export ACE_rwlock_t { - // = TITLE - // This is used to implement readers/writer locks on NT, - // VxWorks, and POSIX pthreads. - // - // = DESCRIPTION - // At the current time, this stuff only works for threads - // within the same process. protected: friend class ACE_OS; @@ -2443,29 +2462,31 @@ typedef rwlock_t ACE_rwlock_t; #if defined (ACE_HAS_RECURSIVE_MUTEXES) typedef ACE_thread_mutex_t ACE_recursive_thread_mutex_t; #else +/** + * @class ACE_recursive_thread_mutex_t + * + * @brief Implement a thin C++ wrapper that allows nested acquisition + * and release of a mutex that occurs in the same thread. + * + * This implementation is based on an algorithm sketched by Dave + * Butenhof <butenhof@zko.dec.com>. Naturally, I take the + * credit for any mistakes ;-) + */ class ACE_recursive_thread_mutex_t { - // = TITLE - // Implement a thin C++ wrapper that allows nested acquisition - // and release of a mutex that occurs in the same thread. - // - // = DESCRIPTION - // This implementation is based on an algorithm sketched by Dave - // Butenhof <butenhof@zko.dec.com>. Naturally, I take the - // credit for any mistakes ;-) public: + /// Guards the state of the nesting level and thread id. ACE_thread_mutex_t nesting_mutex_; - // Guards the state of the nesting level and thread id. + /// This condition variable suspends other waiting threads until the + /// mutex is available. ACE_cond_t lock_available_; - // This condition variable suspends other waiting threads until the - // mutex is available. + /// Current nesting level of the recursion. int nesting_level_; - // Current nesting level of the recursion. + /// Current owner of the lock. ACE_thread_t owner_id_; - // Current owner of the lock. }; #endif /* ACE_WIN32 */ @@ -2567,20 +2588,20 @@ class ACE_Export ACE_event_t protected: + /// Protect critical section. ACE_mutex_t lock_; - // Protect critical section. + /// Keeps track of waiters. ACE_cond_t condition_; - // Keeps track of waiters. + /// Specifies if this is an auto- or manual-reset event. int manual_reset_; - // Specifies if this is an auto- or manual-reset event. + /// "True" if signaled. int is_signaled_; - // "True" if signaled. + /// Number of waiting threads. u_long waiting_threads_; - // Number of waiting threads. }; # endif /* ACE_PSOS */ @@ -3315,20 +3336,20 @@ class ACE_Export ACE_event_t { friend class ACE_OS; protected: + /// Protect critical section. ACE_mutex_t lock_; - // Protect critical section. + /// Keeps track of waiters. ACE_cond_t condition_; - // Keeps track of waiters. + /// Specifies if this is an auto- or manual-reset event. int manual_reset_; - // Specifies if this is an auto- or manual-reset event. + /// "True" if signaled. int is_signaled_; - // "True" if signaled. + /// Number of waiting threads. u_long waiting_threads_; - // Number of waiting threads. }; struct ACE_OVERLAPPED @@ -4273,10 +4294,13 @@ typedef int ucontext_t; # include /**/ <tli/timod.h> # endif /* ACE_HAS_TIMOD_H */ +/** + * @class ACE_Thread_ID + * + * @brief Defines a platform-independent thread ID. + */ class ACE_Export ACE_Thread_ID { - // = TITLE - // Defines a platform-independent thread ID. public: // = Initialization method. ACE_Thread_ID (ACE_thread_t, ACE_hthread_t); @@ -4295,11 +4319,11 @@ public: int operator!= (const ACE_Thread_ID &) const; private: + /// Identify the thread. ACE_thread_t thread_id_; - // Identify the thread. + /// Handle to the thread (typically used to "wait" on Win32). ACE_hthread_t thread_handle_; - // Handle to the thread (typically used to "wait" on Win32). }; // Type of the extended signal handler. @@ -4352,17 +4376,20 @@ struct strbuf }; # endif /* ACE_HAS_STRBUF_T */ +/** + * @class ACE_Str_Buf + * + * @brief Simple wrapper for STREAM pipes strbuf. + */ class ACE_Export ACE_Str_Buf : public strbuf { - // = TITLE - // Simple wrapper for STREAM pipes strbuf. public: // = Initialization method + /// Constructor. ACE_Str_Buf (void *b = 0, int l = 0, int max = 0); - // Constructor. + /// Constructor. ACE_Str_Buf (strbuf &); - // Constructor. }; # if defined (ACE_HAS_BROKEN_BITSHIFT) @@ -4396,81 +4423,91 @@ int ACE_SEH_Default_Exception_Selector (void *); int ACE_SEH_Default_Exception_Handler (void *); # endif /* ACE_WIN32 */ +/** + * @class ACE_Cleanup + * + * @brief Base class for objects that are cleaned by ACE_Object_Manager. + */ class ACE_Export ACE_Cleanup { - // = TITLE - // Base class for objects that are cleaned by ACE_Object_Manager. public: + /// No-op constructor. ACE_Cleanup (void); - // No-op constructor. + /// Destructor. virtual ~ACE_Cleanup (void); - // Destructor. + /// Cleanup method that, by default, simply deletes itself. virtual void cleanup (void *param = 0); - // Cleanup method that, by default, simply deletes itself. }; // Adapter for cleanup, used by ACE_Object_Manager. extern "C" ACE_Export void ace_cleanup_destroyer (ACE_Cleanup *, void *param = 0); +/** + * @class ACE_Cleanup_Info + * + * @brief Hold cleanup information for thread/process + */ class ACE_Export ACE_Cleanup_Info { - // = TITLE - // Hold cleanup information for thread/process public: + /// Default constructor. ACE_Cleanup_Info (void); - // Default constructor. + /// Equality operator. int operator== (const ACE_Cleanup_Info &o) const; - // Equality operator. + /// Inequality operator. int operator!= (const ACE_Cleanup_Info &o) const; - // Inequality operator. + /// Point to object that gets passed into the <cleanup_hook_>. void *object_; - // Point to object that gets passed into the <cleanup_hook_>. + /// Cleanup hook that gets called back. ACE_CLEANUP_FUNC cleanup_hook_; - // Cleanup hook that gets called back. + /// Parameter passed to the <cleanup_hook_>. void *param_; - // Parameter passed to the <cleanup_hook_>. }; class ACE_Cleanup_Info_Node; +/** + * @class ACE_OS_Exit_Info + * + * @brief Hold Object Manager cleanup (exit) information. + * + * For internal use by the ACE library, only. + */ class ACE_Export ACE_OS_Exit_Info { - // = TITLE - // Hold Object Manager cleanup (exit) information. - // - // = DESCRIPTION - // For internal use by the ACE library, only. public: + /// Default constructor. ACE_OS_Exit_Info (void); - // Default constructor. + /// Destructor. ~ACE_OS_Exit_Info (void); - // Destructor. + /// Use to register a cleanup hook. int at_exit_i (void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param); - // Use to register a cleanup hook. + /// Look for a registered cleanup hook object. Returns 1 if already + /// registered, 0 if not. int find (void *object); - // Look for a registered cleanup hook object. Returns 1 if already - // registered, 0 if not. + /// Call all registered cleanup hooks, in reverse order of + /// registration. void call_hooks (); - // Call all registered cleanup hooks, in reverse order of - // registration. private: + /** + * Keeps track of all registered objects. The last node is only + * used to terminate the list (it doesn't contain a valid + * ACE_Cleanup_Info). + */ ACE_Cleanup_Info_Node *registered_objects_; - // Keeps track of all registered objects. The last node is only - // used to terminate the list (it doesn't contain a valid - // ACE_Cleanup_Info). }; class ACE_Base_Thread_Adapter; @@ -4587,19 +4624,23 @@ struct ACE_Protocol_Info #endif /* ACE_HAS_WINSOCK2 && ACE_HAS_WINSOCK2 != 0 */ +/** + * @class ACE_Flow_Spec + * + * @brief Wrapper class that defines the flow spec QoS information, + * which is used by IntServ (RSVP) and DiffServ. + */ class ACE_Export ACE_Flow_Spec #if defined (ACE_HAS_WINSOCK2) && (ACE_HAS_WINSOCK2 != 0) : public FLOWSPEC #endif /* ACE_HAS_WINSOCK2 */ { - // = TITLE - // Wrapper class that defines the flow spec QoS information, which - // is used by IntServ (RSVP) and DiffServ. public: // = Initialization methods. + /// Default constructor. ACE_Flow_Spec (void); - // Default constructor. + /// Constructor that initializes all the fields. ACE_Flow_Spec (u_long token_rate, u_long token_bucket_size, u_long peak_bandwidth, @@ -4610,7 +4651,6 @@ public: u_long minimum_policed_size, int ttl, int priority); - // Constructor that initializes all the fields. // = Get/set the token rate in bytes/sec. u_long token_rate (void) const; @@ -4670,15 +4710,17 @@ private: defined (ACE_HAS_WINSOCK2_GQOS) */ }; -#if defined (ACE_HAS_WINSOCK2) && (ACE_HAS_WINSOCK2 != 0) -class ACE_Export ACE_QoS : public QOS -#else +/** + * @class ACE_QoS + * + * @brief Wrapper class that holds the sender and receiver flow spec + * information, which is used by IntServ (RSVP) and DiffServ. + */ class ACE_Export ACE_QoS +#if defined (ACE_HAS_WINSOCK2) && (ACE_HAS_WINSOCK2 != 0) + : public QOS #endif /* ACE_HAS_WINSOCK2 */ { - // = TITLE - // Wrapper class that holds the sender and receiver flow spec - // information, which is used by IntServ (RSVP) and DiffServ. public: // = Get/set the flow spec for data sending. ACE_Flow_Spec sending_flowspec (void) const; @@ -4702,26 +4744,31 @@ private: }; +/** + * @class ACE_QoS_Params + * + * @brief Wrapper class that simplifies the information passed to the QoS + * enabled <ACE_OS::connect> and <ACE_OS::join_leaf> methods. + */ class ACE_Export ACE_QoS_Params { - // = TITLE - // Wrapper class that simplifies the information passed to the QoS - // enabled <ACE_OS::connect> and <ACE_OS::join_leaf> methods. public: + /** + * Initialize the data members. The <caller_data> is a pointer to + * the user data that is to be transferred to the peer during + * connection establishment. The <callee_data> is a pointer to the + * user data that is to be transferred back from the peer during + * connection establishment. The_<socket_qos> is a pointer to the + * flow specifications for the socket, one for each direction. The + * <group_socket_qos> is a pointer to the flow speicfications for + * the socket group, if applicable. The_<flags> indicate if we're a + * sender, receiver, or both. + */ ACE_QoS_Params (iovec *caller_data = 0, iovec *callee_data = 0, ACE_QoS *socket_qos = 0, ACE_QoS *group_socket_qos = 0, u_long flags = 0); - // Initialize the data members. The <caller_data> is a pointer to - // the user data that is to be transferred to the peer during - // connection establishment. The <callee_data> is a pointer to the - // user data that is to be transferred back from the peer during - // connection establishment. The_<socket_qos> is a pointer to the - // flow specifications for the socket, one for each direction. The - // <group_socket_qos> is a pointer to the flow speicfications for - // the socket group, if applicable. The_<flags> indicate if we're a - // sender, receiver, or both. // = Get/set caller data. iovec *caller_data (void) const; @@ -4744,24 +4791,24 @@ public: void flags (u_long); private: + /// A pointer to the user data that is to be transferred to the peer + /// during connection establishment. iovec *caller_data_; - // A pointer to the user data that is to be transferred to the peer - // during connection establishment. + /// A pointer to the user data that is to be transferred back from + /// the peer during connection establishment. iovec *callee_data_; - // A pointer to the user data that is to be transferred back from - // the peer during connection establishment. + /// A pointer to the flow speicfications for the socket, one for each + /// direction. ACE_QoS *socket_qos_; - // A pointer to the flow speicfications for the socket, one for each - // direction. + /// A pointer to the flow speicfications for the socket group, if + /// applicable. ACE_QoS *group_socket_qos_; - // A pointer to the flow speicfications for the socket group, if - // applicable. + /// Flags that indicate if we're a sender, receiver, or both. u_long flags_; - // Flags that indicate if we're a sender, receiver, or both. }; // Callback function that's used by the QoS-enabled <ACE_OS::accept> @@ -4786,22 +4833,27 @@ typedef void (*ACE_OVERLAPPED_COMPLETION_FUNC) (u_long error, u_long flags); #endif /* ACE_HAS_WINSOCK2 != 0 */ +/** + * @class ACE_Accept_QoS_Params + * + * @brief Wrapper class that simplifies the information passed to the QoS + * enabled <ACE_OS::accept> method. + */ class ACE_Export ACE_Accept_QoS_Params { - // = TITLE - // Wrapper class that simplifies the information passed to the QoS - // enabled <ACE_OS::accept> method. public: + /** + * Initialize the data members. The <qos_condition_callback> is the + * address of an optional, application-supplied condition function + * that will make an accept/reject decision based on the caller + * information pass in as parameters, and optionally create or join + * a socket group by assinging an appropriate value to the result + * parameter <g> of this function. The <callback_data> data is + * passed back to the application as a condition function parameter, + * i.e., it is an Asynchronous Completion Token (ACT). + */ ACE_Accept_QoS_Params (ACE_QOS_CONDITION_FUNC qos_condition_callback = 0, u_long callback_data = 0); - // Initialize the data members. The <qos_condition_callback> is the - // address of an optional, application-supplied condition function - // that will make an accept/reject decision based on the caller - // information pass in as parameters, and optionally create or join - // a socket group by assinging an appropriate value to the result - // parameter <g> of this function. The <callback_data> data is - // passed back to the application as a condition function parameter, - // i.e., it is an Asynchronous Completion Token (ACT). // = Get/set QoS condition callback. ACE_QOS_CONDITION_FUNC qos_condition_callback (void) const; @@ -4812,40 +4864,46 @@ public: void callback_data (u_long cd); private: + /** + * This is the address of an optional, application-supplied + * condition function that will make an accept/reject decision based + * on the caller information pass in as parameters, and optionally + * create or join a socket group by assinging an appropriate value + * to the result parameter <g> of this function. + */ ACE_QOS_CONDITION_FUNC qos_condition_callback_; - // This is the address of an optional, application-supplied - // condition function that will make an accept/reject decision based - // on the caller information pass in as parameters, and optionally - // create or join a socket group by assinging an appropriate value - // to the result parameter <g> of this function. + /** + * This data is passed back to the application as a condition + * function parameter, i.e., it is an Asynchronous Completion Token + * (ACT). + */ u_long callback_data_; - // This data is passed back to the application as a condition - // function parameter, i.e., it is an Asynchronous Completion Token - // (ACT). }; +/** + * @class ACE_OS + * + * @brief This class defines an OS independent programming API that + * shields developers from nonportable aspects of writing + * efficient system programs on Win32, POSIX and other versions + * of UNIX, and various real-time operating systems. + * + * This class encapsulates the differences between various OS + * platforms. When porting ACE to a new platform, this class is + * the place to focus on. Once this file is ported to a new + * platform, pretty much everything else comes for "free." See + * <www.cs.wustl.edu/~schmidt/ACE_wrappers/etc/ACE-porting.html> + * for instructions on porting ACE. Please see the README file + * in this directory for complete information on the meaning of + * the various macros. + */ class ACE_Export ACE_OS : public ACE_OS_Dirent, public ACE_OS_String, public ACE_OS_Memory, public ACE_OS_TLI { - // = TITLE - // This class defines an OS independent programming API that - // shields developers from nonportable aspects of writing - // efficient system programs on Win32, POSIX and other versions - // of UNIX, and various real-time operating systems. - // - // = DESCRIPTION - // This class encapsulates the differences between various OS - // platforms. When porting ACE to a new platform, this class is - // the place to focus on. Once this file is ported to a new - // platform, pretty much everything else comes for "free." See - // <www.cs.wustl.edu/~schmidt/ACE_wrappers/etc/ACE-porting.html> - // for instructions on porting ACE. Please see the README file - // in this directory for complete information on the meaning of - // the various macros. ACE_CLASS_IS_NAMESPACE (ACE_OS); public: @@ -4869,13 +4927,16 @@ public: }; # endif /* ! CHORUS */ + /** + * @class ace_flock_t + * + * @brief OS file locking structure. + */ class ace_flock_t { - // = TITLE - // OS file locking structure. public: + /// Dump state of the object. void dump (void) const; - // Dump state of the object. # if defined (ACE_WIN32) ACE_OVERLAPPED overlapped_; @@ -4883,16 +4944,16 @@ public: struct flock lock_; # endif /* ACE_WIN32 */ + /// Name of this filelock. const ACE_TCHAR *lockname_; - // Name of this filelock. + /// Handle to the underlying file. ACE_HANDLE handle_; - // Handle to the underlying file. # if defined (CHORUS) + /// This is the mutex that's stored in shared memory. It can only + /// be destroyed by the actor that initialized it. ACE_mutex_t *process_lock_; - // This is the mutex that's stored in shared memory. It can only - // be destroyed by the actor that initialized it. # endif /* CHORUS */ }; @@ -4901,8 +4962,8 @@ public: static LPSECURITY_ATTRIBUTES default_win32_security_attributes (LPSECURITY_ATTRIBUTES); // = Win32 OS version determination function. + /// Return the win32 OSVERSIONINFO structure. static const OSVERSIONINFO &get_win32_versioninfo (void); - // Return the win32 OSVERSIONINFO structure. # endif /* ACE_WIN32 */ @@ -4913,11 +4974,11 @@ public: static int atoi (const wchar_t *s); # endif /* ACE_HAS_WCHAR */ + /// This method computes the largest integral value not greater than x. static double floor (double x); - // This method computes the largest integral value not greater than x. + /// This method computes the smallest integral value not less than x. static double ceil (double x); - // This method computes the smallest integral value not less than x. static char *getenv (const char *symbol); # if defined (ACE_HAS_WCHAR) && defined (ACE_WIN32) @@ -4940,7 +5001,7 @@ public: int substitute_env_args = 1); static long sysconf (int); - // = A set of wrappers for condition variables. + //@{ @name A set of wrappers for condition variables. static int condattr_init (ACE_condattr_t &attributes, int type = ACE_DEFAULT_SYNCH_TYPE); static int condattr_destroy (ACE_condattr_t &attributes); @@ -4967,8 +5028,9 @@ public: static int cond_wait (ACE_cond_t *cv, ACE_thread_mutex_t *m); # endif /* ACE_WIN32 && ACE_HAS_WTHREADS */ + //@} - // = A set of wrappers for determining config info. + //@{ @name Wrappers to obtain the current user id static char *cuserid (char *user, size_t maxlen = ACE_MAX_USERID); @@ -4976,7 +5038,9 @@ public: static wchar_t *cuserid (wchar_t *user, size_t maxlen = ACE_MAX_USERID); # endif /* ACE_HAS_WCHAR */ + //@} + //@{ @name Wrappers to obtain configuration info static int uname (struct utsname *name); static long sysinfo (int cmd, char *buf, @@ -4989,8 +5053,9 @@ public: static int hostname (wchar_t *name, size_t maxnamelen); #endif /* ACE_HAS_WCHAR */ + //@} - // = A set of wrappers for explicit dynamic linking. + //@{ @name A set of wrappers for explicit dynamic linking. static int dlclose (ACE_SHLIB_HANDLE handle); static ACE_TCHAR *dlerror (void); @@ -4998,8 +5063,9 @@ public: int mode = ACE_DEFAULT_SHLIB_MODE); static void *dlsym (ACE_SHLIB_HANDLE handle, const ACE_TCHAR *symbol); + //@} - // = A set of wrappers for stdio file operations. + //{@ @name A set of wrappers for stdio file operations. static int last_error (void); static void last_error (int); static int set_errno_to_last_error (void); @@ -5067,8 +5133,9 @@ public: size_t nitems, FILE *fp); static void rewind (FILE *fp); + //@} - // = Wrappers for searching and sorting. + //@{ @name Wrappers for searching and sorting. static void *bsearch (const void *key, const void *base, size_t nel, @@ -5078,8 +5145,9 @@ public: size_t nel, size_t width, ACE_COMPARE_FUNC); + //@} - // = A set of wrappers for file locks. + //@{ @name A set of wrappers for file locks. static int flock_init (ACE_OS::ace_flock_t *lock, int flags = 0, const ACE_TCHAR *name = 0, @@ -5112,8 +5180,9 @@ public: short whence = 0, off_t start = 0, off_t len = 0); + //@} - // = A set of wrappers for low-level process operations. + //@{ @name A set of wrappers for low-level process operations. static int atexit (ACE_EXIT_HOOK func); static int execl (const char *path, const char *arg0, ...); @@ -5132,10 +5201,13 @@ public: static void exit (int status = 0); static void abort (void); static pid_t fork (void); + + //@{ + /// Forks and exec's a process in a manner that works on Solaris and + /// NT. argv[0] must be the full path name to the executable. static pid_t fork (const ACE_TCHAR *program_name); static pid_t fork_exec (ACE_TCHAR *argv[]); - // Forks and exec's a process in a manner that works on Solaris and - // NT. argv[0] must be the full path name to the executable. + //@} static int getpagesize (void); static int allocation_granularity (void); @@ -5152,32 +5224,40 @@ public: static int setreuid (uid_t ruid, uid_t euid); static int setregid (gid_t rgid, gid_t egid); static int system (const ACE_TCHAR *s); + //@} + + /** + * Calls <::waitpid> on UNIX/POSIX platforms and <::await> on + * Chorus. Does not work on Vxworks, or pSoS. + * On Win32, <pid> is ignored if the <handle> is not equal to 0. + * Passing the process <handle> is prefer on Win32 because using + * <pid> to wait on the project doesn't always work correctly + * if the waited process has already terminated. + */ static pid_t waitpid (pid_t pid, ACE_exitcode *status = 0, int wait_options = 0, ACE_HANDLE handle = 0); - // Calls <::waitpid> on UNIX/POSIX platforms and <::await> on - // Chorus. Does not work on Vxworks, or pSoS. - // On Win32, <pid> is ignored if the <handle> is not equal to 0. - // Passing the process <handle> is prefer on Win32 because using - // <pid> to wait on the project doesn't always work correctly - // if the waited process has already terminated. + + /** + * Calls <::WaitForSingleObject> on Win32 and <ACE::waitpid> + * otherwise. Returns the passed in <pid_t> on success and -1 on + * failure. + * On Win32, <pid> is ignored if the <handle> is not equal to 0. + * Passing the process <handle> is prefer on Win32 because using + * <pid> to wait on the project doesn't always work correctly + * if the waited process has already terminated. + */ static pid_t wait (pid_t pid, ACE_exitcode *status, int wait_options = 0, ACE_HANDLE handle = 0); - // Calls <::WaitForSingleObject> on Win32 and <ACE::waitpid> - // otherwise. Returns the passed in <pid_t> on success and -1 on - // failure. - // On Win32, <pid> is ignored if the <handle> is not equal to 0. - // Passing the process <handle> is prefer on Win32 because using - // <pid> to wait on the project doesn't always work correctly - // if the waited process has already terminated. + + /// Calls OS <::wait> function, so it's only portable to UNIX/POSIX + /// platforms. static pid_t wait (int * = 0); - // Calls OS <::wait> function, so it's only portable to UNIX/POSIX - // platforms. - // = A set of wrappers for timers and resource stats. + //@{ @name A set of wrappers for timers and resource stats. static u_int alarm (u_int secs); static u_int ualarm (u_int usecs, u_int interval = 0); @@ -5213,8 +5293,9 @@ public: # define ACE_DIFFTIME(t1, t0) difftime(t1,t0) # undef difftime # endif /* difftime */ + //@} - // = A set of wrappers for operations on time. + //@{ @name A set of wrappers for operations on time. # if !defined (ACE_HAS_WINCE) static time_t mktime (struct tm *timeptr); # endif /* !ACE_HAS_WINCE */ @@ -5241,8 +5322,9 @@ public: size_t maxsize, const char *format, const struct tm *timeptr); + //@} - // = A set of wrappers for System V message queues. + //@{ @name A set of wrappers for System V message queues. static int msgctl (int msqid, int cmd, struct msqid_ds *); @@ -5257,8 +5339,9 @@ public: const void *buf, size_t len, int flags); + //@} - // = A set of wrappers for memory mapped files. + //@{ @name A set of wrappers for memory mapped files. static int madvise (caddr_t addr, size_t len, int advice); @@ -5278,8 +5361,9 @@ public: int sync); static int munmap (void *addr, size_t len); + //@} - // = A set of wrappers for recursive mutex locks. + //@{ @name A set of wrappers for recursive mutex locks. static int recursive_mutex_init (ACE_recursive_thread_mutex_t *m, const ACE_TCHAR *name = 0, ACE_mutexattr_t *arg = 0, @@ -5288,32 +5372,38 @@ public: static int recursive_mutex_lock (ACE_recursive_thread_mutex_t *m); static int recursive_mutex_trylock (ACE_recursive_thread_mutex_t *m); static int recursive_mutex_unlock (ACE_recursive_thread_mutex_t *m); + //@} - // = A set of wrappers for mutex locks. + //@{ @name A set of wrappers for mutex locks. static int mutex_init (ACE_mutex_t *m, int type = ACE_DEFAULT_SYNCH_TYPE, const ACE_TCHAR *name = 0, ACE_mutexattr_t *arg = 0, LPSECURITY_ATTRIBUTES sa = 0); static int mutex_destroy (ACE_mutex_t *m); + + /// Win32 note: Abandoned mutexes are not treated differently. 0 is + /// returned since the calling thread does get the ownership. static int mutex_lock (ACE_mutex_t *m); - // Win32 note: Abandoned mutexes are not treated differently. 0 is - // returned since the calling thread does get the ownership. + + /// This method is only implemented for Win32. For abandoned + /// mutexes, <abandoned> is set to 1 and 0 is returned. static int mutex_lock (ACE_mutex_t *m, int &abandoned); - // This method is only implemented for Win32. For abandoned - // mutexes, <abandoned> is set to 1 and 0 is returned. + + /// Win32 note: Abandoned mutexes are not treated differently. 0 is + /// returned since the calling thread does get the ownership. static int mutex_trylock (ACE_mutex_t *m); - // Win32 note: Abandoned mutexes are not treated differently. 0 is - // returned since the calling thread does get the ownership. + + /// This method is only implemented for Win32. For abandoned + /// mutexes, <abandoned> is set to 1 and 0 is returned. static int mutex_trylock (ACE_mutex_t *m, int &abandoned); - // This method is only implemented for Win32. For abandoned - // mutexes, <abandoned> is set to 1 and 0 is returned. + static int mutex_unlock (ACE_mutex_t *m); + //@} - // = A set of wrappers for mutex locks that only work within a - // single process. + //@{ @name A set of wrappers for mutex locks that only work within a single process. static int thread_mutex_init (ACE_thread_mutex_t *m, int type = ACE_DEFAULT_SYNCH_TYPE, const ACE_TCHAR *name = 0, @@ -5322,8 +5412,9 @@ public: static int thread_mutex_lock (ACE_thread_mutex_t *m); static int thread_mutex_trylock (ACE_thread_mutex_t *m); static int thread_mutex_unlock (ACE_thread_mutex_t *m); + //@} - // = A set of wrappers for low-level file operations. + //@{ @name A set of wrappers for low-level file operations. static int access (const char *path, int amode); #if defined (ACE_HAS_WCHAR) static int access (const wchar_t *path, int amode); @@ -5349,10 +5440,13 @@ public: *data, int *band, int *flags); + + /// UNIX-style <ioctl>. static int ioctl (ACE_HANDLE handle, int cmd, void * = 0); - // UNIX-style <ioctl>. + + /// QoS-enabled <ioctl>. static int ioctl (ACE_HANDLE socket, u_long io_control_code, void *in_buffer_p, @@ -5362,7 +5456,9 @@ public: u_long *bytes_returned, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func); - // QoS-enabled <ioctl>. + + /// QoS-enabled <ioctl> when the I/O control code is either + /// SIO_SET_QOS or SIO_GET_QOS. static int ioctl (ACE_HANDLE socket, u_long io_control_code, ACE_QoS &ace_qos, @@ -5371,8 +5467,7 @@ public: u_long buffer = 0, ACE_OVERLAPPED *overlapped = 0, ACE_OVERLAPPED_COMPLETION_FUNC func = 0); - // QoS-enabled <ioctl> when the I/O control code is either SIO_SET_QOS - // or SIO_GET_QOS. + static int isastream (ACE_HANDLE handle); static int isatty (int handle); #if defined (ACE_WIN32) @@ -5410,16 +5505,19 @@ public: void *buf, size_t len, ACE_OVERLAPPED *); + /** + * Receive <len> bytes into <buf> from <handle> (uses the + * <ACE_OS::read> call, which uses the <read> system call on UNIX + * and the <ReadFile> call on Win32). If errors occur, -1 is + * returned. If EOF occurs, 0 is returned. Whatever data has been + * transmitted will be returned to the caller through + * <bytes_transferred>. + */ static ssize_t read_n (ACE_HANDLE handle, void *buf, size_t len, size_t *bytes_transferred = 0); - // Receive <len> bytes into <buf> from <handle> (uses the - // <ACE_OS::read> call, which uses the <read> system call on UNIX - // and the <ReadFile> call on Win32). If errors occur, -1 is - // returned. If EOF occurs, 0 is returned. Whatever data has been - // transmitted will be returned to the caller through - // <bytes_transferred>. + static int readlink (const char *path, char *buf, size_t bufsiz); @@ -5440,15 +5538,19 @@ public: const void *buf, size_t nbyte, ACE_OVERLAPPED *); + + /** + * Send <len> bytes from <buf> to <handle> (uses the <ACE_OS::write> + * calls, which is uses the <write> system call on UNIX and the + * <WriteFile> call on Win32). If errors occur, -1 is returned. If + * EOF occurs, 0 is returned. Whatever data has been transmitted + * will be returned to the caller through <bytes_transferred>. + */ static ssize_t write_n (ACE_HANDLE handle, const void *buf, size_t len, size_t *bytes_transferred = 0); - // Send <len> bytes from <buf> to <handle> (uses the <ACE_OS::write> - // calls, which is uses the <write> system call on UNIX and the - // <WriteFile> call on Win32). If errors occur, -1 is returned. If - // EOF occurs, 0 is returned. Whatever data has been transmitted - // will be returned to the caller through <bytes_transferred>. + static ssize_t pwrite (ACE_HANDLE handle, const void *buf, size_t nbyte, @@ -5465,8 +5567,9 @@ public: static ssize_t sendv (ACE_HANDLE handle, const iovec *iov, int iovcnt); + //@} - // = A set of wrappers for event demultiplexing and IPC. + //@{ @name A set of wrappers for event demultiplexing and IPC. static int select (int width, fd_set *rfds, fd_set *wfds, @@ -5490,8 +5593,9 @@ public: int perms = 0, LPSECURITY_ATTRIBUTES sa = 0); static int shm_unlink (const ACE_TCHAR *path); + //@} - // = A set of wrappers for directory operations. + //@{ @name A set of wrappers for directory operations. static mode_t umask (mode_t cmask); static int chdir (const char *path); @@ -5511,13 +5615,15 @@ public: static int unlink (const ACE_TCHAR *path); static ACE_TCHAR *tempnam (const ACE_TCHAR *dir = 0, const ACE_TCHAR *pfx = 0); + //@} - // = A set of wrappers for random number operations. + //@{ @name A set of wrappers for random number operations. static int rand (void); static int rand_r (ACE_RANDR_TYPE &seed); static void srand (u_int seed); + //@} - // = A set of wrappers for readers/writer locks. + //@{ @name A set of wrappers for readers/writer locks. static int rwlock_init (ACE_rwlock_t *rw, int type = ACE_DEFAULT_SYNCH_TYPE, const ACE_TCHAR *name = 0, @@ -5529,8 +5635,9 @@ public: static int rw_trywrlock (ACE_rwlock_t *rw); static int rw_trywrlock_upgrade (ACE_rwlock_t *rw); static int rw_unlock (ACE_rwlock_t *rw); + //@} - // = A set of wrappers for auto-reset and manuaevents. + //@{ @name A set of wrappers for auto-reset and manuaevents. static int event_init (ACE_event_t *event, int manual_reset = 0, int initial_state = 0, @@ -5545,8 +5652,9 @@ public: static int event_signal (ACE_event_t *event); static int event_pulse (ACE_event_t *event); static int event_reset (ACE_event_t *event); + //@} - // = A set of wrappers for semaphores. + //@{ @name A set of wrappers for semaphores. static int sema_destroy (ACE_sema_t *s); static int sema_init (ACE_sema_t *s, u_int count, @@ -5562,8 +5670,9 @@ public: static int sema_wait (ACE_sema_t *s); static int sema_wait (ACE_sema_t *s, ACE_Time_Value &tv); + //@} - // = A set of wrappers for System V semaphores. + //@{ @name A set of wrappers for System V semaphores. static int semctl (int int_id, int semnum, int cmd, @@ -5574,13 +5683,15 @@ public: static int semop (int int_id, struct sembuf *sops, size_t nsops); + //@} - // = Thread scheduler interface. + //@{ @name Thread scheduler interface. + /// Set scheduling parameters. An id of ACE_SELF indicates, e.g., + /// set the parameters on the calling thread. static int sched_params (const ACE_Sched_Params &, ACE_id_t id = ACE_SELF); - // Set scheduling parameters. An id of ACE_SELF indicates, e.g., - // set the parameters on the calling thread. + //@} - // = A set of wrappers for System V shared memory. + //@{ @name A set of wrappers for System V shared memory. static void *shmat (int int_id, void *shmaddr, int shmflg); @@ -5591,8 +5702,9 @@ public: static int shmget (key_t key, int size, int flags); + ///@} - // = A set of wrappers for Signals. + //@{ @name A set of wrappers for Signals. static int kill (pid_t pid, int signum); static int sigaction (int signum, @@ -5616,33 +5728,40 @@ public: static int pthread_sigmask (int how, const sigset_t *nsp, sigset_t *osp); + //@} - // = A set of wrappers for sockets. + //@{ @name A set of wrappers for sockets. + /// BSD-style <accept> (no QoS). static ACE_HANDLE accept (ACE_HANDLE handle, struct sockaddr *addr, int *addrlen); - // BSD-style <accept> (no QoS). + + /** + * QoS-enabled <accept>, which passes <qos_params> to <accept>. If + * the OS platform doesn't support QoS-enabled <accept> then the + * <qos_params> are ignored and the BSD-style <accept> is called. + */ static ACE_HANDLE accept (ACE_HANDLE handle, struct sockaddr *addr, int *addrlen, const ACE_Accept_QoS_Params &qos_params); - // QoS-enabled <accept>, which passes <qos_params> to <accept>. If - // the OS platform doesn't support QoS-enabled <accept> then the - // <qos_params> are ignored and the BSD-style <accept> is called. - static int bind (ACE_HANDLE s, - struct sockaddr *name, - int namelen); + /// BSD-style <connect> (no QoS). static int connect (ACE_HANDLE handle, struct sockaddr *addr, int addrlen); - // BSD-style <connect> (no QoS). + /** + * QoS-enabled <connect>, which passes <qos_params> to <connect>. + * If the OS platform doesn't support QoS-enabled <connect> then the + * <qos_params> are ignored and the BSD-style <connect> is called. + */ static int connect (ACE_HANDLE handle, const sockaddr *addr, int addrlen, const ACE_QoS_Params &qos_params); - // QoS-enabled <connect>, which passes <qos_params> to <connect>. - // If the OS platform doesn't support QoS-enabled <connect> then the - // <qos_params> are ignored and the BSD-style <connect> is called. + + static int bind (ACE_HANDLE s, + struct sockaddr *name, + int namelen); static int closesocket (ACE_HANDLE s); static struct hostent *gethostbyaddr (const char *addr, @@ -5696,16 +5815,16 @@ public: static int inet_pton (int family, const char *strptr, void *addrptr); + /// Retrieve information about available transport protocols + /// installed on the local machine. static int enum_protocols (int *protocols, ACE_Protocol_Info *protocol_buffer, u_long *buffer_length); - // Retrieve information about available transport protocols - // installed on the local machine. + /// Joins a leaf node into a QoS-enabled multi-point session. static ACE_HANDLE join_leaf (ACE_HANDLE socket, const sockaddr *name, int namelen, const ACE_QoS_Params &qos_params); - // Joins a leaf node into a QoS-enabled multi-point session. static int listen (ACE_HANDLE handle, int backlog); static int recv (ACE_HANDLE handle, @@ -5746,41 +5865,45 @@ public: int addrlen, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func); + + /// QoS-enabled <ioctl> wrapper. static int setsockopt (ACE_HANDLE handle, int level, int optname, const char *optval, int optlen); - // QoS-enabled <ioctl> wrapper. static int shutdown (ACE_HANDLE handle, int how); + + /// Create a BSD-style socket (no QoS). static ACE_HANDLE socket (int protocol_family, int type, int proto); - // Create a BSD-style socket (no QoS). + /// Create a QoS-enabled socket. If the OS platform doesn't support + /// QoS-enabled <socket> then the BSD-style <socket> is called. static ACE_HANDLE socket (int protocol_family, int type, int proto, ACE_Protocol_Info *protocolinfo, ACE_SOCK_GROUP g, u_long flags); - // Create a QoS-enabled socket. If the OS platform doesn't support - // QoS-enabled <socket> then the BSD-style <socket> is called. static int socketpair (int domain, int type, int protocol, ACE_HANDLE sv[2]); + + /// Initialize WinSock before first use (e.g., when a DLL is first + /// loaded or the first use of a socket() call. static int socket_init (int version_high = 1, int version_low = 1); - // Initialize WinSock before first use (e.g., when a DLL is first - // loaded or the first use of a socket() call. + /// Finalize WinSock after last use (e.g., when a DLL is unloaded). static int socket_fini (void); - // Finalize WinSock after last use (e.g., when a DLL is unloaded). + //@} - // = A set of wrappers for password routines. + //@{ @name A set of wrappers for password routines. static void setpwent (void); static void endpwent (void); static struct passwd *getpwent (void); @@ -5789,14 +5912,17 @@ public: struct passwd *pwent, char *buffer, int buflen); + //@} - // = A set of wrappers for regular expressions. + //@{ @name A set of wrappers for regular expressions. static char *compile (const char *instring, char *expbuf, char *endbuf); static int step (const char *str, char *expbuf); + //@} + //@{ @name Wide-character strings // @@ UNICODE: (brunsch) Can this be handled better? // The following WChar typedef and functions are used by TAO. TAO // does not use wchar_t because the size of wchar_t is @@ -5811,9 +5937,10 @@ public: static int wsncmp (const WChar *, const WChar *, size_t len); + //@} # if 0 - // = A set of wrappers for threads (these are portable since they use the ACE_Thread_ID). + //@{ @name A set of wrappers for threads (these are portable since they use the ACE_Thread_ID). static int thr_continue (const ACE_Thread_ID &thread); static int thr_create (ACE_THR_FUNC, void *args, @@ -5835,13 +5962,44 @@ public: static int thr_setprio (const ACE_Sched_Priority prio); static int thr_suspend (ACE_Thread_ID target_thread); static int thr_cancel (ACE_Thread_ID t_id); + //@} # endif /* 0 */ - // = A set of wrappers for threads + //@{ @name A set of wrappers for threads // These are non-portable since they use ACE_thread_t and // ACE_hthread_t and will go away in a future release. static int thr_continue (ACE_hthread_t target_thread); + + /* + * Creates a new thread having <flags> attributes and running <func> + * with <args> (if <thread_adapter> is non-0 then <func> and <args> + * are ignored and are obtained from <thread_adapter>). <thr_id> + * and <t_handle> are set to the thread's ID and handle (?), + * respectively. The thread runs at <priority> priority (see + * below). + * + * The <flags> are a bitwise-OR of the following: + * = BEGIN<INDENT> + * THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED, + * THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED, + * THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO, + * THR_SCHED_RR, THR_SCHED_DEFAULT + * = END<INDENT> + * + * By default, or if <priority> is set to + * ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for + * the given scheduling policy (specified in <flags}>, e.g., + * <THR_SCHED_DEFAULT>) is used. This value is calculated + * dynamically, and is the median value between the minimum and + * maximum priority values for the given policy. If an explicit + * value is given, it is used. Note that actual priority values are + * EXTREMEMLY implementation-dependent, and are probably best + * avoided. + * + * Note that <thread_adapter> is always deleted by <thr_create>, + * therefore it must be allocated with global operator new. + */ static int thr_create (ACE_THR_FUNC func, void *args, long flags, @@ -5851,33 +6009,6 @@ public: void *stack = 0, size_t stacksize = 0, ACE_Base_Thread_Adapter *thread_adapter = 0); - // Creates a new thread having <flags> attributes and running <func> - // with <args> (if <thread_adapter> is non-0 then <func> and <args> - // are ignored and are obtained from <thread_adapter>). <thr_id> - // and <t_handle> are set to the thread's ID and handle (?), - // respectively. The thread runs at <priority> priority (see - // below). - // - // The <flags> are a bitwise-OR of the following: - // = BEGIN<INDENT> - // THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED, - // THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED, - // THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO, - // THR_SCHED_RR, THR_SCHED_DEFAULT - // = END<INDENT> - // - // By default, or if <priority> is set to - // ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for - // the given scheduling policy (specified in <flags}>, e.g., - // <THR_SCHED_DEFAULT>) is used. This value is calculated - // dynamically, and is the median value between the minimum and - // maximum priority values for the given policy. If an explicit - // value is given, it is used. Note that actual priority values are - // EXTREMEMLY implementation-dependent, and are probably best - // avoided. - // - // Note that <thread_adapter> is always deleted by <thr_create>, - // therefore it must be allocated with global operator new. static int thr_getprio (ACE_hthread_t thr_id, int &prio); @@ -5955,62 +6086,70 @@ public: static void thr_testcancel (void); static void thr_yield (void); + /** + * This method uses process id and object pointer to come up with a + * machine wide unique name. The process ID will provide uniqueness + * between processes on the same machine. The "this" pointer of the + * <object> will provide uniqueness between other "live" objects in + * the same process. The uniqueness of this name is therefore only + * valid for the life of <object>. + */ static void unique_name (const void *object, ACE_TCHAR *name, size_t length); - // This method uses process id and object pointer to come up with a - // machine wide unique name. The process ID will provide uniqueness - // between processes on the same machine. The "this" pointer of the - // <object> will provide uniqueness between other "live" objects in - // the same process. The uniqueness of this name is therefore only - // valid for the life of <object>. + /// This is necessary to deal with POSIX pthreads and their use of + /// structures for thread ids. static ACE_thread_t NULL_thread; - // This is necessary to deal with POSIX pthreads and their use of - // structures for thread ids. + /// This is necessary to deal with POSIX pthreads and their use of + /// structures for thread handles. static ACE_hthread_t NULL_hthread; - // This is necessary to deal with POSIX pthreads and their use of - // structures for thread handles. + /// This is necessary to deal with POSIX pthreads and their use of + /// structures for TSS keys. static ACE_thread_key_t NULL_key; - // This is necessary to deal with POSIX pthreads and their use of - // structures for TSS keys. # if defined (CHORUS) + /// This is used to map an actor's id into a KnCap for killing and + /// waiting actors. static KnCap actorcaps_[ACE_CHORUS_MAX_ACTORS]; - // This is used to map an actor's id into a KnCap for killing and - // waiting actors. # endif /* CHORUS */ + //@} # if defined (ACE_WIN32) + /// Keeps track of whether we've already initialized WinSock... static int socket_initialized_; - // Keeps track of whether we've already initialized WinSock... # endif /* ACE_WIN32 */ + /// Handle asynchronous thread cancellation cleanup. static void mutex_lock_cleanup (void *mutex); - // Handle asynchronous thread cancellation cleanup. + /** + * Call TSS destructors for the current thread. If the current + * thread is the main thread, then the argument must be 1. + * For private use of ACE_Object_Manager and ACE_Thread_Adapter only. + */ static void cleanup_tss (const u_int main_thread); - // Call TSS destructors for the current thread. If the current - // thread is the main thread, then the argument must be 1. - // For private use of ACE_Object_Manager and ACE_Thread_Adapter only. # if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) && defined (ACE_LACKS_NETDB_REENTRANT_FUNCTIONS) static int netdb_acquire (void); static int netdb_release (void); # endif /* defined (ACE_MT_SAFE) && ACE_LACKS_NETDB_REENTRANT_FUNCTIONS */ + /// Find the schedling class ID that corresponds to the class name. static int scheduling_class (const char *class_name, ACE_id_t &); - // Find the schedling class ID that corresponds to the class name. + /// Friendly interface to <priocntl>(2). static int set_scheduling_params (const ACE_Sched_Params &, ACE_id_t id = ACE_SELF); - // Friendly interface to <priocntl>(2). - // Can't call the following priocntl, because that's a macro on Solaris. + /// Low-level interface to <priocntl>(2). + /** + * Can't call the following priocntl, because that's a macro on + * Solaris. + */ static int priority_control (ACE_idtype_t, ACE_id_t, int, void *); - // Low-level interface to <priocntl>(2). #if defined (ACE_HAS_STRPTIME) static char *strptime (char *buf, @@ -6024,38 +6163,40 @@ public: #endif /* ACE_HAS_STRPTIME */ private: + /// Function that is called by <ACE_OS::exit>, if non-null. static ACE_EXIT_HOOK exit_hook_; - // Function that is called by <ACE_OS::exit>, if non-null. + /// For use by ACE_Object_Manager only, to register its exit hook.. static ACE_EXIT_HOOK set_exit_hook (ACE_EXIT_HOOK hook); - // For use by ACE_Object_Manager only, to register its exit hook.. + /// Allow the ACE_OS_Object_Manager to call set_exit_hook. friend class ACE_OS_Object_Manager; - // Allow the ACE_OS_Object_Manager to call set_exit_hook. # if defined (ACE_WIN32) # if defined (ACE_HAS_WINCE) + /// Supporting data for ctime and ctime_r functions on WinCE. static const wchar_t *day_of_week_name[7]; static const wchar_t *month_name[12]; - // Supporting data for ctime and ctime_r functions on WinCE. # endif /* ACE_HAS_WINCE */ + /// Translate fopen's mode char to open's mode. This helper function + /// is here to avoid maintaining several pieces of identical code. static void fopen_mode_to_open_mode_converter (ACE_TCHAR x, int &hmode); - // Translate fopen's mode char to open's mode. This helper function - // is here to avoid maintaining several pieces of identical code. static OSVERSIONINFO win32_versioninfo_; # endif /* ACE_WIN32 */ }; +/** + * @class ACE_Object_Manager_Base + * + * @brief Base class for ACE_Object_Manager(s). + * + * Encapsulates the most useful ACE_Object_Manager data structures. + */ class ACE_Export ACE_Object_Manager_Base { - // = TITLE - // Base class for ACE_Object_Manager(s). - // - // = DESCRIPTION - // Encapsulates the most useful ACE_Object_Manager data structures. # if (defined (ACE_PSOS) && defined (__DIAB)) || \ (defined (__DECCXX_VER) && __DECCXX_VER < 60000000) // The Diab compiler got confused and complained about access rights @@ -6065,22 +6206,26 @@ public: # else /* ! (ACE_PSOS && __DIAB) || ! __DECCXX_VER < 60000000 */ protected: # endif /* ! (ACE_PSOS && __DIAB) || ! __DECCXX_VER < 60000000 */ + /// Default constructor. ACE_Object_Manager_Base (void); - // Default constructor. + /// Destructor. virtual ~ACE_Object_Manager_Base (void); - // Destructor. public: + /** + * Explicitly initialize. Returns 0 on success, -1 on failure due + * to dynamic allocation failure (in which case errno is set to + * ENOMEM), or 1 if it had already been called. + */ virtual int init (void) = 0; - // Explicitly initialize. Returns 0 on success, -1 on failure due - // to dynamic allocation failure (in which case errno is set to - // ENOMEM), or 1 if it had already been called. + /** + * Explicitly destroy. Returns 0 on success, -1 on failure because + * the number of fini () calls hasn't reached the number of init () + * calls, or 1 if it had already been called. + */ virtual int fini (void) = 0; - // Explicitly destroy. Returns 0 on success, -1 on failure because - // the number of fini () calls hasn't reached the number of init () - // calls, or 1 if it had already been called. enum Object_Manager_State { @@ -6092,33 +6237,39 @@ public: }; protected: + /** + * Returns 1 before ACE_Object_Manager_Base has been constructed. + * This flag can be used to determine if the program is constructing + * static objects. If no static object spawns any threads, the + * program will be single-threaded when this flag returns 1. (Note + * that the program still might construct some static objects when + * this flag returns 0, if ACE_HAS_NONSTATIC_OBJECT_MANAGER is not + * defined.) + */ int starting_up_i (void); - // Returns 1 before ACE_Object_Manager_Base has been constructed. - // This flag can be used to determine if the program is constructing - // static objects. If no static object spawns any threads, the - // program will be single-threaded when this flag returns 1. (Note - // that the program still might construct some static objects when - // this flag returns 0, if ACE_HAS_NONSTATIC_OBJECT_MANAGER is not - // defined.) + /** + * Returns 1 after ACE_Object_Manager_Base has been destroyed. This + * flag can be used to determine if the program is in the midst of + * destroying static objects. (Note that the program might destroy + * some static objects before this flag can return 1, if + * ACE_HAS_NONSTATIC_OBJECT_MANAGER is not defined.) + */ int shutting_down_i (void); - // Returns 1 after ACE_Object_Manager_Base has been destroyed. This - // flag can be used to determine if the program is in the midst of - // destroying static objects. (Note that the program might destroy - // some static objects before this flag can return 1, if - // ACE_HAS_NONSTATIC_OBJECT_MANAGER is not defined.) + /// State of the Object_Manager; Object_Manager_State object_manager_state_; - // State of the Object_Manager; + /** + * Flag indicating whether the ACE_Object_Manager was dynamically + * allocated by ACE. (If is was dynamically allocated by the + * application, then the application is responsible for destroying + * it.) + */ u_int dynamically_allocated_; - // Flag indicating whether the ACE_Object_Manager was dynamically - // allocated by ACE. (If is was dynamically allocated by the - // application, then the application is responsible for destroying - // it.) + /// Link to next Object_Manager, for chaining. ACE_Object_Manager_Base *next_; - // Link to next Object_Manager, for chaining. private: // Disallow copying by not implementing the following . . . ACE_Object_Manager_Base (const ACE_Object_Manager_Base &); @@ -6136,21 +6287,24 @@ class ACE_Log_Msg; class ACE_Export ACE_OS_Object_Manager : public ACE_Object_Manager_Base { public: + /// Explicitly initialize. virtual int init (void); - // Explicitly initialize. + /// Explicitly destroy. virtual int fini (void); - // Explicitly destroy. + /** + * Returns 1 before the <ACE_OS_Object_Manager> has been + * constructed. See <ACE_Object_Manager::starting_up> for more + * information. + */ static int starting_up (void); - // Returns 1 before the <ACE_OS_Object_Manager> has been - // constructed. See <ACE_Object_Manager::starting_up> for more - // information. + /// Returns 1 after the <ACE_OS_Object_Manager> has been destroyed. + /// See <ACE_Object_Manager::shutting_down> for more information. static int shutting_down (void); - // Returns 1 after the <ACE_OS_Object_Manager> has been destroyed. - // See <ACE_Object_Manager::shutting_down> for more information. + /// Unique identifiers for preallocated objects. enum Preallocated_Object { # if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) @@ -6170,24 +6324,24 @@ public: ACE_OS_EMPTY_PREALLOCATED_OBJECT, # endif /* ACE_MT_SAFE */ - ACE_OS_PREALLOCATED_OBJECTS // This enum value must be last! + /// This enum value must be last! + ACE_OS_PREALLOCATED_OBJECTS }; - // Unique identifiers for preallocated objects. + /// Accesses a default signal set used, for example, in + /// <ACE_Sig_Guard> methods. static sigset_t *default_mask (void); - // Accesses a default signal set used, for example, in - // <ACE_Sig_Guard> methods. + /// Returns the current thread hook for the process. static ACE_Thread_Hook *thread_hook (void); - // Returns the current thread hook for the process. + /// Returns the existing thread hook and assign a <new_thread_hook>. static ACE_Thread_Hook *thread_hook (ACE_Thread_Hook *new_thread_hook); - // Returns the existing thread hook and assign a <new_thread_hook>. #if defined (ACE_HAS_WIN32_STRUCTURAL_EXCEPTIONS) + /// Get/Set TSS exception action. static ACE_SEH_EXCEPT_HANDLER seh_except_selector (void); static ACE_SEH_EXCEPT_HANDLER seh_except_selector (ACE_SEH_EXCEPT_HANDLER); - // Get/Set TSS exception action. static ACE_SEH_EXCEPT_HANDLER seh_except_handler (void); static ACE_SEH_EXCEPT_HANDLER seh_except_handler (ACE_SEH_EXCEPT_HANDLER); @@ -6199,44 +6353,45 @@ public: // They're public so that the <ACE_Object_Manager> can be // constructed/destructed in <main> with // <ACE_HAS_NONSTATIC_OBJECT_MANAGER>. + /// Constructor. ACE_OS_Object_Manager (void); - // Constructor. + /// Destructor. ~ACE_OS_Object_Manager (void); - // Destructor. private: + /// Accessor to singleton instance. static ACE_OS_Object_Manager *instance (void); - // Accessor to singleton instance. + /// Singleton instance pointer. static ACE_OS_Object_Manager *instance_; - // Singleton instance pointer. + /// Table of preallocated objects. static void *preallocated_object[ACE_OS_PREALLOCATED_OBJECTS]; - // Table of preallocated objects. + /// Default signal set used, for example, in ACE_Sig_Guard. sigset_t *default_mask_; - // Default signal set used, for example, in ACE_Sig_Guard. + /// Thread hook that's used by this process. ACE_Thread_Hook *thread_hook_; - // Thread hook that's used by this process. + /// For at_exit support. ACE_OS_Exit_Info exit_info_; - // For at_exit support. #if defined (ACE_HAS_WIN32_STRUCTURAL_EXCEPTIONS) + /// These handlers determine how a thread handles win32 structured + /// exception. ACE_SEH_EXCEPT_HANDLER seh_except_selector_; ACE_SEH_EXCEPT_HANDLER seh_except_handler_; - // These handlers determine how a thread handles win32 structured - // exception. #endif /* ACE_HAS_WIN32_STRUCTURAL_EXCEPTIONS */ + /// For <ACE_OS::atexit> support. int at_exit (ACE_EXIT_HOOK func); - // For <ACE_OS::atexit> support. + /// For use by init () and fini (), to consolidate error reporting. static void print_error_message (u_int line_number, const ACE_TCHAR *message); - // For use by init () and fini (), to consolidate error reporting. + /// This class is for internal use by ACE_OS, etc., only. friend class ACE_OS; friend class ACE_Object_Manager; friend class ACE_OS_Object_Manager_Manager; @@ -6244,7 +6399,6 @@ private: friend class ACE_TSS_Emulation; friend class ACE_Log_Msg; friend void ACE_OS_Object_Manager_Internal_Exit_Hook (); - // This class is for internal use by ACE_OS, etc., only. }; # if defined (ACE_LACKS_TIMEDWAIT_PROTOTYPES) @@ -6305,70 +6459,74 @@ extern "C" ssize_t writev_timedwait (ACE_HANDLE handle, # define ACE_DEFAULT_THREAD_KEYS 64 # endif /* ! ACE_DEFAULT_THREAD_KEYS */ +/** + * @class ACE_TSS_Emulation + * + * @brief Thread-specific storage emulation. + * + * This provides a thread-specific storage implementation. + * It is intended for use on platforms that don't have a + * native TSS, or have a TSS with limitations such as the + * number of keys or lack of support for removing keys. + */ class ACE_Export ACE_TSS_Emulation { - // = TITLE - // Thread-specific storage emulation. - // - // = DESCRIPTION - // This provides a thread-specific storage implementation. - // It is intended for use on platforms that don't have a - // native TSS, or have a TSS with limitations such as the - // number of keys or lack of support for removing keys. public: typedef void (*ACE_TSS_DESTRUCTOR)(void *value) /* throw () */; + /// Maximum number of TSS keys allowed over the life of the program. enum { ACE_TSS_THREAD_KEYS_MAX = ACE_DEFAULT_THREAD_KEYS }; - // Maximum number of TSS keys allowed over the life of the program. + /// Returns the total number of keys allocated so far. static u_int total_keys (); - // Returns the total number of keys allocated so far. + /// Sets the argument to the next available key. Returns 0 on success, + /// -1 if no keys are available. static int next_key (ACE_thread_key_t &key); - // Sets the argument to the next available key. Returns 0 on success, - // -1 if no keys are available. + /// Returns the exit hook associated with the key. Does _not_ check + /// for a valid key. static ACE_TSS_DESTRUCTOR tss_destructor (const ACE_thread_key_t key); - // Returns the exit hook associated with the key. Does _not_ check - // for a valid key. + /// Associates the TSS destructor with the key. Does _not_ check + /// for a valid key. static void tss_destructor (const ACE_thread_key_t key, ACE_TSS_DESTRUCTOR destructor); - // Associates the TSS destructor with the key. Does _not_ check - // for a valid key. + /// Accesses the object referenced by key in the current thread's TSS array. + /// Does _not_ check for a valid key. static void *&ts_object (const ACE_thread_key_t key); - // Accesses the object referenced by key in the current thread's TSS array. - // Does _not_ check for a valid key. + /** + * Setup an array to be used for local TSS. Returns the array + * address on success. Returns 0 if local TSS had already been + * setup for this thread. There is no corresponding tss_close () + * because it is not needed. + * NOTE: tss_open () is called by ACE for threads that it spawns. + * If your application spawns threads without using ACE, and it uses + * ACE's TSS emulation, each of those threads should call tss_open + * (). See the ace_thread_adapter () implementaiton for an example. + */ static void *tss_open (void *ts_storage[ACE_TSS_THREAD_KEYS_MAX]); - // Setup an array to be used for local TSS. Returns the array - // address on success. Returns 0 if local TSS had already been - // setup for this thread. There is no corresponding tss_close () - // because it is not needed. - // NOTE: tss_open () is called by ACE for threads that it spawns. - // If your application spawns threads without using ACE, and it uses - // ACE's TSS emulation, each of those threads should call tss_open - // (). See the ace_thread_adapter () implementaiton for an example. + /// Shutdown TSS emulation. For use only by ACE_OS::cleanup_tss (). static void tss_close (); - // Shutdown TSS emulation. For use only by ACE_OS::cleanup_tss (). private: // Global TSS structures. + /// Always contains the value of the next key to be allocated. static u_int total_keys_; - // Always contains the value of the next key to be allocated. + /// Array of thread exit hooks (TSS destructors) that are called for each + /// key (that has one) when the thread exits. static ACE_TSS_DESTRUCTOR tss_destructor_ [ACE_TSS_THREAD_KEYS_MAX]; - // Array of thread exit hooks (TSS destructors) that are called for each - // key (that has one) when the thread exits. # if defined (ACE_HAS_THREAD_SPECIFIC_STORAGE) + /// Location of current thread's TSS array. static void **tss_base (void* ts_storage[] = 0, u_int *ts_created = 0); - // Location of current thread's TSS array. # else /* ! ACE_HAS_THREAD_SPECIFIC_STORAGE */ + /// Location of current thread's TSS array. static void **&tss_base (); - // Location of current thread's TSS array. # endif /* ! ACE_HAS_THREAD_SPECIFIC_STORAGE */ # if defined (ACE_HAS_THREAD_SPECIFIC_STORAGE) @@ -6393,108 +6551,114 @@ private: // declarations from OS.cpp so they are visible to the single // file of template instantiations. # if defined (ACE_WIN32) || defined (ACE_HAS_TSS_EMULATION) || (defined (ACE_PSOS) && defined (ACE_PSOS_HAS_TSS)) +/** + * @class ACE_TSS_Ref + * + * @brief "Reference count" for thread-specific storage keys. + * + * Since the <ACE_Unbounded_Stack> doesn't allow duplicates, the + * "reference count" is the identify of the thread_id. + */ class ACE_TSS_Ref { - // = TITLE - // "Reference count" for thread-specific storage keys. - // - // = DESCRIPTION - // Since the <ACE_Unbounded_Stack> doesn't allow duplicates, the - // "reference count" is the identify of the thread_id. public: + /// Constructor ACE_TSS_Ref (ACE_thread_t id); - // Constructor + /// Default constructor ACE_TSS_Ref (void); - // Default constructor + /// Check for equality. int operator== (const ACE_TSS_Ref &) const; - // Check for equality. + /// Check for inequality. int operator!= (const ACE_TSS_Ref &) const; - // Check for inequality. // private: + /// ID of thread using a specific key. ACE_thread_t tid_; - // ID of thread using a specific key. }; +/** + * @class ACE_TSS_Info + * + * @brief Thread Specific Key management. + * + * This class maps a key to a "destructor." + */ class ACE_TSS_Info { - // = TITLE - // Thread Specific Key management. - // - // = DESCRIPTION - // This class maps a key to a "destructor." public: + /// Constructor ACE_TSS_Info (ACE_thread_key_t key, void (*dest)(void *) = 0, void *tss_inst = 0); - // Constructor + /// Default constructor ACE_TSS_Info (void); - // Default constructor + /// Returns 1 if the key is in use, 0 if not. int key_in_use (void) const { return thread_count_ != -1; } - // Returns 1 if the key is in use, 0 if not. + /// Mark the key as being in use if the flag is non-zero, or + /// not in use if the flag is 0. void key_in_use (int flag) { thread_count_ = flag == 0 ? -1 : 1; } - // Mark the key as being in use if the flag is non-zero, or - // not in use if the flag is 0. + /// Check for equality. int operator== (const ACE_TSS_Info &) const; - // Check for equality. + /// Check for inequality. int operator!= (const ACE_TSS_Info &) const; - // Check for inequality. + /// Dump the state. void dump (void); - // Dump the state. private: + /// Key to the thread-specific storage item. ACE_thread_key_t key_; - // Key to the thread-specific storage item. + /// "Destructor" that gets called when the item is finally released. void (*destructor_)(void *); - // "Destructor" that gets called when the item is finally released. + /// Pointer to ACE_TSS<xxx> instance that has/will allocate the key. void *tss_obj_; - // Pointer to ACE_TSS<xxx> instance that has/will allocate the key. + /// Count of threads that are using this key. Contains -1 when the + /// key is not in use. int thread_count_; - // Count of threads that are using this key. Contains -1 when the - // key is not in use. friend class ACE_TSS_Cleanup; }; +/** + * @class ACE_TSS_Keys + * + * @brief Collection of in-use flags for a thread's TSS keys. + * For internal use only by ACE_TSS_Cleanup; it is public because + * some compilers can't use nested classes for template instantiation + * parameters. + * + * Wrapper around array of whether each key is in use. A simple + * typedef doesn't work with Sun C++ 4.2. + */ class ACE_TSS_Keys { - // = TITLE - // Collection of in-use flags for a thread's TSS keys. - // For internal use only by ACE_TSS_Cleanup; it is public because - // some compilers can't use nested classes for template instantiation - // parameters. - // - // = DESCRIPTION - // Wrapper around array of whether each key is in use. A simple - // typedef doesn't work with Sun C++ 4.2. public: + /// Default constructor, to initialize all bits to zero (unused). ACE_TSS_Keys (void); - // Default constructor, to initialize all bits to zero (unused). + /// Mark the specified key as being in use, if it was not already so marked. + /// Returns 1 if the had already been marked, 0 if not. int test_and_set (const ACE_thread_key_t key); - // Mark the specified key as being in use, if it was not already so marked. - // Returns 1 if the had already been marked, 0 if not. + /// Mark the specified key as not being in use, if it was not already so + /// cleared. Returns 1 if the had already been cleared, 0 if not. int test_and_clear (const ACE_thread_key_t key); - // Mark the specified key as not being in use, if it was not already so - // cleared. Returns 1 if the had already been cleared, 0 if not. private: + /// For a given key, find the word and bit number that represent it. static void find (const u_int key, u_int &word, u_int &bit); - // For a given key, find the word and bit number that represent it. enum { @@ -6508,9 +6672,9 @@ private: ACE_WORDS = (ACE_DEFAULT_THREAD_KEYS - 1) / ACE_BITS_PER_WORD + 1 }; + /// Bit flag collection. A bit value of 1 indicates that the key is in + /// use by this thread. u_long key_bit_words_[ACE_WORDS]; - // Bit flag collection. A bit value of 1 indicates that the key is in - // use by this thread. }; # endif /* defined (ACE_WIN32) || defined (ACE_HAS_TSS_EMULATION) */ @@ -6931,13 +7095,16 @@ ace_main_i # if defined (ACE_HAS_WINCE) # if defined (ACE_HAS_WINCE_BROKEN_ERRNO) +/** + * @class ACE_CE_Errno + Some versions of CE don't support <errno> and some versions' + * implementations are busted. So we implement our own. + * Our implementation takes up one Tls key, however, it does not + * allocate memory fromt the heap so there's no problem with cleanin + * up the errno when a thread exit. + */ class ACE_Export ACE_CE_Errno { - // Some versions of CE don't support <errno> and some versions' - // implementations are busted. So we implement our own. - // Our implementation takes up one Tls key, however, it does not - // allocate memory fromt the heap so there's no problem with cleanin - // up the errno when a thread exit. public: ACE_CE_Errno () {} static void init (); @@ -6955,72 +7122,74 @@ private: # define errno (* (ACE_CE_Errno::instance ())) # endif /* ACE_HAS_WINCE_BROKEN_ERRNO */ +/** + * @class ACE_CE_Bridge + * + * @brief This class bridges between ACE's default text output windows + * and the original ACE program. + * + * As there is no such thing as text-based programs on Windows + * CE. We need to create a windows to read the command prompt + * and bridge the output windows with the original ACE program + * entry point. You'll need to link your program with + * "ace-windows.lib" for this to work. You can refer to + * $ACE_ROOT/WindowsCE/Main for how I use a dialog box to run + * the original ACE programs. This is certainly not the only + * way to use ACE in Windows programs. + */ class ACE_Export ACE_CE_Bridge { - // = TITLE - // This class bridges between ACE's default text output windows - // and the original ACE program. - // - // = DESCRIPTION - // As there is no such thing as text-based programs on Windows - // CE. We need to create a windows to read the command prompt - // and bridge the output windows with the original ACE program - // entry point. You'll need to link your program with - // "ace-windows.lib" for this to work. You can refer to - // $ACE_ROOT/WindowsCE/Main for how I use a dialog box to run - // the original ACE programs. This is certainly not the only - // way to use ACE in Windows programs. public: + /// Default ctor. ACE_CE_Bridge (void); - // Default ctor. + /// Construct and set the default windows. ACE_CE_Bridge (HWND, int notification, int idc); - // Construct and set the default windows. + /// Default dtor. ~ACE_CE_Bridge (void); - // Default dtor. + /// Specify which window to use. void set_window (HWND, int notification, int idc); - // Specify which window to use. + /// Set the default window. void set_self_default (void); - // Set the default window. + /// Access functions. int notification (void); int idc (void); HWND window (void); - // Access functions. + /// Get the reference of default ACE_CE_BRIDGE. static ACE_CE_Bridge *get_default_winbridge (void); - // Get the reference of default ACE_CE_BRIDGE. + /// Write a string to windows. int write_msg (const ACE_TCHAR *str); - // Write a string to windows. #if 0 + /// Write a CString to windows. Notice that the CString object will + /// be freed by windows. int write_msg (CString *cs); - // Write a CString to windows. Notice that the CString object will - // be freed by windows. #endif /* 0 */ private: // @@ We should use a allocator here. + /// A pointer to the window that knows how to + /// handle ACE related messages. HWND text_output_; - // A pointer to the window that knows how to - // handle ACE related messages. + /// Notification of the window that receives WM_COMMAND when + /// outputing strings. int notification_; - // Notification of the window that receives WM_COMMAND when - // outputing strings. + /// IDC code of the window that receives WM_COMMAND when + /// outputing strings. int idc_; - // IDC code of the window that receives WM_COMMAND when - // outputing strings. ACE_TCHAR *cmdline_; + /// A pointer to the default ACE_CE_BRIDGE obj. static ACE_CE_Bridge *default_text_bridge_; - // A pointer to the default ACE_CE_BRIDGE obj. }; # endif /* ACE_HAS_WINCE */ @@ -7031,56 +7200,54 @@ private: # define ACE_ERRNO_TYPE int #endif /* ACE_HAS_WINCE */ +/** + * @class ACE_Errno_Guard + * + * @brief Provides a wrapper to improve performance when thread-specific + * errno must be saved and restored in a block of code. + * + * The typical use-case for this is the following: + * int error = errno; + * call_some_function_that_might_change_errno (); + * errno = error; + * This can be replaced with + * { + * ACE_Errno_Guard guard (errno); + * call_some_function_that_might_change_errno (); + * } + * This implementation is more elegant and more efficient since it + * avoids an unnecessary second access to thread-specific storage + * by caching a pointer to the value of errno in TSS. + */ class ACE_Export ACE_Errno_Guard { - // = TITLE - // Provides a wrapper to improve performance when thread-specific - // errno must be saved and restored in a block of code. - // - // = DESCRIPTION - // The typical use-case for this is the following: - // - // int error = errno; - // call_some_function_that_might_change_errno (); - // errno = error; - // - // This can be replaced with - // - // { - // ACE_Errno_Guard guard (errno); - // call_some_function_that_might_change_errno (); - // } - // - // This implementation is more elegant and more efficient since it - // avoids an unnecessary second access to thread-specific storage - // by caching a pointer to the value of errno in TSS. public: // = Initialization and termination methods. + /// Stash the value of <error> into <error_> and initialize the + /// <errno_ptr_> to the address of <errno_ref>. ACE_Errno_Guard (ACE_ERRNO_TYPE &errno_ref, int error); - // Stash the value of <error> into <error_> and initialize the - // <errno_ptr_> to the address of <errno_ref>. + /// Stash the value of <errno> into <error_> and initialize the + /// <errno_ptr_> to the address of <errno_ref>. ACE_Errno_Guard (ACE_ERRNO_TYPE &errno_ref); - // Stash the value of <errno> into <error_> and initialize the - // <errno_ptr_> to the address of <errno_ref>. + /// Reset the value of <errno> to <error>. ~ACE_Errno_Guard (void); - // Reset the value of <errno> to <error>. #if defined (ACE_HAS_WINCE_BROKEN_ERRNO) + /// Assign <errno_ref> to <error_>. int operator= (const ACE_ERRNO_TYPE &errno_ref); - // Assign <errno_ref> to <error_>. #endif /* ACE_HAS_WINCE_BROKEN_ERRNO */ + /// Assign <error> to <error_>. int operator= (int error); - // Assign <error> to <error_>. + /// Compare <error> with <error_> for equality. int operator== (int error); - // Compare <error> with <error_> for equality. + /// Compare <error> with <error_> for inequality. int operator!= (int error); - // Compare <error> with <error_> for inequality. private: #if defined (ACE_MT_SAFE) diff --git a/ace/OS_Dirent.h b/ace/OS_Dirent.h index 8137da9338b..0d25cbd9d51 100644 --- a/ace/OS_Dirent.h +++ b/ace/OS_Dirent.h @@ -1,20 +1,17 @@ // -*- C++ -*- -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// OS_Dirent.h -// -// = AUTHOR -// (Originally in OS.h) -// Doug Schmidt <schmidt@cs.wustl.edu>, Jesper S. M|ller -// <stophph@diku.dk>, and a cast of thousands... -// -// ============================================================================ + +//============================================================================= +/** + * @file OS_Dirent.h + * + * $Id$ + * + * @author Doug Schmidt <schmidt@cs.wustl.edu> + * @author Jesper S. M|ller<stophph@diku.dk> + * @author and a cast of thousands... + */ +//============================================================================= + #ifndef ACE_OS_DIRENT_H #define ACE_OS_DIRENT_H @@ -78,11 +75,13 @@ typedef XDIR DIR; # undef rewinddir #endif /* rewinddir */ +/** + * @class ACE_OS_Dirent + * + * @brief This class is a wrapper for the dirent.h operations + * + */ class ACE_OS_Export ACE_OS_Dirent - // = TITLE - // This class is a wrapper for the dirent.h operations - // - // = DESCRIPTION { public: static DIR *opendir (const ACE_TCHAR *filename); diff --git a/ace/OS_Log_Msg_Attributes.h b/ace/OS_Log_Msg_Attributes.h index a268d991f3a..810cb4bae98 100644 --- a/ace/OS_Log_Msg_Attributes.h +++ b/ace/OS_Log_Msg_Attributes.h @@ -1,18 +1,15 @@ // -*- C++ -*- -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// OS_Log_Msg_Attributes.h -// -// = AUTHOR -// Carlos O'Ryan -// -// ============================================================================ + +//============================================================================= +/** + * @file OS_Log_Msg_Attributes.h + * + * $Id$ + * + * @author Carlos O'Ryan + */ +//============================================================================= + #ifndef ACE_OS_LOG_MSG_ATTRIBUTES_H #define ACE_OS_LOG_MSG_ATTRIBUTES_H diff --git a/ace/OS_Memory.h b/ace/OS_Memory.h index 1b115230dcc..1c70293ca56 100644 --- a/ace/OS_Memory.h +++ b/ace/OS_Memory.h @@ -1,20 +1,17 @@ // -*- C++ -*- -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// OS_Memory.h -// -// = AUTHOR -// (Originally in OS.h) -// Doug Schmidt <schmidt@cs.wustl.edu>, Jesper S. M|ller -// <stophph@diku.dk>, and a cast of thousands... -// -// ============================================================================ +//============================================================================= +/** + * @file OS_Memory.h + * + * $Id$ + * + * @author Doug Schmidt <schmidt@cs.wustl.edu> + * @author Jesper S. M|ller<stophph@diku.dk> + * @author and a cast of thousands... + */ +//============================================================================= + #ifndef ACE_OS_MEMORY_H #define ACE_OS_MEMORY_H @@ -100,12 +97,14 @@ typedef void *ACE_MALLOC_T; # endif /* ACE_HAS_OLD_MALLOC */ #endif /* ACE_HAS_PACE */ +/** + * @class ACE_OS_Memory + * + * @brief This class is a wrapper for memory operations, like + * malloc, memcpy, etc. + * + */ class ACE_OS_Export ACE_OS_Memory - // = TITLE - // This class is a wrapper for memory operations, like - // malloc, memcpy, etc. - // - // = DESCRIPTION { public: // = A set of wrappers for memory managment. diff --git a/ace/OS_String.h b/ace/OS_String.h index a3746d42840..19a3e1f5a10 100644 --- a/ace/OS_String.h +++ b/ace/OS_String.h @@ -42,9 +42,9 @@ class ACE_OS_Export ACE_OS_String public: /** @name Functions from <cstring> * - * Included are the functions defined in <cstring> and their <cwchar> + * Included are the functions defined in <cstring> and their <cwchar> * equivalents. - * + * * @todo To be complete, we should add strcoll, strerror, and strxfrm. */ //@{ @@ -63,7 +63,7 @@ public: /// Moves one buffer to another. static void *memmove (void *t, const void *s, size_t len); - + /// Fills a buffer with a character value. static void *memset (void *s, int c, size_t len); @@ -75,7 +75,7 @@ public: static wchar_t *strcat (wchar_t *s, const wchar_t *t); #endif /* ACE_HAS_WCHAR */ - /// Finds the first occurance of a character in a string (const char + /// Finds the first occurance of a character in a string (const char /// version). static const char *strchr (const char *s, int c); @@ -85,7 +85,7 @@ public: static const wchar_t *strchr (const wchar_t *s, wint_t c); #endif /* ACE_HAS_WCHAR */ - /// Finds the first occurance of a character in a string (char version). + /// Finds the first occurance of a character in a string (char version). static char *strchr (char *s, int c); #if defined (ACE_HAS_WCHAR) @@ -95,7 +95,7 @@ public: /// Compares two strings (char version). static int strcmp (const char *s, const char *t); - + #if defined (ACE_HAS_WCHAR) /// Compares two strings (wchar_t version). static int strcmp (const wchar_t *s, const wchar_t *t); @@ -112,7 +112,7 @@ public: /// Searches for the first substring without any of the specified /// characters and returns the size of the substring (char version). static size_t strcspn (const char *s, const char *reject); - + #if defined (ACE_HAS_WCHAR) /// Searches for the first substring without any of the specified /// characters and returns the size of the substring (wchar_t version). @@ -137,7 +137,7 @@ public: /// Compares two arrays (char version). static int strncmp (const char *s, const char *t, size_t len); - + #if defined (ACE_HAS_WCHAR) /// Compares two arrays (wchar_t version). static int strncmp (const wchar_t *s, const wchar_t *t, size_t len); @@ -167,12 +167,12 @@ public: static wchar_t *strpbrk (wchar_t *s1, const wchar_t *s2); #endif /* ACE_HAS_WCHAR */ - /// Finds the last occurance of a character in a string (const char + /// Finds the last occurance of a character in a string (const char /// version). static const char *strrchr (const char *s, int c); #if defined (ACE_HAS_WCHAR) - /// Finds the last occurance of a character in a string (const wchar_t + /// Finds the last occurance of a character in a string (const wchar_t /// version). static const wchar_t *strrchr (const wchar_t *s, wint_t c); #endif /* ACE_HAS_WCHAR */ @@ -195,7 +195,7 @@ public: static size_t strspn (const wchar_t *s1, const wchar_t *s2); #endif /* ACE_HAS_WCHAR */ - /// Finds the first occurance of a substring in a string (const char + /// Finds the first occurance of a substring in a string (const char /// version). static const char *strstr (const char *s, const char *t); @@ -225,7 +225,7 @@ public: /** @name Functions from <cctype> * - * Included are the functions defined in <cctype> and their <cwctype> + * Included are the functions defined in <cctype> and their <cwctype> * equivalents. * * Since they are often implemented as macros, we don't use the same name @@ -255,7 +255,7 @@ public: //@} /** @name Non-standard functions - * + * * These functions aren't in the standard. * */ @@ -277,12 +277,12 @@ public: static int strcasecmp (const wchar_t *s, const wchar_t *t); #endif /* ACE_HAS_WCHAR */ - /// Finds the first occurance of a character in an array (const char + /// Finds the first occurance of a character in an array (const char /// version). static const char *strnchr (const char *s, int c, size_t len); #if defined (ACE_HAS_WCHAR) - /// Finds the first occurance of a character in an array (const wchar_t + /// Finds the first occurance of a character in an array (const wchar_t /// version). static const wchar_t *strnchr (const wchar_t *s, wint_t c, size_t len); #endif /* ACE_HAS_WCHAR */ @@ -313,15 +313,15 @@ public: static wchar_t *strecpy (wchar_t *s, const wchar_t *t); #endif /* ACE_HAS_WCHAR */ - /// Finds the first occurance of a substring in an array (const char + /// Finds the first occurance of a substring in an array (const char /// version). static const char *strnstr (const char *s, const char *t, size_t len); #if defined (ACE_HAS_WCHAR) - /// Finds the first occurance of a substring in an array (const wchar_t + /// Finds the first occurance of a substring in an array (const wchar_t /// version). - static const wchar_t *strnstr (const wchar_t *s, - const wchar_t *t, + static const wchar_t *strnstr (const wchar_t *s, + const wchar_t *t, size_t len); #endif /* ACE_HAS_WCHAR */ @@ -334,7 +334,7 @@ public: #endif /* ACE_HAS_WCHAR */ /// Returns a malloced duplicated string (char version). - static char *strdup (const char *s); + static char *strdup (const char *s); #if defined (ACE_HAS_WCHAR) /// Returns a malloced duplicated string (wchar_t version). @@ -408,25 +408,25 @@ private: #endif /* ACE_LACKS_STRCSPN */ #if defined (ACE_LACKS_STRCHR) - /// Emulated strchr (char version) - Finds the first occurance of a + /// Emulated strchr (char version) - Finds the first occurance of a /// character in a string. static char *strchr_emulation (char *s, int c); - /// Emulated strchr (const char version) - Finds the first occurance of a + /// Emulated strchr (const char version) - Finds the first occurance of a /// character in a string. static const char *strchr_emulation (const char *s, int c); #endif /* ACE_LACKS_STRCHR */ #if defined (ACE_LACKS_STRRCHR) - /// Emulated strrchr (char version) - Finds the last occurance of a + /// Emulated strrchr (char version) - Finds the last occurance of a /// character in a string. static char *strrchr_emulation (char *s, int c); - /// Emulated strrchr (const char version) - Finds the last occurance of a + /// Emulated strrchr (const char version) - Finds the last occurance of a /// character in a string. static const char *strrchr_emulation (const char *s, int c); #endif /* ACE_LACKS_STRRCHR */ - + #if !defined (ACE_HAS_REENTRANT_FUNCTIONS) /// Emulated strtok_r. static char *strtok_r_emulation (char *s, const char *tokens, char **lasts); @@ -434,7 +434,7 @@ private: #if defined (ACE_HAS_WCHAR) && defined (ACE_LACKS_WCSCAT) /// Emulated wcscat - Appends a string. - static wchar_t *wcscat_emulation (wchar_t *destination, + static wchar_t *wcscat_emulation (wchar_t *destination, const wchar_t *source); #endif /* ACE_HAS_WCHAR && ACE_LACKS_WCSCAT */ @@ -450,13 +450,13 @@ private: #if defined (ACE_HAS_WCHAR) && defined (ACE_LACKS_WCSCPY) /// Emulated wcscpy - Copies a string. - static wchar_t *wcscpy_emulation (wchar_t *destination, + static wchar_t *wcscpy_emulation (wchar_t *destination, const wchar_t *source); #endif /* ACE_HAS_WCHAR && ACE_LACKS_WCSCPY */ #if defined (ACE_HAS_WCHAR) && defined (ACE_LACKS_WCSICMP) /// Emulated wcsicmp - Performs a case insensitive comparison of strings. - static int wcsicmp_emulation (const wchar_t *string1, + static int wcsicmp_emulation (const wchar_t *string1, const wchar_t *string2); #endif /* ACE_HAS_WCHAR && ACE_LACKS_WCSICMP */ @@ -467,36 +467,36 @@ private: #if defined (ACE_HAS_WCHAR) && defined (ACE_LACKS_WCSNCAT) /// Emulated wcscat - Appends a string. - static wchar_t *wcsncat_emulation (wchar_t *destination, + static wchar_t *wcsncat_emulation (wchar_t *destination, const wchar_t *source, size_t count); #endif /* ACE_HAS_WCHAR && ACE_LACKS_WCSCAT */ #if defined (ACE_HAS_WCHAR) && defined (ACE_LACKS_WCSNCMP) /// Emulated wcsncmp - Compares two arrays. - static int wcsncmp_emulation (const wchar_t *string1, - const wchar_t *string2, + static int wcsncmp_emulation (const wchar_t *string1, + const wchar_t *string2, size_t len); #endif /* ACE_HAS_WCHAR && ACE_LACKS_WCSNCMP */ #if defined (ACE_HAS_WCHAR) && defined (ACE_LACKS_WCSNCPY) /// Emulated wcsncpy - Copies an array. - static wchar_t *wcsncpy_emulation (wchar_t *destination, - const wchar_t *source, + static wchar_t *wcsncpy_emulation (wchar_t *destination, + const wchar_t *source, size_t len); #endif /* ACE_HAS_WCHAR && ACE_LACKS_WCSNCPY */ #if defined (ACE_HAS_WCHAR) && defined (ACE_LACKS_WCSNICMP) /// Emulated wcsnicmp - Performs a case insensitive comparison of two /// arrays - static int wcsnicmp_emulation (const wchar_t *string1, - const wchar_t *string2, + static int wcsnicmp_emulation (const wchar_t *string1, + const wchar_t *string2, size_t len); #endif /* ACE_HAS_WCHAR && ACE_LACKS_WCSNICMP */ #if defined (ACE_HAS_WCHAR) && defined (ACE_LACKS_WCSPBRK) /// Emulated wcspbrk - Searches for characters in a string. - static wchar_t *wcspbrk_emulation (const wchar_t *string, + static wchar_t *wcspbrk_emulation (const wchar_t *string, const wchar_t *charset); #endif /* ACE_HAS_WCHAR && ACE_LACKS_WCSPBRK */ @@ -512,24 +512,24 @@ private: #if defined (ACE_HAS_WCHAR) && defined (ACE_LACKS_WCSCSPN) /// Emulated wcsspn. - static size_t wcscspn_emulation (const wchar_t *string, + static size_t wcscspn_emulation (const wchar_t *string, const wchar_t *reject); #endif /* ACE_HAS_WCHAR && ACE_LACKS_WCSCSPN */ #if defined (ACE_HAS_WCHAR) && defined (ACE_LACKS_WCSSPN) /// Emulated wcsspn. - static size_t wcsspn_emulation (const wchar_t *string, + static size_t wcsspn_emulation (const wchar_t *string, const wchar_t *charset); #endif /* ACE_HAS_WCHAR && ACE_LACKS_WCSSPN */ #if defined (ACE_HAS_WCHAR) && defined (ACE_LACKS_WCSSTR) /// Emulated wcsstr - Performs a case insensitive comparison of two strings. - static wchar_t *wcsstr_emulation (const wchar_t *string, + static wchar_t *wcsstr_emulation (const wchar_t *string, const wchar_t *charset); #endif /* ACE_HAS_WCHAR && ACE_LACKS_WCSSTR */ //@} -}; +}; # if defined (ACE_HAS_INLINED_OSCALLS) # if defined (ACE_INLINE) diff --git a/ace/OS_TLI.h b/ace/OS_TLI.h index 6b15485d629..46e4cba0e00 100644 --- a/ace/OS_TLI.h +++ b/ace/OS_TLI.h @@ -1,20 +1,17 @@ // -*- C++ -*- -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// OS_TLI.h -// -// = AUTHOR -// (Originally in OS.h) -// Doug Schmidt <schmidt@cs.wustl.edu>, Jesper S. M|ller -// <stophph@diku.dk>, and a cast of thousands... -// -// ============================================================================ + +//============================================================================= +/** + * @file OS_TLI.h + * + * $Id$ + * + * @author Doug Schmidt <schmidt@cs.wustl.edu> + * @author Jesper S. M|ller<stophph@diku.dk> + * @author and a cast of thousands... + */ +//============================================================================= + #ifndef ACE_OS_TLI_H #define ACE_OS_TLI_H @@ -122,11 +119,13 @@ extern "C" int _xti_error(char *); # endif /* UNIXWARE */ # endif /* ACE_REDEFINES_XTI_FUNCTIONS */ +/** + * @class ACE_OS_TLI + * + * @brief This class is a wrapper for the TLI operations + * + */ class ACE_OS_Export ACE_OS_TLI - // = TITLE - // This class is a wrapper for the TLI operations - // - // = DESCRIPTION { public: // = A set of wrappers for TLI. diff --git a/ace/OS_Thread_Adapter.h b/ace/OS_Thread_Adapter.h index faed0883a62..eca9616cd74 100644 --- a/ace/OS_Thread_Adapter.h +++ b/ace/OS_Thread_Adapter.h @@ -1,17 +1,14 @@ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Thread_Adapter.h -// -// = AUTHOR -// Carlos O'Ryan <coryan@uci.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Thread_Adapter.h + * + * $Id$ + * + * @author Carlos O'Ryan <coryan@uci.edu> + */ +//============================================================================= + #ifndef ACE_OS_THREAD_ADAPTER_H #define ACE_OS_THREAD_ADAPTER_H @@ -25,21 +22,23 @@ #include "ace/OS_Export.h" +/** + * @class ACE_OS_Thread_Adapter + * + * @brief Converts a C++ function into a function <ace_thread_adapter> + * function that can be called from a thread creation routine + * (e.g., <pthread_create> or <_beginthreadex>) that expects an + * extern "C" entry point. This class also makes it possible to + * transparently provide hooks to register a thread with an + * <ACE_Thread_Manager>. + * + * This class is used in <ACE_OS::thr_create>. In general, the + * thread that creates an object of this class is different from + * the thread that calls <invoke> on this object. Therefore, + * the <invoke> method is responsible for deleting itself. + */ class ACE_OS_Export ACE_OS_Thread_Adapter : public ACE_Base_Thread_Adapter { - // = TITLE - // Converts a C++ function into a function <ace_thread_adapter> - // function that can be called from a thread creation routine - // (e.g., <pthread_create> or <_beginthreadex>) that expects an - // extern "C" entry point. This class also makes it possible to - // transparently provide hooks to register a thread with an - // <ACE_Thread_Manager>. - // - // = DESCRIPTION - // This class is used in <ACE_OS::thr_create>. In general, the - // thread that creates an object of this class is different from - // the thread that calls <invoke> on this object. Therefore, - // the <invoke> method is responsible for deleting itself. public: ACE_OS_Thread_Adapter (ACE_THR_FUNC user_func, void *arg, @@ -48,22 +47,24 @@ public: , ACE_SEH_EXCEPT_HANDLER selector = 0 , ACE_SEH_EXCEPT_HANDLER handler = 0 # endif /* ACE_HAS_WIN32_STRUCTURAL_EXCEPTIONS */ + /// Constructor. ); - // Constructor. + /** + * Execute the <user_func_> with the <arg>. This function deletes + * <this>, thereby rendering the object useless after the call + * returns. + */ virtual void *invoke (void); - // Execute the <user_func_> with the <arg>. This function deletes - // <this>, thereby rendering the object useless after the call - // returns. private: + /// Ensure that this object must be allocated on the heap. ~ACE_OS_Thread_Adapter (void); - // Ensure that this object must be allocated on the heap. private: + /// Friend declaration to avoid compiler warning: only defines a private + /// destructor and has no friends. friend class ACE_Thread_Adapter_Has_Private_Destructor; - // Friend declaration to avoid compiler warning: only defines a private - // destructor and has no friends. }; # if defined (ACE_HAS_INLINED_OSCALLS) diff --git a/ace/Object_Manager.h b/ace/Object_Manager.h index 101fbaf0927..fb97befe59d 100644 --- a/ace/Object_Manager.h +++ b/ace/Object_Manager.h @@ -1,18 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Object_Manager.h -// -// = AUTHORS -// David L. Levine, Matthias Kerkhoff, and Per Andersson -// -// ============================================================================ + +//============================================================================= +/** + * @file Object_Manager.h + * + * $Id$ + * + * @author David L. Levine + * @author Matthias Kerkhoff + * @author and Per Andersson + */ +//============================================================================= + #ifndef ACE_OBJECT_MANAGER_H #define ACE_OBJECT_MANAGER_H @@ -54,199 +53,202 @@ template <class T> class ACE_Cleanup_Adapter; #endif /* ! ACE_APPLICATION_PREALLOCATED_ARRAY_DECLARATIONS */ +/** + * @class ACE_Object_Manager + * + * @brief Manager for ACE library services and singleton cleanup. + * + * The <ACE_Object_Manager> manages cleanup of objects, typically + * singletons, at program termination. In addition to managing + * the cleanup of the ACE library, it provides an interface for + * application to register objects to be cleaned up. + * This class also shuts down ACE library services, so that they + * can reclaim their storage, at program termination. It works + * by creating a static instance whose destructor gets called + * along with those of all other static objects. Hooks are + * provided for application code to register objects and arrays + * for cleanup, e.g., destruction. The order of such cleanup + * calls is in the reverse order of registration, i.e., that + * last object/array to register gets cleaned up first. + * The <ACE_Object_Manager> API includes <ACE_Managed_Object>. That + * class is contained in a separate file because it is a + * template class, and some compilers require that template and + * non-template class definitions appear in separate files. + * Please see ace/Managed_Object.h for a description of that + * part of the API. In summary, <ACE_Managed_Object> provides two + * adapters, the <ACE_Cleanup_Adapter> and <ACE_Managed_Object> + * template classes for adapting objects of any type to be + * easily managed by the <ACE_Object_Manager>. There are several + * mechanisms for adapting objects and arrays for cleanup at + * program termination, in roughly increasing order of ease-of-use: + * 1) Derive the object's class from <ACE_Cleanup>. + * 2) Allow the <ACE_Object_Manager> to both dynamically allocate + * and deallocate the object. + * 3) Provide an <ACE_CLEANUP_FUNC> cleanup hook for the object or + * array. + * 4) Allow the <ACE_Object_Manager> to both preallocate the object + * or array, either statically in global data or dynamically on + * the heap, when its singleton instance is construction. + * + * There are also several mechanisms for registering objects and + * arrays for cleanup. In decreasing order of flexibility and + * complexity (with the exception of the last mechanism): + * + * 1) ACE_Object_Manager::at_exit (void *object, + * ACE_CLEANUP_FUNC cleanup_hook, + * void *param); + * can be used to register any object or array for any + * cleanup activity at program termination. + * 2) ACE_Object_Manager::at_exit (ACE_Cleanup *object, + * void *param = 0); + * can be used to register an <ACE_Cleanup> object + * for any cleanup activity at program termination. + * The final mechanism is not general purpose, but can only + * be used to allocate objects and arrays at program startup: + * 3) ACE_Managed_Object::get_preallocated_object + * (ACE_Object_Manager::Preallocated_Object id); + * and + * ACE_Managed_Object::get_preallocated_array + * (ACE_Object_Manager::Preallocated_Array id); + * can only be used to allocate objects at program startup, + * either in global data or on the heap (selected at compile + * time). These are intended to replace static locks, etc. + * Instead of creating a static <ACE_Object_Manager> instance, one + * can alternatively be created on the stack of the main program + * thread. It is created just after entry to ::main (int, char + * *[]), and before any existing code in that function is + * executed. To enable this alternative, add #define + * ACE_HAS_NONSTATIC_OBJECT_MANAGER before including the platform + * specific config-* file in ace/config.h prior to + * building the ACE library and your applications. This #define + * is enabled in some config files that are supplied with ACE. + * + * To ensure a static object manager is used, #undef + * ACE_HAS_NONSTATIC_OBJECT_MANAGER *after* including the platform + * specific config-* file. + * Note that the ACE_Object_Manager _must_ be created before + * any threads are spawned by the program. + * If ACE_HAS_NONSTATIC_OBJECT_MANAGER is not #defined, the ACE + * library creates a static, singleton <ACE_Object_Manager> instance. + * The instance is placed in global program data, and constructed + * via a static object constructor. If ACE_HAS_NONSTATIC_OBJECT_MANAGER + * is #defined, the <ACE_Object_Manager> instance is created on the stack + * of the main program thread, as noted above. + * + * With ACE_HAS_NONSTATIC_OBJECT_MANAGER enabled, the ACE + * library has no static objects that require destruction. + * However, there are two drawbacks to using it: + * 1) main (int, char *[]) must be declared with arguments, even + * if they're not used. All of ACE is converted to this, so + * just applications have to be concerned with it. + * 2) If there any static objects that depend on those that are + * cleaned up by the Object_Manager, they'll get cleaned up too + * late. The ACE tests do not violate this requirement. + * However, applications may have trouble with it. + * NOTE on the use of <::exit> -- <::exit> does not destroy + * automatic objects. Therefore, if + * ACE_HAS_NONSTATIC_OBJECT_MANAGER is enabled, the + * <ACE_Object_Manager> instance will *not* be destroyed if + * <::exit> is called! However, <ACE_OS::exit> will properly + * destroy the ACE_Object_Manager. It is highly recommended + * that <ACE_OS::exit> be used instead of <::exit>. + * + * However, <::exit> and <ACE_OS::exit> are tricky to use + * properly, especially in multithread programs. It is much + * safer to throw an exception (or simulate that effect) that + * will be caught by <main> instead of calling exit. Then, + * <main> can perform any necessary application-specific cleanup + * and return the status value. In addition, it's usually best + * to avoid calling <::exit> and <ACE_OS::exit> from threads + * other than the main thread. Thanks to Jeff Greif + * <jmg@trivida.com> for pointing out that <::exit> doesn't + * destroy automatic objects, and for developing the + * recommendations in this paragraph. + * + * Instead of creating a static <ACE_Object_Manager>, or letting + * ACE create it on the stack of <main> for you, another + * alternative is to #define + * ACE_DOESNT_INSTANTIATE_NONSTATIC_OBJECT_MANAGER. With that + * #define, the application must create the ACE_Object_Manager. + * The recommended way is to call <ACE::init> at the start of + * the program, and call <ACE::fini> at the end. Alternatively, + * the application could explicity construct an + * <ACE_Object_Manager>. + */ class ACE_Export ACE_Object_Manager : public ACE_Object_Manager_Base { - // = TITLE - // Manager for ACE library services and singleton cleanup. - // - // = DESCRIPTION - // The <ACE_Object_Manager> manages cleanup of objects, typically - // singletons, at program termination. In addition to managing - // the cleanup of the ACE library, it provides an interface for - // application to register objects to be cleaned up. - // - // This class also shuts down ACE library services, so that they - // can reclaim their storage, at program termination. It works - // by creating a static instance whose destructor gets called - // along with those of all other static objects. Hooks are - // provided for application code to register objects and arrays - // for cleanup, e.g., destruction. The order of such cleanup - // calls is in the reverse order of registration, i.e., that - // last object/array to register gets cleaned up first. - // - // The <ACE_Object_Manager> API includes <ACE_Managed_Object>. That - // class is contained in a separate file because it is a - // template class, and some compilers require that template and - // non-template class definitions appear in separate files. - // Please see ace/Managed_Object.h for a description of that - // part of the API. In summary, <ACE_Managed_Object> provides two - // adapters, the <ACE_Cleanup_Adapter> and <ACE_Managed_Object> - // template classes for adapting objects of any type to be - // easily managed by the <ACE_Object_Manager>. There are several - // mechanisms for adapting objects and arrays for cleanup at - // program termination, in roughly increasing order of ease-of-use: - // - // 1) Derive the object's class from <ACE_Cleanup>. - // 2) Allow the <ACE_Object_Manager> to both dynamically allocate - // and deallocate the object. - // 3) Provide an <ACE_CLEANUP_FUNC> cleanup hook for the object or - // array. - // 4) Allow the <ACE_Object_Manager> to both preallocate the object - // or array, either statically in global data or dynamically on - // the heap, when its singleton instance is construction. - // - // There are also several mechanisms for registering objects and - // arrays for cleanup. In decreasing order of flexibility and - // complexity (with the exception of the last mechanism): - // - // 1) ACE_Object_Manager::at_exit (void *object, - // ACE_CLEANUP_FUNC cleanup_hook, - // void *param); - // can be used to register any object or array for any - // cleanup activity at program termination. - // - // 2) ACE_Object_Manager::at_exit (ACE_Cleanup *object, - // void *param = 0); - // can be used to register an <ACE_Cleanup> object - // for any cleanup activity at program termination. - // - // The final mechanism is not general purpose, but can only - // be used to allocate objects and arrays at program startup: - // - // 3) ACE_Managed_Object::get_preallocated_object - // (ACE_Object_Manager::Preallocated_Object id); - // and - // ACE_Managed_Object::get_preallocated_array - // (ACE_Object_Manager::Preallocated_Array id); - // can only be used to allocate objects at program startup, - // either in global data or on the heap (selected at compile - // time). These are intended to replace static locks, etc. - // - // Instead of creating a static <ACE_Object_Manager> instance, one - // can alternatively be created on the stack of the main program - // thread. It is created just after entry to ::main (int, char - // *[]), and before any existing code in that function is - // executed. To enable this alternative, add #define - // ACE_HAS_NONSTATIC_OBJECT_MANAGER before including the platform - // specific config-* file in ace/config.h prior to - // building the ACE library and your applications. This #define - // is enabled in some config files that are supplied with ACE. - // To ensure a static object manager is used, #undef - // ACE_HAS_NONSTATIC_OBJECT_MANAGER *after* including the platform - // specific config-* file. - // - // Note that the ACE_Object_Manager _must_ be created before - // any threads are spawned by the program. - // - // If ACE_HAS_NONSTATIC_OBJECT_MANAGER is not #defined, the ACE - // library creates a static, singleton <ACE_Object_Manager> instance. - // The instance is placed in global program data, and constructed - // via a static object constructor. If ACE_HAS_NONSTATIC_OBJECT_MANAGER - // is #defined, the <ACE_Object_Manager> instance is created on the stack - // of the main program thread, as noted above. - // - // With ACE_HAS_NONSTATIC_OBJECT_MANAGER enabled, the ACE - // library has no static objects that require destruction. - // However, there are two drawbacks to using it: - // - // 1) main (int, char *[]) must be declared with arguments, even - // if they're not used. All of ACE is converted to this, so - // just applications have to be concerned with it. - // - // 2) If there any static objects that depend on those that are - // cleaned up by the Object_Manager, they'll get cleaned up too - // late. The ACE tests do not violate this requirement. - // However, applications may have trouble with it. - // - // NOTE on the use of <::exit> -- <::exit> does not destroy - // automatic objects. Therefore, if - // ACE_HAS_NONSTATIC_OBJECT_MANAGER is enabled, the - // <ACE_Object_Manager> instance will *not* be destroyed if - // <::exit> is called! However, <ACE_OS::exit> will properly - // destroy the ACE_Object_Manager. It is highly recommended - // that <ACE_OS::exit> be used instead of <::exit>. - // - // However, <::exit> and <ACE_OS::exit> are tricky to use - // properly, especially in multithread programs. It is much - // safer to throw an exception (or simulate that effect) that - // will be caught by <main> instead of calling exit. Then, - // <main> can perform any necessary application-specific cleanup - // and return the status value. In addition, it's usually best - // to avoid calling <::exit> and <ACE_OS::exit> from threads - // other than the main thread. Thanks to Jeff Greif - // <jmg@trivida.com> for pointing out that <::exit> doesn't - // destroy automatic objects, and for developing the - // recommendations in this paragraph. - // - // Instead of creating a static <ACE_Object_Manager>, or letting - // ACE create it on the stack of <main> for you, another - // alternative is to #define - // ACE_DOESNT_INSTANTIATE_NONSTATIC_OBJECT_MANAGER. With that - // #define, the application must create the ACE_Object_Manager. - // The recommended way is to call <ACE::init> at the start of - // the program, and call <ACE::fini> at the end. Alternatively, - // the application could explicity construct an - // <ACE_Object_Manager>. public: + /** + * Explicitly initialize (construct the singleton instance of) the + * ACE_Object_Manager. Returns 0 on success, -1 on failure, and 1 + * if it had already been called. + */ virtual int init (void); - // Explicitly initialize (construct the singleton instance of) the - // ACE_Object_Manager. Returns 0 on success, -1 on failure, and 1 - // if it had already been called. + /** + * Explicitly destroy the singleton instance of the + * ACE_Object_Manager. Returns 0 on success, -1 on failure, and 1 + * if it had already been called. + */ virtual int fini (void); - // Explicitly destroy the singleton instance of the - // ACE_Object_Manager. Returns 0 on success, -1 on failure, and 1 - // if it had already been called. + /** + * Returns 1 before the ACE_Object_Manager has been constructed. + * This flag can be used to determine if the program is constructing + * static objects. If no static object spawns any threads, the + * program will be single-threaded when this flag returns 1. (Note + * that the program still might construct some static objects when + * this flag returns 0, if ACE_HAS_NONSTATIC_OBJECT_MANAGER is not + * defined.) + */ static int starting_up (void); - // Returns 1 before the ACE_Object_Manager has been constructed. - // This flag can be used to determine if the program is constructing - // static objects. If no static object spawns any threads, the - // program will be single-threaded when this flag returns 1. (Note - // that the program still might construct some static objects when - // this flag returns 0, if ACE_HAS_NONSTATIC_OBJECT_MANAGER is not - // defined.) + /** + * Returns 1 after the ACE_Object_Manager has been destroyed. This + * flag can be used to determine if the program is in the midst of + * destroying static objects. (Note that the program might destroy + * some static objects before this flag can return 1, if + * ACE_HAS_NONSTATIC_OBJECT_MANAGER is not defined.) + */ static int shutting_down (void); - // Returns 1 after the ACE_Object_Manager has been destroyed. This - // flag can be used to determine if the program is in the midst of - // destroying static objects. (Note that the program might destroy - // some static objects before this flag can return 1, if - // ACE_HAS_NONSTATIC_OBJECT_MANAGER is not defined.) + /** + * Register an ACE_Cleanup object for cleanup at process + * termination. The object is deleted via the + * <ace_cleanup_destroyer>. If you need more flexiblity, see the + * <other at_exit> method below. For OS's that do not have + * processes, cleanup takes place at the end of <main>. Returns 0 + * on success. On failure, returns -1 and sets errno to: EAGAIN if + * shutting down, ENOMEM if insufficient virtual memory, or EEXIST + * if the object (or array) had already been registered. + */ static int at_exit (ACE_Cleanup *object, void *param = 0); - // Register an ACE_Cleanup object for cleanup at process - // termination. The object is deleted via the - // <ace_cleanup_destroyer>. If you need more flexiblity, see the - // <other at_exit> method below. For OS's that do not have - // processes, cleanup takes place at the end of <main>. Returns 0 - // on success. On failure, returns -1 and sets errno to: EAGAIN if - // shutting down, ENOMEM if insufficient virtual memory, or EEXIST - // if the object (or array) had already been registered. + /** + * Register an object (or array) for cleanup at process termination. + * "cleanup_hook" points to a (global, or static member) function + * that is called for the object or array when it to be destroyed. + * It may perform any necessary cleanup specific for that object or + * its class. "param" is passed as the second parameter to the + * "cleanup_hook" function; the first parameter is the object (or + * array) to be destroyed. "cleanup_hook", for example, may delete + * the object (or array). For OS's that do not have processes, this + * function is the same as <at_thread_exit>. Returns 0 on success. + * On failure, returns -1 and sets errno to: EAGAIN if shutting + * down, ENOMEM if insufficient virtual memory, or EEXIST if the + * object (or array) had already been registered. + */ static int at_exit (void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param); - // Register an object (or array) for cleanup at process termination. - // "cleanup_hook" points to a (global, or static member) function - // that is called for the object or array when it to be destroyed. - // It may perform any necessary cleanup specific for that object or - // its class. "param" is passed as the second parameter to the - // "cleanup_hook" function; the first parameter is the object (or - // array) to be destroyed. "cleanup_hook", for example, may delete - // the object (or array). For OS's that do not have processes, this - // function is the same as <at_thread_exit>. Returns 0 on success. - // On failure, returns -1 and sets errno to: EAGAIN if shutting - // down, ENOMEM if insufficient virtual memory, or EEXIST if the - // object (or array) had already been registered. #if 0 /* not implemented yet */ + /// Similar to <at_exit>, except that the cleanup_hook is called + /// when the current thread exits instead of when the program terminates. static int at_thread_exit (void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param); - // Similar to <at_exit>, except that the cleanup_hook is called - // when the current thread exits instead of when the program terminates. #endif /* 0 */ enum Preallocated_Object @@ -295,71 +297,85 @@ public: // ace/Managed_Object.h for information on accessing preallocated // arrays. + /** + * Accesses a default signal set used, for example, in ACE_Sig_Guard + * methods. + * Deprecated: use ACE_Object_Manager::default_mask () instead. + */ static ACE_Sig_Set &default_mask (void); - // Accesses a default signal set used, for example, in ACE_Sig_Guard - // methods. - // Deprecated: use ACE_Object_Manager::default_mask () instead. private: + /// For at_exit support. ACE_OS_Exit_Info exit_info_; - // For at_exit support. #if !defined (ACE_LACKS_ACE_SVCCONF) + /// Preallocated objects collection. ACE_Object_Manager_Preallocations *preallocations_; - // Preallocated objects collection. + /// ACE_Service_Config signal handler. ACE_Sig_Adapter *ace_service_config_sig_handler_; - // ACE_Service_Config signal handler. #endif /* ! ACE_LACKS_ACE_SVCCONF */ + /// Register an object or array for deletion at program termination. + /// See description of static version above for return values. int at_exit_i (void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param); - // Register an object or array for deletion at program termination. - // See description of static version above for return values. #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) public: // = The <get_singleton_lock> accessors are for internal // use by ACE_Singleton _only_. + /** + * Accesses an <ACE_Null_Mutex> to be used for construction of + * <ACE_Singletons>. Returns 0, and the lock in the argument, on + * success; returns -1 on failure. + */ static int get_singleton_lock (ACE_Null_Mutex *&); - // Accesses an <ACE_Null_Mutex> to be used for construction of - // <ACE_Singletons>. Returns 0, and the lock in the argument, on - // success; returns -1 on failure. + /** + * Accesses a non-recursive <ACE_Thread_Mutex> to be used for + * construction of <ACE_Singletons>. Returns 0, and the lock in the + * argument, on success; returns -1 on failure. + */ static int get_singleton_lock (ACE_Thread_Mutex *&); - // Accesses a non-recursive <ACE_Thread_Mutex> to be used for - // construction of <ACE_Singletons>. Returns 0, and the lock in the - // argument, on success; returns -1 on failure. + /** + * Accesses a non-recursive <ACE_Mutex> to be used for construction + * of <ACE_Singletons>. Returns 0, and the lock in the argument, on + * success; returns -1 on failure. + */ static int get_singleton_lock (ACE_Mutex *&); - // Accesses a non-recursive <ACE_Mutex> to be used for construction - // of <ACE_Singletons>. Returns 0, and the lock in the argument, on - // success; returns -1 on failure. + /** + * Accesses a recursive <ACE_Recursive_Thread_Mutex> to be used for + * construction of <ACE_Singletons>. Returns 0, and the lock in the + * argument, on success; returns -1 on failure. + */ static int get_singleton_lock (ACE_Recursive_Thread_Mutex *&); - // Accesses a recursive <ACE_Recursive_Thread_Mutex> to be used for - // construction of <ACE_Singletons>. Returns 0, and the lock in the - // argument, on success; returns -1 on failure. + /** + * Accesses a readers/writer <ACE_RW_Thread_Mutex> to be used for + * construction of <ACE_Singletons>. Returns 0, and the lock in the + * argument, on success; returns -1 on failure. + */ static int get_singleton_lock (ACE_RW_Thread_Mutex *&); - // Accesses a readers/writer <ACE_RW_Thread_Mutex> to be used for - // construction of <ACE_Singletons>. Returns 0, and the lock in the - // argument, on success; returns -1 on failure. #endif /* ACE_MT_SAFE */ public: // For internal use only by ACE_Managed_Objects. + /** + * Accessor to singleton instance. Because static member functions + * are provided in the interface, this should not be public. However, + * it is public so that ACE_Managed_Object<TYPE> can access it. + */ static ACE_Object_Manager *instance (void); - // Accessor to singleton instance. Because static member functions - // are provided in the interface, this should not be public. However, - // it is public so that ACE_Managed_Object<TYPE> can access it. + /// Table of preallocated objects. static void *preallocated_object[ACE_PREALLOCATED_OBJECTS]; - // Table of preallocated objects. + /// Table of preallocated arrays. static void *preallocated_array[ACE_PREALLOCATED_ARRAYS]; - // Table of preallocated arrays. public: // Application code should not use these explicitly, so they're @@ -370,19 +386,19 @@ public: ~ACE_Object_Manager (void); private: + /// Singleton pointer. static ACE_Object_Manager *instance_; - // Singleton pointer. #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) + /// Lock that is used to guard internal structures. ACE_Recursive_Thread_Mutex *internal_lock_; - // Lock that is used to guard internal structures. + /// Null lock for guarding singleton creation. ACE_Cleanup_Adapter<ACE_Null_Mutex> *singleton_null_lock_; - // Null lock for guarding singleton creation. + /// Lock for guarding singleton creation, when Object_Manager + /// hasn't been started up, or has already been shut down. ACE_Cleanup_Adapter<ACE_Recursive_Thread_Mutex> *singleton_recursive_lock_; - // Lock for guarding singleton creation, when Object_Manager - // hasn't been started up, or has already been shut down. #endif /* ACE_MT_SAFE */ #if defined (ACE_HAS_TSS_EMULATION) @@ -404,23 +420,25 @@ private: class ACE_Recursive_Thread_Mutex; +/** + * @class ACE_Static_Object_Lock + * + * @brief Provide an interface to access a global lock. + * + * This class is used to serialize the creation of static + * singleton objects. It really isn't needed any more, because + * anyone can access ACE_STATIC_OBJECT_LOCK directly. But, it + * is retained for backward compatibility. + */ class ACE_Export ACE_Static_Object_Lock { - // = TITLE - // Provide an interface to access a global lock. - // - // = DESCRIPTION - // This class is used to serialize the creation of static - // singleton objects. It really isn't needed any more, because - // anyone can access ACE_STATIC_OBJECT_LOCK directly. But, it - // is retained for backward compatibility. public: + /// Static lock access point. static ACE_Recursive_Thread_Mutex *instance (void); - // Static lock access point. + /// For use only by ACE_Object_Manager to clean up lock if it + /// what dynamically allocated. static void cleanup_lock (void); - // For use only by ACE_Object_Manager to clean up lock if it - // what dynamically allocated. }; #endif /* ACE_HAS_THREADS */ diff --git a/ace/Obstack.h b/ace/Obstack.h index 815307984d6..1500e1e9863 100644 --- a/ace/Obstack.h +++ b/ace/Obstack.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Obstack.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Obstack.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_OBSTACK_H #define ACE_OBSTACK_H @@ -24,84 +21,97 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Obchunk + * + * @brief Defines the state that represents a "chunk" of memory. + */ class ACE_Export ACE_Obchunk { - // = TITLE - // Defines the state that represents a "chunk" of memory. public: friend class ACE_Obstack; + /// Constructor. ACE_Obchunk (size_t size); - // Constructor. + /// dtor. ~ACE_Obchunk (void); - // dtor. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to the end of the chunk. ACE_TCHAR *end_; - // Pointer to the end of the chunk. + /// Pointer to the current location in the chunk. ACE_TCHAR *cur_; - // Pointer to the current location in the chunk. + /// Next chunk in the chain. ACE_Obchunk *next_; - // Next chunk in the chain. + /** + * Pointer to the beginning contents of this chunk. This field is + * actually overlayed by the memory allocated by + * <ACE_Obstack::new_chunk>. Therefore, it *must* come last. + */ ACE_TCHAR contents_[4]; - // Pointer to the beginning contents of this chunk. This field is - // actually overlayed by the memory allocated by - // <ACE_Obstack::new_chunk>. Therefore, it *must* come last. }; +/** + * @class ACE_Obstack + * + * @brief Define a simple "mark and release" memory allocation utility. + * + * The implementation is similar to the GNU obstack utility, + * which is used extensively in the GCC compiler. + */ class ACE_Export ACE_Obstack { - // = TITLE - // Define a simple "mark and release" memory allocation utility. - // - // = DESCRIPTION - // The implementation is similar to the GNU obstack utility, - // which is used extensively in the GCC compiler. public: // = Initialization and termination methods. ACE_Obstack (size_t size = 4096 - sizeof (ACE_Obchunk), ACE_Allocator *allocator_strategy = 0); ~ACE_Obstack (void); + /// Copy the data into the current Obchunk. ACE_TCHAR *copy (const ACE_TCHAR *data, size_t len); - // Copy the data into the current Obchunk. + /// "Release" the entire stack of Obchunks, putting it back on the + /// free list. void release (void); - // "Release" the entire stack of Obchunks, putting it back on the - // free list. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: class ACE_Obchunk *new_chunk (void); + /// Pointer to the allocator used by this Obstack. ACE_Allocator *allocator_strategy_; - // Pointer to the allocator used by this Obstack. + /// Current size of the Obstack; size_t size_; - // Current size of the Obstack; // = Don't change the order of the following two fields. +/** + * @class ACE_Obchunk + Head of the Obchunk chain. + */ class ACE_Obchunk *head_; - // Head of the Obchunk chain. +/** + * @class ACE_Obchunk + Pointer to the current Obchunk. + */ class ACE_Obchunk *curr_; - // Pointer to the current Obchunk. }; #if defined (__ACE_INLINE__) diff --git a/ace/PI_Malloc.h b/ace/PI_Malloc.h index ed3ed9ba702..60981cd84e3 100644 --- a/ace/PI_Malloc.h +++ b/ace/PI_Malloc.h @@ -1,13 +1,14 @@ -// $Id$ - -// ========================================================================== -// FILENAME -// PI_Malloc.h -// -// AUTHOR -// Priyanka Gontla <pgontla@ece.uci.edu> -// -// ========================================================================== + +//============================================================================= +/** + * @file PI_Malloc.h + * + * $Id$ + * + * @author Priyanka Gontla <pgontla@ece.uci.edu> + */ +//============================================================================= + #ifndef ACE_PI_MALLOC_H #define ACE_PI_MALLOC_H #include "ace/pre.h" @@ -33,21 +34,21 @@ #endif /* ACE_HAS_THREADS */ typedef ACE_Atomic_Op<ACE_PROCESS_MUTEX, int> ACE_INT; + +/// This keeps stats on the usage of the memory manager. struct ACE_Export ACE_Malloc_Stats -// TITLE -// This keeps stats on the usage of the memory manager. { ACE_Malloc_Stats (void); void dump (void) const; + /// Coarse-grained unit of allocation. ACE_INT nchunks_; - // Coarse-grained unit of allocation. + /// Fine-grained unit of allocation. ACE_INT nblocks_; - // Fine-grained unit of allocation. + /// Number of blocks in use ACE_INT ninuse_; - // Number of blocks in use }; #define ACE_MALLOC_STATS(X) X #else @@ -80,17 +81,19 @@ struct ACE_Export ACE_Malloc_Stats #if (ACE_HAS_POSITION_INDEPENDENT_POINTERS == 1) // prepare for position independent malloc +/** + * @class ACE_PI_Control_Block + * + * @brief This information is stored in memory allocated by the <Memory_Pool>. + * + * This class implements the control block structure that can be + * used in a "position indepent" fashion, i.e., you don't need to + * "map" the underlying memory pool to the same address in + * processes sharing the memory. The tradoff of this flexibility + * is more expensive malloc/free operations. + */ class ACE_Export ACE_PI_Control_Block { - // = TITLE - // This information is stored in memory allocated by the <Memory_Pool>. - // - // = DESCRIPTION - // This class implements the control block structure that can be - // used in a "position indepent" fashion, i.e., you don't need to - // "map" the underlying memory pool to the same address in - // processes sharing the memory. The tradoff of this flexibility - // is more expensive malloc/free operations. public: class ACE_Malloc_Header; class ACE_Name_Node; @@ -99,25 +102,28 @@ public: typedef ACE_Based_Pointer<ACE_Name_Node> NAME_NODE_PTR; typedef ACE_Based_Pointer_Basic<char> CHAR_PTR; + /** + * @class ACE_Malloc_Header + * + * @brief This is the control block header. It's used by <ACE_Malloc> + * to keep track of each chunk of data when it's in the free + * list or in use. + */ class ACE_Export ACE_Malloc_Header { - // = TITLE - // This is the control block header. It's used by <ACE_Malloc> - // to keep track of each chunk of data when it's in the free - // list or in use. public: ACE_Malloc_Header (void); + /// Points to next block if on free list. MALLOC_HEADER_PTR next_block_; - // Points to next block if on free list. + /// Initialize a malloc header pointer. static void init_ptr (MALLOC_HEADER_PTR *ptr, ACE_Malloc_Header *init, void *base_addr); - // Initialize a malloc header pointer. + /// Size of this header control block. size_t size_; - // Size of this header control block. #if defined (ACE_PI_MALLOC_PADDING_SIZE) && (ACE_PI_MALLOC_PADDING_SIZE == 0) // No padding required for PI_Malloc_Header. @@ -130,81 +136,83 @@ public: long padding_[ACE_PI_MALLOC_PADDING_SIZE < 1 ? 1 : ACE_PI_MALLOC_PADDING_SIZE]; #endif /* ACE_PI_MALLOC_PADDING_SIZE && ACE_PI_MALLOC_PADDING_SIZE == 0 */ + /// Dump the state of the object. void dump (void) const; - // Dump the state of the object. private: ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Malloc_Header &)) }; + /** + * @class ACE_Name_Node + * + * @brief This class supports "named memory regions" within <ACE_Malloc>. + * + * Internally, the named memory regions are stored as a + * doubly-linked list within the <Memory_Pool>. This makes + * it easy to iterate over the items in the list in both FIFO + * and LIFO order. + */ class ACE_Export ACE_Name_Node { - // = TITLE - // This class supports "named memory regions" within <ACE_Malloc>. - // - // = DESCRIPTION - // Internally, the named memory regions are stored as a - // doubly-linked list within the <Memory_Pool>. This makes - // it easy to iterate over the items in the list in both FIFO - // and LIFO order. public: // = Initialization methods. + /// Constructor. ACE_Name_Node (const char *name, char *name_ptr, char *pointer, ACE_Name_Node *head); - // Constructor. + /// Copy constructor. ACE_Name_Node (const ACE_Name_Node &); - // Copy constructor. + /// Constructor. ACE_Name_Node (void); - // Constructor. + /// Constructor. ~ACE_Name_Node (void); - // Constructor. + /// Initialize a name node pointer. static void init_ptr (NAME_NODE_PTR *ptr, ACE_Name_Node *init, void *base_addr); - // Initialize a name node pointer. + /// Return a pointer to the name of this node. const char *name (void) const; - // Return a pointer to the name of this node. + /// Assign a name; void name (const char *); - // Assign a name; + /// Name of the Node. CHAR_PTR name_; - // Name of the Node. + /// Pointer to the contents. CHAR_PTR pointer_; - // Pointer to the contents. + /// Pointer to the next node in the doubly-linked list. NAME_NODE_PTR next_; - // Pointer to the next node in the doubly-linked list. + /// Pointer to the previous node in the doubly-linked list. NAME_NODE_PTR prev_; - // Pointer to the previous node in the doubly-linked list. + /// Dump the state of the object. void dump (void) const; - // Dump the state of the object. private: ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Name_Node &)) }; + /// Print out a bunch of size info for debugging. static void print_alignment_info (void); - // Print out a bunch of size info for debugging. + /// Head of the linked list of Name Nodes. NAME_NODE_PTR name_head_; - // Head of the linked list of Name Nodes. + /// Current head of the freelist. MALLOC_HEADER_PTR freep_; - // Current head of the freelist. + /// Name of lock thats ensures mutual exclusion. char lock_name_[MAXNAMELEN]; - // Name of lock thats ensures mutual exclusion. #if defined (ACE_HAS_MALLOC_STATS) // Keep statistics about ACE_Malloc state and performance. @@ -230,15 +238,15 @@ public: ? ACE_MALLOC_ALIGN - (ACE_PI_CONTROL_BLOCK_SIZE % ACE_MALLOC_ALIGN) \ : ACE_MALLOC_ALIGN) / int (sizeof (long))) # endif /* !ACE_PI_CONTROL_BLOCK_ALIGN_LONGS */ + /// Force alignment. long align_[ACE_PI_CONTROL_BLOCK_ALIGN_LONGS < 1 ? 1 : ACE_PI_CONTROL_BLOCK_ALIGN_LONGS]; - // Force alignment. #endif /* ACE_PI_CONTROL_BLOCK_ALIGN_LONGS && ACE_PI_CONTROL_BLOCK_ALIGN_LONGS == 0 */ + /// Dummy node used to anchor the freelist. This needs to come last... ACE_Malloc_Header base_; - // Dummy node used to anchor the freelist. This needs to come last... + /// Dump the state of the object. void dump (void) const; - // Dump the state of the object. private: ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Control_Block &)) diff --git a/ace/POSIX_Asynch_IO.h b/ace/POSIX_Asynch_IO.h index ef5c48f0a76..ff54e7071d3 100644 --- a/ace/POSIX_Asynch_IO.h +++ b/ace/POSIX_Asynch_IO.h @@ -1,28 +1,22 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// -// ace -// -// = FILENAME -// -// POSIX_Asynch_IO.h -// -// = DESCRIPTION -// -// The implementation classes for POSIX implementation of Asynch -// Operations are defined here in this file. -// -// = AUTHOR -// -// Irfan Pyarali (irfan@cs.wustl.edu), -// Tim Harrison (harrison@cs.wustl.edu) and -// Alexander Babu Arulanthu <alex@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file POSIX_Asynch_IO.h + * + * $Id$ + * + * + * The implementation classes for POSIX implementation of Asynch + * Operations are defined here in this file. + * + * + * @author Irfan Pyarali (irfan@cs.wustl.edu) + * @author Tim Harrison (harrison@cs.wustl.edu) + * @author Alexander Babu Arulanthu <alex@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_POSIX_ASYNCH_IO_H #define ACE_POSIX_ASYNCH_IO_H @@ -43,59 +37,69 @@ class ACE_POSIX_SIG_Proactor; class ACE_POSIX_AIOCB_Proactor; class ACE_Proactor_Impl; +/** + * @class ACE_POSIX_Asynch_Result + * + * This class provides concrete implementation for <ACE_Asynch_Result> + * for POSIX4 platforms. This class extends <aiocb> and makes it more + * useful. + */ class ACE_Export ACE_POSIX_Asynch_Result : public virtual ACE_Asynch_Result_Impl, public aiocb { - // = TITLE - // This class provides concrete implementation for - // <ACE_Asynch_Result> for POSIX4 platforms. This class extends - // <aiocb> and makes it more useful. public: + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This is the ACT associated with the handle on which the + * Asynch_Operation takes place. + * + * @@ This is not implemented for POSIX4 platforms. + * + */ const void *completion_key (void) const; - // This is the ACT associated with the handle on which the - // Asynch_Operation takes place. - // - // @@ This is not implemented for POSIX4 platforms. - // + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// This returns ACE_INVALID_HANDLE on POSIX4 platforms. ACE_HANDLE event (void) const; - // This returns ACE_INVALID_HANDLE on POSIX4 platforms. + /** + * This really make sense only when doing file I/O. + * + * @@ On POSIX4-Unix, offset_high should be supported using + * aiocb64. + * + */ u_long offset (void) const; u_long offset_high (void) const; - // This really make sense only when doing file I/O. - // - // @@ On POSIX4-Unix, offset_high should be supported using - // aiocb64. - // + /// Priority of the operation. int priority (void) const; - // Priority of the operation. + /** + * POSIX4 realtime signal number to be used for the + * operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By + * default, SIGRTMIN is used to issue <aio_> calls. + */ int signal_number (void) const; - // POSIX4 realtime signal number to be used for the - // operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By - // default, SIGRTMIN is used to issue <aio_> calls. - + + /// Post <this> to the Proactor. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor. + /// Destructor. virtual ~ACE_POSIX_Asynch_Result (void); - // Destructor. protected: + /// Constructor. <Event> is not used on POSIX. ACE_POSIX_Asynch_Result (ACE_Handler &handler, const void* act, ACE_HANDLE event, @@ -103,95 +107,104 @@ protected: u_long offset_high, int priority, int signal_number); - // Constructor. <Event> is not used on POSIX. + /// Handler that will be called back. ACE_Handler &handler_; - // Handler that will be called back. + /** + * ACT for this operation. + * We could use <aiocb::aio_sigevent.sigev_value.sival_ptr> for + * this. But it doesnot provide the constness, so this may be + * better. + */ const void *act_; - // ACT for this operation. - // We could use <aiocb::aio_sigevent.sigev_value.sival_ptr> for - // this. But it doesnot provide the constness, so this may be - // better. + /// Bytes transferred by this operation. u_long bytes_transferred_; - // Bytes transferred by this operation. + /// Success indicator. int success_; - // Success indicator. + /// ACT associated with handle. const void *completion_key_; - // ACT associated with handle. + /// Error if operation failed. u_long error_; - // Error if operation failed. }; +/** + * @class ACE_POSIX_Asynch_Operation + * + * @brief This class abstracts out the common things needed for + * implementing <Asynch_Operation> for POSIX platforms. Specific + * implementations such as <POSIX_AIOCB_Asynch_Operation> and + * <POSIX_SIG_Asynch_Operation>, can derive from this class. + */ class ACE_Export ACE_POSIX_Asynch_Operation : public virtual ACE_Asynch_Operation_Impl { - // = TITLE - // This class abstracts out the common things needed for - // implementing <Asynch_Operation> for POSIX platforms. Specific - // implementations such as <POSIX_AIOCB_Asynch_Operation> and - // <POSIX_SIG_Asynch_Operation>, can derive from this class. public: + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. No need for the Proactor since the sub classes + * will know the correct implementation Proactor class, since this + * Operation class itself was created by the correct implementation + * Proactor class. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. No need for the Proactor since the sub classes - // will know the correct implementation Proactor class, since this - // Operation class itself was created by the correct implementation - // Proactor class. + /// Check the documentation for <ACE_Asynch_Operation::cancel>. int cancel (void); - // Check the documentation for <ACE_Asynch_Operation::cancel>. // = Access methods. + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. protected: + /// No op contructor. ACE_POSIX_Asynch_Operation (void); - // No op contructor. + /// Destructor. virtual ~ACE_POSIX_Asynch_Operation (void); - // Destructor. + /// Proactor that this Asynch IO will be registered with. ACE_Proactor *proactor_; - // Proactor that this Asynch IO will be registered with. + /// Handler that will receive the callback. ACE_Handler *handler_; - // Handler that will receive the callback. + /// I/O handle used for reading. ACE_HANDLE handle_; - // I/O handle used for reading. }; +/** + * @class ACE_POSIX_AIOCB_Asynch_Operation + * + * @brief This class implements <ACE_Asynch_Operation> for <AIOCB> + * (Asynchronous I/O Control Blocks) based implementation of + * Proactor. + */ class ACE_Export ACE_POSIX_AIOCB_Asynch_Operation : public virtual ACE_POSIX_Asynch_Operation { - // = TITLE - // This class implements <ACE_Asynch_Operation> for <AIOCB> - // (Asynchronous I/O Control Blocks) based implementation of - // Proactor. public: + /// Return the underlying Proactor implementation. ACE_POSIX_AIOCB_Proactor *posix_proactor (void) const; - // Return the underlying Proactor implementation. - + protected: + /// Contructor. ACE_POSIX_AIOCB_Asynch_Operation (ACE_POSIX_AIOCB_Proactor *posix_aiocb_proactor); - // Contructor. + /// Destructor. virtual ~ACE_POSIX_AIOCB_Asynch_Operation (void); - // Destructor. - virtual int register_and_start_aio (ACE_POSIX_Asynch_Result *result, + /// <op> means operation : 0 - read , 1 - write. + virtual int register_and_start_aio (ACE_POSIX_Asynch_Result *result, int op); - // <op> means operation : 0 - read , 1 - write. // This call is for the POSIX implementation. This method is used by // <ACE_Asynch_Operation> to store some information with the @@ -201,105 +214,121 @@ protected: // are slots available or no. Passing a valid ptr stores the ptr // with the Proactor. + /** + * It is easy to get this specific implementation proactor here, + * since it is the one that creates the correct POSIX_Asynch_* + * objects. We can use this to get to the implementation proactor + * directly. + */ ACE_POSIX_AIOCB_Proactor *posix_aiocb_proactor_; - // It is easy to get this specific implementation proactor here, - // since it is the one that creates the correct POSIX_Asynch_* - // objects. We can use this to get to the implementation proactor - // directly. }; +/** + * @class ACE_POSIX_SIG_Asynch_Operation + * + * @brief This class implements <ACE_Asynch_Operation> for Realtime + * Signal (<sigtimedwait>) based implementation of Proactor. + */ class ACE_Export ACE_POSIX_SIG_Asynch_Operation : public virtual ACE_POSIX_Asynch_Operation { - // = TITLE - // This class implements <ACE_Asynch_Operation> for Realtime - // Signal (<sigtimedwait>) based implementation of Proactor. public: + /// Return the underlying Proactor implemetation. ACE_POSIX_SIG_Proactor *posix_proactor (void) const; - // Return the underlying Proactor implemetation. protected: + /// Contructor. ACE_POSIX_SIG_Asynch_Operation (ACE_POSIX_SIG_Proactor *posix_sig_proactor); - // Contructor. + /// Destructor. virtual ~ACE_POSIX_SIG_Asynch_Operation (void); - // Destructor. + /** + * It is easy to get this specific implementation proactor here, + * since it is the one that creates the correct POSIX_Asynch_* + * objects. We can use this to get to the implementation proactor + * directly. + */ ACE_POSIX_SIG_Proactor *posix_sig_proactor_; - // It is easy to get this specific implementation proactor here, - // since it is the one that creates the correct POSIX_Asynch_* - // objects. We can use this to get to the implementation proactor - // directly. }; +/** + * @class ACE_POSIX_Asynch_Read_Stream_Result + * + * @brief This class provides concrete implementation for + * <ACE_Asynch_Read_Stream::Result> class for POSIX platforms. + */ class ACE_Export ACE_POSIX_Asynch_Read_Stream_Result : public virtual ACE_Asynch_Read_Stream_Result_Impl, public ACE_POSIX_Asynch_Result { - // = TITLE - // This class provides concrete implementation for - // <ACE_Asynch_Read_Stream::Result> class for POSIX platforms. + /// Factory classes willl have special permissions. friend class ACE_POSIX_AIOCB_Asynch_Read_Stream; friend class ACE_POSIX_SIG_Asynch_Read_Stream; - // Factory classes willl have special permissions. - + + /// The Proactor constructs the Result class for faking results. friend class ACE_POSIX_Proactor; - // The Proactor constructs the Result class for faking results. public: + /// The number of bytes which were requested at the start of the + /// asynchronous read. u_long bytes_to_read (void) const; - // The number of bytes which were requested at the start of the - // asynchronous read. + /// Message block which contains the read data. ACE_Message_Block &message_block (void) const; - // Message block which contains the read data. + /// I/O handle used for reading. ACE_HANDLE handle (void) const; - // I/O handle used for reading. - + // = Base class operations. These operations are here to kill // dominance warnings. These methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This is the ACT associated with the handle on which the + * Asynch_Operation takes place. + * + * @@ This is not implemented for POSIX4 platforms. + * + */ const void *completion_key (void) const; - // This is the ACT associated with the handle on which the - // Asynch_Operation takes place. - // - // @@ This is not implemented for POSIX4 platforms. - // + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// This returns ACE_INVALID_HANDLE. ACE_HANDLE event (void) const; - // This returns ACE_INVALID_HANDLE. + /** + * This really make sense only when doing file I/O. + * + * @@ On POSIX4-Unix, offset_high should be supported using + * aiocb64. + * + */ u_long offset (void) const; u_long offset_high (void) const; - // This really make sense only when doing file I/O. - // - // @@ On POSIX4-Unix, offset_high should be supported using - // aiocb64. - // + /// The priority of the asynchronous operation. int priority (void) const; - // The priority of the asynchronous operation. + /** + * POSIX4 realtime signal number to be used for the + * operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By + * default, SIGRTMIN is used to issue <aio_> calls. This is a no-op + * on non-POSIX4 systems and returns 0. + */ int signal_number (void) const; - // POSIX4 realtime signal number to be used for the - // operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By - // default, SIGRTMIN is used to issue <aio_> calls. This is a no-op - // on non-POSIX4 systems and returns 0. + /// Post <this> to the Proactor. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor. protected: ACE_POSIX_Asynch_Read_Stream_Result (ACE_Handler &handler, @@ -312,197 +341,216 @@ protected: int signal_number); // Constructor is protected since creation is limited to // ACE_Asynch_Read_Stream factory. - + + /// Get the data copied to this class, before calling application + /// handler. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // Get the data copied to this class, before calling application - // handler. + /// Destrcutor. virtual ~ACE_POSIX_Asynch_Read_Stream_Result (void); - // Destrcutor. // aiocb::aio_nbytes // Bytes requested when the asynchronous read was initiated. + /// Message block for reading the data into. ACE_Message_Block &message_block_; - // Message block for reading the data into. // aiocb::aio_filedes // I/O handle used for reading. }; +/** + * @class ACE_POSIX_AIOCB_Asynch_Read_Stream + * + * This class implements <ACE_Asynch_Read_Stream> for <AIOCB> + * (Asynchronous I/O Control Blocks) based implementation of Proactor. + * + */ class ACE_Export ACE_POSIX_AIOCB_Asynch_Read_Stream : public virtual ACE_Asynch_Read_Stream_Impl, public ACE_POSIX_AIOCB_Asynch_Operation { - // = TITLE - // This class implements <ACE_Asynch_Read_Stream> for <AIOCB> - // (Asynchronous I/O Control Blocks) based implementation of - // Proactor. public: + /// Constructor. ACE_POSIX_AIOCB_Asynch_Read_Stream (ACE_POSIX_AIOCB_Proactor *posix_aiocb_proactor); - // Constructor. + /// This starts off an asynchronous read. Upto <bytes_to_read> will + /// be read and stored in the <message_block>. int read (ACE_Message_Block &message_block, u_long bytes_to_read, const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous read. Upto <bytes_to_read> will - // be read and stored in the <message_block>. + /// Destructor. virtual ~ACE_POSIX_AIOCB_Asynch_Read_Stream (void); - // Destructor. - - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route - // the call to the ACE_POSIX_Asynch_Operation base class. + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route + // the call to the ACE_POSIX_Asynch_Operation base class. + + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. protected: + /// This is the method which does the real work and is there so that + /// the ACE_Asynch_Read_File class can use it too. int shared_read (ACE_POSIX_Asynch_Read_Stream_Result *result); - // This is the method which does the real work and is there so that - // the ACE_Asynch_Read_File class can use it too. }; +/** + * @class ACE_POSIX_SIG_Asynch_Read_Stream + * + * @brief This class implements <ACE_Asynch_Read_Stream> for Realtime + * Signal (<sigtimedwait>) based implementation of Proactor. + */ class ACE_Export ACE_POSIX_SIG_Asynch_Read_Stream : public virtual ACE_Asynch_Read_Stream_Impl, public ACE_POSIX_SIG_Asynch_Operation { - // = TITLE - // This class implements <ACE_Asynch_Read_Stream> for Realtime - // Signal (<sigtimedwait>) based implementation of Proactor. public: + /// Constructor. ACE_POSIX_SIG_Asynch_Read_Stream (ACE_POSIX_SIG_Proactor *posix_sig_proactor); - // Constructor. + /// This starts off an asynchronous read. Upto <bytes_to_read> will + /// be read and stored in the <message_block>. int read (ACE_Message_Block &message_block, u_long bytes_to_read, const void *act, int priority, int signal_number); - // This starts off an asynchronous read. Upto <bytes_to_read> will - // be read and stored in the <message_block>. + /// Destructor. virtual ~ACE_POSIX_SIG_Asynch_Read_Stream (void); - // Destructor. - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route - // the call to the ACE_POSIX_Asynch_Operation base class. + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route + // the call to the ACE_POSIX_Asynch_Operation base class. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. protected: + /// This is the method which does the real work and is there so that + /// the ACE_Asynch_Read_File class can use it too. int shared_read (ACE_POSIX_Asynch_Read_Stream_Result *result); - // This is the method which does the real work and is there so that - // the ACE_Asynch_Read_File class can use it too. }; + +/** + * @class ACE_POSIX_Asynch_Write_Stream_Result + * + * @brief This class provides concrete implementation for + * <ACE_Asynch_Write_Stream::Result> on POSIX platforms. + * + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous write. + */ class ACE_Export ACE_POSIX_Asynch_Write_Stream_Result : public virtual ACE_Asynch_Write_Stream_Result_Impl, public ACE_POSIX_Asynch_Result { - // = TITLE - // This class provides concrete implementation for - // <ACE_Asynch_Write_Stream::Result> on POSIX platforms. - // - // = DESCRIPTION - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous write. - + /// Factory classes will have special privilages. friend class ACE_POSIX_AIOCB_Asynch_Write_Stream; friend class ACE_POSIX_SIG_Asynch_Write_Stream; - // Factory classes will have special privilages. + /// The Proactor constructs the Result class for faking results. friend class ACE_POSIX_Proactor; - // The Proactor constructs the Result class for faking results. public: + /// The number of bytes which were requested at the start of the + /// asynchronous write. u_long bytes_to_write (void) const; - // The number of bytes which were requested at the start of the - // asynchronous write. + /// Message block that contains the data to be written. ACE_Message_Block &message_block (void) const; - // Message block that contains the data to be written. + /// I/O handle used for writing. ACE_HANDLE handle (void) const; - // I/O handle used for writing. - + // = Base class operations. These operations are here to kill - // dominance warnings. These methods call the base class methods. + // dominance warnings. These methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This is the ACT associated with the handle on which the + * Asynch_Operation takes place. + * + * @@ This is not implemented for POSIX4 platforms. + * + */ const void *completion_key (void) const; - // This is the ACT associated with the handle on which the - // Asynch_Operation takes place. - // - // @@ This is not implemented for POSIX4 platforms. - // + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// This returns ACE_INVALID_HANDLE on POSIX4 platforms. ACE_HANDLE event (void) const; - // This returns ACE_INVALID_HANDLE on POSIX4 platforms. + /** + * This really make sense only when doing file I/O. + * + * @@ On POSIX4-Unix, offset_high should be supported using + * aiocb64. + * + */ u_long offset (void) const; u_long offset_high (void) const; - // This really make sense only when doing file I/O. - // - // @@ On POSIX4-Unix, offset_high should be supported using - // aiocb64. - // + /// The priority of the asynchronous operation. int priority (void) const; - // The priority of the asynchronous operation. + /** + * POSIX4 realtime signal number to be used for the + * operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By + * default, SIGRTMIN is used to issue <aio_> calls. This is a no-op + * on non-POSIX4 systems and returns 0. + */ int signal_number (void) const; - // POSIX4 realtime signal number to be used for the - // operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By - // default, SIGRTMIN is used to issue <aio_> calls. This is a no-op - // on non-POSIX4 systems and returns 0. + /// Post <this> to the Proactor. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor. protected: ACE_POSIX_Asynch_Write_Stream_Result (ACE_Handler &handler, @@ -516,197 +564,216 @@ protected: // Constructor is protected since creation is limited to // ACE_Asynch_Write_Stream factory. + /// ACE_Proactor will call this method when the write completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // ACE_Proactor will call this method when the write completes. + /// Destructor. virtual ~ACE_POSIX_Asynch_Write_Stream_Result (void); - // Destructor. protected: // aiocb::aio_nbytes // The number of bytes which were requested at the start of the // asynchronous write. + /// Message block that contains the data to be written. ACE_Message_Block &message_block_; - // Message block that contains the data to be written. // aiocb::aio_filedes // I/O handle used for writing. }; +/** + * @class ACE_POSIX_AIOCB_Asynch_Write_Stream + * + * @brief This class implements <ACE_Asynch_Write_Stream> for <AIOCB> + * (Asynchronous I/O Control Blocks) based implementation of + * Proactor. + */ class ACE_Export ACE_POSIX_AIOCB_Asynch_Write_Stream : public virtual ACE_Asynch_Write_Stream_Impl, public ACE_POSIX_AIOCB_Asynch_Operation { - // = TITLE - // This class implements <ACE_Asynch_Write_Stream> for <AIOCB> - // (Asynchronous I/O Control Blocks) based implementation of - // Proactor. public: + /// Constructor. ACE_POSIX_AIOCB_Asynch_Write_Stream (ACE_POSIX_AIOCB_Proactor *posix_aiocb_proactor); - // Constructor. + /// This starts off an asynchronous write. Upto <bytes_to_write> + /// will be written from the <message_block>. int write (ACE_Message_Block &message_block, u_long bytes_to_write, const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous write. Upto <bytes_to_write> - // will be written from the <message_block>. + /// Destrcutor. virtual ~ACE_POSIX_AIOCB_Asynch_Write_Stream (void); - // Destrcutor. - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route - // the call to the ACE_POSIX_Asynch_Operation base class. + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route + // the call to the ACE_POSIX_Asynch_Operation base class. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. protected: + /// This is the method which does the real work and is there so that + /// the ACE_Asynch_Write_File class can use it too. int shared_write (ACE_POSIX_Asynch_Write_Stream_Result *result); - // This is the method which does the real work and is there so that - // the ACE_Asynch_Write_File class can use it too. }; +/** + * @class ACE_POSIX_SIG_Asynch_Write_Stream + * + * @brief This class implements <ACE_Asynch_Write_Stream> for Realtime + * Signal (<sigtimedwait>) based implementation of Proactor. + */ class ACE_Export ACE_POSIX_SIG_Asynch_Write_Stream : public virtual ACE_Asynch_Write_Stream_Impl, public ACE_POSIX_SIG_Asynch_Operation { - // = TITLE - // This class implements <ACE_Asynch_Write_Stream> for Realtime - // Signal (<sigtimedwait>) based implementation of Proactor. public: + /// Constrctor. ACE_POSIX_SIG_Asynch_Write_Stream (ACE_POSIX_SIG_Proactor *posix_sig_proactor); - // Constrctor. + /// This starts off an asynchronous write. Upto <bytes_to_write> + /// will be written from the <message_block>. int write (ACE_Message_Block &message_block, u_long bytes_to_write, const void *act, int priority, int signal_number); - // This starts off an asynchronous write. Upto <bytes_to_write> - // will be written from the <message_block>. + /// Destructor. virtual ~ACE_POSIX_SIG_Asynch_Write_Stream (void); - // Destructor. - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route - // the call to the ACE_POSIX_Asynch_Operation base class. + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route + // the call to the ACE_POSIX_Asynch_Operation base class. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. protected: + /// This is the method which does the real work and is there so that + /// the ACE_Asynch_Write_File class can use it too. int shared_write (ACE_POSIX_Asynch_Write_Stream_Result *result); - // This is the method which does the real work and is there so that - // the ACE_Asynch_Write_File class can use it too. }; +/** + * @class ACE_POSIX_Asynch_Read_File_Result + * + * @brief This class provides concrete implementation for + * <ACE_Asynch_Read_File::Result> class for POSIX platforms. + */ class ACE_Export ACE_POSIX_Asynch_Read_File_Result : public virtual ACE_Asynch_Read_File_Result_Impl, public ACE_POSIX_Asynch_Read_Stream_Result { - // = TITLE - // This class provides concrete implementation for - // <ACE_Asynch_Read_File::Result> class for POSIX platforms. + /// Factory classes willl have special permissions. friend class ACE_POSIX_AIOCB_Asynch_Read_File; friend class ACE_POSIX_SIG_Asynch_Read_File; - // Factory classes willl have special permissions. + /// The Proactor constructs the Result class for faking results. friend class ACE_POSIX_Proactor; - // The Proactor constructs the Result class for faking results. public: // = These methods belong to ACE_POSIX_Asynch_Result class base // class. These operations are here to kill dominance // warnings. These methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This is the ACT associated with the handle on which the + * Asynch_Operation takes place. + * + * @@ This is not implemented for POSIX4 platforms. + * + */ const void *completion_key (void) const; - // This is the ACT associated with the handle on which the - // Asynch_Operation takes place. - // - // @@ This is not implemented for POSIX4 platforms. - // + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// This returns ACE_INVALID_HANDLE on POSIX4 platforms. ACE_HANDLE event (void) const; - // This returns ACE_INVALID_HANDLE on POSIX4 platforms. + /** + * This really make sense only when doing file I/O. + * + * @@ On POSIX4-Unix, offset_high should be supported using + * aiocb64. + * + */ u_long offset (void) const; u_long offset_high (void) const; - // This really make sense only when doing file I/O. - // - // @@ On POSIX4-Unix, offset_high should be supported using - // aiocb64. - // + /// The priority of the asynchronous operation. int priority (void) const; - // The priority of the asynchronous operation. + /** + * POSIX4 realtime signal number to be used for the + * operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By + * default, SIGRTMIN is used to issue <aio_> calls. This is a no-op + * on non-POSIX4 systems and returns 0. + */ int signal_number (void) const; - // POSIX4 realtime signal number to be used for the - // operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By - // default, SIGRTMIN is used to issue <aio_> calls. This is a no-op - // on non-POSIX4 systems and returns 0. - + // = The following methods belong to - // ACE_POSIX_Asynch_Read_Stream_Result. They are here to avoid + // ACE_POSIX_Asynch_Read_Stream_Result. They are here to avoid // dominance warnings. These methods route their call to the // ACE_POSIX_Asynch_Read_Stream_Result base class. + /// The number of bytes which were requested at the start of the + /// asynchronous read. u_long bytes_to_read (void) const; - // The number of bytes which were requested at the start of the - // asynchronous read. + /// Message block which contains the read data. ACE_Message_Block &message_block (void) const; - // Message block which contains the read data. + /// I/O handle used for reading. ACE_HANDLE handle (void) const; - // I/O handle used for reading. + /// Post <this> to the Proactor. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor. protected: ACE_POSIX_Asynch_Read_File_Result (ACE_Handler &handler, @@ -722,40 +789,46 @@ protected: // Constructor is protected since creation is limited to // ACE_Asynch_Read_File factory. + /// ACE_Proactor will call this method when the read completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // ACE_Proactor will call this method when the read completes. + /// Destructor. virtual ~ACE_POSIX_Asynch_Read_File_Result (void); - // Destructor. }; +/** + * @class ACE_POSIX_AIOCB_Asynch_Read_File + * + * @brief This class is a factory for starting off asynchronous reads + * on a file. This class implements <ACE_Asynch_Read_File> for + * <AIOCB> (Asynchronous I/O Control Blocks) based implementation + * of Proactor. + * + * Once <open> is called, multiple asynchronous <read>s can + * started using this class. A <ACE_Asynch_Read_File::Result> + * will be passed back to the <handler> when the asynchronous + * reads completes through the <ACE_Handler::handle_read_file> + * callback. + * + * This class differs slightly from <ACE_Asynch_Read_Stream> as it + * allows the user to specify an offset for the read. + */ class ACE_Export ACE_POSIX_AIOCB_Asynch_Read_File : public virtual ACE_Asynch_Read_File_Impl, public ACE_POSIX_AIOCB_Asynch_Read_Stream { - // = TITLE - // This class is a factory for starting off asynchronous reads - // on a file. This class implements <ACE_Asynch_Read_File> for - // <AIOCB> (Asynchronous I/O Control Blocks) based implementation - // of Proactor. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <read>s can - // started using this class. A <ACE_Asynch_Read_File::Result> - // will be passed back to the <handler> when the asynchronous - // reads completes through the <ACE_Handler::handle_read_file> - // callback. - // - // This class differs slightly from <ACE_Asynch_Read_Stream> as it - // allows the user to specify an offset for the read. public: + /// Constructor. ACE_POSIX_AIOCB_Asynch_Read_File (ACE_POSIX_AIOCB_Proactor *posix_aiocb_proactor); - // Constructor. + /** + * This starts off an asynchronous read. Upto <bytes_to_read> will + * be read and stored in the <message_block>. The read will start + * at <offset> from the beginning of the file. + */ int read (ACE_Message_Block &message_block, u_long bytes_to_read, u_long offset, @@ -763,65 +836,72 @@ public: const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous read. Upto <bytes_to_read> will - // be read and stored in the <message_block>. The read will start - // at <offset> from the beginning of the file. + /// Destructor. virtual ~ACE_POSIX_AIOCB_Asynch_Read_File (void); - // Destructor. - - - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route - // the call to the ACE_POSIX_Asynch_Operation base class. + + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route + // the call to the ACE_POSIX_Asynch_Operation base class. + + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. private: + /** + * This belongs to ACE_POSIX_AIOCB_Asynch_Read_Stream. We have + * defined this here to avoid compiler warnings and forward the + * method to <ACE_POSIX_AIOCB_Asynch_Read_Stream::read>. + */ int read (ACE_Message_Block &message_block, u_long bytes_to_read, const void *act, int priority, int signal_number = 0); - // This belongs to ACE_POSIX_AIOCB_Asynch_Read_Stream. We have - // defined this here to avoid compiler warnings and forward the - // method to <ACE_POSIX_AIOCB_Asynch_Read_Stream::read>. }; +/** + * @class ACE_POSIX_SIG_Asynch_Read_File + * + * @brief This class is a factory for starting off asynchronous reads + * on a file. This class implements <ACE_Asynch_Operation> for + * Realtime Signal (<sigtimedwait>) based implementation of + * Proactor. + * + * Once <open> is called, multiple asynchronous <read>s can + * started using this class. A <ACE_Asynch_Read_File::Result> + * will be passed back to the <handler> when the asynchronous + * reads completes through the <ACE_Handler::handle_read_file> + * callback. + */ class ACE_Export ACE_POSIX_SIG_Asynch_Read_File : public virtual ACE_Asynch_Read_File_Impl, public ACE_POSIX_SIG_Asynch_Read_Stream { - // = TITLE - // This class is a factory for starting off asynchronous reads - // on a file. This class implements <ACE_Asynch_Operation> for - // Realtime Signal (<sigtimedwait>) based implementation of - // Proactor. - // - // = DESCRIPTION - // Once <open> is called, multiple asynchronous <read>s can - // started using this class. A <ACE_Asynch_Read_File::Result> - // will be passed back to the <handler> when the asynchronous - // reads completes through the <ACE_Handler::handle_read_file> - // callback. - public: + /// Constructor. ACE_POSIX_SIG_Asynch_Read_File (ACE_POSIX_SIG_Proactor *posix_sig_proactor); - // Constructor. + /** + * This starts off an asynchronous read. Upto <bytes_to_read> will + * be read and stored in the <message_block>. The read will start + * at <offset> from the beginning of the file. + */ int read (ACE_Message_Block &message_block, u_long bytes_to_read, u_long offset, @@ -829,132 +909,139 @@ public: const void *act, int priority, int signal_number); - // This starts off an asynchronous read. Upto <bytes_to_read> will - // be read and stored in the <message_block>. The read will start - // at <offset> from the beginning of the file. + /// Destructor. virtual ~ACE_POSIX_SIG_Asynch_Read_File (void); - // Destructor. - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route - // the call to the ACE_POSIX_Asynch_Operation base class. + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route + // the call to the ACE_POSIX_Asynch_Operation base class. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. private: + /** + * This belongs to ACE_POSIX_SIG_Asynch_Read_Stream. We have + * defined this here to avoid compiler warnings and forward the + * method to <ACE_POSIX_SIG_Asynch_Read_Stream::read>. + */ int read (ACE_Message_Block &message_block, u_long bytes_to_read, const void *act, int priority, int signal_number); - // This belongs to ACE_POSIX_SIG_Asynch_Read_Stream. We have - // defined this here to avoid compiler warnings and forward the - // method to <ACE_POSIX_SIG_Asynch_Read_Stream::read>. }; +/** + * @class ACE_POSIX_Asynch_Write_File_Result + * + * @brief This class provides implementation for + * <ACE_Asynch_Write_File_Result> for POSIX platforms. + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous write. + * + * This class differs slightly from + * <ACE_Asynch_Write_Stream::Result> as it calls back + * <ACE_Handler::handle_write_file> on the <handler> instead of + * <ACE_Handler::handle_write_stream>. No additional state is + * required by this class as <ACE_Asynch_Result> can store the + * <offset>. + */ class ACE_Export ACE_POSIX_Asynch_Write_File_Result : public virtual ACE_Asynch_Write_File_Result_Impl, public ACE_POSIX_Asynch_Write_Stream_Result { - // = TITLE - // This class provides implementation for - // <ACE_Asynch_Write_File_Result> for POSIX platforms. - // - // = DESCRIPTION - // - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous write. - // - // This class differs slightly from - // <ACE_Asynch_Write_Stream::Result> as it calls back - // <ACE_Handler::handle_write_file> on the <handler> instead of - // <ACE_Handler::handle_write_stream>. No additional state is - // required by this class as <ACE_Asynch_Result> can store the - // <offset>. - + /// Factory classes will have special permissions. friend class ACE_POSIX_AIOCB_Asynch_Write_File; friend class ACE_POSIX_SIG_Asynch_Write_File; - // Factory classes will have special permissions. + /// The Proactor constructs the Result class for faking results. friend class ACE_POSIX_Proactor; - // The Proactor constructs the Result class for faking results. public: // = Base class operations. These operations are here to kill some // warnings. These methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This is the ACT associated with the handle on which the + * Asynch_Operation takes place. + * + * @@ This is not implemented for POSIX4 platforms. + * + */ const void *completion_key (void) const; - // This is the ACT associated with the handle on which the - // Asynch_Operation takes place. - // - // @@ This is not implemented for POSIX4 platforms. - // + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// This returns ACE_INVALID_HANDLE on POSIX4 platforms. ACE_HANDLE event (void) const; - // This returns ACE_INVALID_HANDLE on POSIX4 platforms. - + + /** + * This really make sense only when doing file I/O. + * + * @@ On POSIX4-Unix, offset_high should be supported using + * aiocb64. + * + */ u_long offset (void) const; u_long offset_high (void) const; - // This really make sense only when doing file I/O. - // - // @@ On POSIX4-Unix, offset_high should be supported using - // aiocb64. - // - + + /// The priority of the asynchronous operation. int priority (void) const; - // The priority of the asynchronous operation. + /** + * POSIX4 realtime signal number to be used for the + * operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By + * default, SIGRTMIN is used to issue <aio_> calls. This is a no-op + * on non-POSIX4 systems and returns 0. + */ int signal_number (void) const; - // POSIX4 realtime signal number to be used for the - // operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By - // default, SIGRTMIN is used to issue <aio_> calls. This is a no-op - // on non-POSIX4 systems and returns 0. - + // = The following methods belong to // ACE_POSIX_Asynch_Write_Stream_Result. They are here to avoid - // dominace warnings. These methods route their call to the - // ACE_POSIX_Asynch_Write_Stream_Result base class. + // dominace warnings. These methods route their call to the + // ACE_POSIX_Asynch_Write_Stream_Result base class. + /// The number of bytes which were requested at the start of the + /// asynchronous write. u_long bytes_to_write (void) const; - // The number of bytes which were requested at the start of the - // asynchronous write. + /// Message block that contains the data to be written. ACE_Message_Block &message_block (void) const; - // Message block that contains the data to be written. + /// I/O handle used for writing. ACE_HANDLE handle (void) const; - // I/O handle used for writing. + /// Post <this> to the Proactor. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor. - + protected: ACE_POSIX_Asynch_Write_File_Result (ACE_Handler &handler, ACE_HANDLE handle, @@ -969,31 +1056,37 @@ protected: // Constructor is protected since creation is limited to // ACE_Asynch_Write_File factory. + /// ACE_Proactor will call this method when the write completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // ACE_Proactor will call this method when the write completes. + /// Destructor. virtual ~ACE_POSIX_Asynch_Write_File_Result (void); - // Destructor. }; +/** + * @class ACE_POSIX_AIOCB_Asynch_Write_File + * + * This class provides concrete implementation for + * <ACE_Asynch_Write_File> for POSIX platforms where the + * completion strategy for Proactor is based on AIOCB (AIO + * Control Blocks). + * + */ class ACE_Export ACE_POSIX_AIOCB_Asynch_Write_File : public virtual ACE_Asynch_Write_File_Impl, public ACE_POSIX_AIOCB_Asynch_Write_Stream { - // = TITLE - // This class provides concrete implementation for - // <ACE_Asynch_Write_File> for POSIX platforms where the - // completion strategy for Proactor is based on AIOCB (AIO - // Control Blocks). - // - // = DESCRIPTION - // public: + /// Constructor. ACE_POSIX_AIOCB_Asynch_Write_File (ACE_POSIX_AIOCB_Proactor *posix_aiocb_proactor); - // Constructor. + /** + * This starts off an asynchronous write. Upto <bytes_to_write> + * will be write and stored in the <message_block>. The write will + * start at <offset> from the beginning of the file. + */ int write (ACE_Message_Block &message_block, u_long bytes_to_write, u_long offset, @@ -1001,65 +1094,72 @@ public: const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous write. Upto <bytes_to_write> - // will be write and stored in the <message_block>. The write will - // start at <offset> from the beginning of the file. + /// Destructor. virtual ~ACE_POSIX_AIOCB_Asynch_Write_File (void); - // Destructor. - - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route - // the call to the ACE_POSIX_Asynch_Operation base class. + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route + // the call to the ACE_POSIX_Asynch_Operation base class. + + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. private: + /** + * This <write> belongs to ACE_POSIX_AIOCB_Asynch_Write_Stream. We + * have put this here to avoid compiler warnings. We forward this + * method call to the <ACE_POSIX_SIG_Asynch_Write_Stream::write> + * one. + */ int write (ACE_Message_Block &message_block, u_long bytes_to_write, const void *act, int priority, int signal_number = 0); - // This <write> belongs to ACE_POSIX_AIOCB_Asynch_Write_Stream. We - // have put this here to avoid compiler warnings. We forward this - // method call to the <ACE_POSIX_SIG_Asynch_Write_Stream::write> - // one. }; +/** + * @class ACE_POSIX_SIG_Asynch_Write_File + * + * @brief This class is a factory for starting off asynchronous reads + * on a file. This class implements <ACE_Asynch_Operation> for + * Realtime Signal (<sigtimedwait>) based implementation of + * Proactor. + * + * Once <open> is called, multiple asynchronous <read>s can + * started using this class. A <ACE_Asynch_Read_File::Result> + * will be passed back to the <handler> when the asynchronous + * reads completes through the <ACE_Handler::handle_read_file> + * callback. + */ class ACE_Export ACE_POSIX_SIG_Asynch_Write_File : public virtual ACE_Asynch_Write_File_Impl, public ACE_POSIX_SIG_Asynch_Write_Stream { - // = TITLE - // This class is a factory for starting off asynchronous reads - // on a file. This class implements <ACE_Asynch_Operation> for - // Realtime Signal (<sigtimedwait>) based implementation of - // Proactor. - // - // = DESCRIPTION - // Once <open> is called, multiple asynchronous <read>s can - // started using this class. A <ACE_Asynch_Read_File::Result> - // will be passed back to the <handler> when the asynchronous - // reads completes through the <ACE_Handler::handle_read_file> - // callback. - public: + /// Constructor. ACE_POSIX_SIG_Asynch_Write_File (ACE_POSIX_SIG_Proactor *posix_sig_proactor); - // Constructor. + /** + * This starts off an asynchronous write. Upto <bytes_to_write> + * will be write and stored in the <message_block>. The write will + * start at <offset> from the beginning of the file. + */ int write (ACE_Message_Block &message_block, u_long bytes_to_write, u_long offset, @@ -1067,123 +1167,131 @@ public: const void *act, int priority, int signal_number); - // This starts off an asynchronous write. Upto <bytes_to_write> - // will be write and stored in the <message_block>. The write will - // start at <offset> from the beginning of the file. + /// Destrcutor. virtual ~ACE_POSIX_SIG_Asynch_Write_File (void); - // Destrcutor. - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route - // the call to the ACE_POSIX_Asynch_Operation base class. + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route + // the call to the ACE_POSIX_Asynch_Operation base class. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. private: + /** + * This <write> belongs to ACE_POSIX_SIG_Asynch_Write_Stream. We + * have put this here to avoid compiler warnings. We forward this + * method call to the <ACE_POSIX_SIG_Asynch_Write_Stream::write> + * one. + */ int write (ACE_Message_Block &message_block, u_long bytes_to_write, const void *act, int priority, int signal_number); - // This <write> belongs to ACE_POSIX_SIG_Asynch_Write_Stream. We - // have put this here to avoid compiler warnings. We forward this - // method call to the <ACE_POSIX_SIG_Asynch_Write_Stream::write> - // one. }; +/** + * @class ACE_POSIX_Asynch_Accept_Result + * + * @brief This is that class which will be passed back to the + * <handler> when the asynchronous accept completes. + * + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous accept. + */ class ACE_Export ACE_POSIX_Asynch_Accept_Result : public virtual ACE_Asynch_Accept_Result_Impl, public ACE_POSIX_Asynch_Result { - // = TITLE - // This is that class which will be passed back to the - // <handler> when the asynchronous accept completes. - // - // = DESCRIPTION - // - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous accept. - + /// Factory classes willl have special permissions. friend class ACE_POSIX_AIOCB_Asynch_Accept; friend class ACE_POSIX_SIG_Asynch_Accept; - // Factory classes willl have special permissions. + /// The Proactor constructs the Result class for faking results. friend class ACE_POSIX_Proactor; - // The Proactor constructs the Result class for faking results. public: + /// The number of bytes which were requested at the start of the + /// asynchronous accept. u_long bytes_to_read (void) const; - // The number of bytes which were requested at the start of the - // asynchronous accept. + /// Message block which contains the read data. ACE_Message_Block &message_block (void) const; - // Message block which contains the read data. + /// I/O handle used for accepting new connections. ACE_HANDLE listen_handle (void) const; - // I/O handle used for accepting new connections. + /// I/O handle for the new connection. ACE_HANDLE accept_handle (void) const; - // I/O handle for the new connection. // = Base class operations. These operations are here to kill // dominance warnings. These methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This is the ACT associated with the handle on which the + * Asynch_Operation takes place. + * + * @@ This is not implemented for POSIX4 platforms. + * + */ const void *completion_key (void) const; - // This is the ACT associated with the handle on which the - // Asynch_Operation takes place. - // - // @@ This is not implemented for POSIX4 platforms. - // + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// This returns ACE_INVALID_HANDLE on POSIX4 platforms. ACE_HANDLE event (void) const; - // This returns ACE_INVALID_HANDLE on POSIX4 platforms. + /** + * This really make sense only when doing file I/O. + * + * @@ On POSIX4-Unix, offset_high should be supported using + * aiocb64. + * + */ u_long offset (void) const; u_long offset_high (void) const; - // This really make sense only when doing file I/O. - // - // @@ On POSIX4-Unix, offset_high should be supported using - // aiocb64. - // + /// The priority of the asynchronous operation. int priority (void) const; - // The priority of the asynchronous operation. + /** + * POSIX4 realtime signal number to be used for the + * operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By + * default, SIGRTMIN is used to issue <aio_> calls. This is a no-op + * on non-POSIX4 systems and returns 0. + */ int signal_number (void) const; - // POSIX4 realtime signal number to be used for the - // operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By - // default, SIGRTMIN is used to issue <aio_> calls. This is a no-op - // on non-POSIX4 systems and returns 0. - + + /// Post <this> to the Proactor. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor. protected: ACE_POSIX_Asynch_Accept_Result (ACE_Handler &handler, @@ -1198,241 +1306,271 @@ protected: // Constructor is protected since creation is limited to // ACE_Asynch_Accept factory. + /// ACE_Proactor will call this method when the accept completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // ACE_Proactor will call this method when the accept completes. + /// Destructor. virtual ~ACE_POSIX_Asynch_Accept_Result (void); - // Destructor. // aiocb::aio_nbytes // Bytes requested when the asynchronous read was initiated. // Actually, on POSIX implementation, we dont read any intial data. + /// Message block for reading the data into. ACE_Message_Block &message_block_; - // Message block for reading the data into. + /// I/O handle used for accepting new connections. ACE_HANDLE listen_handle_; - // I/O handle used for accepting new connections. // aiocb::aio_filedes // I/O handle for the new connection. }; +/** + * @class ACE_POSIX_AIOCB_Asynch_Accept_Handler + * + * Forward declaration. This class is defined the in the cpp file, + * since this is internal to the implementation. + */ class ACE_POSIX_AIOCB_Asynch_Accept_Handler; -// Forward declaration. This class is defined the in the cpp file, -// since this is internal to the implementation. +/** + * @class ACE_POSIX_AIOCB_Asynch_Accept + * + */ class ACE_Export ACE_POSIX_AIOCB_Asynch_Accept : public virtual ACE_Asynch_Accept_Impl, public ACE_POSIX_AIOCB_Asynch_Operation { public: + /// Constructor. ACE_POSIX_AIOCB_Asynch_Accept (ACE_POSIX_AIOCB_Proactor *posix_aiocb_proactor); - // Constructor. + /** + * This <open> belongs to ACE_AIOCB_Asynch_Operation. We forward + * this call to that method. We have put this here to avoid the + * compiler warnings. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // This <open> belongs to ACE_AIOCB_Asynch_Operation. We forward - // this call to that method. We have put this here to avoid the - // compiler warnings. + /** + * This starts off an asynchronous accept. The asynchronous accept + * call also allows any initial data to be returned to the + * <handler>. Upto <bytes_to_read> will be read and stored in the + * <message_block>. The <accept_handle> will be used for the + * <accept> call. If (<accept_handle> == INVALID_HANDLE), a new + * handle will be created. + * + * <message_block> must be specified. This is because the address of + * the new connection is placed at the end of this buffer. + */ int accept (ACE_Message_Block &message_block, u_long bytes_to_read, ACE_HANDLE accept_handle, const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous accept. The asynchronous accept - // call also allows any initial data to be returned to the - // <handler>. Upto <bytes_to_read> will be read and stored in the - // <message_block>. The <accept_handle> will be used for the - // <accept> call. If (<accept_handle> == INVALID_HANDLE), a new - // handle will be created. - // - // <message_block> must be specified. This is because the address of - // the new connection is placed at the end of this buffer. + /// Destructor. virtual ~ACE_POSIX_AIOCB_Asynch_Accept (void); - // Destructor. - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route - // the call to the ACE_POSIX_Asynch_Operation base class. + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route + // the call to the ACE_POSIX_Asynch_Operation base class. + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. - + private: + /// The thread function that does handle events. static void* thread_function (void* reactor); - // The thread function that does handle events. + /// Reactor to wait on the <listen_handle>. ACE_Reactor reactor_; - // Reactor to wait on the <listen_handle>. + /// The Event Handler to do handle_input. ACE_POSIX_AIOCB_Asynch_Accept_Handler* accept_handler_; - // The Event Handler to do handle_input. }; +/** + * @class ACE_POSIX_SIG_Asynch_Accept_Handler; + * + * Forward declaration. This class is defined the in the cpp file, + * since this is internal to the implementation. + */ class ACE_POSIX_SIG_Asynch_Accept_Handler; -// Forward declaration. This class is defined the in the cpp file, -// since this is internal to the implementation. +/** + * @class ACE_POSIX_SIG_Asynch_Accept + * + * @brief This class implements <ACE_Asynch_Accept> for Realtime + * Signal (<sigtimedwait>) based implementation of Proactor. + */ class ACE_Export ACE_POSIX_SIG_Asynch_Accept : public virtual ACE_Asynch_Accept_Impl, public ACE_POSIX_SIG_Asynch_Operation { - // = TITLE - // This class implements <ACE_Asynch_Accept> for Realtime - // Signal (<sigtimedwait>) based implementation of Proactor. public: + /// Constructor. ACE_POSIX_SIG_Asynch_Accept (ACE_POSIX_SIG_Proactor *posix_sig_proactor); - // Constructor. + /** + * This <open> belongs to ACE_SIG_Asynch_Operation. We forward this + * call to that method. We have put this here to avoid the compiler + * warnings. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // This <open> belongs to ACE_SIG_Asynch_Operation. We forward this - // call to that method. We have put this here to avoid the compiler - // warnings. + /** + * This starts off an asynchronous accept. The asynchronous accept + * call also allows any initial data to be returned to the + * <handler>. Upto <bytes_to_read> will be read and stored in the + * <message_block>. The <accept_handle> will be used for the + * <accept> call. If (<accept_handle> == INVALID_HANDLE), a new + * handle will be created. + * + * <message_block> must be specified. This is because the address of + * the new connection is placed at the end of this buffer. + */ int accept (ACE_Message_Block &message_block, u_long bytes_to_read, ACE_HANDLE accept_handle, const void *act, int priority, int signal_number); - // This starts off an asynchronous accept. The asynchronous accept - // call also allows any initial data to be returned to the - // <handler>. Upto <bytes_to_read> will be read and stored in the - // <message_block>. The <accept_handle> will be used for the - // <accept> call. If (<accept_handle> == INVALID_HANDLE), a new - // handle will be created. - // - // <message_block> must be specified. This is because the address of - // the new connection is placed at the end of this buffer. + /// Destructor. virtual ~ACE_POSIX_SIG_Asynch_Accept (void); - // Destructor. - - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route + + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route // the call to the ACE_POSIX_Asynch_Operation base class. - + + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. private: + /// The thread function that does handle events. static void* thread_function (void* reactor); - // The thread function that does handle events. + /// Reactor to wait on the <listen_handle>. ACE_Reactor reactor_; - // Reactor to wait on the <listen_handle>. + /// The Event Handler to do handle_input. ACE_POSIX_SIG_Asynch_Accept_Handler* accept_handler_; - // The Event Handler to do handle_input. }; +/** + * @class ACE_POSIX_Asynch_Transmit_File_Result + * + * @brief This is that class which will be passed back to the + * <handler> when the asynchronous transmit file completes. + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous transmit file. + */ class ACE_Export ACE_POSIX_Asynch_Transmit_File_Result : public virtual ACE_Asynch_Transmit_File_Result_Impl, public ACE_POSIX_Asynch_Result { - // = TITLE - // This is that class which will be passed back to the - // <handler> when the asynchronous transmit file completes. - // - // = DESCRIPTION - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous transmit file. - + /// Factory classes willl have special permissions. friend class ACE_POSIX_AIOCB_Asynch_Transmit_File; friend class ACE_POSIX_SIG_Asynch_Transmit_File; - // Factory classes willl have special permissions. + /// Handlers do all the job. friend class ACE_POSIX_Asynch_Transmit_Handler; friend class ACE_POSIX_AIOCB_Asynch_Transmit_Handler; friend class ACE_POSIX_SIG_Asynch_Transmit_Handler; - // Handlers do all the job. + /// The Proactor constructs the Result class for faking results. friend class ACE_POSIX_Proactor; - // The Proactor constructs the Result class for faking results. public: + /// Socket used for transmitting the file. ACE_HANDLE socket (void) const; - // Socket used for transmitting the file. + /// File from which the data is read. ACE_HANDLE file (void) const; - // File from which the data is read. + /// Header and trailer data associated with this transmit file. ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer (void) const; - // Header and trailer data associated with this transmit file. + /// The number of bytes which were requested at the start of the + /// asynchronous transmit file. u_long bytes_to_write (void) const; - // The number of bytes which were requested at the start of the - // asynchronous transmit file. + /// Number of bytes per send requested at the start of the transmit + /// file. u_long bytes_per_send (void) const; - // Number of bytes per send requested at the start of the transmit - // file. + /// Flags which were passed into transmit file. u_long flags (void) const; - // Flags which were passed into transmit file. // = Base class operations. These operations are here to kill // dominance warnings. These methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This is the ACT associated with the handle on which the + * Asynch_Operation takes place. + * + * @@ This is not implemented for POSIX4 platforms. + * + */ const void *completion_key (void) const; - // This is the ACT associated with the handle on which the - // Asynch_Operation takes place. - // - // @@ This is not implemented for POSIX4 platforms. - // + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// This returns ACE_INVALID_HANDLE. ACE_HANDLE event (void) const; - // This returns ACE_INVALID_HANDLE. + /** + * This really make sense only when doing file I/O. + * + * @@ On POSIX4-Unix, offset_high should be supported using + * aiocb64. + * + */ u_long offset (void) const; u_long offset_high (void) const; - // This really make sense only when doing file I/O. - // - // @@ On POSIX4-Unix, offset_high should be supported using - // aiocb64. - // + /// The priority of the asynchronous operation. int priority (void) const; - // The priority of the asynchronous operation. + /** + * POSIX4 realtime signal number to be used for the + * operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By + * default, SIGRTMIN is used to issue <aio_> calls. This is a no-op + * on non-POSIX4 systems and returns 0. + */ int signal_number (void) const; - // POSIX4 realtime signal number to be used for the - // operation. <signal_number> ranges from SIGRTMIN to SIGRTMAX. By - // default, SIGRTMIN is used to issue <aio_> calls. This is a no-op - // on non-POSIX4 systems and returns 0. - + + /// Post <this> to the Proactor. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor. protected: ACE_POSIX_Asynch_Transmit_File_Result (ACE_Handler &handler, @@ -1451,46 +1589,60 @@ protected: // Constructor is protected since creation is limited to // ACE_Asynch_Transmit_File factory. + /// ACE_Proactor will call this method when the write completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // ACE_Proactor will call this method when the write completes. + /// Destructor. virtual ~ACE_POSIX_Asynch_Transmit_File_Result (void); - // Destructor. + /// Network I/O handle. ACE_HANDLE socket_; - // Network I/O handle. // aiocb::aio_filedes // File I/O handle. + /// Header and trailer data associated with this transmit file. ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer_; - // Header and trailer data associated with this transmit file. // aiocb::aio_nbytes // The number of bytes which were requested at the start of the // asynchronous transmit file. + /// Number of bytes per send requested at the start of the transmit + /// file. u_long bytes_per_send_; - // Number of bytes per send requested at the start of the transmit - // file. + /// Flags which were passed into transmit file. u_long flags_; - // Flags which were passed into transmit file. }; +/** + * @class ACE_POSIX_AIOCB_Asynch_Transmit_File + * + * @brief Implementation for transmit_file will make use of + * POSIX_AIOCB_Asynch_Transmit_Handler. + */ class ACE_Export ACE_POSIX_AIOCB_Asynch_Transmit_File : public virtual ACE_Asynch_Transmit_File_Impl, public ACE_POSIX_AIOCB_Asynch_Operation { - // = DESCRIPTION - // Implementation for transmit_file will make use of - // POSIX_AIOCB_Asynch_Transmit_Handler. public: + /// Constructor. ACE_POSIX_AIOCB_Asynch_Transmit_File (ACE_POSIX_AIOCB_Proactor *posix_aiocb_proactor); - // Constructor. + /** + * This starts off an asynchronous transmit file. The <file> is a + * handle to an open file. <header_and_trailer> is a pointer to a + * data structure that contains pointers to data to send before and + * after the file data is sent. Set this parameter to 0 if you only + * want to transmit the file data. Upto <bytes_to_write> will be + * written to the <socket>. If you want to send the entire file, + * let <bytes_to_write> = 0. <bytes_per_send> is the size of each + * block of data sent per send operation. Please read the POSIX + * documentation on what the flags should be. + */ int transmit_file (ACE_HANDLE file, ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer, u_long bytes_to_write, @@ -1501,50 +1653,57 @@ public: const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous transmit file. The <file> is a - // handle to an open file. <header_and_trailer> is a pointer to a - // data structure that contains pointers to data to send before and - // after the file data is sent. Set this parameter to 0 if you only - // want to transmit the file data. Upto <bytes_to_write> will be - // written to the <socket>. If you want to send the entire file, - // let <bytes_to_write> = 0. <bytes_per_send> is the size of each - // block of data sent per send operation. Please read the POSIX - // documentation on what the flags should be. + /// Destructor. virtual ~ACE_POSIX_AIOCB_Asynch_Transmit_File (void); - // Destructor. - - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route - // the call to the ACE_POSIX_Asynch_Operation base class. + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route + // the call to the ACE_POSIX_Asynch_Operation base class. + + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. }; +/** + * @class ACE_POSIX_SIG_Asynch_Transmit_File + * + * @brief This class implements <ACE_Asynch_Transmit_File> for + * Realtime Signal (<sigtimedwait>) based implementation of + * Proactor. + */ class ACE_Export ACE_POSIX_SIG_Asynch_Transmit_File : public virtual ACE_Asynch_Transmit_File_Impl, public ACE_POSIX_SIG_Asynch_Operation { - // = TITLE - // This class implements <ACE_Asynch_Transmit_File> for Realtime - // Signal (<sigtimedwait>) based implementation of Proactor. public: + /// Constructor. ACE_POSIX_SIG_Asynch_Transmit_File (ACE_POSIX_SIG_Proactor *posix_sig_proactor); - // Constructor. + /** + * This starts off an asynchronous transmit file. The <file> is a + * handle to an open file. <header_and_trailer> is a pointer to a + * data structure that contains pointers to data to send before and + * after the file data is sent. Set this parameter to 0 if you only + * want to transmit the file data. Upto <bytes_to_write> will be + * written to the <socket>. If you want to send the entire file, + * let <bytes_to_write> = 0. <bytes_per_send> is the size of each + * block of data sent per send operation. + */ int transmit_file (ACE_HANDLE file, ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer, u_long bytes_to_write, @@ -1555,37 +1714,31 @@ public: const void *act, int priority, int signal_number); - // This starts off an asynchronous transmit file. The <file> is a - // handle to an open file. <header_and_trailer> is a pointer to a - // data structure that contains pointers to data to send before and - // after the file data is sent. Set this parameter to 0 if you only - // want to transmit the file data. Upto <bytes_to_write> will be - // written to the <socket>. If you want to send the entire file, - // let <bytes_to_write> = 0. <bytes_per_send> is the size of each - // block of data sent per send operation. + /// Destructor. virtual ~ACE_POSIX_SIG_Asynch_Transmit_File (void); - // Destructor. - - // = Methods belong to ACE_POSIX_Asynch_Operation base class. These - // methods are defined here to avoid dominace warnings. They route - // the call to the ACE_POSIX_Asynch_Operation base class. + // = Methods belong to ACE_POSIX_Asynch_Operation base class. These + // methods are defined here to avoid dominace warnings. They route + // the call to the ACE_POSIX_Asynch_Operation base class. + + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor = 0); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /// + /// @@ Not implemented. Returns 0. int cancel (void); - // - // @@ Not implemented. Returns 0. - + + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. }; #if defined (__ACE_INLINE__) diff --git a/ace/POSIX_Proactor.h b/ace/POSIX_Proactor.h index ef43f442dd9..d8f61a25b0f 100644 --- a/ace/POSIX_Proactor.h +++ b/ace/POSIX_Proactor.h @@ -1,20 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// POSIX_Proactor.h -// -// = AUTHOR -// Irfan Pyarali <irfan@cs.wustl.edu>, -// Tim Harrison <harrison@cs.wustl.edu> and -// Alexander Babu Arulanthu <alex@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file POSIX_Proactor.h + * + * $Id$ + * + * @author Irfan Pyarali <irfan@cs.wustl.edu> + * @author Tim Harrison <harrison@cs.wustl.edu> + * @author Alexander Babu Arulanthu <alex@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_POSIX_PROACTOR_H #define ACE_POSIX_PROACTOR_H @@ -29,25 +26,29 @@ #include "ace/Pipe.h" #include "ace/POSIX_Asynch_IO.h" +/** + * @class ACE_POSIX_Proactor + * + * @brief POSIX implementation of the Proactor. + * + * There are two different strategies by which Proactor can get + * to know the completion of <aio> operations. One is based on + * Asynchronous I/O Control Blocks (AIOCB) where a list of + * AIOCBs are stored and completion status of the corresponding + * operations are queried on them. The other one is based on + * POSIX Real Time signals. This class abstracts out the common + * code needed for both the strategies. <ACE_AIOCB_Proactor> and + * <ACE_SIG_Proactor> specialize this class for each strategy. + */ class ACE_Export ACE_POSIX_Proactor : public ACE_Proactor_Impl { - // = TITLE - // POSIX implementation of the Proactor. - // - // = DESCRIPTION - // There are two different strategies by which Proactor can get - // to know the completion of <aio> operations. One is based on - // Asynchronous I/O Control Blocks (AIOCB) where a list of - // AIOCBs are stored and completion status of the corresponding - // operations are queried on them. The other one is based on - // POSIX Real Time signals. This class abstracts out the common - // code needed for both the strategies. <ACE_AIOCB_Proactor> and - // <ACE_SIG_Proactor> specialize this class for each strategy. + /** + * For <POSIX_SIG_Asynch_Accept> operation, this handler class does + * the actual work, has to register the real-time signal with the + * Proactor. + */ friend class ACE_POSIX_SIG_Asynch_Accept_Handler; - // For <POSIX_SIG_Asynch_Accept> operation, this handler class does - // the actual work, has to register the real-time signal with the - // Proactor. public: enum Proactor_Type @@ -57,44 +58,46 @@ public: PROACTOR_SIG = 2, PROACTOR_SUN = 3 }; - + virtual Proactor_Type get_impl_type (void); + /// Virtual destructor. virtual ~ACE_POSIX_Proactor (void); - // Virtual destructor. + /// Close down the Proactor. virtual int close (void); - // Close down the Proactor. + /// This function is a no-op function for Unix systems. Returns 0. virtual int register_handle (ACE_HANDLE handle, const void *completion_key); - // This function is a no-op function for Unix systems. Returns 0. - + + /** + * Post a result to the completion port of the Proactor. If errors + * occur, the result will be deleted by this method. If successful, + * the result will be deleted by the Proactor when the result is + * removed from the completion port. Therefore, the result should + * have been dynamically allocated and should be orphaned by the + * user once this method is called. + */ virtual int post_completion (ACE_POSIX_Asynch_Result *result) = 0; - // Post a result to the completion port of the Proactor. If errors - // occur, the result will be deleted by this method. If successful, - // the result will be deleted by the Proactor when the result is - // removed from the completion port. Therefore, the result should - // have been dynamically allocated and should be orphaned by the - // user once this method is called. + /// @@ This is a no-op on POSIX platforms. Returns 0. int wake_up_dispatch_threads (void); - // @@ This is a no-op on POSIX platforms. Returns 0. + /// @@ This is a no-op on POSIX platforms. Returns 0. int close_dispatch_threads (int wait); - // @@ This is a no-op on POSIX platforms. Returns 0. + /// @@ This is a no-op on POSIX platforms. Returns 0. size_t number_of_threads (void) const; void number_of_threads (size_t threads); - // @@ This is a no-op on POSIX platforms. Returns 0. + /// This is a no-op in POSIX. Returns ACE_INVALID_HANDLE. virtual ACE_HANDLE get_handle (void) const; - // This is a no-op in POSIX. Returns ACE_INVALID_HANDLE. // Methods used to create Asynch_IO_Result objects. We create the right // objects here in these methods. - virtual ACE_Asynch_Read_Stream_Result_Impl *create_asynch_read_stream_result + virtual ACE_Asynch_Read_Stream_Result_Impl *create_asynch_read_stream_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -104,7 +107,7 @@ public: int priority = 0, int signal_number = ACE_SIGRTMIN); - virtual ACE_Asynch_Write_Stream_Result_Impl *create_asynch_write_stream_result + virtual ACE_Asynch_Write_Stream_Result_Impl *create_asynch_write_stream_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -114,7 +117,7 @@ public: int priority = 0, int signal_number = ACE_SIGRTMIN); - virtual ACE_Asynch_Read_File_Result_Impl *create_asynch_read_file_result + virtual ACE_Asynch_Read_File_Result_Impl *create_asynch_read_file_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -125,8 +128,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - - virtual ACE_Asynch_Write_File_Result_Impl *create_asynch_write_file_result + + virtual ACE_Asynch_Write_File_Result_Impl *create_asynch_write_file_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -138,7 +141,7 @@ public: int priority = 0, int signal_number = ACE_SIGRTMIN); - virtual ACE_Asynch_Accept_Result_Impl *create_asynch_accept_result + virtual ACE_Asynch_Accept_Result_Impl *create_asynch_accept_result (ACE_Handler &handler, ACE_HANDLE listen_handle, ACE_HANDLE accept_handle, @@ -149,7 +152,7 @@ public: int priority = 0, int signal_number = ACE_SIGRTMIN); - virtual ACE_Asynch_Transmit_File_Result_Impl *create_asynch_transmit_file_result + virtual ACE_Asynch_Transmit_File_Result_Impl *create_asynch_transmit_file_result (ACE_Handler &handler, ACE_HANDLE socket, ACE_HANDLE file, @@ -163,89 +166,100 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - - virtual ACE_Asynch_Result_Impl *create_asynch_timer + + /// Create a timer result object which can be used with the Timer + /// mechanism of the Proactor. + virtual ACE_Asynch_Result_Impl *create_asynch_timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &tv, ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create a timer result object which can be used with the Timer - // mechanism of the Proactor. - + protected: + /// Constructor. ACE_POSIX_Proactor (void); - // Constructor. + /** + * Protect against structured exceptions caused by user code when + * dispatching handles. The <completion_key> is not very useful + * compared to <AST> that can be associated each asynchronous + * operation. <completion_key> is implemented right now for the + * POSIX Proators. + */ void application_specific_code (ACE_POSIX_Asynch_Result *asynch_result, u_long bytes_transferred, int success, const void *completion_key, u_long error); - // Protect against structured exceptions caused by user code when - // dispatching handles. The <completion_key> is not very useful - // compared to <AST> that can be associated each asynchronous - // operation. <completion_key> is implemented right now for the - // POSIX Proators. + /** + * Post <how_many> completions to the completion port so that all + * threads can wake up. This is used in conjunction with the + * <run_event_loop>. + */ virtual int post_wakeup_completions (int how_many); - // Post <how_many> completions to the completion port so that all - // threads can wake up. This is used in conjunction with the - // <run_event_loop>. protected: + /// Handler to handle the wakeups. This works in conjunction with the + /// <ACE_Proactor::run_event_loop>. ACE_Handler wakeup_handler_; - // Handler to handle the wakeups. This works in conjunction with the - // <ACE_Proactor::run_event_loop>. }; // Forward declarations. class ACE_AIOCB_Notify_Pipe_Manager; +/** + * @class ACE_POSIX_AIOCB_Proactor + * + * @brief This Proactor makes use of Asynchronous I/O Control Blocks + * (AIOCB) to notify/get the completion status of the <aio_> + * operations issued. + */ class ACE_Export ACE_POSIX_AIOCB_Proactor : public ACE_POSIX_Proactor { - // = TITLE - // This Proactor makes use of Asynchronous I/O Control Blocks - // (AIOCB) to notify/get the completion status of the <aio_> - // operations issued. + /// Handler needs to call application specific code. friend class ACE_AIOCB_Notify_Pipe_Manager; - // Handler needs to call application specific code. - + + /// This class does the registering of Asynch Operations with the + /// Proactor which is necessary in the AIOCB strategy. friend class ACE_POSIX_AIOCB_Asynch_Operation; - // This class does the registering of Asynch Operations with the - // Proactor which is necessary in the AIOCB strategy. // friend class ACE_POSIX_AIOCB_Asynch_Accept_Handler; For // <Asynch_Accept> operation class, this helper class takes care of // doing the <Asynch_Accept>. public: + /// Constructor defines max number asynchronous operations + /// which can be started at the same time ACE_POSIX_AIOCB_Proactor (size_t nmaxop = 256) ; //ACE_RTSIG_MAX - // Constructor defines max number asynchronous operations - // which can be started at the same time virtual Proactor_Type get_impl_type (void); + /// Destructor. virtual ~ACE_POSIX_AIOCB_Proactor (void); - // Destructor. + /** + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (ACE_Time_Value &wait_time); - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. + /** + * Block indefinitely until at least one event is dispatched. + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (void); - // Block indefinitely until at least one event is dispatched. - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. + /// Post a result to the completion port of the Proactor. virtual int post_completion (ACE_POSIX_Asynch_Result *result); - // Post a result to the completion port of the Proactor. // = Methods used to create Asynch_IO objects. We create the right // objects here in these methods. @@ -264,104 +278,119 @@ public: protected: + /// Special constructor for ACE_SUN_Proactor ACE_POSIX_AIOCB_Proactor (size_t nmaxop, int flg); - // Special constructor for ACE_SUN_Proactor - + + /// Call these methods from derived class when virtual table is + /// built. void create_notify_manager (void); void delete_notify_manager (void); - // Call these methods from derived class when virtual table is - // built. - + + /** + * Dispatch a single set of events. If <milli_seconds> elapses + * before any events occur, return 0. Return 1 if a completion + * dispatched. Return -1 on errors. + */ virtual int handle_events (u_long milli_seconds); - // Dispatch a single set of events. If <milli_seconds> elapses - // before any events occur, return 0. Return 1 if a completion - // dispatched. Return -1 on errors. + /// We will call the base class's application_specific_code from + /// here. void application_specific_code (ACE_POSIX_Asynch_Result *asynch_result, u_long bytes_transferred, int success, const void *completion_key, u_long error); - // We will call the base class's application_specific_code from - // here. - + virtual int register_and_start_aio (ACE_POSIX_Asynch_Result *result, int op); virtual int start_aio (ACE_POSIX_Asynch_Result *result, - int op); - + int op); + + /// Extract the results of aio. ACE_POSIX_Asynch_Result *find_completed_aio (int &error_status, int &return_status); - // Extract the results of aio. + /// This class takes care of doing <accept> when we use + /// AIO_CONTROL_BLOCKS strategy. ACE_AIOCB_Notify_Pipe_Manager *aiocb_notify_pipe_manager_; - // This class takes care of doing <accept> when we use - // AIO_CONTROL_BLOCKS strategy. - + + /// Use a dynamically allocated array to keep track of all the aio's + /// issued currently. aiocb **aiocb_list_; ACE_POSIX_Asynch_Result **result_list_; - // Use a dynamically allocated array to keep track of all the aio's - // issued currently. - + + /// To maintain the maximum size of the array (list). size_t aiocb_list_max_size_; - // To maintain the maximum size of the array (list). + /// To maintain the current size of the array (list). size_t aiocb_list_cur_size_; - // To maintain the current size of the array (list). #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) + /// Mutex to protect work with lists. ACE_Thread_Mutex mutex_; - // Mutex to protect work with lists. #endif /* ACE_MT_SAFE */ }; +/** + * @class ACE_POSIX_SIG_Proactor + * + * @brief This Proactor implementation does compeltion querying using + * POSIX Real Time signals. <sigtimedwait>/<sigwaitinfo> call is + * used to get the notify/get the completions. + * The real-time signals that are going to be used with this + * Proactor should be given apriori in the constructor, so that + * those signals can be masked from asynchornous delivery. + */ class ACE_Export ACE_POSIX_SIG_Proactor : public ACE_POSIX_Proactor { - // = TITLE - // This Proactor implementation does compeltion querying using - // POSIX Real Time signals. <sigtimedwait>/<sigwaitinfo> call is - // used to get the notify/get the completions. - // The real-time signals that are going to be used with this - // Proactor should be given apriori in the constructor, so that - // those signals can be masked from asynchornous delivery. + /** + * This class does the registering of Asynch Operations with the + * Proactor which is necessary in the SIG strategy, because we need + * to store the signal number. + */ friend class ACE_POSIX_SIG_Asynch_Operation; - // This class does the registering of Asynch Operations with the - // Proactor which is necessary in the SIG strategy, because we need - // to store the signal number. public: + /** + * This constructor masks only the <ACE_SIGRTMIN> + * real-time signal. Only this signal should be used to issue + * asynchronous operations using this Proctor. + */ ACE_POSIX_SIG_Proactor (void); - // This constructor masks only the <ACE_SIGRTMIN> - // real-time signal. Only this signal should be used to issue - // asynchronous operations using this Proctor. virtual Proactor_Type get_impl_type (void); + /** + * This constructor should be used to tell the Proactor to mask and + * wait for the real-time signals specified in this set. Only these + * signals should be used by the asynchronous operations when they + * use this Proactor. + */ ACE_POSIX_SIG_Proactor (const sigset_t mask_set); - // This constructor should be used to tell the Proactor to mask and - // wait for the real-time signals specified in this set. Only these - // signals should be used by the asynchronous operations when they - // use this Proactor. + /// Destructor. virtual ~ACE_POSIX_SIG_Proactor (void); - // Destructor. + /** + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (ACE_Time_Value &wait_time); - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. + /** + * Block indefinitely until at least one event is dispatched. + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (void); - // Block indefinitely until at least one event is dispatched. - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. - + + /// Post a result to the completion port of the Proactor. virtual int post_completion (ACE_POSIX_Asynch_Result *result); - // Post a result to the completion port of the Proactor. // = Methods used to create Asynch_IO objects. We create the right // objects here in these methods. @@ -378,73 +407,82 @@ public: virtual ACE_Asynch_Transmit_File_Impl *create_asynch_transmit_file (void); + /** + * If <signal_number> is -1, check with the Proactor and use one of + * the signals that is present in the mask set (i.e. the signals for + * which the Proactor will be waiting) of the Proactor. If there are + * more than one signal, the higher numbered signal will be chosen. + */ virtual ACE_Asynch_Result_Impl *create_asynch_timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &tv, ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // If <signal_number> is -1, check with the Proactor and use one of - // the signals that is present in the mask set (i.e. the signals for - // which the Proactor will be waiting) of the Proactor. If there are - // more than one signal, the higher numbered signal will be chosen. protected: + /// To setup the handler for a real-time signbal. int setup_signal_handler (int signal_number) const; - // To setup the handler for a real-time signbal. + /// Dummy signal handler. This wont get called at all, since we are + /// going to be masking the signal in all the threads. static void null_handler (int signal_number, siginfo_t *info, void *context); - // Dummy signal handler. This wont get called at all, since we are - // going to be masking the signal in all the threads. - + + /// To mask all the signals in a thread. int mask_all (void) const; - // To mask all the signals in a thread. + /** + * Dispatch a single set of events. If <milli_seconds> elapses + * before any events occur, return 0. Return 1 if a completion is + * dispatched. Return -1 on errors. + */ virtual int handle_events (u_long milli_seconds); - // Dispatch a single set of events. If <milli_seconds> elapses - // before any events occur, return 0. Return 1 if a completion is - // dispatched. Return -1 on errors. + /** + * These signals are used for completion notification by the + * Proactor. The signals specified while issueing <Asynch + * Operation>s are stored here in this set. These signals are masked + * for a thread when it calls the Proactor::handle_events. + */ sigset_t RT_completion_signals_; - // These signals are used for completion notification by the - // Proactor. The signals specified while issueing <Asynch - // Operation>s are stored here in this set. These signals are masked - // for a thread when it calls the Proactor::handle_events. }; +/** + * @class ACE_POSIX_Asynch_Timer + * + * @brief This class is posted to the completion port when a timer + * expires. When the <complete method> of this object is + * called, the <handler>'s <handle_timeout> method will be + * called. + */ class ACE_Export ACE_POSIX_Asynch_Timer : public ACE_POSIX_Asynch_Result { - // = TITLE - // This class is posted to the completion port when a timer - // expires. When the <complete method> of this object is - // called, the <handler>'s <handle_timeout> method will be - // called. - + + /// The factory method for this class is with the POSIX_Proactor + /// class. friend class ACE_POSIX_Proactor; friend class ACE_POSIX_SIG_Proactor; - // The factory method for this class is with the POSIX_Proactor - // class. protected: + /// Constructor. ACE_POSIX_Asynch_Timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &tv, ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Constructor. - + + /// Destructor. virtual ~ACE_POSIX_Asynch_Timer (void) {} - // Destructor. + /// This method calls the <handler>'s handle_timeout method. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error = 0); - // This method calls the <handler>'s handle_timeout method. + /// Time value requested by caller ACE_Time_Value time_; - // Time value requested by caller }; #if defined (__ACE_INLINE__) diff --git a/ace/Pair.h b/ace/Pair.h index e4722a5975e..4fb5693e948 100644 --- a/ace/Pair.h +++ b/ace/Pair.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Pair.h -// -// = AUTHOR -// Irfan Pyarali -// -// ============================================================================ +//============================================================================= +/** + * @file Pair.h + * + * $Id$ + * + * @author Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_PAIR_H #define ACE_PAIR_H diff --git a/ace/Pair_T.h b/ace/Pair_T.h index 18787e4902b..3d0a9a7575d 100644 --- a/ace/Pair_T.h +++ b/ace/Pair_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Pair_T.h -// -// = AUTHOR -// Irfan Pyarali <irfan@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Pair_T.h + * + * $Id$ + * + * @author Irfan Pyarali <irfan@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_PAIR_T_H #define ACE_PAIR_T_H @@ -24,14 +21,16 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Pair + * + * @brief Defines a pair. + * + * Similar to the STL pair. + */ template <class T1, class T2> class ACE_Pair { - // = TITLE - // Defines a pair. - // - // = DESCRIPTION - // Similar to the STL pair. public: // = Traits. @@ -39,22 +38,22 @@ public: typedef T2 second_type; // = Initialization and termination methods. + /// Constructor. ACE_Pair (const T1 &t1, const T2 &t2); - // Constructor. + /// Default constructor. ACE_Pair (void); - // Default constructor. + /// Get/Set first. T1 &first (void); const T1 &first (void) const; void first (const T1 &t1); - // Get/Set first. + /// Access second. T2 &second (void); const T2 &second (void) const; void second (const T2 &t2); - // Access second. protected: @@ -62,15 +61,17 @@ protected: T2 second_; }; +/** + * @class ACE_Reference_Pair + * + * @brief Defines a pair that only hold references. + * + * Similar to the STL pair (but restricted to holding references + * and not copies). + */ template <class T1, class T2> class ACE_Reference_Pair { - // = TITLE - // Defines a pair that only hold references. - // - // = DESCRIPTION - // Similar to the STL pair (but restricted to holding references - // and not copies). public: // = Traits. @@ -78,15 +79,15 @@ public: typedef T2 second_type; // = Initialization and termination methods. + /// Constructor. ACE_Reference_Pair (T1 &t1, T2 &t2); - // Constructor. + /// Access first. T1 &first (void) const; - // Access first. + /// Access second. T2 &second (void) const; - // Access second. protected: diff --git a/ace/Parse_Node.h b/ace/Parse_Node.h index c3f98b13320..718cb3185d4 100644 --- a/ace/Parse_Node.h +++ b/ace/Parse_Node.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Parse_Node.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Parse_Node.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_PARSE_NODE_H #define ACE_PARSE_NODE_H @@ -24,11 +21,14 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Parse_Node + * + * @brief Provide the base of the object hierarchy that defines the parse + * tree of Service Nodes. + */ class ACE_Export ACE_Parse_Node { - // = TITLE - // Provide the base of the object hierarchy that defines the parse - // tree of Service Nodes. public: ACE_Parse_Node (void); ACE_EXPLICIT ACE_Parse_Node (const ACE_TCHAR *name); @@ -41,72 +41,84 @@ public: const ACE_TCHAR *name (void) const; void print (void) const; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: const ACE_TCHAR *name_; ACE_Parse_Node *next_; }; +/** + * @class ACE_Suspend_Node + * + * @brief Suspend a Service Node. + */ class ACE_Export ACE_Suspend_Node : public ACE_Parse_Node { - // = TITLE - // Suspend a Service Node. public: ACE_Suspend_Node (const ACE_TCHAR *name); ~ACE_Suspend_Node (void); virtual void apply (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Resume_Node + * + * @brief Resume a Service Node. + */ class ACE_Export ACE_Resume_Node : public ACE_Parse_Node { - // = TITLE - // Resume a Service Node. public: ACE_Resume_Node (const ACE_TCHAR *name); ~ACE_Resume_Node (void); virtual void apply (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Remove_Node + * + * @brief Remove a Service Node. + */ class ACE_Export ACE_Remove_Node : public ACE_Parse_Node { - // = TITLE - // Remove a Service Node. public: ACE_Remove_Node (const ACE_TCHAR *name); ~ACE_Remove_Node (void); virtual void apply (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Static_Node + * + * @brief Handle a statically linked node. + */ class ACE_Export ACE_Static_Node : public ACE_Parse_Node { - // = TITLE - // Handle a statically linked node. public: ACE_Static_Node (const ACE_TCHAR *name, ACE_TCHAR *params = 0); virtual ~ACE_Static_Node (void); @@ -115,21 +127,24 @@ public: virtual const ACE_Service_Type *record (void) const; ACE_TCHAR *parameters (void) const; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// "Command-line" parameters. ACE_TCHAR *parameters_; - // "Command-line" parameters. }; +/** + * @class ACE_Dynamic_Node + * + * @brief Handle a dynamically linked node. + */ class ACE_Export ACE_Dynamic_Node : public ACE_Static_Node { - // = TITLE - // Handle a dynamically linked node. public: ACE_Dynamic_Node (const ACE_Service_Type *, ACE_TCHAR *params); virtual ~ACE_Dynamic_Node (void); @@ -137,43 +152,49 @@ public: virtual const ACE_Service_Type *record (void) const; virtual void apply (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to a descriptor that describes this node. const ACE_Service_Type *record_; - // Pointer to a descriptor that describes this node. }; +/** + * @class ACE_Stream_Node + * + * @brief Handle a Stream. + */ class ACE_Export ACE_Stream_Node : public ACE_Parse_Node { - // = TITLE - // Handle a Stream. public: ACE_Stream_Node (const ACE_Static_Node *, const ACE_Parse_Node *); virtual ~ACE_Stream_Node (void); virtual void apply (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Linked list of modules that are part of the stream. const ACE_Static_Node *node_; const ACE_Parse_Node *mods_; - // Linked list of modules that are part of the stream. }; +/** + * @class ACE_Location_Node + * + * @brief Keep track of where a shared library is located. + */ class ACE_Export ACE_Location_Node { - // = TITLE - // Keep track of where a shared library is located. public: ACE_Location_Node (void); virtual void *symbol (ACE_Service_Object_Exterminator * = 0) = 0; @@ -186,111 +207,125 @@ public: virtual ~ACE_Location_Node (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: ACE_SHLIB_HANDLE open_handle (void); + /// Pathname to the shared library we are working on. const ACE_TCHAR *pathname_; - // Pathname to the shared library we are working on. + /** + * Flag indicating whether the Service_Object generated by this + * Location Node should be deleted or not + * (ACE_Service_Type::DELETE_OBJ.) + */ int must_delete_; - // Flag indicating whether the Service_Object generated by this - // Location Node should be deleted or not - // (ACE_Service_Type::DELETE_OBJ.) + /// Handle to the open shared library. ACE_SHLIB_HANDLE handle_; - // Handle to the open shared library. + /// Symbol that we've obtained from the shared library. void *symbol_; - // Symbol that we've obtained from the shared library. }; +/** + * @class ACE_Object_Node + * + * @brief Keeps track of the symbol name for a shared object. + */ class ACE_Export ACE_Object_Node : public ACE_Location_Node { - // = TITLE - // Keeps track of the symbol name for a shared object. public: ACE_Object_Node (const ACE_TCHAR *pathname, const ACE_TCHAR *obj_name); virtual void *symbol (ACE_Service_Object_Exterminator * = 0); virtual ~ACE_Object_Node (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Name of the object that we're parsing. const ACE_TCHAR *object_name_; - // Name of the object that we're parsing. }; +/** + * @class ACE_Function_Node + * + * @brief Keeps track of the symbol name of for a shared function. + */ class ACE_Export ACE_Function_Node : public ACE_Location_Node { - // = TITLE - // Keeps track of the symbol name of for a shared function. public: ACE_Function_Node (const ACE_TCHAR *pathname, const ACE_TCHAR *func_name); virtual void *symbol (ACE_Service_Object_Exterminator *gobbler = 0); virtual ~ACE_Function_Node (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Name of the function that we're parsing. const ACE_TCHAR *function_name_; - // Name of the function that we're parsing. }; +/** + * @class ACE_Dummy_Node + * + * @brief I forget why this is here... ;-) + */ class ACE_Export ACE_Dummy_Node : public ACE_Parse_Node { - // = TITLE - // I forget why this is here... ;-) public: ACE_Dummy_Node (const ACE_Static_Node *, const ACE_Parse_Node *); ~ACE_Dummy_Node (void); virtual void apply (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Linked list of modules that we're dealing with. const ACE_Static_Node *node_; const ACE_Parse_Node *mods_; - // Linked list of modules that we're dealing with. }; +/** + * @class ACE_Static_Function_Node + * + * @brief Keeps track of the symbol name for a function that is not + * linked in from a DLL, but is statically linked with the + * application. + */ class ACE_Export ACE_Static_Function_Node : public ACE_Location_Node { - // = TITLE - // Keeps track of the symbol name for a function that is not - // linked in from a DLL, but is statically linked with the - // application. public: ACE_EXPLICIT ACE_Static_Function_Node (const ACE_TCHAR *func_name); virtual void *symbol (ACE_Service_Object_Exterminator * = 0); virtual ~ACE_Static_Function_Node (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Name of the function that we're parsing. const ACE_TCHAR *function_name_; - // Name of the function that we're parsing. }; #if defined (__ACE_INLINE__) diff --git a/ace/Pipe.h b/ace/Pipe.h index 7fe3a772d04..d58767b1729 100644 --- a/ace/Pipe.h +++ b/ace/Pipe.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Pipe.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Pipe.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_PIPE_H #define ACE_PIPE_H @@ -24,52 +21,58 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Pipe + * + * @brief Provides a bidirectional "pipe" abstraction that is portable + * to Windows NT, SVR4 UNIX, and BSD UNIX. + * + * Uses "name" for lookup in the ACE service repository. Obtains + * the object and returns it as the appropriate type. + */ class ACE_Export ACE_Pipe { - // = TITLE - // Provides a bidirectional "pipe" abstraction that is portable - // to Windows NT, SVR4 UNIX, and BSD UNIX. - // - // = DESCRIPTION - // Uses "name" for lookup in the ACE service repository. Obtains - // the object and returns it as the appropriate type. public: // = Initialization and termination. + /// Default constructor (does nothing...). ACE_Pipe (void); - // Default constructor (does nothing...). + /// Open the pipe and initialize the handles. ACE_Pipe (ACE_HANDLE handles[2]); - // Open the pipe and initialize the handles. + /// Initialize the <ACE_Pipe> from the <read> and <write> handles. ACE_Pipe (ACE_HANDLE read, ACE_HANDLE write); - // Initialize the <ACE_Pipe> from the <read> and <write> handles. + /// Default dtor. It doesn't close the handles for you. ~ACE_Pipe (void); - // Default dtor. It doesn't close the handles for you. + /// Open the pipe and initialize the handles. int open (ACE_HANDLE handles[2]); - // Open the pipe and initialize the handles. + /// Open the pipe, setting the buffer size to the maximum. int open (int buffer_size = ACE_DEFAULT_MAX_SOCKET_BUFSIZ); - // Open the pipe, setting the buffer size to the maximum. + /// Close down the pipe HANDLEs; int close (void); - // Close down the pipe HANDLEs; // = Accessors. + /** + * This is the "read" side of the pipe. Note, however, that + * processes can also write to this handle as well since pipes are + * bi-directional. + */ ACE_HANDLE read_handle (void) const; - // This is the "read" side of the pipe. Note, however, that - // processes can also write to this handle as well since pipes are - // bi-directional. + /** + * This is the "write" side of the pipe. Note, however, that + * processes can also read to this handle as well since pipes are + * bi-directional. + */ ACE_HANDLE write_handle (void) const; - // This is the "write" side of the pipe. Note, however, that - // processes can also read to this handle as well since pipes are - // bi-directional. + /// Dump the state of the object. void dump (void) const; - // Dump the state of the object. private: ACE_HANDLE handles_[2]; diff --git a/ace/Priority_Reactor.h b/ace/Priority_Reactor.h index ed059d70da7..d2e63ee5f63 100644 --- a/ace/Priority_Reactor.h +++ b/ace/Priority_Reactor.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Priority_Reactor.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Priority_Reactor.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_PRIORITY_REACTOR_H #define ACE_PRIORITY_REACTOR_H @@ -26,65 +23,67 @@ #include "ace/Select_Reactor.h" +/** + * @class ACE_Priority_Reactor + * + * @brief Implements priority based dispatching. + * + * This class refines the dispatching mechanism for the + * Select_Reactor by taking advantage of the priority method on + * ACE_Event_Handler. + */ class ACE_Export ACE_Priority_Reactor : public ACE_Select_Reactor { - // = TITLE - // Implements priority based dispatching. - // - // = DESCRIPTION - // This class refines the dispatching mechanism for the - // Select_Reactor by taking advantage of the priority method on - // ACE_Event_Handler. public: // = Initialization and termination methods. + /// Initialize <ACE_Priority_Reactor> with the default size. ACE_Priority_Reactor (ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0); - // Initialize <ACE_Priority_Reactor> with the default size. + /// Initialize <ACE_Priority_Reactor> with size <size>. ACE_Priority_Reactor (size_t size, int restart = 0, ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0); - // Initialize <ACE_Priority_Reactor> with size <size>. + /// Close down the select_reactor and release all of its resources. virtual ~ACE_Priority_Reactor (void); - // Close down the select_reactor and release all of its resources. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Dispatching methods. + /// We simply override this function to implement the priority + /// dispatching. virtual int dispatch_io_set (int number_of_active_handles, int &number_dispatched, int mask, ACE_Handle_Set &dispatch_mask, ACE_Handle_Set &ready_mask, ACE_EH_PTMF callback); - // We simply override this function to implement the priority - // dispatching. private: + /// A small helper to initialize the bucket. void init_bucket (void); - // A small helper to initialize the bucket. + /// There is a queue per-priority, which simply holds the + /// Event_Handlers until we knwo who goes first. typedef ACE_Unbounded_Queue<ACE_Event_Tuple> QUEUE; QUEUE** bucket_; - // There is a queue per-priority, which simply holds the - // Event_Handlers until we knwo who goes first. + /// The queues themselves use this allocator to minimize dynamic + /// memory usage. ACE_Allocator* tuple_allocator_; - // The queues themselves use this allocator to minimize dynamic - // memory usage. + /// Deny access since member-wise won't work... ACE_Priority_Reactor (const ACE_Select_Reactor &); ACE_Priority_Reactor &operator = (const ACE_Select_Reactor &); - // Deny access since member-wise won't work... }; #include "ace/post.h" diff --git a/ace/Proactor.h b/ace/Proactor.h index 05f1cb72a03..e82af128929 100644 --- a/ace/Proactor.h +++ b/ace/Proactor.h @@ -1,20 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Proactor.h -// -// = AUTHOR -// Irfan Pyarali <irfan@cs.wustl.edu>, -// Tim Harrison <harrison@cs.wustl.edu> and -// Alexander Babu Arulanthu <alex@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Proactor.h + * + * $Id$ + * + * @author Irfan Pyarali <irfan@cs.wustl.edu> + * @author Tim Harrison <harrison@cs.wustl.edu> + * @author Alexander Babu Arulanthu <alex@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_PROACTOR_H #define ACE_PROACTOR_H @@ -42,62 +39,66 @@ class ACE_Proactor_Impl; class ACE_Proactor_Timer_Handler; +/** + * @class ACE_Proactor_Handle_Timeout_Upcall + * + * @brief Functor for <ACE_Timer_Queue>. + * + * This class implements the functor required by the Timer + * Queue to call <handle_timeout> on ACE_Handlers. + */ class ACE_Export ACE_Proactor_Handle_Timeout_Upcall { - // = TITLE - // Functor for <ACE_Timer_Queue>. - // - // = DESCRIPTION - // This class implements the functor required by the Timer - // Queue to call <handle_timeout> on ACE_Handlers. - + + /// Type def for the timer queue. typedef ACE_Timer_Queue_T<ACE_Handler *, ACE_Proactor_Handle_Timeout_Upcall, ACE_SYNCH_RECURSIVE_MUTEX> TIMER_QUEUE; - // Type def for the timer queue. - + + /// The main Proactor class has special permissions. friend class ACE_Proactor; - // The main Proactor class has special permissions. public: + /// Constructor. ACE_Proactor_Handle_Timeout_Upcall (void); - // Constructor. - + + /// This method is called when the timer expires. int timeout (TIMER_QUEUE &timer_queue, ACE_Handler *handler, const void *arg, const ACE_Time_Value &cur_time); - // This method is called when the timer expires. + /// This method is called when the timer is canceled. int cancellation (TIMER_QUEUE &timer_queue, ACE_Handler *handler); - // This method is called when the timer is canceled. + /// This method is called when the timer queue is destroyed and the + /// timer is still contained in it. int deletion (TIMER_QUEUE &timer_queue, ACE_Handler *handler, const void *arg); - // This method is called when the timer queue is destroyed and the - // timer is still contained in it. protected: + /// Set the proactor. This will fail, if one is already set! int proactor (ACE_Proactor &proactor); - // Set the proactor. This will fail, if one is already set! + /// Handle to the proactor. This is needed for posting a timer result + /// to the Proactor's completion queue. ACE_Proactor *proactor_; - // Handle to the proactor. This is needed for posting a timer result - // to the Proactor's completion queue. }; +/** + * @class ACE_Proactor + * + * @brief A manager for asynchronous event demultiplexing. + * + * See the Proactor pattern description at + * http://www.cs.wustl.edu/~schmidt/proactor.ps.gz for more + * details. + */ class ACE_Export ACE_Proactor { - // = TITLE - // A manager for asynchronous event demultiplexing. - // - // = DESCRIPTION - // See the Proactor pattern description at - // http://www.cs.wustl.edu/~schmidt/proactor.ps.gz for more - // details. // = Here are the private typedefs that the <ACE_Proactor> uses. @@ -129,87 +130,95 @@ class ACE_Export ACE_Proactor ACE_Proactor_Handle_Timeout_Upcall, ACE_SYNCH_RECURSIVE_MUTEX> TIMER_WHEEL_ITERATOR; - + // = Friendship. - + + /// Timer handler runs a thread and manages the timers, on behalf of + /// the Proactor. friend class ACE_Proactor_Timer_Handler; - // Timer handler runs a thread and manages the timers, on behalf of - // the Proactor. public: + /// Public type. typedef ACE_Timer_Queue_T<ACE_Handler *, ACE_Proactor_Handle_Timeout_Upcall, ACE_SYNCH_RECURSIVE_MUTEX> TIMER_QUEUE; - // Public type. + /** + * Constructor. If <implementation> is 0, the correct implementation + * object will be created. <delete_implementation> flag determines + * whether the implementation object should be deleted by the + * Proactor or not. If <tq> is 0, a new TIMER_QUEUE is created. + */ ACE_Proactor (ACE_Proactor_Impl *implementation = 0, int delete_implementation = 0, TIMER_QUEUE *tq = 0); - // Constructor. If <implementation> is 0, the correct implementation - // object will be created. <delete_implementation> flag determines - // whether the implementation object should be deleted by the - // Proactor or not. If <tq> is 0, a new TIMER_QUEUE is created. + /// Virtual destruction. virtual ~ACE_Proactor (void); - // Virtual destruction. + /// Get pointer to a process-wide <ACE_Proactor>. <threads> should + /// be part of another method. static ACE_Proactor *instance (size_t threads = 0); - // Get pointer to a process-wide <ACE_Proactor>. <threads> should - // be part of another method. + /// Set pointer to a process-wide <ACE_Proactor> and return existing + /// pointer. static ACE_Proactor *instance (ACE_Proactor *); - // Set pointer to a process-wide <ACE_Proactor> and return existing - // pointer. + /// Delete the dynamically allocated Singleton. static void close_singleton (void); - // Delete the dynamically allocated Singleton. + /// Cleanup method, used by the <ACE_Object_Manager> to destroy the + /// singleton. static void cleanup (void *instance, void *arg); - // Cleanup method, used by the <ACE_Object_Manager> to destroy the - // singleton. - + // = Proactor event loop management methods. + /// Run the event loop until the <ACE_Proactor::handle_events> method + /// returns -1 or the <end_event_loop> method is invoked. static int run_event_loop (void); - // Run the event loop until the <ACE_Proactor::handle_events> method - // returns -1 or the <end_event_loop> method is invoked. + /** + * Run the event loop until the <ACE_Proactor::handle_events> method + * returns -1, the <end_event_loop> method is invoked, or the + * <ACE_Time_Value> expires. + */ static int run_event_loop (ACE_Time_Value &tv); - // Run the event loop until the <ACE_Proactor::handle_events> method - // returns -1, the <end_event_loop> method is invoked, or the - // <ACE_Time_Value> expires. + /** + * Instruct the <ACE_Proactor::instance> to terminate its event + * loop. + * This method wakes up all the threads blocked on waiting for + * completions and end the event loop. + */ static int end_event_loop (void); - // Instruct the <ACE_Proactor::instance> to terminate its event - // loop. - // This method wakes up all the threads blocked on waiting for - // completions and end the event loop. + /// Report if the <ACE_Proactor::instance> event loop is finished. static int event_loop_done (void); - // Report if the <ACE_Proactor::instance> event loop is finished. + /// Close the IO completion port. virtual int close (void); - // Close the IO completion port. + /// This method adds the <handle> to the I/O completion port. This + /// function is a no-op function for Unix systems and returns 0; virtual int register_handle (ACE_HANDLE handle, const void *completion_key); - // This method adds the <handle> to the I/O completion port. This - // function is a no-op function for Unix systems and returns 0; // = Timer management. + /** + * Schedule a <handler> that will expire after <time>. If it + * expires then <act> is passed in as the value to the <handler>'s + * <handle_timeout> callback method. This method returns a + * <timer_id>. This <timer_id> can be used to cancel a timer before + * it expires. The cancellation ensures that <timer_ids> are unique + * up to values of greater than 2 billion timers. As long as timers + * don't stay around longer than this there should be no problems + * with accidentally deleting the wrong timer. Returns -1 on + * failure (which is guaranteed never to be a valid <timer_id>). + */ virtual long schedule_timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &time); - // Schedule a <handler> that will expire after <time>. If it - // expires then <act> is passed in as the value to the <handler>'s - // <handle_timeout> callback method. This method returns a - // <timer_id>. This <timer_id> can be used to cancel a timer before - // it expires. The cancellation ensures that <timer_ids> are unique - // up to values of greater than 2 billion timers. As long as timers - // don't stay around longer than this there should be no problems - // with accidentally deleting the wrong timer. Returns -1 on - // failure (which is guaranteed never to be a valid <timer_id>). virtual long schedule_repeating_timer (ACE_Handler &handler, const void *act, @@ -218,97 +227,106 @@ public: // Same as above except <interval> it is used to reschedule the // <handler> automatically. + /// This combines the above two methods into one. Mostly for backward + /// compatibility. virtual long schedule_timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &time, const ACE_Time_Value &interval); - // This combines the above two methods into one. Mostly for backward - // compatibility. + /// Cancel all timers associated with this <handler>. Returns number + /// of timers cancelled. virtual int cancel_timer (ACE_Handler &handler, int dont_call_handle_close = 1); - // Cancel all timers associated with this <handler>. Returns number - // of timers cancelled. + /** + * Cancel the single <ACE_Handler> that matches the <timer_id> value + * (which was returned from the <schedule> method). If <act> is + * non-NULL then it will be set to point to the ``magic cookie'' + * argument passed in when the <Handler> was registered. This makes + * it possible to free up the memory and avoid memory leaks. + * Returns 1 if cancellation succeeded and 0 if the <timer_id> + * wasn't found. + */ virtual int cancel_timer (long timer_id, const void **act = 0, int dont_call_handle_close = 1); - // Cancel the single <ACE_Handler> that matches the <timer_id> value - // (which was returned from the <schedule> method). If <act> is - // non-NULL then it will be set to point to the ``magic cookie'' - // argument passed in when the <Handler> was registered. This makes - // it possible to free up the memory and avoid memory leaks. - // Returns 1 if cancellation succeeded and 0 if the <timer_id> - // wasn't found. + /** + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (ACE_Time_Value &wait_time); - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. + /** + * Block indefinitely until at least one event is dispatched. + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (void); - // Block indefinitely until at least one event is dispatched. - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. + /// Add wakeup dispatch threads (reinit). int wake_up_dispatch_threads (void); - // Add wakeup dispatch threads (reinit). + /// Close all dispatch threads. int close_dispatch_threads (int wait); - // Close all dispatch threads. + /// Number of thread used as a parameter to CreatIoCompletionPort. size_t number_of_threads (void) const; void number_of_threads (size_t threads); - // Number of thread used as a parameter to CreatIoCompletionPort. + /// Get/Set timer queue. TIMER_QUEUE *timer_queue (void) const; void timer_queue (TIMER_QUEUE *timer_queue); - // Get/Set timer queue. - + + /** + * Get the event handle. + * It is a no-op in POSIX platforms and it returns + * ACE_INVALID_HANDLE. + */ virtual ACE_HANDLE get_handle (void) const; - // Get the event handle. - // It is a no-op in POSIX platforms and it returns - // ACE_INVALID_HANDLE. + /// Get the implementation class. virtual ACE_Proactor_Impl *implementation (void) const; - // Get the implementation class. // = Factory methods for the operations // Note that the user does not have to use or know about these // methods. + /// Create the correct implementation class for doing + /// Asynch_Read_Stream. virtual ACE_Asynch_Read_Stream_Impl *create_asynch_read_stream (void); - // Create the correct implementation class for doing - // Asynch_Read_Stream. + /// Create the correct implementation class for doing + /// Asynch_Write_Stream. virtual ACE_Asynch_Write_Stream_Impl *create_asynch_write_stream (void); - // Create the correct implementation class for doing - // Asynch_Write_Stream. + /// Create the correct implementation class for doing + /// Asynch_Read_File. virtual ACE_Asynch_Read_File_Impl *create_asynch_read_file (void); - // Create the correct implementation class for doing - // Asynch_Read_File. + /// Create the correct implementation class for doing + /// Asynch_Write_File. virtual ACE_Asynch_Write_File_Impl *create_asynch_write_file (void); - // Create the correct implementation class for doing - // Asynch_Write_File. + /// Create the correct implementation class for doing Asynch_Accept. virtual ACE_Asynch_Accept_Impl *create_asynch_accept (void); - // Create the correct implementation class for doing Asynch_Accept. + /// Create the correct implementation class for doing + /// Asynch_Transmit_File. virtual ACE_Asynch_Transmit_File_Impl *create_asynch_transmit_file (void); - // Create the correct implementation class for doing - // Asynch_Transmit_File. // = Factory methods for the results // Note that the user does not have to use or know about these // methods unless they want to "fake" results. + /// Create the correct implementation class for ACE_Asynch_Read_Stream::Result class. virtual ACE_Asynch_Read_Stream_Result_Impl *create_asynch_read_stream_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -317,8 +335,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Read_Stream::Result class. + /// Create the correct implementation class for ACE_Asynch_Write_Stream::Result. virtual ACE_Asynch_Write_Stream_Result_Impl *create_asynch_write_stream_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -327,8 +345,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Write_Stream::Result. + /// Create the correct implementation class for ACE_Asynch_Read_File::Result. virtual ACE_Asynch_Read_File_Result_Impl *create_asynch_read_file_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -339,8 +357,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Read_File::Result. + /// Create the correct implementation class for ACE_Asynch_Write_File::Result. virtual ACE_Asynch_Write_File_Result_Impl *create_asynch_write_file_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -351,8 +369,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Write_File::Result. + /// Create the correct implementation class for ACE_Asynch_Accept::Result. virtual ACE_Asynch_Accept_Result_Impl *create_asynch_accept_result (ACE_Handler &handler, ACE_HANDLE listen_handle, ACE_HANDLE accept_handle, @@ -362,8 +380,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Accept::Result. + /// Create the correct implementation class for ACE_Asynch_Transmit_File::Result. virtual ACE_Asynch_Transmit_File_Result_Impl *create_asynch_transmit_file_result (ACE_Handler &handler, ACE_HANDLE socket, ACE_HANDLE file, @@ -377,66 +395,69 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Transmit_File::Result. - + + /** + * Create a timer result object which can be used with the Timer + * mechanism of the Proactor. + * If <signal_number> is -1, <POSIX_SIG_Proactor> will create a + * Timer object with a meaningful signal number, choosing the + * largest signal number from the signal mask of the Proactor. + */ virtual ACE_Asynch_Result_Impl *create_asynch_timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &tv, ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create a timer result object which can be used with the Timer - // mechanism of the Proactor. - // If <signal_number> is -1, <POSIX_SIG_Proactor> will create a - // Timer object with a meaningful signal number, choosing the - // largest signal number from the signal mask of the Proactor. protected: + /** + * Post <how_many> completions to the completion port so that all + * threads can wake up. This is used in conjunction with the + * <run_event_loop>. + */ static int post_wakeup_completions (int how_many); - // Post <how_many> completions to the completion port so that all - // threads can wake up. This is used in conjunction with the - // <run_event_loop>. + /// Set the implementation class. virtual void implementation (ACE_Proactor_Impl *implementation); - // Set the implementation class. + /// Delegation/implementation class that all methods will be + /// forwarded to. ACE_Proactor_Impl *implementation_; - // Delegation/implementation class that all methods will be - // forwarded to. + /// Flag used to indicate whether we are responsible for cleaning up + /// the implementation instance. int delete_implementation_; - // Flag used to indicate whether we are responsible for cleaning up - // the implementation instance. + /// Pointer to a process-wide <ACE_Proactor>. static ACE_Proactor *proactor_; - // Pointer to a process-wide <ACE_Proactor>. + /// Must delete the <proactor_> if non-0. static int delete_proactor_; - // Must delete the <proactor_> if non-0. - + + /// Handles timeout events. ACE_Proactor_Timer_Handler *timer_handler_; - // Handles timeout events. - + + /// This will manage the thread in the Timer_Handler. ACE_Thread_Manager thr_mgr_; - // This will manage the thread in the Timer_Handler. + /// Timer Queue. TIMER_QUEUE *timer_queue_; - // Timer Queue. + /// Flag on whether to delete the timer queue. int delete_timer_queue_; - // Flag on whether to delete the timer queue. + /// Terminate the proactor event loop. static sig_atomic_t end_event_loop_; - // Terminate the proactor event loop. + /// Number of threads in the event loop. static sig_atomic_t event_loop_thread_count_; - // Number of threads in the event loop. private: + /// Deny access since member-wise won't work... ACE_Proactor (const ACE_Proactor &); ACE_Proactor &operator= (const ACE_Proactor &); - // Deny access since member-wise won't work... }; #else /* NOT WIN32 or POSIX with AIO features. */ @@ -449,26 +470,26 @@ public: virtual int handle_events (void) { return -1; } virtual int handle_events (ACE_Time_Value &) { return -1; } + /// Placeholder to enable compilation on non-Win32 platforms static ACE_Proactor *instance (size_t threads = 0); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static ACE_Proactor *instance (ACE_Proactor *); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static void close_singleton (void); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static int run_event_loop (void); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static int run_event_loop (ACE_Time_Value &tv); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static int end_event_loop (void); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static sig_atomic_t event_loop_done (void); - // Placeholder to enable compilation on non-Win32 platforms }; #endif /* ACE_WIN32 && !ACE_HAS_WINCE || ACE_HAS_AIO_CALLS*/ #include "ace/post.h" diff --git a/ace/Proactor_Impl.h b/ace/Proactor_Impl.h index bb302387088..979fc7a0a30 100644 --- a/ace/Proactor_Impl.h +++ b/ace/Proactor_Impl.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Proactor_Impl.h -// -// = AUTHOR -// Alexander Babu Arulanthu <alex@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Proactor_Impl.h + * + * $Id$ + * + * @author Alexander Babu Arulanthu <alex@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_PROACTOR_IMPL_H #define ACE_PROACTOR_IMPL_H @@ -22,93 +19,98 @@ #if ((defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)) || (defined (ACE_HAS_AIO_CALLS))) // This only works on Win32 platforms and on Unix platforms supporting -// aio calls. +// aio calls. #include "ace/Asynch_IO.h" #include "ace/Reactor.h" +/** + * @class ACE_Proactor_Impl + * + * @brief A manager for asynchronous event demultiplexing. This class + * is the base class for all the concrete implementation + * classes. + * + * See the Proactor pattern description at + * http://www.cs.wustl.edu/~schmidt/proactor.ps.gz for more + * details. + */ class ACE_Export ACE_Proactor_Impl : public ACE_Event_Handler { - // = TITLE - // - // A manager for asynchronous event demultiplexing. This class - // is the base class for all the concrete implementation - // classes. - // - // = DESCRIPTION - // - // See the Proactor pattern description at - // http://www.cs.wustl.edu/~schmidt/proactor.ps.gz for more - // details. - + public: + /// Virtual destruction. virtual ~ACE_Proactor_Impl (void) {} - // Virtual destruction. + /// Close the IO completion port. virtual int close (void) = 0; - // Close the IO completion port. + /// This method adds the <handle> to the I/O completion port. This + /// function is a no-op function for Unix systems. virtual int register_handle (ACE_HANDLE handle, const void *completion_key) = 0; - // This method adds the <handle> to the I/O completion port. This - // function is a no-op function for Unix systems. + /** + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (ACE_Time_Value &wait_time) = 0; - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. - + + /** + * Block indefinitely until at least one event is dispatched. + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (void) = 0; - // Block indefinitely until at least one event is dispatched. - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. - + + /// Add wakeup dispatch threads (reinit). virtual int wake_up_dispatch_threads (void) = 0; - // Add wakeup dispatch threads (reinit). + /// Close all dispatch threads. virtual int close_dispatch_threads (int wait) = 0; - // Close all dispatch threads. + /// Number of thread used as a parameter to CreatIoCompletionPort. virtual size_t number_of_threads (void) const = 0; virtual void number_of_threads (size_t threads) = 0; - // Number of thread used as a parameter to CreatIoCompletionPort. + /// Get the event handle. virtual ACE_HANDLE get_handle (void) const = 0; - // Get the event handle. - + // // = Factory methods for the operations // // Note that the user does not have to use or know about these // methods. + /// Create the correct implementation class for doing Asynch_Read_Stream. virtual ACE_Asynch_Read_Stream_Impl *create_asynch_read_stream (void) = 0; - // Create the correct implementation class for doing Asynch_Read_Stream. + /// Create the correct implementation class for doing Asynch_Write_Stream. virtual ACE_Asynch_Write_Stream_Impl *create_asynch_write_stream (void) = 0; - // Create the correct implementation class for doing Asynch_Write_Stream. - + + /// Create the correct implementation class for doing Asynch_Read_File. virtual ACE_Asynch_Read_File_Impl *create_asynch_read_file (void) = 0; - // Create the correct implementation class for doing Asynch_Read_File. - + + /// Create the correct implementation class for doing Asynch_Write_File. virtual ACE_Asynch_Write_File_Impl *create_asynch_write_file (void) = 0; - // Create the correct implementation class for doing Asynch_Write_File. + /// Create the correct implementation class for doing Asynch_Accept. virtual ACE_Asynch_Accept_Impl *create_asynch_accept (void) = 0; - // Create the correct implementation class for doing Asynch_Accept. - + + /// Create the correct implementation class for doing Asynch_Transmit_File. virtual ACE_Asynch_Transmit_File_Impl *create_asynch_transmit_file (void) = 0; - // Create the correct implementation class for doing Asynch_Transmit_File. - + // // = Factory methods for the results // // Note that the user does not have to use or know about these // methods unless they want to "fake" results. + /// Create the correct implementation class for ACE_Asynch_Read_Stream::Result class. virtual ACE_Asynch_Read_Stream_Result_Impl *create_asynch_read_stream_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -117,8 +119,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN) = 0; - // Create the correct implementation class for ACE_Asynch_Read_Stream::Result class. - + + /// Create the correct implementation class for ACE_Asynch_Write_Stream::Result. virtual ACE_Asynch_Write_Stream_Result_Impl *create_asynch_write_stream_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -127,8 +129,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN) = 0; - // Create the correct implementation class for ACE_Asynch_Write_Stream::Result. - + + /// Create the correct implementation class for ACE_Asynch_Read_File::Result. virtual ACE_Asynch_Read_File_Result_Impl *create_asynch_read_file_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -139,8 +141,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN) = 0; - // Create the correct implementation class for ACE_Asynch_Read_File::Result. - + + /// Create the correct implementation class for ACE_Asynch_Write_File::Result. virtual ACE_Asynch_Write_File_Result_Impl *create_asynch_write_file_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -151,8 +153,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN) = 0; - // Create the correct implementation class for ACE_Asynch_Write_File::Result. - + + /// Create the correct implementation class for ACE_Asynch_Accept::Result. virtual ACE_Asynch_Accept_Result_Impl *create_asynch_accept_result (ACE_Handler &handler, ACE_HANDLE listen_handle, ACE_HANDLE accept_handle, @@ -162,8 +164,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN) = 0; - // Create the correct implementation class for ACE_Asynch_Accept::Result. - + + /// Create the correct implementation class for ACE_Asynch_Transmit_File::Result. virtual ACE_Asynch_Transmit_File_Result_Impl *create_asynch_transmit_file_result (ACE_Handler &handler, ACE_HANDLE socket, ACE_HANDLE file, @@ -177,22 +179,25 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN) = 0; - // Create the correct implementation class for ACE_Asynch_Transmit_File::Result. + /** + * Create the correct implementation object for the Timer + * result. POSIX_SIG_Proactor will create a Timer object with a + * meaningful signal number, if you leave the signal number as 0. + */ virtual ACE_Asynch_Result_Impl *create_asynch_timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &tv, ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = 0) = 0; - // Create the correct implementation object for the Timer - // result. POSIX_SIG_Proactor will create a Timer object with a - // meaningful signal number, if you leave the signal number as 0. + /** + * Post <how_many> completions to the completion port so that all + * threads can wake up. This is used in conjunction with the + * <run_event_loop>. + */ virtual int post_wakeup_completions (int how_many) = 0; - // Post <how_many> completions to the completion port so that all - // threads can wake up. This is used in conjunction with the - // <run_event_loop>. }; #endif /* (ACE_WIN32 && ACE_HAS_WINCE) || ACE_HAS_AIO_CALLS */ diff --git a/ace/Process.h b/ace/Process.h index 5e848ec5441..0d877d2fdee 100644 --- a/ace/Process.h +++ b/ace/Process.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Process.h -// -// = AUTHOR -// Tim Harrison <harrison@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Process.h + * + * $Id$ + * + * @author Tim Harrison <harrison@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_PROCESS_H #define ACE_PROCESS_H @@ -24,26 +21,27 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Process_Options + * + * @brief Process Options + * + * This class controls the options passed to <CreateProcess> (or <fork> + * and <exec>). + * Notice that on Windows CE, creating a process merely means + * instantiating a new process. You can't set the handles (since + * there's no stdin, stdout and stderr,) specify process/thread + * options, set environment,... So, basically, this class only + * set the command line and nothing else. + * Notice that on UNIX platforms, if the <setenv> is used, the + * <spawn> is using the <execve> system call. It means that the + * <command_line> should include a full path to the program file + * (<execve> does not search the PATH). If <setenv> is not used + * then, the <spawn> is using the <execvp> which searches for the + * program file in the PATH variable. + */ class ACE_Export ACE_Process_Options { - // = TITLE - // Process Options - // - // = DESCRIPTION - // This class controls the options passed to <CreateProcess> (or <fork> - // and <exec>). - // Notice that on Windows CE, creating a process merely means - // instantiating a new process. You can't set the handles (since - // there's no stdin, stdout and stderr,) specify process/thread - // options, set environment,... So, basically, this class only - // set the command line and nothing else. - // - // Notice that on UNIX platforms, if the <setenv> is used, the - // <spawn> is using the <execve> system call. It means that the - // <command_line> should include a full path to the program file - // (<execve> does not search the PATH). If <setenv> is not used - // then, the <spawn> is using the <execvp> which searches for the - // program file in the PATH variable. public: enum { @@ -59,7 +57,7 @@ public: protected: // = Default settings not part of public Interface. // - // @@ These sizes should be taken from the appropriate + // @@todo These sizes should be taken from the appropriate // POSIX/system header files and/or defined dynamically. enum { @@ -69,146 +67,160 @@ protected: }; public: + /** + * If <inherit_environment> == 1, the new process will inherit the + * environment of the current process. <command_line_buf_len> is the + * max strlen for command-line arguments. + */ ACE_Process_Options (int inherit_environment = 1, int command_line_buf_len = DEFAULT_COMMAND_LINE_BUF_LEN, int env_buf_len = ENVIRONMENT_BUFFER, int max_env_args = MAX_ENVIRONMENT_ARGS); - // If <inherit_environment> == 1, the new process will inherit the - // environment of the current process. <command_line_buf_len> is the - // max strlen for command-line arguments. + /// Destructor. ~ACE_Process_Options (void); - // Destructor. // = Methods to set process creation options portably. + /** + * Set the standard handles of the new process to the respective + * handles. If you want to affect a subset of the handles, make + * sure to set the others to ACE_INVALID_HANDLE. Returns 0 on + * success, -1 on failure. + */ int set_handles (ACE_HANDLE std_in, ACE_HANDLE std_out = ACE_INVALID_HANDLE, ACE_HANDLE std_err = ACE_INVALID_HANDLE); - // Set the standard handles of the new process to the respective - // handles. If you want to affect a subset of the handles, make - // sure to set the others to ACE_INVALID_HANDLE. Returns 0 on - // success, -1 on failure. + /// <format> must be of the form "VARIABLE=VALUE". There can not be + /// any spaces between VARIABLE and the equal sign. int setenv (const ACE_TCHAR *format, ...); - // <format> must be of the form "VARIABLE=VALUE". There can not be - // any spaces between VARIABLE and the equal sign. + /** + * Set a single environment variable, <variable_name>. Since + * different platforms separate each environment variable + * differently, you must call this method once for each variable. + * <format> can be any printf format string. So options->setenv + * ("FOO","one + two = %s", "three") will result in "FOO=one + two = + * three". + */ int setenv (const ACE_TCHAR *variable_name, const ACE_TCHAR *format, ...); - // Set a single environment variable, <variable_name>. Since - // different platforms separate each environment variable - // differently, you must call this method once for each variable. - // <format> can be any printf format string. So options->setenv - // ("FOO","one + two = %s", "three") will result in "FOO=one + two = - // three". + /// Same as above with argv format. <envp> must be null terminated. int setenv (ACE_TCHAR *envp[]); - // Same as above with argv format. <envp> must be null terminated. + /// Set the working directory for the process. strlen of <wd> must + /// be <= MAXPATHLEN. void working_directory (const ACE_TCHAR *wd); - // Set the working directory for the process. strlen of <wd> must - // be <= MAXPATHLEN. + /** + * Set the command-line arguments. <format> can use any printf + * formats. The first token in <format> should be the path to the + * application. This can either be a full path, relative path, or + * just an executable name. If an executable name is used, we rely + * on the platform's support for searching paths. Since we need a + * path to run a process, this method *must* be called! Returns 0 + * on success, -1 on failure. + */ int command_line (const ACE_TCHAR *format, ...); - // Set the command-line arguments. <format> can use any printf - // formats. The first token in <format> should be the path to the - // application. This can either be a full path, relative path, or - // just an executable name. If an executable name is used, we rely - // on the platform's support for searching paths. Since we need a - // path to run a process, this method *must* be called! Returns 0 - // on success, -1 on failure. + /// Same as above in argv format. <argv> must be null terminated. int command_line (const ACE_TCHAR * const argv[]); - // Same as above in argv format. <argv> must be null terminated. // = Set/get the pathname used to name the process. + /** + * Specify the full path or relative path, or just the executable + * name for the process. If this is set, then <name> will be used to + * create the process instead of argv[0] set in the command + * line. This is here so that you can supply something other than + * executable name as argv[0]. + */ void process_name (const ACE_TCHAR *name); - // Specify the full path or relative path, or just the executable - // name for the process. If this is set, then <name> will be used to - // create the process instead of argv[0] set in the command - // line. This is here so that you can supply something other than - // executable name as argv[0]. + /// Return the process_name. If the <process_name(name)> set + /// method is not called, this method will return argv[0]. const ACE_TCHAR *process_name (void); - // Return the process_name. If the <process_name(name)> set - // method is not called, this method will return argv[0]. // = Set/get creation flags. + /// Get the creation flags. + /// Set the creation flags. u_long creation_flags (void) const; - // Get the creation flags. void creation_flags (u_long); - // Set the creation flags. // = <ACE_Process> uses these operations to retrieve option values. + /// Current working directory. Returns "" if nothing has been set. ACE_TCHAR *working_directory (void); - // Current working directory. Returns "" if nothing has been set. + /// Buffer of command-line options. Returns exactly what was passed + /// to this->command_line. ACE_TCHAR *command_line_buf (void); - // Buffer of command-line options. Returns exactly what was passed - // to this->command_line. + /** + * argv-style command-line options. Parses and modifies the string + * created from <command_line_>. All spaces not in quotes ("" or + * '') are replaced with null (\0) bytes. An argv array is built + * and returned with each entry pointing to the start of + * null-terminated string. Returns { 0 } if nothing has been set. + */ ACE_TCHAR * const *command_line_argv (void); - // argv-style command-line options. Parses and modifies the string - // created from <command_line_>. All spaces not in quotes ("" or - // '') are replaced with null (\0) bytes. An argv array is built - // and returned with each entry pointing to the start of - // null-terminated string. Returns { 0 } if nothing has been set. + /** + * Null-terminated buffer of null terminated strings. Each string + * is an environment assignment "VARIABLE=value". This buffer + * should end with two null characters. + */ ACE_TCHAR *env_buf (void); - // Null-terminated buffer of null terminated strings. Each string - // is an environment assignment "VARIABLE=value". This buffer - // should end with two null characters. // = Get/set process group. + /// On UNIX, these methods are used by the <ACE_Process_Manager> to + /// manage groups of processes. pid_t getgroup (void) const; pid_t setgroup (pid_t pgrp); - // On UNIX, these methods are used by the <ACE_Process_Manager> to - // manage groups of processes. #if defined (ACE_WIN32) // = Non-portable accessors for when you "just have to use them." + /// Used for setting and getting. ACE_TEXT_STARTUPINFO *startup_info (void); - // Used for setting and getting. + /// Get the process_attributes. Returns NULL if + /// set_process_attributes has not been set. LPSECURITY_ATTRIBUTES get_process_attributes (void) const; - // Get the process_attributes. Returns NULL if - // set_process_attributes has not been set. + /// If this is called, a non-null process attributes is sent to + /// CreateProcess. LPSECURITY_ATTRIBUTES set_process_attributes (void); - // If this is called, a non-null process attributes is sent to - // CreateProcess. + /// Get the thread_attributes. Returns NULL if set_thread_attributes + /// has not been set. LPSECURITY_ATTRIBUTES get_thread_attributes (void) const; - // Get the thread_attributes. Returns NULL if set_thread_attributes - // has not been set. + /// If this is called, a non-null thread attributes is sent to + /// CreateProcess. LPSECURITY_ATTRIBUTES set_thread_attributes (void); - // If this is called, a non-null thread attributes is sent to - // CreateProcess. + /// Default is TRUE. + /// Allows disabling of handle inheritence. int handle_inheritence (void); - // Default is TRUE. void handle_inheritence (int); - // Allows disabling of handle inheritence. #else /* All things not WIN32 */ + /// argv-style array of environment settings. ACE_TCHAR *const *env_argv (void); - // argv-style array of environment settings. // = Accessors for the standard handles. ACE_HANDLE get_stdin (void); ACE_HANDLE get_stdout (void); ACE_HANDLE get_stderr (void); + /// Set value for avoid_zombies. + /// Get current value for avoid_zombies. void avoid_zombies (int); - // Set value for avoid_zombies. int avoid_zombies (void); - // Get current value for avoid_zombies. // = Set/get real & effective user & group id associated with user. int setreugid (const ACE_TCHAR* user); @@ -224,49 +236,49 @@ public: protected: #if !defined (ACE_HAS_WINCE) + /// Add <assignment> to environment_buf_ and adjust + /// environment_argv_. <len> is the strlen of <assignment>. int setenv_i (ACE_TCHAR *assignment, int len); - // Add <assignment> to environment_buf_ and adjust - // environment_argv_. <len> is the strlen of <assignment>. + /// Whether the child process inherits the current process + /// environment. int inherit_environment_; - // Whether the child process inherits the current process - // environment. #endif /* !ACE_HAS_WINCE */ + /// Default 0. u_long creation_flags_; - // Default 0. #if defined (ACE_WIN32) && !defined (ACE_HAS_WINCE) + /// Helper function to grab win32 environment and stick it in + /// environment_buf_ using this->setenv_i. void inherit_environment (void); - // Helper function to grab win32 environment and stick it in - // environment_buf_ using this->setenv_i. + /// Ensures once only call to inherit environment. int environment_inherited_; - // Ensures once only call to inherit environment. ACE_TEXT_STARTUPINFO startup_info_; + /// Default TRUE. BOOL handle_inheritence_; - // Default TRUE. + /// Pointer to security_buf1_. LPSECURITY_ATTRIBUTES process_attributes_; - // Pointer to security_buf1_. + /// Pointer to security_buf2_. LPSECURITY_ATTRIBUTES thread_attributes_; - // Pointer to security_buf2_. + /// Data for process_attributes_. SECURITY_ATTRIBUTES security_buf1_; - // Data for process_attributes_. + /// Data for thread_attributes_. SECURITY_ATTRIBUTES security_buf2_; - // Data for thread_attributes_. #else /* !ACE_WIN32 */ + /// Avoid zombies for spawned processes. ACE_HANDLE stdin_; ACE_HANDLE stdout_; ACE_HANDLE stderr_; int avoid_zombies_; - // Avoid zombies for spawned processes. // = Real & effective user & group id's. // These should be set to -1 to leave unchanged (default). @@ -277,144 +289,157 @@ protected: #endif /* ACE_WIN32 */ #if !defined (ACE_HAS_WINCE) + /// Is 1 if stdhandles was called. int set_handles_called_; - // Is 1 if stdhandles was called. + /// Pointer into environment_buf_. This should point to the next + /// free spot. int environment_buf_index_; - // Pointer into environment_buf_. This should point to the next - // free spot. + /// Pointer to environment_argv_. int environment_argv_index_; - // Pointer to environment_argv_. + /// Pointer to buffer of the environment settings. ACE_TCHAR *environment_buf_; - // Pointer to buffer of the environment settings. + /// Size of the environment buffer. Configurable int environment_buf_len_; - // Size of the environment buffer. Configurable + /// Pointers into environment_buf_. ACE_TCHAR **environment_argv_; - // Pointers into environment_buf_. + /// Maximum number of environment variables. Configurable int max_environment_args_; - // Maximum number of environment variables. Configurable + /// Maximum index of environment_argv_ buffer int max_environ_argv_index_; - // Maximum index of environment_argv_ buffer + /// The current working directory. ACE_TCHAR working_directory_[MAXPATHLEN + 1]; - // The current working directory. #endif /* !ACE_HAS_WINCE */ + /// Ensures command_line_argv is only calculated once. int command_line_argv_calculated_; - // Ensures command_line_argv is only calculated once. + /// Pointer to buffer of command-line arguments. E.g., "-f foo -b bar". ACE_TCHAR *command_line_buf_; - // Pointer to buffer of command-line arguments. E.g., "-f foo -b bar". + /// Argv-style command-line arguments. ACE_TCHAR *command_line_argv_[MAX_COMMAND_LINE_OPTIONS]; - // Argv-style command-line arguments. + /// Process-group on Unix; unused on Win32. pid_t process_group_; - // Process-group on Unix; unused on Win32. + /// Pathname for the process. Relative path or absolute path or just + /// the program name. ACE_TCHAR process_name_[MAXPATHLEN + 1]; - // Pathname for the process. Relative path or absolute path or just - // the program name. }; +/** + * @class ACE_Process + * + * @brief Process + * + * A Portable encapsulation for creating new processes. + * Notice that on UNIX platforms, if the <setenv> is used, the + * <spawn> is using the <execve> system call. It means that the + * <command_line> should include a full path to the program file + * (<execve> does not search the PATH). If <setenv> is not used + * then, the <spawn> is using the <execvp> which searches for the + * program file in the PATH variable. + */ class ACE_Export ACE_Process { - // = TITLE - // Process - // - // = DESCRIPTION - // A Portable encapsulation for creating new processes. - // - // Notice that on UNIX platforms, if the <setenv> is used, the - // <spawn> is using the <execve> system call. It means that the - // <command_line> should include a full path to the program file - // (<execve> does not search the PATH). If <setenv> is not used - // then, the <spawn> is using the <execvp> which searches for the - // program file in the PATH variable. public: + /// Default construction. Must use <ACE_Process::spawn> to start. ACE_Process (void); - // Default construction. Must use <ACE_Process::spawn> to start. + /// Destructor. virtual ~ACE_Process (void); - // Destructor. + /** + * Called just before <ACE_OS::fork> in the <spawn>. If this + * returns non-zero, the <spawn> is aborted (and returns + * ACE_INVALID_PID). The default simply returns zero. + */ virtual int prepare (ACE_Process_Options &options); - // Called just before <ACE_OS::fork> in the <spawn>. If this - // returns non-zero, the <spawn> is aborted (and returns - // ACE_INVALID_PID). The default simply returns zero. + /** + * Launch a new process as described by <options>. Returns the + * process id of the newly spawned child on success or -1 on + * failure. + */ virtual pid_t spawn (ACE_Process_Options &options); - // Launch a new process as described by <options>. Returns the - // process id of the newly spawned child on success or -1 on - // failure. + /// Called just after <ACE_OS::fork> in the parent's context, if the + /// <fork> succeeds. The default is to do nothing. virtual void parent (pid_t child); - // Called just after <ACE_OS::fork> in the parent's context, if the - // <fork> succeeds. The default is to do nothing. + /** + * Called just after <ACE_OS::fork> in the child's context. The + * default does nothing. This function is *not* called on Win32 + * because the process-creation scheme does not allow it. + */ virtual void child (pid_t parent); - // Called just after <ACE_OS::fork> in the child's context. The - // default does nothing. This function is *not* called on Win32 - // because the process-creation scheme does not allow it. + /// Called by a <Process_Manager> that is removing this Process from + /// its table of managed Processes. Default is to do nothing. virtual void unmanage (void); - // Called by a <Process_Manager> that is removing this Process from - // its table of managed Processes. Default is to do nothing. - + + /** + * Wait for the process we've created to exit. If <status> != 0, it + * points to an integer where the function store the exit status of + * child process to. If <wait_options> == <WNOHANG> then return 0 + * and don't block if the child process hasn't exited yet. A return + * value of -1 represents the <wait> operation failed, otherwise, + * the child process id is returned. + */ pid_t wait (ACE_exitcode *status = 0, int wait_options = 0); - // Wait for the process we've created to exit. If <status> != 0, it - // points to an integer where the function store the exit status of - // child process to. If <wait_options> == <WNOHANG> then return 0 - // and don't block if the child process hasn't exited yet. A return - // value of -1 represents the <wait> operation failed, otherwise, - // the child process id is returned. + /** + * Timed wait for the process we've created to exit. A return value + * of -1 indicates that the something failed; 0 indicates that a + * timeout occurred. Otherwise, the child's process id is returned. + * If <status> != 0, it points to an integer where the function + * stores the child's exit status. + * + * NOTE: on UNIX platforms this function uses <ualarm>, i.e., it + * overwrites any existing alarm. In addition, it steals all + * <SIGCHLD>s during the timeout period, which will break another + * <ACE_Process_Manager> in the same process that's expecting + * <SIGCHLD> to kick off process reaping. + */ pid_t wait (const ACE_Time_Value &tv, ACE_exitcode *status = 0); - // Timed wait for the process we've created to exit. A return value - // of -1 indicates that the something failed; 0 indicates that a - // timeout occurred. Otherwise, the child's process id is returned. - // If <status> != 0, it points to an integer where the function - // stores the child's exit status. - // - // NOTE: on UNIX platforms this function uses <ualarm>, i.e., it - // overwrites any existing alarm. In addition, it steals all - // <SIGCHLD>s during the timeout period, which will break another - // <ACE_Process_Manager> in the same process that's expecting - // <SIGCHLD> to kick off process reaping. + /// Send the process a signal. This is only portable to operating + /// systems that support signals, such as UNIX/POSIX. int kill (int signum = SIGINT); - // Send the process a signal. This is only portable to operating - // systems that support signals, such as UNIX/POSIX. + /** + * Terminate the process abruptly using <ACE::terminate_process>. + * This call doesn't give the process a chance to cleanup, so use it + * with caution... + */ int terminate (void); - // Terminate the process abruptly using <ACE::terminate_process>. - // This call doesn't give the process a chance to cleanup, so use it - // with caution... + /// Return the process id of the new child process. pid_t getpid (void) const; - // Return the process id of the new child process. + /// Return the handle of the process, if it has one. ACE_HANDLE gethandle (void) const; - // Return the handle of the process, if it has one. + /// Return 1 if running; 0 otherwise. int running (void) const; - // Return 1 if running; 0 otherwise. + /// Return the Process' exit code int exit_code (void) const; - // Return the Process' exit code + /// Set the Process' exit code (completely unrelated to whether the + /// Process has actually exited)! void exit_code (int code); - // Set the Process' exit code (completely unrelated to whether the - // Process has actually exited)! #if defined (ACE_WIN32) PROCESS_INFORMATION process_info (void); @@ -424,8 +449,8 @@ protected: #if defined (ACE_WIN32) PROCESS_INFORMATION process_info_; #else /* ACE_WIN32 */ + /// Process id of the child. pid_t child_id_; - // Process id of the child. #endif /* ACE_WIN32 */ int exit_code_; }; diff --git a/ace/Process_Manager.h b/ace/Process_Manager.h index c5257f00911..f1c3d56ba72 100644 --- a/ace/Process_Manager.h +++ b/ace/Process_Manager.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Process_Manager.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Process_Manager.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_PROCESS_MANAGER_H #define ACE_PROCESS_MANAGER_H @@ -28,107 +25,100 @@ #include "ace/Process.h" +/** + * @class ACE_Process_Descriptor + * + * @brief Information describing each process that's controlled by an + * <ACE_Process_Manager>. + */ class ACE_Export ACE_Process_Descriptor { - // = TITLE - // Information describing each process that's controlled by an - // <ACE_Process_Manager>. private: friend class ACE_Process_Manager; + /// Default ctor/dtor. ACE_Process_Descriptor (void); ~ACE_Process_Descriptor (void); - // Default ctor/dtor. + /// Describes the process itself. ACE_Process *process_; - // Describes the process itself. + /// function to call when process exits ACE_Event_Handler *exit_notify_; - // function to call when process exits + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. }; +/** + * @class ACE_Process_Manager + * + * @brief Manages a group of processes. + * + * This class allows applications to control groups of processes, + * similar to how the <ACE_Thread_Manager> controls groups of + * threads. Naturally, it doesn't work at all on platforms, such + * as VxWorks or pSoS, that don't support process. + * There are two (main) ways of using <ACE_Process_Manager>, + * depending on how involved you wish to be with the termination + * of managed <ACE_Process>es. If you just want <Process>es to + * go away when they're finished, simply register the + * <Process_Manager> with an <ACE_Reactor>: + * ACE_Process_Manager mgr( 100, some_reactor ) + * -or- + * ACE_Process_Manager mgr; + * ... + * mgr.open( 100, some_reactor ); + * Then, the <Process_Manager> will clean up after any + * <Process>es that it spawns. (On Unix, this means executing a + * wait(2) to collect the exit status -- and avoid zombie + * processes; on Win32, it means closing the process and thread + * HANDLEs that are created when CreateProcess is called.) + * If, on the other hand (and for some inexplicable reason) you + * want to explicitly invoke the terminated <Process> cleanup + * code, then *don't* register the <Process_Manager> with a + * Reactor, and be sure to call one of the + * <Process_Manager::wait> functions whenever there might be + * managed <Process>es that have exited. + * Note that in either case, <Process_Manager> allows you to + * register "<Event_Handlers>" to be called when a specific + * <Process> exits, or when any <Process> without a specific + * <Event_Handler> exits. When a <Process> exits, the + * appropriate <Event_Handler>'s <handle_input> is called; the + * <ACE_HANDLE> passed is either the Process' HANDLE (on Win32), + * or its pid cast to an <ACE_HANDLE> (on unix). + * It is also possible to call the <Process_Manager::wait> + * functions even though the <Process_Manager> is registered with + * a <Reactor>. I don't know what happens in this case, but it's + * probably not *too* bad. + * Note also that the wait functions are "sloppy" on Unix, + * because there's no good way to wait for a subset of the + * children of a process. The wait functions may end up + * collecting the exit status of a process that's not managed by + * the <Process_Manager> whose <wait> you invoked. It's best to + * only use a single <Process_Manager>, and to create all + * subprocesses by calling that <Process_Manager>'s <spawn> + * method. (I have some ideas for workarounds to improve this + * situation, but I consider it fairly low priority because I + * think the "single <Process_Manager>" pattern will be + * sufficient in most cases.) + * Incidentally, when you register your <Process_Manager> with a + * <Reactor> its notification pipe is used to help "reap" the + * available exit statuses. Therefore, you must not use a + * <Reactor> whose notify pipe has been disabled. Here's the + * sequence of steps used to reap the exit statuses in this case: + * + The <Process_Manager> registers a signal handler for + * SIGCHLD. + * + The SIGCHLD handler, when invoked, uses the <Reactor>'s + * <notify> method to inform the <Reactor> to wake up. + * + Next, the <Reactor> calls the <Process_Manager>'s + * <handle_input>, this happens synchronously, not in + * sighandler-space. + * + The <handle_input> method collects all available exit + * statuses. + */ class ACE_Export ACE_Process_Manager : protected ACE_Event_Handler { - // = TITLE - // Manages a group of processes. - // - // = DESCRIPTION - // This class allows applications to control groups of processes, - // similar to how the <ACE_Thread_Manager> controls groups of - // threads. Naturally, it doesn't work at all on platforms, such - // as VxWorks or pSoS, that don't support process. - // - // There are two (main) ways of using <ACE_Process_Manager>, - // depending on how involved you wish to be with the termination - // of managed <ACE_Process>es. If you just want <Process>es to - // go away when they're finished, simply register the - // <Process_Manager> with an <ACE_Reactor>: - // - // ACE_Process_Manager mgr( 100, some_reactor ) - // -or- - // ACE_Process_Manager mgr; - // ... - // mgr.open( 100, some_reactor ); - // - // Then, the <Process_Manager> will clean up after any - // <Process>es that it spawns. (On Unix, this means executing a - // wait(2) to collect the exit status -- and avoid zombie - // processes; on Win32, it means closing the process and thread - // HANDLEs that are created when CreateProcess is called.) - // - // If, on the other hand (and for some inexplicable reason) you - // want to explicitly invoke the terminated <Process> cleanup - // code, then *don't* register the <Process_Manager> with a - // Reactor, and be sure to call one of the - // <Process_Manager::wait> functions whenever there might be - // managed <Process>es that have exited. - // - // Note that in either case, <Process_Manager> allows you to - // register "<Event_Handlers>" to be called when a specific - // <Process> exits, or when any <Process> without a specific - // <Event_Handler> exits. When a <Process> exits, the - // appropriate <Event_Handler>'s <handle_input> is called; the - // <ACE_HANDLE> passed is either the Process' HANDLE (on Win32), - // or its pid cast to an <ACE_HANDLE> (on unix). - // - // It is also possible to call the <Process_Manager::wait> - // functions even though the <Process_Manager> is registered with - // a <Reactor>. I don't know what happens in this case, but it's - // probably not *too* bad. - // - // Note also that the wait functions are "sloppy" on Unix, - // because there's no good way to wait for a subset of the - // children of a process. The wait functions may end up - // collecting the exit status of a process that's not managed by - // the <Process_Manager> whose <wait> you invoked. It's best to - // only use a single <Process_Manager>, and to create all - // subprocesses by calling that <Process_Manager>'s <spawn> - // method. (I have some ideas for workarounds to improve this - // situation, but I consider it fairly low priority because I - // think the "single <Process_Manager>" pattern will be - // sufficient in most cases.) - // - // Incidentally, when you register your <Process_Manager> with a - // <Reactor> its notification pipe is used to help "reap" the - // available exit statuses. Therefore, you must not use a - // <Reactor> whose notify pipe has been disabled. Here's the - // sequence of steps used to reap the exit statuses in this case: - // - // * The <Process_Manager> registers a signal handler for - // SIGCHLD. - // - // * The SIGCHLD handler, when invoked, uses the <Reactor>'s - // <notify> method to inform the <Reactor> to wake up. - // - // * Next, the <Reactor> calls the <Process_Manager>'s - // <handle_input>, this happens synchronously, not in - // sighandler-space. - // - // * The <handle_input> method collects all available exit - // statuses. public: friend class ACE_Process_Control; @@ -138,144 +128,168 @@ public: }; // = Initialization and termination methods. + /** + * Initialize an <ACE_Process_Manager> with a table containing up to + * <size> processes. This table resizes itself automatically as + * needed. If a non-NULL <reactor> is provided, this + * <ACE_Process_Manager> uses it to notify an application when a + * process it controls exits. By default, however, we don't use an + * <ACE_Reactor>. + */ ACE_Process_Manager (size_t size = ACE_Process_Manager::DEFAULT_SIZE, ACE_Reactor *reactor = 0); - // Initialize an <ACE_Process_Manager> with a table containing up to - // <size> processes. This table resizes itself automatically as - // needed. If a non-NULL <reactor> is provided, this - // <ACE_Process_Manager> uses it to notify an application when a - // process it controls exits. By default, however, we don't use an - // <ACE_Reactor>. + /** + * Initialize an <ACE_Process_Manager> with a table containing up to + * <size> processes. This table resizes itself automatically as + * needed. If a non-NULL <reactor> is provided, this + * <ACE_Process_Manager> uses it to notify an application when a + * process it controls exits. By default, however, we don't use an + * <ACE_Reactor>. + */ int open (size_t size = DEFAULT_SIZE, ACE_Reactor *r = 0); - // Initialize an <ACE_Process_Manager> with a table containing up to - // <size> processes. This table resizes itself automatically as - // needed. If a non-NULL <reactor> is provided, this - // <ACE_Process_Manager> uses it to notify an application when a - // process it controls exits. By default, however, we don't use an - // <ACE_Reactor>. + /// Release all resources. Do not wait for processes to exit. int close (void); - // Release all resources. Do not wait for processes to exit. + /// Destructor releases all resources and does not wait for processes + /// to exit. virtual ~ACE_Process_Manager (void); - // Destructor releases all resources and does not wait for processes - // to exit. // = Singleton accessors. + /// Get pointer to a process-wide <ACE_Process_Manager>. static ACE_Process_Manager *instance (void); - // Get pointer to a process-wide <ACE_Process_Manager>. + /// Set pointer to a process-wide <ACE_Process_Manager> and return + /// existing pointer. static ACE_Process_Manager *instance (ACE_Process_Manager *); - // Set pointer to a process-wide <ACE_Process_Manager> and return - // existing pointer. + /// Delete the dynamically allocated singleton. static void close_singleton (void); - // Delete the dynamically allocated singleton. + /// Cleanup method, used by the <ACE_Object_Manager> to destroy the + /// singleton. static void cleanup (void *instance, void *arg); - // Cleanup method, used by the <ACE_Object_Manager> to destroy the - // singleton. // = Process creation methods. + /** + * Create a new process by passing <options> to <proc.spawn>. On + * success, returns the process id of the child that was created. + * On failure, returns ACE_INVALID_PID. + */ pid_t spawn (ACE_Process *proc, ACE_Process_Options &options); - // Create a new process by passing <options> to <proc.spawn>. On - // success, returns the process id of the child that was created. - // On failure, returns ACE_INVALID_PID. + /** + * Create a new process by passing <options> to + * <ACE_Process::spawn>. On success, returns the process id of the + * child that was created. On failure, returns ACE_INVALID_PID. + */ pid_t spawn (ACE_Process_Options &options); - // Create a new process by passing <options> to - // <ACE_Process::spawn>. On success, returns the process id of the - // child that was created. On failure, returns ACE_INVALID_PID. + /** + * Create <n> new processes by passing <options> to + * <ACE_Process::spawn>, which is called <n> times. If <child_pids> + * is non-0 it is expected to be an array of <n> <pid_t>'s, which + * are filled in with the process ids of each newly created process. + * Returns 0 on success and -1 on failure. + */ int spawn_n (size_t n, ACE_Process_Options &options, pid_t *child_pids = 0); - // Create <n> new processes by passing <options> to - // <ACE_Process::spawn>, which is called <n> times. If <child_pids> - // is non-0 it is expected to be an array of <n> <pid_t>'s, which - // are filled in with the process ids of each newly created process. - // Returns 0 on success and -1 on failure. // = Process synchronization operations. + /** + * Block until there are no more child processes running that were + * <spawn>ed by this <ACE_Process_Manager>. Unlike the <wait> call + * below, this method does not require a signal handler or + * <ACE_OS::sigwait> because it simply blocks synchronously waiting + * for all the children managed by this <ACE_Process_Manager> to + * exit. Note that this does not return any status information + * about the success or failure of exiting child processes, although + * any registered exit_handlers are called. Returns 0 on success + * (and <remove>s the corresponding <ACE_Process_Descriptor> entries + * from the <Process_Manager>; otherwise, returns -1 on failure. + */ int wait (const ACE_Time_Value &timeout = ACE_Time_Value::max_time); - // Block until there are no more child processes running that were - // <spawn>ed by this <ACE_Process_Manager>. Unlike the <wait> call - // below, this method does not require a signal handler or - // <ACE_OS::sigwait> because it simply blocks synchronously waiting - // for all the children managed by this <ACE_Process_Manager> to - // exit. Note that this does not return any status information - // about the success or failure of exiting child processes, although - // any registered exit_handlers are called. Returns 0 on success - // (and <remove>s the corresponding <ACE_Process_Descriptor> entries - // from the <Process_Manager>; otherwise, returns -1 on failure. + /** + * Wait up to <timeout> for a single process to terminate. If + * pid==0, waits for any of the managed <Process>es (but see the + * note in the class documentation above for caveats about this -- + * "sloppy process cleanup on unix") If pid != 0, waits for that <Process> + * only. Returns the pid of the Process whose exit was handled, 0 + * if a timeout occurred, or ACE_INVALID_PID on error. + */ pid_t wait (pid_t pid, const ACE_Time_Value &timeout, ACE_exitcode *status = 0); - // Wait up to <timeout> for a single process to terminate. If - // pid==0, waits for any of the managed <Process>es (but see the - // note in DESCRIPTION above for caveats about this -- "sloppy - // Process cleanup on unix") If pid != 0, waits for that <Process> - // only. Returns the pid of the Process whose exit was handled, 0 - // if a timeout occurred, or ACE_INVALID_PID on error. + /** + * Wait indefinitely for a single process to terminate. If pid==0, + * waits for any of the managed <Process>es (but see the note in + * the class documentation for caveats about this -- "sloppy Process + * cleanup on unix") If pid != 0, waits for that <Process> only. + * Returns the pid of the process whose exit was handled, or + * ACE_INVALID_PID on error. + */ pid_t wait (pid_t pid, ACE_exitcode *status = 0); - // Wait indefinitely for a single process to terminate. If pid==0, - // waits for any of the managed <Process>es (but see the note in - // DESCRIPTION above for caveats about this -- "sloppy Process - // cleanup on unix") If pid != 0, waits for that <Process> only. - // Returns the pid of the process whose exit was handled, or - // ACE_INVALID_PID on error. + /** + * Reap the result of a single process by calling <ACE_OS::waitpid>, + * therefore, this method is not portable to Win32. If the child is + * successfully reaped, <remove> is called automatically. This + * method does the same thing that the <wait> method directly above + * it does -- It's just here for backwards compatibility. + */ int reap (pid_t pid = -1, ACE_exitcode *stat_loc = 0, int options = WNOHANG); - // Reap the result of a single process by calling <ACE_OS::waitpid>, - // therefore, this method is not portable to Win32. If the child is - // successfully reaped, <remove> is called automatically. This - // method does the same thing that the <wait> method directly above - // it does -- It's just here for backwards compatibility. // = Utility methods. + /** + * Register an Event_Handler to be called back when the specified + * process exits. If pid == ACE_INVALID_PID this handler is called + * when any process with no specific handler exits. + */ int register_handler (ACE_Event_Handler *event_handler, pid_t pid = ACE_INVALID_PID); - // Register an Event_Handler to be called back when the specified - // process exits. If pid == ACE_INVALID_PID this handler is called - // when any process with no specific handler exits. + /** + * Remove process <pid> from the table. This is called + * automatically by the <reap> method after it successfully reaped a + * <SIGCHLD> signal. It's also possible to call this method + * directly from a signal handler, but don't call both <reap> and + * <remove>! + */ int remove (pid_t pid); - // Remove process <pid> from the table. This is called - // automatically by the <reap> method after it successfully reaped a - // <SIGCHLD> signal. It's also possible to call this method - // directly from a signal handler, but don't call both <reap> and - // <remove>! + /** + * Abruptly terminate a single process with id <pid> using the + * <ACE::terminate_process> method. Note that this call is + * potentially dangerous to use since the process being terminated + * may not have a chance to cleanup before it shuts down. Returns 0 + * on success and -1 on failure. + */ int terminate (pid_t pid); - // Abruptly terminate a single process with id <pid> using the - // <ACE::terminate_process> method. Note that this call is - // potentially dangerous to use since the process being terminated - // may not have a chance to cleanup before it shuts down. Returns 0 - // on success and -1 on failure. + /// On OSs that support signals, send the signal to the specified + /// process. Returns 0 on success and -1 on failure. int terminate (pid_t pid, int sig); - // On OSs that support signals, send the signal to the specified - // process. Returns 0 on success and -1 on failure. + /// Return the number of managed Processes. size_t managed (void) const; - // Return the number of managed Processes. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = These methods allow a <Process_Manager> to be an <Event_Handler>. @@ -302,77 +316,81 @@ protected: // signal handler, and no dummy handle. #if !defined(ACE_WIN32) + /// Collect one (or more, on unix) process exit status. virtual int handle_input (ACE_HANDLE proc); - // Collect one (or more, on unix) process exit status. #endif // !defined(ACE_WIN32) + /** + * On Unix, this routine is called asynchronously when a SIGCHLD is + * received. We just tweak the reactor so that it'll call back our + * <handle_input> function, which allows us to handle Process exits + * synchronously. + * + * On Win32, this routine is called synchronously, and is passed the + * HANDLE of the Process that exited, so we can do all our work here + */ virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0); - // On Unix, this routine is called asynchronously when a SIGCHLD is - // received. We just tweak the reactor so that it'll call back our - // <handle_input> function, which allows us to handle Process exits - // synchronously. - // - // On Win32, this routine is called synchronously, and is passed the - // HANDLE of the Process that exited, so we can do all our work here private: + /// Resize the pool of Process_Descriptors. int resize (size_t); - // Resize the pool of Process_Descriptors. + /// Locate the index of the table slot occupied by <process_id>. + /// Returns -1 if <process_id> is not in the <process_table_> ssize_t find_proc (pid_t process_id); - // Locate the index of the table slot occupied by <process_id>. - // Returns -1 if <process_id> is not in the <process_table_> #if defined (ACE_WIN32) + /// Locate the index of the table slot occupied by <process_handle>. + /// Returns ~0 if <process_handle> is not in the <process_table_> ssize_t find_proc (ACE_HANDLE process_handle); - // Locate the index of the table slot occupied by <process_handle>. - // Returns ~0 if <process_handle> is not in the <process_table_> #endif /* ACE_WIN32 */ + /// Insert a process in the table (checks for duplicates). Omitting + /// the process handle won't work on Win32... int insert_proc (ACE_Process *process); - // Insert a process in the table (checks for duplicates). Omitting - // the process handle won't work on Win32... + /** + * Append information about a process, i.e., its <process_id> in the + * <process_table_>. Each entry is added at the end, growing the + * table if necessary. + */ int append_proc (ACE_Process *process); - // Append information about a process, i.e., its <process_id> in the - // <process_table_>. Each entry is added at the end, growing the - // table if necessary. + /// Actually removes the process at index <n> from the table. This method + /// must be called with locks held. int remove_proc (size_t n); - // Actually removes the process at index <n> from the table. This method - // must be called with locks held. + /// If there's a specific handler for the Process at index <n> in the + /// table, or there's a default handler, call it. int notify_proc_handler (size_t n, ACE_exitcode status); - // If there's a specific handler for the Process at index <n> in the - // table, or there's a default handler, call it. + /// Vector that describes process state within the Process_Manager. ACE_Process_Descriptor *process_table_; - // Vector that describes process state within the Process_Manager. + /// Maximum number of processes we can manage (should be dynamically + /// allocated). size_t max_process_table_size_; - // Maximum number of processes we can manage (should be dynamically - // allocated). + /// Current number of processes we are managing. size_t current_count_; - // Current number of processes we are managing. + /// This event handler is used to notify when a process we control + /// exits. ACE_Event_Handler *default_exit_handler_; - // This event handler is used to notify when a process we control - // exits. + /// Singleton pointer. static ACE_Process_Manager *instance_; - // Singleton pointer. + /// Controls whether the <Process_Manager> is deleted when we shut + /// down (we can only delete it safely if we created it!) static int delete_instance_; - // Controls whether the <Process_Manager> is deleted when we shut - // down (we can only delete it safely if we created it!) #if defined (ACE_HAS_THREADS) + /// This lock protects access/ops on <process_table_>. ACE_Recursive_Thread_Mutex lock_; - // This lock protects access/ops on <process_table_>. #endif /* ACE_HAS_THREADS */ }; diff --git a/ace/Process_Mutex.h b/ace/Process_Mutex.h index 241c7375370..dc8f0f08c62 100644 --- a/ace/Process_Mutex.h +++ b/ace/Process_Mutex.h @@ -1,23 +1,20 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Process_Mutex.h -// -// = DESCRIPTION -// A wrapper for mutexes that can be used across processes on -// the same host machine, as well as within a process, of -// course. -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Process_Mutex.h + * + * $Id$ + * + * A wrapper for mutexes that can be used across processes on + * the same host machine, as well as within a process, of + * course. + * + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_PROCESS_MUTEX_H #define ACE_PROCESS_MUTEX_H @@ -35,86 +32,99 @@ #include "ace/Synch.h" #endif /* !(ACE_WIN32 || ACE_HAS_POSIX_SEM || ACE_PSOS) */ +/** + * @class ACE_Process_Mutex + * + * @brief A wrapper for mutexes that can be used across processes on + * the same host machine, as well as within a process, of + * course. + */ class ACE_Export ACE_Process_Mutex { - // = TITLE - // A wrapper for mutexes that can be used across processes on - // the same host machine, as well as within a process, of - // course. public: + /// Create a Process_Mutex, passing in the optional <name>. ACE_Process_Mutex (const char *name = 0, void *arg = 0); - // Create a Process_Mutex, passing in the optional <name>. #if defined (ACE_HAS_WCHAR) + /// Create a Process_Mutex, passing in the optional <name>. (wchar_t version) ACE_Process_Mutex (const wchar_t *name, void *arg = 0); - // Create a Process_Mutex, passing in the optional <name>. (wchar_t version) #endif /* ACE_HAS_WCHAR */ ~ACE_Process_Mutex (void); + /** + * Explicitly destroy the mutex. Note that only one thread should + * call this method since it doesn't protect against race + * conditions. + */ int remove (void); - // Explicitly destroy the mutex. Note that only one thread should - // call this method since it doesn't protect against race - // conditions. + /// Acquire lock ownership (wait on queue if necessary). int acquire (void); - // Acquire lock ownership (wait on queue if necessary). + /** + * Conditionally acquire lock (i.e., don't wait on queue). Returns + * -1 on failure. If we "failed" because someone else already had + * the lock, <errno> is set to <EBUSY>. + */ int tryacquire (void); - // Conditionally acquire lock (i.e., don't wait on queue). Returns - // -1 on failure. If we "failed" because someone else already had - // the lock, <errno> is set to <EBUSY>. + /// Release lock and unblock a thread at head of queue. int release (void); - // Release lock and unblock a thread at head of queue. + /// Acquire lock ownership (wait on queue if necessary). int acquire_read (void); - // Acquire lock ownership (wait on queue if necessary). + /// Acquire lock ownership (wait on queue if necessary). int acquire_write (void); - // Acquire lock ownership (wait on queue if necessary). + /** + * Conditionally acquire a lock (i.e., won't block). Returns -1 on + * failure. If we "failed" because someone else already had the + * lock, <errno> is set to <EBUSY>. + */ int tryacquire_read (void); - // Conditionally acquire a lock (i.e., won't block). Returns -1 on - // failure. If we "failed" because someone else already had the - // lock, <errno> is set to <EBUSY>. + /** + * Conditionally acquire a lock (i.e., won't block). Returns -1 on + * failure. If we "failed" because someone else already had the + * lock, <errno> is set to <EBUSY>. + */ int tryacquire_write (void); - // Conditionally acquire a lock (i.e., won't block). Returns -1 on - // failure. If we "failed" because someone else already had the - // lock, <errno> is set to <EBUSY>. + /** + * This is only here for consistency with the other synchronization + * APIs and usability with Lock adapters. Assumes the caller already has + * acquired the mutex and returns 0 in all cases. + */ int tryacquire_write_upgrade (void); - // This is only here for consistency with the other synchronization - // APIs and usability with Lock adapters. Assumes the caller already has - // acquired the mutex and returns 0 in all cases. #if defined (ACE_WIN32) || defined (ACE_HAS_POSIX_SEM) || defined (ACE_PSOS) + /// Return the underlying mutex. const ACE_mutex_t &lock (void) const; - // Return the underlying mutex. #endif /* ACE_WIN32 || ACE_HAS_POSIX_SEM || ACE_PSOS */ + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: #if defined (ACE_WIN32) || defined (ACE_HAS_POSIX_SEM) || defined (ACE_PSOS) ACE_Mutex lock_; #else + /// If the user does not provide a name we generate a unique name in + /// this buffer. ACE_TCHAR name_[ACE_UNIQUE_NAME_LEN]; - // If the user does not provide a name we generate a unique name in - // this buffer. + /// Create and return the unique name. const ACE_TCHAR *unique_name (void); - // Create and return the unique name. + /// We need this to get the right semantics... ACE_SV_Semaphore_Complex lock_; - // We need this to get the right semantics... #endif /* ACE_WIN32 || ACE_HAS_POSIX_SEM || ACE_PSOS */ }; diff --git a/ace/Process_Semaphore.h b/ace/Process_Semaphore.h index d33107dfa1e..208bafe8dc1 100644 --- a/ace/Process_Semaphore.h +++ b/ace/Process_Semaphore.h @@ -1,22 +1,19 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Process_Semaphore.h -// -// = DESCRIPTION -// Wrapper for Dijkstra style general semaphores that work -// across processes. -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Process_Semaphore.h + * + * $Id$ + * + * Wrapper for Dijkstra style general semaphores that work + * across processes. + * + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_PROCESS_SEMAPHORE_H #define ACE_PROCESS_SEMAPHORE_H @@ -32,89 +29,108 @@ #include "ace/SV_Semaphore_Complex.h" #endif /* !(ACE_WIN32 || ACE_HAS_POSIX_SEM || ACE_PSOS) */ +/** + * @class ACE_Process_Semaphore + * + * @brief Wrapper for Dijkstra style general semaphores that work + * across processes. + */ class ACE_Export ACE_Process_Semaphore { - // = TITLE - // Wrapper for Dijkstra style general semaphores that work - // across processes. public: + /// Initialize the semaphore, with an initial value of <count> and a + /// maximum value of <max>. ACE_Process_Semaphore (u_int count = 1, // By default make this unlocked. const ACE_TCHAR *name = 0, void * = 0, int max = 0x7FFFFFFF); - // Initialize the semaphore, with an initial value of <count> and a - // maximum value of <max>. + /** + * This method is a no-op, i.e., it doesn't remove the semaphore. + * If you want to remove the semaphore, you must call the <remove> + * method explicitly. + */ ~ACE_Process_Semaphore (void); - // This method is a no-op, i.e., it doesn't remove the semaphore. - // If you want to remove the semaphore, you must call the <remove> - // method explicitly. + /** + * Explicitly destroy the semaphore. Note that only one thread + * should call this method since it doesn't protect against race + * conditions. + */ int remove (void); - // Explicitly destroy the semaphore. Note that only one thread - // should call this method since it doesn't protect against race - // conditions. + /// Block the thread until the semaphore count becomes greater than + /// 0, then decrement it. int acquire (void); - // Block the thread until the semaphore count becomes greater than - // 0, then decrement it. + /** + * Conditionally decrement the semaphore if count is greater than 0 + * (i.e., won't block). Returns -1 on failure. If we "failed" + * because someone else already had the lock, <errno> is set to + * <EBUSY>. + */ int tryacquire (void); - // Conditionally decrement the semaphore if count is greater than 0 - // (i.e., won't block). Returns -1 on failure. If we "failed" - // because someone else already had the lock, <errno> is set to - // <EBUSY>. + /// Increment the semaphore, potentially unblocking a waiting thread. int release (void); - // Increment the semaphore, potentially unblocking a waiting thread. + /** + * Acquire semaphore ownership. This calls <acquire> and is only + * here to make the <ACE_Process_Semaphore> interface consistent + * with the other synchronization APIs. + */ int acquire_read (void); - // Acquire semaphore ownership. This calls <acquire> and is only - // here to make the <ACE_Process_Semaphore> interface consistent - // with the other synchronization APIs. + /** + * Acquire semaphore ownership. This calls <acquire> and is only + * here to make the <ACE_Process_Semaphore> interface consistent + * with the other synchronization APIs. + */ int acquire_write (void); - // Acquire semaphore ownership. This calls <acquire> and is only - // here to make the <ACE_Process_Semaphore> interface consistent - // with the other synchronization APIs. + /** + * Conditionally acquire semaphore (i.e., won't block). This calls + * <tryacquire> and is only here to make the <ACE_Process_Semaphore> + * interface consistent with the other synchronization APIs. + * Returns -1 on failure. If we "failed" because someone else + * already had the lock, <errno> is set to <EBUSY>. + */ int tryacquire_read (void); - // Conditionally acquire semaphore (i.e., won't block). This calls - // <tryacquire> and is only here to make the <ACE_Process_Semaphore> - // interface consistent with the other synchronization APIs. - // Returns -1 on failure. If we "failed" because someone else - // already had the lock, <errno> is set to <EBUSY>. + /** + * Conditionally acquire semaphore (i.e., won't block). This calls + * <tryacquire> and is only here to make the <ACE_Process_Semaphore> + * interface consistent with the other synchronization APIs. + * Returns -1 on failure. If we "failed" because someone else + * already had the lock, <errno> is set to <EBUSY>. + */ int tryacquire_write (void); - // Conditionally acquire semaphore (i.e., won't block). This calls - // <tryacquire> and is only here to make the <ACE_Process_Semaphore> - // interface consistent with the other synchronization APIs. - // Returns -1 on failure. If we "failed" because someone else - // already had the lock, <errno> is set to <EBUSY>. + /** + * This is only here to make the <ACE_Process_Semaphore> + * interface consistent with the other synchronization APIs. + * Assumes the caller has already acquired the semaphore using one of + * the above calls, and returns 0 (success) always. + */ int tryacquire_write_upgrade (void); - // This is only here to make the <ACE_Process_Semaphore> - // interface consistent with the other synchronization APIs. - // Assumes the caller has already acquired the semaphore using one of - // the above calls, and returns 0 (success) always. #if defined (ACE_WIN32) || defined (ACE_HAS_POSIX_SEM) || defined (ACE_PSOS) + /// Return the underlying lock. const ACE_sema_t &lock (void) const; - // Return the underlying lock. #endif /* ACE_WIN32 || ACE_HAS_POSIX_SEM || ACE_PSOS */ + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: #if defined (ACE_WIN32) || defined (ACE_HAS_POSIX_SEM) || defined (ACE_PSOS) ACE_Semaphore lock_; #else + /// We need this to get the right semantics... ACE_SV_Semaphore_Complex lock_; - // We need this to get the right semantics... #endif /* ACE_WIN32 || ACE_HAS_POSIX_SEM || ACE_PSOS */ }; diff --git a/ace/Profile_Timer.h b/ace/Profile_Timer.h index ddaae18d85e..8bdacb52fbf 100644 --- a/ace/Profile_Timer.h +++ b/ace/Profile_Timer.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Profile_Timer.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Profile_Timer.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_PROFILE_TIMER_H #define ACE_PROFILE_TIMER_H @@ -27,22 +24,27 @@ #include "ace/Time_Value.h" #include "ace/High_Res_Timer.h" +/** + * @class ACE_Profile_Timer + * + * @brief This class provides both a timing mechanism and a mechanism + * for reporting the resource usage of a process. + */ class ACE_Export ACE_Profile_Timer { - // = TITLE - // This class provides both a timing mechanism and a mechanism - // for reporting the resource usage of a process. public: + /** + * @class ACE_Elapsed_Time + * + * @brief Keeps track of the various user, system, and elapsed (real) + * times. + * + * If <ACE_HAS_FLOATING_POINT> is enabled these values are in + * microseconds, otherwise, they are in seconds. + */ class ACE_Elapsed_Time { - // = TITLE - // Keeps track of the various user, system, and elapsed (real) - // times. - // - // = DESCRIPTION - // If <ACE_HAS_FLOATING_POINT> is enabled these values are in - // microseconds, otherwise, they are in seconds. public: ACE_timer_t real_time; ACE_timer_t user_time; @@ -52,74 +54,74 @@ public: typedef ACE_Rusage Rusage; // = Initialization and termination methods. + /// Default constructor. ACE_Profile_Timer (void); - // Default constructor. + /// Shutdown the timer. ~ACE_Profile_Timer (void); - // Shutdown the timer. // = Timer methods. + /// Activate the timer. int start (void); - // Activate the timer. + /// Stop the timer. int stop (void); - // Stop the timer. // = Resource utilization methods. + /// Compute the time elapsed since <start>. int elapsed_time (ACE_Elapsed_Time &et); - // Compute the time elapsed since <start>. + /// Compute the amount of resource utilization since the start time. void elapsed_rusage (ACE_Profile_Timer::Rusage &rusage); - // Compute the amount of resource utilization since the start time. + /// Return the resource utilization (don't recompute it). void get_rusage (ACE_Profile_Timer::Rusage &rusage); - // Return the resource utilization (don't recompute it). + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Compute how much time has elapsed. void compute_times (ACE_Elapsed_Time &et); - // Compute how much time has elapsed. + /// Keep track of the starting resource utilization. ACE_Profile_Timer::Rusage begin_usage_; - // Keep track of the starting resource utilization. + /// Keep track of the ending resource utilization. ACE_Profile_Timer::Rusage end_usage_; - // Keep track of the ending resource utilization. + /// Keep track of the last rusage for incremental timing. ACE_Profile_Timer::Rusage last_usage_; - // Keep track of the last rusage for incremental timing. #if defined (ACE_HAS_PRUSAGE_T) + /// Substract two timestructs and store their difference. void subtract (timespec_t &tdiff, timespec_t &t0, timespec_t &t1); - // Substract two timestructs and store their difference. + /// I/O handle for /proc file system. ACE_HANDLE proc_handle_; - // I/O handle for /proc file system. -#elif defined (ACE_HAS_GETRUSAGE) +#elif defined (ACE_HAS_GETRUSAGE) + /// Substract two timestructs and store their difference. void subtract (timeval &tdiff, timeval &t0, timeval &t1); - // Substract two timestructs and store their difference. + /// Keep track of the beginning time. timeval begin_time_; - // Keep track of the beginning time. + /// Keep track of the ending time. timeval end_time_; - // Keep track of the ending time. + /// Keep track of the last time for incremental timing. timeval last_time_; - // Keep track of the last time for incremental timing. #endif /* ACE_HAS_PRUSAGE_T */ #if defined (ACE_WIN32) || (!defined (ACE_HAS_PRUSAGE_T) && !defined (ACE_HAS_GETRUSAGE)) + /// The high resolution timer ACE_High_Res_Timer timer_; - // The high resolution timer #endif /* ACE_WIN32 || !ACE_HAS_PRUSAGE_T && !ACE_HAS_GETRUSAGE */ }; @@ -129,4 +131,3 @@ private: #include "ace/post.h" #endif /* ACE_PROFILE_TIMER_H */ - diff --git a/ace/QoS_Decorator.h b/ace/QoS_Decorator.h index c2d9163539d..901cd8d5ff1 100644 --- a/ace/QoS_Decorator.h +++ b/ace/QoS_Decorator.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE_wrappers/ace -// -// = FILENAME -// QOS_Decorator.h -// -// = AUTHOR -// Vishal Kachroo <vishal@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file QOS_Decorator.h + * + * $Id$ + * + * @author Vishal Kachroo <vishal@cs.wustl.edu> + */ +//============================================================================= + #ifndef QOS_DECORATOR_H #define QOS_DECORATOR_H @@ -29,143 +26,149 @@ #include "ace/SOCK_Dgram_Mcast_QoS.h" ACE_RCSID(QOS_Decorator, QOS_Decorator, "$Id$") - + +/** + * @class ACE_QoS_Decorator_Base + * + * @brief This class is the Decorator Pattern Base class for decorating + * ACE_Event_Handler. + * + * It simply forwards the requests for get_handle (), + * handle_input () and handle_qos () to its event_handler_ + * component. Concrete decorators for ACE_Event_Handler will use + * this class to access the basic event handler functionality and + * decorate that by their own implementation. + */ class ACE_Export ACE_QoS_Decorator_Base : public ACE_Event_Handler { - // = TITLE - // This class is the Decorator Pattern Base class for decorating - // ACE_Event_Handler. - // - // = DESCRIPTION - // It simply forwards the requests for get_handle (), - // handle_input () and handle_qos () to its event_handler_ - // component. Concrete decorators for ACE_Event_Handler will use - // this class to access the basic event handler functionality and - // decorate that by their own implementation. - + public: - + // Initialization and termination methods. + /// Constructor. ACE_QoS_Decorator_Base (void); - // Constructor. + /// Constructor. ACE_QoS_Decorator_Base (ACE_Event_Handler *event_handler); - // Constructor. + /// Destructor. ~ACE_QoS_Decorator_Base (void); - // Destructor. + /// Forwards the request to its event_handler_ component. virtual ACE_HANDLE get_handle (void) const; - // Forwards the request to its event_handler_ component. + /// Forwards the request to its event_handler_ component. virtual int handle_input (ACE_HANDLE fd); - // Forwards the request to its event_handler_ component. + /// Forwards the request to its event_handler_ component. virtual int handle_qos (ACE_HANDLE fd); - // Forwards the request to its event_handler_ component. private: - + + /// The event handler that is decorated by this class. ACE_Event_Handler *event_handler_; - // The event handler that is decorated by this class. }; -class ACE_Export ACE_QoS_Event_Handler : public ACE_Event_Handler +/** + * @class ACE_QoS_Event_Handler + * + * @brief This Handler is registered with the Reactor for QoS events. + * + * Concrete QoS decorator uses this class to receive QoS events + * for RAPI. It hides the application from knowing that it is + * receiving QoS events on a different socket so the application + * doesnt have to be designed differently for RAPI and GQoS. + */ +class ACE_Export ACE_QoS_Event_Handler : public ACE_Event_Handler { - // = TITLE - // This Handler is registered with the Reactor for QoS events. - // - // = DESCRIPTION - // Concrete QoS decorator uses this class to receive QoS events - // for RAPI. It hides the application from knowing that it is - // receiving QoS events on a different socket so the application - // doesnt have to be designed differently for RAPI and GQoS. + /// Destructor. ~ACE_QoS_Event_Handler (void); - // Destructor. + /// Returns the RAPI file descriptor for receiving QoS events. virtual ACE_HANDLE get_handle (void) const; - // Returns the RAPI file descriptor for receiving QoS events. + /// Calls the base class handle_input (). virtual int handle_input (ACE_HANDLE fd); - // Calls the base class handle_input (). + /// Sets the QoS session. void qos_session (ACE_QoS_Session *qos_session); - // Sets the QoS session. friend class ACE_QoS_Decorator; private: + /// Constructor is private because only ACE_QoS_Decorator should + /// create this object. ACE_QoS_Event_Handler (void); - // Constructor is private because only ACE_QoS_Decorator should - // create this object. + /// The QoS Decorator passes in its base for this handler to use. ACE_QoS_Event_Handler (ACE_QoS_Decorator_Base *decorator_base); - // The QoS Decorator passes in its base for this handler to use. + /// Used to get to the RAPI file descriptor for QoS Events. ACE_QoS_Session *qos_session_; - // Used to get to the RAPI file descriptor for QoS Events. + /// Requests on the class are forwarded to this base class; ACE_QoS_Decorator_Base *decorator_base_; - // Requests on the class are forwarded to this base class; }; +/** + * @class ACE_QoS_Decorator + * + * @brief Concrete QoS Decorator. + * + * Decorates the ACE_Event_Handler to additionally handle QoS + * events uniformly for different QoS mechanisms like RAPI and + * GQoS. + */ class ACE_Export ACE_QoS_Decorator : public ACE_QoS_Decorator_Base { - // = TITLE - // Concrete QoS Decorator. - // - // = DESCRIPTION - // Decorates the ACE_Event_Handler to additionally handle QoS - // events uniformly for different QoS mechanisms like RAPI and - // GQoS. public: // Initialization and termination methods. + /// Constructor. ACE_QoS_Decorator (void); - // Constructor. + /// Constructor. ACE_QoS_Decorator (ACE_Event_Handler *event_handler, ACE_QoS_Session *qos_session, ACE_Reactor *reactor = ACE_Reactor::instance ()); - // Constructor. + /// Destructor. ~ACE_QoS_Decorator (void); - // Destructor. + /// Calls the base class get_handle (). virtual ACE_HANDLE get_handle (void) const; - // Calls the base class get_handle (). + /// Calls the base class handle_input (). virtual int handle_input (ACE_HANDLE fd); - // Calls the base class handle_input (). + /// Calls the base class handle_qos (). virtual int handle_qos (ACE_HANDLE fd); - // Calls the base class handle_qos (). - + + /// This method registers the QoS Event Handler with the Reactor + /// to receive RAPI events. int init (void); - // This method registers the QoS Event Handler with the Reactor - // to receive RAPI events. private: + /// Requests on the class are forwarded to this base class; ACE_QoS_Decorator_Base *decorator_base_; - // Requests on the class are forwarded to this base class; + /// Handles the QoS events and in that sense decorates the usual + /// ACE_Event_Handler. ACE_QoS_Event_Handler *qos_event_handler_; - // Handles the QoS events and in that sense decorates the usual - // ACE_Event_Handler. + /// Passed to the ACE_QoS_Event_Handler for retrieving the RAPI + /// session specific information like rapi_fd. ACE_QoS_Session *qos_session_; - // Passed to the ACE_QoS_Event_Handler for retrieving the RAPI - // session specific information like rapi_fd. + /// If the application wants to use an instance of Reactor other + /// than the Singleton one. ACE_Reactor *reactor_; - // If the application wants to use an instance of Reactor other - // than the Singleton one. }; diff --git a/ace/QoS_Manager.h b/ace/QoS_Manager.h index 66936aeeb8e..bd456270fc3 100644 --- a/ace/QoS_Manager.h +++ b/ace/QoS_Manager.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -//============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// QoS_Manager.h -// -// = AUTHOR -// Vishal Kachroo -// -//============================================================================ +//============================================================================= +/** + * @file QoS_Manager.h + * + * $Id$ + * + * @author Vishal Kachroo + */ +//============================================================================= + #ifndef ACE_QOS_MANAGER_H #define ACE_QOS_MANAGER_H @@ -29,42 +26,42 @@ class ACE_QoS_Session; +/** + * @class ACE_QoS_Manager + * + * @brief This class manages the QoS sessions associated with ACE_SOCK. + * + * This class provides functions to manage the QoS + * associated with a socket. The idea is to keep the management of + * QoS for a socket separate from the socket itself. Currently, the + * manager is used to manage the QoS session set. It will handle more + * responsibilities in the future. + */ class ACE_Export ACE_QoS_Manager { - // = TITLE - // This class manages the QoS sessions associated with ACE_SOCK. - // - // = DESCRIPTION - // This class provides functions to manage the QoS - // associated with a socket. The idea is to keep the management of - // QoS for a socket separate from the socket itself. Currently, the - // manager is used to manage the QoS session set. It will handle more - // responsibilities in the future. public: + /// Default ctor/dtor. ACE_QoS_Manager (void); ~ACE_QoS_Manager (void); - // Default ctor/dtor. - + + /** + * Join the given QoS session. A socket can join multiple QoS + * sessions. This call adds the given QoS session to the list of + * QoS sessions that the socket has already joined. + */ int join_qos_session (ACE_QoS_Session *qos_session); - // Join the given QoS session. A socket can join multiple QoS - // sessions. This call adds the given QoS session to the list of - // QoS sessions that the socket has already joined. typedef ACE_Unbounded_Set <ACE_QoS_Session *> ACE_QOS_SESSION_SET; + /// Get the QoS session set. ACE_QOS_SESSION_SET qos_session_set (void); - // Get the QoS session set. private: + /// Set of QoS sessions that this socket has joined. ACE_QOS_SESSION_SET qos_session_set_; - // Set of QoS sessions that this socket has joined. }; #include "ace/post.h" #endif /* ACE_QOS_MANAGER_H */ - - - - diff --git a/ace/QoS_Session.h b/ace/QoS_Session.h index cdbef4db6a8..472fde17b12 100644 --- a/ace/QoS_Session.h +++ b/ace/QoS_Session.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// =========================================================================== -// -// = LIBRARY -// ace -// -// = FILENAME -// QoS_Session.h -// -// = AUTHOR -// Vishal Kachroo <vishal@cs.wustl.edu> -// -// =========================================================================== + +//============================================================================= +/** + * @file QoS_Session.h + * + * $Id$ + * + * @author Vishal Kachroo <vishal@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_QOS_SESSION_H #define ACE_QOS_SESSION_H @@ -30,122 +27,121 @@ class ACE_QoS_Manager; typedef int ACE_Protocol_ID; // IPPROTO_UDP or IPPROTO_TCP. +/** + * @class ACE_QoS_Session + * + * @brief A QoS Session object. + * + * This class defines the interface for a QoS Session. It abstracts the + * notion of QoS on different platforms and presents a simple, easy-to-use + * API. Current [RAPI,GQoS] and future implementations will conform to this + * interface. + */ class ACE_Export ACE_QoS_Session { - // = TITLE - // A QoS Session object. - // - // = DESCRIPTION - // This class defines the interface for a QoS Session. It abstracts the - // notion of QoS on different platforms and presents a simple, easy-to-use - // API. Current [RAPI,GQoS] and future implementations will conform to this - // interface. public: + /// A flag to indicate if this endpoint is a sender or a receiver or + /// both. enum ACE_End_Point_Type { ACE_QOS_SENDER, ACE_QOS_RECEIVER, ACE_QOS_BOTH }; - // A flag to indicate if this endpoint is a sender or a receiver or - // both. + /// to shutup g++. virtual ~ACE_QoS_Session (void) {}; - // to shutup g++. + /// Open a QoS session [dest IP, dest port, Protocol ID]. virtual int open (ACE_INET_Addr dest_addr, ACE_Protocol_ID protocol_id) = 0; - // Open a QoS session [dest IP, dest port, Protocol ID]. + /// Close the QoS Session. virtual int close (void) = 0; - // Close the QoS Session. - + + /// Returns the QoS in the current session. virtual ACE_QoS qos (void) const = 0; - // Returns the QoS in the current session. - + + /// Set QoS for the current session. The qos manager is used to + /// confirm if this QoS session was subscribed to by the socket. virtual int qos (ACE_SOCK *socket, ACE_QoS_Manager *qos_manager, const ACE_QoS &ace_qos) = 0; - // Set QoS for the current session. The qos manager is used to - // confirm if this QoS session was subscribed to by the socket. - + + /** + * Sets the QoS for this session object to ace_qos. Does not + * interfere with the QoS in the underlying socket. This call is + * useful to update the QoS object when the underlying socket QoS is + * being set through a mechanism other than the previous qos () + * method e.g. inside the dgram_mcast.subscribe () where the QoS for + * the socket is set through ACE_OS::join_leaf (). + */ virtual void qos (const ACE_QoS &ace_qos) = 0; - // Sets the QoS for this session object to ace_qos. Does not - // interfere with the QoS in the underlying socket. This call is - // useful to update the QoS object when the underlying socket QoS is - // being set through a mechanism other than the previous qos () - // method e.g. inside the dgram_mcast.subscribe () where the QoS for - // the socket is set through ACE_OS::join_leaf (). + /** + * This is called from handle_qos () method of the the QoS Event + * Handler. Invoking this method is an indication of a QoS event + * occurring, that may have resulted in a change of QoS for the + * underlying session. This method updates the QoS object associated + * with this session. + */ virtual int update_qos (void) = 0; - // This is called from handle_qos () method of the the QoS Event - // Handler. Invoking this method is an indication of a QoS event - // occurring, that may have resulted in a change of QoS for the - // underlying session. This method updates the QoS object associated - // with this session. + /// Get/Set methods for the flags_. virtual ACE_End_Point_Type flags (void) const = 0; virtual void flags (const ACE_End_Point_Type flags) = 0; - // Get/Set methods for the flags_. + /// Get the session id. virtual int session_id (void) const = 0; - // Get the session id. - + + /// Set the session id. virtual void session_id (const int session_id) = 0; - // Set the session id. + /// Get the file descriptor on which RSVP events will occur. virtual ACE_HANDLE rsvp_events_handle (void) = 0; - // Get the file descriptor on which RSVP events will occur. + /// Get the destination address for this session. virtual ACE_INET_Addr dest_addr (void) const = 0; - // Get the destination address for this session. + /// Set the destination address for this session. virtual void dest_addr (const ACE_INET_Addr &dest_addr) = 0; - // Set the destination address for this session. + /// Get the source port for this session. virtual u_short source_port (void) const = 0; - // Get the source port for this session. - + + /// Set the source port for this session. virtual void source_port (const u_short &source_port) = 0; - // Set the source port for this session. - + + /** + * Returns the version of the underlying RSVP implementation. Is + * meaningful only when the underlying implementation has + * versioning. + */ virtual int version (void) = 0; - // Returns the version of the underlying RSVP implementation. Is - // meaningful only when the underlying implementation has - // versioning. - + protected: + /// Source port if this is a Sender session. Used for rapi_sender (). u_short source_port_; - // Source port if this is a Sender session. Used for rapi_sender (). + /// session id for the session. int session_id_; - // session id for the session. - + + /// Destination address for this session. ACE_INET_Addr dest_addr_; - // Destination address for this session. + /// Is this a TCP or a UDP session. ACE_Protocol_ID protocol_id_; - // Is this a TCP or a UDP session. + /// QoS for this session. ACE_QoS qos_; - // QoS for this session. - + + /// Specifies if this is a sending/receiving/both session. ACE_End_Point_Type flags_; - // Specifies if this is a sending/receiving/both session. }; #include "ace/post.h" #endif /* ACE_QOS_SESSION_H */ - - - - - - - - - diff --git a/ace/QoS_Session_Factory.h b/ace/QoS_Session_Factory.h index f4c18336f58..87c2334ff2f 100644 --- a/ace/QoS_Session_Factory.h +++ b/ace/QoS_Session_Factory.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// =========================================================================== -// -// = LIBRARY -// ace -// -// = FILENAME -// QoS_Session_Factory.h -// -// = AUTHOR -// Vishal Kachroo <vishal@cs.wustl.edu> -// -// =========================================================================== + +//============================================================================= +/** + * @file QoS_Session_Factory.h + * + * $Id$ + * + * @author Vishal Kachroo <vishal@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_QOS_SESSION_FACTORY_H #define ACE_QOS_SESSION_FACTORY_H @@ -26,65 +23,61 @@ #include "ace/Containers_T.h" +/** + * @class ACE_QoS_Session; + Forward declare this, so the factory uses only references to this. + */ class ACE_QoS_Session; -// Forward declare this, so the factory uses only references to this. +/** + * @class ACE_QoS_Session_Factory + * + * @brief Concrete factory for the QoS Session objects. + * + * This class manages the life cycle of QoS Session objects. These + * objects are currently either RAPI session objects or GQoS session + * objects. It stores the sessions in an unbounded set. + */ class ACE_Export ACE_QoS_Session_Factory { - // = TITLE - // Concrete factory for the QoS Session objects. - // - // = DESCRIPTION - // This class manages the life cycle of QoS Session objects. These - // objects are currently either RAPI session objects or GQoS session - // objects. It stores the sessions in an unbounded set. public : - + // = Initialization and termination methods. + /// Default constructor. ACE_QoS_Session_Factory (void); - // Default constructor. - + + /// Default destructor. ~ACE_QoS_Session_Factory (void); - // Default destructor. + /// Types of sessions for this factory to manage. enum ACE_QoS_Session_Type { ACE_RAPI_SESSION, ACE_GQOS_SESSION }; - // Types of sessions for this factory to manage. + /// Create a QoS session of the given type (RAPI or GQoS). ACE_QoS_Session * create_session (ACE_QoS_Session_Type qos_session_type); - // Create a QoS session of the given type (RAPI or GQoS). + /// Destroy the QoS Session. int destroy_session (ACE_QoS_Session *qos_session); - // Destroy the QoS Session. private: + /// Used by the create_session () to add new sessions to the + /// set of sessions created by this factory. int add_session (ACE_QoS_Session *qos_session); - // Used by the create_session () to add new sessions to the - // set of sessions created by this factory. + /// Used by the destroy_session () to remove a session from the set + /// of sessions created by this factory. int remove_session (ACE_QoS_Session *qos_session); - // Used by the destroy_session () to remove a session from the set - // of sessions created by this factory. + /// Unordered set of QoS Sessions. typedef ACE_Unbounded_Set <ACE_QoS_Session *> QOS_SESSION_SET; QOS_SESSION_SET qos_session_set_; - // Unordered set of QoS Sessions. }; #include "ace/post.h" #endif /* ACE_QOS_SESSION_FACTORY_H */ - - - - - - - - - diff --git a/ace/QoS_Session_Impl.h b/ace/QoS_Session_Impl.h index a657dbb837b..9d9a5d5570e 100644 --- a/ace/QoS_Session_Impl.h +++ b/ace/QoS_Session_Impl.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// =========================================================================== -// -// = LIBRARY -// ace -// -// = FILENAME -// QoS_Session_Impl.h -// -// = AUTHOR -// Vishal Kachroo <vishal@cs.wustl.edu> -// -// =========================================================================== + +//============================================================================= +/** + * @file QoS_Session_Impl.h + * + * $Id$ + * + * @author Vishal Kachroo <vishal@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_QOS_SESSION_IMPL_H #define ACE_QOS_SESSION_IMPL_H @@ -30,190 +27,200 @@ #define DEFAULT_SOURCE_SENDER_PORT 10001 +/** + * @class ACE_RAPI_Session + * + * @brief A RAPI QoS session object. + * + * This class is a RAPI (RSVP API, an implementation of RSVP on UNIX) + * implementation of the ACE_QoS_Session interface. + */ class ACE_Export ACE_RAPI_Session : public ACE_QoS_Session { - // = TITLE - // A RAPI QoS session object. - // - // = DESCRIPTION - // This class is a RAPI (RSVP API, an implementation of RSVP on UNIX) - // implementation of the ACE_QoS_Session interface. - + public: - + + /// Default destructor. ~ACE_RAPI_Session (void); - // Default destructor. + /// Error handling for RSVP callback static int rsvp_error; - // Error handling for RSVP callback + /// Open a RAPI QoS session [dest IP, dest port, Protocol ID]. virtual int open (ACE_INET_Addr dest_addr, ACE_Protocol_ID protocol_id); - // Open a RAPI QoS session [dest IP, dest port, Protocol ID]. + /// Close the RAPI QoS Session. virtual int close (void); - // Close the RAPI QoS Session. - + + /// Returns the QoS for this RAPI session. virtual ACE_QoS qos (void) const; - // Returns the QoS for this RAPI session. - + + /// Set QoS for this RAPI session. The socket parameter is used to confirm if + /// this QoS session was subscribed to by the socket. virtual int qos (ACE_SOCK *socket, ACE_QoS_Manager *qos_manager, const ACE_QoS &ace_qos); - // Set QoS for this RAPI session. The socket parameter is used to confirm if - // this QoS session was subscribed to by the socket. + /** + * Sets the QoS for this session object to ace_qos. Does not interfere with the + * QoS in the underlying socket. This call is useful to update the QoS object + * when the underlying socket QoS is being set through a mechanism other than + * the previous qos () method e.g. inside the dgram_mcast.subscribe () where the + * QoS for the socket is set through ACE_OS::join_leaf (). + */ virtual void qos (const ACE_QoS &ace_qos); - // Sets the QoS for this session object to ace_qos. Does not interfere with the - // QoS in the underlying socket. This call is useful to update the QoS object - // when the underlying socket QoS is being set through a mechanism other than - // the previous qos () method e.g. inside the dgram_mcast.subscribe () where the - // QoS for the socket is set through ACE_OS::join_leaf (). + /** + * Calls rapi_dispatch () that further triggers the call back function. + * It is a mechanism of updating the QoS for this session asynchronously, as + * RSVP events occur. + */ virtual int update_qos (void); - // Calls rapi_dispatch () that further triggers the call back function. - // It is a mechanism of updating the QoS for this session asynchronously, as - // RSVP events occur. + /// Get/Set methods for the flags_. virtual ACE_End_Point_Type flags (void) const; virtual void flags (const ACE_End_Point_Type flags); - // Get/Set methods for the flags_. + /// Get the RAPI session id. virtual int session_id (void) const; - // Get the RAPI session id. - + + /// Set the RAPI session id. virtual void session_id (const int session_id); - // Set the RAPI session id. + /// Get the RAPI file descriptor for RSVP events. virtual ACE_HANDLE rsvp_events_handle (void); - // Get the RAPI file descriptor for RSVP events. + /// Get the destination address for this RAPI session. virtual ACE_INET_Addr dest_addr (void) const; - // Get the destination address for this RAPI session. + /// Set the destination address for this RAPI session. virtual void dest_addr (const ACE_INET_Addr &dest_addr); - // Set the destination address for this RAPI session. + /// Get the source port for this session. virtual u_short source_port (void) const; - // Get the source port for this session. - + + /// Set the source port for this session. virtual void source_port (const u_short &source_port); - // Set the source port for this session. - + + /// RAPI version. Returned value = 100 * major-version + minor-version. virtual int version (); - // RAPI version. Returned value = 100 * major-version + minor-version. + /// The factory is a friend so it can create this object through + /// the only private constructor. friend class ACE_QoS_Session_Factory; - // The factory is a friend so it can create this object through - // the only private constructor. - + private: - + + /// Default constuctor. Constructor is defined private so that only + /// the friend factory can instantiate this class. ACE_RAPI_Session (void); - // Default constuctor. Constructor is defined private so that only - // the friend factory can instantiate this class. + /// Construct a simplified RAPI Sender TSpec object + /// from an ACE_Flow_Spec object. Used internally by this class. rapi_tspec_t *init_tspec_simplified (const ACE_Flow_Spec &flow_spec); - // Construct a simplified RAPI Sender TSpec object - // from an ACE_Flow_Spec object. Used internally by this class. + /// Construct a simplified RAPI Receiver FlowSpec object + /// from an ACE_Flow_Spec object. Used internally by the class. rapi_flowspec_t *init_flowspec_simplified(const ACE_Flow_Spec &flow_spec); - // Construct a simplified RAPI Receiver FlowSpec object - // from an ACE_Flow_Spec object. Used internally by the class. + /// Set sending QoS for this RAPI session. int sending_qos (const ACE_QoS &ace_qos); - // Set sending QoS for this RAPI session. - + + /// Set receiving QoS for this RAPI session. int receiving_qos (const ACE_QoS &ace_qos); - // Set receiving QoS for this RAPI session. - + }; #endif /* ACE_HAS_RAPI */ +/** + * @class ACE_GQoS_Session + * + * @brief A GQoS session object. + * + * This class is a GQoS (Generic QoS, an implementation of RSVP on + * Win2K) implementation of the ACE_QoS_Session interface. + */ class ACE_Export ACE_GQoS_Session : public ACE_QoS_Session { - // = TITLE - // A GQoS session object. - // - // = DESCRIPTION - // This class is a GQoS (Generic QoS, an implementation of RSVP on - // Win2K) implementation of the ACE_QoS_Session interface. public: - + + /// Default destructor. ~ACE_GQoS_Session (void); - // Default destructor. + /// This is a session ID generator. It does a lot more than expected + /// from an int!. static int GQoS_session_id; - // This is a session ID generator. It does a lot more than expected - // from an int!. + /// Open a GQoS session [dest IP, dest port, Protocol ID]. virtual int open (ACE_INET_Addr dest_addr, ACE_Protocol_ID protocol_id); - // Open a GQoS session [dest IP, dest port, Protocol ID]. + /// Close the GQoS Session. virtual int close (void); - // Close the GQoS Session. - + + /// Returns the QoS for this GQoS session. virtual ACE_QoS qos (void) const; - // Returns the QoS for this GQoS session. + /// Set QoS for this GQoS session. The socket parameter is used to confirm if + /// this QoS session was subscribed to by the socket. virtual int qos (ACE_SOCK *socket, ACE_QoS_Manager *qos_manager, const ACE_QoS &ace_qos); - // Set QoS for this GQoS session. The socket parameter is used to confirm if - // this QoS session was subscribed to by the socket. - + + /** + * Sets the QoS for this session object to ace_qos. Does not interfere with the + * QoS in the underlying socket. This call is useful to update the QoS object + * when the underlying socket QoS is being set through a mechanism other than + * the previous qos () method e.g. inside the dgram_mcast.subscribe () where the + * QoS for the socket is set through ACE_OS::join_leaf (). + */ virtual void qos (const ACE_QoS &ace_qos); - // Sets the QoS for this session object to ace_qos. Does not interfere with the - // QoS in the underlying socket. This call is useful to update the QoS object - // when the underlying socket QoS is being set through a mechanism other than - // the previous qos () method e.g. inside the dgram_mcast.subscribe () where the - // QoS for the socket is set through ACE_OS::join_leaf (). - + + /// Calls the ioctl (ACE_SIO_GET_QOS). It is a mechanism of updating the + /// QoS for this session asynchronously, as RSVP events occur. virtual int update_qos (void); - // Calls the ioctl (ACE_SIO_GET_QOS). It is a mechanism of updating the - // QoS for this session asynchronously, as RSVP events occur. + /// Get/Set methods for the flags_. virtual ACE_End_Point_Type flags (void) const; virtual void flags (const ACE_End_Point_Type flags); - // Get/Set methods for the flags_. + /// Get the destination address for this GQoS session. virtual ACE_INET_Addr dest_addr (void) const; - // Get the destination address for this GQoS session. + /// Set the destination address for this GQoS session. virtual void dest_addr (const ACE_INET_Addr &dest_addr); - // Set the destination address for this GQoS session. + /// Get the source port for this session. virtual u_short source_port (void) const; - // Get the source port for this session. - + + /// Set the source port for this session. virtual void source_port (const u_short &source_port); - // Set the source port for this session. - + + /// Get the GQoS session id. virtual int session_id (void) const; - // Get the GQoS session id. - + + /// Set the GQoS session id. virtual void session_id (const int session_id); - // Set the GQoS session id. + /// Get the file descriptor of the underlying socket. virtual ACE_HANDLE rsvp_events_handle (void); - // Get the file descriptor of the underlying socket. + /// GQoS version. virtual int version (); - // GQoS version. + /// The factory is a friend so it can create this object through + /// the only private constructor. friend class ACE_QoS_Session_Factory; - // The factory is a friend so it can create this object through - // the only private constructor. private: - + + /// Default constructor. Constructor is defined private so that only + /// the friend factory can instantiate this class. ACE_GQoS_Session (void); - // Default constructor. Constructor is defined private so that only - // the friend factory can instantiate this class. - + }; #if defined (__ACE_INLINE__) @@ -222,5 +229,3 @@ private: #include "ace/post.h" #endif /* ACE_QOS_SESSION_IMPL_H */ - - diff --git a/ace/QtReactor.h b/ace/QtReactor.h index e2afc998db0..2944a3b7069 100644 --- a/ace/QtReactor.h +++ b/ace/QtReactor.h @@ -1,18 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// QtReactor.h -// -// = AUTHOR -// Hamish Friedlander <ullexco@wave.co.nz> -// integrated in to ACE by Balachandran Natarajan <bala@cs.wustl.edu> -// ============================================================================ + +//============================================================================= +/** + * @file QtReactor.h + * + * $Id$ + * + * @author Hamish Friedlander <ullexco@wave.co.nz> + * @author Balachandran Natarajan <bala@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_QTREACTOR_H #define ACE_QTREACTOR_H #include "ace/pre.h" @@ -27,32 +25,35 @@ #if defined (ACE_HAS_QT) #include "ace/Map_Manager.h" -// Qttoolkit specific includes. +// Qttoolkit specific includes. #include <qapplication.h> #include <qobject.h> #include <qsocketnotifier.h> #include <qtimer.h> +/** + * @class ACE_QtReactor + * + * @brief An object-oriented event demultiplexor and event handler + * dispatcher that uses the Qt Library. This class declaration + * also uses the extnsion facilities provided by the Qt. So, + * readers of the class declaration should not be upset with + * the appearence of the Keywords like Q_OBJECT, private slots + * etc. They are specific to Qt which uses these as a call back + * methods implementation mechanism. + */ class ACE_Export ACE_QtReactor : public QObject, public ACE_Select_Reactor { - // = TITLE - // An object-oriented event demultiplexor and event handler - // dispatcher that uses the Qt Library. This class declaration - // also uses the extnsion facilities provided by the Qt. So, - // readers of the class declaration should not be upset with - // the appearence of the Keywords like Q_OBJECT, private slots - // etc. They are specific to Qt which uses these as a call back - // methods implementation mechanism. Q_OBJECT - + public: // = Initialization and termination methods. - ACE_QtReactor (QApplication *qapp = NULL, + ACE_QtReactor (QApplication *qapp = NULL, size_t size = DEFAULT_SIZE, int restart = 0, ACE_Sig_Handler *handler = 0); - + virtual ~ACE_QtReactor (void); void qapplication (QApplication *qapp); @@ -62,88 +63,88 @@ class ACE_Export ACE_QtReactor : public QObject, public ACE_Select_Reactor const void *arg, const ACE_Time_Value &delta_time, const ACE_Time_Value &interval); - + virtual int cancel_timer (ACE_Event_Handler *handler, int dont_call_handle_close = 1); virtual int cancel_timer (long timer_id, const void **arg = 0, int dont_call_handle_close = 1); - + protected: - + // = Register timers/handles with Qt - + + /// Register a single <handler>. virtual int register_handler_i (ACE_HANDLE handle, ACE_Event_Handler *handler, ACE_Reactor_Mask mask); - // Register a single <handler>. - + + /// Register a set of <handlers> with Qt. virtual int register_handler_i (const ACE_Handle_Set &handles, ACE_Event_Handler *handler, ACE_Reactor_Mask mask); - // Register a set of <handlers> with Qt. - - + + + /// Remove the <handler> associated with this <handle>. virtual int remove_handler_i (ACE_HANDLE handle, ACE_Reactor_Mask mask); - // Remove the <handler> associated with this <handle>. + /// Remove a set of <handles>. virtual int remove_handler_i (const ACE_Handle_Set &handles, ACE_Reactor_Mask mask); - // Remove a set of <handles>. + /// Wait for events to occur. virtual int wait_for_multiple_events (ACE_Select_Reactor_Handle_Set &handle_set, ACE_Time_Value *max_wait_time); - // Wait for events to occur. virtual int QtWaitForMultipleEvents (int width, ACE_Select_Reactor_Handle_Set &wait_set, ACE_Time_Value *max_wait_time); - + // Wait for Qt events to occur + /// Some Qt stuff that we need to have QApplication *qapp_ ; - // Some Qt stuff that we need to have + /// Typedef of a map. typedef ACE_Map_Manager<ACE_HANDLE, QSocketNotifier *, ACE_Null_Mutex> MAP; - // Typedef of a map. + /// A notifier for a read MAP read_notifier_; - // A notifier for a read + /// A write notifier MAP write_notifier_; - // A write notifier - + + /// An exception notifier MAP exception_notifier_; - // An exception notifier + /// The timer class that would provide timer-sgnals & single-shot timers QTimer *qtime_ ; - // The timer class that would provide timer-sgnals & single-shot timers - private: + private: + /// This method ensures there's an Qt timeout for the first timeout + /// in the Reactor's Timer_Queue. void reset_timeout (void); - // This method ensures there's an Qt timeout for the first timeout - // in the Reactor's Timer_Queue. - + + /// Deny access since member-wise won't work... ACE_QtReactor (const ACE_QtReactor &); ACE_QtReactor &operator= (const ACE_QtReactor &); - // Deny access since member-wise won't work... private slots: - + // These are all part of the communication mechanism adopted in Qt. + /// Dispatch a Read Event void read_event (int FD); - // Dispatch a Read Event + /// Dispatch a Write Event void write_event (int FD); - // Dispatch a Write Event + /// Dispatch an exception event void exception_event (int FD); - // Dispatch an exception event + /// Dispach a timeout event void timeout_event (void); - // Dispach a timeout event }; #endif /*ACE_HAS_QT */ diff --git a/ace/RB_Tree.h b/ace/RB_Tree.h index d42b92d1da6..2450251da8e 100644 --- a/ace/RB_Tree.h +++ b/ace/RB_Tree.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// RB_Tree.h -// -// = AUTHOR -// Chris Gill -// -// ============================================================================ + +//============================================================================= +/** + * @file RB_Tree.h + * + * $Id$ + * + * @author Chris Gill + */ +//============================================================================= + #ifndef ACE_RB_TREE_H #define ACE_RB_TREE_H @@ -46,100 +43,103 @@ public: enum RB_Tree_Node_Color {RED, BLACK}; }; +/** + * @class ACE_RB_Tree_Node + * + * @brief Implements a node in a Red-Black Tree ADT. + */ template <class EXT_ID, class INT_ID> class ACE_RB_Tree_Node : public ACE_RB_Tree_Node_Base { - // = TITLE - // Implements a node in a Red-Black Tree ADT. - // public: // = Initialization and termination methods. + /// Constructor. ACE_RB_Tree_Node (const EXT_ID &k, const INT_ID &t); - // Constructor. + /// Destructor. ~ACE_RB_Tree_Node (void); - // Destructor. + /// Key accessor. EXT_ID &key (void); - // Key accessor. + /// Item accessor. INT_ID &item (void); - // Item accessor. + /// Set color of the node. void color (RB_Tree_Node_Color c); - // Set color of the node. + /// Get color of the node. RB_Tree_Node_Color color (void); - // Get color of the node. + /// Accessor for node's parent pointer. ACE_RB_Tree_Node<EXT_ID, INT_ID> *parent (void); - // Accessor for node's parent pointer. + /// Mutator for node's parent pointer. void parent (ACE_RB_Tree_Node<EXT_ID, INT_ID> * p); - // Mutator for node's parent pointer. + /// Accessor for node's left child pointer. ACE_RB_Tree_Node<EXT_ID, INT_ID> *left (void); - // Accessor for node's left child pointer. + /// Mutator for node's left child pointer. void left (ACE_RB_Tree_Node<EXT_ID, INT_ID> *l); - // Mutator for node's left child pointer. + /// Accessor for node's right child pointer. ACE_RB_Tree_Node<EXT_ID, INT_ID> *right (void); - // Accessor for node's right child pointer. + /// Mutator for node's right child pointer void right (ACE_RB_Tree_Node<EXT_ID, INT_ID> * r); - // Mutator for node's right child pointer private: + /// The key. EXT_ID k_; - // The key. + /// The item. INT_ID t_; - // The item. + /// Color of the node. RB_Tree_Node_Color color_; - // Color of the node. + /// Pointer to node's parent. ACE_RB_Tree_Node<EXT_ID, INT_ID> *parent_; - // Pointer to node's parent. + /// Pointer to node's left child. ACE_RB_Tree_Node<EXT_ID, INT_ID> *left_; - // Pointer to node's left child. + /// Pointer to node's right child. ACE_RB_Tree_Node<EXT_ID, INT_ID> *right_; - // Pointer to node's right child. }; class ACE_RB_Tree_Base { public: - // = Search result enumeration. + /// Search result enumeration. enum RB_SearchResult {LEFT, EXACT, RIGHT}; }; +/** + * @class ACE_RB_Tree + * + * @brief Implements a Red-Black Tree ADT, according to T. H. Corman, + * C. E. Leiserson, and R. L. Rivest, "Introduction to Algorithms" + * 1990, MIT, chapter 14. + * + * A number of Changes have been made to this class template + * in order to conform to the ACE_Hash_Map_Manager_Ex + * interface. All previously supported public methods are + * still part of this class. However, these are marked as + * DEPRECATED and will be removed from this class in + * a future version of ACE. Please migrate your code + * to the appropriate public methods indicated in the + * method deprecation comments. + * This class uses an <ACE_Allocator> to allocate memory. The + * user can make this a persistent class by providing an + * <ACE_Allocator> with a persistable memory pool. + */ template <class EXT_ID, class INT_ID, class COMPARE_KEYS, class ACE_LOCK> class ACE_RB_Tree : public ACE_RB_Tree_Base { - // = TITLE - // Implements a Red-Black Tree ADT, according to T. H. Corman, - // C. E. Leiserson, and R. L. Rivest, "Introduction to Algorithms" - // 1990, MIT, chapter 14. - // - // = Description - // A number of Changes have been made to this class template - // in order to conform to the ACE_Hash_Map_Manager_Ex - // interface. All previously supported public methods are - // still part of this class. However, these are marked as - // DEPRECATED and will be removed from this class in - // a future version of ACE. Please migrate your code - // to the appropriate public methods indicated in the - // method deprecation comments. - // - // This class uses an <ACE_Allocator> to allocate memory. The - // user can make this a persistent class by providing an - // <ACE_Allocator> with a persistable memory pool. public: friend class ACE_RB_Tree_Iterator_Base<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK>; @@ -160,537 +160,603 @@ public: // = Initialization and termination methods. + /// Constructor. ACE_RB_Tree (ACE_Allocator *alloc = 0); - // Constructor. + /// Copy constructor. ACE_RB_Tree (const ACE_RB_Tree<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> &rbt); - // Copy constructor. + /// Initialize an RB Tree. int open (ACE_Allocator *alloc = 0); - // Initialize an RB Tree. + /// Close down an RB_Tree and release dynamically allocated + /// resources. int close (void); - // Close down an RB_Tree and release dynamically allocated - // resources. + /// Destructor. virtual ~ACE_RB_Tree (void); - // Destructor. // = insertion, removal, and search methods. + /** + * Associate <ext_id> with <int_id>. If <ext_id> is already in the + * tree then the <ACE_RB_Tree_Node> is not changed. Returns 0 if a + * new entry is bound successfully, returns 1 if an attempt is made + * to bind an existing entry, and returns -1 if failures occur. + */ int bind (const EXT_ID &item, const INT_ID &int_id); - // Associate <ext_id> with <int_id>. If <ext_id> is already in the - // tree then the <ACE_RB_Tree_Node> is not changed. Returns 0 if a - // new entry is bound successfully, returns 1 if an attempt is made - // to bind an existing entry, and returns -1 if failures occur. + /** + * Same as a normal bind, except the tree entry is also passed back + * to the caller. The entry in this case will either be the newly + * created entry, or the existing one. + */ int bind (const EXT_ID &ext_id, const INT_ID &int_id, ACE_RB_Tree_Node<EXT_ID, INT_ID> *&entry); - // Same as a normal bind, except the tree entry is also passed back - // to the caller. The entry in this case will either be the newly - // created entry, or the existing one. + /** + * Associate <ext_id> with <int_id> if and only if <ext_id> is not + * in the tree. If <ext_id> is already in the tree then the <int_id> + * parameter is assigned the existing value in the tree. Returns 0 + * if a new entry is bound successfully, returns 1 if an attempt is + * made to bind an existing entry, and returns -1 if failures occur. + */ int trybind (const EXT_ID &ext_id, INT_ID &int_id); - // Associate <ext_id> with <int_id> if and only if <ext_id> is not - // in the tree. If <ext_id> is already in the tree then the <int_id> - // parameter is assigned the existing value in the tree. Returns 0 - // if a new entry is bound successfully, returns 1 if an attempt is - // made to bind an existing entry, and returns -1 if failures occur. + /** + * Same as a normal trybind, except the tree entry is also passed + * back to the caller. The entry in this case will either be the + * newly created entry, or the existing one. + */ int trybind (const EXT_ID &ext_id, INT_ID &int_id, ACE_RB_Tree_Node<EXT_ID, INT_ID> *&entry); - // Same as a normal trybind, except the tree entry is also passed - // back to the caller. The entry in this case will either be the - // newly created entry, or the existing one. + /** + * Reassociate <ext_id> with <int_id>. If <ext_id> is not in the + * tree then behaves just like <bind>. Returns 0 if a new entry is + * bound successfully, returns 1 if an existing entry was rebound, + * and returns -1 if failures occur. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id); - // Reassociate <ext_id> with <int_id>. If <ext_id> is not in the - // tree then behaves just like <bind>. Returns 0 if a new entry is - // bound successfully, returns 1 if an existing entry was rebound, - // and returns -1 if failures occur. + /** + * Same as a normal rebind, except the tree entry is also passed back + * to the caller. The entry in this case will either be the newly + * created entry, or the existing one. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, ACE_RB_Tree_Node<EXT_ID, INT_ID> *&entry); - // Same as a normal rebind, except the tree entry is also passed back - // to the caller. The entry in this case will either be the newly - // created entry, or the existing one. + /** + * Associate <ext_id> with <int_id>. If <ext_id> is not in the tree + * then behaves just like <bind>. Otherwise, store the old value of + * <int_id> into the "out" parameter and rebind the new parameters. + * Returns 0 if a new entry is bound successfully, returns 1 if an + * existing entry was rebound, and returns -1 if failures occur. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, INT_ID &old_int_id); - // Associate <ext_id> with <int_id>. If <ext_id> is not in the tree - // then behaves just like <bind>. Otherwise, store the old value of - // <int_id> into the "out" parameter and rebind the new parameters. - // Returns 0 if a new entry is bound successfully, returns 1 if an - // existing entry was rebound, and returns -1 if failures occur. + /** + * Same as a normal rebind, except the tree entry is also passed back + * to the caller. The entry in this case will either be the newly + * created entry, or the existing one. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, INT_ID &old_int_id, ACE_RB_Tree_Node<EXT_ID, INT_ID> *&entry); - // Same as a normal rebind, except the tree entry is also passed back - // to the caller. The entry in this case will either be the newly - // created entry, or the existing one. + /** + * Associate <ext_id> with <int_id>. If <ext_id> is not in the tree + * then behaves just like <bind>. Otherwise, store the old values + * of <ext_id> and <int_id> into the "out" parameters and rebind the + * new parameters. This is very useful if you need to have an + * atomic way of updating <ACE_RB_Tree_Nodes> and you also need + * full control over memory allocation. Returns 0 if a new entry is + * bound successfully, returns 1 if an existing entry was rebound, + * and returns -1 if failures occur. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, EXT_ID &old_ext_id, INT_ID &old_int_id); - // Associate <ext_id> with <int_id>. If <ext_id> is not in the tree - // then behaves just like <bind>. Otherwise, store the old values - // of <ext_id> and <int_id> into the "out" parameters and rebind the - // new parameters. This is very useful if you need to have an - // atomic way of updating <ACE_RB_Tree_Nodes> and you also need - // full control over memory allocation. Returns 0 if a new entry is - // bound successfully, returns 1 if an existing entry was rebound, - // and returns -1 if failures occur. + /** + * Same as a normal rebind, except the tree entry is also passed back + * to the caller. The entry in this case will either be the newly + * created entry, or the existing one. + */ int rebind (const EXT_ID &ext_id, const INT_ID &int_id, EXT_ID &old_ext_id, INT_ID &old_int_id, ACE_RB_Tree_Node<EXT_ID, INT_ID> *&entry); - // Same as a normal rebind, except the tree entry is also passed back - // to the caller. The entry in this case will either be the newly - // created entry, or the existing one. + /// Locate <ext_id> and pass out parameter via <int_id>. If found, + /// return 0, returns -1 if not found. int find (const EXT_ID &ext_id, INT_ID &int_id); - // Locate <ext_id> and pass out parameter via <int_id>. If found, - // return 0, returns -1 if not found. + /// Locate <ext_id> and pass out parameter via <entry>. If found, + /// return 0, returns -1 if not found. int find (const EXT_ID &ext_id, ACE_RB_Tree_Node<EXT_ID, INT_ID> *&entry); - // Locate <ext_id> and pass out parameter via <entry>. If found, - // return 0, returns -1 if not found. + /** + * Unbind (remove) the <ext_id> from the tree. Don't return the + * <int_id> to the caller (this is useful for collections where the + * <int_id>s are *not* dynamically allocated...) + */ int unbind (const EXT_ID &ext_id); - // Unbind (remove) the <ext_id> from the tree. Don't return the - // <int_id> to the caller (this is useful for collections where the - // <int_id>s are *not* dynamically allocated...) + /// Break any association of <ext_id>. Returns the value of <int_id> + /// in case the caller needs to deallocate memory. int unbind (const EXT_ID &ext_id, INT_ID &int_id); - // Break any association of <ext_id>. Returns the value of <int_id> - // in case the caller needs to deallocate memory. + /** + * Remove entry from tree. This method should be used with *extreme* + * caution, and only for optimization purposes. The node being passed + * in had better have been allocated by the tree that is unbinding it. + */ int unbind (ACE_RB_Tree_Node<EXT_ID, INT_ID> *entry); - // Remove entry from tree. This method should be used with *extreme* - // caution, and only for optimization purposes. The node being passed - // in had better have been allocated by the tree that is unbinding it. // = Public helper methods. + /// Returns the current number of nodes in the tree. size_t current_size (void) const; - // Returns the current number of nodes in the tree. + /// Assignment operator. void operator= (const ACE_RB_Tree<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> &rbt); - // Assignment operator. + /// Less than comparison function for keys, using comparison functor. virtual int lessthan (const EXT_ID &k1, const EXT_ID &k2); - // Less than comparison function for keys, using comparison functor. + /** + * Returns a reference to the underlying <ACE_LOCK>. This makes it + * possible to acquire the lock explicitly, which can be useful in + * some cases if you instantiate the <ACE_Atomic_Op> with an + * <ACE_Recursive_Mutex> or <ACE_Process_Mutex>, or if you need to + * guard the state of an iterator. NOTE: the right name would be + * <lock>, but HP/C++ will choke on that! + */ ACE_LOCK &mutex (void); - // Returns a reference to the underlying <ACE_LOCK>. This makes it - // possible to acquire the lock explicitly, which can be useful in - // some cases if you instantiate the <ACE_Atomic_Op> with an - // <ACE_Recursive_Mutex> or <ACE_Process_Mutex>, or if you need to - // guard the state of an iterator. NOTE: the right name would be - // <lock>, but HP/C++ will choke on that! + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL styled iterator factory functions. + /// Return forward iterator positioned at first node in tree. ACE_RB_Tree_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> begin (void); - // Return forward iterator positioned at first node in tree. + /// Return forward iterator positioned at last node in tree. ACE_RB_Tree_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> end (void); - // Return forward iterator positioned at last node in tree. + /// Return reverse iterator positioned at last node in tree. ACE_RB_Tree_Reverse_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> rbegin (void); - // Return reverse iterator positioned at last node in tree. + /// Return reverse iterator positioned at first node in tree. ACE_RB_Tree_Reverse_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> rend (void); - // Return reverse iterator positioned at first node in tree. - - // = DEPRECATED methods. Please migrate your code to use the new methods instead + // = DEPRECATED methods. + // Please migrate your code to use the new methods instead + + /** + * Returns a pointer to the item corresponding to the + * given key, or 0 if it cannot find the key in the tree. + * + * @deprecated signature will change to become + * int find (const EXT_ID &ext_id); which will return + * 0 if the <ext_id> is in the tree, otherwise -1. + */ INT_ID* find (const EXT_ID &k); - // Returns a pointer to the item corresponding to the - // given key, or 0 if it cannot find the key in the tree. - // - // DEPRECATED: signature will change to become - // int find (const EXT_ID &ext_id); which will return - // 0 if the <ext_id> is in the tree, otherwise -1. - - + /** + * Inserts a *copy* of the key and the item into the tree: both the + * key type EXT_ID and the item type INT_ID must have well defined semantics + * for copy construction. The default implementation also requires that + * the key type support well defined < semantics. This method returns a + * pointer to the inserted item copy, or 0 if an error occurred. + * NOTE: if an identical key already exists in the tree, no new item + * is created, and the returned pointer addresses the existing item + * associated with the existing key. + * @deprecated + */ INT_ID* insert (const EXT_ID &k, const INT_ID &t); - // Inserts a *copy* of the key and the item into the tree: both the - // key type EXT_ID and the item type INT_ID must have well defined semantics - // for copy construction. The default implementation also requires that - // the key type support well defined < semantics. This method returns a - // pointer to the inserted item copy, or 0 if an error occurred. - // NOTE: if an identical key already exists in the tree, no new item - // is created, and the returned pointer addresses the existing item - // associated with the existing key. - // DEPRECATED + /** + * Removes the item associated with the given key from the tree and + * destroys it. Returns 1 if it found the item and successfully + * destroyed it, 0 if it did not find the item, or -1 if an error + * occurred. + * @deprecated + */ int remove (const EXT_ID &k); - // Removes the item associated with the given key from the tree and - // destroys it. Returns 1 if it found the item and successfully - // destroyed it, 0 if it did not find the item, or -1 if an error - // occurred. - // DEPRECATED + /// Destroys all nodes and sets the root pointer null. + /// @deprecated void clear (void); - // Destroys all nodes and sets the root pointer null. - // DEPRECATED protected: // = Protected methods. These should only be called with locks held. + /// Method for right rotation of the tree about a given node. void RB_rotate_right (ACE_RB_Tree_Node<EXT_ID, INT_ID> * x); - // Method for right rotation of the tree about a given node. + /// Method for left rotation of the tree about a given node. void RB_rotate_left (ACE_RB_Tree_Node<EXT_ID, INT_ID> * x); - // Method for left rotation of the tree about a given node. + /// Method for restoring Red-Black properties after deletion. void RB_delete_fixup (ACE_RB_Tree_Node<EXT_ID, INT_ID> * x); - // Method for restoring Red-Black properties after deletion. + /// Method to find the successor node of the given node in the tree. ACE_RB_Tree_Node<EXT_ID, INT_ID> * RB_tree_successor (ACE_RB_Tree_Node<EXT_ID, INT_ID> *x) const; - // Method to find the successor node of the given node in the tree. + /// Method to find the predecessor node of the given node in the + /// tree. ACE_RB_Tree_Node<EXT_ID, INT_ID> * RB_tree_predecessor (ACE_RB_Tree_Node<EXT_ID, INT_ID> *x) const; - // Method to find the predecessor node of the given node in the - // tree. + /// Method to find the minimum node of the subtree rooted at the + /// given node. ACE_RB_Tree_Node<EXT_ID, INT_ID> * RB_tree_minimum (ACE_RB_Tree_Node<EXT_ID, INT_ID> *x) const; - // Method to find the minimum node of the subtree rooted at the - // given node. + /// Method to find the maximum node of the subtree rooted at the + /// given node. ACE_RB_Tree_Node<EXT_ID, INT_ID> * RB_tree_maximum (ACE_RB_Tree_Node<EXT_ID, INT_ID> *x) const; - // Method to find the maximum node of the subtree rooted at the - // given node. + /** + * Returns a pointer to a matching node if there is one, a pointer + * to the node under which to insert the item if the tree is not + * empty and there is no such match, or 0 if the tree is empty. + * It stores the result of the search in the result argument: + * LEFT if the node is to the left of the node to be inserted, + * RIGHT if the node is to the right of the node to be inserted, + * or EXACT if an exactly matching node already exists. + */ ACE_RB_Tree_Node<EXT_ID, INT_ID> * find_node (const EXT_ID &k, RB_SearchResult &result); - // Returns a pointer to a matching node if there is one, a pointer - // to the node under which to insert the item if the tree is not - // empty and there is no such match, or 0 if the tree is empty. - // It stores the result of the search in the result argument: - // LEFT if the node is to the left of the node to be inserted, - // RIGHT if the node is to the right of the node to be inserted, - // or EXACT if an exactly matching node already exists. + /// Rebalance the tree after insertion of a node. void RB_rebalance (ACE_RB_Tree_Node<EXT_ID, INT_ID> * x); - // Rebalance the tree after insertion of a node. + /// Close down an RB_Tree. this method should + /// only be called with locks already held. int close_i (void); - // Close down an RB_Tree. this method should - // only be called with locks already held. + /** + * Retrieves a pointer to the item corresponding to the + * given key. Returns 0 for success, or -1 if it cannot find the key + * in the tree. + */ int find_i (const EXT_ID &ext_id, ACE_RB_Tree_Node<EXT_ID, INT_ID>* &entry); - // Retrieves a pointer to the item corresponding to the - // given key. Returns 0 for success, or -1 if it cannot find the key - // in the tree. + /** + * Inserts a *copy* of the key and the item into the tree: both the + * key type EXT_ID and the item type INT_ID must have well defined semantics + * for copy construction. The default implementation also requires that + * the key type support well defined < semantics. This method returns a + * pointer to the inserted item copy, or 0 if an error occurred. + * NOTE: if an identical key already exists in the tree, no new item + * is created, and the returned pointer addresses the existing item + * associated with the existing key. + */ INT_ID* insert_i (const EXT_ID &k, const INT_ID &t); - // Inserts a *copy* of the key and the item into the tree: both the - // key type EXT_ID and the item type INT_ID must have well defined semantics - // for copy construction. The default implementation also requires that - // the key type support well defined < semantics. This method returns a - // pointer to the inserted item copy, or 0 if an error occurred. - // NOTE: if an identical key already exists in the tree, no new item - // is created, and the returned pointer addresses the existing item - // associated with the existing key. + /** + * Inserts a *copy* of the key and the item into the tree: both the + * key type EXT_ID and the item type INT_ID must have well defined semantics + * for copy construction. The default implementation also requires that + * the key type support well defined < semantics. This method passes back + * a pointer to the inserted (or existing) node, and the search status. If + * the node already exists, the method returns 1. If the node does not + * exist, and a new one is successfully created, and the method returns 0. + * If there was an error, the method returns -1. + */ int insert_i (const EXT_ID &k, const INT_ID &t, ACE_RB_Tree_Node<EXT_ID, INT_ID> *&entry); - // Inserts a *copy* of the key and the item into the tree: both the - // key type EXT_ID and the item type INT_ID must have well defined semantics - // for copy construction. The default implementation also requires that - // the key type support well defined < semantics. This method passes back - // a pointer to the inserted (or existing) node, and the search status. If - // the node already exists, the method returns 1. If the node does not - // exist, and a new one is successfully created, and the method returns 0. - // If there was an error, the method returns -1. + /** + * Removes the item associated with the given key from the tree and + * destroys it. Returns 1 if it found the item and successfully + * destroyed it, 0 if it did not find the item, or -1 if an error + * occurred. Returns the stored internal id in the second argument. + */ int remove_i (const EXT_ID &k, INT_ID &i); - // Removes the item associated with the given key from the tree and - // destroys it. Returns 1 if it found the item and successfully - // destroyed it, 0 if it did not find the item, or -1 if an error - // occurred. Returns the stored internal id in the second argument. + /// Removes the item associated with the given key from the tree and + /// destroys it. int remove_i (ACE_RB_Tree_Node<EXT_ID, INT_ID> *z); - // Removes the item associated with the given key from the tree and - // destroys it. private: // = Private members. + /// Pointer to a memory allocator. ACE_Allocator *allocator_; - // Pointer to a memory allocator. + /// Synchronization variable for the MT_SAFE <ACE_RB_Tree>. ACE_LOCK lock_; - // Synchronization variable for the MT_SAFE <ACE_RB_Tree>. + /// The root of the tree. ACE_RB_Tree_Node<EXT_ID, INT_ID> *root_; - // The root of the tree. + /// Comparison functor for comparing nodes in the tree. COMPARE_KEYS compare_keys_; - // Comparison functor for comparing nodes in the tree. + /// The current number of nodes in the tree. size_t current_size_; - // The current number of nodes in the tree. }; +/** + * @class ACE_RB_Tree_Iterator_Base + * + * @brief Implements a common base class for iterators for a Red-Black Tree ADT. + */ template <class EXT_ID, class INT_ID, class COMPARE_KEYS, class ACE_LOCK> class ACE_RB_Tree_Iterator_Base { - // = TITLE - // Implements a common base class for iterators for a Red-Black Tree ADT. public: + /// Assignment operator: copies both the tree reference and the position in the tree. void operator= (const ACE_RB_Tree_Iterator_Base<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> &iter); - // Assignment operator: copies both the tree reference and the position in the tree. // = Iteration methods. + /// Returns 1 when the iteration has completed, otherwise 0. int done (void) const; - // Returns 1 when the iteration has completed, otherwise 0. + /// STL-like iterator dereference operator: returns a reference + /// to the node underneath the iterator. ACE_RB_Tree_Node<EXT_ID, INT_ID> & operator* (void) const; - // STL-like iterator dereference operator: returns a reference - // to the node underneath the iterator. + /// Returns a const reference to the tree over which we're iterating. const ACE_RB_Tree<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> &tree (void); - // Returns a const reference to the tree over which we're iterating. + /// Comparison operator: returns 1 if both iterators point to the same position, otherwise 0. int operator== (const ACE_RB_Tree_Iterator_Base<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> &) const; - // Comparison operator: returns 1 if both iterators point to the same position, otherwise 0. + /// Comparison operator: returns 1 if the iterators point to different positions, otherwise 0. int operator!= (const ACE_RB_Tree_Iterator_Base<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> &) const; - // Comparison operator: returns 1 if the iterators point to different positions, otherwise 0. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Initialization and termination methods. + /// Create the singular iterator. No valid iterator can be equal to + /// it, it is illegal to dereference a singular iterator, etc. etc. ACE_RB_Tree_Iterator_Base (void); - // Create the singular iterator. No valid iterator can be equal to - // it, it is illegal to dereference a singular iterator, etc. etc. + /** + * Constructor. Takes an ACE_RB_Tree over which to iterate, and + * an integer indicating (if non-zero) to position the iterator + * at the first element in the tree (if this integer is 0, the + * iterator is positioned at the last element in the tree). + */ ACE_RB_Tree_Iterator_Base (const ACE_RB_Tree<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> &tree, int set_first); - // Constructor. Takes an ACE_RB_Tree over which to iterate, and - // an integer indicating (if non-zero) to position the iterator - // at the first element in the tree (if this integer is 0, the - // iterator is positioned at the last element in the tree). + /// Copy constructor. ACE_RB_Tree_Iterator_Base (const ACE_RB_Tree_Iterator_Base<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> &iter); - // Copy constructor. + /// Destructor. ~ACE_RB_Tree_Iterator_Base (void); - // Destructor. // = Internal methods + /// Move forward by one element in the tree. Returns 0 when + /// there are no more elements in the tree, otherwise 1. int forward_i (void); - // Move forward by one element in the tree. Returns 0 when - // there are no more elements in the tree, otherwise 1. + /// Move back by one element in the tree. Returns 0 when + /// there are no more elements in the tree, otherwise 1. int reverse_i (void); - // Move back by one element in the tree. Returns 0 when - // there are no more elements in the tree, otherwise 1. + /// Dump the state of an object. void dump_i (void) const; - // Dump the state of an object. // = Protected members. + /// Reference to the ACE_RB_Tree over which we're iterating. const ACE_RB_Tree<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> *tree_; - // Reference to the ACE_RB_Tree over which we're iterating. + /// Pointer to the node currently under the iterator. ACE_RB_Tree_Node <EXT_ID, INT_ID> *node_; - // Pointer to the node currently under the iterator. }; +/** + * @class ACE_RB_Tree_Iterator + * + * @brief Implements an iterator for a Red-Black Tree ADT. + */ template <class EXT_ID, class INT_ID, class COMPARE_KEYS, class ACE_LOCK> class ACE_RB_Tree_Iterator : public ACE_RB_Tree_Iterator_Base<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> { - // = TITLE - // Implements an iterator for a Red-Black Tree ADT. public: // = Initialization and termination methods. + /** + * Create the singular iterator. + * It is illegal to deference the iterator, no valid iterator is + * equal to a singular iterator, etc. etc. + */ ACE_RB_Tree_Iterator (void); - // Create the singular iterator. - // It is illegal to deference the iterator, no valid iterator is - // equal to a singular iterator, etc. etc. + /** + * Constructor. Takes an ACE_RB_Tree over which to iterate, and + * an integer indicating (if non-zero) to position the iterator + * at the first element in the tree (if this integer is 0, the + * iterator is positioned at the last element in the tree). + */ ACE_RB_Tree_Iterator (const ACE_RB_Tree<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> &tree, int set_first = 1); - // Constructor. Takes an ACE_RB_Tree over which to iterate, and - // an integer indicating (if non-zero) to position the iterator - // at the first element in the tree (if this integer is 0, the - // iterator is positioned at the last element in the tree). + /// Destructor. ~ACE_RB_Tree_Iterator (void); - // Destructor. // = ACE-style iteration methods. + /// Move forward by one element in the tree. Returns + /// 0 when all elements have been seen, else 1. int advance (void); - // Move forward by one element in the tree. Returns - // 0 when all elements have been seen, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL-style iteration methods. + /// Prefix advance. ACE_RB_Tree_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> & operator++ (void); - // Prefix advance. + /// Postfix advance. ACE_RB_Tree_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> operator++ (int); - // Postfix advance. + /// Prefix reverse. ACE_RB_Tree_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> & operator-- (void); - // Prefix reverse. + /// Postfix reverse. ACE_RB_Tree_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> operator-- (int); - // Postfix reverse. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /** + * Passes back the <entry> under the iterator. Returns 0 if + * the iteration has completed, otherwise 1. This method must + * be declared and defined in both the derived forward and + * reverse iterator classes rather than in the base iterator + * class because of a method signature resolution problem + * caused by the existence of the deprecated next (void) + * method in the derived forward iterator class. When that + * deprecated method is removed, this method should be removed + * from the derived classes and placed in the base class. + */ int next (ACE_RB_Tree_Node<EXT_ID, INT_ID> *&next_entry) const; - // Passes back the <entry> under the iterator. Returns 0 if - // the iteration has completed, otherwise 1. This method must - // be declared and defined in both the derived forward and - // reverse iterator classes rather than in the base iterator - // class because of a method signature resolution problem - // caused by the existence of the deprecated next (void) - // method in the derived forward iterator class. When that - // deprecated method is removed, this method should be removed - // from the derived classes and placed in the base class. // = DEPRECATED methods. Please migrate your code to use the new methods instead + /// Accessor for key of node under iterator (if any). + /// DEPRECATED EXT_ID *key (void); - // Accessor for key of node under iterator (if any). - // DEPRECATED + /// Accessor for item of node under iterator (if any). + /// DEPRECATED INT_ID *item (void); - // Accessor for item of node under iterator (if any). - // DEPRECATED + /// Move to the first item in the iteration (and in the tree). + /// DEPRECATED int first (void); - // Move to the first item in the iteration (and in the tree). - // DEPRECATED + /// Move to the last item in the iteration (and in the tree). + /// DEPRECATED int last (void); - // Move to the last item in the iteration (and in the tree). - // DEPRECATED + /// Move to the next item in the iteration (and in the tree). + /// DEPRECATED int next (void); - // Move to the next item in the iteration (and in the tree). - // DEPRECATED + /// Move to the previous item in the iteration (and in the tree). + /// DEPRECATED int previous (void); - // Move to the previous item in the iteration (and in the tree). - // DEPRECATED + /** + * Returns 0 if the iterator is positioned over a valid ACE_RB_Tree + * node, returns 1 if not. + * DEPRECATED: use the base class <done> method instead. + */ int is_done (void); - // Returns 0 if the iterator is positioned over a valid ACE_RB_Tree - // node, returns 1 if not. - // DEPRECATED: use the base class <done> method instead. }; +/** + * @class ACE_RB_Tree_Reverse_Iterator + * + * @brief Implements a reverse iterator for a Red-Black Tree ADT. + */ template <class EXT_ID, class INT_ID, class COMPARE_KEYS, class ACE_LOCK> class ACE_RB_Tree_Reverse_Iterator : public ACE_RB_Tree_Iterator_Base<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> { - // = TITLE - // Implements a reverse iterator for a Red-Black Tree ADT. public: // = Initialization and termination methods. + /** + * Create the singular iterator. + * It is illegal to deference the iterator, no valid iterator is + * equal to a singular iterator, etc. etc. + */ ACE_RB_Tree_Reverse_Iterator (void); - // Create the singular iterator. - // It is illegal to deference the iterator, no valid iterator is - // equal to a singular iterator, etc. etc. + /** + * Constructor. Takes an ACE_RB_Tree over which to iterate, and + * an integer indicating (if non-zero) to position the iterator + * at the last element in the tree (if this integer is 0, the + * iterator is positioned at the first element in the tree). + */ ACE_RB_Tree_Reverse_Iterator (const ACE_RB_Tree<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> &tree, int set_last = 1); - // Constructor. Takes an ACE_RB_Tree over which to iterate, and - // an integer indicating (if non-zero) to position the iterator - // at the last element in the tree (if this integer is 0, the - // iterator is positioned at the first element in the tree). + /// Destructor. ~ACE_RB_Tree_Reverse_Iterator (void); - // Destructor. // = ACE-style iteration methods. + /// Move forward by one element in the tree. Returns + /// 0 when all elements have been seen, else 1. int advance (void); - // Move forward by one element in the tree. Returns - // 0 when all elements have been seen, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL-style iteration methods. + /// Prefix advance. ACE_RB_Tree_Reverse_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> & operator++ (void); - // Prefix advance. + /// Postfix advance. ACE_RB_Tree_Reverse_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> operator++ (int); - // Postfix advance. + /// Prefix reverse. ACE_RB_Tree_Reverse_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> & operator-- (void); - // Prefix reverse. + /// Postfix reverse. ACE_RB_Tree_Reverse_Iterator<EXT_ID, INT_ID, COMPARE_KEYS, ACE_LOCK> operator-- (int); - // Postfix reverse. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /** + * Passes back the <entry> under the iterator. Returns 0 if + * the iteration has completed, otherwise 1. This method must + * be declared and defined in both the derived forward and + * reverse iterator classes rather than in the base iterator + * class because of a method signature resolution problem + * caused by the existence of the deprecated next (void) + * method in the derived forward iterator class. When that + * deprecated method is removed, this method should be removed + * from the derived classes and placed in the base class. + */ int next (ACE_RB_Tree_Node<EXT_ID, INT_ID> *&next_entry) const; - // Passes back the <entry> under the iterator. Returns 0 if - // the iteration has completed, otherwise 1. This method must - // be declared and defined in both the derived forward and - // reverse iterator classes rather than in the base iterator - // class because of a method signature resolution problem - // caused by the existence of the deprecated next (void) - // method in the derived forward iterator class. When that - // deprecated method is removed, this method should be removed - // from the derived classes and placed in the base class. }; diff --git a/ace/RW_Process_Mutex.h b/ace/RW_Process_Mutex.h index 51e1dbf6c75..266938dab4f 100644 --- a/ace/RW_Process_Mutex.h +++ b/ace/RW_Process_Mutex.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// RW_Process_Mutex.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file RW_Process_Mutex.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_RW_PROCESS_MUTEX_H #define ACE_RW_PROCESS_MUTEX_H @@ -24,73 +21,83 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_RW_Process_Mutex + * + * @brief Wrapper for readers/writer locks that exist across processes. + * + * Note that because this class uses the + * <ACE_File_Lock> as its implementation it only can be reliably + * used between separate processes, rather than threads in the + * same process. This isn't a limitation of ACE, it's simply + * the file lock semantics on UNIX and Win32. + */ class ACE_Export ACE_RW_Process_Mutex { - // = TITLE - // Wrapper for readers/writer locks that exist across processes. - // - // = DESCRIPTION - // Note that because this class uses the - // <ACE_File_Lock> as its implementation it only can be reliably - // used between separate processes, rather than threads in the - // same process. This isn't a limitation of ACE, it's simply - // the file lock semantics on UNIX and Win32. public: + /// Create a readers/writer <Process_Mutex>, passing in the optional + /// <name>. ACE_RW_Process_Mutex (const ACE_TCHAR *name = 0, int flags = O_CREAT|O_RDWR); - // Create a readers/writer <Process_Mutex>, passing in the optional - // <name>. ~ACE_RW_Process_Mutex (void); + /** + * Explicitly destroy the mutex. Note that only one thread should + * call this method since it doesn't protect against race + * conditions. + */ int remove (void); - // Explicitly destroy the mutex. Note that only one thread should - // call this method since it doesn't protect against race - // conditions. + /// Acquire lock ownership (wait on queue if necessary). int acquire (void); - // Acquire lock ownership (wait on queue if necessary). + /** + * Conditionally acquire lock (i.e., don't wait on queue). Returns + * -1 on failure. If we "failed" because someone else already had + * the lock, <errno> is set to <EBUSY>. + */ int tryacquire (void); - // Conditionally acquire lock (i.e., don't wait on queue). Returns - // -1 on failure. If we "failed" because someone else already had - // the lock, <errno> is set to <EBUSY>. + /// Release lock and unblock a thread at head of queue. int release (void); - // Release lock and unblock a thread at head of queue. + /// Acquire lock ownership (wait on queue if necessary). int acquire_read (void); - // Acquire lock ownership (wait on queue if necessary). + /// Acquire lock ownership (wait on queue if necessary). int acquire_write (void); - // Acquire lock ownership (wait on queue if necessary). + /** + * Conditionally acquire a lock (i.e., won't block). Returns -1 on + * failure. If we "failed" because someone else already had the + * lock, <errno> is set to <EBUSY>. + */ int tryacquire_read (void); - // Conditionally acquire a lock (i.e., won't block). Returns -1 on - // failure. If we "failed" because someone else already had the - // lock, <errno> is set to <EBUSY>. + /** + * Conditionally acquire a lock (i.e., won't block). Returns -1 on + * failure. If we "failed" because someone else already had the + * lock, <errno> is set to <EBUSY>. + */ int tryacquire_write (void); - // Conditionally acquire a lock (i.e., won't block). Returns -1 on - // failure. If we "failed" because someone else already had the - // lock, <errno> is set to <EBUSY>. + /// Attempt to upgrade a read lock to a write lock. Returns 0 on + /// success, -1 on failure. int tryacquire_write_upgrade (void); - // Attempt to upgrade a read lock to a write lock. Returns 0 on - // success, -1 on failure. + /// Return the underlying lock. const ACE_File_Lock &lock (void) const; - // Return the underlying lock. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// We need this to get the readers/writer semantics... ACE_File_Lock lock_; - // We need this to get the readers/writer semantics... }; #if defined (__ACE_INLINE__) diff --git a/ace/Reactor.h b/ace/Reactor.h index 0462732b0e3..aad4856882e 100644 --- a/ace/Reactor.h +++ b/ace/Reactor.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Reactor.h -// -// = AUTHOR -// Irfan Pyarali -// -// ============================================================================ + +//============================================================================= +/** + * @file Reactor.h + * + * $Id$ + * + * @author Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_REACTOR_H #define ACE_REACTOR_H @@ -40,528 +37,597 @@ class ACE_Reactor_Impl; // forward declaration will be useful here #include "ace/Signal.h" +/** + * @class ACE_Reactor + * + * @brief The resposiblility of this class is to forward all methods to + * its delegation/implementation class, e.g., + * <ACE_Select_Reactor> or <ACE_WFMO_Reactor>. + */ class ACE_Export ACE_Reactor { - // = TITLE - // The resposiblility of this class is to forward all methods to - // its delegation/implementation class, e.g., - // <ACE_Select_Reactor> or <ACE_WFMO_Reactor>. public: + /// Operations on the "ready" mask and the "dispatch" mask. enum { - // = Operations on the "ready" mask and the "dispatch" mask. + /// Retrieve current value of the the "ready" mask or the + /// "dispatch" mask. GET_MASK = 1, - // Retrieve current value of the the "ready" mask or the - // "dispatch" mask. + /// Set value of bits to new mask (changes the entire mask). SET_MASK = 2, - // Set value of bits to new mask (changes the entire mask). + /// Bitwise "or" the value into the mask (only changes enabled + /// bits). ADD_MASK = 3, - // Bitwise "or" the value into the mask (only changes enabled - // bits). + /// Bitwise "and" the negation of the value out of the mask (only + /// changes enabled bits). CLR_MASK = 4 - // Bitwise "and" the negation of the value out of the mask (only - // changes enabled bits). }; + /** + * You can add a hook to various run_event methods and the hook will + * be called after handling every reactor event. If this function + * returns 0, run_reactor_event_loop will check for the return value of + * handle_event. If it is -1, the the run_reactor_event_loop will return + * (pre-maturely.) + */ typedef int (*REACTOR_EVENT_HOOK)(void*); - // You can add a hook to various run_event methods and the hook will - // be called after handling every reactor event. If this function - // returns 0, run_reactor_event_loop will check for the return value of - // handle_event. If it is -1, the the run_reactor_event_loop will return - // (pre-maturely.) + /// Get pointer to a process-wide <ACE_Reactor>. static ACE_Reactor *instance (void); - // Get pointer to a process-wide <ACE_Reactor>. + /** + * Set pointer to a process-wide <ACE_Reactor> and return existing + * pointer. If <delete_reactor> != 0 then we'll delete the Reactor + * at destruction time. + */ static ACE_Reactor *instance (ACE_Reactor *, int delete_reactor = 0); - // Set pointer to a process-wide <ACE_Reactor> and return existing - // pointer. If <delete_reactor> != 0 then we'll delete the Reactor - // at destruction time. + /// Delete the dynamically allocated Singleton static void close_singleton (void); - // Delete the dynamically allocated Singleton // = Singleton reactor event loop management methods. // Note that these method ONLY work on the "Singleton Reactor," // i.e., the one returned from <ACE_Reactor::instance>. + /** + * Run the event loop until the + * <ACE_Reactor::handle_events/ACE_Reactor::alertable_handle_events> + * method returns -1 or the <end_event_loop> method is invoked. + * Note that this method can only be used by the singleton + * <ACE_Reactor::instance>. Thus, to run another reactor use + * <ACE_Reactor::run_reactor_event_loop>. + */ static int run_event_loop (void); static int run_alertable_event_loop (void); - // Run the event loop until the - // <ACE_Reactor::handle_events/ACE_Reactor::alertable_handle_events> - // method returns -1 or the <end_event_loop> method is invoked. - // Note that this method can only be used by the singleton - // <ACE_Reactor::instance>. Thus, to run another reactor use - // <ACE_Reactor::run_reactor_event_loop>. + /** + * Run the event loop until the <ACE_Reactor::handle_events> or + * <ACE_Reactor::alertable_handle_events> methods returns -1, the + * <end_event_loop> method is invoked, or the <ACE_Time_Value> + * expires. Note that this method can only be used by the singleton + * <ACE_Reactor::instance>. Thus, to run another reactor use + * <ACE_Reactor::run_reactor_event_loop>. + */ static int run_event_loop (ACE_Time_Value &tv); static int run_alertable_event_loop (ACE_Time_Value &tv); - // Run the event loop until the <ACE_Reactor::handle_events> or - // <ACE_Reactor::alertable_handle_events> methods returns -1, the - // <end_event_loop> method is invoked, or the <ACE_Time_Value> - // expires. Note that this method can only be used by the singleton - // <ACE_Reactor::instance>. Thus, to run another reactor use - // <ACE_Reactor::run_reactor_event_loop>. + /** + * Instruct the <ACE_Reactor::instance> to terminate its event loop + * and notifies the <ACE_Reactor::instance> so that it can wake up + * and close down gracefully. Note that this method can only be + * used by the singleton <ACE_Reactor::instance>. Thus, to + * terminate another reactor, use + * <ACE_Reactor::end_reactor_event_loop>. + */ static int end_event_loop (void); - // Instruct the <ACE_Reactor::instance> to terminate its event loop - // and notifies the <ACE_Reactor::instance> so that it can wake up - // and close down gracefully. Note that this method can only be - // used by the singleton <ACE_Reactor::instance>. Thus, to - // terminate another reactor, use - // <ACE_Reactor::end_reactor_event_loop>. + /** + * Report if the <ACE_Reactor::instance>'s event loop is finished. + * Note that this method can only be used by the singleton + * <ACE_Reactor::instance>. Thus, to check another reactor use + * <ACE_Reactor::reactor_event_loop_done>. + */ static int event_loop_done (void); - // Report if the <ACE_Reactor::instance>'s event loop is finished. - // Note that this method can only be used by the singleton - // <ACE_Reactor::instance>. Thus, to check another reactor use - // <ACE_Reactor::reactor_event_loop_done>. + /** + * Resets the <ACE_Reactor::end_event_loop_> static so that the + * <run_event_loop> method can be restarted. Note that this method + * can only be used by the singleton <ACE_Reactor::instance>. Thus, + * to reset another reactor use + * <ACE_Reactor::reset_reactor_event_loop>. + */ static void reset_event_loop (void); - // Resets the <ACE_Reactor::end_event_loop_> static so that the - // <run_event_loop> method can be restarted. Note that this method - // can only be used by the singleton <ACE_Reactor::instance>. Thus, - // to reset another reactor use - // <ACE_Reactor::reset_reactor_event_loop>. + /** + * The singleton reactor is used by the <ACE_Service_Config>. + * Therefore, we must check for the reconfiguration request and + * handle it after handling an event. + */ static int check_reconfiguration (void *); - // The singleton reactor is used by the <ACE_Service_Config>. - // Therefore, we must check for the reconfiguration request and - // handle it after handling an event. // = Reactor event loop management methods. // These methods work with an instance of a reactor. + /** + * Run the event loop until the + * <ACE_Reactor::handle_events/ACE_Reactor::alertable_handle_events> + * method returns -1 or the <end_event_loop> method is invoked. + */ virtual int run_reactor_event_loop (REACTOR_EVENT_HOOK = 0); virtual int run_alertable_reactor_event_loop (REACTOR_EVENT_HOOK = 0); - // Run the event loop until the - // <ACE_Reactor::handle_events/ACE_Reactor::alertable_handle_events> - // method returns -1 or the <end_event_loop> method is invoked. + /** + * Run the event loop until the <ACE_Reactor::handle_events> or + * <ACE_Reactor::alertable_handle_events> methods returns -1, the + * <end_event_loop> method is invoked, or the <ACE_Time_Value> + * expires. + */ virtual int run_reactor_event_loop (ACE_Time_Value &tv, REACTOR_EVENT_HOOK = 0); virtual int run_alertable_reactor_event_loop (ACE_Time_Value &tv, REACTOR_EVENT_HOOK = 0); - // Run the event loop until the <ACE_Reactor::handle_events> or - // <ACE_Reactor::alertable_handle_events> methods returns -1, the - // <end_event_loop> method is invoked, or the <ACE_Time_Value> - // expires. + /** + * Instruct the <ACE_Reactor::instance> to terminate its event loop + * and notifies the <ACE_Reactor::instance> so that it can wake up + * and close down gracefully. + */ virtual int end_reactor_event_loop (void); - // Instruct the <ACE_Reactor::instance> to terminate its event loop - // and notifies the <ACE_Reactor::instance> so that it can wake up - // and close down gracefully. + /// Report if the <ACE_Reactor::instance>'s event loop is finished. virtual int reactor_event_loop_done (void); - // Report if the <ACE_Reactor::instance>'s event loop is finished. + /// Resets the <ACE_Reactor::end_event_loop_> static so that the + /// <run_event_loop> method can be restarted. virtual void reset_reactor_event_loop (void); - // Resets the <ACE_Reactor::end_event_loop_> static so that the - // <run_event_loop> method can be restarted. + /** + * Create the Reactor using <implementation>. The flag + * <delete_implementation> tells the Reactor whether or not to + * delete the <implementation> on destruction. + */ ACE_Reactor (ACE_Reactor_Impl *implementation = 0, int delete_implementation = 0); - // Create the Reactor using <implementation>. The flag - // <delete_implementation> tells the Reactor whether or not to - // delete the <implementation> on destruction. + /// Close down and release all resources. virtual ~ACE_Reactor (void); - // Close down and release all resources. + /** + * Initialize the <ACE_Reactor> to manage <max_number_of_handles>. + * If <restart> is non-0 then the <ACE_Reactor>'s <handle_events> + * method will be restarted automatically when <EINTR> occurs. If + * <signal_handler> or <timer_queue> are non-0 they are used as the + * signal handler and timer queue, respectively. + */ virtual int open (size_t max_number_of_handles, int restart = 0, ACE_Sig_Handler *signal_handler = 0, ACE_Timer_Queue *timer_queue = 0); - // Initialize the <ACE_Reactor> to manage <max_number_of_handles>. - // If <restart> is non-0 then the <ACE_Reactor>'s <handle_events> - // method will be restarted automatically when <EINTR> occurs. If - // <signal_handler> or <timer_queue> are non-0 they are used as the - // signal handler and timer queue, respectively. + /// Use a user specified signal handler instead. virtual int set_sig_handler (ACE_Sig_Handler *signal_handler); - // Use a user specified signal handler instead. // = The following method is deprecated. Use <timer_queue> instead. + /// Set a user specified timer queue. virtual int set_timer_queue (ACE_Timer_Queue *tq); - // Set a user specified timer queue. + /// Set a user-specified timer queue. + /// Return the current <ACE_Timer_Queue>. virtual int timer_queue (ACE_Timer_Queue *tq); - // Set a user-specified timer queue. virtual ACE_Timer_Queue *timer_queue (void) const; - // Return the current <ACE_Timer_Queue>. + /// Close down and release all resources. virtual int close (void); - // Close down and release all resources. // = Event loop drivers. + /** + * Returns non-zero if there are I/O events "ready" for dispatching, + * but does not actually dispatch the event handlers. By default, + * don't block while checking this, i.e., "poll". + */ virtual int work_pending (const ACE_Time_Value &max_wait_time = ACE_Time_Value::zero); - // Returns non-zero if there are I/O events "ready" for dispatching, - // but does not actually dispatch the event handlers. By default, - // don't block while checking this, i.e., "poll". + /** + * This event loop driver blocks for up to <max_wait_time> before + * returning. It will return earlier if events occur. Note that + * <max_wait_time> can be 0, in which case this method blocks + * indefinitely until events occur. + * + * <max_wait_time> is decremented to reflect how much time this call + * took. For instance, if a time value of 3 seconds is passed to + * handle_events and an event occurs after 2 seconds, + * <max_wait_time> will equal 1 second. This can be used if an + * application wishes to handle events for some fixed amount of + * time. + * + * Returns the total number of timers and I/O <ACE_Event_Handler>s + * that were dispatched, 0 if the <max_wait_time> elapsed without + * dispatching any handlers, or -1 if an error occurs. + * + * The only difference between <alertable_handle_events> and + * <handle_events> is that in the alertable case, the eventloop will + * return when the system queues an I/O completion routine or an + * Asynchronous Procedure Call. + */ virtual int handle_events (ACE_Time_Value *max_wait_time = 0); virtual int alertable_handle_events (ACE_Time_Value *max_wait_time = 0); - // This event loop driver blocks for up to <max_wait_time> before - // returning. It will return earlier if events occur. Note that - // <max_wait_time> can be 0, in which case this method blocks - // indefinitely until events occur. - // - // <max_wait_time> is decremented to reflect how much time this call - // took. For instance, if a time value of 3 seconds is passed to - // handle_events and an event occurs after 2 seconds, - // <max_wait_time> will equal 1 second. This can be used if an - // application wishes to handle events for some fixed amount of - // time. - // - // Returns the total number of timers and I/O <ACE_Event_Handler>s - // that were dispatched, 0 if the <max_wait_time> elapsed without - // dispatching any handlers, or -1 if an error occurs. - // - // The only difference between <alertable_handle_events> and - // <handle_events> is that in the alertable case, the eventloop will - // return when the system queues an I/O completion routine or an - // Asynchronous Procedure Call. + /** + * This method is just like the one above, except the + * <max_wait_time> value is a reference and can therefore never be + * NULL. + * + * The only difference between <alertable_handle_events> and + * <handle_events> is that in the alertable case, the eventloop will + * return when the system queues an I/O completion routine or an + * Asynchronous Procedure Call. + */ virtual int handle_events (ACE_Time_Value &max_wait_time); virtual int alertable_handle_events (ACE_Time_Value &max_wait_time); - // This method is just like the one above, except the - // <max_wait_time> value is a reference and can therefore never be - // NULL. - // - // The only difference between <alertable_handle_events> and - // <handle_events> is that in the alertable case, the eventloop will - // return when the system queues an I/O completion routine or an - // Asynchronous Procedure Call. // = Register and remove Handlers. + /// Register <event_handler> with <mask>. The I/O handle will always + /// come from <get_handle> on the <event_handler>. virtual int register_handler (ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // Register <event_handler> with <mask>. The I/O handle will always - // come from <get_handle> on the <event_handler>. + /// Register <event_handler> with <mask>. The I/O handle is provided + /// through the <io_handle> parameter. virtual int register_handler (ACE_HANDLE io_handle, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // Register <event_handler> with <mask>. The I/O handle is provided - // through the <io_handle> parameter. #if defined (ACE_WIN32) + /** + * Register an <event_handler> that will be notified when + * <event_handle> is signaled. Since no event mask is passed + * through this interface, it is assumed that the <event_handle> + * being passed in is an event handle and not an I/O handle. + * + * Originally this interface was available for all platforms, but + * because ACE_HANDLE is an int on non-Win32 platforms, compilers + * are not able to tell the difference between + * register_handler(ACE_Event_Handler*,ACE_Reactor_Mask) and + * register_handler(ACE_Event_Handler*,ACE_HANDLE). Therefore, we + * have restricted this method to Win32 only. + */ virtual int register_handler (ACE_Event_Handler *event_handler, ACE_HANDLE event_handle = ACE_INVALID_HANDLE); - // Register an <event_handler> that will be notified when - // <event_handle> is signaled. Since no event mask is passed - // through this interface, it is assumed that the <event_handle> - // being passed in is an event handle and not an I/O handle. - // - // Originally this interface was available for all platforms, but - // because ACE_HANDLE is an int on non-Win32 platforms, compilers - // are not able to tell the difference between - // register_handler(ACE_Event_Handler*,ACE_Reactor_Mask) and - // register_handler(ACE_Event_Handler*,ACE_HANDLE). Therefore, we - // have restricted this method to Win32 only. #endif /* ACE_WIN32 */ + /** + * Register an <event_handler> that will be notified when + * <event_handle> is signaled. <mask> specifies the network events + * that the <event_handler> is interested in. + */ virtual int register_handler (ACE_HANDLE event_handle, ACE_HANDLE io_handle, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // Register an <event_handler> that will be notified when - // <event_handle> is signaled. <mask> specifies the network events - // that the <event_handler> is interested in. + /// Register <event_handler> with all the <handles> in the <Handle_Set>. virtual int register_handler (const ACE_Handle_Set &handles, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // Register <event_handler> with all the <handles> in the <Handle_Set>. + /** + * Register <new_sh> to handle the signal <signum> using the + * <new_disp>. Returns the <old_sh> that was previously registered + * (if any), along with the <old_disp> of the signal handler. + */ virtual int register_handler (int signum, ACE_Event_Handler *new_sh, ACE_Sig_Action *new_disp = 0, ACE_Event_Handler **old_sh = 0, ACE_Sig_Action *old_disp = 0); - // Register <new_sh> to handle the signal <signum> using the - // <new_disp>. Returns the <old_sh> that was previously registered - // (if any), along with the <old_disp> of the signal handler. + /// Registers <new_sh> to handle a set of signals <sigset> using the + /// <new_disp>. virtual int register_handler (const ACE_Sig_Set &sigset, ACE_Event_Handler *new_sh, ACE_Sig_Action *new_disp = 0); - // Registers <new_sh> to handle a set of signals <sigset> using the - // <new_disp>. + /** + * Removes <event_handler>. Note that the I/O handle will be + * obtained using <get_handle> method of <event_handler> . If + * <mask> == <ACE_Event_Handler::DONT_CALL> then the <handle_close> + * method of the <event_handler> is not invoked. + */ virtual int remove_handler (ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // Removes <event_handler>. Note that the I/O handle will be - // obtained using <get_handle> method of <event_handler> . If - // <mask> == <ACE_Event_Handler::DONT_CALL> then the <handle_close> - // method of the <event_handler> is not invoked. + /** + * Removes <handle>. If <mask> == <ACE_Event_Handler::DONT_CALL> + * then the <handle_close> method of the associated <event_handler> + * is not invoked. + */ virtual int remove_handler (ACE_HANDLE handle, ACE_Reactor_Mask mask); - // Removes <handle>. If <mask> == <ACE_Event_Handler::DONT_CALL> - // then the <handle_close> method of the associated <event_handler> - // is not invoked. + /** + * Removes all handles in <handle_set>. If <mask> == + * <ACE_Event_Handler::DONT_CALL> then the <handle_close> method of + * the associated <event_handler>s is not invoked. + */ virtual int remove_handler (const ACE_Handle_Set &handle_set, ACE_Reactor_Mask mask); - // Removes all handles in <handle_set>. If <mask> == - // <ACE_Event_Handler::DONT_CALL> then the <handle_close> method of - // the associated <event_handler>s is not invoked. + /** + * Remove the ACE_Event_Handler currently associated with <signum>. + * Install the new disposition (if given) and return the previous + * disposition (if desired by the caller). Returns 0 on success and + * -1 if <signum> is invalid. + */ virtual int remove_handler (int signum, ACE_Sig_Action *new_disp, ACE_Sig_Action *old_disp = 0, int sigkey = -1); - // Remove the ACE_Event_Handler currently associated with <signum>. - // Install the new disposition (if given) and return the previous - // disposition (if desired by the caller). Returns 0 on success and - // -1 if <signum> is invalid. + /// Calls <remove_handler> for every signal in <sigset>. virtual int remove_handler (const ACE_Sig_Set &sigset); - // Calls <remove_handler> for every signal in <sigset>. // = Suspend and resume Handlers. + /// Suspend <event_handler> temporarily. Use + /// <ACE_Event_Handler::get_handle> to get the handle. virtual int suspend_handler (ACE_Event_Handler *event_handler); - // Suspend <event_handler> temporarily. Use - // <ACE_Event_Handler::get_handle> to get the handle. + /// Suspend <handle> temporarily. virtual int suspend_handler (ACE_HANDLE handle); - // Suspend <handle> temporarily. + /// Suspend all <handles> in handle set temporarily. virtual int suspend_handler (const ACE_Handle_Set &handles); - // Suspend all <handles> in handle set temporarily. + /// Suspend all <handles> temporarily. virtual int suspend_handlers (void); - // Suspend all <handles> temporarily. + /// Resume <event_handler>. Use <ACE_Event_Handler::get_handle> to + /// get the handle. virtual int resume_handler (ACE_Event_Handler *event_handler); - // Resume <event_handler>. Use <ACE_Event_Handler::get_handle> to - // get the handle. + /// Resume <handle>. virtual int resume_handler (ACE_HANDLE handle); - // Resume <handle>. + /// Resume all <handles> in handle set. virtual int resume_handler (const ACE_Handle_Set &handles); - // Resume all <handles> in handle set. + /// Resume all <handles>. virtual int resume_handlers (void); - // Resume all <handles>. // = Timer management. + /** + * Schedule an <event_handler> that will expire after <delay> amount + * of time, which is specified as relative time to the current + * <gettimeofday>. If it expires then <arg> is passed in as the + * value to the <event_handler>'s <handle_timeout> callback method. + * If <interval> is != to <ACE_Time_Value::zero> then it is used to + * reschedule the <event_handler> automatically, also specified + * using relative time. This method returns a <timer_id> that + * uniquely identifies the <event_handler> in an internal list. + * This <timer_id> can be used to cancel an <event_handler> before + * it expires. The cancellation ensures that <timer_ids> are unique + * up to values of greater than 2 billion timers. As long as timers + * don't stay around longer than this there should be no problems + * with accidentally deleting the wrong timer. Returns -1 on + * failure (which is guaranteed never to be a valid <timer_id>. + */ virtual long schedule_timer (ACE_Event_Handler *event_handler, const void *arg, const ACE_Time_Value &delta, const ACE_Time_Value &interval = ACE_Time_Value::zero); - // Schedule an <event_handler> that will expire after <delay> amount - // of time, which is specified as relative time to the current - // <gettimeofday>. If it expires then <arg> is passed in as the - // value to the <event_handler>'s <handle_timeout> callback method. - // If <interval> is != to <ACE_Time_Value::zero> then it is used to - // reschedule the <event_handler> automatically, also specified - // using relative time. This method returns a <timer_id> that - // uniquely identifies the <event_handler> in an internal list. - // This <timer_id> can be used to cancel an <event_handler> before - // it expires. The cancellation ensures that <timer_ids> are unique - // up to values of greater than 2 billion timers. As long as timers - // don't stay around longer than this there should be no problems - // with accidentally deleting the wrong timer. Returns -1 on - // failure (which is guaranteed never to be a valid <timer_id>. - - virtual int reset_timer_interval (long timer_id, + + /** + * Resets the interval of the timer represented by <timer_id> to + * <interval>, which is specified in relative time to the current + * <gettimeofday>. If <interval> is equal to + * <ACE_Time_Value::zero>, the timer will become a non-rescheduling + * timer. Returns 0 if successful, -1 if not. + */ + virtual int reset_timer_interval (long timer_id, const ACE_Time_Value &interval); - // Resets the interval of the timer represented by <timer_id> to - // <interval>, which is specified in relative time to the current - // <gettimeofday>. If <interval> is equal to - // <ACE_Time_Value::zero>, the timer will become a non-rescheduling - // timer. Returns 0 if successful, -1 if not. + /// Cancel all <Event_Handler>s that match the address of + /// <event_handler>. Returns number of handlers cancelled. virtual int cancel_timer (ACE_Event_Handler *event_handler, int dont_call_handle_close = 1); - // Cancel all <Event_Handler>s that match the address of - // <event_handler>. Returns number of handlers cancelled. + /** + * Cancel the single <Event_Handler> that matches the <timer_id> + * value, which was returned from the schedule method. If arg is + * non-NULL then it will be set to point to the ``magic cookie'' + * argument passed in when the Event_Handler was registered. This + * makes it possible to free up the memory and avoid memory leaks. + * Returns 1 if cancellation succeeded and 0 if the <timer_id> + * wasn't found. + */ virtual int cancel_timer (long timer_id, const void **arg = 0, int dont_call_handle_close = 1); - // Cancel the single <Event_Handler> that matches the <timer_id> - // value, which was returned from the schedule method. If arg is - // non-NULL then it will be set to point to the ``magic cookie'' - // argument passed in when the Event_Handler was registered. This - // makes it possible to free up the memory and avoid memory leaks. - // Returns 1 if cancellation succeeded and 0 if the <timer_id> - // wasn't found. // = High-level Event_Handler scheduling operations + /// Add <masks_to_be_added> to the <event_handler>'s entry. + /// <event_handler> must already have been registered. virtual int schedule_wakeup (ACE_Event_Handler *event_handler, ACE_Reactor_Mask masks_to_be_added); - // Add <masks_to_be_added> to the <event_handler>'s entry. - // <event_handler> must already have been registered. + /// Add <masks_to_be_added> to the <handle>'s entry. <event_handler> + /// associated with <handle> must already have been registered. virtual int schedule_wakeup (ACE_HANDLE handle, ACE_Reactor_Mask masks_to_be_added); - // Add <masks_to_be_added> to the <handle>'s entry. <event_handler> - // associated with <handle> must already have been registered. + /// Clear <masks_to_be_cleared> from the <event_handler>'s entry. virtual int cancel_wakeup (ACE_Event_Handler *event_handler, ACE_Reactor_Mask masks_to_be_cleared); - // Clear <masks_to_be_cleared> from the <event_handler>'s entry. + /// Clear <masks_to_be_cleared> from the <handle>'s entry. virtual int cancel_wakeup (ACE_HANDLE handle, ACE_Reactor_Mask masks_to_be_cleared); - // Clear <masks_to_be_cleared> from the <handle>'s entry. // = Notification methods. + /** + * Notify <event_handler> of <mask> event. The <ACE_Time_Value> + * indicates how long to blocking trying to notify. If <timeout> == + * 0, the caller will block until action is possible, else will wait + * until the relative time specified in <timeout> elapses). + */ virtual int notify (ACE_Event_Handler *event_handler = 0, ACE_Reactor_Mask mask = ACE_Event_Handler::EXCEPT_MASK, ACE_Time_Value *tv = 0); - // Notify <event_handler> of <mask> event. The <ACE_Time_Value> - // indicates how long to blocking trying to notify. If <timeout> == - // 0, the caller will block until action is possible, else will wait - // until the relative time specified in <timeout> elapses). + /** + * Set the maximum number of times that ACE_Reactor will + * iterate and dispatch the <ACE_Event_Handlers> that are passed in + * via the notify queue before breaking out of its + * <ACE_Message_Queue::dequeue> loop. By default, this is set to + * -1, which means "iterate until the queue is empty." Setting this + * to a value like "1 or 2" will increase "fairness" (and thus + * prevent starvation) at the expense of slightly higher dispatching + * overhead. + */ virtual void max_notify_iterations (int iterations); - // Set the maximum number of times that ACE_Reactor will - // iterate and dispatch the <ACE_Event_Handlers> that are passed in - // via the notify queue before breaking out of its - // <ACE_Message_Queue::dequeue> loop. By default, this is set to - // -1, which means "iterate until the queue is empty." Setting this - // to a value like "1 or 2" will increase "fairness" (and thus - // prevent starvation) at the expense of slightly higher dispatching - // overhead. + /** + * Get the maximum number of times that the ACE_Reactor will + * iterate and dispatch the <ACE_Event_Handlers> that are passed in + * via the notify queue before breaking out of its + * <ACE_Message_Queue::dequeue> loop. + */ virtual int max_notify_iterations (void); - // Get the maximum number of times that the ACE_Reactor will - // iterate and dispatch the <ACE_Event_Handlers> that are passed in - // via the notify queue before breaking out of its - // <ACE_Message_Queue::dequeue> loop. + /** + * Purge any notifications pending in this reactor for the specified + * <ACE_Event_Handler> object. Returns the number of notifications + * purged. Returns -1 on error. + */ virtual int purge_pending_notifications (ACE_Event_Handler * = 0); - // Purge any notifications pending in this reactor for the specified - // <ACE_Event_Handler> object. Returns the number of notifications - // purged. Returns -1 on error. // = Assorted helper methods. - + + /** + * Check to see if <handle> is associated with a valid Event_Handler + * bound to <mask>. Return the <event_handler> associated with this + * <handler> if <event_handler> != 0. + */ virtual int handler (ACE_HANDLE handle, ACE_Reactor_Mask mask, ACE_Event_Handler **event_handler = 0); - // Check to see if <handle> is associated with a valid Event_Handler - // bound to <mask>. Return the <event_handler> associated with this - // <handler> if <event_handler> != 0. + /** + * Check to see if <signum> is associated with a valid Event_Handler + * bound to a signal. Return the <event_handler> associated with + * this <handler> if <event_handler> != 0. + */ virtual int handler (int signum, ACE_Event_Handler **event_handler = 0); - // Check to see if <signum> is associated with a valid Event_Handler - // bound to a signal. Return the <event_handler> associated with - // this <handler> if <event_handler> != 0. + /// Returns true if Reactor has been successfully initialized, else + /// false. virtual int initialized (void); - // Returns true if Reactor has been successfully initialized, else - // false. + /// Returns the current size of the Reactor's internal descriptor + /// table. virtual size_t size (void) const; - // Returns the current size of the Reactor's internal descriptor - // table. + /// Returns a reference to the Reactor's internal lock. virtual ACE_Lock &lock (void); - // Returns a reference to the Reactor's internal lock. + /// Wake up all threads in waiting in the event loop virtual void wakeup_all_threads (void); - // Wake up all threads in waiting in the event loop + /// Transfers ownership of Reactor to the <new_owner>. virtual int owner (ACE_thread_t new_owner, ACE_thread_t *old_owner = 0); - // Transfers ownership of Reactor to the <new_owner>. + /// Return the ID of the "owner" thread. virtual int owner (ACE_thread_t *owner); - // Return the ID of the "owner" thread. + /// Set position of the owner thread. virtual void requeue_position (int position); - // Set position of the owner thread. + /// Get position of the owner thread. virtual int requeue_position (void); - // Get position of the owner thread. + /// Get the existing restart value. virtual int restart (void); - // Get the existing restart value. - + + /// Set a new value for restart and return the original value. virtual int restart (int r); - // Set a new value for restart and return the original value. // = Low-level wait_set mask manipulation methods. + /// GET/SET/ADD/CLR the dispatch mask "bit" bound with the + /// <event_handler> and <mask>. virtual int mask_ops (ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask, int ops); - // GET/SET/ADD/CLR the dispatch mask "bit" bound with the - // <event_handler> and <mask>. + /// GET/SET/ADD/CLR the dispatch MASK "bit" bound with the <handle> + /// and <mask>. virtual int mask_ops (ACE_HANDLE handle, ACE_Reactor_Mask mask, int ops); - // GET/SET/ADD/CLR the dispatch MASK "bit" bound with the <handle> - // and <mask>. // = Low-level ready_set mask manipulation methods. + /// GET/SET/ADD/CLR the ready "bit" bound with the <event_handler> + /// and <mask>. virtual int ready_ops (ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask, int ops); - // GET/SET/ADD/CLR the ready "bit" bound with the <event_handler> - // and <mask>. + /// GET/SET/ADD/CLR the ready "bit" bound with the <handle> and <mask>. virtual int ready_ops (ACE_HANDLE handle, ACE_Reactor_Mask mask, int ops); - // GET/SET/ADD/CLR the ready "bit" bound with the <handle> and <mask>. + /// Get the implementation class virtual ACE_Reactor_Impl *implementation (void) const; - // Get the implementation class + /** + * Returns 0, if the size of the current message has been put in + * <size> returns -1, if not. ACE_HANDLE allows the reactor to + * check if the caller is valid. Used for CLASSIX Reactor + * implementation. + */ virtual int current_info (ACE_HANDLE handle, size_t &msg_size); - // Returns 0, if the size of the current message has been put in - // <size> returns -1, if not. ACE_HANDLE allows the reactor to - // check if the caller is valid. Used for CLASSIX Reactor - // implementation. + /// Return 1 if we any event associations were made by the reactor + /// for the handles that it waits on, 0 otherwise. virtual int uses_event_associations (void); - // Return 1 if we any event associations were made by the reactor - // for the handles that it waits on, 0 otherwise. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /// Dump the state of the object. void dump (void) const; - // Dump the state of the object. protected: + /// Set the implementation class. virtual void implementation (ACE_Reactor_Impl *implementation); - // Set the implementation class. + /// Delegation/implementation class that all methods will be + /// forwarded to. ACE_Reactor_Impl *implementation_; - // Delegation/implementation class that all methods will be - // forwarded to. + /// Flag used to indicate whether we are responsible for cleaning up + /// the implementation instance int delete_implementation_; - // Flag used to indicate whether we are responsible for cleaning up - // the implementation instance + /// Pointer to a process-wide <ACE_Reactor> singleton. static ACE_Reactor *reactor_; - // Pointer to a process-wide <ACE_Reactor> singleton. + /// Must delete the <reactor_> singleton if non-0. static int delete_reactor_; - // Must delete the <reactor_> singleton if non-0. + /// Deny access since member-wise won't work... ACE_Reactor (const ACE_Reactor &); ACE_Reactor &operator = (const ACE_Reactor &); - // Deny access since member-wise won't work... }; #if defined (__ACE_INLINE__) diff --git a/ace/Reactor_Impl.h b/ace/Reactor_Impl.h index e6949630fad..c54e1f503ff 100644 --- a/ace/Reactor_Impl.h +++ b/ace/Reactor_Impl.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Reactor_Impl.h -// -// = AUTHOR -// Irfan Pyarali -// -// ============================================================================ + +//============================================================================= +/** + * @file Reactor_Impl.h + * + * $Id$ + * + * @author Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_REACTOR_IMPL_H #define ACE_REACTOR_IMPL_H @@ -38,11 +35,14 @@ class ACE_Handle_Set; class ACE_Reactor_Impl; +/** + * @class ACE_Reactor_Notify + * + * @brief Abstract class for unblocking an <ACE_Reactor_Impl> from its + * event loop. + */ class ACE_Export ACE_Reactor_Notify : public ACE_Event_Handler { - // = TITLE - // Abstract class for unblocking an <ACE_Reactor_Impl> from its - // event loop. public: // = Initialization and termination methods. virtual int open (ACE_Reactor_Impl *, @@ -50,147 +50,170 @@ public: int disable_notify = 0) = 0; virtual int close (void) = 0; + /** + * Called by a thread when it wants to unblock the <Reactor_Impl>. + * This wakeups the <Reactor_Impl> if currently blocked. Pass over + * both the <Event_Handler> *and* the <mask> to allow the caller to + * dictate which <Event_Handler> method the <Reactor_Impl> will + * invoke. The <ACE_Time_Value> indicates how long to blocking + * trying to notify the <Reactor_Impl>. If <timeout> == 0, the + * caller will block until action is possible, else will wait until + * the relative time specified in *<timeout> elapses). + */ virtual ssize_t notify (ACE_Event_Handler * = 0, ACE_Reactor_Mask = ACE_Event_Handler::EXCEPT_MASK, ACE_Time_Value * = 0) = 0; - // Called by a thread when it wants to unblock the <Reactor_Impl>. - // This wakeups the <Reactor_Impl> if currently blocked. Pass over - // both the <Event_Handler> *and* the <mask> to allow the caller to - // dictate which <Event_Handler> method the <Reactor_Impl> will - // invoke. The <ACE_Time_Value> indicates how long to blocking - // trying to notify the <Reactor_Impl>. If <timeout> == 0, the - // caller will block until action is possible, else will wait until - // the relative time specified in *<timeout> elapses). + /// Handles pending threads (if any) that are waiting to unblock the + /// <Reactor_Impl>. virtual int dispatch_notifications (int &number_of_active_handles, ACE_Handle_Set &rd_mask) = 0; - // Handles pending threads (if any) that are waiting to unblock the - // <Reactor_Impl>. + /** + * Set the maximum number of times that the <handle_input> method + * will iterate and dispatch the <ACE_Event_Handlers> that are + * passed in via the notify queue before breaking out of the event + * loop. By default, this is set to -1, which means "iterate until + * the queue is empty." Setting this to a value like "1 or 2" will + * increase "fairness" (and thus prevent starvation) at the expense + * of slightly higher dispatching overhead. + */ virtual void max_notify_iterations (int) = 0; - // Set the maximum number of times that the <handle_input> method - // will iterate and dispatch the <ACE_Event_Handlers> that are - // passed in via the notify queue before breaking out of the event - // loop. By default, this is set to -1, which means "iterate until - // the queue is empty." Setting this to a value like "1 or 2" will - // increase "fairness" (and thus prevent starvation) at the expense - // of slightly higher dispatching overhead. + /** + * Get the maximum number of times that the <handle_input> method + * will iterate and dispatch the <ACE_Event_Handlers> that are + * passed in via the notify queue before breaking out of its event + * loop. + */ virtual int max_notify_iterations (void) = 0; - // Get the maximum number of times that the <handle_input> method - // will iterate and dispatch the <ACE_Event_Handlers> that are - // passed in via the notify queue before breaking out of its event - // loop. + /** + * Purge any notifications pending in this reactor for the specified + * <ACE_Event_Handler> object. Returns the number of notifications + * purged. Returns -1 on error. + */ virtual int purge_pending_notifications (ACE_Event_Handler * = 0) = 0; - // Purge any notifications pending in this reactor for the specified - // <ACE_Event_Handler> object. Returns the number of notifications - // purged. Returns -1 on error. + /// Dump the state of an object. virtual void dump (void) const = 0; - // Dump the state of an object. }; +/** + * @class ACE_Reactor_Impl + * + * @brief An abstract class for implementing the Reactor Pattern. + */ class ACE_Export ACE_Reactor_Impl { - // = TITLE - // An abstract class for implementing the Reactor Pattern. public: + /// Close down and release all resources. virtual ~ACE_Reactor_Impl (void) {} - // Close down and release all resources. + /// Initialization. virtual int open (size_t size, int restart = 0, ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0, int disable_notify_pipe = 0, ACE_Reactor_Notify * = 0) = 0; - // Initialization. + /** + * Returns 0, if the size of the current message has been put in + * <size> Returns -1, if not. ACE_HANDLE allows the reactor to + * check if the caller is valid. + */ virtual int current_info (ACE_HANDLE, size_t & /* size */) = 0; - // Returns 0, if the size of the current message has been put in - // <size> Returns -1, if not. ACE_HANDLE allows the reactor to - // check if the caller is valid. + /// Use a user specified signal handler instead. virtual int set_sig_handler (ACE_Sig_Handler *signal_handler) = 0; - // Use a user specified signal handler instead. // = The following method is deprecated. Use <timer_queue> instead. + /// Set a user specified timer queue. virtual int set_timer_queue (ACE_Timer_Queue *tq) = 0; - // Set a user specified timer queue. + /// Set a user-specified timer queue. + /// Return the current <ACE_Timer_Queue>. virtual int timer_queue (ACE_Timer_Queue *tq) = 0; - // Set a user-specified timer queue. virtual ACE_Timer_Queue *timer_queue (void) const = 0; - // Return the current <ACE_Timer_Queue>. + /// Close down and release all resources. virtual int close (void) = 0; - // Close down and release all resources. // = Event loop drivers. + /** + * Returns non-zero if there are I/O events "ready" for dispatching, + * but does not actually dispatch the event handlers. By default, + * don't block while checking this, i.e., "poll". + */ virtual int work_pending (const ACE_Time_Value &max_wait_time = ACE_Time_Value::zero) = 0; - // Returns non-zero if there are I/O events "ready" for dispatching, - // but does not actually dispatch the event handlers. By default, - // don't block while checking this, i.e., "poll". + /** + * This event loop driver blocks for up to <max_wait_time> before + * returning. It will return earlier if events occur. Note that + * <max_wait_time> can be 0, in which case this method blocks + * indefinitely until events occur. + * + * <max_wait_time> is decremented to reflect how much time this call + * took. For instance, if a time value of 3 seconds is passed to + * handle_events and an event occurs after 2 seconds, + * <max_wait_time> will equal 1 second. This can be used if an + * application wishes to handle events for some fixed amount of + * time. + * + * Returns the total number of <ACE_Event_Handler>s that were + * dispatched, 0 if the <max_wait_time> elapsed without dispatching + * any handlers, or -1 if an error occurs. + * + * The only difference between <alertable_handle_events> and + * <handle_events> is that in the alertable case, the eventloop will + * return when the system queues an I/O completion routine or an + * Asynchronous Procedure Call. + */ virtual int handle_events (ACE_Time_Value *max_wait_time = 0) = 0; virtual int alertable_handle_events (ACE_Time_Value *max_wait_time = 0) = 0; - // This event loop driver blocks for up to <max_wait_time> before - // returning. It will return earlier if events occur. Note that - // <max_wait_time> can be 0, in which case this method blocks - // indefinitely until events occur. - // - // <max_wait_time> is decremented to reflect how much time this call - // took. For instance, if a time value of 3 seconds is passed to - // handle_events and an event occurs after 2 seconds, - // <max_wait_time> will equal 1 second. This can be used if an - // application wishes to handle events for some fixed amount of - // time. - // - // Returns the total number of <ACE_Event_Handler>s that were - // dispatched, 0 if the <max_wait_time> elapsed without dispatching - // any handlers, or -1 if an error occurs. - // - // The only difference between <alertable_handle_events> and - // <handle_events> is that in the alertable case, the eventloop will - // return when the system queues an I/O completion routine or an - // Asynchronous Procedure Call. + /** + * This method is just like the one above, except the + * <max_wait_time> value is a reference and can therefore never be + * NULL. + * + * The only difference between <alertable_handle_events> and + * <handle_events> is that in the alertable case, the eventloop will + * return when the system queues an I/O completion routine or an + * Asynchronous Procedure Call. + */ virtual int handle_events (ACE_Time_Value &max_wait_time) = 0; virtual int alertable_handle_events (ACE_Time_Value &max_wait_time) = 0; - // This method is just like the one above, except the - // <max_wait_time> value is a reference and can therefore never be - // NULL. - // - // The only difference between <alertable_handle_events> and - // <handle_events> is that in the alertable case, the eventloop will - // return when the system queues an I/O completion routine or an - // Asynchronous Procedure Call. // = Event handling control. + /** + * Return the status of Reactor. If this function returns 0, the reactor is + * actively handling events. If it returns non-zero, <handling_events> and + * <handle_alertable_events> return -1 immediately. + */ virtual int deactivated (void) = 0; - // Return the status of Reactor. If this function returns 0, the reactor is - // actively handling events. If it returns non-zero, <handling_events> and - // <handle_alertable_events> return -1 immediately. + /** + * Control whether the Reactor will handle any more incoming events or not. + * If <do_stop> == 1, the Reactor will be disabled. By default, a reactor + * is in active state and can be deactivated/reactived as wish. + */ virtual void deactivate (int do_stop) = 0; - // Control whether the Reactor will handle any more incoming events or not. - // If <do_stop> == 1, the Reactor will be disabled. By default, a reactor - // is in active state and can be deactivated/reactived as wish. // = Register and remove Handlers. + /// Register <event_handler> with <mask>. The I/O handle will always + /// come from <get_handle> on the <event_handler>. virtual int register_handler (ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask) = 0; - // Register <event_handler> with <mask>. The I/O handle will always - // come from <get_handle> on the <event_handler>. + /// Register <event_handler> with <mask>. The I/O handle is provided + /// through the <io_handle> parameter. virtual int register_handler (ACE_HANDLE io_handle, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask) = 0; - // Register <event_handler> with <mask>. The I/O handle is provided - // through the <io_handle> parameter. #if defined (ACE_WIN32) @@ -201,280 +224,312 @@ public: // register_handler(ACE_Event_Handler*,ACE_HANDLE). Therefore, we // have restricted this method to Win32 only. + /** + * Register an <event_handler> that will be notified when + * <event_handle> is signaled. Since no event mask is passed + * through this interface, it is assumed that the <event_handle> + * being passed in is an event handle and not an I/O handle. + */ virtual int register_handler (ACE_Event_Handler *event_handler, ACE_HANDLE event_handle = ACE_INVALID_HANDLE) = 0; - // Register an <event_handler> that will be notified when - // <event_handle> is signaled. Since no event mask is passed - // through this interface, it is assumed that the <event_handle> - // being passed in is an event handle and not an I/O handle. #endif /* ACE_WIN32 */ + /** + * Register an <event_handler> that will be notified when + * <event_handle> is signaled. <mask> specifies the network events + * that the <event_handler> is interested in. + */ virtual int register_handler (ACE_HANDLE event_handle, ACE_HANDLE io_handle, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask) = 0; - // Register an <event_handler> that will be notified when - // <event_handle> is signaled. <mask> specifies the network events - // that the <event_handler> is interested in. + /// Register <event_handler> with all the <handles> in the <Handle_Set>. virtual int register_handler (const ACE_Handle_Set &handles, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask) = 0; - // Register <event_handler> with all the <handles> in the <Handle_Set>. + /** + * Register <new_sh> to handle the signal <signum> using the + * <new_disp>. Returns the <old_sh> that was previously registered + * (if any), along with the <old_disp> of the signal handler. + */ virtual int register_handler (int signum, ACE_Event_Handler *new_sh, ACE_Sig_Action *new_disp = 0, ACE_Event_Handler **old_sh = 0, ACE_Sig_Action *old_disp = 0) = 0; - // Register <new_sh> to handle the signal <signum> using the - // <new_disp>. Returns the <old_sh> that was previously registered - // (if any), along with the <old_disp> of the signal handler. + /// Registers <new_sh> to handle a set of signals <sigset> using the + /// <new_disp>. virtual int register_handler (const ACE_Sig_Set &sigset, ACE_Event_Handler *new_sh, ACE_Sig_Action *new_disp = 0) = 0; - // Registers <new_sh> to handle a set of signals <sigset> using the - // <new_disp>. + /** + * Removes <event_handler>. Note that the I/O handle will be + * obtained using <get_handle> method of <event_handler> . If + * <mask> == <ACE_Event_Handler::DONT_CALL> then the <handle_close> + * method of the <event_handler> is not invoked. + */ virtual int remove_handler (ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask) = 0; - // Removes <event_handler>. Note that the I/O handle will be - // obtained using <get_handle> method of <event_handler> . If - // <mask> == <ACE_Event_Handler::DONT_CALL> then the <handle_close> - // method of the <event_handler> is not invoked. + /** + * Removes <handle>. If <mask> == <ACE_Event_Handler::DONT_CALL> + * then the <handle_close> method of the associated <event_handler> + * is not invoked. + */ virtual int remove_handler (ACE_HANDLE handle, ACE_Reactor_Mask mask) = 0; - // Removes <handle>. If <mask> == <ACE_Event_Handler::DONT_CALL> - // then the <handle_close> method of the associated <event_handler> - // is not invoked. + /** + * Removes all handles in <handle_set>. If <mask> == + * <ACE_Event_Handler::DONT_CALL> then the <handle_close> method of + * the associated <event_handler>s is not invoked. + */ virtual int remove_handler (const ACE_Handle_Set &handle_set, ACE_Reactor_Mask mask) = 0; - // Removes all handles in <handle_set>. If <mask> == - // <ACE_Event_Handler::DONT_CALL> then the <handle_close> method of - // the associated <event_handler>s is not invoked. + /** + * Remove the ACE_Event_Handler currently associated with <signum>. + * Install the new disposition (if given) and return the previous + * disposition (if desired by the caller). Returns 0 on success and + * -1 if <signum> is invalid. + */ virtual int remove_handler (int signum, ACE_Sig_Action *new_disp, ACE_Sig_Action *old_disp = 0, int sigkey = -1) = 0; - // Remove the ACE_Event_Handler currently associated with <signum>. - // Install the new disposition (if given) and return the previous - // disposition (if desired by the caller). Returns 0 on success and - // -1 if <signum> is invalid. + /// Calls <remove_handler> for every signal in <sigset>. virtual int remove_handler (const ACE_Sig_Set &sigset) = 0; - // Calls <remove_handler> for every signal in <sigset>. // = Suspend and resume Handlers. + /// Suspend <event_handler> temporarily. Use + /// <ACE_Event_Handler::get_handle> to get the handle. virtual int suspend_handler (ACE_Event_Handler *event_handler) = 0; - // Suspend <event_handler> temporarily. Use - // <ACE_Event_Handler::get_handle> to get the handle. + /// Suspend <handle> temporarily. virtual int suspend_handler (ACE_HANDLE handle) = 0; - // Suspend <handle> temporarily. + /// Suspend all <handles> in handle set temporarily. virtual int suspend_handler (const ACE_Handle_Set &handles) = 0; - // Suspend all <handles> in handle set temporarily. + /// Suspend all <handles> temporarily. virtual int suspend_handlers (void) = 0; - // Suspend all <handles> temporarily. + /// Resume <event_handler>. Use <ACE_Event_Handler::get_handle> to + /// get the handle. virtual int resume_handler (ACE_Event_Handler *event_handler) = 0; - // Resume <event_handler>. Use <ACE_Event_Handler::get_handle> to - // get the handle. + /// Resume <handle>. virtual int resume_handler (ACE_HANDLE handle) = 0; - // Resume <handle>. + /// Resume all <handles> in handle set. virtual int resume_handler (const ACE_Handle_Set &handles) = 0; - // Resume all <handles> in handle set. + /// Resume all <handles>. virtual int resume_handlers (void) = 0; - // Resume all <handles>. + /// Return 1 if we any event associations were made by the reactor + /// for the handles that it waits on, 0 otherwise. virtual int uses_event_associations (void) = 0; - // Return 1 if we any event associations were made by the reactor - // for the handles that it waits on, 0 otherwise. // If we need to reset handles returned from accept/connect. // = Timer management. + /** + * Schedule an <event_handler> that will expire after <delay> amount + * of time, which is specified as relative time to the current + * <gettimeofday>. If it expires then <arg> is passed in as the + * value to the <event_handler>'s <handle_timeout> callback method. + * If <interval> is != to <ACE_Time_Value::zero> then it is used to + * reschedule the <event_handler> automatically, also using relative + * time. This method returns a <timer_id> that uniquely identifies + * the <event_handler> in an internal list. This <timer_id> can be + * used to cancel an <event_handler> before it expires. The + * cancellation ensures that <timer_ids> are unique up to values of + * greater than 2 billion timers. As long as timers don't stay + * around longer than this there should be no problems with + * accidentally deleting the wrong timer. Returns -1 on failure + * (which is guaranteed never to be a valid <timer_id>. + */ virtual long schedule_timer (ACE_Event_Handler *event_handler, const void *arg, const ACE_Time_Value &delta, const ACE_Time_Value &interval = ACE_Time_Value::zero) = 0; - // Schedule an <event_handler> that will expire after <delay> amount - // of time, which is specified as relative time to the current - // <gettimeofday>. If it expires then <arg> is passed in as the - // value to the <event_handler>'s <handle_timeout> callback method. - // If <interval> is != to <ACE_Time_Value::zero> then it is used to - // reschedule the <event_handler> automatically, also using relative - // time. This method returns a <timer_id> that uniquely identifies - // the <event_handler> in an internal list. This <timer_id> can be - // used to cancel an <event_handler> before it expires. The - // cancellation ensures that <timer_ids> are unique up to values of - // greater than 2 billion timers. As long as timers don't stay - // around longer than this there should be no problems with - // accidentally deleting the wrong timer. Returns -1 on failure - // (which is guaranteed never to be a valid <timer_id>. - - virtual int reset_timer_interval (long timer_id, + + /** + * Resets the interval of the timer represented by <timer_id> to + * <interval>, which is specified in relative time to the current + * <gettimeofday>. If <interval> is equal to + * <ACE_Time_Value::zero>, the timer will become a non-rescheduling + * timer. Returns 0 if successful, -1 if not. + */ + virtual int reset_timer_interval (long timer_id, const ACE_Time_Value &interval) = 0; - // Resets the interval of the timer represented by <timer_id> to - // <interval>, which is specified in relative time to the current - // <gettimeofday>. If <interval> is equal to - // <ACE_Time_Value::zero>, the timer will become a non-rescheduling - // timer. Returns 0 if successful, -1 if not. + /// Cancel all Event_Handlers that match the address of + /// <event_handler>. Returns number of handlers cancelled. virtual int cancel_timer (ACE_Event_Handler *event_handler, int dont_call_handle_close = 1) = 0; - // Cancel all Event_Handlers that match the address of - // <event_handler>. Returns number of handlers cancelled. + /** + * Cancel the single Event_Handler that matches the <timer_id> value + * (which was returned from the schedule method). If arg is + * non-NULL then it will be set to point to the ``magic cookie'' + * argument passed in when the Event_Handler was registered. This + * makes it possible to free up the memory and avoid memory leaks. + * Returns 1 if cancellation succeeded and 0 if the <timer_id> + * wasn't found. + */ virtual int cancel_timer (long timer_id, const void **arg = 0, int dont_call_handle_close = 1) = 0; - // Cancel the single Event_Handler that matches the <timer_id> value - // (which was returned from the schedule method). If arg is - // non-NULL then it will be set to point to the ``magic cookie'' - // argument passed in when the Event_Handler was registered. This - // makes it possible to free up the memory and avoid memory leaks. - // Returns 1 if cancellation succeeded and 0 if the <timer_id> - // wasn't found. // = High-level Event_Handler scheduling operations + /// Add <masks_to_be_added> to the <event_handler>'s entry. + /// <event_handler> must already have been registered. virtual int schedule_wakeup (ACE_Event_Handler *event_handler, ACE_Reactor_Mask masks_to_be_added) = 0; - // Add <masks_to_be_added> to the <event_handler>'s entry. - // <event_handler> must already have been registered. + /// Add <masks_to_be_added> to the <handle>'s entry. <event_handler> + /// associated with <handle> must already have been registered. virtual int schedule_wakeup (ACE_HANDLE handle, ACE_Reactor_Mask masks_to_be_added) = 0; - // Add <masks_to_be_added> to the <handle>'s entry. <event_handler> - // associated with <handle> must already have been registered. + /// Clear <masks_to_be_cleared> from the <event_handler>'s entry. virtual int cancel_wakeup (ACE_Event_Handler *event_handler, ACE_Reactor_Mask masks_to_be_cleared) = 0; - // Clear <masks_to_be_cleared> from the <event_handler>'s entry. + /// Clear <masks_to_be_cleared> from the <handle>'s entry. virtual int cancel_wakeup (ACE_HANDLE handle, ACE_Reactor_Mask masks_to_be_cleared) = 0; - // Clear <masks_to_be_cleared> from the <handle>'s entry. // = Notification methods. + /** + * Notify <event_handler> of <mask> event. The <ACE_Time_Value> + * indicates how long to blocking trying to notify. If <timeout> == + * 0, the caller will block until action is possible, else will wait + * until the relative time specified in <timeout> elapses). + */ virtual int notify (ACE_Event_Handler *event_handler = 0, ACE_Reactor_Mask mask = ACE_Event_Handler::EXCEPT_MASK, ACE_Time_Value * = 0) = 0; - // Notify <event_handler> of <mask> event. The <ACE_Time_Value> - // indicates how long to blocking trying to notify. If <timeout> == - // 0, the caller will block until action is possible, else will wait - // until the relative time specified in <timeout> elapses). + /** + * Set the maximum number of times that ACE_Reactor_Impl will + * iterate and dispatch the <ACE_Event_Handlers> that are passed in + * via the notify queue before breaking out of its + * <ACE_Message_Queue::dequeue> loop. By default, this is set to + * -1, which means "iterate until the queue is empty." Setting this + * to a value like "1 or 2" will increase "fairness" (and thus + * prevent starvation) at the expense of slightly higher dispatching + * overhead. + */ virtual void max_notify_iterations (int) = 0; - // Set the maximum number of times that ACE_Reactor_Impl will - // iterate and dispatch the <ACE_Event_Handlers> that are passed in - // via the notify queue before breaking out of its - // <ACE_Message_Queue::dequeue> loop. By default, this is set to - // -1, which means "iterate until the queue is empty." Setting this - // to a value like "1 or 2" will increase "fairness" (and thus - // prevent starvation) at the expense of slightly higher dispatching - // overhead. + /** + * Get the maximum number of times that the ACE_Reactor_Impl will + * iterate and dispatch the <ACE_Event_Handlers> that are passed in + * via the notify queue before breaking out of its + * <ACE_Message_Queue::dequeue> loop. + */ virtual int max_notify_iterations (void) = 0; - // Get the maximum number of times that the ACE_Reactor_Impl will - // iterate and dispatch the <ACE_Event_Handlers> that are passed in - // via the notify queue before breaking out of its - // <ACE_Message_Queue::dequeue> loop. + /** + * Purge any notifications pending in this reactor for the specified + * <ACE_Event_Handler> object. Returns the number of notifications + * purged. Returns -1 on error. + */ virtual int purge_pending_notifications (ACE_Event_Handler * = 0) = 0; - // Purge any notifications pending in this reactor for the specified - // <ACE_Event_Handler> object. Returns the number of notifications - // purged. Returns -1 on error. + /** + * Check to see if <handle> is associated with a valid Event_Handler + * bound to <mask>. Return the <event_handler> associated with this + * <handler> if <event_handler> != 0. + */ virtual int handler (ACE_HANDLE handle, ACE_Reactor_Mask mask, ACE_Event_Handler **event_handler = 0) = 0; - // Check to see if <handle> is associated with a valid Event_Handler - // bound to <mask>. Return the <event_handler> associated with this - // <handler> if <event_handler> != 0. + /** + * Check to see if <signum> is associated with a valid Event_Handler + * bound to a signal. Return the <event_handler> associated with + * this <handler> if <event_handler> != 0. + */ virtual int handler (int signum, ACE_Event_Handler ** = 0) = 0; - // Check to see if <signum> is associated with a valid Event_Handler - // bound to a signal. Return the <event_handler> associated with - // this <handler> if <event_handler> != 0. + /// Returns true if Reactor has been successfully initialized, else + /// false. virtual int initialized (void) = 0; - // Returns true if Reactor has been successfully initialized, else - // false. + /// Returns the current size of the Reactor's internal descriptor + /// table. virtual size_t size (void) const = 0; - // Returns the current size of the Reactor's internal descriptor - // table. + /// Returns a reference to the Reactor's internal lock. virtual ACE_Lock &lock (void) = 0; - // Returns a reference to the Reactor's internal lock. + /// Wake up all threads in waiting in the event loop virtual void wakeup_all_threads (void) = 0; - // Wake up all threads in waiting in the event loop + /// Transfers ownership of Reactor_Impl to the <new_owner>. virtual int owner (ACE_thread_t new_owner, ACE_thread_t *old_owner = 0) = 0; - // Transfers ownership of Reactor_Impl to the <new_owner>. + /// Return the ID of the "owner" thread. virtual int owner (ACE_thread_t *owner) = 0; - // Return the ID of the "owner" thread. + /// Get the existing restart value. virtual int restart (void) = 0; - // Get the existing restart value. - + + /// Set a new value for restart and return the original value. virtual int restart (int r) = 0; - // Set a new value for restart and return the original value. + /// Set position of the owner thread. virtual void requeue_position (int) = 0; - // Set position of the owner thread. + /// Get position of the owner thread. virtual int requeue_position (void) = 0; - // Get position of the owner thread. // = Low-level wait_set mask manipulation methods. + /// GET/SET/ADD/CLR the dispatch mask "bit" bound with the + /// <event_handler> and <mask>. virtual int mask_ops (ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask, int ops) = 0; - // GET/SET/ADD/CLR the dispatch mask "bit" bound with the - // <event_handler> and <mask>. + /// GET/SET/ADD/CLR the dispatch MASK "bit" bound with the <handle> + /// and <mask>. virtual int mask_ops (ACE_HANDLE handle, ACE_Reactor_Mask mask, int ops) = 0; - // GET/SET/ADD/CLR the dispatch MASK "bit" bound with the <handle> - // and <mask>. // = Low-level ready_set mask manipulation methods. + /// GET/SET/ADD/CLR the ready "bit" bound with the <event_handler> + /// and <mask>. virtual int ready_ops (ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask, int ops) = 0; - // GET/SET/ADD/CLR the ready "bit" bound with the <event_handler> - // and <mask>. + /// GET/SET/ADD/CLR the ready "bit" bound with the <handle> and <mask>. virtual int ready_ops (ACE_HANDLE handle, ACE_Reactor_Mask, int ops) = 0; - // GET/SET/ADD/CLR the ready "bit" bound with the <handle> and <mask>. + /// Dump the state of an object. virtual void dump (void) const = 0; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #include "ace/post.h" diff --git a/ace/Read_Buffer.h b/ace/Read_Buffer.h index 84688f9bc0c..ad1bef9fa32 100644 --- a/ace/Read_Buffer.h +++ b/ace/Read_Buffer.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Read_Buffer.h -// -// = AUTHOR -// Doug Schmidt and Seth Widoff -// -// ============================================================================ + +//============================================================================= +/** + * @file Read_Buffer.h + * + * $Id$ + * + * @author Doug Schmidt and Seth Widoff + */ +//============================================================================= + #ifndef ACE_READ_BUFFER_H #define ACE_READ_BUFFER_H @@ -26,79 +23,83 @@ #include "ace/Malloc.h" +/** + * @class ACE_Read_Buffer + * + * @brief Efficiently reads an artibrarily large buffer from an input + * stream up to and including a termination character. Also + * performs search/replace on single occurrences a character in + * the buffer using the principles of Integrated Layer + * Processing. + * + * This implementation is optimized to do a single dynamic + * allocation and make only one copy of the data. It uses + * recursion and the run-time stack to accomplish this + * efficiently. + */ class ACE_Export ACE_Read_Buffer { - // = TITLE - // Efficiently reads an artibrarily large buffer from an input - // stream up to and including a termination character. Also - // performs search/replace on single occurrences a character in - // the buffer using the principles of Integrated Layer - // Processing. - // - // = DESCRIPTION - // This implementation is optimized to do a single dynamic - // allocation and make only one copy of the data. It uses - // recursion and the run-time stack to accomplish this - // efficiently. public: // = Initialization and termination methods. + /// Read from a FILE *. ACE_Read_Buffer (FILE *fp, int close_on_delete = 0, ACE_Allocator * = 0); - // Read from a FILE *. + /// Read from an open HANDLE. ACE_Read_Buffer (ACE_HANDLE handle, int close_on_delete = 0, ACE_Allocator * = 0); - // Read from an open HANDLE. + /// Closes the FILE *. ~ACE_Read_Buffer (void); - // Closes the FILE *. + /** + * Returns a pointer dynamically allocated with + * <ACE_Allocator::malloc> to data from the input stream up to (and + * including) the <terminator>. If <search> is >= 0 then all + * occurrences of the <search> value are substituted with the + * <replace> value. The last of the byte of data is a 0, so that + * <strlen> can be used on it. The caller is responsible for + * freeing the pointer returned from this method using the + * <ACE_Allocator::free>. + */ char *read (int terminator = EOF, int search = '\n', int replace = '\0'); - // Returns a pointer dynamically allocated with - // <ACE_Allocator::malloc> to data from the input stream up to (and - // including) the <terminator>. If <search> is >= 0 then all - // occurrences of the <search> value are substituted with the - // <replace> value. The last of the byte of data is a 0, so that - // <strlen> can be used on it. The caller is responsible for - // freeing the pointer returned from this method using the - // <ACE_Allocator::free>. + /// Returns the number of characters replaced during a <read>. size_t replaced (void) const; - // Returns the number of characters replaced during a <read>. + /// Returns the size of the allocated buffer obtained during a + /// <read>, not including the null terminator. size_t size (void) const; - // Returns the size of the allocated buffer obtained during a - // <read>, not including the null terminator. + /// Returns a pointer to its allocator. ACE_Allocator *alloc (void) const; - // Returns a pointer to its allocator. + /// Dump the state of the object. void dump (void) const; - // Dump the state of the object. private: + /// Recursive helper method that does the work... char *rec_read (int term, int search, int replace); - // Recursive helper method that does the work... + /// The total number of characters in the buffer. size_t size_; - // The total number of characters in the buffer. + /// The total number of characters replaced. size_t occurrences_; - // The total number of characters replaced. + /// The stream we are reading from. FILE *stream_; - // The stream we are reading from. + /// Keeps track of whether we should close the FILE in the + /// destructor. int close_on_delete_; - // Keeps track of whether we should close the FILE in the - // destructor. + /// Pointer to the allocator. ACE_Allocator *allocator_; - // Pointer to the allocator. // = Disallow copying and assignment... ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Read_Buffer &)) diff --git a/ace/Registry.h b/ace/Registry.h index 8bb0aa4cab8..c1fc45c5a19 100644 --- a/ace/Registry.h +++ b/ace/Registry.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Registry.h -// -// = AUTHOR -// Irfan Pyarali (irfan@cs.wustl.edu) -// -// ============================================================================ + +//============================================================================= +/** + * @file Registry.h + * + * $Id$ + * + * @author Irfan Pyarali (irfan@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_REGISTRY_H #define ACE_REGISTRY_H @@ -30,21 +27,23 @@ #include "ace/Containers.h" #include "ace/SString.h" +/** + * @class ACE_Registry + * + * @brief A Name Server implementation + * + * The registry interface is inspired by the interface + * specified in the CORBA Naming Service Specification. + * The implementation is done through Win32 <Reg*> functions. + * Other than providing an OO wrapper for the Win32 <Reg*> + * functions, ACE_Registry provides an abstraction for iteration + * over the elements of the Registry. + */ class ACE_Export ACE_Registry { - // = TITLE - // A Name Server implementation - // - // = DESCRIPTION - // The registry interface is inspired by the interface - // specified in the CORBA Naming Service Specification. - // The implementation is done through Win32 <Reg*> functions. - // Other than providing an OO wrapper for the Win32 <Reg*> - // functions, ACE_Registry provides an abstraction for iteration - // over the elements of the Registry. public: -// International string + /// International string struct ACE_Export Name_Component { ACE_TString id_; @@ -60,380 +59,413 @@ public: // A Name is an ordered collections of components (ids) typedef ACE_Unbounded_Set<Name_Component> Name; + /// Separator for components in a name static const ACE_TCHAR *STRING_SEPARATOR; - // Separator for components in a name + /// Convert a <name> to a <string> static ACE_TString make_string (const Name &name); - // Convert a <name> to a <string> + /// Convert a <string> to a <name> static Name make_name (const ACE_TString &string); - // Convert a <string> to a <name> + /// There are two types of bindings enum Binding_Type {INVALID, OBJECT, CONTEXT}; - // There are two types of bindings struct ACE_Export Binding { + /// Empty (default) constructor Binding (void); - // Empty (default) constructor + /// Constructor + /// (Name version) Binding (const Name &binding_name, Binding_Type binding_type); - // Constructor - // (Name version) + /// Constructor + /// (String version) Binding (const ACE_TString &binding_name, Binding_Type binding_type); - // Constructor - // (String version) int operator== (const Binding &rhs) const; int operator!= (const Binding &rhs) const; // Comparison + /// Name accessor + /// (Name version) void name (Name &name); - // Name accessor - // (Name version) + /// Name accessors + /// (String version) void name (ACE_TString &name); ACE_TString name (void); - // Name accessors - // (String version) + /// Type accessor Binding_Type type (void); - // Type accessor private: + /// A binding has a name ACE_TString name_; + + /// .... and a type Binding_Type type_; - // A binding has a name and a type }; // A list of bindings typedef ACE_Unbounded_Set<Binding> Binding_List; + /** + * @class Binding_Iterator; + * + * Forward declaration of iterator + */ class Binding_Iterator; - // Forward declaration of iterator + /** + * @class Object + * + * @brief An object representation + * + * In CORBA, all objects inherit from (CORBA::Object). + * For the registry, this is used as a wrapper for an + * instance of a built-in data type. + * Think about an object as being similar to a file + * in a file system. + */ class ACE_Export Object { - // = TITLE - // An object representation - // - // = DESCRIPTION - // In CORBA, all objects inherit from (CORBA::Object). - // For the registry, this is used as a wrapper for an - // instance of a built-in data type. - // Think about an object as being similar to a file - // in a file system. public: + /// Default constructor Object (void *data = 0, u_long size = 0, u_long type = REG_NONE); - // Default constructor + /// Set/Get data void data (void *data); void *data (void) const; - // Set/Get data + /// Set/Get size void size (u_long size); u_long size (void) const; - // Set/Get size + /// Set/Get type void type (u_long type); u_long type (void) const; - // Set/Get type private: + /// Pointer to data void *data_; - // Pointer to data + /// Size of the data u_long size_; - // Size of the data + /// Type of data u_long type_; - // Type of data }; + /** + * @class Naming_Context + * + * @brief An context representation + * + * Think about a context as being similar to a directory + * in a file system. + */ class ACE_Export Naming_Context { - // = TITLE - // An context representation - // - // = DESCRIPTION - // Think about a context as being similar to a directory - // in a file system. public: + /// Friend factory friend class ACE_Predefined_Naming_Contexts; - // Friend factory - enum { MAX_OBJECT_NAME_SIZE = BUFSIZ, - MAX_CONTEXT_NAME_SIZE = MAXPATHLEN + 1 }; - // Max sizes of names - // (Not too sure about this value) + enum { + /// Max sizes of names + /// (Not too sure about this value) + MAX_OBJECT_NAME_SIZE = BUFSIZ, + + /// Max size of context name + MAX_CONTEXT_NAME_SIZE = MAXPATHLEN + 1 + }; + /// Empty constructor: keys will be NULL Naming_Context (void); - // Empty constructor: keys will be NULL + /// Constructor: key_ will be set to <key> Naming_Context (const HKEY &key); - // Constructor: key_ will be set to <key> + /// Destructor will call <Naming_Context::close>. ~Naming_Context (void); - // Destructor will call <Naming_Context::close>. // The following interfaces are for objects + /** + * Insert <object> with <name> into <this> context + * This will fail if <name> already exists + * (Name version) + */ int bind_new (const Name &name, const Object &object); - // Insert <object> with <name> into <this> context - // This will fail if <name> already exists - // (Name version) + /** + * Insert <object> with <name> into <this> context + * This will fail if <name> already exists + * (String version) + */ int bind_new (const ACE_TString &name, const Object &object); - // Insert <object> with <name> into <this> context - // This will fail if <name> already exists - // (String version) + /** + * Insert or update <object> with <name> into <this> context + * This will not fail if <name> already exists + * (Name version) + */ int bind (const Name &name, const Object &object); - // Insert or update <object> with <name> into <this> context - // This will not fail if <name> already exists - // (Name version) + /** + * Insert or update <object> with <name> into <this> context + * This will not fail if <name> already exists + * (String version) + */ int bind (const ACE_TString &name, const Object &object); - // Insert or update <object> with <name> into <this> context - // This will not fail if <name> already exists - // (String version) + /// Update <object> with <name> in <this> context + /// (Name version) int rebind (const Name &name, const Object &object); - // Update <object> with <name> in <this> context - // (Name version) + /// Update <object> with <name> in <this> context int rebind (const ACE_TString &name, const Object &object); - // Update <object> with <name> in <this> context + /// Find <object> with <name> in <this> context + /// (Name version) int resolve (const Name &name, Object &object); - // Find <object> with <name> in <this> context - // (Name version) + /// Find <object> with <name> in <this> context int resolve (const ACE_TString &name, Object &object); - // Find <object> with <name> in <this> context + /// Delete object with <name> in <this> context + /// (Name version) int unbind (const Name &name); - // Delete object with <name> in <this> context - // (Name version) + /// Delete object with <name> in <this> context int unbind (const ACE_TString &name); - // Delete object with <name> in <this> context // The following interfaces are for Naming Context + /// Create new <naming_context> int new_context (Naming_Context &naming_context); - // Create new <naming_context> + /** + * Insert <naming_context> with <name> relative to <this> context + * This will fail if <name> already exists + * (Name version) + */ int bind_new_context (const Name &name, Naming_Context &naming_context, u_long persistence = REG_OPTION_NON_VOLATILE, u_long security_access = KEY_ALL_ACCESS, LPSECURITY_ATTRIBUTES security_attributes = 0); - // Insert <naming_context> with <name> relative to <this> context - // This will fail if <name> already exists - // (Name version) + /// Insert <naming_context> with <name> relative to <this> context + /// This will fail if <name> already exists int bind_new_context (const ACE_TString &name, Naming_Context &naming_context, u_long persistence = REG_OPTION_NON_VOLATILE, u_long security_access = KEY_ALL_ACCESS, LPSECURITY_ATTRIBUTES security_attributes = 0); - // Insert <naming_context> with <name> relative to <this> context - // This will fail if <name> already exists + /** + * Insert or update <naming_context> with <name> relative to <this> context + * This will not fail if <name> already exists + * (Name version) + */ int bind_context (const Name &name, /* const */ Naming_Context &naming_context, u_long persistence = REG_OPTION_NON_VOLATILE, u_long security_access = KEY_ALL_ACCESS, LPSECURITY_ATTRIBUTES security_attributes = 0); - // Insert or update <naming_context> with <name> relative to <this> context - // This will not fail if <name> already exists - // (Name version) + /// Insert or update <naming_context> with <name> relative to <this> context + /// This will not fail if <name> already exists int bind_context (const ACE_TString &name, /* const */ Naming_Context &naming_context, u_long persistence = REG_OPTION_NON_VOLATILE, u_long security_access = KEY_ALL_ACCESS, LPSECURITY_ATTRIBUTES security_attributes = 0); - // Insert or update <naming_context> with <name> relative to <this> context - // This will not fail if <name> already exists + /// Rename <naming_context> to <name> + /// (Name version) int rebind_context (const Name &name, /* const */ Naming_Context &naming_context); - // Rename <naming_context> to <name> - // (Name version) + /// Rename <naming_context> to <name> int rebind_context (const ACE_TString &name, /* const */ Naming_Context &naming_context); - // Rename <naming_context> to <name> + /// Find <naming_context> with <name> in <this> context + /// (Name version) int resolve_context (const Name &name, Naming_Context &naming_context, u_long security_access = KEY_ALL_ACCESS); - // Find <naming_context> with <name> in <this> context - // (Name version) + /// Find <naming_context> with <name> in <this> context int resolve_context (const ACE_TString &name, Naming_Context &naming_context, u_long security_access = KEY_ALL_ACCESS); - // Find <naming_context> with <name> in <this> context + /// Remove naming_context with <name> from <this> context + /// (Name version) int unbind_context (const Name &name); - // Remove naming_context with <name> from <this> context - // (Name version) + /// Remove naming_context with <name> from <this> context int unbind_context (const ACE_TString &name); - // Remove naming_context with <name> from <this> context + /// Same as <unbind_context> with <this> as naming_context int destroy (void); - // Same as <unbind_context> with <this> as naming_context + /** + * listing function: iterator creator + * This is useful when there are many objects and contexts + * in <this> context and you only want to look at a few entries + * at a time + */ int list (u_long how_many, Binding_List &list, Binding_Iterator &iterator); - // listing function: iterator creator - // This is useful when there are many objects and contexts - // in <this> context and you only want to look at a few entries - // at a time + /// listing function: iterator creator + /// This gives back a listing of all entries in <this> context. int list (Binding_List &list); - // listing function: iterator creator - // This gives back a listing of all entries in <this> context. // Some other necessary functions which are // not part of the CORBA interface + /// Sync content of context to disk int flush (void); - // Sync content of context to disk + /// Close the handle of the context + /// Note: <close> does not call <flush> int close (void); - // Close the handle of the context - // Note: <close> does not call <flush> // Accessors + /// Get key HKEY key (void); - // Get key // void parent (HKEY parent); + /// Get parent HKEY parent (void); - // Get parent + /// Get name + /// (Name version) void name (Name &name); - // Get name - // (Name version) + /// Get name + /// (String version) void name (ACE_TString &name); ACE_TString name (void); - // Get name - // (String version) protected: + /// Set key void key (HKEY key); - // Set key + /// Set parent void parent (HKEY parent); - // Set parent + /// Set name + /// (Name version) void name (const Name &name); - // Set name - // (Name version) + /// Set name + /// (String version) void name (const ACE_TString &name); - // Set name - // (String version) private: + /// Disallow copy constructors Naming_Context (const Naming_Context &rhs); - // Disallow copy constructors + /// Disallow assignment const Naming_Context &operator= (const Naming_Context &rhs); - // Disallow assignment + /// Key for self HKEY key_; - // Key for self + /// Key for parent HKEY parent_key_; - // Key for parent + /// Name of self ACE_TString name_; - // Name of self }; + /** + * @class Binding_Iterator + * + * @brief An iterator + * + * Useful when iteratorating over a few entries at a time + */ class ACE_Export Binding_Iterator { - // = TITLE - // An iterator - // - // = DESCRIPTION - // Useful when iteratorating over a few entries at a time public: + /// Friend factory friend class Naming_Context; - // Friend factory + /// Default constructor Binding_Iterator (void); - // Default constructor + /// Next entry int next_one (Binding &binding); - // Next entry + /// Next <how_many> entries int next_n (u_long how_many, Binding_List &list); - // Next <how_many> entries + /// Cleanup int destroy (void); - // Cleanup + /// Reset the internal state of the iterator void reset (void); - // Reset the internal state of the iterator + /// Get naming_context that the iterator is iterating over Naming_Context &naming_context (void); - // Get naming_context that the iterator is iterating over private: + /// Set naming_context that the iterator is iterating over void naming_context (Naming_Context& naming_context); - // Set naming_context that the iterator is iterating over + /// Reference to context Naming_Context *naming_context_; - // Reference to context public: // This should really be private // But the compiler is broken +/** + * @class Iteration_State + Base class for state + */ class ACE_Export Iteration_State - // Base class for state { public: Iteration_State (Binding_Iterator &iterator); + /// Next <how_many> entries virtual int next_n (u_long how_many, Binding_List &list) = 0; - // Next <how_many> entries + /// Reset state void reset (void); - // Reset state protected: + /// Pointer to parent iterator Binding_Iterator *parent_; - // Pointer to parent iterator u_long index_; }; @@ -444,9 +476,9 @@ public: public: Object_Iteration (Binding_Iterator &iterator); + /// Next <how_many> entries int next_n (u_long how_many, Binding_List &list); - // Next <how_many> entries }; class ACE_Export Context_Iteration : public Iteration_State @@ -454,9 +486,9 @@ public: public: Context_Iteration (Binding_Iterator &iterator); + /// Next <how_many> entries int next_n (u_long how_many, Binding_List &list); - // Next <how_many> entries }; class ACE_Export Iteration_Complete : public Iteration_State @@ -464,52 +496,56 @@ public: public: Iteration_Complete (Binding_Iterator &iterator); + /// Next <how_many> entries int next_n (u_long how_many, Binding_List &list); - // Next <how_many> entries }; + /// Friend states friend class Iteration_State; friend class Object_Iteration; friend class Context_Iteration; friend class Iteration_Complete; - // Friend states + /// Instances of all states Object_Iteration object_iteration_; Context_Iteration context_iteration_; Iteration_Complete iteration_complete_; - // Instances of all states + /// Pointer to current state Iteration_State *current_enumeration_; - // Pointer to current state + /// Set/Get current_enumeration void current_enumeration (Iteration_State& current_enumeration); Iteration_State ¤t_enumeration (void); - // Set/Get current_enumeration }; }; +/** + * @class ACE_Predefined_Naming_Contexts + * + * @brief A factory for predefined registries, which exist by default + * on Win32 platforms + * + * This factory can connect to both local and remote + * predefined registries. + */ class ACE_Export ACE_Predefined_Naming_Contexts { - // = TITLE - // A factory for predefined registries, which exist by default - // on Win32 platforms - // - // = DESCRIPTION - // This factory can connect to both local and remote - // predefined registries. public: + /** + * Factory method for connecting to predefined registries. This + * method works for both remote and local machines. However, for + * remote machines, HKEY_CLASSES_ROOT and HKEY_CURRENT_USER types + * are not allowed + */ static int connect (ACE_Registry::Naming_Context &naming_context, HKEY predefined = HKEY_LOCAL_MACHINE, const ACE_TCHAR *machine_name = 0); - // Factory method for connecting to predefined registries. This - // method works for both remote and local machines. However, for - // remote machines, HKEY_CLASSES_ROOT and HKEY_CURRENT_USER types - // are not allowed private: + /// Check if <machine_name> is the local host static int is_local_host (const ACE_TCHAR *machine_name); - // Check if <machine_name> is the local host }; // Fix me! Shouldn't have to define this stuff diff --git a/ace/Registry_Name_Space.h b/ace/Registry_Name_Space.h index 2c1458a7aa8..439cd14b488 100644 --- a/ace/Registry_Name_Space.h +++ b/ace/Registry_Name_Space.h @@ -1,18 +1,15 @@ /*-*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Registry_Name_Space.h -// -// = AUTHOR -// Irfan Pyarali (irfan@cs.wustl.edu) -// -// ============================================================================ + +//============================================================================= +/** + * @file Registry_Name_Space.h + * + * $Id$ + * + * @author Irfan Pyarali (irfan@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_REGISTRY_NAME_SPACE_H #define ACE_REGISTRY_NAME_SPACE_H @@ -31,95 +28,105 @@ #include "ace/Naming_Context.h" #include "ace/Name_Space.h" +/** + * @class ACE_Registry_Name_Space + * + * @brief Interface to a Name Server Database which is maintained by + * the Win32 Registry. Allows to add, change, remove and + * resolve NameBindings. + * + * Manages a Naming Service for a registry name space which + * includes bindings for all contexts. All strings are stored in + * wide character format. A Name Binding consists of a name + * (that's the key), a value string. There is no type string + * support in this Name Space. + */ class ACE_Export ACE_Registry_Name_Space : public ACE_Name_Space { - // = TITLE - // Interface to a Name Server Database which is maintained by - // the Win32 Registry. Allows to add, change, remove and - // resolve NameBindings. - // - // = DESCRIPTION - // Manages a Naming Service for a registry name space which - // includes bindings for all contexts. All strings are stored in - // wide character format. A Name Binding consists of a name - // (that's the key), a value string. There is no type string - // support in this Name Space. public: + /// Constructor ACE_Registry_Name_Space (void); - // Constructor + /// Contacts and opens the registry on the specified server ACE_Registry_Name_Space (ACE_Name_Options *name_options); - // Contacts and opens the registry on the specified server + /// Destructor ~ACE_Registry_Name_Space (void); - // Destructor + /// Contacts and opens the registry on the specified server int open (ACE_Name_Options *name_options); - // Contacts and opens the registry on the specified server + /// Bind a new name to a naming context (Wide character strings). int bind (const ACE_WString &name_in, const ACE_WString &value_in, const char *type_in = ""); - // Bind a new name to a naming context (Wide character strings). + /** + * Overwrite the value or type of an existing name in a + * ACE_Name_Space or bind a new name to the context, if it didn't + * exist yet. (Wide charcter strings interface). + */ int rebind (const ACE_WString &name_in, const ACE_WString &value_in, const char *type_in = ""); - // Overwrite the value or type of an existing name in a - // ACE_Name_Space or bind a new name to the context, if it didn't - // exist yet. (Wide charcter strings interface). + /// Delete a name from a ACE_Name_Space (Wide charcter strings + /// Interface). int unbind (const ACE_WString &name_in); - // Delete a name from a ACE_Name_Space (Wide charcter strings - // Interface). + /// Get value and type of a given name binding (Wide chars). The + /// caller is responsible for deleting both <value_out> and <type_out>! int resolve (const ACE_WString &name_in, ACE_WString &value_out, char *&type_out); - // Get value and type of a given name binding (Wide chars). The - // caller is responsible for deleting both <value_out> and <type_out>! + /// Get a set of names matching a specified pattern (wchars). Matching + /// means the names must begin with the pattern string. int list_names (ACE_WSTRING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of names matching a specified pattern (wchars). Matching - // means the names must begin with the pattern string. + /// Get a set of values matching a specified pattern (wchars). Matching + /// means the values must begin with the pattern string. int list_values (ACE_WSTRING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of values matching a specified pattern (wchars). Matching - // means the values must begin with the pattern string. + /// Get a set of types matching a specified pattern (wchars). Matching + /// means the types must begin with the pattern string. int list_types (ACE_WSTRING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of types matching a specified pattern (wchars). Matching - // means the types must begin with the pattern string. + /** + * Get a set of names matching a specified pattern (wchars). Matching + * means the names must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ int list_name_entries (ACE_BINDING_SET &set, const ACE_WString &pattern); - // Get a set of names matching a specified pattern (wchars). Matching - // means the names must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of values matching a specified pattern (wchars). Matching + * means the values must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ int list_value_entries (ACE_BINDING_SET &set, const ACE_WString &pattern); - // Get a set of values matching a specified pattern (wchars). Matching - // means the values must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of types matching a specified pattern (wchars). Matching + * means the types must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ int list_type_entries (ACE_BINDING_SET &set, const ACE_WString &pattern); - // Get a set of types matching a specified pattern (wchars). Matching - // means the types must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /// Dump the state of the object void dump (void) const; - // Dump the state of the object private: + /// current context ACE_Registry::Naming_Context context_; - // current context }; #endif /* ACE_WIN32 && UNICODE */ diff --git a/ace/Remote_Name_Space.h b/ace/Remote_Name_Space.h index 2e44e7dd9f9..1e8bcb795b8 100644 --- a/ace/Remote_Name_Space.h +++ b/ace/Remote_Name_Space.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Remote_Name_Space.h -// -// = AUTHOR -// Prashant Jain -// -// ============================================================================ + +//============================================================================= +/** + * @file Remote_Name_Space.h + * + * $Id$ + * + * @author Prashant Jain + */ +//============================================================================= + #ifndef ACE_REMOTE_NAME_SPACE_H #define ACE_REMOTE_NAME_SPACE_H @@ -31,99 +28,113 @@ typedef ACE_Unbounded_Set<ACE_WString> ACE_WSTRING_SET; +/** + * @class ACE_Remote_Name_Space + * + * @brief Maintaining accesses Remote Name Server Database. Allows to + * add NameBindings, change them, remove them and resolve + * NameBindings. + * + * Manages a Naming Service for a remote name space which + * includes bindings for net_local naming context. All strings + * are stored in wide character format. A Name Binding consists + * of a name (that's the key), a value string and an optional + * type string (no wide chars). + */ class ACE_Export ACE_Remote_Name_Space : public ACE_Name_Space { - // = TITLE - // Maintaining accesses Remote Name Server Database. Allows to - // add NameBindings, change them, remove them and resolve - // NameBindings. - // - // = DESCRIPTION - // Manages a Naming Service for a remote name space which - // includes bindings for net_local naming context. All strings - // are stored in wide character format. A Name Binding consists - // of a name (that's the key), a value string and an optional - // type string (no wide chars). public: // = Initialization and termination methods. + /// "Do-nothing" constructor. ACE_Remote_Name_Space (void); - // "Do-nothing" constructor. + /** + * Specifies the scope of this namespace, opens and memory-maps the + * associated file (if accessible) or contacts the dedicated name + * server process for NET_LOCAL namespace. + */ ACE_Remote_Name_Space (const ACE_TCHAR *hostname, u_short port); - // Specifies the scope of this namespace, opens and memory-maps the - // associated file (if accessible) or contacts the dedicated name - // server process for NET_LOCAL namespace. + /** + * Specifies the scope of this namespace, opens and memory-maps the + * associated file (if accessible) or contacts the dedicated name + * server process for NET_LOCAL namespace. + */ int open (const ACE_TCHAR *servername, u_short port); - // Specifies the scope of this namespace, opens and memory-maps the - // associated file (if accessible) or contacts the dedicated name - // server process for NET_LOCAL namespace. + /// destructor, do some cleanup :TBD: last dtor should "compress" + /// file ~ACE_Remote_Name_Space (void); - // destructor, do some cleanup :TBD: last dtor should "compress" - // file + /// Bind a new name to a naming context (Wide character strings). virtual int bind (const ACE_WString &name_in, const ACE_WString &value_in, const char *type_in = ""); - // Bind a new name to a naming context (Wide character strings). + /** + * Overwrite the value or type of an existing name in a + * ACE_Remote_Name_Space or bind a new name to the context, if it + * didn't exist yet. (Wide charcter strings interface). + */ virtual int rebind (const ACE_WString &name_in, const ACE_WString &value_in, const char *type_in = ""); - // Overwrite the value or type of an existing name in a - // ACE_Remote_Name_Space or bind a new name to the context, if it - // didn't exist yet. (Wide charcter strings interface). + /// Delete a name from a ACE_Remote_Name_Space (Wide charcter strings + /// Interface). virtual int unbind (const ACE_WString &name_in); - // Delete a name from a ACE_Remote_Name_Space (Wide charcter strings - // Interface). + /// Get value and type of a given name binding (Wide chars). The + /// caller is responsible for deleting both <value_out> and <type_out>! virtual int resolve (const ACE_WString &name_in, ACE_WString &value_out, char *&type_out); - // Get value and type of a given name binding (Wide chars). The - // caller is responsible for deleting both <value_out> and <type_out>! + /// Get a set of names matching a specified pattern (wchars). Matching + /// means the names must begin with the pattern string. virtual int list_names (ACE_WSTRING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of names matching a specified pattern (wchars). Matching - // means the names must begin with the pattern string. + /// Get a set of values matching a specified pattern (wchars). Matching + /// means the values must begin with the pattern string. virtual int list_values (ACE_WSTRING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of values matching a specified pattern (wchars). Matching - // means the values must begin with the pattern string. + /// Get a set of types matching a specified pattern (wchars). Matching + /// means the types must begin with the pattern string. virtual int list_types (ACE_WSTRING_SET &set_out, const ACE_WString &pattern_in); - // Get a set of types matching a specified pattern (wchars). Matching - // means the types must begin with the pattern string. + /** + * Get a set of names matching a specified pattern (wchars). Matching + * means the names must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_name_entries (ACE_BINDING_SET &set, const ACE_WString &pattern); - // Get a set of names matching a specified pattern (wchars). Matching - // means the names must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of values matching a specified pattern (wchars). Matching + * means the values must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_value_entries (ACE_BINDING_SET &set, const ACE_WString &pattern); - // Get a set of values matching a specified pattern (wchars). Matching - // means the values must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /** + * Get a set of types matching a specified pattern (wchars). Matching + * means the types must begin with the pattern string. Returns the + * complete binding associated each pattern match. + */ virtual int list_type_entries (ACE_BINDING_SET &set, const ACE_WString &pattern); - // Get a set of types matching a specified pattern (wchars). Matching - // means the types must begin with the pattern string. Returns the - // complete binding associated each pattern match. + /// Dump the state of the object. virtual void dump (void) const; - // Dump the state of the object. private: + /// Interface to Name server process for NET_LOCAL namespace. ACE_Name_Proxy ns_proxy_; - // Interface to Name server process for NET_LOCAL namespace. }; #include "ace/post.h" diff --git a/ace/Remote_Tokens.h b/ace/Remote_Tokens.h index c0e2fb041f8..54c486d4723 100644 --- a/ace/Remote_Tokens.h +++ b/ace/Remote_Tokens.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Remote_Tokens.h -// -// = AUTHOR -// Douglas C. Schmidt (schmidt@cs.wustl.edu) and -// Tim Harrison (harrison@cs.wustl.edu) -// -// ============================================================================ + +//============================================================================= +/** + * @file Remote_Tokens.h + * + * $Id$ + * + * @author Douglas C. Schmidt (schmidt@cs.wustl.edu) + * @author Tim Harrison (harrison@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_REMOTE_MUTEX_H #define ACE_REMOTE_MUTEX_H @@ -31,159 +28,178 @@ #include "ace/Local_Tokens.h" #include "ace/Token_Request_Reply.h" +/** + * @class ACE_Remote_Token_Proxy + * + * @brief Proxy for acquiring, renewing, and releasing a distributed + * synchronization token. + * + * The Remote_Token_Proxy class implements the mechanisms for + * distributed token operations. It is similar to the + * ACE_Token_Proxy. + * = BUGS + * Distributed sleep_hooks have not been implemented. <owner_id> + * is not implemented. + */ class ACE_Export ACE_Remote_Token_Proxy : public ACE_Token_Proxy { - // = TITLE - // Proxy for acquiring, renewing, and releasing a distributed - // synchronization token. - // - // = DESCRIPTION - // The Remote_Token_Proxy class implements the mechanisms for - // distributed token operations. It is similar to the - // ACE_Token_Proxy. - // - // = BUGS - // Distributed sleep_hooks have not been implemented. <owner_id> - // is not implemented. public: + /// Null construction. ACE_Remote_Token_Proxy (void); - // Null construction. + /// Death. virtual ~ACE_Remote_Token_Proxy (void); - // Death. + /** + * Same as Token_Proxy. <name> is the string uniquely identifying + * the token. <ignore_deadlock> can be 1 to disable deadlock + * notifications. <debug> prints debug messages. + */ int open (const ACE_TCHAR *name, int ignore_deadlock = 0, int debug = 0); - // Same as Token_Proxy. <name> is the string uniquely identifying - // the token. <ignore_deadlock> can be 1 to disable deadlock - // notifications. <debug> prints debug messages. + /** + * Open a connection with the token server. This only need be used + * when the user wishes to explicitly open a connection to check if + * the server exists. Connections are stored in the + * ACE_Token_Connections singleton as thread-specific data. That + * is, every thread has only one connection that is used for all + * remote tokens. + */ int initiate_connection (void); - // Open a connection with the token server. This only need be used - // when the user wishes to explicitly open a connection to check if - // the server exists. Connections are stored in the - // ACE_Token_Connections singleton as thread-specific data. That - // is, every thread has only one connection that is used for all - // remote tokens. + /** + * Acquire the distributed token. If notify is specified and the + * token is already held, the owner is notified. options contains + * the timeout value for the acquire call. The timer is kept at the + * token server. Asynchronous operations are not supported. + * Returns 0 on success, -1 on failure with <errno> == problem. + */ virtual int acquire (int notify = 0, void (*sleep_hook)(void *) = 0, ACE_Synch_Options &options = ACE_Synch_Options::synch); - // Acquire the distributed token. If notify is specified and the - // token is already held, the owner is notified. options contains - // the timeout value for the acquire call. The timer is kept at the - // token server. Asynchronous operations are not supported. - // Returns 0 on success, -1 on failure with <errno> == problem. + /** + * Try to acquire the distributed token. If the token is already + * held, the call returns without queueing the caller as a waiter. + * Returns 0 on success (the token was acquired), and -1 with + * EWOULDBLOCK if the token was already held. + */ virtual int tryacquire (void (*sleep_hook)(void *) = 0); - // Try to acquire the distributed token. If the token is already - // held, the call returns without queueing the caller as a waiter. - // Returns 0 on success (the token was acquired), and -1 with - // EWOULDBLOCK if the token was already held. + /** + * Renew the token by offering to release it if there are any other + * waiters, otherwise get the token back immediately. This renew + * has the same semantics as ACE_Local_Mutex release. It is + * semantically equivalent to <release> followed by <acquire>, but + * it is faster. options contains the timeout value used if renew + * blocks. As with acquire, the timer is maintained at the token + * server. If there are waiters and requeue_position == -1, the + * caller is queued at the rear of the waiter list. Otherwise, + * requeue_position specifies the number of waiters to "let by" + * before reacquiring the token (effectively, the position in the + * waiter list.) + */ virtual int renew (int requeue_position = 0, ACE_Synch_Options &options = ACE_Synch_Options::synch); - // Renew the token by offering to release it if there are any other - // waiters, otherwise get the token back immediately. This renew - // has the same semantics as ACE_Local_Mutex release. It is - // semantically equivalent to <release> followed by <acquire>, but - // it is faster. options contains the timeout value used if renew - // blocks. As with acquire, the timer is maintained at the token - // server. If there are waiters and requeue_position == -1, the - // caller is queued at the rear of the waiter list. Otherwise, - // requeue_position specifies the number of waiters to "let by" - // before reacquiring the token (effectively, the position in the - // waiter list.) + /** + * Release the distributed token. Similar to ACE_Local_Mutex, if the + * caller is not the owner, it is removed from the waiter list (if + * applicable.) Returns 0 on success, -1 on failure with <errno> == + * problem. + */ virtual int release (ACE_Synch_Options &options = ACE_Synch_Options::synch); - // Release the distributed token. Similar to ACE_Local_Mutex, if the - // caller is not the owner, it is removed from the waiter list (if - // applicable.) Returns 0 on success, -1 on failure with <errno> == - // problem. + /// Become interface compliant for ACE_Guard<>. This has no + /// functionality. virtual int remove (ACE_Synch_Options &options = ACE_Synch_Options::synch); - // Become interface compliant for ACE_Guard<>. This has no - // functionality. + /// Override the default to do nothing. virtual void token_acquired (ACE_TPQ_Entry *); - // Override the default to do nothing. + /// the client id of the current token holder virtual const ACE_TCHAR* owner_id (void); - // the client id of the current token holder + /** + * sets the server address for all instances of ACE_Remote_Token_Proxy + * If this isn't called, the environment variable TOKEN_SERVER is + * checked for the server address. If that is not specified, all + * ACE_Remote_** operations will fail. + */ static void set_server_address (const ACE_INET_Addr &server_address); - // sets the server address for all instances of ACE_Remote_Token_Proxy - // If this isn't called, the environment variable TOKEN_SERVER is - // checked for the server address. If that is not specified, all - // ACE_Remote_** operations will fail. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. protected: + /// if shadows report deadlock, go remote anyway int ignore_shadow_deadlock_; - // if shadows report deadlock, go remote anyway + /// Perform the request and wait for the reply. int request_reply (ACE_Token_Request &request, ACE_Synch_Options &options); - // Perform the request and wait for the reply. }; +/** + * @class ACE_Remote_Mutex + * + * @brief Proxy for acquiring, renewing, and releasing a distributed + * mutex. + * + * This is the remote equivalent to ACE_Local_Mutex. The + * Remote_Mutex class offers methods for acquiring, renewing, and + * releasing a distributed synchronization mutex. Similar to + * ACE_Local_Mutex, ACE_Remote_Token_Proxy offers recursive + * acquisition, FIFO waiter ordering, and deadlock detection. It + * depends on the Token Server for its distributed synchronization + * semantics. + */ class ACE_Export ACE_Remote_Mutex : public ACE_Remote_Token_Proxy { - // = TITLE - // Proxy for acquiring, renewing, and releasing a distributed - // mutex. - // - // = DESCRIPTION - // This is the remote equivalent to ACE_Local_Mutex. The - // Remote_Mutex class offers methods for acquiring, renewing, and - // releasing a distributed synchronization mutex. Similar to - // ACE_Local_Mutex, ACE_Remote_Token_Proxy offers recursive - // acquisition, FIFO waiter ordering, and deadlock detection. It - // depends on the Token Server for its distributed synchronization - // semantics. public: + /// Null creation. Remote_Token_Proxy::open must be called. ACE_Remote_Mutex (void); - // Null creation. Remote_Token_Proxy::open must be called. + /// Calls Remote_Token_Proxy::open for you. ACE_Remote_Mutex (const ACE_TCHAR *token_name, int ignore_deadlock = 0, int debug = 0); - // Calls Remote_Token_Proxy::open for you. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// Return deep copy. virtual ACE_Token_Proxy *clone (void) const; - // Return deep copy. protected: + /// Make the correct type of ACE_Tokens. This is called by the Token + /// Manager. virtual ACE_Tokens *create_token (const ACE_TCHAR *name); - // Make the correct type of ACE_Tokens. This is called by the Token - // Manager. }; +/** + * @class ACE_Remote_RLock + * + * @brief Proxy for acquiring, renewing, and releasing a distributed + * readers lock. + * + * This is the remote equivalent to ACE_Local_RLock. Multiple + * readers can hold the lock simultaneously when no writers have + * the lock. Alternatively, when a writer holds the lock, no other + * participants (readers or writers) may hold the lock. + * ACE_Remote_RLock depends on the ACE Token Server for its + * distributed synchronization semantics. + */ class ACE_Export ACE_Remote_RLock : public ACE_Remote_Token_Proxy { - // = TITLE - // Proxy for acquiring, renewing, and releasing a distributed - // readers lock. - // - // = DESCRIPTION - // This is the remote equivalent to ACE_Local_RLock. Multiple - // readers can hold the lock simultaneously when no writers have - // the lock. Alternatively, when a writer holds the lock, no other - // participants (readers or writers) may hold the lock. - // ACE_Remote_RLock depends on the ACE Token Server for its - // distributed synchronization semantics. public: ACE_Remote_RLock (void); @@ -193,33 +209,35 @@ public: ACE_Remote_RLock (const ACE_Remote_RLock &mutex); + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// Returns ACE_RW_Token::RLOCK; virtual int type (void) const; - // Returns ACE_RW_Token::RLOCK; + /// Return deep copy. virtual ACE_Token_Proxy *clone (void) const; - // Return deep copy. protected: + /// Make the correct type of ACE_Tokens. This is called by the Token + /// Manager. virtual ACE_Tokens *create_token (const ACE_TCHAR *name); - // Make the correct type of ACE_Tokens. This is called by the Token - // Manager. }; +/** + * @class ACE_Remote_WLock + * + * @brief Proxy for acquiring, renewing, and releasing a distributed + * writers lock. + * + * Shields applications from details of interacting with the + * ACE_Token_Server. The token_name_ is just the string that the + * Token Server uses to identify the token. The client_id_ (also + * used by the Token Server,) identifies the owner of the token and + * is used for deadlock detection. + */ class ACE_Export ACE_Remote_WLock : public ACE_Remote_Token_Proxy { - // = TITLE - // Proxy for acquiring, renewing, and releasing a distributed - // writers lock. - // - // = DESCRIPTION - // Shields applications from details of interacting with the - // ACE_Token_Server. The token_name_ is just the string that the - // Token Server uses to identify the token. The client_id_ (also - // used by the Token Server,) identifies the owner of the token and - // is used for deadlock detection. public: ACE_Remote_WLock (void); @@ -229,60 +247,62 @@ public: ACE_Remote_WLock (const ACE_Remote_WLock &mutex); + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// Returns ACE_RW_Token::WLOCK; virtual int type (void) const; - // Returns ACE_RW_Token::WLOCK; + /// Return deep copy. virtual ACE_Token_Proxy *clone (void) const; - // Return deep copy. protected: + /// Make the correct type of ACE_Tokens. This is called by the Token + /// Manager. virtual ACE_Tokens *create_token (const ACE_TCHAR *name); - // Make the correct type of ACE_Tokens. This is called by the Token - // Manager. }; +/** + * @class ACE_TSS_Connection + * + * @brief Class for providing a connection per thread. + * + * ACE_TSS_Connection provides a single access point for all + * threads to access thread-specific connections. This prevents + * resource-sharing problems such as thread serialization. + */ class ACE_Export ACE_TSS_Connection : public ACE_TSS<ACE_SOCK_Stream> { - // = TITLE - // Class for providing a connection per thread. - // - // = DESCRIPTION - // ACE_TSS_Connection provides a single access point for all - // threads to access thread-specific connections. This prevents - // resource-sharing problems such as thread serialization. public: // Necessary to make some compilers work... ACE_TSS_Connection (void); ~ACE_TSS_Connection (void); + /// retrieve the thread's connection ACE_SOCK_Stream *get_connection (void); - // retrieve the thread's connection + /// Factory Method that creates a new SOCK Stream. virtual ACE_SOCK_Stream *make_TSS_TYPE (void) const; - // Factory Method that creates a new SOCK Stream. + /// inheritence and operator overloading don't mix. Redefine this + /// from ACE_TSS so that we can use it. operator ACE_SOCK_Stream *(void); - // inheritence and operator overloading don't mix. Redefine this - // from ACE_TSS so that we can use it. + /// Set the server address. static void set_server_address (const ACE_INET_Addr &server_address); - // Set the server address. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. protected: + /// The address of the Token Server used by all instances of + /// Token_Proxy. static ACE_INET_Addr server_address_; - // The address of the Token Server used by all instances of - // Token_Proxy. private: + /// Private: should not be used ACE_TSS_Connection (const ACE_TSS_Connection &); void operator= (const ACE_TSS_Connection &); - // Private: should not be used }; #if defined (__ACE_INLINE__) diff --git a/ace/SOCK.h b/ace/SOCK.h index 4c02306a523..48626bf5dd4 100644 --- a/ace/SOCK.h +++ b/ace/SOCK.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -//============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SOCK.h -// -// = AUTHOR -// Doug Schmidt -// -//============================================================================ + +//============================================================================= +/** + * @file SOCK.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SOCK_H #define ACE_SOCK_H @@ -28,58 +25,63 @@ #include "ace/IPC_SAP.h" #include "ace/QoS_Session.h" +/** + * @class ACE_SOCK + * + * @brief An abstract class that forms the basis for more specific + * classes, such as <ACE_SOCK_Acceptor> and <ACE_SOCK_Stream>. + * Do not instantiate this class. + * + * This class provides functions that are common to all of the + * <ACE_SOCK_*> classes. <ACE_SOCK> provides the ability to get + * and set socket options, get the local and remote addresses, + * and close the socket. + */ class ACE_Export ACE_SOCK : public ACE_IPC_SAP { - // = TITLE - // An abstract class that forms the basis for more specific - // classes, such as <ACE_SOCK_Acceptor> and <ACE_SOCK_Stream>. - // Do not instantiate this class. - // - // = DESCRIPTION - // This class provides functions that are common to all of the - // <ACE_SOCK_*> classes. <ACE_SOCK> provides the ability to get - // and set socket options, get the local and remote addresses, - // and close the socket. public: + /// Default ctor/dtor. ~ACE_SOCK (void); - // Default ctor/dtor. + /// Wrapper around the <setsockopt> system call. int set_option (int level, int option, void *optval, int optlen) const; - // Wrapper around the <setsockopt> system call. + /// Wrapper around the <getsockopt> system call. int get_option (int level, int option, void *optval, int *optlen) const; - // Wrapper around the <getsockopt> system call. + /// Close down the socket. int close (void); - // Close down the socket. + /// Return the local endpoint address in the referenced <ACE_Addr>. + /// Returns 0 if successful, else -1. int get_local_addr (ACE_Addr &) const; - // Return the local endpoint address in the referenced <ACE_Addr>. - // Returns 0 if successful, else -1. + /** + * Return the address of the remotely connected peer (if there is + * one), in the referenced <ACE_Addr>. Returns 0 if successful, else + * -1. + */ int get_remote_addr (ACE_Addr &) const; - // Return the address of the remotely connected peer (if there is - // one), in the referenced <ACE_Addr>. Returns 0 if successful, else - // -1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /// Wrapper around the BSD-style <socket> system call (no QoS). int open (int type, int protocol_family, int protocol, int reuse_addr); - // Wrapper around the BSD-style <socket> system call (no QoS). + /// Wrapper around the QoS-enabled <WSASocket> function. int open (int type, int protocol_family, int protocol, @@ -87,16 +89,17 @@ public: ACE_SOCK_GROUP g, u_long flags, int reuse_addr); - // Wrapper around the QoS-enabled <WSASocket> function. - + protected: + /// Constructor with arguments to call the BSD-style <socket> system + /// call (no QoS). ACE_SOCK (int type, int protocol_family, int protocol = 0, int reuse_addr = 0); - // Constructor with arguments to call the BSD-style <socket> system - // call (no QoS). + /// Constructor with arguments to call the QoS-enabled <WSASocket> + /// function. ACE_SOCK (int type, int protocol_family, int protocol, @@ -104,12 +107,10 @@ protected: ACE_SOCK_GROUP g, u_long flags, int reuse_addr); - // Constructor with arguments to call the QoS-enabled <WSASocket> - // function. + /// Default constructor is private to prevent instances of this class + /// from being defined. ACE_SOCK (void); - // Default constructor is private to prevent instances of this class - // from being defined. }; @@ -119,7 +120,3 @@ protected: #include "ace/post.h" #endif /* ACE_SOCK_H */ - - - - diff --git a/ace/SOCK_Acceptor.h b/ace/SOCK_Acceptor.h index b4871f328c8..5a65b0e46af 100644 --- a/ace/SOCK_Acceptor.h +++ b/ace/SOCK_Acceptor.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SOCK_Acceptor.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file SOCK_Acceptor.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SOCK_ACCEPTOR_H #define ACE_SOCK_ACCEPTOR_H @@ -26,32 +23,38 @@ #include "ace/Time_Value.h" +/** + * @class ACE_SOCK_Acceptor + * + * @brief Defines a factory that creates new <ACE_Stream>s passively. + * + * The <ACE_SOCK_Acceptor> has its own "passive-mode" socket. + * This serves as a factory to create so-called "data-mode" + * sockets, which are what the <ACE_SOCK_Stream> encapsulates. + * Therefore, by inheriting from <ACE_SOCK>, <ACE_SOCK_Acceptor> + * gets its very own socket. + */ class ACE_Export ACE_SOCK_Acceptor : public ACE_SOCK { - // = TITLE - // Defines a factory that creates new <ACE_Stream>s passively. - // - // = DESCRIPTION - // The <ACE_SOCK_Acceptor> has its own "passive-mode" socket. - // This serves as a factory to create so-called "data-mode" - // sockets, which are what the <ACE_SOCK_Stream> encapsulates. - // Therefore, by inheriting from <ACE_SOCK>, <ACE_SOCK_Acceptor> - // gets its very own socket. public: // = Initialization and termination methods. + /// Default constructor. ACE_SOCK_Acceptor (void); - // Default constructor. + /** + * Initialize a passive-mode BSD-style acceptor socket (no QoS). + * <local_sap> is the address that we're going to listen for + * connections on. If <reuse_addr> is 1 then we'll use the + * <SO_REUSEADDR> to reuse this address. + */ ACE_SOCK_Acceptor (const ACE_Addr &local_sap, int reuse_addr = 0, int protocol_family = PF_INET, int backlog = ACE_DEFAULT_BACKLOG, int protocol = 0); - // Initialize a passive-mode BSD-style acceptor socket (no QoS). - // <local_sap> is the address that we're going to listen for - // connections on. If <reuse_addr> is 1 then we'll use the - // <SO_REUSEADDR> to reuse this address. + /// Initialize a passive-mode QoS-enabled acceptor socket. Returns 0 + /// on success and -1 on failure. ACE_SOCK_Acceptor (const ACE_Addr &local_sap, ACE_Protocol_Info *protocolinfo, ACE_SOCK_GROUP g, @@ -60,20 +63,22 @@ public: int protocol_family, int backlog = ACE_DEFAULT_BACKLOG, int protocol = 0); - // Initialize a passive-mode QoS-enabled acceptor socket. Returns 0 - // on success and -1 on failure. + /** + * Initialize a passive-mode BSD-style acceptor socket (no QoS). + * <local_sap> is the address that we're going to listen for + * connections on. If <reuse_addr> is 1 then we'll use the + * <SO_REUSEADDR> to reuse this address. Returns 0 on success and + * -1 on failure. + */ int open (const ACE_Addr &local_sap, int reuse_addr = 0, int protocol_family = PF_INET, int backlog = ACE_DEFAULT_BACKLOG, int protocol = 0); - // Initialize a passive-mode BSD-style acceptor socket (no QoS). - // <local_sap> is the address that we're going to listen for - // connections on. If <reuse_addr> is 1 then we'll use the - // <SO_REUSEADDR> to reuse this address. Returns 0 on success and - // -1 on failure. + /// Initialize a passive-mode QoS-enabled acceptor socket. Returns 0 + /// on success and -1 on failure. int open (const ACE_Addr &local_sap, ACE_Protocol_Info *protocolinfo, ACE_SOCK_GROUP g, @@ -82,74 +87,78 @@ public: int protocol_family, int backlog = ACE_DEFAULT_BACKLOG, int protocol = 0); - // Initialize a passive-mode QoS-enabled acceptor socket. Returns 0 - // on success and -1 on failure. + /// Default dtor. ~ACE_SOCK_Acceptor (void); - // Default dtor. // = Passive connection <accept> methods. + /** + * Accept a new <ACE_SOCK_Stream> connection. A <timeout> of 0 + * means block forever, a <timeout> of {0, 0} means poll. <restart> + * == 1 means "restart if interrupted," i.e., if errno == EINTR. + * Note that <new_stream> inherits the "blocking mode" of <this> + * <ACE_SOCK_Acceptor>, i.e., if <this> acceptor factory is in + * non-blocking mode, the <net_stream> will be in non-blocking mode + * and vice versa. + */ int accept (ACE_SOCK_Stream &new_stream, ACE_Addr *remote_addr = 0, ACE_Time_Value *timeout = 0, int restart = 1, int reset_new_handle = 0) const; - // Accept a new <ACE_SOCK_Stream> connection. A <timeout> of 0 - // means block forever, a <timeout> of {0, 0} means poll. <restart> - // == 1 means "restart if interrupted," i.e., if errno == EINTR. - // Note that <new_stream> inherits the "blocking mode" of <this> - // <ACE_SOCK_Acceptor>, i.e., if <this> acceptor factory is in - // non-blocking mode, the <net_stream> will be in non-blocking mode - // and vice versa. + /** + * Accept a new <ACE_SOCK_Stream> connection using the QoS + * information in <qos_params>. A <timeout> of 0 means block + * forever, a <timeout> of {0, 0} means poll. <restart> == 1 means + * "restart if interrupted," i.e., if errno == EINTR. Note that + * <new_stream> inherits the "blocking mode" of <this> + * <ACE_SOCK_Acceptor>, i.e., if <this> acceptor factory is in + * non-blocking mode, the <net_stream> will be in non-blocking mode + * and vice versa. + */ int accept (ACE_SOCK_Stream &new_stream, ACE_Accept_QoS_Params qos_params, ACE_Addr *remote_addr = 0, ACE_Time_Value *timeout = 0, int restart = 1, int reset_new_handle = 0) const; - // Accept a new <ACE_SOCK_Stream> connection using the QoS - // information in <qos_params>. A <timeout> of 0 means block - // forever, a <timeout> of {0, 0} means poll. <restart> == 1 means - // "restart if interrupted," i.e., if errno == EINTR. Note that - // <new_stream> inherits the "blocking mode" of <this> - // <ACE_SOCK_Acceptor>, i.e., if <this> acceptor factory is in - // non-blocking mode, the <net_stream> will be in non-blocking mode - // and vice versa. // = Meta-type info typedef ACE_INET_Addr PEER_ADDR; typedef ACE_SOCK_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Perform operations that must occur before <ACE_OS::accept> is + /// called. int shared_accept_start (ACE_Time_Value *timeout, int restart, int &in_blocking_mode) const; - // Perform operations that must occur before <ACE_OS::accept> is - // called. + /// Perform operations that must occur after <ACE_OS::accept> is + /// called. int shared_accept_finish (ACE_SOCK_Stream new_stream, int in_blocking_mode, int reset_new_handle) const; - // Perform operations that must occur after <ACE_OS::accept> is - // called. + /** + * This method factors out the common <open> code and is called by + * both the QoS-enabled <open> method and the BSD-style <open> + * method. + */ int shared_open (const ACE_Addr &local_sap, int protocol_family, int backlog); - // This method factors out the common <open> code and is called by - // both the QoS-enabled <open> method and the BSD-style <open> - // method. private: + /// Do not allow this function to percolate up to this interface... int get_remote_addr (ACE_Addr &) const; - // Do not allow this function to percolate up to this interface... }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/SOCK_CODgram.h b/ace/SOCK_CODgram.h index a865b8075ce..18741c5a1d0 100644 --- a/ace/SOCK_CODgram.h +++ b/ace/SOCK_CODgram.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SOCK_CODgram.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ +//============================================================================= +/** + * @file SOCK_CODgram.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SOCK_CODGRAM_H #define ACE_SOCK_CODGRAM_H @@ -26,15 +23,18 @@ #include "ace/Addr.h" +/** + * @class ACE_SOCK_CODgram + * + * @brief Defines the member functions for the ACE_SOCK connected + * datagram abstraction. + */ class ACE_Export ACE_SOCK_CODgram : public ACE_SOCK_IO { - // = TITLE - // Defines the member functions for the ACE_SOCK connected - // datagram abstraction. public: // = Initialization methods. + /// Default constructor. ACE_SOCK_CODgram (void); - // Default constructor. ACE_SOCK_CODgram (const ACE_Addr &remote_sap, const ACE_Addr &local_sap = ACE_Addr::sap_any, @@ -42,23 +42,23 @@ public: int protocol = 0, int reuse_addr = 0); + /// Default dtor. ~ACE_SOCK_CODgram (void); - // Default dtor. // Initiate a connected dgram. + /// Initiate a connected dgram. int open (const ACE_Addr &remote_sap, const ACE_Addr &local_sap = ACE_Addr::sap_any, int protocol_family = PF_INET, int protocol = 0, int reuse_addr = 0); - // Initiate a connected dgram. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/SOCK_Connector.h b/ace/SOCK_Connector.h index dcbd210e92b..3e0f80fe579 100644 --- a/ace/SOCK_Connector.h +++ b/ace/SOCK_Connector.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SOCK_Connector.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file SOCK_Connector.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SOCK_CONNECTOR_H #define ACE_SOCK_CONNECTOR_H @@ -26,25 +23,42 @@ #include "ace/Time_Value.h" +/** + * @class ACE_SOCK_Connector + * + * @brief Defines a factory that creates new <ACE_Stream>s actively. + * + * The <ACE_SOCK_Connector> doesn't have a socket of its own, + * i.e., it simply "borrows" the one from the ACE_SOCK_Stream + * that's being connected. The reason for this is that the + * underlying socket API doesn't use a "factory" socket to connect + * "data-mode" sockets. Therefore, there's no need to inherit + * <ACE_SOCK_Connector> from <ACE_SOCK>. A nice side-effect of + * this is that <ACE_SOCK_Connector>'s do not store state so they + * can be used reentrantly in multi-threaded programs. + */ class ACE_Export ACE_SOCK_Connector { - // = TITLE - // Defines a factory that creates new <ACE_Stream>s actively. - // - // = DESCRIPTION - // The <ACE_SOCK_Connector> doesn't have a socket of its own, - // i.e., it simply "borrows" the one from the ACE_SOCK_Stream - // that's being connected. The reason for this is that the - // underlying socket API doesn't use a "factory" socket to connect - // "data-mode" sockets. Therefore, there's no need to inherit - // <ACE_SOCK_Connector> from <ACE_SOCK>. A nice side-effect of - // this is that <ACE_SOCK_Connector>'s do not store state so they - // can be used reentrantly in multi-threaded programs. public: // = Initialization and termination methods. + /// Default constructor. ACE_SOCK_Connector (void); - // Default constructor. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + */ ACE_SOCK_Connector (ACE_SOCK_Stream &new_stream, const ACE_Addr &remote_sap, const ACE_Time_Value *timeout = 0, @@ -54,20 +68,24 @@ public: int perms = 0, int protocol_family = PF_INET, int protocol = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <qos_params> contains QoS parameters that are passed + * to the IntServ (RSVP) and DiffServ protocols. The <timeout> is + * the amount of time to wait to connect. If it's 0 then we block + * indefinitely. If *timeout == {0, 0} then the connection is done + * using non-blocking mode. In this case, if the connection can't + * be made immediately the value of -1 is returned with <errno == + * EWOULDBLOCK>. If *timeout > {0, 0} then this is the amount of + * time to wait before timing out. If the time expires before the + * connection is made <errno == ETIME>. The <local_sap> is the + * value of local address to bind to. If it's the default value of + * <ACE_Addr::sap_any> then the user is letting the OS do the + * binding. If <reuse_addr> == 1 then the <local_addr> is reused, + * even if it hasn't been cleanedup yet. + */ ACE_SOCK_Connector (ACE_SOCK_Stream &new_stream, const ACE_Addr &remote_sap, ACE_QoS_Params qos_params, @@ -80,22 +98,23 @@ public: int perms = 0, int protocol_family = PF_INET, int protocol = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <qos_params> contains QoS parameters that are passed - // to the IntServ (RSVP) and DiffServ protocols. The <timeout> is - // the amount of time to wait to connect. If it's 0 then we block - // indefinitely. If *timeout == {0, 0} then the connection is done - // using non-blocking mode. In this case, if the connection can't - // be made immediately the value of -1 is returned with <errno == - // EWOULDBLOCK>. If *timeout > {0, 0} then this is the amount of - // time to wait before timing out. If the time expires before the - // connection is made <errno == ETIME>. The <local_sap> is the - // value of local address to bind to. If it's the default value of - // <ACE_Addr::sap_any> then the user is letting the OS do the - // binding. If <reuse_addr> == 1 then the <local_addr> is reused, - // even if it hasn't been cleanedup yet. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + * Note that the <new_stream> always starts out in blocking mode. + */ int connect (ACE_SOCK_Stream &new_stream, const ACE_Addr &remote_sap, const ACE_Time_Value *timeout = 0, @@ -105,21 +124,24 @@ public: int perms = 0, int protocol_family = PF_INET, int protocol = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. - // Note that the <new_stream> always starts out in blocking mode. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <qos_params> contains QoS parameters that are passed + * to the IntServ (RSVP) and DiffServ protocols. The <timeout> is + * the amount of time to wait to connect. If it's 0 then we block + * indefinitely. If *timeout == {0, 0} then the connection is done + * using non-blocking mode. In this case, if the connection can't + * be made immediately the value of -1 is returned with <errno == + * EWOULDBLOCK>. If *timeout > {0, 0} then this is the amount of + * time to wait before timing out. If the time expires before the + * connection is made <errno == ETIME>. The <local_sap> is the + * value of local address to bind to. If it's the default value of + * <ACE_Addr::sap_any> then the user is letting the OS do the + * binding. If <reuse_addr> == 1 then the <local_addr> is reused, + * even if it hasn't been cleanedup yet. + */ int connect (ACE_SOCK_Stream &new_stream, const ACE_Addr &remote_sap, ACE_QoS_Params qos_params, @@ -132,55 +154,44 @@ public: int perms = 0, int protocol_family = PF_INET, int protocol = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <qos_params> contains QoS parameters that are passed - // to the IntServ (RSVP) and DiffServ protocols. The <timeout> is - // the amount of time to wait to connect. If it's 0 then we block - // indefinitely. If *timeout == {0, 0} then the connection is done - // using non-blocking mode. In this case, if the connection can't - // be made immediately the value of -1 is returned with <errno == - // EWOULDBLOCK>. If *timeout > {0, 0} then this is the amount of - // time to wait before timing out. If the time expires before the - // connection is made <errno == ETIME>. The <local_sap> is the - // value of local address to bind to. If it's the default value of - // <ACE_Addr::sap_any> then the user is letting the OS do the - // binding. If <reuse_addr> == 1 then the <local_addr> is reused, - // even if it hasn't been cleanedup yet. + /// Default dtor. ~ACE_SOCK_Connector (void); - // Default dtor. // = Completion routine. + /** + * Try to complete a non-blocking connection. + * If connection completion is successful then <new_stream> contains + * the connected ACE_SOCK_Stream. If <remote_sap> is non-NULL then it + * will contain the address of the connected peer. + */ int complete (ACE_SOCK_Stream &new_stream, ACE_Addr *remote_sap = 0, const ACE_Time_Value *timeout = 0); - // Try to complete a non-blocking connection. - // If connection completion is successful then <new_stream> contains - // the connected ACE_SOCK_Stream. If <remote_sap> is non-NULL then it - // will contain the address of the connected peer. + /// Resets any event associations on this handle int reset_new_handle (ACE_HANDLE handle); - // Resets any event associations on this handle // = Meta-type info typedef ACE_INET_Addr PEER_ADDR; typedef ACE_SOCK_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Perform operations that ensure the socket is opened using + /// BSD-style semantics (no QoS). int shared_open (ACE_SOCK_Stream &new_stream, int protocol_family, int protocol, int reuse_addr); - // Perform operations that ensure the socket is opened using - // BSD-style semantics (no QoS). + /// Perform operations that ensure the socket is opened using + /// QoS-enabled semantics. int shared_open (ACE_SOCK_Stream &new_stream, int protocol_family, int protocol, @@ -188,18 +199,16 @@ protected: ACE_SOCK_GROUP g, u_long flags, int reuse_addr); - // Perform operations that ensure the socket is opened using - // QoS-enabled semantics. + /// Perform operations that must be called before <ACE_OS::connect>. int shared_connect_start (ACE_SOCK_Stream &new_stream, const ACE_Time_Value *timeout, const ACE_Addr &local_sap); - // Perform operations that must be called before <ACE_OS::connect>. + /// Perform operations that must be called after <ACE_OS::connect>. int shared_connect_finish (ACE_SOCK_Stream &new_stream, const ACE_Time_Value *timeout, int result); - // Perform operations that must be called after <ACE_OS::connect>. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/SOCK_Dgram.h b/ace/SOCK_Dgram.h index 567d5d34142..969fd7f42cd 100644 --- a/ace/SOCK_Dgram.h +++ b/ace/SOCK_Dgram.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// =========================================================================== -// -// = LIBRARY -// ace -// -// = FILENAME -// SOCK_Dgram.h -// -// = AUTHOR -// Doug Schmidt -// -// =========================================================================== + +//============================================================================= +/** + * @file SOCK_Dgram.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SOCK_DGRAM_H #define ACE_SOCK_DGRAM_H @@ -26,23 +23,31 @@ #include "ace/Addr.h" +/** + * @class ACE_SOCK_Dgram + * + * @brief Defines the member functions for the ACE_SOCK datagram + * abstraction. + */ class ACE_Export ACE_SOCK_Dgram : public ACE_SOCK { - // = TITLE - // Defines the member functions for the ACE_SOCK datagram - // abstraction. public: // = Initialization and termination methods. + /// Default constructor. ACE_SOCK_Dgram (void); - // Default constructor. + /// This is a BSD-style method (i.e., no QoS) for initiating a socket + /// dgram that will accept datagrams at the <local> address. ACE_SOCK_Dgram (const ACE_Addr &local, int protocol_family = PF_INET, int protocol = 0, int reuse_addr = 0); - // This is a BSD-style method (i.e., no QoS) for initiating a socket - // dgram that will accept datagrams at the <local> address. + /** + * This is a QoS-enabed method for initiating a socket dgram that + * will accept datagrams at the <local> address. The <qos_params> + * are passed to <ACE_OS::join_leaf>. + */ ACE_SOCK_Dgram (const ACE_Addr &local, int protocol_family, int protocol, @@ -50,17 +55,19 @@ public: ACE_SOCK_GROUP g = 0, u_long flags = 0, int reuse_addr = 0); - // This is a QoS-enabed method for initiating a socket dgram that - // will accept datagrams at the <local> address. The <qos_params> - // are passed to <ACE_OS::join_leaf>. + /// This is a BSD-style method (i.e., no QoS) for initiating a socket + /// dgram that will accept datagrams at the <local> address. int open (const ACE_Addr &local, int protocol_family = PF_INET, int protocol = 0, int reuse_addr = 0); - // This is a BSD-style method (i.e., no QoS) for initiating a socket - // dgram that will accept datagrams at the <local> address. + /** + * This is a QoS-enabed method for initiating a socket dgram that + * will accept datagrams at the <local> address. The <qos_params> + * are passed to <ACE_OS::join_leaf>. + */ int open (const ACE_Addr &local, int protocol_family, int protocol, @@ -68,78 +75,83 @@ public: ACE_SOCK_GROUP g = 0, u_long flags = 0, int reuse_addr = 0); - // This is a QoS-enabed method for initiating a socket dgram that - // will accept datagrams at the <local> address. The <qos_params> - // are passed to <ACE_OS::join_leaf>. + /// Default dtor. ~ACE_SOCK_Dgram (void); - // Default dtor. // = Data transfer routines. + /// Send an <n> byte <buf> to the datagram socket (uses <sendto(3)>). ssize_t send (const void *buf, size_t n, const ACE_Addr &addr, int flags = 0) const; - // Send an <n> byte <buf> to the datagram socket (uses <sendto(3)>). + /// Receive an <n> byte <buf> from the datagram socket (uses + /// <recvfrom(3)>). ssize_t recv (void *buf, size_t n, ACE_Addr &addr, int flags = 0) const; - // Receive an <n> byte <buf> from the datagram socket (uses - // <recvfrom(3)>). + /** + * Allows a client to read from a socket without having to provide a + * buffer to read. This method determines how much data is in the + * socket, allocates a buffer of this size, reads in the data, and + * returns the number of bytes read. The caller is responsible for + * deleting the member in the <iov_base> field of <io_vec> using the + * ``delete []'' syntax. + */ ssize_t recv (iovec *io_vec, ACE_Addr &addr, int flags = 0, const ACE_Time_Value *timeout = 0) const; - // Allows a client to read from a socket without having to provide a - // buffer to read. This method determines how much data is in the - // socket, allocates a buffer of this size, reads in the data, and - // returns the number of bytes read. The caller is responsible for - // deleting the member in the <iov_base> field of <io_vec> using the - // ``delete []'' syntax. + /// Send an <iovec> of size <n> to the datagram socket (uses + /// <sendmsg(3)>). ssize_t send (const iovec iov[], size_t n, const ACE_Addr &addr, int flags = 0) const; - // Send an <iovec> of size <n> to the datagram socket (uses - // <sendmsg(3)>). + /// Recv an <iovec> of size <n> to the datagram socket (uses + /// <recvmsg(3)>). ssize_t recv (iovec iov[], size_t n, ACE_Addr &addr, int flags = 0) const; - // Recv an <iovec> of size <n> to the datagram socket (uses - // <recvmsg(3)>). + /** + * Wait up to <timeout> amount of time to receive a datagram into + * <buf>. The <ACE_Time_Value> indicates how long to blocking + * trying to receive. If <timeout> == 0, the caller will block + * until action is possible, else will wait until the relative time + * specified in *<timeout> elapses). If <recv> times out a -1 is + * returned with <errno == ETIME>. If it succeeds the number of + * bytes received is returned. + */ ssize_t recv (void *buf, size_t n, ACE_Addr &addr, int flags, const ACE_Time_Value *timeout) const; - // Wait up to <timeout> amount of time to receive a datagram into - // <buf>. The <ACE_Time_Value> indicates how long to blocking - // trying to receive. If <timeout> == 0, the caller will block - // until action is possible, else will wait until the relative time - // specified in *<timeout> elapses). If <recv> times out a -1 is - // returned with <errno == ETIME>. If it succeeds the number of - // bytes received is returned. + /** + * Wait up to <timeout> amount of time to receive a datagram into + * <buf>. The <ACE_Time_Value> indicates how long to blocking + * trying to receive. If <timeout> == 0, the caller will block + * until action is possible, else will wait until the relative time + * specified in *<timeout> elapses). If <send> times out a -1 is + * returned with <errno == ETIME>. If it succeeds the number of + * bytes received is returned. + */ ssize_t send (const void *buf, size_t n, ACE_Addr &addr, int flags, const ACE_Time_Value *timeout) const; - // Wait up to <timeout> amount of time to receive a datagram into - // <buf>. The <ACE_Time_Value> indicates how long to blocking - // trying to receive. If <timeout> == 0, the caller will block - // until action is possible, else will wait until the relative time - // specified in *<timeout> elapses). If <send> times out a -1 is - // returned with <errno == ETIME>. If it succeeds the number of - // bytes received is returned. + /// Send <buffer_count> worth of <buffers> to <addr> using overlapped + /// I/O (uses <WSASentTo>). Returns 0 on success. ssize_t send (const iovec buffers[], int buffer_count, size_t &number_of_bytes_sent, @@ -147,9 +159,9 @@ public: const ACE_Addr &addr, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func) const; - // Send <buffer_count> worth of <buffers> to <addr> using overlapped - // I/O (uses <WSASentTo>). Returns 0 on success. + /// Recv <buffer_count> worth of <buffers> from <addr> using + /// overlapped I/O (uses <WSARecvFrom>). Returns 0 on success. ssize_t recv (iovec buffers[], int buffer_count, size_t &number_of_bytes_recvd, @@ -157,40 +169,38 @@ public: ACE_Addr &addr, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func) const; - // Recv <buffer_count> worth of <buffers> from <addr> using - // overlapped I/O (uses <WSARecvFrom>). Returns 0 on success. + /// Send an <n> byte <buf> to the datagram socket (uses <WSASentTo>). ssize_t send (const void *buf, size_t n, const ACE_Addr &addr, int flags, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func) const; - // Send an <n> byte <buf> to the datagram socket (uses <WSASentTo>). + /// Receive an <n> byte <buf> from the datagram socket (uses + /// <WSARecvFrom>). ssize_t recv (void *buf, size_t n, ACE_Addr &addr, int flags, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func) const; - // Receive an <n> byte <buf> from the datagram socket (uses - // <WSARecvFrom>). + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Open is shared by this and by <LSOCK_Dgram>. int shared_open (const ACE_Addr &local, int protocol_family); - // Open is shared by this and by <LSOCK_Dgram>. private: + /// Do not allow this function to percolate up to this interface... int get_remote_addr (ACE_Addr &) const; - // Do not allow this function to percolate up to this interface... }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/SOCK_Dgram_Bcast.h b/ace/SOCK_Dgram_Bcast.h index e509a7bf712..e16c0d2296b 100644 --- a/ace/SOCK_Dgram_Bcast.h +++ b/ace/SOCK_Dgram_Bcast.h @@ -1,17 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// = LIBRARY -// ace -// -// = FILENAME -// SOCK_Dgram_Bcast.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file SOCK_Dgram_Bcast.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SOCK_DGRAM_BCAST_H #define ACE_SOCK_DGRAM_BCAST_H @@ -25,32 +23,38 @@ #include "ace/SOCK_Dgram.h" +/** + * @class ACE_Bcast_Node + * + * @brief Linked list of broadcast interfaces. + */ class ACE_Export ACE_Bcast_Node { - // = TITLE - // Linked list of broadcast interfaces. public: - ACE_Bcast_Node (ACE_INET_Addr &, + /// Default dtor. + ACE_Bcast_Node (ACE_INET_Addr &, ACE_Bcast_Node *); ~ACE_Bcast_Node (void); - // Default dtor. + /// Broadcast address for the interface. ACE_INET_Addr bcast_addr_; - // Broadcast address for the interface. + /// Pointer to the next interface in the chain. ACE_Bcast_Node *next_; - // Pointer to the next interface in the chain. }; +/** + * @class ACE_SOCK_Dgram_Bcast + * + * @brief Defines the member functions for the ACE_SOCK datagram + * abstraction. + */ class ACE_Export ACE_SOCK_Dgram_Bcast : public ACE_SOCK_Dgram { - // = TITLE - // Defines the member functions for the ACE_SOCK datagram - // abstraction. public: // = Initialization and termination methods. + /// Default constructor. ACE_SOCK_Dgram_Bcast (void); - // Default constructor. ACE_SOCK_Dgram_Bcast (const ACE_Addr &local, int protocol_family = PF_INET, @@ -58,65 +62,67 @@ public: int reuse_addr = 0, const ACE_TCHAR *host_name = 0); + /// Default dtor. ~ACE_SOCK_Dgram_Bcast (void); - // Default dtor. // Initiate a connectionless datagram broadcast endpoint. + /// Initiate a connectionless datagram broadcast endpoint. int open (const ACE_Addr &local, int protocol_family = PF_INET, int protocol = 0, int reuse_addr = 0, const ACE_TCHAR *host_name = 0); - // Initiate a connectionless datagram broadcast endpoint. + /// Close up and release dynamically allocated resources. int close (void); - // Close up and release dynamically allocated resources. + /// Broadcast the datagram to every interface. Returns the average + /// number of bytes sent. ssize_t send (const void *buf, size_t n, u_short portnum, int flags = 0) const; - // Broadcast the datagram to every interface. Returns the average - // number of bytes sent. + /// Broadcast the <iovec> datagrams to every interface. Returns the + /// average number of bytes sent. ssize_t send (const iovec iov[], size_t n, u_short portnum, int flags = 0) const; - // Broadcast the <iovec> datagrams to every interface. Returns the - // average number of bytes sent. + /// Broadcast an N byte datagram to ADDR (note that addr must be + /// preassigned to the broadcast address of the subnet...). ssize_t send (const void *buf, size_t n, const ACE_Addr &addr, int flags = 0) const; - // Broadcast an N byte datagram to ADDR (note that addr must be - // preassigned to the broadcast address of the subnet...). + /** + * Broadcast an <iovec> of size <n> to <addr> as a datagram (note + * that addr must be preassigned to the broadcast address of the + * subnet...) + */ ssize_t send (const iovec iov[], size_t n, const ACE_Addr &addr, int flags = 0) const; - // Broadcast an <iovec> of size <n> to <addr> as a datagram (note - // that addr must be preassigned to the broadcast address of the - // subnet...) */ + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Make broadcast available for Datagram socket. int mk_broadcast (const ACE_TCHAR *host_name); - // Make broadcast available for Datagram socket. + /// Points to the head of the list of broadcast interfaces. ACE_Bcast_Node *if_list_; - // Points to the head of the list of broadcast interfaces. + /// Do not allow this function to percolate up to this interface... int get_remote_addr (ACE_Addr &) const; - // Do not allow this function to percolate up to this interface... }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/SOCK_Dgram_Mcast.h b/ace/SOCK_Dgram_Mcast.h index 1d11961d3ef..7d9269f0bd4 100644 --- a/ace/SOCK_Dgram_Mcast.h +++ b/ace/SOCK_Dgram_Mcast.h @@ -1,20 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SOCK_Dgram_Mcast.h -// -// = AUTHORS -// Irfan Pyrali <irfan@cs.wustl.edu>, -// Tim Harrison <harrison@cs.wustl.edu>, and -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file SOCK_Dgram_Mcast.h + * + * $Id$ + * + * @author Irfan Pyrali <irfan@cs.wustl.edu> + * @author Tim Harrison <harrison@cs.wustl.edu> + * @author and Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_SOCK_DGRAM_MCAST_H #define ACE_SOCK_DGRAM_MCAST_H @@ -28,99 +25,111 @@ #include "ace/INET_Addr.h" +/** + * @class ACE_SOCK_Dgram_Mcast + * + * @brief Defines the member functions for the ACE socket wrapper + * for UDP/IP multicast. + */ class ACE_Export ACE_SOCK_Dgram_Mcast : public ACE_SOCK_Dgram { - // = TITLE - // Defines the member functions for the ACE socket wrapper - // for UDP/IP multicast. public: // = Initialization routine. + /** + * Note that there is no public <open> method. Therefore, this + * class cannot be used unless you <subscribe> to a multicast group. + * If you just want to send (and not listen) to a multicast group, + * use <ACE_SOCK_Dgram> or <ACE_SOCK_CODgram> instead. + */ ACE_SOCK_Dgram_Mcast (void); - // Note that there is no public <open> method. Therefore, this - // class cannot be used unless you <subscribe> to a multicast group. - // If you just want to send (and not listen) to a multicast group, - // use <ACE_SOCK_Dgram> or <ACE_SOCK_CODgram> instead. + /// Default dtor. ~ACE_SOCK_Dgram_Mcast (void); - // Default dtor. // = Multicast group management routines. + /** + * This is a BSD-style method (i.e., no QoS) for joining a multicast + * group. The network interface device driver is instructed to + * accept datagrams with <mcast_addr> multicast addresses. If the + * socket has already been opened, <subscribe> closes the socket and + * opens a new socket bound to the <mcast_addr>. + * + * The <net_if> interface is hardware specific, e.g., use "netstat + * -i" to find whether your interface is, such as "le0" or something + * else. If net_if == 0, <subscribe> uses the default mcast + * interface. Returns: -1 if the call fails. + * + * Note that some platforms, such as pSoS, support only number, not + * names, for network interfaces. For these platforms, just give + * these numbers in alphanumeric form and <subscribe> will convert + * them into numbers via <ACE_OS::atoi>. + */ int subscribe (const ACE_INET_Addr &mcast_addr, int reuse_addr = 1, const ACE_TCHAR *net_if = 0, int protocol_family = PF_INET, int protocol = 0); - // This is a BSD-style method (i.e., no QoS) for joining a multicast - // group. The network interface device driver is instructed to - // accept datagrams with <mcast_addr> multicast addresses. If the - // socket has already been opened, <subscribe> closes the socket and - // opens a new socket bound to the <mcast_addr>. - // - // The <net_if> interface is hardware specific, e.g., use "netstat - // -i" to find whether your interface is, such as "le0" or something - // else. If net_if == 0, <subscribe> uses the default mcast - // interface. Returns: -1 if the call fails. - // - // Note that some platforms, such as pSoS, support only number, not - // names, for network interfaces. For these platforms, just give - // these numbers in alphanumeric form and <subscribe> will convert - // them into numbers via <ACE_OS::atoi>. + /** + * Leave a multicast group identified by <mcast_addr>. The <net_if> + * interface is hardware specific. Use something like "netstat -i" + * to find whether your interface is, such as "le0" or something + * else. If <net_if> == 0, <subscribe> uses the default mcast + * interface. Returns: -1 if the call fails. + * + * Note that some platforms, such as pSoS, support only number, not + * names, for network interfaces. For these platforms, just give + * these numbers in alphanumeric form and <subscribe> will convert + * them into numbers via <ACE_OS::atoi>. + */ int unsubscribe (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if = 0, int protocol_family = PF_INET, int protocol = 0); - // Leave a multicast group identified by <mcast_addr>. The <net_if> - // interface is hardware specific. Use something like "netstat -i" - // to find whether your interface is, such as "le0" or something - // else. If <net_if> == 0, <subscribe> uses the default mcast - // interface. Returns: -1 if the call fails. - // - // Note that some platforms, such as pSoS, support only number, not - // names, for network interfaces. For these platforms, just give - // these numbers in alphanumeric form and <subscribe> will convert - // them into numbers via <ACE_OS::atoi>. + /// Unsubscribe from a multicast group. Returns -1 if the call + /// fails. int unsubscribe (void); - // Unsubscribe from a multicast group. Returns -1 if the call - // fails. // = Data transfer routines. + /// Send <n> bytes in <buf>. ssize_t send (const void *buf, size_t n, int flags = 0) const; - // Send <n> bytes in <buf>. + /// Send <n> <iovecs>. ssize_t send (const iovec iov[], size_t n, int flags = 0) const; - // Send <n> <iovecs>. // = Options. - int set_option (int option, + /** + * Set an ip option that takes a char as input, such as + * <IP_MULTICAST_LOOP> or <IP_MULTICAST_TTL>. This is just a more + * concise nice interface to a subset of possible + * <ACE_SOCK::set_option> calls. Returns 0 on success, -1 on + * failure. + */ + int set_option (int option, char optval); - // Set an ip option that takes a char as input, such as - // <IP_MULTICAST_LOOP> or <IP_MULTICAST_TTL>. This is just a more - // concise nice interface to a subset of possible - // <ACE_SOCK::set_option> calls. Returns 0 on success, -1 on - // failure. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: // = Disable public <open> method to ensure class used properly. + /// Not publically visible. int open (const ACE_Addr &mcast_addr, int protocol_family = PF_INET, int protocol = 0, int reuse_addr = 0); - // Not publically visible. + /// Not publically visible. int open (const ACE_Addr &mcast_addr, const ACE_QoS_Params &qos_params, int protocol_family = PF_INET, @@ -129,24 +138,23 @@ private: ACE_SOCK_GROUP g = 0, u_long flags = 0, int reuse_addr = 0); - // Not publically visible. + /// Subscribe to the multicast interface using BSD-style semantics + /// (no QoS). int subscribe_ifs (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if, int protocol_family, int protocol, int reuse_addr); - // Subscribe to the multicast interface using BSD-style semantics - // (no QoS). + /// Unsubscribe to multicast interfaces subscribed to previously by + /// <subscribe_ifs>. int unsubscribe_ifs (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if = 0, int protocol_family = PF_INET, int protocol = 0); - // Unsubscribe to multicast interfaces subscribed to previously by - // <subscribe_ifs>. - // = Disable public use of <ACE_SOCK_Dgram::send>s + // = Disable public use of <ACE_SOCK_Dgram::send>s // This forces <ACE_SOCK_Dgram_Mcast::send>s inline. ssize_t send (const void *buf, @@ -159,22 +167,22 @@ private: int flags = 0) const; protected: + /// Initialize the <multicast_address_> IP address. int make_multicast_address (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if = ACE_LIB_TEXT ("le0")); - // Initialize the <multicast_address_> IP address. + /// Initialize a multicast address. This method factors out common + /// code called by <make_multicast_address> and <subscribe>. int make_multicast_address_i (const ACE_INET_Addr &mcast_addr, ip_mreq& multicast_address, const ACE_TCHAR *net_if = ACE_LIB_TEXT ("le0")); - // Initialize a multicast address. This method factors out common - // code called by <make_multicast_address> and <subscribe>. + /// A copy of the address that we use to <send> multicasts. ACE_INET_Addr mcast_addr_; - // A copy of the address that we use to <send> multicasts. + /// IP address of the interface upon which we're receiving + /// multicasts. ip_mreq mcast_request_if_; - // IP address of the interface upon which we're receiving - // multicasts. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) @@ -183,4 +191,3 @@ protected: #include "ace/post.h" #endif /* ACE_SOCK_DGRAM_MCAST_H */ - diff --git a/ace/SOCK_Dgram_Mcast_QoS.h b/ace/SOCK_Dgram_Mcast_QoS.h index 81d32e11b4c..b24e219421c 100644 --- a/ace/SOCK_Dgram_Mcast_QoS.h +++ b/ace/SOCK_Dgram_Mcast_QoS.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SOCK_Dgram_Mcast_QoS.h -// -// = AUTHORS -// Vishal Kachroo <vishal@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file SOCK_Dgram_Mcast_QoS.h + * + * $Id$ + * + * @author Vishal Kachroo <vishal@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_SOCK_DGRAM_MCAST_QOS_H #define ACE_SOCK_DGRAM_MCAST_QOS_H @@ -25,11 +22,14 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_SOCK_Dgram_Mcast_QoS + * + * @brief Defines the member functions for the ACE QoS enabled socket + * wrapper for UDP/IP multicast. + */ class ACE_Export ACE_SOCK_Dgram_Mcast_QoS : public ACE_SOCK_Dgram_Mcast { - // = TITLE - // Defines the member functions for the ACE QoS enabled socket - // wrapper for UDP/IP multicast. public: // = Initialization routines. @@ -40,10 +40,31 @@ public: // If you just want to send (and not listen) to a multicast group, // use <ACE_SOCK_Dgram> or <ACE_SOCK_CODgram> instead. + /// Default dtor. ~ACE_SOCK_Dgram_Mcast_QoS (void); - // Default dtor. // = Multicast group management routines. + /** + * This is a QoS-enabled method for joining a multicast group, which + * passes <qos_params> via <ACE_OS::join_leaf>. The network + * interface device driver is instructed to accept datagrams with + * <mcast_addr> multicast addresses. If the socket has already been + * opened, <subscribe> closes the socket and opens a new socket + * bound to the <mcast_addr>. The session object specifies the QoS + * session that the socket wants to subscribe to. A socket may + * subscribe to multiple QoS sessions by calling this method multiple + * times with different session objects. + * + * The <net_if> interface is hardware specific, e.g., use "netstat + * -i" to find whether your interface is, such as "le0" or something + * else. If net_if == 0, <subscribe> uses the default mcast + * interface. Returns: -1 if the call fails. + * + * Note that some platforms, such as pSoS, support only number, not + * names, for network interfaces. For these platforms, just give + * these numbers in alphanumeric form and <subscribe> will convert + * them into numbers via <ACE_OS::atoi>. + */ int subscribe (const ACE_INET_Addr &mcast_addr, const ACE_QoS_Params &qos_params, int reuse_addr = 1, @@ -54,28 +75,11 @@ public: ACE_SOCK_GROUP g = 0, u_long flags = 0, ACE_QoS_Session *qos_session = 0); - // This is a QoS-enabled method for joining a multicast group, which - // passes <qos_params> via <ACE_OS::join_leaf>. The network - // interface device driver is instructed to accept datagrams with - // <mcast_addr> multicast addresses. If the socket has already been - // opened, <subscribe> closes the socket and opens a new socket - // bound to the <mcast_addr>. The session object specifies the QoS - // session that the socket wants to subscribe to. A socket may - // subscribe to multiple QoS sessions by calling this method multiple - // times with different session objects. - // - // The <net_if> interface is hardware specific, e.g., use "netstat - // -i" to find whether your interface is, such as "le0" or something - // else. If net_if == 0, <subscribe> uses the default mcast - // interface. Returns: -1 if the call fails. - // - // Note that some platforms, such as pSoS, support only number, not - // names, for network interfaces. For these platforms, just give - // these numbers in alphanumeric form and <subscribe> will convert - // them into numbers via <ACE_OS::atoi>. // = Data transfer routines. + /// Send <buffer_count> worth of <buffers> to <addr> using overlapped + /// I/O (uses <WSASentTo>). Returns 0 on success. ssize_t send (const iovec buffers[], int buffer_count, size_t &number_of_bytes_sent, @@ -83,26 +87,25 @@ public: const ACE_Addr &addr, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func) const; - // Send <buffer_count> worth of <buffers> to <addr> using overlapped - // I/O (uses <WSASentTo>). Returns 0 on success. + /// Send an <n> byte <buf> to the datagram socket (uses <WSASentTo>). ssize_t send (const void *buf, size_t n, const ACE_Addr &addr, int flags, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func) const; - // Send an <n> byte <buf> to the datagram socket (uses <WSASentTo>). + /// Returns the QoS manager for this socket. ACE_QoS_Manager qos_manager (void); - // Returns the QoS manager for this socket. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: // = Disable public <open> method to ensure class used properly. + /// Not publically visible. int open (const ACE_Addr &mcast_addr, const ACE_QoS_Params &qos_params, int protocol_family = PF_INET, @@ -111,8 +114,8 @@ private: ACE_SOCK_GROUP g = 0, u_long flags = 0, int reuse_addr = 0); - // Not publically visible. + /// Subscribe to the multicast interface using QoS-enabled semantics. int subscribe_ifs (const ACE_INET_Addr &mcast_addr, const ACE_QoS_Params &qos_params, const ACE_TCHAR *net_if, @@ -120,10 +123,9 @@ private: int protocol, int reuse_addr, ACE_Protocol_Info *protocolinfo); - // Subscribe to the multicast interface using QoS-enabled semantics. + /// Manages the QoS sessions that this socket subscribes to. ACE_QoS_Manager qos_manager_; - // Manages the QoS sessions that this socket subscribes to. }; @@ -133,5 +135,3 @@ private: #include "ace/post.h" #endif /* ACE_SOCK_DGRAM_MCAST_QOS_H */ - - diff --git a/ace/SOCK_IO.h b/ace/SOCK_IO.h index 0ad3ef62682..61fbace0715 100644 --- a/ace/SOCK_IO.h +++ b/ace/SOCK_IO.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SOCK_IO.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file SOCK_IO.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SOCK_IO_H #define ACE_SOCK_IO_H @@ -24,119 +21,119 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_SOCK_IO + * + * @brief Defines the methods for the ACE socket wrapper I/O routines + * (e.g., send/recv). + * + * + * If <timeout> == 0, then the call behaves as a normal + * send/recv call, i.e., for blocking sockets, the call will + * block until action is possible; for non-blocking sockets, + * EWOULDBLOCK will be returned if no action is immediately + * possible. + * If <timeout> != 0, the call will wait until the relative time + * specified in *<timeout> elapses. + * Errors are reported by -1 and 0 return values. If the + * operation times out, -1 is returned with <errno == ETIME>. + * If it succeeds the number of bytes transferred is returned. + * Methods with the extra <flags> argument will always result in + * <send> getting called. Methods without the extra <flags> + * argument will result in <send> getting called on Win32 + * platforms, and <write> getting called on non-Win32 platforms. + */ class ACE_Export ACE_SOCK_IO : public ACE_SOCK { - // = TITLE - // Defines the methods for the ACE socket wrapper I/O routines - // (e.g., send/recv). - // - // = NOTES - // - // If <timeout> == 0, then the call behaves as a normal - // send/recv call, i.e., for blocking sockets, the call will - // block until action is possible; for non-blocking sockets, - // EWOULDBLOCK will be returned if no action is immediately - // possible. - // - // If <timeout> != 0, the call will wait until the relative time - // specified in *<timeout> elapses. - // - // Errors are reported by -1 and 0 return values. If the - // operation times out, -1 is returned with <errno == ETIME>. - // If it succeeds the number of bytes transferred is returned. - // - // Methods with the extra <flags> argument will always result in - // <send> getting called. Methods without the extra <flags> - // argument will result in <send> getting called on Win32 - // platforms, and <write> getting called on non-Win32 platforms. - // public: // = Initialization and termination methods. + /// Constructor. ACE_SOCK_IO (void); - // Constructor. + /// Destructor. ~ACE_SOCK_IO (void); - // Destructor. + /// Recv an <n> byte buffer from the connected socket. ssize_t recv (void *buf, size_t n, int flags, const ACE_Time_Value *timeout = 0) const; - // Recv an <n> byte buffer from the connected socket. + /// Recv an <n> byte buffer from the connected socket. ssize_t recv (void *buf, size_t n, const ACE_Time_Value *timeout = 0) const; - // Recv an <n> byte buffer from the connected socket. + /// Recv an <iovec> of size <n> from the connected socket. ssize_t recvv (iovec iov[], size_t n, const ACE_Time_Value *timeout = 0) const; - // Recv an <iovec> of size <n> from the connected socket. + /// Same as above. Deprecated. ssize_t recv (iovec iov[], size_t n, const ACE_Time_Value *timeout = 0) const; - // Same as above. Deprecated. + /** + * Allows a client to read from a socket without having to provide a + * buffer to read. This method determines how much data is in the + * socket, allocates a buffer of this size, reads in the data, and + * returns the number of bytes read. The caller is responsible for + * deleting the member in the <iov_base> field of <io_vec> using + * delete [] io_vec->iov_base. + */ ssize_t recvv (iovec *io_vec, const ACE_Time_Value *timeout = 0) const; - // Allows a client to read from a socket without having to provide a - // buffer to read. This method determines how much data is in the - // socket, allocates a buffer of this size, reads in the data, and - // returns the number of bytes read. The caller is responsible for - // deleting the member in the <iov_base> field of <io_vec> using - // delete [] io_vec->iov_base. + /// Same as above. Deprecated. ssize_t recv (iovec *io_vec, const ACE_Time_Value *timeout = 0) const; - // Same as above. Deprecated. + /// Recv <n> varargs messages to the connected socket. ssize_t recv (size_t n, ...) const; - // Recv <n> varargs messages to the connected socket. + /// Recv <n> bytes via Win32 <ReadFile> using overlapped I/O. ssize_t recv (void *buf, size_t n, ACE_OVERLAPPED *overlapped) const; - // Recv <n> bytes via Win32 <ReadFile> using overlapped I/O. + /// Send an <n> byte buffer to the connected socket. ssize_t send (const void *buf, size_t n, int flags, const ACE_Time_Value *timeout = 0) const; - // Send an <n> byte buffer to the connected socket. + /// Send an <n> byte buffer to the connected socket. ssize_t send (const void *buf, size_t n, const ACE_Time_Value *timeout = 0) const; - // Send an <n> byte buffer to the connected socket. + /// Send an <iovec> of size <n> to the connected socket. ssize_t sendv (const iovec iov[], size_t n, const ACE_Time_Value *timeout = 0) const; - // Send an <iovec> of size <n> to the connected socket. + /// Same as above. Deprecated. ssize_t send (const iovec iov[], size_t n, const ACE_Time_Value *timeout = 0) const; - // Same as above. Deprecated. + /// Send <n> varargs messages to the connected socket. ssize_t send (size_t n, ...) const; - // Send <n> varargs messages to the connected socket. + /// Send <n> bytes via Win32 <WriteFile> using overlapped I/O. ssize_t send (const void *buf, size_t n, ACE_OVERLAPPED *overlapped) const; - // Send <n> bytes via Win32 <WriteFile> using overlapped I/O. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/SOCK_Stream.h b/ace/SOCK_Stream.h index e6263bf0f87..1917d3f6010 100644 --- a/ace/SOCK_Stream.h +++ b/ace/SOCK_Stream.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SOCK_Stream.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file SOCK_Stream.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SOCK_STREAM_H #define ACE_SOCK_STREAM_H @@ -26,106 +23,99 @@ #include "ace/INET_Addr.h" +/** + * @class ACE_SOCK_Stream + * + * @brief Defines the methods in the <ACE_SOCK_Stream> abstraction. + * + * This adds additional wrapper methods atop the <ACE_SOCK_IO> + * class. + * + * <buf> is the buffer to write from or receive into. + * <len> is the number of bytes to transfer. + * The <timeout> parameter in the following methods indicates how + * long to blocking trying to transfer data. If <timeout> == 0, + * then the call behaves as a normal send/recv call, i.e., for + * blocking sockets, the call will block until action is possible; + * for non-blocking sockets, EWOULDBLOCK will be returned if no + * action is immediately possible. + * If <timeout> != 0, the call will wait until the relative time + * specified in *<timeout> elapses. + * The "_n()" I/O methods keep looping until all the data has been + * transferred. These methods also work for sockets in non-blocking + * mode i.e., they keep looping on EWOULDBLOCK. <timeout> is used + * to make sure we keep making progress, i.e., the same timeout + * value is used for every I/O operation in the loop and the timeout + * is not counted down. + * The return values for the "*_n()" methods match the return values + * from the non "_n()" methods and are specified as follows: + * - On complete transfer, the number of bytes transferred is returned. + * - On timeout, -1 is returned, errno == ETIME. + * - On error, -1 is returned, errno is set to appropriate error. + * - On EOF, 0 is returned, errno is irrelevant. + * + * On partial transfers, i.e., if any data is transferred before + * timeout/error/EOF, <bytes_transferred> will contain the number of + * bytes transferred. + * Methods with <iovec> parameter are I/O vector variants of the I/O + * operations. + * Methods with the extra <flags> argument will always result in + * <send> getting called. Methods without the extra <flags> argument + * will result in <send> getting called on Win32 platforms, and + * <write> getting called on non-Win32 platforms. + */ class ACE_Export ACE_SOCK_Stream : public ACE_SOCK_IO { - // = TITLE - // Defines the methods in the <ACE_SOCK_Stream> abstraction. - // - // = DESCRIPTION - // This adds additional wrapper methods atop the <ACE_SOCK_IO> - // class. - // - // = NOTES - // <buf> is the buffer to write from or receive into. - // - // <len> is the number of bytes to transfer. - // - // The <timeout> parameter in the following methods indicates how - // long to blocking trying to transfer data. If <timeout> == 0, - // then the call behaves as a normal send/recv call, i.e., for - // blocking sockets, the call will block until action is possible; - // for non-blocking sockets, EWOULDBLOCK will be returned if no - // action is immediately possible. - // - // If <timeout> != 0, the call will wait until the relative time - // specified in *<timeout> elapses. - // - // The "_n()" I/O methods keep looping until all the data has been - // transferred. These methods also work for sockets in non-blocking - // mode i.e., they keep looping on EWOULDBLOCK. <timeout> is used - // to make sure we keep making progress, i.e., the same timeout - // value is used for every I/O operation in the loop and the timeout - // is not counted down. - // - // The return values for the "*_n()" methods match the return values - // from the non "_n()" methods and are specified as follows: - // - // - On complete transfer, the number of bytes transferred is returned. - // - On timeout, -1 is returned, errno == ETIME. - // - On error, -1 is returned, errno is set to appropriate error. - // - On EOF, 0 is returned, errno is irrelevant. - // - // On partial transfers, i.e., if any data is transferred before - // timeout/error/EOF, <bytes_transferred> will contain the number of - // bytes transferred. - // - // Methods with <iovec> parameter are I/O vector variants of the I/O - // operations. - // - // Methods with the extra <flags> argument will always result in - // <send> getting called. Methods without the extra <flags> argument - // will result in <send> getting called on Win32 platforms, and - // <write> getting called on non-Win32 platforms. public: // Initialization and termination methods. + /// Constructor. ACE_SOCK_Stream (void); - // Constructor. + /// Constructor (sets the underlying <ACE_HANDLE> with <h>). ACE_SOCK_Stream (ACE_HANDLE h); - // Constructor (sets the underlying <ACE_HANDLE> with <h>). + /// Destructor. ~ACE_SOCK_Stream (void); - // Destructor. // = I/O functions. + /// Try to recv exactly <len> bytes into <buf> from <handle>. ssize_t recv_n (void *buf, size_t len, int flags, const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0) const; - // Try to recv exactly <len> bytes into <buf> from <handle>. + /// Try to recv exactly <len> bytes into <buf> from <handle>. ssize_t recv_n (void *buf, size_t len, const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0) const; - // Try to recv exactly <len> bytes into <buf> from <handle>. + /// Receive an <iovec> of size <iovcnt> to the connected socket. ssize_t recvv_n (iovec iov[], size_t iovcnt, const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0) const; - // Receive an <iovec> of size <iovcnt> to the connected socket. + /// Try to send exactly <len> bytes into <buf> from <handle>. ssize_t send_n (const void *buf, size_t len, int flags, const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0) const; - // Try to send exactly <len> bytes into <buf> from <handle>. + /// Try to send exactly <len> bytes into <buf> from <handle>. ssize_t send_n (const void *buf, size_t len, const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0) const; - // Try to send exactly <len> bytes into <buf> from <handle>. + /// Send an <iovec> of size <iovcnt> to the connected socket. ssize_t sendv_n (const iovec iov[], size_t iovcnt, const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0) const; - // Send an <iovec> of size <iovcnt> to the connected socket. // = Send/receive ``urgent'' data (see TCP specs...). ssize_t send_urg (const void *ptr, @@ -137,24 +127,26 @@ public: const ACE_Time_Value *timeout = 0) const; // = Selectively close endpoints. + /// Close down the reader. + /// Close down the writer. int close_reader (void); - // Close down the reader. int close_writer (void); - // Close down the writer. + /** + * Close down the socket (we need this to make things work correctly + * on Win32, which requires use to do a <close_writer> before doing + * the close to avoid losing data). + */ int close (void); - // Close down the socket (we need this to make things work correctly - // on Win32, which requires use to do a <close_writer> before doing - // the close to avoid losing data). // = Meta-type info typedef ACE_INET_Addr PEER_ADDR; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/SPIPE.h b/ace/SPIPE.h index a9fcfe334e5..5b49146ea34 100644 --- a/ace/SPIPE.h +++ b/ace/SPIPE.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SPIPE.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file SPIPE.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SPIPE_H #define ACE_SPIPE_H @@ -26,39 +23,44 @@ #include "ace/SPIPE_Addr.h" +/** + * @class ACE_SPIPE + * + * @brief Defines the member functions for the base class of the + * ACE_SPIPE abstraction. + */ class ACE_Export ACE_SPIPE : public ACE_IPC_SAP { - // = TITLE - // Defines the member functions for the base class of the - // ACE_SPIPE abstraction. public: + /// Close down the STREAM pipe without removing the rendezvous point. int close (void); - // Close down the STREAM pipe without removing the rendezvous point. + /// Close down the STREAM pipe and remove the rendezvous point from + /// the file system. int remove (void); - // Close down the STREAM pipe and remove the rendezvous point from - // the file system. + /// Return the local address of this endpoint. int get_local_addr (ACE_SPIPE_Addr &) const; - // Return the local address of this endpoint. + /** + * Disable signal <signum> + * This is here to prevent Win32 from + * disabling SPIPE using socket calls + */ int disable (int signum) const ; - // Disable signal <signum> - // This is here to prevent Win32 from - // disabling SPIPE using socket calls + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Ensure that this class is an abstract base class ACE_SPIPE (void); - // Ensure that this class is an abstract base class + /// Our local address. ACE_SPIPE_Addr local_addr_; - // Our local address. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/SPIPE_Acceptor.h b/ace/SPIPE_Acceptor.h index 2e4d08fa338..d0595f381ab 100644 --- a/ace/SPIPE_Acceptor.h +++ b/ace/SPIPE_Acceptor.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SPIPE_Acceptor.h -// -// = AUTHOR -// Doug Schmidt and Prashant Jain -// -// ============================================================================ + +//============================================================================= +/** + * @file SPIPE_Acceptor.h + * + * $Id$ + * + * @author Doug Schmidt and Prashant Jain + */ +//============================================================================= + #ifndef ACE_SPIPE_ACCEPTOR_H #define ACE_SPIPE_ACCEPTOR_H @@ -28,55 +25,60 @@ #include "ace/Synch.h" #endif /* ACE_WIN32 */ +/** + * @class ACE_SPIPE_Acceptor + * + * @brief Defines the format and interface for the listener side of the + * ACE_SPIPE_Stream. + */ class ACE_Export ACE_SPIPE_Acceptor : public ACE_SPIPE { - // = TITLE - // Defines the format and interface for the listener side of the - // ACE_SPIPE_Stream. public: // = Initialization and termination methods. + /// Default constructor. ACE_SPIPE_Acceptor (void); - // Default constructor. + /// Initiate a passive-mode STREAM pipe listener. ACE_SPIPE_Acceptor (const ACE_SPIPE_Addr &local_sap, int reuse_addr = 1, int perms = ACE_DEFAULT_FILE_PERMS); - // Initiate a passive-mode STREAM pipe listener. + /// Initiate a passive-mode STREAM pipe listener. int open (const ACE_SPIPE_Addr &local_sap, int reuse_addr = 1, int perms = ACE_DEFAULT_FILE_PERMS); - // Initiate a passive-mode STREAM pipe listener. + /// Close down the passive-mode STREAM pipe listener. int close (void); - // Close down the passive-mode STREAM pipe listener. + /// Remove the underlying mounted pipe from the file system. int remove (void); - // Remove the underlying mounted pipe from the file system. // = Passive connection acceptance method. + /** + * Accept a new data transfer connection. A <timeout> of 0 means + * block forever, a <timeout> of {0, 0} means poll. <restart> == 1 + * means "restart if interrupted." + */ int accept (ACE_SPIPE_Stream &ipc_sap_spipe, ACE_SPIPE_Addr *remote_addr = 0, ACE_Time_Value *timeout = 0, int restart = 1, int reset_new_handle = 0); - // Accept a new data transfer connection. A <timeout> of 0 means - // block forever, a <timeout> of {0, 0} means poll. <restart> == 1 - // means "restart if interrupted." // = Meta-type info typedef ACE_SPIPE_Addr PEER_ADDR; typedef ACE_SPIPE_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Create a new instance of an SPIPE. int create_new_instance (int perms = 0); - // Create a new instance of an SPIPE. #if (defined (ACE_WIN32) && defined (ACE_HAS_WINNT4) && (ACE_HAS_WINNT4 != 0)) ACE_OVERLAPPED overlapped_; diff --git a/ace/SPIPE_Addr.h b/ace/SPIPE_Addr.h index 063c2382315..c4878d5d374 100644 --- a/ace/SPIPE_Addr.h +++ b/ace/SPIPE_Addr.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SPIPE_Addr.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file SPIPE_Addr.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SPIPE_ADDR_H #define ACE_SPIPE_ADDR_H @@ -26,74 +23,75 @@ #include "ace/ACE.h" +/** + * @class ACE_SPIPE_Addr + * + * @brief Defines the SVR4 STREAM pipe address family address format. + */ class ACE_Export ACE_SPIPE_Addr : public ACE_Addr { - // = TITLE - // Defines the SVR4 STREAM pipe address family address format. public: // = Initialization methods. + /// Default constructor. ACE_SPIPE_Addr (void); - // Default constructor. + /// Copy constructor. ACE_SPIPE_Addr (const ACE_SPIPE_Addr &sa); - // Copy constructor. + /// Create a ACE_SPIPE_Addr from a rendezvous point in the file + /// system. ACE_SPIPE_Addr (const ACE_TCHAR *rendezvous_point, gid_t = 0, uid_t = 0); - // Create a ACE_SPIPE_Addr from a rendezvous point in the file - // system. + /// Acts like a copy constructor... int set (const ACE_SPIPE_Addr &sa); - // Acts like a copy constructor... + /// Create a ACE_SPIPE_Addr from a rendezvous point in the file + /// system. int set (const ACE_TCHAR *rendezvous_point, gid_t = 0, uid_t = 0); - // Create a ACE_SPIPE_Addr from a rendezvous point in the file - // system. + /// Return a pointer to the address. virtual void *get_addr (void) const; - // Return a pointer to the address. + /// Set a pointer to the underlying network address. virtual void set_addr (void *addr, int len); - // Set a pointer to the underlying network address. + /// Transform the current address into string format. virtual int addr_to_string (ACE_TCHAR *addr, size_t) const; - // Transform the current address into string format. + /// Transform the string into the current addressing format. virtual int string_to_addr (const ACE_TCHAR *addr); - // Transform the string into the current addressing format. // = Equality/inequality tests + /// Check for equality. int operator == (const ACE_SPIPE_Addr &SAP) const; - // Check for equality. + /// Check for inequality int operator != (const ACE_SPIPE_Addr &SAP) const; - // Check for inequality // = SPIPE-specific address operations + /// Pathname of rendezvous point in file system. const ACE_TCHAR *get_path_name (void) const; - // Pathname of rendezvous point in file system. + /// Get user id. + /// Set user id. uid_t user_id (void) const; - // Get user id. void user_id (uid_t uid); - // Set user id. + /// Set group ids. + /// Get group ids. void group_id (gid_t gid); - // Set group ids. gid_t group_id (void) const; - // Get group ids. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Contains security attributes. struct SPIPE_Addr { - // = TITLE - // Contains security attributes. - gid_t gid_; // Group id. diff --git a/ace/SPIPE_Connector.h b/ace/SPIPE_Connector.h index 9bc38a1f7c7..b9a5228e8e3 100644 --- a/ace/SPIPE_Connector.h +++ b/ace/SPIPE_Connector.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SPIPE_Connector.h -// -// = AUTHOR -// Doug Schmidt and Prashant Jain -// -// ============================================================================ +//============================================================================= +/** + * @file SPIPE_Connector.h + * + * $Id$ + * + * @author Doug Schmidt and Prashant Jain + */ +//============================================================================= + #ifndef ACE_SPIPE_CONNECTOR_H #define ACE_SPIPE_CONNECTOR_H @@ -24,16 +21,36 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_SPIPE_Connector + * + * @brief Defines an active connection factory for the STREAM pipe + * wrappers. + */ class ACE_Export ACE_SPIPE_Connector { - // = TITLE - // Defines an active connection factory for the STREAM pipe - // wrappers. public: // = Initialization method. + /// Default constructor. ACE_SPIPE_Connector (void); - // Default constructor. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + * The <flags> and <perms> arguments are passed down to the <open> + * method. + */ ACE_SPIPE_Connector (ACE_SPIPE_Stream &new_io, const ACE_SPIPE_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -41,22 +58,24 @@ public: int reuse_addr = 0, int flags = O_RDWR, int perms = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. - // The <flags> and <perms> arguments are passed down to the <open> - // method. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + * The <flags> and <perms> arguments are passed down to the <open> + * method. + */ int connect (ACE_SPIPE_Stream &new_io, const ACE_SPIPE_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -64,34 +83,19 @@ public: int reuse_addr = 0, int flags = O_RDWR, int perms = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. - // The <flags> and <perms> arguments are passed down to the <open> - // method. + /// Resets any event associations on this handle int reset_new_handle (ACE_HANDLE handle); - // Resets any event associations on this handle // = Meta-type info typedef ACE_SPIPE_Addr PEER_ADDR; typedef ACE_SPIPE_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/SPIPE_Stream.h b/ace/SPIPE_Stream.h index 60fd3ac2bb3..1bbed754227 100644 --- a/ace/SPIPE_Stream.h +++ b/ace/SPIPE_Stream.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SPIPE_Stream.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file SPIPE_Stream.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SPIPE_STREAM_H #define ACE_SPIPE_STREAM_H @@ -26,110 +23,117 @@ #include "ace/SPIPE_Addr.h" +/** + * @class ACE_SPIPE_Stream + * + * @brief Define an ACE_SPIPE_Stream. + */ class ACE_Export ACE_SPIPE_Stream : public ACE_SPIPE { - // = TITLE - // Define an ACE_SPIPE_Stream. public: friend class ACE_SPIPE_Acceptor; friend class ACE_SPIPE_Connector; // = Initialization method. + /// Default constructor. ACE_SPIPE_Stream (void); - // Default constructor. + /// Obtain the address of whom we are connected with. int get_remote_addr (ACE_SPIPE_Addr &remote_sap) const; - // Obtain the address of whom we are connected with. + /// Send an open FD to another process. int send_handle (ACE_HANDLE handle) const; - // Send an open FD to another process. + /// Recv an open FD from another process. int recv_handle (ACE_HANDLE &handle) const; - // Recv an open FD from another process. + /// Recv an open FD from another process. int recv_handle (strrecvfd &recvfd) const; - // Recv an open FD from another process. + /// Send n bytes, keep trying until n are sent. ssize_t send_n (const void *buf, size_t n) const; - // Send n bytes, keep trying until n are sent. + /// Recv n bytes, keep trying until n are received. ssize_t recv_n (void *buf, size_t n) const; - // Recv n bytes, keep trying until n are received. + /// Send bytes via STREAM pipes using "band" mode. ssize_t send (const void *buf, size_t n) const; - // Send bytes via STREAM pipes using "band" mode. + /// Recv bytes via STREAM pipes using "band" mode. ssize_t recv (void *buf, size_t n) const; - // Recv bytes via STREAM pipes using "band" mode. + /// Send <cntl> and <data> via STREAM pipes. ssize_t send (const ACE_Str_Buf *cntl, const ACE_Str_Buf *data, int flags = 0) const; - // Send <cntl> and <data> via STREAM pipes. + /// Recv <cntl> and <data> via STREAM pipes. ssize_t recv (ACE_Str_Buf *cntl, ACE_Str_Buf *data, int *flags) const; - // Recv <cntl> and <data> via STREAM pipes. + /// Send bytes via STREAM pipes using "band" mode. ssize_t send (const ACE_Str_Buf *cntl, const ACE_Str_Buf *data, int band, int flags) const; - // Send bytes via STREAM pipes using "band" mode. + /// Recv bytes via STREAM pipes using "band" mode. ssize_t recv (ACE_Str_Buf *cntl, ACE_Str_Buf *data, int *band, int *flags) const; - // Recv bytes via STREAM pipes using "band" mode. + /// Send iovecs via <::writev>. ssize_t send (const iovec iov[], size_t n) const; - // Send iovecs via <::writev>. + /// Recv iovecs via <::readv>. ssize_t recv (iovec iov[], size_t n) const; - // Recv iovecs via <::readv>. + /** + * Send N char *ptrs and int lengths. Note that the char *'s + * precede the ints (basically, an varargs version of writev). The + * count N is the *total* number of trailing arguments, *not* a + * couple of the number of tuple pairs! + */ ssize_t send (size_t n, ...) const; - // Send N char *ptrs and int lengths. Note that the char *'s - // precede the ints (basically, an varargs version of writev). The - // count N is the *total* number of trailing arguments, *not* a - // couple of the number of tuple pairs! + /** + * This is an interface to ::readv, that doesn't use the struct + * iovec explicitly. The ... can be passed as an arbitrary number + * of (char *ptr, int len) tuples. However, the count N is the + * *total* number of trailing arguments, *not* a couple of the + * number of tuple pairs! + */ ssize_t recv (size_t n, ...) const; - // This is an interface to ::readv, that doesn't use the struct - // iovec explicitly. The ... can be passed as an arbitrary number - // of (char *ptr, int len) tuples. However, the count N is the - // *total* number of trailing arguments, *not* a couple of the - // number of tuple pairs! + /// Send <n> bytes via Win32 WriteFile using overlapped I/O. ssize_t send (const void *buf, size_t n, ACE_OVERLAPPED *overlapped) const; - // Send <n> bytes via Win32 WriteFile using overlapped I/O. + /// Recv <n> bytes via Win32 ReadFile using overlapped I/O. ssize_t recv (void *buf, size_t n, ACE_OVERLAPPED *overlapped) const; - // Recv <n> bytes via Win32 ReadFile using overlapped I/O. + /// Send an <iovec> of size <n> to the stream. ssize_t sendv (const iovec iov[], size_t n) const; - // Send an <iovec> of size <n> to the stream. + /// Send an <iovec> of size <n> to the stream. Will block until all + /// bytes are sent or an error occurs. ssize_t sendv_n (const iovec iov[], size_t n) const; - // Send an <iovec> of size <n> to the stream. Will block until all - // bytes are sent or an error occurs. + /// Receive an <iovec> of size <n> to the stream. ssize_t recvv_n (iovec iov[], size_t n) const; - // Receive an <iovec> of size <n> to the stream. // = Meta-type info typedef ACE_SPIPE_Addr PEER_ADDR; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: ACE_SPIPE_Addr remote_addr_; diff --git a/ace/SString.h b/ace/SString.h index 7fd0cda8fab..af2194eadb8 100644 --- a/ace/SString.h +++ b/ace/SString.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SString.h -// -// = AUTHOR -// Douglas C. Schmidt (schmidt@cs.wustl.edu) -// -// ============================================================================ + +//============================================================================= +/** + * @file SString.h + * + * $Id$ + * + * @author Douglas C. Schmidt (schmidt@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_SSTRING_H #define ACE_SSTRING_H @@ -33,350 +30,364 @@ typedef ACE_USHORT16 ACE_WSTRING_TYPE; // Forward decl. class ACE_Allocator; +/** + * @class ACE_CString + * + * @brief This class provides a wrapper facade for C strings. + * + * This class uses an <ACE_Allocator> to allocate memory. The + * user can make this a persistant class by providing an + * ACE_Allocator with a persistable memory pool. This class is + * optimized for efficiency, so it doesn't provide any internal + * locking. + * NOTE: if an instance of this class is constructed from or + * assigned an empty string (with first element of '\0'), then it + * is _not_ allocated new space. Instead, its internal + * representation is set equal to a global empty string. + * CAUTION: in cases when ACE_CString is constructed from a + * provided buffer with the release parameter set to 0, + * ACE_CString is not guaranteed to be '\0' terminated. + */ class ACE_Export ACE_CString { - // = TITLE - // This class provides a wrapper facade for C strings. - // - // = DESCRIPTION - // This class uses an <ACE_Allocator> to allocate memory. The - // user can make this a persistant class by providing an - // ACE_Allocator with a persistable memory pool. This class is - // optimized for efficiency, so it doesn't provide any internal - // locking. - // - // NOTE: if an instance of this class is constructed from or - // assigned an empty string (with first element of '\0'), then it - // is _not_ allocated new space. Instead, its internal - // representation is set equal to a global empty string. - // - // CAUTION: in cases when ACE_CString is constructed from a - // provided buffer with the release parameter set to 0, - // ACE_CString is not guaranteed to be '\0' terminated. public: + /// No position constant static const int npos; - // No position constant + /// Default constructor. ACE_CString (ACE_Allocator *alloc = 0); - // Default constructor. + /** + * Constructor that copies <s> into dynamically allocated memory. + * If <release> is non-0 then the <ACE_allocator> is responsible for + * freeing this memory. Memory is _not_ allocated/freed if <release> + * is 0. + */ ACE_CString (const char *s, ACE_Allocator *alloc = 0, int release = 1); - // Constructor that copies <s> into dynamically allocated memory. - // If <release> is non-0 then the <ACE_allocator> is responsible for - // freeing this memory. Memory is _not_ allocated/freed if <release> - // is 0. + /** + * Constructor that copies <len> chars of <s> into dynamically + * allocated memory (will NUL terminate the result). If <release> + * is non-0 then the <ACE_allocator> is responsible for freeing this + * memory. Memory is _not_ allocated/freed if <release> is 0. + */ ACE_CString (const char *s, size_t len, ACE_Allocator *alloc = 0, int release = 1); - // Constructor that copies <len> chars of <s> into dynamically - // allocated memory (will NUL terminate the result). If <release> - // is non-0 then the <ACE_allocator> is responsible for freeing this - // memory. Memory is _not_ allocated/freed if <release> is 0. + /// Copy constructor. ACE_CString (const ACE_CString &); - // Copy constructor. + /// Constructor that copies <s> into dynamically allocated memory. + /// Probable loss of data. Please use with care. ACE_CString (const ACE_WSTRING_TYPE *s, ACE_Allocator *alloc = 0); - // Constructor that copies <s> into dynamically allocated memory. - // Probable loss of data. Please use with care. + /// Constructor that copies <c> into dynamically allocated memory. ACE_CString (char c, ACE_Allocator *alloc = 0); - // Constructor that copies <c> into dynamically allocated memory. + /// Deletes the memory... ~ACE_CString (void); - // Deletes the memory... + /// Return the <slot'th> character in the string (doesn't perform + /// bounds checking). const char &operator [] (size_t slot) const; - // Return the <slot'th> character in the string (doesn't perform - // bounds checking). + /// Return the <slot'th> character by reference in the string + /// (doesn't perform bounds checking). char &operator [] (size_t slot); - // Return the <slot'th> character by reference in the string - // (doesn't perform bounds checking). + /// Assignment operator (does copy memory). ACE_CString &operator = (const ACE_CString &); - // Assignment operator (does copy memory). + /// Copy <s> into this <ACE_CString>. Memory is _not_ + /// allocated/freed if <release> is 0. void set (const char *s, int release = 1); - // Copy <s> into this <ACE_CString>. Memory is _not_ - // allocated/freed if <release> is 0. + /// Copy <len> bytes of <s> (will NUL terminate the result). + /// Memory is _not_ allocated/freed if <release> is 0. void set (const char *s, size_t len, int release); - // Copy <len> bytes of <s> (will NUL terminate the result). - // Memory is _not_ allocated/freed if <release> is 0. + /** + * Return a substring given an offset and length, if length == -1 + * use rest of str. Return empty substring if offset or + * offset/length are invalid. + */ ACE_CString substring (size_t offset, ssize_t length = -1) const; - // Return a substring given an offset and length, if length == -1 - // use rest of str. Return empty substring if offset or - // offset/length are invalid. + /// Same as <substring>. ACE_CString substr (size_t offset, ssize_t length = -1) const; - // Same as <substring>. + /// Concat operator (copies memory). ACE_CString &operator += (const ACE_CString &); - // Concat operator (copies memory). + /// Returns a hash value for this string. u_long hash (void) const; - // Returns a hash value for this string. + /// Return the length of the string. size_t length (void) const; - // Return the length of the string. + /// Get a copy of the underlying pointer. char *rep (void) const; - // Get a copy of the underlying pointer. + /** + * Get at the underlying representation directly! + * _Don't_ even think about casting the result to (char *) and modifying it, + * if it has length 0! + */ const char *fast_rep (void) const; - // Get at the underlying representation directly! - // _Don't_ even think about casting the result to (char *) and modifying it, - // if it has length 0! + /// Same as STL String's <c_str> and <fast_rep>. const char *c_str (void) const; - // Same as STL String's <c_str> and <fast_rep>. + /// Comparison operator that will match substrings. Returns the + /// slot of the first location that matches, else -1. int strstr (const ACE_CString &s) const; - // Comparison operator that will match substrings. Returns the - // slot of the first location that matches, else -1. + /// Find <str> starting at pos. Returns the slot of the first + /// location that matches, else npos. int find (const ACE_CString &str, int pos = 0) const; - // Find <str> starting at pos. Returns the slot of the first - // location that matches, else npos. + /// Find <s> starting at pos. Returns the slot of the first + /// location that matches, else npos. int find (const char *s, int pos = 0) const; - // Find <s> starting at pos. Returns the slot of the first - // location that matches, else npos. + /// Find <c> starting at pos. Returns the slot of the first + /// location that matches, else npos. int find (char c, int pos = 0) const; - // Find <c> starting at pos. Returns the slot of the first - // location that matches, else npos. + /// Find <c> starting at pos (counting from the end). Returns the + /// slot of the first location that matches, else npos. int rfind (char c, int pos = npos) const; - // Find <c> starting at pos (counting from the end). Returns the - // slot of the first location that matches, else npos. + /// Equality comparison operator (must match entire string). int operator == (const ACE_CString &s) const; - // Equality comparison operator (must match entire string). + /// Less than comparison operator. int operator < (const ACE_CString &s) const; - // Less than comparison operator. + /// Greater than comparison operator. int operator > (const ACE_CString &s) const; - // Greater than comparison operator. + /// Inequality comparison operator. int operator != (const ACE_CString &s) const; - // Inequality comparison operator. + /// Performs a <strcmp>-style comparison. int compare (const ACE_CString &s) const; - // Performs a <strcmp>-style comparison. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to a memory allocator. ACE_Allocator *allocator_; - // Pointer to a memory allocator. + /// Length of the ACE_CString data (not counting the trailing '\0'). size_t len_; - // Length of the ACE_CString data (not counting the trailing '\0'). + /// Length of the ACE_CString data buffer. Keeping track of the + /// length allows to avoid unnecessary dynamic allocations. size_t buf_len_; - // Length of the ACE_CString data buffer. Keeping track of the - // length allows to avoid unnecessary dynamic allocations. + /// Pointer to data. char *rep_; - // Pointer to data. + /// Flag that indicates if we own the memory int release_; - // Flag that indicates if we own the memory + /// Represents the "NULL" string to simplify the internal logic. static char NULL_CString_; - // Represents the "NULL" string to simplify the internal logic. }; -ACE_Export ACE_INLINE ACE_CString operator + (const ACE_CString &, +ACE_Export ACE_INLINE ACE_CString operator + (const ACE_CString &, const ACE_CString &); #if !defined (ACE_LACKS_IOSTREAM_TOTALLY) ACE_Export ostream &operator << (ostream &, const ACE_CString &); #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */ +/** + * @class ACE_WString + * + * @brief This class provides a wrapper facade for C wide strings. + * + * This class uses an <ACE_Allocator> to allocate memory. The + * user can make this a persistant class by providing an + * <ACE_Allocator> with a persistable memory pool. This class is + * optimized for efficiency, so it doesn't provide any internal + * locking. + */ class ACE_Export ACE_WString { - // = TITLE - // This class provides a wrapper facade for C wide strings. - // - // = DESCRIPTION - // This class uses an <ACE_Allocator> to allocate memory. The - // user can make this a persistant class by providing an - // <ACE_Allocator> with a persistable memory pool. This class is - // optimized for efficiency, so it doesn't provide any internal - // locking. public: + /// No position constant static const int npos; - // No position constant + /// Default constructor. ACE_WString (ACE_Allocator *alloc = 0); - // Default constructor. + /// Constructor that copies <s> into dynamically allocated memory. ACE_WString (const char *s, ACE_Allocator *alloc = 0); - // Constructor that copies <s> into dynamically allocated memory. + /// Constructor that copies <s> into dynamically allocated memory. ACE_WString (const ACE_WSTRING_TYPE *s, ACE_Allocator *alloc = 0); - // Constructor that copies <s> into dynamically allocated memory. #if defined (ACE_WSTRING_HAS_USHORT_SUPPORT) + /// Constructor that takes in a ushort16 string (mainly used by the + /// ACE Name_Space classes) ACE_WString (const ACE_USHORT16 *s, size_t len, ACE_Allocator *alloc = 0); - // Constructor that takes in a ushort16 string (mainly used by the - // ACE Name_Space classes) #endif /* ACE_WSTRING_HAS_USHORT_SUPPORT */ + /// Constructor that copies <len> ACE_WSTRING_TYPE's of <s> into dynamically + /// allocated memory (will NUL terminate the result). ACE_WString (const ACE_WSTRING_TYPE *s, size_t len, ACE_Allocator *alloc = 0); - // Constructor that copies <len> ACE_WSTRING_TYPE's of <s> into dynamically - // allocated memory (will NUL terminate the result). + /// Constructor that dynamically allocates memory for <len> + 1 + /// ACE_WSTRING_TYPE characters. The newly created memory is set memset to 0. ACE_WString (size_t len, ACE_Allocator *alloc = 0); - // Constructor that dynamically allocates memory for <len> + 1 - // ACE_WSTRING_TYPE characters. The newly created memory is set memset to 0. + /// Copy constructor. ACE_WString (const ACE_WString &s); - // Copy constructor. + /// Constructor that copies <c> into dynamically allocated memory. ACE_WString (ACE_WSTRING_TYPE c, ACE_Allocator *alloc = 0); - // Constructor that copies <c> into dynamically allocated memory. + /// Deletes the memory... ~ACE_WString (void); - // Deletes the memory... + /// Return the <slot'th> character in the string (doesn't perform + /// bounds checking). ACE_WSTRING_TYPE operator [] (size_t slot) const; - // Return the <slot'th> character in the string (doesn't perform - // bounds checking). + /// Return the <slot'th> character by reference in the string + /// (doesn't perform bounds checking). ACE_WSTRING_TYPE &operator [] (size_t slot); - // Return the <slot'th> character by reference in the string - // (doesn't perform bounds checking). + /// Assignment operator (does copy memory). ACE_WString &operator = (const ACE_WString &); - // Assignment operator (does copy memory). + /// Copy <s> void set (const ACE_WSTRING_TYPE *s); - // Copy <s> + /// Copy <len> bytes of <s> (will NUL terminate the result) void set (const ACE_WSTRING_TYPE *s, size_t len); - // Copy <len> bytes of <s> (will NUL terminate the result) + /** + * Return a substring given an offset and length, if length == -1 + * use rest of str return empty substring if offset or offset/length + * are invalid. + */ ACE_WString substring (size_t offset, ssize_t length = -1) const; - // Return a substring given an offset and length, if length == -1 - // use rest of str return empty substring if offset or offset/length - // are invalid. + /// Same as substring ACE_WString substr (size_t offset, ssize_t length = -1) const; - // Same as substring + /// Concat operator (does copy memory). ACE_WString &operator += (const ACE_WString &); - // Concat operator (does copy memory). + /// Returns a hash value for this string. u_long hash (void) const; - // Returns a hash value for this string. + /// Return the length of the string. size_t length (void) const; - // Return the length of the string. + /// Gets a copy of the underlying pointer. ACE_WSTRING_TYPE *rep (void) const; - // Gets a copy of the underlying pointer. + /// Transform into a copy of the ASCII character representation. + /// (caller must delete) char *char_rep (void) const; - // Transform into a copy of the ASCII character representation. - // (caller must delete) + /// Transform into a copy of a USHORT16 representation (caller must + /// delete). Note, behavior is undefined when sizeof (wchar_t) != 2. ACE_USHORT16 *ushort_rep (void) const; - // Transform into a copy of a USHORT16 representation (caller must - // delete). Note, behavior is undefined when sizeof (wchar_t) != 2. + /// Get at the underlying representation directly! const ACE_WSTRING_TYPE *fast_rep (void) const; - // Get at the underlying representation directly! + /// Same as STL String's <c_str> and <fast_rep>. const ACE_WSTRING_TYPE *c_str (void) const; - // Same as STL String's <c_str> and <fast_rep>. + /// Comparison operator that will match substrings. Returns the + /// slot of the first location that matches, else -1. int strstr (const ACE_WString &s) const; - // Comparison operator that will match substrings. Returns the - // slot of the first location that matches, else -1. + /// Find <str> starting at pos. Returns the slot of the first + /// location that matches, else npos. int find (const ACE_WString &str, int pos = 0) const; - // Find <str> starting at pos. Returns the slot of the first - // location that matches, else npos. + /// Find <s> starting at pos. Returns the slot of the first + /// location that matches, else npos. int find (const ACE_WSTRING_TYPE *s, int pos = 0) const; - // Find <s> starting at pos. Returns the slot of the first - // location that matches, else npos. + /// Find <c> starting at pos. Returns the slot of the first + /// location that matches, else npos. int find (ACE_WSTRING_TYPE c, int pos = 0) const; - // Find <c> starting at pos. Returns the slot of the first - // location that matches, else npos. + /// Find <c> starting at pos (counting from the end). Returns the + /// slot of the first location that matches, else npos. int rfind (ACE_WSTRING_TYPE c, int pos = npos) const; - // Find <c> starting at pos (counting from the end). Returns the - // slot of the first location that matches, else npos. + /// Equality comparison operator (must match entire string). int operator == (const ACE_WString &s) const; - // Equality comparison operator (must match entire string). + /// Less than comparison operator. int operator < (const ACE_WString &s) const; - // Less than comparison operator. + /// Greater than comparison operator. int operator > (const ACE_WString &s) const; - // Greater than comparison operator. + /// Inequality comparison operator. int operator != (const ACE_WString &s) const; - // Inequality comparison operator. + /// Performs a <strcmp>-style comparison. int compare (const ACE_WString &s) const; - // Performs a <strcmp>-style comparison. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /// Computes the length of a "0" terminated ACE_WSTRING_TYPE *. static size_t strlen (const ACE_WSTRING_TYPE *); - // Computes the length of a "0" terminated ACE_WSTRING_TYPE *. - static const ACE_WSTRING_TYPE *strstr (const ACE_WSTRING_TYPE *s1, + /// Traditional style strstr + static const ACE_WSTRING_TYPE *strstr (const ACE_WSTRING_TYPE *s1, const ACE_WSTRING_TYPE *s2); - // Traditional style strstr + /** + * This method is designed for high-performance. Please use with + * care ;-) If the current size of the string is less than <len>, + * the string is resized to the new length. The data is is zero'd + * out after this operation. + */ void resize (size_t len); - // This method is designed for high-performance. Please use with - // care ;-) If the current size of the string is less than <len>, - // the string is resized to the new length. The data is is zero'd - // out after this operation. private: + /// Pointer to a memory allocator. ACE_Allocator *allocator_; - // Pointer to a memory allocator. + /// Length of the ACE_WString. size_t len_; - // Length of the ACE_WString. + /// Pointer to data. ACE_WSTRING_TYPE *rep_; - // Pointer to data. }; ACE_Export ACE_INLINE ACE_WString operator+ (const ACE_WString &, @@ -385,137 +396,140 @@ ACE_Export ACE_INLINE ACE_WString operator+ (const ACE_WString &, ACE_Export ostream &operator << (ostream &, const ACE_WString &); #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */ +/** + * @class ACE_SString + * + * @brief A very Simple String <ACE_SString> class. This is not a + * general-purpose string class, and you should probably consider + * using <ACE_CString> is you don't understand why this class + * exists... + * + * This class is optimized for efficiency, so it doesn't provide + * any internal locking. + * CAUTION: This class is only intended for use with applications + * that understand how it works. In particular, its destructor + * does not deallocate its memory when it is destroyed... We need + * this class since the <ACE_Map_Manager> requires an object that + * supports the operator == and operator !=. This class uses an + * <ACE_Allocator> to allocate memory. The user can make this a + * persistant class by providing an <ACE_Allocator> with a + * persistable memory pool. + */ class ACE_Export ACE_SString { - // = TITLE - // A very Simple String <ACE_SString> class. This is not a - // general-purpose string class, and you should probably consider - // using <ACE_CString> is you don't understand why this class - // exists... - // - // = DESCRIPTION - // This class is optimized for efficiency, so it doesn't provide - // any internal locking. - // - // CAUTION: This class is only intended for use with applications - // that understand how it works. In particular, its destructor - // does not deallocate its memory when it is destroyed... We need - // this class since the <ACE_Map_Manager> requires an object that - // supports the operator == and operator !=. This class uses an - // <ACE_Allocator> to allocate memory. The user can make this a - // persistant class by providing an <ACE_Allocator> with a - // persistable memory pool. public: + /// No position constant static const int npos; - // No position constant + /// Default constructor. ACE_SString (ACE_Allocator *alloc = 0); - // Default constructor. + /// Constructor that copies <s> into dynamically allocated memory. ACE_SString (const char *s, ACE_Allocator *alloc = 0); - // Constructor that copies <s> into dynamically allocated memory. + /// Constructor that copies <len> chars of <s> into dynamically + /// allocated memory (will NUL terminate the result). ACE_SString (const char *s, size_t len, ACE_Allocator *alloc = 0); - // Constructor that copies <len> chars of <s> into dynamically - // allocated memory (will NUL terminate the result). + /// Copy constructor. ACE_SString (const ACE_SString &); - // Copy constructor. + /// Constructor that copies <c> into dynamically allocated memory. ACE_SString (char c, ACE_Allocator *alloc = 0); - // Constructor that copies <c> into dynamically allocated memory. + /// Default dtor. ~ACE_SString (void); - // Default dtor. + /// Return the <slot'th> character in the string (doesn't perform + /// bounds checking). char operator [] (size_t slot) const; - // Return the <slot'th> character in the string (doesn't perform - // bounds checking). + /// Return the <slot'th> character by reference in the string + /// (doesn't perform bounds checking). char &operator [] (size_t slot); - // Return the <slot'th> character by reference in the string - // (doesn't perform bounds checking). + /// Assignment operator (does copy memory). ACE_SString &operator = (const ACE_SString &); - // Assignment operator (does copy memory). + /** + * Return a substring given an offset and length, if length == -1 + * use rest of str return empty substring if offset or offset/length + * are invalid + */ ACE_SString substring (size_t offset, ssize_t length = -1) const; - // Return a substring given an offset and length, if length == -1 - // use rest of str return empty substring if offset or offset/length - // are invalid + /// Same as substring ACE_SString substr (size_t offset, ssize_t length = -1) const; - // Same as substring + /// Returns a hash value for this string. u_long hash (void) const; - // Returns a hash value for this string. + /// Return the length of the string. size_t length (void) const; - // Return the length of the string. + /// Set the underlying pointer. Since this does not copy memory or + /// delete existing memory use with extreme caution!!! void rep (char *s); - // Set the underlying pointer. Since this does not copy memory or - // delete existing memory use with extreme caution!!! + /// Get the underlying pointer. const char *rep (void) const; - // Get the underlying pointer. + /// Get the underlying pointer. const char *fast_rep (void) const; - // Get the underlying pointer. + /// Same as STL String's <c_str> and <fast_rep>. const char *c_str (void) const; - // Same as STL String's <c_str> and <fast_rep>. + /// Comparison operator that will match substrings. Returns the + /// slot of the first location that matches, else -1. int strstr (const ACE_SString &s) const; - // Comparison operator that will match substrings. Returns the - // slot of the first location that matches, else -1. + /// Find <str> starting at pos. Returns the slot of the first + /// location that matches, else npos. int find (const ACE_SString &str, int pos = 0) const; - // Find <str> starting at pos. Returns the slot of the first - // location that matches, else npos. + /// Find <s> starting at pos. Returns the slot of the first + /// location that matches, else npos. int find (const char *s, int pos = 0) const; - // Find <s> starting at pos. Returns the slot of the first - // location that matches, else npos. + /// Find <c> starting at pos. Returns the slot of the first + /// location that matches, else npos. int find (char c, int pos = 0) const; - // Find <c> starting at pos. Returns the slot of the first - // location that matches, else npos. + /// Find <c> starting at pos (counting from the end). Returns the + /// slot of the first location that matches, else npos. int rfind (char c, int pos = npos) const; - // Find <c> starting at pos (counting from the end). Returns the - // slot of the first location that matches, else npos. + /// Equality comparison operator (must match entire string). int operator == (const ACE_SString &s) const; - // Equality comparison operator (must match entire string). + /// Less than comparison operator. int operator < (const ACE_SString &s) const; - // Less than comparison operator. + /// Greater than comparison operator. int operator > (const ACE_SString &s) const; - // Greater than comparison operator. + /// Inequality comparison operator. int operator != (const ACE_SString &s) const; - // Inequality comparison operator. + /// Performs a <strcmp>-style comparison. int compare (const ACE_SString &s) const; - // Performs a <strcmp>-style comparison. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to a memory allocator. ACE_Allocator *allocator_; - // Pointer to a memory allocator. + /// Length of the ACE_SString (not counting the trailing '\0'). size_t len_; - // Length of the ACE_SString (not counting the trailing '\0'). + /// Pointer to data. char *rep_; - // Pointer to data. }; #if !defined (ACE_LACKS_IOSTREAM_TOTALLY) @@ -533,35 +547,41 @@ ACE_Export ostream &operator << (ostream &, const ACE_SString &); // ************************************************************ +/** + * @class ACE_Tokenizer + * + * @brief Tokenizer + * + * Tokenizes a buffer. Allows application to set delimiters and + * preserve designators. Does not allow special characters, yet + * (e.g., printf ("\"like a quoted string\"")). + */ class ACE_Export ACE_Tokenizer { - // = TITLE - // Tokenizer - // - // = DESCRIPTION - // Tokenizes a buffer. Allows application to set delimiters and - // preserve designators. Does not allow special characters, yet - // (e.g., printf ("\"like a quoted string\"")). public: + /// <buffer> will be parsed. ACE_Tokenizer (ACE_TCHAR *buffer); - // <buffer> will be parsed. + /// <d> is a delimiter. Returns 0 on success, -1 if there is no + /// memory left. int delimiter (ACE_TCHAR d); - // <d> is a delimiter. Returns 0 on success, -1 if there is no - // memory left. + /** + * <d> is a delimiter and, when found, will be replaced by + * <replacement>. Returns 0 on success, -1 if there is no memory + * left. + */ int delimiter_replace (ACE_TCHAR d, ACE_TCHAR replacement); - // <d> is a delimiter and, when found, will be replaced by - // <replacement>. Returns 0 on success, -1 if there is no memory - // left. + /** + * For instance, quotes, or '(' and ')'. Returns 0 on success, -1 + * if there is no memory left. If <strip> == 1, then the preserve + * designators will be stripped from the tokens returned by next. + */ int preserve_designators (ACE_TCHAR start, ACE_TCHAR stop, int strip=1); - // For instance, quotes, or '(' and ')'. Returns 0 on success, -1 - // if there is no memory left. If <strip> == 1, then the preserve - // designators will be stripped from the tokens returned by next. + /// Returns the next token. ACE_TCHAR *next (void); - // Returns the next token. enum { MAX_DELIMITERS=16, @@ -569,85 +589,96 @@ public: }; protected: + /// Returns 1 if <d> is a delimiter, 0 otherwise. If <d> should be + /// replaced with <r>, <replace> is set to 1, otherwise 0. int is_delimiter (ACE_TCHAR d, int &replace, ACE_TCHAR &r); - // Returns 1 if <d> is a delimiter, 0 otherwise. If <d> should be - // replaced with <r>, <replace> is set to 1, otherwise 0. + /** + * If <start> is a start preserve designator, returns 1 and sets + * <stop> to the stop designator. Returns 0 if <start> is not a + * preserve designator. + */ int is_preserve_designator (ACE_TCHAR start, ACE_TCHAR &stop, int &strip); - // If <start> is a start preserve designator, returns 1 and sets - // <stop> to the stop designator. Returns 0 if <start> is not a - // preserve designator. private: ACE_TCHAR *buffer_; int index_; + /** + * @class Preserve_Entry + * + * @brief Preserve Entry + * + * Defines a set of characters that designate an area that + * should not be parsed, but should be treated as a complete + * token. For instance, in: (this is a preserve region), start + * would be a left paren -(- and stop would be a right paren + * -)-. The strip determines whether the designators should be + * removed from the token. + */ class Preserve_Entry { - // = TITLE - // Preserve Entry - // - // = DESCRIPTION - // Defines a set of characters that designate an area that - // should not be parsed, but should be treated as a complete - // token. For instance, in: (this is a preserve region), start - // would be a left paren -(- and stop would be a right paren - // -)-. The strip determines whether the designators should be - // removed from the token. public: + /** + * E.g., "(". + * E.g., ")". + * Whether the designators should be removed from the token. + */ ACE_TCHAR start_; - // E.g., "(". ACE_TCHAR stop_; - // E.g., ")". int strip_; - // Whether the designators should be removed from the token. }; + /// The application can specify MAX_PRESERVES preserve designators. Preserve_Entry preserves_[MAX_PRESERVES]; - // The application can specify MAX_PRESERVES preserve designators. + /// Pointer to the next free spot in preserves_. int preserves_index_; - // Pointer to the next free spot in preserves_. + /** + * @class Delimiter_Entry + * + * @brief Delimiter Entry + * + * Describes a delimiter for the tokenizer. + */ class Delimiter_Entry { - // = TITLE - // Delimiter Entry - // - // = DESCRIPTION - // Describes a delimiter for the tokenizer. public: + /** + * Most commonly a space ' '. + * What occurrences of delimiter_ should be replaced with. + * Whether replacement_ should be used. This should be replaced + * with a technique that sets replacement_ = delimiter by + * default. I'll do that next iteration. + */ ACE_TCHAR delimiter_; - // Most commonly a space ' '. ACE_TCHAR replacement_; - // What occurrences of delimiter_ should be replaced with. int replace_; - // Whether replacement_ should be used. This should be replaced - // with a technique that sets replacement_ = delimiter by - // default. I'll do that next iteration. }; + /// The tokenizer allows MAX_DELIMITERS number of delimiters. Delimiter_Entry delimiters_[MAX_DELIMITERS]; - // The tokenizer allows MAX_DELIMITERS number of delimiters. + /// Pointer to the next free space in delimiters_. int delimiter_index_; - // Pointer to the next free space in delimiters_. }; // **************************************************************** +/** + * @class ACE_Auto_String_Free + * + * @brief Simple class to automatically de-allocate strings + * + * Keeps a pointer to a string and deallocates it (using + * <ACE_OS::free>) on its destructor. + * If you need to delete using "delete[]" the + * ACE_Auto_Array_Ptr<char*> is your choice. + * The class plays the same role as auto_ptr<> + */ class ACE_Export ACE_Auto_String_Free { - // = TITLE - // Simple class to automatically de-allocate strings - // - // = DESCRIPTION - // Keeps a pointer to a string and deallocates it (using - // <ACE_OS::free>) on its destructor. - // If you need to delete using "delete[]" the - // ACE_Auto_Array_Ptr<char*> is your choice. - // The class plays the same role as auto_ptr<> - // public: ACE_EXPLICIT ACE_Auto_String_Free (char* p = 0); ACE_Auto_String_Free (ACE_Auto_String_Free &rhs); diff --git a/ace/SUN_Proactor.h b/ace/SUN_Proactor.h index 900138bb9a4..5bb8feb08b9 100644 --- a/ace/SUN_Proactor.h +++ b/ace/SUN_Proactor.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SUN_Proactor.h -// -// = AUTHOR -// Alexander Libman <alibman@baltimore.com> -// -// ============================================================================ + +//============================================================================= +/** + * @file SUN_Proactor.h + * + * $Id$ + * + * @author Alexander Libman <alibman@baltimore.com> + */ +//============================================================================= + #ifndef ACE_SUN_PROACTOR_H #define ACE_SUN_PROACTOR_H @@ -23,83 +20,88 @@ #include "sys/asynch.h" // Sun native aio calls +/** + * @class ACE_SUN_Proactor + * + * @brief Implementation of the fast and reliable Proactor + * for SunOS 5.6, 5.7, etc. + * + * This proactor, based on <ACE_POSIX_AIOCB_Proactor>, + * works with Sun native interface for aio calls. + * POSIX_API Native SUN_API + * aio_read aioread + * aio_write aiowrite + * aio_suspend aiowait + * aio_error aio_result_t.errno + * aio_return aio_result_t.return + * On Solaris, the Sun <aio*()> native implementation is more + * reliable and efficient than POSIX <aio_*()> implementation. + * There is a problem of lost RT signals with POSIX, if we start + * more than SIGQUEUEMAX asynchronous operations at the same + * time. + * The Sun <aiocb> it is not the standard POSX <aiocb>, instead, + * it has the following structure: + * typedef struct aiocb + * { + * int aio_fildes; File descriptor + * void *aio_buf; buffer location + * size_t aio_nbytes; length of transfer + * off_t aio_offset; file offset + * int aio_reqprio; request priority offset + * sigevent aio_sigevent; signal number and offset + * int aio_lio_opcode; listio operation + * aio_result_t aio_resultp; results + * int aio_state; state flag for List I/O + * int aio__pad[1]; extension padding + * }; + */ class ACE_Export ACE_SUN_Proactor : public ACE_POSIX_AIOCB_Proactor { - // = TITLE - // Implementation of the fast and reliable Proactor - // for SunOS 5.6, 5.7, etc. - // - // = DESCRIPTION - // This proactor, based on <ACE_POSIX_AIOCB_Proactor>, - // works with Sun native interface for aio calls. - // POSIX_API Native SUN_API - // aio_read aioread - // aio_write aiowrite - // aio_suspend aiowait - // aio_error aio_result_t.errno - // aio_return aio_result_t.return - // - // On Solaris, the Sun <aio*()> native implementation is more - // reliable and efficient than POSIX <aio_*()> implementation. - // There is a problem of lost RT signals with POSIX, if we start - // more than SIGQUEUEMAX asynchronous operations at the same - // time. - // - // The Sun <aiocb> it is not the standard POSX <aiocb>, instead, - // it has the following structure: - // - // typedef struct aiocb - // { - // int aio_fildes; File descriptor - // void *aio_buf; buffer location - // size_t aio_nbytes; length of transfer - // off_t aio_offset; file offset - // int aio_reqprio; request priority offset - // sigevent aio_sigevent; signal number and offset - // int aio_lio_opcode; listio operation - // aio_result_t aio_resultp; results - // int aio_state; state flag for List I/O - // int aio__pad[1]; extension padding - // }; public: virtual Proactor_Type get_impl_type (void); + /// Destructor. virtual ~ACE_SUN_Proactor (void); - // Destructor. - + // @@ Alex, this shouldn't be a magic number, i.e., it should be a // constant, such as ACE_MAX_AIO_OPERATIONS. + /// Constructor defines max number asynchronous operations that can + /// be started at the same time. ACE_SUN_Proactor (size_t max_aio_operations = 512); - // Constructor defines max number asynchronous operations that can - // be started at the same time. protected: + /** + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (ACE_Time_Value &wait_time); - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. + /** + * Dispatch a single set of events. If <milli_seconds> elapses + * before any events occur, return 0. Return 1 if a completion is + * dispatched. Return -1 on errors. + */ virtual int handle_events (u_long milli_seconds); - // Dispatch a single set of events. If <milli_seconds> elapses - // before any events occur, return 0. Return 1 if a completion is - // dispatched. Return -1 on errors. - + + /** + * Block indefinitely until at least one event is dispatched. + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (void); - // Block indefinitely until at least one event is dispatched. - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. + /// From ACE_POSIX_AIOCB_Proactor. virtual int start_aio (ACE_POSIX_Asynch_Result *result, int op); - // From ACE_POSIX_AIOCB_Proactor. + /// Extract the results of aio. ACE_POSIX_Asynch_Result *find_completed_aio (aio_result_t *result, int &error_status, int &return_status); - // Extract the results of aio. }; #if defined (__ACE_INLINE__) @@ -108,4 +110,3 @@ protected: #endif /* ACE_HAS_AIO_CALLS && sun */ #endif /* ACE_SUN_PROACTOR_H*/ - diff --git a/ace/SV_Message.h b/ace/SV_Message.h index 64d36b235a6..b93d9e531e5 100644 --- a/ace/SV_Message.h +++ b/ace/SV_Message.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SV_Message.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file SV_Message.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SV_MESSAGE_H #define ACE_SV_MESSAGE_H @@ -24,10 +21,13 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_SV_Message + * + * @brief Defines the header file for the C++ wrapper for message queues. + */ class ACE_Export ACE_SV_Message { - // = TITLE - // Defines the header file for the C++ wrapper for message queues. */ public: // = Initialization and termination methods. ACE_SV_Message (long type = 0); @@ -37,15 +37,15 @@ public: long type (void) const; void type (long); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Type of the message. long type_; - // Type of the message. }; #if defined (__ACE_INLINE__) diff --git a/ace/SV_Message_Queue.h b/ace/SV_Message_Queue.h index 060a1be6b33..ad8caffdca7 100644 --- a/ace/SV_Message_Queue.h +++ b/ace/SV_Message_Queue.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SV_Message_Queue.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file SV_Message_Queue.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SV_MESSAGE_QUEUE_H #define ACE_SV_MESSAGE_QUEUE_H @@ -26,11 +23,14 @@ #include "ace/SV_Message.h" +/** + * @class ACE_SV_Message_Queue + * + * @brief Defines the header file for the C++ wrapper for System V IPC + * message queues. + */ class ACE_Export ACE_SV_Message_Queue { - // = TITLE - // Defines the header file for the C++ wrapper for System V IPC - // message queues. public: // = Useful symbolic constants. enum @@ -41,6 +41,7 @@ public: }; // = Initialization and termination methods. + /// Open a message queue using the <external_id>. ACE_SV_Message_Queue (void); ACE_SV_Message_Queue (key_t external_id, int create = ACE_SV_Message_Queue::ACE_OPEN, @@ -48,16 +49,15 @@ public: int open (key_t external_id, int create = ACE_SV_Message_Queue::ACE_OPEN, int perms = ACE_DEFAULT_FILE_PERMS); - // Open a message queue using the <external_id>. ~ACE_SV_Message_Queue (void); + /// Close down this instance of the message queue without removing it + /// from the system. int close (void); - // Close down this instance of the message queue without removing it - // from the system. + /// Close down and remove the message queue from the system. int remove (void); - // Close down and remove the message queue from the system. // = Message transfer methods. @@ -70,22 +70,22 @@ public: int length, int mflags = 0); + /// Access the underlying control operations. int control (int option, void *arg = 0); - // Access the underlying control operations. // = Get/set the underly internal id. int get_id (void) const; void set_id (int); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Returned from the underlying <msgget> system call. int internal_id_; - // Returned from the underlying <msgget> system call. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/SV_Semaphore_Complex.h b/ace/SV_Semaphore_Complex.h index 6d3cbd81dc6..e26901ac82b 100644 --- a/ace/SV_Semaphore_Complex.h +++ b/ace/SV_Semaphore_Complex.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ACE_SV_Semaphore_Complex.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file ACE_SV_Semaphore_Complex.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SV_SEMAPHORE_COMPLEX_H #define ACE_SV_SEMAPHORE_COMPLEX_H @@ -24,37 +21,37 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_SV_Semaphore_Complex + * + * @brief This is a more complex semaphore wrapper that handles race + * conditions for initialization correctly... + * + * This code is a port to C++, inspired by: W. Richard Stevens + * from his book: UNIX Network Programming (Prentice Hall, ISBN + * 0-13-949876-1 - 1990). We provide a simpler and easier to + * understand interface to the System V Semaphore system calls. + * We create and use a 2 + n-member set for the requested + * <ACE_SV_Semaphore_Complex>. The first member, [0], is a + * counter used to know when all processes have finished with + * the <ACE_SV_Semaphore_Complex>. The counter is initialized + * to a large number, decremented on every create or open and + * incremented on every close. This way we can use the "adjust" + * feature provided by System V so that any process that exit's + * without calling <close> is accounted for. It doesn't help us + * if the last process does this (as we have no way of getting + * control to remove the <ACE_SV_Semaphore_Complex>) but it + * will work if any process other than the last does an exit + * (intentional or unintentional). + * The second member, [1], of the semaphore is used as a lock + * variable to avoid any race conditions in the <create> and + * <close> functions. + * The members beyond [1] are actual semaphore values in the + * array of semaphores, which may be sized by the user in the + * constructor. + */ class ACE_Export ACE_SV_Semaphore_Complex : private ACE_SV_Semaphore_Simple { - // = TITLE - // This is a more complex semaphore wrapper that handles race - // conditions for initialization correctly... - // - // = DESCRIPTION - // This code is a port to C++, inspired by: W. Richard Stevens - // from his book: UNIX Network Programming (Prentice Hall, ISBN - // 0-13-949876-1 - 1990). We provide a simpler and easier to - // understand interface to the System V Semaphore system calls. - // We create and use a 2 + n-member set for the requested - // <ACE_SV_Semaphore_Complex>. The first member, [0], is a - // counter used to know when all processes have finished with - // the <ACE_SV_Semaphore_Complex>. The counter is initialized - // to a large number, decremented on every create or open and - // incremented on every close. This way we can use the "adjust" - // feature provided by System V so that any process that exit's - // without calling <close> is accounted for. It doesn't help us - // if the last process does this (as we have no way of getting - // control to remove the <ACE_SV_Semaphore_Complex>) but it - // will work if any process other than the last does an exit - // (intentional or unintentional). - // - // The second member, [1], of the semaphore is used as a lock - // variable to avoid any race conditions in the <create> and - // <close> functions. - // - // The members beyond [1] are actual semaphore values in the - // array of semaphores, which may be sized by the user in the - // constructor. public: enum { @@ -76,51 +73,53 @@ public: int perms = ACE_DEFAULT_FILE_PERMS); ~ACE_SV_Semaphore_Complex (void); + /// Open or create an array of SV_Semaphores. We return 0 if all is + /// OK, else -1. int open (const char *name, int flags = ACE_SV_Semaphore_Simple::ACE_CREATE, int initial_value = 1, u_short nsems = 1, int perms = ACE_DEFAULT_FILE_PERMS); - // Open or create an array of SV_Semaphores. We return 0 if all is - // OK, else -1. + /// Open or create an array of SV_Semaphores. We return 0 if all is + /// OK, else -1. int open (key_t key, int flags = ACE_SV_Semaphore_Simple::ACE_CREATE, int initial_value = 1, u_short nsems = 1, int perms = ACE_DEFAULT_FILE_PERMS); - // Open or create an array of SV_Semaphores. We return 0 if all is - // OK, else -1. + /** + * Close an ACE_SV_Semaphore. Unlike the <remove> method, this + * method is for a process to call before it exits, when it is done + * with the ACE_SV_Semaphore. We "decrement" the counter of + * processes using the ACE_SV_Semaphore, and if this was the last + * one, we can remove the ACE_SV_Semaphore. + */ int close (void); - // Close an ACE_SV_Semaphore. Unlike the <remove> method, this - // method is for a process to call before it exits, when it is done - // with the ACE_SV_Semaphore. We "decrement" the counter of - // processes using the ACE_SV_Semaphore, and if this was the last - // one, we can remove the ACE_SV_Semaphore. // = Semaphore acquire and release methods. + /// Acquire the semaphore. int acquire (u_short n = 0, int flags = 0) const; - // Acquire the semaphore. + /// Acquire a semaphore for reading. int acquire_read (u_short n = 0, int flags = 0) const; - // Acquire a semaphore for reading. + /// Acquire a semaphore for writing int acquire_write (u_short n = 0, int flags = 0) const; - // Acquire a semaphore for writing + /// Try to acquire the semaphore. int tryacquire (u_short n = 0, int flags = 0) const; - // Try to acquire the semaphore. + /// Try to acquire the semaphore for reading. int tryacquire_read (u_short n = 0, int flags = 0) const; - // Try to acquire the semaphore for reading. + /// Try to acquire the semaphore for writing. int tryacquire_write (u_short n = 0, int flags = 0) const; - // Try to acquire the semaphore for writing. + /// Release the semaphore. int release (u_short n = 0, int flags = 0) const; - // Release the semaphore. // = Semaphore operation methods. int op (int val, u_short n = 0, int flags = 0) const; @@ -134,11 +133,11 @@ public: ACE_USING ACE_SV_Semaphore_Simple::get_id; ACE_USING ACE_SV_Semaphore_Simple::remove; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: static const int BIGCOUNT_; diff --git a/ace/SV_Semaphore_Simple.h b/ace/SV_Semaphore_Simple.h index 9350fb8cd7b..4c73d703d9f 100644 --- a/ace/SV_Semaphore_Simple.h +++ b/ace/SV_Semaphore_Simple.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SV_Semaphore_Simple.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file SV_Semaphore_Simple.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_SV_SEMAPHORE_SIMPLE_H #define ACE_SV_SEMAPHORE_SIMPLE_H @@ -24,12 +21,15 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_SV_Semaphore_Simple + * + * @brief This is a simple semaphore package that assumes there are + * no race conditions for initialization (i.e., the order of + * process startup must be well defined). + */ class ACE_Export ACE_SV_Semaphore_Simple { - // = TITLE - // This is a simple semaphore package that assumes there are - // no race conditions for initialization (i.e., the order of - // process startup must be well defined). public: enum { @@ -58,91 +58,97 @@ public: u_short nsems = 1, int perms = ACE_DEFAULT_FILE_PERMS); + /// Open or create one or more SV_Semaphores. We return 0 if all is + /// OK, else -1. int open (key_t key, int flags = ACE_SV_Semaphore_Simple::ACE_CREATE, int initial_value = 1, u_short nsems = 1, int perms = ACE_DEFAULT_FILE_PERMS); - // Open or create one or more SV_Semaphores. We return 0 if all is - // OK, else -1. + /// Close a ACE_SV_Semaphore, marking it as invalid for subsequent + /// operations... int close (void); - // Close a ACE_SV_Semaphore, marking it as invalid for subsequent - // operations... + /** + * Remove all SV_Semaphores associated with a particular key. This + * call is intended to be called from a server, for example, when it + * is being shut down, as we do an IPC_RMID on the ACE_SV_Semaphore, + * regardless of whether other processes may be using it or not. + * Most other processes should use <close> below. + */ int remove (void) const; - // Remove all SV_Semaphores associated with a particular key. This - // call is intended to be called from a server, for example, when it - // is being shut down, as we do an IPC_RMID on the ACE_SV_Semaphore, - // regardless of whether other processes may be using it or not. - // Most other processes should use <close> below. // = Semaphore acquire and release methods. + /** + * Wait until a ACE_SV_Semaphore's value is greater than 0, the + * decrement it by 1 and return. Dijkstra's P operation, Tannenbaums + * DOWN operation. + */ int acquire (u_short n = 0, int flags = 0) const; - // Wait until a ACE_SV_Semaphore's value is greater than 0, the - // decrement it by 1 and return. Dijkstra's P operation, Tannenbaums - // DOWN operation. + /// Acquire a semaphore for reading. int acquire_read (u_short n = 0, int flags = 0) const; - // Acquire a semaphore for reading. + /// Acquire a semaphore for writing int acquire_write (u_short n = 0, int flags = 0) const; - // Acquire a semaphore for writing + /// Non-blocking version of <acquire>. int tryacquire (u_short n = 0, int flags = 0) const; - // Non-blocking version of <acquire>. + /// Try to acquire the semaphore for reading. int tryacquire_read (u_short n = 0, int flags = 0) const; - // Try to acquire the semaphore for reading. + /// Try to acquire the semaphore for writing. int tryacquire_write (u_short n = 0, int flags = 0) const; - // Try to acquire the semaphore for writing. + /// Increment ACE_SV_Semaphore by one. Dijkstra's V operation, + /// Tannenbaums UP operation. int release (u_short n = 0, int flags = 0) const; - // Increment ACE_SV_Semaphore by one. Dijkstra's V operation, - // Tannenbaums UP operation. // = Semaphore operation methods. + /// General ACE_SV_Semaphore operation. Increment or decrement by a + /// specific amount (positive or negative; amount can`t be zero). int op (int val, u_short semnum = 0, int flags = SEM_UNDO) const; - // General ACE_SV_Semaphore operation. Increment or decrement by a - // specific amount (positive or negative; amount can`t be zero). + /// General ACE_SV_Semaphore operation on an array of SV_Semaphores. int op (sembuf op_vec[], u_short nsems) const; - // General ACE_SV_Semaphore operation on an array of SV_Semaphores. // = Semaphore control methods. int control (int cmd, semun arg, u_short n = 0) const; int control (int cmd, int value = 0, u_short n = 0) const; + /// Get underlying internal id. int get_id (void) const; - // Get underlying internal id. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Semaphore key. key_t key_; - // Semaphore key. + /// Internal ID to identify the semaphore group within this process. int internal_id_; - // Internal ID to identify the semaphore group within this process. + /// Number of semaphores we're creating. int sem_number_; - // Number of semaphores we're creating. + /** + * Convert name to key This function is used internally to create + * keys for the semaphores. A valid name contains letters and + * digits only and MUST start with a letter. + * + * The method for generating names is not very sophisticated, so + * caller should not pass strings which match each other for the first + * LUSED characters when he wants to get a different key. + */ int init (key_t k = ACE_static_cast (key_t, ACE_INVALID_SEM_KEY), int i = -1); key_t name_2_key (const char *name); - // Convert name to key This function is used internally to create - // keys for the semaphores. A valid name contains letters and - // digits only and MUST start with a letter. - // - // The method for generating names is not very sophisticated, so - // caller should not pass strings which match each other for the first - // LUSED characters when he wants to get a different key. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/SV_Shared_Memory.h b/ace/SV_Shared_Memory.h index 73b33d75c0b..cc1fa50d90f 100644 --- a/ace/SV_Shared_Memory.h +++ b/ace/SV_Shared_Memory.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// SV_Shared_Memory.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + + +//============================================================================= +/** + * @file SV_Shared_Memory.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SV_SHARED_MEMORY_H #define ACE_SV_SHARED_MEMORY_H @@ -25,10 +22,13 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_SV_Shared_Memory + * + * @brief This is a wrapper for System V shared memory. + */ class ACE_Export ACE_SV_Shared_Memory { - // = TITLE - // This is a wrapper for System V shared memory. public: enum { @@ -60,49 +60,50 @@ public: void *virtual_addr = 0, int flags = 0); + /// Attach this shared memory segment. int attach (void *virtual_addr = 0, int flags =0); - // Attach this shared memory segment. + /// Detach this shared memory segment. int detach (void); - // Detach this shared memory segment. + /// Remove this shared memory segment. int remove (void); - // Remove this shared memory segment. + /// Forward to underlying System V <shmctl>. int control (int cmd, void *buf); - // Forward to underlying System V <shmctl>. // = Segment-related info. void *get_segment_ptr (void) const; int get_segment_size (void) const; + /// Return the ID of the shared memory segment (i.e., an ACE_HANDLE). ACE_HANDLE get_id (void) const; - // Return the ID of the shared memory segment (i.e., an ACE_HANDLE). + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: enum { - ALIGN_WORDB = 8 // Most restrictive alignment. + /// Most restrictive alignment. + ALIGN_WORDB = 8 }; + /// Internal identifier. ACE_HANDLE internal_id_; - // Internal identifier. + /// Size of the mapped segment. int size_; - // Size of the mapped segment. + /// Pointer to the beginning of the segment. void *segment_ptr_; - // Pointer to the beginning of the segment. + /// Round up to an appropriate page size. int round_up (size_t len); - // Round up to an appropriate page size. }; #if defined (__ACE_INLINE__) diff --git a/ace/Sample_History.h b/ace/Sample_History.h index 90e4ffac0b8..2b171145269 100644 --- a/ace/Sample_History.h +++ b/ace/Sample_History.h @@ -1,17 +1,14 @@ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Sample_History.h -// -// = AUTHOR -// Carlos O'Ryan <coryan@uci.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Sample_History.h + * + * $Id$ + * + * @author Carlos O'Ryan <coryan@uci.edu> + */ +//============================================================================= + #ifndef ACE_SAMPLE_HISTORY_H #define ACE_SAMPLE_HISTORY_H @@ -53,7 +50,7 @@ public: /// Dump all the samples /** * Prints out all the samples, using @param msg as a prefix for each - * message. + * message. */ void dump_samples (const ACE_TCHAR *msg, ACE_UINT32 scale_factor) const; diff --git a/ace/Sched_Params.h b/ace/Sched_Params.h index 19b3e840e90..55380fd5705 100644 --- a/ace/Sched_Params.h +++ b/ace/Sched_Params.h @@ -1,21 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Sched_Params.h -// -// = CREATION DATE -// 28 January 1997 -// -// = AUTHOR -// David Levine <levine@cs.wustl.edu> and Carlos O'Ryan <coryan@uci.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Sched_Params.h + * + * $Id$ + * + * @author David Levine <levine@cs.wustl.edu> + * @author Carlos O'Ryan <coryan@uci.edu> + */ +//============================================================================= + #ifndef ACE_SCHED_PARAMS_H #define ACE_SCHED_PARAMS_H @@ -27,39 +22,39 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Sched_Params + * + * @brief Container for scheduling-related parameters. + * + * ACE_Sched_Params are passed via <ACE_OS::sched_params> to the + * OS to specify scheduling parameters. These parameters include + * scheduling policy, such as FIFO (ACE_SCHED_FIFO), round-robin + * (ACE_SCHED_RR), or an implementation-defined "OTHER" + * (ACE_SCHED_OTHER), to which many systems default; priority; + * and a time-slice quantum for round-robin scheduling. A + * "scope" parameter specifies whether the ACE_Sched_Params + * applies to the current process, current lightweight process + * (LWP) (on Solaris), or current thread. Please see the "NOTE" + * below about not all combinations of parameters being legal on + * a particular platform. + * For the case of thread priorities, it is intended that + * <ACE_OS::sched_params> usually be called from <main> before + * any threads have been spawned. If spawned threads inherit + * their parent's priority (I think that's the default behavior + * for all of our platforms), then this sets the default base + * priority. Individual thread priorities can be adjusted as + * usual using <ACE_OS::thr_prio> or via the ACE_Thread + * interface. See the parameter descriptions in the private: + * section below. + * NOTE: this class does not do any checking of parameters. It + * is just a container class. If it is constructed with values + * that are not supported on a platform, the call to + * <ACE_OS::sched_params> will fail by returning -1 with EINVAL + * (available through <ACE_OS::last_error>). + */ class ACE_Export ACE_Sched_Params { - // = TITLE - // Container for scheduling-related parameters. - // - // = DESCRIPTION - // ACE_Sched_Params are passed via <ACE_OS::sched_params> to the - // OS to specify scheduling parameters. These parameters include - // scheduling policy, such as FIFO (ACE_SCHED_FIFO), round-robin - // (ACE_SCHED_RR), or an implementation-defined "OTHER" - // (ACE_SCHED_OTHER), to which many systems default; priority; - // and a time-slice quantum for round-robin scheduling. A - // "scope" parameter specifies whether the ACE_Sched_Params - // applies to the current process, current lightweight process - // (LWP) (on Solaris), or current thread. Please see the "NOTE" - // below about not all combinations of parameters being legal on - // a particular platform. - // - // For the case of thread priorities, it is intended that - // <ACE_OS::sched_params> usually be called from <main> before - // any threads have been spawned. If spawned threads inherit - // their parent's priority (I think that's the default behavior - // for all of our platforms), then this sets the default base - // priority. Individual thread priorities can be adjusted as - // usual using <ACE_OS::thr_prio> or via the ACE_Thread - // interface. See the parameter descriptions in the private: - // section below. - // - // NOTE: this class does not do any checking of parameters. It - // is just a container class. If it is constructed with values - // that are not supported on a platform, the call to - // <ACE_OS::sched_params> will fail by returning -1 with EINVAL - // (available through <ACE_OS::last_error>). // NOTE: Solaris 2.5.x threads in the RT class must set the // priority of their LWP. The only way to do that through ACE is @@ -76,14 +71,14 @@ public: typedef int Policy; // = Initialization and termination methods. + /// Constructor. ACE_Sched_Params (const Policy policy, const ACE_Sched_Priority priority, const int scope = ACE_SCOPE_THREAD, const ACE_Time_Value &quantum = ACE_Time_Value::zero); - // Constructor. + /// Termination. ~ACE_Sched_Params (void); - // Termination. // = Get/Set methods: @@ -111,105 +106,117 @@ public: static int priority_max (const Policy, const int scope = ACE_SCOPE_THREAD); + /** + * The next higher priority. "Higher" refers to scheduling priority, + * not to the priority value itself. (On some platforms, higher scheduling + * priority is indicated by a lower priority value.) If "priority" is + * already the highest priority (for the specified policy), then it is + * returned. + */ static int next_priority (const Policy, const int priority, const int scope = ACE_SCOPE_THREAD); - // The next higher priority. "Higher" refers to scheduling priority, - // not to the priority value itself. (On some platforms, higher scheduling - // priority is indicated by a lower priority value.) If "priority" is - // already the highest priority (for the specified policy), then it is - // returned. + /** + * The previous, lower priority. "Lower" refers to scheduling priority, + * not to the priority value itself. (On some platforms, lower scheduling + * priority is indicated by a higher priority value.) If "priority" is + * already the lowest priority (for the specified policy), then it is + * returned. + */ static int previous_priority (const Policy, const int priority, const int scope = ACE_SCOPE_THREAD); - // The previous, lower priority. "Lower" refers to scheduling priority, - // not to the priority value itself. (On some platforms, lower scheduling - // priority is indicated by a higher priority value.) If "priority" is - // already the lowest priority (for the specified policy), then it is - // returned. private: + /// Scheduling policy. Policy policy_; - // Scheduling policy. + /// Default <priority_>: for setting the priority for the process, LWP, + /// or thread, as indicated by the scope_ parameter. ACE_Sched_Priority priority_; - // Default <priority_>: for setting the priority for the process, LWP, - // or thread, as indicated by the scope_ parameter. + /** + * <scope_> must be one of the following: + * ACE_SCOPE_PROCESS: sets the scheduling policy for the + * process, and the process priority. On some platforms, + * such as Win32, the scheduling policy can _only_ be + * set at process scope. + * ACE_SCOPE_LWP: lightweight process scope, only used with + * Solaris threads. + * ACE_SCOPE_THREAD: sets the scheduling policy for the thread, + * if the OS supports it, such as with Posix threads, and the + * thread priority. + * NOTE: I don't think that these are the same as POSIX + * contention scope. POSIX users who are interested in, + * and understand, contention scope will have to set it + * by using system calls outside of ACE. + */ int scope_; - // <scope_> must be one of the following: - // ACE_SCOPE_PROCESS: sets the scheduling policy for the - // process, and the process priority. On some platforms, - // such as Win32, the scheduling policy can _only_ be - // set at process scope. - // ACE_SCOPE_LWP: lightweight process scope, only used with - // Solaris threads. - // ACE_SCOPE_THREAD: sets the scheduling policy for the thread, - // if the OS supports it, such as with Posix threads, and the - // thread priority. - // NOTE: I don't think that these are the same as POSIX - // contention scope. POSIX users who are interested in, - // and understand, contention scope will have to set it - // by using system calls outside of ACE. + /** + * The <quantum_> is for time slicing. An ACE_Time_Value of 0 has + * special significance: it means time-slicing is disabled; with + * that, a thread that is running on a CPU will continue to run + * until it blocks or is preempted. Currently ignored if the OS + * doesn't directly support time slicing, such as on VxWorks, or + * setting the quantum (can that be done on Win32?). + */ ACE_Time_Value quantum_; - // The <quantum_> is for time slicing. An ACE_Time_Value of 0 has - // special significance: it means time-slicing is disabled; with - // that, a thread that is running on a CPU will continue to run - // until it blocks or is preempted. Currently ignored if the OS - // doesn't directly support time slicing, such as on VxWorks, or - // setting the quantum (can that be done on Win32?). }; +/** + * @class ACE_Sched_Priority_Iterator + * + * @brief An iterator over the OS-defined scheduling priorities. + * + * The order of priorities (numeric value vs. importance) is OS + * dependant, it can be the case that the priorities are not even + * contigous. This class permits iteration over priorities using + * the iterator pattern. + */ class ACE_Export ACE_Sched_Priority_Iterator - // = TITLE - // An iterator over the OS-defined scheduling priorities. - // - // = DESCRIPTION - // The order of priorities (numeric value vs. importance) is OS - // dependant, it can be the case that the priorities are not even - // contigous. This class permits iteration over priorities using - // the iterator pattern. { public: + /// Initialize the iterator, the arguments define the scheduling + /// policy and scope for the priorities (see ACE_Sched_Param). ACE_Sched_Priority_Iterator (const ACE_Sched_Params::Policy &policy, int scope = ACE_SCOPE_THREAD); - // Initialize the iterator, the arguments define the scheduling - // policy and scope for the priorities (see ACE_Sched_Param). + /// Default dtor. ~ACE_Sched_Priority_Iterator (void); - // Default dtor. + /// Check if there are more priorities. int more (void) const; - // Check if there are more priorities. + /// Return the current priority. int priority (void) const; - // Return the current priority. + /// Move to the next priority. + /// The iteration is from lowest to highest importance. void next (void); - // Move to the next priority. - // The iteration is from lowest to highest importance. + /// Accessor for the scheduling policy over which we are iterating. const ACE_Sched_Params::Policy &policy (void) const; - // Accessor for the scheduling policy over which we are iterating. + /// Accessor for the scheduling int scope (void) const; - // Accessor for the scheduling private: + /// The Scheduling policy (FIFO, RR, etc.) and scheduling scope + /// (PROCESS, SYSTEM) we are iterating on. ACE_Sched_Params::Policy policy_; int scope_; - // The Scheduling policy (FIFO, RR, etc.) and scheduling scope - // (PROCESS, SYSTEM) we are iterating on. + /// The current priority. int priority_; - // The current priority. + /** + * This is set to 1 when there are no more priorities. Cannot easily + * compare against the highest priority on platforms were priorities + * are non-contigous or descending. + */ int done_; - // This is set to 1 when there are no more priorities. Cannot easily - // compare against the highest priority on platforms were priorities - // are non-contigous or descending. }; #if defined (__ACE_INLINE__) diff --git a/ace/Select_Reactor.h b/ace/Select_Reactor.h index 8d9e00576ae..6e503bd51bc 100644 --- a/ace/Select_Reactor.h +++ b/ace/Select_Reactor.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Select_Reactor.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ +//============================================================================= +/** + * @file Select_Reactor.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SELECT_REACTOR_H #define ACE_SELECT_REACTOR_H @@ -37,15 +34,18 @@ typedef ACE_Select_Reactor_Token_T<ACE_Noop_Token> ACE_Select_Reactor_Token; typedef ACE_Select_Reactor_T<ACE_Select_Reactor_Token> ACE_Select_Reactor; ACE_TEMPLATE_SPECIALIZATION + +/** + * @class ACE_Guard< ACE_Select_Reactor_Token_T<ACE_Noop_Token> > + * + * @brief Template specialization of <ACE_Guard> for the + * <ACE_Null_Mutex>. + * + * This specialization is useful since it helps to speedup + * performance of the "Null_Mutex" considerably. + */ class ACE_Export ACE_Guard< ACE_Select_Reactor_Token_T<ACE_Noop_Token> > { - // = TITLE - // Template specialization of <ACE_Guard> for the - // <ACE_Null_Mutex>. - // - // = DESCRIPTION - // This specialization is useful since it helps to speedup - // performance of the "Null_Mutex" considerably. public: // = Initialization and termination methods. ACE_Guard (ACE_Select_Reactor_Token_T<ACE_Noop_Token> &) {} diff --git a/ace/Select_Reactor_Base.h b/ace/Select_Reactor_Base.h index 0948ecce90e..008ac26f714 100644 --- a/ace/Select_Reactor_Base.h +++ b/ace/Select_Reactor_Base.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Select_Reactor_Base.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Select_Reactor_Base.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SELECT_REACTOR_BASE_H #define ACE_SELECT_REACTOR_BASE_H @@ -38,215 +35,240 @@ typedef int (ACE_Event_Handler::*ACE_EH_PTMF) (ACE_HANDLE); // Forward declaration. class ACE_Select_Reactor_Impl; +/** + * @class ACE_Select_Reactor_Handle_Set + * + * @brief Track handles we are interested for various events. + */ class ACE_Export ACE_Select_Reactor_Handle_Set { - // = TITLE - // Track handles we are interested for various events. public: + /// Read events (e.g., input pending, accept pending). ACE_Handle_Set rd_mask_; - // Read events (e.g., input pending, accept pending). + /// Write events (e.g., flow control abated, non-blocking connection + /// complete). ACE_Handle_Set wr_mask_; - // Write events (e.g., flow control abated, non-blocking connection - // complete). + /// Exception events (e.g., SIG_URG). ACE_Handle_Set ex_mask_; - // Exception events (e.g., SIG_URG). }; +/** + * @class ACE_Event_Tuple + * + * @brief An ACE_Event_Handler and its associated ACE_HANDLE. + * + * One <ACE_Event_Handler> is registered for one or more + * <ACE_HANDLE>. At various points, this information must be + * stored explicitly. This class provides a lightweight + * mechanism to do so. + */ class ACE_Export ACE_Event_Tuple { - // = TITLE - // An ACE_Event_Handler and its associated ACE_HANDLE. - // - // = DESCRIPTION - // One <ACE_Event_Handler> is registered for one or more - // <ACE_HANDLE>. At various points, this information must be - // stored explicitly. This class provides a lightweight - // mechanism to do so. public: + /// Default constructor. ACE_Event_Tuple (void); - // Default constructor. + /// Constructor. ACE_Event_Tuple (ACE_Event_Handler *eh, ACE_HANDLE h); - // Constructor. + /// Destructor. ~ACE_Event_Tuple (void); - // Destructor. + /// Equality operator. int operator== (const ACE_Event_Tuple &rhs) const; - // Equality operator. + /// Inequality operator. int operator!= (const ACE_Event_Tuple &rhs) const; - // Inequality operator. + /// Handle. ACE_HANDLE handle_; - // Handle. + /// <ACE_Event_Handler> associated with the <ACE_HANDLE>. ACE_Event_Handler *event_handler_; - // <ACE_Event_Handler> associated with the <ACE_HANDLE>. }; +/** + * @class ACE_Select_Reactor_Notify + * + * @brief Unblock the <ACE_Select_Reactor> from its event loop. + * + * This implementation is necessary for cases where the + * <ACE_Select_Reactor> is run in a multi-threaded program. In + * this case, we need to be able to unblock <select> or <poll> + * when updates occur other than in the main + * <ACE_Select_Reactor> thread. To do this, we signal an + * auto-reset event the <ACE_Select_Reactor> is listening on. + * If an <ACE_Event_Handler> and <ACE_Select_Reactor_Mask> is + * passed to <notify>, the appropriate <handle_*> method is + * dispatched in the context of the <ACE_Select_Reactor> thread. + */ class ACE_Export ACE_Select_Reactor_Notify : public ACE_Reactor_Notify { - // = TITLE - // Unblock the <ACE_Select_Reactor> from its event loop. - // - // = DESCRIPTION - // This implementation is necessary for cases where the - // <ACE_Select_Reactor> is run in a multi-threaded program. In - // this case, we need to be able to unblock <select> or <poll> - // when updates occur other than in the main - // <ACE_Select_Reactor> thread. To do this, we signal an - // auto-reset event the <ACE_Select_Reactor> is listening on. - // If an <ACE_Event_Handler> and <ACE_Select_Reactor_Mask> is - // passed to <notify>, the appropriate <handle_*> method is - // dispatched in the context of the <ACE_Select_Reactor> thread. public: + /// Default dtor. ACE_Select_Reactor_Notify (void); ~ACE_Select_Reactor_Notify (void); - // Default dtor. // = Initialization and termination methods. + /// Initialize. virtual int open (ACE_Reactor_Impl *, ACE_Timer_Queue * = 0, int disable_notify_pipe = 0); - // Initialize. + /// Destroy. virtual int close (void); - // Destroy. + /** + * Called by a thread when it wants to unblock the + * <ACE_Select_Reactor>. This wakeups the <ACE_Select_Reactor> if + * currently blocked in <select>/<poll>. Pass over both the + * <Event_Handler> *and* the <mask> to allow the caller to dictate + * which <Event_Handler> method the <ACE_Select_Reactor> will + * invoke. The <ACE_Time_Value> indicates how long to blocking + * trying to notify the <ACE_Select_Reactor>. If <timeout> == 0, + * the caller will block until action is possible, else will wait + * until the relative time specified in *<timeout> elapses). + */ virtual ssize_t notify (ACE_Event_Handler * = 0, ACE_Reactor_Mask = ACE_Event_Handler::EXCEPT_MASK, ACE_Time_Value * = 0); - // Called by a thread when it wants to unblock the - // <ACE_Select_Reactor>. This wakeups the <ACE_Select_Reactor> if - // currently blocked in <select>/<poll>. Pass over both the - // <Event_Handler> *and* the <mask> to allow the caller to dictate - // which <Event_Handler> method the <ACE_Select_Reactor> will - // invoke. The <ACE_Time_Value> indicates how long to blocking - // trying to notify the <ACE_Select_Reactor>. If <timeout> == 0, - // the caller will block until action is possible, else will wait - // until the relative time specified in *<timeout> elapses). + /// Handles pending threads (if any) that are waiting to unblock the + /// <ACE_Select_Reactor>. virtual int dispatch_notifications (int &number_of_active_handles, ACE_Handle_Set &rd_mask); - // Handles pending threads (if any) that are waiting to unblock the - // <ACE_Select_Reactor>. + /// Called back by the <ACE_Select_Reactor> when a thread wants to + /// unblock us. virtual int handle_input (ACE_HANDLE handle); - // Called back by the <ACE_Select_Reactor> when a thread wants to - // unblock us. + /** + * Set the maximum number of times that the + * <ACE_Select_Reactor_Notify::handle_input> method will iterate and + * dispatch the <ACE_Event_Handlers> that are passed in via the + * notify pipe before breaking out of its <recv> loop. By default, + * this is set to -1, which means "iterate until the pipe is empty." + * Setting this to a value like "1 or 2" will increase "fairness" + * (and thus prevent starvation) at the expense of slightly higher + * dispatching overhead. + */ virtual void max_notify_iterations (int); - // Set the maximum number of times that the - // <ACE_Select_Reactor_Notify::handle_input> method will iterate and - // dispatch the <ACE_Event_Handlers> that are passed in via the - // notify pipe before breaking out of its <recv> loop. By default, - // this is set to -1, which means "iterate until the pipe is empty." - // Setting this to a value like "1 or 2" will increase "fairness" - // (and thus prevent starvation) at the expense of slightly higher - // dispatching overhead. + /** + * Get the maximum number of times that the + * <ACE_Select_Reactor_Notify::handle_input> method will iterate and + * dispatch the <ACE_Event_Handlers> that are passed in via the + * notify pipe before breaking out of its <recv> loop. + */ virtual int max_notify_iterations (void); - // Get the maximum number of times that the - // <ACE_Select_Reactor_Notify::handle_input> method will iterate and - // dispatch the <ACE_Event_Handlers> that are passed in via the - // notify pipe before breaking out of its <recv> loop. + /** + * Purge any notifications pending in this reactor for the specified + * <ACE_Event_Handler> object. Returns the number of notifications + * purged. Returns -1 on error. + */ virtual int purge_pending_notifications (ACE_Event_Handler * = 0); - // Purge any notifications pending in this reactor for the specified - // <ACE_Event_Handler> object. Returns the number of notifications - // purged. Returns -1 on error. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /** + * Keep a back pointer to the <ACE_Select_Reactor>. If this value + * if NULL then the <ACE_Select_Reactor> has been initialized with + * <disable_notify_pipe>. + */ ACE_Select_Reactor_Impl *select_reactor_; - // Keep a back pointer to the <ACE_Select_Reactor>. If this value - // if NULL then the <ACE_Select_Reactor> has been initialized with - // <disable_notify_pipe>. + /** + * Contains the <ACE_HANDLE> the <ACE_Select_Reactor> is listening + * on, as well as the <ACE_HANDLE> that threads wanting the + * attention of the <ACE_Select_Reactor> will write to. + */ ACE_Pipe notification_pipe_; - // Contains the <ACE_HANDLE> the <ACE_Select_Reactor> is listening - // on, as well as the <ACE_HANDLE> that threads wanting the - // attention of the <ACE_Select_Reactor> will write to. + /** + * Keeps track of the maximum number of times that the + * <ACE_Select_Reactor_Notify::handle_input> method will iterate and + * dispatch the <ACE_Event_Handlers> that are passed in via the + * notify pipe before breaking out of its <recv> loop. By default, + * this is set to -1, which means "iterate until the pipe is empty." + */ int max_notify_iterations_; - // Keeps track of the maximum number of times that the - // <ACE_Select_Reactor_Notify::handle_input> method will iterate and - // dispatch the <ACE_Event_Handlers> that are passed in via the - // notify pipe before breaking out of its <recv> loop. By default, - // this is set to -1, which means "iterate until the pipe is empty." #if defined (ACE_HAS_REACTOR_NOTIFICATION_QUEUE) + /// Keeps track of allocated arrays of type + /// <ACE_Notification_Buffer>. ACE_Unbounded_Queue <ACE_Notification_Buffer *> alloc_queue_; - // Keeps track of allocated arrays of type - // <ACE_Notification_Buffer>. + /// Keeps track of all pending notifications. ACE_Unbounded_Queue <ACE_Notification_Buffer *> notify_queue_; - // Keeps track of all pending notifications. + /// Keeps track of all free buffers. ACE_Unbounded_Queue <ACE_Notification_Buffer *> free_queue_; - // Keeps track of all free buffers. + /// Synchronization for handling of queues. ACE_SYNCH_MUTEX notify_queue_lock_; - // Synchronization for handling of queues. #endif /* ACE_HAS_REACTOR_NOTIFICATION_QUEUE */ }; +/** + * @class ACE_Select_Reactor_Handler_Repository + * + * @brief Used to map <ACE_HANDLE>s onto the appropriate + * <ACE_Event_Handler> *. + * + * This class is necessary to shield differences between UNIX + * and Win32. In UNIX, <ACE_HANDLE> is an int, whereas in Win32 + * it's a void *. This class hides all these details from the + * bulk of the <ACE_Select_Reactor> code. All of these methods + * are called with the main <Select_Reactor> token lock held. + */ class ACE_Export ACE_Select_Reactor_Handler_Repository { - // = TITLE - // Used to map <ACE_HANDLE>s onto the appropriate - // <ACE_Event_Handler> *. - // - // = DESCRIPTION - // This class is necessary to shield differences between UNIX - // and Win32. In UNIX, <ACE_HANDLE> is an int, whereas in Win32 - // it's a void *. This class hides all these details from the - // bulk of the <ACE_Select_Reactor> code. All of these methods - // are called with the main <Select_Reactor> token lock held. public: friend class ACE_Select_Reactor_Handler_Repository_Iterator; // = Initialization and termination methods. + /// Default "do-nothing" constructor. ACE_Select_Reactor_Handler_Repository (ACE_Select_Reactor_Impl &); - // Default "do-nothing" constructor. + /// dtor. ~ACE_Select_Reactor_Handler_Repository (void); - // dtor. + /// Initialize a repository of the appropriate <size>. int open (size_t size); - // Initialize a repository of the appropriate <size>. + /// Close down the repository. int close (void); - // Close down the repository. // = Search structure operations. + /** + * Return the <ACE_Event_Handler *> associated with <ACE_HANDLE>. + * If <index_p> is non-0, then return the index location of the + * <handle>, if found. + */ ACE_Event_Handler *find (ACE_HANDLE handle, size_t *index_p = 0); - // Return the <ACE_Event_Handler *> associated with <ACE_HANDLE>. - // If <index_p> is non-0, then return the index location of the - // <handle>, if found. + /// Bind the <ACE_Event_Handler *> to the <ACE_HANDLE> with the + /// appropriate <ACE_Reactor_Mask> settings. int bind (ACE_HANDLE, ACE_Event_Handler *, ACE_Reactor_Mask); - // Bind the <ACE_Event_Handler *> to the <ACE_HANDLE> with the - // appropriate <ACE_Reactor_Mask> settings. + /// Remove the binding of <ACE_HANDLE> in accordance with the <mask>. int unbind (ACE_HANDLE, ACE_Reactor_Mask mask); - // Remove the binding of <ACE_HANDLE> in accordance with the <mask>. + /// Remove all the <ACE_HANDLE, ACE_Event_Handler> tuples. int unbind_all (void); - // Remove all the <ACE_HANDLE, ACE_Event_Handler> tuples. // = Sanity checking. @@ -260,190 +282,206 @@ public: int handle_in_range (ACE_HANDLE handle); // = Accessors. + /// Returns the current table size. size_t size (void) const; - // Returns the current table size. + /// Maximum ACE_HANDLE value, plus 1. size_t max_handlep1 (void); - // Maximum ACE_HANDLE value, plus 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Reference to our <Select_Reactor>. ACE_Select_Reactor_Impl &select_reactor_; - // Reference to our <Select_Reactor>. + /// Maximum number of handles. ssize_t max_size_; - // Maximum number of handles. + /// The highest currently active handle, plus 1 (ranges between 0 and + /// <max_size_>. int max_handlep1_; - // The highest currently active handle, plus 1 (ranges between 0 and - // <max_size_>. #if defined (ACE_WIN32) // = The mapping from <HANDLES> to <Event_Handlers>. + /** + * The NT version implements this via a dynamically allocated + * array of <ACE_Event_Tuple *>. Since NT implements ACE_HANDLE + * as a void * we can't directly index into this array. Therefore, + * we just do a linear search (for now). Next, we'll modify + * things to use hashing or something faster... + */ ACE_Event_Tuple *event_handlers_; - // The NT version implements this via a dynamically allocated - // array of <ACE_Event_Tuple *>. Since NT implements ACE_HANDLE - // as a void * we can't directly index into this array. Therefore, - // we just do a linear search (for now). Next, we'll modify - // things to use hashing or something faster... #else + /** + * The UNIX version implements this via a dynamically allocated + * array of <ACE_Event_Handler *> that is indexed directly using + * the ACE_HANDLE value. + */ ACE_Event_Handler **event_handlers_; - // The UNIX version implements this via a dynamically allocated - // array of <ACE_Event_Handler *> that is indexed directly using - // the ACE_HANDLE value. #endif /* ACE_WIN32 */ }; +/** + * @class ACE_Select_Reactor_Handler_Repository_Iterator + * + * @brief Iterate through the <ACE_Select_Reactor_Handler_Repository>. + */ class ACE_Export ACE_Select_Reactor_Handler_Repository_Iterator { - // = TITLE - // Iterate through the <ACE_Select_Reactor_Handler_Repository>. public: // = Initialization method. ACE_Select_Reactor_Handler_Repository_Iterator (const ACE_Select_Reactor_Handler_Repository *s); + /// dtor. ~ACE_Select_Reactor_Handler_Repository_Iterator (void); - // dtor. // = Iteration methods. + /// Pass back the <next_item> that hasn't been seen in the Set. + /// Returns 0 when all items have been seen, else 1. int next (ACE_Event_Handler *&next_item); - // Pass back the <next_item> that hasn't been seen in the Set. - // Returns 0 when all items have been seen, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Reference to the Handler_Repository we are iterating over. const ACE_Select_Reactor_Handler_Repository *rep_; - // Reference to the Handler_Repository we are iterating over. + /// Pointer to the current iteration level. ssize_t current_; - // Pointer to the current iteration level. }; +/** + * @class ACE_Select_Reactor_Impl + * + * @brief This class simply defines how Select_Reactor's basic interface + * functions should look like and provides a common base class for + * <Select_Reactor> using various locking mechanism. + */ class ACE_Export ACE_Select_Reactor_Impl : public ACE_Reactor_Impl { - // = TITLE - // This class simply defines how Select_Reactor's basic interface - // functions should look like and provides a common base class for - // <Select_Reactor> using various locking mechanism. public: enum { + /// Default size of the Select_Reactor's handle table. DEFAULT_SIZE = ACE_DEFAULT_SELECT_REACTOR_SIZE - // Default size of the Select_Reactor's handle table. }; + /// Constructor. ACE_Select_Reactor_Impl (void); - // Constructor. - + friend class ACE_Select_Reactor_Notify; friend class ACE_Select_Reactor_Handler_Repository; + /** + * Purge any notifications pending in this reactor for the specified + * <ACE_Event_Handler> object. Returns the number of notifications + * purged. Returns -1 on error. + */ virtual int purge_pending_notifications (ACE_Event_Handler * = 0); - // Purge any notifications pending in this reactor for the specified - // <ACE_Event_Handler> object. Returns the number of notifications - // purged. Returns -1 on error. protected: + /// Allow manipulation of the <wait_set_> mask and <ready_set_> mask. virtual int bit_ops (ACE_HANDLE handle, ACE_Reactor_Mask mask, ACE_Select_Reactor_Handle_Set &wait_Set, int ops); - // Allow manipulation of the <wait_set_> mask and <ready_set_> mask. + /// Enqueue ourselves into the list of waiting threads at the + /// appropriate point specified by <requeue_position_>. virtual void renew (void) = 0; - // Enqueue ourselves into the list of waiting threads at the - // appropriate point specified by <requeue_position_>. + /// Table that maps <ACE_HANDLEs> to <ACE_Event_Handler *>'s. ACE_Select_Reactor_Handler_Repository handler_rep_; - // Table that maps <ACE_HANDLEs> to <ACE_Event_Handler *>'s. + /// Tracks handles that are waited for by <select>. ACE_Select_Reactor_Handle_Set wait_set_; - // Tracks handles that are waited for by <select>. + /// Tracks handles that are currently suspended. ACE_Select_Reactor_Handle_Set suspend_set_; - // Tracks handles that are currently suspended. + /// Track HANDLES we are interested in for various events that must + /// be dispatched *without* going through <select>. ACE_Select_Reactor_Handle_Set ready_set_; - // Track HANDLES we are interested in for various events that must - // be dispatched *without* going through <select>. + /// Defined as a pointer to allow overriding by derived classes... ACE_Timer_Queue *timer_queue_; - // Defined as a pointer to allow overriding by derived classes... + /// Keeps track of whether we should delete the timer queue (if we + /// didn't create it, then we don't delete it). int delete_timer_queue_; - // Keeps track of whether we should delete the timer queue (if we - // didn't create it, then we don't delete it). + /// Handle signals without requiring global/static variables. ACE_Sig_Handler *signal_handler_; - // Handle signals without requiring global/static variables. + /// Keeps track of whether we should delete the signal handler (if we + /// didn't create it, then we don't delete it). int delete_signal_handler_; - // Keeps track of whether we should delete the signal handler (if we - // didn't create it, then we don't delete it). + /// Callback object that unblocks the <ACE_Select_Reactor> if it's + /// sleeping. ACE_Reactor_Notify *notify_handler_; - // Callback object that unblocks the <ACE_Select_Reactor> if it's - // sleeping. + /// Keeps track of whether we need to delete the notify handler (if + /// we didn't create it, then we don't delete it). int delete_notify_handler_; - // Keeps track of whether we need to delete the notify handler (if - // we didn't create it, then we don't delete it). + /// Restart the <handle_events> event-loop method automatically when + /// <select> is interrupted via <EINTR>. int restart_; - // Restart the <handle_events> event-loop method automatically when - // <select> is interrupted via <EINTR>. + /** + * Position that the main ACE_Select_Reactor thread is requeued in + * the list of waiters during a <notify> callback. If this value == + * -1 we are requeued at the end of the list. Else if it's 0 then + * we are requeued at the front of the list. Else if it's > 1 then + * that indicates the number of waiters to skip over. + */ int requeue_position_; - // Position that the main ACE_Select_Reactor thread is requeued in - // the list of waiters during a <notify> callback. If this value == - // -1 we are requeued at the end of the list. Else if it's 0 then - // we are requeued at the front of the list. Else if it's > 1 then - // that indicates the number of waiters to skip over. + /// True if we've been initialized yet... int initialized_; - // True if we've been initialized yet... + /// The original thread that created this Select_Reactor. ACE_thread_t owner_; - // The original thread that created this Select_Reactor. + /** + * True if state has changed during dispatching of + * <ACE_Event_Handlers>, else false. This is used to determine + * whether we need to make another trip through the + * <Select_Reactor>'s <wait_for_multiple_events> loop. + */ int state_changed_; - // True if state has changed during dispatching of - // <ACE_Event_Handlers>, else false. This is used to determine - // whether we need to make another trip through the - // <Select_Reactor>'s <wait_for_multiple_events> loop. + /// Controls/access whether the notify handler should renew the + /// Select_Reactor's token or not. int supress_notify_renew (void); void supress_notify_renew (int sr); - // Controls/access whether the notify handler should renew the - // Select_Reactor's token or not. private: + /// Determine whether we should renew Select_Reactor's token after handling + /// the notification message. int supress_renew_; - // Determine whether we should renew Select_Reactor's token after handling - // the notification message. + /// Deny access since member-wise won't work... ACE_Select_Reactor_Impl (const ACE_Select_Reactor_Impl &); ACE_Select_Reactor_Impl &operator = (const ACE_Select_Reactor_Impl &); - // Deny access since member-wise won't work... }; #if defined (__ACE_INLINE__) diff --git a/ace/Select_Reactor_T.h b/ace/Select_Reactor_T.h index acb3457b224..2a3736e258d 100644 --- a/ace/Select_Reactor_T.h +++ b/ace/Select_Reactor_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Select_Reactor_T.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Select_Reactor_T.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SELECT_REACTOR_T_H #define ACE_SELECT_REACTOR_T_H @@ -24,103 +21,105 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Select_Reactor_Token_T + * + * @brief Used as a synchronization mechanism to coordinate concurrent + * access to a Select_Reactor object. + * + * This class is used to make the <ACE_Select_Reactor> + * thread-safe. By default, the thread that runs the + * <handle_events> loop holds the token, even when it is blocked + * in the <select> call. Whenever another thread wants to + * access the <ACE_Reactor> via its <register_handler>, + * <remove_handler>, etc. methods) it must ask the token owner + * for temporary release of the token. To accomplish this, the + * owner of a token must define a <sleep_hook> through which it + * can be notified to temporarily release the token if the + * current situation permits this. + * The owner of the token is responsible for deciding which + * request for the token can be granted. By using the + * <ACE_Token::renew> API, the thread that releases the token + * temporarily can specify to get the token back right after the + * other thread has completed using the token. Thus, there is a + * dedicated thread that owns the token ``by default.'' This + * thread grants other threads access to the token by ensuring + * that whenever somebody else has finished using the token the + * ``default owner'' first holds the token again, i.e., the + * owner has the chance to schedule other threads. + * The thread that most likely needs the token most of the time + * is the thread running the dispatch loop. Typically the token + * gets released prior to entering the <select> call and gets + * ``re-acquired'' as soon as the <select> call returns, which + * results probably in many calls to <release>/<acquire> that + * are not really needed since no other thread would need the + * token in the meantime. That's why the dispatcher thread is + * chosen to be the owner of the token. + * In case the token would have been released while in <select> + * there would be a good chance that the <fd_set> could have + * been modified while the <select> returns from blocking and + * trying to re-acquire the lock. Through the token mechanism + * it is ensured that while another thread is holding the token, + * the dispatcher thread is blocked in the <renew> call and not + * in <select>. Thus, it is not critical to change the + * <fd_set>. The implementation of the <sleep_hook> mechanism + * provided by the <ACE_Select_Reactor_Token> enables the + * default owner to be the thread that executes the dispatch + * loop. + */ template <class ACE_SELECT_REACTOR_MUTEX> class ACE_Select_Reactor_Token_T : public ACE_SELECT_REACTOR_MUTEX { - // = TITLE - // Used as a synchronization mechanism to coordinate concurrent - // access to a Select_Reactor object. - // - // = DESCRIPTION - // This class is used to make the <ACE_Select_Reactor> - // thread-safe. By default, the thread that runs the - // <handle_events> loop holds the token, even when it is blocked - // in the <select> call. Whenever another thread wants to - // access the <ACE_Reactor> via its <register_handler>, - // <remove_handler>, etc. methods) it must ask the token owner - // for temporary release of the token. To accomplish this, the - // owner of a token must define a <sleep_hook> through which it - // can be notified to temporarily release the token if the - // current situation permits this. - // - // The owner of the token is responsible for deciding which - // request for the token can be granted. By using the - // <ACE_Token::renew> API, the thread that releases the token - // temporarily can specify to get the token back right after the - // other thread has completed using the token. Thus, there is a - // dedicated thread that owns the token ``by default.'' This - // thread grants other threads access to the token by ensuring - // that whenever somebody else has finished using the token the - // ``default owner'' first holds the token again, i.e., the - // owner has the chance to schedule other threads. - // - // The thread that most likely needs the token most of the time - // is the thread running the dispatch loop. Typically the token - // gets released prior to entering the <select> call and gets - // ``re-acquired'' as soon as the <select> call returns, which - // results probably in many calls to <release>/<acquire> that - // are not really needed since no other thread would need the - // token in the meantime. That's why the dispatcher thread is - // chosen to be the owner of the token. - // - // In case the token would have been released while in <select> - // there would be a good chance that the <fd_set> could have - // been modified while the <select> returns from blocking and - // trying to re-acquire the lock. Through the token mechanism - // it is ensured that while another thread is holding the token, - // the dispatcher thread is blocked in the <renew> call and not - // in <select>. Thus, it is not critical to change the - // <fd_set>. The implementation of the <sleep_hook> mechanism - // provided by the <ACE_Select_Reactor_Token> enables the - // default owner to be the thread that executes the dispatch - // loop. public: ACE_Select_Reactor_Token_T (ACE_Select_Reactor_Impl &r); ACE_Select_Reactor_Token_T (void); virtual ~ACE_Select_Reactor_Token_T (void); + /// Called just before the ACE_Event_Handler goes to sleep. virtual void sleep_hook (void); - // Called just before the ACE_Event_Handler goes to sleep. + /// Set/Get methods ACE_Select_Reactor_Impl &select_reactor (void); void select_reactor (ACE_Select_Reactor_Impl &); - // Set/Get methods + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: ACE_Select_Reactor_Impl *select_reactor_; }; +/** + * @class ACE_Select_Reactor_T + * + * @brief An object oriented event demultiplexor and event handler + * dispatcher. + * + * The <ACE_Select_Reactor> is an object-oriented event + * demultiplexor and event handler dispatcher. The sources of + * events that the <ACE_Select_Reactor> waits for and dispatches + * includes I/O events, signals, and timer events. All public + * methods acquire the main <ACE_Select_Reactor_Token> lock and + * call down to private or protected methods, which assume that + * the lock is held and so therefore don't (re)acquire the lock. + */ template <class ACE_SELECT_REACTOR_TOKEN> class ACE_Select_Reactor_T : public ACE_Select_Reactor_Impl { - // = TITLE - // An object oriented event demultiplexor and event handler - // dispatcher. - // - // = DESCRIPTION - // The <ACE_Select_Reactor> is an object-oriented event - // demultiplexor and event handler dispatcher. The sources of - // events that the <ACE_Select_Reactor> waits for and dispatches - // includes I/O events, signals, and timer events. All public - // methods acquire the main <ACE_Select_Reactor_Token> lock and - // call down to private or protected methods, which assume that - // the lock is held and so therefore don't (re)acquire the lock. public: // = Initialization and termination methods. + /// Initialize <ACE_Select_Reactor> with the default size. ACE_Select_Reactor_T (ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0, int disable_notify_pipe = 0, ACE_Reactor_Notify *notify = 0, int mask_signals = 1); - // Initialize <ACE_Select_Reactor> with the default size. + /// Initialize <ACE_Select_Reactor> with size <size>. ACE_Select_Reactor_T (size_t size, int restart = 0, ACE_Sig_Handler * = 0, @@ -128,106 +127,121 @@ public: int disable_notify_pipe = 0, ACE_Reactor_Notify *notify = 0, int mask_signals = 1); - // Initialize <ACE_Select_Reactor> with size <size>. + /** + * Initialize the <ACE_Select_Reactor> to manage + * <max_number_of_handles>. If <restart> is non-0 then the + * <ACE_Reactor>'s <handle_events> method will be restarted + * automatically when <EINTR> occurs. If <signal_handler> or + * <timer_queue> are non-0 they are used as the signal handler and + * timer queue, respectively. If <disable_notify_pipe> is non-0 the + * notification pipe is not created, thereby saving two I/O handles. + */ virtual int open (size_t max_number_of_handles = DEFAULT_SIZE, int restart = 0, ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0, int disable_notify_pipe = 0, ACE_Reactor_Notify * = 0); - // Initialize the <ACE_Select_Reactor> to manage - // <max_number_of_handles>. If <restart> is non-0 then the - // <ACE_Reactor>'s <handle_events> method will be restarted - // automatically when <EINTR> occurs. If <signal_handler> or - // <timer_queue> are non-0 they are used as the signal handler and - // timer queue, respectively. If <disable_notify_pipe> is non-0 the - // notification pipe is not created, thereby saving two I/O handles. + /// Returns -1 (not used in this implementation); virtual int current_info (ACE_HANDLE, size_t & /* size */); - // Returns -1 (not used in this implementation); + /// Use a user specified signal handler instead. virtual int set_sig_handler (ACE_Sig_Handler *signal_handler); - // Use a user specified signal handler instead. // = The following method is deprecated. Use <timer_queue> instead. + /// Set a user specified timer queue. virtual int set_timer_queue (ACE_Timer_Queue *tq); - // Set a user specified timer queue. + /// Set a user-specified timer queue. + /// Return the current <ACE_Timer_Queue>. virtual int timer_queue (ACE_Timer_Queue *tq); - // Set a user-specified timer queue. virtual ACE_Timer_Queue *timer_queue (void) const; - // Return the current <ACE_Timer_Queue>. + /// Close down the select_reactor and release all of its resources. virtual int close (void); - // Close down the select_reactor and release all of its resources. + /// Close down the select_reactor and release all of its resources. virtual ~ACE_Select_Reactor_T (void); - // Close down the select_reactor and release all of its resources. // = Event loop drivers. + /** + * Returns non-zero if there are I/O events "ready" for dispatching, + * but does not actually dispatch the event handlers. By default, + * don't block while checking this, i.e., "poll". + */ virtual int work_pending (const ACE_Time_Value &max_wait_time = ACE_Time_Value::zero); - // Returns non-zero if there are I/O events "ready" for dispatching, - // but does not actually dispatch the event handlers. By default, - // don't block while checking this, i.e., "poll". + /** + * This event loop driver that blocks for <max_wait_time> before + * returning. It will return earlier if timer events, I/O events, + * or signal events occur. Note that <max_wait_time> can be 0, in + * which case this method blocks indefinitely until events occur. + * + * <max_wait_time> is decremented to reflect how much time this call + * took. For instance, if a time value of 3 seconds is passed to + * handle_events and an event occurs after 2 seconds, + * <max_wait_time> will equal 1 second. This can be used if an + * application wishes to handle events for some fixed amount of + * time. + * + * Returns the total number of I/O and Timer <ACE_Event_Handler>s + * that were dispatched, 0 if the <max_wait_time> elapsed without + * dispatching any handlers, or -1 if something goes wrong. + * + * Current <alertable_handle_events> is identical to + * <handle_events>. + */ virtual int handle_events (ACE_Time_Value *max_wait_time = 0); virtual int alertable_handle_events (ACE_Time_Value *max_wait_time = 0); - // This event loop driver that blocks for <max_wait_time> before - // returning. It will return earlier if timer events, I/O events, - // or signal events occur. Note that <max_wait_time> can be 0, in - // which case this method blocks indefinitely until events occur. - // - // <max_wait_time> is decremented to reflect how much time this call - // took. For instance, if a time value of 3 seconds is passed to - // handle_events and an event occurs after 2 seconds, - // <max_wait_time> will equal 1 second. This can be used if an - // application wishes to handle events for some fixed amount of - // time. - // - // Returns the total number of I/O and Timer <ACE_Event_Handler>s - // that were dispatched, 0 if the <max_wait_time> elapsed without - // dispatching any handlers, or -1 if something goes wrong. - // - // Current <alertable_handle_events> is identical to - // <handle_events>. + /** + * This method is just like the one above, except the + * <max_wait_time> value is a reference and can therefore never be + * NULL. + * + * Current <alertable_handle_events> is identical to + * <handle_events>. + */ virtual int handle_events (ACE_Time_Value &max_wait_time); virtual int alertable_handle_events (ACE_Time_Value &max_wait_time); - // This method is just like the one above, except the - // <max_wait_time> value is a reference and can therefore never be - // NULL. - // - // Current <alertable_handle_events> is identical to - // <handle_events>. // = Event handling control. + /** + * Return the status of Reactor. If this function returns 0, the reactor is + * actively handling events. If it returns non-zero, <handling_events> and + * <handle_alertable_events> return -1 immediately. + */ virtual int deactivated (void); - // Return the status of Reactor. If this function returns 0, the reactor is - // actively handling events. If it returns non-zero, <handling_events> and - // <handle_alertable_events> return -1 immediately. + /** + * Control whether the Reactor will handle any more incoming events or not. + * If <do_stop> == 1, the Reactor will be disabled. By default, a reactor + * is in active state and can be deactivated/reactived as wish. + */ virtual void deactivate (int do_stop); - // Control whether the Reactor will handle any more incoming events or not. - // If <do_stop> == 1, the Reactor will be disabled. By default, a reactor - // is in active state and can be deactivated/reactived as wish. // = Register and remove <ACE_Event_Handler>s. + /** + * Register a <eh> with a particular <mask>. Note that the + * <Select_Reactor> will call <ACE_Event_Handler::get_handle> to + * extract the underlying I/O handle. + */ virtual int register_handler (ACE_Event_Handler *eh, ACE_Reactor_Mask mask); - // Register a <eh> with a particular <mask>. Note that the - // <Select_Reactor> will call <ACE_Event_Handler::get_handle> to - // extract the underlying I/O handle. + /** + * Register a <eh> with a particular <mask>. Note that since the + * <handle> is given the Select_Reactor will *not* call + * <ACE_Event_Handler::get_handle> to extract the underlying I/O + * handle. + */ virtual int register_handler (ACE_HANDLE handle, ACE_Event_Handler *eh, ACE_Reactor_Mask mask); - // Register a <eh> with a particular <mask>. Note that since the - // <handle> is given the Select_Reactor will *not* call - // <ACE_Event_Handler::get_handle> to extract the underlying I/O - // handle. #if defined (ACE_WIN32) @@ -238,282 +252,314 @@ public: // register_handler(ACE_Event_Handler*,ACE_HANDLE). Therefore, we // have restricted this method to Win32 only. + /// Not implemented. virtual int register_handler (ACE_Event_Handler *event_handler, ACE_HANDLE event_handle = ACE_INVALID_HANDLE); - // Not implemented. #endif /* ACE_WIN32 */ + /// Not implemented. virtual int register_handler (ACE_HANDLE event_handle, ACE_HANDLE io_handle, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // Not implemented. + /// Register <eh> with all the <handles> in the <Handle_Set>. virtual int register_handler (const ACE_Handle_Set &handles, ACE_Event_Handler *eh, ACE_Reactor_Mask mask); - // Register <eh> with all the <handles> in the <Handle_Set>. + /** + * Register <new_sh> to handle the signal <signum> using the + * <new_disp>. Returns the <old_sh> that was previously registered + * (if any), along with the <old_disp> of the signal handler. + */ virtual int register_handler (int signum, ACE_Event_Handler *new_sh, ACE_Sig_Action *new_disp = 0, ACE_Event_Handler **old_sh = 0, ACE_Sig_Action *old_disp = 0); - // Register <new_sh> to handle the signal <signum> using the - // <new_disp>. Returns the <old_sh> that was previously registered - // (if any), along with the <old_disp> of the signal handler. + /// Registers <new_sh> to handle a set of signals <sigset> using the + /// <new_disp>. virtual int register_handler (const ACE_Sig_Set &sigset, ACE_Event_Handler *new_sh, ACE_Sig_Action *new_disp = 0); - // Registers <new_sh> to handle a set of signals <sigset> using the - // <new_disp>. + /** + * Removes the <mask> binding of <eh> from the Select_Reactor. If + * there are no more bindings for this <eh> then it is removed from + * the Select_Reactor. Note that the Select_Reactor will call + * <ACE_Event_Handler::get_handle> to extract the underlying I/O + * handle. + */ virtual int remove_handler (ACE_Event_Handler *eh, ACE_Reactor_Mask mask); - // Removes the <mask> binding of <eh> from the Select_Reactor. If - // there are no more bindings for this <eh> then it is removed from - // the Select_Reactor. Note that the Select_Reactor will call - // <ACE_Event_Handler::get_handle> to extract the underlying I/O - // handle. + /** + * Removes the <mask> bind of <Event_Handler> whose handle is + * <handle> from the Select_Reactor. If there are no more bindings + * for this <eh> then it is removed from the Select_Reactor. + */ virtual int remove_handler (ACE_HANDLE handle, ACE_Reactor_Mask); - // Removes the <mask> bind of <Event_Handler> whose handle is - // <handle> from the Select_Reactor. If there are no more bindings - // for this <eh> then it is removed from the Select_Reactor. + /** + * Removes all the <mask> bindings for handles in the <handle_set> + * bind of <Event_Handler>. If there are no more bindings for any + * of these handlers then they are removed from the Select_Reactor. + */ virtual int remove_handler (const ACE_Handle_Set &handle_set, ACE_Reactor_Mask); - // Removes all the <mask> bindings for handles in the <handle_set> - // bind of <Event_Handler>. If there are no more bindings for any - // of these handlers then they are removed from the Select_Reactor. + /** + * Remove the ACE_Event_Handler currently associated with <signum>. + * <sigkey> is ignored in this implementation since there is only + * one instance of a signal handler. Install the new disposition + * (if given) and return the previous disposition (if desired by the + * caller). Returns 0 on success and -1 if <signum> is invalid. + */ virtual int remove_handler (int signum, ACE_Sig_Action *new_disp, ACE_Sig_Action *old_disp = 0, int sigkey = -1); - // Remove the ACE_Event_Handler currently associated with <signum>. - // <sigkey> is ignored in this implementation since there is only - // one instance of a signal handler. Install the new disposition - // (if given) and return the previous disposition (if desired by the - // caller). Returns 0 on success and -1 if <signum> is invalid. + /// Calls <remove_handler> for every signal in <sigset>. virtual int remove_handler (const ACE_Sig_Set &sigset); - // Calls <remove_handler> for every signal in <sigset>. // = Suspend and resume Handlers. + /// Temporarily suspend the <Event_Handler> associated with <eh>. virtual int suspend_handler (ACE_Event_Handler *eh); - // Temporarily suspend the <Event_Handler> associated with <eh>. + /// Temporarily suspend the <Event_Handler> associated with <handle>. virtual int suspend_handler (ACE_HANDLE handle); - // Temporarily suspend the <Event_Handler> associated with <handle>. + /// Suspend all <handles> in handle set temporarily. virtual int suspend_handler (const ACE_Handle_Set &handles); - // Suspend all <handles> in handle set temporarily. + /// Suspend all the <Event_Handlers> in the Select_Reactor. virtual int suspend_handlers (void); - // Suspend all the <Event_Handlers> in the Select_Reactor. + /// Resume a temporarily suspend <Event_Handler> associated with + /// <eh>. virtual int resume_handler (ACE_Event_Handler *eh); - // Resume a temporarily suspend <Event_Handler> associated with - // <eh>. + /// Resume a temporarily suspended <Event_Handler> associated with + /// <handle>. virtual int resume_handler (ACE_HANDLE handle); - // Resume a temporarily suspended <Event_Handler> associated with - // <handle>. + /// Resume all <handles> in handle set. virtual int resume_handler (const ACE_Handle_Set &handles); - // Resume all <handles> in handle set. + /// Resume all the <Event_Handlers> in the Select_Reactor. virtual int resume_handlers (void); - // Resume all the <Event_Handlers> in the Select_Reactor. + /** + * Return 1 if we any event associations were made by the reactor + * for the handles that it waits on, 0 otherwise. Since the + * Select_Reactor does not do any event associations, this function + * always return 0. + */ virtual int uses_event_associations (void); - // Return 1 if we any event associations were made by the reactor - // for the handles that it waits on, 0 otherwise. Since the - // Select_Reactor does not do any event associations, this function - // always return 0. // = Timer management. + /** + * Schedule an <event_handler> that will expire after <delta> amount + * of time, which is specified as relative time to the current + * <gettimeofday>. If it expires then <arg> is passed in as the + * value to the <event_handler>'s <handle_timeout> callback method. + * If <interval> is != to <ACE_Time_Value::zero> then it is used to + * reschedule the <event_handler> automatically, which is also + * specified using relative time. This method returns a <timer_id> + * that uniquely identifies the <event_handler> in an internal list. + * This <timer_id> can be used to cancel an <event_handler> before + * it expires. The cancellation ensures that <timer_ids> are unique + * up to values of greater than 2 billion timers. As long as timers + * don't stay around longer than this there should be no problems + * with accidentally deleting the wrong timer. Returns -1 on + * failure (which is guaranteed never to be a valid <timer_id>. + */ virtual long schedule_timer (ACE_Event_Handler *, const void *arg, const ACE_Time_Value &delta, const ACE_Time_Value &interval = ACE_Time_Value::zero); - // Schedule an <event_handler> that will expire after <delta> amount - // of time, which is specified as relative time to the current - // <gettimeofday>. If it expires then <arg> is passed in as the - // value to the <event_handler>'s <handle_timeout> callback method. - // If <interval> is != to <ACE_Time_Value::zero> then it is used to - // reschedule the <event_handler> automatically, which is also - // specified using relative time. This method returns a <timer_id> - // that uniquely identifies the <event_handler> in an internal list. - // This <timer_id> can be used to cancel an <event_handler> before - // it expires. The cancellation ensures that <timer_ids> are unique - // up to values of greater than 2 billion timers. As long as timers - // don't stay around longer than this there should be no problems - // with accidentally deleting the wrong timer. Returns -1 on - // failure (which is guaranteed never to be a valid <timer_id>. - - virtual int reset_timer_interval (long timer_id, + + /** + * Resets the interval of the timer represented by <timer_id> to + * <interval>, which is specified in relative time to the current + * <gettimeofday>. If <interval> is equal to + * <ACE_Time_Value::zero>, the timer will become a non-rescheduling + * timer. Returns 0 if successful, -1 if not. + */ + virtual int reset_timer_interval (long timer_id, const ACE_Time_Value &interval); - // Resets the interval of the timer represented by <timer_id> to - // <interval>, which is specified in relative time to the current - // <gettimeofday>. If <interval> is equal to - // <ACE_Time_Value::zero>, the timer will become a non-rescheduling - // timer. Returns 0 if successful, -1 if not. + /** + * Cancel all <event_handlers> that match the address of + * <event_handler>. If <dont_call_handle_close> is 0 then the + * <handle_close> method of <event_handler> will be invoked. + * Returns number of handler's cancelled. + */ virtual int cancel_timer (ACE_Event_Handler *event_handler, int dont_call_handle_close = 1); - // Cancel all <event_handlers> that match the address of - // <event_handler>. If <dont_call_handle_close> is 0 then the - // <handle_close> method of <event_handler> will be invoked. - // Returns number of handler's cancelled. + /** + * Cancel the single <ACE_Event_Handler> that matches the <timer_id> + * value (which was returned from the <schedule> method). If arg is + * non-NULL then it will be set to point to the ``magic cookie'' + * argument passed in when the <Event_Handler> was registered. This + * makes it possible to free up the memory and avoid memory leaks. + * If <dont_call_handle_close> is 0 then the <handle_close> method + * of <event_handler> will be invoked. Returns 1 if cancellation + * succeeded and 0 if the <timer_id> wasn't found. + */ virtual int cancel_timer (long timer_id, const void **arg = 0, int dont_call_handle_close = 1); - // Cancel the single <ACE_Event_Handler> that matches the <timer_id> - // value (which was returned from the <schedule> method). If arg is - // non-NULL then it will be set to point to the ``magic cookie'' - // argument passed in when the <Event_Handler> was registered. This - // makes it possible to free up the memory and avoid memory leaks. - // If <dont_call_handle_close> is 0 then the <handle_close> method - // of <event_handler> will be invoked. Returns 1 if cancellation - // succeeded and 0 if the <timer_id> wasn't found. // = High-level Event_Handler scheduling operations + /// ADD the dispatch MASK "bit" bound with the <eh> and the <mask>. virtual int schedule_wakeup (ACE_Event_Handler *eh, ACE_Reactor_Mask mask); - // ADD the dispatch MASK "bit" bound with the <eh> and the <mask>. + /// ADD the dispatch MASK "bit" bound with the <handle> and the <mask>. virtual int schedule_wakeup (ACE_HANDLE handle, ACE_Reactor_Mask mask); - // ADD the dispatch MASK "bit" bound with the <handle> and the <mask>. + /// CLR the dispatch MASK "bit" bound with the <eh> and the <mask>. virtual int cancel_wakeup (ACE_Event_Handler *eh, ACE_Reactor_Mask mask); - // CLR the dispatch MASK "bit" bound with the <eh> and the <mask>. + /// CLR the dispatch MASK "bit" bound with the <handle> and the <mask>. virtual int cancel_wakeup (ACE_HANDLE handle, ACE_Reactor_Mask mask); - // CLR the dispatch MASK "bit" bound with the <handle> and the <mask>. // = Notification methods. + /** + * Called by a thread when it wants to unblock the Select_Reactor. + * This wakeups the <ACE_Select_Reactor> if currently blocked in + * <select>/<poll>. Pass over both the <Event_Handler> *and* the + * <mask> to allow the caller to dictate which <Event_Handler> + * method the <Select_Reactor> will invoke. The <ACE_Time_Value> + * indicates how long to blocking trying to notify the + * <Select_Reactor>. If <timeout> == 0, the caller will block until + * action is possible, else will wait until the relative time + * specified in *<timeout> elapses). + */ virtual int notify (ACE_Event_Handler * = 0, ACE_Reactor_Mask = ACE_Event_Handler::EXCEPT_MASK, ACE_Time_Value * = 0); - // Called by a thread when it wants to unblock the Select_Reactor. - // This wakeups the <ACE_Select_Reactor> if currently blocked in - // <select>/<poll>. Pass over both the <Event_Handler> *and* the - // <mask> to allow the caller to dictate which <Event_Handler> - // method the <Select_Reactor> will invoke. The <ACE_Time_Value> - // indicates how long to blocking trying to notify the - // <Select_Reactor>. If <timeout> == 0, the caller will block until - // action is possible, else will wait until the relative time - // specified in *<timeout> elapses). + /** + * Set the maximum number of times that the + * <ACE_Select_Reactor_Notify::handle_input> method will iterate and + * dispatch the <ACE_Event_Handlers> that are passed in via the + * notify pipe before breaking out of its <recv> loop. By default, + * this is set to -1, which means "iterate until the pipe is empty." + * Setting this to a value like "1 or 2" will increase "fairness" + * (and thus prevent starvation) at the expense of slightly higher + * dispatching overhead. + */ virtual void max_notify_iterations (int); - // Set the maximum number of times that the - // <ACE_Select_Reactor_Notify::handle_input> method will iterate and - // dispatch the <ACE_Event_Handlers> that are passed in via the - // notify pipe before breaking out of its <recv> loop. By default, - // this is set to -1, which means "iterate until the pipe is empty." - // Setting this to a value like "1 or 2" will increase "fairness" - // (and thus prevent starvation) at the expense of slightly higher - // dispatching overhead. + /** + * Get the maximum number of times that the + * <ACE_Select_Reactor_Notify::handle_input> method will iterate and + * dispatch the <ACE_Event_Handlers> that are passed in via the + * notify pipe before breaking out of its <recv> loop. + */ virtual int max_notify_iterations (void); - // Get the maximum number of times that the - // <ACE_Select_Reactor_Notify::handle_input> method will iterate and - // dispatch the <ACE_Event_Handlers> that are passed in via the - // notify pipe before breaking out of its <recv> loop. + /// Get the existing restart value. virtual int restart (void); - // Get the existing restart value. - + + /// Set a new value for restart and return the original value. virtual int restart (int r); - // Set a new value for restart and return the original value. + /// Set position that the main ACE_Select_Reactor thread is requeued in the + /// list of waiters during a <notify> callback. virtual void requeue_position (int); - // Set position that the main ACE_Select_Reactor thread is requeued in the - // list of waiters during a <notify> callback. + /// Get position that the main ACE_Select_Reactor thread is requeued in the + /// list of waiters during a <notify> callback. virtual int requeue_position (void); - // Get position that the main ACE_Select_Reactor thread is requeued in the - // list of waiters during a <notify> callback. // = Low-level wait_set mask manipulation methods. + /// GET/SET/ADD/CLR the dispatch mask "bit" bound with the <eh> and + /// <mask>. virtual int mask_ops (ACE_Event_Handler *eh, ACE_Reactor_Mask mask, int ops); - // GET/SET/ADD/CLR the dispatch mask "bit" bound with the <eh> and - // <mask>. + /// GET/SET/ADD/CLR the dispatch MASK "bit" bound with the <handle> + /// and <mask>. virtual int mask_ops (ACE_HANDLE handle, ACE_Reactor_Mask mask, int ops); - // GET/SET/ADD/CLR the dispatch MASK "bit" bound with the <handle> - // and <mask>. // = Low-level ready_set mask manipulation methods. + /// GET/SET/ADD/CLR the ready "bit" bound with the <eh> and <mask>. virtual int ready_ops (ACE_Event_Handler *eh, ACE_Reactor_Mask mask, int ops); - // GET/SET/ADD/CLR the ready "bit" bound with the <eh> and <mask>. + /// GET/SET/ADD/CLR the ready "bit" bound with the <handle> and <mask>. virtual int ready_ops (ACE_HANDLE handle, ACE_Reactor_Mask, int ops); - // GET/SET/ADD/CLR the ready "bit" bound with the <handle> and <mask>. + /// Wake up all threads in waiting in the event loop virtual void wakeup_all_threads (void); - // Wake up all threads in waiting in the event loop // = Only the owner thread that can perform a <handle_events>. + /// Set the new owner of the thread and return the old owner. virtual int owner (ACE_thread_t n_id, ACE_thread_t *o_id = 0); - // Set the new owner of the thread and return the old owner. + /// Return the current owner of the thread. virtual int owner (ACE_thread_t *); - // Return the current owner of the thread. // = Miscellaneous Handler operations. + /** + * Check to see if <handle> is associated with a valid Event_Handler + * bound to <mask>. Return the <eh> associated with this <handler> + * if <eh> != 0. + */ virtual int handler (ACE_HANDLE handle, ACE_Reactor_Mask mask, ACE_Event_Handler **eh = 0); - // Check to see if <handle> is associated with a valid Event_Handler - // bound to <mask>. Return the <eh> associated with this <handler> - // if <eh> != 0. + /** + * Check to see if <signum> is associated with a valid Event_Handler + * bound to a signal. Return the <eh> associated with this + * <handler> if <eh> != 0. + */ virtual int handler (int signum, ACE_Event_Handler ** = 0); - // Check to see if <signum> is associated with a valid Event_Handler - // bound to a signal. Return the <eh> associated with this - // <handler> if <eh> != 0. + /// Returns true if we've been successfully initialized, else false. virtual int initialized (void); - // Returns true if we've been successfully initialized, else false. + /// Returns the current size of the Reactor's internal descriptor + /// table. virtual size_t size (void) const; - // Returns the current size of the Reactor's internal descriptor - // table. + /** + * Returns a reference to the <ACE_Select_Reactor_Token> that is + * used to serialize the internal Select_Reactor's processing logic. + * This can be useful for situations where you need to avoid + * deadlock efficiently when <ACE_Event_Handlers> are used in + * multiple threads. + */ virtual ACE_Lock &lock (void); - // Returns a reference to the <ACE_Select_Reactor_Token> that is - // used to serialize the internal Select_Reactor's processing logic. - // This can be useful for situations where you need to avoid - // deadlock efficiently when <ACE_Event_Handlers> are used in - // multiple threads. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Internal methods that do the actual work. @@ -521,145 +567,159 @@ protected: // All of these methods assume that the <Select_Reactor>'s token // lock is held by the public methods that call down to them. + /// Do the work of actually binding the <handle> and <eh> with the + /// <mask>. virtual int register_handler_i (ACE_HANDLE handle, ACE_Event_Handler *eh, ACE_Reactor_Mask mask); - // Do the work of actually binding the <handle> and <eh> with the - // <mask>. + /// Register a set of <handles>. virtual int register_handler_i (const ACE_Handle_Set &handles, ACE_Event_Handler *handler, ACE_Reactor_Mask mask); - // Register a set of <handles>. + /// Do the work of actually unbinding the <handle> and <eh> with the + /// <mask>. virtual int remove_handler_i (ACE_HANDLE handle, ACE_Reactor_Mask); - // Do the work of actually unbinding the <handle> and <eh> with the - // <mask>. + /// Remove a set of <handles>. virtual int remove_handler_i (const ACE_Handle_Set &handles, ACE_Reactor_Mask); - // Remove a set of <handles>. + /// Suspend the <Event_Handler> associated with <handle> virtual int suspend_i (ACE_HANDLE handle); - // Suspend the <Event_Handler> associated with <handle> + /// Check to see if the <Event_Handler> associated with <handle> is + /// suspended. Returns 0 if not, 1 if so. virtual int is_suspended_i (ACE_HANDLE handle); - // Check to see if the <Event_Handler> associated with <handle> is - // suspended. Returns 0 if not, 1 if so. + /// Resume the <Event_Handler> associated with <handle> virtual int resume_i (ACE_HANDLE handle); - // Resume the <Event_Handler> associated with <handle> + /// Implement the public <handler> method. virtual int handler_i (ACE_HANDLE handle, ACE_Reactor_Mask, ACE_Event_Handler ** = 0); - // Implement the public <handler> method. + /// Implement the public <handler> method. virtual int handler_i (int signum, ACE_Event_Handler ** = 0); - // Implement the public <handler> method. + /** + * Check if there are any HANDLEs enabled in the <ready_set_>, and + * if so, update the <handle_set> and return the number ready. If + * there aren't any HANDLEs enabled return 0. + */ virtual int any_ready (ACE_Select_Reactor_Handle_Set &handle_set); - // Check if there are any HANDLEs enabled in the <ready_set_>, and - // if so, update the <handle_set> and return the number ready. If - // there aren't any HANDLEs enabled return 0. + /// Implement the <any_ready> method, assuming that the Sig_Guard is + /// beign held virtual int any_ready_i (ACE_Select_Reactor_Handle_Set &handle_set); - // Implement the <any_ready> method, assuming that the Sig_Guard is - // beign held + /// Take corrective action when errors occur. virtual int handle_error (void); - // Take corrective action when errors occur. + /// Make sure the handles are all valid. virtual int check_handles (void); - // Make sure the handles are all valid. + /// Wait for events to occur. virtual int wait_for_multiple_events (ACE_Select_Reactor_Handle_Set &, ACE_Time_Value *); - // Wait for events to occur. // = Dispatching methods. + /** + * Template Method that dispatches <ACE_Event_Handler>s for time + * events, I/O events, and signal events. Returns the total number + * of <ACE_Event_Handler>s that were dispatched or -1 if something + * goes wrong. + */ virtual int dispatch (int nfound, ACE_Select_Reactor_Handle_Set &); - // Template Method that dispatches <ACE_Event_Handler>s for time - // events, I/O events, and signal events. Returns the total number - // of <ACE_Event_Handler>s that were dispatched or -1 if something - // goes wrong. + /** + * Dispatch all timer handlers that have expired. Returns -1 if the + * state of the <wait_set_> has changed, else 0. + * <number_dispatched> is set to the number of timer handlers + * dispatched. + */ virtual int dispatch_timer_handlers (int &number_dispatched); - // Dispatch all timer handlers that have expired. Returns -1 if the - // state of the <wait_set_> has changed, else 0. - // <number_dispatched> is set to the number of timer handlers - // dispatched. + /** + * Dispatch any notification handlers. Returns -1 if the state of + * the <wait_set_> has changed, else returns number of handlers + * notified. + */ virtual int dispatch_notification_handlers (ACE_Select_Reactor_Handle_Set &dispatch_set, int &number_of_active_handles, int &number_of_handlers_dispatched); - // Dispatch any notification handlers. Returns -1 if the state of - // the <wait_set_> has changed, else returns number of handlers - // notified. + /** + * Dispatch all the input/output/except handlers that are enabled in + * the <dispatch_set>. Updates <number_of_active_handles> and + * <number_of_handlers_dispatched> according to the behavior of the + * number Returns -1 if the state of the <wait_set_> has changed, + * else 0. + */ virtual int dispatch_io_handlers (ACE_Select_Reactor_Handle_Set &dispatch_set, int &number_of_active_handles, int &number_of_handlers_dispatched); - // Dispatch all the input/output/except handlers that are enabled in - // the <dispatch_set>. Updates <number_of_active_handles> and - // <number_of_handlers_dispatched> according to the behavior of the - // number Returns -1 if the state of the <wait_set_> has changed, - // else 0. + /** + * Factors the dispatching of an io handle set (each WRITE, EXCEPT + * or READ set of handles). It updates the + * <number_of_handlers_dispatched> and invokes this->notify_handle + * for all the handles in <dispatch_set> using the <mask>, + * <ready_set> and <callback> parameters. Must return -1 if + * this->state_changed otherwise it must return 0. + */ virtual int dispatch_io_set (int number_of_active_handles, int &number_of_handlers_dispatched, int mask, ACE_Handle_Set& dispatch_mask, ACE_Handle_Set& ready_mask, ACE_EH_PTMF callback); - // Factors the dispatching of an io handle set (each WRITE, EXCEPT - // or READ set of handles). It updates the - // <number_of_handlers_dispatched> and invokes this->notify_handle - // for all the handles in <dispatch_set> using the <mask>, - // <ready_set> and <callback> parameters. Must return -1 if - // this->state_changed otherwise it must return 0. + /// Notify the appropriate <callback> in the context of the <eh> + /// associated with <handle> that a particular event has occurred. virtual void notify_handle (ACE_HANDLE handle, ACE_Reactor_Mask mask, ACE_Handle_Set &, ACE_Event_Handler *eh, ACE_EH_PTMF callback); - // Notify the appropriate <callback> in the context of the <eh> - // associated with <handle> that a particular event has occurred. + /// Enqueue ourselves into the list of waiting threads at the + /// appropriate point specified by <requeue_position_>. virtual void renew (void); - // Enqueue ourselves into the list of waiting threads at the - // appropriate point specified by <requeue_position_>. + /// Synchronization token for the MT_SAFE ACE_Select_Reactor. ACE_SELECT_REACTOR_TOKEN token_; - // Synchronization token for the MT_SAFE ACE_Select_Reactor. + /// Adapter used to return internal lock to outside world. ACE_Lock_Adapter<ACE_SELECT_REACTOR_TOKEN> lock_adapter_; - // Adapter used to return internal lock to outside world. + /// Release the token lock when a Win32 structured exception occurs. int release_token (void); - // Release the token lock when a Win32 structured exception occurs. + /// Stops the VC++ compiler from bitching about exceptions and destructors int handle_events_i (ACE_Time_Value *max_wait_time = 0); - // Stops the VC++ compiler from bitching about exceptions and destructors + /// This flag is used to keep track of whether we are actively handling + /// events or not. sig_atomic_t deactivated_; - // This flag is used to keep track of whether we are actively handling - // events or not. + /** + * If 0 then the Reactor will not mask the signals during the event + * dispatching. This is useful for applications that do not + * register any signal handlers and want to reduce the overhead + * introduce by the kernel level locks required to change the mask. + */ int mask_signals_; - // If 0 then the Reactor will not mask the signals during the event - // dispatching. This is useful for applications that do not - // register any signal handlers and want to reduce the overhead - // introduce by the kernel level locks required to change the mask. private: + /// Deny access since member-wise won't work... ACE_UNIMPLEMENTED_FUNC (ACE_Select_Reactor_T (const ACE_Select_Reactor_T<ACE_SELECT_REACTOR_TOKEN> &)) ACE_UNIMPLEMENTED_FUNC (ACE_Select_Reactor_T<ACE_SELECT_REACTOR_TOKEN> &operator= (const ACE_Select_Reactor_T<ACE_SELECT_REACTOR_TOKEN> &) ) - // Deny access since member-wise won't work... }; // @@ The latest version of SunCC can't grok the code if we put inline diff --git a/ace/Service_Config.h b/ace/Service_Config.h index 614d7fec58e..a4cbf4445ed 100644 --- a/ace/Service_Config.h +++ b/ace/Service_Config.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Service_Config.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Service_Config.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SERVICE_CONFIG_H #define ACE_SERVICE_CONFIG_H @@ -40,36 +37,39 @@ extern "C" typedef ACE_Service_Object *(*ACE_SERVICE_ALLOCATOR) (ACE_Service_Object_Exterminator *); } +/** + * @class ACE_Static_Svc_Descriptor + * + * @brief Holds the information necessary to describe a statically linked + * Svc. + */ class ACE_Static_Svc_Descriptor { - // = TITLE - // Holds the information necessary to describe a statically linked - // Svc. public: + /// Name of the service. const ACE_TCHAR *name_; - // Name of the service. + /// Type of service. int type_; - // Type of service. + /// Factory function that allocates the service. ACE_SERVICE_ALLOCATOR alloc_; - // Factory function that allocates the service. + /// Bitmask flags indicating how the framework should delete memory. u_int flags_; - // Bitmask flags indicating how the framework should delete memory. + /// Flag indicating whether the service starts out active. int active_; - // Flag indicating whether the service starts out active. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. public: + /// Compare two service descriptors for equality. int operator== (ACE_Static_Svc_Descriptor &) const; - // Compare two service descriptors for equality. }; // Maintain a set of the statically linked service descriptors. @@ -86,23 +86,24 @@ typedef ACE_Unbounded_Queue_Iterator<ACE_TString> ACE_SVC_QUEUE_ITERATOR; #define ACE_Component_Config ACE_Service_Config +/** + * @class ACE_Service_Config + * + * @brief Supplies common server operations for dynamic and static + * configuration of services. + * + * The <ACE_Service_Config> uses the Monostate pattern. Therefore, + * you can only have one of these instantiated per-process. + * NOTE: the signal_handler_ static member is allocated by the + * <ACE_Object_Manager>. The <ACE_Service_Config> constructor + * uses signal_handler_. Therefore, if the program has any + * static <ACE_Service_Config> objects, there might be + * initialization order problems. They can be minimized, but + * not eliminated, by _not_ #defining + * <ACE_HAS_NONSTATIC_OBJECT_MANAGER>. + */ class ACE_Export ACE_Service_Config { - // = TITLE - // Supplies common server operations for dynamic and static - // configuration of services. - // - // = DESCRIPTION - // The <ACE_Service_Config> uses the Monostate pattern. Therefore, - // you can only have one of these instantiated per-process. - // - // NOTE: the signal_handler_ static member is allocated by the - // <ACE_Object_Manager>. The <ACE_Service_Config> constructor - // uses signal_handler_. Therefore, if the program has any - // static <ACE_Service_Config> objects, there might be - // initialization order problems. They can be minimized, but - // not eliminated, by _not_ #defining - // <ACE_HAS_NONSTATIC_OBJECT_MANAGER>. public: enum { @@ -111,145 +112,165 @@ public: // = Initialization and termination methods. + /// Initialize the Service Repository. ACE_Service_Config (int ignore_static_svcs = 1, size_t size = ACE_Service_Config::MAX_SERVICES, int signum = SIGHUP); - // Initialize the Service Repository. + /** + * Performs an open without parsing command-line arguments. The + * <logger_key> indicates where to write the logging output, which + * is typically either a STREAM pipe or a socket address. + */ ACE_Service_Config (const ACE_TCHAR program_name[], const ACE_TCHAR *logger_key = ACE_DEFAULT_LOGGER_KEY); - // Performs an open without parsing command-line arguments. The - // <logger_key> indicates where to write the logging output, which - // is typically either a STREAM pipe or a socket address. + /** + * Performs an open without parsing command-line arguments. The + * <logger_key> indicates where to write the logging output, which + * is typically either a STREAM pipe or a socket address. If + * <ignore_default_svc_conf_file> is non-0 then the "svc.conf" file + * will be ignored. If <ignore_debug_flag> is non-0 then the + * application is responsible for setting the + * <ACE_Log_Msg::priority_mask> appropriately. Returns number of + * errors that occurred on failure and 0 otherwise. + */ static int open_i (const ACE_TCHAR program_name[], const ACE_TCHAR *logger_key = ACE_DEFAULT_LOGGER_KEY, int ignore_default_svc_conf_file = 0, int ignore_debug_flag = 0); - // Performs an open without parsing command-line arguments. The - // <logger_key> indicates where to write the logging output, which - // is typically either a STREAM pipe or a socket address. If - // <ignore_default_svc_conf_file> is non-0 then the "svc.conf" file - // will be ignored. If <ignore_debug_flag> is non-0 then the - // application is responsible for setting the - // <ACE_Log_Msg::priority_mask> appropriately. Returns number of - // errors that occurred on failure and 0 otherwise. + /** + * Performs an open without parsing command-line arguments. The + * <logger_key> indicates where to write the logging output, which + * is typically either a STREAM pipe or a socket address. If + * <ignore_static_svcs> is 1 then static services are not loaded, + * otherwise, they are loaded. If <ignore_default_svc_conf_file> is + * non-0 then the <svc.conf> configuration file will be ignored. + * Returns zero upon success, -1 if the file is not found or cannot + * be opened (errno is set accordingly), otherwise returns the + * number of errors encountered loading the services in the + * specified svc.conf configuration file. If <ignore_debug_flag> is + * non-0 then the application is responsible for setting the + * <ACE_Log_Msg::priority_mask> appropriately. + */ static int open (const ACE_TCHAR program_name[], const ACE_TCHAR *logger_key = ACE_DEFAULT_LOGGER_KEY, int ignore_static_svcs = 1, int ignore_default_svc_conf_file = 0, int ignore_debug_flag = 0); - // Performs an open without parsing command-line arguments. The - // <logger_key> indicates where to write the logging output, which - // is typically either a STREAM pipe or a socket address. If - // <ignore_static_svcs> is 1 then static services are not loaded, - // otherwise, they are loaded. If <ignore_default_svc_conf_file> is - // non-0 then the <svc.conf> configuration file will be ignored. - // Returns zero upon success, -1 if the file is not found or cannot - // be opened (errno is set accordingly), otherwise returns the - // number of errors encountered loading the services in the - // specified svc.conf configuration file. If <ignore_debug_flag> is - // non-0 then the application is responsible for setting the - // <ACE_Log_Msg::priority_mask> appropriately. + /** + * This is the primary entry point into the ACE_Service_Config (the + * constructor just handles simple initializations). It parses + * arguments passed in from <argc> and <argv> parameters. The + * arguments that are valid in a call to this method include: + * + * - '-b' Option to indicate that we should be a daemon + * - '-d' Turn on debugging mode + * - '-f' Option to read in the list of svc.conf file names + * - '-k' Option to read a wide string where in the logger output can + * be written + * - '-y' Option required to use statically linked services. + * A static service repostory will be constructed if the flag + * is used. Use this flag to override the default + * <ignore_static_svcs> flag at run-time. + * - '-n' Option to avoid using any statically linked services, which + * eliminates the need to construct the static service repository. + * - '-S' Option to read in the list of services on the command-line + * Please observe the difference between options '-f' that looks + * for a list of files and here a list of services. + * + * Returns number of errors that occurred on failure and 0 + * otherwise. + * + * The <logger_key> indicates where to write the logging output, + * which is typically either a STREAM pipe or a socket address. If + * <ignore_static_svcs> is 1 then static services are not loaded, + * otherwise, they are loaded. If <ignore_default_svc_conf_file> is + * non-0 then the <svc.conf> configuration file will be ignored. + * Returns zero upon success, -1 if the file is not found or cannot + * be opened (errno is set accordingly), otherwise returns the + * number of errors encountered loading the services in the + * specified svc.conf configuration file. If <ignore_debug_flag> is + * non-0 then the application is responsible for setting the + * <ACE_Log_Msg::priority_mask> appropriately. + */ static int open (int argc, ACE_TCHAR *argv[], const ACE_TCHAR *logger_key = ACE_DEFAULT_LOGGER_KEY, int ignore_static_svcs = 1, int ignore_default_svc_conf = 0, int ignore_debug_flag = 0); - // This is the primary entry point into the ACE_Service_Config (the - // constructor just handles simple initializations). It parses - // arguments passed in from <argc> and <argv> parameters. The - // arguments that are valid in a call to this method include: - // - // '-b' - Option to indicate that we should be a daemon - // '-d' - Turn on debugging mode - // '-f' - Option to read in the list of svc.conf file names - // '-k' - Option to read a wide string where in the logger output can - // be written - // '-y' - Option required to use statically linked services. - // A static service repostory will be constructed if the flag - // is used. Use this flag to override the default - // <ignore_static_svcs> flag at run-time. - // '-n' - Option to avoid using any statically linked services, which - // eliminates the need to construct the static service repository. - // '-S' - Option to read in the list of services on the command-line - // Please observe the difference between options '-f' that looks - // for a list of files and here a list of services. - // - // Returns number of errors that occurred on failure and 0 - // otherwise. - // - // The <logger_key> indicates where to write the logging output, - // which is typically either a STREAM pipe or a socket address. If - // <ignore_static_svcs> is 1 then static services are not loaded, - // otherwise, they are loaded. If <ignore_default_svc_conf_file> is - // non-0 then the <svc.conf> configuration file will be ignored. - // Returns zero upon success, -1 if the file is not found or cannot - // be opened (errno is set accordingly), otherwise returns the - // number of errors encountered loading the services in the - // specified svc.conf configuration file. If <ignore_debug_flag> is - // non-0 then the application is responsible for setting the - // <ACE_Log_Msg::priority_mask> appropriately. + /// Perform user-specified close activities and remove dynamic + /// memory. virtual ~ACE_Service_Config (void); - // Perform user-specified close activities and remove dynamic - // memory. + /// Tidy up and perform last rites when ACE_Service_Config is shut + /// down. This method calls <close_svcs>. Returns 0. static int close (void); - // Tidy up and perform last rites when ACE_Service_Config is shut - // down. This method calls <close_svcs>. Returns 0. + /// Perform user-specified close hooks and possibly delete all of the + /// configured services in the <Service_Repository>. static int fini_svcs (void); - // Perform user-specified close hooks and possibly delete all of the - // configured services in the <Service_Repository>. + /** + * Perform user-specified close hooks on all of the configured + * services in the <Service_Repository>, then delete the + * <Service_Repository> itself. Returns 0. + */ static int close_svcs (void); - // Perform user-specified close hooks on all of the configured - // services in the <Service_Repository>, then delete the - // <Service_Repository> itself. Returns 0. + /** + * Delete the dynamically allocated Singletons (i.e., the <Reactor>, + * <Proactor>, <ReactorEx>, and <Thread_Manager>. + * Returns 0. + */ static int close_singletons (void); - // Delete the dynamically allocated Singletons (i.e., the <Reactor>, - // <Proactor>, <ReactorEx>, and <Thread_Manager>. - // Returns 0. // = Reactor event loop management methods. + /** + * Run the event loop until the <ACE_Reactor::handle_events> method + * returns -1 or the <end_reactor_event_loop> method is invoked. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * Use <ACE_Reactor::run_event_loop> instead. + */ static int run_reactor_event_loop (void); - // Run the event loop until the <ACE_Reactor::handle_events> method - // returns -1 or the <end_reactor_event_loop> method is invoked. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // Use <ACE_Reactor::run_event_loop> instead. + /** + * Run the event loop until the <ACE_Reactor::handle_events> method + * returns -1, the <end_reactor_event_loop> method is invoked, or the + * <ACE_Time_Value> expires. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * <Use ACE_Reactor::run_event_loop> instead. + */ static int run_reactor_event_loop (ACE_Time_Value &tv); - // Run the event loop until the <ACE_Reactor::handle_events> method - // returns -1, the <end_reactor_event_loop> method is invoked, or the - // <ACE_Time_Value> expires. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // <Use ACE_Reactor::run_event_loop> instead. + /** + * Instruct the <ACE_Service_Config> to terminate its event loop and + * notifies the <ACE_Reactor::instance> so that it can wake up + * and close down gracefully. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * Use <ACE_Reactor::end_event_loop> instead. + */ static int end_reactor_event_loop (void); - // Instruct the <ACE_Service_Config> to terminate its event loop and - // notifies the <ACE_Reactor::instance> so that it can wake up - // and close down gracefully. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // Use <ACE_Reactor::end_event_loop> instead. + /** + * Report if the Reactor's event loop is finished. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * Use <ACE_Reactor::event_loop_done> instead. + */ static int reactor_event_loop_done (void); - // Report if the Reactor's event loop is finished. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // Use <ACE_Reactor::event_loop_done> instead. + /// True if reconfiguration occurred. static int reconfig_occurred (void); - // True if reconfiguration occurred. + /// Indicate that reconfiguration occurred. static void reconfig_occurred (int); - // Indicate that reconfiguration occurred. + /// Perform the reconfiguration process. static void reconfigure (void); - // Perform the reconfiguration process. // = The following methods are static in order to enforce Singleton // semantics for the Reactor, Service_Repository, Thread_Manager, @@ -258,80 +279,98 @@ public: // = Accessors and mutators for process-wide Singletons. + /// Returns a pointer to the list of statically linked services. static ACE_STATIC_SVCS *static_svcs (void); - // Returns a pointer to the list of statically linked services. + /** + * Get pointer to a process-wide <ACE_Reactor>. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * Use <ACE_Reactor::instance> instead. + */ static ACE_Reactor *reactor (void); - // Get pointer to a process-wide <ACE_Reactor>. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // Use <ACE_Reactor::instance> instead. + /** + * Set pointer to a process-wide <ACE_Reactor> and return existing + * pointer. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * Use <ACE_Reactor::instance> instead. + */ static ACE_Reactor *reactor (ACE_Reactor *); - // Set pointer to a process-wide <ACE_Reactor> and return existing - // pointer. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // Use <ACE_Reactor::instance> instead. + /** + * Get pointer to a process-wide <ACE_Service_Repository>. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * Use <ACE_Service_Repository::instance> instead. + */ static ACE_Service_Repository *svc_rep (void); - // Get pointer to a process-wide <ACE_Service_Repository>. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // Use <ACE_Service_Repository::instance> instead. + /** + * Set pointer to a process-wide <ACE_Service_Repository> and return + * existing pointer. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * Use <ACE_Service_Repository::instance> instead. + */ static ACE_Service_Repository *svc_rep (ACE_Service_Repository *); - // Set pointer to a process-wide <ACE_Service_Repository> and return - // existing pointer. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // Use <ACE_Service_Repository::instance> instead. + /** + * Get pointer to a process-wide <ACE_Thread_Manager>. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * Use <ACE_Thread_Manager::instance> instead. + */ static ACE_Thread_Manager *thr_mgr (void); - // Get pointer to a process-wide <ACE_Thread_Manager>. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // Use <ACE_Thread_Manager::instance> instead. #if ! defined (ACE_THREAD_MANAGER_LACKS_STATICS) + /** + * Set pointer to a process-wide <ACE_Thread_Manager> and return + * existing pointer. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * Use ACE_Thread_Manager::instance() instead. + */ static ACE_Thread_Manager *thr_mgr (ACE_Thread_Manager *); - // Set pointer to a process-wide <ACE_Thread_Manager> and return - // existing pointer. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // Use ACE_Thread_Manager::instance() instead. #endif /* ! defined (ACE_THREAD_MANAGER_LACKS_STATICS) */ + /** + * Get pointer to a default <ACE_Allocator>. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * Use <ACE_Allocator::instance> instead. + */ static ACE_Allocator *alloc (void); - // Get pointer to a default <ACE_Allocator>. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // Use <ACE_Allocator::instance> instead. + /** + * Set pointer to a process-wide <ACE_Allocator> and return existing + * pointer. + * DO NOT USE THIS METHOD. It may be unsupported in future releases. + * Use <ACE_Allocator::instance> instead. + */ static ACE_Allocator *alloc (ACE_Allocator *); - // Set pointer to a process-wide <ACE_Allocator> and return existing - // pointer. - // DO NOT USE THIS METHOD. It may be unsupported in future releases. - // Use <ACE_Allocator::instance> instead. // = Utility methods. + /// Dynamically link the shared object file and retrieve a pointer to + /// the designated shared object in this file. static int initialize (const ACE_Service_Type *, ACE_TCHAR parameters[]); - // Dynamically link the shared object file and retrieve a pointer to - // the designated shared object in this file. + /// Initialize and activate a statically <svc_name> service. static int initialize (const ACE_TCHAR svc_name[], ACE_TCHAR parameters[]); - // Initialize and activate a statically <svc_name> service. + /// Resume a <svc_name> that was previously suspended or has not yet + /// been resumed (e.g., a static service). static int resume (const ACE_TCHAR svc_name[]); - // Resume a <svc_name> that was previously suspended or has not yet - // been resumed (e.g., a static service). + /** + * Suspend <svc_name>. Note that this will not unlink the service + * from the daemon if it was dynamically linked, it will mark it as + * being suspended in the Service Repository and call the <suspend> + * member function on the appropriate <ACE_Service_Object>. A + * service can be resumed later on by calling the <RESUME> member + * function... + */ static int suspend (const ACE_TCHAR svc_name[]); - // Suspend <svc_name>. Note that this will not unlink the service - // from the daemon if it was dynamically linked, it will mark it as - // being suspended in the Service Repository and call the <suspend> - // member function on the appropriate <ACE_Service_Object>. A - // service can be resumed later on by calling the <RESUME> member - // function... + /// Totally remove <svc_name> from the daemon by removing it + /// from the ACE_Reactor, and unlinking it if necessary. static int remove (const ACE_TCHAR svc_name[]); - // Totally remove <svc_name> from the daemon by removing it - // from the ACE_Reactor, and unlinking it if necessary. #if defined (ACE_HAS_WINCE) // We must provide these function to bridge the <Svc_Conf> parser @@ -343,100 +382,108 @@ public: static int remove (const char svc_name[]); #endif /* ACE_HAS_WINCE */ + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Set the signal_handler;for internal use by ACE_Object_Manager only. static ACE_INLINE void signal_handler (ACE_Sig_Adapter *); - // Set the signal_handler;for internal use by ACE_Object_Manager only. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /// Process one service configuration <directive>, which is passed as + /// a string. Returns the number of errors that occurred. static int process_directive (const ACE_TCHAR directive[]); - // Process one service configuration <directive>, which is passed as - // a string. Returns the number of errors that occurred. + /** + * Process (or re-process) service configuration requests that are + * provided in the svc.conf file(s). Returns the number of errors + * that occurred. + */ static int process_directives (void); - // Process (or re-process) service configuration requests that are - // provided in the svc.conf file(s). Returns the number of errors - // that occurred. + /// Handles signals to trigger reconfigurations. static void handle_signal (int sig, siginfo_t *, ucontext_t *); - // Handles signals to trigger reconfigurations. + /** + * Handle the command-line options intended for the + * <ACE_Service_Config>. Note that <argv[0]> is assumed to be the + * program name. + * The arguments that are valid in a call to this method are + * - '-b' Option to indicate that we should be a daemon + * - '-d' Turn on debugging mode + * - '-f' Option to read in the list of svc.conf file names + * - '-k' Option to read a wide string where in the logger output can + * be written + * - '-y' Turn on the flag for a repository of statically + * linked services + * - '-n' Need not have a repository of statically linked services + * - '-S' Option to read in the list of services on the command-line + * Please observe the difference between options '-f' that looks + * for a list of files and here a list of services. + */ static int parse_args (int, ACE_TCHAR *argv[]); - // Handle the command-line options intended for the - // <ACE_Service_Config>. Note that <argv[0]> is assumed to be the - // program name. - // The arguments that are valid in a call to this method are - // '-b' - Option to indicate that we should be a daemon - // '-d' - Turn on debugging mode - // '-f' - Option to read in the list of svc.conf file names - // '-k' - Option to read a wide string where in the logger output can - // be written - // '-y' - Turn on the flag for a repository of statically - // linked services - // '-n' - Need not have a repository of statically linked services - // '-S' - Option to read in the list of services on the command-line - // Please observe the difference between options '-f' that looks - // for a list of files and here a list of services. protected: + /// Process service configuration requests that were provided on the + /// command-line. Returns the number of errors that occurred. static int process_commandline_directives (void); - // Process service configuration requests that were provided on the - // command-line. Returns the number of errors that occurred. + /** + * This is the implementation function that <process_directives> and + * <process_directive> both call. Returns the number of errors that + * occurred. + */ static int process_directives_i (void); - // This is the implementation function that <process_directives> and - // <process_directive> both call. Returns the number of errors that - // occurred. + /// Become a daemon. static int start_daemon (void); - // Become a daemon. + /// Add the default statically-linked services to the + /// <ACE_Service_Repository>. static int load_static_svcs (void); - // Add the default statically-linked services to the - // <ACE_Service_Repository>. private: + /// Indicates where to write the logging output. This is typically + /// either a STREAM pipe or a socket address. static const ACE_TCHAR *logger_key_; - // Indicates where to write the logging output. This is typically - // either a STREAM pipe or a socket address. + /// Singleton repository of statically linked services. static ACE_STATIC_SVCS *static_svcs_; - // Singleton repository of statically linked services. + /// Queue of services specified on the command-line. static ACE_SVC_QUEUE *svc_queue_; - // Queue of services specified on the command-line. + /// Queue of svc.conf files specified on the command-line. + /// @@ This should probably be made to handle unicode filenames... static ACE_SVC_QUEUE *svc_conf_file_queue_; - // Queue of svc.conf files specified on the command-line. - // @@ This should probably be made to handle unicode filenames... + /// Initialize the <svc_conf_file_queue_> if necessary. static int init_svc_conf_file_queue (void); - // Initialize the <svc_conf_file_queue_> if necessary. + /// True if reconfiguration occurred. static sig_atomic_t reconfig_occurred_; - // True if reconfiguration occurred. // = Set by command-line options. + /// Shall we become a daemon process? static char be_a_daemon_; - // Shall we become a daemon process? + /// Should we avoid loading the static services? static char no_static_svcs_; - // Should we avoid loading the static services? + /// Number of the signal used to trigger reconfiguration. static int signum_; - // Number of the signal used to trigger reconfiguration. + /// Handles the reconfiguration signals. static ACE_Sig_Adapter *signal_handler_; - // Handles the reconfiguration signals. + /** + * Keep track of whether the <ACE_Service_Config> is already + * initialized. If so, we can't allow <yyparse> to be called since + * it's not reentrant. This variable is incremented by the + * <ACE_Service_Config::open> method and decremented by the + * <ACE_Service_Config::close> method. + */ static int is_initialized_; - // Keep track of whether the <ACE_Service_Config> is already - // initialized. If so, we can't allow <yyparse> to be called since - // it's not reentrant. This variable is incremented by the - // <ACE_Service_Config::open> method and decremented by the - // <ACE_Service_Config::close> method. }; #if defined (__ACE_INLINE__) diff --git a/ace/Service_Manager.h b/ace/Service_Manager.h index f628b65c413..7c0c5cbd10d 100644 --- a/ace/Service_Manager.h +++ b/ace/Service_Manager.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Service_Manager.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + + +//============================================================================= +/** + * @file Service_Manager.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SERVICE_MANAGER_H #define ACE_SERVICE_MANAGER_H @@ -29,35 +26,37 @@ #include "ace/INET_Addr.h" #include "ace/Service_Object.h" +/** + * @class ACE_Service_Manager + * + * @brief Provide a standard ACE service for managing all the services + * configured in an <ACE_Service_Repository>. + * + * This implementation is very simple. It just handles each + * client request one at a time. Each request is associated + * with a new connection, which is closed when the request is + * processed. In addition, you must be using the singleton + * <ACE_Reactor::instance> in order to trigger reconfigurations. + * This scheme can certainly be improved. + */ class ACE_Export ACE_Service_Manager : public ACE_Service_Object { - // = TITLE - // Provide a standard ACE service for managing all the services - // configured in an <ACE_Service_Repository>. - // - // = DESCRIPTION - // This implementation is very simple. It just handles each - // client request one at a time. Each request is associated - // with a new connection, which is closed when the request is - // processed. In addition, you must be using the singleton - // <ACE_Reactor::instance> in order to trigger reconfigurations. - // This scheme can certainly be improved. public: // = Initialization and termination hooks. + /// Constructor. ACE_Service_Manager (void); - // Constructor. + /// Destructor. ~ACE_Service_Manager (void); - // Destructor. protected: // = Perform the various meta-services. + /// Trigger a remote reconfiguration of the Service Configurator. virtual int reconfigure_services (void); - // Trigger a remote reconfiguration of the Service Configurator. + /// Determine all the services offered by this daemon and return the + /// information back to the client. virtual int list_services (void); - // Determine all the services offered by this daemon and return the - // information back to the client. // = Dynamic linking hooks. virtual int init (int argc, ACE_TCHAR *argv[]); @@ -68,11 +67,11 @@ protected: virtual int suspend (void); virtual int resume (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: int open (const ACE_INET_Addr &sia); @@ -83,21 +82,21 @@ private: virtual int handle_close (ACE_HANDLE fd, ACE_Reactor_Mask); virtual int handle_signal (int signum, siginfo_t *, ucontext_t *); + /// Connection to the client (we only support one client connection + /// at a time). ACE_SOCK_Stream client_stream_; - // Connection to the client (we only support one client connection - // at a time). + /// Acceptor instance. ACE_SOCK_Acceptor acceptor_; - // Acceptor instance. + /// Keep track of the debugging level. int debug_; - // Keep track of the debugging level. + /// The signal used to trigger reconfiguration. int signum_; - // The signal used to trigger reconfiguration. + /// Default port for the Acceptor to listen on. static u_short DEFAULT_PORT_; - // Default port for the Acceptor to listen on. }; #if defined (__ACE_INLINE__) diff --git a/ace/Service_Object.h b/ace/Service_Object.h index de4e7aaca66..c74de19141c 100644 --- a/ace/Service_Object.h +++ b/ace/Service_Object.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Service_Object.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Service_Object.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SERVICE_OBJECT_H #define ACE_SERVICE_OBJECT_H @@ -27,51 +24,55 @@ #include "ace/Event_Handler.h" #define ACE_Component ACE_Service_Object +/** + * @class ACE_Service_Object + * + * @brief Provide the abstract base class common to all service + * implementations. + * + * Classes that inherit from <ACE_Service_Objects> are capable + * of being registered with the <ACE_Reactor> (due to the + * <ACE_Event_Handler>, as well as being dynamically linked by + * the <ACE_Service_Config> (due to the <ACE_Shared_Object>). + */ class ACE_Export ACE_Service_Object : public ACE_Event_Handler, public ACE_Shared_Object { - // = TITLE - // Provide the abstract base class common to all service - // implementations. - // - // = DESCRIPTION - // Classes that inherit from <ACE_Service_Objects> are capable - // of being registered with the <ACE_Reactor> (due to the - // <ACE_Event_Handler>, as well as being dynamically linked by - // the <ACE_Service_Config> (due to the <ACE_Shared_Object>). public: // = Initialization and termination methods. + /// Constructor. ACE_Service_Object (ACE_Reactor * = 0); - // Constructor. + /// Destructor. virtual ~ACE_Service_Object (void); - // Destructor. + /// Temporarily disable a service without removing it completely. virtual int suspend (void); - // Temporarily disable a service without removing it completely. + /// Re-enable a previously suspended service. virtual int resume (void); - // Re-enable a previously suspended service. }; // Forward decl. class ACE_Service_Type_Impl; +/** + * @class ACE_Service_Type + * + * @brief Keeps track of information related to the various + * <ACE_Service_Type_Impl> subclasses. + * + * This class acts as the interface of the "Bridge" pattern. + */ class ACE_Export ACE_Service_Type { - // = TITLE - // Keeps track of information related to the various - // <ACE_Service_Type_Impl> subclasses. - // - // = DESCRIPTION - // This class acts as the interface of the "Bridge" pattern. public: enum { + /// Delete the payload object. DELETE_OBJ = 1, - // Delete the payload object. + /// Delete the enclosing object. DELETE_THIS = 2 - // Delete the enclosing object. }; // = Initialization and termination methods. @@ -96,62 +97,64 @@ public: int active (void) const; void active (int); + /// Calls <fini> on <type_> void fini (void); - // Calls <fini> on <type_> + /// Check if the service has been fini'ed. int fini_called (void) const; - // Check if the service has been fini'ed. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Humanly readible name of svc. const ACE_TCHAR *name_; - // Humanly readible name of svc. + /// Pointer to C++ object that implements the svc. const ACE_Service_Type_Impl *type_; - // Pointer to C++ object that implements the svc. + /// Handle to shared object file (non-zero if dynamically linked). ACE_SHLIB_HANDLE handle_; - // Handle to shared object file (non-zero if dynamically linked). + /// 1 if svc is currently active, otherwise 0. int active_; - // 1 if svc is currently active, otherwise 0. + /// 1 if <fini> on <type_> has already been called, otherwise 0. int fini_already_called_; - // 1 if <fini> on <type_> has already been called, otherwise 0. }; +/** + * @class ACE_Service_Object_Ptr + * + * @brief This is a smart pointer that holds onto the associated + * <ACE_Service_Object> * until the current scope is left, at + * which point the object's <fini> hook is called and the + * service_object_ gets deleted. + * + * This class is similar to the Standard C++ Library class + * <auto_ptr>. It is used in conjunction with statically linked + * <ACE_Service_Objects>, as shown in the + * ./netsvcs/server/main.cpp example. + */ class ACE_Export ACE_Service_Object_Ptr { - // = TITLE - // This is a smart pointer that holds onto the associated - // <ACE_Service_Object> * until the current scope is left, at - // which point the object's <fini> hook is called and the - // service_object_ gets deleted. - // - // = DESCRIPTION - // This class is similar to the Standard C++ Library class - // <auto_ptr>. It is used in conjunction with statically linked - // <ACE_Service_Objects>, as shown in the - // ./netsvcs/server/main.cpp example. public: // = Initialization and termination methods. + /// Acquire ownership of the <so>. ACE_Service_Object_Ptr (ACE_Service_Object *so); - // Acquire ownership of the <so>. + /// Release the held <ACE_Service_Object> by calling its <fini> hook. ~ACE_Service_Object_Ptr (void); - // Release the held <ACE_Service_Object> by calling its <fini> hook. + /// Smart pointer to access the underlying <ACE_Service_Object>. ACE_Service_Object *operator-> (); - // Smart pointer to access the underlying <ACE_Service_Object>. private: + /// Holds the service object until we're done. ACE_Service_Object *service_object_; - // Holds the service object until we're done. }; #if defined (__ACE_INLINE__) diff --git a/ace/Service_Repository.h b/ace/Service_Repository.h index 0b1141192b3..73d9685b662 100644 --- a/ace/Service_Repository.h +++ b/ace/Service_Repository.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Service_Repository.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Service_Repository.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SERVICE_REPOSITORY_H #define ACE_SERVICE_REPOSITORY_H @@ -25,21 +22,23 @@ #endif /* ACE_LACKS_PRAGMA_ONCE */ #define ACE_Component_Repository ACE_Service_Repository +/** + * @class ACE_Service_Repository + * + * @brief Contains all the services offered by a Service + * Configurator-based application. + * + * This class contains a vector of <ACE_Service_Types> *'s and + * allows an administrative entity to centrally manage and + * control the behavior of application services. Note that if + * services are removed from the middle of the repository the + * order won't necessarily be maintained since the <remove> + * method performs compaction. However, the common case is not + * to remove services, so typically they are deleted in the + * reverse order that they were added originally. + */ class ACE_Export ACE_Service_Repository { - // = TITLE - // Contains all the services offered by a Service - // Configurator-based application. - // - // = DESCRIPTION - // This class contains a vector of <ACE_Service_Types> *'s and - // allows an administrative entity to centrally manage and - // control the behavior of application services. Note that if - // services are removed from the middle of the repository the - // order won't necessarily be maintained since the <remove> - // method performs compaction. However, the common case is not - // to remove services, so typically they are deleted in the - // reverse order that they were added originally. public: friend class ACE_Service_Repository_Iterator; @@ -49,147 +48,151 @@ public: }; // = Initialization and termination methods. + /// Initialize the repository. ACE_Service_Repository (void); - // Initialize the repository. + /// Initialize the repository. ACE_Service_Repository (int size); - // Initialize the repository. + /// Initialize the repository. int open (int size = DEFAULT_SIZE); - // Initialize the repository. + /// Close down the repository and free up dynamically allocated + /// resources. ~ACE_Service_Repository (void); - // Close down the repository and free up dynamically allocated - // resources. + /// Close down the repository and free up dynamically allocated + /// resources. int close (void); - // Close down the repository and free up dynamically allocated - // resources. + /// Finalize all the services by calling <fini> and deleteing + /// dynamically allocated services. int fini (void); - // Finalize all the services by calling <fini> and deleteing - // dynamically allocated services. + /// Get pointer to a process-wide <ACE_Service_Repository>. static ACE_Service_Repository *instance (int size = ACE_Service_Repository::DEFAULT_SIZE); - // Get pointer to a process-wide <ACE_Service_Repository>. + /// Set pointer to a process-wide <ACE_Service_Repository> and return + /// existing pointer. static ACE_Service_Repository *instance (ACE_Service_Repository *); - // Set pointer to a process-wide <ACE_Service_Repository> and return - // existing pointer. + /// Delete the dynamically allocated Singleton. static void close_singleton (void); - // Delete the dynamically allocated Singleton. // = Search structure operations (all acquire locks as necessary). + /// Insert a new service record. int insert (const ACE_Service_Type *); - // Insert a new service record. + /** + * Locate an entry with <name> in the table. If <ignore_suspended> + * is set then only consider services marked as resumed. If the + * caller wants the located entry, pass back a pointer to the + * located entry via <srp>. If <name> is not found, -1 is returned. + * If <name> is found, but it is suspended and the caller wants to + * ignore suspended services a -2 is returned. + */ int find (const ACE_TCHAR name[], const ACE_Service_Type **srp = 0, int ignore_suspended = 1); - // Locate an entry with <name> in the table. If <ignore_suspended> - // is set then only consider services marked as resumed. If the - // caller wants the located entry, pass back a pointer to the - // located entry via <srp>. If <name> is not found, -1 is returned. - // If <name> is found, but it is suspended and the caller wants to - // ignore suspended services a -2 is returned. + /// Remove an existing service record. int remove (const ACE_TCHAR[]); - // Remove an existing service record. // = Liveness control + /// Resume a service record. int resume (const ACE_TCHAR[], const ACE_Service_Type ** = 0); - // Resume a service record. + /// Suspend a service record. int suspend (const ACE_TCHAR[], const ACE_Service_Type ** = 0); - // Suspend a service record. + /// Return the current size of the repository. int current_size (void); - // Return the current size of the repository. + /// Return the total size of the repository. int total_size (void); - // Return the total size of the repository. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Locates <service_name>. Must be called without locks being + /// held... int find_i (const ACE_TCHAR service_name[], const ACE_Service_Type ** = 0, int ignore_suspended = 1); - // Locates <service_name>. Must be called without locks being - // held... + /// Contains all the configured services. const ACE_Service_Type **service_vector_; - // Contains all the configured services. + /// Current number of services. int current_size_; - // Current number of services. + /// Maximum number of services. int total_size_; - // Maximum number of services. + /// Pointer to a process-wide <ACE_Service_Repository>. static ACE_Service_Repository *svc_rep_; - // Pointer to a process-wide <ACE_Service_Repository>. + /// Must delete the <svc_rep_> if non-0. static int delete_svc_rep_; - // Must delete the <svc_rep_> if non-0. #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) + /// Synchronization variable for the MT_SAFE Repository ACE_Thread_Mutex lock_; - // Synchronization variable for the MT_SAFE Repository #endif /* ACE_MT_SAFE */ }; +/** + * @class ACE_Service_Repository_Iterator + * + * @brief Iterate through the <ACE_Service_Repository>. + * + * Make sure not to delete entries as the iteration is going on + * since this class is not designed as a robust iterator. + */ class ACE_Export ACE_Service_Repository_Iterator { - // = TITLE - // Iterate through the <ACE_Service_Repository>. - // - // = DESCRIPTION - // Make sure not to delete entries as the iteration is going on - // since this class is not designed as a robust iterator. public: // = Initialization and termination methods. + /// Constructor. ACE_Service_Repository_Iterator (ACE_Service_Repository &sr, int ignored_suspended = 1); - // Constructor. + /// Destructor. ~ACE_Service_Repository_Iterator (void); - // Destructor. // = Iteration methods. + /// Pass back the <next_item> that hasn't been seen in the set. + /// Returns 0 when all items have been seen, else 1. int next (const ACE_Service_Type *&next_item); - // Pass back the <next_item> that hasn't been seen in the set. - // Returns 0 when all items have been seen, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Reference to the Service Repository we are iterating over. ACE_Service_Repository &svc_rep_; - // Reference to the Service Repository we are iterating over. + /// Next index location that we haven't yet seen. int next_; - // Next index location that we haven't yet seen. + /// Are we ignoring suspended services? int ignore_suspended_; - // Are we ignoring suspended services? }; #if defined (__ACE_INLINE__) diff --git a/ace/Service_Templates.h b/ace/Service_Templates.h index 29cb071aee7..939081f7813 100644 --- a/ace/Service_Templates.h +++ b/ace/Service_Templates.h @@ -1,4 +1,14 @@ -// $Id$ + +//============================================================================= +/** + * @file Service_Templates.h + * + * $Id$ + * + * @author Priyanka Gontla <pgontla@ece.uci.edu> + */ +//============================================================================= + #ifndef ACE_SERVICE_TEMPLATES_H #define ACE_SERVICE_TEMPLATES_H diff --git a/ace/Service_Types.h b/ace/Service_Types.h index c70a8ffdd3e..738dbb177f2 100644 --- a/ace/Service_Types.h +++ b/ace/Service_Types.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Service_Types.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Service_Types.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SERVICE_TYPE_H #define ACE_SERVICE_TYPE_H @@ -26,19 +23,21 @@ #include "ace/Synch.h" +/** + * @class ACE_Service_Type_Impl + * + * @brief The abstract base class of the hierarchy that defines the + * contents of the <ACE_Service_Repository>. The subclasses of + * this class allow the configuration of <ACE_Service_Objects>, + * <ACE_Modules>, and <ACE_Streams>. + * + * This class provides the root of the implementation hierarchy + * of the "Bridge" pattern. It maintains a pointer to the + * appropriate type of service implementation, i.e., + * <ACE_Service_Object>, <ACE_Module>, or <ACE_Stream>. + */ class ACE_Export ACE_Service_Type_Impl { - // = TITLE - // The abstract base class of the hierarchy that defines the - // contents of the <ACE_Service_Repository>. The subclasses of - // this class allow the configuration of <ACE_Service_Objects>, - // <ACE_Modules>, and <ACE_Streams>. - // - // = DESCRIPTION - // This class provides the root of the implementation hierarchy - // of the "Bridge" pattern. It maintains a pointer to the - // appropriate type of service implementation, i.e., - // <ACE_Service_Object>, <ACE_Module>, or <ACE_Stream>. public: // = Initialization and termination methods. ACE_Service_Type_Impl (void *object, @@ -54,41 +53,44 @@ public: virtual int fini (void) const; virtual int info (ACE_TCHAR **str, size_t len) const = 0; + /// The pointer to the service. void *object (void) const; - // The pointer to the service. + /// Get the name of the service. const ACE_TCHAR *name (void) const; - // Get the name of the service. + /// Set the name of the service. void name (const ACE_TCHAR *); - // Set the name of the service. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Name of the service. const ACE_TCHAR *name_; - // Name of the service. + /// Pointer to object that implements the service. This actually + /// points to an <ACE_Service_Object>, <ACE_Module>, or <ACE_Stream>. void *obj_; - // Pointer to object that implements the service. This actually - // points to an <ACE_Service_Object>, <ACE_Module>, or <ACE_Stream>. + /// Destroy function to deallocate obj_. ACE_Service_Object_Exterminator gobbler_; - // Destroy function to deallocate obj_. + /// Flags that control serivce behavior (particularly deletion). u_int flags_; - // Flags that control serivce behavior (particularly deletion). }; +/** + * @class ACE_Service_Object_Type + * + * @brief Define the methods for handling the configuration of + * <ACE_Service_Objects>. + */ class ACE_Export ACE_Service_Object_Type : public ACE_Service_Type_Impl { - // = TITLE - // Define the methods for handling the configuration of - // <ACE_Service_Objects>. public: // = Initialization method. ACE_Service_Object_Type (void *so, @@ -106,11 +108,14 @@ public: virtual int info (ACE_TCHAR **str, size_t len) const; }; +/** + * @class ACE_Module_Type + * + * @brief Define the methods for handling the configuration of + * <ACE_Modules>. + */ class ACE_Export ACE_Module_Type : public ACE_Service_Type_Impl { - // = TITLE - // Define the methods for handling the configuration of - // <ACE_Modules>. public: // = Initialization method. ACE_Module_Type (void *m, // Really an <ACE_Module> *. @@ -130,22 +135,25 @@ public: ACE_Module_Type *link (void) const; void link (ACE_Module_Type *); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to the next <ACE_Module_Type> in an <ACE_Stream_Type>. ACE_Module_Type *link_; - // Pointer to the next <ACE_Module_Type> in an <ACE_Stream_Type>. }; +/** + * @class ACE_Stream_Type + * + * @brief Define the methods for handling the configuration of + * <ACE_Streams>. + */ class ACE_Export ACE_Stream_Type : public ACE_Service_Type_Impl { - // = TITLE - // Define the methods for handling the configuration of - // <ACE_Streams>. public: // = Initialization method. ACE_Stream_Type (void *s, // Really an <ACE_Stream> *. @@ -161,24 +169,24 @@ public: virtual int fini (void) const; virtual int info (ACE_TCHAR **str, size_t len) const; + /// Add a new <ACE_Module> to the top of the <ACE_Stream>. int push (ACE_Module_Type *new_module); - // Add a new <ACE_Module> to the top of the <ACE_Stream>. + /// Search for <module> and remove it from the <ACE_Stream>. int remove (ACE_Module_Type *module); - // Search for <module> and remove it from the <ACE_Stream>. + /// Locate the <ACE_Module> with <mod_name>. ACE_Module_Type *find (const ACE_TCHAR *mod_name) const; - // Locate the <ACE_Module> with <mod_name>. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to the head of the <ACE_Module> list. ACE_Module_Type *head_; - // Pointer to the head of the <ACE_Module> list. }; #if defined (__ACE_INLINE__) diff --git a/ace/Shared_Memory.h b/ace/Shared_Memory.h index 2faf3a94d1f..b97d92e2af8 100644 --- a/ace/Shared_Memory.h +++ b/ace/Shared_Memory.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Shared_Memory.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + + +//============================================================================= +/** + * @file Shared_Memory.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SHARED_MEMORY_H #define ACE_SHARED_MEMORY_H @@ -25,17 +22,19 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Shared_Memory + * + * @brief This base class adapts both System V shared memory and "BSD" + * mmap to a common API. + * + * This is a very simple-minded wrapper, i.e., it really is only + * useful for allocating large contiguous chunks of shared + * memory. For a much more sophisticated version, please check + * out the <ACE_Malloc> class. + */ class ACE_Export ACE_Shared_Memory { - // = TITLE - // This base class adapts both System V shared memory and "BSD" - // mmap to a common API. - // - // = DESCRIPTION - // This is a very simple-minded wrapper, i.e., it really is only - // useful for allocating large contiguous chunks of shared - // memory. For a much more sophisticated version, please check - // out the <ACE_Malloc> class. public: virtual ~ACE_Shared_Memory (void); @@ -47,5 +46,6 @@ public: virtual int get_segment_size (void) const = 0; virtual ACE_HANDLE get_id (void) const = 0; }; + #include "ace/post.h" #endif /* ACE_SHARED_MEMORY_H */ diff --git a/ace/Shared_Memory_MM.h b/ace/Shared_Memory_MM.h index 85062dbc3e6..1ea201be975 100644 --- a/ace/Shared_Memory_MM.h +++ b/ace/Shared_Memory_MM.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Shared_Memory_MM.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Shared_Memory_MM.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SHARED_MALLOC_MM_H #define ACE_SHARED_MALLOC_MM_H @@ -26,28 +23,31 @@ #include "ace/Mem_Map.h" +/** + * @class ACE_Shared_Memory_MM + * + * @brief Shared memory wrapper based on MMAP. + * + * This class provides a very simple-minded shared memory + * manager. For more a powerful memory allocator please see + * <ACE_Malloc>. + */ class ACE_Export ACE_Shared_Memory_MM : public ACE_Shared_Memory { - // = TITLE - // Shared memory wrapper based on MMAP. - // - // = DESCRIPTION - // This class provides a very simple-minded shared memory - // manager. For more a powerful memory allocator please see - // <ACE_Malloc>. public: // = Initialization and termination methods. + /// Default constructor. ACE_Shared_Memory_MM (void); - // Default constructor. + /// Constructor. ACE_Shared_Memory_MM (ACE_HANDLE handle, int length = -1, int prot = PROT_RDWR, int share = ACE_MAP_PRIVATE, char *addr = 0, off_t pos = 0); - // Constructor. + /// Constructor. ACE_Shared_Memory_MM (const ACE_TCHAR *file_name, int len = -1, int flags = O_RDWR | O_CREAT, @@ -55,16 +55,16 @@ public: int prot = PROT_RDWR, int share = ACE_MAP_SHARED, char *addr = 0, off_t pos = 0); - // Constructor. + /// Open method. int open (ACE_HANDLE handle, int length = -1, int prot = PROT_RDWR, int share = ACE_MAP_PRIVATE, char *addr = 0, off_t pos = 0); - // Open method. + /// Open method. int open (const ACE_TCHAR *file_name, int len = -1, int flags = O_RDWR | O_CREAT, @@ -73,40 +73,39 @@ public: int share = ACE_MAP_SHARED, char *addr = 0, off_t pos = 0); - // Open method. + /// Return the name of file that is mapped (if any). const ACE_TCHAR *filename (void) const; - // Return the name of file that is mapped (if any). + /// Close down the shared memory segment. virtual int close (void); - // Close down the shared memory segment. + /// Remove the shared memory segment and the underlying file. virtual int remove (void); - // Remove the shared memory segment and the underlying file. // = Allocation and deallocation methods. + /// Create a new chuck of memory containing <size> bytes. virtual void *malloc (size_t size = 0); - // Create a new chuck of memory containing <size> bytes. + /// Free a chuck of memory allocated by + /// <ACE_Shared_Memory_MM::malloc>. virtual int free (void *p); - // Free a chuck of memory allocated by - // <ACE_Shared_Memory_MM::malloc>. + /// Return the size of the shared memory segment. virtual int get_segment_size (void) const; - // Return the size of the shared memory segment. + /// Return the ID of the shared memory segment (i.e., an ACE_HANDLE). virtual ACE_HANDLE get_id (void) const; - // Return the ID of the shared memory segment (i.e., an ACE_HANDLE). + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// This version is implemented with memory-mapped files. ACE_Mem_Map shared_memory_; - // This version is implemented with memory-mapped files. }; #if defined (__ACE_INLINE__) diff --git a/ace/Shared_Memory_SV.h b/ace/Shared_Memory_SV.h index bf7fd7d36cb..6ed7315c168 100644 --- a/ace/Shared_Memory_SV.h +++ b/ace/Shared_Memory_SV.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Shared_Memory_SV.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Shared_Memory_SV.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SHARED_MALLOC_SV_H #define ACE_SHARED_MALLOC_SV_H @@ -26,15 +23,17 @@ #include "ace/SV_Shared_Memory.h" +/** + * @class ACE_Shared_Memory_SV + * + * @brief Shared memory wrapper based on System V shared memory. + * + * This class provides a very simple-minded shared memory + * manager. For more a powerful memory allocator please see + * <ACE_Malloc>. + */ class ACE_Export ACE_Shared_Memory_SV : public ACE_Shared_Memory { - // = TITLE - // Shared memory wrapper based on System V shared memory. - // - // = DESCRIPTION - // This class provides a very simple-minded shared memory - // manager. For more a powerful memory allocator please see - // <ACE_Malloc>. public: enum { @@ -58,36 +57,36 @@ public: void *addr = 0, int flags = 0); + /// Close down the shared memory segment. virtual int close (void); - // Close down the shared memory segment. + /// Remove the underlying shared memory segment. virtual int remove (void); - // Remove the underlying shared memory segment. // = Allocation and deallocation methods. + /// Create a new chuck of memory containing <size> bytes. virtual void *malloc (size_t = 0); - // Create a new chuck of memory containing <size> bytes. + /// Free a chuck of memory allocated by <ACE_Shared_Memory_SV::malloc>. virtual int free (void *p); - // Free a chuck of memory allocated by <ACE_Shared_Memory_SV::malloc>. + /// Return the size of the shared memory segment. virtual int get_segment_size (void) const; - // Return the size of the shared memory segment. + /// Return the ID of the shared memory segment (i.e., a System V + /// shared memory internal id). virtual ACE_HANDLE get_id (void) const; - // Return the ID of the shared memory segment (i.e., a System V - // shared memory internal id). + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// This version is implemented with System V shared memory + /// segments. ACE_SV_Shared_Memory shared_memory_; - // This version is implemented with System V shared memory - // segments. }; #if defined (__ACE_INLINE__) diff --git a/ace/Shared_Object.h b/ace/Shared_Object.h index e4082203255..33f0231a3c2 100644 --- a/ace/Shared_Object.h +++ b/ace/Shared_Object.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Shared_Object.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + + +//============================================================================= +/** + * @file Shared_Object.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SHARED_OBJECT_H #define ACE_SHARED_OBJECT_H @@ -25,22 +22,25 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Shared_Object + * + * @brief Provide the abstract base class used to access dynamic + * linking facilities. + */ class ACE_Export ACE_Shared_Object { - // = TITLE - // Provide the abstract base class used to access dynamic - // linking facilities. public: ACE_Shared_Object (void); + /// Initializes object when dynamic linking occurs. virtual int init (int argc, ACE_TCHAR *argv[]); - // Initializes object when dynamic linking occurs. + /// Terminates object when dynamic unlinking occurs. virtual int fini (void); - // Terminates object when dynamic unlinking occurs. + /// Returns information on active object. virtual int info (ACE_TCHAR **info_string, size_t length = 0) const; - // Returns information on active object. virtual ~ACE_Shared_Object (void); }; diff --git a/ace/Signal.h b/ace/Signal.h index ad4e3e19bf7..db3c2c66fcc 100644 --- a/ace/Signal.h +++ b/ace/Signal.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Signal.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Signal.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SIGNAL_HANDLER_H #define ACE_SIGNAL_HANDLER_H @@ -33,148 +30,161 @@ // This worksaround a horrible bug with HP/UX C++... typedef struct sigaction ACE_SIGACTION; +/** + * @class ACE_Sig_Set + * + * @brief Provide a C++ wrapper for the C sigset_t interface. + * + * Handle signals via a more elegant C++ interface (e.g., + * doesn't require the use of global variables or global + * functions in an application). + */ class ACE_Export ACE_Sig_Set { - // = TITLE - // Provide a C++ wrapper for the C sigset_t interface. - // - // = DESCRIPTION - // Handle signals via a more elegant C++ interface (e.g., - // doesn't require the use of global variables or global - // functions in an application). public: // = Initialization and termination methods. + /// Initialize <sigset_> with <sigset>. If <sigset> == 0 then fill + /// the set. ACE_Sig_Set (sigset_t *sigset); - // Initialize <sigset_> with <sigset>. If <sigset> == 0 then fill - // the set. + /// Initialize <sigset_> with <sigset>. If <sigset> == 0 then fill + /// the set. ACE_Sig_Set (ACE_Sig_Set *sigset); - // Initialize <sigset_> with <sigset>. If <sigset> == 0 then fill - // the set. + /// If <fill> == 0 then initialize the <sigset_> to be empty, else + /// full. ACE_Sig_Set (int fill = 0); - // If <fill> == 0 then initialize the <sigset_> to be empty, else - // full. ~ACE_Sig_Set (void); + /// Create a set that excludes all signals defined by the system. int empty_set (void); - // Create a set that excludes all signals defined by the system. + /// Create a set that includes all signals defined by the system. int fill_set (void); - // Create a set that includes all signals defined by the system. + /// Adds the individual signal specified by <signo> to the set. int sig_add (int signo); - // Adds the individual signal specified by <signo> to the set. + /// Deletes the individual signal specified by <signo> from the set. int sig_del (int signo); - // Deletes the individual signal specified by <signo> from the set. + /// Checks whether the signal specified by <signo> is in the set. int is_member (int signo) const; - // Checks whether the signal specified by <signo> is in the set. + /// Returns a pointer to the underlying <sigset_t>. operator sigset_t *(); - // Returns a pointer to the underlying <sigset_t>. + /// Returns a copy of the underlying <sigset_t>. sigset_t sigset (void) const; - // Returns a copy of the underlying <sigset_t>. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Set of signals. sigset_t sigset_; - // Set of signals. }; +/** + * @class ACE_Sig_Action + * + * @brief C++ wrapper facade for the <sigaction> struct. + */ class ACE_Export ACE_Sig_Action { - // = TITLE - // C++ wrapper facade for the <sigaction> struct. public: // = Initialization methods. + /// Default constructor. Initializes everything to 0. ACE_Sig_Action (void); - // Default constructor. Initializes everything to 0. + /// Assigns the various fields of a <sigaction> struct but doesn't + /// register for signal handling via the <sigaction> function. ACE_Sig_Action (ACE_SignalHandler handler, sigset_t *sigmask = 0, int flags = 0); - // Assigns the various fields of a <sigaction> struct but doesn't - // register for signal handling via the <sigaction> function. + /// Assigns the various fields of a <sigaction> struct but doesn't + /// register for signal handling via the <sigaction> function. ACE_Sig_Action (ACE_SignalHandler handler, const ACE_Sig_Set &sigmask, int flags = 0); - // Assigns the various fields of a <sigaction> struct but doesn't - // register for signal handling via the <sigaction> function. + /** + * Assigns the various fields of a <sigaction> struct and registers + * the <handler> to process signal <signum> via the <sigaction> + * function. + */ ACE_Sig_Action (ACE_SignalHandler handler, int signum, sigset_t *sigmask = 0, int flags = 0); - // Assigns the various fields of a <sigaction> struct and registers - // the <handler> to process signal <signum> via the <sigaction> - // function. + /** + * Assigns the various fields of a <sigaction> struct and registers + * the <handler> to process signal <signum> via the <sigaction> + * function. + */ ACE_Sig_Action (ACE_SignalHandler handler, int signum, const ACE_Sig_Set &sigmask, int flags = 0); - // Assigns the various fields of a <sigaction> struct and registers - // the <handler> to process signal <signum> via the <sigaction> - // function. - + // @@ The next two methods have a parameter as "signalss". Please do // not change the argument name as "signals". This causes the // following problem as reported by - // <James.Briggs@dsto.defence.gov.au>. + // <James.Briggs@dsto.defence.gov.au>. + - // In the file Signal.h two of the functions have and argument name // of signals. signals is a Qt macro (to do with their meta object - // stuff. + // stuff. // We could as well have it as "signal", but I am nost sure whether // that would cause a problem with something else - Bala <bala@cs> - + + /** + * Assigns the various fields of a <sigaction> struct and registers + * the <handler> to process all <signals> via the <sigaction> + * function. + */ ACE_Sig_Action (const ACE_Sig_Set &signalss, ACE_SignalHandler handler, const ACE_Sig_Set &sigmask, int flags = 0); - // Assigns the various fields of a <sigaction> struct and registers - // the <handler> to process all <signals> via the <sigaction> - // function. + /** + * Assigns the various fields of a <sigaction> struct and registers + * the <handler> to process all <signals> via the <sigaction> + * function. + */ ACE_Sig_Action (const ACE_Sig_Set &signalss, ACE_SignalHandler handler, sigset_t *sigmask = 0, int flags = 0); - // Assigns the various fields of a <sigaction> struct and registers - // the <handler> to process all <signals> via the <sigaction> - // function. + /// Copy constructor. ACE_Sig_Action (const ACE_Sig_Action &s); - // Copy constructor. + /// Default dtor. ~ACE_Sig_Action (void); - // Default dtor. // = Signal action management. + /// Register <this> as the current disposition and store old + /// disposition into <oaction> if it is non-NULL. int register_action (int signum, ACE_Sig_Action *oaction = 0); - // Register <this> as the current disposition and store old - // disposition into <oaction> if it is non-NULL. + /// Assign the value of <oaction> to <this> and make it become the + /// new signal disposition. int restore_action (int signum, ACE_Sig_Action &oaction); - // Assign the value of <oaction> to <this> and make it become the - // new signal disposition. + /// Retrieve the current disposition into <this>. int retrieve_action (int signum); - // Retrieve the current disposition into <this>. // = Set/get current signal action. void set (struct sigaction *); @@ -194,257 +204,290 @@ public: void handler (ACE_SignalHandler); ACE_SignalHandler handler (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Controls signal behavior. struct sigaction sa_; - // Controls signal behavior. }; +/** + * @class ACE_Sig_Guard + * + * @brief Hold signals in MASK for duration of a C++ statement block. + * Note that a "0" for mask causes all signals to be held. + */ class ACE_Export ACE_Sig_Guard { - // = TITLE - // Hold signals in MASK for duration of a C++ statement block. - // Note that a "0" for mask causes all signals to be held. public: // = Initialization and termination methods. + /// Block out signals in <mask>. Default is to block all signals! ACE_Sig_Guard (ACE_Sig_Set *mask = 0); - // Block out signals in <mask>. Default is to block all signals! + /// Restore blocked signals. ~ACE_Sig_Guard (void); - // Restore blocked signals. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Original signal mask. ACE_Sig_Set omask_; - // Original signal mask. }; +/** + * @class ACE_Sig_Handler + * + * @brief This is the main dispatcher of signals for ACE. It improves + * the existing UNIX signal handling mechanism by allowing C++ + * objects to handle signals in a way that avoids the use of + * global/static variables and functions. + * + * Using this class a program can register an <ACE_Event_Handler> + * with the <ACE_Sig_Handler> in order to handle a designated + * <signum>. When a signal occurs that corresponds to this + * <signum>, the <handle_signal> method of the registered + * <ACE_Event_Handler> is invoked automatically. + */ class ACE_Export ACE_Sig_Handler { - // = TITLE - // This is the main dispatcher of signals for ACE. It improves - // the existing UNIX signal handling mechanism by allowing C++ - // objects to handle signals in a way that avoids the use of - // global/static variables and functions. - // - // = DESCRIPTION - // Using this class a program can register an <ACE_Event_Handler> - // with the <ACE_Sig_Handler> in order to handle a designated - // <signum>. When a signal occurs that corresponds to this - // <signum>, the <handle_signal> method of the registered - // <ACE_Event_Handler> is invoked automatically. public: #if defined (ACE_HAS_WINCE) + /// Default ctor/dtor. ACE_Sig_Handler (void); virtual ~ACE_Sig_Handler (void); - // Default ctor/dtor. #endif /* ACE_HAS_WINCE */ // = Registration and removal methods. + /** + * Add a new <ACE_Event_Handler> and a new sigaction associated with + * <signum>. Passes back the existing <ACE_Event_Handler> and its + * sigaction if pointers are non-zero. Returns -1 on failure and >= + * 0 on success. + */ virtual int register_handler (int signum, ACE_Event_Handler *new_sh, ACE_Sig_Action *new_disp = 0, ACE_Event_Handler **old_sh = 0, ACE_Sig_Action *old_disp = 0); - // Add a new <ACE_Event_Handler> and a new sigaction associated with - // <signum>. Passes back the existing <ACE_Event_Handler> and its - // sigaction if pointers are non-zero. Returns -1 on failure and >= - // 0 on success. + /** + * Remove the <ACE_Event_Handler> currently associated with + * <signum>. <sigkey> is ignored in this implementation since there + * is only one instance of a signal handler. Install the new + * disposition (if given) and return the previous disposition (if + * desired by the caller). Returns 0 on success and -1 if <signum> + * is invalid. + */ virtual int remove_handler (int signum, ACE_Sig_Action *new_disp = 0, ACE_Sig_Action *old_disp = 0, int sigkey = -1); - // Remove the <ACE_Event_Handler> currently associated with - // <signum>. <sigkey> is ignored in this implementation since there - // is only one instance of a signal handler. Install the new - // disposition (if given) and return the previous disposition (if - // desired by the caller). Returns 0 on success and -1 if <signum> - // is invalid. // Set/get signal status. + /// True if there is a pending signal. static int sig_pending (void); - // True if there is a pending signal. + /// Reset the value of <sig_pending_> so that no signal is pending. static void sig_pending (int); - // Reset the value of <sig_pending_> so that no signal is pending. // = Set/get the handler associated with a particular signal. + /// Return the <ACE_Sig_Handler> associated with <signum>. virtual ACE_Event_Handler *handler (int signum); - // Return the <ACE_Sig_Handler> associated with <signum>. + /// Set a new <ACE_Event_Handler> that is associated with <signum>. + /// Return the existing handler. virtual ACE_Event_Handler *handler (int signum, ACE_Event_Handler *); - // Set a new <ACE_Event_Handler> that is associated with <signum>. - // Return the existing handler. + /** + * Callback routine registered with sigaction(2) that dispatches the + * <handle_signal> method of the appropriate pre-registered + * ACE_Event_Handler. + */ static void dispatch (int, siginfo_t *, ucontext_t *); - // Callback routine registered with sigaction(2) that dispatches the - // <handle_signal> method of the appropriate pre-registered - // ACE_Event_Handler. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = These methods and data members are shared by derived classes. + /** + * Set a new <ACE_Event_Handler> that is associated with <signum>. + * Return the existing handler. Does not acquire any locks so that + * it can be called from a signal handler, such as <dispatch>. + */ static ACE_Event_Handler *handler_i (int signum, ACE_Event_Handler *); - // Set a new <ACE_Event_Handler> that is associated with <signum>. - // Return the existing handler. Does not acquire any locks so that - // it can be called from a signal handler, such as <dispatch>. + /** + * This implementation method is called by <register_handler> and + * <dispatch>. It doesn't do any locking so that it can be called + * within a signal handler, such as <dispatch>. It adds a new + * <ACE_Event_Handler> and a new sigaction associated with <signum>. + * Passes back the existing <ACE_Event_Handler> and its sigaction if + * pointers are non-zero. Returns -1 on failure and >= 0 on + * success. + */ static int register_handler_i (int signum, ACE_Event_Handler *new_sh, ACE_Sig_Action *new_disp = 0, ACE_Event_Handler **old_sh = 0, ACE_Sig_Action *old_disp = 0); - // This implementation method is called by <register_handler> and - // <dispatch>. It doesn't do any locking so that it can be called - // within a signal handler, such as <dispatch>. It adds a new - // <ACE_Event_Handler> and a new sigaction associated with <signum>. - // Passes back the existing <ACE_Event_Handler> and its sigaction if - // pointers are non-zero. Returns -1 on failure and >= 0 on - // success. + /// Check whether the SIGNUM is within the legal range of signals. static int in_range (int signum); - // Check whether the SIGNUM is within the legal range of signals. + /// Keeps track of whether a signal is pending. static sig_atomic_t sig_pending_; - // Keeps track of whether a signal is pending. private: + /// Array used to store one user-defined Event_Handler for every + /// signal. static ACE_Event_Handler *signal_handlers_[ACE_NSIG]; - // Array used to store one user-defined Event_Handler for every - // signal. }; +/** + * @class ACE_Sig_Adapter + * + * @brief Provide an adapter that transforms various types of signal + * handlers into the scheme used by the <ACE_Reactor>. + */ class ACE_Export ACE_Sig_Adapter : public ACE_Event_Handler { - // = TITLE - // Provide an adapter that transforms various types of signal - // handlers into the scheme used by the <ACE_Reactor>. public: ACE_Sig_Adapter (ACE_Sig_Action &, int sigkey); ACE_Sig_Adapter (ACE_Event_Handler *, int sigkey); ACE_Sig_Adapter (ACE_Sig_Handler_Ex, int sigkey = 0); ~ACE_Sig_Adapter (void); + /// Returns this signal key that's used to remove this from the + /// <ACE_Reactor>'s internal table. int sigkey (void); - // Returns this signal key that's used to remove this from the - // <ACE_Reactor>'s internal table. + /// Called by the <Reactor> to dispatch the signal handler. virtual int handle_signal (int, siginfo_t *, ucontext_t *); - // Called by the <Reactor> to dispatch the signal handler. private: + /// Key for this signal handler (used to remove it). int sigkey_; - // Key for this signal handler (used to remove it). + /// Is this an external handler or an ACE handler? enum { - ACE_HANDLER, // We're just wrapping an ACE_Event_Handler. - SIG_ACTION, // An ACE_Sig_Action. - C_FUNCTION // A normal C function. + /// We're just wrapping an ACE_Event_Handler. + ACE_HANDLER, + /// An ACE_Sig_Action. + SIG_ACTION, + /// A normal C function. + C_FUNCTION } type_; - // Is this an external handler or an ACE handler? // = This should be a union, but C++ won't allow that because the // <ACE_Sig_Action> has a constructor. + /// This is an external handler (ugh). ACE_Sig_Action sa_; - // This is an external handler (ugh). + /// This is an ACE hander. ACE_Event_Handler *eh_; - // This is an ACE hander. + /// This is a normal C function. ACE_Sig_Handler_Ex sig_func_; - // This is a normal C function. }; #if !defined (ACE_HAS_BROKEN_HPUX_TEMPLATES) +/** + * @class ACE_Sig_Handlers + * + * @brief This is an alternative signal handling dispatcher for ACE. It + * allows a list of signal handlers to be registered for each + * signal. It also makes SA_RESTART the default mode. + * + * Using this class a program can register one or more + * ACE_Event_Handler with the ACE_Sig_Handler in order to + * handle a designated <signum>. When a signal occurs that + * corresponds to this <signum>, the <handle_signal> methods of + * all the registered ACE_Event_Handlers are invoked + * automatically. + */ class ACE_Export ACE_Sig_Handlers : public ACE_Sig_Handler { - // = TITLE - // This is an alternative signal handling dispatcher for ACE. It - // allows a list of signal handlers to be registered for each - // signal. It also makes SA_RESTART the default mode. - // - // = DESCRIPTION - // Using this class a program can register one or more - // ACE_Event_Handler with the ACE_Sig_Handler in order to - // handle a designated <signum>. When a signal occurs that - // corresponds to this <signum>, the <handle_signal> methods of - // all the registered ACE_Event_Handlers are invoked - // automatically. public: // = Registration and removal methods. + /** + * Add a new ACE_Event_Handler and a new sigaction associated with + * <signum>. Passes back the existing ACE_Event_Handler and its + * sigaction if pointers are non-zero. Returns -1 on failure and + * a <sigkey> that is >= 0 on success. + */ virtual int register_handler (int signum, ACE_Event_Handler *new_sh, ACE_Sig_Action *new_disp = 0, ACE_Event_Handler **old_sh = 0, ACE_Sig_Action *old_disp = 0); - // Add a new ACE_Event_Handler and a new sigaction associated with - // <signum>. Passes back the existing ACE_Event_Handler and its - // sigaction if pointers are non-zero. Returns -1 on failure and - // a <sigkey> that is >= 0 on success. + /** + * Remove the ACE_Event_Handler currently associated with <signum>. + * Install the new disposition (if given) and return the previous + * disposition (if desired by the caller). Returns 0 on success and + * -1 if <signum> is invalid. + */ virtual int remove_handler (int signum, ACE_Sig_Action *new_disp = 0, ACE_Sig_Action *old_disp = 0, int sigkey = -1); - // Remove the ACE_Event_Handler currently associated with <signum>. - // Install the new disposition (if given) and return the previous - // disposition (if desired by the caller). Returns 0 on success and - // -1 if <signum> is invalid. // = Set/get the handler associated with a particular signal. + /// Return the head of the list of <ACE_Sig_Handler>s associated with + /// SIGNUM. virtual ACE_Event_Handler *handler (int signum); - // Return the head of the list of <ACE_Sig_Handler>s associated with - // SIGNUM. + /** + * Set a new <ACE_Event_Handler> that is associated with SIGNUM at + * the head of the list of signals. Return the existing handler + * that was at the head. + */ virtual ACE_Event_Handler *handler (int signum, ACE_Event_Handler *); - // Set a new <ACE_Event_Handler> that is associated with SIGNUM at - // the head of the list of signals. Return the existing handler - // that was at the head. + /** + * Callback routine registered with sigaction(2) that dispatches the + * <handle_signal> method of all the pre-registered + * ACE_Event_Handlers for <signum> + */ static void dispatch (int signum, siginfo_t *, ucontext_t *); - // Callback routine registered with sigaction(2) that dispatches the - // <handle_signal> method of all the pre-registered - // ACE_Event_Handlers for <signum> + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /** + * Keeps track of the id that uniquely identifies each registered + * signal handler. This id can be used to cancel a timer via the + * <remove_handler> method. + */ static int sigkey_; - // Keeps track of the id that uniquely identifies each registered - // signal handler. This id can be used to cancel a timer via the - // <remove_handler> method. + /// If this is > 0 then a 3rd party library has registered a + /// handler... static int third_party_sig_handler_; - // If this is > 0 then a 3rd party library has registered a - // handler... }; #endif /* ACE_HAS_BROKEN_HPUX_TEMPLATES */ diff --git a/ace/Singleton.h b/ace/Singleton.h index bbef2cd335e..a06e5b4cf6f 100644 --- a/ace/Singleton.h +++ b/ace/Singleton.h @@ -1,21 +1,21 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Singleton.h -// -// = DESCRIPTION -// -// = AUTHOR -// Tim Harrison (harrison@cs.wustl.edu), Douglas C. Schmidt, Chris -// Lahey, Rich Christy, and David Levine. -// -// ============================================================================ + +//============================================================================= +/** + * @file Singleton.h + * + * $Id$ + * + * @brief + * + * @author Tim Harrison (harrison@cs.wustl.edu) + * @author Douglas C. Schmidt + * @author Chris Lahey + * @author Rich Christy + * @author and David Levine. + */ +//============================================================================= + #ifndef ACE_SINGLETON_H #define ACE_SINGLETON_H @@ -27,209 +27,211 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Singleton + * + * @brief A Singleton Adapter uses the Adapter pattern to turn ordinary + * classes into Singletons optimized with the Double-Checked + * Locking optimization pattern. + * + * This implementation is a slight variation on the GoF + * Singleton pattern. In particular, a single + * <ACE_Singleton<TYPE, ACE_LOCK> > instance is allocated here, + * not a <TYPE> instance. The reason for this is to allow + * registration with the <ACE_Object_Manager>, so that the + * Singleton can be cleaned up when the process exits. For this + * scheme to work, a (static) <cleanup> function must be + * provided. <ACE_Singleton> provides one so that TYPE doesn't + * need to. + * If you want to make sure that only the singleton instance of + * <T> is created, and that users cannot create their own + * instances of <T>, do the following to class <T>: + * (a) Make the constructor of <T> private (or protected) + * (b) Make Singleton a friend of <T> + * Here is an example: + * @verbatim + * class foo + * { + * friend class ACE_Singleton<foo, ACE_Null_Mutex>; + * private: + * foo () { cout << "foo constructed" << endl; } + * ~foo () { cout << "foo destroyed" << endl; } + * }; + * typedef ACE_Singleton<foo, ACE_Null_Mutex> FOO; + * @endverbatim + * + * NOTE: the best types to use for ACE_LOCK are + * ACE_Recursive_Thread_Mutex and ACE_Null_Mutex. + * ACE_Recursive_Thread_Mutex should be used in multi-threaded + * programs in which it is possible for more than one thread to + * access the <ACE_Singleton<TYPE, ACE_LOCK>> instance. + * ACE_Null_Mutex can be used otherwise. The reason that these + * types of locks are best has to do with their allocation by + * the ACE_Object_Manager. Single ACE_Recursive_Thread_Mutex + * and ACE_Null_Mutex instances are used for all ACE_Singleton + * instantiations. However, other types of locks are allocated + * per ACE_Singleton instantiation. + */ template <class TYPE, class ACE_LOCK> class ACE_Singleton : public ACE_Cleanup { - // = TITLE - // A Singleton Adapter uses the Adapter pattern to turn ordinary - // classes into Singletons optimized with the Double-Checked - // Locking optimization pattern. - // - // = DESCRIPTION - // This implementation is a slight variation on the GoF - // Singleton pattern. In particular, a single - // <ACE_Singleton<TYPE, ACE_LOCK> > instance is allocated here, - // not a <TYPE> instance. The reason for this is to allow - // registration with the <ACE_Object_Manager>, so that the - // Singleton can be cleaned up when the process exits. For this - // scheme to work, a (static) <cleanup> function must be - // provided. <ACE_Singleton> provides one so that TYPE doesn't - // need to. - // - // If you want to make sure that only the singleton instance of - // <T> is created, and that users cannot create their own - // instances of <T>, do the following to class <T>: - // - // (a) Make the constructor of <T> private (or protected) - // (b) Make Singleton a friend of <T> - // - // Here is an example: - // - // class foo - // { - // friend class ACE_Singleton<foo, ACE_Null_Mutex>; - // private: - // foo () { cout << "foo constructed" << endl; } - // ~foo () { cout << "foo destroyed" << endl; } - // }; - // - // typedef ACE_Singleton<foo, ACE_Null_Mutex> FOO; - // - // NOTE: the best types to use for ACE_LOCK are - // ACE_Recursive_Thread_Mutex and ACE_Null_Mutex. - // ACE_Recursive_Thread_Mutex should be used in multi-threaded - // programs in which it is possible for more than one thread to - // access the <ACE_Singleton<TYPE, ACE_LOCK>> instance. - // ACE_Null_Mutex can be used otherwise. The reason that these - // types of locks are best has to do with their allocation by - // the ACE_Object_Manager. Single ACE_Recursive_Thread_Mutex - // and ACE_Null_Mutex instances are used for all ACE_Singleton - // instantiations. However, other types of locks are allocated - // per ACE_Singleton instantiation. - // public: + /// Global access point to the Singleton. static TYPE *instance (void); - // Global access point to the Singleton. + /// Cleanup method, used by <ace_cleanup_destroyer> to destroy the + /// <ACE_Singleton>. virtual void cleanup (void *param = 0); - // Cleanup method, used by <ace_cleanup_destroyer> to destroy the - // <ACE_Singleton>. + /// Dump the state of the object. static void dump (void); - // Dump the state of the object. protected: + /// Default constructor. ACE_Singleton (void); - // Default constructor. + /// Contained instance. TYPE instance_; - // Contained instance. #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES) + /// Pointer to the Singleton (ACE_Cleanup) instance. static ACE_Singleton<TYPE, ACE_LOCK> *singleton_; - // Pointer to the Singleton (ACE_Cleanup) instance. #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */ + /// Get pointer to the Singleton instance. static ACE_Singleton<TYPE, ACE_LOCK> *&instance_i (void); - // Get pointer to the Singleton instance. }; +/** + * @class ACE_Unmanaged_Singleton + * + * @brief Same as <ACE_Singleton>, except does _not_ register with + * <ACE_Object_Manager> for destruction. + * + * This version of <ACE_Singleton> can be used if, for example, + * its DLL will be unloaded before the <ACE_Object_Manager> + * destroys the instance. Unlike with <ACE_Singleton>, the + * application is responsible for explicitly destroying the + * instance after it is no longer needed (if it wants to avoid + * memory leaks, at least). The <close> static member function + * must be used to explicitly destroy the Singleton. + * Usage is the same as for ACE_Singleton, but note that if you + * you declare a friend, the friend class must still be an + * *ACE_Singleton*<T, [ACE_LOCK]>, not an ACE_Unmanaged_Singleton. + */ template <class TYPE, class ACE_LOCK> class ACE_Unmanaged_Singleton : public ACE_Singleton <TYPE, ACE_LOCK> { - // = TITLE - // Same as <ACE_Singleton>, except does _not_ register with - // <ACE_Object_Manager> for destruction. - // - // = DESCRIPTION - // This version of <ACE_Singleton> can be used if, for example, - // its DLL will be unloaded before the <ACE_Object_Manager> - // destroys the instance. Unlike with <ACE_Singleton>, the - // application is responsible for explicitly destroying the - // instance after it is no longer needed (if it wants to avoid - // memory leaks, at least). The <close> static member function - // must be used to explicitly destroy the Singleton. - // Usage is the same as for ACE_Singleton, but note that if you - // you declare a friend, the friend class must still be an - // *ACE_Singleton*<T, [ACE_LOCK]>, not an ACE_Unmanaged_Singleton. - // public: + /// Global access point to the Singleton. static TYPE *instance (void); - // Global access point to the Singleton. + /// Explicitly delete the Singleton instance. static void close (void); - // Explicitly delete the Singleton instance. + /// Dump the state of the object. static void dump (void); - // Dump the state of the object. protected: + /// Default constructor. ACE_Unmanaged_Singleton (void); - // Default constructor. #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES) + /// Pointer to the Singleton (ACE_Cleanup) instance. static ACE_Unmanaged_Singleton<TYPE, ACE_LOCK> *singleton_; - // Pointer to the Singleton (ACE_Cleanup) instance. #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */ + /// Get pointer to the Singleton instance. static ACE_Unmanaged_Singleton<TYPE, ACE_LOCK> *&instance_i (void); - // Get pointer to the Singleton instance. }; +/** + * @class ACE_TSS_Singleton + * + * @brief This class uses the Adapter pattern to turn ordinary classes + * into Thread-specific Singletons optimized with the + * Double-Checked Locking optimization pattern. + * + * This implementation is another variation on the GoF Singleton + * pattern. In this case, a single <ACE_TSS_Singleton<TYPE, + * LOCK> > instance is allocated here, not a <TYPE> instance. + * Each call to the <instance> static method returns a Singleton + * whose pointer resides in thread-specific storage. As with + * <ACE_Singleton>, we use the <ACE_Object_Manager> so that the + * Singleton can be cleaned up when the process exits. For this + * scheme to work, a (static) <cleanup> function must be + * provided. <ACE_Singleton> provides one so that TYPE doesn't + * need to. + */ template <class TYPE, class ACE_LOCK> class ACE_TSS_Singleton : public ACE_Cleanup { - // = TITLE - // This class uses the Adapter pattern to turn ordinary classes - // into Thread-specific Singletons optimized with the - // Double-Checked Locking optimization pattern. - // - // = DESCRIPTION - // This implementation is another variation on the GoF Singleton - // pattern. In this case, a single <ACE_TSS_Singleton<TYPE, - // LOCK> > instance is allocated here, not a <TYPE> instance. - // Each call to the <instance> static method returns a Singleton - // whose pointer resides in thread-specific storage. As with - // <ACE_Singleton>, we use the <ACE_Object_Manager> so that the - // Singleton can be cleaned up when the process exits. For this - // scheme to work, a (static) <cleanup> function must be - // provided. <ACE_Singleton> provides one so that TYPE doesn't - // need to. public: + /// Global access point to the Singleton. static TYPE *instance (void); - // Global access point to the Singleton. + /// Cleanup method, used by <ace_cleanup_destroyer> to destroy the + /// singleton. virtual void cleanup (void *param = 0); - // Cleanup method, used by <ace_cleanup_destroyer> to destroy the - // singleton. + /// Dump the state of the object. static void dump (void); - // Dump the state of the object. protected: + /// Default constructor. ACE_TSS_Singleton (void); - // Default constructor. + /// Contained instance. ACE_TSS_TYPE (TYPE) instance_; - // Contained instance. #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES) + /// Pointer to the Singleton (ACE_Cleanup) instance. static ACE_TSS_Singleton<TYPE, ACE_LOCK> *singleton_; - // Pointer to the Singleton (ACE_Cleanup) instance. #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */ + /// Get pointer to the TSS Singleton instance. static ACE_TSS_Singleton<TYPE, ACE_LOCK> *&instance_i (void); - // Get pointer to the TSS Singleton instance. }; +/** + * @class ACE_Unmanaged_TSS_Singleton + * + * @brief Same as <ACE_TSS_Singleton>, except does _not_ register with + * <ACE_Object_Manager> for destruction. + * + * This version of <ACE_TSS_Singleton> can be used if, for + * example, its DLL will be unloaded before the + * <ACE_Object_Manager> destroys the instance. Unlike with + * <ACE_Singleton>, the application is responsible for + * explicitly destroying the instance after it is no longer + * needed (if it wants to avoid memory leaks, at least). The + * <close> static member function must be used to explicitly + * destroy the Singleton. + */ template <class TYPE, class ACE_LOCK> class ACE_Unmanaged_TSS_Singleton : public ACE_TSS_Singleton <TYPE, ACE_LOCK> { - // = TITLE - // Same as <ACE_TSS_Singleton>, except does _not_ register with - // <ACE_Object_Manager> for destruction. - // - // = DESCRIPTION - // This version of <ACE_TSS_Singleton> can be used if, for - // example, its DLL will be unloaded before the - // <ACE_Object_Manager> destroys the instance. Unlike with - // <ACE_Singleton>, the application is responsible for - // explicitly destroying the instance after it is no longer - // needed (if it wants to avoid memory leaks, at least). The - // <close> static member function must be used to explicitly - // destroy the Singleton. - // public: + /// Global access point to the Singleton. static TYPE *instance (void); - // Global access point to the Singleton. + /// Explicitly delete the Singleton instance. static void close (void); - // Explicitly delete the Singleton instance. + /// Dump the state of the object. static void dump (void); - // Dump the state of the object. protected: + /// Default constructor. ACE_Unmanaged_TSS_Singleton (void); - // Default constructor. #if !defined (ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES) + /// Pointer to the Singleton (ACE_Cleanup) instance. static ACE_Unmanaged_TSS_Singleton<TYPE, ACE_LOCK> *singleton_; - // Pointer to the Singleton (ACE_Cleanup) instance. #endif /* ACE_LACKS_STATIC_DATA_MEMBER_TEMPLATES */ + /// Get pointer to the Singleton instance. static ACE_Unmanaged_TSS_Singleton<TYPE, ACE_LOCK> *&instance_i (void); - // Get pointer to the Singleton instance. }; #if defined (__ACE_INLINE__) diff --git a/ace/Sock_Connect.h b/ace/Sock_Connect.h index 6309753990e..ef6513fb7f3 100644 --- a/ace/Sock_Connect.h +++ b/ace/Sock_Connect.h @@ -1,4 +1,14 @@ -// $Id$ + +//============================================================================= +/** + * @file Sock_Connect.h + * + * $Id$ + * + * @author Priyanka Gontla <pgontla@ece.uci.edu> + */ +//============================================================================= + #ifndef ACE_SOCK_CONNECT_H #define ACE_SOCK_CONNECT_H @@ -19,36 +29,42 @@ class ACE_Export ACE_Sock_Connect // = Socket connection establishment calls. + /// Bind a new unused port to <handle>. static int bind_port (ACE_HANDLE handle, ACE_UINT32 ip_addr = INADDR_ANY); - // Bind a new unused port to <handle>. + /** + * Get our broadcast address based on our <host_addr>. If + * <hostname> is non-0 we'll use it to determine our IP address. If + * <handle> is not <ACE_INVALID_HANDLE> then we'll use this to + * determine our broadcast address, otherwise we'll have to create a + * socket internally (and free it). Returns -1 on failure and 0 on + * success. + */ static int get_bcast_addr (ACE_UINT32 &bcast_addr, const ACE_TCHAR *hostname = 0, ACE_UINT32 host_addr = 0, ACE_HANDLE handle = ACE_INVALID_HANDLE); - // Get our broadcast address based on our <host_addr>. If - // <hostname> is non-0 we'll use it to determine our IP address. If - // <handle> is not <ACE_INVALID_HANDLE> then we'll use this to - // determine our broadcast address, otherwise we'll have to create a - // socket internally (and free it). Returns -1 on failure and 0 on - // success. + /** + * Return count and array of all configured IP interfaces on this + * host, rc = 0 on success (count == number of interfaces else -1). + * Caller is responsible for calling delete [] on <addr_array>. + */ static int get_ip_interfaces (size_t &count, ACE_INET_Addr *&addr_array); - // Return count and array of all configured IP interfaces on this - // host, rc = 0 on success (count == number of interfaces else -1). - // Caller is responsible for calling delete [] on <addr_array>. + /** + * Helper routine for get_ip_interfaces, differs by UNIX platform so + * put into own subroutine. perform some ioctls to retrieve ifconf + * list of ifreq structs. + */ static int count_interfaces (ACE_HANDLE handle, size_t &how_many); - // Helper routine for get_ip_interfaces, differs by UNIX platform so - // put into own subroutine. perform some ioctls to retrieve ifconf - // list of ifreq structs. + /// Routine to return a handle from which <ioctl> requests can be + /// made. Caller must <close> the handle. static ACE_HANDLE get_handle (void); - // Routine to return a handle from which <ioctl> requests can be - // made. Caller must <close> the handle. }; diff --git a/ace/Stats.h b/ace/Stats.h index cae62e865fa..c413dd7f062 100644 --- a/ace/Stats.h +++ b/ace/Stats.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Stats.h -// -// = AUTHORS -// David L. Levine -// -// ============================================================================ + +//============================================================================= +/** + * @file Stats.h + * + * $Id$ + * + * @author David L. Levine + */ +//============================================================================= + #ifndef ACE_STATS_H #define ACE_STATS_H @@ -28,165 +25,184 @@ #include "ace/Log_Msg.h" #include "ace/Basic_Stats.h" +/** + * @class ACE_Stats_Value + * + * @brief Helper class for ACE_Stats. + * + * Container struct for 64-bit signed quantity and its + * precision. It would be nicer to use a fixed-point class, but + * this is sufficient. Users typically don't need to use this + * class directly; see ACE_Stats below. + */ class ACE_Export ACE_Stats_Value { - // = TITLE - // Helper class for ACE_Stats. - // - // = DESCRIPTION - // Container struct for 64-bit signed quantity and its - // precision. It would be nicer to use a fixed-point class, but - // this is sufficient. Users typically don't need to use this - // class directly; see ACE_Stats below. public: + /** + * Constructor, which requires precision in terms of number of + * decimal digits. The more variation in the data, and the greater + * the data values, the smaller the precision must be to avoid + * overflow in the standard deviation calculation. 3 might be a + * good value, or maybe 4. 5 will probably be too large for + * non-trivial data sets. + */ ACE_Stats_Value (const u_int precision); - // Constructor, which requires precision in terms of number of - // decimal digits. The more variation in the data, and the greater - // the data values, the smaller the precision must be to avoid - // overflow in the standard deviation calculation. 3 might be a - // good value, or maybe 4. 5 will probably be too large for - // non-trivial data sets. + /// Accessor for precision. u_int precision (void) const; - // Accessor for precision. + /// Set the whole_ field. void whole (const ACE_UINT32); - // Set the whole_ field. + /// Accessor for the whole_ field. ACE_UINT32 whole (void) const; - // Accessor for the whole_ field. + /// Set the fractional_ field. void fractional (const ACE_UINT32); - // Set the fractional_ field. + /// Accessor for the fractional_ field. ACE_UINT32 fractional (void) const; - // Accessor for the fractional_ field. + /// Calculates the maximum value of the fractional portion, given its + /// precision. ACE_UINT32 fractional_field (void) const; - // Calculates the maximum value of the fractional portion, given its - // precision. + /** + * Access the value as an _unsigned_ 64 bit quantity. It scales the + * value up by <precision> decimal digits, so that no precision will + * be lost. It assumes that <whole_> is >= 0. + */ void scaled_value (ACE_UINT64 &) const; - // Access the value as an _unsigned_ 64 bit quantity. It scales the - // value up by <precision> decimal digits, so that no precision will - // be lost. It assumes that <whole_> is >= 0. + /// Print to stdout. void dump (void) const; - // Print to stdout. private: + /// The integer portion of the value. ACE_UINT32 whole_; - // The integer portion of the value. + /// The fractional portion of the value. ACE_UINT32 fractional_; - // The fractional portion of the value. + /** + * The number of decimal digits of precision represented by + * <fractional_>. Not declared const, so the only way to change it + * is via the assignment operator. + */ u_int precision_; - // The number of decimal digits of precision represented by - // <fractional_>. Not declared const, so the only way to change it - // is via the assignment operator. ACE_UNIMPLEMENTED_FUNC (ACE_Stats_Value (void)) }; +/** + * @class ACE_Stats + * + * @brief Provides simple statistical analysis. + * + * Simple statistical analysis package. Prominent features are: + * -# It does not use any floating point arithmetic. + * -# It handles positive and/or negative sample values. The + * sample value type is ACE_INT32. + * -# It uses 64 bit unsigned, but not 64 bit signed, quantities + * internally. + * -# It checks for overflow of internal state. + * -# It has no static variables of other than built-in types. + * + * Example usage: + * + * @verbatim + * ACE_Stats stats; + * for (u_int i = 0; i < n; ++i) + * { + * const ACE_UINT32 sample = ...; + * stats.sample (sample); + * } + * stats.print_summary (3); + * @endverbatim + */ class ACE_Export ACE_Stats { - // = TITLE - // Provides simple statistical analysis. - // - // = DESCRIPTION - // Simple statistical analysis package. Prominent features are: - // 1) It does not use any floating point arithmetic. - // 2) It handles positive and/or negative sample values. The - // sample value type is ACE_INT32. - // 3) It uses 64 bit unsigned, but not 64 bit signed, quantities - // internally. - // 4) It checks for overflow of internal state. - // 5) It has no static variables of other than built-in types. - // - // Example usage: - // ACE_Stats stats; - // for (u_int i = 0; i < n; ++i) - // { - // const ACE_UINT32 sample = /* ... */; - // stats.sample (sample); - // } - // stats.print_summary (3); public: + /// Default constructor. ACE_Stats (void); - // Default constructor. + /// Provide a new sample. Returns 0 on success, -1 if it fails due + /// to running out of memory, or to rolling over of the sample count. int sample (const ACE_INT32 value); - // Provide a new sample. Returns 0 on success, -1 if it fails due - // to running out of memory, or to rolling over of the sample count. + /// Access the number of samples provided so far. ACE_UINT32 samples (void) const; - // Access the number of samples provided so far. + /// Value of the minimum sample provided so far. ACE_INT32 min_value (void) const; - // Value of the minimum sample provided so far. + /// Value of the maximum sample provided so far. ACE_INT32 max_value (void) const; - // Value of the maximum sample provided so far. + /** + * Access the mean of all samples provided so far. The fractional + * part is to the specified number of digits. E.g., 3 fractional + * digits specifies that the fractional part is in thousandths. + */ void mean (ACE_Stats_Value &mean, const ACE_UINT32 scale_factor = 1); - // Access the mean of all samples provided so far. The fractional - // part is to the specified number of digits. E.g., 3 fractional - // digits specifies that the fractional part is in thousandths. + /// Access the standard deviation, whole and fractional parts. See + /// description of <mean> method for argument descriptions. int std_dev (ACE_Stats_Value &std_dev, const ACE_UINT32 scale_factor = 1); - // Access the standard deviation, whole and fractional parts. See - // description of <mean> method for argument descriptions. + /** + * Print summary statistics. If scale_factor is not 1, then the + * results are divided by it, i.e., each of the samples is scaled + * down by it. If internal overflow is reached with the specified + * scale factor, it successively tries to reduce it. Returns -1 if + * there is overflow even with a 0 scale factor. + */ int print_summary (const u_int precision, const ACE_UINT32 scale_factor = 1, FILE * = stdout) const; - // Print summary statistics. If scale_factor is not 1, then the - // results are divided by it, i.e., each of the samples is scaled - // down by it. If internal overflow is reached with the specified - // scale factor, it successively tries to reduce it. Returns -1 if - // there is overflow even with a 0 scale factor. + /// Initialize internal state. void reset (void); - // Initialize internal state. + /// Utility division function, for ACE_UINT64 dividend. static void quotient (const ACE_UINT64 dividend, const ACE_UINT32 divisor, ACE_Stats_Value "ient); - // Utility division function, for ACE_UINT64 dividend. + /// Utility division function, for ACE_Stats_Value dividend. static void quotient (const ACE_Stats_Value ÷nd, const ACE_UINT32 divisor, ACE_Stats_Value "ient); - // Utility division function, for ACE_Stats_Value dividend. + /** + * Sqrt function, which uses an oversimplified version of Newton's + * method. It's not fast, but it doesn't require floating point + * support. + */ static void square_root (const ACE_UINT64 n, ACE_Stats_Value &square_root); - // Sqrt function, which uses an oversimplified version of Newton's - // method. It's not fast, but it doesn't require floating point - // support. + /// Print summary statistics to stdout. void dump (void) const; - // Print summary statistics to stdout. private: + /// Internal indication of whether there has been overflow. Contains + /// the errno corresponding to the cause of overflow. u_int overflow_; - // Internal indication of whether there has been overflow. Contains - // the errno corresponding to the cause of overflow. + /// Number of samples. ACE_UINT32 number_of_samples_; - // Number of samples. + /// Minimum sample value. ACE_INT32 min_; - // Minimum sample value. + /// Maximum sample value. ACE_INT32 max_; - // Maximum sample value. + /// The samples. ACE_Unbounded_Queue <ACE_INT32> samples_; - // The samples. }; // **************************************************************** @@ -197,13 +213,11 @@ private: * * Keep the relevant information to perform throughput and latency * analysis, including: - * <OL> - * <LI> Minimum, Average and Maximum latency</LI> - * <LI> Jitter for the latency</LI> - * <LI> Linear regression for throughput</LI> - * <LI> Accumulate results from several samples to obtain aggregated - * results, across several threads or experiments.</LI> - * </OL> + * -# Minimum, Average and Maximum latency + * -# Jitter for the latency + * -# Linear regression for throughput + * -# Accumulate results from several samples to obtain aggregated + * results, across several threads or experiments. * * @todo The idea behind this class was to use linear regression to * determine if the throughput was linear or exhibited jitter. @@ -238,12 +252,12 @@ private: /// These are the fields that we should keep to perform linear /// regression //@{ + ///@} ACE_UINT64 throughput_sum_x_; ACE_UINT64 throughput_sum_x2_; ACE_UINT64 throughput_sum_y_; ACE_UINT64 throughput_sum_y2_; ACE_UINT64 throughput_sum_xy_; - //@} #endif /* 0 */ }; diff --git a/ace/Strategies.h b/ace/Strategies.h index 856fc3a3458..8abb99d6a27 100644 --- a/ace/Strategies.h +++ b/ace/Strategies.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Strategies.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Strategies.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_STRATEGIES_H #define ACE_STRATEGIES_H @@ -27,15 +24,17 @@ // Forward decls. class ACE_Reactor; +/** + * @class ACE_Notification_Strategy + * + * @brief Abstract class used for notifing an interested party + * + * A vehicle for extending the behavior of ACE_Message_Queue wrt + * notification *without subclassing*. Thus, it's an example of + * the Bridge/Strategy patterns. + */ class ACE_Export ACE_Notification_Strategy { - // = TITLE - // Abstract class used for notifing an interested party - // - // = DESCRIPTION - // A vehicle for extending the behavior of ACE_Message_Queue wrt - // notification *without subclassing*. Thus, it's an example of - // the Bridge/Strategy patterns. public: ACE_Notification_Strategy (ACE_Event_Handler *eh, ACE_Reactor_Mask mask); @@ -58,21 +57,23 @@ protected: ACE_Reactor_Mask mask_; }; +/** + * @class ACE_Reactor_Notification_Strategy + * + * @brief Used to notify an ACE_Reactor + * + * Integrates the <ACE_Message_Queue> notification into the + * <ACE_Reactor::notify> method. + */ class ACE_Export ACE_Reactor_Notification_Strategy : public ACE_Notification_Strategy { - // = TITLE - // Used to notify an ACE_Reactor - // - // = DESCRIPTION - // Integrates the <ACE_Message_Queue> notification into the - // <ACE_Reactor::notify> method. public: ACE_Reactor_Notification_Strategy (ACE_Reactor *reactor, ACE_Event_Handler *eh, ACE_Reactor_Mask mask); + /// Default dtor. virtual ~ACE_Reactor_Notification_Strategy (void); - // Default dtor. virtual int notify (void); @@ -87,101 +88,104 @@ protected: ACE_Reactor *reactor_; }; +/** + * @class ACE_Connection_Recycling_Strategy + * + * @brief Defines the interface for a connection recycler. + */ class ACE_Export ACE_Connection_Recycling_Strategy { - // = TITLE - // Defines the interface for a connection recycler. public: + /// Virtual Destructor virtual ~ACE_Connection_Recycling_Strategy (void); - // Virtual Destructor + /// Remove from cache. virtual int purge (const void *recycling_act) = 0; - // Remove from cache. + /// Add to cache. virtual int cache (const void *recycling_act) = 0; - // Add to cache. virtual int recycle_state (const void *recycling_act, ACE_Recyclable_State new_state) = 0; + /// Get/Set <recycle_state>. virtual ACE_Recyclable_State recycle_state (const void *recycling_act) const = 0; - // Get/Set <recycle_state>. + /// Mark as closed. virtual int mark_as_closed (const void *recycling_act) = 0; - // Mark as closed. + /// Mark as closed.(non-locking version) virtual int mark_as_closed_i (const void *recycling_act) = 0; - // Mark as closed.(non-locking version) + /// Cleanup hint and reset <*act_holder> to zero if <act_holder != 0>. virtual int cleanup_hint (const void *recycling_act, void **act_holder = 0) = 0; - // Cleanup hint and reset <*act_holder> to zero if <act_holder != 0>. protected: + /// Default ctor. ACE_Connection_Recycling_Strategy (void); - // Default ctor. }; class ACE_Export ACE_Recyclable { public: + /// Destructor. virtual ~ACE_Recyclable (void); - // Destructor. // = Set/Get the recyclable bit ACE_Recyclable_State recycle_state (void) const; void recycle_state (ACE_Recyclable_State new_state); protected: + /// Protected constructor. ACE_Recyclable (ACE_Recyclable_State initial_state); - // Protected constructor. + /// Our state. ACE_Recyclable_State recycle_state_; - // Our state. }; class ACE_Export ACE_Hashable { public: + /// Destructor. virtual ~ACE_Hashable (void); - // Destructor. + /// Computes and returns hash value. This "caches" the hash value to + /// improve performance. virtual u_long hash (void) const; - // Computes and returns hash value. This "caches" the hash value to - // improve performance. protected: + /// Protected constructor. ACE_Hashable (void); - // Protected constructor. + /// This is the method that actually performs the non-cached hash + /// computation. virtual u_long hash_i (void) const = 0; - // This is the method that actually performs the non-cached hash - // computation. + /// Pre-computed hash-value. u_long hash_value_; - // Pre-computed hash-value. }; class ACE_Export ACE_Refcountable { public: + /// Destructor. virtual ~ACE_Refcountable (void); - // Destructor. // = Increment/Decrement refcount int increment (void); int decrement (void); + /// Returns the current refcount. int refcount (void) const; - // Returns the current refcount. protected: + /// Protected constructor. ACE_Refcountable (int refcount); - // Protected constructor. + /// Current refcount. int refcount_; - // Current refcount. }; // This needs to come here to avoid circular dependencies. diff --git a/ace/Strategies_T.h b/ace/Strategies_T.h index 2f3e2669fbf..6f05e30d1a7 100644 --- a/ace/Strategies_T.h +++ b/ace/Strategies_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ACE_Strategies_T.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file ACE_Strategies_T.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_STRATEGIES_T_H #define ACE_STRATEGIES_T_H @@ -33,84 +30,92 @@ // Needed for broken linkers that can't grok long symbols. #define ACE_Refcounted_Hash_Recyclable ARHR +/** + * @class ACE_Recycling_Strategy + * + * @brief Defines the interface (and default implementation) for + * specifying a recycling strategy for a SVC_HANDLER. + * + * Acts as a consular to the Svc_Handler, preparing it for the + * tough times ahead when the Svc_Handler will be recycled. + */ template<class SVC_HANDLER> class ACE_Recycling_Strategy { - // = TITLE - // Defines the interface (and default implementation) for - // specifying a recycling strategy for a SVC_HANDLER. - // - // = DESCRIPTION - // Acts as a consular to the Svc_Handler, preparing it for the - // tough times ahead when the Svc_Handler will be recycled. public: + /// Virtual Destructor virtual ~ACE_Recycling_Strategy (void); - // Virtual Destructor + /// Tell the Svc_Handler something about the recycler, so that it can + /// reach the recycler when necessary. virtual int assign_recycler (SVC_HANDLER *svc_handler, ACE_Connection_Recycling_Strategy *recycler, const void *recycling_act); - // Tell the Svc_Handler something about the recycler, so that it can - // reach the recycler when necessary. + /// This allows us to prepare the svc_handler for recycling. virtual int prepare_for_recycling (SVC_HANDLER *svc_handler); - // This allows us to prepare the svc_handler for recycling. }; +/** + * @class ACE_Creation_Strategy + * + * @brief Defines the interface for specifying a creation strategy for + * a SVC_HANDLER. + * + * The default behavior is to make a new SVC_HANDLER. However, + * subclasses can override this strategy to perform SVC_HANDLER + * creation in any way that they like (such as creating subclass + * instances of SVC_HANDLER, using a singleton, dynamically + * linking the handler, etc.). + */ template <class SVC_HANDLER> class ACE_Creation_Strategy { - // = TITLE - // Defines the interface for specifying a creation strategy for - // a SVC_HANDLER. - // - // = DESCRIPTION - // The default behavior is to make a new SVC_HANDLER. However, - // subclasses can override this strategy to perform SVC_HANDLER - // creation in any way that they like (such as creating subclass - // instances of SVC_HANDLER, using a singleton, dynamically - // linking the handler, etc.). public: // = Initialization and termination methods. + /// Default constructor. ACE_Creation_Strategy (ACE_Thread_Manager * = 0); - // Default constructor. + /// A <Thread_Manager> is useful when creating active objects. int open (ACE_Thread_Manager * = 0); - // A <Thread_Manager> is useful when creating active objects. virtual ~ACE_Creation_Strategy (void); // = Factory method. + /** + * Create a SVC_HANDLER with the appropriate creation strategy. The + * default behavior of this method is to make a new <SVC_HANDLER> if + * <sh> == 0 (passing in the <Thread_Manager>), else <sh> is + * unchanged. Returns -1 on failure, else 0. + */ virtual int make_svc_handler (SVC_HANDLER *&sh); - // Create a SVC_HANDLER with the appropriate creation strategy. The - // default behavior of this method is to make a new <SVC_HANDLER> if - // <sh> == 0 (passing in the <Thread_Manager>), else <sh> is - // unchanged. Returns -1 on failure, else 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Pointer to a thread manager. ACE_Thread_Manager *thr_mgr_; - // Pointer to a thread manager. }; +/** + * @class ACE_Singleton_Strategy + * + * @brief Defines the interface for specifying a creation strategy for + * a <SVC_HANDLER> that always returns the same <SVC_HANDLER> (i.e., + * it's a Singleton). + * + * Note that this class takes over the ownership of the + * SVC_HANDLER passed into it as a parameter and it becomes + * responsible for deleting this object. + */ template <class SVC_HANDLER> class ACE_Singleton_Strategy : public ACE_Creation_Strategy<SVC_HANDLER> { - // = TITLE - // Defines the interface for specifying a creation strategy for - // a <SVC_HANDLER> that always returns the same <SVC_HANDLER> (i.e., - // it's a Singleton). - // - // = DESCRIPTION - // Note that this class takes over the ownership of the - // SVC_HANDLER passed into it as a parameter and it becomes - // responsible for deleting this object. public: // = Initialization and termination methods. ACE_Singleton_Strategy (SVC_HANDLER * = 0, @@ -120,366 +125,393 @@ public: virtual ~ACE_Singleton_Strategy (void); // = Factory method. + /// Create a Singleton SVC_HANDLER by always returning the same + /// SVC_HANDLER. Returns -1 on failure, else 0. virtual int make_svc_handler (SVC_HANDLER *&); - // Create a Singleton SVC_HANDLER by always returning the same - // SVC_HANDLER. Returns -1 on failure, else 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Pointer to the Singleton svc_handler. SVC_HANDLER *svc_handler_; - // Pointer to the Singleton svc_handler. + /// Keep track of whether we need to delete the <SVC_HANDLER>. int delete_svc_handler_; - // Keep track of whether we need to delete the <SVC_HANDLER>. }; +/** + * @class ACE_DLL_Strategy + * + * @brief Defines the interface for specifying a creation strategy for + * a SVC_HANDLER based on dynamic linking of the SVC_HANDLER. + */ template <class SVC_HANDLER> class ACE_DLL_Strategy : public ACE_Creation_Strategy<SVC_HANDLER> { - // = TITLE - // Defines the interface for specifying a creation strategy for - // a SVC_HANDLER based on dynamic linking of the SVC_HANDLER. public: // = Intialization and termination methods. + /// "Do-nothing" constructor. ACE_DLL_Strategy (void); - // "Do-nothing" constructor. + /// Initialize the DLL strategy based upon the service's DLL + /// information contained in the <svc_dll_info> string. ACE_DLL_Strategy (const char dll_name[], const char factory_function[], const char svc_name[], ACE_Service_Repository *, ACE_Thread_Manager * = 0); - // Initialize the DLL strategy based upon the service's DLL - // information contained in the <svc_dll_info> string. + /// Initialize the DLL strategy based upon the service's DLL + /// information contained in the <svc_dll_info> string. int open (const char dll_name[], const char factory_function[], const char svc_name[], ACE_Service_Repository *, ACE_Thread_Manager * = 0); - // Initialize the DLL strategy based upon the service's DLL - // information contained in the <svc_dll_info> string. // = Factory method. + /// Create a SVC_HANDLER by dynamically linking it from a DLL. + /// Returns -1 on failure, else 0. virtual int make_svc_handler (SVC_HANDLER *&); - // Create a SVC_HANDLER by dynamically linking it from a DLL. - // Returns -1 on failure, else 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: typedef ACE_Creation_Strategy<SVC_HANDLER> inherited; + /// Name of the DLL to dynamically link. char dll_name_[MAXPATHLEN + 1]; - // Name of the DLL to dynamically link. + /// Name of the factory function in the shared library to use to + /// obtain a pointer to the new SVC_HANDLER. char factory_function_[MAXPATHLEN + 1]; - // Name of the factory function in the shared library to use to - // obtain a pointer to the new SVC_HANDLER. + /// Name of the service. char svc_name_[MAXNAMELEN + 1]; - // Name of the service. + /// Pointer to the <Service_Repository>. ACE_Service_Repository *svc_rep_; - // Pointer to the <Service_Repository>. }; +/** + * @class ACE_Concurrency_Strategy + * + * @brief Defines the interface for specifying a concurrency strategy + * for a SVC_HANDLER. + * + * Default behavior is to activate the SVC_HANDLER by calling + * its <open> method (which allows the SVC_HANDLER to define its + * own concurrency strategy). However, subclasses can override + * this default strategy to do more sophisticated concurrency + * activations (such as creating the SVC_HANDLER as an active + * object via multi-threading or multi-processing). + */ template <class SVC_HANDLER> class ACE_Concurrency_Strategy { - // = TITLE - // Defines the interface for specifying a concurrency strategy - // for a SVC_HANDLER. - // - // = DESCRIPTION - // Default behavior is to activate the SVC_HANDLER by calling - // its <open> method (which allows the SVC_HANDLER to define its - // own concurrency strategy). However, subclasses can override - // this default strategy to do more sophisticated concurrency - // activations (such as creating the SVC_HANDLER as an active - // object via multi-threading or multi-processing). public: + /// Constructor ACE_Concurrency_Strategy (int flags = 0); - // Constructor // = Factory method. + /** + * Activate the <svc_handler> with an appropriate concurrency + * strategy. The default behavior of this method is to activate the + * SVC_HANDLER by calling its <open> method (which allows the + * SVC_HANDLER to define its own concurrency strategy). + */ virtual int activate_svc_handler (SVC_HANDLER *svc_handler, void *arg = 0); - // Activate the <svc_handler> with an appropriate concurrency - // strategy. The default behavior of this method is to activate the - // SVC_HANDLER by calling its <open> method (which allows the - // SVC_HANDLER to define its own concurrency strategy). virtual ~ACE_Concurrency_Strategy (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Flags that are parsed to set options for the connected + /// <SVC_HANDLER>. int flags_; - // Flags that are parsed to set options for the connected - // <SVC_HANDLER>. }; +/** + * @class ACE_Reactive_Strategy + * + * @brief Defines the interface for specifying a Reactive concurrency + * strategy for a SVC_HANDLER. + * + * This class provides a strategy that registers the + * <SVC_HANDLER> with a <Reactor>. + */ template <class SVC_HANDLER> class ACE_Reactive_Strategy : public ACE_Concurrency_Strategy <SVC_HANDLER> { - // = TITLE - // Defines the interface for specifying a Reactive concurrency - // strategy for a SVC_HANDLER. - // - // = DESCRIPTION - // This class provides a strategy that registers the - // <SVC_HANDLER> with a <Reactor>. public: // = Intialization and termination methods. + /// "Do-nothing constructor" ACE_Reactive_Strategy (int flags = 0); - // "Do-nothing constructor" + /// Initialize the strategy. ACE_Reactive_Strategy (ACE_Reactor *reactor, ACE_Reactor_Mask = ACE_Event_Handler::READ_MASK, int flags = 0); - // Initialize the strategy. + /// Initialize the strategy. virtual int open (ACE_Reactor *reactor, ACE_Reactor_Mask = ACE_Event_Handler::READ_MASK, int flags = 0); - // Initialize the strategy. + /// Destructor. virtual ~ACE_Reactive_Strategy (void); - // Destructor. // = Factory method. + /// Activate the <svc_handler> by registering it with the <Reactor> + /// and then calling it's <open> hook. virtual int activate_svc_handler (SVC_HANDLER *svc_handler, void *arg = 0); - // Activate the <svc_handler> by registering it with the <Reactor> - // and then calling it's <open> hook. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: typedef ACE_Concurrency_Strategy<SVC_HANDLER> inherited; + /// Pointer to the Reactor we'll use to register the <SVC_HANDLER>. ACE_Reactor *reactor_; - // Pointer to the Reactor we'll use to register the <SVC_HANDLER>. + /// The mask that we pass to the <Reactor> when we register the + /// <SVC_HANDLER>. ACE_Reactor_Mask mask_; - // The mask that we pass to the <Reactor> when we register the - // <SVC_HANDLER>. }; +/** + * @class ACE_Thread_Strategy + * + * @brief Defines the interface for specifying a concurrency strategy + * for a <SVC_HANDLER> based on multithreading. + * + * This class provides a strategy that manages the creation of + * threads to handle requests from clients concurrently. It + * behaves as a "thread factory", spawning threads "on-demand" + * to run the service specified by a user-supplied + * <SVC_HANDLER>. + */ template <class SVC_HANDLER> class ACE_Thread_Strategy : public ACE_Concurrency_Strategy<SVC_HANDLER> { - // = TITLE - // Defines the interface for specifying a concurrency strategy - // for a <SVC_HANDLER> based on multithreading. - // - // = DESCRIPTION - // This class provides a strategy that manages the creation of - // threads to handle requests from clients concurrently. It - // behaves as a "thread factory", spawning threads "on-demand" - // to run the service specified by a user-supplied - // <SVC_HANDLER>. public: // = Intialization and termination methods. + /// "Do-nothing constructor" ACE_Thread_Strategy (int flags = 0); - // "Do-nothing constructor" + /// Initialize the strategy. ACE_Thread_Strategy (ACE_Thread_Manager *tm, long thr_flags, size_t n_threads = 1, int flags = 0); - // Initialize the strategy. + /// Initialize the strategy. virtual int open (ACE_Thread_Manager *tm, long thr_flags, size_t n_threads = 1, int flags = 0); - // Initialize the strategy. virtual ~ACE_Thread_Strategy (void); // = Factory method. + /** + * Activate the <svc_handler> with an appropriate concurrency + * strategy. This method activates the SVC_HANDLER by first calling + * its <open> method and then calling its <activate> method to turn + * it into an active object. + */ virtual int activate_svc_handler (SVC_HANDLER *svc_handler, void *arg = 0); - // Activate the <svc_handler> with an appropriate concurrency - // strategy. This method activates the SVC_HANDLER by first calling - // its <open> method and then calling its <activate> method to turn - // it into an active object. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: typedef ACE_Concurrency_Strategy<SVC_HANDLER> inherited; + /// Thread manager for this class (must be provided). ACE_Thread_Manager *thr_mgr_; - // Thread manager for this class (must be provided). + /// Flags to pass into the <SVC_HANDLER::activate> method. long thr_flags_; - // Flags to pass into the <SVC_HANDLER::activate> method. + /// Number of threads to spawn. size_t n_threads_; - // Number of threads to spawn. }; +/** + * @class ACE_Process_Strategy + * + * @brief Defines the interface for specifying a concurrency strategy + * for a <SVC_HANDLER> based on multiprocessing. + * + * This class provides a strategy that manages the creation of + * processes to handle requests from clients concurrently. It + * behaves as a "process factory", using <ACE::fork> to fork + * threads "on-demand" to run the service specified by a + * user-supplied <SVC_HANDLER> in a separate process. + */ template <class SVC_HANDLER> class ACE_Process_Strategy : public ACE_Concurrency_Strategy<SVC_HANDLER> { - // = TITLE - // Defines the interface for specifying a concurrency strategy - // for a <SVC_HANDLER> based on multiprocessing. - // - // = DESCRIPTION - // This class provides a strategy that manages the creation of - // processes to handle requests from clients concurrently. It - // behaves as a "process factory", using <ACE::fork> to fork - // threads "on-demand" to run the service specified by a - // user-supplied <SVC_HANDLER> in a separate process. public: // = Intialization and termination methods. + /// Initialize the strategy. If <avoid_zombies> is non-0 then set a + /// flag to <ACE::fork> to avoid zombies. ACE_Process_Strategy (size_t n_processes = 1, ACE_Event_Handler *acceptor = 0, ACE_Reactor * = 0, int avoid_zombies = 0); - // Initialize the strategy. If <avoid_zombies> is non-0 then set a - // flag to <ACE::fork> to avoid zombies. + /// Initialize the strategy. If <avoid_zombies> is non-0 then set a + /// flag to <ACE::fork> to avoid zombies. virtual int open (size_t n_processes = 1, ACE_Event_Handler *acceptor = 0, ACE_Reactor * = 0, int avoid_zombies = 0); - // Initialize the strategy. If <avoid_zombies> is non-0 then set a - // flag to <ACE::fork> to avoid zombies. virtual ~ACE_Process_Strategy (void); // = Factory method. + /** + * Activate the <svc_handler> with an appropriate concurrency + * strategy. This method activates the SVC_HANDLER by first forking + * and then calling the <open> method of the SVC_HANDLER in the + * child. + */ virtual int activate_svc_handler (SVC_HANDLER *svc_handler, void *arg = 0); - // Activate the <svc_handler> with an appropriate concurrency - // strategy. This method activates the SVC_HANDLER by first forking - // and then calling the <open> method of the SVC_HANDLER in the - // child. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: typedef ACE_Concurrency_Strategy<SVC_HANDLER> inherited; + /// Number of processes to spawn. size_t n_processes_; - // Number of processes to spawn. + /** + * This is the <Acceptor> in the parent is listening on. We need to + * make sure that we remove it from the Reactor and close it down in + * the child. + */ ACE_Event_Handler *acceptor_; - // This is the <Acceptor> in the parent is listening on. We need to - // make sure that we remove it from the Reactor and close it down in - // the child. + /** + * This is the <Reactor> the child is using in conjunction with the + * <Acceptor>. We need to remove the <Acceptor> from this <Reactor> + * in the child. + */ ACE_Reactor *reactor_; - // This is the <Reactor> the child is using in conjunction with the - // <Acceptor>. We need to remove the <Acceptor> from this <Reactor> - // in the child. }; +/** + * @class ACE_Accept_Strategy + * + * @brief Defines the interface for specifying a passive connection + * acceptance strategy for a SVC_HANDLER. + * + * This class provides a strategy that manages passive + * connection acceptance of a client. + */ template <class SVC_HANDLER, ACE_PEER_ACCEPTOR_1> class ACE_Accept_Strategy { - // = TITLE - // Defines the interface for specifying a passive connection - // acceptance strategy for a SVC_HANDLER. - // - // = DESCRIPTION - // This class provides a strategy that manages passive - // connection acceptance of a client. public: // = Initialization and termination methods. + /// Default constructor. ACE_Accept_Strategy (ACE_Reactor *reactor = ACE_Reactor::instance ()); - // Default constructor. + /// Initialize the <peer_acceptor_> with <local_addr>. ACE_Accept_Strategy (const ACE_PEER_ACCEPTOR_ADDR &local_addr, int restart = 0, ACE_Reactor *reactor = ACE_Reactor::instance ()); - // Initialize the <peer_acceptor_> with <local_addr>. + /// Initialize the <peer_acceptor_> with <local_addr>. virtual int open (const ACE_PEER_ACCEPTOR_ADDR &local_addr, int restart = 0); - // Initialize the <peer_acceptor_> with <local_addr>. + /// Return the underlying ACE_HANDLE of the <peer_acceptor_>. virtual ACE_HANDLE get_handle (void) const; - // Return the underlying ACE_HANDLE of the <peer_acceptor_>. + /// Return a reference to the <peer_acceptor_>. virtual ACE_PEER_ACCEPTOR &acceptor (void) const; - // Return a reference to the <peer_acceptor_>. virtual ~ACE_Accept_Strategy (void); // = Factory method. + /// The default behavior delegates to the <accept> method of the + /// PEER_ACCEPTOR. virtual int accept_svc_handler (SVC_HANDLER *); - // The default behavior delegates to the <accept> method of the - // PEER_ACCEPTOR. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Factory that establishes connections passively. ACE_PEER_ACCEPTOR acceptor_; - // Factory that establishes connections passively. + /// Pointer to the reactor used by the Acceptor. ACE_Reactor *reactor_; - // Pointer to the reactor used by the Acceptor. }; +/** + * @class ACE_Connect_Strategy + * + * @brief Defines the interface for specifying an active + * connection establishment strategy for a SVC_HANDLER. + * + * This class provides a strategy that manages active + * connection establishment to a server. + */ template <class SVC_HANDLER, ACE_PEER_CONNECTOR_1> class ACE_Connect_Strategy { - // = TITLE - // Defines the interface for specifying an active - // connection establishment strategy for a SVC_HANDLER. - // - // = DESCRIPTION - // This class provides a strategy that manages active - // connection establishment to a server. public: // = Initialization and termination methods. + /// Default constructor. ACE_Connect_Strategy (void); - // Default constructor. + /// Return a reference to the <peer_connector_>. virtual ACE_PEER_CONNECTOR &connector (void) const; - // Return a reference to the <peer_connector_>. virtual ~ACE_Connect_Strategy (void); // = Factory method. + /// The default behavior delegates to the <connect> method of the + /// <PEER_CONNECTOR::connect>. virtual int connect_svc_handler (SVC_HANDLER *&sh, const ACE_PEER_CONNECTOR_ADDR &remote_addr, ACE_Time_Value *timeout, @@ -487,9 +519,12 @@ public: int reuse_addr, int flags, int perms); - // The default behavior delegates to the <connect> method of the - // <PEER_CONNECTOR::connect>. + /** + * The default behavior delegates to the <connect> method of the + * <PEER_CONNECTOR::connect>. + * Please check the documentation in Connector.h for more details. + */ virtual int connect_svc_handler (SVC_HANDLER *&sh, SVC_HANDLER *&sh_copy, const ACE_PEER_CONNECTOR_ADDR &remote_addr, @@ -498,151 +533,158 @@ public: int reuse_addr, int flags, int perms); - // The default behavior delegates to the <connect> method of the - // <PEER_CONNECTOR::connect>. - // Please check the documentation in Connector.h for more details. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Factory that establishes connections actively. ACE_PEER_CONNECTOR connector_; - // Factory that establishes connections actively. }; +/** + * @class ACE_Scheduling_Strategy + * + * @brief Defines the interface for specifying how to suspend and + * resume a service . + * + * This class provides a strategy that allows arbitrarily + * sophisticated service suspension and resumption. The default + * behavior is to do nothing... + */ template <class SVC_HANDLER> class ACE_Scheduling_Strategy { - // = TITLE - // Defines the interface for specifying how to suspend and - // resume a service . - // - // = DESCRIPTION - // This class provides a strategy that allows arbitrarily - // sophisticated service suspension and resumption. The default - // behavior is to do nothing... public: // = Initialization and termination methods. + /// Constructor ACE_Scheduling_Strategy (SVC_HANDLER * = 0); - // Constructor + /// Destructor virtual ~ACE_Scheduling_Strategy (void); - // Destructor // = Scheduling methods + /// Suspend hook. virtual int suspend (void); - // Suspend hook. + /// Resume hook. virtual int resume (void); - // Resume hook. + /// Dump the state of the object. virtual void dump (void) const; - // Dump the state of the object. }; +/** + * @class ACE_Schedule_All_Reactive_Strategy + * + * @brief Defines the interface for specifying how to suspend and + * resume a single-threaded reactive service . + * + * This class provides a strategy that suspends and resumes all + * the Event_Handlers in a Reactor in one fell swoop. + */ template <class SVC_HANDLER> class ACE_Schedule_All_Reactive_Strategy : public ACE_Scheduling_Strategy<SVC_HANDLER> { - // = TITLE - // Defines the interface for specifying how to suspend and - // resume a single-threaded reactive service . - // - // = DESCRIPTION - // This class provides a strategy that suspends and resumes all - // the Event_Handlers in a Reactor in one fell swoop. public: // = Initialization and termination methods. + /// Constructor ACE_Schedule_All_Reactive_Strategy (SVC_HANDLER * = 0); - // Constructor // = Scheduling methods + /// Suspend hook. virtual int suspend (void); - // Suspend hook. + /// Resume hook. virtual int resume (void); - // Resume hook. + /// Dump the state of the object. virtual void dump (void) const; - // Dump the state of the object. protected: + /// Thread Manager ACE_Reactor *reactor_; - // Thread Manager }; +/** + * @class ACE_Schedule_All_Threaded_Strategy + * + * @brief Defines the interface for specifying how to suspend and + * resume a multithreaded service . + * + * This class provides a strategy that suspends and resumes all + * the Event_Handlers controlled by a Thread_Manager in one fell swoop. + */ template <class SVC_HANDLER> class ACE_Schedule_All_Threaded_Strategy : public ACE_Scheduling_Strategy<SVC_HANDLER> { - // = TITLE - // Defines the interface for specifying how to suspend and - // resume a multithreaded service . - // - // = DESCRIPTION - // This class provides a strategy that suspends and resumes all - // the Event_Handlers controlled by a Thread_Manager in one fell swoop. public: // = Initialization and termination methods. + /// Constructor ACE_Schedule_All_Threaded_Strategy (SVC_HANDLER * = 0); - // Constructor // = Scheduling methods + /// Suspend hook. virtual int suspend (void); - // Suspend hook. + /// Resume hook. virtual int resume (void); - // Resume hook. + /// Dump the state of the object. virtual void dump (void) const; - // Dump the state of the object. protected: + /// Thread Manager ACE_Thread_Manager *thr_mgr_; - // Thread Manager }; +/** + * @class ACE_NOOP_Creation_Strategy + * + * @brief Implements a no-op creation strategy in order to defer + * decisions regarding creation to some later point in time, such + * as in connect or accept strategy. + * + * An example of the use of this is in the + * <ACE_Cached_Connect_Strategy>, which only returns a single + * connection for a given endpoint. + */ template <class SVC_HANDLER> class ACE_NOOP_Creation_Strategy : public ACE_Creation_Strategy<SVC_HANDLER> { - // = TITLE - // Implements a no-op creation strategy in order to defer - // decisions regarding creation to some later point in time, such - // as in connect or accept strategy. - // - // = DESCRIPTION - // An example of the use of this is in the - // <ACE_Cached_Connect_Strategy>, which only returns a single - // connection for a given endpoint. public: + /// This is a no-op. virtual int make_svc_handler (SVC_HANDLER *&); - // This is a no-op. }; +/** + * @class ACE_NOOP_Concurrency_Strategy + * + * @brief Implements a no-op activation strategy in order to avoid + * calling open on a svc_handler multiple times. + * + * An example of the use of this is in the + * <ACE_Cached_Connect_Strategy>, which reuses svc_handlers. + * Therefore we don't want to call open on the recycled + * svc_handler more than once. + */ template <class SVC_HANDLER> class ACE_NOOP_Concurrency_Strategy : public ACE_Concurrency_Strategy<SVC_HANDLER> { - // = TITLE - // Implements a no-op activation strategy in order to avoid - // calling open on a svc_handler multiple times. - // - // = DESCRIPTION - // An example of the use of this is in the - // <ACE_Cached_Connect_Strategy>, which reuses svc_handlers. - // Therefore we don't want to call open on the recycled - // svc_handler more than once. public: // = Factory method. + /// This is a no-op. virtual int activate_svc_handler (SVC_HANDLER *svc_handler, void *arg = 0); - // This is a no-op. }; template <class T> @@ -651,77 +693,93 @@ class ACE_Refcounted_Hash_Recyclable : public ACE_Refcountable, public ACE_Recyclable { public: + /// Default constructor. ACE_Refcounted_Hash_Recyclable (void); - // Default constructor. + /// Constructor. ACE_Refcounted_Hash_Recyclable (const T &t, int refcount = 0, ACE_Recyclable_State state = ACE_RECYCLABLE_UNKNOWN); - // Constructor. + /// Destructor virtual ~ACE_Refcounted_Hash_Recyclable (void); - // Destructor + /// Compares two instances. int operator== (const ACE_Refcounted_Hash_Recyclable<T> &rhs) const; int operator!= (const ACE_Refcounted_Hash_Recyclable<T> &rhs) const; - // Compares two instances. T &subject (); protected: + /// Computes and returns hash value. u_long hash_i (void) const; - // Computes and returns hash value. T t_; }; +/** + * @class ACE_Cached_Connect_Strategy + * + * @brief A connection strategy which caches connections to peers + * (represented by <SVC_HANDLER> instances), thereby allowing + * subsequent re-use of unused, but available, connections. + * + * <ACE_Cached_Connect_Strategy> is intended to be used as a + * plug-in connection strategy for <ACE_Strategy_Connector>. + * It's added value is re-use of established connections. + */ template <class SVC_HANDLER, ACE_PEER_CONNECTOR_1, class MUTEX> class ACE_Cached_Connect_Strategy : public ACE_Connection_Recycling_Strategy, public ACE_Connect_Strategy<SVC_HANDLER, ACE_PEER_CONNECTOR_2> { - // = TITLE - // A connection strategy which caches connections to peers - // (represented by <SVC_HANDLER> instances), thereby allowing - // subsequent re-use of unused, but available, connections. - // - // = DESCRIPTION - // <ACE_Cached_Connect_Strategy> is intended to be used as a - // plug-in connection strategy for <ACE_Strategy_Connector>. - // It's added value is re-use of established connections. public: typedef ACE_Cached_Connect_Strategy<SVC_HANDLER, ACE_PEER_CONNECTOR_2, MUTEX> SELF; + /// Constructor ACE_Cached_Connect_Strategy (ACE_Creation_Strategy<SVC_HANDLER> *cre_s = 0, ACE_Concurrency_Strategy<SVC_HANDLER> *con_s = 0, ACE_Recycling_Strategy<SVC_HANDLER> *rec_s = 0, MUTEX *mutex = 0, int delete_mutex = 0); - // Constructor + /// Destructor virtual ~ACE_Cached_Connect_Strategy (void); - // Destructor + /// This methods allow you to change the strategies used by the + /// cached connector. virtual int open (ACE_Creation_Strategy<SVC_HANDLER> *cre_s, ACE_Concurrency_Strategy<SVC_HANDLER> *con_s, ACE_Recycling_Strategy<SVC_HANDLER> *rec_s); - // This methods allow you to change the strategies used by the - // cached connector. + /// Template method for making a new <svc_handler> virtual int make_svc_handler (SVC_HANDLER *&sh); - // Template method for making a new <svc_handler> + /// Template method for activating a new <svc_handler> virtual int activate_svc_handler (SVC_HANDLER *svc_handler); - // Template method for activating a new <svc_handler> + /// Template method for setting the recycler information of the + /// svc_handler. virtual int assign_recycler (SVC_HANDLER *svc_handler, ACE_Connection_Recycling_Strategy *recycler, const void *recycling_act); - // Template method for setting the recycler information of the - // svc_handler. + /// Template method for preparing the svc_handler for recycling. virtual int prepare_for_recycling (SVC_HANDLER *svc_handler); - // Template method for preparing the svc_handler for recycling. + /** + * Checks to see if there is already a <SVC_HANDLER> in the cache + * connected to the <remote_addr>. If so, we return this pointer. + * Otherwise we establish the connection, put it into the cache, and + * return the <SVC_HANDLER> pointer. <[NOTE]>: the <{reuse_addr}> + * argument does NOT control re-use of addresses in the cache. + * Rather, if the underlying protocol requires a "dead time" prior + * to re-use of its addresses (TCP is a classic example of this), + * <{and}> the protocol provides a means by which to defeat the dead + * time, setting this argument to non-zero will defeat the dead-time + * requirement. <{Dev. Note: We might want to consider enhancing + * the interface at some point so that this also controls re-use of + * the cache.}> + */ virtual int connect_svc_handler (SVC_HANDLER *&sh, const ACE_PEER_CONNECTOR_ADDR &remote_addr, ACE_Time_Value *timeout, @@ -737,41 +795,31 @@ public: int reuse_addr, int flags, int perms); - // Checks to see if there is already a <SVC_HANDLER> in the cache - // connected to the <remote_addr>. If so, we return this pointer. - // Otherwise we establish the connection, put it into the cache, and - // return the <SVC_HANDLER> pointer. <[NOTE]>: the <{reuse_addr}> - // argument does NOT control re-use of addresses in the cache. - // Rather, if the underlying protocol requires a "dead time" prior - // to re-use of its addresses (TCP is a classic example of this), - // <{and}> the protocol provides a means by which to defeat the dead - // time, setting this argument to non-zero will defeat the dead-time - // requirement. <{Dev. Note: We might want to consider enhancing - // the interface at some point so that this also controls re-use of - // the cache.}> + /// Remove from cache. virtual int purge (const void *recycling_act); - // Remove from cache. + /// Add to cache. virtual int cache (const void *recycling_act); - // Add to cache. + /// Get/Set <recycle_state>. virtual int recycle_state (const void *recycling_act, ACE_Recyclable_State new_state); virtual ACE_Recyclable_State recycle_state (const void *recycling_act) const; - // Get/Set <recycle_state>. + /// Mark as closed. virtual int mark_as_closed (const void *recycling_act); - // Mark as closed. + /** + * Mark as closed (non-locking version). This method needs to be public + * as it is used in the cleanup of handlers where teh locked version causes + * a deadlock. + */ virtual int mark_as_closed_i (const void *recycling_act); - // Mark as closed (non-locking version). This method needs to be public - // as it is used in the cleanup of handlers where teh locked version causes - // a deadlock. + /// Cleanup hint and reset <*act_holder> to zero if <act_holder != 0>. virtual int cleanup_hint (const void *recycling_act, void **act_holder = 0); - // Cleanup hint and reset <*act_holder> to zero if <act_holder != 0>. // = Define some useful typedefs. typedef ACE_Creation_Strategy<SVC_HANDLER> @@ -804,6 +852,7 @@ public: protected: + /// Creates a new connection. virtual int new_connection (SVC_HANDLER *&sh, const ACE_PEER_CONNECTOR_ADDR &remote_addr, ACE_Time_Value *timeout, @@ -811,26 +860,25 @@ protected: int reuse_addr, int flags, int perms); - // Creates a new connection. + /// Find an idle handle. int find (ACE_Refcounted_Hash_Recyclable<ACE_PEER_CONNECTOR_ADDR> &search_addr, ACE_Hash_Map_Entry<ACE_Refcounted_Hash_Recyclable<ACE_PEER_CONNECTOR_ADDR>, SVC_HANDLER *> *&entry); - // Find an idle handle. + /// Remove from cache (non-locking version). virtual int purge_i (const void *recycling_act); - // Remove from cache (non-locking version). + /// Add to cache (non-locking version). virtual int cache_i (const void *recycling_act); - // Add to cache (non-locking version). + /// Get/Set <recycle_state> (non-locking version). virtual int recycle_state_i (const void *recycling_act, ACE_Recyclable_State new_state); virtual ACE_Recyclable_State recycle_state_i (const void *recycling_act) const; - // Get/Set <recycle_state> (non-locking version). + /// Cleanup hint and reset <*act_holder> to zero if <act_holder != 0>. virtual int cleanup_hint_i (const void *recycling_act, void **act_holder); - // Cleanup hint and reset <*act_holder> to zero if <act_holder != 0>. // = Helpers int check_hint_i (SVC_HANDLER *&sh, @@ -862,40 +910,40 @@ protected: int perms, int &found); + /// Table that maintains the cache of connected <SVC_HANDLER>s. CONNECTION_MAP connection_map_; - // Table that maintains the cache of connected <SVC_HANDLER>s. + /// Mutual exclusion for this object. MUTEX *lock_; - // Mutual exclusion for this object. + /// Mutual exclusion for this object. int delete_lock_; - // Mutual exclusion for this object. + /// Reverse lock. REVERSE_MUTEX *reverse_lock_; - // Reverse lock. // = Strategy objects. + /// Creation strategy for an <Connector>. CREATION_STRATEGY *creation_strategy_; - // Creation strategy for an <Connector>. + /// 1 if <Connector> created the creation strategy and thus should + /// delete it, else 0. int delete_creation_strategy_; - // 1 if <Connector> created the creation strategy and thus should - // delete it, else 0. + /// Concurrency strategy for an <Connector>. CONCURRENCY_STRATEGY *concurrency_strategy_; - // Concurrency strategy for an <Connector>. + /// 1 if <Connector> created the concurrency strategy and thus should + /// delete it, else 0. int delete_concurrency_strategy_; - // 1 if <Connector> created the concurrency strategy and thus should - // delete it, else 0. + /// Recycling strategy for an <Connector>. RECYCLING_STRATEGY *recycling_strategy_; - // Recycling strategy for an <Connector>. + /// 1 if <Connector> created the recycling strategy and thus should + /// delete it, else 0. int delete_recycling_strategy_; - // 1 if <Connector> created the recycling strategy and thus should - // delete it, else 0. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/Stream.h b/ace/Stream.h index 81d073ae848..f4f432e10f3 100644 --- a/ace/Stream.h +++ b/ace/Stream.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Stream.h -// -// = AUTHOR -// Doug Schmidt <schmidt@uci.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Stream.h + * + * $Id$ + * + * @author Doug Schmidt <schmidt@uci.edu> + */ +//============================================================================= + #ifndef ACE_STREAM_H #define ACE_STREAM_H @@ -32,178 +29,191 @@ // Forward decls. template<ACE_SYNCH_DECL> class ACE_Stream_Iterator; +/** + * @class ACE_Stream + * + * @brief This class is the primary abstraction for the ASX framework. + * It is moduled after System V Stream. + * + * A Stream consists of a stack of <ACE_Modules>, each of which + * contains two <ACE_Tasks>. Even though the methods in this + * class are virtual, this class isn't really intended for + * subclassing unless you know what you are doing. In + * particular, the <ACE_Stream> destructor calls <close>, which + * won't be overridden properly unless you call it in a subclass + * destructor. + */ template <ACE_SYNCH_DECL> class ACE_Stream { - // = TITLE - // This class is the primary abstraction for the ASX framework. - // It is moduled after System V Stream. - // - // = DESCRIPTION - // A Stream consists of a stack of <ACE_Modules>, each of which - // contains two <ACE_Tasks>. Even though the methods in this - // class are virtual, this class isn't really intended for - // subclassing unless you know what you are doing. In - // particular, the <ACE_Stream> destructor calls <close>, which - // won't be overridden properly unless you call it in a subclass - // destructor. public: friend class ACE_Stream_Iterator<ACE_SYNCH_USE>; enum { + /// Indicates that <close> deletes the Tasks. Don't change this + /// value without updating the same enum in class ACE_Module... M_DELETE = 3 - // Indicates that <close> deletes the Tasks. Don't change this - // value without updating the same enum in class ACE_Module... }; // = Initializatation and termination methods. + /** + * Create a Stream consisting of <head> and <tail> as the Stream + * head and Stream tail, respectively. If these are 0 then the + * <ACE_Stream_Head> and <ACE_Stream_Tail> are used, respectively. + * <arg> is the value past in to the <open> methods of the tasks. + */ ACE_Stream (void *arg = 0, ACE_Module<ACE_SYNCH_USE> *head = 0, ACE_Module<ACE_SYNCH_USE> *tail = 0); - // Create a Stream consisting of <head> and <tail> as the Stream - // head and Stream tail, respectively. If these are 0 then the - // <ACE_Stream_Head> and <ACE_Stream_Tail> are used, respectively. - // <arg> is the value past in to the <open> methods of the tasks. + /** + * Create a Stream consisting of <head> and <tail> as the Stream + * head and Stream tail, respectively. If these are 0 then the + * <ACE_Stream_Head> and <ACE_Stream_Tail> are used, respectively. + * <arg> is the value past in to the <open> methods of the tasks. + */ virtual int open (void *arg, ACE_Module<ACE_SYNCH_USE> *head = 0, ACE_Module<ACE_SYNCH_USE> *tail = 0); - // Create a Stream consisting of <head> and <tail> as the Stream - // head and Stream tail, respectively. If these are 0 then the - // <ACE_Stream_Head> and <ACE_Stream_Tail> are used, respectively. - // <arg> is the value past in to the <open> methods of the tasks. + /// Close down the stream and release all the resources. virtual int close (int flags = M_DELETE); - // Close down the stream and release all the resources. + /// Close down the stream and release all the resources. virtual ~ACE_Stream (void); - // Close down the stream and release all the resources. // = ACE_Stream plumbing operations + /// Add a new module <mod> right below the Stream head. virtual int push (ACE_Module<ACE_SYNCH_USE> *mod); - // Add a new module <mod> right below the Stream head. + /// Remove the <mod> right below the Stream head and close it down. virtual int pop (int flags = M_DELETE); - // Remove the <mod> right below the Stream head and close it down. + /// Return the top module on the stream (right below the stream + /// head). virtual int top (ACE_Module<ACE_SYNCH_USE> *&mod); - // Return the top module on the stream (right below the stream - // head). + /// Insert a new module <mod> below the named module <prev_name>. virtual int insert (const ACE_TCHAR *prev_name, ACE_Module<ACE_SYNCH_USE> *mod); - // Insert a new module <mod> below the named module <prev_name>. + /// Replace the named module <replace_name> with a new module <mod>. virtual int replace (const ACE_TCHAR *replace_name, ACE_Module<ACE_SYNCH_USE> *mod, int flags = M_DELETE); - // Replace the named module <replace_name> with a new module <mod>. + /// Remove the named module <mod> from the stream. This bypasses the + /// strict LIFO ordering of <push> and <pop>. virtual int remove (const ACE_TCHAR *mod, int flags = M_DELETE); - // Remove the named module <mod> from the stream. This bypasses the - // strict LIFO ordering of <push> and <pop>. + /// Return current stream head. virtual ACE_Module<ACE_SYNCH_USE> *head (void); - // Return current stream head. + /// Return current stream tail. virtual ACE_Module<ACE_SYNCH_USE> *tail (void); - // Return current stream tail. + /// Find a particular ACE_Module. virtual ACE_Module<ACE_SYNCH_USE> *find (const ACE_TCHAR *mod); - // Find a particular ACE_Module. + /// Create a pipe between two Streams. virtual int link (ACE_Stream<ACE_SYNCH_USE> &); - // Create a pipe between two Streams. + /// Remove a pipe formed between two Streams. virtual int unlink (void); - // Remove a pipe formed between two Streams. // = Blocking data transfer operations + /** + * Send the message <mb> down the stream, starting at the Module + * below the Stream head. Wait for upto <timeout> amount of + * absolute time for the operation to complete (or block forever if + * <timeout> == 0). + */ virtual int put (ACE_Message_Block *mb, ACE_Time_Value *timeout = 0); - // Send the message <mb> down the stream, starting at the Module - // below the Stream head. Wait for upto <timeout> amount of - // absolute time for the operation to complete (or block forever if - // <timeout> == 0). + /** + * Read the message <mb> that is stored in the the stream head. + * Wait for upto <timeout> amount of absolute time for the operation + * to complete (or block forever if <timeout> == 0). + */ virtual int get (ACE_Message_Block *&mb, ACE_Time_Value *timeout = 0); - // Read the message <mb> that is stored in the the stream head. - // Wait for upto <timeout> amount of absolute time for the operation - // to complete (or block forever if <timeout> == 0). + /// Send control message down the stream. virtual int control (ACE_IO_Cntl_Msg::ACE_IO_Cntl_Cmds cmd, void *args); - // Send control message down the stream. + /// Synchronize with the final close of the stream. virtual int wait (void); - // Synchronize with the final close of the stream. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Actually perform the unlinking of two Streams (must be called + /// with locks held). int unlink_i (void); - // Actually perform the unlinking of two Streams (must be called - // with locks held). + /// Actually perform the linking of two Streams (must be called with + /// locks held). int link_i (ACE_Stream<ACE_SYNCH_USE> &); - // Actually perform the linking of two Streams (must be called with - // locks held). + /// Must a new module onto the Stream. int push_module (ACE_Module<ACE_SYNCH_USE> *, ACE_Module<ACE_SYNCH_USE> * = 0, ACE_Module<ACE_SYNCH_USE> * = 0); - // Must a new module onto the Stream. + /// Pointer to the head of the stream. ACE_Module<ACE_SYNCH_USE> *stream_head_; - // Pointer to the head of the stream. + /// Pointer to the tail of the stream. ACE_Module<ACE_SYNCH_USE> *stream_tail_; - // Pointer to the tail of the stream. + /// Pointer to an adjoining linked stream. ACE_Stream<ACE_SYNCH_USE> *linked_us_; - // Pointer to an adjoining linked stream. // = Synchronization objects used for thread-safe streams. + /// Protect the stream against race conditions. ACE_SYNCH_MUTEX_T lock_; - // Protect the stream against race conditions. + /// Use to tell all threads waiting on the close that we are done. ACE_SYNCH_CONDITION_T final_close_; - // Use to tell all threads waiting on the close that we are done. }; +/** + * @class ACE_Stream_Iterator + * + * @brief Iterate through an <ACE_Stream>. + */ template <ACE_SYNCH_DECL> class ACE_Stream_Iterator { - // = TITLE - // Iterate through an <ACE_Stream>. public: // = Initialization method. ACE_Stream_Iterator (const ACE_Stream<ACE_SYNCH_USE> &sr); // = Iteration methods. + /// Pass back the <next_item> that hasn't been seen in the set. + /// Returns 0 when all items have been seen, else 1. int next (const ACE_Module<ACE_SYNCH_USE> *&next_item); - // Pass back the <next_item> that hasn't been seen in the set. - // Returns 0 when all items have been seen, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Move forward by one element in the set. Returns 0 when all the + /// items in the set have been seen, else 1. int advance (void); - // Move forward by one element in the set. Returns 0 when all the - // items in the set have been seen, else 1. private: + /// Next <Module> that we haven't yet seen. ACE_Module<ACE_SYNCH_USE> *next_; - // Next <Module> that we haven't yet seen. }; #if defined (__ACE_INLINE__) diff --git a/ace/Stream_Modules.h b/ace/Stream_Modules.h index 9489bac1975..1cf2ef4e6ad 100644 --- a/ace/Stream_Modules.h +++ b/ace/Stream_Modules.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Stream_Modules.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Stream_Modules.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + // This needs to go outside of the #if !defined() block. Don't ask... #include "ace/Task.h" @@ -25,17 +22,20 @@ #define ACE_STREAM_MODULES #include "ace/pre.h" +/** + * @class ACE_Stream_Head + * + * @brief Standard module that acts as the head of a ustream. + */ template <ACE_SYNCH_DECL> class ACE_Stream_Head : public ACE_Task<ACE_SYNCH_USE> { - // = TITLE - // Standard module that acts as the head of a ustream. public: + /// Construction ACE_Stream_Head (void); - // Construction + /// Destruction ~ACE_Stream_Head (void); - // Destruction // = ACE_Task hooks virtual int open (void *a = 0); @@ -48,29 +48,32 @@ public: virtual int info (ACE_TCHAR **info_string, size_t length) const; virtual int fini (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Performs canonical flushing at the ACE_Stream Head. int control (ACE_Message_Block *); int canonical_flush (ACE_Message_Block *); - // Performs canonical flushing at the ACE_Stream Head. }; +/** + * @class ACE_Stream_Tail + * + * @brief Standard module that acts as the head of a ustream. + */ template <ACE_SYNCH_DECL> class ACE_Stream_Tail : public ACE_Task<ACE_SYNCH_USE> { - // = TITLE - // Standard module that acts as the head of a ustream. public: + /// Construction ACE_Stream_Tail (void); - // Construction + /// Destruction ~ACE_Stream_Tail (void); - // Destruction // = ACE_Task hooks virtual int open (void *a = 0); @@ -83,30 +86,33 @@ public: virtual int info (ACE_TCHAR **info_string, size_t length) const; virtual int fini (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Performs canonical flushing at the ACE_Stream tail. int control (ACE_Message_Block *); int canonical_flush (ACE_Message_Block *); - // Performs canonical flushing at the ACE_Stream tail. }; +/** + * @class ACE_Thru_Task + * + * @brief Standard module that acts as a "no op", simply passing on all + * data to its adjacent neighbor. + */ template <ACE_SYNCH_DECL> class ACE_Thru_Task : public ACE_Task<ACE_SYNCH_USE> { - // = TITLE - // Standard module that acts as a "no op", simply passing on all - // data to its adjacent neighbor. public: + /// Construction ACE_Thru_Task (void); - // Construction + /// Destruction ~ACE_Thru_Task (void); - // Destruction // = ACE_Task hooks virtual int open (void *a = 0); @@ -119,11 +125,11 @@ public: virtual int info (ACE_TCHAR **info_string, size_t length) const; virtual int fini (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/Svc_Conf.h b/ace/Svc_Conf.h index 729a91769ac..2b9ad997a00 100644 --- a/ace/Svc_Conf.h +++ b/ace/Svc_Conf.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Svc_Conf.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Svc_Conf.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SVC_CONF_H #define ACE_SVC_CONF_H diff --git a/ace/Svc_Handler.h b/ace/Svc_Handler.h index b0efb441b00..cae1dd67206 100644 --- a/ace/Svc_Handler.h +++ b/ace/Svc_Handler.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Svc_Handler.h -// -// = AUTHOR -// Doug Schmidt and Irfan Pyrarli. -// -// ============================================================================ + +//============================================================================= +/** + * @file Svc_Handler.h + * + * $Id$ + * + * @author Doug Schmidt and Irfan Pyrarli. + */ +//============================================================================= + #ifndef ACE_SVC_HANDLER_H #define ACE_SVC_HANDLER_H @@ -30,136 +27,156 @@ class ACE_Connection_Recycling_Strategy; #include "ace/Task.h" #include "ace/Service_Config.h" +/** + * @class ACE_Svc_Handler + * + * @brief Defines the interface for a service that exchanges data with + * its connected peer. + * + * This class provides a well-defined interface that the + * Acceptor and Connector pattern factories use as their target. + * Typically, client applications will subclass ACE_Svc_Handler + * and do all the interesting work in the subclass. One thing + * that the ACE_Svc_Handler does contain is a PEER_STREAM + * endpoint that is initialized by an ACE_Acceptor or + * ACE_Connector when a connection is established successfully. + * This endpoint is used to exchange data between a + * ACE_Svc_Handler and the peer it is connected with. + */ template <ACE_PEER_STREAM_1, ACE_SYNCH_DECL> class ACE_Svc_Handler : public ACE_Task<ACE_SYNCH_USE> { - // = TITLE - // Defines the interface for a service that exchanges data with - // its connected peer. - // - // = DESCRIPTION - // This class provides a well-defined interface that the - // Acceptor and Connector pattern factories use as their target. - // Typically, client applications will subclass ACE_Svc_Handler - // and do all the interesting work in the subclass. One thing - // that the ACE_Svc_Handler does contain is a PEER_STREAM - // endpoint that is initialized by an ACE_Acceptor or - // ACE_Connector when a connection is established successfully. - // This endpoint is used to exchange data between a - // ACE_Svc_Handler and the peer it is connected with. public: // = Initialization and termination methods. + /** + * Constructor initializes the <thr_mgr> and <mq> by passing them + * down to the <ACE_Task> base class. The <reactor> is passed to + * the <ACE_Event_Handler>. + */ ACE_Svc_Handler (ACE_Thread_Manager *thr_mgr = 0, ACE_Message_Queue<ACE_SYNCH_USE> *mq = 0, ACE_Reactor *reactor = ACE_Reactor::instance ()); - // Constructor initializes the <thr_mgr> and <mq> by passing them - // down to the <ACE_Task> base class. The <reactor> is passed to - // the <ACE_Event_Handler>. + /// Destructor. virtual ~ACE_Svc_Handler (void); - // Destructor. + /// Activate the client handler. This is typically called by the + /// <ACE_Acceptor> or <ACE_Connector>. virtual int open (void * = 0); - // Activate the client handler. This is typically called by the - // <ACE_Acceptor> or <ACE_Connector>. + /** + * Object termination hook -- application-specific cleanup code goes + * here. This function is called by the idle() function if the object + * does not have a ACE_Connection_Recycling_Strategy associated with it. + * Also, due to this class's derivation from <ACE_Task>, <close> is + * also called when a thread activated with this object exits. See + * <ACE_Task::close> for further details. The default action of this + * function is to call <handle_close> with the default arguments. + */ virtual int close (u_long flags = 0); - // Object termination hook -- application-specific cleanup code goes - // here. This function is called by the idle() function if the object - // does not have a ACE_Connection_Recycling_Strategy associated with it. - // Also, due to this class's derivation from <ACE_Task>, <close> is - // also called when a thread activated with this object exits. See - // <ACE_Task::close> for further details. The default action of this - // function is to call <handle_close> with the default arguments. + /** + * Call this method if you want to recycling the <Svc_Handler> + * instead of closing it. If the object does not have a recycler, + * it will be closed. + */ virtual int idle (u_long flags = 0); - // Call this method if you want to recycling the <Svc_Handler> - // instead of closing it. If the object does not have a recycler, - // it will be closed. + /** + * Call this method if you want to get/set the state of the + * <Svc_Handler>. If the object does not have a recycler, this call + * will have no effect (and the accessor will return + * ACE_RECYCLABLE_UNKNOWN). + */ virtual ACE_Recyclable_State recycle_state (void) const; virtual int recycle_state (ACE_Recyclable_State new_state); - // Call this method if you want to get/set the state of the - // <Svc_Handler>. If the object does not have a recycler, this call - // will have no effect (and the accessor will return - // ACE_RECYCLABLE_UNKNOWN). + /** + * When the svc_handle is no longer needed around as a hint, call + * this method. In addition, reset <*act_holder> to zero if + * <act_holder != 0>. + */ virtual void cleanup_hint (void **act_holder = 0); - // When the svc_handle is no longer needed around as a hint, call - // this method. In addition, reset <*act_holder> to zero if - // <act_holder != 0>. // = Dynamic linking hooks. + /// Default version does no work and returns -1. Must be overloaded + /// by application developer to do anything meaningful. virtual int init (int argc, ACE_TCHAR *argv[]); - // Default version does no work and returns -1. Must be overloaded - // by application developer to do anything meaningful. + /// Default version does no work and returns -1. Must be overloaded + /// by application developer to do anything meaningful. virtual int fini (void); - // Default version does no work and returns -1. Must be overloaded - // by application developer to do anything meaningful. + /// Default version does no work and returns -1. Must be overloaded + /// by application developer to do anything meaningful. virtual int info (ACE_TCHAR **info_string, size_t length) const; - // Default version does no work and returns -1. Must be overloaded - // by application developer to do anything meaningful. // = Demultiplexing hooks. + /** + * Perform termination activities on the SVC_HANDLER. The default + * behavior is to close down the <peer_> (to avoid descriptor leaks) + * and to <destroy> this object (to avoid memory leaks)! If you + * don't want this behavior make sure you override this method... + */ virtual int handle_close (ACE_HANDLE = ACE_INVALID_HANDLE, ACE_Reactor_Mask = ACE_Event_Handler::ALL_EVENTS_MASK); - // Perform termination activities on the SVC_HANDLER. The default - // behavior is to close down the <peer_> (to avoid descriptor leaks) - // and to <destroy> this object (to avoid memory leaks)! If you - // don't want this behavior make sure you override this method... + /// Default behavior when timeouts occur is to close down the + /// <Svc_Handler> by calling <handle_close>. virtual int handle_timeout (const ACE_Time_Value &time, const void *); - // Default behavior when timeouts occur is to close down the - // <Svc_Handler> by calling <handle_close>. + /// Get the underlying handle associated with the <peer_>. virtual ACE_HANDLE get_handle (void) const; - // Get the underlying handle associated with the <peer_>. + /// Set the underlying handle associated with the <peer_>. virtual void set_handle (ACE_HANDLE); - // Set the underlying handle associated with the <peer_>. + /// Returns the underlying PEER_STREAM. Used by + /// <ACE_Acceptor::accept> and <ACE_Connector::connect> factories ACE_PEER_STREAM &peer (void) const; - // Returns the underlying PEER_STREAM. Used by - // <ACE_Acceptor::accept> and <ACE_Connector::connect> factories + /// Overloaded new operator. This method unobtrusively records if a + /// <Svc_Handler> is allocated dynamically. void *operator new (size_t n); - // Overloaded new operator. This method unobtrusively records if a - // <Svc_Handler> is allocated dynamically. + /// This operator permits "placement new" on a per-object basis. void * operator new (size_t n, void *p); - // This operator permits "placement new" on a per-object basis. + /** + * Call this to free up dynamically allocated <Svc_Handlers> + * (otherwise you will get memory leaks). In general, you should + * call this method rather than <delete> since this method knows + * whether or not the object was allocated dynamically, and can act + * accordingly (i.e., deleting it if it was allocated dynamically). + */ virtual void destroy (void); - // Call this to free up dynamically allocated <Svc_Handlers> - // (otherwise you will get memory leaks). In general, you should - // call this method rather than <delete> since this method knows - // whether or not the object was allocated dynamically, and can act - // accordingly (i.e., deleting it if it was allocated dynamically). + /** + * This really should be private so that users are forced to call + * <destroy>. Unfortunately, the C++ standard doesn't allow there + * to be a public new and a private delete. It is a bad idea to + * call this method directly, so use <destroy> instead, unless you + * know for sure that you've allocated the object dynamically. + */ void operator delete (void *); - // This really should be private so that users are forced to call - // <destroy>. Unfortunately, the C++ standard doesn't allow there - // to be a public new and a private delete. It is a bad idea to - // call this method directly, so use <destroy> instead, unless you - // know for sure that you've allocated the object dynamically. #if !defined (ACE_LACKS_PLACEMENT_OPERATOR_DELETE) + /** + * This operator is necessary to complement the class-specific + * operator new above. Unfortunately, it's not portable to all C++ + * compilers... + */ void operator delete (void *, void *); - // This operator is necessary to complement the class-specific - // operator new above. Unfortunately, it's not portable to all C++ - // compilers... #endif /* ACE_LACKS_PLACEMENT_OPERATOR_DELETE */ + /// Close down the descriptor and unregister from the Reactor void shutdown (void); - // Close down the descriptor and unregister from the Reactor + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. public: @@ -170,108 +187,116 @@ public: // = Accessors to set/get the connection recycler. + /// Set the recycler and the <recycling_act> that is used during + /// purging and caching. virtual void recycler (ACE_Connection_Recycling_Strategy *recycler, const void *recycling_act); - // Set the recycler and the <recycling_act> that is used during - // purging and caching. + /// Get the recycler. virtual ACE_Connection_Recycling_Strategy *recycler (void) const; - // Get the recycler. + /// Get the recycling act. virtual const void *recycling_act (void) const; - // Get the recycling act. + /** + * Upcall made by the recycler when it is about to recycle the + * connection. This gives the object a chance to prepare itself for + * recycling. Return 0 if the object is ready for recycling, -1 on + * failures. + */ virtual int recycle (void * = 0); - // Upcall made by the recycler when it is about to recycle the - // connection. This gives the object a chance to prepare itself for - // recycling. Return 0 if the object is ready for recycling, -1 on - // failures. protected: + /// Maintain connection with client. ACE_PEER_STREAM peer_; - // Maintain connection with client. + /// Have we been dynamically created? int dynamic_; - // Have we been dynamically created? + /// Keeps track of whether we are in the process of closing (required + /// to avoid circular calls to <handle_close>). char closing_; - // Keeps track of whether we are in the process of closing (required - // to avoid circular calls to <handle_close>). + /// Pointer to the connection recycler. ACE_Connection_Recycling_Strategy *recycler_; - // Pointer to the connection recycler. + /// Asynchronous Completion Token (ACT) to be used to when talking to + /// the recycler. const void *recycling_act_; - // Asynchronous Completion Token (ACT) to be used to when talking to - // the recycler. }; +/** + * @class ACE_Buffered_Svc_Handler + * + * @brief Defines the interface for a service that exchanges data with + * its connected peer and supports buffering. + * + * The buffering feature makes it possible to queue up + * <ACE_Message_Blocks> in an <ACE_Message_Queue> until (1) the + * queue is "full" or (2) a period of time elapses, at which + * point the queue is "flushed" via <sendv_n> to the peer. + */ template <ACE_PEER_STREAM_1, ACE_SYNCH_DECL> class ACE_Buffered_Svc_Handler : public ACE_Svc_Handler<ACE_PEER_STREAM_2, ACE_SYNCH_USE> { - // = TITLE - // Defines the interface for a service that exchanges data with - // its connected peer and supports buffering. - // - // = DESCRIPTION - // The buffering feature makes it possible to queue up - // <ACE_Message_Blocks> in an <ACE_Message_Queue> until (1) the - // queue is "full" or (2) a period of time elapses, at which - // point the queue is "flushed" via <sendv_n> to the peer. public: // = Initialization and termination methods. + /** + * Constructor initializes the <thr_mgr> and <mq> by passing them + * down to the <ACE_Task> base class. The <reactor> is passed to + * the <ACE_Event_Handler>. The <max_buffer_size> and + * <relative_timeout> are used to determine at what point to flush + * the <mq>. By default, there's no buffering at all. The + * <relative_timeout> value is interpreted to be in a unit that's + * relative to the current time returned by <ACE_OS::gettimeofday>. + */ ACE_Buffered_Svc_Handler (ACE_Thread_Manager *thr_mgr = 0, ACE_Message_Queue<ACE_SYNCH_USE> *mq = 0, ACE_Reactor *reactor = ACE_Reactor::instance (), size_t max_buffer_size = 0, ACE_Time_Value *relative_timeout = 0); - // Constructor initializes the <thr_mgr> and <mq> by passing them - // down to the <ACE_Task> base class. The <reactor> is passed to - // the <ACE_Event_Handler>. The <max_buffer_size> and - // <relative_timeout> are used to determine at what point to flush - // the <mq>. By default, there's no buffering at all. The - // <relative_timeout> value is interpreted to be in a unit that's - // relative to the current time returned by <ACE_OS::gettimeofday>. + /// Destructor, which calls <flush>. virtual ~ACE_Buffered_Svc_Handler (void); - // Destructor, which calls <flush>. + /** + * Insert the <ACE_Message_Block> chain rooted at <message_block> + * into the <ACE_Message_Queue> with the designated <timeout>. The + * <flush> method will be called if this <put> causes the number of + * bytes to exceed the maximum buffer size or if the timeout period + * has elapsed. + */ virtual int put (ACE_Message_Block *message_block, ACE_Time_Value *timeout = 0); - // Insert the <ACE_Message_Block> chain rooted at <message_block> - // into the <ACE_Message_Queue> with the designated <timeout>. The - // <flush> method will be called if this <put> causes the number of - // bytes to exceed the maximum buffer size or if the timeout period - // has elapsed. + /// Flush the <ACE_Message_Queue>, which writes all the queued + /// <ACE_Message_Block>s to the <PEER_STREAM>. virtual int flush (void); - // Flush the <ACE_Message_Queue>, which writes all the queued - // <ACE_Message_Block>s to the <PEER_STREAM>. + /// This method is not currently implemented -- this is where the + /// integration with the <Reactor> would occur. virtual int handle_timeout (const ACE_Time_Value &time, const void *); - // This method is not currently implemented -- this is where the - // integration with the <Reactor> would occur. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. protected: + /// Maximum size the <Message_Queue> can be before we have to flush + /// the buffer. size_t maximum_buffer_size_; - // Maximum size the <Message_Queue> can be before we have to flush - // the buffer. + /// Current size in bytes of the <Message_Queue> contents. size_t current_buffer_size_; - // Current size in bytes of the <Message_Queue> contents. + /// Timeout value used to control when the buffer is flushed. ACE_Time_Value next_timeout_; - // Timeout value used to control when the buffer is flushed. + /// Interval of the timeout. ACE_Time_Value interval_; - // Interval of the timeout. + /// Timeout pointer. ACE_Time_Value *timeoutp_; - // Timeout pointer. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/Synch.h b/ace/Synch.h index 87ca817eb93..6ad851c1c86 100644 --- a/ace/Synch.h +++ b/ace/Synch.h @@ -1,21 +1,18 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Synch.h -// -// = DESCRIPTION -// Wrappers for various synchronization routines. -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Synch.h + * + * $Id$ + * + * Wrappers for various synchronization routines. + * + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SYNCH_H #define ACE_SYNCH_H @@ -28,93 +25,114 @@ #endif /* ACE_LACKS_PRAGMA_ONCE */ // Forward declarations. +/** + * @class ACE_Time_Value; + template <class ACE_COND_MUTEX> class ACE_Condition; + */ class ACE_Time_Value; -// template <class ACE_COND_MUTEX> class ACE_Condition; +/** + * @class ACE_Lock + * + * @brief This is the abstract base class that contains the uniform + * locking API that is supported by all the ACE synchronization + * mechanisms. + * + * This class is typically used in conjunction with the + * <ACE_Lock_Adapter> in order to provide a polymorphic + * interface to the ACE synchronization mechanisms (e.g., + * <ACE_Mutex>, <ACE_Semaphore>, <ACE_RW_Mutex>, etc). Note that + * the reason that all of ACE doesn't use polymorphic locks is + * that (1) they add ~20% extra overhead for virtual function + * calls and (2) objects with virtual functions can't be placed + * into shared memory. + */ class ACE_Export ACE_Lock { - // = TITLE - // This is the abstract base class that contains the uniform - // locking API that is supported by all the ACE synchronization - // mechanisms. - // - // = DESCRIPTION - // This class is typically used in conjunction with the - // <ACE_Lock_Adapter> in order to provide a polymorphic - // interface to the ACE synchronization mechanisms (e.g., - // <ACE_Mutex>, <ACE_Semaphore>, <ACE_RW_Mutex>, etc). Note that - // the reason that all of ACE doesn't use polymorphic locks is - // that (1) they add ~20% extra overhead for virtual function - // calls and (2) objects with virtual functions can't be placed - // into shared memory. public: + /// CE needs a default ctor here. ACE_Lock (void); - // CE needs a default ctor here. + /// Noop virtual destructor virtual ~ACE_Lock (void); - // Noop virtual destructor + /** + * Explicitly destroy the lock. Note that only one thread should + * call this method since it doesn't protect against race + * conditions. + */ virtual int remove (void) = 0; - // Explicitly destroy the lock. Note that only one thread should - // call this method since it doesn't protect against race - // conditions. + /// Block the thread until the lock is acquired. Returns -1 on + /// failure. virtual int acquire (void) = 0; - // Block the thread until the lock is acquired. Returns -1 on - // failure. + /** + * Conditionally acquire the lock (i.e., won't block). Returns -1 + * on failure. If we "failed" because someone else already had the + * lock, <errno> is set to <EBUSY>. + */ virtual int tryacquire (void) = 0; - // Conditionally acquire the lock (i.e., won't block). Returns -1 - // on failure. If we "failed" because someone else already had the - // lock, <errno> is set to <EBUSY>. + /// Release the lock. Returns -1 on failure. virtual int release (void) = 0; - // Release the lock. Returns -1 on failure. + /** + * Block until the thread acquires a read lock. If the locking + * mechanism doesn't support read locks then this just calls + * <acquire>. Returns -1 on failure. + */ virtual int acquire_read (void) = 0; - // Block until the thread acquires a read lock. If the locking - // mechanism doesn't support read locks then this just calls - // <acquire>. Returns -1 on failure. + /** + * Block until the thread acquires a write lock. If the locking + * mechanism doesn't support read locks then this just calls + * <acquire>. Returns -1 on failure. + */ virtual int acquire_write (void) = 0; - // Block until the thread acquires a write lock. If the locking - // mechanism doesn't support read locks then this just calls - // <acquire>. Returns -1 on failure. + /** + * Conditionally acquire a read lock. If the locking mechanism + * doesn't support read locks then this just calls <acquire>. + * Returns -1 on failure. If we "failed" because someone else + * already had the lock, <errno> is set to <EBUSY>. + */ virtual int tryacquire_read (void) = 0; - // Conditionally acquire a read lock. If the locking mechanism - // doesn't support read locks then this just calls <acquire>. - // Returns -1 on failure. If we "failed" because someone else - // already had the lock, <errno> is set to <EBUSY>. + /** + * Conditionally acquire a write lock. If the locking mechanism + * doesn't support read locks then this just calls <acquire>. + * Returns -1 on failure. If we "failed" because someone else + * already had the lock, <errno> is set to <EBUSY>. + */ virtual int tryacquire_write (void) = 0; - // Conditionally acquire a write lock. If the locking mechanism - // doesn't support read locks then this just calls <acquire>. - // Returns -1 on failure. If we "failed" because someone else - // already had the lock, <errno> is set to <EBUSY>. + /** + * Conditionally try to upgrade a lock held for read to a write lock. + * If the locking mechanism doesn't support read locks then this just + * calls <acquire>. Returns 0 on success, -1 on failure. + */ virtual int tryacquire_write_upgrade (void) = 0; - // Conditionally try to upgrade a lock held for read to a write lock. - // If the locking mechanism doesn't support read locks then this just - // calls <acquire>. Returns 0 on success, -1 on failure. }; +/** + * @class ACE_Adaptive_Lock + * + * @brief An adaptive general locking class that defers the decision of + * lock type to run time. + * + * This class, as ACE_Lock, provide a set of general locking APIs. + * However, it defers our decision of what kind of lock to use + * to the run time and delegates all locking operations to the actual + * lock. Users must define a constructor in their subclass to + * initialize <lock_>. + */ class ACE_Export ACE_Adaptive_Lock : public ACE_Lock { - // = TITLE - // An adaptive general locking class that defers the decision of - // lock type to run time. - // - // = DESCRIPTION - // This class, as ACE_Lock, provide a set of general locking APIs. - // However, it defers our decision of what kind of lock to use - // to the run time and delegates all locking operations to the actual - // lock. Users must define a constructor in their subclass to - // initialize <lock_>. public: + /// You must also override the destructor function to match with how + /// you construct the underneath <lock_>. virtual ~ACE_Adaptive_Lock (void); - // You must also override the destructor function to match with how - // you construct the underneath <lock_>. // = Lock/unlock operations. @@ -130,111 +148,132 @@ public: void dump (void) const; protected: + /** + * Create and initialize create the actual lcok used in the class. + * The default constructor simply set the <lock_> to 0 (null). You + * must overwrite this method for this class to work. + */ ACE_Adaptive_Lock (void); - // Create and initialize create the actual lcok used in the class. - // The default constructor simply set the <lock_> to 0 (null). You - // must overwrite this method for this class to work. ACE_Lock *lock_; }; +/** + * @class ACE_Semaphore + * + * @brief Wrapper for Dijkstra style general semaphores. + */ class ACE_Export ACE_Semaphore { - // = TITLE - // Wrapper for Dijkstra style general semaphores. public: // = Initialization and termination. + /// Initialize the semaphore, with initial value of "count". ACE_Semaphore (u_int count = 1, // By default make this unlocked. int type = USYNC_THREAD, const ACE_TCHAR *name = 0, void * = 0, int max = 0x7fffffff); - // Initialize the semaphore, with initial value of "count". + /// Implicitly destroy the semaphore. ~ACE_Semaphore (void); - // Implicitly destroy the semaphore. + /** + * Explicitly destroy the semaphore. Note that only one thread + * should call this method since it doesn't protect against race + * conditions. + */ int remove (void); - // Explicitly destroy the semaphore. Note that only one thread - // should call this method since it doesn't protect against race - // conditions. + /// Block the thread until the semaphore count becomes + /// greater than 0, then decrement it. int acquire (void); - // Block the thread until the semaphore count becomes - // greater than 0, then decrement it. + /** + * Block the thread until <tv> times out or until the semaphore + * count becomes greater than 0 (at which point it is decremented). + * Note that <tv> is assumed to be in "absolute" rather than + * "relative" time. The value of <tv> is updated upon return to + * show the actual (absolute) acquisition time. + * + * NOTE: Solaris threads do not support timed semaphores. + * Therefore, if you're running on Solaris you might want to + * consider using the ACE POSIX pthreads implementation instead, + * which can be enabled by compiling ACE with + * -D_POSIX_PTHREAD_SEMANTICS. + */ int acquire (ACE_Time_Value &tv); - // Block the thread until <tv> times out or until the semaphore - // count becomes greater than 0 (at which point it is decremented). - // Note that <tv> is assumed to be in "absolute" rather than - // "relative" time. The value of <tv> is updated upon return to - // show the actual (absolute) acquisition time. - // - // NOTE: Solaris threads do not support timed semaphores. - // Therefore, if you're running on Solaris you might want to - // consider using the ACE POSIX pthreads implementation instead, - // which can be enabled by compiling ACE with - // -D_POSIX_PTHREAD_SEMANTICS. + /** + * Conditionally decrement the semaphore if count is greater than 0 + * (i.e., won't block). Returns -1 on failure. If we "failed" + * because someone else already had the lock, <errno> is set to + * <EBUSY>. + */ int tryacquire (void); - // Conditionally decrement the semaphore if count is greater than 0 - // (i.e., won't block). Returns -1 on failure. If we "failed" - // because someone else already had the lock, <errno> is set to - // <EBUSY>. + /// Increment the semaphore by 1, potentially unblocking a waiting + /// thread. int release (void); - // Increment the semaphore by 1, potentially unblocking a waiting - // thread. + /// Increment the semaphore by <release_count>, potentially + /// unblocking waiting threads. int release (size_t release_count); - // Increment the semaphore by <release_count>, potentially - // unblocking waiting threads. + /** + * Acquire semaphore ownership. This calls <acquire> and is only + * here to make the <ACE_Semaphore> interface consistent with the + * other synchronization APIs. + */ int acquire_read (void); - // Acquire semaphore ownership. This calls <acquire> and is only - // here to make the <ACE_Semaphore> interface consistent with the - // other synchronization APIs. + /** + * Acquire semaphore ownership. This calls <acquire> and is only + * here to make the <ACE_Semaphore> interface consistent with the + * other synchronization APIs. + */ int acquire_write (void); - // Acquire semaphore ownership. This calls <acquire> and is only - // here to make the <ACE_Semaphore> interface consistent with the - // other synchronization APIs. + /** + * Conditionally acquire semaphore (i.e., won't block). This calls + * <tryacquire> and is only here to make the <ACE_Semaphore> + * interface consistent with the other synchronization APIs. + * Returns -1 on failure. If we "failed" because someone else + * already had the lock, <errno> is set to <EBUSY>. + */ int tryacquire_read (void); - // Conditionally acquire semaphore (i.e., won't block). This calls - // <tryacquire> and is only here to make the <ACE_Semaphore> - // interface consistent with the other synchronization APIs. - // Returns -1 on failure. If we "failed" because someone else - // already had the lock, <errno> is set to <EBUSY>. + /** + * Conditionally acquire semaphore (i.e., won't block). This calls + * <tryacquire> and is only here to make the <ACE_Semaphore> + * interface consistent with the other synchronization APIs. + * Returns -1 on failure. If we "failed" because someone else + * already had the lock, <errno> is set to <EBUSY>. + */ int tryacquire_write (void); - // Conditionally acquire semaphore (i.e., won't block). This calls - // <tryacquire> and is only here to make the <ACE_Semaphore> - // interface consistent with the other synchronization APIs. - // Returns -1 on failure. If we "failed" because someone else - // already had the lock, <errno> is set to <EBUSY>. + /** + * This is only here to make the <ACE_Semaphore> + * interface consistent with the other synchronization APIs. + * Assumes the caller has already acquired the semaphore using one of + * the above calls, and returns 0 (success) always. + */ int tryacquire_write_upgrade (void); - // This is only here to make the <ACE_Semaphore> - // interface consistent with the other synchronization APIs. - // Assumes the caller has already acquired the semaphore using one of - // the above calls, and returns 0 (success) always. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /// Return the underlying lock. const ACE_sema_t &lock (void) const; - // Return the underlying lock. protected: ACE_sema_t semaphore_; + /// Keeps track of whether <remove> has been called yet to avoid + /// multiple <remove> calls, e.g., explicitly and implicitly in the int removed_; - // Keeps track of whether <remove> has been called yet to avoid - // multiple <remove> calls, e.g., explicitly and implicitly in the // destructor. This flag isn't protected by a lock, so make sure // that you don't have multiple threads simultaneously calling // <remove> on the same object, which is a bad idea anyway... @@ -245,11 +284,14 @@ private: ACE_Semaphore (const ACE_Semaphore &); }; +/** + * @class ACE_Null_Semaphore + * + * @brief Implement a do nothing <ACE_Semaphore>, i.e., all the methods are + * no ops. + */ class ACE_Export ACE_Null_Semaphore { - // = TITLE - // Implement a do nothing <ACE_Semaphore>, i.e., all the methods are - // no ops. public: ACE_Null_Semaphore (u_int count = 1, // By default make this unlocked. int type = USYNC_THREAD, @@ -270,89 +312,101 @@ public: int acquire_read (void); int tryacquire_read (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; +/** + * @class ACE_RW_Mutex + * + * @brief Wrapper for readers/writer locks. + * + * These are most useful for applications that have many more + * parallel readers than writers... + */ class ACE_Export ACE_RW_Mutex { - // = TITLE - // Wrapper for readers/writer locks. - // - // = DESCRIPTION - // These are most useful for applications that have many more - // parallel readers than writers... public: + /// Initialize a readers/writer lock. ACE_RW_Mutex (int type = USYNC_THREAD, const ACE_TCHAR *name = 0, void *arg = 0); - // Initialize a readers/writer lock. + /// Implicitly destroy a readers/writer lock ~ACE_RW_Mutex (void); - // Implicitly destroy a readers/writer lock + /** + * Explicitly destroy a readers/writer lock. Note that only one + * thread should call this method since it doesn't protect against + * race conditions. + */ int remove (void); - // Explicitly destroy a readers/writer lock. Note that only one - // thread should call this method since it doesn't protect against - // race conditions. + /// Acquire a read lock, but block if a writer hold the lock. int acquire_read (void); - // Acquire a read lock, but block if a writer hold the lock. + /// Acquire a write lock, but block if any readers or a + /// writer hold the lock. int acquire_write (void); - // Acquire a write lock, but block if any readers or a - // writer hold the lock. + /** + * Conditionally acquire a read lock (i.e., won't block). Returns + * -1 on failure. If we "failed" because someone else already had + * the lock, <errno> is set to <EBUSY>. + */ int tryacquire_read (void); - // Conditionally acquire a read lock (i.e., won't block). Returns - // -1 on failure. If we "failed" because someone else already had - // the lock, <errno> is set to <EBUSY>. + /// Conditionally acquire a write lock (i.e., won't block). int tryacquire_write (void); - // Conditionally acquire a write lock (i.e., won't block). + /** + * Conditionally upgrade a read lock to a write lock. This only + * works if there are no other readers present, in which case the + * method returns 0. Otherwise, the method returns -1 and sets + * <errno> to <EBUSY>. Note that the caller of this method *must* + * already possess this lock as a read lock (but this condition is + * not checked by the current implementation). + */ int tryacquire_write_upgrade (void); - // Conditionally upgrade a read lock to a write lock. This only - // works if there are no other readers present, in which case the - // method returns 0. Otherwise, the method returns -1 and sets - // <errno> to <EBUSY>. Note that the caller of this method *must* - // already possess this lock as a read lock (but this condition is - // not checked by the current implementation). + /** + * Note, for interface uniformity with other synchronization + * wrappers we include the <acquire> method. This is implemented as + * a write-lock to safe... + */ int acquire (void); - // Note, for interface uniformity with other synchronization - // wrappers we include the <acquire> method. This is implemented as - // a write-lock to safe... + /** + * Note, for interface uniformity with other synchronization + * wrappers we include the <tryacquire> method. This is implemented + * as a write-lock to be safe... Returns -1 on failure. If we + * "failed" because someone else already had the lock, <errno> is + * set to <EBUSY>. + */ int tryacquire (void); - // Note, for interface uniformity with other synchronization - // wrappers we include the <tryacquire> method. This is implemented - // as a write-lock to be safe... Returns -1 on failure. If we - // "failed" because someone else already had the lock, <errno> is - // set to <EBUSY>. + /// Unlock a readers/writer lock. int release (void); - // Unlock a readers/writer lock. + /// Return the underlying lock. const ACE_rwlock_t &lock (void) const; - // Return the underlying lock. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Readers/writer lock. ACE_rwlock_t lock_; - // Readers/writer lock. + /// Keeps track of whether <remove> has been called yet to avoid + /// multiple <remove> calls, e.g., explicitly and implicitly in the int removed_; - // Keeps track of whether <remove> has been called yet to avoid - // multiple <remove> calls, e.g., explicitly and implicitly in the // destructor. This flag isn't protected by a lock, so make sure // that you don't have multiple threads simultaneously calling // <remove> on the same object, which is a bad idea anyway... @@ -362,92 +416,111 @@ private: ACE_RW_Mutex (const ACE_RW_Mutex &); }; +/** + * @class ACE_Mutex + * + * @brief <ACE_Mutex> wrapper (valid in same process or across + * processes (depending on TYPE flag)). + */ class ACE_Export ACE_Mutex { - // = TITLE - // <ACE_Mutex> wrapper (valid in same process or across - // processes (depending on TYPE flag)). public: + /// Initialize the mutex. ACE_Mutex (int type = USYNC_THREAD, const ACE_TCHAR *name = 0, ACE_mutexattr_t *arg = 0); - // Initialize the mutex. + /// Implicitly destroy the mutex. ~ACE_Mutex (void); - // Implicitly destroy the mutex. + /** + * Explicitly destroy the mutex. Note that only one thread should + * call this method since it doesn't protect against race + * conditions. + */ int remove (void); - // Explicitly destroy the mutex. Note that only one thread should - // call this method since it doesn't protect against race - // conditions. + /// Acquire lock ownership (wait on queue if necessary). int acquire (void); - // Acquire lock ownership (wait on queue if necessary). + /** + * Conditionally acquire lock (i.e., don't wait on queue). Returns + * -1 on failure. If we "failed" because someone else already had + * the lock, <errno> is set to <EBUSY>. + */ int tryacquire (void); - // Conditionally acquire lock (i.e., don't wait on queue). Returns - // -1 on failure. If we "failed" because someone else already had - // the lock, <errno> is set to <EBUSY>. + /// Release lock and unblock a thread at head of queue. int release (void); - // Release lock and unblock a thread at head of queue. + /** + * Acquire mutex ownership. This calls <acquire> and is only + * here to make the <ACE_Mutex> interface consistent with the + * other synchronization APIs. + */ int acquire_read (void); - // Acquire mutex ownership. This calls <acquire> and is only - // here to make the <ACE_Mutex> interface consistent with the - // other synchronization APIs. + /** + * Acquire mutex ownership. This calls <acquire> and is only + * here to make the <ACE_Mutex> interface consistent with the + * other synchronization APIs. + */ int acquire_write (void); - // Acquire mutex ownership. This calls <acquire> and is only - // here to make the <ACE_Mutex> interface consistent with the - // other synchronization APIs. + /** + * Conditionally acquire mutex (i.e., won't block). This calls + * <tryacquire> and is only here to make the <ACE_Mutex> interface + * consistent with the other synchronization APIs. Returns -1 on + * failure. If we "failed" because someone else already had the + * lock, <errno> is set to <EBUSY>. + */ int tryacquire_read (void); - // Conditionally acquire mutex (i.e., won't block). This calls - // <tryacquire> and is only here to make the <ACE_Mutex> interface - // consistent with the other synchronization APIs. Returns -1 on - // failure. If we "failed" because someone else already had the - // lock, <errno> is set to <EBUSY>. + /** + * Conditionally acquire mutex (i.e., won't block). This calls + * <tryacquire> and is only here to make the <ACE_Mutex> interface + * consistent with the other synchronization APIs. Returns -1 on + * failure. If we "failed" because someone else already had the + * lock, <errno> is set to <EBUSY>. + */ int tryacquire_write (void); - // Conditionally acquire mutex (i.e., won't block). This calls - // <tryacquire> and is only here to make the <ACE_Mutex> interface - // consistent with the other synchronization APIs. Returns -1 on - // failure. If we "failed" because someone else already had the - // lock, <errno> is set to <EBUSY>. + /** + * This is only here for consistency with the other synchronization + * APIs and usability with Lock adapters. Assumes the caller already has + * acquired the mutex and returns 0 in all cases. + */ int tryacquire_write_upgrade (void); - // This is only here for consistency with the other synchronization - // APIs and usability with Lock adapters. Assumes the caller already has - // acquired the mutex and returns 0 in all cases. + /// Return the underlying mutex. const ACE_mutex_t &lock (void) const; - // Return the underlying mutex. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. // = This should be protected but some C++ compilers complain... public: #if defined (CHORUS) + /// This lock resides in shared memory. ACE_mutex_t *process_lock_; - // This lock resides in shared memory. + /** + * Remember the name of the mutex if we created it so we can unlink + * it when we go away (only the actor that initialized the memory + * can destroy it). + */ const ACE_TCHAR *lockname_; - // Remember the name of the mutex if we created it so we can unlink - // it when we go away (only the actor that initialized the memory - // can destroy it). #endif /* CHORUS */ + /// Mutex type supported by the OS. ACE_mutex_t lock_; - // Mutex type supported by the OS. + /// Keeps track of whether <remove> has been called yet to avoid + /// multiple <remove> calls, e.g., explicitly and implicitly in the int removed_; - // Keeps track of whether <remove> has been called yet to avoid - // multiple <remove> calls, e.g., explicitly and implicitly in the // destructor. This flag isn't protected by a lock, so make sure // that you don't have multiple threads simultaneously calling // <remove> on the same object, which is a bad idea anyway... @@ -458,28 +531,31 @@ private: ACE_Mutex (const ACE_Mutex &); }; +/** + * @class ACE_Null_Barrier + * + * @brief Implements "NULL barrier synchronization". + */ class ACE_Export ACE_Null_Barrier { - // = TITLE - // Implements "NULL barrier synchronization". public: + /// Initialize the barrier to synchronize <count> threads. ACE_Null_Barrier (u_int, const char * = 0, void * = 0); - // Initialize the barrier to synchronize <count> threads. + /// Default dtor. ~ACE_Null_Barrier (void); - // Default dtor. + /// Block the caller until all <count> threads have called <wait> and + /// then allow all the caller threads to continue in parallel. int wait (void); - // Block the caller until all <count> threads have called <wait> and - // then allow all the caller threads to continue in parallel. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: // = Prevent assignment and initialization. @@ -487,11 +563,14 @@ private: ACE_Null_Barrier (const ACE_Null_Barrier &); }; +/** + * @class ACE_Null_Mutex + * + * @brief Implement a do nothing <ACE_Mutex>, i.e., all the methods are + * no ops. + */ class ACE_Export ACE_Null_Mutex { - // = TITLE - // Implement a do nothing <ACE_Mutex>, i.e., all the methods are - // no ops. public: ACE_Null_Mutex (const ACE_TCHAR * = 0); ~ACE_Null_Mutex (void); @@ -506,11 +585,11 @@ public: int acquire_read (void); int tryacquire_read (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; class ACE_Export ACE_Noop_Token : public ACE_Null_Mutex @@ -518,19 +597,22 @@ class ACE_Export ACE_Noop_Token : public ACE_Null_Mutex public: int renew (int = 0, ACE_Time_Value * =0); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Null_Condition + * + * @brief Implement a do nothing <ACE_Condition> variable wrapper, + * i.e., all methods are no ops. This class is necessary since + * some C++ compilers are *very* lame... + */ class ACE_Export ACE_Null_Condition { - // = TITLE - // Implement a do nothing <ACE_Condition> variable wrapper, - // i.e., all methods are no ops. This class is necessary since - // some C++ compilers are *very* lame... public: ACE_Null_Condition (const ACE_Null_Mutex &m, const ACE_TCHAR * = 0, @@ -542,8 +624,8 @@ public: int broadcast (void); ACE_Null_Mutex &mutex (void); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. @@ -558,16 +640,18 @@ private: }; #if defined (ACE_USES_OBSOLETE_GUARD_CLASSES) +/** + * @class ACE_Null_Mutex_Guard + * + * @brief This data structure is meant to be used within a method or + * function... It performs automatic aquisition and release of + * an ACE_Null_Mutex. + * + * This class is obsolete and should be replaced by + * ACE_Guard<ACE_Null_Mutex>. + */ class ACE_Export ACE_Null_Mutex_Guard { - // = TITLE - // This data structure is meant to be used within a method or - // function... It performs automatic aquisition and release of - // an ACE_Null_Mutex. - // - // = DESCRIPTION - // This class is obsolete and should be replaced by - // ACE_Guard<ACE_Null_Mutex>. public: ACE_Null_Mutex_Guard (ACE_Null_Mutex &); ~ACE_Null_Mutex_Guard (void); @@ -585,120 +669,133 @@ private: }; #endif /* ACE_USES_OBSOLETE_GUARD_CLASSES */ +/** + * @class ACE_TSS_Adapter + * + * @brief This class encapsulates a TSS object and its associated + * C++ destructor function. It is used by the ACE_TSS... + * methods (in Synch_T.cpp) in order to allow an extern + * "C" cleanup routine to be used. Needed by the "frigging" + * MVS C++ compiler. + * + * Objects of this class are stored in thread specific + * storage. ts_obj_ points to the "real" object and + * func_ is a pointer to the C++ cleanup function for ts_obj_. + */ class ACE_Export ACE_TSS_Adapter { - // = TITLE - // This class encapsulates a TSS object and its associated - // C++ destructor function. It is used by the ACE_TSS... - // methods (in Synch_T.cpp) in order to allow an extern - // "C" cleanup routine to be used. Needed by the "frigging" - // MVS C++ compiler. - // - // = DESCRIPTION - // Objects of this class are stored in thread specific - // storage. ts_obj_ points to the "real" object and - // func_ is a pointer to the C++ cleanup function for ts_obj_. - // public: + /// Initialize the adapter. ACE_TSS_Adapter (void *object, ACE_THR_DEST f); - // Initialize the adapter. + /// Default dtor. ~ACE_TSS_Adapter (void); - // Default dtor. + /// Perform the cleanup operation. void cleanup (void); - // Perform the cleanup operation. //private: + /// The real TS object. void *ts_obj_; - // The real TS object. + /// The real cleanup routine for ts_obj; ACE_THR_DEST func_; - // The real cleanup routine for ts_obj; }; +/** + * @class ACE_Event + * + * @brief A wrapper around the Win32 event locking mechanism. + * + * Portable implementation of an Event mechanism, which is + * native to Win32, but must be emulated on UNIX. Note that + * this only provides <USYNC_PROCESS> support on Win32 machines. + */ class ACE_Export ACE_Event { - // = TITLE - // A wrapper around the Win32 event locking mechanism. - // - // = DESCRIPTION - // Portable implementation of an Event mechanism, which is - // native to Win32, but must be emulated on UNIX. Note that - // this only provides <USYNC_PROCESS> support on Win32 machines. public: + /// Constructor which will create event. ACE_Event (int manual_reset = 0, int initial_state = 0, int type = USYNC_THREAD, const ACE_TCHAR *name = 0, void *arg = 0); - // Constructor which will create event. + /// Implicitly destroy the event variable. ~ACE_Event (void); - // Implicitly destroy the event variable. + /** + * Explicitly destroy the event variable. Note that only one thread + * should call this method since it doesn't protect against race + * conditions. + */ int remove (void); - // Explicitly destroy the event variable. Note that only one thread - // should call this method since it doesn't protect against race - // conditions. + /// Underlying handle to event. ACE_event_t handle (void) const; - // Underlying handle to event. + /** + * Set the underlying handle to event. Note that this method assumes + * ownership of the <handle> and will close it down in <remove>. If + * you want the <handle> to stay open when <remove> is called make + * sure to call <dup> on the <handle> before closing it. You are + * responsible for the closing the existing <handle> before + * overwriting it. + */ void handle (ACE_event_t new_handle); - // Set the underlying handle to event. Note that this method assumes - // ownership of the <handle> and will close it down in <remove>. If - // you want the <handle> to stay open when <remove> is called make - // sure to call <dup> on the <handle> before closing it. You are - // responsible for the closing the existing <handle> before - // overwriting it. + /** + * if MANUAL reset + * sleep till the event becomes signaled + * event remains signaled after wait() completes. + * else AUTO reset + * sleep till the event becomes signaled + * event resets wait() completes. + */ int wait (void); - // if MANUAL reset - // sleep till the event becomes signaled - // event remains signaled after wait() completes. - // else AUTO reset - // sleep till the event becomes signaled - // event resets wait() completes. + /// Same as wait() above, but this one can be timed + /// <abstime> is absolute time-of-day. int wait (const ACE_Time_Value *abstime); - // Same as wait() above, but this one can be timed - // <abstime> is absolute time-of-day. + /** + * if MANUAL reset + * wake up all waiting threads + * set to signaled state + * else AUTO reset + * if no thread is waiting, set to signaled state + * if thread(s) are waiting, wake up one waiting thread and + * reset event + */ int signal (void); - // if MANUAL reset - // wake up all waiting threads - // set to signaled state - // else AUTO reset - // if no thread is waiting, set to signaled state - // if thread(s) are waiting, wake up one waiting thread and - // reset event + /** + * if MANUAL reset + * wakeup all waiting threads and + * reset event + * else AUTO reset + * wakeup one waiting thread (if present) and + * reset event + */ int pulse (void); - // if MANUAL reset - // wakeup all waiting threads and - // reset event - // else AUTO reset - // wakeup one waiting thread (if present) and - // reset event + /// Set to nonsignaled state. int reset (void); - // Set to nonsignaled state. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks protected: + /// The underlying handle. ACE_event_t handle_; - // The underlying handle. + /// Keeps track of whether <remove> has been called yet to avoid + /// multiple <remove> calls, e.g., explicitly and implicitly in the int removed_; - // Keeps track of whether <remove> has been called yet to avoid - // multiple <remove> calls, e.g., explicitly and implicitly in the // destructor. This flag isn't protected by a lock, so make sure // that you don't have multiple threads simultaneously calling // <remove> on the same object, which is a bad idea anyway... @@ -709,80 +806,87 @@ private: const ACE_Event &operator= (const ACE_Event &rhs); }; +/** + * @class ACE_Manual_Event + * + * @brief Manual Events. + * + * Specialization of Event mechanism which wakes up all waiting + * threads on <signal>. Note that this only provides + * <USYNC_PROCESS> support on Win32 machines. + */ class ACE_Export ACE_Manual_Event : public ACE_Event { - // = TITLE - // Manual Events. - // - // = DESCRIPTION - // Specialization of Event mechanism which wakes up all waiting - // threads on <signal>. Note that this only provides - // <USYNC_PROCESS> support on Win32 machines. public: + /// constructor which will create manual event ACE_Manual_Event (int initial_state = 0, int type = USYNC_THREAD, const char *name = 0, void *arg = 0); - // constructor which will create manual event #if defined (ACE_HAS_WCHAR) + /// constructor which will create manual event (wchar_t version) ACE_Manual_Event (int initial_state, int type, const wchar_t *name, void *arg = 0); - // constructor which will create manual event (wchar_t version) #endif /* ACE_HAS_WCHAR */ + /// Default dtor. ~ACE_Manual_Event (void); - // Default dtor. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks }; +/** + * @class ACE_Auto_Event + * + * @brief Auto Events. + * + * Specialization of Event mechanism which wakes up one waiting + * thread on <signal>. Note that this only provides + * <USYNC_PROCESS> support on Win32 machines. + */ class ACE_Export ACE_Auto_Event : public ACE_Event { - // = TITLE - // Auto Events. - // - // = DESCRIPTION - // Specialization of Event mechanism which wakes up one waiting - // thread on <signal>. Note that this only provides - // <USYNC_PROCESS> support on Win32 machines. public: + /// constructor which will create auto event ACE_Auto_Event (int initial_state = 0, int type = USYNC_THREAD, const char *name = 0, void *arg = 0); - // constructor which will create auto event #if defined (ACE_HAS_WCHAR) + /// constructor which will create auto event (wchar_t version) ACE_Auto_Event (int initial_state, int type, const wchar_t *name, void *arg = 0); - // constructor which will create auto event (wchar_t version) #endif /* ACE_HAS_WCHAR */ + /// Default dtor. ~ACE_Auto_Event (void); - // Default dtor. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks }; // ACE platform supports some form of threading. #if !defined (ACE_HAS_THREADS) +/** + * @class ACE_Barrier + * + * @brief This is a no-op to make ACE "syntactically consistent." + */ class ACE_Barrier { - // = TITLE - // This is a no-op to make ACE "syntactically consistent." public: ACE_Barrier (u_int, const ACE_TCHAR * = 0, void * = 0) {} ~ACE_Barrier (void) {} @@ -790,93 +894,108 @@ public: void dump (void) const {} }; #else + /** + * @class ACE_Thread_Mutex + * + * @brief ACE_Thread_Mutex wrapper (only valid for threads in the same + * process). + * + * This implementation is optimized for locking threads that are + * in the same process. It maps to <CRITICAL_SECTION>s on NT + * and <ACE_mutex_t> with <type> set to <USYNC_THREAD> on UNIX. + * ACE_Thread_Mutex is recursive on some platforms (like + * Win32). However, on most platforms (like Solaris) it is not + * recursive. To be totally safe and portable, developers + * should use <ACE_Recursive_Thread_Mutex> when they need a + * recursive mutex. + */ class ACE_Export ACE_Thread_Mutex { - // = TITLE - // ACE_Thread_Mutex wrapper (only valid for threads in the same - // process). - // - // = DESCRIPTION - // This implementation is optimized for locking threads that are - // in the same process. It maps to <CRITICAL_SECTION>s on NT - // and <ACE_mutex_t> with <type> set to <USYNC_THREAD> on UNIX. - // - // ACE_Thread_Mutex is recursive on some platforms (like - // Win32). However, on most platforms (like Solaris) it is not - // recursive. To be totally safe and portable, developers - // should use <ACE_Recursive_Thread_Mutex> when they need a - // recursive mutex. friend class ACE_Condition_Thread_Mutex; public: + /// Constructor. ACE_Thread_Mutex (const ACE_TCHAR *name = 0, ACE_mutexattr_t *attributes = 0); - // Constructor. + /// Implicitly destroy the mutex. ~ACE_Thread_Mutex (void); - // Implicitly destroy the mutex. + /** + * Explicitly destroy the mutex. Note that only one thread should + * call this method since it doesn't protect against race + * conditions. + */ int remove (void); - // Explicitly destroy the mutex. Note that only one thread should - // call this method since it doesn't protect against race - // conditions. + /// Acquire lock ownership (wait on queue if necessary). int acquire (void); - // Acquire lock ownership (wait on queue if necessary). + /** + * Conditionally acquire lock (i.e., don't wait on queue). Returns + * -1 on failure. If we "failed" because someone else already had + * the lock, <errno> is set to <EBUSY>. + */ int tryacquire (void); - // Conditionally acquire lock (i.e., don't wait on queue). Returns - // -1 on failure. If we "failed" because someone else already had - // the lock, <errno> is set to <EBUSY>. + /// Release lock and unblock a thread at head of queue. int release (void); - // Release lock and unblock a thread at head of queue. + /** + * Acquire mutex ownership. This calls <acquire> and is only here + * to make the <ACE_Thread_Mutex> interface consistent with the + * other synchronization APIs. + */ int acquire_read (void); - // Acquire mutex ownership. This calls <acquire> and is only here - // to make the <ACE_Thread_Mutex> interface consistent with the - // other synchronization APIs. + /** + * Acquire mutex ownership. This calls <acquire> and is only here + * to make the <ACE_Thread_Mutex> interface consistent with the + * other synchronization APIs. + */ int acquire_write (void); - // Acquire mutex ownership. This calls <acquire> and is only here - // to make the <ACE_Thread_Mutex> interface consistent with the - // other synchronization APIs. + /** + * Conditionally acquire mutex (i.e., won't block). This calls + * <tryacquire> and is only here to make the <ACE_Thread_Mutex> + * interface consistent with the other synchronization APIs. + * Returns -1 on failure. If we "failed" because someone else + * already had the lock, <errno> is set to <EBUSY>. + */ int tryacquire_read (void); - // Conditionally acquire mutex (i.e., won't block). This calls - // <tryacquire> and is only here to make the <ACE_Thread_Mutex> - // interface consistent with the other synchronization APIs. - // Returns -1 on failure. If we "failed" because someone else - // already had the lock, <errno> is set to <EBUSY>. + /** + * Conditionally acquire mutex (i.e., won't block). This calls + * <tryacquire> and is only here to make the <ACE_Thread_Mutex> + * interface consistent with the other synchronization APIs. + * Returns -1 on failure. If we "failed" because someone else + * already had the lock, <errno> is set to <EBUSY>. + */ int tryacquire_write (void); - // Conditionally acquire mutex (i.e., won't block). This calls - // <tryacquire> and is only here to make the <ACE_Thread_Mutex> - // interface consistent with the other synchronization APIs. - // Returns -1 on failure. If we "failed" because someone else - // already had the lock, <errno> is set to <EBUSY>. + /** + * This is only here to make the <ACE_Thread_Mutex> + * interface consistent with the other synchronization APIs. + * Assumes the caller has already acquired the mutex using one of + * the above calls, and returns 0 (success) always. + */ int tryacquire_write_upgrade (void); - // This is only here to make the <ACE_Thread_Mutex> - // interface consistent with the other synchronization APIs. - // Assumes the caller has already acquired the mutex using one of - // the above calls, and returns 0 (success) always. + /// Return the underlying mutex. const ACE_thread_mutex_t &lock (void) const; - // Return the underlying mutex. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. // protected: + /// Mutex type that supports single-process locking efficiently. ACE_thread_mutex_t lock_; - // Mutex type that supports single-process locking efficiently. + /// Keeps track of whether <remove> has been called yet to avoid + /// multiple <remove> calls, e.g., explicitly and implicitly in the int removed_; - // Keeps track of whether <remove> has been called yet to avoid - // multiple <remove> calls, e.g., explicitly and implicitly in the // destructor. This flag isn't protected by a lock, so make sure // that you don't have multiple threads simultaneously calling // <remove> on the same object, which is a bad idea anyway... @@ -888,55 +1007,61 @@ private: }; #if defined (ACE_USES_OBSOLETE_GUARD_CLASSES) +/** + * @class ACE_Thread_Mutex_Guard + * + * @brief This data structure is meant to be used within a method or + * function... It performs automatic aquisition and release of + * an <ACE_Thread_Mutex>. + * + * This class is obsolete and should be replaced by + * ACE_Guard<ACE_Thread_Mutex>. + */ class ACE_Export ACE_Thread_Mutex_Guard { - // = TITLE - // This data structure is meant to be used within a method or - // function... It performs automatic aquisition and release of - // an <ACE_Thread_Mutex>. - // - // = DESCRIPTION - // This class is obsolete and should be replaced by - // ACE_Guard<ACE_Thread_Mutex>. public: + /// Implicitly and automatically acquire the lock. ACE_Thread_Mutex_Guard (ACE_Thread_Mutex &m, int block = 1); - // Implicitly and automatically acquire the lock. + /// Implicitly release the lock. ~ACE_Thread_Mutex_Guard (void); - // Implicitly release the lock. + /// 1 if locked, 0 if couldn't acquire the lock (errno will contain + /// the reason for this). int locked (void); - // 1 if locked, 0 if couldn't acquire the lock (errno will contain - // the reason for this). + /** + * Explicitly release the lock. Note that only one thread should + * call this method since it doesn't protect against race + * conditions. + */ int remove (void); - // Explicitly release the lock. Note that only one thread should - // call this method since it doesn't protect against race - // conditions. + /// Explicitly acquire the lock. int acquire (void); - // Explicitly acquire the lock. + /** + * Conditionally acquire the lock (i.e., won't block). Returns -1 + * on failure. If we "failed" because someone else already had the + * lock, <errno> is set to <EBUSY>. + */ int tryacquire (void); - // Conditionally acquire the lock (i.e., won't block). Returns -1 - // on failure. If we "failed" because someone else already had the - // lock, <errno> is set to <EBUSY>. + /// Explicitly release the lock. int release (void); - // Explicitly release the lock. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Reference to the mutex. ACE_Thread_Mutex &lock_; - // Reference to the mutex. + /// Keeps track of whether we acquired the lock or failed. int owner_; - // Keeps track of whether we acquired the lock or failed. private: // = Prevent assignment and initialization. @@ -948,17 +1073,17 @@ private: class ACE_Export ACE_Condition_Attributes { public: + /// Constructor ACE_Condition_Attributes (int type = ACE_DEFAULT_SYNCH_TYPE); - // Constructor + /// Destructor ~ACE_Condition_Attributes (void); - // Destructor private: friend class ACE_Condition_Thread_Mutex; + /// The attributes ACE_condattr_t attributes_; - // The attributes private: // = Prevent assignment and initialization. @@ -966,89 +1091,96 @@ private: ACE_Condition_Attributes (const ACE_Condition_Attributes &); }; +/** + * @class ACE_Condition_Thread_Mutex + * + * @brief ACE_Condition variable wrapper written using ACE_Mutexes This + * allows threads to block until shared data changes state. + * A condition variable enables threads to atomically block and + * test the condition under the protection of a mutual exclu- + * sion lock (mutex) until the condition is satisfied. That is, + * the mutex must have been held by the thread before calling + * wait or signal on the condition. If the condition is false, + * a thread blocks on a condition variable and atomically + * releases the mutex that is waiting for the condition to + * change. If another thread changes the condition, it may wake + * up waiting threads by signaling the associated condition + * variable. The waiting threads, upon awakening, reacquire the + * mutex and re-evaluate the condition. + * + * This should be an instantiation of ACE_Condition but problems + * with compilers precludes this... + */ class ACE_Export ACE_Condition_Thread_Mutex { - // = TITLE - // ACE_Condition variable wrapper written using ACE_Mutexes This - // allows threads to block until shared data changes state. - // - // A condition variable enables threads to atomically block and - // test the condition under the protection of a mutual exclu- - // sion lock (mutex) until the condition is satisfied. That is, - // the mutex must have been held by the thread before calling - // wait or signal on the condition. If the condition is false, - // a thread blocks on a condition variable and atomically - // releases the mutex that is waiting for the condition to - // change. If another thread changes the condition, it may wake - // up waiting threads by signaling the associated condition - // variable. The waiting threads, upon awakening, reacquire the - // mutex and re-evaluate the condition. - // - // = DESCRIPTION - // This should be an instantiation of ACE_Condition but problems - // with compilers precludes this... public: + /// Initialize the condition variable. ACE_Condition_Thread_Mutex (const ACE_Thread_Mutex &m, const ACE_TCHAR *name = 0, void *arg = 0); - // Initialize the condition variable. + /// Initialize the condition variable. ACE_Condition_Thread_Mutex (const ACE_Thread_Mutex &m, ACE_Condition_Attributes &attributes, const ACE_TCHAR *name = 0, void *arg = 0); - // Initialize the condition variable. + /// Implicitly destroy the condition variable. ~ACE_Condition_Thread_Mutex (void); - // Implicitly destroy the condition variable. + /** + * Explicitly destroy the condition variable. Note that only one + * thread should call this method since it doesn't protect against + * race conditions. + */ int remove (void); - // Explicitly destroy the condition variable. Note that only one - // thread should call this method since it doesn't protect against - // race conditions. + /** + * Block on condition, or until absolute time-of-day has passed. If + * abstime == 0 use "blocking" <wait> semantics. Else, if <abstime> + * != 0 and the call times out before the condition is signaled + * <wait> returns -1 and sets errno to ETIME. + */ int wait (const ACE_Time_Value *abstime); - // Block on condition, or until absolute time-of-day has passed. If - // abstime == 0 use "blocking" <wait> semantics. Else, if <abstime> - // != 0 and the call times out before the condition is signaled - // <wait> returns -1 and sets errno to ETIME. + /// Block on condition. int wait (void); - // Block on condition. + /** + * Block on condition or until absolute time-of-day has passed. If + * abstime == 0 use "blocking" wait() semantics on the <mutex> + * passed as a parameter (this is useful if you need to store the + * <Condition> in shared memory). Else, if <abstime> != 0 and the + * call times out before the condition is signaled <wait> returns -1 + * and sets errno to ETIME. + */ int wait (ACE_Thread_Mutex &mutex, const ACE_Time_Value *abstime = 0); - // Block on condition or until absolute time-of-day has passed. If - // abstime == 0 use "blocking" wait() semantics on the <mutex> - // passed as a parameter (this is useful if you need to store the - // <Condition> in shared memory). Else, if <abstime> != 0 and the - // call times out before the condition is signaled <wait> returns -1 - // and sets errno to ETIME. + /// Signal one waiting thread. int signal (void); - // Signal one waiting thread. + /// Signal *all* waiting threads. int broadcast (void); - // Signal *all* waiting threads. + /// Returns a reference to the underlying mutex_; ACE_Thread_Mutex &mutex (void); - // Returns a reference to the underlying mutex_; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Condition variable. ACE_cond_t cond_; - // Condition variable. + /// Reference to mutex lock. ACE_Thread_Mutex &mutex_; - // Reference to mutex lock. + /// Keeps track of whether <remove> has been called yet to avoid + /// multiple <remove> calls, e.g., explicitly and implicitly in the int removed_; - // Keeps track of whether <remove> has been called yet to avoid - // multiple <remove> calls, e.g., explicitly and implicitly in the // destructor. This flag isn't protected by a lock, so make sure // that you don't have multiple threads simultaneously calling // <remove> on the same object, which is a bad idea anyway... @@ -1059,96 +1191,119 @@ private: ACE_Condition_Thread_Mutex (const ACE_Condition_Thread_Mutex &); }; +/** + * @class ACE_Recursive_Thread_Mutex + * + * @brief Implement a C++ wrapper that allows nested acquisition and + * release of a mutex that occurs in the same thread. + */ class ACE_Export ACE_Recursive_Thread_Mutex { - // = TITLE - // Implement a C++ wrapper that allows nested acquisition and - // release of a mutex that occurs in the same thread. public: + /// Initialize a recursive mutex. ACE_Recursive_Thread_Mutex (const ACE_TCHAR *name = 0, ACE_mutexattr_t *arg = 0); - // Initialize a recursive mutex. + /// Implicitly release a recursive mutex. ~ACE_Recursive_Thread_Mutex (void); - // Implicitly release a recursive mutex. + /** + * Implicitly release a recursive mutex. Note that only one thread + * should call this method since it doesn't protect against race + * conditions. + */ int remove (void); - // Implicitly release a recursive mutex. Note that only one thread - // should call this method since it doesn't protect against race - // conditions. + /** + * Acquire a recursive mutex (will increment the nesting level and + * not deadmutex if the owner of the mutex calls this method more + * than once). + */ int acquire (void); - // Acquire a recursive mutex (will increment the nesting level and - // not deadmutex if the owner of the mutex calls this method more - // than once). + /** + * Conditionally acquire a recursive mutex (i.e., won't block). + * Returns -1 on failure. If we "failed" because someone else + * already had the lock, <errno> is set to <EBUSY>. + */ int tryacquire (void); - // Conditionally acquire a recursive mutex (i.e., won't block). - // Returns -1 on failure. If we "failed" because someone else - // already had the lock, <errno> is set to <EBUSY>. + /** + * Acquire mutex ownership. This calls <acquire> and is only + * here to make the <ACE_Recusive_Thread_Mutex> interface consistent + * with the other synchronization APIs. + */ int acquire_read (void); - // Acquire mutex ownership. This calls <acquire> and is only - // here to make the <ACE_Recusive_Thread_Mutex> interface consistent - // with the other synchronization APIs. + /** + * Acquire mutex ownership. This calls <acquire> and is only + * here to make the <ACE_Recusive_Thread_Mutex> interface consistent + * with the other synchronization APIs. + */ int acquire_write (void); - // Acquire mutex ownership. This calls <acquire> and is only - // here to make the <ACE_Recusive_Thread_Mutex> interface consistent - // with the other synchronization APIs. + /** + * Conditionally acquire mutex (i.e., won't block). This calls + * <tryacquire> and is only here to make the + * <ACE_Recusive_Thread_Mutex> interface consistent with the other + * synchronization APIs. Returns -1 on failure. If we "failed" + * because someone else already had the lock, <errno> is set to + * <EBUSY>. + */ int tryacquire_read (void); - // Conditionally acquire mutex (i.e., won't block). This calls - // <tryacquire> and is only here to make the - // <ACE_Recusive_Thread_Mutex> interface consistent with the other - // synchronization APIs. Returns -1 on failure. If we "failed" - // because someone else already had the lock, <errno> is set to - // <EBUSY>. + /** + * Conditionally acquire mutex (i.e., won't block). This calls + * <tryacquire> and is only here to make the + * <ACE_Recusive_Thread_Mutex> interface consistent with the other + * synchronization APIs. Returns -1 on failure. If we "failed" + * because someone else already had the lock, <errno> is set to + * <EBUSY>. + */ int tryacquire_write (void); - // Conditionally acquire mutex (i.e., won't block). This calls - // <tryacquire> and is only here to make the - // <ACE_Recusive_Thread_Mutex> interface consistent with the other - // synchronization APIs. Returns -1 on failure. If we "failed" - // because someone else already had the lock, <errno> is set to - // <EBUSY>. + /** + * This is only here to make the <ACE_Recursive_Thread_Mutex> + * interface consistent with the other synchronization APIs. + * Assumes the caller has already acquired the mutex using one of + * the above calls, and returns 0 (success) always. + */ int tryacquire_write_upgrade (void); - // This is only here to make the <ACE_Recursive_Thread_Mutex> - // interface consistent with the other synchronization APIs. - // Assumes the caller has already acquired the mutex using one of - // the above calls, and returns 0 (success) always. + /** + * Releases a recursive mutex (will not release mutex until all the + * nesting level drops to 0, which means the mutex is no longer + * held). + */ int release (void); - // Releases a recursive mutex (will not release mutex until all the - // nesting level drops to 0, which means the mutex is no longer - // held). + /// Return the id of the thread that currently owns the mutex. ACE_thread_t get_thread_id (void); - // Return the id of the thread that currently owns the mutex. + /** + * Return the nesting level of the recursion. When a thread has + * acquired the mutex for the first time, the nesting level == 1. + * The nesting level is incremented every time the thread acquires + * the mutex recursively. + */ int get_nesting_level (void); - // Return the nesting level of the recursion. When a thread has - // acquired the mutex for the first time, the nesting level == 1. - // The nesting level is incremented every time the thread acquires - // the mutex recursively. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = This method should *not* be public (they hold no locks...) void set_thread_id (ACE_thread_t t); + /// Recursive mutex. ACE_recursive_thread_mutex_t recursive_mutex_; - // Recursive mutex. + /// Keeps track of whether <remove> has been called yet to avoid + /// multiple <remove> calls, e.g., explicitly and implicitly in the int removed_; - // Keeps track of whether <remove> has been called yet to avoid - // multiple <remove> calls, e.g., explicitly and implicitly in the // destructor. This flag isn't protected by a lock, so make sure // that you don't have multiple threads simultaneously calling // <remove> on the same object, which is a bad idea anyway... @@ -1159,53 +1314,61 @@ private: ACE_Recursive_Thread_Mutex (const ACE_Recursive_Thread_Mutex &); }; +/** + * @class ACE_RW_Thread_Mutex + * + * @brief Wrapper for readers/writer locks that exist within a process. + */ class ACE_Export ACE_RW_Thread_Mutex : public ACE_RW_Mutex { - // = TITLE - // Wrapper for readers/writer locks that exist within a process. public: ACE_RW_Thread_Mutex (const ACE_TCHAR *name = 0, void *arg = 0); + /// Default dtor. ~ACE_RW_Thread_Mutex (void); - // Default dtor. + /** + * Conditionally upgrade a read lock to a write lock. This only + * works if there are no other readers present, in which case the + * method returns 0. Otherwise, the method returns -1 and sets + * <errno> to <EBUSY>. Note that the caller of this method *must* + * already possess this lock as a read lock (but this condition is + * not checked by the current implementation). + */ int tryacquire_write_upgrade (void); - // Conditionally upgrade a read lock to a write lock. This only - // works if there are no other readers present, in which case the - // method returns 0. Otherwise, the method returns -1 and sets - // <errno> to <EBUSY>. Note that the caller of this method *must* - // already possess this lock as a read lock (but this condition is - // not checked by the current implementation). + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Thread_Semaphore + * + * @brief Wrapper for Dijkstra style general semaphores that work + * only within one process. + */ class ACE_Export ACE_Thread_Semaphore : public ACE_Semaphore { - // = TITLE - // Wrapper for Dijkstra style general semaphores that work - // only within one process. public: + /// Initialize the semaphore, with an initial value of <count>, + /// maximum value of <max>, and unlocked by default. ACE_Thread_Semaphore (u_int count = 1, // By default make this unlocked. const ACE_TCHAR *name = 0, void * = 0, int max = 0x7FFFFFFF); - // Initialize the semaphore, with an initial value of <count>, - // maximum value of <max>, and unlocked by default. + /// Default dtor. ~ACE_Thread_Semaphore (void); - // Default dtor. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; struct ACE_Export ACE_Sub_Barrier @@ -1231,59 +1394,63 @@ struct ACE_Export ACE_Sub_Barrier // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Barrier + * + * @brief Implements "barrier synchronization". + * + * This class allows <count> number of threads to synchronize + * their completion of (one round of) a task, which is known as + * "barrier synchronization". The implementation uses a + * "sub-barrier generation numbering" scheme to avoid overhead + * and to ensure that all threads wait to leave the barrier + * correct. This code is based on an article from SunOpsis + * Vol. 4, No. 1 by Richard Marejka + * (Richard.Marejka@canada.sun.com). + */ class ACE_Export ACE_Barrier { - // = TITLE - // Implements "barrier synchronization". - // - // = DESCRIPTION - // This class allows <count> number of threads to synchronize - // their completion of (one round of) a task, which is known as - // "barrier synchronization". The implementation uses a - // "sub-barrier generation numbering" scheme to avoid overhead - // and to ensure that all threads wait to leave the barrier - // correct. This code is based on an article from SunOpsis - // Vol. 4, No. 1 by Richard Marejka - // (Richard.Marejka@canada.sun.com). public: + /// Initialize the barrier to synchronize <count> threads. ACE_Barrier (u_int count, const ACE_TCHAR *name = 0, void *arg = 0); - // Initialize the barrier to synchronize <count> threads. + /// Default dtor. ~ACE_Barrier (void); - // Default dtor. + /// Block the caller until all <count> threads have called <wait> and + /// then allow all the caller threads to continue in parallel. int wait (void); - // Block the caller until all <count> threads have called <wait> and - // then allow all the caller threads to continue in parallel. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Serialize access to the barrier state. ACE_Thread_Mutex lock_; - // Serialize access to the barrier state. + /// Either 0 or 1, depending on whether we are the first generation + /// of waiters or the next generation of waiters. int current_generation_; - // Either 0 or 1, depending on whether we are the first generation - // of waiters or the next generation of waiters. + /// Total number of threads that can be waiting at any one time. int count_; - // Total number of threads that can be waiting at any one time. + /** + * We keep two <sub_barriers>, one for the first "generation" of + * waiters, and one for the next "generation" of waiters. This + * efficiently solves the problem of what to do if all the first + * generation waiters don't leave the barrier before one of the + * threads calls wait() again (i.e., starts up the next generation + * barrier). + */ ACE_Sub_Barrier sub_barrier_1_; ACE_Sub_Barrier sub_barrier_2_; ACE_Sub_Barrier *sub_barrier_[2]; - // We keep two <sub_barriers>, one for the first "generation" of - // waiters, and one for the next "generation" of waiters. This - // efficiently solves the problem of what to do if all the first - // generation waiters don't leave the barrier before one of the - // threads calls wait() again (i.e., starts up the next generation - // barrier). private: // = Prevent assignment and initialization. @@ -1297,15 +1464,18 @@ private: // functionality across platforms. If you know of a portable and // robust way to implement this functionality please let us know. +/** + * @class ACE_Process_Condition + * + * @brief ACE_Condition variable wrapper that works across processes. + */ class ACE_Export ACE_Process_Condition { - // = TITLE - // ACE_Condition variable wrapper that works across processes. public: ACE_Process_Condition (MUTEX &m, const ACE_TCHAR *name = 0, void *arg = 0); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. @@ -1313,46 +1483,50 @@ public: #endif /* 0 */ #if 0 +/** + * @class ACE_Process_Barrier + * + * @brief Implements "barrier synchronization" using ACE_Process_Mutexes! + * + * This class is just a simple wrapper for ACE_Barrier that + * selects the USYNC_PROCESS variant for the locks. + */ class ACE_Export ACE_Process_Barrier : public ACE_Barrier { - // = TITLE - // Implements "barrier synchronization" using ACE_Process_Mutexes! - // - // = DESCRIPTION - // This class is just a simple wrapper for ACE_Barrier that - // selects the USYNC_PROCESS variant for the locks. public: + /// Create a Process_Barrier, passing in the optional <name>. ACE_Process_Barrier (u_int count, const ACE_TCHAR *name = 0); - // Create a Process_Barrier, passing in the optional <name>. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #endif /* 0 */ +/** + * @class ACE_Thread_Barrier + * + * @brief Implements "barrier synchronization" using ACE_Thread_Mutexes! + * + * This class is just a simple wrapper for ACE_Barrier that + * selects the USYNC_THREAD variant for the locks. + */ class ACE_Export ACE_Thread_Barrier : public ACE_Barrier { - // = TITLE - // Implements "barrier synchronization" using ACE_Thread_Mutexes! - // - // = DESCRIPTION - // This class is just a simple wrapper for ACE_Barrier that - // selects the USYNC_THREAD variant for the locks. public: + /// Create a Thread_Barrier, passing in the optional <name>. ACE_Thread_Barrier (u_int count, const ACE_TCHAR *name = 0); - // Create a Thread_Barrier, passing in the optional <name>. + /// Default dtor. ~ACE_Thread_Barrier (void); - // Default dtor. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #endif /* ACE_HAS_THREADS */ @@ -1367,15 +1541,17 @@ template <class ACE_LOCK> class ACE_Guard; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Guard<ACE_Null_Mutex> + * + * @brief Template specialization of <ACE_Guard> for the + * <ACE_Null_Mutex>. + * + * This specialization is useful since it helps to speedup + * performance of the "Null_Mutex" considerably. + */ class ACE_Export ACE_Guard<ACE_Null_Mutex> { - // = TITLE - // Template specialization of <ACE_Guard> for the - // <ACE_Null_Mutex>. - // - // = DESCRIPTION - // This specialization is useful since it helps to speedup - // performance of the "Null_Mutex" considerably. public: // = Initialization and termination methods. ACE_Guard (ACE_Null_Mutex &) {} @@ -1401,9 +1577,12 @@ template <class ACE_LOCK> class ACE_Write_Guard; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Write_Guard<ACE_Null_Mutex> + * + */ class ACE_Export ACE_Write_Guard<ACE_Null_Mutex> : public ACE_Guard<ACE_Null_Mutex> { - // = TITLE public: ACE_Write_Guard (ACE_Null_Mutex &m) : ACE_Guard<ACE_Null_Mutex> (m) {} @@ -1421,9 +1600,12 @@ template <class ACE_LOCK> class ACE_Read_Guard; ACE_TEMPLATE_SPECIALIZATION +/** + * @class ACE_Read_Guard<ACE_Null_Mutex> + * + */ class ACE_Export ACE_Read_Guard<ACE_Null_Mutex> : public ACE_Guard<ACE_Null_Mutex> { - // = TITLE public: ACE_Read_Guard (ACE_Null_Mutex &m) : ACE_Guard<ACE_Null_Mutex> (m) {} @@ -1437,13 +1619,13 @@ public: void dump (void) const {} }; -#if defined (ACE_LEGACY_MODE) -# include "ace/File_Lock.h" -# include "ace/Process_Semaphore.h" -# include "ace/Process_Mutex.h" -# include "ace/RW_Process_Mutex.h" -# include "ace/Test_and_Set.h" -#endif /* ACE_LEGACY_MODE */ +#if defined (ACE_LEGACY_MODE) +# include "ace/File_Lock.h" +# include "ace/Process_Semaphore.h" +# include "ace/Process_Mutex.h" +# include "ace/RW_Process_Mutex.h" +# include "ace/Test_and_Set.h" +#endif /* ACE_LEGACY_MODE */ #include "ace/post.h" #endif /* ACE_SYNCH_H */ diff --git a/ace/Synch_Options.h b/ace/Synch_Options.h index 5ce8d3f9b96..2c7bf196607 100644 --- a/ace/Synch_Options.h +++ b/ace/Synch_Options.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// ACE_Synch_Options.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file ACE_Synch_Options.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_SYNCH_OPTIONS_H #define ACE_SYNCH_OPTIONS_H @@ -24,121 +21,129 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Synch_Options + * + * @brief Contains the values of options used to determine the + * synchronous and asynchronous behavior. + * + * Values support the following behavior (TV == "timeout" + * and UR == "use ACE_Reactor"): + * + * <CODE> + * | Parameters | Description + * | + * |TV | UR | + * |-----|----------|------------------------------- + * | | + * |NULL | yes | infinite timeout (using ACE_Reactor) + * | | + * |time | yes | try asynch transaction for + * | | the specified time (using ACE_Reactor) + * | | + * |0,0 | yes | poll; try, if EWOULDBLOCK, + * | | then return immediately + * | | (using ACE_Reactor) + * | | + * |NULL | no | block forever (don't use ACE_Reactor) + * | | + * |time | no | do a blocking transaction + * | | for the specified time + * | | (don't use ACE_Reactor) + * | | + * |0,0 | no | poll; but do not initiate a + * | | nonblocking transaction + * | | (don't use ACE_Reactor) + * </CODE> + */ class ACE_Export ACE_Synch_Options { - // = TITLE - // Contains the values of options used to determine the - // synchronous and asynchronous behavior. - // - // = DESCRIPTION - // Values support the following behavior (TV == "timeout" - // and UR == "use ACE_Reactor"): - // - // = BEGIN<CODE> - // Parameters | Description - // | - // TV | UR | - // -----|----------|------------------------------- - // | | - // NULL | yes | infinite timeout (using ACE_Reactor) - // | | - // time | yes | try asynch transaction for - // | | the specified time (using ACE_Reactor) - // | | - // 0,0 | yes | poll; try, if EWOULDBLOCK, - // | | then return immediately - // | | (using ACE_Reactor) - // | | - // NULL | no | block forever (don't use ACE_Reactor) - // | | - // time | no | do a blocking transaction - // | | for the specified time - // | | (don't use ACE_Reactor) - // | | - // 0,0 | no | poll; but do not initiate a - // | | nonblocking transaction - // | | (don't use ACE_Reactor) - // = END<CODE> public: - // = Options flags for controlling synchronization. Note that these - // flags can be bit-wise "or'd" together if both options are - // desired. + /// Options flags for controlling synchronization. + /** + * Note that these flags can be bit-wise "or'd" together if both + * options are desired. + */ enum { + /// Use the Reactor. USE_REACTOR = 01, - // Use the Reactor. + /// Interprete the Time_Value. USE_TIMEOUT = 02 - // Interprete the Time_Value. }; // = Initialization methods. + /// Initialize the Synch_Options based on parameters. ACE_Synch_Options (u_long options = 0, const ACE_Time_Value &timeout = ACE_Time_Value::zero, const void *arg = 0); - // Initialize the Synch_Options based on parameters. + /// Default dtor. ~ACE_Synch_Options (void); - // Default dtor. + /// Initialize the Synch_Options based on parameters. void set (u_long options = 0, const ACE_Time_Value &timeout = ACE_Time_Value::zero, const void *arg = 0); - // Initialize the Synch_Options based on parameters. + /// Get method for determining which options are enabled. int operator[] (u_long option) const; - // Get method for determining which options are enabled. + /// Set method for enabling certain options. void operator= (u_long option); - // Set method for enabling certain options. + /// Returns the "magic cookie" argument. const void *arg (void) const; - // Returns the "magic cookie" argument. + /// Set the "magic cookie" argument. void arg (const void *); - // Set the "magic cookie" argument. + /// Returns a reference to the <Time_Value>. This value only makes + /// sense if (*this)[USE_TIMEOUT] is true. const ACE_Time_Value &timeout (void) const; - // Returns a reference to the <Time_Value>. This value only makes - // sense if (*this)[USE_TIMEOUT] is true. + /// Set the <Time_Value>. void timeout (const ACE_Time_Value &tv); - // Set the <Time_Value>. + /** + * Returns the address of the timeout <Time_Value> if + * (*this)[USE_TIMEOUT] is true, else 0. This should be used with + * care, e.g., the timeout pointer should not be stored in a manner + * that will lead to dangling pointers... + */ const ACE_Time_Value *time_value (void) const; - // Returns the address of the timeout <Time_Value> if - // (*this)[USE_TIMEOUT] is true, else 0. This should be used with - // care, e.g., the timeout pointer should not be stored in a manner - // that will lead to dangling pointers... // = Static data members (singletons) + /// This is the default setting for options, which will block + /// synchronously. static ACE_Synch_Options defaults; - // This is the default setting for options, which will block - // synchronously. + /// This is the default synchronous setting. static ACE_Synch_Options synch; - // This is the default synchronous setting. + /// This is the default asynchronous setting. static ACE_Synch_Options asynch; - // This is the default asynchronous setting. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Keeps track of the enabled options. u_long options_; - // Keeps track of the enabled options. + /// Amount of time to wait for timeouts. ACE_Time_Value timeout_; - // Amount of time to wait for timeouts. + /** + * "Magic cookie" always passed in as an argument to the ACE_Reactor's + * <schedule_timer> method. Used to communicate values for + * asynchronous programming. + */ const void *arg_; - // "Magic cookie" always passed in as an argument to the ACE_Reactor's - // <schedule_timer> method. Used to communicate values for - // asynchronous programming. }; #if defined (__ACE_INLINE__) diff --git a/ace/Synch_T.h b/ace/Synch_T.h index 8a742b1f682..81980b6cb40 100644 --- a/ace/Synch_T.h +++ b/ace/Synch_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Synch_T.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@uci.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Synch_T.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@uci.edu> + */ +//============================================================================= + #ifndef ACE_SYNCH_T_H #define ACE_SYNCH_T_H @@ -26,430 +23,451 @@ // Forward decl class ACE_Time_Value; +/** + * @class ACE_Lock_Adapter + * + * @brief This is an adapter that allows applications to transparently + * combine the <ACE_Lock> abstract base class (which contains + * pure virtual methods) with any of the other concrete ACE + * synchronization classes (e.g., <ACE_Mutex>, <ACE_Semaphore>, + * <ACE_RW_Mutex>, etc.). + * + * This class uses a form of the Adapter pattern. + */ template <class ACE_LOCKING_MECHANISM> class ACE_Lock_Adapter : public ACE_Lock { - // = TITLE - // This is an adapter that allows applications to transparently - // combine the <ACE_Lock> abstract base class (which contains - // pure virtual methods) with any of the other concrete ACE - // synchronization classes (e.g., <ACE_Mutex>, <ACE_Semaphore>, - // <ACE_RW_Mutex>, etc.). - // - // = DESCRIPTION - // This class uses a form of the Adapter pattern. public: typedef ACE_LOCKING_MECHANISM ACE_LOCK; // = Initialization/Finalization methods. + /// Constructor. All locking requests will be forwarded to <lock>. ACE_Lock_Adapter (ACE_LOCKING_MECHANISM &lock); - // Constructor. All locking requests will be forwarded to <lock>. + /// Constructor. Since no lock is provided by the user, one will be + /// created internally. ACE_Lock_Adapter (void); - // Constructor. Since no lock is provided by the user, one will be - // created internally. + /// Destructor. If <lock_> was not passed in by the user, it will be + /// deleted. virtual ~ACE_Lock_Adapter (void); - // Destructor. If <lock_> was not passed in by the user, it will be - // deleted. // = Lock accessors. + /// Block the thread until the lock is acquired. virtual int acquire (void); - // Block the thread until the lock is acquired. + /// Conditionally acquire the lock (i.e., won't block). virtual int tryacquire (void); - // Conditionally acquire the lock (i.e., won't block). + /// Release the lock. virtual int release (void); - // Release the lock. + /** + * Block until the thread acquires a read lock. If the locking + * mechanism doesn't support read locks then this just calls + * <acquire>. + */ virtual int acquire_read (void); - // Block until the thread acquires a read lock. If the locking - // mechanism doesn't support read locks then this just calls - // <acquire>. + /** + * Block until the thread acquires a write lock. If the locking + * mechanism doesn't support read locks then this just calls + * <acquire>. + */ virtual int acquire_write (void); - // Block until the thread acquires a write lock. If the locking - // mechanism doesn't support read locks then this just calls - // <acquire>. + /// Conditionally acquire a read lock. If the locking mechanism + /// doesn't support read locks then this just calls <acquire>. virtual int tryacquire_read (void); - // Conditionally acquire a read lock. If the locking mechanism - // doesn't support read locks then this just calls <acquire>. + /// Conditionally acquire a write lock. If the locking mechanism + /// doesn't support read locks then this just calls <acquire>. virtual int tryacquire_write (void); - // Conditionally acquire a write lock. If the locking mechanism - // doesn't support read locks then this just calls <acquire>. + /** + * Conditionally try to upgrade a lock held for read to a write lock. + * If the locking mechanism doesn't support read locks then this just + * calls <acquire>. Returns 0 on success, -1 on failure. + */ virtual int tryacquire_write_upgrade (void); - // Conditionally try to upgrade a lock held for read to a write lock. - // If the locking mechanism doesn't support read locks then this just - // calls <acquire>. Returns 0 on success, -1 on failure. + /// Explicitly destroy the lock. virtual int remove (void); - // Explicitly destroy the lock. private: + /// The concrete locking mechanism that all the methods delegate to. ACE_LOCKING_MECHANISM *lock_; - // The concrete locking mechanism that all the methods delegate to. + /// This flag keep track of whether we are responsible for deleting + /// the lock int delete_lock_; - // This flag keep track of whether we are responsible for deleting - // the lock }; +/** + * @class ACE_Reverse_Lock + * + * @brief A reverse (or anti) lock. + * + * This is an interesting adapter class that changes a lock into + * a reverse lock, i.e., <acquire> on this class calls <release> + * on the lock, and <release> on this class calls <acquire> on + * the lock. + * One motivation for this class is when we temporarily want to + * release a lock (which we have already acquired) but then + * reaquire it soon after. An alternative design would be to + * add a Anti_Guard or Reverse_Guard class which would <release> + * on construction and <acquire> destruction. However, there + * are *many* varieties of the Guard class and this design + * choice would lead to at least 6 new classes. One new + * ACE_Reverse_Lock class seemed more reasonable. + */ template <class ACE_LOCKING_MECHANISM> class ACE_Reverse_Lock : public ACE_Lock { - // = TITLE - // A reverse (or anti) lock. - // - // = DESCRIPTION - // This is an interesting adapter class that changes a lock into - // a reverse lock, i.e., <acquire> on this class calls <release> - // on the lock, and <release> on this class calls <acquire> on - // the lock. - // - // One motivation for this class is when we temporarily want to - // release a lock (which we have already acquired) but then - // reaquire it soon after. An alternative design would be to - // add a Anti_Guard or Reverse_Guard class which would <release> - // on construction and <acquire> destruction. However, there - // are *many* varieties of the Guard class and this design - // choice would lead to at least 6 new classes. One new - // ACE_Reverse_Lock class seemed more reasonable. public: typedef ACE_LOCKING_MECHANISM ACE_LOCK; // = Initialization/Finalization methods. + /// Constructor. All locking requests will be forwarded to <lock>. ACE_Reverse_Lock (ACE_LOCKING_MECHANISM &lock); - // Constructor. All locking requests will be forwarded to <lock>. + /// Destructor. If <lock_> was not passed in by the user, it will be + /// deleted. virtual ~ACE_Reverse_Lock (void); - // Destructor. If <lock_> was not passed in by the user, it will be - // deleted. // = Lock accessors. + /// Release the lock. virtual int acquire (void); - // Release the lock. + /// Release the lock. virtual int tryacquire (void); - // Release the lock. + /// Acquire the lock. virtual int release (void); - // Acquire the lock. + /// Release the lock. virtual int acquire_read (void); - // Release the lock. + /// Release the lock. virtual int acquire_write (void); - // Release the lock. + /// Release the lock. virtual int tryacquire_read (void); - // Release the lock. + /// Release the lock. virtual int tryacquire_write (void); - // Release the lock. + /// Release the lock. virtual int tryacquire_write_upgrade (void); - // Release the lock. + /// Explicitly destroy the lock. virtual int remove (void); - // Explicitly destroy the lock. private: + /// The concrete locking mechanism that all the methods delegate to. ACE_LOCKING_MECHANISM &lock_; - // The concrete locking mechanism that all the methods delegate to. }; +/** + * @class ACE_Atomic_Op + * + * @brief Transparently parameterizes synchronization into basic + * arithmetic operations. + * + * This class is described in an article in the July/August 1994 + * issue of the C++ Report magazine. It implements a + * templatized version of the Decorator pattern from the GoF book. + */ template <class ACE_LOCK, class TYPE> class ACE_Atomic_Op { - // = TITLE - // Transparently parameterizes synchronization into basic - // arithmetic operations. - // - // = DESCRIPTION - // This class is described in an article in the July/August 1994 - // issue of the C++ Report magazine. It implements a - // templatized version of the Decorator pattern from the GoF book. public: // = Initialization methods. + /// Initialize <value_> to 0. ACE_Atomic_Op (void); - // Initialize <value_> to 0. + /// Initialize <value_> to c. ACE_Atomic_Op (const TYPE &c); - // Initialize <value_> to c. // = Accessors. + /// Atomically pre-increment <value_>. TYPE operator++ (void); - // Atomically pre-increment <value_>. + /// Atomically post-increment <value_>. TYPE operator++ (int); - // Atomically post-increment <value_>. + /// Atomically increment <value_> by i. TYPE operator+= (const TYPE &i); - // Atomically increment <value_> by i. + /// Atomically pre-decrement <value_>. TYPE operator-- (void); - // Atomically pre-decrement <value_>. + /// Atomically post-decrement <value_>. TYPE operator-- (int); - // Atomically post-decrement <value_>. + /// Atomically decrement <value_> by i. TYPE operator-= (const TYPE &i); - // Atomically decrement <value_> by i. + /// Atomically compare <value_> with i. int operator== (const TYPE &i) const; - // Atomically compare <value_> with i. + /// Atomically compare <value_> with i. int operator!= (const TYPE &i) const; - // Atomically compare <value_> with i. + /// Atomically check if <value_> greater than or equal to i. int operator>= (const TYPE &i) const; - // Atomically check if <value_> greater than or equal to i. + /// Atomically check if <value_> greater than i. int operator> (const TYPE &rhs) const; - // Atomically check if <value_> greater than i. + /// Atomically check if <value_> less than or equal to i. int operator<= (const TYPE &rhs) const; - // Atomically check if <value_> less than or equal to i. + /// Atomically check if <value_> less than i. int operator< (const TYPE &rhs) const; - // Atomically check if <value_> less than i. + /// Atomically assign i to <value_>. void operator= (const TYPE &i); - // Atomically assign i to <value_>. + /// Atomically assign <rhs> to <value_>. void operator= (const ACE_Atomic_Op<ACE_LOCK, TYPE> &rhs); - // Atomically assign <rhs> to <value_>. + /// Explicitly return <value_>. TYPE value (void) const; - // Explicitly return <value_>. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. + /// Manage copying... ACE_Atomic_Op (const ACE_Atomic_Op<ACE_LOCK, TYPE> &); - // Manage copying... + /** + * Returns a reference to the underlying <ACE_LOCK>. This makes it + * possible to acquire the lock explicitly, which can be useful in + * some cases if you instantiate the <ACE_Atomic_Op> with an + * <ACE_Recursive_Mutex> or <ACE_Process_Mutex>. NOTE: the right + * name would be lock_, but HP/C++ will choke on that! + */ ACE_LOCK &mutex (void); - // Returns a reference to the underlying <ACE_LOCK>. This makes it - // possible to acquire the lock explicitly, which can be useful in - // some cases if you instantiate the <ACE_Atomic_Op> with an - // <ACE_Recursive_Mutex> or <ACE_Process_Mutex>. NOTE: the right - // name would be lock_, but HP/C++ will choke on that! + /** + * Explicitly return <value_> (by reference). This gives the user + * full, unrestricted access to the underlying value. This method + * will usually be used in conjunction with explicit access to the + * lock. Use with care ;-) + */ TYPE &value_i (void); - // Explicitly return <value_> (by reference). This gives the user - // full, unrestricted access to the underlying value. This method - // will usually be used in conjunction with explicit access to the - // lock. Use with care ;-) private: + /// Type of synchronization mechanism. ACE_LOCK mutex_; - // Type of synchronization mechanism. + /// Current object decorated by the atomic op. TYPE value_; - // Current object decorated by the atomic op. }; +/** + * @class ACE_TSS + * + * @brief Allows objects that are "physically" in thread specific + * storage (i.e., private to a thread) to be accessed as though + * they were "logically" global to a program. + * + * This class is a wrapper around the OS thread library + * thread-specific functions. It uses the <C++ operator->> to + * shield applications from the details of accessing + * thread-specific storage. + * NOTE: TYPE cannot be a built-in type, but instead must be a + * user-defined class. (Some compilers will allow a built-in + * type, but shouldn't. Sun C++ won't, properly detecting the + * improper return type from <operator->>.) See template class + * ACE_TSS_Type_Adapter, below, for adapting built-in types to + * work with ACE_TSS. + */ template <class TYPE> class ACE_TSS { - // = TITLE - // Allows objects that are "physically" in thread specific - // storage (i.e., private to a thread) to be accessed as though - // they were "logically" global to a program. - // - // = DESCRIPTION - // This class is a wrapper around the OS thread library - // thread-specific functions. It uses the <C++ operator->> to - // shield applications from the details of accessing - // thread-specific storage. - // - // NOTE: TYPE cannot be a built-in type, but instead must be a - // user-defined class. (Some compilers will allow a built-in - // type, but shouldn't. Sun C++ won't, properly detecting the - // improper return type from <operator->>.) See template class - // ACE_TSS_Type_Adapter, below, for adapting built-in types to - // work with ACE_TSS. public: // = Initialization and termination methods. + /** + * If caller has passed us a non-NULL ts_obj *, then we'll just use + * this to initialize the thread-specific value (but only for the + * calling thread). Thus, subsequent calls to <operator->> in this + * thread will return this value. This is useful since it enables + * us to assign objects to thread-specific data that have + * arbitrarily complex constructors. + */ ACE_TSS (TYPE *ts_obj = 0); - // If caller has passed us a non-NULL ts_obj *, then we'll just use - // this to initialize the thread-specific value (but only for the - // calling thread). Thus, subsequent calls to <operator->> in this - // thread will return this value. This is useful since it enables - // us to assign objects to thread-specific data that have - // arbitrarily complex constructors. + /// Deregister with thread-key administration. virtual ~ACE_TSS (void); - // Deregister with thread-key administration. // = Accessors. + /** + * Get the thread-specific object for the key associated with this + * object. Returns 0 if the data has never been initialized, + * otherwise returns a pointer to the data. + */ TYPE *ts_object (void) const; - // Get the thread-specific object for the key associated with this - // object. Returns 0 if the data has never been initialized, - // otherwise returns a pointer to the data. + /// Set the thread-specific object for the key associated with this + /// object. TYPE *ts_object (TYPE *); - // Set the thread-specific object for the key associated with this - // object. + /// Use a "smart pointer" to get the thread-specific object + /// associated with the <key_>. TYPE *operator-> () const; - // Use a "smart pointer" to get the thread-specific object - // associated with the <key_>. + /// Return or create and return the calling threads TYPE object. operator TYPE *(void) const; - // Return or create and return the calling threads TYPE object. + /// Hook for construction parameters. virtual TYPE *make_TSS_TYPE (void) const; - // Hook for construction parameters. // = Utility methods. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. protected: + /// Actually implements the code that retrieves the object from + /// thread-specific storage. TYPE *ts_get (void) const; - // Actually implements the code that retrieves the object from - // thread-specific storage. + /// Factors out common code for initializing TSS. This must NOT be + /// called with the lock held... int ts_init (void) const; - // Factors out common code for initializing TSS. This must NOT be - // called with the lock held... #if !(defined (ACE_HAS_THREADS) && (defined (ACE_HAS_THREAD_SPECIFIC_STORAGE) || defined (ACE_HAS_TSS_EMULATION))) + /// This implementation only works for non-threading systems... TYPE *type_; - // This implementation only works for non-threading systems... #else + /// Avoid race conditions during initialization. ACE_Thread_Mutex keylock_; - // Avoid race conditions during initialization. + /// "First time in" flag. int once_; - // "First time in" flag. + /// Key for the thread-specific error data. ACE_thread_key_t key_; - // Key for the thread-specific error data. + /// "Destructor" that deletes internal TYPE * when thread exits. static void cleanup (void *ptr); - // "Destructor" that deletes internal TYPE * when thread exits. #endif /* defined (ACE_HAS_THREADS) && (defined (ACE_HAS_THREAD_SPECIFIC_STORAGE) || defined (ACE_HAS_TSS_EMULATION)) */ // = Disallow copying... ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_TSS<TYPE> &)) ACE_UNIMPLEMENTED_FUNC (ACE_TSS (const ACE_TSS<TYPE> &)) }; +/** + * @class ACE_TSS_Type_Adapter + * + * @brief Adapter that allows built-in types to be used with ACE_TSS. + * + * Wraps a value of a built-in type, providing conversions to + * and from the type. Example use with ACE_TSS: + * ACE_TSS<ACE_TSS_Type_Adapter<int> > i; + * *i = 37; + * ACE_OS::fprintf (stderr, "%d\n", *i); + * Unfortunately, though, some compilers have trouble with the + * implicit type conversions. This seems to work better: + * ACE_TSS<ACE_TSS_Type_Adapter<int> > i; + * i->operator int & () = 37; + * ACE_OS::fprintf (stderr, "%d\n", i->operator int ()); + */ template <class TYPE> class ACE_TSS_Type_Adapter { - // = TITLE - // Adapter that allows built-in types to be used with ACE_TSS. - // - // = DESCRIPTION - // Wraps a value of a built-in type, providing conversions to - // and from the type. Example use with ACE_TSS: - // - // ACE_TSS<ACE_TSS_Type_Adapter<int> > i; - // *i = 37; - // ACE_OS::fprintf (stderr, "%d\n", *i); - // - // Unfortunately, though, some compilers have trouble with the - // implicit type conversions. This seems to work better: - // - // ACE_TSS<ACE_TSS_Type_Adapter<int> > i; - // i->operator int & () = 37; - // ACE_OS::fprintf (stderr, "%d\n", i->operator int ()); public: + /// Constructor. Inlined here so that it should _always_ be inlined. ACE_TSS_Type_Adapter (const TYPE value = 0): value_ (value) {} - // Constructor. Inlined here so that it should _always_ be inlined. + /// TYPE conversion. Inlined here so that it should _always_ be + /// inlined. operator TYPE () const { return value_; }; - // TYPE conversion. Inlined here so that it should _always_ be - // inlined. + /// TYPE & conversion. Inlined here so that it should _always_ be + /// inlined. operator TYPE &() { return value_; }; - // TYPE & conversion. Inlined here so that it should _always_ be - // inlined. private: + /// The wrapped value. TYPE value_; - // The wrapped value. }; +/** + * @class ACE_Guard + * + * @brief This data structure is meant to be used within a method or + * function... It performs automatic aquisition and release of + * a parameterized synchronization object <ACE_LOCK>. + * + * The <ACE_LOCK> class given as an actual parameter must provide at + * the very least the <acquire>, <tryacquire>, <release>, and + * <remove> methods. + */ template <class ACE_LOCK> class ACE_Guard { - // = TITLE - // This data structure is meant to be used within a method or - // function... It performs automatic aquisition and release of - // a parameterized synchronization object <ACE_LOCK>. - // - // = DESCRIPTION - // The <ACE_LOCK> class given as an actual parameter must provide at - // the very least the <acquire>, <tryacquire>, <release>, and - // <remove> methods. public: // = Initialization and termination methods. ACE_Guard (ACE_LOCK &l); + /// Implicitly and automatically acquire (or try to acquire) the + /// lock. ACE_Guard (ACE_LOCK &l, int block); - // Implicitly and automatically acquire (or try to acquire) the - // lock. + /// Implicitly release the lock. ~ACE_Guard (void); - // Implicitly release the lock. // = Lock accessors. + /// Explicitly acquire the lock. int acquire (void); - // Explicitly acquire the lock. + /// Conditionally acquire the lock (i.e., won't block). int tryacquire (void); - // Conditionally acquire the lock (i.e., won't block). + /// Explicitly release the lock, but only if it is held! int release (void); - // Explicitly release the lock, but only if it is held! // = Utility methods. + /// 1 if locked, 0 if couldn't acquire the lock + /// (errno will contain the reason for this). int locked (void); - // 1 if locked, 0 if couldn't acquire the lock - // (errno will contain the reason for this). + /// Explicitly remove the lock. int remove (void); - // Explicitly remove the lock. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. protected: + /// Helper, meant for subclass only. ACE_Guard (ACE_LOCK *lock): lock_ (lock) {} - // Helper, meant for subclass only. + /// Pointer to the ACE_LOCK we're guarding. ACE_LOCK *lock_; - // Pointer to the ACE_LOCK we're guarding. + /// Keeps track of whether we acquired the lock or failed. int owner_; - // Keeps track of whether we acquired the lock or failed. private: // = Prevent assignment and initialization. @@ -457,83 +475,89 @@ private: ACE_UNIMPLEMENTED_FUNC (ACE_Guard (const ACE_Guard<ACE_LOCK> &)) }; +/** + * @class ACE_Write_Guard + * + * @brief This class is similar to class <ACE_Guard>, though it + * acquires/releases a write lock automatically (naturally, the + * <ACE_LOCK> it is instantiated with must support the appropriate + * API). + */ template <class ACE_LOCK> class ACE_Write_Guard : public ACE_Guard<ACE_LOCK> { - // = TITLE - // This class is similar to class <ACE_Guard>, though it - // acquires/releases a write lock automatically (naturally, the - // <ACE_LOCK> it is instantiated with must support the appropriate - // API). public: // = Initialization method. + /// Implicitly and automatically acquire a write lock. ACE_Write_Guard (ACE_LOCK &m); - // Implicitly and automatically acquire a write lock. + /// Implicitly and automatically acquire (or try to acquire) a write + /// lock. ACE_Write_Guard (ACE_LOCK &m, int block); - // Implicitly and automatically acquire (or try to acquire) a write - // lock. // = Lock accessors. + /// Explicitly acquire the write lock. int acquire_write (void); - // Explicitly acquire the write lock. + /// Explicitly acquire the write lock. int acquire (void); - // Explicitly acquire the write lock. + /// Conditionally acquire the write lock (i.e., won't block). int tryacquire_write (void); - // Conditionally acquire the write lock (i.e., won't block). + /// Conditionally acquire the write lock (i.e., won't block). int tryacquire (void); - // Conditionally acquire the write lock (i.e., won't block). // = Utility methods. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. }; +/** + * @class ACE_Read_Guard + * + * @brief This class is similar to class <ACE_Guard>, though it + * acquires/releases a read lock automatically (naturally, the + * <ACE_LOCK> it is instantiated with must support the appropriate + * API). + */ template <class ACE_LOCK> class ACE_Read_Guard : public ACE_Guard<ACE_LOCK> { - // = TITLE - // This class is similar to class <ACE_Guard>, though it - // acquires/releases a read lock automatically (naturally, the - // <ACE_LOCK> it is instantiated with must support the appropriate - // API). public: // = Initialization methods. + /// Implicitly and automatically acquire a read lock. ACE_Read_Guard (ACE_LOCK& m); - // Implicitly and automatically acquire a read lock. + /// Implicitly and automatically acquire (or try to acquire) a read + /// lock. ACE_Read_Guard (ACE_LOCK &m, int block); - // Implicitly and automatically acquire (or try to acquire) a read - // lock. // = Lock accessors. + /// Explicitly acquire the read lock. int acquire_read (void); - // Explicitly acquire the read lock. + /// Explicitly acquire the read lock. int acquire (void); - // Explicitly acquire the read lock. + /// Conditionally acquire the read lock (i.e., won't block). int tryacquire_read (void); - // Conditionally acquire the read lock (i.e., won't block). + /// Conditionally acquire the read lock (i.e., won't block). int tryacquire (void); - // Conditionally acquire the read lock (i.e., won't block). // = Utility methods. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. @@ -549,57 +573,60 @@ public: /* ACE platform supports some form of threading and thread-specific storage. */ +/** + * @class ACE_TSS_Guard + * + * @brief This data structure is meant to be used within a method or + * function... It performs automatic aquisition and release of + * a synchronization object. Moreover, it ensures that the lock + * is released even if a thread exits via <thr_exit>! + */ template <class ACE_LOCK> class ACE_TSS_Guard { - // = TITLE - // This data structure is meant to be used within a method or - // function... It performs automatic aquisition and release of - // a synchronization object. Moreover, it ensures that the lock - // is released even if a thread exits via <thr_exit>! public: // = Initialization and termination methods. + /// Implicitly and automatically acquire the thread-specific lock. ACE_TSS_Guard (ACE_LOCK &lock, int block = 1); - // Implicitly and automatically acquire the thread-specific lock. + /// Implicitly release the thread-specific lock. ~ACE_TSS_Guard (void); - // Implicitly release the thread-specific lock. // = Lock accessors. + /// Explicitly acquire the thread-specific lock. int acquire (void); - // Explicitly acquire the thread-specific lock. + /// Conditionally acquire the thread-specific lock (i.e., won't + /// block). int tryacquire (void); - // Conditionally acquire the thread-specific lock (i.e., won't - // block). + /// Explicitly release the thread-specific lock. int release (void); - // Explicitly release the thread-specific lock. // = Utility methods. + /// Explicitly release the thread-specific lock. int remove (void); - // Explicitly release the thread-specific lock. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. protected: + /// Helper, meant for subclass only. ACE_TSS_Guard (void); - // Helper, meant for subclass only. + /// Initialize the key. void init_key (void); - // Initialize the key. + /// Called when thread exits to clean up the lock. static void cleanup (void *ptr); - // Called when thread exits to clean up the lock. + /// Thread-specific key... ACE_thread_key_t key_; - // Thread-specific key... private: // = Prevent assignment and initialization. @@ -607,74 +634,80 @@ private: ACE_UNIMPLEMENTED_FUNC (ACE_TSS_Guard (const ACE_TSS_Guard<ACE_LOCK> &)) }; +/** + * @class ACE_TSS_Write_Guard + * + * @brief This class is similar to class ACE_TSS_Guard, though it + * acquires/releases a write-lock automatically (naturally, the + * ACE_LOCK it is instantiated with must support the appropriate + * API). + */ template <class ACE_LOCK> class ACE_TSS_Write_Guard : public ACE_TSS_Guard<ACE_LOCK> { - // = TITLE - // This class is similar to class ACE_TSS_Guard, though it - // acquires/releases a write-lock automatically (naturally, the - // ACE_LOCK it is instantiated with must support the appropriate - // API). public: // = Initialization method. + /// Implicitly and automatically acquire the thread-specific write lock. ACE_TSS_Write_Guard (ACE_LOCK &lock, int block = 1); - // Implicitly and automatically acquire the thread-specific write lock. // = Lock accessors. + /// Explicitly acquire the thread-specific write lock. int acquire_write (void); - // Explicitly acquire the thread-specific write lock. + /// Explicitly acquire the thread-specific write lock. int acquire (void); - // Explicitly acquire the thread-specific write lock. + /// Conditionally acquire the thread-specific write lock (i.e., won't block). int tryacquire_write (void); - // Conditionally acquire the thread-specific write lock (i.e., won't block). + /// Conditionally acquire the thread-specific write lock (i.e., won't block). int tryacquire (void); - // Conditionally acquire the thread-specific write lock (i.e., won't block). // = Utility methods. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. }; +/** + * @class ACE_TSS_Read_Guard + * + * @brief This class is similar to class <ACE_TSS_Guard>, though it + * acquires/releases a read lock automatically (naturally, the + * <ACE_LOCK> it is instantiated with must support the + * appropriate API). + */ template <class ACE_LOCK> class ACE_TSS_Read_Guard : public ACE_TSS_Guard<ACE_LOCK> { - // = TITLE - // This class is similar to class <ACE_TSS_Guard>, though it - // acquires/releases a read lock automatically (naturally, the - // <ACE_LOCK> it is instantiated with must support the - // appropriate API). public: // = Initialization method. + /// Implicitly and automatically acquire the thread-specific read lock. ACE_TSS_Read_Guard (ACE_LOCK &lock, int block = 1); - // Implicitly and automatically acquire the thread-specific read lock. // = Lock accessors. + /// Explicitly acquire the thread-specific read lock. int acquire_read (void); - // Explicitly acquire the thread-specific read lock. + /// Explicitly acquire the thread-specific read lock. int acquire (void); - // Explicitly acquire the thread-specific read lock. + /// Conditionally acquire the thread-specific read lock (i.e., won't + /// block). int tryacquire_read (void); - // Conditionally acquire the thread-specific read lock (i.e., won't - // block). + /// Conditionally acquire the thread-specific read lock (i.e., won't + /// block). int tryacquire (void); - // Conditionally acquire the thread-specific read lock (i.e., won't - // block). // = Utility methods. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. @@ -683,90 +716,97 @@ public: #if defined (ACE_HAS_THREADS) /* ACE platform supports some form of threading. */ +/** + * @class ACE_Condition + * + * @brief ACE_Condition variable wrapper, which allows threads to block + * until shared data changes state. + * + * A condition variable enables threads to atomically block and + * test the condition under the protection of a mutual exclu- + * sion lock (mutex) until the condition is satisfied. That is, + * the mutex must have been held by the thread before calling + * wait or signal on the condition. If the condition is false, + * a thread blocks on a condition variable and atomically + * releases the mutex that is waiting for the condition to + * change. If another thread changes the condition, it may wake + * up waiting threads by signaling the associated condition + * variable. The waiting threads, upon awakening, reacquire the + * mutex and re-evaluate the condition. + * Note, you can only parameterize <ACE_Condition> with + * <ACE_Thread_Mutex> or <ACE_Null_Mutex>. + */ template <class MUTEX> class ACE_Condition { - // = TITLE - // ACE_Condition variable wrapper, which allows threads to block - // until shared data changes state. - // - // = DESCRIPTION - // A condition variable enables threads to atomically block and - // test the condition under the protection of a mutual exclu- - // sion lock (mutex) until the condition is satisfied. That is, - // the mutex must have been held by the thread before calling - // wait or signal on the condition. If the condition is false, - // a thread blocks on a condition variable and atomically - // releases the mutex that is waiting for the condition to - // change. If another thread changes the condition, it may wake - // up waiting threads by signaling the associated condition - // variable. The waiting threads, upon awakening, reacquire the - // mutex and re-evaluate the condition. - // - // Note, you can only parameterize <ACE_Condition> with - // <ACE_Thread_Mutex> or <ACE_Null_Mutex>. public: // = Initialiation and termination methods. + /// Initialize the condition variable. ACE_Condition (MUTEX &m, int type = USYNC_THREAD, const ACE_TCHAR *name = 0, void *arg = 0); - // Initialize the condition variable. + /// Implicitly destroy the condition variable. ~ACE_Condition (void); - // Implicitly destroy the condition variable. // = Lock accessors. + /** + * Block on condition, or until absolute time-of-day has passed. If + * abstime == 0 use "blocking" <wait> semantics. Else, if <abstime> + * != 0 and the call times out before the condition is signaled + * <wait> returns -1 and sets errno to ETIME. + */ int wait (const ACE_Time_Value *abstime); - // Block on condition, or until absolute time-of-day has passed. If - // abstime == 0 use "blocking" <wait> semantics. Else, if <abstime> - // != 0 and the call times out before the condition is signaled - // <wait> returns -1 and sets errno to ETIME. + /// Block on condition. int wait (void); - // Block on condition. + /** + * Block on condition or until absolute time-of-day has passed. If + * abstime == 0 use "blocking" wait() semantics on the <mutex> + * passed as a parameter (this is useful if you need to store the + * <Condition> in shared memory). Else, if <abstime> != 0 and the + * call times out before the condition is signaled <wait> returns -1 + * and sets errno to ETIME. + */ int wait (MUTEX &mutex, const ACE_Time_Value *abstime = 0); - // Block on condition or until absolute time-of-day has passed. If - // abstime == 0 use "blocking" wait() semantics on the <mutex> - // passed as a parameter (this is useful if you need to store the - // <Condition> in shared memory). Else, if <abstime> != 0 and the - // call times out before the condition is signaled <wait> returns -1 - // and sets errno to ETIME. + /// Signal one waiting thread. int signal (void); - // Signal one waiting thread. + /// Signal *all* waiting threads. int broadcast (void); - // Signal *all* waiting threads. // = Utility methods. + /// Explicitly destroy the condition variable. int remove (void); - // Explicitly destroy the condition variable. + /// Returns a reference to the underlying mutex_; MUTEX &mutex (void); - // Returns a reference to the underlying mutex_; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. protected: #if defined (CHORUS) + /// This condition resides in shared memory. ACE_cond_t *process_cond_; - // This condition resides in shared memory. + /** + * Remember the name of the condition if we created it so we can + * unlink it when we go away (only the actor that initialized the + * memory can destroy it). + */ const ACE_TCHAR *condname_; - // Remember the name of the condition if we created it so we can - // unlink it when we go away (only the actor that initialized the - // memory can destroy it). #endif /* CHORUS */ + /// Condition variable. ACE_cond_t cond_; - // Condition variable. + /// Reference to mutex lock. MUTEX &mutex_; - // Reference to mutex lock. private: // = Prevent assignment and initialization. @@ -774,30 +814,32 @@ private: ACE_UNIMPLEMENTED_FUNC (ACE_Condition (const ACE_Condition<MUTEX> &)) }; +/** + * @class ACE_Thread_Condition + * + * @brief ACE_Condition variable wrapper that works within processes. + * + * A condition variable enables threads to atomically block and + * test the condition under the protection of a mutual exclu- + * sion lock (mutex) until the condition is satisfied. That is, + * the mutex must have been held by the thread before calling + * wait or signal on the condition. If the condition is false, + * a thread blocks on a condition variable and atomically + * releases the mutex that is waiting for the condition to + * change. If another thread changes the condition, it may wake + * up waiting threads by signaling the associated condition + * variable. The waiting threads, upon awakening, reacquire the + * mutex and re-evaluate the condition. + */ template <class MUTEX> class ACE_Thread_Condition : public ACE_Condition<MUTEX> { - // = TITLE - // ACE_Condition variable wrapper that works within processes. - // - // = DESCRIPTION - // A condition variable enables threads to atomically block and - // test the condition under the protection of a mutual exclu- - // sion lock (mutex) until the condition is satisfied. That is, - // the mutex must have been held by the thread before calling - // wait or signal on the condition. If the condition is false, - // a thread blocks on a condition variable and atomically - // releases the mutex that is waiting for the condition to - // change. If another thread changes the condition, it may wake - // up waiting threads by signaling the associated condition - // variable. The waiting threads, upon awakening, reacquire the - // mutex and re-evaluate the condition. public: // = Initialization method. ACE_Thread_Condition (MUTEX &m, const ACE_TCHAR *name = 0, void *arg = 0); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. @@ -807,11 +849,14 @@ public: #if defined (ACE_HAS_TEMPLATE_TYPEDEFS) +/** + * @class ACE_NULL_SYNCH + * + * @brief Implement a do nothing Synchronization wrapper that + * typedefs the <ACE_Condition> and <ACE_Mutex> to the Null* versions. + */ class ACE_Export ACE_NULL_SYNCH { - // = TITLE - // Implement a do nothing Synchronization wrapper that - // typedefs the <ACE_Condition> and <ACE_Mutex> to the Null* versions. public: typedef ACE_Null_Mutex MUTEX; typedef ACE_Null_Mutex NULL_MUTEX; @@ -827,14 +872,17 @@ public: class ACE_Process_Mutex; +/** + * @class ACE_MT_SYNCH + * + * @brief Implement a default thread safe synchronization wrapper that + * typedefs the <ACE_Condition> and <ACE_Mutex> to the + * <ACE_Condition> and <ACE_Mutex> versions. Note that this + * should be a template, but SunC++ 4.0.1 complains about + * this... + */ class ACE_Export ACE_MT_SYNCH { - // = TITLE - // Implement a default thread safe synchronization wrapper that - // typedefs the <ACE_Condition> and <ACE_Mutex> to the - // <ACE_Condition> and <ACE_Mutex> versions. Note that this - // should be a template, but SunC++ 4.0.1 complains about - // this... public: typedef ACE_Thread_Mutex MUTEX; typedef ACE_Null_Mutex NULL_MUTEX; diff --git a/ace/System_Time.h b/ace/System_Time.h index ca3afa1a7a7..3374d031cac 100644 --- a/ace/System_Time.h +++ b/ace/System_Time.h @@ -1,19 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// System_Time.h -// -// = AUTHOR -// Prashant Jain, Tim H. Harrison and Douglas C. Schmidt -// -// ============================================================================ + + +//============================================================================= +/** + * @file System_Time.h + * + * $Id$ + * + * @author Prashant Jain + * @author Tim H. Harrison and Douglas C. Schmidt + */ +//============================================================================= + #ifndef ACE_SYSTEM_TIME_H #define ACE_SYSTEM_TIME_H @@ -28,56 +26,61 @@ #include "ace/Memory_Pool.h" #include "ace/Malloc_T.h" +/** + * @class ACE_System_Time + * + * @brief Defines the timer services of the OS interface to access the + * system time either on the local host or on the central time + * server in the network. + */ class ACE_Export ACE_System_Time { - // = TITLE - // Defines the timer services of the OS interface to access the - // system time either on the local host or on the central time - // server in the network. public: + /** + * enumeration types to specify mode of synchronization with master + * clock. Jump will set local system time directly (thus possibly + * producing time gaps or ambiguous local system times. Adjust will + * smoothly slow down or speed up the local system clock to reach + * the system time of the master clock. + */ enum Sync_Mode { Jump, Adjust }; - // enumeration types to specify mode of synchronization with master - // clock. Jump will set local system time directly (thus possibly - // producing time gaps or ambiguous local system times. Adjust will - // smoothly slow down or speed up the local system clock to reach - // the system time of the master clock. + /// Default constructor. ACE_System_Time (const ACE_TCHAR *poolname = 0); - // Default constructor. + /// Default destructor. ~ACE_System_Time (void); - // Default destructor. + /// Get the local system time, i.e., the value returned by + /// <ACE_OS::time>. static int get_local_system_time (ACE_UINT32 &time_out); - // Get the local system time, i.e., the value returned by - // <ACE_OS::time>. + /// Get the local system time, i.e., the value returned by + /// <ACE_OS::time>. static int get_local_system_time (ACE_Time_Value &time_out); - // Get the local system time, i.e., the value returned by - // <ACE_OS::time>. + /// Get the system time of the central time server. int get_master_system_time (ACE_UINT32 &time_out); - // Get the system time of the central time server. + /// Get the system time of the central time server. int get_master_system_time (ACE_Time_Value &time_out); - // Get the system time of the central time server. + /// synchronize local system time with the central time server using + /// specified mode. int sync_local_system_time (ACE_System_Time::Sync_Mode mode); - // synchronize local system time with the central time server using - // specified mode. private: typedef ACE_Malloc <ACE_MMAP_MEMORY_POOL, ACE_Null_Mutex> MALLOC; typedef ACE_Allocator_Adapter<MALLOC> ALLOCATOR; + /// Our allocator (used for obtaining system time from shared memory). ALLOCATOR *shmem_; - // Our allocator (used for obtaining system time from shared memory). + /// The name of the pool used by the allocator. ACE_TCHAR poolname_[MAXPATHLEN + 1]; - // The name of the pool used by the allocator. + /// Pointer to delta time kept in shared memory. long *delta_time_; - // Pointer to delta time kept in shared memory. }; #include "ace/post.h" diff --git a/ace/TLI.h b/ace/TLI.h index 8a1fb9e1ff1..f00e22f48fa 100644 --- a/ace/TLI.h +++ b/ace/TLI.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// TLI.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file TLI.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_TLI_H #define ACE_TLI_H @@ -43,26 +40,29 @@ #define ACE_XTI_ATM_DEVICE "/dev/xtisvc0" #endif +/** + * @class ACE_TLI + * + * @brief Defines the member functions for the base class of the + * ACE_TLI abstraction. + */ class ACE_Export ACE_TLI : public ACE_IPC_SAP { - // = TITLE - // Defines the member functions for the base class of the - // ACE_TLI abstraction. public: // = Initialization and termination methods. + /// Initialize a TLI endpoint. ACE_HANDLE open (const char device[], int oflag = O_RDWR, struct t_info *info = 0); - // Initialize a TLI endpoint. + /// Close a TLI endpoint and release resources. int close (void); - // Close a TLI endpoint and release resources. + /// Set underlying protocol options. int set_option (int level, int option, void *optval, int optlen); - // Set underlying protocol options. + /// Get underlying protocol options. int get_option (int level, int option, void *optval, int &optlen); - // Get underlying protocol options. // = Calls to underlying TLI operations. int look (void) const; @@ -71,24 +71,24 @@ public: int sndrel (void) const; int rcvrel (void) const; + /// Return our local endpoint address. int get_local_addr (ACE_Addr &) const; - // Return our local endpoint address. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Ensure we are an abstract class. + /// Default constructor. + /// Destructor. ACE_TLI (void); - // Default constructor. ~ACE_TLI (void); - // Destructor. + /// Initialize a TLI endpoint. ACE_TLI (const char device[], int oflag = O_RDWR, struct t_info *info = 0); - // Initialize a TLI endpoint. private: #if defined (ACE_HAS_SVR4_TLI) diff --git a/ace/TLI_Acceptor.h b/ace/TLI_Acceptor.h index 83dbec0f3b7..2112bf4535c 100644 --- a/ace/TLI_Acceptor.h +++ b/ace/TLI_Acceptor.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// TLI_Acceptor.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file TLI_Acceptor.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_TLI_ACCEPTOR_H #define ACE_TLI_ACCEPTOR_H @@ -32,44 +29,51 @@ // Forward reference... class ACE_TLI_Request_Queue; +/** + * @class ACE_TLI_Acceptor + * + * @brief Defines the member functions for ACE_TLI_Acceptor abstraction. + * + * This class implements the algorithm described in Steve Rago's + * book on System V UNIX network programming. It basically + * makes TLI look like the C++ SOCK_SAP socket wrappers with + * respect to establishing passive-mode listener endpoints. + */ class ACE_Export ACE_TLI_Acceptor : public ACE_TLI { - // = TITLE - // Defines the member functions for ACE_TLI_Acceptor abstraction. - // - // = DESCRIPTION - // This class implements the algorithm described in Steve Rago's - // book on System V UNIX network programming. It basically - // makes TLI look like the C++ SOCK_SAP socket wrappers with - // respect to establishing passive-mode listener endpoints. public: friend class ACE_Request_Queue; // = Initialization and termination methods. + /// Default constructor. ACE_TLI_Acceptor (void); - // Default constructor. + /// Initiate a passive mode socket. ACE_TLI_Acceptor (const ACE_Addr &remote_sap, int reuse_addr = 0, int oflag = O_RDWR, struct t_info *info = 0, int backlog = ACE_DEFAULT_BACKLOG, const char device[] = ACE_TLI_TCP_DEVICE); - // Initiate a passive mode socket. + /// Initiate a passive mode socket. ACE_HANDLE open (const ACE_Addr &remote_sap, int reuse_addr = 0, int oflag = O_RDWR, struct t_info *info = 0, int backlog = ACE_DEFAULT_BACKLOG, const char device[] = ACE_TLI_TCP_DEVICE); - // Initiate a passive mode socket. + /// Close down the acceptor and release resources. int close (void); - // Close down the acceptor and release resources. // = Passive connection acceptance method. + /** + * Accept a new data transfer connection. A <timeout> of 0 means + * block forever, a <timeout> of {0, 0} means poll. <restart> == 1 + * means "restart if interrupted." + */ int accept (ACE_TLI_Stream &new_tli_sap, ACE_Addr *remote_addr = 0, ACE_Time_Value *timeout = 0, @@ -78,38 +82,35 @@ public: int rwflag = 1, netbuf *udata = 0, netbuf *opt = 0); - // Accept a new data transfer connection. A <timeout> of 0 means - // block forever, a <timeout> of {0, 0} means poll. <restart> == 1 - // means "restart if interrupted." // = Meta-type info typedef ACE_INET_Addr PEER_ADDR; typedef ACE_TLI_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Network "device" we are using. const char *device_; - // Network "device" we are using. + /// Number of connections to queue. int backlog_; - // Number of connections to queue. + /// Are we using "tirdwr" mod? int rwflag_; - // Are we using "tirdwr" mod? + /// Handle TLI accept insanity... int handle_async_event (int restart, int rwflag); - // Handle TLI accept insanity... + /// Used for queueing up pending requests. ACE_TLI_Request_Queue *queue_; - // Used for queueing up pending requests. + /// Used for handling disconnects struct t_discon *disp_; - // Used for handling disconnects }; #endif /* ACE_HAS_TLI */ diff --git a/ace/TLI_Connector.h b/ace/TLI_Connector.h index 14417454ddb..35a8e1b0253 100644 --- a/ace/TLI_Connector.h +++ b/ace/TLI_Connector.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// TLI_Connector.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file TLI_Connector.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_TLI_CONNECTOR_H #define ACE_TLI_CONNECTOR_H @@ -27,16 +24,34 @@ #if defined (ACE_HAS_TLI) -class ACE_Export ACE_TLI_Connector +/** + * @class ACE_TLI_Connector + * + * @brief Defines an active connection factory for the ACE_TLI C++ + * wrappers. + */ +class ACE_Export ACE_TLI_Connector { - // = TITLE - // Defines an active connection factory for the ACE_TLI C++ - // wrappers. public: // = Initialization methods. + /// Default constructor. ACE_TLI_Connector (void); - // Default constructor. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + */ ACE_TLI_Connector (ACE_TLI_Stream &new_stream, const ACE_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -49,20 +64,22 @@ public: int rw_flag = 1, struct netbuf *udata = 0, struct netbuf *opt = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + */ int connect (ACE_TLI_Stream &new_stream, const ACE_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -75,40 +92,29 @@ public: int rw_flag = 1, struct netbuf *udata = 0, struct netbuf *opt = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. + /** + * Try to complete a non-blocking connection. + * If connection completion is successful then <new_stream> contains + * the connected ACE_SOCK_Stream. If <remote_sap> is non-NULL then it + * will contain the address of the connected peer. + */ int complete (ACE_TLI_Stream &new_stream, ACE_Addr *remote_sap, ACE_Time_Value *tv); - // Try to complete a non-blocking connection. - // If connection completion is successful then <new_stream> contains - // the connected ACE_SOCK_Stream. If <remote_sap> is non-NULL then it - // will contain the address of the connected peer. + /// Resets any event associations on this handle int reset_new_handle (ACE_HANDLE handle); - // Resets any event associations on this handle // = Meta-type info typedef ACE_INET_Addr PEER_ADDR; typedef ACE_TLI_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if defined (__ACE_INLINE__) diff --git a/ace/TLI_Stream.h b/ace/TLI_Stream.h index ca880d1e8fd..ba5c08299e4 100644 --- a/ace/TLI_Stream.h +++ b/ace/TLI_Stream.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// TLI_Stream.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file TLI_Stream.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_TLI_STREAM_H #define ACE_TLI_STREAM_H @@ -28,92 +25,95 @@ #if defined (ACE_HAS_TLI) +/** + * @class ACE_TLI_Stream + * + * @brief Defines the member functions for ACE_TLI_Stream abstraction. + */ class ACE_Export ACE_TLI_Stream : public ACE_TLI { - // = TITLE - // Defines the member functions for ACE_TLI_Stream abstraction. public: friend class ACE_TLI_Acceptor; friend class ACE_TLI_Connector; // = Initialization and termination methods. + /// Default constructor. ACE_TLI_Stream (void); - // Default constructor. // = TLI-specific shutdown operations. + /// Close down and release resources. int close (void); - // Close down and release resources. + /// Send a release and then await the release from the other side. int active_close (void); - // Send a release and then await the release from the other side. + /// Acknowledge the release from the other side and then send the + /// release to the other side. int passive_close (void); - // Acknowledge the release from the other side and then send the - // release to the other side. + /// Return address of remotely connected peer. int get_remote_addr (ACE_Addr &) const; - // Return address of remotely connected peer. // = timod bindings + /// Send an n byte buffer to the connected socket (uses t_snd(3)). + /// Recv an n byte buffer from the connected socket (uses t_rcv(3)). ssize_t send (const void *buf, size_t n, int flags, const ACE_Time_Value *timeout = 0) const; - // Send an n byte buffer to the connected socket (uses t_snd(3)). ssize_t recv (void *buf, size_t n, int *flags, const ACE_Time_Value *timeout = 0) const; - // Recv an n byte buffer from the connected socket (uses t_rcv(3)). + /// Send exactly n bytes to the connected socket (uses t_snd(3)). + /// Recv exactly n bytes from the connected socket (uses t_rcv(3)). ssize_t send_n (const void *buf, size_t n, int flags, const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0) const; - // Send exactly n bytes to the connected socket (uses t_snd(3)). ssize_t recv_n (void *buf, size_t n, int *flags, const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0) const; - // Recv exactly n bytes from the connected socket (uses t_rcv(3)). // = tirdwr bindings + /// Send an n byte buffer to the connected socket (uses write(2)). ssize_t send (const void *buf, size_t n, const ACE_Time_Value *timeout = 0) const; - // Send an n byte buffer to the connected socket (uses write(2)). + /// Recv an n byte buffer from the connected socket (uses read(2)). ssize_t recv (void *buf, size_t n, const ACE_Time_Value *timeout = 0) const; - // Recv an n byte buffer from the connected socket (uses read(2)). + /// Send n bytes, keep trying until n are sent (uses write(2)). ssize_t send_n (const void *buf, size_t n, const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0) const; - // Send n bytes, keep trying until n are sent (uses write(2)). + /// Recv n bytes, keep trying until n are received (uses read (2)). ssize_t recv_n (void *buf, size_t n, const ACE_Time_Value *timeout = 0, size_t *bytes_transferred = 0) const; - // Recv n bytes, keep trying until n are received (uses read (2)). // = Meta-type info typedef ACE_INET_Addr PEER_ADDR; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Indicates whether the tirdwr module should be pushed int rwflag_; - // Indicates whether the tirdwr module should be pushed // = Get/set rwflag int get_rwflag (void); diff --git a/ace/TP_Reactor.h b/ace/TP_Reactor.h index ab1dcf2078c..d591e51f184 100644 --- a/ace/TP_Reactor.h +++ b/ace/TP_Reactor.h @@ -1,33 +1,31 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// TP_Reactor.h -// -// = DESCRIPTION -// The <ACE_TP_Reactor> (aka, Thread Pool Reactor) uses the -// Leader/Followers pattern to demultiplex events among a pool of -// threads. When using a thread pool reactor, an application -// pre-spawns a _fixed_ number of threads. When these threads -// invoke the <ACE_TP_Reactor>'s <handle_events> method, one thread -// will become the leader and wait for an event. The other -// follower threads will queue up waiting for their turn to become -// the leader. When an event occurs, the leader will pick a -// follower to become the leader and go on to handle the event. -// The consequence of using <ACE_TP_Reactor> is the amortization of -// the costs used to creating threads. The context switching cost -// will also reduce. More over, the total resources used by -// threads are bounded because there are a fixed number of threads. -// -// = AUTHOR -// Irfan Pyarali <irfan@cs.wustl.edu> and Nanbor Wang <nanbor@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file TP_Reactor.h + * + * $Id$ + * + * The <ACE_TP_Reactor> (aka, Thread Pool Reactor) uses the + * Leader/Followers pattern to demultiplex events among a pool of + * threads. When using a thread pool reactor, an application + * pre-spawns a _fixed_ number of threads. When these threads + * invoke the <ACE_TP_Reactor>'s <handle_events> method, one thread + * will become the leader and wait for an event. The other + * follower threads will queue up waiting for their turn to become + * the leader. When an event occurs, the leader will pick a + * follower to become the leader and go on to handle the event. + * The consequence of using <ACE_TP_Reactor> is the amortization of + * the costs used to creating threads. The context switching cost + * will also reduce. More over, the total resources used by + * threads are bounded because there are a fixed number of threads. + * + * + * @author Irfan Pyarali <irfan@cs.wustl.edu> + * @author Nanbor Wang <nanbor@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_TP_REACTOR_H #define ACE_TP_REACTOR_H @@ -40,12 +38,14 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_EH_Dispatch_Info + * + * @brief This structure contains information of the activated event + * handler. + */ class ACE_Export ACE_EH_Dispatch_Info { - // = TITLE - // - // This structure contains information of the activated event - // handler. public: ACE_EH_Dispatch_Info (void); @@ -67,145 +67,150 @@ public: int dispatch_; }; +/** + * @class ACE_TP_Reactor + * + * @brief Specialization of Select Reactor to support thread-pool based + * event dispatching. + * + * One of the short comings of the Select_Reactor in ACE is that + * it did not support a thread pool based event dispatching + * model, similar to the one in WFMO_Reactor. In + * Select_Reactor, only thread can be blocked in <handle_events> + * at any given time. + * A new Reactor has been added to ACE that removes this + * short-coming. TP_Reactor is a specialization of Select + * Reactor to support thread-pool based event dispatching. This + * Reactor takes advantage of the fact that events reported by + * <select> are persistent if not acted upon immediately. It + * works by remembering the event handler that just got + * activated, releasing the internal lock (so that some other + * thread can start waiting in the event loop) and then + * dispatching the event handler outside the context of the + * Reactor lock. + * This Reactor is best suited for situations when the callbacks + * to event handlers can take arbitrarily long and/or a number + * of threads are available to run the event loops. + * Note that callback code in Event Handlers + * (e.g. Event_Handler::handle_input) does not have to be + * modified or made thread-safe for this Reactor. This is + * because an activated Event Handler is suspended in the + * Reactor before the upcall is made and resumed after the + * upcall completes. Therefore, one Event Handler cannot be + * called by multiple threads simultaneously. + */ class ACE_Export ACE_TP_Reactor : public ACE_Select_Reactor { - // = TITLE - // Specialization of Select Reactor to support thread-pool based - // event dispatching. - // - // = DESCRIPTION - // One of the short comings of the Select_Reactor in ACE is that - // it did not support a thread pool based event dispatching - // model, similar to the one in WFMO_Reactor. In - // Select_Reactor, only thread can be blocked in <handle_events> - // at any given time. - // - // A new Reactor has been added to ACE that removes this - // short-coming. TP_Reactor is a specialization of Select - // Reactor to support thread-pool based event dispatching. This - // Reactor takes advantage of the fact that events reported by - // <select> are persistent if not acted upon immediately. It - // works by remembering the event handler that just got - // activated, releasing the internal lock (so that some other - // thread can start waiting in the event loop) and then - // dispatching the event handler outside the context of the - // Reactor lock. - // - // This Reactor is best suited for situations when the callbacks - // to event handlers can take arbitrarily long and/or a number - // of threads are available to run the event loops. - // - // Note that callback code in Event Handlers - // (e.g. Event_Handler::handle_input) does not have to be - // modified or made thread-safe for this Reactor. This is - // because an activated Event Handler is suspended in the - // Reactor before the upcall is made and resumed after the - // upcall completes. Therefore, one Event Handler cannot be - // called by multiple threads simultaneously. public: // = Initialization and termination methods. + /// Initialize <ACE_TP_Reactor> with the default size. ACE_TP_Reactor (ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0, int mask_signals = 1); - // Initialize <ACE_TP_Reactor> with the default size. + /** + * Initialize the <ACE_TP_Reactor> to manage + * <max_number_of_handles>. If <restart> is non-0 then the + * <ACE_Reactor>'s <handle_events> method will be restarted + * automatically when <EINTR> occurs. If <signal_handler> or + * <timer_queue> are non-0 they are used as the signal handler and + * timer queue, respectively. + */ ACE_TP_Reactor (size_t max_number_of_handles, int restart = 0, ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0, int mask_signals = 1); - // Initialize the <ACE_TP_Reactor> to manage - // <max_number_of_handles>. If <restart> is non-0 then the - // <ACE_Reactor>'s <handle_events> method will be restarted - // automatically when <EINTR> occurs. If <signal_handler> or - // <timer_queue> are non-0 they are used as the signal handler and - // timer queue, respectively. // = Event loop drivers. + /** + * This event loop driver that blocks for <max_wait_time> before + * returning. It will return earlier if timer events, I/O events, + * or signal events occur. Note that <max_wait_time> can be 0, in + * which case this method blocks indefinitely until events occur. + * + * <max_wait_time> is decremented to reflect how much time this call + * took. For instance, if a time value of 3 seconds is passed to + * handle_events and an event occurs after 2 seconds, + * <max_wait_time> will equal 1 second. This can be used if an + * application wishes to handle events for some fixed amount of + * time. + * + * Returns the total number of <ACE_Event_Handler>s that were + * dispatched, 0 if the <max_wait_time> elapsed without dispatching + * any handlers, or -1 if something goes wrong. + */ virtual int handle_events (ACE_Time_Value *max_wait_time = 0); - // This event loop driver that blocks for <max_wait_time> before - // returning. It will return earlier if timer events, I/O events, - // or signal events occur. Note that <max_wait_time> can be 0, in - // which case this method blocks indefinitely until events occur. - // - // <max_wait_time> is decremented to reflect how much time this call - // took. For instance, if a time value of 3 seconds is passed to - // handle_events and an event occurs after 2 seconds, - // <max_wait_time> will equal 1 second. This can be used if an - // application wishes to handle events for some fixed amount of - // time. - // - // Returns the total number of <ACE_Event_Handler>s that were - // dispatched, 0 if the <max_wait_time> elapsed without dispatching - // any handlers, or -1 if something goes wrong. virtual int handle_events (ACE_Time_Value &max_wait_time); + /// GET/SET/ADD/CLR the dispatch mask "bit" bound with the <eh> and + /// <mask>. virtual int mask_ops (ACE_Event_Handler *eh, ACE_Reactor_Mask mask, int ops); - // GET/SET/ADD/CLR the dispatch mask "bit" bound with the <eh> and - // <mask>. + /// GET/SET/ADD/CLR the dispatch mask "bit" bound with the <handle> + /// and <mask>. virtual int mask_ops (ACE_HANDLE handle, ACE_Reactor_Mask mask, int ops); - // GET/SET/ADD/CLR the dispatch mask "bit" bound with the <handle> - // and <mask>. + /// Called from handle events static void no_op_sleep_hook (void *); - // Called from handle events + /// Wake up all threads in waiting in the event loop virtual void wakeup_all_threads (void); - // Wake up all threads in waiting in the event loop // = Any thread can perform a <handle_events>, override the owner() // methods to avoid the overhead of setting the owner thread. + /// Set the new owner of the thread and return the old owner. virtual int owner (ACE_thread_t n_id, ACE_thread_t *o_id = 0); - // Set the new owner of the thread and return the old owner. + /// Return the current owner of the thread. virtual int owner (ACE_thread_t *); - // Return the current owner of the thread. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: // = Internal methods that do the actual work. + /** + * Dispatch signal, timer, notification handlers and return possibly + * 1 I/O handler for dispatching. Ideally, it would dispatch nothing, + * and return dispatch information for only one of (signal, timer, + * notification, I/O); however, the reactor mechanism is too enmeshed + * in the timer queue expiry functions and the notification class to + * do this without some significant redesign. + */ int dispatch_i (ACE_Time_Value *max_wait_time, ACE_EH_Dispatch_Info &event); - // Dispatch signal, timer, notification handlers and return possibly - // 1 I/O handler for dispatching. Ideally, it would dispatch nothing, - // and return dispatch information for only one of (signal, timer, - // notification, I/O); however, the reactor mechanism is too enmeshed - // in the timer queue expiry functions and the notification class to - // do this without some significant redesign. int dispatch_i_protected (ACE_Time_Value *max_wait_time, + /// Only really does anything for Win32. Wraps a call to dispatch_i in an + /// ACE_SEH_TRY block. ACE_EH_Dispatch_Info &event); - // Only really does anything for Win32. Wraps a call to dispatch_i in an - // ACE_SEH_TRY block. + /// This method shouldn't get called. virtual void notify_handle (ACE_HANDLE handle, ACE_Reactor_Mask mask, ACE_Handle_Set &, ACE_Event_Handler *eh, ACE_EH_PTMF callback); - // This method shouldn't get called. + /// Notify the appropriate <callback> in the context of the <eh> + /// associated with <handle> that a particular event has occurred. virtual int notify_handle (ACE_EH_Dispatch_Info &dispatch_info); - // Notify the appropriate <callback> in the context of the <eh> - // associated with <handle> that a particular event has occurred. private: + /// Deny access since member-wise won't work... ACE_TP_Reactor (const ACE_TP_Reactor &); ACE_TP_Reactor &operator = (const ACE_TP_Reactor &); - // Deny access since member-wise won't work... }; #if defined (__ACE_INLINE__) diff --git a/ace/TTY_IO.h b/ace/TTY_IO.h index 75e0eff5ced..e716aebe741 100644 --- a/ace/TTY_IO.h +++ b/ace/TTY_IO.h @@ -1,20 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// TTY_IO.h -// -// = DESCRIPTION -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@uci.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file TTY_IO.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@uci.edu> + */ +//============================================================================= + #ifndef ACE_TTY_IO_H #define ACE_TTY_IO_H @@ -29,28 +24,32 @@ #include "ace/DEV_Connector.h" #include "ace/DEV_IO.h" +/** + * @class ACE_TTY_IO + * + * @brief Class definitions for platform specific TTY features. + * + * This class represents an example interface for a specific + * device (a serial line) It extends the capability of the + * underlying DEV_IO class by adding a control method that takes + * a special structure (Serial_Params) as argument to allow a + * comfortable user interface (away from that annoying termios + * structure, which is very specific to UNIX). + */ class ACE_Export ACE_TTY_IO : public ACE_DEV_IO { - // = TITLE - // Class definitions for platform specific TTY features. - // - // = DESCRIPTION - // This class represents an example interface for a specific - // device (a serial line) It extends the capability of the - // underlying DEV_IO class by adding a control method that takes - // a special structure (Serial_Params) as argument to allow a - // comfortable user interface (away from that annoying termios - // structure, which is very specific to UNIX). public: enum Control_Mode { - SETPARAMS, // Set control parameters. - GETPARAMS // Get control parameters. + /// Set control parameters. + SETPARAMS, + /// Get control parameters. + GETPARAMS }; struct Serial_Params { - // Common params + // Common params int baudrate; int parityenb; const char *paritymode; @@ -71,13 +70,13 @@ public: int xofflim; // max bytes in input buffer before xoff }; + /// Interface for reading/writing serial device parameters. int control (Control_Mode cmd, Serial_Params *arg) const; - // Interface for reading/writing serial device parameters. #if defined (ACE_NEEDS_DEV_IO_CONVERSION) + /// This is necessary to pass ACE_TTY_IO as parameter to DEV_Connector. operator ACE_DEV_IO &(); - // This is necessary to pass ACE_TTY_IO as parameter to DEV_Connector. #endif /* ACE_NEEDS_DEV_IO_CONVERSION */ }; diff --git a/ace/Task.h b/ace/Task.h index 0dcb6a7811c..e44978ba19e 100644 --- a/ace/Task.h +++ b/ace/Task.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Task.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Task.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_TASK_H #define ACE_TASK_H @@ -26,85 +23,142 @@ #include "ace/Thread_Manager.h" +/** + * @class ACE_Task_Flags + * + * @brief These flags are used within the ACE_Task. + * + * These flags should be hidden within ACE_Task. Unfortunately, the + * HP/UX C++ compiler can't grok this... Fortunately, there's no + * code defined here, so we don't have to worry about multiple + * definitions. + */ class ACE_Export ACE_Task_Flags { public: - // = TITLE - // These flags are used within the ACE_Task. - // - // = DESCRIPTION - // These flags should be hidden within ACE_Task. Unfortunately, the - // HP/UX C++ compiler can't grok this... Fortunately, there's no - // code defined here, so we don't have to worry about multiple - // definitions. enum { - ACE_READER = 01, // Identifies a Task as being the "reader" in a Module. - ACE_FLUSHDATA = 02, // Just flush data messages in the queue. - ACE_FLUSHALL = 04, // Flush all messages in the Queue. - ACE_FLUSHR = 010, // flush read queue - ACE_FLUSHW = 020, // flush write queue - ACE_FLUSHRW = 030 // flush both queues + /// Identifies a Task as being the "reader" in a Module. + ACE_READER = 01, + /// Just flush data messages in the queue. + ACE_FLUSHDATA = 02, + /// Flush all messages in the Queue. + ACE_FLUSHALL = 04, + /// flush read queue + ACE_FLUSHR = 010, + /// flush write queue + ACE_FLUSHW = 020, + /// flush both queues + ACE_FLUSHRW = 030 }; }; +/** + * @class ACE_Task_Base + * + * @brief Direct base class for the ACE_Task template. + * + * This class factors out the non-template code in order to + * reduce template bloat, as well as to make it possible for the + * <ACE_Thread_Manager> to store <ACE_Task_Base> *'s + * polymorphically. + */ class ACE_Export ACE_Task_Base : public ACE_Service_Object { - // = TITLE - // Direct base class for the ACE_Task template. - // - // = DESCRIPTION - // This class factors out the non-template code in order to - // reduce template bloat, as well as to make it possible for the - // <ACE_Thread_Manager> to store <ACE_Task_Base> *'s - // polymorphically. public: // = Initialization and termination methods. + /// Constructor. ACE_Task_Base (ACE_Thread_Manager * = 0); - // Constructor. + /// Destructor. virtual ~ACE_Task_Base (void); - // Destructor. // = Initialization and termination hooks. // These methods should be overridden by subclasses if you'd like to // provide <Task>-specific initialization and termination behavior. + /// Hook called to open a Task. <args> can be used to pass arbitrary + /// information into <open>. virtual int open (void *args = 0); - // Hook called to open a Task. <args> can be used to pass arbitrary - // information into <open>. + /** + * Hook called from <ACE_Thread_Exit> when during thread exit and from + * the default implemenation of <module_closed>. In general, this + * method shouldn't be called directly by an application, + * particularly if the <Task> is running as an Active Object. + * Instead, a special message should be passed into the <Task> via + * the <put> method defined below, and the <svc> method should + * interpret this as a flag to shut down the <Task>. + */ virtual int close (u_long flags = 0); - // Hook called from <ACE_Thread_Exit> when during thread exit and from - // the default implemenation of <module_closed>. In general, this - // method shouldn't be called directly by an application, - // particularly if the <Task> is running as an Active Object. - // Instead, a special message should be passed into the <Task> via - // the <put> method defined below, and the <svc> method should - // interpret this as a flag to shut down the <Task>. + /** + * Hook called during <ACE_Module::close>. The default + * implementation calls forwards the call to close(1). Please + * notice the changed value of the default argument of <close>. + * This allows tasks to differ between the call has been originated + * from <ACE_Thread_Exit> or from <module_closed>. Be aware that + * close(0) will be also called when a thread associated with the + * ACE_Task instance exits. + */ virtual int module_closed (void); - // Hook called during <ACE_Module::close>. The default - // implementation calls forwards the call to close(1). Please - // notice the changed value of the default argument of <close>. - // This allows tasks to differ between the call has been originated - // from <ACE_Thread_Exit> or from <module_closed>. Be aware that - // close(0) will be also called when a thread associated with the - // ACE_Task instance exits. // = Immediate and deferred processing methods, respectively. // These methods should be overridden by subclasses if you'd like to // provide <Task>-specific message processing behavior. + /// Transfer msg into the queue to handle immediate processing. virtual int put (ACE_Message_Block *, ACE_Time_Value * = 0); - // Transfer msg into the queue to handle immediate processing. + /// Run by a daemon thread to handle deferred processing. virtual int svc (void); - // Run by a daemon thread to handle deferred processing. // = Active object activation method. + /** + * Turn the task into an active object, i.e., having <n_threads> of + * control, all running at the <priority> level (see below) with the + * same <grp_id>, all of which invoke <Task::svc>. Returns -1 if + * failure occurs, returns 1 if Task is already an active object and + * <force_active> is false (i.e., do *not* create a new thread in + * this case), and returns 0 if Task was not already an active + * object and a thread is created successfully or thread is an + * active object and <force_active> is true. Note that if + * <force_active> is true and there are already threads spawned in + * this <Task>, the <grp_id> parameter is ignored and the <grp_id> + * of any newly activated thread(s) will inherit the existing + * <grp_id> of the existing thread(s) in the <Task>. + * + * The <{flags}> are a bitwise-OR of the following: + * = BEGIN<INDENT> + * THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED, + * THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED, + * THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO, + * THR_SCHED_RR, THR_SCHED_DEFAULT + * = END<INDENT> + * + * By default, or if <{priority}> is set to + * ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for + * the given scheduling policy (specified in <{flags}>, e.g., + * <THR_SCHED_DEFAULT>) is used. This value is calculated + * dynamically, and is the median value between the minimum and + * maximum priority values for the given policy. If an explicit + * value is given, it is used. Note that actual priority values are + * EXTREMEMLY implementation-dependent, and are probably best + * avoided. + * + * If <thread_handles> != 0 it is assumed to be an array of <n> + * thread_handles that will be assigned the values of the thread + * handles being spawned. Returns -1 on failure (<errno> will + * explain...), otherwise returns the group id of the threads. + * + * If <stack> != 0 it is assumed to be an array of <n> pointers to + * the base of the stacks to use for the threads being spawned. + * Likewise, if <stack_size> != 0 it is assumed to be an array of + * <n> values indicating how big each of the corresponding <stack>s + * are. + */ virtual int activate (long flags = THR_NEW_LWP | THR_JOINABLE, int n_threads = 1, int force_active = 0, @@ -115,117 +169,80 @@ public: void *stack[] = 0, size_t stack_size[] = 0, ACE_thread_t thread_ids[] = 0); - // Turn the task into an active object, i.e., having <n_threads> of - // control, all running at the <priority> level (see below) with the - // same <grp_id>, all of which invoke <Task::svc>. Returns -1 if - // failure occurs, returns 1 if Task is already an active object and - // <force_active> is false (i.e., do *not* create a new thread in - // this case), and returns 0 if Task was not already an active - // object and a thread is created successfully or thread is an - // active object and <force_active> is true. Note that if - // <force_active> is true and there are already threads spawned in - // this <Task>, the <grp_id> parameter is ignored and the <grp_id> - // of any newly activated thread(s) will inherit the existing - // <grp_id> of the existing thread(s) in the <Task>. - // - // The <{flags}> are a bitwise-OR of the following: - // = BEGIN<INDENT> - // THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED, - // THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED, - // THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO, - // THR_SCHED_RR, THR_SCHED_DEFAULT - // = END<INDENT> - // - // By default, or if <{priority}> is set to - // ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for - // the given scheduling policy (specified in <{flags}>, e.g., - // <THR_SCHED_DEFAULT>) is used. This value is calculated - // dynamically, and is the median value between the minimum and - // maximum priority values for the given policy. If an explicit - // value is given, it is used. Note that actual priority values are - // EXTREMEMLY implementation-dependent, and are probably best - // avoided. - // - // If <thread_handles> != 0 it is assumed to be an array of <n> - // thread_handles that will be assigned the values of the thread - // handles being spawned. Returns -1 on failure (<errno> will - // explain...), otherwise returns the group id of the threads. - // - // If <stack> != 0 it is assumed to be an array of <n> pointers to - // the base of the stacks to use for the threads being spawned. - // Likewise, if <stack_size> != 0 it is assumed to be an array of - // <n> values indicating how big each of the corresponding <stack>s - // are. + /// Wait for all threads running in this task to exit. virtual int wait (void); - // Wait for all threads running in this task to exit. // = Suspend/resume a Task. // Note that these methods are not portable and should be avoided // since they are inherently error-prone to use. They are only here // for (the rare) applications that know how to use them correctly. + /// Suspend a task. + /// Resume a suspended task. virtual int suspend (void); - // Suspend a task. virtual int resume (void); - // Resume a suspended task. + /// Get the current group id. int grp_id (void) const; - // Get the current group id. + /// Set the current group id. void grp_id (int); - // Set the current group id. + /// Gets the thread manager associated with this Task. ACE_Thread_Manager *thr_mgr (void) const; - // Gets the thread manager associated with this Task. + /// Set the thread manager associated with this Task. void thr_mgr (ACE_Thread_Manager *); - // Set the thread manager associated with this Task. + /// True if queue is a reader, else false. int is_reader (void) const; - // True if queue is a reader, else false. + /// True if queue is a writer, else false. int is_writer (void) const; - // True if queue is a writer, else false. + /** + * Returns the number of threads currently running within a task. + * If we're a passive object this value is 0, else it's greater than + * 0. + */ size_t thr_count (void) const; - // Returns the number of threads currently running within a task. - // If we're a passive object this value is 0, else it's greater than - // 0. + /// Atomically decrement the thread count by 1. This should only be + /// called by the <ACE_Thread_Exit> class destructor. void thr_count_dec (void); - // Atomically decrement the thread count by 1. This should only be - // called by the <ACE_Thread_Exit> class destructor. + /// Routine that runs the service routine as a daemon thread. static void *svc_run (void *); - // Routine that runs the service routine as a daemon thread. + /// Cleanup hook that is called when a thread exits to gracefully + /// shutdown an <ACE_Task>. static void cleanup (void *object, void *params); - // Cleanup hook that is called when a thread exits to gracefully - // shutdown an <ACE_Task>. // = Internal data (should be private...). // private: + /** + * Count of the number of threads running within the task. If this + * value is great than 0 then we're an active object and the value + * of <thr_count_> is the number of active threads at this instant. + * If the value == 0, then we're a passive object. + */ size_t thr_count_; - // Count of the number of threads running within the task. If this - // value is great than 0 then we're an active object and the value - // of <thr_count_> is the number of active threads at this instant. - // If the value == 0, then we're a passive object. + /// Multi-threading manager. ACE_Thread_Manager *thr_mgr_; - // Multi-threading manager. + /// ACE_Task flags. u_long flags_; - // ACE_Task flags. + /// This maintains the group id of the Task. int grp_id_; - // This maintains the group id of the Task. #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) + /// Protect the state of a Task during concurrent operations, but + /// only if we're configured as MT safe... ACE_Thread_Mutex lock_; - // Protect the state of a Task during concurrent operations, but - // only if we're configured as MT safe... #endif /* ACE_MT_SAFE */ private: diff --git a/ace/Task_T.h b/ace/Task_T.h index 3374fb6d42a..4545465c460 100644 --- a/ace/Task_T.h +++ b/ace/Task_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Task_T.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Task_T.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_TASK_T_H #define ACE_TASK_T_H @@ -30,36 +27,40 @@ // Forward decls... template <ACE_SYNCH_DECL> class ACE_Module; +/** + * @class ACE_Task + * + * @brief Primary interface for application message processing, as well + * as input and output message queueing. + * + * This class serves as the basis for passive and active objects + * in ACE. + */ template <ACE_SYNCH_DECL> class ACE_Task : public ACE_Task_Base { - // = TITLE - // Primary interface for application message processing, as well - // as input and output message queueing. - // - // = DESCRIPTION - // This class serves as the basis for passive and active objects - // in ACE. public: friend class ACE_Module<ACE_SYNCH_USE>; friend class ACE_Module_Type; // = Initialization/termination methods. + /** + * Initialize a Task, supplying a thread manager and a message + * queue. If the user doesn't supply a ACE_Message_Queue pointer + * then we'll allocate one dynamically. Otherwise, we'll use the + * one passed as a parameter. + */ ACE_Task (ACE_Thread_Manager *thr_mgr = 0, ACE_Message_Queue<ACE_SYNCH_USE> *mq = 0); - // Initialize a Task, supplying a thread manager and a message - // queue. If the user doesn't supply a ACE_Message_Queue pointer - // then we'll allocate one dynamically. Otherwise, we'll use the - // one passed as a parameter. + /// Destructor. virtual ~ACE_Task (void); - // Destructor. + /// Gets the message queue associated with this task. ACE_Message_Queue<ACE_SYNCH_USE> *msg_queue (void); - // Gets the message queue associated with this task. + /// Sets the message queue associated with this task. void msg_queue (ACE_Message_Queue<ACE_SYNCH_USE> *); - // Sets the message queue associated with this task. public: // Should be protected: // = Message queue manipulation methods. @@ -73,76 +74,82 @@ public: // Should be protected: // signal occurs, or if the time specified in timeout elapses, (in // which case errno = EWOULDBLOCK). + /// Insert message into the message queue. Note that <timeout> uses + /// <{absolute}> time rather than <{relative}> time. int putq (ACE_Message_Block *, ACE_Time_Value *timeout = 0); - // Insert message into the message queue. Note that <timeout> uses - // <{absolute}> time rather than <{relative}> time. + /// Extract the first message from the queue (blocking). Note that + /// <timeout> uses <{absolute}> time rather than <{relative}> time. int getq (ACE_Message_Block *&mb, ACE_Time_Value *timeout = 0); - // Extract the first message from the queue (blocking). Note that - // <timeout> uses <{absolute}> time rather than <{relative}> time. + /// Return a message to the queue. Note that <timeout> uses + /// <{absolute}> time rather than <{relative}> time. int ungetq (ACE_Message_Block *, ACE_Time_Value *timeout = 0); - // Return a message to the queue. Note that <timeout> uses - // <{absolute}> time rather than <{relative}> time. + /** + * Turn the message around and send it back down the Stream. Note + * that <timeout> uses <{absolute}> time rather than <{relative}> + * time. + */ int reply (ACE_Message_Block *, ACE_Time_Value *timeout = 0); - // Turn the message around and send it back down the Stream. Note - // that <timeout> uses <{absolute}> time rather than <{relative}> - // time. + /** + * Transfer message to the adjacent ACE_Task in a ACE_Stream. Note + * that <timeout> uses <{absolute}> time rather than <{relative}> + * time. + */ int put_next (ACE_Message_Block *msg, ACE_Time_Value *timeout = 0); - // Transfer message to the adjacent ACE_Task in a ACE_Stream. Note - // that <timeout> uses <{absolute}> time rather than <{relative}> - // time. + /// Tests whether we can enqueue a message without blocking. int can_put (ACE_Message_Block *); - // Tests whether we can enqueue a message without blocking. // = ACE_Task utility routines to identify names et al. + /// Return the name of the enclosing Module if there's one associated + /// with the Task, else returns 0. const ACE_TCHAR *name (void) const; - // Return the name of the enclosing Module if there's one associated - // with the Task, else returns 0. // = Pointers to next ACE_Task_Base (if ACE is part of an ACE_Stream). + /// Get next Task pointer. + /// Set next Task pointer. ACE_Task<ACE_SYNCH_USE> *next (void); - // Get next Task pointer. void next (ACE_Task<ACE_SYNCH_USE> *); - // Set next Task pointer. + /// Return the Task's sibling if there's one associated with the + /// Task's Module, else returns 0. ACE_Task<ACE_SYNCH_USE> *sibling (void); - // Return the Task's sibling if there's one associated with the - // Task's Module, else returns 0. + /// Return the Task's Module if there is one, else returns 0. ACE_Module<ACE_SYNCH_USE> *module (void) const; - // Return the Task's Module if there is one, else returns 0. + /** + * Flush the queue. Note that if this conflicts with the C++ + * iostream <flush> function, just rewrite the iostream function as + * ::<flush>. + */ int flush (u_long flag = ACE_Task_Flags::ACE_FLUSHALL); - // Flush the queue. Note that if this conflicts with the C++ - // iostream <flush> function, just rewrite the iostream function as - // ::<flush>. // = Special routines corresponding to certain message types. + /// Manipulate watermarks. void water_marks (ACE_IO_Cntl_Msg::ACE_IO_Cntl_Cmds, size_t); - // Manipulate watermarks. + /// Queue of messages on the ACE_Task.. ACE_Message_Queue<ACE_SYNCH_USE> *msg_queue_; - // Queue of messages on the ACE_Task.. + /// 1 if should delete Message_Queue, 0 otherwise. int delete_msg_queue_; - // 1 if should delete Message_Queue, 0 otherwise. + /// Back-pointer to the enclosing module. ACE_Module<ACE_SYNCH_USE> *mod_; - // Back-pointer to the enclosing module. + /// Pointer to adjacent ACE_Task. ACE_Task<ACE_SYNCH_USE> *next_; - // Pointer to adjacent ACE_Task. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: diff --git a/ace/Test_and_Set.h b/ace/Test_and_Set.h index 27964034855..83bb57e329d 100644 --- a/ace/Test_and_Set.h +++ b/ace/Test_and_Set.h @@ -1,4 +1,14 @@ -// $Id$ + +//============================================================================= +/** + * @file Test_and_Set.h + * + * $Id$ + * + * @author Priyanka Gontla <pgontla@ece.uci.edu> + */ +//============================================================================= + #ifndef ACE_TEST_AND_SET_H #define ACE_TEST_AND_SET_H @@ -10,41 +20,44 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Test_and_Set + * + * @brief Implements the classic ``test and set'' operation. + * + * + * This class keeps track of the status of <is_set_>, which can + * be set based on various events (such as receipt of a + * signal). This class is derived from <ACE_Event_Handler> so + * that it can be "signaled" by a Reactor when a signal occurs. + * We assume that <TYPE> is a data type that can be assigned the + * value 0 or 1. + */ template <class ACE_LOCK, class TYPE> class ACE_Export ACE_Test_and_Set : public ACE_Event_Handler { public: - // = TITLE - // Implements the classic ``test and set'' operation. - // - // = DESCRIPTION - // This class keeps track of the status of <is_set_>, which can - // be set based on various events (such as receipt of a - // signal). This class is derived from <ACE_Event_Handler> so - // that it can be "signaled" by a Reactor when a signal occurs. - // We assume that <TYPE> is a data type that can be assigned the - // value 0 or 1. ACE_Test_and_Set (TYPE initial_value = 0); + /// Returns true if we are set, else false. TYPE is_set (void) const; - // Returns true if we are set, else false. + /// Sets the <is_set_> status, returning the original value of + /// <is_set_>. TYPE set (TYPE); - // Sets the <is_set_> status, returning the original value of - // <is_set_>. + /// Called when object is signaled by OS (either via UNIX signals or + /// when a Win32 object becomes signaled). virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0); - // Called when object is signaled by OS (either via UNIX signals or - // when a Win32 object becomes signaled). private: + /// Keeps track of our state. TYPE is_set_; - // Keeps track of our state. + /// Protect the state from race conditions. ACE_LOCK lock_; - // Protect the state from race conditions. }; #if defined (__ACE_INLINE__) diff --git a/ace/Thread.h b/ace/Thread.h index 0f76790c930..9473d3ab498 100644 --- a/ace/Thread.h +++ b/ace/Thread.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Thread.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Thread.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_THREAD_H #define ACE_THREAD_H @@ -25,19 +22,50 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Thread + * + * @brief Provides a wrapper for threads. + * + * This class provides a common interface that is mapped onto + * POSIX Pthreads, Solaris threads, Win32 threads, VxWorks + * threads, or pSoS threads. Note, however, that it is + * generally a better idea to use the <ACE_Thread_Manager> + * programming API rather than the <ACE_Thread> API since the + * thread manager is more powerful. + */ class ACE_Export ACE_Thread { - // = TITLE - // Provides a wrapper for threads. - // - // = DESCRIPTION - // This class provides a common interface that is mapped onto - // POSIX Pthreads, Solaris threads, Win32 threads, VxWorks - // threads, or pSoS threads. Note, however, that it is - // generally a better idea to use the <ACE_Thread_Manager> - // programming API rather than the <ACE_Thread> API since the - // thread manager is more powerful. public: + /** + * Creates a new thread having <flags> attributes and running <func> + * with <args> (if <thread_adapter> is non-0 then <func> and <args> + * are ignored and are obtained from <thread_adapter>). <thr_id> + * and <t_handle> are set to the thread's ID and handle (?), + * respectively. The thread runs at <priority> priority (see + * below). + * + * The <flags> are a bitwise-OR of the following: + * = BEGIN<INDENT> + * THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED, + * THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED, + * THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO, + * THR_SCHED_RR, THR_SCHED_DEFAULT + * = END<INDENT> + * + * By default, or if <priority> is set to + * ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for + * the given scheduling policy (specified in <flags}>, e.g., + * <THR_SCHED_DEFAULT>) is used. This value is calculated + * dynamically, and is the median value between the minimum and + * maximum priority values for the given policy. If an explicit + * value is given, it is used. Note that actual priority values are + * EXTREMEMLY implementation-dependent, and are probably best + * avoided. + * + * Note that <thread_adapter> is always deleted by <thr_create>, + * therefore it must be allocated with global operator new. + */ static int spawn (ACE_THR_FUNC func, void *arg = 0, long flags = THR_NEW_LWP | THR_JOINABLE, @@ -47,34 +75,21 @@ public: void *stack = 0, size_t stack_size = 0, ACE_Thread_Adapter *thread_adapter = 0); - // Creates a new thread having <flags> attributes and running <func> - // with <args> (if <thread_adapter> is non-0 then <func> and <args> - // are ignored and are obtained from <thread_adapter>). <thr_id> - // and <t_handle> are set to the thread's ID and handle (?), - // respectively. The thread runs at <priority> priority (see - // below). - // - // The <flags> are a bitwise-OR of the following: - // = BEGIN<INDENT> - // THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED, - // THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED, - // THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO, - // THR_SCHED_RR, THR_SCHED_DEFAULT - // = END<INDENT> - // - // By default, or if <priority> is set to - // ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for - // the given scheduling policy (specified in <flags}>, e.g., - // <THR_SCHED_DEFAULT>) is used. This value is calculated - // dynamically, and is the median value between the minimum and - // maximum priority values for the given policy. If an explicit - // value is given, it is used. Note that actual priority values are - // EXTREMEMLY implementation-dependent, and are probably best - // avoided. - // - // Note that <thread_adapter> is always deleted by <thr_create>, - // therefore it must be allocated with global operator new. + /** + * Spawn N new threads, which execute <func> with argument <arg> (if + * <thread_adapter> is non-0 then <func> and <args> are ignored and + * are obtained from <thread_adapter>). If <stack> != 0 it is + * assumed to be an array of <n> pointers to the base of the stacks + * to use for the threads being spawned. Likewise, if <stack_size> + * != 0 it is assumed to be an array of <n> values indicating how + * big each of the corresponding <stack>s are. Returns the number + * of threads actually spawned (if this doesn't equal the number + * requested then something has gone wrong and <errno> will + * explain...). + * + * See also <spawn>. + */ static int spawn_n (size_t n, ACE_THR_FUNC func, void *arg = 0, @@ -83,19 +98,25 @@ public: void *stack[] = 0, size_t stack_size[] = 0, ACE_Thread_Adapter *thread_adapter = 0); - // Spawn N new threads, which execute <func> with argument <arg> (if - // <thread_adapter> is non-0 then <func> and <args> are ignored and - // are obtained from <thread_adapter>). If <stack> != 0 it is - // assumed to be an array of <n> pointers to the base of the stacks - // to use for the threads being spawned. Likewise, if <stack_size> - // != 0 it is assumed to be an array of <n> values indicating how - // big each of the corresponding <stack>s are. Returns the number - // of threads actually spawned (if this doesn't equal the number - // requested then something has gone wrong and <errno> will - // explain...). - // - // See also <spawn>. + /** + * Spawn <n> new threads, which execute <func> with argument <arg> + * (if <thread_adapter> is non-0 then <func> and <args> are ignored + * and are obtained from <thread_adapter>). The thread_ids of + * successfully spawned threads will be placed into the <thread_ids> + * buffer (which must be the same size as <n>). If <stack> != 0 it + * is assumed to be an array of <n> pointers to the base of the + * stacks to use for the threads being spawned. If <stack_size> != + * 0 it is assumed to be an array of <n> values indicating how big + * each of the corresponding <stack>s are. If <thread_handles> != 0 + * it is assumed to be an array of <n> thread_handles that will be + * assigned the values of the thread handles being spawned. Returns + * the number of threads actually spawned (if this doesn't equal the + * number requested then something has gone wrong and <errno> will + * explain...). + * + * See also <spawn>. + */ static int spawn_n (ACE_thread_t thread_ids[], size_t n, ACE_THR_FUNC func, @@ -106,73 +127,59 @@ public: size_t stack_size[] = 0, ACE_hthread_t thread_handles[] = 0, ACE_Thread_Adapter *thread_adapter = 0); - // Spawn <n> new threads, which execute <func> with argument <arg> - // (if <thread_adapter> is non-0 then <func> and <args> are ignored - // and are obtained from <thread_adapter>). The thread_ids of - // successfully spawned threads will be placed into the <thread_ids> - // buffer (which must be the same size as <n>). If <stack> != 0 it - // is assumed to be an array of <n> pointers to the base of the - // stacks to use for the threads being spawned. If <stack_size> != - // 0 it is assumed to be an array of <n> values indicating how big - // each of the corresponding <stack>s are. If <thread_handles> != 0 - // it is assumed to be an array of <n> thread_handles that will be - // assigned the values of the thread handles being spawned. Returns - // the number of threads actually spawned (if this doesn't equal the - // number requested then something has gone wrong and <errno> will - // explain...). - // - // See also <spawn>. + /// Wait for one or more threads to exit. static int join (ACE_thread_t, ACE_thread_t *, void **status = 0); - // Wait for one or more threads to exit. + /// Wait for one thread to exit. static int join (ACE_hthread_t, void ** = 0); - // Wait for one thread to exit. + /// Continue the execution of a previously suspended thread. static int resume (ACE_hthread_t); - // Continue the execution of a previously suspended thread. + /// Suspend the execution of a particular thread. static int suspend (ACE_hthread_t); - // Suspend the execution of a particular thread. + /// Get the priority of a particular thread. static int getprio (ACE_hthread_t, int &prio); - // Get the priority of a particular thread. + /// Set the priority of a particular thread. static int setprio (ACE_hthread_t, int prio); - // Set the priority of a particular thread. + /// Send a signal to the thread. static int kill (ACE_thread_t, int signum); - // Send a signal to the thread. + /// Yield the thread to another. static void yield (void); - // Yield the thread to another. + /** + * Return the unique kernel handle of the thread. Note that on + * Win32 this is actually a pseudohandle, which cannot be shared + * with other processes or waited on by threads. To locate the real + * handle, please use the <ACE_Thread_Manager::thr_self> method. + */ static void self (ACE_hthread_t &t_handle); - // Return the unique kernel handle of the thread. Note that on - // Win32 this is actually a pseudohandle, which cannot be shared - // with other processes or waited on by threads. To locate the real - // handle, please use the <ACE_Thread_Manager::thr_self> method. + /// Return the unique ID of the thread. static ACE_thread_t self (void); - // Return the unique ID of the thread. + /// Exit the current thread and return "status". + /// Should _not_ be called by main thread. static void exit (void *status = 0); - // Exit the current thread and return "status". - // Should _not_ be called by main thread. + /// Get the LWP concurrency level of the process. static int getconcurrency (void); - // Get the LWP concurrency level of the process. + /// Set the LWP concurrency level of the process. static int setconcurrency (int new_level); - // Set the LWP concurrency level of the process. + /// Change and/or examine calling thread's signal mask. static int sigsetmask (int how, const sigset_t *sigset, sigset_t *osigset = 0); - // Change and/or examine calling thread's signal mask. static int keycreate (ACE_thread_key_t *keyp, #if defined (ACE_HAS_THR_C_DEST) @@ -180,46 +187,50 @@ public: #else ACE_THR_DEST destructor, #endif /* ACE_HAS_THR_C_DEST */ + /** + * Allocates a <keyp> that is used to identify data that is specific + * to each thread in the process. The key is global to all threads + * in the process. + */ void * = 0); - // Allocates a <keyp> that is used to identify data that is specific - // to each thread in the process. The key is global to all threads - // in the process. + /// Free up the key so that other threads can reuse it. static int keyfree (ACE_thread_key_t key); - // Free up the key so that other threads can reuse it. + /// Bind value to the thread-specific data key, <key>, for the calling + /// thread. static int setspecific (ACE_thread_key_t key, void *value); - // Bind value to the thread-specific data key, <key>, for the calling - // thread. + /// Stores the current value bound to <key> for the calling thread + /// into the location pointed to by <valuep>. static int getspecific (ACE_thread_key_t key, void **valuep); - // Stores the current value bound to <key> for the calling thread - // into the location pointed to by <valuep>. + /// Disable thread cancellation. static int disablecancel (struct cancel_state *old_state); - // Disable thread cancellation. + /// Enable thread cancellation. static int enablecancel (struct cancel_state *old_state, int flag); - // Enable thread cancellation. + /// Set the cancellation state. static int setcancelstate (struct cancel_state &new_state, struct cancel_state *old_state); - // Set the cancellation state. + /** + * Cancel a thread. Note that this method is only portable on + * platforms, such as POSIX pthreads, that support thread + * cancellation. + */ static int cancel (ACE_thread_t t_id); - // Cancel a thread. Note that this method is only portable on - // platforms, such as POSIX pthreads, that support thread - // cancellation. + /// Test the cancel. static void testcancel (void); - // Test the cancel. private: + /// Ensure that we don't get instantiated. ACE_Thread (void); - // Ensure that we don't get instantiated. }; #if defined (__ACE_INLINE__) diff --git a/ace/Thread_Adapter.h b/ace/Thread_Adapter.h index e2baa67066a..6bf0e1915af 100644 --- a/ace/Thread_Adapter.h +++ b/ace/Thread_Adapter.h @@ -1,17 +1,14 @@ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Thread_Adapter.h -// -// = AUTHOR -// Carlos O'Ryan <coryan@uci.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Thread_Adapter.h + * + * $Id$ + * + * @author Carlos O'Ryan <coryan@uci.edu> + */ +//============================================================================= + #ifndef ACE_THREAD_ADAPTER_H #define ACE_THREAD_ADAPTER_H @@ -27,21 +24,23 @@ class ACE_Thread_Manager; class ACE_Thread_Descriptor; +/** + * @class ACE_Thread_Adapter + * + * @brief Converts a C++ function into a function <ace_thread_adapter> + * function that can be called from a thread creation routine + * (e.g., <pthread_create> or <_beginthreadex>) that expects an + * extern "C" entry point. This class also makes it possible to + * transparently provide hooks to register a thread with an + * <ACE_Thread_Manager>. + * + * This class is used in <ACE_OS::thr_create>. In general, the + * thread that creates an object of this class is different from + * the thread that calls <invoke> on this object. Therefore, + * the <invoke> method is responsible for deleting itself. + */ class ACE_Export ACE_Thread_Adapter : public ACE_Base_Thread_Adapter { - // = TITLE - // Converts a C++ function into a function <ace_thread_adapter> - // function that can be called from a thread creation routine - // (e.g., <pthread_create> or <_beginthreadex>) that expects an - // extern "C" entry point. This class also makes it possible to - // transparently provide hooks to register a thread with an - // <ACE_Thread_Manager>. - // - // = DESCRIPTION - // This class is used in <ACE_OS::thr_create>. In general, the - // thread that creates an object of this class is different from - // the thread that calls <invoke> on this object. Therefore, - // the <invoke> method is responsible for deleting itself. public: ACE_Thread_Adapter (ACE_THR_FUNC user_func, void *arg, @@ -52,32 +51,34 @@ public: , ACE_SEH_EXCEPT_HANDLER selector = 0, ACE_SEH_EXCEPT_HANDLER handler = 0 # endif /* ACE_HAS_WIN32_STRUCTURAL_EXCEPTIONS */ + /// Constructor. ); - // Constructor. + /** + * Execute the <user_func_> with the <arg>. This function deletes + * <this>, thereby rendering the object useless after the call + * returns. + */ virtual void *invoke (void); - // Execute the <user_func_> with the <arg>. This function deletes - // <this>, thereby rendering the object useless after the call - // returns. + /// Accessor for the optional <Thread_Manager>. ACE_Thread_Manager *thr_mgr (void); - // Accessor for the optional <Thread_Manager>. private: + /// Ensure that this object must be allocated on the heap. ~ACE_Thread_Adapter (void); - // Ensure that this object must be allocated on the heap. + /// Called by invoke, mainly here to separate the SEH stuff because + /// SEH on Win32 doesn't compile with local vars with destructors. virtual void *invoke_i (void); - // Called by invoke, mainly here to separate the SEH stuff because - // SEH on Win32 doesn't compile with local vars with destructors. private: + /// Optional thread manager. ACE_Thread_Manager *thr_mgr_; - // Optional thread manager. + /// Friend declaration to avoid compiler warning: only defines a private + /// destructor and has no friends. friend class ACE_Thread_Adapter_Has_Private_Destructor; - // Friend declaration to avoid compiler warning: only defines a private - // destructor and has no friends. }; # if defined (ACE_HAS_INLINED_OSCALLS) diff --git a/ace/Thread_Control.h b/ace/Thread_Control.h index 669eeb4d0a5..fbf8f0f213f 100644 --- a/ace/Thread_Control.h +++ b/ace/Thread_Control.h @@ -1,17 +1,14 @@ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Thread_Control.h -// -// = AUTHOR -// Carlos O'Ryan <coryan@uci.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Thread_Control.h + * + * $Id$ + * + * @author Carlos O'Ryan <coryan@uci.edu> + */ +//============================================================================= + #ifndef ACE_THREAD_CONTROL_H #define ACE_THREAD_CONTROL_H @@ -29,66 +26,67 @@ class ACE_Thread_Manager; +/** + * @class ACE_Thread_Control + * + * @brief Used to keep track of a thread's activities within its entry + * point function. + * + * A <ACE_Thread_Manager> uses this class to ensure that threads + * it spawns automatically register and unregister themselves + * with it. + * This class can be stored in thread-specific storage using the + * <ACE_TSS> wrapper. When a thread exits the + * <ACE_TSS::cleanup> function deletes this object, thereby + * ensuring that it gets removed from its associated + * <ACE_Thread_Manager>. + */ class ACE_Export ACE_Thread_Control { - // = TITLE - // Used to keep track of a thread's activities within its entry - // point function. - // - // = DESCRIPTION - // A <ACE_Thread_Manager> uses this class to ensure that threads - // it spawns automatically register and unregister themselves - // with it. - // - // This class can be stored in thread-specific storage using the - // <ACE_TSS> wrapper. When a thread exits the - // <ACE_TSS::cleanup> function deletes this object, thereby - // ensuring that it gets removed from its associated - // <ACE_Thread_Manager>. public: + /// Initialize the thread control object. If <insert> != 0, then + /// register the thread with the Thread_Manager. ACE_Thread_Control (ACE_Thread_Manager *tm = 0, int insert = 0); - // Initialize the thread control object. If <insert> != 0, then - // register the thread with the Thread_Manager. + /// Remove the thread from its associated <Thread_Manager> and exit + /// the thread if <do_thr_exit> is enabled. ~ACE_Thread_Control (void); - // Remove the thread from its associated <Thread_Manager> and exit - // the thread if <do_thr_exit> is enabled. + /// Remove this thread from its associated <Thread_Manager> and exit + /// the thread if <do_thr_exit> is enabled. void *exit (void *status, int do_thr_exit); - // Remove this thread from its associated <Thread_Manager> and exit - // the thread if <do_thr_exit> is enabled. + /// Store the <Thread_Manager> and use it to register ourselves for + /// correct shutdown. int insert (ACE_Thread_Manager *tm, int insert = 0); - // Store the <Thread_Manager> and use it to register ourselves for - // correct shutdown. + /// Returns the current <Thread_Manager>. ACE_Thread_Manager *thr_mgr (void); - // Returns the current <Thread_Manager>. + /// Atomically set a new <Thread_Manager> and return the old + /// <Thread_Manager>. ACE_Thread_Manager *thr_mgr (ACE_Thread_Manager *); - // Atomically set a new <Thread_Manager> and return the old - // <Thread_Manager>. + /// Set the exit status (and return existing status). void *status (void *status); - // Set the exit status (and return existing status). + /// Get the current exit status. void *status (void); - // Get the current exit status. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to the thread manager for this block of code. ACE_Thread_Manager *tm_; - // Pointer to the thread manager for this block of code. + /// Keeps track of the exit status for the thread. void *status_; - // Keeps track of the exit status for the thread. }; # if defined (ACE_HAS_INLINED_OSCALLS) diff --git a/ace/Thread_Exit.h b/ace/Thread_Exit.h index 6bb692a09b5..5b87817ffaa 100644 --- a/ace/Thread_Exit.h +++ b/ace/Thread_Exit.h @@ -1,17 +1,14 @@ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Thread_Exit.h -// -// = AUTHOR -// Carlos O'Ryan <coryan@uci.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Thread_Exit.h + * + * $Id$ + * + * @author Carlos O'Ryan <coryan@uci.edu> + */ +//============================================================================= + #ifndef ACE_THREAD_EXIT_H #define ACE_THREAD_EXIT_H @@ -26,79 +23,86 @@ #include "ace/OS.h" #include "ace/Thread_Control.h" +/** + * @class ACE_Thread_Exit + * + * @brief Keep exit information for a Thread in thread specific storage. + * so that the thread-specific exit hooks will get called no + * matter how the thread exits (e.g., via <ACE_Thread::exit>, C++ + * or Win32 exception, "falling off the end" of the thread entry + * point function, etc.). + * + * This clever little helper class is stored in thread-specific + * storage using the <ACE_TSS> wrapper. When a thread exits the + * <ACE_TSS::cleanup> function deletes this object, thereby + * closing it down gracefully. + */ class ACE_Export ACE_Thread_Exit { - // = TITLE - // Keep exit information for a Thread in thread specific storage. - // so that the thread-specific exit hooks will get called no - // matter how the thread exits (e.g., via <ACE_Thread::exit>, C++ - // or Win32 exception, "falling off the end" of the thread entry - // point function, etc.). - // - // = DESCRIPTION - // This clever little helper class is stored in thread-specific - // storage using the <ACE_TSS> wrapper. When a thread exits the - // <ACE_TSS::cleanup> function deletes this object, thereby - // closing it down gracefully. public: + /// Capture the Thread that will be cleaned up automatically. ACE_Thread_Exit (void); - // Capture the Thread that will be cleaned up automatically. + /// Set the <ACE_Thread_Manager>. void thr_mgr (ACE_Thread_Manager *tm); - // Set the <ACE_Thread_Manager>. + /// Destructor calls the thread-specific exit hooks when a thread + /// exits. ~ACE_Thread_Exit (void); - // Destructor calls the thread-specific exit hooks when a thread - // exits. + /// Singleton access point. static ACE_Thread_Exit *instance (void); - // Singleton access point. + /// Cleanup method, used by the <ACE_Object_Manager> to destroy the + /// singleton. static void cleanup (void *instance, void *); - // Cleanup method, used by the <ACE_Object_Manager> to destroy the - // singleton. private: + /// Allow OS_Object_Manager to reset the status of <is_constructed_>. friend class ACE_OS_Object_Manager; - // Allow OS_Object_Manager to reset the status of <is_constructed_>. + /// Automatically add/remove the thread from the + /// <ACE_Thread_Manager>. ACE_Thread_Control thread_control_; - // Automatically add/remove the thread from the - // <ACE_Thread_Manager>. + /** + * Used to detect whether we should create a new instance (or not) + * within the instance method -- we don't trust the instance_ ptr + * because the destructor may have run (if ACE::fini() was called). + * See bug #526. + * We don't follow the singleton pattern due to dependency issues. + */ static u_int is_constructed_; - // Used to detect whether we should create a new instance (or not) - // within the instance method -- we don't trust the instance_ ptr - // because the destructor may have run (if ACE::fini() was called). - // See bug #526. - // We don't follow the singleton pattern due to dependency issues. }; +/** + * @class ACE_Thread_Exit_Maybe + * + * @brief A version of ACE_Thread_Exit that is created dynamically + * under the hood if the flag is set to TRUE. + * + * Allows the appearance of a "smart pointer", but is not + * always created. + */ class ACE_Export ACE_Thread_Exit_Maybe - // = TITLE - // A version of ACE_Thread_Exit that is created dynamically - // under the hood if the flag is set to TRUE. - // = DESCRIPTION - // Allows the appearance of a "smart pointer", but is not - // always created. { public: + /// Don't create an ACE_Thread_Exit instance by default. ACE_Thread_Exit_Maybe (int flag = 0); - // Don't create an ACE_Thread_Exit instance by default. + /// Destroys the underlying ACE_Thread_Exit instance if it exists. ~ACE_Thread_Exit_Maybe (void); - // Destroys the underlying ACE_Thread_Exit instance if it exists. + /// Delegates to underlying instance. ACE_Thread_Exit * operator -> (void) const; - // Delegates to underlying instance. + /// Returns the underlying instance. ACE_Thread_Exit * instance (void) const; - // Returns the underlying instance. private: + /// Holds the underlying instance. ACE_Thread_Exit *instance_; - // Holds the underlying instance. }; diff --git a/ace/Thread_Hook.h b/ace/Thread_Hook.h index cc9a8ef9623..591e50193d6 100644 --- a/ace/Thread_Hook.h +++ b/ace/Thread_Hook.h @@ -1,17 +1,14 @@ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Thread_Hook.h -// -// = AUTHOR -// Carlos O'Ryan <coryan@uci.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Thread_Hook.h + * + * $Id$ + * + * @author Carlos O'Ryan <coryan@uci.edu> + */ +//============================================================================= + #ifndef ACE_THREAD_HOOK_H #define ACE_THREAD_HOOK_H @@ -25,29 +22,34 @@ #include "ace/OS_Export.h" +/** + * @class ACE_Thread_Hook + * + * @brief This class makes it possible to provide user-defined "start" + * hooks that are called before the thread entry point function + * is invoked. + */ class ACE_OS_Export ACE_Thread_Hook { - // = TITLE - // This class makes it possible to provide user-defined "start" - // hooks that are called before the thread entry point function - // is invoked. public: + /** + * This method can be overridden in a subclass to customize this + * pre-function call "hook" invocation that can perform + * initialization processing before the thread entry point <func> + * method is called back. The <func> and <arg> passed into the + * start hook are the same as those passed by the application that + * spawned the thread. + */ virtual void *start (ACE_THR_FUNC func, void *arg); - // This method can be overridden in a subclass to customize this - // pre-function call "hook" invocation that can perform - // initialization processing before the thread entry point <func> - // method is called back. The <func> and <arg> passed into the - // start hook are the same as those passed by the application that - // spawned the thread. + /// sets the system wide thread hook, returns the previous thread + /// hook or 0 if none is set. static ACE_Thread_Hook *thread_hook (ACE_Thread_Hook *hook); - // sets the system wide thread hook, returns the previous thread - // hook or 0 if none is set. + /// Returns the current system thread hook. static ACE_Thread_Hook *thread_hook (void); - // Returns the current system thread hook. }; #include "ace/post.h" diff --git a/ace/Thread_Manager.h b/ace/Thread_Manager.h index 11a30653811..d1b2171e208 100644 --- a/ace/Thread_Manager.h +++ b/ace/Thread_Manager.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Thread_Manager.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Thread_Manager.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_THREAD_MANAGER_H #define ACE_THREAD_MANAGER_H @@ -80,10 +77,13 @@ class ACE_Thread_Manager; class ACE_Thread_Descriptor; #if !defined(ACE_USE_ONE_SHOT_AT_THREAD_EXIT) + /** + * @class ACE_At_Thread_Exit + * + * @brief Contains a method to be applied when a thread is terminated. + */ class ACE_Export ACE_At_Thread_Exit { - // = TITLE - // Contains a method to be applied when a thread is terminated. friend class ACE_Thread_Descriptor; friend class ACE_Thread_Manager; public: @@ -106,23 +106,23 @@ public: int was_applied (int applied); protected: + /// The next <At_Thread_Exit> hook in the list. ACE_At_Thread_Exit *next_; - // The next <At_Thread_Exit> hook in the list. // Do the apply if necessary void do_apply (void); + /// The apply method. virtual void apply (void) = 0; - // The apply method. + /// The Thread_Descriptor where this at is registered. ACE_Thread_Descriptor* td_; - // The Thread_Descriptor where this at is registered. + /// The at was applied? int was_applied_; - // The at was applied? + /// The at has the ownership of this? int is_owner_; - // The at has the ownership of this? }; class ACE_Export ACE_At_Thread_Exit_Func : public ACE_At_Thread_Exit @@ -136,14 +136,14 @@ public: virtual ~ACE_At_Thread_Exit_Func (void); protected: + /// The object to be cleanup void *object_; - // The object to be cleanup + /// The cleanup func ACE_CLEANUP_FUNC func_; - // The cleanup func + /// A param if required void *param_; - // A param if required // The apply method void apply (void); @@ -151,12 +151,15 @@ protected: #endif /* !ACE_USE_ONE_SHOT_AT_THREAD_EXIT */ +/** + * @class ACE_Thread_Descriptor_Base + * + * @brief Basic information for thread descriptors. These information + * gets extracted out because we need it after a thread is + * terminated. + */ class ACE_Export ACE_Thread_Descriptor_Base : public ACE_OS_Thread_Descriptor { - // = TITLE - // Basic information for thread descriptors. These information - // gets extracted out because we need it after a thread is - // terminated. friend class ACE_Thread_Manager; friend class ACE_Double_Linked_List<ACE_Thread_Descriptor_Base>; @@ -171,53 +174,56 @@ public: // = We need the following operators to make Borland happy. + /// Equality operator. int operator== (const ACE_Thread_Descriptor_Base &rhs) const; - // Equality operator. + /// Inequality operator. int operator!= (const ACE_Thread_Descriptor_Base &rhs) const; - // Inequality operator. + /// Group ID. int grp_id (void); - // Group ID. + /// Current state of the thread. ACE_UINT32 state (void); - // Current state of the thread. + /// Return the pointer to an <ACE_Task_Base> or NULL if there's no + /// <ACE_Task_Base> associated with this thread.; ACE_Task_Base *task (void); - // Return the pointer to an <ACE_Task_Base> or NULL if there's no - // <ACE_Task_Base> associated with this thread.; protected: + /// Reset this base thread descriptor. void reset (void); - // Reset this base thread descriptor. + /// Unique thread ID. ACE_thread_t thr_id_; - // Unique thread ID. + /// Unique handle to thread (used by Win32 and AIX). ACE_hthread_t thr_handle_; - // Unique handle to thread (used by Win32 and AIX). + /// Group ID. int grp_id_; - // Group ID. + /// Current state of the thread. ACE_UINT32 thr_state_; - // Current state of the thread. + /// Pointer to an <ACE_Task_Base> or NULL if there's no + /// <ACE_Task_Base>. ACE_Task_Base *task_; - // Pointer to an <ACE_Task_Base> or NULL if there's no - // <ACE_Task_Base>. + /// We need these pointers to maintain the double-linked list in a + /// thread managers. ACE_Thread_Descriptor_Base *next_; ACE_Thread_Descriptor_Base *prev_; - // We need these pointers to maintain the double-linked list in a - // thread managers. }; +/** + * @class ACE_Thread_Descriptor + * + * @brief Information for controlling threads that run under the control + * of the <Thread_Manager>. + */ class ACE_Export ACE_Thread_Descriptor : public ACE_Thread_Descriptor_Base { - // = TITLE - // Information for controlling threads that run under the control - // of the <Thread_Manager>. #if !defined(ACE_USE_ONE_SHOT_AT_THREAD_EXIT) friend class ACE_At_Thread_Exit; #endif /* !ACE_USE_ONE_SHOT_AT_THREAD_EXIT */ @@ -229,107 +235,119 @@ public: ACE_Thread_Descriptor (void); // = Accessor methods. + /// Unique thread id. ACE_thread_t self (void); - // Unique thread id. + /// Unique handle to thread (used by Win32 and AIX). void self (ACE_hthread_t &); - // Unique handle to thread (used by Win32 and AIX). + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. #if !defined(ACE_USE_ONE_SHOT_AT_THREAD_EXIT) + /** + * This cleanup function must be called only for ACE_TSS_cleanup. + * The ACE_TSS_cleanup delegate Log_Msg instance destruction when + * Log_Msg cleanup is called before terminate. + */ void log_msg_cleanup(ACE_Log_Msg* log_msg); - // This cleanup function must be called only for ACE_TSS_cleanup. - // The ACE_TSS_cleanup delegate Log_Msg instance destruction when - // Log_Msg cleanup is called before terminate. + /** + * Register an At_Thread_Exit hook and the ownership is acquire by + * Thread_Descriptor, this is the usual case when the AT is dynamically + * allocated. + */ int at_exit (ACE_At_Thread_Exit* cleanup); - // Register an At_Thread_Exit hook and the ownership is acquire by - // Thread_Descriptor, this is the usual case when the AT is dynamically - // allocated. + /// Register an At_Thread_Exit hook and the ownership is retained for the + /// caller. Normally used when the at_exit hook is created in stack. int at_exit (ACE_At_Thread_Exit& cleanup); - // Register an At_Thread_Exit hook and the ownership is retained for the - // caller. Normally used when the at_exit hook is created in stack. #endif /* !ACE_USE_ONE_SHOT_AT_THREAD_EXIT */ + /** + * Register an object (or array) for cleanup at thread termination. + * "cleanup_hook" points to a (global, or static member) function + * that is called for the object or array when it to be destroyed. + * It may perform any necessary cleanup specific for that object or + * its class. "param" is passed as the second parameter to the + * "cleanup_hook" function; the first parameter is the object (or + * array) to be destroyed. Returns 0 on success, non-zero on + * failure: -1 if virtual memory is exhausted or 1 if the object (or + * arrayt) had already been registered. + */ int at_exit (void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param); - // Register an object (or array) for cleanup at thread termination. - // "cleanup_hook" points to a (global, or static member) function - // that is called for the object or array when it to be destroyed. - // It may perform any necessary cleanup specific for that object or - // its class. "param" is passed as the second parameter to the - // "cleanup_hook" function; the first parameter is the object (or - // array) to be destroyed. Returns 0 on success, non-zero on - // failure: -1 if virtual memory is exhausted or 1 if the object (or - // arrayt) had already been registered. + /// Do nothing destructor to keep some compilers happy ~ACE_Thread_Descriptor (void); - // Do nothing destructor to keep some compilers happy + /** + * Do nothing but to acquire the thread descriptor's lock and + * release. This will first check if the thread is registered or + * not. If it is already registered, there's no need to reacquire + * the lock again. This is used mainly to get newly spawned thread + * in synch with thread manager and prevent it from accessing its + * thread descriptor before it gets fully built. This function is + * only called from ACE_Log_Msg::thr_desc. + */ void acquire_release (void); - // Do nothing but to acquire the thread descriptor's lock and - // release. This will first check if the thread is registered or - // not. If it is already registered, there's no need to reacquire - // the lock again. This is used mainly to get newly spawned thread - // in synch with thread manager and prevent it from accessing its - // thread descriptor before it gets fully built. This function is - // only called from ACE_Log_Msg::thr_desc. + /** + * Set/get the <next_> pointer. These are required by the + * ACE_Free_List. ACE_INLINE is specified here because one version + * of g++ couldn't grok this code without it. + */ ACE_INLINE_FOR_GNUC void set_next (ACE_Thread_Descriptor *td); ACE_INLINE_FOR_GNUC ACE_Thread_Descriptor *get_next (void); - // Set/get the <next_> pointer. These are required by the - // ACE_Free_List. ACE_INLINE is specified here because one version - // of g++ couldn't grok this code without it. private: + /// Reset this thread descriptor. void reset (ACE_Thread_Manager *tm); - // Reset this thread descriptor. #if !defined (ACE_USE_ONE_SHOT_AT_THREAD_EXIT) + /// Pop an At_Thread_Exit from at thread termination list, apply the at + /// if apply is true. void at_pop (int apply = 1); - // Pop an At_Thread_Exit from at thread termination list, apply the at - // if apply is true. + /// Push an At_Thread_Exit to at thread termination list and set the + /// ownership of at. void at_push (ACE_At_Thread_Exit* cleanup, int is_owner = 0); - // Push an At_Thread_Exit to at thread termination list and set the - // ownership of at. + /// Run the AT_Thread_Exit hooks. void do_at_exit (void); - // Run the AT_Thread_Exit hooks. + /// terminate realize the cleanup process to thread termination void terminate (void); - // terminate realize the cleanup process to thread termination + /// Thread_Descriptor is the ownership of ACE_Log_Msg if log_msg_!=0 + /// This can occur because ACE_TSS_cleanup was executed before terminate. ACE_Log_Msg *log_msg_; - // Thread_Descriptor is the ownership of ACE_Log_Msg if log_msg_!=0 - // This can occur because ACE_TSS_cleanup was executed before terminate. + /// The AT_Thread_Exit list ACE_At_Thread_Exit *at_exit_list_; - // The AT_Thread_Exit list #endif /* !ACE_USE_ONE_SHOT_AT_THREAD_EXIT */ + /** + * Stores the cleanup info for a thread. + * @@ Note, this should be generalized to be a stack of + * <ACE_Cleanup_Info>s. + */ ACE_Cleanup_Info cleanup_info_; - // Stores the cleanup info for a thread. - // @@ Note, this should be generalized to be a stack of - // <ACE_Cleanup_Info>s. #if !defined(ACE_USE_ONE_SHOT_AT_THREAD_EXIT) + /// Pointer to an <ACE_Thread_Manager> or NULL if there's no + /// <ACE_Thread_Manager>. ACE_Thread_Manager* tm_; - // Pointer to an <ACE_Thread_Manager> or NULL if there's no - // <ACE_Thread_Manager>. #endif /* !ACE_USE_ONE_SHOT_AT_THREAD_EXIT */ + /// Registration lock to prevent premature removal of thread descriptor. ACE_DEFAULT_THREAD_MANAGER_LOCK *sync_; - // Registration lock to prevent premature removal of thread descriptor. #if !defined(ACE_USE_ONE_SHOT_AT_THREAD_EXIT) + /// Keep track of termination status. int terminated_; - // Keep track of termination status. #endif /* !ACE_USE_ONE_SHOT_AT_THREAD_EXIT */ }; @@ -346,26 +364,27 @@ class ACE_Thread_Control; typedef int (ACE_Thread_Manager::*ACE_THR_MEMBER_FUNC)(ACE_Thread_Descriptor *, int); #endif /* __GNUG__ */ +/** + * @class ACE_Thread_Manager + * + * @brief Manages a pool of threads. + * + * This class allows operations on groups of threads atomically. + * The default behavior of thread manager is to wait on + * all threads under it's management when it gets destructed. + * Therefore, remember to remove a thread from thread manager if + * you don't want it to wait for the thread. There are also + * function to disable this default wait-on-exit behavior. + * However, if your program depends on turning this off to run + * correctly, you are probably doing something wrong. Rule of + * thumb, use ACE_Thread to manage your daemon threads. + * Notice that if there're threads live beyond the scope of + * <main>, you are sure to have resource leaks in your program. + * Remember to wait on threads before exiting <main> if that + * could happen in your programs. + */ class ACE_Export ACE_Thread_Manager { - // = TITLE - // Manages a pool of threads. - // - // = DESCRIPTION - // This class allows operations on groups of threads atomically. - // The default behavior of thread manager is to wait on - // all threads under it's management when it gets destructed. - // Therefore, remember to remove a thread from thread manager if - // you don't want it to wait for the thread. There are also - // function to disable this default wait-on-exit behavior. - // However, if your program depends on turning this off to run - // correctly, you are probably doing something wrong. Rule of - // thumb, use ACE_Thread to manage your daemon threads. - // - // Notice that if there're threads live beyond the scope of - // <main>, you are sure to have resource leaks in your program. - // Remember to wait on threads before exiting <main> if that - // could happen in your programs. public: friend class ACE_Thread_Control; #if !defined(ACE_USE_ONE_SHOT_AT_THREAD_EXIT) @@ -380,29 +399,29 @@ public: // <Thread_Manager> can be in. enum { + /// Uninitialized. ACE_THR_IDLE = 0x00000000, - // Uninitialized. + /// Created but not yet running. ACE_THR_SPAWNED = 0x00000001, - // Created but not yet running. + /// Thread is active (naturally, we don't know if it's actually + /// *running* because we aren't the scheduler...). ACE_THR_RUNNING = 0x00000002, - // Thread is active (naturally, we don't know if it's actually - // *running* because we aren't the scheduler...). + /// Thread is suspended. ACE_THR_SUSPENDED = 0x00000004, - // Thread is suspended. + /// Thread has been cancelled (which is an indiction that it needs to + /// terminate...). ACE_THR_CANCELLED = 0x00000008, - // Thread has been cancelled (which is an indiction that it needs to - // terminate...). + /// Thread has shutdown, but the slot in the thread manager hasn't + /// been reclaimed yet. ACE_THR_TERMINATED = 0x00000010, - // Thread has shutdown, but the slot in the thread manager hasn't - // been reclaimed yet. + /// Join operation has been invoked on the thread by thread manager. ACE_THR_JOINING = 0x10000000 - // Join operation has been invoked on the thread by thread manager. }; // = Initialization and termination methods. @@ -413,26 +432,28 @@ public: virtual ~ACE_Thread_Manager (void); #if ! defined (ACE_THREAD_MANAGER_LACKS_STATICS) + /// Get pointer to a process-wide <ACE_Thread_Manager>. static ACE_Thread_Manager *instance (void); - // Get pointer to a process-wide <ACE_Thread_Manager>. + /// Set pointer to a process-wide <ACE_Thread_Manager> and return + /// existing pointer. static ACE_Thread_Manager *instance (ACE_Thread_Manager *); - // Set pointer to a process-wide <ACE_Thread_Manager> and return - // existing pointer. + /// Delete the dynamically allocated Singleton static void close_singleton (void); - // Delete the dynamically allocated Singleton #endif /* ! defined (ACE_THREAD_MANAGER_LACKS_STATICS) */ + /// No-op. Currently unused. int open (size_t size = 0); - // No-op. Currently unused. + /** + * Release all resources. + * By default, this method will wait till all threads + * exit. However, when called from <close_singleton>, most global resources + * are destroyed and thus, we don't try to wait but just clean up the thread + * descriptor list. + */ int close (void); - // Release all resources. - // By default, this method will wait till all threads - // exit. However, when called from <close_singleton>, most global resources - // are destroyed and thus, we don't try to wait but just clean up the thread - // descriptor list. // The <ACE_thread_t> * argument to each of the <spawn> family member // functions is interpreted and used as shown in the following @@ -448,6 +469,11 @@ public: // the task name. The // argument is not modified. + /** + * Create a new thread, which executes <func>. + * Returns: on success a unique group id that can be used to control + * other threads added to the same group. On failure, returns -1. + */ int spawn (ACE_THR_FUNC func, void *args = 0, long flags = THR_NEW_LWP | THR_JOINABLE, @@ -457,10 +483,12 @@ public: int grp_id = -1, void *stack = 0, size_t stack_size = 0); - // Create a new thread, which executes <func>. - // Returns: on success a unique group id that can be used to control - // other threads added to the same group. On failure, returns -1. + /** + * Create N new threads, all of which execute <func>. + * Returns: on success a unique group id that can be used to control + * all of the threads in the same group. On failure, returns -1. + */ int spawn_n (size_t n, ACE_THR_FUNC func, void *args = 0, @@ -471,10 +499,21 @@ public: ACE_hthread_t thread_handles[] = 0, void *stack[] = 0, size_t stack_size[] = 0); - // Create N new threads, all of which execute <func>. - // Returns: on success a unique group id that can be used to control - // all of the threads in the same group. On failure, returns -1. + /** + * Spawn N new threads, which execute <func> with argument <arg>. + * If <thread_ids> != 0 the thread_ids of successfully spawned + * threads will be placed into the <thread_ids> buffer (which must + * be the same size as <n>). If <stack> != 0 it is assumed to be an + * array of <n> pointers to the base of the stacks to use for the + * threads being spawned. If <stack_size> != 0 it is assumed to be + * an array of <n> values indicating how big each of the + * corresponding <stack>s are. If <thread_handles> != 0 it is + * assumed to be an array of <n> thread_handles that will be + * assigned the values of the thread handles being spawned. Returns + * -1 on failure (<errno> will explain...), otherwise returns the + * group id of the threads. + */ int spawn_n (ACE_thread_t thread_ids[], size_t n, ACE_THR_FUNC func, @@ -486,129 +525,139 @@ public: size_t stack_size[] = 0, ACE_hthread_t thread_handles[] = 0, ACE_Task_Base *task = 0); - // Spawn N new threads, which execute <func> with argument <arg>. - // If <thread_ids> != 0 the thread_ids of successfully spawned - // threads will be placed into the <thread_ids> buffer (which must - // be the same size as <n>). If <stack> != 0 it is assumed to be an - // array of <n> pointers to the base of the stacks to use for the - // threads being spawned. If <stack_size> != 0 it is assumed to be - // an array of <n> values indicating how big each of the - // corresponding <stack>s are. If <thread_handles> != 0 it is - // assumed to be an array of <n> thread_handles that will be - // assigned the values of the thread handles being spawned. Returns - // -1 on failure (<errno> will explain...), otherwise returns the - // group id of the threads. + /** + * Called to clean up when a thread exits. If <do_thread_exit> is + * non-0 then <ACE_Thread::exit> is called to exit the thread, in + * which case <status> is passed as the exit value of the thread. + * Should _not_ be called by main thread. + */ void *exit (void *status = 0, int do_thread_exit = 1); - // Called to clean up when a thread exits. If <do_thread_exit> is - // non-0 then <ACE_Thread::exit> is called to exit the thread, in - // which case <status> is passed as the exit value of the thread. - // Should _not_ be called by main thread. + /** + * Block until there are no more threads running in the + * <Thread_Manager> or <timeout> expires. Note that <timeout> is + * treated as "absolute" time. Returns 0 on success and -1 on + * failure. If <abandon_detached_threads> is set, wait will first + * check thru its thread list for threads with THR_DETACHED or + * THR_DAEMON flags set and remove these threads. Notice that + * unlike other wait_* function, by default, <wait> does wait on + * all thread spawned by this thread_manager no matter the detached + * flags are set or not unless it is called with + * <abandon_detached_threads> flag set. + * NOTE that if this function is called while the ACE_Object_Manager + * is shutting down (as a result of program rundown via ACE::fini), + * it will not wait for any threads to complete. If you must wait for + * threads spawned by this thread manager to complete and you are in a + * ACE rundown situation (such as your object is being destroyed by the + * ACE_Object_Manager) you can use wait_grp instead. + */ int wait (const ACE_Time_Value *timeout = 0, int abandon_detached_threads = 0); - // Block until there are no more threads running in the - // <Thread_Manager> or <timeout> expires. Note that <timeout> is - // treated as "absolute" time. Returns 0 on success and -1 on - // failure. If <abandon_detached_threads> is set, wait will first - // check thru its thread list for threads with THR_DETACHED or - // THR_DAEMON flags set and remove these threads. Notice that - // unlike other wait_* function, by default, <wait> does wait on - // all thread spawned by this thread_manager no matter the detached - // flags are set or not unless it is called with - // <abandon_detached_threads> flag set. - // NOTE that if this function is called while the ACE_Object_Manager - // is shutting down (as a result of program rundown via ACE::fini), - // it will not wait for any threads to complete. If you must wait for - // threads spawned by this thread manager to complete and you are in a - // ACE rundown situation (such as your object is being destroyed by the - // ACE_Object_Manager) you can use wait_grp instead. + /// Join a thread specified by <tid>. Do not wait on a detached thread. int join (ACE_thread_t tid, void **status = 0); - // Join a thread specified by <tid>. Do not wait on a detached thread. + /** + * Block until there are no more threads running in a group. + * Returns 0 on success and -1 on failure. Notice that wait_grp + * will not wait on detached threads. + */ int wait_grp (int grp_id); - // Block until there are no more threads running in a group. - // Returns 0 on success and -1 on failure. Notice that wait_grp - // will not wait on detached threads. // = Accessors for ACE_Thread_Descriptors. + /** + * Get a pointer to the calling thread's own thread_descriptor. + * This must be called from a spawn thread. This function will + * fetch the info from TSS. + */ ACE_Thread_Descriptor *thread_desc_self (void); - // Get a pointer to the calling thread's own thread_descriptor. - // This must be called from a spawn thread. This function will - // fetch the info from TSS. + /// Return a pointer to the thread's Thread_Descriptor, + /// 0 if fail. ACE_Thread_Descriptor *thread_descriptor (ACE_thread_t); - // Return a pointer to the thread's Thread_Descriptor, - // 0 if fail. + /// Return a pointer to the thread's Thread_Descriptor, + /// 0 if fail. ACE_Thread_Descriptor *hthread_descriptor (ACE_hthread_t); - // Return a pointer to the thread's Thread_Descriptor, - // 0 if fail. + /** + * Return the "real" handle to the calling thread, caching it if + * necessary in TSS to speed up subsequent lookups. This is + * necessary since on some platforms (e.g., Win32) we can't get this + * handle via direct method calls. Notice that you should *not* + * close the handle passed back from this method. It is used + * internally by Thread Manager. On the other hand, you *have to* + * use this internal thread handle when working on Thread_Manager. + * Return -1 if fail. + */ int thr_self (ACE_hthread_t &); - // Return the "real" handle to the calling thread, caching it if - // necessary in TSS to speed up subsequent lookups. This is - // necessary since on some platforms (e.g., Win32) we can't get this - // handle via direct method calls. Notice that you should *not* - // close the handle passed back from this method. It is used - // internally by Thread Manager. On the other hand, you *have to* - // use this internal thread handle when working on Thread_Manager. - // Return -1 if fail. + /** + * Return the unique ID of the thread. This is not strictly + * necessary (because a thread can always just call + * <ACE_Thread::self>). However, we put it here to be complete. + */ ACE_thread_t thr_self (void); - // Return the unique ID of the thread. This is not strictly - // necessary (because a thread can always just call - // <ACE_Thread::self>). However, we put it here to be complete. + /** + * Returns a pointer to the current <ACE_Task_Base> we're executing + * in if this thread is indeed running in an <ACE_Task_Base>, else + * return 0. + */ ACE_Task_Base *task (void); - // Returns a pointer to the current <ACE_Task_Base> we're executing - // in if this thread is indeed running in an <ACE_Task_Base>, else - // return 0. // = Suspend methods, which isn't supported on POSIX pthreads (will not block). + /** + * Suspend all threads + * Suspend a single thread. + * Suspend a group of threads. + * True if <t_id> is inactive (i.e., suspended), else false. + */ int suspend_all (void); - // Suspend all threads int suspend (ACE_thread_t); - // Suspend a single thread. int suspend_grp (int grp_id); - // Suspend a group of threads. int testsuspend (ACE_thread_t t_id); - // True if <t_id> is inactive (i.e., suspended), else false. // = Resume methods, which isn't supported on POSIX pthreads (will not block). + /** + * Resume all stopped threads + * Resume a single thread. + * Resume a group of threads. + * True if <t_id> is active (i.e., resumed), else false. + */ int resume_all (void); - // Resume all stopped threads int resume (ACE_thread_t); - // Resume a single thread. int resume_grp (int grp_id); - // Resume a group of threads. int testresume (ACE_thread_t t_id); - // True if <t_id> is active (i.e., resumed), else false. // = Send signals to one or more threads without blocking. + /** + * Send <signum> to all stopped threads. Not supported on platforms + * that do not have advanced signal support, such as Win32. + * Send the <signum> to a single thread. Not supported on platforms + * that do not have advanced signal support, such as Win32. + * Send <signum> to a group of threads, not supported on platforms + * that do not have advanced signal support, such as Win32. + */ int kill_all (int signum); - // Send <signum> to all stopped threads. Not supported on platforms - // that do not have advanced signal support, such as Win32. int kill (ACE_thread_t, int signum); - // Send the <signum> to a single thread. Not supported on platforms - // that do not have advanced signal support, such as Win32. int kill_grp (int grp_id, int signum); - // Send <signum> to a group of threads, not supported on platforms - // that do not have advanced signal support, such as Win32. // = Cancel methods, which provides a cooperative thread-termination mechanism (will not block). + /** + * Cancel's all the threads. + * Cancel a single thread. + * Cancel a group of threads. + * True if <t_id> is cancelled, else false. + */ int cancel_all (int async_cancel = 0); - // Cancel's all the threads. int cancel (ACE_thread_t, int async_cancel = 0); - // Cancel a single thread. int cancel_grp (int grp_id, int async_cancel = 0); - // Cancel a group of threads. int testcancel (ACE_thread_t t_id); - // True if <t_id> is cancelled, else false. // = Set/get group ids for a particular thread id. int set_grp (ACE_thread_t, @@ -623,146 +672,172 @@ public: // = Operations on ACE_Tasks. + /** + * Block until there are no more threads running in <task>. Returns + * 0 on success and -1 on failure. Note that <wait_task> will not + * wait on detached threads. + * Suspend all threads in an ACE_Task. + * Resume all threads in an ACE_Task. + * Send a signal <signum> to all threads in an <ACE_Task>. + */ int wait_task (ACE_Task_Base *task); - // Block until there are no more threads running in <task>. Returns - // 0 on success and -1 on failure. Note that <wait_task> will not - // wait on detached threads. int suspend_task (ACE_Task_Base *task); - // Suspend all threads in an ACE_Task. int resume_task (ACE_Task_Base *task); - // Resume all threads in an ACE_Task. int kill_task (ACE_Task_Base *task, int signum); - // Send a signal <signum> to all threads in an <ACE_Task>. + /** + * Cancel all threads in an <ACE_Task>. If <async_cancel> is non-0, + * then asynchronously cancel these threads if the OS platform + * supports cancellation. Otherwise, perform a "cooperative" + * cancellation. + */ int cancel_task (ACE_Task_Base *task, int async_cancel = 0); - // Cancel all threads in an <ACE_Task>. If <async_cancel> is non-0, - // then asynchronously cancel these threads if the OS platform - // supports cancellation. Otherwise, perform a "cooperative" - // cancellation. // = Collect thread handles in the thread manager. Notice that // the collected information is just a snapshot. + /// Check if the thread is managed by the thread manager. Return true if + /// the thread is found, false otherwise. int hthread_within (ACE_hthread_t handle); int thread_within (ACE_thread_t tid); - // Check if the thread is managed by the thread manager. Return true if - // the thread is found, false otherwise. + /// Returns the number of <ACE_Task_Base> in a group. int num_tasks_in_group (int grp_id); - // Returns the number of <ACE_Task_Base> in a group. + /// Returns the number of threads in an <ACE_Task_Base>. int num_threads_in_task (ACE_Task_Base *task); - // Returns the number of threads in an <ACE_Task_Base>. + /** + * Returns in <task_list> a list of up to <n> <ACE_Tasks> in a + * group. The caller must allocate the memory for <task_list>. In + * case of an error, -1 is returned. If no requested values are + * found, 0 is returned, otherwise correct number of retrieved + * values are returned. + */ int task_list (int grp_id, ACE_Task_Base *task_list[], size_t n); - // Returns in <task_list> a list of up to <n> <ACE_Tasks> in a - // group. The caller must allocate the memory for <task_list>. In - // case of an error, -1 is returned. If no requested values are - // found, 0 is returned, otherwise correct number of retrieved - // values are returned. + /** + * Returns in <thread_list> a list of up to <n> thread ids in an + * <ACE_Task_Base>. The caller must allocate the memory for + * <thread_list>. In case of an error, -1 is returned. If no + * requested values are found, 0 is returned, otherwise correct + * number of retrieved values are returned. + */ int thread_list (ACE_Task_Base *task, ACE_thread_t thread_list[], size_t n); - // Returns in <thread_list> a list of up to <n> thread ids in an - // <ACE_Task_Base>. The caller must allocate the memory for - // <thread_list>. In case of an error, -1 is returned. If no - // requested values are found, 0 is returned, otherwise correct - // number of retrieved values are returned. + /** + * Returns in <hthread_list> a list of up to <n> thread handles in + * an <ACE_Task_Base>. The caller must allocate memory for + * <hthread_list>. In case of an error, -1 is returned. If no + * requested values are found, 0 is returned, otherwise correct + * number of retrieved values are returned. + */ int hthread_list (ACE_Task_Base *task, ACE_hthread_t hthread_list[], size_t n); - // Returns in <hthread_list> a list of up to <n> thread handles in - // an <ACE_Task_Base>. The caller must allocate memory for - // <hthread_list>. In case of an error, -1 is returned. If no - // requested values are found, 0 is returned, otherwise correct - // number of retrieved values are returned. + /** + * Returns in <thread_list> a list of up to <n> thread ids in a + * group <grp_id>. The caller must allocate the memory for + * <thread_list>. In case of an error, -1 is returned. If no + * requested values are found, 0 is returned, otherwise correct + * number of retrieved values are returned. + */ int thread_grp_list (int grp_id, ACE_thread_t thread_list[], size_t n); - // Returns in <thread_list> a list of up to <n> thread ids in a - // group <grp_id>. The caller must allocate the memory for - // <thread_list>. In case of an error, -1 is returned. If no - // requested values are found, 0 is returned, otherwise correct - // number of retrieved values are returned. + /** + * Returns in <hthread_list> a list of up to <n> thread handles in + * a group <grp_id>. The caller must allocate memory for + * <hthread_list>. + */ int hthread_grp_list (int grp_id, ACE_hthread_t hthread_list[], size_t n); - // Returns in <hthread_list> a list of up to <n> thread handles in - // a group <grp_id>. The caller must allocate memory for - // <hthread_list>. + /** + * Returns in <task_list> a list of up to <n> <ACE_Tasks>. The + * caller must allocate the memory for <task_list>. In case of an + * error, -1 is returned. If no requested values are found, 0 is + * returned, otherwise correct number of retrieved values are + * returned. + */ int task_all_list (ACE_Task_Base *task_list[], size_t n); - // Returns in <task_list> a list of up to <n> <ACE_Tasks>. The - // caller must allocate the memory for <task_list>. In case of an - // error, -1 is returned. If no requested values are found, 0 is - // returned, otherwise correct number of retrieved values are - // returned. + /** + * Returns in <thread_list> a list of up to <n> thread ids. The + * caller must allocate the memory for <thread_list>. In case of an + * error, -1 is returned. If no requested values are found, 0 is + * returned, otherwise correct number of retrieved values are + * returned. + */ int thread_all_list (ACE_thread_t thread_list[], size_t n); - // Returns in <thread_list> a list of up to <n> thread ids. The - // caller must allocate the memory for <thread_list>. In case of an - // error, -1 is returned. If no requested values are found, 0 is - // returned, otherwise correct number of retrieved values are - // returned. // = Set/get group ids for a particular task. int set_grp (ACE_Task_Base *task, int grp_id); int get_grp (ACE_Task_Base *task, int &grp_id); + /// Return a count of the current number of threads active in the + /// <Thread_Manager>. int count_threads (void) const; - // Return a count of the current number of threads active in the - // <Thread_Manager>. #if !defined(ACE_USE_ONE_SHOT_AT_THREAD_EXIT) + /** + * Register an At_Thread_Exit hook and the ownership is acquire by + * Thread_Descriptor, this is the usual case when the AT is dynamically + * allocated. + */ int at_exit (ACE_At_Thread_Exit* cleanup); - // Register an At_Thread_Exit hook and the ownership is acquire by - // Thread_Descriptor, this is the usual case when the AT is dynamically - // allocated. + /// Register an At_Thread_Exit hook and the ownership is retained for the + /// caller. Normally used when the at_exit hook is created in stack. int at_exit (ACE_At_Thread_Exit& cleanup); - // Register an At_Thread_Exit hook and the ownership is retained for the - // caller. Normally used when the at_exit hook is created in stack. #endif /* !ACE_USE_ONE_SHOT_AT_THREAD_EXIT */ + /** + * + ***** + * @deprecated This function is deprecated. Please use the previous two + * at_exit method. Notice that you should avoid mixing this method + * with the previous two at_exit methods. + ***** + * + * Register an object (or array) for cleanup at + * thread termination. "cleanup_hook" points to a (global, or + * static member) function that is called for the object or array + * when it to be destroyed. It may perform any necessary cleanup + * specific for that object or its class. "param" is passed as the + * second parameter to the "cleanup_hook" function; the first + * parameter is the object (or array) to be destroyed. + * "cleanup_hook", for example, may delete the object (or array). + * If <cleanup_hook> == 0, the <object> will _NOT_ get cleanup at + * thread exit. You can use this to cancel the previously added + * at_exit. + */ int at_exit (void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param); - // *** This function is deprecated. Please use the previous two - // *** at_exit method. Notice that you should avoid mixing this method - // *** with the previous two at_exit methods. - // - // Register an object (or array) for cleanup at - // thread termination. "cleanup_hook" points to a (global, or - // static member) function that is called for the object or array - // when it to be destroyed. It may perform any necessary cleanup - // specific for that object or its class. "param" is passed as the - // second parameter to the "cleanup_hook" function; the first - // parameter is the object (or array) to be destroyed. - // "cleanup_hook", for example, may delete the object (or array). - // If <cleanup_hook> == 0, the <object> will _NOT_ get cleanup at - // thread exit. You can use this to cancel the previously added - // at_exit. + /// Access function to determine whether the Thread_Manager will + /// wait for its thread to exit or not when being closing down. void wait_on_exit (int dowait); int wait_on_exit (void); - // Access function to determine whether the Thread_Manager will - // wait for its thread to exit or not when being closing down. + /// Dump the state of an object. void dump (void); - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Create a new thread (must be called with locks held). virtual int spawn_i (ACE_THR_FUNC func, void *args, long flags, @@ -773,133 +848,138 @@ protected: void *stack = 0, size_t stack_size = 0, ACE_Task_Base *task = 0); - // Create a new thread (must be called with locks held). + /// Run the registered hooks when the thread exits. void run_thread_exit_hooks (int i); - // Run the registered hooks when the thread exits. + /// Locate the index of the table slot occupied by <t_id>. Returns + /// -1 if <t_id> is not in the table doesn't contain <t_id>. ACE_Thread_Descriptor *find_thread (ACE_thread_t t_id); - // Locate the index of the table slot occupied by <t_id>. Returns - // -1 if <t_id> is not in the table doesn't contain <t_id>. + /// Locate the index of the table slot occupied by <h_id>. Returns + /// -1 if <h_id> is not in the table doesn't contain <h_id>. ACE_Thread_Descriptor *find_hthread (ACE_hthread_t h_id); - // Locate the index of the table slot occupied by <h_id>. Returns - // -1 if <h_id> is not in the table doesn't contain <h_id>. + /** + * Locate the thread descriptor address of the list occupied by + * <task>. Returns 0 if <task> is not in the table doesn't contain + * <task>. + */ ACE_Thread_Descriptor *find_task (ACE_Task_Base *task, int slot = -1); - // Locate the thread descriptor address of the list occupied by - // <task>. Returns 0 if <task> is not in the table doesn't contain - // <task>. + /// Insert a thread in the table (checks for duplicates). int insert_thr (ACE_thread_t t_id, ACE_hthread_t, int grp_id = -1, long flags = 0); - // Insert a thread in the table (checks for duplicates). + /// Append a thread in the table (adds at the end, growing the table + /// if necessary). int append_thr (ACE_thread_t t_id, ACE_hthread_t, ACE_UINT32, int grp_id, ACE_Task_Base *task = 0, long flags = 0, ACE_Thread_Descriptor *td = 0); - // Append a thread in the table (adds at the end, growing the table - // if necessary). + /// Remove thread from the table. void remove_thr (ACE_Thread_Descriptor *td, int close_handler); - // Remove thread from the table. + /// Remove all threads from the table. void remove_thr_all (void); - // Remove all threads from the table. // = The following four methods implement a simple scheme for // operating on a collection of threads atomically. + /** + * Efficiently check whether <thread> is in a particular <state>. + * This call updates the TSS cache if possible to speed up + * subsequent searches. + */ int check_state (ACE_UINT32 state, ACE_thread_t thread, int enable = 1); - // Efficiently check whether <thread> is in a particular <state>. - // This call updates the TSS cache if possible to speed up - // subsequent searches. + /// Apply <func> to all members of the table that match the <task> int apply_task (ACE_Task_Base *task, ACE_THR_MEMBER_FUNC, int = 0); - // Apply <func> to all members of the table that match the <task> + /// Apply <func> to all members of the table that match the <grp_id>. int apply_grp (int grp_id, ACE_THR_MEMBER_FUNC func, int arg = 0); - // Apply <func> to all members of the table that match the <grp_id>. + /// Apply <func> to all members of the table. int apply_all (ACE_THR_MEMBER_FUNC, int = 0); - // Apply <func> to all members of the table. + /// Join the thread described in <tda>. int join_thr (ACE_Thread_Descriptor *td, int = 0); - // Join the thread described in <tda>. + /// Resume the thread described in <tda>. int resume_thr (ACE_Thread_Descriptor *td, int = 0); - // Resume the thread described in <tda>. + /// Suspend the thread described in <tda>. int suspend_thr (ACE_Thread_Descriptor *td, int = 0); - // Suspend the thread described in <tda>. + /// Send signal <signum> to the thread described in <tda>. int kill_thr (ACE_Thread_Descriptor *td, int signum); - // Send signal <signum> to the thread described in <tda>. + /// Set the cancellation flag for the thread described in <tda>. int cancel_thr (ACE_Thread_Descriptor *td, int async_cancel = 0); - // Set the cancellation flag for the thread described in <tda>. + /// Register a thread as terminated and put it into the <terminated_thr_list_>. int register_as_terminated (ACE_Thread_Descriptor *td); - // Register a thread as terminated and put it into the <terminated_thr_list_>. + /** + * Keeping a list of thread descriptors within the thread manager. + * Double-linked list enables us to cache the entries in TSS + * and adding/removing thread descriptor entries without + * affecting other thread's descriptor entries. + */ ACE_Double_Linked_List<ACE_Thread_Descriptor> thr_list_; - // Keeping a list of thread descriptors within the thread manager. - // Double-linked list enables us to cache the entries in TSS - // and adding/removing thread descriptor entries without - // affecting other thread's descriptor entries. #if !defined (VXWORKS) + /// Collect terminated but not yet joined thread entries. ACE_Double_Linked_List<ACE_Thread_Descriptor_Base> terminated_thr_list_; - // Collect terminated but not yet joined thread entries. #endif /* VXWORKS */ + /// Collect pointers to thread descriptors of threads to be removed later. ACE_Unbounded_Queue<ACE_Thread_Descriptor*> thr_to_be_removed_; - // Collect pointers to thread descriptors of threads to be removed later. + /// Keeps track of the next group id to assign. int grp_id_; - // Keeps track of the next group id to assign. + /// Set if we want the Thread_Manager to wait on all threads before + /// being closed, reset otherwise. int automatic_wait_; - // Set if we want the Thread_Manager to wait on all threads before - // being closed, reset otherwise. // = ACE_Thread_Mutex and condition variable for synchronizing termination. #if defined (ACE_HAS_THREADS) + /// Serialize access to the <zero_cond_>. ACE_Thread_Mutex lock_; - // Serialize access to the <zero_cond_>. + /// Keep track of when there are no more threads. ACE_Condition_Thread_Mutex zero_cond_; - // Keep track of when there are no more threads. #endif /* ACE_HAS_THREADS */ private: ACE_Locked_Free_List<ACE_Thread_Descriptor, ACE_SYNCH_MUTEX> thread_desc_freelist_; #if ! defined (ACE_THREAD_MANAGER_LACKS_STATICS) + /// Pointer to a process-wide <ACE_Thread_Manager>. static ACE_Thread_Manager *thr_mgr_; - // Pointer to a process-wide <ACE_Thread_Manager>. + /// Must delete the <thr_mgr_> if non-0. static int delete_thr_mgr_; - // Must delete the <thr_mgr_> if non-0. #endif /* ! defined (ACE_THREAD_MANAGER_LACKS_STATICS) */ }; diff --git a/ace/Time_Request_Reply.h b/ace/Time_Request_Reply.h index ed7022e0dc8..9397a72939a 100644 --- a/ace/Time_Request_Reply.h +++ b/ace/Time_Request_Reply.h @@ -1,23 +1,20 @@ /* -*- C++ -*- */ -// $Id$ - - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// ACE_Time_Request_Reply.h -// -// = DESCRIPTION -// Define the format used to exchange messages between the -// ACE_Time_Server and clerks. -// -// = AUTHOR -// Prashant Jain -// -// ============================================================================ + + +//============================================================================= +/** + * @file ACE_Time_Request_Reply.h + * + * $Id$ + * + * Define the format used to exchange messages between the + * ACE_Time_Server and clerks. + * + * + * @author Prashant Jain + */ +//============================================================================= + #ifndef ACE_TIME_REQUEST_REPLY_H #define ACE_TIME_REQUEST_REPLY_H @@ -31,35 +28,37 @@ #include "ace/SString.h" +/** + * @class ACE_Time_Request + * + * @brief Message format for delivering requests to the ACE_Time Server. + * + * This class is implemented to minimize data copying. + * In particular, all marshaling is done in situ... + */ class ACE_Export ACE_Time_Request { - // = TITLE - // Message format for delivering requests to the ACE_Time Server. - // - // = DESCRIPTION - // This class is implemented to minimize data copying. - // In particular, all marshaling is done in situ... public: enum Constants { - // Request message types. + /// Request message types. TIME_UPDATE = 01, - // Class-specific constant values. + /// Class-specific constant values. MAX_TIME_LEN = MAXPATHLEN + 1 }; + /// Default constructor. ACE_Time_Request (void); - // Default constructor. + /// Create a <ACE_Time_Request> message. ACE_Time_Request (ACE_INT32 msg_type, // Type of request. const ACE_UINT32 time, ACE_Time_Value *timeout = 0); // Max time waiting for request. - // Create a <ACE_Time_Request> message. + /// Initialize length_ in order to ensure correct byte ordering + /// before a request is sent. void init (void); - // Initialize length_ in order to ensure correct byte ordering - // before a request is sent. // Get the fixed size of message ssize_t size (void) const; @@ -80,14 +79,14 @@ public: ACE_Time_Value timeout (void) const; void timeout (const ACE_Time_Value timeout); + /// Encode the message before transmission. int encode (void *&); - // Encode the message before transmission. + /// Decode message after reception. int decode (void); - // Decode message after reception. + /// Print out the values of the message for debugging purposes. void dump (void) const; - // Print out the values of the message for debugging purposes. private: // = The 5 fields in the <Transfer> struct are transmitted to the server. @@ -113,11 +112,11 @@ private: // The data portion contains <time_> }; + /// Transfer buffer. Transfer transfer_; - // Transfer buffer. + /// Time ACE_UINT32 time_; - // Time }; diff --git a/ace/Time_Value.h b/ace/Time_Value.h index 4ac2bed868d..913b180c2a0 100644 --- a/ace/Time_Value.h +++ b/ace/Time_Value.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Time_Value.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ +//============================================================================= +/** + * @file Time_Value.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_TIME_VALUE_H #define ACE_TIME_VALUE_H diff --git a/ace/Timeprobe.h b/ace/Timeprobe.h index 92caac950cc..bd0b7b1b687 100644 --- a/ace/Timeprobe.h +++ b/ace/Timeprobe.h @@ -1,45 +1,32 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timeprobe.h -// -// = AUTHOR -// Irfan Pyarali -// -// = ADDITIONAL COMMENTS -// -// If users want to use time probes, the ACE_COMPILE_TIMEPROBES -// flag must be defined when compiling ACE. This can be achieved -// by doing one of the following: -// -// . Use make probe = 1, if you are using the make utility. -// -// . Define ACE_COMPILE_TIMEPROBES in config.h -// -// . Define ACE_COMPILE_TIMEPROBES in the VC project file. -// -// . Other regular methods will also work. -// -// It is not necessary to define ACE_COMPILE_TIMEPROBES when using -// time probes, you simply need ACE_ENABLE_TIMEPROBES. You can use -// the ACE_TIMEPROBE_* macros to program the time probes, and use -// the ACE_ENABLE_TIMEPROBE to enable the time probes. If you -// define ACE_ENABLE_TIMEPROBE in your code, but forget to compile -// ACE with ACE_COMPILE_TIMEPROBES, you will end up with linker -// errors. -// -// Remember that ACE_COMPILE_TIMEPROBES means that the ACE library -// will contain code for time probes. This is only useful when -// compiling ACE. ACE_ENABLE_TIMEPROBES means that the -// ACE_TIMEPROBE_* macros should spring to life. -// -// ============================================================================ + +//============================================================================= +/** + * @file Timeprobe.h + * + * $Id$ + * + * @author Irfan Pyarali + * + * If users want to use time probes the ACE_COMPILE_TIMEPROBES flag + * must be defined when compiling ACE. This can be achieved by doing + * one of the following: . Use make probe = 1 if you are using the + * make utility. . Define ACE_COMPILE_TIMEPROBES in config.h . Define + * ACE_COMPILE_TIMEPROBES in the VC project file. . Other regular + * methods will also work. It is not necessary to define + * ACE_COMPILE_TIMEPROBES when using time probes you simply need + * ACE_ENABLE_TIMEPROBES. You can use the ACE_TIMEPROBE_* macros to + * program the time probes and use the ACE_ENABLE_TIMEPROBE to enable + * the time probes. If you define ACE_ENABLE_TIMEPROBE in your code + * but forget to compile ACE with ACE_COMPILE_TIMEPROBES you will end + * up with linker errors. Remember that ACE_COMPILE_TIMEPROBES means + * that the ACE library will contain code for time probes. This is + * only useful when compiling ACE. ACE_ENABLE_TIMEPROBES means that + * the ACE_TIMEPROBE_* macros should spring to life. + * + */ +//============================================================================= + #ifndef ACE_TIMEPROBE_H #define ACE_TIMEPROBE_H @@ -59,51 +46,57 @@ #if defined (ACE_COMPILE_TIMEPROBES) +/** + * @class ACE_Event_Descriptions + * + * @brief Event Descriptions. + */ class ACE_Export ACE_Event_Descriptions { - // = TITLE - // Event Descriptions. public: + /// Event descriptions const char **descriptions_; - // Event descriptions + /// Minimum id of this description set u_long minimum_id_; - // Minimum id of this description set + /// Comparison int operator== (const ACE_Event_Descriptions &rhs) const; - // Comparison }; +/** + * @class ACE_timeprobe_t + * + * @brief Time probe record. + */ class ACE_Export ACE_timeprobe_t { - // = TITLE - // Time probe record. public: - // = Events are record as strings or numbers. + /// Events are record as strings or numbers. union event { u_long event_number_; const char *event_description_; }; - // = Type of event. + /// Type of event. enum event_type { NUMBER, STRING }; + /// Event. event event_; - // Event. + /// Type of event. event_type event_type_; - // Type of event. + /// Timestamp. ACE_hrtime_t time_; - // Timestamp. + /// Id of thread posting the time probe. ACE_thread_t thread_; - // Id of thread posting the time probe. }; #if defined (__ACE_INLINE__) diff --git a/ace/Timeprobe_T.h b/ace/Timeprobe_T.h index 3850020415a..41744e153d8 100644 --- a/ace/Timeprobe_T.h +++ b/ace/Timeprobe_T.h @@ -1,5 +1,15 @@ /* -*- C++ -*- */ -// $Id$ + +//============================================================================= +/** + * @file Timeprobe_T.h + * + * $Id$ + * + * @author Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_TIMEPROBE_T_H #define ACE_TIMEPROBE_T_H @@ -15,151 +25,154 @@ #include "ace/Containers.h" +/** + * @class ACE_Timeprobe + * + * @brief This class is used to instrument code. This is accomplished + * by inserting time probes at different location in the code. + * ACE_Timeprobe then measures the time difference between two + * time probes. + * + * This class provides a lightweight implementation for + * measuring the time required to execute code between two time + * probes. When a time probe executes, it records the time, the + * id of the calling thread, and an event description. The + * event description can either be an unsigned long or a string + * (char *). If string are used, care must be taken cause only + * pointer copies are done and the string data is *not* copied. + * The recorded time probes can then be printed by calling + * <print_times>. If you have used unsigned longs as event + * descriptions in any of your time probes, you must have + * provided an event description table that maps the unsigned + * longs to readable strings. This map is a simple array of + * strings, and the event number is used as the index into the + * array when looking for the event description. If you have + * only used strings for the event description, this map is not + * necessary. + * Multiple maps can also be used to chunk up the time probes. + * Each one can be added by calling <event_descriptions>. + * Different tables are used internally by consulting the + * minimum_id for each table. It is up to the user to make sure + * that multiple tables do not share the same event id range. + */ template <class ACE_LOCK> class ACE_Timeprobe { - // = TITLE - // This class is used to instrument code. This is accomplished - // by inserting time probes at different location in the code. - // ACE_Timeprobe then measures the time difference between two - // time probes. - // - // = DESCRIPTION - // This class provides a lightweight implementation for - // measuring the time required to execute code between two time - // probes. When a time probe executes, it records the time, the - // id of the calling thread, and an event description. The - // event description can either be an unsigned long or a string - // (char *). If string are used, care must be taken cause only - // pointer copies are done and the string data is *not* copied. - // - // The recorded time probes can then be printed by calling - // <print_times>. If you have used unsigned longs as event - // descriptions in any of your time probes, you must have - // provided an event description table that maps the unsigned - // longs to readable strings. This map is a simple array of - // strings, and the event number is used as the index into the - // array when looking for the event description. If you have - // only used strings for the event description, this map is not - // necessary. - // - // Multiple maps can also be used to chunk up the time probes. - // Each one can be added by calling <event_descriptions>. - // Different tables are used internally by consulting the - // minimum_id for each table. It is up to the user to make sure - // that multiple tables do not share the same event id range. public: + /// Self typedef ACE_Timeprobe<ACE_LOCK> SELF; - // Self + /// We can hold multiple event description tables. typedef ACE_Unbounded_Set<ACE_Event_Descriptions> EVENT_DESCRIPTIONS; - // We can hold multiple event description tables. + /// Create Timeprobes with <size> slots ACE_Timeprobe (u_long size = ACE_DEFAULT_TIMEPROBE_TABLE_SIZE); - // Create Timeprobes with <size> slots + /// Destructor. ~ACE_Timeprobe (void); - // Destructor. + /// Record a time. <event> is used to describe this time probe. void timeprobe (u_long event); - // Record a time. <event> is used to describe this time probe. + /// Record a time. <id> is used to describe this time probe. void timeprobe (const char *id); - // Record a time. <id> is used to describe this time probe. + /// Record event descriptions. int event_descriptions (const char **descriptions, u_long minimum_id); - // Record event descriptions. + /// Print the time probes. void print_times (void); - // Print the time probes. + /// Print the time probes. void print_absolute_times (void); - // Print the time probes. + /// Reset the slots. All old time probes will be lost. void reset (void); - // Reset the slots. All old time probes will be lost. ACE_Timeprobe (const ACE_Timeprobe<ACE_LOCK> &); // Not implemented (stupid MSVC won't let it be protected). // = (Somewhat private) Accessors + /// Event Descriptions ACE_Unbounded_Set<ACE_Event_Descriptions> &event_descriptions (void); - // Event Descriptions + /// Sorted Event Descriptions. ACE_Unbounded_Set<ACE_Event_Descriptions> &sorted_event_descriptions (void); - // Sorted Event Descriptions. + /// VME slot address. u_int *current_slot_vme_address (void); - // VME slot address. + /// Find description of event <i> const char *find_description_i (u_long i); - // Find description of event <i> + /// Sort event descriptions void sort_event_descriptions_i (void); - // Sort event descriptions + /// Time probe slots ACE_timeprobe_t *timeprobes (void); - // Time probe slots + /// Synchronization variable. ACE_LOCK &lock (void); - // Synchronization variable. + /// Max size of timestamp table u_long max_size (void); - // Max size of timestamp table + /// Current size of timestamp table u_long current_size (void); - // Current size of timestamp table protected: + /// Event Descriptions EVENT_DESCRIPTIONS event_descriptions_; - // Event Descriptions + /// Sorted Event Descriptions. EVENT_DESCRIPTIONS sorted_event_descriptions_; - // Sorted Event Descriptions. + /// Added sections below here to make compatible with the VMETRO + /// board test. u_int *current_slot_vme_address_; - // Added sections below here to make compatible with the VMETRO - // board test. + /// Time probe slots ACE_timeprobe_t *timeprobes_; - // Time probe slots + /// Synchronization variable. ACE_LOCK lock_; - // Synchronization variable. + /// Max size of timestamp table u_long max_size_; - // Max size of timestamp table + /// Current size of timestamp table u_long current_size_; - // Current size of timestamp table }; +/** + * @class ACE_Function_Timeprobe + * + * @brief Auto pointer like time probes. It will record <event> on + * construction and <event + 1> on destruction. + */ template <class Timeprobe> class ACE_Function_Timeprobe { - // = TITLE - // Auto pointer like time probes. It will record <event> on - // construction and <event + 1> on destruction. public: + /// Constructor. ACE_Function_Timeprobe (Timeprobe &timeprobe, u_long event); - // Constructor. + /// Destructor. ~ACE_Function_Timeprobe (void); - // Destructor. protected: + /// Reference to timeprobe. Timeprobe &timeprobe_; - // Reference to timeprobe. + /// Event. u_long event_; - // Event. }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/ace/Timer_Hash.h b/ace/Timer_Hash.h index c86d3bd1730..189fbb7bace 100644 --- a/ace/Timer_Hash.h +++ b/ace/Timer_Hash.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timer_Hash.h -// -// = AUTHOR -// Darrell Brunsch <brunsch@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Timer_Hash.h + * + * $Id$ + * + * @author Darrell Brunsch <brunsch@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_TIMER_HASH_H #define ACE_TIMER_HASH_H diff --git a/ace/Timer_Hash_T.h b/ace/Timer_Hash_T.h index a35ff3cc2da..42ef2b47a35 100644 --- a/ace/Timer_Hash_T.h +++ b/ace/Timer_Hash_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timer_Hash_T.h -// -// = AUTHOR -// Darrell Brunsch <brunsch@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Timer_Hash_T.h + * + * $Id$ + * + * @author Darrell Brunsch <brunsch@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_TIMER_HASH_T_H #define ACE_TIMER_HASH_T_H @@ -30,222 +27,244 @@ template <class TYPE, class FUNCTOR, class ACE_LOCK, class BUCKET> class ACE_Timer_Hash_T; +/** + * @class ACE_Timer_Hash_Upcall + * + * @brief Functor for Timer_Hash + * + * This class calls up to the Timer Hash's functor from the + * timer queues in the hash table + */ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_Hash_Upcall { - // = TITLE - // Functor for Timer_Hash - // - // = DESCRIPTION - // This class calls up to the Timer Hash's functor from the - // timer queues in the hash table public: typedef ACE_Timer_Queue_T<ACE_Event_Handler *, ACE_Timer_Hash_Upcall<TYPE, FUNCTOR, ACE_LOCK>, ACE_Null_Mutex> TIMER_QUEUE; + /// Default constructor (creates an invalid object, but needs to be here + /// so timer queues using this functor can be constructed) ACE_Timer_Hash_Upcall (void); - // Default constructor (creates an invalid object, but needs to be here - // so timer queues using this functor can be constructed) + /// Constructor that specifies a Timer_Hash to call up to ACE_Timer_Hash_Upcall (ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> *timer_hash); - // Constructor that specifies a Timer_Hash to call up to + /// This method is called when the timer expires int timeout (TIMER_QUEUE &timer_queue, ACE_Event_Handler *handler, const void *arg, const ACE_Time_Value &cur_time); - // This method is called when the timer expires + /// This method is called when the timer is canceled int cancellation (TIMER_QUEUE &timer_queue, ACE_Event_Handler *handler); - // This method is called when the timer is canceled + /// This method is called when the timer queue is destroyed and + /// the timer is still contained in it int deletion (TIMER_QUEUE &timer_queue, ACE_Event_Handler *handler, const void *arg); - // This method is called when the timer queue is destroyed and - // the timer is still contained in it private: + /// Timer Queue to do the calling up to ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> *timer_hash_; - // Timer Queue to do the calling up to // = Don't allow these operations for now. ACE_UNIMPLEMENTED_FUNC (ACE_Timer_Hash_Upcall (const ACE_Timer_Hash_Upcall<TYPE, FUNCTOR, ACE_LOCK> &)) ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Timer_Hash_Upcall<TYPE, FUNCTOR, ACE_LOCK> &)) }; +/** + * @class ACE_Timer_Hash_Iterator_T + * + * @brief Iterates over an <ACE_Timer_Hash>. + * + * This is a generic iterator that can be used to visit every + * node of a timer queue. Be aware that it doesn't transverse + * in the order of timeout values. + */ template <class TYPE, class FUNCTOR, class ACE_LOCK, class BUCKET> class ACE_Timer_Hash_Iterator_T : public ACE_Timer_Queue_Iterator_T <TYPE, FUNCTOR, ACE_LOCK> { - // = TITLE - // Iterates over an <ACE_Timer_Hash>. - // - // = DESCRIPTION - // This is a generic iterator that can be used to visit every - // node of a timer queue. Be aware that it doesn't transverse - // in the order of timeout values. public: + /// Constructor. ACE_Timer_Hash_Iterator_T (ACE_Timer_Hash_T<TYPE, FUNCTOR, ACE_LOCK, BUCKET> &); - // Constructor. + /// Positions the iterator at the earliest node in the Timer Queue virtual void first (void); - // Positions the iterator at the earliest node in the Timer Queue + /// Positions the iterator at the next node in the Timer Queue virtual void next (void); - // Positions the iterator at the next node in the Timer Queue + /// Returns true when there are no more nodes in the sequence virtual int isdone (void); - // Returns true when there are no more nodes in the sequence + /// Returns the node at the current position in the sequence virtual ACE_Timer_Node_T<TYPE> *item (void); - // Returns the node at the current position in the sequence protected: + /// Pointer to the <ACE_Timer_Hash> that we are iterating over. ACE_Timer_Hash_T<TYPE, FUNCTOR, ACE_LOCK, BUCKET> &timer_hash_; - // Pointer to the <ACE_Timer_Hash> that we are iterating over. + /// Current position in <timer_hash_>'s table size_t position_; - // Current position in <timer_hash_>'s table + /// Current iterator used on <position>'s bucket ACE_Timer_Queue_Iterator_T<TYPE, ACE_Timer_Hash_Upcall<TYPE, FUNCTOR, ACE_LOCK>, ACE_Null_Mutex> *iter_; - // Current iterator used on <position>'s bucket }; +/** + * @class ACE_Timer_Hash_T + * + * @brief Provides a hash table of <BUCKET>s as an implementation for + * a timer queue. + * + * This implementation uses a hash table of BUCKETs. The hash + * is based on the time_value of the event. Unlike other Timer + * Queues, ACE_Timer_Hash does not expire events in order. + */ template <class TYPE, class FUNCTOR, class ACE_LOCK, class BUCKET> class ACE_Timer_Hash_T : public ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> { - // = TITLE - // Provides a hash table of <BUCKET>s as an implementation for - // a timer queue. - // - // = DESCRIPTION - // This implementation uses a hash table of BUCKETs. The hash - // is based on the time_value of the event. Unlike other Timer - // Queues, ACE_Timer_Hash does not expire events in order. public: + /// Type of iterator typedef ACE_Timer_Hash_Iterator_T<TYPE, FUNCTOR, ACE_LOCK, BUCKET> HASH_ITERATOR; - // Type of iterator + /// Iterator is a friend friend class ACE_Timer_Hash_Iterator_T<TYPE, FUNCTOR, ACE_LOCK, BUCKET>; - // Iterator is a friend + /// Type inherited from typedef ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> INHERITED; - // Type inherited from // = Initialization and termination methods. + /** + * Default constructor. <table_size> determines the size of the + * hash table. <upcall_functor> is the instance of the FUNCTOR + * to be used by the buckets. If <upcall_functor> is 0, a default + * FUNCTOR will be created. + */ ACE_Timer_Hash_T (size_t table_size, FUNCTOR *upcall_functor = 0, ACE_Free_List<ACE_Timer_Node_T <TYPE> > *freelist = 0); - // Default constructor. <table_size> determines the size of the - // hash table. <upcall_functor> is the instance of the FUNCTOR - // to be used by the buckets. If <upcall_functor> is 0, a default - // FUNCTOR will be created. + /** + * Default constructor. <upcall_functor> is the instance of the + * FUNCTOR to be used by the queue. If <upcall_functor> is 0, Timer + * Hash will create a default FUNCTOR. <freelist> the freelist of + * timer nodes. If 0, then a default freelist will be created. The default + * size will be ACE_DEFAULT_TIMERS and there will be no preallocation. + */ ACE_Timer_Hash_T (FUNCTOR *upcall_functor = 0, ACE_Free_List<ACE_Timer_Node_T <TYPE> > *freelist = 0); - // Default constructor. <upcall_functor> is the instance of the - // FUNCTOR to be used by the queue. If <upcall_functor> is 0, Timer - // Hash will create a default FUNCTOR. <freelist> the freelist of - // timer nodes. If 0, then a default freelist will be created. The default - // size will be ACE_DEFAULT_TIMERS and there will be no preallocation. + /// Destructor virtual ~ACE_Timer_Hash_T (void); - // Destructor + /// True if queue is empty, else false. virtual int is_empty (void) const; - // True if queue is empty, else false. + /// Returns the time of the earlier node in the <ACE_Timer_Hash>. virtual const ACE_Time_Value &earliest_time (void) const; - // Returns the time of the earlier node in the <ACE_Timer_Hash>. + /** + * Schedule <type> that will expire after <delay> amount of time, + * which is specified in absolute time. If it expires then <act> is + * passed in as the value to the <functor>. If <interval> is != to + * <ACE_Time_Value::zero> then it is used to reschedule the <type> + * automatically, using relative time to the current <gettimeofday>. + * This method returns a <timer_id> that is a pointer to a token + * which stores information about the event. This <timer_id> can be + * used to cancel the timer before it expires. Returns -1 on + * failure. + */ virtual long schedule (const TYPE &type, const void *act, const ACE_Time_Value &delay, const ACE_Time_Value &interval = ACE_Time_Value::zero); - // Schedule <type> that will expire after <delay> amount of time, - // which is specified in absolute time. If it expires then <act> is - // passed in as the value to the <functor>. If <interval> is != to - // <ACE_Time_Value::zero> then it is used to reschedule the <type> - // automatically, using relative time to the current <gettimeofday>. - // This method returns a <timer_id> that is a pointer to a token - // which stores information about the event. This <timer_id> can be - // used to cancel the timer before it expires. Returns -1 on - // failure. - - virtual int reset_interval (long timer_id, + + /** + * Resets the interval of the timer represented by <timer_id> to + * <interval>, which is specified in relative time to the current + * <gettimeofday>. If <interval> is equal to + * <ACE_Time_Value::zero>, the timer will become a non-rescheduling + * timer. Returns 0 if successful, -1 if not. + */ + virtual int reset_interval (long timer_id, const ACE_Time_Value &interval); - // Resets the interval of the timer represented by <timer_id> to - // <interval>, which is specified in relative time to the current - // <gettimeofday>. If <interval> is equal to - // <ACE_Time_Value::zero>, the timer will become a non-rescheduling - // timer. Returns 0 if successful, -1 if not. + /** + * Cancel all timer associated with <type>. If <dont_call> is 0 + * then the <functor> will be invoked. Returns number of timers + * cancelled. + */ virtual int cancel (const TYPE &type, int dont_call_handle_close = 1); - // Cancel all timer associated with <type>. If <dont_call> is 0 - // then the <functor> will be invoked. Returns number of timers - // cancelled. + /** + * Cancel the single timer that matches the <timer_id> value (which + * was returned from the <schedule> method). If act is non-NULL + * then it will be set to point to the ``magic cookie'' argument + * passed in when the timer was registered. This makes it possible + * to free up the memory and avoid memory leaks. If <dont_call> is + * 0 then the <functor> will be invoked. Returns 1 if cancellation + * succeeded and 0 if the <timer_id> wasn't found. + */ virtual int cancel (long timer_id, const void **act = 0, int dont_call_handle_close = 1); - // Cancel the single timer that matches the <timer_id> value (which - // was returned from the <schedule> method). If act is non-NULL - // then it will be set to point to the ``magic cookie'' argument - // passed in when the timer was registered. This makes it possible - // to free up the memory and avoid memory leaks. If <dont_call> is - // 0 then the <functor> will be invoked. Returns 1 if cancellation - // succeeded and 0 if the <timer_id> wasn't found. + /** + * Run the <functor> for all timers whose values are <= + * <ACE_OS::gettimeofday>. Also accounts for <timer_skew>. Returns + * the number of timers canceled. + */ virtual int expire (void); - // Run the <functor> for all timers whose values are <= - // <ACE_OS::gettimeofday>. Also accounts for <timer_skew>. Returns - // the number of timers canceled. + /** + * Run the <functor> for all timers whose values are <= <cur_time>. + * This does not account for <timer_skew>. Returns the number of + * timers canceled. + */ virtual int expire (const ACE_Time_Value ¤t_time); - // Run the <functor> for all timers whose values are <= <cur_time>. - // This does not account for <timer_skew>. Returns the number of - // timers canceled. + /// Returns a pointer to this <ACE_Timer_Queue>'s iterator. virtual ACE_Timer_Queue_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> &iter (void); - // Returns a pointer to this <ACE_Timer_Queue>'s iterator. + /// Removes the earliest node from the queue and returns it virtual ACE_Timer_Node_T<TYPE> *remove_first (void); - // Removes the earliest node from the queue and returns it + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Reads the earliest node from the queue and returns it. virtual ACE_Timer_Node_T<TYPE> *get_first (void); - // Reads the earliest node from the queue and returns it. private: + /// Reschedule an "interval" <ACE_Timer_Node>. virtual void reschedule (ACE_Timer_Node_T<TYPE> *); - // Reschedule an "interval" <ACE_Timer_Node>. + /// Finds the earliest node void find_new_earliest (void); - // Finds the earliest node + /// Keeps track of the size of the queue size_t size_; - // Keeps track of the size of the queue + /// Table of BUCKETS BUCKET **table_; - // Table of BUCKETS + /// Keeps track of the size of <table> size_t table_size_; - // Keeps track of the size of <table> + /// Functor used for the table's timer queues ACE_Timer_Hash_Upcall<TYPE, FUNCTOR, ACE_LOCK> table_functor_; - // Functor used for the table's timer queues + /// Index to the position with the earliest entry size_t earliest_position_; - // Index to the position with the earliest entry + /// Iterator used to expire timers. HASH_ITERATOR *iterator_; - // Iterator used to expire timers. // = Don't allow these operations for now. ACE_UNIMPLEMENTED_FUNC (ACE_Timer_Hash_T (const ACE_Timer_Hash_T<TYPE, FUNCTOR, ACE_LOCK, BUCKET> &)) diff --git a/ace/Timer_Heap.h b/ace/Timer_Heap.h index dcaabc00051..5db29677f75 100644 --- a/ace/Timer_Heap.h +++ b/ace/Timer_Heap.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timer_Heap.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Timer_Heap.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_TIMER_HEAP_H #define ACE_TIMER_HEAP_H diff --git a/ace/Timer_Heap_T.h b/ace/Timer_Heap_T.h index 54b74e660ba..4eee67b00ad 100644 --- a/ace/Timer_Heap_T.h +++ b/ace/Timer_Heap_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timer_Heap_T.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Timer_Heap_T.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_TIMER_HEAP_T_H #define ACE_TIMER_HEAP_T_H @@ -31,58 +28,62 @@ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_Heap_T; +/** + * @class ACE_Timer_Heap_Iterator_T + * + * @brief Iterates over an <ACE_Timer_Heap_T>. + * + * This is a generic iterator that can be used to visit every + * node of a timer queue. Be aware that it doesn't transverse + * in the order of timeout values. + */ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_Heap_Iterator_T : public ACE_Timer_Queue_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> { - // = TITLE - // Iterates over an <ACE_Timer_Heap_T>. - // - // = DESCRIPTION - // This is a generic iterator that can be used to visit every - // node of a timer queue. Be aware that it doesn't transverse - // in the order of timeout values. public: + /// Constructor. ACE_Timer_Heap_Iterator_T (ACE_Timer_Heap_T<TYPE, FUNCTOR, ACE_LOCK> &); - // Constructor. + /// Destructor. ~ACE_Timer_Heap_Iterator_T (void); - // Destructor. + /// Positions the iterator at the earliest node in the Timer Queue virtual void first (void); - // Positions the iterator at the earliest node in the Timer Queue + /// Positions the iterator at the next node in the Timer Queue virtual void next (void); - // Positions the iterator at the next node in the Timer Queue + /// Returns true when there are no more nodes in the sequence virtual int isdone (void); - // Returns true when there are no more nodes in the sequence + /// Returns the node at the current position in the sequence virtual ACE_Timer_Node_T<TYPE> *item (void); - // Returns the node at the current position in the sequence protected: + /// Pointer to the <ACE_Timer_Heap> that we are iterating over. ACE_Timer_Heap_T<TYPE, FUNCTOR, ACE_LOCK> &timer_heap_; - // Pointer to the <ACE_Timer_Heap> that we are iterating over. + /// Position in the array where the iterator is at size_t position_; - // Position in the array where the iterator is at }; +/** + * @class ACE_Timer_Heap_T + * + * @brief Provides a very fast and predictable timer implementation. + * + * This implementation uses a heap-based callout queue of + * absolute times. Therefore, in the average and worst case, + * scheduling, canceling, and expiring timers is O(log N) (where + * N is the total number of timers). In addition, we can also + * preallocate as many <ACE_Timer_Nodes> as there are slots in + * the heap. This allows us to completely remove the need for + * dynamic memory allocation, which is important for real-time + * systems. + */ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_Heap_T : public ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> { - // = TITLE - // Provides a very fast and predictable timer implementation. - // - // = DESCRIPTION - // This implementation uses a heap-based callout queue of - // absolute times. Therefore, in the average and worst case, - // scheduling, canceling, and expiring timers is O(log N) (where - // N is the total number of timers). In addition, we can also - // preallocate as many <ACE_Timer_Nodes> as there are slots in - // the heap. This allows us to completely remove the need for - // dynamic memory allocation, which is important for real-time - // systems. public: typedef ACE_Timer_Heap_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> HEAP_ITERATOR; friend class ACE_Timer_Heap_Iterator_T<TYPE, FUNCTOR, ACE_LOCK>; @@ -90,183 +91,207 @@ public: typedef ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> INHERITED; // = Initialization and termination methods. + /** + * The Constructor creates a heap with <size> elements. If + * <preallocated> is non-0 then we'll pre-allocate all the memory + * for the <ACE_Timer_Nodes>. This saves time and is more + * predictable (though it requires more space). Otherwise, we'll + * just allocate the nodes as we need them. This can also take in a + * upcall functor and freelist (if 0, then defaults will be created) + */ ACE_Timer_Heap_T (size_t size, int preallocated = 0, FUNCTOR *upcall_functor = 0, ACE_Free_List<ACE_Timer_Node_T <TYPE> > *freelist = 0); - // The Constructor creates a heap with <size> elements. If - // <preallocated> is non-0 then we'll pre-allocate all the memory - // for the <ACE_Timer_Nodes>. This saves time and is more - // predictable (though it requires more space). Otherwise, we'll - // just allocate the nodes as we need them. This can also take in a - // upcall functor and freelist (if 0, then defaults will be created) + /** + * Default constructor. <upcall_functor> is the instance of the + * FUNCTOR to be used by the queue. If <upcall_functor> is 0, Timer + * Heap will create a default FUNCTOR. <freelist> the freelist of + * timer nodes. If 0, then a default freelist will be created. The default + * size will be ACE_DEFAULT_TIMERS and there will be no preallocation. + */ ACE_Timer_Heap_T (FUNCTOR *upcall_functor = 0, ACE_Free_List<ACE_Timer_Node_T <TYPE> > *freelist = 0); - // Default constructor. <upcall_functor> is the instance of the - // FUNCTOR to be used by the queue. If <upcall_functor> is 0, Timer - // Heap will create a default FUNCTOR. <freelist> the freelist of - // timer nodes. If 0, then a default freelist will be created. The default - // size will be ACE_DEFAULT_TIMERS and there will be no preallocation. + /// Destructor. virtual ~ACE_Timer_Heap_T (void); - // Destructor. + /// True if heap is empty, else false. virtual int is_empty (void) const; - // True if heap is empty, else false. + /// Returns the time of the earlier node in the Timer_Queue. virtual const ACE_Time_Value &earliest_time (void) const; - // Returns the time of the earlier node in the Timer_Queue. + /** + * Schedule <type> that will expire after <delay> amount of time, + * which is specified in absolute time. If it expires then <act> is + * passed in as the value to the <functor>. If <interval> is != to + * <ACE_Time_Value::zero> then it is used to reschedule the <type> + * automatically, using relative time to the current <gettimeofday>. + * This method returns a <timer_id> that uniquely identifies the the + * <type> entry in an internal list. This <timer_id> can be used to + * cancel the timer before it expires. The cancellation ensures + * that <timer_ids> are unique up to values of greater than 2 + * billion timers. As long as timers don't stay around longer than + * this there should be no problems with accidentally deleting the + * wrong timer. Returns -1 on failure (which is guaranteed never to + * be a valid <timer_id>). + */ virtual long schedule (const TYPE &type, const void *act, const ACE_Time_Value &delay, const ACE_Time_Value &interval = ACE_Time_Value::zero); - // Schedule <type> that will expire after <delay> amount of time, - // which is specified in absolute time. If it expires then <act> is - // passed in as the value to the <functor>. If <interval> is != to - // <ACE_Time_Value::zero> then it is used to reschedule the <type> - // automatically, using relative time to the current <gettimeofday>. - // This method returns a <timer_id> that uniquely identifies the the - // <type> entry in an internal list. This <timer_id> can be used to - // cancel the timer before it expires. The cancellation ensures - // that <timer_ids> are unique up to values of greater than 2 - // billion timers. As long as timers don't stay around longer than - // this there should be no problems with accidentally deleting the - // wrong timer. Returns -1 on failure (which is guaranteed never to - // be a valid <timer_id>). - - virtual int reset_interval (long timer_id, + + /** + * Resets the interval of the timer represented by <timer_id> to + * <interval>, which is specified in relative time to the current + * <gettimeofday>. If <interval> is equal to + * <ACE_Time_Value::zero>, the timer will become a non-rescheduling + * timer. Returns 0 if successful, -1 if not. + */ + virtual int reset_interval (long timer_id, const ACE_Time_Value &interval); - // Resets the interval of the timer represented by <timer_id> to - // <interval>, which is specified in relative time to the current - // <gettimeofday>. If <interval> is equal to - // <ACE_Time_Value::zero>, the timer will become a non-rescheduling - // timer. Returns 0 if successful, -1 if not. + /** + * Cancel all timer associated with <type>. If <dont_call> is 0 + * then the <functor> will be invoked. Returns number of timers + * cancelled. + */ virtual int cancel (const TYPE &type, int dont_call_handle_close = 1); - // Cancel all timer associated with <type>. If <dont_call> is 0 - // then the <functor> will be invoked. Returns number of timers - // cancelled. + /** + * Cancel the single timer that matches the <timer_id> value (which + * was returned from the <schedule> method). If act is non-NULL + * then it will be set to point to the ``magic cookie'' argument + * passed in when the timer was registered. This makes it possible + * to free up the memory and avoid memory leaks. If <dont_call> is + * 0 then the <functor> will be invoked. Returns 1 if cancellation + * succeeded and 0 if the <timer_id> wasn't found. + */ virtual int cancel (long timer_id, const void **act = 0, int dont_call_handle_close = 1); - // Cancel the single timer that matches the <timer_id> value (which - // was returned from the <schedule> method). If act is non-NULL - // then it will be set to point to the ``magic cookie'' argument - // passed in when the timer was registered. This makes it possible - // to free up the memory and avoid memory leaks. If <dont_call> is - // 0 then the <functor> will be invoked. Returns 1 if cancellation - // succeeded and 0 if the <timer_id> wasn't found. + /// Returns a pointer to this <ACE_Timer_Queue>'s iterator. virtual ACE_Timer_Queue_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> &iter (void); - // Returns a pointer to this <ACE_Timer_Queue>'s iterator. + /// Removes the earliest node from the queue and returns it ACE_Timer_Node_T <TYPE> *remove_first (void); - // Removes the earliest node from the queue and returns it + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Reads the earliest node from the queue and returns it. virtual ACE_Timer_Node_T<TYPE> *get_first (void); - // Reads the earliest node from the queue and returns it. protected: + /// Reschedule an "interval" <ACE_Timer_Node>. virtual void reschedule (ACE_Timer_Node_T<TYPE> *); - // Reschedule an "interval" <ACE_Timer_Node>. + /// Factory method that allocates a new node (uses operator new if + /// we're *not* preallocating, otherwise uses an internal freelist). virtual ACE_Timer_Node_T<TYPE> *alloc_node (void); - // Factory method that allocates a new node (uses operator new if - // we're *not* preallocating, otherwise uses an internal freelist). + /** + * Factory method that frees a previously allocated node (uses + * operatord delete if we're *not* preallocating, otherwise uses an + * internal freelist). + */ virtual void free_node (ACE_Timer_Node_T<TYPE> *); - // Factory method that frees a previously allocated node (uses - // operatord delete if we're *not* preallocating, otherwise uses an - // internal freelist). private: + /// Remove and return the <slot>th <ACE_Timer_Node> and restore the + /// heap property. ACE_Timer_Node_T<TYPE> *remove (size_t slot); - // Remove and return the <slot>th <ACE_Timer_Node> and restore the - // heap property. + /// Insert <new_node> into the heap and restore the heap property. void insert (ACE_Timer_Node_T<TYPE> *new_node); - // Insert <new_node> into the heap and restore the heap property. + /** + * Doubles the size of the heap and the corresponding timer_ids array. + * If preallocation is used, will also double the size of the + * preallocated array of ACE_Timer_Nodes. + */ void grow_heap (void); - // Doubles the size of the heap and the corresponding timer_ids array. - // If preallocation is used, will also double the size of the - // preallocated array of ACE_Timer_Nodes. + /// Restore the heap property, starting at <slot>. void reheap_up (ACE_Timer_Node_T<TYPE> *new_node, size_t slot, size_t parent); - // Restore the heap property, starting at <slot>. + /// Restore the heap property, starting at <slot>. void reheap_down (ACE_Timer_Node_T<TYPE> *moved_node, size_t slot, size_t child); - // Restore the heap property, starting at <slot>. + /// Copy <moved_node> into the <slot> slot of <heap_> and move + /// <slot> into the corresponding slot in the <timer_id_> array. void copy (int slot, ACE_Timer_Node_T<TYPE> *moved_node); - // Copy <moved_node> into the <slot> slot of <heap_> and move - // <slot> into the corresponding slot in the <timer_id_> array. + /** + * Returns a timer id that uniquely identifies this timer. This id + * can be used to cancel a timer via the <cancel (int)> method. The + * timer id returned from this method will never == -1 to avoid + * conflicts with other failure return values. + */ int timer_id (void); - // Returns a timer id that uniquely identifies this timer. This id - // can be used to cancel a timer via the <cancel (int)> method. The - // timer id returned from this method will never == -1 to avoid - // conflicts with other failure return values. + /// Pops and returns a new timer id from the freelist. int pop_freelist (void); - // Pops and returns a new timer id from the freelist. + /// Pushes <old_id> onto the freelist. void push_freelist (int old_id); - // Pushes <old_id> onto the freelist. + /// Maximum size of the heap. size_t max_size_; - // Maximum size of the heap. + /// Current size of the heap. size_t cur_size_; - // Current size of the heap. + /// Iterator used to expire timers. HEAP_ITERATOR *iterator_; - // Iterator used to expire timers. + /** + * Current contents of the Heap, which is organized as a "heap" of + * <ACE_Timer_Node> *'s. In this context, a heap is a "partially + * ordered, almost complete" binary tree, which is stored in an + * array. + */ ACE_Timer_Node_T<TYPE> **heap_; - // Current contents of the Heap, which is organized as a "heap" of - // <ACE_Timer_Node> *'s. In this context, a heap is a "partially - // ordered, almost complete" binary tree, which is stored in an - // array. + /** + * An array of "pointers" that allows each <ACE_Timer_Node> in the + * <heap_> to be located in O(1) time. Basically, <timer_id_[i]> + * contains the slot in the <heap_> array where an <ACE_Timer_Node> + * * with timer id <i> resides. Thus, the timer id passed back from + * <schedule> is really an slot into the <timer_ids> array. The + * <timer_ids_> array serves two purposes: negative values are + * treated as "pointers" for the <freelist_>, whereas positive + * values are treated as "pointers" into the <heap_> array. + */ long *timer_ids_; - // An array of "pointers" that allows each <ACE_Timer_Node> in the - // <heap_> to be located in O(1) time. Basically, <timer_id_[i]> - // contains the slot in the <heap_> array where an <ACE_Timer_Node> - // * with timer id <i> resides. Thus, the timer id passed back from - // <schedule> is really an slot into the <timer_ids> array. The - // <timer_ids_> array serves two purposes: negative values are - // treated as "pointers" for the <freelist_>, whereas positive - // values are treated as "pointers" into the <heap_> array. + /// "Pointer" to the first element in the freelist contained within + /// the <timer_ids_> array, which is organized as a stack. long timer_ids_freelist_; - // "Pointer" to the first element in the freelist contained within - // the <timer_ids_> array, which is organized as a stack. + /** + * If this is non-0, then we preallocate <max_size_> number of + * <ACE_Timer_Node> objects in order to reduce dynamic allocation + * costs. In auto-growing implementation, this points to the + * last array of nodes allocated. + */ ACE_Timer_Node_T<TYPE> *preallocated_nodes_; - // If this is non-0, then we preallocate <max_size_> number of - // <ACE_Timer_Node> objects in order to reduce dynamic allocation - // costs. In auto-growing implementation, this points to the - // last array of nodes allocated. + /// This points to the head of the <preallocated_nodes_> freelist, + /// which is organized as a stack. ACE_Timer_Node_T<TYPE> *preallocated_nodes_freelist_; - // This points to the head of the <preallocated_nodes_> freelist, - // which is organized as a stack. + /// Set of pointers to the arrays of preallocated timer nodes. + /// Used to delete the allocated memory when required. ACE_Unbounded_Set<ACE_Timer_Node_T<TYPE> *> preallocated_node_set_; - // Set of pointers to the arrays of preallocated timer nodes. - // Used to delete the allocated memory when required. // = Don't allow these operations for now. ACE_UNIMPLEMENTED_FUNC (ACE_Timer_Heap_T (const ACE_Timer_Heap_T<TYPE, FUNCTOR, ACE_LOCK> &)) diff --git a/ace/Timer_List.h b/ace/Timer_List.h index 3f9c6b462b3..a9586061307 100644 --- a/ace/Timer_List.h +++ b/ace/Timer_List.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timer_List.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Timer_List.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_TIMER_LIST_H #define ACE_TIMER_LIST_H diff --git a/ace/Timer_List_T.h b/ace/Timer_List_T.h index d8e1970f8c2..25b980db903 100644 --- a/ace/Timer_List_T.h +++ b/ace/Timer_List_T.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timer_List_T.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Timer_List_T.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_TIMER_LIST_T_H #define ACE_TIMER_LIST_T_H @@ -28,165 +25,180 @@ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_List_T; +/** + * @class ACE_Timer_List_Iterator_T + * + * @brief Iterates over an <ACE_Timer_List>. + * + * This is a generic iterator that can be used to visit every + * node of a timer queue. + */ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_List_Iterator_T : public ACE_Timer_Queue_Iterator_T <TYPE, FUNCTOR, ACE_LOCK> { - // = TITLE - // Iterates over an <ACE_Timer_List>. - // - // = DESCRIPTION - // This is a generic iterator that can be used to visit every - // node of a timer queue. public: + /// Constructor. ACE_Timer_List_Iterator_T (ACE_Timer_List_T<TYPE, FUNCTOR, ACE_LOCK> &); - // Constructor. + /// Destructor. ~ACE_Timer_List_Iterator_T (void); - // Destructor. + /// Positions the iterator at the earliest node in the Timer Queue virtual void first (void); - // Positions the iterator at the earliest node in the Timer Queue + /// Positions the iterator at the next node in the Timer Queue virtual void next (void); - // Positions the iterator at the next node in the Timer Queue + /// Returns true when there are no more nodes in the sequence virtual int isdone (void); - // Returns true when there are no more nodes in the sequence + /// Returns the node at the current position in the sequence virtual ACE_Timer_Node_T<TYPE> *item (void); - // Returns the node at the current position in the sequence protected: + /// Pointer to the <ACE_Timer_List> that we are iterating over. ACE_Timer_List_T<TYPE, FUNCTOR, ACE_LOCK> &timer_list_; - // Pointer to the <ACE_Timer_List> that we are iterating over. ACE_Timer_Node_T<TYPE> *position_; }; +/** + * @class ACE_Timer_List_T + * + * @brief Provides a simple implementation of timers. + * + * This implementation uses a linked list of absolute times. + * Therefore, in the average case, scheduling and canceling + * timers is O(N) (where N is the total number of timers) and + * expiring timers is O(K) (where K is the total number of timers + * that are < the current time of day). + * More clever implementations could use a delta-list, a heap, + * or timing wheels, etc. For instance, <ACE_Timer_Heap> + * is a subclass of <ACE_Timer_List> that implements a + * heap-based callout queue. For most applications, the + * <ACE_Timer_Heap> will perform substantially faster than the + * <ACE_Timer_List>. + */ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_List_T : public ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> { - // = TITLE - // Provides a simple implementation of timers. - // - // = DESCRIPTION - // This implementation uses a linked list of absolute times. - // Therefore, in the average case, scheduling and canceling - // timers is O(N) (where N is the total number of timers) and - // expiring timers is O(K) (where K is the total number of timers - // that are < the current time of day). - // - // More clever implementations could use a delta-list, a heap, - // or timing wheels, etc. For instance, <ACE_Timer_Heap> - // is a subclass of <ACE_Timer_List> that implements a - // heap-based callout queue. For most applications, the - // <ACE_Timer_Heap> will perform substantially faster than the - // <ACE_Timer_List>. public: + /// Type of iterator typedef ACE_Timer_List_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> LIST_ITERATOR; - // Type of iterator + /// Iterator is a friend friend class ACE_Timer_List_Iterator_T<TYPE, FUNCTOR, ACE_LOCK>; - // Iterator is a friend + /// Type inherited from typedef ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> INHERITED; - // Type inherited from // = Initialization and termination methods. + /** + * Default constructor. <upcall_functor> is the instance of the + * FUNCTOR to be used by the list. If <upcall_functor> is 0, a + * default FUNCTOR will be created. <freelist> the freelist of + * timer nodes. If 0, then a default freelist will be created. + */ ACE_Timer_List_T (FUNCTOR *upcall_functor = 0, ACE_Free_List<ACE_Timer_Node_T <TYPE> > *freelist = 0); - // Default constructor. <upcall_functor> is the instance of the - // FUNCTOR to be used by the list. If <upcall_functor> is 0, a - // default FUNCTOR will be created. <freelist> the freelist of - // timer nodes. If 0, then a default freelist will be created. + /// Destructor virtual ~ACE_Timer_List_T (void); - // Destructor + /// True if queue is empty, else false. virtual int is_empty (void) const; - // True if queue is empty, else false. + /// Returns the time of the earlier node in the <ACE_Timer_List>. virtual const ACE_Time_Value &earliest_time (void) const; - // Returns the time of the earlier node in the <ACE_Timer_List>. + /** + * Schedule <type> that will expire after <delay> amount of time, + * which is specified in absolute time. If it expires then <act> is + * passed in as the value to the <functor>. If <interval> is != to + * <ACE_Time_Value::zero> then it is used to reschedule the <type> + * automatically, using relative time to the current <gettimeofday>. + * This method returns a <timer_id> that uniquely identifies the the + * <type> entry in an internal list. This <timer_id> can be used to + * cancel the timer before it expires. The cancellation ensures + * that <timer_ids> are unique up to values of greater than 2 + * billion timers. As long as timers don't stay around longer than + * this there should be no problems with accidentally deleting the + * wrong timer. Returns -1 on failure (which is guaranteed never to + * be a valid <timer_id>). + */ virtual long schedule (const TYPE &type, const void *act, const ACE_Time_Value &delay, const ACE_Time_Value &interval = ACE_Time_Value::zero); - // Schedule <type> that will expire after <delay> amount of time, - // which is specified in absolute time. If it expires then <act> is - // passed in as the value to the <functor>. If <interval> is != to - // <ACE_Time_Value::zero> then it is used to reschedule the <type> - // automatically, using relative time to the current <gettimeofday>. - // This method returns a <timer_id> that uniquely identifies the the - // <type> entry in an internal list. This <timer_id> can be used to - // cancel the timer before it expires. The cancellation ensures - // that <timer_ids> are unique up to values of greater than 2 - // billion timers. As long as timers don't stay around longer than - // this there should be no problems with accidentally deleting the - // wrong timer. Returns -1 on failure (which is guaranteed never to - // be a valid <timer_id>). - - virtual int reset_interval (long timer_id, + + /** + * Resets the interval of the timer represented by <timer_id> to + * <interval>, which is specified in relative time to the current + * <gettimeofday>. If <interval> is equal to + * <ACE_Time_Value::zero>, the timer will become a non-rescheduling + * timer. Returns 0 if successful, -1 if not. + */ + virtual int reset_interval (long timer_id, const ACE_Time_Value &interval); - // Resets the interval of the timer represented by <timer_id> to - // <interval>, which is specified in relative time to the current - // <gettimeofday>. If <interval> is equal to - // <ACE_Time_Value::zero>, the timer will become a non-rescheduling - // timer. Returns 0 if successful, -1 if not. + /** + * Cancel all timer associated with <type>. If <dont_call> is 0 + * then the <functor> will be invoked. Returns number of timers + * cancelled. + */ virtual int cancel (const TYPE &type, int dont_call_handle_close = 1); - // Cancel all timer associated with <type>. If <dont_call> is 0 - // then the <functor> will be invoked. Returns number of timers - // cancelled. + /** + * Cancel the single timer that matches the <timer_id> value (which + * was returned from the <schedule> method). If act is non-NULL + * then it will be set to point to the ``magic cookie'' argument + * passed in when the timer was registered. This makes it possible + * to free up the memory and avoid memory leaks. If <dont_call> is + * 0 then the <functor> will be invoked. Returns 1 if cancellation + * succeeded and 0 if the <timer_id> wasn't found. + */ virtual int cancel (long timer_id, const void **act = 0, int dont_call_handle_close = 1); - // Cancel the single timer that matches the <timer_id> value (which - // was returned from the <schedule> method). If act is non-NULL - // then it will be set to point to the ``magic cookie'' argument - // passed in when the timer was registered. This makes it possible - // to free up the memory and avoid memory leaks. If <dont_call> is - // 0 then the <functor> will be invoked. Returns 1 if cancellation - // succeeded and 0 if the <timer_id> wasn't found. + /// Returns a pointer to this <ACE_Timer_Queue>'s iterator. virtual ACE_Timer_Queue_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> &iter (void); - // Returns a pointer to this <ACE_Timer_Queue>'s iterator. + /// Removes the earliest node from the queue and returns it virtual ACE_Timer_Node_T<TYPE> *remove_first (void); - // Removes the earliest node from the queue and returns it + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Reschedule an "interval" <ACE_Timer_Node>. This should be private + /// but for now it needs to be public for <ACE_Timer_Hash_T> virtual void reschedule (ACE_Timer_Node_T<TYPE> *); - // Reschedule an "interval" <ACE_Timer_Node>. This should be private - // but for now it needs to be public for <ACE_Timer_Hash_T> + /// Reads the earliest node from the queue and returns it. virtual ACE_Timer_Node_T<TYPE> *get_first (void); - // Reads the earliest node from the queue and returns it. protected: + /// Factory method that allocates a new node (uses operator new). /* virtual ACE_Timer_Node_T<TYPE> *alloc_node (void); - // Factory method that allocates a new node (uses operator new). + /// Factory method that frees a previously allocated node (uses + /// operator delete). virtual void free_node (ACE_Timer_Node_T<TYPE> *); - // Factory method that frees a previously allocated node (uses - // operator delete). */ private: + /// Pointer to linked list of <ACE_Timer_Handles>. ACE_Timer_Node_T<TYPE> *head_; - // Pointer to linked list of <ACE_Timer_Handles>. + /// Iterator used to expire timers. LIST_ITERATOR *iterator_; - // Iterator used to expire timers. + /** + * Keeps track of the timer id that uniquely identifies each timer. + * This id can be used to cancel a timer via the <cancel (int)> + * method. + */ long timer_id_; - // Keeps track of the timer id that uniquely identifies each timer. - // This id can be used to cancel a timer via the <cancel (int)> - // method. // = Don't allow these operations for now. ACE_UNIMPLEMENTED_FUNC (ACE_Timer_List_T (const ACE_Timer_List_T<TYPE, FUNCTOR, ACE_LOCK> &)) diff --git a/ace/Timer_Queue.h b/ace/Timer_Queue.h index e754cd60f96..45c5b5640d9 100644 --- a/ace/Timer_Queue.h +++ b/ace/Timer_Queue.h @@ -1,18 +1,15 @@ -// $Id$ /* -*- C++ -*- */ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timer_Queue.h -// -// = AUTHOR -// Doug Schmidt and Irfan Pyarali -// -// ============================================================================ +//============================================================================= +/** + * @file Timer_Queue.h + * + * $Id$ + * + * @author Doug Schmidt and Irfan Pyarali + */ +//============================================================================= + #ifndef ACE_TIMER_QUEUE_H #define ACE_TIMER_QUEUE_H diff --git a/ace/Timer_Queue_Adapters.h b/ace/Timer_Queue_Adapters.h index 174275b13f5..0f6619b1463 100644 --- a/ace/Timer_Queue_Adapters.h +++ b/ace/Timer_Queue_Adapters.h @@ -1,18 +1,15 @@ // -*- C++ -*- -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timer_Queue_Adapters.h -// -// = AUTHOR -// Douglas C. Schmidt and Carlos O'Ryan -// -// ============================================================================ + +//============================================================================= +/** + * @file Timer_Queue_Adapters.h + * + * $Id$ + * + * @author Douglas C. Schmidt and Carlos O'Ryan + */ +//============================================================================= + #ifndef ACE_TIMER_QUEUE_ADAPTERS_H # define ACE_TIMER_QUEUE_ADAPTERS_H @@ -26,119 +23,134 @@ # include "ace/Signal.h" +/** + * @class ACE_Async_Timer_Queue_Adapter + * + * @brief Adapts a <TQ> to be run asynchronously. + * + * This implementation uses the <ualarm> call, which generates + * the SIGARLM signal that is caught by this class. + */ template <class TQ> class ACE_Export ACE_Async_Timer_Queue_Adapter : public ACE_Event_Handler { - // = TITLE - // Adapts a <TQ> to be run asynchronously. - // - // = DESCRIPTION - // This implementation uses the <ualarm> call, which generates - // the SIGARLM signal that is caught by this class. public: typedef TQ TIMER_QUEUE; + /// Constructor + /** + * Register the SIGALRM handler. If <mask> == 0 then block all + * signals when <SIGALRM> is run. Otherwise, just block the signals + * indicated in <mask>. + */ ACE_Async_Timer_Queue_Adapter (ACE_Sig_Set *mask = 0); - // Register the SIGALRM handler. If <mask> == 0 then block all - // signals when <SIGALRM> is run. Otherwise, just block the signals - // indicated in <mask>. + /// Schedule the timer according to the semantics of the + /// <ACE_Timer_List>. + /** + * Tthis timer gets dispatched via a signal, rather than by a user + * calling <expire>. Note that interval timers are not implemented + * yet. + */ long schedule (ACE_Event_Handler *type, const void *act, const ACE_Time_Value &delay, const ACE_Time_Value &interval = ACE_Time_Value::zero); - // Schedule the timer according to the semantics of the - // <ACE_Timer_List>. However, this timer gets dispatched via a - // signal, rather than by a user calling <expire>. Note that - // interval timers are not implemented yet. + /// Cancel the <timer_id> and pass back the <act> if an address is + /// passed in. int cancel (long timer_id, const void **act = 0); - // Cancel the <timer_id> and pass back the <act> if an address is - // passed in. + /// Dispatch all timers whose values are <= <cur_time>. Returns the + /// number of timers canceled. int expire (void); - // Dispatch all timers whose values are <= <cur_time>. Returns the - // number of timers canceled. + /// Access the underlying <TIMER_QUEUE>. TQ &timer_queue (void); - // Access the underlying <TIMER_QUEUE>. private: + /// Perform the logic to compute the new ualarm(2) setting. virtual int schedule_ualarm (void); - // Perform the logic to compute the new ualarm(2) setting. + /// Called back by <SIGALRM> handler. virtual int handle_signal (int signum, siginfo_t *, ucontext_t *); - // Called back by <SIGALRM> handler. + /// Handler for the <SIGALRM> signal, so that we can access our state + /// without requiring any global variables. ACE_Sig_Handler sig_handler_; - // Handler for the <SIGALRM> signal, so that we can access our state - // without requiring any global variables. + /// Implementation of the timer queue (e.g., <ACE_Timer_List>, + /// <ACE_Timer_Heap>, etc.). TQ timer_queue_; - // Implementation of the timer queue (e.g., <ACE_Timer_List>, - // <ACE_Timer_Heap>, etc.). + /// Mask of signals to be blocked when we're servicing <SIGALRM>. ACE_Sig_Set mask_; - // Mask of signals to be blocked when we're servicing <SIGALRM>. }; +/** + * @class ACE_Thread_Timer_Queue_Adapter + * + * @brief Adapts a Timer_Queue using a separate thread for dispatching. + * + * This implementation of a Timer_Queue uses a separate thread to + * dispatch the timers. The base queue need not be thread safe, + * this class takes all the necessary locks. + * + * @note This is a case were template parameters will be useful, but + * (IMHO) the effort and portability problems discourage their + * use. + * + */ template <class TQ> class ACE_Export ACE_Thread_Timer_Queue_Adapter : public ACE_Task_Base { - // = TITLE - // Adapts a Timer_Queue using a separate thread for dispatching. - // - // = DESCRIPTION - // This implementation of a Timer_Queue uses a separate thread to - // dispatch the timers. The base queue need not be thread safe, - // this class takes all the necessary locks. - // - // = NOTE - // This is a case were template parameters will be useful, but - // (IMHO) the effort and portability problems discourage their - // use. public: + /// Trait for the underlying queue type. typedef TQ TIMER_QUEUE; - // Trait for the underlying queue type. # if defined (ACE_HAS_DEFERRED_TIMER_COMMANDS) + /// Typedef for the position at which to enqueue a deferred execution command. enum COMMAND_ENQUEUE_POSITION {HEAD, TAIL}; - // Typedef for the position at which to enqueue a deferred execution command. # endif /* ACE_HAS_DEFERRED_TIMER_COMMANDS */ + /// Creates the timer queue. Activation of the task is the user's + /// responsibility. ACE_Thread_Timer_Queue_Adapter (ACE_Thread_Manager * = ACE_Thread_Manager::instance ()); - // Creates the timer queue. Activation of the task is the user's - // responsibility. + /// Schedule the timer according to the semantics of the <TQ>; wakes + /// up the dispatching thread. long schedule (ACE_Event_Handler *handler, const void *act, const ACE_Time_Value &delay, const ACE_Time_Value &interval = ACE_Time_Value::zero); - // Schedule the timer according to the semantics of the <TQ>; wakes - // up the dispatching thread. + /// Cancel the <timer_id> add return the <act> parameter if an + /// address is passed in. Also wakes up the dispatching thread. int cancel (long timer_id, const void **act = 0); - // Cancel the <timer_id> add return the <act> parameter if an - // address is passed in. Also wakes up the dispatching thread. + /// Runs the dispatching thread. virtual int svc (void); - // Runs the dispatching thread. + /// Inform the dispatching thread that it should terminate. virtual void deactivate (void); - // Inform the dispatching thread that it should terminate. + /// Access the locking mechanism, useful for iteration. ACE_SYNCH_MUTEX &mutex (void); - // Access the locking mechanism, useful for iteration. + /// Access the implementation queue, useful for iteration. TQ &timer_queue (void); - // Access the implementation queue, useful for iteration. + /// Return the thread id of our active object. ACE_thread_t thr_id (void); - // Return the thread id of our active object. + /** + * We override the default <activate> method so that we can ensure + * that only a single thread is ever spawned. Otherwise, too many + * weird things can happen... + */ virtual int activate (long flags = THR_NEW_LWP | THR_JOINABLE, int n_threads = 1, int force_active = 0, @@ -149,19 +161,18 @@ public: void *stack[] = 0, size_t stack_size[] = 0, ACE_thread_t thread_names[] = 0); - // We override the default <activate> method so that we can ensure - // that only a single thread is ever spawned. Otherwise, too many - // weird things can happen... # if defined (ACE_HAS_DEFERRED_TIMER_COMMANDS) + /** + * Enqueues a command object for execution just before waiting on the next + * timer event. This allows deferred execution of commands that cannot + * be performed in the timer event handler context, such as registering + * or cancelling timers on platforms where the timer queue mutex is not + * recursive. + */ int enqueue_command (ACE_Command_Base *command_, COMMAND_ENQUEUE_POSITION pos = TAIL); - // Enqueues a command object for execution just before waiting on the next - // timer event. This allows deferred execution of commands that cannot - // be performed in the timer event handler context, such as registering - // or cancelling timers on platforms where the timer queue mutex is not - // recursive. # endif /* ACE_HAS_DEFERRED_TIMER_COMMANDS */ @@ -169,36 +180,38 @@ private: # if defined (ACE_HAS_DEFERRED_TIMER_COMMANDS) + /// Dispatches all command objects enqueued in the most + /// recent event handler context. int dispatch_commands (void); - // Dispatches all command objects enqueued in the most - // recent event handler context. + /// Queue of commands for deferred execution. ACE_Unbounded_Queue<ACE_Command_Base *> command_queue_; - // Queue of commands for deferred execution. + /// The mutual exclusion mechanism for the command queue. ACE_SYNCH_MUTEX command_mutex_; - // The mutual exclusion mechanism for the command queue. # endif /* ACE_HAS_DEFERRED_TIMER_COMMANDS */ + /// The underlying Timer_Queue. TQ timer_queue_; - // The underlying Timer_Queue. + /** + * The dispatching thread sleeps on this condition while waiting to + * dispatch the next timer; it is used to wake it up if there is a + * change on the timer queue. + */ ACE_SYNCH_CONDITION condition_; - // The dispatching thread sleeps on this condition while waiting to - // dispatch the next timer; it is used to wake it up if there is a - // change on the timer queue. + /// The mutual exclusion mechanism which is required to use the + /// <condition_>. ACE_SYNCH_MUTEX mutex_; - // The mutual exclusion mechanism which is required to use the - // <condition_>. + /// When deactivate is called this variable turns to false and the + /// dispatching thread is signalled, to terminate its main loop. int active_; - // When deactivate is called this variable turns to false and the - // dispatching thread is signalled, to terminate its main loop. + /// Thread id of our active object task. ACE_thread_t thr_id_; - // Thread id of our active object task. }; # if defined (__ACE_INLINE__) diff --git a/ace/Timer_Queue_T.h b/ace/Timer_Queue_T.h index 2b67381c412..70ae7679936 100644 --- a/ace/Timer_Queue_T.h +++ b/ace/Timer_Queue_T.h @@ -1,19 +1,18 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timer_Queue_T.h -// -// = AUTHOR -// Doug Schmidt, Irfan Pyarali, and Darrell Brunsch -// -// ============================================================================ + +//============================================================================= +/** + * @file Timer_Queue_T.h + * + * $Id$ + * + * @author Doug Schmidt + * @author Irfan Pyarali + * @author and Darrell Brunsch + */ +//============================================================================= + #ifndef ACE_TIMER_QUEUE_T_H #define ACE_TIMER_QUEUE_T_H @@ -27,26 +26,30 @@ #include "ace/Test_and_Set.h" +/** + * @class ACE_Timer_Node_T + * + * @brief Maintains the state associated with a Timer entry. + */ template <class TYPE> class ACE_Timer_Node_T { - // = TITLE - // Maintains the state associated with a Timer entry. public: + /// Default constructor ACE_Timer_Node_T (void); - // Default constructor + /// Dtor. ~ACE_Timer_Node_T (void); - // Dtor. + /// singly linked list void set (const TYPE &type, const void *a, const ACE_Time_Value &t, const ACE_Time_Value &i, ACE_Timer_Node_T<TYPE> *n, long timer_id); - // singly linked list + /// doubly linked list version void set (const TYPE &type, const void *a, const ACE_Time_Value &t, @@ -54,301 +57,324 @@ public: ACE_Timer_Node_T<TYPE> *p, ACE_Timer_Node_T<TYPE> *n, long timer_id); - // doubly linked list version // = Accessors + /// Get the type. TYPE &get_type (void); - // Get the type. + /// Set the type. void set_type (TYPE &type); - // Set the type. + /// Get the asynchronous completion token. const void *get_act (void); - // Get the asynchronous completion token. + /// set the asynchronous completion token. void set_act (void *act); - // set the asynchronous completion token. + /// get the timer value. ACE_Time_Value &get_timer_value (void); - // get the timer value. + /// set the timer value. void set_timer_value (ACE_Time_Value timer_value); - // set the timer value. + /// get the timer interval. ACE_Time_Value &get_interval (void); - // get the timer interval. + /// Set the timer interval. void set_interval (ACE_Time_Value interval); - // Set the timer interval. + /// get the previous pointer. ACE_Timer_Node_T<TYPE> *get_prev (void); - // get the previous pointer. + /// set the previous pointer. void set_prev (ACE_Timer_Node_T<TYPE> *prev); - // set the previous pointer. + /// get the next pointer. ACE_Timer_Node_T<TYPE> *get_next (void); - // get the next pointer. + /// set the next pointer. void set_next (ACE_Timer_Node_T<TYPE> *next); - // set the next pointer. + /// get the timer_id. long get_timer_id (void); - // get the timer_id. + /// set the timer_id. void set_timer_id (long timer_id); - // set the timer_id. + /// Dump the state of an TYPE. void dump (void) const; - // Dump the state of an TYPE. private: + /// Type of object stored in the Queue TYPE type_; - // Type of object stored in the Queue + /// Asynchronous completion token associated with the timer. const void *act_; - // Asynchronous completion token associated with the timer. + /// Time until the timer expires. ACE_Time_Value timer_value_; - // Time until the timer expires. + /// If this is a periodic timer this holds the time until the next + /// timeout. ACE_Time_Value interval_; - // If this is a periodic timer this holds the time until the next - // timeout. + /// Pointer to previous timer. ACE_Timer_Node_T<TYPE> *prev_; - // Pointer to previous timer. + /// Pointer to next timer. ACE_Timer_Node_T<TYPE> *next_; - // Pointer to next timer. + /// Id of this timer (used to cancel timers before they expire). long timer_id_; - // Id of this timer (used to cancel timers before they expire). }; +/** + * @class ACE_Timer_Queue_Iterator_T + * + * @brief Generic interface for iterating over a subclass of + * <ACE_Timer_Queue>. + * + * This is a generic iterator that can be used to visit every + * node of a timer queue. Be aware that it isn't guaranteed + * that the transversal will be in order of timeout values. + */ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_Queue_Iterator_T { - // = TITLE - // Generic interface for iterating over a subclass of - // <ACE_Timer_Queue>. - // - // = DESCRIPTION - // This is a generic iterator that can be used to visit every - // node of a timer queue. Be aware that it isn't guaranteed - // that the transversal will be in order of timeout values. public: // = Initialization and termination methods. + /// Constructor. ACE_Timer_Queue_Iterator_T (void); - // Constructor. + /// Destructor. virtual ~ACE_Timer_Queue_Iterator_T (void); - // Destructor. + /// Positions the iterator at the earliest node in the Timer Queue virtual void first (void) = 0; - // Positions the iterator at the earliest node in the Timer Queue + /// Positions the iterator at the next node in the Timer Queue virtual void next (void) = 0; - // Positions the iterator at the next node in the Timer Queue + /// Returns true when there are no more nodes in the sequence virtual int isdone (void) = 0; - // Returns true when there are no more nodes in the sequence + /// Returns the node at the current position in the sequence virtual ACE_Timer_Node_T<TYPE> *item (void) = 0; - // Returns the node at the current position in the sequence }; +/** + * @class ACE_Timer_Queue_T + * + * @brief Provides an interface to timers. + * + * This is an abstract base class that provides hook for + * implementing specialized policies such as <ACE_Timer_List> + * and <ACE_Timer_Heap>. + */ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_Queue_T { - // = TITLE - // Provides an interface to timers. - // - // = DESCRIPTION - // This is an abstract base class that provides hook for - // implementing specialized policies such as <ACE_Timer_List> - // and <ACE_Timer_Heap>. public: + /// Type of Iterator. typedef ACE_Timer_Queue_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> ITERATOR; - // Type of Iterator. // = Initialization and termination methods. + /** + * Default constructor. <upcall_functor> is the instance of the + * FUNCTOR to be used by the queue. If <upcall_functor> is 0, Timer + * Queue will create a default FUNCTOR. <freelist> the freelist of + * timer nodes. If 0, then a default freelist will be created. + */ ACE_Timer_Queue_T (FUNCTOR *upcall_functor = 0, ACE_Free_List<ACE_Timer_Node_T <TYPE> > *freelist = 0); - // Default constructor. <upcall_functor> is the instance of the - // FUNCTOR to be used by the queue. If <upcall_functor> is 0, Timer - // Queue will create a default FUNCTOR. <freelist> the freelist of - // timer nodes. If 0, then a default freelist will be created. + /// Destructor - make virtual for proper destruction of inherited + /// classes. virtual ~ACE_Timer_Queue_T (void); - // Destructor - make virtual for proper destruction of inherited - // classes. + /// True if queue is empty, else false. virtual int is_empty (void) const = 0; - // True if queue is empty, else false. + /// Returns the time of the earlier node in the Timer_Queue. virtual const ACE_Time_Value &earliest_time (void) const = 0; - // Returns the time of the earlier node in the Timer_Queue. + /** + * Schedule <type> that will expire after <delay> amount of time, + * which is specified in absolute time. If it expires then <act> is + * passed in as the value to the <functor>. If <interval> is != to + * <ACE_Time_Value::zero> then it is used to reschedule the <type> + * automatically, using relative time to the current <gettimeofday>. + * This method returns a <timer_id> that uniquely identifies the the + * <type> entry in an internal list. This <timer_id> can be used to + * cancel the timer before it expires. The cancellation ensures + * that <timer_ids> are unique up to values of greater than 2 + * billion timers. As long as timers don't stay around longer than + * this there should be no problems with accidentally deleting the + * wrong timer. Returns -1 on failure (which is guaranteed never to + * be a valid <timer_id>). + */ virtual long schedule (const TYPE &type, const void *act, const ACE_Time_Value &delay, const ACE_Time_Value &interval = ACE_Time_Value::zero) = 0; - // Schedule <type> that will expire after <delay> amount of time, - // which is specified in absolute time. If it expires then <act> is - // passed in as the value to the <functor>. If <interval> is != to - // <ACE_Time_Value::zero> then it is used to reschedule the <type> - // automatically, using relative time to the current <gettimeofday>. - // This method returns a <timer_id> that uniquely identifies the the - // <type> entry in an internal list. This <timer_id> can be used to - // cancel the timer before it expires. The cancellation ensures - // that <timer_ids> are unique up to values of greater than 2 - // billion timers. As long as timers don't stay around longer than - // this there should be no problems with accidentally deleting the - // wrong timer. Returns -1 on failure (which is guaranteed never to - // be a valid <timer_id>). - - virtual int reset_interval (long timer_id, + + /** + * Resets the interval of the timer represented by <timer_id> to + * <interval>, which is specified in relative time to the current + * <gettimeofday>. If <interval> is equal to + * <ACE_Time_Value::zero>, the timer will become a non-rescheduling + * timer. Returns 0 if successful, -1 if not. + */ + virtual int reset_interval (long timer_id, const ACE_Time_Value &interval) = 0; - // Resets the interval of the timer represented by <timer_id> to - // <interval>, which is specified in relative time to the current - // <gettimeofday>. If <interval> is equal to - // <ACE_Time_Value::zero>, the timer will become a non-rescheduling - // timer. Returns 0 if successful, -1 if not. + /** + * Cancel all timer associated with <type>. If + * <dont_call_handle_close> is 0 then the <functor> will be invoked, + * which typically invokes the <handle_close> hook. Returns number + * of timers cancelled. + */ virtual int cancel (const TYPE &type, int dont_call_handle_close = 1) = 0; - // Cancel all timer associated with <type>. If - // <dont_call_handle_close> is 0 then the <functor> will be invoked, - // which typically invokes the <handle_close> hook. Returns number - // of timers cancelled. + /** + * Cancel the single timer that matches the <timer_id> value (which + * was returned from the <schedule> method). If act is non-NULL + * then it will be set to point to the ``magic cookie'' argument + * passed in when the timer was registered. This makes it possible + * to free up the memory and avoid memory leaks. If + * <dont_call_handle_close> is 0 then the <functor> will be invoked, + * which typically calls the <handle_close> hook. Returns 1 if + * cancellation succeeded and 0 if the <timer_id> wasn't found. + */ virtual int cancel (long timer_id, const void **act = 0, int dont_call_handle_close = 1) = 0; - // Cancel the single timer that matches the <timer_id> value (which - // was returned from the <schedule> method). If act is non-NULL - // then it will be set to point to the ``magic cookie'' argument - // passed in when the timer was registered. This makes it possible - // to free up the memory and avoid memory leaks. If - // <dont_call_handle_close> is 0 then the <functor> will be invoked, - // which typically calls the <handle_close> hook. Returns 1 if - // cancellation succeeded and 0 if the <timer_id> wasn't found. + /** + * Run the <functor> for all timers whose values are <= <cur_time>. + * This does not account for <timer_skew>. Returns the number of + * timers canceled. + */ virtual int expire (const ACE_Time_Value ¤t_time); - // Run the <functor> for all timers whose values are <= <cur_time>. - // This does not account for <timer_skew>. Returns the number of - // timers canceled. + /** + * Run the <functor> for all timers whose values are <= + * <ACE_OS::gettimeofday>. Also accounts for <timer_skew>. Returns + * the number of timers canceled. + */ /* virtual */ int expire (void); - // Run the <functor> for all timers whose values are <= - // <ACE_OS::gettimeofday>. Also accounts for <timer_skew>. Returns - // the number of timers canceled. + /** + * Returns the current time of day. This allows different + * implementations of the timer queue to use special high resolution + * timers. + */ /* virtual */ ACE_Time_Value gettimeofday (void); - // Returns the current time of day. This allows different - // implementations of the timer queue to use special high resolution - // timers. + /// Allows applications to control how the timer queue gets the time + /// of day. void gettimeofday (ACE_Time_Value (*gettimeofday)(void)); - // Allows applications to control how the timer queue gets the time - // of day. + /// Determine the next event to timeout. Returns <max> if there are + /// no pending timers or if all pending timers are longer than max. virtual ACE_Time_Value *calculate_timeout (ACE_Time_Value *max); - // Determine the next event to timeout. Returns <max> if there are - // no pending timers or if all pending timers are longer than max. + /** + * Determine the next event to timeout. Returns <max> if there are + * no pending timers or if all pending timers are longer than max. + * <the_timeout> should be a pointer to storage for the timeout value, + * and this value is also returned. + */ virtual ACE_Time_Value *calculate_timeout (ACE_Time_Value *max, ACE_Time_Value *the_timeout); - // Determine the next event to timeout. Returns <max> if there are - // no pending timers or if all pending timers are longer than max. - // <the_timeout> should be a pointer to storage for the timeout value, - // and this value is also returned. // = Set/get the timer skew for the Timer_Queue. void timer_skew (const ACE_Time_Value &skew); const ACE_Time_Value &timer_skew (void) const; + /// Synchronization variable used by the queue ACE_LOCK &mutex (void); - // Synchronization variable used by the queue + /// Accessor to the upcall functor FUNCTOR &upcall_functor (void); - // Accessor to the upcall functor + /// Returns a pointer to this <ACE_Timer_Queue>'s iterator. virtual ITERATOR &iter (void) = 0; - // Returns a pointer to this <ACE_Timer_Queue>'s iterator. + /// Removes the earliest node from the queue and returns it virtual ACE_Timer_Node_T<TYPE> *remove_first (void) = 0; - // Removes the earliest node from the queue and returns it + /// Dump the state of a object. virtual void dump (void) const; - // Dump the state of a object. + /// Reads the earliest node from the queue and returns it. virtual ACE_Timer_Node_T<TYPE> *get_first (void) = 0; - // Reads the earliest node from the queue and returns it. + /// Method used to return a timer node to the queue's ownership + /// after it is returned by a method like <remove_first>. virtual void return_node (ACE_Timer_Node_T<TYPE> *); - // Method used to return a timer node to the queue's ownership - // after it is returned by a method like <remove_first>. protected: + /// This method will call the <functor> with the <type>, <act> and + /// <time> /* virtual */ void upcall (TYPE &type, const void *act, const ACE_Time_Value &cur_time); - // This method will call the <functor> with the <type>, <act> and - // <time> + /// Reschedule an "interval" <ACE_Timer_Node>. virtual void reschedule (ACE_Timer_Node_T<TYPE> *) = 0; - // Reschedule an "interval" <ACE_Timer_Node>. + /// Factory method that allocates a new node. virtual ACE_Timer_Node_T<TYPE> *alloc_node (void); - // Factory method that allocates a new node. + /// Factory method that frees a previously allocated node. virtual void free_node (ACE_Timer_Node_T<TYPE> *); - // Factory method that frees a previously allocated node. + /// Synchronization variable for <ACE_Timer_Queue>. + /// NOTE: the right name would be lock_, but HP/C++ will choke on that! ACE_LOCK mutex_; - // Synchronization variable for <ACE_Timer_Queue>. - // NOTE: the right name would be lock_, but HP/C++ will choke on that! + /// Class that implements a free list ACE_Free_List<ACE_Timer_Node_T<TYPE> > *free_list_; - // Class that implements a free list + /// Pointer to function that returns the current time of day. ACE_Time_Value (*gettimeofday_)(void); - // Pointer to function that returns the current time of day. + /// Upcall functor FUNCTOR *upcall_functor_; - // Upcall functor + /// To delete or not to delete is the question? int delete_upcall_functor_; - // To delete or not to delete is the question? + /// Flag to delete only if the class created the <free_list_> int delete_free_list_; - // Flag to delete only if the class created the <free_list_> private: + /// Returned by <calculate_timeout>. ACE_Time_Value timeout_; - // Returned by <calculate_timeout>. + /// Adjusts for timer skew in various clocks. ACE_Time_Value timer_skew_; - // Adjusts for timer skew in various clocks. // = Don't allow these operations for now. ACE_UNIMPLEMENTED_FUNC (ACE_Timer_Queue_T (const ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> &)) ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> &)) }; +/** + * @class ACE_Event_Handler_Handle_Timeout_Upcall + * + * @brief Functor for Timer_Queues. + * + * This class implements the functor required by the Timer + * Queue to call <handle_timeout> on ACE_Event_Handlers. + */ template <class ACE_LOCK> class ACE_Event_Handler_Handle_Timeout_Upcall { - // = TITLE - // Functor for Timer_Queues. - // - // = DESCRIPTION - // This class implements the functor required by the Timer - // Queue to call <handle_timeout> on ACE_Event_Handlers. public: typedef ACE_Timer_Queue_T<ACE_Event_Handler *, ACE_Event_Handler_Handle_Timeout_Upcall<ACE_LOCK>, @@ -356,27 +382,27 @@ public: TIMER_QUEUE; // = Initialization and termination methods. + /// Constructor. ACE_Event_Handler_Handle_Timeout_Upcall (void); - // Constructor. + /// Destructor. ~ACE_Event_Handler_Handle_Timeout_Upcall (void); - // Destructor. + /// This method is called when the timer expires int timeout (TIMER_QUEUE &timer_queue, ACE_Event_Handler *handler, const void *arg, const ACE_Time_Value &cur_time); - // This method is called when the timer expires + /// This method is called when the timer is canceled int cancellation (TIMER_QUEUE &timer_queue, ACE_Event_Handler *handler); - // This method is called when the timer is canceled + /// This method is called when the timer queue is destroyed and + /// the timer is still contained in it int deletion (TIMER_QUEUE &timer_queue, ACE_Event_Handler *handler, const void *arg); - // This method is called when the timer queue is destroyed and - // the timer is still contained in it }; #if defined (__ACE_INLINE__) diff --git a/ace/Timer_Wheel.h b/ace/Timer_Wheel.h index 0aeae495b40..5d37d0488dc 100644 --- a/ace/Timer_Wheel.h +++ b/ace/Timer_Wheel.h @@ -1,19 +1,16 @@ -// $Id$ /* -*- C++ -*- */ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timer_Wheel.h -// -// = AUTHOR -// Darrell Brunsch (brunsch@cs.wustl.edu) -// -// ============================================================================ +//============================================================================= +/** + * @file Timer_Wheel.h + * + * $Id$ + * + * @author Darrell Brunsch (brunsch@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_TIMER_WHEEL_H #define ACE_TIMER_WHEEL_H diff --git a/ace/Timer_Wheel_T.h b/ace/Timer_Wheel_T.h index 5736c28effa..8a39fb6cd0f 100644 --- a/ace/Timer_Wheel_T.h +++ b/ace/Timer_Wheel_T.h @@ -1,19 +1,16 @@ -// $Id$ /* -*- C++ -*- */ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Timer_Wheel.h -// -// = AUTHOR -// Darrell Brunsch <brunsch@cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Timer_Wheel.h + * + * $Id$ + * + * @author Darrell Brunsch <brunsch@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_TIMER_WHEEL_T_H #define ACE_TIMER_WHEEL_T_H @@ -29,188 +26,208 @@ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_Wheel_T; +/** + * @class ACE_Timer_Wheel_Iterator_T + * + * @brief Iterates over an <ACE_Timer_Wheel>. + * + * This is a generic iterator that can be used to visit every + * node of a timer queue. Be aware that it doesn't transverse + * in the order of timeout values. + */ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_Wheel_Iterator_T : public ACE_Timer_Queue_Iterator_T <TYPE, FUNCTOR, ACE_LOCK> { - // = TITLE - // Iterates over an <ACE_Timer_Wheel>. - // - // = DESCRIPTION - // This is a generic iterator that can be used to visit every - // node of a timer queue. Be aware that it doesn't transverse - // in the order of timeout values. public: + /// Constructor ACE_Timer_Wheel_Iterator_T (ACE_Timer_Wheel_T<TYPE, FUNCTOR, ACE_LOCK> &); - // Constructor + /// Destructor ~ACE_Timer_Wheel_Iterator_T (void); - // Destructor + /// Positions the iterator at the earliest node in the Timer Queue virtual void first (void); - // Positions the iterator at the earliest node in the Timer Queue + /// Positions the iterator at the next node in the Timer Queue virtual void next (void); - // Positions the iterator at the next node in the Timer Queue + /// Returns true when there are no more nodes in the sequence virtual int isdone (void); - // Returns true when there are no more nodes in the sequence + /// Returns the node at the current position in the sequence virtual ACE_Timer_Node_T<TYPE> *item (void); - // Returns the node at the current position in the sequence protected: + /// Pointer to the <ACE_Timer_List> that we are iterating over. ACE_Timer_Wheel_T<TYPE, FUNCTOR, ACE_LOCK> &timer_wheel_; - // Pointer to the <ACE_Timer_List> that we are iterating over. + /// Current position in the timing wheel size_t pos_; - // Current position in the timing wheel + /// Pointer to the position in the the <pos_>th list ACE_Timer_Node_T<TYPE> *list_item_; - // Pointer to the position in the the <pos_>th list }; +/** + * @class ACE_Timer_Wheel_T + * + * @brief Provides a Timing Wheel version of Timer Queue + * + * This implementation uses a hash table of ordered doubly- + * linked lists of absolute times. The other enhancements + * to Timer List include using the pointer to the node as the + * timer id (to speed up removing), adding a free list and + * the ability to preallocate nodes. Timer Wheel is based on + * the timing wheel implementation used in Adam M. Costello and + * George Varghese's paper "Redesigning the BSD Callout and + * Timer Facilities" + * (http://dworkin.wustl.edu/~varghese/PAPERS/newbsd.ps.Z) + */ template <class TYPE, class FUNCTOR, class ACE_LOCK> class ACE_Timer_Wheel_T : public ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> { - // = TITLE - // Provides a Timing Wheel version of Timer Queue - // - // = DESCRIPTION - // This implementation uses a hash table of ordered doubly- - // linked lists of absolute times. The other enhancements - // to Timer List include using the pointer to the node as the - // timer id (to speed up removing), adding a free list and - // the ability to preallocate nodes. Timer Wheel is based on - // the timing wheel implementation used in Adam M. Costello and - // George Varghese's paper "Redesigning the BSD Callout and - // Timer Facilities" - // (http://dworkin.wustl.edu/~varghese/PAPERS/newbsd.ps.Z) public: + /// Type of iterator typedef ACE_Timer_Wheel_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> WHEEL_ITERATOR; - // Type of iterator + /// Iterator is a friend friend class ACE_Timer_Wheel_Iterator_T<TYPE, FUNCTOR, ACE_LOCK>; - // Iterator is a friend + /// Type inherited from typedef ACE_Timer_Queue_T<TYPE, FUNCTOR, ACE_LOCK> INHERITED; - // Type inherited from // = Initialization and termination methods + /** + * Constructor that takes in <wheelsize> - size of the timing wheel, + * <resolution> - resolution of time values the hashing function uses, + * and <upcall_functor> - a functor that will be used instead of creating + * a default functor. Also, when the freelist is created, <prealloc> nodes + * will be allocated. This can also take in a upcall functor and freelist + * (if 0, then defaults will be created) + */ ACE_Timer_Wheel_T (size_t wheelsize, size_t resolution, size_t prealloc = 0, FUNCTOR *upcall_functor = 0, ACE_Free_List<ACE_Timer_Node_T <TYPE> > *freelist = 0); - // Constructor that takes in <wheelsize> - size of the timing wheel, - // <resolution> - resolution of time values the hashing function uses, - // and <upcall_functor> - a functor that will be used instead of creating - // a default functor. Also, when the freelist is created, <prealloc> nodes - // will be allocated. This can also take in a upcall functor and freelist - // (if 0, then defaults will be created) + /** + * Default constructor. <upcall_functor> is the instance of the + * FUNCTOR to be used by the queue. If <upcall_functor> is 0, Timer + * Queue will create a default FUNCTOR. <freelist> the freelist of + * timer nodes. If 0, then a default freelist will be created. The + * defaults will be used for size and resolution and no preallocation + * (ACE_DEFAULT_TIMER_WHEEL_SIZE, ACE_DEFAULT_TIMER_WHEEL_RESOLUTION) + */ ACE_Timer_Wheel_T (FUNCTOR *upcall_functor = 0, ACE_Free_List<ACE_Timer_Node_T <TYPE> > *freelist = 0); - // Default constructor. <upcall_functor> is the instance of the - // FUNCTOR to be used by the queue. If <upcall_functor> is 0, Timer - // Queue will create a default FUNCTOR. <freelist> the freelist of - // timer nodes. If 0, then a default freelist will be created. The - // defaults will be used for size and resolution and no preallocation - // (ACE_DEFAULT_TIMER_WHEEL_SIZE, ACE_DEFAULT_TIMER_WHEEL_RESOLUTION) + /// Destructor virtual ~ACE_Timer_Wheel_T (void); - // Destructor + /// True if queue is empty, else false. virtual int is_empty (void) const; - // True if queue is empty, else false. + /// Returns the time of the earlier node in the <ACE_Timer_Wheel>. virtual const ACE_Time_Value &earliest_time (void) const; - // Returns the time of the earlier node in the <ACE_Timer_Wheel>. + /** + * Schedule <type> that will expire after <delay> amount of time, + * which is specified in absolute time. If it expires then <act> is + * passed in as the value to the <functor>. If <interval> is != to + * <ACE_Time_Value::zero> then it is used to reschedule the <type> + * automatically, using relative time to the current <gettimeofday>. + * This method returns a <timer_id> that uniquely identifies the the + * timer. This <timer_id> can be used to cancel the timer before it + * expires. Returns -1 on failure. + */ virtual long schedule (const TYPE &type, const void *act, const ACE_Time_Value &delay, const ACE_Time_Value &interval = ACE_Time_Value::zero); - // Schedule <type> that will expire after <delay> amount of time, - // which is specified in absolute time. If it expires then <act> is - // passed in as the value to the <functor>. If <interval> is != to - // <ACE_Time_Value::zero> then it is used to reschedule the <type> - // automatically, using relative time to the current <gettimeofday>. - // This method returns a <timer_id> that uniquely identifies the the - // timer. This <timer_id> can be used to cancel the timer before it - // expires. Returns -1 on failure. - - virtual int reset_interval (long timer_id, + + /** + * Resets the interval of the timer represented by <timer_id> to + * <interval>, which is specified in relative time to the current + * <gettimeofday>. If <interval> is equal to + * <ACE_Time_Value::zero>, the timer will become a non-rescheduling + * timer. Returns 0 if successful, -1 if not. + */ + virtual int reset_interval (long timer_id, const ACE_Time_Value &interval); - // Resets the interval of the timer represented by <timer_id> to - // <interval>, which is specified in relative time to the current - // <gettimeofday>. If <interval> is equal to - // <ACE_Time_Value::zero>, the timer will become a non-rescheduling - // timer. Returns 0 if successful, -1 if not. + /** + * Cancel all timer associated with <type>. If <dont_call> is 0 + * then the <functor> will be invoked. Returns number of timers + * cancelled. + */ virtual int cancel (const TYPE &type, int dont_call_handle_close = 1); - // Cancel all timer associated with <type>. If <dont_call> is 0 - // then the <functor> will be invoked. Returns number of timers - // cancelled. + /** + * Cancel the single timer that matches the <timer_id> value (which + * was returned from the <schedule> method). If act is non-NULL + * then it will be set to point to the ``magic cookie'' argument + * passed in when the timer was registered. This makes it possible + * to free up the memory and avoid memory leaks. If <dont_call> is + * 0 then the <functor> will be invoked. Returns 1 if cancellation + * succeeded and 0 if the <timer_id> wasn't found. + */ virtual int cancel (long timer_id, const void **act = 0, int dont_call_handle_close = 1); - // Cancel the single timer that matches the <timer_id> value (which - // was returned from the <schedule> method). If act is non-NULL - // then it will be set to point to the ``magic cookie'' argument - // passed in when the timer was registered. This makes it possible - // to free up the memory and avoid memory leaks. If <dont_call> is - // 0 then the <functor> will be invoked. Returns 1 if cancellation - // succeeded and 0 if the <timer_id> wasn't found. + /** + * Run the <functor> for all timers whose values are <= + * <ACE_OS::gettimeofday>. Also accounts for <timer_skew>. Returns + * the number of timers canceled. + */ virtual int expire (void); - // Run the <functor> for all timers whose values are <= - // <ACE_OS::gettimeofday>. Also accounts for <timer_skew>. Returns - // the number of timers canceled. + /** + * Run the <functor> for all timers whose values are <= <cur_time>. + * This does not account for <timer_skew>. Returns the number of + * timers canceled. + */ int expire (const ACE_Time_Value &); - // Run the <functor> for all timers whose values are <= <cur_time>. - // This does not account for <timer_skew>. Returns the number of - // timers canceled. + /// Returns a pointer to this <ACE_Timer_Queue_T>'s iterator. virtual ACE_Timer_Queue_Iterator_T<TYPE, FUNCTOR, ACE_LOCK> &iter (void); - // Returns a pointer to this <ACE_Timer_Queue_T>'s iterator. + /// Removes the earliest node from the queue and returns it virtual ACE_Timer_Node_T<TYPE> *remove_first (void); - // Removes the earliest node from the queue and returns it + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. + /// Reads the earliest node from the queue and returns it. virtual ACE_Timer_Node_T<TYPE> *get_first (void); - // Reads the earliest node from the queue and returns it. private: + /// Reschedule an "interval" node virtual void reschedule (ACE_Timer_Node_T<TYPE> *); - // Reschedule an "interval" node + /// Timing Wheel. ACE_Timer_Node_T<TYPE> **wheel_; - // Timing Wheel. + /// Size of the timing wheel. size_t wheel_size_; - // Size of the timing wheel. + /// Resolution (in microsoconds) of the timing wheel. size_t resolution_; - // Resolution (in microsoconds) of the timing wheel. + /// Index of the list with the earliest time size_t earliest_pos_; - // Index of the list with the earliest time + /// Keeps track of the size of the queue long size_; - // Keeps track of the size of the queue + /// Iterator used to expire timers. WHEEL_ITERATOR *iterator_; - // Iterator used to expire timers. + /// Pointer to the freelist of <ACE_Timer_Node_T<TYPE>>. ACE_Timer_Node_T<TYPE> *freelist_; - // Pointer to the freelist of <ACE_Timer_Node_T<TYPE>>. // = Don't allow these operations for now. ACE_UNIMPLEMENTED_FUNC (ACE_Timer_Wheel_T (const ACE_Timer_Wheel_T<TYPE, FUNCTOR, ACE_LOCK> &)) diff --git a/ace/TkReactor.h b/ace/TkReactor.h index 2c0cca41f52..a7834f80661 100644 --- a/ace/TkReactor.h +++ b/ace/TkReactor.h @@ -1,17 +1,14 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// TkReactor.h -// -// = AUTHOR -// Nagarajan Surendran <naga@cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file TkReactor.h + * + * $Id$ + * + * @author Nagarajan Surendran <naga@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_TKREACTOR_H #define ACE_TKREACTOR_H @@ -25,17 +22,20 @@ #if defined (ACE_HAS_TK) #include <tk.h> +/** + * @class ACE_TkReactorID + * + * @brief This little class is necessary due to the way that Microsoft + * implements sockets to be pointers rather than indices. + */ class ACE_Export ACE_TkReactorID { - // = TITLE - // This little class is necessary due to the way that Microsoft - // implements sockets to be pointers rather than indices. public: + /// Underlying handle. ACE_HANDLE handle_; - // Underlying handle. + /// Pointer to next node in the linked list. ACE_TkReactorID *next_; - // Pointer to next node in the linked list. }; class ACE_TkReactor; @@ -47,11 +47,14 @@ public: ACE_HANDLE handle_; }; +/** + * @class ACE_TkReactor + * + * @brief An object-oriented event demultiplexor and event handler + * dispatcher that uses the Tk functions. + */ class ACE_Export ACE_TkReactor : public ACE_Select_Reactor { - // = TITLE - // An object-oriented event demultiplexor and event handler - // dispatcher that uses the Tk functions. public: // = Initialization and termination methods. ACE_TkReactor (size_t size = DEFAULT_SIZE, @@ -65,7 +68,7 @@ public: const void *arg, const ACE_Time_Value &delta_time, const ACE_Time_Value &interval); - virtual int reset_timer_interval (long timer_id, + virtual int reset_timer_interval (long timer_id, const ACE_Time_Value &interval); virtual int cancel_timer (ACE_Event_Handler *handler, int dont_call_handle_close = 1); @@ -75,51 +78,51 @@ public: protected: // = Register timers/handles with Tk. + /// Register a single <handler>. virtual int register_handler_i (ACE_HANDLE handle, ACE_Event_Handler *handler, ACE_Reactor_Mask mask); - // Register a single <handler>. + /// Register a set of <handlers>. virtual int register_handler_i (const ACE_Handle_Set &handles, ACE_Event_Handler *handler, ACE_Reactor_Mask mask); - // Register a set of <handlers>. + /// Remove the <handler> associated with this <handle>. virtual int remove_handler_i (ACE_HANDLE handle, ACE_Reactor_Mask mask); - // Remove the <handler> associated with this <handle>. + /// Remove a set of <handles>. virtual int remove_handler_i (const ACE_Handle_Set &handles, ACE_Reactor_Mask); - // Remove a set of <handles>. + /// Removes an Tk FileHandler. virtual void remove_TkFileHandler (ACE_HANDLE handle); - // Removes an Tk FileHandler. + /// Wait for events to occur. virtual int wait_for_multiple_events (ACE_Select_Reactor_Handle_Set &, ACE_Time_Value *); - // Wait for events to occur. + ///Wait for Tk events to occur. virtual int TkWaitForMultipleEvents (int, ACE_Select_Reactor_Handle_Set &, ACE_Time_Value *); - //Wait for Tk events to occur. ACE_TkReactorID *ids_; Tk_TimerToken timeout_; private: + /// This method ensures there's a Tk timeout for the first timeout in + /// the Reactor's Timer_Queue. void reset_timeout (void); - // This method ensures there's a Tk timeout for the first timeout in - // the Reactor's Timer_Queue. // = Integrate with the X callback function mechanism. static void TimerCallbackProc (ClientData cd); static void InputCallbackProc (ClientData cd,int mask); + /// Deny access since member-wise won't work... ACE_TkReactor (const ACE_TkReactor &); ACE_TkReactor &operator = (const ACE_TkReactor &); - // Deny access since member-wise won't work... }; #endif /* ACE_HAS_TK */ diff --git a/ace/Token.h b/ace/Token.h index 06e286d3a67..54835a1ef1f 100644 --- a/ace/Token.h +++ b/ace/Token.h @@ -1,19 +1,18 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Token.h -// -// = AUTHOR -// Original author -- Karl-Heinz Dorn (kdorn@erlh.siemens.de) -// Ported to ACE by Douglas C. Schmidt (schmidt@cs.wustl.edu) -// -// ============================================================================ + +//============================================================================= +/** + * @file Token.h + * + * $Id$ + * + * @author Original author + * @author Karl-Heinz Dorn (kdorn@erlh.siemens.de) + * @author Ported to ACE by + * @author Douglas C. Schmidt (schmidt@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_TOKEN_H #define ACE_TOKEN_H @@ -32,36 +31,37 @@ # define ACE_TOKEN_USES_SEMAPHORE #endif /* (ACE_WIN32 && !ACE_HAS_WINCE) || VXWORKS || ACE_PSOS */ +/** + * @class ACE_Token + * + * @brief Class that acquires, renews, and releases a synchronization + * token that is serviced in strict FIFO ordering and that also + * supports (1) recursion and (2) readers/writer semantics. + * + * This class is a more general-purpose synchronization mechanism + * than many native OS mutexes. For example, it implements + * "recursive mutex" semantics, where a thread that owns the token + * can reacquire it without deadlocking. If the same thread calls + * <acquire> multiple times, however, it must call <release> an + * equal number of times before the token is actually released. + * Threads that are blocked awaiting the token are serviced in + * strict FIFO order as other threads release the token (Solaris + * and Pthread mutexes don't strictly enforce an acquisition + * order). There are two FIFO lists within the class. Write + * acquires always have higher priority over read acquires. Which + * means, if you use both write/read operations, care must be + * taken to avoid starvation on the readers. Notice that the + * read/write acquire operations do not have the usual semantic of + * reader/writer locks. Only one reader can acquire the token at + * a time (which is different from the usual reader/writer locks + * where several readers can acquire a lock at the same time as + * long as there is no writer waiting for the lock). We choose + * the names to (1) borrow the semantic to give writers higher + * priority and (2) support a common interface for all locking + * classes in ACE. + */ class ACE_Export ACE_Token { - // = TITLE - // Class that acquires, renews, and releases a synchronization - // token that is serviced in strict FIFO ordering and that also - // supports (1) recursion and (2) readers/writer semantics. - // - // = DESCRIPTION - // This class is a more general-purpose synchronization mechanism - // than many native OS mutexes. For example, it implements - // "recursive mutex" semantics, where a thread that owns the token - // can reacquire it without deadlocking. If the same thread calls - // <acquire> multiple times, however, it must call <release> an - // equal number of times before the token is actually released. - // - // Threads that are blocked awaiting the token are serviced in - // strict FIFO order as other threads release the token (Solaris - // and Pthread mutexes don't strictly enforce an acquisition - // order). There are two FIFO lists within the class. Write - // acquires always have higher priority over read acquires. Which - // means, if you use both write/read operations, care must be - // taken to avoid starvation on the readers. Notice that the - // read/write acquire operations do not have the usual semantic of - // reader/writer locks. Only one reader can acquire the token at - // a time (which is different from the usual reader/writer locks - // where several readers can acquire a lock at the same time as - // long as there is no writer waiting for the lock). We choose - // the names to (1) borrow the semantic to give writers higher - // priority and (2) support a common interface for all locking - // classes in ACE. public: // = Initialization and termination. @@ -70,113 +70,123 @@ public: // = Synchronization operations. + /** + * Acquire the token, sleeping until it is obtained or until the + * expiration of <timeout>, which is treated as "absolute" time. If + * some other thread currently holds the token then <sleep_hook> is + * called before our thread goes to sleep. This <sleep_hook> can be + * used by the requesting thread to unblock a token-holder that is + * sleeping, e.g., by means of writing to a pipe (the ACE + * ACE_Reactor uses this functionality). Return values: 0 if + * acquires without calling <sleep_hook> 1 if <sleep_hook> is + * called. 2 if the token is signaled. -1 if failure or timeout + * occurs (if timeout occurs errno == ETIME) If <timeout> == + * <&ACE_Time_Value::zero> then acquire has polling semantics (and + * does *not* call <sleep_hook>). + */ int acquire (void (*sleep_hook)(void *), void *arg = 0, ACE_Time_Value *timeout = 0); - // Acquire the token, sleeping until it is obtained or until the - // expiration of <timeout>, which is treated as "absolute" time. If - // some other thread currently holds the token then <sleep_hook> is - // called before our thread goes to sleep. This <sleep_hook> can be - // used by the requesting thread to unblock a token-holder that is - // sleeping, e.g., by means of writing to a pipe (the ACE - // ACE_Reactor uses this functionality). Return values: 0 if - // acquires without calling <sleep_hook> 1 if <sleep_hook> is - // called. 2 if the token is signaled. -1 if failure or timeout - // occurs (if timeout occurs errno == ETIME) If <timeout> == - // <&ACE_Time_Value::zero> then acquire has polling semantics (and - // does *not* call <sleep_hook>). + /** + * This behaves just like the previous <acquire> method, except that + * it invokes the virtual function called <sleep_hook> that can be + * overridden by a subclass of ACE_Token. + */ int acquire (ACE_Time_Value *timeout = 0); - // This behaves just like the previous <acquire> method, except that - // it invokes the virtual function called <sleep_hook> that can be - // overridden by a subclass of ACE_Token. + /** + * This should be overridden by a subclass to define the appropriate + * behavior before <acquire> goes to sleep. By default, this is a + * no-op... + */ virtual void sleep_hook (void); - // This should be overridden by a subclass to define the appropriate - // behavior before <acquire> goes to sleep. By default, this is a - // no-op... + /** + * An optimized method that efficiently reacquires the token if no + * other threads are waiting. This is useful for situations where + * you don't want to degrad the quality of service if there are + * other threads waiting to get the token. If <requeue_position> == + * -1 and there are other threads waiting to obtain the token we are + * queued at the end of the list of waiters. If <requeue_position> + * > -1 then it indicates how many entries to skip over before + * inserting our thread into the list of waiters (e.g., + * <requeue_position> == 0 means "insert at front of the queue"). + * Renew has the rather odd semantics such that if there are other + * waiting threads it will give up the token even if the + * nesting_level_ > 1. I'm not sure if this is really the right + * thing to do (since it makes it possible for shared data to be + * changed unexpectedly) so use with caution... This method + * maintians the original token priority. As in <acquire>, the + * <timeout> value is an absolute time. + */ int renew (int requeue_position = 0, ACE_Time_Value *timeout = 0); - // An optimized method that efficiently reacquires the token if no - // other threads are waiting. This is useful for situations where - // you don't want to degrad the quality of service if there are - // other threads waiting to get the token. If <requeue_position> == - // -1 and there are other threads waiting to obtain the token we are - // queued at the end of the list of waiters. If <requeue_position> - // > -1 then it indicates how many entries to skip over before - // inserting our thread into the list of waiters (e.g., - // <requeue_position> == 0 means "insert at front of the queue"). - // Renew has the rather odd semantics such that if there are other - // waiting threads it will give up the token even if the - // nesting_level_ > 1. I'm not sure if this is really the right - // thing to do (since it makes it possible for shared data to be - // changed unexpectedly) so use with caution... This method - // maintians the original token priority. As in <acquire>, the - // <timeout> value is an absolute time. + /// Become interface-compliant with other lock mechanisms (implements + /// a non-blocking <acquire>). int tryacquire (void); - // Become interface-compliant with other lock mechanisms (implements - // a non-blocking <acquire>). + /// Shuts down the ACE_Token instance. int remove (void); - // Shuts down the ACE_Token instance. + /// Relinquish the token. If there are any waiters then the next one + /// in line gets it. int release (void); - // Relinquish the token. If there are any waiters then the next one - // in line gets it. + /// Behave like acquire but in a lower priority. It should probably + /// be called acquire_yield. int acquire_read (void); - // Behave like acquire but in a lower priority. It should probably - // be called acquire_yield. + /// More sophisticate version of acquire_read. int acquire_read (void (*sleep_hook)(void *), void *arg = 0, ACE_Time_Value *timeout = 0); - // More sophisticate version of acquire_read. + /// Just calls <acquire>. int acquire_write (void); - // Just calls <acquire>. + /// More sophisticate version of acquire_write. int acquire_write (void (*sleep_hook)(void *), void *arg = 0, ACE_Time_Value *timeout = 0); - // More sophisticate version of acquire_write. + /// Lower priority try_acquire. int tryacquire_read (void); - // Lower priority try_acquire. + /// Just calls <tryacquire>. int tryacquire_write (void); - // Just calls <tryacquire>. + /// Assumes the caller has acquired the token and returns 0. int tryacquire_write_upgrade (void); - // Assumes the caller has acquired the token and returns 0. // = Accessor methods. + /// Return the number of threads that are currently waiting to get + /// the token. int waiters (void); - // Return the number of threads that are currently waiting to get - // the token. + /// Return the id of the current thread that owns the token. ACE_thread_t current_owner (void); - // Return the id of the current thread that owns the token. + /** + * Force all threads waiting to acquire the token to return one by + * one. The method sets the <signal_all_thread_> to non-zero if + * there're threads waiting, and returns the number of threads + * waiting. If there's no thread waiting for the token, the call + * returns 0 and doesn't do anything. The last thread releases the + * token also reset the <singal_all_thread_> flag to 0. This means, + * any threads that try to acquire the token after the call is + * issued will also get "signaled" and the number of threads waiting + * the token is only a snapshot. + */ int signal_all_threads (void); - // Force all threads waiting to acquire the token to return one by - // one. The method sets the <signal_all_thread_> to non-zero if - // there're threads waiting, and returns the number of threads - // waiting. If there's no thread waiting for the token, the call - // returns 0 and doesn't do anything. The last thread releases the - // token also reset the <singal_all_thread_> flag to 0. This means, - // any threads that try to acquire the token after the call is - // issued will also get "signaled" and the number of threads waiting - // the token is only a snapshot. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. // = The following structure implements a ACE_FIFO of waiter threads // that are asleep waiting to obtain the token. @@ -241,42 +251,42 @@ private: // Tail of the list of waiting threads. }; + /// Implements the <acquire> and <tryacquire> methods above. int shared_acquire (void (*sleep_hook_func)(void *), void *arg, ACE_Time_Value *timeout, ACE_Token_Op_Type op_type); - // Implements the <acquire> and <tryacquire> methods above. + /// Wake next in line for ownership. void wakeup_next_waiter (void); - // Wake next in line for ownership. + /// A queue of writer threads. ACE_Token_Queue writers_; - // A queue of writer threads. + /// A queue of reader threads. ACE_Token_Queue readers_; - // A queue of reader threads. + /// ACE_Thread_Mutex used to lock internal data structures. ACE_Thread_Mutex lock_; - // ACE_Thread_Mutex used to lock internal data structures. + /// Current owner of the token. ACE_thread_t owner_; - // Current owner of the token. + /// Some thread (i.e., <owner_>) is using the token. We need this + /// extra variable to deal with POSIX pthreads madness... int in_use_; - // Some thread (i.e., <owner_>) is using the token. We need this - // extra variable to deal with POSIX pthreads madness... + /// Number of waiters. int waiters_; - // Number of waiters. + /// Current nesting level. int nesting_level_; - // Current nesting level. + /// Whether we are "signaling" all threads or not. int signal_all_threads_; - // Whether we are "signaling" all threads or not. + /// The attributes for the condition variables, optimizes lock time. ACE_Condition_Attributes attributes_; - // The attributes for the condition variables, optimizes lock time. }; #if defined (__ACE_INLINE__) diff --git a/ace/Token_Collection.h b/ace/Token_Collection.h index 247dec47cd1..c0fc0bbc531 100644 --- a/ace/Token_Collection.h +++ b/ace/Token_Collection.h @@ -1,28 +1,25 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Token_Collection.h -// -// = DESCRIPTION -// The ACE_Token class offers methods for acquiring, renewing, -// and releasing a synchronization token on a per-token basis. The -// ACE_Token_Collection offers an interface for performing -// operations on groups of tokens as a whole, or on a single token -// within the collection. -// -// The atomic group operations are not yet implemented. -// -// = AUTHOR -// Douglas C. Schmidt (schmidt@cs.wustl.edu) and -// Tim Harrison (harrison@cs.wustl.edu) -// -// ============================================================================ + +//============================================================================= +/** + * @file Token_Collection.h + * + * $Id$ + * + * The ACE_Token class offers methods for acquiring, renewing, + * and releasing a synchronization token on a per-token basis. The + * ACE_Token_Collection offers an interface for performing + * operations on groups of tokens as a whole, or on a single token + * within the collection. + * + * The atomic group operations are not yet implemented. + * + * + * @author Douglas C. Schmidt (schmidt@cs.wustl.edu) + * @author Tim Harrison (harrison@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_TOKEN_COLLECTION_H #define ACE_TOKEN_COLLECTION_H @@ -37,33 +34,37 @@ #include "ace/Local_Tokens.h" #include "ace/SString.h" +/** + * @class ACE_Token_Collection + * + * @brief Allows atomic token group operations AND + * provides a ACE_Token manager interface. + * + * There are two types of operations offered by + * ACE_Token_Collection. The first is atomic operations on + * collections of Token_Proxies. In this respect, the + * ACE_Token_Collection can be thought of as a single token + * consisting of multiple Token_Proxies. The second role of the + * ACE_Token_Collection is as a ACE_Token manager. + * ACE_Token_Collection allows individual operations on single + * members of a collection of Token_Proxies. This provides a + * single access point for operations on multiple tokens. + */ class ACE_Export ACE_Token_Collection : public ACE_Token_Proxy { - // = TITLE - // Allows atomic token group operations AND - // provides a ACE_Token manager interface. - // - // = DESCRIPTION - // There are two types of operations offered by - // ACE_Token_Collection. The first is atomic operations on - // collections of Token_Proxies. In this respect, the - // ACE_Token_Collection can be thought of as a single token - // consisting of multiple Token_Proxies. The second role of the - // ACE_Token_Collection is as a ACE_Token manager. - // ACE_Token_Collection allows individual operations on single - // members of a collection of Token_Proxies. This provides a - // single access point for operations on multiple tokens. // = BUGS // Although ACE_Token_Collection inherits from ACE_Token_Proxy, it // can not be including in a collection. This is because <clone> // returns zero for now. public: + /** + * <debug> print out verbose debugging messages. <name> will give a + * name to the collection. Collections don't really need names, but + * are sometimes useful for debugging. + */ ACE_Token_Collection (int debug = 0, const ACE_TCHAR *name = 0); - // <debug> print out verbose debugging messages. <name> will give a - // name to the collection. Collections don't really need names, but - // are sometimes useful for debugging. // Collection Management operations @@ -80,20 +81,24 @@ public: // thread using the collection will be used. Client ID's can be // changed explicity on each proxy using is_member. + /** + * removes the ACE_Token matching the given token_name from the + * collection. On success, extract returns 0. On failure + * (token_name was not in the collection,) extract returns -1. On + * success, the state of the token found is copied into proxy. + * The returned ACE_Token_Proxy* must be deleted by the user. + */ int extract (const ACE_TCHAR *token_name, ACE_Token_Proxy *&proxy); - // removes the ACE_Token matching the given token_name from the - // collection. On success, extract returns 0. On failure - // (token_name was not in the collection,) extract returns -1. On - // success, the state of the token found is copied into proxy. - // The returned ACE_Token_Proxy* must be deleted by the user. + /// returns the proxy if true. 0 otherwise. ACE_Token_Proxy *is_member (const ACE_TCHAR *token_name); - // returns the proxy if true. 0 otherwise. + /** + * Is the specified token in the collection? + * 1, yes. + * 0, no. + */ int is_member (const ACE_Token_Proxy &token); - // Is the specified token in the collection? - // 1, yes. - // 0, no. // = Collective operation semantics. @@ -108,103 +113,109 @@ public: // inserted. For each one it performs the operation (acquire, // renew, or release). + /** + * Acquire "atomically" all resources in the collection. This is + * only successfull if all tokens in the collection could be + * acquired. options contains the blocking semantics, timeout + * value, etc. Returns: 0 on success, -1 on failure with <errno> == + * problem. If and error or deadlock occurs for one of the tokens, + * all the tokens will be released and the method will return -1. + * Note that returning on detection of deadlock prevents livelock + * between competing collections. If a collection returns after + * detecting deadlock, it is the application's responsibility to not + * to blindly loop on the collection::acquire operation. In other + * words, once the collection reports deadlock, it is out of our + * hands. + */ virtual int acquire (int notify = 0, void (*sleep_hook)(void *) = 0, ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Acquire "atomically" all resources in the collection. This is - // only successfull if all tokens in the collection could be - // acquired. options contains the blocking semantics, timeout - // value, etc. Returns: 0 on success, -1 on failure with <errno> == - // problem. If and error or deadlock occurs for one of the tokens, - // all the tokens will be released and the method will return -1. - // Note that returning on detection of deadlock prevents livelock - // between competing collections. If a collection returns after - // detecting deadlock, it is the application's responsibility to not - // to blindly loop on the collection::acquire operation. In other - // words, once the collection reports deadlock, it is out of our - // hands. + /// Acquire the token corresponding to <token_name>. The other + /// parameters are passed to <token>::acquire. virtual int acquire (const ACE_TCHAR *token_name, int notify = 0, void (*sleep_hook)(void *) = 0, ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Acquire the token corresponding to <token_name>. The other - // parameters are passed to <token>::acquire. + /// Try to acquire all tokens in collection. virtual int tryacquire (void (*sleep_hook)(void *) = 0); - // Try to acquire all tokens in collection. + /// Try to acquire <token_name>. virtual int tryacquire (const ACE_TCHAR *token_name, void (*sleep_hook)(void *) = 0); - // Try to acquire <token_name>. + /** + * Renews "atomically" all resources in the collection. This is + * only successfull if all tokens in the collection could be + * renewed. options contains the blocking semantics, timeout + * value, etc. Returns: 0 on success, -1 on failure with <errno> == + * problem. + */ virtual int renew (int requeue_position = 0, ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Renews "atomically" all resources in the collection. This is - // only successfull if all tokens in the collection could be - // renewed. options contains the blocking semantics, timeout - // value, etc. Returns: 0 on success, -1 on failure with <errno> == - // problem. + /// Renew the token corresponding to <token_name>. The other + /// parameters are passed to <token>::renew. virtual int renew (const ACE_TCHAR *token_name, int requeue_position = 0, ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Renew the token corresponding to <token_name>. The other - // parameters are passed to <token>::renew. + /** + * Releases "atomically" all resources in the collection. This is + * only successfull if all tokens in the collection could be + * released. options contains the blocking semantics, timeout + * value, etc. Returns: 0 on success, -1 on failure with <errno> == + * problem. + */ virtual int release (ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Releases "atomically" all resources in the collection. This is - // only successfull if all tokens in the collection could be - // released. options contains the blocking semantics, timeout - // value, etc. Returns: 0 on success, -1 on failure with <errno> == - // problem. + /// Release the token corresponding to <token_name>. The other + /// parameters are passed to <token>::release. virtual int release (const ACE_TCHAR *token_name, ACE_Synch_Options &options = ACE_Synch_Options::defaults); - // Release the token corresponding to <token_name>. The other - // parameters are passed to <token>::release. ~ACE_Token_Collection (void); + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// Return the name of the collection. Not very functionally + /// important, but sometimes a useful debugging tool. virtual const ACE_TCHAR *name (void) const; - // Return the name of the collection. Not very functionally - // important, but sometimes a useful debugging tool. protected: typedef ACE_Token_Name TOKEN_NAME; + /// COLLECTION maintains a mapping from token names to ACE_Tokens* typedef ACE_Map_Manager<TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex> COLLECTION; - // COLLECTION maintains a mapping from token names to ACE_Tokens* + /// Allows iterations through collection_ typedef ACE_Map_Iterator<TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex> COLLECTION_ITERATOR; - // Allows iterations through collection_ + /// Allows iterations through collection_ typedef ACE_Map_Entry<TOKEN_NAME, ACE_Token_Proxy *> COLLECTION_ENTRY; - // Allows iterations through collection_ + /// COLLECTION maintains a mapping from token names to ACE_Tokens*. COLLECTION collection_; - // COLLECTION maintains a mapping from token names to ACE_Tokens*. + /// Whether to print out debug messages or not. int debug_; - // Whether to print out debug messages or not. + /// Name of the collection. ACE_TCHAR name_[ACE_MAXTOKENNAMELEN]; - // Name of the collection. // = I'm not sure what these mean, but they have to be defined since they're // pure virtual in ACE_Token_Proxy. diff --git a/ace/Token_Invariants.h b/ace/Token_Invariants.h index 3bda6f2b572..2be2d194017 100644 --- a/ace/Token_Invariants.h +++ b/ace/Token_Invariants.h @@ -1,23 +1,21 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Token_Invariants.h -// -// = AUTHOR -// Tim Harrison (harrison@cs.wustl.edu) -// -// = DESCRIPTION -// Allows applications to test that invariants are always -// satisfied. Can test mutexes and readers/writer locks. Does -// not test recursive acquisition. -// -// ============================================================================ + +//============================================================================= +/** + * @file Token_Invariants.h + * + * $Id$ + * + * @author Tim Harrison (harrison@cs.wustl.edu) + * + * Allows applications to test that invariants are always + * satisfied. Can test mutexes and readers/writer locks. Does + * not test recursive acquisition. + * + * + */ +//============================================================================= + #ifndef ACE_TOKEN_INVARIANTS_H #define ACE_TOKEN_INVARIANTS_H @@ -32,189 +30,195 @@ #include "ace/Map_Manager.h" #include "ace/Local_Tokens.h" +/** + * @class ACE_Mutex_Invariants + * + * @brief Mutex Invariants + * = INVARIANTS + * 1. Only one owner at a time. + */ class ACE_Export ACE_Mutex_Invariants { - // = TITLE - // Mutex Invariants - // - // = INVARIANTS - // 1. Only one owner at a time. public: + /// Default construction. ACE_Mutex_Invariants (void); - // Default construction. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int acquired (void); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Updates internal database. void releasing (void); - // Updates internal database. // = Map_Manager operations. + /// Copy construction. ACE_Mutex_Invariants (const ACE_Mutex_Invariants &rhs); - // Copy construction. + /// Copy. void operator= (const ACE_Mutex_Invariants &rhs); - // Copy. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. private: + /// Number of owners. This had better be 0 >= owners_ <= 1; int owners_; - // Number of owners. This had better be 0 >= owners_ <= 1; }; +/** + * @class ACE_RWLock_Invariants + * + * @brief RWLock Invariants + * + * Preserve the following invariants: + * -# Only one writer at a time. + * -# If there is an owning writer, there are no owning readers. + */ class ACE_Export ACE_RWLock_Invariants { - // = TITLE - // RWLock Invariants - // - // = INVARIANTS - // 1. Only one writer at a time. - // 2. If there is an owning writer, there are no owning readers. public: + /// Default construction. ACE_RWLock_Invariants (void); - // Default construction. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int writer_acquired (void); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int reader_acquired (void); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Updates internal database. void releasing (void); - // Updates internal database. // = Map_Manager operations. + /// Copy construction. ACE_RWLock_Invariants (const ACE_RWLock_Invariants &rhs); - // Copy construction. + /// Copy. void operator= (const ACE_RWLock_Invariants &rhs); - // Copy. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. private: + /// Number of owning writers. int writers_; - // Number of owning writers. + /// Number of owning readers. int readers_; - // Number of owning readers. }; +/** + * @class ACE_Token_Invariant_Manager + * + * @brief Token Invariants + * + * The Token Invariant Manager allows applications to test that + * invariants are always satisfied. Currently, Token_Invariants + * can test mutexes and readers/writer locks. Does not test + * recursive acquisition. + * Note that this class does not ever clean its database. Until + * destroyed, it's size will forever increase. + */ class ACE_Export ACE_Token_Invariant_Manager : public ACE_Cleanup { - // = TITLE - // Token Invariants - // - // = DESCRIPTION - // The Token Invariant Manager allows applications to test that - // invariants are always satisfied. Currently, Token_Invariants - // can test mutexes and readers/writer locks. Does not test - // recursive acquisition. - // - // Note that this class does not ever clean its database. Until - // destroyed, it's size will forever increase. public: + /// Singleton access point. static ACE_Token_Invariant_Manager *instance (void); - // Singleton access point. // = Polymorphic methods. Just pass in the proxy and the method // figures out the type of the token. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int acquired (const ACE_Token_Proxy *proxy); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Updates internal database. void releasing (const ACE_Token_Proxy *proxy); - // Updates internal database. // = Explicit methods. These to not require actual proxies in order // to test a scenario. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int mutex_acquired (const ACE_TCHAR *token_name); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Updates internal database. void mutex_releasing (const ACE_TCHAR *token_name); - // Updates internal database. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int reader_acquired (const ACE_TCHAR *token_name); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int writer_acquired (const ACE_TCHAR *token_name); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Updates internal database. void rwlock_releasing (const ACE_TCHAR *token_name); - // Updates internal database. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. // = The following two method should be in the protected part of the // class. Bugs with certain compilers preclude this. + /// Prevent non-singleton construction. ACE_Token_Invariant_Manager (void); - // Prevent non-singleton construction. + /// Destruction. virtual ~ACE_Token_Invariant_Manager (void); - // Destruction. protected: + /// Return or create. int get_mutex (const ACE_TCHAR *token_name, ACE_Mutex_Invariants *&inv); - // Return or create. + /// Return or create. int get_rwlock (const ACE_TCHAR *token_name, ACE_RWLock_Invariants *&inv); - // Return or create. + /// ACE_Mutex_Token used to lock internal data structures. ACE_TOKEN_CONST::MUTEX lock_; - // ACE_Mutex_Token used to lock internal data structures. + /// This may be changed to a template type. typedef ACE_Token_Name TOKEN_NAME; - // This may be changed to a template type. + /// COLLECTION maintains a mapping from token names to mutexes. typedef ACE_Map_Manager<TOKEN_NAME, ACE_Mutex_Invariants *, ACE_Null_Mutex> MUTEX_COLLECTION; - // COLLECTION maintains a mapping from token names to mutexes. + /// Allows iterations through collection. typedef ACE_Map_Iterator<TOKEN_NAME, ACE_Mutex_Invariants *, ACE_Null_Mutex> MUTEX_COLLECTION_ITERATOR; - // Allows iterations through collection. + /// Allows iterations through collection. typedef ACE_Map_Entry<TOKEN_NAME, ACE_Mutex_Invariants *> MUTEX_COLLECTION_ENTRY; - // Allows iterations through collection. + /// MUTEX_COLLECTION maintains a mapping from token names to mutexes. MUTEX_COLLECTION mutex_collection_; - // MUTEX_COLLECTION maintains a mapping from token names to mutexes. + /// COLLECTION maintains a mapping from token names to mutexes. typedef ACE_Map_Manager<TOKEN_NAME, ACE_RWLock_Invariants *, ACE_Null_Mutex> RWLOCK_COLLECTION; - // COLLECTION maintains a mapping from token names to mutexes. + /// Allows iterations through collection. typedef ACE_Map_Iterator<TOKEN_NAME, ACE_RWLock_Invariants *, ACE_Null_Mutex> RWLOCK_COLLECTION_ITERATOR; - // Allows iterations through collection. + /// Allows iterations through collection. typedef ACE_Map_Entry<TOKEN_NAME, ACE_RWLock_Invariants *> RWLOCK_COLLECTION_ENTRY; - // Allows iterations through collection. + /// MUTEX_COLLECTION maintains a mapping from token names to mutexes. RWLOCK_COLLECTION rwlock_collection_; - // MUTEX_COLLECTION maintains a mapping from token names to mutexes. + /// Singleton pointer. static ACE_Token_Invariant_Manager *instance_; - // Singleton pointer. }; #include "ace/post.h" diff --git a/ace/Token_Manager.h b/ace/Token_Manager.h index 79e37935d95..56fb63db6a0 100644 --- a/ace/Token_Manager.h +++ b/ace/Token_Manager.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Token_Manager.h -// -// = AUTHOR -// Tim Harrison (harrison@cs.wustl.edu) -// -// ============================================================================ + +//============================================================================= +/** + * @file Token_Manager.h + * + * $Id$ + * + * @author Tim Harrison (harrison@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_TOKEN_MANAGER_H #define ACE_TOKEN_MANAGER_H @@ -30,17 +27,19 @@ class ACE_Local_Mutex; class ACE_Mutex_Token; +/** + * @class ACE_Token_Manager + * + * @brief Manages all tokens in a process space. + * + * Factory: Proxies use the token manager to obtain token + * references. This allows multiple proxies to reference the same + * logical token. + * Deadlock detection: Tokens use the manager to check for + * deadlock situations during acquires. + */ class ACE_Export ACE_Token_Manager : public ACE_Cleanup { - // = TITLE - // Manages all tokens in a process space. - // - // = DESCRIPTION - // Factory: Proxies use the token manager to obtain token - // references. This allows multiple proxies to reference the same - // logical token. - // Deadlock detection: Tokens use the manager to check for - // deadlock situations during acquires. // To add a new type of token (e.g. semaphore), do the following // steps: 1. Create a new derivation of ACE_Token. This class @@ -55,68 +54,74 @@ public: static ACE_Token_Manager *instance (void); void instance (ACE_Token_Manager *); + /** + * The Token manager uses ACE_Token_Proxy::token_id_ to look for + * an existing token. If none is found, the Token Manager calls + * ACE_Token_Proxy::create_token to create a new one. When + * finished, sets ACE_Token_Proxy::token_. <token_name> uniquely + * id's the token name. + */ void get_token (ACE_Token_Proxy *, const ACE_TCHAR *token_name); - // The Token manager uses ACE_Token_Proxy::token_id_ to look for - // an existing token. If none is found, the Token Manager calls - // ACE_Token_Proxy::create_token to create a new one. When - // finished, sets ACE_Token_Proxy::token_. <token_name> uniquely - // id's the token name. + /** + * returns 1 if the acquire will _not_ cause deadlock. + * returns 0 if the acquire _will_ cause deadlock. + * this method ignores recursive acquisition. That is, it will not + * report deadlock if the client holding the token requests the + * token again. Thus, it assumes recursive mutexes. + */ int check_deadlock (ACE_Token_Proxy *proxy); int check_deadlock (ACE_Tokens *token, ACE_Token_Proxy *proxy); - // returns 1 if the acquire will _not_ cause deadlock. - // returns 0 if the acquire _will_ cause deadlock. - // this method ignores recursive acquisition. That is, it will not - // report deadlock if the client holding the token requests the - // token again. Thus, it assumes recursive mutexes. + /// notify the token manager that a token has been released. If as a + /// result, there is no owner of the token, the token is deleted. void release_token (ACE_Tokens *&token); - // notify the token manager that a token has been released. If as a - // result, there is no owner of the token, the token is deleted. + /** + * This is to allow Tokens to perform atomic transactions. The + * typical usage is to acquire this mutex, check for a safe_acquire, + * perform some queueing (if need be) and then release the lock. + * This is necessary since safe_acquire is implemented in terms of + * the Token queues. + */ ACE_TOKEN_CONST::MUTEX &mutex (void); - // This is to allow Tokens to perform atomic transactions. The - // typical usage is to acquire this mutex, check for a safe_acquire, - // perform some queueing (if need be) and then release the lock. - // This is necessary since safe_acquire is implemented in terms of - // the Token queues. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// Turn debug mode on/off. void debug (int d); - // Turn debug mode on/off. private: + /// Whether to print debug messages or not. int debug_; - // Whether to print debug messages or not. + /// pointer to singleton token manager. static ACE_Token_Manager *token_manager_; - // pointer to singleton token manager. + /// return the token that the given client_id is waiting for, if any ACE_Tokens *token_waiting_for (const ACE_TCHAR *client_id); - // return the token that the given client_id is waiting for, if any + /// ACE_Mutex_Token used to lock internal data structures. ACE_TOKEN_CONST::MUTEX lock_; - // ACE_Mutex_Token used to lock internal data structures. + /// This may be changed to a template type. typedef ACE_Token_Name TOKEN_NAME; - // This may be changed to a template type. + /// COLLECTION maintains a mapping from token names to ACE_Tokens* typedef ACE_Map_Manager<TOKEN_NAME, ACE_Tokens *, ACE_Null_Mutex> COLLECTION; - // COLLECTION maintains a mapping from token names to ACE_Tokens* + /// Allows iterations through collection_ typedef ACE_Map_Iterator<TOKEN_NAME, ACE_Tokens *, ACE_Null_Mutex> COLLECTION_ITERATOR; - // Allows iterations through collection_ + /// Allows iterations through collection_ typedef ACE_Map_Entry<TOKEN_NAME, ACE_Tokens *> COLLECTION_ENTRY; - // Allows iterations through collection_ + /// COLLECTION maintains a mapping from token names to ACE_Tokens*. COLLECTION collection_; - // COLLECTION maintains a mapping from token names to ACE_Tokens*. }; #if defined (__ACE_INLINE__) diff --git a/ace/Token_Request_Reply.h b/ace/Token_Request_Reply.h index 3391df69f53..f1f10b93ba9 100644 --- a/ace/Token_Request_Reply.h +++ b/ace/Token_Request_Reply.h @@ -1,23 +1,20 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ACE -// -// = FILENAME -// Token_Request_Reply.h -// -// = DESCRIPTION -// Define the format used to exchange messages between the -// ACE_Token Server and its clients. -// -// = AUTHOR -// Douglas C. Schmidt (schmidt@cs.wustl.edu) -// Tim Harrison (harrison@cs.wustl.edu) -// -// ============================================================================ + +//============================================================================= +/** + * @file Token_Request_Reply.h + * + * $Id$ + * + * Define the format used to exchange messages between the + * ACE_Token Server and its clients. + * + * + * @author Douglas C. Schmidt (schmidt@cs.wustl.edu) + * @author Tim Harrison (harrison@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_TOKEN_REQUEST_REPLY_H #define ACE_TOKEN_REQUEST_REPLY_H @@ -35,40 +32,49 @@ // the Transfer structure in ACE_Token_Request #define ACE_TOKEN_REQUEST_HEADER_SIZE 40 +/** + * @class ACE_Token_Request + * + * @brief Message format for delivering requests to the ACE_Token Server. + * + * This class is implemented to minimize data copying. + * In particular, all marshaling is done in situ... + */ class ACE_Export ACE_Token_Request { - // = TITLE - // Message format for delivering requests to the ACE_Token Server. - // - // = DESCRIPTION - // This class is implemented to minimize data copying. - // In particular, all marshaling is done in situ... public: + /// Operation types. enum OPERATION { - // Operation types. - ACQUIRE, // Acquire the token. - RELEASE, // Release the token. - RENEW, // Renew the token. - REMOVE, // Remove the token. + /// Acquire the token. + ACQUIRE, + /// Release the token. + RELEASE, + /// Renew the token. + RENEW, + /// Remove the token. + REMOVE, + // Try to acquire the token. TRY_ACQUIRE }; + /// Default constructor. ACE_Token_Request (void); - // Default constructor. + /** + * token_type - MUTEX, RWLOCK + * proxy_type - MUTEX, RLOCK, WLOCK (acquires mean different things) + * operation - method + * token_name + * client_id + * options - we check USE_TIMEOUT and use the arg. + */ ACE_Token_Request (int token_type, int proxy_type, ACE_UINT32 operation, const ACE_TCHAR token_name[], const ACE_TCHAR client_id[], const ACE_Synch_Options &options); - // token_type - MUTEX, RWLOCK - // proxy_type - MUTEX, RLOCK, WLOCK (acquires mean different things) - // operation - method - // token_name - // client_id - // options - we check USE_TIMEOUT and use the arg. // = Set/get the length of the encoded/decoded message. ACE_UINT32 length (void) const; @@ -106,15 +112,15 @@ public: ACE_TCHAR *client_id (void) const; void token_name (const ACE_TCHAR *token_name, const ACE_TCHAR *client_id); + /// Encode the message before transmission. int encode (void *&); - // Encode the message before transmission. + /// Decode message after reception. This must be called to set the + /// internal options. int decode (void); - // Decode message after reception. This must be called to set the - // internal options. + /// Print out the values of the message for debugging purposes. void dump (void) const; - // Print out the values of the message for debugging purposes. private: // = The 5 fields in the <Transfer> struct are transmitted to the server. @@ -162,27 +168,29 @@ private: // a ':', then the <clientId> including a 0 terminator } transfer_; + /// Pointer to the beginning of the token name in this->data_. ACE_TCHAR *token_name_; - // Pointer to the beginning of the token name in this->data_. + /// Pointer to the beginning of the client id in this->data_; ACE_TCHAR *client_id_; - // Pointer to the beginning of the client id in this->data_; + /// Holds arg, sec, usec, etc. ACE_Synch_Options options_; - // Holds arg, sec, usec, etc. }; +/** + * @class ACE_Token_Reply + * + * @brief Message format for delivering replies from the ACE_Token Server. + * + * This class is implemented to minimize data copying. + * In particular, all marshaling is done in situ... + */ class ACE_Export ACE_Token_Reply { - // = TITLE - // Message format for delivering replies from the ACE_Token Server. - // - // = DESCRIPTION - // This class is implemented to minimize data copying. - // In particular, all marshaling is done in situ... public: + /// Default constructor. ACE_Token_Reply (void); - // Default constructor. // = Set/get the length of the encoded/decoded message. ACE_UINT32 length (void) const; @@ -196,14 +204,14 @@ public: ACE_UINT32 arg (void) const; void arg (ACE_UINT32); + /// Encode the message before transfer. int encode (void *&); - // Encode the message before transfer. + /// Decode a message after reception. int decode (void); - // Decode a message after reception. + /// Print out the values of the message for debugging purposes. void dump (void) const; - // Print out the values of the message for debugging purposes. private: // = The 2 fields in the <Transfer> struct are transmitted to the server. diff --git a/ace/Trace.h b/ace/Trace.h index b75fed44148..fe46767ff53 100644 --- a/ace/Trace.h +++ b/ace/Trace.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Trace.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Trace.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_TRACE_H @@ -21,60 +18,62 @@ #include "ace/OS.h" +/** + * @class ACE_Trace + * + * @brief A C++ trace facility that keeps track of which methods are + * entered and exited. + * + * This class uses C++ constructors and destructors to automate + * the ACE_Trace nesting. In addition, thread-specific storage + * is used to enable multiple threads to work correctly. + */ class ACE_Export ACE_Trace { - // = TITLE - // A C++ trace facility that keeps track of which methods are - // entered and exited. - // - // = DESCRIPTION - // This class uses C++ constructors and destructors to automate - // the ACE_Trace nesting. In addition, thread-specific storage - // is used to enable multiple threads to work correctly. public: // = Initialization and termination methods. + /// Perform the first part of the trace, which prints out the string + /// N, the LINE, and the ACE_FILE as the function is entered. ACE_Trace (const ACE_TCHAR *n, int line = 0, const ACE_TCHAR *file = ACE_LIB_TEXT ("")); - // Perform the first part of the trace, which prints out the string - // N, the LINE, and the ACE_FILE as the function is entered. + /// Perform the second part of the trace, which prints out the NAME + /// as the function is exited. ~ACE_Trace (void); - // Perform the second part of the trace, which prints out the NAME - // as the function is exited. // = Control the tracing level. + /// Determine if tracing is enabled (return == 1) or not (== 0) static int is_tracing(void); - // Determine if tracing is enabled (return == 1) or not (== 0) + /// Enable the tracing facility. static void start_tracing (void); - // Enable the tracing facility. + /// Disable the tracing facility. static void stop_tracing (void); - // Disable the tracing facility. + /// Change the nesting indentation level. static void set_nesting_indent (int indent); - // Change the nesting indentation level. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. private: // Keeps track of how deeply the call stack is nested (this is // maintained in thread-specific storage to ensure correctness in // multiple threads of control. + /// Name of the method we are in. const ACE_TCHAR *name_; - // Name of the method we are in. + /// Keeps track of how far to indent per trace call. static int nesting_indent_; - // Keeps track of how far to indent per trace call. + /// Is tracing enabled? static int enable_tracing_; - // Is tracing enabled? - // Default values. + /// Default values. enum { DEFAULT_INDENT = 3, diff --git a/ace/Typed_SV_Message.h b/ace/Typed_SV_Message.h index 01e72802ee2..36c5137b80e 100644 --- a/ace/Typed_SV_Message.h +++ b/ace/Typed_SV_Message.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Typed_SV_Message.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + + +//============================================================================= +/** + * @file Typed_SV_Message.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_TYPED_SV_MESSAGE_H #define ACE_TYPED_SV_MESSAGE_H @@ -25,12 +22,15 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Typed_SV_Message + * + * @brief Defines the header file for the C++ wrapper for System V + * message queues. + */ template <class T> class ACE_Typed_SV_Message { - // = TITLE - // Defines the header file for the C++ wrapper for System V - // message queues. public: // = Initialization and termination methods. ACE_Typed_SV_Message (long type = 0, @@ -58,24 +58,24 @@ public: T &data (void); void data (const T &data); + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Type of message. long type_; - // Type of message. + /// Length of this message. int length_; - // Length of this message. + /// Maximum length of any message. int max_; - // Maximum length of any message. + /// Data stored in a message. T data_; - // Data stored in a message. }; #if defined (__ACE_INLINE__) diff --git a/ace/Typed_SV_Message_Queue.h b/ace/Typed_SV_Message_Queue.h index ec6d97909c2..46d952f40ce 100644 --- a/ace/Typed_SV_Message_Queue.h +++ b/ace/Typed_SV_Message_Queue.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Typed_SV_Message_Queue.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + + +//============================================================================= +/** + * @file Typed_SV_Message_Queue.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_TYPED_MESSAGE_QUEUE_H #define ACE_TYPED_MESSAGE_QUEUE_H @@ -27,11 +24,14 @@ #include "ace/Typed_SV_Message.h" +/** + * @class ACE_Typed_SV_Message_Queue + * + * @brief Defines the header file for the C++ wrapper for message queues. + */ template <class T> class ACE_Typed_SV_Message_Queue { - // = TITLE - // Defines the header file for the C++ wrapper for message queues. public: enum { @@ -56,17 +56,17 @@ public: int send (const ACE_Typed_SV_Message<T> &mb, int mflags = 0); int recv (ACE_Typed_SV_Message<T> &mb, int mflags = 0); + /// Return the id of the underlying <ACE_SV_Message_Queue>. int get_id (void) const; - // Return the id of the underlying <ACE_SV_Message_Queue>. + /// Control the underlying message queue. int control (int option, void *arg = 0); - // Control the underlying message queue. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: ACE_SV_Message_Queue message_queue_; diff --git a/ace/UNIX_Addr.h b/ace/UNIX_Addr.h index 3c4d9985761..fc9be3bdff6 100644 --- a/ace/UNIX_Addr.h +++ b/ace/UNIX_Addr.h @@ -1,18 +1,15 @@ // -*- C++ -*- -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// UNIX_Addr.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file UNIX_Addr.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_UNIX_ADDR_H #define ACE_UNIX_ADDR_H @@ -28,66 +25,69 @@ #if !defined (ACE_LACKS_UNIX_DOMAIN_SOCKETS) +/** + * @class ACE_UNIX_Addr + * + * @brief Defines the ``UNIX domain address family'' address format. + */ class ACE_Export ACE_UNIX_Addr : public ACE_Addr { - // = TITLE - // Defines the ``UNIX domain address family'' address format. public: // = Initialization methods. + /// Default constructor. ACE_UNIX_Addr (void); - // Default constructor. + /// Copy constructor. ACE_UNIX_Addr (const ACE_UNIX_Addr &sa); - // Copy constructor. + /// Creates an ACE_UNIX_Addr from a string. ACE_UNIX_Addr (const char rendezvous_point[]); - // Creates an ACE_UNIX_Addr from a string. + /// Creates an ACE_INET_Addr from a sockaddr_un structure. ACE_UNIX_Addr (const sockaddr_un *, int len); - // Creates an ACE_INET_Addr from a sockaddr_un structure. + /// Creates an ACE_UNIX_Addr from another <ACE_UNIX_Addr>. int set (const ACE_UNIX_Addr &sa); - // Creates an ACE_UNIX_Addr from another <ACE_UNIX_Addr>. + /// Creates an ACE_UNIX_Addr from a string. int set (const char rendezvous_point[]); - // Creates an ACE_UNIX_Addr from a string. + /// Creates an ACE_UNIX_Addr from a sockaddr_un structure. int set (const sockaddr_un *, int len); - // Creates an ACE_UNIX_Addr from a sockaddr_un structure. + /// Return a pointer to the underlying network address. virtual void *get_addr (void) const; - // Return a pointer to the underlying network address. + /// Set a pointer to the underlying network address. virtual void set_addr (void *addr, int len); - // Set a pointer to the underlying network address. + /// Transform the current address into string format. virtual int addr_to_string (char addr[], size_t) const; - // Transform the current address into string format. + /// Transform the string into the current addressing format. virtual int string_to_addr (const char addr[]); - // Transform the string into the current addressing format. + /// Compare two addresses for equality. int operator == (const ACE_UNIX_Addr &SAP) const; - // Compare two addresses for equality. + /// Compare two addresses for inequality. int operator != (const ACE_UNIX_Addr &SAP) const; - // Compare two addresses for inequality. + /// Return the path name of the underlying rendezvous point. const char *get_path_name (void) const; - // Return the path name of the underlying rendezvous point. + /// Computes and returns hash value. virtual u_long hash (void) const; - // Computes and returns hash value. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Underlying socket address. sockaddr_un unix_addr_; - // Underlying socket address. }; #if defined (__ACE_INLINE__) diff --git a/ace/UPIPE_Acceptor.h b/ace/UPIPE_Acceptor.h index fcad01e71d3..d19151370fc 100644 --- a/ace/UPIPE_Acceptor.h +++ b/ace/UPIPE_Acceptor.h @@ -1,18 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// UPIPE_Acceptor.h -// -// = AUTHOR -// Gerhard Lenzer and Douglas C. Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file UPIPE_Acceptor.h + * + * $Id$ + * + * @author Gerhard Lenzer + * @author Douglas C. Schmidt + */ +//============================================================================= + #ifndef ACE_UPIPE_ACCEPTOR_H #define ACE_UPIPE_ACCEPTOR_H @@ -30,56 +28,61 @@ #if defined (ACE_HAS_THREADS) +/** + * @class ACE_UPIPE_Acceptor + * + * @brief Defines the format and interface for the listener side of the + * ACE_UPIPE_Stream. + */ class ACE_Export ACE_UPIPE_Acceptor : public ACE_SPIPE_Acceptor { - // = TITLE - // Defines the format and interface for the listener side of the - // ACE_UPIPE_Stream. public: // = Initialization and termination. + /// Default constructor. ACE_UPIPE_Acceptor (void); - // Default constructor. + /// Initialize passive endpoint. ACE_UPIPE_Acceptor (const ACE_UPIPE_Addr &local_sap, int reuse_addr = 0); - // Initialize passive endpoint. + /// Initialize passive endpoint. int open (const ACE_UPIPE_Addr &local_sap, int reuse_addr = 0); - // Initialize passive endpoint. + /// Close down and release resources. ~ACE_UPIPE_Acceptor (void); - // Close down and release resources. + /// Close down and release resources. int close (void); - // Close down and release resources. + /// Close down and release resources and remove the underlying SPIPE + /// rendezvous point. int remove (void); - // Close down and release resources and remove the underlying SPIPE - // rendezvous point. // = Passive connection acceptance method. + /** + * Accept a new data transfer connection. A <timeout> of 0 means + * block forever, a <timeout> of {0, 0} means poll. <restart> == 1 + * means "restart if interrupted." + */ int accept (ACE_UPIPE_Stream &server_stream, ACE_UPIPE_Addr *remote_addr = 0, ACE_Time_Value *timeout = 0, int restart = 1, int reset_new_handle = 0); - // Accept a new data transfer connection. A <timeout> of 0 means - // block forever, a <timeout> of {0, 0} means poll. <restart> == 1 - // means "restart if interrupted." + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Manage threads. ACE_Thread_Manager tm; - // Manage threads. + /// To confirm connection establishment. ACE_Message_Block mb_; - // To confirm connection establishment. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/UPIPE_Addr.h b/ace/UPIPE_Addr.h index d0b37436555..1a46f564403 100644 --- a/ace/UPIPE_Addr.h +++ b/ace/UPIPE_Addr.h @@ -1,19 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// UPIPE_Addr.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + + +//============================================================================= +/** + * @file UPIPE_Addr.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_UPIPE_ADDR_H #define ACE_UPIPE_ADDR_H @@ -30,14 +27,16 @@ typedef ACE_SPIPE_Addr ACE_UPIPE_Addr; #if 0 // We need this "class" to make the class2man documentation utility // happy. +/** + * @class ACE_UPIPE_Addr + * + * @brief Defines the ACE "user pipe" address family address format. + * + * This class has an identical interface to the <ACE_SPIPE_Addr> + * class. In fact, it's simply a typedef! + */ class ACE_Export ACE_UPIPE_Addr { - // = TITLE - // Defines the ACE "user pipe" address family address format. - // - // = DESCRIPTION - // This class has an identical interface to the <ACE_SPIPE_Addr> - // class. In fact, it's simply a typedef! public: // = Same interface as <ACE_SPIPE_Addr>. }; diff --git a/ace/UPIPE_Connector.h b/ace/UPIPE_Connector.h index b4132f5d6d8..8d510ab4489 100644 --- a/ace/UPIPE_Connector.h +++ b/ace/UPIPE_Connector.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// UPIPE_Connector.h -// -// = AUTHOR -// Gerhard Lenzer and Douglas C. Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file UPIPE_Connector.h + * + * $Id$ + * + * @author Gerhard Lenzer and Douglas C. Schmidt + */ +//============================================================================= + #ifndef ACE_UPIPE_CONNECTOR_H #define ACE_UPIPE_CONNECTOR_H @@ -29,16 +26,36 @@ #if defined (ACE_HAS_THREADS) +/** + * @class ACE_UPIPE_Connector + * + * @brief Defines an active connection factory for the + * <ACE_UPIPE_STREAM> wrappers. + */ class ACE_Export ACE_UPIPE_Connector { - // = TITLE - // Defines an active connection factory for the - // <ACE_UPIPE_STREAM> wrappers. public: // = Initialization methods. + /// Default constructor. ACE_UPIPE_Connector (void); - // Default constructor. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + * The <flags> and <perms> arguments are passed down to the <open> + * method. + */ ACE_UPIPE_Connector (ACE_UPIPE_Stream &new_stream, const ACE_UPIPE_Addr &addr, ACE_Time_Value *timeout = 0, @@ -46,22 +63,24 @@ public: int reuse_addr = 0, int flags = O_RDWR, int perms = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. - // The <flags> and <perms> arguments are passed down to the <open> - // method. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + * The <flags> and <perms> arguments are passed down to the <open> + * method. + */ int connect (ACE_UPIPE_Stream &new_stream, const ACE_UPIPE_Addr &addr, ACE_Time_Value *timeout = 0, @@ -69,34 +88,19 @@ public: int reuse_addr = 0, int flags = O_RDWR, int perms = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. - // The <flags> and <perms> arguments are passed down to the <open> - // method. + /// Resets any event associations on this handle int reset_new_handle (ACE_HANDLE handle); - // Resets any event associations on this handle // = Meta-type info typedef ACE_UPIPE_Addr PEER_ADDR; typedef ACE_UPIPE_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if !defined (ACE_LACKS_INLINE_FUNCTIONS) diff --git a/ace/UPIPE_Stream.h b/ace/UPIPE_Stream.h index ce7ba6e0e00..8fd79a1c269 100644 --- a/ace/UPIPE_Stream.h +++ b/ace/UPIPE_Stream.h @@ -1,18 +1,16 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// UPIPE_Stream.h -// -// = AUTHOR -// Gerhard Lenzer and Douglas C. Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file UPIPE_Stream.h + * + * $Id$ + * + * @author Gerhard Lenzer + * @author Douglas C. Schmidt + */ +//============================================================================= + #ifndef ACE_UPIPE_STREAM_H #define ACE_UPIPE_STREAM_H @@ -34,10 +32,13 @@ // Use a typedef to make life easier later on. typedef ACE_Stream<ACE_SYNCH> MT_Stream; +/** + * @class ACE_UPIPE_Stream + * + * @brief Defines the method that transfer data on a UPIPE. + */ class ACE_Export ACE_UPIPE_Stream : public ACE_SPIPE { - // = TITLE - // Defines the method that transfer data on a UPIPE. public: friend class ACE_UPIPE_Acceptor; friend class ACE_UPIPE_Connector; @@ -48,82 +49,82 @@ public: virtual ~ACE_UPIPE_Stream (void); + /// Shut down the UPIPE and release resources. int close (void); - // Shut down the UPIPE and release resources. + /// Return the underlying I/O handle. ACE_HANDLE get_handle (void) const; - // Return the underlying I/O handle. // = Send/recv ACE Message_Blocks. + /// Send a message through the message queue. Returns -1 on error, + /// else 0. int send (ACE_Message_Block *mb_p, ACE_Time_Value *timeout = 0); - // Send a message through the message queue. Returns -1 on error, - // else 0. + /// Recv a message from the message queue. Returns -1 on error, else + /// 0. int recv (ACE_Message_Block *&mb_p, ACE_Time_Value *timeout = 0); - // Recv a message from the message queue. Returns -1 on error, else - // 0. // = Send/recv char buffers. + /// Send a buffer of <n> bytes through the message queue. Returns -1 + /// on error, else number of bytes sent. int send (const char *buffer, size_t n, ACE_Time_Value *timeout = 0); - // Send a buffer of <n> bytes through the message queue. Returns -1 - // on error, else number of bytes sent. + /// Recv a buffer of upto <n> bytes from the message queue. Returns + /// -1 on error, else number of bytes read. int recv (char *buffer, size_t n, ACE_Time_Value *timeout = 0); - // Recv a buffer of upto <n> bytes from the message queue. Returns - // -1 on error, else number of bytes read. + /// Send a buffer of exactly <n> bytes to the message queue. Returns + /// -1 on error, else number of bytes written (which should == n). int send_n (const char *buffer, size_t n, ACE_Time_Value *timeout = 0); - // Send a buffer of exactly <n> bytes to the message queue. Returns - // -1 on error, else number of bytes written (which should == n). + /// Recv a buffer of exactly <n> bytes from the message queue. + /// Returns -1 on error, else the number of bytes read. int recv_n (char *buffer, size_t n, ACE_Time_Value *timeout = 0); - // Recv a buffer of exactly <n> bytes from the message queue. - // Returns -1 on error, else the number of bytes read. + /// Perform control operations on the UPIPE_Stream. int control (int cmd, void *val) const; - // Perform control operations on the UPIPE_Stream. + /// Return the remote address we are connected to. int get_remote_addr (ACE_UPIPE_Addr &remote_sap) const; - // Return the remote address we are connected to. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// To hold the last ACE_Message_Block read out of the stream. Thus + /// allowing subsequent reads from one ACE_Message_Block ACE_Message_Block *mb_last_; - // To hold the last ACE_Message_Block read out of the stream. Thus - // allowing subsequent reads from one ACE_Message_Block + /// Holds the number of bytes that are still available in mb_last_. size_t remaining_; - // Holds the number of bytes that are still available in mb_last_. + /// Address of who we are connected to. ACE_UPIPE_Addr remote_addr_; - // Address of who we are connected to. + /// Stream component used by the <UPIPE_Acceptor> and + /// <UPIPE_Connector> to link together two UPIPE_Streams. MT_Stream stream_; - // Stream component used by the <UPIPE_Acceptor> and - // <UPIPE_Connector> to link together two UPIPE_Streams. + /// Keep track of whether the sender and receiver have both shut + /// down. int reference_count_; - // Keep track of whether the sender and receiver have both shut - // down. #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) + /// Ensure that we are thread-safe. ACE_Thread_Mutex lock_; - // Ensure that we are thread-safe. #endif /* ACE_MT_SAFE */ }; diff --git a/ace/WFMO_Reactor.h b/ace/WFMO_Reactor.h index 5980711f42d..dc41242181e 100644 --- a/ace/WFMO_Reactor.h +++ b/ace/WFMO_Reactor.h @@ -1,18 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// WFMO_Reactor.h -// -// = AUTHOR -// Irfan Pyarali, Tim Harrison, and Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file WFMO_Reactor.h + * + * $Id$ + * + * @author Irfan Pyarali + * @author Tim Harrison + * @author and Doug Schmidt + */ +//============================================================================= + #ifndef ACE_WFMO_REACTOR_H #define ACE_WFMO_REACTOR_H @@ -75,75 +74,85 @@ int WSAEnumNetworkEvents (SOCKET s, class ACE_WFMO_Reactor; class ACE_Handle_Set; +/** + * @class ACE_Wakeup_All_Threads_Handler + * + * @brief This is a helper class whose sole purpose is to handle events + * on <ACE_WFMO_Reactor->wakeup_all_threads_> + */ class ACE_Export ACE_Wakeup_All_Threads_Handler : public ACE_Event_Handler { - // = TITLE - // - // This is a helper class whose sole purpose is to handle events - // on <ACE_WFMO_Reactor->wakeup_all_threads_> - // public: + /// Called when the <ACE_WFMO_Reactor->wakeup_all_threads_> virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0); - // Called when the <ACE_WFMO_Reactor->wakeup_all_threads_> }; +/** + * @class ACE_WFMO_Reactor_Handler_Repository + * + * @brief Used to map <ACE_HANDLE>s onto the appropriate + * <ACE_Event_Handler> * and other information. + */ class ACE_Export ACE_WFMO_Reactor_Handler_Repository { - // = TITLE - // - // Used to map <ACE_HANDLE>s onto the appropriate - // <ACE_Event_Handler> * and other information. - // public: friend class ACE_WFMO_Reactor; + /** + * @class Common_Info + * + * @brief This struct contains the necessary information for every + * <Event_Handler> entry. The reason the event is not in this + * structure is because we need to pass an event array into + * WaitForMultipleObjects and therefore keeping the events + * seperate makes sense. + */ class Common_Info { - // = TITLE - // - // This struct contains the necessary information for every - // <Event_Handler> entry. The reason the event is not in this - // structure is because we need to pass an event array into - // WaitForMultipleObjects and therefore keeping the events - // seperate makes sense. - // public: + /// This indicates whether this entry is for I/O or for a regular + /// event int io_entry_; - // This indicates whether this entry is for I/O or for a regular - // event + /// The assosiated <Event_Handler> ACE_Event_Handler *event_handler_; - // The assosiated <Event_Handler> + /// The I/O handle related to the <Event_Handler>. This entry is + /// only valid if the <io_entry_> flag is true. ACE_HANDLE io_handle_; - // The I/O handle related to the <Event_Handler>. This entry is - // only valid if the <io_entry_> flag is true. + /** + * This is the set of events that the <Event_Handler> is + * interested in This entry is only valid if the <io_entry_> flag + * is true. + */ long network_events_; - // This is the set of events that the <Event_Handler> is - // interested in This entry is only valid if the <io_entry_> flag - // is true. + /** + * This flag indicates that <WFMO_Reactor> created the event on + * behalf of the user. Therefore we need to clean this up when the + * <Event_Handler> removes itself from <WFMO_Reactor>. This entry + * is only valid if the <io_entry_> flag is true. + */ int delete_event_; - // This flag indicates that <WFMO_Reactor> created the event on - // behalf of the user. Therefore we need to clean this up when the - // <Event_Handler> removes itself from <WFMO_Reactor>. This entry - // is only valid if the <io_entry_> flag is true. + /// This is set when the entry needed to be deleted. int delete_entry_; - // This is set when the entry needed to be deleted. + /** + * These are the masks related to <handle_close> for the + * <Event_Handler>. This is only valid when <delete_entry_> is + * set. + */ ACE_Reactor_Mask close_masks_; - // These are the masks related to <handle_close> for the - // <Event_Handler>. This is only valid when <delete_entry_> is - // set. + /// Constructor used for initializing the structure Common_Info (void); - // Constructor used for initializing the structure + /// Reset the state of the structure void reset (void); - // Reset the state of the structure + /// Set the structure to these new values void set (int io_entry, ACE_Event_Handler *event_handler, ACE_HANDLE io_handle, @@ -151,32 +160,33 @@ public: int delete_event, int delete_entry, ACE_Reactor_Mask close_masks); - // Set the structure to these new values + /// Set the structure to these new values void set (Common_Info &common_info); - // Set the structure to these new values + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. }; + /** + * @class Current_Info + * + * @brief This structure inherits from the common structure to add + * information for current entries. + */ class Current_Info : public Common_Info { - // = TITLE - // - // This structure inherits from the common structure to add - // information for current entries. - // public: + /// This is set when the entry needed to be suspended. int suspend_entry_; - // This is set when the entry needed to be suspended. + /// Default constructor Current_Info (void); - // Default constructor + /// Reset the state of the structure void reset (void); - // Reset the state of the structure + /// Set the structure to these new values void set (int io_entry, ACE_Event_Handler *event_handler, ACE_HANDLE io_handle, @@ -185,36 +195,37 @@ public: int delete_entry = 0, ACE_Reactor_Mask close_masks = ACE_Event_Handler::NULL_MASK, int suspend_entry = 0); - // Set the structure to these new values + /// Set the structure to these new values void set (Common_Info &common_info, int suspend_entry = 0); - // Set the structure to these new values + /// Dump the state of an object. void dump (ACE_HANDLE event_handle) const; - // Dump the state of an object. }; + /** + * @class To_Be_Added_Info + * + * @brief This structure inherits from the common structure to add + * information for <to_be_added> entries. + */ class To_Be_Added_Info : public Common_Info { - // = TITLE - // - // This structure inherits from the common structure to add - // information for <to_be_added> entries. - // public: + /// Handle for the event ACE_HANDLE event_handle_; - // Handle for the event + /// This is set when the entry needed to be suspended. int suspend_entry_; - // This is set when the entry needed to be suspended. + /// Default constructor To_Be_Added_Info (void); - // Default constructor + /// Reset the state of the structure void reset (void); - // Reset the state of the structure + /// Set the structure to these new values void set (ACE_HANDLE event_handle, int io_entry, ACE_Event_Handler *event_handler, @@ -224,37 +235,38 @@ public: int delete_entry = 0, ACE_Reactor_Mask close_masks = ACE_Event_Handler::NULL_MASK, int suspend_entry = 0); - // Set the structure to these new values + /// Set the structure to these new values void set (ACE_HANDLE event_handle, Common_Info &common_info, int suspend_entry = 0); - // Set the structure to these new values + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. }; + /** + * @class Suspended_Info + * + * @brief This structure inherits from the common structure to add + * information for suspended entries. + */ class Suspended_Info : public Common_Info { - // = TITLE - // - // This structure inherits from the common structure to add - // information for suspended entries. - // public: + /// Handle for the event ACE_HANDLE event_handle_; - // Handle for the event + /// This is set when the entry needed to be resumed. int resume_entry_; - // This is set when the entry needed to be resumed. + /// Constructor used for initializing the structure Suspended_Info (void); - // Constructor used for initializing the structure + /// Reset the state of the structure void reset (void); - // Reset the state of the structure + /// Set the structure to these new values void set (ACE_HANDLE event_handle, int io_entry, ACE_Event_Handler *event_handler, @@ -264,55 +276,54 @@ public: int delete_entry = 0, ACE_Reactor_Mask close_masks = 0, int resume_entry = 0); - // Set the structure to these new values + /// Set the structure to these new values void set (ACE_HANDLE event_handle, Common_Info &common_info, int resume_entry = 0); - // Set the structure to these new values + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. }; + /// Constructor. ACE_WFMO_Reactor_Handler_Repository (ACE_WFMO_Reactor &wfmo_reactor); - // Constructor. + /// Destructor. virtual ~ACE_WFMO_Reactor_Handler_Repository (void); - // Destructor. + /// Initialize the repository of the approriate <size>. int open (size_t size); - // Initialize the repository of the approriate <size>. + /// Close down the handler repository. int close (void); - // Close down the handler repository. // = Search structure operations. + /// Bind the <ACE_Event_Handler *> to the <ACE_HANDLE>. This is for + /// the simple event entry. int bind (ACE_HANDLE, ACE_Event_Handler *); - // Bind the <ACE_Event_Handler *> to the <ACE_HANDLE>. This is for - // the simple event entry. + /// Insert I/O <Event_Handler> entry into the system. This method + /// assumes that the lock are head *before* this method is invoked. int bind_i (int io_entry, ACE_Event_Handler *event_handler, long network_events, ACE_HANDLE io_handle, ACE_HANDLE event_handle, int delete_event); - // Insert I/O <Event_Handler> entry into the system. This method - // assumes that the lock are head *before* this method is invoked. + /// Remove the binding of <ACE_HANDLE> in accordance with the <mask>. int unbind (ACE_HANDLE, ACE_Reactor_Mask mask); - // Remove the binding of <ACE_HANDLE> in accordance with the <mask>. + /// Non-lock-grabbing version of <unbind> int unbind_i (ACE_HANDLE, ACE_Reactor_Mask mask, int &changes_required); - // Non-lock-grabbing version of <unbind> + /// Remove all bindings of <ACE_HANDLE, ACE_Event_Handler> tuples. void unbind_all (void); - // Remove all bindings of <ACE_HANDLE, ACE_Event_Handler> tuples. // = Sanity checking. @@ -320,26 +331,32 @@ public: int invalid_handle (ACE_HANDLE handle) const; // = Accessors. + /// Maximum ACE_HANDLE value, plus 1. size_t max_handlep1 (void) const; - // Maximum ACE_HANDLE value, plus 1. + /// Pointer to the beginning of the current array of <ACE_HANDLE> + /// *'s. ACE_HANDLE *handles (void) const; - // Pointer to the beginning of the current array of <ACE_HANDLE> - // *'s. + /// Pointer to the beginning of the current array of + /// <ACE_Event_Handler> *'s. Current_Info *current_info (void) const; - // Pointer to the beginning of the current array of - // <ACE_Event_Handler> *'s. + /// Check if changes to the handle set are required. virtual int changes_required (void); - // Check if changes to the handle set are required. + /// Make changes to the handle set virtual int make_changes (void); - // Make changes to the handle set + /// Check to see if <slot> has been scheduled for deletion int scheduled_for_deletion (size_t slot) const; - // Check to see if <slot> has been scheduled for deletion + /** + * This method is used to calculate the network mask after a mask_op + * request to <WFMO_Reactor>. Note that because the <Event_Handler> + * may already be in the handler repository, we may have to find the + * old event and the old network events + */ int modify_network_events_i (ACE_HANDLE io_handle, ACE_Reactor_Mask new_masks, ACE_Reactor_Mask &old_masks, @@ -347,181 +364,193 @@ public: ACE_HANDLE &event_handle, int &delete_event, int operation); - // This method is used to calculate the network mask after a mask_op - // request to <WFMO_Reactor>. Note that because the <Event_Handler> - // may already be in the handler repository, we may have to find the - // old event and the old network events + /// This method is used to change the network mask left (if any) + /// after a remove request to <WFMO_Reactor> ACE_Reactor_Mask bit_ops (long &existing_masks, ACE_Reactor_Mask to_be_removed_masks, int operation); - // This method is used to change the network mask left (if any) - // after a remove request to <WFMO_Reactor> + /// Temporarily suspend entry int suspend_handler_i (ACE_HANDLE handle, int &changes_required); - // Temporarily suspend entry + /// Resume suspended entry int resume_handler_i (ACE_HANDLE handle, int &changes_required); - // Resume suspended entry + /// Deletions and suspensions in current_info_ int make_changes_in_current_infos (void); - // Deletions and suspensions in current_info_ + /// Deletions and resumptions in current_suspended_info_ int make_changes_in_suspension_infos (void); - // Deletions and resumptions in current_suspended_info_ + /// Deletions in to_be_added_info_, or transfers to current_info_ or + /// current_suspended_info_ from to_be_added_info_ int make_changes_in_to_be_added_infos (void); - // Deletions in to_be_added_info_, or transfers to current_info_ or - // current_suspended_info_ from to_be_added_info_ + /// Removes the <ACE_Event_Handler> at <slot> from the table. int remove_handler_i (size_t slot, ACE_Reactor_Mask mask); - // Removes the <ACE_Event_Handler> at <slot> from the table. + /// Removes the <ACE_Event_Handler> at <slot> from the table. int remove_suspended_handler_i (size_t slot, ACE_Reactor_Mask mask); - // Removes the <ACE_Event_Handler> at <slot> from the table. + /// Removes the <ACE_Event_Handler> at <slot> from the table. int remove_to_be_added_handler_i (size_t slot, ACE_Reactor_Mask to_be_removed_masks); - // Removes the <ACE_Event_Handler> at <slot> from the table. + /** + * Check to see if <handle> is associated with a valid Event_Handler + * bound to <mask>. Return the <event_handler> associated with this + * <handler> if <event_handler> != 0. + */ int handler (ACE_HANDLE handle, ACE_Reactor_Mask mask, ACE_Event_Handler **event_handler = 0); - // Check to see if <handle> is associated with a valid Event_Handler - // bound to <mask>. Return the <event_handler> associated with this - // <handler> if <event_handler> != 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. protected: + /// Reference to our <WFMO_Reactor>. ACE_WFMO_Reactor &wfmo_reactor_; - // Reference to our <WFMO_Reactor>. + /// Maximum number of handles. size_t max_size_; - // Maximum number of handles. + /** + * Array of <ACE_HANDLEs> passed to <WaitForMultipleObjects>. This + * is not part of the structure as the handle array needs to be + * passed directly to <WaitForMultipleObjects>. + */ ACE_HANDLE *current_handles_; - // Array of <ACE_HANDLEs> passed to <WaitForMultipleObjects>. This - // is not part of the structure as the handle array needs to be - // passed directly to <WaitForMultipleObjects>. + /// Array of current entries in the table Current_Info *current_info_; - // Array of current entries in the table + /// A count of the number of active handles. size_t max_handlep1_; - // A count of the number of active handles. + /// Information for entries to be added To_Be_Added_Info *to_be_added_info_; - // Information for entries to be added + /// Number of records to be added size_t handles_to_be_added_; - // Number of records to be added + /// Currently suspended handles Suspended_Info *current_suspended_info_; - // Currently suspended handles + /// Number of currently suspended handles size_t suspended_handles_; - // Number of currently suspended handles + /// Number of records to be suspended size_t handles_to_be_suspended_; - // Number of records to be suspended + /// Number of records to be resumed size_t handles_to_be_resumed_; - // Number of records to be resumed + /// Number of records to be deleted size_t handles_to_be_deleted_; - // Number of records to be deleted }; +/** + * @class ACE_WFMO_Reactor_Notify + * + * @brief Unblock the <ACE_WFMO_Reactor> from its event loop, passing + * it an optional <ACE_Event_Handler> to dispatch. + * + * This implementation is necessary for cases where the + * <ACE_WFMO_Reactor> is run in a multi-threaded program. In + * this case, we need to be able to unblock + * <WaitForMultipleObjects> when updates occur other than in the + * main <ACE_WFMO_Reactor> thread. To do this, we signal an + * auto-reset event the <ACE_WFMO_Reactor> is listening on. If + * an <ACE_Event_Handler> and <ACE_Reactor_Mask> is passed to + * <notify>, the appropriate <handle_*> method is dispatched. + */ class ACE_Export ACE_WFMO_Reactor_Notify : public ACE_Reactor_Notify { - // = TITLE - // Unblock the <ACE_WFMO_Reactor> from its event loop, passing - // it an optional <ACE_Event_Handler> to dispatch. - // - // = DESCRIPTION - // This implementation is necessary for cases where the - // <ACE_WFMO_Reactor> is run in a multi-threaded program. In - // this case, we need to be able to unblock - // <WaitForMultipleObjects> when updates occur other than in the - // main <ACE_WFMO_Reactor> thread. To do this, we signal an - // auto-reset event the <ACE_WFMO_Reactor> is listening on. If - // an <ACE_Event_Handler> and <ACE_Reactor_Mask> is passed to - // <notify>, the appropriate <handle_*> method is dispatched. public: + /// Constructor ACE_WFMO_Reactor_Notify (void); - // Constructor + /// Initialization. <timer_queue> is stored to call <gettimeofday>. virtual int open (ACE_Reactor_Impl *wfmo_reactor, ACE_Timer_Queue *timer_queue, int disable_notify = 0); - // Initialization. <timer_queue> is stored to call <gettimeofday>. + /// No-op. virtual int close (void); - // No-op. + /** + * Special trick to unblock <WaitForMultipleObjects> when updates + * occur. All we do is enqueue <event_handler> and <mask> onto the + * <ACE_Message_Queue> and wakeup the <WFMO_Reactor> by signaling + * its <ACE_Event> handle. The <ACE_Time_Value> indicates how long + * to blocking trying to notify the <WFMO_Reactor>. If <timeout> == + * 0, the caller will block until action is possible, else will wait + * until the relative time specified in <timeout> elapses). + */ ssize_t notify (ACE_Event_Handler *event_handler = 0, ACE_Reactor_Mask mask = ACE_Event_Handler::EXCEPT_MASK, ACE_Time_Value *timeout = 0); - // Special trick to unblock <WaitForMultipleObjects> when updates - // occur. All we do is enqueue <event_handler> and <mask> onto the - // <ACE_Message_Queue> and wakeup the <WFMO_Reactor> by signaling - // its <ACE_Event> handle. The <ACE_Time_Value> indicates how long - // to blocking trying to notify the <WFMO_Reactor>. If <timeout> == - // 0, the caller will block until action is possible, else will wait - // until the relative time specified in <timeout> elapses). + /// No-op. virtual int dispatch_notifications (int &number_of_active_handles, ACE_Handle_Set &rd_mask); - // No-op. + /// Returns a handle to the <ACE_Auto_Event>. virtual ACE_HANDLE get_handle (void) const; - // Returns a handle to the <ACE_Auto_Event>. + /** + * Set the maximum number of times that the + * <ACE_WFMO_Reactor_Notify::handle_input> method will iterate and + * dispatch the <ACE_Event_Handlers> that are passed in via the + * notify queue before breaking out of its + * <ACE_Message_Queue::dequeue> loop. By default, this is set to + * -1, which means "iterate until the queue is empty." Setting this + * to a value like "1 or 2" will increase "fairness" (and thus + * prevent starvation) at the expense of slightly higher dispatching + * overhead. + */ void max_notify_iterations (int); - // Set the maximum number of times that the - // <ACE_WFMO_Reactor_Notify::handle_input> method will iterate and - // dispatch the <ACE_Event_Handlers> that are passed in via the - // notify queue before breaking out of its - // <ACE_Message_Queue::dequeue> loop. By default, this is set to - // -1, which means "iterate until the queue is empty." Setting this - // to a value like "1 or 2" will increase "fairness" (and thus - // prevent starvation) at the expense of slightly higher dispatching - // overhead. + /** + * Get the maximum number of times that the + * <ACE_WFMO_Reactor_Notify::handle_input> method will iterate and + * dispatch the <ACE_Event_Handlers> that are passed in via the + * notify queue before breaking out of its + * <ACE_Message_Queue::dequeue> loop. + */ int max_notify_iterations (void); - // Get the maximum number of times that the - // <ACE_WFMO_Reactor_Notify::handle_input> method will iterate and - // dispatch the <ACE_Event_Handlers> that are passed in via the - // notify queue before breaking out of its - // <ACE_Message_Queue::dequeue> loop. + /** + * Purge any notifications pending in this reactor for the specified + * <ACE_Event_Handler> object. Returns the number of notifications + * purged. Returns -1 on error. + */ virtual int purge_pending_notifications (ACE_Event_Handler * = 0); - // Purge any notifications pending in this reactor for the specified - // <ACE_Event_Handler> object. Returns the number of notifications - // purged. Returns -1 on error. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. private: + /// Pointer to the wfmo_reactor's timer queue. ACE_Timer_Queue *timer_queue_; - // Pointer to the wfmo_reactor's timer queue. + /** + * Called when the notification event waited on by + * <ACE_WFMO_Reactor> is signaled. This dequeues all pending + * <ACE_Event_Handlers> and dispatches them. + */ virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0); - // Called when the notification event waited on by - // <ACE_WFMO_Reactor> is signaled. This dequeues all pending - // <ACE_Event_Handlers> and dispatches them. + /// An auto event is used so that we can <signal> it to wakeup one + /// thread up (e.g., when the <notify> method is called). ACE_Auto_Event wakeup_one_thread_; - // An auto event is used so that we can <signal> it to wakeup one - // thread up (e.g., when the <notify> method is called). #if defined (ACE_WIN32) && !defined (ACE_HAS_WINCE) // because Sun C++ 4.1 can't cope with this declaration: @@ -531,651 +560,730 @@ private: // This queue must be thread-safe because it can be called by // multiple threads of control. + /** + * Keeps track of the maximum number of times that the + * <ACE_WFMO_Reactor_Notify::handle_input> method will iterate and + * dispatch the <ACE_Event_Handlers> that are passed in via the + * notify queue before breaking out of its + * <ACE_Message_Queue::dequeue> loop. By default, this is set to + * -1, which means "iterate until the queue is empty." + */ int max_notify_iterations_; - // Keeps track of the maximum number of times that the - // <ACE_WFMO_Reactor_Notify::handle_input> method will iterate and - // dispatch the <ACE_Event_Handlers> that are passed in via the - // notify queue before breaking out of its - // <ACE_Message_Queue::dequeue> loop. By default, this is set to - // -1, which means "iterate until the queue is empty." }; #if defined (ACE_WIN32) && !defined (ACE_HAS_WINCE) +/** + * @class ACE_WFMO_Reactor + * + * @brief An object oriented event demultiplexor and event handler + * WFMO_Reactor for Win32 WaitForMultipleObjects + * + * The ACE_WFMO_Reactor is an object-oriented event + * demultiplexor and event handler Reactor. The sources of + * events that the ACE_WFMO_Reactor waits for and dispatches + * includes I/O events, general Win32 synchronization events + * (such as mutexes, semaphores, threads, etc.) and timer + * events. + * Note that changes to the state of WFMO_Reactor are not + * instantaneous. Most changes (registration, removal, + * suspension, and resumption of handles, and changes in + * ownership) are made when the WFMO_Reactor reaches a stable + * state. Users should be careful, specially when removing + * handlers. This is because the WFMO_Reactor will call + * handle_close on the handler when it is finally removed and + * not when remove_handler is called. If the handler is not + * going to be around when the WFMO_Reactor calls + * <ACE_Event_Handler::handle_close>, use the DONT_CALL flag + * with <remove_handler>. Or else, dynamically allocate the + * handler, and then call "delete this" inside + * <ACE_Event_Handler::handle_close>. + */ class ACE_Export ACE_WFMO_Reactor : public ACE_Reactor_Impl { - // = TITLE - // An object oriented event demultiplexor and event handler - // WFMO_Reactor for Win32 WaitForMultipleObjects - // - // = DESCRIPTION - // The ACE_WFMO_Reactor is an object-oriented event - // demultiplexor and event handler Reactor. The sources of - // events that the ACE_WFMO_Reactor waits for and dispatches - // includes I/O events, general Win32 synchronization events - // (such as mutexes, semaphores, threads, etc.) and timer - // events. - // - // Note that changes to the state of WFMO_Reactor are not - // instantaneous. Most changes (registration, removal, - // suspension, and resumption of handles, and changes in - // ownership) are made when the WFMO_Reactor reaches a stable - // state. Users should be careful, specially when removing - // handlers. This is because the WFMO_Reactor will call - // handle_close on the handler when it is finally removed and - // not when remove_handler is called. If the handler is not - // going to be around when the WFMO_Reactor calls - // <ACE_Event_Handler::handle_close>, use the DONT_CALL flag - // with <remove_handler>. Or else, dynamically allocate the - // handler, and then call "delete this" inside - // <ACE_Event_Handler::handle_close>. public: friend class ACE_WFMO_Reactor_Handler_Repository; friend class ACE_WFMO_Reactor_Test; enum { + /// Default size of the WFMO_Reactor's handle table. + /** + * Two slots will be added to the <size> parameter in the + * constructor and open methods which will store handles used for + * internal management purposes. + */ DEFAULT_SIZE = MAXIMUM_WAIT_OBJECTS - 2 - // Default size of the WFMO_Reactor's handle table. Two slots will - // be added to the <size> parameter in the constructor and open - // methods which will store handles used for internal management - // purposes. }; // = Initialization and termination methods. + /// Initialize <ACE_WFMO_Reactor> with the default size. ACE_WFMO_Reactor (ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0); - // Initialize <ACE_WFMO_Reactor> with the default size. + /** + * Initialize <ACE_WFMO_Reactor> with size <size>. <size> should + * not exceed <ACE_WFMO_Reactor::DEFAULT_SIZE>. Two slots will be + * added to the <size> parameter which will store handles used for + * internal management purposes. + */ ACE_WFMO_Reactor (size_t size, int unused = 0, ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0); - // Initialize <ACE_WFMO_Reactor> with size <size>. <size> should - // not exceed <ACE_WFMO_Reactor::DEFAULT_SIZE>. Two slots will be - // added to the <size> parameter which will store handles used for - // internal management purposes. + /** + * Initialize <ACE_WFMO_Reactor> with size <size>. <size> should + * not exceed <ACE_WFMO_Reactor::DEFAULT_SIZE>. Two slots will be + * added to the <size> parameter which will store handles used for + * internal management purposes. + */ virtual int open (size_t size = ACE_WFMO_Reactor::DEFAULT_SIZE, int restart = 0, ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0, int disable_notify_pipe = 0, ACE_Reactor_Notify * = 0); - // Initialize <ACE_WFMO_Reactor> with size <size>. <size> should - // not exceed <ACE_WFMO_Reactor::DEFAULT_SIZE>. Two slots will be - // added to the <size> parameter which will store handles used for - // internal management purposes. + /// Returns -1 (not used in this implementation); virtual int current_info (ACE_HANDLE, size_t & /* size */); - // Returns -1 (not used in this implementation); + /// Use a user specified signal handler instead. virtual int set_sig_handler (ACE_Sig_Handler *signal_handler); - // Use a user specified signal handler instead. // = The following method is deprecated. Use <timer_queue> instead. + /// Set a user specified timer queue. virtual int set_timer_queue (ACE_Timer_Queue *tq); - // Set a user specified timer queue. + /// Set a user-specified timer queue. + /// Return the current <ACE_Timer_Queue>. virtual int timer_queue (ACE_Timer_Queue *tq); - // Set a user-specified timer queue. virtual ACE_Timer_Queue *timer_queue (void) const; - // Return the current <ACE_Timer_Queue>. + /// Close down the WFMO_Reactor and release all of its resources. virtual int close (void); - // Close down the WFMO_Reactor and release all of its resources. + /// Close down the WFMO_Reactor and release all of its resources. virtual ~ACE_WFMO_Reactor (void); - // Close down the WFMO_Reactor and release all of its resources. // = Event loop drivers. + /** + * Returns non-zero if there are I/O events "ready" for dispatching, + * but does not actually dispatch the event handlers. By default, + * don't block while checking this, i.e., "poll". + */ virtual int work_pending (const ACE_Time_Value &max_wait_time = ACE_Time_Value::zero); - // Returns non-zero if there are I/O events "ready" for dispatching, - // but does not actually dispatch the event handlers. By default, - // don't block while checking this, i.e., "poll". + /** + * This event loop driver blocks for up to <max_wait_time> before + * returning. It will return earlier if timer events, I/O events, + * or signal events occur. Note that <max_wait_time> can be 0, in + * which case this method blocks indefinitely until events occur. + * + * <max_wait_time> is decremented to reflect how much time this call + * took. For instance, if a time value of 3 seconds is passed to + * handle_events and an event occurs after 2 seconds, + * <max_wait_time> will equal 1 second. This can be used if an + * application wishes to handle events for some fixed amount of + * time. + * + * <WaitForMultipleObjects> is used as the demultiplexing call + * + * Returns the total number of I/O and timer <ACE_Event_Handler>s + * that were dispatched, 0 if the <max_wait_time> elapsed without + * dispatching any handlers, or -1 if an error occurs. + * + * The only difference between <alertable_handle_events> and + * <handle_events> is that in the alertable case, TRUE is passed to + * <WaitForMultipleObjects> for the <bAlertable> option. + */ virtual int handle_events (ACE_Time_Value *max_wait_time = 0); virtual int alertable_handle_events (ACE_Time_Value *max_wait_time = 0); - // This event loop driver blocks for up to <max_wait_time> before - // returning. It will return earlier if timer events, I/O events, - // or signal events occur. Note that <max_wait_time> can be 0, in - // which case this method blocks indefinitely until events occur. - // - // <max_wait_time> is decremented to reflect how much time this call - // took. For instance, if a time value of 3 seconds is passed to - // handle_events and an event occurs after 2 seconds, - // <max_wait_time> will equal 1 second. This can be used if an - // application wishes to handle events for some fixed amount of - // time. - // - // <WaitForMultipleObjects> is used as the demultiplexing call - // - // Returns the total number of I/O and timer <ACE_Event_Handler>s - // that were dispatched, 0 if the <max_wait_time> elapsed without - // dispatching any handlers, or -1 if an error occurs. - // - // The only difference between <alertable_handle_events> and - // <handle_events> is that in the alertable case, TRUE is passed to - // <WaitForMultipleObjects> for the <bAlertable> option. + /** + * This method is just like the one above, except the + * <max_wait_time> value is a reference and can therefore never be + * NULL. + * + * The only difference between <alertable_handle_events> and + * <handle_events> is that in the alertable case, TRUE is passed to + * <WaitForMultipleObjects> for the <bAlertable> option. + */ virtual int handle_events (ACE_Time_Value &max_wait_time); virtual int alertable_handle_events (ACE_Time_Value &max_wait_time); - // This method is just like the one above, except the - // <max_wait_time> value is a reference and can therefore never be - // NULL. - // - // The only difference between <alertable_handle_events> and - // <handle_events> is that in the alertable case, TRUE is passed to - // <WaitForMultipleObjects> for the <bAlertable> option. // = Event handling control. + /** + * Return the status of Reactor. If this function returns 0, the reactor is + * actively handling events. If it returns non-zero, <handling_events> and + * <handle_alertable_events> return -1 immediately. + */ virtual int deactivated (void); - // Return the status of Reactor. If this function returns 0, the reactor is - // actively handling events. If it returns non-zero, <handling_events> and - // <handle_alertable_events> return -1 immediately. + /** + * Control whether the Reactor will handle any more incoming events or not. + * If <do_stop> == 1, the Reactor will be disabled. By default, a reactor + * is in active state and can be deactivated/reactived as wish. + */ virtual void deactivate (int do_stop); - // Control whether the Reactor will handle any more incoming events or not. - // If <do_stop> == 1, the Reactor will be disabled. By default, a reactor - // is in active state and can be deactivated/reactived as wish. // = Register and remove Handlers. + /** + * Register an <ACE_Event_Handler> <event_handler>. Since no Event + * Mask is passed through this interface, it is assumed that the + * <handle> being passed in is an event handle and when the event + * becomes signaled, <WFMO_Reactor> will call handle_signal on + * <event_handler>. If <handle> == <ACE_INVALID_HANDLE> the + * <ACE_WFMO_Reactor> will call the <get_handle> method of + * <event_handler> to extract the underlying event handle. + */ virtual int register_handler (ACE_Event_Handler *event_handler, ACE_HANDLE event_handle = ACE_INVALID_HANDLE); - // Register an <ACE_Event_Handler> <event_handler>. Since no Event - // Mask is passed through this interface, it is assumed that the - // <handle> being passed in is an event handle and when the event - // becomes signaled, <WFMO_Reactor> will call handle_signal on - // <event_handler>. If <handle> == <ACE_INVALID_HANDLE> the - // <ACE_WFMO_Reactor> will call the <get_handle> method of - // <event_handler> to extract the underlying event handle. + /** + * Register an <ACE_Event_Handler> <event_handle>. <mask> specifies + * the network events that the <event_handler> is interested in. If + * <io_handle> == <ACE_INVALID_HANDLE> the <ACE_WFMO_Reactor> will + * call the <get_handle> method of <event_handler> to extract the + * underlying I/O handle. If the <event_handle> == + * <ACE_INVALID_HANDLE>, WFMO_Reactor will create an event for + * associating it with the I/O handle. When the <event_handle> is + * signalled, the appropriate <handle_*> callback will be invoked on + * the <Event_Handler> + */ virtual int register_handler (ACE_HANDLE event_handle, ACE_HANDLE io_handle, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // Register an <ACE_Event_Handler> <event_handle>. <mask> specifies - // the network events that the <event_handler> is interested in. If - // <io_handle> == <ACE_INVALID_HANDLE> the <ACE_WFMO_Reactor> will - // call the <get_handle> method of <event_handler> to extract the - // underlying I/O handle. If the <event_handle> == - // <ACE_INVALID_HANDLE>, WFMO_Reactor will create an event for - // associating it with the I/O handle. When the <event_handle> is - // signalled, the appropriate <handle_*> callback will be invoked on - // the <Event_Handler> + /** + * This is a simple version of the above <register_handler> method + * where the I/O handle is passed in and the event handle will + * always be created by <WFMO_Reactor> + */ virtual int register_handler (ACE_HANDLE io_handle, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // This is a simple version of the above <register_handler> method - // where the I/O handle is passed in and the event handle will - // always be created by <WFMO_Reactor> + /** + * This is a simple version of the above <register_handler> method + * where the I/O handle will always come from <get_handle> on the + * <Event_Handler> and the event handle will always be created by + * <WFMO_Reactor> + */ virtual int register_handler (ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // This is a simple version of the above <register_handler> method - // where the I/O handle will always come from <get_handle> on the - // <Event_Handler> and the event handle will always be created by - // <WFMO_Reactor> + /// Register <event_handler> with all the <handles> in the + /// <Handle_Set>. virtual int register_handler (const ACE_Handle_Set &handles, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // Register <event_handler> with all the <handles> in the - // <Handle_Set>. + /** + * Register <new_sh> to handle the signal <signum> using the + * <new_disp>. Returns the <old_sh> that was previously registered + * (if any), along with the <old_disp> of the signal handler. + */ virtual int register_handler (int signum, ACE_Event_Handler *new_sh, ACE_Sig_Action *new_disp = 0, ACE_Event_Handler **old_sh = 0, ACE_Sig_Action *old_disp = 0); - // Register <new_sh> to handle the signal <signum> using the - // <new_disp>. Returns the <old_sh> that was previously registered - // (if any), along with the <old_disp> of the signal handler. + /// Registers <new_sh> to handle a set of signals <sigset> using the + /// <new_disp>. virtual int register_handler (const ACE_Sig_Set &sigset, ACE_Event_Handler *new_sh, ACE_Sig_Action *new_disp = 0); - // Registers <new_sh> to handle a set of signals <sigset> using the - // <new_disp>. + /** + * Removes <event_handler> from the <ACE_WFMO_Reactor>. Note that + * the <ACE_WFMO_Reactor> will call the <get_handle> method of + * <event_handler> to extract the underlying handle. If <mask> == + * <ACE_Event_Handler::DONT_CALL> then the <handle_close> method of + * the <event_handler> is not invoked. Note that the <handle> can + * either be the <event_handle> or the <io_handle> + */ virtual int remove_handler (ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // Removes <event_handler> from the <ACE_WFMO_Reactor>. Note that - // the <ACE_WFMO_Reactor> will call the <get_handle> method of - // <event_handler> to extract the underlying handle. If <mask> == - // <ACE_Event_Handler::DONT_CALL> then the <handle_close> method of - // the <event_handler> is not invoked. Note that the <handle> can - // either be the <event_handle> or the <io_handle> + /** + * Removes <handle> from the <ACE_WFMO_Reactor>. If <mask> == + * <ACE_Event_Handler::DONT_CALL> then the <handle_close> method of + * the <event_handler> is not invoked. Note that the <handle> can + * either be the <event_handle> or the <io_handle> + * + * For the case of I/O entries, this removes the <mask> binding of + * <Event_Handler> whose handle is <handle> from <WFMO_Reactor>. If + * there are no more bindings for this <event_handler> then it is + * removed from the WFMO_Reactor. For simple event entries, mask is + * mostly ignored and the <Event_Handler> is always removed from + * <WFMO_Reactor> + */ virtual int remove_handler (ACE_HANDLE handle, ACE_Reactor_Mask mask); - // Removes <handle> from the <ACE_WFMO_Reactor>. If <mask> == - // <ACE_Event_Handler::DONT_CALL> then the <handle_close> method of - // the <event_handler> is not invoked. Note that the <handle> can - // either be the <event_handle> or the <io_handle> - // - // For the case of I/O entries, this removes the <mask> binding of - // <Event_Handler> whose handle is <handle> from <WFMO_Reactor>. If - // there are no more bindings for this <event_handler> then it is - // removed from the WFMO_Reactor. For simple event entries, mask is - // mostly ignored and the <Event_Handler> is always removed from - // <WFMO_Reactor> + /** + * Removes all the <mask> bindings for handles in the <handle_set> + * bind of <Event_Handler>. If there are no more bindings for any + * of these handles then they are removed from WFMO_Reactor. + */ virtual int remove_handler (const ACE_Handle_Set &handle_set, ACE_Reactor_Mask); - // Removes all the <mask> bindings for handles in the <handle_set> - // bind of <Event_Handler>. If there are no more bindings for any - // of these handles then they are removed from WFMO_Reactor. + /** + * Remove the ACE_Event_Handler currently associated with <signum>. + * <sigkey> is ignored in this implementation since there is only + * one instance of a signal handler. Install the new disposition + * (if given) and return the previous disposition (if desired by the + * caller). Returns 0 on success and -1 if <signum> is invalid. + */ virtual int remove_handler (int signum, ACE_Sig_Action *new_disp, ACE_Sig_Action *old_disp = 0, int sigkey = -1); - // Remove the ACE_Event_Handler currently associated with <signum>. - // <sigkey> is ignored in this implementation since there is only - // one instance of a signal handler. Install the new disposition - // (if given) and return the previous disposition (if desired by the - // caller). Returns 0 on success and -1 if <signum> is invalid. + /// Calls <remove_handler> for every signal in <sigset>. virtual int remove_handler (const ACE_Sig_Set &sigset); - // Calls <remove_handler> for every signal in <sigset>. // = Suspend and resume Handlers. + /// Suspend <event_handler> temporarily. Use + /// <ACE_Event_Handler::get_handle> to get the handle. virtual int suspend_handler (ACE_Event_Handler *event_handler); - // Suspend <event_handler> temporarily. Use - // <ACE_Event_Handler::get_handle> to get the handle. + /// Suspend <handle> temporarily. virtual int suspend_handler (ACE_HANDLE handle); - // Suspend <handle> temporarily. + /// Suspend all <handles> in handle set temporarily. virtual int suspend_handler (const ACE_Handle_Set &handles); - // Suspend all <handles> in handle set temporarily. + /// Suspend all <handles> temporarily. virtual int suspend_handlers (void); - // Suspend all <handles> temporarily. + /// Resume <event_handler>. Use <ACE_Event_Handler::get_handle> to + /// get the handle. virtual int resume_handler (ACE_Event_Handler *event_handler); - // Resume <event_handler>. Use <ACE_Event_Handler::get_handle> to - // get the handle. + /// Resume <handle>. virtual int resume_handler (ACE_HANDLE handle); - // Resume <handle>. + /// Resume all <handles> in handle set. virtual int resume_handler (const ACE_Handle_Set &handles); - // Resume all <handles> in handle set. + /// Resume all <handles>. virtual int resume_handlers (void); - // Resume all <handles>. + /** + * Return 1 if we any event associations were made by the reactor + * for the handles that it waits on, 0 otherwise. Since the + * WFMO_Reactor does use event associations, this function always + * return 1. + */ virtual int uses_event_associations (void); - // Return 1 if we any event associations were made by the reactor - // for the handles that it waits on, 0 otherwise. Since the - // WFMO_Reactor does use event associations, this function always - // return 1. // Timer management. + /** + * Schedule an <event_handler> that will expire after <delay> amount + * of time, which is specified using relative time to the current + * <gettimeofday>. If it expires then <arg> is passed in as the + * value to the <event_handler>'s <handle_timeout> callback method. + * If <interval> is != to <ACE_Time_Value::zero> then it is used to + * reschedule the <event_handler> automatically, which is also + * specified using relative time. This method returns a <timer_id> + * that uniquely identifies the <event_handler> in an internal list. + * This <timer_id> can be used to cancel an <event_handler> before + * it expires. The cancellation ensures that <timer_ids> are unique + * up to values of greater than 2 billion timers. As long as timers + * don't stay around longer than this there should be no problems + * with accidentally deleting the wrong timer. Returns -1 on + * failure (which is guaranteed never to be a valid <timer_id>. + */ virtual long schedule_timer (ACE_Event_Handler *event_handler, const void *arg, const ACE_Time_Value &delta, const ACE_Time_Value &interval = ACE_Time_Value::zero); - // Schedule an <event_handler> that will expire after <delay> amount - // of time, which is specified using relative time to the current - // <gettimeofday>. If it expires then <arg> is passed in as the - // value to the <event_handler>'s <handle_timeout> callback method. - // If <interval> is != to <ACE_Time_Value::zero> then it is used to - // reschedule the <event_handler> automatically, which is also - // specified using relative time. This method returns a <timer_id> - // that uniquely identifies the <event_handler> in an internal list. - // This <timer_id> can be used to cancel an <event_handler> before - // it expires. The cancellation ensures that <timer_ids> are unique - // up to values of greater than 2 billion timers. As long as timers - // don't stay around longer than this there should be no problems - // with accidentally deleting the wrong timer. Returns -1 on - // failure (which is guaranteed never to be a valid <timer_id>. + /** + * Resets the interval of the timer represented by <timer_id> to + * <interval>, which is specified in relative time to the current + * <gettimeofday>. If <interval> is equal to + * <ACE_Time_Value::zero>, the timer will become a non-rescheduling + * timer. Returns 0 if successful, -1 if not. + */ virtual int reset_timer_interval (long timer_id, const ACE_Time_Value &interval); - // Resets the interval of the timer represented by <timer_id> to - // <interval>, which is specified in relative time to the current - // <gettimeofday>. If <interval> is equal to - // <ACE_Time_Value::zero>, the timer will become a non-rescheduling - // timer. Returns 0 if successful, -1 if not. + /// Cancel all Event_Handlers that match the address of + /// <event_handler>. Returns number of handler's cancelled. virtual int cancel_timer (ACE_Event_Handler *event_handler, int dont_call_handle_close = 1); - // Cancel all Event_Handlers that match the address of - // <event_handler>. Returns number of handler's cancelled. + /** + * Cancel the single Event_Handler that matches the <timer_id> value + * (which was returned from the schedule method). If arg is + * non-NULL then it will be set to point to the ``magic cookie'' + * argument passed in when the Event_Handler was registered. This + * makes it possible to free up the memory and avoid memory leaks. + * Returns 1 if cancellation succeeded and 0 if the <timer_id> + * wasn't found. + */ virtual int cancel_timer (long timer_id, const void **arg = 0, int dont_call_handle_close = 1); - // Cancel the single Event_Handler that matches the <timer_id> value - // (which was returned from the schedule method). If arg is - // non-NULL then it will be set to point to the ``magic cookie'' - // argument passed in when the Event_Handler was registered. This - // makes it possible to free up the memory and avoid memory leaks. - // Returns 1 if cancellation succeeded and 0 if the <timer_id> - // wasn't found. // = High-level Event_Handler scheduling operations + /** + * Add <masks_to_be_added> to the <event_handler>'s entry in + * WFMO_Reactor. <event_handler> must already have been registered + * with WFMO_Reactor. + */ virtual int schedule_wakeup (ACE_Event_Handler *event_handler, ACE_Reactor_Mask masks_to_be_added); - // Add <masks_to_be_added> to the <event_handler>'s entry in - // WFMO_Reactor. <event_handler> must already have been registered - // with WFMO_Reactor. + /** + * Add <masks_to_be_added> to the <handle>'s entry in WFMO_Reactor. + * The Event_Handler associated with <handle> must already have been + * registered with WFMO_Reactor. + */ virtual int schedule_wakeup (ACE_HANDLE handle, ACE_Reactor_Mask masks_to_be_added); - // Add <masks_to_be_added> to the <handle>'s entry in WFMO_Reactor. - // The Event_Handler associated with <handle> must already have been - // registered with WFMO_Reactor. + /** + * Remove <masks_to_be_deleted> to the <handle>'s entry in + * WFMO_Reactor. The Event_Handler associated with <handle> must + * already have been registered with WFMO_Reactor. + */ virtual int cancel_wakeup (ACE_Event_Handler *event_handler, ACE_Reactor_Mask masks_to_be_deleted); - // Remove <masks_to_be_deleted> to the <handle>'s entry in - // WFMO_Reactor. The Event_Handler associated with <handle> must - // already have been registered with WFMO_Reactor. + /** + * Remove <masks_to_be_deleted> to the <handle>'s entry in + * WFMO_Reactor. The Event_Handler associated with <handle> must + * already have been registered with WFMO_Reactor. + */ virtual int cancel_wakeup (ACE_HANDLE handle, ACE_Reactor_Mask masks_to_be_deleted); - // Remove <masks_to_be_deleted> to the <handle>'s entry in - // WFMO_Reactor. The Event_Handler associated with <handle> must - // already have been registered with WFMO_Reactor. // = Notification methods. + /** + * Wakeup one <ACE_WFMO_Reactor> thread if it is currently blocked + * in <WaitForMultipleObjects>. The <ACE_Time_Value> indicates how + * long to blocking trying to notify the <WFMO_Reactor>. If + * <timeout> == 0, the caller will block until action is possible, + * else will wait until the relative time specified in <timeout> + * elapses). + */ virtual int notify (ACE_Event_Handler * = 0, ACE_Reactor_Mask = ACE_Event_Handler::EXCEPT_MASK, ACE_Time_Value * = 0); - // Wakeup one <ACE_WFMO_Reactor> thread if it is currently blocked - // in <WaitForMultipleObjects>. The <ACE_Time_Value> indicates how - // long to blocking trying to notify the <WFMO_Reactor>. If - // <timeout> == 0, the caller will block until action is possible, - // else will wait until the relative time specified in <timeout> - // elapses). + /** + * Set the maximum number of times that the + * <ACE_WFMO_Reactor_Notify::handle_input> method will iterate and + * dispatch the <ACE_Event_Handlers> that are passed in via the + * notify queue before breaking out of its + * <ACE_Message_Queue::dequeue> loop. By default, this is set to + * -1, which means "iterate until the queue is empty." Setting this + * to a value like "1 or 2" will increase "fairness" (and thus + * prevent starvation) at the expense of slightly higher dispatching + * overhead. + */ virtual void max_notify_iterations (int); - // Set the maximum number of times that the - // <ACE_WFMO_Reactor_Notify::handle_input> method will iterate and - // dispatch the <ACE_Event_Handlers> that are passed in via the - // notify queue before breaking out of its - // <ACE_Message_Queue::dequeue> loop. By default, this is set to - // -1, which means "iterate until the queue is empty." Setting this - // to a value like "1 or 2" will increase "fairness" (and thus - // prevent starvation) at the expense of slightly higher dispatching - // overhead. + /** + * Get the maximum number of times that the + * <ACE_WFMO_Reactor_Notify::handle_input> method will iterate and + * dispatch the <ACE_Event_Handlers> that are passed in via the + * notify queue before breaking out of its + * <ACE_Message_Queue::dequeue> loop. + */ virtual int max_notify_iterations (void); - // Get the maximum number of times that the - // <ACE_WFMO_Reactor_Notify::handle_input> method will iterate and - // dispatch the <ACE_Event_Handlers> that are passed in via the - // notify queue before breaking out of its - // <ACE_Message_Queue::dequeue> loop. + /** + * Purge any notifications pending in this reactor for the specified + * <ACE_Event_Handler> object. Returns the number of notifications + * purged. Returns -1 on error. + */ virtual int purge_pending_notifications (ACE_Event_Handler * = 0); - // Purge any notifications pending in this reactor for the specified - // <ACE_Event_Handler> object. Returns the number of notifications - // purged. Returns -1 on error. // = Assorted helper methods. + /** + * Check to see if <handle> is associated with a valid Event_Handler + * bound to <mask>. Return the <event_handler> associated with this + * <handler> if <event_handler> != 0. + */ virtual int handler (ACE_HANDLE handle, ACE_Reactor_Mask mask, ACE_Event_Handler **event_handler = 0); - // Check to see if <handle> is associated with a valid Event_Handler - // bound to <mask>. Return the <event_handler> associated with this - // <handler> if <event_handler> != 0. + /** + * Check to see if <signum> is associated with a valid Event_Handler + * bound to a signal. Return the <event_handler> associated with + * this <handler> if <event_handler> != 0. + */ virtual int handler (int signum, ACE_Event_Handler ** = 0); - // Check to see if <signum> is associated with a valid Event_Handler - // bound to a signal. Return the <event_handler> associated with - // this <handler> if <event_handler> != 0. + /// Returns true if WFMO_Reactor has been successfully initialized, else + /// false. virtual int initialized (void); - // Returns true if WFMO_Reactor has been successfully initialized, else - // false. + /// Returns the current size of the WFMO_Reactor's internal + /// descriptor table. virtual size_t size (void) const; - // Returns the current size of the WFMO_Reactor's internal - // descriptor table. + /// Returns a reference to the WFMO_Reactor's internal lock. virtual ACE_Lock &lock (void); - // Returns a reference to the WFMO_Reactor's internal lock. + /// Wake up all threads in WaitForMultipleObjects so that they can + /// reconsult the handle set virtual void wakeup_all_threads (void); - // Wake up all threads in WaitForMultipleObjects so that they can - // reconsult the handle set + /** + * Transfers ownership of the WFMO_Reactor to the <new_owner>. The + * transfer will not complete until all threads are ready (just like + * the handle set). + */ virtual int owner (ACE_thread_t new_owner, ACE_thread_t *old_owner = 0); - // Transfers ownership of the WFMO_Reactor to the <new_owner>. The - // transfer will not complete until all threads are ready (just like - // the handle set). + /// Return the ID of the "owner" thread. virtual int owner (ACE_thread_t *owner); - // Return the ID of the "owner" thread. + /// Get the existing restart value. virtual int restart (void); - // Get the existing restart value. + /// Set a new value for restart and return the original value. virtual int restart (int r); - // Set a new value for restart and return the original value. + /// Not implemented virtual void requeue_position (int); - // Not implemented + /// Not implemented virtual int requeue_position (void); - // Not implemented // = Low-level wait_set mask manipulation methods. + /** + * Modify <masks> of the <event_handler>'s entry in WFMO_Reactor + * depending upon <operation>. <event_handler> must already have + * been registered with WFMO_Reactor. + */ virtual int mask_ops (ACE_Event_Handler *event_handler, ACE_Reactor_Mask masks, int operation); - // Modify <masks> of the <event_handler>'s entry in WFMO_Reactor - // depending upon <operation>. <event_handler> must already have - // been registered with WFMO_Reactor. + /** + * Modify <masks> of the <handle>'s entry in WFMO_Reactor depending + * upon <operation>. <handle> must already have been registered + * with WFMO_Reactor. + */ virtual int mask_ops (ACE_HANDLE handle, ACE_Reactor_Mask masks, int ops); - // Modify <masks> of the <handle>'s entry in WFMO_Reactor depending - // upon <operation>. <handle> must already have been registered - // with WFMO_Reactor. // = Low-level ready_set mask manipulation methods. + /// Not implemented virtual int ready_ops (ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask, int ops); - // Not implemented + /// Not implemented virtual int ready_ops (ACE_HANDLE handle, ACE_Reactor_Mask, int ops); - // Not implemented + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. + /// Dump the state of an object. virtual void dump (void) const; - // Dump the state of an object. protected: + /// Registration workhorse virtual int register_handler_i (ACE_HANDLE event_handle, ACE_HANDLE io_handle, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // Registration workhorse + /// Event handling workhorse virtual int event_handling (ACE_Time_Value *max_wait_time = 0, int alertable = 0); - // Event handling workhorse + /// Bit masking workhorse virtual int mask_ops_i (ACE_HANDLE io_handle, ACE_Reactor_Mask masks, int operation); - // Bit masking workhorse + /// Return the ID of the "owner" thread. Does not do any locking. virtual ACE_thread_t owner_i (void); - // Return the ID of the "owner" thread. Does not do any locking. + /// Check to see if it is ok to enter <::WaitForMultipleObjects>. virtual int ok_to_wait (ACE_Time_Value *max_wait_time, int alertable); - // Check to see if it is ok to enter <::WaitForMultipleObjects>. + /// Wait for timer and I/O events to occur. virtual int wait_for_multiple_events (int timeout, int alertable); - // Wait for timer and I/O events to occur. + /// Check for activity on remaining handles. virtual DWORD poll_remaining_handles (size_t slot); - // Check for activity on remaining handles. + /// Expire timers. Only the owner thread does useful stuff in this + /// function. virtual int expire_timers (void); - // Expire timers. Only the owner thread does useful stuff in this - // function. + /// Dispatches the timers and I/O handlers. virtual int dispatch (int wait_status); - // Dispatches the timers and I/O handlers. + /// Protect against structured exceptions caused by user code when + /// dispatching handles virtual int safe_dispatch (int wait_status); - // Protect against structured exceptions caused by user code when - // dispatching handles + /** + * Dispatches any active handles from handles_[<slot>] to + * handles_[active_handles_] using <WaitForMultipleObjects> to poll + * through our handle set looking for active handles. + */ virtual int dispatch_handles (size_t slot); - // Dispatches any active handles from handles_[<slot>] to - // handles_[active_handles_] using <WaitForMultipleObjects> to poll - // through our handle set looking for active handles. + /// Dispatches a single handler. Returns 0 on success, -1 if the + /// handler was removed. virtual int dispatch_handler (size_t slot, size_t max_handlep1); - // Dispatches a single handler. Returns 0 on success, -1 if the - // handler was removed. + /// Dispatches a single handler. Returns 0 on success, -1 if the + /// handler was removed. virtual int simple_dispatch_handler (int slot, ACE_HANDLE event_handle); - // Dispatches a single handler. Returns 0 on success, -1 if the - // handler was removed. + /// Dispatches a single handler. Returns 0 on success, -1 if the + /// handler was removed. virtual int complex_dispatch_handler (int slot, ACE_HANDLE event_handle); - // Dispatches a single handler. Returns 0 on success, -1 if the - // handler was removed. + /// Dispatches window messages. Noop for WFMO_Reactor. virtual int dispatch_window_messages (void); - // Dispatches window messages. Noop for WFMO_Reactor. virtual ACE_Reactor_Mask upcall (ACE_Event_Handler *event_handler, ACE_HANDLE io_handle, WSANETWORKEVENTS &events); + /// Used to caluculate the next timeout virtual int calculate_timeout (ACE_Time_Value *time); - // Used to caluculate the next timeout + /// Update the state of the handler repository virtual int update_state (void); - // Update the state of the handler repository + /// Check to see if we have a new owner virtual int new_owner (void); - // Check to see if we have a new owner + /// Set owner to new owner virtual int change_owner (void); - // Set owner to new owner + /// Handle signals without requiring global/static variables. ACE_Sig_Handler *signal_handler_; - // Handle signals without requiring global/static variables. + /// Keeps track of whether we should delete the signal handler (if we + /// didn't create it, then we don't delete it). int delete_signal_handler_; - // Keeps track of whether we should delete the signal handler (if we - // didn't create it, then we don't delete it). + /// Defined as a pointer to allow overriding by derived classes... ACE_Timer_Queue *timer_queue_; - // Defined as a pointer to allow overriding by derived classes... + /// Keeps track of whether we should delete the timer queue (if we + /// didn't create it, then we don't delete it). int delete_timer_queue_; - // Keeps track of whether we should delete the timer queue (if we - // didn't create it, then we don't delete it). + /// Keeps track of whether we should delete the handler repository int delete_handler_rep_; - // Keeps track of whether we should delete the handler repository + /// Used when <notify> is called. ACE_Reactor_Notify *notify_handler_; - // Used when <notify> is called. + /// Keeps track of whether we should delete the notify handler. int delete_notify_handler_; - // Keeps track of whether we should delete the notify handler. + /** + * Synchronization for the ACE_WFMO_Reactor. + * + * A Process Mutex is used here because of two reasons: + * (a) The implementation of ACE_Thread_Mutex uses CriticalSections + * CriticalSections are not waitable using ::WaitForMultipleObjects + * (b) This is really not a process mutex because it is not + * named. No other process can use this mutex. + */ ACE_Process_Mutex lock_; - // Synchronization for the ACE_WFMO_Reactor. - // - // A Process Mutex is used here because of two reasons: - // (a) The implementation of ACE_Thread_Mutex uses CriticalSections - // CriticalSections are not waitable using ::WaitForMultipleObjects - // (b) This is really not a process mutex because it is not - // named. No other process can use this mutex. + /// Adapter used to return internal lock to outside world. ACE_Lock_Adapter<ACE_Process_Mutex> lock_adapter_; - // Adapter used to return internal lock to outside world. + /// Table that maps <ACE_HANDLEs> to <ACE_Event_Handler *>'s. ACE_WFMO_Reactor_Handler_Repository handler_rep_; - // Table that maps <ACE_HANDLEs> to <ACE_Event_Handler *>'s. + /// A manual event used to block threads from proceeding into + /// WaitForMultipleObjects ACE_Manual_Event ok_to_wait_; - // A manual event used to block threads from proceeding into - // WaitForMultipleObjects + /** + * A manual event is used so that we can wake everyone up (e.g., + * when <ACE_Event_Handlers> are bounded and unbound from the + * handler repository). + */ ACE_Manual_Event wakeup_all_threads_; - // A manual event is used so that we can wake everyone up (e.g., - // when <ACE_Event_Handlers> are bounded and unbound from the - // handler repository). + /// Used when <wakeup_all_threads_> is signaled ACE_Wakeup_All_Threads_Handler wakeup_all_threads_handler_; - // Used when <wakeup_all_threads_> is signaled + /// The changing thread waits on this event, till all threads are not + /// active anymore ACE_Auto_Event waiting_to_change_state_; - // The changing thread waits on this event, till all threads are not - // active anymore + /// Count of currently active threads size_t active_threads_; - // Count of currently active threads + /** + * The thread which is "owner" of the WFMO_Reactor. The owner + * concept is used because we don't want multiple threads to try to + * expire timers. Therefore the "owner" thread is the only one + * allowed to expire timers. Also, the owner thread is the only + * thread which waits on the notify handle. Note that the ownership + * can be transferred. + */ ACE_thread_t owner_; - // The thread which is "owner" of the WFMO_Reactor. The owner - // concept is used because we don't want multiple threads to try to - // expire timers. Therefore the "owner" thread is the only one - // allowed to expire timers. Also, the owner thread is the only - // thread which waits on the notify handle. Note that the ownership - // can be transferred. + /// The owner to be of the WFMO_Reactor ACE_thread_t new_owner_; - // The owner to be of the WFMO_Reactor + /// This is the thread which is responsible for the changing the + /// state of the <WFMO_Reactor> handle set ACE_thread_t change_state_thread_; - // This is the thread which is responsible for the changing the - // state of the <WFMO_Reactor> handle set + /// This is an array of ACE_HANDLEs which keep track of the <lock_> + /// and <ok_to_wait_> handles ACE_HANDLE atomic_wait_array_ [2]; - // This is an array of ACE_HANDLEs which keep track of the <lock_> - // and <ok_to_wait_> handles + /// This flag is used to keep track of whether we are already closed. int open_for_business_; - // This flag is used to keep track of whether we are already closed. + /// This flag is used to keep track of whether we are actively handling + /// events or not. sig_atomic_t deactivated_; - // This flag is used to keep track of whether we are actively handling - // events or not. private: + /// Deny access since member-wise won't work... ACE_WFMO_Reactor (const ACE_WFMO_Reactor &); ACE_WFMO_Reactor &operator = (const ACE_WFMO_Reactor &); - // Deny access since member-wise won't work... }; #endif /* ACE_WIN32 */ diff --git a/ace/WIN32_Asynch_IO.h b/ace/WIN32_Asynch_IO.h index 11e04507955..dad9f60e418 100644 --- a/ace/WIN32_Asynch_IO.h +++ b/ace/WIN32_Asynch_IO.h @@ -1,31 +1,25 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// -// ace -// -// = FILENAME -// -// WIN32_Asynch_IO.h -// -// = DESCRIPTION -// -// These classes only works on Win32 platforms. -// -// The implementation of <ACE_Asynch_Transmit_File> and -// <ACE_Asynch_Accept> are only supported if ACE_HAS_WINSOCK2 is -// defined or you are on WinNT 4.0 or higher. -// -// = AUTHOR -// -// Irfan Pyarali (irfan@cs.wustl.edu), -// Tim Harrison (harrison@cs.wustl.edu) and -// Alexander Babu Arulanthu <alex@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file WIN32_Asynch_IO.h + * + * $Id$ + * + * + * These classes only works on Win32 platforms. + * + * The implementation of <ACE_Asynch_Transmit_File> and + * <ACE_Asynch_Accept> are only supported if ACE_HAS_WINSOCK2 is + * defined or you are on WinNT 4.0 or higher. + * + * + * @author Irfan Pyarali (irfan@cs.wustl.edu) + * @author Tim Harrison (harrison@cs.wustl.edu) + * @author Alexander Babu Arulanthu <alex@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_WIN32_ASYNCH_IO_H #define ACE_WIN32_ASYNCH_IO_H @@ -44,70 +38,73 @@ // Forward declaration class ACE_WIN32_Proactor; -class ACE_Export ACE_WIN32_Asynch_Result : public virtual ACE_Asynch_Result_Impl, +/** + * @class ACE_WIN32_Asynch_Result + * + * @brief An abstract class which adds information to the OVERLAPPED + * structure to make it more useful. + * + * An abstract base class from which you can obtain some basic + * information like the number of bytes transferred, the ACT + * associated with the asynchronous operation, indication of + * success or failure, etc. Subclasses may want to store more + * information that is particular to the asynchronous operation + * it represents. + */ +class ACE_Export ACE_WIN32_Asynch_Result : public virtual ACE_Asynch_Result_Impl, public OVERLAPPED { - // = TITLE - // - // An abstract class which adds information to the OVERLAPPED - // structure to make it more useful. - // - // = DESCRIPTION - // - // An abstract base class from which you can obtain some basic - // information like the number of bytes transferred, the ACT - // associated with the asynchronous operation, indication of - // success or failure, etc. Subclasses may want to store more - // information that is particular to the asynchronous operation - // it represents. + /// Factory class has special permissions. friend class ACE_WIN32_Asynch_Accept; - // Factory class has special permissions. + /// Proactor class has special permission. friend class ACE_WIN32_Proactor; - // Proactor class has special permission. public: + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This returns the ACT associated with the handle when it was + * registered with the I/O completion port. This ACT is not the + * same as the ACT associated with the asynchronous operation. + */ const void *completion_key (void) const; - // This returns the ACT associated with the handle when it was - // registered with the I/O completion port. This ACT is not the - // same as the ACT associated with the asynchronous operation. + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// Event associated with the OVERLAPPED structure. ACE_HANDLE event (void) const; - // Event associated with the OVERLAPPED structure. + /// This really make sense only when doing file I/O. u_long offset (void) const; - // This really make sense only when doing file I/O. + /// Offset_high associated with the OVERLAPPED structure. u_long offset_high (void) const; - // Offset_high associated with the OVERLAPPED structure. + /// The priority of the asynchronous operation. Currently, this is + /// not supported on Win32. int priority (void) const; - // The priority of the asynchronous operation. Currently, this is - // not supported on Win32. + /// Returns 0. int signal_number (void) const; - // Returns 0. + /// Post <this> to the Proactor's completion port. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor's completion port. + /// Destructor. virtual ~ACE_WIN32_Asynch_Result (void); - // Destructor. protected: + /// Constructor. ACE_WIN32_Asynch_Result (ACE_Handler &handler, const void* act, ACE_HANDLE event, @@ -115,142 +112,146 @@ protected: u_long offset_high, int priority, int signal_number = 0); - // Constructor. + /// Handler that will be called back. ACE_Handler &handler_; - // Handler that will be called back. + /// ACT for this operation. const void *act_; - // ACT for this operation. + /// Bytes transferred by this operation. u_long bytes_transferred_; - // Bytes transferred by this operation. + /// Success indicator. int success_; - // Success indicator. + /// ACT associated with handle. const void *completion_key_; - // ACT associated with handle. + /// Error if operation failed. u_long error_; - // Error if operation failed. }; +/** + * @class ACE_WIN32_Asynch_Operation + * + * @brief This class abstracts out the common things needed for + * implementing Asynch_Operation for WIN32 platform. + * + */ class ACE_Export ACE_WIN32_Asynch_Operation : public virtual ACE_Asynch_Operation_Impl { - // = TITLE - // - // This class abstracts out the common things needed for - // implementing Asynch_Operation for WIN32 platform. - // - // = DESCRIPTION - // public: + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * This cancels all pending accepts operations that were issued by + * the calling thread. The function does not cancel asynchronous + * operations issued by other threads. + */ int cancel (void); - // This cancels all pending accepts operations that were issued by - // the calling thread. The function does not cancel asynchronous - // operations issued by other threads. // = Access methods. + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. protected: + /// Constructor. ACE_WIN32_Asynch_Operation (ACE_WIN32_Proactor *win32_proactor); - // Constructor. + /// Destructor. virtual ~ACE_WIN32_Asynch_Operation (void); - // Destructor. + /// WIn32 Proactor. ACE_WIN32_Proactor *win32_proactor_; - // WIn32 Proactor. + /// Proactor that this asynch IO is registered with. ACE_Proactor *proactor_; - // Proactor that this asynch IO is registered with. + /// Handler that will receive the callback. ACE_Handler *handler_; - // Handler that will receive the callback. + /// I/O handle used for reading. ACE_HANDLE handle_; - // I/O handle used for reading. }; -class ACE_Export ACE_WIN32_Asynch_Read_Stream_Result : public virtual ACE_Asynch_Read_Stream_Result_Impl, +/** + * @class ACE_WIN32_Asynch_Read_Stream_Result + * + * @brief This is class provides concrete implementation for + * ACE_Asynch_Read_Stream::Result class. + */ +class ACE_Export ACE_WIN32_Asynch_Read_Stream_Result : public virtual ACE_Asynch_Read_Stream_Result_Impl, public virtual ACE_WIN32_Asynch_Result { - // = TITLE - // - // This is class provides concrete implementation for - // ACE_Asynch_Read_Stream::Result class. - // - // = DESCRIPTION - // + /// Factory class will have special permissions. friend class ACE_WIN32_Asynch_Read_Stream; - // Factory class will have special permissions. + /// Proactor class has special permission. friend class ACE_WIN32_Proactor; - // Proactor class has special permission. public: + /// The number of bytes which were requested at the start of the + /// asynchronous read. u_long bytes_to_read (void) const; - // The number of bytes which were requested at the start of the - // asynchronous read. + /// Message block which contains the read data. ACE_Message_Block &message_block (void) const; - // Message block which contains the read data. + /// I/O handle used for reading. ACE_HANDLE handle (void) const; - // I/O handle used for reading. // Base class operations. These operations are here to kill // dominance warnings. These methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This returns the ACT associated with the handle when it was + * registered with the I/O completion port. This ACT is not the + * same as the ACT associated with the asynchronous operation. + */ const void *completion_key (void) const; - // This returns the ACT associated with the handle when it was - // registered with the I/O completion port. This ACT is not the - // same as the ACT associated with the asynchronous operation. + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// Event associated with the OVERLAPPED structure. ACE_HANDLE event (void) const; - // Event associated with the OVERLAPPED structure. + /// This really make sense only when doing file I/O. u_long offset (void) const; - // This really make sense only when doing file I/O. + /// Offset_high associated with the OVERLAPPED structure. u_long offset_high (void) const; - // Offset_high associated with the OVERLAPPED structure. + /// The priority of the asynchronous operation. Currently, this is + /// not supported on Win32. int priority (void) const; - // The priority of the asynchronous operation. Currently, this is - // not supported on Win32. + /// No-op. Returns 0. int signal_number (void) const; - // No-op. Returns 0. + /// Post <this> to the Proactor's completion port. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor's completion port. protected: ACE_WIN32_Asynch_Read_Stream_Result (ACE_Handler &handler, @@ -264,149 +265,153 @@ protected: // Constructor is protected since creation is limited to // ACE_Asynch_Read_Stream factory. + /// Proactor will call this method when the read completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // Proactor will call this method when the read completes. + /// Destructor. virtual ~ACE_WIN32_Asynch_Read_Stream_Result (void); - // Destructor. + /// Bytes requested when the asynchronous read was initiated. u_long bytes_to_read_; - // Bytes requested when the asynchronous read was initiated. + /// Message block for reading the data into. ACE_Message_Block &message_block_; - // Message block for reading the data into. + /// I/O handle used for reading. ACE_HANDLE handle_; - // I/O handle used for reading. }; -class ACE_Export ACE_WIN32_Asynch_Read_Stream : public virtual ACE_Asynch_Read_Stream_Impl, +/** + * @class ACE_WIN32_Asynch_Read_Stream + * + * @brief This class is a factory for starting off asynchronous reads + * on a stream. + * + * Once <open> is called, multiple asynchronous <read>s can + * started using this class. An ACE_Asynch_Read_Stream::Result + * will be passed back to the <handler> when the asynchronous + * reads completes through the <ACE_Handler::handle_read_stream> + * callback. + */ +class ACE_Export ACE_WIN32_Asynch_Read_Stream : public virtual ACE_Asynch_Read_Stream_Impl, public ACE_WIN32_Asynch_Operation { - // = TITLE - // - // This class is a factory for starting off asynchronous reads - // on a stream. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <read>s can - // started using this class. An ACE_Asynch_Read_Stream::Result - // will be passed back to the <handler> when the asynchronous - // reads completes through the <ACE_Handler::handle_read_stream> - // callback. public: + /// Constructor. ACE_WIN32_Asynch_Read_Stream (ACE_WIN32_Proactor *win32_proactor); - // Constructor. + /// This starts off an asynchronous read. Upto <bytes_to_read> will + /// be read and stored in the <message_block>. int read (ACE_Message_Block &message_block, u_long bytes_to_read, const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous read. Upto <bytes_to_read> will - // be read and stored in the <message_block>. + /// Destructor. virtual ~ACE_WIN32_Asynch_Read_Stream (void); - // Destructor. // Methods belong to ACE_WIN32_Asynch_Operation base class. These // methods are defined here to avoid VC++ warnings. They route the // call to the ACE_WIN32_Asynch_Operation base class. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * This cancels all pending accepts operations that were issued by + * the calling thread. The function does not cancel asynchronous + * operations issued by other threads. + */ int cancel (void); - // This cancels all pending accepts operations that were issued by - // the calling thread. The function does not cancel asynchronous - // operations issued by other threads. + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. protected: + /// This is the method which does the real work and is there so that + /// the ACE_Asynch_Read_File class can use it too. int shared_read (ACE_WIN32_Asynch_Read_Stream_Result *result); - // This is the method which does the real work and is there so that - // the ACE_Asynch_Read_File class can use it too. }; -class ACE_Export ACE_WIN32_Asynch_Write_Stream_Result : public virtual ACE_Asynch_Write_Stream_Result_Impl, +/** + * @class ACE_WIN32_Asynch_Write_Stream_Result + * + * @brief This is class provides concrete implementation for + * ACE_Asynch_Write_Stream::Result class. + */ +class ACE_Export ACE_WIN32_Asynch_Write_Stream_Result : public virtual ACE_Asynch_Write_Stream_Result_Impl, public ACE_WIN32_Asynch_Result { - // = TITLE - // - // This is class provides concrete implementation for - // ACE_Asynch_Write_Stream::Result class. - // - // = DESCRIPTION - // - + /// Factory class willl have special permissions. friend class ACE_WIN32_Asynch_Write_Stream; - // Factory class willl have special permissions. + /// Proactor class has special permission. friend class ACE_WIN32_Proactor; - // Proactor class has special permission. public: + /// The number of bytes which were requested at the start of the + /// asynchronous write. u_long bytes_to_write (void) const; - // The number of bytes which were requested at the start of the - // asynchronous write. + /// Message block that contains the data to be written. ACE_Message_Block &message_block (void) const; - // Message block that contains the data to be written. + /// I/O handle used for writing. ACE_HANDLE handle (void) const; - // I/O handle used for writing. - // = Base class operations. These operations are here to kill some + // = Base class operations. These operations are here to kill some // warnings. These methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This returns the ACT associated with the handle when it was + * registered with the I/O completion port. This ACT is not the + * same as the ACT associated with the asynchronous operation. + */ const void *completion_key (void) const; - // This returns the ACT associated with the handle when it was - // registered with the I/O completion port. This ACT is not the - // same as the ACT associated with the asynchronous operation. + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// Event associated with the OVERLAPPED structure. ACE_HANDLE event (void) const; - // Event associated with the OVERLAPPED structure. + /// This really make sense only when doing file I/O. u_long offset (void) const; - // This really make sense only when doing file I/O. + /// Offset_high associated with the OVERLAPPED structure. u_long offset_high (void) const; - // Offset_high associated with the OVERLAPPED structure. + /// The priority of the asynchronous operation. Currently, this is + /// not supported on Win32. int priority (void) const; - // The priority of the asynchronous operation. Currently, this is - // not supported on Win32. + /// No-op. Returns 0. int signal_number (void) const; - // No-op. Returns 0. - + + /// Post <this> to the Proactor's completion port. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor's completion port. protected: ACE_WIN32_Asynch_Write_Stream_Result (ACE_Handler &handler, @@ -420,157 +425,161 @@ protected: // Constructor is protected since creation is limited to // ACE_Asynch_Write_Stream factory. + /// ACE_Proactor will call this method when the write completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // ACE_Proactor will call this method when the write completes. + /// Destructor. virtual ~ACE_WIN32_Asynch_Write_Stream_Result (void); - // Destructor. + /// The number of bytes which were requested at the start of the + /// asynchronous write. u_long bytes_to_write_; - // The number of bytes which were requested at the start of the - // asynchronous write. + /// Message block that contains the data to be written. ACE_Message_Block &message_block_; - // Message block that contains the data to be written. + /// I/O handle used for writing. ACE_HANDLE handle_; - // I/O handle used for writing. }; -class ACE_Export ACE_WIN32_Asynch_Write_Stream : public virtual ACE_Asynch_Write_Stream_Impl, +/** + * @class ACE_WIN32_Asynch_Write_Stream + * + * @brief This class is a factory for starting off asynchronous writes + * on a stream. + * + * + * Once <open> is called, multiple asynchronous <writes>s can + * started using this class. A ACE_Asynch_Write_Stream::Result + * will be passed back to the <handler> when the asynchronous + * write completes through the + * <ACE_Handler::handle_write_stream> callback. + */ +class ACE_Export ACE_WIN32_Asynch_Write_Stream : public virtual ACE_Asynch_Write_Stream_Impl, public ACE_WIN32_Asynch_Operation { - // = TITLE - // - // This class is a factory for starting off asynchronous writes - // on a stream. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <writes>s can - // started using this class. A ACE_Asynch_Write_Stream::Result - // will be passed back to the <handler> when the asynchronous - // write completes through the - // <ACE_Handler::handle_write_stream> callback. - public: + /// Constructor. ACE_WIN32_Asynch_Write_Stream (ACE_WIN32_Proactor *win32_proactor); - // Constructor. + /// This starts off an asynchronous write. Upto <bytes_to_write> + /// will be written from the <message_block>. int write (ACE_Message_Block &message_block, u_long bytes_to_write, const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous write. Upto <bytes_to_write> - // will be written from the <message_block>. + /// Destructor. virtual ~ACE_WIN32_Asynch_Write_Stream (void); - // Destructor. - // = Methods belonging to <ACE_WIN32_Asynch_Operation> base class. + // = Methods belonging to <ACE_WIN32_Asynch_Operation> base class. // These methods are defined here to avoid VC++ warnings. They route // the call to the <ACE_WIN32_Asynch_Operation> base class. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * This cancels all pending accepts operations that were issued by + * the calling thread. The function does not cancel asynchronous + * operations issued by other threads. + */ int cancel (void); - // This cancels all pending accepts operations that were issued by - // the calling thread. The function does not cancel asynchronous - // operations issued by other threads. + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. protected: + /// This is the method which does the real work and is there so that + /// the ACE_Asynch_Write_File class can use it too. int shared_write (ACE_WIN32_Asynch_Write_Stream_Result *result); - // This is the method which does the real work and is there so that - // the ACE_Asynch_Write_File class can use it too. }; -class ACE_Export ACE_WIN32_Asynch_Read_File_Result : public virtual ACE_Asynch_Read_File_Result_Impl, +/** + * @class ACE_WIN32_Asynch_Read_File_Result + * + * @brief This is class provides concrete implementation for + * ACE_Asynch_Read_File::Result class. + */ +class ACE_Export ACE_WIN32_Asynch_Read_File_Result : public virtual ACE_Asynch_Read_File_Result_Impl, public ACE_WIN32_Asynch_Read_Stream_Result { - // = TITLE - // - // This is class provides concrete implementation for - // ACE_Asynch_Read_File::Result class. - // - // = DESCRIPTION - // - + /// Factory class will have special permissions. friend class ACE_WIN32_Asynch_Read_File; - // Factory class will have special permissions. + /// Proactor class has special permission. friend class ACE_WIN32_Proactor; - // Proactor class has special permission. public: // = These methods belong to ACE_WIN32_Asynch_Result class base - // class. These operations are here to kill some warnings. These + // class. These operations are here to kill some warnings. These // methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This returns the ACT associated with the handle when it was + * registered with the I/O completion port. This ACT is not the + * same as the ACT associated with the asynchronous operation. + */ const void *completion_key (void) const; - // This returns the ACT associated with the handle when it was - // registered with the I/O completion port. This ACT is not the - // same as the ACT associated with the asynchronous operation. + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// Event associated with the OVERLAPPED structure. ACE_HANDLE event (void) const; - // Event associated with the OVERLAPPED structure. + /// This really make sense only when doing file I/O. u_long offset (void) const; - // This really make sense only when doing file I/O. + /// Offset_high associated with the OVERLAPPED structure. u_long offset_high (void) const; - // Offset_high associated with the OVERLAPPED structure. + /// The priority of the asynchronous operation. Currently, this is + /// not supported on Win32. int priority (void) const; - // The priority of the asynchronous operation. Currently, this is - // not supported on Win32. + /// No-op. Returns 0. int signal_number (void) const; - // No-op. Returns 0. - + // The following methods belong to // ACE_WIN32_Asynch_Read_Stream_Result. They are here to avoid VC++ // dominance warnings. These methods route their call to the // ACE_WIN32_Asynch_Read_Stream_Result base class. + /// The number of bytes which were requested at the start of the + /// asynchronous read. u_long bytes_to_read (void) const; - // The number of bytes which were requested at the start of the - // asynchronous read. + /// Message block which contains the read data. ACE_Message_Block &message_block (void) const; - // Message block which contains the read data. + /// I/O handle used for reading. ACE_HANDLE handle (void) const; - // I/O handle used for reading. + /// Post <this> to the Proactor's completion port. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor's completion port. protected: ACE_WIN32_Asynch_Read_File_Result (ACE_Handler &handler, @@ -586,39 +595,44 @@ protected: // Constructor is protected since creation is limited to // ACE_Asynch_Read_File factory. + /// ACE_Proactor will call this method when the read completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // ACE_Proactor will call this method when the read completes. + /// Destructor. virtual ~ACE_WIN32_Asynch_Read_File_Result (void); - // Destructor. }; -class ACE_Export ACE_WIN32_Asynch_Read_File : public virtual ACE_Asynch_Read_File_Impl, +/** + * @class ACE_WIN32_Asynch_Read_File + * + * @brief This class is a factory for starting off asynchronous reads + * on a file. + * + * Once <open> is called, multiple asynchronous <read>s can + * started using this class. A ACE_Asynch_Read_File::Result + * will be passed back to the <handler> when the asynchronous + * reads completes through the <ACE_Handler::handle_read_file> + * callback. + * + * This class differs slightly from ACE_Asynch_Read_Stream as it + * allows the user to specify an offset for the read. + */ +class ACE_Export ACE_WIN32_Asynch_Read_File : public virtual ACE_Asynch_Read_File_Impl, public ACE_WIN32_Asynch_Read_Stream { - // = TITLE - // - // This class is a factory for starting off asynchronous reads - // on a file. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <read>s can - // started using this class. A ACE_Asynch_Read_File::Result - // will be passed back to the <handler> when the asynchronous - // reads completes through the <ACE_Handler::handle_read_file> - // callback. - // - // This class differs slightly from ACE_Asynch_Read_Stream as it - // allows the user to specify an offset for the read. public: + /// Constructor. ACE_WIN32_Asynch_Read_File (ACE_WIN32_Proactor *win32_proactor); - // Constructor. + /** + * This starts off an asynchronous read. Upto <bytes_to_read> will + * be read and stored in the <message_block>. The read will start + * at <offset> from the beginning of the file. + */ int read (ACE_Message_Block &message_block, u_long bytes_to_read, u_long offset, @@ -626,126 +640,130 @@ public: const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous read. Upto <bytes_to_read> will - // be read and stored in the <message_block>. The read will start - // at <offset> from the beginning of the file. + /// Destructor. virtual ~ACE_WIN32_Asynch_Read_File (void); - // Destructor. - // = Methods belong to ACE_WIN32_Asynch_Operation base class. These - // methods are defined here to avoid VC++ warnings. They route the + // = Methods belong to ACE_WIN32_Asynch_Operation base class. These + // methods are defined here to avoid VC++ warnings. They route the // call to the ACE_WIN32_Asynch_Operation base class. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * This cancels all pending accepts operations that were issued by + * the calling thread. The function does not cancel asynchronous + * operations issued by other threads. + */ int cancel (void); - // This cancels all pending accepts operations that were issued by - // the calling thread. The function does not cancel asynchronous - // operations issued by other threads. + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. private: + /** + * This method belongs to ACE_WIN32_Asynch_Read_Stream. It is here + * to avoid the compiler warnings. We forward this call to the + * ACE_WIN32_Asynch_Read_Stream class. + */ int read (ACE_Message_Block &message_block, u_long bytes_to_read, const void *act, int priority, int signal_number = 0); - // This method belongs to ACE_WIN32_Asynch_Read_Stream. It is here - // to avoid the compiler warnings. We forward this call to the - // ACE_WIN32_Asynch_Read_Stream class. }; -class ACE_Export ACE_WIN32_Asynch_Write_File_Result : public virtual ACE_Asynch_Write_File_Result_Impl, +/** + * @class ACE_WIN32_Asynch_Write_File_Result + * + * @brief This class provides implementation for + * ACE_Asynch_Write_File_Result for WIN32 platforms. + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous write. + * + * This class differs slightly from + * ACE_Asynch_Write_Stream::Result as it calls back + * <ACE_Handler::handle_write_file> on the <handler> instead + * of <ACE_Handler::handle_write_stream>. No additional state + * is required by this class as ACE_Asynch_Result can store + * the <offset>. + */ +class ACE_Export ACE_WIN32_Asynch_Write_File_Result : public virtual ACE_Asynch_Write_File_Result_Impl, public ACE_WIN32_Asynch_Write_Stream_Result { - // = TITLE - // - // This class provides implementation for - // ACE_Asynch_Write_File_Result for WIN32 platforms. - // - // = DESCRIPTION - // - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous write. - // - // This class differs slightly from - // ACE_Asynch_Write_Stream::Result as it calls back - // <ACE_Handler::handle_write_file> on the <handler> instead - // of <ACE_Handler::handle_write_stream>. No additional state - // is required by this class as ACE_Asynch_Result can store - // the <offset>. - + /// Factory class will have special permission. friend class ACE_WIN32_Asynch_Write_File; - // Factory class will have special permission. + /// Proactor class has special permission. friend class ACE_WIN32_Proactor; - // Proactor class has special permission. public: // = Base class operations. These operations are here to kill some // warnings. These methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This returns the ACT associated with the handle when it was + * registered with the I/O completion port. This ACT is not the + * same as the ACT associated with the asynchronous operation. + */ const void *completion_key (void) const; - // This returns the ACT associated with the handle when it was - // registered with the I/O completion port. This ACT is not the - // same as the ACT associated with the asynchronous operation. + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// Event associated with the OVERLAPPED structure. ACE_HANDLE event (void) const; - // Event associated with the OVERLAPPED structure. + /// This really make sense only when doing file I/O. u_long offset (void) const; - // This really make sense only when doing file I/O. + /// Offset_high associated with the OVERLAPPED structure. u_long offset_high (void) const; - // Offset_high associated with the OVERLAPPED structure. + /// The priority of the asynchronous operation. Currently, this is + /// not supported on Win32. int priority (void) const; - // The priority of the asynchronous operation. Currently, this is - // not supported on Win32. + /// No-op. Returns 0. int signal_number (void) const; - // No-op. Returns 0. - + // The following methods belong to // ACE_WIN32_Asynch_Read_Stream_Result. They are here to avoid VC++ // warnings. These methods route their call to the // ACE_WIN32_Asynch_Read_Stream_Result base class. + /// The number of bytes which were requested at the start of the + /// asynchronous write. u_long bytes_to_write (void) const; - // The number of bytes which were requested at the start of the - // asynchronous write. + /// Message block that contains the data to be written. ACE_Message_Block &message_block (void) const; - // Message block that contains the data to be written. + /// I/O handle used for writing. ACE_HANDLE handle (void) const; - // I/O handle used for writing. + /// Post <this> to the Proactor's completion port. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor's completion port. protected: ACE_WIN32_Asynch_Write_File_Result (ACE_Handler &handler, @@ -761,36 +779,40 @@ protected: // Constructor is protected since creation is limited to // ACE_Asynch_Write_File factory. + /// ACE_Proactor will call this method when the write completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // ACE_Proactor will call this method when the write completes. + /// Destructor. virtual ~ACE_WIN32_Asynch_Write_File_Result (void); - // Destructor. }; -class ACE_Export ACE_WIN32_Asynch_Write_File : public virtual ACE_Asynch_Write_File_Impl, +/** + * @class ACE_WIN32_Asynch_Write_File + * + * @brief This class is a factory for starting off asynchronous writes + * on a file. + * + * Once <open> is called, multiple asynchronous <write>s can be + * started using this class. A ACE_Asynch_Write_File::Result + * will be passed back to the <handler> when the asynchronous + * writes completes through the <ACE_Handler::handle_write_file> + * callback. + */ +class ACE_Export ACE_WIN32_Asynch_Write_File : public virtual ACE_Asynch_Write_File_Impl, public ACE_WIN32_Asynch_Write_Stream { - // = TITLE - // - // This class is a factory for starting off asynchronous writes - // on a file. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <write>s can be - // started using this class. A ACE_Asynch_Write_File::Result - // will be passed back to the <handler> when the asynchronous - // writes completes through the <ACE_Handler::handle_write_file> - // callback. - public: + /// Constructor. ACE_WIN32_Asynch_Write_File (ACE_WIN32_Proactor *win32_proactor); - // Constructor. + /** + * This starts off an asynchronous write. Upto <bytes_to_write> + * will be write and stored in the <message_block>. The write will + * start at <offset> from the beginning of the file. + */ int write (ACE_Message_Block &message_block, u_long bytes_to_write, u_long offset, @@ -798,117 +820,121 @@ public: const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous write. Upto <bytes_to_write> - // will be write and stored in the <message_block>. The write will - // start at <offset> from the beginning of the file. + /// Destrcutor. virtual ~ACE_WIN32_Asynch_Write_File (void); - // Destrcutor. - // = Methods belong to ACE_WIN32_Asynch_Operation base class. These - // methods are defined here to avoid VC++ warnings. They route the + // = Methods belong to ACE_WIN32_Asynch_Operation base class. These + // methods are defined here to avoid VC++ warnings. They route the // call to the ACE_WIN32_Asynch_Operation base class. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * This cancels all pending accepts operations that were issued by + * the calling thread. The function does not cancel asynchronous + * operations issued by other threads. + */ int cancel (void); - // This cancels all pending accepts operations that were issued by - // the calling thread. The function does not cancel asynchronous - // operations issued by other threads. + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. private: + /** + * This method belongs to ACE_WIN32_Asynch_Write_Stream. It is here + * to avoid compiler warnings. This method is forwarded to the + * ACE_WIN32_Asynch_Write_Stream class. + */ int write (ACE_Message_Block &message_block, u_long bytes_to_write, const void *act, int priority, int signal_number = 0); - // This method belongs to ACE_WIN32_Asynch_Write_Stream. It is here - // to avoid compiler warnings. This method is forwarded to the - // ACE_WIN32_Asynch_Write_Stream class. }; -class ACE_Export ACE_WIN32_Asynch_Accept_Result : public virtual ACE_Asynch_Accept_Result_Impl, +/** + * @class ACE_WIN32_Asynch_Accept_Result + * + * @brief This class implements ACE_Asynch_Accept::Result for WIN32 + * platform. + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous accept. + */ +class ACE_Export ACE_WIN32_Asynch_Accept_Result : public virtual ACE_Asynch_Accept_Result_Impl, public ACE_WIN32_Asynch_Result { - // = TITLE - // - // This class implements ACE_Asynch_Accept::Result for WIN32 - // platform. - // - // = DESCRIPTION - // - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous accept. - + /// Factory will have special permission. friend class ACE_WIN32_Asynch_Accept; - // Factory will have special permission. + /// Proactor class has special permission. friend class ACE_WIN32_Proactor; - // Proactor class has special permission. public: + /// The number of bytes which were requested at the start of the + /// asynchronous accept. u_long bytes_to_read (void) const; - // The number of bytes which were requested at the start of the - // asynchronous accept. + /// Message block which contains the read data. ACE_Message_Block &message_block (void) const; - // Message block which contains the read data. + /// I/O handle used for accepting new connections. ACE_HANDLE listen_handle (void) const; - // I/O handle used for accepting new connections. + /// I/O handle for the new connection. ACE_HANDLE accept_handle (void) const; - // I/O handle for the new connection. - // = Base class operations. These operations are here to kill some - // warnings. These methods call the base class methods. + // = Base class operations. These operations are here to kill some + // warnings. These methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This returns the ACT associated with the handle when it was + * registered with the I/O completion port. This ACT is not the + * same as the ACT associated with the asynchronous operation. + */ const void *completion_key (void) const; - // This returns the ACT associated with the handle when it was - // registered with the I/O completion port. This ACT is not the - // same as the ACT associated with the asynchronous operation. + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// Event associated with the OVERLAPPED structure. ACE_HANDLE event (void) const; - // Event associated with the OVERLAPPED structure. + /// This really make sense only when doing file I/O. u_long offset (void) const; - // This really make sense only when doing file I/O. + /// Offset_high associated with the OVERLAPPED structure. u_long offset_high (void) const; - // Offset_high associated with the OVERLAPPED structure. + /// The priority of the asynchronous operation. Currently, this is + /// not supported on Win32. int priority (void) const; - // The priority of the asynchronous operation. Currently, this is - // not supported on Win32. + /// No-op. Returns 0. int signal_number (void) const; - // No-op. Returns 0. - + + /// Post <this> to the Proactor's completion port. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor's completion port. protected: ACE_WIN32_Asynch_Accept_Result (ACE_Handler &handler, @@ -923,168 +949,175 @@ protected: // Constructor is protected since creation is limited to // ACE_Asynch_Accept factory. + /// ACE_Proactor will call this method when the accept completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // ACE_Proactor will call this method when the accept completes. + /// Destructor. virtual ~ACE_WIN32_Asynch_Accept_Result (void); - // Destructor. + /// Bytes requested when the asynchronous read was initiated. u_long bytes_to_read_; - // Bytes requested when the asynchronous read was initiated. + /// Message block for reading the data into. ACE_Message_Block &message_block_; - // Message block for reading the data into. + /// I/O handle used for accepting new connections. ACE_HANDLE listen_handle_; - // I/O handle used for accepting new connections. + /// I/O handle for the new connection. ACE_HANDLE accept_handle_; - // I/O handle for the new connection. }; -class ACE_Export ACE_WIN32_Asynch_Accept : public virtual ACE_Asynch_Accept_Impl, +/** + * @class ACE_WIN32_Asynch_Accept + * + * @brief This class is a factory for starting off asynchronous accepts + * on a listen handle. + * + * Once <open> is called, multiple asynchronous <accept>s can + * started using this class. A ACE_Asynch_Accept::Result will + * be passed back to the <handler> when the asynchronous accept + * completes through the <ACE_Handler::handle_accept> + * callback. + */ +class ACE_Export ACE_WIN32_Asynch_Accept : public virtual ACE_Asynch_Accept_Impl, public ACE_WIN32_Asynch_Operation { - // = TITLE - // - // This class is a factory for starting off asynchronous accepts - // on a listen handle. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <accept>s can - // started using this class. A ACE_Asynch_Accept::Result will - // be passed back to the <handler> when the asynchronous accept - // completes through the <ACE_Handler::handle_accept> - // callback. - public: + /// Constructor. ACE_WIN32_Asynch_Accept (ACE_WIN32_Proactor *win32_proactor); - // Constructor. + /** + * This starts off an asynchronous accept. The asynchronous accept + * call also allows any initial data to be returned to the + * <handler>. Upto <bytes_to_read> will be read and stored in the + * <message_block>. The <accept_handle> will be used for the + * <accept> call. If (<accept_handle> == INVALID_HANDLE), a new + * handle will be created. + * + * <message_block> must be specified. This is because the address of + * the new connection is placed at the end of this buffer. + */ int accept (ACE_Message_Block &message_block, u_long bytes_to_read, ACE_HANDLE accept_handle, const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous accept. The asynchronous accept - // call also allows any initial data to be returned to the - // <handler>. Upto <bytes_to_read> will be read and stored in the - // <message_block>. The <accept_handle> will be used for the - // <accept> call. If (<accept_handle> == INVALID_HANDLE), a new - // handle will be created. - // - // <message_block> must be specified. This is because the address of - // the new connection is placed at the end of this buffer. + /// Destructor. ~ACE_WIN32_Asynch_Accept (void); - // Destructor. // Methods belong to ACE_WIN32_Asynch_Operation base class. These // methods are defined here to avoid VC++ warnings. They route the // call to the ACE_WIN32_Asynch_Operation base class. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * This cancels all pending accepts operations that were issued by + * the calling thread. The function does not cancel asynchronous + * operations issued by other threads. + */ int cancel (void); - // This cancels all pending accepts operations that were issued by - // the calling thread. The function does not cancel asynchronous - // operations issued by other threads. + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. }; -class ACE_Export ACE_WIN32_Asynch_Transmit_File_Result : public virtual ACE_Asynch_Transmit_File_Result_Impl, +/** + * @class ACE_WIN32_Asynch_Transmit_File_Result + * + * + * @brief This class implements ACE_Asynch_Transmit_File::Result for + * WIN32 platforms. + * + * This class has all the information necessary for the + * <handler> to uniquiely identify the completion of the + * asynchronous transmit file. + */ +class ACE_Export ACE_WIN32_Asynch_Transmit_File_Result : public virtual ACE_Asynch_Transmit_File_Result_Impl, public ACE_WIN32_Asynch_Result { - // = TITLE - // - // This class implements ACE_Asynch_Transmit_File::Result for - // WIN32 platforms. - // - // = DESCRIPTION - // - // This class has all the information necessary for the - // <handler> to uniquiely identify the completion of the - // asynchronous transmit file. - + /// Factory class will have special permission. friend class ACE_WIN32_Asynch_Transmit_File; - // Factory class will have special permission. + /// Proactor class has special permission. friend class ACE_WIN32_Proactor; - // Proactor class has special permission. public: + /// Socket used for transmitting the file. ACE_HANDLE socket (void) const; - // Socket used for transmitting the file. + /// File from which the data is read. ACE_HANDLE file (void) const; - // File from which the data is read. + /// Header and trailer data associated with this transmit file. ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer (void) const; - // Header and trailer data associated with this transmit file. + /// The number of bytes which were requested at the start of the + /// asynchronous transmit file. u_long bytes_to_write (void) const; - // The number of bytes which were requested at the start of the - // asynchronous transmit file. + /// Number of bytes per send requested at the start of the transmit + /// file. u_long bytes_per_send (void) const; - // Number of bytes per send requested at the start of the transmit - // file. + /// Flags which were passed into transmit file. u_long flags (void) const; - // Flags which were passed into transmit file. // Base class operations. These operations are here to kill some // warnings. These methods call the base class methods. + /// Number of bytes transferred by the operation. u_long bytes_transferred (void) const; - // Number of bytes transferred by the operation. + /// ACT associated with the operation. const void *act (void) const; - // ACT associated with the operation. + /// Did the operation succeed? int success (void) const; - // Did the operation succeed? + /** + * This returns the ACT associated with the handle when it was + * registered with the I/O completion port. This ACT is not the + * same as the ACT associated with the asynchronous operation. + */ const void *completion_key (void) const; - // This returns the ACT associated with the handle when it was - // registered with the I/O completion port. This ACT is not the - // same as the ACT associated with the asynchronous operation. + /// Error value if the operation fail. u_long error (void) const; - // Error value if the operation fail. + /// Event associated with the OVERLAPPED structure. ACE_HANDLE event (void) const; - // Event associated with the OVERLAPPED structure. + /// This really make sense only when doing file I/O. u_long offset (void) const; - // This really make sense only when doing file I/O. + /// Offset_high associated with the OVERLAPPED structure. u_long offset_high (void) const; - // Offset_high associated with the OVERLAPPED structure. + /// The priority of the asynchronous operation. Currently, this is + /// not supported on Win32. int priority (void) const; - // The priority of the asynchronous operation. Currently, this is - // not supported on Win32. + /// No-op. Returns 0. int signal_number (void) const; - // No-op. Returns 0. - + + /// Post <this> to the Proactor's completion port. int post_completion (ACE_Proactor_Impl *proactor); - // Post <this> to the Proactor's completion port. protected: ACE_WIN32_Asynch_Transmit_File_Result (ACE_Handler &handler, @@ -1103,63 +1136,73 @@ protected: // Constructor is protected since creation is limited to // ACE_Asynch_Transmit_File factory. + /// Proactor will call this method when the write completes. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error); - // Proactor will call this method when the write completes. + /// Destructor. virtual ~ACE_WIN32_Asynch_Transmit_File_Result (void); - // Destructor. + /// Network I/O handle. ACE_HANDLE socket_; - // Network I/O handle. + /// File I/O handle. ACE_HANDLE file_; - // File I/O handle. + /// Header and trailer data associated with this transmit file. ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer_; - // Header and trailer data associated with this transmit file. + /// The number of bytes which were requested at the start of the + /// asynchronous transmit file. u_long bytes_to_write_; - // The number of bytes which were requested at the start of the - // asynchronous transmit file. + /// Number of bytes per send requested at the start of the transmit + /// file. u_long bytes_per_send_; - // Number of bytes per send requested at the start of the transmit - // file. + /// Flags which were passed into transmit file. u_long flags_; - // Flags which were passed into transmit file. }; -class ACE_Export ACE_WIN32_Asynch_Transmit_File : public virtual ACE_Asynch_Transmit_File_Impl, +/** + * @class ACE_WIN32_Asynch_Transmit_File + * + * @brief This class is a factory for starting off asynchronous + * transmit files on a stream. + * + * Once <open> is called, multiple asynchronous <transmit_file>s + * can started using this class. A + * ACE_Asynch_Transmit_File::Result will be passed back to the + * <handler> when the asynchronous transmit file completes + * through the <ACE_Handler::handle_transmit_file> callback. + * + * The transmit_file function transmits file data over a + * connected network connection. The function uses the operating + * system's cache manager to retrieve the file data. This + * function provides high-performance file data transfer over + * network connections. This function would be of great use in + * a Web Server, Image Server, etc. + */ +class ACE_Export ACE_WIN32_Asynch_Transmit_File : public virtual ACE_Asynch_Transmit_File_Impl, public ACE_WIN32_Asynch_Operation { - // = TITLE - // - // This class is a factory for starting off asynchronous - // transmit files on a stream. - // - // = DESCRIPTION - // - // Once <open> is called, multiple asynchronous <transmit_file>s - // can started using this class. A - // ACE_Asynch_Transmit_File::Result will be passed back to the - // <handler> when the asynchronous transmit file completes - // through the <ACE_Handler::handle_transmit_file> callback. - // - // The transmit_file function transmits file data over a - // connected network connection. The function uses the operating - // system's cache manager to retrieve the file data. This - // function provides high-performance file data transfer over - // network connections. This function would be of great use in - // a Web Server, Image Server, etc. - public: + /// Constructor. ACE_WIN32_Asynch_Transmit_File (ACE_WIN32_Proactor *win32_proactor); - // Constructor. + /** + * This starts off an asynchronous transmit file. The <file> is a + * handle to an open file. <header_and_trailer> is a pointer to a + * data structure that contains pointers to data to send before and + * after the file data is sent. Set this parameter to 0 if you only + * want to transmit the file data. Upto <bytes_to_write> will be + * written to the <socket>. If you want to send the entire file, + * let <bytes_to_write> = 0. <bytes_per_send> is the size of each + * block of data sent per send operation. Please read the Win32 + * documentation on what the flags should be. + */ int transmit_file (ACE_HANDLE file, ACE_Asynch_Transmit_File::Header_And_Trailer *header_and_trailer, u_long bytes_to_write, @@ -1170,39 +1213,34 @@ public: const void *act, int priority, int signal_number = 0); - // This starts off an asynchronous transmit file. The <file> is a - // handle to an open file. <header_and_trailer> is a pointer to a - // data structure that contains pointers to data to send before and - // after the file data is sent. Set this parameter to 0 if you only - // want to transmit the file data. Upto <bytes_to_write> will be - // written to the <socket>. If you want to send the entire file, - // let <bytes_to_write> = 0. <bytes_per_send> is the size of each - // block of data sent per send operation. Please read the Win32 - // documentation on what the flags should be. + /// Destructor. ~ACE_WIN32_Asynch_Transmit_File (void); - // Destructor. // Methods belong to ACE_WIN32_Asynch_Operation base class. These // methods are defined here to avoid VC++ warnings. They route the // call to the ACE_WIN32_Asynch_Operation base class. + /** + * Initializes the factory with information which will be used with + * each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), + * <ACE_Handler::handle> will be called on the <handler> to get the + * correct handle. + */ int open (ACE_Handler &handler, ACE_HANDLE handle, const void *completion_key, ACE_Proactor *proactor); - // Initializes the factory with information which will be used with - // each asynchronous call. If (<handle> == ACE_INVALID_HANDLE), - // <ACE_Handler::handle> will be called on the <handler> to get the - // correct handle. + /** + * This cancels all pending accepts operations that were issued by + * the calling thread. The function does not cancel asynchronous + * operations issued by other threads. + */ int cancel (void); - // This cancels all pending accepts operations that were issued by - // the calling thread. The function does not cancel asynchronous - // operations issued by other threads. + /// Return the underlying proactor. ACE_Proactor* proactor (void) const; - // Return the underlying proactor. }; #endif /* ACE_WIN32 && !ACE_HAS_WINCE */ diff --git a/ace/WIN32_Proactor.h b/ace/WIN32_Proactor.h index 5170f5129cf..fb20563c04e 100644 --- a/ace/WIN32_Proactor.h +++ b/ace/WIN32_Proactor.h @@ -1,20 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// WIN_Proactor.h -// -// = AUTHOR -// Irfan Pyarali (irfan@cs.wustl.edu), -// Tim Harrison (harrison@cs.wustl.edu) and -// Alexander Babu Arulanthu <alex@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file WIN_Proactor.h + * + * $Id$ + * + * @author Irfan Pyarali (irfan@cs.wustl.edu) + * @author Tim Harrison (harrison@cs.wustl.edu) + * @author Alexander Babu Arulanthu <alex@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_WIN32_PROACTOR_H #define ACE_WIN32_PROACTOR_H @@ -33,64 +30,72 @@ class ACE_WIN32_Asynch_Result; class ACE_WIN32_Proactor_Timer_Handler; +/** + * @class ACE_WIN32_Proactor + * + * @brief A manager for asynchronous event demultiplexing. + * + * See the Proactor pattern description at + * http://www.cs.wustl.edu/~schmidt/proactor.ps.gz for more + * details. + */ class ACE_Export ACE_WIN32_Proactor : public ACE_Proactor_Impl { - // = TITLE - // A manager for asynchronous event demultiplexing. - // - // = DESCRIPTION - // See the Proactor pattern description at - // http://www.cs.wustl.edu/~schmidt/proactor.ps.gz for more - // details. public: + /// A do nothing constructor. ACE_WIN32_Proactor (size_t number_of_threads = 0, int used_with_reactor_event_loop = 0); - // A do nothing constructor. + /// Virtual destruction. virtual ~ACE_WIN32_Proactor (void); - // Virtual destruction. + /// Close the IO completion port. virtual int close (void); - // Close the IO completion port. + /// This method adds the <handle> to the I/O completion port. This + /// function is a no-op function for Unix systems. virtual int register_handle (ACE_HANDLE handle, const void *completion_key); - // This method adds the <handle> to the I/O completion port. This - // function is a no-op function for Unix systems. + /** + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (ACE_Time_Value &wait_time); - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. + /** + * Block indefinitely until at least one event is dispatched. + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (void); - // Block indefinitely until at least one event is dispatched. - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. + /** + * Post a result to the completion port of the Proactor. If errors + * occur, the result will be deleted by this method. If successful, + * the result will be deleted by the Proactor when the result is + * removed from the completion port. Therefore, the result should + * have been dynamically allocated and should be orphaned by the + * user once this method is called. + */ virtual int post_completion (ACE_WIN32_Asynch_Result *result); - // Post a result to the completion port of the Proactor. If errors - // occur, the result will be deleted by this method. If successful, - // the result will be deleted by the Proactor when the result is - // removed from the completion port. Therefore, the result should - // have been dynamically allocated and should be orphaned by the - // user once this method is called. + /// Add wakeup dispatch threads (reinit). int wake_up_dispatch_threads (void); - // Add wakeup dispatch threads (reinit). + /// Close all dispatch threads. int close_dispatch_threads (int wait); - // Close all dispatch threads. + /// Number of thread used as a parameter to CreatIoCompletionPort. size_t number_of_threads (void) const; void number_of_threads (size_t threads); - // Number of thread used as a parameter to CreatIoCompletionPort. + /// Get the event handle. virtual ACE_HANDLE get_handle (void) const; - // Get the event handle. virtual ACE_Asynch_Read_Stream_Impl *create_asynch_read_stream (void); @@ -170,93 +175,100 @@ public: ACE_HANDLE event, int priority, int signal_number = 0); - + + /// Create a timer result object which can be used with the Timer + /// mechanism of the Proactor. virtual ACE_Asynch_Result_Impl *create_asynch_timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &tv, ACE_HANDLE event, int priority, int signal_number = 0); - // Create a timer result object which can be used with the Timer - // mechanism of the Proactor. protected: + /// Called when object is signaled by OS (either via UNIX signals or + /// when a Win32 object becomes signaled). virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0); - // Called when object is signaled by OS (either via UNIX signals or - // when a Win32 object becomes signaled). + /// Called when object is removed from the ACE_Reactor. virtual int handle_close (ACE_HANDLE handle, ACE_Reactor_Mask close_mask); - // Called when object is removed from the ACE_Reactor. + /** + * Dispatch a single set of events. If <milli_seconds> elapses + * before any events occur, return 0. Return 1 if a completion is + * dispatched. Return -1 on errors. + */ virtual int handle_events (unsigned long milli_seconds); - // Dispatch a single set of events. If <milli_seconds> elapses - // before any events occur, return 0. Return 1 if a completion is - // dispatched. Return -1 on errors. + /// Protect against structured exceptions caused by user code when + /// dispatching handles. void application_specific_code (ACE_WIN32_Asynch_Result *asynch_result, u_long bytes_transferred, int success, const void *completion_key, u_long error); - // Protect against structured exceptions caused by user code when - // dispatching handles. + /** + * Post <how_many> completions to the completion port so that all + * threads can wake up. This is used in conjunction with the + * <run_event_loop>. + */ virtual int post_wakeup_completions (int how_many); - // Post <how_many> completions to the completion port so that all - // threads can wake up. This is used in conjunction with the - // <run_event_loop>. + /// Handle for the completion port. Unix doesnt have completion + /// ports. ACE_HANDLE completion_port_; - // Handle for the completion port. Unix doesnt have completion - // ports. + /// This number is passed to the <CreatIOCompletionPort> system + /// call. size_t number_of_threads_; - // This number is passed to the <CreatIOCompletionPort> system - // call. + /// This event is used in conjunction with Reactor when we try to + /// integrate the event loops of Reactor and the Proactor. ACE_Auto_Event event_; - // This event is used in conjunction with Reactor when we try to - // integrate the event loops of Reactor and the Proactor. + /// Flag that indicates whether we are used in conjunction with + /// Reactor. int used_with_reactor_event_loop_; - // Flag that indicates whether we are used in conjunction with - // Reactor. - + + /// Handler to handle the wakeups. This works in conjunction with the + /// <ACE_Proactor::run_event_loop>. ACE_Handler wakeup_handler_; - // Handler to handle the wakeups. This works in conjunction with the - // <ACE_Proactor::run_event_loop>. }; +/** + * @class ACE_WIN32_Asynch_Timer + * + * @brief This class is posted to the completion port when a timer + * expires. When the complete method of this object is + * called, the <handler>'s handle_timeout method will be + * called. + */ class ACE_Export ACE_WIN32_Asynch_Timer : public ACE_WIN32_Asynch_Result { - // = TITLE - // This class is posted to the completion port when a timer - // expires. When the complete method of this object is - // called, the <handler>'s handle_timeout method will be - // called. + /// The factory method for this class is with the POSIX_Proactor + /// class. friend class ACE_WIN32_Proactor; - // The factory method for this class is with the POSIX_Proactor - // class. - + protected: + /// Constructor. ACE_WIN32_Asynch_Timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &tv, ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = 0); - // Constructor. - + + /// This method calls the <handler>'s handle_timeout method. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error = 0); - // This method calls the <handler>'s handle_timeout method. + /// Time value requested by caller ACE_Time_Value time_; - // Time value requested by caller }; #endif /* ACE_WIN32 */ diff --git a/ace/XTI_ATM_Mcast.h b/ace/XTI_ATM_Mcast.h index d7589668055..ed1ef058303 100644 --- a/ace/XTI_ATM_Mcast.h +++ b/ace/XTI_ATM_Mcast.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// XTI_ATM_Mcast.h -// -// = AUTHOR -// Joe Hoffert -// -// ============================================================================ +//============================================================================= +/** + * @file XTI_ATM_Mcast.h + * + * $Id$ + * + * @author Joe Hoffert + */ +//============================================================================= + #ifndef ACE_XTI_ATM_MCAST_H #define ACE_XTI_ATM_MCAST_H @@ -27,16 +24,34 @@ #if defined (ACE_HAS_XTI_ATM) -class ACE_Export ACE_XTI_ATM_Mcast : public ACE_TLI_Connector +/** + * @class ACE_XTI_ATM_Mcast + * + * @brief Defines an active connection factory for the ACE_TLI C++ + * wrappers to support XTI/ATM multicast. + */ +class ACE_Export ACE_XTI_ATM_Mcast : public ACE_TLI_Connector { - // = TITLE - // Defines an active connection factory for the ACE_TLI C++ - // wrappers to support XTI/ATM multicast. public: // = Initialization methods. + /// Default constructor. ACE_XTI_ATM_Mcast (void); - // Default constructor. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + */ ACE_XTI_ATM_Mcast (ACE_TLI_Stream &new_stream, const ACE_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -49,20 +64,22 @@ public: int rw_flag = 1, struct netbuf *udata = 0, struct netbuf *opt = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. + /** + * Actively connect and produce a <new_stream> if things go well. + * The <remote_sap> is the address that we are trying to connect + * with. The <timeout> is the amount of time to wait to connect. + * If it's 0 then we block indefinitely. If *timeout == {0, 0} then + * the connection is done using non-blocking mode. In this case, if + * the connection can't be made immediately the value of -1 is + * returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then + * this is the amount of time to wait before timing out. If the + * time expires before the connection is made <errno == ETIME>. The + * <local_sap> is the value of local address to bind to. If it's + * the default value of <ACE_Addr::sap_any> then the user is letting + * the OS do the binding. If <reuse_addr> == 1 then the + * <local_addr> is reused, even if it hasn't been cleanedup yet. + */ int connect (ACE_TLI_Stream &new_stream, const ACE_Addr &remote_sap, ACE_Time_Value *timeout = 0, @@ -75,43 +92,32 @@ public: int rw_flag = 1, struct netbuf *udata = 0, struct netbuf *opt = 0); - // Actively connect and produce a <new_stream> if things go well. - // The <remote_sap> is the address that we are trying to connect - // with. The <timeout> is the amount of time to wait to connect. - // If it's 0 then we block indefinitely. If *timeout == {0, 0} then - // the connection is done using non-blocking mode. In this case, if - // the connection can't be made immediately the value of -1 is - // returned with <errno == EWOULDBLOCK>. If *timeout > {0, 0} then - // this is the amount of time to wait before timing out. If the - // time expires before the connection is made <errno == ETIME>. The - // <local_sap> is the value of local address to bind to. If it's - // the default value of <ACE_Addr::sap_any> then the user is letting - // the OS do the binding. If <reuse_addr> == 1 then the - // <local_addr> is reused, even if it hasn't been cleanedup yet. + /** + * Actively add a leaf to the currently connected stream (i.e., + * multicast). The <remote_sap> is the address of the leaf that we + * are trying to add. The <timeout> is the amount of time to wait to + * connect. If it's 0 then we block indefinitely. If *timeout == + * {0, 0} then the connection is done using non-blocking mode. In + * this case, if the connection can't be made immediately the value + * of -1 is returned with <errno == EWOULDBLOCK>. If *timeout > + * {0, 0} then this is the amount of time to wait before timing out. + * If the time expires before the connection is made <errno == ETIME>. + */ int add_leaf (ACE_TLI_Stream ¤t_stream, const ACE_Addr &remote_sap, ACE_INT32 leaf_id, ACE_Time_Value *timeout = 0); - // Actively add a leaf to the currently connected stream (i.e., - // multicast). The <remote_sap> is the address of the leaf that we - // are trying to add. The <timeout> is the amount of time to wait to - // connect. If it's 0 then we block indefinitely. If *timeout == - // {0, 0} then the connection is done using non-blocking mode. In - // this case, if the connection can't be made immediately the value - // of -1 is returned with <errno == EWOULDBLOCK>. If *timeout > - // {0, 0} then this is the amount of time to wait before timing out. - // If the time expires before the connection is made <errno == ETIME>. // = Meta-type info typedef ACE_ATM_Addr PEER_ADDR; typedef ACE_TLI_Stream PEER_STREAM; + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. }; #if defined (__ACE_INLINE__) diff --git a/ace/XtReactor.h b/ace/XtReactor.h index 6dc3f57ae25..d2d4d81c307 100644 --- a/ace/XtReactor.h +++ b/ace/XtReactor.h @@ -1,20 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// XtReactor.h -// -// = AUTHOR -// Eric C. Newton's <ecn@clark.net>, -// Kirill Rybaltchenko <Kirill.Rybaltchenko@cern.ch>, and -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file XtReactor.h + * + * $Id$ + * + * @author Eric C. Newton's <ecn@clark.net> + * @author Kirill Rybaltchenko <Kirill.Rybaltchenko@cern.ch> + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_XTREACTOR_H #define ACE_XTREACTOR_H @@ -32,27 +29,33 @@ #include /**/ <X11/Intrinsic.h> //#undef String +/** + * @class ACE_XtReactorID + * + * @brief This little class is necessary due to the way that Microsoft + * implements sockets to be pointers rather than indices. + */ class ACE_Export ACE_XtReactorID { - // = TITLE - // This little class is necessary due to the way that Microsoft - // implements sockets to be pointers rather than indices. public: + /// Magic cookie. XtInputId id_; - // Magic cookie. + /// Underlying handle. ACE_HANDLE handle_; - // Underlying handle. + /// Pointer to next node in the linked list. ACE_XtReactorID *next_; - // Pointer to next node in the linked list. }; +/** + * @class ACE_XtReactor + * + * @brief An object-oriented event demultiplexor and event handler + * dispatcher that uses the X Toolkit functions. + */ class ACE_Export ACE_XtReactor : public ACE_Select_Reactor { - // = TITLE - // An object-oriented event demultiplexor and event handler - // dispatcher that uses the X Toolkit functions. public: // = Initialization and termination methods. ACE_XtReactor (XtAppContext context = 0, @@ -69,7 +72,7 @@ public: const void *arg, const ACE_Time_Value &delta_time, const ACE_Time_Value &interval); - virtual int reset_timer_interval (long timer_id, + virtual int reset_timer_interval (long timer_id, const ACE_Time_Value &interval); virtual int cancel_timer (ACE_Event_Handler *handler, int dont_call_handle_close = 1); @@ -80,52 +83,52 @@ public: protected: // = Register timers/handles with Xt. + /// Register a single <handler>. virtual int register_handler_i (ACE_HANDLE handle, ACE_Event_Handler *handler, ACE_Reactor_Mask mask); - // Register a single <handler>. + /// Register a set of <handlers>. virtual int register_handler_i (const ACE_Handle_Set &handles, ACE_Event_Handler *handler, ACE_Reactor_Mask mask); - // Register a set of <handlers>. + /// Remove the <handler> associated with this <handle>. virtual int remove_handler_i (ACE_HANDLE handle, ACE_Reactor_Mask mask); - // Remove the <handler> associated with this <handle>. + /// Remove a set of <handles>. virtual int remove_handler_i (const ACE_Handle_Set &handles, ACE_Reactor_Mask); - // Remove a set of <handles>. + /// Removes an Xt handle. virtual void remove_XtInput (ACE_HANDLE handle); - // Removes an Xt handle. + /// Wait for events to occur. virtual int wait_for_multiple_events (ACE_Select_Reactor_Handle_Set &, ACE_Time_Value *); - // Wait for events to occur. + ///Wait for Xt events to occur. virtual int XtWaitForMultipleEvents (int, ACE_Select_Reactor_Handle_Set &, ACE_Time_Value *); - //Wait for Xt events to occur. XtAppContext context_; ACE_XtReactorID *ids_; XtIntervalId timeout_; private: + /// This method ensures there's an Xt timeout for the first timeout + /// in the Reactor's Timer_Queue. void reset_timeout (void); - // This method ensures there's an Xt timeout for the first timeout - // in the Reactor's Timer_Queue. // = Integrate with the X callback function mechanism. static void TimerCallbackProc (XtPointer closure, XtIntervalId *id); static void InputCallbackProc (XtPointer closure, int* source, XtInputId *id); + /// Deny access since member-wise won't work... ACE_XtReactor (const ACE_XtReactor &); ACE_XtReactor &operator = (const ACE_XtReactor &); - // Deny access since member-wise won't work... }; #endif /* ACE_HAS_XT */ diff --git a/ace/ace_wchar.h b/ace/ace_wchar.h index 2e8b18c158c..19ed348a156 100644 --- a/ace/ace_wchar.h +++ b/ace/ace_wchar.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// unicode.h -// -// = AUTHOR -// Darrell Brunsch -// -// ============================================================================ + +//============================================================================= +/** + * @file unicode.h + * + * $Id$ + * + * @author Darrell Brunsch + */ +//============================================================================= + #ifndef ACE_WCHAR_H #define ACE_WCHAR_H @@ -112,68 +109,72 @@ typedef char ACE_TCHAR; #endif /* ACE_LEGACY_MODE */ #if defined ACE_HAS_WCHAR +/** + * @class ACE_Wide_To_Ascii + * + * @brief A lightweight wchar* to char* string conversion class. + * + * The purpose of this class is to perform conversion from + * wchar* to char* strings. It is not intended for general + * purpose use. + */ class ACE_Wide_To_Ascii { - // = TITLE - // A lightweight wchar* to char* string conversion class. - // - // = DESCRIPTION - // The purpose of this class is to perform conversion from - // wchar* to char* strings. It is not intended for general - // purpose use. public: + /// Ctor must take a wchar string. ACE_Wide_To_Ascii (const wchar_t *s); - // Ctor must take a wchar string. + /// Dtor will free up the memory. ~ACE_Wide_To_Ascii (void); - // Dtor will free up the memory. + /// Return the internal char* representation. char *char_rep (void); - // Return the internal char* representation. + /// Converts an wchar_t string to ascii and returns a new string. static char *convert (const wchar_t *wstr); - // Converts an wchar_t string to ascii and returns a new string. private: + /// Internal pointer to the converted string. char *s_; - // Internal pointer to the converted string. + /// Disallow these operation. ACE_Wide_To_Ascii (void); ACE_Wide_To_Ascii (ACE_Wide_To_Ascii &); ACE_Wide_To_Ascii& operator= (ACE_Wide_To_Ascii &); - // Disallow these operation. }; +/** + * @class ACE_Ascii_To_Wide + * + * @brief A lightweight char* to wchar* string conversion class. + * + * The purpose of this class is to perform conversion from + * char* to wchar* strings. It is not intended for general + * purpose use. + */ class ACE_Ascii_To_Wide { - // = TITLE - // A lightweight char* to wchar* string conversion class. - // - // = DESCRIPTION - // The purpose of this class is to perform conversion from - // char* to wchar* strings. It is not intended for general - // purpose use. public: + /// Ctor must take a wchar string. ACE_Ascii_To_Wide (const char *s); - // Ctor must take a wchar string. + /// Dtor will free up the memory. ~ACE_Ascii_To_Wide (void); - // Dtor will free up the memory. + /// Return the internal wchar* representation. wchar_t *wchar_rep (void); - // Return the internal wchar* representation. + /// Converts an char string to unicode/wide and returns a new string. static wchar_t *convert (const char *str); - // Converts an char string to unicode/wide and returns a new string. private: + /// Internal pointer to the converted string. wchar_t *s_; - // Internal pointer to the converted string. + /// Disallow these operation. ACE_Ascii_To_Wide (void); ACE_Ascii_To_Wide (ACE_Ascii_To_Wide &); ACE_Ascii_To_Wide operator= (ACE_Ascii_To_Wide &); - // Disallow these operation. }; #if defined (ACE_LEGACY_MODE) diff --git a/ace/config-all.h b/ace/config-all.h index 8a1a68edd75..fa8ef4c5d7c 100644 --- a/ace/config-all.h +++ b/ace/config-all.h @@ -1,20 +1,17 @@ // -*- C++ -*- -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// config-all.h -// -// = AUTHOR -// (Originally in OS.h) -// Doug Schmidt <schmidt@cs.wustl.edu>, Jesper S. M|ller -// <stophph@diku.dk>, and a cast of thousands... -// -// ============================================================================ +//============================================================================= +/** + * @file config-all.h + * + * $Id$ + * + * @author (Originally in OS.h)Doug Schmidt <schmidt@cs.wustl.edu> + * @author Jesper S. M|ller<stophph@diku.dk> + * @author and a cast of thousands... + */ +//============================================================================= + #ifndef ACE_CONFIG_ALL_H #define ACE_CONFIG_ALL_H diff --git a/ace/iosfwd.h b/ace/iosfwd.h index d99e941bdfd..412b6b3bdde 100644 --- a/ace/iosfwd.h +++ b/ace/iosfwd.h @@ -1,28 +1,26 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// iosfwd.h -// -// = AUTHOR -// Irfan Pyarali -// -// = DESCRIPTION -// This file contains the portability ugliness for the Standard C++ -// Library. As implementations of the "standard" emerge, this file -// will need to be updated. -// -// This files deals with forward declaration for the stream -// classes. Remember that since the new Standard C++ Library code -// for streams uses templates, simple forward declaration will not -// work. -// -// ============================================================================ +//============================================================================= +/** + * @file iosfwd.h + * + * $Id$ + * + * @author Irfan Pyarali + * + * This file contains the portability ugliness for the Standard C++ + * Library. As implementations of the "standard" emerge, this file + * will need to be updated. + * + * This files deals with forward declaration for the stream + * classes. Remember that since the new Standard C++ Library code + * for streams uses templates, simple forward declaration will not + * work. + * + * + */ +//============================================================================= + #ifndef ACE_IOSFWD_H #define ACE_IOSFWD_H diff --git a/ace/post.h b/ace/post.h index 419ea8af80b..746a6398e33 100644 --- a/ace/post.h +++ b/ace/post.h @@ -1,21 +1,19 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// post.h -// -// = AUTHOR -// Christopher Kohlhoff <chris@kohlhoff.com> -// -// = DESCRIPTION -// This file restore the original alignment rules. -// -// ============================================================================ +//============================================================================= +/** + * @file post.h + * + * $Id$ + * + * @author Christopher Kohlhoff <chris@kohlhoff.com> + * + * This file restore the original alignment rules. + * + * + */ +//============================================================================= + // No header guard #if defined (_MSC_VER) diff --git a/ace/pre.h b/ace/pre.h index 0361b1a3c31..de00998dc96 100644 --- a/ace/pre.h +++ b/ace/pre.h @@ -1,22 +1,20 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// pre.h -// -// = AUTHOR -// Christopher Kohlhoff <chris@kohlhoff.com> -// -// = DESCRIPTION -// This file save the original alignment rules and changes the alignment -// boundary to ACE's default. -// -// ============================================================================ +//============================================================================= +/** + * @file pre.h + * + * $Id$ + * + * @author Christopher Kohlhoff <chris@kohlhoff.com> + * + * This file save the original alignment rules and changes the alignment + * boundary to ACE's default. + * + * + */ +//============================================================================= + // No header guard #if defined (_MSC_VER) diff --git a/ace/streams.h b/ace/streams.h index 26b9c2b7931..f724ad03e7e 100644 --- a/ace/streams.h +++ b/ace/streams.h @@ -1,26 +1,23 @@ // -*- C++ -*- -// -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// streams.h -// -// = AUTHOR -// Irfan Pyarali -// -// = DESCRIPTION -// This file contains the portability ugliness for the Standard C++ -// Library. As implementations of the "standard" emerge, this file -// will need to be updated. -// -// This files deals with the streams includes. -// -// ============================================================================ + +//============================================================================= +/** + * @file streams.h + * + * $Id$ + * + * @author Irfan Pyarali + * + * This file contains the portability ugliness for the Standard C++ + * Library. As implementations of the "standard" emerge, this file + * will need to be updated. + * + * This files deals with the streams includes. + * + * + */ +//============================================================================= + #ifndef ACE_STREAMS_H #define ACE_STREAMS_H |