github.com/moontrade/mdbx-go@v0.4.0/mdbx.h (about) 1 /** 2 3 _libmdbx_ is an extremely fast, compact, powerful, embedded, 4 transactional [key-value 5 store](https://en.wikipedia.org/wiki/Key-value_database) database, with 6 [permissive license](./LICENSE). _MDBX_ has a specific set of properties and 7 capabilities, focused on creating unique lightweight solutions with 8 extraordinary performance. 9 10 _libmdbx_ is superior to [LMDB](https://bit.ly/26ts7tL) in terms of features 11 and reliability, not inferior in performance. In comparison to LMDB, _libmdbx_ 12 makes many things just work perfectly, not silently and catastrophically 13 break down. _libmdbx_ supports Linux, Windows, MacOS, OSX, iOS, Android, 14 FreeBSD, DragonFly, Solaris, OpenSolaris, OpenIndiana, NetBSD, OpenBSD and other 15 systems compliant with POSIX.1-2008. 16 17 The origin has been migrated to 18 [GitFlic](https://gitflic.ru/project/erthink/libmdbx) since on 2022-04-15 19 the Github administration, without any warning nor explanation, deleted libmdbx 20 along with a lot of other projects, simultaneously blocking access for many 21 developers. For the same reason ~~Github~~ is blacklisted forever. 22 23 _The Future will (be) [Positive](https://www.ptsecurity.com). Всё будет хорошо._ 24 25 26 \section copyright LICENSE & COPYRIGHT 27 28 \authors Copyright (c) 2015-2022, Leonid Yuriev <leo@yuriev.ru> 29 and other _libmdbx_ authors: please see [AUTHORS](./AUTHORS) file. 30 31 \copyright Redistribution and use in source and binary forms, with or without 32 modification, are permitted only as authorized by the OpenLDAP Public License. 33 34 A copy of this license is available in the file LICENSE in the 35 top-level directory of the distribution or, alternatively, at 36 <http://www.OpenLDAP.org/license.html>. 37 38 --- 39 40 This code is derived from "LMDB engine" written by 41 Howard Chu (Symas Corporation), which itself derived from btree.c 42 written by Martin Hedenfalk. 43 44 --- 45 46 Portions Copyright 2011-2015 Howard Chu, Symas Corp. All rights reserved. 47 48 Redistribution and use in source and binary forms, with or without 49 modification, are permitted only as authorized by the OpenLDAP 50 Public License. 51 52 A copy of this license is available in the file LICENSE in the 53 top-level directory of the distribution or, alternatively, at 54 <http://www.OpenLDAP.org/license.html>. 55 56 --- 57 58 Portions Copyright (c) 2009, 2010 Martin Hedenfalk <martin@bzero.se> 59 60 Permission to use, copy, modify, and distribute this software for any 61 purpose with or without fee is hereby granted, provided that the above 62 copyright notice and this permission notice appear in all copies. 63 64 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 65 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 66 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 67 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 68 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 69 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 70 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 71 72 *******************************************************************************/ 73 74 #pragma once 75 #ifndef LIBMDBX_H 76 #define LIBMDBX_H 77 78 #ifdef _MSC_VER 79 #pragma warning(push, 1) 80 #pragma warning(disable : 4548) /* expression before comma has no effect; \ 81 expected expression with side - effect */ 82 #pragma warning(disable : 4530) /* C++ exception handler used, but unwind \ 83 * semantics are not enabled. Specify /EHsc */ 84 #pragma warning(disable : 4577) /* 'noexcept' used with no exception handling \ 85 * mode specified; termination on exception is \ 86 * not guaranteed. Specify /EHsc */ 87 #endif /* _MSC_VER (warnings) */ 88 89 /* *INDENT-OFF* */ 90 /* clang-format off */ 91 /** 92 \file mdbx.h 93 \brief The libmdbx C API header file 94 95 \defgroup c_api C API 96 @{ 97 \defgroup c_err Error handling 98 \defgroup c_opening Opening & Closing 99 \defgroup c_transactions Transactions 100 \defgroup c_dbi Databases 101 \defgroup c_crud Create/Read/Update/Delete (see Quick Reference in details) 102 103 \details 104 \anchor c_crud_hints 105 # Quick Reference for Insert/Update/Delete operations 106 107 Historically, libmdbx inherits the API basis from LMDB, where it is often 108 difficult to select flags/options and functions for the desired operation. 109 So it is recommend using this hints. 110 111 ## Databases with UNIQUE keys 112 113 In databases created without the \ref MDBX_DUPSORT option, keys are always 114 unique. Thus always a single value corresponds to the each key, and so there 115 are only a few cases of changing data. 116 117 | Case | Flags to use | Result | 118 |---------------------------------------------|---------------------|------------------------| 119 | _INSERTING_||| 120 |Key is absent → Insertion |\ref MDBX_NOOVERWRITE|Insertion | 121 |Key exist → Error since key present |\ref MDBX_NOOVERWRITE|Error \ref MDBX_KEYEXIST and return Present value| 122 | _UPSERTING_||| 123 |Key is absent → Insertion |\ref MDBX_UPSERT |Insertion | 124 |Key exist → Update |\ref MDBX_UPSERT |Update | 125 | _UPDATING_||| 126 |Key is absent → Error since no such key |\ref MDBX_CURRENT |Error \ref MDBX_NOTFOUND| 127 |Key exist → Update |\ref MDBX_CURRENT |Update value | 128 | _DELETING_||| 129 |Key is absent → Error since no such key |\ref mdbx_del() or \ref mdbx_replace()|Error \ref MDBX_NOTFOUND| 130 |Key exist → Delete by key |\ref mdbx_del() with the parameter `data = NULL`|Deletion| 131 |Key exist → Delete by key with with data matching check|\ref mdbx_del() with the parameter `data` filled with the value which should be match for deletion|Deletion or \ref MDBX_NOTFOUND if the value does not match| 132 |Delete at the current cursor position |\ref mdbx_cursor_del() with \ref MDBX_CURRENT flag|Deletion| 133 |Extract (read & delete) value by the key |\ref mdbx_replace() with zero flag and parameter `new_data = NULL`|Returning a deleted value| 134 135 136 ## Databases with NON-UNIQUE keys 137 138 In databases created with the \ref MDBX_DUPSORT (Sorted Duplicates) option, keys 139 may be non unique. Such non-unique keys in a key-value database may be treated 140 as a duplicates or as like a multiple values corresponds to keys. 141 142 143 | Case | Flags to use | Result | 144 |---------------------------------------------|---------------------|------------------------| 145 | _INSERTING_||| 146 |Key is absent → Insertion |\ref MDBX_NOOVERWRITE|Insertion| 147 |Key exist → Needn't to add new values |\ref MDBX_NOOVERWRITE|Error \ref MDBX_KEYEXIST with returning the first value from those already present| 148 | _UPSERTING_||| 149 |Key is absent → Insertion |\ref MDBX_UPSERT |Insertion| 150 |Key exist → Wanna to add new values |\ref MDBX_UPSERT |Add one more value to the key| 151 |Key exist → Replace all values with a new one|\ref MDBX_UPSERT + \ref MDBX_ALLDUPS|Overwrite by single new value| 152 | _UPDATING_||| 153 |Key is absent → Error since no such key |\ref MDBX_CURRENT |Error \ref MDBX_NOTFOUND| 154 |Key exist, Single value → Update |\ref MDBX_CURRENT |Update single value | 155 |Key exist, Multiple values → Replace all values with a new one|\ref MDBX_CURRENT + \ref MDBX_ALLDUPS|Overwrite by single new value| 156 |Key exist, Multiple values → Error since it is unclear which of the values should be updated|\ref mdbx_put() with \ref MDBX_CURRENT|Error \ref MDBX_EMULTIVAL| 157 |Key exist, Multiple values → Update particular entry of multi-value|\ref mdbx_replace() with \ref MDBX_CURRENT + \ref MDBX_NOOVERWRITE and the parameter `old_value` filled with the value that wanna to update|Update one multi-value entry| 158 |Key exist, Multiple values → Update the current entry of multi-value|\ref mdbx_cursor_put() with \ref MDBX_CURRENT|Update one multi-value entry| 159 | _DELETING_||| 160 |Key is absent → Error since no such key |\ref mdbx_del() or \ref mdbx_replace()|Error \ref MDBX_NOTFOUND| 161 |Key exist → Delete all values corresponds given key|\ref mdbx_del() with the parameter `data = NULL`|Deletion| 162 |Key exist → Delete particular value corresponds given key|\ref mdbx_del() with the parameter `data` filled with the value that wanna to delete, or \ref mdbx_replace() with \ref MDBX_CURRENT + \ref MDBX_NOOVERWRITE and the `old_value` parameter filled with the value that wanna to delete and `new_data = NULL`| Deletion or \ref MDBX_NOTFOUND if no such key-value pair| 163 |Delete one value at the current cursor position|\ref mdbx_cursor_del() with \ref MDBX_CURRENT flag|Deletion only the current entry| 164 |Delete all values of key at the current cursor position|\ref mdbx_cursor_del() with with \ref MDBX_ALLDUPS flag|Deletion all duplicates of key (all multi-values) at the current cursor position| 165 166 \defgroup c_cursors Cursors 167 \defgroup c_statinfo Statistics & Information 168 \defgroup c_settings Settings 169 \defgroup c_debug Logging and runtime debug 170 \defgroup c_rqest Range query estimation 171 \defgroup c_extra Extra operations 172 */ 173 /* *INDENT-ON* */ 174 /* clang-format on */ 175 176 #include <stdarg.h> 177 #include <stddef.h> 178 #include <stdint.h> 179 #if !defined(NDEBUG) && !defined(assert) 180 #include <assert.h> 181 #endif /* NDEBUG */ 182 183 #if defined(_WIN32) || defined(_WIN64) 184 #include <windows.h> 185 #include <winnt.h> 186 #ifndef __mode_t_defined 187 typedef unsigned short mdbx_mode_t; 188 #else 189 typedef mode_t mdbx_mode_t; 190 #endif /* __mode_t_defined */ 191 typedef HANDLE mdbx_filehandle_t; 192 typedef DWORD mdbx_pid_t; 193 typedef DWORD mdbx_tid_t; 194 #else /* Windows */ 195 #include <errno.h> /* for error codes */ 196 #include <pthread.h> /* for pthread_t */ 197 #include <sys/types.h> /* for pid_t */ 198 #include <sys/uio.h> /* for struct iovec */ 199 #define HAVE_STRUCT_IOVEC 1 200 typedef int mdbx_filehandle_t; 201 typedef pid_t mdbx_pid_t; 202 typedef pthread_t mdbx_tid_t; 203 typedef mode_t mdbx_mode_t; 204 #endif /* !Windows */ 205 206 #ifdef _MSC_VER 207 #pragma warning(pop) 208 #endif 209 210 /** end of c_api @} 211 * 212 * \defgroup api_macros Common Macros 213 * @{ */ 214 215 /*----------------------------------------------------------------------------*/ 216 217 #ifndef __has_attribute 218 #define __has_attribute(x) (0) 219 #endif /* __has_attribute */ 220 221 #ifndef __has_cpp_attribute 222 #define __has_cpp_attribute(x) 0 223 #endif /* __has_cpp_attribute */ 224 225 #ifndef __has_feature 226 #define __has_feature(x) (0) 227 #endif /* __has_feature */ 228 229 #ifndef __has_extension 230 #define __has_extension(x) (0) 231 #endif /* __has_extension */ 232 233 #ifndef __has_builtin 234 #define __has_builtin(x) (0) 235 #endif /* __has_builtin */ 236 237 /** \brief The 'pure' function attribute for optimization. 238 * \details Many functions have no effects except the return value and their 239 * return value depends only on the parameters and/or global variables. 240 * Such a function can be subject to common subexpression elimination 241 * and loop optimization just as an arithmetic operator would be. 242 * These functions should be declared with the attribute pure. */ 243 #if defined(DOXYGEN) 244 #define MDBX_PURE_FUNCTION [[gnu::pure]] 245 #elif (defined(__GNUC__) || __has_attribute(__pure__)) && \ 246 (!defined(__clang__) /* https://bugs.llvm.org/show_bug.cgi?id=43275 */ \ 247 || !defined(__cplusplus) || !__has_feature(cxx_exceptions)) 248 #define MDBX_PURE_FUNCTION __attribute__((__pure__)) 249 #elif defined(_MSC_VER) && !defined(__clang__) && _MSC_VER >= 1920 250 #define MDBX_PURE_FUNCTION 251 #elif defined(__cplusplus) && __has_cpp_attribute(gnu::pure) && \ 252 (!defined(__clang__) || !__has_feature(cxx_exceptions)) 253 #define MDBX_PURE_FUNCTION [[gnu::pure]] 254 #else 255 #define MDBX_PURE_FUNCTION 256 #endif /* MDBX_PURE_FUNCTION */ 257 258 /** \brief The 'pure nothrow' function attribute for optimization. 259 * \details Like \ref MDBX_PURE_FUNCTION with addition `noexcept` restriction 260 * that is compatible to CLANG and proposed [[pure]]. */ 261 #if defined(DOXYGEN) 262 #define MDBX_NOTHROW_PURE_FUNCTION [[gnu::pure, gnu::nothrow]] 263 #elif defined(__GNUC__) || \ 264 (__has_attribute(__pure__) && __has_attribute(__nothrow__)) 265 #define MDBX_NOTHROW_PURE_FUNCTION __attribute__((__pure__, __nothrow__)) 266 #elif defined(_MSC_VER) && !defined(__clang__) && _MSC_VER >= 1920 267 #if __has_cpp_attribute(pure) 268 #define MDBX_NOTHROW_PURE_FUNCTION [[pure]] 269 #else 270 #define MDBX_NOTHROW_PURE_FUNCTION 271 #endif 272 #elif defined(__cplusplus) && __has_cpp_attribute(gnu::pure) 273 #if __has_cpp_attribute(gnu::nothrow) 274 #define MDBX_NOTHROW_PURE_FUNCTION [[gnu::pure, gnu::nothrow]] 275 #else 276 #define MDBX_NOTHROW_PURE_FUNCTION [[gnu::pure]] 277 #endif 278 #elif defined(__cplusplus) && __has_cpp_attribute(pure) 279 #define MDBX_NOTHROW_PURE_FUNCTION [[pure]] 280 #else 281 #define MDBX_NOTHROW_PURE_FUNCTION 282 #endif /* MDBX_NOTHROW_PURE_FUNCTION */ 283 284 /** \brief The 'const' function attribute for optimization. 285 * \details Many functions do not examine any values except their arguments, 286 * and have no effects except the return value. Basically this is just 287 * slightly more strict class than the PURE attribute, since function 288 * is not allowed to read global memory. 289 * 290 * Note that a function that has pointer arguments and examines the 291 * data pointed to must not be declared const. Likewise, a function 292 * that calls a non-const function usually must not be const. 293 * It does not make sense for a const function to return void. */ 294 #if defined(DOXYGEN) 295 #define MDBX_CONST_FUNCTION [[gnu::const]] 296 #elif (defined(__GNUC__) || __has_attribute(__pure__)) && \ 297 (!defined(__clang__) /* https://bugs.llvm.org/show_bug.cgi?id=43275 */ \ 298 || !defined(__cplusplus) || !__has_feature(cxx_exceptions)) 299 #define MDBX_CONST_FUNCTION __attribute__((__const__)) 300 #elif defined(_MSC_VER) && !defined(__clang__) && _MSC_VER >= 1920 301 #define MDBX_CONST_FUNCTION MDBX_PURE_FUNCTION 302 #elif defined(__cplusplus) && __has_cpp_attribute(gnu::const) && \ 303 (!defined(__clang__) || !__has_feature(cxx_exceptions)) 304 #define MDBX_CONST_FUNCTION [[gnu::const]] 305 #else 306 #define MDBX_CONST_FUNCTION MDBX_PURE_FUNCTION 307 #endif /* MDBX_CONST_FUNCTION */ 308 309 /** \brief The 'const nothrow' function attribute for optimization. 310 * \details Like \ref MDBX_CONST_FUNCTION with addition `noexcept` restriction 311 * that is compatible to CLANG and future [[const]]. */ 312 #if defined(DOXYGEN) 313 #define MDBX_NOTHROW_CONST_FUNCTION [[gnu::const, gnu::nothrow]] 314 #elif defined(__GNUC__) || \ 315 (__has_attribute(__const__) && __has_attribute(__nothrow__)) 316 #define MDBX_NOTHROW_CONST_FUNCTION __attribute__((__const__, __nothrow__)) 317 #elif defined(_MSC_VER) && !defined(__clang__) && _MSC_VER >= 1920 318 #define MDBX_NOTHROW_CONST_FUNCTION MDBX_NOTHROW_PURE_FUNCTION 319 #elif defined(__cplusplus) && __has_cpp_attribute(gnu::const) 320 #if __has_cpp_attribute(gnu::nothrow) 321 #define MDBX_NOTHROW_PURE_FUNCTION [[gnu::const, gnu::nothrow]] 322 #else 323 #define MDBX_NOTHROW_PURE_FUNCTION [[gnu::const]] 324 #endif 325 #elif defined(__cplusplus) && __has_cpp_attribute(const) 326 #define MDBX_NOTHROW_CONST_FUNCTION [[const]] 327 #else 328 #define MDBX_NOTHROW_CONST_FUNCTION MDBX_NOTHROW_PURE_FUNCTION 329 #endif /* MDBX_NOTHROW_CONST_FUNCTION */ 330 331 /** \brief The 'deprecated' attribute to produce warnings when used. 332 * \note This macro may be predefined as empty to avoid "deprecated" warnings. 333 */ 334 #ifndef MDBX_DEPRECATED 335 #ifdef __deprecated 336 #define MDBX_DEPRECATED __deprecated 337 #elif defined(DOXYGEN) || \ 338 (defined(__cplusplus) && __cplusplus >= 201603L && \ 339 __has_cpp_attribute(maybe_unused) && \ 340 __has_cpp_attribute(maybe_unused) >= 201603L) || \ 341 (!defined(__cplusplus) && defined(__STDC_VERSION__) && \ 342 __STDC_VERSION__ > 202005L) 343 #define MDBX_DEPRECATED [[deprecated]] 344 #elif defined(__GNUC__) || __has_attribute(__deprecated__) 345 #define MDBX_DEPRECATED __attribute__((__deprecated__)) 346 #elif defined(_MSC_VER) 347 #define MDBX_DEPRECATED __declspec(deprecated) 348 #else 349 #define MDBX_DEPRECATED 350 #endif 351 #endif /* MDBX_DEPRECATED */ 352 353 #ifndef __dll_export 354 #if defined(_WIN32) || defined(_WIN64) || defined(__CYGWIN__) || \ 355 defined(__MINGW__) || defined(__MINGW32__) || defined(__MINGW64__) 356 #if defined(__GNUC__) || __has_attribute(__dllexport__) 357 #define __dll_export __attribute__((__dllexport__)) 358 #elif defined(_MSC_VER) 359 #define __dll_export __declspec(dllexport) 360 #else 361 #define __dll_export 362 #endif 363 #elif defined(__GNUC__) || __has_attribute(__visibility__) 364 #define __dll_export __attribute__((__visibility__("default"))) 365 #else 366 #define __dll_export 367 #endif 368 #endif /* __dll_export */ 369 370 #ifndef __dll_import 371 #if defined(_WIN32) || defined(_WIN64) || defined(__CYGWIN__) || \ 372 defined(__MINGW__) || defined(__MINGW32__) || defined(__MINGW64__) 373 #if defined(__GNUC__) || __has_attribute(__dllimport__) 374 #define __dll_import __attribute__((__dllimport__)) 375 #elif defined(_MSC_VER) 376 #define __dll_import __declspec(dllimport) 377 #else 378 #define __dll_import 379 #endif 380 #else 381 #define __dll_import 382 #endif 383 #endif /* __dll_import */ 384 385 /** \brief Auxiliary macro for robustly define the both inline version of API 386 * function and non-inline fallback dll-exported version for applications linked 387 * with old version of libmdbx, with a strictly ODR-common implementation. */ 388 #if defined(LIBMDBX_INTERNALS) && !defined(LIBMDBX_NO_EXPORTS_LEGACY_API) 389 #define LIBMDBX_INLINE_API(TYPE, NAME, ARGS) \ 390 /* proto of exported which uses common impl */ LIBMDBX_API TYPE NAME ARGS; \ 391 /* definition of common impl */ static __inline TYPE __inline_##NAME ARGS 392 #else 393 #define LIBMDBX_INLINE_API(TYPE, NAME, ARGS) static __inline TYPE NAME ARGS 394 #endif /* LIBMDBX_INLINE_API */ 395 396 /** \brief Converts a macro argument into a string constant. */ 397 #ifndef MDBX_STRINGIFY 398 #define MDBX_STRINGIFY_HELPER(x) #x 399 #define MDBX_STRINGIFY(x) MDBX_STRINGIFY_HELPER(x) 400 #endif /* MDBX_STRINGIFY */ 401 402 /*----------------------------------------------------------------------------*/ 403 404 #ifndef __cplusplus 405 #ifndef bool 406 #define bool _Bool 407 #endif 408 #ifndef true 409 #define true (1) 410 #endif 411 #ifndef false 412 #define false (0) 413 #endif 414 #endif /* bool without __cplusplus */ 415 416 /** Workaround for old compilers without support for C++17 `noexcept`. */ 417 #if defined(DOXYGEN) 418 #define MDBX_CXX17_NOEXCEPT noexcept 419 #elif !defined(__cpp_noexcept_function_type) || \ 420 __cpp_noexcept_function_type < 201510L 421 #define MDBX_CXX17_NOEXCEPT 422 #else 423 #define MDBX_CXX17_NOEXCEPT noexcept 424 #endif /* MDBX_CXX17_NOEXCEPT */ 425 426 /** Workaround for old compilers without support for any kind of `constexpr`. */ 427 #if defined(DOXYGEN) 428 #define MDBX_CXX01_CONSTEXPR constexpr 429 #define MDBX_CXX01_CONSTEXPR_VAR constexpr 430 #elif !defined(__cplusplus) 431 #define MDBX_CXX01_CONSTEXPR __inline 432 #define MDBX_CXX01_CONSTEXPR_VAR const 433 #elif !defined(DOXYGEN) && \ 434 ((__cplusplus < 201103L && defined(__cpp_constexpr) && \ 435 __cpp_constexpr < 200704L) || \ 436 (defined(__LCC__) && __LCC__ < 124) || \ 437 (defined(__GNUC__) && (__GNUC__ * 100 + __GNUC_MINOR__ < 407) && \ 438 !defined(__clang__) && !defined(__LCC__)) || \ 439 (defined(_MSC_VER) && _MSC_VER < 1910) || \ 440 (defined(__clang__) && __clang_major__ < 4)) 441 #define MDBX_CXX01_CONSTEXPR inline 442 #define MDBX_CXX01_CONSTEXPR_VAR const 443 #else 444 #define MDBX_CXX01_CONSTEXPR constexpr 445 #define MDBX_CXX01_CONSTEXPR_VAR constexpr 446 #endif /* MDBX_CXX01_CONSTEXPR */ 447 448 /** Workaround for old compilers without properly support for C++11 `constexpr`. 449 */ 450 #if defined(DOXYGEN) 451 #define MDBX_CXX11_CONSTEXPR constexpr 452 #define MDBX_CXX11_CONSTEXPR_VAR constexpr 453 #elif !defined(__cplusplus) 454 #define MDBX_CXX11_CONSTEXPR __inline 455 #define MDBX_CXX11_CONSTEXPR_VAR const 456 #elif !defined(DOXYGEN) && \ 457 (!defined(__cpp_constexpr) || __cpp_constexpr < 201304L || \ 458 (defined(__LCC__) && __LCC__ < 124) || \ 459 (defined(__GNUC__) && __GNUC__ < 6 && !defined(__clang__) && \ 460 !defined(__LCC__)) || \ 461 (defined(_MSC_VER) && _MSC_VER < 1910) || \ 462 (defined(__clang__) && __clang_major__ < 5)) 463 #define MDBX_CXX11_CONSTEXPR inline 464 #define MDBX_CXX11_CONSTEXPR_VAR const 465 #else 466 #define MDBX_CXX11_CONSTEXPR constexpr 467 #define MDBX_CXX11_CONSTEXPR_VAR constexpr 468 #endif /* MDBX_CXX11_CONSTEXPR */ 469 470 /** Workaround for old compilers without properly support for C++14 `constexpr`. 471 */ 472 #if defined(DOXYGEN) 473 #define MDBX_CXX14_CONSTEXPR constexpr 474 #define MDBX_CXX14_CONSTEXPR_VAR constexpr 475 #elif !defined(__cplusplus) 476 #define MDBX_CXX14_CONSTEXPR __inline 477 #define MDBX_CXX14_CONSTEXPR_VAR const 478 #elif defined(DOXYGEN) || \ 479 defined(__cpp_constexpr) && __cpp_constexpr >= 201304L && \ 480 ((defined(_MSC_VER) && _MSC_VER >= 1910) || \ 481 (defined(__clang__) && __clang_major__ > 4) || \ 482 (defined(__GNUC__) && __GNUC__ > 6) || \ 483 (!defined(__GNUC__) && !defined(__clang__) && !defined(_MSC_VER))) 484 #define MDBX_CXX14_CONSTEXPR constexpr 485 #define MDBX_CXX14_CONSTEXPR_VAR constexpr 486 #else 487 #define MDBX_CXX14_CONSTEXPR inline 488 #define MDBX_CXX14_CONSTEXPR_VAR const 489 #endif /* MDBX_CXX14_CONSTEXPR */ 490 491 #if defined(__noreturn) 492 #define MDBX_NORETURN __noreturn 493 #elif defined(_Noreturn) 494 #define MDBX_NORETURN _Noreturn 495 #elif defined(DOXYGEN) || (defined(__cplusplus) && __cplusplus >= 201103L) || \ 496 (!defined(__cplusplus) && defined(__STDC_VERSION__) && \ 497 __STDC_VERSION__ > 202005L) 498 #define MDBX_NORETURN [[noreturn]] 499 #elif defined(__GNUC__) || __has_attribute(__noreturn__) 500 #define MDBX_NORETURN __attribute__((__noreturn__)) 501 #elif defined(_MSC_VER) && !defined(__clang__) 502 #define MDBX_NORETURN __declspec(noreturn) 503 #else 504 #define MDBX_NORETURN 505 #endif /* MDBX_NORETURN */ 506 507 #ifndef MDBX_PRINTF_ARGS 508 #if defined(__GNUC__) || __has_attribute(__format__) || defined(DOXYGEN) 509 #if defined(__MINGW__) || defined(__MINGW32__) || defined(__MINGW64__) 510 #define MDBX_PRINTF_ARGS(format_index, first_arg) \ 511 __attribute__((__format__(__gnu_printf__, format_index, first_arg))) 512 #else 513 #define MDBX_PRINTF_ARGS(format_index, first_arg) \ 514 __attribute__((__format__(__printf__, format_index, first_arg))) 515 #endif /* MinGW */ 516 #else 517 #define MDBX_PRINTF_ARGS(format_index, first_arg) 518 #endif 519 #endif /* MDBX_PRINTF_ARGS */ 520 521 #if defined(DOXYGEN) || \ 522 (defined(__cplusplus) && __cplusplus >= 201603L && \ 523 __has_cpp_attribute(maybe_unused) && \ 524 __has_cpp_attribute(maybe_unused) >= 201603L) || \ 525 (!defined(__cplusplus) && defined(__STDC_VERSION__) && \ 526 __STDC_VERSION__ > 202005L) 527 #define MDBX_MAYBE_UNUSED [[maybe_unused]] 528 #elif defined(__GNUC__) || __has_attribute(__unused__) 529 #define MDBX_MAYBE_UNUSED __attribute__((__unused__)) 530 #else 531 #define MDBX_MAYBE_UNUSED 532 #endif /* MDBX_MAYBE_UNUSED */ 533 534 #if __has_attribute(no_sanitize) || defined(DOXYGEN) 535 #define MDBX_NOSANITIZE_ENUM __attribute((__no_sanitize__("enum"))) 536 #else 537 #define MDBX_NOSANITIZE_ENUM 538 #endif /* MDBX_NOSANITIZE_ENUM */ 539 540 /* Oh, below are some songs and dances since: 541 * - C++ requires explicit definition of the necessary operators. 542 * - the proper implementation of DEFINE_ENUM_FLAG_OPERATORS for C++ required 543 * the constexpr feature which is broken in most old compilers; 544 * - DEFINE_ENUM_FLAG_OPERATORS may be defined broken as in the Windows SDK. */ 545 #ifndef DEFINE_ENUM_FLAG_OPERATORS 546 547 #ifdef __cplusplus 548 #if !defined(__cpp_constexpr) || __cpp_constexpr < 200704L || \ 549 (defined(__LCC__) && __LCC__ < 124) || \ 550 (defined(__GNUC__) && (__GNUC__ * 100 + __GNUC_MINOR__ < 407) && \ 551 !defined(__clang__) && !defined(__LCC__)) || \ 552 (defined(_MSC_VER) && _MSC_VER < 1910) || \ 553 (defined(__clang__) && __clang_major__ < 4) 554 /* The constexpr feature is not available or (may be) broken */ 555 #define CONSTEXPR_ENUM_FLAGS_OPERATIONS 0 556 #else 557 /* C always allows these operators for enums */ 558 #define CONSTEXPR_ENUM_FLAGS_OPERATIONS 1 559 #endif /* __cpp_constexpr */ 560 561 /// Define operator overloads to enable bit operations on enum values that are 562 /// used to define flags (based on Microsoft's DEFINE_ENUM_FLAG_OPERATORS). 563 #define DEFINE_ENUM_FLAG_OPERATORS(ENUM) \ 564 extern "C++" { \ 565 MDBX_NOSANITIZE_ENUM MDBX_CXX01_CONSTEXPR ENUM operator|(ENUM a, ENUM b) { \ 566 return ENUM(unsigned(a) | unsigned(b)); \ 567 } \ 568 MDBX_NOSANITIZE_ENUM MDBX_CXX14_CONSTEXPR ENUM &operator|=(ENUM &a, \ 569 ENUM b) { \ 570 return a = a | b; \ 571 } \ 572 MDBX_NOSANITIZE_ENUM MDBX_CXX01_CONSTEXPR ENUM operator&(ENUM a, ENUM b) { \ 573 return ENUM(unsigned(a) & unsigned(b)); \ 574 } \ 575 MDBX_NOSANITIZE_ENUM MDBX_CXX01_CONSTEXPR ENUM operator&(ENUM a, \ 576 unsigned b) { \ 577 return ENUM(unsigned(a) & b); \ 578 } \ 579 MDBX_NOSANITIZE_ENUM MDBX_CXX01_CONSTEXPR ENUM operator&(unsigned a, \ 580 ENUM b) { \ 581 return ENUM(a & unsigned(b)); \ 582 } \ 583 MDBX_NOSANITIZE_ENUM MDBX_CXX14_CONSTEXPR ENUM &operator&=(ENUM &a, \ 584 ENUM b) { \ 585 return a = a & b; \ 586 } \ 587 MDBX_NOSANITIZE_ENUM MDBX_CXX14_CONSTEXPR ENUM &operator&=(ENUM &a, \ 588 unsigned b) { \ 589 return a = a & b; \ 590 } \ 591 MDBX_CXX01_CONSTEXPR unsigned operator~(ENUM a) { return ~unsigned(a); } \ 592 MDBX_NOSANITIZE_ENUM MDBX_CXX01_CONSTEXPR ENUM operator^(ENUM a, ENUM b) { \ 593 return ENUM(unsigned(a) ^ unsigned(b)); \ 594 } \ 595 MDBX_NOSANITIZE_ENUM MDBX_CXX14_CONSTEXPR ENUM &operator^=(ENUM &a, \ 596 ENUM b) { \ 597 return a = a ^ b; \ 598 } \ 599 } 600 #else /* __cplusplus */ 601 /* nope for C since it always allows these operators for enums */ 602 #define DEFINE_ENUM_FLAG_OPERATORS(ENUM) 603 #define CONSTEXPR_ENUM_FLAGS_OPERATIONS 1 604 #endif /* !__cplusplus */ 605 606 #elif !defined(CONSTEXPR_ENUM_FLAGS_OPERATIONS) 607 608 #ifdef __cplusplus 609 /* DEFINE_ENUM_FLAG_OPERATORS may be defined broken as in the Windows SDK */ 610 #define CONSTEXPR_ENUM_FLAGS_OPERATIONS 0 611 #else 612 /* C always allows these operators for enums */ 613 #define CONSTEXPR_ENUM_FLAGS_OPERATIONS 1 614 #endif 615 616 #endif /* DEFINE_ENUM_FLAG_OPERATORS */ 617 618 /** end of api_macros @} */ 619 620 /*----------------------------------------------------------------------------*/ 621 622 /** \addtogroup c_api 623 * @{ */ 624 625 #ifdef __cplusplus 626 extern "C" { 627 #endif 628 629 /* MDBX version 0.12.x */ 630 #define MDBX_VERSION_MAJOR 0 631 #define MDBX_VERSION_MINOR 12 632 633 #ifndef LIBMDBX_API 634 #if defined(LIBMDBX_EXPORTS) 635 #define LIBMDBX_API __dll_export 636 #elif defined(LIBMDBX_IMPORTS) 637 #define LIBMDBX_API __dll_import 638 #else 639 #define LIBMDBX_API 640 #endif 641 #endif /* LIBMDBX_API */ 642 643 #ifdef __cplusplus 644 #if defined(__clang__) || __has_attribute(type_visibility) 645 #define LIBMDBX_API_TYPE LIBMDBX_API __attribute__((type_visibility("default"))) 646 #else 647 #define LIBMDBX_API_TYPE LIBMDBX_API 648 #endif 649 #else 650 #define LIBMDBX_API_TYPE 651 #endif /* LIBMDBX_API_TYPE */ 652 653 #if defined(LIBMDBX_IMPORTS) 654 #define LIBMDBX_VERINFO_API __dll_import 655 #else 656 #define LIBMDBX_VERINFO_API __dll_export 657 #endif /* LIBMDBX_VERINFO_API */ 658 659 /** \brief libmdbx version information */ 660 extern LIBMDBX_VERINFO_API const struct MDBX_version_info { 661 uint8_t major; /**< Major version number */ 662 uint8_t minor; /**< Minor version number */ 663 uint16_t release; /**< Release number of Major.Minor */ 664 uint32_t revision; /**< Revision number of Release */ 665 struct { 666 const char *datetime; /**< committer date, strict ISO-8601 format */ 667 const char *tree; /**< commit hash (hexadecimal digits) */ 668 const char *commit; /**< tree hash, i.e. digest of the source code */ 669 const char *describe; /**< git-describe string */ 670 } git; /**< source information from git */ 671 const char *sourcery; /**< sourcery anchor for pinning */ 672 } /** \brief libmdbx version information */ mdbx_version; 673 674 /** \brief libmdbx build information 675 * \attention Some strings could be NULL in case no corresponding information 676 * was provided at build time (i.e. flags). */ 677 extern LIBMDBX_VERINFO_API const struct MDBX_build_info { 678 const char *datetime; /**< build timestamp (ISO-8601 or __DATE__ __TIME__) */ 679 const char *target; /**< cpu/arch-system-config triplet */ 680 const char *options; /**< mdbx-related options */ 681 const char *compiler; /**< compiler */ 682 const char *flags; /**< CFLAGS and CXXFLAGS */ 683 } /** \brief libmdbx build information */ mdbx_build; 684 685 #if (defined(_WIN32) || defined(_WIN64)) && !MDBX_BUILD_SHARED_LIBRARY 686 /* MDBX internally uses global and thread local storage destructors to 687 * automatically (de)initialization, releasing reader lock table slots 688 * and so on. 689 * 690 * If MDBX builded as a DLL this is done out-of-the-box by DllEntry() function, 691 * which called automatically by Windows core with passing corresponding reason 692 * argument. 693 * 694 * Otherwise, if MDBX was builded not as a DLL, some black magic 695 * may be required depending of Windows version: 696 * 697 * - Modern Windows versions, including Windows Vista and later, provides 698 * support for "TLS Directory" (e.g .CRT$XL[A-Z] sections in executable 699 * or dll file). In this case, MDBX capable of doing all automatically, 700 * therefore you DON'T NEED to call mdbx_module_handler() 701 * so the MDBX_MANUAL_MODULE_HANDLER defined as 0. 702 * 703 * - Obsolete versions of Windows, prior to Windows Vista, REQUIRES calling 704 * mdbx_module_handler() manually from corresponding DllMain() or WinMain() 705 * of your DLL or application, 706 * so the MDBX_MANUAL_MODULE_HANDLER defined as 1. 707 * 708 * Therefore, building MDBX as a DLL is recommended for all version of Windows. 709 * So, if you doubt, just build MDBX as the separate DLL and don't care about 710 * the MDBX_MANUAL_MODULE_HANDLER. */ 711 712 #ifndef _WIN32_WINNT 713 #error Non-dll build libmdbx requires target Windows version \ 714 to be explicitly defined via _WIN32_WINNT for properly \ 715 handling thread local storage destructors. 716 #endif /* _WIN32_WINNT */ 717 718 #if _WIN32_WINNT >= 0x0600 /* Windows Vista */ 719 /* As described above mdbx_module_handler() is NOT needed for Windows Vista 720 * and later. */ 721 #define MDBX_MANUAL_MODULE_HANDLER 0 722 #else 723 /* As described above mdbx_module_handler() IS REQUIRED for Windows versions 724 * prior to Windows Vista. */ 725 #define MDBX_MANUAL_MODULE_HANDLER 1 726 void LIBMDBX_API NTAPI mdbx_module_handler(PVOID module, DWORD reason, 727 PVOID reserved); 728 #endif 729 730 #endif /* Windows && !DLL && MDBX_MANUAL_MODULE_HANDLER */ 731 732 /* OPACITY STRUCTURES *********************************************************/ 733 734 /** \brief Opaque structure for a database environment. 735 * \details An environment supports multiple key-value sub-databases (aka 736 * key-value spaces or tables), all residing in the same shared-memory map. 737 * \see mdbx_env_create() \see mdbx_env_close() */ 738 #ifndef __cplusplus 739 typedef struct MDBX_env MDBX_env; 740 #else 741 struct MDBX_env; 742 #endif 743 744 /** \brief Opaque structure for a transaction handle. 745 * \ingroup c_transactions 746 * \details All database operations require a transaction handle. Transactions 747 * may be read-only or read-write. 748 * \see mdbx_txn_begin() \see mdbx_txn_commit() \see mdbx_txn_abort() */ 749 #ifndef __cplusplus 750 typedef struct MDBX_txn MDBX_txn; 751 #else 752 struct MDBX_txn; 753 #endif 754 755 /** \brief A handle for an individual database (key-value spaces) in the 756 * environment. 757 * \ingroup c_dbi 758 * \details Zero handle is used internally (hidden Garbage Collection subDB). 759 * So, any valid DBI-handle great than 0 and less than or equal 760 * \ref MDBX_MAX_DBI. 761 * \see mdbx_dbi_open() \see mdbx_dbi_close() */ 762 typedef uint32_t MDBX_dbi; 763 764 /** \brief Opaque structure for navigating through a database 765 * \ingroup c_cursors 766 * \see mdbx_cursor_create() \see mdbx_cursor_bind() \see mdbx_cursor_close() 767 */ 768 #ifndef __cplusplus 769 typedef struct MDBX_cursor MDBX_cursor; 770 #else 771 struct MDBX_cursor; 772 #endif 773 774 /** \brief Generic structure used for passing keys and data in and out of the 775 * database. 776 * \anchor MDBX_val \see mdbx::slice \see mdbx::buffer 777 * 778 * \details Values returned from the database are valid only until a subsequent 779 * update operation, or the end of the transaction. Do not modify or 780 * free them, they commonly point into the database itself. 781 * 782 * Key sizes must be between 0 and \ref mdbx_env_get_maxkeysize() inclusive. 783 * The same applies to data sizes in databases with the \ref MDBX_DUPSORT flag. 784 * Other data items can in theory be from 0 to \ref MDBX_MAXDATASIZE bytes long. 785 * 786 * \note The notable difference between MDBX and LMDB is that MDBX support zero 787 * length keys. */ 788 #ifndef HAVE_STRUCT_IOVEC 789 struct iovec { 790 void *iov_base; /**< pointer to some data */ 791 size_t iov_len; /**< the length of data in bytes */ 792 }; 793 #define HAVE_STRUCT_IOVEC 794 #endif /* HAVE_STRUCT_IOVEC */ 795 796 #if defined(__sun) || defined(__SVR4) || defined(__svr4__) 797 /* The `iov_len` is signed on Sun/Solaris. 798 * So define custom MDBX_val to avoid a lot of warnings. */ 799 struct MDBX_val { 800 void *iov_base; /**< pointer to some data */ 801 size_t iov_len; /**< the length of data in bytes */ 802 }; 803 #ifndef __cplusplus 804 typedef struct MDBX_val MDBX_val; 805 #endif 806 #else /* SunOS */ 807 typedef struct iovec MDBX_val; 808 #endif /* ! SunOS */ 809 810 enum MDBX_constants { 811 /** The hard limit for DBI handles */ 812 MDBX_MAX_DBI = UINT32_C(32765), 813 814 /** The maximum size of a data item. */ 815 MDBX_MAXDATASIZE = UINT32_C(0x7fff0000), 816 817 /** The minimal database page size in bytes. */ 818 MDBX_MIN_PAGESIZE = 256, 819 820 /** The maximal database page size in bytes. */ 821 MDBX_MAX_PAGESIZE = 65536, 822 }; 823 824 /* THE FILES ******************************************************************* 825 * At the file system level, the environment corresponds to a pair of files. */ 826 827 #ifndef MDBX_LOCKNAME 828 /** \brief The name of the lock file in the environment 829 * without using \ref MDBX_NOSUBDIR */ 830 #if !(defined(_WIN32) || defined(_WIN64)) 831 #define MDBX_LOCKNAME "/mdbx.lck" 832 #else 833 #define MDBX_LOCKNAME L"\\mdbx.lck" 834 #endif 835 #endif /* MDBX_LOCKNAME */ 836 #ifndef MDBX_DATANAME 837 /** \brief The name of the data file in the environment 838 * without using \ref MDBX_NOSUBDIR */ 839 #if !(defined(_WIN32) || defined(_WIN64)) 840 #define MDBX_DATANAME "/mdbx.dat" 841 #else 842 #define MDBX_DATANAME L"\\mdbx.dat" 843 #endif 844 #endif /* MDBX_DATANAME */ 845 846 #ifndef MDBX_LOCK_SUFFIX 847 /** \brief The suffix of the lock file when \ref MDBX_NOSUBDIR is used */ 848 #if !(defined(_WIN32) || defined(_WIN64)) 849 #define MDBX_LOCK_SUFFIX "-lck" 850 #else 851 #define MDBX_LOCK_SUFFIX L"-lck" 852 #endif 853 #endif /* MDBX_LOCK_SUFFIX */ 854 855 /* DEBUG & LOGGING ************************************************************/ 856 857 /** \addtogroup c_debug 858 * \note Most of debug feature enabled only when libmdbx builded with 859 * \ref MDBX_DEBUG build option. @{ */ 860 861 /** Log level 862 * \note Levels detailed than (great than) \ref MDBX_LOG_NOTICE 863 * requires build libmdbx with \ref MDBX_DEBUG option. */ 864 enum MDBX_log_level_t { 865 /** Critical conditions, i.e. assertion failures. 866 * \note libmdbx always produces such messages regardless 867 * of \ref MDBX_DEBUG build option. */ 868 MDBX_LOG_FATAL = 0, 869 870 /** Enables logging for error conditions 871 * and \ref MDBX_LOG_FATAL. 872 * \note libmdbx always produces such messages regardless 873 * of \ref MDBX_DEBUG build option. */ 874 MDBX_LOG_ERROR = 1, 875 876 /** Enables logging for warning conditions 877 * and \ref MDBX_LOG_ERROR ... \ref MDBX_LOG_FATAL. 878 * \note libmdbx always produces such messages regardless 879 * of \ref MDBX_DEBUG build option. */ 880 MDBX_LOG_WARN = 2, 881 882 /** Enables logging for normal but significant condition 883 * and \ref MDBX_LOG_WARN ... \ref MDBX_LOG_FATAL. 884 * \note libmdbx always produces such messages regardless 885 * of \ref MDBX_DEBUG build option. */ 886 MDBX_LOG_NOTICE = 3, 887 888 /** Enables logging for verbose informational 889 * and \ref MDBX_LOG_NOTICE ... \ref MDBX_LOG_FATAL. 890 * \note Requires build libmdbx with \ref MDBX_DEBUG option. */ 891 MDBX_LOG_VERBOSE = 4, 892 893 /** Enables logging for debug-level messages 894 * and \ref MDBX_LOG_VERBOSE ... \ref MDBX_LOG_FATAL. 895 * \note Requires build libmdbx with \ref MDBX_DEBUG option. */ 896 MDBX_LOG_DEBUG = 5, 897 898 /** Enables logging for trace debug-level messages 899 * and \ref MDBX_LOG_DEBUG ... \ref MDBX_LOG_FATAL. 900 * \note Requires build libmdbx with \ref MDBX_DEBUG option. */ 901 MDBX_LOG_TRACE = 6, 902 903 /** Enables extra debug-level messages (dump pgno lists) 904 * and all other log-messages. 905 * \note Requires build libmdbx with \ref MDBX_DEBUG option. */ 906 MDBX_LOG_EXTRA = 7, 907 908 #ifdef ENABLE_UBSAN 909 MDBX_LOG_MAX = 7 /* avoid UBSAN false-positive trap by a tests */, 910 #endif /* ENABLE_UBSAN */ 911 912 /** for \ref mdbx_setup_debug() only: Don't change current settings */ 913 MDBX_LOG_DONTCHANGE = -1 914 }; 915 #ifndef __cplusplus 916 typedef enum MDBX_log_level_t MDBX_log_level_t; 917 #endif 918 919 /** \brief Runtime debug flags 920 * 921 * \details `MDBX_DBG_DUMP` and `MDBX_DBG_LEGACY_MULTIOPEN` always have an 922 * effect, but `MDBX_DBG_ASSERT`, `MDBX_DBG_AUDIT` and `MDBX_DBG_JITTER` only if 923 * libmdbx builded with \ref MDBX_DEBUG. */ 924 enum MDBX_debug_flags_t { 925 MDBX_DBG_NONE = 0, 926 927 /** Enable assertion checks. 928 * \note Always enabled for builds with `MDBX_FORCE_ASSERTIONS` option, 929 * otherwise requires build with \ref MDBX_DEBUG > 0 */ 930 MDBX_DBG_ASSERT = 1, 931 932 /** Enable pages usage audit at commit transactions. 933 * \note Requires build with \ref MDBX_DEBUG > 0 */ 934 MDBX_DBG_AUDIT = 2, 935 936 /** Enable small random delays in critical points. 937 * \note Requires build with \ref MDBX_DEBUG > 0 */ 938 MDBX_DBG_JITTER = 4, 939 940 /** Include or not meta-pages in coredump files. 941 * \note May affect performance in \ref MDBX_WRITEMAP mode */ 942 MDBX_DBG_DUMP = 8, 943 944 /** Allow multi-opening environment(s) */ 945 MDBX_DBG_LEGACY_MULTIOPEN = 16, 946 947 /** Allow read and write transactions overlapping for the same thread. */ 948 MDBX_DBG_LEGACY_OVERLAP = 32, 949 950 /** Don't auto-upgrade format signature. 951 * \note However a new write transactions will use and store 952 * the last signature regardless this flag */ 953 MDBX_DBG_DONT_UPGRADE = 64, 954 955 #ifdef ENABLE_UBSAN 956 MDBX_DBG_MAX = ((unsigned)MDBX_LOG_MAX) << 16 | 957 127 /* avoid UBSAN false-positive trap by a tests */, 958 #endif /* ENABLE_UBSAN */ 959 960 /** for mdbx_setup_debug() only: Don't change current settings */ 961 MDBX_DBG_DONTCHANGE = -1 962 }; 963 #ifndef __cplusplus 964 typedef enum MDBX_debug_flags_t MDBX_debug_flags_t; 965 #else 966 DEFINE_ENUM_FLAG_OPERATORS(MDBX_debug_flags_t) 967 #endif 968 969 /** \brief A debug-logger callback function, 970 * called before printing the message and aborting. 971 * \see mdbx_setup_debug() 972 * 973 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 974 * \param [in] msg The assertion message, not including newline. */ 975 typedef void MDBX_debug_func(MDBX_log_level_t loglevel, const char *function, 976 int line, const char *fmt, 977 va_list args) MDBX_CXX17_NOEXCEPT; 978 979 /** \brief The "don't change `logger`" value for mdbx_setup_debug() */ 980 #define MDBX_LOGGER_DONTCHANGE ((MDBX_debug_func *)(intptr_t)-1) 981 982 /** \brief Setup global log-level, debug options and debug logger. 983 * \returns The previously `debug_flags` in the 0-15 bits 984 * and `log_level` in the 16-31 bits. */ 985 LIBMDBX_API int mdbx_setup_debug(MDBX_log_level_t log_level, 986 MDBX_debug_flags_t debug_flags, 987 MDBX_debug_func *logger); 988 989 /** \brief A callback function for most MDBX assert() failures, 990 * called before printing the message and aborting. 991 * \see mdbx_env_set_assert() 992 * 993 * \param [in] env An environment handle returned by mdbx_env_create(). 994 * \param [in] msg The assertion message, not including newline. */ 995 typedef void MDBX_assert_func(const MDBX_env *env, const char *msg, 996 const char *function, 997 unsigned line) MDBX_CXX17_NOEXCEPT; 998 999 /** \brief Set or reset the assert() callback of the environment. 1000 * 1001 * Does nothing if libmdbx was built with MDBX_DEBUG=0 or with NDEBUG, 1002 * and will return `MDBX_ENOSYS` in such case. 1003 * 1004 * \param [in] env An environment handle returned by mdbx_env_create(). 1005 * \param [in] func An MDBX_assert_func function, or 0. 1006 * 1007 * \returns A non-zero error value on failure and 0 on success. */ 1008 LIBMDBX_API int mdbx_env_set_assert(MDBX_env *env, MDBX_assert_func *func); 1009 1010 /** \brief Dump given MDBX_val to the buffer 1011 * 1012 * Dumps it as string if value is printable (all bytes in the range 0x20..0x7E), 1013 * otherwise made hexadecimal dump. Requires at least 4 byte length buffer. 1014 * 1015 * \returns One of: 1016 * - NULL if given buffer size less than 4 bytes; 1017 * - pointer to constant string if given value NULL or empty; 1018 * - otherwise pointer to given buffer. */ 1019 LIBMDBX_API const char *mdbx_dump_val(const MDBX_val *key, char *const buf, 1020 const size_t bufsize); 1021 1022 /** \brief Panics with message and causes abnormal process termination. */ 1023 LIBMDBX_API void mdbx_panic(const char *fmt, ...) MDBX_PRINTF_ARGS(1, 2); 1024 1025 /** \brief Panics with asserton failed message and causes abnormal process 1026 * termination. */ 1027 LIBMDBX_API void mdbx_assert_fail(const MDBX_env *env, const char *msg, 1028 const char *func, unsigned line); 1029 /** end of c_debug @} */ 1030 1031 /** \brief Environment flags 1032 * \ingroup c_opening 1033 * \anchor env_flags 1034 * \see mdbx_env_open() \see mdbx_env_set_flags() */ 1035 enum MDBX_env_flags_t { 1036 MDBX_ENV_DEFAULTS = 0, 1037 1038 /** Extra validation of DB structure and pages content. 1039 * 1040 * The `MDBX_VALIDATION` enabled the simple safe/careful mode for working 1041 * with damaged or untrusted DB. However, a notable performance 1042 * degradation should be expected. */ 1043 MDBX_VALIDATION = UINT32_C(0x00002000), 1044 1045 /** No environment directory. 1046 * 1047 * By default, MDBX creates its environment in a directory whose pathname is 1048 * given in path, and creates its data and lock files under that directory. 1049 * With this option, path is used as-is for the database main data file. 1050 * The database lock file is the path with "-lck" appended. 1051 * 1052 * - with `MDBX_NOSUBDIR` = in a filesystem we have the pair of MDBX-files 1053 * which names derived from given pathname by appending predefined suffixes. 1054 * 1055 * - without `MDBX_NOSUBDIR` = in a filesystem we have the MDBX-directory with 1056 * given pathname, within that a pair of MDBX-files with predefined names. 1057 * 1058 * This flag affects only at new environment creating by \ref mdbx_env_open(), 1059 * otherwise at opening an existing environment libmdbx will choice this 1060 * automatically. */ 1061 MDBX_NOSUBDIR = UINT32_C(0x4000), 1062 1063 /** Read only mode. 1064 * 1065 * Open the environment in read-only mode. No write operations will be 1066 * allowed. MDBX will still modify the lock file - except on read-only 1067 * filesystems, where MDBX does not use locks. 1068 * 1069 * - with `MDBX_RDONLY` = open environment in read-only mode. 1070 * MDBX supports pure read-only mode (i.e. without opening LCK-file) only 1071 * when environment directory and/or both files are not writable (and the 1072 * LCK-file may be missing). In such case allowing file(s) to be placed 1073 * on a network read-only share. 1074 * 1075 * - without `MDBX_RDONLY` = open environment in read-write mode. 1076 * 1077 * This flag affects only at environment opening but can't be changed after. 1078 */ 1079 MDBX_RDONLY = UINT32_C(0x20000), 1080 1081 /** Open environment in exclusive/monopolistic mode. 1082 * 1083 * `MDBX_EXCLUSIVE` flag can be used as a replacement for `MDB_NOLOCK`, 1084 * which don't supported by MDBX. 1085 * In this way, you can get the minimal overhead, but with the correct 1086 * multi-process and multi-thread locking. 1087 * 1088 * - with `MDBX_EXCLUSIVE` = open environment in exclusive/monopolistic mode 1089 * or return \ref MDBX_BUSY if environment already used by other process. 1090 * The main feature of the exclusive mode is the ability to open the 1091 * environment placed on a network share. 1092 * 1093 * - without `MDBX_EXCLUSIVE` = open environment in cooperative mode, 1094 * i.e. for multi-process access/interaction/cooperation. 1095 * The main requirements of the cooperative mode are: 1096 * 1097 * 1. data files MUST be placed in the LOCAL file system, 1098 * but NOT on a network share. 1099 * 2. environment MUST be opened only by LOCAL processes, 1100 * but NOT over a network. 1101 * 3. OS kernel (i.e. file system and memory mapping implementation) and 1102 * all processes that open the given environment MUST be running 1103 * in the physically single RAM with cache-coherency. The only 1104 * exception for cache-consistency requirement is Linux on MIPS 1105 * architecture, but this case has not been tested for a long time). 1106 * 1107 * This flag affects only at environment opening but can't be changed after. 1108 */ 1109 MDBX_EXCLUSIVE = UINT32_C(0x400000), 1110 1111 /** Using database/environment which already opened by another process(es). 1112 * 1113 * The `MDBX_ACCEDE` flag is useful to avoid \ref MDBX_INCOMPATIBLE error 1114 * while opening the database/environment which is already used by another 1115 * process(es) with unknown mode/flags. In such cases, if there is a 1116 * difference in the specified flags (\ref MDBX_NOMETASYNC, 1117 * \ref MDBX_SAFE_NOSYNC, \ref MDBX_UTTERLY_NOSYNC, \ref MDBX_LIFORECLAIM 1118 * and \ref MDBX_NORDAHEAD), instead of returning an error, 1119 * the database will be opened in a compatibility with the already used mode. 1120 * 1121 * `MDBX_ACCEDE` has no effect if the current process is the only one either 1122 * opening the DB in read-only mode or other process(es) uses the DB in 1123 * read-only mode. */ 1124 MDBX_ACCEDE = UINT32_C(0x40000000), 1125 1126 /** Map data into memory with write permission. 1127 * 1128 * Use a writeable memory map unless \ref MDBX_RDONLY is set. This uses fewer 1129 * mallocs and requires much less work for tracking database pages, but 1130 * loses protection from application bugs like wild pointer writes and other 1131 * bad updates into the database. This may be slightly faster for DBs that 1132 * fit entirely in RAM, but is slower for DBs larger than RAM. Also adds the 1133 * possibility for stray application writes thru pointers to silently 1134 * corrupt the database. 1135 * 1136 * - with `MDBX_WRITEMAP` = all data will be mapped into memory in the 1137 * read-write mode. This offers a significant performance benefit, since the 1138 * data will be modified directly in mapped memory and then flushed to disk 1139 * by single system call, without any memory management nor copying. 1140 * 1141 * - without `MDBX_WRITEMAP` = data will be mapped into memory in the 1142 * read-only mode. This requires stocking all modified database pages in 1143 * memory and then writing them to disk through file operations. 1144 * 1145 * \warning On the other hand, `MDBX_WRITEMAP` adds the possibility for stray 1146 * application writes thru pointers to silently corrupt the database. 1147 * 1148 * \note The `MDBX_WRITEMAP` mode is incompatible with nested transactions, 1149 * since this is unreasonable. I.e. nested transactions requires mallocation 1150 * of database pages and more work for tracking ones, which neuters a 1151 * performance boost caused by the `MDBX_WRITEMAP` mode. 1152 * 1153 * This flag affects only at environment opening but can't be changed after. 1154 */ 1155 MDBX_WRITEMAP = UINT32_C(0x80000), 1156 1157 /** Tie reader locktable slots to read-only transactions 1158 * instead of to threads. 1159 * 1160 * Don't use Thread-Local Storage, instead tie reader locktable slots to 1161 * \ref MDBX_txn objects instead of to threads. So, \ref mdbx_txn_reset() 1162 * keeps the slot reserved for the \ref MDBX_txn object. A thread may use 1163 * parallel read-only transactions. And a read-only transaction may span 1164 * threads if you synchronizes its use. 1165 * 1166 * Applications that multiplex many user threads over individual OS threads 1167 * need this option. Such an application must also serialize the write 1168 * transactions in an OS thread, since MDBX's write locking is unaware of 1169 * the user threads. 1170 * 1171 * \note Regardless to `MDBX_NOTLS` flag a write transaction entirely should 1172 * always be used in one thread from start to finish. MDBX checks this in a 1173 * reasonable manner and return the \ref MDBX_THREAD_MISMATCH error in rules 1174 * violation. 1175 * 1176 * This flag affects only at environment opening but can't be changed after. 1177 */ 1178 MDBX_NOTLS = UINT32_C(0x200000), 1179 1180 /** Don't do readahead. 1181 * 1182 * Turn off readahead. Most operating systems perform readahead on read 1183 * requests by default. This option turns it off if the OS supports it. 1184 * Turning it off may help random read performance when the DB is larger 1185 * than RAM and system RAM is full. 1186 * 1187 * By default libmdbx dynamically enables/disables readahead depending on 1188 * the actual database size and currently available memory. On the other 1189 * hand, such automation has some limitation, i.e. could be performed only 1190 * when DB size changing but can't tracks and reacts changing a free RAM 1191 * availability, since it changes independently and asynchronously. 1192 * 1193 * \note The mdbx_is_readahead_reasonable() function allows to quickly find 1194 * out whether to use readahead or not based on the size of the data and the 1195 * amount of available memory. 1196 * 1197 * This flag affects only at environment opening and can't be changed after. 1198 */ 1199 MDBX_NORDAHEAD = UINT32_C(0x800000), 1200 1201 /** Don't initialize malloc'ed memory before writing to datafile. 1202 * 1203 * Don't initialize malloc'ed memory before writing to unused spaces in the 1204 * data file. By default, memory for pages written to the data file is 1205 * obtained using malloc. While these pages may be reused in subsequent 1206 * transactions, freshly malloc'ed pages will be initialized to zeroes before 1207 * use. This avoids persisting leftover data from other code (that used the 1208 * heap and subsequently freed the memory) into the data file. 1209 * 1210 * Note that many other system libraries may allocate and free memory from 1211 * the heap for arbitrary uses. E.g., stdio may use the heap for file I/O 1212 * buffers. This initialization step has a modest performance cost so some 1213 * applications may want to disable it using this flag. This option can be a 1214 * problem for applications which handle sensitive data like passwords, and 1215 * it makes memory checkers like Valgrind noisy. This flag is not needed 1216 * with \ref MDBX_WRITEMAP, which writes directly to the mmap instead of using 1217 * malloc for pages. The initialization is also skipped if \ref MDBX_RESERVE 1218 * is used; the caller is expected to overwrite all of the memory that was 1219 * reserved in that case. 1220 * 1221 * This flag may be changed at any time using `mdbx_env_set_flags()`. */ 1222 MDBX_NOMEMINIT = UINT32_C(0x1000000), 1223 1224 /** Aims to coalesce a Garbage Collection items. 1225 * \note Always enabled since v0.12 1226 * 1227 * With `MDBX_COALESCE` flag MDBX will aims to coalesce items while recycling 1228 * a Garbage Collection. Technically, when possible short lists of pages 1229 * will be combined into longer ones, but to fit on one database page. As a 1230 * result, there will be fewer items in Garbage Collection and a page lists 1231 * are longer, which slightly increases the likelihood of returning pages to 1232 * Unallocated space and reducing the database file. 1233 * 1234 * This flag may be changed at any time using mdbx_env_set_flags(). */ 1235 MDBX_COALESCE = UINT32_C(0x2000000), 1236 1237 /** LIFO policy for recycling a Garbage Collection items. 1238 * 1239 * `MDBX_LIFORECLAIM` flag turns on LIFO policy for recycling a Garbage 1240 * Collection items, instead of FIFO by default. On systems with a disk 1241 * write-back cache, this can significantly increase write performance, up 1242 * to several times in a best case scenario. 1243 * 1244 * LIFO recycling policy means that for reuse pages will be taken which became 1245 * unused the lastest (i.e. just now or most recently). Therefore the loop of 1246 * database pages circulation becomes as short as possible. In other words, 1247 * the number of pages, that are overwritten in memory and on disk during a 1248 * series of write transactions, will be as small as possible. Thus creates 1249 * ideal conditions for the efficient operation of the disk write-back cache. 1250 * 1251 * \ref MDBX_LIFORECLAIM is compatible with all no-sync flags, but gives NO 1252 * noticeable impact in combination with \ref MDBX_SAFE_NOSYNC or 1253 * \ref MDBX_UTTERLY_NOSYNC. Because MDBX will reused pages only before the 1254 * last "steady" MVCC-snapshot, i.e. the loop length of database pages 1255 * circulation will be mostly defined by frequency of calling 1256 * \ref mdbx_env_sync() rather than LIFO and FIFO difference. 1257 * 1258 * This flag may be changed at any time using mdbx_env_set_flags(). */ 1259 MDBX_LIFORECLAIM = UINT32_C(0x4000000), 1260 1261 /** Debugging option, fill/perturb released pages. */ 1262 MDBX_PAGEPERTURB = UINT32_C(0x8000000), 1263 1264 /* SYNC MODES****************************************************************/ 1265 /** \defgroup sync_modes SYNC MODES 1266 * 1267 * \attention Using any combination of \ref MDBX_SAFE_NOSYNC, \ref 1268 * MDBX_NOMETASYNC and especially \ref MDBX_UTTERLY_NOSYNC is always a deal to 1269 * reduce durability for gain write performance. You must know exactly what 1270 * you are doing and what risks you are taking! 1271 * 1272 * \note for LMDB users: \ref MDBX_SAFE_NOSYNC is NOT similar to LMDB_NOSYNC, 1273 * but \ref MDBX_UTTERLY_NOSYNC is exactly match LMDB_NOSYNC. See details 1274 * below. 1275 * 1276 * THE SCENE: 1277 * - The DAT-file contains several MVCC-snapshots of B-tree at same time, 1278 * each of those B-tree has its own root page. 1279 * - Each of meta pages at the beginning of the DAT file contains a 1280 * pointer to the root page of B-tree which is the result of the particular 1281 * transaction, and a number of this transaction. 1282 * - For data durability, MDBX must first write all MVCC-snapshot data 1283 * pages and ensure that are written to the disk, then update a meta page 1284 * with the new transaction number and a pointer to the corresponding new 1285 * root page, and flush any buffers yet again. 1286 * - Thus during commit a I/O buffers should be flushed to the disk twice; 1287 * i.e. fdatasync(), FlushFileBuffers() or similar syscall should be 1288 * called twice for each commit. This is very expensive for performance, 1289 * but guaranteed durability even on unexpected system failure or power 1290 * outage. Of course, provided that the operating system and the 1291 * underlying hardware (e.g. disk) work correctly. 1292 * 1293 * TRADE-OFF: 1294 * By skipping some stages described above, you can significantly benefit in 1295 * speed, while partially or completely losing in the guarantee of data 1296 * durability and/or consistency in the event of system or power failure. 1297 * Moreover, if for any reason disk write order is not preserved, then at 1298 * moment of a system crash, a meta-page with a pointer to the new B-tree may 1299 * be written to disk, while the itself B-tree not yet. In that case, the 1300 * database will be corrupted! 1301 * 1302 * \see MDBX_SYNC_DURABLE \see MDBX_NOMETASYNC \see MDBX_SAFE_NOSYNC 1303 * \see MDBX_UTTERLY_NOSYNC 1304 * 1305 * @{ */ 1306 1307 /** Default robust and durable sync mode. 1308 * 1309 * Metadata is written and flushed to disk after a data is written and 1310 * flushed, which guarantees the integrity of the database in the event 1311 * of a crash at any time. 1312 * 1313 * \attention Please do not use other modes until you have studied all the 1314 * details and are sure. Otherwise, you may lose your users' data, as happens 1315 * in [Miranda NG](https://www.miranda-ng.org/) messenger. */ 1316 MDBX_SYNC_DURABLE = 0, 1317 1318 /** Don't sync the meta-page after commit. 1319 * 1320 * Flush system buffers to disk only once per transaction commit, omit the 1321 * metadata flush. Defer that until the system flushes files to disk, 1322 * or next non-\ref MDBX_RDONLY commit or \ref mdbx_env_sync(). Depending on 1323 * the platform and hardware, with \ref MDBX_NOMETASYNC you may get a doubling 1324 * of write performance. 1325 * 1326 * This trade-off maintains database integrity, but a system crash may 1327 * undo the last committed transaction. I.e. it preserves the ACI 1328 * (atomicity, consistency, isolation) but not D (durability) database 1329 * property. 1330 * 1331 * `MDBX_NOMETASYNC` flag may be changed at any time using 1332 * \ref mdbx_env_set_flags() or by passing to \ref mdbx_txn_begin() for 1333 * particular write transaction. \see sync_modes */ 1334 MDBX_NOMETASYNC = UINT32_C(0x40000), 1335 1336 /** Don't sync anything but keep previous steady commits. 1337 * 1338 * Like \ref MDBX_UTTERLY_NOSYNC the `MDBX_SAFE_NOSYNC` flag disable similarly 1339 * flush system buffers to disk when committing a transaction. But there is a 1340 * huge difference in how are recycled the MVCC snapshots corresponding to 1341 * previous "steady" transactions (see below). 1342 * 1343 * With \ref MDBX_WRITEMAP the `MDBX_SAFE_NOSYNC` instructs MDBX to use 1344 * asynchronous mmap-flushes to disk. Asynchronous mmap-flushes means that 1345 * actually all writes will scheduled and performed by operation system on it 1346 * own manner, i.e. unordered. MDBX itself just notify operating system that 1347 * it would be nice to write data to disk, but no more. 1348 * 1349 * Depending on the platform and hardware, with `MDBX_SAFE_NOSYNC` you may get 1350 * a multiple increase of write performance, even 10 times or more. 1351 * 1352 * In contrast to \ref MDBX_UTTERLY_NOSYNC mode, with `MDBX_SAFE_NOSYNC` flag 1353 * MDBX will keeps untouched pages within B-tree of the last transaction 1354 * "steady" which was synced to disk completely. This has big implications for 1355 * both data durability and (unfortunately) performance: 1356 * - a system crash can't corrupt the database, but you will lose the last 1357 * transactions; because MDBX will rollback to last steady commit since it 1358 * kept explicitly. 1359 * - the last steady transaction makes an effect similar to "long-lived" read 1360 * transaction (see above in the \ref restrictions section) since prevents 1361 * reuse of pages freed by newer write transactions, thus the any data 1362 * changes will be placed in newly allocated pages. 1363 * - to avoid rapid database growth, the system will sync data and issue 1364 * a steady commit-point to resume reuse pages, each time there is 1365 * insufficient space and before increasing the size of the file on disk. 1366 * 1367 * In other words, with `MDBX_SAFE_NOSYNC` flag MDBX insures you from the 1368 * whole database corruption, at the cost increasing database size and/or 1369 * number of disk IOPs. So, `MDBX_SAFE_NOSYNC` flag could be used with 1370 * \ref mdbx_env_sync() as alternatively for batch committing or nested 1371 * transaction (in some cases). As well, auto-sync feature exposed by 1372 * \ref mdbx_env_set_syncbytes() and \ref mdbx_env_set_syncperiod() functions 1373 * could be very useful with `MDBX_SAFE_NOSYNC` flag. 1374 * 1375 * The number and volume of of disk IOPs with MDBX_SAFE_NOSYNC flag will 1376 * exactly the as without any no-sync flags. However, you should expect a 1377 * larger process's [work set](https://bit.ly/2kA2tFX) and significantly worse 1378 * a [locality of reference](https://bit.ly/2mbYq2J), due to the more 1379 * intensive allocation of previously unused pages and increase the size of 1380 * the database. 1381 * 1382 * `MDBX_SAFE_NOSYNC` flag may be changed at any time using 1383 * \ref mdbx_env_set_flags() or by passing to \ref mdbx_txn_begin() for 1384 * particular write transaction. */ 1385 MDBX_SAFE_NOSYNC = UINT32_C(0x10000), 1386 1387 /** \deprecated Please use \ref MDBX_SAFE_NOSYNC instead of `MDBX_MAPASYNC`. 1388 * 1389 * Since version 0.9.x the `MDBX_MAPASYNC` is deprecated and has the same 1390 * effect as \ref MDBX_SAFE_NOSYNC with \ref MDBX_WRITEMAP. This just API 1391 * simplification is for convenience and clarity. */ 1392 MDBX_MAPASYNC = MDBX_SAFE_NOSYNC, 1393 1394 /** Don't sync anything and wipe previous steady commits. 1395 * 1396 * Don't flush system buffers to disk when committing a transaction. This 1397 * optimization means a system crash can corrupt the database, if buffers are 1398 * not yet flushed to disk. Depending on the platform and hardware, with 1399 * `MDBX_UTTERLY_NOSYNC` you may get a multiple increase of write performance, 1400 * even 100 times or more. 1401 * 1402 * If the filesystem preserves write order (which is rare and never provided 1403 * unless explicitly noted) and the \ref MDBX_WRITEMAP and \ref 1404 * MDBX_LIFORECLAIM flags are not used, then a system crash can't corrupt the 1405 * database, but you can lose the last transactions, if at least one buffer is 1406 * not yet flushed to disk. The risk is governed by how often the system 1407 * flushes dirty buffers to disk and how often \ref mdbx_env_sync() is called. 1408 * So, transactions exhibit ACI (atomicity, consistency, isolation) properties 1409 * and only lose `D` (durability). I.e. database integrity is maintained, but 1410 * a system crash may undo the final transactions. 1411 * 1412 * Otherwise, if the filesystem not preserves write order (which is 1413 * typically) or \ref MDBX_WRITEMAP or \ref MDBX_LIFORECLAIM flags are used, 1414 * you should expect the corrupted database after a system crash. 1415 * 1416 * So, most important thing about `MDBX_UTTERLY_NOSYNC`: 1417 * - a system crash immediately after commit the write transaction 1418 * high likely lead to database corruption. 1419 * - successful completion of mdbx_env_sync(force = true) after one or 1420 * more committed transactions guarantees consistency and durability. 1421 * - BUT by committing two or more transactions you back database into 1422 * a weak state, in which a system crash may lead to database corruption! 1423 * In case single transaction after mdbx_env_sync, you may lose transaction 1424 * itself, but not a whole database. 1425 * 1426 * Nevertheless, `MDBX_UTTERLY_NOSYNC` provides "weak" durability in case 1427 * of an application crash (but no durability on system failure), and 1428 * therefore may be very useful in scenarios where data durability is 1429 * not required over a system failure (e.g for short-lived data), or if you 1430 * can take such risk. 1431 * 1432 * `MDBX_UTTERLY_NOSYNC` flag may be changed at any time using 1433 * \ref mdbx_env_set_flags(), but don't has effect if passed to 1434 * \ref mdbx_txn_begin() for particular write transaction. \see sync_modes */ 1435 MDBX_UTTERLY_NOSYNC = MDBX_SAFE_NOSYNC | UINT32_C(0x100000), 1436 1437 /** end of sync_modes @} */ 1438 }; 1439 #ifndef __cplusplus 1440 /** \ingroup c_opening */ 1441 typedef enum MDBX_env_flags_t MDBX_env_flags_t; 1442 #else 1443 DEFINE_ENUM_FLAG_OPERATORS(MDBX_env_flags_t) 1444 #endif 1445 1446 /** Transaction flags 1447 * \ingroup c_transactions 1448 * \anchor txn_flags 1449 * \see mdbx_txn_begin() \see mdbx_txn_flags() */ 1450 enum MDBX_txn_flags_t { 1451 /** Start read-write transaction. 1452 * 1453 * Only one write transaction may be active at a time. Writes are fully 1454 * serialized, which guarantees that writers can never deadlock. */ 1455 MDBX_TXN_READWRITE = 0, 1456 1457 /** Start read-only transaction. 1458 * 1459 * There can be multiple read-only transactions simultaneously that do not 1460 * block each other and a write transactions. */ 1461 MDBX_TXN_RDONLY = MDBX_RDONLY, 1462 1463 /** Prepare but not start read-only transaction. 1464 * 1465 * Transaction will not be started immediately, but created transaction handle 1466 * will be ready for use with \ref mdbx_txn_renew(). This flag allows to 1467 * preallocate memory and assign a reader slot, thus avoiding these operations 1468 * at the next start of the transaction. */ 1469 #if CONSTEXPR_ENUM_FLAGS_OPERATIONS || defined(DOXYGEN) 1470 MDBX_TXN_RDONLY_PREPARE = MDBX_RDONLY | MDBX_NOMEMINIT, 1471 #else 1472 MDBX_TXN_RDONLY_PREPARE = uint32_t(MDBX_RDONLY) | uint32_t(MDBX_NOMEMINIT), 1473 #endif 1474 1475 /** Do not block when starting a write transaction. */ 1476 MDBX_TXN_TRY = UINT32_C(0x10000000), 1477 1478 /** Exactly the same as \ref MDBX_NOMETASYNC, 1479 * but for this transaction only. */ 1480 MDBX_TXN_NOMETASYNC = MDBX_NOMETASYNC, 1481 1482 /** Exactly the same as \ref MDBX_SAFE_NOSYNC, 1483 * but for this transaction only. */ 1484 MDBX_TXN_NOSYNC = MDBX_SAFE_NOSYNC, 1485 1486 /* Transaction state flags ---------------------------------------------- */ 1487 1488 /** Transaction is invalid. 1489 * \note Transaction state flag. Returned from \ref mdbx_txn_flags() 1490 * but can't be used with \ref mdbx_txn_begin(). */ 1491 MDBX_TXN_INVALID = INT32_MIN, 1492 1493 /** Transaction is finished or never began. 1494 * \note Transaction state flag. Returned from \ref mdbx_txn_flags() 1495 * but can't be used with \ref mdbx_txn_begin(). */ 1496 MDBX_TXN_FINISHED = 0x01, 1497 1498 /** Transaction is unusable after an error. 1499 * \note Transaction state flag. Returned from \ref mdbx_txn_flags() 1500 * but can't be used with \ref mdbx_txn_begin(). */ 1501 MDBX_TXN_ERROR = 0x02, 1502 1503 /** Transaction must write, even if dirty list is empty. 1504 * \note Transaction state flag. Returned from \ref mdbx_txn_flags() 1505 * but can't be used with \ref mdbx_txn_begin(). */ 1506 MDBX_TXN_DIRTY = 0x04, 1507 1508 /** Transaction or a parent has spilled pages. 1509 * \note Transaction state flag. Returned from \ref mdbx_txn_flags() 1510 * but can't be used with \ref mdbx_txn_begin(). */ 1511 MDBX_TXN_SPILLS = 0x08, 1512 1513 /** Transaction has a nested child transaction. 1514 * \note Transaction state flag. Returned from \ref mdbx_txn_flags() 1515 * but can't be used with \ref mdbx_txn_begin(). */ 1516 MDBX_TXN_HAS_CHILD = 0x10, 1517 1518 /** Most operations on the transaction are currently illegal. 1519 * \note Transaction state flag. Returned from \ref mdbx_txn_flags() 1520 * but can't be used with \ref mdbx_txn_begin(). */ 1521 MDBX_TXN_BLOCKED = MDBX_TXN_FINISHED | MDBX_TXN_ERROR | MDBX_TXN_HAS_CHILD 1522 }; 1523 #ifndef __cplusplus 1524 typedef enum MDBX_txn_flags_t MDBX_txn_flags_t; 1525 #else 1526 DEFINE_ENUM_FLAG_OPERATORS(MDBX_txn_flags_t) 1527 #endif 1528 1529 /** \brief Database flags 1530 * \ingroup c_dbi 1531 * \anchor db_flags 1532 * \see mdbx_dbi_open() */ 1533 enum MDBX_db_flags_t { 1534 /** Variable length unique keys with usual byte-by-byte string comparison. */ 1535 MDBX_DB_DEFAULTS = 0, 1536 1537 /** Use reverse string comparison for keys. */ 1538 MDBX_REVERSEKEY = UINT32_C(0x02), 1539 1540 /** Use sorted duplicates, i.e. allow multi-values for a keys. */ 1541 MDBX_DUPSORT = UINT32_C(0x04), 1542 1543 /** Numeric keys in native byte order either uint32_t or uint64_t 1544 * (must be one of uint32_t or uint64_t, other integer types, for example, 1545 * signed integer or uint16_t will not work). 1546 * The keys must all be of the same size and must be aligned while passing as 1547 * arguments. */ 1548 MDBX_INTEGERKEY = UINT32_C(0x08), 1549 1550 /** With \ref MDBX_DUPSORT; sorted dup items have fixed size. The data values 1551 * must all be of the same size. */ 1552 MDBX_DUPFIXED = UINT32_C(0x10), 1553 1554 /** With \ref MDBX_DUPSORT and with \ref MDBX_DUPFIXED; dups are fixed size 1555 * like \ref MDBX_INTEGERKEY -style integers. The data values must all be of 1556 * the same size and must be aligned while passing as arguments. */ 1557 MDBX_INTEGERDUP = UINT32_C(0x20), 1558 1559 /** With \ref MDBX_DUPSORT; use reverse string comparison for data values. */ 1560 MDBX_REVERSEDUP = UINT32_C(0x40), 1561 1562 /** Create DB if not already existing. */ 1563 MDBX_CREATE = UINT32_C(0x40000), 1564 1565 /** Opens an existing sub-database created with unknown flags. 1566 * 1567 * The `MDBX_DB_ACCEDE` flag is intend to open a existing sub-database which 1568 * was created with unknown flags (\ref MDBX_REVERSEKEY, \ref MDBX_DUPSORT, 1569 * \ref MDBX_INTEGERKEY, \ref MDBX_DUPFIXED, \ref MDBX_INTEGERDUP and 1570 * \ref MDBX_REVERSEDUP). 1571 * 1572 * In such cases, instead of returning the \ref MDBX_INCOMPATIBLE error, the 1573 * sub-database will be opened with flags which it was created, and then an 1574 * application could determine the actual flags by \ref mdbx_dbi_flags(). */ 1575 MDBX_DB_ACCEDE = MDBX_ACCEDE 1576 }; 1577 #ifndef __cplusplus 1578 /** \ingroup c_dbi */ 1579 typedef enum MDBX_db_flags_t MDBX_db_flags_t; 1580 #else 1581 DEFINE_ENUM_FLAG_OPERATORS(MDBX_db_flags_t) 1582 #endif 1583 1584 /** \brief Data changing flags 1585 * \ingroup c_crud 1586 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations" 1587 * \see mdbx_put() \see mdbx_cursor_put() \see mdbx_replace() */ 1588 enum MDBX_put_flags_t { 1589 /** Upsertion by default (without any other flags) */ 1590 MDBX_UPSERT = 0, 1591 1592 /** For insertion: Don't write if the key already exists. */ 1593 MDBX_NOOVERWRITE = UINT32_C(0x10), 1594 1595 /** Has effect only for \ref MDBX_DUPSORT databases. 1596 * For upsertion: don't write if the key-value pair already exist. 1597 * For deletion: remove all values for key. */ 1598 MDBX_NODUPDATA = UINT32_C(0x20), 1599 1600 /** For upsertion: overwrite the current key/data pair. 1601 * MDBX allows this flag for \ref mdbx_put() for explicit overwrite/update 1602 * without insertion. 1603 * For deletion: remove only single entry at the current cursor position. */ 1604 MDBX_CURRENT = UINT32_C(0x40), 1605 1606 /** Has effect only for \ref MDBX_DUPSORT databases. 1607 * For deletion: remove all multi-values (aka duplicates) for given key. 1608 * For upsertion: replace all multi-values for given key with a new one. */ 1609 MDBX_ALLDUPS = UINT32_C(0x80), 1610 1611 /** For upsertion: Just reserve space for data, don't copy it. 1612 * Return a pointer to the reserved space. */ 1613 MDBX_RESERVE = UINT32_C(0x10000), 1614 1615 /** Data is being appended. 1616 * Don't split full pages, continue on a new instead. */ 1617 MDBX_APPEND = UINT32_C(0x20000), 1618 1619 /** Has effect only for \ref MDBX_DUPSORT databases. 1620 * Duplicate data is being appended. 1621 * Don't split full pages, continue on a new instead. */ 1622 MDBX_APPENDDUP = UINT32_C(0x40000), 1623 1624 /** Only for \ref MDBX_DUPFIXED. 1625 * Store multiple data items in one call. */ 1626 MDBX_MULTIPLE = UINT32_C(0x80000) 1627 }; 1628 #ifndef __cplusplus 1629 /** \ingroup c_crud */ 1630 typedef enum MDBX_put_flags_t MDBX_put_flags_t; 1631 #else 1632 DEFINE_ENUM_FLAG_OPERATORS(MDBX_put_flags_t) 1633 #endif 1634 1635 /** \brief Environment copy flags 1636 * \ingroup c_extra 1637 * \see mdbx_env_copy() \see mdbx_env_copy2fd() */ 1638 enum MDBX_copy_flags_t { 1639 MDBX_CP_DEFAULTS = 0, 1640 1641 /** Copy with compactification: Omit free space from copy and renumber all 1642 * pages sequentially */ 1643 MDBX_CP_COMPACT = 1u, 1644 1645 /** Force to make resizeable copy, i.e. dynamic size instead of fixed */ 1646 MDBX_CP_FORCE_DYNAMIC_SIZE = 2u 1647 }; 1648 #ifndef __cplusplus 1649 /** \ingroup c_extra */ 1650 typedef enum MDBX_copy_flags_t MDBX_copy_flags_t; 1651 #else 1652 DEFINE_ENUM_FLAG_OPERATORS(MDBX_copy_flags_t) 1653 #endif 1654 1655 /** \brief Cursor operations 1656 * \ingroup c_cursors 1657 * This is the set of all operations for retrieving data using a cursor. 1658 * \see mdbx_cursor_get() */ 1659 enum MDBX_cursor_op { 1660 /** Position at first key/data item */ 1661 MDBX_FIRST, 1662 1663 /** \ref MDBX_DUPSORT -only: Position at first data item of current key. */ 1664 MDBX_FIRST_DUP, 1665 1666 /** \ref MDBX_DUPSORT -only: Position at key/data pair. */ 1667 MDBX_GET_BOTH, 1668 1669 /** \ref MDBX_DUPSORT -only: Position at given key and at first data greater 1670 * than or equal to specified data. */ 1671 MDBX_GET_BOTH_RANGE, 1672 1673 /** Return key/data at current cursor position */ 1674 MDBX_GET_CURRENT, 1675 1676 /** \ref MDBX_DUPFIXED -only: Return up to a page of duplicate data items 1677 * from current cursor position. Move cursor to prepare 1678 * for \ref MDBX_NEXT_MULTIPLE. */ 1679 MDBX_GET_MULTIPLE, 1680 1681 /** Position at last key/data item */ 1682 MDBX_LAST, 1683 1684 /** \ref MDBX_DUPSORT -only: Position at last data item of current key. */ 1685 MDBX_LAST_DUP, 1686 1687 /** Position at next data item */ 1688 MDBX_NEXT, 1689 1690 /** \ref MDBX_DUPSORT -only: Position at next data item of current key. */ 1691 MDBX_NEXT_DUP, 1692 1693 /** \ref MDBX_DUPFIXED -only: Return up to a page of duplicate data items 1694 * from next cursor position. Move cursor to prepare 1695 * for `MDBX_NEXT_MULTIPLE`. */ 1696 MDBX_NEXT_MULTIPLE, 1697 1698 /** Position at first data item of next key */ 1699 MDBX_NEXT_NODUP, 1700 1701 /** Position at previous data item */ 1702 MDBX_PREV, 1703 1704 /** \ref MDBX_DUPSORT -only: Position at previous data item of current key. */ 1705 MDBX_PREV_DUP, 1706 1707 /** Position at last data item of previous key */ 1708 MDBX_PREV_NODUP, 1709 1710 /** Position at specified key */ 1711 MDBX_SET, 1712 1713 /** Position at specified key, return both key and data */ 1714 MDBX_SET_KEY, 1715 1716 /** Position at first key greater than or equal to specified key. */ 1717 MDBX_SET_RANGE, 1718 1719 /** \ref MDBX_DUPFIXED -only: Position at previous page and return up to 1720 * a page of duplicate data items. */ 1721 MDBX_PREV_MULTIPLE, 1722 1723 /** Positions cursor at first key-value pair greater than or equal to 1724 * specified, return both key and data, and the return code depends on whether 1725 * a exact match. 1726 * 1727 * For non DUPSORT-ed collections this work the same to \ref MDBX_SET_RANGE, 1728 * but returns \ref MDBX_SUCCESS if key found exactly or 1729 * \ref MDBX_RESULT_TRUE if greater key was found. 1730 * 1731 * For DUPSORT-ed a data value is taken into account for duplicates, 1732 * i.e. for a pairs/tuples of a key and an each data value of duplicates. 1733 * Returns \ref MDBX_SUCCESS if key-value pair found exactly or 1734 * \ref MDBX_RESULT_TRUE if the next pair was returned. */ 1735 MDBX_SET_LOWERBOUND, 1736 1737 /** Positions cursor at first key-value pair greater than specified, 1738 * return both key and data, and the return code depends on whether a 1739 * upper-bound was found. 1740 * 1741 * For non DUPSORT-ed collections this work the same to \ref MDBX_SET_RANGE, 1742 * but returns \ref MDBX_SUCCESS if the greater key was found or 1743 * \ref MDBX_NOTFOUND otherwise. 1744 * 1745 * For DUPSORT-ed a data value is taken into account for duplicates, 1746 * i.e. for a pairs/tuples of a key and an each data value of duplicates. 1747 * Returns \ref MDBX_SUCCESS if the greater pair was returned or 1748 * \ref MDBX_NOTFOUND otherwise. */ 1749 MDBX_SET_UPPERBOUND 1750 }; 1751 #ifndef __cplusplus 1752 /** \ingroup c_cursors */ 1753 typedef enum MDBX_cursor_op MDBX_cursor_op; 1754 #endif 1755 1756 /** \brief Errors and return codes 1757 * \ingroup c_err 1758 * 1759 * BerkeleyDB uses -30800 to -30999, we'll go under them 1760 * \see mdbx_strerror() \see mdbx_strerror_r() \see mdbx_liberr2str() */ 1761 enum MDBX_error_t { 1762 /** Successful result */ 1763 MDBX_SUCCESS = 0, 1764 1765 /** Alias for \ref MDBX_SUCCESS */ 1766 MDBX_RESULT_FALSE = MDBX_SUCCESS, 1767 1768 /** Successful result with special meaning or a flag */ 1769 MDBX_RESULT_TRUE = -1, 1770 1771 /** key/data pair already exists */ 1772 MDBX_KEYEXIST = -30799, 1773 1774 /** The first LMDB-compatible defined error code */ 1775 MDBX_FIRST_LMDB_ERRCODE = MDBX_KEYEXIST, 1776 1777 /** key/data pair not found (EOF) */ 1778 MDBX_NOTFOUND = -30798, 1779 1780 /** Requested page not found - this usually indicates corruption */ 1781 MDBX_PAGE_NOTFOUND = -30797, 1782 1783 /** Database is corrupted (page was wrong type and so on) */ 1784 MDBX_CORRUPTED = -30796, 1785 1786 /** Environment had fatal error, 1787 * i.e. update of meta page failed and so on. */ 1788 MDBX_PANIC = -30795, 1789 1790 /** DB file version mismatch with libmdbx */ 1791 MDBX_VERSION_MISMATCH = -30794, 1792 1793 /** File is not a valid MDBX file */ 1794 MDBX_INVALID = -30793, 1795 1796 /** Environment mapsize reached */ 1797 MDBX_MAP_FULL = -30792, 1798 1799 /** Environment maxdbs reached */ 1800 MDBX_DBS_FULL = -30791, 1801 1802 /** Environment maxreaders reached */ 1803 MDBX_READERS_FULL = -30790, 1804 1805 /** Transaction has too many dirty pages, i.e transaction too big */ 1806 MDBX_TXN_FULL = -30788, 1807 1808 /** Cursor stack too deep - this usually indicates corruption, 1809 * i.e branch-pages loop */ 1810 MDBX_CURSOR_FULL = -30787, 1811 1812 /** Page has not enough space - internal error */ 1813 MDBX_PAGE_FULL = -30786, 1814 1815 /** Database engine was unable to extend mapping, e.g. since address space 1816 * is unavailable or busy. This can mean: 1817 * - Database size extended by other process beyond to environment mapsize 1818 * and engine was unable to extend mapping while starting read 1819 * transaction. Environment should be reopened to continue. 1820 * - Engine was unable to extend mapping during write transaction 1821 * or explicit call of \ref mdbx_env_set_geometry(). */ 1822 MDBX_UNABLE_EXTEND_MAPSIZE = -30785, 1823 1824 /** Environment or database is not compatible with the requested operation 1825 * or the specified flags. This can mean: 1826 * - The operation expects an \ref MDBX_DUPSORT / \ref MDBX_DUPFIXED 1827 * database. 1828 * - Opening a named DB when the unnamed DB has \ref MDBX_DUPSORT / 1829 * \ref MDBX_INTEGERKEY. 1830 * - Accessing a data record as a database, or vice versa. 1831 * - The database was dropped and recreated with different flags. */ 1832 MDBX_INCOMPATIBLE = -30784, 1833 1834 /** Invalid reuse of reader locktable slot, 1835 * e.g. read-transaction already run for current thread */ 1836 MDBX_BAD_RSLOT = -30783, 1837 1838 /** Transaction is not valid for requested operation, 1839 * e.g. had errored and be must aborted, has a child, or is invalid */ 1840 MDBX_BAD_TXN = -30782, 1841 1842 /** Invalid size or alignment of key or data for target database, 1843 * either invalid subDB name */ 1844 MDBX_BAD_VALSIZE = -30781, 1845 1846 /** The specified DBI-handle is invalid 1847 * or changed by another thread/transaction */ 1848 MDBX_BAD_DBI = -30780, 1849 1850 /** Unexpected internal error, transaction should be aborted */ 1851 MDBX_PROBLEM = -30779, 1852 1853 /** The last LMDB-compatible defined error code */ 1854 MDBX_LAST_LMDB_ERRCODE = MDBX_PROBLEM, 1855 1856 /** Another write transaction is running or environment is already used while 1857 * opening with \ref MDBX_EXCLUSIVE flag */ 1858 MDBX_BUSY = -30778, 1859 1860 /** The first of MDBX-added error codes */ 1861 MDBX_FIRST_ADDED_ERRCODE = MDBX_BUSY, 1862 1863 /** The specified key has more than one associated value */ 1864 MDBX_EMULTIVAL = -30421, 1865 1866 /** Bad signature of a runtime object(s), this can mean: 1867 * - memory corruption or double-free; 1868 * - ABI version mismatch (rare case); */ 1869 MDBX_EBADSIGN = -30420, 1870 1871 /** Database should be recovered, but this could NOT be done for now 1872 * since it opened in read-only mode */ 1873 MDBX_WANNA_RECOVERY = -30419, 1874 1875 /** The given key value is mismatched to the current cursor position */ 1876 MDBX_EKEYMISMATCH = -30418, 1877 1878 /** Database is too large for current system, 1879 * e.g. could NOT be mapped into RAM. */ 1880 MDBX_TOO_LARGE = -30417, 1881 1882 /** A thread has attempted to use a not owned object, 1883 * e.g. a transaction that started by another thread. */ 1884 MDBX_THREAD_MISMATCH = -30416, 1885 1886 /** Overlapping read and write transactions for the current thread */ 1887 MDBX_TXN_OVERLAPPING = -30415, 1888 1889 /* The last of MDBX-added error codes */ 1890 MDBX_LAST_ADDED_ERRCODE = MDBX_TXN_OVERLAPPING, 1891 1892 #if defined(_WIN32) || defined(_WIN64) 1893 MDBX_ENODATA = ERROR_HANDLE_EOF, 1894 MDBX_EINVAL = ERROR_INVALID_PARAMETER, 1895 MDBX_EACCESS = ERROR_ACCESS_DENIED, 1896 MDBX_ENOMEM = ERROR_OUTOFMEMORY, 1897 MDBX_EROFS = ERROR_FILE_READ_ONLY, 1898 MDBX_ENOSYS = ERROR_NOT_SUPPORTED, 1899 MDBX_EIO = ERROR_WRITE_FAULT, 1900 MDBX_EPERM = ERROR_INVALID_FUNCTION, 1901 MDBX_EINTR = ERROR_CANCELLED, 1902 MDBX_ENOFILE = ERROR_FILE_NOT_FOUND, 1903 MDBX_EREMOTE = ERROR_REMOTE_STORAGE_MEDIA_ERROR 1904 #else /* Windows */ 1905 #ifdef ENODATA 1906 MDBX_ENODATA = ENODATA, 1907 #else 1908 MDBX_ENODATA = 9919 /* for compatibility with LLVM's C++ libraries/headers */, 1909 #endif /* ENODATA */ 1910 MDBX_EINVAL = EINVAL, 1911 MDBX_EACCESS = EACCES, 1912 MDBX_ENOMEM = ENOMEM, 1913 MDBX_EROFS = EROFS, 1914 MDBX_ENOSYS = ENOSYS, 1915 MDBX_EIO = EIO, 1916 MDBX_EPERM = EPERM, 1917 MDBX_EINTR = EINTR, 1918 MDBX_ENOFILE = ENOENT, 1919 MDBX_EREMOTE = ENOTBLK 1920 #endif /* !Windows */ 1921 }; 1922 #ifndef __cplusplus 1923 /** \ingroup c_err */ 1924 typedef enum MDBX_error_t MDBX_error_t; 1925 #endif 1926 1927 /** MDBX_MAP_RESIZED 1928 * \ingroup c_err 1929 * \deprecated Please review your code to use MDBX_UNABLE_EXTEND_MAPSIZE 1930 * instead. */ 1931 MDBX_DEPRECATED static __inline int MDBX_MAP_RESIZED_is_deprecated(void) { 1932 return MDBX_UNABLE_EXTEND_MAPSIZE; 1933 } 1934 #define MDBX_MAP_RESIZED MDBX_MAP_RESIZED_is_deprecated() 1935 1936 /** \brief Return a string describing a given error code. 1937 * \ingroup c_err 1938 * 1939 * This function is a superset of the ANSI C X3.159-1989 (ANSI C) `strerror()` 1940 * function. If the error code is greater than or equal to 0, then the string 1941 * returned by the system function `strerror()` is returned. If the error code 1942 * is less than 0, an error string corresponding to the MDBX library error is 1943 * returned. See errors for a list of MDBX-specific error codes. 1944 * 1945 * `mdbx_strerror()` is NOT thread-safe because may share common internal buffer 1946 * for system messages. The returned string must NOT be modified by the 1947 * application, but MAY be modified by a subsequent call to 1948 * \ref mdbx_strerror(), `strerror()` and other related functions. 1949 * \see mdbx_strerror_r() 1950 * 1951 * \param [in] errnum The error code. 1952 * 1953 * \returns "error message" The description of the error. */ 1954 LIBMDBX_API const char *mdbx_strerror(int errnum); 1955 1956 /** \brief Return a string describing a given error code. 1957 * \ingroup c_err 1958 * 1959 * This function is a superset of the ANSI C X3.159-1989 (ANSI C) `strerror()` 1960 * function. If the error code is greater than or equal to 0, then the string 1961 * returned by the system function `strerror()` is returned. If the error code 1962 * is less than 0, an error string corresponding to the MDBX library error is 1963 * returned. See errors for a list of MDBX-specific error codes. 1964 * 1965 * `mdbx_strerror_r()` is thread-safe since uses user-supplied buffer where 1966 * appropriate. The returned string must NOT be modified by the application, 1967 * since it may be pointer to internal constant string. However, there is no 1968 * restriction if the returned string points to the supplied buffer. 1969 * \see mdbx_strerror() 1970 * 1971 * mdbx_liberr2str() returns string describing only MDBX error numbers but NULL 1972 * for non-MDBX error codes. This function is thread-safe since return pointer 1973 * to constant non-localized strings. 1974 * 1975 * \param [in] errnum The error code. 1976 * \param [in,out] buf Buffer to store the error message. 1977 * \param [in] buflen The size of buffer to store the message. 1978 * 1979 * \returns "error message" The description of the error. */ 1980 LIBMDBX_API const char *mdbx_strerror_r(int errnum, char *buf, size_t buflen); 1981 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API const char *mdbx_liberr2str(int errnum); 1982 1983 #if defined(_WIN32) || defined(_WIN64) || defined(DOXYGEN) 1984 /** Bit of Windows' madness. The similar to \ref mdbx_strerror() but returns 1985 * Windows error-messages in the OEM-encoding for console utilities. 1986 * \ingroup c_err 1987 * \see mdbx_strerror_r_ANSI2OEM() */ 1988 LIBMDBX_API const char *mdbx_strerror_ANSI2OEM(int errnum); 1989 1990 /** Bit of Windows' madness. The similar to \ref mdbx_strerror_r() but returns 1991 * Windows error-messages in the OEM-encoding for console utilities. 1992 * \ingroup c_err 1993 * \see mdbx_strerror_ANSI2OEM() */ 1994 LIBMDBX_API const char *mdbx_strerror_r_ANSI2OEM(int errnum, char *buf, 1995 size_t buflen); 1996 #endif /* Bit of Windows' madness */ 1997 1998 /** \brief Create an MDBX environment instance. 1999 * \ingroup c_opening 2000 * 2001 * This function allocates memory for a \ref MDBX_env structure. To release 2002 * the allocated memory and discard the handle, call \ref mdbx_env_close(). 2003 * Before the handle may be used, it must be opened using \ref mdbx_env_open(). 2004 * 2005 * Various other options may also need to be set before opening the handle, 2006 * e.g. \ref mdbx_env_set_geometry(), \ref mdbx_env_set_maxreaders(), 2007 * \ref mdbx_env_set_maxdbs(), depending on usage requirements. 2008 * 2009 * \param [out] penv The address where the new handle will be stored. 2010 * 2011 * \returns a non-zero error value on failure and 0 on success. */ 2012 LIBMDBX_API int mdbx_env_create(MDBX_env **penv); 2013 2014 /** \brief MDBX environment options. */ 2015 enum MDBX_option_t { 2016 /** \brief Controls the maximum number of named databases for the environment. 2017 * 2018 * \details By default only unnamed key-value database could used and 2019 * appropriate value should set by `MDBX_opt_max_db` to using any more named 2020 * subDB(s). To reduce overhead, use the minimum sufficient value. This option 2021 * may only set after \ref mdbx_env_create() and before \ref mdbx_env_open(). 2022 * 2023 * \see mdbx_env_set_maxdbs() \see mdbx_env_get_maxdbs() */ 2024 MDBX_opt_max_db, 2025 2026 /** \brief Defines the maximum number of threads/reader slots 2027 * for all processes interacting with the database. 2028 * 2029 * \details This defines the number of slots in the lock table that is used to 2030 * track readers in the the environment. The default is about 100 for 4K 2031 * system page size. Starting a read-only transaction normally ties a lock 2032 * table slot to the current thread until the environment closes or the thread 2033 * exits. If \ref MDBX_NOTLS is in use, \ref mdbx_txn_begin() instead ties the 2034 * slot to the \ref MDBX_txn object until it or the \ref MDBX_env object is 2035 * destroyed. This option may only set after \ref mdbx_env_create() and before 2036 * \ref mdbx_env_open(), and has an effect only when the database is opened by 2037 * the first process interacts with the database. 2038 * 2039 * \see mdbx_env_set_maxreaders() \see mdbx_env_get_maxreaders() */ 2040 MDBX_opt_max_readers, 2041 2042 /** \brief Controls interprocess/shared threshold to force flush the data 2043 * buffers to disk, if \ref MDBX_SAFE_NOSYNC is used. 2044 * 2045 * \see mdbx_env_set_syncbytes() \see mdbx_env_get_syncbytes() */ 2046 MDBX_opt_sync_bytes, 2047 2048 /** \brief Controls interprocess/shared relative period since the last 2049 * unsteady commit to force flush the data buffers to disk, 2050 * if \ref MDBX_SAFE_NOSYNC is used. 2051 * \see mdbx_env_set_syncperiod() \see mdbx_env_get_syncperiod() */ 2052 MDBX_opt_sync_period, 2053 2054 /** \brief Controls the in-process limit to grow a list of reclaimed/recycled 2055 * page's numbers for finding a sequence of contiguous pages for large data 2056 * items. 2057 * 2058 * \details A long values requires allocation of contiguous database pages. 2059 * To find such sequences, it may be necessary to accumulate very large lists, 2060 * especially when placing very long values (more than a megabyte) in a large 2061 * databases (several tens of gigabytes), which is much expensive in extreme 2062 * cases. This threshold allows you to avoid such costs by allocating new 2063 * pages at the end of the database (with its possible growth on disk), 2064 * instead of further accumulating/reclaiming Garbage Collection records. 2065 * 2066 * On the other hand, too small threshold will lead to unreasonable database 2067 * growth, or/and to the inability of put long values. 2068 * 2069 * The `MDBX_opt_rp_augment_limit` controls described limit for the current 2070 * process. Default is 262144, it is usually enough for most cases. */ 2071 MDBX_opt_rp_augment_limit, 2072 2073 /** \brief Controls the in-process limit to grow a cache of dirty 2074 * pages for reuse in the current transaction. 2075 * 2076 * \details A 'dirty page' refers to a page that has been updated in memory 2077 * only, the changes to a dirty page are not yet stored on disk. 2078 * To reduce overhead, it is reasonable to release not all such pages 2079 * immediately, but to leave some ones in cache for reuse in the current 2080 * transaction. 2081 * 2082 * The `MDBX_opt_loose_limit` allows you to set a limit for such cache inside 2083 * the current process. Should be in the range 0..255, default is 64. */ 2084 MDBX_opt_loose_limit, 2085 2086 /** \brief Controls the in-process limit of a pre-allocated memory items 2087 * for dirty pages. 2088 * 2089 * \details A 'dirty page' refers to a page that has been updated in memory 2090 * only, the changes to a dirty page are not yet stored on disk. 2091 * Without \ref MDBX_WRITEMAP dirty pages are allocated from memory and 2092 * released when a transaction is committed. To reduce overhead, it is 2093 * reasonable to release not all ones, but to leave some allocations in 2094 * reserve for reuse in the next transaction(s). 2095 * 2096 * The `MDBX_opt_dp_reserve_limit` allows you to set a limit for such reserve 2097 * inside the current process. Default is 1024. */ 2098 MDBX_opt_dp_reserve_limit, 2099 2100 /** \brief Controls the in-process limit of dirty pages 2101 * for a write transaction. 2102 * 2103 * \details A 'dirty page' refers to a page that has been updated in memory 2104 * only, the changes to a dirty page are not yet stored on disk. 2105 * Without \ref MDBX_WRITEMAP dirty pages are allocated from memory and will 2106 * be busy until are written to disk. Therefore for a large transactions is 2107 * reasonable to limit dirty pages collecting above an some threshold but 2108 * spill to disk instead. 2109 * 2110 * The `MDBX_opt_txn_dp_limit` controls described threshold for the current 2111 * process. Default is 65536, it is usually enough for most cases. */ 2112 MDBX_opt_txn_dp_limit, 2113 2114 /** \brief Controls the in-process initial allocation size for dirty pages 2115 * list of a write transaction. Default is 1024. */ 2116 MDBX_opt_txn_dp_initial, 2117 2118 /** \brief Controls the in-process how maximal part of the dirty pages may be 2119 * spilled when necessary. 2120 * 2121 * \details The `MDBX_opt_spill_max_denominator` defines the denominator for 2122 * limiting from the top for part of the current dirty pages may be spilled 2123 * when the free room for a new dirty pages (i.e. distance to the 2124 * `MDBX_opt_txn_dp_limit` threshold) is not enough to perform requested 2125 * operation. 2126 * Exactly `max_pages_to_spill = dirty_pages - dirty_pages / N`, 2127 * where `N` is the value set by `MDBX_opt_spill_max_denominator`. 2128 * 2129 * Should be in the range 0..255, where zero means no limit, i.e. all dirty 2130 * pages could be spilled. Default is 8, i.e. no more than 7/8 of the current 2131 * dirty pages may be spilled when reached the condition described above. */ 2132 MDBX_opt_spill_max_denominator, 2133 2134 /** \brief Controls the in-process how minimal part of the dirty pages should 2135 * be spilled when necessary. 2136 * 2137 * \details The `MDBX_opt_spill_min_denominator` defines the denominator for 2138 * limiting from the bottom for part of the current dirty pages should be 2139 * spilled when the free room for a new dirty pages (i.e. distance to the 2140 * `MDBX_opt_txn_dp_limit` threshold) is not enough to perform requested 2141 * operation. 2142 * Exactly `min_pages_to_spill = dirty_pages / N`, 2143 * where `N` is the value set by `MDBX_opt_spill_min_denominator`. 2144 * 2145 * Should be in the range 0..255, where zero means no restriction at the 2146 * bottom. Default is 8, i.e. at least the 1/8 of the current dirty pages 2147 * should be spilled when reached the condition described above. */ 2148 MDBX_opt_spill_min_denominator, 2149 2150 /** \brief Controls the in-process how much of the parent transaction dirty 2151 * pages will be spilled while start each child transaction. 2152 * 2153 * \details The `MDBX_opt_spill_parent4child_denominator` defines the 2154 * denominator to determine how much of parent transaction dirty pages will be 2155 * spilled explicitly while start each child transaction. 2156 * Exactly `pages_to_spill = dirty_pages / N`, 2157 * where `N` is the value set by `MDBX_opt_spill_parent4child_denominator`. 2158 * 2159 * For a stack of nested transactions each dirty page could be spilled only 2160 * once, and parent's dirty pages couldn't be spilled while child 2161 * transaction(s) are running. Therefore a child transaction could reach 2162 * \ref MDBX_TXN_FULL when parent(s) transaction has spilled too less (and 2163 * child reach the limit of dirty pages), either when parent(s) has spilled 2164 * too more (since child can't spill already spilled pages). So there is no 2165 * universal golden ratio. 2166 * 2167 * Should be in the range 0..255, where zero means no explicit spilling will 2168 * be performed during starting nested transactions. 2169 * Default is 0, i.e. by default no spilling performed during starting nested 2170 * transactions, that correspond historically behaviour. */ 2171 MDBX_opt_spill_parent4child_denominator, 2172 2173 /** \brief Controls the in-process threshold of semi-empty pages merge. 2174 * \warning This is experimental option and subject for change or removal. 2175 * \details This option controls the in-process threshold of minimum page 2176 * fill, as used space of percentage of a page. Neighbour pages emptier than 2177 * this value are candidates for merging. The threshold value is specified 2178 * in 1/65536 of percent, which is equivalent to the 16-dot-16 fixed point 2179 * format. The specified value must be in the range from 12.5% (almost empty) 2180 * to 50% (half empty) which corresponds to the range from 8192 and to 32768 2181 * in units respectively. */ 2182 MDBX_opt_merge_threshold_16dot16_percent, 2183 }; 2184 #ifndef __cplusplus 2185 /** \ingroup c_settings */ 2186 typedef enum MDBX_option_t MDBX_option_t; 2187 #endif 2188 2189 /** \brief Sets the value of a runtime options for an environment. 2190 * \ingroup c_settings 2191 * 2192 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 2193 * \param [in] option The option from \ref MDBX_option_t to set value of it. 2194 * \param [in] value The value of option to be set. 2195 * 2196 * \see MDBX_option_t 2197 * \see mdbx_env_get_option() 2198 * \returns A non-zero error value on failure and 0 on success. */ 2199 LIBMDBX_API int mdbx_env_set_option(MDBX_env *env, const MDBX_option_t option, 2200 uint64_t value); 2201 2202 /** \brief Gets the value of runtime options from an environment. 2203 * \ingroup c_settings 2204 * 2205 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 2206 * \param [in] option The option from \ref MDBX_option_t to get value of it. 2207 * \param [out] pvalue The address where the option's value will be stored. 2208 * 2209 * \see MDBX_option_t 2210 * \see mdbx_env_get_option() 2211 * \returns A non-zero error value on failure and 0 on success. */ 2212 LIBMDBX_API int mdbx_env_get_option(const MDBX_env *env, 2213 const MDBX_option_t option, 2214 uint64_t *pvalue); 2215 2216 /** \brief Open an environment instance. 2217 * \ingroup c_opening 2218 * 2219 * Indifferently this function will fails or not, the \ref mdbx_env_close() must 2220 * be called later to discard the \ref MDBX_env handle and release associated 2221 * resources. 2222 * 2223 * \param [in] env An environment handle returned 2224 * by \ref mdbx_env_create() 2225 * 2226 * \param [in] pathname The pathname for the database or the directory in which 2227 * the database files reside. In the case of directory it 2228 * must already exist and be writable. 2229 * 2230 * \param [in] flags Specifies options for this environment. 2231 * This parameter must be bitwise OR'ing together 2232 * any constants described above in the \ref env_flags 2233 * and \ref sync_modes sections. 2234 * 2235 * Flags set by mdbx_env_set_flags() are also used: 2236 * - \ref MDBX_ENV_DEFAULTS, \ref MDBX_NOSUBDIR, \ref MDBX_RDONLY, 2237 * \ref MDBX_EXCLUSIVE, \ref MDBX_WRITEMAP, \ref MDBX_NOTLS, 2238 * \ref MDBX_NORDAHEAD, \ref MDBX_NOMEMINIT, \ref MDBX_COALESCE, 2239 * \ref MDBX_LIFORECLAIM. See \ref env_flags section. 2240 * 2241 * - \ref MDBX_SYNC_DURABLE, \ref MDBX_NOMETASYNC, \ref MDBX_SAFE_NOSYNC, 2242 * \ref MDBX_UTTERLY_NOSYNC. See \ref sync_modes section. 2243 * 2244 * \note `MDB_NOLOCK` flag don't supported by MDBX, 2245 * try use \ref MDBX_EXCLUSIVE as a replacement. 2246 * 2247 * \note MDBX don't allow to mix processes with different \ref MDBX_SAFE_NOSYNC 2248 * flags on the same environment. 2249 * In such case \ref MDBX_INCOMPATIBLE will be returned. 2250 * 2251 * If the database is already exist and parameters specified early by 2252 * \ref mdbx_env_set_geometry() are incompatible (i.e. for instance, different 2253 * page size) then \ref mdbx_env_open() will return \ref MDBX_INCOMPATIBLE 2254 * error. 2255 * 2256 * \param [in] mode The UNIX permissions to set on created files. 2257 * Zero value means to open existing, but do not create. 2258 * 2259 * \return A non-zero error value on failure and 0 on success, 2260 * some possible errors are: 2261 * \retval MDBX_VERSION_MISMATCH The version of the MDBX library doesn't match 2262 * the version that created the database environment. 2263 * \retval MDBX_INVALID The environment file headers are corrupted. 2264 * \retval MDBX_ENOENT The directory specified by the path parameter 2265 * doesn't exist. 2266 * \retval MDBX_EACCES The user didn't have permission to access 2267 * the environment files. 2268 * \retval MDBX_EAGAIN The environment was locked by another process. 2269 * \retval MDBX_BUSY The \ref MDBX_EXCLUSIVE flag was specified and the 2270 * environment is in use by another process, 2271 * or the current process tries to open environment 2272 * more than once. 2273 * \retval MDBX_INCOMPATIBLE Environment is already opened by another process, 2274 * but with different set of \ref MDBX_SAFE_NOSYNC, 2275 * \ref MDBX_UTTERLY_NOSYNC flags. 2276 * Or if the database is already exist and parameters 2277 * specified early by \ref mdbx_env_set_geometry() 2278 * are incompatible (i.e. different pagesize, etc). 2279 * 2280 * \retval MDBX_WANNA_RECOVERY The \ref MDBX_RDONLY flag was specified but 2281 * read-write access is required to rollback 2282 * inconsistent state after a system crash. 2283 * 2284 * \retval MDBX_TOO_LARGE Database is too large for this process, 2285 * i.e. 32-bit process tries to open >4Gb database. 2286 */ 2287 LIBMDBX_API int mdbx_env_open(MDBX_env *env, const char *pathname, 2288 MDBX_env_flags_t flags, mdbx_mode_t mode); 2289 2290 #if defined(_WIN32) || defined(_WIN64) 2291 LIBMDBX_API int mdbx_env_openW(MDBX_env *env, const wchar_t *pathnameW, 2292 MDBX_env_flags_t flags, mdbx_mode_t mode); 2293 #endif /* Windows */ 2294 2295 /** \brief Deletion modes for \ref mdbx_env_delete(). 2296 * \ingroup c_extra 2297 * \see mdbx_env_delete() */ 2298 enum MDBX_env_delete_mode_t { 2299 /** \brief Just delete the environment's files and directory if any. 2300 * \note On POSIX systems, processes already working with the database will 2301 * continue to work without interference until it close the environment. 2302 * \note On Windows, the behavior of `MDB_ENV_JUST_DELETE` is different 2303 * because the system does not support deleting files that are currently 2304 * memory mapped. */ 2305 MDBX_ENV_JUST_DELETE = 0, 2306 /** \brief Make sure that the environment is not being used by other 2307 * processes, or return an error otherwise. */ 2308 MDBX_ENV_ENSURE_UNUSED = 1, 2309 /** \brief Wait until other processes closes the environment before deletion. 2310 */ 2311 MDBX_ENV_WAIT_FOR_UNUSED = 2, 2312 }; 2313 #ifndef __cplusplus 2314 /** \ingroup c_extra */ 2315 typedef enum MDBX_env_delete_mode_t MDBX_env_delete_mode_t; 2316 #endif 2317 2318 /** \brief Delete the environment's files in a proper and multiprocess-safe way. 2319 * \ingroup c_extra 2320 * 2321 * \param [in] pathname The pathname for the database or the directory in which 2322 * the database files reside. 2323 * 2324 * \param [in] mode Specifies deletion mode for the environment. This 2325 * parameter must be set to one of the constants described 2326 * above in the \ref MDBX_env_delete_mode_t section. 2327 * 2328 * \note The \ref MDBX_ENV_JUST_DELETE don't supported on Windows since system 2329 * unable to delete a memory-mapped files. 2330 * 2331 * \returns A non-zero error value on failure and 0 on success, 2332 * some possible errors are: 2333 * \retval MDBX_RESULT_TRUE No corresponding files or directories were found, 2334 * so no deletion was performed. */ 2335 LIBMDBX_API int mdbx_env_delete(const char *pathname, 2336 MDBX_env_delete_mode_t mode); 2337 #if defined(_WIN32) || defined(_WIN64) 2338 LIBMDBX_API int mdbx_env_deleteW(const wchar_t *pathnameW, 2339 MDBX_env_delete_mode_t mode); 2340 #endif /* Windows */ 2341 2342 /** \brief Copy an MDBX environment to the specified path, with options. 2343 * \ingroup c_extra 2344 * 2345 * This function may be used to make a backup of an existing environment. 2346 * No lockfile is created, since it gets recreated at need. 2347 * \note This call can trigger significant file size growth if run in 2348 * parallel with write transactions, because it employs a read-only 2349 * transaction. See long-lived transactions under \ref restrictions section. 2350 * 2351 * \param [in] env An environment handle returned by mdbx_env_create(). 2352 * It must have already been opened successfully. 2353 * \param [in] dest The pathname of a file in which the copy will reside. 2354 * This file must not be already exist, but parent directory 2355 * must be writable. 2356 * \param [in] flags Specifies options for this operation. This parameter 2357 * must be bitwise OR'ing together any of the constants 2358 * described here: 2359 * 2360 * - \ref MDBX_CP_DEFAULTS 2361 * Perform copy as-is without compaction, etc. 2362 * 2363 * - \ref MDBX_CP_COMPACT 2364 * Perform compaction while copying: omit free pages and sequentially 2365 * renumber all pages in output. This option consumes little bit more 2366 * CPU for processing, but may running quickly than the default, on 2367 * account skipping free pages. 2368 * 2369 * - \ref MDBX_CP_FORCE_DYNAMIC_SIZE 2370 * Force to make resizeable copy, i.e. dynamic size instead of fixed. 2371 * 2372 * \returns A non-zero error value on failure and 0 on success. */ 2373 LIBMDBX_API int mdbx_env_copy(MDBX_env *env, const char *dest, 2374 MDBX_copy_flags_t flags); 2375 #if defined(_WIN32) || defined(_WIN64) 2376 LIBMDBX_API int mdbx_env_copyW(MDBX_env *env, const wchar_t *dest, 2377 MDBX_copy_flags_t flags); 2378 #endif /* Windows */ 2379 2380 /** \brief Copy an environment to the specified file descriptor, with 2381 * options. 2382 * \ingroup c_extra 2383 * 2384 * This function may be used to make a backup of an existing environment. 2385 * No lockfile is created, since it gets recreated at need. 2386 * \see mdbx_env_copy() 2387 * 2388 * \note This call can trigger significant file size growth if run in 2389 * parallel with write transactions, because it employs a read-only 2390 * transaction. See long-lived transactions under \ref restrictions 2391 * section. 2392 * 2393 * \note Fails if the environment has suffered a page leak and the destination 2394 * file descriptor is associated with a pipe, socket, or FIFO. 2395 * 2396 * \param [in] env An environment handle returned by mdbx_env_create(). 2397 * It must have already been opened successfully. 2398 * \param [in] fd The file descriptor to write the copy to. It must have 2399 * already been opened for Write access. 2400 * \param [in] flags Special options for this operation. \see mdbx_env_copy() 2401 * 2402 * \returns A non-zero error value on failure and 0 on success. */ 2403 LIBMDBX_API int mdbx_env_copy2fd(MDBX_env *env, mdbx_filehandle_t fd, 2404 MDBX_copy_flags_t flags); 2405 2406 /** \brief Statistics for a database in the environment 2407 * \ingroup c_statinfo 2408 * \see mdbx_env_stat_ex() \see mdbx_dbi_stat() */ 2409 struct MDBX_stat { 2410 uint32_t ms_psize; /**< Size of a database page. This is the same for all 2411 databases. */ 2412 uint32_t ms_depth; /**< Depth (height) of the B-tree */ 2413 uint64_t ms_branch_pages; /**< Number of internal (non-leaf) pages */ 2414 uint64_t ms_leaf_pages; /**< Number of leaf pages */ 2415 uint64_t ms_overflow_pages; /**< Number of overflow pages */ 2416 uint64_t ms_entries; /**< Number of data items */ 2417 uint64_t ms_mod_txnid; /**< Transaction ID of committed last modification */ 2418 }; 2419 #ifndef __cplusplus 2420 /** \ingroup c_statinfo */ 2421 typedef struct MDBX_stat MDBX_stat; 2422 #endif 2423 2424 /** \brief Return statistics about the MDBX environment. 2425 * \ingroup c_statinfo 2426 * 2427 * At least one of env or txn argument must be non-null. If txn is passed 2428 * non-null then stat will be filled accordingly to the given transaction. 2429 * Otherwise, if txn is null, then stat will be populated by a snapshot from 2430 * the last committed write transaction, and at next time, other information 2431 * can be returned. 2432 * 2433 * Legacy mdbx_env_stat() correspond to calling \ref mdbx_env_stat_ex() with the 2434 * null `txn` argument. 2435 * 2436 * \param [in] env An environment handle returned by \ref mdbx_env_create() 2437 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin() 2438 * \param [out] stat The address of an \ref MDBX_stat structure where 2439 * the statistics will be copied 2440 * \param [in] bytes The size of \ref MDBX_stat. 2441 * 2442 * \returns A non-zero error value on failure and 0 on success. */ 2443 LIBMDBX_API int mdbx_env_stat_ex(const MDBX_env *env, const MDBX_txn *txn, 2444 MDBX_stat *stat, size_t bytes); 2445 2446 /** \brief Return statistics about the MDBX environment. 2447 * \ingroup c_statinfo 2448 * \deprecated Please use mdbx_env_stat_ex() instead. */ 2449 MDBX_DEPRECATED LIBMDBX_INLINE_API(int, mdbx_env_stat, 2450 (const MDBX_env *env, MDBX_stat *stat, 2451 size_t bytes)) { 2452 return mdbx_env_stat_ex(env, NULL, stat, bytes); 2453 } 2454 2455 /** \brief Information about the environment 2456 * \ingroup c_statinfo 2457 * \see mdbx_env_info_ex() */ 2458 struct MDBX_envinfo { 2459 struct { 2460 uint64_t lower; /**< Lower limit for datafile size */ 2461 uint64_t upper; /**< Upper limit for datafile size */ 2462 uint64_t current; /**< Current datafile size */ 2463 uint64_t shrink; /**< Shrink threshold for datafile */ 2464 uint64_t grow; /**< Growth step for datafile */ 2465 } mi_geo; 2466 uint64_t mi_mapsize; /**< Size of the data memory map */ 2467 uint64_t mi_last_pgno; /**< Number of the last used page */ 2468 uint64_t mi_recent_txnid; /**< ID of the last committed transaction */ 2469 uint64_t mi_latter_reader_txnid; /**< ID of the last reader transaction */ 2470 uint64_t mi_self_latter_reader_txnid; /**< ID of the last reader transaction 2471 of caller process */ 2472 uint64_t mi_meta0_txnid, mi_meta0_sign; 2473 uint64_t mi_meta1_txnid, mi_meta1_sign; 2474 uint64_t mi_meta2_txnid, mi_meta2_sign; 2475 uint32_t mi_maxreaders; /**< Total reader slots in the environment */ 2476 uint32_t mi_numreaders; /**< Max reader slots used in the environment */ 2477 uint32_t mi_dxb_pagesize; /**< Database pagesize */ 2478 uint32_t mi_sys_pagesize; /**< System pagesize */ 2479 2480 /** \brief A mostly unique ID that is regenerated on each boot. 2481 2482 As such it can be used to identify the local machine's current boot. MDBX 2483 uses such when open the database to determine whether rollback required to 2484 the last steady sync point or not. I.e. if current bootid is differ from the 2485 value within a database then the system was rebooted and all changes since 2486 last steady sync must be reverted for data integrity. Zeros mean that no 2487 relevant information is available from the system. */ 2488 struct { 2489 struct { 2490 uint64_t x, y; 2491 } current, meta0, meta1, meta2; 2492 } mi_bootid; 2493 2494 /** Bytes not explicitly synchronized to disk */ 2495 uint64_t mi_unsync_volume; 2496 /** Current auto-sync threshold, see \ref mdbx_env_set_syncbytes(). */ 2497 uint64_t mi_autosync_threshold; 2498 /** Time since the last steady sync in 1/65536 of second */ 2499 uint32_t mi_since_sync_seconds16dot16; 2500 /** Current auto-sync period in 1/65536 of second, 2501 * see \ref mdbx_env_set_syncperiod(). */ 2502 uint32_t mi_autosync_period_seconds16dot16; 2503 /** Time since the last readers check in 1/65536 of second, 2504 * see \ref mdbx_reader_check(). */ 2505 uint32_t mi_since_reader_check_seconds16dot16; 2506 /** Current environment mode. 2507 * The same as \ref mdbx_env_get_flags() returns. */ 2508 uint32_t mi_mode; 2509 2510 /** Statistics of page operations. 2511 * \details Overall statistics of page operations of all (running, completed 2512 * and aborted) transactions in the current multi-process session (since the 2513 * first process opened the database after everyone had previously closed it). 2514 */ 2515 struct { 2516 uint64_t newly; /**< Quantity of a new pages added */ 2517 uint64_t cow; /**< Quantity of pages copied for update */ 2518 uint64_t clone; /**< Quantity of parent's dirty pages clones 2519 for nested transactions */ 2520 uint64_t split; /**< Page splits */ 2521 uint64_t merge; /**< Page merges */ 2522 uint64_t spill; /**< Quantity of spilled dirty pages */ 2523 uint64_t unspill; /**< Quantity of unspilled/reloaded pages */ 2524 uint64_t wops; /**< Number of explicit write operations (not a pages) 2525 to a disk */ 2526 uint64_t 2527 gcrtime_seconds16dot16; /**< Time spent loading and searching inside 2528 GC (aka FreeDB) in 1/65536 of second. */ 2529 } mi_pgop_stat; 2530 }; 2531 #ifndef __cplusplus 2532 /** \ingroup c_statinfo */ 2533 typedef struct MDBX_envinfo MDBX_envinfo; 2534 #endif 2535 2536 /** \brief Return information about the MDBX environment. 2537 * \ingroup c_statinfo 2538 * 2539 * At least one of env or txn argument must be non-null. If txn is passed 2540 * non-null then stat will be filled accordingly to the given transaction. 2541 * Otherwise, if txn is null, then stat will be populated by a snapshot from 2542 * the last committed write transaction, and at next time, other information 2543 * can be returned. 2544 * 2545 * Legacy \ref mdbx_env_info() correspond to calling \ref mdbx_env_info_ex() 2546 * with the null `txn` argument. 2547 * 2548 * \param [in] env An environment handle returned by \ref mdbx_env_create() 2549 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin() 2550 * \param [out] info The address of an \ref MDBX_envinfo structure 2551 * where the information will be copied 2552 * \param [in] bytes The size of \ref MDBX_envinfo. 2553 * 2554 * \returns A non-zero error value on failure and 0 on success. */ 2555 LIBMDBX_API int mdbx_env_info_ex(const MDBX_env *env, const MDBX_txn *txn, 2556 MDBX_envinfo *info, size_t bytes); 2557 /** \brief Return information about the MDBX environment. 2558 * \ingroup c_statinfo 2559 * \deprecated Please use mdbx_env_info_ex() instead. */ 2560 MDBX_DEPRECATED LIBMDBX_INLINE_API(int, mdbx_env_info, 2561 (const MDBX_env *env, MDBX_envinfo *info, 2562 size_t bytes)) { 2563 return mdbx_env_info_ex(env, NULL, info, bytes); 2564 } 2565 2566 /** \brief Flush the environment data buffers to disk. 2567 * \ingroup c_extra 2568 * 2569 * Unless the environment was opened with no-sync flags (\ref MDBX_NOMETASYNC, 2570 * \ref MDBX_SAFE_NOSYNC and \ref MDBX_UTTERLY_NOSYNC), then 2571 * data is always written an flushed to disk when \ref mdbx_txn_commit() is 2572 * called. Otherwise \ref mdbx_env_sync() may be called to manually write and 2573 * flush unsynced data to disk. 2574 * 2575 * Besides, \ref mdbx_env_sync_ex() with argument `force=false` may be used to 2576 * provide polling mode for lazy/asynchronous sync in conjunction with 2577 * \ref mdbx_env_set_syncbytes() and/or \ref mdbx_env_set_syncperiod(). 2578 * 2579 * \note This call is not valid if the environment was opened with MDBX_RDONLY. 2580 * 2581 * \param [in] env An environment handle returned by \ref mdbx_env_create() 2582 * \param [in] force If non-zero, force a flush. Otherwise, If force is 2583 * zero, then will run in polling mode, 2584 * i.e. it will check the thresholds that were 2585 * set \ref mdbx_env_set_syncbytes() 2586 * and/or \ref mdbx_env_set_syncperiod() and perform flush 2587 * if at least one of the thresholds is reached. 2588 * 2589 * \param [in] nonblock Don't wait if write transaction 2590 * is running by other thread. 2591 * 2592 * \returns A non-zero error value on failure and \ref MDBX_RESULT_TRUE or 0 on 2593 * success. The \ref MDBX_RESULT_TRUE means no data pending for flush 2594 * to disk, and 0 otherwise. Some possible errors are: 2595 * 2596 * \retval MDBX_EACCES the environment is read-only. 2597 * \retval MDBX_BUSY the environment is used by other thread 2598 * and `nonblock=true`. 2599 * \retval MDBX_EINVAL an invalid parameter was specified. 2600 * \retval MDBX_EIO an error occurred during synchronization. */ 2601 LIBMDBX_API int mdbx_env_sync_ex(MDBX_env *env, bool force, bool nonblock); 2602 2603 /** \brief The shortcut to calling \ref mdbx_env_sync_ex() with 2604 * the `force=true` and `nonblock=false` arguments. 2605 * \ingroup c_extra */ 2606 LIBMDBX_INLINE_API(int, mdbx_env_sync, (MDBX_env * env)) { 2607 return mdbx_env_sync_ex(env, true, false); 2608 } 2609 2610 /** \brief The shortcut to calling \ref mdbx_env_sync_ex() with 2611 * the `force=false` and `nonblock=true` arguments. 2612 * \ingroup c_extra */ 2613 LIBMDBX_INLINE_API(int, mdbx_env_sync_poll, (MDBX_env * env)) { 2614 return mdbx_env_sync_ex(env, false, true); 2615 } 2616 2617 /** \brief Sets threshold to force flush the data buffers to disk, even any of 2618 * \ref MDBX_SAFE_NOSYNC flag in the environment. 2619 * \ingroup c_settings 2620 * \see mdbx_env_get_syncbytes \see MDBX_opt_sync_bytes 2621 * 2622 * The threshold value affects all processes which operates with given 2623 * environment until the last process close environment or a new value will be 2624 * settled. 2625 * 2626 * Data is always written to disk when \ref mdbx_txn_commit() is called, but 2627 * the operating system may keep it buffered. MDBX always flushes the OS buffers 2628 * upon commit as well, unless the environment was opened with 2629 * \ref MDBX_SAFE_NOSYNC, \ref MDBX_UTTERLY_NOSYNC 2630 * or in part \ref MDBX_NOMETASYNC. 2631 * 2632 * The default is 0, than mean no any threshold checked, and no additional 2633 * flush will be made. 2634 * 2635 * \param [in] env An environment handle returned by mdbx_env_create(). 2636 * \param [in] threshold The size in bytes of summary changes when 2637 * a synchronous flush would be made. 2638 * 2639 * \returns A non-zero error value on failure and 0 on success. */ 2640 LIBMDBX_INLINE_API(int, mdbx_env_set_syncbytes, 2641 (MDBX_env * env, size_t threshold)) { 2642 return mdbx_env_set_option(env, MDBX_opt_sync_bytes, threshold); 2643 } 2644 2645 /** \brief Get threshold to force flush the data buffers to disk, even any of 2646 * \ref MDBX_SAFE_NOSYNC flag in the environment. 2647 * \ingroup c_statinfo 2648 * \see mdbx_env_set_syncbytes() \see MDBX_opt_sync_bytes 2649 * 2650 * \param [in] env An environment handle returned 2651 * by \ref mdbx_env_create(). 2652 * \param [out] threshold Address of an size_t to store 2653 * the number of bytes of summary changes when 2654 * a synchronous flush would be made. 2655 * 2656 * \returns A non-zero error value on failure and 0 on success, 2657 * some possible errors are: 2658 * \retval MDBX_EINVAL An invalid parameter was specified. */ 2659 LIBMDBX_INLINE_API(int, mdbx_env_get_syncbytes, 2660 (const MDBX_env *env, size_t *threshold)) { 2661 int rc = MDBX_EINVAL; 2662 if (threshold) { 2663 uint64_t proxy = 0; 2664 rc = mdbx_env_get_option(env, MDBX_opt_sync_bytes, &proxy); 2665 #ifdef assert 2666 assert(proxy <= SIZE_MAX); 2667 #endif /* assert */ 2668 *threshold = (size_t)proxy; 2669 } 2670 return rc; 2671 } 2672 2673 /** \brief Sets relative period since the last unsteady commit to force flush 2674 * the data buffers to disk, even of \ref MDBX_SAFE_NOSYNC flag in the 2675 * environment. 2676 * \ingroup c_settings 2677 * \see mdbx_env_get_syncperiod \see MDBX_opt_sync_period 2678 * 2679 * The relative period value affects all processes which operates with given 2680 * environment until the last process close environment or a new value will be 2681 * settled. 2682 * 2683 * Data is always written to disk when \ref mdbx_txn_commit() is called, but the 2684 * operating system may keep it buffered. MDBX always flushes the OS buffers 2685 * upon commit as well, unless the environment was opened with 2686 * \ref MDBX_SAFE_NOSYNC or in part \ref MDBX_NOMETASYNC. 2687 * 2688 * Settled period don't checked asynchronously, but only by the 2689 * \ref mdbx_txn_commit() and \ref mdbx_env_sync() functions. Therefore, in 2690 * cases where transactions are committed infrequently and/or irregularly, 2691 * polling by \ref mdbx_env_sync() may be a reasonable solution to timeout 2692 * enforcement. 2693 * 2694 * The default is 0, than mean no any timeout checked, and no additional 2695 * flush will be made. 2696 * 2697 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 2698 * \param [in] seconds_16dot16 The period in 1/65536 of second when 2699 * a synchronous flush would be made since 2700 * the last unsteady commit. 2701 * 2702 * \returns A non-zero error value on failure and 0 on success. */ 2703 LIBMDBX_INLINE_API(int, mdbx_env_set_syncperiod, 2704 (MDBX_env * env, unsigned seconds_16dot16)) { 2705 return mdbx_env_set_option(env, MDBX_opt_sync_period, seconds_16dot16); 2706 } 2707 2708 /** \brief Get relative period since the last unsteady commit to force flush 2709 * the data buffers to disk, even of \ref MDBX_SAFE_NOSYNC flag in the 2710 * environment. 2711 * \ingroup c_statinfo 2712 * \see mdbx_env_set_syncperiod() \see MDBX_opt_sync_period 2713 * 2714 * \param [in] env An environment handle returned 2715 * by \ref mdbx_env_create(). 2716 * \param [out] period_seconds_16dot16 Address of an size_t to store 2717 * the period in 1/65536 of second when 2718 * a synchronous flush would be made since 2719 * the last unsteady commit. 2720 * 2721 * \returns A non-zero error value on failure and 0 on success, 2722 * some possible errors are: 2723 * \retval MDBX_EINVAL An invalid parameter was specified. */ 2724 LIBMDBX_INLINE_API(int, mdbx_env_get_syncperiod, 2725 (const MDBX_env *env, unsigned *period_seconds_16dot16)) { 2726 int rc = MDBX_EINVAL; 2727 if (period_seconds_16dot16) { 2728 uint64_t proxy = 0; 2729 rc = mdbx_env_get_option(env, MDBX_opt_sync_period, &proxy); 2730 #ifdef assert 2731 assert(proxy <= UINT32_MAX); 2732 #endif /* assert */ 2733 *period_seconds_16dot16 = (unsigned)proxy; 2734 } 2735 return rc; 2736 } 2737 2738 /** \brief Close the environment and release the memory map. 2739 * \ingroup c_opening 2740 * 2741 * Only a single thread may call this function. All transactions, databases, 2742 * and cursors must already be closed before calling this function. Attempts 2743 * to use any such handles after calling this function will cause a `SIGSEGV`. 2744 * The environment handle will be freed and must not be used again after this 2745 * call. 2746 * 2747 * \param [in] env An environment handle returned by 2748 * \ref mdbx_env_create(). 2749 * 2750 * \param [in] dont_sync A dont'sync flag, if non-zero the last checkpoint 2751 * will be kept "as is" and may be still "weak" in the 2752 * \ref MDBX_SAFE_NOSYNC or \ref MDBX_UTTERLY_NOSYNC 2753 * modes. Such "weak" checkpoint will be ignored on 2754 * opening next time, and transactions since the last 2755 * non-weak checkpoint (meta-page update) will rolledback 2756 * for consistency guarantee. 2757 * 2758 * \returns A non-zero error value on failure and 0 on success, 2759 * some possible errors are: 2760 * \retval MDBX_BUSY The write transaction is running by other thread, 2761 * in such case \ref MDBX_env instance has NOT be destroyed 2762 * not released! 2763 * \note If any OTHER error code was returned then 2764 * given MDBX_env instance has been destroyed and released. 2765 * 2766 * \retval MDBX_EBADSIGN Environment handle already closed or not valid, 2767 * i.e. \ref mdbx_env_close() was already called for the 2768 * `env` or was not created by \ref mdbx_env_create(). 2769 * 2770 * \retval MDBX_PANIC If \ref mdbx_env_close_ex() was called in the child 2771 * process after `fork()`. In this case \ref MDBX_PANIC 2772 * is expected, i.e. \ref MDBX_env instance was freed in 2773 * proper manner. 2774 * 2775 * \retval MDBX_EIO An error occurred during synchronization. */ 2776 LIBMDBX_API int mdbx_env_close_ex(MDBX_env *env, bool dont_sync); 2777 2778 /** \brief The shortcut to calling \ref mdbx_env_close_ex() with 2779 * the `dont_sync=false` argument. 2780 * \ingroup c_opening */ 2781 LIBMDBX_INLINE_API(int, mdbx_env_close, (MDBX_env * env)) { 2782 return mdbx_env_close_ex(env, false); 2783 } 2784 2785 /** \brief Set environment flags. 2786 * \ingroup c_settings 2787 * 2788 * This may be used to set some flags in addition to those from 2789 * mdbx_env_open(), or to unset these flags. 2790 * \see mdbx_env_get_flags() 2791 * 2792 * \note In contrast to LMDB, the MDBX serialize threads via mutex while 2793 * changing the flags. Therefore this function will be blocked while a write 2794 * transaction running by other thread, or \ref MDBX_BUSY will be returned if 2795 * function called within a write transaction. 2796 * 2797 * \param [in] env An environment handle returned 2798 * by \ref mdbx_env_create(). 2799 * \param [in] flags The \ref env_flags to change, bitwise OR'ed together. 2800 * \param [in] onoff A non-zero value sets the flags, zero clears them. 2801 * 2802 * \returns A non-zero error value on failure and 0 on success, 2803 * some possible errors are: 2804 * \retval MDBX_EINVAL An invalid parameter was specified. */ 2805 LIBMDBX_API int mdbx_env_set_flags(MDBX_env *env, MDBX_env_flags_t flags, 2806 bool onoff); 2807 2808 /** \brief Get environment flags. 2809 * \ingroup c_statinfo 2810 * \see mdbx_env_set_flags() 2811 * 2812 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 2813 * \param [out] flags The address of an integer to store the flags. 2814 * 2815 * \returns A non-zero error value on failure and 0 on success, 2816 * some possible errors are: 2817 * \retval MDBX_EINVAL An invalid parameter was specified. */ 2818 LIBMDBX_API int mdbx_env_get_flags(const MDBX_env *env, unsigned *flags); 2819 2820 /** \brief Return the path that was used in mdbx_env_open(). 2821 * \ingroup c_statinfo 2822 * 2823 * \param [in] env An environment handle returned by \ref mdbx_env_create() 2824 * \param [out] dest Address of a string pointer to contain the path. 2825 * This is the actual string in the environment, not a 2826 * copy. It should not be altered in any way. 2827 * 2828 * \returns A non-zero error value on failure and 0 on success, 2829 * some possible errors are: 2830 * \retval MDBX_EINVAL An invalid parameter was specified. */ 2831 #if !(defined(_WIN32) || defined(_WIN64)) 2832 LIBMDBX_API int mdbx_env_get_path(const MDBX_env *env, const char **dest); 2833 #else 2834 LIBMDBX_API int mdbx_env_get_pathW(const MDBX_env *env, const wchar_t **dest); 2835 #endif /* Windows */ 2836 2837 /** \brief Return the file descriptor for the given environment. 2838 * \ingroup c_statinfo 2839 * 2840 * \note All MDBX file descriptors have `FD_CLOEXEC` and 2841 * couldn't be used after exec() and or `fork()`. 2842 * 2843 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 2844 * \param [out] fd Address of a int to contain the descriptor. 2845 * 2846 * \returns A non-zero error value on failure and 0 on success, 2847 * some possible errors are: 2848 * \retval MDBX_EINVAL An invalid parameter was specified. */ 2849 LIBMDBX_API int mdbx_env_get_fd(const MDBX_env *env, mdbx_filehandle_t *fd); 2850 2851 /** \brief Set all size-related parameters of environment, including page size 2852 * and the min/max size of the memory map. 2853 * \ingroup c_settings 2854 * 2855 * In contrast to LMDB, the MDBX provide automatic size management of an 2856 * database according the given parameters, including shrinking and resizing 2857 * on the fly. From user point of view all of these just working. Nevertheless, 2858 * it is reasonable to know some details in order to make optimal decisions 2859 * when choosing parameters. 2860 * 2861 * Both \ref mdbx_env_set_geometry() and legacy \ref mdbx_env_set_mapsize() are 2862 * inapplicable to read-only opened environment. 2863 * 2864 * Both \ref mdbx_env_set_geometry() and legacy \ref mdbx_env_set_mapsize() 2865 * could be called either before or after \ref mdbx_env_open(), either within 2866 * the write transaction running by current thread or not: 2867 * 2868 * - In case \ref mdbx_env_set_geometry() or legacy \ref mdbx_env_set_mapsize() 2869 * was called BEFORE \ref mdbx_env_open(), i.e. for closed environment, then 2870 * the specified parameters will be used for new database creation, 2871 * or will be applied during opening if database exists and no other process 2872 * using it. 2873 * 2874 * If the database is already exist, opened with \ref MDBX_EXCLUSIVE or not 2875 * used by any other process, and parameters specified by 2876 * \ref mdbx_env_set_geometry() are incompatible (i.e. for instance, 2877 * different page size) then \ref mdbx_env_open() will return 2878 * \ref MDBX_INCOMPATIBLE error. 2879 * 2880 * In another way, if database will opened read-only or will used by other 2881 * process during calling \ref mdbx_env_open() that specified parameters will 2882 * silently discarded (open the database with \ref MDBX_EXCLUSIVE flag 2883 * to avoid this). 2884 * 2885 * - In case \ref mdbx_env_set_geometry() or legacy \ref mdbx_env_set_mapsize() 2886 * was called after \ref mdbx_env_open() WITHIN the write transaction running 2887 * by current thread, then specified parameters will be applied as a part of 2888 * write transaction, i.e. will not be completely visible to any others 2889 * processes until the current write transaction has been committed by the 2890 * current process. However, if transaction will be aborted, then the 2891 * database file will be reverted to the previous size not immediately, but 2892 * when a next transaction will be committed or when the database will be 2893 * opened next time. 2894 * 2895 * - In case \ref mdbx_env_set_geometry() or legacy \ref mdbx_env_set_mapsize() 2896 * was called after \ref mdbx_env_open() but OUTSIDE a write transaction, 2897 * then MDBX will execute internal pseudo-transaction to apply new parameters 2898 * (but only if anything has been changed), and changes be visible to any 2899 * others processes immediately after succesful completion of function. 2900 * 2901 * Essentially a concept of "automatic size management" is simple and useful: 2902 * - There are the lower and upper bounds of the database file size; 2903 * - There is the growth step by which the database file will be increased, 2904 * in case of lack of space; 2905 * - There is the threshold for unused space, beyond which the database file 2906 * will be shrunk; 2907 * - The size of the memory map is also the maximum size of the database; 2908 * - MDBX will automatically manage both the size of the database and the size 2909 * of memory map, according to the given parameters. 2910 * 2911 * So, there some considerations about choosing these parameters: 2912 * - The lower bound allows you to prevent database shrinking below certain 2913 * reasonable size to avoid unnecessary resizing costs. 2914 * - The upper bound allows you to prevent database growth above certain 2915 * reasonable size. Besides, the upper bound defines the linear address space 2916 * reservation in each process that opens the database. Therefore changing 2917 * the upper bound is costly and may be required reopening environment in 2918 * case of \ref MDBX_UNABLE_EXTEND_MAPSIZE errors, and so on. Therefore, this 2919 * value should be chosen reasonable large, to accommodate future growth of 2920 * the database. 2921 * - The growth step must be greater than zero to allow the database to grow, 2922 * but also reasonable not too small, since increasing the size by little 2923 * steps will result a large overhead. 2924 * - The shrink threshold must be greater than zero to allow the database 2925 * to shrink but also reasonable not too small (to avoid extra overhead) and 2926 * not less than growth step to avoid up-and-down flouncing. 2927 * - The current size (i.e. `size_now` argument) is an auxiliary parameter for 2928 * simulation legacy \ref mdbx_env_set_mapsize() and as workaround Windows 2929 * issues (see below). 2930 * 2931 * Unfortunately, Windows has is a several issue 2932 * with resizing of memory-mapped file: 2933 * - Windows unable shrinking a memory-mapped file (i.e memory-mapped section) 2934 * in any way except unmapping file entirely and then map again. Moreover, 2935 * it is impossible in any way when a memory-mapped file is used more than 2936 * one process. 2937 * - Windows does not provide the usual API to augment a memory-mapped file 2938 * (i.e. a memory-mapped partition), but only by using "Native API" 2939 * in an undocumented way. 2940 * 2941 * MDBX bypasses all Windows issues, but at a cost: 2942 * - Ability to resize database on the fly requires an additional lock 2943 * and release `SlimReadWriteLock` during each read-only transaction. 2944 * - During resize all in-process threads should be paused and then resumed. 2945 * - Shrinking of database file is performed only when it used by single 2946 * process, i.e. when a database closes by the last process or opened 2947 * by the first. 2948 * = Therefore, the size_now argument may be useful to set database size 2949 * by the first process which open a database, and thus avoid expensive 2950 * remapping further. 2951 * 2952 * For create a new database with particular parameters, including the page 2953 * size, \ref mdbx_env_set_geometry() should be called after 2954 * \ref mdbx_env_create() and before \ref mdbx_env_open(). Once the database is 2955 * created, the page size cannot be changed. If you do not specify all or some 2956 * of the parameters, the corresponding default values will be used. For 2957 * instance, the default for database size is 10485760 bytes. 2958 * 2959 * If the mapsize is increased by another process, MDBX silently and 2960 * transparently adopt these changes at next transaction start. However, 2961 * \ref mdbx_txn_begin() will return \ref MDBX_UNABLE_EXTEND_MAPSIZE if new 2962 * mapping size could not be applied for current process (for instance if 2963 * address space is busy). Therefore, in the case of 2964 * \ref MDBX_UNABLE_EXTEND_MAPSIZE error you need close and reopen the 2965 * environment to resolve error. 2966 * 2967 * \note Actual values may be different than your have specified because of 2968 * rounding to specified database page size, the system page size and/or the 2969 * size of the system virtual memory management unit. You can get actual values 2970 * by \ref mdbx_env_sync_ex() or see by using the tool `mdbx_chk` with the `-v` 2971 * option. 2972 * 2973 * Legacy \ref mdbx_env_set_mapsize() correspond to calling 2974 * \ref mdbx_env_set_geometry() with the arguments `size_lower`, `size_now`, 2975 * `size_upper` equal to the `size` and `-1` (i.e. default) for all other 2976 * parameters. 2977 * 2978 * \param [in] env An environment handle returned 2979 * by \ref mdbx_env_create() 2980 * 2981 * \param [in] size_lower The lower bound of database size in bytes. 2982 * Zero value means "minimal acceptable", 2983 * and negative means "keep current or use default". 2984 * 2985 * \param [in] size_now The size in bytes to setup the database size for 2986 * now. Zero value means "minimal acceptable", and 2987 * negative means "keep current or use default". So, 2988 * it is recommended always pass -1 in this argument 2989 * except some special cases. 2990 * 2991 * \param [in] size_upper The upper bound of database size in bytes. 2992 * Zero value means "minimal acceptable", 2993 * and negative means "keep current or use default". 2994 * It is recommended to avoid change upper bound while 2995 * database is used by other processes or threaded 2996 * (i.e. just pass -1 in this argument except absolutely 2997 * necessary). Otherwise you must be ready for 2998 * \ref MDBX_UNABLE_EXTEND_MAPSIZE error(s), unexpected 2999 * pauses during remapping and/or system errors like 3000 * "address busy", and so on. In other words, there 3001 * is no way to handle a growth of the upper bound 3002 * robustly because there may be a lack of appropriate 3003 * system resources (which are extremely volatile in 3004 * a multi-process multi-threaded environment). 3005 * 3006 * \param [in] growth_step The growth step in bytes, must be greater than 3007 * zero to allow the database to grow. Negative value 3008 * means "keep current or use default". 3009 * 3010 * \param [in] shrink_threshold The shrink threshold in bytes, must be greater 3011 * than zero to allow the database to shrink and 3012 * greater than growth_step to avoid shrinking 3013 * right after grow. 3014 * Negative value means "keep current 3015 * or use default". Default is 2*growth_step. 3016 * 3017 * \param [in] pagesize The database page size for new database 3018 * creation or -1 otherwise. Once the database 3019 * is created, the page size cannot be changed. 3020 * Must be power of 2 in the range between 3021 * \ref MDBX_MIN_PAGESIZE and 3022 * \ref MDBX_MAX_PAGESIZE. Zero value means 3023 * "minimal acceptable", and negative means 3024 * "keep current or use default". 3025 * 3026 * \returns A non-zero error value on failure and 0 on success, 3027 * some possible errors are: 3028 * \retval MDBX_EINVAL An invalid parameter was specified, 3029 * or the environment has an active write transaction. 3030 * \retval MDBX_EPERM Two specific cases for Windows: 3031 * 1) Shrinking was disabled before via geometry settings 3032 * and now it enabled, but there are reading threads that 3033 * don't use the additional `SRWL` (which is required to 3034 * avoid Windows issues). 3035 * 2) Temporary close memory mapped is required to change 3036 * geometry, but there read transaction(s) is running 3037 * and no corresponding thread(s) could be suspended 3038 * since the \ref MDBX_NOTLS mode is used. 3039 * \retval MDBX_EACCESS The environment opened in read-only. 3040 * \retval MDBX_MAP_FULL Specified size smaller than the space already 3041 * consumed by the environment. 3042 * \retval MDBX_TOO_LARGE Specified size is too large, i.e. too many pages for 3043 * given size, or a 32-bit process requests too much 3044 * bytes for the 32-bit address space. */ 3045 LIBMDBX_API int mdbx_env_set_geometry(MDBX_env *env, intptr_t size_lower, 3046 intptr_t size_now, intptr_t size_upper, 3047 intptr_t growth_step, 3048 intptr_t shrink_threshold, 3049 intptr_t pagesize); 3050 3051 /** \deprecated Please use \ref mdbx_env_set_geometry() instead. 3052 * \ingroup c_settings */ 3053 MDBX_DEPRECATED LIBMDBX_INLINE_API(int, mdbx_env_set_mapsize, 3054 (MDBX_env * env, size_t size)) { 3055 return mdbx_env_set_geometry(env, size, size, size, -1, -1, -1); 3056 } 3057 3058 /** \brief Find out whether to use readahead or not, based on the given database 3059 * size and the amount of available memory. 3060 * \ingroup c_extra 3061 * 3062 * \param [in] volume The expected database size in bytes. 3063 * \param [in] redundancy Additional reserve or overload in case of negative 3064 * value. 3065 * 3066 * \returns A \ref MDBX_RESULT_TRUE or \ref MDBX_RESULT_FALSE value, 3067 * otherwise the error code: 3068 * \retval MDBX_RESULT_TRUE Readahead is reasonable. 3069 * \retval MDBX_RESULT_FALSE Readahead is NOT reasonable, 3070 * i.e. \ref MDBX_NORDAHEAD is useful to 3071 * open environment by \ref mdbx_env_open(). 3072 * \retval Otherwise the error code. */ 3073 LIBMDBX_API int mdbx_is_readahead_reasonable(size_t volume, 3074 intptr_t redundancy); 3075 3076 /** \brief Returns the minimal database page size in bytes. 3077 * \ingroup c_statinfo */ 3078 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_INLINE_API(intptr_t, mdbx_limits_pgsize_min, 3079 (void)) { 3080 return MDBX_MIN_PAGESIZE; 3081 } 3082 3083 /** \brief Returns the maximal database page size in bytes. 3084 * \ingroup c_statinfo */ 3085 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_INLINE_API(intptr_t, mdbx_limits_pgsize_max, 3086 (void)) { 3087 return MDBX_MAX_PAGESIZE; 3088 } 3089 3090 /** \brief Returns minimal database size in bytes for given page size, 3091 * or -1 if pagesize is invalid. 3092 * \ingroup c_statinfo */ 3093 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API intptr_t 3094 mdbx_limits_dbsize_min(intptr_t pagesize); 3095 3096 /** \brief Returns maximal database size in bytes for given page size, 3097 * or -1 if pagesize is invalid. 3098 * \ingroup c_statinfo */ 3099 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API intptr_t 3100 mdbx_limits_dbsize_max(intptr_t pagesize); 3101 3102 /** \brief Returns maximal key size in bytes for given page size 3103 * and database flags, or -1 if pagesize is invalid. 3104 * \ingroup c_statinfo 3105 * \see db_flags */ 3106 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API intptr_t 3107 mdbx_limits_keysize_max(intptr_t pagesize, MDBX_db_flags_t flags); 3108 3109 /** \brief Returns maximal data size in bytes for given page size 3110 * and database flags, or -1 if pagesize is invalid. 3111 * \ingroup c_statinfo 3112 * \see db_flags */ 3113 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API intptr_t 3114 mdbx_limits_valsize_max(intptr_t pagesize, MDBX_db_flags_t flags); 3115 3116 /** \brief Returns maximal write transaction size (i.e. limit for summary volume 3117 * of dirty pages) in bytes for given page size, or -1 if pagesize is invalid. 3118 * \ingroup c_statinfo */ 3119 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API intptr_t 3120 mdbx_limits_txnsize_max(intptr_t pagesize); 3121 3122 /** \brief Set the maximum number of threads/reader slots for for all processes 3123 * interacts with the database. 3124 * \ingroup c_settings 3125 * 3126 * \details This defines the number of slots in the lock table that is used to 3127 * track readers in the the environment. The default is about 100 for 4K system 3128 * page size. Starting a read-only transaction normally ties a lock table slot 3129 * to the current thread until the environment closes or the thread exits. If 3130 * \ref MDBX_NOTLS is in use, \ref mdbx_txn_begin() instead ties the slot to the 3131 * \ref MDBX_txn object until it or the \ref MDBX_env object is destroyed. 3132 * This function may only be called after \ref mdbx_env_create() and before 3133 * \ref mdbx_env_open(), and has an effect only when the database is opened by 3134 * the first process interacts with the database. 3135 * \see mdbx_env_get_maxreaders() 3136 * 3137 * \param [in] env An environment handle returned 3138 * by \ref mdbx_env_create(). 3139 * \param [in] readers The maximum number of reader lock table slots. 3140 * 3141 * \returns A non-zero error value on failure and 0 on success, 3142 * some possible errors are: 3143 * \retval MDBX_EINVAL An invalid parameter was specified. 3144 * \retval MDBX_EPERM The environment is already open. */ 3145 LIBMDBX_INLINE_API(int, mdbx_env_set_maxreaders, 3146 (MDBX_env * env, unsigned readers)) { 3147 return mdbx_env_set_option(env, MDBX_opt_max_readers, readers); 3148 } 3149 3150 /** \brief Get the maximum number of threads/reader slots for the environment. 3151 * \ingroup c_statinfo 3152 * \see mdbx_env_set_maxreaders() 3153 * 3154 * \param [in] env An environment handle returned 3155 * by \ref mdbx_env_create(). 3156 * \param [out] readers Address of an integer to store the number of readers. 3157 * 3158 * \returns A non-zero error value on failure and 0 on success, 3159 * some possible errors are: 3160 * \retval MDBX_EINVAL An invalid parameter was specified. */ 3161 LIBMDBX_INLINE_API(int, mdbx_env_get_maxreaders, 3162 (const MDBX_env *env, unsigned *readers)) { 3163 int rc = MDBX_EINVAL; 3164 if (readers) { 3165 uint64_t proxy = 0; 3166 rc = mdbx_env_get_option(env, MDBX_opt_max_readers, &proxy); 3167 *readers = (unsigned)proxy; 3168 } 3169 return rc; 3170 } 3171 3172 /** \brief Set the maximum number of named databases for the environment. 3173 * \ingroup c_settings 3174 * 3175 * This function is only needed if multiple databases will be used in the 3176 * environment. Simpler applications that use the environment as a single 3177 * unnamed database can ignore this option. 3178 * This function may only be called after \ref mdbx_env_create() and before 3179 * \ref mdbx_env_open(). 3180 * 3181 * Currently a moderate number of slots are cheap but a huge number gets 3182 * expensive: 7-120 words per transaction, and every \ref mdbx_dbi_open() 3183 * does a linear search of the opened slots. 3184 * \see mdbx_env_get_maxdbs() 3185 * 3186 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 3187 * \param [in] dbs The maximum number of databases. 3188 * 3189 * \returns A non-zero error value on failure and 0 on success, 3190 * some possible errors are: 3191 * \retval MDBX_EINVAL An invalid parameter was specified. 3192 * \retval MDBX_EPERM The environment is already open. */ 3193 LIBMDBX_INLINE_API(int, mdbx_env_set_maxdbs, (MDBX_env * env, MDBX_dbi dbs)) { 3194 return mdbx_env_set_option(env, MDBX_opt_max_db, dbs); 3195 } 3196 3197 /** \brief Get the maximum number of named databases for the environment. 3198 * \ingroup c_statinfo 3199 * \see mdbx_env_set_maxdbs() 3200 * 3201 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 3202 * \param [out] dbs Address to store the maximum number of databases. 3203 * 3204 * \returns A non-zero error value on failure and 0 on success, 3205 * some possible errors are: 3206 * \retval MDBX_EINVAL An invalid parameter was specified. */ 3207 LIBMDBX_INLINE_API(int, mdbx_env_get_maxdbs, 3208 (const MDBX_env *env, MDBX_dbi *dbs)) { 3209 int rc = MDBX_EINVAL; 3210 if (dbs) { 3211 uint64_t proxy = 0; 3212 rc = mdbx_env_get_option(env, MDBX_opt_max_db, &proxy); 3213 *dbs = (MDBX_dbi)proxy; 3214 } 3215 return rc; 3216 } 3217 3218 /** \brief Returns the default size of database page for the current system. 3219 * \ingroup c_statinfo 3220 * \details Default size of database page depends on the size of the system 3221 * page and usually exactly match it. */ 3222 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API size_t mdbx_default_pagesize(void); 3223 3224 /** \brief Returns basic information about system RAM. 3225 * This function provides a portable way to get information about available RAM 3226 * and can be useful in that it returns the same information that libmdbx uses 3227 * internally to adjust various options and control readahead. 3228 * \ingroup c_statinfo 3229 * 3230 * \param [out] page_size Optional address where the system page size 3231 * will be stored. 3232 * \param [out] total_pages Optional address where the number of total RAM 3233 * pages will be stored. 3234 * \param [out] avail_pages Optional address where the number of 3235 * available/free RAM pages will be stored. 3236 * 3237 * \returns A non-zero error value on failure and 0 on success. */ 3238 LIBMDBX_API int mdbx_get_sysraminfo(intptr_t *page_size, intptr_t *total_pages, 3239 intptr_t *avail_pages); 3240 3241 /** \brief Returns the maximum size of keys can put. 3242 * \ingroup c_statinfo 3243 * 3244 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 3245 * \param [in] flags Database options (\ref MDBX_DUPSORT, \ref MDBX_INTEGERKEY 3246 * and so on). \see db_flags 3247 * 3248 * \returns The maximum size of a key can write, 3249 * or -1 if something is wrong. */ 3250 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int 3251 mdbx_env_get_maxkeysize_ex(const MDBX_env *env, MDBX_db_flags_t flags); 3252 3253 /** \brief Returns the maximum size of data we can put. 3254 * \ingroup c_statinfo 3255 * 3256 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 3257 * \param [in] flags Database options (\ref MDBX_DUPSORT, \ref MDBX_INTEGERKEY 3258 * and so on). \see db_flags 3259 * 3260 * \returns The maximum size of a data can write, 3261 * or -1 if something is wrong. */ 3262 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int 3263 mdbx_env_get_maxvalsize_ex(const MDBX_env *env, MDBX_db_flags_t flags); 3264 3265 /** \deprecated Please use \ref mdbx_env_get_maxkeysize_ex() 3266 * and/or \ref mdbx_env_get_maxvalsize_ex() 3267 * \ingroup c_statinfo */ 3268 MDBX_DEPRECATED MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int 3269 mdbx_env_get_maxkeysize(const MDBX_env *env); 3270 3271 /** \brief Sets application information (a context pointer) associated with 3272 * the environment. 3273 * \see mdbx_env_get_userctx() 3274 * \ingroup c_settings 3275 * 3276 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 3277 * \param [in] ctx An arbitrary pointer for whatever the application needs. 3278 * 3279 * \returns A non-zero error value on failure and 0 on success. */ 3280 LIBMDBX_API int mdbx_env_set_userctx(MDBX_env *env, void *ctx); 3281 3282 /** \brief Returns an application information (a context pointer) associated 3283 * with the environment. 3284 * \see mdbx_env_set_userctx() 3285 * \ingroup c_statinfo 3286 * 3287 * \param [in] env An environment handle returned by \ref mdbx_env_create() 3288 * \returns The pointer set by \ref mdbx_env_set_userctx() 3289 * or `NULL` if something wrong. */ 3290 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API void * 3291 mdbx_env_get_userctx(const MDBX_env *env); 3292 3293 /** \brief Create a transaction with a user provided context pointer 3294 * for use with the environment. 3295 * \ingroup c_transactions 3296 * 3297 * The transaction handle may be discarded using \ref mdbx_txn_abort() 3298 * or \ref mdbx_txn_commit(). 3299 * \see mdbx_txn_begin() 3300 * 3301 * \note A transaction and its cursors must only be used by a single thread, 3302 * and a thread may only have a single transaction at a time. If \ref MDBX_NOTLS 3303 * is in use, this does not apply to read-only transactions. 3304 * 3305 * \note Cursors may not span transactions. 3306 * 3307 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 3308 * 3309 * \param [in] parent If this parameter is non-NULL, the new transaction will 3310 * be a nested transaction, with the transaction indicated 3311 * by parent as its parent. Transactions may be nested 3312 * to any level. A parent transaction and its cursors may 3313 * not issue any other operations than mdbx_txn_commit and 3314 * \ref mdbx_txn_abort() while it has active child 3315 * transactions. 3316 * 3317 * \param [in] flags Special options for this transaction. This parameter 3318 * must be set to 0 or by bitwise OR'ing together one 3319 * or more of the values described here: 3320 * - \ref MDBX_RDONLY This transaction will not perform 3321 * any write operations. 3322 * 3323 * - \ref MDBX_TXN_TRY Do not block when starting 3324 * a write transaction. 3325 * 3326 * - \ref MDBX_SAFE_NOSYNC, \ref MDBX_NOMETASYNC. 3327 * Do not sync data to disk corresponding 3328 * to \ref MDBX_NOMETASYNC or \ref MDBX_SAFE_NOSYNC 3329 * description. \see sync_modes 3330 * 3331 * \param [out] txn Address where the new \ref MDBX_txn handle 3332 * will be stored. 3333 * 3334 * \param [in] context A pointer to application context to be associated with 3335 * created transaction and could be retrieved by 3336 * \ref mdbx_txn_get_userctx() until transaction finished. 3337 * 3338 * \returns A non-zero error value on failure and 0 on success, 3339 * some possible errors are: 3340 * \retval MDBX_PANIC A fatal error occurred earlier and the 3341 * environment must be shut down. 3342 * \retval MDBX_UNABLE_EXTEND_MAPSIZE Another process wrote data beyond 3343 * this MDBX_env's mapsize and this 3344 * environment map must be resized as well. 3345 * See \ref mdbx_env_set_mapsize(). 3346 * \retval MDBX_READERS_FULL A read-only transaction was requested and 3347 * the reader lock table is full. 3348 * See \ref mdbx_env_set_maxreaders(). 3349 * \retval MDBX_ENOMEM Out of memory. 3350 * \retval MDBX_BUSY The write transaction is already started by the 3351 * current thread. */ 3352 LIBMDBX_API int mdbx_txn_begin_ex(MDBX_env *env, MDBX_txn *parent, 3353 MDBX_txn_flags_t flags, MDBX_txn **txn, 3354 void *context); 3355 3356 /** \brief Create a transaction for use with the environment. 3357 * \ingroup c_transactions 3358 * 3359 * The transaction handle may be discarded using \ref mdbx_txn_abort() 3360 * or \ref mdbx_txn_commit(). 3361 * \see mdbx_txn_begin_ex() 3362 * 3363 * \note A transaction and its cursors must only be used by a single thread, 3364 * and a thread may only have a single transaction at a time. If \ref MDBX_NOTLS 3365 * is in use, this does not apply to read-only transactions. 3366 * 3367 * \note Cursors may not span transactions. 3368 * 3369 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 3370 * 3371 * \param [in] parent If this parameter is non-NULL, the new transaction will 3372 * be a nested transaction, with the transaction indicated 3373 * by parent as its parent. Transactions may be nested 3374 * to any level. A parent transaction and its cursors may 3375 * not issue any other operations than mdbx_txn_commit and 3376 * \ref mdbx_txn_abort() while it has active child 3377 * transactions. 3378 * 3379 * \param [in] flags Special options for this transaction. This parameter 3380 * must be set to 0 or by bitwise OR'ing together one 3381 * or more of the values described here: 3382 * - \ref MDBX_RDONLY This transaction will not perform 3383 * any write operations. 3384 * 3385 * - \ref MDBX_TXN_TRY Do not block when starting 3386 * a write transaction. 3387 * 3388 * - \ref MDBX_SAFE_NOSYNC, \ref MDBX_NOMETASYNC. 3389 * Do not sync data to disk corresponding 3390 * to \ref MDBX_NOMETASYNC or \ref MDBX_SAFE_NOSYNC 3391 * description. \see sync_modes 3392 * 3393 * \param [out] txn Address where the new \ref MDBX_txn handle 3394 * will be stored. 3395 * 3396 * \returns A non-zero error value on failure and 0 on success, 3397 * some possible errors are: 3398 * \retval MDBX_PANIC A fatal error occurred earlier and the 3399 * environment must be shut down. 3400 * \retval MDBX_UNABLE_EXTEND_MAPSIZE Another process wrote data beyond 3401 * this MDBX_env's mapsize and this 3402 * environment map must be resized as well. 3403 * See \ref mdbx_env_set_mapsize(). 3404 * \retval MDBX_READERS_FULL A read-only transaction was requested and 3405 * the reader lock table is full. 3406 * See \ref mdbx_env_set_maxreaders(). 3407 * \retval MDBX_ENOMEM Out of memory. 3408 * \retval MDBX_BUSY The write transaction is already started by the 3409 * current thread. */ 3410 LIBMDBX_INLINE_API(int, mdbx_txn_begin, 3411 (MDBX_env * env, MDBX_txn *parent, MDBX_txn_flags_t flags, 3412 MDBX_txn **txn)) { 3413 return mdbx_txn_begin_ex(env, parent, flags, txn, NULL); 3414 } 3415 3416 /** \brief Sets application information associated (a context pointer) with the 3417 * transaction. 3418 * \ingroup c_transactions 3419 * \see mdbx_txn_get_userctx() 3420 * 3421 * \param [in] txn An transaction handle returned by \ref mdbx_txn_begin_ex() 3422 * or \ref mdbx_txn_begin(). 3423 * \param [in] ctx An arbitrary pointer for whatever the application needs. 3424 * 3425 * \returns A non-zero error value on failure and 0 on success. */ 3426 LIBMDBX_API int mdbx_txn_set_userctx(MDBX_txn *txn, void *ctx); 3427 3428 /** \brief Returns an application information (a context pointer) associated 3429 * with the transaction. 3430 * \ingroup c_transactions 3431 * \see mdbx_txn_set_userctx() 3432 * 3433 * \param [in] txn An transaction handle returned by \ref mdbx_txn_begin_ex() 3434 * or \ref mdbx_txn_begin(). 3435 * \returns The pointer which was passed via the `context` parameter 3436 * of `mdbx_txn_begin_ex()` or set by \ref mdbx_txn_set_userctx(), 3437 * or `NULL` if something wrong. */ 3438 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API void * 3439 mdbx_txn_get_userctx(const MDBX_txn *txn); 3440 3441 /** \brief Information about the transaction 3442 * \ingroup c_statinfo 3443 * \see mdbx_txn_info */ 3444 struct MDBX_txn_info { 3445 /** The ID of the transaction. For a READ-ONLY transaction, this corresponds 3446 to the snapshot being read. */ 3447 uint64_t txn_id; 3448 3449 /** For READ-ONLY transaction: the lag from a recent MVCC-snapshot, i.e. the 3450 number of committed transaction since read transaction started. 3451 For WRITE transaction (provided if `scan_rlt=true`): the lag of the oldest 3452 reader from current transaction (i.e. at least 1 if any reader running). */ 3453 uint64_t txn_reader_lag; 3454 3455 /** Used space by this transaction, i.e. corresponding to the last used 3456 * database page. */ 3457 uint64_t txn_space_used; 3458 3459 /** Current size of database file. */ 3460 uint64_t txn_space_limit_soft; 3461 3462 /** Upper bound for size the database file, i.e. the value `size_upper` 3463 argument of the appropriate call of \ref mdbx_env_set_geometry(). */ 3464 uint64_t txn_space_limit_hard; 3465 3466 /** For READ-ONLY transaction: The total size of the database pages that were 3467 retired by committed write transactions after the reader's MVCC-snapshot, 3468 i.e. the space which would be freed after the Reader releases the 3469 MVCC-snapshot for reuse by completion read transaction. 3470 For WRITE transaction: The summarized size of the database pages that were 3471 retired for now due Copy-On-Write during this transaction. */ 3472 uint64_t txn_space_retired; 3473 3474 /** For READ-ONLY transaction: the space available for writer(s) and that 3475 must be exhausted for reason to call the Handle-Slow-Readers callback for 3476 this read transaction. 3477 For WRITE transaction: the space inside transaction 3478 that left to `MDBX_TXN_FULL` error. */ 3479 uint64_t txn_space_leftover; 3480 3481 /** For READ-ONLY transaction (provided if `scan_rlt=true`): The space that 3482 actually become available for reuse when only this transaction will be 3483 finished. 3484 For WRITE transaction: The summarized size of the dirty database 3485 pages that generated during this transaction. */ 3486 uint64_t txn_space_dirty; 3487 }; 3488 #ifndef __cplusplus 3489 /** \ingroup c_statinfo */ 3490 typedef struct MDBX_txn_info MDBX_txn_info; 3491 #endif 3492 3493 /** \brief Return information about the MDBX transaction. 3494 * \ingroup c_statinfo 3495 * 3496 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin() 3497 * \param [out] info The address of an \ref MDBX_txn_info structure 3498 * where the information will be copied. 3499 * \param [in] scan_rlt The boolean flag controls the scan of the read lock 3500 * table to provide complete information. Such scan 3501 * is relatively expensive and you can avoid it 3502 * if corresponding fields are not needed. 3503 * See description of \ref MDBX_txn_info. 3504 * 3505 * \returns A non-zero error value on failure and 0 on success. */ 3506 LIBMDBX_API int mdbx_txn_info(const MDBX_txn *txn, MDBX_txn_info *info, 3507 bool scan_rlt); 3508 3509 /** \brief Returns the transaction's MDBX_env. 3510 * \ingroup c_transactions 3511 * 3512 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin() */ 3513 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API MDBX_env * 3514 mdbx_txn_env(const MDBX_txn *txn); 3515 3516 /** \brief Return the transaction's flags. 3517 * \ingroup c_transactions 3518 * 3519 * This returns the flags, including internal, associated with this transaction. 3520 * 3521 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 3522 * 3523 * \returns A transaction flags, valid if input is an valid transaction, 3524 * otherwise -1. */ 3525 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int mdbx_txn_flags(const MDBX_txn *txn); 3526 3527 /** \brief Return the transaction's ID. 3528 * \ingroup c_statinfo 3529 * 3530 * This returns the identifier associated with this transaction. For a 3531 * read-only transaction, this corresponds to the snapshot being read; 3532 * concurrent readers will frequently have the same transaction ID. 3533 * 3534 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 3535 * 3536 * \returns A transaction ID, valid if input is an active transaction, 3537 * otherwise 0. */ 3538 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API uint64_t 3539 mdbx_txn_id(const MDBX_txn *txn); 3540 3541 /** \brief Latency of commit stages in 1/65536 of seconds units. 3542 * \warning This structure may be changed in future releases. 3543 * \ingroup c_statinfo 3544 * \see mdbx_txn_commit_ex() */ 3545 struct MDBX_commit_latency { 3546 /** \brief Duration of preparation (commit child transactions, update 3547 * sub-databases records and cursors destroying). */ 3548 uint32_t preparation; 3549 /** \brief Duration of GC/freeDB handling & updation. */ 3550 uint32_t gc; 3551 /** \brief Duration of internal audit if enabled. */ 3552 uint32_t audit; 3553 /** \brief Duration of writing dirty/modified data pages to a filesystem, 3554 * i.e. the summary duration of a `write()` syscalls during commit. */ 3555 uint32_t write; 3556 /** \brief Duration of syncing written data to the disk/storage, i.e. 3557 * the duration of a `fdatasync()` or a `msync()` syscall during commit. */ 3558 uint32_t sync; 3559 /** \brief Duration of transaction ending (releasing resources). */ 3560 uint32_t ending; 3561 /** \brief The total duration of a commit. */ 3562 uint32_t whole; 3563 }; 3564 #ifndef __cplusplus 3565 /** \ingroup c_statinfo */ 3566 typedef struct MDBX_commit_latency MDBX_commit_latency; 3567 #endif 3568 3569 /** \brief Commit all the operations of a transaction into the database and 3570 * collect latency information. 3571 * \see mdbx_txn_commit() 3572 * \ingroup c_transactions 3573 * \warning This function may be changed in future releases. */ 3574 LIBMDBX_API int mdbx_txn_commit_ex(MDBX_txn *txn, MDBX_commit_latency *latency); 3575 3576 /** \brief Commit all the operations of a transaction into the database. 3577 * \ingroup c_transactions 3578 * 3579 * If the current thread is not eligible to manage the transaction then 3580 * the \ref MDBX_THREAD_MISMATCH error will returned. Otherwise the transaction 3581 * will be committed and its handle is freed. If the transaction cannot 3582 * be committed, it will be aborted with the corresponding error returned. 3583 * 3584 * Thus, a result other than \ref MDBX_THREAD_MISMATCH means that the 3585 * transaction is terminated: 3586 * - Resources are released; 3587 * - Transaction handle is invalid; 3588 * - Cursor(s) associated with transaction must not be used, except with 3589 * mdbx_cursor_renew() and \ref mdbx_cursor_close(). 3590 * Such cursor(s) must be closed explicitly by \ref mdbx_cursor_close() 3591 * before or after transaction commit, either can be reused with 3592 * \ref mdbx_cursor_renew() until it will be explicitly closed by 3593 * \ref mdbx_cursor_close(). 3594 * 3595 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 3596 * 3597 * \returns A non-zero error value on failure and 0 on success, 3598 * some possible errors are: 3599 * \retval MDBX_RESULT_TRUE Transaction was aborted since it should 3600 * be aborted due to previous errors. 3601 * \retval MDBX_PANIC A fatal error occurred earlier 3602 * and the environment must be shut down. 3603 * \retval MDBX_BAD_TXN Transaction is already finished or never began. 3604 * \retval MDBX_EBADSIGN Transaction object has invalid signature, 3605 * e.g. transaction was already terminated 3606 * or memory was corrupted. 3607 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 3608 * by current thread. 3609 * \retval MDBX_EINVAL Transaction handle is NULL. 3610 * \retval MDBX_ENOSPC No more disk space. 3611 * \retval MDBX_EIO A system-level I/O error occurred. 3612 * \retval MDBX_ENOMEM Out of memory. */ 3613 LIBMDBX_INLINE_API(int, mdbx_txn_commit, (MDBX_txn * txn)) { 3614 return mdbx_txn_commit_ex(txn, NULL); 3615 } 3616 3617 /** \brief Abandon all the operations of the transaction instead of saving them. 3618 * \ingroup c_transactions 3619 * 3620 * The transaction handle is freed. It and its cursors must not be used again 3621 * after this call, except with \ref mdbx_cursor_renew() and 3622 * \ref mdbx_cursor_close(). 3623 * 3624 * If the current thread is not eligible to manage the transaction then 3625 * the \ref MDBX_THREAD_MISMATCH error will returned. Otherwise the transaction 3626 * will be aborted and its handle is freed. Thus, a result other than 3627 * \ref MDBX_THREAD_MISMATCH means that the transaction is terminated: 3628 * - Resources are released; 3629 * - Transaction handle is invalid; 3630 * - Cursor(s) associated with transaction must not be used, except with 3631 * \ref mdbx_cursor_renew() and \ref mdbx_cursor_close(). 3632 * Such cursor(s) must be closed explicitly by \ref mdbx_cursor_close() 3633 * before or after transaction abort, either can be reused with 3634 * \ref mdbx_cursor_renew() until it will be explicitly closed by 3635 * \ref mdbx_cursor_close(). 3636 * 3637 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 3638 * 3639 * \returns A non-zero error value on failure and 0 on success, 3640 * some possible errors are: 3641 * \retval MDBX_PANIC A fatal error occurred earlier and 3642 * the environment must be shut down. 3643 * \retval MDBX_BAD_TXN Transaction is already finished or never began. 3644 * \retval MDBX_EBADSIGN Transaction object has invalid signature, 3645 * e.g. transaction was already terminated 3646 * or memory was corrupted. 3647 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 3648 * by current thread. 3649 * \retval MDBX_EINVAL Transaction handle is NULL. */ 3650 LIBMDBX_API int mdbx_txn_abort(MDBX_txn *txn); 3651 3652 /** \brief Marks transaction as broken. 3653 * \ingroup c_transactions 3654 * 3655 * Function keeps the transaction handle and corresponding locks, but makes 3656 * impossible to perform any operations within a broken transaction. 3657 * Broken transaction must then be aborted explicitly later. 3658 * 3659 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 3660 * 3661 * \see mdbx_txn_abort() \see mdbx_txn_reset() \see mdbx_txn_commit() 3662 * \returns A non-zero error value on failure and 0 on success. */ 3663 LIBMDBX_API int mdbx_txn_break(MDBX_txn *txn); 3664 3665 /** \brief Reset a read-only transaction. 3666 * \ingroup c_transactions 3667 * 3668 * Abort the read-only transaction like \ref mdbx_txn_abort(), but keep the 3669 * transaction handle. Therefore \ref mdbx_txn_renew() may reuse the handle. 3670 * This saves allocation overhead if the process will start a new read-only 3671 * transaction soon, and also locking overhead if \ref MDBX_NOTLS is in use. The 3672 * reader table lock is released, but the table slot stays tied to its thread 3673 * or \ref MDBX_txn. Use \ref mdbx_txn_abort() to discard a reset handle, and to 3674 * free its lock table slot if \ref MDBX_NOTLS is in use. 3675 * 3676 * Cursors opened within the transaction must not be used again after this 3677 * call, except with \ref mdbx_cursor_renew() and \ref mdbx_cursor_close(). 3678 * 3679 * Reader locks generally don't interfere with writers, but they keep old 3680 * versions of database pages allocated. Thus they prevent the old pages from 3681 * being reused when writers commit new data, and so under heavy load the 3682 * database size may grow much more rapidly than otherwise. 3683 * 3684 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 3685 * 3686 * \returns A non-zero error value on failure and 0 on success, 3687 * some possible errors are: 3688 * \retval MDBX_PANIC A fatal error occurred earlier and 3689 * the environment must be shut down. 3690 * \retval MDBX_BAD_TXN Transaction is already finished or never began. 3691 * \retval MDBX_EBADSIGN Transaction object has invalid signature, 3692 * e.g. transaction was already terminated 3693 * or memory was corrupted. 3694 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 3695 * by current thread. 3696 * \retval MDBX_EINVAL Transaction handle is NULL. */ 3697 LIBMDBX_API int mdbx_txn_reset(MDBX_txn *txn); 3698 3699 /** \brief Renew a read-only transaction. 3700 * \ingroup c_transactions 3701 * 3702 * This acquires a new reader lock for a transaction handle that had been 3703 * released by \ref mdbx_txn_reset(). It must be called before a reset 3704 * transaction may be used again. 3705 * 3706 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 3707 * 3708 * \returns A non-zero error value on failure and 0 on success, 3709 * some possible errors are: 3710 * \retval MDBX_PANIC A fatal error occurred earlier and 3711 * the environment must be shut down. 3712 * \retval MDBX_BAD_TXN Transaction is already finished or never began. 3713 * \retval MDBX_EBADSIGN Transaction object has invalid signature, 3714 * e.g. transaction was already terminated 3715 * or memory was corrupted. 3716 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 3717 * by current thread. 3718 * \retval MDBX_EINVAL Transaction handle is NULL. */ 3719 LIBMDBX_API int mdbx_txn_renew(MDBX_txn *txn); 3720 3721 /** \brief The fours integers markers (aka "canary") associated with the 3722 * environment. 3723 * \ingroup c_crud 3724 * \see mdbx_canary_set() 3725 * \see mdbx_canary_get() 3726 * 3727 * The `x`, `y` and `z` values could be set by \ref mdbx_canary_put(), while the 3728 * 'v' will be always set to the transaction number. Updated values becomes 3729 * visible outside the current transaction only after it was committed. Current 3730 * values could be retrieved by \ref mdbx_canary_get(). */ 3731 struct MDBX_canary { 3732 uint64_t x, y, z, v; 3733 }; 3734 #ifndef __cplusplus 3735 /** \ingroup c_crud */ 3736 typedef struct MDBX_canary MDBX_canary; 3737 #endif 3738 3739 /** \brief Set integers markers (aka "canary") associated with the environment. 3740 * \ingroup c_crud 3741 * \see mdbx_canary_get() 3742 * 3743 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin() 3744 * \param [in] canary A optional pointer to \ref MDBX_canary structure for `x`, 3745 * `y` and `z` values from. 3746 * - If canary is NOT NULL then the `x`, `y` and `z` values will be 3747 * updated from given canary argument, but the 'v' be always set 3748 * to the current transaction number if at least one `x`, `y` or 3749 * `z` values have changed (i.e. if `x`, `y` and `z` have the same 3750 * values as currently present then nothing will be changes or 3751 * updated). 3752 * - if canary is NULL then the `v` value will be explicitly update 3753 * to the current transaction number without changes `x`, `y` nor 3754 * `z`. 3755 * 3756 * \returns A non-zero error value on failure and 0 on success. */ 3757 LIBMDBX_API int mdbx_canary_put(MDBX_txn *txn, const MDBX_canary *canary); 3758 3759 /** \brief Returns fours integers markers (aka "canary") associated with the 3760 * environment. 3761 * \ingroup c_crud 3762 * \see mdbx_canary_set() 3763 * 3764 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 3765 * \param [in] canary The address of an MDBX_canary structure where the 3766 * information will be copied. 3767 * 3768 * \returns A non-zero error value on failure and 0 on success. */ 3769 LIBMDBX_API int mdbx_canary_get(const MDBX_txn *txn, MDBX_canary *canary); 3770 3771 /** \brief A callback function used to compare two keys in a database 3772 * \ingroup c_crud 3773 * \see mdbx_cmp() \see mdbx_get_keycmp() 3774 * \see mdbx_get_datacmp \see mdbx_dcmp() 3775 * 3776 * \anchor avoid_custom_comparators 3777 * It is recommend not using custom comparison functions, but instead 3778 * converting the keys to one of the forms that are suitable for built-in 3779 * comparators (for instance take look to the \ref value2key). 3780 * The reasons to not using custom comparators are: 3781 * - The order of records could not be validated without your code. 3782 * So `mdbx_chk` utility will reports "wrong order" errors 3783 * and the `-i` option is required to suppress ones. 3784 * - A records could not be ordered or sorted without your code. 3785 * So `mdbx_load` utility should be used with `-a` option to preserve 3786 * input data order. 3787 * - However, the custom comparators feature will never be removed. 3788 * You have been warned but still can use custom comparators knowing 3789 * about the issues noted above. In this case you should ignore `deprecated` 3790 * warnings or define `MDBX_DEPRECATED` macro to empty to avoid ones. */ 3791 typedef int(MDBX_cmp_func)(const MDBX_val *a, 3792 const MDBX_val *b) MDBX_CXX17_NOEXCEPT; 3793 3794 /** \brief Open or Create a database in the environment. 3795 * \ingroup c_dbi 3796 * 3797 * A database handle denotes the name and parameters of a database, 3798 * independently of whether such a database exists. The database handle may be 3799 * discarded by calling \ref mdbx_dbi_close(). The old database handle is 3800 * returned if the database was already open. The handle may only be closed 3801 * once. 3802 * 3803 * \note A notable difference between MDBX and LMDB is that MDBX make handles 3804 * opened for existing databases immediately available for other transactions, 3805 * regardless this transaction will be aborted or reset. The REASON for this is 3806 * to avoiding the requirement for multiple opening a same handles in 3807 * concurrent read transactions, and tracking of such open but hidden handles 3808 * until the completion of read transactions which opened them. 3809 * 3810 * Nevertheless, the handle for the NEWLY CREATED database will be invisible 3811 * for other transactions until the this write transaction is successfully 3812 * committed. If the write transaction is aborted the handle will be closed 3813 * automatically. After a successful commit the such handle will reside in the 3814 * shared environment, and may be used by other transactions. 3815 * 3816 * In contrast to LMDB, the MDBX allow this function to be called from multiple 3817 * concurrent transactions or threads in the same process. 3818 * 3819 * To use named database (with name != NULL), \ref mdbx_env_set_maxdbs() 3820 * must be called before opening the environment. Table names are 3821 * keys in the internal unnamed database, and may be read but not written. 3822 * 3823 * \param [in] txn transaction handle returned by \ref mdbx_txn_begin(). 3824 * \param [in] name The name of the database to open. If only a single 3825 * database is needed in the environment, 3826 * this value may be NULL. 3827 * \param [in] flags Special options for this database. This parameter must 3828 * be bitwise OR'ing together any of the constants 3829 * described here: 3830 * 3831 * - \ref MDBX_DB_DEFAULTS 3832 * Keys are arbitrary byte strings and compared from beginning to end. 3833 * - \ref MDBX_REVERSEKEY 3834 * Keys are arbitrary byte strings to be compared in reverse order, 3835 * from the end of the strings to the beginning. 3836 * - \ref MDBX_INTEGERKEY 3837 * Keys are binary integers in native byte order, either uint32_t or 3838 * uint64_t, and will be sorted as such. The keys must all be of the 3839 * same size and must be aligned while passing as arguments. 3840 * - \ref MDBX_DUPSORT 3841 * Duplicate keys may be used in the database. Or, from another point of 3842 * view, keys may have multiple data items, stored in sorted order. By 3843 * default keys must be unique and may have only a single data item. 3844 * - \ref MDBX_DUPFIXED 3845 * This flag may only be used in combination with \ref MDBX_DUPSORT. This 3846 * option tells the library that the data items for this database are 3847 * all the same size, which allows further optimizations in storage and 3848 * retrieval. When all data items are the same size, the 3849 * \ref MDBX_GET_MULTIPLE, \ref MDBX_NEXT_MULTIPLE and 3850 * \ref MDBX_PREV_MULTIPLE cursor operations may be used to retrieve 3851 * multiple items at once. 3852 * - \ref MDBX_INTEGERDUP 3853 * This option specifies that duplicate data items are binary integers, 3854 * similar to \ref MDBX_INTEGERKEY keys. The data values must all be of the 3855 * same size and must be aligned while passing as arguments. 3856 * - \ref MDBX_REVERSEDUP 3857 * This option specifies that duplicate data items should be compared as 3858 * strings in reverse order (the comparison is performed in the direction 3859 * from the last byte to the first). 3860 * - \ref MDBX_CREATE 3861 * Create the named database if it doesn't exist. This option is not 3862 * allowed in a read-only transaction or a read-only environment. 3863 * 3864 * \param [out] dbi Address where the new \ref MDBX_dbi handle 3865 * will be stored. 3866 * 3867 * For \ref mdbx_dbi_open_ex() additional arguments allow you to set custom 3868 * comparison functions for keys and values (for multimaps). 3869 * \see avoid_custom_comparators 3870 * 3871 * \returns A non-zero error value on failure and 0 on success, 3872 * some possible errors are: 3873 * \retval MDBX_NOTFOUND The specified database doesn't exist in the 3874 * environment and \ref MDBX_CREATE was not specified. 3875 * \retval MDBX_DBS_FULL Too many databases have been opened. 3876 * \see mdbx_env_set_maxdbs() 3877 * \retval MDBX_INCOMPATIBLE Database is incompatible with given flags, 3878 * i.e. the passed flags is different with which the 3879 * database was created, or the database was already 3880 * opened with a different comparison function(s). 3881 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 3882 * by current thread. */ 3883 LIBMDBX_API int mdbx_dbi_open(MDBX_txn *txn, const char *name, 3884 MDBX_db_flags_t flags, MDBX_dbi *dbi); 3885 3886 /** \deprecated Please 3887 * \ref avoid_custom_comparators "avoid using custom comparators" and use 3888 * \ref mdbx_dbi_open() instead. 3889 * 3890 * \ingroup c_dbi 3891 * 3892 * \param [in] txn transaction handle returned by \ref mdbx_txn_begin(). 3893 * \param [in] name The name of the database to open. If only a single 3894 * database is needed in the environment, 3895 * this value may be NULL. 3896 * \param [in] flags Special options for this database. 3897 * \param [in] keycmp Optional custom key comparison function for a database. 3898 * \param [in] datacmp Optional custom data comparison function for a database. 3899 * \param [out] dbi Address where the new MDBX_dbi handle will be stored. 3900 * \returns A non-zero error value on failure and 0 on success. */ 3901 MDBX_DEPRECATED LIBMDBX_API int 3902 mdbx_dbi_open_ex(MDBX_txn *txn, const char *name, MDBX_db_flags_t flags, 3903 MDBX_dbi *dbi, MDBX_cmp_func *keycmp, MDBX_cmp_func *datacmp); 3904 3905 /** \defgroup value2key Value-to-Key functions 3906 * \brief Value-to-Key functions to 3907 * \ref avoid_custom_comparators "avoid using custom comparators" 3908 * \see key2value 3909 * @{ 3910 * 3911 * The \ref mdbx_key_from_jsonInteger() build a keys which are comparable with 3912 * keys created by \ref mdbx_key_from_double(). So this allows mixing `int64_t` 3913 * and IEEE754 double values in one index for JSON-numbers with restriction for 3914 * integer numbers range corresponding to RFC-7159, i.e. \f$[-2^{53}+1, 3915 * 2^{53}-1]\f$. See bottom of page 6 at https://tools.ietf.org/html/rfc7159 */ 3916 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API uint64_t 3917 mdbx_key_from_jsonInteger(const int64_t json_integer); 3918 3919 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API uint64_t 3920 mdbx_key_from_double(const double ieee754_64bit); 3921 3922 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API uint64_t 3923 mdbx_key_from_ptrdouble(const double *const ieee754_64bit); 3924 3925 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API uint32_t 3926 mdbx_key_from_float(const float ieee754_32bit); 3927 3928 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API uint32_t 3929 mdbx_key_from_ptrfloat(const float *const ieee754_32bit); 3930 3931 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_INLINE_API(uint64_t, mdbx_key_from_int64, 3932 (const int64_t i64)) { 3933 return UINT64_C(0x8000000000000000) + i64; 3934 } 3935 3936 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_INLINE_API(uint32_t, mdbx_key_from_int32, 3937 (const int32_t i32)) { 3938 return UINT32_C(0x80000000) + i32; 3939 } 3940 /** end of value2key @} */ 3941 3942 /** \defgroup key2value Key-to-Value functions 3943 * \brief Key-to-Value functions to 3944 * \ref avoid_custom_comparators "avoid using custom comparators" 3945 * \see value2key 3946 * @{ */ 3947 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int64_t 3948 mdbx_jsonInteger_from_key(const MDBX_val); 3949 3950 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API double 3951 mdbx_double_from_key(const MDBX_val); 3952 3953 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API float 3954 mdbx_float_from_key(const MDBX_val); 3955 3956 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int32_t 3957 mdbx_int32_from_key(const MDBX_val); 3958 3959 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int64_t 3960 mdbx_int64_from_key(const MDBX_val); 3961 /** end of value2key @} */ 3962 3963 /** \brief Retrieve statistics for a database. 3964 * \ingroup c_statinfo 3965 * 3966 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 3967 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 3968 * \param [out] stat The address of an \ref MDBX_stat structure where 3969 * the statistics will be copied. 3970 * \param [in] bytes The size of \ref MDBX_stat. 3971 * 3972 * \returns A non-zero error value on failure and 0 on success, 3973 * some possible errors are: 3974 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 3975 * by current thread. 3976 * \retval MDBX_EINVAL An invalid parameter was specified. */ 3977 LIBMDBX_API int mdbx_dbi_stat(MDBX_txn *txn, MDBX_dbi dbi, MDBX_stat *stat, 3978 size_t bytes); 3979 3980 /** \brief Retrieve depth (bitmask) information of nested dupsort (multi-value) 3981 * B+trees for given database. 3982 * \ingroup c_statinfo 3983 * 3984 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 3985 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 3986 * \param [out] mask The address of an uint32_t value where the bitmask 3987 * will be stored. 3988 * 3989 * \returns A non-zero error value on failure and 0 on success, 3990 * some possible errors are: 3991 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 3992 * by current thread. 3993 * \retval MDBX_EINVAL An invalid parameter was specified. 3994 * \retval MDBX_RESULT_TRUE The dbi isn't a dupsort (multi-value) database. */ 3995 LIBMDBX_API int mdbx_dbi_dupsort_depthmask(MDBX_txn *txn, MDBX_dbi dbi, 3996 uint32_t *mask); 3997 3998 /** \brief DBI state bits returted by \ref mdbx_dbi_flags_ex() 3999 * \ingroup c_statinfo 4000 * \see mdbx_dbi_flags_ex() */ 4001 enum MDBX_dbi_state_t { 4002 /** DB was written in this txn */ 4003 MDBX_DBI_DIRTY = 0x01, 4004 /** Named-DB record is older than txnID */ 4005 MDBX_DBI_STALE = 0x02, 4006 /** Named-DB handle opened in this txn */ 4007 MDBX_DBI_FRESH = 0x04, 4008 /** Named-DB handle created in this txn */ 4009 MDBX_DBI_CREAT = 0x08, 4010 }; 4011 #ifndef __cplusplus 4012 /** \ingroup c_statinfo */ 4013 typedef enum MDBX_dbi_state_t MDBX_dbi_state_t; 4014 #else 4015 DEFINE_ENUM_FLAG_OPERATORS(MDBX_dbi_state_t) 4016 #endif 4017 4018 /** \brief Retrieve the DB flags and status for a database handle. 4019 * \ingroup c_statinfo 4020 * 4021 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 4022 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4023 * \param [out] flags Address where the flags will be returned. 4024 * \param [out] state Address where the state will be returned. 4025 * 4026 * \returns A non-zero error value on failure and 0 on success. */ 4027 LIBMDBX_API int mdbx_dbi_flags_ex(MDBX_txn *txn, MDBX_dbi dbi, unsigned *flags, 4028 unsigned *state); 4029 /** \brief The shortcut to calling \ref mdbx_dbi_flags_ex() with `state=NULL` 4030 * for discarding it result. 4031 * \ingroup c_statinfo */ 4032 LIBMDBX_INLINE_API(int, mdbx_dbi_flags, 4033 (MDBX_txn * txn, MDBX_dbi dbi, unsigned *flags)) { 4034 unsigned state; 4035 return mdbx_dbi_flags_ex(txn, dbi, flags, &state); 4036 } 4037 4038 /** \brief Close a database handle. Normally unnecessary. 4039 * \ingroup c_dbi 4040 * 4041 * Closing a database handle is not necessary, but lets \ref mdbx_dbi_open() 4042 * reuse the handle value. Usually it's better to set a bigger 4043 * \ref mdbx_env_set_maxdbs(), unless that value would be large. 4044 * 4045 * \note Use with care. 4046 * This call is synchronized via mutex with \ref mdbx_dbi_close(), but NOT with 4047 * other transactions running by other threads. The "next" version of libmdbx 4048 * (\ref MithrilDB) will solve this issue. 4049 * 4050 * Handles should only be closed if no other threads are going to reference 4051 * the database handle or one of its cursors any further. Do not close a handle 4052 * if an existing transaction has modified its database. Doing so can cause 4053 * misbehavior from database corruption to errors like \ref MDBX_BAD_DBI 4054 * (since the DB name is gone). 4055 * 4056 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 4057 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4058 * 4059 * \returns A non-zero error value on failure and 0 on success. */ 4060 LIBMDBX_API int mdbx_dbi_close(MDBX_env *env, MDBX_dbi dbi); 4061 4062 /** \brief Empty or delete and close a database. 4063 * \ingroup c_crud 4064 * 4065 * \see mdbx_dbi_close() \see mdbx_dbi_open() 4066 * 4067 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 4068 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4069 * \param [in] del `false` to empty the DB, `true` to delete it 4070 * from the environment and close the DB handle. 4071 * 4072 * \returns A non-zero error value on failure and 0 on success. */ 4073 LIBMDBX_API int mdbx_drop(MDBX_txn *txn, MDBX_dbi dbi, bool del); 4074 4075 /** \brief Get items from a database. 4076 * \ingroup c_crud 4077 * 4078 * This function retrieves key/data pairs from the database. The address 4079 * and length of the data associated with the specified key are returned 4080 * in the structure to which data refers. 4081 * If the database supports duplicate keys (\ref MDBX_DUPSORT) then the 4082 * first data item for the key will be returned. Retrieval of other 4083 * items requires the use of \ref mdbx_cursor_get(). 4084 * 4085 * \note The memory pointed to by the returned values is owned by the 4086 * database. The caller need not dispose of the memory, and may not 4087 * modify it in any way. For values returned in a read-only transaction 4088 * any modification attempts will cause a `SIGSEGV`. 4089 * 4090 * \note Values returned from the database are valid only until a 4091 * subsequent update operation, or the end of the transaction. 4092 * 4093 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 4094 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4095 * \param [in] key The key to search for in the database. 4096 * \param [in,out] data The data corresponding to the key. 4097 * 4098 * \returns A non-zero error value on failure and 0 on success, 4099 * some possible errors are: 4100 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4101 * by current thread. 4102 * \retval MDBX_NOTFOUND The key was not in the database. 4103 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4104 LIBMDBX_API int mdbx_get(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, 4105 MDBX_val *data); 4106 4107 /** \brief Get items from a database 4108 * and optionally number of data items for a given key. 4109 * 4110 * \ingroup c_crud 4111 * 4112 * Briefly this function does the same as \ref mdbx_get() with a few 4113 * differences: 4114 * 1. If values_count is NOT NULL, then returns the count 4115 * of multi-values/duplicates for a given key. 4116 * 2. Updates BOTH the key and the data for pointing to the actual key-value 4117 * pair inside the database. 4118 * 4119 * \param [in] txn A transaction handle returned 4120 * by \ref mdbx_txn_begin(). 4121 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4122 * \param [in,out] key The key to search for in the database. 4123 * \param [in,out] data The data corresponding to the key. 4124 * \param [out] values_count The optional address to return number of values 4125 * associated with given key: 4126 * = 0 - in case \ref MDBX_NOTFOUND error; 4127 * = 1 - exactly for databases 4128 * WITHOUT \ref MDBX_DUPSORT; 4129 * >= 1 for databases WITH \ref MDBX_DUPSORT. 4130 * 4131 * \returns A non-zero error value on failure and 0 on success, 4132 * some possible errors are: 4133 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4134 * by current thread. 4135 * \retval MDBX_NOTFOUND The key was not in the database. 4136 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4137 LIBMDBX_API int mdbx_get_ex(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, 4138 MDBX_val *data, size_t *values_count); 4139 4140 /** \brief Get equal or great item from a database. 4141 * \ingroup c_crud 4142 * 4143 * Briefly this function does the same as \ref mdbx_get() with a few 4144 * differences: 4145 * 1. Return equal or great (due comparison function) key-value 4146 * pair, but not only exactly matching with the key. 4147 * 2. On success return \ref MDBX_SUCCESS if key found exactly, 4148 * and \ref MDBX_RESULT_TRUE otherwise. Moreover, for databases with 4149 * \ref MDBX_DUPSORT flag the data argument also will be used to match over 4150 * multi-value/duplicates, and \ref MDBX_SUCCESS will be returned only when 4151 * BOTH the key and the data match exactly. 4152 * 3. Updates BOTH the key and the data for pointing to the actual key-value 4153 * pair inside the database. 4154 * 4155 * \param [in] txn A transaction handle returned 4156 * by \ref mdbx_txn_begin(). 4157 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4158 * \param [in,out] key The key to search for in the database. 4159 * \param [in,out] data The data corresponding to the key. 4160 * 4161 * \returns A non-zero error value on failure and \ref MDBX_RESULT_FALSE 4162 * or \ref MDBX_RESULT_TRUE on success (as described above). 4163 * Some possible errors are: 4164 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4165 * by current thread. 4166 * \retval MDBX_NOTFOUND The key was not in the database. 4167 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4168 LIBMDBX_API int mdbx_get_equal_or_great(MDBX_txn *txn, MDBX_dbi dbi, 4169 MDBX_val *key, MDBX_val *data); 4170 4171 /** \brief Store items into a database. 4172 * \ingroup c_crud 4173 * 4174 * This function stores key/data pairs in the database. The default behavior 4175 * is to enter the new key/data pair, replacing any previously existing key 4176 * if duplicates are disallowed, or adding a duplicate data item if 4177 * duplicates are allowed (see \ref MDBX_DUPSORT). 4178 * 4179 * \param [in] txn A transaction handle returned 4180 * by \ref mdbx_txn_begin(). 4181 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4182 * \param [in] key The key to store in the database. 4183 * \param [in,out] data The data to store. 4184 * \param [in] flags Special options for this operation. 4185 * This parameter must be set to 0 or by bitwise OR'ing 4186 * together one or more of the values described here: 4187 * - \ref MDBX_NODUPDATA 4188 * Enter the new key-value pair only if it does not already appear 4189 * in the database. This flag may only be specified if the database 4190 * was opened with \ref MDBX_DUPSORT. The function will return 4191 * \ref MDBX_KEYEXIST if the key/data pair already appears in the database. 4192 * 4193 * - \ref MDBX_NOOVERWRITE 4194 * Enter the new key/data pair only if the key does not already appear 4195 * in the database. The function will return \ref MDBX_KEYEXIST if the key 4196 * already appears in the database, even if the database supports 4197 * duplicates (see \ref MDBX_DUPSORT). The data parameter will be set 4198 * to point to the existing item. 4199 * 4200 * - \ref MDBX_CURRENT 4201 * Update an single existing entry, but not add new ones. The function will 4202 * return \ref MDBX_NOTFOUND if the given key not exist in the database. 4203 * In case multi-values for the given key, with combination of 4204 * the \ref MDBX_ALLDUPS will replace all multi-values, 4205 * otherwise return the \ref MDBX_EMULTIVAL. 4206 * 4207 * - \ref MDBX_RESERVE 4208 * Reserve space for data of the given size, but don't copy the given 4209 * data. Instead, return a pointer to the reserved space, which the 4210 * caller can fill in later - before the next update operation or the 4211 * transaction ends. This saves an extra memcpy if the data is being 4212 * generated later. MDBX does nothing else with this memory, the caller 4213 * is expected to modify all of the space requested. This flag must not 4214 * be specified if the database was opened with \ref MDBX_DUPSORT. 4215 * 4216 * - \ref MDBX_APPEND 4217 * Append the given key/data pair to the end of the database. This option 4218 * allows fast bulk loading when keys are already known to be in the 4219 * correct order. Loading unsorted keys with this flag will cause 4220 * a \ref MDBX_EKEYMISMATCH error. 4221 * 4222 * - \ref MDBX_APPENDDUP 4223 * As above, but for sorted dup data. 4224 * 4225 * - \ref MDBX_MULTIPLE 4226 * Store multiple contiguous data elements in a single request. This flag 4227 * may only be specified if the database was opened with 4228 * \ref MDBX_DUPFIXED. With combination the \ref MDBX_ALLDUPS 4229 * will replace all multi-values. 4230 * The data argument must be an array of two \ref MDBX_val. The `iov_len` 4231 * of the first \ref MDBX_val must be the size of a single data element. 4232 * The `iov_base` of the first \ref MDBX_val must point to the beginning 4233 * of the array of contiguous data elements which must be properly aligned 4234 * in case of database with \ref MDBX_INTEGERDUP flag. 4235 * The `iov_len` of the second \ref MDBX_val must be the count of the 4236 * number of data elements to store. On return this field will be set to 4237 * the count of the number of elements actually written. The `iov_base` of 4238 * the second \ref MDBX_val is unused. 4239 * 4240 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations" 4241 * 4242 * \returns A non-zero error value on failure and 0 on success, 4243 * some possible errors are: 4244 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4245 * by current thread. 4246 * \retval MDBX_KEYEXIST The key/value pair already exists in the database. 4247 * \retval MDBX_MAP_FULL The database is full, see \ref mdbx_env_set_mapsize(). 4248 * \retval MDBX_TXN_FULL The transaction has too many dirty pages. 4249 * \retval MDBX_EACCES An attempt was made to write 4250 * in a read-only transaction. 4251 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4252 LIBMDBX_API int mdbx_put(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, 4253 MDBX_val *data, MDBX_put_flags_t flags); 4254 4255 /** \brief Replace items in a database. 4256 * \ingroup c_crud 4257 * 4258 * This function allows to update or delete an existing value at the same time 4259 * as the previous value is retrieved. If the argument new_data equal is NULL 4260 * zero, the removal is performed, otherwise the update/insert. 4261 * 4262 * The current value may be in an already changed (aka dirty) page. In this 4263 * case, the page will be overwritten during the update, and the old value will 4264 * be lost. Therefore, an additional buffer must be passed via old_data 4265 * argument initially to copy the old value. If the buffer passed in is too 4266 * small, the function will return \ref MDBX_RESULT_TRUE by setting iov_len 4267 * field pointed by old_data argument to the appropriate value, without 4268 * performing any changes. 4269 * 4270 * For databases with non-unique keys (i.e. with \ref MDBX_DUPSORT flag), 4271 * another use case is also possible, when by old_data argument selects a 4272 * specific item from multi-value/duplicates with the same key for deletion or 4273 * update. To select this scenario in flags should simultaneously specify 4274 * \ref MDBX_CURRENT and \ref MDBX_NOOVERWRITE. This combination is chosen 4275 * because it makes no sense, and thus allows you to identify the request of 4276 * such a scenario. 4277 * 4278 * \param [in] txn A transaction handle returned 4279 * by \ref mdbx_txn_begin(). 4280 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4281 * \param [in] key The key to store in the database. 4282 * \param [in] new_data The data to store, if NULL then deletion will 4283 * be performed. 4284 * \param [in,out] old_data The buffer for retrieve previous value as describe 4285 * above. 4286 * \param [in] flags Special options for this operation. 4287 * This parameter must be set to 0 or by bitwise 4288 * OR'ing together one or more of the values 4289 * described in \ref mdbx_put() description above, 4290 * and additionally 4291 * (\ref MDBX_CURRENT | \ref MDBX_NOOVERWRITE) 4292 * combination for selection particular item from 4293 * multi-value/duplicates. 4294 * 4295 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations" 4296 * 4297 * \returns A non-zero error value on failure and 0 on success. */ 4298 LIBMDBX_API int mdbx_replace(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, 4299 MDBX_val *new_data, MDBX_val *old_data, 4300 MDBX_put_flags_t flags); 4301 4302 typedef int (*MDBX_preserve_func)(void *context, MDBX_val *target, 4303 const void *src, size_t bytes); 4304 LIBMDBX_API int mdbx_replace_ex(MDBX_txn *txn, MDBX_dbi dbi, 4305 const MDBX_val *key, MDBX_val *new_data, 4306 MDBX_val *old_data, MDBX_put_flags_t flags, 4307 MDBX_preserve_func preserver, 4308 void *preserver_context); 4309 4310 /** \brief Delete items from a database. 4311 * \ingroup c_crud 4312 * 4313 * This function removes key/data pairs from the database. 4314 * 4315 * \note The data parameter is NOT ignored regardless the database does 4316 * support sorted duplicate data items or not. If the data parameter 4317 * is non-NULL only the matching data item will be deleted. Otherwise, if data 4318 * parameter is NULL, any/all value(s) for specified key will be deleted. 4319 * 4320 * This function will return \ref MDBX_NOTFOUND if the specified key/data 4321 * pair is not in the database. 4322 * 4323 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations" 4324 * 4325 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 4326 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4327 * \param [in] key The key to delete from the database. 4328 * \param [in] data The data to delete. 4329 * 4330 * \returns A non-zero error value on failure and 0 on success, 4331 * some possible errors are: 4332 * \retval MDBX_EACCES An attempt was made to write 4333 * in a read-only transaction. 4334 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4335 LIBMDBX_API int mdbx_del(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, 4336 const MDBX_val *data); 4337 4338 /** \brief Create a cursor handle but not bind it to transaction nor DBI handle. 4339 * \ingroup c_cursors 4340 * 4341 * A cursor cannot be used when its database handle is closed. Nor when its 4342 * transaction has ended, except with \ref mdbx_cursor_bind() and \ref 4343 * mdbx_cursor_renew(). Also it can be discarded with \ref mdbx_cursor_close(). 4344 * 4345 * A cursor must be closed explicitly always, before or after its transaction 4346 * ends. It can be reused with \ref mdbx_cursor_bind() 4347 * or \ref mdbx_cursor_renew() before finally closing it. 4348 * 4349 * \note In contrast to LMDB, the MDBX required that any opened cursors can be 4350 * reused and must be freed explicitly, regardless ones was opened in a 4351 * read-only or write transaction. The REASON for this is eliminates ambiguity 4352 * which helps to avoid errors such as: use-after-free, double-free, i.e. 4353 * memory corruption and segfaults. 4354 * 4355 * \param [in] context A pointer to application context to be associated with 4356 * created cursor and could be retrieved by 4357 * \ref mdbx_cursor_get_userctx() until cursor closed. 4358 * 4359 * \returns Created cursor handle or NULL in case out of memory. */ 4360 LIBMDBX_API MDBX_cursor *mdbx_cursor_create(void *context); 4361 4362 /** \brief Set application information associated with the \ref MDBX_cursor. 4363 * \ingroup c_cursors 4364 * \see mdbx_cursor_get_userctx() 4365 * 4366 * \param [in] cursor An cursor handle returned by \ref mdbx_cursor_create() 4367 * or \ref mdbx_cursor_open(). 4368 * \param [in] ctx An arbitrary pointer for whatever the application needs. 4369 * 4370 * \returns A non-zero error value on failure and 0 on success. */ 4371 LIBMDBX_API int mdbx_cursor_set_userctx(MDBX_cursor *cursor, void *ctx); 4372 4373 /** \brief Get the application information associated with the MDBX_cursor. 4374 * \ingroup c_cursors 4375 * \see mdbx_cursor_set_userctx() 4376 * 4377 * \param [in] cursor An cursor handle returned by \ref mdbx_cursor_create() 4378 * or \ref mdbx_cursor_open(). 4379 * \returns The pointer which was passed via the `context` parameter 4380 * of `mdbx_cursor_create()` or set by \ref mdbx_cursor_set_userctx(), 4381 * or `NULL` if something wrong. */ 4382 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API void * 4383 mdbx_cursor_get_userctx(const MDBX_cursor *cursor); 4384 4385 /** \brief Bind cursor to specified transaction and DBI handle. 4386 * \ingroup c_cursors 4387 * 4388 * Using of the `mdbx_cursor_bind()` is equivalent to calling 4389 * \ref mdbx_cursor_renew() but with specifying an arbitrary dbi handle. 4390 * 4391 * A cursor may be associated with a new transaction, and referencing a new or 4392 * the same database handle as it was created with. This may be done whether the 4393 * previous transaction is live or dead. 4394 * 4395 * \note In contrast to LMDB, the MDBX required that any opened cursors can be 4396 * reused and must be freed explicitly, regardless ones was opened in a 4397 * read-only or write transaction. The REASON for this is eliminates ambiguity 4398 * which helps to avoid errors such as: use-after-free, double-free, i.e. 4399 * memory corruption and segfaults. 4400 * 4401 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 4402 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4403 * \param [out] cursor A cursor handle returned by \ref mdbx_cursor_create(). 4404 * 4405 * \returns A non-zero error value on failure and 0 on success, 4406 * some possible errors are: 4407 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4408 * by current thread. 4409 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4410 LIBMDBX_API int mdbx_cursor_bind(MDBX_txn *txn, MDBX_cursor *cursor, 4411 MDBX_dbi dbi); 4412 4413 /** \brief Create a cursor handle for the specified transaction and DBI handle. 4414 * \ingroup c_cursors 4415 * 4416 * Using of the `mdbx_cursor_open()` is equivalent to calling 4417 * \ref mdbx_cursor_create() and then \ref mdbx_cursor_bind() functions. 4418 * 4419 * A cursor cannot be used when its database handle is closed. Nor when its 4420 * transaction has ended, except with \ref mdbx_cursor_bind() and \ref 4421 * mdbx_cursor_renew(). Also it can be discarded with \ref mdbx_cursor_close(). 4422 * 4423 * A cursor must be closed explicitly always, before or after its transaction 4424 * ends. It can be reused with \ref mdbx_cursor_bind() 4425 * or \ref mdbx_cursor_renew() before finally closing it. 4426 * 4427 * \note In contrast to LMDB, the MDBX required that any opened cursors can be 4428 * reused and must be freed explicitly, regardless ones was opened in a 4429 * read-only or write transaction. The REASON for this is eliminates ambiguity 4430 * which helps to avoid errors such as: use-after-free, double-free, i.e. 4431 * memory corruption and segfaults. 4432 * 4433 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 4434 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4435 * \param [out] cursor Address where the new \ref MDBX_cursor handle will be 4436 * stored. 4437 * 4438 * \returns A non-zero error value on failure and 0 on success, 4439 * some possible errors are: 4440 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4441 * by current thread. 4442 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4443 LIBMDBX_API int mdbx_cursor_open(MDBX_txn *txn, MDBX_dbi dbi, 4444 MDBX_cursor **cursor); 4445 4446 /** \brief Close a cursor handle. 4447 * \ingroup c_cursors 4448 * 4449 * The cursor handle will be freed and must not be used again after this call, 4450 * but its transaction may still be live. 4451 * 4452 * \note In contrast to LMDB, the MDBX required that any opened cursors can be 4453 * reused and must be freed explicitly, regardless ones was opened in a 4454 * read-only or write transaction. The REASON for this is eliminates ambiguity 4455 * which helps to avoid errors such as: use-after-free, double-free, i.e. 4456 * memory corruption and segfaults. 4457 * 4458 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open() 4459 * or \ref mdbx_cursor_create(). */ 4460 LIBMDBX_API void mdbx_cursor_close(MDBX_cursor *cursor); 4461 4462 /** \brief Renew a cursor handle. 4463 * \ingroup c_cursors 4464 * 4465 * The cursor may be associated with a new transaction, and referencing a new or 4466 * the same database handle as it was created with. This may be done whether the 4467 * previous transaction is live or dead. 4468 * 4469 * Using of the `mdbx_cursor_renew()` is equivalent to calling 4470 * \ref mdbx_cursor_bind() with the DBI handle that previously 4471 * the cursor was used with. 4472 * 4473 * \note In contrast to LMDB, the MDBX allow any cursor to be re-used by using 4474 * \ref mdbx_cursor_renew(), to avoid unnecessary malloc/free overhead until it 4475 * freed by \ref mdbx_cursor_close(). 4476 * 4477 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 4478 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). 4479 * 4480 * \returns A non-zero error value on failure and 0 on success, 4481 * some possible errors are: 4482 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4483 * by current thread. 4484 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4485 LIBMDBX_API int mdbx_cursor_renew(MDBX_txn *txn, MDBX_cursor *cursor); 4486 4487 /** \brief Return the cursor's transaction handle. 4488 * \ingroup c_cursors 4489 * 4490 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). */ 4491 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API MDBX_txn * 4492 mdbx_cursor_txn(const MDBX_cursor *cursor); 4493 4494 /** \brief Return the cursor's database handle. 4495 * \ingroup c_cursors 4496 * 4497 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). */ 4498 LIBMDBX_API MDBX_dbi mdbx_cursor_dbi(const MDBX_cursor *cursor); 4499 4500 /** \brief Copy cursor position and state. 4501 * \ingroup c_cursors 4502 * 4503 * \param [in] src A source cursor handle returned 4504 * by \ref mdbx_cursor_create() or \ref mdbx_cursor_open(). 4505 * 4506 * \param [in,out] dest A destination cursor handle returned 4507 * by \ref mdbx_cursor_create() or \ref mdbx_cursor_open(). 4508 * 4509 * \returns A non-zero error value on failure and 0 on success. */ 4510 LIBMDBX_API int mdbx_cursor_copy(const MDBX_cursor *src, MDBX_cursor *dest); 4511 4512 /** \brief Retrieve by cursor. 4513 * \ingroup c_crud 4514 * 4515 * This function retrieves key/data pairs from the database. The address and 4516 * length of the key are returned in the object to which key refers (except 4517 * for the case of the \ref MDBX_SET option, in which the key object is 4518 * unchanged), and the address and length of the data are returned in the object 4519 * to which data refers. 4520 * \see mdbx_get() 4521 * 4522 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). 4523 * \param [in,out] key The key for a retrieved item. 4524 * \param [in,out] data The data of a retrieved item. 4525 * \param [in] op A cursor operation \ref MDBX_cursor_op. 4526 * 4527 * \returns A non-zero error value on failure and 0 on success, 4528 * some possible errors are: 4529 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4530 * by current thread. 4531 * \retval MDBX_NOTFOUND No matching key found. 4532 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4533 LIBMDBX_API int mdbx_cursor_get(MDBX_cursor *cursor, MDBX_val *key, 4534 MDBX_val *data, MDBX_cursor_op op); 4535 4536 /** \brief Retrieve multiple non-dupsort key/value pairs by cursor. 4537 * \ingroup c_crud 4538 * 4539 * This function retrieves multiple key/data pairs from the database without 4540 * \ref MDBX_DUPSORT option. For `MDBX_DUPSORT` databases please 4541 * use \ref MDBX_GET_MULTIPLE and \ref MDBX_NEXT_MULTIPLE. 4542 * 4543 * The number of key and value items is returned in the `size_t count` 4544 * refers. The addresses and lengths of the keys and values are returned in the 4545 * array to which `pairs` refers. 4546 * \see mdbx_cursor_get() 4547 * 4548 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). 4549 * \param [out] count The number of key and value item returned, on success 4550 * it always be the even because the key-value 4551 * pairs are returned. 4552 * \param [in,out] pairs A pointer to the array of key value pairs. 4553 * \param [in] limit The size of pairs buffer as the number of items, 4554 * but not a pairs. 4555 * \param [in] op A cursor operation \ref MDBX_cursor_op (only 4556 * \ref MDBX_FIRST, \ref MDBX_NEXT, \ref MDBX_GET_CURRENT 4557 * are supported). 4558 * 4559 * \returns A non-zero error value on failure and 0 on success, 4560 * some possible errors are: 4561 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4562 * by current thread. 4563 * \retval MDBX_NOTFOUND No more key-value pairs are available. 4564 * \retval MDBX_ENODATA The cursor is already at the end of data. 4565 * \retval MDBX_RESULT_TRUE The specified limit is less than the available 4566 * key-value pairs on the current page/position 4567 * that the cursor points to. 4568 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4569 LIBMDBX_API int mdbx_cursor_get_batch(MDBX_cursor *cursor, size_t *count, 4570 MDBX_val *pairs, size_t limit, 4571 MDBX_cursor_op op); 4572 4573 /** \brief Store by cursor. 4574 * \ingroup c_crud 4575 * 4576 * This function stores key/data pairs into the database. The cursor is 4577 * positioned at the new item, or on failure usually near it. 4578 * 4579 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). 4580 * \param [in] key The key operated on. 4581 * \param [in,out] data The data operated on. 4582 * \param [in] flags Options for this operation. This parameter 4583 * must be set to 0 or by bitwise OR'ing together 4584 * one or more of the values described here: 4585 * - \ref MDBX_CURRENT 4586 * Replace the item at the current cursor position. The key parameter 4587 * must still be provided, and must match it, otherwise the function 4588 * return \ref MDBX_EKEYMISMATCH. With combination the 4589 * \ref MDBX_ALLDUPS will replace all multi-values. 4590 * 4591 * \note MDBX allows (unlike LMDB) you to change the size of the data and 4592 * automatically handles reordering for sorted duplicates 4593 * (see \ref MDBX_DUPSORT). 4594 * 4595 * - \ref MDBX_NODUPDATA 4596 * Enter the new key-value pair only if it does not already appear in the 4597 * database. This flag may only be specified if the database was opened 4598 * with \ref MDBX_DUPSORT. The function will return \ref MDBX_KEYEXIST 4599 * if the key/data pair already appears in the database. 4600 * 4601 * - \ref MDBX_NOOVERWRITE 4602 * Enter the new key/data pair only if the key does not already appear 4603 * in the database. The function will return \ref MDBX_KEYEXIST if the key 4604 * already appears in the database, even if the database supports 4605 * duplicates (\ref MDBX_DUPSORT). 4606 * 4607 * - \ref MDBX_RESERVE 4608 * Reserve space for data of the given size, but don't copy the given 4609 * data. Instead, return a pointer to the reserved space, which the 4610 * caller can fill in later - before the next update operation or the 4611 * transaction ends. This saves an extra memcpy if the data is being 4612 * generated later. This flag must not be specified if the database 4613 * was opened with \ref MDBX_DUPSORT. 4614 * 4615 * - \ref MDBX_APPEND 4616 * Append the given key/data pair to the end of the database. No key 4617 * comparisons are performed. This option allows fast bulk loading when 4618 * keys are already known to be in the correct order. Loading unsorted 4619 * keys with this flag will cause a \ref MDBX_KEYEXIST error. 4620 * 4621 * - \ref MDBX_APPENDDUP 4622 * As above, but for sorted dup data. 4623 * 4624 * - \ref MDBX_MULTIPLE 4625 * Store multiple contiguous data elements in a single request. This flag 4626 * may only be specified if the database was opened with 4627 * \ref MDBX_DUPFIXED. With combination the \ref MDBX_ALLDUPS 4628 * will replace all multi-values. 4629 * The data argument must be an array of two \ref MDBX_val. The `iov_len` 4630 * of the first \ref MDBX_val must be the size of a single data element. 4631 * The `iov_base` of the first \ref MDBX_val must point to the beginning 4632 * of the array of contiguous data elements which must be properly aligned 4633 * in case of database with \ref MDBX_INTEGERDUP flag. 4634 * The `iov_len` of the second \ref MDBX_val must be the count of the 4635 * number of data elements to store. On return this field will be set to 4636 * the count of the number of elements actually written. The `iov_base` of 4637 * the second \ref MDBX_val is unused. 4638 * 4639 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations" 4640 * 4641 * \returns A non-zero error value on failure and 0 on success, 4642 * some possible errors are: 4643 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4644 * by current thread. 4645 * \retval MDBX_EKEYMISMATCH The given key value is mismatched to the current 4646 * cursor position 4647 * \retval MDBX_MAP_FULL The database is full, 4648 * see \ref mdbx_env_set_mapsize(). 4649 * \retval MDBX_TXN_FULL The transaction has too many dirty pages. 4650 * \retval MDBX_EACCES An attempt was made to write in a read-only 4651 * transaction. 4652 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4653 LIBMDBX_API int mdbx_cursor_put(MDBX_cursor *cursor, const MDBX_val *key, 4654 MDBX_val *data, MDBX_put_flags_t flags); 4655 4656 /** \brief Delete current key/data pair. 4657 * \ingroup c_crud 4658 * 4659 * This function deletes the key/data pair to which the cursor refers. This 4660 * does not invalidate the cursor, so operations such as \ref MDBX_NEXT can 4661 * still be used on it. Both \ref MDBX_NEXT and \ref MDBX_GET_CURRENT will 4662 * return the same record after this operation. 4663 * 4664 * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). 4665 * \param [in] flags Options for this operation. This parameter must be set 4666 * to one of the values described here. 4667 * 4668 * - \ref MDBX_CURRENT Delete only single entry at current cursor position. 4669 * - \ref MDBX_ALLDUPS 4670 * or \ref MDBX_NODUPDATA (supported for compatibility) 4671 * Delete all of the data items for the current key. This flag has effect 4672 * only for database(s) was created with \ref MDBX_DUPSORT. 4673 * 4674 * \see \ref c_crud_hints "Quick reference for Insert/Update/Delete operations" 4675 * 4676 * \returns A non-zero error value on failure and 0 on success, 4677 * some possible errors are: 4678 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4679 * by current thread. 4680 * \retval MDBX_MAP_FULL The database is full, 4681 * see \ref mdbx_env_set_mapsize(). 4682 * \retval MDBX_TXN_FULL The transaction has too many dirty pages. 4683 * \retval MDBX_EACCES An attempt was made to write in a read-only 4684 * transaction. 4685 * \retval MDBX_EINVAL An invalid parameter was specified. */ 4686 LIBMDBX_API int mdbx_cursor_del(MDBX_cursor *cursor, MDBX_put_flags_t flags); 4687 4688 /** \brief Return count of duplicates for current key. 4689 * \ingroup c_crud 4690 * 4691 * This call is valid for all databases, but reasonable only for that support 4692 * sorted duplicate data items \ref MDBX_DUPSORT. 4693 * 4694 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). 4695 * \param [out] pcount Address where the count will be stored. 4696 * 4697 * \returns A non-zero error value on failure and 0 on success, 4698 * some possible errors are: 4699 * \retval MDBX_THREAD_MISMATCH Given transaction is not owned 4700 * by current thread. 4701 * \retval MDBX_EINVAL Cursor is not initialized, or an invalid parameter 4702 * was specified. */ 4703 LIBMDBX_API int mdbx_cursor_count(const MDBX_cursor *cursor, size_t *pcount); 4704 4705 /** \brief Determines whether the cursor is pointed to a key-value pair or not, 4706 * i.e. was not positioned or points to the end of data. 4707 * \ingroup c_cursors 4708 * 4709 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). 4710 * 4711 * \returns A \ref MDBX_RESULT_TRUE or \ref MDBX_RESULT_FALSE value, 4712 * otherwise the error code: 4713 * \retval MDBX_RESULT_TRUE No more data available or cursor not 4714 * positioned 4715 * \retval MDBX_RESULT_FALSE A data is available 4716 * \retval Otherwise the error code */ 4717 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int 4718 mdbx_cursor_eof(const MDBX_cursor *cursor); 4719 4720 /** \brief Determines whether the cursor is pointed to the first key-value pair 4721 * or not. 4722 * \ingroup c_cursors 4723 * 4724 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). 4725 * 4726 * \returns A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, 4727 * otherwise the error code: 4728 * \retval MDBX_RESULT_TRUE Cursor positioned to the first key-value pair 4729 * \retval MDBX_RESULT_FALSE Cursor NOT positioned to the first key-value 4730 * pair \retval Otherwise the error code */ 4731 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int 4732 mdbx_cursor_on_first(const MDBX_cursor *cursor); 4733 4734 /** \brief Determines whether the cursor is pointed to the last key-value pair 4735 * or not. 4736 * \ingroup c_cursors 4737 * 4738 * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). 4739 * 4740 * \returns A \ref MDBX_RESULT_TRUE or \ref MDBX_RESULT_FALSE value, 4741 * otherwise the error code: 4742 * \retval MDBX_RESULT_TRUE Cursor positioned to the last key-value pair 4743 * \retval MDBX_RESULT_FALSE Cursor NOT positioned to the last key-value pair 4744 * \retval Otherwise the error code */ 4745 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int 4746 mdbx_cursor_on_last(const MDBX_cursor *cursor); 4747 4748 /** \addtogroup c_rqest 4749 * \details \note The estimation result varies greatly depending on the filling 4750 * of specific pages and the overall balance of the b-tree: 4751 * 4752 * 1. The number of items is estimated by analyzing the height and fullness of 4753 * the b-tree. The accuracy of the result directly depends on the balance of 4754 * the b-tree, which in turn is determined by the history of previous 4755 * insert/delete operations and the nature of the data (i.e. variability of 4756 * keys length and so on). Therefore, the accuracy of the estimation can vary 4757 * greatly in a particular situation. 4758 * 4759 * 2. To understand the potential spread of results, you should consider a 4760 * possible situations basing on the general criteria for splitting and merging 4761 * b-tree pages: 4762 * - the page is split into two when there is no space for added data; 4763 * - two pages merge if the result fits in half a page; 4764 * - thus, the b-tree can consist of an arbitrary combination of pages filled 4765 * both completely and only 1/4. Therefore, in the worst case, the result 4766 * can diverge 4 times for each level of the b-tree excepting the first and 4767 * the last. 4768 * 4769 * 3. In practice, the probability of extreme cases of the above situation is 4770 * close to zero and in most cases the error does not exceed a few percent. On 4771 * the other hand, it's just a chance you shouldn't overestimate. */ 4772 4773 /** \brief Estimates the distance between cursors as a number of elements. 4774 * \ingroup c_rqest 4775 * 4776 * This function performs a rough estimate based only on b-tree pages that are 4777 * common for the both cursor's stacks. The results of such estimation can be 4778 * used to build and/or optimize query execution plans. 4779 * 4780 * Please see notes on accuracy of the result in the details 4781 * of \ref c_rqest section. 4782 * 4783 * Both cursors must be initialized for the same database and the same 4784 * transaction. 4785 * 4786 * \param [in] first The first cursor for estimation. 4787 * \param [in] last The second cursor for estimation. 4788 * \param [out] distance_items The pointer to store estimated distance value, 4789 * i.e. `*distance_items = distance(first, last)`. 4790 * 4791 * \returns A non-zero error value on failure and 0 on success. */ 4792 LIBMDBX_API int mdbx_estimate_distance(const MDBX_cursor *first, 4793 const MDBX_cursor *last, 4794 ptrdiff_t *distance_items); 4795 4796 /** \brief Estimates the move distance. 4797 * \ingroup c_rqest 4798 * 4799 * This function performs a rough estimate distance between the current 4800 * cursor position and next position after the specified move-operation with 4801 * given key and data. The results of such estimation can be used to build 4802 * and/or optimize query execution plans. Current cursor position and state are 4803 * preserved. 4804 * 4805 * Please see notes on accuracy of the result in the details 4806 * of \ref c_rqest section. 4807 * 4808 * \param [in] cursor Cursor for estimation. 4809 * \param [in,out] key The key for a retrieved item. 4810 * \param [in,out] data The data of a retrieved item. 4811 * \param [in] move_op A cursor operation \ref MDBX_cursor_op. 4812 * \param [out] distance_items A pointer to store estimated move distance 4813 * as the number of elements. 4814 * 4815 * \returns A non-zero error value on failure and 0 on success. */ 4816 LIBMDBX_API int mdbx_estimate_move(const MDBX_cursor *cursor, MDBX_val *key, 4817 MDBX_val *data, MDBX_cursor_op move_op, 4818 ptrdiff_t *distance_items); 4819 4820 /** \brief Estimates the size of a range as a number of elements. 4821 * \ingroup c_rqest 4822 * 4823 * The results of such estimation can be used to build and/or optimize query 4824 * execution plans. 4825 * 4826 * Please see notes on accuracy of the result in the details 4827 * of \ref c_rqest section. 4828 * 4829 * 4830 * \param [in] txn A transaction handle returned 4831 * by \ref mdbx_txn_begin(). 4832 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4833 * \param [in] begin_key The key of range beginning or NULL for explicit FIRST. 4834 * \param [in] begin_data Optional additional data to seeking among sorted 4835 * duplicates. 4836 * Only for \ref MDBX_DUPSORT, NULL otherwise. 4837 * \param [in] end_key The key of range ending or NULL for explicit LAST. 4838 * \param [in] end_data Optional additional data to seeking among sorted 4839 * duplicates. 4840 * Only for \ref MDBX_DUPSORT, NULL otherwise. 4841 * \param [out] distance_items A pointer to store range estimation result. 4842 * 4843 * \returns A non-zero error value on failure and 0 on success. */ 4844 LIBMDBX_API int mdbx_estimate_range(MDBX_txn *txn, MDBX_dbi dbi, 4845 MDBX_val *begin_key, MDBX_val *begin_data, 4846 MDBX_val *end_key, MDBX_val *end_data, 4847 ptrdiff_t *distance_items); 4848 4849 /** \brief The EPSILON value for mdbx_estimate_range() 4850 * \ingroup c_rqest */ 4851 #define MDBX_EPSILON ((MDBX_val *)((ptrdiff_t)-1)) 4852 4853 /** \brief Determines whether the given address is on a dirty database page of 4854 * the transaction or not. 4855 * \ingroup c_statinfo 4856 * 4857 * Ultimately, this allows to avoid copy data from non-dirty pages. 4858 * 4859 * "Dirty" pages are those that have already been changed during a write 4860 * transaction. Accordingly, any further changes may result in such pages being 4861 * overwritten. Therefore, all functions libmdbx performing changes inside the 4862 * database as arguments should NOT get pointers to data in those pages. In 4863 * turn, "not dirty" pages before modification will be copied. 4864 * 4865 * In other words, data from dirty pages must either be copied before being 4866 * passed as arguments for further processing or rejected at the argument 4867 * validation stage. Thus, `mdbx_is_dirty()` allows you to get rid of 4868 * unnecessary copying, and perform a more complete check of the arguments. 4869 * 4870 * \note The address passed must point to the beginning of the data. This is 4871 * the only way to ensure that the actual page header is physically located in 4872 * the same memory page, including for multi-pages with long data. 4873 * 4874 * \note In rare cases the function may return a false positive answer 4875 * (\ref MDBX_RESULT_TRUE when data is NOT on a dirty page), but never a false 4876 * negative if the arguments are correct. 4877 * 4878 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 4879 * \param [in] ptr The address of data to check. 4880 * 4881 * \returns A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, 4882 * otherwise the error code: 4883 * \retval MDBX_RESULT_TRUE Given address is on the dirty page. 4884 * \retval MDBX_RESULT_FALSE Given address is NOT on the dirty page. 4885 * \retval Otherwise the error code. */ 4886 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int mdbx_is_dirty(const MDBX_txn *txn, 4887 const void *ptr); 4888 4889 /** \brief Sequence generation for a database. 4890 * \ingroup c_crud 4891 * 4892 * The function allows to create a linear sequence of unique positive integers 4893 * for each database. The function can be called for a read transaction to 4894 * retrieve the current sequence value, and the increment must be zero. 4895 * Sequence changes become visible outside the current write transaction after 4896 * it is committed, and discarded on abort. 4897 * 4898 * \param [in] txn A transaction handle returned 4899 * by \ref mdbx_txn_begin(). 4900 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4901 * \param [out] result The optional address where the value of sequence 4902 * before the change will be stored. 4903 * \param [in] increment Value to increase the sequence, 4904 * must be 0 for read-only transactions. 4905 * 4906 * \returns A non-zero error value on failure and 0 on success, 4907 * some possible errors are: 4908 * \retval MDBX_RESULT_TRUE Increasing the sequence has resulted in an 4909 * overflow and therefore cannot be executed. */ 4910 LIBMDBX_API int mdbx_dbi_sequence(MDBX_txn *txn, MDBX_dbi dbi, uint64_t *result, 4911 uint64_t increment); 4912 4913 /** \brief Compare two keys according to a particular database. 4914 * \ingroup c_crud 4915 * \see MDBX_cmp_func 4916 * 4917 * This returns a comparison as if the two data items were keys in the 4918 * specified database. 4919 * 4920 * \warning There ss a Undefined behavior if one of arguments is invalid. 4921 * 4922 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 4923 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4924 * \param [in] a The first item to compare. 4925 * \param [in] b The second item to compare. 4926 * 4927 * \returns < 0 if a < b, 0 if a == b, > 0 if a > b */ 4928 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int mdbx_cmp(const MDBX_txn *txn, 4929 MDBX_dbi dbi, 4930 const MDBX_val *a, 4931 const MDBX_val *b); 4932 4933 /** \brief Returns default internal key's comparator for given database flags. 4934 * \ingroup c_extra */ 4935 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API MDBX_cmp_func * 4936 mdbx_get_keycmp(MDBX_db_flags_t flags); 4937 4938 /** \brief Compare two data items according to a particular database. 4939 * \ingroup c_crud 4940 * \see MDBX_cmp_func 4941 * 4942 * This returns a comparison as if the two items were data items of the 4943 * specified database. 4944 * 4945 * \warning There ss a Undefined behavior if one of arguments is invalid. 4946 * 4947 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 4948 * \param [in] dbi A database handle returned by \ref mdbx_dbi_open(). 4949 * \param [in] a The first item to compare. 4950 * \param [in] b The second item to compare. 4951 * 4952 * \returns < 0 if a < b, 0 if a == b, > 0 if a > b */ 4953 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int mdbx_dcmp(const MDBX_txn *txn, 4954 MDBX_dbi dbi, 4955 const MDBX_val *a, 4956 const MDBX_val *b); 4957 4958 /** \brief Returns default internal data's comparator for given database flags 4959 * \ingroup c_extra */ 4960 MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_API MDBX_cmp_func * 4961 mdbx_get_datacmp(MDBX_db_flags_t flags); 4962 4963 /** \brief A callback function used to enumerate the reader lock table. 4964 * \ingroup c_statinfo 4965 * 4966 * \param [in] ctx An arbitrary context pointer for the callback. 4967 * \param [in] num The serial number during enumeration, 4968 * starting from 1. 4969 * \param [in] slot The reader lock table slot number. 4970 * \param [in] txnid The ID of the transaction being read, 4971 * i.e. the MVCC-snapshot number. 4972 * \param [in] lag The lag from a recent MVCC-snapshot, 4973 * i.e. the number of committed write transactions 4974 * since the current read transaction started. 4975 * \param [in] pid The reader process ID. 4976 * \param [in] thread The reader thread ID. 4977 * \param [in] bytes_used The number of last used page 4978 * in the MVCC-snapshot which being read, 4979 * i.e. database file can't shrinked beyond this. 4980 * \param [in] bytes_retained The total size of the database pages that were 4981 * retired by committed write transactions after 4982 * the reader's MVCC-snapshot, 4983 * i.e. the space which would be freed after 4984 * the Reader releases the MVCC-snapshot 4985 * for reuse by completion read transaction. 4986 * 4987 * \returns < 0 on failure, >= 0 on success. \see mdbx_reader_list() */ 4988 typedef int(MDBX_reader_list_func)(void *ctx, int num, int slot, mdbx_pid_t pid, 4989 mdbx_tid_t thread, uint64_t txnid, 4990 uint64_t lag, size_t bytes_used, 4991 size_t bytes_retained) MDBX_CXX17_NOEXCEPT; 4992 4993 /** \brief Enumerate the entries in the reader lock table. 4994 * 4995 * \ingroup c_statinfo 4996 * 4997 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 4998 * \param [in] func A \ref MDBX_reader_list_func function. 4999 * \param [in] ctx An arbitrary context pointer for the enumeration 5000 * function. 5001 * 5002 * \returns A non-zero error value on failure and 0 on success, 5003 * or \ref MDBX_RESULT_TRUE if the reader lock table is empty. */ 5004 LIBMDBX_API int mdbx_reader_list(const MDBX_env *env, 5005 MDBX_reader_list_func *func, void *ctx); 5006 5007 /** \brief Check for stale entries in the reader lock table. 5008 * \ingroup c_extra 5009 * 5010 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 5011 * \param [out] dead Number of stale slots that were cleared. 5012 * 5013 * \returns A non-zero error value on failure and 0 on success, 5014 * or \ref MDBX_RESULT_TRUE if a dead reader(s) found or mutex was recovered. */ 5015 LIBMDBX_API int mdbx_reader_check(MDBX_env *env, int *dead); 5016 5017 /** \brief Returns a lag of the reading for the given transaction. 5018 * \ingroup c_statinfo 5019 * 5020 * Returns an information for estimate how much given read-only 5021 * transaction is lagging relative the to actual head. 5022 * \deprecated Please use \ref mdbx_txn_info() instead. 5023 * 5024 * \param [in] txn A transaction handle returned by \ref mdbx_txn_begin(). 5025 * \param [out] percent Percentage of page allocation in the database. 5026 * 5027 * \returns Number of transactions committed after the given was started for 5028 * read, or negative value on failure. */ 5029 MDBX_DEPRECATED LIBMDBX_API int mdbx_txn_straggler(const MDBX_txn *txn, 5030 int *percent); 5031 5032 /** \brief Registers the current thread as a reader for the environment. 5033 * \ingroup c_extra 5034 * 5035 * To perform read operations without blocking, a reader slot must be assigned 5036 * for each thread. However, this assignment requires a short-term lock 5037 * acquisition which is performed automatically. This function allows you to 5038 * assign the reader slot in advance and thus avoid capturing the blocker when 5039 * the read transaction starts firstly from current thread. 5040 * \see mdbx_thread_unregister() 5041 * 5042 * \note Threads are registered automatically the first time a read transaction 5043 * starts. Therefore, there is no need to use this function, except in 5044 * special cases. 5045 * 5046 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 5047 * 5048 * \returns A non-zero error value on failure and 0 on success, 5049 * or \ref MDBX_RESULT_TRUE if thread is already registered. */ 5050 LIBMDBX_API int mdbx_thread_register(const MDBX_env *env); 5051 5052 /** \brief Unregisters the current thread as a reader for the environment. 5053 * \ingroup c_extra 5054 * 5055 * To perform read operations without blocking, a reader slot must be assigned 5056 * for each thread. However, the assigned reader slot will remain occupied until 5057 * the thread ends or the environment closes. This function allows you to 5058 * explicitly release the assigned reader slot. 5059 * \see mdbx_thread_register() 5060 * 5061 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 5062 * 5063 * \returns A non-zero error value on failure and 0 on success, or 5064 * \ref MDBX_RESULT_TRUE if thread is not registered or already unregistered. */ 5065 LIBMDBX_API int mdbx_thread_unregister(const MDBX_env *env); 5066 5067 /** \brief A Handle-Slow-Readers callback function to resolve database 5068 * full/overflow issue due to a reader(s) which prevents the old data from being 5069 * recycled. 5070 * \ingroup c_err 5071 * 5072 * Read transactions prevent reuse of pages freed by newer write transactions, 5073 * thus the database can grow quickly. This callback will be called when there 5074 * is not enough space in the database (i.e. before increasing the database size 5075 * or before \ref MDBX_MAP_FULL error) and thus can be used to resolve issues 5076 * with a "long-lived" read transactions. 5077 * \see mdbx_env_set_hsr() 5078 * \see mdbx_env_get_hsr() 5079 * \see <a href="intro.html#long-lived-read">Long-lived read transactions</a> 5080 * 5081 * Using this callback you can choose how to resolve the situation: 5082 * - abort the write transaction with an error; 5083 * - wait for the read transaction(s) to complete; 5084 * - notify a thread performing a long-lived read transaction 5085 * and wait for an effect; 5086 * - kill the thread or whole process that performs the long-lived read 5087 * transaction; 5088 * 5089 * Depending on the arguments and needs, your implementation may wait, 5090 * terminate a process or thread that is performing a long read, or perform 5091 * some other action. In doing so it is important that the returned code always 5092 * corresponds to the performed action. 5093 * 5094 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 5095 * \param [in] txn The current write transaction which internally at 5096 * the \ref MDBX_MAP_FULL condition. 5097 * \param [in] pid A pid of the reader process. 5098 * \param [in] tid A thread_id of the reader thread. 5099 * \param [in] laggard An oldest read transaction number on which stalled. 5100 * \param [in] gap A lag from the last committed txn. 5101 * \param [in] space A space that actually become available for reuse after 5102 * this reader finished. The callback function can take 5103 * this value into account to evaluate the impact that 5104 * a long-running transaction has. 5105 * \param [in] retry A retry number starting from 0. 5106 * If callback has returned 0 at least once, then at end of 5107 * current handling loop the callback function will be 5108 * called additionally with negative `retry` value to notify 5109 * about the end of loop. The callback function can use this 5110 * fact to implement timeout reset logic while waiting for 5111 * a readers. 5112 * 5113 * \returns The RETURN CODE determines the further actions libmdbx and must 5114 * match the action which was executed by the callback: 5115 * 5116 * \retval -2 or less An error condition and the reader was not killed. 5117 * 5118 * \retval -1 The callback was unable to solve the problem and 5119 * agreed on \ref MDBX_MAP_FULL error; 5120 * libmdbx should increase the database size or 5121 * return \ref MDBX_MAP_FULL error. 5122 * 5123 * \retval 0 (zero) The callback solved the problem or just waited for 5124 * a while, libmdbx should rescan the reader lock table and 5125 * retry. This also includes a situation when corresponding 5126 * transaction terminated in normal way by 5127 * \ref mdbx_txn_abort() or \ref mdbx_txn_reset(), 5128 * and my be restarted. I.e. reader slot don't needed 5129 * to be cleaned from transaction. 5130 * 5131 * \retval 1 Transaction aborted asynchronous and reader slot 5132 * should be cleared immediately, i.e. read transaction 5133 * will not continue but \ref mdbx_txn_abort() 5134 * nor \ref mdbx_txn_reset() will be called later. 5135 * 5136 * \retval 2 or great The reader process was terminated or killed, 5137 * and libmdbx should entirely reset reader registration. 5138 */ 5139 typedef int(MDBX_hsr_func)(const MDBX_env *env, const MDBX_txn *txn, 5140 mdbx_pid_t pid, mdbx_tid_t tid, uint64_t laggard, 5141 unsigned gap, size_t space, 5142 int retry) MDBX_CXX17_NOEXCEPT; 5143 5144 /** \brief Sets a Handle-Slow-Readers callback to resolve database full/overflow 5145 * issue due to a reader(s) which prevents the old data from being recycled. 5146 * \ingroup c_err 5147 * 5148 * The callback will only be triggered when the database is full due to a 5149 * reader(s) prevents the old data from being recycled. 5150 * 5151 * \see MDBX_hsr_func 5152 * \see mdbx_env_get_hsr() 5153 * \see <a href="intro.html#long-lived-read">Long-lived read transactions</a> 5154 * 5155 * \param [in] env An environment handle returned 5156 * by \ref mdbx_env_create(). 5157 * \param [in] hsr_callback A \ref MDBX_hsr_func function 5158 * or NULL to disable. 5159 * 5160 * \returns A non-zero error value on failure and 0 on success. */ 5161 LIBMDBX_API int mdbx_env_set_hsr(MDBX_env *env, MDBX_hsr_func *hsr_callback); 5162 5163 /** \brief Gets current Handle-Slow-Readers callback used to resolve database 5164 * full/overflow issue due to a reader(s) which prevents the old data from being 5165 * recycled. 5166 * \see MDBX_hsr_func 5167 * \see mdbx_env_set_hsr() 5168 * \see <a href="intro.html#long-lived-read">Long-lived read transactions</a> 5169 * 5170 * \param [in] env An environment handle returned by \ref mdbx_env_create(). 5171 * 5172 * \returns A MDBX_hsr_func function or NULL if disabled 5173 * or something wrong. */ 5174 MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API MDBX_hsr_func * 5175 mdbx_env_get_hsr(const MDBX_env *env); 5176 5177 /** \defgroup btree_traversal B-tree Traversal 5178 * This is internal API for mdbx_chk tool. You should avoid to use it, except 5179 * some extremal special cases. 5180 * \ingroup c_extra 5181 * @{ */ 5182 5183 /** \brief Page types for traverse the b-tree. 5184 * \see mdbx_env_pgwalk() \see MDBX_pgvisitor_func */ 5185 enum MDBX_page_type_t { 5186 MDBX_page_broken, 5187 MDBX_page_meta, 5188 MDBX_page_large, 5189 MDBX_page_branch, 5190 MDBX_page_leaf, 5191 MDBX_page_dupfixed_leaf, 5192 MDBX_subpage_leaf, 5193 MDBX_subpage_dupfixed_leaf, 5194 MDBX_subpage_broken, 5195 }; 5196 #ifndef __cplusplus 5197 typedef enum MDBX_page_type_t MDBX_page_type_t; 5198 #endif 5199 5200 /** \brief Pseudo-name for MainDB */ 5201 #define MDBX_PGWALK_MAIN ((const char *)((ptrdiff_t)0)) 5202 /** \brief Pseudo-name for GarbageCollectorDB */ 5203 #define MDBX_PGWALK_GC ((const char *)((ptrdiff_t)-1)) 5204 /** \brief Pseudo-name for MetaPages */ 5205 #define MDBX_PGWALK_META ((const char *)((ptrdiff_t)-2)) 5206 5207 /** \brief Callback function for traverse the b-tree. \see mdbx_env_pgwalk() */ 5208 typedef int MDBX_pgvisitor_func( 5209 const uint64_t pgno, const unsigned number, void *const ctx, const int deep, 5210 const char *const dbi, const size_t page_size, const MDBX_page_type_t type, 5211 const MDBX_error_t err, const size_t nentries, const size_t payload_bytes, 5212 const size_t header_bytes, const size_t unused_bytes) MDBX_CXX17_NOEXCEPT; 5213 5214 /** \brief B-tree traversal function. */ 5215 LIBMDBX_API int mdbx_env_pgwalk(MDBX_txn *txn, MDBX_pgvisitor_func *visitor, 5216 void *ctx, bool dont_check_keys_ordering); 5217 5218 /** \brief Open an environment instance using specific meta-page 5219 * for checking and recovery. 5220 * 5221 * This function mostly of internal API for `mdbx_chk` utility and subject to 5222 * change at any time. Do not use this function to avoid shooting your own 5223 * leg(s). */ 5224 LIBMDBX_API int mdbx_env_open_for_recovery(MDBX_env *env, const char *pathname, 5225 unsigned target_meta, 5226 bool writeable); 5227 #if defined(_WIN32) || defined(_WIN64) 5228 LIBMDBX_API int mdbx_env_open_for_recoveryW(MDBX_env *env, 5229 const wchar_t *pathnameW, 5230 unsigned target_meta, 5231 bool writeable); 5232 #endif /* Windows */ 5233 5234 /** \brief Turn database to the specified meta-page. 5235 * 5236 * This function mostly of internal API for `mdbx_chk` utility and subject to 5237 * change at any time. Do not use this function to avoid shooting your own 5238 * leg(s). */ 5239 LIBMDBX_API int mdbx_env_turn_for_recovery(MDBX_env *env, unsigned target_meta); 5240 5241 /** end of btree_traversal @} */ 5242 5243 /** end of c_api @} */ 5244 5245 #ifdef __cplusplus 5246 } /* extern "C" */ 5247 #endif 5248 5249 #endif /* LIBMDBX_H */