Documentation/filesystems/caching/backend-api.rst

Source file repositories/reference/linux-study-clean/Documentation/filesystems/caching/backend-api.rst

File Facts

System
Linux kernel
Corpus path
Documentation/filesystems/caching/backend-api.rst
Extension
.rst
Size
16508 bytes
Lines
480
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct fscache_cache {
		void		*cache_priv;
		unsigned int	debug_id;
		char		*name;
		...
	};

There 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.


Registering a Cache
===================

When a cache backend wants to bring a cache online, it should first register
the cache name and that will get it a cache cookie.  This is done with::

	struct fscache_cache *fscache_acquire_cache(const char *name);

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.

If successful, the cache backend can then start setting up the cache.  In the
event that the initialisation fails, the cache backend should call::

	void fscache_relinquish_cache(struct fscache_cache *cache);

to reset and discard the cookie.


Bringing a Cache Online
=======================

Once the cache is set up, it can be brought online by calling::

	int fscache_add_cache(struct fscache_cache *cache,
			      const struct fscache_cache_ops *ops,
			      void *cache_priv);

This 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.


Withdrawing a Cache From Service
================================

The cache backend can withdraw a cache from service by calling this function::

	void fscache_withdraw_cache(struct fscache_cache *cache);

This 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.

The cache must then go through the data storage objects it has and tell fscache
to withdraw them, calling::

	void fscache_withdraw_cookie(struct fscache_cookie *cookie);

on the cookie that each object belongs to.  This schedules the specified cookie
for withdrawal.  This gets offloaded to a workqueue.  The cache backend can
wait for completion by calling::

Annotation

Implementation Notes