1 /* Copyright 2003-2019 Joaquin M Lopez Munoz.
2 * Distributed under the Boost Software License, Version 1.0.
3 * (See accompanying file LICENSE_1_0.txt or copy at
4 * http://www.boost.org/LICENSE_1_0.txt)
6 * See http://www.boost.org/libs/multi_index for library home page.
9 #ifndef BOOST_MULTI_INDEX_DETAIL_HASH_INDEX_NODE_HPP
10 #define BOOST_MULTI_INDEX_DETAIL_HASH_INDEX_NODE_HPP
16 #include <boost/config.hpp> /* keep it first to prevent nasty warns in MSVC */
17 #include <boost/multi_index/detail/allocator_traits.hpp>
18 #include <boost/multi_index/detail/raw_ptr.hpp>
23 namespace multi_index{
27 /* Certain C++ requirements on unordered associative containers (see LWG issue
28 * #579) imply a data structure where nodes are linked in a single list, which
29 * in its turn forces implementors to add additional overhed per node to
30 * associate each with its corresponding bucket. Others resort to storing hash
31 * values, we use an alternative structure providing unconditional O(1)
32 * manipulation, even in situations of unfair hash distribution, plus some
33 * lookup speedups. For unique indices we maintain a doubly linked list of
34 * nodes except that if N is the first node of a bucket its associated
35 * bucket node is embedded between N and the preceding node in the following
38 * +---+ +---+ +---+ +---+
39 * <--+ |<--+ | <--+ |<--+ |
40 * ... | B0| | B1| ... | B1| | B2| ...
41 * | |-+ | +--> | |-+ | +-->
42 * +-+-+ | +---+ +-+-+ | +---+
48 * --+---+---+---+-- --+---+---+---+--
49 * ... | | B1| | ... | | B2| | ...
50 * --+---+---+---+-- --+---+---+---+--
53 * The fist and last nodes of buckets can be checked with
55 * first node of a bucket: Npn != N
56 * last node of a bucket: Nnp != N
58 * (n and p short for ->next(), ->prior(), bucket nodes have prior pointers
59 * only). Pure insert and erase (without lookup) can be unconditionally done
61 * For non-unique indices we add the following additional complexity: when
62 * there is a group of 3 or more equivalent elements, they are linked as
65 * +-----------------------+
67 * +---+ | +---+ +---+ +---+
69 * | F | | S | ... | P | | L |
71 * +---+ +---+ +---+ | +---+
73 * +-----------------------+
75 * F, S, P and L are the first, second, penultimate and last node in the
76 * group, respectively (S and P can coincide if the group has size 3.) This
77 * arrangement is used to skip equivalent elements in O(1) when doing lookup,
78 * while preserving O(1) insert/erase. The following invariants identify
79 * special positions (some of the operations have to be carefully implemented
80 * as Xnn is not valid if Xn points to a bucket):
82 * first node of a bucket: Npnp == N
83 * last node of a bucket: Nnpp == N
84 * first node of a group: Nnp != N && Nnppn == N
85 * second node of a group: Npn != N && Nppnn == N
86 * n-1 node of a group: Nnp != N && Nnnpp == N
87 * last node of a group: Npn != N && Npnnp == N
89 * The memory overhead is one pointer per bucket plus two pointers per node,
90 * probably unbeatable. The resulting structure is bidirectonally traversable,
91 * though currently we are just providing forward iteration.
94 template<typename Allocator>
95 struct hashed_index_node_impl;
97 /* half-header (only prior() pointer) to use for the bucket array */
99 template<typename Allocator>
100 struct hashed_index_base_node_impl
102 typedef typename rebind_alloc_for<
103 Allocator,hashed_index_base_node_impl
104 >::type base_allocator;
105 typedef typename rebind_alloc_for<
106 Allocator,hashed_index_node_impl<Allocator>
107 >::type node_allocator;
108 typedef allocator_traits<base_allocator> base_alloc_traits;
109 typedef allocator_traits<node_allocator> node_alloc_traits;
110 typedef typename base_alloc_traits::pointer base_pointer;
111 typedef typename base_alloc_traits::const_pointer const_base_pointer;
112 typedef typename node_alloc_traits::pointer pointer;
113 typedef typename node_alloc_traits::const_pointer const_pointer;
114 typedef typename node_alloc_traits::difference_type difference_type;
116 pointer& prior(){return prior_;}
117 pointer prior()const{return prior_;}
123 /* full header (prior() and next()) for the nodes */
125 template<typename Allocator>
126 struct hashed_index_node_impl:hashed_index_base_node_impl<Allocator>
129 typedef hashed_index_base_node_impl<Allocator> super;
132 typedef typename super::base_pointer base_pointer;
133 typedef typename super::const_base_pointer const_base_pointer;
134 typedef typename super::pointer pointer;
135 typedef typename super::const_pointer const_pointer;
137 base_pointer& next(){return next_;}
138 base_pointer next()const{return next_;}
140 static pointer pointer_from(base_pointer x)
142 return static_cast<pointer>(
143 static_cast<hashed_index_node_impl*>(
144 raw_ptr<super*>(x)));
147 static base_pointer base_pointer_from(pointer x)
149 return static_cast<base_pointer>(
150 raw_ptr<hashed_index_node_impl*>(x));
157 /* Boost.MultiIndex requires machinery to reverse unlink operations. A simple
158 * way to make a pointer-manipulation function undoable is to templatize
159 * its internal pointer assignments with a functor that, besides doing the
160 * assignment, keeps track of the original pointer values and can later undo
161 * the operations in reverse order.
164 struct default_assigner
166 template<typename T> void operator()(T& x,const T& val){x=val;}
169 template<typename Node>
170 struct unlink_undo_assigner
172 typedef typename Node::base_pointer base_pointer;
173 typedef typename Node::pointer pointer;
175 unlink_undo_assigner():pointer_track_count(0),base_pointer_track_count(0){}
177 void operator()(pointer& x,pointer val)
179 pointer_tracks[pointer_track_count].x=&x;
180 pointer_tracks[pointer_track_count++].val=x;
184 void operator()(base_pointer& x,base_pointer val)
186 base_pointer_tracks[base_pointer_track_count].x=&x;
187 base_pointer_tracks[base_pointer_track_count++].val=x;
191 void operator()() /* undo op */
193 /* in the absence of aliasing, restitution order is immaterial */
195 while(pointer_track_count--){
196 *(pointer_tracks[pointer_track_count].x)=
197 pointer_tracks[pointer_track_count].val;
199 while(base_pointer_track_count--){
200 *(base_pointer_tracks[base_pointer_track_count].x)=
201 base_pointer_tracks[base_pointer_track_count].val;
205 struct pointer_track {pointer* x; pointer val;};
206 struct base_pointer_track{base_pointer* x; base_pointer val;};
208 /* We know the maximum number of pointer and base pointer assignments that
209 * the two unlink versions do, so we can statically reserve the needed
213 pointer_track pointer_tracks[3];
214 int pointer_track_count;
215 base_pointer_track base_pointer_tracks[2];
216 int base_pointer_track_count;
219 /* algorithmic stuff for unique and non-unique variants */
221 struct hashed_unique_tag{};
222 struct hashed_non_unique_tag{};
224 template<typename Node,typename Category>
225 struct hashed_index_node_alg;
227 template<typename Node>
228 struct hashed_index_node_alg<Node,hashed_unique_tag>
230 typedef typename Node::base_pointer base_pointer;
231 typedef typename Node::const_base_pointer const_base_pointer;
232 typedef typename Node::pointer pointer;
233 typedef typename Node::const_pointer const_pointer;
235 static bool is_first_of_bucket(pointer x)
237 return x->prior()->next()!=base_pointer_from(x);
240 static pointer after(pointer x)
242 return is_last_of_bucket(x)?x->next()->prior():pointer_from(x->next());
245 static pointer after_local(pointer x)
247 return is_last_of_bucket(x)?pointer(0):pointer_from(x->next());
250 static pointer next_to_inspect(pointer x)
252 return is_last_of_bucket(x)?pointer(0):pointer_from(x->next());
255 static void link(pointer x,base_pointer buc,pointer end)
257 if(buc->prior()==pointer(0)){ /* empty bucket */
258 x->prior()=end->prior();
259 x->next()=end->prior()->next();
260 x->prior()->next()=buc;
265 x->prior()=buc->prior()->prior();
266 x->next()=base_pointer_from(buc->prior());
268 x->next()->prior()=x;
272 static void unlink(pointer x)
274 default_assigner assign;
278 typedef unlink_undo_assigner<Node> unlink_undo;
280 template<typename Assigner>
281 static void unlink(pointer x,Assigner& assign)
283 if(is_first_of_bucket(x)){
284 if(is_last_of_bucket(x)){
285 assign(x->prior()->next()->prior(),pointer(0));
286 assign(x->prior()->next(),x->next());
287 assign(x->next()->prior()->prior(),x->prior());
290 assign(x->prior()->next()->prior(),pointer_from(x->next()));
291 assign(x->next()->prior(),x->prior());
294 else if(is_last_of_bucket(x)){
295 assign(x->prior()->next(),x->next());
296 assign(x->next()->prior()->prior(),x->prior());
299 assign(x->prior()->next(),x->next());
300 assign(x->next()->prior(),x->prior());
304 /* used only at rehashing */
306 static void append(pointer x,pointer end)
308 x->prior()=end->prior();
309 x->next()=end->prior()->next();
310 x->prior()->next()=base_pointer_from(x);
314 static bool unlink_last(pointer end)
316 /* returns true iff bucket is emptied */
318 pointer x=end->prior();
319 if(x->prior()->next()==base_pointer_from(x)){
320 x->prior()->next()=x->next();
321 end->prior()=x->prior();
325 x->prior()->next()->prior()=pointer(0);
326 x->prior()->next()=x->next();
327 end->prior()=x->prior();
333 static pointer pointer_from(base_pointer x)
335 return Node::pointer_from(x);
338 static base_pointer base_pointer_from(pointer x)
340 return Node::base_pointer_from(x);
343 static bool is_last_of_bucket(pointer x)
345 return x->next()->prior()!=x;
349 template<typename Node>
350 struct hashed_index_node_alg<Node,hashed_non_unique_tag>
352 typedef typename Node::base_pointer base_pointer;
353 typedef typename Node::const_base_pointer const_base_pointer;
354 typedef typename Node::pointer pointer;
355 typedef typename Node::const_pointer const_pointer;
357 static bool is_first_of_bucket(pointer x)
359 return x->prior()->next()->prior()==x;
362 static bool is_first_of_group(pointer x)
365 x->next()->prior()!=x&&
366 x->next()->prior()->prior()->next()==base_pointer_from(x);
369 static pointer after(pointer x)
371 if(x->next()->prior()==x)return pointer_from(x->next());
372 if(x->next()->prior()->prior()==x)return x->next()->prior();
373 if(x->next()->prior()->prior()->next()==base_pointer_from(x))
374 return pointer_from(x->next());
375 return pointer_from(x->next())->next()->prior();
378 static pointer after_local(pointer x)
380 if(x->next()->prior()==x)return pointer_from(x->next());
381 if(x->next()->prior()->prior()==x)return pointer(0);
382 if(x->next()->prior()->prior()->next()==base_pointer_from(x))
383 return pointer_from(x->next());
384 return pointer_from(x->next())->next()->prior();
387 static pointer next_to_inspect(pointer x)
389 if(x->next()->prior()==x)return pointer_from(x->next());
390 if(x->next()->prior()->prior()==x)return pointer(0);
391 if(x->next()->prior()->next()->prior()!=x->next()->prior())
393 return pointer_from(x->next()->prior()->next());
396 static void link(pointer x,base_pointer buc,pointer end)
398 if(buc->prior()==pointer(0)){ /* empty bucket */
399 x->prior()=end->prior();
400 x->next()=end->prior()->next();
401 x->prior()->next()=buc;
406 x->prior()=buc->prior()->prior();
407 x->next()=base_pointer_from(buc->prior());
409 x->next()->prior()=x;
413 static void link(pointer x,pointer first,pointer last)
415 x->prior()=first->prior();
416 x->next()=base_pointer_from(first);
417 if(is_first_of_bucket(first)){
418 x->prior()->next()->prior()=x;
421 x->prior()->next()=base_pointer_from(x);
427 else if(first->next()==base_pointer_from(last)){
429 first->next()=base_pointer_from(x);
432 pointer second=pointer_from(first->next()),
433 lastbutone=last->prior();
434 second->prior()=first;
436 lastbutone->next()=base_pointer_from(x);
440 static void unlink(pointer x)
442 default_assigner assign;
446 typedef unlink_undo_assigner<Node> unlink_undo;
448 template<typename Assigner>
449 static void unlink(pointer x,Assigner& assign)
451 if(x->prior()->next()==base_pointer_from(x)){
452 if(x->next()->prior()==x){
453 left_unlink(x,assign);
454 right_unlink(x,assign);
456 else if(x->next()->prior()->prior()==x){ /* last of bucket */
457 left_unlink(x,assign);
458 right_unlink_last_of_bucket(x,assign);
460 else if(x->next()->prior()->prior()->next()==
461 base_pointer_from(x)){ /* first of group size */
462 left_unlink(x,assign);
463 right_unlink_first_of_group(x,assign);
465 else{ /* n-1 of group */
466 unlink_last_but_one_of_group(x,assign);
469 else if(x->prior()->next()->prior()==x){ /* first of bucket */
470 if(x->next()->prior()==x){
471 left_unlink_first_of_bucket(x,assign);
472 right_unlink(x,assign);
474 else if(x->next()->prior()->prior()==x){ /* last of bucket */
475 assign(x->prior()->next()->prior(),pointer(0));
476 assign(x->prior()->next(),x->next());
477 assign(x->next()->prior()->prior(),x->prior());
479 else{ /* first of group */
480 left_unlink_first_of_bucket(x,assign);
481 right_unlink_first_of_group(x,assign);
484 else if(x->next()->prior()->prior()==x){ /* last of group and bucket */
485 left_unlink_last_of_group(x,assign);
486 right_unlink_last_of_bucket(x,assign);
488 else if(pointer_from(x->prior()->prior()->next())
489 ->next()==base_pointer_from(x)){ /* second of group */
490 unlink_second_of_group(x,assign);
492 else{ /* last of group, ~(last of bucket) */
493 left_unlink_last_of_group(x,assign);
494 right_unlink(x,assign);
498 /* used only at rehashing */
500 static void link_range(
501 pointer first,pointer last,base_pointer buc,pointer cend)
503 if(buc->prior()==pointer(0)){ /* empty bucket */
504 first->prior()=cend->prior();
505 last->next()=cend->prior()->next();
506 first->prior()->next()=buc;
511 first->prior()=buc->prior()->prior();
512 last->next()=base_pointer_from(buc->prior());
514 last->next()->prior()=last;
518 static void append_range(pointer first,pointer last,pointer cend)
520 first->prior()=cend->prior();
521 last->next()=cend->prior()->next();
522 first->prior()->next()=base_pointer_from(first);
526 static std::pair<pointer,bool> unlink_last_group(pointer end)
528 /* returns first of group true iff bucket is emptied */
530 pointer x=end->prior();
531 if(x->prior()->next()==base_pointer_from(x)){
532 x->prior()->next()=x->next();
533 end->prior()=x->prior();
534 return std::make_pair(x,false);
536 else if(x->prior()->next()->prior()==x){
537 x->prior()->next()->prior()=pointer(0);
538 x->prior()->next()=x->next();
539 end->prior()=x->prior();
540 return std::make_pair(x,true);
543 pointer y=pointer_from(x->prior()->next());
545 if(y->prior()->next()==base_pointer_from(y)){
546 y->prior()->next()=x->next();
547 end->prior()=y->prior();
548 return std::make_pair(y,false);
551 y->prior()->next()->prior()=pointer(0);
552 y->prior()->next()=x->next();
553 end->prior()=y->prior();
554 return std::make_pair(y,true);
559 static void unlink_range(pointer first,pointer last)
561 if(is_first_of_bucket(first)){
562 if(is_last_of_bucket(last)){
563 first->prior()->next()->prior()=pointer(0);
564 first->prior()->next()=last->next();
565 last->next()->prior()->prior()=first->prior();
568 first->prior()->next()->prior()=pointer_from(last->next());
569 last->next()->prior()=first->prior();
572 else if(is_last_of_bucket(last)){
573 first->prior()->next()=last->next();
574 last->next()->prior()->prior()=first->prior();
577 first->prior()->next()=last->next();
578 last->next()->prior()=first->prior();
583 static pointer pointer_from(base_pointer x)
585 return Node::pointer_from(x);
588 static base_pointer base_pointer_from(pointer x)
590 return Node::base_pointer_from(x);
593 static bool is_last_of_bucket(pointer x)
595 return x->next()->prior()->prior()==x;
598 template<typename Assigner>
599 static void left_unlink(pointer x,Assigner& assign)
601 assign(x->prior()->next(),x->next());
604 template<typename Assigner>
605 static void right_unlink(pointer x,Assigner& assign)
607 assign(x->next()->prior(),x->prior());
610 template<typename Assigner>
611 static void left_unlink_first_of_bucket(pointer x,Assigner& assign)
613 assign(x->prior()->next()->prior(),pointer_from(x->next()));
616 template<typename Assigner>
617 static void right_unlink_last_of_bucket(pointer x,Assigner& assign)
619 assign(x->next()->prior()->prior(),x->prior());
622 template<typename Assigner>
623 static void right_unlink_first_of_group(pointer x,Assigner& assign)
625 pointer second=pointer_from(x->next()),
626 last=second->prior(),
627 lastbutone=last->prior();
628 if(second==lastbutone){
629 assign(second->next(),base_pointer_from(last));
630 assign(second->prior(),x->prior());
633 assign(lastbutone->next(),base_pointer_from(second));
634 assign(second->next()->prior(),last);
635 assign(second->prior(),x->prior());
639 template<typename Assigner>
640 static void left_unlink_last_of_group(pointer x,Assigner& assign)
642 pointer lastbutone=x->prior(),
643 first=pointer_from(lastbutone->next()),
644 second=pointer_from(first->next());
645 if(lastbutone==second){
646 assign(lastbutone->prior(),first);
647 assign(lastbutone->next(),x->next());
650 assign(second->prior(),lastbutone);
651 assign(lastbutone->prior()->next(),base_pointer_from(first));
652 assign(lastbutone->next(),x->next());
656 template<typename Assigner>
657 static void unlink_last_but_one_of_group(pointer x,Assigner& assign)
659 pointer first=pointer_from(x->next()),
660 second=pointer_from(first->next()),
661 last=second->prior();
663 assign(last->prior(),first);
664 assign(first->next(),base_pointer_from(last));
667 assign(last->prior(),x->prior());
668 assign(x->prior()->next(),base_pointer_from(first));
672 template<typename Assigner>
673 static void unlink_second_of_group(pointer x,Assigner& assign)
675 pointer last=x->prior(),
676 lastbutone=last->prior(),
677 first=pointer_from(lastbutone->next());
679 assign(first->next(),base_pointer_from(last));
680 assign(last->prior(),first);
683 assign(first->next(),x->next());
684 assign(x->next()->prior(),last);
689 template<typename Super>
690 struct hashed_index_node_trampoline:
691 hashed_index_node_impl<
692 typename rebind_alloc_for<
693 typename Super::allocator_type,char
697 typedef typename rebind_alloc_for<
698 typename Super::allocator_type,char
699 >::type impl_allocator_type;
700 typedef hashed_index_node_impl<impl_allocator_type> impl_type;
703 template<typename Super,typename Category>
704 struct hashed_index_node:
705 Super,hashed_index_node_trampoline<Super>
708 typedef hashed_index_node_trampoline<Super> trampoline;
711 typedef typename trampoline::impl_type impl_type;
712 typedef hashed_index_node_alg<
713 impl_type,Category> node_alg;
714 typedef typename trampoline::base_pointer impl_base_pointer;
715 typedef typename trampoline::const_base_pointer const_impl_base_pointer;
716 typedef typename trampoline::pointer impl_pointer;
717 typedef typename trampoline::const_pointer const_impl_pointer;
718 typedef typename trampoline::difference_type difference_type;
720 impl_pointer& prior(){return trampoline::prior();}
721 impl_pointer prior()const{return trampoline::prior();}
722 impl_base_pointer& next(){return trampoline::next();}
723 impl_base_pointer next()const{return trampoline::next();}
727 return static_cast<impl_pointer>(
728 static_cast<impl_type*>(static_cast<trampoline*>(this)));
731 const_impl_pointer impl()const
733 return static_cast<const_impl_pointer>(
734 static_cast<const impl_type*>(static_cast<const trampoline*>(this)));
737 static hashed_index_node* from_impl(impl_pointer x)
740 static_cast<hashed_index_node*>(
741 static_cast<trampoline*>(
742 raw_ptr<impl_type*>(x)));
745 static const hashed_index_node* from_impl(const_impl_pointer x)
748 static_cast<const hashed_index_node*>(
749 static_cast<const trampoline*>(
750 raw_ptr<const impl_type*>(x)));
753 /* interoperability with hashed_index_iterator */
755 static void increment(hashed_index_node*& x)
757 x=from_impl(node_alg::after(x->impl()));
760 static void increment_local(hashed_index_node*& x)
762 x=from_impl(node_alg::after_local(x->impl()));
766 } /* namespace multi_index::detail */
768 } /* namespace multi_index */
770 } /* namespace boost */