1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/wiki/ClientLibrary Sat Aug 28 00:28:17 2021 +0200
1.3 @@ -0,0 +1,146 @@
1.4 += Client Library =
1.5 +
1.6 +The filesystem client library offers abstractions and a number of layers of
1.7 +functionality to support interaction with [[Components|components]] and the
1.8 +provision of higher-level mechanisms and abstractions for file access.
1.9 +
1.10 +<<TableOfContents(2,3)>>
1.11 +
1.12 +== File Data Structures ==
1.13 +
1.14 +Since files are accessed using file references, the `file_t` data structure is
1.15 +used to wrap such references and other relevant state. Thus, such structures
1.16 +can be broadly regarded as similar to the traditional `FILE` data structure.
1.17 +
1.18 +The fields of the `file_t` data structure are as follows:
1.19 +
1.20 +|| '''Field''' || '''Description''' ||
1.21 +|| `memory` || The memory address of the exposed file region ||
1.22 +|| `start_pos` || The start position of the region in the file ||
1.23 +|| `end_pos` || The end position of the region in the file ||
1.24 +|| `data_end` || The amount or extent of populated data in the region ||
1.25 +|| `data_current` || The offset used to track client position in the region ||
1.26 +|| `size` || The total size of the file ||
1.27 +|| `object_flags` || Flags indicating support for certain file features ||
1.28 +|| `can_block` || Notification flags for blocking access to the file ||
1.29 +|| `notifications`|| Notification flags set for the file ||
1.30 +
1.31 +== Client Programming Interface ==
1.32 +
1.33 +The client programming interface provides functions somewhat resembling the
1.34 +traditional C library and low-level Unix interfaces for file access, and these
1.35 +functions are intended to support such traditional interfaces.
1.36 +
1.37 +=== Files ===
1.38 +
1.39 +Files are opened and closed using the following functions:
1.40 +
1.41 +{{{
1.42 +file_t *client_open(const char *name, flags_t flags);
1.43 +}}}
1.44 +
1.45 +Each file endpoint may be closed using `client_close`.
1.46 +
1.47 +=== Pipes ===
1.48 +
1.49 +Pipes are opened using a special function:
1.50 +
1.51 +{{{
1.52 +long client_pipe(file_t **reader, file_t **writer, flags_t flags);
1.53 +}}}
1.54 +
1.55 +Each pipe endpoint may be closed using `client_close`.
1.56 +
1.57 +=== Closing Files and Pipes ===
1.58 +
1.59 +Closing files and pipes involves a common operation:
1.60 +
1.61 +{{{
1.62 +void client_close(file_t *file);
1.63 +}}}
1.64 +
1.65 +When client programs terminate, the freeing of their object capabilities
1.66 +should cause the closure of files and pipes, but programs may choose to close
1.67 +such resources explicitly.
1.68 +
1.69 +=== Reading and Writing ===
1.70 +
1.71 +Reading and writing files and pipes involves functions resembling the
1.72 +traditional low-level `read` and `write` functions:
1.73 +
1.74 +{{{
1.75 +offset_t client_read(file_t *file, void *buf, offset_t count);
1.76 +offset_t client_write(file_t *file, const void *buf, offset_t count);
1.77 +}}}
1.78 +
1.79 +=== Navigation in Files ===
1.80 +
1.81 +Support for navigation in files is provided using functions resembling the
1.82 +traditional higher-level `fseek` and `ftell` functions:
1.83 +
1.84 +{{{
1.85 +offset_t client_seek(file_t *file, offset_t offset, int whence);
1.86 +long client_tell(file_t *file);
1.87 +}}}
1.88 +
1.89 +=== Accessing Exposed Memory Regions ===
1.90 +
1.91 +Although the client library (and the provision of files) employs mapped
1.92 +memory, a function can be used to explicitly reference memory for file access:
1.93 +
1.94 +{{{
1.95 +void *client_mmap(file_t *file, offset_t position, offset_t length);
1.96 +}}}
1.97 +
1.98 +Pipes support a different mechanism for navigation involving the following
1.99 +functions:
1.100 +
1.101 +{{{
1.102 +long client_current_region(file_t *file);
1.103 +long client_next_region(file_t *file);
1.104 +}}}
1.105 +
1.106 +Such navigation functions for files and pipes do not need to be used where the
1.107 +higher-level reading, writing and seeking functions are in use.
1.108 +
1.109 +=== Flushing and Synchronisation ===
1.110 +
1.111 +For synchronisation purposes, either with the filesystem itself or with other
1.112 +users of the filesystem, a function resembling the traditional `fflush`
1.113 +function is provided:
1.114 +
1.115 +{{{
1.116 +long client_flush(file_t *file);
1.117 +}}}
1.118 +
1.119 +This updates the file data structure with new details of the file size, also
1.120 +updating any altered details of the extent of the data in the currently
1.121 +accessed region of the file.
1.122 +
1.123 +=== Notifications ===
1.124 +
1.125 +Since files and pipes may be accessed by multiple clients, necessarily for any
1.126 +sensible use of the latter, notifications can be configured to communicate a
1.127 +change in state to other users of these resources when they are accessed.
1.128 +
1.129 +Notification types are specified using values encoding a number of flags, and
1.130 +the following flags are available for this purpose:
1.131 +
1.132 +|| '''Flag''' || '''Notification Type''' ||
1.133 +|| `NOTIFY_CONTENT_AVAILABLE` || Content available to read ||
1.134 +|| `NOTIFY_PEER_CLOSED` || Other party has closed their endpoint ||
1.135 +|| `NOTIFY_SPACE_AVAILABLE` || Space available for writing ||
1.136 +
1.137 +=== Blocking Operations ===
1.138 +
1.139 +Reading and writing operations can be configured to block if data cannot be
1.140 +read or written respectively. The following function is provided for this
1.141 +purpose:
1.142 +
1.143 +{{{
1.144 +long client_set_blocking(file_t *file, notify_flags_t flags);
1.145 +}}}
1.146 +
1.147 +For pipes, blocking behaviour is the default and must be disabled explicitly,
1.148 +either by opening using the `O_NONBLOCK` flag or by calling
1.149 +`client_set_blocking` with no flags set.