123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316 |
- [library Boost.Functional/Forward
- [quickbook 1.3]
- [version 1.0]
- [authors [Schwinger, Tobias]]
- [copyright 2007 2008 Tobias Schwinger]
- [license
- Distributed under the Boost Software License, Version 1.0.
- (See accompanying file LICENSE_1_0.txt or copy at
- [@http://www.boost.org/LICENSE_1_0.txt])
- ]
- [purpose Function object adapters for generic argument forwarding.]
- [category higher-order]
- [category generic]
- [last-revision $Date: 2008/11/01 19:58:50 $]
- ]
- [def __unspecified__ /unspecified/]
- [def __boost_ref__ [@http://www.boost.org/doc/html/ref.html Boost.Ref]]
- [def __boost_result_of__ [@http://www.boost.org/libs/utility/utility.htm#result_of Boost.ResultOf]]
- [def __boost__result_of__ [@http://www.boost.org/libs/utility/utility.htm#result_of `boost::result_of`]]
- [def __the_forwarding_problem__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm The Forwarding Problem]]
- [def __boost_fusion__ [@http://www.boost.org/libs/fusion/doc/html/index.html Boost.Fusion]]
- [section Brief Description]
- `boost::forward_adapter` provides a reusable adapter template for function
- objects. It forwards RValues as references to const, while leaving LValues
- as-is.
- struct g // function object that only accept LValues
- {
- template< typename T0, typename T1, typename T2 >
- void operator()(T0 & t0, T1 & t1, T2 & t2) const;
- typedef void result_type;
- };
- // Adapted version also accepts RValues and forwards
- // them as references to const, LValues as-is
- typedef boost::forward_adapter<g> f;
- Another adapter, `boost::lighweight_forward_adapter` allows forwarding with
- some help from the user accepting and unwrapping reference wrappers (see
- __boost_ref__) for reference arguments, const qualifying all other arguments.
- The target functions must be compatible with __boost_result_of__, and so are
- the adapters.
- [endsect]
- [section Background]
- Let's suppose we have some function `f` that we can call like this:
- f(123,a_variable);
- Now we want to write another, generic function `g` that can be called the
- same way and returns some object that calls `f` with the same arguments.
- f(123,a_variable) == g(f,123,a_variable).call_f()
- [heading Why would we want to do it, anyway?]
- Maybe we want to run `f` several times. Or maybe we want to run it within
- another thread. Maybe we just want to encapsulate the call expression for now,
- and then use it with other code that allows to compose more complex expressions
- in order to decompose it with C++ templates and have the compiler generate some
- machinery that eventually calls `f` at runtime (in other words; apply a
- technique that is commonly referred to as Expression Templates).
- [heading Now, how do we do it?]
- The bad news is: It's impossible.
- That is so because there is a slight difference between a variable and an
- expression that evaluates to its value: Given
- int y;
- int const z = 0;
- and
- template< typename T > void func1(T & x);
- we can call
- func1(y); // x is a reference to a non-const object
- func1(z); // x is a reference to a const object
- where
- func1(1); // fails to compile.
- This way we can safely have `func1` store its reference argument and the
- compiler keeps us from storing a reference to an object with temporary lifetime.
- It is important to realize that non-constness and whether an object binds to a
- non-const reference parameter are two different properties. The latter is the
- distinction between LValues and RValues. The names stem from the left hand side
- and the right hand side of assignment expressions, thus LValues are typically
- the ones you can assign to, and RValues the temporary results from the right
- hand side expression.
- y = 1+2; // a is LValue, 1+2 is the expression producing the RValue,
- // 1+2 = a; // usually makes no sense.
- func1(y); // works, because y is an LValue
- // func1(1+2); // fails to compile, because we only got an RValue.
- If we add const qualification on the parameter, our function also accepts
- RValues:
- template< typename T > void func2(T const & x);
- // [...] function scope:
- func2(1); // x is a reference to a const temporary, object,
- func2(y); // x is a reference to a const object, while y is not const, and
- func2(z); // x is a reference to a const object, just like z.
- In all cases, the argument `x` in `func2` is a const-qualified LValue.
- We can use function overloading to identify non-const LValues:
- template< typename T > void func3(T const & x); // #1
- template< typename T > void func3(T & x); // #2
- // [...] function scope:
- func3(1); // x is a reference to a const, temporary object in #1,
- func3(y); // x is a reference to a non-const object in #2, and
- func3(z); // x is a reference to a const object in #1.
- Note that all arguments `x` in the overloaded function `func3` are LValues.
- In fact, there is no way to transport RValues into a function as-is in C++98.
- Also note that we can't distinguish between what used to be a const qualified
- LValue and an RValue.
- That's as close as we can get to a generic forwarding function `g` as
- described above by the means of C++ 98. See __the_forwarding_problem__ for a
- very detailed discussion including solutions that require language changes.
- Now, for actually implementing it, we need 2^N overloads for N parameters
- (each with and without const qualifier) for each number of arguments
- (that is 2^(Nmax+1) - 2^Nmin). Right, that means the compile-time complexity
- is O(2^N), however the factor is low so it works quite well for a reasonable
- number (< 10) of arguments.
- [endsect]
- [section:reference Reference]
- [section forward_adapter]
- [heading Description]
- Function object adapter template whose instances are callable with LValue and
- RValue arguments. RValue arguments are forwarded as reference-to-const typed
- LValues.
- An arity can be given as second, numeric non-type template argument to restrict
- forwarding to a specific arity.
- If a third, numeric non-type template argument is present, the second and third
- template argument are treated as minimum and maximum arity, respectively.
- Specifying an arity can be helpful to improve the readability of diagnostic
- messages and compile time performance.
- __boost_result_of__ can be used to determine the result types of specific call
- expressions.
- [heading Header]
- #include <boost/functional/forward_adapter.hpp>
- [heading Synopsis]
- namespace boost
- {
- template< class Function,
- int Arity_Or_MinArity = __unspecified__, int MaxArity = __unspecified__ >
- class forward_adapter;
- }
- [variablelist Notation
- [[`F`] [a possibly const qualified function object type or reference type thereof]]
- [[`f`] [an object convertible to `F`]]
- [[`FA`] [the type `forward_adapter<F>`]]
- [[`fa`] [an instance object of `FA`, initialized with `f`]]
- [[`a0`...`aN`] [arguments to `fa`]]
- ]
- The result type of a target function invocation must be
- __boost__result_of__<F*(TA0 [const]&...TAN [const]&])>::type
- where `TA0`...`TAN` denote the argument types of `a0`...`aN`.
- [heading Expression Semantics]
- [table
- [[Expression] [Semantics]]
- [[`FA(f)`] [creates an adapter, initializes the target function with `f`.]]
- [[`FA()`] [creates an adapter, attempts to use `F`'s default constructor.]]
- [[`fa(a0`...`aN)`] [calls `f` with with arguments `a0`...`aN`.]]
- ]
- [heading Limits]
- The macro BOOST_FUNCTIONAL_FORWARD_ADAPTER_MAX_ARITY can be defined to set the
- maximum call arity. It defaults to 6.
- [heading Complexity]
- Preprocessing time: O(2^N), where N is the arity limit.
- Compile time: O(2^N), where N depends on the arity range.
- Run time: O(0) if the compiler inlines, O(1) otherwise.
- [endsect]
- [section lightweight_forward_adapter]
- [heading Description]
- Function object adapter template whose instances are callable with LValue and
- RValue arguments. All arguments are forwarded as reference-to-const typed
- LValues, except for reference wrappers which are unwrapped and may yield
- non-const LValues.
- An arity can be given as second, numeric non-type template argument to restrict
- forwarding to a specific arity.
- If a third, numeric non-type template argument is present, the second and third
- template argument are treated as minimum and maximum arity, respectively.
- Specifying an arity can be helpful to improve the readability of diagnostic
- messages and compile time performance.
- __boost_result_of__ can be used to determine the result types of specific call
- expressions.
- [heading Header]
- #include <boost/functional/lightweight_forward_adapter.hpp>
- [heading Synopsis]
- namespace boost
- {
- template< class Function,
- int Arity_Or_MinArity = __unspecified__, int MaxArity = __unspecified__ >
- struct lightweight_forward_adapter;
- }
- [variablelist Notation
- [[`F`] [a possibly const qualified function object type or reference type thereof]]
- [[`f`] [an object convertible to `F`]]
- [[`FA`] [the type `lightweight_forward_adapter<F>`]]
- [[`fa`] [an instance of `FA`, initialized with `f`]]
- [[`a0`...`aN`] [arguments to `fa`]]
- ]
- The result type of a target function invocation must be
- __boost__result_of__<F*(TA0 [const]&...TAN [const]&])>::type
- where `TA0`...`TAN` denote the argument types of `a0`...`aN`.
- [heading Expression Semantics]
- [table
- [[Expression] [Semantics]]
- [[`FA(f)`] [creates an adapter, initializes the target function with `f`.]]
- [[`FA()`] [creates an adapter, attempts to use `F`'s default constructor.]]
- [[`fa(a0`...`aN)`] [calls `f` with with const arguments `a0`...`aN`. If `aI` is a
- reference wrapper it is unwrapped.]]
- ]
- [heading Limits]
- The macro BOOST_FUNCTIONAL_LIGHTWEIGHT_FORWARD_ADAPTER_MAX_ARITY can be defined
- to set the maximum call arity. It defaults to 10.
- [heading Complexity]
- Preprocessing time: O(N), where N is the arity limit.
- Compile time: O(N), where N is the effective arity of a call.
- Run time: O(0) if the compiler inlines, O(1) otherwise.
- [endsect]
- [endsect]
- [section Acknowledgements]
- As these utilities are factored out of the __boost_fusion__ functional module,
- I want to thank Dan Marsden and Joel de Guzman for letting me participate in the
- development of that great library in the first place.
- Further, I want to credit the authors of the references below, for their
- in-depth investigation of the problem and the solution implemented here.
- Last but not least I want to thank Vesa Karnoven and Paul Mensonides for the
- Boost Preprocessor library. Without it, I would have ended up with an external
- code generator for this one.
- [endsect]
- [section References]
- # [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm The Forwarding Problem],
- Peter Dimov, Howard E. Hinnant, David Abrahams, 2002
- # [@http://www.boost.org/libs/utility/utility.htm#result_of Boost.ResultOf],
- Douglas Gregor, 2004
- # [@http://www.boost.org/doc/html/ref.html Boost.Ref],
- Jaakko Jarvi, Peter Dimov, Douglas Gregor, David Abrahams, 1999-2002
- [endsect]
|