diff --git a/doc/compiler_specifics.html b/doc/compiler_specifics.html index ce80c4d..341ccb0 100644 --- a/doc/compiler_specifics.html +++ b/doc/compiler_specifics.html @@ -28,911 +28,63 @@ Performance

-Boost.MultiIndex has been tried in different compilers, with -various degrees of success. We list the limitations encountered, -along with suitable workarounds when available. +Boost.MultiIndex utilizes some C++11 capabilities but is also equipped +to work reasonably well in decent C++03-compliant environments. +We list some of the possible limitations along with suitable workarounds when available.

Contents

+
  • Legacy compilers
  • -

    Borland C++ Builder 6.4 and later

    +

    Move semantics

    -Currently, Boost.MultiIndex cannot be used with any of BCB 6.4 up to BCB 2006 -and CodeGear C++Builder 2010. -The number of problems encountered during the tests makes it unlikely that -future versions of the library can be made to work under these compilers. +Boost.MultiIndex uses Boost.Move +to support compilers without rvalue references. In such scenarios, taking +advantage of multi_index_container<Value> capabilities for +increased efficiency in insertion and handling of moveable-only elements will +require that Value be suitably instrumented.

    -

    Comeau C/C++ 4.3.10.1 for Windows (VC++ 9.0 backend)

    +

    Emplace functions

    -Note: Last tested in Boost 1.38. The information might be no longer accurate. +In compilers without variadic template support, Boost.MultiIndex emplace +functions emulate this missing functionality by accepting up to +BOOST_MULTI_INDEX_LIMIT_VARTEMPL_ARGS +construction arguments that are internally forwarded with +Boost.Move: +only constant lvalue references and rvalues are permitted as construction arguments +in such case.

    -No problems have been detected with this compiler. The library fails to compile, -however, when Microsoft Visual C++ 6.0 is used as the backend. Last time they were -tested (Boost.1.34.1), VC++ 7.0/7.1 backends worked correctly. The beta 2 version of -the Comeau compiler 4.3.10.1 has been used. +BOOST_MULTI_INDEX_LIMIT_VARTEMPL_ARGS, which by default is 5, can +be globally defined by the user to a different value.

    -

    Compaq C++ 6.5-042 and later for Tru64 UNIX

    +

    Initializer lists

    -Note: Last tested in Boost 1.38. The information might be no longer accurate. +No transparent emulation of this functionality can be provided in the absence of +std::initializer_list: consider +Boost.Assign as a +possible replacement.

    -

    -No problems have been detected with this compiler. Last tested for version 7.1-006. -

    - -

    GNU GCC 3.2 and later

    - -

    -No problems have been detected with several versions of this compiler -starting from 3.2. The following versions have been explicitly tested: -

    -Boost.MultiIndex does not work with versions 3.1 and prior of GCC. -

    - -

    GNU GCC for Tru64 UNIX

    - -

    -On this platform, GCC is not able to handle debug symbol names whose length -exceeds 32,768 bytes, resulting in the error mips-tfile, ... string -too big. You may encounter this issue with heavily templatized -code like Boost.MultiIndex, which typically produces long symbol names. The problem -can be overcome by omitting the compiler option -g (generate debugging -information.) Alternatively, consult the section on -reduction of symbol name lengths for various -applicable workarounds. -

    - -

    Darwin GCC 4.0

    - -

    -Build 4061 of GCC 4.0, shipped with Darwin 8.2 and prior (Mac OS X 10.4.2 and -prior), corresponds to a prerelease version of GNU GCC 4.0.0 which introduces -a regression bug -related to binding of references to temporary objects. This bug precludes the -usage of Boost.MultiIndex -invariant-checking mode; other -than this, Boost.MultiIndex works correctly. -The bug is corrected in GCC 4.0 Apple build 5026, which is in sync with the official -release of GNU GCC 4.0.0, so the invariant-checking mode is available from this -upgrade. -

    - -

    HP aC++ A.06.12 and later for HP-UX IA64

    - -

    -Note: Last tested in Boost 1.38. The information might be no longer accurate. -

    - -

    -No problems have been detected with this compiler. -Last tested for version A.06.17. -

    - -

    HP aC++ A.03.80 for HP-UX PA-RISC

    - -

    -Note: Last tested in Boost 1.38. The information might be no longer accurate. -

    - -

    -No problems have been detected with this compiler. -Last tested for version A.03.85. -

    - -

    IBM VisualAge C++ V6.0 for AIX

    - -

    -Note: Last tested in Boost 1.33.1. The information might be no longer accurate. -

    - -

    - -

    -member not supported, -refer to the section on -use of member_offset for workarounds. -member_offset causes the compiler to emit warnings about the -use of offsetof with non-POD types: these warnings can be suppressed -by setting the compiler option -qsuppress=1540-1281, or, alternatively, -by inserting the following preprocessor directive: -

    - -
    -#pragma info(nolan)
    -
    - -

    -This latter pragma, however, may also eliminate other warnings not related -to the use of offsetof. -

    - -

    - -

    -Serialization capabilities are not available as Boost.Serialization is not -supported on this platform. -

    - -

    IBM XL C/C++ V9.0 for AIX and later

    - -

    -member not supported, -refer to the section on -use of member_offset for workarounds. -member_offset causes the compiler to emit warnings about the -use of offsetof with non-POD types: these warnings can be suppressed -by setting the compiler option -qsuppress=1540-1281, or, alternatively, -by inserting the following preprocessor directive: -

    - -
    -#pragma info(nolan)
    -
    - -

    -This latter pragma, however, may also eliminate other warnings not related -to the use of offsetof. -Other than this, Boost.MultiIndex works without problems. -Last tested for version V10.1. -

    - -

    Intel C++ Compiler for Linux 8.1 and later

    - -

    -No problems have been detected with this compiler. -Last tested for compiler versions 10.0 to 11.1. -

    - -

    Intel C++ Compiler for Mac OS 9.1 and later

    - -

    -No problems have been detected with this compiler. -Tested from version 10.1 to 11.0. -

    - -

    Intel C++ Compiler for Windows 32-bit 8.0 and later

    - -

    -When used on top of MSVC++ 7.0 or prior, argument dependent lookup is -disabled by default. This will cause problems with many Boost libraries, -and in particular with the serialization part of Boost.MultiIndex. -Argument dependent lookup is enabled by adding -/Qoption,c,--arg_dep_lookup to the project options. -Other than this, Boost.MultiIndex works without problems. -Last tested for compiler version 11.1. -

    - -

    Intel C++ Compiler for Windows 64-bit 10.0 and later

    - -

    -No problems have been detected with this compiler. -Last tested for compiler version 11.1. -

    - -

    Metrowerks CodeWarrior 8.3

    - -

    -Note: Last tested in Boost 1.36. The information might be no longer accurate. -

    - -

    -Predefined key extractors instantiated on a given type do not accept -objects of derived types. For instance: -

    - -
    -struct base{};
    -struct derived:public base{};
    -...
    -
    -identity<base> key_extractor;
    -derived        x;
    -
    -// not accepted by this compiler: an explicit cast to base is required
    -key_extractor(x);
    -
    - -

    -Other than this, Boost.MultiIndex works without problems under Mac OS and Windows (last -tested under Windows only). -

    - -

    Metrowerks CodeWarrior 9 and later

    - -

    -Note: Last tested in Boost 1.34.1. The information might be no longer accurate. -

    - -

    -Boost.MultiIndex works correctly with versions of this compiler from 9.0 to -9.5, both under Mac OS and Windows. -

    - -

    Microsoft Visual C++ 6.0 Service Pack 5

    - -

    -Note: Last tested in Boost 1.36. The information might be no longer accurate. -

    - -

    - -

    -Beginning with Boost.1.36, Boost.Serialization is no longer supported in this -compiler, thus the serialization capabilities cannot be used. -

    - -

    - -

    -member not supported, -refer to the section on -use of member_offset for workarounds. -

    - -

    -const_mem_fun and -mem_fun -not supported, refer to the section on -use of const_mem_fun_explicit and -mem_fun_explicit for workarounds. -

    - -

    - -

    -No support for index retrieval -and projection -nested types and member functions: -

    -You can use instead their global equivalents. Also, this compiler does not -implement argument dependent lookup, so you might need to explicitly qualify -these global names with ::boost::multi_index. -

    - -

    - -

    -boost::multi_index::multi_index_container is imported to -namespace boost by means of a using declaration. -MSVC++ 6.0, however, does not properly handle this import. So, instead of -writing: -

    - -
    -boost::multi_index_container<...>
    -
    - -

    -use the following: -

    - -
    -boost::multi_index::multi_index_container<...>
    -
    - -

    -or else resort to a directive using namespace boost::multi_index. -

    - -

    - -

    -The lack of partial template specialization support in MSVC++ 6.0 -results in some inconveniences when using composite_key that -can be remedied as explained in -"composite_key -in compilers without partial template specialization". -

    - -

    - -

    -Due to problems with function template ordering support, -composite_key_compare -and related classes do not accept the notational variations of -operator() where one of the operands is treated as if -included into a tuple of length 1. As a result, the user cannot ever -omit tuple enclosing when specifying the arguments of lookup operations -involving composite keys. -

    - -

    - -

    -Predefined key extractors instantiated on a given type do not accept -objects of derived types. For instance: -

    - -
    -struct base{};
    -struct derived:public base{};
    -...
    -
    -identity<base> key_extractor;
    -derived        x;
    -
    -// not accepted by this compiler: an explicit cast to base is required
    -key_extractor(x);
    -
    - -

    - -

    -MSVC++ 6.0 presents serious limitations for the maximum length of -symbol names generated by the compiler, which might result in the -linker error -LNK1179: -invalid or corrupt file: duplicate comdat -comdat. To overcome this problem, consult the section on -reduction of symbol name lengths for various -applicable workarounds. -

    - -

    - -

    -Under some circumstances, the compiler emits the error - -C2587: '_U' : illegal use of local variable as -default parameter, inside the MSVC internal header -<xlocnum>. -This problem is a recurrent bug of the compiler, and has been reported in -other unrelated libraries, like the -Boost Graph Library, -Boost.MultiArray, -Boost.Regex, -CGAL and -MySQL++. -The error is triggered, though not in a systematic manner, by the use -of multi_index_container iterator constructor. Two workarounds exist: -the first consists of avoiding this constructor and replacing -code like: -

    - -
    -multi_index_container<...> s(c.begin(),c.end());
    -
    - -

    -with equivalent operations: -

    - -
    -multi_index_container<...> s;
    -s.insert(c.begin(),c.end());
    -
    - -

    -The second workaround has not been confirmed by the author, but it is given -on the Internet in connection with this error appearing in other libraries. -Replace line 84 of <xlocnum> - -

    - #define _VIRTUAL	virtual
    -
    - -

    -with the following: -

    - -
    - #define _VIRTUAL
    -
    - -

    -Warning: it is not known whether this -replacement can result in unexpected side effects in code implicitly -using <xlocnum>. -

    - -

    - -

    -In general, the extensive use of templates by Boost.MultiIndex puts this compiler -under severe stress, so that several internal limitations may be reached. -The following measures can help alleviate these problems: -

    -

    - -

    -Microsoft Visual C++ 6.0 Service Pack 5 -+ STLport 4.5.3 and later -

    - -

    -Note: Last tested in Boost 1.36. The information might be no longer accurate. -

    - -

    -Boost.MultiIndex works for this configuration. The same limitations apply as -in MSVC++ 6.0 with its original Dinkumware standard library. STLport 4.6.2 and -5.0.1 has also been confirmed to work correctly. -

    - -

    Microsoft Visual C++ 7.0

    - -

    -Note: Last tested in Boost 1.35. The information might be no longer accurate. -

    - -

    - -

    -Beginning with Boost.1.36, Boost.Serialization is no longer supported in this -compiler, thus the serialization capabilities cannot be used. -

    - -

    - -

    -member not supported, -refer to the section on -use of member_offset for workarounds. -

    - -

    - -

    -No support for index retrieval -and projection -nested types and member functions: -

    -You can use instead their global equivalents. Also, this compiler does not -implement argument dependent lookup, so you might need to explicitly qualify -these global names with ::boost::multi_index. -

    - -

    - -

    -boost::multi_index::multi_index_container is imported to -namespace boost by means of a using declaration. -MSVC++ 7.0, however, does not properly handle this import. So, instead of -writing: -

    - -
    -boost::multi_index_container<...>
    -
    - -

    -use the following: -

    - -
    -boost::multi_index::multi_index_container<...>
    -
    - -

    -or else resort to a directive using namespace boost::multi_index. -

    - -

    - -

    -The lack of partial template specialization support in MSVC++ 7.0 -results in some inconveniences when using composite_key that -can be remedied as explained in -"composite_key -in compilers without partial template specialization". -

    - -

    - -

    -Due to problems with function template ordering support, -composite_key_compare -and related classes do not accept the notational variations of -operator() where one of the operands is treated as if -included into a tuple of length 1. As a result, the user cannot ever -omit tuple enclosing when specifying the arguments of lookup operations -involving composite keys. -

    - -

    - -

    -Predefined key extractors instantiated on a given type do not accept -objects of derived types. For instance: -

    - -
    -struct base{};
    -struct derived:public base{};
    -...
    -
    -identity<base> key_extractor;
    -derived        x;
    -
    -// not accepted by this compiler: an explicit cast to base is required
    -key_extractor(x);
    -
    - -

    Microsoft Visual C++ 7.0 + STLport 5.0.1

    - -

    -Note: Last tested in Boost 1.35. The information might be no longer accurate. -

    - -

    -Boost.MultiIndex works for this configuration. The same issues apply as in -MSVC++ 7.0 with its original Dinkumware standard library. -

    - -

    Microsoft Visual C++ 7.1

    - -

    -Problems have been reported when compiling the library with the /Gm -option (Enable Minimal Rebuild.) Seemingly, this is due to an -internal defect of the compiler (see for instance - -this mention of a similar issue in the Boost Users mailing list.) -If /Gm is turned off, Boost.MultiIndex compiles and runs -without further problems. -

    - -

    Microsoft Visual C++ 8.0 and later

    - -

    -No problems have been detected with this compiler, both in 32-bit and 64-bit modes. -Last tested for compiler versions 8.0 to 10.0. -

    - -

    Sun Studio 10 and later for Solaris

    - -

    -No problems have been detected with this platform. Last tested for compiler version -Sun C++ 5.10 (Sun Studio 12 Update 1). -The option -library=stlport4 was used to replace the default -standard library with STLport. -

    - -

    Portability techniques

    - -

    Use of member_offset

    - -

    -The member key extractor poses some problems in compilers -that do not properly support pointers to members as non-type -template arguments, as indicated by the -Boost Configuration Library -defect macro BOOST_NO_POINTER_TO_MEMBER_TEMPLATE_PARAMETERS. -The following compilers have been confirmed not -to work correctly with member: -

    -This program can help determine if your compiler -properly supports pointers to members as non-type template parameters: -

    - -
    -#include <iostream>
    -
    -struct pair
    -{
    -  int x,y;
    -
    -  pair(int x_,int y_):x(x_),y(y_){}
    -};
    -
    -template<int pair::* PtrToPairMember>
    -struct foo
    -{
    -  int bar(pair& p){return p.*PtrToPairMember;}
    -};
    -
    -int main()
    -{
    -  pair p(0,1);
    -  foo<&pair::x> fx;
    -  foo<&pair::y> fy;
    -
    -  if(fx.bar(p)!=0||fy.bar(p)!=1)std::cout<<"KO"<<std::endl;
    -  else std::cout<<"OK"<<std::endl;
    -
    -  return 0;
    -}
    -
    -
    - -

    -If you find a compiler that does not pass the test, and for which -BOOST_NO_POINTER_TO_MEMBER_TEMPLATE_PARAMETERS is not defined, -please report to the Boost developers mailing list. -

    -

    To overcome this defect, a replacement utility -member_offset -has been provided that does the work of member at the -expense of less convenient notation and the possibility of -non-conformance with the standard. Please consult -the reference for further information on member_offset. -As an example of use, given the class -

    - -
    -class A
    -{
    -  int x;
    -}
    -
    - -

    -the instantiation member<A,int,&A::x> can be simulated then -as member_offset<A,int,offsetof(A,x)>. -

    - -

    -For those writing portable code, Boost.MultiIndex provides the ternary macro -BOOST_MULTI_INDEX_MEMBER. -Continuing with the example above, the -expression -

    - -
    -BOOST_MULTI_INDEX_MEMBER(A,int,x)
    -
    - -

    -expands by default to -

    - -
    -member<A,int,&A::x>
    -
    - -

    -or alternatively to -

    - -
    -member_offset<A,int,offsetof(A,x)>
    -
    - -

    -if BOOST_NO_POINTER_TO_MEMBER_TEMPLATE_PARAMETERS is defined. -

    - -

    Use of const_mem_fun_explicit and -mem_fun_explicit

    - -

    -MSVC++ 6.0 has problems with const member functions as non-type -template parameters, and thus does not accept the const_mem_fun -key extractor. A simple workaround, fortunately, has been found, consisting -in specifying the type of these pointers as an additional template -parameter. The alternative -const_mem_fun_explicit -extractor adopts this solution; for instance, given the type -

    - -
    -struct A
    -{
    -  int f()const;
    -};
    -
    - -

    -the extractor const_mem_fun<A,int,&A::f> can be replaced by -const_mem_fun_explicit<A,int,int (A::*)()const,&A::f>. A similar -mem_fun_explicit class template is provided for non-constant -member functions. -

    - -

    -If you are writing cross-platform code, the selection of either key extractor -is transparently handled by the macro -BOOST_MULTI_INDEX_CONST_MEM_FUN, -so that -

    - -
    -BOOST_MULTI_INDEX_CONST_MEM_FUN(A,int,f)
    -
    - -

    -expands by default to -

    - -
    -const_mem_fun<A,int,&A::f>
    -
    - -

    -but resolves to -

    - -
    -const_mem_fun_explicit<A,int,int (A::*)()const,&A::f>
    -
    - -

    -in MSVC++ 6.0. Non-const member functions are covered by -mem_fun_explicit -and the macro -BOOST_MULTI_INDEX_MEM_FUN. -

    - -

    composite_key in compilers -without partial template specialization

    - -

    -When using composite_keys, lookup is performed by passing -tuples of values: this ability is achieved by suitably specializing -the class templates std::equal_to, std::less, -std::greater and boost::hash for - -composite_key_result instantiations so that they -provide the appropriate overloads accepting tuples --and in the case -of std::less and std::greater, also partial -tuples where only the first components are specified. -

    - -

    -In those compilers that do not support partial template specialization, -these specializations cannot be provided, and so -tuple-based lookup is not available by default. In this case, -multi_index_container instantiations using composite keys -will work as expected, both for ordered and hashed indices, -except that lookup operations will not accept tuples as an argument. -For ordered indices, the most obvious workaround -to this deficiency involves explicitly specifying the comparison -predicate with -composite_key_compare; -in the case of hashed indices we can use the analogous -composite_key_equal_to -and -composite_key_hash. -This substitution is tedious as the elementary components for all the constituent key extractors must -be explicitly typed. For this reason, Boost.MultiIndex provides the following replacement -class templates -

    -that act as the missing specializations of std::equal_to, std::less, -std::greater and boost::hash for composite_key_results. -They can be used as follows: -

    - -
    -typedef composite_key<
    -  phonebook_entry,
    -  member<phonebook_entry,std::string,&phonebook_entry::family_name>,
    -  member<phonebook_entry,std::string,&phonebook_entry::given_name>
    -> ckey_t;
    -
    -typedef multi_index_container<
    -  phonebook_entry,
    -  indexed_by<
    -    ordered_non_unique< 
    -      ckey_t,
    -      // composite_key_result_less plays the role of
    -      // std::less<ckey_t::result_type>
    -      composite_key_result_less<ckey_t::result_type>
    -    >,
    -    ordered_unique<
    -      member<phonebook_entry,std::string,&phonebook_entry::phone_number>
    -    >
    -  >
    -> phonebook;
    -
    - -

    Reduction of symbol name lengths

    +

    Reduction of symbol name lengths

    The types generated on the instantiations of multi_index_containers @@ -942,7 +94,7 @@ names: these techniques have also the beneficial side effect that resulting erro messages are more readable.

    -

    Limitation of maximum number of arguments

    +

    Limitation of maximum number of arguments

    The class templates indexed_by, @@ -985,7 +137,7 @@ of symbol names.

    -

    Type hiding

    +

    Type hiding

    Consider a typical instantiation of multi_index_container: @@ -1098,6 +250,114 @@ Type hiding techniques can also be applied to composite_key intanti which often contribute a great deal to symbol name lengths.

    +

    Legacy compilers

    + +

    +Boost.MultiIndex support for legacy compilers is not actively kept, so if you happen +to work with an old environment you might need to use a former version of the library. +A table is provided of some legacy compilers along with the latest version of +Boost.MultiIndex known to work for them (frequently with limitations as explained +in the corresponding compiler specifics section.) If you successfully try one of those +with newer versions of Boost.MultiIndex than stated here, please report back so that +the information can be udated. +

    + +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Support for legacy compilers.
    CompilerLatest known
    compatible version
    Date
    Borland C++ Builder 6.4 through 2006, CodeGear C++Builder 2010Never worked with Boost.MultiIndex
    Comeau C/C++ 4.3.10.1 for Windows (VC++ 9.0 backend)Boost 1.38February 2009
    Compaq C++ 6.5-042 through 7.1-006 for Tru64 UNIXBoost 1.38February 2009
    GCC 3.2 through 3.4Boost 1.41November 2009
    HP aC++ A.06.12 through A.06.17 for HP-UX IA64Boost 1.38February 2009
    HP aC++ A.03.80 through A.03.85 for HP-UX PA-RISCBoost 1.38February 2009
    IBM VisualAge C++ V6.0 for AIXBoost 1.33.1December 2006
    IBM XL C/C++ V9.0 through V10.1 for AIXBoost 1.41November 2009
    Intel C++ Compiler for Linux 8.1 through 11.1Boost 1.41November 2009
    Intel C++ Compiler for Mac OS 9.1 through 11.0Boost 1.41November 2009
    Intel C++ Compiler for Windows 32-bit 8.0 through 11.1Boost 1.41November 2009
    Intel C++ Compiler for Windows 64-bit 10.0 through 11.11Boost 1.41November 2009
    Metrowerks CodeWarrior 8.3Boost 1.36August 2008
    Metrowerks CodeWarrior 9 through 9.5Boost 1.34.1July 2007
    Microsoft Visual C++ 6.0 Service Pack 5Boost 1.36August 2008
    Microsoft Visual C++ 7.0Boost 1.35March 2008
    Sun Studio 10 through 12 Update 1for SolarisBoost 1.41November 2009
    +

    +