"

 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'!

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.

"

!

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.

"

!

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.

"

!

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

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

    Interestingly, 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

	collections are provided, which store their values directly inside (instead

	of a reference to the object). A FloatArray consisting of 1 million floats

	requires about 4mb of memory, while an Array of Floats requires 4mb for the

	references to the floats, PLUS 20Mb for the floats themself.

      - check if you really need fast access to all of these objects; you may

	try to only keep some subset in memory, and use binary storage or

	(if this is too slow) optimized store/retrieve methods and keep the bigger

	part in a file. 

	(How about a DiskArray class, which does this transparently ?

	 See the FileText class for some ideas and something to start with ...)

    Hint / Example 1: 

      you are about to allocate a huge data structure, which is known to

      survive long. In this case, it is better to have these objects move into the

      oldspace sooner, to avoid the copying overhead during scavenges.

      To do this, you can call ObjectMemory>>tenure after allocation, which

      forces all new-objects immediately into the oldspace. 

      Make certain, that not to many (ideally no) short-living objects are in the

      newspace when doing this.

      Another alternative is to tell the system that all allocation should be

      done directly in the oldspace. This completely avoids the scavenging overhead

      for these objects. To do so, use ObjectMemory>>turnGarbageCollectorOff

      before the allocation, and ObjectMemory>>turnGarbageCollectorOn afterwards.

      Keep in mind, that do-loops may allocate block-objects and other temporaries,

      so there is a danger of making things worse due to having all those temporaries

      in the oldspace afterwards. (which is not a fatal situation, but will

      force the system to do an oldspace collect earlier, which may not be your

      intention).

   Hint / Example 2:

      you know in advance, that a certain (big) amount of memory will be needed.

      For example, the fileBrowser wants to show a huge file in its text-view.

      In this case, it is better to tell the memory system in advance, how much

      memory will be needed, since otherwise many compresses and reallocations will

      occur (the memory system will allocate additional memory in chunks of smaller

      256k pieces, if a compress failes. Thus, if you are going to allocate (say) 1Mb of 

      strings, it will perform 5 compressing GC's).

      This is done using ObjectMemory>>moreOldSpace: or ObjectMemory announceSpaceNeed:.

      In the above example, you would do 'ObjectMemory announceSpaceNeed:500000', which 

      avoids those annoying 5 compressing GC's.

      BTW: if you have other smalltalk processes (threads) running which should not be

      paused if possible, it is better to use #announceSpaceNeed. This tries to avoid 

      pausing in other processes and sometimes succeeds, while moreOldSpace will always 

      block the whole system for a while. However, there is no 'no-pause' guarantee.

      The amount of automatic increase (in case the oldSpace becomes full) is 256k by

      default. This number can be changed with ObjectMemory>>oldSpaceIncrement:.

    Hint / Example3:

      There are rare cases, when an explicit GC makes a difference: since

      object finalization is done at GC time, objects which keep operatingSystem

      resources may be finalized late. This is normally no problem, except if

      the system is running out of resources. For example, allocating new colors

      may fail if many colors have already been allocated in the past - even

      though these colors are actually free. The Depth8Image calls for an

      explicit GC, whenever it fails to allocate a color for a bitmap, to force

      finalization of free, but not yet finalized colors.