Runnable.h

Go to the documentation of this file.

#ifndef _NOVADAQ_RUNNABLE_H
#define _NOVADAQ_RUNNABLE_H

#include <unistd.h>

namespace novadaq {

/**
 * Interface for objects that can be run in separate threads using the
 * Boost Thread library.
 *
 * Sample usage:
 * <code>
 * RunnableDescendant myRunnable;
 * boost::thread
 *   myThread(boost::bind(&novadaq::Runnable::run, &myRunnable));
 * </code>
 *
 * @author Kurt Biery
 * @author Steve Foulkes
 * @version $Revision: 1.4.34.1 $ $Date: 2019/09/27 00:07:20 $
 */

// Implementation note:  Classes that implement the Runnable interface
// can make use of the stop() and isRunning() methods *only* if the derived
// classes are careful to keep the relevant attribute values current and
// test against them where appropriate.
//
// In particular, a thorough implementation of the Runnable interface would
// include the following features:
// - assignment of _running to "true" at the beginning of the run() method
// - assignment of _running to "false" at the end of the run() method
// - periodic testing of the _stopRequested attributed within the run()
//   method to see if it should clean up and return

class Runnable {
 public:
    /**
     * Default constructor.
     */
    Runnable() {
        _running = false;
        _stopRequested = false;
        _hasCompleted = false;
    }

    /**
     * Virtual destructor (to ensure that derived class destructors
     * are called).
     */
    virtual ~Runnable() {}

    /**
     * Contains the operations that are to be executed in a separate thread.
     */
    virtual void run() = 0;

    /**
     * Stops the execution of the Runnable object.
     */
    virtual void stop() {
        if (_hasCompleted) {return;}
        _stopRequested = true;
    }

    /**
     * Tests if the Runnable object is running.
     *
     * @return true if the object is running, false otherwise.
     */
    virtual bool isRunning() const {
        return _running;
    }

    /**
     * Tests if the Runnable object has completed its running.
     *
     * @return true if the object is done, false otherwise.
     */
    virtual bool isDone() const {
        return _hasCompleted;
    }

    /**
     * Sleeps for the specified amount of time, but periodically
     * checks if a stop has been requested, and returns if so.
     */
    virtual void watchfulSleep(int microseconds,
                               int numberOfIntervals = 10) {
        if (numberOfIntervals < 1) {numberOfIntervals = 1;}
        int intervalTime = microseconds / numberOfIntervals;
        if (intervalTime < 1) {intervalTime = 1;}
        for (int idx = 0; idx < numberOfIntervals; ++idx) {
            if (_stopRequested) {break;}
            usleep(intervalTime);
        }
    }

 protected:

    /**
     * Tracks whether the Runnable object is running or not
     * (this can be before it has started or after it has finished)
     */
    bool _running;
    
    /**
     * Indicates that a request has been made to stop running.
     */
    bool _stopRequested;

    /**
     * Tracks whether the Runnable object has completed its running.
     */
    bool _hasCompleted;
    
};

} // end of namespace novadaq

#endif