forked from tarcieri/iobuffer
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
83 lines (67 loc) · 2.16 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
= IO::Buffer
IO::Buffer is a fast byte queue which is primarily intended for non-blocking
I/O applications but is suitable wherever buffering is required. IO::Buffer
is compatible with Ruby 1.8.6+ and Ruby 1.9.0+
It was conceived for two reasons: it performs non-blocking buffered I/O
completely in C which removes the performance penalties associated with
implementing buffered I/O in pure Ruby, and also to mitigate performance
problems associated with M17N strings in Ruby 1.9.
== Usage
IO::Buffer provides a subset of the methods available in Strings:
>> buf = IO::Buffer.new
=> #<IO::Buffer:0x12fc708>
>> buf << "foo"
=> "foo"
>> buf << "bar"
=> "bar"
>> buf.to_str
=> "foobar"
>> buf.size
=> 6
The IO::Buffer#<< method is an alias for IO::Buffer#append. A prepend method
is also available:
>> buf = IO::Buffer.new
=> #<IO::Buffer:0x12f5250>
>> buf.append "bar"
=> "bar"
>> buf.prepend "foo"
=> "foo"
>> buf.append "baz"
=> "baz"
>> buf.to_str
=> "foobarbaz"
IO::Buffer#read can be used to retrieve the contents of a buffer. You can mix
reads alongside adding more data to the buffer:
>> buf = IO::Buffer.new
=> #<IO::Buffer:0x12fc5f0>
>> buf << "foo"
=> "foo"
>> buf.read 2
=> "fo"
>> buf << "bar"
=> "bar"
>> buf.read 2
=> "ob"
>> buf << "baz"
=> "baz"
>> buf.read 3
=> "arb"
Finally, IO::Buffer provides methods for performing non-blocking I/O with the
contents of the buffer. The IO::Buffer#read_from(IO) method will read as much
data as possible from the given IO object until the read would block.
The IO::Buffer#write_to(IO) method writes the contents of the buffer to the
given IO object until either the buffer is empty or the write would block:
>> buf = IO::Buffer.new
=> #<IO::Buffer:0x12fc5c8>
>> file = File.open("README")
=> #<File:README>
>> buf.read_from(file)
=> 1713
>> buf.to_str
=> "= IO::Buffer\n\nIO::Buffer is a fast byte queue...
If the file descriptor is not ready for I/O, the Errno::EAGAIN exception is
raised indicating no I/O was performed.
== History
IO::Buffer began its life as the buffer for Rev, a high performance event
library for Ruby.
As IO::Buffer has uses outside of Rev, it was spun off into its own Gem.