mtsEventReceiver.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):  Peter Kazanzides
  Created on: 2010-09-24
 
  (C) Copyright 2010-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 _mtsEventReceiver_h
#define _mtsEventReceiver_h

 

 
#include <cisstMultiTask/mtsInterfaceRequired.h>
#include <cisstOSAbstraction/osaForwardDeclarations.h>
#include <cisstOSAbstraction/osaMutex.h>
 
// Always include last
#include <cisstMultiTask/mtsExport.h>
 
 
// EventReceivers must be added before Bind (should add check for InterfaceProvidedOrOutput==0)
// EventHandlers can be added at any time.
// When Bind called,
//    if no EventReceiver, directly add EventHandler
//    if EventReceiver, set handler in it
 
class CISST_EXPORT mtsEventReceiverBase {
protected:
    std::string Name;
    mtsInterfaceRequired * Required;   // Pointer to the required interface
    osaThreadSignal * EventSignal;
    bool OwnEventSignal;   // true if we created our own thread signal
 
    // There are 4 possible wait states.
    // EVENT_RECEIVER_IDLE and EVENT_RECEIVER_WAITING are the only two that are required; they are
    // equivalent to the Waiting boolean flag in the previous implementation.
    // These are sufficient to wait on a stream of events, but not enough if waiting on a single event
    // that could occur before the Wait is started, in which case the waiting thread could wait forever.
    // This case could occur with blocking commands, such as VoidReturn and WriteReturn, where the basic
    // approach is for the client thread to issue the remote command (to the server thread) and then
    // wait for the server thread to signal when complete. The problem occurs if the server thread signals
    // completion before the client thread starts waiting. The solution in this case is for the client
    // thread to call PrepareToWait() before issuing the remote command. In that case, WaitState transitions
    // to EVENT_RECEIVER_PREPARING. Subsequently, if the signal handler is called it changes WaitState to
    // EVENT_RECEIVER_SIGNALED to indicate that the event happened before the Wait was called.
    // Because WaitState is an integral type (enum), we assume that is is updated atomically. Nevertheless,
    // the WaitMutex is necessary in the following cases:
    //   1. When the event handler is called (by the server thread), it must check if WaitState is
    //      EVENT_RECEIVER_PREPARING and, if so, transition to EVENT_RECEIVER_SIGNALED. The mutex is needed
    //      to ensure that the client thread does not simultaneous attempt to change the state to
    //      EVENT_RECEIVER_WAITING.
    //   2. When the client thread calls Wait or WaitWithTimeout and attempts to change WaitState from
    //      EVENT_RECEIVER_PREPARING (or EVENT_RECEIVER_IDLE if PrepareToWait was not called) to
    //      EVENT_RECEIVER_WAITING. Specifically, we do not want the server thread to simultaneously
    //      attempt to change WaitState from EVENT_RECEIVER_PREPARING to EVENT_RECEIVER_SIGNALED.
    enum WaitStates { EVENT_RECEIVER_IDLE, EVENT_RECEIVER_PREPARING, EVENT_RECEIVER_WAITING, EVENT_RECEIVER_SIGNALED };
    WaitStates WaitState;
    osaMutex WaitMutex;
 
    bool CheckRequired() const;
    void CheckEventSignal();
    bool WaitCommon();
 
public:
    mtsEventReceiverBase();
    virtual ~mtsEventReceiverBase();
 
    void SetName(const std::string &name) { Name = name; }
    virtual std::string GetName() const { return Name; }

    virtual void SetRequired(const std::string &name, mtsInterfaceRequired *req);
 
    virtual void SetThreadSignal(osaThreadSignal *signal);

    virtual bool PrepareToWait();

    virtual bool Wait();

    virtual bool WaitWithTimeout(double timeoutInSec);

    virtual void ClearWait();
 
    virtual void Detach();

    virtual void ToStream(std::ostream & outputStream) const = 0;
};
 

inline std::ostream & operator << (std::ostream & output,
                                   const mtsEventReceiverBase & receiver) {
    receiver.ToStream(output);
    return output;
}
 
class CISST_EXPORT mtsEventReceiverVoid : public mtsEventReceiverBase {
protected:
    mtsCommandVoid * Command;      // Command object for calling EventHandler method
    mtsCommandVoid * UserHandler;  // User supplied event handler
 
    // This one always gets added non-queued
    void EventHandler(void);
 
public:
    mtsEventReceiverVoid();
    ~mtsEventReceiverVoid();

    mtsCommandVoid * GetCommand(void);

    void SetHandlerCommand(mtsCommandVoid * commandHandler);
 
    // Same functionality as mtsInterfaceRequired::AddEventHandlerVoid.
    template <class __classType>
    inline mtsCommandVoid * SetHandler(void (__classType::*method)(void),
                                       __classType * classInstantiation,
                                       mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY) {
        return CheckRequired() ? (Required->AddEventHandlerVoid(method, classInstantiation, this->GetName(), queueingPolicy)) : 0;
    }
 
    inline mtsCommandVoid * SetHandler(void (*function)(void),
                                       mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY) {
        return CheckRequired() ? (Required->AddEventHandlerVoid(function, this->GetName(), queueingPolicy)) : 0;
    }
 
    bool RemoveHandler(void);

    void ToStream(std::ostream & outputStream) const;
};
 
class CISST_EXPORT mtsEventReceiverWrite : public mtsEventReceiverBase {
protected:
    mtsCommandWriteBase *Command;      // Command object for calling EventHandler method
    mtsCommandWriteBase *UserHandler;  // User supplied event handler
    mtsGenericObject *ArgPtr;
 
    // This one always gets added non-queued
    void EventHandler(const mtsGenericObject &arg);
 
public:
    mtsEventReceiverWrite();
    ~mtsEventReceiverWrite();

    mtsCommandWriteBase *GetCommand();

    void SetHandlerCommand(mtsCommandWriteBase * commandHandler);
 
    // Same functionality as mtsInterfaceRequired::AddEventHandlerWrite.
    template <class __classType, class __argumentType>
    inline mtsCommandWriteBase * SetHandler(void (__classType::*method)(const __argumentType &),
                                            __classType * classInstantiation,
                                            mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY) {
        return CheckRequired() ? (Required->AddEventHandlerWrite(method, classInstantiation, this->GetName(), queueingPolicy)) : 0;
    }
 
    // PK: Do we need the "generic" version (AddEventHandlerWriteGeneric)?
 
 
    using mtsEventReceiverBase::PrepareToWait;
    virtual bool PrepareToWait(mtsGenericObject &obj);
 
    bool IsArgValid() const
    { return (ArgPtr && ArgPtr->Valid()); }
 
    // Note that we are using the Wait and WaitWithTimeout member functions from the base class.
    using mtsEventReceiverBase::Wait;
    using mtsEventReceiverBase::WaitWithTimeout;

    virtual bool Wait();
    virtual bool WaitWithTimeout(double timeoutInSec);
 
    using mtsEventReceiverBase::ClearWait;
    virtual void ClearWait();
 
    //PK: might be nice to have this
    //const mtsGenericObject *GetArgumentPrototype() const;
 
    bool RemoveHandler(void);

    void ToStream(std::ostream & outputStream) const;
};
 
 
#endif // _mtsEventReceiver_h