mdcache: documentation for path_traverse

Signed-off-by: Greg Farnum <gregory.farnum@dreamhost.com>

diff --git a/src/mds/MDCache.cc b/src/mds/MDCache.cc
index 35ba8e694e94e510014e944121e51221d4b9c52f..e07479e2fe48bd9acd82c7224fa7aaf567bf1129 100644 (file)
--- a/src/mds/MDCache.cc
+++ b/src/mds/MDCache.cc
@@ -6489,22 +6489,6 @@ void MDCache::dispatch(Message *m)
   }
 }
 
-
-/* path_traverse
- *
- * return values:
- *   <0 : traverse error (ENOTDIR, ENOENT, etc.)
- *    0 : success
- *   >0 : delayed or forwarded
- *
- * onfail values:
- *
- *  MDS_TRAVERSE_FORWARD       - forward to auth (or best guess)
- *  MDS_TRAVERSE_DISCOVER      - discover missing items.  skip permission checks.
- *  MDS_TRAVERSE_DISCOVERXLOCK - discover XLOCKED items too (be careful!).
- *  MDS_TRAVERSE_FAIL          - return an error
- */
-
 Context *MDCache::_get_waiter(MDRequest *mdr, Message *req, Context *fin)
 {
   if (mdr) {
@@ -6518,14 +6502,6 @@ Context *MDCache::_get_waiter(MDRequest *mdr, Message *req, Context *fin)
   }
 }
 
-/*
- * Returns 0 on success, >0 if request has been put on hold or otherwise dealt with,
- * <0 if there's been a failure the caller needs to clean up from.
- *
- * on succes, @pdnvec points to a vector of dentries we traverse.  
- * on failure, @pdnvec it is either the full trace, up to and
- *             including the final null dn, or empty.
- */
 int MDCache::path_traverse(MDRequest *mdr, Message *req, Context *fin,     // who
                           const filepath& path,                   // what
                            vector<CDentry*> *pdnvec,         // result

diff --git a/src/mds/MDCache.h b/src/mds/MDCache.h
index b1132301aed83cf0c220987733c936bd4ee4aafe..21a6c5177cce1b63ee6828560841069694d3c9da 100644 (file)
--- a/src/mds/MDCache.h
+++ b/src/mds/MDCache.h
@@ -1012,7 +1012,42 @@ public:
   CDentry *get_or_create_stray_dentry(CInode *in);
 
   Context *_get_waiter(MDRequest *mdr, Message *req, Context *fin);
-  int path_traverse(MDRequest *mdr, Message *req, Context *c, const filepath& path,
+
+  /**
+   * Find the given dentry (and whether it exists or not), its ancestors,
+   * and get them all into memory and usable on this MDS. This function
+   * makes a best-effort attempt to load everything; if it needs to
+   * go away and do something then it will put the request on a waitlist.
+   * It prefers the mdr, then the req, then the fin. (At least one of these
+   * must be non-null.)
+   *
+   * At least one of the params mdr, req, and fin must be non-null.
+   *
+   * @param mdr The MDRequest associated with the path. Can be null.
+   * @param req The Message associated with the path. Can be null.
+   * @param fin The Context associated with the path. Can be null.
+   * @param filepath The path to traverse to.
+   * @pdnvec Data return parameter -- on success, contains a vector of dentries.
+   * On failure, is either empty or contains the full trace of traversable
+   * dentries.
+   * @param pin Data return parameter -- if successful, points to the inode
+   * associated with filepath. If unsuccessful, is null.
+   * @param onfail Specifies different lookup failure behaviors. If set to
+   * MDS_TRAVERSE_DISCOVERXLOCK, path_traverse will succeed on null
+   * dentries (instead of returning -ENOENT). If set to
+   * MDS_TRAVERSE_FORWARD, it will forward the request to the auth
+   * MDS if that becomes appropriate (ie, if it doesn't know the contents
+   * of a directory). If set to MDS_TRAVERSE_DISCOVER, it
+   * will attempt to look up the path from a different MDS (and bring them
+   * into its cache as replicas).
+   *
+   * @returns 0 on success, 1 on "not done yet", 2 on "forwarding", -errno otherwise.
+   * If it returns 1, the requester associated with this call has been placed
+   * on the appropriate waitlist, and it should unwind itself and back out.
+   * If it returns 2 the request has been forwarded, and again the requester
+   * should unwind itself and back out.
+   */
+  int path_traverse(MDRequest *mdr, Message *req, Context *fin, const filepath& path,
                    vector<CDentry*> *pdnvec, CInode **pin, int onfail);
   bool path_is_mine(filepath& path);
   bool path_is_mine(string& p) {