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): ______________________________________.
 */
 
#ifndef PTLIB_SAFE_COLLECTION_H
#define PTLIB_SAFE_COLLECTION_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif


#include <ptlib/syncthrd.h>


#if P_TIMERS
class PTimer;
#endif


class PSafeObject : public PObject
{
    PCLASSINFO(PSafeObject, PObject);
  public:
    PSafeObject();
    PSafeObject(
      const PSafeObject & other 
    );
    explicit PSafeObject(
      PSafeObject * indirectLock 
    );
    explicit PSafeObject(
      PReadWriteMutex & mutex 
    );
    ~PSafeObject();

    PBoolean SafeReference();

    PBoolean SafeDereference();

    __inline bool LockReadOnly() const { return InternalLockReadOnly(NULL); }
    __inline bool LockReadOnly(const PDebugLocation & location) const { return InternalLockReadOnly(&location); }

    __inline void UnlockReadOnly() const { InternalUnlockReadOnly(NULL); }
    __inline void UnlockReadOnly(const PDebugLocation & location) const { InternalUnlockReadOnly(&location); }

    __inline bool LockReadWrite() const { return InternalLockReadWrite(NULL); }
    __inline bool LockReadWrite(const PDebugLocation & location) const { return InternalLockReadWrite(&location); }

    __inline void UnlockReadWrite() const { InternalUnlockReadWrite(NULL); }
    __inline void UnlockReadWrite(const PDebugLocation & location) const { InternalUnlockReadWrite(&location); }

    void SafeRemove();

    unsigned IsSafelyBeingRemoved() const { return m_safelyBeingRemoved; }

    PBoolean SafelyCanBeDeleted() const;

    virtual bool GarbageCollection();

    unsigned GetSafeReferenceCount() const { PWaitAndSignal lock(m_safetyMutex); return m_safeReferenceCount; }

  private:
    void operator=(const PSafeObject &) { }

    bool InternalLockReadOnly(const PDebugLocation * location) const;
    void InternalUnlockReadOnly(const PDebugLocation * location) const;
    bool InternalLockReadWrite(const PDebugLocation * location) const;
    void InternalUnlockReadWrite(const PDebugLocation * location) const;
    PReadWriteMutex & InternalGetMutex() const;

    mutable PCriticalSection m_safetyMutex;
    unsigned          m_safeReferenceCount;
    bool              m_safelyBeingRemoved;
    bool              m_safeMutexCreated;
    PReadWriteMutex * m_safeInUseMutex;

  friend class PSafeCollection;
  friend class PSafePtrBase;
  friend class PSafeLockReadOnly;
  friend class PSafeLockReadWrite;
  friend class PInstrumentedSafeLockReadOnly;
  friend class PInstrumentedSafeLockReadWrite;
};


class PSafeLockBase
{
  protected:
    typedef bool (PSafeObject:: * LockFn)(const PDebugLocation * location) const;
    typedef void (PSafeObject:: * UnlockFn)(const PDebugLocation * location) const;

    PSafeLockBase(const PSafeObject & object, const PDebugLocation * location, LockFn lock, UnlockFn unlock);

  public:
    ~PSafeLockBase();

    bool Lock();
    void Unlock();

    bool IsLocked() const { return m_locked; }
    bool operator!() const { return !m_locked; }

  protected:
    PSafeObject  & m_safeObject;
    PDebugLocation m_location;
    LockFn         m_lock;
    UnlockFn       m_unlock;
    bool           m_locked;
};


class PSafeLockReadOnly : public PSafeLockBase
{
  public:
    PSafeLockReadOnly(const PSafeObject & object)
      : PSafeLockBase(object, NULL, &PSafeObject::InternalLockReadOnly, &PSafeObject::InternalUnlockReadOnly)
    { }
};


class PSafeLockReadWrite : public PSafeLockBase
{
  public:
    PSafeLockReadWrite(const PSafeObject & object)
      : PSafeLockBase(object, NULL, &PSafeObject::InternalLockReadWrite, &PSafeObject::InternalUnlockReadWrite)
    { }
};


#if PTRACING
  class PInstrumentedSafeLockReadOnly : public PSafeLockBase
  {
    public:
      PInstrumentedSafeLockReadOnly(const PSafeObject & object, const PDebugLocation & location)
        : PSafeLockBase(object, &location, &PSafeObject::InternalLockReadOnly, &PSafeObject::InternalUnlockReadOnly)
      { }
  };

  class PInstrumentedSafeLockReadWrite : public PSafeLockBase
  {
    public:
      PInstrumentedSafeLockReadWrite(const PSafeObject & object, const PDebugLocation & location)
        : PSafeLockBase(object, &location, &PSafeObject::InternalLockReadWrite, &PSafeObject::InternalUnlockReadWrite)
      { }
  };

  #define P_INSTRUMENTED_LOCK_READ_ONLY2(var, obj)  PInstrumentedSafeLockReadOnly  var((obj), P_DEBUG_LOCATION)
  #define P_INSTRUMENTED_LOCK_READ_WRITE2(var, obj) PInstrumentedSafeLockReadWrite var((obj), P_DEBUG_LOCATION)
#else // P_TRACING
  #define P_INSTRUMENTED_LOCK_READ_ONLY2(var, obj)  PSafeLockReadOnly  var((obj))
  #define P_INSTRUMENTED_LOCK_READ_WRITE2(var, obj) PSafeLockReadWrite var((obj))
#endif // P_TRACING

#define P_MAKE_UNIQUE_VAR(base) P_MAKE_UNIQUE_VAR1(base, __LINE__)
#define P_MAKE_UNIQUE_VAR1(base, line) P_MAKE_UNIQUE_VAR2(base, line)
#define P_MAKE_UNIQUE_VAR2(base, line)  base##line

#define P_READ_WRITE_RETURN_ARG_0()
#define P_READ_WRITE_RETURN_ARG_1(arg) ; if (!P_MAKE_UNIQUE_VAR(lock).IsLocked()) arg
#define P_READ_WRITE_RETURN_PART1(narg, args) P_READ_WRITE_RETURN_PART2(narg, args)
#define P_READ_WRITE_RETURN_PART2(narg, args) P_READ_WRITE_RETURN_ARG_##narg args

#define P_INSTRUMENTED_LOCK_READ_ONLY(...)  P_INSTRUMENTED_LOCK_READ_ONLY2(P_MAKE_UNIQUE_VAR(lock),*this) P_READ_WRITE_RETURN_PART1(PARG_COUNT(__VA_ARGS__), (__VA_ARGS__))
#define P_INSTRUMENTED_LOCK_READ_WRITE(...) P_INSTRUMENTED_LOCK_READ_WRITE2(P_MAKE_UNIQUE_VAR(lock),*this) P_READ_WRITE_RETURN_PART1(PARG_COUNT(__VA_ARGS__), (__VA_ARGS__))


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   
    ) { m_deleteObjects = yes; }

    void DisallowDeleteObjects() { m_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 m_collectionMutex; }
          PMutex & GetMutex()       { return m_collectionMutex; }

  protected:
    void CopySafeCollection(PCollection * other);
    void CopySafeDictionary(PAbstractDictionary * other);
    bool SafeAddObject(PSafeObject * obj, PSafeObject * old);
    void SafeRemoveObject(PSafeObject * obj);

    PCollection      * m_collection;
    mutable PMutex     m_collectionMutex;
    bool               m_deleteObjects;
    PList<PSafeObject> m_toBeRemoved;
    PMutex             m_removalMutex;

#if P_TIMERS
    PDECLARE_NOTIFIER(PTimer, PSafeCollection, DeleteObjectsTimeout);
    PTimer           * m_deleteObjectsTimer;
#endif

  private:
    PSafeCollection(const PSafeCollection & other)
      : PObject(other)
      , m_collection()
      , m_deleteObjects()
      , m_deleteObjectsTimer()
    { }
    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 m_currentObject == NULL; }

    PSafeObject * GetObject() const { return m_currentObject; }

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

    PSafetyMode GetSafetyMode() const { return m_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 * m_collection;
    PSafeObject           * m_currentObject;
    PSafetyMode             m_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)
      {
        this->Assign(ptr);
        return *this;
      }

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

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

    PSafePtr & operator=(PINDEX idx)
      {
        this->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 *>(this->m_currentObject); }

    T & operator*()  const { return *dynamic_cast<T *>(PAssertNULL(this->m_currentObject)); }

    T * operator->() const { return  dynamic_cast<T *>(PAssertNULL(this->m_currentObject)); }

    T * operator++(int)
      {
        T * previous = dynamic_cast<T *>(this->m_currentObject);
        this->Next();
        return previous;
      }

    T * operator++()
      {
        this->Next();
        return dynamic_cast<T *>(this->m_currentObject);
      }

    T * operator--(int)
      {
        T * previous = dynamic_cast<T *>(this->m_currentObject);
        this->Previous();
        return previous;
      }

    T * operator--()
      {
        this->Previous();
        return dynamic_cast<T *>(this->m_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.m_collectionMutex);
      this->CopySafeCollection(dynamic_cast<Coll *>(other.m_collection));
    }

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

    virtual PSafePtr<Base> Append(
      Base * obj,       
      PSafetyMode mode = PSafeReference   
    ) {
        PWaitAndSignal mutex(this->m_collectionMutex);
        if (SafeAddObject(obj, NULL))
          return PSafePtr<Base>(*this, mode, this->m_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
    ) {
        this->m_collectionMutex.Wait();
        PSafePtr<Base> ptr(*this, PSafeReference, this->m_collection->GetValuesIndex(value));
        this->m_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.m_collectionMutex);
      CopySafeDictionary(dynamic_cast<Coll *>(other.m_collection));
    }

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

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

    virtual PBoolean RemoveAt(
      const Key & key   
    ) {
        PWaitAndSignal mutex(this->m_collectionMutex);
        return SafeRemove(dynamic_cast<Coll &>(*this->m_collection).GetAt(key));
      }

    virtual PBoolean Contains(
      const Key & key
    ) {
        PWaitAndSignal lock(this->m_collectionMutex);
        return dynamic_cast<Coll &>(*this->m_collection).Contains(key);
      }

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

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

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

    P_DEPRECATED virtual PSafePtr<Base> FindWithLock(
      const Key & key,
      PSafetyMode mode = PSafeReadWrite
    ) const { return FindIterator(key, mode); }

    virtual bool Move(
      const Key & from,   
      const Key & to      
    ) {
      PWaitAndSignal mutex(this->m_collectionMutex);
      if (dynamic_cast<Coll &>(*this->m_collection).GetAt(to) != NULL)
        return false;
      dynamic_cast<Coll &>(*this->m_collection).SetAt(to, dynamic_cast<Coll &>(*this->m_collection).GetAt(from));
      return true;
    }

    void MoveFrom(PSafeDictionaryBase & other)
    {
      if (this == &other)
        return;

      *this = other;
      this->AllowDeleteObjects(); // We now own the objects, need to put this back on

      // Remove from other without deleting them
      bool del = other.m_deleteObjects;
      other.DisallowDeleteObjects();
      other.RemoveAll();
      other.AllowDeleteObjects(del);
    }

    PArray<Key> GetKeys() const
    {
      PArray<Key> keys;
      this->m_collectionMutex.Wait();
      dynamic_cast<Coll &>(*this->m_collection).AbstractGetKeys(keys);
      this->m_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->Find(*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 ///////////////////////////////////////////////////////////////