class.h

Go to the documentation of this file.

/*
 * Copyright (c) 2010-2015:  G-CSC, Goethe University Frankfurt
 * Author: Andreas Vogel
 * 
 * This file is part of UG4.
 * 
 * UG4 is free software: you can redistribute it and/or modify it under the
 * terms of the GNU Lesser General Public License version 3 (as published by the
 * Free Software Foundation) with the following additional attribution
 * requirements (according to LGPL/GPL v3 §7):
 * 
 * (1) The following notice must be displayed in the Appropriate Legal Notices
 * of covered and combined works: "Based on UG4 (www.ug4.org/license)".
 * 
 * (2) The following notice must be displayed at a prominent place in the
 * terminal output of covered works: "Based on UG4 (www.ug4.org/license)".
 * 
 * (3) The following bibliography is recommended for citation and must be
 * preserved in all covered files:
 * "Reiter, S., Vogel, A., Heppner, I., Rupp, M., and Wittum, G. A massively
 *   parallel geometric multigrid solver on hierarchically distributed grids.
 *   Computing and visualization in science 16, 4 (2013), 151-164"
 * "Vogel, A., Reiter, S., Rupp, M., Nägel, A., and Wittum, G. UG4 -- a novel
 *   flexible software system for simulating pde based models on high performance
 *   computers. Computing and visualization in science 16, 4 (2013), 165-179"
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 */
 
 
#ifndef __H__UG_BRIDGE__CLASS__
#define __H__UG_BRIDGE__CLASS__
 
#include <cstdlib>
#include <cstring>
#include <string>
 
#include <type_traits> // for std::is_void
 
// std::optional is Cxx17 and not yet supported by all compilers, so we use boost::optional for now
#include <boost/optional.hpp> // for boost::optional
 
#include "parameter_stack.h"
#include "function_traits.h"
#include "global_function.h"
#include "common/common.h"
#include "error.h"
#include "registry_util.h"
 
#ifdef PROFILE_BRIDGE
#ifndef UG_PROFILER
  #error "You need to define UG_PROFILER to use PROFILE_BRIDGE"
#endif
#include "common/profiler/runtime_profile_info.h"
#else
#endif
 
 
namespace ug
{
namespace bridge
{
 
 
class MethodPtrWrapper
{
  public:
    template <typename TMethod>
    MethodPtrWrapper(TMethod m)
    {
      size = sizeof(TMethod);
      data = malloc(size);
      memcpy(data, &m, size);
    }
    
    MethodPtrWrapper(const MethodPtrWrapper& mpw)
    {
      size = mpw.size;
      data = malloc(size);
      memcpy(data, mpw.get_raw_ptr(), size);
    }
    
    ~MethodPtrWrapper() {free(data);}
    
    void* get_raw_ptr() const {return data;}
    
  protected:
    void* data;
    int   size;
};
 
template <class TClass> void CastAndDelete(const void* ptr)
{
  delete reinterpret_cast<const TClass*>(ptr);
}
 
template <> inline void CastAndDelete<void>(const void* ptr)
{
  UG_THROW("Can't delete instance of class 'void'");
}
 
 
class ExportedMethod : public ExportedFunctionBase
{
  public:
  // all c++ functions are wrapped by a proxy function of the following type
    typedef void (*ProxyFunc)(const MethodPtrWrapper& func, void* obj,
                  const ParameterStack& in, ParameterStack& out);
 
  public:
    ExportedMethod( const MethodPtrWrapper& m, ProxyFunc pf,
            const std::string& name, const std::string& className,
            const std::string& methodOptions,
            const std::string& retValInfos, const std::string& paramInfos,
            const std::string& tooltip, const std::string& help)
    : ExportedFunctionBase(name, methodOptions, retValInfos, paramInfos, tooltip, help),
      m_ptrWrapper(m), m_proxy_func(pf), m_className(className)
#ifdef PROFILE_BRIDGE
    ,m_dpi((m_className + ":" + name).c_str(), true, "registry", false)
#endif
    {
    }
 
    void execute(void* obj, const ParameterStack& paramsIn, ParameterStack& paramsOut) const
    {
#ifdef PROFILE_BRIDGE
      m_dpi.beginNode();
#endif
      m_proxy_func(m_ptrWrapper, obj, paramsIn, paramsOut);
 
#ifdef PROFILE_BRIDGE
      m_dpi.endNode();
#endif
    }
 
    template <typename TFunc>
    void create_parameter_stack()
    {
      ExportedFunctionBase::create_parameter_stack<TFunc>();
      m_customReturn = func_traits<TFunc>::custom_return;
    }
    
    const std::string& class_name() const {return m_className;}
 
    bool has_custom_return() const {return m_customReturn;}
 
  private:
    MethodPtrWrapper m_ptrWrapper;
  
    ProxyFunc m_proxy_func;
 
    std::string m_className;
 
    bool m_customReturn;
 
#ifdef PROFILE_BRIDGE
    mutable RuntimeProfileInfo m_dpi;
#endif
};
 
//  ExportedMethodGroup (sreiter)
 
class ExportedMethodGroup
{
  typedef ExportedMethod::ProxyFunc ProxyFunc;
 
  public:
    ExportedMethodGroup(const std::string& name) : m_name(name)
    {}
 
    ~ExportedMethodGroup()
    {
      for(size_t i = 0; i < m_overloads.size(); ++i)
        delete m_overloads[i].m_func;
    }
 
    const std::string& name() const {return m_name;}
 
    template <class TFunc>
    bool add_overload(  const TFunc& m, ProxyFunc pf,
                        const std::string& className,
              const std::string& methodOptions, const std::string& retValInfos,
              const std::string& paramInfos, const std::string& tooltip,
              const std::string& help)
    {
      size_t typeID = GetUniqueTypeID<TFunc>();
 
    //  make sure that the overload didn't exist
      if(get_overload_by_type_id(typeID))
        return false;
 
    //  create a new overload
      ExportedMethod* func = new ExportedMethod(MethodPtrWrapper(m),
                        pf, m_name, className,
                        methodOptions, retValInfos,
                        paramInfos, tooltip, help);
 
      m_overloads.push_back(Overload(func, typeID));
 
 
    //  create parameter in list
      func->create_parameter_stack<TFunc>();
 
      return true;
    }
 
    size_t num_overloads() const {return m_overloads.size();}
 
    ExportedMethod* get_overload(size_t index) {return m_overloads.at(index).m_func;}
 
    const ExportedMethod* get_overload(size_t index) const {return m_overloads.at(index).m_func;}
 
    template <class TType>
    ExportedMethod* get_overload_by_type()
    {
      size_t typeID = GetUniqueTypeID<TType>();
      return get_overload_by_type_id(typeID);
    }
 
    template <class TType>
    const ExportedMethod* get_overload_by_type() const
    {
      size_t typeID = GetUniqueTypeID<TType>();
      return get_overload_by_type_id(typeID);
    }
 
    ExportedMethod* get_overload_by_type_id(size_t typeID)
    {
      for(size_t i = 0; i < m_overloads.size(); ++i){
        if(m_overloads[i].m_typeID == typeID)
          return m_overloads[i].m_func;
      }
      return NULL;
    }
 
    const ExportedMethod* get_overload_by_type_id(size_t typeID) const
    {
      for(size_t i = 0; i < m_overloads.size(); ++i){
        if(m_overloads[i].m_typeID == typeID)
          return m_overloads[i].m_func;
      }
      return NULL;
    }
 
    size_t get_overload_type_id(size_t index) const {return m_overloads.at(index).m_typeID;}
 
  private:
    struct Overload{
      Overload()  {}
      Overload(ExportedMethod* func, size_t typeID)
        : m_func(func), m_typeID(typeID)
      {}
      ExportedMethod*   m_func;
      size_t        m_typeID;
    };
 
    std::string m_name;
    std::vector<Overload> m_overloads;
};
 
template <typename TClass, typename TMethod,
      typename TRet = typename func_traits<TMethod>::return_type>
struct MethodProxy
{
  static void apply(const MethodPtrWrapper& method, void* obj,
                    const ParameterStack& in, ParameterStack& out)
  {
  //  cast to method pointer
    TMethod mptr = *(TMethod*) method.get_raw_ptr();
 
  //  cast object to type
    TClass* objPtr = (TClass*) (obj);
 
  //  get parameter
    typedef typename func_traits<TMethod>::params_type params_type;
    ParameterStackToTypeValueList<params_type> args(in);
 
  //  apply method
    TRet res = func_traits<TMethod>::apply(mptr, objPtr, args);
 
  //  write return value
    out.push<TRet>(res);
  }
};
 
template <typename TClass, typename TMethod>
struct MethodProxy<TClass, TMethod, void>
{
  static void apply(const MethodPtrWrapper& method, void* obj,
                    const ParameterStack& in, ParameterStack& out)
  {
  //  cast to method pointer
    TMethod mptr = *(TMethod*) method.get_raw_ptr();
 
  //  cast object to type
    TClass* objPtr = (TClass*) (obj);
 
  //  get parameter
    typedef typename func_traits<TMethod>::params_type params_type;
    ParameterStackToTypeValueList<params_type> args(in);
 
  //  apply method
    func_traits<TMethod>::apply(mptr, objPtr, args);
  }
};
 
template <typename TClass, typename TMethod>
struct MethodProxy<TClass, TMethod, CustomReturn>
{
  static void apply(const MethodPtrWrapper& method, void* obj,
                    const ParameterStack& in, ParameterStack& out)
  {
  //  cast to method pointer
    TMethod mptr = *(TMethod*) method.get_raw_ptr();
 
  //  cast object to type
    TClass* objPtr = (TClass*) (obj);
 
  //  get parameter
    typedef typename func_traits<TMethod>::params_type params_type;
    ParameterStackToTypeValueList<params_type> args(in);
 
  //  apply method
    func_traits<TMethod>::apply(mptr, objPtr, args);
  }
};
 
 
// Exported Constructor
 
class UG_API ExportedConstructor
{
  public:
  // all c++ functions are wrapped by a proxy function of the following type
    typedef void* (*ProxyFunc)(const ParameterStack& in);
 
  public:
    ExportedConstructor(ProxyFunc pf,
                        const std::string& className, const std::string& options,
                        const std::string& paramInfos,
                        const std::string& tooltip, const std::string& help);
 
    void* create(const ParameterStack& paramsIn) const
    {
#ifdef PROFILE_BRIDGE
      m_dpi.beginNode();
#endif
 
      void *pRet = m_proxy_func(paramsIn);
 
#ifdef PROFILE_BRIDGE
      m_dpi.endNode();
#endif
      return pRet;
    }
 
    const std::string& options() const {return m_options;}
 
    size_t num_parameter() const {return m_vvParamInfo.size();}
 
    size_t num_infos(size_t i) const {return m_vvParamInfo.at(i).size();}
 
    const std::string& parameter_name(size_t i) const {return parameter_info(i, 0);}
 
    const std::string& parameter_info(size_t i, size_t j) const {return m_vvParamInfo.at(i).at(j);}
 
    const std::vector<std::string>& parameter_info_vec(size_t i) const {return m_vvParamInfo.at(i);}
 
    const std::string& parameter_info_string() const {return m_paramInfos;}
 
    const std::string& tooltip() const {return m_tooltip;}
 
    const std::string& help() const {return m_help;}
 
    const ParameterInfo& params_in() const  {return m_paramsIn;}
 
    ParameterInfo& params_in() {return m_paramsIn;}
 
    bool check_consistency(std::string classname) const;
 
    template <typename TFunc>
    void create_parameter_stack()
    {
      typedef typename func_traits<TFunc>::params_type params_type;
      CreateParameterInfo<params_type>::create(m_paramsIn);
 
    //  arbitrary choosen minimum number of infos exported
    //  (If values non given we set them to an empty string)
      const size_t MinNumInfos = 3; // for "name | style | options"
 
    //  Fill missing Parameter
      m_vvParamInfo.resize(m_paramsIn.size());
 
    //  resize missing infos for each parameter
      for(int i = 0; i < (int)m_vvParamInfo.size(); ++i)
        for(size_t j = m_vvParamInfo.at(i).size(); j < MinNumInfos; ++j)
          m_vvParamInfo.at(i).push_back(std::string(""));
    }
 
  protected:
  //  help function to tokenize the parameter string
    void tokenize(const std::string& str, std::vector<std::string>& tokens,
                  const char delimiter);
 
  protected:
  private:
    ProxyFunc m_proxy_func;
 
    std::string m_className;
 
    std::string m_options;
 
    std::string m_paramInfos;
 
    std::vector<std::vector<std::string> > m_vvParamInfo;
 
    std::string m_tooltip;
    std::string m_help;
 
    ParameterInfo m_paramsIn;
 
#ifdef PROFILE_BRIDGE
    mutable RuntimeProfileInfo m_dpi;
#endif
};
 
template <typename TClass, typename TMethod>
struct ConstructorProxy
{
  static void* create(const ParameterStack& in)
  {
  //  get parameter
    typedef typename func_traits<TMethod>::params_type params_type;
    ParameterStackToTypeValueList<params_type> args(in);
 
  //  apply method
    TClass* newInst = constructor_traits<TClass, params_type>::apply(args);
 
  //  return new pointer
    return (void*) newInst;
  }
};
 
template <typename TClass>
void DestructorProxy(void* obj)
{
  TClass* pObj = (TClass*)obj;
  delete pObj;
}
 
// Interface Exported Class
 
 
class JSONConstructible {};
 
class IExportedClass
{
  public:
    typedef void (*DeleteFunction)(const void*);
 
  public:
    virtual const std::string& name() const = 0;
 
    virtual const std::string& group() const = 0;
 
    virtual const ClassNameNode& class_name_node() const = 0;
 
    virtual const std::string& tooltip() const = 0;
 
    virtual const std::vector<const char*>* class_names() const = 0;
 
    virtual size_t num_methods() const = 0;
 
    virtual size_t num_const_methods() const = 0;
    
    virtual const ExportedMethod& get_method(size_t i) const = 0;
 
    virtual const ExportedMethod& get_const_method(size_t i) const = 0;
    
    virtual size_t num_overloads(size_t funcInd) const = 0;
 
    virtual size_t num_const_overloads(size_t funcInd) const = 0;
 
    virtual const ExportedMethod& get_overload(size_t funcInd, size_t oInd) const = 0;
 
    virtual const ExportedMethod& get_const_overload(size_t funcInd, size_t oInd) const = 0;
 
    virtual const ExportedMethodGroup& get_method_group(size_t ind) const = 0;
 
    virtual const ExportedMethodGroup& get_const_method_group(size_t ind) const = 0;
 
    virtual const ExportedMethodGroup* get_exported_method_group(const std::string& name) const = 0;
 
    virtual const ExportedMethodGroup* get_const_exported_method_group(const std::string& name) const = 0;
 
    virtual bool is_instantiable() const = 0;
 
    virtual size_t num_constructors() const = 0;
 
    virtual const ExportedConstructor& get_constructor(size_t i) const = 0;
 
    virtual const boost::optional<ExportedConstructor&> get_json_constructor() const = 0;
 
    virtual bool is_json_constructible() const = 0;
 
    virtual bool construct_as_smart_pointer() const = 0;
 
    virtual void destroy(void* obj) const = 0;
 
    virtual DeleteFunction get_delete_function() const = 0;
 
    virtual bool check_consistency() const;
 
    virtual ~IExportedClass() {};
};
 
 
class ExportedClassBaseImpl : public IExportedClass
{
  private:
  //  disallow
    ExportedClassBaseImpl();
    ExportedClassBaseImpl(const ExportedClassBaseImpl& other);
 
  public:
    ExportedClassBaseImpl(const std::string& tooltip);
 
    virtual ~ExportedClassBaseImpl();
 
    virtual const std::string& tooltip() const;
 
    virtual size_t num_methods() const;
 
    virtual size_t num_const_methods() const;
 
    virtual const ExportedMethod& get_method(size_t i) const;
 
    virtual const ExportedMethod& get_const_method(size_t i) const;
 
    virtual size_t num_overloads(size_t funcInd) const;
 
    virtual size_t num_const_overloads(size_t funcInd) const;
 
    virtual const ExportedMethod& get_overload(size_t funcInd, size_t oInd) const;
 
    virtual const ExportedMethod& get_const_overload(size_t funcInd, size_t oInd) const;
 
    virtual const ExportedMethodGroup& get_method_group(size_t ind) const;
 
    virtual const ExportedMethodGroup& get_const_method_group(size_t ind) const;
 
    virtual const ExportedMethodGroup* get_exported_method_group(const std::string& name) const;
 
    virtual const ExportedMethodGroup* get_const_exported_method_group(const std::string& name) const;
 
    virtual size_t num_constructors() const;
 
    virtual const ExportedConstructor& get_constructor(size_t i) const;
 
    virtual const boost::optional<ExportedConstructor&> get_json_constructor() const;
 
    virtual bool construct_as_smart_pointer() const;
 
 
    virtual void set_construct_as_smart_pointer(bool enable);
 
    virtual bool is_instantiable() const;
 
    virtual void destroy(void* obj) const;
 
  protected:
    bool constructor_type_id_registered(size_t typeID);
 
    bool constmethodname_registered(const std::string& name);
 
    bool methodname_registered(const std::string& name);
 
    ExportedMethodGroup* get_exported_method_group(const std::string& name);
 
    ExportedMethodGroup* get_const_exported_method_group(const std::string& name);
 
  protected:
    struct ConstructorOverload{
      ConstructorOverload() {}
      ConstructorOverload(ExportedConstructor* func, size_t typeID)
        : m_constructor(func), m_typeID(typeID)
      {}
      ExportedConstructor*  m_constructor;
      size_t          m_typeID;
    };
 
    std::vector<ConstructorOverload> m_vConstructor;
 
    typedef void (*DestructorFunc)(void*);
    DestructorFunc m_destructor;
 
    std::vector<ExportedMethodGroup*> m_vMethod;
    std::vector<ExportedMethodGroup*> m_vConstMethod;
    std::string m_tooltip;
 
    bool  m_constructAsSmartPtr;
};
 
 
template <typename TClass>
class ExportedClass : public ExportedClassBaseImpl
{
  private:
  //  disallow
    ExportedClass () {};
    ExportedClass (const ExportedClass& other);
 
  public:
  //  contructor
    ExportedClass(const std::string& name, const std::string& group,
                   const std::string& tooltip)
        : ExportedClassBaseImpl(tooltip)
    {
      ClassNameProvider<TClass>::set_name(name, group, true);
      ClassNameProvider<const TClass>::set_name(name, group, true);
    }
 
    virtual ~ExportedClass(){}
 
    virtual const std::string& name() const {return ClassNameProvider<TClass>::name();}
 
    virtual const ClassNameNode& class_name_node() const {return ClassNameProvider<TClass>::class_name_node();}
 
    virtual const std::string& group() const {return ClassNameProvider<TClass>::group();}
 
    virtual bool is_json_constructible() const { return std::is_base_of<JSONConstructible, TClass>::value; }
 
  //\todo: remove this method, use class name nodes instead
    virtual const std::vector<const char*>* class_names() const {return &ClassNameProvider<TClass>::names();}
 
    template<typename T>
    ExportedClass<TClass>& add_(T t)
    {
      return t.add_to(*this);
    }
 
    template <typename TMethod>
    ExportedClass<TClass>& add_method (std::string methodName, TMethod func,
                                        std::string retValInfos = "", std::string paramInfos = "",
                                        std::string tooltip = "", std::string help = "")
    {
    //  At this point the method name contains parameters (name|param1=...).
    //todo: they should be removed and specified with an extra parameter.
 
      std::string strippedMethodName = methodName;
      std::string methodOptions;
      std::string::size_type pos = strippedMethodName.find("|");
      if(pos != std::string::npos){
        methodOptions = strippedMethodName.substr(pos + 1, strippedMethodName.length() - pos);
        strippedMethodName = strippedMethodName.substr(0, pos);
      }
 
    //  trim whitespaces
      strippedMethodName = TrimString(strippedMethodName);
      methodOptions = TrimString(methodOptions);
 
    //  check that name is not empty
      if(strippedMethodName.empty())
      {
        UG_THROW_REGISTRY_ERROR(strippedMethodName,
                "Trying to register empty method name.");
      }
      
      // check that name does not contain illegal characters
      if (!IsValidRegistryIdentifier(strippedMethodName)) {
        UG_THROW_REGISTRY_ERROR(strippedMethodName,
        "Trying to register method '"<< strippedMethodName << "' that"
        << " contains illegal characters. "
        << GetRegistryIdentifierMessage());
      }
 
    //  if the method is already in use, we have to add an overload.
    //  If not, we have to create a new method group
      ExportedMethodGroup* methodGrp = NULL;
      if(func_traits<TMethod>::const_method)
        methodGrp = get_const_exported_method_group(strippedMethodName);
      else
        methodGrp = get_exported_method_group(strippedMethodName);
 
      if(!methodGrp){
        methodGrp = new ExportedMethodGroup(strippedMethodName);
        if(func_traits<TMethod>::const_method)
          m_vConstMethod.push_back(methodGrp);
        else
          m_vMethod.push_back(methodGrp);
      }
 
      bool success = methodGrp->add_overload(func, &MethodProxy<TClass, TMethod>::apply,
                           ClassNameProvider<TClass>::name(),
                           methodOptions, retValInfos, paramInfos,
                           tooltip, help);
 
      if(!success)
      {
        UG_THROW_REGISTRY_ERROR(name(),
        "Trying to register method name '" << strippedMethodName
        << "' to class '" << name() << "', but another method with this name "
        << " and the same function signature is already registered for this class.");
      }
 
      return *this;
    }
 
    ExportedClass<TClass>& add_constructor ()
    {
    //  add also in new style
      add_constructor<void (*)()>();
 
    //  remember constructor proxy
      m_destructor = &DestructorProxy<TClass>;
 
      return *this;
    }
 
 
    template <typename TFunc>
    ExportedClass<TClass>& add_constructor(std::string paramInfos = "",
                                           std::string tooltip = "", std::string help = "",
                                           std::string options = "")
    {
    //  return-type must be void
      if(!(std::is_void< typename func_traits<TFunc>::return_type >::value))
      {
        UG_THROW_REGISTRY_ERROR(name(),
        "Trying to register constructor of class "
         <<name()<<"with non-void return value in signature function.");
      }
 
    //  type id of constructor
      size_t typeID = GetUniqueTypeID<TFunc>();
 
    //  make sure that the overload didn't exist
      if(constructor_type_id_registered(typeID))
      {
        UG_THROW_REGISTRY_ERROR(name(),
        "Trying to register constructor of class "
         <<name()<<" with same signature twice.");
      }
 
    //  create new exported constructor
      ExportedConstructor* expConstr
        = new ExportedConstructor(  &ConstructorProxy<TClass, TFunc>::create,
                                    ClassNameProvider<TClass>::name(),
                      options, paramInfos, tooltip, help);
 
    //  create parameter stack
      expConstr->create_parameter_stack<TFunc>();
 
    //  rememeber it
      m_vConstructor.push_back(ConstructorOverload(expConstr, typeID));
 
    //  done
      return *this;
    }
 
    virtual DeleteFunction get_delete_function() const
    {
      return CastAndDelete<TClass>;
    }
};
 
// end group registry
 
} // end namespace bridge
} // end namespace ug
 
 
#endif /* __H__UG_BRIDGE__CLASS__ */