Class: Trip

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

Defined Under Namespace

Classes: Event

Constant Summary collapse

Error =
Class.new(RuntimeError)
InternalError =
Class.new(Error)
PauseError =
Class.new(Error)
NotStartedError =
Class.new(Error)
InProgressError =
Class.new(Error)
VERSION =
'1.1.0'

Instance Method Summary collapse

Constructor Details

#initialize(&block) ⇒ Trip

Returns an instance of Trip, a concurrent tracer.

Parameters:

  • &block (Proc)

    A block of code to trace.

Raises:

  • (ArgumentError)

33
34
35
36
37
38
39
40
# File 'lib/trip.rb', line 33

def initialize(&block)
  raise ArgumentError, "expected a block" unless block_given?
  @thread = nil
  @block = block
  @queue = nil
  @pause_when = PAUSE_WHEN
  @caller = Thread.current
end

Instance Method Details

#finished?Boolean

Returns true when the tracer thread has finished.

Returns:

  • (Boolean)

    Returns true when the tracer thread has finished.


83
84
85
# File 'lib/trip.rb', line 83

def finished?
  @thread and END_STATE.include?(@thread.status)
end

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

This method returns an undefined value.

Parameters:

  • callable (Proc) (defaults to: nil)

    A block or an object who responds to #call.

Raises:

  • (ArgumentError)

48
49
50
51
52
# File 'lib/trip.rb', line 48

def pause_when(callable = nil, &block)
  pauser = callable || block
  raise ArgumentError, "expected a block or an object who responds to call" unless pauser
  @pause_when = pauser
end

#resumeTrip::Event?

Returns an event or nil.

Returns:

Raises:


125
126
127
128
129
130
131
# File 'lib/trip.rb', line 125

def resume
  raise NotStartedError, "a trace hasn't started" unless started?
  if sleeping?
    @thread.wakeup
    @queue.deq
  end
end

#running?Boolean

Returns true when the tracer thread is running.

Returns:

  • (Boolean)

    Returns true when the tracer thread is running.


67
68
69
# File 'lib/trip.rb', line 67

def running?
  @thread and @thread.status == RUN_STATE
end

#sleeping?Boolean

Returns true when the tracer thread is sleeping.

Returns:

  • (Boolean)

    Returns true when the tracer thread is sleeping.


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

def sleeping?
  @thread and @thread.status == SLEEP_STATE
end

#startTrip::Event?

Returns an event, or nil

Returns:

Raises:

  • (Trip::InProgessError)

    When there's already a trace in progress that hasn't finished. This could be raised by calling #start twice.

  • (Trip::PauseError)

    When an exception is raised by the block given to #pause_when.

  • (Trip::InternalError)

    When an exception internal to Trip is raised.


101
102
103
104
105
106
107
108
109
110
111
112
# File 'lib/trip.rb', line 101

def start
  raise InProgressError, "A trace is already in progress." \
                         "Call #resume instead ?" if started? && !finished?
  @queue = Queue.new
  @thread = Thread.new do
    Thread.current.set_trace_func method(:on_event).to_proc
    @block.call
    Thread.current.set_trace_func(nil)
    @queue.enq(nil)
  end
  @queue.deq
end

#started?Boolean

Returns true when the tracer has started. (ie #start has been called).

Returns:

  • (Boolean)

    Returns true when the tracer has started. (ie #start has been called).


59
60
61
# File 'lib/trip.rb', line 59

def started?
  @thread != nil
end

#stopnil

Stops the tracer.

Returns:

  • (nil)

138
139
140
141
142
143
144
145
# File 'lib/trip.rb', line 138

def stop
  if @thread
    @thread.set_trace_func(nil)
    @thread.exit
    @thread.join
    nil
  end
end