cvrThread.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   cvrThread.h
 *         Contains the cvr::thread wrapper class to encapulate the differences
 *         between the POSIX threads in *ix systems and the Win32 concepts.
 * \author Thomas Rusert
 * \author Pablo Alvarado
 * \date   04.11.1999
 *
 * $Id: cvrThread.h,v 1.5 2005/04/20 16:02:17 doerfler Exp $
 */

#ifndef _CVR_THREAD_H_
#define _CVR_THREAD_H_

#include "cvrMutex.h"
#include "cvrSemaphore.h"
#include "cvrMacroSymbols.h"

#ifndef _CVR_WIN32
#  include <pthread.h>
#else
#  include <winbase.h>
#endif

namespace cvr {

  /**
   * CVR-Lib thread class.
   *
   * Representiation of a system thread (currently a posix thread for Unix
   * systems, and WIN32 thread for windows systems)
   *
   * If you need a thread, just inherit from this class and reimplement the
   * method run():
   * \code
   * class myThread : public thread {
   * protected:
   *   void run() {
   *     // your thread's job here!
   *   }
   * };
   *
   * ...
   *
   * // somewhere else in your code:
   *
   * myThread aThread;
   * aThread.start(); // do your threads job...
   * // continue with other things (your thread runs in parallel...)
   * \endcode
   */
  class thread {
  public:
    /**
     * Default constructor
     */
    thread();

    /**
     * Destructor.
     *
     * If the thread is still executing while destroying the thread object,
     * the thread will be forced to stop. Use join() to wait for the thread
     * to terminate itself.
     */
    virtual ~thread();

    /**
     * Start thread.
     *
     * This method is called by the parent thread, to start in a
     * second thread the execution of the run() method, which is overloaded
     * in the derived classes.
     */
    virtual void start();

    /**
     * Stop thread execution.
     *
     * Forces the thread to stop executing.
     *
     * Overload this function to cleanup things that the run() method
     * could leave unfinished after thread cancellation.
     */
    virtual void stop();

    /**
     * Wait for thread termination.
     *
     * This has to be called by a thread different than the one
     * executing the run() method, in order to wait that the run()
     * method normally finishes.
     */
    virtual void join();

    /**
     * Check if thread is alive.
     *
     * Test if the thread that should execute the run() method is still alive.
     *
     * @return true if the thread is alive, or false if it was already
     * stopped or finished.
     */
    bool isAlive() const;

    /**
     * Check which thread is calling.
     *
     * Returns whether the thread that calls this method represents the
     * thread executing the run() method (i.e. if the method
     * is directly or indirectly called within the run() method).
     *
     * @return true if the thread executing the run() method is the one that
     *              called the current method, or false otherwise.
     */
    bool representsCalledThread() const;

  protected:
    /**
     * Thread execution method.
     *
     * The whole thread object is somehow just a representation for
     * this method, since the created thread will just call it, (which
     * means will execute the overloaded run() method of the derived
     * class).  The thread will also persist as long as this method
     * does, i.e. the thread will stop when the method finishes.
     */
    virtual void run() = 0;

    /**
     * Clean up the thread.
     *
     * Method to be called when finishing regulary or cancelling the thread;
     * something like a destructor for the run() method.
     *
     * The default behaviour, if not overloaded, is do nothing.
     */
    virtual void cleanUp() {};

  private:
    /**
     * The function to be called by the OS to clean up the thread.
     *
     * It will be called with the instance of the object as a parameter.
     * The static interface allows to use it as a C function.
     */
    static void clean(void* threadObject);

    /**
     * Flag to indicate if the thread is alive or not.
     */
    bool alive;

    /**
     * Mutex to protect the access to the multithreading functions.
     */
    static mutex startMutex;

    /**
     * Semaphore used to join called thread with the calling one
     */
    semaphore suspendSem;

# ifndef _CVR_WIN32 // UNIX/LINUX
    /**
     * The real C function called as the POSIX thread standard
     * requires.  It just wrapps calling the method run() of the given
     * instance.
     */
    static void* execute(void* threadObject);

    /**
     * Handler of the created POSIX thread.
     */
    pthread_t theThread;
# else          // WINDOWS
    /**
     * The real C function called as the Win32 thread interface
     * requires.  It just wrapps calling the method run() of the given
     * instance.
     */
    static void execute(void* threadObject);

    /**
     * Windows handle of the thread.
     */
    HANDLE theThread;

    /**
     * ID of the called thread
     */
    unsigned int calledThreadId;
# endif
  };

}

#endif