1.1 --- a/docs/wiki/Filesystems Tue Jan 04 23:43:56 2022 +0100
1.2 +++ b/docs/wiki/Filesystems Fri Jan 07 23:49:06 2022 +0100
1.3 @@ -5,6 +5,6 @@
1.4
1.5 == Topics ==
1.6
1.7 - * [[Components]]
1.8 + * [[Components]] and [[Mechanisms]]
1.9 * [[ClientLibrary|Client Library]]
1.10 * [[Users]]
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/wiki/Mechanisms Fri Jan 07 23:49:06 2022 +0100
2.3 @@ -0,0 +1,208 @@
2.4 += Mechanisms =
2.5 +
2.6 +Within the filesystem server library, a number of different abstractions and
2.7 +mechanisms are employed to provide access to filesystem objects.
2.8 +
2.9 +<<TableOfContents(2,3)>>
2.10 +
2.11 +The abstractions or components used in the library are organised as follows.
2.12 +
2.13 +######## A graph showing the relationships between library components
2.14 +
2.15 +{{{#!graphviz
2.16 +#format svg
2.17 +#transform notugly
2.18 +digraph components {
2.19 + node [fontsize="12.0",fontname="sans-serif",shape=box];
2.20 + edge [fontsize="12.0",fontname="sans-serif"];
2.21 + rankdir=LR;
2.22 +
2.23 + subgraph {
2.24 + rank=same;
2.25 +
2.26 + Resource -> DirectoryResource -> FilePager
2.27 + [dir=none,style=dotted];
2.28 + }
2.29 +
2.30 + subgraph {
2.31 + rank=same;
2.32 +
2.33 + Provider -> DirectoryProvider -> FileProvider
2.34 + [dir=none,style=dotted];
2.35 + }
2.36 +
2.37 + subgraph {
2.38 + rank=same;
2.39 +
2.40 + Accessor -> Ext2FileAccessor
2.41 + [dir=none,style=dotted];
2.42 + }
2.43 +
2.44 + subgraph {
2.45 + rank=same;
2.46 +
2.47 + DirectoryAccessor -> Ext2DirectoryAccessor
2.48 + [dir=none,style=dotted];
2.49 + }
2.50 +
2.51 + subgraph {
2.52 + node [shape=ellipse];
2.53 + rank=same;
2.54 +
2.55 + Directory [label="dir"];
2.56 + File [label="dir/file"];
2.57 + }
2.58 +
2.59 + DirectoryResource -> DirectoryProvider -> Ext2DirectoryAccessor -> Directory;
2.60 + FilePager -> FileProvider -> Ext2FileAccessor -> File;
2.61 +}
2.62 +}}}
2.63 +
2.64 +########
2.65 +
2.66 +== Accountable ==
2.67 +
2.68 +This interface provides the following operations:
2.69 +
2.70 +{{{
2.71 +attach()
2.72 +detach(out unsigned int count)
2.73 +}}}
2.74 +
2.75 +Its purpose is to provide reference counting for components, with the `attach`
2.76 +operation incrementing the number of users of a component, and with the
2.77 +`detach` operation decrementing the number of users. When components no longer
2.78 +have any attached users, they may perform operations to tidy up after
2.79 +themselves and permit their deallocation.
2.80 +
2.81 +== Accessors ==
2.82 +
2.83 +Accessors provide the means of accessing filesystem object data and metadata.
2.84 +Conceptually, files and directories are both exposed by accessors, although
2.85 +the interfaces and mechanisms may differ between these types of objects.
2.86 +
2.87 +=== Directory Accessors ===
2.88 +
2.89 +Currently, directory accessors provide support for traversing directory
2.90 +listings, obtaining the relevant filesystem metadata using the underlying
2.91 +filesystem access library.
2.92 +
2.93 +=== File Accessors ===
2.94 +
2.95 +File content is accessed through an interface with the following operations:
2.96 +
2.97 +{{{
2.98 +close()
2.99 +fill(inout Flexpage flexpage)
2.100 +flush(inout Flexpage flexpage)
2.101 +get_size(out offset_t size)
2.102 +set_size(in offset_t size)
2.103 +}}}
2.104 +
2.105 +The operations need to be supported with actual filesystem operations. For
2.106 +example, ext2-based filesystems employ a specific abstraction which invokes
2.107 +library functions provided by the `libext2fs` package.
2.108 +
2.109 +== Providers ==
2.110 +
2.111 +Providers encapsulate the essential functionality for accessing filesystem
2.112 +objects. Implementing the `Accountable` interface, they are shared by
2.113 +resources and discarded when no resources are using them.
2.114 +
2.115 +The following operations are supported by providers:
2.116 +
2.117 +{{{
2.118 +registry(out ProviderRegistry *registry)
2.119 +make_resource(out offset_t size, out object_flags_t object_flags, out Resource *resource)
2.120 +}}}
2.121 +
2.122 +Providers are associated with filesystem objects in a registry which can be
2.123 +obtained from each provider.
2.124 +
2.125 +Providers also support the creation of resources through which each user of a
2.126 +provider exercises its use of that provider.
2.127 +
2.128 +== Resources ==
2.129 +
2.130 +Resources allow each user of a filesystem object to access that object
2.131 +independently. They effectively provide a session in which accesses may occur.
2.132 +
2.133 +The base interface of a resource is as follows:
2.134 +
2.135 +{{{
2.136 +activate()
2.137 +close()
2.138 +}}}
2.139 +
2.140 +Activation of a resource is an optional operation that performs any
2.141 +initialisation before a resource is made available to its user.
2.142 +
2.143 +In practice, other operations are required to make resources useful.
2.144 +
2.145 +=== Directory Resources ===
2.146 +
2.147 +Directory resources primarily expose the contents of directories in the
2.148 +filesystem. They employ directory accessors which concern themselves with the
2.149 +actual filesystem content.
2.150 +
2.151 +[[Components#Directories|Directory components]] are provided using directory
2.152 +resources.
2.153 +
2.154 +=== Pagers ===
2.155 +
2.156 +Pagers are resources that support dataspace access operations, thus allowing
2.157 +the resources to expose filesystem content in mapped memory regions.
2.158 +
2.159 +[[Components#Files|File components]] and [[Components#Pipes|pipe components]]
2.160 +are provided using pagers.
2.161 +
2.162 +== Registries ==
2.163 +
2.164 +The basic mechanism for obtaining a resource involves a registry, as
2.165 +illustrated by the following diagram.
2.166 +
2.167 +######## A graph showing the use of a registry in obtaining resources
2.168 +
2.169 +{{{#!graphviz
2.170 +#format svg
2.171 +#transform notugly
2.172 +digraph registry {
2.173 + node [fontsize="12.0",fontname="sans-serif",shape=box];
2.174 + edge [fontsize="12.0",fontname="sans-serif"];
2.175 + rankdir=LR;
2.176 +
2.177 + subgraph {
2.178 + node [label="OpenerContextResource"];
2.179 + rank=same;
2.180 +
2.181 + OpenerContextResource1 -> OpenerContextResource2 [dir=none,style=dotted];
2.182 + }
2.183 +
2.184 + subgraph {
2.185 + node [label="OpenerResource"];
2.186 + rank=same;
2.187 +
2.188 + OpenerResource1 -> OpenerResource2 [dir=none,style=dotted];
2.189 + }
2.190 +
2.191 + subgraph {
2.192 + rank=same;
2.193 +
2.194 + ResourceRegistry -> Resource;
2.195 + }
2.196 +
2.197 + subgraph {
2.198 + rank=same;
2.199 +
2.200 + ProviderRegistry -> Provider;
2.201 + }
2.202 +
2.203 + OpenerContextResource1 -> OpenerResource1 [label="open"];
2.204 + OpenerResource1 -> ResourceRegistry [label="get_resource"];
2.205 + ResourceRegistry -> ProviderRegistry [label="get/set"];
2.206 +
2.207 + Provider -> Resource -> OpenerResource2 -> OpenerContextResource2;
2.208 +}
2.209 +}}}
2.210 +
2.211 +########