Class: MessageTracer

• Inheritance
• Description
• Class protocol
  • Signal constants
  • class initialization
  • class tracing
  • class wrapping
  • cleanup
  • execution trace
  • method breakpointing
  • method counting
  • method memory usage
  • 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.110 date: 2010/04/19 16:47:24

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:

 breakpointSignal

 objectWrittenBreakpointSignal

 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 methods return value as arguments.

 cleanup

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

 debugTrace: aBlock

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

 trace: aBlock

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

 traceFull: aBlock

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

 traceFullIndented: aBlock

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

 traceIndented: aBlock

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

 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.

 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.

 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.

 trapMethod: aMethod if: conditionBlock

arrange for the debugger to be entered when aMethod has been invoked and conditionBlock
evaluates to true.
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.

 untrapAllClasses

remove any traps on any class

 untrapClass: aClass

remove any traps on aClass

 untrapClass: aClass selector: aSelector

remove trap of aSelector sent to aClass

 untrapMethod: aMethod

remove break on aMethod

 countMethod: aMethod

arrange for a aMethods execution to be counted.
Use unwrapMethod to remove this.

 executionCountOfMethod: aMethod

return the current count

 resetCountOfMethod: aMethod

return the current count

 stopCountingMethod: aMethod

remove counting of aMethod

 countMemoryUsageOfMethod: aMethod

arrange for aMethods memory usage to be counted.
Use unwrapMethod to remove this.

 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

 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 aMethods execution time to be measured.
Use unwrapMethod: or stopTimingMethod: to remove this.

 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.

 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.

 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.

 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.

 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.

 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.

 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 on: aStream

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.

 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 Stderr, 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.

 untraceMethod: aMethod

remove tracing of aMethod

 unwrapAllMethods

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

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

 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)

 trapModificationsIn: anObject

trap modifications in anObject

 trapModificationsIn: anObject filter: aFilterBlock

trap modifications in anObject

 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

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

 traceAll: anObject

trace all messages which are understood by anObject

 traceAll: anObject from: aClass

trace all messages defined in aClass sent to anObject

 traceAll: anObject from: aClass on: aStream

trace all messages defined in aClass sent to anObject

 traceAll: anObject on: aStream

trace all messages which are understood by anObject

 traceEntry: anObject selectors: aCollectionOfSelectors on: aStream

arrange for a trace message to be output on Stderr, 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 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.

 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 methods 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 methods 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 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 methods 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

 areAnyMethodsWrapped

 isCounting: aMethod

return true if aMethod is counted

 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)

 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.

 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

 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.

Private classes:

    InteractionCollector
    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