1<!--"$Id: 2.2.html,v 1.4 2007/05/17 18:17:17 bostic Exp $ (Sleepycat) $Date: 2007/05/17 18:17:17 $"--> 2<html> 3<head> 4<title>The Berkeley DB Package: Interface Changes introduced in DB 2.2.0</title> 5<meta name="description" content="DB: A database programmatic toolkit."> 6<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods"> 7</head> 8<body bgcolor=white> 9 10<h3 align=center>Interface Changes introduced in DB 2.2.0:</h3> 11 12<ol> 13 14<li> 15In DB 2.2.0, the handles returned by the DB subsystems, for example, the 16db_appinit() function's DB_ENV, and the db_open() function's DB, are 17free-threaded. If you specify the DB_THREAD flag to each subsystem, or 18globally using db_appinit(), you can then use the returned handle 19concurrently in any number of threads. 20 21<p> 22There are some important caveats for using DB handles concurrently in 23multiple threads: 24 25<p><ol type=a> 26<li> 27The DB_THREAD flag must be specified for all subsystems either explicitly 28by calling the subsystems open() function, or via the db_appinit() 29function. Setting the DB_THREAD flag inconsistently may result in 30database corruption. 31 32<p><li> 33Spinlocks must have be implemented for the compiler/architecture 34combination. Attempting to specify the DB_THREAD flag will fail with an 35EINVAL error if spinlocks are not available. 36 37<p><li> 38Only a single thread may call the close function for a returned database 39or subsystem handle. See 40db_open(3) 41and the appropriate subsystem manual pages for more information. 42 43<p><li> 44Either the DB_DBT_MALLOC or DB_DBT_USERMEM flags must be set in a DBT used 45for key or data retrieval. See 46db_open(3) 47for more information. 48 49<p><li> 50The DB_CURRENT, DB_NEXT and DB_PREV flags to the log_get() function may 51not be used by a free-threaded handle. If such calls are necessary, a 52thread should explicitly create a unique DB_LOG handle by calling log_open(). 53See 54db_log(3) 55for more information. 56 57<p><li> 58Each database operation (that is, any call to a function underlying the 59handles returned by db_open() and db_cursor()) is normally performed on 60behalf of a locker associated with the handle. If, within a single 61thread of control, multiple calls on behalf of the same locker are 62desired, then transactions must be used. See db(3) for more 63information. 64 65<p><li> 66Transactions may not span threads, that is, each transaction must begin 67and end in the same thread, and each transaction may only be used by a 68single thread. 69 70</ol> 71 72<p> 73See 74db(3) 75and 76db_appinit(3) 77for more information on using DB in the context of threads. 78 79<p><li> 80We've added spinlock support for OSF/1, HP, Solaris and UTS4, in all cases 81for the native compiler/architecture combination. In the case of Solaris, 82this means that all DB applications must be loaded using the <b>-lthread</b> 83library. 84 85<p><li> 86We've added a C++ API for DB. 87<font color=red> 88There are not yet any manual pages for the C++ API, and the interface is 89going to change! 90</font> 91Please feel free to browse and send us comments, but please remember 92that the C++ interface is going to be different in the next release. 93<p> 94The C++ files and directories in the source distribution are: 95<p> 96<table border> 97<tr> 98<td>db/cxx/</td> 99<td>C++ API</td> 100</tr><tr> 101<td>db/examples_cxx/</td> 102<td>The example programs recoded in C++.</td> 103</tr><tr> 104<td>db/include/cxx_int.h</td> 105<td>Internal C++ include file.</td> 106</tr><tr> 107<td>db/include/db_cxx.h</td> 108<td>External C++ include file.</td> 109</tr> 110</table> 111<p> 112C++ support is automatically built on Win32. To configure it under UNIX, 113specify <b>--enable-cxx</b> as a configuration argument (see the file 114<b>db/build.unix/README</b> for more information). 115 116<p><li> 117The functionality previously embodied in some of the support utilities 118(db_archive(1), 119db_checkpoint(1), 120db_deadlock(1), 121and 122db_recover(1)) 123is now available through the DB API as well. 124<p> 125<table border> 126<tr> 127<td><h3>Utility</h3></td> 128<td><h3>Underlying API support:</h3></td> 129</tr> 130<tr> 131<td>db_archive(1)</td> 132<td>Log archival. See the log_archive() function in 133db_log(3) 134</td> 135</tr><tr> 136<td>db_checkpoint(1)</td> 137<td>Transaction checkpoint. See the txn_checkpoint() function in 138db_txn(3). 139</td> 140</tr><tr> 141<td>db_deadlock(1)</td> 142<td>Deadlock detection. See the lock_detect() function in 143db_lock(3). 144</td> 145</tr><tr> 146<td>db_recover(1)</td> 147<td>Database recovery. See the DB_RECOVER and DB_RECOVER_FATAL flags for 148the db_appinit() function in 149db_appinit(3). 150</td> 151</tr> 152</table> 153 154<p><li> 155We've added a new default hashing function, __ham_func5(), written by 156Glenn Fowler, Landon Curt Noll and Phong Vo, and integrated into DB by 157Ariel Faigon of SGI. We've also deleted the previous supplied function 158__ham_func1(). 159<p> 160<font color=red> 161This change is NOT transparent to applications. 162</font> 163We incremented the hash access method database version number, and the 164new hash function will only be used in newly created databases, which 165means that applications written using version DB 2.2.0 and greater will 166be able to share databases with applications written using previous 167versions of DB with a major number of 2. 168 169<p> 170However, we now use the __ham_func5() hash function internally, in the 171log and lock subsystems, which means that applications written using 172version DB 2.2.0 and greater will NOT be able to share database 173environments, or read log files, written using previous versions of DB. 174 175<p><li> 176The interfaces that DB uses to export statistics have been enhanced and, 177in one case, modified: 178 179<p><ol type=a> 180<li> 181DB 2.2 exports statistical information via the DB handle for the access 182methods. Currently, the only access method for which this information is 183available is B+tree. See the dbp->db_stat() function in the 184db_open(3) 185manual page for more information. 186 187<p><li> 188DB 2.2 exports statistical information for the transaction region via a 189new function, txn_stat(). See 190db_txn(3) 191for more information. 192 193<p><li> 194The 195db_stat(1) 196utility has two new options. The <b>-d</b> flag permits users to display 197the access method statistics. The <b>-t</b> flag permits users to display 198the transaction region statistics. 199 200<p><li> 201The interface for shared memory buffer pool statistics in DB 2.2 has been 202revised to make it consistent with the interfaces provided for the 203transaction region and access methods. 204<font color=red> 205This change is NOT transparent to applications. 206</font> 207See 208db_mpool(3) 209for more information. 210</ol> 211 212<p><li> 213The interface to the shared memory buffer pool has been extended in DB 2142.2 to permit applications to control the maximum size of read-only files 215that will be mapped into the application's address space instead of being 216read through the memory pool cache. See the DB_NOMMAP flag to the 217memp_open() function and the mp_mmapsize field in the DB_ENV structure, 218as described in 219db_mpool(3). 220 221<p><li> 222The interface to the transaction subsystem has been extended in DB 2.2 to 223permit applications to specify that the log is not to be synchronously 224flushed on transaction commit. This potentially provides a significant 225performance improvement for applications that do not require database 226durability. See the DB_TXN_NOSYNC flag to the txn_open() function, as 227described in 228db_txn(3). 229 230<p><li> 231There have been several changes to the process of creating a DB environment: 232 233<p><ol type=a> 234<li> 235By default, when a lock is unavailable to a DB thread (or process), the 236thread/process is put to sleep for a period of time, permitting other 237threads/processes to run. This may not be optimal in the presence of 238multiple threads in a single process. The DB_ENV structure has been 239extended to permit applications to specify a ``yield'' function, which is 240called when a DB thread has requested a lock which is unavailable. See 241db_appinit(3) 242for more information. 243 244<p><li> 245In previous versions of DB, the DB_CREATE flag was implied by calling the 246db_appinit() function, that is, initializing the environment implied that 247the application wanted to create the environment if it did not already 248exist. This version of DB no longer supports this semantic, and the 249DB_CREATE must be explicitly specified to db_appinit() if the application 250wants to create the DB environment. 251<font color=red> 252This change is NOT transparent to applications. 253</font> 254 255<p><li> 256The flags that may be specified when creating the DB environment have been 257extended in DB 2.2 to allow the specification of the DB_MPOOL_PRIVATE flag, 258which was previously supported only by the underlying memory pool subsystem. 259<p> 260The flags that may be specified when creating the DB environment have been 261extended in DB 2.2 to provide new functionality: the list of new flags 262includes DB_NOMMAP, DB_THREAD and DB_TXN_NOSYNC. 263 264<p><li> 265The DB_DATA_DIR configuration argument to the db_appinit() function is 266now additive, permitting applications to specify multiple directories in 267which to 268search for database files. If multiple paths are specified, created data 269files will always be created in the <b>first</b> directory specified. 270 271<p><li> 272The db_errbuf field of the DB_ENV structure has been deleted from the 273current release. In its place, we have added the db_errcall field, which 274specifies a function which is called with the information previously found 275in the db_errbuf buffer. 276<font color=red> 277This change is NOT transparent to applications. 278</font> 279 280<p><li> 281The default temporary file location list (used when no DB_TMP_DIR 282configuration argument was specified) has been extended to include any 283directory specified by the <b>TempFolder</b> environment variable, if it 284exists. 285 286</ol> 287 288<p> 289In all cases, see 290db_appinit(3) 291for more information. 292 293<p><li> 294There have been several changes to the logging subsystem: 295 296<p><ol type=a> 297<li> 298The log_get() and log_put() functions now support the 299standard DBT flags described by the 300db_open(3) 301manual page. 302 303<p><li> 304The interface to the log_flush() function has been extended to 305flush the entire log if a NULL LSN is specified. See 306db_log(3) 307for more information. 308 309<p><li> 310The interface to the log_file() function has been changed in DB 2.2 311to eliminate the need for the library to return allocated memory 312that may never be freed. 313<font color=red> 314This change is NOT transparent to applications. 315</font> 316See 317db_log(3) 318for more information. 319 320<p><li> 321The 322db_checkpoint(1) 323and 324db_deadlock(1) 325utilities have a new option, <b>-L</b>, in DB 2.2 to optionally log their 326process ID to a file. If they exit gracefully, or if they receive a 327SIGINT signal, the log file is removed before they exit. 328 329</ol> 330 331<p><li> 332There have been a couple of changes to the source code layout other 333than those specified above: 334 335<p><ol type=a> 336<li> 337Operating system specific functionality is separated out in DB 2.2 into 338a separate subdirectory in the source code, <b>db/os</b>. 339 340<p><li> 341All of the include files in DB 2.2 have been moved into a single 342subdirectory, <b>db/include</b>, as part of the work to port DB to MacOS. 343 344</ol> 345 346</ol> 347</body> 348</html> 349