Deprecating things (#176)

* Add deprecation notices for NoTLS and Coalesce constants.

* Replace OpenDBI with OpenDBISimple for simplified database handling.

---------

Co-authored-by: JkLondon <ilya@mikheev.fun>

Author: JkLondon

mdbx/cursor_test.go

@@ -51,7 +51,7 @@ func TestCursor_DBI(t *testing.T) {
 	env, _ := setup(t)
 
 	err := env.Update(func(txn *Txn) (err error) {
-		db, err := txn.OpenDBI("db", Create, nil, nil)
+		db, err := txn.OpenDBISimple("db", Create)
 		if err != nil {
 			return err
 		}
@@ -91,7 +91,7 @@ func TestCursor_Close(t *testing.T) {
 	}
 	defer txn.Abort()
 
-	db, err := txn.OpenDBI("testing", Create, nil, nil)
+	db, err := txn.OpenDBISimple("testing", Create)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -210,7 +210,7 @@ func TestCursor_Get_KV(t *testing.T) {
 
 	var dbi DBI
 	err := env.Update(func(txn *Txn) (err error) {
-		dbi, err = txn.OpenDBI("testdb", Create|DupSort, nil, nil)
+		dbi, err = txn.OpenDBISimple("testdb", Create|DupSort)
 		return err
 	})
 	if err != nil {
@@ -277,7 +277,7 @@ func TestLastDup(t *testing.T) {
 
 	var dbi DBI
 	err := env.Update(func(txn *Txn) (err error) {
-		dbi, err = txn.OpenDBI("testdb", Create|DupSort, nil, nil)
+		dbi, err = txn.OpenDBISimple("testdb", Create|DupSort)
 		if err != nil {
 			return err
 		}
@@ -356,7 +356,7 @@ func TestCursor_Get_op_Set_bytesBuffer(t *testing.T) {
 
 	var dbi DBI
 	err := env.Update(func(txn *Txn) (err error) {
-		dbi, err = txn.OpenDBI("testdb", Create|DupSort, nil, nil)
+		dbi, err = txn.OpenDBISimple("testdb", Create|DupSort)
 		return err
 	})
 	if err != nil {
@@ -436,7 +436,7 @@ func TestCursor_Get_DupFixed(t *testing.T) {
 	var dbi DBI
 	key := []byte("key")
 	err := env.Update(func(txn *Txn) (err error) {
-		dbi, err = txn.OpenDBI("test", DupSort|DupFixed|Create, nil, nil)
+		dbi, err = txn.OpenDBISimple("test", DupSort|DupFixed|Create)
 		if err != nil {
 			return err
 		}
@@ -737,7 +737,7 @@ func TestDupCursor_EmptyKeyValues1(t *testing.T) {
 
 	var db DBI
 	err := env.Update(func(txn *Txn) (err error) {
-		db, err = txn.OpenDBI("testingdup", Create|DupSort, nil, nil)
+		db, err = txn.OpenDBISimple("testingdup", Create|DupSort)
 		if err != nil {
 			return err
 		}
@@ -812,7 +812,7 @@ func TestDupCursor_EmptyKeyValues2(t *testing.T) {
 
 	var db DBI
 	err := env.Update(func(txn *Txn) (err error) {
-		db, err = txn.OpenDBI("testingdup", Create|DupSort, nil, nil)
+		db, err = txn.OpenDBISimple("testingdup", Create|DupSort)
 		if err != nil {
 			return err
 		}
@@ -916,7 +916,7 @@ func TestDupCursor_EmptyKeyValues3(t *testing.T) {
 
 	var db DBI
 	err := env.Update(func(txn *Txn) (err error) {
-		db, err = txn.OpenDBI("testingdup", Create|DupSort, nil, nil)
+		db, err = txn.OpenDBISimple("testingdup", Create|DupSort)
 		if err != nil {
 			return err
 		}
@@ -1029,7 +1029,7 @@ func TestDupCursor_EmptyKeyValues(t *testing.T) {
 
 	var db DBI
 	err := env.Update(func(txn *Txn) (err error) {
-		db, err = txn.OpenDBI("testingdup", Create|DupSort, nil, nil)
+		db, err = txn.OpenDBISimple("testingdup", Create|DupSort)
 		if err != nil {
 			return err
 		}
@@ -1157,7 +1157,7 @@ func TestCursor_Count_DupSort(t *testing.T) {
 
 	var db DBI
 	err := env.Update(func(txn *Txn) (err error) {
-		db, err = txn.OpenDBI("testingdup", Create|DupSort, nil, nil)
+		db, err = txn.OpenDBISimple("testingdup", Create|DupSort)
 		if err != nil {
 			return err
 		}
@@ -1209,7 +1209,7 @@ func TestCursor_Del_DupSort(t *testing.T) {
 
 	var db DBI
 	err := env.Update(func(txn *Txn) (err error) {
-		db, err = txn.OpenDBI("testingdup", Create|DupSort, nil, nil)
+		db, err = txn.OpenDBISimple("testingdup", Create|DupSort)
 		if err != nil {
 			return err
 		}

mdbx/env.go

@@ -32,17 +32,19 @@ const (
 	EnvDefaults = C.MDBX_ENV_DEFAULTS
 	LifoReclaim = C.MDBX_LIFORECLAIM
 	//FixedMap    = C.MDBX_FIXEDMAP   // Danger zone. Map memory at a fixed address.
-	NoSubdir        = C.MDBX_NOSUBDIR // Argument to Open is a file, not a directory.
-	Accede          = C.MDBX_ACCEDE
-	Coalesce        = C.MDBX_COALESCE
-	Readonly        = C.MDBX_RDONLY     // Used in several functions to denote an object as readonly.
-	WriteMap        = C.MDBX_WRITEMAP   // Use a writable memory map.
-	NoMetaSync      = C.MDBX_NOMETASYNC // Don't fsync metapage after commit.
-	UtterlyNoSync   = C.MDBX_UTTERLY_NOSYNC
-	SafeNoSync      = C.MDBX_SAFE_NOSYNC
-	Durable         = C.MDBX_SYNC_DURABLE
+	NoSubdir = C.MDBX_NOSUBDIR // Argument to Open is a file, not a directory.
+	Accede   = C.MDBX_ACCEDE
+	// Deprecated: always turned on since v0.12, deprecated since v0.13
+	Coalesce      = C.MDBX_COALESCE
+	Readonly      = C.MDBX_RDONLY     // Used in several functions to denote an object as readonly.
+	WriteMap      = C.MDBX_WRITEMAP   // Use a writable memory map.
+	NoMetaSync    = C.MDBX_NOMETASYNC // Don't fsync metapage after commit.
+	UtterlyNoSync = C.MDBX_UTTERLY_NOSYNC
+	SafeNoSync    = C.MDBX_SAFE_NOSYNC
+	Durable       = C.MDBX_SYNC_DURABLE
+	// Deprecated: use NoStickyThreads instead because now they're sharing the same functionality
 	NoTLS           = C.MDBX_NOTLS           // Danger zone. When unset reader locktable slots are tied to their thread.
-	NoStickyThreads = C.MDBX_NOSTICKYTHREADS // Danger zone. Like MDBX_NOTLS. But also allow move RwTx between threads. Still require to call Begin/Rollback in stame thread.
+	NoStickyThreads = C.MDBX_NOSTICKYTHREADS // Danger zone. Like MDBX_NOTLS. But also allow move RwTx between threads. Still require to call Begin/Rollback in same thread.
 	//NoLock      = C.MDBX_NOLOCK     // Danger zone. MDBX does not use any locks.
 	NoReadahead = C.MDBX_NORDAHEAD // Disable readahead. Requires OS support.
 	NoMemInit   = C.MDBX_NOMEMINIT // Disable MDBX memory initialization.

mdbx/txn.go

@@ -13,7 +13,7 @@ import (
 	"unsafe"
 )
 
-// This flags are used exclusively for Txn.OpenDBI and Txn.OpenRoot.  The
+// This flags are used exclusively for Txn.OpenDBISimple and Txn.OpenRoot.  The
 // Create flag must always be supplied when opening a non-root DBI for the
 // first time.
 //
@@ -418,23 +418,36 @@ func (txn *Txn) renew() error {
 // null bytes in the name argument.
 //
 // See mdbx_dbi_open.
+// Deprecated: use OpenDBISimple instead
 func (txn *Txn) OpenDBI(name string, flags uint, cmp, dcmp CmpFunc) (DBI, error) {
 	cname := C.CString(name)
 	dbi, err := txn.openDBI(cname, flags, (*C.MDBX_cmp_func)(unsafe.Pointer(cmp)), (*C.MDBX_cmp_func)(unsafe.Pointer(dcmp)))
 	C.free(unsafe.Pointer(cname))
 	return dbi, err
 }
 
+// OpenDBISimple opens a named database in the environment.  An error is returned if
+// name is empty.  The DBI returned by OpenDBISimple can be used in other
+// transactions but not before Txn has terminated.
+//
+// OpenDBISimple can only be called after env.SetMaxDBs() has been called to set the
+// maximum number of named databases.
+//
+// The C API uses null terminated strings for database names.  A consequence is
+// that names cannot contain null bytes themselves. OpenDBISimple does not check for
+// null bytes in the name argument.
+//
+// See mdbx_dbi_open.
 func (txn *Txn) OpenDBISimple(name string, flags uint) (DBI, error) {
 	cname := C.CString(name)
 	dbi, err := txn.openDBISimple(cname, flags)
 	C.free(unsafe.Pointer(cname))
 	return dbi, err
 }
 
-// CreateDBI is a shorthand for OpenDBI that passed the flag lmdb.Create.
+// CreateDBI is a shorthand for OpenDBISimple that passed the flag lmdb.Create.
 func (txn *Txn) CreateDBI(name string) (DBI, error) {
-	return txn.OpenDBI(name, Create, nil, nil)
+	return txn.OpenDBISimple(name, Create)
 }
 
 // Flags returns the database flags for handle dbi.
@@ -444,20 +457,21 @@ func (txn *Txn) Flags(dbi DBI) (uint, error) {
 	return uint(cflags), operrno("mdbx_dbi_flags", ret)
 }
 
-// OpenRoot opens the root database.  OpenRoot behaves similarly to OpenDBI but
+// OpenRoot opens the root database.  OpenRoot behaves similarly to OpenDBISimple but
 // does not require env.SetMaxDBs() to be called beforehand.  And, OpenRoot can
 // be called without flags in a View transaction.
 func (txn *Txn) OpenRoot(flags uint) (DBI, error) {
-	return txn.openDBI(nil, flags, nil, nil)
+	return txn.openDBISimple(nil, flags)
 }
 
 type Cmp func(k1, k2 []byte) int
 
-// openDBI returns returns whatever DBI value was set by mdbx_open_dbi.  In an
+// openDBI returns whatever DBI value was set by mdbx_open_dbi.  In an
 // error case, LMDB does not currently set DBI in case of failure, so zero is
 // returned in those cases.  This is not a big deal for now because
 // applications are expected to handle any error encountered opening a
 // database.
+// Deprecated: openDBISimple instead because using comparators now is a deprecated
 func (txn *Txn) openDBI(cname *C.char, flags uint, cmp, dcmp *C.MDBX_cmp_func) (DBI, error) {
 	var dbi C.MDBX_dbi
 	ret := C.mdbx_dbi_open_ex(txn._txn, cname, C.MDBX_db_flags_t(flags), &dbi, cmp, dcmp)

mdbx/txn_test.go

@@ -46,7 +46,7 @@ func TestTxn_ID(t *testing.T) {
 	}
 
 	err = env.Update(func(txn *Txn) (err error) {
-		dbi, err := txn.OpenDBI("test", Create, nil, nil)
+		dbi, err := txn.OpenDBISimple("test", Create)
 		if err != nil {
 			return err
 		}
@@ -556,7 +556,7 @@ func TestTxn_Flags(t *testing.T) {
 
 	dbflags := uint(ReverseKey | ReverseDup | DupSort | DupFixed)
 	err := env.Update(func(txn *Txn) (err error) {
-		db, err := txn.OpenDBI("testdb", dbflags|Create, nil, nil)
+		db, err := txn.OpenDBISimple("testdb", dbflags|Create)
 		if err != nil {
 			return err
 		}
@@ -613,7 +613,7 @@ func TestTxn_Flags(t *testing.T) {
 		return
 	}
 	err = env.View(func(txn *Txn) (err error) {
-		db, err := txn.OpenDBI("testdb", 0, nil, nil)
+		db, err := txn.OpenDBISimple("testdb", 0)
 		if err != nil {
 			return err
 		}
@@ -1280,7 +1280,7 @@ func openRoot(env *Env, flags uint) (DBI, error) {
 func openDBI(env *Env, key string, flags uint) (DBI, error) {
 	var db DBI
 	err := env.Update(func(txn *Txn) (err error) {
-		db, err = txn.OpenDBI(key, flags, nil, nil)
+		db, err = txn.OpenDBISimple(key, flags)
 		return err
 	})
 	if err != nil {