--- name: "ACE_Malloc" section: "3" platform: "linux" package: "libace-doc" version: "5.0.7-4" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/ACE_Malloc" --- # ACE\_Malloc(3) Define a C++ class that uses parameterized types to provide an extensible mechanism for encapsulating various of dynamic memory management strategies. ## NAME ACE\_Malloc - Define a C++ class that uses parameterized types to provide an extensible mechanism for encapsulating various of dynamic memory management strategies. ## SYNOPSIS ``` #include template class ACE_Malloc { public: friend class ACE_Malloc_LIFO_Iterator; friend class ACE_Malloc_FIFO_Iterator; typedef ACE_MEM_POOL MEMORY_POOL; typedef ACE_MEM_POOL_OPTIONS MEMORY_POOL_OPTIONS; ACE_Malloc (LPCTSTR pool_name = 0); ACE_Malloc ( LPCTSTR pool_name, LPCTSTR lock_name, const ACE_MEM_POOL_OPTIONS *options = 0 ); ACE_Malloc ( LPCTSTR pool_name, LPCTSTR lock_name, const void *options = 0 ); ~ACE_Malloc (void); int remove (void); void *malloc (size_t nbytes); void *calloc (size_t nbytes, char initial_value = ' '); void free (void *ptr); MEMORY_POOL &memory_pool (void); int bind (const char *name, void *pointer, int duplicates = 0); int trybind (const char *name, void *&pointer); int find (const char *name, void *&pointer); int find (const char *name); int unbind (const char *name); int unbind (const char *name, void *&pointer); int sync (ssize_t len = -1, int flags = MS_SYNC); int sync (void *addr, size_t len, int flags = MS_SYNC); int protect (ssize_t len = -1, int prot = PROT_RDWR); int protect (void *addr, size_t len, int prot = PROT_RDWR); ssize_t avail_chunks (size_t size) const; void print_stats (void) const; ACE_LOCK &mutex (void); void dump (void) const; ACE_ALLOC_HOOK_DECLARE; private: int open (void); int shared_bind (const char *name, void *pointer); ACE_Name_Node *shared_find (const char *name); void *shared_malloc (size_t nbytes); void shared_free (void *ptr); ACE_Control_Block *cb_ptr_; MEMORY_POOL memory_pool_; ACE_LOCK lock_; }; ``` ## DESCRIPTION This class can be configured flexibly with different MEMORY\_POOL strategies and different types of ACE\_LOCK strategies. ## Initialization and termination methods. ``` ACE_Malloc (LPCTSTR 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). ``` ACE_Malloc ( LPCTSTR pool_name, LPCTSTR 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. ``` ACE_Malloc ( LPCTSTR pool_name, LPCTSTR lock_name, const void *options = 0 ); ``` This is necessary to work around template bugs with certain C++ compilers. ``` ~ACE_Malloc (void); ``` Destructor ``` int remove (void); ``` Releases resources allocated by ACE\_Malloc. ## Memory management ``` void *malloc (size_t nbytes); ``` Allocate nbytes, but don't give them any initial value. ``` void *calloc (size_t nbytes, char initial_value = ' '); ``` Allocate nbytes, giving them initial\_value. ``` void free (void *ptr); ``` Deallocate memory pointed to by ptr, which must have been allocated previously by this-malloc. ``` MEMORY_POOL &memory_pool (void); ``` Returns a reference to the underlying memory pool. ## Map manager like functions ``` 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. ``` 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. ``` int find (const char *name, void *&pointer); ``` Locate name and pass out parameter via pointer. If found, return 0, returns -1 if failure occurs. ``` int find (const char *name); ``` Returns 0 if name is in the mapping. -1, otherwise. ``` 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... ``` 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)." ``` 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. ``` 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\_. ``` 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. ``` 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. ``` 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. ``` void print_stats (void) const; ``` Dump statistics of how malloc is behaving. ``` ACE_LOCK &mutex (void); ``` Returns a pointer to the lock used to provide mutual exclusion to an ACE\_Malloc allocator. ``` void dump (void) const; ``` Dump the state of an object. ``` ACE_ALLOC_HOOK_DECLARE; ``` Declare the dynamic allocation hooks. ## AUTHOR Doug Schmidt and Irfan Pyarali ## LIBRARY ace