summaryrefslogtreecommitdiff
path: root/ace
diff options
context:
space:
mode:
Diffstat (limited to 'ace')
-rw-r--r--ace/ACE.h407
-rw-r--r--ace/ARGV.h149
-rw-r--r--ace/ATM_Acceptor.h54
-rw-r--r--ace/ATM_Addr.h146
-rw-r--r--ace/ATM_Connector.h124
-rw-r--r--ace/ATM_Params.h105
-rw-r--r--ace/ATM_QoS.h58
-rw-r--r--ace/ATM_Stream.h57
-rw-r--r--ace/Acceptor.h517
-rw-r--r--ace/Activation_Queue.h74
-rw-r--r--ace/Active_Map_Manager.h89
-rw-r--r--ace/Active_Map_Manager_T.h149
-rw-r--r--ace/Addr.h72
-rw-r--r--ace/Arg_Shifter.h229
-rw-r--r--ace/Array.h31
-rw-r--r--ace/Asynch_Acceptor.h166
-rw-r--r--ace/Asynch_IO.h1237
-rw-r--r--ace/Asynch_IO_Impl.h437
-rw-r--r--ace/Auto_IncDec_T.h53
-rw-r--r--ace/Auto_Ptr.h78
-rw-r--r--ace/Base_Thread_Adapter.h135
-rw-r--r--ace/Based_Pointer_Repository.h58
-rw-r--r--ace/Based_Pointer_T.h187
-rw-r--r--ace/Basic_Stats.h30
-rw-r--r--ace/Basic_Types.h125
-rw-r--r--ace/CDR_Base.h140
-rw-r--r--ace/CDR_Stream.h663
-rw-r--r--ace/CORBA_Handler.h195
-rw-r--r--ace/CORBA_Ref.h74
-rw-r--r--ace/CORBA_macros.h31
-rw-r--r--ace/Cache_Map_Manager_T.h278
-rw-r--r--ace/Cached_Connect_Strategy_T.h143
-rw-r--r--ace/Caching_Strategies_T.h406
-rw-r--r--ace/Caching_Utility_T.h261
-rw-r--r--ace/Capabilities.h141
-rw-r--r--ace/Cleanup_Strategies_T.h127
-rw-r--r--ace/Codeset_IBM1047.h77
-rw-r--r--ace/Configuration.h462
-rw-r--r--ace/Connector.h445
-rw-r--r--ace/Containers.h36
-rw-r--r--ace/Containers_T.h1554
-rw-r--r--ace/DEV.h48
-rw-r--r--ace/DEV_Addr.h60
-rw-r--r--ace/DEV_Connector.h104
-rw-r--r--ace/DEV_IO.h93
-rw-r--r--ace/DLL.h123
-rw-r--r--ace/Date_Time.h67
-rw-r--r--ace/Dirent.h128
-rw-r--r--ace/Dump.h153
-rw-r--r--ace/Dump_T.h53
-rw-r--r--ace/Dynamic.h62
-rw-r--r--ace/Dynamic_Service.h46
-rw-r--r--ace/Env_Value_T.h71
-rw-r--r--ace/Event_Handler.h128
-rw-r--r--ace/Event_Handler_T.h125
-rw-r--r--ace/FIFO.h67
-rw-r--r--ace/FIFO_Recv.h52
-rw-r--r--ace/FIFO_Recv_Msg.h50
-rw-r--r--ace/FIFO_Send.h44
-rw-r--r--ace/FIFO_Send_Msg.h52
-rw-r--r--ace/FILE.h113
-rw-r--r--ace/FILE_Addr.h62
-rw-r--r--ace/FILE_Connector.h98
-rw-r--r--ace/FILE_IO.h106
-rw-r--r--ace/File_Lock.h149
-rw-r--r--ace/Filecache.h230
-rw-r--r--ace/FlReactor.h78
-rw-r--r--ace/Flag_Manip.h30
-rw-r--r--ace/Free_List.h119
-rw-r--r--ace/Functor.h229
-rw-r--r--ace/Functor_T.h135
-rw-r--r--ace/Future.h344
-rw-r--r--ace/Future_Set.h90
-rw-r--r--ace/Get_Opt.h175
-rw-r--r--ace/Handle_Gobbler.h59
-rw-r--r--ace/Handle_Ops.h39
-rw-r--r--ace/Handle_Set.h166
-rw-r--r--ace/Hash_Cache_Map_Manager_T.h174
-rw-r--r--ace/Hash_Map_Manager.h23
-rw-r--r--ace/Hash_Map_Manager_T.h575
-rw-r--r--ace/Hash_Map_With_Allocator_T.h71
-rw-r--r--ace/High_Res_Timer.h273
-rw-r--r--ace/INET_Addr.h220
-rw-r--r--ace/IOStream.h277
-rw-r--r--ace/IOStream_T.h179
-rw-r--r--ace/IO_Cntl_Msg.h80
-rw-r--r--ace/IO_SAP.h71
-rw-r--r--ace/IPC_SAP.h68
-rw-r--r--ace/Init_ACE.h58
-rw-r--r--ace/LOCK_SOCK_Acceptor.h51
-rw-r--r--ace/LSOCK.h52
-rw-r--r--ace/LSOCK_Acceptor.h54
-rw-r--r--ace/LSOCK_CODgram.h48
-rw-r--r--ace/LSOCK_Connector.h94
-rw-r--r--ace/LSOCK_Dgram.h48
-rw-r--r--ace/LSOCK_Stream.h50
-rw-r--r--ace/Lib_Find.h89
-rw-r--r--ace/Local_Name_Space.h98
-rw-r--r--ace/Local_Name_Space_T.h179
-rw-r--r--ace/Local_Tokens.h993
-rw-r--r--ace/Log_Msg.h416
-rw-r--r--ace/Log_Msg_Backend.h27
-rw-r--r--ace/Log_Msg_Callback.h32
-rw-r--r--ace/Log_Msg_IPC.h23
-rw-r--r--ace/Log_Priority.h75
-rw-r--r--ace/Log_Record.h124
-rw-r--r--ace/Logging_Strategy.h96
-rw-r--r--ace/MEM_Acceptor.h111
-rw-r--r--ace/MEM_Addr.h110
-rw-r--r--ace/MEM_Connector.h104
-rw-r--r--ace/MEM_IO.h167
-rw-r--r--ace/MEM_SAP.h88
-rw-r--r--ace/MEM_Stream.h118
-rw-r--r--ace/Makefile415
-rw-r--r--ace/Malloc.h119
-rw-r--r--ace/Malloc_Allocator.h94
-rw-r--r--ace/Malloc_Base.h140
-rw-r--r--ace/Malloc_T.h564
-rw-r--r--ace/Managed_Object.h135
-rw-r--r--ace/Map.h23
-rw-r--r--ace/Map_Manager.h430
-rw-r--r--ace/Map_T.h1208
-rw-r--r--ace/Mem_Map.h141
-rw-r--r--ace/Memory_Pool.h578
-rw-r--r--ace/Message_Block.h874
-rw-r--r--ace/Message_Block_T.h60
-rw-r--r--ace/Message_Queue.h445
-rw-r--r--ace/Message_Queue_T.h687
-rw-r--r--ace/Method_Object.h33
-rw-r--r--ace/Method_Request.h57
-rw-r--r--ace/Min_Max.h40
-rw-r--r--ace/Module.h178
-rw-r--r--ace/Msg_WFMO_Reactor.h121
-rw-r--r--ace/Multiplexor.h52
-rw-r--r--ace/NT_Service.h342
-rw-r--r--ace/Name_Proxy.h71
-rw-r--r--ace/Name_Request_Reply.h111
-rw-r--r--ace/Name_Space.h126
-rw-r--r--ace/Naming_Context.h283
-rw-r--r--ace/OS.h1417
-rw-r--r--ace/OS_Dirent.h39
-rw-r--r--ace/OS_Log_Msg_Attributes.h25
-rw-r--r--ace/OS_Memory.h39
-rw-r--r--ace/OS_String.h80
-rw-r--r--ace/OS_TLI.h39
-rw-r--r--ace/OS_Thread_Adapter.h67
-rw-r--r--ace/Object_Manager.h476
-rw-r--r--ace/Obstack.h92
-rw-r--r--ace/PI_Malloc.h126
-rw-r--r--ace/POSIX_Asynch_IO.h1515
-rw-r--r--ace/POSIX_Proactor.h380
-rw-r--r--ace/Pair.h23
-rw-r--r--ace/Pair_T.h65
-rw-r--r--ace/Parse_Node.h191
-rw-r--r--ace/Pipe.h73
-rw-r--r--ace/Priority_Reactor.h67
-rw-r--r--ace/Proactor.h341
-rw-r--r--ace/Proactor_Impl.h153
-rw-r--r--ace/Process.h391
-rw-r--r--ace/Process_Manager.h432
-rw-r--r--ace/Process_Mutex.h112
-rw-r--r--ace/Process_Semaphore.h136
-rw-r--r--ace/Profile_Timer.h93
-rw-r--r--ace/QoS_Decorator.h155
-rw-r--r--ace/QoS_Manager.h63
-rw-r--r--ace/QoS_Session.h148
-rw-r--r--ace/QoS_Session_Factory.h79
-rw-r--r--ace/QoS_Session_Impl.h225
-rw-r--r--ace/QtReactor.h113
-rw-r--r--ace/RB_Tree.h660
-rw-r--r--ace/RW_Process_Mutex.h101
-rw-r--r--ace/Reactor.h610
-rw-r--r--ace/Reactor_Impl.h491
-rw-r--r--ace/Read_Buffer.h99
-rw-r--r--ace/Registry.h388
-rw-r--r--ace/Registry_Name_Space.h115
-rw-r--r--ace/Remote_Name_Space.h129
-rw-r--r--ace/Remote_Tokens.h296
-rw-r--r--ace/SOCK.h93
-rw-r--r--ace/SOCK_Acceptor.h135
-rw-r--r--ace/SOCK_CODgram.h42
-rw-r--r--ace/SOCK_Connector.h205
-rw-r--r--ace/SOCK_Dgram.h144
-rw-r--r--ace/SOCK_Dgram_Bcast.h86
-rw-r--r--ace/SOCK_Dgram_Mcast.h157
-rw-r--r--ace/SOCK_Dgram_Mcast_QoS.h94
-rw-r--r--ace/SOCK_IO.h119
-rw-r--r--ace/SOCK_Stream.h148
-rw-r--r--ace/SPIPE.h58
-rw-r--r--ace/SPIPE_Acceptor.h58
-rw-r--r--ace/SPIPE_Addr.h76
-rw-r--r--ace/SPIPE_Connector.h104
-rw-r--r--ace/SPIPE_Stream.h100
-rw-r--r--ace/SString.h599
-rw-r--r--ace/SUN_Proactor.h141
-rw-r--r--ace/SV_Message.h38
-rw-r--r--ace/SV_Message_Queue.h50
-rw-r--r--ace/SV_Semaphore_Complex.h121
-rw-r--r--ace/SV_Semaphore_Simple.h112
-rw-r--r--ace/SV_Shared_Memory.h59
-rw-r--r--ace/Sample_History.h27
-rw-r--r--ace/Sched_Params.h219
-rw-r--r--ace/Select_Reactor.h40
-rw-r--r--ace/Select_Reactor_Base.h422
-rw-r--r--ace/Select_Reactor_T.h698
-rw-r--r--ace/Service_Config.h489
-rw-r--r--ace/Service_Manager.h77
-rw-r--r--ace/Service_Object.h121
-rw-r--r--ace/Service_Repository.h163
-rw-r--r--ace/Service_Templates.h12
-rw-r--r--ace/Service_Types.h114
-rw-r--r--ace/Shared_Memory.h48
-rw-r--r--ace/Shared_Memory_MM.h73
-rw-r--r--ace/Shared_Memory_SV.h63
-rw-r--r--ace/Shared_Object.h42
-rw-r--r--ace/Signal.h393
-rw-r--r--ace/Singleton.h278
-rw-r--r--ace/Sock_Connect.h48
-rw-r--r--ace/Stats.h218
-rw-r--r--ace/Strategies.h108
-rw-r--r--ace/Strategies_T.h682
-rw-r--r--ace/Stream.h170
-rw-r--r--ace/Stream_Modules.h76
-rw-r--r--ace/Svc_Conf.h25
-rw-r--r--ace/Svc_Handler.h291
-rw-r--r--ace/Synch.h1356
-rw-r--r--ace/Synch_Options.h159
-rw-r--r--ace/Synch_T.h726
-rw-r--r--ace/System_Time.h77
-rw-r--r--ace/TLI.h54
-rw-r--r--ace/TLI_Acceptor.h75
-rw-r--r--ace/TLI_Connector.h110
-rw-r--r--ace/TLI_Stream.h66
-rw-r--r--ace/TP_Reactor.h223
-rw-r--r--ace/TTY_IO.h59
-rw-r--r--ace/Task.h263
-rw-r--r--ace/Task_T.h123
-rw-r--r--ace/Test_and_Set.h49
-rw-r--r--ace/Thread.h237
-rw-r--r--ace/Thread_Adapter.h75
-rw-r--r--ace/Thread_Control.h88
-rw-r--r--ace/Thread_Exit.h108
-rw-r--r--ace/Thread_Hook.h56
-rw-r--r--ace/Thread_Manager.h730
-rw-r--r--ace/Time_Request_Reply.h71
-rw-r--r--ace/Time_Value.h23
-rw-r--r--ace/Timeprobe.h101
-rw-r--r--ace/Timeprobe_T.h143
-rw-r--r--ace/Timer_Hash.h25
-rw-r--r--ace/Timer_Hash_T.h239
-rw-r--r--ace/Timer_Heap.h25
-rw-r--r--ace/Timer_Heap_T.h297
-rw-r--r--ace/Timer_List.h25
-rw-r--r--ace/Timer_List_T.h206
-rw-r--r--ace/Timer_Queue.h23
-rw-r--r--ace/Timer_Queue_Adapters.h183
-rw-r--r--ace/Timer_Queue_T.h338
-rw-r--r--ace/Timer_Wheel.h23
-rw-r--r--ace/Timer_Wheel_T.h223
-rw-r--r--ace/TkReactor.h67
-rw-r--r--ace/Token.h242
-rw-r--r--ace/Token_Collection.h189
-rw-r--r--ace/Token_Invariants.h180
-rw-r--r--ace/Token_Manager.h107
-rw-r--r--ace/Token_Request_Reply.h116
-rw-r--r--ace/Trace.h69
-rw-r--r--ace/Typed_SV_Message.h48
-rw-r--r--ace/Typed_SV_Message_Queue.h42
-rw-r--r--ace/UNIX_Addr.h68
-rw-r--r--ace/UPIPE_Acceptor.h65
-rw-r--r--ace/UPIPE_Addr.h41
-rw-r--r--ace/UPIPE_Connector.h106
-rw-r--r--ace/UPIPE_Stream.h87
-rw-r--r--ace/WFMO_Reactor.h1128
-rw-r--r--ace/WIN32_Asynch_IO.h1068
-rw-r--r--ace/WIN32_Proactor.h180
-rw-r--r--ace/XTI_ATM_Mcast.h116
-rw-r--r--ace/XtReactor.h75
-rw-r--r--ace/ace_wchar.h81
-rw-r--r--ace/config-all.h27
-rw-r--r--ace/iosfwd.h44
-rw-r--r--ace/post.h30
-rw-r--r--ace/pre.h32
-rw-r--r--ace/streams.h41
284 files changed, 29057 insertions, 25642 deletions
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 &current_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 &current_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 &current_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> &current_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 &current_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)
diff --git a/ace/OS.h b/ace/OS.h
index 27cb1ec9101..48ecce95fe6 100644
--- a/ace/OS.h
+++ b/ace/OS.h
@@ -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 &current_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 &quotient);
- // Utility division function, for ACE_UINT64 dividend.
+ /// Utility division function, for ACE_Stats_Value dividend.
static void quotient (const ACE_Stats_Value &dividend,
const ACE_UINT32 divisor,
ACE_Stats_Value &quotient);
- // 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 &current_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 &current_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 &current_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