chiark - git - mdw - sod/blob - doc/output.tex

   1 %%% -*-latex-*-
   2 %%%
   3 %%% Output machinery
   4 %%%
   5 %%% (c) 2015 Straylight/Edgeware
   6 %%%
   7
   8 %%%----- Licensing notice ---------------------------------------------------
   9 %%%
  10 %%% This file is part of the Sensible Object Design, an object system for C.
  11 %%%
  12 %%% SOD is free software; you can redistribute it and/or modify
  13 %%% it under the terms of the GNU General Public License as published by
  14 %%% the Free Software Foundation; either version 2 of the License, or
  15 %%% (at your option) any later version.
  16 %%%
  17 %%% SOD is distributed in the hope that it will be useful,
  18 %%% but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 %%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 %%% GNU General Public License for more details.
  21 %%%
  22 %%% You should have received a copy of the GNU General Public License
  23 %%% along with SOD; if not, write to the Free Software Foundation,
  24 %%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  25
  26 \chapter{The output system} \label{ch:output}
  27
  28 This chapter deals with actually generating output files.  It will be of
  29 interest to programmers introducing new layout object classes, or new kinds
  30 of output files.  An understanding of the material in
  31 \xref{sec:structures.layout} will prove valuable.
  32
  33 %%%--------------------------------------------------------------------------
  34 \section{Output sequencing} \label{sec:output.sequencer}
  35
  36 C compilers are picky about the order in which things are presented to them
  37 in their input; but information about the structure of our classes is
  38 scattered among a variety of different layout objects.  It's not the case
  39 that a layout object only contributes to a single localized portion of the
  40 output: for example, a @|vtmsgs| layout object is responsible for declaring
  41 both the appropriate @|struct $C$__vtmsgs_$a$| structure in the header file,
  42 populated with method entry pointers, but also declaring its member in the
  43 enclosing @|struct $C$__vt_$i$| structure.
  44
  45 One approach would be to have the various layout objects just know how to
  46 call each other in the right order so as to have everything come out
  47 properly.  That would make extending the translator, e.g., to add new kinds
  48 of layout objects, rather difficult.  And it doesn't let users insert custom
  49 C fragments in flexible ways.
  50
  51 Instead, there's a clear separation between which things need to be output,
  52 and the order in which they're produced.
  53
  54 Ordering is handled by a \emph{sequencer} object.  A sequencer doesn't know
  55 anything particular about output: its job is simply to do things in a
  56 particular order.  It's described here because Sod only uses it for output
  57 scheduling.
  58
  59 A sequencer maintains a collection of named \emph{items}, each of which has a
  60 name and a list of functions associated with it.  A name can be any Lisp
  61 object.  Names are compared using @|equal|, so lists can be used to construct
  62 a hierarchical namespace.
  63
  64 The sequencer also maintains a collection of \emph{constraints}, which take
  65 the form of lists of item names.  A constraint of the form @|($N_1$, $N_2$,
  66 $\ldots$, $N_k$)| requires that the item named $N_1$ must be scheduled before
  67 the item named $N_2$, and so on, all of which must be scheduled before the
  68 item named $N_k$.  Items with these names do not need to exist or be known to
  69 the sequencer.  An item name may appear in any number of constraints, all of
  70 which apply.
  71
  72 It might be that a collection of constraints is impossible to satisfy: for
  73 example, the set
  74 \begin{center} \codeface
  75   (alice bob) \qquad (bob carol) \qquad (carol alice)
  76 \end{center}
  77 can't be satisfied, since the first constraint requires that @|alice|
  78 precedes @|bob|, but the third says that @|alice| must come after @|carol|,
  79 and the second that @|carol| comes after @|bob|: it's not possible that
  80 @|alice| comes before @|bob| and after @|bob|.  In this case, the sequencer
  81 fails and signals an error of type @|inconsistent-merge-error|.
  82
  83 It is possible, but tedious, to explicitly order an entire collection of
  84 items by adding constraints.  In the absence of explicit constraints to order
  85 them, items are ordered according to the order in which constraints naming
  86 them were first added to the sequencer.  Items not named in any constraint
  87 are not processed at all.
  88
  89 For example, suppose we have the following constraints.
  90 \begin{center} \codeface
  91   (perl java) \qquad
  92   (lisp java) \qquad
  93   (python icon) \qquad
  94   (icon perl)
  95 \end{center}
  96 The constraints give us that $@|python| < @|icon| < @|perl| < @|java|$, and
  97 also $@|lisp| < @|java|$.  In this case, @|lisp| precedes @|python| because
  98 @|lisp| is mentioned in the second constraint while @|python| isn't mentioned
  99 until the third.  So the final processing order is
 100 \begin{center}
 101   @|lisp|, \quad
 102   @|python|, \quad
 103   @|icon|, \quad
 104   @|perl|, \quad
 105   @|java|
 106 \end{center}
 107
 108
 109 \begin{describe}{cls}{sequencer-item}
 110   An object of class @|sequencer-item| represents a sequencer item.
 111   Sequencer items maintain a \emph{name} and a list of \emph{functions}.
 112   Names are compared using @|equal|.
 113
 114   The functions are maintained in \emph{reverse order}, because it's
 115   convenient to be able to add new functions using @|push|.
 116 \end{describe}
 117
 118 \begin{describe}{fun}{sequencer-item-p @<object> @> @<generalized-boolean>}
 119   Return non-nil if and only if @<object> is a @|sequencer-item|.
 120 \end{describe}
 121
 122 \begin{describe}{fun}
 123     {make-sequencer-item @<name> \&optional @<functions> @> @<item>}
 124   Create and return a new sequencer item with the given @<name> and list of
 125   @<functions>; the list of functions defaults to nil if omitted.
 126 \end{describe}
 127
 128 \begin{describe*}
 129     {\dhead{fun}{sequencer-item-name @<item> @> @<name>}
 130      \dhead{fun}{sequencer-item-functions @<item> @> @<list>}
 131      \dhead{fun}{setf (sequencer-item-functions @<item>) @<list>}}
 132    These functions read or modify the state of a sequencer @<item>, as
 133    originally established by @|make-sequencer-item|.
 134
 135    It is an error to modify an item's list of functions during a call to
 136    @|invoke-sequencer-items| on the item's owning sequencer.
 137 \end{describe*}
 138
 139 \begin{describe}{cls}{sequencer () \&key :constraints}
 140 \end{describe}
 141
 142 \begin{describe}{fun}{ensure-sequencer-item @<sequencer> @<name> @> @<item>}
 143 \end{describe}
 144
 145 \begin{describe}{fun}{add-sequencer-constraint @<sequencer> @<constraint>}
 146 \end{describe}
 147
 148 \begin{describe}{fun}
 149     {invoke-sequencer-items @<sequencer> \&rest @<arguments>}
 150 \end{describe}
 151
 152 \begin{describe}{gf}{hook-output progn @<object> @<reason> @<sequencer>}
 153   \begin{describe}{meth}
 154     {hook-output progn (@<object> t) (@<reason> t) @<sequencer>}
 155   \end{describe}
 156 \end{describe}
 157
 158 \begin{describe}{mac}
 159     {sequence-output (@<stream-var> @<sequencer>)               \\ \ind
 160       @{ :constraint (@<item-name>^*) @}                        \\
 161       @{ (@<item-name> @<form>^*) @}^*}
 162 \end{describe}
 163
 164 %%%--------------------------------------------------------------------------
 165 \section{Module output} \label{output.module}
 166
 167 \subsection{Producing output}
 168
 169 \begin{describe}{fun}{output-module @<module> @<reason> @<stream>}
 170 \end{describe}
 171
 172
 173 \subsection{Managing output types} \label{output.module.manage}
 174
 175 \begin{describe}{fun}{declare-output-type @<reason> @<pathname>}
 176 \end{describe}
 177
 178 \begin{describe}{fun}{output-type-pathname @<reason> @> @<pathname>}
 179 \end{describe}
 180
 181
 182 \subsection{Utilities} \label{output.module.utilities}
 183
 184 \begin{describe}{fun}{banner @<title> @<output> \&key :blank-line-p}
 185 \end{describe}
 186
 187 \begin{describe}{fun}{guard-name @<filename> @> @<string>}
 188 \end{describe}
 189
 190 \begin{describe}{fun}
 191     {one-off-output @<token> @<sequencer> @<item-name> @<function>}
 192 \end{describe}
 193
 194 %%%--------------------------------------------------------------------------
 195 \section{Class output} \label{output.class}
 196
 197 \begin{describe}{var}{*instance-class*}
 198 \end{describe}
 199
 200 %% output for `h' files
 201 %%
 202 %% prologue
 203 %% guard start
 204 %% typedefs start
 205 %% typedefs
 206 %% typedefs end
 207 %% includes start
 208 %% includes
 209 %% includes end
 210 %% classes start
 211 %% early-user start
 212 %% early-user
 213 %% early-user end
 214 %% CLASS banner
 215 %% CLASS islots start
 216 %% CLASS islots slots
 217 %% CLASS islots end
 218 %% CLASS vtmsgs start
 219 %% CLASS vtmsgs CLASS start
 220 %% CLASS vtmsgs CLASS slots
 221 %% CLASS vtmsgs CLASS end
 222 %% CLASS vtmsgs end
 223 %% CLASS vtables start
 224 %% CLASS vtables CHAIN-HEAD start
 225 %% CLASS vtables CHAIN-HEAD slots
 226 %% CLASS vtables CHAIN-HEAD end
 227 %% CLASS vtables end
 228 %% CLASS vtable-externs
 229 %% CLASS vtable-externs-after
 230 %% CLASS methods start
 231 %% CLASS methods
 232 %% CLASS methods end
 233 %% CLASS ichains start
 234 %% CLASS ichains CHAIN-HEAD start
 235 %% CLASS ichains CHAIN-HEAD slots
 236 %% CLASS ichains CHAIN-HEAD end
 237 %% CLASS ichains end
 238 %% CLASS ilayout start
 239 %% CLASS ilayout slots
 240 %% CLASS ilayout end
 241 %% CLASS conversions
 242 %% CLASS object
 243 %% classes end
 244 %% user start
 245 %% user
 246 %% user end
 247 %% guard end
 248 %% epilogue
 249
 250 %% output for `c' files
 251 %%
 252 %% prologue
 253 %% includes start
 254 %% includes
 255 %% includes end
 256 %% early-user start
 257 %% early-user
 258 %% early-user end
 259 %% classes start
 260 %% CLASS banner
 261 %% CLASS direct-methods start
 262 %% CLASS direct-methods METHOD start
 263 %% CLASS direct-methods METHOD body
 264 %% CLASS direct-methods METHOD end
 265 %% CLASS direct-methods end
 266 %% CLASS effective-methods
 267 %% CLASS vtables start
 268 %% CLASS vtables CHAIN-HEAD start
 269 %% CLASS vtables CHAIN-HEAD class-pointer METACLASS
 270 %% CLASS vtables CHAIN-HEAD base-offset
 271 %% CLASS vtables CHAIN-HEAD chain-offset TARGET-HEAD
 272 %% CLASS vtables CHAIN-HEAD vtmsgs CLASS start
 273 %% CLASS vtables CHAIN-HEAD vtmsgs CLASS slots
 274 %% CLASS vtables CHAIN-HEAD vtmsgs CLASS end
 275 %% CLASS vtables CHAIN-HEAD end
 276 %% CLASS vtables end
 277 %% CLASS object prepare
 278 %% CLASS object start
 279 %% CLASS object CHAIN-HEAD ichain start
 280 %% CLASS object SUPER slots start
 281 %% CLASS object SUPER slots
 282 %% CLASS object SUPER vtable
 283 %% CLASS object SUPER slots end
 284 %% CLASS object CHAIN-HEAD ichain end
 285 %% CLASS object end
 286 %% classes end
 287 %% user start
 288 %% user
 289 %% user end
 290 %% epilogue
 291
 292 %%%----- That's all, folks --------------------------------------------------
 293
 294 %%% Local variables:
 295 %%% mode: LaTeX
 296 %%% TeX-master: "sod.tex"
 297 %%% TeX-PDF-mode: t
 298 %%% End: