## 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 <ace/Malloc_T.h>

    template<ACE_MEM_POOL_1, class ACE_LOCK>
    class ACE_Malloc
    {
      public:
        friend class ACE_Malloc_Iterator<ACE_MEM_POOL_2, ACE_LOCK>;
        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;
        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.

    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