cvrSemaphore.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   cvrSemaphore.h
 *         Contains the cvr::semaphore wrapper class to encapulate the
 *         differences between the POSIX and Win32 concepts.
 * \author Thomas Rusert
 * \date   04.11.1999
 *
 * $Id: cvrSemaphore.h,v 1.5 2006/01/03 14:49:25 alvarado Exp $
 */


#ifndef _CVR_SEMAPHORE_H_
#define _CVR_SEMAPHORE_H_

#include "cvrObject.h"
#include "cvrMacroSymbols.h"

#ifndef _CVR_WIN32
#  include <semaphore.h>
#else
#  include <windows.h>
#  include <process.h>
#  define SEM_VALUE_MAX 16777215 // (2^24-1)
#endif

namespace cvr {
  /**
   * Class for inter-thread synchronisation concept of semaphores.
   *
   * The difference between semaphores and mutexes is that the later one only
   * tracks if the mutex has been locked or not, while the semaphore counts
   * the number of "locks" (called here "waits()") and requires the same
   * number of unlocks (here "posts()") to release the access.
   *
   * The semaphore is unlocked when the counter reaches the value zero (see
   * getValue()), which means that in construction time you decide how far
   * from unlocking the semaphore is (for values greater than zero) or if it
   * is from the beginning unlocked (for value zero).  Note that the default
   * counter value is set to 1.
   *
   * @see cvr::mutex, cvr::thread
   */
  class semaphore {
  public:
    /**
     * Default constructor.
     *
     * The semaphore is unlocked when the counter reaches the value
     * zero, which means that in construction time you decide how far
     * from unlocking the semaphore is (for values greater than
     * zero) or if it is from the beginning unlocked (for value zero).
     *
     * @param initialValue initial value for the semaphore counter.
     */
    semaphore(const int initialValue = 1);

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

    /**
     * Wait on semaphore.
     *
     * Wait on semaphore, i.e. decrease the value or wait if counter <= 0
     *
     * @return true if successful, false otherwise
     */
    bool wait();

    /**
     * Try to wait on semaphore, but do not block.
     *
     * If this function returns true, then you can get access to the resource
     * you are trying to protect, but if it returns false, then you may not
     * assume you have rights to do that.
     *
     * @return true if value was decreased.
     */
    bool tryWait();

    /**
     * Post semaphore.
     *
     * Post semaphore, i.e. increase its value
     *
     * @return true if successful, false otherwise
     */
    bool post();

    /**
     * Get current value.
     *
     * The returned value will be usually lower than zero or zero if
     * the semaphore has been unlocked.
     */
    int getValue();

    /**
     * Reset value to initialValue
     */
    void reset();

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

    /**
     * Initial semaphore value.
     *
     * This value is required to allow resetting the semaphore
     */
    int initValue;

# ifndef _CVR_WIN32
    /**
     * The posix semaphore
     */
    sem_t theSemaphore;
# else
    /**
     * The WIN32 semaphore object
     */
    HANDLE theSemaphore;

    /**
     * Counter of the semaphore
     */
    int counter;
# endif
  };
}

#endif