1.. SPDX-License-Identifier: GPL-2.0 2 3==================================================== 4In-Kernel Cache Object Representation and Management 5==================================================== 6 7By: David Howells <dhowells@redhat.com> 8 9.. Contents: 10 11 (*) Representation 12 13 (*) Object management state machine. 14 15 - Provision of cpu time. 16 - Locking simplification. 17 18 (*) The set of states. 19 20 (*) The set of events. 21 22 23Representation 24============== 25 26FS-Cache maintains an in-kernel representation of each object that a netfs is 27currently interested in. Such objects are represented by the fscache_cookie 28struct and are referred to as cookies. 29 30FS-Cache also maintains a separate in-kernel representation of the objects that 31a cache backend is currently actively caching. Such objects are represented by 32the fscache_object struct. The cache backends allocate these upon request, and 33are expected to embed them in their own representations. These are referred to 34as objects. 35 36There is a 1:N relationship between cookies and objects. A cookie may be 37represented by multiple objects - an index may exist in more than one cache - 38or even by no objects (it may not be cached). 39 40Furthermore, both cookies and objects are hierarchical. The two hierarchies 41correspond, but the cookies tree is a superset of the union of the object trees 42of multiple caches:: 43 44 NETFS INDEX TREE : CACHE 1 : CACHE 2 45 : : 46 : +-----------+ : 47 +----------->| IObject | : 48 +-----------+ | : +-----------+ : 49 | ICookie |-------+ : | : 50 +-----------+ | : | : +-----------+ 51 | +------------------------------>| IObject | 52 | : | : +-----------+ 53 | : V : | 54 | : +-----------+ : | 55 V +----------->| IObject | : | 56 +-----------+ | : +-----------+ : | 57 | ICookie |-------+ : | : V 58 +-----------+ | : | : +-----------+ 59 | +------------------------------>| IObject | 60 +-----+-----+ : | : +-----------+ 61 | | : | : | 62 V | : V : | 63 +-----------+ | : +-----------+ : | 64 | ICookie |------------------------->| IObject | : | 65 +-----------+ | : +-----------+ : | 66 | V : | : V 67 | +-----------+ : | : +-----------+ 68 | | ICookie |-------------------------------->| IObject | 69 | +-----------+ : | : +-----------+ 70 V | : V : | 71 +-----------+ | : +-----------+ : | 72 | DCookie |------------------------->| DObject | : | 73 +-----------+ | : +-----------+ : | 74 | : : | 75 +-------+-------+ : : | 76 | | : : | 77 V V : : V 78 +-----------+ +-----------+ : : +-----------+ 79 | DCookie | | DCookie |------------------------>| DObject | 80 +-----------+ +-----------+ : : +-----------+ 81 : : 82 83In the above illustration, ICookie and IObject represent indices and DCookie 84and DObject represent data storage objects. Indices may have representation in 85multiple caches, but currently, non-index objects may not. Objects of any type 86may also be entirely unrepresented. 87 88As far as the netfs API goes, the netfs is only actually permitted to see 89pointers to the cookies. The cookies themselves and any objects attached to 90those cookies are hidden from it. 91 92 93Object Management State Machine 94=============================== 95 96Within FS-Cache, each active object is managed by its own individual state 97machine. The state for an object is kept in the fscache_object struct, in 98object->state. A cookie may point to a set of objects that are in different 99states. 100 101Each state has an action associated with it that is invoked when the machine 102wakes up in that state. There are four logical sets of states: 103 104 (1) Preparation: states that wait for the parent objects to become ready. The 105 representations are hierarchical, and it is expected that an object must 106 be created or accessed with respect to its parent object. 107 108 (2) Initialisation: states that perform lookups in the cache and validate 109 what's found and that create on disk any missing metadata. 110 111 (3) Normal running: states that allow netfs operations on objects to proceed 112 and that update the state of objects. 113 114 (4) Termination: states that detach objects from their netfs cookies, that 115 delete objects from disk, that handle disk and system errors and that free 116 up in-memory resources. 117 118 119In most cases, transitioning between states is in response to signalled events. 120When a state has finished processing, it will usually set the mask of events in 121which it is interested (object->event_mask) and relinquish the worker thread. 122Then when an event is raised (by calling fscache_raise_event()), if the event 123is not masked, the object will be queued for processing (by calling 124fscache_enqueue_object()). 125 126 127Provision of CPU Time 128--------------------- 129 130The work to be done by the various states was given CPU time by the threads of 131the slow work facility. This was used in preference to the workqueue facility 132because: 133 134 (1) Threads may be completely occupied for very long periods of time by a 135 particular work item. These state actions may be doing sequences of 136 synchronous, journalled disk accesses (lookup, mkdir, create, setxattr, 137 getxattr, truncate, unlink, rmdir, rename). 138 139 (2) Threads may do little actual work, but may rather spend a lot of time 140 sleeping on I/O. This means that single-threaded and 1-per-CPU-threaded 141 workqueues don't necessarily have the right numbers of threads. 142 143 144Locking Simplification 145---------------------- 146 147Because only one worker thread may be operating on any particular object's 148state machine at once, this simplifies the locking, particularly with respect 149to disconnecting the netfs's representation of a cache object (fscache_cookie) 150from the cache backend's representation (fscache_object) - which may be 151requested from either end. 152 153 154The Set of States 155================= 156 157The object state machine has a set of states that it can be in. There are 158preparation states in which the object sets itself up and waits for its parent 159object to transit to a state that allows access to its children: 160 161 (1) State FSCACHE_OBJECT_INIT. 162 163 Initialise the object and wait for the parent object to become active. In 164 the cache, it is expected that it will not be possible to look an object 165 up from the parent object, until that parent object itself has been looked 166 up. 167 168There are initialisation states in which the object sets itself up and accesses 169disk for the object metadata: 170 171 (2) State FSCACHE_OBJECT_LOOKING_UP. 172 173 Look up the object on disk, using the parent as a starting point. 174 FS-Cache expects the cache backend to probe the cache to see whether this 175 object is represented there, and if it is, to see if it's valid (coherency 176 management). 177 178 The cache should call fscache_object_lookup_negative() to indicate lookup 179 failure for whatever reason, and should call fscache_obtained_object() to 180 indicate success. 181 182 At the completion of lookup, FS-Cache will let the netfs go ahead with 183 read operations, no matter whether the file is yet cached. If not yet 184 cached, read operations will be immediately rejected with ENODATA until 185 the first known page is uncached - as to that point there can be no data 186 to be read out of the cache for that file that isn't currently also held 187 in the pagecache. 188 189 (3) State FSCACHE_OBJECT_CREATING. 190 191 Create an object on disk, using the parent as a starting point. This 192 happens if the lookup failed to find the object, or if the object's 193 coherency data indicated what's on disk is out of date. In this state, 194 FS-Cache expects the cache to create 195 196 The cache should call fscache_obtained_object() if creation completes 197 successfully, fscache_object_lookup_negative() otherwise. 198 199 At the completion of creation, FS-Cache will start processing write 200 operations the netfs has queued for an object. If creation failed, the 201 write ops will be transparently discarded, and nothing recorded in the 202 cache. 203 204There are some normal running states in which the object spends its time 205servicing netfs requests: 206 207 (4) State FSCACHE_OBJECT_AVAILABLE. 208 209 A transient state in which pending operations are started, child objects 210 are permitted to advance from FSCACHE_OBJECT_INIT state, and temporary 211 lookup data is freed. 212 213 (5) State FSCACHE_OBJECT_ACTIVE. 214 215 The normal running state. In this state, requests the netfs makes will be 216 passed on to the cache. 217 218 (6) State FSCACHE_OBJECT_INVALIDATING. 219 220 The object is undergoing invalidation. When the state comes here, it 221 discards all pending read, write and attribute change operations as it is 222 going to clear out the cache entirely and reinitialise it. It will then 223 continue to the FSCACHE_OBJECT_UPDATING state. 224 225 (7) State FSCACHE_OBJECT_UPDATING. 226 227 The state machine comes here to update the object in the cache from the 228 netfs's records. This involves updating the auxiliary data that is used 229 to maintain coherency. 230 231And there are terminal states in which an object cleans itself up, deallocates 232memory and potentially deletes stuff from disk: 233 234 (8) State FSCACHE_OBJECT_LC_DYING. 235 236 The object comes here if it is dying because of a lookup or creation 237 error. This would be due to a disk error or system error of some sort. 238 Temporary data is cleaned up, and the parent is released. 239 240 (9) State FSCACHE_OBJECT_DYING. 241 242 The object comes here if it is dying due to an error, because its parent 243 cookie has been relinquished by the netfs or because the cache is being 244 withdrawn. 245 246 Any child objects waiting on this one are given CPU time so that they too 247 can destroy themselves. This object waits for all its children to go away 248 before advancing to the next state. 249 250(10) State FSCACHE_OBJECT_ABORT_INIT. 251 252 The object comes to this state if it was waiting on its parent in 253 FSCACHE_OBJECT_INIT, but its parent died. The object will destroy itself 254 so that the parent may proceed from the FSCACHE_OBJECT_DYING state. 255 256(11) State FSCACHE_OBJECT_RELEASING. 257(12) State FSCACHE_OBJECT_RECYCLING. 258 259 The object comes to one of these two states when dying once it is rid of 260 all its children, if it is dying because the netfs relinquished its 261 cookie. In the first state, the cached data is expected to persist, and 262 in the second it will be deleted. 263 264(13) State FSCACHE_OBJECT_WITHDRAWING. 265 266 The object transits to this state if the cache decides it wants to 267 withdraw the object from service, perhaps to make space, but also due to 268 error or just because the whole cache is being withdrawn. 269 270(14) State FSCACHE_OBJECT_DEAD. 271 272 The object transits to this state when the in-memory object record is 273 ready to be deleted. The object processor shouldn't ever see an object in 274 this state. 275 276 277The Set of Events 278----------------- 279 280There are a number of events that can be raised to an object state machine: 281 282 FSCACHE_OBJECT_EV_UPDATE 283 The netfs requested that an object be updated. The state machine will ask 284 the cache backend to update the object, and the cache backend will ask the 285 netfs for details of the change through its cookie definition ops. 286 287 FSCACHE_OBJECT_EV_CLEARED 288 This is signalled in two circumstances: 289 290 (a) when an object's last child object is dropped and 291 292 (b) when the last operation outstanding on an object is completed. 293 294 This is used to proceed from the dying state. 295 296 FSCACHE_OBJECT_EV_ERROR 297 This is signalled when an I/O error occurs during the processing of some 298 object. 299 300 FSCACHE_OBJECT_EV_RELEASE, FSCACHE_OBJECT_EV_RETIRE 301 These are signalled when the netfs relinquishes a cookie it was using. 302 The event selected depends on whether the netfs asks for the backing 303 object to be retired (deleted) or retained. 304 305 FSCACHE_OBJECT_EV_WITHDRAW 306 This is signalled when the cache backend wants to withdraw an object. 307 This means that the object will have to be detached from the netfs's 308 cookie. 309 310Because the withdrawing releasing/retiring events are all handled by the object 311state machine, it doesn't matter if there's a collision with both ends trying 312to sever the connection at the same time. The state machine can just pick 313which one it wants to honour, and that effects the other. 314