function_types.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

[section:non_volatile non_volatile]

  typedef __unspecified__ non_volatile;

[*Header]

  #include <boost/function_types/property_tags.hpp>

States that a function type is not volatile qualified.

[endsect]

[section:non_cv non_cv]

  typedef __unspecified__ non_cv;

[*Header]

  #include <boost/function_types/property_tags.hpp>

States that a function type is neither const nor volatile qualified.
Equivalent to `__tag<__non_const,__non_volatile>`, but involves
fewer template instantiations when evaluated.

[endsect]

[section:const_non_volatile const_non_volatile]

  typedef __unspecified__ const_non_volatile;

[*Header]

  #include <boost/function_types/property_tags.hpp>

States that a function type is const but not volatile qualified.
Equivalent to `__tag<__const_qualified,__non_volatile>`, but involves
fewer template instantiations when evaluated.

[endsect]

[section:volatile_non_const volatile_non_const]

  typedef __unspecified__ volatile_non_const;

[*Header]

  #include <boost/function_types/property_tags.hpp>

States that a function type is volatile but not const qualified.
Equivalent to `__tag<__volatile_qualified,__non_const>`, but involves
fewer template instantiations when evaluated.

[endsect]

[section:cv_qualfied cv_qualfied]

  typedef __unspecified__ cv_qualified;

[*Header]

  #include <boost/function_types/property_tags.hpp>

States that a function type is both const and volatile qualified.
Equivalent to `__tag<__const_qualified,__volatile_qualified>`, but involves
fewer template instantiations when evaluated.

[endsect]

[section:null_tag null_tag]

  typedef __unspecified__ null_tag;

[*Header]

  #include <boost/function_types/property_tags.hpp>

States nothing.

[endsect]

[section:tag tag]

  template<class Tag1, class Tag2, 
      class Tag3 = null_tag, class Tag4 = null_tag>
  struct tag;

[*Header]

  #include <boost/function_types/property_tags.hpp>

[variablelist
  [[[^Tag['N]]][Property tag]]
  [[[^tag<Tag1,Tag2...>]][Compound property tag]]
]

Combination of up to four property tags.  If the arguments describe different 
values for the same property the value of the rightmost argument is used.

[endsect]

[endsect] [/ Tag Types]

[/ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ]

[section:macros Macros]

[section:BOOST_FT_MAX_ARITY BOOST_FT_MAX_ARITY]

Expands to a numeric value that describes the maximum function arity 
supported by the library.

Defaults to 20 if not explicitly defined by the user before inclusion
of the first library header.

[endsect]



[*The following macros do not need to be defined, unless to configure
the library to work with a compiler and/or calling convention not covered by 
the auto-detection mechanism in [^boost/function_types/config/compiler.hpp].]


[section:BOOST_FT_CC_NAMES BOOST_FT_CC_NAMES]

Expands to a [@../../../preprocessor/doc/data/sequences.html sequence] of 
ternary [@../../../preprocessor/doc/data/tuples.html tuples] (these data 
types are defined in the [@../../../preprocessor/doc/index.html
documentation of the Boost Preprocessor library]). 
Each sequence element describes one calling convention specifier.
The first element in each tuple is the macro suffix for 
[link boost_functiontypes.reference.macros.BOOST_FT_CC [^BOOST_FT\_CC\_*]], 
the second element is the name of the tag that describes the calling 
convention and the third is the name of the specifier. 
The specifier is allowed to be an empty string, so the third tuple element
is either [@../../../preprocessor/doc/ref/empty.html [^BOOST_PP_EMPTY]] or 
[@../../../preprocessor/doc/ref/identity.html [^BOOST_PP_IDENTITY]][^(['name])].

Define this macro to extend the set of possible names for custom calling
conventions. The macro expands to nothing by default.

The following names are predefined by the library and must not occur in the
definition of [^BOOST_FT_CC_NAMES]:

  #define BOOST_FT_BUILTIN_CC_NAMES \
    (( IMPLICIT           , implicit_cc , BOOST_PP_EMPTY                ))\
    (( CDECL              , cdecl_cc    , BOOST_PP_IDENTITY(__cdecl   ) ))\
    (( STDCALL            , stdcall_cc  , BOOST_PP_IDENTITY(__stdcall ) ))\
    (( PASCAL             , pascal_cc   , BOOST_PP_IDENTITY(pascal    ) ))\
    (( FASTCALL           , fastcall_cc , BOOST_PP_IDENTITY(__fastcall) ))\
    (( CLRCALL            , clrcall_cc  , BOOST_PP_IDENTITY(__clrcall ) ))\
    (( THISCALL           , thiscall_cc , BOOST_PP_IDENTITY(__thiscall) ))\
    (( IMPLICIT_THISCALL  , thiscall_cc , BOOST_PP_EMPTY                )) 
  // Don't get confused by the last line, here (thiscall can't be specified
  // explicitly prior to MSVC 8).

[endsect]

[section:BOOST_FT_CC BOOST_FT\_CC\_*]

Enables a specific calling convention. * dentoes the macro suffix, as 
defined by
[link boost_functiontypes.reference.macros.BOOST_FT_CC_NAMES [^BOOST_FT_CC_NAMES]] 
or 
[link boost_functiontypes.reference.macros.BOOST_FT_CC_NAMES [^BOOST_FT_BUILTIN_CC_NAMES]].

The macro expands to a list of restrictions, separated by the [^|] character.
Possible items are:

* callable_builtin
* member
* non_member
* variadic
* non_variadic

If no such macro is defined for a particular calling convention, it is disabled.
Example:

  #define BOOST_FT_CC_STDCALL non_variadic|callable_builtin
  // enables stdcall calling convention for all non-variadic, 
  // callable, builtin types

[endsect]

[section:BOOST_FT_COMMON_X86_CCs BOOST_FT_COMMON_X86_CCs]

Defining this macro causes the following macros to be defined, if not defined 
already:

  #define BOOST_FT_CC_CDECL BOOST_FT_COMMON_X86_CCs
  #define BOOST_FT_CC_STDCALL non_variadic|BOOST_FT_COMMON_X86_CCs
  #define BOOST_FT_CC_FASTCALL non_variadic|BOOST_FT_COMMON_X86_CCs

[endsect]

[section:BOOST_FT_SYNTAX BOOST_FT_SYNTAX]

This macro allows to change the syntax of callable builtin types.
It is useful to handle the compiler specific placement of the calling 
convention specifier.

The default definition is as follows:

  #define BOOST_FT_SYNTAX(result,lparen,cc_spec,type_mod,name,rparen) \
            result() lparen() cc_spec() type_mod() name() rparen()

[endsect]

[section:BOOST_FT_NULLARY_PARAM BOOST_FT_NULLARY_PARAM]

Set to [^void] for compilers that insist on a [^void] parameter for
nullary function types, empty by default.

[endsect]

[section:BOOST_FT_NO_CV_FUNC_SUPPORT BOOST_FT_NO_CV_FUNC_SUPPORT]

Disables support for cv-qualified function types.
Cv-qualified function types are illegal by the current standard
version, but there is a pending defect report on that issue.
It defaults to [^1] until the standard changes, setting this macro
to [^0] may not work.

[endsect]



[*The following macros are useful for testing when changing the source code of
the library.]



[section:BOOST_FT_PREPROCESSING_MODE BOOST_FT_PREPROCESSING_MODE]

Makes the compiler preprocess as much as possible of the library code 
(rather than loading already-preprocessed header files) if defined.

[endsect]

[section:BOOST_FT_CC_PREPROCESSING BOOST_FT_CC_PREPROCESSING]

Makes the compiler preprocess the loop over possible names for custom
calling conventions (rather than loading an already-preprocessed header
file) if defined.

This macro is defined automatically if 
[link boost_functiontypes.reference.macros.BOOST_FT_CC_NAMES [^BOOST_FT_CC_NAMES]] 
has been defined.

[endsect]

[endsect]

[endsect]

[/ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ]

[section:rationale Rationale]

[heading Error handling rationale]

The library does not define the required members of class templates in
case of an error. This technique causes the compiler to stop displaying
diagnostics in client code, at the point where the error actually is, 
instead of tracing template instantiations into the implementation of
the library. 

The library's components have limited error conditions, so problematic
input can be spotted easily.


[heading Why MPL Sequences?]

MPL provides algorithms on Sequences, so transformations (such as turning
by-value parameter types into const references for optimized forwarding
or computing a signature to specialize 
[@../../../function/index.html [^boost::function]] after applying 
[@../../../bind/index.html [^boost::bind]]) can be expressed more 
easily. The MPL Sequence concept is compatible with several other Boost 
libraries (most importantly [@../../../fusion/index.html Fusion]), 
so another reason is interoperability.


[heading Pointer to member object types]

Despite their syntax, pointer to member object types can be seen as
dereferencing functionals. 


[heading The ClassTransform template parameter]

[^This]-pointer, [^this]-reference or just the object (or maybe even a
smart pointer to the object) plus adjustments of cv-qualification - all
these cases have their place, somewhere and there is no single best answer.

Special treatment of the class type within the sequence can significantly
complicate client code. A custom [^ClassTransform] argument allows the
client to adjust the class type before the sequence is formed and then
treat all parameters uniformly.


[heading Why tag types?]

Let's consider the alternatives.

The first one is just using more templates so every property has to be 
asked for explicitly. This approach results in more complicated client 
code if more than one propery has to be checked and in a exponentially 
larger library interface.

The second alternative is having the client pass in bit patterns via 
non-type template parameters. The logic has to be performed by the 
client and there are much more error conditions. Further, class templates
with non-type template parameters do not work within MPL lambda 
expressions and can cause problems with older compilers.

[heading Is it safe to have the synthesis templates take a callable 
builtin type or an MPL sequence as the first template argument?]

Yes, but it isn't immediately obvious as the set of possible MPL sequences
isn't inherently disjoint from the set of callable builtin types.

However, any attempt to make a builtin type work as an MPL sequence is
a bad idea, because builtin types are accessible before the headers that
make the type a sequence have been included, which can easily violate the
ODR. 

[heading Why does the hidden [^this] parameter count for the 
function arity of member functions?]

It was found preferable that the following condition holds:

  mpl::size< __parameter_types<T> >::value == __function_arity<T>::value

[heading Why ignore top-level cv-qualifiers on pointers?]

A cv-qualified pointer is still a pointer. It usually doesn't matter and
even if it does, it's a job for 
[@../../../type_traits/index.html Boost.TypeTraits]. 


[endsect]

[section:acknowledgements Acknowledgements]

Thanks go to the following people for supporting the development of this 
library in one or the other way:

* David Abrahams
* Tom Brinkman
* Aleksey Gurtovoy
* Jody Hagins
* Hartmut Kaiser 
* Andy Little
* John Maddock 
* Paul Mensonides
* Alexander Nasonov
* Richard Smith
* Rob Stewart
* Jonathan Turkanis
* Pavel Vozenilek
* Steven Watanabe
* K. Noel Belcourt

[endsect]