filesystems/nfs/rpc-cache.rst

21   - mapping from IP address to client name
22   - mapping from client name and filesystem to export options
23   - mapping from UID to list of GIDs, to work around NFS's limitation
25   - mappings between local UID/GID and remote UID/GID for sites that
27   - mapping from network identify to public key for crypto authentication.
31    - general cache lookup with correct locking
32    - supporting 'NEGATIVE' as well as positive entries
33    - allowing an EXPIRED time on cache items, and removing
34      items after they expire, and are no longer in-use.
35    - making requests to user-space to fill in cache entries
36    - allowing user-space to directly set entries in the cache
37    - delaying RPC requests that depend on as-yet incomplete
40    - clean out old entries as they expire.
43 ----------------
45 -  A cache needs a datum to store.  This is in the form of a
51 -  A cache needs a "cache_detail" structure that
64       This is called when the last reference to an item is
85       contents of a cache.  This should show one item,
89       Format a request to be send to user-space for an item
99       cache_parse should parse this, find the item in the
100       cache with sunrpc_cache_lookup_rcu, and update the item
104 -  A cache needs to be registered using cache_register().  This
109 -------------
112 to the cache_head in a sample item with the 'key' fields filled in.
113 This will be passed to ->match to identify the target entry.  If no
117 The item returned is typically passed to cache_check which will check
118 if the data is valid, and may initiate an up-call to get fresh data.
119 cache_check will return -ENOENT in the entry is negative or if an up
120 call is needed but not possible, -EAGAIN if an upcall is pending,
125 deferred copy of the request (struct cache_deferred_req).  This is
126 done when the found cache item is not uptodate, but the is reason to
128 item does become valid, the deferred copy of the request will be
129 revisited (->revisit).  It is expected that this method will
133 sunrpc_cache_update to set the content for the item.  A second item is
134 passed which should hold the content.  If the item found by _lookup
135 has valid data, then it is discarded and a new item is created.  This
136 saves any user of an item from worrying about content changing while
137 it is being inspected.  If the item found by _lookup does not contain
141 ------------------
156   - a key
157   - an expiry time
158   - a content.
160 with the intention that an item in the cache with the give key
162 expiry time should be set on that item.
166 expire, a request is lodged for that cache item to be updated by
167 user-space.  These requests appear in the channel file.
174 Thus a user-space helper is likely to::
187 written from user-space and processes it.  It should return an error
191 takes a cache item and encodes a request into the buffer
203 -----------------------
214 -  If a field begins '\x' then it must contain an even number of
217 -  otherwise a \ in the field must be followed by 3 octal digits