filesystems/caching/object.rst

4 In-Kernel Cache Object Representation and Management
13  (*) Object management state machine.
26 FS-Cache maintains an in-kernel representation of each object that a netfs is
41 correspond, but the cookies tree is a superset of the union of the object trees
93 Object Management State Machine
96 Within FS-Cache, each active object is managed by its own individual state
97 machine.  The state for an object is kept in the fscache_object struct, in
98 object->state.  A cookie may point to a set of objects that are in different
105      representations are hierarchical, and it is expected that an object must
106      be created or accessed with respect to its parent object.
121 which it is interested (object->event_mask) and relinquish the worker thread.
123 is not masked, the object will be queued for processing (by calling
147 Because only one worker thread may be operating on any particular object's
149 to disconnecting the netfs's representation of a cache object (fscache_cookie)
157 The object state machine has a set of states that it can be in.  There are
158 preparation states in which the object sets itself up and waits for its parent
159 object to transit to a state that allows access to its children:
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
168 There are initialisation states in which the object sets itself up and accesses
169 disk for the object metadata:
173      Look up the object on disk, using the parent as a starting point.
175      object is represented there, and if it is, to see if it's valid (coherency
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
200      operations the netfs has queued for an object.  If creation failed, the
204 There are some normal running states in which the object spends its time
220      The object is undergoing invalidation.  When the state comes here, it
227      The state machine comes here to update the object in the cache from the
231 And there are terminal states in which an object cleans itself up, deallocates
236      The object comes here if it is dying because of a lookup or creation
242      The object comes here if it is dying due to an error, because its parent
247      can destroy themselves.  This object waits for all its children to go away
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
259      The object comes to one of these two states when dying once it is rid of
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
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
280 There are a number of events that can be raised to an object state machine:
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
290      (a) when an object's last child object is dropped and
292      (b) when the last operation outstanding on an object is completed.
298      object.
303      object to be retired (deleted) or retained.
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
310 Because the withdrawing releasing/retiring events are all handled by the object