lmdbjava · at055612 · Jan 27, 2026 · Jan 27, 2026 · Jan 27, 2026 · Jan 27, 2026
diff --git a/pom.xml b/pom.xml
@@ -34,6 +34,7 @@
     <google-java-format.version>1.28.0</google-java-format.version>
     <guava.version>33.5.0-jre</guava.version>
     <jacoco-maven-plugin.version>0.8.14</jacoco-maven-plugin.version>
+    <jmh.version>1.37</jmh.version>
     <jnr-constants.version>0.10.4</jnr-constants.version>
     <jnr-ffi.version>2.2.18</jnr-ffi.version>
     <junit.version>5.14.1</junit.version>
@@ -125,6 +126,18 @@
       <version>${mockito.version}</version>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>org.openjdk.jmh</groupId>
+      <artifactId>jmh-core</artifactId>
+      <version>${jmh.version}</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.openjdk.jmh</groupId>
+      <artifactId>jmh-generator-annprocess</artifactId>
+      <version>${jmh.version}</version>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
   <build>
     <plugins>

diff --git a/src/main/java/org/lmdbjava/AbstractFlagSet.java b/src/main/java/org/lmdbjava/AbstractFlagSet.java
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2016-2025 The LmdbJava Open Source Project
+ * Copyright © 2016-2026 The LmdbJava Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -85,6 +85,18 @@ public String toString() {
     return FlagSet.asString(this);
   }
 
+  @Override
+  public boolean equals(Object object) {
+    if (object == null || getClass() != object.getClass()) return false;
+    AbstractFlagSet<?> that = (AbstractFlagSet<?>) object;
+    return mask == that.mask && Objects.equals(flags, that.flags);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(flags, mask);
+  }
+
   static class AbstractEmptyFlagSet<T extends MaskedFlag> implements FlagSet<T> {
 
     @Override

diff --git a/src/main/java/org/lmdbjava/Cursor.java b/src/main/java/org/lmdbjava/Cursor.java
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2016-2025 The LmdbJava Open Source Project
+ * Copyright © 2016-2026 The LmdbJava Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,60 +30,99 @@
 import static org.lmdbjava.SeekOp.MDB_NEXT;
 import static org.lmdbjava.SeekOp.MDB_PREV;
 
+import java.util.concurrent.atomic.AtomicBoolean;
 import jnr.ffi.Pointer;
 import jnr.ffi.byref.NativeLongByReference;
 
 /**
- * A cursor handle.
+ * A cursor handle for iterating through key/value pairs in an LMDB database.
+ *
+ * <p>A cursor belongs to a {@link Txn}.
+ *
+ * <p>If {@link Txn} is a read-write transaction, LMDB will automatically close the cursor handle
+ * when the {@link Txn} is committed or aborted, meaning that Cursor#close() does not need to be
+ * called, however, if it is called, it must be called before the {@link Txn} is committed/aborted.
+ *
+ * <p>NOTE: If {@link Env.Builder#setSafeClose()} is set, the {@link Env} requires that all cursors
+ * are closed before the {@link Env} is closed, therefore it is good practice to explicitly call
+ * {@link Cursor#close()} or use a try-with-resources block on all types of cursor.
+ *
+ * <p>If {@link Txn} is a read-only transaction, {@link Cursor#close()} must be called to free up
+ * the cursor handle. This can be called at any time. Read-only transactions can 'moved' to a
+ * different transaction using the {@link Cursor#renew(Txn)} method. This can also be done at any
+ * time.
  *
  * @param <T> buffer type
  */
 public final class Cursor<T> implements AutoCloseable {
 
-  private boolean closed;
+  private final AtomicBoolean closed;
   private final KeyVal<T> kv;
   private final Pointer ptrCursor;
-  private Txn<T> txn;
   private final Env<T> env;
+  private final RefCounter.RefCounterReleaser refCounterReleaser;
+  private volatile Txn<T> txn;
 
   Cursor(final Pointer ptr, final Txn<T> txn, final Env<T> env) {
     requireNonNull(ptr);
     requireNonNull(txn);
+    requireNonNull(env);
     this.ptrCursor = ptr;
     this.txn = txn;
-    this.kv = txn.newKeyVal();
+    // The env needs to track open RW cursors to prevent env closure before the cursors are closed.
+    // We don't care about RO cursors as LMDB will automatically free them.
+    refCounterReleaser = txn.isWritable() ? env.acquire() : null;
     this.env = env;
+    this.closed = new AtomicBoolean(false);
+    try {
+      this.kv = txn.newKeyVal();
+    } catch (final Exception e) {
+      closed.set(true);
+      releaseRefCount();
+
+      // Clean up the native cursor
+      if (txn.isReadOnly() || txn.isReady()) {
+        LIB.mdb_cursor_close(ptrCursor);
+      }
+      throw e;
+    }
   }
 
   /**
    * Close a cursor handle.
    *
    * <p>The cursor handle will be freed and must not be used again after this call. Its transaction
-   * must still be live if it is a write-transaction.
+   * must still be live (i.e. not committed or aborted) if it is a write-transaction.
    */
   @Override
   public void close() {
-    if (closed) {
-      return;
-    }
-    kv.close();
-    if (SHOULD_CHECK) {
-      env.checkNotClosed();
-      if (!txn.isReadOnly()) {
-        txn.checkReady();
+    if (closed.compareAndSet(false, true)) {
+      kv.close();
+      if (SHOULD_CHECK) {
+        env.checkNotClosed();
+        if (!txn.isReadOnly()) {
+          // TODO Rather than throwing if the txn is not in the right state to close
+          //  we could check the txn state and only call mdb_cursor_close if the state is
+          // appropriate,
+          //  i.e. (txn.isReadOnly() || txn.isReady())
+          //  This would make using try-with-resources less likely to fail
+
+          // Cannot close the mdb_cursor if the txn is writable and not in a ready state
+          txn.checkReady();
+        }
       }
+      LIB.mdb_cursor_close(ptrCursor);
+      releaseRefCount();
     }
-    LIB.mdb_cursor_close(ptrCursor);
-    closed = true;
   }
 
   /**
-   * Return count of duplicates for current key.
+   * Return count of duplicates for the current key.
    *
    * <p>This call is only valid on databases that support sorted duplicate data items {@link
    * DbiFlags#MDB_DUPSORT}.
    *
-   * @return count of duplicates for current key
+   * @return count of duplicates for the current key
    */
   public long count() {
     if (SHOULD_CHECK) {
@@ -368,7 +407,6 @@ public void putMultiple(final T key, final T val, final int elements) {
    */
   public void putMultiple(final T key, final T val, final int elements, final PutFlagSet flags) {
     if (SHOULD_CHECK) {
-      requireNonNull(txn);
       requireNonNull(key);
       requireNonNull(val);
       env.checkNotClosed();
@@ -397,19 +435,20 @@ public void putMultiple(final T key, final T val, final int elements, final PutF
    * may be associated with a new read-only transaction, and referencing the same database handle as
    * it was created with. This may be done whether the previous transaction is live or dead.
    *
-   * @param newTxn transaction handle
+   * @param newTxn The new transaction handle to associate with this cursor. It must be a read-only
+   *     transaction and in a ready state, i.e. not committed/aborted/closed.
    */
   public void renew(final Txn<T> newTxn) {
     if (SHOULD_CHECK) {
       requireNonNull(newTxn);
       env.checkNotClosed();
       checkNotClosed();
-      this.txn.checkReadOnly(); // existing
+      txn.checkReadOnly(); // existing
       newTxn.checkReadOnly();
       newTxn.checkReady();
     }
     checkRc(LIB.mdb_cursor_renew(newTxn.pointer(), ptrCursor));
-    this.txn = newTxn;
+    txn = newTxn;
   }
 
   /**
@@ -518,11 +557,18 @@ public T val() {
   }
 
   private void checkNotClosed() {
-    if (closed) {
+    if (closed.get()) {
       throw new ClosedException();
     }
   }
 
+  private void releaseRefCount() {
+    // May be null if the cursor was created with a read-only transaction
+    if (refCounterReleaser != null) {
+      refCounterReleaser.release();
+    }
+  }
+
   /** Cursor has already been closed. */
   public static final class ClosedException extends LmdbException {
 

diff --git a/src/main/java/org/lmdbjava/CursorIterable.java b/src/main/java/org/lmdbjava/CursorIterable.java
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2016-2025 The LmdbJava Open Source Project
+ * Copyright © 2016-2026 The LmdbJava Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -38,6 +38,8 @@
  *
  * <p>An instance will create and close its own cursor.
  *
+ * <p>Not thread safe.
+ *
  * @param <T> buffer type
  */
 public final class CursorIterable<T> implements Iterable<CursorIterable.KeyVal<T>>, AutoCloseable {

diff --git a/src/main/java/org/lmdbjava/Dbi.java b/src/main/java/org/lmdbjava/Dbi.java
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2016-2025 The LmdbJava Open Source Project
+ * Copyright © 2016-2026 The LmdbJava Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -408,6 +408,9 @@ public Cursor<T> openCursor(final Txn<T> txn) {
   /**
    * Starts a new read-write transaction and puts the key/data pair.
    *
+   * <p>NOTE: If this is called while this thread already has an open write transaction, it will
+   * block indefinitely.
+   *
    * @param key key to store in the database (not null)
    * @param val value to store in the database (not null)
    * @see #put(Txn, Object, Object, PutFlagSet)