Subversion Repositories tendra.SVN

Rev

Rev 2 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 7u83 1
<!-- Crown Copyright (c) 1998 -->
2
<HTML>
3
<HEAD>
4
<TITLE>CAPSULEs and UNITs</TITLE>
5
</HEAD>
6
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
7
<A NAME=S8>
8
<H1>TDF Guide, Issue 4.0 </H1>
9
<H3>January 1998</H3>
10
<A HREF="guide6.html"><IMG SRC="../images/next.gif" ALT="next section">
11
</A> <A HREF="guide4.html">
12
<IMG SRC="../images/prev.gif" ALT="previous section"></A>
13
<A HREF="guide1.html"><IMG SRC="../images/top.gif" ALT="current document"></A>
14
<A HREF="../index.html"><IMG SRC="../images/home.gif" ALT="TenDRA home page">
15
</A>
16
<IMG SRC="../images/no_index.gif" ALT="document index"><P>
17
<HR>
18
<DL>
19
<DT><A HREF="#S9"><B>3.1 </B> - make_capsule and name-spaces</A><DD>
20
<DT><A HREF="#S10"><B>3.1.1 </B> - External linkages</A><DD>
21
<DT><A HREF="#S11"><B>3.1.2 </B> - UNITs</A><DD>
22
<DT><A HREF="#S12"><B>3.1.3 </B> - make_unit</A><DD>
23
<DT><A HREF="#S13"><B>3.1.4 </B> - LINK</A><DD>
24
<DT><A HREF="#S14"><B>3.2 </B> - Definitions and declarations</A><DD>
25
<DT><A HREF="#S15"><B>3.2.1 </B> - Scopes and linking</A><DD>
26
<DT><A HREF="#S16"><B>3.2.2 </B> - Declaration and definition signatures</A><DD>
27
<DT><A HREF="#S17"><B>3.2.3 </B> - STRING</A><DD>
28
</DL>
29
<HR>
30
<H1>3  CAPSULEs and UNITs</H1>
31
A CAPSULE is typically the result of a single compilation - one could
32
regard it as being the TDF analogue of a Unix .o file. Just as with
33
.o files, a set of CAPSULEs can be linked together to form another.
34
Similarly, a CAPSULE may be translated to make program for some platform,
35
provided certain conditions are met. One of these conditions is obviously
36
that a translator exists for the platform, but there are others. They
37
basically state that any names that are undefined in the CAPSULE can
38
be supplied by the system in which it is to be run. For example, the
39
translator could produce assembly code with external identifiers which
40
will be supplied by some system library.<P>
41
<A NAME=S9>
42
<HR><H2>3.1. <A NAME=2>make_capsule and name-spaces</H2>
43
The only constructor for a CAPSULE is make_capsule. Its basic function
44
is to compose together UNITs which contain the declarations and definitions
45
of the program. The signature of make_capsule looks rather daunting
46
and is probable best represented graphically.<P>
47
<CENTER>
48
<IMG SRC="../images/guide2.gif">
49
</CENTER>
50
<P>
51
The diagram gives an example of a CAPSULE using the same components
52
as in the following text. <P>
53
Each CAPSULE has its own name-space, distinct from all other CAPSULEs'
54
name-spaces and also from the name-spaces of its component UNITs (see
55
<A HREF="#11">section 3.1.2 on page 14</A>). There are several different
56
kinds of names in TDF and each name-space is further subdivided into
57
one for each kind of name. The number of different kinds of names
58
is potentially unlimited but only three are used in core-TDF, namely
59
&quot;tag&quot;, &quot;token&quot; and &quot;al_tag&quot;. Those names
60
in a &quot;tag&quot; name-space generally correspond to identifiers
61
in normal programs and I shall use these as the paradigm for the properties
62
of them all.<P>
63
The actual representations of a &quot;tag&quot; name in a given name-space
64
is an integer, described as SORT TDFINT. These integers are drawn
65
from a contiguous set starting from 0 up to some limit given by the
66
constructor which introduces the name-space. For CAPSULE name-spaces,
67
this is given by the <I>capsule_linking</I> parameter of make_capsule:<P>
68
<PRE>
69
<I>capsule_linking</I>: SLIST(CAPSULE_LINK)
70
</PRE>
71
In the most general case in core-TDF, there would be three entries
72
in the list introducing limits using make_capsule_link for each of
73
the &quot;tag&quot;, &quot;token&quot; and &quot;al_tag&quot; name-spaces
74
for the CAPSULE. Thus if: <P>
75
<PRE>
76
<I>capsule_linking</I> = (make_capsule_link(&quot;tag&quot;, 5), 
77
			            make_capsule_link(&quot;token&quot;, 6), 
78
			            make_capsule_link(&quot;al_tag&quot;, 7))
79
</PRE>
80
there are 5 CAPSULE &quot;tag&quot; names used within the CAPSULE,
81
namely 0, 1, 2, 3 and 4; similarly there are 6 &quot;token&quot; names
82
and 7 &quot;al_tag&quot; names.<P>
83
<A NAME=S10>
84
<H3>3.1.1. External linkages</H3>
85
The context of usage will always determine when and how an integer
86
is to be interpreted as a name in a particular name-space. For example,
87
a TAG in a UNIT is constructed by make_tag applied to a TDFINT which
88
will be interpreted as a name from that UNIT's &quot;tag&quot; name-space.
89
An integer representing a name in the CAPSULE name-space would be
90
found in a LINKEXTERN of the <I>external_linkage</I>
91
parameter of make_capsule.<P>
92
<PRE>
93
<I>external_linkage: </I>SLIST(EXTERN_LINK)
94
</PRE>
95
Each EXTERN_LINK is itself formed from an SLIST of LINKEXTERNs given
96
by make_extern_link . The order of the EXTERN_LINKs determines which
97
name-space one is dealing with; they are in the same order as given
98
by the <I>capsule_linkage</I>
99
parameter. Thus, with the <I>capsule_linkage</I> given above, the
100
first EXTERN_LINK would deal with the &quot;tag&quot; name-space;
101
Each of its component  LINKEXTERNs constructed by make_linkextern
102
would be identifying a tag number with some name external to the CAPSULE;
103
for example one might be:<P>
104
<PRE>
105
make_linkextern (4, string_extern(&quot;printf&quot;))
106
</PRE>
107
This would mean: identify the CAPSULE's &quot;tag&quot; 4 with an
108
name called &quot;printf&quot;, external to the module. The name &quot;printf&quot;
109
would be used to linkage external to the CAPSULE; any name required
110
outside the CAPSULE would have to be linked like this.<P>
111
<P>
112
<A NAME=S11>
113
<H3>3.1.2. <A NAME=11>UNITs</H3>
114
This name &quot;printf&quot;, of course, does not necessarily mean
115
the C procedure in the system library. This depends both on the system
116
context in which the CAPSULE is translated and also the meaning of
117
the CAPSULE &quot;tag&quot; name 4 given by the component UNITs of
118
the CAPSULE in the <I>groups</I> parameter of make_capsule:<P>
119
<PRE>
120
<I>groups: </I>SLIST(GROUP)
121
</PRE>
122
Each GROUP in the <I>groups</I> SLIST will be formed by sets of UNITs
123
of the same kind. Once again, there are a potentially unlimited number
124
of kinds of UNITs but core-TDF only uses those named &quot;tld&quot;,&quot;al_tagdefs&quot;,
125
&quot;tagdecs&quot;, &quot;tagdefs&quot;, &quot;tokdecs&quot; and
126
&quot;tokdefs&quot; 
127
<A NAME=footnote71 HREF="footnote.html#71">*</A>. These names will
128
appear (in the same order as in <I>groups</I>) in the <I>prop_names
129
</I>parameter of make_capsule, one for each kind of UNIT appearing
130
in the CAPSULE:<P>
131
<PRE>
132
<I>prop_names: </I>SLIST<I>(</I>TDFIDENT)
133
</PRE>
134
Thus if:<P>
135
<PRE>
136
<I>prop_names</I> = (&quot;tagdecs&quot;, &quot;tagdefs&quot;)
137
</PRE>
138
then, the first element of <I>groups</I> would contain only &quot;tagdecs&quot;
139
UNITs and and the second would contain only &quot;tagdefs&quot; UNITs.
140
A &quot;tagdecs&quot; UNIT contains things rather like a set of global
141
identifier declarations in C, while a &quot;tagdefs&quot; UNIT is
142
like a set of global definitions of identifiers.<P>
143
<A NAME=S12>
144
<H3>3.1.3. make_unit</H3>
145
Now we come to the construction of UNITs using make_unit, as in the
146
diagram below<P>
147
<CENTER>
148
<IMG SRC="../images/guide1.gif">
149
</CENTER>
150
<P>
151
First we give the limits of the various name-spaces local to the UNIT
152
in the <I>local_vars</I> parameter:<P>
153
<PRE>
154
<I>local_vars</I><I>: </I>SLIST(TDFINT<I>)</I>
155
</PRE>
156
Just in the same way as with <I>external_linkage</I>, the numbers
157
in local_vars correspond (in the same order) to the spaces indicated
158
in <I>capsule_linking</I> in <A HREF="#2">section 3.1 on page 13</A>.
159
With our example,the first element of <I>local_vars</I> gives the
160
number of &quot;tag&quot; names local to the UNIT, the second gives
161
the number of &quot;token&quot; names local to the UNIT etc. These
162
will include all the names used in the body of the UNIT. Each declaration
163
of a TAG, for example, will use a new number from the &quot;tag&quot;
164
name-space; there is no hiding or reuse of names within a UNIT.<P>
165
<A NAME=S13>
166
<H3>3.1.4. LINK</H3>
167
Connections between the CAPSULE name-spaces and the UNIT name-spaces
168
are made by LINKs in the <I>lks </I>parameter of make_unit: <P>
169
<PRE>
170
<I>lks</I>: SLIST(LINKS<I>)</I>
171
</PRE>
172
Once again, <I>lks</I> is effectively indexed by the kind of name-space
173
a. Each LINKS is an SLIST of LINKs each of which which establish an
174
identity between names in the CAPSULE name-space and names in the
175
UNIT name-space. Thus if the first element of <I>lks</I> contains:<P>
176
<PRE>
177
make_link(42, 4)
178
</PRE>
179
then, the UNIT &quot;tag&quot; 42 is identical to the CAPSULE &quot;tag&quot;
180
4.<P>
181
Note that names from the CAPSULE name-space only arise in two places,
182
LINKs and LINK_EXTERNs. Every other use of names are derived from
183
some UNIT name-space.<P>
184
<A NAME=S14>
185
<HR><H2>3.2. <A NAME=19>Definitions and declarations</H2>
186
The encoding in the <I>properties</I>:BYTSTREAM parameter of a UNIT
187
is a PROPS , for which there are five constructors corresponding to
188
the kinds of UNITs in core-TDF, make_al_tagdefs, make_tagdecs, make_tagdefs,
189
make_tokdefs and make_tokdecs. Each of these will declare or define
190
names in the appropriate UNIT name-space which can be used by make_link
191
in the UNIT's <I>lks</I>
192
parameter as well as elsewhere in the <I>properties</I> parameter.
193
The distinction between &quot;declarations&quot; and &quot;definitions&quot;
194
is rather similar to C usage; a declaration provides the &quot;type&quot;
195
of a name, while a definition gives its meaning. For tags, the &quot;type&quot;
196
is the SORT SHAPE (see below). For tokens, the &quot;type&quot; is
197
a SORTNAME constructed from the SORTNAMEs of the parameters and result
198
of the TOKEN using token: <P>
199
<PRE>
200
	<I>params</I>:	LIST(SORTNAME)
201
	<I>result</I>:	SORTNAME
202
		   -&gt; SORTNAME
203
</PRE>
204
Taking make_tagdefs as a paradigm for PROPS, we have:<P>
205
<PRE>
206
<I>	no_labels</I>: 	TDFINT
207
<I>	tds</I>: 	SLIST(TAGDEF)
208
		   -&gt; TAGDEF_PROPS
209
</PRE>
210
The <I>no_labels</I> parameter introduces the size of yet another
211
name-space local to the PROPS, this time for the LABELs used in the
212
TAGDEFs. Each TAGDEF in <I>tds</I> will define a &quot;tag&quot; name
213
in the UNIT's name-space. The order of these TAGDEFs is immaterial
214
since the initialisations of the tags are values which can be solved
215
at translate time, load time or as unordered dynamic initialisations.
216
<P>
217
There are three constructors for TAGDEFs, each with slightly different
218
properties. The simplest is make_id_tagdef:<P>
219
<PRE>
220
	<I>t</I>:	TDFINT	
221
	<I>signature</I>:	OPTION(STRING)
222
	<I>e</I>:	EXP <I>x</I>
223
		   -&gt; TAGDEF
224
</PRE>
225
Here, <I>t</I> is the tag name and the evaluation of <I>e</I> will
226
be the value of SHAPE <I>x</I> of an obtain_tag(<I>t</I>) in an EXP.
227
Note that t is not a variable; the value of obtain_tag(<I>t</I>) will
228
be invariant. The <I>signature</I> parameter gives a STRING (see 
229
<A HREF="#39">section 3.2.3 on page 18</A>) which may be used as an
230
name for the tag, external to TDF and also as a check introduced by
231
the producer that a tagdef and its corresponding tagdec have the same
232
notion of the language-specific type of the tag.<P>
233
<P>
234
The two other constructors for TAGDEF, make_var_tagdef and common_tagdef
235
both define variable tags and have the same signature: <P>
236
<PRE>
237
	<I>t</I>:	TDFINT
238
<I>	opt_access</I>:	OPTION(ACCESS)
239
	<I>signature</I>:	OPTION(STRING)
240
	<I>e</I>:	EXP <I>x</I>
241
		   -&gt; TAGDEF
242
</PRE>
243
Once again <I>t</I> is tag name but now <I>e</I> is initialisation
244
of the variable <I>t</I>. A use of obtain_tag(<I>t</I>) will give
245
a pointer to the variable (of SHAPE POINTER x), rather than its contents
246
<A NAME=footnote72 HREF="footnote.html#72">*</A>. There can only be
247
one make_var_tagdef of a given tag in a program, but there may be
248
more than one common_tagdef, possibly with different initialisations;
249
however these initialisations must overlap consistently just as in
250
common blocks in FORTRAN.<P>
251
The ACCESS parameter gives various properties required for the tag
252
being defined and is discussed in <A HREF="guide7.html#40">section
253
5.3.2 on page 30</A>.<P>
254
The initialisation EXPs of TAGDEFs will be evaluated before the &quot;main&quot;
255
program is started. An initialiation EXP must either be a constant
256
(in the sense of <A HREF="guide11.html#0">section 9 on page 43</A>)
257
or reduce to (either directly or by token or _cond expansions) to
258
an initial_value:<P>
259
<PRE>
260
	<I>init</I>:	EXP <I>s</I>
261
		   -&gt; EXP <I>s</I>
262
</PRE>
263
The translator will arrange that <I>init</I> will be evaluated once
264
only before any procedure application, other than those themselves
265
involved in initial_values, but after any constant initialisations.
266
The order of evaluation of different initial_values is arbitrary.<P>
267
<A NAME=S15>
268
<H3>3.2.1. Scopes and linking</H3>
269
Only names introduced by AL_TAGDEFS, TAGDEFS, TAGDECs, TOKDECs and
270
TOKDEFs can be used in other UNITs (and then, only via the <I>lks</I>
271
parameters of the UNITs involved). You can regard them as being similar
272
to C global declarations. Token definitions include their declarations
273
implicitly; however this is not true of tags. This means that any
274
CAPSULE which uses or defines a tag across UNITs must include a TAGDEC
275
for that tag in its &quot;tagdecs&quot; UNITs. A TAGDEC is constructed
276
using either make_id_tagdec , make_var_tagdec or common_tagdec, all
277
with the same form:<P>
278
<PRE>
279
	<I>t_intro</I>:	TDFINT
280
	<I>acc</I>:		OPTION(ACCESS)
281
	<I>signature</I>:	OPTION(STRING)
282
	<I>x</I>:		SHAPE
283
		   -&gt; TAGDEC
284
</PRE>
285
Here the tagname is given by <I>t_intro</I>; the SHAPE <I>x</I> will
286
defined the space and alignment required for the tag (this is analogous
287
to the type in a C declaration). The <I>acc</I> field will define
288
certain properties of the tag not implicit in its SHAPE; I shall return
289
to the kinds of properties envisaged in discussing local declarations
290
in <A HREF="guide7.html#34">section 5.3 on page 30</A>.<P>
291
Most program will appear in the &quot;tagdefs&quot; UNITs - they will
292
include the definitions of the procedures of the program which in
293
turn will include local definitions of tags for the locals of the
294
procedures.<P>
295
The standard TDF linker allows one to link CAPSULEs together using
296
the name identifications given in the LINKEXTERNs, perhaps hiding
297
some of them in the final CAPSULE. It does this just by generating
298
a new CAPSULE name-space, grouping together component UNITs of the
299
same kind and replacing their <I>lks</I> parameters with values derived
300
from the new CAPSULE name-space without changing the UNITs' name-spaces
301
or their <I>props</I> parameters. The operation of grouping together
302
UNITs is effectively assumed to be associative, commutative and idempotent
303
e.g. if the same tag is declared in two capsules it is assumed to
304
be the same thing . It also means that there is no implied order of
305
evaluation of UNITs or of their component TAGDEFs<P>
306
Different languages have different conventions for deciding how programs
307
are actually run. For example, C requires the presence of a suitably
308
defined &quot;main&quot; procedure; this is usually enforced by requiring
309
the system ld utility to bind the name &quot;main&quot; along with
310
the definitions of any library values required. Otherwise, the C conventions
311
are met by standard TDF linking. Other languages have more stringent
312
requirements. For example, C++ requires dynamic initialisation of
313
globals, using initial_value. As the only runnable code in TDF is
314
in procedures, C++ would probably require an additional linking phase
315
to construct a &quot;main&quot; procedure which calls the initialisation
316
procedures of each CAPSULE involved if the system linker did not provide
317
suitable C++ linking. <P>
318
<A NAME=S16>
319
<H3>3.2.2. <A NAME=37>Declaration and definition <I>signatures</I></H3>
320
The <I>signature</I> arguments of TAGDEFs and TAGDECs are designed
321
to allow a measure of cross-UNIT checking when linking independently
322
compiled CAPSULEs. Suppose that we have a tag, <I>t</I>, used in one
323
CAPSULE and defined in another; the first CAPSULE would have to have
324
a TAGDEC for <I>t</I> whose TAGDEF is in the second. The <I>signature</I>
325
STRING of both could be arranged to represent the language-specific
326
type of <I>t</I> as understood at compilation-time. Clearly, when
327
the CAPSULEs are linked the types must be identical and hence their
328
STRING representation must be the same - a translator will reject
329
any attempt to link definitions and declarations of the same object
330
with different signatures.<P>
331
Similar considerations apply to TOKDEFs and TOKDECs; the &quot;type&quot;
332
of a TOKEN may not have any familiar analogue in most HLLs, but the
333
principle remains the same.<P>
334
<A NAME=S17>
335
<H3>3.2.3. <A NAME=39>STRING</H3>
336
The SORT STRING is used in various constructs other than declarations
337
and definitions. It is a first-class SORT with  string_apply_token
338
and string_cond. A primitive STRING is constructed from a TDFSTRING(k,n)
339
which is an encoding of n integers,each of k bits, using make_string:
340
<P>
341
<PRE>
342
	<I>arg</I>:	TDFSTRING<I>(k, n)</I>
343
		   -&gt; STRING<I>(k, n)</I>
344
</PRE>
345
STRINGs may be concatenated using concat_string:<P>
346
<PRE>
347
	<I>arg1</I>:	STRING<I>(k, n)</I>
348
	<I>arg2</I>:	STRING<I>(k,m)</I>
349
		   -&gt; STRING<I>(k, n+m)</I>
350
</PRE>
351
Being able to compose strings, including token applications etc, means
352
that late-binding is possible in <I>signature</I> checking in definitions
353
and declarations. This late-binding means that the representation
354
of platform-dependent HLL types need only be fully expanded at install-time
355
and hence the types could be expressed in their representational form
356
on the specific platform.<P>
357
<P>
358
<HR>
359
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
360
Copyright &copy; 1998.</I></P>
361
</BODY>
362
</HTML>