Logo Search packages:      
Sourcecode: poco version File versions  Download package

AbstractCache.h
//
// AbstractCache.h
//
// $Id: //poco/1.3/Foundation/include/Poco/AbstractCache.h#2 $
//
// Library: Foundation
// Package: Cache
// Module:  AbstractCache
//
// Definition of the AbstractCache class.
//
// Copyright (c) 2006, Applied Informatics Software Engineering GmbH.
// and Contributors.
//
// Permission is hereby granted, free of charge, to any person or organization
// obtaining a copy of the software and accompanying documentation covered by
// this license (the "Software") to use, reproduce, display, distribute,
// execute, and transmit the Software, and to prepare derivative works of the
// Software, and to permit third-parties to whom the Software is furnished to
// do so, all subject to the following:
// 
// The copyright notices in the Software and this entire statement, including
// the above license grant, this restriction and the following disclaimer,
// must be included in all copies of the Software, in whole or in part, and
// all derivative works of the Software, unless such copies or derivative
// works are solely in the form of machine-executable object code generated by
// a source language processor.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
// SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
// FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//


#ifndef  Foundation_AbstractCache_INCLUDED
#define  Foundation_AbstractCache_INCLUDED


#include "Poco/KeyValueArgs.h"
#include "Poco/ValidArgs.h" 
#include "Poco/Mutex.h"
#include "Poco/Exception.h"
#include "Poco/FIFOEvent.h"
#include "Poco/EventArgs.h"
#include "Poco/Delegate.h"
#include "Poco/SharedPtr.h"
#include <map>
#include <set>
#include <cstddef>


namespace Poco {


template <class TKey, class TValue, class TStrategy> 
00060 class AbstractCache
      /// An AbstractCache is the interface of all caches. 
{
public:
      FIFOEvent<const KeyValueArgs<TKey, TValue > > Add;
      FIFOEvent<const TKey>                         Remove;
      FIFOEvent<const TKey>                         Get;
      FIFOEvent<const EventArgs>                    Clear;

      typedef std::map<TKey, SharedPtr<TValue > > DataHolder;
      typedef typename DataHolder::iterator       Iterator;
      typedef typename DataHolder::const_iterator ConstIterator;
      typedef std::set<TKey>                      KeySet;

      AbstractCache()
      {
            initialize();
      }

      AbstractCache(const TStrategy& strat): _strategy(strat)
      {
            initialize();
      }

      virtual ~AbstractCache()
      {
            uninitialize();
      }

00089       void add(const TKey& key, const TValue& val)
            /// Adds the key value pair to the cache.
            /// If for the key already an entry exists, it will be overwritten.
      {
            FastMutex::ScopedLock lock(_mutex);
            doAdd(key, val);
      }

00097       void add(const TKey& key, SharedPtr<TValue > val)
            /// Adds the key value pair to the cache. Note that adding a NULL SharedPtr will fail!
            /// If for the key already an entry exists, it will be overwritten.
      {
            FastMutex::ScopedLock lock(_mutex);
            doAdd(key, val);
      }

00105       void remove(const TKey& key)
            /// Removes an entry from the cache. If the entry is not found,
            /// the remove is ignored.
      {
            FastMutex::ScopedLock lock(_mutex);
            Iterator it = _data.find(key);
            doRemove(it);
      }

00114       bool has(const TKey& key) const
            /// Returns true if the cache contains a value for the key.
      {
            FastMutex::ScopedLock lock(_mutex);
            return doHas(key);
      }

00121       SharedPtr<TValue> get(const TKey& key)
            /// Returns a SharedPtr of the value. The SharedPointer will remain valid
            /// even when cache replacement removes the element.
            /// If for the key no value exists, an empty SharedPtr is returned.
      {
            FastMutex::ScopedLock lock(_mutex);
            return doGet (key);
      }

00130       void clear()
            /// Removes all elements from the cache.
      {
            FastMutex::ScopedLock lock(_mutex);
            doClear();
      }

00137       std::size_t size()
            /// Returns the number of cached elements
      {
            FastMutex::ScopedLock lock(_mutex);
            doReplace();
            return _data.size();
      }

00145       void forceReplace()
            /// Forces cache replacement. Note that Poco's cache strategy use for efficiency reason no background thread
            /// which periodically triggers cache replacement. Cache Replacement is only started when the cache is modified
            /// from outside, i.e. add is called, or when a user tries to access an cache element via get.
            /// In some cases, i.e. expire based caching where for a long time no access to the cache happens,
            /// it might be desirable to be able to trigger cache replacement manually.
      {
            FastMutex::ScopedLock lock(_mutex);
            doReplace();
      }

00156       std::set<TKey> getAllKeys()
            /// Returns a copy of all keys stored in the cache
      {
            FastMutex::ScopedLock lock(_mutex);
            doReplace();
            ConstIterator it = _data.begin();
            ConstIterator itEnd = _data.end();
            std::set<TKey> result;
            for (; it != itEnd; ++it)
                  result.insert(it->first);

            return result;
      }

protected:
      mutable FIFOEvent<ValidArgs<TKey> > IsValid;
      mutable FIFOEvent<KeySet>           Replace;

00174       void initialize()
            /// Sets up event registration.
      {
            Add         += Delegate<TStrategy, const KeyValueArgs<TKey, TValue> >(&_strategy, &TStrategy::onAdd);
            Remove      += Delegate<TStrategy, const TKey>(&_strategy, &TStrategy::onRemove);
            Get         += Delegate<TStrategy, const TKey>(&_strategy, &TStrategy::onGet);
            Clear += Delegate<TStrategy, const EventArgs>(&_strategy, &TStrategy::onClear);
            IsValid     += Delegate<TStrategy, ValidArgs<TKey> >(&_strategy, &TStrategy::onIsValid);
            Replace     += Delegate<TStrategy, KeySet>(&_strategy, &TStrategy::onReplace);
      }

00185       void uninitialize()
            /// Reverts event registration.
      {
            Add         -= Delegate<TStrategy, const KeyValueArgs<TKey, TValue> >(&_strategy, &TStrategy::onAdd );
            Remove      -= Delegate<TStrategy, const TKey>(&_strategy, &TStrategy::onRemove);
            Get         -= Delegate<TStrategy, const TKey>(&_strategy, &TStrategy::onGet);
            Clear -= Delegate<TStrategy, const EventArgs>(&_strategy, &TStrategy::onClear);
            IsValid     -= Delegate<TStrategy, ValidArgs<TKey> >(&_strategy, &TStrategy::onIsValid);
            Replace     -= Delegate<TStrategy, KeySet>(&_strategy, &TStrategy::onReplace);
      }

00196       void doAdd(const TKey& key, const TValue& val)
            /// Adds the key value pair to the cache.
            /// If for the key already an entry exists, it will be overwritten.
      {
            Iterator it = _data.find(key);
            doRemove(it);

            KeyValueArgs<TKey, TValue> args(key, val);
            Add.notify(this, args);
            _data.insert(std::make_pair(key, SharedPtr<TValue>(new TValue(val))));
            
            doReplace();
      }

00210       void doAdd(const TKey& key, SharedPtr<TValue>& val)
            /// Adds the key value pair to the cache.
            /// If for the key already an entry exists, it will be overwritten.
      {
            Iterator it = _data.find(key);
            doRemove(it);

            KeyValueArgs<TKey, TValue> args(key, *val);
            Add.notify(this, args);
            _data.insert(std::make_pair(key, val));
            
            doReplace();
      }

00224       void doRemove(Iterator it) 
            /// Removes an entry from the cache. If the entry is not found
            /// the remove is ignored.
      {
            if (it != _data.end())
            {
                  Remove.notify(this, it->first);
                  _data.erase(it);
            }
      }

00235       bool doHas(const TKey& key) const
            /// Returns true if the cache contains a value for the key
      {
            // ask the strategy if the key is valid
            ConstIterator it = _data.find(key);
            bool result = false;

            if (it != _data.end())
            {
                  ValidArgs<TKey> args(key);
                  IsValid.notify(this, args);
                  result = args.isValid();
            }

            return result;
      }

00252       SharedPtr<TValue> doGet(const TKey& key) 
            /// Returns a SharedPtr of the cache entry, returns 0 if for
            /// the key no value was found
      {
            Iterator it = _data.find(key);
            SharedPtr<TValue> result;

            if (it != _data.end())
            {     
                  // inform all strategies that a read-access to an element happens
                  Get.notify(this, key);
                  // ask all strategies if the key is valid
                  ValidArgs<TKey> args(key);
                  IsValid.notify(this, args);

                  if (!args.isValid())
                  {
                        doRemove(it);
                  }
                  else
                  {
                        result = it->second;
                  }
            }

            return result;
      }

      void doClear()
      {
            static EventArgs _emptyArgs;
            Clear.notify(this, _emptyArgs);
            _data.clear();
      }

      void doReplace()
      {
            std::set<TKey> delMe;
            Replace.notify(this, delMe);
            // delMe contains the to be removed elements
            typename std::set<TKey>::const_iterator it    = delMe.begin();
            typename std::set<TKey>::const_iterator endIt = delMe.end();

            for (; it != endIt; ++it)
            {
                  Iterator itH = _data.find(*it);
                  doRemove(itH);
            }
      }

      TStrategy          _strategy;
      mutable DataHolder _data;
      mutable FastMutex  _mutex;

private:
      AbstractCache(const AbstractCache& aCache);
      AbstractCache& operator = (const AbstractCache& aCache);
};


} // namespace Poco


#endif

Generated by  Doxygen 1.6.0   Back to index