Smalltalk/X Webserver

Documentation of class 'CompiledCode':

Class: CompiledCode

Inheritance
Description
Class protocol
Instance protocol

Inheritance:

   Object
   |
   +--ExecutableFunction
      |
      +--CompiledCode
         |
         +--Block
         |
         +--Method

Package:: stx:libbasic

Category:: Kernel-Methods

Version:: rev: 1.161 date: 2023/11/30 15:47:55; user: cg; file: CompiledCode.st directory: libbasic; module: stx stc-classLibrary: libbasic

Description:

This is an abstract class, to merge common attributes of Blocks and
Methods i.e. describe all objects consisting of either compiled or
interpreted code.

Instances of CompiledCode are not to be created by user code
(the compilers create Blocks, Methods etc.)

[Instance variables:]

flags <SmallInteger> special flag bits coded in a number
byteCode <ByteArray> bytecode if it's an interpreted codeobject

The block/methods literals are stored in the indexed instance variables.
If there is only one indexed instvar, it contains a reference to an
Object containing the literals.

[Class variables:]

NoByteCodeSignal raised if a codeObject is about to be executed
which has neither code nor byteCode (i.e. both are nil)
InvalidByteCodeSignal raised if byteCode is not an instance of ByteArray
InvalidInstructionSignal raised if an invalid instruction opcode is encountered
BadLiteralsSignal raised if literalArray is not an array
NonBooleanReceiverSignal raised for conditional jumps where receiver is not a boolean
ArgumentSignal raised if argument count is not what the codeObject expects

all of these signals are children of ExecutionErrorSignal.

NOTICE: layout known by runtime system and compiler - 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 title to or ownership of the software is
hereby transferred.

Class protocol:

Signal constants

wongNumberOfArgumentsSignal: return the signal raised when the number of arguments is wrong in a call

instance creation

new: create a new method with an indirect literal array
stored in the first and only indexed instvar
new: numberOfLiterals: create a new method with numberOfLiterals.
Implementation note:
If (self size) == 1, the only literal is an indirect literal
containing an array of literals. Otherwise the literals
are stored in self.

queries

isAbstract

Return if this class is an abstract class.
True is returned here for myself only; false for subclasses.
Abstract subclasses must redefine this again.

isBuiltInClass

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

maxNumberOfArguments

return the maximum number of arguments a method can have.
This is a limit in the VM, which may be removed in one of
the next versions ...

numArgsMaskInFlags

fallback if no primitive code

Usage example(s):

     self numArgsMaskInFlags

numArgsShiftInFlags

fallback if no primitive code

Usage example(s):

     self numArgsShiftInFlags

numVarsMaskInFlags

fallback if no primitive code

Usage example(s):

     self numVarsMaskInFlags

numVarsShiftInFlags

fallback if no primitive code

Usage example(s):

     self numVarsShiftInFlags

Instance protocol:

Compatibility-ANSI

argumentCount: ANSI alias for numArgs: return the number of arguments, the method expects.

Compatibility-ST80

getSource: return the code object's source code, nil if none is available
getSourceForUserIfNone: aBlock: return the code object's source code.
If none is available, return the result from evaluating aBlock.
initialPC
methodClass: return the class I am defined in
sourceString: return the code object's source code, nil if none is available
withAllBlockMethodsDo: aBlock

Compatibility-V'Age

bytecodes

accessing

allLiterals

return a collection of all literals (includes all block literals)

allSymbolLiterals

return a collection of all symbol-literals

byteCode

return the bytecode (a ByteArray)

changeLiteral: aLiteral to: newLiteral

change aLiteral to newLiteral

containingClass

return the class of the receiver's home method.
That's the class of the method where the block was compiled.

decompiledSource

reconstruct some synthetic source by decompiling by byteCode

decompilerClass

do: aBlock

same as #literalsDo:, in order to get common protocol with Array

flags

return the flags (number of method variables, stacksize etc.).
Don't depend on the values in the flag field - its interpretations
may change without notice.

homeMethod

for common protocol with blocks: if the receiver is a method,
return the receiver; otherwise, if it's a block, return its home
method.

literalAt: index

return a literal element

literalAt: index ifAbsent: exceptionalValue

return a literal element

literalAt: index put: newValue

change a literal slots value.
WARNING: dangerous internal interface; only for knowledgable users

literals

return the literals as an array

Usage example(s):

     (CompiledCode compiledMethodAt:#literals) literals

literalsDetect: aBlock ifNone: exceptionBlock

execute a one arg block for each of our literals.
Return the first literal for which aBlock returns true,
or the value from exceptionBlock, if either no literals or
none satisfied the block

literalsDo: aBlock

execute a one arg block for each of our literals

mclass

return the class of the receiver's home method.
That's the class of the method where the block was compiled.

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

numLiterals

return the number of literals I have

numberOfMethodArgs

return the number of arguments, the method expects.
This method is left for backward compatibility - use #argumentCount.

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

numberOfMethodVars

return the number of method local variables.
This method is left for backward compatibility - use #numVars.

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

source

** This method must be redefined in concrete classes (subclassResponsibility) **

compiler interface

compilerClass

who is responsible to parse the source code?
Fetch it from the class

Usage example(s):

     (Object compiledMethodAt:#at:) compilerClass

parserClass

who is responsible to parse the source code?
Fetch it from the class

Usage example(s):

     (Object compiledMethodAt:#at:) parserClass

programmingLanguage

the following is correct, but might be too slow...

Usage example(s):

^ mclass programmingLanguage

syntaxHighlighterClass

if #askClass is returned here, my owning class will be asked for the syntaxHighlighter.
if nil is returned, no syntaxHighlighting will be done.
Can be redefined in subclasses (MetaMethod) which use special syntax.

converting

makeRealMethod: by default, we are a real method.
Subclasses (e.g. LazyMethod) may redefine this

debugging

breakPointAfter: countInvocations: arrange for a breakpoint-debugger to be opened when this method
was invoked countInvocations times.
breakPointIf: conditionBlock: arrange for a breakpoint-debugger to be opened when this method
is invoked AND conditionBlock evaluates to true.
conditionBlock gets context and method as (optional) arguments.
breakPointInProcess: aProcess: arrange for a breakpoint-debugger to be opened when this method
is invoked from withn aProcess.
breakPointInProcess: aProcess withChildProcesses: withChildProcessesBoolean: arrange for a breakpoint-debugger to be opened when this method
is invoked from withn aProcess.
breakPointOnReturnIf: conditionBlock: arrange for a breakpoint-debugger to be opened when this method
returns AND conditionBlock evaluates to true.
conditionBlock gets returnValue, context and method as (optional) arguments.
clearBreakPoint: remove any break/trace-point on this method
isCounted: obsolete - replaced by isCountingMemoryUsage
isCounting: return true, if invokations of this method are counted
isCountingByReceiverClass: return true, if invokations of this method are counted
isCountingMemoryUsage: return true, if memory allocations done by this method (and callees)
are counted
isTiming: return true if timing statistics are being gathered on this method.
resetCountingStatistics: reset count statistics of the receiver
resetMemoryUsageStatistics: reset count statistics of the receiver
resetTimingStatistics: reset timing statistics of the receiver
setBreakPoint: arrange for a breakpoint-debugger to be opened when this method
is invoked.
setFullTracePoint: arrange for a full-backtrace to be sent to the standard-error stream
when this method is invoked.
setFullTracePointInProcess: aProcess: arrange for a full-backtrace to be sent to the standard-error stream
when this method is invoked by the given process.
setTraceFullPoint: arrange for a full-backtrace to be sent to the standard-error stream
when this method is invoked.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
setTracePoint: arrange for a trace-message to be sent to the standard-error stream
when this method is invoked.
setTraceSenderPoint: arrange for a sender-trace-message to be sent to the standard-error stream
when this method is invoked.
setTracelog
( an extension from the stx:libbasic3 package ): Arrange for a trace logging - enter/leave of the method will be logged using
current Logger
startCounting: start counting invokations of the receiver
startCountingByReceiverClass: start counting invokations of the receiver
startCountingMemoryUsage: start counting memory usage of the receiver (and every callee)
startMessageTally: set a MessageTally on the receiver
startTiming: start timing the receiver
stopCounting: stop counting calls of the receiver
stopCountingMemoryUsage: stop counting memory usage of the receiver
stopTiming: stop timing of the receiver

enumeration

breakpointsDo: aBlock: Evaluate `aBlock` for every breakpoint installed in this method

error handling

badArgumentArray: argsGiven: this error is triggered, if a non-array is passed to
#valueWithReceiver:.. type of methods
badLiteralTable: this error is triggered, when a block/method is called with a bad literal
array (i.e. non-array) - this can only happen, if the
compiler is broken or someone played around with a blocks/methods
literal table or the GC is broken and corrupted it.
interpretWithReceiver: aReceiver: invoked by VM for non-Smalltalk-methods (MetaMethods)
interpretWithReceiver: aReceiver arg: arg1: invoked by VM for non-Smalltalk-methods (MetaMethods)
interpretWithReceiver: aReceiver arg: arg1 arg: arg2: invoked by VM for non-Smalltalk-methods (MetaMethods)
interpretWithReceiver: aReceiver arg: arg1 arg: arg2 arg: arg3: invoked by VM for non-Smalltalk-methods (MetaMethods)
interpretWithReceiver: aReceiver arguments: argVector: invoked by VM for non-Smalltalk-methods (MetaMethods)

** This method must be redefined in concrete classes (subclassResponsibility) **
invalidByteCode: this error is triggered when the interpreter tries to execute a
code object, where the byteCode is nonNil, but not a ByteArray.
Can only happen when Compiler/runtime system is broken or
someone played around with a blocks/methods code.
invalidInstruction: this error is triggered when the bytecode-interpreter tries to
execute an invalid bytecode instruction.
Can only happen when Compiler/runtime system is broken or
someone played around with a blocks/methods code.
noByteCode: this error is triggered when the interpreter tries to execute a
code object, where both the code and byteCode instances are nil.
This can happen if:
- the Compiler/runtime system is broken, (should not happen)

- someone played around with a block/method, (you should not do this)

- compilation of a lazy method failed
(i.e. the lazy method contains an error or
it contains primitive code and there is no stc compiler available)

- an unloaded object modules method is called for.

Only the first case is to be considered serious
- it should not happen if the system is used correctly.
receiverNotBoolean: anObject: this error is triggered when the bytecode-interpreter tries to
execute ifTrue:/ifFalse or whileTrue: - type of expressions where the
receiver is neither true nor false.
Machine compiled code does not detect this, and may behave undeterministec.
tooManyArguments: this error is triggered, when a method/block tries to perform a send with
more arguments than supported by the interpreter.
This can only happen, if the compiler has been changed without
updating the VM, since the compiler checks for allowed number of
arguments.
wrongNumberOfArguments: numArgsGiven: this error is triggered by the VM, if a method is called with a wrong number
of arguments.
This only applies to #valueWithReceiverXXX and #perform:withArguments: - sends.
With a normal send, this error cannot happen.

executing

valueWithReceiver: anObject

low level call of a method's code - BIG DANGER ALERT.
Perform the receiver-method on anObject as receiver and no arguments.
This does NO message lookup at all and mimics a traditional function call.
This method is provided for debugging- and breakpoint-support
(replacing a method by a stub and recalling the original), or to implement
experimental MI implementations - it is not for general use.

The receiver must be a method compiled in anObject's class or one of its
superclasses and also, the number of arguments given must match the method's
expectations -
- otherwise strange things (and also strange crashes) can occur.
The system is NOT always detecting a wrong method/receiver combination.
YOU HAVE BEEN WARNED.

valueWithReceiver: anObject arguments: argArray

low level call of a method's code - BIG DANGER ALERT.
Perform the receiver-method on anObject as receiver and argArray as arguments.
This does NO message lookup at all and mimics a traditional function call.
This method is provided for debugging- and breakpoint-support
(replacing a method by a stub and recalling the original), or to implement
experimental MI implementations - it is not for general use.

The receiver must be a method compiled in anObject's class or one of its
superclasses and also, the number of arguments given must match the method's
expectations -
- otherwise strange things (and also strange crashes) can occur.
The system is NOT always detecting a wrong method/receiver combination.
YOU HAVE BEEN WARNED.

valueWithReceiver: anObject arguments: argArray selector: aSymbol

valueWithReceiver: anObject arguments: argArray selector: aSymbol search: aClass

valueWithReceiver: anObject arguments: argArray selector: aSymbol search: aClass sender: virtualSender

low level call of a method's code - BIG DANGER ALERT.
Perform the receiver-method on anObject as receiver and argArray as arguments.
This does NO message lookup at all and mimics a traditional function call.
This method is provided for debugging- and breakpoint-support
(replacing a method by a stub and recalling the original), or to implement
experimental MI implementations - it is not for general use.

The receiver must be a method compiled in anObject's class or one of its
superclasses and also, the number of arguments given must match the methods
expectations -
- otherwise strange things (and also strange crashes) can occur.
The system is NOT always detecting a wrong method/receiver combination.
YOU HAVE BEEN WARNED.

Usage example(s):

     (Float compiledMethodAt:#+)
        valueWithReceiver:1.0 arguments:#(2.0)

     'the next example is a wrong one - which is detected by True's method ...'.
     (True compiledMethodAt:#printString)
        valueWithReceiver:false arguments:nil

     'the next example is a wrong one - it is nowhere detected
      and a wrong value returned ...'.
     (Point compiledMethodAt:#x)
        valueWithReceiver:(1->2) arguments:nil

     'the next example is VERY bad one - it is nowhere detected
      and may crash the system WARNING: save your work before doing this ...'.
     (Point compiledMethodAt:#x)
        valueWithReceiver:(Object new) arguments:nil

     'the next example is a wrong one - which is detected here ...'.
     (Object compiledMethodAt:#printOn:)
        valueWithReceiver:false arguments:nil

     'the next example is a wrong one - which is detected here ...'.
     (Object compiledMethodAt:#printOn:)
        valueWithReceiver:false arguments:#()

private-accessing

byteCode: aByteArray: set the bytecode field - DANGER ALERT
checked: aBoolean: set/clear the flag bit stating that this method has already been checked
by the just-in-time compiler.
Setting the flag prevents it from trying any compilation.
Not for public use - for VM debugging only.
clearJittedCodeAndForceJittingAgain: clear the method's jitted code and clear the flag bit stating that this method has already been checked
by the just-in-time compiler. Thus, it will be recompiled when called the next time.
Not for public use - for VM debugging only.
dynamic: marked as obsolete by Stefan Vogel at 21-Sep-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **
literals: aLiteralArray: set the literal array for evaluation - DANGER ALERT
markFlag: return the mark bits value as a boolean.
This bit is not used by the VM, but instead free to mark codeObjects
for any (debugging/tracing) use. For example, the coverage test uses
these to mark reached methods. (inspired by a note in c.l.s)
markFlag: aBoolean: set/clear the mark flag bit.
This bit is not used by the VM, but instead free to mark codeObjects
for any (debugging/tracing) use. For example, the coverage test uses
these to mark reached methods. (inspired by a note in c.l.s)

private-compiler interface

contextMustBeReturnable: aBoolean
flags: newFlags: set the flags (number of method variables, stacksize).
WARNING: for internal use by the compiler only.
playing around here with incorrect values
may crash smalltalk badly.

Don't depend on the values in the flag field - its interpretations
may change without notice.
marked: aBoolean: Sets the mark bit. You may use it for whatever you want. Actually,
it's used for marking profiled methods
numberOfArgs: aNumber: set the number of arguments, the codeObject expects.
WARNING: for internal use by the compiler only.
playing around here with incorrect values
may (will ?) crash smalltalk badly.

The limitation in the max. number of arguments is due to the
missing SENDxx functions in the VM and cases in #perform. This too
will be removed in a later release, allowing any number of arguments.
numberOfVars: aNumber: set the number of local variables - for use by compiler only.
WARNING: for internal use by the compiler only.
playing around here with incorrect values
may (will ?) crash smalltalk badly.
stackSize: return thedepth of the local stack in the context.

WARNING: for internal use by ST/X debuggers only.
This method may be removed without notice.
stackSize: aNumber: set the depth of the local stack.

WARNING: for internal use by the compiler only.
playing around here with incorrect values
may crash smalltalk badly.
if the runtime library was compiled with DEBUG,
a bad stack will be detected and triggers an error
(by default, the VM is compiled with this option)

queries

decompileTo: aStream

hasAnnotation: key

Return false here, as a fallback

isChecked

return true, if this method has been analyzed for jitting

isDynamic

return true, if the machine code was created
dynamically (from bytecode); false if the machine code was
already present in an objectFile
(i.e. has JIT-compiled machineCode, as opposed to stc-compiled code).

isExecutable

return true, if this method is executable.
I.e. neither an invalidated nor an unloaded method

isExtension

return true, if this method is an extension (i.e. package ~= classes' package)

isMarked

return true, if this method has been marked (for whatever reason)

isUnloaded

return true, if the method's machine code has been unloaded
from the system (i.e. it is not executable).

messages

return a Set of all symbols referenced by this thingy.
(this is more than the message selectors, since also global names
and symbols found in immediate arrays are included).

Usage example(s):

     (CompiledCode compiledMethodAt:#messages) messages

numArgs

but left in for a while, for performance

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

numVars

return the number of block local variables.
Do not depend on the returned value - future optimizations
may change things here (i.e. when moving locals into
surrounding context for inlining).
- for debugging only.

referencesGlobal: aGlobalSymbol

return true, if this method references the global named aGlobalSymbol.
For now, this is the same as #referencesLiteral:,
but this might change in the future to perform a deeper
analyzes on the bytecodes, to detect implicit global
refs (as done by some special bytecodes)

Usage example(s):

     (CompiledCode compiledMethodAt:#referencesGlobal:) referencesGlobal:#referencesLiteral:
     (CompiledCode compiledMethodAt:#referencesGlobal:) referencesGlobal:#bla

referencesGlobalMatching: aMatchPattern

return true, if this method references the given a literal symbol,
which matches the given pattern.

Usage example(s):

     (CompiledCode compiledMethodAt:#referencesGlobalMatching:) referencesGlobalMatching:'*atch*'
     (CompiledCode compiledMethodAt:#referencesGlobalMatching:) referencesGlobalMatching:'*batch*'

referencesLiteral: aLiteral

return true, if this method references the given literal directly
(i.e. a flat search, which does not look deeper into literal arrays).

Usage example(s):

     (CompiledCode compiledMethodAt:#referencesLiteral:) referencesGlobal:#literalsDetect:ifNone:
     (CompiledCode compiledMethodAt:#referencesLiteral:) referencesGlobal:#bla

refersToLiteral: aLiteral

return true if the receiver, or recursively any array element in the receiver,
refers to aLiteral (i.e. a deep search)

Usage example(s):

     (CompiledCode compiledMethodAt:#refersToLiteral:) refersToLiteral:#foo
     (CompiledCode compiledMethodAt:#refersToLiteral:) refersToLiteral:#class

refersToLiteralMatching: aMatchPattern

return true if the receiver, or recursively any array element in the receiver,
is symbolic and matches aMatchPattern (i.e. a deep search)

Usage example(s):

     (CompiledCode compiledMethodAt:#refersToLiteralMatching:) refersToLiteral:'is*'
     (CompiledCode compiledMethodAt:#refersToLiteralMatching:) refersToLiteral:'foo*'

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 04:35:32 GMT