## NAME

ACE_Hash_Map_Manager_Ex - Define a map abstraction that efficiently associates `EXT_ID`s with `INT_ID`s.

## SYNOPSIS

    #include <ace/Hash_Map_Manager_T.h>

    template<class EXT_ID, class INT_ID, class HASH_KEY, class COMPARE_KEYS, class ACE_LOCK>
    class ACE_Hash_Map_Manager_Ex
    {
      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>;

            friend class ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK>;

            friend class ACE_Hash_Map_Bucket_Iterator<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK>;

        typedef EXT_ID KEY;
        typedef INT_ID VALUE;
        typedef ACE_Hash_Map_Entry<EXT_ID, INT_ID> ENTRY;
            typedef ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> ITERATOR;

            typedef ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> REVERSE_ITERATOR;

            typedef ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> iterator;

            typedef ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> reverse_iterator;

        ACE_Hash_Map_Manager_Ex (ACE_Allocator *alloc = 0);
        ACE_Hash_Map_Manager_Ex (size_t size, ACE_Allocator *alloc = 0);
        int open (
            size_t size = ACE_DEFAULT_MAP_SIZE,
            ACE_Allocator *alloc = 0
            );
        int close (void);
        ~ACE_Hash_Map_Manager_Ex (void);
        int bind (const EXT_ID &item, const INT_ID &int_id);
        int bind (
            const EXT_ID &ext_id,
            const INT_ID &int_id,
            ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry
            );
        int trybind (const EXT_ID &ext_id, INT_ID &int_id);
        int trybind (
            const EXT_ID &ext_id,
            INT_ID &int_id,
            ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry
            );
        int rebind (const EXT_ID &ext_id, const INT_ID &int_id);
        int rebind (
            const EXT_ID &ext_id,
            const INT_ID &int_id,
            ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry
            );
        int rebind (
            const EXT_ID &ext_id,
            const INT_ID &int_id,
            INT_ID &old_int_id
            );
        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
            );
        int rebind (
            const EXT_ID &ext_id,
            const INT_ID &int_id,
            EXT_ID &old_ext_id,
            INT_ID &old_int_id
            );
        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
            );
        int find (const EXT_ID &ext_id, INT_ID &int_id);
        int find (const EXT_ID &ext_id);
        int find (
            const EXT_ID &ext_id,
            ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry
            );
        int unbind (const EXT_ID &ext_id);
        int unbind (const EXT_ID &ext_id, INT_ID &int_id);
        int unbind (ACE_Hash_Map_Entry<EXT_ID, INT_ID> *entry);
        size_t current_size (void) const;
        size_t total_size (void) const;
        ACE_LOCK &mutex (void);
        void dump (void) const;
        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
            );
        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
            );
      protected:
        int equal (const EXT_ID &id1, const EXT_ID &id2);
        u_long hash (const EXT_ID &ext_id);
        int bind_i (const EXT_ID &ext_id, const INT_ID &int_id);
        int bind_i (
            const EXT_ID &ext_id,
            const INT_ID &int_id,
            ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry
            );
        int trybind_i (const EXT_ID &ext_id, INT_ID &int_id);
        int trybind_i (
            const EXT_ID &ext_id,
            INT_ID &int_id,
            ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry
            );
        int rebind_i (const EXT_ID &ext_id, const INT_ID &int_id);
        int rebind_i (
            const EXT_ID &ext_id,
            const INT_ID &int_id,
            ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry
            );
        int rebind_i (
            const EXT_ID &ext_id,
            const INT_ID &int_id,
            INT_ID &old_int_id
            );
        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
            );
        int rebind_i (
            const EXT_ID &ext_id,
            const INT_ID &int_id,
            EXT_ID &old_ext_id,
            INT_ID &old_int_id
            );
        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
            );
        int find_i (const EXT_ID &ext_id, INT_ID &int_id);
        int find_i (const EXT_ID &ext_id);
        int find_i (
            const EXT_ID &ext_id,
            ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry
            );
        int unbind_i (const EXT_ID &ext_id, INT_ID &int_id);
        int unbind_i (const EXT_ID &ext_id);
        int unbind_i (ACE_Hash_Map_Entry<EXT_ID, INT_ID> *entry);
        int create_buckets (size_t size);
        int close_i (void);
        ACE_Allocator *allocator_;
        ACE_LOCK lock_;
        HASH_KEY hash_key_;
        COMPARE_KEYS compare_keys_;
      private:
        int shared_find (
            const EXT_ID &ext_id,
            ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry,
            u_long &loc
            );
        ACE_Hash_Map_Entry<EXT_ID, INT_ID> *table_;
        size_t total_size_;
        size_t cur_size_;
    };

## 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.

## ACE-style iterator typedefs.

        typedef ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> ITERATOR;

        typedef ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> REVERSE_ITERATOR;

## STL-style iterator typedefs.

        typedef ACE_Hash_Map_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> iterator;

        typedef ACE_Hash_Map_Reverse_Iterator_Ex<EXT_ID, INT_ID, HASH_KEY, COMPARE_KEYS, ACE_LOCK> reverse_iterator;

## Initialization and termination methods.

    ACE_Hash_Map_Manager_Ex (ACE_Allocator *alloc = 0);

Initialize a `Hash_Map_Manager_Ex` with default size.

    ACE_Hash_Map_Manager_Ex (size_t size, ACE_Allocator *alloc = 0);

Initialize a `Hash_Map_Manager_Ex` with size `length`.

    int open (
        size_t size = ACE_DEFAULT_MAP_SIZE,
        ACE_Allocator *alloc = 0
        );

Initialize a `Hash_Map_Manager_Ex` with `size` elements.

    int close (void);

Close down a `Hash_Map_Manager_Ex` and release dynamically allocated resources.

    ~ACE_Hash_Map_Manager_Ex (void);

Initialize a `Hash_Map_Manager_Ex` with size `length`.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    int find (const EXT_ID &ext_id);

Returns 0 if the `ext_id` is in the mapping, otherwise -1.

    int find (
        const EXT_ID &ext_id,
        ACE_Hash_Map_Entry<EXT_ID, INT_ID> *&entry
        );

Locate `ext_id` and pass out parameter via `entry`. If found, return 0, returns -1 if not found.

    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...)

    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.

    int unbind (ACE_Hash_Map_Entry<EXT_ID, INT_ID> *entry);

Remove entry from map.

    size_t current_size (void) const;

Return the current size of the map.

    size_t total_size (void) const;

Return the total size of the map.

    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!

    void dump (void) const;

Dump the state of an object.

## STL styled iterator factory functions.

    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.

    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.

## The following methods do the actual work.

    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.

    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.

    int bind_i (const EXT_ID &ext_id, const INT_ID &int_id);

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.

    int trybind_i (const EXT_ID &ext_id, INT_ID &int_id);

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.

    int rebind_i (const EXT_ID &ext_id, const INT_ID &int_id);

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.

    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.

    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.

    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.

    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.

    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.

    int find_i (const EXT_ID &ext_id);

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.

    int unbind_i (const EXT_ID &ext_id, INT_ID &int_id);

Performs unbind. Must be called with locks held.

    int unbind_i (const EXT_ID &ext_id);

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.

    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.

    int close_i (void);

Close down a `Map_Manager_Ex`. Must be called with locks held.

    ACE_Allocator *allocator_;

Pointer to a memory allocator.

    ACE_LOCK lock_;

Synchronization variable for the MT_SAFE `ACE_Hash_Map_Manager_Ex`.

    HASH_KEY hash_key_;

Function object used for hashing keys.

    COMPARE_KEYS compare_keys_;

Function object used for comparing keys.

## AUTHOR

Doug Schmidt

## LIBRARY

ace