Subject: [nfsv4] CB_NOTIFY_LOCK

From: "J. Bruce Fields" <[email-masked]>
Date: Tue, 3 Oct 2006 16:40:29 -0400

Here's an updated version of the CB_NOTIFY_LOCK language. As a reminder,
the goals of CB_NOTIFY_LOCK are:

	- to give cooperating clients the chance to acquire locks
	  immediately after they're relased, without having to set
	  ridiculously small polling intervals;
	- to require no modification of any locking state on its own,
	  and hence avoid the raciness and annoying sequencing
	  requirements of a real grant callback;
	- to be optional--servers may omit it, clients may ignore it;
	- to be simple to specify and implement.

The only change is to add an OPEN4_RESULT_MAY_NOTIFY_LOCK flag which the
server can set on open returns, to indicate that it may issue
NOTIFY_LOCK callbacks to clients polling on locks derived from this
open.  The client may use this flag as a hint that it may poll less
aggressively.

---
 Makefile                            |    3 ++
 dotx.d/Makefile                     |    2 +
 dotx.d/cb_notify_lock_args.x        |    4 +++
 dotx.d/cb_notify_lock_res.x         |    3 ++
 dotx.d/open_res.x                   |    2 +
 nfsv41_middle_op_cb_notify_lock.xml |   55 +++++++++++++++++++++++++++++++++++
 nfsv41_middle_op_open.xml           |    3 ++
 7 files changed, 72 insertions(+), 0 deletions(-)

diff --git a/Makefile b/Makefile
index 3101586..1685e33 100755
--- a/Makefile
+++ b/Makefile
@@ -66,6 +66,8 @@ AUTOGEN =	nfsv41_middle_errortoop_autoge
 		autogen/cb_layoutrecall_res.xml \
 		autogen/cb_notify_args.xml \
 		autogen/cb_notify_res.xml \
+		autogen/cb_notify_lock_args.xml \
+		autogen/cb_notify_lock_res.xml \
 		autogen/cb_push_deleg_args.xml \
 		autogen/cb_push_deleg_res.xml \
 		autogen/cb_recall_any_args.xml \
@@ -273,6 +275,7 @@ IDCONTENTS = \
 	nfsv41_middle_op_cb_recall_credit.xml \
 	nfsv41_middle_op_cb_sequence.xml \
 	nfsv41_middle_op_cb_wants_cancelled.xml \
+	nfsv41_middle_op_cb_notify_lock.xml \
 	nfsv41_middle_op_cb_illegal.xml \
 	nfsv41_middle_op_cb_zzz.xml \
 	nfsv41_middle_security_considerations.xml \
diff --git a/dotx.d/Makefile b/dotx.d/Makefile
index a73af18..0d00514 100755
--- a/dotx.d/Makefile
+++ b/dotx.d/Makefile
@@ -112,6 +112,8 @@ BACK_OPS =	cb_getattr_args.x \
 		cb_layoutrecall_res.x \
 		cb_notify_args.x \
 		cb_notify_res.x \
+		cb_notify_lock_args.x \
+		cb_notify_lock_res.x \
 		cb_push_deleg_args.x \
 		cb_push_deleg_res.x \
 		cb_recall_any_args.x \
diff --git a/dotx.d/cb_notify_lock_args.x b/dotx.d/cb_notify_lock_args.x
new file mode 100644
index 0000000..1192538
--- /dev/null
+++ b/dotx.d/cb_notify_lock_args.x
@@ -0,0 +1,4 @@
+struct CB_NOTIFY_LOCK4args {
+    nfs_fh4     file;
+    lock_owner4 lock_owner;
+}
diff --git a/dotx.d/cb_notify_lock_res.x b/dotx.d/cb_notify_lock_res.x
new file mode 100644
index 0000000..58a644e
--- /dev/null
+++ b/dotx.d/cb_notify_lock_res.x
@@ -0,0 +1,3 @@
+struct CB_NOTIFY_LOCK4res {
+        nfsstat4        status;
+};
diff --git a/dotx.d/open_res.x b/dotx.d/open_res.x
index 44deedd..169738f 100755
--- a/dotx.d/open_res.x
+++ b/dotx.d/open_res.x
@@ -69,6 +69,8 @@ switch (open_delegation_type4 delegation
 const OPEN4_RESULT_CONFIRM	= 0x00000002;
 /* Type of file locking behavior at the server */
 const OPEN4_RESULT_LOCKTYPE_POSIX = 0x00000004;
+/* Server may use CB_NOTIFY_LOCK on locks derived from this open */
+const OPEN4_RESULT_MAY_NOTIFY_LOCK = 0x00000008;
 
 struct OPEN4resok {
 	stateid4	stateid;	/* Stateid for open */
diff --git a/nfsv41_middle_op_cb_notify_lock.xml b/nfsv41_middle_op_cb_notify_lock.xml
new file mode 100644
index 0000000..2b7149f
--- /dev/null
+++ b/nfsv41_middle_op_cb_notify_lock.xml
@@ -0,0 +1,55 @@
+<!-- Copyright (C) The Internet Society (2006) -->
+<section anchor="OP_CB_NOTIFY_LOCK" title="Operation 13: CB_NOTIFY_LOCK - Notify of possible lock availability" >
+  <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_SYNOPSIS" title="SYNOPSIS">
+    <figure>
+      <artwork>
+fh, lockowner -> ()
+      </artwork>
+    </figure>
+  </section>
+  <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_ARGUMENT" title="ARGUMENT">
+    <?rfc include='autogen/cb_notify_lock_args.xml'?>
+  </section>
+  <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_RESULT" title="RESULT">
+    <?rfc include='autogen/cb_notify_lock_res.xml'?>
+  </section>
+  <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_DESCRIPTION" title="DESCRIPTION">
+    <t>
+     The server may use this operation to indicate that a lock for the given
+     file and lockowner may have become available.
+    </t>
+    <t>
+     This callback is meant to be used by servers to help reduce the latency of
+     blocking locks in the case where they recognize that a client which has
+     been polling for a blocking lock may now be able to acquire the lock.
+     The notification is purely a hint, provided as a possible performance
+     optimization, and is not required for correctness.
+    </t>
+  </section>
+  <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_IMPLEMENTATION" title="IMPLEMENTATION">
+    <t>
+     The server must not grant the lock to the client unless and until it
+     recieves an actual lock request from the client.  Similarly, the client
+     receiving this callback cannot assume that it now has the lock, or that a
+     subsequent request for the lock will be succesful.
+    </t>
+    <t>
+     The server is not required to implement this callback, and even if it
+     does, it is not required to use it in any particular case.  Therefore the
+     client must still rely on polling for blocking locks, as described in the
+     "Blocking Locks" section.
+    </t>
+    <t>
+     Similarly, the client is not required to implement this callback, and even
+     it does, is still free to ignore it.  Therefore the server must not assume
+     that the client will act based on the callback.
+    </t>
+    <t>
+     If the server supports this callback for a given file, it should set the
+     OPEN4_RESULT_MAY_NOTIFY_LOCK flag when responding to succesful opens
+     for that file.  This does not commit the server to use of CB_NOTIFY_LOCK,
+     but the client may use this as a hint to decide how frequently poll
+     for locks derived from that open.
+    </t>
+  </section>
+</section>
diff --git a/nfsv41_middle_op_open.xml b/nfsv41_middle_op_open.xml
index e7952af..5259498 100755
--- a/nfsv41_middle_op_open.xml
+++ b/nfsv41_middle_op_open.xml
@@ -173,6 +173,9 @@ stateid, cinfo, rflags, open_confirm, at
       behavior supports the complete set of Posix locking techniques.  From
       this the client can choose to manage file locking state in a way to
       handle a mis-match of file locking management.
+      OPEN4_RESULT_MAY_NOTIFY_LOCK indicates that the server may attempt
+      CB_NOTIFY_LOCK callbacks for locks on this file.  This flag is a hint
+      only, and may be safely ignored by the client.
     </t>
     <t>
       If the component is of zero length, NFS4ERR_INVAL will be returned.
-- 
1.4.2.g55c3

_______________________________________________
nfsv4 mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/nfsv4