"

 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

			   AllocationFailureSignal LowSpaceSemaphore

			   IncrementalGCLimit FreeSpaceGCLimit FreeSpaceGCAmount 

			   BackgroundCollectProcess BackgroundFinalizationProcess

			   FinalizationSemaphore

			   Dependents

			   ImageName'

       poolDictionaries:''

       category:'System-Support'

!

ObjectMemory comment:'

COPYRIGHT (c) 1992 by Claus Gittinger

	     All Rights Reserved

'!

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

    in previous versions this stuff used to be in the Smalltalk class.

    It has been separated for better overall structure.

    There are no instances of ObjectMemory - all is done in class methods.

    Many methods here are for debuging purposes only, and not standard.

    Do not depend on them being there - some may vanish ...

    (especially those, that depend on a specific GC implementation)

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

    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)

	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:

"

!

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, special care is needed, since it is not defined, which process gets

    the interrupt and will do the processing.

    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)

"

!

garbageCollection

"

    Currently, Smalltalk/X uses a two-level memory hierachy.

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

    This newSpace is cleaned by a 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 unreferenced

    objects as garbage behind. After this copying, these two semispaces exchange their

    roles - i.e. 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'.

    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. To honor this 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.

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

    longer than a few milliseconds. 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).

    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 will turn 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

    for. This may prevent the system from running into a GC pause when 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)

  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.

    Hint 4:

      If you run in too small of physical memory, the incremental GC may have a

      bad effect on your working set: since it touches pages (which may otherwise

      not be needed at the moment, the operating system is forced to steal other

      (possibly more useful) pages from your set of incore pages.

      You may get better performance, if you turn off the incremental GC while

      processing a big data structure.

    Warning: many of the methods found here are not standard and may not even be available in

    future versions of ST/X. Use them only in very special situations or experiments.

    Let me know about additional special features you think are useful, and about

    special features you are using - this provides the feedback required to decide

    which methods are to be removed or kept or enhanced in future versions.

"

! !

!ObjectMemory class methodsFor:'initialization'!

initialize

    "initialize the class"

    AllocationFailureSignal isNil ifTrue:[

	AllocationFailureSignal := ErrorSignal newSignalMayProceed:true.

	AllocationFailureSignal nameClass:self message:#allocationFailureSignal.

	AllocationFailureSignal notifierString:'allocation failure'.

	LowSpaceSemaphore := Semaphore new.

    ].

    DisposeInterruptHandler := self.

    IncrementalGCLimit := 500000.

    FreeSpaceGCLimit := FreeSpaceGCAmount := nil.

    MemoryInterruptHandler := self

! !

!ObjectMemory class methodsFor:'Signal constants'!

allocationFailureSignal

    "return the signal raised when an object allocation failed"

    ^ AllocationFailureSignal

! !

!ObjectMemory class methodsFor:'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."

    ^ LowSpaceSemaphore

! !

!ObjectMemory class methodsFor:'dependents access'!

dependents

    "return the colleciton of my dependents"

    ^ Dependents

!

dependents:aCollection

    "set the dependents collection"

    Dependents := aCollection

!

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

    |deps|

    deps := Dependents.

    deps notNil ifTrue:[

	deps do:[:each |