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