## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links 
## note.0= 
## descriptive title for the tutorial
## title = Function Objects
## multi-line description to be displayed in search 
## description = Passing functions around as typed class objects.
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=
## next.1.link=
## what level user is this tutorial for 
## level= IntermediateCategory
## keywords = ecl function objects
####################################

<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

<<TableOfContents(4)>>

== Introduction ==

Resolving c++ function passing (as arguments to other functions)
is complicated by the differences between global/static and member
functions as well as by the awkward syntax. Here we attempt to
provide a standardised approach to using them.

== Definition ==

One way of standardising the approach is to utilise the idea of a
function object (also known as functor). A function object is simply
an object that characterises a function. In c++, this has three
advantages:

 * Function code can be inlined (instead of repeated pointer calls) when used repetitively in a loop.
 * The function object can maintain state, something which pure function callbacks cannot do.
 * The syntax is much cleaner and more flexible.

An example of a unary function object is given below:

{{{
#!cplusplus
class Sum {
    int val;
public:
    Sum(int i) :val(i) { }
    int operator()(int i) { return val+=i; }        // unary function
};
}}}

We also make a terminology distinction here when distinguishing between ''free'' and ''member'' functions. Free functions are defined to be global or static functions.

== Compiling & Linking ==

Include some or all of the following at the top of any translation unit that requires compilation of class that uses parameters.

{{{
#!cplusplus
#include <ecl/utilities.hpp>

// The classes
using ecl::NullaryFunction;
using ecl::UnaryFunction;
using ecl::BinaryFunction;
using ecl::NullaryFreeFunction;
using ecl::UnaryFreeFunction;
using ecl::BoundUnaryFreeFunction;
using ecl::NullaryMemberFunction;
using ecl::BoundNullaryMemberFunction;
using ecl::UnaryMemberFunction;
using ecl::PartiallyBoundUnaryMemberFunction;
using ecl::BoundUnaryMemberFunction;
using ecl::NullaryFunctionCopy;
using ecl::NullaryFunctionReference;
using ecl::UnaryFunctionCopy;
using ecl::UnaryFunctionReference;

// Overloaded utility functions
using ecl::generateFunctionObject;
}}}

Since it is a template class, no linking is required if you are only using this class.

== Usage ==

Many of the higher level classes in the ecl utilise function objects, e.g. [[ecl_threads]], [[ecl_sigslots]]. These classes expect certain concepts to be fulfilled when accepting function objects as arguments and also make use of some of the convenience classes/tools in the above list.

=== Concepts ===

Classes that accept function objects generally utilise a template parameter and require the function object to fulfill the requirements of a concept. For example, threads require function objects to satisfy the nullary function concept. The current list of concepts for function objects include:

 * `NullaryFunction`

Documentation for the concepts can be found in the [[ecl_concepts]] package.

=== Creating Your Own Function Objects ===

When constructing your own function object classes to be used with higher level ecl components, they must conform to the requirements of their target concept. For example, a suitable thread class function object:

{{{
#!cplusplus
class ThreadFunction {
public:
    typedef void result_type;
    void operator()() {
        // thread worker function
    }
};
ThreadFunction thread_function;
Thread thread(thread_function); // Alternatively Thread thread = Thread(ThreadFunction());
}}}

=== Wrapping Free/Member Functions ===

Wrapping functions can be done via construction calls to many of the classes listed above, however to make it easier, there is the overloaded
`ecl::generateFunctionObject` method.

A good example of its usage is with the ecl Thread class where a
nullary function object is required for construction.

{{{
#!cplusplus
int f(int i) {}
class A {
    void f() {}
    void g(int i) {}
};
// ...
A a;
Thread thread0(generateFunctionObject(f, 3));         // Bind the first argument to a global function
Thread thread1(generateFunctionObject(&A::f, a));     // Bind an object instance with the nullary function
Thread thread2(generateFunctionObject(&A::g, a, 2));  // Bind object instance, first argument to a unary member function
}}}

For member functions, in the above code we bound the instance with the member function. Alternatively, you can leave it free so that the following two lines of code produce the same result:

{{{
#!cplusplus
generateFunctionObject(&A::f, a)(); // This case produces and calls a nullary function
generateFunctionObject(&A::f)(a);   // This case produces and calls a unary function
}}}

=== Case Scenario : Threads ===

Threads uses the tools here, an example of thread function loading is shown below.

{{{
#!cplusplus
A a;                             // Just an ordinary class with nullary member f().
NullaryFunction function_object; // Conforms to the concept above.
Thread thread_f1(f);
Thread thread_f2(&A::f,a);
Thread thread_f3(generateFunctionObject(f));
Thread thread_f4(generateFunctionObject(g,1));
Thread thread_f5(generateFunctionObject(&A::f,a));
Thread thread_f6(generateFunctionObject(&A::g,a,2));
Thread thread_f7(function_object);
Thread thread_f8 = NullaryFunction();
Thread thread_f8(ref(function_object));
}}}

== Limitations ==

We only utilise at most one argument to any free/member function. In practice a limit has to be drawn somewhere and I find you can always bundle however many arguments you wish into an appropriately defined structure, so either none or one is always sufficient for all purposes.

## AUTOGENERATED DO NOT DELETE 
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE