1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
4 <TITLE>Access To The GHC CVS Repository</TITLE>
5 <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; SunOS 5.5.1 i86pc) [Netscape]">
9 <H1>Coding suggestions for GHC/Hugs related code</h1>
13 NB These are just suggestions. They're not set in stone. Some of
14 them are probably misguided. If you disagree with them, feel free to
15 modify this document (and make your commit message reasonably informative)
16 or mail someone (eg <a href="fp-cvs-fptools@dcs.gla.ac.uk">The FP-CVS mailing list</a> or
18 href="mailto:reid-alastair@cs.yale.edu">reid-alastair@cs.yale.edu</a>).
23 If you haven't read them already, you might like to check the following.
24 Where they conflict with our suggestions, they're probably right.
28 Writing Solid Code, Microsoft Press. (Highly recommended. Possibly
29 the only Microsoft Press book that's worth reading. SimonPJ has a
33 Autoconf documentation (which doesn't seem to be on the web).
34 See also <a href="http://peti.gmd.de/autoconf-archive/">The autoconf macro archive</a> and
35 <a href="http://www.cyclic.com/cyclic-pages/autoconf.html">Cyclic Software's description</a>
38 <a href="http://www.cs.umd.edu/users/cml/cstyle/indhill-cstyle.html">Indian Hill C Style and Coding Standards</a>.
41 <a href="http://www.cs.umd.edu/users/cml/cstyle/">A list of C programming style links</a>
44 <a href="http://www.lysator.liu.se/c/c-www.html">A very large list of C programming links</a>
47 <a href="http://www.geek-girl.com/unix.html">A list of Unix programming links</a>
53 <h2>Portability issues</h2>
57 We use ANSI C with some extensions. In particular, we use:
60 <li>ANSI style prototypes
61 <li>#elsif, #error, #warning, ## and other cpp features
65 We use the following gcc extensions (see gcc documentation):
67 <li>zero length arrays (useful as the last field of a struct)
68 <li>inline annotations on functions (see later)
69 <li>Labeled elements in initialisers
70 <li>Function attributes (mostly just no_return)
71 <li>Macro varargs (actually, we don't use them yet but I'm very tempted)
72 <li>Alastair really likes to use C++ style comments - but
73 he'll probably regret it later.
74 <li>other stuff I've forgotten about...
77 Some of these gcc/ANSI features could be avoided (for example, we
78 could use __inline__ instead of inline or use the usual PROTO((...))
79 trick in function prototypes) - but some of them can't be avoided
80 so we don't try with the others.
83 char can be signed or unsigned - always say which you mean
86 Some architectures have memory alignment constraints.
87 Others don't have any constraints but go faster if you align things.
88 These macros tell you which alignment to use
91 /* minimum alignment of unsigned int */
92 #define ALIGNMENT_UNSIGNED_INT 4
94 /* minimum alignment of long */
95 #define ALIGNMENT_LONG 4
97 /* minimum alignment of float */
98 #define ALIGNMENT_FLOAT 4
100 /* minimum alignment of double */
101 #define ALIGNMENT_DOUBLE 4
105 Use StgInt, StgWord and StgPtr when reading/writing ints and ptrs to
106 the stack or heap. Note that, by definition, StgInt, StgWord and
107 StgPtr are the same size and have the same alignment constraints
108 even if sizeof(int) != sizeof(ptr) on that platform.
111 Use StgInt8, StgInt16, etc when you need a certain minimum number of
112 bits in a type. Use int and nat when there's no particular
113 constraint. ANSI C only guarantees that ints are at least 16 bits but
114 within GHC we assume they are 32 bits. (I'm not sure if this is a
118 Use StgFloat and StgDouble for floating point values which will go
119 on/have come from the stack or heap. Note that StgFloat may be the
120 same as StgDouble on some architectures (eg Alphas) and that it might
121 occupy many StgWords.
124 Use PK_FLT(addr), PK_DBL(addr) to read StgFloat and
125 StgDouble values from the stack/heap, and ASSIGN_FLT(val,addr)/
126 ASSIGN_DBL(val,addr) to assign StgFloat/StgDouble values to heap/stack
127 locations. These macros take care of alignment restrictions.
130 Heap/Stack locations are StgWord aligned; the alignment requirements
131 of an StgDouble may be more than that of StgWord, but we don't pad
132 misaligned StgDoubles (doing so would be too much hassle).
135 Doing a direct assignment/read of an StgDouble to/from a mis-aligned
136 location may not work, so we use the ASSIGN_DBL(,)/PK_DBL() macro,
137 which goes via a temporary.
140 Problem: if the architecture allows mis-aligned accesses, but prefers
141 aligned accesses, these macros just add an extra level of indirection.
142 We need to distinguish between an architecture that allows mis-aligned
143 accesses and one that just imposes a performance penalty (this is most
144 of them). Perhaps have PREFERRED_ALIGNMENT and REQUIRED_ALIGMENT
148 Avoid conditional code like this:
151 #ifdef solaris_HOST_OS
152 // do something solaris specific
156 Instead, add an appropriate test to the configure.in script and use
157 the result of that test instead.
165 The problem is that things change from one version of an OS to another
166 - things get added, things get deleted, things get broken, some things
167 are optional extras. Using "feature tests" instead of "system tests"
168 makes things a lot less brittle. Things also tend to get documented
173 <h2>Debugging/robustness tricks</h2>
176 Anyone who has tried to debug a garbage collector or code generator
177 will tell you: "If a program is going to crash, it should crash as
178 soon, as noisily and as often as possible." There's nothing worse
179 than trying to find a bug which only shows up when running GHC on
180 itself and doesn't manifest itself until 10 seconds after the actual
181 cause of the problem.
184 The ideas in this section are mostly aimed at this issue:
188 Use assertions. Use lots of assertions. If you write a comment
189 that says "takes a +ve number" add an assertion. If you're casting
190 an int to a nat, add an assertion. If you're casting an int to a char,
194 When defining an enumeration, it's a good idea not to use 0 for normal
195 values. Instead, make 0 raise an internal error. The idea here is to
196 make it easier to detect pointer-related errors on the assumption that
197 random pointers are more likely to point to a 0 than to anything else.
201 { i_INTERNAL_ERROR /* Instruction 0 raises an internal error */
202 , i_PANIC /* irrefutable pattern match failed! */
203 , i_ERROR /* user level error */
207 <li> Use #warning or #error whenever you write a piece of incomplete/broken code.
210 <h2>Syntactic details</h2>
213 <li><b>Important:</b> Put "redundant" braces or parens in your code.
214 Omitting braces and parens leads to very hard to spot bugs -
215 especially if you use macros (and you might have noticed that GHC does
222 Put braces round the body of for loops, while loops, if statements, etc.
223 even if they "aren't needed" because it's really hard to find the resulting
224 bug if you mess up. Indent them any way you like but put them in there!
227 When defining a macro, always put parens round args - just in case.
230 #define add(x,y) ((x)+(y))
238 Don't define macros that expand to a list of statements.
239 You could just use braces as in:
242 #define ASSIGN_CC_ID(ccID) \
249 but it's better to use the "do { ... } while (0)" trick instead:
252 #define ASSIGN_CC_ID(ccID) \
259 The following explanation comes from
260 <a href="http://www.cs.umd.edu/users/cml/cstyle/code-std-disc.txt">The Usenet C programming FAQ</a>
262 10.4: What's the best way to write a multi-statement macro?
264 A: The usual goal is to write a macro that can be invoked as if it
265 were a statement consisting of a single function call. This
266 means that the "caller" will be supplying the final semicolon,
267 so the macro body should not. The macro body cannot therefore
268 be a simple brace-enclosed compound statement, because syntax
269 errors would result if it were invoked (apparently as a single
270 statement, but with a resultant extra semicolon) as the if
271 branch of an if/else statement with an explicit else clause.
273 The traditional solution, therefore, is to use
275 #define MACRO(arg1, arg2) do { \
280 } while(0) /* (no trailing ; ) */
282 When the caller appends a semicolon, this expansion becomes a
283 single statement regardless of context. (An optimizing compiler
284 will remove any "dead" tests or branches on the constant
285 condition 0, although lint may complain.)
287 If all of the statements in the intended macro are simple
288 expressions, with no declarations or loops, another technique is
289 to write a single, parenthesized expression using one or more
290 comma operators. (For an example, see the first DEBUG() macro
291 in question 10.26.) This technique also allows a value to be
294 References: H&S Sec. 3.3.2 p. 45; CT&P Sec. 6.3 pp. 82-3.
298 Don't even write macros that expand to 0 statements - they can mess you
299 up as well. Use the doNothing macro instead.
301 #define doNothing() do { } while (0)
306 Use inline functions instead of macros if possible - they're a lot
307 less tricky to get right and don't suffer from the usual problems
308 of side effects, evaluation order, multiple evaluation, etc.
311 <li>Inline functions get the naming issue right. E.g. they
312 can have local variables which (in an expression context)
315 <li> Inline functions have call-by-value semantics whereas macros
316 are call-by-name. You can be bitten by duplicated computation
317 if you aren't careful.
320 However, note that macros can serve as both l-values and r-values and
321 can be "polymorphic" as these examples show:
323 // you can use this as an l-value or an l-value
324 #define PROF_INFO(cl) (((StgClosure*)(cl))->header.profInfo)
327 // but note that min(min(1,2),3) does 3 comparisions instead of 2!!
328 #define min(x,y) (((x)<=(y)) ? (x) : (y))
332 Inline functions should be "static inline" because:
335 gcc will delete static inlines if not used or theyre always inlined.
338 if they're externed, we could get conflicts between 2 copies of the
339 same function if, for some reason, gcc is unable to delete them.
340 If they're static, we still get multiple copies but at least they don't conflict.
343 OTOH, the gcc manual says this
344 so maybe we should use extern inline?
347 When a function is both inline and `static', if all calls to the
348 function are integrated into the caller, and the function's address is
349 never used, then the function's own assembler code is never referenced.
350 In this case, GNU CC does not actually output assembler code for the
351 function, unless you specify the option `-fkeep-inline-functions'.
352 Some calls cannot be integrated for various reasons (in particular,
353 calls that precede the function's definition cannot be integrated, and
354 neither can recursive calls within the definition). If there is a
355 nonintegrated call, then the function is compiled to assembler code as
356 usual. The function must also be compiled as usual if the program
357 refers to its address, because that can't be inlined.
359 When an inline function is not `static', then the compiler must
360 assume that there may be calls from other source files; since a global
361 symbol can be defined only once in any program, the function must not
362 be defined in the other source files, so the calls therein cannot be
363 integrated. Therefore, a non-`static' inline function is always
364 compiled on its own in the usual fashion.
366 If you specify both `inline' and `extern' in the function
367 definition, then the definition is used only for inlining. In no case
368 is the function compiled on its own, not even if you refer to its
369 address explicitly. Such an address becomes an external reference, as
370 if you had only declared the function, and had not defined it.
372 This combination of `inline' and `extern' has almost the effect of a
373 macro. The way to use it is to put a function definition in a header
374 file with these keywords, and put another copy of the definition
375 (lacking `inline' and `extern') in a library file. The definition in
376 the header file will cause most calls to the function to be inlined.
377 If any uses of the function remain, they will refer to the single copy
382 Try to use ANSI C's enum feature when defining lists of constants of the
383 same type. You'll notice that gdb works better when you do this.
387 typedef enum { /* N.B. Used as indexes into arrays */
399 # define NO_HEAP_PROFILING 0 /* N.B. Used as indexes into arrays */
400 # define HEAP_BY_CC 1
401 # define HEAP_BY_MOD 2
402 # define HEAP_BY_GRP 3
403 # define HEAP_BY_DESCR 4
404 # define HEAP_BY_TYPE 5
405 # define HEAP_BY_TIME 6
423 # define DESCRchar 'D'
424 # define TYPEchar 'Y'
425 # define TIMEchar 'T'
427 ToDo: at the time of writing, we still use the former.
430 Alastair likes to use stgCast instead of C syntax. He claims
431 it's easier to write and easier to grep for. YMMV.
433 #define stgCast(ty,e) ((ty)(e))
436 <li> We don't care too much about your indentation style but, if
437 you're modifying a function, please try to use the same style as the
438 rest of the function (or file).
442 Hugs related pieces of code often start with the line:
444 /* -*- mode: hugs-c; -*- */
446 which helps Emacs mimic the indentation style used by Mark P Jones
447 within Hugs. Add this to your .emacs file.
449 (defun hugs-c-mode ()
450 "C mode with adjusted defaults for use with Hugs (based on linux-c-mode)"
453 (setq c-basic-offset 4)
454 (setq indent-tabs-mode nil) ; don't use tabs to indent
455 (setq c-recognize-knr-r nil) ; no K&R here - don't pay the price
456 ; no: (setq tab-width 4)
458 (c-set-offset 'knr-argdecl-intro 0)
459 (c-set-offset 'case-label 0)
460 (c-set-offset 'statement-case-intro '++)
461 (c-set-offset 'statement-case-open '+)
472 Don't be tempted to reindent or reorganise large chunks of code - it
473 generates large diffs in which it's hard to see whether anything else
476 If you must reindent or reorganise, don't do anything else in that commit
477 and give advance warning that you're about to do it in case anyone else
478 is changing that file.