= Executor =
[[TracNav(TracNav/TOC_Development)]]
[[TOC]]

== Description ==
Executor is a wrapper around [wiki:Functor]. Executor implements additional features like a name, default values, descriptions and more. While Functor already allows you to bind an object to the function, Executor allows you to bind arguments to the function by using default values. With that you can store a whole functioncall (including object and arguments) in one single class and execute it whenever and wherever you want. This features is used by [wiki:Timer], [wiki:ConsoleCommand] and many more.

== Usage ==
=== Creation ===
To create an Executor, you first have to create a [wiki:Functor] (usually by using the helper function '''createFunctor('''''function-pointer''''')'''). Then you call '''createExecutor('''''functor''''')''' to create the Executor. Of course you can also use '''new Executor('''''functor''''')'''.
{{{
void function();

Executor* myexecutor = createExecutor(createFunctor(&function));
}}}

'''Important''': createExecutor uses '''new''' to create the executor. If you are responsible for the Executor, you have to delete it afterwards.

'''Important''': If an Executor gets deleted, it deletes it's Functor too, so you don't have to care about the Functor. '''Never''' share Functors among different Executors, this would lead to a crash.

It's also possible to give the Executor a name:
{{{
void function();

Executor* myexecutor = createExecutor(createFunctor(&function), "name");
}}}
This is usually unnecessary, but very important for [wiki:ConsoleCommand] and other features.

=== Call ===
You can call an Executor just as you call a [wiki:Functor]:
{{{
void function(int value);
Executor* myexecutor = createExecutor(createFunctor(&function));

(*myexecutor)(10); // equivalent to function(10);
}}}

=== Default Values ===
It's possible to add a default value for every argument:
{{{
void function(bool value1, float value2, int value3);
Executor* myexecutor = createExecutor(createFunctor(&function));

// Variant 1: Bind a default value to all arguments:
myexecutor->setDefaultValues(false, 2.5, 10);
}}}
{{{
// Variant 2: Bind default values to specific arguments:
myexecutor->setDefaultValue(0, false); // the first argument
myexecutor->setDefaultValue(1, 2.5);   // the second argument
myexecutor->setDefaultValue(2, 10);    // the third argument
}}}
(The second variant allows you to only bind the last argument for example.)

Then you can call the Executor without passing arguments; the Executor uses the previously added default values to compensate the missing arguments:
{{{
(*myexecutor)(); // equivalent to function(false, 2.5, 10);
}}}

Of course you can still use arguments to overwrite default values:
{{{
(*myexecutor)(true, 3.3); // equivalent to function(true, 3.3, 10);
}}}

=== Descriptions ===
 * '''setDescription('''''description''''')''': Sets the description of the Executor (what the function does)
 * '''getDescription()''': Returns the description of the Executor

 * '''setDescriptionParam('''''param number (0-4)''''', '''''description''''')''': Sets the description of an argument (what the argument does)
 * '''getDescriptionParam('''''param number (0-4)''''')''': Returns the description of an argument

 * '''setDescriptionReturnvalue('''''description''''')''': Sets the description of the return value (what the return value does)
 * '''getDescriptionReturnvalue()''': Returns the description of the return value

=== Other Functions ===
 * '''getName()''': Returns the Executors name
 * '''getFunctor()''': Returns a pointer to the Functor

 * '''getDefaultValue('''''param number (0-4)''''')''': Returns the default value for the given argument
 * '''allDefaultValuesSet()''': Returns true if there's a default value for every argument

 * '''getParamCount()''': Returns the amount of parameters the function takes
 * '''hasReturnvalue()''': Returns true if the function returns a value
 * '''getReturnvalue()''': Returns the value returned by the last call of the Functor
 * '''getType()''': Returns the type of the function as an enum: FT_MEMBER, FT_CONSTMEMBER, FT_STATIC
 * '''getTypenameParam('''''param number (0-4)''''')''': Returns the typename
 * '''getTypenameReturnvalue()''': Returns the typename of the returnvalue as a string

== Subtypes ==
There are two subclasses of Executor:

=== ExecutorStatic ===
ExecutorStatic accepts only a [wiki:Functor#FunctorStatic FunctorStatic]. Read the linked chapter for more information.

=== ExecutorMember ===
ExecutorMember accepts only a [wiki:Functor#FunctorMember FunctorMember]. Read the linked chapter for more information. To call an ExecutorMember, just use it like FunctorMember:
{{{
class SomeClass
{
    void someFunction(int value);
};

SomeClass* object = new SomeClass();
ExecutorMember* executor = createExecutor(createFunctor(&SomeClass::someFunction));

(*executor)(object, 10); // this is equivalent to object->someFunction(10);

// And with default value:
executor->setDefaultValues(20);

(*executor)(object); // this is equivalent to object->someFunction(20);
}}}

== Illustration ==
[[Image(Executor.png)]]