Running Larceny

Contents

0. Summary (Overall behavior)
1. Quick summary (precise GC)
2. Quick summary (conservative GC)
3. Command line format overview
4. Heap allocation options (precise GC)
5. GC policy options (precise GC)
6. GC policy options (conservative gc)
7. General options
8. Developers' options
9. Startup file
10. Reorganizing a heap image

0. Summary (Overall behavior)

Larceny can be started in two distinct ways. Those users who use Larceny only for Scheme programming will usually install it as described in the introduction and will run it via the standard shell script by typing larceny at the shell prompt.

Those users who change Twobit and Larceny, on the other hand, will also run the shell script -- and also the twobit script -- but will sometimes need to run a newly-compiled program or newly-built heap without installing it first. In that case, the binary 'larceny.bin' will be run directly, as described below.

The command line options in this section apply to both the shell scripts and the binary program. However, a heap file name may not be supplied to the shell scripts, and the option -small (described in the introduction) is not accepted by the binary program or by the twobit script.

1. Summary (precise gc)

Larceny is most easily run from the command line with the following command: 
     larceny.bin heap-filename
That command will run Larceny with the default configuration. (You can also omit the heap-filename, which then defaults to the file sparc.heap in the current directory.) The default configuration is:

2. Summary (conservative GC)

Larceny with the conservative collector is run from the command line with the following command: 
     bdwlarceny.bin heap-filename
That command will run Larceny with the default configuration. (You can also omit the heap-filename, which then defaults to the file larceny.heap in the current directory.) The default configuration is: Note: It is beneficial to run the conservative collector with a split heap image, that is, a heap image where the code vectors and the other data are separated. Using such a heap image reduces the risk of accidental storage retention, although it is at the present time unclear whether the practical benefits are measurable (in Larceny, at least). The heap image created by the development system is not split, but you can create such a heap image with Larceny. Click here to learn more.

3. Command line format overview

Larceny accepts a number of command line options to control its configuration and behavior. The summary of the command line format is as follows: 
     larceny.bin [ option ... ] [ heap-filename ] [ -args argument ... ]
where each option is described in this document; see the contents for a topic listing. If the switch -args is present, then the arguments following that switch are made available to Scheme code running in Larceny as a vector of strings; see the description of the command-line-arguments procedure.

Option arguments: where an argument size is indicated, a nonnegative integer is expected, optionally followed immediately by the letter "K" (Kilo) or "M" (Mega); e.g. a size of 512K means 524288 8-bit bytes. Where an argument n is indicated, a nonnegative integer is expected.

4. Heap allocation options (precise GC)

-gen
Select the generational garbage collector with the default number of collected areas (3). An area is akin to a generation except that some areas (notably, the non-predictive dynamic area) have multiple generations.

-areas n
Select the generational garbage collector with n collected areas, where n specifies the number of non-static heap areas the system will use. Implies use of a generational collector. The default for n is 3 and the minimum is 2.

-np
Select the generational garbage collector with the non-predictive dynamic area. This option can be combined with -areas to select a specific number of areas.

-stopcopy
Select the stop-and-copy garbage collector with one collected area.

-nostatic
Disable the static area (which is on by default in all configurations).

-size size
-sizek size
Specify the size of the data areas, in bytes. If the form -sizek is used, then the size for area k is set, all others remain unchanged. Areas are numbered from 1, where area 1 is the youngest. If the more general form is used, then the value specified affects all areas that have not had their size specified individually.

The dynamic area will grow to accomodate the live data; see -load and -max.

-steps n
-stepsize size
Select the generational garbage collector and the non-predictive dynamic area, and also set the initial number of steps or the initial step size.

-stats
Print a summary of memory allocation statistics at startup time.

5. GC policy options (precise GC)

-max size
Specify the desired maximum heap size for the dynamic area. This is a very strong suggestion to the collector for that area that it should never allow the size of the area to grow to more than size bytes. In each case when the collector cannot obey this, it prints a message to this effect and temporarily exceeds the limit with the minimal amount it thinks works.

In practice this appears to work very well.

-load n
Specify the inverse load factor (ratio of heap storage to live storage) for the dynamic area. This is a decimal number; the default is 3.0.

-rhash size
Specify the size of the remembered-set hash table, in the number of elements the table will have. The size given must be a power of 2. The default is 16K. Bug warning: this is ignored in 1.0a1. See BUGS.

-ssb size
Specify the size of the write barrier's Sequential Store Buffer (SSB), as the number of elements the SSB will have. The default is 16K. Bug warning: this is ignored in 1.0a1. See BUGS.

6. GC policy options (conservative GC)

-incremental
Enable the conservative collector's incremental, generational mode. This switch is currently disabled. I've had no luck whatever using incremental collection under SunOS; this probably has to do with the costly VM write protection under SunOS coupled with the very high frequency of writes. Here are some musings on the issue.

7. General options

-help
Print a summary of the legal command line options.

-quiet
Suppress nonessential messages.

-annoy-user
-annoy-user-greatly
Print annoying messages at major points in the program (garbage collections in older generations, for example). The form -annoy-user-greatly causes the garbage collectors to print messages about promotions and policy decisions also. Try it; you'll hate it.

8. Developers' options

-break
[Development] Enable manually-placed breakpoints.

-step
[Development] Enable debugging of code compiled with MAL single-stepping enabled.

9. Startup/configuration file

The default read-eval-print loop looks for a startup/configuration file when Larceny is started. The file, if found, will be assumed to contain either Scheme source code or compiled fasl-format code, and will be loaded before control is passed to the repl. If the file is found but the load fails, a warning will be printed but the read-eval-print loop will still be run.

The file .larceny will be taken to be the startup file; Larceny looks first in the current directory and then in the user's home directory.

10. Reorganizing a heap image

You can create a split heap image by invoking the following command: 
    larceny.bin -reorganize-and-dump filename
where filename is the name of an existing heap file. Larceny will read the heap file, reorganize it into two pieces, one containing code and one other data, and then dump a new heap file filename.split containing the split heap. Larceny then exits. The new heap file can be used as an argument to larceny in future runs.

$Id: starting.html,v 1.4 1998/12/21 21:23:23 will Exp $
larceny@ccs.neu.edu