ReflectorInterface.h

Go to the documentation of this file.

/*
 * Copyright (C) 2012 by
 *   MetraLabs GmbH (MLAB), GERMANY
 * and
 *   Neuroinformatics and Cognitive Robotics Labs (NICR) at TU Ilmenau, GERMANY
 * All rights reserved.
 *
 * Contact: info@mira-project.org
 *
 * Commercial Usage:
 *   Licensees holding valid commercial licenses may use this file in
 *   accordance with the commercial license agreement provided with the
 *   software or, alternatively, in accordance with the terms contained in
 *   a written agreement between you and MLAB or NICR.
 *
 * GNU General Public License Usage:
 *   Alternatively, this file may be used under the terms of the GNU
 *   General Public License version 3.0 as published by the Free Software
 *   Foundation and appearing in the file LICENSE.GPL3 included in the
 *   packaging of this file. Please review the following information to
 *   ensure the GNU General Public License version 3.0 requirements will be
 *   met: http://www.gnu.org/copyleft/gpl.html.
 *   Alternatively you may (at your option) use any later version of the GNU
 *   General Public License if such license has been publicly approved by
 *   MLAB and NICR (or its successors, if any).
 *
 * IN NO EVENT SHALL "MLAB" OR "NICR" BE LIABLE TO ANY PARTY FOR DIRECT,
 * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
 * THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF "MLAB" OR
 * "NICR" HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * "MLAB" AND "NICR" SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND "MLAB" AND "NICR" HAVE NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS.
 */

#ifndef _MIRA_REFLECTORINTERFACE_H_
#define _MIRA_REFLECTORINTERFACE_H_

#include <string>
#include <unordered_map>

#ifndef Q_MOC_RUN
#include <boost/preprocessor/repetition.hpp>
#include <boost/mpl/bool.hpp>
#include <boost/type_traits/integral_constant.hpp>
#endif

#include <platform/Environment.h>
#include <platform/Typename.h>

#include <rpc/RPCMacros.h>
#include <serialization/GetterSetter.h>
#include <serialization/PropertyHint.h>
#include <serialization/ReflectControlFlags.h>

namespace mira {


namespace serialization {
    typedef uint8 VersionType;
    typedef std::unordered_map<Typename, VersionType> ClassVersionMap;

    struct AcceptDesiredVersion {};
}

template <typename Derived>
class ReflectorInterface
{
public:
    struct Tag {};

    typedef boost::mpl::bool_<true> isReadOnly;

    typedef boost::mpl::bool_<true> useHumanReadableIDs;

    typedef boost::mpl::bool_<false> requireReflectBarriers;

    struct ReflectState {};

public:

    typedef serialization::VersionType VersionType;

    template <typename T>
    VersionType version(VersionType version, const T* caller = NULL)
    {
        return version;
    }

    MIRA_DEPRECATED("Please call as version<MyType>(v) or version(v, this)",
    VersionType version(VersionType version)) { return version; }

    template <typename T>
    VersionType requireVersion(VersionType version,
                               VersionType minVersion, const T* caller = NULL) { return version; }

    MIRA_DEPRECATED("Please call as requireVersion<MyType>(v, minV) or requireVersion(v, minV, this)",
    VersionType requireVersion(VersionType version, VersionType minVersion)) { return version; }

    template <typename T>
    void requireVersion(VersionType version, const T* caller = NULL) {}

    MIRA_DEPRECATED("Please call as requireVersion<MyType>(v) or requireVersion(v, this)",
    VersionType requireVersion(VersionType version)) { return version; }

    typedef serialization::ClassVersionMap ClassVersionMap;

    void desireClassVersions(const ClassVersionMap& versions) {}

    typedef serialization::AcceptDesiredVersion AcceptDesiredVersion;

    template <typename T>
    VersionType version(VersionType version, AcceptDesiredVersion, const T* caller = NULL)
    {
        return version;
    }

    template <typename T>
    VersionType requireVersion(VersionType version, VersionType minVersion,
                               AcceptDesiredVersion, const T* caller = NULL) { return version; }

    template <typename T>
    void requireVersion(VersionType version, AcceptDesiredVersion, const T* caller = NULL) {}



    template<typename T>
    void member(const char* name, T& member, const char* comment,
                ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void member(const char* name, const std::string& id, T& member,
                const char* comment, ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void member(const char* name, const T& member, Setter<T> setter,
                const char* comment, ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void member(const char* name, Getter<T> getter, Setter<T> setter,
                const char* comment, ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}


    // with default value

    template<typename T, typename U>
    void member(const char* name, T& member, const char* comment,
                const U& defaultValue, ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T, typename U>
    void member(const char* name, const T& member, Setter<T> setter,
                const char* comment, const U& defaultValue,
                ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T, typename U>
    void member(const char* name, Getter<T> getter, Setter<T> setter,
                const char* comment, const U& defaultValue,
                ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    // Properties

    template<typename T>
    void property(const char* name, T& member, const char* comment,
                  PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void property(const char* name, const std::string& id, T& member,
                  const char* comment, PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void property(const char* name, const T& member, Setter<T> setter,
                  const char* comment, PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void property(const char* name, Getter<T> getter, Setter<T> setter,
                  const char* comment, PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    // default values

    template<typename T, typename U>
    void property(const char* name, T& member, const char* comment,
                  const U& defaultValue, PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T, typename U>
    void property(const char* name, const T& member, Setter<T> setter,
                  const char* comment, const U& defaultValue,
                  PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T, typename U>
    void property(const char* name, Getter<T> getter, Setter<T> setter,
                  const char* comment, const U& defaultValue,
                  PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}


    template<typename T>
    void roproperty(const char* name, const T& member,
                    const char* comment, PropertyHint&& hint = PropertyHint(),
                    ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void roproperty(const char* name, const std::string& id, const T& member,
                    const char* comment, PropertyHint&& hint = PropertyHint(),
                    ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void roproperty(const char* name, Getter<T> getter, const char* comment,
                    PropertyHint&& hint = PropertyHint(),
                    ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    void itemName(const std::string& name) {}

    template<typename T>
    void delegate(T& member,
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void delegate(const T& member, Setter<T> setter,
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void delegate(Getter<T> getter, Setter<T> setter,
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}



    void interface(const char* name) {}

    #define RPC_METHODS_MAX_PARAMS 8

    // method(name, function<...>, comment)
    #define RPCGEN_METHODS(z,n,_)                                                                        \
    template<typename R BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P)>                                 \
    void method(const char* name, R (*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)), const char* comment) {}        \
                                                                                                         \
    template<typename R, typename Class BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P)>                 \
    void method(const char* name, R (Class::*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)), Class*, const char* comment) {} \
                                                                                                         \
    template<typename R, typename Class BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P)>                 \
    void method(const char* name, R (Class::*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)) const, Class*, const char* comment) {} \
                                                                                                         \
    template<typename R BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P)>                                 \
    void method(const char* name, boost::function<R (BOOST_PP_ENUM_PARAMS_Z(z,n,P))>, const char* comment) {} \

    BOOST_PP_REPEAT(BOOST_PP_INC(RPC_METHODS_MAX_PARAMS),RPCGEN_METHODS,nil)
    #undef RPCGEN_METHODS

    // method(name, function<...>, comment, paramname, paramdescription, ... )
    #define RPCGEN_METHODS_PARAMDESC(z,n,_)                                                              \
    template<typename R BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P)>                                 \
    void method(const char* name, R (*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)),                                \
                const char* comment, BOOST_PP_ENUM(n,RPCGEN_CALL_NAME_DESC_DECL,nil)) {}                 \
                                                                                                         \
    template<typename R, typename Class BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P)>                 \
    void method(const char* name, R (Class::*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)), Class*,                 \
                const char* comment, BOOST_PP_ENUM(n,RPCGEN_CALL_NAME_DESC_DECL,nil)) {}                 \
                                                                                                         \
    template<typename R, typename Class BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P)>                 \
    void method(const char* name, R (Class::*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)) const, Class*,           \
                const char* comment, BOOST_PP_ENUM(n,RPCGEN_CALL_NAME_DESC_DECL,nil)) {}                 \
                                                                                                         \
    template<typename R BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P)>                                 \
    void method(const char* name, boost::function<R (BOOST_PP_ENUM_PARAMS_Z(z,n,P))>,                    \
                const char* comment, BOOST_PP_ENUM(n,RPCGEN_CALL_NAME_DESC_DECL,nil)) {}                 \

    // generate variants with parameter descriptions only for param count > 0 
    BOOST_PP_REPEAT_FROM_TO(1,BOOST_PP_INC(RPC_METHODS_MAX_PARAMS),RPCGEN_METHODS_PARAMDESC,nil)
    #undef RPCGEN_METHODS_PARAMDESC

    // method(name, function<...>, comment, paramname, paramdescription, paramsamplevalue, ... )
    #define RPCGEN_METHODS_PARAMDESCSAMPLE(z,n,_)                                                        \
    template<typename R, BOOST_PP_ENUM(n,RPCGEN_CALL_TYPENAME_PARAM_DECL,nil)>                           \
    void method(const char* name, R (*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)),                                \
                const char* comment, BOOST_PP_ENUM(n,RPCGEN_CALL_NAME_DESC_SAMPLE_DECL,nil)) {}          \
                                                                                                         \
    template<typename R, typename Class, BOOST_PP_ENUM(n,RPCGEN_CALL_TYPENAME_PARAM_DECL,nil)>           \
    void method(const char* name, R (Class::*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)), Class*,                 \
                const char* comment, BOOST_PP_ENUM(n,RPCGEN_CALL_NAME_DESC_SAMPLE_DECL,nil)) {}          \
                                                                                                         \
    template<typename R, typename Class, BOOST_PP_ENUM(n,RPCGEN_CALL_TYPENAME_PARAM_DECL,nil)>           \
    void method(const char* name, R (Class::*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)) const, Class*,           \
                const char* comment, BOOST_PP_ENUM(n,RPCGEN_CALL_NAME_DESC_SAMPLE_DECL,nil)) {}          \
                                                                                                         \
    template<typename R, BOOST_PP_ENUM(n,RPCGEN_CALL_TYPENAME_PARAM_DECL,nil)>                           \
    void method(const char* name, boost::function<R (BOOST_PP_ENUM_PARAMS_Z(z,n,P))>,                    \
                const char* comment, BOOST_PP_ENUM(n,RPCGEN_CALL_NAME_DESC_SAMPLE_DECL,nil)) {}          \

    // generate variants with parameter descriptions only for param count > 0 
    BOOST_PP_REPEAT_FROM_TO(1,BOOST_PP_INC(RPC_METHODS_MAX_PARAMS),RPCGEN_METHODS_PARAMDESCSAMPLE,nil)
    #undef RPCGEN_METHODS_PARAMDESCSAMPLE
    #undef RPCGEN_METHODS_CONSTCHARPTR_NAME_DESC_SAMPLE

    // These are essentially catch-all clauses for mismatched parameter numbers/types. We will just ignore
    // the mismatch here where we don't implement these functions anyway (i.e., subclasses NOT overriding
    // method() with actual implementation will also not complain about invalid optional parameters).
    // We could just include ONLY these catch-alls here instead of the 2 sets above, but they have the extra
    // requirement of compiler support for variadic templates. Keeping them as a separate add-on allows to
    // make them available conditionally if required (their existence just helps getting more informative
    // compiler error messages on wrong use).
    #define RPCGEN_METHODS_WRONG_ARGUMENT_NUMBER(z,n,_)                                                  \
    template<typename R BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P), typename... Args>               \
    void method(const char* name, R (*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)),                                \
                const char* comment, Args...) {}                                                         \
                                                                                                         \
    template<typename R, typename Class BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P), typename... Args> \
    void method(const char* name, R (Class::*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)), Class* This,            \
                const char* comment, Args...) {}                                                         \
                                                                                                         \
    template<typename R, typename Class BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P), typename... Args> \
    void method(const char* name, R (Class::*fn)(BOOST_PP_ENUM_PARAMS_Z(z,n,P)) const, Class* This,      \
                const char* comment, Args...) {}                                                         \
                                                                                                         \
    template<typename R BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P), typename... Args>               \
    void method(const char* name, boost::function<R (BOOST_PP_ENUM_PARAMS_Z(z,n,P))> fn,                 \
                const char* comment, Args...) {}                                                         \

    BOOST_PP_REPEAT_FROM_TO(1,BOOST_PP_INC(RPC_METHODS_MAX_PARAMS),RPCGEN_METHODS_WRONG_ARGUMENT_NUMBER,nil)
    #undef RPCGEN_METHODS_WRONG_ARGUMENT_NUMBER

    // provide a method that causes an error at compile time if instantiated. Derived classes overriding
    // method() should call this in their implementation for wrong argument number
    #define RPCGEN_METHODS_INVALID(z,n,_)                                                                \
    template<typename R BOOST_PP_ENUM_TRAILING_PARAMS_Z(z,n,typename P)>                                 \
    void invalid_method()                                                                                \
    {    /* force this to fail whenever it is instantiated - but only then! */                           \
        static_assert(sizeof(R*)==0,                                                                     \
                      "_____________NUMBER OR TYPES OF NAMES/DESCRIPTIONS/SAMPLEVALUES FOR PARAMETERS "  \
                      "IN CALL TO Reflector::method() DO NOT MATCH THE PROVIDED FUNCTION'S SIGNATURE. "  \
                      "PLEASE PROVIDE const char* NAME AND DESCRIPTION FOR EACH RPC METHOD PARAMETER, "  \
                      "OR NAME, DESCRIPTION AND A CORRECTLY TYPED SAMPLE VALUE FOR EACH PARAMETER._____________"); \
    }

    BOOST_PP_REPEAT(BOOST_PP_INC(RPC_METHODS_MAX_PARAMS),RPCGEN_METHODS_INVALID,nil)
    #undef RPCGEN_METHODS_INVALID

#ifdef DOXYGEN
    // this is a fake method to generate a doxygen documentation for the
    // methods created above

    void method(const char* name, Method method, const char* comment,
                const char* paramName, const char* paramDescription, P paramSampleValue, ...);

    void method(const char* name, Method method, Class* object, const char* comment,
                const char* paramName, const char* paramDescription, P paramSampleValue, ...);

    void method(const char* name, Method method, const char* comment,
                const char* paramName, const char* paramDescription, P paramSampleValue, ...);

#endif



    void pushObjectTrackingStore() {}

    void popObjectTrackingStore() {}


    template <typename Base>
    void reflectBase(Base& base) {}


    static bool usesHumanReadableIDs() {
        return Derived::useHumanReadableIDs::value;
    }

    ReflectState preReflect(const char* context = "")
    {
        MIRA_THROW(XNotImplemented,
                   typeName<Derived>() << "::requireReflectBarriers == true, but " <<
                   typeName<Derived>() << "::preReflect() not implemented!");
    
        return ReflectState();
    }

    void postReflect(const ReflectState&)
    {
        MIRA_THROW(XNotImplemented,
                   typeName<Derived>() << "::requireReflectBarriers == true, but " <<
                   typeName<Derived>() << "::postReflect() not implemented!");
    }

protected:

    static int checkForcedVersion(const std::string& variable)
    {
        try {
            std::stringstream ss;
            ss.str(resolveEnvironmentVariable(variable));
            int i;
            ss >> i;
            return i;
        }
        catch(XInvalidConfig&) {}

        return -1;
    }
};


#define MIRA_REFLECT_VERSION(reflector, versionNumber) reflector.version(versionNumber, this)

#define MIRA_REFLECT_REQUIRE_VERSION(reflector, versionNumber) reflector.requireVersion(versionNumber, this)

#define MIRA_REFLECT_BASE(reflector, BaseClass) reflector.template reflectBase<BaseClass>(*this)

#define MIRA_REFLECT_BASE_NONINTRUSIVE(reflector, BaseClass, object) reflector.template reflectBase<BaseClass>(object)

#define MIRA_REFLECT_BASE_IF_VERSION_ATLEAST(reflector, BaseClass, versionvar, minversion) \
    if (versionvar < minversion)                                                           \
        BaseClass::reflect(reflector);                                                     \
    else                                                                                   \
        reflector.template reflectBase<BaseClass>(*this);                                  \


#define MIRA_REFLECT_BASE_NONINTRUSIVE_IF_VERSION_ATLEAST(reflector, BaseClass, object, versionvar, minversion) \
    if (versionvar < minversion)                                                           \
        reflect(reflector, (BaseClass&)object);                                            \
    else                                                                                   \
        reflector.template reflectBase<BaseClass>(object);                                 \


#define MIRA_MEMBER_WITH_ID(reflector, name, id, var, ...) \
    if(reflector.usesHumanReadableIDs())                   \
        reflector.member(name, id, var, __VA_ARGS__);      \
    else                                                   \
        reflector.member(name, var, __VA_ARGS__);

#define MIRA_PROPERTY_WITH_ID(reflector, name, id, var, ...) \
    if(reflector.usesHumanReadableIDs())                     \
        reflector.property(name, id, var, __VA_ARGS__);      \
    else                                                     \
        reflector.property(name, var, __VA_ARGS__);


} // namespace

#endif