"

 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 variableSubclass:#Context

	 instanceVariableNames:'flags sender home receiver selector searchClass lineNr retvalTemp

                handle*'

	 classVariableNames:'InvalidReturnSignal'

	 poolDictionaries:''

	 category:'Kernel-Methods'

!

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

"

!

documentation

"

    Contexts represent the stack frame objects, which keep the processing

    state of a method or block (i.e. its local variables, temporaries etc.)

    Every message send adds a context to a chain, which can be traced back via 

    the sender field. The context of the currently active method is always

    accessable via the pseuodoVariable called 'thisContext'.

    (The actual implementation uses the machines stack for this, building real 

     contexts on demand only).

    For both method- and block-contexts, the layout is the same. 

    For method contexts, the home-field is nil, while for block contexts the home-

    field is either the context of its surrounding block (i.e. the context of the

    block, in which the receiving block was created, if its a nested block) or of

    its home method. 

    Contexts of cheap blocks do not have a home context - their home field is 

    also nil.

    Currently, contexts do not contain a reference to the method or block which

    created it - this is not needed for program execution, but could get the debugger

    somewhat into trouble: it has to search the class hierarchy for receiver/selector

    combinations to find the method. This usually works, but fails in case of methods

    which are not anchored in any class - especially leading to problems with wrapper-

    and lazy methods. Also, Method>>valueWithReceiver - type of invocations cannot

    be easily debugged.

    Therefore, the implementation may be changed in the near future, to include a

    field for the method/block, and set it in the VM during program execution.

    (there may be some small performance penalty for this, though).

    LineNumbers vs. program counter:

    Due to the compilation to machine code, methods and/or block do not

    always (actually: do seldom) contain bytecodes. Thus, there is no such concept

    as a bytecode p-counter. To support debugging, the linenumber within the

    original source is instead remembered when a send or loop entry is performed.

    Since linenumbers are not always sufficient for debugging (multiple sends in one

    line), this may be changed in future versions to a character offset, giving

    the position of the selector in the source.

    Restartable / Returnable contexts:

    In previous versions (up to ST/X 2.10.5), every method stored enough

    information in the context for that one to be restartable later (for example,

    via the debuggers restart button). With 2.10.6, this is now an stc-compiler

    option, and the system as delivered is compiled to only create restartable

    contexts for those which contain blocks. This resulted in an overall speedup of

    roughly 10-20% percent, depending on the type of CPU. However, it makes most

    methods non-restartable (however, abort, signal handling and unwind blocks work

    as usual).

    In practice, this was reported to be not a severe limitation and all users were happy

    to trade the increased performance for that slight inconvenience.

    (during development, this is seldom a problem, since interpreted methods are always

     returnable and restartable)

    If you do not like this (and you are a happy owner of the full distribution), you

    should recompile all classes with stc's '-optContext' flag.

    Resuming contexts:

    Strictly speaking, ST/X does not support a context to be resumed. However,

    it does support a forced return (i.e. non-local-return) from a context.

    Thus, resume of a context is implemented by forcing a return from the context

    which was created by the method called from the first one. The effect is the same.

    Returning from a dead method:

    Blocksreturn from an outlived context (i.e. its home method has already returned)

    is now rewarded by an invalidReturn exception - it used to be a noop in previous

    releases (The blue book described this to be a noop, but other smalltalk implementations

    changed this to be an invalid operation -  good decision)

    instance variables:

	flags       <SmallInteger>          used by the VM; never touch.

					    contains info about number of args, 

					    locals and temporaries.

	sender      <Context>               the 'calling / sending' context

	home        <Context>               the context, where this block was 

					    created, or nil if its a method context

					    There are also cheap blocks, which do

					    not need a reference to the home context,

					    for those, its nil too.

	receiver    <Object>                the receiver of this message

	selector    <Symbol>                the selector of this message

	searchClass <Class>                 the class, where the message lookup started

					    (for super sends) or nil, for regular sends.

	lineNr      <SmallInteger>          the position where the context left off

					    (kind of p-counter). Only the low 16bits

					     are valid.

	retValTemp  nil                     temporary - always nil, when you see the context

					    (used in the VM as temporary)

	handle      *noObject*              used by the VM; not accessable, not an object

	<indexed>                           arguments of the send followed by

					    locals of the method/block followed by

					    temporaries.

    class variables:

	InvalidReturnSignal                 signal raised when a block tries

					    to return ('^') from a method context

					    which itself has already returned

					    (i.e. there is no place to return to)

    WARNING: layout and size known by the compiler and runtime system - do not change.

"

!

version

    ^ '$Header: /cvs/stx/stx/libbasic/Context.st,v 1.47 1995-11-23 11:16:45 cg Exp $'

! !

!Context class methodsFor:'initialization'!

initialize

    InvalidReturnSignal isNil ifTrue:[

	InvalidReturnSignal := ErrorSignal newSignalMayProceed:true.

	InvalidReturnSignal nameClass:self message:#invalidReturnSignal.

	InvalidReturnSignal notifierString:'invalid return; method cannot return twice'.

    ]

! !

!Context class methodsFor:'Signal constants'!

invalidReturnSignal

    "return the signal used when a method is tried to be returned twice

     or, when some dead context is unwound or restarted."

    ^ InvalidReturnSignal

! !

!Context class methodsFor:'queries'!

isBuiltInClass

    "this class & subclasses are known by the run-time-system"

    ^ true

! !

!Context methodsFor:'accessing'!

argAt:n

    "return the n'th argument"

    ^ self at:n

!

argAt:n put:value

    "set the n'th argument - useful when the receiver should be restarted"

    ^ self at:n put:value

!

args

    "return an array filled with the arguments of this context"

    |n|

    n := self numArgs.

    ^ (Array new:n) replaceFrom:1 to:n with:self.

!

argsAndVars

    "return an array filled with the arguments and variables of this context"

    |n|

    n := self numArgs + self nvars.

    ^ (Array new:n) replaceFrom:1 to:n with:self.

!

canReturn

    "return true, if the receiver allows returning through it.

     For normal method contexts, this returns true;

     for blocks, it (currently) always returns false.

     However, the system can be compiled (for production code), to create

     contexts which cannot be returned or restarted

     (except, if the method contains a returning block). 

     This saves some administrative work in every method

     invocation and makes overall execution faster. However, it limits

     the debugger, in that it cannot return from or restart those contexts.

     (unwinding and termination is not affected by this optimization)

     Currently, the system as delivered has this optimization disabled."

%{  /* NOCONTEXT */

    RETURN ( (_intVal(_INST(flags)) & __CANNOT_RETURN) ? false : true );

%}

!

home

    "return the immediate home of the receiver.

     for block contexts, this is the methodcontext, where the block was created,

     for nested block contexts, its the surrounding blocks context.

     for method-contexts this is nil."

    ^ nil "home"

!

instVarAt:index

    "have to catch instVar access to retVal and handle - they are invalid.

     Notice, that one of the next ST/X versions will get some syntactic

     extension to get this automatically)."

    (index == 8) ifTrue:[^ nil].

    (index == 9) ifTrue:[^ nil].

    ^ super instVarAt:index

!

instVarAt:index put:value

    "have to catch instVar access to retVal and handle - they are invalid.

     Notice, that one of the next ST/X versions will get some syntactic

     extension to get this automatically)."

    (index == 8) ifTrue:[^ nil].

    (index == 9) ifTrue:[^ nil].

    ^ super instVarAt:index put:value

!

isUnwindContext

    "return true, if this is an unwindContext"

%{  /* NOCONTEXT */

     RETURN ( ((INT)_INST(flags) & __MASKSMALLINT(__UNWIND_MARK)) ? true : false );

%}

!

lineNumber

    "this returns the lineNumber within the methods source, where the context was

     interrupted or called another method. (currently, sometimes this information

     is not available - in this case 0 is returned)"

    lineNr isNil ifTrue:[^ nil].

    ^ lineNr bitAnd:16rFFFF

!

method

    "return the method for which the receiver was created.

     To save time during normal execution, this information is not held in the

     context, but computed here on request."

    |c|

    c := self searchClass.

    "

     the below cannot happen in normal circumstances

     (added to avoid recursive errors in case of a broken sender chain)

    "

    c isBehavior ifFalse:[

	'OOPS: non class in searchClass' errorPrintNL.

	'      selector: ' errorPrint. selector errorPrint.

	' receiver: ' errorPrint. receiver errorPrintNL.

	^ nil

    ].

    c := c whichClassIncludesSelector:selector.

    c notNil ifTrue:[

	^ c compiledMethodAt:selector

    ].

    "mhmh - seems to be a context for an unbound method;

     look in the senders context. Consider this a kludge.

     (maybe it was not too good of an idea to not keep the current

      method in the context ....

      future versions of ST/X's message lookup may store the method in

      the context.)

    "

    (sender notNil and:[sender selector startsWith:'valueWithReceiver:']) ifTrue:[

	^ sender receiver

    ].

    ^ nil

!

methodClass

    "return the class in which the method for which the receiver was created is."

    ^ self searchClass whichClassIncludesSelector:selector.

!

methodHome

    "return the method-home - for method contexts this is the receiver"

    ^ self

!

ntemp

    "return the number of temporary variables of the Block/Method.

     (for debugging only)"

    ^ self size - self numArgs - self nvars

!

numArgs

    "return the number of arguments to the Block/Method"

%{  /* NOCONTEXT */

    RETURN ( _MKSMALLINT( (_intVal(_INST(flags)) >> __NARG_SHIFT) & __NARG_MASK) );

%}

!

nvars

    "return the number of local variables of the Block/Method"

%{  /* NOCONTEXT */

    RETURN ( _MKSMALLINT( (_intVal(_INST(flags)) >> __NVAR_SHIFT) & __NVAR_MASK) );

%}

!

receiver

    "return the receiver of the context"

    ^ receiver

!

searchClass

    "this is the class where the method-lookup started;

     for normal sends, it is nil (or sometimes the receivers class).

     For supersends, its the superclass of the one, in which the

     caller was defined."

    searchClass notNil ifTrue:[^ searchClass].

    ^ receiver class

!

selector

    "return the selector of the method for which the context was created"

    ^ selector

!

sender

    "return the sender of the context"

    "this special test is for the very first context (startup-context);

     actually, its cosmetics, to avoid a visible nil>>nil context in the debugger."

%{  /* NOCONTEXT */

    OBJ con;

    if (__isNonNilObject(con = _INST(sender))) {

	if (__isLazy(con)) {

	    /*

	     * this cannot happen

	     */

	    _PATCHUPCONTEXT(con);

	}

	/* 

	 * to be prepared for the worst situation 

	 * (the sender is not stored, so the trap wont catch it)

	 * make the writeBarrier trigger manually.

	 * We'll see, if this is really required.

	 */

	con->o_space |= CATCHMARK;

	_markNonLIFO(con);

    }

%}.

    ^ sender

!

setLineNumber:aNumber

    "private entry for uncompiledCodeObject ..."

    lineNr := aNumber

!

temporaries 

    "return an array filled with the temporaries of this context"

    |nonTemps mySize|

    nonTemps := self numArgs + self nvars.

    mySize := self ntemp.

    ^ (Array new:mySize) replaceFrom:1 to:mySize with:self startingAt:nonTemps+1

!

unsafeSender

    "temporary: for debugging only"

    ^ sender

!

varAt:n

    "return the n'th local variable"

    ^ self at:(n + self numArgs)

!

varAt:n put:value

    "set the n'th local variable - useful when the receiver should be restarted

     or continued"

    self at:(n + self numArgs) put:value

!

vars 

    "return an array filled with the local variables of this context"

    |nonVars mySize|

    nonVars := self numArgs.

    mySize := self nvars.

    ^ (Array new:mySize) replaceFrom:1 to:mySize with:self startingAt:nonVars+1

! !

!Context methodsFor:'copying'!

deepCopy

    "raise an error - deepCopy is not allowed for contexts"

    ^ self deepCopyError

! !

!Context methodsFor:'error handling'!

invalidReturn:returnValue

    "this message is sent by the VM, when a methods context

     which has already returned is about to return again.

     (i.e. about to execute a return from an already returned

      method in a block).

    We raise a signal here, to allow catching of that situation."

    "

     in previous versions of ST/X and ST-80, this was no error;

     (instead, a normal blockreturn was performed to the value-sender).

     From a note in comp.lang.smalltalk, I conclude that new ST-80 versions

     now raise an error if this happens.

     Comment out the raise below to get that (old) behavior

     BETTER REWRITE YOUR APPLICATION

    " 

"/ new behavior:

    ^ InvalidReturnSignal 

	raiseRequestWith:returnValue.

"/ old behavior:

"/  ^ returnValue

!

invalidReturnOrRestart:returnValue

    "this message is sent by the VM, when a methods context

     which was compiled non-returnable is about to return again.

     We raise a signal here, to allow catching of that situation."