mtsInterfaceRequired.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, Anton Deguet
  Created on: 2008-11-13

  (C) Copyright 2008-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 _mtsInterfaceRequired_h
#define _mtsInterfaceRequired_h

#include <cisstMultiTask/mtsInterface.h>

#include <cisstCommon/cmnNamedMap.h>
#include <cisstOSAbstraction/osaThread.h>

#include <cisstMultiTask/mtsCommandBase.h>

#include <cisstMultiTask/mtsCallableVoidMethod.h>
#include <cisstMultiTask/mtsCallableVoidFunction.h>
#include <cisstMultiTask/mtsCommandVoid.h>
#include <cisstMultiTask/mtsCommandWrite.h>
#include <cisstMultiTask/mtsCommandQueuedVoid.h>
#include <cisstMultiTask/mtsCommandQueuedWrite.h>
#include <cisstMultiTask/mtsInterfaceCommon.h>

#include <cisstMultiTask/mtsFunctionBase.h>

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

class mtsEventHandlerList;

class CISST_EXPORT mtsInterfaceRequired: public mtsInterface
{
    CMN_DECLARE_SERVICES(CMN_NO_DYNAMIC_CREATION, CMN_LOG_ALLOW_DEFAULT);

    friend class mtsComponentProxy;
    friend class mtsComponentInterfaceProxyClient;
    friend class mtsManagerLocal;
    friend class mtsManagerLocalTest;
    friend class mtsEventReceiverBase;
    friend class mtsManagerComponentClient;
    // for GetDescription
    friend class mtsSocketProxyClient;
    // for MailBox
    friend class mtsSocketProxyServer;

 protected:

    mtsRequiredType Required;

    mtsMailBox * MailBox;

    const mtsInterfaceProvided * InterfaceProvided;

    size_t MailBoxSize;

    size_t ArgumentQueuesSize;

    mtsInterfaceRequired(void);

    osaThreadSignal ThreadSignalForBlockingCommands;

    osaThreadSignal * GetThreadSignal(void);

 public:

    enum {DEFAULT_MAIL_BOX_AND_ARGUMENT_QUEUES_SIZE = 64};

    mtsInterfaceRequired(const std::string & interfaceName, mtsComponent * component,
                         mtsMailBox * mailBox, mtsRequiredType required = MTS_REQUIRED);

    virtual ~mtsInterfaceRequired();

    const mtsInterfaceProvided * GetConnectedInterface(void) const;

    bool SetMailBoxSize(size_t desiredSize);

    bool SetArgumentQueuesSize(size_t desiredSize);

    bool SetMailBoxAndArgumentQueuesSize(size_t desiredSize);

    virtual std::vector<std::string> GetNamesOfFunctions(void) const;
    virtual std::vector<std::string> GetNamesOfFunctionsVoid(void) const;
    virtual std::vector<std::string> GetNamesOfFunctionsVoidReturn(void) const;
    virtual std::vector<std::string> GetNamesOfFunctionsWrite(void) const;
    virtual std::vector<std::string> GetNamesOfFunctionsWriteReturn(void) const;
    virtual std::vector<std::string> GetNamesOfFunctionsRead(void) const;
    virtual std::vector<std::string> GetNamesOfFunctionsQualifiedRead(void) const;

    mtsFunctionVoid * GetFunctionVoid(const std::string & functionName) const;
    mtsFunctionVoidReturn * GetFunctionVoidReturn(const std::string & functionName) const;
    mtsFunctionWrite * GetFunctionWrite(const std::string & functionName) const;
    mtsFunctionWriteReturn * GetFunctionWriteReturn(const std::string & functionName) const;
    mtsFunctionRead * GetFunctionRead(const std::string & functionName) const;
    mtsFunctionQualifiedRead * GetFunctionQualifiedRead(const std::string & functionName) const;

    virtual std::vector<std::string> GetNamesOfEventHandlersVoid(void) const;
    virtual std::vector<std::string> GetNamesOfEventHandlersWrite(void) const;

    virtual mtsCommandVoid * GetEventHandlerVoid(const std::string & eventName) const;
    virtual mtsCommandWriteBase * GetEventHandlerWrite(const std::string & eventName) const;

    /* adeguet - seems deprecated or at least not used anywhere?
    inline bool CouldConnectTo(mtsInterfaceProvided * CMN_UNUSED(interfaceProvidedOrOutput)) {
        return true;
        } */

    bool ConnectTo(mtsInterfaceProvided * interfaceProvided);  // used by mtsManagerComponentClient.cpp
    //    bool Disconnect(void) { return DetachCommands(); }  // Should be deprecated -- adeguet1 OrOutput

    mtsRequiredType IsRequired(void) const;

    bool AddSystemEventHandlers(void);

 private:
    void BlockingCommandExecutedHandler(void);
    void BlockingCommandReturnExecutedHandler(void);

    bool BindCommands(const mtsInterfaceProvided * interfaceProvided);
    bool DetachCommands(void); // used by mtsManagerComponentClient

    void GetEventList(mtsEventHandlerList & eventList);
    bool CheckEventList(mtsEventHandlerList & eventList) const;
 public:

    void DisableAllEvents(void);

    void EnableAllEvents(void);

    size_t ProcessMailBoxes(void);

    void ToStream(std::ostream & outputStream) const;

 protected:
 public: // adeguet1 todo fix -- this has been added for ostream << operator
#ifndef SWIG  // SWIG cannot deal with this
    template <class _PointerType>
        class FunctionOrReceiverInfo
    {
        // For GCM UI
        friend class mtsManagerLocal;
        friend class mtsInterfaceRequired;
    protected:
        _PointerType * Pointer;
        mtsRequiredType Required;
    public:
        FunctionOrReceiverInfo(_PointerType & func_or_recv, mtsRequiredType required):
            Pointer(&func_or_recv),
            Required(required)
        {}

        ~FunctionOrReceiverInfo() {}

        inline void Detach(void) {
            Pointer->Detach();
        }

        void ToStream(std::ostream & outputStream) const
        {
            outputStream << *Pointer;
            if (Required == MTS_OPTIONAL) {
                outputStream << " (optional)";
            } else {
                outputStream << " (required)";
            }
        }
    };

    typedef FunctionOrReceiverInfo<mtsFunctionBase> FunctionInfo;
    typedef FunctionOrReceiverInfo<mtsEventReceiverVoid> ReceiverVoidInfo;
    typedef FunctionOrReceiverInfo<mtsEventReceiverWrite> ReceiverWriteInfo;

#endif // !SWIG
 protected:

    bool UseQueueBasedOnInterfacePolicy(mtsEventQueueingPolicy queueingPolicy,
                                        const std::string & methodName,
                                        const std::string & eventName);

    bool AddEventHandlerToReceiver(const std::string & eventName, mtsCommandVoid * handler) const;
    bool AddEventHandlerToReceiver(const std::string & eventName, mtsCommandWriteBase * handler) const;

    typedef cmnNamedMap<FunctionInfo> FunctionInfoMapType;

    FunctionInfoMapType FunctionsVoid; // Void (command)

    FunctionInfoMapType FunctionsVoidReturn; // Void return (command)

    FunctionInfoMapType FunctionsWrite; // Write (command)

    FunctionInfoMapType FunctionsWriteReturn; // Write return (command)

    FunctionInfoMapType FunctionsRead; // Read (state read)

    FunctionInfoMapType FunctionsQualifiedRead; // Qualified Read (conversion, read at time index, ...)

    typedef cmnNamedMap<ReceiverVoidInfo> EventReceiverVoidMapType;
    typedef cmnNamedMap<ReceiverWriteInfo> EventReceiverWriteMapType;

    EventReceiverVoidMapType EventReceiversVoid; // Void (event)

    EventReceiverWriteMapType EventReceiversWrite; // Write (event)

    typedef cmnNamedMap<mtsCommandVoid> EventHandlerVoidMapType;
    typedef cmnNamedMap<mtsCommandWriteBase> EventHandlerWriteMapType;
    EventHandlerVoidMapType EventHandlersVoid;
    EventHandlerWriteMapType EventHandlersWrite;

    void GetDescription(mtsInterfaceRequiredDescription & requiredInterfaceDescription);

 public:

    bool AddFunction(const std::string & functionName, mtsFunctionVoid & function, mtsRequiredType required = MTS_REQUIRED);

    bool AddFunction(const std::string & functionName, mtsFunctionVoidReturn & function, mtsRequiredType required = MTS_REQUIRED);

    bool AddFunction(const std::string & functionName, mtsFunctionWrite & function, mtsRequiredType required = MTS_REQUIRED);

    bool AddFunction(const std::string & functionName, mtsFunctionWriteReturn & function, mtsRequiredType required = MTS_REQUIRED);

    bool AddFunction(const std::string & functionName, mtsFunctionRead & function, mtsRequiredType required = MTS_REQUIRED);

    bool AddFunction(const std::string & functionName, mtsFunctionQualifiedRead & function, mtsRequiredType required = MTS_REQUIRED);

    bool AddEventReceiver(const std::string & eventName, mtsEventReceiverVoid & receiver, mtsRequiredType required = MTS_REQUIRED);

    bool AddEventReceiver(const std::string & eventName, mtsEventReceiverWrite & receiver, mtsRequiredType required = MTS_REQUIRED);

    mtsCommandVoid * AddEventHandlerVoid(mtsCallableVoidBase * callable,
                                         const std::string & eventName,
                                         mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY);
    template <class __classType>
        inline mtsCommandVoid * AddEventHandlerVoid(void (__classType::*method)(void),
                                                    __classType * classInstantiation,
                                                    const std::string & eventName,
                                                    mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY) {
        mtsCallableVoidBase * callable = new mtsCallableVoidMethod<__classType>(method, classInstantiation);
        return this->AddEventHandlerVoid(callable, eventName, queueingPolicy);
    }

    inline mtsCommandVoid * AddEventHandlerVoid(void (*function)(void),
                                                const std::string & eventName,
                                                mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY) {
        mtsCallableVoidBase * callable = new mtsCallableVoidFunction(function);
        return this->AddEventHandlerVoid(callable, eventName, queueingPolicy);
    }

    template <class __classType, class __argumentType>
        inline mtsCommandWriteBase * AddEventHandlerWrite(void (__classType::*method)(const __argumentType &),
                                                          __classType * classInstantiation,
                                                          const std::string & eventName,
                                                          mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY);

    template <class __classType>
        inline mtsCommandWriteBase * AddEventHandlerWriteGeneric(void (__classType::*method)(const mtsGenericObject &),
                                                                 __classType * classInstantiation,
                                                                 const std::string & eventName,
                                                                 mtsEventQueueingPolicy queueingPolicy = MTS_INTERFACE_EVENT_POLICY,
                                                                 mtsGenericObject *argumentPrototype = 0);

    bool RemoveEventHandlerVoid(const std::string & eventName);
    bool RemoveEventHandlerWrite(const std::string & eventName);
};


#ifndef SWIG
template <class __classType, class __argumentType>
inline mtsCommandWriteBase * mtsInterfaceRequired::AddEventHandlerWrite(void (__classType::*method)(const __argumentType &),
                                                                        __classType * classInstantiation,
                                                                        const std::string & eventName,
                                                                        mtsEventQueueingPolicy queueingPolicy)
{
    bool queued = this->UseQueueBasedOnInterfacePolicy(queueingPolicy, "AddEventHandlerWrite", eventName);
    mtsCommandWriteBase * actualCommand =
        new mtsCommandWrite<__classType, __argumentType>(method, classInstantiation, eventName, __argumentType());
    if (queued) {
        if (MailBox)
            EventHandlersWrite.AddItem(eventName,  new mtsCommandQueuedWrite<__argumentType>(MailBox, actualCommand, this->ArgumentQueuesSize));
        else
            CMN_LOG_CLASS_INIT_ERROR << "No mailbox for queued event handler write \"" << eventName << "\"" << std::endl;
    } else {
        EventHandlersWrite.AddItem(eventName, actualCommand);
    }
    mtsCommandWriteBase *handler = EventHandlersWrite.GetItem(eventName);
    AddEventHandlerToReceiver(eventName, handler);  // does nothing if event receiver does not exist
    return  handler;
}


template <class __classType>
inline mtsCommandWriteBase * mtsInterfaceRequired::AddEventHandlerWriteGeneric(void (__classType::*method)(const mtsGenericObject &),
                                                                               __classType * classInstantiation,
                                                                               const std::string & eventName,
                                                                               mtsEventQueueingPolicy queueingPolicy,
                                                                               mtsGenericObject *argumentPrototype)
{
    bool queued = this->UseQueueBasedOnInterfacePolicy(queueingPolicy, "AddEventHandlerWriteGeneric", eventName);
    mtsCommandWriteBase * actualCommand =
        new mtsCommandWriteGeneric<__classType>(method, classInstantiation, eventName, argumentPrototype);
    if (queued) {
        // PK: check for MailBox overlaps with code in UseQueueBasedOnInterfacePolicy
        if (MailBox) {
            mtsCommandQueuedWriteGeneric *tmp = new mtsCommandQueuedWriteGeneric(MailBox, actualCommand, this->ArgumentQueuesSize);
            if (argumentPrototype)
                tmp->SetArgumentPrototype(argumentPrototype);
            EventHandlersWrite.AddItem(eventName,  tmp);
        } else {
            CMN_LOG_CLASS_INIT_ERROR << "No mailbox for queued event handler write generic \"" << eventName << "\"" << std::endl;
        }
    } else {
        EventHandlersWrite.AddItem(eventName, actualCommand);
    }
    mtsCommandWriteBase *handler = EventHandlersWrite.GetItem(eventName);
    AddEventHandlerToReceiver(eventName, handler);  // does nothing if event receiver does not exist
    return  handler;
}
#endif  // !SWIG


inline std::ostream & operator << (std::ostream & output,
                                   const mtsInterfaceRequired::FunctionInfo & functionInfo) {
    functionInfo.ToStream(output);
    return output;
}

CMN_DECLARE_SERVICES_INSTANTIATION(mtsInterfaceRequired)


#endif // _mtsInterfaceRequired_h