<p> The header <<aHREF="../../boost/function.hpp">boost/function.hpp</a>> includes a family of class templates that are function object wrappers. The notion is similar to a generalized callback. It shares features with function pointers in that both define a call interface (e.g., a function taking two integer arguments and returning a floating-point value) through which some implementation can be called, and the implementation that is invoked may change throughout the course of the program.
<p> Generally, any place in which a function pointer would be used to defer a call or make a callback, Boost.Function can be used instead to allow the user greater flexibility in the implementation of the target. Targets can be any 'compatible' function object (or function pointer), meaning that the arguments to the interface designated by Boost.Function can be converted to the arguments of the target function object.
<p> Boost.Function has been partially redesigned to minimize the interface and make it cleaner. Several seldom- or never-used features of the older Boost.Function have been deprecated and will be removed in the near future. Here is a list of features that have been deprecated, the likely impact of the deprecations, and how to adjust your code:
<ul>
<li>The <code>boost::function</code> class template syntax has changed. The old syntax, e.g., <code>boost::function<int, float, double, std::string></code>, has been changed to a more natural syntax <code>boost::function<int (float, double, std::string)></code>, where all return and argument types are encoded in a single function type parameter. Any other template parameters (e.g., the <code>Allocator</code>) follow this single parameter.
<p> The resolution to this change depends on the abilities of your compiler: if your compiler supports template partial specialization (most do), modify your code to use the newer syntax (preferable) or directly use one of the <code>function<em>N</em></code> classes whose syntax has not changed. If your compiler does not support template partial specialization, you must take the latter option and use the numbered Boost.Function classes.
<p> Support for the old syntax with the <code>boost::function</code> class template will persist for a short while, but will eventually be removed so that we can provide better error messages and link compatibility. </li>
<li>The invocation policy template parameter (<code>Policy</code>) has been deprecated and will be removed. There is no direct equivalent to this rarely used feature.</li>
<li>The mixin template parameter (<code>Mixin</code>) has been deprecated and will be removed. There is not direct equivalent to this rarely used feature.</li>
<li>The <code>set</code> methods have been deprecated and will be removed. Use the assignment operator instead.</li>
<p>Boost.Function has several advantages over function pointers, namely:
<ul>
<li>Boost.Function allows arbitrary compatible function objects to be targets (instead of requiring an exact function signature).</li>
<li>Boost.Function may be used with argument-binding and other function object construction libraries.</li>
<li>Boost.Function has predictible debug behavior when an empty function object is called. </li>
<li>Boost.Function can be adapted to perform operations before and after each call, allowing, for instance, synchronization primitives to be made part of the function type.</li>
</ul>
And, of course, function pointers have several advantages over Boost.Function:
<ul>
<li> Function pointers are smaller (the size of one pointer instead of three) </li>
<li> Function pointers are faster (Boost.Function may require two calls through function pointers) </li>
<li> Function pointers are backward-compatible with C libraries.</li>
<li> More readable error messages. </li>
</ul>
<p> The above two lists were adapted from comments made by Darin Adler.
<p> Function object wrappers will be the size of two function pointers plus one function pointer or data pointer (whichever is larger). On common 32-bit platforms, this amounts to 12 bytes per wrapper. Additionally, the function object target will be allocated on the heap.
<p> Copying function object wrappers may require allocating memory for a copy of the function object target. The default allocator may be replaced with a faster custom allocator or one may choose to allow the function object wrappers to only store function object targets by reference (using <ahref="../bind/ref.html"><code>ref</code></a>) if the cost of this cloning becomes prohibitive.
<p> With a properly inlining compiler, an invocation of a function object requires one call through a function pointer. If the call is to a free function pointer, an additional call must be made to that function pointer (unless the compiler has very powerful interprocedural analysis).
<p> The function object wrappers have been designed to be as portable as possible, and to support many compilers even when they do not support the C++ standard well. The following compilers have passed all of the test cases included with <code>boost::function</code>.
<p> The following compilers work with <code>boost::function</code>, but have some problems:
<ul>
<li>Microsoft Visual C++ 6.0 (service pack 5): allocators not supported, some problems with <code>boost::function</code> class template (numbered variants seem to work)</li>
<p> If your compiler is not listed, there is a small set of tests to stress the capabilities of the <code>boost::function</code> library. A standards-compliant compiler should compile the code without any modifications, but if you find you run into problems please submit a bug report.
<p> The use of virtual functions tends to cause 'code bloat' on many compilers. When a class contains a virtual function, it is necessary to emit an additional function that classifies the type of the object. It has been our experience that these auxiliary functions increase the size of the executable significantly when many <code>boost::function</code> objects are used.
<p> In Boost.Function, an alternative but equivalent approach was taken using free functions instead of virtual functions. The Boost.Function object essentially holds two pointers to make a valid target call: a void pointer to the function object it contains and a void pointer to an "invoker" that can call the function object, given the function pointer. This invoker function performs the argument and return value conversions Boost.Function provides. A third pointer points to a free function called the "manager", which handles the cloning and destruction of function objects. The scheme is typesafe because the only functions that actually handle the function object, the invoker and the manager, are instantiated given the type of the function object, so they can safely cast the incoming void pointer (the function object pointer) to the appropriate type.
<p> Many people were involved in the construction of this library. William Kempf, Jesse Jones and Karl Nelson were all extremely helpful in isolating an interface and scope for the library. John Maddock managed the formal review, and many reviewers gave excellent comments on interface, implementation, and documentation.
