Skip to content

Commit 36c9559

Browse files
dhowellsdhowells
committed
FS-Cache: Object management state machine
Implement the cache object management state machine. The following documentation is added to illuminate the working of this state machine. It will also be added as: Documentation/filesystems/caching/object.txt ==================================================== IN-KERNEL CACHE OBJECT REPRESENTATION AND MANAGEMENT ==================================================== ============== REPRESENTATION ============== FS-Cache maintains an in-kernel representation of each object that a netfs is currently interested in. Such objects are represented by the fscache_cookie struct and are referred to as cookies. FS-Cache also maintains a separate in-kernel representation of the objects that a cache backend is currently actively caching. Such objects are represented by the fscache_object struct. The cache backends allocate these upon request, and are expected to embed them in their own representations. These are referred to as objects. There is a 1:N relationship between cookies and objects. A cookie may be represented by multiple objects - an index may exist in more than one cache - or even by no objects (it may not be cached). Furthermore, both cookies and objects are hierarchical. The two hierarchies correspond, but the cookies tree is a superset of the union of the object trees of multiple caches: NETFS INDEX TREE : CACHE 1 : CACHE 2 : : : +-----------+ : +----------->| IObject | : +-----------+ | : +-----------+ : | ICookie |-------+ : | : +-----------+ | : | : +-----------+ | +------------------------------>| IObject | | : | : +-----------+ | : V : | | : +-----------+ : | V +----------->| IObject | : | +-----------+ | : +-----------+ : | | ICookie |-------+ : | : V +-----------+ | : | : +-----------+ | +------------------------------>| IObject | +-----+-----+ : | : +-----------+ | | : | : | V | : V : | +-----------+ | : +-----------+ : | | ICookie |------------------------->| IObject | : | +-----------+ | : +-----------+ : | | V : | : V | +-----------+ : | : +-----------+ | | ICookie |-------------------------------->| IObject | | +-----------+ : | : +-----------+ V | : V : | +-----------+ | : +-----------+ : | | DCookie |------------------------->| DObject | : | +-----------+ | : +-----------+ : | | : : | +-------+-------+ : : | | | : : | V V : : V +-----------+ +-----------+ : : +-----------+ | DCookie | | DCookie |------------------------>| DObject | +-----------+ +-----------+ : : +-----------+ : : In the above illustration, ICookie and IObject represent indices and DCookie and DObject represent data storage objects. Indices may have representation in multiple caches, but currently, non-index objects may not. Objects of any type may also be entirely unrepresented. As far as the netfs API goes, the netfs is only actually permitted to see pointers to the cookies. The cookies themselves and any objects attached to those cookies are hidden from it. =============================== OBJECT MANAGEMENT STATE MACHINE =============================== Within FS-Cache, each active object is managed by its own individual state machine. The state for an object is kept in the fscache_object struct, in object->state. A cookie may point to a set of objects that are in different states. Each state has an action associated with it that is invoked when the machine wakes up in that state. There are four logical sets of states: (1) Preparation: states that wait for the parent objects to become ready. The representations are hierarchical, and it is expected that an object must be created or accessed with respect to its parent object. (2) Initialisation: states that perform lookups in the cache and validate what's found and that create on disk any missing metadata. (3) Normal running: states that allow netfs operations on objects to proceed and that update the state of objects. (4) Termination: states that detach objects from their netfs cookies, that delete objects from disk, that handle disk and system errors and that free up in-memory resources. In most cases, transitioning between states is in response to signalled events. When a state has finished processing, it will usually set the mask of events in which it is interested (object->event_mask) and relinquish the worker thread. Then when an event is raised (by calling fscache_raise_event()), if the event is not masked, the object will be queued for processing (by calling fscache_enqueue_object()). PROVISION OF CPU TIME --------------------- The work to be done by the various states is given CPU time by the threads of the slow work facility (see Documentation/slow-work.txt). This is used in preference to the workqueue facility because: (1) Threads may be completely occupied for very long periods of time by a particular work item. These state actions may be doing sequences of synchronous, journalled disk accesses (lookup, mkdir, create, setxattr, getxattr, truncate, unlink, rmdir, rename). (2) Threads may do little actual work, but may rather spend a lot of time sleeping on I/O. This means that single-threaded and 1-per-CPU-threaded workqueues don't necessarily have the right numbers of threads. LOCKING SIMPLIFICATION ---------------------- Because only one worker thread may be operating on any particular object's state machine at once, this simplifies the locking, particularly with respect to disconnecting the netfs's representation of a cache object (fscache_cookie) from the cache backend's representation (fscache_object) - which may be requested from either end. ================= THE SET OF STATES ================= The object state machine has a set of states that it can be in. There are preparation states in which the object sets itself up and waits for its parent object to transit to a state that allows access to its children: (1) State FSCACHE_OBJECT_INIT. Initialise the object and wait for the parent object to become active. In the cache, it is expected that it will not be possible to look an object up from the parent object, until that parent object itself has been looked up. There are initialisation states in which the object sets itself up and accesses disk for the object metadata: (2) State FSCACHE_OBJECT_LOOKING_UP. Look up the object on disk, using the parent as a starting point. FS-Cache expects the cache backend to probe the cache to see whether this object is represented there, and if it is, to see if it's valid (coherency management). The cache should call fscache_object_lookup_negative() to indicate lookup failure for whatever reason, and should call fscache_obtained_object() to indicate success. At the completion of lookup, FS-Cache will let the netfs go ahead with read operations, no matter whether the file is yet cached. If not yet cached, read operations will be immediately rejected with ENODATA until the first known page is uncached - as to that point there can be no data to be read out of the cache for that file that isn't currently also held in the pagecache. (3) State FSCACHE_OBJECT_CREATING. Create an object on disk, using the parent as a starting point. This happens if the lookup failed to find the object, or if the object's coherency data indicated what's on disk is out of date. In this state, FS-Cache expects the cache to create The cache should call fscache_obtained_object() if creation completes successfully, fscache_object_lookup_negative() otherwise. At the completion of creation, FS-Cache will start processing write operations the netfs has queued for an object. If creation failed, the write ops will be transparently discarded, and nothing recorded in the cache. There are some normal running states in which the object spends its time servicing netfs requests: (4) State FSCACHE_OBJECT_AVAILABLE. A transient state in which pending operations are started, child objects are permitted to advance from FSCACHE_OBJECT_INIT state, and temporary lookup data is freed. (5) State FSCACHE_OBJECT_ACTIVE. The normal running state. In this state, requests the netfs makes will be passed on to the cache. (6) State FSCACHE_OBJECT_UPDATING. The state machine comes here to update the object in the cache from the netfs's records. This involves updating the auxiliary data that is used to maintain coherency. And there are terminal states in which an object cleans itself up, deallocates memory and potentially deletes stuff from disk: (7) State FSCACHE_OBJECT_LC_DYING. The object comes here if it is dying because of a lookup or creation error. This would be due to a disk error or system error of some sort. Temporary data is cleaned up, and the parent is released. (8) State FSCACHE_OBJECT_DYING. The object comes here if it is dying due to an error, because its parent cookie has been relinquished by the netfs or because the cache is being withdrawn. Any child objects waiting on this one are given CPU time so that they too can destroy themselves. This object waits for all its children to go away before advancing to the next state. (9) State FSCACHE_OBJECT_ABORT_INIT. The object comes to this state if it was waiting on its parent in FSCACHE_OBJECT_INIT, but its parent died. The object will destroy itself so that the parent may proceed from the FSCACHE_OBJECT_DYING state. (10) State FSCACHE_OBJECT_RELEASING. (11) State FSCACHE_OBJECT_RECYCLING. The object comes to one of these two states when dying once it is rid of all its children, if it is dying because the netfs relinquished its cookie. In the first state, the cached data is expected to persist, and in the second it will be deleted. (12) State FSCACHE_OBJECT_WITHDRAWING. The object transits to this state if the cache decides it wants to withdraw the object from service, perhaps to make space, but also due to error or just because the whole cache is being withdrawn. (13) State FSCACHE_OBJECT_DEAD. The object transits to this state when the in-memory object record is ready to be deleted. The object processor shouldn't ever see an object in this state. THE SET OF EVENTS ----------------- There are a number of events that can be raised to an object state machine: (*) FSCACHE_OBJECT_EV_UPDATE The netfs requested that an object be updated. The state machine will ask the cache backend to update the object, and the cache backend will ask the netfs for details of the change through its cookie definition ops. (*) FSCACHE_OBJECT_EV_CLEARED This is signalled in two circumstances: (a) when an object's last child object is dropped and (b) when the last operation outstanding on an object is completed. This is used to proceed from the dying state. (*) FSCACHE_OBJECT_EV_ERROR This is signalled when an I/O error occurs during the processing of some object. (*) FSCACHE_OBJECT_EV_RELEASE (*) FSCACHE_OBJECT_EV_RETIRE These are signalled when the netfs relinquishes a cookie it was using. The event selected depends on whether the netfs asks for the backing object to be retired (deleted) or retained. (*) FSCACHE_OBJECT_EV_WITHDRAW This is signalled when the cache backend wants to withdraw an object. This means that the object will have to be detached from the netfs's cookie. Because the withdrawing releasing/retiring events are all handled by the object state machine, it doesn't matter if there's a collision with both ends trying to sever the connection at the same time. The state machine can just pick which one it wants to honour, and that effects the other. Signed-off-by: David Howells <[email protected]> Acked-by: Steve Dickson <[email protected]> Acked-by: Trond Myklebust <[email protected]> Acked-by: Al Viro <[email protected]> Tested-by: Daire Byrne <[email protected]>
1 parent 2868cbe commit 36c9559

File tree

5 files changed

+1155
-2
lines changed

5 files changed

+1155
-2
lines changed

‎Documentation/filesystems/caching/fscache.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,11 @@ The cache backend API to FS-Cache can be found in:
188188

189189
Documentation/filesystems/caching/backend-api.txt
190190

191+
A description of the internal representations and object state machine can be
192+
found in:
193+
194+
Documentation/filesystems/caching/object.txt
195+
191196

192197
=======================
193198
STATISTICAL INFORMATION

‎Documentation/filesystems/caching/object.txt

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

‎fs/fscache/Makefile

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ fscache-y := \
77
cookie.o \
88
fsdef.o \
99
main.o \
10-
netfs.o
10+
netfs.o \
11+
object.o
1112

1213
fscache-$(CONFIG_PROC_FS) += proc.o
1314
fscache-$(CONFIG_FSCACHE_STATS) += stats.o

‎fs/fscache/internal.h

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,18 @@ extern struct kobject *fscache_root;
8585
extern int fscache_wait_bit(void *);
8686
extern int fscache_wait_bit_interruptible(void *);
8787

88+
/*
89+
* fsc-object.c
90+
*/
91+
extern void fscache_withdrawing_object(struct fscache_cache *,
92+
struct fscache_object *);
93+
extern void fscache_enqueue_object(struct fscache_object *);
94+
95+
/*
96+
* fsc-operation.c
97+
*/
98+
#define fscache_start_operations(obj) BUG()
99+
88100
/*
89101
* fsc-proc.c
90102
*/
@@ -196,7 +208,19 @@ extern const struct file_operations fscache_stats_fops;
196208
static inline void fscache_raise_event(struct fscache_object *object,
197209
unsigned event)
198210
{
199-
BUG(); // TODO
211+
if (!test_and_set_bit(event, &object->events) &&
212+
test_bit(event, &object->event_mask))
213+
fscache_enqueue_object(object);
214+
}
215+
216+
/*
217+
* drop a reference to a cookie
218+
*/
219+
static inline void fscache_cookie_put(struct fscache_cookie *cookie)
220+
{
221+
BUG_ON(atomic_read(&cookie->usage) <= 0);
222+
if (atomic_dec_and_test(&cookie->usage))
223+
__fscache_cookie_put(cookie);
200224
}
201225

202226
/*****************************************************************************/

0 commit comments

Comments
 (0)