UT/UT_ThreadSafeCache.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Andrew Clinton
 *      Side Effects Software Inc
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * NAME:        UT_ThreadSafeCache.h ( UT Library, C++ )
 *
 * COMMENTS:    A fast, thread-safe cache to be used for high-performance
 *              applications.  See VRAY_BBoxCacheNode for example usage.
 */

#ifndef __UT_ThreadSafeCache__
#define __UT_ThreadSafeCache__

#include "UT_API.h"
#include <SYS/SYS_Types.h>
#include <SYS/SYS_AtomicInt.h>
#include <SYS/SYS_AtomicIntImpl.h>
#include "UT_LockUtil.h"

// Explicit instantiations are provided for:
// - UT_Lock
// - UT_SpinLock
template <class Lock>
class UT_API UT_ThreadSafeCache {
public:
    // A cache item stub.  You must implement a subclass to provide
    // allocation and deallocation routines.
    class UT_CacheItem
    {
    public:
                 UT_CacheItem()
                     : myPrev(0), myNext(0), myMemory(0)
                     , myRefCount(0), myTimeStamp(0)
                     , myAllocated(false) {}
        virtual ~UT_CacheItem() {}

    protected:
        // Allocate an item and return the total amount of memory consumed
        // by the cache item in bytes.
        virtual int64    allocate(void *parms) = 0;

        // Deallocate the item and free associated memory.
        virtual void     deallocate() = 0;

        // Retrieve the amount of memory consumed by the cache item
        int64            getMemoryUsage() const { return myMemory; }

    private:
        int              getRefCount() const    { return myRefCount; }
        void             incRefCount()          { myRefCount.add(1); }
        void             decRefCount()          { myRefCount.add(-1); }

        bool             isInCache() const      { return myNext; }

    private:
        UT_CacheItem    *myPrev;
        UT_CacheItem    *myNext;
        int64            myMemory;
        SYS_AtomicInt32  myRefCount;
        int              myTimeStamp;
        bool             myAllocated;

        friend class     UT_ThreadSafeCache;
    };

public:
    // The destroy flag controls whether the cache will clean up its
    // allocated items on destruction.
    // Fast access caches assume that for frequently accessed items, the
    // access() method can operate without locking.  For extremely small
    // caches, this may lead to multithreading errors - so an option is
    // provided to disable this feature.
     UT_ThreadSafeCache(bool destroy = true, bool fastaccess = true);
    ~UT_ThreadSafeCache();

    // Set cache size in megabytes
    void                setMaxMemory(int size_mb);

    // Get total cache memory usage in bytes, including all allocated item
    // memory.
    int64               getMemoryUsage() const    { return myMemoryUsed; }

    // Access an item in the cache.  If the item is not already in the
    // cache, it will be inserted at the head.  If the lock flag is true,
    // calling this operation acquires an access lock that must be released
    // with release().  parms will be passed directly to the allocate()
    // operation.
    void                access(UT_CacheItem *item,
                               bool lock = true, void *parms = 0);

    // Release the access lock an an item.  For every call to access()
    // there must be a corresponding call to release().
    void                release(UT_CacheItem *item);

    // Deallocates and removes an item from the cache.
    void                free(UT_CacheItem *item);

    // Clear all entries from the cache.
    void                freeAll();

private:
    void                addToCache(UT_CacheItem *item);
    void                removeFromCache(UT_CacheItem *item);
    void                allocateItem(UT_CacheItem *item, void *parms)
                        {
                            if (!item->myAllocated)
                            {
                                int handle = myObjLock.lock(item);
                                if (!item->myAllocated)
                                {
                                    item->myMemory = item->allocate(parms);
                                    item->myAllocated = true;
                                }
                                myObjLock.unlock(item, handle);
                            }
                        }

    // Heuristic to decide when an item is close to the head.  Items can
    // only be moved when this method returns false.
    bool                isNearHead(const UT_CacheItem *item) const
                        { return myHeadTime - item->myTimeStamp <=
                            myQuarterEntries; }

private:
    UT_ObjLockType<Lock>         myObjLock;
    Lock                         myThreadLock;
    int64                        myMemoryLimit;
    int64                        myMemoryLowWater;
    int64                        myMemoryUsed;
    UT_CacheItem                *myHead;
    int                          myEntries;
    int                          myQuarterEntries;
    int                          myHeadTime;
    bool                         myDestroy;
    bool                         myFastAccess;
};

#endif

---