fs/ceph/super: document struct ceph_dentry_info and its flags
PATCH 1/1 fs/ceph/super: document struct ceph_dentry_info and its flags
--- fs/ceph/super.h | 122 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 119 insertions(+), 3 deletions(-)
fs/ceph/super.h +119 -3
@@ -326,29 +326,145 @@ struct ceph_inode_xattr {int should_free_val; }; -/* -* Ceph dentry state +/** +* Ceph-specific dentry data (for `dentry.d_fsdata`). Call +* ceph_dentry() to obtain the #ceph_dentry_info pointer from a +* #dentry. */ struct ceph_dentry_info { +/** +* A pointer back to the #dentry owning this object. +*/ struct dentry *dentry; + +/** +* The #ceph_mds_session that issued the lease; holds a +* reference that must be freed with ceph_put_mds_session(). +* May be NULL. +*/ struct ceph_mds_session *lease_session; + +/** +* List hook; depending on the flags, it may be in +* ceph_mds_client.dentry_leases, +* ceph_mds_client.dentry_dir_leases or in +* __dentry_leases_walk().dispose (or in no list at all if +* this #list_head is empty). +*/ struct list_head lease_list; + +/** +* Hook for `ceph_fs_client.async_unlink_conflict`, protected +* by `ceph_fs_client.async_unlink_conflict_lock`. +*/ struct hlist_node hnode; + +/** +* Bit mask of CEPH_DENTRY_* +*/ unsigned long flags; + +/** +* Snapshot of the parent directory's +* `ceph_inode_info.i_shared_gen` taken when this dentry was +* last validated against the directory lease. When the +* directory's `i_shared_gen` moves on, all cached dentries +* below it (including this one's #offset) are stale. +*/ int lease_shared_gen; + +/** +* Snapshot of the issuing `ceph_mds_session.s_cap_gen` taken +* when the (single-dentry) lease was granted. The lease is +* only valid while this matches the session's current +* generation; a session reconnect bumps `s_cap_gen` and thus +* invalidates all of its leases. Zero means "no valid +* lease". +*/ u32 lease_gen; + +/** +* The lease sequence number as received from the MDS +* (`ceph_mds_reply_lease.seq`). It is echoed back to the MDS +* in lease RENEW/REVOKE messages. +*/ u32 lease_seq; -unsigned long lease_renew_after, lease_renew_from; + +/** +* Jiffies timestamp: the earliest time at which a proactive +* lease renewal should be initiated (roughly half the lease +* TTL). Zero while a renewal is already in flight (see +* #lease_renew_from). +*/ +unsigned long lease_renew_after; + +/** +* Jiffies timestamp recorded when a lease renewal request was +* sent; the new TTL and #lease_renew_after are computed +* relative to it once the reply arrives. Zero when no +* renewal is pending. +*/ +unsigned long lease_renew_from; + +/** +* Jiffies timestamp whose meaning depends on which lease this +* dentry holds: for a single-dentry lease it is the expiry +* time (TTL); for a directory lease it is when the dir lease +* was last touched (compared against +* `ceph_lease_walk_control.dir_lease_ttl`). +*/ unsigned long time; + +/** +* This dentry's position (an encoded file position; see +* ceph_make_fpos()) within its parent directory's readdir +* stream, used to preserve readdir ordering when serving +* entries from cached dentries. Zero if unknown/invalid. +*/ u64 offset; }; +/** +* Second-chance ("referenced") bit for the dentry-lease shrinker: set +* when a dentry already queued on the shrink list is touched again, so +* the shrinker spares it for another round instead of disposing of it +* (a clock/LRU-style approximation). +*/ #define CEPH_DENTRY_REFERENCED (1 << 0) + +/** +* `ceph_dentry_info.lease_list` is on the +* `ceph_mds_client.dentry_leases` list. +*/ #define CEPH_DENTRY_LEASE_LIST (1 << 1) + +/** +* `ceph_dentry_info.lease_list` is on the +* __dentry_leases_walk().dispose list. +*/ #define CEPH_DENTRY_SHRINK_LIST (1 << 2) + +/** +* This dentry is the primary link to its inode (as opposed to a +* remote/hard link). Reflected from #CEPH_LEASE_PRIMARY_LINK in the +* MDS lease mask. +*/ #define CEPH_DENTRY_PRIMARY_LINK (1 << 3) + +/** +* An asynchronous unlink is in flight for this dentry. While set, +* the dentry is on the `ceph_fs_client.async_unlink_conflict` hash +* (via `ceph_dentry_info.hnode`); other operations on a conflicting +* name must wait for the bit to clear +* (ceph_wait_on_conflict_unlink()). +*/ #define CEPH_DENTRY_ASYNC_UNLINK_BIT (4)#define CEPH_DENTRY_ASYNC_UNLINK (1 << CEPH_DENTRY_ASYNC_UNLINK_BIT) + +/** +* An asynchronous create is in flight for this dentry; waiters block +* on the bit until the create completes. +*/ #define CEPH_DENTRY_ASYNC_CREATE_BIT (5)#define CEPH_DENTRY_ASYNC_CREATE (1 << CEPH_DENTRY_ASYNC_CREATE_BIT)
Signature · 1 line
2.47.3
Alex Markuze
maintainerHi Max,
NACK for now. Thanks for the patch, but I have some concerns that need a v2:
1. [minor] fs/ceph/super.h:440: CEPH_DENTRY_REFERENCED comment is too narrow
The comment says the bit is set when a dentry on the "shrink list"
is touched again. In practice __ceph_dentry_dir_lease_touch()
also sets it when a dentry already on dentry_dir_leases is
touched — same second-chance concept, different list. The
dispose-path consumer checks the bit to decide whether to requeue
onto either list.
Suggested fix: Widen to: "set when an already-listed dentry is
touched again, so the walker spares it for another round instead of
disposing of it."
2. [minor] fs/ceph/super.h:422: time field comment says last touched but is insertion/requeue timestamp
3. [nit] fs/ceph/super.h:399: lease_seq comment says REVOKE but client sends REVOKE_ACK
Documentation-only patch with two minor semantic inaccuracies (REFERENCED scope, time semantics) and one naming nit (REVOKE vs REVOKE_ACK); needs a v2.
Signature · 1 line
Alex Markuze
Quoted 1 line · Alex Markuze
1. [minor]
fs/ceph/super.h:440:CEPH_DENTRY_REFERENCEDcomment is too narrow
[...]
Quoted 1 line
2. [minor]
fs/ceph/super.h:422: time field comment says last touched but is insertion/requeue timestamp
I don't understand, please explain. The "time" field is only ever updated here:
- ceph_d_init(): initialization after object is created
- __dentry_dir_lease_touch(): I documented this as "last touched"
- ceph_invalidate_dentry_lease(): preparing for destruction
None of these insert or requeue the object anywhere, do they? What does "insertion"/"requeue" even mean here?
Quoted 1 line
3. [nit]
fs/ceph/super.h:399:lease_seqcomment says REVOKE but client sendsREVOKE_ACK
I have fixed 1. and 3. in patch v2.
Signature · 8 lines
Max Kellermann Principal Architect Hosting Technology cm4all | Im Mediapark 6a | 50670 Köln | Germany General information about the company can be found here: https://www.cm4all.com/impressum A member of the IONOS Group