"

 COPYRIGHT (c) 1992 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

Object subclass:#ObjectMemory

       instanceVariableNames:''

       classVariableNames:'InternalErrorHandler UserInterruptHandler TimerInterruptHandler

			   SpyInterruptHandler StepInterruptHandler ExceptionInterruptHandler

			   ErrorInterruptHandler MemoryInterruptHandler SignalInterruptHandler

			   ChildSignalInterruptHandler DisposeInterruptHandler

			   RecursionInterruptHandler IOInterruptHandler

			   CustomInterruptHandler

			   RegisteredErrorInterruptHandlers

			   InterruptLatencyMonitor

			   AllocationFailureSignal MallocFailureSignal LowSpaceSemaphore

			   IncrementalGCLimit FreeSpaceGCLimit FreeSpaceGCAmount 

			   BackgroundCollectProcess BackgroundFinalizationProcess

			   FinalizationSemaphore

			   Dependents

			   ImageName ChangeFileName

			   MaxInterruptLatency InterruptLatencyGoal'

       poolDictionaries:''

       category:'System-Support'

!

!ObjectMemory class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1992 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

version

!

documentation

"

    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

	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 be no longer 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 meomory manager

					is really in trouble (i.e. above feelings where

					correct)

	BackgroundCollectProcess        created by startBackgroundCollectorAt:

	BackgroundFinalizationProcess   created by startBackgroundFinalizationAt:

    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.

"

!

caching

"

    The system uses various caches to speed up method-lookup.

    Currently, there is a three-level cache hierarchy:

	inline-cache            keeps the target of the last send at the caller-

				side (i.e. every send goes through its private 

				1-slot inline-cache, where the address of the last

				called function at this call location is kept.)

	polymorph-inline-cache  keeps a limited list of all targets ever reached 

				at this call location. The list is automatically 

				flushed if it grows too large, or the overall number

				of poly-chache entries exceeds a limit.

	method-lookup-cache     a global cache. Hashes on class-selector pairs,

				returning the target method.

    Whenever methods are added or removed from the system, or the inheritance 

    hierarchy changes, some or all caches have to be flushed.

    The flushXXX methods perform the task of flushing various caches.

    All standard methods in Behavior call for cache flushing, when things change;

    however, if you use the low level access methods in Behavior

    (for example: #setSuperclass:) special care has to be taken.

    In some situations, not all caches need flushing, for example a change

    in an interpreted method (currently) needs no flushing of the inline caches.

    Also, flushing can be limited to entries for a specific class for most changes.

    To be 'on the brigth side of live', use ObjectMemory>>flushCaches (which

    flushes all of them), when in doubt of which caches should be flushed. 

    It is better flush too much - otherwise you may end up in a wrong method after 

    a send.

"

!

interrupts

"

    Handling of interrupts (i.e. unix-signals) is done via handler objects, which

    get a #XXXInterrupt-message sent. This is more flexible than (say) signalling

    a semaphore, since the handler-object may do anything to react on the signal

    (of course, it can also signal a semaphore to emulate the above behavior).

    Another reason for having handler objects is that they allow interrupt handling

    without any context switch, for high speed interrupt response.

    However, if you do this, special care is needed, since it is not defined, 

    which process gets the interrupt and will do the processing (therefore,

    the default setup installs handlers which simply signal a semaphore and

    continue the running process).

    Typically, the handlers are set during early initialization of the system

    by sending 'ObjectMemory XXXInterruptHandler:aHandler' and not changed later.

    (see Smalltalk>>initialize or ProcessorScheduler>>initialize).

    To setup your own handler, create some object which responds to #xxxInterrupt,

    and make it the handler using the above method.

    Interrupt messages sent to handlers are:

	internalError:<someString>      - internal interpreter/GC errors

	userInterrupt                   - ^C interrupt

	customInterrupt                 - custom interrupt

	ioInterrupt                     - SIGIO interrupt

	timerInterrupt                  - alarm timer (SIGALRM)

	errorInterrupt:<id>             - errors from other primitives/subsystems

					  (DisplayError)

	spyInterrupt                    - spy timer interrupt (SIGVTALARM)

	stepInterrupt                   - single step interrupt

	disposeInterrupt                - finalization required

	recursionInterrupt              - recursion (stack) overflow

	memoryInterrupt                 - soon running out of memory

	fpExceptionInterrupt            - floating point exception (SIGFPE)

	childSignalInterrupt            - death of a child process (SIGCHILD)

	signalInterrupt:<number>        - unix signal (if other than above signals)

    To avoid frustration in case of badly set handlers, these messages

    are also implemented in the Object class - thus anything can be defined

    as interrupt handler. However, the VM will not send any

    interrupt message, if the corresonding handler object is nil

    (which means that nil is a bad choice, if you are interrested in the event).

    Interrupt processing is not immediately after the event arrives: there

    are certain ``save-places'' at which this handling is performed

    (message send, method return and loop-heads).

    If not explicitely enabled, primitive code is never interrupted.

    Interrupts may be disabled (OperatingSystem blockInterrupts) and reenabled

    (unblockInterrupts) to allow for critical data to be manipulated.

    Every process has its own interrupt-enable state which is switched

    when processes switch control (i.e. you cannot block interrupts across

    a suspend, delay etc.). However, the state will be restored after a resume.

"

!

garbageCollection

"

    Currently, Smalltalk/X uses a two-level memory hierachy (actually, there

    are more memory regions used for stack, permanent objects, symbols etc.

    but for the following discussion, these are not of interrest).

  newSpace:

    Objects are created in a so-called newSpace, which is relatively small.

    This newSpace is cleaned by a so called ``scavenge''-operation, whenever 

    becoming full. Scavenging means, that all still-live objects (i.e. referenced

    by some other) are copied over to another memory area, leaving all unreachable

    objects as garbage behind. Thus, the newSpace actually consists of two semispaces,

    of whih only one is active - the other being used only while objects are

    copied.

    After this copying, these two semispaces exchange their roles - i.e. reachable

    objects are copied ping-pong like between these semispaces.

    Once an object survives enough of these copying operations, the next scavenge 

    will move it into the so called oldSpace, which is much larger, and not

    processed by the scavenger. 

    This movement of an object from newSpace to oldSpace is called ``tenure''.

    (this avoids objects being copied around forever).

    Once tenured, an object is no longer contained in the newSpace, and

    thus ceases to create any scavenging overhead after that.

    Scavenging occurs automatically, and is usually done fast enough to go 

    unnoticed (typically, it takes some 5 to 50ms to perform a scavenge, 

    depending on how many live objects are in the newspace).

    Interrestingly, the scavenger performs better, if many garbage objects

    are to be reclaimed, since less object-copying has to be done. Therefore,

    the best-case scavenge time is almost zero, if there is only garbage in

    the newSpace. In contrast, the worst-case is when all newSpace objects are still

    living. Thus, from a newSpace collectors viewPoint, it makes sense to get

    objects out of the way as fast as possible. However the oldSpace is

    collected much less frequently and the cost to reclaim an oldspace object

    is much higher (actually, the cost to reclaim a newspace object is zero -

    its the survival of objects which we have to pay for).

    Therefore, from an oldSpace collectors point of view, its preferable to

    keep objects in the newSpace as long as possible.

    To honor this conflicting situation, the system uses an adaptive tenure-count,

    which adjusts the number of scavenges required for tenure (the so called 

    'tenureAge') according to the fill-grade of the newSpace.

    If the newSpace is relatively empty, it tries to keep objects longer there.

    The controlling parameters of the tenure age can be changed dynamically,

    detailed information is available upon request.

    The exact speed of the scavenger depends mostly on the speed of your memory

    interface (and, since most of todays memories have access times in the order

    of 50-100ns, the raw CPU speed does not correlate linear with the GC speed).

    Measurements give roughly 40-70ms for a full 400k newSpace 

    (i.e. all objects survive).

    The upper bounds of the scavenge blocking time can be controlled by changing

    the size of the newSpace - ether via acommand line argument, or even dynamically

    by Objectmemory>>newSpaceSize:. Smaller sizes lead to shorter blocking periods,

    but greater absolute GC overhead. The default (400k) seems to be a good compromise.

    (if you are not happy with it, try playing around with the settings)

  oldSpace:

    To reclaim oldspace, the system uses three algorithms: mark&sweep, a copying

    (and compressing) baker-type collector and an incremental mark&sweep.

    The mark&sweep runs whenever the oldspace becomes full, putting dead objects

    onto a free list. If a memory request cannot be served from this freelist,

    and the total size of objects on the freelist exceeds a threshold, the system

    will compress the oldspace to make the free-space into one big area.

    This compress is done by copying all live objects into a newly allocated

    area, and freeing the previous memory afterwards (baker collector).

    Since a compressing oldspace collect leads to a noticable pause of the system,

    the memory manager tries hard to avoid oldspace compression.

    (actually, if enough real memory is available to hold both spaces in physical

     memory, the compress is pretty fast).

    The incremental mark&sweep runs in the background, whenever the system is idle

    (see ProcessorSceduler>>waitForEventOrTimeout), or alternatively as a low or high

    priority background process (see ObjectMemory>>startBackgroundCollector). 

    Like the normal mark&sweep, this incremental collector follows object references 

    and marks reachable objects on its way. However, this is done 'a few objects-at-a-time',

    to not disrupt the system noticably. Currently, there are some (theoretical) and in

    practice never occurring situations, in which the incremental GC still creates noticable

    delays. A current project is involved with this and a future versions of ST/X (ST/X-RT)

    will be available which shows deterministic worst case behavior in its GC pauses 

    (this will be provided as an additional add-on option - certainly not for free ;-).

    Currently, incremental GC blockings are in the order of 10-70ms.

    There is one catch with low priority background IGC: if there is never any idle

    time available (i.e. all processes run all the time), it would never get a chance

    to do any collection work. To handle this case, a background IGC can also be started

    as a high priority process, which gives up the cpu (by delaying on the time) after

    every IGC step. A high priority background collector will always make progress

    and eventually finish a GC cycle. However, it may have more of an influence on 

    the other processes. So, its up to you, to decide ...

    Incremental garbage collection is controlled by the variables 

    'IncrementalGCLimit', 'FreeSpaceGCLimit' and 'FreeSpaceGCAmount':

      the ProcessorScheduler will perform incremental GC steps at idle time, 

      if the total space allocated since the last full collect exceeds 

      'IncrementalGCLimit',

      or if there are less than 'FreeSpaceGCLimit' bytes available in free store.

      If after the incrementalGC, less than 'FreeSpaceGCLimi't bytes are available,

      'FreeSpaceGCAmount' more bytes are requested from the memory manager.

    The defaults are set in ObjectMemory>>initialize and can be changed in your 

    startup 'smalltalk.rc'-file. Setting them to nil turns incremental GC off.

    For example, setting 'IncrementalGCLimit' to 500000 will start the background collector

    whenever 500k bytes have been allocated - usually very seldom. Setting it to some

    small number (say 10000) will have it run very often.

    Setting 'FreeSpaceGCAmount' to (say) 1meg lets the system try to always keep

    1meg of freeSpace. If less memory is available, more oldSpace will be allocated.

    Keeping some memory in the pocket may prevent the system from running into a blocking

    GC if memory is allocated in peaks (but only, if the incremental GC can keep up with 

    allocation rate). The trigger level 'FreeSpaceGCLimit' should be below that amount;

    to avoid excessive incremental GC activity (say 1/4 if the amount).

    Having the background GC running often should not hurt the performance of your 

    smalltalk processes, since the IGC only runs at times when no ST processes are runnable. 

    (there are some short delays in event processing, since the IGC's steps may take 

    some XX ms.) 

    However, if you are not alone on your machine (i.e. a timesharing system) or 

    you have other Unix processes to run, you should not run the IGC too often, 

    since it may hurt OTHER users/unix processes.

    Since this collector only runs at idle times, even a low priority background 

    process will prevent it from doing its work. You may want to start a somewhat

    higher priority background collect (say at prio 4), which also preempts these

    background processes. (see ObjectMemory>>startBackgroundCollectorAt:).

    Beginning with 2.10.4, a third space, called symSpace has been added.

    Objects in this space are never moved or garbage collected.

    This space is used for (some) symbols only.

    Beginning with 2.10.5, a fourth space, called fixSpace has been added.

    Objects in this space are never moved or garbage collected.

    This space is used for constant objects (true, false, some basic classes etc.).

    A plan for 2.11 is to offer an arbitrary number of spaces, which can be

    attached and detached at runtime. This will allow easy share of object

    with remote systems and separating objects into a per application/package

    space. (be prepared for changes in the future and make your application

    independ of the VM internals)

  default setup:

    The following table lists some default settings and means for changing them:

	    what        default     change by           

				    command line arg    dynamically

    -----------------------------------------------------------------------

	newSpace size     400k      -Mnew nnn           newSpaceSize:nnn

	oldSpace size    3000k      -Mold nnn           moreOldSpace:

							announceSpaceNeed:

							collectGarbage

	max tenure age     29                           lockTenure:

							avoidTenure:

							(sets it to infinity)

	adaptive tenure                                 tenureParameters

	oldSpace

	compressor      enabled     -Msingle            -

	limit for

	old-compress     8000k      -                   oldSpaceCompressLimit:

	chunk size

	to increase

	oldpPace          256k      -                   oldSpaceIncrement:

	prefer moreOld

	to doing GC      false      -                   fastMoreOldSpaceAllocation:

	limit for

	above                -      -                   fastMoreOldSpaceLimit:

	keep size for        -      -                   freeSpaceGCAmount:

	IGC

	low water

	trigger for IGC      -      -                   freeSpaceGCLimit:

	allocated

	trigger for IGC   500k      -                   incrementalGCLimit

    By default, no incremental GC activity is started.

    You have to change your startup files to do this. A suggested configuration

    (used by the author) is:

	' keep 1meg in the pocket '

	ObjectMemory freeSpaceGCAmount:1000000. 

	' start incrementalGC when freespace drops below 250k '

	' or 500k of oldSpace has been allocated              '

	ObjectMemory freeSpaceGCLimit:250000.                 '

	ObjectMemory incrementalGCLimit:500000.               '

	' collect as a background process (the default is: at idle times)

	' this means that running cubes or other demo processes are suspended

	' for the collect; change the prio to below 4 if you want them to continue

	ObjectMemory startBackgroundCollectorAt:5.            '

	ObjectMemory startBackgroundFinalizationAt:5.         '

	' quickly allocate more space (i.e. avoid blocking collects)

	' up to 8meg - then start to collect if more memory is needed.

	ObjectMemory fastMoreOldSpaceLimit:8*1024*1024.       '

	ObjectMemory fastMoreOldSpaceAllocation:true.         '

  hints & tricks:

    normally, there is no need to call for an explicit garbage collection, or

    modify the default parameters.

    The memory system should adapt reasonable and provide good performance 

    for a wide range of allocation patterns (see Example3 below for an exception).

    However, there may be situations, in which hints and/or explicit

    control over allocation can speedup your programs; but please:

      - if you think you have to play around with the memory policies,

	first check your program - you may find useless allocations

	or bad uses of collections. A typical error that is made is to

	create large collections using the #, (comma) concatenation method,

	which shows square behavior, since it allocates many, many temporary

	collections. Also, watch out for #copyWith:, #add: etc.

	All of these create a new collection. Remember, that most collections

	offer methods to preallocate some space; for example, 'Set new:' creates

	an empty set, but preallocates space to avoid resizing over and over.

	An especially bad performace dog is to use #add: on fix-size collection

	objects (such as Strings or Arrays), since in addition to allocating

	lots of garbage, a #become: operation is required for EACH element

	added. NEVER use Arrays for growing/shrinking data - use OrderedCollection

	instead. (if you really need an array, use asArray afterwards)

      - if you are going to allocate huge data structures, think about

	optimizing space. For example, if you allocate a million instances of

	some object, each added instance variable makes up 4Mb of additional 

	memory need.

	Also, for Byte-valued, Integer-valued and Float like objects, special