Boost.Function TutorialBoost.Function Tutorial A function wrapper is defined simply by instantiating the function class template with the desired return type and argument types. Any number of arguments may be supplied, up to some implementation-defined limit (10 is the default maximum). The following declares a function object wrapper f that takes two int parameters and returns a float:
boost::function<float, int, int> f;
By default, function object wrappers are empty, so we can create a
function object to assign to f:
struct int_div {
float operator()(int x, int y) const { return ((float)x)/y; };
};
f = int_div();
Now we can use f to execute the underlying function object
int_div:
std::cout << f(5, 3) << std::endl;
We are free to assign any compatible function object to f. If int_div had been declared to take two long operands,
the implicit conversions would have been applied to the arguments without any user interference. The only limit on the types of arguments is that they be CopyConstructible, so we can even use references and arrays:
boost::function<void, int[], int, int&, float&> sum_avg;
void do_sum_avg(int values[], int n, int& sum, float& avg)
{
sum = 0;
for (int i = 0; i < n; i++)
sum += values[i];
avg = (float)sum / n;
}
sum_avg = &do_sum_avg;
Invoking a function object wrapper that does not actually contain a function object is a precondition violation, much like trying to call through a null function pointer. We can check for an empty function object wrapper by querying its empty() method or, more succinctly, by using it in a boolean context: if it evaluates true, it contains a function object target, i.e.,
if (f) std::cout << f(5, 3) << std::endl; else std::cout << "f has no target, so it is unsafe to call" << std::endl;
We can clear out a function target using the clear() member function.
Free function pointers can be considered singleton function objects with const function call operators, and can therefore be directly used with the function object wrappers:
float mul_ints(int x, int y) { return ((float)x) * y; }
f = &mul_ints;
Note that the & isn't really necessary unless you happen to be using Microsoft Visual C++ version 6.
In many systems, callbacks often call to member functions of a particular object. This is often referred to as "argument binding", and is beyond the scope of Boost.Function. The use of member functions directly, however, is supported, so the following code is valid:
struct X {
int foo(int);
};
boost::function<int, X*, int> f;
f = &X::foo;
X x;
f(&x, 5);
Several libraries exist that support argument binding. Three such libraries are summarized below:
std::bind1st and std::mem_fun together one can bind the object of a pointer-to-member function for use with Boost.Function:
struct X {
int foo(int);
};
boost::function<int, int> f;
X x;
f = std::bind1st(std::mem_fun(&X::foo), &x);
f(5); // Call x.foo(5) In some cases it is expensive (or semantically incorrect) to have
Boost.Function clone a function object. In such cases, it is possible
to request that Boost.Function keep only a reference to the actual
function object. This is done using the ref and cref functions to wrap a
reference to a function object:
stateful_type a_function_object; boost::function<int, int> f; f = ref(a_function_object); boost::function<int, int> f2(f);Here,
f will not make a copy of
a_function_object, nor will f2 when it is
targeted to f's reference to
a_function_object. Additionally, when using references to
function objects, Boost.Function will not throw exceptions during assignment.
function family The header <boost/function.hpp> defines the primary entry point to the function object wrappers, the class template boost::function. This class template is essentially a thin wrapper around a set of similar numbered function object wrappers, boost::function0, boost::function1, etc., where the number indicates the number of arguments passed to the function object target. The declaration of f above could also be written as:
boost::function2<float, int, int> f;
The numbered class templates contain most of the implementation and are each distinct class templates. They may be helpful if used in shared libraries, where the number of arguments supported by Boost.Function may change between revisions. Additionally, some compilers (e.g., Microsoft Visual C++ 6.0) have been known to be incapable of compiling boost::function in some instances but are able to handle the numbered variants.
The boost::function family supports additional customization by means of policies, mixins, and allocators. The specific usage of each of these will be explained in later sections, but they share a common problem: how to replace each default with your own version.
With boost::function it is not so clear, because support for an arbitrary number of parameters means that it is impossible to specify just the last parameter, but not 5 of the parameters in between. Therefore, boost::function doubles as a generative interface for the underlying numbered class templates that uses named template parameters. For instance, to specify both a policy and an allocator for a function object wrapper f taking an int and returning an int, use:
function<int, int>::policy<MyPolicy>::allocator<MyAllocator>::type f;
The named template parameters policy, mixin and allocator each take one template parameter (the replacement class) and may be nested as above to generate a function object wrapper. The ::type at the end accesses the actual type that fits the given properties.
Policies define what happens directly before and directly after an invocation of a function object target is made. A policy must have two member functions, precall and postcall, each of which must be able to accept a const function object wrapper pointer. The following policy will print "before" prior to execution and "after" afterwards:
struct print_policy {
void precall(const boost::function_base*) { std::cout << "before"; }
void postcall(const boost::function_base*) { std::cout << "after"; }
};
A new instance of the policy class will be created prior to calling the function object target and will be preserved until after the call has returned. Therefore, for any invocation the precall and postcall will be executed on the same policy class instance; however, policy class instances will not be kept between target invocations.
Policies are further described in the Boost discussion on generic programming techniques.
The function object wrappers allow any class to be "mixed in" as a base class. This allows extra members and/or functionality to be included by the user. This can be used, for instance, to overcome the limitations of policies by storing data between invocations in a base class instead of in a static member of a policy class.
The function object wrappers allow the user to specify a new allocator to handle the cloning of function object targets (when the wrappers are copied). The allocators used are the same as the C++ standard library allocators. The wrappers assume the allocators are stateless, and will create a new instance each time they are used (because they are rebound very often). This shares the semantics of most standard library implementations, and is explicitly allowed by the C++ standard.
Synchronization of callbacks in a multithreaded environment is extremely important. Using mixins and policies, a Boost.Function object may implement its own synchronization policy that ensures that only one thread can be in the callback function at any given point in time.
We will use the prototype Boost.Threads library for its recursive_mutex. Since the mutex is on a per-callback basis, we will add a mutex to the boost::function by mixin it in with this mixin class:
class SynchronizedMixin {
mutable boost::recursive_mutex mutex;
};
Next, we create a policy that obtains a lock before the target is called (via the precall function) and releases the lock after the target has been called (via the postcall function):
class SynchronizedPolicy {
std::auto_ptr<boost::recursive_mutex::lock> lock;
void precall(const SynchronizedMixin* f)
{
lock.reset(new boost::recursive_mutex::lock(f->mutex));
}
void postcall(const SynchronizedMixin* f)
{
lock.reset();
}
};
The use of std::auto_ptr ensures that the lock will be destroyed (and therefore released) if an exception is thrown by the target function. Now we can use the policy and mixin together to create a synchronized callback:
boost::function2<float, int, int, SynchronizedPolicy, SynchronizedMixin> f;