1.1 --- a/docs/wiki/Mechanisms Fri Mar 25 01:42:15 2022 +0100
1.2 +++ b/docs/wiki/Mechanisms Sat Mar 26 23:20:28 2022 +0100
1.3 @@ -60,20 +60,25 @@
1.4
1.5 ########
1.6
1.7 +This document uses C-style interface syntax since the components operating
1.8 +within the described mechanisms will themselves be described using such
1.9 +syntax.
1.10 +
1.11 == Accountable ==
1.12
1.13 This interface provides the following operations:
1.14
1.15 {{{
1.16 -attach()
1.17 -detach(out unsigned int count)
1.18 +void attach()
1.19 +unsigned int detach()
1.20 }}}
1.21
1.22 Its purpose is to provide reference counting for components, with the `attach`
1.23 operation incrementing the number of users of a component, and with the
1.24 -`detach` operation decrementing the number of users. When components no longer
1.25 -have any attached users, they may perform operations to tidy up after
1.26 -themselves and permit their deallocation.
1.27 +`detach` operation decrementing the number of users and returning the
1.28 +resulting number of users. When components no longer have any attached users,
1.29 +they may perform operations to tidy up after themselves and permit their
1.30 +deallocation.
1.31
1.32 == Accessors ==
1.33
1.34 @@ -92,11 +97,11 @@
1.35 File content is accessed through an interface with the following operations:
1.36
1.37 {{{
1.38 -close()
1.39 -fill(inout Flexpage flexpage)
1.40 -flush(inout Flexpage flexpage)
1.41 -get_size(out offset_t size)
1.42 -set_size(in offset_t size)
1.43 +void close()
1.44 +void fill(Flexpage *flexpage)
1.45 +void flush(Flexpage *flexpage)
1.46 +offset_t get_size()
1.47 +void set_size(offset_t size)
1.48 }}}
1.49
1.50 The operations need to be supported with actual filesystem operations. For
1.51 @@ -112,15 +117,47 @@
1.52 The following operations are supported by providers:
1.53
1.54 {{{
1.55 -registry(out ProviderRegistry *registry)
1.56 -make_resource(out offset_t size, out object_flags_t object_flags, out Resource *resource)
1.57 +ProviderRegistry *registry()
1.58 +long make_resource(offset_t *size, object_flags_t *object_flags, Resource **resource)
1.59 +bool removal_pending()
1.60 +void remove()
1.61 +void remove_pending(bool remove)
1.62 }}}
1.63
1.64 Providers are associated with filesystem objects in a registry which can be
1.65 -obtained from each provider.
1.66 +obtained from each provider using the `registry` operation.
1.67
1.68 Providers also support the creation of resources through which each user of a
1.69 -provider exercises its use of that provider.
1.70 +provider exercises its use of that provider. The `make_resource` operation
1.71 +performs the creation and returns size, flags and resource instance details.
1.72 +
1.73 +The removal of providers can be directed using the `remove_pending` and
1.74 +`remove` operations. Where `remove_pending` has been called with a true value
1.75 +as its parameter, the `removal_pending` operation will also return a true
1.76 +value, and upon the provider being discarded, the `remove` operation will be
1.77 +invoked. The `remove` operation performs the appropriate underlying operation
1.78 +to remove the object being provided.
1.79 +
1.80 +Typically, removal of providers is managed by the provider registry when
1.81 +resources are closed and detached from providers.
1.82 +
1.83 +######## A graph showing the removal mechanism
1.84 +
1.85 +{{{#!graphviz
1.86 +#format svg
1.87 +#transform notugly
1.88 +digraph provider_removal {
1.89 + node [fontsize="12.0",fontname="sans-serif",shape=box];
1.90 + edge [fontsize="12.0",fontname="sans-serif"];
1.91 + rankdir=LR;
1.92 +
1.93 + ResourceServer -> Resource [label="close"];
1.94 + Resource -> ProviderRegistry [label="detach"];
1.95 + ProviderRegistry -> Provider [label="remove"];
1.96 +}
1.97 +}}}
1.98 +
1.99 +########
1.100
1.101 == Resources ==
1.102
1.103 @@ -130,8 +167,8 @@
1.104 The base interface of a resource is as follows:
1.105
1.106 {{{
1.107 -activate()
1.108 -close()
1.109 +void activate()
1.110 +void close()
1.111 }}}
1.112
1.113 Activation of a resource is an optional operation that performs any