filesystems/nfs/rpc-cache.txt

1 	This document gives a brief introduction to the caching
8 a wide variety of values to be caches.
10 There are a number of caches that are similar in structure though
11 quite possibly very different in content and use.  There is a corpus
35 Creating a Cache
38 1/ A cache needs a datum to store.  This is in the form of a
39    structure definition that must contain a
42    It will also contain a key and some content.
45 2/ A cache needs a "cache_detail" structure that
52    		a pointer to the cache_detail embedded within the
72 		Optional.  Used to provide a /proc file that lists the
73 		contents of a cache.  This should show one item,
77 		Format a request to be send to user-space for an item
78    		to be instantiated.  *bpp is a buffer of size *blen.
84 		A message from user space has arrived to fill out a
91 3/ A cache needs to be registered using cache_register().  This
92    includes it on a list of caches that will be regularly
95 Using a cache
98 To find a value in a cache, call sunrpc_cache_lookup passing a pointer
99 to the cache_head in a sample item with the 'key' fields filled in.
101 entry is found, a new entry will be create, added to the cache, and
110 cache_check can be passed a "struct cache_req *".  This structure is
111 typically embedded in the actual request and can be used to create a
120 sunrpc_cache_update to set the content for the item.  A second item is
122 has valid data, then it is discarded and a new item is created.  This
127 Populating a cache
130 Each cache has a name, and when the cache is registered, a directory
133 This directory contains a file called 'channel' which is a channel
138 The 'channel' works a bit like a datagram socket. Each 'write' is
139 passed as a whole to the cache for parsing and interpretation.
141 expected that a message written will contain:
142   - a key
144   - a content.
149 Reading from a channel is a bit more interesting.  When a cache
151 expire, a request is lodged for that cache item to be updated by
155 If there are no more requests to return, read will return EOF, but a
159 Thus a user-space helper is likely to:
162     read a request
163     write a response
170 Each cache should define a "cache_parse" method which takes a message
174 Each cache should also define a "cache_request" method which
175 takes a cache item and encodes a request into the buffer
178 Note: If a cache has no active readers on the channel, and has had not
180 added to the channel but instead all lookups that do not find a valid
182 previous nfs exports table was deemed to be authoritative and a
183 failed lookup meant a definite 'no'.
194 If spaces, newlines, or nul characters are needed in a field they
196 1/ If a field begins '\x' then it must contain an even number of
199 2/ otherwise a \ in the field must be followed by 3 octal digits
200    which give the code for a byte.  Other characters are treated