paul@183 | 1 | = Components = |
paul@142 | 2 | |
paul@142 | 3 | Access to files is provided by a number of programs acting as components. For |
paul@183 | 4 | convenience, the component-level operations are wrapped up in a |
paul@183 | 5 | [[ClientLibrary|client library]] that aims to provide simpler, more familiar |
paul@183 | 6 | mechanisms for opening, reading, writing, and closing files, together with |
paul@183 | 7 | various other operations. |
paul@142 | 8 | |
paul@427 | 9 | Components are provided by functionality in `libfsserver` used by programs |
paul@427 | 10 | found in the `servers` directory within the `departure` package. |
paul@427 | 11 | |
paul@142 | 12 | <<TableOfContents(2,3)>> |
paul@142 | 13 | |
paul@183 | 14 | Components are accessed via interfaces defined using the interface description |
paul@183 | 15 | language supported by the ``idl4re`` tool. Interface operations in this |
paul@183 | 16 | document are described using excerpts from the appropriate interface |
paul@183 | 17 | descriptions. |
paul@183 | 18 | |
paul@190 | 19 | == Overview == |
paul@190 | 20 | |
paul@217 | 21 | An overview of the component interactions involved in opening a file or |
paul@217 | 22 | directory is provided by the diagram below. |
paul@190 | 23 | |
paul@183 | 24 | ######## A graph showing the interactions between components |
paul@183 | 25 | |
paul@183 | 26 | {{{#!graphviz |
paul@183 | 27 | #format svg |
paul@183 | 28 | #transform notugly |
paul@183 | 29 | digraph components { |
paul@183 | 30 | node [fontsize="12.0",fontname="sans-serif",shape=box]; |
paul@183 | 31 | edge [fontsize="12.0",fontname="sans-serif"]; |
paul@183 | 32 | rankdir=LR; |
paul@183 | 33 | |
paul@183 | 34 | subgraph { |
paul@217 | 35 | node [label="Client"]; |
paul@183 | 36 | rank=min; |
paul@183 | 37 | |
paul@188 | 38 | Client1; Client2; Client3; Client4; Client5; Client6; Client7; |
paul@188 | 39 | } |
paul@183 | 40 | |
paul@188 | 41 | subgraph { |
paul@188 | 42 | rank=same; |
paul@217 | 43 | |
paul@188 | 44 | Memory [label="filename",shape=note]; |
paul@183 | 45 | } |
paul@183 | 46 | |
paul@183 | 47 | subgraph { |
paul@217 | 48 | rank=max; |
paul@217 | 49 | |
paul@183 | 50 | Filesystem; |
paul@142 | 51 | |
paul@183 | 52 | subgraph { |
paul@183 | 53 | node [label="Opener\n(user)"]; |
paul@183 | 54 | Opener1; Opener2; |
paul@183 | 55 | } |
paul@183 | 56 | |
paul@183 | 57 | subgraph { |
paul@183 | 58 | node [label="OpenerContext"]; |
paul@188 | 59 | OpenerContext1; OpenerContext2; OpenerContext3; |
paul@183 | 60 | } |
paul@183 | 61 | |
paul@217 | 62 | Object [label="MappedFile\nor\nDirectory"]; |
paul@183 | 63 | } |
paul@183 | 64 | |
paul@381 | 65 | Client1 -> Client2 -> Client3 -> Client4 -> Client5 -> Client6 -> Client7 [dir=none,style=dotted]; |
paul@381 | 66 | Opener1 -> Opener2 [dir=none,style=dotted]; |
paul@381 | 67 | OpenerContext1 -> OpenerContext2 -> OpenerContext3 [dir=none,style=dotted]; |
paul@142 | 68 | |
paul@183 | 69 | Client1 -> Filesystem [label="open_for_user(user)"]; |
paul@183 | 70 | Filesystem -> Opener1; |
paul@188 | 71 | Opener1 -> Client2; |
paul@183 | 72 | |
paul@183 | 73 | Client3 -> Opener2 [label="context()"]; |
paul@183 | 74 | Opener2 -> OpenerContext1; |
paul@188 | 75 | OpenerContext1 -> Client4; |
paul@188 | 76 | |
paul@188 | 77 | Client5 -> Memory -> OpenerContext2; |
paul@183 | 78 | |
paul@188 | 79 | Client6 -> OpenerContext3 [label="open(flags, ...)"]; |
paul@217 | 80 | OpenerContext3 -> Object; |
paul@217 | 81 | Object -> Client7; |
paul@183 | 82 | } |
paul@183 | 83 | }}} |
paul@183 | 84 | |
paul@183 | 85 | ######## |
paul@183 | 86 | |
paul@190 | 87 | In pseudocode, the operations as conducted by the client program are as |
paul@190 | 88 | follows: |
paul@190 | 89 | |
paul@190 | 90 | {{{ |
paul@190 | 91 | opener = filesystem.open_for_user(user) |
paul@190 | 92 | context = opener.context() |
paul@190 | 93 | context.write("filename") # this being a memory access operation |
paul@190 | 94 | file = context.open(flags, ...) |
paul@190 | 95 | }}} |
paul@190 | 96 | |
paul@217 | 97 | Reading from an opened directory is achieved as shown in the following |
paul@217 | 98 | diagram. |
paul@217 | 99 | |
paul@217 | 100 | ######## A graph showing the interactions between components |
paul@217 | 101 | |
paul@217 | 102 | {{{#!graphviz |
paul@217 | 103 | #format svg |
paul@217 | 104 | #transform notugly |
paul@217 | 105 | digraph components { |
paul@217 | 106 | node [fontsize="12.0",fontname="sans-serif",shape=box]; |
paul@217 | 107 | edge [fontsize="12.0",fontname="sans-serif"]; |
paul@217 | 108 | rankdir=LR; |
paul@217 | 109 | |
paul@217 | 110 | subgraph { |
paul@217 | 111 | node [label="Client"]; |
paul@217 | 112 | rank=min; |
paul@217 | 113 | |
paul@217 | 114 | Client1; Client2; Client3; Client4; |
paul@217 | 115 | } |
paul@217 | 116 | |
paul@217 | 117 | subgraph { |
paul@217 | 118 | rank=same; |
paul@217 | 119 | |
paul@217 | 120 | Memory [label="entries",shape=note]; |
paul@217 | 121 | } |
paul@217 | 122 | |
paul@217 | 123 | subgraph { |
paul@217 | 124 | rank=max; |
paul@217 | 125 | |
paul@217 | 126 | Directory; |
paul@217 | 127 | |
paul@217 | 128 | subgraph { |
paul@217 | 129 | node [label="Reader"]; |
paul@217 | 130 | |
paul@217 | 131 | Reader1; Reader2; Reader3; |
paul@217 | 132 | } |
paul@217 | 133 | } |
paul@217 | 134 | |
paul@381 | 135 | Client1 -> Client2 -> Client3 -> Client4 [dir=none,style=dotted]; |
paul@381 | 136 | Reader1 -> Reader2 -> Reader3 [dir=none,style=dotted]; |
paul@217 | 137 | |
paul@217 | 138 | Client1 -> Directory [label="opendir()"]; |
paul@217 | 139 | Directory -> Reader1; |
paul@217 | 140 | Reader1 -> Client2; |
paul@217 | 141 | |
paul@217 | 142 | Client3 -> Reader2 [label="current_region()"]; |
paul@217 | 143 | Reader3 -> Memory -> Client4; |
paul@217 | 144 | } |
paul@217 | 145 | }}} |
paul@217 | 146 | |
paul@217 | 147 | ######## |
paul@217 | 148 | |
paul@217 | 149 | In pseudocode, the operations as conducted by the client program are as |
paul@217 | 150 | follows: |
paul@217 | 151 | |
paul@217 | 152 | {{{ |
paul@217 | 153 | reader = directory.opendir() |
paul@217 | 154 | reader.current_region() |
paul@217 | 155 | entries = reader.read() # this being a memory access operation |
paul@217 | 156 | }}} |
paul@217 | 157 | |
paul@183 | 158 | == Filesystems == |
paul@142 | 159 | |
paul@144 | 160 | Filesystems implement the `Filesystem` interface which provides the |
paul@144 | 161 | `open_for_user` operation: |
paul@144 | 162 | |
paul@144 | 163 | {{{ |
paul@172 | 164 | open_for_user(in user_t user, out cap opener) |
paul@144 | 165 | }}} |
paul@144 | 166 | |
paul@183 | 167 | The operation yields a file opener appropriate for the given [[Users|user]] |
paul@183 | 168 | credentials. |
paul@144 | 169 | |
paul@427 | 170 | ((Openers)) |
paul@398 | 171 | == File and Directory Openers == |
paul@144 | 172 | |
paul@427 | 173 | Openers implement the `Opener` interface which provides the `context` |
paul@142 | 174 | operation: |
paul@142 | 175 | |
paul@142 | 176 | {{{ |
paul@142 | 177 | context(out cap context) |
paul@142 | 178 | }}} |
paul@142 | 179 | |
paul@142 | 180 | Each client program, task or thread obtains its own context because it will |
paul@142 | 181 | need its own dedicated channel for communication with the filesystem. |
paul@142 | 182 | |
paul@183 | 183 | == Opener Contexts == |
paul@142 | 184 | |
paul@183 | 185 | An opener context acts as a dataspace, meaning that it can be attached to a |
paul@183 | 186 | task using a region manager and provide a buffer via a region of mapped memory |
paul@183 | 187 | that the task can write to. In the case of a context, the task will write a |
paul@183 | 188 | filesystem path indicating the file to be opened. |
paul@142 | 189 | |
paul@142 | 190 | Each context allows a client program to request access to individual files via |
paul@142 | 191 | operations provided by the `OpenerContext` interface, of which the most |
paul@142 | 192 | pertinent is the `open` operation: |
paul@142 | 193 | |
paul@142 | 194 | {{{ |
paul@172 | 195 | open(in flags_t flags, out offset_t size, out cap file, |
paul@172 | 196 | out object_flags_t object_flags) |
paul@142 | 197 | }}} |
paul@142 | 198 | |
paul@142 | 199 | Using the path information written to the context's memory region, the `open` |
paul@172 | 200 | operation will obtain a reference to a file-like object whose characteristics |
paul@172 | 201 | are described by the accompanying `object_flags`, these helping the client to |
paul@172 | 202 | distinguish between files that support arbitrary memory mapping operations and |
paul@172 | 203 | pipes that mandate sequential region-by-region access. |
paul@172 | 204 | |
paul@172 | 205 | Alongside regular files, directories may also be opened. Reading from them |
paul@172 | 206 | yields a listing of directory entries. |
paul@142 | 207 | |
paul@270 | 208 | === Removing === |
paul@270 | 209 | |
paul@270 | 210 | Filesystem objects are removed by invoking the `remove` operation on an opener |
paul@270 | 211 | context: |
paul@270 | 212 | |
paul@270 | 213 | {{{ |
paul@270 | 214 | remove() |
paul@270 | 215 | }}} |
paul@270 | 216 | |
paul@270 | 217 | The path information identifying the object must first be written to the |
paul@270 | 218 | context's memory region. |
paul@270 | 219 | |
paul@270 | 220 | === Renaming === |
paul@270 | 221 | |
paul@270 | 222 | Filesystem objects are renamed by invoking the `rename` operation on an opener |
paul@270 | 223 | context: |
paul@270 | 224 | |
paul@270 | 225 | {{{ |
paul@270 | 226 | rename() |
paul@270 | 227 | }}} |
paul@270 | 228 | |
paul@270 | 229 | The path information of the affected object and the destination of the rename |
paul@270 | 230 | operation must first be written to the context's memory region. The |
paul@270 | 231 | destination path follows immediately after the terminating byte of the |
paul@270 | 232 | affected path. |
paul@270 | 233 | |
paul@270 | 234 | === Statistics/Metadata === |
paul@270 | 235 | |
paul@270 | 236 | Statistics or metadata for a filesystem object can be obtained by invoking the |
paul@270 | 237 | `stat` operation on an opener context: |
paul@270 | 238 | |
paul@270 | 239 | {{{ |
paul@270 | 240 | stat() |
paul@270 | 241 | }}} |
paul@270 | 242 | |
paul@270 | 243 | The path information identifying the object must first be written to the |
paul@270 | 244 | context's memory region. As a result of the invocation, a `stat` data |
paul@270 | 245 | structure will be written to the start of the memory region. |
paul@270 | 246 | |
paul@183 | 247 | == Files == |
paul@142 | 248 | |
paul@142 | 249 | Files themselves act as dataspaces, meaning that they can be attached to a |
paul@142 | 250 | task using a region manager and provide their content via a region of mapped |
paul@142 | 251 | memory. Files implement the `MappedFile` interface. |
paul@142 | 252 | |
paul@142 | 253 | Control over the region of the file provided via mapped memory occurs |
paul@142 | 254 | using the `mmap` operation: |
paul@142 | 255 | |
paul@142 | 256 | {{{ |
paul@142 | 257 | mmap(in offset_t position, in offset_t length, |
paul@359 | 258 | in offset_t start_visible, in offset_t end_visible, |
paul@142 | 259 | out offset_t start_pos, out offset_t end_pos, |
paul@142 | 260 | out offset_t size) |
paul@142 | 261 | }}} |
paul@142 | 262 | |
paul@142 | 263 | Files also implement the more general `File` interface that provides the |
paul@142 | 264 | `resize` operation: |
paul@142 | 265 | |
paul@142 | 266 | {{{ |
paul@142 | 267 | resize(inout offset_t size) |
paul@142 | 268 | }}} |
paul@142 | 269 | |
paul@142 | 270 | This allows the portion of the memory region dedicated to the file's contents |
paul@142 | 271 | to be extended. |
paul@142 | 272 | |
paul@183 | 273 | == Directories == |
paul@172 | 274 | |
paul@217 | 275 | Directories are obtained, like files, using the `open` operation. They |
paul@217 | 276 | implement the `Directory` interface. |
paul@217 | 277 | |
paul@217 | 278 | To read directory listings, the `opendir` operation is used to obtain a |
paul@217 | 279 | directory reader: |
paul@217 | 280 | |
paul@217 | 281 | {{{ |
paul@217 | 282 | opendir(out offset_t size, out cap file, out object_flags_t object_flags) |
paul@217 | 283 | }}} |
paul@217 | 284 | |
paul@217 | 285 | Directory readers are meant to be accessed like files, meaning that it should |
paul@172 | 286 | be possible to attach them to a task using a region manager and access the |
paul@172 | 287 | provided content, this being a listing of directory entries, via the mapped |
paul@172 | 288 | region. |
paul@172 | 289 | |
paul@172 | 290 | However, unlike files which may support arbitrary mapping of their contents, |
paul@172 | 291 | the provided content may be supplied by a pipe endpoint, thereby not |
paul@172 | 292 | supporting precisely the same navigation mechanisms as those supported by |
paul@172 | 293 | files. |
paul@172 | 294 | |
paul@183 | 295 | == Pipe Openers == |
paul@172 | 296 | |
paul@172 | 297 | Distinct from filesystems but potentially used by them, pipe openers provide a |
paul@172 | 298 | means of obtaining pipes, which are channels that support unidirectional |
paul@172 | 299 | communication via shared memory. |
paul@172 | 300 | |
paul@172 | 301 | Pipe openers implement the `PipeOpener` interface and support the following |
paul@172 | 302 | operation: |
paul@172 | 303 | |
paul@172 | 304 | {{{ |
paul@172 | 305 | pipe(in offset_t size, out cap reader, out cap writer) |
paul@172 | 306 | }}} |
paul@172 | 307 | |
paul@172 | 308 | The size is indicated to request pipe regions long enough for the needs of the |
paul@172 | 309 | communicating parties, with both reader and writer endpoint capabilities being |
paul@172 | 310 | returned. Such capabilities may be propagated to the eventual parties, these |
paul@172 | 311 | typically being separate tasks. |
paul@172 | 312 | |
paul@183 | 313 | == Pipes == |
paul@172 | 314 | |
paul@172 | 315 | Although not generally obtained from filesystems, pipes may be involved in |
paul@172 | 316 | providing content from some filesystem objects such as directories. However, |
paul@172 | 317 | they are also obtained directly from an appropriate pipe server providing pipe |
paul@172 | 318 | opening facilities. |
paul@172 | 319 | |
paul@172 | 320 | Pipes expose single regions of shared memory to their endpoints, with the |
paul@172 | 321 | writing endpoint populating one region while the reading endpoint accesses the |
paul@172 | 322 | other. The reading endpoint may advance to the region being written, and this |
paul@172 | 323 | will free up a new region for the writer when it has filled its region. When |
paul@172 | 324 | the writer itself advances, it permits the reader to consume all data in the |
paul@172 | 325 | fully populated region. Naturally, the reader may not advance ahead of the |
paul@172 | 326 | writer. |
paul@172 | 327 | |
paul@172 | 328 | Pipes implement the `Pipe` interface and a number of operations to support |
paul@172 | 329 | this interaction mechanism. |
paul@172 | 330 | |
paul@172 | 331 | The details of an endpoint's current region can be queried using the following |
paul@172 | 332 | operation: |
paul@172 | 333 | |
paul@172 | 334 | {{{ |
paul@172 | 335 | current_region(out offset_t populated_size, out offset_t size) |
paul@172 | 336 | }}} |
paul@172 | 337 | |
paul@172 | 338 | This provides details of the populated size (or amount of written data) in a |
paul@172 | 339 | region along with the size of the region. |
paul@172 | 340 | |
paul@172 | 341 | Navigation to the next available region of the pipe is performed using the |
paul@172 | 342 | following operation: |
paul@172 | 343 | |
paul@172 | 344 | {{{ |
paul@172 | 345 | next_region(inout offset_t populated_size, out offset_t size) |
paul@172 | 346 | }}} |
paul@172 | 347 | |
paul@172 | 348 | Here, the populated size may be specified by the writer so that the reader may |
paul@172 | 349 | query the current region's properties using the appropriate operation. |
paul@172 | 350 | |
paul@172 | 351 | The status of the pipe can be queried using the `closed` operation: |
paul@172 | 352 | |
paul@172 | 353 | {{{ |
paul@172 | 354 | closed(out int closed) |
paul@172 | 355 | }}} |
paul@172 | 356 | |
paul@172 | 357 | This indicates through a boolean-equivalent parameter whether one or both |
paul@172 | 358 | endpoints have been closed. |