eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ObjectMemory':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: ObjectMemory


Inheritance:

   Object
   |
   +--ObjectMemory

Package:
stx:libbasic
Category:
System-Support
Version:
rev: 1.326 date: 2018/05/24 19:10:08
user: cg
file: ObjectMemory.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


This class contains access methods to the system memory and the VM.

In previous ST/X versions, this stuff used to be in the Smalltalk class.
It has been separated for better overall class structure and modularisation.
There are no instances of ObjectMemory - all is done in class methods.
(this is a functional interface).

Many methods here are for debuging purposes, for developers
or experimental, and therefore not standard.
Do not depend on them being there - some may vanish ...
(especially those, that depend on a specific GC implementation)
Most of the stuff found here is not available, or different or called
different in other smalltalk implementations. Be aware, that using these
interfaces (especially: depending on them) may make your application
non portable.

See more documentation in -> caching
                          -> interrupts
                          -> garbageCollection

[Class variables:]

    InternalErrorHandler            gets informed (by VM), when some runtime
                                    error occurs (usually fatal)

    UserInterruptHandler            gets informed (by VM) when CNTL-C is pressed
    TimerInterruptHandler           gets alarm timer interrupts (from VM)
    SpyInterruptHandler             another alarm timer (from VM)
    StepInterruptHandler            gets single step interrupts (from VM)
    ExceptionInterruptHandler       gets floating point exceptions (from VM)
    ErrorInterruptHandler           gets primitive errors (from VM)
    MemoryInterruptHandler          gets soon-out-of-memory conditions (from VM)
    SignalInterruptHandler          gets unix signals (from VM)
    ChildSignalInterruptHandler     gets child death signals (from VM)
    DisposeInterruptHandler         gets informed, when an object is disposed from
                                    a shadowArray (from VM)
    RecursionInterruptHandler       gets recursion limit violations (from VM)
    IOInterruptHandler              gets SIGIO unix signals (from VM)
    CustomInterruptHandler          gets custom interrupts (from VM)

    InterruptLatencyMonitor         if nonNil, that one will be notified (by the VM)
                                    with an interruptLatency:millis message for every
                                    interrupt and gets the delay time
                                    (between the time when the signal arrived and
                                     when it was really delivered) as argument.
                                    This can be used to create a statistic for
                                    realtime systems.

    RegisteredErrorInterruptHandlers
                                    associates errorID (as passed from primitive
                                    to the __errorInterruptWithID() function)
                                    with handlers.

    IncrementalGCLimit              number of bytes, that must be allocated since
                                    last full garbage collect to turn the incremental
                                    collector on (at idle time).

    FreeSpaceGCLimit                low limit on freeSpace, at which incremental
                                    gc starts to run at idle time.

    FreeSpaceGCAmount               amount to allocate, once freeSpace drops
                                    below FreeSpaceGCLimit

    DynamicCodeGCTrigger            amount of generated dynamically compiled code
                                    to trigger the incremental garbage collector
                                    nil means: no trigger

    DynamicCodeLimit                max. amount of space allocated for dynamically compiled code
                                    nil means: unlimited.

    JustInTimeCompilationEnabled    boolean - enables/disables JIT-compilation of
                                    bytecode to machine code.
                                    (this has nothing to do with stc-compilation)

    Dependents                      keep my dependents locally (its faster) for
                                    all those registries

    LowSpaceSemaphore               a semaphore signalled whenever the system is
                                    running in low memory (i.e. the memory manager
                                    ran into memory shortage and feels that it
                                    may soon no longer be able to grant allocation requests).
                                    You can have a process waiting on this semaphore
                                    which starts to remove (i.e. nil-out) objects
                                    or preform other cleanup actions.

    AllocationFailureSignal         signal raised when a new fails (see Behavior)
                                    When this signal is raised, the memory manager
                                    is really in trouble (i.e. above low-mem feelings
                                    were correct)

    MallocFailureSignal             signal raised when a malloc fails
                                    mallocs are used internally in the VM and/or
                                    by some classes (ExternalBytes)

    BackgroundCollectProcess        created by startBackgroundCollectorAt:

    BackgroundFinalizationProcess   created by startBackgroundFinalizationAt:

    BackgroundCollectMaximumInterval
                                    number of seconds after which an incremental background
                                    collection is started - regardless of the allocation
                                    rate or freeSpace situation. If nil, IGC is only done
                                    when the space situation makes it feasable.
                                    Can be set to (say) 3600, to have the memory cleaned
                                    at least once an hour.

    FinalizationSemaphore           triggered by the VM, when any weak pointer is
                                    lost. Been waited upon by the backgroundFinalizer.

    ImageName                       name of the current image (or nil)

    ImageSaveTime   <Timestamp>  timestamp when this image was saved


Warning:
  The InterruptHandler variables are known by the runtime system -
  they are the objects that get an interrupt message when the event
  occurs. You may not remove any of them.


Class protocol:

Compatibility-ST80
o  availableFreeBytes
return the amount of free memory
(both in the compact free area and in the free lists)
usage example(s):
     ObjectMemory availableFreeBytes

o  bytesPerOOP
return the number of bytes an object reference (for example: an instvar)
takes
usage example(s):
     ObjectMemory bytesPerOOP

o  bytesPerOTE
return the number of overhead bytes of an object.
i.e. the number of bytes in every objects header.
usage example(s):
     ObjectMemory bytesPerOTE

o  collectGarbage
ObjectMemory garbageCollect

o  compactingGC
perform a compacting garbage collect

o  current
the 'current' ObjectMemory - that's myself

o  globalCompactingGC
perform a compacting garbage collect

o  globalGarbageCollect
perform a compacting garbage collect

o  growMemoryBy: numberOfBytes
allocate more memory

o  numOopsNumBytes
return an array filled with the number of objects
and the number of used bytes.
usage example(s):
     ObjectMemory numOopsNumBytes

o  verboseCompactingGC
ST80 compatibility; same as verboseGarbageCollect

o  verboseGlobalCompactingGC
ST80 compatibility; same as verboseGarbageCollect

o  versionId
return this systems version.
For ST80 compatibility.

Signal constants
o  allocationFailureSignal
return the signal raised when an object allocation failed

o  mallocFailureSignal
return the signal raised when malloc memory allocation failed.
(usually, this kind of memory is used with I/O buffers or other temporary
non-Object storage)

VM messages
o  debugPrinting
return true, if various debug printouts in the VM
are turned on, false of off.
usage example(s):
     ObjectMemory debugPrinting

o  debugPrinting: aBoolean
turn on/off various debug printouts in the VM
in case of an error. For example, a double-notUnderstood
leads to a VM context dump if debugPrinting is on.
If off, those messages are suppressed.
The default is on, since these messages are only printed for severe errors.
Returns the previous setting.

o  infoPrinting
return true, if various informational printouts in the VM
are turned on, false of off.
usage example(s):
     ObjectMemory infoPrinting

o  infoPrinting: aBoolean
turn on/off various informational printouts in the VM.
For example, the GC activity messages are controlled by
this flags setting.
The default is true, since (currently) those messages are useful for ST/X developers.
Returns the previous setting.

o  initTrace: aBoolean
turn on/off various init-trace printouts in the VM.
The default is false.
Returns the previous setting.

VM unwind protect support
o  lookupMethodForSelectorUnwindHandlerFor: lookup
An unwind handler for external method lookup
(MOP). This method effectively called only
from handler block returned by
ObjectMemory>>unwindHandlerInContext:.

The VM also create an artifical context with
ObjectMemory as receiver and selector if this
method as selector and marks it for unwind.

See: ObjectMemory>>unwindHandlerInContext:

o  unwindHandlerInContext: aContext
Return an unwind handler block for given context.
Selector of that context denotes which unwind handler
to use.

Occasionally, the VM needs to unwind-protect some C code.
If so, it creates and artificial context on the stack and
marks it for unwind, so stack unwinding logic finds it
and handles it.

Now, only #lookupMethodForSelectorUnwindProtect is supported
(ensures the lookup is popped out from the lookupActications)

access debugging
o  debugPrivacyChecks: aBoolean
turn on/off checks for private methods being called.
By default, this is on in the ST/X IDE, but off for standAlone (packaged) endUser
applications. Method privacy is an experimental feature, which may be removed in later
versions, if it turns out to be not useful.

o  setTrapOnAccessFor: anObject
install an access trap for anObject;
An accessSignal will be raised, whenever any instvar of anObject is either read or written.
This is not supported on all architectures, therefore the return value
(true of trap was installed ok, false if failed) should be checked.

o  setTrapOnReadFor: anObject
install a read trap for anObject;
An accessSignal will be raised, whenever any access into anObject occurs.
This is not supported on all architectures, therefore the return value
(true of trap was installed ok, false if failed) should be checked.

o  setTrapOnWriteFor: anObject
install a write trap for anObject;
An accessSignal will be raised, whenever any instvar of anObject is written to.
This is not supported on all architectures, therefore the return value
(true of trap was installed ok, false if failed) should be checked.

o  unsetAllTraps
remove all access traps

o  unsetTrapFor: anObject
remove any access trap for anObject.

cache management
o  debugBreakPoint

o  debugBreakPoint3

o  flushCaches
flush method and inline caches for all classes

o  flushCachesFor: aClass
flush method and inline caches for aClass

o  flushCachesForSelector: aSelector
flush method and inline caches for aSelector

o  flushCachesForSelector: aSelector numArgs: numArgs
flush method and inline caches for aSelector

o  flushInlineCaches
flush all inlinecaches

o  flushInlineCachesFor: aClass withArgs: nargs
flush inlinecaches for calls to aClass with nargs arguments

o  flushInlineCachesForClass: aClass
flush inlinecaches for calls to aClass.

o  flushInlineCachesForSelector: aSelector
flush inlinecaches for sends of aSelector

o  flushInlineCachesWithArgs: nargs
flush inlinecaches for calls with nargs arguments

o  flushMethodCache
flush the method cache

o  flushMethodCacheFor: aClass
flush the method cache for sends to aClass

o  flushMethodCacheForSelector: aSelector
flush the method cache for sends of aSelector

o  ilcMisses: newValue

o  ilcMissesTrace: bool

o  incrementSnapshotID
obsolete - do not use

o  snapshotID
return the internal snapshotID number.
This is incremented when an image is restarted, and
stored with the image.
Not for normal users, this is used by the VM to invalidate
caches which are stored with the image
usage example(s):
     ObjectMemory snapshotID

o  trapRestrictedMethods: trap
Allow/Deny execution of restricted Methods (see Method>>>restricted:)

Notice: method restriction is a nonstandard feature, not supported
by other smalltalk implementations and not specified in the ANSI spec.
This is EXPERIMENTAL - and being evaluated for usability.
It may change or even vanish (if it shows to be not useful).
usage example(s):
	ObjectMemory trapRestrictedMethods:true
	ObjectMemory trapRestrictedMethods:false

debug queries
o  addressOf: anObject
return the core address of anObject as an integer
- since objects may move around, the returned value is invalid after the
next scavenge/collect.
WARNING: this method is for ST/X debugging only
it will be removed without notice

o  ageOf: anObject
return the number of scavenges, an object has survived
in new space.
For old objects and living contexts, the returned number is invalid.
WARNING: this method is for ST/X debugging only
it will be removed without notice

o  displayRefChainTo: anObject
self displayRefChainTo:Point new

usage example(s):
      Smalltalk at:#foo put:Point new.
      self displayRefChainTo:(Smalltalk at:#foo)
usage example(s):
      self displayRefChainTo:Transcript topView

o  displayRefChainToAny: aCollection

o  displayRefChainToAny: aCollection limitNumberOfSearchedReferences: limitOrNil
consider this a kludge:

o  dumpObject: someObject
low level dump an object.
WARNING: this method is for ST/X debugging only
it may be removed (or replaced by a noop) without notice
usage example(s):
     ObjectMemory dumpObject:true
     ObjectMemory dumpObject:(Array new:10)
     ObjectMemory dumpObject:(10@20 corner:30@40)

o  dumpSender
dump my senders context
usage example(s):
     ObjectMemory dumpSender

o  flagsOf: anObject
For debugging only.
WARNING: this method is for ST/X debugging only
it will be removed without notice

o  objectAt: anAddress
return whatever anAddress points to as object.
BIG BIG DANGER ALERT:
this method is only to be used for debugging ST/X itself
- you can easily (and badly) crash the system.
WARNING: this method is for ST/X debugging only
it will be removed without notice

o  printReferences: anObject
for debugging: print referents to anObject.
WARNING: this method is for ST/X debugging only
it will be removed without notice
use ObjectMemory>>whoReferences: or anObject>>allOwners.

o  refChainFrom: start to: anObject inRefSets: levels startingAt: index
(self refNameFor:anObject in:start)

o  refChainsFrom: start to: anObject inRefSets: levels startingAt: index
(self refNameFor:anObject in:start)

o  refNameFor: anObject in: referent
for our convenience - if it's a nameSpace, cut off Smalltalk.

o  sizeOf: anObject
return the size of anObject in bytes.
(this is not the same as 'anObject size').
WARNING: this method is for ST/X debugging only
it will be removed without notice

o  spaceOf: anObject
return the memory space, in which anObject is.
- since objects may move between spaces,
the returned value may be invalid after the next scavenge/collect.
WARNING: this method is for ST/X debugging only
it will be removed without notice

debugging ST/X
o  checkConsistency
call the object memory consistency checker.
Useful to check if all obejct references are still valid,
especially when primitive (inline-C) code is developed.
If called before and after a primitive, missing STORE checks or
overwritten object headers etc. might be detected.
(there is no real guarantee, that all such errors are detected, though)
usage example(s):
     ObjectMemory checkConsistency

o  printPolyCaches
dump poly caches.
WARNING: this method is for debugging only
it will be removed without notice
usage example(s):
     ObjectMemory printPolyCaches

o  printStackBacktrace
print a stack backtrace - then continue.
(You may turn off the stack print with debugPrinting:false)
WARNING: this method is for debugging only
it will be removed without notice
usage example(s):
     ObjectMemory printStackBacktrace

o  printStackBacktraceFrom: aContext
print a stack backtrace - then continue.
(You may turn off the stack print with debugPrinting:false)
WARNING: this method is for debugging only
it will be removed without notice
usage example(s):
     ObjectMemory printStackBacktraceFrom:thisContext sender sender

o  printSymbols
dump the internal symbol table.
WARNING: this method is for debugging only
it will be removed without notice
usage example(s):
     ObjectMemory printSymbols

o  sendTraceOff
turns tracing of message sends off.
WARNING: this method is for debugging only
it may be removed without notice
usage example(s):
     ObjectMemory sendTraceOff

o  sendTraceOn
turns tracing of message sends on.
WARNING: this method is for debugging only
it may be removed without notice
usage example(s):
     ObjectMemory sendTraceOn

dependents access
o  dependents
return the collection of my dependents

o  dependents: aCollection
set the dependents collection

o  dependentsDo: aBlock
evaluate aBlock for all of my dependents.
Since this is performed at startup time (under the scheduler),
this is redefined here to catch abort signals.
Thus, if any error occurs in a #returnFromSnapshot,
the user can press abort to continue.

enumerating
o  allInstancesOf: aClass do: aBlock
evaluate the argument, aBlock for all instances of aClass in the system.
There is one caveat: if a compressing oldSpace collect
occurs while looping over the objects, the loop cannot be
continued (for some internal reasons). In this case, false
is returned.

o  allObjectsDo: aBlock
evaluate the argument, aBlock for all objects in the system.
There is one caveat: if a compressing oldSpace collect
occurs while looping over the objects, the loop cannot be
continued (for some internal reasons). In this case, false
is returned.

o  allObjectsIncludingContextsDo: aBlock
like allObjectsDo, but also walks over all contexts
of living processes

o  allOldObjectsDo: aBlock
evaluate the argument, aBlock for all old objects in the system.
For debugging and tests only - do not use

o  processesKnownInVM
debug query: return a collection of processObjects as known
in the VM. For ST/X internal use only.
usage example(s):
     ObjectMemory processesKnownInVM

garbage collection
o  backgroundCollectProcess
return the backgroundCollectProcess (or nil, if noone is running)

o  backgroundCollectorRunning
return true, if a backgroundCollector is running
usage example(s):
     ObjectMemory backgroundCollectorRunning

o  compressOldSpace
COMPRESS the oldSpace memory area.
This uses an inplace 2-pass compress algorithm, which may
be slightly slower than the semispace compress if lots of real memory
is available.
In memory limited systems, this inplace compress is usually preferable.
Inplace compression can be enforced by setting the compress-limit to a
small number.

This can take a long time.
usage example(s):
     ObjectMemory compressOldSpace
usage example(s):
     Transcript showCR:(Time millisecondsToRun:[
	 ObjectMemory markAndSweep.
	 ObjectMemory compressOldSpace.
     ]).

o  compressingGarbageCollect
search for and free garbage in the oldSpace (newSpace is cleaned automatically)
performing a COMPRESSING garbage collect.
This uses a 1-pass copying semispace algorithm, which may
be slightly faster than the 2-pass in-place compress if enough real memory
is available. In memory limited systems, an inplace compress is
preferable, which is enforced by setting the compress-limit to a
small number.

This can take a long time - especially, if paging is involved
(when no paging is involved, its faster than I thought :-).
If no memory is available for the compress, or the system has been started with
the -Msingle option, this does a non-COMPRESSING collect.
usage example(s):
     ObjectMemory compressingGarbageCollect

o  garbageCollect
search for and free garbage in the oldSpace.
This can take a long time - especially, if paging is involved.
usage example(s):
     ObjectMemory garbageCollect

o  gcStep
one incremental garbage collect step.
Mark or sweep some small number of objects. This
method will return after a reasonable (short) time.
This is used by the ProcessorScheduler at idle times.
Returns true, if an incremental GC cycle has finished.

o  gcStepIfUseful
If either the IncrementalGCLimit or the FreeSpaceGCLimits have been
reached, perform one incremental garbage collect step.
Return true, if more gcSteps are required to finish the cycle,
false if done with a gc round.
If no limit has been reached yet, do nothing and return false.
This is called by the ProcessorScheduler at idle times or by the
backgroundCollector.

o  incrementalGC
perform one round of incremental GC steps.
The overall effect of this method is (almost) the same as calling
markAndSweep. However, #incrementalGC is interruptable while #markAndSweep
is atomic and blocks for a while. The code here performs incremental
GC steps, until one complete gc-cycle is completed. If running at a higher
than userBackground priority, it will give up the CPU after every such
step for a while.
Thus this method can be called either from a low prio (background) process
or from a high prio process.
(however, if you have nothing else to do, its better to call for markAndSweep,
since it is faster)
For example, someone allocating huge amounts of memory could
ask for the possibility of a quick allocation using
#checkForFastNew: and try a #incrementalGC if not. In many
cases, this can avoid a pause (in the higher prio processes) due to
a blocking GC.
usage example(s):
     ObjectMemory incrementalGC
     [ObjectMemory incrementalGC] forkAt:3
     [ObjectMemory incrementalGC] forkAt:9

o  markAndSweep
mark/sweep garbage collector.
perform a full mark&sweep collect.
Warning: this may take some time and it is NOT interruptable.
If you want to do a collect from a background process, or have
other things to do, better use #incrementalGC which is interruptable.
usage example(s):
     ObjectMemory markAndSweep

o  nonVerboseGarbageCollect
perform a compressing garbage collect or fallback to non-compressing collect,
if required.
usage example(s):
     ObjectMemory nonVerboseGarbageCollect

o  reclaimSymbols
reclaim unused symbols;
Unused symbols are (currently) not reclaimed automatically,
but only upon request with this method.
It takes some time to do this ... and it is NOT interruptable.
Future versions may do this automatically, while garbage collecting.
usage example(s):
     ObjectMemory reclaimSymbols

o  resumeBackgroundCollector
resume the background collector process
usage example(s):
     ObjectMemory resumeBackgroundCollector

o  scavenge
collect young objects, without aging (i.e. no tenure).
Can be used to quickly get rid of shortly before allocated
stuff. This is relatively fast (compared to oldspace collect).

An example where a non-tenuring scavenge makes sense is when
allocating some OperatingSystem resource (a Color, File or View)
and the OS runs out of resources. In this case, the scavenge may
free some ST-objects and therefore (by signalling the WeakArrays
or Registries) free the OS resources too.
Of course, only recently allocated resources will be freed this
way. If none was freed, a full collect will be needed.
usage example(s):
     ObjectMemory scavenge

o  startBackgroundCollectorAt: aPriority
start a process doing incremental GC in the background.
Use this, if you have suspendable background processes which
run all the time, and therefore would prevent the idle-collector
from running. See documentation in this class for more details.
usage example(s):
     ObjectMemory stopBackgroundCollector.

     ObjectMemory incrementalGCLimit:100000.
     ObjectMemory freeSpaceGCLimit:1000000.
     ObjectMemory startBackgroundCollectorAt:4.

o  stopBackgroundCollector
stop the background collector
usage example(s):
     ObjectMemory stopBackgroundCollector

o  suspendBackgroundCollector
suspend the background collector process.
Answer true, if the background collector was running before
usage example(s):
     ObjectMemory suspendBackgroundCollector.
     ObjectMemory resumeBackgroundCollector

o  tenure
force all living new stuff into old-space - effectively making
all living young objects become old objects immediately.
This is relatively fast (compared to oldspace collect).

This method should only be used in very special situations:
for example, when building up some long-living data structure
in a time critical application.
To do so, you have to do a scavenge followed by a tenure after the
objects are created. Be careful, to not reference any other chunk-
data when calling for a tenure (this will lead to lots of garbage in
the oldspace).
In normal situations, explicit tenures are not needed.
usage example(s):
     ObjectMemory tenure

o  tenuringScavenge
collect newspace stuff, with aging (i.e. objects old enough
will be moved into the oldSpace).
Use this for debugging and testing only - the system performs
this automatically when the newspace fills up.
This is relatively fast (compared to oldspace collect)
usage example(s):
     ObjectMemory tenuringScavenge

o  verboseGarbageCollect
perform a compressing garbage collect and show some informational
output on the Transcript
usage example(s):
     ObjectMemory verboseGarbageCollect

garbage collector control
o  allowTenureOf: anObject
set the age of anObject back to 0 so it may eventually tenure
into old space.
This should only be used in very special situations.
One such situation may be to ensure that an object is finalized early by the next
scavenge, and not by a (possibly late) old space collect.
To undo this setup (i.e. to allow the object to tenure again), set its age back to
any value with the seatAgeOf:to: message.
If the object is already old, this call has no effect.
WARNING: this method is for ST/X experts only
it is dangerous, should be used with care
and it may be removed without notice

o  announceOldSpaceNeed: howMuch
announce to the memory system, that howMuch bytes of memory will be needed
soon, which is going to live longer (whatever that means).
It first checks if the memory can be allocated without forcing a compressing
GC. If not, the oldSpace is increased. This may also lead to a slow compressing
collect. However, many smaller increases are avoided afterwards. Calling this
method before allocating huge chunks of data may provide better overall performance.
Notice: this is a nonstandard interface - use only in special situations.
usage example(s):
     ObjectMemory announceOldSpaceNeed:1000000

o  announceSpaceNeed: howMuch
announce to the memory system, that howMuch bytes of memory will be needed
soon. The VM tries to prepare itself for this allocation to be performed
with less overhead. For example, it could preallocate some memory in one
big chunk (instead of doing many smaller reallocations later).
Notice: this is a nonstandard interface - use only in special situations.
Also, this does a background collect before the big chunk of memory is
allocated, not locking other processes while doing so.
usage example(s):
     ObjectMemory announceSpaceNeed:100000

o  avoidTenure: flag
set/clear the avoidTenure flag. If set, aging of newSpace is turned off
as long as the newSpace fill-grade stays below some magic high-water mark.
If off (the default), aging is done as usual.
If the flag is turned on, scavenge may be a bit slower, due to more
objects being copied around. However, chances are high that in an idle
or (almost idle) system, less objects are moved into oldSpace.
Therefore, this helps to avoid oldSpace collects, in systems which go into
some standby mode and are reactivated by some external event.
(the avoid-flag should be turned off there, and set again once the idle loop
is reentered).

This is an EXPERIMENTAL interface.

o  avoidTenure: flag fraction: edenFraction
set/clear the avoidTenure flag and set the fraction of eden to be kept.
If set, aging of newSpace is turned off
as long as the newSpace fill-grade stays below a 1/edenFraction high-water mark.
If off (the default), aging is done as usual.
If the flag is turned on, scavenge may be a bit slower, due to more
objects being copied around. However, chances are high that in an idle
or (almost idle) system, less objects are moved into oldSpace.
Therefore, this helps to avoid oldSpace collects, in systems which go into
some standby mode and are reactivated by some external event.
(the avoid-flag should be turned off there, and set again once the idle loop
is reentered).

This is an EXPERIMENTAL interface.

o  checkForFastNew: amount
this method returns true, if amount bytes could be allocated
quickly (i.e. without forcing a full GC or compress).
This can be used for smart background processes, which want to
allocate big chunks of data without disturbing foreground processes
too much. Such a process would check for fast-allocation, and perform
incremental GC-steps if required. Thus, avoiding the long blocking pause
due to a forced (non-incremental) GC.
Especially: doing so will not block higher priority foreground processes.
See an example use in Behavior>>niceBasicNew:.
This is experimental and not guaranteed to be in future versions.

o  dynamicCodeGCTrigger
return the dynamic code trigger limit for incremental GC activation.
The system will start doing incremental background GC, whenever this amount
of code was dynamically generated.
The default is nil; which disables this trigger
usage example(s):
     ObjectMemory dynamicCodeGCTrigger

o  dynamicCodeGCTrigger: numberOfBytesOrNil
set the dynamic code trigger limit for incremental GC activation.
The system will start doing incremental background GC, whenever this amount
of code was dynamically generated.
The default is nil; which disables this trigger
usage example(s):
     ObjectMemory dynamicCodeGCTrigger:50000

o  dynamicCodeLimit
return the dynamic code limit.
The system will start doing incremental background GC, whenever this amount
of code has been generated (overall), and start to flush the code cache,
if (after the GC), more code is still allocated.
The default is nil; which disables this trigger
usage example(s):
     ObjectMemory dynamicCodeLimit

o  dynamicCodeLimit: nBytesOrNil
set the dynamic code limit.
The system will start doing incremental background GC, whenever this amount
of code has been generated (overall), and start to flush the code cache,
if (after the GC), more code is still allocated.
The default is nil; which disables this trigger
usage example(s):
     ObjectMemory dynamicCodeLimit:100000

o  fastMoreOldSpaceAllocation: aBoolean
this method turns on/off fastMoreOldSpace allocation.
By default, this is turned off (false), which means that in case of
a filled-up oldSpace, a GC is tried first before more oldSpace is allocated.
This strategy is ok for the normal operation of the system,
but behaves badly, if the program allocates huge data structures (say a
game tree of 30Mb in size) which survives and therefore will not be reclaimed
by a GC.
Of course while building this tree, and the memory becomes full, the system
would not know in advance, that the GC will not reclaim anything.

Setting fastMoreOldSpaceAllocation to true will avoid this, by forcing the
memory system to allocate more memory right away, without doing a GC first.

WARNING: make certain that this flag is turned off, after your huge data
is allocated, since otherwise the system may continue to increase its
virtual memory without ever checking for garbage.
This method returns the previous value of the flag; typically this return
value should be used to switch back.

o  fastMoreOldSpaceLimit: aNumber
this method sets and returns the fastMoreOldSpace limit.
If fastMoreOldSpaceAllocation is true, and the current oldSpace size is
below this limit, the memory manager will NOT do a GC when running out of
oldSpace, but instead quickly go ahead increasing the size of the oldSpace.
Setting the limit to 0 turns off any limit (i.e. it will continue to
increase the oldSpace forwever - actually, until the OS refuses to give us
more memory). The returned value is the previous setting of the limit.

o  freeSpaceGCAmount
return the amount to be allocated if, after an incrementalGC,
not at least FreeSpaceGCLimit bytes are available for allocation.
The default is nil, which lets the system compute an abbpropriate value
usage example(s):
     ObjectMemory freeSpaceGCAmount

o  freeSpaceGCAmount: aNumber
set the amount to be allocated if, after an incrementalGC,
not at least FreeSpaceGCLimit bytes are available for allocation.
The amount should be greater than the limit, otherwise the incremental
GC may try over and over to get the memory (actually waisting time).
usage example(s):
     ObjectMemory freeSpaceGCLimit:250000.
     ObjectMemory freeSpaceGCAmount:1000000.
usage example(s):
     ObjectMemory freeSpaceGCAmount:nil.

o  freeSpaceGCLimit
return the freeSpace limit for incremental GC activation.
The system will start doing incremental background GC, once less than this number
of bytes are available in the compact free space.
The default is 100000; setting it to nil will turn this trigger off.
usage example(s):
     ObjectMemory freeSpaceGCLimit

o  freeSpaceGCLimit: aNumber
set the freeSpace limit for incremental GC activation.
The system will start doing incremental background GC, once less than this number
of bytes are available for allocation.
The default is nil; setting it to nil will turn this trigger off.
usage example(s):
     ObjectMemory freeSpaceGCLimit:1000000.
usage example(s):
     ObjectMemory freeSpaceGCLimit:nil.

o  incrementalGCLimit
return the allocatedSinceLastGC limit for incremental GC activation.
The system will start doing incremental background GC, once more than this number
of bytes have been allocated since the last GC.
The default is 500000; setting it to nil will turn this trigger off.
usage example(s):
     ObjectMemory incrementalGCLimit

o  incrementalGCLimit: aNumber
set the allocatedSinceLastGC limit for incremental GC activation.
The system will start doing incremental background GC, once more than this number
of bytes have been allocated since the last GC.
The default is 500000; setting it to nil will turn this trigger off.
usage example(s):
     ObjectMemory incrementalGCLimit:500000.  'do incr. GC very seldom'
     ObjectMemory incrementalGCLimit:100000.  'medium'
     ObjectMemory incrementalGCLimit:10000.   'do incr. GC very often'
     ObjectMemory incrementalGCLimit:nil.     'never'

o  incrementalSweep: aBoolean
ineable/disable incremental sweeps during background GC.
This entry is provided as a test interface and should not be
used by applications - it may vanish without notice
usage example(s):
     ObjectMemory incrementalSweep:false.
     ObjectMemory incrementalSweep:true

o  lockTenure: flag
set/clear the tenureLock. If the lock is set, the system
completely turns off tenuring, and objects remain in newSpace (forever).
Once this lock is set, the system operates only in the newSpace and no memory
allocations from oldSpace are allowed (except for explicit tenure calls).
If any allocation request cannot be resoved, the VM raises a memory interrupt,
clears the lockTenure-flag and returns nil. Thus, it automatically falls back into
the normal mode of operation, to avoid big trouble
(fail to allocate memory when handling the exception).

This interface can be used in applications, which are guaranteed to have their
working set completely in the newSpace AND want to limit the worst case
pause times to the worst case scavenge time
(which itself is limitd by the size of the newSpace).
I.e. systems which go into some event loop after initial startup,
may turn on the tenureLock to make certain that no oldSpace memory is
allocated in the future; thereby limiting any GC activity to newSpace scavenges only.

This is an EXPERIMENTAL interface.

o  makeOld: anObject
move anObject into oldSpace.
This method is for internal & debugging purposes only -
it may vanish. Don't use it, unless you know what you are doing.

o  makeOld: anObject now: aBoolean
move anObject into oldSpace.
If aBoolean is true, this is done immediately, but takes some processing time.
Otherwise, it will be done on-the-fly in the near future, without any cost.
If multiple objects are to be aged this way, pass a false as argument.
This method is for internal & debugging purposes only -
it may vanish. Don't use it, unless you know what you are doing.

o  maxOldSpace
return the maxOldSpace value. If non-zero, that's the limit for which the
VM will try hard to not allocate more oldSpace memory. (its not a hard limit)
If zero, it will allocate forever (until the OS won't hand out more).
The default is zero.
usage example(s):
     ObjectMemory maxOldSpace

o  maxOldSpace: amount
set the maxOldSpace value. If non-zero, that's the limit for which the
VM will try hard to not allocate more oldSpace memory. (its not a hard limit)
If zero, it will allocate forever (until the OS wont hand out more).
The default is zero.
WARNING:
an oldSpace limit may lead to trashing due to exorbitant GC activity;
its usually better to let it allocate more and page in/page out.
Usually, the background GC will catch up sooner or later and reclaim
the memory without blocking the system
usage example(s):
     to change maximum to 1GByte:

        ObjectMemory maxOldSpace:1024*1024*1024

o  moreOldSpace: howMuch
allocate howMuch bytes more for old objects; return true if this worked,
false if that failed.
This is done automatically, when running out of space, but makes
sense, if it's known in advance that a lot of memory is needed to
avoid multiple reallocations and compresses.
On systems which do not support the mmap (or equivalent) system call,
this (currently) implies a compressing garbage collect - so its slow.
Notice: this is a nonstandard interface - use only in special situations.
usage example(s):
     ObjectMemory moreOldSpace:1000000

o  moreOldSpaceIfUseful
to be called after an incremental GC cycle;
if freeSpace is still below limit, allocate more oldSpace

o  newSpaceSize: newSize
change the size of the newSpace. To do this, the current contents
of the newSpace may have to be tenured (if size is smaller).
Returns false, if it failed for any reason.
Experimental: this interface may valish without notice.

DANGER ALERT:
be careful too big of a size may lead to longer scavenge pauses.
Too small of a newSpace may lead to more CPU overhead, due to
excessive scavenges. You have been warned.
usage example(s):
less absolute CPU overhead (but longer pauses):

    ObjectMemory newSpaceSize:1600*1024
usage example(s):
smaller pauses, but more overall CPU overhead:

    ObjectMemory newSpaceSize:200*1024
usage example(s):
the default:

    ObjectMemory newSpaceSize:800*1024

o  oldSpaceCompressLimit
return the limit for oldSpace compression. If more memory than this
limit is in use, the system will not perform compresses on the oldspace,
but instead do a mark&sweep GC followed by an oldSpace increase if not enough
could be reclaimed. The default is currently some 8Mb, which is ok for workstations
with 16..32Mb of physical memory. If your system has much more physical RAM,
you may want to increase this limit.
usage example(s):
     ObjectMemory oldSpaceCompressLimit

o  oldSpaceCompressLimit: amount
set the limit for oldSpace compression. If more memory than this
limit is in use, the system will not perform compresses on the oldspace,
but instead do a mark&sweep GC followed by an oldSpace increase if not enough
could be reclaimed. The default is currently some 8Mb, which is ok for workstations
with 16..32Mb of physical memory. If your system has much more physical RAM,
you may want to increase this limit.
This method returns the previous increment value.
usage example(s):
     ObjectMemory oldSpaceCompressLimit:12*1024*1024

o  oldSpaceIncrement
return the oldSpaceIncrement value. That's the amount by which
more memory is allocated in case the oldSpace gets filled up.
In normal situations, the default value used in the VM is fine
and there is no need to change it.
usage example(s):
     ObjectMemory oldSpaceIncrement

o  oldSpaceIncrement: amount
set the oldSpaceIncrement value. That's the amount by which
more memory is allocated in case the oldSpace gets filled up.
In normal situations, the default value used in the VM is fine
and there is no need to change it. This method returns the
previous increment value.
usage example(s):
     ObjectMemory oldSpaceIncrement:1024*1024

o  preventTenureOf: anObject
set the age of anObject to the never-tenure special age.
This prevents the object from ever going out of the new space,
and if used without care may lead to a filling of the newspace to a point,
where the system becomes inoperable.
Therefore it should only be used in very special situations.
One such situation may be to ensure that an object is finalized early by the next
scavenge, and not by a (possibly late) old space collect.
To undo this setup (i.e. to allow the object to tenure again), set its age back to
any value with the setAgeOf:to: message.
If the object is already old, this call has no effect.
WARNING: this method is for ST/X experts only
it is dangerous, should be used with care
and it may be removed without notice

o  setAgeOf: anObject to: newAge
change the age of anObject.
This counts the number of scavenges that an object has survived in new space.
If it is set to 0, this makes GC think, that the object is just created, and it will
remain in eden for a longer time.
If it is set to a big number (say > 32), GC will think that it is old, and tenure it
with the next collect into old space. This later operation will get the object out of the way,
if it is well-known, that it will survive for a very long time.
For old space objects, this is a no-op.

WARNING: this method is for ST/X debugging only
it may be removed without notice

o  tenureParameters: magic
this is pure magic and not for public eyes ...
This method allows fine tuning the scavenger internals,
in cooperation to some statistic & test programs.
It is undocumented, secret and may vanish.
If you play around here, the system may behave very strange.

o  turnGarbageCollectorOff
turn off the generational garbage collector by forcing new objects to be
allocated directly in oldSpace (instead of newSpace)
WARNING:
This is somewhat dangerous: if collector is turned off,
and too many objects are created, the system may run into trouble
(i.e. oldSpace becomes full) and be forced to perform a full mark&sweep
or even a compressing collect - making the overall realtime behavior worse.
Use this only for special purposes or when realtime behavior
is required for a limited time period.

OBSOLETE: this is no longer supported
- it may be a no-operation by the time you read this.

o  turnGarbageCollectorOn
turn garbage collector on again (see ObjectMemory>>turnGarbageCollectorOff)

o  watchTenure: flag
set/clear the tenureWatch. If set, an internalError exception will be raised,
whenever objects are tenured from newSpace into oldSpace
(except for an explicit tenure request).
This can be used to validate that no oldSpace objects are created
(i.e. the system operates fully in newSpace).
Be careful, if the avoidTenure flag is not set,
there will almost always be a tenure sooner or later.

EXPERIMENTAL - no warranty

garbage collector settings
o  restoreGarbageCollectorSettings
restore the saved garbage collector settings

o  saveGarbageCollectorSetting: aSymbol value: something
save some garbage collector setting, which is stored only in the VM,
to be restored on snapshot return

initialization
o  initialize
initialize the class

interrupt handler access
o  childSignalInterruptHandler
return the handler for UNIX-death-of-a-childprocess-signal interrupts

o  childSignalInterruptHandler: aHandler
set the handler for UNIX-death-of-a-childprocess-signal interrupts

o  customInterruptHandler
return the handler for custom interrupts

o  customInterruptHandler: aHandler
set the handler for custom interrupts

o  disposeInterruptHandler
return the handler for object disposal interrupts

o  disposeInterruptHandler: aHandler
set the handler for object disposal interrupts

o  errorInterruptHandler
return the handler for display error interrupts

o  errorInterruptHandler: aHandler
set the handler for display error interrupts

o  exceptionInterruptHandler
return the handler for floating point exception interrupts

o  internalErrorHandler
return the handler for ST/X internal errors.
An internal error is reported for example when a methods
bytecode is not a ByteArray, the selector table is not an Array
etc.
Those should not occur in normal circumstances.

o  ioInterruptHandler
return the handler for I/O available signal interrupts (SIGIO/SIGPOLL)

o  ioInterruptHandler: aHandler
set the handler for I/O available signal interrupts (SIGIO/SIGPOLL)

o  recursionInterruptHandler
return the handler for recursion/stack overflow interrupts

o  recursionInterruptHandler: aHandler
set the handler for recursion/stack overflow interrupts

o  registerErrorInterruptHandler: aHandler forID: errorIDSymbol
register a handler

o  registeredErrorInterruptHandlers
return registered handlers

o  signalInterruptHandler
return the handler for UNIX-signal interrupts

o  signalInterruptHandler: aHandler
set the handler for UNIX-signal interrupts

o  spyInterruptHandler
return the handler for spy-timer interrupts

o  spyInterruptHandler: aHandler
set the handler for spy-timer interrupts

o  stepInterruptHandler
return the handler for single step interrupts

o  stepInterruptHandler: aHandler
set the handler for single step interrupts

o  timerInterruptHandler
return the handler for timer interrupts

o  timerInterruptHandler: aHandler
set the handler for timer interrupts

o  userInterruptHandler
return the handler for CNTL-C interrupt handling

o  userInterruptHandler: aHandler
set the handler for CNTL-C interrupt handling

interrupt statistics
o  interruptLatency: ms receiver: rec class: cls selector: sel vmActivity: vmActivity id: pid
example implementation of latencyTime monitoring:
This method simply measures the max-latency time.
You may want to use some other handler (see #interruptLatencyMonitor:)
and extract more information (blocking context).
DEMO Example.

o  interruptLatencyGoal: millis
setup to report an error message, whenever a realtime goal could not be
met due to blocked interrupts or long primitives or GC activity.
An argument of nil clears the check.
DEMO Example.
usage example(s):
     ObjectMemory interruptLatencyGoal:50

o  interruptLatencyMonitor
return the interrupt-latency-monitor if any.
See comment in #interruptLatencyMonitor:.
This is a non-standard debugging/realtime instrumentation entry.

o  interruptLatencyMonitor: aHandler
set the interrupt latency monitor. If non-nil, this one will be sent
an interruptLatency: message with the millisecond delay between
the interrupt and its handling.
This is a non-standard debugging/realtime instrumentation entry.

o  maxInterruptLatency
return the maximum accumulated interrupt latency in millis.
DEMO Example.

o  resetMaxInterruptLatency
reset the maximum accumulated interrupt latency probe time.
DEMO Example.

just in time compilation
o  byteCodeSizeLimitForDynamicCompilation: aNumber
set a limit on a methods number of byteCodes.
Compilation of a method into machine code is aborted,
if it's bytecode size is larger than the given number.
This is only useful, if large methods have a smaller
chance of being evaluated often (which may not be true).
The predefined limit is some 4k (which seems to be ok).
usage example(s):
     ObjectMemory byteCodeSizeLimitForDynamicCompilation:nil
     ObjectMemory byteCodeSizeLimitForDynamicCompilation:8000

o  codeForCPU: aCPUSymbol
instruct the just in time compiler that some specific CPU
is present (forcing it to generate code for that).
The default is set correct for the architecture, and the
runTime system tries to figure out the cpu - but who knows ...
The valid symbols depend on the architecture:
i386: #i486 / #i586 (affects code ordering)
sparc: #sparcV8 / #sparcV8 (affects instruction set)
mips: #rs2000 / #rs4000 (affects delay slot generation)
This method returns the current setting; a nil arg will not change
the setting (but only return the current).

This is a nonstandard entry and may be removed without notice -
not for the general user.
usage example(s):
     ObjectMemory codeForCPU:nil
     ObjectMemory codeForCPU:#i486
     ObjectMemory codeForCPU:#i586

o  codeSizeLimitForDynamicCompilation: aNumber
set a limit on the resulting dynamic generates code
size. Compilation of a method into machine code is aborted,
if the resulting code is larger than the given number of
bytes. This is only useful, if large methods have a smaller
chance of being evaluated often (which may not be true).
The predefined limit is some 4k (which seems to be ok).
usage example(s):
     ObjectMemory codeSizeLimitForDynamicCompilation:nil
     ObjectMemory codeSizeLimitForDynamicCompilation:8000

o  compiledCodeCounter
return the number of additional code-bytes which
were generated since the counter was last reset
usage example(s):
     ObjectMemory compiledCodeCounter

o  compiledCodeSpaceUsed
return the actual number of bytes used for compiled code
usage example(s):
     ObjectMemory compiledCodeSpaceUsed

o  fullSingleStepSupport
return the setting of the full single step support flag
usage example(s):
     ObjectMemory fullSingleStepSupport

o  fullSingleStepSupport: aBoolean
enable/disable full single step support for the just-in-time-compiled code.
If off, things like simple increment/decrement, additions and variable-
stores are not steppable, but treated like atomar invisible operations.
If on, single step halts at those operations.
Execution is a bit slower if enabled.
usage example(s):
     ObjectMemory fullSingleStepSupport:true
     ObjectMemory fullSingleStepSupport:false

o  getCompiledCodeLimit
get the codeLimit from the VM

o  insnSizeLimitForDynamicCompilation: aNumber
set a limit on a methods number of internal insns.
Compilation of a method into machine code is aborted,
if during compilation, more than the given number of
internal insns are generated.
The limit controls the amount of dynamic memory allocated
during compilation and may be changed for small-memory
systems.
The predefined limit is some 4k (which seems to be ok).
usage example(s):
     ObjectMemory insnSizeLimitForDynamicCompilation:nil
     ObjectMemory insnSizeLimitForDynamicCompilation:8000

o  javaJustInTimeCompilation
return the value of the java-just-in-time-compilation flag
usage example(s):
     ObjectMemory javaJustInTimeCompilation

o  javaJustInTimeCompilation: aBoolean
enable/disable java just-in-time-compilation.
usage example(s):
     ObjectMemory javaJustInTimeCompilation:true
     ObjectMemory javaJustInTimeCompilation:false

o  javaNativeCodeOptimization
return the value of the java-native-code-optimization flag
usage example(s):
     ObjectMemory javaNativeCodeOptimization

o  javaNativeCodeOptimization: aBoolean
enable/disable java native code-optimization.
usage example(s):
     ObjectMemory javaNativeCodeOptimization:true
     ObjectMemory javaNativeCodeOptimization:false

o  justInTimeCompilation
return the value of the just-in-time-compilation flag
usage example(s):
     ObjectMemory justInTimeCompilation

o  justInTimeCompilation: aBoolean
enable/disable just-in-time-compilation.
usage example(s):
     ObjectMemory justInTimeCompilation:true
     ObjectMemory justInTimeCompilation:false

o  optimizeContexts
return the setting of the optimize contexts flag
usage example(s):
     ObjectMemory optimizeContexts

o  optimizeContexts: aBoolean
enable/disable restartable contexts for the just-in-time-compiled code.
If off, contexts that does not contain blocks are not restartable.
Execution is a bit slower if enabled.
usage example(s):
     ObjectMemory optimizeContexts:true
     ObjectMemory optimizeContexts:false

o  reEnableJustInTimeCompilation
to be called after a snapshot restart; if justInTimeCompiler
was enabled before, do it again.
For now, this is not done automatically, to allow restarting
a system with the dynamic compiler turned off (its still experimental).
Therefore, this reenabling is done in the smalltalk_r.rc file.

o  resetCompiledCodeCounter
reset the counter of additional code-bytes
usage example(s):
     ObjectMemory resetCompiledCodeCounter

o  setCompiledCodeLimit: newLimit
set the VM's limit

o  supportsJustInTimeCompilation
return true, if this system supports just-in-time-compilation of
bytecode to machine code. Don't confuse this with stc-compilation.
usage example(s):
     ObjectMemory supportsJustInTimeCompilation

low memory handling
o  allocationFailed
memory allocation has failed in the VM
This is triggered by the runtime system (or possibly by
a user primitive)

o  memoryInterrupt
when a low-memory condition arises, ask all classes to
remove possibly cached data. You may help the system a bit,
in providing a lowSpaceCleanup method in your classes which have
lots of data kept somewhere (usually, cached data).
- this may or may not help.

o  performLowSpaceCleanup
ask all classes to remove possibly cached data.
You may help the system a bit, in providing a lowSpaceCleanup method
in your classes which have lots of data kept somewhere (usually, cached data).
Notice: it may never hurt to call lowSpaceCleanup (i.e. the data must always be
reconstructable)
usage example(s):
     ObjectMemory performLowSpaceCleanup

object finalization
o  allChangedShadowObjectsDo: aBlock
evaluate the argument, aBlock for all known shadow objects which have
lost a pointer recently.

o  backgroundFinalizationProcess
return the backgroundFinalizationProcess (or nil, if noone is running)

o  disposeInterrupt
this is triggered by the garbage collector,
whenever any shadowArray looses a pointer.

o  finalize
tell all weak objects that something happened.

o  startBackgroundFinalizationAt: aPriority
start a process doing finalization work in the background.
Can be used to reduce the pauses created by finalization.
Normally, these pauses are not noticed; however if you have (say)
ten thousands of weak objects, these could become long enough to
make background finalization useful.
WARNING: background finalization may lead to much delayed freeing of
system resources. Especially, you may temporarily run out of free
color table entries or fileDescriptors etc. Use at your own risk (if at all)
usage example(s):
     ObjectMemory stopBackgroundFinalization.
     ObjectMemory startBackgroundFinalizationAt:5

o  stopBackgroundFinalization
stop the background finalizer
usage example(s):
     ObjectMemory stopBackgroundFinalization

physical memory access
o  collectedOldSpacePagesDo: aBlock
evaluates aBlock for all pages in the prev. oldSpace, passing
the pages address as argument.
For internal & debugging use only.

o  newSpacePagesDo: aBlock
evaluates aBlock for all pages in the newSpace, passing
the pages address as argument.
For internal & debugging use only.

o  oldSpacePagesDo: aBlock
evaluates aBlock for all pages in the oldSpace, passing
the pages address as argument.
For internal & debugging use only.

o  pageIsInCore: aPageNumber
return true, if the page (as enumerated via oldSpacePagesDo:)
is in memory; false, if currently paged out. For internal
use / monitors only; may vanish.
NOTICE: not all systems provide this information; on those that
do not, true is returned for all pages.

queries
o  bytesUsed
return the number of bytes allocated for objects -
this number is not exact, since some objects may already be dead
(i.e. not yet reclaimed by the garbage collector).
If you need the exact number, you have to loop over all
objects and ask for the bytesize using ObjectMemory>>sizeOf:.
usage example(s):
     ObjectMemory bytesUsed

o  collectObjectsWhich: aBlock
helper for the whoReferences queries. Returns a collection
of objects for which aBlock returns true.

o  collectedOldSpaceAddress
self collectedOldSpaceAddress

o  fixSpaceSize
return the total size of the fix space.
usage example(s):
     ObjectMemory fixSpaceSize

o  fixSpaceUsed
return the number of bytes allocated for old objects in fix space.
usage example(s):
     ObjectMemory fixSpaceUsed

o  freeListSpace
return the number of bytes in the free lists.
(which is included in oldSpaceUsed)
usage example(s):
     ObjectMemory freeListSpace

o  freeSpace
return the number of bytes in the compact free area.
(oldSpaceUsed + freeSpaceSize = oldSpaceSize)
usage example(s):
     ObjectMemory freeSpace

o  garbageCollectCount
return the number of compressing collects that occurred since startup
usage example(s):
     ObjectMemory garbageCollectCount

o  incrementalGCCount
return the number of incremental collects that occurred since startup
usage example(s):
     ObjectMemory incrementalGCCount

o  incrementalGCPhase
returns the internal state of the incremental GC.
The meaning of those numbers is a secret :-).
(for the curious: (currently)
2 is idle, 3..11 are various mark phases,
12 is the sweep phase. 0 and 1 are cleanup phases when the
incr. GC gets interrupted by a full GC).
Do not depend on the values - there may be additional phases in
future versions (incremental compact ;-).
This is for debugging and monitoring only - and may change or vanish

o  incrementalGCPhaseSymbolic
returns the internal state of the incremental GC
in a symbolic form.
(for the curious: (currently)
2 is idle, 3..11 are various mark phases,
12 is the sweep phase. 0 and 1 are cleanup phases when the
incr. GC gets interrupted by a full GC).
Do not depend on the values - there may be additional phases in
future versions (incremental compact ;-).
This is for debugging and monitoring only - and may change or vanish

o  isSchteamEngine
is this Smalltalk/X system running under the new Schteam engine?

o  lastScavengeReclamation
returns the number of bytes replacimed by the last scavenge.
For statistic only - this may vanish.
usage example(s):
percentage of reclaimed objects is returned by:

     ((ObjectMemory lastScavengeReclamation)
      / (ObjectMemory newSpaceSize)) * 100.0

o  lifoRememberedSet
return the lifoRemSet.
This is pure VM debugging and will vanish without notice.
usage example(s):
     ObjectMemory lifoRememberedSet

o  lifoRememberedSetSize
return the size of the lifoRemSet.
This is a VM debugging interface and may vanish without notice.
usage example(s):
     ObjectMemory lifoRememberedSetSize

o  mallocAllocated
return the number of bytes allocated (and used) by malloc.
usage example(s):
     ObjectMemory mallocAllocated

o  mallocTotal
return the number of bytes reserved by malloc (may not have been used yet).
usage example(s):
     ObjectMemory mallocTotal

o  markAndSweepCount
return the number of mark&sweep collects that occurred since startup
usage example(s):
     ObjectMemory markAndSweepCount

o  maximumIdentityHashValue
for ST-80 compatibility: return the maximum value
a hashKey as returned by identityHash can get.
Since ST/X uses direct pointers, a field in the objectHeader
is used, which is currently 11 bits in size.
usage example(s):
     ObjectMemory maximumIdentityHashValue

o  minScavengeReclamation
returns the number of bytes replaimed by the least effective scavenge.
For statistic only - this may vanish.
usage example(s):
     ObjectMemory minScavengeReclamation

o  newSpaceSize
return the total size of the new space - this is usually fix
usage example(s):
     ObjectMemory newSpaceSize

o  newSpaceUsed
return the number of bytes allocated for new objects.
The returned value is usually obsolete as soon as you do
something with it ...
usage example(s):
     ObjectMemory newSpaceUsed

o  numberOfObjects
return the number of objects in the system.
usage example(s):
     ObjectMemory numberOfObjects

o  numberOfWeakObjects
return the number of weak objects in the system
usage example(s):
     ObjectMemory numberOfWeakObjects

o  oldSpaceAddress
self oldSpaceAddress

o  oldSpaceAllocatedSinceLastGC
return the number of bytes allocated for old objects since the
last oldspace garbage collect occurred. This information is used
by ProcessorScheduler to decide when to start the incremental
background GC.
usage example(s):
     ObjectMemory oldSpaceAllocatedSinceLastGC

o  oldSpaceSize
return the total size of the old space. - may grow slowly
usage example(s):
     ObjectMemory oldSpaceSize

o  oldSpaceUsed
return the number of bytes allocated for old objects.
(This includes the free lists)
usage example(s):
     ObjectMemory oldSpaceUsed

o  rememberedSetSize
return the number of old objects referencing new ones.
This is a VM debugging interface and may vanish without notice.
usage example(s):
     ObjectMemory rememberedSetSize

o  resetMinScavengeReclamation
resets the number of bytes replacimed by the least effective scavenge.
For statistic only - this may vanish.
usage example(s):
     ObjectMemory resetMinScavengeReclamation.
     ObjectMemory minScavengeReclamation

o  runsSingleOldSpace
return true, if the system runs in a single oldSpace or
false if not.
The memory system will always drop the second semispace when
running out of virtual memory, or the baker-limit is reached.
OBSOLETE:
the system may now decide at any time to switch between
single and double-space algorithms, depending on the overall memory
size. You will now almost always get true as result, since the
second semispace is only allocated when needed, and released
immediately afterwards.

usage example(s):
     ObjectMemory runsSingleOldSpace

o  scavengeCount
return the number of scavenges that occurred since startup
usage example(s):
     ObjectMemory scavengeCount

o  symSpaceSize
return the total size of the sym space.
usage example(s):
     ObjectMemory symSpaceSize

o  symSpaceUsed
return the number of bytes allocated for old objects in sym space.
usage example(s):
     ObjectMemory symSpaceUsed

o  tenureAge
return the current tenure age - that's the number of times
an object has to survive scavenges to be moved into oldSpace.
For statistic/debugging only - this method may vanish

o  vmSymbols
return a collection of symbols used by the VM

o  whoReferences: anObject
return a collection of objects referencing the argument, anObject
usage example(s):
     (ObjectMemory whoReferences:Transcript) printCR

o  whoReferencesAny: aCollection
return a collection of objects referencing any object from
the argument, aCollection
usage example(s):
     ObjectMemory whoReferencesAny:(Array with:Transcript with:Smalltalk)

o  whoReferencesDerivedInstancesOf: aClass
return a collection of objects refering to instances
of the argument, aClass or a subclass of it.
usage example(s):
     (ObjectMemory whoReferencesDerivedInstancesOf:View) printCR

o  whoReferencesInstancesOf: aClass
return a collection of objects refering to instances
of the argument, aClass
usage example(s):
     (ObjectMemory whoReferencesInstancesOf:SystemBrowser) printCR

semaphore access
o  lowSpaceSemaphore
return the semaphore that is signalled when the system detects a
low space condition. Usually, some time after this, an allocationFailure
will happen. You can have a cleanup process sitting in that semaphore and
start to release object.

statistics
o  ageStatistic
for ST/X developers only:
dump contents of newSpace with objects age information.
This method may be removed without notice
usage example(s):
     ObjectMemory ageStatistic

o  codeCacheInfo
for ST/X developers only:
dump contents of dynamic code cache LRU lists.
This method may be removed without notice
usage example(s):
     ObjectMemory codeCacheInfo do:[:item |
	|n nMethods nBytes|

	n := item at:1.
	nMethods := item at:2.
	nBytes := item at:3.

	n isNil ifTrue:[
	    '>>' print
	] ifFalse:[
	    (n printStringLeftPaddedTo:2) print.
	].
	' ' print.
	(nMethods printStringLeftPaddedTo:4) print.
	' ' print.
	(nBytes printStringLeftPaddedTo:6) printCR.
     ]

o  mallocStatistics
for ST/X developers only:
dump statistics on malloc memory allocation (used, for example for ExternalBytes) on
the standard output. Dummy on some architectures, where the standard malloc is used (win32, for example).
This method may be removed without notice
usage example(s):
     ObjectMemory mallocStatistics

system configuration queries
o  allBinaryModulesDo: aBlock
internal private method - walk over all known binary
modules and evaluate aBlock for each entry.
Do not depend on the information returned for each - this may
change without notice.

o  binaryModuleInfo
return a collection of moduleInfo entries.
This returns a dictionary (keys are internal moduleIDs)
with one entry for each binary package (module).
usage example(s):
     ObjectMemory binaryModuleInfo

o  getVMIdentificationStrings
return a collection of release strings giving information
about the running VM. This is for configuration management only.
Do not depend on the information returned - this may
change or vanish without notice.
usage example(s):
     ObjectMemory getVMIdentificationStrings

system management
o  directoryForImageAndChangeFile
the current directory is not a good idea, if stx is started via a desktop manager
usage example(s):
     self directoryForImageAndChangeFile

o  imageBaseName
return a reasonable filename to use as baseName (i.e. without extension).
This is the filename of the current image (without '.img') or,
if not running from an image, the default name 'st'
usage example(s):
     ObjectMemory imageBaseName

o  imageName
return the filename of the current image, or nil
if not running from an image.
usage example(s):
     ObjectMemory imageName

o  imageSaveTime
return a timestamp for when the running image was saved.
Return nil if not running from an image.

o  initChangeFilename
make the changeFilePath an absolute one,
usage example(s):
     self initChangeFilename

o  nameForChanges
return a reasonable filename string to store the changes into.
By default, this is the basename of the current image with '.img' replaced
by '.chg', or, if not running from an image, the default name 'st.chg'.
However, it can be overwritten via the nameForChanges: setter.
For now, this returns a string (for backward compatibility);
senders should be prepared to get a filename in the future.
usage example(s):
     ObjectMemory nameForChanges

o  nameForChanges: aFilename
set the name of the file where changes are stored into.
usage example(s):
     ObjectMemory nameForChanges:'myChanges'

o  nameForChangesLocal
return a reasonable filename to store the changes into.

o  nameForCrashImage
ObjectMemory nameForCrashImage

o  nameForSnapshot
return a reasonable filename to store the snapshot image into.
This is the filename of the current image or,
if not running from an image, the default name 'st.img'
usage example(s):
     ObjectMemory nameForSnapshot

o  nameForSnapshotLocal
return a reasonable filename to store the snapshot image into.
This is the filename of the current image or,
if not running from an image, the default name 'st.img'

o  nameForSources
return a reasonable filename to store the sources into.
This is the basename of the current image with '.img' replaced
by '.src', or, if not running from an image, the default name 'st.src'
usage example(s):
     ObjectMemory nameForSources

o  primSnapShotOn: aFilename
create a snapshot in the given file.
Low level entry. Does not notify classes or write an entry to
the changes file. Also, no image backup is created.
Returns true if the snapshot worked, false if it failed for some reason.
This method should not be used in normal cases.

o  refreshChangesFrom: oldChangesName
The snapshot image name has changed (snapshot saved),
the changes file must be copied to the new name.
No copy when the changes name is given explicitly.

o  snapShot
create a snapshot file containing all of the current state.
usage example(s):
     ObjectMemory snapShot

o  snapShotOn: aFileName
create a snapshot file containing all of the current state.
usage example(s):
     ObjectMemory snapShotOn:'myimage.img'

o  snapShotOn: aFileName setImageName: setImageName
create a snapshot in the given file.
If the file exists, save it for backup.
Return true if the snapshot worked, false if it failed for some reason.
Notify dependents before and after the snapshot operation.

If setImageName is true, the name of the current image is set and
a copy of the change file is created.
usage example(s):
     ObjectMemory snapShotOn:'myimage.img' setImageName:false
     ObjectMemory snapShotOn:'myimage.img' setImageName:true

o  suffixForSnapshot
return the suffix used for snapshot files'

o  writeCrashImage
create a 'crash.img' snapshot file containing all of the current state.
Keep the current image name.
usage example(s):
     ObjectMemory writeCrashImage


Private classes:

    BinaryModuleDescriptor


ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Wed, 19 Sep 2018 12:42:52 GMT