mdbx: refine mdbx.h and API description, etc (4 of 5).

Change-Id: I36955c54f55facfb31b403f12fe6fd16c789e167

GNUmakefile

@@ -59,7 +59,7 @@ strip: all
 
 clean:
 	rm -rf $(TOOLS) mdbx_test @* *.[ao] *.[ls]o *~ tmp.db/* \
-		*.gcov *.log *.err src/*.o test/*.o example dist \
+		*.gcov *.log *.err src/*.o test/*.o mdbx_example dist \
 		config.h src/elements/config.h src/elements/version.c *.tar*
 
 libmdbx.a: mdbx-static.o
@@ -131,12 +131,12 @@ MDBX_GIT_DESCRIBE = $(shell git describe --tags --long --dirty=-dirty || echo 'P
 MDBX_VERSION_SUFFIX = $(shell set -o pipefail; echo -n '$(MDBX_GIT_DESCRIBE)' | tr -c -s '[a-zA-Z0-9]' _)
 MDBX_BUILD_SOURCERY = $(shell set -o pipefail; $(MAKE) -s src/elements/version.c && (openssl dgst -r -sha256 src/elements/version.c || sha256sum src/elements/version.c || shasum -a 256 src/elements/version.c) 2>/dev/null | cut -d ' ' -f 1 || echo 'Please install openssl or sha256sum or shasum')_$(MDBX_VERSION_SUFFIX)
 
-check: all example mdbx_test
+check: all mdbx_example mdbx_test
 	rm -f $(TEST_DB) $(TEST_LOG) && (set -o pipefail; ./mdbx_test --repeat=$(TEST_ITER) --pathname=$(TEST_DB) --dont-cleanup-after basic | tee -a $(TEST_LOG) | tail -n 42) \
 	&& ./mdbx_chk -vvn $(TEST_DB) && ./mdbx_chk -vvn $(TEST_DB)-copy
 
-example: mdbx.h tutorial/sample-mdbx.c libmdbx.$(SO_SUFFIX)
+mdbx_example: mdbx.h example/example-mdbx.c libmdbx.$(SO_SUFFIX)
-	$(CC) $(CFLAGS) -I. tutorial/sample-mdbx.c ./libmdbx.$(SO_SUFFIX) -o example
+	$(CC) $(CFLAGS) -I. example/example-mdbx.c ./libmdbx.$(SO_SUFFIX) -o $@
 
 check-singleprocess: all mdbx_test
 	rm -f $(TEST_DB) $(TEST_LOG) && (set -o pipefail; \

README.md

@@ -4,7 +4,9 @@
 
 libmdbx
 ======================================
-Revised and extended descendant of [Lightning Memory-Mapped
+MDBX is compact, fast, powerful, and robust and implements a simplified
+variant of the BerkeleyDB API. In fact _libmdbx_ is revised and extended
+descendant of [Lightning Memory-Mapped
 Database](https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database)
 (aka _LMDB_). Permissive non-copyleft BSD-style [OpenLDAP Public License
 2.8](LICENSE). Русскоязычная версия этого README [здесь](README-RU.md).

example/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(TARGET mdbx_example)
+project(${TARGET})
+
+add_executable(${TARGET} example-mdbx.c)
+
+target_link_libraries(${TARGET} mdbx)

example/README.md

@@ -0,0 +1 @@
+See [example-mdbx.c](example-mdbx.c) as an example of using _libmdbx_, and do a line-by-line comparison of it with the [sample-bdb.txt](sample-bdb.txt) file.

example/example-mdbx.c

@@ -1,11 +1,11 @@
-/* sample-mdb.txt - MDB toy/sample
+/* MDBX usage examle
  *
  * Do a line-by-line comparison of this and sample-bdb.txt
  */
 
 /*
- * Copyright 2017 Ilya Shipitsin <chipitsine@gmail.com>.
  * Copyright 2015-2019 Leonid Yuriev <leo@yuriev.ru>.
+ * Copyright 2017 Ilya Shipitsin <chipitsine@gmail.com>.
  * Copyright 2012-2015 Howard Chu, Symas Corp.
  * All rights reserved.
  *

example/sample-bdb.txt

@@ -1,6 +1,6 @@
-/* sample-bdb.txt - BerkeleyDB toy/sample
+/* BerkeleyDB toy/sample
  *
- * Do a line-by-line comparison of this and sample-mdb.txt
+ * Do a line-by-line comparison of this and example-mdbx.c
  */
 
 /*

src/elements/core.c

@@ -3153,7 +3153,7 @@ fail:
   return rc;
 }
 
-__cold static int mdbx_env_sync_ex(MDBX_env *env, int force, int nonblock) {
+__cold int mdbx_env_sync_ex(MDBX_env *env, int force, int nonblock) {
   if (unlikely(!env))
     return MDBX_EINVAL;
 
@@ -3770,7 +3770,7 @@ MDBX_env *mdbx_txn_env(MDBX_txn *txn) {
 
 uint64_t mdbx_txn_id(MDBX_txn *txn) {
   if (unlikely(!txn || txn->mt_signature != MDBX_MT_SIGNATURE))
-    return ~(txnid_t)0;
+    return 0;
   return txn->mt_txnid;
 }
 
@@ -6063,7 +6063,7 @@ mdbx_env_set_geometry(MDBX_env *env, intptr_t size_lower, intptr_t size_now,
   int rc = MDBX_PROBLEM;
   if (env->me_map) {
     /* env already mapped */
-    if (!env->me_lck || (env->me_flags & MDBX_RDONLY))
+    if (unlikely(env->me_flags & MDBX_RDONLY))
       return MDBX_EACCESS;
 
     if (!inside_txn) {
@@ -6277,6 +6277,10 @@ mdbx_env_set_geometry(MDBX_env *env, intptr_t size_lower, intptr_t size_now,
       /* Was DB shrinking disabled before and now it will be enabled? */
       if (new_geo.lower < new_geo.upper && new_geo.shrink &&
           !(current_geo->lower < current_geo->upper && current_geo->shrink)) {
+        if (!env->me_lck) {
+          rc = MDBX_EPERM;
+          goto bailout;
+        }
         rc = mdbx_rdt_lock(env);
         if (unlikely(rc != MDBX_SUCCESS))
           goto bailout;
@@ -7993,9 +7997,8 @@ static int mdbx_cursor_sibling(MDBX_cursor *mc, int move_right) {
   MDBX_node *indx;
   MDBX_page *mp;
 
-  if (unlikely(mc->mc_snum < 2)) {
+  if (unlikely(mc->mc_snum < 2))
     return MDBX_NOTFOUND; /* root has no siblings */
-  }
 
   mdbx_cursor_pop(mc);
   mdbx_debug("parent page is page %" PRIaPGNO ", index %u",
@@ -12496,11 +12499,11 @@ static int __cold mdbx_stat0(const MDBX_env *env, const MDBX_db *db,
 }
 
 int __cold mdbx_env_stat(MDBX_env *env, MDBX_stat *arg, size_t bytes) {
-  return mdbx_env_stat2(env, NULL, arg, bytes);
+  return mdbx_env_stat_ex(env, NULL, arg, bytes);
 }
 
-int __cold mdbx_env_stat2(const MDBX_env *env, const MDBX_txn *txn,
+int __cold mdbx_env_stat_ex(const MDBX_env *env, const MDBX_txn *txn,
-                          MDBX_stat *arg, size_t bytes) {
+                            MDBX_stat *arg, size_t bytes) {
   if (unlikely((env == NULL && txn == NULL) || arg == NULL))
     return MDBX_EINVAL;
 
@@ -12537,11 +12540,11 @@ int __cold mdbx_env_stat2(const MDBX_env *env, const MDBX_txn *txn,
 }
 
 int __cold mdbx_env_info(MDBX_env *env, MDBX_envinfo *arg, size_t bytes) {
-  return mdbx_env_info2(env, NULL, arg, bytes);
+  return mdbx_env_info_ex(env, NULL, arg, bytes);
 }
 
-int __cold mdbx_env_info2(const MDBX_env *env, const MDBX_txn *txn,
+int __cold mdbx_env_info_ex(const MDBX_env *env, const MDBX_txn *txn,
-                          MDBX_envinfo *arg, size_t bytes) {
+                            MDBX_envinfo *arg, size_t bytes) {
   if (unlikely((env == NULL && txn == NULL) || arg == NULL))
     return MDBX_EINVAL;
 

src/tools/mdbx_chk.c

@@ -1063,13 +1063,13 @@ int main(int argc, char *argv[]) {
   }
   maxkeysize = rc;
 
-  rc = mdbx_env_info2(env, txn, &envinfo, sizeof(envinfo));
+  rc = mdbx_env_info_ex(env, txn, &envinfo, sizeof(envinfo));
   if (rc) {
     error("mdbx_env_info failed, error %d %s\n", rc, mdbx_strerror(rc));
     goto bailout;
   }
 
-  rc = mdbx_env_stat2(env, txn, &envstat, sizeof(envstat));
+  rc = mdbx_env_stat_ex(env, txn, &envstat, sizeof(envstat));
   if (rc) {
     error("mdbx_env_stat failed, error %d %s\n", rc, mdbx_strerror(rc));
     goto bailout;

tutorial/CMakeLists.txt

@@ -1,7 +0,0 @@
-set(TARGET mdbx_tutorial)
-project(${TARGET})
-
-add_executable(${TARGET} sample-mdbx.c)
-
-target_link_libraries(${TARGET} mdbx)
-

tutorial/README.md

@@ -1 +0,0 @@
-This directory is just a placeholder for now. Tutorial and examples will be added later.