HPC GAP debugging hints

There are certain GAP functions and global variables useful for the debugging purposes. Some of them may have disruptive behaviour, like e.g. DISABLE_GUARDS, not guaranteeing the consistent state of objects after their application, while the others may be quite safe to use at any stage.

• If either GAP code or a kernel primitive attempts to access an object that it is not allowed to access according to these semantics, either a "write guard error" (for a failed write access) or a "read guard error" (for a failed read access) will be raised. The global variable LastInaccessible will contain the object that caused such an error.
• First, check the region of the object with RegionOf(LastInaccessible).
• To inspect objects whose contents lie in other regions (and therefore cannot be displayed by PrintObj or ViewObj), the functions ViewShared and UNSAFE_VIEW can be used. ViewShared allows the inspection of objects in shared regions. It will try to lock the region and then call ViewObj(obj). If it cannot acquire a lock for the region, it will simply display the normal description of the object. UNSAFE_VIEW allows the inspection of any object in the system, regardless of whether the current thread has access to the region containing it. It should be used with care: If the object inspected is being modified by another thread concurrently, the resulting behaviour is undefined. Moreover, the function works by temporarily disabling read and write guards for regions, so other threads may corrupt memory rather than producing errors. It is generally safe to use if all threads but the current one are paused.
• MAKE_PUBLIC migrates the object to the public region.
• if this does not help, try to call DISABLE_GUARDS(1) or DISABLE_GUARDS(2)
• If you still can't see the object, at least call TYPE_OBJ, this may give some clue
• Another useful utility is FindAllGVarsHolding(obj).
• If GAP was compiled with make debug or make gapdebug, then CREATOR_OF(obj) will tell which function(s) constructed the object obj (first is the function which created the object, second is the function which called the first; maybe longer call stack will be available in the future). To find names of these functions, use NAME_FUNC. Note that GAP will work approximately three times slower in the debug mode. Also, remember that some changes may require you to recompile from scratch using make distclean first.
• To inspect the content of atomic component objects, you may use FromAtomicComObj which will return a record containing all components of such an object.
• HPC-GAP has a multi-threaded user interface to assist with the development and debugging of concurrent programs. This user interface is enabled by default; to disable it, and use the single-threaded interface, GAP has to be started with the -S option.
• There is a reference implementation of tasks available. It is enabled by setting the environment variable GAP_STDTASKS=1 before starting GAP. If something does not work, try to see if the problem persists using the reference implementation.

If you are running tests using Test, the following two options are very useful:

• Test("tst/grpperm.tst",rec(compareFunction:="uptowhitespace")); to compare result only up to whitespaces
• Test("tst/grpperm.tst",rec(compareFunction:="uptowhitespace", showProgress:= true)); to show also the progress of calculations.