From 48e2bc0bdbb4971986748944e7a0e4b0b597f170 Mon Sep 17 00:00:00 2001 From: Douglas Gregor Date: Wed, 12 Mar 2003 23:27:25 +0000 Subject: [PATCH] Import of BoostBook documentation for any, array, bind, function, ref, and signals libraries. [SVN r17866] --- doc/faq.xml | 56 ++++++ doc/function.xml | 66 +++++++ doc/history.xml | 87 +++++++++ doc/misc.xml | 65 +++++++ doc/reference.xml | 450 ++++++++++++++++++++++++++++++++++++++++++++++ doc/tests.xml | 248 +++++++++++++++++++++++++ doc/tutorial.xml | 324 +++++++++++++++++++++++++++++++++ 7 files changed, 1296 insertions(+) create mode 100644 doc/faq.xml create mode 100644 doc/function.xml create mode 100644 doc/history.xml create mode 100644 doc/misc.xml create mode 100644 doc/reference.xml create mode 100644 doc/tests.xml create mode 100644 doc/tutorial.xml diff --git a/doc/faq.xml b/doc/faq.xml new file mode 100644 index 0000000..c9e9ac6 --- /dev/null +++ b/doc/faq.xml @@ -0,0 +1,56 @@ + + +
+ Frequently Asked Questions + + + + I see void pointers; is this [mess] type safe? + +Yes, boost::function 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). + + + + + Why are there workarounds for void returns? C++ allows them! + Void returns are permitted by the C++ standard, as in this code snippet: +void f(); +void g() { return f(); } + + + This is a valid usage of boost::function because void returns are not used. With void returns, we would attempting to compile ill-formed code similar to: +int f(); +void g() { return f(); } + + + In essence, not using void returns allows +boost::function to swallow a return value. This is +consistent with allowing the user to assign and invoke functions and +function objects with parameters that don't exactly match. + + + + + + Why (function) cloning? + + 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. + + + + +
diff --git a/doc/function.xml b/doc/function.xml new file mode 100644 index 0000000..210f0e1 --- /dev/null +++ b/doc/function.xml @@ -0,0 +1,66 @@ + + + + + + Douglas + Gregor + gregod@cs.rpi.edu + + + + 2001 + 2002 + 2003 + Douglas Gregor + + + + 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. + + + Function object wrappers for deferred calls or callbacks + + + +Boost.Function + +
+Introduction +The Boost.Function library contains 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. + + 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. +
+ + + + + + + + + diff --git a/doc/history.xml b/doc/history.xml new file mode 100644 index 0000000..63fb44e --- /dev/null +++ b/doc/history.xml @@ -0,0 +1,87 @@ + + +
+ History & Compatibility Notes + + + Version 1.30.0: + + All features deprecated in version 1.29.0 have + been removed from Boost.Function. + + boost::function + and boost::functionN objects + can be assigned to 0 (semantically equivalent to calling + clear()) and + compared against 0 (semantically equivalent to calling + empty()). + + The Boost.Function code is now generated + entirely by the Preprocessor library, + so it is now possible to generate + boost::function and + boost::functionN class + templates for any number of arguments. + + The + boost::bad_function_call exception class + was introduced. + + + + Version 1.29.0: + 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: + + + The boost::function class template syntax has + changed. The old syntax, e.g., boost::function<int, float, + double, std::string>, has been changed to a more natural + syntax boost::function<int (float, double, + std::string)>, where all return and argument types are + encoded in a single function type parameter. Any other template + parameters (e.g., the Allocator) follow this single + parameter. + + The resolution to this change depends on the + abilities of your compiler: if your compiler supports template + partial specialization and can parse function types (most do), modify + your code to use the newer + syntax (preferable) or directly use one of the + functionN classes whose syntax has not + changed. If your compiler does not support template partial + specialization or function types, you must take the latter option and + use the numbered Boost.Function classes. This option merely requires + changing types such as boost::function<void, int, int> + to boost::function2<void, int, int> (adding the number of + function arguments to the end of the class name). + + Support for the old syntax with the + boost::function class template will persist for a short + while, but will eventually be removed so that we can provide better + error messages and link compatibility. + + The invocation + policy template parameter (Policy) has been deprecated + and will be removed. There is no direct equivalent to this rarely + used feature. + + The mixin template parameter + (Mixin) has been deprecated and will be removed. There + is not direct equivalent to this rarely used feature. + + The + set methods have been deprecated and will be + removed. Use the assignment operator instead. + + + + +
diff --git a/doc/misc.xml b/doc/misc.xml new file mode 100644 index 0000000..29807de --- /dev/null +++ b/doc/misc.xml @@ -0,0 +1,65 @@ + + +
+ Miscellaneous Notes + +
+ Boost.Function vs. Function Pointers +Boost.Function has several advantages over function pointers, namely: + + + Boost.Function allows arbitrary compatible function objects to be targets (instead of requiring an exact function signature). + Boost.Function may be used with argument-binding and other function object construction libraries. + Boost.Function has predictible behavior when an empty function object is called. + + + And, of course, function pointers have several advantages over Boost.Function: + + + Function pointers are smaller (the size of one pointer instead of three) + Function pointers are faster (Boost.Function may require two calls through function pointers) + Function pointers are backward-compatible with C libraries. + More readable error messages. + + +
+ +
+ Performance + +
+ Function object wrapper size + 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. +
+ +
+ Copying efficiency + 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 ref) if the cost of this cloning becomes prohibitive. +
+ +
+ Invocation efficiency + 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). +
+
+ +
+ Combatting virtual function "bloat" + 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 boost::function objects are used. + + 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. +
+ +
+ Acknowledgements + + 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. Peter Dimov led us to the function + declarator-based syntax. +
+
diff --git a/doc/reference.xml b/doc/reference.xml new file mode 100644 index 0000000..f20c073 --- /dev/null +++ b/doc/reference.xml @@ -0,0 +1,450 @@ + + + + + +
+ Definitions + + + + A function object f is + compatible if for the given set of argument + types Arg1, + Arg2, ..., + ArgN and a + return type ResultType, the + appropriate following function is well-formed: + + // if ResultType is not void + ResultType foo(Arg1 arg1, Arg2 arg2, ..., ArgN argN) + { + return f(arg1, arg2, ..., argN); + } + + // if ResultType is void + ResultType foo(Arg1 arg1, Arg2 arg2, ..., ArgN argN) + { + f(arg1, arg2, ..., argN); + } + + + A special provision is made for pointers to member + functions. Though they are not function objects, Boost.Function + will adapt them internally to function objects. This requires + that a pointer to member function of the form R + (X::*mf)(Arg1, Arg2, ..., ArgN) + cv-quals be adapted to a + function object with the following function call operator + overloads: + + template<typename P> + R operator()(cv-quals P& x, Arg1 arg1, Arg2 arg2, ..., ArgN argN) const + { + return (*x).*mf(arg1, arg2, ..., argN); + } + + + + + A function object f of + type F is + stateless if it is a function pointer or if + boost::is_stateless<T> + is true. The construction of or copy to a Boost.Function object + from a stateless function object will not cause exceptions to be + thrown and will not allocate any storage. + + + + +
+ +
+ + + std::runtime_error + An exception type thrown when an instance of a function object is empty when invoked. + + Constructs a bad_function_call exception object. + + + + + The common base class for all Boost.Function + objects. Objects of type function_base may not be created + directly. + + + + true if this has a target, and false otherwise. + Will not throw. + + + + + + + + function_base + + A set of generalized function pointers that can be used for callbacks or wrapping function objects. + + + Class template functionN is actually a + family of related classes function0, + function1, etc., up to some + implementation-defined maximum. In this context, + N refers to the number of + parameters. + + + R + Allocator + + T1If N == 1 + + + T1 + If N == 2 + + + T2 + If N == 2 + + T1 + T2 + + TN + + + + + this->empty() + Will not throw. + + + + + const functionN& + + Contains a copy of the f's target, if it has one, or is empty if f.empty(). + Will not throw unless copying the target of f throws. + + + + + F + F is a function object Callable from this. + *this targets a copy of f if f is nonempty, or this->empty() if f is empty. + Will not throw when f is a stateless function object. + + + + If !this->empty(), destroys the target of this. + + + + + + const functionN& + + *this targets a copy of f's target, if it has one, or is empty if f.empty(). + Will not throw when the target of f is a stateless function object or a reference to the function object. + + + + + const functionN& + Interchanges the targets of *this and f. + Will not throw. + + + + this->empty() + Will not throw. + + + + + + bool + true if this has a target, and false otherwise. + Will not throw. + + + + A safe_bool that evaluates false in a boolean context when this->empty(), and true otherwise. + Will not throw. + + + + this->empty() + Will not throw. + + + + + + arg1_type + arg2_type + ... + argN_type + f(a1, a2, ..., aN), where f is the target of *this. + if R is void, nothing is returned; otherwise, the return value of the call to f is returned. + bad_function_call if !this->empty(). Otherwise, may through any exception thrown by the target function f. + + + + + + + functionN<T1, T2, ..., TN, Allocator>& + functionN<T1, T2, ..., TN, Allocator>& + f1.swap(f2) + Will not throw. + + + + + + + const functionN<T1, T2, ..., TN, Allocator1>& + const functionN<U1, U2, ..., UN, Allocator2>& + This function must be left undefined. + The safe_bool conversion opens a loophole whereby two function instances can be compared via ==. This undefined void operator == closes the loophole and ensures a compile-time or link-time error. + + + + + const functionN<T1, T2, ..., TN, Allocator1>& + const functionN<U1, U2, ..., UN, Allocator2>& + This function must be left undefined. + The safe_bool conversion opens a loophole whereby two function instances can be compared via !=. This undefined void operator != closes the loophole and ensures a compile-time or link-time error. + + + + + + + functionN<R, T1, T2, ..., TN, Allocator> + + A generalized function pointer that can be used for + callbacks or wrapping function objects. + + + Class template function is a thin wrapper + around the numbered class templates function0, function1, etc. It accepts a + function type with N arguments and will will derive from + functionN instantiated with the arguments it receives. + + The semantics of all operations in class template + function are equivalent to that of the underlying + functionN object, although additional member + functions are required to allow proper copy construction and + copy assignment of function objects. + + + R + Allocator + + T1If N == 1 + + + T1 + If N == 2 + + + T2 + If N == 2 + + T1 + T2 + + TN + + + + + this->empty() + Will not throw. + + + + + const functionN& + + Contains a copy of the f's target, if it has one, or is empty if f.empty(). + Will not throw unless copying the target of f throws. + + + + + const function& + + Contains a copy of the f's target, if it has one, or is empty if f.empty(). + Will not throw unless copying the target of f throws. + + + + + F + F is a function object Callable from this. + *this targets a copy of f if f is nonempty, or this->empty() if f is empty. + Will not throw when f is a stateless function object. + + + + If !this->empty(), destroys the target of this. + + + + + + const functionN& + + *this targets a copy of f's target, if it has one, or is empty if f.empty() + Will not throw when the target of f is a stateless function object or a reference to the function object. + + + + + const function& + + *this targets a copy of f's target, if it has one, or is empty if f.empty() + Will not throw when the target of f is a stateless function object or a reference to the function object. + + + + + const function& + Interchanges the targets of *this and f. + Will not throw. + + + + this->empty() + Will not throw. + + + + + + true if this has a target, and false otherwise. + Will not throw. + + + + A safe_bool that evaluates false in a boolean context when this->empty(), and true otherwise. + Will not throw. + + + + this->empty() + Will not throw. + + + + + + arg1_type + arg2_type + ... + argN_type + f(a1, a2, ..., aN), where f is the target of *this. + if R is void, nothing is returned; otherwise, the return value of the call to f is returned. + bad_function_call if !this->empty(). Otherwise, may through any exception thrown by the target function f. + + + + + + + function<Signature, Allocator>& + function<Signature, Allocator>& + f1.swap(f2) + Will not throw. + + + + + + + const function<Signature1, Allocator1>& + const function<Signature2, Allocator2>& + This function must be left undefined. + The safe_bool conversion opens a loophole whereby two function instances can be compared via ==. This undefined void operator == closes the loophole and ensures a compile-time or link-time error. + + + + + const function<Signature1, Allocator1>& + const function<Signature2, Allocator2>& + This function must be left undefined. + The safe_bool conversion opens a loophole whereby two function instances can be compared via !=. This undefined void operator != closes the loophole and ensures a compile-time or link-time error. + + + + +
+ diff --git a/doc/tests.xml b/doc/tests.xml new file mode 100644 index 0000000..3a34722 --- /dev/null +++ b/doc/tests.xml @@ -0,0 +1,248 @@ + + + + + Test the capabilities of the boost::function class template. + The boost::function class template may not be usable on your compiler. However, the library may still be usable via the boost::functionN class templates. + + + + Test the capabilities of the boost::functionN class templates. + + + + ../../../libs/test/build/boost_test_exec_monitor + Test the use of custom allocators. + Allocators are ignored by the implementation. + + + + ../../../libs/test/build/boost_test_exec_monitor + Test the optimization of stateless function objects in the Boost.Function library. + The exception-safety and performance guarantees given for stateless function objects may not be met by the implementation. + + + + ../../../libs/test/build/boost_test_exec_monitor + Test the interaction between Boost.Function and Boost.Lambda. + Either Boost.Lambda does not work on the platform, or Boost.Function cannot safely be applied without the use of boost::unlambda. + + + + Test the (incorrect!) use of comparisons between Boost.Function function objects. + Intuitive (but incorrect!) code may compile and will give meaningless results. + + + + Test the use of an incompatible function object with Boost.Function + Incorrect code may compile (with potentially unexpected results). + + + + Test the generation of a Boost.Function function object adaptor accepting 30 arguments. + The Boost.Function library may work for function object adaptors of up to 10 parameters, but will be unable to generate adaptors for an arbitrary number of parameters. Failure often indicates an error in the compiler's preprocessor. + + + + + +#include +]]> + + + + +int main() +{ + + + + + + + + return 0; +} + + Test the first tutorial example. + + + + + +#include +]]> + + +int main() +{ + + + + + + + + return 0; +} + + Test the first tutorial example. + + + + + +#include +]]> + +int main() +{ + + + + return 0; +} + + Test the second tutorial example. + + + + + +#include +]]> + +int main() +{ + + + + return 0; +} + + Test the second tutorial example. + + + + + +#include +#include +]]> + +int X::foo(int x) { return -x; } + +int main() +{ + + + return 0; +} + + Test member function example from tutorial. + + + + + +#include +#include +]]> + +int X::foo(int x) { return -x; } + +int main() +{ + + + return 0; +} + + Test member function example from tutorial. + + + + + +#include +#include +]]> + +int X::foo(int x) { return -x; } + +int main() +{ + + + return 0; +} + + Test standard binders example from tutorial. + + + + + +#include +#include +]]> + +int X::foo(int x) { return -x; } + +int main() +{ + + + return 0; +} + + Test standard binders example from tutorial. + + + + + +#include +]]> + +struct stateful_type { int operator()(int) const { return 0; } }; + +int main() +{ + + + return 0; +} + + Test boost::ref example from tutorial. + + + + + +#include +]]> + +struct stateful_type { int operator()(int) const { return 0; } }; + +int main() +{ + + + return 0; +} + + Test boost::ref example from tutorial. + + diff --git a/doc/tutorial.xml b/doc/tutorial.xml new file mode 100644 index 0000000..68da82a --- /dev/null +++ b/doc/tutorial.xml @@ -0,0 +1,324 @@ + + +
+Tutorial + + + + Boost.Function has two syntactical forms: the preferred form +and the portable form. The preferred form fits more closely with the +C++ language and reduces the number of separate template parameters +that need to be considered, often improving readability; however, the +preferred form is not supported on all platforms due to compiler +bugs. The compatible form will work on all compilers supported by +Boost.Function. Consult the table below to determine which syntactic +form to use for your compiler. + + + + + + Preferred syntax + Portable syntax + + + + + + + GNU C++ 2.95.x, 3.0.x, 3.1.x + Comeau C++ 4.2.45.2 + SGI MIPSpro 7.3.0 + Intel C++ 5.0, 6.0 + Compaq's cxx 6.2 + + + + + Any compiler supporting the preferred syntax + Microsoft Visual C++ 6.0, 7.0 + Borland C++ 5.5.1 + Sun WorkShop 6 update 2 C++ 5.3 + Metrowerks CodeWarrior 8.1 + + + + + + + + + + If your compiler does not appear in this list, please try the preferred syntax and report your results to the Boost list so that we can keep this table up-to-date. + + + +
+Basic Usage A function wrapper is defined simply +by instantiating the function class +template with the desired return type and argument types, formulated +as a C++ function type. 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: + + + + + + Preferred syntax + Portable syntax + + + + + +boost::function<float (int x, int y)> f; + + +boost::function2<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: + + + + Preferred syntax + + + +boost::function<void (int values[], int n, int& sum, float& avg)> sum_avg; + + + + + + + + Portable syntax + + + +boost::function4<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, and will throw a bad_function_call exception). We can check for an +empty function object wrapper by using it in a boolean context (it evaluates true if the wrapper is not empty) or compare it against 0. For instance: +if (f) + std::cout << f(5, 3) << std::endl; +else + std::cout << "f has no target, so it is unsafe to call" << std::endl; + + + Alternatively, +empty() +method will return whether or not the wrapper is empty. + + Finally, we can clear out a function target by assigning it to 0 or by calling the clear() member function, e.g., +f = 0; + + +
+ +
+ Free functions + 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. +
+ +
+ Member functions + + 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); +}; + + + + + + Preferred syntax + Portable syntax + + + + + +boost::function<int (X*, int)> f; + +f = &X::foo; + +X x; +f(&x, 5); + + +boost::function2<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: + + Bind. This library allows binding of + arguments for any function object. It is lightweight and very + portable. + + The C++ Standard library. Using + std::bind1st and + std::mem_fun together one can bind + the object of a pointer-to-member function for use with + Boost.Function: + + + + + + Preferred syntax + Portable syntax + + + + + + boost::function<int (int)> f; + X x; + f = std::bind1st( + std::mem_fun(&X::foo), &x); + f(5); // Call x.foo(5) + + + boost::function1<int, int> f; + X x; + f = std::bind1st( + std::mem_fun(&X::foo), &x); + f(5); // Call x.foo(5) + + + + + + + + + The Lambda library. 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. + + + +
+ +
+ References to Functions 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: + + + + + + Preferred syntax + Portable syntax + + + + + + stateful_type a_function_object; + boost::function<int (int)> f; + f = boost::ref(a_function_object); + + boost::function<int (int)> f2(f); + + + stateful_type a_function_object; + boost::function1<int, int> f; + f = boost::ref(a_function_object); + + boost::function1<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 or construction. + +
+
+