cvrMutex.h

Go to the documentation of this file.

/*
 * Copyright (C) 1998-2005
 * Lehrstuhl fuer Technische Informatik, RWTH-Aachen, Germany
 *
 *
 * This file is part of the Computer Vision and Robotics Library (CVR-Lib)
 *
 * The CVR-Lib is free software; you can redistribute it and/or
 * modify it under the terms of the BSD License.
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the authors nor the names of its contributors may be
 *    used to endorse or promote products derived from this software without
 *    specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */



/**
 * \file   cvrMutex.h
 *         Contains cvr::mutex for protecting critical sections for
 *         multithreading.
 * \author Thomas Rusert
 * \date   04.11.1999
 *
 * $Id: cvrMutex.h,v 1.6 2005/01/03 16:16:22 alvarado Exp $
 */

#ifndef _CVR_MUTEX_H_
#define _CVR_MUTEX_H_

#include "cvrMacroSymbols.h"

#ifndef _CVR_WIN32
#  include <pthread.h> // for unix/linux systems (posix threads!)
#else
#  include <windows.h>
#  include <process.h>
#endif

namespace cvr {
  /**
   * Mutex class for the library
   *
   * This object can be used to protect critical sections on multithreaded
   * applications.  The same thread should NOT try to lock the mutex more than
   * once.  The behavior of this will depend on the operating system: on
   * linux/unix the thread will be locked forever (posix standard); on
   * windows, the thread will count how many lock have been done, but it will
   * not be blocked by the later locks!
   *
   * Example:
   *
   * \code
   * // A class with some code to be protected
   * class A {
   * private:
   *   // The mutex used to protect the some code blocks
   *   cvr::mutex lock_;
   *
   *   // Data that requires exclusive access, e.g. a std::list
   *   std::list<int> data_;
   *
   * public:
   *   // A method that requires some exclusive access
   *   void access() {
   *     lock_.lock();   // ensure exclusive access to the data
   *     static int numAccesses = 0;
   *     data_.push_back(numAccesses++);
   *     lock_.unlock(); // realease exclusive access
   *   }
   * };
   * \endcode
   *
   * In the previous example the "access()" method ensures that only one thread
   * at a time has access to the data_ attribute of the class.  Other methods
   * that also access the data_ attribute should also protect the access.
   *
   * @see cvr::semaphore, cvr::thread
   */
  class mutex {
  public:
    /**
     * Default constructor with unlocked mutex.
     */
    mutex();

    /**
     * Destructor
     */
    virtual ~mutex();

    /**
     * Wait until lock for mutex becomes available and lock it
     */
    void lock();

    /**
     * Try to lock mutex, but do not block.
     *
     * @return true if locking was successful.
     */
    bool tryLock();

    /**
     * Unlock mutex
     */
    void unlock();

  protected:
    /**
     * Destroy the mutex
     */
    void destroy();

# ifndef _CVR_WIN32
    /**
     * the posix mutex object
     */
    pthread_mutex_t theMutex_;
# else
    /**
     * the WIN32 mutex objects
     */
    HANDLE theMutex_;
# endif
  };
}

#endif