• Michael’s post on using Unicorn with Heroku is a fantastic idea and great way to improve the efficiency of your Heroku application’s web dynos.
• Heroku imposes a limit of 15 threads per Ruby process (there is an open question about this, it might just be a bug in the Heroku Cedar stack, which is still beta). If you are using thin, you get 1 process and 15 threads per dyno. If you are using Unicorn, you get 3 processes^* and 45 threads.
• girl_friday defaults to 5 threads per queue. With the thread limit on Heroku, you’ll want to carefully ration the size of each queue. girl_friday’s Rack status app can tell you at runtime which queues are busy and which are quiet for tuning purposes.
• girl_friday can, in many cases, replace or dramatically reduce your need for separate worker dynos, saving you money.

* Where 3 is based on the memory consumption of your application. YMMV.

Unicorn appears to work great with girl_friday and Heroku’s free service level actually becomes useful for non-trivial applications with these optimizations. Know any other tips? Let me know!

Ruby’s threading has historically been terrible. So we turned to event-based systems like EventMachine but the reactor pattern brings its own set of drawbacks. So we turned to Fibers to solve some of those problems but they bring along another set of drawbacks. In the end though, all of this is a workaround for Ruby’s historically terrible threading implementation. But what if Ruby’s threading didn’t suck?

JRuby has great threads. Rubinius will soon have great threads. Both have really matured into excellent, stable runtimes over the last year. Make no mistake threads have issues too; locks and race conditions are notoriously hard to write well and Ruby code can’t be autoloaded safely in a multithreaded system. The former is what Actors attempt to solve: making concurrency simpler and safer by passing messages rather than sharing mutable state and requiring locks.

I think the Ruby community needs to give threads another chance: ensure their gems are thread-safe and use Actors when needing to write safe multithreaded code. Celluloid and the Rubinius Actor API are two APIs which provide Actors to Ruby. My new gem girl_friday leverages actors for safe concurrency. The autoloading problem is the only hard problem remaining; I hope some time and effort can determine ways around this issue.

On the other hand, I do think Actors are a good step forward for concurrency by making Threads safer to utilize. By the end of this year, we’ll have several Ruby VMs (JRuby, MacRuby, Rubinius) that can execute threads in parallel, allowing a single Ruby process to peg a multi-core machine; Actors will be helpful in building applications that can take advantage of this.

I’ve written two posts on the Carbon Five blog, the first covering Actors in general and the second covering my new, simple but full-featured asynchronous processing library, girl_friday, which leverages Actors. Take a look and let me know what you think!

require 'java'
require 'iText-5.0.6.jar'
 
module Pdf
  include_package "com.itextpdf.text.pdf"
  include_package "java.io"
 
  def self.write
    reader = PdfReader.new('application.pdf');
    stamper = PdfStamper.new(reader, FileOutputStream.new('completed.pdf'))
    form = stamper.acro_fields
    puts "Form has these fields: #{form.fields.key_set.to_a}"
    form.set_field("some_zipcode_field", "94115")
    stamper.close
  end
end
 
Pdf.write

Obviously sample code, not production quality, etc. Really the only hard/tedious part is mapping field names to Ruby object attribute values. If you have a complex form, you may have tens or even hundreds of set_field calls.

Creating RDoc

I’ve never found an easily accessible RDoc markup reference. The only one I know of is unlinkable, buried at the bottom of the RDoc readme instead of front and center as it should be. So I extracted the RDoc markup reference for your reading pleasure. Jan Varwig created a great RDoc cheatsheet PDF for local or offline access.

Next time you’re working on a gem, take 10 minutes to read the reference and document the main class for the gem. It’ll make you a better Rubyist, I guarantee it.

Generating RDoc

Ok, so you’ve learned RDoc markup and your code is documented like a champ. What do you do now? You’ve got several choices:

• Generate rdoc by hand – the rdoc command ships with Ruby and by default generates all .rb files in or below the current directory. You probably want something like rdoc lib to just include your project’s main Ruby code.
• Integrate RDoc into Rake – Rake has an RDocTask which can be configured for your project, so you can just run rake rdoc.

Once generated, you can view the generated output at doc/index.html.

Viewing RDoc

Rubygems has built-in support for generating and viewing the RDoc for installed gems. rdoc is generated when the gem is installed (using gem install --no-rdoc [name] skips the local rdoc generation). You can then use gem server to view your local gem rdoc at http://localhost:8808.

Check out YARD

YARD is an interesting project by Loren Segal to create a next generation Ruby documentation system. Getting started with YARD is well documented; try it out if you want an alternative to RDoc. YARD’s syntax is a superset of RDoc’s so backwards compatibility should not be an issue. The generated documentation looks pretty awesome (note the support for Markdown-formatted README files, which RDoc does not have).

The YARD team also created RubyDoc.info, which hosts documentation for popular gems and is a great resource for finding linkable documentation.

I hope this helps de-mystify rdoc for people. Any other rdoc tips, please leave a comment. Happy documenting!

• Fork http://github.com/ruby/ruby
• Make and commit your changes in your repo
• Send a pull request

In other words, contributing to Ruby is now just as easy to contribute to as any other Github project! This is a huge deal. Obviously there are caveats: if you are making significant changes to runtime code, you should probably enter an issue in Redmine and/or send an email to the ruby-dev mailing list. But for small cleanups and RDoc improvements that have been sorely missing for years, there’s no longer any excuse!

1) It’s full of unnecessary libraries that should be separately distributed

The Ruby community, at least in the US, has proven to be very open to change, see Rails 1, 2 and 3 for example. Sometimes you have to break compatibility to advance the state of the art. Continuing to bundle inferior implementations means that we have this compatibility albatross around our neck while stronger third-party libraries don’t pop to the top of the ecosystem. Some random dude said it better than me. Some other dude agreed, REXML in this case should be unbundled.

I was proposing unbundling DRb and Tk not because their codebase sucks but simply because they aren’t used by the vast majority of the Ruby community. treetop and shoes are very useful libraries also but they don’t belong in stdlib either.

I’m not proposing we do this in the next 1.9.2 patch, but for 2.0, sure. Now that rubygems is in core (thanks Eric!), I think we should be aggressive in unbundling everything that can be unbundled.

2) It’s (still) too hard to contribute

The Net::HTTP docs haven’t been touched AFAICT in 5 years. They’re full of broken English and rudimentary examples. I hear people complain about it all the time, why hasn’t anyone fixed it? Maybe everyone is lazy or maybe the contribution process remains too steep for most.

Net::HTTP had performance issues in the 1.8.6 era, sounds they have been fixed. The API is still poor and poorly documented IMO. Just about every HTTP library has a better API IMO, e.g. Typhoeus, httparty and rest-client. As someone else pointed out, Ruby really does need an http API in core though, if not just for Rubygems to use.

I would love to see ruby-core treat git as a first class citizen and allow pull requests and git email patches against http://github.com/ruby/ruby. If this is the case today, please let me know. I will be the first to submit a pull request for better net/http docs.

The canonical example is Ruby’s net/http library. Its performance and API are just terrible. (Side note: how do you know if an API is terrible? If you have to consult the docs even after having used the API for the past 5 years.) But because it’s in the standard library, most people use it as the base for higher-level API abstractions (e.g. httparty, rest-client).

So looking at Ruby’s core RDoc, my suggested list for removal (where removal means move to a rubygem):

• Net::*
• DRb
• REXML
• RSS
• Rinda
• WEBrick
• XML

Any others I missed? Will Ruby 1.9.3 or 2.0 get a good spring cleaning or will we have to live with these classes forever?

memcache-client runs the GC 4x as much as Dalli and roughly half of Dalli’s speed improvement over memcache-client is due to more efficient object allocation requiring less garbage collection. Note that Dalli’s GC runs seem to take twice as long as the memcache-client runs. Anyone know Ruby 1.9′s GC implementation and have an idea why this might be?

My goals for Dalli were threefold:

1. Clean sheet codebase using the binary protocol
2. Drop-in replacement for memcache-client in Rails for a very simple upgrade path for Rails developers
3. Equivalent or faster performance than memcache-client

I’m happy to say that Dalli meets all those goals. For one, the Dalli core is almost half the size of the memcache-client core, 700 vs 1250 LOC! But wait, there’s more! Using Rails 3? Dalli drops right in! Using Heroku? Dalli works without any additional configuration! Take a look at the README for more details.

Please file an issue if you find a bug or have a feature you’d like to see. In the meantime, happy caching!