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-2026 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;

    using mtsComponent::GetManagerComponentServices;
    virtual const mtsManagerComponentServices *GetManagerComponentServices(void) const override;
 
    /******************** 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 **************************/
 
    /* Change to desired state (newState). The change is protected by a mutex
       so can be called from another thread. */
    void ChangeState(mtsComponentState::Enum newState);
 
    /* documented in base class */
    bool WaitForState(mtsComponentState desiredState, double timeout) override;
 
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);

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

    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) override { Create(0); }

    void Kill(void) override;

    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) override;
 
    /* documented in base class */
    mtsInterfaceProvided * AddInterfaceProvidedWithoutSystemEvents(const std::string & newInterfaceName,
                                                                   mtsInterfaceQueueingPolicy queueingPolicy = MTS_COMPONENT_POLICY) override;
 
    /********************* 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