LU-3443 mdc: document mdc_rpc_lock

[fs/lustre-release.git] / lustre / include / lustre_mdc.h

diff --git a/lustre/include/lustre_mdc.h b/lustre/include/lustre_mdc.h
index 8b10c64..bc04678 100644 (file)
--- a/lustre/include/lustre_mdc.h
+++ b/lustre/include/lustre_mdc.h
@@ -28,7 +28,7 @@
  * Use is subject to license terms.
  */
 /*
- * Copyright (c) 2012 Whamcloud, Inc.
+ * Copyright (c) 2011, 2012, Intel Corporation.
  */
 /*
  * This file is part of Lustre, http://www.lustre.org/
@@ -58,10 +58,10 @@
 #endif /* __KERNEL__ */
 #include <lustre_handles.h>
 #include <libcfs/libcfs.h>
+#include <obd_class.h>
 #include <lustre/lustre_idl.h>
 #include <lustre_lib.h>
 #include <lustre_dlm.h>
-#include <lustre_log.h>
 #include <lustre_export.h>
 
 struct ptlrpc_client;
@@ -69,9 +69,27 @@ struct obd_export;
 struct ptlrpc_request;
 struct obd_device;
 
+/**
+ * Serializes in-flight MDT-modifying RPC requests to preserve idempotency.
+ *
+ * This mutex is used to implement execute-once semantics on the MDT.
+ * The MDT stores the last transaction ID and result for every client in
+ * its last_rcvd file. If the client doesn't get a reply, it can safely
+ * resend the request and the MDT will reconstruct the reply being aware
+ * that the request has already been executed. Without this lock,
+ * execution status of concurrent in-flight requests would be
+ * overwritten.
+ *
+ * This design limits the extent to which we can keep a full pipeline of
+ * in-flight requests from a single client.  This limitation could be
+ * overcome by allowing multiple slots per client in the last_rcvd file.
+ */
 struct mdc_rpc_lock {
-       cfs_mutex_t             rpcl_mutex;
+       /** Lock protecting in-flight RPC concurrency. */
+       struct mutex            rpcl_mutex;
+       /** Intent associated with currently executing request. */
        struct lookup_intent    *rpcl_it;
+       /** Used for MDS/RPC load testing purposes. */
        int                     rpcl_fakes;
 };
 
@@ -79,7 +97,7 @@ struct mdc_rpc_lock {
 
 static inline void mdc_init_rpc_lock(struct mdc_rpc_lock *lck)
 {
-        cfs_mutex_init(&lck->rpcl_mutex);
+       mutex_init(&lck->rpcl_mutex);
         lck->rpcl_it = NULL;
 }
 
@@ -88,7 +106,8 @@ static inline void mdc_get_rpc_lock(struct mdc_rpc_lock *lck,
 {
        ENTRY;
 
-       if (it != NULL && (it->it_op == IT_GETATTR || it->it_op == IT_LOOKUP))
+       if (it != NULL && (it->it_op == IT_GETATTR || it->it_op == IT_LOOKUP ||
+                          it->it_op == IT_LAYOUT))
                return;
 
        /* This would normally block until the existing request finishes.
@@ -98,12 +117,12 @@ static inline void mdc_get_rpc_lock(struct mdc_rpc_lock *lck,
         * Only when all fake requests are finished can normal requests
         * be sent, to ensure they are recoverable again. */
  again:
-       cfs_mutex_lock(&lck->rpcl_mutex);
+       mutex_lock(&lck->rpcl_mutex);
 
        if (CFS_FAIL_CHECK_QUIET(OBD_FAIL_MDC_RPCS_SEM)) {
                lck->rpcl_it = MDC_FAKE_RPCL_IT;
                lck->rpcl_fakes++;
-               cfs_mutex_unlock(&lck->rpcl_mutex);
+               mutex_unlock(&lck->rpcl_mutex);
                return;
        }
 
@@ -113,7 +132,7 @@ static inline void mdc_get_rpc_lock(struct mdc_rpc_lock *lck,
         * in this extremely rare case, just have low overhead in
         * the common case when it isn't true. */
        while (unlikely(lck->rpcl_it == MDC_FAKE_RPCL_IT)) {
-               cfs_mutex_unlock(&lck->rpcl_mutex);
+               mutex_unlock(&lck->rpcl_mutex);
                cfs_schedule_timeout(cfs_time_seconds(1) / 4);
                goto again;
        }
@@ -125,11 +144,12 @@ static inline void mdc_get_rpc_lock(struct mdc_rpc_lock *lck,
 static inline void mdc_put_rpc_lock(struct mdc_rpc_lock *lck,
                                    struct lookup_intent *it)
 {
-       if (it != NULL && (it->it_op == IT_GETATTR || it->it_op == IT_LOOKUP))
+       if (it != NULL && (it->it_op == IT_GETATTR || it->it_op == IT_LOOKUP ||
+                          it->it_op == IT_LAYOUT))
                goto out;
 
        if (lck->rpcl_it == MDC_FAKE_RPCL_IT) { /* OBD_FAIL_MDC_RPCS_SEM */
-               cfs_mutex_lock(&lck->rpcl_mutex);
+               mutex_lock(&lck->rpcl_mutex);
 
                LASSERTF(lck->rpcl_fakes > 0, "%d\n", lck->rpcl_fakes);
                lck->rpcl_fakes--;
@@ -142,7 +162,7 @@ static inline void mdc_put_rpc_lock(struct mdc_rpc_lock *lck,
                lck->rpcl_it = NULL;
        }
 
-       cfs_mutex_unlock(&lck->rpcl_mutex);
+       mutex_unlock(&lck->rpcl_mutex);
  out:
        EXIT;
 }