Description

Native IO for Windows. This class matches and extends the current Ruby
IO class API, using native Windows functions underneath the hood.

Installation

gem install win32-nio

Synopsis

require 'win32/nio'
include Win32

# Similar to Ruby
p NIO.read('some_file.text')
p NIO.read('some_file.text', 50)
p NIO.read('some_file.text', 50, 5)

p NIO.readlines('some_file.txt')
p NIO.readlines('some_file.txt', '')

# With events
event = Win32::Event.new

NIO.read('some_big_file.txt', nil, nil, event)
p event.signaled? # => true

# With blocks
NIO.read('some_big_file.txt'){ puts "Finished" }

Proof of Concept

This code was originally written to see if using pure Windows functions
to implement MRI methods would offer any practical advantage. The answer
is a definite maybe.

Functionally, these library does offer something the MRI methods do not,
which is the ability to provide a block or event object that is called
when a read is finished.

In terms of speed, I've found the NIO.read method to be almost twice as
fast as Ruby 2.2, while the NIO.readlines method was about the same speed.
In most cases the NIO.readlines method offers no practical advantage, but
see the documentation for details.

Benchmarks

Using my current laptop running Windows 7 I saw these results, which were
typical in repeated runs:

IO.read(small)         0.000000   0.016000   0.016000 (  0.020342)
NIO.read(small)        0.000000   0.000000   0.000000 (  0.008140)
IO.read(medium)        0.187000   0.047000   0.234000 (  0.230579)
NIO.read(medium)       0.015000   0.093000   0.108000 (  0.122542)
IO.read(large)         1.654000   0.593000   2.247000 (  2.355478)
NIO.read(large)        0.343000   0.765000   1.108000 (  1.222567)
IO.readlines(small)    0.125000   0.000000   0.125000 (  0.119982)
NIO.readlines(small)   0.094000   0.015000   0.109000 (  0.132461)
IO.readlines(medium)   1.419000   0.234000   1.653000 (  1.764216)
NIO.readlines(medium)  1.092000   0.109000   1.201000 (  1.537593)
IO.readlines(large)   12.714000   0.874000  13.588000 ( 13.798494)
NIO.readlines(large)   9.719000   0.468000  10.187000 ( 13.437217)

Your results may vary.

JRuby

As of version 0.2.0 this code was written as a C extension, and
does not support JRuby. However, JRuby users can continue to use
the 0.1.x branch.

Known Bugs

None that I know of. Please log any other bug reports on the RubyForge
project page at https://github.com/djberg96/win32-nio.

License

Artistic 2.0

Copyright

(C) 2008-2015 Daniel J. Berger, All Rights Reserved

Warranty

This package is provided "as is" and without any express or
implied warranties, including, without limitation, the implied
warranties of merchantability and fitness for a particular purpose.

Author(s)

Daniel Berger
Park Heesob