1/*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2009 Oracle. All rights reserved. 5 * 6 */ 7using System; 8using System.Collections.Generic; 9using System.Text; 10 11namespace BerkeleyDB { 12 /// <summary> 13 /// A class representing configuration parameters for 14 /// <see cref="HashDatabase"/> 15 /// </summary> 16 public class HashDatabaseConfig : DatabaseConfig { 17 /* Fields for db->set_flags() */ 18 /// <summary> 19 /// Policy for duplicate data items in the database; that is, insertion 20 /// when the key of the key/data pair being inserted already exists in 21 /// the database will be successful. 22 /// </summary> 23 /// <remarks> 24 /// <para> 25 /// The ordering of duplicates in the database for 26 /// <see cref="DuplicatesPolicy.UNSORTED"/> is determined by the order 27 /// of insertion, unless the ordering is otherwise specified by use of a 28 /// cursor operation or a duplicate sort function. The ordering of 29 /// duplicates in the database for 30 /// <see cref="DuplicatesPolicy.SORTED"/> is determined by the 31 /// duplicate comparison function. If the application does not specify a 32 /// comparison function using 33 /// <see cref="DuplicateCompare"/>, a default lexical 34 /// comparison will be used. 35 /// </para> 36 /// <para> 37 /// <see cref="DuplicatesPolicy.SORTED"/> is preferred to 38 /// <see cref="DuplicatesPolicy.UNSORTED"/> for performance reasons. 39 /// <see cref="DuplicatesPolicy.UNSORTED"/> should only be used by 40 /// applications wanting to order duplicate data items manually. 41 /// </para> 42 /// <para> 43 /// If the database already exists, the value of Duplicates must be the 44 /// same as the existing database or an error will be returned. 45 /// </para> 46 /// </remarks> 47 public DuplicatesPolicy Duplicates; 48 internal new uint flags { 49 get { 50 uint ret = base.flags; 51 ret |= (uint)Duplicates; 52 return ret; 53 } 54 } 55 56 /// <summary> 57 /// The policy for how to handle database creation. 58 /// </summary> 59 /// <remarks> 60 /// If the database does not already exist and 61 /// <see cref="CreatePolicy.NEVER"/> is set, 62 /// <see cref="HashDatabase.Open"/> will fail. 63 /// </remarks> 64 public CreatePolicy Creation; 65 internal new uint openFlags { 66 get { 67 uint flags = base.openFlags; 68 flags |= (uint)Creation; 69 return flags; 70 } 71 } 72 73 /// <summary> 74 /// The Hash key comparison function. 75 /// </summary> 76 /// <remarks> 77 /// <para> 78 /// The comparison function is called whenever it is necessary to 79 /// compare a key specified by the application with a key currently 80 /// stored in the tree. 81 /// </para> 82 /// <para> 83 /// If no comparison function is specified, the keys are compared 84 /// lexically, with shorter keys collating before longer keys. 85 /// </para> 86 /// <para> 87 /// If the database already exists, the comparison function must be the 88 /// same as that historically used to create the database or corruption 89 /// can occur. 90 /// </para> 91 /// </remarks> 92 public EntryComparisonDelegate HashComparison; 93 94 internal bool fillFactorIsSet; 95 private uint ffactor; 96 /// <summary> 97 /// The desired density within the hash table. If no value is specified, 98 /// the fill factor will be selected dynamically as pages are filled. 99 /// </summary> 100 /// <remarks> 101 /// <para> 102 /// The density is an approximation of the number of keys allowed to 103 /// accumulate in any one bucket, determining when the hash table grows 104 /// or shrinks. If you know the average sizes of the keys and data in 105 /// your data set, setting the fill factor can enhance performance. A 106 /// reasonable rule computing fill factor is to set it to the following: 107 /// </para> 108 /// <para> 109 /// (pagesize - 32) / (average_key_size + average_data_size + 8) 110 /// </para> 111 /// <para> 112 /// If the database already exists, this setting will be ignored. 113 /// </para> 114 /// </remarks> 115 public uint FillFactor { 116 get { return ffactor; } 117 set { 118 fillFactorIsSet = true; 119 ffactor = value; 120 } 121 } 122 123 /// <summary> 124 /// A user-defined hash function; if no hash function is specified, a 125 /// default hash function is used. 126 /// </summary> 127 /// <remarks> 128 /// <para> 129 /// Because no hash function performs equally well on all possible data, 130 /// the user may find that the built-in hash function performs poorly 131 /// with a particular data set. 132 /// </para> 133 /// <para> 134 /// If the database already exists, HashFunction must be the same as 135 /// that historically used to create the database or corruption can 136 /// occur. 137 /// </para> 138 /// </remarks> 139 public HashFunctionDelegate HashFunction; 140 141 /// <summary> 142 /// The duplicate data item comparison function. 143 /// </summary> 144 /// <remarks> 145 /// <para> 146 /// The comparison function is called whenever it is necessary to 147 /// compare a data item specified by the application with a data item 148 /// currently stored in the database. Setting DuplicateCompare implies 149 /// setting <see cref="Duplicates"/> to 150 /// <see cref="DuplicatesPolicy.SORTED"/>. 151 /// </para> 152 /// <para> 153 /// If no comparison function is specified, the data items are compared 154 /// lexically, with shorter data items collating before longer data 155 /// items. 156 /// </para> 157 /// <para> 158 /// If the database already exists when <see cref="HashDatabase.Open"/> 159 /// is called, the delegate must be the same as that historically used 160 /// to create the database or corruption can occur. 161 /// </para> 162 /// </remarks> 163 public EntryComparisonDelegate DuplicateCompare; 164 165 internal bool nelemIsSet; 166 private uint nelems; 167 /// <summary> 168 /// An estimate of the final size of the hash table. 169 /// </summary> 170 /// <remarks> 171 /// <para> 172 /// In order for the estimate to be used when creating the database, 173 /// <see cref="FillFactor"/> must also be set. If the estimate or fill 174 /// factor are not set or are set too low, hash tables will still expand 175 /// gracefully as keys are entered, although a slight performance 176 /// degradation may be noticed. 177 /// </para> 178 /// <para> 179 /// If the database already exists, this setting will be ignored. 180 /// </para> 181 /// </remarks> 182 public uint TableSize { 183 get { return nelems; } 184 set { 185 nelemIsSet = true; 186 nelems = value; 187 } 188 } 189 190 /// <summary> 191 /// Instantiate a new HashDatabaseConfig object 192 /// </summary> 193 public HashDatabaseConfig() { 194 Duplicates = DuplicatesPolicy.NONE; 195 HashComparison = null; 196 fillFactorIsSet = false; 197 nelemIsSet = false; 198 Creation = CreatePolicy.NEVER; 199 } 200 } 201}