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



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

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:



79
80
81
82
 
# File 'lib/trip.rb', line 79

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

#resume ⇒ Trip::Event?

Starts or resumes the tracer.

Returns:

Raises:



90
91
92
93
94
95
96
97
 
# File 'lib/trip.rb', line 90

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.



113
114
115
116
117
118
119
 
# File 'lib/trip.rb', line 113

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:



127
128
129
130
131
132
133
134
135
 
# File 'lib/trip.rb', line 127

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