The GHC Commentary - Style Guidelines for RTS C code

From 82af8c0af70a1f72d5c364d35d04eef17d88395d Mon Sep 17 00:00:00 2001 From: Simon Marlow Date: Wed, 6 Sep 2006 10:40:22 +0000 Subject: [PATCH] Now in the wiki --- docs/comm/index.html | 2 +- docs/comm/rts-libs/coding-style.html | 516 ---------------------------------- 2 files changed, 1 insertion(+), 517 deletions(-) delete mode 100644 docs/comm/rts-libs/coding-style.html diff --git a/docs/comm/index.html b/docs/comm/index.html index 5ccd5f0..294ba09 100644 --- a/docs/comm/index.html +++ b/docs/comm/index.html @@ -82,7 +82,7 @@

RTS & Libraries

Coding Style Guidelines +
Coding Style Guidelines
Spineless Tagless C
Primitives
Prelude Foundations diff --git a/docs/comm/rts-libs/coding-style.html b/docs/comm/rts-libs/coding-style.html deleted file mode 100644 index 58f5b4f..0000000 --- a/docs/comm/rts-libs/coding-style.html +++ /dev/null @@ -1,516 +0,0 @@ - - - - - The GHC Commentary - Style Guidelines for RTS C code - - - -
The GHC Commentary - Style Guidelines for RTS C code
- -
Comments
- -
These coding style guidelines are mainly intended for use in -ghc/rts and ghc/includes. - -
NB These are just suggestions. They're not set in stone. Some of -them are probably misguided. If you disagree with them, feel free to -modify this document (and make your commit message reasonably -informative) or mail someone (eg. The GHC mailing list) - -
References
- -If you haven't read them already, you might like to check the following. -Where they conflict with our suggestions, they're probably right. - -
- -The C99 standard. One reasonable reference is here. - -
- -Writing Solid Code, Microsoft Press. (Highly recommended. Possibly -the only Microsoft Press book that's worth reading.) - -
- -Autoconf documentation. -See also The autoconf macro archive and -Cyclic Software's description - -
- Indian -Hill C Style and Coding Standards. - -
- -A list of C programming style links - -
- -A very large list of C programming links - -
- -A list of Unix programming links - -
- - -
Portability issues
- -
- We try to stick to C99 where possible. We use the following -C99 features relative to C89, some of which were previously GCC -extensions (possibly with different syntax): - -
  - Variable length arrays as the last field of a struct. GCC has -a similar extension, but the syntax is slightly different: in GCC you -would declare the array as arr[0], whereas in C99 it is -declared as arr[]. - -
  - Inline annotations on functions (see later) - -
  - Labeled elements in initialisers. Again, GCC has a slightly -different syntax from C99 here, and we stick with the GCC syntax until -GCC implements the C99 proposal. - -
  - C++-style comments. These are part of the C99 standard, and we -prefer to use them whenever possible. -
  - -
  In addition we use ANSI-C-style function declarations and -prototypes exclusively. Every function should have a prototype; -static function prototypes may be placed near the top of the file in -which they are declared, and external prototypes are usually placed in -a header file with the same basename as the source file (although there -are exceptions to this rule, particularly when several source files -together implement a subsystem which is described by a single external -header file). - -
- We use the following GCC extensions, but surround them with -#ifdef __GNUC__: - -
  - Function attributes (mostly just no_return and -unused) -
  - Inline assembly. -
  - -
- -char can be signed or unsigned - always say which you mean - -
- Our POSIX policy: try to write code that only uses POSIX (IEEE -Std 1003.1) interfaces and APIs. We used to define -POSIX_SOURCE by default, but found that this caused more -problems than it solved, so now we require any code that is -POSIX-compliant to explicitly say so by having #include -"PosixSource.h" at the top. Try to do this whenever possible. - -
- Some architectures have memory alignment constraints. Others -don't have any constraints but go faster if you align things. These -macros (from ghcconfig.h) tell you which alignment to use - -
```
-  /* minimum alignment of unsigned int */
-  #define ALIGNMENT_UNSIGNED_INT 4
-
-  /* minimum alignment of long */
-  #define ALIGNMENT_LONG 4
-
-  /* minimum alignment of float */
-  #define ALIGNMENT_FLOAT 4
-
-  /* minimum alignment of double */
-  #define ALIGNMENT_DOUBLE 4
-
```
  - -
- Use StgInt, StgWord and StgPtr when -reading/writing ints and ptrs to the stack or heap. Note that, by -definition, StgInt, StgWord and StgPtr are -the same size and have the same alignment constraints even if -sizeof(int) != sizeof(ptr) on that platform. - -
- Use StgInt8, StgInt16, etc when you need a -certain minimum number of bits in a type. Use int and -nat when there's no particular constraint. ANSI C only -guarantees that ints are at least 16 bits but within GHC we assume -they are 32 bits. - -
- Use StgFloat and StgDouble for floating -point values which will go on/have come from the stack or heap. Note -that StgDouble may occupy more than one StgWord, but -it will always be a whole number multiple. - -
  -Use PK_FLT(addr), PK_DBL(addr) to read -StgFloat and StgDouble values from the stack/heap, -and ASSIGN_FLT(val,addr) / -ASSIGN_DBL(val,addr) to assign StgFloat/StgDouble values -to heap/stack locations. These macros take care of alignment -restrictions. - -
  -Heap/Stack locations are always StgWord aligned; the -alignment requirements of an StgDouble may be more than that -of StgWord, but we don't pad misaligned StgDoubles -because doing so would be too much hassle (see PK_DBL & -co above). - -
- -Avoid conditional code like this: - -
```
-  #ifdef solaris_host_OS
-  // do something solaris specific
-  #endif
-
```
  - -Instead, add an appropriate test to the configure.ac script and use -the result of that test instead. - -
```
-  #ifdef HAVE_BSD_H
-  // use a BSD library
-  #endif
-
```
  - -
  The problem is that things change from one version of an OS to another -- things get added, things get deleted, things get broken, some things -are optional extras. Using "feature tests" instead of "system tests" -makes things a lot less brittle. Things also tend to get documented -better. - -
- -
Debugging/robustness tricks
- - -Anyone who has tried to debug a garbage collector or code generator -will tell you: "If a program is going to crash, it should crash as -soon, as noisily and as often as possible." There's nothing worse -than trying to find a bug which only shows up when running GHC on -itself and doesn't manifest itself until 10 seconds after the actual -cause of the problem. - -
We put all our debugging code inside #ifdef DEBUG. The -general policy is we don't ship code with debugging checks and -assertions in it, but we do run with those checks in place when -developing and testing. Anything inside #ifdef DEBUG should -not slow down the code by more than a factor of 2. - -
We also have more expensive "sanity checking" code for hardcore -debugging - this can slow down the code by a large factor, but is only -enabled on demand by a command-line flag. General sanity checking in -the RTS is currently enabled with the -DS RTS flag. - -
There are a number of RTS flags which control debugging output and -sanity checking in various parts of the system when DEBUG is -defined. For example, to get the scheduler to be verbose about what -it is doing, you would say +RTS -Ds -RTS. See -includes/RtsFlags.h and rts/RtsFlags.c for the full -set of debugging flags. To check one of these flags in the code, -write: - -
```
-  IF_DEBUG(gc, fprintf(stderr, "..."));
-
```
- -would check the gc flag before generating the output (and the -code is removed altogether if DEBUG is not defined). - -
All debugging output should go to stderr. - -
-Particular guidelines for writing robust code: - -
- -Use assertions. Use lots of assertions. If you write a comment -that says "takes a +ve number" add an assertion. If you're casting -an int to a nat, add an assertion. If you're casting an int to a char, -add an assertion. We use the ASSERT macro for writing -assertions; it goes away when DEBUG is not defined. - -
- -Write special debugging code to check the integrity of your data structures. -(Most of the runtime checking code is in rts/Sanity.c) -Add extra assertions which call this code at the start and end of any -code that operates on your data structures. - -
- -When you find a hard-to-spot bug, try to think of some assertions, -sanity checks or whatever that would have made the bug easier to find. - -
- -When defining an enumeration, it's a good idea not to use 0 for normal -values. Instead, make 0 raise an internal error. The idea here is to -make it easier to detect pointer-related errors on the assumption that -random pointers are more likely to point to a 0 than to anything else. - -
```
-typedef enum
-    { i_INTERNAL_ERROR  /* Instruction 0 raises an internal error */
-    , i_PANIC           /* irrefutable pattern match failed! */
-    , i_ERROR           /* user level error */
-
-    ...
-
```
  - -
- Use #warning or #error whenever you write a -piece of incomplete/broken code. - -
- When testing, try to make infrequent things happen often. - For example, make a context switch/gc/etc happen every time a - context switch/gc/etc can happen. The system will run like a - pig but it'll catch a lot of bugs. - -
- -
Syntactic details
- -
- Important: Put "redundant" braces or parens in your code. -Omitting braces and parens leads to very hard to spot bugs - -especially if you use macros (and you might have noticed that GHC does -this a lot!) - -
  -In particular: -
  - -Put braces round the body of for loops, while loops, if statements, etc. -even if they "aren't needed" because it's really hard to find the resulting -bug if you mess up. Indent them any way you like but put them in there! -
  - -
- -When defining a macro, always put parens round args - just in case. -For example, write: -
```
-  #define add(x,y) ((x)+(y))
-
```
  -instead of -
```
-  #define add(x,y) x+y
-
```
  - -
- Don't declare and initialize variables at the same time. -Separating the declaration and initialization takes more lines, but -make the code clearer. - -
- -Use inline functions instead of macros if possible - they're a lot -less tricky to get right and don't suffer from the usual problems -of side effects, evaluation order, multiple evaluation, etc. - -
  - Inline functions get the naming issue right. E.g. they - can have local variables which (in an expression context) - macros can't. - -
  - Inline functions have call-by-value semantics whereas macros - are call-by-name. You can be bitten by duplicated computation - if you aren't careful. - -
  - You can use inline functions from inside gdb if you compile with - -O0 or -fkeep-inline-functions. If you use macros, you'd better - know what they expand to. -
  - -However, note that macros can serve as both l-values and r-values and -can be "polymorphic" as these examples show: -
```
-  // you can use this as an l-value or an l-value
-  #define PROF_INFO(cl) (((StgClosure*)(cl))->header.profInfo)
-
-  // polymorphic case
-  // but note that min(min(1,2),3) does 3 comparisions instead of 2!!
-  #define min(x,y) (((x)<=(y)) ? (x) : (y))
-
```
  - -
- -Inline functions should be "static inline" because: -
  - -gcc will delete static inlines if not used or theyre always inlined. - -
  - - if they're externed, we could get conflicts between 2 copies of the - same function if, for some reason, gcc is unable to delete them. - If they're static, we still get multiple copies but at least they don't conflict. -
  - -OTOH, the gcc manual says this -so maybe we should use extern inline? - -
```
-   When a function is both inline and `static', if all calls to the
-function are integrated into the caller, and the function's address is
-never used, then the function's own assembler code is never referenced.
-In this case, GNU CC does not actually output assembler code for the
-function, unless you specify the option `-fkeep-inline-functions'.
-Some calls cannot be integrated for various reasons (in particular,
-calls that precede the function's definition cannot be integrated, and
-neither can recursive calls within the definition).  If there is a
-nonintegrated call, then the function is compiled to assembler code as
-usual.  The function must also be compiled as usual if the program
-refers to its address, because that can't be inlined.
-
-   When an inline function is not `static', then the compiler must
-assume that there may be calls from other source files; since a global
-symbol can be defined only once in any program, the function must not
-be defined in the other source files, so the calls therein cannot be
-integrated.  Therefore, a non-`static' inline function is always
-compiled on its own in the usual fashion.
-
-   If you specify both `inline' and `extern' in the function
-definition, then the definition is used only for inlining.  In no case
-is the function compiled on its own, not even if you refer to its
-address explicitly.  Such an address becomes an external reference, as
-if you had only declared the function, and had not defined it.
-
-   This combination of `inline' and `extern' has almost the effect of a
-macro.  The way to use it is to put a function definition in a header
-file with these keywords, and put another copy of the definition
-(lacking `inline' and `extern') in a library file.  The definition in
-the header file will cause most calls to the function to be inlined.
-If any uses of the function remain, they will refer to the single copy
-in the library.
-
```
  - -
- -Don't define macros that expand to a list of statements. -You could just use braces as in: - -
```
-  #define ASSIGN_CC_ID(ccID)              \
-        {                                 \
-        ccID = CC_ID;                     \
-        CC_ID++;                          \
-        }
-
```
  - -(but it's usually better to use an inline function instead - see above). - -
- -Don't even write macros that expand to 0 statements - they can mess you -up as well. Use the doNothing macro instead. -
```
-  #define doNothing() do { } while (0)
-
```
  - -
- -This code -
```
-int* p, q;
-
```
  -looks like it declares two pointers but, in fact, only p is a pointer. -It's safer to write this: -
```
-int* p;
-int* q;
-
```
  -You could also write this: -
```
-int *p, *q;
-
```
  -but it is preferrable to split the declarations. - -
- -Try to use ANSI C's enum feature when defining lists of constants of -the same type. Among other benefits, you'll notice that gdb uses the -name instead of its (usually inscrutable) number when printing values -with enum types and gdb will let you use the name in expressions you -type. - -
  -Examples: -
```
-    typedef enum { /* N.B. Used as indexes into arrays */
-     NO_HEAP_PROFILING,		
-     HEAP_BY_CC,		
-     HEAP_BY_MOD,		
-     HEAP_BY_GRP,		
-     HEAP_BY_DESCR,		
-     HEAP_BY_TYPE,		
-     HEAP_BY_TIME		
-    } ProfilingFlags;
-
```
  -instead of -
```
-    # define NO_HEAP_PROFILING	0	/* N.B. Used as indexes into arrays */
-    # define HEAP_BY_CC		1
-    # define HEAP_BY_MOD	2
-    # define HEAP_BY_GRP	3
-    # define HEAP_BY_DESCR	4
-    # define HEAP_BY_TYPE	5
-    # define HEAP_BY_TIME	6
-
```
  -and -
```
-    typedef enum {
-     CCchar    = 'C',
-     MODchar   = 'M',
-     GRPchar   = 'G',
-     DESCRchar = 'D',
-     TYPEchar  = 'Y',
-     TIMEchar  = 'T'
-    } ProfilingTag;
-
```
  -instead of -
```
-    # define CCchar    'C'
-    # define MODchar   'M'
-    # define GRPchar   'G'
-    # define DESCRchar 'D'
-    # define TYPEchar  'Y'
-    # define TIMEchar  'T'
-
```
  - -
- Please keep to 80 columns: the line has to be drawn somewhere, -and by keeping it to 80 columns we can ensure that code looks OK on -everyone's screen. Long lines are hard to read, and a sign that the -code needs to be restructured anyway. - -
- When commenting out large chunks of code, use #ifdef 0 -... #endif rather than /* ... */ because C doesn't -have nested comments. - -
- When declaring a typedef for a struct, give the struct a name -as well, so that other headers can forward-reference the struct name -and it becomes possible to have opaque pointers to the struct. Our -convention is to name the struct the same as the typedef, but add a -leading underscore. For example: - -
```
-  typedef struct _Foo {
-    ...
-  } Foo;
-
```
  - -
- Do not use ! instead of explicit comparison against -NULL or '\0'; the latter is much clearer. - -
- We don't care too much about your indentation style but, if -you're modifying a function, please try to use the same style as the -rest of the function (or file). If you're writing new code, a -tab width of 4 is preferred. - -
- -
CVS issues
- -
- -Don't be tempted to reindent or reorganise large chunks of code - it -generates large diffs in which it's hard to see whether anything else -was changed. -
  -If you must reindent or reorganise, don't include any functional -changes that commit and give advance warning that you're about to do -it in case anyone else is changing that file. -
- - - - -- 1.7.10.4

RTS & Libraries

The GHC Commentary - Style Guidelines for RTS C code

Comments

References

Portability issues

Debugging/robustness tricks

Syntactic details

CVS issues