boost_unordered/doc/rationale.qbk

[/ Copyright 2006-2008 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
    N2345, 'Placement Insert for Containers']]
[def __n2369__
    [@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2007/n2369.pdf
    the August 2007 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 decisions 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, 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 - losing 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 surprised 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 modulus
of the hash function's result will usually give a good result. The downside
is that the required modulus 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
modulus 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 Equality operators]

`operator==` and `operator!=` are not included in the standard, but I've
added them as I think they could be useful and can be efficiently
implemented. They are specified
differently to the standard associative containers, comparing keys
using the equality predicate rather than `operator==`. This is inconsistent
with the other containers but it is probably closer to user's expectations.

[h2 Active Issues and Proposals]

[h3 Removing unused allocator functions]

In
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2257.html
N2257, removing unused allocator functions],
Matt Austern suggests removing the `construct`, `destroy` and `address` member
functions - all of which Boost.Unordered calls. Changing this will simplify the
implementation, as well as make supporting `emplace` easier, but means that the
containers won't support allocators which require these methods to be called.
Detlef Vollmann opposed this change in
[@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2007/n2339.htm N2339].

[h3 Swapping containers with unequal allocators]

It isn't clear how to swap containers when their allocators aren't equal.
This is 
[@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#431
Issue 431: Swapping containers with unequal allocators].

Howard Hinnant wrote about this in
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1599.html N1599]
and suggested swapping both the allocators and the containers' contents.
But the committee 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.

In
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2387.pdf
N2387, Omnibus Allocator Fix-up Proposals],
Pablo Halpern suggests that there are actually two distinct allocator models,
"Moves with Value" and "Scoped" which behave differently:

[:
When allocators are allowed to have state, it is necessary to have a model for
determining from where an object obtains its allocator. We’ve identified two such
models: the “Moves with Value” allocator model and the “Scoped” allocator model.

In the “Moves with Value” allocator model, the copy constructor of an allocator-aware
class will copy both the value and the allocator from its argument. This is the model
specified in the C++03 standard. With this model, inserting an object into a container
usually causes the new container item to copy the allocator from the object that was
inserted. This model can be useful in special circumstances, e.g., if the items within a
container use an allocator that is specially tuned to the item’s type.

In the “Scoped” allocator model, the allocator used to construct an object is determined
by the context of that object, much like a storage class. With this model, inserting an
object into a container causes the new container item to use the same allocator as the
container. To avoid allocators being used in the wrong context, the allocator is never
copied during copy or move construction. Thus, it is possible using this model to use
allocators based on short-lived resources without fear that an object will transfer its
allocator to a copy that might outlive the (shared) allocator resource. This model is
reasonably safe and generally useful on a large scale. There was strong support in the
2005 Tremblant meeting for pursuing an allocator model that propagates allocators
from container to contained objects.
]

With these models the choice becomes clearer:

[:
I introduced the “Moves with Value” allocator model and the
“Scoped” allocator model. In the former case, the allocator is copied when the container
is copy-constructed. In the latter case it is not. Swapping the allocators is the right thing
to do if the containers conform to the “Moves with Value” allocator model and
absolutely the wrong thing to do if the containers conform to the “Scoped” allocator
model. With the two allocator models well-defined, the desired behavior becomes clear.
]

The proposal is that allocators are swapped if the allocator follows the
"Moves with Value" model and the allocator is swappable. Otherwise a slow swap
is used. Since containers currently only support the "Moves with Value" model
this is consistent with the committee's current recommendation (although it
suggests using a trait to detect if the allocator is swappable rather than a
concept).

Since there is currently neither have a swappable trait or concept for
allocators this implementation always performs a slow swap.

[h3 Are insert and erase stable for unordered_multiset and unordered_multimap?]

It is not specified if `unordered_multiset` and `unordered_multimap` preserve the order
of elements with equivalent keys (i.e. if they're stable under `insert` and `erase`).
This is [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#518 issue 581].
The current proposal is that insert, erase and rehash are stable - so they are here.
(Update: during the release of this version, this requirement was added to
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2691.pdf
the lastest working draft]).

[h3 const_local_iterator cbegin, cend missing from TR1]

[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2684.html#691
Issue 691] is that `cbegin` and `cend` are missing for local iterators.
The current resolution is that they'll be added, so I've added them.

[endsect]