Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 4, 2010, 11:33:02 PM (15 years ago)
Author:
landauf
Message:

added documentation

also some small naming and readability changes in the code.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • code/branches/doc/src/libraries/core/command/Executor.h

    r7284 r7352  
    2828 */
    2929
     30/**
     31    @defgroup FunctorExecutor Functor and Executor
     32    @ingroup Command
     33*/
     34
     35/**
     36    @file
     37    @ingroup Command FunctorExecutor
     38    @brief Declaration of the orxonox::Executor class and the createExecutor() functions.
     39
     40    @anchor ExecutorExample
     41
     42    orxonox::Executor is used to wrap an orxonox::Functor and to store default values for
     43    its parameters. Usually one uses the function createExecutor() to create a new executor.
     44    This function returns an orxonox::ExecutorPtr which is a typedef of @ref orxonox::SharedPtr
     45    "SharedPtr<Executor>", used to manage the pointer to the executor.
     46
     47    Executors are mostly used to execute callbacks. Because some callback functions need arguments,
     48    Executor provides an easy interface to store these arguments as default values, so the
     49    executor can also be executed without arguments because it will use these default values.
     50
     51    The Executor doesn't contain the function-pointer directly. Instead it wraps an instance
     52    of orxonox::Functor. See @ref FunctorExample "Functor.h" for more information and some
     53    examples.
     54
     55    Example:
     56    @code
     57    void myFunction(int a, int b)                           // declare a static function
     58    {
     59        COUT(0) << "The sum is " << (a + b) << std::endl;   // print the sum of a and b to the console
     60    }
     61
     62    FunctorPtr functor = createFunctor(&myFunction);        // create a functor that wraps the function-pointer
     63    ExecutorPtr executor = createExecutor(functor);         // create an executor that wraps the functor
     64
     65    (*executor)(2, 5);                                      // calls the executor with arguments 2 and 5, prints "The sum is 7" to the console
     66
     67    executor->setDefaultValue(1, 10);                       // sets the default-value for the second parameter (note: paramters start at index 0) to 10
     68
     69    (*executor)(2);                                         // calls the executor with argument 2 and default-value 10, prints "The sum is 12"
     70
     71    executor->setDefaultValue(0, 5);                        // sets the default-value for the first parameter to 5
     72
     73    (*executor)();                                          // calls the executor with default-values only, prints "The sum is 15"
     74    @endcode
     75
     76    Because executors that were created with createExecutor() are managed by an orxonox::SharedPtr,
     77    they don't need to be deleted after usage.
     78*/
     79
    3080#ifndef _Executor_H__
    3181#define _Executor_H__
    … …  
    4090namespace orxonox
    4191{
     92    /**
     93        @brief This class is used to wrap a Functor and to store default values for any of its parameters.
     94
     95        @see See @ref ExecutorExample "Executor.h" for an example.
     96    */
    4297    class _CoreExport Executor
    4398    {
    … …  
    47102            virtual ~Executor();
    48103
     104            /// Calls the wrapped function with 0 arguments. If the function needs more arguments, the executor's default values are used.
    49105            inline MultiType operator()() const
    50106                { return (*this->functor_)(this->defaultValue_[0], this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    51             inline MultiType operator()(const MultiType& param1) const
    52                 { return (*this->functor_)(param1, this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    53             inline MultiType operator()(const MultiType& param1, const MultiType& param2) const
    54                 { return (*this->functor_)(param1, param2, this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    55             inline MultiType operator()(const MultiType& param1, const MultiType& param2, const MultiType& param3) const
    56                 { return (*this->functor_)(param1, param2, param3, this->defaultValue_[3], this->defaultValue_[4]); }
    57             inline MultiType operator()(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4) const
    58                 { return (*this->functor_)(param1, param2, param3, param4, this->defaultValue_[4]); }
    59             inline MultiType operator()(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5) const
    60                 { return (*this->functor_)(param1, param2, param3, param4, param5); }
     107            /// Calls the wrapped function with 1 argument. If the function needs more arguments, the executor's default values are used.
     108            inline MultiType operator()(const MultiType& arg1) const
     109                { return (*this->functor_)(arg1, this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
     110            /// Calls the wrapped function with 2 arguments. If the function needs more arguments, the executor's default values are used.
     111            inline MultiType operator()(const MultiType& arg1, const MultiType& arg2) const
     112                { return (*this->functor_)(arg1, arg2, this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
     113            /// Calls the wrapped function with 3 arguments. If the function needs more arguments, the executor's default values are used.
     114            inline MultiType operator()(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3) const
     115                { return (*this->functor_)(arg1, arg2, arg3, this->defaultValue_[3], this->defaultValue_[4]); }
     116            /// Calls the wrapped function with 4 arguments. If the function needs more arguments, the executor's default values are used.
     117            inline MultiType operator()(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4) const
     118                { return (*this->functor_)(arg1, arg2, arg3, arg4, this->defaultValue_[4]); }
     119            /// Calls the wrapped function with 5 arguments. If the function needs more arguments, the executor's default values are used.
     120            inline MultiType operator()(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5) const
     121                { return (*this->functor_)(arg1, arg2, arg3, arg4, arg5); }
    61122
    62123            MultiType parse(const std::string& arguments, int* error = 0, const std::string& delimiter = " ", bool bPrintError = false) const;
    63124            MultiType parse(const SubString& arguments, int* error = 0, const std::string& delimiter = " ", bool bPrintError = false) const;
    64125
    65             int evaluateParams(const SubString& arguments, MultiType param[MAX_FUNCTOR_ARGUMENTS], int* error = 0, const std::string& delimiter = " ") const;
    66 
     126            int evaluateArguments(const SubString& arguments, MultiType arg[MAX_FUNCTOR_ARGUMENTS], int* error = 0, const std::string& delimiter = " ") const;
     127
     128            /// Changes the functor.
    67129            inline void setFunctor(const FunctorPtr& functor)
    68130                { this->functor_ = functor; }
     131            /// Returns the functor.
    69132            inline const FunctorPtr& getFunctor() const
    70133                { return this->functor_; }
    71134
     135            /// Changes the name of the executor.
    72136            inline void setName(const std::string& name)
    73137                { this->name_ = name; }
     138            /// Returns the name of the executor.
    74139            inline const std::string& getName() const
    75140                { return this->name_; }
    76141
     142            /// Returns the number of parameters of the wrapped function.
    77143            inline unsigned int getParamCount() const
    78144                { return this->functor_->getParamCount(); }
     145            /// Returns true if the wrapped function returns a value.
    79146            inline bool hasReturnvalue() const
    80147                { return this->functor_->hasReturnvalue(); }
     148            /// Returns the type of the wrapped function (static or member).
    81149            inline Functor::Type::Enum getType() const
    82150                { return this->functor_->getType(); }
     151            /// Returns the name of the type of a parameter with given index (the first parameter has index 0).
    83152            inline std::string getTypenameParam(unsigned int param) const
    84153                { return this->functor_->getTypenameParam(param); }
     154            /// Returns the name of the type of the return value.
    85155            inline std::string getTypenameReturnvalue() const
    86156                { return this->functor_->getTypenameReturnvalue(); }
    87157
    88             void setDefaultValues(const MultiType& param1);
    89             void setDefaultValues(const MultiType& param1, const MultiType& param2);
    90             void setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3);
    91             void setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4);
    92             void setDefaultValues(const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5);
    93             void setDefaultValue(unsigned int index, const MultiType& param);
    94 
     158            void setDefaultValues(const MultiType& arg1);
     159            void setDefaultValues(const MultiType& arg1, const MultiType& arg2);
     160            void setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3);
     161            void setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4);
     162            void setDefaultValues(const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5);
     163            void setDefaultValue(unsigned int index, const MultiType& arg);
     164
     165            /// Returns the default value for a parameter with given index (the first parameter has index 0).
    95166            inline MultiType getDefaultValue(unsigned int index) const
    96167            {
    … …  
    102173
    103174            bool allDefaultValuesSet() const;
     175
     176            /// Returns true if the executor contains a default value for the parameter with given index (the first parameter has index 0).
    104177            inline bool defaultValueSet(unsigned int index) const
    105178            {
    … …  
    111184
    112185        protected:
    113             FunctorPtr functor_;
    114             std::string name_;
    115             MultiType defaultValue_[MAX_FUNCTOR_ARGUMENTS];
     186            FunctorPtr functor_;                                ///< The underlying Functor that wraps a function
     187            std::string name_;                                  ///< The name of the executor
     188            MultiType defaultValue_[MAX_FUNCTOR_ARGUMENTS];     ///< The default values, one for each parameter
    116189    };
    117190
     191    /**
     192        @brief A child class of Executor, used to distinguish executors that wrap static functions from executors that wrap member-functions.
     193
     194        Behaves exactly like Executor, because static functions need no special treatment.
     195    */
    118196    class _CoreExport ExecutorStatic : public Executor
    119197    {
    120198        public:
     199            /// Constructor: Initializes the parent class
    121200            ExecutorStatic(const FunctorStaticPtr& functor, const std::string& name = "") : Executor(functor, name) {}
     201            /// Destructor
    122202            virtual ~ExecutorStatic() {}
    123203    };
    124204
     205    /**
     206        @brief A child class of Executor, used for easier handling of non-static member-functions.
     207
     208        Overloads some functions that call the underlying FunctorMember and additionally pass
     209        an object-pointer that is needed for non-static member-functions.
     210    */
    125211    template <class T>
    126212    class ExecutorMember : public Executor
    127213    {
    128214        public:
     215            /// Constructor: Initializes the parent class and the pointer to the member-functor.
    129216            ExecutorMember(const FunctorMemberPtr<T>& functor, const std::string& name = "") : Executor(functor, name), functorMember_(functor) {}
     217            /// Destructor
    130218            virtual ~ExecutorMember() {}
    131219
    132220            using Executor::operator();
    133221
     222            /// Calls the wrapped function with 0 arguments and an object-pointer. If the function needs more arguments, the executor's default values are used.
    134223            inline MultiType operator()(T* object) const
    135224                { return (*this->functorMember_)(object, this->defaultValue_[0], this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    136             inline MultiType operator()(T* object, const MultiType& param1) const
    137                 { return (*this->functorMember_)(object, param1, this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    138             inline MultiType operator()(T* object, const MultiType& param1, const MultiType& param2) const
    139                 { return (*this->functorMember_)(object, param1, param2, this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    140             inline MultiType operator()(T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3) const
    141                 { return (*this->functorMember_)(object, param1, param2, param3, this->defaultValue_[3], this->defaultValue_[4]); }
    142             inline MultiType operator()(T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4) const
    143                 { return (*this->functorMember_)(object, param1, param2, param3, param4, this->defaultValue_[4]); }
    144             inline MultiType operator()(T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5) const
    145                 { return (*this->functorMember_)(object, param1, param2, param3, param4, param5); }
    146 
    147 
    148             inline MultiType operator()(const T* object) const
    149                 { return (*this->functorMember_)(object, this->defaultValue_[0], this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    150             inline MultiType operator()(const T* object, const MultiType& param1) const
    151                 { return (*this->functorMember_)(object, param1, this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    152             inline MultiType operator()(const T* object, const MultiType& param1, const MultiType& param2) const
    153                 { return (*this->functorMember_)(object, param1, param2, this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
    154             inline MultiType operator()(const T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3) const
    155                 { return (*this->functorMember_)(object, param1, param2, param3, this->defaultValue_[3], this->defaultValue_[4]); }
    156             inline MultiType operator()(const T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4) const
    157                 { return (*this->functorMember_)(object, param1, param2, param3, param4, this->defaultValue_[4]); }
    158             inline MultiType operator()(const T* object, const MultiType& param1, const MultiType& param2, const MultiType& param3, const MultiType& param4, const MultiType& param5) const
    159                 { return (*this->functorMember_)(object, param1, param2, param3, param4, param5); }
    160 
     225            /// Calls the wrapped function with 1 argument and an object-pointer. If the function needs more arguments, the executor's default values are used.
     226            inline MultiType operator()(T* object, const MultiType& arg1) const
     227                { return (*this->functorMember_)(object, arg1, this->defaultValue_[1], this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
     228            /// Calls the wrapped function with 2 arguments and an object-pointer. If the function needs more arguments, the executor's default values are used.
     229            inline MultiType operator()(T* object, const MultiType& arg1, const MultiType& arg2) const
     230                { return (*this->functorMember_)(object, arg1, arg2, this->defaultValue_[2], this->defaultValue_[3], this->defaultValue_[4]); }
     231            /// Calls the wrapped function with 3 arguments and an object-pointer. If the function needs more arguments, the executor's default values are used.
     232            inline MultiType operator()(T* object, const MultiType& arg1, const MultiType& arg2, const MultiType& arg3) const
     233                { return (*this->functorMember_)(object, arg1, arg2, arg3, this->defaultValue_[3], this->defaultValue_[4]); }
     234            /// Calls the wrapped function with 4 arguments and an object-pointer. If the function needs more arguments, the executor's default values are used.
     235            inline MultiType operator()(T* object, const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4) const
     236                { return (*this->functorMember_)(object, arg1, arg2, arg3, arg4, this->defaultValue_[4]); }
     237            /// Calls the wrapped function with 5 arguments and an object-pointer. If the function needs more arguments, the executor's default values are used.
     238            inline MultiType operator()(T* object, const MultiType& arg1, const MultiType& arg2, const MultiType& arg3, const MultiType& arg4, const MultiType& arg5) const
     239                { return (*this->functorMember_)(object, arg1, arg2, arg3, arg4, arg5); }
     240
     241            /// Changes the object-pointer of the underlying FunctorMember.
    161242            inline void setObject(T* object) const
    162243                { this->functorMember_->setObject(object); }
    163             inline void setObject(const T* object) const
    164                 { this->functorMember_->setObject(object); }
     244            /// Returns the object-pointer of the underlying FunctorMember.
     245            inline T* getObject() const
     246                { return this->functorMember_->getObject(); }
    165247
    166248            using Executor::parse;
    167249
    168             MultiType parse(T* object, const std::string& params, int* error = 0, const std::string& delimiter = " ", bool bPrintError = false) const
     250            /// Overloads Executor::parse() with an additional object-pointer.
     251            MultiType parse(T* object, const std::string& arguments, int* error = 0, const std::string& delimiter = " ", bool bPrintError = false) const
    169252            {
    170253                T* oldobject = this->functorMember_->getObject();
    171254
    172255                this->functorMember_->setObject(object);
    173                 const MultiType& result = this->Executor::parse(params, error, delimiter, bPrintError);
     256                const MultiType& result = this->Executor::parse(arguments, error, delimiter, bPrintError);
    174257                this->functorMember_->setObject(oldobject);
    175258
    … …  
    177260            }
    178261
    179             MultiType parse(const T* object, const std::string& params, int* error = 0, const std::string& delimiter = " ", bool bPrintError = false) const
    180             {
    181                 T* oldobject = this->functorMember_->getObject();
    182 
    183                 this->functorMember_->setObject(object);
    184                 const MultiType& result = this->Executor::parse(params, error, delimiter, bPrintError);
    185                 this->functorMember_->setObjects(oldobject);
    186 
    187                 return result;
    188             }
    189 
    190262        protected:
    191             FunctorMemberPtr<T> functorMember_;
     263            FunctorMemberPtr<T> functorMember_;     ///< A pointer to the FunctorMember is stored separately to avoid casting when executing the function.
    192264    };
    193265
     266    /// Creates a new Executor that wraps a given Functor.
    194267    inline ExecutorPtr createExecutor(const FunctorPtr& functor, const std::string& name = "")
    195268    {
    … …  
    197270    }
    198271
     272    /// Creates a new ExecutorMember that wraps a given FunctorMember.
    199273    template <class T>
    200274    inline ExecutorMemberPtr<T> createExecutor(const FunctorMemberPtr<T>& functor, const std::string& name = "")
    … …  
    203277    }
    204278
     279    /// Creates a new ExecutorStatic that wraps a given FunctorStatic.
    205280    inline ExecutorStaticPtr createExecutor(const FunctorStaticPtr& functor, const std::string& name = "")
    206281    {
Note: See TracChangeset for help on using the changeset viewer.