filesystems/caching/backend-api.rst

48    * "fsdef" which should point to the object representation for the FS-Cache
50      here.  FS-Cache keeps the caller's reference to the index object if
114      The fields that might be of use to the backend describe the object
116      The object definition contain functions supplied by the netfs for loading
121    * In-cache object representation::
137      the case of CacheFS, they're embedded in CacheFS's internal object
141      that refer to a particular object.  In such a case it should be printed
144      Each object contains a pointer to the cookie that represents the object it
145      is backing.  An object should retired when put_object() is called if it is
147      initialised by calling fscache_object_init(object).
154 		struct fscache_object	*object;
168      An operation can be made exclusive upon an object by setting the
208      the write_page() method on the object at appropriate times to effect
230    * Allocate a new object [mandatory]::
235      This method is used to allocate a cache object representation to back a
237      the object to initialise it prior to returning.
245    * Look up and create object [mandatory]::
247 	void (*lookup_object)(struct fscache_object *object)
249      This method is used to look up an object, given that the object is already
250      allocated and attached to the cookie.  This should instantiate that object
254      possible if it determines the object doesn't exist in the cache.  If the
255      object is found to exist and the netfs indicates that it is valid then
256      fscache_obtained_object() should be called once the object is in a
258      should also be called once a non-present object has been created.
261      to abort the lookup of that object.
266 	void (*lookup_complete)(struct fscache_object *object)
272    * Increment object refcount [mandatory]::
274 	struct fscache_object *(*grab_object)(struct fscache_object *object)
276      This method is called to increment the reference count on an object.  It
278      It should return the object pointer if successful.
281    * Lock/Unlock object [mandatory]::
283 	void (*lock_object)(struct fscache_object *object)
284 	void (*unlock_object)(struct fscache_object *object)
286      These methods are used to exclusively lock an object.  It must be possible
290    * Pin/Unpin object [optional]::
292 	int (*pin_object)(struct fscache_object *object)
293 	void (*unpin_object)(struct fscache_object *object)
295      These methods are used to pin an object into the cache.  Once pinned an
296      object cannot be reclaimed to make space.  Return -ENOSPC if there's not
300    * Check coherency state of an object [mandatory]::
302 	int (*check_consistency)(struct fscache_object *object)
305      the object against the netfs's idea of the state.  0 should be returned
309    * Update object [mandatory]::
311 	int (*update_object)(struct fscache_object *object)
313      This is called to update the index entry for the specified object.  The
314      new information should be in object->cookie->netfs_data.  This can be
315      obtained by calling object->cookie->def->get_aux()/get_attr().
318    * Invalidate data object [mandatory]::
322      This is called to invalidate a data object (as pointed to by op->object).
323      All the data stored for this object should be discarded and an
325      with an object update operation.
330    * Discard object [mandatory]::
332 	void (*drop_object)(struct fscache_object *object)
334      This method is called to indicate that an object has been unbound from its
335      cookie, and that the cache should release the object's resources and
342    * Release object reference [mandatory]::
344 	void (*put_object)(struct fscache_object *object)
346      This method is used to discard a reference to an object.  The object may
368 	int (*attr_changed)(struct fscache_object *object);
377      highest byte it's willing to store for an object.
379      This method may return -ve if an error occurred or the cache object cannot
380      be expanded.  In such a case, the object will be withdrawn from service.
387    * Reserve cache space for an object's data [optional]::
389 	int (*reserve_space)(struct fscache_object *object, loff_t size);
392      for an object and the metadata used to track it.  Zero size should be
398      The reservation may exceed the current size of the object, thus permitting
399      future expansion.  If the amount of space consumed by an object would
401      pages, but not required.  An object may be pruned down to its reservation
509      in response to an error, such as withdrawing this object.
517 	void (*uncache_page)(struct fscache_object *object, struct page *page)
534      has been called, only resource dissociation operations (object and page
567      this operation from the parent object's run state, potentially permitting
573 	void fscache_set_store_limit(struct fscache_object *object,
590    * Perform coherency check on an object::
592 	enum fscache_checkaux fscache_check_aux(struct fscache_object *object,
596      This asks the netfs to perform a coherency check on an object that has
597      just been looked up.  The cookie attached to the object will determine the
604 	    The coherency data indicates the object is valid as is.
607 	    The coherency data needs updating, but otherwise the object is
611 	    The coherency data indicates that the object is obsolete and should
615    * Initialise a freshly allocated object::
617 	void fscache_object_init(struct fscache_object *object);
619      This initialises all the fields in an object representation.
622    * Indicate the destruction of an object::
626      This must be called to inform FS-Cache that an object that belonged to a
632    * Indicate negative lookup on an object::
634 	void fscache_object_lookup_negative(struct fscache_object *object);
636      This is called to indicate to FS-Cache that a lookup process for an object
639      This changes the state of an object to permit reads pending on lookup
643      This may be called multiple times on an object.  Only the first call is
647    * Indicate an object has been obtained::
649 	void fscache_obtained_object(struct fscache_object *object);
651      This is called to indicate to FS-Cache that a lookup process for an object
652      produced a positive result, or that an object was created.  This should
653      only be called once for any particular object.
655      This changes the state of an object to indicate:
658 	    this object, that there may be data available, and that reads can
661         (2) that writes may now proceed against this object.
664    * Indicate that object lookup failed::
666 	void fscache_object_lookup_error(struct fscache_object *object);
668      This marks an object as having encountered a fatal error (usually EIO)
673    * Indicate that a stale object was found and discarded::
675 	void fscache_object_retrying_stale(struct fscache_object *object);
677      This is called to indicate that the lookup procedure found an object in
678      the cache that the netfs decided was stale.  The object has been
682    * Indicate that the caching backend killed an object::
684 	void fscache_object_mark_killed(struct fscache_object *object,
688      object.  The why parameter should be set to indicate the reason:
691 	    - the object was stale and needs discarding.
697 	    - the object was retired when relinquished.
700 	    - the object was culled to make space.
722    * List of object state names::
726      For debugging purposes, this may be used to turn the state that an object