5 %%% (c) 2015 Straylight/Edgeware
8 %%%----- Licensing notice ---------------------------------------------------
10 %%% This file is part of the Sensible Object Design, an object system for C.
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.
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.
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.
26 \chapter{The output system
} \label{ch:output
}
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.
33 %%%--------------------------------------------------------------------------
34 \section{Output sequencing
} \label{sec:output.sequencer
}
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.
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.
51 Instead, there's a clear separation between which things need to be output,
52 and the order in which they're produced.
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
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.
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
72 It might be that a collection of constraints is impossible to satisfy: for
74 \begin{center
} \codeface
75 (alice bob)
\qquad (bob carol)
\qquad (carol alice)
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|.
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.
89 For example, suppose we have the following constraints.
90 \begin{center
} \codeface
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
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|.
114 The functions are maintained in
\emph{reverse order
}, because it's
115 convenient to be able to add new functions using @|push|.
118 \begin{describe
}{fun
}{sequencer-item-p @<object> @> @<generalized-boolean>
}
119 Return non-nil if and only if @<object> is a @|sequencer-item|.
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.
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|.
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.
139 \begin{describe
}{cls
}{sequencer () \&key :constraints
}
143 {\dhead{fun
}{sequencer-constraints @<sequencer> @> @<list>
}
144 \dhead{fun
}{setf (sequencer-constraints @<sequencer>) @<list>
}
145 \dhead{fun
}{sequencer-table @<sequencer> @> @<hash-table>
}}
148 \begin{describe
}{fun
}{ensure-sequencer-item @<sequencer> @<name> @> @<item>
}
151 \begin{describe
}{fun
}{add-sequencer-constraint @<sequencer> @<constraint>
}
154 \begin{describe
}{fun
}
155 {add-sequencer-item-function @<sequencer> @<name> @<function>
}
158 \begin{describe
}{fun
}
159 {invoke-sequencer-items @<sequencer> \&rest @<arguments>
}
162 \begin{describe
}{gf
}{hook-output @<object> @<reason> @<sequencer>
}
163 \begin{describe
}{meth
}{t,t
}
164 {hook-output (@<object> t) (@<reason> t) @<sequencer>
}
168 \begin{describe
}{mac
}
169 {sequence-output (@<stream-var> @<sequencer>) \\
\ind
170 @
{ :constraint (@<item-name>^*) @
} \\
171 @
{ (@<item-name> @<form>^*) @
}^*
}
174 %%%--------------------------------------------------------------------------
175 \section{Module output
} \label{output.module
}
177 \subsection{Producing output
}
180 {module-output-file @<module> @<output-type> @<output-dir>
183 {\dhead{meth
}{module,symbol
}
184 {module-output-file \=(@<module> module) \\
185 \>(@<output-type> symbol) \\
188 \dhead{meth
}{module,pathname
}
189 {module-output-file \=(@<module> module) \\
190 \>(@<output-type> pathname) \\
196 \begin{describe
}{gf
}{write-dependency-file @<module> @<reason> @<output-dir>
}
199 \begin{describe
}{fun
}{output-module @<module> @<reason> @<stream>
}
203 \subsection{Managing output types
} \label{output.module.manage
}
205 \begin{describe
}{fun
}{declare-output-type @<reason> @<pathname>
}
208 \begin{describe
}{fun
}{output-type-pathname @<reason> @> @<pathname>
}
212 \subsection{Utilities
} \label{output.module.utilities
}
214 \begin{describe
}{fun
}{banner @<title> @<output> \&key :blank-line-p
}
217 \begin{describe
}{fun
}{guard-name @<filename> @> @<string>
}
220 \begin{describe
}{fun
}
221 {one-off-output @<token> @<sequencer> @<item-name> @<function>
}
224 %%%--------------------------------------------------------------------------
225 \section{Class output
} \label{output.class
}
227 \begin{describe
}{var
}{*instance-class*
}
230 \begin{describe
}{gf
}{emit-class-typedef @<class> @<stream>
}
233 \begin{describe
}{gf
}{emit-class-object-decl @<class> @<stream>
}
236 \begin{describe
}{gf
}{emit-class-conversion-macro @<class> @<super> @<stream>
}
240 {\dhead{gf
}{emit-message-macro @<class> @<entry> @<stream>
}
241 \dhead{gf
}{emit-message-macro-defn
242 \=@<class> @<entry> @<varargsp> @<me> \\
243 \>@<in-names> @<out-names> @<stream>
}}
246 %% output for `h' files
261 %% CLASS islots start
262 %% CLASS islots slots
264 %% CLASS vtmsgs start
265 %% CLASS vtmsgs CLASS start
266 %% CLASS vtmsgs CLASS slots
267 %% CLASS vtmsgs CLASS end
269 %% CLASS vtables start
270 %% CLASS vtables CHAIN-HEAD start
271 %% CLASS vtables CHAIN-HEAD slots
272 %% CLASS vtables CHAIN-HEAD end
274 %% CLASS vtable-externs
275 %% CLASS vtable-externs-after
276 %% CLASS methods start
279 %% CLASS ichains start
280 %% CLASS ichains CHAIN-HEAD start
281 %% CLASS ichains CHAIN-HEAD slots
282 %% CLASS ichains CHAIN-HEAD end
284 %% CLASS ilayout start
285 %% CLASS ilayout slots
296 %% output for `c' files
307 %% CLASS direct-methods start
308 %% CLASS direct-methods METHOD start
309 %% CLASS direct-methods METHOD body
310 %% CLASS direct-methods METHOD end
311 %% CLASS direct-methods end
312 %% CLASS effective-methods
313 %% CLASS vtables start
314 %% CLASS vtables CHAIN-HEAD start
315 %% CLASS vtables CHAIN-HEAD class-pointer METACLASS
316 %% CLASS vtables CHAIN-HEAD base-offset
317 %% CLASS vtables CHAIN-HEAD chain-offset TARGET-HEAD
318 %% CLASS vtables CHAIN-HEAD vtmsgs CLASS start
319 %% CLASS vtables CHAIN-HEAD vtmsgs CLASS slots
320 %% CLASS vtables CHAIN-HEAD vtmsgs CLASS end
321 %% CLASS vtables CHAIN-HEAD end
323 %% CLASS object prepare
324 %% CLASS object start
325 %% CLASS object CHAIN-HEAD ichain start
326 %% CLASS object SUPER slots start
327 %% CLASS object SUPER slots
328 %% CLASS object SUPER vtable
329 %% CLASS object SUPER slots end
330 %% CLASS object CHAIN-HEAD ichain end
338 %%%----- That's all, folks --------------------------------------------------
342 %%% TeX-master: "sod.tex"