diff --git a/doc/faq.html b/doc/faq.html deleted file mode 100644 index 5b1e07e..0000000 --- a/doc/faq.html +++ /dev/null @@ -1,44 +0,0 @@ - - - - Boost.Function Frequently Asked Questions - - - -

boost::function Frequently Asked Questions

- -

Q: 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). - -

Q: 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(); }
-
- -

One reason for not using void returns is that not all compilers support them. In fact, very few compilers seem to support this trivial feature. Additionally, boost::function is more flexible because it does not use void returns. Consider the following code: -

-int do_something(int);
-
-boost::function f;
-f = do_something;
-
-

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. - -

Q: 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. - -

-
Doug Gregor
- - -Last modified: Wed Nov 7 15:11:52 EST 2001 - - - \ No newline at end of file diff --git a/doc/reference.html b/doc/reference.html deleted file mode 100644 index 4740e4b..0000000 --- a/doc/reference.html +++ /dev/null @@ -1,271 +0,0 @@ - - - - Boost.Function Reference Manual - - - - -

Boost.Function Reference Manual

- -

Header <boost/function.hpp> synopsis

-

Here MAX_ARGS is an implementation-defined constant that defines the maximum number of function arguments supported by Boost.Function and will be at least 10. The MAX_ARGS constant referred to in this document need not have any direct representation in the library. - -

-namespace boost {
-  class function_base  // Deprecated
-  {
-    bool empty() const;
-  };
-
-  // For N in [0, MAX_ARGS]
-  template<typename Signature,
-           typename Arg1,
-	   typename Arg2,
-           ...
-           typename ArgN,
-	   typename Allocator = std::allocator<void> >
-  class functionN : public function_base
-  {
-    typedef implementation-defined safe_bool;
-
-  public:
-    typedef ResultType result_type; // [1]
-    typedef Allocator  allocator_type;
-
-    typedef Arg1 argument_type;        // If N == 1
-
-    typedef Arg1 first_argument_type;  // If N == 2
-    typedef Arg2 second_argument_type; // If N == 2
-
-    typedef Arg1 arg1_type;
-    typedef Arg2 arg2_type;
-             .
-             .
-             .
-    typedef ArgN argN_type;
-
-    enum { arity = N };
-
-    // Construction
-    explicit functionN();
-    functionN(const functionN&);
-    template<typename F> functionN(F);
-    template<typename F> functionN(reference_wrapper<F>);
-    
-    // Assignment
-    functionN& operator=(const functionN&);
-    template<typename F> functionN& operator=(F);
-    template<typename F> functionN& operator=(reference_wrapper<F>);
-    void swap(functionN&);
-    void clear();
-
-    // Boolean context
-    operator safe_bool() const;
-    bool operator!() const;
-
-    // Invocation
-    result_type operator()(Arg1 a1, Arg2 a2, ..., ArgN aN) const;
-  };
-
-  template<typename ResultType,
-           typename Arg1,
-	   typename Arg2,
-           ...
-	   typename ArgN,
-           typename Allocator>
-  void swap(functionN<ResultType, Arg1, Arg2, ..., ArgN, Allocator>&,
-            functionN<ResultType, Arg1, Arg2, ..., ArgN, Allocator>&);
-
-  // For any N in [0, MAX_ARGS]
-  template<typename Signature, // Function type: ResultType (Arg1, Arg2, ..., ArgN)
-	   typename Allocator = std::allocator<void> >
-  class function : public functionN<ResultType, Arg1, Arg2, ..., ArgN, Allocator>
-  {
-    // Construction
-    function();
-    function(const function&);
-    function(const functionN<ResultType, Arg1, Arg2, ..., ArgN, Allocator>&);
-    template<typename F> functionN(F);
-    
-    // Assignment
-    function& operator=(const function&);
-    function& operator=(const functionN<ResultType, Arg1, Arg2, ..., ArgN, Allocator>&);
-    template<typename F> function& operator=(F);
-  };
-
-  template<typename Signature, typename Allocator>
-  void swap(function<Signature, Allocator>&,
-            function<Signature, Allocator>&);
-}	   
-
- -

Definitions

-

-

- -

Class function_base

-

Class function_base is the common base class for all Boost.Function objects. Objects of type function_base may not be created directly. -

Note: the use of this class by users is deprecated. This class will become an implementation detail in the future. -

bool empty() const -

- -

Class template functionN

-

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 and f refers to the implicit object parameter. - -

explicit functionN(); -

- -

functionN(const functionN& g); -

- -

template<typename F> functionN(F g); -

- -

template<typename F> functionN(reference_wrapper<F> g); -

- -

functionN& operator=(const functionN& g); -

- -

template<typename F> functionN& operator=(F g); -

- -

template<typename F> functionN& operator=(reference_wrapper<F> g); -

- -

void swap(functionN& g); -

- -

void clear(); -

- -

operator safe_bool() const -

- -

bool operator!() const -

- -

result_type operator()(Arg1 a1, Arg2 a2, ..., ArgN aN) const; -

- -

Class template function

-

Class template function is a thin wrapper around the numbered class templates function0, function1, etc. It accepts up to MAX_ARGS arguments, but when passed N arguments it will derive from functionN specialized 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. - -

Operations

-

-

-template<typename ResultType,
-         typename Arg1,
-	 typename Arg2,
-         ...
-	 typename ArgN,
-         typename Allocator>
-void swap(functionN<ResultType, Arg1, Arg2, ..., ArgN, Allocator>& f,
-          functionN<ResultType, Arg1, Arg2, ..., ArgN, Allocator>& g);
-
- - -

-

-template<typename Signature, typename Allocator>
-void swap(function<Signature, Allocator>& f,
-          function<Signature, Allocator>& g);
-
- - -
-

[1] On compilers not supporting void returns, when the ReturnType is void, the result_type of a Boost.Function object is implementation-defined. -

-
Douglas Gregor
- - -Last modified: Fri Sep 6 14:46:50 EDT 2002 - - - diff --git a/doc/tutorial.html b/doc/tutorial.html deleted file mode 100644 index 249f300..0000000 --- a/doc/tutorial.html +++ /dev/null @@ -1,258 +0,0 @@ - - - - Boost.Function Tutorial - - - - -

Boost.Function Tutorial

- -

Boost.Function has two syntactical forms: the preferred form and the compatibility 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 SyntaxCompatible 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
    • -
- 		-
    -
  • 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 SyntaxCompatible 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 SyntaxCompatible Syntax
- 
-boost::function<void (int values[], int n, int& sum, float& avg)> sum_avg;
-
- 		- 
-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. 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 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: - -

- - - - - - -
Preferred SyntaxCompatible Syntax
-
-struct X {
-  int foo(int);
-};
-
-boost::function<int (X*, int)> f;
-
-f = &X::foo;
-  
-X x;
-f(&x, 5);
-
- 		-
-struct X {
-  int foo(int);
-};
-
-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: -

 - -

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 SyntaxCompatible Syntax
-
-  stateful_type a_function_object;
-  boost::function<int (int)> f;
-  f = ref(a_function_object);
-
-  boost::function<int (int)> f2(f);
-
- 		-
-  stateful_type a_function_object;
-  boost::function1<int, int> f;
-  f = 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. - -
-
Douglas Gregor
- - -Last modified: Wed Jan 29 08:49:02 EST 2003 - - - diff --git a/index.html b/index.html index b5c59f4..221f49e 100644 --- a/index.html +++ b/index.html @@ -1,137 +1,9 @@ - - - - - Boost.Function - - - - -

C++ BoostHeader <boost/function.hpp>

- -

The header <boost/function.hpp> 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. - -

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. - -

- -

Compatibility Note

-

Version 1.30.0: All deprecated features have been removed -from Boost.Function. - -

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: -

- -

To aid in porting to the new syntax and removing the use of deprecated features, define the preprocessor macro BOOST_FUNCTION_NO_DEPRECATED. This macro makes all deprecated features unavailable. A program compiled with BOOST_FUNCTION_NO_DEPRECATED will likely be prepared when the deprecated features are removed. - -

Boost.Function vs. Function Pointers

-

Boost.Function has several advantages over function pointers, namely: - -

- -

And, of course, function pointers have several advantages over Boost.Function: - -

- - -

The above two lists were adapted from comments made by Darin Adler. - -

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). - -

Portability

-

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 boost::function. -

- -

The following compilers work with boost::function, but have some problems: -

- -

If your compiler is not listed, there is a small set of tests to stress the capabilities of the boost::function 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. - -

Design rationale

-

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. - -

-
Doug Gregor
- + + + + +Automatic redirection failed, please go to +../../doc/html/function.html +