Smalltalk/X Webserver

Documentation of class 'MessageTracer':

Class: MessageTracer

Inheritance
Description
Class protocol
Instance protocol
- trace helpers
Private classes
Examples

Inheritance:

   Object
   |
   +--MessageTracer
      |
      +--MessageTracer::InteractionCollector
      |
      +--MessageTracer::PrintingMessageTracer

Package:: stx:libbasic3

Category:: System-Debugging-Support

Version:: rev: 1.154 date: 2019/08/12 09:53:37; user: cg; file: MessageTracer.st directory: libbasic3; module: stx stc-classLibrary: libbasic3

Author:: Claus Gittinger

Description:

This class provides a common home for the tracing
facilities (originally, they where in Object, but have been moved to
allow easier separation of development vs. runtime configurations).

tracing execution of a block:

    MessageTracer trace:[ ... ]

    MessageTracer traceFull:[ ... ]

    (for system developer only:)

    MessageTracer debugTrace:[ ... ]


trapping sends to a specific object:

    MessageTracer trap:anObject selector:aSelector
    ...
    MessageTracer untrap:anObject selector:aSelector
    or:
    MessageTracer untrap:anObject



trapping some messages sent to a specific object:

    MessageTracer trap:anObject selectors:aCollectionOfSelectors
    ...
    MessageTracer untrap:anObject



trapping any message sent to a specific object:

    MessageTracer trapAll:anObject
    ...
    MessageTracer untrap:anObject



trapping evaluation of a specific method:

    MessageTracer trapMethod:aMethod
    ...
    MessageTracer unwrapMethod:aMethod



trapping evaluation of a specific method with
receiver being an instance of some class:

    MessageTracer trapMethod:aMethod forInstancesOf:aClass
    ...
    MessageTracer unwrapMethod:aMethod



tracing sends to a specific object:

    MessageTracer trace:anObject selector:aSelector
    ...
    MessageTracer untrace:anObject selector:aSelector
    or:
    MessageTracer untrace:anObject



tracing sender only:

    MessageTracer traceSender:anObject selector:aSelector
    ...
    MessageTracer untrace:anObject selector:aSelector
    or:
    MessageTracer untrace:anObject



tracing evaluation of a specific method:

    MessageTracer traceMethod:aMethod
    ...
    MessageTracer unwrapmethod:aMethod

  see more in examples and in method comments.

Class protocol:

Signal constants

breakpointSignal
objectWrittenBreakpointSignal

class initialization

initialize

BreakpointSignal := HaltSignal newSignalMayProceed:true.

usage example(s):

     BreakpointSignal := nil.
     MessageTracer initialize

update: something with: parameter from: changedObject

sent when restarted after a snapIn

class tracing

untraceAllClasses: remove all traces of messages sent to any class
untraceClass: aClass: remove all traces of messages sent to instances of aClass

class wrapping

wrapClass: orgClass selector: aSelector onEntry: entryBlock onExit: exitBlock

arrange for the two blocks entryBlock and exitBlock to be evaluated whenever
aSelector is sent to instances of orgClass or subclasses.
EntryBlock will be called on entry, and get the current context passed as argument.
ExitBlock will be called, when the method is left, and get context and the method's return value as arguments.

usage example(s):

     MessageTracer
                wrapClass:Point
                 selector:#scaleBy:
                   onEntry:nil
                    onExit:[:con :retVal |
                               Transcript show:'leave Point>>scaleBy:; returning:'.
                               Transcript showCR:retVal printString.
                               Transcript endEntry
                           ].
     (1@2) scaleBy:5.
     MessageTracer untrapClass:Point selector:#scaleBy:.
     (1@2) scaleBy:5.

usage example(s):

     MessageTracer
                wrapClass:Integer
                 selector:#factorial
                   onEntry:[:con |
                               Transcript showCR:('entering ' , con receiver printString , '>>factorial').
                           ]
                    onExit:[:con :retVal |
                               Transcript show:'leave Integer>>factorial; returning:'.
                               Transcript showCR:retVal printString.
                               Transcript endEntry
                           ].
     Transcript showCR:'5 factorial traced'.
     5 factorial.
     MessageTracer untrapClass:Integer selector:#factorial.
     Transcript showCR:'5 factorial normal'.
     5 factorial.

cleanup

if you forgot which classes/methods where wrapped and/or trapped,
this cleans up everything ...

usage example(s):

     MessageTracer cleanup

execution trace

debugTrace: aBlock

trace execution of aBlock. This is for system debugging only;
The trace output is a low level trace generated in the VM.

usage example(s):

     MessageTracer debugTrace:[#(6 5 4 3 2 1) sort]

trace: aBlock

evaluate aBlock sending trace information to stdout.
Return the value of the block.

usage example(s):

     MessageTracer trace:[#(6 5 4 3 2 1) sort]

trace: aBlock on: aStream

evaluate aBlock sending trace information to stdout.
Return the value of the block.

usage example(s):

     MessageTracer trace:[#(6 5 4 3 2 1) sort] on:Transcript

traceFull: aBlock

evaluate aBlock sending trace information to stdout.
Return the value of the block.
The trace information is more detailed.

usage example(s):

     MessageTracer traceFull:[#(6 5 4 3 2 1) sort]

traceFull: aBlock on: aStream

evaluate aBlock sending trace information to stdout.
Return the value of the block.
The trace information is more detailed.

usage example(s):

     MessageTracer traceFull:[#(6 5 4 3 2 1) sort]

traceFullIndented: aBlock

evaluate aBlock sending trace information to stdout.
Return the value of the block.
The trace information is more detailed.

usage example(s):

     MessageTracer traceFullIndented:[ #(6 5 4 3 2 1) sort ]

traceFullIndented: aBlock on: aStream

evaluate aBlock sending trace information to aStream.
Return the value of the block.
The trace information is more detailed.

usage example(s):

     MessageTracer traceFullIndented:[ #(6 5 4 3 2 1) sort ]

traceIndented: aBlock

evaluate aBlock sending trace information to stdout.
Return the value of the block.

usage example(s):

     MessageTracer traceIndented:[ #(6 5 4 3 2 1) sort ]

traceIndented: aBlock on: aStream

evaluate aBlock sending trace information to aStream.
Return the value of the block.

usage example(s):

     MessageTracer traceIndented:[ #(6 5 4 3 2 1) sort ] on:Transcript

method breakpointing

trapClass: aClass selector: aSelector

arrange for the debugger to be entered when a message with aSelector is
sent to instances of aClass (or subclass instances). Use untrapClass to remove this trap.
Be careful, to not place a trap on code needed in the debugger (i.e. on scrollBars etc.);
if there is a need to trap those, use the low-level wrap-methods, and put a check into the
entry/leave blocks.

usage example(s):

     MessageTracer trapClass:Collection selector:#select:.
     Dictionary new select:[:e | ].       'not caught - Dictionary has its own select'.
     (Array new:10) select:[:e | ].       'not caught - SeqColl has its own select'.
     Set new select:[:e | ].              'caught - Set inherits this from Collection'.
     MessageTracer untrapClass:Collection

trapMethod: aMethod

arrange for the debugger to be entered when aMethod is about to be executed.
The trap is enabled for any process - see #trapMethod:inProcess: for a more
selective breakPoint.
Use unwrapMethod or untrapClass to remove this trap.
Be careful, to not place a trap on code needed in the debugger (i.e. on scrollBars etc.);
if there is a need to trap those, use the low-level wrap-methods, and put a check into the
entry/leave blocks.

usage example(s):

     MessageTracer trapMethod:(Collection compiledMethodAt:#select:).
     Dictionary new select:[:e | ].       'not caught - Dictionary has its own select'.
     (Array new:10) select:[:e | ].       'not caught - SeqColl has its own select'.
     Set new select:[:e | ].              'caught - Set inherits this from Collection'.
     MessageTracer unwrapMethod:(Collection compiledMethodAt:#select:).

trapMethod: aMethod after: countInvocations

arrange for the debugger to be entered when aMethod has been invoked countInvocations times.
The trap is enabled for any process.
Use unwrapMethod or untrapClass to remove this trap.
Be careful, to not place a trap on code needed in the debugger (i.e. on scrollBars etc.);
if there is a need to trap those, use the low-level wrap-methods, and put a check into the
entry/leave blocks.

trapMethod: aMethod forInstancesOf: aClass

arrange for the debugger to be entered when aMethod is about to be executed
for an instance of aClass.
Use unwrapMethod or untrapClass to remove this trap.
Be careful, to not place a trap on code needed in the debugger (i.e. on scrollBars etc.);
if there is a need to trap those, use the low-level wrap-methods, and put a check into the
entry/leave blocks.

usage example(s):

     MessageTracer trapMethod:(View compiledMethodAt:#redraw) forInstancesOf:myView.

trapMethod: aMethod if: conditionBlock

arrange for the debugger to be entered when aMethod has been invoked and conditionBlock
evaluates to true.
conditionBlock gets context and method as (optional) arguments.
The trap is enabled for any process.
Use unwrapMethod or untrapClass to remove this trap.
Be careful, to not place a trap on code needed in the debugger (i.e. on scrollBars etc.);
if there is a need to trap those, use the low-level wrap-methods, and put a check into the
entry/leave blocks.

trapMethod: aMethod inProcess: aProcess

arrange for the debugger to be entered when aMethod is about to be executed,
but only, if executed aProcess or one of aProcess's offspring.
This allows for breakpoints to be set on system-critical code.
The trap will only fire for selected processes (making browsers etc. still usable).
Use unwrapMethod or untrapClass to remove this trap.
Be careful, to not place a trap on code needed in the debugger (i.e. on scrollBars etc.);
if there is a need to trap those, use the low-level wrap-methods, and put a check into the
entry/leave blocks.

trapMethod: aMethod onReturnIf: conditionBlock

arrange for the debugger to be entered when aMethod returns
and conditionBlock evaluates to true.
conditionBlock gets retVal, context and method as (optional) arguments.
The trap is enabled for any process.
Use unwrapMethod or untrapClass to remove this trap.
Be careful, to not place a trap on code needed in the debugger (i.e. on scrollBars etc.);
if there is a need to trap those, use the low-level wrap-methods, and put a check into the
entry/leave blocks.

untrapAllClasses

remove any traps on any class

usage example(s):

     MessageTracer untrapAllClasses

untrapClass: aClass

remove any traps on aClass

usage example(s):

     MessageTracer untrapClass:Point

untrapClass: aClass selector: aSelector

remove trap of aSelector sent to aClass

usage example(s):

     MessageTracer trapClass:Point selector:#copy.
     (1@2) copy.
     (1@2) deepCopy.
     MessageTracer trapClass:Point selector:#deepCopy.
     (1@2) copy.
     (1@2) deepCopy.
     MessageTracer untrapClass:Point selector:#copy.
     (1@2) copy.
     (1@2) deepCopy.
     MessageTracer untrapClass:Point selector:#deepCopy.
     (1@2) copy.
     (1@2) deepCopy.

untrapMethod: aMethod

remove break on aMethod

method breakpointing - new

breakMethod: method atLine: line: Installs new breakpoint in given method at given line.
Returns the installed breakpoint or nil if none could be
installed

method counting

countMethod: aMethod

arrange for a aMethod's execution to be counted.
Use unwrapMethod to remove this.

usage example(s):

     MessageTracer countMethod:(Integer compiledMethodAt:#factorial).
     5 factorial.
     MessageTracer executionCountOf:(Integer compiledMethodAt:#factorial) printNL.
     MessageTracer stopCountingMethod:(Integer compiledMethodAt:#factorial)

countMethodByReceiverClass: aMethod

arrange for a aMethod's execution to be counted and maintain
a per-receiver class profile.
Use unwrapMethod to remove this.

executionCountOfMethod: aMethod

return the current count

executionCountsByReceiverClassOfMethod: aMethod

return a collection mapping receiver class to call counts

resetCountOfMethod: aMethod

return the current count

stopCountingMethod: aMethod

remove counting of aMethod

method memory usage

countMemoryUsageOfMethod: aMethod

arrange for aMethod's memory usage to be counted.
Use unwrapMethod to remove this.

usage example(s):

     MessageTracer countMemoryUsageOfMethod:(Integer compiledMethodAt:#factorialR).
     3 factorialR.
     Transcript showCR:(MessageTracer memoryUsageOfMethod:(Integer compiledMethodAt:#factorialR)).
     MessageTracer stopCountingMemoryUsageOfMethod:(Integer compiledMethodAt:#factorialR)

isCountingMemoryUsage: aMethod

return true if aMethod is counting memoryUsage

memoryUsageOfMethod: aMethod

return the current count

resetMemoryUsageOfMethod: aMethod

reset the current usage

stopCountingMemoryUsageOfMethod: aMethod

remove counting memory of aMethod

method mocking

mock: selector in: class do: block

mockMethod: method do: block

Temporarily change the behaviour of the given method to perform the given block instead
of the method's code. The value of the block is returned as the method's return value.
The behaviour is changed only for current thread, i.e., thread the calling this methood
and its child threads.

The block gets the receiver as the first argument, followed by method parameters
and then - optionally - the original method object.

Do not forget to 'unmock' by means of #unmockMethod: or #unmockAllMethods

CAVEAT: The 'current thread and its child threads' detection is done by walking
threads along their #creatorId. However, when the parent thread dies,
the link if broken and thus 'and its child threads' may not work 100%.
For the calling thread itself, mocking should work reliably.

usage example(s):

     MessageTracer
                mockMethod:(Color class compiledMethodAt:#magenta)
                do: [ :color |
                    Color red
                ].
     Color magenta.
     [ [ Color magenta inspect ] fork. Delay waitForSeconds: 1. ] fork.
     (Color class compiledMethodAt:#magenta) isMocked.
     MessageTracer unwrapMethod:(Color class compiledMethodAt:#magenta).
     Color magenta.

unmock: selector in: class

unmockAllMethods

Remove mocking wrapper from all methods, unconditionally.
May (should) be called in tearDdown of each testcase that
uses method mocking

unmockMethod: method

Remove mocking wrapper from a method, if it has been mocked by
#mockMethod:do:

method profiling

spyMethod: aMethod: arrange for given method to collect profiling data
using message tally profiler.
Use unwrapMethod to remove this.
spyMethod: aMethod interval: anInteger: arrange for given method to collect profiling data
using message tally profiler.
Use unwrapMethod to remove this.

method timing

executionTimesOfMethod: aMethod

return the current gathered execution time statistics

resetExecutionTimesOfMethod: aMethod

reset the gathered execution times statistics for aMethod;
the method remains wrapped.

stopTimingMethod: aMethod

remove timing of aMethod

timeMethod: aMethod

arrange for a aMethod's execution time to be measured.
Use unwrapMethod: or stopTimingMethod: to remove this.

usage example(s):

     MessageTracer timeMethod:(Integer compiledMethodAt:#factorial).
     5 factorial.
     5 factorial.
     5 factorial.
     (MessageTracer executionTimesOfMethod:(Integer compiledMethodAt:#factorial)) printCR.
     MessageTracer stopTimingMethod:(Integer compiledMethodAt:#factorial)

method tracing

traceClass: aClass selector: aSelector

arrange for a trace message to be output on Stderr, when a message with aSelector is
sent to instances of aClass (or subclass instances). Use untraceClass to remove this.

usage example(s):

     MessageTracer traceClass:Integer selector:#factorial.
     5 factorial.
     MessageTracer untraceClass:Integer

usage example(s):

     MessageTracer traceClass:SequenceableCollection selector:#quickSortFrom:to:.
     #(6 1 9 66 2 17) copy sort.
     MessageTracer untraceClass:SequenceableCollection

usage example(s):

     MessageTracer traceClass:Array selector:#at:.
     MessageTracer traceClass:Array selector:#at:put:.
     #(6 1 9 66 2 17) copy sort.
     MessageTracer untraceClass:Array

traceClass: aClass selector: aSelector on: aStream

arrange for a trace message to be output on aStream, when a message with aSelector is
sent to instances of aClass (or subclass instances). Use untraceClass to remove this.

usage example(s):

     MessageTracer traceClass:Integer selector:#factorial on:Transcript.
     5 factorial.
     MessageTracer untraceClass:Integer

usage example(s):

     MessageTracer traceClass:Integer selector:#factorialR on:Transcript.
     5 factorialR.
     MessageTracer untraceClass:Integer

traceMethod: aMethod

arrange for a trace message to be output on Stderr,
when aMethod is executed. Traces both entry and exit.
Use unwrapMethod to remove this.

usage example(s):

     MessageTracer traceMethod:(Integer compiledMethodAt:#factorial).
     5 factorial.
     MessageTracer untraceMethod:(Integer compiledMethodAt:#factorial)

usage example(s):

     MessageTracer traceMethod:(Integer compiledMethodAt:#factorialR).
     5 factorialR.
     MessageTracer untraceMethod:(Integer compiledMethodAt:#factorialR)

usage example(s):

     MessageTracer traceMethod:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:).
     #(6 1 9 66 2 17) copy sort.
     MessageTracer untraceMethod:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:).

usage example(s):

     MessageTracer traceMethod:(Object compiledMethodAt:#at:).
     MessageTracer traceMethod:(Object compiledMethodAt:#at:put:).
     #(6 1 9 66 2 17) copy sort.
     MessageTracer untraceMethod:(Object compiledMethodAt:#at:).
     MessageTracer untraceMethod:(Object compiledMethodAt:#at:put:).

traceMethod: aMethod inProcess: aProcess on: aStream

arrange for a trace message to be output on aStream,
when aMethod is executed. Traces both entry and exit.
Use unwrapMethod to remove this.

usage example(s):

     MessageTracer traceMethod:(Integer compiledMethodAt:#factorial) on:Transcript.
     5 factorial.
     MessageTracer untraceMethod:(Integer compiledMethodAt:#factorial)

usage example(s):

     MessageTracer traceMethod:(Integer compiledMethodAt:#factorialR) on:Transcript.
     5 factorialR.
     MessageTracer untraceMethod:(Integer compiledMethodAt:#factorialR)

usage example(s):

     MessageTracer traceMethod:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:) on:Transcript.
     #(6 1 9 66 2 17) copy sort.
     MessageTracer untraceMethod:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:).

traceMethod: aMethod on: aStream

arrange for a trace message to be output on aStream,
when aMethod is executed. Traces both entry and exit.
Use unwrapMethod to remove this.

usage example(s):

     MessageTracer traceMethod:(Integer compiledMethodAt:#factorial) on:Transcript.
     5 factorial.
     MessageTracer untraceMethod:(Integer compiledMethodAt:#factorial)

usage example(s):

     MessageTracer traceMethod:(Integer compiledMethodAt:#factorialR) on:Transcript.
     5 factorialR.
     MessageTracer untraceMethod:(Integer compiledMethodAt:#factorialR)

usage example(s):

     MessageTracer traceMethod:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:) on:Transcript.
     #(6 1 9 66 2 17) copy sort.
     MessageTracer untraceMethod:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:).

traceMethodAll: aMethod

arrange for a full trace message to be output on Stderr, when aMethod is executed.
Only the sender is traced on entry.
Use untraceMethod to remove this trace.
This is for system debugging only;
The trace output is a low level trace generated in the VM.

traceMethodEntry: aMethod

arrange for a trace message to be output on stdErr,
when aMethod is executed. Only entry is traced.
Use unwrapMethod to remove this.

usage example(s):

     MessageTracer traceMethodEntry:(Integer compiledMethodAt:#factorial).
     5 factorial.
     MessageTracer untraceMethod:(Integer compiledMethodAt:#factorial)

usage example(s):

     MessageTracer traceMethodEntry:(Integer compiledMethodAt:#factorialR).
     5 factorialR.
     MessageTracer untraceMethod:(Integer compiledMethodAt:#factorialR)

usage example(s):

     MessageTracer traceMethodEntry:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:).
     #(6 1 9 66 2 17) copy sort.
     MessageTracer untraceMethod:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:).

traceMethodEntry: aMethod on: aStream

arrange for a trace message to be output on aStream,
when aMethod is executed. Only entry is traced.
Use unwrapMethod to remove this.

usage example(s):

     MessageTracer traceMethodEntry:(Integer compiledMethodAt:#factorial) on:Transcript.
     5 factorial.
     MessageTracer untraceMethod:(Integer compiledMethodAt:#factorial)

usage example(s):

     MessageTracer traceMethodEntry:(Integer compiledMethodAt:#factorialR) on:Transcript.
     5 factorialR.
     MessageTracer untraceMethod:(Integer compiledMethodAt:#factorialR)

usage example(s):

     MessageTracer traceMethodEntry:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:) on:Transcript.
     #(6 1 9 66 2 17) copy sort.
     MessageTracer untraceMethod:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:).

traceMethodFull: aMethod

arrange for a full trace message to be output on Stderr, when amethod is executed.
Only the sender is traced on entry.
Use untraceMethod to remove this trace.

traceMethodFull: aMethod inProcess: aProcess on: aStream

arrange for a full trace message to be output on aStream, when aMethod is executed.
Only the sender is traced on entry.
Use untraceMethod to remove this trace.

traceMethodFull: aMethod on: aStream

arrange for a full trace message to be output on aStream, when aMethod is executed.
Only the sender is traced on entry.
Use untraceMethod to remove this trace.

traceMethodSender: aMethod

arrange for a trace message to be output on Stderr,
when amethod is executed.
Only the sender is traced on entry.
Use untraceMethod to remove this trace.

traceMethodSender: aMethod on: aStream

arrange for a trace message to be output on aStream, when amethod is executed.
Only the sender is traced on entry.
Use untraceMethod to remove this trace.

traceUpdateMethod: aMethod on: aStream

arrange for a trace message to be output on aStream,
when aMethod is executed.
Traces both entry and exit.
Use unwrapMethod to remove this.
This one is specialized for change-update calling i.e. it traces from the update
back to the origial change message.

tracelogMethod: aMethod

arrange for a trace log entry to be appended to a standard log using
Logger, when aMethod is executed. Traces both entry and exit.
Use unwrapMethod to remove this.

untraceMethod: aMethod

remove tracing of aMethod

method wrapping

unwrapAllMethods

just in case you don't know what methods have break/trace-points
on them; this removes them all

usage example(s):

     MessageTracer unwrapAllMethods

unwrapMethod: aMethod

remove any wrapper on aMethod

wrapMethod: aMethod onEntry: entryBlock onExit: exitBlock

wrapMethod: aMethod onEntry: entryBlock onExit: exitBlock onUnwind: unwindBlock

arrange for the two blocks entryBlock and exitBlock to be evaluated whenever
aMethod is evaluated.
EntryBlock will be called on entry, and gets the current context passed as argument.
ExitBlock will be called, when the method is left, and gets the context and
the method's return value as arguments.
UnwindBlock will be called when the contxt of aMethod is unwound.
If there is an unwindBlock, the entry and exitBlocks will be called within the unwind block,
because allocating the unwindBlock uses memory and some users want to count allocated memory.

usage example(s):

     MessageTracer
                wrapMethod:(Point compiledMethodAt:#scaleBy:)
                   onEntry:nil
                    onExit:[:con :retVal |
                               Transcript show:'leave Point>>scaleBy:; returning:'.
                               Transcript showCR:retVal printString.
                               Transcript endEntry
                           ].
     (1@2) scaleBy:5.
     MessageTracer unwrapMethod:(Point compiledMethodAt:#scaleBy:).
     (1@2) scaleBy:5.

usage example(s):

     MessageTracer
                wrapMethod:(Integer compiledMethodAt:#factorial)
                   onEntry:[:con |
                               Transcript showCR:('entering ' , con receiver printString , '>>factorial').
                           ]
                    onExit:[:con :retVal |
                               Transcript show:'leave Integer>>factorial; returning:'.
                               Transcript showCR:retVal printString.
                               Transcript endEntry
                           ].
     Transcript showCR:'5 factorial traced'.
     5 factorial.
     MessageTracer unwrapMethod:(Integer compiledMethodAt:#factorial).
     Transcript showCR:'5 factorial normal'.
     5 factorial.

wrapMethod: aMethod onEntryCode: entryCode onExitCode: exitCode

wrapMethod: aMethod onEntryCode: entryCode onExitCode: exitCode onUnwindCode: unwindCode

arrange for the entryCode and exitCode to be evaluated whenever
aMethod is evaluated.
EntryCode will be executed on entry, exitCode when the method is left.
UnwindCode will be executed when the context of aMethod is unwound.

Because the code is sliced in, it may return.
Useful to wrap existing methods with before and after code.

usage example(s):

     MessageTracer
                wrapMethod:(Point compiledMethodAt:#scaleBy:)
                onEntryCode:'Transcript showCR:''hello'' '
                onExitCode:'Transcript showCR:''good bye'' '.

     (1@2) scaleBy:5.
     MessageTracer unwrapMethod:(Point compiledMethodAt:#scaleBy:).
     (1@2) scaleBy:5.

object breakpointing

objectHasWraps: anObject: return true, if anObject has any wraps
realClassOf: anObject: return anObjects real class
trap: anObject selector: aSelector: arrange for the debugger to be entered when a message with aSelector is
sent to anObject. Use untrap to remove this trap.
The current implementation does not allow integers or nil to be trapped.
trap: anObject selectors: aCollection
trapAll: anObject: trap on all messages which are understood by anObject
trapAll: anObject from: aClass: trap on all messages defined in aClass sent to anObject
untrap: anObject: remove any traps on anObject
untrap: anObject selector: aSelector: remove trap on aSelector from anObject
wrappedSelectorsOf: anObject: return the set of wrapped selectors (if any)

object modification traps

trapModificationsIn: anObject

trap modifications in anObject

trapModificationsIn: anObject filter: aFilterBlock

trap modifications in anObject

usage example(s):

trap if arrays 5th slot is modified:

     |a|

     a := Array new:10.
     MessageTracer trapModificationsIn:a filter:[:old :new | (old at:5) ~~ (new at:5)].

     a size.
     a at:1.
     a at:2 put:nil.
     a at:2 put:2.
     a at:2.
     a at:3.
     a at:2 put:2.
     a at:2 put:3.
     a at:5 put:3.
     a at:5 put:3.
     MessageTracer untrace:a.
     a at:3 put:5.

trapModificationsIn: anObject selector: aSelector filter: aFilterBlock

install a trap for modifications in anObject by aSelector-messages.
the filterBlock will be invoked (after a modification) with the old and
new values as arguments and should return true,
if the debugger is really wanted.

trapModificationsIn: anObject selectors: aCollectionOfSelectors filter: aFilterBlock

install a trap for modifications in anObject by aSelector-messages.
the filterBlock will be invoked (after a modification) with the old and
new values as arguments and should return true,
if the debugger is really wanted.

trapModificationsOf: anInstVarOrOffset in: anObject

trap modifications in anObject

object tracing

trace: anObject selector: aSelector

arrange for a trace message to be output on Stderr, when a message with
aSelector is sent to anObject. Both entry and exit are traced.
Use untrap to remove this trace.
The current implementation does not allow integers or nil to be traced.

trace: anObject selector: aSelector on: aStream

arrange for a trace message to be output on aStream, when a message with
aSelector is sent to anObject. Both entry and exit are traced.
Use untrap to remove this trace.
The current implementation does not allow integers or nil to be traced.

trace: anObject selectors: aCollectionOfSelectors

arrange for a trace message to be output on Stderr, when any message
from aCollectionOfSelectors is sent to anObject.
Both entry and exit are traced.
Use untrap:/untrace: to remove this trace.
The current implementation does not allow integers or nil to be traced.

trace: anObject selectors: aCollectionOfSelectors on: aStream

arrange for a trace message to be output on aStream, when any message
from aCollectionOfSelectors is sent to anObject.
Both entry and exit are traced.
Use untrap:/untrace: to remove this trace.
The current implementation does not allow integers or nil to be traced.

traceAll: anObject

trace all messages which are understood by anObject

usage example(s):

     MessageTracer traceAll:Display
     MessageTracer untrace:Display

traceAll: anObject from: aClass

trace all messages, which are defined in aClass, sent to an anObject on stderr

usage example(s):

     MessageTracer traceAll:Display from:XWorkstation
     MessageTracer untrace:Display

traceAll: anObject from: aClass on: aStream

trace all messages, which are defined in aClass, sent to anObject

usage example(s):

     MessageTracer traceAll:Display from:XWorkstation on:Transcript
     MessageTracer untrace:Display

traceAll: anObject on: aStream

trace all messages which are understood by anObject

usage example(s):

     MessageTracer traceAll:Display on:Transcript
     MessageTracer untrace:Display

traceEntry: anObject selectors: aCollectionOfSelectors on: aStream

arrange for a trace message to be output on aStream, when any message
from aCollectionOfSelectors is sent to anObject.
Only entry is traced.
Use untrap:/untrace: to remove this trace.
The current implementation does not allow integers or nil to be traced.

traceSender: anObject selector: aSelector

arrange for a trace message to be output on Stderr, when a message with
aSelector is sent to anObject. Only the sender is traced on entry.
Use untrap to remove this trace.
The current implementation does not allow integers or nil to be traced.

traceSender: anObject selector: aSelector on: aStream

arrange for a trace message to be output on aStream, when a message with
aSelector is sent to anObject. Only the sender is traced on entry.
Use untrap to remove this trace.
The current implementation does not allow integers or nil to be traced.

untrace: anObject

remove any traces on anObject

untrace: anObject selector: aSelector

remove traces of aSelector sent to anObject

object wrapping

wrap: anObject selector: aSelector onEntry: entryBlock onExit: exitBlock

arrange for the two blocks entryBlock and exitBlock to be evaluated whenever
a message with aSelector is sent to anObject. EntryBlock will be called on
entry, and get the current context passed as argument. ExitBlock will be called,
when the method is left, and get the context and the method's return value as arguments.
The current implementation does not allow integers or nil to be wrapped.

wrap: anObject selector: aSelector onEntry: entryBlock onExit: exitBlock additionalEntryCode: additionalEntryCode additionalExitCode: additionalExitCode additionalVariables: additionalVariables withOriginalClass: withOriginalClass flushCaches: flushCaches

arrange for the two blocks entryBlock and exitBlock to be evaluated whenever
a message with aSelector is sent to anObject. EntryBlock will be called on
entry, and get the current context passed as argument. ExitBlock will be called,
when the method is left, and get the current context and the method's return value as argument.
If withOriginalClass is true, the class of anObject will be set to its original class
before the wrapped method will be called.
NOTICE: The current implementation does not allow integers or nil to be wrapped.

usage example(s):

                                                                        [exBegin]
     |p|

     p := Point new copy.
     MessageTracer
                wrap:p
            selector:#y:
             onEntry:nil
              onExit:[:context :retVal |
                         Transcript show:'leave Point>>y:, returning:'.
                         Transcript showCR:retVal printString.
                         Transcript endEntry
                     ]
               withOriginalClass:true.
     Transcript showCR:'sending x: ...'.
     p x:1.
     Transcript showCR:'sending y: ...'.
     p y:2.
     MessageTracer untrap:p.
     Transcript showCR:'sending x: ...'.
     p x:2.
     Transcript showCR:'sending y: ...'.
     p y:1.
                                                                        [exEnd]

usage example(s):

                                                                        [exBegin]
     |p|

     p := Point new copy.
     MessageTracer wrap:p
               selector:#y:
                onEntry:[:context | self halt:'y: you are trapped']
                 onExit:nil
                  withOriginalClass:false.
     Transcript showCR:'sending x: ...'.
     p x:1.
     Transcript showCR:'sending y: ...'.
     p y:2.
     MessageTracer untrap:p.
     Transcript showCR:'sending x: ...'.
     p x:2.
     Transcript showCR:'sending y: ...'.
     p y:1.
                                                                        [exEnd]

wrap: anObject selector: aSelector onEntry: entryBlock onExit: exitBlock withOriginalClass: withOriginalClass flushCaches: flushCaches

arrange for the two blocks entryBlock and exitBlock to be evaluated whenever
a message with aSelector is sent to anObject. EntryBlock will be called on
entry, and get the current context passed as argument. ExitBlock will be called,
when the method is left, and get the current context and the method's return value as argument.
If withOriginalClass is true, the class of anObject will be set to its original class
before the wrapped method will be called.
NOTICE: The current implementation does not allow integers or nil to be wrapped.

wrap: anObject selectors: aCollection onEntry: entryBlock onExit: exitBlock

install wrappers for anObject on all selectors from aCollection

wrapAll: anObject onEntry: entryBlock onExit: exitBlock

install wrappers for anObject on all implemented selectors

queries

allWrappedMethods

^ Smalltalk allMethodsForWhich:[:mthd | mthd isWrapped]

areAnyMethodsWrapped

Smalltalk allMethodsDo:[:mthd |

isCounting: aMethod

return true if aMethod is counted

isCountingByReceiverClass: aMethod

return true if aMethod is counted with per receiver class statistics

isMocking: aMethod

Return true if aMethod is mocking

isTiming: aMethod

return true if aMethod is timed

isTrapped: aMethod

return true, if a breakpoint is set on aMethod.
This only returns true for standard breakpoints (i.e. for user-wraps,
this returns false)

usage example(s):

     MessageTracer trapMethod:(Collection compiledMethodAt:#select:).
     Transcript showCR:(Collection compiledMethodAt:#select:) isWrapped.
     Transcript showCR:(MessageTracer isTrapped:(Collection compiledMethodAt:#select:)).
     MessageTracer unwrapMethod:(Collection compiledMethodAt:#select:).

trace helpers

dummyEmptyMethod

helper - to get the time it takes to evaluate the wrappers for
a dummy method.

getTimeForWrappers

helper - get the overhead (in ms) spent in the wrapper code of
a timed method.

usage example(s):

     self getTimeForWrappers

printEntryFull: aContext

printEntryFull: aContext level: lvl

printEntryFull: aContext level: lvl on: aStream

printEntryFull: aContext on: aStream

printEntrySender: aContext on: aStream

printExit: aContext with: retVal

printExit: aContext with: retVal level: lvl

printExit: aContext with: retVal level: lvl on: aStream

printExit: aContext with: retVal on: aStream

printFull: aContext on: aStream withSender: withSender

printFull: aContext on: aStream withSenderContext: aSenderContextOrNil

printObject: anObject on: aStream

printSender: aSenderContext on: aStream

printUpdateEntryFull: aContext level: lvl on: aStream

called when tracing changed-update sequences.
Searches for the sender of the changed message and prints its context

traceEntryFull: aContext on: aStream

traceFullBlockFor: aStream

avoid generation of fullBlocks

traceSenderBlockFor: aStream

avoid generation of fullBlocks

Instance protocol:

trace helpers

trace: aBlock detail: fullDetail

trace execution of aBlock.

usage example(s):

     PrintingMessageTracer new trace:[#(6 5 4 3 2 1) sort] detail:false

     PrintingMessageTracer new trace:[#(6 5 4 3 2 1) sort] detail:true

     PrintingMessageTracer new trace:[#(6 5 4 3 2 1) sort] detail:#indent

     PrintingMessageTracer new trace:[#(6 5 4 3 2 1) sort] detail:#fullIndent

Private classes:

    InteractionCollector
    MethodSpyInfo
    MethodTimingInfo
    PrintingMessageTracer

Examples:

For the common cases, you will find a menu entry in the SystemBrowser. Howeever, more special cases (especially with condition checks) can be set up by evaluating the lower level entries. trapping specific methods: (by class/selector):

   MessageTracer trapClass:Collection selector:#select:.
   Dictionary new select:[:e | ].       'not caught - Dictionary has its own select'.
   (Array new:10) select:[:e | ].       'not caught - SeqColl has its own select'.
   Set new select:[:e | ].              'caught - Set inherits this from Collection'.
   MessageTracer untrapClass:Collection

(by method):

   MessageTracer trapMethod:(Collection compiledMethodAt:#select:).
   Dictionary new select:[:e | ].       'not caught - Dictionary has its own select'.
   (Array new:10) select:[:e | ].       'not caught - SeqColl has its own select'.
   Set new select:[:e | ].              'caught - Set inherits this from Collection'.
   MessageTracer unwrapMethod:(Collection compiledMethodAt:#select:).

(by method & instance class):

   MessageTracer trapMethod:(SequenceableCollection compiledMethodAt:#select:)
                 forInstancesOf:SortedCollection.
   Dictionary new select:[:e | ].       'not caught - Dictionary has its own select'.
   (Array new:10) select:[:e | ].       'not caught - not a SortedCollection'.
   OrderedCollection new select:[:e | ]. 'not caught - not a SortedCollection'.
   SortedCollection new select:[:e | ].  'caught - Set inherits this from Collection'.
   MessageTracer unwrapMethod:(SequenceableCollection compiledMethodAt:#select:).

tracing specific methods: (by class/selector):

   MessageTracer traceClass:SequenceableCollection selector:#quickSortFrom:to:.
   #(6 1 9 66 2 17) copy sort.
   MessageTracer untraceClass:SequenceableCollection

(by method):

   MessageTracer traceMethod:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:).
   #(6 1 9 66 2 17) copy sort.
   MessageTracer unwrapMethod:(SequenceableCollection compiledMethodAt:#quickSortFrom:to:).

object trapping:

   |o|

   o := OrderedCollection new.
   MessageTracer trapAll:o.
   o collect:[:el | el].

trapping modifications to an objects instVars:

   |o|

   o := Point new.
   MessageTracer trapModificationsIn:o.
   o x:1.
   o y:2.
   o x:1.
   o y:2.
   MessageTracer untrap:o

trapping modifications of a particular instVar:

   |o|

   o := Point new.
   MessageTracer trapModificationsIn:o filter:[:old :new | old x ~~ new x].
   o x:1.
   o y:2.
   o x:1.
   o y:2.
   MessageTracer untrap:o

tracing during block execution:

   MessageTracer trace:[ 10 factorialR ]

ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 19 Apr 2024 12:44:08 GMT