1.1 --- a/docs/wiki/Development Sat Apr 25 15:44:16 2020 +0200
1.2 +++ b/docs/wiki/Development Sat Apr 25 22:26:54 2020 +0200
1.3 @@ -271,6 +271,27 @@
1.4 * `begin_compound_output`
1.5 * `write_files`
1.6
1.7 +These functions are described in more detail with regard to the topics of
1.8 +compound and individual interfaces.
1.9 +
1.10 +Meanwhile, a selection of writer functions are employed to generate code for
1.11 +the different structures employed within interface descriptions. Since output
1.12 +may be generated for different kinds of files, the following concepts are
1.13 +employed to parameterise the output appropriately:
1.14 +
1.15 + * Component roles indicate the nature of the component employing the
1.16 + generated code: client or server
1.17 +
1.18 + * Function roles indicate the characteristics of the function being written:
1.19 + general or completion
1.20 +
1.21 + * Parameter roles indicate the context of an identifier at a location in the
1.22 + generated code: signature (formal function parameter), structure (member),
1.23 + invocation (actual function parameter)
1.24 +
1.25 +Through the use of roles, the same fundamental information can be expressed in
1.26 +different ways by the same routine.
1.27 +
1.28 === Compound Interfaces ===
1.29
1.30 The `begin_compound_output` function is called by the main program when
1.31 @@ -308,6 +329,7 @@
1.32 server [shape=folder,fillcolor="#77ff77",label="..._server.{c,cc,h}"];
1.33 interface [shape=folder,fillcolor="#77ff77",label="..._interface.h"];
1.34 interfaces [shape=folder,fillcolor="#77ff77",label="..._interfaces.h"];
1.35 + interface_type [shape=folder,fillcolor="#77ff77",label="..._interface_type.h"];
1.36 }
1.37
1.38 subgraph {
1.39 @@ -334,6 +356,7 @@
1.40
1.41 write_compound_interface -> interface;
1.42 write_compound_output -> write_include -> interfaces;
1.43 + write_include -> interface_type;
1.44 }
1.45 }}}
1.46
1.47 @@ -397,35 +420,74 @@
1.48
1.49 ######## End of graph.
1.50
1.51 -== Includes and Headers ==
1.52 +=== Includes and Headers ===
1.53 +
1.54 +The `includes.c` and `includes.h` files provide support for writing `#include`
1.55 +statements in C and C++ programs, with the `write_includes` function
1.56 +traversing an `include` structure list to emit a list of statements.
1.57 +
1.58 +=== Interface Definitions ===
1.59
1.60 - * `includes.c`
1.61 +The `interface.c` and `interface.h` files provide the
1.62 +`write_interface_definition` function which is concerned with generating a
1.63 +description of an interface in two different contexts: client and server.
1.64 +Some generated files are employed in both contexts such as the file of the
1.65 +form `<interface>_interface.h`.
1.66 +
1.67 +==== Client Definitions ====
1.68 +
1.69 +For client use, some types are defined for client programs to use in a header
1.70 +file of the form `<interface>_client.h`.
1.71 +
1.72 +C programs employ a collection of function signatures for the different
1.73 +operations provided by the interface plus a declaration of an interface object
1.74 +retaining references to those functions as members.
1.75
1.76 -== Interface Definitions ==
1.77 +C++ programs employ a class declaration containing the operations as methods
1.78 +and with internal state referencing the component providing the operations.
1.79 +
1.80 +==== Server Definitions ====
1.81 +
1.82 +For server use, some types are defined for server programs to use in a header
1.83 +file of the form `<interface>_server.h`.
1.84
1.85 - * `interface.c`
1.86 +C programs employ declarations of the interface object type whose members
1.87 +provide a table of references to operation functions. A reference type is
1.88 +defined as a way of referencing the component providing the operations, and an
1.89 +object type is defined that bundles this opaque reference with a reference to
1.90 +the interface details. (Such an object is populated with a pointer to a
1.91 +component and a pointer to a table of concrete functions providing the
1.92 +appropriate operations.)
1.93
1.94 -== Templates and Output ==
1.95 +C++ programs provide the rather more straightforward class declaration
1.96 +containing the operations to be implemented by a component. (The
1.97 +implementation is provided by deriving from the generated class and defining
1.98 +concrete methods.)
1.99 +
1.100 +Both C and C++ output contains additional details describing operation codes
1.101 +and message structures (incoming and outgoing) for the different operations.
1.102 +
1.103 +=== Templates and Output ===
1.104
1.105 * `templates.h`
1.106
1.107 -== Servers ==
1.108 +=== Servers ===
1.109
1.110 * `server.c`
1.111
1.112 -== Dispatchers and Handlers ==
1.113 +=== Dispatchers and Handlers ===
1.114
1.115 * `dispatch.c`
1.116
1.117 -== Parameters and Members ==
1.118 +=== Parameters and Members ===
1.119
1.120 * `declaration.c`
1.121
1.122 -== Message Structures and Access ==
1.123 +=== Message Structures and Access ===
1.124
1.125 * `message.c`
1.126 * `structure.c`
1.127
1.128 -== Summaries ==
1.129 +=== Summaries ===
1.130
1.131 * `summary.c`