Changes between Version 9 and Version 10 of Commentary/Rts/Conventions


Ignore:
Timestamp:
Dec 12, 2012 8:21:54 AM (17 months ago)
Author:
simonmar
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/Rts/Conventions

    v9 v10  
    225225== Syntactic details == 
    226226 
     227 * Please keep to 80 columns: the line has to be drawn somewhere, and 
     228   by keeping it to 80 columns we can ensure that code looks OK on 
     229   everyone's screen.  Long lines are hard to read, and a sign that 
     230   the code needs to be restructured anyway. 
     231 
     232 * An indentation width of 4 is preferred (don't use actual tab characters, use spaces). 
     233 
    227234 * '''Important:''' Put "redundant" braces or parens in your code. 
    228235    Omitting braces and parens leads to very hard to spot bugs - 
     
    248255   Separating the declaration and initialization takes more lines, but 
    249256   make the code clearer. 
    250  
    251  * Use inline functions instead of macros if possible - they're a lot 
    252    less tricky to get right and don't suffer from the usual problems 
    253    of side effects, evaluation order, multiple evaluation, etc. 
    254  
    255  * Inline functions get the naming issue right.  E.g. they 
    256    can have local variables which (in an expression context) 
    257    macros can't. 
    258  
    259  * Inline functions have call-by-value semantics whereas macros are 
    260    call-by-name.  You can be bitten by duplicated computation if you 
    261    aren't careful. 
    262  
    263  * You can use inline functions from inside gdb if you compile with 
    264    -O0 or -fkeep-inline-functions.  If you use macros, you'd better know 
    265    what they expand to. 
    266  
    267   However, note that macros can serve as both l-values and r-values and 
    268   can be "polymorphic" as these examples show: 
    269 {{{ 
    270   // you can use this as an l-value or an r-value 
    271   #define PROF_INFO(cl) (((StgClosure*)(cl))->header.profInfo) 
    272  
    273   // polymorphic case 
    274   // but note that min(min(1,2),3) does 3 comparisons instead of 2! 
    275   #define min(x,y) (((x)<=(y)) ? (x) : (y)) 
    276 }}} 
    277  
    278  * Inline functions should be "static inline" because: 
    279  
    280  * gcc will delete static inlines if not used or theyre always inlined. 
    281  
    282  * if they're externed, we could get conflicts between 2 copies of the 
    283    same function if, for some reason, gcc is unable to delete them. 
    284    If they're static, we still get multiple copies but at least they 
    285    don't conflict. 
    286257 
    287258 * Don't define macros that expand to a list of statements.  You could 
     
    367338}}} 
    368339 
    369  * Please keep to 80 columns: the line has to be drawn somewhere, and 
    370    by keeping it to 80 columns we can ensure that code looks OK on 
    371    everyone's screen.  Long lines are hard to read, and a sign that 
    372    the code needs to be restructured anyway. 
    373  
    374340 * When commenting out large chunks of code, use {{{#ifdef 0 ... #endif}}}  
    375341   rather than {{{/* ... */}}} because C doesn't have 
     
    390356   or {{{'\0'}}}; the latter is much clearer. 
    391357 
    392  * We don't care too much about your indentation style but, if you're 
    393    modifying a function, please try to use the same style as the rest 
    394    of the function (or file).  If you're writing new code, an indentation width 
    395    of 4 is preferred (don't use actual tab characters, use spaces). 
    396  
    397358 * Please write comments in English.  Especially avoid Klingon. 
     359 
     360== Inline functions == 
     361 
     362Use inline functions instead of macros if possible - they're a lot 
     363less tricky to get right and don't suffer from the usual problems 
     364of side effects, evaluation order, multiple evaluation, etc. 
     365 
     366 * Inline functions get the naming issue right.  E.g. they 
     367   can have local variables which (in an expression context) 
     368   macros can't. 
     369 
     370 * Inline functions have call-by-value semantics whereas macros are 
     371   call-by-name.  You can be bitten by duplicated computation if you 
     372   aren't careful. 
     373 
     374 * You can use inline functions from inside gdb if you compile with 
     375   -O0 or -fkeep-inline-functions.  If you use macros, you'd better know 
     376   what they expand to. 
     377 
     378  However, note that macros can serve as both l-values and r-values and 
     379  can be "polymorphic" as these examples show: 
     380{{{ 
     381  // you can use this as an l-value or an r-value 
     382  #define PROF_INFO(cl) (((StgClosure*)(cl))->header.profInfo) 
     383 
     384  // polymorphic case 
     385  // but note that min(min(1,2),3) does 3 comparisons instead of 2! 
     386  #define min(x,y) (((x)<=(y)) ? (x) : (y)) 
     387}}} 
     388 
     389There are three macros to do inline portably.  Don't use `inline` directly, use these instead: 
     390 
     391`INLINE_HEADER` 
     392  An inline function in a header file.  This is just like a macro.  We never emit 
     393  a standalone copy of the function, so it ''must'' be inlined everywhere. 
     394 
     395`STATIC_INLINE` 
     396  An inline function in a C source file.  Again, it is always inlined, and we never 
     397  emit a standalone copy.  
     398 
     399`EXTERN_INLINE` 
     400  A function which is optionally inlined.  The C compiler is told to inline if possible, 
     401  but we also generated a standalone copy of the function just in case (see source:rts/Inlines.c). 
    398402 
    399403== Source-control issues == 
     
    403407   else was changed, and causes extra conflicts when moving patches to 
    404408   another branch. 
    405  
    406   If you must re-indent or re-organise, don't include any functional 
    407   changes that commit and give advance warning that you're about to do 
    408   it in case anyone else is changing that file. 
     409   [[BR]][[BR]] 
     410   If you must re-indent or re-organise, don't include any functional 
     411   changes that commit and give advance warning that you're about to do 
     412   it in case anyone else is changing that file.