| 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(). |