GAP can use several garbage collectors
(GASMAN, the Julia garbage collector, and the Boehm garbage collector).
Up to now, the GAP documentation mentions only GASMAN.
Several GAP functions make sense only if GASMAN is running,
and several command line options make sense only in this case.
The proposed changes try to adjust the documentation to situations
where GASMAN is not used.
(More changes in this direction will be needed,
below is a list of open questions.)
Details of the changes:
----------------------
- In `debug.xml`, section "Global Memory Information",
moved the introductory part to a new subsection "Garbage Collection"
that can be cross-referenced from places where garbage collection
is mentioned;
mention in this subsection that several garbage collectors
can be used by GAP.
- In the functions `GasmanStatistics, `GasmanMessageStatus`,
`GasmanLimits`, mention that they work only if GASMAN is running.
- In `run.xml`, section "Saving and Loading a Workspace",
mention that workspaces can be saved/loaded only if GASMAN is running.
- Added a cross-reference from `SaveOnExitFile` to `SaveWorkspace`.
- Changed the description of GAP's command line options:
- In `run.xml`, mention that the options `-g`, `-L`, `-o`, `-s`
are available only if GASMAN is used.
- Do the same in `system.g`, variable `GAPInfo.CommandLineOptionData`.
(I had thought about omitting the not supported options from the
list, but such a filtered list might confuse users who want to
understand why their options did not work as expected.)
- Call `GASMAN( "message" )` in `SetGasmanMessageStatus`
only if GASMAN is running, in order to avoid an error message.
- In chapter "Weak Pointers", removed the word GASMAN in the introduction
and added a reference to "Garbage Collection".
(Weak pointer objects work also with other garbage collectors than
GASMAN.)
Open questions:
--------------
- The command line options `-K` and `-m` are evaluated also when the
Julia GC is running, but are their values really used?
- The introduction of the section "Command Line Options" refers to a file
https://www.gap-system.org/Download/INSTALL which exists but seems to
be outdated --which URL should be given here?
(The corresponding file in the GAP distribution is `INSTALL.md`.)
- If GASMAN is not running, a file given with the `-L` command line option
is currently ignored, because `LoadWorkspace` is not called when
`GAP_ENABLE_SAVELOAD` is not defined.
Should we better show an error message telling that no workspace
could be loaded?
(In earlier versions, there was such a message.)
- The function `GASMAN` is undocumented.
(The Development manual contains a section "Garbage collection in GAP",
where GASMAN is said to be "the GAP memory manager".
This seems to be the right place to add documentation for alternative
garbage collectors.
On the other hand, this manual is not part of the GAP distribution.)
Calling `GASMAN( "collect" )` and `GASMAN( "partial" )` work also
with the Julia GC; if this is intentional then we should choose
a better name for the function.
(`GASMAN( "message" )` works only with the GASMAN GC.)
The function `GASMAN` is shown in manual examples about weak pointer
objects. Thus a function for forcing a garbage collection should be
documented.
- The section "The GASMAN Interface for Weak Pointer Objects"
in chapter "Weak Pointers" looks GASMAN specific (not only the title).
How to reformulate it?