"

 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 ImageSaveTime ChangeFileName MaxInterruptLatency

		InterruptLatencyGoal VMSelectors DynamicCodeGCTrigger

		DynamicCodeLimit JustInTimeCompilationEnabled'

	poolDictionaries:''

	category:'System-Support'

!

Object subclass:#BinaryModuleDescriptor

	instanceVariableNames:'name type id dynamic classNames pathName libraryName timeStamp'

	classVariableNames:''

	poolDictionaries:''

	privateIn:ObjectMemory

!

!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 (you wont really see a difference in speed after the flush, anyway).

"

!

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

	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.

        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 meomory manager

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

                                        correct)

        BackgroundCollectProcess        created by startBackgroundCollectorAt:

        BackgroundFinalizationProcess   created by startBackgroundFinalizationAt:

        ImageName                       name of the current image (or nil)

        ImageSaveTime   <AbsoluteTime>  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.

    [author:]

        Claus Gittinger

"

!

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 40ms 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 40ms for a full 400k newSpace 

    (i.e. all objects survive) on a 486/50 - this only drops to some 20-30ms on a P5.

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

    the size of the newSpace - either via a command 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.

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

     memory, the compress is actually 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 version 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 is started by the system; however,

    the standard startup script starts a low prio background incremental GC process.

    You have to edit your startup files to change this. 

    A suggested configuration (used by the author and the default) 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.