1 #ifndef _DB_STL_COMMON_H 2 #define _DB_STL_COMMON_H 3 4 #ifdef DBSTL_DEBUG_LEAK 5 #include "vld.h" 6 #endif 7 8 #include <assert.h> 9 10 #include "db_cxx.h" 11 12 // In release builds, the native assert will be disabled so we 13 // can't use it in dbstl in cases where we rely on the expression being 14 // evaluated to change the state of the application. 15 // 16 #if !defined(DEBUG) && !defined(_DEBUG) 17 #undef dbstl_assert 18 #define dbstl_assert(expression) 19 #else 20 #undef dbstl_assert 21 #define dbstl_assert(expression) do { \ 22 if (!(expression)) { \ 23 FailedAssertionException ex(__FILE__, __LINE__, #expression);\ 24 throw ex; } } while (0) 25 #endif 26 27 #if defined( DB_WIN32) || defined(_WIN32) 28 #include <windows.h> 29 #include <tchar.h> 30 #else 31 #define TCHAR char 32 #define _T(e) (e) 33 #define _ftprintf fprintf 34 #define _snprintf snprintf 35 #define _tcschr strchr 36 #define _tcscmp strcmp 37 #define _tcscpy strcpy 38 #define _tcslen strlen 39 #define _tgetopt getopt 40 #define _tmain main 41 #define _tprintf printf 42 #define _ttoi atoi 43 #endif 44 45 #undef SIZE_T_MAX 46 // The max value for size_t variables, one fourth of 2 powers 32. 47 #define SIZE_T_MAX 1073741824 48 49 // Macro for HAVE_WSTRING (detected by configure) 50 #define HAVE_WSTRING 1 51 52 // Thread local storage modifier declaration. 53 #define TLS_DECL_MODIFIER __declspec(thread) 54 #define TLS_DEFN_MODIFIER __declspec(thread) 55 56 #if !defined(TLS_DECL_MODIFIER) && !defined(HAVE_PTHREAD_TLS) 57 #error "No appropriate TLS modifier defined." 58 #endif 59 60 ////////////////////////////////////////////////////////////////////////// 61 ///////////////////////////////////////////////////////////////////////// 62 // 63 // C++ compiler portability control macro definitions. 64 // If a C++ compiler does not support the following capabilities, disabling 65 // these flags will remove usage of the feature from DB STL. 66 // Where possible a DB STL has implemented work-arounds for the missing 67 // functionality. 68 // 69 #define HAVE_EXPLICIT_KEYWORD 1 70 #define HAVE_NAMESPACE 1 71 #define HAVE_TYPENAME 1 72 73 // Platform specific compiler capability configuration. 74 #ifdef WIN32 75 #define CLS_SCOPE(clstmpl_name) 76 #else 77 78 // C++ standard: It is not possible to define a full specialized version of 79 // a member function of a class template inside the class body. It needs to 80 // be defined outside the class template, and must be defined in the namespace 81 // scope. 82 #define CLS_SCOPE(clstmpl_name) clstmpl_name:: 83 #define NO_IN_CLASS_FULL_SPECIALIZATION 1 84 #define NO_MEMBER_FUNCTION_PARTIAL_SPECIALIZATION 1 85 #endif 86 87 #if HAVE_NAMESPACE 88 #define START_NS(nsname) namespace nsname { 89 #define END_NS } 90 #else 91 #define START_NS(nsname) struct nsname { 92 #define END_NS }; 93 #endif 94 95 #if HAVE_EXPLICIT_KEYWORD 96 #define EXPLICIT explicit 97 #else 98 #define EXPLICIT 99 #endif 100 101 #if HAVE_TYPENAME 102 #define Typename typename 103 #else 104 #define Typename class 105 #endif 106 107 ////////////////////////////////////////////////////////////////////////// 108 // End of compiler portability control macro definitions. 109 //////////////////////////////////////////////////////////////////////// 110 111 ////////////////////////////////////////////////////////////////////////// 112 ///////////////////////////////////////////////////////////////////////// 113 // 114 // Iterator status macro definitions. 115 // 116 #define INVALID_ITERATOR_POSITION -1 // Iterator goes out of valid range. 117 #define INVALID_ITERATOR_CURSOR -2 // The iterator's dbc cursor is invalid. 118 #define ITERATOR_DUP_ERROR -3 // Failed to duplicate a cursor. 119 120 // Current cursor's key or data dbt has no data. 121 #define INVALID_KEY_DATA -4 122 #define EMPTY_DBT_DATA -5 // Current cursor's pointed data dbt has no data. 123 #define ITERATOR_AT_END -6 124 #define CURSOR_NOT_OPEN -7 125 126 /////////////////////////////////////////////////////////////////////// 127 // End of iterator status macro definitions. 128 ////////////////////////////////////////////////////////////////////// 129 130 ////////////////////////////////////////////////////////////////////// 131 ////////////////////////////////////////////////////////////////////// 132 // 133 // Helper macros definitions. 134 // 135 // Use BDBOP and BDBOP2 to wrap Berkeley DB calls. The macros validate the 136 // return value. On failure, the wrappers clean up, and generate the 137 // expected exception. 138 // 139 #define BDBOP(bdb_call, ret) do { \ 140 if ((ret = (bdb_call)) != 0) throw_bdb_exception(#bdb_call, ret);\ 141 } while(0) 142 #define BDBOP2(bdb_call, ret, cleanup) do { \ 143 if ((ret = (bdb_call)) != 0) { (cleanup); \ 144 throw_bdb_exception(#bdb_call, ret);} \ 145 } while (0) 146 // Do not throw the exception if bdb_call returned a specified error number. 147 #define BDBOP3(bdb_call, ret, exception, cleanup) do { \ 148 if (((ret = (bdb_call)) != 0) && (ret & exception) == 0) { \ 149 (cleanup); throw_bdb_exception(#bdb_call, ret);} \ 150 } while (0) 151 152 #define THROW(exception_type, arg_list) do { \ 153 exception_type ex arg_list; throw ex; } while (0) 154 155 #define THROW0(exception_type) do { \ 156 exception_type ex; throw ex; } while (0) 157 158 #define INVALID_INDEX ((index_type)-1) 159 #define INVALID_DLEN ((u_int32_t)-1) 160 161 #define DBSTL_MAX_DATA_BUF_LEN 1024 * 4096 162 #define DBSTL_MAX_KEY_BUF_LEN 1024 * 4096 163 #define DBSTL_MAX_MTX_ENV_MUTEX 4096 * 4 164 #define DBSTL_BULK_BUF_SIZE 256 * 1024 165 166 #define COMPARE_CHECK(obj) if (this == &obj) return true; 167 #define ASSIGNMENT_PREDCOND(obj) if (this == &obj) return obj; 168 ////////////////////////////////////////////////////////////////// 169 // End of helper macro definitions. 170 ////////////////////////////////////////////////////////////////// 171 172 ////////////////////////////////////////////////////////////////// 173 ////////////////////////////////////////////////////////////////// 174 // 175 // Public global function declarations. 176 // These functions are open/public functionalities of dbstl for 177 // dbstl users to call. 178 // 179 START_NS(dbstl) 180 // _exported is a macro we employ from db_cxx.h of Berkeley DB C++ 181 // API. If we want to export the symbols it decorates on Windows, 182 // we must define the macro "DB_CREATE_DLL", as is defined in dbstl 183 // project property. 184 /// \defgroup dbstl_global_functions dbstl global public functions 185 //@{ 186 187 /// \name Functions to close database/environments. 188 /// Normally you don't have to close any database 189 /// or environment handles, they will be closed automatically. 190 /// Though you still have the following API to close them. 191 //@{ 192 /// Close pdb regardless of reference count. You must make sure pdb 193 /// is not used by others before calling this method. 194 /// You can close the underlying database of a container and assign 195 /// another database with right configurations to it, if the configuration 196 /// is not suitable for the container, there will be an 197 /// InvalidArgumentException type of exception thrown. 198 /// You can't use the container after you called close_db and before setting 199 /// another valid database handle to the container via 200 /// db_container::set_db_handle() function. 201 /// \param pdb The database handle to close. 202 _exported void close_db(Db *pdb); 203 204 /// Close all open database handles regardless of reference count. 205 /// You can't use any container after you called close_all_dbs and 206 /// before setting another valid database handle to the 207 /// container via db_container::set_db_handle() function. 208 /// \sa close_db(Db *); 209 _exported void close_all_dbs(); 210 211 /// \brief Close specified database environment handle regardless of reference 212 /// count. 213 /// 214 /// Make sure the environment is not used by any other databases. 215 /// \param pdbenv The database environment handle to close. 216 _exported void close_db_env(DbEnv *pdbenv); 217 218 /// \brief Close all open database environment handles regardless of 219 /// reference count. 220 /// 221 /// You can't use the container after you called close_db and before setting 222 /// another valid database handle to the container via 223 /// db_container::set_db_handle() function. \sa close_db_env(DbEnv *); 224 _exported void close_all_db_envs(); 225 //@} 226 227 /// \name Transaction control global functions. 228 /// dbstl transaction API. You should call these API rather than DB C/C++ 229 /// API to use Berkeley DB transaction features. 230 //@{ 231 /// Begin a new transaction from the specified environment "env". 232 /// This function is called by dbstl user to begin an external transaction. 233 /// The "flags" parameter is passed to DbEnv::txn_begin(). 234 /// If a transaction created from 235 /// the same database environment already exists and is unresolved, 236 /// the new transaction is started as a child transaction of that transaction, 237 /// and thus you can't specify the parent transaction. 238 /// \param env The environment to start a transaction from. 239 /// \param flags It is set to DbEnv::txn_begin() function. 240 /// \return The newly created transaction. 241 /// 242 _exported DbTxn* begin_txn(u_int32_t flags, DbEnv *env); 243 244 /// Commit current transaction opened in the environment "env". 245 /// This function is called by user to commit an external explicit transaction. 246 /// \param env The environment whose current transaction is to be committed. 247 /// \param flags It is set to DbTxn::commit() funcion. 248 /// \sa commit_txn(DbEnv *, DbTxn *, u_int32_t); 249 /// 250 _exported void commit_txn(DbEnv *env, u_int32_t flags = 0); 251 252 /// Commit a specified transaction and all its child transactions. 253 /// \param env The environment where txn is started from. 254 /// \param txn The transaction to commit, can be a parent transaction of a 255 /// nested transaction group, all un-aborted child transactions of 256 /// it will be committed. 257 /// \param flags It is passed to each DbTxn::commit() call. 258 /// \sa commit_txn(DbEnv *, u_int32_t); 259 _exported void commit_txn(DbEnv *env, DbTxn *txn, u_int32_t flags = 0); 260 261 /// Abort current transaction of environment "env". This function is called by 262 /// dbstl user to abort an outside explicit transaction. 263 /// \param env The environment whose current transaction is to be aborted. 264 /// \sa abort_txn(DbEnv *, DbTxn *); 265 _exported void abort_txn(DbEnv *env); 266 267 /// Abort specified transaction "txn" and all its child transactions. 268 /// That is, "txn" can be a parent transaction of a nested transaction group. 269 /// \param env The environment where txn is started from. 270 /// \param txn The transaction to abort, can be a parent transaction of a 271 /// nested transaction group, all child transactions of it will be aborted. 272 /// \sa abort_txn(DbEnv *); 273 /// 274 _exported void abort_txn(DbEnv *env, DbTxn *txn); 275 276 /// Get current transaction of environment "env". 277 /// \param env The environment whose current transaction we want to get. 278 /// \return Current transaction of env. 279 _exported DbTxn* current_txn(DbEnv *env); 280 281 /// Set environment env's current transaction handle to be newtxn. The original 282 /// transaction handle returned without aborting or commiting. This function 283 /// is used for users to use one transaction among multiple threads. 284 /// \param env The environment whose current transaction to replace. 285 /// \param newtxn The new transaction to be as the current transaction of env. 286 /// \return The old current transaction of env. It is not resolved. 287 _exported DbTxn* set_current_txn_handle(DbEnv *env, DbTxn *newtxn); 288 //@} 289 290 /// \name Functions to open and register database/environment handles. 291 //@{ 292 /// Register a Db handle "pdb1". This handle and handles opened in it will be 293 /// closed by ResourceManager, so application code must not try to close or 294 /// delete it. Users can do enough configuration before opening the Db then 295 /// register it via this function. 296 /// All database handles should be registered via this function in each 297 /// thread using the handle. The only exception is the database handle opened 298 /// by dbstl::open_db should not be registered in the thread of the 299 /// dbstl::open_db call. 300 /// \param pdb1 The database handle to register into dbstl for current thread. 301 /// 302 _exported void register_db(Db *pdb1); 303 304 /// Register a DbEnv handle env1, this handle and handles opened in it will be 305 /// closed by ResourceManager. Application code must not try to close or delete 306 /// it. Users can do enough config before opening the DbEnv and then register 307 /// it via this function. 308 /// All environment handles should be registered via this function in each 309 /// thread using the handle. The only exception is the environment handle 310 /// opened by dbstl::open_db_env should not be registered in the thread of 311 /// the dbstl::open_db_env call. 312 /// \param env1 The environment to register into dbstl for current thread. 313 /// 314 _exported void register_db_env(DbEnv *env1); 315 316 /// Helper function to open a database and register it into dbstl for the 317 /// calling thread. 318 /// Users still need to register it in any other thread using it if it 319 /// is shared by multiple threads, via register_db() function. 320 /// Users don't need to delete or free the memory of the returned object, 321 /// dbstl will take care of that. 322 /// When you don't use dbstl::open_db() but explicitly call DB C++ API to 323 /// open a database, you must new the Db object, rather than create it 324 /// on stack, and you must delete the Db object by yourself. 325 /// \param penv The environment to open the database from. 326 /// \param cflags The create flags passed to Db class constructor. 327 /// \param filename The database file name, passed to Db::open. 328 /// \param dbname The database name, passed to Db::open. 329 /// \param dbtype The database type, passed to Db::open. 330 /// \param oflags The database open flags, passed to Db::open. 331 /// \param mode The database open mode, passed to Db::open. 332 /// \param txn The transaction to open the database from, passed to Db::open. 333 /// \param set_flags The flags to be set to the created database handle. 334 /// \return The opened database handle. 335 /// \sa register_db(Db *); 336 /// \sa open_db_env; 337 /// 338 _exported Db* open_db (DbEnv *penv, const char *filename, DBTYPE dbtype, 339 u_int32_t oflags, u_int32_t set_flags, int mode = 0644, DbTxn *txn = NULL, 340 u_int32_t cflags = 0, const char* dbname = NULL); 341 342 /// Helper function to open an environment and register it into dbstl for the 343 /// calling thread. Users still need to register it in any other thread if it 344 /// is shared by multiple threads, via register_db_env() function above. 345 /// Users don't need to delete or free the memory of the returned object, 346 /// dbstl will take care of that. 347 /// 348 /// When you don't use dbstl::open_env() but explicitly call DB C++ API to 349 /// open an environment, you must new the DbEnv object, rather than create it 350 /// on stack, and you must delete the DbEnv object by yourself. 351 /// \param env_home Environment home directory, it must exist. Passed to 352 /// DbEnv::open. 353 /// \param cflags DbEnv constructor creation flags, passed to DbEnv::DbEnv. 354 /// \param set_flags Flags to set to the created environment before opening it. 355 /// \param oflags Environment open flags, passed to DbEnv::open. 356 /// \param mode Environment region files mode, passed to DbEnv::open. 357 /// \param cachesize Environment cache size, by default 4M bytes. 358 /// \return The opened database environment handle. 359 /// \sa register_db_env(DbEnv *); 360 /// \sa open_db; 361 /// 362 _exported DbEnv* open_env(const char *env_home, u_int32_t set_flags, 363 u_int32_t oflags = DB_CREATE | DB_INIT_MPOOL, 364 u_int32_t cachesize = 4 * 1024 * 1024, 365 int mode = 0644, 366 u_int32_t cflags = 0/* Flags for DbEnv constructor. */); 367 //@} 368 369 /// @name Mutex API based on Berkeley DB mutex. 370 /// These functions are in-process mutex support which uses Berkeley DB 371 /// mutex mechanisms. You can call these functions to do portable 372 /// synchronization for your code. 373 //@{ 374 /// Allocate a Berkeley DB mutex. 375 /// \return Berkeley DB mutex handle. 376 _exported db_mutex_t alloc_mutex(); 377 /// Lock a mutex, wait if it is held by another thread. 378 /// \param mtx The mutex handle to lock. 379 /// \return 0 if succeed, non-zero otherwise, call db_strerror to get message. 380 _exported int lock_mutex(db_mutex_t mtx); 381 /// Unlock a mutex, and return immediately. 382 /// \param mtx The mutex handle to unlock. 383 /// \return 0 if succeed, non-zero otherwise, call db_strerror to get message. 384 _exported int unlock_mutex(db_mutex_t mtx); 385 /// Free a mutex, and return immediately. 386 /// \param mtx The mutex handle to free. 387 /// \return 0 if succeed, non-zero otherwise, call db_strerror to get message. 388 _exported void free_mutex(db_mutex_t mtx); 389 //@} 390 391 /// Close cursors opened in dbp1. 392 /// \param dbp1 The database handle whose active cursors to close. 393 /// \return The number of cursors closed by this call. 394 _exported size_t close_db_cursors(Db* dbp1); 395 396 /// \name Other global functions. 397 //@{ 398 /// If there are multiple threads within a process that make use of dbstl, then 399 /// this function should be called in a single thread mutual exclusively before 400 /// any use of dbstl in a process; Otherwise, you don't need to call it, but 401 /// are allowed to call it anyway. 402 _exported void dbstl_startup(); 403 404 /// This function releases any memory allocated in the heap by code of dbstl, 405 /// and close all DB handles in the right order. 406 /// So you can only call dbstl_exit() right before the entire process exits. 407 /// It will release any memory allocated by dbstl that have to live during 408 /// the entire process lifetime. 409 _exported void dbstl_exit(); 410 411 /// This function release all DB handles in the right order. The environment 412 /// and database handles are only closed when they are not used by other 413 /// threads, otherwise the reference cout is decremented. 414 _exported void dbstl_thread_exit(); 415 416 /// Operators to compare two Dbt objects. 417 /// \param d1 Dbt object to compare. 418 /// \param d2 Dbt object to compare. 419 _exported bool operator==(const Dbt&d1, const Dbt&d2); 420 /// Operators to compare two DBT objects. 421 /// \param d1 DBT object to compare. 422 /// \param d2 DBT object to compare. 423 _exported bool operator==(const DBT&d1, const DBT&d2); 424 425 /// If exisiting random temporary database name generation mechanism is still 426 /// causing name clashes, users can set this global suffix number which will 427 /// be append to each temporary database file name and incremented after each 428 /// append, and by default it is 0. 429 /// \param num Starting number to append to each temporary db file name. 430 _exported void set_global_dbfile_suffix_number(u_int32_t num); 431 //@} 432 433 //@} // dbstl_global_functions 434 435 // Internally used memory allocation functions, they will throw an exception 436 // of NotEnoughMemoryException if can't allocate memory. 437 _exported void * DbstlReAlloc(void *ptr, size_t size); 438 _exported void * DbstlMalloc(size_t size); 439 440 _exported u_int32_t hash_default(Db * /*dbp*/, const void *key, u_int32_t len); 441 442 // Default string manipulation callbacks. 443 _exported u_int32_t dbstl_strlen(const char *str); 444 _exported void dbstl_strcpy(char *dest, const char *src, size_t num); 445 _exported int dbstl_strncmp(const char *s1, const char *s2, size_t num); 446 _exported int dbstl_strcmp(const char *s1, const char *s2); 447 _exported int dbstl_wcscmp(const wchar_t *s1, const wchar_t *s2); 448 _exported int dbstl_wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t num); 449 _exported u_int32_t dbstl_wcslen(const wchar_t *str); 450 _exported void dbstl_wcscpy(wchar_t *dest, const wchar_t *src, size_t num); 451 452 END_NS 453 454 ////////////////////////////////////////////////////////////////// 455 // End of public global function declarations. 456 ////////////////////////////////////////////////////////////////// 457 458 #endif /* !_DB_STL_COMMON_H */ 459