Smalltalk/X Webserver

Documentation of class 'Context':

Class: Context

Inheritance
Description
Class protocol
Instance protocol

Inheritance:

   Object
   |
   +--Context
      |
      +--BlockContext

Package:: stx:libbasic

Category:: Kernel-Methods

Version:: rev: 1.286 date: 2024/03/10 21:01:01; user: cg; file: Context.st directory: libbasic; module: stx stc-classLibrary: libbasic

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
accessible via the pseuodoVariable called 'thisContext'.
The actual implementation uses the machine's stack for this, building real
contexts on demand only, whenever a context is needed. Also, initially these are
allocated on the stack and only moved to the heap, when a context outlives its
activation.

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 it's a nested block) or of
its home method.

Cheap blocks are blocks which do not refer to any locals or the receiver (currently),
but only access globals, class vars or arguments (for example: [:a :b | a < b] is a cheap block).
Cheap blocks do not need a home and therefore never require that their home context be moved
to the heap. Contexts of cheap blocks do not have a home context - their home field is also nil.

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 debugger's restart button). As stc is supposed to generate portable C-code,
this means that technically, a setjmp needs to be done at the beginning of the method
in order to have a resumable (and portable) state (however, inline asm code does this setjmp,
so it is much faster than the libc-setjmo, which stores a lot of additional state, not needed here).
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 or are marked as special
via a directive.
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, you should recompile all classes with stc's '-optContext' flag.

Resuming contexts:

Strictly speaking, ST/X does not support a context to be resumed (because the setjmp is
not done on the caller side, but in the callee).
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:

Block-return 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 - a good decision, as it makes debugging much easier.

[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 accessible, 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 accessible, 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.

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 t itle to or ownership of the software is
hereby transferred.

Class protocol:

Signal constants

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

accessing

printWithReceiverHashes
printWithReceiverHashes: aBoolean: if aBoolean is true, add the identityHash of the receiver to the printString.
Answer the previous setting.

error handling

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

Usage example(s):

      Context showWhereWeCameFrom

initialization

initialize: if true, print the identityHash of the Receiver in walkbacks

queries

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

special searching

findFirstSpecialHandle: searchForHandle raise: searchForRaise: find the first handle context (if searchForHandle is true)
or raise context (if serachForRaise is true)
below thisContext

Instance protocol:

Compatibility-Squeak

longStack

Compatibility-VW

resumeWith: value: same as #resume: - visualWorks compatibility

accessing

arg1Index

return the index of the 1st arg (redefined in JavaContext)

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

need some aid for optimized code -

home

return the immediate home of the receiver.
for block contexts, this is the methodcontext, where the block was created,
for nested block contexts, it's the surrounding block's context.
for method-contexts this is nil.

Usage example(s):

home

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

lineNumber

this returns the lineNumber within the method's source, where the context was
interrupted or called another method. (currently, sometimes this information
is not available - in this case 0 is returned)

Usage example(s):

nr := m lineNumber

Usage example(s):

nr := self method lineNumberForPC:l.

Usage example(s):

nr := m lineNumber

lineNumberFromMethod

logFacility

the 'log facility';
this is used by the Logger both as a prefix to the log message,
and maybe (later) used to filter and/or control per-facility log thresholds.
The default here is to base the facility on the package:
if the class is anywhere in the base ST/X system, 'STX' is returned as facility.
Otherwise, the last component of the package name is returned.

Usage example(s):

     thisContext logFacility
     thisContext sender logFacility

message

thisContext methodHome message
thisContext message

messageSend

thisContext methodHome messageSend
thisContext messageSend

method

return the method for which the receiver was created.
Change with ST/X vsn 6:
In older versions, the method was not stored in the context, but a lookup
was simulated using selector and class.
(which occasionally returned the wrong method - especially in the debugger,
when the debugged method was changed).
This has been changed - especially to support Jan's meta-object protocol.
It is now stored in the context

Usage example(s):

VM should have placed the method into the context

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;
For block contexts, this is the context of the containing method
(which could be a context which is no longer alive)

methodSelector

return the method's (or home method's) selector

ntemp

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

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

numArgs

marked as obsolete by Stefan Vogel at 9-Feb-2024

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

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 don't like the name of this method; its here for compatibility.

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

programmingLanguage

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 receiver's 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.
This little ugly piece of code is needed (instead of the obvious
'sender isNil') because sender is a protected field, which cannot be
directly accessed by smalltalk code. The reason is that the sender field
is lazily filled in by the VM, in the sender-accessor, and is usually
invalid until needed.

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

copying

deepCopyUsing: aDictionary postCopySelector: postCopySelector: (comment from inherited method)
a helper for deepCopy; return a copy of the object with
all subobjects also copied. If the to-be-copied object is in the dictionary,
use the value found there. The class of the receiver is not copied.
This method DOES handle cycles/self references.

enumerating

withAllSendersDo: aBlock: evaluate aBlock for me and all contexts of my sender chain
withSendersThroughContextForWhich: checkBlock do: aBlock: evaluate aBlock for me and all contexts of my sender chain,
until checkBlock returns true (incl. that last one)
withSendersUpToContextForWhich: checkBlock do: aBlock: evaluate aBlock for me and all contexts of my sender chain,
until checkBlock returns true, excl. that context.

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.
invalidReturnOrRestart: returnValue: this message is sent by the VM, when a method's or block's context
which was compiled non-returnable is about to return again,
or a non-restartable context is tried to be restarted.
In ST/X, not all contexts are restartable/returnable.
We raise a signal here, to allow catching of that situation.
invalidReturnOrRestartError: how with: value: common error reporter for restart/return errors

fixups

fixAllLineNumbers

internationalization support

resources

try to provide the resourcePack for internationalization
from:
the receiver
the class of the receiver.
(Parser >> #stringWithEmbeddedExpressions and stc generate code
to call this method for i'internationalized text' strings).

Usage example(s):

     thisContext resources
     AAA new test value.

minidebugger printing

fullPrint

print the receiver, selector and args of the context
- used only for MiniDebugger's walkback print

Usage example(s):

     thisContext fullPrint

fullPrintAll

print a full walkback starting at the receiver
- used only for MiniDebugger's walkback print

Usage example(s):

     thisContext fullPrintAll

fullPrintAllLevels: nOrNil

print a full walkback starting at the receiver, only print n levels
- used only for MiniDebugger's walkback print

Usage example(s):

     thisContext fullPrintAllLevels:5

printAll

print a full walkback starting at the receiver, only print n levels
- used only for MiniDebugger's walkback print

Usage example(s):

     thisContext printAll

printAllLevels: nOrNil

print a full walkback starting at the receiver, only print n levels
- used only for MiniDebugger's walkback print

Usage example(s):

     thisContext printAllLevels:5

savePrint

print the receiver-class and selector only
- used when there is a danger that printing results in errors

Usage example(s):

     thisContext fullPrint
     thisContext savePrint

non local control flow

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)
resend: EXPERIMENTAL: resend the context's message (to the same receiver).
if the method's implementation has been changed in the meanwhile (for example, in the debugger),
the new code is executed. Otherwise the same code is reexecuted from the start.
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 receiver's 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 receiver's 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 receiver's 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 did 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 block's 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.
unwindThenResend: EXPERIMENTAL: resend the context's message (to the same receiver).
if the method's implementation has been changed in the meanwhile (for example, in the debugger),
the new code is executed. Otherwise the same code is reexecuted from the start.
Evaluate all unwind-blocks as specified in Block>>valueNowOrOnUnwind:
and Block>>valueOnUnwindDo: on the way.
The resend happens AFTER all unwind actions are performed

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.

printing & storing

argStringFor: someObject

take care, do not evaluate lazy or do sends to
a bridge when showing backtrace. Especially not after
timeout of a bridge call!

argsDisplayString

Modified (format): / 07-03-2012 / 13:11:17 / cg

argsDisplayStringShort

displayArgsOn: aStream withCRs: withCRs indent: i

displayArgsOn: aStream withCRs: withCRs indent: i contractEachTo: limitOrNil

displayLocalsOn: aStream withCRs: withCRs indent: i

displayOn: aGCOrStream

return a string to display the receiver - for display in Inspector

fullPrintAllOn: aStream