File: lib.html

package info (click to toggle)
tendra-doc 4.1.2-8
links: PTS
area: main
in suites: etch, etch-m68k, jessie, jessie-kfreebsd, lenny, squeeze
size: 2,608 kB
ctags: 1,566
sloc: makefile: 31; sh: 3
file content (1950 lines) | stat: -rw-r--r-- 80,022 bytes
parent folder | download | duplicates (4)
<!-- Crown Copyright (c) 1998 -->
<HTML>
<HEAD>
<TITLE>
C++ Producer Guide: Implementation 
</TITLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">

<H1>C++ Producer Guide</H1>
<H3>March 1998</H3>
<A HREF="std.html"><IMG SRC="../images/next.gif" ALT="next section"></A>
<A HREF="link.html"><IMG SRC="../images/prev.gif" ALT="previous section"></A>
<A HREF="index.html"><IMG SRC="../images/top.gif" ALT="current document"></A>
<A HREF="../index.html"><IMG SRC="../images/home.gif" ALT="TenDRA home page">
</A>
<IMG SRC="../images/no_index.gif" ALT="document index"><P>
<HR>

<DL>
<DT><A HREF="#arith"><B>2.6.1</B> - Arithmetic types</A><DD>
<DT><A HREF="#literal"><B>2.6.2</B> - Integer literal types</A><DD>
<DT><A HREF="#bitfield"><B>2.6.3</B> - Bitfield types</A><DD>
<DT><A HREF="#pointer"><B>2.6.4</B> - Generic pointers</A><DD>
<DT><A HREF="#conv"><B>2.6.5</B> - Undefined conversions</A><DD>
<DT><A HREF="#div"><B>2.6.6</B> - Integer division</A><DD>
<DT><A HREF="#call"><B>2.6.7</B> - Calling conventions</A><DD>
<DT><A HREF="#ptr_mem"><B>2.6.8</B> - Pointers to data members</A><DD>
<DT><A HREF="#ptr_mem_func"><B>2.6.9</B> - Pointers to function members</A><DD>
<DT><A HREF="#class"><B>2.6.10</B> - Class layout</A><DD>
<DT><A HREF="#derive"><B>2.6.11</B> - Derived class layout</A><DD>
<DT><A HREF="#constr"><B>2.6.12</B> - Constructors and destructors</A><DD>
<DT><A HREF="#vtable"><B>2.6.13</B> - Virtual function tables</A><DD>
<DT><A HREF="#rtti"><B>2.6.14</B> - Run-time type information</A><DD>
<DT><A HREF="#init"><B>2.6.15</B> - Dynamic initialisation</A><DD>
<DT><A HREF="#except"><B>2.6.16</B> - Exception handling</A><DD>
<DT><A HREF="#mangle"><B>2.6.17</B> - Mangled identifier names</A><DD>
</DL>
<HR>

<H2>2.6. Implementation details</H2>
<P>
This section describes various of the implementation details of the
C++ producer TDF output.  In particular it describes the standard
TDF tokens used to represent the target dependent aspects of the language
and to provide links into the run-time system.  Many of these tokens
are common to the C and C++ producers.  Those which are unique to
the C++ producer have names of the form <CODE>~cpp.*</CODE>.  Note
that the description is in terms of TDF tokens, not the internal tokens
introduced by the 
<A HREF="token.html"><CODE>#pragma token</CODE> syntax</A>. 
</P>
<P>
There are two levels of implementation in the run-time system.  The
actual interface between the producer and the run-time system is given
by the standard tokens.  The provided implementation defines these
tokens in a way appropriate to itself.  An alternative implementation
would have to define the tokens differently.  It is intended that
the standard tokens are sufficiently generic to allow a variety of
implementations to hook into the producer output in the manner they
require. 
</P>

<HR>
<H3><A NAME="arith">2.6.1. Arithmetic types</A></H3>
<P>
The representations of the basic arithmetic types are target dependent,
so, for example, an <CODE>int</CODE> may contain 16, 32, 64 or some
other number of bits.  Thus it is necessary to introduce a token to
stand for each of the built-in arithmetic types (including the 
<A HREF="pragma.html#longlong"><CODE>long long</CODE> types</A>).
Each integral type is represented by a <CODE>VARIETY</CODE> token
as follows: 
</P>
<CENTER>
<TABLE BORDER>
<TR><TH>Type</TH>
<TH>Token</TH>
<TH>Encoding</TH>
<TR><TD ALIGN=CENTER>char</TD>
<TD ALIGN=CENTER>~char</TD>
<TD ALIGN=CENTER>0</TD>
<TR><TD ALIGN=CENTER>signed char</TD>
<TD ALIGN=CENTER>~signed_char</TD>
<TD ALIGN=CENTER>0 | 4 = 4</TD>
<TR><TD ALIGN=CENTER>unsigned char</TD>
<TD ALIGN=CENTER>~unsigned_char</TD>
<TD ALIGN=CENTER>0 | 8 = 8</TD>
<TR><TD ALIGN=CENTER>signed short</TD>
<TD ALIGN=CENTER>~signed_short</TD>
<TD ALIGN=CENTER>1 | 4 = 5</TD>
<TR><TD ALIGN=CENTER>unsigned short</TD>
<TD ALIGN=CENTER>~unsigned_short</TD>
<TD ALIGN=CENTER>1 | 8 = 9</TD>
<TR><TD ALIGN=CENTER>signed int</TD>
<TD ALIGN=CENTER>~signed_int</TD>
<TD ALIGN=CENTER>2 | 4 = 6</TD>
<TR><TD ALIGN=CENTER>unsigned int</TD>
<TD ALIGN=CENTER>~unsigned_int</TD>
<TD ALIGN=CENTER>2 | 8 = 10</TD>
<TR><TD ALIGN=CENTER>signed long</TD>
<TD ALIGN=CENTER>~signed_long</TD>
<TD ALIGN=CENTER>3 | 4 = 7</TD>
<TR><TD ALIGN=CENTER>unsigned long</TD>
<TD ALIGN=CENTER>~unsigned_long</TD>
<TD ALIGN=CENTER>3 | 8 = 11</TD>
<TR><TD ALIGN=CENTER>signed long long</TD>
<TD ALIGN=CENTER>~signed_longlong</TD>
<TD ALIGN=CENTER>3 | 4 | 16 = 23 </TD>
<TR><TD ALIGN=CENTER>unsigned long long</TD>
<TD ALIGN=CENTER>~unsigned_longlong</TD>
<TD ALIGN=CENTER>3 | 8 | 16 = 27</TD>
</TABLE>
</CENTER>
<P>
Similarly each floating point type is represent by a 
<CODE>FLOATING_VARIETY</CODE> token: 
</P>
<CENTER>
<TABLE BORDER>
<TR><TH>Type</TH>   <TH>Token</TH>
<TR><TD ALIGN=CENTER>float</TD>  <TD ALIGN=CENTER>~float</TD>
<TR><TD ALIGN=CENTER>double</TD> <TD ALIGN=CENTER>~double</TD>
<TR><TD ALIGN=CENTER>long double</TD> <TD ALIGN=CENTER>~long_double</TD>
</TABLE>
</CENTER>
<P>
Each integral type also has an encoding as a <CODE>SIGNED_NAT</CODE>
as shown above.  This number is a bit pattern built up from the following
values: 
</P>
<CENTER>
<TABLE BORDER>
<TR><TH>Type</TH>   <TH>Encoding</TH>
<TR><TD ALIGN=CENTER>char</TD>  <TD ALIGN=CENTER>0</TD>
<TR><TD ALIGN=CENTER>short</TD>  <TD ALIGN=CENTER>1</TD>
<TR><TD ALIGN=CENTER>int</TD>  <TD ALIGN=CENTER>2</TD>
<TR><TD ALIGN=CENTER>long</TD>  <TD ALIGN=CENTER>3</TD>
<TR><TD ALIGN=CENTER>signed</TD> <TD ALIGN=CENTER>4</TD>
<TR><TD ALIGN=CENTER>unsigned</TD> <TD ALIGN=CENTER>8</TD>
<TR><TD ALIGN=CENTER>long long</TD> <TD ALIGN=CENTER>16</TD>
</TABLE>
</CENTER>
<P>
Any target dependent integral type can be represented by a 
<CODE>SIGNED_NAT</CODE> token using this encoding.  This representation,
rather than one based on <CODE>VARIETY</CODE>s, is used for ease of
manipulation.  The token: 
<PRE>
	~convert : ( SIGNED_NAT ) -&gt; VARIETY
</PRE>
gives the mapping from the integral encoding to the representing variety.
For example, it will map <CODE>6</CODE> to <CODE>~signed_int</CODE>.
</P>
<P>
The token: 
<PRE>
	~promote : ( SIGNED_NAT ) -&gt; SIGNED_NAT
</PRE>
describes how to form the promotion of an integral type according
to the ISO C/C++ value preserving rules, and is used by the producer
to represent target dependent promotion types.  For example, the promotion
of <CODE>unsigned short</CODE> may be <CODE>int</CODE> or <CODE>unsigned
int</CODE> depending on the representation of these types; that is
to say, <CODE>~promote ( 9 )</CODE> will be <CODE>6</CODE> on some
machines and <CODE>10</CODE> on others.  Although <CODE>~promote</CODE>
is used by default, a program may specify another token with the same
sort signature to be used in its place by means of the directive:
<PRE>
	#pragma TenDRA compute promote <I>identifier</I>
</PRE>
For example, a standard token <CODE>~sign_promote</CODE> is defined
which gives the older C sign preserving promotion rules.  In addition,
the promotion of an individual type can be specified using: 
<PRE>
	#pragma TenDRA promoted <I>type-id</I> : <I>promoted-type-id</I>
</PRE>
</P>
<P>
The token: 
<PRE>
	~arith_type : ( SIGNED_NAT, SIGNED_NAT ) -&gt; SIGNED_NAT
</PRE>
similarly describes how to form the usual arithmetic result type from
two promoted integral operand types.  For example, the arithmetic
type of <CODE>long</CODE> and <CODE>unsigned int</CODE> may be 
<CODE>long</CODE> or <CODE>unsigned long</CODE> depending on the representation
of these types; that is to say, 
<CODE>~arith_type ( 7, 10 )</CODE> will be <CODE>7</CODE> on some
machines and <CODE>11</CODE> on others. 
</P>
<P>
Any tokenised type declared using: 
<PRE>
	#pragma token VARIETY v # tv
</PRE>
will be represented by a <CODE>SIGNED_NAT</CODE> token with external
name 
<CODE>tv</CODE> corresponding to the encoding of <CODE>v</CODE>. 
Special cases of this are the implementation dependent integral types
which arise naturally within the language.  The external token names
for these types are given below: 
</P>
<CENTER>
<TABLE BORDER>
<TR><TH>Type</TH>   <TH>Token</TH>
<TR><TD ALIGN=CENTER>bool</TD>  <TD ALIGN=CENTER>~cpp.bool</TD>
<TR><TD ALIGN=CENTER>ptrdiff_t</TD> <TD ALIGN=CENTER>ptrdiff_t</TD>
<TR><TD ALIGN=CENTER>size_t</TD> <TD ALIGN=CENTER>size_t</TD>
<TR><TD ALIGN=CENTER>wchar_t</TD> <TD ALIGN=CENTER>wchar_t</TD>
</TABLE>
</CENTER>
<P>
So, for example, a <CODE>sizeof</CODE> expression has shape 
<CODE>~convert ( size_t )</CODE>.  The token <CODE>~cpp.bool</CODE>
is defined in the default implementation, but the other tokens are
defined according to their definitions on the target machine in the
normal API library building mechanism. 
</P>

<HR>
<H3><A NAME="literal">2.6.2. Integer literal types</A></H3>
<P>
The <A HREF="pragma.html#int">type of an integer literal</A> is defined
in terms of the first in a list of possible integral types.  The first
type in which the literal value can be represented gives the type
of the literal.  For small literals it is possible to work out the
type exactly, however for larger literals the result is target dependent.
For example, the literal <CODE>50000</CODE> will have type <CODE>int</CODE>
on machines in which <CODE>50000</CODE> fits into an <CODE>int</CODE>,
and 
<CODE>long</CODE> otherwise.  This target dependent mapping is given
by a series of tokens of the form: 
<PRE>
	~lit_* : ( SIGNED_NAT ) -&gt; SIGNED_NAT
</PRE>
which map a literal value to the representation of an integral type.
The token used depends on the list of possible types, which in turn
depends on the base used to represent the literal and the integer
suffix used, as given in the following table: 
</P>
<CENTER>
<TABLE BORDER>
<TR><TH>Base</TH>
<TH>Suffix</TH>
<TH>Token</TH>
<TH>Types</TH>
<TR><TD ALIGN=CENTER>decimal</TD>
<TD ALIGN=CENTER>none</TD>
<TD ALIGN=CENTER>~lit_int</TD>
<TD ALIGN=CENTER>int, long, unsigned long</TD>
<TR><TD ALIGN=CENTER>octal</TD>
<TD ALIGN=CENTER>none</TD>
<TD ALIGN=CENTER>~lit_hex</TD>
<TD ALIGN=CENTER>int, unsigned int, long, unsigned long</TD>
<TR><TD ALIGN=CENTER>hexadecimal</TD>
<TD ALIGN=CENTER>none</TD>
<TD ALIGN=CENTER>~lit_hex</TD>
<TD ALIGN=CENTER>int, unsigned int, long, unsigned long</TD>
<TR><TD ALIGN=CENTER>any</TD>
<TD ALIGN=CENTER>U</TD>
<TD ALIGN=CENTER>~lit_unsigned</TD>
<TD ALIGN=CENTER>unsigned int, unsigned long</TD>
<TR><TD ALIGN=CENTER>any</TD>
<TD ALIGN=CENTER>L</TD>
<TD ALIGN=CENTER>~lit_long</TD>
<TD ALIGN=CENTER>long, unsigned long</TD>
<TR><TD ALIGN=CENTER>any</TD>
<TD ALIGN=CENTER>UL</TD>
<TD ALIGN=CENTER>~lit_ulong</TD>
<TD ALIGN=CENTER>unsigned long</TD>
<TR><TD ALIGN=CENTER>any</TD>
<TD ALIGN=CENTER>LL</TD>
<TD ALIGN=CENTER>~lit_longlong</TD>
<TD ALIGN=CENTER>long long, unsigned long long</TD>
<TR><TD ALIGN=CENTER>any</TD>
<TD ALIGN=CENTER>ULL</TD>
<TD ALIGN=CENTER>~lit_ulonglong</TD>
<TD ALIGN=CENTER>unsigned long long</TD>
</TABLE>
</CENTER>
<P>
Thus, for example, the shape of the integer literal 50000 is: 
<PRE>
	~convert ( ~lit_int ( 50000 ) )
</PRE>
</P>

<HR>
<H3><A NAME="bitfield">2.6.3. Bitfield types</A></H3>
<P>
The sign of a plain bitfield type, declared without using 
<CODE>signed</CODE> or <CODE>unsigned</CODE>, is left unspecified
in C and C++.  The token: 
<PRE>
	~cpp.bitf_sign : ( SIGNED_NAT ) -&gt; BOOL
</PRE>
is used to give a mapping from integral types to the sign of a plain
bitfield of that type, in a form suitable for use in the TDF 
<CODE>bfvar_bits</CODE> construct.  (Note that <CODE>~cpp.bitf_sign</CODE>
should have been a standard C token but was omitted.) 
</P>

<HR>
<H3><A NAME="pointer">2.6.4. Generic pointers</A></H3>
<P>
TDF has no concept of a generic pointer type, so tokens are used to
defer the representation of <CODE>void *</CODE> and the basic operations
on it to the target machine.  The fundamental token is: 
<PRE>
	~ptr_void : () -&gt; SHAPE
</PRE>
which gives the representation of <CODE>void *</CODE>.  This shape
will be denoted by <CODE>pv</CODE> in the description of the following
tokens.  It is not guaranteed that <CODE>pv</CODE> is a TDF <CODE>pointer</CODE>
shape, although normally it will be implemented as a pointer to a
suitable alignment. 
</P>
<P>
The token: 
<PRE>
	~null_pv : () -&gt; EXP pv
</PRE>
gives the value of a null pointer of type <CODE>void *</CODE>.  Generic
pointers can also be converted to and from other pointers.  These
conversions are represented by the tokens: 
<PRE>
	~to_ptr_void : ( ALIGNMENT a, EXP POINTER a ) -&gt; EXP pv
	~from_ptr_void : ( ALIGNMENT a, EXP pv ) -&gt; EXP POINTER a
</PRE>
where the given alignment describes the destination or source pointer
type.  Finally a generic pointer may be tested against the null pointer
or two generic pointers may be compared.  These operations are represented
by the tokens: 
<PRE>
	~pv_test : ( EXP pv, LABEL, NTEST ) -&gt; EXP TOP
	~cpp.pv_compare : ( EXP pv, EXP pv, LABEL, NTEST ) -&gt; EXP TOP
</PRE>
where the given <CODE>NTEST</CODE> gives the comparison to be applied
and the given label gives the destination to jump to if the test fails.
(Note that <CODE>~cpp.pv_compare</CODE> should have been a standard
C token but was omitted.) 
</P>

<HR>
<H3><A NAME="conv">2.6.5. Undefined conversions</A></H3>
<P>
Several conversions in C and C++ can only be represented by undefined
TDF.  For example, converting a pointer to an integer can only be
represented in TDF by forming a union of the pointer and integer shapes,
putting the pointer into the union and pulling the integer out.  Such
conversions are tokenised.  Undefined conversions not mentioned below
may be performed by combining those given with the standard, well-defined,
conversions. 
</P>
<P>
The token: 
<PRE>
	~ptr_to_ptr : ( ALIGNMENT a, ALIGNMENT b, EXP POINTER a ) -&gt; EXP POINTER b
</PRE>
is used to convert between two incompatible pointer types.  The first
alignment describes the source pointer shape while the second describes
the destination pointer shape.  Note that if the destination alignment
is greater than the source alignment then the source pointer can be
used in most TDF constructs in place of the destination pointer, so
the use of <CODE>~ptr_to_ptr</CODE> can be omitted (the exception
is 
<CODE>pointer_test</CODE> which requires equal alignments).  Base
class pointer conversions are examples of these well-behaved, alignment
preserving conversions. 
</P>
<P>
The tokens: 
<PRE>
	~f_to_pv : ( EXP PROC ) -&gt; EXP pv
	~pv_to_f : ( EXP pv ) -&gt; EXP PROC
</PRE>
are used to convert pointers to functions to and from <CODE>void *</CODE>
(these conversions are not allowed in ISO C/C++ but are in older dialects).
</P>
<P>
The tokens: 
<PRE>
	~i_to_p : ( VARIETY v, ALIGNMENT a, EXP INTEGER v ) -&gt; EXP POINTER a
	~p_to_i : ( ALIGNMENT a, VARIETY v, EXP POINTER a ) -&gt; EXP INTEGER v
	~i_to_pv : ( VARIETY v, EXP INTEGER v ) -&gt; EXP pv
	~pv_to_i : ( VARIETY v, EXP pv ) -&gt; EXP INTEGER v
</PRE>
are used to convert integers to and from <CODE>void *</CODE> and other
pointers. 
</P>

<HR>
<H3><A NAME="div">2.6.6. Integer division</A></H3>
<P>
The precise form of the integer division and remainder operations
in C and C++ is left unspecified with respect to the sign of the result
if either operand is negative.  The tokens: 
<PRE>
	~div : ( EXP INTEGER v, EXP INTEGER v ) -&gt; EXP INTEGER v
	~rem : ( EXP INTEGER v, EXP INTEGER v ) -&gt; EXP INTEGER v
</PRE>
are used to represent integer division and remainder.  They will map
onto one of the pairs of TDF constructs, <CODE>div0</CODE> and <CODE>rem0</CODE>,
<CODE>div1</CODE> and <CODE>rem1</CODE> or <CODE>div2</CODE> and 
<CODE>rem2</CODE>. 
</P>

<HR>
<H3><A NAME="call">2.6.7. Calling conventions</A></H3>
<P>
The function calling conventions used by the C++ producer are essentially
the same as those used by the C producer with one exception.  That
is to say, all types except arrays are passed by value (note that
individual installers may modify these conventions to conform to their
own ABIs). 
</P>
<P>
The exception concerns classes with a non-trivial constructor, destructor
or assignment operator.  These classes are passed as function arguments
by taking a reference to a copy of the object (although it is often
possible to eliminate the copy and pass a reference to the object
directly).  They are passed as function return values by adding an
extra parameter to the start of the function parameters giving a reference
to a location into which the return value should be copied. 
</P>

<H4>Member functions</H4>
<P>
Non-static member functions are implemented in the obvious fashion,
by passing a pointer to the object the method is being applied to
as the first argument (or the second argument if the method has an
extra argument for its return value). 
</P>

<H4><A NAME="ellipsis">Ellipsis functions</A></H4>
<P>
Calls to functions declared with ellipses are via the 
<CODE>apply_proc</CODE> TDF construct, with all the arguments being
treated as non-variable.  However the definition of such a function
uses the <CODE>make_proc</CODE> construct with a variable parameter.
This parameter can be referred to within the program using the 
<A HREF="pragma.html#ellipsis"><CODE>...</CODE> expression</A>.  The
type of this expression is given by the built-in token: 
<PRE>
	~__va_t : () -&gt; SHAPE
</PRE>
The <CODE>va_start</CODE> macro declared in the 
<CODE>&lt;stdarg.h&gt;</CODE> header then describes how the variable
parameter (expressed as <CODE>...</CODE>) can be converted to an expression
of type <CODE>va_list</CODE> suitable for use in the 
<CODE>va_arg</CODE> macro. 
</P>
<P>
Note that the variable parameter is in effect only being used to determine
where the first optional parameter is defined.  The assumption is
that all such parameters are located contiguously on the stack, however
the fact that calls to such functions do not use the variable parameter
mechanism means that this is not automatically the case.  Strictly
speaking this means that the implementation of ellipsis functions
uses undefined behaviour in TDF, however given the non-type-safe function
calling rules in C this is unavoidable and installers need to make
provision for such calls (by dumping any parameters from registers
to the stack if necessary).  Given the theoretically type-safe nature
of C++ it would be possible to avoid such undefined behaviour, but
the need for C-compatible calling conventions prevents this. 
</P>

<HR>
<H3><A NAME="ptr_mem">2.6.8. Pointers to data members</A></H3>
<P>
The representation of, and operations on, pointers to data members
are represented by tokens to allow for a variety of implementations.
It is assumed that all pointers to data members (as opposed to pointers
to function members) are represented by the same shape: 
<PRE>
	~cpp.pm.type : () -&gt; SHAPE
</PRE>
This shape will be denoted by <CODE>pm</CODE> in the description of
the following tokens. 
</P>
<P>
There are two basic methods of constructing a pointer to a data member.
The first is to take the address of a data member of a class.  A data
member is represented in TDF by an expression which gives the offset
of the member from the start of its enclosing <CODE>compound</CODE>
shape (note that it is not possible to take the address of a member
of a virtual base). The mapping from this offset to a pointer to a
data member is given by: 
<PRE>
	~cpp.pm.make : ( EXP OFFSET ) -&gt; EXP pm
</PRE>
The second way of constructing a pointer to a data member is to use
a null pointer to member: 
<PRE>
	~cpp.pm.null : () -&gt; EXP pm
</PRE>
The other fundamental operation on a pointer to data member is to
turn it back into an offset expression which can be added to a pointer
to a class to access a member of that class in a <CODE>.*</CODE> or
<CODE>-&gt*</CODE>
operation.  This is done by the token: 
<PRE>
	~cpp.pm.offset : ( EXP pm, ALIGNMENT a ) -&gt; EXP OFFSET ( a, a )
</PRE>
Note that it is necessary to specify an alignment in order to describe
the shape of the result.  The value of this token is undefined if
the given expression is a null pointer to data member. 
</P>
<P>
A pointer to a data member of a non-virtual base class can be converted
to a pointer to a data member of a derived class.  The reverse conversion
is also possible using <CODE>static_cast</CODE>.  If the base is a
<A HREF="#primary">primary base class</A> then these conversions are
trivial and have no effect.  Otherwise null pointers to data members
are converted to null pointers to data members, and the non-null cases
are handled by the tokens: 
<PRE>
	~cpp.pm.cast : ( EXP pm, EXP OFFSET ) -&gt; EXP pm
	~cpp.pm.uncast : ( EXP pm, EXP OFFSET ) -&gt; EXP pm
</PRE>
where the given offset is the offset of the base class within the
derived class.  It is also possible to convert between any two pointers
to data members using <CODE>reinterpret_cast</CODE>.  This conversion
is implied by the equality of representation between any two pointers
to data members and has no effect. 
</P>
<P>
The only remaining operations on pointer to data members are to test
one against the null pointer to data member and to compare two pointer
to data members.  These are represented by the tokens: 
<PRE>
	~cpp.pm.test : ( EXP pm, LABEL, NTEST ) -&gt; EXP TOP
	~cpp.pm.compare : ( EXP pm, EXP pm, LABEL, NTEST ) -&gt; EXP TOP
</PRE>
where the given <CODE>NTEST</CODE> gives the comparison to be applied
and the given label gives the destination to jump to if the test fails.
</P>
<P>
In the default implementation, pointers to data members are implemented
as <CODE>int</CODE>.  The null pointer to member is represented by
0 and the address of a class member is represented by 1 plus the offset
of the member (in bytes).  Casting to and from a derived class then
correspond to adding or subtracting the base class offset (in bytes),
and pointer to member comparisons correspond to integer comparisons.
</P>

<HR>
<H3><A NAME="ptr_mem_func">2.6.9. Pointers to function members</A></H3>
<P>
As with pointers to data members, pointers to function members and
the operations on them are represented by tokens to allow for a range
of implementations.  All pointers to function members are represented
by the same shape: 
<PRE>
	~cpp.pmf.type : () -&gt; SHAPE
</PRE>
This shape will be denoted by <CODE>pmf</CODE> in the description
of the following tokens.  Many of the tokens take an expression which
has a shape which is a pointer to the alignment of <CODE>pmf</CODE>.
This will be denoted by <CODE>ppmf</CODE>. 
</P>
<P>
There are two basic methods for constructing a pointer to a function
member.  The first is to take the address of a non-static member function
of a class.  There are two cases, depending on whether or not the
member function is virtual.  The non-virtual case is given by the
token: 
<PRE>
	~cpp.pmf.make : ( EXP PROC, EXP OFFSET, EXP OFFSET ) -&gt; EXP pmf
</PRE>
where the first argument is the address of the corresponding function,
the second argument gives any base class offset which is to be added
when calling this function (to deal with inherited member functions),
and the third argument is a zero offset. 
</P>
<P>
For virtual functions, a pointer to function member of the form above
is entered in the <A HREF="#vtable">virtual function table</A> for
the corresponding class.  The actual pointer to the virtual function
member then gives a reference into the virtual function table as follows:
<PRE>
	~cpp.pmf.vmake : ( SIGNED_NAT, EXP OFFSET, EXP, EXP ) -&gt; EXP pmf
</PRE>
where the first argument gives the index of the function within the
virtual function table, the second argument gives the offset of the
<I>vptr</I> field within the class, and the third and fourth arguments
are zero offsets. 
</P>
<P>
The second way of constructing a pointer to a function member is to
use a null pointer to function member: 
<PRE>
	~cpp.pmf.null : () -&gt; EXP pmf
	~cpp.pmf.null2 : () -&gt; EXP pmf
</PRE>
For technical reasons there are two versions of this token, although
they have the same value.  The first token is used in static initialisers;
the second token is used in other expressions. 
<P>
The cast operations on pointers to function members are more complex
than those on pointers to data members.  The value to be cast is copied
into a temporary and one of the tokens: 
<PRE>
	~cpp.pmf.cast : ( EXP ppmf, EXP OFFSET, EXP, EXP OFFSET ) -&gt; EXP TOP
	~cpp.pmf.uncast : ( EXP ppmf, EXP OFFSET, EXP, EXP OFFSET ) -&gt; EXP TOP
</PRE>
is applied to modify the value of the temporary according to the given
cast.  The first argument gives the address of the temporary, the
second gives the base class offset to be added or subtracted, the
third gives the number to be added or subtracted to convert virtual
function indexes for the base class into virtual function indexes
for the derived class, and the fourth gives the offset of the <I>vptr</I>
field within the class.  Again, the ability to use <CODE>reinterpret_cast</CODE>
to convert between any two pointer to function member types arises
because of the uniform representation of these types. 
</P>
<P>
As with pointers to data members, there are tokens implementing comparisons
on pointers to function members: 
<PRE>
	~cpp.pmf.test : ( EXP ppmf, LABEL, NTEST ) -&gt; EXP TOP
	~cpp.pmf.compare : ( EXP ppmf, EXP ppmf, LABEL, NTEST ) -&gt; EXP TOP
</PRE>
Note however that the arguments are passed by reference. 
</P>
<P>
The most important, and most complex, operation is calling a function
through a pointer to function member.  The first step is to copy the
pointer to function member into a temporary.  The token: 
<PRE>
	~cpp.pmf.virt : ( EXP ppmf, EXP, ALIGNMENT ) -&gt; EXP TOP
</PRE>
is then applied to the temporary to convert a pointer to a virtual
function member to a normal pointer to function member by looking
it up in the corresponding virtual function table.  The first argument
gives the address of the temporary, the second gives the object to
which the function is to be applied, and the third gives the alignment
of the corresponding class.  Now the base class conversion to be applied
to the object can be determined by applying the token: 
<PRE>
	~cpp.pmf.delta : ( ALIGNMENT a, EXP ppmf ) -&gt; EXP OFFSET ( a, a )
</PRE>
to the temporary to find the offset to be added.  Finally the function
to be called can be extracted from the temporary using the token:
<PRE>
	~cpp.pmf.func : ( EXP ppmf ) -&gt; EXP PROC
</PRE>
The function call then procedes as normal. 
</P>
<P>
The default implementation is that described in the ARM, where each
pointer to function member is represented in the form: 
<PRE>
	struct PTR_MEM_FUNC {
	    short delta ;
	    short index ;
	    union {
		void ( *func ) () ;
		short off ;
	    } u ;
	} ;
</PRE>
The <CODE>delta</CODE> field gives the base class offset (in bytes)
to be added before applying the function.  The <CODE>index</CODE>
field is 0 for null pointers, -1 for non-virtual function pointers
and the index into the virtual function table for virtual function
pointers (as described below these indexes start from 1).  For non-virtual
function pointers the function itself is given by the <CODE>u.func</CODE>
field. For virtual function pointers the offset of the <I>vptr</I>
field within the class is given by the <CODE>u.off</CODE> field. 
</P>

<HR>
<H3><A NAME="class">2.6.10. Class layout</A></H3>
<P>
Consider a class with no base classes: 
<PRE>
	class A {
	    // A's members
	} ;
</PRE>
Each object of class <I>A</I> needs its own copy of the non-static
data members of <I>A</I> and, for polymorphic types, a means of referencing
the virtual function table and run-time type information for <I>A</I>.
This is accomplished using a layout of the form: 
<CENTER>
<IMG SRC="../images/class.gif" ALT="class A">
</CENTER>
where the <I>A</I> component consists of the non-static data members
and 
<I>vptr A</I> is a pointer to the virtual function table for <I>A</I>.
For non-polymorphic classes the <I>vptr A</I> field is omitted; otherwise
space for <I>vptr A</I> needs to be allocated within the class and
the pointer needs to be initialised in each constructor for <I>A</I>.
The precise layout of the <A HREF="#vtable">virtual function table</A>
and the <A HREF="#rtti">run-time type information</A> is given below.
</P>
<P>
Two alternative ways of laying out the non-static data members within
the class are implemented.  The first, which is default, gives them
in the order in which they are declared in the class definition. 
The second lays out the <CODE>public</CODE>, the <CODE>protected</CODE>,
and the <CODE>private</CODE> members in three distinct sections, the
members within each section being given in the order in which they
are declared. The latter can be enabled using the <CODE>-jo</CODE>
command-line option. 
</P>
<P>
The offset of each member within the class (including <I>vptr A</I>)
can be calculated in terms of the offset of the previous member. 
The first member has offset zero.  The offset of any other member
is given by the offset of the previous member plus the size of the
previous member, rounded up to the alignment of the current member.
The overall size of the class is given by the offset of the last member
plus the size of the last member, rounded up using the token: 
<PRE>
	~comp_off : ( EXP OFFSET ) -&gt; EXP OFFSET
</PRE>
which allows for any target dependent padding at the end of the class.
The shape of the class is then a <CODE>compound</CODE> shape with
this offset. 
</P>
<P>
Classes with no members need to be treated slightly differently. 
The shape of such a class is given by the token: 
<PRE>
	~cpp.empty.shape : () -&gt; SHAPE
</PRE>
(recall that an empty class still has a nonzero size).  The token:
<PRE>
	~cpp.empty.offset : () -&gt; EXP OFFSET
</PRE>
is used to represent the offset required for an empty class when it
is used as a base class.  This may be a zero offset. 
</P>
<P>
Bitfield members provide a slight complication to the picture above.
The offset of a bitfield is additionally padded using the token: 
<PRE>
	~pad : ( EXP OFFSET, SHAPE, SHAPE ) -&gt; EXP OFFSET
</PRE>
where the two shapes give the type underlying the bitfield and the
bitfield itself. 
</P>
<P>
The layout of unions is similar to that of classes except that all
members have zero offset, and the size of the union is the maximum
of the sizes of its members, suitably padded.  Of course unions cannot
be polymorphic and cannot have base classes. 
</P>
<P>
Pointers to incomplete classes are represented by means of the alignment:
<PRE>
	~cpp.empty.align : () -&gt; ALIGNMENT
</PRE>
This token is also used for the alignment of a complete class if that
class is never used in the generated TDF in a manner which requires
it to be complete.  This can lead to savings on the size of the generated
code by preventing the need to define all the member offset tokens
in order to find the shape of the class. 
</P>

<HR>
<H3><A NAME="derive">2.6.11. Derived class layout</A></H3>
<P>
The description of the implementation of derived classes will be given
in terms of the example class hierarchy given by: 
<PRE>
	class A {
	    // A's members
	} ;

	class B : public A {
	    // B's members
	} ;

	class C : public A {
	    // C's members
	} ;

	class D : public B, public C {
	    // D's members
	} ;
</PRE>
or, as a directed acyclic graph: 
<CENTER>
<IMG SRC="../images/graph.gif" ALT="class D">
</CENTER>

<H4>Single inheritance</H4>
<P>
The layout of class <I>A</I> is given by: 
<CENTER>
<IMG SRC="../images/classA.gif" ALT="class A">
</CENTER>
as above.  Class <I>B</I> inherits all the members of class <I>A</I>
plus those members explicitly declared within class <I>B</I>.  In
addition, class <I>B</I> inherits all the virtual member functions
of <I>A</I>, some of which may be overridden in <I>B</I>, extended
by any additional virtual functions declared in <I>B</I>.  This may
be represented as follows: 
<CENTER>
<IMG SRC="../images/classB.gif" ALT="class B">
</CENTER>
where <I>A</I> denotes those members inherited from the base class
and 
<I>B</I> denotes those members added in the derived class.  Note that
an object of class <I>B</I> contains a sub-object of class <I>A</I>.
The fact that this sub-object is located at the start of <I>B</I>
means that the base class conversion from <I>B</I> to <I>A</I> is
trivial.  Any base class with this property is called a 
<A NAME="primary">primary base class</A>. 
</P>
<P>
Note that in theory two virtual function tables are required, the
normal virtual function table for <I>B</I>, denoted by <I>vtbl B</I>,
and a modified virtual function table for <I>A</I>, denoted by <I>vtbl
B::A</I>, taking into account any overriding virtual functions within
<I>B</I>, and pointing to <I>B</I>'s run-time type information.  This
latter means that the dynamic type information for the <I>A</I> sub-object
relates to 
<I>B</I> rather than <I>A</I>.  However these two tables can usually
be combined - if the virtual functions added in <I>B</I> are listed
in the virtual function table after those inherited from <I>A</I>
and the form of the overriding is <A HREF="#override">suitably well
behaved</A>
(in the sense defined below) then <I>vptr B::A</I> is an initial segment
of <I>vptr B</I>.  It is also possible to remove the <I>vptr B</I>
field and use <I>vptr B::A</I> in its place in this case (it has to
be this way round to preserve the <I>A</I> sub-object).  Thus the
items shaded in the diagram can be removed. 
</P>
<P>
The class <I>C</I> is similarly given by: 
<CENTER>
<IMG SRC="../images/classC.gif" ALT="class C">
</CENTER>
</P>

<H4>Multiple inheritance</H4>
<P>
Class <I>D</I> is more complex because of the presence of multiple
inheritance.  <I>D</I> inherits all the members of <I>B</I>, including
those which <I>B</I> inherits from <I>A</I>, plus all the members
of 
<I>C</I>, including those which <I>C</I> inherits from <I>A</I>. 
It also inherits all of the virtual member functions from <I>B</I>
and 
<I>C</I>, some of which may be overridden in <I>D</I>, extended by
any additional virtual functions declared in <I>D</I>.  This may be
represented as follows: 
<CENTER>
<IMG SRC="../images/classD.gif" ALT="class D">
</CENTER>
Note that there are two copies of <I>A</I> in <I>D</I> because virtual
inheritance has not been used. 
</P>
<P>
The <I>B</I> base class of <I>D</I> is essentially similar to the
single inheritance case already discussed; the <I>C</I> base class
is different however.  Note firstly that the <I>C</I> sub-object of
<I>D</I> is located at a non-zero offset, <I>delta D::C</I>, from
the start of the object. This means that the base class conversion
from <I>D</I> to <I>C</I>
consists of adding this offset (for pointer conversions things are
further complicated by the need to allow for null pointers).  Also
<I>vtbl D::C</I> is not an initial segment of <I>vtbl D</I> because
this contains the virtual functions inherited from <I>B</I> first,
followed by those inherited from <I>C</I>, followed by those first
declared in <I>D</I> (there are <A HREF="#override">other reasons</A>
as well).  Thus <I>vtbl D::C</I> cannot be eliminated. 
</P>

<H4>Virtual inheritance</H4>
<P>
Virtual inheritance introduces a further complication.  Now consider
the class hierarchy given by: 
<PRE>
	class A {
	    // A's members
	} ;

	class B : virtual public A {
	    // B's members
	} ;

	class C : virtual public A {
	    // C's members
	} ;

	class D : public B, public C {
	    // D's members
	} ;
</PRE>
or, as a <A NAME="diamond">directed acyclic graph</A>: 
<CENTER>
<IMG SRC="../images/diamond.gif" ALT="class D">
</CENTER>
As before <I>A</I> is given by: 
<CENTER>
<IMG SRC="../images/classA.gif" ALT="class A">
</CENTER>
but now <I>B</I> is given by: 
<CENTER>
<IMG SRC="../images/virtualB.gif" ALT="class B">
</CENTER>
Rather than having the sub-object of class <I>A</I> directly as part
of 
<I>B</I>, the class now contains a pointer, <I>ptr A</I>, to this
sub-object.  The virtual sub-objects are always located at the end
of a class layout; their offset may therefore vary for different objects,
however the offset for <I>ptr A</I> is always fixed.  The <I>ptr A</I>
field is initialised in each constructor for <I>B</I>.  In order to
perform the base class conversion from <I>B</I> to <I>A</I>, the contents
of <I>ptr A</I> are taken (again provision needs to be made for null
pointers in pointer conversions).  In cases when the dynamic type
of the <I>B</I> object can be determined statically it is possible
to access the <I>A</I> sub-object directly by adding a suitable offset.
Because this conversion is non-trivial (see <A HREF="#override">below</A>)
the virtual function table <I>vtbl B::A</I> is not an initial segment
of 
<I>vtbl B</I> and cannot be eliminated. 
</P>
<P>
The class <I>C</I> is similarly given by: 
<CENTER>
<IMG SRC="../images/virtualC.gif" ALT="class C">
</CENTER>
Now the class <I>D</I> is given by: 
<CENTER>
<IMG SRC="../images/virtualD.gif" ALT="class D">
</CENTER>
Note that there is a single <I>A</I> sub-object of <I>D</I> referenced
by the <I>ptr A</I> fields in both the <I>B</I> and <I>C</I> sub-objects.
The elimination of <I>vtbl D::B</I> is as above. 
</P>

<HR>
<H3><A NAME="constr">2.6.12. Constructors and destructors</A></H3>
<P>
The implementation of constructors and destructors, whether explicitly
or implicitly defined, is slightly more complex than that of other
member functions.  For example, the constructors need to set up the
internal <I>vptr</I> and <I>ptr</I> fields mentioned above. 
</P>
<P>
The order of initialisation in a constructor is as follows: 
<OL>
<LI>The internal <I>ptr</I> fields giving the locations of the virtual
base classes are initialised. 
<LI>The constructors for the virtual base classes are called. 
<LI>The constructors for the non-virtual direct base classes are called.
<LI>The internal <I>vptr</I> fields giving the locations of the virtual
function tables are initialised. 
<LI>The constructors for the members of the class are called. 
<LI>The main constructor body is executed. 
</OL>
To ensure that each virtual base is only initialised once, if a class
has a virtual base class then all its constructors have an implicit
extra parameter of type <CODE>int</CODE>.  The first two steps above
are then only applied if this flag is nonzero.  In normal applications
of the constructor this argument will be 1, however in base class
initialisations such as those in the third and fourth steps above,
it will be 0. 
</P>
<P>
Note that similar steps to protect virtual base classes are not taken
in an implicitly declared <CODE>operator=</CODE> function.  The order
of assignment in this case is as follows: 
<OL>
<LI>The assignment operators for the direct base classes (both virtual
and non-virtual) are called. 
<LI>The assignment operators for the members of the class are called.
<LI>A reference to the object assigned to (i.e. <CODE>*this</CODE>)
is     returned. 
</OL>
</P>
<P>
The order of destruction in a destructor is essentially the reverse
of the order of construction: 
<OL>
<LI>The main destructor body is executed. 
<LI>The destructor for the members of the class are called. 
<LI>The internal <I>vptr</I> fields giving the locations of the virtual
function tables are re-initialised. 
<LI>The destructors for the non-virtual direct base classes are called.
<LI>The destructors for the virtual base classes are called. 
<LI>If necessary the space occupied by the object is deallocated.
</OL>
All destructors have an extra parameter of type <CODE>int</CODE>.
The virtual base classes are only destroyed if this flag is nonzero
when and-ed with 2.  The space occupied by the object is only deallocated
if this flag is nonzero when and-ed with 1.  This deallocation is
equivalent to inserting:  
<PRE>
	delete this ;
</PRE>
in the destructor.  The <CODE>operator delete</CODE> function is called
via the destructor in this way in order to implement the pseudo-virtual
nature of these deallocation functions.  Thus for normal destructor
calls the extra argument is 2, for base class destructor calls it
is 0, and for calls arising from a <CODE>delete</CODE> expression
it is 3. 
</P>
<P>
The point at which the virtual function tables are initialised in
the constructor, and the fact that they are re-initialised in the
destructor, is to ensure that virtual functions called from base class
initialisers are handled correctly (see ISO C++ 12.7). 
</P>
<P>
A further complication arises from the need to destroy 
<A NAME="partial">partially constructed objects</A> if an exception
is thrown in a constructor.  A count is maintained of the number of
base classes and members constructed within a constructor.  If an
exception is thrown then it is caught in the constructor, the constructed
base classes and members are destroyed, and the exception is re-thrown.
The count variable is used to determine which bases and members need
to be destroyed. 
</P>
<P>
<IMG SRC="../images/warn.gif" ALT="warning"> These partial destructors
currently do not interact correctly with any exception specification
on the constructor.  Exceptions thrown within destructors are not
correctly handled either. 
</P>

<HR>
<H3><A NAME="vtable">2.6.13. Virtual function tables</A></H3>
<P>
The virtual functions in a polymorphic class are given in its virtual
function table in the following order: firstly those virtual functions
inherited from its direct base classes (which may be overridden in
the derived class) followed by those first declared in the derived
class in the order in which they are declared.  Note that this can
result in virtual functions inherited from virtual base classes appearing
more than once.  The virtual functions are numbered from 1 (this is
slightly more convenient than numbering from 0 in the default implementation).
</P>
<P>
The virtual function table for this class has shape: 
<PRE>
	~cpp.vtab.type : ( NAT ) -&gt; SHAPE
</PRE>
the argument being <I>n + 1</I> where <I>n</I> is the number of virtual
functions in the class (there is also a token: 
<PRE>
	~cpp.vtab.diag : () -&gt; SHAPE
</PRE>
which is used in the diagnostic output for a generic virtual function
table).  The table is created using the token: 
<PRE>
	~cpp.vtab.make : ( EXP pti, EXP OFFSET, NAT, EXP NOF ) -&gt; EXP vt
</PRE>
where the first expression gives the address of the <A HREF="#rtti">run-time
type information structure</A> for the class, the second expression
gives the offset of the <I>vptr</I> field within the class (i.e. <I>voff</I>),
the integer constant is <I>n + 1</I>, and the final expression is
a 
<CODE>make_nof</CODE> construct giving information on each of the
<I>n</I>
virtual functions. 
</P>
<P>
The information given on each virtual function in this table has the
form of a <A HREF="#ptr_mem_func">pointer to function member</A> formed
using the token: 
<PRE>
	~cpp.pmf.make : ( EXP PROC, EXP OFFSET, EXP OFFSET ) -&gt; EXP pmf
</PRE>
as above, except that the third argument gives the offset of the base
class in virtual function tables such as <I>vtbl B::A</I>.  For pure
virtual functions the function pointer in this token is given by:
<PRE>
	~cpp.vtab.pure : () -&gt; EXP PROC
</PRE>
In the default implementation this gives a function 
<CODE>__TCPPLUS_pure</CODE> which just calls <CODE>abort</CODE>. 
</P>
<P>
To avoid duplicate copies of virtual function tables and run-time
type information structures being created, the ARM algorithm is used.
The virtual function table and run-time type information structure
for a class are defined in the module containing the definition of
the first non-inline, non-pure virtual function declared in that class.
If such a function does not exist then duplicate copies are created
in every module which requires them.  In the former case the virtual
function table will have an <A HREF="#other">external tag name</A>;
in the latter case it will be an internal tag.  This scheme can be
overridden using the <CODE>-jv</CODE> command-line option, which causes
local virtual function tables to be output for all classes. 
</P>
<P>
Note that the discussion above applies to both simple virtual function
tables, such as <I>vtbl B</I> above, and to those arising from base
classes, such as <I>vtbl B::A</I>.  <A NAME="override">We are now
in a position to precisely determine when <I>vtbl B::A</I> is an initial
segment of <I>vtbl B</I> and hence can be eliminated</A>.  Firstly,
<I>A</I> must be the first direct base class of <I>B</I> and cannot
be virtual.  This is to ensure both that there are no virtual functions
in <I>vtbl B</I> before those inherited from <I>A</I>, and that the
corresponding base class conversion is trivial so that the pointers
to function members of <I>B</I> comprising the virtual function table
can be equally regarded as pointers to function members of <I>A</I>.
The second requirement is that if a virtual function for <I>A</I>,
<I>f</I>, is overridden in <I>B</I> then the return type for <I>B::f</I>
cannot differ from the return type for <I>A::f</I> by a non-trivial
conversion (recall that ISO C++ allows the return types to differ
by a base class conversion).  In the non-trivial conversion case the
function entered in <I>vtbl B::A</I> needs to be, not <I>B::f</I>
as in <I>vtbl B</I>, but a stub function which calls <I>B::f</I> and
converts its return value to the return type of <I>A::f</I>. 
</P>

<H4>Calling virtual functions</H4>
<P>
The virtual function call mechanism is implemented using the token:
<PRE>
	~cpp.vtab.func : ( EXP ppvt, SIGNED_NAT ) -&gt; EXP ppmf
</PRE>
which has as its arguments a reference to the <I>vptr</I> field of
the object the function is to be called for, and the number of the
virtual function to be called.  It returns a reference to the corresponding
pointer to function member within the object's virtual function table.
The function is then called by extracting the base class offset to
be added, and the function to be called, from this reference using
the tokens: 
<PRE>
	~cpp.pmf.delta : ( ALIGNMENT a, EXP ppmf ) -&gt; EXP OFFSET ( a, a )
	~cpp.pmf.func : ( EXP ppmf ) -&gt; EXP PROC
</PRE>
described as part of the <A HREF="#ptr_mem_func">pointer to function
member call mechanism</A> above. 
</P>

<HR>
<H3><A NAME="rtti">2.6.14. Run-time type information</A></H3>
<P>
Each C++ type can be associated with a run-time type information structure
giving information about that type.  These type information structures
have shape given by the token: 
<PRE>
	~cpp.typeid.type : () -&gt; SHAPE
</PRE>
which corresponds to the representation for the standard type 
<CODE>std::type_info</CODE> declared in the header 
<CODE>&lt;typeinfo&gt;</CODE>.  Each type information structure consists
of a tag number, giving information on the kind of type represented,
a string literal, giving the name of the type, and a pointer to a
list of base type information structures.  These are combined to give
a type information structure using the token: 
<PRE>
	~cpp.typeid.make : ( SIGNED_NAT, EXP, EXP ) -&gt; EXP ti
</PRE>
Each base type information structure has shape given by the token:
<PRE>
	~cpp.baseid.type : () -&gt; SHAPE
</PRE>
It consists of a pointer to a type information structure, an expression
used to describe the offset of a base class, a pointer to the next
base type information structure in the list, and two integers giving
information on type qualifiers etc.  These are combined to give a
base type information structure using the token: 
<PRE>
	~cpp.baseid.make : ( EXP, EXP, EXP, SIGNED_NAT, SIGNED_NAT ) -&gt; EXP bi
</PRE>
</P>
<P>
The following table gives the various tag numbers used in type information
structures plus a list of the base type information structures associated
with each type.  Macros giving these tag numbers are provided in the
default implementation in a header, <CODE>interface.h</CODE>, which
is shared by the C++ producer. 
</P>
<P>
<CENTER>
<TABLE BORDER>
<TR><TH>Type</TH>
<TH>Form</TH>
<TH>Tag</TH>
<TH>Base information</TH>
<TR><TD ALIGN=CENTER>integer</TD>
<TD ALIGN=CENTER>-</TD>
<TD ALIGN=CENTER>0</TD>
<TD ALIGN=CENTER>-</TD>
<TR><TD ALIGN=CENTER>floating point</TD>
<TD ALIGN=CENTER>-</TD>
<TD ALIGN=CENTER>1</TD>
<TD ALIGN=CENTER>-</TD>
<TR><TD ALIGN=CENTER>void</TD>
<TD ALIGN=CENTER>-</TD>
<TD ALIGN=CENTER>2</TD>
<TD ALIGN=CENTER>-</TD>
<TR><TD ALIGN=CENTER>class or struct</TD>
<TD ALIGN=CENTER>class T</TD>
<TD ALIGN=CENTER>3</TD>
<TD ALIGN=CENTER>[base,access,virtual], ....</TD>
<TR><TD ALIGN=CENTER>union</TD>
<TD ALIGN=CENTER>union T</TD>
<TD ALIGN=CENTER>4</TD>
<TD ALIGN=CENTER>-</TD>
<TR><TD ALIGN=CENTER>enumeration</TD>
<TD ALIGN=CENTER>enum T</TD>
<TD ALIGN=CENTER>5</TD>
<TD ALIGN=CENTER>-</TD>
<TR><TD ALIGN=CENTER>pointer</TD>
<TD ALIGN=CENTER>cv T *</TD>
<TD ALIGN=CENTER>6</TD>
<TD ALIGN=CENTER>[T,cv,0]</TD>
<TR><TD ALIGN=CENTER>reference</TD>
<TD ALIGN=CENTER>cv T &amp;</TD>
<TD ALIGN=CENTER>7</TD>
<TD ALIGN=CENTER>[T,cv,0]</TD>
<TR><TD ALIGN=CENTER>pointer to member</TD>
<TD ALIGN=CENTER>cv T S::*</TD>
<TD ALIGN=CENTER>8</TD>
<TD ALIGN=CENTER>[S,0,0], [T,cv,0]</TD>
<TR><TD ALIGN=CENTER>array</TD>
<TD ALIGN=CENTER>cv T [n]</TD>
<TD ALIGN=CENTER>9</TD>
<TD ALIGN=CENTER>[T,cv,n]</TD>
<TR><TD ALIGN=CENTER>bitfield</TD>
<TD ALIGN=CENTER>cv T : n</TD>
<TD ALIGN=CENTER>10</TD>
<TD ALIGN=CENTER>[T,cv,n]</TD>
<TR><TD ALIGN=CENTER>C++ function</TD>
<TD ALIGN=CENTER>cv T ( S1, ...., Sn )</TD>
<TD ALIGN=CENTER>11</TD>
<TD ALIGN=CENTER>[T,cv,0], [S1,0,0], ...., [Sn,0,0]</TD>
<TR><TD ALIGN=CENTER>C function</TD>
<TD ALIGN=CENTER>cv T ( S1, ...., Sn )</TD>
<TD ALIGN=CENTER>12</TD>
<TD ALIGN=CENTER>[T,cv,0], [S1,0,0], ...., [Sn,0,0]</TD>
</TABLE>
</CENTER>
</P>
<P>
In the form column <CODE>cv T</CODE> is used to denote not only the
normal cv-qualifiers but, when <CODE>T</CODE> is a function type,
the member function cv-qualifiers.  Arrays with an unspecified bound
are treated as if their bound was zero.  Functions with ellipsis are
treated as if they had an extra parameter of a dummy type named 
<CODE>...</CODE> (see below).  Note the distinction between C++ and
C function types. 
</P>
<P>
Each base type information structure is described as a triple consisting
of a type and two integers.  One of these integers may be used to
encode a type qualifier, <CODE>cv</CODE>, as follows: 
</P>
<P>
<CENTER>
<TABLE BORDER>
<TR><TH>Qualifier</TH>   <TH>Encoding</TH>
<TR><TD ALIGN=CENTER>none</TD>  <TD ALIGN=CENTER>0</TD>
<TR><TD ALIGN=CENTER>const</TD>  <TD ALIGN=CENTER>1</TD>
<TR><TD ALIGN=CENTER>volatile</TD> <TD ALIGN=CENTER>2</TD>
<TR><TD ALIGN=CENTER>const volatile</TD><TD ALIGN=CENTER>3</TD>
</TABLE>
</CENTER>
</P>
<P>
The base type information for a class consists of information on each
of its direct base classes.  The includes the offset of this base
within the class (for a virtual base class this is the offset of the
corresponding 
<I>ptr</I> field), whether the base is virtual (1) or not (0), and
the base class access, encoded as follows: 
</P>
<P>
<CENTER>
<TABLE BORDER>
<TR><TH>Access</TH>   <TH>Encoding</TH>
<TR><TD ALIGN=CENTER>public</TD> <TD ALIGN=CENTER>0</TD>
<TR><TD ALIGN=CENTER>protected</TD> <TD ALIGN=CENTER>1</TD>
<TR><TD ALIGN=CENTER>private</TD> <TD ALIGN=CENTER>2</TD>
</TABLE>
</CENTER>
</P>
<P>
For example, the run-time type information structures for the classes
declared in the <A HREF="#diamond">diamond lattice</A> above can be
represented as follows: 
<CENTER>
<IMG SRC="../images/rttiD.gif" ALT="typeid D">
</CENTER>
</P>

<H4>Defining run-time type information structures</H4>
<P>
For built-in types, the run-time type information structure may be
referenced by the token: 
<PRE>
	~cpp.typeid.basic : ( SIGNED_NAT ) -&gt; EXP pti
</PRE>
where the argument gives the encoding of the type as given in the
following table: 
</P>
<CENTER>
<TABLE BORDER>
<TR><TH>Type</TH>   <TH>Encoding</TH>
<TH>Type</TH>   <TH>Encoding</TH>
<TR><TD ALIGN=CENTER>char</TD>  <TD ALIGN=CENTER>0</TD>
<TD ALIGN=CENTER>unsigned long</TD> <TD ALIGN=CENTER>11</TD>
<TR><TD ALIGN=CENTER>(error)</TD> <TD ALIGN=CENTER>1</TD>
<TD ALIGN=CENTER>float</TD>  <TD ALIGN=CENTER>12</TD>
<TR><TD ALIGN=CENTER>void</TD>  <TD ALIGN=CENTER>2</TD>
<TD ALIGN=CENTER>double</TD> <TD ALIGN=CENTER>13</TD>
<TR><TD ALIGN=CENTER>(bottom)</TD> <TD ALIGN=CENTER>3</TD>
<TD ALIGN=CENTER>long double</TD> <TD ALIGN=CENTER>14</TD>
<TR><TD ALIGN=CENTER>signed char</TD> <TD ALIGN=CENTER>4</TD>
<TD ALIGN=CENTER>wchar_t</TD> <TD ALIGN=CENTER>16</TD>
<TR><TD ALIGN=CENTER>signed short</TD> <TD ALIGN=CENTER>5</TD>
<TD ALIGN=CENTER>bool</TD>  <TD ALIGN=CENTER>17</TD>
<TR><TD ALIGN=CENTER>signed int</TD> <TD ALIGN=CENTER>6</TD>
<TD ALIGN=CENTER>(ptrdiff_t)</TD> <TD ALIGN=CENTER>18</TD>
<TR><TD ALIGN=CENTER>signed long</TD> <TD ALIGN=CENTER>7</TD>
<TD ALIGN=CENTER>(size_t)</TD> <TD ALIGN=CENTER>19</TD>
<TR><TD ALIGN=CENTER>unsigned char</TD> <TD ALIGN=CENTER>8</TD>
<TD ALIGN=CENTER>(...)</TD>  <TD ALIGN=CENTER>20</TD>
<TR><TD ALIGN=CENTER>unsigned short</TD><TD ALIGN=CENTER>9</TD>
<TD ALIGN=CENTER>signed long long</TD>
<TD ALIGN=CENTER>23</TD>
<TR><TD ALIGN=CENTER>unsigned int</TD> <TD ALIGN=CENTER>10</TD>
<TD ALIGN=CENTER>unsigned long long</TD>
<TD ALIGN=CENTER>27</TD>
</TABLE>
</CENTER>
<P>
Note that the encoding for the basic integral types is the same as
that 
<A HREF="#arith">given above</A>.  The other types are assigned to
unused values.  Note that the encodings for <CODE>ptrdiff_t</CODE>
and 
<CODE>size_t</CODE> are not used, instead that for their implementation
is used (using the standard tokens <CODE>ptrdiff_t</CODE> and 
<CODE>size_t</CODE>).  The encodings for <CODE>bool</CODE> and 
<CODE>wchar_t</CODE> are used because they are conceptually distinct
types even though they are implemented as one of the basic integral
types.  The type labelled <CODE>...</CODE> is the dummy used in the
representation of ellipsis functions.  The default implementation
uses an array of type information structures, <CODE>__TCPPLUS_typeid</CODE>,
to implement <CODE>~cpp.typeid.basic</CODE>. 
</P>
<P>
The run-time type information structures for classes are defined in
the same place as their <A HREF="#vtable">virtual function tables</A>.
Other run-time type information structures are defined in whatever
modules require them.  In the former case the type information structure
will have an <A HREF="#other">external tag name</A>; in the latter
case it will be an internal tag. 
</P>

<H4>Accessing run-time type information</H4>
<P>
The primary means of accessing the run-time type information for an
object is using the <CODE>typeid</CODE> construct.  In cases where
the operand type can be determined statically, the address of the
corresponding type information structure is returned.  In other cases
the token: 
<PRE>
	~cpp.typeid.ref : ( EXP ppvt ) -&gt; EXP pti
</PRE>
is used, where the argument gives a reference to the <I>vptr</I> field
of the object being checked.  From this information it is trivial
to trace the corresponding type information. 
</P>
<P>
Another means of querying the run-time type information for an object
is using the <CODE>dynamic_cast</CODE> construct.  When the result
cannot be determined statically, this is implemented using the token:
<PRE>
	~cpp.dynam.cast : ( EXP ppvt, EXP pti ) -&gt; EXP pv
</PRE>
where the first expression gives a reference to the <I>vptr</I> field
of the object being cast and the second gives the run-time type information
for the type being cast to.  In the default implementation this token
is implemented by the procedure <CODE>__TCPPLUS_dynamic_cast</CODE>.
The key point to note is that the virtual function table contains
the offset, <I>voff</I>, of the <I>vptr</I> field from the start of
the most complete object.  Thus it is possible to find the address
of the most complete object.  The run-time type information contains
enough information to determine whether this object has a sub-object
of the type being cast to, and if so, how to find the address of this
sub-object.  The result is returned as a <CODE>void *</CODE>, with
the null pointer indicating that the conversion is not possible. 
</P>

<HR>
<H3><A NAME="init">2.6.15. Dynamic initialisation</A></H3>
<P>
The dynamic initialisation of variables with static storage duration
in C++ is implemented by means of the TDF <CODE>initial_value</CODE>
construct.  However in order for the producer to maintain control
over the order of initialisation, rather than each variable being
initialised separately using <CODE>initial_value</CODE>, a single
expression is created which initialises all the variables in a module,
and this initialiser expression is used to initialise a single dummy
variable using <CODE>initial_value</CODE>.  Note that, while this
enables the variables within a single module to be initialised in
the order in which they are defined, the order of initialisation between
different modules is unspecified. 
</P>
<P>
The implementation needs to keep a list of those variables with static
storage duration which have been initialised so that it can call the
destructors for these objects at the end of the program. This is done
by declaring a variable of shape: 
<PRE>
	~cpp.destr.type : () -&gt; SHAPE
</PRE>
for each such object with a non-trivial destructor.  Each element
of an array is considered a distinct object.  Immediately after the
variable has been initialised the token: 
<PRE>
	~cpp.destr.global : ( EXP pd, EXP POINTER c, EXP PROC ) -&gt; EXP TOP
</PRE>
is called to add the variable to the list of objects to be destroyed.
The first argument is the address of the dummy variable just declared,
the second is the address of the object to be destroyed, and the third
is the destructor to be used.  In this way a list giving the objects
to be destroyed, and the order in which to destroy them, is built
up.  Note that partially constructed objects are destroyed within
their constructors (see <A HREF="#partial">above</A>) so that only
completely constructed objects need to be considered. 
</P>
<P>
The implementation also needs to ensure that it calls the destructors
in this list at the end of the program, including calls of 
<CODE>exit</CODE>.  This is done by calling the token: 
<PRE>
	~cpp.destr.init : () -&gt; EXP TOP
</PRE>
at the start of each <CODE>initial_value</CODE> construct.  In the
default implementation this uses <CODE>atexit</CODE> to register a
function, <CODE>__TCPPLUS_term</CODE>, which calls the destructors.
To aid alternative implementations the token: 
<PRE>
	~cpp.start : () -&gt; EXP TOP
</PRE>
is called at the start of the <CODE>main</CODE> function, however
this has no effect in the default implementation. 
</P>

<HR>
<H3><A NAME="except">2.6.16. Exception handling</A></H3>
<P>
Conceptually, exception handling can be described in terms of the
following diagram: 
<CENTER>
<IMG SRC="../images/try.gif" ALT="try stack">
</CENTER>
At any point in the execution of the program there is a stack of currently
active <CODE>try</CODE> blocks and currently active local variables.
A 
<CODE>try</CODE> block is pushed onto the stack as it is entered and
popped from the stack when it is left (whether directly or via a jump).
A local variable with a non-trivial destructor is pushed onto the
stack just after its constructor has been called at the start of its
scope, and popped from the stack just before its destructor is called
at the end of its scope (including before jumps out of its scope).
Each element of an array is considered a separate object.  Each <CODE>try</CODE>
block has an associated list of handlers.  Each local variable has
an associated destructor. 
</P>
<P>
Provided no exception is thrown this stack grows and shrinks in a
well-behaved manner as execution proceeds.  When an exception is thrown
an exception manager is invoked to find a matching exception handler.
The exception manager proceeds to execute a loop to unwind the stack
as follows.  If the stack is empty then the exception cannot be caught
and 
<CODE>std::terminate</CODE> is called.  Otherwise the top element
is popped from the stack.  If this is a local variable then the associated
destructor is called for the variable.  If the top element is a 
<CODE>try</CODE> block then the current exception is compared in turn
to each of the associated handlers.  If a match is found then execution
jumps to the handler body, otherwise the exception manager continues
to the next element of the stack. 
</P>
<P>
Note that this description is purely conceptual.  There is no need
for exception handling to be implemented by a stack in this way (although
the default implementation uses a similar technique).  It does however
serve to illustrate the various stages which must exist in any implementation.
</P>

<H4>Try blocks</H4>
<P>
At the start of a <CODE>try</CODE> block a variable of shape: 
<PRE>
	~cpp.try.type : () -&gt; SHAPE
</PRE>
is declared corresponding to the stack element for this block.  This
is then initialised using the token: 
<PRE>
	~cpp.try.begin : ( EXP ptb, EXP POINTER fa, EXP POINTER ca ) -&gt; EXP TOP
</PRE>
</P>
where the first argument is a pointer to this variable, the second
argument is the TDF <CODE>current_env</CODE> construct, and the third
argument is the result of the TDF <CODE>make_local_lv</CODE> construct
on the label which is used to mark the first handler associated with
the block.  Note that the last two arguments enable a TDF 
<CODE>long_jump</CODE> construct to be applied to transfer control
to the first handler. 
<P>
When control exits from a <CODE>try</CODE> block, whether by reaching
the end of the block or jumping out of it, the block is removed from
the stack using the token: 
<PRE>
	~cpp.try.end : ( EXP ptb ) -&gt; EXP TOP
</PRE>
where the argument is a pointer to the <CODE>try</CODE> block variable.
</P>

<H4>Local variables</H4>
<P>
The technique used to add a local variable with a non-trivial destructor
to the stack is similar to that used in the dynamic initialisation
of global variables.  A local variable of shape <CODE>~cpp.destr.type</CODE>
is declared at the start of the variable scope.  This is initialised
just after the constructor for the variable is called using the token:
<PRE>
	~cpp.destr.local : ( EXP pd, EXP POINTER c, EXP PROC ) -&gt; EXP TOP
</PRE>
where the first argument is a pointer to the variable being initialised,
the  second is a pointer to the local variable to be destroyed, and
the third is the destructor to be called.  At the end of the variable
scope, just before its destructor is called, the token: 
<PRE>
	~cpp.destr.end : ( EXP pd ) -&gt; EXP TOP
</PRE>
where the argument is a pointer to destructor variable, is called
to remove the local variable destructor from the stack.  Note that
partially constructed objects are destroyed within their constructors
(see 
<A HREF="#partial">above</A>) so that only completely constructed
objects need to be considered. 
</P>
<P>
In cases where the local variable may be conditionally initialised
(for example a temporary variable in the second operand of a <CODE>||</CODE>
operation) the local variable of shape <CODE>~cpp.destr.type</CODE>
is initialised to the value given by the token: 
<PRE>
	~cpp.destr.null : () -&gt; EXP d
</PRE>
(normally it is  left uninitialised).  Before the destructor for this
variable is called the value of the token: 
<PRE>
	~cpp.destr.ptr : ( EXP pd ) -&gt; EXP POINTER c
</PRE>
is tested.  If <CODE>~cpp.destr.local</CODE> has been called for this
variable then this token returns a pointer to the variable, otherwise
it returns a null pointer.  The token <CODE>~cpp.destr.end</CODE>
and the destructor are only called if this token indicates that the
variable has been initialised. 
</P>

<H4>Throwing an exception</H4>
<P>
When a <CODE>throw</CODE> expression with an argument is encountered
a number of steps performed.  Firstly, space is allocated to hold
the exception value using the token: 
<PRE>
	~cpp.except.alloc : ( EXP VARIETY size_t ) -&gt; EXP pv
</PRE>
the argument of which gives the size of the value.  The space allocated
is returned as an expression of type <CODE>void *</CODE>.  Secondly,
the exception value is copied into the space allocated, using a copy
constructor if appropriate.  Finally the exception is raised using
the token: 
<PRE>
	~cpp.except.throw : ( EXP pv, EXP pti, EXP PROC ) -&gt; EXP BOTTOM
</PRE>
The first argument gives the pointer to the exception value, returned
by 
<CODE>~cpp.except.alloc</CODE>, the second argument gives a pointer
to the run-time type information for the exception type, and the third
argument gives the destructor to be called to destroy the exception
value (if any). This token sets the current exception to the given
values and invokes the exception manager as above. 
</P>
<P>
A <CODE>throw</CODE> expression without an argument results in a call
to the token: 
<PRE>
	~cpp.except.rethrow : () -&gt EXP BOTTOM
</PRE>
which re-invokes the exception manager with the current exception.
If there is no current exception then the implementation should call
<CODE>std::terminate</CODE>. 
</P>

<H4>Handling an exception</H4>
<P>
The exception manager proceeds to find an exception in the manner
described above, unwinding the stack and calling destructors for local
variables.  When a <CODE>try</CODE> block is popped from the stack
a TDF <CODE>long_jump</CODE> is applied to transfer control to its
list of handlers.  For each handler in turn it is checked whether
the handler can catch the current exception.  For <CODE>...</CODE>
handlers this is always true; for other handlers it is checked using
the token: 
<PRE>
	~cpp.except.catch : ( EXP pti ) -&gt; EXP VARIETY int
</PRE>
where the argument is a pointer to the run-time type information for
the handler type.  This token gives 1 if the exception is caught by
this handler, and 0 otherwise.  If the exception is not caught by
the handler then the next handler is checked, until there are no more
handlers associated with the <CODE>try</CODE> block.  In this case
control is passed back to the exception manager by re-throwing the
current exception using <CODE>~cpp.except.rethrow</CODE>. 
</P>
<P>
If an exception is caught by a handler then a number of steps are
performed. Firstly, if appropriate, the handler variable is initialised
by copying the current exception value.  A pointer to the current
exception value can be obtained using the token: 
<PRE>
	~cpp.except.value : () -&gt; EXP pv
</PRE>
Once this initialisation is complete the token: 
<PRE>
	~cpp.except.caught : () -&gt; EXP TOP
</PRE>
is called to indicate that the exception has been caught.  The handler
body is then executed.  When control exits from the handler, whether
by reaching the end of the handler or by jumping out of it, the token:
<PRE>
	~cpp.except.end : () -&gt; EXP TOP
</PRE>
is called to indicate that the exception has been completed.  Note
that the implementation should call the destructor for the current
exception and free the space allocated by <CODE>~cpp.except.alloc</CODE>
at this point. Execution then continues with the statement following
the handler. 
</P>
<P>
To conclude, the TDF generated for a <CODE>try</CODE> block and its
associated list of handlers has the form: 
<PRE>
	variable (
	    long_jump_access,
	    stack_tag,
	    make_value ( ~cpp.try.type ),
	    conditional (
		handler_label,
		sequence (
		    ~cpp.try.begin (
			obtain_tag ( stack_tag ),
			current_env,
			make_local_lv ( handler_label ) ),
			<I>try-block-body</I>,
			~cpp.try.end ),
		    conditional (
			catch_label_1,
			sequence (
			    integer_test (
				not_equal,
				catch_label_1,
				~cpp.except.catch (
				    <I>handler-1-typeid</I> ) )
			    variable (
				handler_tag_1,
				<I>handler-1-init</I> (
				    ~cpp.except.value ),
				sequence (
				    ~cpp.except.caught,
				    <I>handler-1-body</I> ) )
			    ~cpp.except.end )
			conditional (
			    catch_label_2,
			    <I>further-handlers</I>,
			    ~cpp.except.rethrow ) ) ) )
</PRE>
</P>
<P>
Note that for a local variable to maintain its previous value when
an  exception is caught in this way it is necessary to declare it
using the TDF <CODE>long_jump_access</CODE> construct.  Any local
variable which contains a <CODE>try</CODE> block in its scope is declared
in this way. 
</P>
<P>
To aid implementations in the writing of exception managers the following
standard tokens are provided: 
<PRE>
	~cpp.ptr.code : () -&gt; SHAPE POINTER ca
	~cpp.ptr.frame : () -&gt; SHAPE POINTER fa
	~cpp.except.jump : ( EXP POINTER fa, EXP POINTER ca ) -&gt; EXP BOTTOM
</PRE>
These give the shape of the TDF <CODE>make_local_lv</CODE> construct,
the shape of the TDF <CODE>current_env</CODE> construct, and direct
access to the TDF <CODE>long_jump</CODE> access.  The exception manager
in the default implementation is a function called <CODE>__TCPPLUS_throw</CODE>.
</P>

<H4>Exception specifications</H4>
<P>
If a function is declared with an exception specification then extra
code needs to be generated in the function definition to catch any
unexpected exceptions thrown by the function and to call <CODE>std::unexpected
</CODE>. Since this is a potentially high overhead for small functions,
this extra code is not generated if it can be proved that such unexpected
exceptions can never be thrown (the analysis is essentially the same
as that in the 
<A HREF="pragma.html#exception">exception analysis</A> check). 
</P>
<P>
The implementation of exception specification is to enclose the entire
function definition in a <CODE>try</CODE> block.  The handler for
this block uses <CODE>~cpp.except.catch</CODE> to check whether the
current exception can be caught by any of the types listed in the
exception specification.  If so the current exception is re-thrown.
If none of these types catch the current exception then the token:
<PRE>
	~cpp.except.bad : ( SIGNED_NAT ) -&gt; EXP TOP
</PRE>
is called.  The argument is 1 if the exception specification includes
the special type <CODE>std::bad_exception</CODE>, and 0 otherwise.
The implementation should call <CODE>std::unexpected</CODE>, but how
any exceptions thrown during this call are to be handled depends on
the value of the argument. 
</P>

<HR>
<H3><A NAME="mangle">2.6.17. Mangled identifier names</A></H3>
<P>
In a similar fashion to other C++ compilers, the C++ producer needs
a method of mapping C++ identifiers to a form suitable for further
processing, namely TDF tag names.  This mangled name contains an encoding
of the identifier name, its parent namespace or class and its type.
Identifiers with C linkage are not mangled.  The producer contains
a built-in <A HREF="man.html#unmangle">name unmangler</A>
which performs the reverse operation of transforming the mangled form
of an identifier name back to the underlying identifier.  This can
be useful when analysing system linker errors. 
</P>
<P>
Note that the type of an identifier forms part of its mangled name
not only for functions, but also for variables.  Many other compilers
do not mangle variable names, however the ISO C++ rules on namespaces
and variables with C linkage make it necessary (this can be suppressed
using the <CODE>-j-n</CODE> command-line option).  Declaring the language
linkage of a variable inconsistently can therefore lead to linking
errors with the C++ producer which are not detected by other compilers.
A common example is: 
<PRE>
	extern int errno ;
</PRE>
which, leaving aside whether <CODE>errno</CODE> is actually an external
variable, should be: 
<PRE>
	extern &quot;C&quot; int errno ;
</PRE>
</P>
<P>
As described above, the mangled form of an identifier has three components;
the identifier name, the identifier namespace and the identifier type.
Two underscores (<CODE>__</CODE>) are used to separate the name component
from the namespace and type components.  The mangling scheme used
is based on that described in the ARM.  The description below is not
complete; the mangling and unmangling routines themselves should be
consulted for a complete description. 
</P>

<H4>Mangling identifier names</H4>
<P>
Simple identifier names are mapped to themselves.  Unicode characters
of the forms <CODE>\u</CODE><I>xxxx</I> and <CODE>\U</CODE><I>xxxxxxxx</I>
are mapped to <CODE>__k</CODE><I>xxxx</I> and <CODE>__K</CODE><I>xxxxxxxx</I>
respectively, where the hex digits are output in their canonical lower-case
form.  Constructors are mapped to <CODE>__ct</CODE> and destructors
to <CODE>__dt</CODE>.  Conversions functions are mapped to 
<CODE>__op</CODE><I>type</I> where <I>type</I> is the mangled form
of the conversion type.  Overloaded operator functions, 
<CODE>operator@</CODE>, are mapped as follows: 
</P>
<CENTER>
<TABLE BORDER>
<TR><TH>Operator</TH>   <TH>Mapping</TH>
<TH>Operator</TH>   <TH>Mapping</TH>
<TH>Operator</TH>   <TH>Mapping</TH>
<TR><TD ALIGN=CENTER>&amp;</TD>  <TD ALIGN=CENTER>__ad</TD>
<TD ALIGN=CENTER>&amp;=</TD> <TD ALIGN=CENTER>__aad</TD>
<TD ALIGN=CENTER>[]</TD>  <TD ALIGN=CENTER>__vc</TD>
<TR><TD ALIGN=CENTER>-&gt;</TD>  <TD ALIGN=CENTER>__rf</TD>
<TD ALIGN=CENTER>-&gt;*</TD> <TD ALIGN=CENTER>__rm</TD>
<TD ALIGN=CENTER>=</TD>  <TD ALIGN=CENTER>__as</TD>
<TR><TD ALIGN=CENTER>,</TD>  <TD ALIGN=CENTER>__cm</TD>
<TD ALIGN=CENTER>~</TD>  <TD ALIGN=CENTER>__co</TD>
<TD ALIGN=CENTER>/</TD>  <TD ALIGN=CENTER>__dv</TD>
<TR><TD ALIGN=CENTER>/=</TD>  <TD ALIGN=CENTER>__adv</TD>
<TD ALIGN=CENTER>==</TD>  <TD ALIGN=CENTER>__eq</TD>
<TD ALIGN=CENTER>()</TD>  <TD ALIGN=CENTER>__cl</TD>
<TR><TD ALIGN=CENTER>&gt;</TD>  <TD ALIGN=CENTER>__gt</TD>
<TD ALIGN=CENTER>&gt;=</TD>  <TD ALIGN=CENTER>__ge</TD>
<TD ALIGN=CENTER>&lt;</TD>  <TD ALIGN=CENTER>__lt</TD>
<TR><TD ALIGN=CENTER>&lt;=</TD>  <TD ALIGN=CENTER>__le</TD>
<TD ALIGN=CENTER>&amp;&amp;</TD> <TD ALIGN=CENTER>__aa</TD>
<TD ALIGN=CENTER>||</TD>  <TD ALIGN=CENTER>__oo</TD>
<TR><TD ALIGN=CENTER>&lt;&lt;</TD> <TD ALIGN=CENTER>__ls</TD>
<TD ALIGN=CENTER>&lt;&lt;=</TD> <TD ALIGN=CENTER>__als</TD>
<TD ALIGN=CENTER>-</TD>  <TD ALIGN=CENTER>__mi</TD>
<TR><TD ALIGN=CENTER>-=</TD>  <TD ALIGN=CENTER>__ami</TD>
<TD ALIGN=CENTER>--</TD>  <TD ALIGN=CENTER>__mm</TD>
<TD ALIGN=CENTER>!</TD>  <TD ALIGN=CENTER>__nt</TD>
<TR><TD ALIGN=CENTER>!=</TD>  <TD ALIGN=CENTER>__ne</TD>
<TD ALIGN=CENTER>|</TD>  <TD ALIGN=CENTER>__or</TD>
<TD ALIGN=CENTER>|=</TD>  <TD ALIGN=CENTER>__aor</TD>
<TR><TD ALIGN=CENTER>+</TD>  <TD ALIGN=CENTER>__pl</TD>
<TD ALIGN=CENTER>+=</TD>  <TD ALIGN=CENTER>__apl</TD>
<TD ALIGN=CENTER>++</TD>  <TD ALIGN=CENTER>__pp</TD>
<TR><TD ALIGN=CENTER>%</TD>  <TD ALIGN=CENTER>__md</TD>
<TD ALIGN=CENTER>%=</TD>  <TD ALIGN=CENTER>__amd</TD>
<TD ALIGN=CENTER>&gt;&gt;</TD> <TD ALIGN=CENTER>__rs</TD>
<TR><TD ALIGN=CENTER>&gt;&gt;=</TD> <TD ALIGN=CENTER>__ars</TD>
<TD ALIGN=CENTER>*</TD>  <TD ALIGN=CENTER>__ml</TD>
<TD ALIGN=CENTER>*=</TD>  <TD ALIGN=CENTER>__aml</TD>
<TR><TD ALIGN=CENTER>^</TD>  <TD ALIGN=CENTER>__er</TD>
<TD ALIGN=CENTER>^=</TD>  <TD ALIGN=CENTER>__aer</TD>
<TD ALIGN=CENTER>delete</TD> <TD ALIGN=CENTER>__dl</TD>
<TR><TD ALIGN=CENTER>delete []</TD> <TD ALIGN=CENTER>__vd</TD>
<TD ALIGN=CENTER>new</TD>  <TD ALIGN=CENTER>__nw</TD>
<TD ALIGN=CENTER>new []</TD> <TD ALIGN=CENTER>__vn</TD>
<TR><TD ALIGN=CENTER>?:</TD>  <TD ALIGN=CENTER>__cn</TD>
<TD ALIGN=CENTER>:</TD>  <TD ALIGN=CENTER>__cs</TD>
<TD ALIGN=CENTER>::</TD>  <TD ALIGN=CENTER>__cc</TD>
<TR><TD ALIGN=CENTER>.</TD>  <TD ALIGN=CENTER>__df</TD>
<TD ALIGN=CENTER>.*</TD>  <TD ALIGN=CENTER>__dm</TD>
<TD ALIGN=CENTER>abs</TD>  <TD ALIGN=CENTER>__ab</TD>
<TR><TD ALIGN=CENTER>max</TD>  <TD ALIGN=CENTER>__mx</TD>
<TD ALIGN=CENTER>min</TD>  <TD ALIGN=CENTER>__mn</TD>
<TD ALIGN=CENTER>sizeof</TD> <TD ALIGN=CENTER>__sz</TD>
<TR><TD ALIGN=CENTER>typeid</TD> <TD ALIGN=CENTER>__td</TD>
<TD ALIGN=CENTER>vtable</TD> <TD ALIGN=CENTER>__tb</TD>
<TD ALIGN=CENTER>-</TD>  <TD ALIGN=CENTER>-</TD>
</TABLE>
</CENTER>
<P>
Note that this table contains a number of operators which are not
part of C++ or cannot be overloaded in C++.  These are used in the
representation of target dependent integer constants. 
</P>

<H4>Mangling namespace names</H4>
<P>
The global namespace is mapped to an empty string.  Simple namespace
and class names are mapped as above, but are preceded by a series
of decimal digits giving the length of the mangled name.  Nested namespaces
and classes are represented by a sequence of such namespace names,
preceded by the number of elements in the sequence.  This takes the
form <CODE>Q</CODE><I>digit</I> if there are less than 10 elements,
or 
<CODE>Q_</CODE><I>digits</I><CODE>_</CODE> if there are more than
10. Note that members of anonymous classes or namespaces are local
to their translation unit, and so do not have external tag names.
</P>

<H4>Mangling types</H4>
<P>
The mangling of types is essentially similar to that used in the 
<A HREF="dump.html">symbol table dump</A> format.  The type used in
the mangled name for an identifier ignores the return type for a function
and ignores the most significant bound for an array. 
</P>
<P>
The built-in types are mapped in precisely the same way as in the
<A HREF="dump.html#built-in">symbol table dump</A>.  Class and enumeration
types are mapped to their type names mangled in the same way as the
namespace names above.  The exception to this is that in a class member,
the parent class is mapped to <CODE>X</CODE>. 
</P>
<P>
The composite types are again mapped in a similar fashion to that
in the <A HREF="dump.html#composite">dump file</A>.  For example,
<CODE>PCc</CODE> represents <CODE>const char *</CODE>.  The only difficult
case concerns function parameter types where the ARM 
<CODE>T</CODE> and <CODE>N</CODE> encodings are used for duplicate
parameter types.  The function return type is included in the mangled
form except for function identifier types.  In the cases where the
identifier is known always to represent a function (constructors,
destructors etc.) the initial <CODE>F</CODE>
indicating a function type is also omitted. 
</P>
<P>
The types of template functions and classes are represented by the
underlying template and the template arguments giving rise to the
instance.  Template classes are preceded by <CODE>t</CODE>; template
functions are preceded by <CODE>G</CODE> rather than <CODE>F</CODE>.
Type arguments are represented by <CODE>Z</CODE> followed by the type
value; non-type arguments are represented by the argument type followed
by the argument value.  In the underlying type the template parameters
are represented by <CODE>m0</CODE>, <CODE>m1</CODE> etc. An alternative
scheme, in which the mangled form of a template function includes
the type of that instance, rather than the underlying template, can
be enabled using the <CODE>-j-f</CODE>
command-line option. 
</P>

<H4><A NAME="other">Other mangled names</A></H4>
<P>
The <A HREF="#vtable">virtual function table</A> for a class, when
this is a variable with external linkage, is named <CODE>__vt__</CODE><I>type
</I>, where <I>type</I> is the mangled form of the class name.  The
virtual function table for a base class is named <CODE>__vt__</CODE><I>base</I>
where <I>base</I> is a sequence of mangled class names specifying
the base class.  The <A HREF="#rtti">run-time type information structure</A>
for a type, when this is a variable with external linkage, is named
<CODE>__ti__</CODE><I>type</I>, where <I>type</I> is the mangled form
of the type name. 
</P>

<H4>Mangled name examples</H4>
<P>
The following gives some examples of the name mangling scheme: 
<PRE>
	class A {
	    static int a ;			// a__1Ai
	public :
	    A () ;				// __ct__1A
	    A ( int ) ;				// __ct__1Ai
	    A ( const A &amp; ) ;			// __ct__1ARCX
	    virtual ~A () ;			// __dt__1A
	    operator bool () ;			// __opb__1A
	    bool operator! () ;			// __nt__1A
	} ;

	// virtual function table	__vt__1A
	// run-time type information	__ti__1A

	int f ( A *, int, A * ) ;		// f__FP1AiT1
	int b = 2 ;				// b__i
	int c [3] ;				// c__A_i

	namespace N {
	    int *p = 0 ;			// p__1NPi
	}
</PRE>
</P>

<HR>
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
Copyright &copy; 1998.</I></P>
</BODY>
</HTML>