mdw@git.distorted.org.uk Git - 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 Sensble 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 General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or
  15 .\" (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 General Public License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU General Public License
  23 .\" along with SOD; if not, write to the Free Software Foundation,
  24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  25 .
  26 .\"\X'tty: sgr 1'
  27 .\" String definitions and font selection.
  28 .ie t \{\
  29 .  ds o \(bu
  30 .  if \n(.g .fam P
  31 .\}
  32 .el \{\
  33 .  ds o o
  34 .\}
  35 .
  36 .\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
  37 .de hP
  38 .IP
  39 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
  40 ..
  41 .
  42 .\"--------------------------------------------------------------------------
  43 .TH sod 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design"
  44 .
  45 .SH NAME
  46 sod \- Sensible Object Design runtime library
  47 .
  48 .\"--------------------------------------------------------------------------
  49 .SH SYNOPSIS
  50 .B #include <sod/sod.h>
  51 .PP
  52 .B void *\c
  53 .B SOD_XCHAIN(\c
  54 .IB chead ,
  55 .BI "const " cls " *" obj );
  56 .br
  57 .B ptrdiff_t
  58 .B SOD_OFFSETDIFF(\c
  59 .IB type ,
  60 .IB mema ,
  61 .IB memb );
  62 .br
  63 .IB cls "__ilayout *" \c
  64 .B SOD_ILAYOUT(\c
  65 .IB cls ,
  66 .IB chead ,
  67 .BI "const void *" obj );
  68 .br
  69 .B SOD_CAR(\c
  70 .IB arg ,
  71 .RB ... );
  72 .PP
  73 .B const void *\c
  74 .B SOD_CLASSOF(\c
  75 .BI "const " cls " *" obj );
  76 .br
  77 .B void *\c
  78 .B SOD_INSTBASE(\c
  79 .BI "const " cls " *" obj );
  80 .br
  81 .IB cls " *" \c
  82 .B SOD_CONVERT(\c
  83 .IB cls ,
  84 .BI "const void *" obj );
  85 .br
  86 .B SOD_DECL(\c
  87 .IB cls ,
  88 .IB var );
  89 .PP
  90 .B int
  91 .B sod_subclassp(\c
  92 .BI "const SodClass *" sub ,
  93 .BI "const SodClass *" super );
  94 .br
  95 .B int
  96 .B sod_convert(\c
  97 .BI "const SodClass *" cls ,
  98 .BI "const void *" obj );
  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 Infrastructure macros
 111 These macros are mostly intended for use in code
 112 generated by the Sod translator.
 113 Others may find them useful for special effects,
 114 but they can be tricky to understand and use correctly
 115 and can't really be recommended for general use.
 116 .PP
 117 The
 118 .B SOD_XCHAIN
 119 macro performs a `cross-chain upcast'.
 120 Given a pointer
 121 .I cls
 122 .BI * obj
 123 to an instance of a class of type
 124 .I cls
 125 and the nickname
 126 .I chead
 127 of the least specific class in one of
 128 .IR cls 's
 129 superclass chains which does not contain
 130 .I cls
 131 itself,
 132 .B SOD_XCHAIN(\c
 133 .IB chead ,
 134 .IB obj )
 135 returns the address of that chain's storage
 136 within the instance layout as a raw
 137 .B void *
 138 pointer.
 139 (Note that
 140 .I cls
 141 is not mentioned explicitly.)
 142 This macro is used by the generated
 143 .IB CLASS __CONV_ CLS
 144 conversion macros,
 145 which you are encouraged to use instead where possible.
 146 .PP
 147 The
 148 .B SOD_OFFSETDIFF
 149 macro returns the signed offset between
 150 two members of a structure or union type.
 151 Given a structure or union type
 152 .IR type ,
 153 and two member names
 154 .I mema
 155 and
 156 .IR memb ,
 157 then
 158 .B SOD_OFFSETDIFF(\c
 159 .IB type ,
 160 .IB mema ,
 161 .IB memb )
 162 gives the difference, in bytes,
 163 between the objects
 164 .IB x . mema
 165 and
 166 .IB x . memb
 167 for any object
 168 .I x
 169 of type
 170 .IR type .
 171 This macro is used internally when generating vtables
 172 and is not expected to be very useful elsewhere.
 173 .PP
 174 The
 175 .B SOD_ILAYOUT
 176 macro recovers the instance layout base address
 177 from a pointer to one of its instance chains.
 178 Specifically, given a class name
 179 .IR cls ,
 180 the nickname
 181 .I chead
 182 of the least specific class in one of
 183 .IR cls 's
 184 superclass chains,
 185 and a pointer
 186 .I obj
 187 to the instance storage for the chain containing
 188 .I chead
 189 within an exact instance of
 190 .I cls
 191 (i.e., not an instance of any proper subclass),
 192 .B SOD_ILAYOUT(\c
 193 .IB cls ,
 194 .IB chead ,
 195 .IB obj )
 196 returns the a pointer to the layout structure containing
 197 .IB obj .
 198 This macro is used internally in effective method bodies
 199 and is not expected to be very useful elsewhere
 200 since it's unusual to have such specific knowledge
 201 about the dynamic type of an instance.
 202 The
 203 .B SOD_INSTBASE
 204 macro (described below) is more suited to general use.
 205 .PP
 206 The
 207 .B SOD_CAR
 208 macro accepts one or more arguments
 209 and expands to just its first argument,
 210 discarding the others.
 211 It is only defined if the C implementation
 212 advertises support for C99.
 213 It is used in the definitions of message convenience macros
 214 for messages which accept a variable number of arguments
 215 but no required arguments,
 216 and is exported because the author has found such a thing useful in
 217 other contexts.
 218 .
 219 .SS Utility macros
 220 The following macros are expected to be useful
 221 in Sod method definitions and client code.
 222 .PP
 223 The
 224 .B SOD_CLASSOF
 225 macro returns the class object describing an instance's dynamic class.
 226 Given a pointer
 227 .BI "const " cls " *" obj
 228 to an instance,
 229 .BI SOD_CLASSOF( obj )
 230 returns a pointer to
 231 .IR obj 's
 232 dynamic class,
 233 which
 234 (assuming
 235 .I obj
 236 is typed correctly in the first place)
 237 will be a subclass of
 238 .IR cls .
 239 (If you wanted the class object for
 240 .I cls
 241 itself,
 242 it's called
 243 .IB cls __class \fR.)
 244 .PP
 245 The
 246 .B SOD_INSTBASE
 247 macro finds the base address of an instance's layout.
 248 Given a pointer
 249 .BI "const " cls " *" obj
 250 to an instance,
 251 .BI SOD_INSTBASE( obj )
 252 returns the base address of the storage allocated to
 253 .IR obj .
 254 This is useful if you want to free a dynamically allocated instance,
 255 for example.
 256 This macro needs to look up an offset in
 257 .IR obj 's
 258 vtable to do its work.
 259 Compare
 260 .B SOD_ILAYOUT
 261 above,
 262 which is faster but requires
 263 precise knowledge of the instance's dynamic class.
 264 .PP
 265 The
 266 .B SOD_CONVERT
 267 macro performs general conversions
 268 (up-, down-, and cross-casts) on instance pointers.
 269 Given a class name
 270 .I cls
 271 and a pointer
 272 .BI "const void *" obj
 273 to an instance,
 274 .B SOD_CONVERT(\c
 275 .IB cls ,
 276 .IB obj )
 277 returns an appropriately converted pointer to
 278 .I obj
 279 if
 280 .I obj
 281 is indeed an instance of (some subclass of)
 282 .IR cls ;
 283 otherwise it returns a null pointer.
 284 This macro is a simple wrapper around the
 285 .B sod_convert
 286 function described below,
 287 which is useful in the common case that
 288 the target class is known statically.
 289 .PP
 290 The
 291 .B SOD_DECL
 292 macro declares and initializes an instance
 293 with automatic storage duration.
 294 Given a class name
 295 .I cls
 296 and an identifier
 297 .IR var ,
 298 .B SOD_DECL(\c
 299 .IB cls ,
 300 .IB var )
 301 declares
 302 .I var
 303 to be a pointer to an instance of
 304 .IR cls .
 305 The instance is initialized in the sense that
 306 its vtable and class pointers have been set up,
 307 and slots for which initializers are defined
 308 are set to the appropriate initial values.
 309 The instance has automatic storage duration:
 310 pointers to it will become invalid when control
 311 exits the scope of the declaration.
 312 .
 313 .SS Functions
 314 The following functions are provided.
 315 .PP
 316 The
 317 .B sod_subclassp
 318 function answers whether one class
 319 .I sub
 320 is actually a subclass of another class
 321 .IR super .
 322 .B sod_subclassp(\c
 323 .IB sub ,
 324 .IB super )
 325 returns nonzero if and only if
 326 .I sub
 327 is a subclass of
 328 .IR super .
 329 This involves a run-time trawl through the class structures:
 330 while some effort has been made to make it perform well
 331 it's still not very fast.
 332 .PP
 333 The
 334 .B sod_convert
 335 function performs general conversions
 336 (up-, down-, and cross-casts) on instance pointers.
 337 Given a class pointer
 338 .I cls
 339 and an instance pointer
 340 .IR obj ,
 341 .B sod_convert(\c
 342 .IB cls ,
 343 .IB obj )
 344 returns an appropriately converted pointer to
 345 .I obj
 346 in the case that
 347 .I obj
 348 is an instance of (some subclass of)
 349 .IR cls ;
 350 otherwise it returns null.
 351 This involves a run-time trawl through the class structures:
 352 while some effort has been made to make it perform well
 353 it's still not very fast.
 354 For upcasts (where
 355 .I cls
 356 is a superclass of the static type of
 357 .IR obj )
 358 the automatically defined conversion macros should be used instead,
 359 because they're much faster and can't fail.
 360 When the target class is known statically,
 361 it's slightly more convenient to use the
 362 .B SOD_CONVERT
 363 macro instead.
 364 .
 365 .\"--------------------------------------------------------------------------
 366 .SH SEE ALSO
 367 .BR sod-structs (3).
 368 .
 369 .\"--------------------------------------------------------------------------
 370 .SH AUTHOR
 371 Mark Wooding, <mdw@distorted.org.uk>
 372 .
 373 .\"----- That's all, folks --------------------------------------------------