"

 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.

"

Object subclass:#Object

       instanceVariableNames:''

       classVariableNames:'ErrorSignal HaltSignal 

			   MessageNotUnderstoodSignal UserInterruptSignal

			   RecursionInterruptSignal ExceptionInterruptSignal

			   SubscriptOutOfBoundsSignal NonIntegerIndexSignal

			   NotFoundSignal KeyNotFoundSignal ElementOutOfBoundsSignal

			   InformationSignal PrimitiveFailureSignal

			   DeepCopyErrorSignal

			   AbortSignal

			   ErrorRecursion Dependencies

			   InfoPrinting'

       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.

"

!

version

    ^ '$Header: /cvs/stx/stx/libbasic/Object.st,v 1.69 1995-11-11 15:25:11 cg Exp $'

!

documentation

"

   Object is the superclass of all other classes. Protocol 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 where 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

	DeepCopyErrorSignal

	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     <Dictionary>   keeps track of object dependencies

"

! !

!Object class methodsFor:'initialization'!

initialize

    "called only once - initialize signals"

    ErrorSignal isNil ifTrue:[

	ErrorSignal := (Signal new) mayProceed:true.

	ErrorSignal nameClass:self message:#errorSignal.

	ErrorSignal notifierString:'error encountered'.

	HaltSignal := ErrorSignal 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'.

"/        UserInterruptSignal := ErrorSignal newSignalMayProceed:true.

	UserInterruptSignal := (Signal new) newSignalMayProceed: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'.

	SubscriptOutOfBoundsSignal := ErrorSignal newSignalMayProceed:false.

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

	NotFoundSignal := ErrorSignal newSignalMayProceed:true.

	NotFoundSignal nameClass:self message:#notFoundSignal.

	NotFoundSignal notifierString:'no such element'.

	KeyNotFoundSignal := ErrorSignal newSignalMayProceed:true.

	KeyNotFoundSignal nameClass:self message:#keyNotFoundSignal.

	KeyNotFoundSignal notifierString:'no such key:'.

	NonIntegerIndexSignal := ErrorSignal newSignalMayProceed:false.

	NonIntegerIndexSignal nameClass:self message:#nonIntegerIndexSignal.

	NonIntegerIndexSignal notifierString:'index must be integer'.

	InformationSignal := ErrorSignal newSignalMayProceed:true.

	InformationSignal nameClass:self message:#informationSignal.

	InformationSignal notifierString:'information'.

	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 new mayProceed:true.

	AbortSignal nameClass:self message:#abortSignal.

	AbortSignal notifierString:'unhandled abort signal'.

	Dependencies isNil ifTrue:[

	    Dependencies := WeakIdentityDictionary new.

	]

    ].

    InfoPrinting := true

    "Object initialize"

! !

!Object class methodsFor:'Signal constants'!

errorSignal

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

    ^ ErrorSignal

!

haltSignal

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

    ^ HaltSignal

!

messageNotUnderstoodSignal

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

    ^ MessageNotUnderstoodSignal

!

privateMethodSignal

    "return the signal used for privateMethod - error handling"

    ^ MessageNotUnderstoodSignal

!

primitiveFailureSignal

    "return the signal used for primitiveFailed - error handling"

    ^ PrimitiveFailureSignal

!

userInterruptSignal

    "return the signal used for ^C interrupts handling"

    ^ UserInterruptSignal

!

recursionInterruptSignal 

    "return the signal used for recursion overflow error handling"

    ^ RecursionInterruptSignal

!

exceptionInterruptSignal

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

    ^ ExceptionInterruptSignal

!

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

!

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

!

nonIntegerIndexSignal 

    "return the signal used for bad subscript error reporting"

    ^ NonIntegerIndexSignal

!

notFoundSignal 

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

    ^ NotFoundSignal

!

keyNotFoundSignal 

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

    ^ KeyNotFoundSignal

!

informationSignal 

    "return the signal used for informations"

    ^ InformationSignal

!

deepCopyErrorSignal 

    "return the signal raised when a deepcopy is asked for

     an object which cannot do this (for example, BlockClosures

     or Contexts)."

    ^ DeepCopyErrorSignal

!

abortSignal 

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

     raised if cought (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

! !

!Object class methodsFor:'info messages'!

infoPrinting:aBoolean

    "turn on/off printing of information messages.

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

     messages. The default is true."

    InfoPrinting := aBoolean

!

infoPrinting

    "return the flag which controls information messages."

    ^ InfoPrinting

! !

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

    ^ self == Object

! !

!Object methodsFor:'initialization'!

initialize

    "just to ignore initialize to objects which do not need it"

    ^ self

! !

!Object ignoredMethodsFor:'initialization'!

fromLiteralArrayEncoding:aSpecArray

    "read my values from a specArray. The argument is supposed to

     consist of setSelector/value pairs, which are sent to the receiver.

     Some classes (Point, Rectangle) redefine this for a slightly more compact

     literal representation.

     This was added to allow for VW windowSpecs to be parsed in ST/X;

     do not use if for general object printing/restoring."

    |sz "{Class: SmallInteger }"|

    sz := aSpecArray size.

    2 to:sz  by:2 do:[:i | 

	self perform:(aSpecArray at:i) with:(aSpecArray at:i+1)

    ]

    "

     (Association new) fromLiteralArrayEncoding:#(#dummy #key: 1 #value: 'one')

    "

! !

!Object methodsFor:'cleanup'!

lowSpaceCleanup

    "ignored here - redefined in some classes to

     cleanup in low-memory situations"

    ^ self

! !

!Object methodsFor:'system primitives'!

become:anotherObject

    "make all references to the receiver become references to anotherObject

     and vice-versa. This may be an expensive (i.e. slow) operation, 

     since in the worst case, the whole memory has to be searched for 

     references to the two objects (although the primitive tries hard to

     limit the search, for acceptable performance in most cases). 

     In general, using become: should be avoided if possible, since it may 

     produce many strange effects (think of hashing in Sets).

     This method fails, if the receiver or the argument is a SmallInteger 

     or nil, or is a context of a living method (i.e. one that has not already 

     returned).

     (notice that become: is not used heavily by the system 

      - the Collection-classes have been rewritten to not use it.)"

%{

    if (__primBecome(self, anotherObject COMMA_CON))

	RETURN ( self );

%}

.

    self primitiveFailed

!

becomeNil

    "make all references to the receiver become nil - effectively getting

     rid of the receiver. This can be a very dangerous operation - be warned.

     The receiver may not be a SmallInteger or a context of a living method."

%{

    if (__primBecomeNil(self COMMA_CON ))

	RETURN ( nil );

%}

.

    self primitiveFailed

!

changeClassTo:otherClass

    "changes the class of the receiver to the argument, otherClass.

     This is only allowed (possible), if the receivers class and the argument

     have the same structure (i.e. number of named instance variables and

     type of indexed instance variables). 

     If the structures do not match, or any of the original class or new class

     is UndefinedObject or a Smallinteger, a primitive error is triggered."

    |myClass ok|

    "check for UndefinedObject/SmallInteger receiver or newClass"

%{

    if (__isNonNilObject(self) 

     && __isNonNilObject(otherClass)

     && (otherClass != UndefinedObject)

     && (otherClass != SmallInteger)) {

	ok = true;

    } else {

	ok = false;

    }

%}.

    ok ifTrue:[

	ok := false.

	myClass := self class.

	myClass flags == otherClass flags ifTrue:[

	    myClass instSize == otherClass instSize ifTrue:[

		"same instance layout and types: its ok to do it"

		ok := true.

	    ] ifFalse:[

		myClass isPointers ifTrue:[

		    myClass isVariable ifTrue:[

			ok := true

		    ]

		]

	    ]

	] ifFalse:[

	    myClass isPointers ifTrue:[

		"if newClass is a variable class, with instSize <= my instsize,

		 we can do it (effectively mapping additional instvars into the

		 variable part) - usefulness is questionable, though"

		otherClass isPointers ifTrue:[

		    otherClass isVariable ifTrue:[

			otherClass instSize <= (myClass instSize + self basicSize) 

			ifTrue:[

			    ok := true

			]

		    ] ifFalse:[

			otherClass instSize == (myClass instSize + self basicSize) 

			ifTrue:[

			    ok := true

			]

		    ]

		] ifFalse:[

		    "it does not make sense to convert pointers to bytes ..."

		]

	    ] ifFalse:[

		"does it make sense, to convert bits ?"

		"could allow byteArray->wordArray->longArray->floatArray->doubleArray here ..."

	    ]

	]

    ].

    ok ifTrue:[

	"now, change the receivers class ..."

%{

	__qClass(self) = otherClass;

	__STORE(self, otherClass);

	RETURN ( self );

%}.

    ].

    self primitiveFailed

!

changeClassToThatOf:anObject

    "changes the class of the receiver to that of the argument, anObject.

     This is only allowed (possible), if the receivers class and the arguments

     class have the same structure (i.e. number of named instance variables and 

     type of indexed instance variables). If the structures do not match, or any

     of the objects is nil or a Smallinteger, a primitive error is triggered."

    self changeClassTo:(anObject class)

! !

!Object methodsFor:'queries'!

size

    "return the number of the receivers indexed instance variables;

     this method may be redefined in subclasses"

    ^ self basicSize

!

basicSize

    "return the number of the receivers indexed instance variables,

     0 if it has none.

     This method should NOT be redefined in any subclass"

%{  /* NOCONTEXT */

    REGISTER int nbytes;

    REGISTER OBJ myClass;

    REGISTER int flags;

    /*

     * notice the missing test for self being a nonNilObject -

     * this can be done since basicSize is defined both in UndefinedObject

     * and SmallInteger

     */

    myClass = __qClass(self);

    nbytes = __qSize(self) 

	      - OHDR_SIZE 

	      - __OBJS2BYTES__(_intVal(_ClassInstPtr(myClass)->c_ninstvars));