filesystems/nfs/rpc-cache.rst

5 This document gives a brief introduction to the caching
13 a wide variety of values to be caches.
15 There are a number of caches that are similar in structure though
16 quite possibly very different in content and use.  There is a corpus
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.
42 Creating a Cache
43 ----------------
45 -  A cache needs a datum to store.  This is in the form of a
46    structure definition that must contain a struct cache_head
48    It will also contain a key and some content.
51 -  A cache needs a "cache_detail" structure that
60       a pointer to the cache_detail embedded within the
84       Optional.  Used to provide a /proc file that lists the
85       contents of a cache.  This should show one item,
89       Format a request to be send to user-space for an item
90       to be instantiated.  \*bpp is a buffer of size \*blen.
97       A message from user space has arrived to fill out a
104 -  A cache needs to be registered using cache_register().  This
105    includes it on a list of caches that will be regularly
108 Using a cache
109 -------------
111 To find a value in a cache, call sunrpc_cache_lookup_rcu passing a pointer
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
114 entry is found, a new entry will be create, added to the cache, and
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,
123 cache_check can be passed a "struct cache_req\*".  This structure is
124 typically embedded in the actual request and can be used to create a
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
135 has valid data, then it is discarded and a new item is created.  This
140 Populating a cache
141 ------------------
143 Each cache has a name, and when the cache is registered, a directory
146 This directory contains a file called 'channel' which is a channel
151 The 'channel' works a bit like a datagram socket. Each 'write' is
152 passed as a whole to the cache for parsing and interpretation.
154 expected that a message written will contain:
156   - a key
157   - an expiry time
158   - a content.
164 Reading from a channel is a bit more interesting.  When a cache
166 expire, a request is lodged for that cache item to be updated by
167 user-space.  These requests appear in the channel file.
170 If there are no more requests to return, read will return EOF, but a
174 Thus a user-space helper is likely to::
178     read a request
179     write a response
186 Each cache should define a "cache_parse" method which takes a message
187 written from user-space and processes it.  It should return an error
190 Each cache should also define a "cache_request" method which
191 takes a cache item and encodes a request into the buffer
195   If a cache has no active readers on the channel, and has had not
197   added to the channel but instead all lookups that do not find a valid
199   previous nfs exports table was deemed to be authoritative and a
200   failed lookup meant a definite 'no'.
203 -----------------------
211 If spaces, newlines, or nul characters are needed in a field they
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
218    which give the code for a byte.  Other characters are treated