mirror of
https://github.com/boostorg/function.git
synced 2025-07-21 08:32:07 +02:00
index.html:
- Removed reference and tutorial: now just link to them faq.html: - Moved to doc/faq.html doc/faq.html: - Relative directory fixups doc/reference.html: - Reference manual for Boost.Function doc/tutorial.html: - Tutorial for Boost.Function (the old "Usage" sections) - Additional example showing the use of references and arrays example/bind1st.cpp: example/int_div.cpp: example/sum_avg.cpp: - Examples from tutorial [SVN r10620]
This commit is contained in:
Douglas Gregor
@ -5,7 +5,7 @@
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080">
|
||||
<h1><IMG SRC="../../c++boost.gif" WIDTH="276" HEIGHT="86">boost::function Frequently Asked Questions</h1>
|
||||
<h1><IMG SRC="../../../c++boost.gif" WIDTH="276" HEIGHT="86">boost::function Frequently Asked Questions</h1>
|
||||
|
||||
<h2>Q: I see void pointers; is this [mess] type safe?</h2>
|
||||
<p>Yes, <code>boost::function</code> is type safe even though it uses void pointers and pointers to functions returning void and taking no arguments. Essentially, all type information is encoded in the functions that manage and invoke function pointers and function objects. Only these functions are instantiated with the exact type that is pointed to by the void pointer or pointer to void function. The reason that both are required is that one may cast between void pointers and object pointers safely or between different types of function pointers (provided you don't invoke a function pointer with the wrong type).
|
||||
@ -35,13 +35,13 @@ void g() { return f(); }
|
||||
<p> In November and December of 2000, the issue of cloning vs. reference counting was debated at length and it was decided that cloning gave more predictable semantics. I won't rehash the discussion here, but if it cloning is incorrect for a particular application a reference-counting allocator could be used.
|
||||
|
||||
<h2>Q: How do I assign from a member function?</h2>
|
||||
<p> Member function assignments are not included directly in <code>boost::function</code> because they do not conform to the syntax of function objects. Several libraries exist to wrap member functions in a function object and/or bind the first argument to the member function (the <code>this</code> pointer). A few libraries are <a href="index.html#member_func">described</a> in the <a href="index.html">Boost.Function</a> documentation.
|
||||
<p> Member function assignments are not included directly in <code>boost::function</code> because they do not conform to the syntax of function objects. Several libraries exist to wrap member functions in a function object and/or bind the first argument to the member function (the <code>this</code> pointer). A few libraries are <a href="tutorial.html#member_func">described</a> in the <a href="../index.html">Boost.Function</a> documentation.
|
||||
|
||||
<hr>
|
||||
<address><a href="mailto:gregod@cs.rpi.edu">Doug Gregor</a></address>
|
||||
<!-- Created: Fri Feb 16 09:30:41 EST 2001 -->
|
||||
<!-- hhmts start -->
|
||||
Last modified: Sun Jun 17 10:06:31 EDT 2001
|
||||
Last modified: Sat Jul 14 16:00:11 EDT 2001
|
||||
<!-- hhmts end -->
|
||||
</body>
|
||||
</html>
|
||||
255
doc/reference.html
Normal file
255
doc/reference.html
Normal file
@ -0,0 +1,255 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>Boost.Function Reference Manual</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080">
|
||||
|
||||
<h1><IMG SRC="../../../c++boost.gif" WIDTH="276" HEIGHT="86">Boost.Function Reference Manual</h1>
|
||||
|
||||
<h2><a name="header">Header <code><<a href="../../../boost/function.hpp">boost/function.hpp</a>></code> synopsis</a></h2>
|
||||
<p> Here <code><i>MAX_ARGS</i></code> is an implementation-defined constant that defines the maximum number of function arguments supported by Boost.Function and will be at least 10. The <code><i>MAX_ARGS</i></code> constant referred to in this document need not have any direct representation in the library.
|
||||
|
||||
<pre>
|
||||
namespace boost {
|
||||
class <a href="#function_base">function_base</a>
|
||||
{
|
||||
<a href="#empty">bool empty() const</a>;
|
||||
<a href="#bool">operator bool() const</a>;
|
||||
};
|
||||
|
||||
// For <i>N</i> in [0, <i>MAX_ARGS</i>]
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>N</i>,
|
||||
typename Policy = empty_function_policy,
|
||||
typename Mixin = empty_function_mixin,
|
||||
typename Allocator = std::allocator<function_base> >
|
||||
class <a href="#functionN">function<i>N</i></a> : public <a href="#function_base">function_base</a>, public Mixin
|
||||
{
|
||||
typedef ResultType result_type;
|
||||
typedef Policy policy_type;
|
||||
typedef Mixin mixin_type;
|
||||
typedef Allocator allocator_type;
|
||||
|
||||
typedef Arg1 argument_type; <i>// If N == 1</i>
|
||||
|
||||
typedef Arg1 first_argument_type; <i>// If N == 2</i>
|
||||
typedef Arg2 second_argument_type; <i>// If N == 2</i>
|
||||
|
||||
<i>// Construction</i>
|
||||
<a href="#functionN_default">explicit function<i>N</i>(const Mixin& = Mixin())</a>;
|
||||
<a href="#functionN_copy">function<i>N</i>(const function<i>N</i>&)</a>;
|
||||
<a href="#functionN_target">template<typename F> function<i>N</i>(const F&, const Mixin& = Mixin())</a>;
|
||||
|
||||
<i>// Assignment</i>
|
||||
<a href="#functionN_copy_assn">function<i>N</i>& operator=(const function<i>N</i>&)</a>;
|
||||
<a href="#functionN_target_assn">template<typename F> function<i>N</i>& operator=(const F&)</a>;
|
||||
<a href="#functionN_copy_set">void set(const function<i>N</i>&)</a>;
|
||||
<a href="#functionN_target_set">template<typename F> void set(const F&)</a>;
|
||||
<a href="#functionN_swap">void swap(function<i>N</i>&)</a>;
|
||||
<a href="#functionN_clear">void clear()</a>;
|
||||
|
||||
<i>// Invocation</i>
|
||||
<a href="#functionN_call">result_type operator()(Arg1 a1, Arg2 a2, <i>...</i>, Arg<i>N</i> a<i>N</i>)</a>;
|
||||
<a href="#functionN_call_const">result_type operator()(Arg1 a1, Arg2 a2, <i>...</i>, Arg<i>N</i> a<i>N</i>) const</a>;
|
||||
};
|
||||
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>N</i>,
|
||||
typename Policy,
|
||||
typename Mixin,
|
||||
typename Allocator>
|
||||
inline void <a href="#swap_functionN">swap</a>(const function<Arg1, Arg2, <i>...</i>Arg<i>N</i>, Policy, Mixin, Allocator>&,
|
||||
const function<Arg1, Arg2, <i>...</i>Arg<i>N</i>, Policy, Mixin, Allocator>&);
|
||||
|
||||
// For any <i>N</i> in [0, <i>MAX_ARGS</i>]
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>N</i>,
|
||||
typename Arg<i>N+1</i> = <i>implementation-defined</i>,
|
||||
typename Arg<i>N+2</i> = <i>implementation-defined</i>,
|
||||
<i>...</i>
|
||||
typename Arg<i>MAX_ARGS</i> = <i>implementation-defined</i>>
|
||||
class <a href="#function">function</a> : public <a href="#functionN">function<i>N</i></a><Arg1, Arg2, <i>...</i>, Arg<i>N</i>>
|
||||
{
|
||||
<i>// Construction</i>
|
||||
function();
|
||||
function(const function&);
|
||||
function<i>N</i>(const function<i>N</i>&);
|
||||
template<typename F> function<i>N</i>(const F&);
|
||||
|
||||
<i>// Assignment</i>
|
||||
function& operator=(const function&);
|
||||
function<i>N</i>& operator=(const function<i>N</i>&);
|
||||
template<typename F> function& operator=(const F&);
|
||||
void set(const function&);
|
||||
void set(const function<i>N</i>&);
|
||||
template<typename F> void set(const F&);
|
||||
};
|
||||
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>MAX_ARGS</i>>
|
||||
inline void <a href="#swap_function">swap</a>(const function<Arg1, Arg2, <i>...</i>Arg<i>MAX_ARGS</i>>&,
|
||||
const function<Arg1, Arg2, <i>...</i>Arg<i>MAX_ARGS</i>>&);
|
||||
}
|
||||
</pre>
|
||||
|
||||
<h2><a name="function_base">Class <code>function_base</code></a></h2>
|
||||
<p> Class <code>function_base</code> is the common base class for all Boost.Function objects. Objects of type <code>function_base</code> may not be created directly.
|
||||
|
||||
<p> <a name="empty"><code>bool empty() const</code></a>
|
||||
<ul>
|
||||
<li><b>Returns</b>: <code>true</code> if the function object has a target, <code>false</code> otherwise.</li>
|
||||
<li><b>Throws</b>: will not throw.</li>
|
||||
</ul>
|
||||
|
||||
<p> <a name="bool"><code>operator bool() const</code></a>
|
||||
<ul>
|
||||
<li><b>Returns</b>: <code>!<a href="#empty">empty</a>()</code></li>
|
||||
<li><b>Throws</b>: will not throw.</li>
|
||||
</ul>
|
||||
|
||||
<h2><a name="functionN">Class template <code>function<i>N</i></code></a></h2>
|
||||
<p> Class template <code>function<i>N</i></code> is actually a family of related classes <code>function0</code>, <code>function1</code>, etc., up to some implementation-defined maximum. In this context, <code><i>N</i></code> refers to the number of parameters and <code>f</code> refers to the implicit object parameter.
|
||||
|
||||
<p> <a name="functionN_default"><code>explicit function<i>N</i>(const Mixin& = Mixin());</code></a>
|
||||
<ul>
|
||||
<li><b>Effects</b>: Constructs the <code>Mixin</code> subobject with the given mixin.</li>
|
||||
<li><b>Postconditions</b>: <code>f.<a href="#empty">empty</a>()</code>.</li>
|
||||
<li><b>Throws</b>: will not throw.</li>
|
||||
</ul>
|
||||
|
||||
<p> <a name="functionN_copy"><code>function<i>N</i>(const function<i>N</i>& g);</code></a>
|
||||
<ul>
|
||||
<li><b>Postconditions</b>: <code>f</code> contains a copy of the <code>g</code>'s target, if it has one, or is empty if <code>g.<a href="#empty">empty</a>()</code>. The mixin for the <code>f</code> is copy-constructed from the mixin of <code>g</code>.</li>
|
||||
</ul>
|
||||
|
||||
<p> <a name="functionN_target"><code>template<typename F> function<i>N</i>(const F& g, const Mixin& = Mixin());</code></a>
|
||||
<ul>
|
||||
<li><b>Requires</b>: <code>g</code> is a compatible function object.</li>
|
||||
<li><b>Effects</b>: Constructs the <code>Mixin</code> subobject from the given mixin.</li>
|
||||
<li><b>Postconditions</b>: <code>f</code> targets a copy of <code>g</code> if <code>g</code> is nonempty, or <code>f.<a href="#empty">empty</a>()</code> if <code>g</code> is empty.</li>
|
||||
<li><b>Rationale</b>: <code>g</code> is a reference-to-<code>const</code> because it is a portable, efficient, and concise way to accept any function object or function pointer. In the case of a function pointer, the type of <code>g</code> is reference-to-<code>const</code> pointer-to-function.</li>
|
||||
</ul>
|
||||
|
||||
<p> <a name="functionN_copy_assn"><code>function<i>N</i>& operator=(const function<i>N</i>& g);</code></a>
|
||||
<ul>
|
||||
<li><b>Postconditions</b>: <code>f</code> targets a copy of <code>g</code>'s target, if it has one, or is empty if <code>g.<a href="#empty">empty</a>()</code>. The mixin for <code>f</code> is assigned the value of the mixin for <code>g</code>.</li>
|
||||
<li><b>Returns</b>: <code>*this</code>.</li>
|
||||
<li><b>Throws</b>: TBD: Should meet strong guarantee, but doesn't yet.</li>
|
||||
</ul>
|
||||
|
||||
<p> <a name="functionN_target_assn"><code>template<typename F> function<i>N</i>& operator=(const F& g);</code></a>
|
||||
<ul>
|
||||
<li><b>Requires</b>: <code>g</code> is a compatible function object.</li>
|
||||
<li><b>Postconditions</b>: <code>f</code> targets a copy of <code>g</code> if <code>g</code> is nonempty, or <code>f.<a href="#empty">empty</a>()</code> if <code>g</code> is empty.</li>
|
||||
<li><b>Returns</b>: <code>*this</code>.</li>
|
||||
<li><b>Throws</b>: TBD: Should meet strong guarantee, but doesn't yet.</li>
|
||||
<li><b>Rationale</b>: <code>g</code> is a reference-to-<code>const</code> because it is a portable, efficient, and concise way to accept any function object or function pointer. In the case of a function pointer, the type of <code>g</code> is reference-to-<code>const</code> pointer-to-function.</li>
|
||||
</ul>
|
||||
|
||||
<p> <a name="functionN_copy_set"><code>void set(const function<i>N</i>& g);</code></a>
|
||||
<ul>
|
||||
<li><b>Effects</b>: <code><a href="#functionN_copy_assn">*this = g</a></code>.</li>
|
||||
</ul>
|
||||
|
||||
<p> <a name="functionN_target_set"><code>template<typename F> void set(const F& g);</code></a>
|
||||
<ul>
|
||||
<li><b>Effects</b>: <code><a href="#functionN_target_assn">*this = g</a></code>.</li>
|
||||
</ul>
|
||||
|
||||
<p> <a name="functionN_swap"><code>void swap(function<i>N</i>& g);</code></a>
|
||||
<ul>
|
||||
<li><b>Effects</b>: interchanges the targets of <code>f</code> and <code>g</code>.</li>
|
||||
<li><b>Throws</b>: will not throw.</li>
|
||||
</ul>
|
||||
|
||||
<p> <a name="functionN_clear"><code>void clear(); </code></a>
|
||||
<ul>
|
||||
<li><b>Effects</b>: If <code>!<a href="#empty">empty</a>()</code>, deallocates current target.</li>
|
||||
<li><b>Postconditions</b>: <code><a href="#empty">empty</a>()</code>.</li>
|
||||
</ul>
|
||||
|
||||
<p> <a name="functionN_call"><code> result_type operator()(Arg1 a1, Arg2 a2, <i>...</i>, Arg<i>N</i> a<i>N</i>);</code></a>
|
||||
<ul>
|
||||
<li><b>Requires</b>: <code>!<a href="#empty">empty</a>()</code>.</li>
|
||||
<li><b>Effects</b>: <i>target</i> is the underlying function target. It is not <code>const</code> or <code>volatile</code> qualified.
|
||||
<ol>
|
||||
<li><code>policy_type policy;</code></li>
|
||||
<li><code>policy.precall(this);</code></li>
|
||||
<li><code><i>target</i>(a1, a2, <i>...</i>, a<i>N</i>);</code></li>
|
||||
<li><code>policy.postcall(this);</code></li>
|
||||
</ol>
|
||||
<li><b>Returns</b>: the value returned by <i>target</i>.</li>
|
||||
</ul>
|
||||
|
||||
<p> <a name="functionN_call_const"><code> result_type operator()(Arg1 a1, Arg2 a2, <i>...</i>, Arg<i>N</i> a<i>N</i>) const;</code></a>
|
||||
<ul>
|
||||
<li><b>Requires</b>: <code>!<a href="#empty">empty</a>()</code>.</li>
|
||||
<li><b>Effects</b>: <i>const-target</i> is the underlying function target. It is <code>const</code> qualified but not <code>volatile</code> qualified.
|
||||
<ol>
|
||||
<li><code>policy_type policy;</code></li>
|
||||
<li><code>policy.precall(this);</code></li>
|
||||
<li><code><i>const-target</i>(a1, a2, <i>...</i>, a<i>N</i>);</code></li>
|
||||
<li><code>policy.postcall(this);</code></li>
|
||||
</ol>
|
||||
<li><b>Returns</b>: the value returned by <i>const-target</i>.</li>
|
||||
</ul>
|
||||
|
||||
<h2><a name="function">Class template <code>function</code></a></h2>
|
||||
<p> Class template <code>function</code> is a thin wrapper around the numbered class templates <code>function0</code>, <code>function1</code>, etc. It accepts up to <i>MAX_ARGS</i> arguments, but when passed <i>N</i> arguments it will derive from <code>function<i>N</i></code> specialized with the arguments it receives.
|
||||
|
||||
<p> The semantics of all operations in class template <code>function</code> are equivalent to that of the underlying <code>function<i>N</i></code> object, although additional member functions are required to allow proper copy construction and copy assignment of <code>function</code> objects.
|
||||
|
||||
<h2><a name="operations">Operations</a></h2>
|
||||
<p>
|
||||
<pre>
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>N</i>,
|
||||
typename Policy,
|
||||
typename Mixin,
|
||||
typename Allocator>
|
||||
inline void <a name="swap_functionN">swap</a>(const function<i>N</i><Arg1, Arg2, <i>...</i>Arg<i>N</i>, Policy, Mixin, Allocator>& f,
|
||||
const function<i>N</i><Arg1, Arg2, <i>...</i>Arg<i>N</i>, Policy, Mixin, Allocator>& g);
|
||||
</pre>
|
||||
<ul>
|
||||
<li><b>Effects</b>: <code>f.<a href="#functionN_swap">swap</a>(g);</code></li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
<pre>
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>MAX_ARGS</i>>
|
||||
inline void <a name="swap_function">swap</a>(const function<Arg1, Arg2, <i>...</i>Arg<i>MAX_ARGS</i>>& f,
|
||||
const function<Arg1, Arg2, <i>...</i>Arg<i>MAX_ARGS</i>>& g);
|
||||
</pre>
|
||||
<ul>
|
||||
<li><b>Effects</b>: <code>f.<a href="#functionN_swap">swap</a>(g);</code></li>
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
<address><a href="mailto:gregod@cs.rpi.edu">Douglas Gregor</a></address>
|
||||
<!-- Created: Fri Jul 13 10:57:20 EDT 2001 -->
|
||||
<!-- hhmts start -->
|
||||
Last modified: Sat Jul 14 15:55:35 EDT 2001
|
||||
<!-- hhmts end -->
|
||||
</body>
|
||||
</html>
|
||||
167
doc/tutorial.html
Normal file
167
doc/tutorial.html
Normal file
@ -0,0 +1,167 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>Boost.Function Tutorial</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080">
|
||||
|
||||
<h1><IMG SRC="../../../c++boost.gif" WIDTH="276" HEIGHT="86">Boost.Function Tutorial</h1>
|
||||
|
||||
<h2><a name="usage">Basic usage</a></h2>
|
||||
<p> A function wrapper is defined simply by instantiating the <code>function</code> 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 <code>f</code> that takes two <code>int</code> parameters and returns a <code>float</code>:
|
||||
<pre>
|
||||
boost::<a href="reference.html#function">function</a><float, int, int> f;
|
||||
</pre>
|
||||
|
||||
<p> By default, function object wrappers are empty, so we can create a
|
||||
function object to assign to <code>f</code>:
|
||||
<pre>
|
||||
struct int_div {
|
||||
float operator()(int x, int y) const { return ((float)x)/y; };
|
||||
};
|
||||
|
||||
f = int_div();
|
||||
</pre>
|
||||
|
||||
<p> Now we can use <code>f</code> to execute the underlying function object
|
||||
<code>int_div</code>:
|
||||
<pre>
|
||||
std::cout << f(5, 3) << std::endl;
|
||||
</pre>
|
||||
|
||||
<p> We are free to assign any compatible function object to <code>f</code>. If <code>int_div</code> had been declared to take two <code>long</code> 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:
|
||||
<pre>
|
||||
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;
|
||||
</pre>
|
||||
|
||||
<p> 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 <code><a href="reference.html#empty">empty</a>()</code> method or, more succinctly, by using it in a boolean context: if it evaluates true, it contains a function object target, i.e.,
|
||||
<pre>
|
||||
if (f)
|
||||
std::cout << f(5, 3) << std::endl;
|
||||
else
|
||||
std::cout << "f has no target, so it is unsafe to call" << std::endl;
|
||||
</pre>
|
||||
|
||||
<p> We can clear out a function target using the <code><a href="reference.html#functionN_clear">clear</a>()</code> member function.
|
||||
|
||||
<h3>Free functions</h3>
|
||||
<p> 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:
|
||||
<pre>
|
||||
float mul_ints(int x, int y) { return ((float)x) * y; }
|
||||
f = &mul_ints;
|
||||
</pre>
|
||||
|
||||
<h3>Member functions</h3>
|
||||
<a name="member_func">
|
||||
<p> In many systems, callbacks often call to member functions of a particular
|
||||
object. Handling argument binding is beyond the scope of Boost.Function. However, there are several libraries that perform 'argument binding', including
|
||||
<ul>
|
||||
<li> The C++ Standard library. Using <code>std::bind1st</code> and <code>std::mem_fun</code> together one can bind the object of a pointer-to-member function for use with Boost.Function:
|
||||
<pre>
|
||||
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)</pre></li>
|
||||
|
||||
<li><a href="http://lambda.cs.utu.fi/">The Lambda library</a>. This library provides a powerful composition mechanism to construct function objects that uses very natural C++ syntax. Lambda requires a compiler that is reasonably conformant to the C++ standard. Note that it is not a Boost library.</li>
|
||||
|
||||
<li>Peter Dimov's <a href="http://groups.yahoo.com/group/boost/files/bind/bind.hpp">bind</a> library. It has a smaller scope than the Lambda Library but is more tolerant of broken compilers. It is an unreviewed library in development.</li>
|
||||
</ul>
|
||||
|
||||
<h2><a name="family">The <code>function</code> family</a></h2>
|
||||
<p> The header <<a href="../../boost/function.hpp">boost/function.hpp</a>> defines the primary entry point to the function object wrappers, the class template <code>boost::function</code>. This class template is essentially a thin wrapper around a set of similar numbered function object wrappers, <code>boost::function0</code>, <code>boost::function1</code>, etc., where the number indicates the number of arguments passed to the function object target. The declaration of <code>f</code> above could also be written as:
|
||||
<pre>
|
||||
boost::function2<float, int, int> f;
|
||||
</pre>
|
||||
|
||||
<p> 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 <code>boost::function</code> in some instances but are able to handle the numbered variants.
|
||||
|
||||
<h2><a name="advanced">Advanced usage</a></h2>
|
||||
<p> The <code>boost::function</code> 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.
|
||||
|
||||
<p> With <code>boost::function</code> 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, <code>boost::function</code> 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 <code>f</code> taking an <code>int</code> and returning an <code>int</code>, use:
|
||||
<pre>
|
||||
function<int, int>::policy<MyPolicy>::allocator<MyAllocator>::type f;
|
||||
</pre>
|
||||
|
||||
<p> The named template parameters <code>policy</code>, <code>mixin</code> and <code>allocator</code> each take one template parameter (the replacement class) and may be nested as above to generate a function object wrapper. The <code>::type</code> at the end accesses the actual type that fits the given properties.
|
||||
|
||||
<h3><a name="policies">Policies</a></h3>
|
||||
<p> 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, <code>precall</code> and <code>postcall</code>, each of which must be able to accept a <code>const</code> function object wrapper pointer. The following policy will print "before" prior to execution and "after" afterwards:
|
||||
|
||||
<pre>
|
||||
struct print_policy {
|
||||
void precall(const boost::function_base*) { std::cout << "before"; }
|
||||
void postcall(const boost::function_base*) { std::cout << "after"; }
|
||||
};
|
||||
</pre>
|
||||
|
||||
<p> 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 <code>precall</code> and <code>postcall</code> will be executed on the same policy class instance; however, policy class instances will not be kept between target invocations.
|
||||
|
||||
<p> Policies are further <a href="../../../more/generic_programming.html#policy">described</a> in the Boost discussion on <a href="../../../more/generic_programming.html">generic programming techniques</a>.
|
||||
|
||||
<h3><a name="mixins">Mixins</a></h3>
|
||||
<p> 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 <code>static</code> member of a policy class.
|
||||
|
||||
<h3><a name="allocators">Allocators</a></h3>
|
||||
<p> 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.
|
||||
|
||||
<h3><a name="synchronizing">Example: Synchronized callbacks</a></h3>
|
||||
<p> 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.
|
||||
|
||||
<p> We will use the prototype Boost.Threads library for its <code>recursive_mutex</code>. Since the mutex is on a per-callback basis, we will add a mutex to the <code>boost::function</code> by mixin it in with this mixin class:
|
||||
<pre>
|
||||
class SynchronizedMixin {
|
||||
mutable boost::recursive_mutex mutex;
|
||||
};
|
||||
</pre>
|
||||
|
||||
<p> Next, we create a policy that obtains a lock before the target is called (via the <code>precall</code> function) and releases the lock after the target has been called (via the <code>postcall</code> function):
|
||||
|
||||
<pre>
|
||||
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();
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
|
||||
<p>The use of <code>std::auto_ptr</code> 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:
|
||||
|
||||
<pre>
|
||||
boost::function2<float, int, int, SynchronizedPolicy, SynchronizedMixin> f;
|
||||
</pre>
|
||||
|
||||
<hr>
|
||||
<address><a href="mailto:gregod@cs.rpi.edu">Douglas Gregor</a></address>
|
||||
<!-- Created: Fri Jul 13 12:47:11 EDT 2001 -->
|
||||
<!-- hhmts start -->
|
||||
Last modified: Fri Jul 13 23:58:17 EDT 2001
|
||||
<!-- hhmts end -->
|
||||
</body>
|
||||
</html>
|
||||
38
example/bind1st.cpp
Normal file
38
example/bind1st.cpp
Normal file
@ -0,0 +1,38 @@
|
||||
// Boost.Function library examples
|
||||
|
||||
// Copyright (C) 2001 Doug Gregor (gregod@cs.rpi.edu)
|
||||
//
|
||||
// Permission to copy, use, sell and distribute this software is granted
|
||||
// provided this copyright notice appears in all copies.
|
||||
// Permission to modify the code and to distribute modified code is granted
|
||||
// provided this copyright notice appears in all copies, and a notice
|
||||
// that the code was modified is included with the copyright notice.
|
||||
//
|
||||
// This software is provided "as is" without express or implied warranty,
|
||||
// and with no claim as to its suitability for any purpose.
|
||||
|
||||
// For more information, see http://www.boost.org
|
||||
|
||||
#include <iostream>
|
||||
#include <boost/function.hpp>
|
||||
#include <functional>
|
||||
|
||||
struct X {
|
||||
X(int val) : value(val) {}
|
||||
|
||||
int foo(int x) { return x * value; }
|
||||
|
||||
int value;
|
||||
};
|
||||
|
||||
|
||||
int
|
||||
main()
|
||||
{
|
||||
boost::function<int, int> f;
|
||||
X x(7);
|
||||
f = std::bind1st(std::mem_fun(&X::foo), &x);
|
||||
|
||||
std::cout << f(5) << std::endl; // Call x.foo(5)
|
||||
return 0;
|
||||
}
|
||||
32
example/int_div.cpp
Normal file
32
example/int_div.cpp
Normal file
@ -0,0 +1,32 @@
|
||||
// Boost.Function library examples
|
||||
|
||||
// Copyright (C) 2001 Doug Gregor (gregod@cs.rpi.edu)
|
||||
//
|
||||
// Permission to copy, use, sell and distribute this software is granted
|
||||
// provided this copyright notice appears in all copies.
|
||||
// Permission to modify the code and to distribute modified code is granted
|
||||
// provided this copyright notice appears in all copies, and a notice
|
||||
// that the code was modified is included with the copyright notice.
|
||||
//
|
||||
// This software is provided "as is" without express or implied warranty,
|
||||
// and with no claim as to its suitability for any purpose.
|
||||
|
||||
// For more information, see http://www.boost.org
|
||||
|
||||
#include <iostream>
|
||||
#include <boost/function.hpp>
|
||||
|
||||
struct int_div {
|
||||
float operator()(int x, int y) const { return ((float)x)/y; };
|
||||
};
|
||||
|
||||
int
|
||||
main()
|
||||
{
|
||||
boost::function<float, int, int> f;
|
||||
f = int_div();
|
||||
|
||||
std::cout << f(5, 3) << std::endl; // 1.66667
|
||||
|
||||
return 0;
|
||||
}
|
||||
42
example/sum_avg.cpp
Normal file
42
example/sum_avg.cpp
Normal file
@ -0,0 +1,42 @@
|
||||
// Boost.Function library examples
|
||||
|
||||
// Copyright (C) 2001 Doug Gregor (gregod@cs.rpi.edu)
|
||||
//
|
||||
// Permission to copy, use, sell and distribute this software is granted
|
||||
// provided this copyright notice appears in all copies.
|
||||
// Permission to modify the code and to distribute modified code is granted
|
||||
// provided this copyright notice appears in all copies, and a notice
|
||||
// that the code was modified is included with the copyright notice.
|
||||
//
|
||||
// This software is provided "as is" without express or implied warranty,
|
||||
// and with no claim as to its suitability for any purpose.
|
||||
|
||||
// For more information, see http://www.boost.org
|
||||
|
||||
#include <iostream>
|
||||
#include <boost/function.hpp>
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
int
|
||||
main()
|
||||
{
|
||||
boost::function<void, int[], int, int&, float&> sum_avg;
|
||||
|
||||
sum_avg = &do_sum_avg;
|
||||
|
||||
int values[5] = { 1, 1, 2, 3, 5 };
|
||||
int sum;
|
||||
float avg;
|
||||
sum_avg(values, 5, sum, avg);
|
||||
|
||||
std::cout << "sum = " << sum << std::endl;
|
||||
std::cout << "avg = " << avg << std::endl;
|
||||
return 0;
|
||||
}
|
||||
404
index.html
404
index.html
@ -13,414 +13,16 @@
|
||||
<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.
|
||||
|
||||
<ul>
|
||||
<li><a href="#header">Header <code><boost/function.hpp></code> synopsis</a></li>
|
||||
<li><a href="#function_base">Class <code>function_base</code></a></li>
|
||||
<li><a href="#functionN">Class template <code>function<i>N</i></code></a></li>
|
||||
<li><a href="#function">Class template <code>function</code></a></li>
|
||||
<li><a href="#operations">Operations on function object wrappers</a></li>
|
||||
<li><a href="#usage">Basic usage</a>
|
||||
<ul>
|
||||
<li>Free functions</li>
|
||||
<li>Member functions</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#family">The <code>function</code> family</a></li>
|
||||
<li><a href="#advanced">Advanced usage</a>
|
||||
<ul>
|
||||
<li><a href="#policies">Policies</a></li>
|
||||
<li><a href="#mixins">Mixins</a></li>
|
||||
<li><a href="#allocators">Allocators</a></li>
|
||||
<li><a href="#synchronizing">Example: Synchronized functions</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="doc/tutorial.html">Tutorial</a></li>
|
||||
<li><a href="doc/reference.html">Reference manual</a></li>
|
||||
<li><a href="#vspointers">Boost.Function vs. Function Pointers</a></li>
|
||||
<li><a href="#performance">Performance</a></li>
|
||||
<li><a href="#portability">Portability</a></li>
|
||||
<li><a href="#design">Design rationale</a></li>
|
||||
<li><a href="#acknowledgements">Acknowledgements</a></li>
|
||||
<li><a href="faq.html">Frequently Asked Questions</a></li>
|
||||
<li><a href="doc/faq.html">Frequently Asked Questions</a></li>
|
||||
</ul>
|
||||
|
||||
|
||||
<h2><a name="header">Header <code><boost/function.hpp></code> synopsis</a></h2>
|
||||
<p> Here <code><i>MAX_ARGS</i></code> is an implementation-defined constant that defines the maximum number of function arguments supported by Boost.Function and will be at least 10. The <code><i>MAX_ARGS</i></code> constant referred to in this document need not have any direct representation in the library.
|
||||
|
||||
<pre>
|
||||
namespace boost {
|
||||
class function_base
|
||||
{
|
||||
bool empty() const;
|
||||
operator bool() const;
|
||||
};
|
||||
|
||||
// For <i>N</i> in [0, <i>MAX_ARGS</i>]
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>N</i>,
|
||||
typename Policy = empty_function_policy,
|
||||
typename Mixin = empty_function_mixin,
|
||||
typename Allocator = std::allocator<function_base> >
|
||||
class function<i>N</i> : public function_base, public Mixin
|
||||
{
|
||||
typedef ResultType result_type;
|
||||
typedef Policy policy_type;
|
||||
typedef Mixin mixin_type;
|
||||
typedef Allocator allocator_type;
|
||||
|
||||
typedef Arg1 argument_type; <i>// If N == 1</i>
|
||||
|
||||
typedef Arg1 first_argument_type; <i>// If N == 2</i>
|
||||
typedef Arg2 second_argument_type; <i>// If N == 2</i>
|
||||
|
||||
<i>// Construction</i>
|
||||
function<i>N</i>();
|
||||
function<i>N</i>(const function<i>N</i>&);
|
||||
template<typename F> function<i>N</i>(const F&);
|
||||
|
||||
<i>// Assignment</i>
|
||||
function<i>N</i>& operator=(const function<i>N</i>&);
|
||||
template<typename F> function<i>N</i>& operator=(const F&);
|
||||
void set(const function<i>N</i>&);
|
||||
template<typename F> void set(const F&);
|
||||
void swap(function<i>N</i>&);
|
||||
void clear();
|
||||
|
||||
<i>// Invocation</i>
|
||||
result_type operator()(Arg1 a1, Arg2 a2, <i>...</i>, Arg<i>N</i> a<i>N</i>);
|
||||
result_type operator()(Arg1 a1, Arg2 a2, <i>...</i>, Arg<i>N</i> a<i>N</i>) const;
|
||||
};
|
||||
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>N</i>,
|
||||
typename Policy,
|
||||
typename Mixin,
|
||||
typename Allocator>
|
||||
inline void swap(const function<Arg1, Arg2, <i>...</i>Arg<i>N</i>, Policy, Mixin, Allocator>&,
|
||||
const function<Arg1, Arg2, <i>...</i>Arg<i>N</i>, Policy, Mixin, Allocator>&);
|
||||
|
||||
// For any <i>N</i> in [0, <i>MAX_ARGS</i>]
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>N</i>,
|
||||
typename Arg<i>N+1</i> = <i>implementation-defined</i>,
|
||||
typename Arg<i>N+2</i> = <i>implementation-defined</i>,
|
||||
<i>...</i>
|
||||
typename Arg<i>MAX_ARGS</i> = <i>implementation-defined</i>>
|
||||
class function : public function<i>N</i><Arg1, Arg2, <i>...</i>, Arg<i>N</i>>
|
||||
{
|
||||
<i>// Construction</i>
|
||||
function();
|
||||
function(const function&);
|
||||
function<i>N</i>(const function<i>N</i>&);
|
||||
template<typename F> function<i>N</i>(const F&);
|
||||
|
||||
<i>// Assignment</i>
|
||||
function& operator=(const function&);
|
||||
function<i>N</i>& operator=(const function<i>N</i>&);
|
||||
template<typename F> function& operator=(const F&);
|
||||
void set(const function&);
|
||||
void set(const function<i>N</i>&);
|
||||
template<typename F> void set(const F&);
|
||||
};
|
||||
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>MAX_ARGS</i>>
|
||||
inline void swap(const function<Arg1, Arg2, <i>...</i>Arg<i>MAX_ARGS</i>>&,
|
||||
const function<Arg1, Arg2, <i>...</i>Arg<i>MAX_ARGS</i>>&);
|
||||
}
|
||||
</pre>
|
||||
|
||||
<h2><a name="function_base">Class <code>function_base</code></a></h2>
|
||||
<p> Class <code>function_base</code> is the common base class for all Boost.Function objects. Objects of type <code>function_base</code> may not be created directly.
|
||||
|
||||
<p> <code>bool empty() const</code>
|
||||
<ul>
|
||||
<li><b>Returns</b>: <code>true</code> if the function object has a target, <code>false</code> otherwise.</li>
|
||||
<li><b>Throws</b>: will not throw.</li>
|
||||
<li><b>Complexity</b>: constant.</li>
|
||||
</ul>
|
||||
|
||||
<p> <code>operator bool() const</code>
|
||||
<ul>
|
||||
<li><b>Returns</b>: <code>!empty()</code></li>
|
||||
<li><b>Throws</b>: will not throw.</li>
|
||||
<li><b>Complexity</b>: constant.</li>
|
||||
</ul>
|
||||
|
||||
<h2><a name="functionN">Class template <code>function<i>N</i></code></a></h2>
|
||||
<p> Class template <code>function<i>N</i></code> is actually a family of related classes <code>function0</code>, <code>function1</code>, etc., up to some implementation-defined maximum. In this context, <code><i>N</i></code> refers to the number of parameters and <code>f</code> refers to the implicit object parameter.
|
||||
|
||||
<p> <code>function<i>N</i>();</code>
|
||||
<ul>
|
||||
<li><b>Postconditions</b>: <code>f.empty()</code>.</li>
|
||||
<li><b>Throws</b>: will not throw.</li>
|
||||
<li><b>Complexity</b>: constant.</li>
|
||||
</ul>
|
||||
|
||||
<p> <code>function<i>N</i>(const function<i>N</i>& g);</code>
|
||||
<ul>
|
||||
<li><b>Postconditions</b>: <code>f</code> contains a copy of the <code>g</code>'s target, if it has one, or is empty if <code>g.empty()</code>. The mixin for the <code>f</code> is copy-constructed from the mixin of <code>g</code>.</li>
|
||||
<li><b>Complexity</b>: constant.</li>
|
||||
</ul>
|
||||
|
||||
<p> <code>template<typename F> function<i>N</i>(const F& g);</code>
|
||||
<ul>
|
||||
<li><b>Requires</b>: <code>g</code> is a compatible function object.</li>
|
||||
<li><b>Postconditions</b>: <code>f</code> targets a copy of <code>g</code>.</li>
|
||||
<li><b>Complexity</b>: constant.</li>
|
||||
<li><b>Rationale</b>: <code>g</code> is a reference-to-<code>const</code> because it is a portable, efficient, and concise way to accept any function object or function pointer. In the case of a function pointer, the type of <code>g</code> is reference-to-<code>const</code> pointer-to-function.</li>
|
||||
</ul>
|
||||
|
||||
<p> <code>function<i>N</i>& operator=(const function<i>N</i>& g);</code>
|
||||
<ul>
|
||||
<li><b>Postconditions</b>: <code>f</code> targets a copy of <code>g</code>'s target, if it has one, or is empty if <code>g.empty()</code>. The mixin for <code>f</code> is assigned the value of the mixin for <code>g</code>.</li>
|
||||
<li><b>Returns</b>: <code>*this</code>.</li>
|
||||
<li><b>Throws</b>: TBD: Should meet strong guarantee, but doesn't yet.</li>
|
||||
<li><b>Complexity</b>: constant.</li>
|
||||
</ul>
|
||||
|
||||
<p> <code>template<typename F> function<i>N</i>& operator=(const F& g);</code>
|
||||
<ul>
|
||||
<li><b>Requires</b>: <code>g</code> is a compatible function object.</li>
|
||||
<li><b>Postconditions</b>: <code>f</code> targets a copy of <code>g</code>.</li>
|
||||
<li><b>Returns</b>: <code>*this</code>.</li>
|
||||
<li><b>Throws</b>: TBD: Should meet strong guarantee, but doesn't yet.</li>
|
||||
<li><b>Complexity</b>: constant.</li>
|
||||
<li><b>Rationale</b>: <code>g</code> is a reference-to-<code>const</code> because it is a portable, efficient, and concise way to accept any function object or function pointer. In the case of a function pointer, the type of <code>g</code> is reference-to-<code>const</code> pointer-to-function.</li>
|
||||
</ul>
|
||||
|
||||
<p> <code>void set(const function<i>N</i>& g);</code>
|
||||
<ul>
|
||||
<li><b>Effects</b>: <code>*this = g</code>.</li>
|
||||
</ul>
|
||||
|
||||
<p> <code>template<typename F> void set(const F&);</code>
|
||||
<ul>
|
||||
<li><b>Effects</b>: <code>*this = g</code>.</li>
|
||||
</ul>
|
||||
|
||||
<p> <code>void swap(function<i>N</i>& g);</code>
|
||||
<ul>
|
||||
<li><b>Effects</b>: interchanges the targets of <code>f</code> and <code>g</code>.</li>
|
||||
<li><b>Throws</b>: will not throw.</li>
|
||||
<li><b>Complexity</b>: constant.</li>
|
||||
</ul>
|
||||
|
||||
<p> <code>void clear(); </code>
|
||||
<ul>
|
||||
<li><b>Effects</b>: If <code>!empty()</code>, deallocates current target.</li>
|
||||
<li><b>Postconditions</b>: <code>empty()</code>.</li>
|
||||
<li><b>Complexity</b>: constant.</li>
|
||||
</ul>
|
||||
|
||||
<p> <code> result_type operator()(Arg1 a1, Arg2 a2, <i>...</i>, Arg<i>N</i> a<i>N</i>);</code>
|
||||
<ul>
|
||||
<li><b>Requires</b>: <code>!empty()</code>.</li>
|
||||
<li><b>Effects</b>: <i>target</i> is the underlying function target. It is not <code>const</code> or <code>volatile</code> qualified.
|
||||
<ol>
|
||||
<li><code>policy_type policy;</code></li>
|
||||
<li><code>policy.precall(this);</code></li>
|
||||
<li><code><i>target</i>(a1, a2, <i>...</i>, a<i>N</i>);</code></li>
|
||||
<li><code>policy.postcall(this);</code></li>
|
||||
</ol>
|
||||
<li><b>Returns</b>: the value returned by <i>target</i>.</li>
|
||||
<li><b>Complexity</b>: constant.</li>
|
||||
</ul>
|
||||
|
||||
<p> <code> result_type operator()(Arg1 a1, Arg2 a2, <i>...</i>, Arg<i>N</i> a<i>N</i>) const;</code>
|
||||
<ul>
|
||||
<li><b>Requires</b>: <code>!empty()</code>.</li>
|
||||
<li><b>Effects</b>: <i>const-target</i> is the underlying function target. It is <code>const</code> qualified but not <code>volatile</code> qualified.
|
||||
<ol>
|
||||
<li><code>policy_type policy;</code></li>
|
||||
<li><code>policy.precall(this);</code></li>
|
||||
<li><code><i>const-target</i>(a1, a2, <i>...</i>, a<i>N</i>);</code></li>
|
||||
<li><code>policy.postcall(this);</code></li>
|
||||
</ol>
|
||||
<li><b>Returns</b>: the value returned by <i>const-target</i>.</li>
|
||||
<li><b>Complexity</b>: constant.</li>
|
||||
</ul>
|
||||
|
||||
<h2><a name="function">Class template <code>function</code></a></h2>
|
||||
<p> Class template <code>function</code> is a thin wrapper around the numbered class templates <code>function0</code>, <code>function1</code>, etc. It accepts up to <i>MAX_ARGS</i> arguments, but when passed <i>N</i> arguments it will derive from <code>function<i>N</i></code> specialized with the arguments it receives.
|
||||
|
||||
<p> The semantics of all operations in class template <code>function</code> are equivalent to that of the underlying <code>function<i>N</i></code> object, although additional member functions are required to allow proper copy construction and copy assignment of <code>function</code> objects.
|
||||
|
||||
<h2><a name="operations">Operations on function object wrappers</a></h2>
|
||||
<p>
|
||||
<pre>
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>N</i>,
|
||||
typename Policy,
|
||||
typename Mixin,
|
||||
typename Allocator>
|
||||
inline void swap(const function<Arg1, Arg2, <i>...</i>Arg<i>N</i>, Policy, Mixin, Allocator>& f,
|
||||
const function<Arg1, Arg2, <i>...</i>Arg<i>N</i>, Policy, Mixin, Allocator>& g);
|
||||
</pre>
|
||||
<ul>
|
||||
<li><b>Effects</b>: <code>f.swap(g);</code></li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
<pre>
|
||||
template<typename ResultType,
|
||||
typename Arg1,
|
||||
typename Arg2,
|
||||
<i>...</i>
|
||||
typename Arg<i>MAX_ARGS</i>>
|
||||
inline void swap(const function<Arg1, Arg2, <i>...</i>Arg<i>MAX_ARGS</i>>& f,
|
||||
const function<Arg1, Arg2, <i>...</i>Arg<i>MAX_ARGS</i>>& g);
|
||||
</pre>
|
||||
<ul>
|
||||
<li><b>Effects</b>: <code>f.swap(g);</code></li>
|
||||
</ul>
|
||||
|
||||
<h2><a name="usage">Basic usage</a></h2>
|
||||
<p> A wrapper is defined simply by instantiating the <code>function</code> 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 <code>f</code> that takes two <code>int</code> parameters and returns a <code>float</code>:
|
||||
<pre>
|
||||
boost::function<float, int, int> f;
|
||||
</pre>
|
||||
|
||||
<p> By default, function object wrappers are empty, so we can create a
|
||||
function object to assign to <code>f</code>:
|
||||
<pre>
|
||||
struct int_div { float operator()(int x, int y) const { return ((float)x)/y; }; };
|
||||
f = int_div();
|
||||
</pre>
|
||||
|
||||
<p> Now we can use <code>f</code> to execute the underlying function object
|
||||
<code>int_div</code>:
|
||||
<pre>
|
||||
std::cout << f(5, 3) << std::endl;
|
||||
</pre>
|
||||
|
||||
<p> We are free to assign any compatible function object to <code>f</code>. If <code>int_div</code> had been declared to take two <code>long</code> operands,
|
||||
the implicit conversions would have been applied without any user interference.
|
||||
|
||||
<p> Invoking a function object wrapper that does not actually contain a function object is a precondition violation. We can check for an empty function object wrapper by querying its <code>empty()</code> method or, more succinctly, by using it in a boolean context: if it evaluates true, it contains a function object target, i.e.,
|
||||
<pre>
|
||||
if (f)
|
||||
std::cout << f(5, 3) << std::endl;
|
||||
else
|
||||
std::cout << "f has no target" << std::endl;
|
||||
</pre>
|
||||
|
||||
<p> We can clear out a function target using the <code>clear()</code> member functor.
|
||||
|
||||
<h3>Free functions</h3>
|
||||
<p> 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:
|
||||
<pre>
|
||||
float mul_ints(int x, int y) { return ((float)x) * y; }
|
||||
f = &mul_ints;
|
||||
</pre>
|
||||
|
||||
<h3>Member functions</h3>
|
||||
<a name="member_func">
|
||||
<p> In many systems, callbacks often call to member functions of a particular
|
||||
object. Handling argument binding is beyond the scope of Boost.Function. However, there are several libraries that perform 'argument binding', including
|
||||
<ul>
|
||||
<li> The C++ Standard library. Using <code>std::bind1st</code> and <code>std::mem_fun</code> together one can bind the object of a pointer-to-member function for use with Boost.Function:
|
||||
<pre>
|
||||
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)</pre></li>
|
||||
|
||||
<li><a href="http://lambda.cs.utu.fi/">The Lambda library</a>. This library provides a powerful composition mechanism to construct function objects that uses very natural C++ syntax. Lambda requires a compiler that is reasonably conformant to the C++ standard. Note that it is not a Boost library.</li>
|
||||
|
||||
<li>Peter Dimov's <a href="http://groups.yahoo.com/group/boost/files/bind/bind.hpp">bind</a> library. It has a smaller scope than the Lambda Library but is more tolerant of broken compilers. It is an unreviewed library in development.</li>
|
||||
</ul>
|
||||
|
||||
<h2><a name="family">The <code>function</code> family</a></h2>
|
||||
<p> The header <<a HREF="../../boost/function.hpp">boost/function.hpp</a>> defines the primary entry point to the function object wrappers, the class template <code>boost::function</code>. This class template is essentially a thin wrapper around a set of similar numbered function object wrappers, <code>boost::function0</code>, <code>boost::function1</code>, etc., where the number indicates the number of arguments passed to the function object target. The declaration of <code>f</code> above could also be written as:
|
||||
<pre>
|
||||
boost::function2<float, int, int> f;
|
||||
</pre>
|
||||
|
||||
<p> 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 <code>boost::function</code> in some instances but are able to handle the numbered variants.
|
||||
|
||||
<h2><a name="advanced">Advanced usage</a></h2>
|
||||
<p> The <code>boost::function</code> 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.
|
||||
|
||||
<p> With <code>boost::function</code> 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, <code>boost::function</code> 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 <code>f</code> taking an <code>int</code> and returning an <code>int</code>, use:
|
||||
<pre>
|
||||
function<int, int>::policy<MyPolicy>::allocator<MyAllocator>::type f;
|
||||
</pre>
|
||||
|
||||
<p> The named template parameters <code>policy</code>, <code>mixin</code> and <code>allocator</code> each take one template parameter (the replacement class) and may be nested as above to generate a function object wrapper. The <code>::type</code> at the end accesses the actual type that fits the given properties.
|
||||
|
||||
<h3><a name="policies">Policies</a></h3>
|
||||
<p> 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, <code>precall</code> and <code>postcall</code>, each of which must be able to accept a <code>const</code> function object wrapper pointer. The following policy will print "before" prior to execution and "after" afterwards:
|
||||
|
||||
<pre>
|
||||
struct print_policy {
|
||||
void precall(const boost::function_base*) { std::cout << "before"; }
|
||||
void postcall(const boost::function_base*) { std::cout << "after"; }
|
||||
};
|
||||
</pre>
|
||||
|
||||
<p> 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 <code>precall</code> and <code>postcall</code> will be executed on the same policy class instance; however, policy class instances will not be kept between target invocations.
|
||||
|
||||
<p> Policies are further <a href="../../more/generic_programming.html#policy">described</a> in the Boost discussion on <a href="../../more/generic_programming.html">generic programming techniques</a>.
|
||||
|
||||
<h3><a name="mixins">Mixins</a></h3>
|
||||
<p> 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 <code>static</code> member of a policy class.
|
||||
|
||||
<h3><a name="allocators">Allocators</a></h3>
|
||||
<p> 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.
|
||||
|
||||
<h3><a name="synchronizing">Example: Synchronized callbacks</a></h3>
|
||||
<p> 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.
|
||||
|
||||
<p> We will use the prototype Boost.Threads library for its <code>recursive_mutex</code>. Since the mutex is on a per-callback basis, we will add a mutex to the <code>boost::function</code> by mixin it in with this mixin class:
|
||||
<pre>
|
||||
class SynchronizedMixin {
|
||||
mutable boost::recursive_mutex mutex;
|
||||
};
|
||||
</pre>
|
||||
|
||||
<p> Next, we create a policy that obtains a lock before the target is called (via the <code>precall</code> function) and releases the lock after the target has been called (via the <code>postcall</code> function):
|
||||
|
||||
<pre>
|
||||
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();
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
|
||||
<p>The use of <code>std::auto_ptr</code> 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:
|
||||
|
||||
<pre>
|
||||
boost::function2<float, int, int, SynchronizedPolicy, SynchronizedMixin> f;
|
||||
</pre>
|
||||
|
||||
<h2><a name="vspointers">Boost.Function vs. Function Pointers</a></h2>
|
||||
<p>Boost.Function has several advantages over function pointers, namely:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user