From a11c8161ef21f18f0b4cc8b45082e8097d96cbc9 Mon Sep 17 00:00:00 2001
From: Axel Viala <axel.viala@darnuria.eu>
Date: Sun, 9 Jul 2023 18:43:52 +0200
Subject: [PATCH] Fix #164 add documentation about locks and txn limitation of
 lmdb.

---
 heed/src/env.rs | 18 ++++++++++++++++++
 heed/src/txn.rs | 11 +++++++++++
 2 files changed, 29 insertions(+)

diff --git a/heed/src/env.rs b/heed/src/env.rs
index 0df42b21..d5a931d2 100644
--- a/heed/src/env.rs
+++ b/heed/src/env.rs
@@ -584,6 +584,13 @@ impl Env {
     }
 
     /// Create a transaction with read and write access for use with the environment.
+    ///
+    /// ## LMDB limitation
+    ///
+    /// Only one [RwTxn] may exist at the same time on the current environnement.
+    /// If an other write transaction is initiated, while an other write transaction exist
+    /// the thread initiating the new one will wait on a mutex upon completion of the previous
+    /// transaction.
     pub fn write_txn(&self) -> Result<RwTxn> {
         RwTxn::new(self)
     }
@@ -601,6 +608,17 @@ impl Env {
 
     /// Create a transaction with read-only access for use with the environment.
     ///
+    /// ## LMDB Limitation
+    ///
+    /// It's possible to have multiple read transaction on the same environnement
+    /// while there is a write transaction ongoing.
+    ///
+    /// But read transactions prevent reuse of pages freed by newer write transactions,
+    /// thus the database can grow quickly. Write transactions prevent other write transactions,
+    /// since writes are serialized.
+    ///
+    /// So avoid long lived read transaction.
+    ///
     /// ## Errors
     ///
     /// * [heed::mdb::lmdb_error::Error::Panic]: A fatal error occurred earlier and the environnement must be shut down
diff --git a/heed/src/txn.rs b/heed/src/txn.rs
index 3d1229c9..1fa633ce 100644
--- a/heed/src/txn.rs
+++ b/heed/src/txn.rs
@@ -6,6 +6,13 @@ use crate::mdb::ffi;
 use crate::{Env, Result};
 
 /// A read-only transaction.
+///
+/// ## LMDB Limitation
+///
+/// It's a must to keep read transaction short lived.
+///
+/// Active Read transactions prevent reuse of pages freed
+/// by newer write transactions, thus the database can grow quickly.
 pub struct RoTxn<'e> {
     pub(crate) txn: *mut ffi::MDB_txn,
     env: &'e Env,
@@ -50,6 +57,10 @@ fn abort_txn(txn: *mut ffi::MDB_txn) {
 }
 
 /// A read-write transaction.
+///
+/// Only one [RwTxn] may exist on the same environnement at the same time,
+/// it two exist the new one may wait on a Mutex for [RwTxn::commit] or [RwTxn::abort] of
+/// the first one.
 pub struct RwTxn<'p> {
     pub(crate) txn: RoTxn<'p>,
 }