1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/wiki/Mechanisms Fri Jan 07 23:49:06 2022 +0100
1.3 @@ -0,0 +1,208 @@
1.4 += Mechanisms =
1.5 +
1.6 +Within the filesystem server library, a number of different abstractions and
1.7 +mechanisms are employed to provide access to filesystem objects.
1.8 +
1.9 +<<TableOfContents(2,3)>>
1.10 +
1.11 +The abstractions or components used in the library are organised as follows.
1.12 +
1.13 +######## A graph showing the relationships between library components
1.14 +
1.15 +{{{#!graphviz
1.16 +#format svg
1.17 +#transform notugly
1.18 +digraph components {
1.19 + node [fontsize="12.0",fontname="sans-serif",shape=box];
1.20 + edge [fontsize="12.0",fontname="sans-serif"];
1.21 + rankdir=LR;
1.22 +
1.23 + subgraph {
1.24 + rank=same;
1.25 +
1.26 + Resource -> DirectoryResource -> FilePager
1.27 + [dir=none,style=dotted];
1.28 + }
1.29 +
1.30 + subgraph {
1.31 + rank=same;
1.32 +
1.33 + Provider -> DirectoryProvider -> FileProvider
1.34 + [dir=none,style=dotted];
1.35 + }
1.36 +
1.37 + subgraph {
1.38 + rank=same;
1.39 +
1.40 + Accessor -> Ext2FileAccessor
1.41 + [dir=none,style=dotted];
1.42 + }
1.43 +
1.44 + subgraph {
1.45 + rank=same;
1.46 +
1.47 + DirectoryAccessor -> Ext2DirectoryAccessor
1.48 + [dir=none,style=dotted];
1.49 + }
1.50 +
1.51 + subgraph {
1.52 + node [shape=ellipse];
1.53 + rank=same;
1.54 +
1.55 + Directory [label="dir"];
1.56 + File [label="dir/file"];
1.57 + }
1.58 +
1.59 + DirectoryResource -> DirectoryProvider -> Ext2DirectoryAccessor -> Directory;
1.60 + FilePager -> FileProvider -> Ext2FileAccessor -> File;
1.61 +}
1.62 +}}}
1.63 +
1.64 +########
1.65 +
1.66 +== Accountable ==
1.67 +
1.68 +This interface provides the following operations:
1.69 +
1.70 +{{{
1.71 +attach()
1.72 +detach(out unsigned int count)
1.73 +}}}
1.74 +
1.75 +Its purpose is to provide reference counting for components, with the `attach`
1.76 +operation incrementing the number of users of a component, and with the
1.77 +`detach` operation decrementing the number of users. When components no longer
1.78 +have any attached users, they may perform operations to tidy up after
1.79 +themselves and permit their deallocation.
1.80 +
1.81 +== Accessors ==
1.82 +
1.83 +Accessors provide the means of accessing filesystem object data and metadata.
1.84 +Conceptually, files and directories are both exposed by accessors, although
1.85 +the interfaces and mechanisms may differ between these types of objects.
1.86 +
1.87 +=== Directory Accessors ===
1.88 +
1.89 +Currently, directory accessors provide support for traversing directory
1.90 +listings, obtaining the relevant filesystem metadata using the underlying
1.91 +filesystem access library.
1.92 +
1.93 +=== File Accessors ===
1.94 +
1.95 +File content is accessed through an interface with the following operations:
1.96 +
1.97 +{{{
1.98 +close()
1.99 +fill(inout Flexpage flexpage)
1.100 +flush(inout Flexpage flexpage)
1.101 +get_size(out offset_t size)
1.102 +set_size(in offset_t size)
1.103 +}}}
1.104 +
1.105 +The operations need to be supported with actual filesystem operations. For
1.106 +example, ext2-based filesystems employ a specific abstraction which invokes
1.107 +library functions provided by the `libext2fs` package.
1.108 +
1.109 +== Providers ==
1.110 +
1.111 +Providers encapsulate the essential functionality for accessing filesystem
1.112 +objects. Implementing the `Accountable` interface, they are shared by
1.113 +resources and discarded when no resources are using them.
1.114 +
1.115 +The following operations are supported by providers:
1.116 +
1.117 +{{{
1.118 +registry(out ProviderRegistry *registry)
1.119 +make_resource(out offset_t size, out object_flags_t object_flags, out Resource *resource)
1.120 +}}}
1.121 +
1.122 +Providers are associated with filesystem objects in a registry which can be
1.123 +obtained from each provider.
1.124 +
1.125 +Providers also support the creation of resources through which each user of a
1.126 +provider exercises its use of that provider.
1.127 +
1.128 +== Resources ==
1.129 +
1.130 +Resources allow each user of a filesystem object to access that object
1.131 +independently. They effectively provide a session in which accesses may occur.
1.132 +
1.133 +The base interface of a resource is as follows:
1.134 +
1.135 +{{{
1.136 +activate()
1.137 +close()
1.138 +}}}
1.139 +
1.140 +Activation of a resource is an optional operation that performs any
1.141 +initialisation before a resource is made available to its user.
1.142 +
1.143 +In practice, other operations are required to make resources useful.
1.144 +
1.145 +=== Directory Resources ===
1.146 +
1.147 +Directory resources primarily expose the contents of directories in the
1.148 +filesystem. They employ directory accessors which concern themselves with the
1.149 +actual filesystem content.
1.150 +
1.151 +[[Components#Directories|Directory components]] are provided using directory
1.152 +resources.
1.153 +
1.154 +=== Pagers ===
1.155 +
1.156 +Pagers are resources that support dataspace access operations, thus allowing
1.157 +the resources to expose filesystem content in mapped memory regions.
1.158 +
1.159 +[[Components#Files|File components]] and [[Components#Pipes|pipe components]]
1.160 +are provided using pagers.
1.161 +
1.162 +== Registries ==
1.163 +
1.164 +The basic mechanism for obtaining a resource involves a registry, as
1.165 +illustrated by the following diagram.
1.166 +
1.167 +######## A graph showing the use of a registry in obtaining resources
1.168 +
1.169 +{{{#!graphviz
1.170 +#format svg
1.171 +#transform notugly
1.172 +digraph registry {
1.173 + node [fontsize="12.0",fontname="sans-serif",shape=box];
1.174 + edge [fontsize="12.0",fontname="sans-serif"];
1.175 + rankdir=LR;
1.176 +
1.177 + subgraph {
1.178 + node [label="OpenerContextResource"];
1.179 + rank=same;
1.180 +
1.181 + OpenerContextResource1 -> OpenerContextResource2 [dir=none,style=dotted];
1.182 + }
1.183 +
1.184 + subgraph {
1.185 + node [label="OpenerResource"];
1.186 + rank=same;
1.187 +
1.188 + OpenerResource1 -> OpenerResource2 [dir=none,style=dotted];
1.189 + }
1.190 +
1.191 + subgraph {
1.192 + rank=same;
1.193 +
1.194 + ResourceRegistry -> Resource;
1.195 + }
1.196 +
1.197 + subgraph {
1.198 + rank=same;
1.199 +
1.200 + ProviderRegistry -> Provider;
1.201 + }
1.202 +
1.203 + OpenerContextResource1 -> OpenerResource1 [label="open"];
1.204 + OpenerResource1 -> ResourceRegistry [label="get_resource"];
1.205 + ResourceRegistry -> ProviderRegistry [label="get/set"];
1.206 +
1.207 + Provider -> Resource -> OpenerResource2 -> OpenerContextResource2;
1.208 +}
1.209 +}}}
1.210 +
1.211 +########