Class: Trip

Inherits:
Object
  • Object
show all
Defined in:
lib/trip.rb,
lib/trip/version.rb

Overview

Trip is a concurrent tracer that can pause and resume the code it is tracing. Trip yields control between two Fibers - typically the root Fiber and a Fiber that Trip creates. The process of yielding control back and forth between the two Fibers can be repeated until the the code being traced has finished and exits normally. Trip is currently implemented using TracePoint.

Defined Under Namespace

Classes: Event, Fiber

Exceptions collapse

Error =

The superclass of all Trip exceptions

Class.new(RuntimeError)
InternalError =

An exception that’s raised when the tracer crashes

Class.new(Error)
PauseError =

An exception that’s raised when the Trip#pause_when callback crashes

Class.new(Error)

Constant Summary collapse

VERSION = 
"0.1.2"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(events = DEFAULT_EVENTS, callable = nil, &block) ⇒ Trip

Returns an instance of Trip

Parameters:

  • events (Array<Symbol>) (defaults to: DEFAULT_EVENTS) —

    An array of event names to listen for

  • callable (<Proc, #call>) (defaults to: nil) —

    A block, or object that implements “call”



56
57
58
59
60
61
62
63
64
 
# File 'lib/trip.rb', line 56

def initialize(events = DEFAULT_EVENTS, callable = nil, &block)
  @callable = callable || block
  @fiber = nil
  @pauser = DEFAULT_PAUSE
  @events = events
  if @callable.nil?
    raise ArgumentError, "Expected a block or object implementing 'call'"
  end
end

Instance Attribute Details

#callable ⇒ <Proc, #call> (readonly)

Returns the callable object being traced

Returns:

  • (<Proc, #call>) —

    Returns the callable object being traced



37
38
39
 
# File 'lib/trip.rb', line 37

def callable
  @callable
end

#pauser ⇒ <Proc, #call> (readonly)

Returns the callable that decides when to pause the tracer

Returns:

  • (<Proc, #call>) —

    Returns the callable that decides when to pause the tracer



42
43
44
 
# File 'lib/trip.rb', line 42

def pauser
  @pauser
end

#events ⇒ <Array<Symbol>, String> (readonly)

Returns the events being listened for

Returns:

  • (<Array<Symbol>, String>) —

    Returns the events being listened for



47
48
49
 
# File 'lib/trip.rb', line 47

def events
  @events
end

Instance Method Details

#start ⇒ Trip::Event?

Starts the tracer

Returns:

Raises:



75
76
77
78
 
# File 'lib/trip.rb', line 75

def start
  @fiber = Trip::Fiber.new(self).create
  resume
end

#resume ⇒ Trip::Event?

Starts or resumes the tracer

Returns:

Raises:



85
86
87
88
89
90
91
92
 
# File 'lib/trip.rb', line 85

def resume
  if @fiber.nil?
    start
  else
    e = @fiber.resume
    (e == true) ? nil : e
  end
end

#pause_when(callable = nil, &block) ⇒ void

This method returns an undefined value.

Sets a callable that decides when to pause the tracer

Examples:

trip = Trip.new { Kernel.puts(1 + 1) }
trip.pause_when { |event| event.c_call? || event.c_return? }

Parameters:

  • callable (Proc) (defaults to: nil) —

    A block or object that implements “call”

Raises:

  • (ArgumentError) —

    When a callable is not provided



104
105
106
107
108
109
110
 
# File 'lib/trip.rb', line 104

def pause_when(callable = nil, &block)
  callable ||= block
  unless callable.respond_to?(:call)
    raise ArgumentError, "Expected a block or object implementing 'call'"
  end
  @pauser = callable
end

#to_a ⇒ Array<Trip::Event>

Performs a trace from start to finish, then returns an array of Trip::Event objects upon completion

Returns:



117
118
119
120
121
122
123
124
125
 
# File 'lib/trip.rb', line 117

def to_a
  events = []
  loop do
    e = resume
    break unless e
    events.push(e)
  end
  events
end