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


Ignore:
Timestamp:
Dec 12, 2012 8:21:54 AM (3 years 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.