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): ______________________________________.
 *
 * $Log: safecoll.h,v $
 * Revision 1.17  2007/06/09 05:43:55  rjongbloed
 * Added ability for PSafePtr to be used as an garbage collecting pointer when not
 *   contained within a collection. Last PSafePtr reference to go out of scope deletes
 *   the object, provided it has never been in a PSafeCollection.
 *
 * Revision 1.16  2007/04/20 02:31:14  rjongbloed
 * Added ability to share a single mutex amongst multiple PSafeObjects,
 *   this can help with certain deadlock scenarios.
 *
 * Revision 1.15  2005/11/25 03:43:47  csoutheren
 * Fixed function argument comments to be compatible with Doxygen
 *
 * Revision 1.14  2004/11/08 02:34:18  csoutheren
 * Refactored code to (hopefully) compile on Linux
 *
 * Revision 1.13  2004/11/07 12:55:38  rjongbloed
 * Fixed safe ptr casting so keeps associated collection for use in for loops.
 *
 * Revision 1.12  2004/10/28 12:19:44  rjongbloed
 * Added oeprator! to assure test for NULL that some people use is correct for PSafePtr
 *
 * Revision 1.11  2004/10/14 12:31:45  rjongbloed
 * Added synchronous mode for safe collection RemoveAll() to wait until all objects
 *   have actually been deleted before returning.
 *
 * Revision 1.10  2004/10/04 12:54:33  rjongbloed
 * Added functions for locking an unlocking to "auto-unlock" classes.
 *
 * Revision 1.9  2004/08/12 12:37:40  rjongbloed
 * Fixed bug recently introduced so removes deleted object from deletion list.
 * Also changed removal list to be correct type.
 *
 * Revision 1.8  2004/08/05 12:15:56  rjongbloed
 * Added classes for auto unlocking read only and read write mutex on
 *   PSafeObject - similar to PWaitAndSIgnal.
 * Utilised mutable keyword for mutex and improved the constness of functions.
 * Added DisallowDeleteObjects to safe collections so can have a PSafeObject in
 *   multiple collections.
 * Added a tempalte function to do casting of PSafePtr to a PSafePtr of a derived
 *   class.
 * Assured that a PSafeObject present on a collection always increments its
 *   reference count so while in collection it is not deleted.
 *
 * Revision 1.7  2002/12/10 07:36:57  robertj
 * Fixed possible deadlock in PSafeCollection find functions.
 *
 * Revision 1.6  2002/10/29 00:06:14  robertj
 * Changed template classes so things like PSafeList actually creates the
 *   base collection class as well.
 * Allowed for the PSafeList::Append() to return a locked pointer to the
 *   object just appended.
 *
 * Revision 1.5  2002/10/04 08:22:40  robertj
 * Changed read/write mutex so can be called by same thread without deadlock
 *   removing the need to a lock count in safe pointer.
 * Added asserts if try and dereference a NULL safe pointer.
 * Added more documentation on behaviour.
 *
 * Revision 1.4  2002/09/16 01:08:59  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 1.3  2002/08/29 06:51:11  robertj
 * Added optimisiation, separate mutex for toBeRemoved list.
 *
 * Revision 1.2  2002/05/06 00:44:45  robertj
 * Made the lock/unlock read only const so can be used in const functions.
 *
 * Revision 1.1  2002/05/01 04:16:43  robertj
 * Added thread safe collection classes.
 *
 */
 
#ifndef _SAFE_COLLECTION_H
#define _SAFE_COLLECTION_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif


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

    BOOL SafeReference();

    BOOL SafeDereference();

    BOOL LockReadOnly() const;

    void UnlockReadOnly() const;

    BOOL LockReadWrite();

    void UnlockReadWrite();

    void SafeRemove();

    BOOL SafelyCanBeDeleted() const;

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


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

  protected:
    PSafeObject & safeObject;
    BOOL          locked;
};



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

  protected:
    PSafeObject & safeObject;
    BOOL          locked;
};



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

    ~PSafeCollection();

  protected:
    virtual BOOL SafeRemove(
      PSafeObject * obj   
    );

    virtual BOOL SafeRemoveAt(
      PINDEX idx    
    );

  public:
    virtual void RemoveAll(
      BOOL synchronous = FALSE  
    );

    void AllowDeleteObjects(
      BOOL yes = TRUE   
    ) { deleteObjects = yes; }

    void DisallowDeleteObjects() { deleteObjects = FALSE; }

    virtual BOOL DeleteObjectsToBeRemoved();

    virtual void DeleteObject(PObject * object) const;

    virtual void SetAutoDeleteObjects();

    PINDEX GetSize() const;

    BOOL 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;
    BOOL               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();

    Comparison Compare(
      const PObject & obj   
    ) const;

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

    PSafetyMode GetSafetyMode() const { return lockMode; }

    BOOL SetSafetyMode(
      PSafetyMode mode  
    );

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

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

  protected:
    void Next();
    void Previous();

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

    T * operator--()
      {
        Previous();
        return (T *)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 (!obj->SafeReference())
          return NULL;
        return PSafePtr<Base>(*this, mode, collection->Append(obj));
      }

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

    virtual BOOL 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>
{
};


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


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


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 (obj->SafeReference())
          ((Coll *)collection)->SetAt(key, obj);
        collectionMutex.Signal();
      }

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

    virtual BOOL 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>
{
};


#endif // _SAFE_COLLECTION_H

---