chiark - git - mdw - sod/blob - lib/sod.3

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" The Sod runtime library
   4 .\"
   5 .\" (c) 2015 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the Sensible Object Design, an object system for C.
  11 .\"
  12 .\" SOD is free software; you can redistribute it and/or modify
  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.
  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
  20 .\" GNU Library General Public License for more details.
  21 .\"
  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.
  26 .
  27 .\" Highlight using terminal escapes, rather than overstriking.
  28 .\"\X'tty: sgr 1'
  29 .
  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 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design"
  47 .
  48 .SH NAME
  49 sod \- Sensible Object Design runtime library
  50 .
  51 .\"--------------------------------------------------------------------------
  52 .SH SYNOPSIS
  53 .B #include <sod/sod.h>
  54 .PP
  55 .B void *\c
  56 .B SOD_XCHAIN(\c
  57 .IB chead ,
  58 .BI "const " cls " *" obj );
  59 .br
  60 .B ptrdiff_t
  61 .B SOD_OFFSETDIFF(\c
  62 .IB type ,
  63 .IB mema ,
  64 .IB memb );
  65 .br
  66 .IB cls "__ilayout *" \c
  67 .B SOD_ILAYOUT(\c
  68 .IB cls ,
  69 .IB chead ,
  70 .BI "const void *" obj );
  71 .br
  72 .B void *\c
  73 .B SOD_INSTBASE(\c
  74 .BI "const " cls " *" obj );
  75 .PP
  76 .B const void *\c
  77 .B SOD_CLASSOF(\c
  78 .BI "const " cls " *" obj );
  79 .br
  80 .B int
  81 .B sod_subclassp(\c
  82 .BI "const SodClass *" sub ,
  83 .BI "const SodClass *" super );
  84 .PP
  85 .IB cls " *" \c
  86 .B SOD_CONVERT(\c
  87 .IB cls ,
  88 .BI "const void *" obj );
  89 .br
  90 .B int
  91 .B sod_convert(\c
  92 .BI "const SodClass *" cls ,
  93 .BI "const void *" obj );
  94 .PP
  95 .B SOD_DECL(\c
  96 .IB cls ,
  97 .IB var );
  98 .PP
  99 .
 100 .\"--------------------------------------------------------------------------
 101 .SH DESCRIPTION
 102 .
 103 The functions and macros defined here generally expect that
 104 instances and classes inherit from the standard
 105 .B SodObject
 106 root object.
 107 While the translator can (at some effort) support alternative roots,
 108 they will require different run-time support machinery.
 109 .
 110 .SS Layout utilities
 111 The following macros are useful in
 112 finding one's way around an instance layout structure,
 113 given various levels of information about
 114 what kind of object one is dealing with,
 115 or for computing the tables which are used for
 116 this kind of navigation.
 117 .PP
 118 These macros are mostly intended for use in
 119 code generated by the Sod translator.
 120 Others may find them useful for special effects,
 121 but they can be tricky to understand and use correctly
 122 and can't really be recommended for general use.
 123 .PP
 124 The
 125 .B SOD_OFFSETDIFF
 126 macro returns the signed offset between
 127 two members of a structure or union type.
 128 Given a structure or union type
 129 .IR type ,
 130 and two member names
 131 .I mema
 132 and
 133 .IR memb ,
 134 then
 135 .B SOD_OFFSETDIFF(\c
 136 .IB type ,
 137 .IB mema ,
 138 .IB memb )
 139 gives the difference, in bytes,
 140 between the objects
 141 .IB x . mema
 142 and
 143 .IB x . memb
 144 for any object
 145 .I x
 146 of type
 147 .IR type .
 148 This macro is used internally when generating vtables
 149 and is not expected to be very useful elsewhere.
 150 .PP
 151 The
 152 .B SOD_ILAYOUT
 153 macro recovers the instance layout base address
 154 from a pointer to one of its instance chains.
 155 Specifically, given a class name
 156 .IR cls ,
 157 the nickname
 158 .I chead
 159 of the least specific class in one of
 160 .IR cls 's
 161 superclass chains,
 162 and a pointer
 163 .I obj
 164 to the instance storage for the chain containing
 165 .I chead
 166 within an exact instance of
 167 .I cls
 168 (i.e., not an instance of any proper subclass),
 169 .B SOD_ILAYOUT(\c
 170 .IB cls ,
 171 .IB chead ,
 172 .IB obj )
 173 returns the a pointer to the layout structure containing
 174 .IB obj .
 175 This macro is used internally in effective method bodies
 176 and is not expected to be very useful elsewhere
 177 since it's unusual to have such specific knowledge
 178 about the dynamic type of an instance.
 179 The
 180 .B SOD_INSTBASE
 181 macro (described below) is more suited to general use.
 182 .PP
 183 The
 184 .B SOD_INSTBASE
 185 macro finds the base address of an instance's layout.
 186 Given a pointer
 187 .BI "const " cls " *" obj
 188 to an instance,
 189 .BI SOD_INSTBASE( obj )
 190 returns the base address of the storage allocated to
 191 .IR obj .
 192 This is useful if you want to free a dynamically allocated instance,
 193 for example.
 194 This macro needs to look up an offset in
 195 .IR obj 's
 196 vtable to do its work.
 197 Compare
 198 .B SOD_ILAYOUT
 199 above,
 200 which is faster but requires
 201 precise knowledge of the instance's dynamic class.
 202 .
 203 .SS Classes
 204 The following macros and functions
 205 query the runtime relationhips between
 206 instances and classes.
 207 .PP
 208 The
 209 .B SOD_CLASSOF
 210 macro returns the class object describing an instance's dynamic class.
 211 Given a pointer
 212 .BI "const " cls " *" obj
 213 to an instance,
 214 .BI SOD_CLASSOF( obj )
 215 returns a pointer to
 216 .IR obj 's
 217 dynamic class,
 218 which
 219 (assuming
 220 .I obj
 221 is typed correctly in the first place)
 222 will be a subclass of
 223 .IR cls .
 224 (If you wanted the class object for
 225 .I cls
 226 itself,
 227 it's called
 228 .IB cls __class \fR.)
 229 .PP
 230 The
 231 .B sod_subclassp
 232 function answers whether one class
 233 .I sub
 234 is actually a subclass of another class
 235 .IR super .
 236 .B sod_subclassp(\c
 237 .IB sub ,
 238 .IB super )
 239 returns nonzero if and only if
 240 .I sub
 241 is a subclass of
 242 .IR super .
 243 This involves a run-time trawl through the class structures:
 244 while some effort has been made to make it perform well
 245 it's still not very fast.
 246 .
 247 .SS Conversions
 248 The following macros and functions are used
 249 to convert instance pointers of some (static) type
 250 into instance pointers of other static types
 251 to the same instance.
 252 .PP
 253 The
 254 .B SOD_XCHAIN
 255 macro performs a `cross-chain upcast'.
 256 Given a pointer
 257 .I cls
 258 .BI * obj
 259 to an instance of a class of type
 260 .I cls
 261 and the nickname
 262 .I chead
 263 of the least specific class in one of
 264 .IR cls 's
 265 superclass chains which does not contain
 266 .I cls
 267 itself,
 268 .B SOD_XCHAIN(\c
 269 .IB chead ,
 270 .IB obj )
 271 returns the address of that chain's storage
 272 within the instance layout as a raw
 273 .B void *
 274 pointer.
 275 (Note that
 276 .I cls
 277 is not mentioned explicitly.)
 278 This macro is used by the generated
 279 .IB cls __CONV_ c
 280 conversion macros,
 281 which you are encouraged to use instead where possible.
 282 .PP
 283 The
 284 .B SOD_CONVERT
 285 macro
 286 and
 287 .B sod_convert
 288 function
 289 perform general conversions
 290 (up-, down-, and cross-casts) on instance pointers.
 291 Given a class
 292 .I cls
 293 and a pointer
 294 .BI "const void *" obj
 295 to an instance,
 296 they return an appropriately converted pointer to
 297 .I obj
 298 if
 299 .I obj
 300 is indeed an instance of (some subclass of)
 301 .IR cls ;
 302 otherwise they return a null pointer.
 303 .PP
 304 The
 305 .B SOD_CONVERT
 306 macro expects
 307 .I cls
 308 to be a class name;
 309 the
 310 .B sod_convert
 311 function
 312 expects a pointer to a class object instead.
 313 .PP
 314 This involves a run-time trawl through the class structures:
 315 while some effort has been made to make it perform well
 316 it's still not very fast.
 317 For upcasts (where
 318 .I cls
 319 is a superclass of the static type of
 320 .IR obj )
 321 the automatically defined conversion macros should be used instead,
 322 because they're much faster and can't fail.
 323 .PP
 324 When the target class is known statically,
 325 it's slightly more convenient to use the
 326 .B SOD_CONVERT
 327 macro rather than the
 328 .B sod_convert
 329 function,
 330 since the class object name is longer and uglier,
 331 and the macro returns a pointer of the correct type.
 332 .
 333 .SS Instance lifecycle
 334 The following macros and functions
 335 manage the standard steps along
 336 an instance's lifecycle.
 337 .PP
 338 The
 339 .B SOD_DECL
 340 macro declares and initializes an instance
 341 with automatic storage duration.
 342 Given a class name
 343 .I cls
 344 and an identifier
 345 .IR var ,
 346 .B SOD_DECL(\c
 347 .IB cls ,
 348 .IB var )
 349 declares
 350 .I var
 351 to be a pointer to an instance of
 352 .IR cls .
 353 The instance is initialized in the sense that
 354 its vtable and class pointers have been set up,
 355 and slots for which initializers are defined
 356 are set to the appropriate initial values.
 357 The instance has automatic storage duration:
 358 pointers to it will become invalid when control
 359 exits the scope of the declaration.
 360 .
 361 .\"--------------------------------------------------------------------------
 362 .SH SEE ALSO
 363 .BR sod (1),
 364 .BR sod-structs (3).
 365 .
 366 .\"--------------------------------------------------------------------------
 367 .SH AUTHOR
 368 Mark Wooding, <mdw@distorted.org.uk>
 369 .
 370 .\"----- That's all, folks --------------------------------------------------