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