Scopeo instrumentation

A library to install instrumentation on Pharo smalltalk methods.

How to install?

Open a playground and execute the following baseline:

Metacello new
  githubUser: 'scopeo-project' project: 'scopeo-instrumentation' 
  commitish: 'main' path: 'src';
  baseline: 'ScopeoInstrumentation';
  load

How to use?

Create an instrumentation

To create the instrumentation, instantiate the ScpMethodInstrumentation class.

To define the behavioral indirection to install in a given method use one of ScpIndirection subclasses:

• ScpMethodIndirection: transfer the control of method execution.
• ScpAssigmentIndirection: transfer the control of variable assignments.
• ScpMessageIndirection: transfer the control of messages sending.

All of these classes expect following parameters:

• handler: the object which is going to catch the control of the original execution.
• selector: the selector of the hook method implemented by the handler to control the execution.
• arguments: the arguments expected by the later hook method. Please refer to the methods beginning with generate of the indirection classes to know which arguments are valid for your indirection.

Note: since an indirection transfers the original behavior to the object of your choice, it is the responsibility of the latter object to perform the original behavior or not. I.e if an indirection is installed to trace all message sends, the handler code must log and perform the message send to ensure the execution is still correct. To do so, use the argument operation, this will provide the handler with a block containing the operation to execute.

Example

| instrumentation |

instrumentation := ScpMethodInstrumentation new.

instrumentation addIndirection: (
  ScpMessageIndirection new
    handler: [ :operation :selector :receiver | 
      selector crTrace. 
      receiver crTrace.
      operation value
    ];
    selector: #value:value:value:;
    arguments: #( operation selector receiver );
    yourself
)

Install an instrumentation

Install

It is possible to instrument an anonymous method using the message applyOn: aMethod:

instrumented := instrumentation applyOn: aMethod

If the method is attached to a class, its instrumentation version can be installed using the message installOn: aMethod:.

instrumented := instrumentation installOn: aMethod

One instrumentation can be installed on several methods.
In this case, each non-anonymous methods is going to be attached to the instrumentation.

Uninstall

To uninstall the instrumentation, use the uninstall message.
This message will affect each method on which the instrumentation was installed.

instrumentation uninstall

Update

The instrumentation can be updated, for example to add a new indirection (removal not supported yet).

instrumentation addIndirection: (
  ScpAssignmentIndirection new
    handler: [ :operation :variable :newValue | 
      variable crTrace. 
      newValue crTrace.
      operation value 
    ];
    selector: #value:value:value:;
    arguments: #( operation variable newValue );
    yourself
)

To apply this new indirection to all the methods previously instrumented use the reinstall message.

instrumentation reinstall

Troubleshoot

Known issues

• The methods are recompiled when instrumented, therefore the debugger looses track of the executed bytecode and cannot highlight the currently executed node.

Possible issues

• An instrumented method always returns the source code of its original method, in some cases it might not be the expected behavior. For example, in the inspector of such method, the source code, AST and bytecode don't match.
• When the source code of an instrumented method is being edited, the new source code is automatically updated (only for non-anonymous methods). During development, I sometimes had troubles with that, the method was re-instrumented while I previously had uninstalled the instrumentation. To troubleshoot such issues, de-activate the method updater using like so: ScpMethodUpdater stop.