include/linux/fscache-cache.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /* General filesystem caching backing cache interface
0003  *
0004  * Copyright (C) 2021 Red Hat, Inc. All Rights Reserved.
0005  * Written by David Howells (dhowells@redhat.com)
0006  *
0007  * NOTE!!! See:
0008  *
0009  *  Documentation/filesystems/caching/backend-api.rst
0010  *
0011  * for a description of the cache backend interface declared here.
0012  */
0013
0014 #ifndef _LINUX_FSCACHE_CACHE_H
0015 #define _LINUX_FSCACHE_CACHE_H
0016
0017 #include <linux/fscache.h>
0018
0019 enum fscache_cache_trace;
0020 enum fscache_cookie_trace;
0021 enum fscache_access_trace;
0022
0023 enum fscache_cache_state {
0024     FSCACHE_CACHE_IS_NOT_PRESENT,   /* No cache is present for this name */
0025     FSCACHE_CACHE_IS_PREPARING, /* A cache is preparing to come live */
0026     FSCACHE_CACHE_IS_ACTIVE,    /* Attached cache is active and can be used */
0027     FSCACHE_CACHE_GOT_IOERROR,  /* Attached cache stopped on I/O error */
0028     FSCACHE_CACHE_IS_WITHDRAWN, /* Attached cache is being withdrawn */
0029 #define NR__FSCACHE_CACHE_STATE (FSCACHE_CACHE_IS_WITHDRAWN + 1)
0030 };
0031
0032 /*
0033  * Cache cookie.
0034  */
0035 struct fscache_cache {
0036     const struct fscache_cache_ops *ops;
0037     struct list_head    cache_link; /* Link in cache list */
0038     void            *cache_priv;    /* Private cache data (or NULL) */
0039     refcount_t      ref;
0040     atomic_t        n_volumes;  /* Number of active volumes; */
0041     atomic_t        n_accesses; /* Number of in-progress accesses on the cache */
0042     atomic_t        object_count;   /* no. of live objects in this cache */
0043     unsigned int        debug_id;
0044     enum fscache_cache_state state;
0045     char            *name;
0046 };
0047
0048 /*
0049  * cache operations
0050  */
0051 struct fscache_cache_ops {
0052     /* name of cache provider */
0053     const char *name;
0054
0055     /* Acquire a volume */
0056     void (*acquire_volume)(struct fscache_volume *volume);
0057
0058     /* Free the cache's data attached to a volume */
0059     void (*free_volume)(struct fscache_volume *volume);
0060
0061     /* Look up a cookie in the cache */
0062     bool (*lookup_cookie)(struct fscache_cookie *cookie);
0063
0064     /* Withdraw an object without any cookie access counts held */
0065     void (*withdraw_cookie)(struct fscache_cookie *cookie);
0066
0067     /* Change the size of a data object */
0068     void (*resize_cookie)(struct netfs_cache_resources *cres,
0069                   loff_t new_size);
0070
0071     /* Invalidate an object */
0072     bool (*invalidate_cookie)(struct fscache_cookie *cookie);
0073
0074     /* Begin an operation for the netfs lib */
0075     bool (*begin_operation)(struct netfs_cache_resources *cres,
0076                 enum fscache_want_state want_state);
0077
0078     /* Prepare to write to a live cache object */
0079     void (*prepare_to_write)(struct fscache_cookie *cookie);
0080 };
0081
0082 extern struct workqueue_struct *fscache_wq;
0083 extern wait_queue_head_t fscache_clearance_waiters;
0084
0085 /*
0086  * out-of-line cache backend functions
0087  */
0088 extern struct rw_semaphore fscache_addremove_sem;
0089 extern struct fscache_cache *fscache_acquire_cache(const char *name);
0090 extern void fscache_relinquish_cache(struct fscache_cache *cache);
0091 extern int fscache_add_cache(struct fscache_cache *cache,
0092                  const struct fscache_cache_ops *ops,
0093                  void *cache_priv);
0094 extern void fscache_withdraw_cache(struct fscache_cache *cache);
0095 extern void fscache_withdraw_volume(struct fscache_volume *volume);
0096 extern void fscache_withdraw_cookie(struct fscache_cookie *cookie);
0097
0098 extern void fscache_io_error(struct fscache_cache *cache);
0099
0100 extern void fscache_end_volume_access(struct fscache_volume *volume,
0101                       struct fscache_cookie *cookie,
0102                       enum fscache_access_trace why);
0103
0104 extern struct fscache_cookie *fscache_get_cookie(struct fscache_cookie *cookie,
0105                          enum fscache_cookie_trace where);
0106 extern void fscache_put_cookie(struct fscache_cookie *cookie,
0107                    enum fscache_cookie_trace where);
0108 extern void fscache_end_cookie_access(struct fscache_cookie *cookie,
0109                       enum fscache_access_trace why);
0110 extern void fscache_cookie_lookup_negative(struct fscache_cookie *cookie);
0111 extern void fscache_resume_after_invalidation(struct fscache_cookie *cookie);
0112 extern void fscache_caching_failed(struct fscache_cookie *cookie);
0113 extern bool fscache_wait_for_operation(struct netfs_cache_resources *cred,
0114                        enum fscache_want_state state);
0115
0116 /**
0117  * fscache_cookie_state - Read the state of a cookie
0118  * @cookie: The cookie to query
0119  *
0120  * Get the state of a cookie, imposing an ordering between the cookie contents
0121  * and the state value.  Paired with fscache_set_cookie_state().
0122  */
0123 static inline
0124 enum fscache_cookie_state fscache_cookie_state(struct fscache_cookie *cookie)
0125 {
0126     return smp_load_acquire(&cookie->state);
0127 }
0128
0129 /**
0130  * fscache_get_key - Get a pointer to the cookie key
0131  * @cookie: The cookie to query
0132  *
0133  * Return a pointer to the where a cookie's key is stored.
0134  */
0135 static inline void *fscache_get_key(struct fscache_cookie *cookie)
0136 {
0137     if (cookie->key_len <= sizeof(cookie->inline_key))
0138         return cookie->inline_key;
0139     else
0140         return cookie->key;
0141 }
0142
0143 static inline struct fscache_cookie *fscache_cres_cookie(struct netfs_cache_resources *cres)
0144 {
0145     return cres->cache_priv;
0146 }
0147
0148 /**
0149  * fscache_count_object - Tell fscache that an object has been added
0150  * @cache: The cache to account to
0151  *
0152  * Tell fscache that an object has been added to the cache.  This prevents the
0153  * cache from tearing down the cache structure until the object is uncounted.
0154  */
0155 static inline void fscache_count_object(struct fscache_cache *cache)
0156 {
0157     atomic_inc(&cache->object_count);
0158 }
0159
0160 /**
0161  * fscache_uncount_object - Tell fscache that an object has been removed
0162  * @cache: The cache to account to
0163  *
0164  * Tell fscache that an object has been removed from the cache and will no
0165  * longer be accessed.  After this point, the cache cookie may be destroyed.
0166  */
0167 static inline void fscache_uncount_object(struct fscache_cache *cache)
0168 {
0169     if (atomic_dec_and_test(&cache->object_count))
0170         wake_up_all(&fscache_clearance_waiters);
0171 }
0172
0173 /**
0174  * fscache_wait_for_objects - Wait for all objects to be withdrawn
0175  * @cache: The cache to query
0176  *
0177  * Wait for all extant objects in a cache to finish being withdrawn
0178  * and go away.
0179  */
0180 static inline void fscache_wait_for_objects(struct fscache_cache *cache)
0181 {
0182     wait_event(fscache_clearance_waiters,
0183            atomic_read(&cache->object_count) == 0);
0184 }
0185
0186 #ifdef CONFIG_FSCACHE_STATS
0187 extern atomic_t fscache_n_read;
0188 extern atomic_t fscache_n_write;
0189 extern atomic_t fscache_n_no_write_space;
0190 extern atomic_t fscache_n_no_create_space;
0191 extern atomic_t fscache_n_culled;
0192 #define fscache_count_read() atomic_inc(&fscache_n_read)
0193 #define fscache_count_write() atomic_inc(&fscache_n_write)
0194 #define fscache_count_no_write_space() atomic_inc(&fscache_n_no_write_space)
0195 #define fscache_count_no_create_space() atomic_inc(&fscache_n_no_create_space)
0196 #define fscache_count_culled() atomic_inc(&fscache_n_culled)
0197 #else
0198 #define fscache_count_read() do {} while(0)
0199 #define fscache_count_write() do {} while(0)
0200 #define fscache_count_no_write_space() do {} while(0)
0201 #define fscache_count_no_create_space() do {} while(0)
0202 #define fscache_count_culled() do {} while(0)
0203 #endif
0204
0205 #endif /* _LINUX_FSCACHE_CACHE_H */