fs: Expand subsection on NFS file delegations.

Add some text about leases, the new corteous server feature and
directory delegations.

diff --git a/Filesystems.m4 b/Filesystems.m4
index ca894346e55d865ee7171c1052c22a01a005acf4..903b0b35a4ebcda8ab3a18997c7cc77617368744 100644 (file)
--- a/Filesystems.m4
+++ b/Filesystems.m4
@@ -1316,15 +1316,43 @@ operations. With close-to-open cache consistency the green client is
 guaranteed to see the write operation of the blue client while there
 is no such guarantee for the red client. </p>
 
-SUBSECTION(«Delegations»)
-
-nfs4 introduced a feature called <em>file delegation</em>. A file
-delegation allows the client to treat a file temporarily as if no
-other client is accessing it.  Once a file has been delegated to a
-client, the client might cache all write operations for this file,
-and only contact the server when memory pressure forces the client
-to free memory by writing back file contents. The server notifies
-the client if another client attempts to access that file.
+SUBSECTION(«File and Directory Delegations»)
+
+<p> nfs4 introduced a per-file state management feature called
+<em>file delegation</em>. Once a file has been delegated to a client,
+the server blocks write access to the file for other nfs clients and
+for local processes. Therefore the client may assume that the file
+does not change unexpectedly. This cache-coherency guarantee can
+improve performance because the client may cache all write operations
+for this file, and only contact the server when memory pressure forces
+the client to free memory by writing back file contents. </p>
+
+<p> A drawback of file delegations is that they delay conflicting open
+requests by other clients because existing delegations must be recalled
+before the open request completes. This is particularly important if
+an nfs client which is holding a delegation gets disconnected from
+the network. To detect this condition, clients report to the server
+that they are still alive by periodically sending a <code>RENEW</code>
+request. If no such request has arrived for the <em>lease time</em>
+(typically 90 seconds), the server may recall any delegations it
+has granted to the disconnected client. This allows accesses from
+other clients that would normally be prevented because of the
+delegation. </p>
+
+<p> However, the server is not obliged to recall <em>uncontested</em>
+delegations for clients whose lease period has expired. In fact,
+newer Linux NFS server implementations retain the uncontested
+state of unresponsive clients for up to 24 hours. This so-called
+<em>courteous server</em> feature was introduced in Linux-5.19
+(released in 2022). </p>
+
+<p> Let us finally remark that the delegations as discussed above
+work only for regular files. NFS versions up to and including 4.0
+do not grant delegations for directories. With nfs4.1 an nfs client
+may ask the server to be notified whenever changes are made to the
+directory by another client. Among other benefits, this feature allows
+for <em>strong directory cache coherency</em>. However, as of 2022,
+directory delegations are not yet implemented by Linux. </p>
 
 SUBSECTION(«Silly Renames and Stale File Handles»)