Document the WithTls, WithoutTls and TlsUsage types and traits

heed/Cargo.toml

@@ -44,21 +44,6 @@ url = "2.5.4"
 default = ["serde", "serde-bincode", "serde-json"]
 serde = ["bitflags/serde", "dep:serde"]
 
-# The #MDB_NOTLS flag is automatically set on Env opening,
-# RoTxn and RoCursors implements the Send trait. This allows the
-# user to move RoTxns and RoCursors between threads as read transactions
-# will no more use thread local storage and will tie reader locktable
-# slots to #MDB_txn objects instead of to threads.
-#
-# According to the LMDB documentation, when this feature is not enabled:
-# A thread can only use one transaction at a time, plus any child
-# transactions. Each transaction belongs to one thread. [...]
-# The #MDB_NOTLS flag changes this for read-only transactions.
-#
-# And a #MDB_BAD_RSLOT error will be thrown when multiple read
-# transactions exists on the same thread
-# read-txn-no-tls = []
-
 # Enable the serde en/decoders for bincode, serde_json, or rmp_serde
 serde-bincode = ["heed-types/serde-bincode"]
 serde-json = ["heed-types/serde-json"]

heed/src/envs/env_open_options.rs

@@ -56,13 +56,24 @@ impl EnvOpenOptions<WithoutTls> {
 }
 
 impl<T: TlsUsage> EnvOpenOptions<T> {
-    /// Make the read transactions `!Send` by specifying they will use Thread Local Storage (TLS).
+    /// Make the read transactions `!Send` by specifying they will
+    /// use Thread Local Storage (TLS).
+    ///
+    /// A thread can only use one transaction at a time, plus any
+    /// child (nested) transactions. Each transaction belongs to one
+    /// thread. A `BadRslot` error will be thrown when multiple read
+    /// transactions exists on the same thread.
     pub fn read_txn_with_tls(self) -> EnvOpenOptions<WithTls> {
         let Self { map_size, max_readers, max_dbs, flags, _tls_marker: _ } = self;
         EnvOpenOptions { map_size, max_readers, max_dbs, flags, _tls_marker: PhantomData }
     }
 
-    /// Make the read transactions `Send` by specifying they will not use Thread Local Storage (TLS).
+    /// Make the read transactions `Send` by specifying they will
+    /// not use Thread Local Storage (TLS).
+    ///
+    /// A thread can use any number of read transactions at a time on
+    /// the same thread. Read transactions can be moved in between
+    /// threads (`Send`).
     pub fn read_txn_without_tls(self) -> EnvOpenOptions<WithoutTls> {
         let Self { map_size, max_readers, max_dbs, flags, _tls_marker: _ } = self;
         EnvOpenOptions { map_size, max_readers, max_dbs, flags, _tls_marker: PhantomData }

heed/src/lib.rs

@@ -104,7 +104,7 @@ use self::mdb::ffi::{from_val, into_val};
 pub use self::mdb::flags::{DatabaseFlags, EnvFlags, PutFlags};
 pub use self::reserved_space::ReservedSpace;
 pub use self::traits::{BoxedError, BytesDecode, BytesEncode, Comparator, LexicographicComparator};
-pub use self::txn::{RoTxn, RwTxn, WithTls, WithoutTls};
+pub use self::txn::{RoTxn, RwTxn, TlsUsage, WithTls, WithoutTls};
 
 /// The underlying LMDB library version information.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]

heed/src/txn.rs

@@ -118,13 +118,32 @@ impl<T> Drop for RoTxn<'_, T> {
 
 /// Parameter defining that read transactions are opened with
 /// Thread Local Storage (TLS) and cannot be sent between threads `!Send`.
+///
+/// When used to open transactions: A thread can only use one transaction
+/// at a time, plus any child (nested) transactions. Each transaction belongs
+/// to one thread. A `BadRslot` error will be thrown when multiple read
+/// transactions exists on the same thread.
 pub enum WithTls {}
 
 /// Parameter defining that read transactions are opened without
 /// Thread Local Storage (TLS) and are therefore `Send`.
+///
+/// When used to open transactions: A thread can use any number
+/// of read transactions at a time on the same thread. Read transactions
+/// can be moved in between threads (`Send`).
 pub enum WithoutTls {}
 
+/// Specifycies if Thread Local Storage (TLS) must be used when
+/// opening transactions. It is often faster to open TLS-backed
+/// transactions but makes them `!Send`.
+///
+/// The `#MDB_NOTLS` flag is set on `Env` opening, `RoTxn`s and
+/// iterators implements the `Send` trait. This allows the user to
+/// move `RoTxn`s and iterators between threads as read transactions
+/// will no more use thread local storage and will tie reader
+/// locktable slots to transaction objects instead of to threads.
 pub trait TlsUsage {
+    /// True if TLS must be used, false otherwise.
     const ENABLED: bool;
 }