diff options
Diffstat (limited to 'ace/Malloc_T.h')
| -rw-r--r-- | ace/Malloc_T.h | 564 |
1 files changed, 308 insertions, 256 deletions
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__) |