## NAME

ACE_Cache_Map_Manager - Defines a abstraction that will purge entries from a map.

## SYNOPSIS

    #include <ace/Cache_Map_Manager.h>

    template<ACE_T1>
    class ACE_Cache_Map_Manager
    {
      public:
        typedef KEY key_type;
        typedef VALUE mapped_type;
        typedef MAP map_type;
        typedef CACHING_STRATEGY caching_strategy_type;
        typedef ITERATOR_IMPL ITERATOR_IMPLEMENTATION;
        typedef REVERSE_ITERATOR_IMPL REVERSE_ITERATOR_IMPLEMENTATION;
            friend class ACE_Cache_Map_Iterator<KEY, VALUE, ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>;

            friend class ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>;

            typedef ACE_Cache_Map_Iterator<KEY, VALUE, ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> ITERATOR;

            typedef ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> REVERSE_ITERATOR;

        typedef ITERATOR iterator;
        typedef REVERSE_ITERATOR reverse_iterator;
        typedef ACE_Pair<VALUE, ATTRIBUTES> CACHE_VALUE;
        ACE_Cache_Map_Manager (
            CACHING_STRATEGY &caching_strategy,
            size_t size = ACE_DEFAULT_MAP_SIZE,
            ACE_Allocator *alloc = 0
            );
        virtual ~ACE_Cache_Map_Manager (void);
        int open (
            size_t length = ACE_DEFAULT_MAP_SIZE,
            ACE_Allocator *alloc = 0
            );
        int close (void);
        int bind (const KEY &key, const VALUE &value);
        int find (const KEY &key, VALUE &value);
        int find (const KEY &key);
        int rebind (const KEY &key, const VALUE &value);
        int rebind (const KEY &key, const VALUE &value, VALUE &old_value);
        int rebind (
            const KEY &key,
            const VALUE &value,
            KEY &old_key,
            VALUE &old_value
            );
        int trybind (const KEY &key, VALUE &value);
        int unbind (const KEY &key);
        int unbind (const KEY &key, VALUE &value);
        int purge (void);
        size_t current_size (void) const;
        size_t total_size (void) const;
        void dump (void) const;
        ITERATOR begin (void);
        ITERATOR end (void);
        REVERSE_ITERATOR rbegin (void);
        REVERSE_ITERATOR rend (void);
        MAP &map (void);
        CACHING_STRATEGY &caching_strategy (void);
      protected:
        MAP map_;
        CACHING_STRATEGY &caching_strategy_;
      private:
        inline ACE_UNIMPLEMENTED_FUNC (
            void operator= (const ACE_Cache_Map_Manager<ACE_T2> &)
            );
    };

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

## Traits.

    typedef KEY key_type;

    typedef VALUE mapped_type;

    typedef MAP map_type;

    typedef CACHING_STRATEGY caching_strategy_type;

    typedef ITERATOR_IMPL ITERATOR_IMPLEMENTATION;

    typedef REVERSE_ITERATOR_IMPL REVERSE_ITERATOR_IMPLEMENTATION;

        friend class ACE_Cache_Map_Iterator<KEY, VALUE, ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>;

        friend class ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>;

## ACE-style iterator typedefs.

        typedef ACE_Cache_Map_Iterator<KEY, VALUE, ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> ITERATOR;

        typedef ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> REVERSE_ITERATOR;

## STL-style iterator typedefs.

    typedef ITERATOR iterator;

    typedef REVERSE_ITERATOR reverse_iterator;

    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.

    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.

    virtual ~ACE_Cache_Map_Manager (void);

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

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

Initialize a cache with size `length`.

    int close (void);

Close down a cache and release dynamically allocated resources.

    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.

    int find (const KEY &key, VALUE &value);

Loopkup entry`key,value` in the cache.

    int find (const KEY &key);

Is `key` in the cache?

    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.

    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.

    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.

    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.

    int unbind (const KEY &key);

Remove `key` from the cache.

    int unbind (const KEY &key, VALUE &value);

Remove `key` from the cache, and return the `value` associated with `key`.

    int purge (void);

Remove entries from the cache depending upon the strategy.

    size_t current_size (void) const;

Return the current size of the cache.

    size_t total_size (void) const;

Return the total size of the cache.

    void dump (void) const;

Dumps the state of the object.

## STL styled iterator factory functions.

    ITERATOR begin (void);

    ITERATOR end (void);

Return forward iterator.

    REVERSE_ITERATOR rbegin (void);

    REVERSE_ITERATOR rend (void);

Return reverse iterator.

    MAP &map (void);

The map managed by the Cache_Map_Manager.

    CACHING_STRATEGY &caching_strategy (void);

The caching strategy used on the cache.

## Disallow these operations.

    inline ACE_UNIMPLEMENTED_FUNC (
        void operator= (const ACE_Cache_Map_Manager<ACE_T2> &)
        );

## AUTHOR

Kirthika Parameswaran `kirthika@cs.wustl.edu`

## LIBRARY

ace