Smalltalk/X Webserver

Documentation of class 'ObjectMemory':

Class: ObjectMemory

Inheritance
Description
Class protocol
Private classes

Inheritance:

   Object
   |
   +--ObjectMemory

Package:: stx:libbasic

Category:: System-Support

Version:: rev: 1.338 date: 2019/07/16 14:41:31; 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.

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.

infoPrinting

return true, if various informational printouts in the VM
are turned on, false of off.

usage example(s):

     ObjectMemory infoPrinting

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.

initTrace: aBoolean

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

VM unwind protect support

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:
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

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.
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.
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.
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.
unsetAllTraps: remove all access traps
unsetTrapFor: anObject: remove any access trap for anObject.

cache management

debugBreakPoint

debugBreakPoint3

flushCaches

flush method and inline caches for all classes

flushCachesFor: aClass

flush method and inline caches for aClass

flushCachesForSelector: aSelector

flush method and inline caches for aSelector

flushCachesForSelector: aSelector numArgs: numArgs

flush method and inline caches for aSelector

flushInlineCaches

flush all inlinecaches

flushInlineCachesFor: aClass withArgs: nargs

flush inlinecaches for calls to aClass with nargs arguments

flushInlineCachesForClass: aClass

flush inlinecaches for calls to aClass.

flushInlineCachesForSelector: aSelector

flush inlinecaches for sends of aSelector

flushInlineCachesWithArgs: nargs

flush inlinecaches for calls with nargs arguments

flushMethodCache

flush the method cache

flushMethodCacheFor: aClass

flush the method cache for sends to aClass

flushMethodCacheForSelector: aSelector

flush the method cache for sends of aSelector

ilcMisses: newValue

ilcMissesTrace: bool

incrementSnapshotID

obsolete - do not use

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

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

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

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

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

displayRefChainToAny: aCollection

displayRefChainToAny: aCollection limitNumberOfSearchedReferences: limitOrNil

consider this a kludge:

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)

dumpSender

dump my senders context

usage example(s):

     ObjectMemory dumpSender

flagsOf: anObject

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

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

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.

refChainFrom: start to: anObject inRefSets: levels startingAt: index

(self refNameFor:anObject in:start)

refChainsFrom: start to: anObject inRefSets: levels startingAt: index

(self refNameFor:anObject in:start)

refNameFor: anObject in: referent

for our convenience - if it's a nameSpace, cut off Smalltalk.

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

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

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

printPolyCaches

dump poly caches.
WARNING: this method is for debugging only
it will be removed without notice

usage example(s):

     ObjectMemory printPolyCaches

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

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

printSymbols

dump the internal symbol table.
WARNING: this method is for debugging only
it will be removed without notice

usage example(s):

     ObjectMemory printSymbols

sendConsistencyCheckPrimitivesOn

turns consistency check after every send to primitive code.

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

sendConsistencyChecksOn

turns consistency check after every message sends on.
This will slow down the system to make it almost unusable,
so this should only be enabled around small pieces of code
to find errors in primitive code (eg. missing STOREs).

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

usage example(s):

     ObjectMemory sendConsistencyChecksOn
     ObjectMemory sendTraceOff

sendTraceAndConsistencyChecksOn

turns tracing of message sends on
AND performs memory consistency checks after every message
send.
This will slow down the system to make it almost unusable,
so this should only be enabled around small pieces of code
to find errors in primitive code (eg. missing STOREs).

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

usage example(s):

     ObjectMemory sendTraceAndConsistencyChecksOn
     ObjectMemory sendTraceOff

sendTraceOff

turns tracing of message sends off.
WARNING: this method is for debugging only
it may be removed without notice

usage example(s):

     ObjectMemory sendTraceOn
     ObjectMemory sendTraceOff

sendTraceOn

backward compatibility

usage example(s):

     ObjectMemory sendTraceOnForThread
     ObjectMemory sendTraceOff

sendTraceOnForAll

turns tracing of message sends on for all threads.
WARNING: this method is for debugging only
it may be removed without notice

sendTraceOnForThread

turns tracing of message sends on for the current thread.
WARNING: this method is for debugging only
it may be removed without notice

dependents access

dependents: return the collection of my dependents
dependents: aCollection: set the dependents collection
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

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.

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.

allObjectsIncludingContextsDo: aBlock

like allObjectsDo, but also walks over all contexts
of living processes

allOldObjectsDo: aBlock

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

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

backgroundCollectProcess

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

backgroundCollectorRunning

return true, if a backgroundCollector is running

usage example(s):

     ObjectMemory backgroundCollectorRunning

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.
     ]).

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

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

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.

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.

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

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

nonVerboseGarbageCollect

perform a compressing garbage collect or fallback to non-compressing collect,
if required.

usage example(s):

     ObjectMemory nonVerboseGarbageCollect

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

resumeBackgroundCollector

resume the background collector process

usage example(s):

     ObjectMemory resumeBackgroundCollector

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

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.

stopBackgroundCollector

stop the background collector

usage example(s):

     ObjectMemory stopBackgroundCollector

suspendBackgroundCollector

suspend the background collector process.
Answer true, if the background collector was running before

usage example(s):

     ObjectMemory suspendBackgroundCollector.
     ObjectMemory resumeBackgroundCollector

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

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

verboseGarbageCollect

perform a compressing garbage collect and show some informational
output on the Transcript

usage example(s):

     ObjectMemory verboseGarbageCollect

garbage collector control

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

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

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

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.

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.

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.

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

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

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

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

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.

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.

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

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.

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

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.

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

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'

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

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.

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.

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.

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

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

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

moreOldSpaceIfUseful

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

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

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

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

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

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

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

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

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.

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.

turnGarbageCollectorOn

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

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

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

initialization

initialize: initialize the class

interrupt handler access

childSignalInterruptHandler: return the handler for UNIX-death-of-a-childprocess-signal interrupts
childSignalInterruptHandler: aHandler: set the handler for UNIX-death-of-a-childprocess-signal interrupts
customInterruptHandler: return the handler for custom interrupts
customInterruptHandler: aHandler: set the handler for custom interrupts
disposeInterruptHandler: return the handler for object disposal interrupts
disposeInterruptHandler: aHandler: set the handler for object disposal interrupts
errorInterruptHandler: return the handler for display error interrupts
errorInterruptHandler: aHandler: set the handler for display error interrupts
exceptionInterruptHandler: return the handler for floating point exception interrupts
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.
ioInterruptHandler: return the handler for I/O available signal interrupts (SIGIO/SIGPOLL)
ioInterruptHandler: aHandler: set the handler for I/O available signal interrupts (SIGIO/SIGPOLL)
recursionInterruptHandler: return the handler for recursion/stack overflow interrupts
recursionInterruptHandler: aHandler: set the handler for recursion/stack overflow interrupts
registerErrorInterruptHandler: aHandler forID: errorIDSymbol: register a handler
registeredErrorInterruptHandlers: return registered handlers
signalInterruptHandler: return the handler for UNIX-signal interrupts
signalInterruptHandler: aHandler: set the handler for UNIX-signal interrupts
spyInterruptHandler: return the handler for spy-timer interrupts
spyInterruptHandler: aHandler: set the handler for spy-timer interrupts
stepInterruptHandler: return the handler for single step interrupts
stepInterruptHandler: aHandler: set the handler for single step interrupts
timerInterruptHandler: return the handler for timer interrupts
timerInterruptHandler: aHandler: set the handler for timer interrupts
userInterruptHandler: return the handler for CNTL-C interrupt handling
userInterruptHandler: aHandler: set the handler for CNTL-C interrupt handling

interrupt statistics

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.

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

interruptLatencyMonitor

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

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.

maxInterruptLatency

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

resetMaxInterruptLatency

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

just in time compilation

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

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

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

compiledCodeCounter

return the number of additional code-bytes which
were generated since the counter was last reset

usage example(s):

     ObjectMemory compiledCodeCounter

compiledCodeSpaceUsed

return the actual number of bytes used for compiled code

usage example(s):

     ObjectMemory compiledCodeSpaceUsed

fullSingleStepSupport

return the setting of the full single step support flag

usage example(s):

     ObjectMemory fullSingleStepSupport

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

getCompiledCodeLimit

get the codeLimit from the VM

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

javaJustInTimeCompilation

return the value of the java-just-in-time-compilation flag

usage example(s):

     ObjectMemory javaJustInTimeCompilation

javaJustInTimeCompilation: aBoolean

enable/disable java just-in-time-compilation.

usage example(s):

     ObjectMemory javaJustInTimeCompilation:true
     ObjectMemory javaJustInTimeCompilation:false

javaNativeCodeOptimization

return the value of the java-native-code-optimization flag

usage example(s):

     ObjectMemory javaNativeCodeOptimization

javaNativeCodeOptimization: aBoolean

enable/disable java native code-optimization.

usage example(s):

     ObjectMemory javaNativeCodeOptimization:true
     ObjectMemory javaNativeCodeOptimization:false

justInTimeCompilation

return the value of the just-in-time-compilation flag

usage example(s):

     ObjectMemory justInTimeCompilation

justInTimeCompilation: aBoolean

enable/disable just-in-time-compilation.

usage example(s):

     ObjectMemory justInTimeCompilation:true
     ObjectMemory justInTimeCompilation:false

optimizeContexts

return the setting of the optimize contexts flag

usage example(s):

     ObjectMemory optimizeContexts

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

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.

resetCompiledCodeCounter

reset the counter of additional code-bytes

usage example(s):

     ObjectMemory resetCompiledCodeCounter

setCompiledCodeLimit: newLimit

set the VM's limit

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

allocationFailed

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

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.

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

allChangedShadowObjectsDo: aBlock

evaluate the argument, aBlock for all known shadow objects which have
lost a pointer recently.

backgroundFinalizationProcess

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

disposeInterrupt

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

finalize

tell all weak objects that something happened.

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

stopBackgroundFinalization

stop the background finalizer

usage example(s):

     ObjectMemory stopBackgroundFinalization

physical memory access

collectedOldSpacePagesDo: aBlock: evaluates aBlock for all pages in the prev. oldSpace, passing
the pages address as argument.
For internal & debugging use only.
newSpacePagesDo: aBlock: evaluates aBlock for all pages in the newSpace, passing
the pages address as argument.
For internal & debugging use only.
oldSpacePagesDo: aBlock: evaluates aBlock for all pages in the oldSpace, passing
the pages address as argument.
For internal & debugging use only.
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

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

collectObjectsWhich: aBlock

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

collectedOldSpaceAddress

self collectedOldSpaceAddress

fixSpaceSize

return the total size of the fix space.

usage example(s):

     ObjectMemory fixSpaceSize

fixSpaceUsed

return the number of bytes allocated for old objects in fix space.

usage example(s):

     ObjectMemory fixSpaceUsed

freeListSpace

return the number of bytes in the free lists.
(which is included in oldSpaceUsed)

usage example(s):

     ObjectMemory freeListSpace

freeSpace

return the number of bytes in the compact free area.
(oldSpaceUsed + freeSpaceSize = oldSpaceSize)

usage example(s):

     ObjectMemory freeSpace

garbageCollectCount

return the number of compressing collects that occurred since startup

usage example(s):

     ObjectMemory garbageCollectCount

incrementalGCCount

return the number of incremental collects that occurred since startup

usage example(s):

     ObjectMemory incrementalGCCount

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

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

isSchteamEngine

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

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

lifoRememberedSet

return the lifoRemSet.
This is pure VM debugging and will vanish without notice.

usage example(s):

     ObjectMemory lifoRememberedSet

lifoRememberedSetSize

return the size of the lifoRemSet.
This is a VM debugging interface and may vanish without notice.

usage example(s):

     ObjectMemory lifoRememberedSetSize

mallocAllocated

return the number of bytes allocated (and used) by malloc.

usage example(s):

     ObjectMemory mallocAllocated

mallocTotal

return the number of bytes reserved by malloc (may not have been used yet).

usage example(s):

     ObjectMemory mallocTotal

markAndSweepCount

return the number of mark&sweep collects that occurred since startup

usage example(s):

     ObjectMemory markAndSweepCount

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

minScavengeReclamation

returns the number of bytes replaimed by the least effective scavenge.
For statistic only - this may vanish.

usage example(s):

     ObjectMemory minScavengeReclamation

newSpaceSize

return the total size of the new space - this is usually fix

usage example(s):

     ObjectMemory newSpaceSize

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

numberOfObjects

return the number of objects in the system.

usage example(s):

     ObjectMemory numberOfObjects

numberOfWeakObjects

return the number of weak objects in the system

usage example(s):

     ObjectMemory numberOfWeakObjects

oldSpaceAddress

self oldSpaceAddress

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

oldSpaceSize

return the total size of the old space. - may grow slowly

usage example(s):

     ObjectMemory oldSpaceSize

oldSpaceUsed

return the number of bytes allocated for old objects.
(This includes the free lists)

usage example(s):

     ObjectMemory oldSpaceUsed

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

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

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

scavengeCount

return the number of scavenges that occurred since startup

usage example(s):

     ObjectMemory scavengeCount

symSpaceSize

return the total size of the sym space.

usage example(s):

     ObjectMemory symSpaceSize

symSpaceUsed

return the number of bytes allocated for old objects in sym space.

usage example(s):

     ObjectMemory symSpaceUsed

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

vmSymbols

return a collection of symbols used by the VM

whoReferences: anObject

return a collection of objects referencing the argument, anObject

usage example(s):

     (ObjectMemory whoReferences:Transcript) printCR

whoReferencesAny: aCollection

return a collection of objects referencing any object from
the argument, aCollection

usage example(s):

     ObjectMemory whoReferencesAny:(Array with:Transcript with:Smalltalk)

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

whoReferencesInstancesOf: aClass

return a collection of objects refering to instances
of the argument, aClass

usage example(s):

     (ObjectMemory whoReferencesInstancesOf:SystemBrowser) printCR

semaphore access

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

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

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.
     ]

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

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.

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

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

directoryForImageAndChangeFile

the current directory is not a good idea, if stx is started via a desktop manager

usage example(s):

     self directoryForImageAndChangeFile

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

imageName

return the filename of the current image, or nil
if not running from an image.

usage example(s):

     ObjectMemory imageName

imageSaveTime

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

initChangeFilename

make the changeFilePath an absolute one,

usage example(s):

     self initChangeFilename

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

nameForChanges: aFilename

set the name of the file where changes are stored into.

usage example(s):

     ObjectMemory nameForChanges:'myChanges'

nameForChangesLocal

return a reasonable filename to store the changes into.

nameForCrashImage

ObjectMemory nameForCrashImage

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

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'

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

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.

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.

snapShot

create a snapshot file containing all of the current state.

usage example(s):

     ObjectMemory snapShot

snapShotOn: aFileName

create a snapshot file containing all of the current state.

usage example(s):

     ObjectMemory snapShotOn:'myimage.img'

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

suffixForSnapshot

return the suffix used for snapshot files'

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.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Sat, 20 Apr 2024 05:27:59 GMT

Smalltalk/X Webserver

Documentation of class 'ObjectMemory':

Class: ObjectMemory

Inheritance:

Description:

Class protocol:

Private classes: