threads.h

/**************************************************************
* Copyright (c) 2010-2013, Dynamic Network Services, Inc.
* Jake Montgomery (jmontgomery@dyn.com) & Tom Daly (tom@dyn.com)
* Distributed under the FreeBSD License - see LICENSE
***************************************************************/
// Various threading and lock routines
#pragma once

#include <pthread.h>

namespace openbfdd
{

  /**
   * Helper/wrapper for pthread_cond_t Could handle initialization failure better.
   */
  class WaitCondition
  {
  public:
    WaitCondition(bool init = true);
    ~WaitCondition();

    /**
     * Signals the condition.
     */
    void Signal();

    /**
     * Only call if this is not created with init == true;
     *
     * @return bool - false on failure
     */
    bool Init();

    /**
     * Waits on the signal and lock. Note that spurious wakeups can occur.
     * On failure other than timeout the mutex and signal state will not have
     * changed.
     *
     * @param lock [in]- Must not be NULL.
     * @param msTimeout [in] - The timeout time, or 0 for no timeout.
     *
     * @return int - 0 on success. 1 on timeout, -1 on other failure.
     */
    int Wait(pthread_mutex_t *lock, uint32_t msTimeout = 0);


  private:
    pthread_cond_t m_condition;
    bool m_initDone;  // the condition initialization succeeded.
  };


  /**
   * Wrapper for a simple mutex.
   */
  class QuickLock
  {
  public:
    /**
     * @param create - If true then the lock is created and initialized.
     */
    QuickLock(bool create = false);
    ~QuickLock();

    /**
     * Use to create the lock, if constructor was not called with create.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool Create();

    /**
     * Permanently destroys the lock. Do not call any other methods after this
     * unless Create is called.
     */
    void Destroy();

    /**
     *  Locks the lock. Normally use an AutoQuickLock on the stack to ensure that
     *  this gets unlocked.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool Lock();

    /**
     *  Unlocks the lock. Normally use an AutoQuickLock on the stack to ensure that
     *  this gets unlocked.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool UnLock();


    /**
     * Signal a condition.
     * Lock must be locked by us.
     * On return, this is always unlocked. (even on failure)
     *
     * @param condition
     */
    void SignalAndUnlock(WaitCondition &condition);

    /**
     *
     * Waits on a condition. Lock must be locked by us.
     * On return, this is still locked.
     *
     * @param condition
     * @param msTimeout [in] - The timeout time, or 0 for no timeout.
     *
     * @return int - 0 on success. 1 on timeout, -1 on other failure.
     */
    int LockWait(WaitCondition &condition, uint32_t msTimeout = 0);


  private:
    pthread_mutex_t m_Lock;
    bool m_initialized;
  };

  // Helper for QuickLock.  This object should only be used from a single thread.
  class AutoQuickLock
  {
  public:
    /**
     *
     *
     * @param threadLock - The lock.
     * @param lockInitial - Should the lock start in the locked state. Use
     *                    IsLockedByMe to check for failure. Will log on failure.
     */
    AutoQuickLock(QuickLock &threadLock, bool lockInitial = true);
    ~AutoQuickLock();

    /**
     * Lock the lock.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool Lock();

    /**
     * Check if this object had locked the lock.
     *
     * @return bool - true if this object had locked the lock.
     */
    bool IsLockedByMe();

    /**
     *  Unlock the lock.
     *  Called automatically when this is destroyed.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool UnLock();

    /**
     * Signal a condition.
     * Lock must be locked by us.
     * On return, this is always unlocked. (even on failure)
     *
     * @param condition
     */
    void SignalAndUnlock(WaitCondition &condition);

    /**
     *
     * Waits on a condition. Lock must be locked by us.
     * On return, this is still locked.
     *
     * @param condition
     * @param msTimeout [in] - The timeout time, or 0 for no timeout.
     *
     * @return int - 0 on success. 1 on timeout, -1 on other failure.
     */
    int LockWait(WaitCondition &condition, uint32_t msTimeout = 0);



  private:
    QuickLock *m_quickLock;
    bool m_isLockedByMe;
  };


  /**
   * Wrapper for a read/write lock.
   */
  class ReadWriteLock
  {
  public:

    /**
     * @param create - If true then the lock is created and initialized.
     */
    ReadWriteLock(bool create = false);
    ~ReadWriteLock();

    /**
     * Use to create the lock, if constructor was not called with create.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool Create();

    /**
     * Permanently destroys the lock. Do not call any other methods after this
     * unless Create is called.
     */
    void Destroy();

    /**
     *  Shared locks the lock. Normally use an AutoReadWriteLock on the stack
     *  to ensure that this gets unlocked.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool ReadLock();

    /**
     *  Exclusive locks the lock . Normally use an AutoReadWriteLock on the stack to ensure
     *  that this gets unlocked.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool WriteLock();

    /**
     *  Unlocks the lock. Normally use an AutoRWriteLock on the stack to ensure that
     *  this gets unlocked.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool UnLock();

  private:
    pthread_rwlock_t m_Lock;
    bool m_initialized;
  };


  // Helper for RWriteLock.  This object should only be used from a single thread.
  class AutoReadWriteLock
  {
  public:

    enum LockType
    {
      None, // not locked
      Read, // Read locked
      Write // write locked.
    };

    /**
     *
     *
     * @param threadLock - The lock.
     * @param lockInitial - Should the lock start in the locked state. Use
     *                    IsLockedByMe to check for failure. Will log on failure.
     */
    AutoReadWriteLock(ReadWriteLock &threadLock, AutoReadWriteLock::LockType lockInitial);
    ~AutoReadWriteLock();

    /**
     * Read lock the lock.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool ReadLock();

    /**
     * Exclusive lock the lock.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool WriteLock();

    /**
     * Check if this object had locked the lock.
     *
     * @return bool - true if this object had locked the lock.
     */
    bool IsLockedByMe();

    /**
     *  Unlock the lock.
     *  Called automatically when this is destroyed.
     *
     *  @return bool - false on failure. (Will log failure.)
     */
    bool UnLock();

  private:
    ReadWriteLock *m_rwLock;
    AutoReadWriteLock::LockType m_lockedByMeType;
  };


};