Commit 67145c23 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

docs: filesystems: convert caching/object.txt to ReST 



- Add a SPDX header;
- Adjust document and section titles;
- Comment out text ToC for html/pdf output;
- Some whitespace fixes and new line breaks;
- Adjust the events list to make them look better for html output;
- Add it to filesystems/index.rst.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/49026a8ea7e714c2e0f003aa26b975b1025476b7.1588021877.git.mchehab+huawei@kernel.org


Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent ec43a27f

Documentation/filesystems/caching/fscache.txt

+1 −1
Original line number Diff line number Diff line
@@ -191,7 +191,7 @@ The cache backend API to FS-Cache can be found in: 
A description of the internal representations and object state machine can be

found in:



	Documentation/filesystems/caching/object.txt

	Documentation/filesystems/caching/object.rst





=======================

Documentation/filesystems/caching/index.rst

0 → 100644
+9 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



Filesystem Caching

==================



.. toctree::

   :maxdepth: 2



   object

Documentation/filesystems/caching/object.txt→Documentation/filesystems/caching/object.rst

+18 −25
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



====================================================

	     IN-KERNEL CACHE OBJECT REPRESENTATION AND MANAGEMENT

In-Kernel Cache Object Representation and Management

====================================================



By: David Howells <dhowells@redhat.com>



Contents:

.. Contents:



 (*) Representation
@@ -18,8 +20,7 @@ Contents: 
 (*) The set of events.





==============

REPRESENTATION

Representation

==============



FS-Cache maintains an in-kernel representation of each object that a netfs is
@@ -38,7 +39,7 @@ 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:

of multiple caches::



	    NETFS INDEX TREE               :      CACHE 1     :      CACHE 2

	                                   :                  :
@@ -89,8 +90,7 @@ pointers to the cookies. The cookies themselves and any objects attached to 
those cookies are hidden from it.





===============================

OBJECT MANAGEMENT STATE MACHINE

Object Management State Machine

===============================



Within FS-Cache, each active object is managed by its own individual state
@@ -124,7 +124,7 @@ is not masked, the object will be queued for processing (by calling 
fscache_enqueue_object()).





PROVISION OF CPU TIME

Provision of CPU Time

---------------------



The work to be done by the various states was given CPU time by the threads of
@@ -141,7 +141,7 @@ because: 
     workqueues don't necessarily have the right numbers of threads.





LOCKING SIMPLIFICATION

Locking Simplification

----------------------



Because only one worker thread may be operating on any particular object's
@@ -151,8 +151,7 @@ from the cache backend's representation (fscache_object) - which may be 
requested from either end.





=================

THE SET OF STATES

The Set of States

=================



The object state machine has a set of states that it can be in.  There are
@@ -275,19 +274,17 @@ memory and potentially deletes stuff from disk: 
     this state.





THE SET OF EVENTS

The Set of Events

-----------------



There are a number of events that can be raised to an object state machine:



 (*) FSCACHE_OBJECT_EV_UPDATE



 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



 FSCACHE_OBJECT_EV_CLEARED

     This is signalled in two circumstances:



     (a) when an object's last child object is dropped and
@@ -296,20 +293,16 @@ There are a number of events that can be raised to an object state machine: 


     This is used to proceed from the dying state.



 (*) FSCACHE_OBJECT_EV_ERROR



 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



 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



 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.

Documentation/filesystems/index.rst

+2 −0
Original line number Diff line number Diff line
@@ -25,6 +25,8 @@ algorithms work. 
   locking

   directory-locking



   caching/index



   porting



Filesystem support layers

fs/fscache/object.c

+1 −1
Original line number Diff line number Diff line
@@ -4,7 +4,7 @@ 
 * Copyright (C) 2007 Red Hat, Inc. All Rights Reserved.

 * Written by David Howells (dhowells@redhat.com)

 *

 * See Documentation/filesystems/caching/object.txt for a description of the

 * See Documentation/filesystems/caching/object.rst for a description of the

 * object state machine and the in-kernel representations.

 */