mtsTask.h

Go to the documentation of this file.

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-    */
/* ex: set filetype=cpp softtabstop=4 shiftwidth=4 tabstop=4 cindent expandtab: */

/*

  Author(s):  Ankur Kapoor, Peter Kazanzides, Anton Deguet, Min Yang Jung
  Created on: 2004-04-30

  (C) Copyright 2004-2013 Johns Hopkins University (JHU), All Rights Reserved.

--- begin cisst license - do not edit ---

This software is provided "as is" under an open source license, with
no warranty.  The complete license can be found in license.txt and
http://www.cisst.org/cisst/license.txt.

--- end cisst license ---
*/


#ifndef _mtsTask_h
#define _mtsTask_h

#include <stdexcept>

#include <cisstCommon/cmnPortability.h>
#include <cisstOSAbstraction/osaThread.h>
#include <cisstOSAbstraction/osaMutex.h>

#include <cisstMultiTask/mtsForwardDeclarations.h>
#include <cisstMultiTask/mtsStateTable.h>
#include <cisstMultiTask/mtsMailBox.h>
#include <cisstMultiTask/mtsCommandVoid.h>
#include <cisstMultiTask/mtsCommandRead.h>
#include <cisstMultiTask/mtsCommandWrite.h>
#include <cisstMultiTask/mtsCommandQueuedVoid.h>
#include <cisstMultiTask/mtsCommandQueuedWrite.h>
#include <cisstMultiTask/mtsComponent.h>
#include <cisstMultiTask/mtsFunctionVoid.h>
#include <cisstMultiTask/mtsFunctionWrite.h>

// Always include last
#include <cisstMultiTask/mtsExport.h>

class CISST_EXPORT mtsTask: public mtsComponent
{
    CMN_DECLARE_SERVICES(CMN_NO_DYNAMIC_CREATION, CMN_LOG_ALLOW_DEFAULT);

    friend class mtsManagerLocal;

public:
    typedef mtsComponent BaseType;

    static std::runtime_error UnknownException;

protected:
    /************************ Protected task data  *********************/

    osaThread Thread;

    double InitializationDelay;

    osaMutex StateChange;

    osaThreadSignal StateChangeSignal;

    mtsStateTable StateTable;

    bool OverranPeriod;

    void * ThreadStartData;

    void * ReturnValue;

    mtsCallableVoidBase * InterfaceProvidedToManagerCallable;

    /******************** ExecIn interface *************************/

    mtsInterfaceRequired * ExecIn;

    void RunEventHandler(void);

    void ChangeStateEventHandler(const mtsComponentState &newState);

    /******************** ExecOut interface ************************/

    mtsInterfaceProvided * ExecOut;

    mtsFunctionVoid RunEventInternal;
    bool RunEventCalled;
    mtsExecutionResult RunEvent(bool check = true);

    mtsFunctionWrite ChangeStateEvent;

    /********************* Methods that call user methods *****************/

    virtual void * RunInternal(void * argument) = 0;

    void DoRunInternal(void);

    virtual void StartupInternal(void);

    virtual void CleanupInternal(void);

    /**************** Methods for managing task timing ********************/

    void Sleep(double timeInSeconds);

    mtsStateIndex::TimeTicksType GetTick(void) const;

    /*********** Methods for thread start data and return values **********/

    virtual void SaveThreadStartData(void * data);

    virtual void SetThreadReturnValue(void * returnValue);

    /*********** Methods for changing task state **************************/

    /* documented in base class */
    void ChangeState(mtsComponentState::Enum newState);

    /* documented in base class */
    bool WaitForState(mtsComponentState desiredState, double timeout);

public:
    /********************* Task constructor and destructor *****************/

    mtsTask(const std::string & name,
            unsigned int sizeStateTable = 256);

    virtual ~mtsTask();

    /********************* Methods to be defined by user *****************/
    /* The Run, Startup, and Cleanup methods could be made protected.    */
    /* Note that Startup and Cleanup are now defind in mtsComponent.     */

    virtual void OnStartupException(const std::exception &excp);

    virtual void Run(void) = 0;

    virtual void OnRunException(const std::exception &excp);

    virtual void Configure(const std::string & CMN_UNUSED(filename) = "") {}

    void SetInitializationDelay(double delay);

    /********************* Methods to change task state ******************/
    /* Maybe some or all of these should be pure virtual functions.      */

    /* Create a new thread (if needed). */
    virtual void Create(void * data) = 0;
    inline void Create(void) { Create(0); }

    void Kill(void);

    double GetAveragePeriod(void) const { return StateTable.GetAveragePeriod(); }

    inline const std::string GetDefaultStateTableName(void) const {
        return StateTable.GetName();
    }

    inline mtsStateTable * GetDefaultStateTable(void) {
        return this->StateTables.GetItem(this->GetDefaultStateTableName(), CMN_LOG_LEVEL_INIT_ERROR);
    }

    /********************* Methods to manage interfaces *******************/

    /* documented in base class */
    mtsInterfaceRequired * AddInterfaceRequiredWithoutSystemEventHandlers(const std::string & interfaceRequiredName,
                                                                          mtsRequiredType required = MTS_REQUIRED);

    /* documented in base class */
    mtsInterfaceProvided * AddInterfaceProvidedWithoutSystemEvents(const std::string & newInterfaceName,
                                                                   mtsInterfaceQueueingPolicy queueingPolicy = MTS_COMPONENT_POLICY,
                                                                   bool isProxy = false);

    /********************* Methods for task synchronization ***************/

    virtual bool WaitToStart(double timeout);

    virtual bool WaitToTerminate(double timeout);

    inline virtual void WaitForWakeup(void) {
        Thread.WaitForWakeup();
    }

    inline virtual void Wakeup(void) {
        Thread.Wakeup();
    }

    void ProcessManagerCommandsIfNotActive();

    bool CheckForOwnThread(void) const;

    /********************* Methods for task period and overrun ************/

    inline virtual bool IsPeriodic(void) const {
        return false;
    }

    inline virtual bool IsOverranPeriod(void) const {
        return OverranPeriod;
    }

    inline virtual void ResetOverranPeriod(void) {
        OverranPeriod = false;
    }
};


CMN_DECLARE_SERVICES_INSTANTIATION(mtsTask)


#endif // _mtsTask_h