Lines Matching full:cache
2 FS-CACHE CACHE BACKEND API
5 The FS-Cache system provides an API by which actual caches can be supplied to
6 FS-Cache for it to then serve out to network filesystems and other interested
9 This API is declared in <linux/fscache-cache.h>.
13 INITIALISING AND REGISTERING A CACHE
16 To start off, a cache definition must be initialised and registered for each
17 cache the backend wants to make available. For instance, CacheFS does this in
20 The cache definition (struct fscache_cache) should be initialised by calling:
22 void fscache_init_cache(struct fscache_cache *cache,
29 (*) "cache" is a pointer to the cache definition;
32 this cache; and
35 for the cache.
38 The cache should then be registered with FS-Cache by passing a pointer to the
39 previously initialised cache definition to:
41 int fscache_add_cache(struct fscache_cache *cache,
47 (*) "fsdef" which should point to the object representation for the FS-Cache
48 master index in this cache. Netfs primary index entries will be created
49 here. FS-Cache keeps the caller's reference to the index object if
50 successful and will release it upon withdrawal of the cache.
52 (*) "tagname" which, if given, should be a text string naming this cache. If
62 UNREGISTERING A CACHE
65 A cache can be withdrawn from the system by calling this function with a
66 pointer to the cache definition:
68 void fscache_withdraw_cache(struct fscache_cache *cache);
77 The cache methods are executed one of two contexts:
80 the cache method to be invoked, or
82 (2) that of one of the processes in the FS-Cache thread pool.
85 cache.
88 be masqueraded for the duration of the cache driver's access to the cache.
89 This is left to the cache to handle; FS-Cache makes no effort in this regard.
96 The cache may present data to the outside world through FS-Cache's interfaces
101 and is for use by the cache as it sees fit.
108 (*) Index/Data file FS-Cache representation cookie:
121 cache operations.
124 (*) In-cache object representation:
133 struct fscache_cache *cache;
138 Structures of this type should be allocated by the cache backend and
139 passed to FS-Cache when requested by the appropriate cache operation. In
145 using "OBJ%x" to be consistent with FS-Cache.
153 (*) FS-Cache operation record:
165 FS-Cache has a pool of threads that it uses to give CPU time to the
167 the cache. These are represented by the above structure. The processor
176 (*) FS-Cache retrieval operation record:
185 A structure of this type is allocated by FS-Cache to record retrieval and
197 The to_do field is an empty list available for the cache backend to use as
201 (*) FS-Cache storage operation record:
209 A structure of this type is allocated by FS-Cache to record outstanding
210 writes to be made. FS-Cache itself enqueues this operation and invokes
216 CACHE OPERATIONS
219 The cache backend provides FS-Cache with a table of operations that can be
220 performed on the denizens of the cache. These are held in a structure of type:
224 (*) Name of cache provider [mandatory]:
234 struct fscache_object *(*alloc_object)(struct fscache_cache *cache,
237 This method is used to allocate a cache object representation to back a
238 cookie in a particular cache. fscache_object_init() should be called on
242 multiple lookup calls to turn it into a more convenient form. FS-Cache
243 will call the lookup_complete() method to allow the cache to release the
253 in the cache if it can.
256 possible if it determines the object doesn't exist in the cache. If the
270 This method is called to ask the cache to release any resources it was
279 may fail (for instance if the cache is being withdrawn) by returning NULL.
297 These methods are used to pin an object into the cache. Once pinned an
299 enough space in the cache to permit this.
306 This method is called to have the cache check the saved auxiliary data of
337 cookie, and that the cache should release the object's resources and
352 (*) Synchronise a cache [mandatory]:
354 void (*sync)(struct fscache_cache *cache)
356 This is called to ask the backend to synchronise a cache with its backing
360 (*) Dissociate a cache [mandatory]:
362 void (*dissociate_pages)(struct fscache_cache *cache)
364 This is called to ask a cache to perform any page dissociations as part of
365 cache withdrawal.
372 This is called to indicate to the cache that certain attributes on a netfs
374 cache can read these from the netfs by calling the cookie's get_attr()
377 The cache may use the file size information to reserve space on the cache.
378 It should also call fscache_set_store_limit() to indicate to FS-Cache the
381 This method may return -ve if an error occurred or the cache object cannot
384 This operation is run asynchronously from FS-Cache's thread pool, and
389 (*) Reserve cache space for an object's data [optional]:
393 This is called to request that cache space be reserved to hold the data
407 (*) Request page be read from cache [mandatory]:
413 This is called to attempt to read a netfs page from the cache, or to
414 reserve a backing block if not. FS-Cache will have done as much checking
417 If there's no page in the cache, then -ENODATA should be returned if the
421 If there is suitable data in the cache, then a read operation should be
425 The fscache_mark_pages_cached() should be called for the page if any cache
434 The retrieval record may be used to get CPU time via the FS-Cache thread
449 (*) Request pages be read from cache [mandatory]:
458 started must be added to the page cache for the specified mapping and also
469 (*) Request page be allocated in the cache [mandatory]:
476 read from the cache, even if there's data there that could be retrieved.
478 the write_page() method can write to the cache.
485 (*) Request pages be allocated in the cache [mandatory]:
496 (*) Request page be written to cache [mandatory]:
502 successful read_or_alloc_page() call or similar. FS-Cache filters out
505 This method is called asynchronously from the FS-Cache thread pool. It is
510 otherwise zero should be returned. FS-Cache will take appropriate action
513 If this method returns success then FS-Cache will inform the netfs
522 cache backend should tear down any internal representation or tracking it
527 FS-CACHE UTILITIES
530 FS-Cache provides some utilities that a cache backend may make use of:
532 (*) Note occurrence of an I/O error in a cache:
534 void fscache_io_error(struct fscache_cache *cache)
536 This tells FS-Cache that an I/O error occurred in the cache. After this
538 release) will be passed from the netfs to the cache backend for the
539 specified cache.
541 This does not actually withdraw the cache. That must be done separately.
579 This sets the limit FS-Cache imposes on the highest byte it's willing to
602 retrieved from the cache can be found.
630 void fscache_object_destroyed(struct fscache_cache *cache);
632 This must be called to inform FS-Cache that an object that belonged to a
633 cache has been destroyed and deallocated. This will allow continuation
634 of the cache withdrawal process when it is stopped pending destruction of
642 This is called to indicate to FS-Cache that a lookup process for an object
647 known at this point that there can't be any data in the cache.
657 This is called to indicate to FS-Cache that a lookup process for an object
684 the cache that the netfs decided was stale. The object has been
685 discarded from the cache and the lookup will be performed again.
693 This is called to indicate that the cache backend preemptively killed an
697 FSCACHE_OBJECT_NO_SPACE - there was insufficient cache space
715 This enqueues a retrieval record for processing by the FS-Cache thread