Class: Context

• Inheritance
• Description
• Related information
• Class protocol
  • Signal constants
  • error handling
  • initialization
  • queries
  • special searching
• Instance protocol
  • Compatibility-Squeak
  • Compatibility-VW
  • accessing
  • copying
  • error handling
  • fixups
  • minidebugger printing
  • non local control flow
  • printing & storing
  • private-accessing
  • searching
  • special accessing
  • testing

Inheritance:

   Object
   |
   +--Context
      |
      +--BlockContext

Package:

stx:libbasic

Category:

Kernel-Methods

Version:

rev: 1.157 date: 2010/04/07 17:36:33

user: cg

file: Context.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

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:

Blockreturn 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
                                        This is not directly accessable, since it may
                                        be a lazy context (i.e. an empty frame).
                                        The #sender method cares for this.

    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

    method                              the corresponding method

    <indexed>                           arguments of the send followed by
                                        locals of the method/block followed by
                                        temporaries.

[errors:]
    CannotReturnError                   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.

Related information:

    Block
    Process
    Method
    [contexts, stacks & unwinding]

Class protocol:

 cannotResumeSignal

return the signal used when a method is tried to be resumed, which cannot

 cannotReturnSignal

return the signal used when a method is tried to be returned twice
or, when some dead context is unwound or restarted.

 invalidReturnSignal

return the signal used when a method is tried to be returned twice
or, when some dead context is unwound or restarted.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 singleStepInterruptRequest

return the dummy query signal to ask for single stepping

 showWhereWeCameFrom

show the stack backtrace: at least 4 levels, or until the first
send to a non-collection object (because we want to know,
which non-collection send invoked a bad collection-method).

 initialize

InvalidReturnSignal isNil ifTrue:[

 isBuiltInClass

return true if this class is known by the run-time-system.
Here, true is returned.

 findFirstSpecialHandle: searchForHandle raise: searchForRaise

Instance protocol:

 longStack

 resumeWith: value

same as #resume: - visualWorks compatibility

 argAt: n

return the n'th argument

 argAt: n put: value

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

 args

return an array filled with the arguments of this context

 argsAndVars

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

 argumentCount

ANSI alias for numArgs: return the number of arguments to the Block/Method

 at: n put: value

 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.

 homeReceiver

return the receiver from the context, where the receiver was defined

 instVarAt: index

have to catch instVar access to retVal and handle - they are invalid.
Notice, that one of the next ST/X versions might get some syntactic
extension to get this automatically).

 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 might get some syntactic
extension to get this automatically).

 javaLineNumber

 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)

 lineNumberFromMethod

 message

 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.

 methodClass

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

 methodHome

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

 ntemp

return the number of temporary variables of the Block/Method.
(for debugging only).
I dont like the name of this method; its here for compatibility.

 numArgs

return the number of arguments to the Block/Method

 numTemps

return the number of temporary variables of the Block/Method.
(for debugging only)

 numVars

return the number of local variables of the Block/Method

 nvars

return the number of local variables of the Block/Method.
I dont like the name of this method; its here for compatibility.

 receiver

return the receiver of the context

 receiver: aCompiledCode

set the receiver of the message

 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.

 selector

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

 sender

return the sender of the context

 senderIsNil

return true, if I have no sender

 setLineNumber: aNumber

private entry for uncompiledCodeObject ...

 setNumArgs: nA numVars: nV

set the number of arguments and variables

 tempAt: index

return the n'th stack-temporary variable

 temporaries

return an array filled with the temporaries of this context

 varAt: n

return the n'th local variable

 varAt: n put: value

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

 vars

return an array filled with the local variables of this context

 deepCopyUsing: aDictionary postCopySelector: postCopySelector

raise an error - deepCopy is not allowed for contexts

 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.

 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.

 invalidReturnOrRestartError: how with: value

common error reporter for restart/return errors

 fixAllLineNumbers

 fullPrint

print the receiver, selector and args of the context
- used only for MiniDebuggers walkback print

 fullPrintAll

print a full walkback starting at the receiver
- used only for MiniDebuggers walkback print

 fullPrintAllLevels: nOrNil

print a full walkback starting at the receiver, only print n levels
- used only for MiniDebuggers walkback print

 printAll

print a full walkback starting at the receiver, only print n levels
- used only for MiniDebuggers walkback print

 printAllLevels: nOrNil

print a full walkback starting at the receiver, only print n levels
- used only for MiniDebuggers walkback print

 evaluateUnwindActionsUpTo: aContext

walk up the calling chain, looking for unwind-cleanup actions to
be performed. This depends upon those contexts being specially
marked using #markForUnwind.
Returns the argument (i.e. non-nil), if all went well,
nil if aContext is not on the caller chain (definitely an error)

 restart

restart the receiver - i.e. the method is evaluated again.
if the context to restart already died, trigger an error.
This is a low level helper for unwindAndRestart.

NOTICE:
NO unwind actions are performed - this is usually not
what you want (see Context>>unwindAndRestart).

LIMITATION:
currently a context can only be restarted by
the owning process - not from outside.
Also, the compiler has an option (+optcontext) to create
non-restartable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 resume

resume execution in this context. I.e. as if the method called
last by the receiver did a ^ nil.
If the context has already returned, report an error.

NOTICE:
NO unwind actions are performed (see Context>>unwind).

LIMITATION:
currently a context can only be resumed by
the owning process - not from outside.
Also, the compiler has an option (+optcontext) to create
non-resumable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 resume: value

resume the receiver - as if it got 'value' from whatever
it called. This continues execution in the receivers method
after the point where it did its last send.
If the context has already returned - report an error.

NOTICE:
NO unwind actions are performed (see Context>>unwind:).

LIMITATION:
currently a context can only be resumed by
the owning process - not from outside.
Also, the compiler has an option (+optcontext) to create
non-resumable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 resumeIgnoringErrors: value

resume the receiver - as if it got 'value' from whatever
it called. This continues execution in the receivers method
after the point where it did its last send.
If the context has already returned - simply return.

NOTICE:
NO unwind actions are performed (see Context>>unwind:).

LIMITATION:
currently a context can only be resumed by
the owning process - not from outside.
Also, the compiler has an option (+optcontext) to create
non-resumable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 resumeOnErrorProceed: value

resume the receiver - as if it got 'value' from whatever
it called. This continues execution in the receivers method
after the point where it did its last send.
If the context has already returned - simply return.

NOTICE:
NO unwind actions are performed (see Context>>unwind:).

LIMITATION:
currently a context can only be resumed by
the owning process - not from outside.
Also, the compiler has an option (+optcontext) to create
non-resumable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 return

return from this context with nil. I.e. as if it did a ^ nil.
NOTICE:
NO unwind actions are performed - this is usually not
what you want (See Context>>unwind).
This is a low level method - a helper for unwind.

LIMITATION:
currently a context can only be returned by
the owning process - not from outside.
Also, the compiler has an option (+optcontext) to create
non-returnable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 return: value

return from this context as if it did a '^ value'.
NOTICE:
NO unwind actions are performed - this is usually not
what you want (See Context>>unwind:).
This is a low level method - a helper for unwind.

LIMITATION:
currently a context can only be returned by
the owning process - not from outside.
Also, the compiler has an option (+optcontext) to create
non-returnable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 returnDoing: aBlock

return from this context as if it did a '^ aBlock value'.
The block is evaluated as if called by the receiver context;
NOT the true executing context.
NOTICE:
NO unwind actions are performed - this is usually not
what you want (See Context>>unwindThenDo:).
This is a low level method - a helper for unwind.

LIMITATION:
currently a context can only be returned by
the owning process - not from outside.
Also, the compiler has an option (+optcontext) to create
non-returnable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 unwind

return nil from the receiver - i.e. simulate a '^ nil'.
If the context has already returned, report an error.
Evaluate all unwind-blocks as specified in Block>>valueNowOrOnUnwind:
and Block>>valueOnUnwindDo: on the way.

LIMITATION:
currently a context can only be unwound by
the owning process - not from outside.
i.e. it is not possible for one thread to unwind
another threads context - which does not make sense anyway.
However, you can force another thread to do this in its own process
context, by giving it an interrupt action - this does make sense.

Also, the compiler has an option (+optcontext) to create
non-returnable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 unwind: value

return value from the receiver - i.e. simulate a '^ value'.
If the context has already returned , report an error.
Evaluate all unwind-blocks as specified in Block>>valueNowOrOnUnwind:
and Block>>valueOnUnwindDo: on the way.

LIMITATION:
currently a context can only be unwound by
the owning process - not from outside.
i.e. it is not possible for one thread to unwind
another threads context - which does not make sense anyway.
However, you can force another thread to do this in its own process
context, by giving it an interrupt action - this does make sense.

Also, the compiler has an option (+optcontext) to create
non-returnable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 unwindAndRestart

restart the receiver - i.e. the method is evaluated again.
if the context to restart already died report an error.
Evaluate all unwind-blocks as specified in Block>>valueNowOrOnUnwind:
and Block>>valueOnUnwindDo: before restarting.

LIMITATION:
a context can only be restarted by
the owning process - not from outside.
i.e. it is not possible for one thread to unwindAndRestart
another threads context - which does not make sense anyway.
However, you can force another thread to do this in its own process
context, by giving it an interrupt action - this does make sense.

Also, the compiler has an option (+optcontext) to create
non-restartable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 unwindAndResume: value

resume execution in the the receiver - i.e. simulate a '^ value'
from whatever it called last.
If the context has already returned , report an error.
Evaluate all unwind-blocks as specified in Block>>valueNowOrOnUnwind:
and Block>>valueOnUnwindDo: on the way.

LIMITATION:
currently a context can only be unwound by
the owning process - not from outside.
i.e. it is not possible for one thread to unwind
another threads context - which does not make sense anyway.
However, you can force another thread to do this in its own process
context, by giving it an interrupt action - this does make sense.

Also, the compiler has an option (+optcontext) to create
non-returnable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 unwindThenDo: aBlock

return the value of aBlock from the receiver - i.e. simulate a '^ aBlock value'.
If the context has already returned , report an error.
Evaluate all unwind-blocks as specified in Block>>valueNowOrOnUnwind:
and Block>>valueOnUnwindDo: on the way.
The block is evaluated AFTER all unwind actions are performed
(i.e. the blocks sender will be the receiving context, not the
currently executing context)

LIMITATION:
currently a context can only be unwound by
the owning process - not from outside
i.e. it is not possible for one thread to unwindThenDo
another threads context - which does not make sense anyway.
However, you can force another thread to do this in its own process
context, by giving it an interrupt action - this does make sense.

Also, the compiler has an option (+optcontext) to create
non-returnable contexts (which are faster).
If such a context is restarted, a runtime error is raised.

 argStringFor: someObject

 argsDisplayString

 displayArgsOn: aStream

 displayString

return a string describing the context - for display in Inspector

 fullPrintAllOn: aStream

print a full walkback (incl arguments) starting at the receiver

 fullPrintOn: aStream

append a verbose description (incl. arguments) of the receiver onto aStream

 fullPrintString

return a string describing the context - this includes the linenumber,
receiver printString and argument printString

 methodPrintString

return a string describing the contexts method as 'implementorClass>>selector'

 printAllOn: aStream

print a brief walkback (excl. arguments) starting at the receiver

 printOn: aStream

append a brief description (excl. arguments) of the receiver onto aStream

 receiverPrintString

return a string describing the receiver of the context

 saveReceiverClassName

return the receivers class-name string or nil, if the receiver is invalid.
This cares for invalid (free) objects which may appear with bad primitive code,
and prevents a crash in such a case.

 isMarkedForUnwind

true if the mark for unwind flag is set in the receiver.
The VM needs this to know that some special action is to be performed with
this context - a highly internal mechanism and not for public use.

 markForHandle

set the mark for exception handle flag in the receiver.
The VM needs this to know that some special action is to be performed with
this context - a highly internal mechanism and not for public use.

 markForInterrupt

set the interrupt flag.
The VM needs this to know that some special action is to be performed with
this context upon return - a highly internal mechanism and not for public use.

 markForInterruptOnUnwind

set the interrupt-on-unwind flag in the receiver.
The VM will generate a stepInterrupt, when this context returns or
is unwound. This is used by the debugger for faster single-stepping;
- a highly internal mechanism and not for public use.

 markForRaise

set the mark for exception raise flag in the receiver.
The VM needs this to know that some special action is to be performed with
this context - a highly internal mechanism and not for public use.

 markForUnwind

set the mark for unwind flag in the receiver.
The VM needs this to know that some special action is to be performed with
this context - a highly internal mechanism and not for public use.

 setHome: aContext

set the homeContext.
DANGER: this is for experimental, internal use only (byteCode interpreters)

 setSender: aContext

set the sender of the context.
DANGER: this is for experimental, internal use only (byteCode interpreters)

 unmarkForUnwind

clear the mark for unwind flag in the receiver.
The VM needs this to know that some special action is to be performed with
this context - a highly internal mechanism and not for public use.

 findExceptional

walk along the sender chain (starting with the sender),
for a context which is marked as handle or raise context.
This non-standard interface is only to be used by exception

 findNextContextWithSelector: selector1 or: selector2 or: selector3

walk along the sender chain (starting with the sender),
for a context with either one of the given selectors.
This non-standard interface is only to be used by exception

 findNextUnwindContextOr: aContext

walk along the sender chain (starting at the sender),
for a context marked for unwindAction or aContext.
This non-standard interface is only to be used by mySelf

 findSpecialHandle: findHandleContext raise: findRaiseContext

walk along the sender chain (starting with the sender),
for a context which is marked as handle or raise context.
This non-standard interface is only to be used by exception

 argAndVarNames

helper: given a context, return a collection of arg&var names

 canResume

return true, if the receiver allows to be resumed.
Due to the implementation, this requires that the context which
is right below the receiver is returnable.

 canReturn

return true, if the receiver allows returning through it.
Blocks, (currently) always return false.
Methods which contain a (non-inlined) block are always
returnable - for other methods, it depends on how the system
was compiled (stc flag +/-optContext).
If it was compiled with +optContext, methods are compiled
non returnable, unless a return-pragma was present in the method.
Since this saves some administrative work in every method
invocation and makes overall execution faster, the system classes
are all compiled with this flag turned on.

 hasStackToShow

private interface to the debugger.
Smalltalk contexts return false here - other language frames
(i.e. Java frames) may want to show the evaluation stack

 isHandleContext

return true, if this is a context with exception-handle flag set

 isNonLifo

return true, if this is a nonLifo context.
A nonLifo context is one that is still on the machine stack,
but has a reference taken and needs to be converted to a real
object (in objectMemory) when the method/block returns.
You dont have to understand this - this is a special ST/X
debug query, which may be removed without notice.

 isOnMachineStack

return true, if this is a machine stack context as opposed to a
real heap context.
You dont have to understand this - this is a special ST/X
debug query, which may be removed without notice.

 isRaiseContext

return true, if this is a context with exception-raise flag set

 isSpecial

return true, if this is either a nonLifo or interrupted context

 isUnwindContext

return true, if this is an unwindContext

 tempNames

helper: given a context, return a collection of arg, var and temporary names

 isBlockContext

return true, iff the receiver is a BlockContext, false otherwise

 isContext

return true, iff the receiver is a Context, false otherwise

 isRecursive

return true, if this context is one of a recursive send of the same
selector to the same receiver before.
Here, different arguments are ignored - i.e. only the same method
counts for recursiveness.
Used to detect recursive errors or recursive printing - for example.