Subject: [nfsv4] Directory delegation text in draft

From: "david m. richter" <[email-masked]>
Date: Wed, 22 Mar 2006 13:55:18 -0500 (EST)

first, i should say that these are minor textual (not technical)
changes to the draft's new delegation text.  these are, to be sure, nits;
but as bruce told me, we'll be reading this document for a long time,
maybe it's worth a bit of nit-picking.  we'll see.

=====================================================================
	in section 22.44.2, i propose changing ..
... from this:

        typedef uint32_t dir_notification_type4;
        typedef nfstime4 attr_notice4;

        struct GET_DIR_DELEGATION4args {
               dir_notification_type4  notification_type;
               attr_notice4            child_attr_delay;
               attr_notice4            dir_attr_delay;
        };

... to this:
        typedef uint32_t dir_notification_type4;
        typedef bitmap4  notification_types4;
        typedef nfstime4 typedef

        struct GET_DIR_DELEGATION4args {
               notification_types4     notif_types;
               notification_delay4     dir_notif_delay;
               notification_delay4     dir_entry_notif_delay;
        };

... because:

-- "dir_notification_type4" is really used as a bitmap, and so encodes
multiple values at once, so perhaps it should be plural, and perhaps it
should actually be listed as a bitmap4 (i had left it as a uint32_t
above).  thoughts?

-- "attr_notice4" is kind of obscure.  perhaps we could encode the "this
is a time value"-idea in the name of the type, as with
"notification_delay4", instead of the name of the variable.

-- "child_attr_delay" is kind of obscure: sounds to me like we're delaying
an attribute in some sense?  rather, we're delaying the notifications
about the attributes.

-- "dir_attr_delay"; just like "child_attr_delay" above.

-- "child" vs. "entry" (above) is very minor.  it briefly came up on the
list in
http://www1.ietf.org/mail-archive/web/nfsv4/current/msg02525.html.  my
offhand feeling is that "directory entry" appearing in the text is a
smidge clearer.  yes, i know this is anal and just a trifle.  :)

=====================================================================
	in section 22.44.3, i propose changing ..
... from this:

      struct GET_DIR_DELEGATION4resok {
             verifier4                       cookieverf;
             /* Stateid for get_dir_delegation */
             stateid4                        stateid;
             /* Which notifications can the server support */
             dir_notification_type4          notification;
             bitmap4                         child_attributes;
             bitmap4                         dir_attributes;
      };

 ... to this:
      struct GET_DIR_DELEGATIONresok {
             verifier4                       cookieverf;
             stateid4                        stateid;
             dir_delegation_status4          status;
             notification_types4             notif_types;
             bitmap4                         dir_notif_attrs;
             bitmap4                         dir_entry_notif_attrs;
      };

      enum dir_delegation_status4 {
             NFS4_DIR_DELEGATION_NONE       = 0, /* an unqualified "no" */
             NFS4_DIR_DELEGATION_READ       = 1, /* read deleg granted */
             NFS4_DIR_DELEGATION_DENIED     = 2, /* denied by policy */
             NFS4_DIR_DELEGATION_UNAVAIL    = 3  /* not supported */
      };

... because:

-- "dir_notification_type4" is mentioned above.

-- "child_attributes" feels a bit imprecise, since it's not
attrs-like-GETATTR, it's on which attrs the server will give
notifications.  that is, there aren't actual attributes in that
variable, it's info about notifications on attributes.

-- "dir_attributes"; just like "child_attributes" above.

	please note my little "enum dir_delegation_status4" used in the
result struct above.  that's just a placeholder for the idea of not using
the operation's return code to represent delegation-specific information
(this idea has been over the list a few times lately).  e.g., the
server refusing to grant a delegation doesn't fail the operation, and so
won't fail a COMPOUND containing GET_DIR_DELEGATION.  anyway, i support
returning delegation-info independent (as with file delegations) of the
operation's return code.

	carl mentioned also adding values to represent denial due to
contention and resource exhaustion.  i expect this issue to come up at the
IETF meeting, so i'm awaiting marching orders :)

=====================================================================
	also in 22.44.4, the description of cookieverf feels a tad vague
(?); it could maybe say something explicit about how the cookieverf is
meant to match that returned by a READDIR, and is just for the client's
benefit.  i'm not saying this well; this ties to my confusion over:

      "If the cookie verifier changes when the client is holding the
    delegation, the delegation will be recalled unless the client has
    asked for notification for this event."

... i think the first part of the statement is correct, but mostly by
implication (?).  i may be wrong, but after speaking with saadia, i no
longer feel that the above text (and stuff around it) means that the
server will somehow explicitly track the cookieverfs for all delegs and
somehow act on that.  now, i -think- it simply means that modifying the
directory (which has the side-effect of changing the dir's cookieverf)
will just break a delegation on it.  am i on-track here?

   	so, the cookieverf is there only to help the client coordinate
between GET_DIR_DELEGATION and READDIR operations, right?  that is, it's
of no value to the server, no?  i am just groping around for simpler
phrasing, that's all.

	anyway, i know this is the tiniest of nit-picking, so pardon me
for that (i was a copy editor); most of my real issues will likely be
addressed by the IETF meeting.

	thanks much,

	d
	.

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