"

 COPYRIGHT (c) 1988 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.

"

"{ Package: 'stx:libbasic' }"

nil subclass:#Object

	instanceVariableNames:''

	classVariableNames:'ErrorSignal HaltSignal MessageNotUnderstoodSignal

		UserInterruptSignal RecursionInterruptSignal

		ExceptionInterruptSignal SubscriptOutOfBoundsSignal

		IndexNotFoundSignal NonIntegerIndexSignal NotFoundSignal

		KeyNotFoundSignal ElementOutOfBoundsSignal UserNotificationSignal

		InformationSignal WarningSignal PrimitiveFailureSignal

		DeepCopyErrorSignal AbortSignal ErrorRecursion Dependencies

		InfoPrinting ActivityNotificationSignal InternalErrorSignal

		NonWeakDependencies SynchronizationSemaphores ObjectAttributes

		OSSignalInterruptSignal FinalizationLobby'

	poolDictionaries:''

	category:'Kernel-Objects'

!

!Object class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1988 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.

"

!

dependencies

"

   ST/X dependencies are slightly modified from ST-80's 

   (we think they are better ;-).

   One problem occuring very often in ST-80 is that some object

   cannot be garbage collected because some dependency is present,

   having the object as a dependent of some other object.

   In ST-80, this association remains alive (because a Dictionary

   is used to hold dependents) - even if no other references exist to

   to dependent or the dependee.

   This means, that in ST-80, a #release is mandatory in order to

   prevent memory leaks.

   We think, that this is a bad solution, since after all, exactly that

   kind of work should be performed by a garbage collector - you should not

   need to care about dependencies.

   From a philosophical point of view, why should some object depend on 

   something that the programmer considers a dead object ?

   (well - worse than that: it seems that some ST-80 code even depends on

    that behavior)

   In order to limit the trouble, ST-80 reimplemented the way dependents

   are stored in the model class - this one keeps the dependents locally,

   so these dependents go away, once the model is reclaimed.

   That may make things even more confusing: with models, no #release is

   needed, with general objects it is mandatory.

   In ST/X, dependencies are implemented using a WeakDictionary; this means,

   that once the dependee dies, the dependency association is removed automatically,

   and the dependent can be reclaimed by the garbage collector, if no other

   references exist to the dependent.

   In order to (at least) provide a mechanism for the old behavior

   (in case your application heavily depends on the ST-80 mechanism), complementary

   protocol to add nonWeak dependencies is provided 

   (see #addNonWeakDependent / #removeNonWeakDependent).

   Caveat:

      since interests are implemented using InterestConverter (which are simply

      forwarding messages), these must use the nonWeak mechanism (as done in ST-80

      automatically).

      The reason is that there are usually no direct references to the converters,

      and those would be reclaimed if stored in a weakDictionary.

      This means, that those interests MUST be removed with #retractInterest

      (which is bug-compatible to ST-80). 

      We rewrite things to provide a more convenient mechanism in the future ...

   I like to hear comments on the above - do you think its better ?

"

!

documentation

"

   Object is the superclass of most other classes. 

   (except for nil-subclasses, which inherit nothing,

    to catch any message into their #doesNotUnderstand: method)

   Protocol which is common to every object is defined here.

   Also some utility stuff (like notify) and error handling is implemented here.

   Object has no instance variables (and may not get any added). One reason is, that

   UndefinedObject and SmallInteger are also inheriting from Object - these two cannot 

   have instance variables (due to their implementation). 

   The other reason is that the runtime system (VM) knows about the layout of some built-in 

   classes (think of Class, Method, Block and also Integer or Float). 

   If you were allowed to add instance variables to Object, the VM had to be recompiled 

   (and also rewritten in some places).

   [Class variables:]

        ErrorSignal     <Signal>        Signal raised for error/error: messages

                                        also, parent of all other signals.

        HaltSignal      <Signal>        Signal raised for halt/halt: messages

        MessageNotUnderstoodSignal      Signals raised for various error conditions

        UserInterruptSignal

        RecursionInterruptSignal 

        ExceptionInterruptSignal

        SubscriptOutOfBoundsSignal 

        NonIntegerIndexSignal

        NotFoundSignal 

        KeyNotFoundSignal 

        ElementOutOfBoundsSignal

        InformationSignal

        WarningSignal

        DeepCopyErrorSignal

        InternalErrorSignal

        AbortSignal      <Signal>       Signal raised by debugger, to abort a computation

                                        BUT, the debugger will only raise it if it is handled.

                                        By handling the abortSignal, you can control where the

                                        debuggers abort-function resumes execution in case of

                                        an error.

        ErrorRecursion   <Boolean>      controls behavior when recursive errors occur (i.e. 

                                        an error while handling an error).

        Dependencies     <WeakDependencyDictionary>  

                                        keeps track of object dependencies.

        InfoPrinting     <Boolean>      controls weather informational messages 

                                        are printed.

        ActivityNotificationSignal <QuerySignal> 

                                         raised on #activityNotification:

        NonWeakDependencies <Dictionary> keeps track of object dependencies.

                                         Dependents stay alive.

        SynchronizationSemaphores <WeakIdentityDictionary>

                                         Semaphores for per-object-monitor.

    [author:]

        Claus Gittinger

"

! !

!Object class methodsFor:'initialization'!

initialize

    "called only once - initialize signals"

    ErrorSignal isNil ifTrue:[

        ErrorSignal := Error.

        HaltSignal := Exception newSignalMayProceed:true.

        HaltSignal nameClass:self message:#haltSignal.

        HaltSignal notifierString:'halt encountered'.

        MessageNotUnderstoodSignal := ErrorSignal newSignalMayProceed:true.

        MessageNotUnderstoodSignal nameClass:self message:#messageNotUnderstoodSignal.

        MessageNotUnderstoodSignal notifierString:'message not understood'.

        PrimitiveFailureSignal := ErrorSignal newSignalMayProceed:true.

        PrimitiveFailureSignal nameClass:self message:#primitiveFailureSignal.

        PrimitiveFailureSignal notifierString:'primitive failed'.

        InternalErrorSignal := ErrorSignal newSignalMayProceed:false.

        InternalErrorSignal nameClass:self message:#internalErrorSignal.

        InternalErrorSignal notifierString:'VM internal error: '.

"/        UserInterruptSignal := ErrorSignal newSignalMayProceed:true.

        UserInterruptSignal := (Signal new) mayProceed:true.

        UserInterruptSignal nameClass:self message:#userInterruptSignal.

        UserInterruptSignal notifierString:'user Interrupt'.

"/        RecursionInterruptSignal := ErrorSignal newSignalMayProceed:false.

        RecursionInterruptSignal := (Signal new) mayProceed:true.

        RecursionInterruptSignal nameClass:self message:#recursionInterruptSignal.

        RecursionInterruptSignal notifierString:'recursion limit reached'.

        ExceptionInterruptSignal := ErrorSignal newSignalMayProceed:true.

        ExceptionInterruptSignal nameClass:self message:#exceptionInterruptSignal.

        ExceptionInterruptSignal notifierString:'exception Interrupt'.

        NotFoundSignal := ErrorSignal newSignalMayProceed:true.

        NotFoundSignal nameClass:self message:#notFoundSignal.

        NotFoundSignal notifierString:'no such element'.

        IndexNotFoundSignal := NotFoundSignal newSignalMayProceed:true.

        IndexNotFoundSignal nameClass:self message:#indexNotFoundSignal.

        IndexNotFoundSignal notifierString:'bad index: '.

        SubscriptOutOfBoundsSignal := IndexNotFoundSignal newSignalMayProceed:true.

        SubscriptOutOfBoundsSignal nameClass:self message:#subscriptOutOfBoundsSignal.

        SubscriptOutOfBoundsSignal notifierString:'subscript out of bounds: '.

        ElementOutOfBoundsSignal := ErrorSignal newSignalMayProceed:false.

        ElementOutOfBoundsSignal nameClass:self message:#elementOutOfBoundsSignal.

        ElementOutOfBoundsSignal notifierString:'element not appropriate or out of bounds'.

        KeyNotFoundSignal := NotFoundSignal newSignalMayProceed:true.

        KeyNotFoundSignal nameClass:self message:#keyNotFoundSignal.

        KeyNotFoundSignal notifierString:'no such key: '.

        NonIntegerIndexSignal := IndexNotFoundSignal newSignalMayProceed:true.

        NonIntegerIndexSignal nameClass:self message:#nonIntegerIndexSignal.

        NonIntegerIndexSignal notifierString:'index must be integer'.

        UserNotificationSignal := QuerySignal new.

        UserNotificationSignal nameClass:self message:#userNotificationSignal.

        UserNotificationSignal notifierString:'user notifiaction wanted'.

        InformationSignal := UserNotificationSignal newSignalMayProceed:true.

        InformationSignal nameClass:self message:#informationSignal.

        InformationSignal notifierString:'information'.

        WarningSignal := UserNotificationSignal newSignalMayProceed:true.

        WarningSignal nameClass:self message:#warningSignal.

        WarningSignal notifierString:'warning'.

        ActivityNotificationSignal := UserNotificationSignal newSignalMayProceed:true.

        ActivityNotificationSignal nameClass:self message:#activityNotificationSignal.

        ActivityNotificationSignal notifierString:'activity'.

        DeepCopyErrorSignal := ErrorSignal newSignalMayProceed:true.

        DeepCopyErrorSignal nameClass:self message:#deepCopyErrorSignal.

        DeepCopyErrorSignal notifierString:'object cannot be deepCopy-ed'.

        "

         AbortSignal is not a child of ErrorSignal -

         this would complicate abort from within a signal handler

        "

        AbortSignal := Signal genericSignal newSignalMayProceed:true.

        AbortSignal nameClass:self message:#abortSignal.

        AbortSignal notifierString:'unhandled abort signal'.

        "

         OSSignalInterruptSignal is not a child of ErrorSignal -

         it requires explicit catching.

         If unhandled, a debugger is entered.

        "

        OSSignalInterruptSignal := Signal genericSignal newSignalMayProceed:true.

        OSSignalInterruptSignal nameClass:self message:#osSignalInterruptSignal.

        OSSignalInterruptSignal notifierString:'OS signal interrupt'.

        ObjectAttributes isNil ifTrue:[

            ObjectAttributes := WeakIdentityDictionary new.

        ].

        Dependencies isNil ifTrue:[

            Dependencies := WeakDependencyDictionary new.

        ].

        NonWeakDependencies isNil ifTrue:[

            NonWeakDependencies := IdentityDictionary new.

        ].

        SynchronizationSemaphores isNil ifTrue:[

            SynchronizationSemaphores := WeakIdentityDictionary new.

        ].

    ].

    FinalizationLobby isNil ifTrue:[

        FinalizationLobby := Registry new.

    ].

    "/ initialize InfoPrinting to the VM's infoPrint setting

    "/ (which can be turned off via a command line argument)

    InfoPrinting := ObjectMemory infoPrinting.

    "Object initialize"

    "Modified: / 22.1.1998 / 21:23:40 / av"

    "Modified: / 3.2.1998 / 18:55:09 / cg"

    "Modified: / 4.8.1999 / 08:54:06 / stefan"

! !

!Object class methodsFor:'Compatibility - ST80'!

rootError

    "return the signal used for error/error: - handling.

     Same as errorSignal for ST80 compatibility."

    ^ ErrorSignal

    "Created: / 15.1.1998 / 23:47:05 / stefan"

! !

!Object class methodsFor:'Signal constants'!

abortSignal 

    "return the signal used to abort user actions. This signal is only

     raised if caught (by the debugger), and will lead way out of the

     currently active doIt/printIt or inspectIt. (also some others use

     this for a save abort)"

    ^ AbortSignal

!

activityNotificationSignal

    "return the signal used for activity notifications.

     A handler for this signal gets all #activityNotification: sends"

    ^ ActivityNotificationSignal

!

deepCopyErrorSignal 

    "return the signal raised when a deepcopy is asked for

     an object which cannot do this (for example, BlockClosures

     or Contexts)."

    ^ DeepCopyErrorSignal

!

elementOutOfBoundsSignal

    "return the signal used for element error reporting

     (this signal is used for example when a value not in 0..255 is to

      be put into a bytearray)"

    ^ ElementOutOfBoundsSignal

!

errorSignal

    "return the signal used for error/error: - handling"

    ^ ErrorSignal

!

exceptionInterruptSignal

    "return the signal used for exception (display errors) error handling"

    ^ ExceptionInterruptSignal

!

haltSignal

    "return the signal used for halt/halt: - handling"

    ^ HaltSignal

!

indexNotFoundSignal

    "return the signal used for bad index error reporting.

     This is also the parentSignal of the nonIntegerIndex- and

     subscriptOutOfBoundsSignal"

    ^ IndexNotFoundSignal

    "Created: / 8.11.1997 / 19:15:48 / cg"

!

informationSignal 

    "return the signal used for informations. 

     A handler for this signal gets all #information: sends"

    ^ InformationSignal

!

internalErrorSignal

    "return the signal used to report internal (VM-) errors."

    ^ InternalErrorSignal

!

keyNotFoundSignal 

    "return the signal used for no such key error reporting"

    ^ KeyNotFoundSignal

!

messageNotUnderstoodSignal

    "return the signal used for doesNotUnderstand: - error handling"

    ^ MessageNotUnderstoodSignal

!

nonIntegerIndexSignal 

    "return the signal used for bad subscript error reporting"

    ^ NonIntegerIndexSignal

!

notFoundSignal 

    "return the signal used for no element found error reporting"

    ^ NotFoundSignal

!

osSignalInterruptSignal 

    "return the signal used for OS-signal error reporting;

     This is only raised if handled - otherwise, a debugger is entered."

    ^ OSSignalInterruptSignal

    "Modified: / 12.6.1998 / 16:27:26 / cg"

!

primitiveFailureSignal

    "return the signal used for primitiveFailed - error handling"

    ^ PrimitiveFailureSignal

!

privateMethodSignal

    "return the signal used for privateMethod - error handling"

    ^ MessageNotUnderstoodSignal

!

recursionInterruptSignal 

    "return the signal used for recursion overflow error handling"

    ^ RecursionInterruptSignal

!

subscriptOutOfBoundsSignal

    "return the signal used for subscript error reporting.

     (this signal is used for example when an array is accessed with an

      index less than 1 or greater than the array size)"

    ^ SubscriptOutOfBoundsSignal

!

userInterruptSignal

    "return the signal used for ^C interrupts handling"

    ^ UserInterruptSignal

!

userNotificationSignal

    "the parent signal used with information and warnings.

     Handling this allows handling of both information- and warning notifications."

    ^ UserNotificationSignal

!

warningSignal 

    "return the signal used for warnings.

     A handler for this signal gets all #warn: sends"

    ^ WarningSignal

! !

!Object class methodsFor:'info messages'!

infoPrinting

    "return the flag which controls information messages."

    ^ InfoPrinting

!

infoPrinting:aBoolean

    "{ Pragma: +optSpace }"

    "turn on/off printing of information messages.

     If the argument, aBoolean is false, infoPrint will not output

     messages. The default is true."

    InfoPrinting := aBoolean

! !

!Object class methodsFor:'queries'!

isBuiltInClass

    "return true, if this class is known by the run-time-system,

     i.e. you cannot add/remove instance variables without recompiling

     the VM.

     Here, true is returned for myself, false for subclasses."

    ^ self == Object