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: 30263 $
 * $Author: rjongbloed $
 * $Date: 2013-08-07 16:37:36 +1000 (Wed, 07 Aug 2013) $
 */
 
#ifndef PTLIB_SAFE_COLLECTION_H
#define PTLIB_SAFE_COLLECTION_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif


#include <ptlib/syncthrd.h>


class PTimer;


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

    unsigned GetSafeReferenceCount() const { return safeReferenceCount; }

  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 PrintOn(
      ostream &strm   // Stream to print the object into.
    ) const;

    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 CopySafeCollection(PCollection * other);
    void CopySafeDictionary(PAbstractDictionary * other);
    bool SafeAddObject(PSafeObject * obj, PSafeObject * old);
    void SafeRemoveObject(PSafeObject * obj);
    PDECLARE_NOTIFIER(PTimer, PSafeCollection, DeleteObjectsTimeout);

    PCollection      * collection;
    mutable PMutex     collectionMutex;
    bool               deleteObjects;
    PList<PSafeObject> toBeRemoved;
    PMutex             removalMutex;
    PTimer           * m_deleteObjectsTimer;

  private:
    PSafeCollection(const PSafeCollection & other) : PObject(other) { }
    void operator=(const PSafeCollection &) { }

  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 PrintOn(
      ostream &strm   // Stream to print the object into.
    ) const;

    virtual void SetNULL();

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

    PSafeObject * GetObject() const { return currentObject; }

    template <class T>
    T * GetObjectAs() const { return dynamic_cast<T *>(currentObject); }

    PSafetyMode GetSafetyMode() const { return lockMode; }

    virtual PBoolean SetSafetyMode(
      PSafetyMode mode  
    );

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

    virtual void LockPtr() { }
    virtual void UnlockPtr() { }

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

    virtual void LockPtr() { m_mutex.Wait(); }
    virtual void UnlockPtr();

  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)
      {
        this->Assign(obj);
        return *this;
      }

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

    PSafePtr Set(T * obj)
      {
        this->LockPtr();
        PSafePtr oldPtr = *this;
        this->Assign(obj);
        this->UnlockPtr();
        return oldPtr;
      }

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

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

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

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

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

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

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


template <class Base, class Derived>
PSafePtr<Derived> PSafePtrCast(const PSafePtr<Base> & oldPtr)
{
    PSafePtr<Derived> newPtr;
    if (dynamic_cast<Derived *>(oldPtr.GetObject()) != NULL)
      newPtr.Assign(oldPtr);
    return newPtr;
}


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

    PSafeColl(const PSafeColl & other)
      : PSafeCollection(new Coll)
    {
      PWaitAndSignal lock2(other.collectionMutex);
      CopySafeCollection(dynamic_cast<Coll *>(other.collection));
    }

    PSafeColl & operator=(const PSafeColl & other)
    {
      if (&other != this) {
        RemoveAll(true);
        PWaitAndSignal lock1(collectionMutex);
        PWaitAndSignal lock2(other.collectionMutex);
        CopySafeCollection(dynamic_cast<Coll *>(other.collection));
      }
      return *this;
    }

    virtual PSafePtr<Base> Append(
      Base * obj,       
      PSafetyMode mode = PSafeReference   
    ) {
        PWaitAndSignal mutex(collectionMutex);
        if (SafeAddObject(obj, NULL))
          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_WITH_CLONE(PSafeDictionaryBase, PSafeCollection);
  public:
    PSafeDictionaryBase()
      : PSafeCollection(new Coll) { }

    PSafeDictionaryBase(const PSafeDictionaryBase & other)
      : PSafeCollection(new Coll)
    {
      PWaitAndSignal lock2(other.collectionMutex);
      CopySafeDictionary(dynamic_cast<Coll *>(other.collection));
    }

    PSafeDictionaryBase & operator=(const PSafeDictionaryBase & other)
    {
      if (&other != this) {
        RemoveAll(true);
        PWaitAndSignal lock1(collectionMutex);
        PWaitAndSignal lock2(other.collectionMutex);
        CopySafeDictionary(dynamic_cast<Coll *>(other.collection));
      }
      return *this;
    }

    virtual void SetAt(const Key & key, Base * obj)
      {
        collectionMutex.Wait();
        if (SafeAddObject(obj, dynamic_cast<Coll &>(*collection).GetAt(key)))
          dynamic_cast<Coll &>(*collection).SetAt(key, obj);
        collectionMutex.Signal();
      }

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

    virtual PBoolean Contains(
      const Key & key
    ) {
        PWaitAndSignal lock(collectionMutex);
        return dynamic_cast<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
    ) const {
        collectionMutex.Wait();
        PSafePtr<Base> ptr(*this, PSafeReference, dynamic_cast<Coll &>(*collection).GetAt(key));
        collectionMutex.Signal();
        ptr.SetSafetyMode(mode);
        return ptr;
      }

    PArray<Key> GetKeys() const
    {
      PArray<Key> keys;
      collectionMutex.Wait();
      dynamic_cast<Coll &>(*collection).AbstractGetKeys(keys);
      collectionMutex.Signal();
      return keys;
    }
};


template <class K, class D>
 class PSafeDictionary : public PSafeDictionaryBase<PDictionary<K, D>, K, D>
{
  public:
    typedef K key_type;
    typedef D data_type;
    typedef PSafePtr<D> value_type;
    typedef PSafeDictionary<K, D> dict_type;

    class iterator;
    class const_iterator;
    class iterator_base {
      protected:
        K * m_internal_first;  // Must be first two members
        value_type m_internal_second;

        const dict_type * m_dictionary;
        PArray<K>   m_keys;
        PINDEX      m_position;

        iterator_base()
          : m_internal_first(NULL)
          , m_internal_second(NULL)
          , m_dictionary(NULL)
          , m_position(P_MAX_INDEX)
        {
        }

        iterator_base(const dict_type * dict)
          : m_dictionary(dict)
          , m_keys(dict->GetKeys())
        {
          this->SetPosition(0);
        }

        iterator_base(const dict_type * dict, const K & key)
          : m_dictionary(dict)
          , m_keys(dict->GetKeys())
        {
          this->SetPosition(m_keys.GetValuesIndex(key));
        }

        bool SetPosition(PINDEX position)
        {
          if (position >= this->m_keys.GetSize()) {
            this->m_position = P_MAX_INDEX;
            this->m_internal_first = NULL;
            this->m_internal_second.SetNULL();
            return false;
          }

          this->m_position = position;
          this->m_internal_first  = &this->m_keys[position];
          this->m_internal_second = this->m_dictionary->FindWithLock(*this->m_internal_first, PSafeReference);
          return this->m_internal_second == NULL;
        }

        void Next() { while (this->SetPosition(this->m_position+1)) { } }
        void Prev() { while (this->SetPosition(this->m_position > 0 ? this->m_position+1 : P_MAX_INDEX)) { } }

      public:
        bool operator==(const iterator_base & it) const { return this->m_position == it.m_position; }
        bool operator!=(const iterator_base & it) const { return this->m_position != it.m_position; }
    };

    class iterator_pair {
      public:
        const K & first;
        value_type second;

      private:
        iterator_pair() : first(reinterpret_cast<const K &>(0)) { }
    };

    class iterator : public iterator_base, public std::iterator<std::forward_iterator_tag, iterator_pair> {
      protected:
        iterator(dict_type * dict) : iterator_base(dict) { }
        iterator(dict_type * dict, const K & key) : iterator_base(dict, key) { }

      public:
        iterator() { }

        iterator operator++()    {                      this->Next(); return *this; }
        iterator operator--()    {                      this->Prev(); return *this; }
        iterator operator++(int) { iterator it = *this; this->Next(); return it;    }
        iterator operator--(int) { iterator it = *this; this->Prev(); return it;    }

        const iterator_pair * operator->() const { return  reinterpret_cast<const iterator_pair *>(this); }
        const iterator_pair & operator* () const { return *reinterpret_cast<const iterator_pair *>(this); }

      friend class PSafeDictionary<K, D>;
    };

    iterator begin() { return iterator(this); }
    iterator end()   { return iterator(); }
    iterator find(const K & key) { return iterator(this, key); }


    class const_iterator : public iterator_base, public std::iterator<std::forward_iterator_tag, iterator_pair> {
      protected:
        const_iterator(const dict_type * dict) : iterator_base(dict) { }
        const_iterator(const dict_type * dict, const K & key) : iterator_base(dict, key) { }

      public:
        const_iterator() { }
        const_iterator(const typename dict_type::iterator & it) : iterator_base(it) { }

        const_iterator operator++()    {                            this->Next(); return *this; }
        const_iterator operator--()    {                            this->Prev(); return *this; }
        const_iterator operator++(int) { const_iterator it = *this; this->Next(); return it;    }
        const_iterator operator--(int) { const_iterator it = *this; this->Prev(); return it;    }

        const iterator_pair * operator->() const { return  reinterpret_cast<const iterator_pair *>(this); }
        const iterator_pair & operator* () const { return *reinterpret_cast<const iterator_pair *>(this); }

      friend class PSafeDictionary<K, D>;
    };

    const_iterator begin() const { return const_iterator(this); }
    const_iterator end()   const { return const_iterator(); }
    const_iterator find(const K & key) const { return const_iterator(this, key); }

    void erase(const       iterator & it) { this->RemoveAt(it->first); }
    void erase(const const_iterator & it) { this->RemoveAt(it->first); }
};


#endif // PTLIB_SAFE_COLLECTION_H


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