jruby · Mar 2, 2015 · Mar 2, 2015
Showing with 54 additions and 0 deletions.

+7 −0 truffle/README.md

+38 −0 truffle/src/main/ruby/core/truffle/debug.rb

+9 −0 truffle/src/main/ruby/core/truffle/truffle.rb
diff --git a/truffle/README.md b/truffle/README.md
@@ -0,0 +1,7 @@
+# JRuby+Truffle - a High-Performance Truffle Backend for JRuby
+
+## Authors
+
+* Chris Seaton
+* Benoit Daloze
+* Kevin Menard
diff --git a/truffle/src/main/ruby/core/truffle/debug.rb b/truffle/src/main/ruby/core/truffle/debug.rb
@@ -8,8 +8,46 @@
 
 module Truffle
 
+  # Debug utilities specific to Truffle.
   module Debug
 
+    # Break and enter an interactive shell.
+    # @return [nil]
+    #
+    # # Usage
+    # 
+    # In the shell you can type normal Ruby expressions and have them evaluated
+    # in the current frame. Results will be printed via `#inspect`, like in
+    # IRB.
+    # 
+    # Extra commands available are:
+    #
+    # * `continue` leave the interactive shell and continue execution
+    # * `exit` exit the VM
+    # * `backtrace` print a backtrace, with numbered frames
+    # * `frame n` make the nth frame active for expressions that you type into
+    #   the shell (see +backtrace+ to find the frame you want)
+    #
+    # # Example
+    #
+    # In your ruby code call `Truffle::Debug.break` where you want to break.
+    # When that method is called you will see the shell:
+    #
+    # ```
+    # > backtrace
+    #   ▶    at Truffle::Primitive#simple_shell
+    #   1    at core:/core/truffle/debug.rb:14:in 'break'
+    #   2    at test.rb:4:in 'foo'
+    #   3    at test.rb:9:in 'bar'
+    #   4    at test.rb:12:in '<main>'
+    # > frame 2
+    # > x + y
+    # 110
+    # > frame 3
+    # > a
+    # 99
+    # > continue
+    # ```
     def self.break
       Truffle::Primitive.simple_shell
     end

diff --git a/truffle/src/main/ruby/core/truffle/truffle.rb b/truffle/src/main/ruby/core/truffle/truffle.rb
@@ -6,16 +6,25 @@
 # GNU General Public License version 2
 # GNU Lesser General Public License version 2.1
 
+# Methods specific to the Truffle implementation. This module is only available
+# when running with `-X+T+`. `defined? Truffle` can therefore be used as a
+# runtime test for the program running in Truffle mode.
 module Truffle
 
+  # What is the version of Truffle/Graal being used?
+  # @return [String] a version string such as `"0.6"`, or `"undefined"` if
+  # running on a non-Graal JVM.
   def self.version
     Primitive.version
   end
 
+  # Are we currently running on a Graal VM? If this returns false you are
+  # running on a conventional JVM and performance will be much lower.
   def self.graal?
     Primitive.graal?
   end
 
+  # Is this VM built on the SubstrateVM?
   def self.substrate?
     Primitive.substrate?
   end