Concurrency is a hotly debated subject in the Ruby community. Shared state or shared nothing? Threads or Events? Sync or Async? The fact that the standard Ruby interpreter does not provide multiple-core saturation without resorting to process management clouds the issue, causing developers to constantly evaluate new approaches for using all available CPUs.

JRuby enters the discussion, sporting its use of native (kernel) threads, allowing single-process access to all of your cores. Is true concurrently-executing Ruby code obtained simply by switching to JRuby? Before you think that JRuby will make your threaded code run faster, we need to take a step back and explain.

Mental Model

[caption id="attachment_9567" align="alignleft" width="240" caption="model_team_canada by Dept of Energy Solar Decathlon, on Flickr"][/caption]

First, a new mental model is needed. Although JRuby is just another Ruby implementation, it's also a new tool running on a completely different VM, the Java Virtual Machine, which has performance characteristics much different than Ruby's VM. These characteristics vary due to the use of native threads compared to green threads, the JVM's sophisticated garbage collection facilities, and most importantly JRuby's own codebase. So your assumptions about how code works do not carry across Ruby implementations. Code that previously ran slow may now be fast and vice versa.

Uncertainty

Adding to the uncertainty of the situation is the unpredictability of native threads. Have you ever seen "should never happen" comments in code, where some programmer was convinced that a branch of code was completely unreachable? If the code branches based on a piece of shared state corrupted by multiple threads scheduled across multiple cores, the impossible code just might end up executing.

/* ruby/struct.c */
static VALUE rb_struct_equal(VALUE s, VALUE s2) {
    /* ... */
    if (RSTRUCT_LEN(s) != RSTRUCT_LEN(s2)) {
        rb_bug("inconsistent struct"); /* should never happen */
    }
    /* ... */
}

Here's a hypothetical example running on some fictitious native-threaded, optimizing Ruby VM. Say we have this singleton object that's expensive to create, so the programmer wrote it to be constructed lazily.

class ExpensiveToCreate
  def self.instance
    @instance ||= ExpensiveToCreate.new
  end
end

As we all know, the "or-equals" operator is really just sugar for the following code:

class ExpensiveToCreate
  def self.instance
    unless defined?(@instance)
      @instance = ExpensiveToCreate.new
    end
    @instance
  end
end

Now let's play the role of the optimizing VM. Let's say that this VM decides to inline the new method like so:

class ExpensiveToCreate
  def self.instance
    unless defined?(@instance) # Line 3
      @instance = ExpensiveToCreate.allocate
      @instance.initialize     # Line 5
    end
    @instance
  end
end

What if two threads try to initialize the instance at the same time? Trouble! We have the potential for a race: the first thread on line 5 is not finished performing the expensive initialization, but the @instance variable has already been defined, so the second thread will happily return the uninitialized instance and try to use it. (Some of you will recognize this as a variation on the Double-checked locking problem.)

So does this mean that we need to be extra vigilant with our code, sprinkling it with mutex blocks everywhere? Will it become an unreadable, unmaintainable mess? Certainly not, as long as we follow a simple rule:

Avoid shared, mutable state.

This includes lazy initialization, which is mutating shared state at the time it is first accessed.

The consequences of programming with real threads are difficult to conceptualize at first, especially if you're used to Ruby's green threads or Ruby 1.9's global interpreter lock (GIL). Consider this code:

data = []
M.times do |m|
  threads << Thread.new do
    N.times do |n|
      data << m * n
    end
  end
end

What happens to the data array after all threads have finished? Under Ruby 1.8 and Ruby 1.9, we always get an array of integers of size M * N. There may be a little randomness in the ordering of the entries, but otherwise the array is intact and well-behaved.

Under JRuby, arrays (as well as strings, hashes and other core library data structures) are not safe for mutation by multiple threads. So when we run the code above with JRuby, the array and its internals become corrupted. The array's size is frequently less than M * N, and what's more, we often observe some of the entries are nil rather than the integers we expect. Sometimes we'll encounter a ConcurrencyError raised as well.

This uncertainty can be the cause of some nasty, hard-to-pinpoint bugs in your code. So if your code works well with Ruby but blows up with unexpected nils or otherwise unexplained behavior, you can at least start to point the blame at threaded code that mutates state.

What about metaprogramming in the presence of threads? Can we corrupt the interpreter by defining classes and/or methods from many threads at once? Fortunately the answer here is no. JRuby explicitly takes steps to ensure that class and method definition are properly synchronized internally. Also, since class variables are frequently used for sharing state between objects, they are synchronized as well.

Using Native Threads

As you might expect, using native threads in JRuby is as simple as working with the regular Ruby Thread class. (Note that there are some caveats). For example, you can easily offload some computation to the background:

require 'java'
@count = java.util.concurrent.atomic.AtomicInteger.new

def send_email(message)
  Thread.new do
    # send the message
    puts "sent #{@count.incrementAndGet} emails"
  end
end

send_email("hello")

For systems with large volumes of email, this naive approach may not work well. Native threads carry a bigger initialization cost and memory overhead than green threads, so JRuby normally cannot support more than about 10,000 threads.

$ jruby -e '100_000.times { Thread.new { sleep 1 } }'
ThreadError: unable to create new native thread

To work around this, we can use a thread pool. Using JRuby's Java integration, we can easily access the built-in Executor classes:

java_import java.util.concurrent.Executors

def send_email(message, executor)
  executor.submit do
    # send the message
    puts "sent #{@count.incrementAndGet} emails"
  end
end

executor = Executors.newCachedThreadPool
send_email("hello", executor)

executor = Executors.newFixedThreadPool(2)
10.times do
  send_email("hello", executor)
end

Here we're using two thread pools. The first, the "cached" thread pool, is a general-purpose pool that grows as needed by demand and frees up system resources by releasing threads after they have been idle. The second example uses a fixed pool of two threads for when you want a place hard limit on the amount of background processing.

Java's java.util.concurrent package has a number of useful utilities like these for concurrent programming including locks, semaphores, latches, queues, concurrent lists and maps, and atomic objects such as the AtomicInteger used above. And they're all trivially available to you via JRuby.

Concurrency with Actors

The shift in thinking around concurrent programming in recent years has been around the development of higher-level abstractions. This arose out of the realization that lower-level coding with fine-grained locks is hard: it's error-prone, makes code less readable and maintainable, and is difficult to troubleshoot. The upside of this is that we get to leave the hard stuff to the library programmers who create the implementations of these abstractions.

Of all the higher level ways of doing concurrent programming, the actor model has become preferred in recent years coincident with the rise in popularity of Erlang where the actor model has been proven to work well.

Ruby has had a number of Actor frameworks for some time, including a recent entry, Celluloid. (Be sure to watch Celluloid's creator Tony Arcieri in a screencast for EMRubyConf.) While these all work great on JRuby, again I'd like to focus on two Java libraries that are just as accessible from JRuby but go above and beyond what is currently possible with the pure Ruby libraries.

Jetlang/Jretlang

Jetlang isn't quite a full actor library, but instead claims to be "designed specifically for high performance in-memory messaging". (Jretlang is the JRuby wrapper around Jetlang). The main primitives in Jetlang are Fibers and Channels. Here's a "Hello World" example:

require 'java'
require 'jretlang'

fiber = JRL::Fiber.new
channel = JRL::Channel.new
fiber.start

channel.subscribe_on_fiber(fiber) do |msg|
  puts msg
end

channel.publish "Hello"

If you want a toolkit for building a message-passing framework in your application, give Jretlang a look.

Akka

Akka is a platform and toolkit for concurrent, scalable, and fault-tolerant systems. It has many features inspired by Erlang, including many flavors of actors and fault-tolerant supervisor hierarchies. Here's the simplest-possible Akka-in-Ruby example:

require 'akka'

class HelloWorld
  def hi
    puts "hello actor world"
  end
end

Actors.actorOf(HelloWorld.new).hi
puts "initiating shutdown..."
Actors.delayedShutdown 1

When run, this example prints:

$ ./runner.sh lib/everything_is_an_actor.rb
[...lots of akka logging...]
initiating shutdown...
hello actor world

Of note here is that we're creating an actor reference to the HelloWorld object and sending it the #hi message, but that does call the method immediately. Instead, the message is routed through Akka and back to the object later.

JRuby Makes Concurrency Easy

Once again, the long and short of the concurrency story on JRuby is buttressed by the ease of which you can access both the best of Ruby and Java libraries. Go forth and glue together concurrency-heavy applications with JRuby, and please share them with us!

You have an existing Java web server

Maybe your organization is already Java-heavy, or you have an operations team that's familiar with operating an existing Java server. That's fine! In that case, JRuby-Rack is what you need.

JRuby-Rack is the foundation that enables Ruby applications to run on virtually any existing Java web server. Put simply, JRuby-Rack is a bridge from the Java Servlet API to Ruby's Rack API. So if you have a Servlet container (and pretty much every widely-used Java server in existence has one), you can run any Rack application with JRuby-Rack. We regularly test JRuby-Rack with Tomcat 6/7, Jetty 6/7, JBoss 5/6, Resin 4, and GlassFish 3, so chances are good that your application will run fine on your server.

JRuby-Rack is also the hidden engine behind Warbler, the tool that quickly assembles a full .war file from your Ruby application. When you run warble, Warbler includes a copy of JRuby-Rack in the final assembled archive and wires up the RackFilter Servlet filter that delegates requests to your Ruby application.

In addition to managing the lifecycle of your Ruby application inside the Java web server, JRuby-Rack has accumulated a number of useful extensions over its three-year life. Here are three.

Response streaming

Say you'd like to do some early flushing of your response. With JRuby-Rack, simply set the Transfer-Encoding: chunked header in the response, and JRuby-Rack will flush each element of the response body individually. (A word of caution: Aaron Patterson reports how the Rack API doesn't support this very well, so make sure you know what you're doing.) Here's a Sinatra example that perpetually reports the server time in a series of JSON chunks:

class ServerTime
  def initialize(response)
    @boundary = 'MultipartBody'
    response['Content-Type'] = "multipart/mixed; boundary=\"#{@boundary}\""
    response['Transfer-Encoding'] = 'chunked'
  end

  def chunk(content_type, body)
    "--#{@boundary}\nContent-Type: #{content_type}\n\n#{body}\n"
  end

  def each
    loop do
      yield chunk("application/json", "{\"currentTime\":\"#{Time.now.strftime '%H:%M:%S'}\"}")
      sleep 2
    end
  end
end

get '/servertime' do
  ServerTime.new(response)
end

A more efficient X-Sendfile

You can also use a Ruby File or Tempfile object as the response body, and JRuby-Rack will write it to the response using the Java NIO FileChannel#transferTo method, which, depending on the OS, can transfer bytes directly from the filesystem cache to the target channel without actually copying them. JRuby-Rack will close the file after the request is finished so you don't have to worry about leaking the resource.

Interaction with Servlets

You can use the JRuby-Rack RackFilter alongside other servlets or JSPs in a Java web application. For example, you can internally redirect from Ruby to another servlet. JRuby-Rack adds a custom #forward_to method to Rails' ActionController:

class JspController < ApplicationController
  def index
    servlet_request['message'] = 'Hello from Rails!'
    forward_to '/jsp/index.jsp'
  end
end

Inside public/jsps/index.jsp, we can consume the message attribute as follows:

<html>
  <head><title>Rails with JSPs</title></head>
  <body>
    <h1><%= request.getAttribute("message") %></h1>
  </body>
</html>

With this technique it's easy to introduce Rails as the routing and controller layer on top of an existing Java web application.

We'll be writing much more about integrating Ruby alongside Java web applications in the near future, so watch this space.

You want to distribute your application

Warbler comes with a feature dubbed executable war, which builds a .war file that can be deployed in a container or run as an self-contained executable. Warbler embeds Winstone, a small servlet container, in the archive that self-extracts and listens at localhost:8080 when run:

$ warble executable war
rm -f sinatra.war
Creating sinatra.war
$ java -jar sinatra.war
[Winstone 2011/03/07 12:40:58] - Beginning extraction from war file
[Winstone 2011/03/07 12:40:59] - WARNING: The Servlet 2.4/2.5 spec XSD was unavailable inside the winstone classpath. Will be retrieved from the web if required (slow)
[Winstone 2011/03/07 12:40:59] - No webapp classes folder found - /private/var/folders/CA/CAMqlEcnEmSLCKPW5k22oE+++TI/-Tmp-/winstone5711860033631390551webroot/sinatra.war/WEB-INF/classes
[Winstone 2011/03/07 12:41:05] - HTTP Listener started: port=8080
[Winstone 2011/03/07 12:41:05] - Listener winstone.ajp13.Ajp13Listener not found / disabled - ignoring
[Winstone 2011/03/07 12:41:05] - Listener winstone.ssl.HttpsListener not found / disabled - ignoring
[Winstone 2011/03/07 12:41:05] - Winstone Servlet Engine v0.9.10 running: controlPort=disabled

The executable archive is completely self-contained, so you can distribute it and run it anywhere a Java Virtual Machine is installed.

Up to this point, we've learned that Warbler and JRuby-Rack are great for deploying across a wide range of environments, but what about development? When you're coding a new application, it would be mighty painful  to generate a .war file and deploy it after every change. Rubyists are used to firing up a web server, writing code, and hitting the refresh button. JRuby certainly supports this mode, but with a different cast of characters than you know from the C Ruby world. Let's take a look at five JRuby servers that fill different needs.

You want uniformity across environments

Unlike WEBrick, the server included in Ruby's standard library, Trinidad by David Calavera is equally suited for development and production use. Written in pure Ruby, Trinidad is built by employing JRuby-Rack and Apache Tomcat as embedded Java libraries. To try out Trinidad, simply gem install trinidad and start the server with the trinidad command.

Trinidad is the most mature of the JRuby web servers, and most familiar in feel to other Ruby servers. trinidad -e production -p 3001 does what you expect. In addition, JRuby-specific options like --threadsafe, --classes, and --jars are easily accessible.

You can also customize Trinidad with extensions. Currently there are lifecycle, daemon, hotdeploy, and sandbox extensions available.  Also notable is the brand new scheduler extension, developed by Brandon DeWitt, and is the first extension developed by someone other than David, showing growth in the Trinidad community beyond its primary maintainer.

You want a light, customizable server

Mizuno, by Don Werve, is a great example of how easy it is to leverage an existing Java library in a very small amount of code. Mizuno is advertised as "a set of Jetty-powered running shoes for JRuby and Rack", and clocks in at a svelte 335 lines of pure Ruby code. Size does not matter in this case though, as Mizuno manages to turn in good performance numbers as well. Try out the Mizuno gem and if you're thinking of writing a custom server, take a look at the Mizuno codebase as a starting point.

You like playing with asynchronous APIs

Kevin Williams has been hacking on his server, Aspen, for a while now, and has recently kicked it up a notch. Aspen's approach is to mimic the design of the Ruby web server Thin using the JBoss Netty asynchronous event-driven network application framework. If a JVM-based, Ruby-flavored Node.js is up your alley, get in touch with Kevin and take a look at Aspen.

You want a full-stack solution

TorqueBox, from the fine folks at RedHat, provides an all-in-one solution by building on top of the JBoss application server. According to the FAQ:

[TorqueBox] attempts to go beyond providing web-centric services (supporting Rails, Rack, Sinatra, etc), to also expose other enterprise-grade services to Ruby applications.

One of the niceties of TorqueBox's full-stack solution is integrated messaging and asynchronous tasks. Backgrounding is as simple as creating a task class in app/tasks/email_task.rb:

class EmailTask < TorqueBox::Messaging::Task
  def send_hello(payload)
    puts "EmailTask: sent hello email with #{payload.inspect}"
  end
end

and invoking it:

class HelloController < ApplicationController
  def index
    EmailTask.async(:send_hello, params[:message])
  end
end

This is much better than simply launching a background thread or even a subprocess, because behind the scenes TorqueBox creates a queue for your task on the internal HornetQ message bus and invokes an instance of the task class on the receiving end of the queue. If the server happens to crash, you're much less likely to lose the task.

So if you're familiar with JBoss or like the idea of having a wider platform to build messaging and other background infrastructure all in Ruby, TorqueBox is definitely worth a look.

You want zero-downtime deploys

Kirk, at two months old the youngest entry in the JRuby server category, is brought to us by Carl Lerche of Rails core and Bundler fame.

The key use case for Kirk is zero-downtime deploys in the same fashion as Passenger or Unicorn. Applications deployed in Kirk can be redeployed either by command-line or by updating files that Kirk is configured to watch.

Kirk deployments are configured with a Kirkfile (facepalm!). Here's a simple example:

rack "rails3/config.ru" do
  listen 9090
end

rack "sinatra/config.ru" do
  listen 9091
end

rack "camping/config.ru" do
  listen 9092
end

As you surely guessed, this starts up three socket listeners on ports 9090-9092, all inside a single JVM. Each application is redeployable on its own, or all at once if you configure them to watch the same file.

If you redeploy while the application is servicing requests, Kirk warms up the new version of the application and swaps it in atomically. In a stress test, I compared response rates between a stable application and one that continuously redeploys every two seconds. The stable server performed at a rate of 285 replies per second:

$ httperf --port 9292 --uri /env --num-conns 500 --num-calls 20
httperf --client=0/1 --server=localhost --port=9292 --uri=/env --send-buffer=4096 --recv-buffer=16384 --num-conns=500 --num-calls=20
httperf: warning: open file limit > FD_SETSIZE; limiting max. # of open files to FD_SETSIZE
Maximum connect burst length: 1

Total: connections 500 requests 10000 replies 10000 test-duration 34.972 s

Connection rate: 14.3 conn/s (69.9 ms/conn, <=1 concurrent connections)
Connection time [ms]: min 61.1 avg 69.9 max 357.4 median 66.5 stddev 15.9
Connection time [ms]: connect 0.3
Connection length [replies/conn]: 20.000

Request rate: 285.9 req/s (3.5 ms/req)
Request size [B]: 65.0

Reply rate [replies/s]: min 220.8 avg 284.9 max 305.6 stddev 32.6 (6 samples)
Reply time [ms]: response 3.5 transfer 0.0
Reply size [B]: header 113.0 content 6893.0 footer 0.0 (total 7006.0)
Reply status: 1xx=0 2xx=10000 3xx=0 4xx=0 5xx=0

The coutinuous-redeploy version responded to every request but dropped to a rate of 90 replies per second. Obviously redeploys aren't free, but as long as you don't deploy new code every two seconds (!), you won't see a noticeable slowdown.

$ httperf --port 9292 --uri /env --num-conns 500 --num-calls 20
httperf --client=0/1 --server=localhost --port=9292 --uri=/env --send-buffer=4096 --recv-buffer=16384 --num-conns=500 --num-calls=20
httperf: warning: open file limit > FD_SETSIZE; limiting max. # of open files to FD_SETSIZE
Maximum connect burst length: 1

Total: connections 500 requests 10000 replies 10000 test-duration 111.636 s

Connection rate: 4.5 conn/s (223.3 ms/conn, <=1 concurrent connections)
Connection time [ms]: min 63.7 avg 223.3 max 5839.1 median 161.5 stddev 337.7
Connection time [ms]: connect 1.6
Connection length [replies/conn]: 20.000

Request rate: 89.6 req/s (11.2 ms/req)
Request size [B]: 65.0

Reply rate [replies/s]: min 8.4 avg 90.2 max 169.8 stddev 34.7 (22 samples)
Reply time [ms]: response 11.1 transfer 0.0
Reply size [B]: header 113.0 content 6908.0 footer 0.0 (total 7021.0)
Reply status: 1xx=0 2xx=10000 3xx=0 4xx=0 5xx=0

Bright Future

There's certainly a swarm of activity in JRuby web server land, and you can count on seeing a few of these options appear in future JRuby offerings on the Engine Yard AppCloud.

If you haven't yet tried running your application with JRuby, stay tuned. My session at RailsConf 2011 covers porting to JRuby and you can rest assured that we'll cover the details in a future article as well.

Let us know in the comments about your preferred way of deploying JRuby applications, or tell us frankly what's holding you back from deploying with JRuby so we can correct those issues!

For those of you who are Rubyists or regular readers of the Engine Yard blog, the content will most likely not be anything new. We're reaching out to you because we know you love Ruby and want to help Ruby continue to succeed and find new enthusiasts. So if you have friends or colleagues who are Java programmers that haven't heard the Ruby message, please pass this along and encourage them to check out the first webinar in the series that I'll be leading next week.

*Webinar:* *JRuby - Connecting the Worlds of Java and Ruby*
*Date: Tuesday, December 14th, 2010*
*Time: 10:00 AM - 11:00 AM Pacific*

The content will be a very high-level overview of Ruby and JRuby for Java developers, including:

• An introduction to the Ruby language: Learn how Ruby can make you more productive and write more readable and maintainable code

• An introduction to Rails: Learn how it speeds up web development

• An introduction to JRuby: Learn how to integrate existing Java code with just a few of lines of Ruby and how to use JRuby to extend existing Java applications with Ruby on Rails

If you're interested in attending, please register here. If you'd like to attend, but can't make the live webinar, go ahead and register and we will email you a link to the full recording and slides once available.

Happy holidays, and thanks for helping us spread the Ruby cheer!

Although many of us wish we could consume the web through a magic programmer portal that shields us and our code from all the pointy angle brackets, the reality that is the legacy of HTML, Atom and RSS on the web leaves us little choice but to soldier on. So let’s take a look at what Ruby-colored armor is available to us as we continue our quest to slay the XML dragons.

Background

Historically, Ruby has had a number of options for dealing with structured markup, though oddly none have reached a solid consensus among Ruby developers as the “go to” library. The earliest available library seems to be Yoshida Masato’s XMLParser, which wraps Expat and was first released around the time that Expat itself was released, back in 1998. A pure Ruby parser by Jim Menard called NQXML appeared in 2001, though it never matured to the level of a robust XML parser.

In late 2001, Matz expressed his desire for out of the box XML support, but sadly, nothing appeared in Ruby’s standard library until 2003, when REXML was imported for the 1.8.0 release. After reading bike-shed discussions like this one on ruby-talk in November 2001, or this wayback-machine page from the old RubyGarden wiki, it’s not hard to see why. Meanwhile, other language runtimes, such as Python and Java, moved along and built solid, acceptable foundations, making Ruby’s omission seem more glaring.

But all was not lost: Ruby has always had a quality without a name that made it a great language for distilling an API. All that was needed was an infusion of interest and talent in Ruby, and a few more experiments and iterations.

Fast forward to the present time, and all those chips have fallen. We’ve seen evolution from REXML to libxml-ruby to Hpricot, and finally to Nokogiri. So, is the XML landscape on Ruby so dire? Certainly not, as you’ll see by the end of this article! While the standard library support for XML hasn’t progressed beyond REXML yet, state-of-the-art solutions are a few keystrokes away.

XML APIs

A big part of what makes XML such a pain to work with is the APIs. We Rubyists tend to have an especially low tolerance for friction in API design, and we really feel it when we work with XML. If XML is just a tree structure, why isn’t navigating it as simple and elegant as traversing a Ruby Enumerable?

The canonical example of API craptasticism is undoubtedly the W3C DOM API. For proof, observe the meteoric rise of jQuery in the JavaScript world. While it would be easy to fill an entire article with criticisms regarding the DOM, it’s been done before. (Incidentally, read the whole series of interviews with Elliotte Rusty Harold for a series of insights on API design, schema evolution, and more.)

Instead, we’ll take a brief exploratory tour of some Ruby XML APIs using code examples. Though some of the examples may seem trivially short, don’t underestimate their power. Conciseness and readability are Ruby’s gifts to the library authors and they’re being put to good use.

The libraries we’ll use for comparison are REXML, Nokogiri, and JAXP, Java’s XML parsing APIs (via JRuby).

Parsing

The simplest possible thing to do in XML is to hand the library some XML and get back a document.

REXML

require 'rexml/document'
document = REXML::Document.new(xml)

Nokogiri

require 'nokogiri'
document = Nokogiri::XML(xml)

Both REXML and Nokogiri more or less get this right. What’s also nice is that they both transparently accept either an IO-like object or a string. Contrast this to Java:

JAXP/JRuby

factory = javax.xml.parsers.DocumentBuilderFactory.newInstance
factory.namespace_aware = true # unfortunately, important!
parser = factory.newDocumentBuilder
# String
document = parser.parse(xml)
# IO
document = parser.parse(xml.to_inputstream)

In that familiar Java style, the JAXP approach forces you to choose from many options and write more code for the happy path. JRuby helps you a little bit by converting a Ruby string into a Java string, but needs a little help with intent for converting an IO to a Java InputStream.

XPath

Now that we’ve got a document object, let’s query it via XPath, assuming the underlying format is an Atom feed. Here is the code to grab the entries’ titles and store them as an array of strings:

REXML

elements = REXML::XPath.match(document.root, "//atom:entry/atom:title/text()",
                              "atom" => "http://www.w3.org/2005/Atom")
titles = elements.map {|el| el.value }

Nokogiri

elements = document.xpath("//atom:entry/atom:title/text()",
                          "atom" => "http://www.w3.org/2005/Atom")
titles = elements.map {|e| e.to_s}

Again, both REXML and Nokogiri clock in at similar code sizes, but subtle differences begin to emerge. Nokogiri’s use of #xpath as an instance method on the document object feels more natural as a way of drilling down for further detail. Also, note that both APIs return DOM objects for the text, so we need to take one more step to convert them to pure Ruby strings. Here, Nokogiri’s use of the standard String#to_s method is more intuitive; REXML::Text’s version returns the raw text without the entities replaced.

Unfortunately, doing XPath in Java gets a bit more complicated. First we need to construct an XPath object. At least JRuby helps us a bit here–we can create an instance of the NamespaceContext interface completely in Ruby, and omit the methods we don’t care about.

JAXP/JRuby

xpath = javax.xml.xpath.XPathFactory.newInstance.newXPath
ns_context = Object.new
def ns_context.getNamespaceURI(prefix)
  {"atom" => "http://www.w3.org/2005/Atom"}[prefix]
end
xpath.namespace_context = ns_context

Next, we evaluate the expression and construct the array titles:

JAXP/JRuby

nodes = xpath.evaluate("//atom:entry/atom:title/text()",
                       document, javax.xml.xpath.XPathConstants::NODESET)
titles = []
0.upto(nodes.length-1) do |i|
  titles << nodes.item(i).node_value
end

That last bit where we need to externally iterate the DOM API is particularly un-Ruby-like. With JRuby we can mix in some methods to the NodeList class:

JAXP/JRuby

module org::w3c::dom::NodeList
  include Enumerable
  def each
    0.upto(length - 1) do |i|
      yield item(i)
    end
  end
end

And replace the external iteration with a more natural internal one:

JAXP/JRuby

titles = nodes.map {|e| e.node_value}

This kind of technique tends to become a fairly common occurrence when coding Ruby to Java libraries in JRuby. Fortunately Ruby makes it simple to hide away the ugliness in the Java APIs!

Walking the DOM

Say we’d like to explore the DOM. Both REXML and Nokogiri provide multiple ways of doing this, with parent/child/sibling navigation methods. They also each sport a recursive descent method, which is quite convenient.

REXML

titles = []
document.root.each_recursive do |elem|
  titles << elem.text.to_s if elem.name == "title"
end

Nokogiri

titles = []
document.root.traverse do |elem|
  titles << elem.content if elem.name == "title"
end

Needless to say, Java’s DOM API has no such convenience method, so we have to write one. But again, JRuby makes it easy to Rubify the code. Note that our #traverse method makes use of our Enumerable-ization of NodeList above as well.

JAXP/JRuby

module org::w3c::dom::Node
  def traverse(&blk)
    blk.call(self)
    child_nodes.each do |e|
      e.traverse(&blk)
    end
  end
end

titles = []
document.traverse do |elem|
  titles << elem.text_content if elem.node_name == "title"
end

Pull parsing

All three libraries have a pull parser (also called a stream parser or reader) as well. Pull parsers are efficient because they behave like a cursor scrolling through the document, but usually result in more verbose code because of the need to implement a small state machine on top of lower-level XML events. They are best employed on very large documents where it’s impractical to store the entire DOM tree in memory at once.

REXML

parser = REXML::Parsers::PullParser.new(xml_stream)
titles = []
text = ''
grab_text = false
parser.each do |event|
  case event.event_type
  when :start_element
    grab_text = true if event[0] == "title"
  when :text
    text << event[1] if grab_text
  when :end_element
    if event[0] == "title"
      titles << text
      text = ''
      grab_text = false
    end
  end
end

Nokogiri

reader = Nokogiri::XML::Reader(xml_stream)
titles = []
text = ''
grab_text = false
reader.each do |elem|
  if elem.name == "title"
    if elem.node_type == 1  # start element?
      grab_text = true
    else # elem.node_type == 15  # end element?
      titles << text
      text = ''
      grab_text = false
    end
  elsif grab_text && elem.node_type == 3 # text?
    text << elem.value
  end
end

(Aside to the Nokogiri team: where are the reader node type constants?)

JAXP/JRuby

include javax.xml.stream.XMLStreamConstants
factory = javax.xml.stream.XMLInputFactory.newInstance
reader = factory.createXMLStreamReader(xml_stream.to_inputstream)
titles = []
text = ''
grab_text = false
while reader.has_next
  case reader.next
  when START_ELEMENT
    grab_text = true if reader.local_name == "title"
  when CHARACTERS
    text << reader.text if grab_text
  when END_ELEMENT
    if reader.local_name == "title"
      titles << text
      text = ''
      grab_text = false
    end
  end
end

Not surprisingly, all three pull parser examples end up looking very similar. The subtleties of the pull parser APIs end up getting blurred in the loops and conditionals. Only write this code when you have to.

Performance

At the end of the day, it comes down to performance, doesn’t it? Although the topic of Ruby XML parser performance has been discussed before, I thought it would be instructive to do another round of comparisons with JRuby and Ruby 1.9 thrown into the mix.

System Configuration

• Mac OS X 10.5 on a MacBook Pro 2.53 GHz Core 2 Duo
• Ruby 1.8.6p287
• Ruby 1.9.1p243
• JRuby 1.5.0.dev (rev c7b3348) on Apple JDK 5 (32-bit)
• Nokogiri 1.4.0
• libxml2 2.7.3

Here are results comparing Nokogiri and Hpricot on the three implementations  along with the JAXP version which only runs on JRuby (smaller is better).

The REXML results were over an order of magnitude slower, so it's easier to view them on a separate graph. Note the number of iterations here is 100 vs. 1000 for the results above.

While these results don’t paint a complete picture of XML parser performance, they should give you enough of a guideline to make a decision on which parser to use once you take portability and readability into account. In summary:

• Use REXML when your parsing needs are minimal and want the widest portability (across all implementations) with the smallest install footprint.
• Use JRuby with the JAXP APIs for portability across any operating system that supports the Java platform (including Google AppEngine).
• Use Nokogiri for everything else. It’s the fastest implementation, and produces the most programmer-friendly code of all Ruby XML parsers to date.

(As a footnote, we on the Nokogiri and JRuby teams are looking for community help to further develop the pure-Java backend for Nokogiri so that AppEngine and other JVM deployment scenarios that don’t allow loading native code can benefit from Nokogiri’s awesomeness. Please leave a comment or contact the JRuby team on the mailing list if you’re interested.)

The source code for this article is available if you’d like to examine the code or run the benchmarks yourself. Keep an eye on the Engine Yard blog for an upcoming post on Nokogiri, and as always, leave questions and thoughts in the comments!

The release itself is tentatively planned to enter a round of release candidates at the end of September. Please prepare yourselves, try the release candidates when they are available, and most importantly, report bugs!

So what can you expect in the next release, other than the usual array of bug, performance, and compatibility fixes? Here are the five areas where we’ve been focusing efforts.

1. 1.8.7 is the New Baseline

When Ruby 1.8.7 was first released, we had a false start where we eagerly started to add some of the new additions, only to find that Rails (version 2.0 at the time) was rendered useless by the changes. Now, finally, three minor releases of Rails 2.x later, Rails on Ruby 1.8.7 has finally stabilized, and is now the recommended version of Ruby to use with Rails. Additionally, 1.8.7 is showing up as the default version of Ruby in many operating systems, and we began to see more bug reports about missing 1.8.7 features.

So, in JRuby 1.4, we’ll finally report compatibility with Ruby 1.8.7p174:

$ jruby -v
jruby 1.4.0dev (ruby 1.8.7p174) (2009-09-14 b09f382) (Java HotSpot(TM) Client VM 1.5.0_19) [i386-java]

The patch-level (p174) is based on the version of Ruby where we pulled the updated standard library. We always maintain that patch-level is a “best effort” number, and as such, we cannot promise full feature-for-feature (or bug-for-bug!) compatibility. However, as the RubySpec project has matured, it's gotten much easier for us to feel confident about this claim. As always, if you spot an area where we differ from Ruby 1.8.7, please do file a bug on the discrepancy, or even better, make sure that RubySpec covers the issue by submitting a patch to RubySpec.

2. Improving 1.9 Compatibility

Even though Ruby 1.9 is still a moving target, the RubySpec project has recently begun to cover many of the new 1.9 features, which gives JRuby an easier, more robust mechanism for tracking how far along the path to 1.9 we are.

We’ve also been following our tried-and-true approach of just trying to get stuff working. In particular, IRB, RubyGems, Rake, and even some simple Rails applications are working with JRuby in 1.9 mode.

Other than a couple of major new features remaining (Multilingualization/encoding, IO transcoding, Fibers), JRuby 1.9 mode should just work. To try out JRuby in 1.9 mode, just pass --1.9 as a leading argument on the command-line:

$ jruby --1.9 -v
jruby 1.4.0dev (ruby 1.9.1p0) (2009-09-14 b09f382) (Java HotSpot(TM) Client VM 1.5.0_19) [i386-java]

If you’ve been writing 1.9 code, we’d love to hear if you can get it working on JRuby: do comment!

3. New YAML Parser

Ok, so a new YAML parser is something you’d probably have to give more than a cursory glance to notice. But our good friend Ola Bini has gone and done it again with Yecht, a new YAML engine. Ola re-implemented YAML support in JRuby to be much closer to the idiosyncracies of Syck, the C YAML parser that MRI uses. With this change, a number of long-standing YAML compatibility issues are fixed. Hopefully this is the last YAML engine that JRuby will ever need!

4. Java Method Selection and Coercion API

For a long time, JRuby Java integration features have been something of a black box, especially the way Java methods are selected and invoked and arguments are coerced. This black box has hindered understanding of how JRuby calls Java, and in the case of overloaded methods, has made some Java methods unreachable. Consider this Java class:

public class Overloaded {
    public static void use(int i) { /* ... */ }
    public static void use(long l) { /* ... */ }
}

And this JRuby code:

Java::Overloaded.use 10

Which Overloaded method is called? It turns out it’s use(long). JRuby behavior is to coerce Ruby Fixnums into Java longs. Thus, with current versions of JRuby, it’s impossible to call the version that takes an int.

We’d like to make this part of the Java integration layer more transparent and accessible. Here are a few APIs we’re considering:

a. Object#java_send(name, signature, *args)

Like Object#send except it would allow you to identify and invoke a specific Java method by its name and signature. A signature for these purposes is an array of classes, where the first element in the array specifies the return type.

b. Object#java_method(name, signature)

Like Object#method, except it would take an array of Java classes representing a method signature as an additional argument and return a Method object that can be #call‘ed.

c. #coerce_to?(type)

Method convention to allow an object to decide whether it can be coerced to a Java type. JRuby will call this method if it’s available to get hints to aid in choosing a method in the presence of several overloaded methods.

d. #to_java(type)

Method convention to allow arbitrary Ruby objects to control how they are coerced to Java. If a Ruby object responds to #to_java, JRuby will use it to convert the argument before passing to a Java method invocation.

e. #to_ruby(type)

Like #to_java except to be applied to return types and Java objects coming back to Ruby.

All of these APIs are still yet to be implemented, and we could use some good real-world examples of where JRuby falls down to help ensure that we solve those issues.

5. Generate Real Java Classes from Ruby

Since we started writing Ruby2java as an add-on library, we’ve been looking for a way to expose the functionality of creating a real Java class from Ruby in the JRuby core. JRuby 1.4 will have some new experimental APIs for doing this. The example below explains it in code:

require 'java'
require 'jruby/core_ext'

class SimpleTest
  def equals
    raise "not equal" unless 1.0 == 1
  end
end

SimpleTest.add_method_signature("equals", [java.lang.Void::TYPE])
SimpleTest.add_method_annotation("equals", org.junit.Test => {})
SimpleTest.become_java!

The effect of this code is the same as writing the following Java code:

package ruby;
import org.junit.Test;
public class SimpleTest {
    @Test
    public void equals() {
        // dispatch back to Ruby code here
    }
}

We are also providing #add_class_annotation and #add_parameter_annotation methods as well, rounding out the ability to shape a real Java class.

These APIs are admittedly verbose and low-level, but they do allow you to easily build higher level constructs using Ruby metaprogramming techniques.

Here’s a more realistic example of implementing a JAX-RS/Jersey resource using Ruby (full source available):

class Hello < RubyJersey::Resource
  GET()
  Produces("text/plain")
  Returns(java.lang.String)
  def hello
    "Hello Ruby Jersey!"
  end
end

Feedback

The release is still a couple of weeks away, so none of this is by any means final. Please send us feedback by commenting here or use the JRuby mailing list for longer discussions, and let us know how the 1.4 release candidates work for you!