"

 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

		BackgroundCollectMaximumInterval'

	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.

        JustInTimeCompilationEnabled    boolean - enables/disables JIT-compilation of

                                        bytecode to machine code.

                                        (this has nothing to do with stc-compilation)

        Dependents                      keep my dependents locally (its faster) for

                                        all those registries

        LowSpaceSemaphore               a semaphore signalled whenever the system is

                                        running in low memory (i.e. the memory manager

                                        ran into memory shortage and feels that it

                                        may soon no longer be able to grant allocation requests).

                                        You can have a process waiting on this semaphore

                                        which starts to remove (i.e. nil-out) objects

                                        or preform other cleanup actions.

        AllocationFailureSignal         signal raised when a new fails (see Behavior)

                                        When this signal is raised, the memory manager

                                        is really in trouble (i.e. above low-mem feelings 

                                        were correct)

        MallocFailureSignal             signal raised when a malloc fails

                                        mallocs are used internally in the VM and/or

                                        by some classes (ExternalBytes)

        BackgroundCollectProcess        created by startBackgroundCollectorAt:

        BackgroundFinalizationProcess   created by startBackgroundFinalizationAt:

        BackgroundCollectMaximumInterval

                                        number of seconds after which an incremental background

                                        collection is started - regardless of the allocation

                                        rate or freeSpace situation. If nil, IGC is only done

                                        when the space situation makes it feasable.

                                        Can be set to (say) 3600, to have the memory cleaned

                                        at least once an hour.

        FinalizationSemaphore           triggered by the VM, when any weak pointer is

                                        lost. Been waited upon by the backgroundFinalizer.

        ImageName                       name of the current image (or nil)

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

    Big caches help - i.e. a 1Mb cache machine performs better than a 256k cache machine.

    Also, a good memory interface (small number of wait cycles and burst modes)

    help a lot.

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

    by an inplace compress algorithm.

    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 either done by a 1-pass semispace copy algorithm, or

    a 2pass inplace compress - depending on the setting of the compress limit.

    The 1pass algorithm copies all live objects into a newly allocated

    area, and frees the previous memory afterwards (a baker style copying collector).

    The 2pass algorithm moves objects inPlace, and adjusts the pointers in

    a second pass.

    The 1pass algorithm requires twice the amount of memory (virtually) and is

    slightly faster, if enough real memory is available.

    In memory limited systems, the 2pass algorithm generally performs better,

    since it is less affected by paging.

    To honor this situation, the compressLimit should be set to enforce the

    2-pass algorithm if the oldSpace size exceeds a certain threshold.

    We recommend setting the compressLimit to roughly 1/4th of the physical

    memory size of the machine, if other programs are to run beside ST/X

    (i.e. an XServer, some xterms etc.).

    If ST/X is running almost alone (i.e. using an XTerminal), the compressLimit

    can be set to 1/3rd of the physical memory.

    This is only a rough estimate - you may want to play around with this

    parameter, to find a value which avoids paging due to a 1pass compress.

    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 algorithms are 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 either be started as a high priority

    process, which gives up the cpu (by delaying on the time) after every IGC step,

    or it can be gicen a dynamic priority, where the max-prio is above UserSchedulingPriority.

    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 (currently) used for 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;

    Notice, that the defaults below are those of the VM and or ObjectMemory class.

    These may already be changed by a smalltalk.rc or private.rc startup file.

            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

        2pass oldSpace

        compressor      enabled     -Msingle            -

        limit for 1pass

        old-compress     8000k      -                   oldSpaceCompressLimit:

        chunk size

        to increase

        oldSpace          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

        maximum time

        interval between

        IGC's                -      -                   BackgroundCollectMaximumInterval

        JIT codeCache

        size            unlimited   -                   dynamicCodeLimit:

        new JIT code

        trigger for IGC   none      -                   dynamicCodeGCTrigger:

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