cls_lock: document lock properties

Added some comments about different lock properties.

Signed-off-by: Yehuda Sadeh <yehuda@inktank.com>

diff --git a/src/cls/lock/cls_lock.cc b/src/cls/lock/cls_lock.cc
index f4a47648431db017c5181f8b9e89b0a60ec0475e..36a24a5d1945116ac13559810fe4822adf363388 100644 (file)
--- a/src/cls/lock/cls_lock.cc
+++ b/src/cls/lock/cls_lock.cc
@@ -42,9 +42,11 @@ cls_method_handle_t h_list_locks;
 #define LOCK_PREFIX    "lock."
 
 typedef struct lock_info_s {
-  map<cls_lock_id_t, cls_lock_locker_info_t> lockers;
-  ClsLockType lock_type;
-  string tag;
+  map<cls_lock_id_t, cls_lock_locker_info_t> lockers; // map of lockers
+  ClsLockType lock_type;                              // lock type (exclusive / shared)
+  string tag;                                         // tag: operations on lock can only succeed with this tag
+                                                      //      as long as set of non expired lockers
+                                                      //      is bigger than 0.
 
   void encode(bufferlist &bl) const {
     ENCODE_START(1, 1, bl);

diff --git a/src/cls/lock/cls_lock_types.h b/src/cls/lock/cls_lock_types.h
index 6361e917932d5f99a1e0f1cdac820d3545230e05..58254267afab2a93d2386ee77aab96b75c82ceef 100644 (file)
--- a/src/cls/lock/cls_lock_types.h
+++ b/src/cls/lock/cls_lock_types.h
@@ -27,9 +27,12 @@ static inline const char *cls_lock_type_str(ClsLockType type)
     }
 }
 
+/*
+ * cls_lock_id_t: the locker id, needs to be unique in a single lock
+ */
 struct cls_lock_id_t {
-  entity_name_t locker;
-  string cookie;
+  entity_name_t locker;   // locker's client name
+  string cookie;          // locker's cookie.
 
   cls_lock_id_t() {}
   cls_lock_id_t(entity_name_t& _n, const string& _c) : locker(_n), cookie(_c) {}
@@ -61,9 +64,9 @@ WRITE_CLASS_ENCODER(cls_lock_id_t)
 
 struct cls_lock_locker_info_t
 {
-  utime_t expiration;
-  entity_addr_t addr;
-  string description;
+  utime_t expiration;  // expiration: non-zero means epoch of locker expiration
+  entity_addr_t addr;  // addr: locker address
+  string description;  // description: locker description, may be empty
 
   cls_lock_locker_info_t() {}
   cls_lock_locker_info_t(const utime_t& _e, const entity_addr_t& _a,