hash_policy.hpp

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 // Copyright (C) 2005, 2006 Free Software Foundation, Inc.
00004 //
00005 // This file is part of the GNU ISO C++ Library.  This library is free
00006 // software; you can redistribute it and/or modify it under the terms
00007 // of the GNU General Public License as published by the Free Software
00008 // Foundation; either version 2, or (at your option) any later
00009 // version.
00010 
00011 // This library is distributed in the hope that it will be useful, but
00012 // WITHOUT ANY WARRANTY; without even the implied warranty of
00013 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014 // General Public License for more details.
00015 
00016 // You should have received a copy of the GNU General Public License
00017 // along with this library; see the file COPYING.  If not, write to
00018 // the Free Software Foundation, 59 Temple Place - Suite 330, Boston,
00019 // MA 02111-1307, USA.
00020 
00021 // As a special exception, you may use this file as part of a free
00022 // software library without restriction.  Specifically, if other files
00023 // instantiate templates or use macros or inline functions from this
00024 // file, or you compile this file and link it with other files to
00025 // produce an executable, this file does not by itself cause the
00026 // resulting executable to be covered by the GNU General Public
00027 // License.  This exception does not however invalidate any other
00028 // reasons why the executable file might be covered by the GNU General
00029 // Public License.
00030 
00031 // Copyright (C) 2004 Ami Tavory and Vladimir Dreizin, IBM-HRL.
00032 
00033 // Permission to use, copy, modify, sell, and distribute this software
00034 // is hereby granted without fee, provided that the above copyright
00035 // notice appears in all copies, and that both that copyright notice
00036 // and this permission notice appear in supporting documentation. None
00037 // of the above authors, nor IBM Haifa Research Laboratories, make any
00038 // representation about the suitability of this software for any
00039 // purpose. It is provided "as is" without express or implied
00040 // warranty.
00041 
00042 /**
00043  * @file hash_policy.hpp
00044  * Contains hash-related policies.
00045  */
00046 
00047 #ifndef PB_DS_HASH_POLICY_HPP
00048 #define PB_DS_HASH_POLICY_HPP
00049 
00050 #include <algorithm>
00051 #include <vector>
00052 #include <cmath>
00053 #include <ext/pb_ds/exception.hpp>
00054 #include <ext/pb_ds/detail/type_utils.hpp>
00055 #include <ext/pb_ds/detail/hash_fn/mask_based_range_hashing.hpp>
00056 #include <ext/pb_ds/detail/hash_fn/mod_based_range_hashing.hpp>
00057 #include <ext/pb_ds/detail/resize_policy/hash_load_check_resize_trigger_size_base.hpp>
00058 
00059 namespace pb_ds
00060 {
00061   // A null hash function, indicating that the combining hash function
00062   // is actually a ranged hash function.
00063   struct null_hash_fn
00064   { };
00065 
00066   // A null probe function, indicating that the combining probe
00067   // function is actually a ranged probe function.
00068   struct null_probe_fn
00069   { };
00070 
00071 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
00072 #define PB_DS_CLASS_C_DEC linear_probe_fn<Size_Type>
00073 
00074   // A probe sequence policy using fixed increments.
00075   template<typename Size_Type = size_t>
00076   class linear_probe_fn
00077   {
00078   public:
00079     typedef Size_Type size_type;
00080 
00081     void
00082     swap(PB_DS_CLASS_C_DEC& other);
00083 
00084   protected:
00085     // Returns the i-th offset from the hash value.
00086     inline size_type
00087     operator()(size_type i) const;
00088   };
00089 
00090 #include <ext/pb_ds/detail/hash_fn/linear_probe_fn_imp.hpp>
00091 
00092 #undef PB_DS_CLASS_T_DEC
00093 #undef PB_DS_CLASS_C_DEC
00094 
00095 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
00096 #define PB_DS_CLASS_C_DEC quadratic_probe_fn<Size_Type>
00097 
00098   // A probe sequence policy using square increments.
00099   template<typename Size_Type = size_t>
00100   class quadratic_probe_fn
00101   {
00102   public:
00103     typedef Size_Type size_type;
00104 
00105     void
00106     swap(PB_DS_CLASS_C_DEC& other);
00107 
00108   protected:
00109     // Returns the i-th offset from the hash value.
00110     inline size_type
00111     operator()(size_type i) const;
00112   };
00113 
00114 #include <ext/pb_ds/detail/hash_fn/quadratic_probe_fn_imp.hpp>
00115 
00116 #undef PB_DS_CLASS_T_DEC
00117 #undef PB_DS_CLASS_C_DEC
00118 
00119 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
00120 #define PB_DS_CLASS_C_DEC direct_mask_range_hashing<Size_Type>
00121 
00122   // A mask range-hashing class (uses a bit-mask).
00123   template<typename Size_Type = size_t>
00124   class direct_mask_range_hashing 
00125   : public detail::mask_based_range_hashing<Size_Type>
00126   {
00127   private:
00128     typedef detail::mask_based_range_hashing<Size_Type> mask_based_base;
00129 
00130   public:
00131     typedef Size_Type size_type;
00132 
00133     void
00134     swap(PB_DS_CLASS_C_DEC& other);
00135 
00136   protected:
00137     void
00138     notify_resized(size_type size);
00139 
00140     // Transforms the __hash value hash into a ranged-hash value
00141     // (using a bit-mask).
00142     inline size_type
00143     operator()(size_type hash) const;
00144   };
00145 
00146 #include <ext/pb_ds/detail/hash_fn/direct_mask_range_hashing_imp.hpp>
00147 
00148 #undef PB_DS_CLASS_T_DEC
00149 #undef PB_DS_CLASS_C_DEC
00150 
00151 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
00152 #define PB_DS_CLASS_C_DEC direct_mod_range_hashing<Size_Type>
00153 
00154   // A mod range-hashing class (uses the modulo function).
00155   template<typename Size_Type = size_t>
00156   class direct_mod_range_hashing 
00157   : public detail::mod_based_range_hashing<Size_Type>
00158   {
00159   public:
00160     typedef Size_Type size_type;
00161       
00162     void
00163     swap(PB_DS_CLASS_C_DEC& other);
00164 
00165   protected:
00166     void
00167     notify_resized(size_type size);
00168       
00169     // Transforms the __hash value hash into a ranged-hash value
00170     // (using a modulo operation).
00171     inline size_type
00172     operator()(size_type hash) const;
00173       
00174   private:
00175     typedef detail::mod_based_range_hashing<size_type> mod_based_base;
00176   };
00177 
00178 #include <ext/pb_ds/detail/hash_fn/direct_mod_range_hashing_imp.hpp>
00179 
00180 #undef PB_DS_CLASS_T_DEC
00181 #undef PB_DS_CLASS_C_DEC
00182 
00183 #define PB_DS_CLASS_T_DEC template<bool External_Load_Access, typename Size_Type>
00184 #define PB_DS_CLASS_C_DEC hash_load_check_resize_trigger<External_Load_Access, Size_Type>
00185 #define PB_DS_SIZE_BASE_C_DEC detail::hash_load_check_resize_trigger_size_base<Size_Type, External_Load_Access>
00186 
00187   // A resize trigger policy based on a load check. It keeps the
00188   // load factor between some load factors load_min and load_max.
00189   template<bool External_Load_Access = false, typename Size_Type = size_t>
00190   class hash_load_check_resize_trigger : private PB_DS_SIZE_BASE_C_DEC
00191   {
00192   public:
00193     typedef Size_Type size_type;
00194 
00195     enum
00196       {
00197     external_load_access = External_Load_Access
00198       };
00199 
00200     // Default constructor, or constructor taking load_min and
00201     // load_max load factors between which this policy will keep the
00202     // actual load.
00203     hash_load_check_resize_trigger(float load_min = 0.125,
00204                    float load_max = 0.5);
00205 
00206     void
00207     swap(hash_load_check_resize_trigger& other);
00208 
00209     virtual
00210     ~hash_load_check_resize_trigger();
00211 
00212     // Returns a pair of the minimal and maximal loads, respectively.
00213     inline std::pair<float, float>
00214     get_loads() const;
00215 
00216     // Sets the loads through a pair of the minimal and maximal
00217     // loads, respectively.
00218     void
00219     set_loads(std::pair<float, float> load_pair);
00220 
00221   protected:
00222     inline void
00223     notify_insert_search_start();
00224 
00225     inline void
00226     notify_insert_search_collision();
00227 
00228     inline void
00229     notify_insert_search_end();
00230 
00231     inline void
00232     notify_find_search_start();
00233 
00234     inline void
00235     notify_find_search_collision();
00236 
00237     inline void
00238     notify_find_search_end();
00239 
00240     inline void
00241     notify_erase_search_start();
00242 
00243     inline void
00244     notify_erase_search_collision();
00245 
00246     inline void
00247     notify_erase_search_end();
00248 
00249     // Notifies an element was inserted. The total number of entries
00250     // in the table is num_entries.
00251     inline void
00252     notify_inserted(size_type num_entries);
00253 
00254     inline void
00255     notify_erased(size_type num_entries);
00256 
00257     // Notifies the table was cleared.
00258     void
00259     notify_cleared();
00260 
00261     // Notifies the table was resized as a result of this object's
00262     // signifying that a resize is needed.
00263     void
00264     notify_resized(size_type new_size);
00265 
00266     void
00267     notify_externally_resized(size_type new_size);
00268 
00269     inline bool
00270     is_resize_needed() const;
00271 
00272     inline bool
00273     is_grow_needed(size_type size, size_type num_entries) const;
00274 
00275   private:
00276     virtual void
00277     do_resize(size_type new_size);
00278 
00279     typedef PB_DS_SIZE_BASE_C_DEC size_base;
00280 
00281 #ifdef _GLIBCXX_DEBUG
00282     void
00283     assert_valid() const;
00284 #endif 
00285 
00286     float   m_load_min;
00287     float   m_load_max;
00288     size_type   m_next_shrink_size;
00289     size_type   m_next_grow_size;
00290     bool    m_resize_needed;
00291   };
00292 
00293 #include <ext/pb_ds/detail/resize_policy/hash_load_check_resize_trigger_imp.hpp>
00294 
00295 #undef PB_DS_CLASS_T_DEC
00296 #undef PB_DS_CLASS_C_DEC
00297 #undef PB_DS_SIZE_BASE_C_DEC
00298 
00299 #define PB_DS_CLASS_T_DEC template<bool External_Load_Access, typename Size_Type>
00300 #define PB_DS_CLASS_C_DEC cc_hash_max_collision_check_resize_trigger<External_Load_Access, Size_Type>
00301 
00302   // A resize trigger policy based on collision checks. It keeps the
00303   // simulated load factor lower than some given load factor.
00304   template<bool External_Load_Access = false, typename Size_Type = size_t>
00305   class cc_hash_max_collision_check_resize_trigger
00306   {
00307   public:
00308     typedef Size_Type size_type;
00309 
00310     enum
00311       {
00312     external_load_access = External_Load_Access
00313       };
00314 
00315     // Default constructor, or constructor taking load, a __load
00316     // factor which it will attempt to maintain.
00317     cc_hash_max_collision_check_resize_trigger(float load = 0.5);
00318 
00319     void
00320     swap(PB_DS_CLASS_C_DEC& other);
00321 
00322     // Returns the current load.
00323     inline float
00324     get_load() const;
00325 
00326     // Sets the load; does not resize the container.
00327     void
00328     set_load(float load);
00329 
00330   protected:
00331     inline void
00332     notify_insert_search_start();
00333 
00334     inline void
00335     notify_insert_search_collision();
00336 
00337     inline void
00338     notify_insert_search_end();
00339 
00340     inline void
00341     notify_find_search_start();
00342 
00343     inline void
00344     notify_find_search_collision();
00345 
00346     inline void
00347     notify_find_search_end();
00348 
00349     inline void
00350     notify_erase_search_start();
00351 
00352     inline void
00353     notify_erase_search_collision();
00354 
00355     inline void
00356     notify_erase_search_end();
00357 
00358     inline void
00359     notify_inserted(size_type num_entries);
00360 
00361     inline void
00362     notify_erased(size_type num_entries);
00363 
00364     void
00365     notify_cleared();
00366 
00367     // Notifies the table was resized as a result of this object's
00368     // signifying that a resize is needed.
00369     void
00370     notify_resized(size_type new_size);
00371 
00372     void
00373     notify_externally_resized(size_type new_size);
00374 
00375     inline bool
00376     is_resize_needed() const;
00377 
00378     inline bool
00379     is_grow_needed(size_type size, size_type num_entries) const;
00380 
00381   private:
00382     void
00383     calc_max_num_coll();
00384 
00385     inline void
00386     calc_resize_needed();
00387 
00388     float   m_load;
00389     size_type   m_size;
00390     size_type   m_num_col;
00391     size_type   m_max_col;
00392     bool    m_resize_needed;
00393   };
00394 
00395 #include <ext/pb_ds/detail/resize_policy/cc_hash_max_collision_check_resize_trigger_imp.hpp>
00396 
00397 #undef PB_DS_CLASS_T_DEC
00398 #undef PB_DS_CLASS_C_DEC
00399 
00400 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
00401 #define PB_DS_CLASS_C_DEC hash_exponential_size_policy<Size_Type>
00402 
00403   // A size policy whose sequence of sizes form an exponential
00404   // sequence (typically powers of 2.
00405   template<typename Size_Type = size_t>
00406   class hash_exponential_size_policy
00407   {
00408   public:
00409     typedef Size_Type size_type;
00410 
00411     // Default constructor, or onstructor taking a start_size, or
00412     // constructor taking a start size and grow_factor. The policy
00413     // will use the sequence of sizes start_size, start_size*
00414     // grow_factor, start_size* grow_factor^2, ...
00415     hash_exponential_size_policy(size_type start_size = 8,
00416                  size_type grow_factor = 2);
00417 
00418     void
00419     swap(PB_DS_CLASS_C_DEC& other);
00420 
00421   protected:
00422     size_type
00423     get_nearest_larger_size(size_type size) const;
00424 
00425     size_type
00426     get_nearest_smaller_size(size_type size) const;
00427 
00428   private:
00429     size_type m_start_size;
00430     size_type m_grow_factor;
00431   };
00432 
00433 #include <ext/pb_ds/detail/resize_policy/hash_exponential_size_policy_imp.hpp>
00434 
00435 #undef PB_DS_CLASS_T_DEC
00436 #undef PB_DS_CLASS_C_DEC
00437 
00438 #define PB_DS_CLASS_T_DEC
00439 #define PB_DS_CLASS_C_DEC hash_prime_size_policy
00440 
00441   // A size policy whose sequence of sizes form a nearly-exponential
00442   // sequence of primes.
00443   class hash_prime_size_policy
00444   {
00445   public:
00446     // Size type.
00447     typedef size_t size_type;
00448 
00449     // Default constructor, or onstructor taking a start_size The
00450     // policy will use the sequence of sizes approximately
00451     // start_size, start_size* 2, start_size* 2^2, ...
00452     hash_prime_size_policy(size_type start_size = 8);
00453 
00454     inline void
00455     swap(PB_DS_CLASS_C_DEC& other);
00456 
00457   protected:
00458     size_type
00459     get_nearest_larger_size(size_type size) const;
00460 
00461     size_type
00462     get_nearest_smaller_size(size_type size) const;
00463 
00464   private:
00465     size_type m_start_size;
00466   };
00467 
00468 #include <ext/pb_ds/detail/resize_policy/hash_prime_size_policy_imp.hpp>
00469 
00470 #undef PB_DS_CLASS_T_DEC
00471 #undef PB_DS_CLASS_C_DEC
00472 
00473 #define PB_DS_CLASS_T_DEC template<typename Size_Policy, typename Trigger_Policy, bool External_Size_Access, typename Size_Type>
00474 
00475 #define PB_DS_CLASS_C_DEC hash_standard_resize_policy<Size_Policy, Trigger_Policy, External_Size_Access, Size_Type>
00476 
00477   // A resize policy which delegates operations to size and trigger policies.
00478   template<typename Size_Policy = hash_exponential_size_policy<>,
00479        typename Trigger_Policy = hash_load_check_resize_trigger<>,
00480        bool External_Size_Access = false,
00481        typename Size_Type = size_t>
00482   class hash_standard_resize_policy 
00483   : public Size_Policy, public Trigger_Policy
00484   {
00485   public:
00486     typedef Size_Type       size_type;
00487     typedef Trigger_Policy  trigger_policy;
00488     typedef Size_Policy     size_policy;
00489 
00490     enum
00491       {
00492     external_size_access = External_Size_Access
00493       };
00494 
00495     // Default constructor.
00496     hash_standard_resize_policy();
00497 
00498     // constructor taking some policies r_size_policy will be copied
00499     // by the Size_Policy object of this object.
00500     hash_standard_resize_policy(const Size_Policy& r_size_policy);
00501 
00502     // constructor taking some policies. r_size_policy will be
00503     // copied by the Size_Policy object of this
00504     // object. r_trigger_policy will be copied by the Trigger_Policy
00505     // object of this object.
00506     hash_standard_resize_policy(const Size_Policy& r_size_policy, 
00507                 const Trigger_Policy& r_trigger_policy);
00508 
00509     virtual
00510     ~hash_standard_resize_policy();
00511 
00512     inline void
00513     swap(PB_DS_CLASS_C_DEC& other);
00514 
00515     // Access to the Size_Policy object used.
00516     Size_Policy& 
00517     get_size_policy();
00518 
00519     // Const access to the Size_Policy object used.
00520     const Size_Policy& 
00521     get_size_policy() const;
00522 
00523     // Access to the Trigger_Policy object used.
00524     Trigger_Policy& 
00525     get_trigger_policy();
00526 
00527     // Access to the Trigger_Policy object used.
00528     const Trigger_Policy& 
00529     get_trigger_policy() const;
00530 
00531     // Returns the actual size of the container.
00532     inline size_type
00533     get_actual_size() const;
00534 
00535     // Resizes the container to suggested_new_size, a suggested size
00536     // (the actual size will be determined by the Size_Policy
00537     // object).
00538     void
00539     resize(size_type suggested_new_size);
00540 
00541   protected:
00542     inline void
00543     notify_insert_search_start();
00544 
00545     inline void
00546     notify_insert_search_collision();
00547 
00548     inline void
00549     notify_insert_search_end();
00550 
00551     inline void
00552     notify_find_search_start();
00553 
00554     inline void
00555     notify_find_search_collision();
00556 
00557     inline void
00558     notify_find_search_end();
00559 
00560     inline void
00561     notify_erase_search_start();
00562 
00563     inline void
00564     notify_erase_search_collision();
00565 
00566     inline void
00567     notify_erase_search_end();
00568 
00569     inline void
00570     notify_inserted(size_type num_e);
00571 
00572     inline void
00573     notify_erased(size_type num_e);
00574 
00575     void
00576     notify_cleared();
00577 
00578     void
00579     notify_resized(size_type new_size);
00580 
00581     inline bool
00582     is_resize_needed() const;
00583 
00584     // Queries what the new size should be, when the container is
00585     // resized naturally. The current __size of the container is
00586     // size, and the number of used entries within the container is
00587     // num_used_e.
00588     size_type
00589     get_new_size(size_type size, size_type num_used_e) const;
00590 
00591   private:
00592     // Resizes to new_size.
00593     virtual void
00594     do_resize(size_type new_size);
00595 
00596     typedef Trigger_Policy trigger_policy_base;
00597 
00598     typedef Size_Policy size_policy_base;
00599 
00600     size_type m_size;
00601   };
00602 
00603 #include <ext/pb_ds/detail/resize_policy/hash_standard_resize_policy_imp.hpp>
00604 
00605 #undef PB_DS_CLASS_T_DEC
00606 #undef PB_DS_CLASS_C_DEC
00607 
00608 } // namespace pb_ds
00609 
00610 #endif 

Generated on Thu Nov 1 13:11:51 2007 for libstdc++ by  doxygen 1.5.1