io-extra 1.4.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/{CHANGES → CHANGES.md} +26 -17
- data/Gemfile +2 -0
- data/LICENSE +177 -0
- data/{MANIFEST → MANIFEST.md} +4 -4
- data/README.md +127 -0
- data/Rakefile +107 -0
- data/certs/djberg96_pub.pem +26 -0
- data/doc/io_extra.txt +85 -0
- data/examples/example_io_extra.rb +53 -0
- data/examples/example_pread.rb +24 -0
- data/examples/example_writev.rb +171 -0
- data/examples/writev_benchmark.rb +19 -0
- data/ext/extconf.rb +2 -0
- data/ext/extra.bundle.dSYM/Contents/Info.plist +20 -0
- data/ext/extra.bundle.dSYM/Contents/Resources/Relocations/aarch64/extra.bundle.yml +5 -0
- data/ext/io/extra.c +292 -81
- data/io-extra.gemspec +51 -0
- data/lib/io-extra.rb +3 -1
- data/spec/io_extra_spec.rb +235 -0
- data.tar.gz.sig +0 -0
- metadata +76 -16
- metadata.gz.sig +0 -0
- data/README +0 -97
- data/test/test_io_extra.rb +0 -148
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
##############################################################################
|
|
2
|
+
# example_io_extra.rb
|
|
3
|
+
#
|
|
4
|
+
# This is a small example program for the io-extra library. Modify as you see
|
|
5
|
+
# fit. You can run this via the 'rake example' task.
|
|
6
|
+
##############################################################################
|
|
7
|
+
require_relative "../lib/io-extra"
|
|
8
|
+
puts "VERSION: #{IO::EXTRA_VERSION}"
|
|
9
|
+
|
|
10
|
+
begin
|
|
11
|
+
fh = File.open("foo.txt","w+")
|
|
12
|
+
|
|
13
|
+
puts "DIRECTIO"
|
|
14
|
+
sleep 2
|
|
15
|
+
|
|
16
|
+
p fh.directio?
|
|
17
|
+
fh.directio = IO::DIRECTIO_ON
|
|
18
|
+
p fh.directio?
|
|
19
|
+
|
|
20
|
+
puts "FDWALK"
|
|
21
|
+
sleep 2
|
|
22
|
+
|
|
23
|
+
IO.fdwalk(0){ |handle|
|
|
24
|
+
p handle
|
|
25
|
+
p handle.fileno
|
|
26
|
+
puts
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
=begin
|
|
30
|
+
STDIN.close
|
|
31
|
+
|
|
32
|
+
# Should print "Hello" 2 times
|
|
33
|
+
IO.fdwalk(0){ |fd|
|
|
34
|
+
puts "Hello #{fd}"
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
IO.closefrom(0)
|
|
39
|
+
|
|
40
|
+
puts "Done" # Shouldn't see this
|
|
41
|
+
=end
|
|
42
|
+
|
|
43
|
+
puts "IO.writev"
|
|
44
|
+
sleep 2
|
|
45
|
+
|
|
46
|
+
a = (1..1000).map(&:to_s)
|
|
47
|
+
IO.writev(fh, a)
|
|
48
|
+
fh.rewind
|
|
49
|
+
p fh.read
|
|
50
|
+
ensure
|
|
51
|
+
fh.close
|
|
52
|
+
File.delete("foo.txt") if File.exist?("foo.txt")
|
|
53
|
+
end
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
########################################################################
|
|
2
|
+
# example_pread.rb
|
|
3
|
+
#
|
|
4
|
+
# Example program demonstrating the use of IO.pread.
|
|
5
|
+
########################################################################
|
|
6
|
+
require_relative '../lib/io-extra'
|
|
7
|
+
require 'tmpdir'
|
|
8
|
+
|
|
9
|
+
# Create a temporary file with a little data in it.
|
|
10
|
+
file = File.join(Dir.tmpdir, 'pread_test.txt')
|
|
11
|
+
File.open(file, 'w'){ |fh| 100.times{ |n| fh.puts "Hello: #{n}" } }
|
|
12
|
+
|
|
13
|
+
# Read from the file using pread.
|
|
14
|
+
begin
|
|
15
|
+
fh = File.open(file)
|
|
16
|
+
|
|
17
|
+
puts "Handle position before read: #{fh.pos}"
|
|
18
|
+
puts IO.pread(fh, 18, 0)
|
|
19
|
+
|
|
20
|
+
puts "Handle position after read: #{fh.pos}"
|
|
21
|
+
puts IO.pread(fh, 18, 0)
|
|
22
|
+
ensure
|
|
23
|
+
fh.close
|
|
24
|
+
end
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
#!/usr/bin/env ruby
|
|
2
|
+
##############################################################################
|
|
3
|
+
# example_writev.rb
|
|
4
|
+
#
|
|
5
|
+
# Demonstrates practical use cases for IO.writev, which writes multiple
|
|
6
|
+
# buffers in a single system call without concatenating them first.
|
|
7
|
+
#
|
|
8
|
+
# When to use writev:
|
|
9
|
+
# 1. Writing structured data with separate components (headers, body, etc.)
|
|
10
|
+
# 2. Logging with multiple fields that don't need string interpolation
|
|
11
|
+
# 3. Building protocol messages from discrete parts
|
|
12
|
+
# 4. Any scenario where you have an array of strings and want to avoid
|
|
13
|
+
# the memory overhead of joining them into one large string
|
|
14
|
+
##############################################################################
|
|
15
|
+
require_relative '../lib/io-extra'
|
|
16
|
+
|
|
17
|
+
puts "IO.writev Example - Version #{IO::EXTRA_VERSION}"
|
|
18
|
+
puts "IOV_MAX (max buffers per call): #{IO::IOV_MAX}"
|
|
19
|
+
puts "-" * 60
|
|
20
|
+
|
|
21
|
+
##############################################################################
|
|
22
|
+
# Example 1: Writing HTTP-like Response
|
|
23
|
+
# Instead of interpolating or joining strings, write each part directly
|
|
24
|
+
##############################################################################
|
|
25
|
+
puts "\n=== Example 1: HTTP-like Response ==="
|
|
26
|
+
|
|
27
|
+
http_parts = [
|
|
28
|
+
"HTTP/1.1 200 OK\r\n",
|
|
29
|
+
"Content-Type: text/html\r\n",
|
|
30
|
+
"Content-Length: 13\r\n",
|
|
31
|
+
"Connection: close\r\n",
|
|
32
|
+
"\r\n",
|
|
33
|
+
"Hello, World!"
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
File.open('http_response.txt', 'w') do |f|
|
|
37
|
+
bytes = IO.writev(f, http_parts)
|
|
38
|
+
puts "Wrote #{bytes} bytes for HTTP response"
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
puts "Contents:"
|
|
42
|
+
puts File.read('http_response.txt')
|
|
43
|
+
File.delete('http_response.txt')
|
|
44
|
+
|
|
45
|
+
##############################################################################
|
|
46
|
+
# Example 2: Log Entry with Structured Fields
|
|
47
|
+
# Avoid string interpolation overhead for high-volume logging
|
|
48
|
+
##############################################################################
|
|
49
|
+
puts "\n=== Example 2: Structured Log Entry ==="
|
|
50
|
+
|
|
51
|
+
def write_log_entry(io, timestamp, level, component, message)
|
|
52
|
+
parts = [
|
|
53
|
+
"[", timestamp, "] ",
|
|
54
|
+
"[", level.to_s.upcase.ljust(5), "] ",
|
|
55
|
+
"[", component, "] ",
|
|
56
|
+
message, "\n"
|
|
57
|
+
]
|
|
58
|
+
IO.writev(io, parts)
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
File.open('app.log', 'w') do |log|
|
|
62
|
+
write_log_entry(log, Time.now.iso8601, :info, "Database", "Connection established")
|
|
63
|
+
write_log_entry(log, Time.now.iso8601, :warn, "Cache", "Cache miss for key 'user:123'")
|
|
64
|
+
write_log_entry(log, Time.now.iso8601, :error, "Auth", "Invalid token received")
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
puts "Log contents:"
|
|
68
|
+
puts File.read('app.log')
|
|
69
|
+
File.delete('app.log')
|
|
70
|
+
|
|
71
|
+
##############################################################################
|
|
72
|
+
# Example 3: CSV Generation Without Building Large Strings
|
|
73
|
+
# Each row's fields can be written efficiently
|
|
74
|
+
##############################################################################
|
|
75
|
+
puts "\n=== Example 3: CSV Generation ==="
|
|
76
|
+
|
|
77
|
+
def write_csv_row(io, fields, separator: ",", newline: "\n")
|
|
78
|
+
parts = []
|
|
79
|
+
fields.each_with_index do |field, i|
|
|
80
|
+
parts << separator if i > 0
|
|
81
|
+
parts << field.to_s
|
|
82
|
+
end
|
|
83
|
+
parts << newline
|
|
84
|
+
IO.writev(io, parts)
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
File.open('data.csv', 'w') do |csv|
|
|
88
|
+
# Header
|
|
89
|
+
write_csv_row(csv, ['Name', 'Email', 'Department', 'Salary'])
|
|
90
|
+
|
|
91
|
+
# Data rows
|
|
92
|
+
employees = [
|
|
93
|
+
['Alice Smith', 'alice@example.com', 'Engineering', '95000'],
|
|
94
|
+
['Bob Jones', 'bob@example.com', 'Marketing', '75000'],
|
|
95
|
+
['Carol White', 'carol@example.com', 'Sales', '82000'],
|
|
96
|
+
]
|
|
97
|
+
|
|
98
|
+
employees.each { |emp| write_csv_row(csv, emp) }
|
|
99
|
+
end
|
|
100
|
+
|
|
101
|
+
puts "CSV contents:"
|
|
102
|
+
puts File.read('data.csv')
|
|
103
|
+
File.delete('data.csv')
|
|
104
|
+
|
|
105
|
+
##############################################################################
|
|
106
|
+
# Example 4: Building Network Protocol Messages
|
|
107
|
+
# Many protocols have fixed headers + variable payload
|
|
108
|
+
##############################################################################
|
|
109
|
+
puts "\n=== Example 4: Protocol Message Construction ==="
|
|
110
|
+
|
|
111
|
+
def build_message(io, msg_type, payload)
|
|
112
|
+
header = [msg_type].pack('C') # 1-byte message type
|
|
113
|
+
length = [payload.bytesize].pack('N') # 4-byte length (big-endian)
|
|
114
|
+
|
|
115
|
+
# Write header, length, and payload in one syscall
|
|
116
|
+
bytes = IO.writev(io, [header, length, payload])
|
|
117
|
+
puts " Message type #{msg_type}: #{bytes} bytes (#{payload.bytesize} payload)"
|
|
118
|
+
bytes
|
|
119
|
+
end
|
|
120
|
+
|
|
121
|
+
File.open('messages.bin', 'wb') do |f|
|
|
122
|
+
build_message(f, 1, "HELLO")
|
|
123
|
+
build_message(f, 2, "This is a longer message payload")
|
|
124
|
+
build_message(f, 3, "BYE")
|
|
125
|
+
end
|
|
126
|
+
|
|
127
|
+
puts "Binary file size: #{File.size('messages.bin')} bytes"
|
|
128
|
+
File.delete('messages.bin')
|
|
129
|
+
|
|
130
|
+
##############################################################################
|
|
131
|
+
# Example 5: Performance Comparison
|
|
132
|
+
# Shows memory efficiency when writing many small strings
|
|
133
|
+
##############################################################################
|
|
134
|
+
puts "\n=== Example 5: Memory Efficiency Comparison ==="
|
|
135
|
+
|
|
136
|
+
# Simulate a scenario with many small pieces of data
|
|
137
|
+
pieces = 500.times.map { |i| "item_#{i}|" }
|
|
138
|
+
|
|
139
|
+
# Method 1: Join then write (creates intermediate string)
|
|
140
|
+
joined = pieces.join
|
|
141
|
+
puts "Joined string size: #{joined.bytesize} bytes"
|
|
142
|
+
puts " - Creates a new string object in memory"
|
|
143
|
+
|
|
144
|
+
# Method 2: writev (no intermediate string needed)
|
|
145
|
+
File.open('writev_output.txt', 'w') do |f|
|
|
146
|
+
bytes = IO.writev(f, pieces)
|
|
147
|
+
puts "writev wrote: #{bytes} bytes"
|
|
148
|
+
puts " - No intermediate string allocation!"
|
|
149
|
+
end
|
|
150
|
+
|
|
151
|
+
File.delete('writev_output.txt')
|
|
152
|
+
|
|
153
|
+
##############################################################################
|
|
154
|
+
# Key Takeaways
|
|
155
|
+
##############################################################################
|
|
156
|
+
puts "\n" + "=" * 60
|
|
157
|
+
puts "KEY TAKEAWAYS - When to use IO.writev:"
|
|
158
|
+
puts "=" * 60
|
|
159
|
+
puts <<~TIPS
|
|
160
|
+
|
|
161
|
+
✓ You have pre-existing array of strings to write
|
|
162
|
+
✓ You want to avoid memory allocation from Array#join
|
|
163
|
+
✓ You're writing structured data with discrete components
|
|
164
|
+
✓ High-performance logging or protocol implementations
|
|
165
|
+
✓ Building output from template parts
|
|
166
|
+
|
|
167
|
+
✗ NOT needed for single strings (use regular write)
|
|
168
|
+
✗ NOT needed if you already have a joined string
|
|
169
|
+
✗ Watch out for IOV_MAX limit (#{IO::IOV_MAX} buffers max)
|
|
170
|
+
|
|
171
|
+
TIPS
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
require 'benchmark'
|
|
2
|
+
require 'io/extra'
|
|
3
|
+
|
|
4
|
+
a = (0..1023).to_a.map(&:to_s)
|
|
5
|
+
|
|
6
|
+
file1 = 'write_test.txt'
|
|
7
|
+
file2 = 'writev_test.txt'
|
|
8
|
+
|
|
9
|
+
fh = File.open(file2, 'w')
|
|
10
|
+
|
|
11
|
+
Benchmark.bm(25) do |x|
|
|
12
|
+
x.report('write'){ 100000.times{ File.write(file1, a.join) } }
|
|
13
|
+
x.report('writev'){ 100000.times{ IO.writev(fh.fileno, a) } }
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
fh.close
|
|
17
|
+
|
|
18
|
+
File.delete(file1)
|
|
19
|
+
File.delete(file2)
|
data/ext/extconf.rb
CHANGED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
2
|
+
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
3
|
+
<plist version="1.0">
|
|
4
|
+
<dict>
|
|
5
|
+
<key>CFBundleDevelopmentRegion</key>
|
|
6
|
+
<string>English</string>
|
|
7
|
+
<key>CFBundleIdentifier</key>
|
|
8
|
+
<string>com.apple.xcode.dsym.extra.bundle</string>
|
|
9
|
+
<key>CFBundleInfoDictionaryVersion</key>
|
|
10
|
+
<string>6.0</string>
|
|
11
|
+
<key>CFBundlePackageType</key>
|
|
12
|
+
<string>dSYM</string>
|
|
13
|
+
<key>CFBundleSignature</key>
|
|
14
|
+
<string>????</string>
|
|
15
|
+
<key>CFBundleShortVersionString</key>
|
|
16
|
+
<string>1.0</string>
|
|
17
|
+
<key>CFBundleVersion</key>
|
|
18
|
+
<string>1</string>
|
|
19
|
+
</dict>
|
|
20
|
+
</plist>
|