regina/HACKERS.txt

   1 Hello hackers and helpers,
   2
   3 This is a small guide to those of you who want to make Regina a better
   4 program.
   5
   6 contents:
   7    1) You want to debug but you can't set breakpoints on functions
   8    2) You want to make a bug fix
   9    3) You have done a bug fix
  10    4) You have added a function which is exported from the library
  11    5) You have added a global function or variable
  12    6) Your code uses global variables or static variables
  13    7) You want to port the multi-threading code
  14    8) The code don't work as expected in a multi-threading environment
  15    9) Never use exit()
  16
  17
  18 1) You want to debug but you can't set breakpoints on functions
  19    Add the prefix "__regina_" to the function name. The file wrappers.h
  20    wraps global function names to prevent a conflict with user defined
  21    names. You should add an entry in this file if you want to add a global
  22    function or variable.
  23
  24 2) You want to make a bug fix
  25    Great! Do the fix, make a diff (next point) and give a small
  26    description and an example, e.g.:
  27    >  function DATE has had an Y3K error and will work now:
  28    >  /* this has given "22 Nov 3001" instead of "22 Dec 3001" */
  29    >  say date(N,30011222,S)
  30    This is an example, regina is year 3000 save :-)
  31
  32    If you want to edit:
  33    Don't use the tabulator or let the tab key expand to blanks.
  34    If a tabulator key is a must the ONLY indention levels are
  35    at 1, 9, 17, ... (every 8)
  36
  37 3) You have done a bug fix
  38    The best way to say what you have done is to use diff. diff is
  39    a program with many parameters. Try
  40    >  diff -u former_file corrected_file
  41    and send the output to Mark.
  42
  43 4) You have added a function which is exported from the library
  44    This should happen very seldom since the functions names are
  45    restricted by the REXX standard.
  46    Add a line
  47    > GLOBAL_ENTRY_POINT();
  48    at the very start of the code of the function.
  49
  50 5) You have added a global function or variable
  51    Read 1)
  52
  53 6) Your code uses global variables or static variables
  54    This may lead to problems in the multi-threading environment.
  55    There are constant values which are harmless:
  56    > const char REXX_VERSION[] = "Regina 2000";
  57    Changing variables are a problem:
  58    > extern int trace_flag;
  59    Such a variable will change its value due execution. You can
  60    do now three things:
  61    1) be SURE that this is not a problem and the variable is
  62       global and of the same value in all threads.
  63    2) move it to the thread-specific variables if this will
  64       match the sense. Think on an execution time counter
  65       for an example.
  66    3) protect the variable. A typical example is the usage
  67       of external or generated code like the parser. It
  68       uses its own values. You may change bison/flex or
  69       wait until the maintainer changes the code or you
  70       surround the access of the code or variable by a
  71       THREAD_PROTECT
  72       THREAD_UNPROTECT
  73       pair. Note the missing semicolon. You must be sure
  74       not to call another function which uses a
  75       THREAD_PROTECT/UNPROTECT pair. This may lead to a
  76       deadlock.
  77       Also note that you can't span the protection calls
  78       over two functions. You may use a helper function
  79       instead or you may save the results in a separate
  80       temporary variable. Thus, some typical code looks
  81       like:
  82       > unsigned char MyToupper(unsigned char c)
  83       > {
  84       >    static int first = 1;
  85       >    static unsigned char ExtendedTranslateSet[256];
  86       >    THREAD_PROTECT
  87       >    if (first)
  88       >       {
  89       >          first = 0;
  90       >          AskOSforInitializeUppercase(ExtendedTranslateSet);
  91       >       }
  92       >    THREAD_UNPROTECT
  93       >    return(ExtendedTranslateSet[c]);
  94       > }
  95       A better solution IN THIS CASE may be this:
  96       Let ExtendedTranslateSet be a global variable and call
  97       "AskOSforInitializeUppercase(ExtendedTranslateSet);" in
  98       the function "ReginaInitializeProcess()".
  99    Don't forget to wrap the variable name by a "__regina_".
 100
 101 7) You want to port the multi-threading code
 102    Your code is highly welcome. Please, drop Mark an email
 103    first. There might be somebody in the outer space who has the
 104    same idea.
 105    You have to build only some few functions and defines.
 106    Have a look at mt_posix.* or mt_win32.*. You have to
 107    incorporate your changes into the correct makefile and
 108    into mt.h.
 109
 110 8) The code don't work as expected in a multi-threading environment
 111    Regina don't share variables between threads. You must set/read/destroy
 112    variables exactly in that thread which uses it. Two variables with
 113    the same name are different in different threads.
 114
 115 9) Never use exit(), use TSD->MTExit().