Overview

• Description
• Function Index
• Function Details

Version: 1.42.1

Description

A User Level Scheduler of Erlang resulting from the ProTest project. Copyright Developer Team, see licence conditions

This module defined the parse transformation necessary to instrument Erlang code for scheduling with PULSE.

This parse transformation is automatically applied to the module that you want to instrument by adding the compile flag {parse_transform,pulse_instrument} when you compile the file. For example, from Erlang shell:
c(YourModule,[{parse_transform,pulse_instrument}]).

You can provide a number of options to the compiler (see below) that this parse transformation takes care of. These can either be supplied as compiler options in the -compile attribute or as additional options in the compile command. Option specified in the erlang module with -compile attribute take precedence over the options provided when the compiler is called.

Note that parse transformation adds explicit module names to the function calls. Thus testing hot code loading with the scheduler may give unexpected results. The semantics of imported functions has changed.

Compiler options

pulse_skip

You can skip the instrumentation of certain functions in the module by providing the compiler option pulse_skip, for example, {pulse_skip,[{f,3},{g,1}]} will not instrument the source code for f/3 and g/1.

pulse_side_effect

Certain functions in your modules may contain side-effects that you want to observe. For example, you may be interested in calls to the ets module or calls to the file module. The way to give the scheduler control over calls to these side-effect functions is to provide a compiler option to specify them: {pulse_side_effect,[MatchSpec]} with a list of match specifications. Each match specification MatchSpec is of the form {Module,'_','_'}, {Module,Function,'_'} or {Module,Function,Arity} . In the first case any function in the specified module is replaced by a call to pulse:side_effect/3. In the second case, any function application Module:Function(A1,...,An) in the source code is replaced by pulse:side_effect(Module,Function,[A1,...,An]). In the last case, only functions with the specified arity are replaced by a call to pulse side_effect.

The function pulse:side_effect/3 ensures that the scheduler randomly chooses to either directly execute the side-effect or to yield and let another process execute first. In addition, it generates an event that visualizes that a side-effect function has been evaluated.

pulse_no_side_effect

This option can be used to override the option pulse_side_effect. For example if you would mark all calls to the ets module as side effects, but you do not want to consider the function ets:delete/2 as side effect, you could exclude it from instrumentation as side effect by using the option {pulse_no_side_effect,[{ets,delete,2}]}. The match specifications are the same as used for the pulse_side_effect option.

pulse_replace_module

Alternatively, some external modules may contain side-effects, but they are in fact part of your application, typically the otp library modules such as application, supervisor or generic server. Thus, your application has a supervisor callback module and you would like to instrument the supervisor to be able to schedule restarts with pulse_instrument. However, instrumenting the supervisor is not possible, since other software uses this module as well. Instead you should replace the supervisor module by an instrumented supervisor version, e.g., pulse_supervisor. All calls to the supervisor have to be replaced by calls to pulse_supervisor instead of masking the calls as side-effects.

The compiler option {pulse_replace_module,[{old(),new()}]} gets a list of atom pairs as second argument which specifies which module to replace by what other module. Calls to old are replaced by calls to new in the instrumented module.

The pulse_otp application provides instrumented versions of many common OTP behaviours; you can use these versions by including

  -include_lib("pulse_otp/include/pulse_otp.hrl").
  

Function Index

Function Details

source/1

Prints the source code produced by the instrumenter, provided that the debug_info flag has been used when compiling.

transformed/1

Return the source code produced by the instrumenter, provided that the debug_info flag has been used when compiling.

Overview