From: Yehuda Sadeh <yehuda@inktank.com>
Date: Fri, 20 Jul 2012 20:28:19 +0000 (-0700)
Subject: cls_lock: document lock properties
X-Git-Tag: v0.51~76^2~2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=315bbea511c0b92f235c543146b890c876eefe49;p=ceph.git

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 f4a47648431d..36a24a5d1945 100644
--- 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 6361e917932d..58254267afab 100644
--- 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,