1 ///////////////////////////////////////////////////////////////////////////// 2 // 3 // (C) Copyright Ion Gaztanaga 2013-2013 4 // 5 // Distributed under the Boost Software License, Version 1.0. 6 // (See accompanying file LICENSE_1_0.txt or copy at 7 // http://www.boost.org/LICENSE_1_0.txt) 8 // 9 // See http://www.boost.org/libs/container for documentation. 10 // 11 ///////////////////////////////////////////////////////////////////////////// 12 13 #ifndef BOOST_CONTAINER_OPTIONS_HPP 14 #define BOOST_CONTAINER_OPTIONS_HPP 15 16 #ifndef BOOST_CONFIG_HPP 17 # include <boost/config.hpp> 18 #endif 19 20 #if defined(BOOST_HAS_PRAGMA_ONCE) 21 # pragma once 22 #endif 23 24 #include <boost/container/detail/config_begin.hpp> 25 #include <boost/container/container_fwd.hpp> 26 #include <boost/intrusive/pack_options.hpp> 27 #include <boost/static_assert.hpp> 28 29 namespace boost { 30 namespace container { 31 32 //////////////////////////////////////////////////////////////// 33 // 34 // 35 // OPTIONS FOR ASSOCIATIVE TREE-BASED CONTAINERS 36 // 37 // 38 //////////////////////////////////////////////////////////////// 39 40 //! Enumeration used to configure ordered associative containers 41 //! with a concrete tree implementation. 42 enum tree_type_enum 43 { 44 red_black_tree, 45 avl_tree, 46 scapegoat_tree, 47 splay_tree 48 }; 49 50 #if !defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 51 52 template<tree_type_enum TreeType, bool OptimizeSize> 53 struct tree_opt 54 { 55 static const boost::container::tree_type_enum tree_type = TreeType; 56 static const bool optimize_size = OptimizeSize; 57 }; 58 59 typedef tree_opt<red_black_tree, true> tree_assoc_defaults; 60 61 #endif //!defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 62 63 //!This option setter specifies the underlying tree type 64 //!(red-black, AVL, Scapegoat or Splay) for ordered associative containers 65 BOOST_INTRUSIVE_OPTION_CONSTANT(tree_type, tree_type_enum, TreeType, tree_type) 66 67 //!This option setter specifies if node size is optimized 68 //!storing rebalancing data masked into pointers for ordered associative containers 69 BOOST_INTRUSIVE_OPTION_CONSTANT(optimize_size, bool, Enabled, optimize_size) 70 71 //! Helper metafunction to combine options into a single type to be used 72 //! by \c boost::container::set, \c boost::container::multiset 73 //! \c boost::container::map and \c boost::container::multimap. 74 //! Supported options are: \c boost::container::optimize_size and \c boost::container::tree_type 75 #if defined(BOOST_CONTAINER_DOXYGEN_INVOKED) || defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 76 template<class ...Options> 77 #else 78 template<class O1 = void, class O2 = void, class O3 = void, class O4 = void> 79 #endif 80 struct tree_assoc_options 81 { 82 /// @cond 83 typedef typename ::boost::intrusive::pack_options 84 < tree_assoc_defaults, 85 #if !defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 86 O1, O2, O3, O4 87 #else 88 Options... 89 #endif 90 >::type packed_options; 91 typedef tree_opt<packed_options::tree_type, packed_options::optimize_size> implementation_defined; 92 /// @endcond 93 typedef implementation_defined type; 94 }; 95 96 #if !defined(BOOST_NO_CXX11_TEMPLATE_ALIASES) 97 98 //! Helper alias metafunction to combine options into a single type to be used 99 //! by tree-based associative containers 100 template<class ...Options> 101 using tree_assoc_options_t = typename boost::container::tree_assoc_options<Options...>::type; 102 103 #endif 104 105 106 //////////////////////////////////////////////////////////////// 107 // 108 // 109 // OPTIONS FOR ASSOCIATIVE HASH-BASED CONTAINERS 110 // 111 // 112 //////////////////////////////////////////////////////////////// 113 114 #if !defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 115 116 template<bool StoreHash> 117 struct hash_opt 118 { 119 static const bool store_hash = StoreHash; 120 }; 121 122 typedef hash_opt<false> hash_assoc_defaults; 123 124 #endif //!defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 125 126 //!This option setter specifies if node size is optimized 127 //!storing rebalancing data masked into pointers for ordered associative containers 128 BOOST_INTRUSIVE_OPTION_CONSTANT(store_hash, bool, Enabled, store_hash) 129 130 //! Helper metafunction to combine options into a single type to be used 131 //! by \c boost::container::hash_set, \c boost::container::hash_multiset 132 //! \c boost::container::hash_map and \c boost::container::hash_multimap. 133 //! Supported options are: \c boost::container::store_hash 134 #if defined(BOOST_CONTAINER_DOXYGEN_INVOKED) || defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 135 template<class ...Options> 136 #else 137 template<class O1 = void, class O2 = void, class O3 = void, class O4 = void> 138 #endif 139 struct hash_assoc_options 140 { 141 /// @cond 142 typedef typename ::boost::intrusive::pack_options 143 < hash_assoc_defaults, 144 #if !defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 145 O1, O2, O3, O4 146 #else 147 Options... 148 #endif 149 >::type packed_options; 150 typedef hash_opt<packed_options::store_hash> implementation_defined; 151 /// @endcond 152 typedef implementation_defined type; 153 }; 154 155 #if !defined(BOOST_NO_CXX11_TEMPLATE_ALIASES) 156 157 //! Helper alias metafunction to combine options into a single type to be used 158 //! by hash-based associative containers 159 template<class ...Options> 160 using hash_assoc_options_t = typename boost::container::hash_assoc_options<Options...>::type; 161 162 #endif 163 164 //////////////////////////////////////////////////////////////// 165 // 166 // 167 // OPTIONS FOR VECTOR-BASED CONTAINERS 168 // 169 // 170 //////////////////////////////////////////////////////////////// 171 172 #if !defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 173 174 template<class T, class Default> 175 struct default_if_void 176 { 177 typedef T type; 178 }; 179 180 template<class Default> 181 struct default_if_void<void, Default> 182 { 183 typedef Default type; 184 }; 185 186 #endif 187 188 #if !defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 189 190 template<class AllocTraits, class StoredSizeType> 191 struct get_stored_size_type_with_alloctraits 192 { 193 typedef StoredSizeType type; 194 }; 195 196 template<class AllocTraits> 197 struct get_stored_size_type_with_alloctraits<AllocTraits, void> 198 { 199 typedef typename AllocTraits::size_type type; 200 }; 201 202 template<class GrowthType, class StoredSizeType> 203 struct vector_opt 204 { 205 typedef GrowthType growth_factor_type; 206 typedef StoredSizeType stored_size_type; 207 208 template<class AllocTraits> 209 struct get_stored_size_type 210 : get_stored_size_type_with_alloctraits<AllocTraits, StoredSizeType> 211 {}; 212 }; 213 214 class default_next_capacity; 215 216 typedef vector_opt<void, void> vector_null_opt; 217 218 #else //!defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 219 220 //!This growth factor argument specifies that the container should increase it's 221 //!capacity a 50% when existing capacity is exhausted. 222 struct growth_factor_50{}; 223 224 //!This growth factor argument specifies that the container should increase it's 225 //!capacity a 60% when existing capacity is exhausted. 226 struct growth_factor_60{}; 227 228 //!This growth factor argument specifies that the container should increase it's 229 //!capacity a 100% (doubling its capacity) when existing capacity is exhausted. 230 struct growth_factor_100{}; 231 232 #endif //!defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 233 234 //!This option setter specifies the growth factor strategy of the underlying vector. 235 //! 236 //!\tparam GrowthFactor A function object that has the following signature:<br/><br/> 237 //!`template<class SizeType>`<br/> 238 //!`SizeType operator()(SizeType cur_cap, SizeType add_min_cap, SizeType max_cap) const;`.<br/><br/> 239 //!`cur_cap` is the current capacity, `add_min_cap` is the minimum additional capacity 240 //!we want to achieve and `max_cap` is the maximum capacity that the allocator or other 241 //!factors allow. The implementation should return a value between `cur_cap` + `add_min_cap` 242 //!and `max_cap`. `cur_cap` + `add_min_cap` is guaranteed not to overflow/wraparound, 243 //! but the implementation should handle wraparound produced by the growth factor. 244 //! 245 //!Predefined growth factors that can be passed as arguments to this option are: 246 //!\c boost::container::growth_factor_50 247 //!\c boost::container::growth_factor_60 248 //!\c boost::container::growth_factor_100 249 //! 250 //!If this option is not specified, a default will be used by the container. 251 BOOST_INTRUSIVE_OPTION_TYPE(growth_factor, GrowthFactor, GrowthFactor, growth_factor_type) 252 253 //!This option specifies the unsigned integer type that a user wants the container 254 //!to use to hold size-related information inside a container (e.g. current size, current capacity). 255 //! 256 //!\tparam StoredSizeType An unsigned integer type. It shall be smaller than than the size 257 //! of the size_type deduced from `allocator_traits<A>::size_type` or the same type. 258 //! 259 //!If the maximum capacity() to be used is limited, a user can try to use 8-bit, 16-bit 260 //!(e.g. in 32-bit machines), or 32-bit size types (e.g. in a 64 bit machine) to see if some 261 //!memory can be saved for empty vectors. This could potentially performance benefits due to better 262 //!cache usage. 263 //! 264 //!Note that alignment requirements can disallow theoretical space savings. Example: 265 //!\c vector holds a pointer and two size types (for size and capacity), in a 32 bit machine 266 //!a 8 bit size type (total size: 4 byte pointer + 2 x 1 byte sizes = 6 bytes) 267 //!will not save space when comparing two 16-bit size types because usually 268 //!a 32 bit alignment is required for vector and the size will be rounded to 8 bytes. In a 64-bit 269 //!machine a 16 bit size type does not usually save memory when comparing to a 32-bit size type. 270 //!Measure the size of the resulting container and do not assume a smaller \c stored_size 271 //!will always lead to a smaller sizeof(container). 272 //! 273 //!If a user tries to insert more elements than representable by \c stored_size, vector 274 //!will throw a length_error. 275 //! 276 //!If this option is not specified, `allocator_traits<A>::size_type` (usually std::size_t) will 277 //!be used to store size-related information inside the container. 278 BOOST_INTRUSIVE_OPTION_TYPE(stored_size, StoredSizeType, StoredSizeType, stored_size_type) 279 280 //! Helper metafunction to combine options into a single type to be used 281 //! by \c boost::container::vector. 282 //! Supported options are: \c boost::container::growth_factor and \c boost::container::stored_size 283 #if defined(BOOST_CONTAINER_DOXYGEN_INVOKED) || defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 284 template<class ...Options> 285 #else 286 template<class O1 = void, class O2 = void, class O3 = void, class O4 = void> 287 #endif 288 struct vector_options 289 { 290 /// @cond 291 typedef typename ::boost::intrusive::pack_options 292 < vector_null_opt, 293 #if !defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 294 O1, O2, O3, O4 295 #else 296 Options... 297 #endif 298 >::type packed_options; 299 typedef vector_opt< typename packed_options::growth_factor_type 300 , typename packed_options::stored_size_type> implementation_defined; 301 /// @endcond 302 typedef implementation_defined type; 303 }; 304 305 #if !defined(BOOST_NO_CXX11_TEMPLATE_ALIASES) 306 307 //! Helper alias metafunction to combine options into a single type to be used 308 //! by \c boost::container::vector. 309 //! Supported options are: \c boost::container::growth_factor and \c boost::container::stored_size 310 template<class ...Options> 311 using vector_options_t = typename boost::container::vector_options<Options...>::type; 312 313 #endif 314 315 //////////////////////////////////////////////////////////////// 316 // 317 // 318 // OPTIONS FOR SMALL-VECTOR CONTAINER 319 // 320 // 321 //////////////////////////////////////////////////////////////// 322 323 //! This option specifies the desired alignment for the value_type stored 324 //! in the container. 325 //! A value zero represents the natural alignment. 326 //! 327 //!\tparam Alignment An unsigned integer value. Must be power of two. 328 BOOST_INTRUSIVE_OPTION_CONSTANT(inplace_alignment, std::size_t, Alignment, inplace_alignment) 329 330 #if !defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 331 332 template<class GrowthType, std::size_t InplaceAlignment> 333 struct small_vector_opt 334 { 335 typedef GrowthType growth_factor_type; 336 static const std::size_t inplace_alignment = InplaceAlignment; 337 }; 338 339 typedef small_vector_opt<void, 0u> small_vector_null_opt; 340 341 #endif //!defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 342 343 //! Helper metafunction to combine options into a single type to be used 344 //! by \c boost::container::small_vector. 345 //! Supported options are: \c boost::container::growth_factor and \c boost::container::inplace_alignment 346 #if defined(BOOST_CONTAINER_DOXYGEN_INVOKED) || defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 347 template<class ...Options> 348 #else 349 template<class O1 = void, class O2 = void, class O3 = void, class O4 = void> 350 #endif 351 struct small_vector_options 352 { 353 /// @cond 354 typedef typename ::boost::intrusive::pack_options 355 < small_vector_null_opt, 356 #if !defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 357 O1, O2, O3, O4 358 #else 359 Options... 360 #endif 361 >::type packed_options; 362 typedef small_vector_opt< typename packed_options::growth_factor_type 363 , packed_options::inplace_alignment> implementation_defined; 364 /// @endcond 365 typedef implementation_defined type; 366 }; 367 368 #if !defined(BOOST_NO_CXX11_TEMPLATE_ALIASES) 369 370 //! Helper alias metafunction to combine options into a single type to be used 371 //! by \c boost::container::small_vector. 372 //! Supported options are: \c boost::container::growth_factor and \c boost::container::stored_size 373 template<class ...Options> 374 using small_vector_options_t = typename boost::container::small_vector_options<Options...>::type; 375 376 #endif 377 378 379 //////////////////////////////////////////////////////////////// 380 // 381 // 382 // OPTIONS FOR STATIC-VECTOR CONTAINER 383 // 384 // 385 //////////////////////////////////////////////////////////////// 386 387 //!This option specifies if the container will throw if in 388 //!the static capacity is not sufficient to hold the required 389 //!values. If false is specified, insufficient capacity will 390 //!lead to BOOST_ASSERT, and if this assertion returns, to undefined behaviour, 391 //!which potentially can lead to better static_vector performance. 392 //!The default value is true. 393 //! 394 //!\tparam ThrowOnExhaustion A boolean value. True if throw is required. 395 BOOST_INTRUSIVE_OPTION_CONSTANT(throw_on_overflow, bool, ThrowOnOverflow, throw_on_overflow) 396 397 #if !defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 398 399 template<bool ThrowOnOverflow, std::size_t InplaceAlignment> 400 struct static_vector_opt 401 { 402 static const bool throw_on_overflow = ThrowOnOverflow; 403 static const std::size_t inplace_alignment = InplaceAlignment; 404 }; 405 406 typedef static_vector_opt<true, 0u> static_vector_null_opt; 407 408 #endif //!defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 409 410 //! Helper metafunction to combine options into a single type to be used 411 //! by \c boost::container::static_vector. 412 //! Supported options are: \c boost::container::throw_on_overflow and \c boost::container::inplace_alignment 413 #if defined(BOOST_CONTAINER_DOXYGEN_INVOKED) || defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 414 template<class ...Options> 415 #else 416 template<class O1 = void, class O2 = void, class O3 = void, class O4 = void> 417 #endif 418 struct static_vector_options 419 { 420 /// @cond 421 typedef typename ::boost::intrusive::pack_options 422 < static_vector_null_opt, 423 #if !defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 424 O1, O2, O3, O4 425 #else 426 Options... 427 #endif 428 >::type packed_options; 429 typedef static_vector_opt< packed_options::throw_on_overflow 430 , packed_options::inplace_alignment> implementation_defined; 431 /// @endcond 432 typedef implementation_defined type; 433 }; 434 435 #if !defined(BOOST_NO_CXX11_TEMPLATE_ALIASES) 436 437 //! Helper alias metafunction to combine options into a single type to be used 438 //! by \c boost::container::static_vector. 439 //! Supported options are: \c boost::container::growth_factor and \c boost::container::stored_size 440 template<class ...Options> 441 using static_vector_options_t = typename boost::container::static_vector_options<Options...>::type; 442 443 #endif 444 445 446 //////////////////////////////////////////////////////////////// 447 // 448 // 449 // OPTIONS FOR DEQUE-BASED CONTAINERS 450 // 451 // 452 //////////////////////////////////////////////////////////////// 453 454 #if !defined(BOOST_CONTAINER_DOXYGEN_INVOKED) 455 456 template<std::size_t BlockBytes, std::size_t BlockSize> 457 struct deque_opt 458 { 459 static const std::size_t block_bytes = BlockBytes; 460 static const std::size_t block_size = BlockSize; 461 BOOST_STATIC_ASSERT_MSG(!(block_bytes && block_size), "block_bytes and block_size can't be specified at the same time"); 462 }; 463 464 typedef deque_opt<0u, 0u> deque_null_opt; 465 466 #endif 467 468 //! Helper metafunction to combine options into a single type to be used 469 //! by \c boost::container::deque. 470 //! Supported options are: \c boost::container::block_bytes 471 #if defined(BOOST_CONTAINER_DOXYGEN_INVOKED) || defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 472 template<class ...Options> 473 #else 474 template<class O1 = void, class O2 = void, class O3 = void, class O4 = void> 475 #endif 476 struct deque_options 477 { 478 /// @cond 479 typedef typename ::boost::intrusive::pack_options 480 < deque_null_opt, 481 #if !defined(BOOST_CONTAINER_VARIADIC_TEMPLATES) 482 O1, O2, O3, O4 483 #else 484 Options... 485 #endif 486 >::type packed_options; 487 typedef deque_opt< packed_options::block_bytes, packed_options::block_size > implementation_defined; 488 /// @endcond 489 typedef implementation_defined type; 490 }; 491 492 #if !defined(BOOST_NO_CXX11_TEMPLATE_ALIASES) 493 494 //! Helper alias metafunction to combine options into a single type to be used 495 //! by \c boost::container::deque. 496 //! Supported options are: \c boost::container::block_bytes 497 template<class ...Options> 498 using deque_options_t = typename boost::container::deque_options<Options...>::type; 499 500 #endif 501 502 //!This option specifies the maximum size of a block in bytes: this delimites the number of contiguous elements 503 //!that will be allocated by deque as min(1u, BlockBytes/sizeof(value_type)) 504 //!A value zero represents the default value. 505 //! 506 //!\tparam BlockBytes An unsigned integer value. 507 BOOST_INTRUSIVE_OPTION_CONSTANT(block_bytes, std::size_t, BlockBytes, block_bytes) 508 509 //!This option specifies the size of a block, delimites the number of contiguous elements 510 //!that will be allocated by deque as BlockSize. 511 //!A value zero represents the default value. 512 //! 513 //!\tparam BlockBytes An unsigned integer value. 514 BOOST_INTRUSIVE_OPTION_CONSTANT(block_size, std::size_t, BlockSize, block_size) 515 516 } //namespace container { 517 } //namespace boost { 518 519 #include <boost/container/detail/config_end.hpp> 520 521 #endif //#ifndef BOOST_CONTAINER_OPTIONS_HPP 522