6.1. Introduction to Rigging

It is not necessary to compile a MAINSAIL MODULE with any special compiler options in order to use rigging. In fact, it is not even necessary to compile the MODULE debuggable, although that is desirable in order to obtain as much information as possible about where a dangling reference occurred.

6.2. $startRigging and $stopRigging

PROCEDURE $startRigging (OPTIONAL INTEGER whatToRig);

whatToRig is interpreted as follows:

• whatToRig = pointerCode: rig POINTERs
• whatToRig = stringCode: rig STRINGs
• whatToRig = 0 (unspecified): rig both

After a call to $startRigging, whenever a dynamic object is disposed or an area is cleared or disposed, all POINTERs and STRINGs that point to the reclaimed memory are rigged. However, POINTERs or STRINGs that were already dangling at the time of the call to $startRigging are not rigged.

To stop rigging, call $stopRigging:

PROCEDURE $stopRigging (OPTIONAL INTEGER whatNotToRig);

After a call to $stopRigging with no arguments, MAINSAIL no longer does anything special when dynamic objects are disposed or areas are cleared or disposed. POINTERs and STRINGs that have already been rigged remain rigged. If the argument is pointerCode, only POINTERs stop being rigged; if stringCode, only STRINGs.

You can also control rigging interactively by issuing the following MAINEX subcommands:

The potential for vastly increased execution time is the reason why POINTERs and STRINGs are not rigged by default (except on SUPERCHECK platforms, where rigging incurs a smaller execution time penalty; see Chapter 18 of the MAINSAIL Language Manual).

Because dangling POINTER and STRING bugs in large programs are very difficult to track, it can sometimes be worth the extra execution time to enable rigging when you suspect that a bug in your program is caused by a dangling POINTER or STRING. If you suspect such a bug, either modify your program to call $startRigging when it begins executing, or issue the MAINEX subcommands RIGPTRS and/or RIGSTRS, or, from the debugger, issue the command XS $startRigging. Then run your program from the debugger. Your program's runtime may be much longer than normal, but the amount of time you spend may be small compared to the time it would take to track down the bug without rigging.

To reduce the penalty in runtime that you pay for rigging, you may want to start rigging at some point later than the very beginning of your program's execution. If you are sure that no POINTER or STRING that will later be used becomes dangling before a certain point in the program, set a breakpoint there, and enable rigging only when the breakpoint is reached.

6.4. What Happens When a Rigged POINTER or STRING Is Used

The bit patterns MAINSAIL uses by default are (currently the same on all platforms, although this may change):

You can change the values of the bit patterns used at runtime; see below. The values currently used are available through the system variables $riggedAdrBits and $riggedCharadrBits.

Thus, for example, if rigging POINTERs is enabled, and you get a bus error and enter the debugger and find yourself sitting on a statement like:

p.f := q.f

you can issue the debugger command:

v p,q

If the output is something like:

p = 'H16B408:P
q = 'HFFFFBEEF:P

then you can assume that q is a dangling POINTER.

If you suspect a dangling STRING instead of a POINTER, you can use the debugger to inspect the CHARADR part of a STRING s's STRING descriptor with:

v cvc(s)

If you are lucky enough to get an error message that lists the address of the MAINSAIL chunk containing a dangling POINTER or STRING, you can do something like:

.v cvp('H14ABC20L)

(assuming 'H14ABC20L is the chunk address of a dangling POINTER as reported in the error message); one of the fields or elements of the chunk should have the rigged bit pattern as its value, and this is the dangling POINTER or STRING.

6.5. Changing the Default Bit Patterns for Rigged POINTERs and STRINGs

> riggingPtrBadAddr 'HBBBBBEEF<eol>
> riggingStrBadChar 'HBBBBEEEE<eol>

Both of these subcommands take a LONG BITS argument (from which the trailing L may be omitted), which is the bit pattern to use for subsequently rigged POINTERs and STRINGs. These subcommands set the system variables $riggedAdrBits and $riggedCharadrBits, respectively. The subcommands may be set in the site.cmd file on your MAINSAIL directory if you wish to specify a default more appropriate to your site than the one MAINSAIL is shipped with.

With no argument, each of these subcommands shows the current value of the corresponding bit pattern.

If you need to figure out which addresses are valid and invalid on your system, you can try running a program like the one in Figure 6–1, which works on machines with 32-bit addresses. It checks every address on a 64-Kbyte boundary to see whether or not loading from it causes an exception. It prints out a message whenever the validity of the address it just tried is different from that of the previous address it tried. Of course, it determines only which addresses are valid in the current process's address space; other executions of MAINSAIL on the same machine may produce different results.

+W:N cvlb(cva(myPtr)) = $riggedAdrBits

or:

+W:N cvlb(cvc(myStr)) = $riggedCharadrBits

These commands allow you to watch an expression and break when that expression's value changes. The debugger will break on the first debuggable PROCEDURE call after the POINTER or STRING changes to the rigged value. Once you reach this point, where the object or STRING text has just been disposed, examine and record the count value. Then run the program again, setting the count break to one less than the recorded count value. You can then single step, checking for the rigged value at each statement to determine which statement is incorrectly freeing memory.

6.6.1. Debugger's +W:C Command and POINTER Rigging

Use +W:N cvlb(cva(p)) = $riggedAdrBits, as shown above, to break when p becomes dangling.

Similar considerations apply to STRINGs that become dangling.