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.
@@ -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
@@ -11,6 +11,8 @@ have_func('closefrom')
11
11
  have_func('fdwalk')
12
12
  have_func('directio')
13
13
  have_func('writev')
14
+ have_func('readv', 'sys/uio.h')
15
+ have_func('preadv', 'sys/uio.h')
14
16
  have_func('ttyname')
15
17
 
16
18
  case RbConfig::CONFIG['host_os']
@@ -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>
@@ -0,0 +1,5 @@
1
+ ---
2
+ triple: 'arm64-apple-darwin'
3
+ binary-path: extra.bundle
4
+ relocations: []
5
+ ...