= net-wrong - experimental Ruby 1.9.3+ net/* monkey patch

The goal of this project is to obsolete itself and improve Ruby itself.
This RubyGem /may/ improve the performance of net/* libraries under
(matz) Ruby 1.9.3+.  If there is any benefit, large (memory-footprint)
applications stand more to gain than smaller ones.
See: https://bugs.ruby-lang.org/issues/5138 and
http://redmine.ruby-lang.org/issues/5765

== Features/Caveats

* Avoids expensive exceptions in Net::BufferedIO#rbuf_fill

* Avoids temporary classes which invalidate VM caches on GC

* Avoids (some) GC thrashing by reusing a temporary buffer

* Won't improve performance if using SSL connections

* Only net/http and net/smtp are tested for now.

== Things To Avoid When Using This

* Avoid using Timeout.timeout at all (always :P).

* Avoid using temporary Class objects on your own, this causes internal
  VM caches to be invalidated when Classes are garbage-collected

* Avoid using Timeout.timeout without an explicit exception class,
  Timeout.timeout will generate a temporary Classes.

* Avoid defining/redefining methods/constants once your application is
  running, you'll have temporary singleton Classes this way.

== Installing

This is only supported on mainline Ruby 1.9.3+ on Unix-like systems.

* gem install net-wrong

This depends on the following gems (which RubyGems should take care of):

* kgio - http://bogomips.org/kgio/
* terrible_timeout - http://bogomips.org/terrible_timeout/

== Using

All you need to do is require the appropriate module and continue
using your existing Net::* code as usual.  For Net::HTTP users,
you should:

   require "net/wrong/http"

If you're using Net::SMTP:

   require "net/wrong/smtp"

...And similar for the (untested) net/wrong/telnet and net/wrong/pop

== Hacking

* git clone git://bogomips.org/net-wrong

Email patches (git format-patch + git send-email) or pull requests
(git request-pull) to the public list <net.wrong@librelist.org>
and/or Eric Wong <normalperson@yhbt.net>

If you like web browsers, you can also view the source with a web browser:

http://bogomips.org/net-wrong.git

== Recommended

* net-http-persistent - manages persistent connections for Net::HTTP
  This reduces the use of terrible_timeout.

== Contact

Feedback (results, bug reports, patches, pull-requests) is very much
appreciated.

For issues/bugs/patches/pull-requests/improvements specific to this package
itself, email the mailing list net.wrong@librelist.org or
Eric Wong <normalperson@yhbt.net>.  Please send plain-text mail, HTML
will not be read.

There is an open ticket for improving things in the Ruby issue tracker:
https://bugs.ruby-lang.org/issues/5138 (forwards to ruby-core@ruby-lang.org)

== License

GPLv3

Patches submitted to Ruby related to this project have their respective
license(s) compatible with Ruby's.  GPLv3 only applies to code in
net-wrong.  Dependencies of net-wrong are also LGPL or GPL.

net-wrong is copyrighted Free Software by all contributors, see logs
in revision control for names and email addresses of all of them.

You can redistribute it and/or modify it under the terms of the GNU
General Public License (GPL) as published by the Free Software
Foundation, version {3}[http://www.gnu.org/licenses/gpl-3.0.txt].

net-wrong is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this library; if not, write to the Free Software Foundation,
Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301