1.1 --- a/docs/wiki/Client_Library Mon Nov 21 01:19:48 2022 +0100
1.2 +++ b/docs/wiki/Client_Library Thu Dec 01 17:55:12 2022 +0100
1.3 @@ -7,8 +7,8 @@
1.4 library, with the functions in the C library invoking client library functions
1.5 and employing client library structures internally.
1.6
1.7 -The client library is provided by `libfsclient` within the `departure`
1.8 -package.
1.9 +The client library is provided by [[Libraries#libfsclient|`libfsclient`]]
1.10 +within the `departure` package.
1.11
1.12 <<TableOfContents(2,3)>>
1.13
1.14 @@ -28,7 +28,7 @@
1.15
1.16 The members of the `file_t` data structure are as follows:
1.17
1.18 -|| '''Field''' || '''Description''' ||
1.19 +|| '''Member''' || '''Description''' ||
1.20 || `ref` || A reference to the component providing file content ||
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 @@ -203,18 +203,74 @@
1.24
1.25 === Notifications ===
1.26
1.27 -Since files and pipes may be accessed by multiple clients, necessarily for any
1.28 -sensible use of the latter, notifications can be configured to communicate a
1.29 -change in state to other users of these resources when they are accessed.
1.30 +Since files and pipes may be accessed by multiple clients, this being of
1.31 +particular significance for any real use of pipes, notifications can be
1.32 +configured to communicate a change in state to other users of these resources
1.33 +when they are accessed. Directories can also be monitored using notifications.
1.34
1.35 Notification types are specified using values encoding a number of flags, and
1.36 the following flags are available for this purpose:
1.37
1.38 || '''Flag''' || '''Notification Type''' ||
1.39 || `NOTIFY_CONTENT_AVAILABLE` || Content available to read ||
1.40 +|| `NOTIFY_FILE_OPENED` || File opened in directory ||
1.41 || `NOTIFY_PEER_CLOSED` || Other party has closed their endpoint ||
1.42 || `NOTIFY_SPACE_AVAILABLE` || Space available for writing ||
1.43
1.44 +The delivery of notifications is requested by subscribing to notifications for
1.45 +a given resource via a notifier object:
1.46 +
1.47 +{{{
1.48 +long client_subscribe(file_t *file, notify_flags_t flags, file_notifier_t *notifier);
1.49 +}}}
1.50 +
1.51 +A notifier object can be common throughout all threads in a task, being
1.52 +obtained using the following function:
1.53 +
1.54 +{{{
1.55 +file_notifier_t *client_notifier_task();
1.56 +}}}
1.57 +
1.58 +Alternatively, a local notifier can be created for use within a thread:
1.59 +
1.60 +{{{
1.61 +file_notifier_t *client_notifier_local();
1.62 +}}}
1.63 +
1.64 +Local notifiers must be closed when they are no longer needed:
1.65 +
1.66 +{{{
1.67 +void client_notifier_close(file_notifier_t *notifier);
1.68 +}}}
1.69 +
1.70 +When notifications are no longer needed, an unsubscribe operation can be
1.71 +invoked:
1.72 +
1.73 +{{{
1.74 +long client_unsubscribe(file_t *file, file_notifier_t *notifier);
1.75 +}}}
1.76 +
1.77 +==== Example ====
1.78 +
1.79 +{{{
1.80 +file_notifier_t *notifier = client_notifier_local();
1.81 +file_t *directory = client_open(filename, O_DIRECTORY);
1.82 +
1.83 +if (client_opened(directory))
1.84 +{
1.85 + if (!client_subscribe(directory, NOTIFY_FILE_OPENED, notifier))
1.86 + {
1.87 + if (!client_wait_file(directory, notifier))
1.88 + {
1.89 + /* File opened in directory. */
1.90 + }
1.91 + }
1.92 +}
1.93 +
1.94 +client_close(directory);
1.95 +client_notifier_close(notifier);
1.96 +}}}
1.97 +
1.98 === Blocking Operations ===
1.99
1.100 Reading and writing operations can be configured to block if data cannot be
1.101 @@ -228,3 +284,12 @@
1.102 For pipes, blocking behaviour is the default and must be disabled explicitly,
1.103 either by opening using the `O_NONBLOCK` flag or by calling
1.104 `client_set_blocking` with no flags set.
1.105 +
1.106 +Blocking behaviour is supported using the notification functionality. When
1.107 +access to a file or pipe cannot be satisfied for a particular operation, such
1.108 +as reading not being able to yield more content or writing not being able to
1.109 +submit more content, the task-level notifier will be used to wait for
1.110 +notifications applicable to the file or pipe involved. Consequently, the
1.111 +access will effectively block until notifications are delivered indicating
1.112 +that the state of the file or pipe has changed, and until it is determined
1.113 +that the change of state will allow the operation to proceed successfully.