sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget3/translations/zh_CN/filesystems/caching/backend-apimodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/zh_TW/filesystems/caching/backend-apimodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/it_IT/filesystems/caching/backend-apimodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/ja_JP/filesystems/caching/backend-apimodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/ko_KR/filesystems/caching/backend-apimodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/pt_BR/filesystems/caching/backend-apimodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/sp_SP/filesystems/caching/backend-apimodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhM/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api.rsthKubhsection)}(hhh](htitle)}(hCache Backend APIh]hCache Backend API}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hThe FS-Cache system provides an API by which actual caches can be supplied to FS-Cache for it to then serve out to network filesystems and other interested parties. This API is used by::h]hThe FS-Cache system provides an API by which actual caches can be supplied to FS-Cache for it to then serve out to network filesystems and other interested parties. This API is used by:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh literal_block)}(h!#include .h]h!#include .}hhsbah}(h]h ]h"]h$]h&]hhuh1hhhhK hhhhubh)}(hhh](h)}(hOverviewh]hOverview}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hInteraction with the API is handled on three levels: cache, volume and data storage, and each level has its own type of cookie object:h]hInteraction with the API is handled on three levels: cache, volume and data storage, and each level has its own type of cookie object:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh block_quote)}(hX8======================= ======================= COOKIE C TYPE ======================= ======================= Cache cookie struct fscache_cache Volume cookie struct fscache_volume Data storage cookie struct fscache_cookie ======================= ======================= h]htable)}(hhh]htgroup)}(hhh](hcolspec)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1j,hj)ubj-)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1j,hj)ubhthead)}(hhh]hrow)}(hhh](hentry)}(hhh]h)}(hCOOKIEh]hCOOKIE}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjNubah}(h]h ]h"]h$]h&]uh1jLhjIubjM)}(hhh]h)}(hC TYPEh]hC TYPE}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjeubah}(h]h ]h"]h$]h&]uh1jLhjIubeh}(h]h ]h"]h$]h&]uh1jGhjDubah}(h]h ]h"]h$]h&]uh1jBhj)ubhtbody)}(hhh](jH)}(hhh](jM)}(hhh]h)}(h Cache cookieh]h Cache cookie}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jLhjubjM)}(hhh]h)}(hstruct fscache_cacheh]hstruct fscache_cache}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jLhjubeh}(h]h ]h"]h$]h&]uh1jGhjubjH)}(hhh](jM)}(hhh]h)}(h Volume cookieh]h Volume cookie}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jLhjubjM)}(hhh]h)}(hstruct fscache_volumeh]hstruct fscache_volume}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jLhjubeh}(h]h ]h"]h$]h&]uh1jGhjubjH)}(hhh](jM)}(hhh]h)}(hData storage cookieh]hData storage cookie}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jLhjubjM)}(hhh]h)}(hstruct fscache_cookieh]hstruct fscache_cookie}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jLhjubeh}(h]h ]h"]h$]h&]uh1jGhjubeh}(h]h ]h"]h$]h&]uh1jhj)ubeh}(h]h ]h"]h$]h&]colsKuh1j'hj$ubah}(h]h ]h"]h$]h&]uh1j"hjubah}(h]h ]h"]h$]h&]uh1jhhhKhhhhubh)}(hXCookies are used to provide some filesystem data to the cache, manage state and pin the cache during access in addition to acting as reference points for the API functions. Each cookie has a debugging ID that is included in trace points to make it easier to correlate traces. Note, though, that debugging IDs are simply allocated from incrementing counters and will eventually wrap.h]hXCookies are used to provide some filesystem data to the cache, manage state and pin the cache during access in addition to acting as reference points for the API functions. Each cookie has a debugging ID that is included in trace points to make it easier to correlate traces. Note, though, that debugging IDs are simply allocated from incrementing counters and will eventually wrap.}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hThe cache backend and the network filesystem can both ask for cache cookies - and if they ask for one of the same name, they'll get the same cookie. Volume and data cookies, however, are created at the behest of the filesystem only.h]hThe cache backend and the network filesystem can both ask for cache cookies - and if they ask for one of the same name, they’ll get the same cookie. Volume and data cookies, however, are created at the behest of the filesystem only.}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK"hhhhubeh}(h]overviewah ]h"]overviewah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Cache Cookiesh]h Cache Cookies}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjohhhhhK(ubh)}(hPCaches are represented in the API by cache cookies. These are objects of type::h]hOCaches are represented in the API by cache cookies. These are objects of type:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK*hjohhubh)}(hstruct fscache_cache { void *cache_priv; unsigned int debug_id; char *name; ... };h]hstruct fscache_cache { void *cache_priv; unsigned int debug_id; char *name; ... };}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhK-hjohhubh)}(hXUThere are a few fields that the cache backend might be interested in. The ``debug_id`` can be used in tracing to match lines referring to the same cache and ``name`` is the name the cache was registered with. The ``cache_priv`` member is private data provided by the cache when it is brought online. The other fields are for internal use.h](hKThere are a few fields that the cache backend might be interested in. The }(hjhhhNhNubhliteral)}(h ``debug_id``h]hdebug_id}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhG can be used in tracing to match lines referring to the same cache and }(hjhhhNhNubj)}(h``name``h]hname}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh1 is the name the cache was registered with. The }(hjhhhNhNubj)}(h``cache_priv``h]h cache_priv}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhp member is private data provided by the cache when it is brought online. The other fields are for internal use.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK4hjohhubeh}(h] cache-cookiesah ]h"] cache cookiesah$]h&]uh1hhhhhhhhK(ubh)}(hhh](h)}(hRegistering a Cacheh]hRegistering a Cache}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKhjhhubh)}(h>struct fscache_cache *fscache_acquire_cache(const char *name);h]h>struct fscache_cache *fscache_acquire_cache(const char *name);}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhKAhjhhubh)}(hX=This will look up and potentially create a cache cookie. The cache cookie may have already been created by a network filesystem looking for it, in which case that cache cookie will be used. If the cache cookie is not in use by another cache, it will be moved into the preparing state, otherwise it will return busy.h]hX=This will look up and potentially create a cache cookie. The cache cookie may have already been created by a network filesystem looking for it, in which case that cache cookie will be used. If the cache cookie is not in use by another cache, it will be moved into the preparing state, otherwise it will return busy.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKChjhhubh)}(hIf successful, the cache backend can then start setting up the cache. In the event that the initialisation fails, the cache backend should call::h]hIf successful, the cache backend can then start setting up the cache. In the event that the initialisation fails, the cache backend should call:}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKIhjhhubh)}(h;void fscache_relinquish_cache(struct fscache_cache *cache);h]h;void fscache_relinquish_cache(struct fscache_cache *cache);}hj3sbah}(h]h ]h"]h$]h&]hhuh1hhhhKLhjhhubh)}(h to reset and discard the cookie.h]h to reset and discard the cookie.}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKNhjhhubeh}(h]registering-a-cacheah ]h"]registering a cacheah$]h&]uh1hhhhhhhhKOnce the cache is set up, it can be brought online by calling:}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKThjWhhubh)}(hint fscache_add_cache(struct fscache_cache *cache, const struct fscache_cache_ops *ops, void *cache_priv);h]hint fscache_add_cache(struct fscache_cache *cache, const struct fscache_cache_ops *ops, void *cache_priv);}hjvsbah}(h]h ]h"]h$]h&]hhuh1hhhhKVhjWhhubh)}(hThis stores the cache operations table pointer and cache private data into the cache cookie and moves the cache to the active state, thereby allowing accesses to take place.h]hThis stores the cache operations table pointer and cache private data into the cache cookie and moves the cache to the active state, thereby allowing accesses to take place.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKZhjWhhubeh}(h]bringing-a-cache-onlineah ]h"]bringing a cache onlineah$]h&]uh1hhhhhhhhKRubh)}(hhh](h)}(h Withdrawing a Cache From Serviceh]h Withdrawing a Cache From Service}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK`ubh)}(hNThe cache backend can withdraw a cache from service by calling this function::h]hMThe cache backend can withdraw a cache from service by calling this function:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKbhjhhubh)}(h9void fscache_withdraw_cache(struct fscache_cache *cache);h]h9void fscache_withdraw_cache(struct fscache_cache *cache);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKdhjhhubh)}(hThis moves the cache to the withdrawn state to prevent new cache- and volume-level accesses from starting and then waits for outstanding cache-level accesses to complete.h]hThis moves the cache to the withdrawn state to prevent new cache- and volume-level accesses from starting and then waits for outstanding cache-level accesses to complete.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKfhjhhubh)}(hkThe cache must then go through the data storage objects it has and tell fscache to withdraw them, calling::h]hjThe cache must then go through the data storage objects it has and tell fscache to withdraw them, calling:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjhhubh)}(h``cache_priv`` - A place for the cache to stash private data. h]h)}(h=``cache_priv`` - A place for the cache to stash private data.h](j)}(h``cache_priv``h]h cache_priv}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh/ - A place for the cache to stash private data.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h:``debug_id`` - A debugging ID for logging in tracepoints. h]h)}(h9``debug_id`` - A debugging ID for logging in tracepoints.h](j)}(h ``debug_id``h]hdebug_id}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh- - A debugging ID for logging in tracepoints.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h``key`` - A printable string with no '/' characters in it that represents the index key for the volume. The key is NUL-terminated and padded out to a multiple of 4 bytes. h]h)}(h``key`` - A printable string with no '/' characters in it that represents the index key for the volume. The key is NUL-terminated and padded out to a multiple of 4 bytes.h](j)}(h``key``h]hkey}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj%ubh - A printable string with no ‘/’ characters in it that represents the index key for the volume. The key is NUL-terminated and padded out to a multiple of 4 bytes.}(hj%hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj!ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(ho``key_hash`` - A hash of the index key. This should work out the same, no matter the cpu arch and endianness. h]h)}(hn``key_hash`` - A hash of the index key. This should work out the same, no matter the cpu arch and endianness.h](j)}(h ``key_hash``h]hkey_hash}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjKubhb - A hash of the index key. This should work out the same, no matter the cpu arch and endianness.}(hjKhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjGubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hk``coherency`` - A piece of coherency data that should be checked when the volume is bound to in the cache. h]h)}(hj``coherency`` - A piece of coherency data that should be checked when the volume is bound to in the cache.h](j)}(h ``coherency``h]h coherency}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjqubh] - A piece of coherency data that should be checked when the volume is bound to in the cache.}(hjqhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjmubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hA``coherency_len`` - The amount of data in the coherency buffer. h]h)}(h?``coherency_len`` - The amount of data in the coherency buffer.h](j)}(h``coherency_len``h]h coherency_len}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh. - The amount of data in the coherency buffer.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]bullet*uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjihhubeh}(h]volume-cookiesah ]h"]volume cookiesah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hData Storage Cookiesh]hData Storage Cookies}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hA volume is a logical group of data storage objects, each of which is represented to the network filesystem by a cookie. Cookies are represented in the API as objects of type::h]hA volume is a logical group of data storage objects, each of which is represented to the network filesystem by a cookie. Cookies are represented in the API as objects of type:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXstruct fscache_cookie { struct fscache_volume *volume; void *cache_priv; unsigned long flags; unsigned int debug_id; unsigned int inval_counter; loff_t object_size; u8 advice; u32 key_hash; u8 key_len; u8 aux_len; ... };h]hXstruct fscache_cookie { struct fscache_volume *volume; void *cache_priv; unsigned long flags; unsigned int debug_id; unsigned int inval_counter; loff_t object_size; u8 advice; u32 key_hash; u8 key_len; u8 aux_len; ... };}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubh)}(hGThe fields in the cookie that are of interest to the cache backend are:h]hGThe fields in the cookie that are of interest to the cache backend are:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hX* ``volume`` - The parent volume cookie. * ``cache_priv`` - A place for the cache to stash private data. * ``flags`` - A collection of bit flags, including: * FSCACHE_COOKIE_NO_DATA_TO_READ - There is no data available in the cache to be read as the cookie has been created or invalidated. * FSCACHE_COOKIE_NEEDS_UPDATE - The coherency data and/or object size has been changed and needs committing. * FSCACHE_COOKIE_LOCAL_WRITE - The netfs's data has been modified locally, so the cache object may be in an incoherent state with respect to the server. * FSCACHE_COOKIE_HAVE_DATA - The backend should set this if it successfully stores data into the cache. * FSCACHE_COOKIE_RETIRED - The cookie was invalidated when it was relinquished and the cached data should be discarded. * ``debug_id`` - A debugging ID for logging in tracepoints. * ``inval_counter`` - The number of invalidations done on the cookie. * ``advice`` - Information about how the cookie is to be used. * ``key_hash`` - A hash of the index key. This should work out the same, no matter the cpu arch and endianness. * ``key_len`` - The length of the index key. * ``aux_len`` - The length of the coherency data buffer. h]j)}(hhh](j)}(h'``volume`` - The parent volume cookie. h]h)}(h&``volume`` - The parent volume cookie.h](j)}(h ``volume``h]hvolume}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh - The parent volume cookie.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h>``cache_priv`` - A place for the cache to stash private data. h]h)}(h=``cache_priv`` - A place for the cache to stash private data.h](j)}(h``cache_priv``h]h cache_priv}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj;ubh/ - A place for the cache to stash private data.}(hj;hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj7ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hX``flags`` - A collection of bit flags, including: * FSCACHE_COOKIE_NO_DATA_TO_READ - There is no data available in the cache to be read as the cookie has been created or invalidated. * FSCACHE_COOKIE_NEEDS_UPDATE - The coherency data and/or object size has been changed and needs committing. * FSCACHE_COOKIE_LOCAL_WRITE - The netfs's data has been modified locally, so the cache object may be in an incoherent state with respect to the server. * FSCACHE_COOKIE_HAVE_DATA - The backend should set this if it successfully stores data into the cache. * FSCACHE_COOKIE_RETIRED - The cookie was invalidated when it was relinquished and the cached data should be discarded. h](h)}(h1``flags`` - A collection of bit flags, including:h](j)}(h ``flags``h]hflags}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1jhjaubh( - A collection of bit flags, including:}(hjahhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj]ubj)}(hX{* FSCACHE_COOKIE_NO_DATA_TO_READ - There is no data available in the cache to be read as the cookie has been created or invalidated. * FSCACHE_COOKIE_NEEDS_UPDATE - The coherency data and/or object size has been changed and needs committing. * FSCACHE_COOKIE_LOCAL_WRITE - The netfs's data has been modified locally, so the cache object may be in an incoherent state with respect to the server. * FSCACHE_COOKIE_HAVE_DATA - The backend should set this if it successfully stores data into the cache. * FSCACHE_COOKIE_RETIRED - The cookie was invalidated when it was relinquished and the cached data should be discarded. h]j)}(hhh](j)}(hFSCACHE_COOKIE_NO_DATA_TO_READ - There is no data available in the cache to be read as the cookie has been created or invalidated. h]h)}(hFSCACHE_COOKIE_NO_DATA_TO_READ - There is no data available in the cache to be read as the cookie has been created or invalidated.h]hFSCACHE_COOKIE_NO_DATA_TO_READ - There is no data available in the cache to be read as the cookie has been created or invalidated.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hkFSCACHE_COOKIE_NEEDS_UPDATE - The coherency data and/or object size has been changed and needs committing. h]h)}(hjFSCACHE_COOKIE_NEEDS_UPDATE - The coherency data and/or object size has been changed and needs committing.h]hjFSCACHE_COOKIE_NEEDS_UPDATE - The coherency data and/or object size has been changed and needs committing.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hFSCACHE_COOKIE_LOCAL_WRITE - The netfs's data has been modified locally, so the cache object may be in an incoherent state with respect to the server. h]h)}(hFSCACHE_COOKIE_LOCAL_WRITE - The netfs's data has been modified locally, so the cache object may be in an incoherent state with respect to the server.h]hFSCACHE_COOKIE_LOCAL_WRITE - The netfs’s data has been modified locally, so the cache object may be in an incoherent state with respect to the server.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hfFSCACHE_COOKIE_HAVE_DATA - The backend should set this if it successfully stores data into the cache. h]h)}(heFSCACHE_COOKIE_HAVE_DATA - The backend should set this if it successfully stores data into the cache.h]heFSCACHE_COOKIE_HAVE_DATA - The backend should set this if it successfully stores data into the cache.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hvFSCACHE_COOKIE_RETIRED - The cookie was invalidated when it was relinquished and the cached data should be discarded. h]h)}(huFSCACHE_COOKIE_RETIRED - The cookie was invalidated when it was relinquished and the cached data should be discarded.h]huFSCACHE_COOKIE_RETIRED - The cookie was invalidated when it was relinquished and the cached data should be discarded.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhj}ubah}(h]h ]h"]h$]h&]uh1jhhhKhj]ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(h:``debug_id`` - A debugging ID for logging in tracepoints. h]h)}(h9``debug_id`` - A debugging ID for logging in tracepoints.h](j)}(h ``debug_id``h]hdebug_id}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh- - A debugging ID for logging in tracepoints.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hD``inval_counter`` - The number of invalidations done on the cookie. h]h)}(hC``inval_counter`` - The number of invalidations done on the cookie.h](j)}(h``inval_counter``h]h inval_counter}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8ubh2 - The number of invalidations done on the cookie.}(hj8hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj4ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h=``advice`` - Information about how the cookie is to be used. h]h)}(h<``advice`` - Information about how the cookie is to be used.h](j)}(h ``advice``h]hadvice}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj^ubh2 - Information about how the cookie is to be used.}(hj^hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjZubah}(h]h ]h"]h$]h&]uh1jhjubj)}(ho``key_hash`` - A hash of the index key. This should work out the same, no matter the cpu arch and endianness. h]h)}(hn``key_hash`` - A hash of the index key. This should work out the same, no matter the cpu arch and endianness.h](j)}(h ``key_hash``h]hkey_hash}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhb - A hash of the index key. This should work out the same, no matter the cpu arch and endianness.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h+``key_len`` - The length of the index key. h]h)}(h*``key_len`` - The length of the index key.h](j)}(h ``key_len``h]hkey_len}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh - The length of the index key.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h7``aux_len`` - The length of the coherency data buffer. h]h)}(h6``aux_len`` - The length of the coherency data buffer.h](j)}(h ``aux_len``h]haux_len}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh+ - The length of the coherency data buffer.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubh)}(hEach cookie has an index key, which may be stored inline to the cookie or elsewhere. A pointer to this can be obtained by calling::h]hEach cookie has an index key, which may be stored inline to the cookie or elsewhere. A pointer to this can be obtained by calling:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h5void *fscache_get_key(struct fscache_cookie *cookie);h]h5void *fscache_get_key(struct fscache_cookie *cookie);}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubh)}(h]The index key is a binary blob, the storage for which is padded out to a multiple of 4 bytes.h]h]The index key is a binary blob, the storage for which is padded out to a multiple of 4 bytes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hEach cookie also has a buffer for coherency data. This may also be inline or detached from the cookie and a pointer is obtained by calling::h]hEach cookie also has a buffer for coherency data. This may also be inline or detached from the cookie and a pointer is obtained by calling:}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h5void *fscache_get_aux(struct fscache_cookie *cookie);h]h5void *fscache_get_aux(struct fscache_cookie *cookie);}hj6sbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubeh}(h]data-storage-cookiesah ]h"]data storage cookiesah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hCookie Accountingh]hCookie Accounting}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjLhhhhhKubh)}(hData storage cookies are counted and this is used to block cache withdrawal completion until all objects have been destroyed. The following functions are provided to the cache to deal with that::h]hData storage cookies are counted and this is used to block cache withdrawal completion until all objects have been destroyed. The following functions are provided to the cache to deal with that:}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjLhhubh)}(hvoid fscache_count_object(struct fscache_cache *cache); void fscache_uncount_object(struct fscache_cache *cache); void fscache_wait_for_objects(struct fscache_cache *cache);h]hvoid fscache_count_object(struct fscache_cache *cache); void fscache_uncount_object(struct fscache_cache *cache); void fscache_wait_for_objects(struct fscache_cache *cache);}hjksbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjLhhubh)}(hThe count function records the allocation of an object in a cache and the uncount function records its destruction. Warning: by the time the uncount function returns, the cache may have been destroyed.h]hThe count function records the allocation of an object in a cache and the uncount function records its destruction. Warning: by the time the uncount function returns, the cache may have been destroyed.}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjLhhubh)}(hThe wait function can be used during the withdrawal procedure to wait for fscache to finish withdrawing all the objects in the cache. When it completes, there will be no remaining objects referring to the cache object or any volume objects.h]hThe wait function can be used during the withdrawal procedure to wait for fscache to finish withdrawing all the objects in the cache. When it completes, there will be no remaining objects referring to the cache object or any volume objects.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjLhhubeh}(h]cookie-accountingah ]h"]cookie accountingah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hCache Management APIh]hCache Management API}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM ubh)}(hThe cache backend implements the cache management API by providing a table of operations that fscache can use to manage various aspects of the cache. These are held in a structure of type::h]hThe cache backend implements the cache management API by providing a table of operations that fscache can use to manage various aspects of the cache. These are held in a structure of type:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hCstruct fscache_cache_ops { const char *name; ... };h]hCstruct fscache_cache_ops { const char *name; ... };}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhMhjhhubh)}(hThis contains a printable name for the cache backend driver plus a number of pointers to methods to allow fscache to request management of the cache:h]hThis contains a printable name for the cache backend driver plus a number of pointers to methods to allow fscache to request management of the cache:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hX&* Set up a volume cookie [optional]:: void (*acquire_volume)(struct fscache_volume *volume); This method is called when a volume cookie is being created. The caller holds a cache-level access pin to prevent the cache from going away for the duration. This method should set up the resources to access a volume in the cache and should not return until it has done so. If successful, it can set ``cache_priv`` to its own data. * Clean up volume cookie [optional]:: void (*free_volume)(struct fscache_volume *volume); This method is called when a volume cookie is being released if ``cache_priv`` is set. * Look up a cookie in the cache [mandatory]:: bool (*lookup_cookie)(struct fscache_cookie *cookie); This method is called to look up/create the resources needed to access the data storage for a cookie. It is called from a worker thread with a volume-level access pin in the cache to prevent it from being withdrawn. True should be returned if successful and false otherwise. If false is returned, the withdraw_cookie op (see below) will be called. If lookup fails, but the object could still be created (e.g. it hasn't been cached before), then:: void fscache_cookie_lookup_negative( struct fscache_cookie *cookie); can be called to let the network filesystem proceed and start downloading stuff whilst the cache backend gets on with the job of creating things. If successful, ``cookie->cache_priv`` can be set. * Withdraw an object without any cookie access counts held [mandatory]:: void (*withdraw_cookie)(struct fscache_cookie *cookie); This method is called to withdraw a cookie from service. It will be called when the cookie is relinquished by the netfs, withdrawn or culled by the cache backend or closed after a period of non-use by fscache. The caller doesn't hold any access pins, but it is called from a non-reentrant work item to manage races between the various ways withdrawal can occur. The cookie will have the ``FSCACHE_COOKIE_RETIRED`` flag set on it if the associated data is to be removed from the cache. * Change the size of a data storage object [mandatory]:: void (*resize_cookie)(struct netfs_cache_resources *cres, loff_t new_size); This method is called to inform the cache backend of a change in size of the netfs file due to local truncation. The cache backend should make all of the changes it needs to make before returning as this is done under the netfs inode mutex. The caller holds a cookie-level access pin to prevent a race with withdrawal and the netfs must have the cookie marked in-use to prevent garbage collection or culling from removing any resources. * Invalidate a data storage object [mandatory]:: bool (*invalidate_cookie)(struct fscache_cookie *cookie); This is called when the network filesystem detects a third-party modification or when an O_DIRECT write is made locally. This requests that the cache backend should throw away all the data in the cache for this object and start afresh. It should return true if successful and false otherwise. On entry, new I O/operations are blocked. Once the cache is in a position to accept I/O again, the backend should release the block by calling:: void fscache_resume_after_invalidation(struct fscache_cookie *cookie); If the method returns false, caching will be withdrawn for this cookie. * Prepare to make local modifications to the cache [mandatory]:: void (*prepare_to_write)(struct fscache_cookie *cookie); This method is called when the network filesystem finds that it is going to need to modify the contents of the cache due to local writes or truncations. This gives the cache a chance to note that a cache object may be incoherent with respect to the server and may need writing back later. This may also cause the cached data to be scrapped on later rebinding if not properly committed. * Begin an operation for the netfs lib [mandatory]:: bool (*begin_operation)(struct netfs_cache_resources *cres, enum fscache_want_state want_state); This method is called when an I/O operation is being set up (read, write or resize). The caller holds an access pin on the cookie and must have marked the cookie as in-use. If it can, the backend should attach any resources it needs to keep around to the netfs_cache_resources object and return true. If it can't complete the setup, it should return false. The want_state parameter indicates the state the caller needs the cache object to be in and what it wants to do during the operation: * ``FSCACHE_WANT_PARAMS`` - The caller just wants to access cache object parameters; it doesn't need to do data I/O yet. * ``FSCACHE_WANT_READ`` - The caller wants to read data. * ``FSCACHE_WANT_WRITE`` - The caller wants to write to or resize the cache object. Note that there won't necessarily be anything attached to the cookie's cache_priv yet if the cookie is still being created. h]j)}(hhh](j)}(hXSet up a volume cookie [optional]:: void (*acquire_volume)(struct fscache_volume *volume); This method is called when a volume cookie is being created. The caller holds a cache-level access pin to prevent the cache from going away for the duration. This method should set up the resources to access a volume in the cache and should not return until it has done so. If successful, it can set ``cache_priv`` to its own data. h](h)}(h#Set up a volume cookie [optional]::h]h"Set up a volume cookie [optional]:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(h6void (*acquire_volume)(struct fscache_volume *volume);h]h6void (*acquire_volume)(struct fscache_volume *volume);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhMhjubh)}(hXThis method is called when a volume cookie is being created. The caller holds a cache-level access pin to prevent the cache from going away for the duration. This method should set up the resources to access a volume in the cache and should not return until it has done so.h]hXThis method is called when a volume cookie is being created. The caller holds a cache-level access pin to prevent the cache from going away for the duration. This method should set up the resources to access a volume in the cache and should not return until it has done so.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(h9If successful, it can set ``cache_priv`` to its own data.h](hIf successful, it can set }(hj hhhNhNubj)}(h``cache_priv``h]h cache_priv}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh to its own data.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM!hjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hClean up volume cookie [optional]:: void (*free_volume)(struct fscache_volume *volume); This method is called when a volume cookie is being released if ``cache_priv`` is set. h](h)}(h#Clean up volume cookie [optional]::h]h"Clean up volume cookie [optional]:}(hj7 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM$hj3 ubh)}(h3void (*free_volume)(struct fscache_volume *volume);h]h3void (*free_volume)(struct fscache_volume *volume);}hjE sbah}(h]h ]h"]h$]h&]hhuh1hhhhM&hj3 ubh)}(hVThis method is called when a volume cookie is being released if ``cache_priv`` is set.h](h@This method is called when a volume cookie is being released if }(hjS hhhNhNubj)}(h``cache_priv``h]h cache_priv}(hj[ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjS ubh is set.}(hjS hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM(hj3 ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hXULook up a cookie in the cache [mandatory]:: bool (*lookup_cookie)(struct fscache_cookie *cookie); This method is called to look up/create the resources needed to access the data storage for a cookie. It is called from a worker thread with a volume-level access pin in the cache to prevent it from being withdrawn. True should be returned if successful and false otherwise. If false is returned, the withdraw_cookie op (see below) will be called. If lookup fails, but the object could still be created (e.g. it hasn't been cached before), then:: void fscache_cookie_lookup_negative( struct fscache_cookie *cookie); can be called to let the network filesystem proceed and start downloading stuff whilst the cache backend gets on with the job of creating things. If successful, ``cookie->cache_priv`` can be set. h](h)}(h+Look up a cookie in the cache [mandatory]::h]h*Look up a cookie in the cache [mandatory]:}(hj} hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hjy ubh)}(h5bool (*lookup_cookie)(struct fscache_cookie *cookie);h]h5bool (*lookup_cookie)(struct fscache_cookie *cookie);}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhM.hjy ubh)}(hThis method is called to look up/create the resources needed to access the data storage for a cookie. It is called from a worker thread with a volume-level access pin in the cache to prevent it from being withdrawn.h]hThis method is called to look up/create the resources needed to access the data storage for a cookie. It is called from a worker thread with a volume-level access pin in the cache to prevent it from being withdrawn.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM0hjy ubh)}(hTrue should be returned if successful and false otherwise. If false is returned, the withdraw_cookie op (see below) will be called.h]hTrue should be returned if successful and false otherwise. If false is returned, the withdraw_cookie op (see below) will be called.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM4hjy ubh)}(hbIf lookup fails, but the object could still be created (e.g. it hasn't been cached before), then::h]hcIf lookup fails, but the object could still be created (e.g. it hasn’t been cached before), then:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM7hjy ubh)}(hLvoid fscache_cookie_lookup_negative( struct fscache_cookie *cookie);h]hLvoid fscache_cookie_lookup_negative( struct fscache_cookie *cookie);}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhM:hjy ubh)}(hcan be called to let the network filesystem proceed and start downloading stuff whilst the cache backend gets on with the job of creating things.h]hcan be called to let the network filesystem proceed and start downloading stuff whilst the cache backend gets on with the job of creating things.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM=hjy ubh)}(h1If successful, ``cookie->cache_priv`` can be set.h](hIf successful, }(hj hhhNhNubj)}(h``cookie->cache_priv``h]hcookie->cache_priv}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh can be set.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM@hjy ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hXmWithdraw an object without any cookie access counts held [mandatory]:: void (*withdraw_cookie)(struct fscache_cookie *cookie); This method is called to withdraw a cookie from service. It will be called when the cookie is relinquished by the netfs, withdrawn or culled by the cache backend or closed after a period of non-use by fscache. The caller doesn't hold any access pins, but it is called from a non-reentrant work item to manage races between the various ways withdrawal can occur. The cookie will have the ``FSCACHE_COOKIE_RETIRED`` flag set on it if the associated data is to be removed from the cache. h](h)}(hFWithdraw an object without any cookie access counts held [mandatory]::h]hEWithdraw an object without any cookie access counts held [mandatory]:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMChj ubh)}(h7void (*withdraw_cookie)(struct fscache_cookie *cookie);h]h7void (*withdraw_cookie)(struct fscache_cookie *cookie);}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhMEhj ubh)}(hThis method is called to withdraw a cookie from service. It will be called when the cookie is relinquished by the netfs, withdrawn or culled by the cache backend or closed after a period of non-use by fscache.h]hThis method is called to withdraw a cookie from service. It will be called when the cookie is relinquished by the netfs, withdrawn or culled by the cache backend or closed after a period of non-use by fscache.}(hj% hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMGhj ubh)}(hThe caller doesn't hold any access pins, but it is called from a non-reentrant work item to manage races between the various ways withdrawal can occur.h]hThe caller doesn’t hold any access pins, but it is called from a non-reentrant work item to manage races between the various ways withdrawal can occur.}(hj3 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhj ubh)}(hzThe cookie will have the ``FSCACHE_COOKIE_RETIRED`` flag set on it if the associated data is to be removed from the cache.h](hThe cookie will have the }(hjA hhhNhNubj)}(h``FSCACHE_COOKIE_RETIRED``h]hFSCACHE_COOKIE_RETIRED}(hjI hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjA ubhG flag set on it if the associated data is to be removed from the cache.}(hjA hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMOhj ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hXYChange the size of a data storage object [mandatory]:: void (*resize_cookie)(struct netfs_cache_resources *cres, loff_t new_size); This method is called to inform the cache backend of a change in size of the netfs file due to local truncation. The cache backend should make all of the changes it needs to make before returning as this is done under the netfs inode mutex. The caller holds a cookie-level access pin to prevent a race with withdrawal and the netfs must have the cookie marked in-use to prevent garbage collection or culling from removing any resources. h](h)}(h6Change the size of a data storage object [mandatory]::h]h5Change the size of a data storage object [mandatory]:}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMShjg ubh)}(havoid (*resize_cookie)(struct netfs_cache_resources *cres, loff_t new_size);h]havoid (*resize_cookie)(struct netfs_cache_resources *cres, loff_t new_size);}hjy sbah}(h]h ]h"]h$]h&]hhuh1hhhhMUhjg ubh)}(hThis method is called to inform the cache backend of a change in size of the netfs file due to local truncation. The cache backend should make all of the changes it needs to make before returning as this is done under the netfs inode mutex.h]hThis method is called to inform the cache backend of a change in size of the netfs file due to local truncation. The cache backend should make all of the changes it needs to make before returning as this is done under the netfs inode mutex.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMXhjg ubh)}(hThe caller holds a cookie-level access pin to prevent a race with withdrawal and the netfs must have the cookie marked in-use to prevent garbage collection or culling from removing any resources.h]hThe caller holds a cookie-level access pin to prevent a race with withdrawal and the netfs must have the cookie marked in-use to prevent garbage collection or culling from removing any resources.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM]hjg ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hXInvalidate a data storage object [mandatory]:: bool (*invalidate_cookie)(struct fscache_cookie *cookie); This is called when the network filesystem detects a third-party modification or when an O_DIRECT write is made locally. This requests that the cache backend should throw away all the data in the cache for this object and start afresh. It should return true if successful and false otherwise. On entry, new I O/operations are blocked. Once the cache is in a position to accept I/O again, the backend should release the block by calling:: void fscache_resume_after_invalidation(struct fscache_cookie *cookie); If the method returns false, caching will be withdrawn for this cookie. h](h)}(h.Invalidate a data storage object [mandatory]::h]h-Invalidate a data storage object [mandatory]:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMbhj ubh)}(h9bool (*invalidate_cookie)(struct fscache_cookie *cookie);h]h9bool (*invalidate_cookie)(struct fscache_cookie *cookie);}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhMdhj ubh)}(hX&This is called when the network filesystem detects a third-party modification or when an O_DIRECT write is made locally. This requests that the cache backend should throw away all the data in the cache for this object and start afresh. It should return true if successful and false otherwise.h]hX&This is called when the network filesystem detects a third-party modification or when an O_DIRECT write is made locally. This requests that the cache backend should throw away all the data in the cache for this object and start afresh. It should return true if successful and false otherwise.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMfhj ubh)}(hOn entry, new I O/operations are blocked. Once the cache is in a position to accept I/O again, the backend should release the block by calling::h]hOn entry, new I O/operations are blocked. Once the cache is in a position to accept I/O again, the backend should release the block by calling:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMlhj ubh)}(hFvoid fscache_resume_after_invalidation(struct fscache_cookie *cookie);h]hFvoid fscache_resume_after_invalidation(struct fscache_cookie *cookie);}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhMohj ubh)}(hGIf the method returns false, caching will be withdrawn for this cookie.h]hGIf the method returns false, caching will be withdrawn for this cookie.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMqhj ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hXPrepare to make local modifications to the cache [mandatory]:: void (*prepare_to_write)(struct fscache_cookie *cookie); This method is called when the network filesystem finds that it is going to need to modify the contents of the cache due to local writes or truncations. This gives the cache a chance to note that a cache object may be incoherent with respect to the server and may need writing back later. This may also cause the cached data to be scrapped on later rebinding if not properly committed. h](h)}(h>Prepare to make local modifications to the cache [mandatory]::h]h=Prepare to make local modifications to the cache [mandatory]:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMthj ubh)}(h8void (*prepare_to_write)(struct fscache_cookie *cookie);h]h8void (*prepare_to_write)(struct fscache_cookie *cookie);}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhMvhj ubh)}(hXThis method is called when the network filesystem finds that it is going to need to modify the contents of the cache due to local writes or truncations. This gives the cache a chance to note that a cache object may be incoherent with respect to the server and may need writing back later. This may also cause the cached data to be scrapped on later rebinding if not properly committed.h]hXThis method is called when the network filesystem finds that it is going to need to modify the contents of the cache due to local writes or truncations. This gives the cache a chance to note that a cache object may be incoherent with respect to the server and may need writing back later. This may also cause the cached data to be scrapped on later rebinding if not properly committed.}(hj' hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMxhj ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hX=Begin an operation for the netfs lib [mandatory]:: bool (*begin_operation)(struct netfs_cache_resources *cres, enum fscache_want_state want_state); This method is called when an I/O operation is being set up (read, write or resize). The caller holds an access pin on the cookie and must have marked the cookie as in-use. If it can, the backend should attach any resources it needs to keep around to the netfs_cache_resources object and return true. If it can't complete the setup, it should return false. The want_state parameter indicates the state the caller needs the cache object to be in and what it wants to do during the operation: * ``FSCACHE_WANT_PARAMS`` - The caller just wants to access cache object parameters; it doesn't need to do data I/O yet. * ``FSCACHE_WANT_READ`` - The caller wants to read data. * ``FSCACHE_WANT_WRITE`` - The caller wants to write to or resize the cache object. Note that there won't necessarily be anything attached to the cookie's cache_priv yet if the cookie is still being created. h](h)}(h2Begin an operation for the netfs lib [mandatory]::h]h1Begin an operation for the netfs lib [mandatory]:}(hj? hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj; ubh)}(hxbool (*begin_operation)(struct netfs_cache_resources *cres, enum fscache_want_state want_state);h]hxbool (*begin_operation)(struct netfs_cache_resources *cres, enum fscache_want_state want_state);}hjM sbah}(h]h ]h"]h$]h&]hhuh1hhhhMhj; ubh)}(hThis method is called when an I/O operation is being set up (read, write or resize). The caller holds an access pin on the cookie and must have marked the cookie as in-use.h]hThis method is called when an I/O operation is being set up (read, write or resize). The caller holds an access pin on the cookie and must have marked the cookie as in-use.}(hj[ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj; ubh)}(hIf it can, the backend should attach any resources it needs to keep around to the netfs_cache_resources object and return true.h]hIf it can, the backend should attach any resources it needs to keep around to the netfs_cache_resources object and return true.}(hji hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj; ubh)}(h7If it can't complete the setup, it should return false.h]h9If it can’t complete the setup, it should return false.}(hjw hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj; ubh)}(hThe want_state parameter indicates the state the caller needs the cache object to be in and what it wants to do during the operation:h]hThe want_state parameter indicates the state the caller needs the cache object to be in and what it wants to do during the operation:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj; ubj)}(hX * ``FSCACHE_WANT_PARAMS`` - The caller just wants to access cache object parameters; it doesn't need to do data I/O yet. * ``FSCACHE_WANT_READ`` - The caller wants to read data. * ``FSCACHE_WANT_WRITE`` - The caller wants to write to or resize the cache object. h]j)}(hhh](j)}(hw``FSCACHE_WANT_PARAMS`` - The caller just wants to access cache object parameters; it doesn't need to do data I/O yet. h]h)}(hv``FSCACHE_WANT_PARAMS`` - The caller just wants to access cache object parameters; it doesn't need to do data I/O yet.h](j)}(h``FSCACHE_WANT_PARAMS``h]hFSCACHE_WANT_PARAMS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubha - The caller just wants to access cache object parameters; it doesn’t need to do data I/O yet.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(h7``FSCACHE_WANT_READ`` - The caller wants to read data. h]h)}(h6``FSCACHE_WANT_READ`` - The caller wants to read data.h](j)}(h``FSCACHE_WANT_READ``h]hFSCACHE_WANT_READ}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh! - The caller wants to read data.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hR``FSCACHE_WANT_WRITE`` - The caller wants to write to or resize the cache object. h]h)}(hQ``FSCACHE_WANT_WRITE`` - The caller wants to write to or resize the cache object.h](j)}(h``FSCACHE_WANT_WRITE``h]hFSCACHE_WANT_WRITE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jWhj ubh; - The caller wants to write to or resize the cache object.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]jjuh1jhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhhhMhj; ubh)}(h{Note that there won't necessarily be anything attached to the cookie's cache_priv yet if the cookie is still being created.h]hNote that there won’t necessarily be anything attached to the cookie’s cache_priv yet if the cookie is still being created.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj; ubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jjuh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhhhMhjhhubeh}(h]cache-management-apiah ]h"]cache management apiah$]h&]uh1hhhhhhhhM ubh)}(hhh](h)}(h Data I/O APIh]h Data I/O API}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj@ hhhhhMubh)}(hA cache backend provides a data I/O API by through the netfs library's ``struct netfs_cache_ops`` attached to a ``struct netfs_cache_resources`` by the ``begin_operation`` method described above.h](hIA cache backend provides a data I/O API by through the netfs library’s }(hjQ hhhNhNubj)}(h``struct netfs_cache_ops``h]hstruct netfs_cache_ops}(hjY hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjQ ubh attached to a }(hjQ hhhNhNubj)}(h ``struct netfs_cache_resources``h]hstruct netfs_cache_resources}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjQ ubh by the }(hjQ hhhNhNubj)}(h``begin_operation``h]hbegin_operation}(hj} hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjQ ubh method described above.}(hjQ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj@ hhubh)}(hFSee the Documentation/filesystems/netfs_library.rst for a description.h]hFSee the Documentation/filesystems/netfs_library.rst for a description.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj@ hhubeh}(h] data-i-o-apiah ]h"] data i/o apiah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hMiscellaneous Functionsh]hMiscellaneous Functions}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hFFS-Cache provides some utilities that a cache backend may make use of:h]hFFS-Cache provides some utilities that a cache backend may make use of:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hX* Note occurrence of an I/O error in a cache:: void fscache_io_error(struct fscache_cache *cache); This tells FS-Cache that an I/O error occurred in the cache. This prevents any new I/O from being started on the cache. This does not actually withdraw the cache. That must be done separately. * Note cessation of caching on a cookie due to failure:: void fscache_caching_failed(struct fscache_cookie *cookie); This notes that a the caching that was being done on a cookie failed in some way, for instance the backing storage failed to be created or invalidation failed and that no further I/O operations should take place on it until the cache is reset. * Count I/O requests:: void fscache_count_read(void); void fscache_count_write(void); These record reads and writes from/to the cache. The numbers are displayed in /proc/fs/fscache/stats. * Count out-of-space errors:: void fscache_count_no_write_space(void); void fscache_count_no_create_space(void); These record ENOSPC errors in the cache, divided into failures of data writes and failures of filesystem object creations (e.g. mkdir). * Count objects culled:: void fscache_count_culled(void); This records the culling of an object. * Get the cookie from a set of cache resources:: struct fscache_cookie *fscache_cres_cookie(struct netfs_cache_resources *cres) Pull a pointer to the cookie from the cache resources. This may return a NULL cookie if no cookie was set. h]j)}(hhh](j)}(hX*Note occurrence of an I/O error in a cache:: void fscache_io_error(struct fscache_cache *cache); This tells FS-Cache that an I/O error occurred in the cache. This prevents any new I/O from being started on the cache. This does not actually withdraw the cache. That must be done separately. h](h)}(h,Note occurrence of an I/O error in a cache::h]h+Note occurrence of an I/O error in a cache:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(h3void fscache_io_error(struct fscache_cache *cache);h]h3void fscache_io_error(struct fscache_cache *cache);}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhMhj ubh)}(hxThis tells FS-Cache that an I/O error occurred in the cache. This prevents any new I/O from being started on the cache.h]hxThis tells FS-Cache that an I/O error occurred in the cache. This prevents any new I/O from being started on the cache.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(hIThis does not actually withdraw the cache. That must be done separately.h]hIThis does not actually withdraw the cache. That must be done separately.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hXlNote cessation of caching on a cookie due to failure:: void fscache_caching_failed(struct fscache_cookie *cookie); This notes that a the caching that was being done on a cookie failed in some way, for instance the backing storage failed to be created or invalidation failed and that no further I/O operations should take place on it until the cache is reset. h](h)}(h6Note cessation of caching on a cookie due to failure::h]h5Note cessation of caching on a cookie due to failure:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(h;void fscache_caching_failed(struct fscache_cookie *cookie);h]h;void fscache_caching_failed(struct fscache_cookie *cookie);}hj% sbah}(h]h ]h"]h$]h&]hhuh1hhhhMhj ubh)}(hThis notes that a the caching that was being done on a cookie failed in some way, for instance the backing storage failed to be created or invalidation failed and that no further I/O operations should take place on it until the cache is reset.h]hThis notes that a the caching that was being done on a cookie failed in some way, for instance the backing storage failed to be created or invalidation failed and that no further I/O operations should take place on it until the cache is reset.}(hj3 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hCount I/O requests:: void fscache_count_read(void); void fscache_count_write(void); These record reads and writes from/to the cache. The numbers are displayed in /proc/fs/fscache/stats. h](h)}(hCount I/O requests::h]hCount I/O requests:}(hjK hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjG ubh)}(h>void fscache_count_read(void); void fscache_count_write(void);h]h>void fscache_count_read(void); void fscache_count_write(void);}hjY sbah}(h]h ]h"]h$]h&]hhuh1hhhhMhjG ubh)}(hfThese record reads and writes from/to the cache. The numbers are displayed in /proc/fs/fscache/stats.h]hfThese record reads and writes from/to the cache. The numbers are displayed in /proc/fs/fscache/stats.}(hjg hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjG ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hCount out-of-space errors:: void fscache_count_no_write_space(void); void fscache_count_no_create_space(void); These record ENOSPC errors in the cache, divided into failures of data writes and failures of filesystem object creations (e.g. mkdir). h](h)}(hCount out-of-space errors::h]hCount out-of-space errors:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj{ ubh)}(hRvoid fscache_count_no_write_space(void); void fscache_count_no_create_space(void);h]hRvoid fscache_count_no_write_space(void); void fscache_count_no_create_space(void);}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhMhj{ ubh)}(hThese record ENOSPC errors in the cache, divided into failures of data writes and failures of filesystem object creations (e.g. mkdir).h]hThese record ENOSPC errors in the cache, divided into failures of data writes and failures of filesystem object creations (e.g. mkdir).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj{ ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hdCount objects culled:: void fscache_count_culled(void); This records the culling of an object. h](h)}(hCount objects culled::h]hCount objects culled:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(h void fscache_count_culled(void);h]h void fscache_count_culled(void);}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhMhj ubh)}(h&This records the culling of an object.h]h&This records the culling of an object.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hGet the cookie from a set of cache resources:: struct fscache_cookie *fscache_cres_cookie(struct netfs_cache_resources *cres) Pull a pointer to the cookie from the cache resources. This may return a NULL cookie if no cookie was set. h](h)}(h.Get the cookie from a set of cache resources::h]h-Get the cookie from a set of cache resources:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(hNstruct fscache_cookie *fscache_cres_cookie(struct netfs_cache_resources *cres)h]hNstruct fscache_cookie *fscache_cres_cookie(struct netfs_cache_resources *cres)}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhMhj ubh)}(hkPull a pointer to the cookie from the cache resources. This may return a NULL cookie if no cookie was set.h]hkPull a pointer to the cookie from the cache resources. This may return a NULL cookie if no cookie was set.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]jjuh1jhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhhhMhj hhubeh}(h]miscellaneous-functionsah ]h"]miscellaneous functionsah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hAPI Function Referenceh]hAPI Function Reference}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj+hhhhhMubhindex)}(hhh]h}(h]h ]h"]h$]h&]entries](single!fscache_cookie_state (C function)c.fscache_cookie_statehNtauh1j<hj+hhhNhNubhdesc)}(hhh](hdesc_signature)}(hNenum fscache_cookie_state fscache_cookie_state (struct fscache_cookie *cookie)h]hdesc_signature_line)}(hMenum fscache_cookie_state fscache_cookie_state(struct fscache_cookie *cookie)h](hdesc_sig_keyword)}(henumh]henum}(hj`hhhNhNubah}(h]h ]kah"]h$]h&]uh1j^hjZhhhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhK{ubhdesc_sig_space)}(h h]h }(hjrhhhNhNubah}(h]h ]wah"]h$]h&]uh1jphjZhhhjohK{ubh)}(hhh]h desc_sig_name)}(hfscache_cookie_stateh]hfscache_cookie_state}(hjhhhNhNubah}(h]h ]nah"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&] refdomaincreftype identifier reftargetjmodnameN classnameN c:parent_keysphinx.domains.c LookupKey)}data]j ASTIdentifier)}jfscache_cookie_statesbc.fscache_cookie_stateasbuh1hhjZhhhjohK{ubjq)}(h h]h }(hjhhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjZhhhjohK{ubh desc_name)}(hfscache_cookie_stateh]j)}(hjh]hfscache_cookie_state}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ](sig-namedescnameeh"]h$]h&]hhuh1jhjZhhhjohK{ubhdesc_parameterlist)}(h(struct fscache_cookie *cookie)h]hdesc_parameter)}(hstruct fscache_cookie *cookieh](j_)}(hstructh]hstruct}(hjhhhNhNubah}(h]h ]jkah"]h$]h&]uh1j^hjubjq)}(h h]h }(hjhhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjubh)}(hhh]j)}(hfscache_cookieh]hfscache_cookie}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&] refdomainjreftypej reftargetjmodnameN classnameNjj)}j]jc.fscache_cookie_stateasbuh1hhjubjq)}(h h]h }(hj#hhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjubhdesc_sig_punctuation)}(hjh]h*}(hj3hhhNhNubah}(h]h ]pah"]h$]h&]uh1j1hjubj)}(hcookieh]hcookie}(hjAhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubah}(h]h ]h"]h$]h&]hhuh1jhjZhhhjohK{ubeh}(h]h ]h"]h$]h&]hhƌ add_permalinkuh1jXsphinx_line_type declaratorhjThhhjohK{ubah}(h]jKah ](sig sig-objecteh"]h$]h&] is_multiline _toc_parts) _toc_namehuh1jRhjohK{hjOhhubh desc_content)}(hhh]h)}(hRead the state of a cookieh]hRead the state of a cookie}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhK{hjrhhubah}(h]h ]h"]h$]h&]uh1jphjOhhhjohK{ubeh}(h]h ](jfunctioneh"]h$]h&]domainjobjtypejdesctypejnoindex noindexentrynocontentsentryuh1jMhhhj+hNhNubh container)}(h**Parameters** ``struct fscache_cookie *cookie`` The cookie to query **Description** Get the state of a cookie, imposing an ordering between the cookie contents and the state value. Paired with fscache_set_cookie_state().h](h)}(h**Parameters**h]hstrong)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjubhdefinition_list)}(hhh]hdefinition_list_item)}(h6``struct fscache_cookie *cookie`` The cookie to query h](hterm)}(h!``struct fscache_cookie *cookie``h]j)}(hjh]hstruct fscache_cookie *cookie}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhK|hjubh definition)}(hhh]h)}(hThe cookie to queryh]hThe cookie to query}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK|hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjhK|hjubah}(h]h ]h"]h$]h&]uh1jhjubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhK~hjubh)}(hGet the state of a cookie, imposing an ordering between the cookie contents and the state value. Paired with fscache_set_cookie_state().h]hGet the state of a cookie, imposing an ordering between the cookie contents and the state value. Paired with fscache_set_cookie_state().}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhK}hjubeh}(h]h ] kernelindentah"]h$]h&]uh1jhj+hhhNhNubj=)}(hhh]h}(h]h ]h"]h$]h&]entries](jIfscache_get_key (C function)c.fscache_get_keyhNtauh1j<hj+hhhNhNubjN)}(hhh](jS)}(h6void * fscache_get_key (struct fscache_cookie *cookie)h]jY)}(h4void *fscache_get_key(struct fscache_cookie *cookie)h](hdesc_sig_keyword_type)}(hvoidh]hvoid}(hjJhhhNhNubah}(h]h ]ktah"]h$]h&]uh1jHhjDhhhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKubjq)}(h h]h }(hjZhhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjDhhhjYhKubj2)}(hjh]h*}(hjhhhhNhNubah}(h]h ]j=ah"]h$]h&]uh1j1hjDhhhjYhKubj)}(hfscache_get_keyh]j)}(hfscache_get_keyh]hfscache_get_key}(hjyhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjuubah}(h]h ](jjeh"]h$]h&]hhuh1jhjDhhhjYhKubj)}(h(struct fscache_cookie *cookie)h]j)}(hstruct fscache_cookie *cookieh](j_)}(hjh]hstruct}(hjhhhNhNubah}(h]h ]jkah"]h$]h&]uh1j^hjubjq)}(h h]h }(hjhhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjubh)}(hhh]j)}(hfscache_cookieh]hfscache_cookie}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&] refdomainjreftypej reftargetjmodnameN classnameNjj)}j]j)}jj{sbc.fscache_get_keyasbuh1hhjubjq)}(h h]h }(hjhhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjubj2)}(hjh]h*}(hjhhhNhNubah}(h]h ]j=ah"]h$]h&]uh1j1hjubj)}(hcookieh]hcookie}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubah}(h]h ]h"]h$]h&]hhuh1jhjDhhhjYhKubeh}(h]h ]h"]h$]h&]hhjbuh1jXjcjdhj@hhhjYhKubah}(h]j;ah ](jhjieh"]h$]h&]jmjn)johuh1jRhjYhKhj=hhubjq)}(hhh]h)}(hGet a pointer to the cookie keyh]hGet a pointer to the cookie key}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjhhubah}(h]h ]h"]h$]h&]uh1jphj=hhhjYhKubeh}(h]h ](jfunctioneh"]h$]h&]jjjj0jj0jjjuh1jMhhhj+hNhNubj)}(h**Parameters** ``struct fscache_cookie *cookie`` The cookie to query **Description** Return a pointer to the where a cookie's key is stored.h](h)}(h**Parameters**h]j)}(hj:h]h Parameters}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8ubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhj4ubj)}(hhh]j)}(h6``struct fscache_cookie *cookie`` The cookie to query h](j)}(h!``struct fscache_cookie *cookie``h]j)}(hjYh]hstruct fscache_cookie *cookie}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjWubah}(h]h ]h"]h$]h&]uh1jhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjSubj)}(hhh]h)}(hThe cookie to queryh]hThe cookie to query}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjnhKhjoubah}(h]h ]h"]h$]h&]uh1jhjSubeh}(h]h ]h"]h$]h&]uh1jhjnhKhjPubah}(h]h ]h"]h$]h&]uh1jhj4ubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhj4ubh)}(h7Return a pointer to the where a cookie's key is stored.h]h9Return a pointer to the where a cookie’s key is stored.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhj4ubeh}(h]h ] kernelindentah"]h$]h&]uh1jhj+hhhNhNubj=)}(hhh]h}(h]h ]h"]h$]h&]entries](jI!fscache_count_object (C function)c.fscache_count_objecthNtauh1j<hj+hhhNhNubjN)}(hhh](jS)}(h7void fscache_count_object (struct fscache_cache *cache)h]jY)}(h6void fscache_count_object(struct fscache_cache *cache)h](jI)}(hvoidh]hvoid}(hjhhhNhNubah}(h]h ]jUah"]h$]h&]uh1jHhjhhhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKubjq)}(h h]h }(hjhhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjhhhjhKubj)}(hfscache_count_objecth]j)}(hfscache_count_objecth]hfscache_count_object}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ](jjeh"]h$]h&]hhuh1jhjhhhjhKubj)}(h(struct fscache_cache *cache)h]j)}(hstruct fscache_cache *cacheh](j_)}(hjh]hstruct}(hjhhhNhNubah}(h]h ]jkah"]h$]h&]uh1j^hjubjq)}(h h]h }(hj#hhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjubh)}(hhh]j)}(h fscache_cacheh]h fscache_cache}(hj4hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj1ubah}(h]h ]h"]h$]h&] refdomainjreftypej reftargetj6modnameN classnameNjj)}j]j)}jjsbc.fscache_count_objectasbuh1hhjubjq)}(h h]h }(hjThhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjubj2)}(hjh]h*}(hjbhhhNhNubah}(h]h ]j=ah"]h$]h&]uh1j1hjubj)}(hcacheh]hcache}(hjohhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubah}(h]h ]h"]h$]h&]hhuh1jhjhhhjhKubeh}(h]h ]h"]h$]h&]hhjbuh1jXjcjdhjhhhjhKubah}(h]jah ](jhjieh"]h$]h&]jmjn)johuh1jRhjhKhjhhubjq)}(hhh]h)}(h*Tell fscache that an object has been addedh]h*Tell fscache that an object has been added}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjhhubah}(h]h ]h"]h$]h&]uh1jphjhhhjhKubeh}(h]h ](jfunctioneh"]h$]h&]jjjjjjjjjuh1jMhhhj+hNhNubj)}(h**Parameters** ``struct fscache_cache *cache`` The cache to account to **Description** Tell fscache that an object has been added to the cache. This prevents the cache from tearing down the cache structure until the object is uncounted.h](h)}(h**Parameters**h]j)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjubj)}(hhh]j)}(h8``struct fscache_cache *cache`` The cache to account to h](j)}(h``struct fscache_cache *cache``h]j)}(hjh]hstruct fscache_cache *cache}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjubj)}(hhh]h)}(hThe cache to account toh]hThe cache to account to}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjubh)}(hTell fscache that an object has been added to the cache. This prevents the cache from tearing down the cache structure until the object is uncounted.h]hTell fscache that an object has been added to the cache. This prevents the cache from tearing down the cache structure until the object is uncounted.}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjubeh}(h]h ] kernelindentah"]h$]h&]uh1jhj+hhhNhNubj=)}(hhh]h}(h]h ]h"]h$]h&]entries](jI#fscache_uncount_object (C function)c.fscache_uncount_objecthNtauh1j<hj+hhhNhNubjN)}(hhh](jS)}(h9void fscache_uncount_object (struct fscache_cache *cache)h]jY)}(h8void fscache_uncount_object(struct fscache_cache *cache)h](jI)}(hvoidh]hvoid}(hjZhhhNhNubah}(h]h ]jUah"]h$]h&]uh1jHhjVhhhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKubjq)}(h h]h }(hjihhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjVhhhjhhKubj)}(hfscache_uncount_objecth]j)}(hfscache_uncount_objecth]hfscache_uncount_object}(hj{hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjwubah}(h]h ](jjeh"]h$]h&]hhuh1jhjVhhhjhhKubj)}(h(struct fscache_cache *cache)h]j)}(hstruct fscache_cache *cacheh](j_)}(hjh]hstruct}(hjhhhNhNubah}(h]h ]jkah"]h$]h&]uh1j^hjubjq)}(h h]h }(hjhhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjubh)}(hhh]j)}(h fscache_cacheh]h fscache_cache}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&] refdomainjreftypej reftargetjmodnameN classnameNjj)}j]j)}jj}sbc.fscache_uncount_objectasbuh1hhjubjq)}(h h]h }(hjhhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjubj2)}(hjh]h*}(hjhhhNhNubah}(h]h ]j=ah"]h$]h&]uh1j1hjubj)}(hcacheh]hcache}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubah}(h]h ]h"]h$]h&]hhuh1jhjVhhhjhhKubeh}(h]h ]h"]h$]h&]hhjbuh1jXjcjdhjRhhhjhhKubah}(h]jMah ](jhjieh"]h$]h&]jmjn)johuh1jRhjhhKhjOhhubjq)}(hhh]h)}(h,Tell fscache that an object has been removedh]h,Tell fscache that an object has been removed}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjhhubah}(h]h ]h"]h$]h&]uh1jphjOhhhjhhKubeh}(h]h ](jfunctioneh"]h$]h&]jjjj2jj2jjjuh1jMhhhj+hNhNubj)}(h**Parameters** ``struct fscache_cache *cache`` The cache to account to **Description** Tell fscache that an object has been removed from the cache and will no longer be accessed. After this point, the cache cookie may be destroyed.h](h)}(h**Parameters**h]j)}(hj<h]h Parameters}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj:ubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhj6ubj)}(hhh]j)}(h8``struct fscache_cache *cache`` The cache to account to h](j)}(h``struct fscache_cache *cache``h]j)}(hj[h]hstruct fscache_cache *cache}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjYubah}(h]h ]h"]h$]h&]uh1jhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjUubj)}(hhh]h)}(hThe cache to account toh]hThe cache to account to}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhjphKhjqubah}(h]h ]h"]h$]h&]uh1jhjUubeh}(h]h ]h"]h$]h&]uh1jhjphKhjRubah}(h]h ]h"]h$]h&]uh1jhj6ubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhj6ubh)}(hTell fscache that an object has been removed from the cache and will no longer be accessed. After this point, the cache cookie may be destroyed.h]hTell fscache that an object has been removed from the cache and will no longer be accessed. After this point, the cache cookie may be destroyed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhj6ubeh}(h]h ] kernelindentah"]h$]h&]uh1jhj+hhhNhNubj=)}(hhh]h}(h]h ]h"]h$]h&]entries](jI%fscache_wait_for_objects (C function)c.fscache_wait_for_objectshNtauh1j<hj+hhhNhNubjN)}(hhh](jS)}(h;void fscache_wait_for_objects (struct fscache_cache *cache)h]jY)}(h:void fscache_wait_for_objects(struct fscache_cache *cache)h](jI)}(hvoidh]hvoid}(hjhhhNhNubah}(h]h ]jUah"]h$]h&]uh1jHhjhhhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKubjq)}(h h]h }(hjhhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjhhhjhKubj)}(hfscache_wait_for_objectsh]j)}(hfscache_wait_for_objectsh]hfscache_wait_for_objects}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ](jjeh"]h$]h&]hhuh1jhjhhhjhKubj)}(h(struct fscache_cache *cache)h]j)}(hstruct fscache_cache *cacheh](j_)}(hjh]hstruct}(hjhhhNhNubah}(h]h ]jkah"]h$]h&]uh1j^hjubjq)}(h h]h }(hj%hhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjubh)}(hhh]j)}(h fscache_cacheh]h fscache_cache}(hj6hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj3ubah}(h]h ]h"]h$]h&] refdomainjreftypej reftargetj8modnameN classnameNjj)}j]j)}jjsbc.fscache_wait_for_objectsasbuh1hhjubjq)}(h h]h }(hjVhhhNhNubah}(h]h ]j}ah"]h$]h&]uh1jphjubj2)}(hjh]h*}(hjdhhhNhNubah}(h]h ]j=ah"]h$]h&]uh1j1hjubj)}(hcacheh]hcache}(hjqhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubah}(h]h ]h"]h$]h&]hhuh1jhjhhhjhKubeh}(h]h ]h"]h$]h&]hhjbuh1jXjcjdhjhhhjhKubah}(h]jah ](jhjieh"]h$]h&]jmjn)johuh1jRhjhKhjhhubjq)}(hhh]h)}(h$Wait for all objects to be withdrawnh]h$Wait for all objects to be withdrawn}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjhhubah}(h]h ]h"]h$]h&]uh1jphjhhhjhKubeh}(h]h ](jfunctioneh"]h$]h&]jjjjjjjjjuh1jMhhhj+hNhNubj)}(h**Parameters** ``struct fscache_cache *cache`` The cache to query **Description** Wait for all extant objects in a cache to finish being withdrawn and go away.h](h)}(h**Parameters**h]j)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjubj)}(hhh]j)}(h3``struct fscache_cache *cache`` The cache to query h](j)}(h``struct fscache_cache *cache``h]j)}(hjh]hstruct fscache_cache *cache}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjubj)}(hhh]h)}(hThe cache to queryh]hThe cache to query}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjubh)}(hMWait for all extant objects in a cache to finish being withdrawn and go away.h]hMWait for all extant objects in a cache to finish being withdrawn and go away.}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhn/var/lib/git/docbuild/linux/Documentation/filesystems/caching/backend-api:479: ./include/linux/fscache-cache.hhKhjubeh}(h]h ] kernelindentah"]h$]h&]uh1jhj+hhhNhNubeh}(h]api-function-referenceah ]h"]api function referenceah$]h&]uh1hhhhhhhhMubeh}(h]cache-backend-apiah ]h"]cache backend apiah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksjLfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjuerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jPjMjljijjjTjQjjjfjcjjjIjFjjj= j: j j j(j%jHjEu nametypes}(jPjljjTjjfjjIjj= j j(jHuh}(jMhjihjjojQjjjWjcjjjijFjjjLj: jj j@ j%j jEj+jKjTj;j@jjjMjRjju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.