safecoll.h

Go to the documentation of this file.

/*
 * safecoll.h
 *
 * Thread safe collection classes.
 *
 * Portable Windows Library
 *
 * Copyright (c) 2002 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): ______________________________________.
 *
 * $Revision: 24177 $
 * $Author: rjongbloed $
 * $Date: 2010-04-05 06:52:04 -0500 (Mon, 05 Apr 2010) $
 */
 
#ifndef PTLIB_SAFE_COLLECTION_H
#define PTLIB_SAFE_COLLECTION_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif


class PSafeObject : public PObject
{
    PCLASSINFO(PSafeObject, PObject);
  public:
    PSafeObject(
        PSafeObject * indirectLock = NULL 
    );

    PBoolean SafeReference();

    PBoolean SafeDereference();

    PBoolean LockReadOnly() const;

    void UnlockReadOnly() const;

    PBoolean LockReadWrite();

    void UnlockReadWrite();

    void SafeRemove();

    PBoolean SafelyCanBeDeleted() const;

    virtual bool GarbageCollection();

  private:
    mutable PMutex    safetyMutex;
    unsigned          safeReferenceCount;
    bool              safelyBeingRemoved;
    PReadWriteMutex   safeInUseMutex;
    PReadWriteMutex * safeInUse;

  friend class PSafeCollection;
};


class PSafeLockReadOnly
{
  public:
    PSafeLockReadOnly(const PSafeObject & object);
    ~PSafeLockReadOnly();
    PBoolean Lock();
    void Unlock();
    PBoolean IsLocked() const { return locked; }
    bool operator!() const { return !locked; }

  protected:
    PSafeObject & safeObject;
    PBoolean          locked;
};



class PSafeLockReadWrite
{
  public:
    PSafeLockReadWrite(const PSafeObject & object);
    ~PSafeLockReadWrite();
    PBoolean Lock();
    void Unlock();
    PBoolean IsLocked() const { return locked; }
    bool operator!() const { return !locked; }

  protected:
    PSafeObject & safeObject;
    PBoolean          locked;
};



class PSafeCollection : public PObject
{
    PCLASSINFO(PSafeCollection, PObject);
  public:
    PSafeCollection(
      PCollection * collection    
     );

    ~PSafeCollection();

  protected:
    virtual PBoolean SafeRemove(
      PSafeObject * obj   
    );

    virtual PBoolean SafeRemoveAt(
      PINDEX idx    
    );

  public:
    virtual void RemoveAll(
      PBoolean synchronous = false  
    );

    void AllowDeleteObjects(
      PBoolean yes = true   
    ) { deleteObjects = yes; }

    void DisallowDeleteObjects() { deleteObjects = false; }

    virtual PBoolean DeleteObjectsToBeRemoved();

    virtual void DeleteObject(PObject * object) const;

    virtual void SetAutoDeleteObjects();

    PINDEX GetSize() const;

    PBoolean IsEmpty() const { return GetSize() == 0; }

    const PMutex & GetMutex() const { return collectionMutex; }

  protected:
    void SafeRemoveObject(PSafeObject * obj);
    PDECLARE_NOTIFIER(PTimer, PSafeCollection, DeleteObjectsTimeout);

    PCollection  *     collection;
    mutable PMutex     collectionMutex;
    PBoolean               deleteObjects;
    PList<PSafeObject> toBeRemoved;
    PMutex             removalMutex;
    PTimer             deleteObjectsTimer;

  friend class PSafePtrBase;
};


enum PSafetyMode {
  PSafeReference,
  PSafeReadOnly,
  PSafeReadWrite
};

class PSafePtrBase : public PObject
{
    PCLASSINFO(PSafePtrBase, PObject);

  protected:
    PSafePtrBase(
      PSafeObject * obj = NULL,         
      PSafetyMode mode = PSafeReference 
    );

    PSafePtrBase(
      const PSafeCollection & safeCollection, 
      PSafetyMode mode,                       
      PINDEX idx                              
    );

    PSafePtrBase(
      const PSafeCollection & safeCollection, 
      PSafetyMode mode,                       
      PSafeObject * obj                       
    );

    PSafePtrBase(
      const PSafePtrBase & enumerator   
    );

  public:
    ~PSafePtrBase();

    virtual Comparison Compare(
      const PObject & obj   
    ) const;

    virtual void SetNULL();

    bool operator!() const { return currentObject == NULL; }

    PSafetyMode GetSafetyMode() const { return lockMode; }

    virtual PBoolean SetSafetyMode(
      PSafetyMode mode  
    );

    const PSafeCollection * GetCollection() const { return collection; }

    virtual void Assign(const PSafePtrBase & ptr);
    virtual void Assign(const PSafeCollection & safeCollection);
    virtual void Assign(PSafeObject * obj);
    virtual void Assign(PINDEX idx);

  protected:
    virtual void Next();
    virtual void Previous();
    virtual void DeleteObject(PSafeObject * obj);

    enum EnterSafetyModeOption {
      WithReference,
      AlreadyReferenced
    };
    PBoolean EnterSafetyMode(EnterSafetyModeOption ref);

    enum ExitSafetyModeOption {
      WithDereference,
      NoDereference
    };
    void ExitSafetyMode(ExitSafetyModeOption ref);

  protected:
    const PSafeCollection * collection;
    PSafeObject           * currentObject;
    PSafetyMode             lockMode;
};


class PSafePtrMultiThreaded : public PSafePtrBase
{
    PCLASSINFO(PSafePtrMultiThreaded, PSafePtrBase);

  protected:
    PSafePtrMultiThreaded(
      PSafeObject * obj = NULL,         
      PSafetyMode mode = PSafeReference 
    );

    PSafePtrMultiThreaded(
      const PSafeCollection & safeCollection, 
      PSafetyMode mode,                       
      PINDEX idx                              
    );

    PSafePtrMultiThreaded(
      const PSafeCollection & safeCollection, 
      PSafetyMode mode,                       
      PSafeObject * obj                       
    );

    PSafePtrMultiThreaded(
      const PSafePtrMultiThreaded & enumerator   
    );

  public:
    ~PSafePtrMultiThreaded();

    virtual Comparison Compare(
      const PObject & obj   
    ) const;

    virtual void SetNULL();

    virtual PBoolean SetSafetyMode(
      PSafetyMode mode  
    );

    virtual void Assign(const PSafePtrMultiThreaded & ptr);
    virtual void Assign(const PSafePtrBase & ptr);
    virtual void Assign(const PSafeCollection & safeCollection);
    virtual void Assign(PSafeObject * obj);
    virtual void Assign(PINDEX idx);

  protected:
    virtual void Next();
    virtual void Previous();
    virtual void DeleteObject(PSafeObject * obj);

    void Lock() { m_mutex.Wait(); }
    void Unlock();

  protected:
    mutable PMutex m_mutex;
    PSafeObject  * m_objectToDelete;
};


template <class T, class BaseClass = PSafePtrBase> class PSafePtr : public BaseClass
{
  public:
    PSafePtr(
      T * obj = NULL,                   
      PSafetyMode mode = PSafeReference 
    ) : BaseClass(obj, mode) { }

    PSafePtr(
      const PSafeCollection & safeCollection, 
      PSafetyMode mode = PSafeReadWrite,      
      PINDEX idx = 0                          
    ) : BaseClass(safeCollection, mode, idx) { }

    PSafePtr(
      const PSafeCollection & safeCollection, 
      PSafetyMode mode,                       
      PSafeObject * obj                       
    ) : BaseClass(safeCollection, mode, obj) { }

    PSafePtr(
      const PSafePtr & ptr   
    ) : BaseClass(ptr) { }

    PSafePtr & operator=(const PSafePtr & ptr)
      {
        BaseClass::Assign(ptr);
        return *this;
      }

    PSafePtr & operator=(const PSafeCollection & safeCollection)
      {
        BaseClass::Assign(safeCollection);
        return *this;
      }

    PSafePtr & operator=(T * obj)
      {
        Assign(obj);
        return *this;
      }

    PSafePtr & operator=(PINDEX idx)
      {
        BaseClass::Assign(idx);
        return *this;
      }

    operator T*()    const { return  (T *)BaseClass::currentObject; }

    T & operator*()  const { return *(T *)PAssertNULL(BaseClass::currentObject); }

    T * operator->() const { return  (T *)PAssertNULL(BaseClass::currentObject); }

    T * operator++(int)
      {
        T * previous = (T *)BaseClass::currentObject;
        BaseClass::Next();
        return previous;
      }

    T * operator++()
      {
        BaseClass::Next();
        return (T *)BaseClass::currentObject;
      }

    T * operator--(int)
      {
        T * previous = (T *)BaseClass::currentObject;
        BaseClass::Previous();
        return previous;
      }

    T * operator--()
      {
        BaseClass::Previous();
        return (T *)BaseClass::currentObject;
      }

      /*
  template <class Base>
  static PSafePtr<T> DownCast(const PSafePtr<Base> & oldPtr)
  {
    PSafePtr<T> newPtr;
    Base * realPtr = oldPtr;
    if (realPtr != NULL && PIsDescendant(realPtr, T))
      newPtr.Assign(oldPtr);
    return newPtr;
  }
  */
};


template <class Base, class Derived>
PSafePtr<Derived> PSafePtrCast(const PSafePtr<Base> & oldPtr)
{
//  return PSafePtr<Derived>::DownCast<Base>(oldPtr);
    PSafePtr<Derived> newPtr;
    Base * realPtr = oldPtr;
    if (realPtr != NULL && PIsDescendant(realPtr, Derived))
      newPtr.Assign(oldPtr);
    return newPtr;
}


template <class Coll, class Base> class PSafeColl : public PSafeCollection
{
    PCLASSINFO(PSafeColl, PSafeCollection);
  public:
    PSafeColl()
      : PSafeCollection(new Coll)
      { }

    virtual PSafePtr<Base> Append(
      Base * obj,       
      PSafetyMode mode = PSafeReference   
    ) {
        PWaitAndSignal mutex(collectionMutex);
        if (PAssert(collection->GetObjectsIndex(obj) == P_MAX_INDEX, "Cannot insert safe object twice") &&
            obj->SafeReference())
          return PSafePtr<Base>(*this, mode, collection->Append(obj));
        return NULL;
      }

    virtual PBoolean Remove(
      Base * obj          
    ) {
        return SafeRemove(obj);
      }

    virtual PBoolean RemoveAt(
      PINDEX idx     
    ) {
        return SafeRemoveAt(idx);
      }

    virtual PSafePtr<Base> GetAt(
      PINDEX idx,
      PSafetyMode mode = PSafeReadWrite
    ) {
        return PSafePtr<Base>(*this, mode, idx);
      }

    virtual PSafePtr<Base> FindWithLock(
      const Base & value,
      PSafetyMode mode = PSafeReadWrite
    ) {
        collectionMutex.Wait();
        PSafePtr<Base> ptr(*this, PSafeReference, collection->GetValuesIndex(value));
        collectionMutex.Signal();
        ptr.SetSafetyMode(mode);
        return ptr;
      }
};


template <class Base> class PSafeArray : public PSafeColl<PArray<Base>, Base>
{
  public:
    typedef PSafePtr<Base> value_type;
};


template <class Base> class PSafeList : public PSafeColl<PList<Base>, Base>
{
  public:
    typedef PSafePtr<Base> value_type;
};


template <class Base> class PSafeSortedList : public PSafeColl<PSortedList<Base>, Base>
{
  public:
    typedef PSafePtr<Base> value_type;
};


template <class Coll, class Key, class Base> class PSafeDictionaryBase : public PSafeCollection
{
    PCLASSINFO(PSafeDictionaryBase, PSafeCollection);
  public:
    PSafeDictionaryBase()
      : PSafeCollection(new Coll) { }

    virtual void SetAt(const Key & key, Base * obj)
      {
        collectionMutex.Wait();
        SafeRemove(((Coll *)collection)->GetAt(key));
        if (PAssert(collection->GetObjectsIndex(obj) == P_MAX_INDEX, "Cannot insert safe object twice") &&
            obj->SafeReference())
          ((Coll *)collection)->SetAt(key, obj);
        collectionMutex.Signal();
      }

    virtual PBoolean RemoveAt(
      const Key & key   
    ) {
        PWaitAndSignal mutex(collectionMutex);
        return SafeRemove(((Coll *)collection)->GetAt(key));
      }

    virtual PBoolean Contains(
      const Key & key
    ) {
        PWaitAndSignal lock(collectionMutex);
        return ((Coll *)collection)->Contains(key);
      }

    virtual PSafePtr<Base> GetAt(
      PINDEX idx,
      PSafetyMode mode = PSafeReadWrite
    ) {
        return PSafePtr<Base>(*this, mode, idx);
      }

    virtual PSafePtr<Base> FindWithLock(
      const Key & key,
      PSafetyMode mode = PSafeReadWrite
    ) {
        collectionMutex.Wait();
        PSafePtr<Base> ptr(*this, PSafeReference, ((Coll *)collection)->GetAt(key));
        collectionMutex.Signal();
        ptr.SetSafetyMode(mode);
        return ptr;
      }
};


template <class Key, class Base> class PSafeDictionary : public PSafeDictionaryBase<PDictionary<Key, Base>, Key, Base>
{
  public:
    typedef PSafePtr<Base> value_type;
};


#endif // PTLIB_SAFE_COLLECTION_H


// End Of File ///////////////////////////////////////////////////////////////

---