HACKERS.txt

Hello hackers and helpers,

This is a small guide to those of you who want to make Regina a better
program.

contents:
   1) You want to debug but you can't set breakpoints on functions
   2) You want to make a bug fix
   3) You have done a bug fix
   4) You have added a function which is exported from the library
   5) You have added a global function or variable
   6) Your code uses global variables or static variables
   7) You want to port the multi-threading code
   8) The code don't work as expected in a multi-threading environment
   9) Never use exit()


1) You want to debug but you can't set breakpoints on functions
   Add the prefix "__regina_" to the function name. The file wrappers.h
   wraps global function names to prevent a conflict with user defined
   names. You should add an entry in this file if you want to add a global
   function or variable.

2) You want to make a bug fix
   Great! Do the fix, make a diff (next point) and give a small
   description and an example, e.g.:
   >  function DATE has had an Y3K error and will work now:
   >  /* this has given "22 Nov 3001" instead of "22 Dec 3001" */
   >  say date(N,30011222,S)
   This is an example, regina is year 3000 save :-)

   If you want to edit:
   Don't use the tabulator or let the tab key expand to blanks.
   If a tabulator key is a must the ONLY indention levels are
   at 1, 9, 17, ... (every 8)

3) You have done a bug fix
   The best way to say what you have done is to use diff. diff is
   a program with many parameters. Try
   >  diff -u former_file corrected_file
   and send the output to Mark.

4) You have added a function which is exported from the library
   This should happen very seldom since the functions names are
   restricted by the REXX standard.
   Add a line
   > GLOBAL_ENTRY_POINT();
   at the very start of the code of the function.

5) You have added a global function or variable
   Read 1)

6) Your code uses global variables or static variables
   This may lead to problems in the multi-threading environment.
   There are constant values which are harmless:
   > const char REXX_VERSION[] = "Regina 2000";
   Changing variables are a problem:
   > extern int trace_flag;
   Such a variable will change its value due execution. You can
   do now three things:
   1) be SURE that this is not a problem and the variable is
      global and of the same value in all threads.
   2) move it to the thread-specific variables if this will
      match the sense. Think on an execution time counter
      for an example.
   3) protect the variable. A typical example is the usage
      of external or generated code like the parser. It
      uses its own values. You may change bison/flex or
      wait until the maintainer changes the code or you
      surround the access of the code or variable by a
      THREAD_PROTECT
      THREAD_UNPROTECT
      pair. Note the missing semicolon. You must be sure
      not to call another function which uses a
      THREAD_PROTECT/UNPROTECT pair. This may lead to a
      deadlock.
      Also note that you can't span the protection calls
      over two functions. You may use a helper function
      instead or you may save the results in a separate
      temporary variable. Thus, some typical code looks
      like:
      > unsigned char MyToupper(unsigned char c)
      > {
      >    static int first = 1;
      >    static unsigned char ExtendedTranslateSet[256];
      >    THREAD_PROTECT
      >    if (first)
      >       {
      >          first = 0;
      >          AskOSforInitializeUppercase(ExtendedTranslateSet);
      >       }
      >    THREAD_UNPROTECT
      >    return(ExtendedTranslateSet[c]);
      > }
      A better solution IN THIS CASE may be this:
      Let ExtendedTranslateSet be a global variable and call
      "AskOSforInitializeUppercase(ExtendedTranslateSet);" in
      the function "ReginaInitializeProcess()".
   Don't forget to wrap the variable name by a "__regina_".

7) You want to port the multi-threading code
   Your code is highly welcome. Please, drop Mark an email
   first. There might be somebody in the outer space who has the
   same idea.
   You have to build only some few functions and defines.
   Have a look at mt_posix.* or mt_win32.*. You have to
   incorporate your changes into the correct makefile and
   into mt.h.

8) The code don't work as expected in a multi-threading environment
   Regina don't share variables between threads. You must set/read/destroy
   variables exactly in that thread which uses it. Two variables with
   the same name are different in different threads.

9) Never use exit(), use TSD->MTExit().