NAME

       readers - Reader Lock Table

   Data Structures
       struct MDB_rxbody
       struct MDB_reader
       struct MDB_txbody
       struct MDB_txninfo

   Macros
       #define DEFAULT_READERS   126
       #define CACHELINE   64
       #define MDB_LOCK_FORMAT

Detailed Description

       Readers don't acquire any locks for their data access. Instead, they simply record their
       transaction ID in the reader table. The reader mutex is needed just to find an empty slot
       in the reader table. The slot's address is saved in thread-specific data so that
       subsequent read transactions started by the same thread need no further locking to
       proceed.

       If MDB_NOTLS is set, the slot address is not saved in thread-specific data.

       No reader table is used if the database is on a read-only filesystem, or if MDB_NOLOCK is
       set.

       Since the database uses multi-version concurrency control, readers don't actually need any
       locking. This table is used to keep track of which readers are using data from which old
       transactions, so that we'll know when a particular old transaction is no longer in use.
       Old transactions that have discarded any data pages can then have those pages reclaimed
       for use by a later write transaction.

       The lock table is constructed such that reader slots are aligned with the processor's
       cache line size. Any slot is only ever used by one thread. This alignment guarantees that
       there will be no contention or cache thrashing as threads update their own slot info, and
       also eliminates any need for locking when accessing a slot.

       A writer thread will scan every slot in the table to determine the oldest outstanding
       reader transaction. Any freed pages older than this will be reclaimed by the writer. The
       writer doesn't use any locks when scanning this table. This means that there's no
       guarantee that the writer will see the most up-to-date reader info, but that's not
       required for correct operation - all we need is to know the upper bound on the oldest
       reader, we don't care at all about the newest reader. So the only consequence of reading
       stale information here is that old pages might hang around a while longer before being
       reclaimed. That's actually good anyway, because the longer we delay reclaiming old pages,
       the more likely it is that a string of contiguous pages can be found after coalescing old
       pages from many old transactions together.

Data Structure Documentation

struct MDB_rxbody

       The information we store in a single slot of the reader table. In addition to a
       transaction ID, we also record the process and thread ID that owns a slot, so that we can
       detect stale information, e.g. threads or processes that went away without cleaning up.

       Note:
           We currently don't check for stale records. We simply re-init the table when we know
           that we're the only process opening the lock file.

   Data Fields

       volatile txnid_t mrb_txnid
       volatile MDB_PID_T mrb_pid
       volatile MDB_THR_T mrb_tid

Field Documentation

   volatile txnid_t MDB_rxbody::mrb_txnid
       Current Transaction ID when this transaction began, or (txnid_t)-1. Multiple readers that
       start at the same time will probably have the same ID here. Again, it's not important to
       exclude them from anything; all we need to know is which version of the DB they started
       from so we can avoid overwriting any data used in that particular version.

   volatile MDB_PID_T MDB_rxbody::mrb_pid
       The process ID of the process owning this reader txn.

   volatile MDB_THR_T MDB_rxbody::mrb_tid
       The thread ID of the thread owning this txn.

struct MDB_reader

       The actual reader record, with cacheline padding.

   Data Fields

       union {
          MDB_rxbody mrx
          char pad [(sizeof(MDB_rxbody)+CACHELINE-1)&~(CACHELINE-1)]
       } mru

Field Documentation

   char MDB_reader::pad[(sizeof(MDB_rxbody)+CACHELINE-1)&~(CACHELINE-1)]
       cache line alignment

struct MDB_txbody

       The header for the reader table. The table resides in a memory-mapped file. (This is a
       different file than is used for the main database.)

       For POSIX the actual mutexes reside in the shared memory of this mapped file. On Windows,
       mutexes are named objects allocated by the kernel; we store the mutex names in this mapped
       file so that other processes can grab them. This same approach is also used on
       MacOSX/Darwin (using named semaphores) since MacOSX doesn't support process-shared POSIX
       mutexes. For these cases where a named object is used, the object name is derived from a
       64 bit FNV hash of the environment pathname. As such, naming collisions are extremely
       unlikely. If a collision occurs, the results are unpredictable.

   Data Fields

       uint32_t mtb_magic
       uint32_t mtb_format
       mdb_mutex_t mtb_rmutex
       volatile txnid_t mtb_txnid
       volatile unsigned mtb_numreaders

Field Documentation

   uint32_t MDB_txbody::mtb_magic
       Stamp identifying this as an LMDB file. It must be set to MDB_MAGIC.

   uint32_t MDB_txbody::mtb_format
       Format of this lock file. Must be set to MDB_LOCK_FORMAT.

   mdb_mutex_t MDB_txbody::mtb_rmutex
       Mutex protecting access to this table. This is the reader table lock used with
       LOCK_MUTEX().

   volatile txnid_t MDB_txbody::mtb_txnid
       The ID of the last transaction committed to the database. This is recorded here only for
       convenience; the value can always be determined by reading the main database meta pages.

   volatile unsigned MDB_txbody::mtb_numreaders
       The number of slots that have been used in the reader table. This always records the
       maximum count, it is not decremented when readers release their slots.

struct MDB_txninfo

       The actual reader table definition.

   Data Fields

       union {
          MDB_txbody mtb
          char pad [(sizeof(MDB_txbody)+CACHELINE-1)&~(CACHELINE-1)]
       } mt1
       union {
          mdb_mutex_t mt2_wmutex
          char pad [(MNAME_LEN+CACHELINE-1)&~(CACHELINE-1)]
       } mt2
       MDB_reader mti_readers [1]

Macro Definition Documentation

   #define DEFAULT_READERS   126
       Number of slots in the reader table. This value was chosen somewhat arbitrarily. 126
       readers plus a couple mutexes fit exactly into 8KB on my development machine. Applications
       should set the table size using mdb_env_set_maxreaders().

   #define CACHELINE   64
       The size of a CPU cache line in bytes. We want our lock structures aligned to this size to
       avoid false cache line sharing in the lock table. This value works for most CPUs. For
       Itanium this should be 128.

   #define MDB_LOCK_FORMAT
       Value:

       ((uint32_t)      ((MDB_LOCK_VERSION)       /* Flags which describe functionality */       + (((MDB_PIDLOCK) != 0) << 16)))
       Lockfile format signature: version, features and field layout

Author

       Generated automatically by Doxygen for LMDB from the source code.