Asp Forum - [ANN] FastRI 0.3.1: faster, Leopard compatibility, etc.

Mauricio Fernández

2/2/2008 5:07:00 PM

FastRI is an alternative to the ri documentation browser for Ruby.

Why prefer it over ri? FastRI
* actually works
* is *much* faster than ri
* can perform fast full-text searching over all your rdoc documentation
* is smarter than ri, and can find classes anywhere in the hierarchy without
specifying the "full path"
* can be told to use different search strategies (completion, nested
namespaces, etc.)
* supports RubyGems much better than ri, and knows which gem a method/class
came from
* can serve RI documentation over DRb

Getting it
==========
Additional information, tarballs... at
http://eige.../h...

FastRI can be installed with RubyGems:
gem install fastri
(if you get an old version/a 404 error, please allow some time after the
release until the package propagates to the RubyForge mirrors). Please read
below for an important note regarding the RubyGems packages.

Visible changes since version 0.3.0
===================================
* speed increases
* works on Leopard and with non-standard RubyGems setups
* -1 (--exact) option to disable second-guessing.
* -a (--all) option to show the documentation for all matching entries

Usage
=====
Starting from 0.3.0, fri can be used in either local mode (--local, -L) or
remote mode (using a fastri-server, -R, --remote).
By default, fri will run in remote mode. There's a new executable named
qri that defaults to local mode (it behaves otherwise identically to fri).

Remote mode is slightly faster (typically about 150ms) , since the
documentation index is kept in memory and needs not be read from disk.

Local mode
----------
$ qri Array
----------------------------------------------------------- Class: Array
Arrays are ordered, integer-indexed collections of any object.
Array indexing starts at 0, as in C or Java. A negative index is
...

$ qri compact
---------------------------------------------------------- Array#compact
array.compact -> an_array
------------------------------------------------------------------------
Returns a copy of self with all nil elements removed.

Remote mode
-----------
There are two parts to using FastRI in remote mode:
* the server: fastri-server
* the client: fri

FastRI uses a Rinda Ring to allow servers to be discovered automatically
without needing to indicate the DRb URIs manually. It can work across
machines if you make sure the ring server is bound to the correct interface,
and the ACL permissions are correct.

Running in remote mode:

$ fastri-server (creates the index on the first run, blocks)

Later, (times measured with a cold cache):
$ time ruby bin/fri -f plain Array#fetch
------------------------------------------------------------ Array#fetch
array.fetch(index) -> obj
[...]
real 0m0.287s (real 0m0.127s with a hot cache)
user 0m0.048s
sys 0m0.008s

Compare to:
$ time ri -T -f plain Array#fetch
------------------------------------------------------------ Array#fetch
[...]
real 0m10.136s (real ~ 1.5s with a hot cache)
user 0m1.140s
sys 0m0.464s

This illustrates FastRI's ability to locate classes deep in the class
hierarchy:

$ fri Base
------------------------------------------------------ Multiple choices:

ActionMailer::Base, ActionView::Base, ActionWebService::API::Base,
ActionWebService::Base, ActionWebService::Client::Base,
ActiveRecord::Base, MapReduce::ActiveRecord::Base,
RSS::Maker::Base, Scruffy::Components::Base,
Scruffy::Formatters::Base, Scruffy::Layers::Base,
Scruffy::Renderers::Base, Scruffy::Themes::Base

$ fri Themes::Base
------------------------------------------- Class: Scruffy::Themes::Base
Scruffy::Themes::Base
Author: Brasten Sager

Date: August 14th, 2006

Compare to
$ ri Themes::Base .... several seconds later ...
Nothing known about Themes::Base

A small note about RubyGems + FastRI.
=====================================
RubyGems adds a noticeable overhead to fri, making it run slower than if you
installed it directly from the tarball with setup.rb.

Compare the execution time when installed with RubyGems:
$ time fri -f plain String > /dev/null

real 0m0.385s
user 0m0.244s
sys 0m0.036s

to the time fri actually takes to run, without the overhead introduced by
RubyGems:
$ time ruby bin/fri -f plain String > /dev/null

real 0m0.088s
user 0m0.040s
sys 0m0.008s

If you care about those extra 300ms (and there are situations where they will
matter, e.g. when using fri for method completion), get FastRI from the
tarballs.

License
=======
FastRI is licensed under the same terms as Ruby. See LICENSE.

Feedback
========
Bug reports, patches, comments... are appreciated.
You can contact the author via <mfp@acm.org>. Please add "fastri" to the
subject in order to bypass the spam filters.

--
Mauricio Fernandez - http://eige...

20 Answers

Joel VanderWerf

2/2/2008 8:48:00 PM

Does this happen to anyone else?

$ qri String
/usr/local/lib/ruby/gems/1.8/gems/fastri-0.3.1.1/lib/fastri/ri_index.rb:354:in
`initialize': No such file or directory -
/usr/local/lib/ruby/gems/1.8/doc/mocha-0.4.0/ri/String/cdesc-String.yaml
(Errno::ENOENT)
...

I've tried uninstalling mocha (qri fails the same way), and reinstalling
mocha (ditto).

--
vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

Joel VanderWerf

2/2/2008 8:58:00 PM

Joel VanderWerf wrote:
>
> Does this happen to anyone else?
>
> $ qri String
> /usr/local/lib/ruby/gems/1.8/gems/fastri-0.3.1.1/lib/fastri/ri_index.rb:354:in
> `initialize': No such file or directory -
> /usr/local/lib/ruby/gems/1.8/doc/mocha-0.4.0/ri/String/cdesc-String.yaml
> (Errno::ENOENT)
> ...
>
> I've tried uninstalling mocha (qri fails the same way), and reinstalling
> mocha (ditto).

Well, whatever it was, it got fixed by rebuilding the index:

fastri-server -b

(It would be nice if fri/qri could suggest this course of action when an
exception is raised while using the index.)

--
vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

botp

2/3/2008 3:41:00 PM

On Feb 3, 2008 1:07 AM, Mauricio Fernandez <mfp@acm.org> wrote:
> FastRI is an alternative to the ri documentation browser for Ruby.

forgive the dumb question, but how can i make fastri work for ruby1.9?
thanks for fri/qri, mauricio. 'm very much dependent on it now :)
-botp

Daniel Schömer

2/5/2008 6:03:00 PM

Mauricio Fernandez wrote:
> FastRI is an alternative to the ri documentation browser for Ruby.
> [...]
> Visible changes since version 0.3.0
> ===================================
> * speed increases
> [...]
> Compare the execution time when installed with RubyGems:
> $ time fri -f plain String > /dev/null
>
> real 0m0.385s
> user 0m0.244s
> sys 0m0.036s
>
> to the time fri actually takes to run, without the overhead introduced by
> RubyGems:
> $ time ruby bin/fri -f plain String > /dev/null
>
> real 0m0.088s
> user 0m0.040s
> sys 0m0.008s
> [...]

Hm, the times are different on my box (P4 2.4 GHz, 1 G RAM,
Gentoo Linux, ruby 1.8.6 (2007-12-03 patchlevel 113) no threads):

$ time fri -f plain String > /dev/null

real 0m0.228s
user 0m0.152s
sys 0m0.019s

$ time ruby bin/fri -f plain String > /dev/null

real 0m0.147s
user 0m0.080s
sys 0m0.010s

fri installed with RubyGems is faster (0.228 / 0.385), fri from
the tarball ist slower (0.147 / 0.088) than or your box.

Is my box just slower than yours and is this the result of
improvements in the RubyGems-installed code?

Daniel

Eric Hodel

2/6/2008 10:52:00 PM

On Feb 3, 2008, at 07:40 AM, botp wrote:
> On Feb 3, 2008 1:07 AM, Mauricio Fernandez <mfp@acm.org> wrote:
>> FastRI is an alternative to the ri documentation browser for Ruby.
>
> forgive the dumb question, but how can i make fastri work for ruby1.9?
> thanks for fri/qri, mauricio. 'm very much dependent on it now :)

Are you really concerned about 1/10 of a second? (All times with hot
cache.)

$ time ri -f plain Array#fetch > /dev/null

real 0m0.589s
user 0m0.365s
sys 0m0.221s
$ time qri -f plain Array#fetch > /dev/null

real 0m0.110s
user 0m0.089s
sys 0m0.020s
$ time ri19 -f plain Array#fetch > /dev/null

real 0m0.208s
user 0m0.163s
sys 0m0.033s

Mauricio Fernández

2/18/2008 11:54:00 AM

On Thu, Feb 07, 2008 at 07:52:20AM +0900, Eric Hodel wrote:
> On Feb 3, 2008, at 07:40 AM, botp wrote:
> >On Feb 3, 2008 1:07 AM, Mauricio Fernandez <mfp@acm.org> wrote:
> >>FastRI is an alternative to the ri documentation browser for Ruby.
> >
> >forgive the dumb question, but how can i make fastri work for ruby1.9?
> >thanks for fri/qri, mauricio. 'm very much dependent on it now :)

I haven't ported it to 1.9 yet, mainly because 1.9.0 is still too unstable.
It shouldn't be hard, though.

> Are you really concerned about 1/10 of a second? (All times with hot
> cache.)
>
> $ time ri -f plain Array#fetch > /dev/null
> real 0m0.589s
[...]
> $ time qri -f plain Array#fetch > /dev/null
> real 0m0.110s
[...]
> $ time ri19 -f plain Array#fetch > /dev/null
> real 0m0.208s
[...]

1/10th of a second does matter in some cases (e.g. if qri is being called by an
editor to display "live" documentation), but the behavior when the cache isn't
hot matters much more to me:

(worst case, cold cache)

$ time qri -f plain Array#fetch > /dev/null

real 0m3.690s
...
$ time ri -f plain Array#fetch > /dev/null

real 0m32.235s
...
$ time ri19 -f plain Array#fetch > /dev/null
[...]
[BUG] Segmentation fault
ruby 1.9.0 (2007-12-20) [i686-linux]

Aborted

real 0m6.141s

I rarely refer to the RI documentation nowadays, but I definitely don't want
to wait for several seconds (the average case observed in practice, with a
"temperate cache") when I do, to have ri tell me something like this:

$ ri -T collect_file
More than one method matched your request. You can refine
your search by asking for information on one of:

Test::Unit::Collector::Dir#collect_file,
Test::Unit::Collector::Dir#collect_file,
Test::Unit::Collector::Dir#collect_file,
Test::Unit::Collector::Dir#collect_file,
Test::Unit::Collector::Dir#collect_file

Unfortunately, ri is so slow and buggy that many (me included) find it
unusable. FastRI is just an usable ri with some extra features (working
RubyGems support, full-text search, configurable lookup order, better search
strategies, etc.).

--
Mauricio Fernandez - http://eige...

Mauricio Fernández

2/18/2008 12:04:00 PM

On Wed, Feb 06, 2008 at 03:04:58AM +0900, Daniel Schömer wrote:
[...]
> fri installed with RubyGems is faster (0.228 / 0.385), fri from
> the tarball ist slower (0.147 / 0.088) than or your box.
>
> Is my box just slower than yours and is this the result of
> improvements in the RubyGems-installed code?

The times you quoted were taken on a machine more or less comparable to yours.
RubyGems has improved recently, to the point that most people might not notice
the difference between running fri directly or through RubyGems. At this point
it only seems to matter if you're using fri in your editor to display info for
expansion candidates, etc.

--
Mauricio Fernandez - http://eige...

James Gray

2/18/2008 2:18:00 PM

On Feb 18, 2008, at 5:53 AM, Mauricio Fernandez wrote:

> $ ri -T collect_file
> More than one method matched your request. You can refine
> your search by asking for information on one of:
>
> Test::Unit::Collector::Dir#collect_file,
> Test::Unit::Collector::Dir#collect_file,
> Test::Unit::Collector::Dir#collect_file,
> Test::Unit::Collector::Dir#collect_file,
> Test::Unit::Collector::Dir#collect_file
>
> Unfortunately, ri is so slow and buggy that many (me included) find it
> unusable. FastRI is just an usable ri with some extra features
> (working
> RubyGems support, full-text search, configurable lookup order,
> better search
> strategies, etc.).

Amen.

We had so many bug reports on TextMate's documentation command when we
used ri. We later switched to qri (part of FastRI) and added some
documentation about how to install it. Our bug reports are
practically gone now. When we do see one, we point them at the
install documentation and it solves their problem.

I really don't understand why we don't toss RI in the standard library
and replace it with the FastRI code. It's RI with more features, it's
faster, oh and it works. What's the downside exactly?

James Edward Gray II

James Britt

2/18/2008 4:45:00 PM

James Gray wrote:

>
> We had so many bug reports on TextMate's documentation command when we
> used ri. We later switched to qri (part of FastRI) and added some
> documentation about how to install it. Our bug reports are practically
> gone now. When we do see one, we point them at the install
> documentation and it solves their problem.
>
> I really don't understand why we don't toss RI in the standard library
> and replace it with the FastRI code. It's RI with more features, it's
> faster, oh and it works. What's the downside exactly?

I'm curious if drbrain is planning any changes to rdoc that would change
how ri might behave differently.

One of my complaints with the current ri/rdoc situation is how elective
module mixins get pushed into various class docs by default. For
example, looking up String, I see that strings have a to_yaml method.
Except, of course, they don't unless you explicitly include the YAML module.

ri and rdoc are brain-dead with regard to dynamic class composition.

fri has the exact same behavior (since it's using the same broken
datastore as ri)

It gets worse as more gems are installed if they do any base class
alterations. (f)ri tells me that strings have a "_expand_ch" method. I
have no idea where that even comes from.

--
James Britt

"Serious engineering is only a few thousand years old. Our attempts at
deliberately producing very complex robust systems are immature at best."
- Gerald Jay Sussman

Eric Hodel

2/19/2008 6:05:00 AM

On Feb 18, 2008, at 03:53 AM, Mauricio Fernandez wrote:
> $ ri -T collect_file
> More than one method matched your request. You can refine
> your search by asking for information on one of:
>
> Test::Unit::Collector::Dir#collect_file,
> Test::Unit::Collector::Dir#collect_file,
> Test::Unit::Collector::Dir#collect_file,
> Test::Unit::Collector::Dir#collect_file,
> Test::Unit::Collector::Dir#collect_file
>
> Unfortunately, ri is so slow and buggy that many (me included) find it
> unusable. FastRI is just an usable ri with some extra features
> (working
> RubyGems support, full-text search, configurable lookup order,
> better search
> strategies, etc.).

Strange, I don't see a bug filed in the tracker matching this:

http://rubyforge.org/tracker/index.php?group_id=627&...

If "many" people are having this problem, I would expect one of them
to file a bug.

comp.lang.ruby

[ANN] FastRI 0.3.1: faster, Leopard compatibility, etc.

Mauricio Fernández

Joel VanderWerf

Joel VanderWerf

botp

Daniel Schömer

Eric Hodel

Mauricio Fernández

Mauricio Fernández

James Gray

James Britt

Eric Hodel

x Login to ForumsZone