€•£š      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ-/translations/zh_CN/filesystems/nfs/rpc-cache”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/zh_TW/filesystems/nfs/rpc-cache”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/it_IT/filesystems/nfs/rpc-cache”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/ja_JP/filesystems/nfs/rpc-cache”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/ko_KR/filesystems/nfs/rpc-cache”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/sp_SP/filesystems/nfs/rpc-cache”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ	RPC Cache”h]”hŒ	RPC Cache”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒG/var/lib/git/docbuild/linux/Documentation/filesystems/nfs/rpc-cache.rst”h KubhŒ	paragraph”“”)”}”(hŒ‹This document gives a brief introduction to the caching
mechanisms in the sunrpc layer that is used, in particular,
for NFS authentication.”h]”hŒ‹This document gives a brief introduction to the caching
mechanisms in the sunrpc layer that is used, in particular,
for NFS authentication.”…””}”(hh¹hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¢)”}”(hhh]”(h§)”}”(hŒCaches”h]”hŒCaches”…””}”(hhÊhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hhÇhžhhŸh¶h K
ubh¸)”}”(hŒ`The caching replaces the old exports table and allows for
a wide variety of values to be caches.”h]”hŒ`The caching replaces the old exports table and allows for
a wide variety of values to be caches.”…””}”(hhØhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KhhÇhžhubh¸)”}”(hŒ°There are a number of caches that are similar in structure though
quite possibly very different in content and use.  There is a corpus
of common code for managing these caches.”h]”hŒ°There are a number of caches that are similar in structure though
quite possibly very different in content and use.  There is a corpus
of common code for managing these caches.”…””}”(hhæhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KhhÇhžhubh¸)”}”(hŒ4Examples of caches that are likely to be needed are:”h]”hŒ4Examples of caches that are likely to be needed are:”…””}”(hhôhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KhhÇhžhubhŒblock_quote”“”)”}”(hXh  - mapping from IP address to client name
- mapping from client name and filesystem to export options
- mapping from UID to list of GIDs, to work around NFS's limitation
  of 16 gids.
- mappings between local UID/GID and remote UID/GID for sites that
  do not have uniform uid assignment
- mapping from network identify to public key for crypto authentication.
”h]”hŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ&mapping from IP address to client name”h]”h¸)”}”(hj  h]”hŒ&mapping from IP address to client name”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj
  ubj  )”}”(hŒ9mapping from client name and filesystem to export options”h]”h¸)”}”(hj(  h]”hŒ9mapping from client name and filesystem to export options”…””}”(hj*  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khj&  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj
  ubj  )”}”(hŒMmapping from UID to list of GIDs, to work around NFS's limitation
of 16 gids.”h]”h¸)”}”(hŒMmapping from UID to list of GIDs, to work around NFS's limitation
of 16 gids.”h]”hŒOmapping from UID to list of GIDs, to work around NFSâ€™s limitation
of 16 gids.”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khj=  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj
  ubj  )”}”(hŒcmappings between local UID/GID and remote UID/GID for sites that
do not have uniform uid assignment”h]”h¸)”}”(hŒcmappings between local UID/GID and remote UID/GID for sites that
do not have uniform uid assignment”h]”hŒcmappings between local UID/GID and remote UID/GID for sites that
do not have uniform uid assignment”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KhjU  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj
  ubj  )”}”(hŒGmapping from network identify to public key for crypto authentication.
”h]”h¸)”}”(hŒFmapping from network identify to public key for crypto authentication.”h]”hŒFmapping from network identify to public key for crypto authentication.”…””}”(hjq  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khjm  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj
  ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1j  hŸh¶h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh¶h KhhÇhžhubh¸)”}”(hŒ'The common code handles such things as:”h]”hŒ'The common code handles such things as:”…””}”(hj“  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KhhÇhžhubj  )”}”(hXô  - general cache lookup with correct locking
- supporting 'NEGATIVE' as well as positive entries
- allowing an EXPIRED time on cache items, and removing
  items after they expire, and are no longer in-use.
- making requests to user-space to fill in cache entries
- allowing user-space to directly set entries in the cache
- delaying RPC requests that depend on as-yet incomplete
  cache entries, and replaying those requests when the cache entry
  is complete.
- clean out old entries as they expire.
”h]”j	  )”}”(hhh]”(j  )”}”(hŒ)general cache lookup with correct locking”h]”h¸)”}”(hjª  h]”hŒ)general cache lookup with correct locking”…””}”(hj¬  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khj¨  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj¥  ubj  )”}”(hŒ1supporting 'NEGATIVE' as well as positive entries”h]”h¸)”}”(hjÁ  h]”hŒ5supporting â€˜NEGATIVEâ€™ as well as positive entries”…””}”(hjÃ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K hj¿  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj¥  ubj  )”}”(hŒhallowing an EXPIRED time on cache items, and removing
items after they expire, and are no longer in-use.”h]”h¸)”}”(hŒhallowing an EXPIRED time on cache items, and removing
items after they expire, and are no longer in-use.”h]”hŒhallowing an EXPIRED time on cache items, and removing
items after they expire, and are no longer in-use.”…””}”(hjÚ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K!hjÖ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj¥  ubj  )”}”(hŒ6making requests to user-space to fill in cache entries”h]”h¸)”}”(hjð  h]”hŒ6making requests to user-space to fill in cache entries”…””}”(hjò  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K#hjî  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj¥  ubj  )”}”(hŒ8allowing user-space to directly set entries in the cache”h]”h¸)”}”(hj  h]”hŒ8allowing user-space to directly set entries in the cache”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K$hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj¥  ubj  )”}”(hŒ„delaying RPC requests that depend on as-yet incomplete
cache entries, and replaying those requests when the cache entry
is complete.”h]”h¸)”}”(hŒ„delaying RPC requests that depend on as-yet incomplete
cache entries, and replaying those requests when the cache entry
is complete.”h]”hŒ„delaying RPC requests that depend on as-yet incomplete
cache entries, and replaying those requests when the cache entry
is complete.”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K%hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj¥  ubj  )”}”(hŒ&clean out old entries as they expire.
”h]”h¸)”}”(hŒ%clean out old entries as they expire.”h]”hŒ%clean out old entries as they expire.”…””}”(hj8  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K(hj4  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj¥  ubeh}”(h]”h ]”h"]”h$]”h&]”j‹  jŒ  uh1j  hŸh¶h Khj¡  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh¶h KhhÇhžhubh¢)”}”(hhh]”(h§)”}”(hŒCreating a Cache”h]”hŒCreating a Cache”…””}”(hj[  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjX  hžhhŸh¶h K+ubj	  )”}”(hhh]”(j  )”}”(hX-  A cache needs a datum to store.  This is in the form of a
structure definition that must contain a struct cache_head
as an element, usually the first.
It will also contain a key and some content.
Each cache element is reference counted and contains
expiry and update times for use in cache management.”h]”h¸)”}”(hX-  A cache needs a datum to store.  This is in the form of a
structure definition that must contain a struct cache_head
as an element, usually the first.
It will also contain a key and some content.
Each cache element is reference counted and contains
expiry and update times for use in cache management.”h]”hX-  A cache needs a datum to store.  This is in the form of a
structure definition that must contain a struct cache_head
as an element, usually the first.
It will also contain a key and some content.
Each cache element is reference counted and contains
expiry and update times for use in cache management.”…””}”(hjp  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K-hjl  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hji  hžhhŸh¶h Nubj  )”}”(hXQ  A cache needs a "cache_detail" structure that
describes the cache.  This stores the hash table, some
parameters for cache management, and some operations detailing how
to work with particular cache items.

The operations are:

 struct cache_head \*alloc(void)
   This simply allocates appropriate memory and returns
   a pointer to the cache_detail embedded within the
   structure

 void cache_put(struct kref \*)
   This is called when the last reference to an item is
   dropped.  The pointer passed is to the 'ref' field
   in the cache_head.  cache_put should release any
   references create by 'cache_init' and, if CACHE_VALID
   is set, any references created by cache_update.
   It should then release the memory allocated by
   'alloc'.

 int match(struct cache_head \*orig, struct cache_head \*new)
   test if the keys in the two structures match.  Return
   1 if they do, 0 if they don't.

 void init(struct cache_head \*orig, struct cache_head \*new)
   Set the 'key' fields in 'new' from 'orig'.  This may
   include taking references to shared objects.

 void update(struct cache_head \*orig, struct cache_head \*new)
   Set the 'content' fields in 'new' from 'orig'.

 int cache_show(struct seq_file \*m, struct cache_detail \*cd, struct cache_head \*h)
   Optional.  Used to provide a /proc file that lists the
   contents of a cache.  This should show one item,
   usually on just one line.

 int cache_request(struct cache_detail \*cd, struct cache_head \*h, char \*\*bpp, int \*blen)
   Format a request to be send to user-space for an item
   to be instantiated.  \*bpp is a buffer of size \*blen.
   bpp should be moved forward over the encoded message,
   and  \*blen should be reduced to show how much free
   space remains.  Return 0 on success or <0 if not
   enough room or other problem.

 int cache_parse(struct cache_detail \*cd, char \*buf, int len)
   A message from user space has arrived to fill out a
   cache entry.  It is in 'buf' of length 'len'.
   cache_parse should parse this, find the item in the
   cache with sunrpc_cache_lookup_rcu, and update the item
   with sunrpc_cache_update.

”h]”(h¸)”}”(hŒÌA cache needs a "cache_detail" structure that
describes the cache.  This stores the hash table, some
parameters for cache management, and some operations detailing how
to work with particular cache items.”h]”hŒÐA cache needs a â€œcache_detailâ€ structure that
describes the cache.  This stores the hash table, some
parameters for cache management, and some operations detailing how
to work with particular cache items.”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K3hj„  ubh¸)”}”(hŒThe operations are:”h]”hŒThe operations are:”…””}”(hj–  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K8hj„  ubj  )”}”(hXI  struct cache_head \*alloc(void)
  This simply allocates appropriate memory and returns
  a pointer to the cache_detail embedded within the
  structure

void cache_put(struct kref \*)
  This is called when the last reference to an item is
  dropped.  The pointer passed is to the 'ref' field
  in the cache_head.  cache_put should release any
  references create by 'cache_init' and, if CACHE_VALID
  is set, any references created by cache_update.
  It should then release the memory allocated by
  'alloc'.

int match(struct cache_head \*orig, struct cache_head \*new)
  test if the keys in the two structures match.  Return
  1 if they do, 0 if they don't.

void init(struct cache_head \*orig, struct cache_head \*new)
  Set the 'key' fields in 'new' from 'orig'.  This may
  include taking references to shared objects.

void update(struct cache_head \*orig, struct cache_head \*new)
  Set the 'content' fields in 'new' from 'orig'.

int cache_show(struct seq_file \*m, struct cache_detail \*cd, struct cache_head \*h)
  Optional.  Used to provide a /proc file that lists the
  contents of a cache.  This should show one item,
  usually on just one line.

int cache_request(struct cache_detail \*cd, struct cache_head \*h, char \*\*bpp, int \*blen)
  Format a request to be send to user-space for an item
  to be instantiated.  \*bpp is a buffer of size \*blen.
  bpp should be moved forward over the encoded message,
  and  \*blen should be reduced to show how much free
  space remains.  Return 0 on success or <0 if not
  enough room or other problem.

int cache_parse(struct cache_detail \*cd, char \*buf, int len)
  A message from user space has arrived to fill out a
  cache entry.  It is in 'buf' of length 'len'.
  cache_parse should parse this, find the item in the
  cache with sunrpc_cache_lookup_rcu, and update the item
  with sunrpc_cache_update.

”h]”hŒdefinition_list”“”)”}”(hhh]”(hŒdefinition_list_item”“”)”}”(hŒ‘struct cache_head \*alloc(void)
This simply allocates appropriate memory and returns
a pointer to the cache_detail embedded within the
structure
”h]”(hŒterm”“”)”}”(hŒstruct cache_head \*alloc(void)”h]”hŒstruct cache_head  *alloc(void)”…””}”(hjµ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j³  hŸh¶h K=hj¯  ubhŒ
definition”“”)”}”(hhh]”h¸)”}”(hŒpThis simply allocates appropriate memory and returns
a pointer to the cache_detail embedded within the
structure”h]”hŒpThis simply allocates appropriate memory and returns
a pointer to the cache_detail embedded within the
structure”…””}”(hjÈ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K;hjÅ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÃ  hj¯  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j­  hŸh¶h K=hjª  ubj®  )”}”(hXV  void cache_put(struct kref \*)
This is called when the last reference to an item is
dropped.  The pointer passed is to the 'ref' field
in the cache_head.  cache_put should release any
references create by 'cache_init' and, if CACHE_VALID
is set, any references created by cache_update.
It should then release the memory allocated by
'alloc'.
”h]”(j´  )”}”(hŒvoid cache_put(struct kref \*)”h]”hŒvoid cache_put(struct kref  *)”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j³  hŸh¶h KFhjâ  ubjÄ  )”}”(hhh]”h¸)”}”(hX6  This is called when the last reference to an item is
dropped.  The pointer passed is to the 'ref' field
in the cache_head.  cache_put should release any
references create by 'cache_init' and, if CACHE_VALID
is set, any references created by cache_update.
It should then release the memory allocated by
'alloc'.”h]”hXB  This is called when the last reference to an item is
dropped.  The pointer passed is to the â€˜refâ€™ field
in the cache_head.  cache_put should release any
references create by â€˜cache_initâ€™ and, if CACHE_VALID
is set, any references created by cache_update.
It should then release the memory allocated by
â€˜allocâ€™.”…””}”(hj÷  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K@hjô  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÃ  hjâ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j­  hŸh¶h KFhjª  ubj®  )”}”(hŒ’int match(struct cache_head \*orig, struct cache_head \*new)
test if the keys in the two structures match.  Return
1 if they do, 0 if they don't.
”h]”(j´  )”}”(hŒ<int match(struct cache_head \*orig, struct cache_head \*new)”h]”hŒ<int match(struct cache_head  *orig, struct cache_head  *new)”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j³  hŸh¶h KJhj  ubjÄ  )”}”(hhh]”h¸)”}”(hŒTtest if the keys in the two structures match.  Return
1 if they do, 0 if they don't.”h]”hŒVtest if the keys in the two structures match.  Return
1 if they do, 0 if they donâ€™t.”…””}”(hj&  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KIhj#  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÃ  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j­  hŸh¶h KJhjª  ubj®  )”}”(hŒŸvoid init(struct cache_head \*orig, struct cache_head \*new)
Set the 'key' fields in 'new' from 'orig'.  This may
include taking references to shared objects.
”h]”(j´  )”}”(hŒ<void init(struct cache_head \*orig, struct cache_head \*new)”h]”hŒ<void init(struct cache_head  *orig, struct cache_head  *new)”…””}”(hjD  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j³  hŸh¶h KNhj@  ubjÄ  )”}”(hhh]”h¸)”}”(hŒaSet the 'key' fields in 'new' from 'orig'.  This may
include taking references to shared objects.”h]”hŒmSet the â€˜keyâ€™ fields in â€˜newâ€™ from â€˜origâ€™.  This may
include taking references to shared objects.”…””}”(hjU  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KMhjR  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÃ  hj@  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j­  hŸh¶h KNhjª  ubj®  )”}”(hŒnvoid update(struct cache_head \*orig, struct cache_head \*new)
Set the 'content' fields in 'new' from 'orig'.
”h]”(j´  )”}”(hŒ>void update(struct cache_head \*orig, struct cache_head \*new)”h]”hŒ>void update(struct cache_head  *orig, struct cache_head  *new)”…””}”(hjs  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j³  hŸh¶h KQhjo  ubjÄ  )”}”(hhh]”h¸)”}”(hŒ.Set the 'content' fields in 'new' from 'orig'.”h]”hŒ:Set the â€˜contentâ€™ fields in â€˜newâ€™ from â€˜origâ€™.”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KQhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÃ  hjo  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j­  hŸh¶h KQhjª  ubj®  )”}”(hŒ×int cache_show(struct seq_file \*m, struct cache_detail \*cd, struct cache_head \*h)
Optional.  Used to provide a /proc file that lists the
contents of a cache.  This should show one item,
usually on just one line.
”h]”(j´  )”}”(hŒTint cache_show(struct seq_file \*m, struct cache_detail \*cd, struct cache_head \*h)”h]”hŒTint cache_show(struct seq_file  *m, struct cache_detail  *cd, struct cache_head  *h)”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j³  hŸh¶h KVhjž  ubjÄ  )”}”(hhh]”h¸)”}”(hŒOptional.  Used to provide a /proc file that lists the
contents of a cache.  This should show one item,
usually on just one line.”h]”hŒOptional.  Used to provide a /proc file that lists the
contents of a cache.  This should show one item,
usually on just one line.”…””}”(hj³  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KThj°  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÃ  hjž  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j­  hŸh¶h KVhjª  ubj®  )”}”(hXƒ  int cache_request(struct cache_detail \*cd, struct cache_head \*h, char \*\*bpp, int \*blen)
Format a request to be send to user-space for an item
to be instantiated.  \*bpp is a buffer of size \*blen.
bpp should be moved forward over the encoded message,
and  \*blen should be reduced to show how much free
space remains.  Return 0 on success or <0 if not
enough room or other problem.
”h]”(j´  )”}”(hŒ\int cache_request(struct cache_detail \*cd, struct cache_head \*h, char \*\*bpp, int \*blen)”h]”hŒ\int cache_request(struct cache_detail  *cd, struct cache_head  *h, char  * *bpp, int  *blen)”…””}”(hjÑ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j³  hŸh¶h K^hjÍ  ubjÄ  )”}”(hhh]”h¸)”}”(hX%  Format a request to be send to user-space for an item
to be instantiated.  \*bpp is a buffer of size \*blen.
bpp should be moved forward over the encoded message,
and  \*blen should be reduced to show how much free
space remains.  Return 0 on success or <0 if not
enough room or other problem.”h]”hX%  Format a request to be send to user-space for an item
to be instantiated.   *bpp is a buffer of size  *blen.
bpp should be moved forward over the encoded message,
and   *blen should be reduced to show how much free
space remains.  Return 0 on success or <0 if not
enough room or other problem.”…””}”(hjâ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KYhjß  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÃ  hjÍ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j­  hŸh¶h K^hjª  ubj®  )”}”(hX(  int cache_parse(struct cache_detail \*cd, char \*buf, int len)
A message from user space has arrived to fill out a
cache entry.  It is in 'buf' of length 'len'.
cache_parse should parse this, find the item in the
cache with sunrpc_cache_lookup_rcu, and update the item
with sunrpc_cache_update.

”h]”(j´  )”}”(hŒ>int cache_parse(struct cache_detail \*cd, char \*buf, int len)”h]”hŒ>int cache_parse(struct cache_detail  *cd, char  *buf, int len)”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j³  hŸh¶h Kfhjü  ubjÄ  )”}”(hhh]”h¸)”}”(hŒçA message from user space has arrived to fill out a
cache entry.  It is in 'buf' of length 'len'.
cache_parse should parse this, find the item in the
cache with sunrpc_cache_lookup_rcu, and update the item
with sunrpc_cache_update.”h]”hŒïA message from user space has arrived to fill out a
cache entry.  It is in â€˜bufâ€™ of length â€˜lenâ€™.
cache_parse should parse this, find the item in the
cache with sunrpc_cache_lookup_rcu, and update the item
with sunrpc_cache_update.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kahj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÃ  hjü  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j­  hŸh¶h Kfhjª  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¨  hj¤  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh¶h K:hj„  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hji  hžhhŸh¶h Nubj  )”}”(hŒ‘A cache needs to be registered using cache_register().  This
includes it on a list of caches that will be regularly
cleaned to discard old data.
”h]”h¸)”}”(hŒA cache needs to be registered using cache_register().  This
includes it on a list of caches that will be regularly
cleaned to discard old data.”h]”hŒA cache needs to be registered using cache_register().  This
includes it on a list of caches that will be regularly
cleaned to discard old data.”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khhj=  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hji  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”j‹  jŒ  uh1j  hŸh¶h K-hjX  hžhubeh}”(h]”Œcreating-a-cache”ah ]”h"]”Œcreating a cache”ah$]”h&]”uh1h¡hhÇhžhhŸh¶h K+ubh¢)”}”(hhh]”(h§)”}”(hŒUsing a cache”h]”hŒUsing a cache”…””}”(hjf  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjc  hžhhŸh¶h Kmubh¸)”}”(hX;  To find a value in a cache, call sunrpc_cache_lookup_rcu passing a pointer
to the cache_head in a sample item with the 'key' fields filled in.
This will be passed to ->match to identify the target entry.  If no
entry is found, a new entry will be create, added to the cache, and
marked as not containing valid data.”h]”hX?  To find a value in a cache, call sunrpc_cache_lookup_rcu passing a pointer
to the cache_head in a sample item with the â€˜keyâ€™ fields filled in.
This will be passed to ->match to identify the target entry.  If no
entry is found, a new entry will be create, added to the cache, and
marked as not containing valid data.”…””}”(hjt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kohjc  hžhubh¸)”}”(hX,  The item returned is typically passed to cache_check which will check
if the data is valid, and may initiate an up-call to get fresh data.
cache_check will return -ENOENT in the entry is negative or if an up
call is needed but not possible, -EAGAIN if an upcall is pending,
or 0 if the data is valid;”h]”hX,  The item returned is typically passed to cache_check which will check
if the data is valid, and may initiate an up-call to get fresh data.
cache_check will return -ENOENT in the entry is negative or if an up
call is needed but not possible, -EAGAIN if an upcall is pending,
or 0 if the data is valid;”…””}”(hj‚  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kuhjc  hžhubh¸)”}”(hXý  cache_check can be passed a "struct cache_req\*".  This structure is
typically embedded in the actual request and can be used to create a
deferred copy of the request (struct cache_deferred_req).  This is
done when the found cache item is not uptodate, but the is reason to
believe that userspace might provide information soon.  When the cache
item does become valid, the deferred copy of the request will be
revisited (->revisit).  It is expected that this method will
reschedule the request for processing.”h]”hX  cache_check can be passed a â€œstruct cache_req *â€.  This structure is
typically embedded in the actual request and can be used to create a
deferred copy of the request (struct cache_deferred_req).  This is
done when the found cache item is not uptodate, but the is reason to
believe that userspace might provide information soon.  When the cache
item does become valid, the deferred copy of the request will be
revisited (->revisit).  It is expected that this method will
reschedule the request for processing.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K{hjc  hžhubh¸)”}”(hXå  The value returned by sunrpc_cache_lookup_rcu can also be passed to
sunrpc_cache_update to set the content for the item.  A second item is
passed which should hold the content.  If the item found by _lookup
has valid data, then it is discarded and a new item is created.  This
saves any user of an item from worrying about content changing while
it is being inspected.  If the item found by _lookup does not contain
valid data, then the content is copied across and CACHE_VALID is set.”h]”hXå  The value returned by sunrpc_cache_lookup_rcu can also be passed to
sunrpc_cache_update to set the content for the item.  A second item is
passed which should hold the content.  If the item found by _lookup
has valid data, then it is discarded and a new item is created.  This
saves any user of an item from worrying about content changing while
it is being inspected.  If the item found by _lookup does not contain
valid data, then the content is copied across and CACHE_VALID is set.”…””}”(hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K„hjc  hžhubeh}”(h]”Œusing-a-cache”ah ]”h"]”Œusing a cache”ah$]”h&]”uh1h¡hhÇhžhhŸh¶h Kmubh¢)”}”(hhh]”(h§)”}”(hŒPopulating a cache”h]”hŒPopulating a cache”…””}”(hj·  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj´  hžhhŸh¶h Kubh¸)”}”(hŒoEach cache has a name, and when the cache is registered, a directory
with that name is created in /proc/net/rpc”h]”hŒoEach cache has a name, and when the cache is registered, a directory
with that name is created in /proc/net/rpc”…””}”(hjÅ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khj´  hžhubh¸)”}”(hŒÒThis directory contains a file called 'channel' which is a channel
for communicating between kernel and user for populating the cache.
This directory may later contain other files of interacting
with the cache.”h]”hŒÖThis directory contains a file called â€˜channelâ€™ which is a channel
for communicating between kernel and user for populating the cache.
This directory may later contain other files of interacting
with the cache.”…””}”(hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K’hj´  hžhubh¸)”}”(hŒíThe 'channel' works a bit like a datagram socket. Each 'write' is
passed as a whole to the cache for parsing and interpretation.
Each cache can treat the write requests differently, but it is
expected that a message written will contain:”h]”hŒõThe â€˜channelâ€™ works a bit like a datagram socket. Each â€˜writeâ€™ is
passed as a whole to the cache for parsing and interpretation.
Each cache can treat the write requests differently, but it is
expected that a message written will contain:”…””}”(hjá  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K—hj´  hžhubj  )”}”(hŒ&- a key
- an expiry time
- a content.
”h]”j	  )”}”(hhh]”(j  )”}”(hŒa key”h]”h¸)”}”(hjø  h]”hŒa key”…””}”(hjú  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kœhjö  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjó  ubj  )”}”(hŒan expiry time”h]”h¸)”}”(hj  h]”hŒan expiry time”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjó  ubj  )”}”(hŒa content.
”h]”h¸)”}”(hŒ
a content.”h]”hŒ
a content.”…””}”(hj(  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kžhj$  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjó  ubeh}”(h]”h ]”h"]”h$]”h&]”j‹  jŒ  uh1j  hŸh¶h Kœhjï  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh¶h Kœhj´  hžhubh¸)”}”(hŒ¥with the intention that an item in the cache with the give key
should be create or updated to have the given content, and the
expiry time should be set on that item.”h]”hŒ¥with the intention that an item in the cache with the give key
should be create or updated to have the given content, and the
expiry time should be set on that item.”…””}”(hjH  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K hj´  hžhubh¸)”}”(hŒûReading from a channel is a bit more interesting.  When a cache
lookup fails, or when it succeeds but finds an entry that may soon
expire, a request is lodged for that cache item to be updated by
user-space.  These requests appear in the channel file.”h]”hŒûReading from a channel is a bit more interesting.  When a cache
lookup fails, or when it succeeds but finds an entry that may soon
expire, a request is lodged for that cache item to be updated by
user-space.  These requests appear in the channel file.”…””}”(hjV  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K¤hj´  hžhubh¸)”}”(hŒÂSuccessive reads will return successive requests.
If there are no more requests to return, read will return EOF, but a
select or poll for read will block waiting for another request to be
added.”h]”hŒÂSuccessive reads will return successive requests.
If there are no more requests to return, read will return EOF, but a
select or poll for read will block waiting for another request to be
added.”…””}”(hjd  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K©hj´  hžhubh¸)”}”(hŒ'Thus a user-space helper is likely to::”h]”hŒ&Thus a user-space helper is likely to:”…””}”(hjr  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K®hj´  hžhubhŒliteral_block”“”)”}”(hŒQopen the channel.
  select for readable
  read a request
  write a response
loop.”h]”hŒQopen the channel.
  select for readable
  read a request
  write a response
loop.”…””}”hj‚  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1j€  hŸh¶h K°hj´  hžhubh¸)”}”(hŒ If it dies and needs to be restarted, any requests that have not been
answered will still appear in the file and will be read by the new
instance of the helper.”h]”hŒ If it dies and needs to be restarted, any requests that have not been
answered will still appear in the file and will be read by the new
instance of the helper.”…””}”(hj’  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K¶hj´  hžhubh¸)”}”(hŒ½Each cache should define a "cache_parse" method which takes a message
written from user-space and processes it.  It should return an error
(which propagates back to the write syscall) or 0.”h]”hŒÁEach cache should define a â€œcache_parseâ€ method which takes a message
written from user-space and processes it.  It should return an error
(which propagates back to the write syscall) or 0.”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kºhj´  hžhubh¸)”}”(hŒEach cache should also define a "cache_request" method which
takes a cache item and encodes a request into the buffer
provided.”h]”hŒƒEach cache should also define a â€œcache_requestâ€ method which
takes a cache item and encodes a request into the buffer
provided.”…””}”(hj®  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K¾hj´  hžhubhŒnote”“”)”}”(hXr  If a cache has no active readers on the channel, and has had not
active readers for more than 60 seconds, further requests will not be
added to the channel but instead all lookups that do not find a valid
entry will fail.  This is partly for backward compatibility: The
previous nfs exports table was deemed to be authoritative and a
failed lookup meant a definite 'no'.”h]”h¸)”}”(hXr  If a cache has no active readers on the channel, and has had not
active readers for more than 60 seconds, further requests will not be
added to the channel but instead all lookups that do not find a valid
entry will fail.  This is partly for backward compatibility: The
previous nfs exports table was deemed to be authoritative and a
failed lookup meant a definite 'no'.”h]”hXv  If a cache has no active readers on the channel, and has had not
active readers for more than 60 seconds, further requests will not be
added to the channel but instead all lookups that do not find a valid
entry will fail.  This is partly for backward compatibility: The
previous nfs exports table was deemed to be authoritative and a
failed lookup meant a definite â€˜noâ€™.”…””}”(hjÂ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÃhj¾  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¼  hj´  hžhhŸh¶h Nubeh}”(h]”Œpopulating-a-cache”ah ]”h"]”Œpopulating a cache”ah$]”h&]”uh1h¡hhÇhžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒrequest/response format”h]”hŒrequest/response format”…””}”(hjá  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÞ  hžhhŸh¶h KËubh¸)”}”(hXá  While each cache is free to use its own format for requests
and responses over channel, the following is recommended as
appropriate and support routines are available to help:
Each request or response record should be printable ASCII
with precisely one newline character which should be at the end.
Fields within the record should be separated by spaces, normally one.
If spaces, newlines, or nul characters are needed in a field they
much be quoted.  two mechanisms are available:”h]”hXá  While each cache is free to use its own format for requests
and responses over channel, the following is recommended as
appropriate and support routines are available to help:
Each request or response record should be printable ASCII
with precisely one newline character which should be at the end.
Fields within the record should be separated by spaces, normally one.
If spaces, newlines, or nul characters are needed in a field they
much be quoted.  two mechanisms are available:”…””}”(hjï  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÍhjÞ  hžhubj	  )”}”(hhh]”(j  )”}”(hŒƒIf a field begins '\x' then it must contain an even number of
hex digits, and pairs of these digits provide the bytes in the
field.”h]”h¸)”}”(hŒƒIf a field begins '\x' then it must contain an even number of
hex digits, and pairs of these digits provide the bytes in the
field.”h]”hŒ‡If a field begins â€˜ xâ€™ then it must contain an even number of
hex digits, and pairs of these digits provide the bytes in the
field.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÖhj   ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjý  hžhhŸh¶h Nubj  )”}”(hŒØotherwise a \ in the field must be followed by 3 octal digits
which give the code for a byte.  Other characters are treated
as them selves.  At the very least, space, newline, nul, and
'\' must be quoted in this way.”h]”h¸)”}”(hŒØotherwise a \ in the field must be followed by 3 octal digits
which give the code for a byte.  Other characters are treated
as them selves.  At the very least, space, newline, nul, and
'\' must be quoted in this way.”h]”hŒÚotherwise a   in the field must be followed by 3 octal digits
which give the code for a byte.  Other characters are treated
as them selves.  At the very least, space, newline, nul, and
â€˜ ' must be quoted in this way.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÙhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjý  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”j‹  jŒ  uh1j  hŸh¶h KÖhjÞ  hžhubeh}”(h]”Œrequest-response-format”ah ]”h"]”Œrequest/response format”ah$]”h&]”uh1h¡hhÇhžhhŸh¶h KËubeh}”(h]”Œcaches”ah ]”h"]”Œcaches”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K
ubeh}”(h]”Œ	rpc-cache”ah ]”h"]”Œ	rpc cache”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jq  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jK  jH  jC  j@  j`  j]  j±  j®  jÛ  jØ  j;  j8  uŒ	nametypes”}”(jK  ‰jC  ‰j`  ‰j±  ‰jÛ  ‰j;  ‰uh}”(jH  h£j@  hÇj]  jX  j®  jc  jØ  j´  j8  jÞ  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.