Class: MessageTracer

• Inheritance
• Description
• Class protocol
  • Signal constants
  • class initialization
  • class tracing
  • class wrapping
  • cleanup
  • execution trace
  • method breakpointing
  • method breakpointing - new
  • method counting
  • method memory usage
  • method mocking
  • method profiling
  • method timing
  • method tracing
  • method wrapping
  • object breakpointing
  • object modification traps
  • object tracing
  • object wrapping
  • queries
  • trace helpers
• Instance protocol
  • trace helpers
• Private classes
• Examples

Inheritance:

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

Package:

stx:libbasic3

Category:

System-Debugging-Support

Version:

rev: 1.174 date: 2024/04/28 17:18:54

user: cg

file: MessageTracer.st directory: libbasic3

module: stx stc-classLibrary: libbasic3

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.

copyright
COPYRIGHT (c) 1994 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

 breakpointSignal

 objectWrittenBreakpointSignal

 initialize

BreakpointSignal := HaltSignal newSignalMayProceed:true.

Usage example(s):

BreakpointSignal := nil. MessageTracer initialize

 update: something with: parameter from: changedObject

sent when restarted after a snapIn

 untraceAllClasses

remove all traces of messages sent to any class

 untraceClass: aClass

remove all traces of messages sent to instances of aClass

 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.

Usage example(s):

|lvl| lvl := 0. MessageTracer wrapClass:Integer selector:#factorial onEntry:[:con | Transcript spaces:lvl. lvl := lvl + 2. Transcript showCR:('entering ' , con receiver printString , '>>factorial'). ] onExit:[:con :retVal | lvl := lvl - 2. Transcript spaces:lvl. Transcript show:('leave ' , con receiver printString , '>>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

 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

 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 inProcess: aProcess withChildProcesses: withChildProcessesBoolean

arrange for the debugger to be entered when aMethod is about to be executed,
but only, if executed by 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

 breakMethod: method atLine: line

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

 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

 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

 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:

 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.

 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)

 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 entry: traceEntryBoolean exit: traceExitBoolean inProcess: aProcessOrNil on: aStream

arrange for a trace message to be output on aStream,
when aMethod is executed;
either in a particular process and its subprocesses,
or by any process if aProcessOrNil is nil.
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 inProcess: aProcessOrNil on: aStream

arrange for a trace message to be output on aStream,
when aMethod is executed;
either in a particular process and its subprocesses,
or by any process if aProcessOrNil is nil.
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 by any process.
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

 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

 unwrapAllMethodsIn: aClass

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

Usage example(s):

MessageTracer unwrapAllMethods MessageTracer unwrapAllMethodsIn:Integer

 unwrapMethod: aMethod

remove any wrapper on aMethod

 wrapMethod: aMethod onEntry: entryBlockOrNil onExit: exitBlockOrNil

install a wrapper so that 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.

 wrapMethod: aMethod onEntry: entryBlockOrNil onExit: exitBlockOrNil onUnwind: unwindBlockOrNil

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 and its value will be the return value
of the method.
UnwindBlock will be called when the context 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:#factorialR) onEntry:[:con | Transcript showCR:('entering ' , con receiver printString , '>>factorial'). ] onExit:[:con :retVal | Transcript show:'leave Integer>>factorial; returning:'. Transcript showCR:retVal printString. Transcript endEntry. retVal ]. Transcript showCR:'5 factorialR traced'. 5 factorialR. MessageTracer unwrapMethod:(Integer compiledMethodAt:#factorialR). Transcript showCR:'5 factorialR normal'. 5 factorialR.

Usage example(s):

|lvl| lvl := 0. MessageTracer wrapMethod:(Integer compiledMethodAt:#factorial) onEntry:[:con | Transcript spaces:lvl. lvl := lvl + 2. Transcript showCR:('entering ' , con receiver printString , '>>factorial'). ] onExit:[:con :retVal | lvl := lvl - 2. Transcript spaces:lvl. Transcript show:('leave ' , con receiver printString , '>>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 onEntry: entryBlockOrNil onExit: exitBlockOrNil onUnwind: unwindBlockOrNil inProcess: aProcessOrNil

arrange for the two blocks entryBlock and exitBlock to be evaluated whenever
aMethod is evaluated;
either in a particular process and its subprocesses,
or by any process if aProcessOrNil is nil.
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 context 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. retVal ]. (1@2) scaleBy:5. MessageTracer unwrapMethod:(Point compiledMethodAt:#scaleBy:). (1@2) scaleBy:5.

Usage example(s):

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

Usage example(s):

|lvl| lvl := 0. MessageTracer wrapMethod:(Integer compiledMethodAt:#factorialR) onEntry:[:con | Transcript spaces:lvl. lvl := lvl + 2. Transcript showCR:('entering ' , con receiver printString , '>>factorialR'). ] onExit:[:con :retVal | lvl := lvl - 2. Transcript spaces:lvl. Transcript show:('leave ' , con receiver printString , '>>factorialR; returning:'). Transcript showCR:retVal printString. Transcript endEntry. retVal ]. Transcript showCR:'5 factorialR traced'. 5 factorialR. MessageTracer unwrapMethod:(Integer compiledMethodAt:#factorialR). Transcript showCR:'5 factorialR normal'. 5 factorialR.

 wrapMethod: aMethod onEntryCode: entryCodeOrNil onExitCode: exitCodeOrNil

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.

Because the code is sliced in, it may return.
Also the context call chain is not affected
(i.e. thisContext sender etc. work correctly inside).
Notice, that the code should be in a single line, so that the lineNr info is correct.
Useful to wrap existing methods with before and after code.

 wrapMethod: aMethod onEntryCode: entryCodeOrNil onExitCode: exitCodeOrNil onUnwindCode: unwindCodeOrNil

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.
Also the context call chain is not affected
(i.e. thisContext sender etc. work correctly inside).
Notice, that the code should be in a single line, so that the lineNr info is correct.
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.

 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.

Usage example(s):

|p| p := Point new. MessageTracer trap:p selector:#x:. p x:5

 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

Usage example(s):

|p| p := Point new copy. MessageTracer trace:p selector:#x:. MessageTracer trace:p selector:#y:. p y:1. p x:2. MessageTracer untrap:p p y:2. p x:1.

 untrap: anObject selector: aSelector

remove trap on aSelector from anObject

Usage example(s):

|p| p := Point new copy. MessageTracer trace:p selector:#x:. MessageTracer trace:p selector:#y:. 'trace both ...' errorPrintNL. p x:2. p y:1. 'trace only y ...' errorPrintNL. MessageTracer untrap:p selector:#x:. p x:2. p y:1. 'trace none ...' errorPrintNL. MessageTracer untrap:p selector:#y:. p x:2. p y:1.

 wrappedSelectorsOf: anObject

return the set of wrapped selectors (if any)

 trapModificationsIn: anObject

trap modifications in anObject

Usage example(s):

|a| a := Array new:10. MessageTracer trapModificationsIn:a. a size. a at:1. a at:2 put:nil. ' no trap here (nil already there) '. a at:2 put:2. ' expect trap here (changing nil to 2) '. a at:2. a at:3. a at:2 put:2. ' no trap here (2 already there) '. a at:2 put:3. ' expect trap here (changing 2 to 3) '. MessageTracer untrace:a. a at:3 put:5.

 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

Usage example(s):

|a| a := Array new:10. MessageTracer trapModificationsOf:2 in:a. a size. a at:1. a at:2 put:nil. ' no trap here (nil already there) '. a at:2 put:2. ' expect trap here (changing nil to 2) '. a at:2. a at:3. a at:2 put:2. ' no trap here (2 already there) '. a at:2 put:3. ' expect trap here (changing nil to 2) '. a at:3. a at:3 put:3. ' no trap here (index is different) '. MessageTracer untrace:a. a at:3 put:5.

 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.

Usage example(s):

|p| p := Point new. MessageTracer trace:p selector:#x:. p x:5. p y:1. p x:10. MessageTracer untrap:p. p x:7

Usage example(s):

|a| a := #(6 1 9 66 2 17) copy. MessageTracer trace:a selector:#at:put:. MessageTracer trace:a selector:#at:. a sort.

 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.

Usage example(s):

|p| p := Point new. MessageTracer trace:p selector:#x: on:Stderr. p x:5. p y:1. p x:10. MessageTracer untrap:p. p x:7

 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.

Usage example(s):

|p| p := Point new. MessageTracer trace:p selector:#x:. p x:5. p y:1. p x:10. MessageTracer untrap:p. p x:7

Usage example(s):

|a| a := #(6 1 9 66 2 17) copy. MessageTracer trace:a selector:#at:put:. MessageTracer trace:a selector:#at:. a sort.

 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.

Usage example(s):

|p| p := Point new. MessageTracer trace:p selectors:#(x:) on:Transcript. p x:5. p y:1. p x:10. MessageTracer untrap:p. p x:7

Usage example(s):

|a| a := #(6 1 9 66 2 17) copy. MessageTracer trace:a selectors:#( at:put: at:) on:Transcript. a sort.

 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.

Usage example(s):

|p| p := Point new. MessageTracer traceEntry:p selectors:#(x:). p x:5. p y:1. p x:10. MessageTracer untrap:p. p x:7

Usage example(s):

|a| a := #(6 1 9 66 2 17) copy. MessageTracer traceEntry:a selectors:#( at:put: at:). a sort.

 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.

Usage example(s):

|p| p := Point new. MessageTracer traceSender:p selector:#x:. p x:5. p y:1. p x:10. MessageTracer untrap:p. p x:7

Usage example(s):

|a| a := #(6 1 9 66 2 17) copy. MessageTracer traceSender:a selector:#at:put:. MessageTracer traceSender:a selector:#at:. a sort.

 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.

Usage example(s):

|p| p := Point new. MessageTracer traceSender:p selector:#x: on:Transcript. p x:5. p y:1. p x:10. MessageTracer untrap:p. p x:7

 untrace: anObject

remove any traces on anObject

 untrace: anObject selector: aSelector

remove traces of aSelector sent to anObject

 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

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

 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 withSender: withSender prefix: prefixOrNIl

 printFull: aContext on: aStream withSenderContext: aSenderContextOrNil

 printFull: aContext on: aStream withSenderContext: aSenderContextOrNil prefix: prefixOrNil

 printObject: anObject on: aStream

in case an error happens when we try to print an uninitialized object

 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: aBlock detail: fullDetail

trace execution of aBlock.

Usage example(s):

PrintingMessageTracer new trace:[1 halt] detail:false 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:

   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

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

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

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

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

   |o|

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

   |o|

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

   |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

   MessageTracer trace:[ 10 factorialR ]