[rhmessaging-commits] rhmessaging commits: r1521 - store/trunk/cpp/lib/jrnl.

[rhmessaging-commits at lists.jboss.org]

Author: kpvdr
Date: 2007-12-19 09:18:17 -0500 (Wed, 19 Dec 2007)
New Revision: 1521

Modified:
   store/trunk/cpp/lib/jrnl/enq_map.hpp
   store/trunk/cpp/lib/jrnl/txn_map.hpp
Log:
Some doxygen comments for enq_map and txn_map classes.

Modified: store/trunk/cpp/lib/jrnl/enq_map.hpp
===================================================================
--- store/trunk/cpp/lib/jrnl/enq_map.hpp	2007-12-19 08:50:22 UTC (rev 1520)
+++ store/trunk/cpp/lib/jrnl/enq_map.hpp	2007-12-19 14:18:17 UTC (rev 1521)
@@ -54,7 +54,22 @@
     /**
     * \class enq_map
     * \brief Class for storing the file id (fid) and a transaction locked flag for each enqueued
-    *     data block using the record id (rid) as a key.
+    *     data block using the record id (rid) as a key. This is the primary mechanism for
+    *     deterimining the enqueue low water mark: if an fid exists in this map, then there is
+    *     at least one still-enqueued record in that file. (The transaction map must also be
+    *     clear, however.)
+    *
+    * Map keying rids against fid and lock status. As records ar enqueued, they are added to this
+    * map, and as they are dequeued, they are removed. An enqueue is locked when a transactional
+    * dequeue is pending that has not been either committed or aborted.
+    * <pre>
+    *   key      data
+    *
+    *   rid1 --- [ fid, txn_lock ]
+    *   rid2 --- [ fid, txn_lock ]
+    *   rid3 --- [ fid, txn_lock ]
+    *   ...
+    * </pre>
     */
     class enq_map
     {

Modified: store/trunk/cpp/lib/jrnl/txn_map.hpp
===================================================================
--- store/trunk/cpp/lib/jrnl/txn_map.hpp	2007-12-19 08:50:22 UTC (rev 1520)
+++ store/trunk/cpp/lib/jrnl/txn_map.hpp	2007-12-19 14:18:17 UTC (rev 1521)
@@ -50,6 +50,11 @@
 namespace journal
 {
 
+    /**
+    * \struct txn_data_struct
+    * \brief Struct encapsulating transaction data necessary for processing a transaction
+    *     in the journal once it is closed with either a commit or abort.
+    */
     struct txn_data_struct
     {
         u_int64_t _rid;     ///< Record id for this operation
@@ -64,6 +69,37 @@
     typedef std::vector<txn_data> txn_data_list;
     typedef txn_data_list::iterator tdl_itr;
 
+    /**
+    * \class txn_map
+    * \brief Class for storing transaction data for each open (ie not committed or aborted)
+    *     xid in the store. If aborted, records are discarded; if committed, they are
+    *     transferred to the enqueue map.
+    *
+    * The data is encapsulated by struct txn_data_struct. A vector containing the information
+    * for each operation included as part of the same transaction is mapped against the
+    * xid.
+    *
+    * On transaction commit, then for each operation is handled as follows:
+    *
+    * If an enqueue (_enq_flag is true), then the rid and fid are transferred to the enq_map.
+    * If a dequeue (_enq_flag is false), then the rid stored in the drid field is used to
+    * remove the corresponding record from the enq_map.
+    *
+    * On transaction abort, then for each operation is handled as follows:
+    *
+    * If an enqueue (_enq_flag is true), then the data is simply discarded.
+    * If a dequeue (_enq_flag is false), then the lock for the corresponding enqueue in enq_map
+    * (if not a part of the same transaction) is removed, and the data discarded.
+    *
+    * <pre>
+    *   key      data
+    *
+    *   xid1 --- vector< [ rid, drid, fid, enq_flag, aio_compl ] >
+    *   xid2 --- vector< [ rid, drid, fid, enq_flag, aio_compl ] >
+    *   xid3 --- vector< [ rid, drid, fid, enq_flag, aio_compl ] >
+    *   ...
+    * </pre>
+    */
     class txn_map
     {
     private: