"

 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

		RecursiveStoreStringSignal AbortAllSignal'

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

initSignals

    "called only once - initialize signals"

    ErrorSignal := Error.

    ControlInterrupt notifierString:'control interrupted'.

    HaltSignal := HaltInterrupt.

    HaltSignal notifierString:'halt encountered'.

    MessageNotUnderstoodSignal := MessageNotUnderstood.

    MessageNotUnderstoodSignal notifierString:'message not understood'.

    PrimitiveFailureSignal := PrimitiveFailure.

    PrimitiveFailureSignal notifierString:'primitive failed'.

    InternalErrorSignal := VMInternalError.

    UserInterruptSignal := UserInterrupt.

    UserInterruptSignal notifierString:'user Interrupt'.

    RecursionInterruptSignal := RecursionError.

    RecursionInterruptSignal notifierString:'recursion limit reached'.

    NotFoundSignal := NotFoundError.

    NotFoundSignal notifierString:'no such element'.

    IndexNotFoundSignal := IndexNotFoundError.

    IndexNotFoundSignal notifierString:'bad index: '.

    SubscriptOutOfBoundsSignal := SubscriptOutOfBoundsError.

    SubscriptOutOfBoundsSignal notifierString:'subscript out of bounds: '.

    NonIntegerIndexSignal := NonIntegerIndexError.

    NonIntegerIndexSignal notifierString:'index must be integer'.

    KeyNotFoundSignal := KeyNotFoundError.

    KeyNotFoundSignal notifierString:'no such key: '.

    ElementOutOfBoundsSignal := ElementBoundsError.

    UserNotificationSignal := UserNotification.

    WarningSignal := Warning.

    InformationSignal := UserInformation.

    ActivityNotificationSignal := ActivityNotification.

    DeepCopyErrorSignal := DeepCopyError.

    AbortSignal := AbortOperationRequest.

    AbortAllSignal := AbortAllOperationRequest.

    OSSignalInterruptSignal := OSSignalInterrupt.

    RecursiveStoreStringSignal := RecursiveStoreError.

    "

     Object initSignals

    "

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

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

    "Modified: / 16.11.2001 / 16:30:08 / cg"

!

initialize

    "called only once - initialize signals"

    ErrorSignal isNil ifTrue:[

        self initSignals

    ].

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

    ^ Error

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

! !

!Object class methodsFor:'Signal constants'!

abortAllSignal 

    "return the signal used to abort user actions (much like AbortSignal).

     This signal is supposed to abort multiple operation actions, and get out of

     the loop (such as when confirming multiple class deletions etc.)"

    ^ AbortAllSignal

!

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

    ^ AbortOperationRequest

!

activityNotificationSignal

    "return the signal used for activity notifications.

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

    ^ ActivityNotification

!

deepCopyErrorSignal 

    "return the signal raised when a deepcopy is asked for

     an object which cannot do this (for example, BlockClosures

     or Contexts)."

    ^ DeepCopyError

!

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

    ^ ElementBoundsError

!

errorSignal

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

    ^ Error

!

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

    ^ VMInternalError

!

keyNotFoundSignal 

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

    ^ KeyNotFoundError

!

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

!

notifySignal

    "return the parent of all notification signals."

    ^ Notification

!

osSignalInterruptSignal 

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

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

    ^ OSSignalInterrupt

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

!

primitiveFailureSignal

    "return the signal used for primitiveFailed - error handling"

    ^ PrimitiveFailure

!

privateMethodSignal

    "return the signal used for privateMethod - error handling"

    ^ MessageNotUnderstoodSignal

!

recursionInterruptSignal 

    "return the signal used for recursion overflow error handling"

    ^ RecursionInterruptSignal

!

recursiveStoreStringSignal

    "return the notification used to report storeString generation of recursive objects"

    ^ RecursiveStoreError

    "

     RecursiveStoreError handle:[:ex |

        self halt

     ] do:[

        |a|

        a := Array new:1.

        a at:1 put:a.

        a storeOn:Transcript

     ]

    "

    "

     |a|

     a := Array new:1.

     a at:1 put:a.

     a storeOn:Transcript

    "

!

subclassResponsibilitySignal

    "return the signal used for subclassResponsibility error reporting.

     (this signal is used to signal incomplete subclasses - i.e. a programmers error)"

    ^ SubclassResponsibilityError

!

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