From 7d3e9651f39746adb4039f476be7817614ee1295 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Renault?= Date: Sun, 15 Dec 2024 13:33:26 +0100 Subject: [PATCH] Document the WithTls, WithoutTls and TlsUsage types and traits --- heed/Cargo.toml | 15 --------------- heed/src/lib.rs | 2 +- heed/src/txn.rs | 19 +++++++++++++++++++ 3 files changed, 20 insertions(+), 16 deletions(-) diff --git a/heed/Cargo.toml b/heed/Cargo.toml index c7e5ef9f..3152a49a 100644 --- a/heed/Cargo.toml +++ b/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"] diff --git a/heed/src/lib.rs b/heed/src/lib.rs index f3b0657f..5baf29f5 100644 --- a/heed/src/lib.rs +++ b/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)] diff --git a/heed/src/txn.rs b/heed/src/txn.rs index 18ecc4c7..95f5aa05 100644 --- a/heed/src/txn.rs +++ b/heed/src/txn.rs @@ -118,13 +118,32 @@ impl 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 +/// transactions at a time. Each transaction belongs to one thread but +/// 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; }