Merge pull request #174 from darnuria/doc/read_txn

RwTxn + RoTxn documentation improvement.

heed/src/env.rs

@@ -584,6 +584,13 @@ impl Env {
     }
 
     /// Create a transaction with read and write access for use with the environment.
+    ///
+    /// ## LMDB Limitations
+    ///
+    /// Only one [RwTxn] may exist simultaneously in the current environment.
+    /// If another write transaction is initiated, while another write transaction exists
+    /// 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)
     }
@@ -600,6 +607,25 @@ impl Env {
     }
 
     /// Create a transaction with read-only access for use with the environment.
+    ///
+    /// ## LMDB Limitations
+    ///
+    /// It's possible to have multiple read transactions in the same environment
+    /// 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 transactions.
+    ///
+    /// ## Errors
+    ///
+    /// * [heed::mdb::lmdb_error::Error::Panic]: A fatal error occurred earlier, and the environment must be shut down
+    /// * [heed::mdb::lmdb_error::Error::MapResized]: Another process wrote data beyond this [Env] mapsize and this env
+    /// map must be resized
+    /// * [heed::mdb::lmdb_error::Error::ReadersFull]: a read-only transaction was requested, and the reader lock table is
+    /// full
     pub fn read_txn(&self) -> Result<RoTxn> {
         RoTxn::new(self)
     }

heed/src/txn.rs

@@ -6,6 +6,24 @@ use crate::mdb::ffi;
 use crate::{Env, Result};
 
 /// A read-only transaction.
+///
+/// ## LMDB Limitations
+///
+/// It's a must to keep read transactions short-lived.
+///
+/// Active Read transactions prevent the reuse of pages freed
+/// by newer write transactions, thus the database can grow quickly.
+///
+/// ## OSX/Darwin Limitation
+///
+/// At least 10 transactions can be active at the same time in the same process, since only 10 Posix semaphores can
+/// be active at the same time for a process. Threads are in the same process space.
+///
+/// If the process crash in the Posix semaphore locking section of the transaction, the semaphore will be kept locked.
+///
+/// Note: if you program already use Posix Semaphore then you will have less available for heed/lmdb!
+///
+/// You may changing it by editing at **your own risk**: `/Library/LaunchDaemons/sysctl.plist`
 pub struct RoTxn<'e> {
     pub(crate) txn: *mut ffi::MDB_txn,
     env: &'e Env,
@@ -50,6 +68,23 @@ fn abort_txn(txn: *mut ffi::MDB_txn) {
 }
 
 /// A read-write transaction.
+///
+/// ## LMDB Limitations
+///
+/// Only one [RwTxn] may exist in the same environment 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.
+///
+/// ## OSX/Darwin Limitation
+///
+/// At least 10 transactions can be active at the same time in the same process, since only 10 Posix semaphores can
+/// be active at the same time for a process. Threads are in the same process space.
+///
+/// If the process crash in the Posix semaphore locking section of the transaction, the semaphore will be kept locked.
+///
+/// Note: if you program already use Posix Semaphore then you will have less available for heed/lmdb!
+///
+/// You may changing it by editing at **your own risk**: `/Library/LaunchDaemons/sysctl.plist`
 pub struct RwTxn<'p> {
     pub(crate) txn: RoTxn<'p>,
 }