From bd1477fa257400adfa7b015fe518a64d67068a27 Mon Sep 17 00:00:00 2001 From: Daniel James Date: Sun, 20 May 2007 16:48:52 +0000 Subject: [PATCH] Add a couple of notes about the updated issues/proposals in the post-Oxford mailing (more to come...) [SVN r4145] --- doc/rationale.qbk | 147 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 doc/rationale.qbk diff --git a/doc/rationale.qbk b/doc/rationale.qbk new file mode 100644 index 00000000..dbc6e089 --- /dev/null +++ b/doc/rationale.qbk @@ -0,0 +1,147 @@ +[/ 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]] + +[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. + +[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. In +the future I develop support for concepts and do this, but what should I do for +the current implementation and, in the future, compilers without concepts? I +should probably change it to a slow swap. + +[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?]] + +In this implementation, erase is stable. All inserts are stable, except for +inserting with a hint, which has slightly surprising behaviour. If the hint +points to the first element in the correct equal range it inserts at the end of +the range, for all other elements in the range it inserts immediately before +the element. I am very tempted to change insert with a hint to just ignore the +hint completely. + +[h3 [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#528 + 528. TR1: issue 6.19 vs 6.3.4.3/2 (and 6.3.4.5/2)]] + +In the current implementation, for `unordered_set` and +`unordered_multiset`, `iterator` and `const_iterator` have the same type and +`local_iterator` and `const_local_iterator` also have the same type. This makes +it impossible to implement the header exactly as described in the synopsis, as +some member functions are overloaded by the same type. + +The proposed resolution is to add a new subsection to 17.4.4: +[:An implementation shall not supply an overloaded function signature specified in any library clause if such a signature would be inherently ambiguous during overload resolution due to two library types referring to the same type.] +So I don't supply the `iterator` overloads. + +[h3 [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#560 + 560. User-defined allocators without default constructor]] + +This implementation should work okay for an allocator without a default +constructor, although I don't currently test for this. + +[endsect]