The OPJ Virtual Machine

SYNOPSIS

opj [ options ] classname <args>

DESCRIPTION

The OPJ  Virtual Machine accepts all the standard virtual machine command line options, arguments and environment variables which are described in the Java(TM) 2 SDK Documentation. However, some default values for these options have been increased to better suit OPJ applications. In particular, the default initial heap size is 24MB and the default maximum heap size is 64MB.

MEMORY MANAGEMENT

PJama utilizes a two-generation allocation system and garbage collector, referred to as "young-space" and "old-space", respectively. In the absence of persistent objects, this system operates in the same way as the standard virtual machine. Objects are allocated in young-space and, if they survive several young-space collections, they are promoted to old-space, which is collected less frequently.

When running with a persistent store, persistent objects are faulted into main-memory as needed by allocating them in either the young space or the old space, which can be controlled by a command-line option. The default is to allocate faulted-in objects in old space, on the assumption that persistent objects are inherently long-lived, at least when compared with the very short-lived objects that are created during computations. It may help to think of the persistent objects as being the a special very-old generation, although the heap is not, in fact, structured as a three generation system.

Memory management in PJama is complicated by the fact that the total size of the persistent objects accessed by an application may exceed the maximum heap size. One way to solve this is simply to increase the heap size, which is the only solution available in a standard Java Virtual Machine. Ultimately, this results in the paging of the heap by the operating ssystem once physical memory is exhausted. This solution can interact badly with the old-space garbage collector, as it always traces the entire old-space generation, provoking considerable paging activity.

PJama provides an alternative solution that is based on evicting individual objects. This is similar to paging, but operates at the object granularity, which can be more efficient. Several policies are available for controlling eviction, of which the default is called "second-chance". This policy attempts to determine objects that are not being accessed by the application and selects these for eviction. Evicted objects, of course, are faulted in again automatically if they are subsequently needed. Eviction only occurs as part of an old-space collection.

OPJ OPTIONS

In this document we only describe the options and environment variables that are specific to OPJ. Some are preceeded by -X, consistent with the conventions for non-standard options. The only option that is required in normal usage is -config.

-classroot classname

Makes the specified class a persistent root. The class is unconditionally loaded and initialized before the main class, using the application class loader.  This option can be used to run simple applications without requiring any modifications at all to the source code.  Provided that the given class contains static variables that can act as persistent roots, this option and the implicit checkpoint on normal termination suffice to cause the objects reachable from the roots to be made persistent.

-mainonce

-1

Causes the 'main' method in the class passed at the end of the command line to be executed at most once. Subsequent calls with the same command line will skip invocation of 'main'. (By default the main method does get called.) This option is useful with AWT programs, where the main program creates persistent windows that manage all the application control logic. Without this option, each run would create duplicate windows.

-mainroot

Equivalent to "-classroot mainclassname"

-noexitcheckpoint

Switches off automatic checkpointing on "normal" VM exit. By default process termination with status code '0' causes a checkpoint just before the process terminates.

-nowindowresume

Switches off automatic restart notification of visible AWT windows. By default visible windows are roots of persistence and automatically reappear on the screen on restart.

-pjamaversion

Causes output of a version string to 'stdout'.

-config pathname

-store pathname

Provides a name that represents the persistent object store.  The pathname argument must be absolute  and must denote a valid configuration file. If the store specified by the configuratiion file has already been created, it will be opened. If not, a new store will be created. There is no default configuration pathname. N.B. If this argument is omitted, the OPJ Virtual Machine acts as a regular VM without orthogonal persistence.

-Xevict<level>

Controls the policy on eviction of persistent objects from the resident-object cache. Level is an integer with the following values:

0    do not evict any resident persistent objects (no eviction)

1    evict all unreachable unmodified resident objects

2    (default) also evict reachable unmodified resident objects

3    also evict modified reachable objects (unimplemented)

In this context, "reachable" is defined in terms of the set of active (resident in primary-memory) objects. That is, references to non-resident objects are not followed.

-Xevict<strategy>

This option controls the eviction strategy if and only if the eviction level (see above) is 2 (evict all "candidate" objects--ones not modified and not needed for PEVM operation). The option controls which among the candidate objects are actually evicted:

total    evict all candidate objects

random[percent]    evict a randomally generated subset of the candidate objects. The default percentage is 50%.

secondchance    evict those objects that were not accessed since the last old-space collection.

-XpagebuffersizeNumberOfBytes

Sets the size of Sphere's page buffer (disk block cache) in bytes (e.g. " -Xpagebuffersize4M "). If not set, Sphere uses its own default setting (8MB).

-Xverifyrot

This is a debugging option and causes the consistency of the Resident Object Table (ROT) to be checked at key points.

opj -Xevict:0 -config ....