forked from itanium-cxx-abi/cxx-abi
-
Notifications
You must be signed in to change notification settings - Fork 0
/
abi-layout.html
3736 lines (3187 loc) · 119 KB
/
abi-layout.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<HTML>
<HEAD>
<title>C++ ABI for IA-64: Data Layout</title>
<link rel=stylesheet href=small-table.css type="text/css">
<link rel=stylesheet href=code.css type="text/css">
<hr>
<font size=6><i><b>
<p>
C++ ABI for IA-64: Data Layout
</b></i></font>
<font size=-1>
<p>
<i>Revised 18 April 2000</i>
</center>
</HEAD>
<BODY>
<p> <hr> <p>
<a name=intro>
<h3> Introduction </h3>
In this document, we define the memory layout for C++ data objects,
including both predefined and user-defined data types,
as well as internal compiler generated objects such as virtual tables.
In general, this document is written as a generic specification,
to be usable by C++ implementations on a variety of architectures.
However, it does contain processor-specific material for the IA-64
64-bit ABI, identified as such.
<p>
In general, text appearing in this document in color is either
tentative wording of agreements,
or proposals not yet agreed upon,
and should be taken as more subject to change than black material.
<p>
<font color=blue>
Note that the body of this document makes free use of a number of terms
which are defined in the <i><b>Definitions</b></i> section below.
</font>
<p> <hr> <p>
<h3> Contents </h3>
<ul>
<li> <a href=#general> General </a>
<li> <a href=#definitions> Definitions </a>
<li> <a href=#limits> Limits </a>
<li> <a href=#namespace> Namespace and Header </a>
<li> <a href=#pod> POD Data Types </a>
<li> <a href=#member-pointers> Member Pointers </a>
<li> <a href=#class-types> Non-POD Class Types </a>
<li> <a href=#vtable> Virtual Table Layout </a>
<li> <a href=#vcall> Virtual Function Calling Conventions </a>
<li> <a href=#vtable-ctor> Virtual Tables During Object Construction </a>
<li> <a href=#array-ctor> Array Constructors and Destructors </a>
<li> <a href=#guards> Initialization Guard Variables </a>
<li> <a href=#rtti> Run-Time Type Information (RTTI) </a>
<li> <a href=#mangling> External Names (a.k.a. Mangling)</a>
<li> <a href=#vague> Vague Linkage </a>
<li> <a href=#revisions> Revision History</a>
</ul>
<p> <hr> <p>
<h3> Outstanding Questions </h3>
<font color=red>
There are outstanding questions in the body of the document to be
clarified:
<ul>
<a href=#guards>
<li> Specify initialization guard variables.
</a>
<a href=#vmi>
<li> Is there any useful purpose for the has-public-base flag in
<code>vmi_flags</code> of <code>__vmi_class_type_info</code>?
(Action item 37.)
</a>
</ul>
</font>
<p> <hr> <p>
<h3> Revisions </h3>
<p>
<font color=blue>[000417]</font>
Updates from 17 April meeting.
Clarify order of vcall offsets.
More elaboration of construction vtable.
Specification of COMDAT RTTI name.
Reorganization of pointer RTTI.
Modify mangling grammar to clarify substitution in compound names.
Clarify Vague Linkage section.
<p>
<font color=blue>[000407]</font>
Updates from 6 April meeting, email.
More elaboration of construction vtable.
Updates/issues in RTTI.
Minor mangling changes.
Added Vague Linkage section.
<p>
<font color=blue>[000327]</font>
Updates from 30 March meeting.
Define base classes to include self, proper base classes.
Modify local function mangling per JFW proposal.
<p>
<font color=blue>[000327]</font>
Updates from 23 March meeting.
Adopt construction vtable Proposal B, and rewrite.
Further work on mangling, especially substitution.
<p>
<font color=blue>[000320]</font>
Clarify class size limit.
Editorial changes in vtable components description.
Add alternate to construction vtable proposal.
Clarification in array cookie specification.
Removed COMMON proxy from class RTTI.
Extensive changes to mangling writeup.
<p>
<a href=#revisions>Revision History</a>
<p> <hr> <p>
<a name=definitions>
<h3> Definitions </h3>
<p>
The descriptions below make use of the following definitions:
<dl>
<p>
<dt> <i>alignment</i> of a type T (or object X)</dt>
<dd>
A value A such that any object X of type T has an address satisfying
the constraint that &X modulo A == 0.
<p>
<dt> <i>base class</i> of a class T</dt>
<dd>
When this document refers to base classes of a class T,
unless otherwise specified,
it means T itself as well as all of the classes from which it is derived,
directly or indirectly, virtually or non-virtually.
We use the term <i>proper base class</i>
to exclude T itself from the list.
<p>
<dt> <i>direct base class order</i> </dt>
<dd>
When the direct base classes of a class are viewed as an ordered set,
the order assumed is the order declared, left-to-right.
<p>
<dt> <i>diamond-shaped inheritance</i> </dt>
<dd>
A class has diamond-shaped inheritance iff it has a virtual base class
that can be reached by distinct inheritance graph paths through
more than one direct base.
<p>
<dt> <i>dynamic class</i> </dt>
<dd>
A class requiring a virtual table pointer
(because it or its bases have one or more virtual member functions or
virtual base classes).
<p>
<dt> <i>empty class</i> </dt>
<dd>
A class with no non-static data members other than zero-width bitfields,
no virtual functions, no virtual base classes,
and no non-empty non-virtual proper base classes.
<p>
<dt> <i>inheritance graph</i> </dt>
<dd>
A graph with nodes representing a class and all of its subobjects,
and arcs connecting each node with its direct bases.
<p>
<dt> <i>inheritance graph order</i> </dt>
<dd>
The ordering on a class object and all its subobjects obtained
by a depth-first traversal of its inheritance graph,
where:
<ul>
<p>
<li> No node is visited more than once.
(So, a virtual base subobject, and all of its base subobjects,
will be visited only once.)
<p>
<li>
The subobjects of a node are visited in the order in which they
were declared.
(So, given <code>class A : public B, public C</code>,
A is walked first,
then B and its subobjects,
and then C and its subobjects.)
</ul>
<p>
Note that the traversal may be preorder or postorder.
Unless otherwise specified,
preorder (derived classes before their bases) is intended.
<p>
<a name=q3></a>
<dt> <i>nearly empty class</i> </dt>
<dd>
A class that contains no data except its virtual pointer (if any) or
virtual bases. In particular, it:
<ul>
<li> has no non-static data members other than zero-width bitfields,
<li> has no proper base classes that are not either empty, nearly empty,
or virtual, and
<li> has at most one non-virtual, nearly empty proper base class.
</ul>
Such classes may be primary base classes even if virtual,
sharing a virtual pointer with the derived class.
<p>
<dt> <i>primary base class</i> </dt>
<dd>
For a dynamic class,
the unique base class (if any) with which it shares the virtual pointer
at offset 0.
<p>
<dt> <i>secondary vtable</i> </dt>
<dd>
The instance of a vtable for a base class
that is embedded in the vtable of a class derived from it.
<p>
<dt> <i>thunk</i> </dt>
<dd>
A segment of code associated (in this ABI) with a target function,
which is called instead of the target function for the purpose of
modifying parameters (e.g. <code>this</code>)
or other parts of the environment
before transferring control to the target function,
and possibly making further modifications after its return.
A thunk may contain as little as an instruction to be executed prior to
falling through to an immediately following target function,
or it may be a full function with its own stack frame that does
a full call to the target function.
<p>
<dt> <i>vague linkage</i> </dt>
<dd>
The treatment of entities --
e.g. inline functions, templates, vtables --
with external linkage that can be
defined in multiple translation units,
while the ODR requires that the program
behave as if there were only a single definition.
<p>
<dt> <i>virtual table</i> (or <i>vtable</i>) </dt>
<dd>
A dynamic class has an associated table
(often several instances, but not one per object)
which contains information about its dynamic attributes,
e.g. virtual function pointers, virtual base class offsets, etc.
<p>
<dt> <i>vtable group</i> </dt>
<dd>
The primary vtable for a class along with all of the associated
secondary vtables for its proper base classes.
</dl>
<p> <hr> <p>
<a name=general>
<h3> General </h3>
<p>
In what follows, we define the memory layout for C++ data objects.
Specifically, for each type, we specify the following information about
an object O of that type:
<ul>
<li> the <i>size</i> of an object, <i>sizeof</i>(O);
<li> the <i>alignment</i> of an object, <i>align</i>(O); and
<li> the <i>offset</i> within O, <i>offset</i>(C),
of each data component C, i.e. base or member.
</ul>
<p> For purposes internal to the specification,
we also specify:
<ul>
<li> <i>dsize</i>(O):
the <i>data size</i> of an object,
which intuitively is sizeof(O) minus the size of tail padding.
<p>
<li> <i>nvsize</i>(O):
the <i>non-virtual size</i> of an object,
which intuitively is dsize(O) minus the size of virtual bases.
It is always equal to <i>dsize</i>(O) for types without virtual bases.
<p>
<li> <i>nvalign</i>(O):
the <i>non-virtual alignment</i> of an object,
which intuitively is the alignment determined by ignoring virtual bases.
It is always equal to <i>align</i>(O) for types without virtual bases.
</ul>
<p> <hr> <p>
<a name=limits>
<h3> Limits </h3>
<p>
Various representations specified by this ABI impose limitations on
conforming user programs.
These include, for the 64-bit IA-64 ABI:
<ul>
<p>
<li>
The offset of a non-virtual base subobject in the full object containing
it must be representable by a 56-bit signed integer
(due to RTTI implementation).
This implies a practical limit of 2**55 bytes on the size of a class.
</ul>
<p> <hr> <p>
<a name=namespace>
<h3> Namespace and Header </h3>
<p>
This ABI specifies a number of type and function APIs supplemental
to those required by the ISO C++ Standard.
A header file named <code>cxxabi.h</code> will be provided by
implementations that declares these APIs.
The reference header file included with this ABI definition
shall be the authoritative definition of the APIs.
<p>
These APIs will be placed in a namespace <code>__cxxabiv1</code>.
The header file will also declare a namespace alias <code>abi</code>
for <code>__cxxabiv1</code>.
It is expected that users will use the alias,
and the remainder of the ABI specification will use it as well.
<p>
In general,
API objects defined as part of this ABI are assumed to be extern "C++".
However, some (many?) are specified to be extern "C" if they:
<ul>
<li> are expected to be called by users from C code,
e.g. <code>longjmp_unwind</code>; or
<li> are expected to be called only implicitly by compiled code,
and are likely to be implemented in C.
Note: this second exception has not yet been adopted.
</ul>
<p> <hr> <p>
<a name=pod>
<h3> POD Data Types </h3>
<p>
The size and alignment of C POD types is as specified by the base (C) ABI.
Type bool has size and alignment 1.
All of these types have data size and non-virtual size equal to their size.
(We ignore tail padding for PODs because the Standard does not allow us
to use it for anything else.)
<p> <hr> <p>
<a name=member-pointers></a>
<h3> Member Pointers </h3>
<p>
A pointer to data member is an offset from the base
address of the class object containing it,
represented as a <code>ptrdiff_t</code>.
It has the size and alignment attributes of a <code>ptrdiff_t</code>.
A NULL pointer is represented as -1.
<p>
A pointer to member function is a pair <ptr, adj> as follows:
<dl>
<p>
<dt> <code>ptr</code>:
<dd> For a non-virtual function, this field is a simple function pointer.
(Under current base IA-64 psABI conventions,
that is a pointer to a GP/function address pair.)
For a virtual function,
it is 1 plus the Vtable offset (in bytes) of the function,
represented as a <code>ptrdiff_t</code>.
The value zero represents a NULL pointer,
independent of the adjustment field value below.
<p>
<dt> <code>adj</code>:
<dd> The required adjustment to <i>this</i>,
represented as a <code>ptrdiff_t</code>.
</dl>
<p>
It has the size, data size, and alignment
of a class containing those two members, in that order.
(For 64-bit IA-64, that will be 16, 16, and 8 bytes respectively.)
<p> <hr> <p>
<a name=class-types></a>
<h3> Non-POD Class Types </h3>
For non-POD class types C, assume that all component types
(i.e. proper base classes and non-static data member types)
have been laid out, defining size, data size, non-virtual size,
alignment, and non-virtual alignment.
(See the description of these terms in
<a href=#general><b>General</b></a> above.)
Layout (of type C) is done using the following procedure.
<ol type=I>
<p>
<li> <h5> Initialization </h5>
<ol type=1>
<p>
<li> Initialize sizeof(C) to zero, align(C) to one, dsize(C) to zero.
<p>
<li> If C is a dynamic class type:
<ol type=a>
<p>
<li> Identify all virtual base classes, direct or indirect,
that are primary base classes for some other direct or indirect
base class.
Call these <i>indirect primary base classes</i>.
<p>
<li> If C has a dynamic base class,
attempt to choose a primary base class B.
It is the first (in direct base class order)
non-virtual dynamic base class, if one exists.
Otherwise, it is a nearly empty virtual base class,
the first one in (preorder) inheritance graph order which
is not an indirect primary base class if any exist,
or just the first one if they are all indirect primaries.
<p>
Allocate the chosen primary base at offset zero, and set
sizeof(C) to sizeof(B), align(C) to nvalign(B),
dsize(C) to nvsize(B).
This step allocates only B's non-virtual part,
i.e. excluding any direct or indirect bases.
<p>
<li> Otherwise, allocate the vtable pointer for C at offset zero,
and set sizeof(C), align(C), and dsize(C) to the appropriate
values for a pointer (all 8 bytes for IA-64 64-bit ABI).
</ol>
</ol>
<p>
<li> <h5> Non-Virtual-Base Allocation </h5>
<p>
For each data component D (i.e. proper base or non-static data member)
except virtual bases,
first the non-virtual proper base classes in declaration order
and then the non-static data members in declaration order,
allocate as follows:
<ol type=1>
<p>
<li> If D is a bitfield, i.e. declared as "<code>T [b]: n;"</code>,
for some integral POD type T and bit count n,
there are two cases depending on <code>sizeof(T)</code>
and <code>n</code>:
<ol type=a>
<p>
<li>
If <code>sizeof(T)*8 >= n</code>,
the bitfield is allocated as required by the underlying C psABI.
That is, it will be placed in the next available n bits,
subject to the constraint that it does not cross an alignment
boundary for type <code>T</code>.
The next available n bits are at offset dsize(C),
unless the preceding byte is only partially filled by a bitfield,
in which case the bitfield allocation can begin in that byte.
<p>
Update align(C) to max (align(C), align(T)).
<p>
<li>
If <code>sizeof(T)*8 < n</code>,
let T' be the largest integral POD type with
<code>sizeof(T')*8 <= n</code>.
The bitfield is allocated starting at the next offset aligned
appropriately for T', with length n bits.
The first <code>sizeof(T)*8</code> bits are used to hold the
value of the bitfield,
followed by <code>n - sizeof(T)*8</code> bits of padding.
<p>
Update align(C) to max (align(C), align(T')).
</ol>
<p>
In either case,
update sizeof(C) and dsize(C) to include the last byte
containing (part of) the bitfield.
<p>
<li> Otherwise, if D is not an empty base class
(including all data members),
start at offset dsize(C),
incremented if necessary to alignment nvalign(type(D)).
Place D at this offset unless doing so would result in two
components (direct or indirect) of the same type having the
same offset.
If such a component type conflict occurs,
increment the candidate offset by nvalign(type(D)),
and try again,
repeating until success occurs
(which will occur no later than sizeof(C) rounded up to the
required alignment).
<p>
If D is a base class, this step allocates only its non-virtual
part, i.e. excluding any direct or indirect virtual bases.
<p>
Update sizeof(C) to max (sizeof(C), offset(D)+nvsize(D)).
Update align(C) to max (align(C), nvalign(D)).
If D is a base class (not empty in this case),
update dsize(C) to offset(D)+nvsize(D).
If D is a data member,
update dsize(C) to max (offset(D)+dsize(D), offset(D)+1).
<p>
<li> If D is an empty proper base class,
its allocation is similar to case (2) above,
except that additional candidate offsets are considered before
starting at dsize(C).
First, attempt to place D at offset zero.
If unsuccessful (due to a component type conflict),
proceed with attempts at dsize(C) as for non-empty bases.
As for that case, if there is a type conflict at dsize(C)
(with alignment updated as necessary),
increment the candidate offset by nvalign(type(D)),
and try again,
repeating until success occurs.
<p>
Once offset(D) has been chosen,
update sizeof(C) to max (sizeof(C), offset(D)+sizeof(D)).
Note that nvalign(D) is 1, so no update of align(C) is needed.
Similarly, since D is an empty base class,
no update of dsize(C) is needed.
</ol>
<p>
After all such components have been allocated,
set nvsize(C) = dsize(C) and nvalign(C) = align(C).
These values will not change during virtual base allocation.
<p><a name=a17></a>
<li> <h5> Virtual Base Allocation </h5>
<p>
<p>
Finally allocate any direct or indirect virtual base classes
(except the primary base class or any indirect primary base classes)
as we did non-virtual base classes
in step II-2 (if empty) or II-3 (if non-empty),
in inheritance graph order.
Update sizeof(C) to max (sizeof(C), offset(D)+nvsize(D)).
If non-empty, also update align(C) and dsize(C) as in II-2.
<p>
The primary base class has already been allocated in I-2b.
Any indirect primary base class E of the current class C,
that has been chosen as the primary base class of some other base class
(direct or indirect, virtual or non-virtual) of C,
will be allocated as part of that other base class,
and is not allocated here.
If E is a primary base class of more than one other base,
the instance used as its allocation in C shall be the first such
in the inheritance graph order.
<i>
<p>
Consider:
<pre><code>
struct R { virtual void r (); };
struct S { virtual void s (); };
struct T : virtual public S { virtual void t (); };
struct U : public R, virtual public T { virtual void u (); };
</code></pre>
R is the primary base class for U since it is the first direct
non-virtual dynamic base.
Then, since an inheritance-order walk of U is { U, R, T, S }
the T base is allocated next.
Since S is a primary base of T,
there is no need to allocate it separately.
However, given:
<pre><code>
struct V : public R, virtual public S, virtual public T {
virtual void v ();
};
</code></pre>
the inheritance-order walk of V is { V, R, S, T }.
Nevertheless, although S is considered for allocation first as a virtual base,
it is not allocated separately because it is a primary base of T,
another base.
Thus sizeof (V) == sizeof (U),
and the full layout is equivalent to the C struct:
</i>
<pre><code>
struct X {
R r;
T t;
};
</code></pre>
<p>
<li> <h5> Finalization </h5>
<p>
Round sizeof(C) up to a non-zero multiple of align(C).
</ol>
<p> <hr> <p>
<a name=vtable></a>
<h3> Virtual Table Layout </h3>
<p>
<h4> General </h4>
<p>
A <i>virtual table</i> (<i>vtable</i>) is a table of information used
to dispatch virtual functions,
to access virtual base class subobjects,
and to access information for runtime type identification (RTTI).
Each class that has virtual member functions or virtual bases
has an associated set of vtables.
There may be multiple vtables for a particular class,
if it is used as a base class for other classes.
However, the vtable pointers within all the objects (instances)
of a particular most-derived class point to the same set of vtables.
<p>
A vtable consists of a sequence of offsets, data pointers,
and function pointers, as well as structures composed of such items.
We will describe below the sequence of such items.
Their offsets within the vtable are determined by that allocation
sequence and the natural ABI size and alignment,
just as a data struct would be. In particular:
<ul>
<li> Offsets are of type <code>ptrdiff_t</code> unless otherwise stated.
<li> Data pointers have normal pointer size and alignment.
<li> Function pointers remain to be defined.
One possibility is that they will be
<function address, GP address> pairs, with pointer alignment.
</ul>
<p>
In general, what we consider the address of a vtable
(i.e. the address contained in objects pointing to a vtable)
may not be the beginning of the vtable.
We call it the <i>address point</i> of the vtable.
The vtable may therefore contain components at either positive or
negative offsets from its address point.
<p>
<h4> Virtual Table Components and Order </h4>
<p>
This section describes the usage and relative order of various
components that may appear in virtual tables.
Precisely which components are present in various possible virtual
tables is specified in the next section.
If present, components are present in the order described,
except for the exceptions specified.
<ul>
<p>
<li>
<i>Virtual call (vcall) offsets</i> are used
to perform pointer adjustment for
virtual functions declared in a virtual base class or its subobjects,
and overridden in a class derived from it.
These entries are allocated in the vtable for the virtual base class
that is most immediately derived from the base class containing the
overridden virtual function declaration.
They are used
to find the necessary adjustment from the virtual base to the
derived class containing the overrider,
if any.
When a virtual function is invoked via a virtual base,
but has been overridden in a derived class,
the overriding function first adds a fixed offset to adjust the
<code>this</code> pointer to the virtual base,
and then adds the value contained at the vcall offset
in the virtual base to its <code>this</code> pointer
to get the address of the derived object where the function was overridden.
These values may be positive or negative.
These are first in the vtable if present,
ordered as defined in categories 3 and 4 below.
<p>
<li>
<a name=q1></a>
<i>Virtual Base (vbase) offsets</i> are used to access
the virtual bases of an object.
Such an entry is added to the derived class object address
(i.e. the address of its vtable pointer)
to get the address of a virtual base class.
Such an entry is required for each virtual base class.
The values can be positive or negative.
<br>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
However, in classes sharing a vtable with a primary base class,
the vcall and vbase offsets added by the derived class all come before
the vcall and vbase offsets required by the base class,
so that the latter may be laid out as required by the base class
without regard to additions from the derived class(es).
</i>
<p>
<li>
The <i>offset to top</i> holds the displacement to the top of the object
from the location within the object of the vtable pointer that addresses
this vtable,
as a <code>ptrdiff_t</code>.
It is always present.
The offset provides a way to find the top of the object from any base
subobject with a vtable pointer.
This is necessary for dynamic_cast<void*> in particular.
<p>
<i>In a complete object vtable,
and therefore in all of its primary base vtables,
the value of this offset will be zero.
For the secondary vtables of other non-virtual bases,
and of many virtual bases,
it will be negative.
Only in some construction vtables will some virtual base vtables have
positive offsets, due to a different ordering of the virtual bases in
the full object than in the subobject's standalone layout.
</i>
<p>
<li>
The <i>typeinfo pointer</i> points to the typeinfo object used for RTTI.
It is always present.
All entries in each of the vtables for a given class must point to the
same typeinfo object.
A correct implementation of typeinfo equality is to check pointer equality,
except for pointers (directly or indirectly) to incomplete types.
The typeinfo pointer is a valid pointer for polymorphic classes,
i.e. those with virtual functions,
and is zero for non-polymorphic classes.
<p>
<li>
The vtable address point points here,
i.e. this is the vtable address contained in an object's virtual pointer.
This address must have the alignment required for pointers.
<p>
<li>
<i>Virtual function pointers</i> are used for virtual function dispatch.
Each pointer holds either the address of a virtual function of the class,
or the address of a secondary entry point that performs certain
adjustments before transferring control to a virtual function.
<p>
The form of a virtual function pointer is specified by the
processor-specific C++ ABI for the implementation.
In the specific case of 64-bit IA-64 shared library builds,
a virtual function pointer entry contains a pair of components
(each 64 bits):
the value of the target GP value and the actual function address.
That is, rather than being a normal function pointer,
which points to such a two-component descriptor,
a virtual function pointer entry is the descriptor.
<p>
The order of the virtual function pointers in a vtable is the order
of declaration of the corresponding member functions in the class.
There is an entry for any virtual function declared in a class,
whether it is a new function or overrides a base class function,
unless it overrides a function from the primary base,
and conversion between their return types does not require an adjustment.
(In the case of this exception,
the primary base and the derived class share the vtable,
and can share the virtual function entry because no adjustments are
necessary.)
If a class has an implicitly-defined virtual destructor,
its entries come after the declared virtual function pointers.
<p>
When a derived class and its primary base share a vtable,
the virtual function entries introduced by the derived class follow
those for the primary base,
so that the layout of the primary base's embedded vtable is the same as
that of its standalone vtable.
<p>
The entries for virtual destructors are actually pairs of entries.
The first destructor,
called the non-deleting in-charge destructor,
performs the destruction without calling delete() on the object.
The second destructor,
called the deleting in-charge destructor,
calls delete() after destroying the object.
Both destroy any virtual bases;
a separate, non-virtual function,
called the not-in-charge destructor,
performs destruction of the object but
not its virtual base subobjects, and does not call delete().
</ul>
<p>
Following the primary vtable of a derived class are
<i>secondary vtables</i> for each of its proper base classes,
except any primary base(s) with which it shares its primary vtable.
These are copies of the vtables for the respective base classes
(copies in the sense that they have the same layout,
though the fields may have different values).
We call the collection consisting of a primary vtable along with all of
its secondary vtables a <i>vtable group</i>.
The order in which they occur is the same as the order in which the
base class subobjects are considered for allocation in the derived object:
<ul>
<p>
<li>
First are the vtables of direct non-primary, non-virtual proper bases,
in the order declared,
including their secondary vtables for non-virtual bases in the order
they appear in the standalone vtable group for the base.
(Thus the effect is that these vtables occur in inheritance graph order,
excluding primary bases and virtual bases.)
<p>
<li>
Then come the virtual base vtables,
also in inheritance graph order,
and again excluding primary bases
(which share vtables with the classes for which they are primary).
</ul>
<p>
<h4> Virtual Table Construction </h4>
<p>
In this section, we describe how to construct the vtable for an class,
given vtables for all of its proper base classes.
To do so, we divide classes into several categories,
based on their base class structure.
<p>
<h5> Category 0: Trivial </h5>
Structure:
<ul>
<li> No virtual base classes.
<li> No virtual functions.
</ul>
<p>
Such a class has no associated vtable,
and its objects contain no virtual pointer.
<p>
<h5> Category 1: Leaf </h5>
Structure:
<ul>
<li> No inherited virtual functions.
<li> No virtual base classes.
<li> Declares virtual functions.
</ul>
<p>
The vtable contains offset-to-top and RTTI fields
followed by virtual function pointers.
There is one function pointer entry for each
virtual function declared in the class.
<p>
<h5> Category 2: Non-Virtual Bases </h5>
Structure:
<ul>
<li> Only non-virtual proper base classes.
<li> Inherits virtual functions.
</ul>
<p>
The class has a vtable for each proper base class that has a vtable.
The secondary vtables for the class
are constructed from copies of the base class complete object vtables.
The entries are the same, except:
<ul>
<p>
<li> The offset-to-top and RTTI fields
contain information for the class,
rather than for the base class.
<p>
<li> The function pointer entries for virtual functions inherited from
the base class and overridden by this class are replaced with the
addresses of the overriding functions
(or the corresponding adjustor secondary entry points).
</ul>
<p>
For a proper base class <code>Base</code>,
and a derived class <code>Derived</code> for which we are constructing
this set of vtables,
we shall refer to the vtable for <code>Base</code> as
<code>Base-in-Derived</code>.
The virtual pointer of each base subobject of an object of the
derived class will point to the corresponding base vtable in this set.
<p>
The vtable copied from the primary base class is also called the
primary vtable;
it is addressed by the vtable pointer at the top of the object.
The other vtables of the class are called secondary vtables;
they are addressed by vtable pointers inside the object.
<p>
Following the function pointer entries that correspond to those of the
primary base class,
the primary vtable holds the following additional entries at its tail:
<ul>
<li> Entries for virtual functions introduced by this class.
<li> Entries for overridden virtual functions not already in the vtable.
(These are also called replicated entries because they are already
in the secondary vtables of the class.)
</ul>
The primary vtable, therefore,
has the base class functions appearing before the derived class functions.
The primary vtable can be viewed as two vtables accessed
from a shared vtable pointer.
<p>
<i>Note</i>:
Another benefit of replicating virtual function entries is that it
reduces the number of this pointer adjustments during virtual calls.
Without replication,
there would be more cases where the this pointer would have to be
adjusted to access a secondary vtable prior to the call.
These additional cases would be exactly those where the function
is overridden in the derived class,
implying an additional thunk adjustment back to the original pointer.