Add a new class slot `align', holding the instance layout alignment.
[sod] / lib / sod-structs.3
CommitLineData
47de28ae
MW
1.\" -*-nroff-*-
2.\"
3.\" Description of the main Sod data structures
4.\"
5.\" (c) 2015 Straylight/Edgeware
6.\"
7.
8.\"----- Licensing notice ---------------------------------------------------
9.\"
e0808c47 10.\" This file is part of the Sensible Object Design, an object system for C.
47de28ae
MW
11.\"
12.\" SOD is free software; you can redistribute it and/or modify
65aaa02c
MW
13.\" it under the terms of the GNU Library General Public License as
14.\" published by the Free Software Foundation; either version 2 of the
15.\" License, or (at your option) any later version.
47de28ae
MW
16.\"
17.\" SOD is distributed in the hope that it will be useful,
18.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
65aaa02c 20.\" GNU Library General Public License for more details.
47de28ae 21.\"
65aaa02c
MW
22.\" You should have received a copy of the GNU Library General Public
23.\" License along with SOD; if not, write to the Free
24.\" Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
25.\" MA 02111-1307, USA.
47de28ae 26.
9ed8eb2a 27.\" Highlight using terminal escapes, rather than overstriking.
47de28ae 28.\"\X'tty: sgr 1'
9ed8eb2a 29.
47de28ae
MW
30.\" String definitions and font selection.
31.ie t \{\
32. ds o \(bu
33. if \n(.g .fam P
34.\}
35.el \{\
36. ds o o
37.\}
38.
39.\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
40.de hP
41.IP
42\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
43..
44.
45.\"--------------------------------------------------------------------------
46.TH sod-structs 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design"
47.
48.SH NAME
49sod-structs \- main Sod data structures
50.
51.\"--------------------------------------------------------------------------
52.SH SYNOPSIS
53.nf
54.ft B
55#include <sod/sod.h>
56
57typedef struct SodObject__ichain_obj SodObject;
58typedef struct SodClass__ichain_obj SodClass;
59
60struct sod_instance {
61\h'2n'const struct sod_vtable *_vt;
62};
63
64struct sod_vtable {
65\h'2n'const SodClass *_class;
66\h'2n'size_t _base;
67};
68
69struct SodObject__vt_obj {
70\h'2n'const SodClass *_class;
71\h'2n'size_t _base;
72};
73
74struct SodObject__ilayout {
75\h'2n'union {
76\h'4n'struct SodObject__ichain_obj {
77\h'6n'const struct SodObject__vt_obj *_vt;
78\h'4n'};
79\h'2n'} obj;
80};
81
82extern const struct SodClass__ilayout SodObject__classobj;
83#define SodObject__class (&SodObject__classobj.obj.cls)
84
85struct SodClass__vt_obj {
86\h'2n'const SodClass *_class;
87\h'2n'size_t _base;
88};
89
90struct SodObject__ilayout {
91\h'2n'union {
92\h'4n'struct SodClass__ichain_obj {
93\h'6n'const struct SodClass__vt_obj *_vt;
94\h'6n'struct SodClass__islots {
95\h'8n'const char *name;
96\h'8n'const char *nick;
97\h'8n'size_t initsz;
8c2c58ae 98\h'8n'size_t align;
47de28ae
MW
99\h'8n'void *(*imprint)(void *\fIp\fB);
100\h'8n'void *(*init)(void *\fIp\fB);
101\h'8n'size_t n_supers;
102\h'8n'const SodClass *const *supers;
103\h'8n'size_t n_cpl;
104\h'8n'const SodClass *const *cpl;
105\h'8n'const SodClass *link;
106\h'8n'const SodClass *head;
107\h'8n'size_t level;
108\h'8n'size_t n_chains;
109\h'8n'const struct sod_chain *chains;
110\h'8n'size_t off_islots;
111\h'8n'size_t islotsz;
112\h'6n'} cls;
113\h'4n'};
114\h'4n'SodObject obj;
115\h'2n'} obj;
116};
117
118struct sod_chain {
119\h'2n'size_t n_classes;
120\h'2n'const SodClass *const *classes;
121\h'2n'size_t off_ichain;
122\h'2n'const struct sod_vtable *vt;
123\h'2n'size_t ichainsz;
124};
125
126extern const struct SodClass__ilayout SodClass__classobj;
127#define SodClass__class (&SodClass__classobj.obj.cls)
128.fi
129.ft P
130.
131.\"--------------------------------------------------------------------------
132.SH DESCRIPTION
133.
134This page describes the structure and layout
135of standard Sod objects, classes and associated metadata.
136Note that Sod's object system is very flexible
137and it's possible for an extension
138to define a new root class
139which works very differently from the standard
140.B SodObject
141described here.
142.
143.\"--------------------------------------------------------------------------
144.SH COMMON INSTANCE STRUCTURE
145.
146As described below,
147a pointer to an instance actually points to an
148.I "instance chain"
149structure within the instances overall layout structure.
150.PP
151Instance chains contain slots and vtable pointers,
152as described below.
153All instances have the basic structure of a
154.BR "struct sod_instance" ,
155which has the following members.
156.TP
157.B "const struct sod_vtable *_vt"
158A pointer to a
159.IR vtable ,
160which has the basic structure of a
161.BR "struct sod_vtable" ,
162described below.
163.PP
164A vtable contains static metadata needed
165for efficient conversions and
166message dispatch,
167and pointers to the instance's class.
168Each chain points to a different vtable
169All vtables have the basic structure of a
170.BR "struct sod_vtable" ,
171which has the following members.
172.TP
173.B "const SodClass *_class"
174A pointer to the instance's class object.
175.TP
176.B "size_t _base;"
177The offset of this chain structure
178above the start of the overall instance layout, in bytes.
179Subtracting
180.B _base
181from the instance chain pointer
182finds the layout base address.
183.
184.\"--------------------------------------------------------------------------
185.SH BUILT-IN ROOT OBJECTS
186.
187This section describes the built-in classes
188.B SodObject
189and
190.BR SodClass ,
191which are the standard roots of the inheritance and metaclass graphs
192respectively.
193Specifically,
194.B SodObject
195has no direct superclasses,
196and
197.B SodClass
198is its own metaclass.
9c4a4110
MW
199It is not possible to define root classes in module files
200because of circularities:
47de28ae
MW
201.B SodObject
202has
203.B SodClass
9c4a4110
MW
204as its metaclass,
205and
47de28ae
MW
206.B SodClass
207is a subclass of
208.BR SodObject .
209Extensions can define additional root classes,
210but this is tricky,
211and not really to be recommended.
212.
213.SS The SodObject class
214The
215.B SodObject
216class defines no slots or messages.
217Because
218.B SodObject
219has no direct superclasses,
220there is only one chain,
221and no inherited slots or messages,
222so the single chain contains only a vtable pointer.
223.PP
224Since there are no messages,
225and
226.B SodClass
227also has only one chain,
228the vtable contains only the standard class pointer and offset-to-base
229members.
230In an actual instance of
231.B SodObject
232(why would you want one?)
233the class pointer contains the address of
234.B SodObject__class
235and the offset is zero.
236.
237.SS The SodClass class
238The
239.B SodClass
240class defines no messages,
241but there are a number of slots.
242Its only direct superclass is
243.B SodObject
244and so (like its superclass) its vtable is trivial.
245.PP
246The slots defined are as follows.
247.TP
248.B const char *name;
249A pointer to the class's name.
250.TP
251.B const char *nick;
252A pointer to the class's nickname.
253.TP
254.B size_t initsz;
255The size in bytes required to store an instance of the class.
256.TP
8c2c58ae
MW
257.B size_t align;
258A sufficient alignment for the class's instance storage.
259.TP
47de28ae
MW
260.BI "void *(*imprint)(void *" p );
261A pointer to a function:
262given a pointer
263.I p
264to at least
265.I initsz
266bytes of appropriately aligned memory,
267`imprint' this memory it so that it becomes a minimally functional
268instance of the class:
269all of the vtable and class pointers are properly initialized,
270but the slots are left untouched.
271The function returns its argument
272.IR p .
273.TP
274.BI "void *(*init)(void *" p );
275A pointer to a function:
276given a pointer
277.I p
278to at least
279.I initsz
280bytes of appropriately aligned memory,
281initialize an instance of the class in it:
282all of the vtable and class pointers are initialized,
283as are slots for which initializers are defined.
284Other slots are left untouched.
285The function returns its argument
286.IR p .
287.TP
288.B size_t n_supers;
289The number of direct superclasses.
290(This is zero exactly in the case of
291.BR SodObject .)
292.TP
293.B const SodClass *const *supers;
294A pointer to an array of
295.I n_supers
296pointers to class objects
297listing the class's direct superclasses,
298in the order in which they were listed in the class definition.
299If
300.I n_supers
301is zero,
302then this pointer is null.
303.TP
304.B size_t n_cpl;
305The number of superclasses in the class's class precedence list.
306.TP
307.B const SodClass *const *cpl;
308A pointer to an array of pointers to class objects
309listing all of the class's superclasses,
310from most- to least-specific,
311starting with the class itself,
312so
313.IB c ->cls.cpl[0]
314=
315.I c
316for all class objects
317.IR c .
318.TP
319.B const SodClass *link;
320If the class is a chain head, then this is a null pointer;
321otherwise it points to the class's distinguished link superclass
322(which might or might not be a direct superclass).
323.TP
324.B const SodClass *head;
325A pointer to the least-specific class in this class's chain;
326so
327.IB c ->cls.head->cls.link
328is always null,
329and either
330.IB c ->cls.link
331is null
332(in which case
333.IB c ->cls.head
334=
335.IR c )
336or
337.IB c ->cls.head
338=
339.IB c ->cls.link->cls.head \fR.
340.TP
341.B size_t level;
342The number of less specific superclasses in this class's chain.
343If
344.IB c ->cls.link
345is null then
346.IB c ->cls.level
347is zero;
348otherwise
349.IB c ->cls.level
350=
351.IB c ->cls.link->cls.level
352+ 1.
353.TP
354.B size_t n_chains;
355The number of chains formed by the class's superclasses.
356.TP
357.B const struct sod_chain *chains;
358A pointer to an array of
359.B struct sod_chain
360structures (see below) describing the class's superclass chains,
361in decreasing order of specificity of their most specific classes.
362It is always the case that
363.IB c ->cls.chains[0].classes[ c ->cls.level]
364=
365.IR c .
366.TP
367.B size_t off_islots;
368The offset of the class's
369.B islots
370structure relative to its containing
371.B ichain
372structure.
373The class doesn't define any slots if and only if this is zero.
374(The offset can't be zero because the vtable pointer is at offset zero.)
375.TP
376.B size_t islotsz;
377The size required to store the class's direct slots,
378i.e., the size of its
379.B islots
380structure.
381The class doesn't define any slots if and only if this is zero.
382.PP
383The
384.B struct sod_chain
385structure describes an individual chain of superclasses.
386It has the following members.
387.TP
388.B size_t n_classes;
389The number of classes in the chain.
390This is always at least one.
391.TP
392.B const SodClass *const *classes;
393A pointer to an array of class pointers
394listing the classes in the chain from least- to most-specific.
395So
396.IB classes [ i ]->cls.head
397=
398.IB classes [0]
399for all
4000 \(<=
401.I i
402<
403.IR n_classes ,
404.IB classes [0]->cls.link
405is always null,
406and
407.IB classes [ i ]->cls.link
408=
409.IB classes [ "i\fR \- 1" ]
410if
4111 \(<=
412.I i
413<
414.IR n_classes .
415.TP
416.B size_t off_ichain;
417The size of the
418.B ichain
419structure for this chain.
420.TP
421.B const struct sod_vtable *vt;
422The vtable for this chain.
423(It is possible, therefore, to duplicate the behaviour of the
424.I imprint
425function by walking the chain structure.
426The
427.I imprint
428function is much faster, though.)
429.TP
430.B size_t ichainsz;
431The size of the
432.B ichain
433structure for this chain.
434.
435.\"--------------------------------------------------------------------------
436.SH CLASS AND VTABLE LAYOUT
437.
438The layout algorithms for Sod instances and vtables are nontrivial.
439They are defined here in full detail,
440since they're effectively fixed by Sod's ABI compatibility guarantees,
441so they might as well be documented for the sake of interoperating
442programs.
443.PP
444Unfortunately, the descriptions are rather complicated,
445and, for the most part not necessary to a working understanding of Sod.
446The skeleton structure definitions shown should be more than enough
447for readers attempting to make sense of the generated headers and tables.
448.PP
449In the description that follows,
450uppercase letters vary over class names,
451while the corresponding lowercase letters indicate the class nicknames.
452Throughout, we consider a class
453.I C
454(therefore with nickname
455.IR c ).
456.
457.SS Generic instance structure
458The entire state of an instance of
459.I C
460is contained in a single structure of type
461.B struct
462.IB C __ilayout \fR.
463.IP
464.nf
465.ft B
466struct \fIC\fB__ilayout {
467\h'2n'union \fIC\fB__ichainu_\fIh\fB {
468\h'4n'struct \fIC\fB__ichain_\fIh\fB {
469\h'6n'const struct \fIC\fB__vt_\fIh\fB *_vt;
470\h'6n'struct \fIH\fB__islots \fIh\fB;
471\h'6n'\fR...\fB
472\h'6n'struct \fIC\fB__islots {
473\h'8n'\fItype\fB \fIslota\fB;
474\h'8n'\fR...\fB
475\h'6n'} \fIc\fB;
476\h'4n'} \fIc\fB;
477\h'4n'\fR...\fB
478\h'4n'struct \fIH\fB__ichain_\fIh\fB \fIh\fB;
479\h'2n'} \fIh\fB;
480\h'2n'union \fIB\fB__ichainu_\fIi\fB \fIi\fB;
481\h'2n'\fR...\fB
482};
483
484typedef struct \fIC\fB__ichain_\fIh\fB \fIC\fB;
485.ft P
486.fi
487.PP
488The set of superclasses of
489.IR C ,
490including itself,
491can be partitioned into chains
492by following their distinguished superclass links.
493(Formally, the chains are the equivalence classes determined by
494the reflexive, symmetric, transitive closure of
495the `links to' relation.)
496Chains are identified by naming their least specific classes;
497the least specific class in a chain is called the
498.IR "chain head" .
499Suppose that the chain head of the chain containing
500.I C
501itself is named
502.I H
503(though keep in mind that it's possible that
504.I H
505is in fact
506.I C
507itself.)
508.PP
509The
510.B ilayout
511structure contains one member for each of
512.IR C 's
513superclass chains.
514The first such member is
515.IP
516.B
517.B union
518.IB C __ichainu_ h
519.IB h ;
520.PP
521described below;
522this is followed by members
523.IP
524.B union
525.IB B __ichainu_ i
526.IB i ;
527.PP
528for each other chain,
529where
530.I I
531is the head
532and
533.I B
534the tail (most-specific) class of the chain.
535The members are in decreasing order
536of the specificity of the chains' most-specific classes.
537(Note that all but the first of these unions
538has already been defined as part of
539the definition of the corresponding
540.IR B .)
541.PP
542The
543.B ichainu
544union contains a member for each class in the chain.
545The first is
546.IP
547.B struct
548.IB C __ichain_ h
549.IB c ;
550.PP
551and this is followed by corresponding members
552.IP
553.B struct
554.IB A __ichain_ h
555.IB a ;
556.PP
557for each of
9c4a4110
MW
558.IR C 's
559superclasses
47de28ae
MW
560.IR A
561in the same chain in some (unimportant) order.
562A `pointer to
563.IR C '
564is always assumed
565(and, indeed, defined in C's type system)
566to be a pointer to the
567.B struct
568.IB C __ichain_ h \fR.
569.PP
570The
571.B ichain
572structure contains (in order), a pointer
573.IP
574.B const
575.B struct
576.IB C __vt_ h
577.B *_vt;
578.PP
579followed by a structure
580.IP
581.B struct
582.IB A __islots
583.IB a ;
584.PP
585for each superclass
586.I A
587of
588.IR C
589in the same chain which defines slots,
590from least- to most-specific;
591if
592.I C
593defines any slots,
594then the last member is
595.IP
596.B struct
597.IB C __islots
598.IB c ;
599.PP
600Finally, the
601.B islots
602structure simply contains one member for each slot defined by
603.I C
604in the order they appear in the class definition.
605.
606.SS Generic vtable structure
607As described above,
608each
609.B ichain
610structure of an instance's storage
611has a vtable pointer
612.IP
613.B const
614.B struct
615.IB C __vt_ h
616.B *_vt;
617.PP
618In general,
619the vtables for the different chains
620will have
621.I different
622structures.
623.PP
624The instance layout split neatly into disjoint chains.
625This is necessary because
626each
627.B ichain
628must have as a prefix the
629.B ichain
9c4a4110
MW
630for each superclass in the same chain,
631and each slot must be stored in exactly one place.
47de28ae
MW
632The layout of vtables doesn't have this second requirement:
633it doesn't matter that there are
634multiple method entry pointers
635for the same effective method
636as long as they all work correctly.
9c4a4110
MW
637Indeed, it's essential that they do,
638because each chain's method entry function
639will need to apply a different offset to the receiver pointer
640before invoking the effective method.
47de28ae
MW
641.PP
642A vtable for a class
643.I C
644with chain head
645.I H
646has the following general structure.
647.IP
648.nf
649.ft B
650union \fIC\fB__vtu_\fIh\fB {
651\h'2n'struct \fIC\fB__vt_\fIh\fB {
652\h'4n'const \fIP\fB *_class;
653\h'4n'size_t _base;
654\h'4n'\fR...\fB
655\h'4n'const \fIQ\fB *_cls_\fIj\fB;
656\h'4n'\fR...\fB
657\h'4n'ptrdiff_t _off_\fIi\fB;
658\h'4n'\fR...\fB
659\h'4n'struct \fIC\fB__vtmsgs_\fIa\fB {
660\h'6n'\fItype\fB (*\fImsg\fB)(\fIC\fB *, \fR...\fB);
661\h'6n'\fR...\fB
662\h'4n'} \fIa\fB;
663\h'4n'\fR...\fB
664\h'2n'} \fIc\fB;
665};
666
667extern const union \fIC\fB__vtu_\fIh\fB \fIC\fB__vtable_\fIh\fB;
668.ft P
669.fi
670.PP
671The outer layer is a
47de28ae
MW
672.B union
673.IB C __vtu_ h
47de28ae
MW
674containing a member
675.IP
676.B struct
677.IB A __vt_ h
678.IB a ;
679.PP
680for each of
681.IR C 's
682superclasses
683.I A
684in the same chain,
685with
686.I C
687itself listed first.
688This is mostly an irrelevant detail,
689whose purpose is to defend against malicious compilers:
690pointers are always to one of the inner
691.B vt
692structures.
693It's important only because it's the outer
694.B vtu
695union which is exported by name.
696Specifically, for each chain of
697.IR C 's
698superclasses
699there is an external object
700.IP
701.B const union
702.IB A __vtu_ i
703.IB C __vtable_ i ;
704.PP
705where
706.I A
707and
708.I I
709are respectively the most and least specific classes in the chain.
710.PP
711The first member in the
712.B vt
713structure is the
714.I root class pointer
715.IP
716.B const
717.IR P
718.B *_class;
719.PP
720Among the superclasses of
721.I C
722there must be exactly one class
723.I O
724which itself has no direct superclasses;
725this is the
726.I root superclass
727of
728.IR C .
729(This is a rule enforced by the Sod translator.)
730The metaclass
731.I R
732of
9c4a4110 733.I O
47de28ae
MW
734is then the
735.I root metaclass
736of
737.IR C .
738The
739.B _class
740member points to the
741.B ichain
742structure of most specific superclass
743.I P
744of
745.I M
746in the same chain as
747.IR R .
748.PP
749This is followed by the
750.I base offset
751.IP
752.B size_t
753.B _base;
754.PP
755which is simply the offset of the
756.B ichain
757structure from the instance base.
758.PP
759The rest of the vtable structure is populated
760by walking the superclass chain containing
761.I C
762as follows.
763For each such superclass
764.IR B ,
765in increasing order of specificity,
766walk the class precedence list of
767.IR B ,
768again starting with its least-specific superclass.
769(This complex procedure guarantees that
770the vtable structure for a class is a prefix of
771the vtable structure for any of its subclasses in the same chain.)
772.PP
773So, let
774.I A
775be some superclass of
776.I C
777which has been encountered during this traversal.
778.hP \*o
779Let
780.I N
781be the metaclass of
782.IR A .
783Examine the superclass chains of
784.I N
785in order of decreasing specificity of their most-specific classes.
786Let
787.I J
788be the chain head of such a chain,
789and let
790.I Q
791be the most specific superclass of
792.I M
793in the same chain as
794.IR J .
795Then, if there is currently no class pointer of type
9c4a4110 796.IR Q ,
47de28ae
MW
797then add a member
798.RS
799.IP
800.B const
801.I Q
802.BI *_cls_ j ;
803.PP
804to the vtable
805pointing to the appropriate
806.B islots
807structure within
808.IR M 's
809class object.
810.RE
811.hP \*o
812Examine the superclass chains of
813.I A
814in order of decreasing specificity of their most-specific classes.
815Let
816.I I
817be the chain head of such a chain.
818If there is currently no member
819.BI _off_ i
820then add a member
821.RS
822.IP
823.B ptrdiff_t
824.BI _off_ i ;
825.PP
826to the vtable,
827containing the (signed) offset from the
828.B ichain
829structure of the chain headed by
830.I h
831to that of the chain headed by
832.I i
833within the instance's layout.
834.RE
835.hP \*o
836If class
837.I A
838defines any messages,
839and there is currently no member
9c4a4110 840.IR a ,
47de28ae
MW
841then add a member
842.RS
843.IP
844.B struct
845.IB C __vtmsgs_ a
846.IB a ;
847.PP
848to the vtable.
849See below.
850.RE
851.PP
852Finally, the
853.B vtmsgs
854structures contain pointers to the effective method entry functions
855for the messages defined by a superclass.
856There may be more than one method entry for a message,
857but all of the entry pointers for a message appear together,
858and entry pointers for separate messages appear
859in the order in which the messages are defined.
860If the receiver class has no applicable primary method for a message
861then it's usual for the method entry pointer to be null
862(though, as with a lot of things in Sod,
863extensions may do something different).
864.PP
865For a standard message which takes a fixed number of arguments,
866defined as
867.IP
868.I tr
869.IB m ( \c
870.I t1
871.IB a1 ,
872.RB ... ,
873.I tn
874.IB an );
875.PP
876there is always a `main' entry point,
877.IP
878.I tr
879.BI (* m )( \c
880.I C
881.BI * me ,
882.I t1
883.IB a1 ,
884.RB ... ,
885.I tn
886.IB an );
887.PP
888For a standard message which takes a variable number of arguments,
889defined as
890.IP
891.I tr
892.IB m ( \c
893.I t1
894.IB a1 ,
895.RB ... ,
896.I tn
897.IB an ,
898.B ...);
899.PP
900two entry points are defined:
901the usual `main' entry point
902which accepts a variable number of
903arguments,
904and a `valist' entry point
905which accepts an argument of type
906.B va_list
907in place of the variable portion of the argument list.
908.IP
909.I tr
910.BI (* m )( \c
911.I C
912.BI * me ,
913.I t1
914.IB a1 ,
915.RB ... ,
916.I tn
917.IB an ,
918.B ...);
919.br
920.I tr
921.BI (* m __v)( \c
922.I C
923.BI * me ,
924.I t1
925.IB a1 ,
926.RB ... ,
927.I tn
928.IB an ,
929.B va_list
930.IB sod__ap );
931.
932.SS Additional definitions
933In addition to the instance and vtable structures described above,
934the following definitions are made for each class
935.IR C .
936.PP
937For each message
938.I m
939directly defined by
940.I C
941there is a macro definition
942.IP
943.B #define
944.IB C _ m ( me ,
945.RB ... )
946.IB me ->_vt-> c . m ( me ,
947.RB ... )
948.PP
949which makes sending the message
950.I m
951to an instance of (any subclass of)
952.I C
953somewhat less ugly.
954If
955.I m
956takes a variable number of arguments,
957the macro is more complicated
958and is only available in compilers advertising C99 support,
959but the effect is the same.
960For each variable-argument message,
961there is also an additional macro
962for calling the `valist' entry point.
963.IP
964.B #define
965.IB C _ m __v( me ,
966.RB ...,
967.IB sod__ap )
968.if !t \{\
969\e
970.br
971\h'4m'\c
972.\}
973.IB me ->_vt-> c . m __v( me ,
974.RB ...,
975.IB sod__ap )
976.PP
977For each proper superclass
978.I A
979of
980.IR C ,
981there is a macro defined
982.IP
983.I A
984.BI * C __CONV_ a ( C
985.BI * _obj );
986.PP
987(named in
988.IR "upper case" )
989which converts a (static-type) pointer to
990.I C
991to a pointer to the same actual instance,
992but statically typed as a pointer to
993.IR A .
994This is most useful when
995.I A
996is not in the same chain as
997.I C
998since in-chain upcasts are both trivial and rarely needed,
999but the full set is defined for the sake of completeness.
1000.PP
1001Finally, the class object is defined as
1002.IP
1003.B extern const struct
1004.IB R __ilayout
1005.IB C __classobj;
1006.br
1007.B #define
1008.IB C __class
1009.BI (& C __classobj. j . r )
1010.PP
1011The exported symbol
1012.IB C __classobj
1013contains the entire class instance.
1014This is usually rather unwieldy.
1015The macro
1016.IB C __class
1017is usable as a pointer of type
1018.B const
1019.I R
1020.BR * ,
1021where
1022.I R
1023is the root metaclass of
1024.IR C ,
1025i.e., the metaclass of the least specific superclass of
1026.IR C ;
1027usually this is
1028.BR "const SodClass *" .
1029.
1030.\"--------------------------------------------------------------------------
1031.SH SEE ALSO
1032.BR sod (3).
1033.
1034.\"--------------------------------------------------------------------------
1035.SH AUTHOR
1036Mark Wooding, <mdw@distorted.org.uk>
1037.
1038.\"----- That's all, folks --------------------------------------------------