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