ObjectPool.h

/* This file is Copyright 2000-2008 Meyer Sound Laboratories Inc.  See the included LICENSE.txt file for details. */

#ifndef MuscleObjectPool_h
#define MuscleObjectPool_h

#include "util/Queue.h"
#include "system/Mutex.h"

BEGIN_NAMESPACE(muscle);

// Uncomment this #define to disable object pools (i.e. turn them into
// fancy new/delete operators).  This is helpful if you are trying
// to track down memory leaks.
//#define DISABLE_OBJECT_POOLING 1

#ifndef MUSCLE_POOL_SLAB_SIZE
# define MUSCLE_POOL_SLAB_SIZE (4*1024)  // let's have each slab fit nicely into a 4KB page
#endif

class AbstractObjectGenerator
{
public:
   AbstractObjectGenerator() {/* empty */}

   virtual ~AbstractObjectGenerator() {/* empty */}

   virtual void * ObtainObjectGeneric() = 0;
};

class AbstractObjectRecycler
{
public:
   AbstractObjectRecycler();

   virtual ~AbstractObjectRecycler();

   virtual void RecycleObject(void * obj) = 0;

   virtual uint32 FlushCachedObjects() = 0;

   static void GlobalFlushAllCachedObjects();

private:
   AbstractObjectRecycler * _prev;
   AbstractObjectRecycler * _next;
};

class AbstractObjectManager : public AbstractObjectGenerator, public AbstractObjectRecycler
{
   // empty
};

template <class Object> class ObjectPool : public AbstractObjectManager
{
public:
   typedef void (*ObjectCallback)(Object * obj, void * userData);

   ObjectPool(uint32 maxPoolSize=100, 
              ObjectCallback recycleCallback = NULL, void * recycleData = NULL,
              ObjectCallback initCallback = NULL, void * initCallbackData = NULL) : 
      _initObjectFunc(initCallback), _initObjectUserData(initCallbackData),
      _recycleObjectFunc(recycleCallback), _recycleObjectUserData(recycleData),
      _curPoolSize(0), _maxPoolSize(maxPoolSize), _firstSlab(NULL), _lastSlab(NULL)
   {
      // empty
   }

   virtual ~ObjectPool()
   {
      while(_firstSlab)
      {
         if (_firstSlab->IsInUse()) 
         {
            LogTime(MUSCLE_LOG_CRITICALERROR, "~ObjectPool %p:  slab %p is still in use when we destroy it!\n", this, _firstSlab);
            MCRASH("ObjectPool destroyed while its objects were still in use (Is a CompleteSetupSystem object declared at the top of main()?");
         }
         ObjectSlab * nextSlab = _firstSlab->GetNext();
         delete _firstSlab;
         _firstSlab = nextSlab;
      }
   }

   Object * ObtainObject()
   {
#ifdef DISABLE_OBJECT_POOLING
      Object * ret = newnothrow Object;
      if (ret) 
      {
         ret->SetManager(this);
         if (_initObjectFunc) _initObjectFunc(ret, _initObjectUserData);
      }
      else WARN_OUT_OF_MEMORY;
      return ret;
#else
      Object * ret = NULL;
      if (_mutex.Lock() == B_NO_ERROR)
      {
         if ((_firstSlab)&&(_firstSlab->HasAvailableNodes()))
         {
            ret = _firstSlab->ObtainObjectNode();
            if ((_firstSlab->HasAvailableNodes() == false)&&(_firstSlab != _lastSlab))
            {
               // Move _firstSlab out of the way (to the end of the slab list) for next time
               ObjectSlab * tmp = _firstSlab;  // use temp var since _firstSlab will change
               tmp->RemoveFromSlabList();
               tmp->AppendToSlabList();
            }
         }
         else
         {
            // Hmm, we must have run out out of non-full slabs.  Create a new slab and use it.
            ObjectSlab * slab = newnothrow ObjectSlab(this);
            if (slab)
            {
               ret = slab->ObtainObjectNode();  // guaranteed not to fail, since slab is new
               if (slab->HasAvailableNodes()) slab->PrependToSlabList();
                                         else slab->AppendToSlabList();  // could happen, if NUM_OBJECTS_PER_SLAB==1
               _curPoolSize += NUM_OBJECTS_PER_SLAB;
            }
            // we'll do the WARN_OUT_OF_MEMORY below, outside the mutex lock
         }
         if (ret) --_curPoolSize;
         _mutex.Unlock();
      }
      if (ret)
      {
         ret->SetManager(this);
         if (_initObjectFunc) _initObjectFunc(ret, _initObjectUserData);
      }
      else WARN_OUT_OF_MEMORY;
      return ret;
#endif
   }

   void ReleaseObject(Object * obj)
   {
      if (obj)
      {
         MASSERT(obj->GetManager()==this, "ObjectPool::ReleaseObject was passed an object that it never allocated!");
         if (_recycleObjectFunc) _recycleObjectFunc(obj, _recycleObjectUserData);
         obj->SetManager(NULL);

#ifdef DISABLE_OBJECT_POOLING
         delete obj;
#else
         if (_mutex.Lock() == B_NO_ERROR)
         {
            ObjectSlab * slabToDelete = NULL;
            ObjectNode * objNode = static_cast<ObjectNode *>(obj);
            ObjectSlab * objSlab = objNode->GetSlab();

            objSlab->ReleaseNode(objNode);  // guaranteed to work, since we know (obj) is in use in (objSlab)

            if ((++_curPoolSize > (_maxPoolSize+NUM_OBJECTS_PER_SLAB))&&(objSlab->IsInUse() == false))
            {
               _curPoolSize -= NUM_OBJECTS_PER_SLAB;
               objSlab->RemoveFromSlabList();
               slabToDelete = objSlab;
            }
            else if (objSlab != _firstSlab) 
            {
               objSlab->RemoveFromSlabList();
               objSlab->PrependToSlabList();
            }
            _mutex.Unlock();

            delete slabToDelete;  // do this outside the critical section, for better concurrency
         }
         else WARN_OUT_OF_MEMORY;  // critical error -- not really out of memory but still
#endif
      }
   }

   virtual void * ObtainObjectGeneric() {return ObtainObject();}

   virtual void RecycleObject(void * obj) {ReleaseObject((Object *)obj);}
    
   status_t SetInitObjectCallback(ObjectCallback cb, void * userData)
   {
      if (_mutex.Lock() == B_NO_ERROR)
      {
         _initObjectFunc = cb;
         _initObjectUserData = userData;
         (void) _mutex.Unlock();
         return B_NO_ERROR;
      }
      else return B_ERROR;
   }

   void SetRecycleObjectCallback(ObjectCallback cb, void * userData)
   {
      if (_mutex.Lock() == B_NO_ERROR)
      {
         _recycleObjectFunc = cb;
         _recycleObjectUserData = userData;
         (void) _mutex.Unlock();
         return B_NO_ERROR;
      }
      else return B_ERROR;
   }

   virtual uint32 FlushCachedObjects() {uint32 ret = 0; (void) Drain(&ret); return ret;}

   status_t Drain(uint32 * optSetNumDrained = NULL)
   {
      if (_mutex.Lock() == B_NO_ERROR)
      {
         // This will be our linked list of slabs to delete, later
         ObjectSlab * toDelete = NULL;

         // Pull out all the slabs that are not currently in use
         ObjectSlab * slab = _firstSlab;
         while(slab)
         {
            ObjectSlab * nextSlab = slab->GetNext();
            if (slab->IsInUse() == false)
            {
               slab->RemoveFromSlabList();
               slab->SetNext(toDelete);
               toDelete = slab;
            }
            slab = nextSlab;
         }
         (void) _mutex.Unlock();

         // Do the actual slab deletions outside of the critical section, for better concurrency
         uint32 numObjectsDeleted = 0;
         while(toDelete)
         {
            ObjectSlab * nextSlab = toDelete->GetNext();

            numObjectsDeleted += NUM_OBJECTS_PER_SLAB;
            _curPoolSize -= NUM_OBJECTS_PER_SLAB;

            delete toDelete;
            toDelete = nextSlab;
         }

         if (optSetNumDrained) *optSetNumDrained = numObjectsDeleted;
         return B_NO_ERROR;
      }
      else return B_ERROR;
   }

   uint32 GetMaxPoolSize() const {return _maxPoolSize;}

   void SetMaxPoolSize(uint32 mps) {_maxPoolSize = mps;}

private:
   Mutex _mutex;

   ObjectCallback _initObjectFunc;
   void * _initObjectUserData;
   
   ObjectCallback _recycleObjectFunc;
   void * _recycleObjectUserData;

   class ObjectSlab;

   class ObjectNode : public Object
   {
   public:
      ObjectNode() : _slab(NULL), _next(NULL) {/* empty */}

      void SetSlab(ObjectSlab * slab) {_slab = slab;}
      ObjectSlab * GetSlab() const {return _slab;}

      void SetNext(ObjectNode * next) {_next = next;}
      ObjectNode * GetNext() const {return _next;}

   private:
      ObjectSlab * _slab;
      ObjectNode * _next;  // only used when we are in the free list
   };

   friend class ObjectSlab;  // for VC++ compatibility, this must be here

   // All the (int) casts are here so that it the user specifies a slab size of zero, we will get a negative
   // number and not a very large positive number that crashes the compiler!
   #define __POOL_OPS__ (((int)MUSCLE_POOL_SLAB_SIZE-(5*(int)sizeof(void *)))/(int)sizeof(ObjectNode))
   enum {NUM_OBJECTS_PER_SLAB = ((__POOL_OPS__>0)?__POOL_OPS__:1)};
   
   class ObjectSlab
   {
   public:
      // Note that _prev and _next are deliberately not set here... we don't use them until we are added to the list
      ObjectSlab(ObjectPool * pool) : _pool(pool), _firstFreeNode(NULL), _numNodesInUse(0)
      {
         for (int32 i=0; i<NUM_OBJECTS_PER_SLAB; i++)
         {
            ObjectNode * n = &_nodes[i];
            n->SetSlab(this);
            n->SetNext(_firstFreeNode);
            _firstFreeNode = n;
         }
      }

      bool HasAvailableNodes() const {return (_firstFreeNode != NULL);}

      bool IsInUse() const {return (_numNodesInUse > 0);}

      // Note:  this method assumes a node is available!  Don't call it without
      //        calling HasAvailableNodes() first to check, or you will crash!
      ObjectNode * ObtainObjectNode()
      {
         ObjectNode * ret = _firstFreeNode;
         _firstFreeNode = ret->GetNext();
         ++_numNodesInUse;
         return ret;
      }

      void ReleaseNode(ObjectNode * node)
      {
         node->SetNext(_firstFreeNode);
         _firstFreeNode = node; 
         --_numNodesInUse;
      }

      void RemoveFromSlabList()
      {
         (_prev ? _prev->_next : _pool->_firstSlab) = _next;
         (_next ? _next->_prev : _pool->_lastSlab)  = _prev;
      }

      void AppendToSlabList()
      {
         _prev = _pool->_lastSlab;
         _next = NULL;
         (_prev ? _prev->_next : _pool->_firstSlab) = _pool->_lastSlab = this;
      }

      void PrependToSlabList()
      {
         _prev = NULL;
         _next = _pool->_firstSlab;
         (_next ? _next->_prev : _pool->_lastSlab) = _pool->_firstSlab = this;
      }

      void SetNext(ObjectSlab * next) {_next = next;}
      ObjectSlab * GetNext() const {return _next;}

   private:
      ObjectPool * _pool;
      ObjectSlab * _prev;
      ObjectSlab * _next;
      ObjectNode * _firstFreeNode;
      uint32 _numNodesInUse;
      ObjectNode _nodes[NUM_OBJECTS_PER_SLAB];
   };

   uint32 _curPoolSize;  // tracks the current number of "available" objects
   uint32 _maxPoolSize;  // the maximum desired number of "available" objects
   ObjectSlab * _firstSlab;
   ObjectSlab * _lastSlab;
};

END_NAMESPACE(muscle);

#endif

---