[/ Copyright 2006-2007 Daniel James. / 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) ] [def __wang__ [@http://www.concentric.net/~Ttwang/tech/inthash.htm Thomas Wang's article on integer hash functions]] [def __n2345__ [@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2007/n2345.pdf the August 2008 version of the working draft standard]] [def __n2369__ [@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2007/n2369.pdf the August 2008 version of the working draft standard]] [section:rationale Implementation Rationale] The intent of this library is to implement the unordered containers in the draft standard, so the interface was fixed. But there are still some implementation desicions to make. The priorities are conformance to the standard and portability. The [@http://en.wikipedia.org/wiki/Hash_table wikipedia article on hash tables] has a good summary of the implementation issues for hash tables in general. [h2 Data Structure] By specifying an interface for accessing the buckets of the container the standard pretty much requires that the hash table uses chained addressing. It would be conceivable to write a hash table that uses another method. For example, an it could use open addressing, and use the lookup chain to act as a bucket but there are a some serious problems with this: * The draft standard requires that pointers to elements aren't invalidated, so the elements can't be stored in one array, but will need a layer of indirection instead - loosing the efficiency and most of the memory gain, the main advantages of open addressing. * Local iterators would be very inefficient and may not be able to meet the complexity requirements. * There are also the restrictions on when iterators can be invalidated. Since open addressing degrades badly when there are a high number of collisions the restrictions could prevent a rehash when it's really needed. The maximum load factor could be set to a fairly low value to work around this - but the standard requires that it is initially set to 1.0. * And since the standard is written with a eye towards chained addressing, users will be suprised if the performance doesn't reflect that. So chained addressing is used. For containers with unique keys I store the buckets in a single-linked list. There are other possible data structures (such as a double-linked list) that allow for some operations to be faster (such as erasing and iteration) but the possible gain seems small compared to the extra memory needed. The most commonly used operations (insertion and lookup) would not be improved at all. But for containers with equivalent keys a single-linked list can degrade badly when a large number of elements with equivalent keys are inserted. I think it's reasonable to assume that users who choose to use `unordered_multiset` or `unordered_multimap` do so because they are likely to insert elements with equivalent keys. So I have used an alternative data structure that doesn't degrade, at the expense of an extra pointer per node. This works by adding storing a circular linked list for each group of equivalent nodes in reverse order. This allows quick navigation to the end of a group (since the first element points to the last) and can be quickly updated when elements are inserted or erased. The main disadvantage of this approach is some hairy code for erasing elements. [h2 Number of Buckets] There are two popular methods for choosing the number of buckets in a hash table. One is to have a prime number of buckets, another is to use a power of 2. Using a prime number of buckets, and choosing a bucket by using the modulous of the hash functions's result will usually give a good result. The downside is that the required modulous operation is fairly expensive. Using a power of 2 allows for much quicker selection of the bucket to use, but at the expense of loosing the upper bits of the hash value. For some specially designed hash functions it is possible to do this and still get a good result but as the containers can take arbitrary hash functions this can't be relied on. To avoid this a transformation could be applied to the hash function, for an example see __wang__. Unfortunately, a transformation like Wang's requires knowledge of the number of bits in the hash value, so it isn't portable enough. This leaves more expensive methods, such as Knuth's Multiplicative Method (mentioned in Wang's article). These don't tend to work as well as taking the modulous of a prime, and the extra computation required might negate efficiency advantage of power of 2 hash tables. So, this implementation uses a prime number for the hash table size. [h2 Active Issues and Proposals] [h3 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2257.html Removing unused allocator functions]] This proposal suggests removing the `construct`, `destroy` and `address` member functions - all of which Boost.Unordered calls. It's near trivial to replace the calls with the appropriate code - and will simplify the implementation, as well as make supporting `emplace` easier. [@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2007/n2339.htm N2339] opposed this change. [h3 [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#431 431. Swapping containers with unequal allocators]] I followed Howard Hinnant's advice and implemented option 3. There is currently a further issue - if the allocator's swap does throw there's no guarantee what state the allocators will be in. The only solution seems to be to double buffer the allocators. But I'm assuming that it won't throw for now. Update: The comittee have now decided that `swap` should do a fast swap if the allocator is Swappable and a slow swap using copy construction otherwise. To make this distinction requires concepts. For now I'm sticking with the current implementation. [h3 [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#518 518. Are insert and erase stable for unordered_multiset and unordered_multimap?]] The current proposal is that insert, erase and rehash are stable - so they are here. [h2 Future Developments] [h3 Support for `emplace`] In __n2369__ a new member function, `emplace` was added to the containers to allow placement insert, as described in __n2345__. To fully implement this `std::forward` is required, along with new functions in `std::allocator` and new constructors in `std::pair`. But partial support is possible - especially if I don't use the `construct` member of allocators. [endsect]