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