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