Ruby 4.0.10p0 (2026-11-19 revision a704b7cd95a42cc0cf5f307137bf3aac0285b915)
io_buffer.c
1/**********************************************************************
2
3 io_buffer.c
4
5 Copyright (C) 2021 Samuel Grant Dawson Williams
6
7**********************************************************************/
8
9#include "ruby/io/buffer.h"
11
12// For `rb_nogvl`.
13#include "ruby/thread.h"
14
15#include "internal.h"
16#include "internal/array.h"
17#include "internal/bits.h"
18#include "internal/error.h"
19#include "internal/gc.h"
20#include "internal/numeric.h"
21#include "internal/string.h"
22#include "internal/io.h"
23
24VALUE rb_cIOBuffer;
25VALUE rb_eIOBufferLockedError;
26VALUE rb_eIOBufferAllocationError;
27VALUE rb_eIOBufferAccessError;
28VALUE rb_eIOBufferInvalidatedError;
29VALUE rb_eIOBufferMaskError;
30
31size_t RUBY_IO_BUFFER_PAGE_SIZE;
32size_t RUBY_IO_BUFFER_DEFAULT_SIZE;
33
34#ifdef _WIN32
35#else
36#include <unistd.h>
37#include <sys/mman.h>
38#endif
39
40enum {
41 RB_IO_BUFFER_HEXDUMP_DEFAULT_WIDTH = 16,
42 RB_IO_BUFFER_HEXDUMP_MAXIMUM_WIDTH = 1024,
43
44 RB_IO_BUFFER_INSPECT_HEXDUMP_MAXIMUM_SIZE = 256,
45 RB_IO_BUFFER_INSPECT_HEXDUMP_WIDTH = 16,
46
47 // This is used to validate the flags given by the user.
48 RB_IO_BUFFER_FLAGS_MASK = RB_IO_BUFFER_EXTERNAL | RB_IO_BUFFER_INTERNAL | RB_IO_BUFFER_MAPPED | RB_IO_BUFFER_SHARED | RB_IO_BUFFER_LOCKED | RB_IO_BUFFER_PRIVATE | RB_IO_BUFFER_READONLY,
49
50 RB_IO_BUFFER_DEBUG = 0,
51};
52
54 void *base;
55 size_t size;
56 enum rb_io_buffer_flags flags;
57
58#if defined(_WIN32)
59 HANDLE mapping;
60#endif
61
62 VALUE source;
63};
64
65static inline void *
66io_buffer_map_memory(size_t size, int flags)
67{
68#if defined(_WIN32)
69 void * base = VirtualAlloc(0, size, MEM_COMMIT, PAGE_READWRITE);
70
71 if (!base) {
72 rb_sys_fail("io_buffer_map_memory:VirtualAlloc");
73 }
74#else
75 int mmap_flags = MAP_ANONYMOUS;
76 if (flags & RB_IO_BUFFER_SHARED) {
77 mmap_flags |= MAP_SHARED;
78 }
79 else {
80 mmap_flags |= MAP_PRIVATE;
81 }
82
83 void * base = mmap(NULL, size, PROT_READ | PROT_WRITE, mmap_flags, -1, 0);
84
85 if (base == MAP_FAILED) {
86 rb_sys_fail("io_buffer_map_memory:mmap");
87 }
88
89 ruby_annotate_mmap(base, size, "Ruby:io_buffer_map_memory");
90#endif
91
92 return base;
93}
94
95static void
96io_buffer_map_file(struct rb_io_buffer *buffer, int descriptor, size_t size, rb_off_t offset, enum rb_io_buffer_flags flags)
97{
98#if defined(_WIN32)
99 HANDLE file = (HANDLE)_get_osfhandle(descriptor);
100 if (!file) rb_sys_fail("io_buffer_map_descriptor:_get_osfhandle");
101
102 DWORD protect = PAGE_READONLY, access = FILE_MAP_READ;
103
104 if (flags & RB_IO_BUFFER_READONLY) {
105 buffer->flags |= RB_IO_BUFFER_READONLY;
106 }
107 else {
108 protect = PAGE_READWRITE;
109 access = FILE_MAP_WRITE;
110 }
111
112 if (flags & RB_IO_BUFFER_PRIVATE) {
113 protect = PAGE_WRITECOPY;
114 access = FILE_MAP_COPY;
115 buffer->flags |= RB_IO_BUFFER_PRIVATE;
116 }
117 else {
118 // This buffer refers to external buffer.
119 buffer->flags |= RB_IO_BUFFER_EXTERNAL;
120 buffer->flags |= RB_IO_BUFFER_SHARED;
121 }
122
123 HANDLE mapping = CreateFileMapping(file, NULL, protect, 0, 0, NULL);
124 if (RB_IO_BUFFER_DEBUG) fprintf(stderr, "io_buffer_map_file:CreateFileMapping -> %p\n", mapping);
125 if (!mapping) rb_sys_fail("io_buffer_map_descriptor:CreateFileMapping");
126
127 void *base = MapViewOfFile(mapping, access, (DWORD)(offset >> 32), (DWORD)(offset & 0xFFFFFFFF), size);
128
129 if (!base) {
130 CloseHandle(mapping);
131 rb_sys_fail("io_buffer_map_file:MapViewOfFile");
132 }
133
134 buffer->mapping = mapping;
135#else
136 int protect = PROT_READ, access = 0;
137
138 if (flags & RB_IO_BUFFER_READONLY) {
139 buffer->flags |= RB_IO_BUFFER_READONLY;
140 }
141 else {
142 protect |= PROT_WRITE;
143 }
144
145 if (flags & RB_IO_BUFFER_PRIVATE) {
146 buffer->flags |= RB_IO_BUFFER_PRIVATE;
147 access |= MAP_PRIVATE;
148 }
149 else {
150 // This buffer refers to external buffer.
151 buffer->flags |= RB_IO_BUFFER_EXTERNAL;
152 buffer->flags |= RB_IO_BUFFER_SHARED;
153 access |= MAP_SHARED;
154 }
155
156 void *base = mmap(NULL, size, protect, access, descriptor, offset);
157
158 if (base == MAP_FAILED) {
159 rb_sys_fail("io_buffer_map_file:mmap");
160 }
161#endif
162
163 buffer->base = base;
164 buffer->size = size;
165
166 buffer->flags |= RB_IO_BUFFER_MAPPED;
167 buffer->flags |= RB_IO_BUFFER_FILE;
168}
169
170static void
171io_buffer_experimental(void)
172{
173 static int warned = 0;
174
175 if (warned) return;
176
177 warned = 1;
178
179 if (rb_warning_category_enabled_p(RB_WARN_CATEGORY_EXPERIMENTAL)) {
181 "IO::Buffer is experimental and both the Ruby and C interface may change in the future!"
182 );
183 }
184}
185
186static void
187io_buffer_zero(struct rb_io_buffer *buffer)
188{
189 buffer->base = NULL;
190 buffer->size = 0;
191#if defined(_WIN32)
192 buffer->mapping = NULL;
193#endif
194 buffer->source = Qnil;
195}
196
197static void
198io_buffer_initialize(VALUE self, struct rb_io_buffer *buffer, void *base, size_t size, enum rb_io_buffer_flags flags, VALUE source)
199{
200 if (base) {
201 // If we are provided a pointer, we use it.
202 }
203 else if (size) {
204 // If we are provided a non-zero size, we allocate it:
205 if (flags & RB_IO_BUFFER_INTERNAL) {
206 base = calloc(size, 1);
207 }
208 else if (flags & RB_IO_BUFFER_MAPPED) {
209 base = io_buffer_map_memory(size, flags);
210 }
211
212 if (!base) {
213 rb_raise(rb_eIOBufferAllocationError, "Could not allocate buffer!");
214 }
215 }
216 else {
217 // Otherwise we don't do anything.
218 return;
219 }
220
221 buffer->base = base;
222 buffer->size = size;
223 buffer->flags = flags;
224 RB_OBJ_WRITE(self, &buffer->source, source);
225
226#if defined(_WIN32)
227 buffer->mapping = NULL;
228#endif
229}
230
231static void
232io_buffer_free(struct rb_io_buffer *buffer)
233{
234 if (buffer->base) {
235 if (buffer->flags & RB_IO_BUFFER_INTERNAL) {
236 free(buffer->base);
237 }
238
239 if (buffer->flags & RB_IO_BUFFER_MAPPED) {
240#ifdef _WIN32
241 if (buffer->flags & RB_IO_BUFFER_FILE) {
242 UnmapViewOfFile(buffer->base);
243 }
244 else {
245 VirtualFree(buffer->base, 0, MEM_RELEASE);
246 }
247#else
248 munmap(buffer->base, buffer->size);
249#endif
250 }
251
252 // Previously we had this, but we found out due to the way GC works, we
253 // can't refer to any other Ruby objects here.
254 // if (RB_TYPE_P(buffer->source, T_STRING)) {
255 // rb_str_unlocktmp(buffer->source);
256 // }
257
258 buffer->base = NULL;
259
260 buffer->size = 0;
261 buffer->flags = 0;
262 buffer->source = Qnil;
263 }
264
265#if defined(_WIN32)
266 if (buffer->mapping) {
267 if (RB_IO_BUFFER_DEBUG) fprintf(stderr, "io_buffer_free:CloseHandle -> %p\n", buffer->mapping);
268 if (!CloseHandle(buffer->mapping)) {
269 fprintf(stderr, "io_buffer_free:GetLastError -> %lu\n", GetLastError());
270 }
271 buffer->mapping = NULL;
272 }
273#endif
274}
275
276static void
277rb_io_buffer_type_mark(void *_buffer)
278{
279 struct rb_io_buffer *buffer = _buffer;
280 if (buffer->source != Qnil) {
281 if (RB_TYPE_P(buffer->source, T_STRING)) {
282 // The `source` String has to be pinned, because the `base` may point to the embedded String content,
283 // which can be otherwise moved by GC compaction.
284 rb_gc_mark(buffer->source);
285 } else {
286 rb_gc_mark_movable(buffer->source);
287 }
288 }
289}
290
291static void
292rb_io_buffer_type_compact(void *_buffer)
293{
294 struct rb_io_buffer *buffer = _buffer;
295 if (buffer->source != Qnil) {
296 if (RB_TYPE_P(buffer->source, T_STRING)) {
297 // The `source` String has to be pinned, because the `base` may point to the embedded String content,
298 // which can be otherwise moved by GC compaction.
299 } else {
300 buffer->source = rb_gc_location(buffer->source);
301 }
302 }
303}
304
305static void
306rb_io_buffer_type_free(void *_buffer)
307{
308 struct rb_io_buffer *buffer = _buffer;
309
310 io_buffer_free(buffer);
311}
312
313static size_t
314rb_io_buffer_type_size(const void *_buffer)
315{
316 const struct rb_io_buffer *buffer = _buffer;
317 size_t total = sizeof(struct rb_io_buffer);
318
319 if (buffer->flags) {
320 total += buffer->size;
321 }
322
323 return total;
324}
325
326static const rb_data_type_t rb_io_buffer_type = {
327 .wrap_struct_name = "IO::Buffer",
328 .function = {
329 .dmark = rb_io_buffer_type_mark,
330 .dfree = rb_io_buffer_type_free,
331 .dsize = rb_io_buffer_type_size,
332 .dcompact = rb_io_buffer_type_compact,
333 },
334 .data = NULL,
335 .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED | RUBY_TYPED_EMBEDDABLE,
336};
337
338static inline enum rb_io_buffer_flags
339io_buffer_extract_flags(VALUE argument)
340{
341 if (rb_int_negative_p(argument)) {
342 rb_raise(rb_eArgError, "Flags can't be negative!");
343 }
344
345 enum rb_io_buffer_flags flags = RB_NUM2UINT(argument);
346
347 // We deliberately ignore unknown flags. Any future flags which are exposed this way should be safe to ignore.
348 return flags & RB_IO_BUFFER_FLAGS_MASK;
349}
350
351// Extract an offset argument, which must be a non-negative integer.
352static inline size_t
353io_buffer_extract_offset(VALUE argument)
354{
355 if (rb_int_negative_p(argument)) {
356 rb_raise(rb_eArgError, "Offset can't be negative!");
357 }
358
359 return NUM2SIZET(argument);
360}
361
362// Extract a length argument, which must be a non-negative integer.
363// Length is generally considered a mutable property of an object and
364// semantically should be considered a subset of "size" as a concept.
365static inline size_t
366io_buffer_extract_length(VALUE argument)
367{
368 if (rb_int_negative_p(argument)) {
369 rb_raise(rb_eArgError, "Length can't be negative!");
370 }
371
372 return NUM2SIZET(argument);
373}
374
375// Extract a size argument, which must be a non-negative integer.
376// Size is generally considered an immutable property of an object.
377static inline size_t
378io_buffer_extract_size(VALUE argument)
379{
380 if (rb_int_negative_p(argument)) {
381 rb_raise(rb_eArgError, "Size can't be negative!");
382 }
383
384 return NUM2SIZET(argument);
385}
386
387// Extract a width argument, which must be a non-negative integer, and must be
388// at least the given minimum and at most RB_IO_BUFFER_HEXDUMP_MAXIMUM_WIDTH.
389static inline size_t
390io_buffer_extract_width(VALUE argument, size_t minimum)
391{
392 if (rb_int_negative_p(argument)) {
393 rb_raise(rb_eArgError, "Width can't be negative!");
394 }
395
396 size_t width = NUM2SIZET(argument);
397
398 if (width < minimum) {
399 rb_raise(rb_eArgError, "Width must be at least %" PRIuSIZE "!", minimum);
400 }
401
402 if (width > RB_IO_BUFFER_HEXDUMP_MAXIMUM_WIDTH) {
403 rb_raise(rb_eArgError, "Width must be at most %" PRIuSIZE "!", (size_t)RB_IO_BUFFER_HEXDUMP_MAXIMUM_WIDTH);
404 }
405
406 return width;
407}
408
409// Compute the default length for a buffer, given an offset into that buffer.
410// The default length is the size of the buffer minus the offset. The offset
411// must be less than the size of the buffer otherwise the length will be
412// invalid; in that case, an ArgumentError exception will be raised.
413static inline size_t
414io_buffer_default_length(const struct rb_io_buffer *buffer, size_t offset)
415{
416 if (offset > buffer->size) {
417 rb_raise(rb_eArgError, "The given offset is bigger than the buffer size!");
418 }
419
420 // Note that the "length" is computed by the size the offset.
421 return buffer->size - offset;
422}
423
424// Extract the optional length and offset arguments, returning the buffer.
425// The length and offset are optional, but if they are provided, they must be
426// positive integers. If the length is not provided, the default length is
427// computed from the buffer size and offset. If the offset is not provided, it
428// defaults to zero.
429static inline struct rb_io_buffer *
430io_buffer_extract_length_offset(VALUE self, int argc, VALUE argv[], size_t *length, size_t *offset)
431{
432 struct rb_io_buffer *buffer = NULL;
433 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
434
435 if (argc >= 2 && !NIL_P(argv[1])) {
436 *offset = io_buffer_extract_offset(argv[1]);
437 }
438 else {
439 *offset = 0;
440 }
441
442 if (argc >= 1 && !NIL_P(argv[0])) {
443 *length = io_buffer_extract_length(argv[0]);
444 }
445 else {
446 *length = io_buffer_default_length(buffer, *offset);
447 }
448
449 return buffer;
450}
451
452// Extract the optional offset and length arguments, returning the buffer.
453// Similar to `io_buffer_extract_length_offset` but with the order of arguments
454// reversed.
455//
456// After much consideration, I decided to accept both forms.
457// The `(offset, length)` order is more natural when referring about data,
458// while the `(length, offset)` order is more natural when referring to
459// read/write operations. In many cases, with the latter form, `offset`
460// is usually not supplied.
461static inline struct rb_io_buffer *
462io_buffer_extract_offset_length(VALUE self, int argc, VALUE argv[], size_t *offset, size_t *length)
463{
464 struct rb_io_buffer *buffer = NULL;
465 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
466
467 if (argc >= 1 && !NIL_P(argv[0])) {
468 *offset = io_buffer_extract_offset(argv[0]);
469 }
470 else {
471 *offset = 0;
472 }
473
474 if (argc >= 2 && !NIL_P(argv[1])) {
475 *length = io_buffer_extract_length(argv[1]);
476 }
477 else {
478 *length = io_buffer_default_length(buffer, *offset);
479 }
480
481 return buffer;
482}
483
484VALUE
485rb_io_buffer_type_allocate(VALUE self)
486{
487 io_buffer_experimental();
488
489 struct rb_io_buffer *buffer = NULL;
490 VALUE instance = TypedData_Make_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
491
492 io_buffer_zero(buffer);
493
494 return instance;
495}
496
497static VALUE io_buffer_for_make_instance(VALUE klass, VALUE string, enum rb_io_buffer_flags flags)
498{
499 VALUE instance = rb_io_buffer_type_allocate(klass);
500
501 struct rb_io_buffer *buffer = NULL;
502 TypedData_Get_Struct(instance, struct rb_io_buffer, &rb_io_buffer_type, buffer);
503
504 flags |= RB_IO_BUFFER_EXTERNAL;
505
506 if (RB_OBJ_FROZEN(string))
507 flags |= RB_IO_BUFFER_READONLY;
508
509 if (!(flags & RB_IO_BUFFER_READONLY))
510 rb_str_modify(string);
511
512 io_buffer_initialize(instance, buffer, RSTRING_PTR(string), RSTRING_LEN(string), flags, string);
513
514 return instance;
515}
516
518 VALUE klass;
519 VALUE string;
520 VALUE instance;
521 enum rb_io_buffer_flags flags;
522};
523
524static VALUE
525io_buffer_for_yield_instance(VALUE _arguments)
526{
528
529 arguments->instance = io_buffer_for_make_instance(arguments->klass, arguments->string, arguments->flags);
530
531 if (!RB_OBJ_FROZEN(arguments->string)) {
532 rb_str_locktmp(arguments->string);
533 }
534
535 return rb_yield(arguments->instance);
536}
537
538static VALUE
539io_buffer_for_yield_instance_ensure(VALUE _arguments)
540{
542
543 if (arguments->instance != Qnil) {
544 rb_io_buffer_free(arguments->instance);
545 }
546
547 if (!RB_OBJ_FROZEN(arguments->string)) {
548 rb_str_unlocktmp(arguments->string);
549 }
550
551 return Qnil;
552}
553
554/*
555 * call-seq:
556 * IO::Buffer.for(string) -> readonly io_buffer
557 * IO::Buffer.for(string) {|io_buffer| ... read/write io_buffer ...}
558 *
559 * Creates a zero-copy IO::Buffer from the given string's memory. Without a
560 * block a frozen internal copy of the string is created efficiently and used
561 * as the buffer source. When a block is provided, the buffer is associated
562 * directly with the string's internal buffer and updating the buffer will
563 * update the string.
564 *
565 * Until #free is invoked on the buffer, either explicitly or via the garbage
566 * collector, the source string will be locked and cannot be modified.
567 *
568 * If the string is frozen, it will create a read-only buffer which cannot be
569 * modified. If the string is shared, it may trigger a copy-on-write when
570 * using the block form.
571 *
572 * string = 'test'
573 * buffer = IO::Buffer.for(string)
574 * buffer.external? #=> true
575 *
576 * buffer.get_string(0, 1)
577 * # => "t"
578 * string
579 * # => "test"
580 *
581 * buffer.resize(100)
582 * # in `resize': Cannot resize external buffer! (IO::Buffer::AccessError)
583 *
584 * IO::Buffer.for(string) do |buffer|
585 * buffer.set_string("T")
586 * string
587 * # => "Test"
588 * end
589 */
590VALUE
591rb_io_buffer_type_for(VALUE klass, VALUE string)
592{
593 StringValue(string);
594
595 // If the string is frozen, both code paths are okay.
596 // If the string is not frozen, if a block is not given, it must be frozen.
597 if (rb_block_given_p()) {
598 struct io_buffer_for_yield_instance_arguments arguments = {
599 .klass = klass,
600 .string = string,
601 .instance = Qnil,
602 .flags = 0,
603 };
604
605 return rb_ensure(io_buffer_for_yield_instance, (VALUE)&arguments, io_buffer_for_yield_instance_ensure, (VALUE)&arguments);
606 }
607 else {
608 // This internally returns the source string if it's already frozen.
609 string = rb_str_tmp_frozen_acquire(string);
610 return io_buffer_for_make_instance(klass, string, RB_IO_BUFFER_READONLY);
611 }
612}
613
614/*
615 * call-seq:
616 * IO::Buffer.string(length) {|io_buffer| ... read/write io_buffer ...} -> string
617 *
618 * Creates a new string of the given length and yields a zero-copy IO::Buffer
619 * instance to the block which uses the string as a source. The block is
620 * expected to write to the buffer and the string will be returned.
621 *
622 * IO::Buffer.string(4) do |buffer|
623 * buffer.set_string("Ruby")
624 * end
625 * # => "Ruby"
626 */
627VALUE
628rb_io_buffer_type_string(VALUE klass, VALUE length)
629{
630 VALUE string = rb_str_new(NULL, RB_NUM2LONG(length));
631
632 struct io_buffer_for_yield_instance_arguments arguments = {
633 .klass = klass,
634 .string = string,
635 .instance = Qnil,
636 };
637
638 rb_ensure(io_buffer_for_yield_instance, (VALUE)&arguments, io_buffer_for_yield_instance_ensure, (VALUE)&arguments);
639
640 return string;
641}
642
643VALUE
644rb_io_buffer_new(void *base, size_t size, enum rb_io_buffer_flags flags)
645{
646 VALUE instance = rb_io_buffer_type_allocate(rb_cIOBuffer);
647
648 struct rb_io_buffer *buffer = NULL;
649 TypedData_Get_Struct(instance, struct rb_io_buffer, &rb_io_buffer_type, buffer);
650
651 io_buffer_initialize(instance, buffer, base, size, flags, Qnil);
652
653 return instance;
654}
655
656VALUE
657rb_io_buffer_map(VALUE io, size_t size, rb_off_t offset, enum rb_io_buffer_flags flags)
658{
659 VALUE instance = rb_io_buffer_type_allocate(rb_cIOBuffer);
660
661 struct rb_io_buffer *buffer = NULL;
662 TypedData_Get_Struct(instance, struct rb_io_buffer, &rb_io_buffer_type, buffer);
663
664 int descriptor = rb_io_descriptor(io);
665
666 io_buffer_map_file(buffer, descriptor, size, offset, flags);
667
668 return instance;
669}
670
671/*
672 * call-seq: IO::Buffer.map(file, [size, [offset, [flags]]]) -> io_buffer
673 *
674 * Create an IO::Buffer for reading from +file+ by memory-mapping the file.
675 * +file+ should be a +File+ instance, opened for reading or reading and writing.
676 *
677 * Optional +size+ and +offset+ of mapping can be specified.
678 * Trying to map an empty file or specify +size+ of 0 will raise an error.
679 * Valid values for +offset+ are system-dependent.
680 *
681 * By default, the buffer is writable and expects the file to be writable.
682 * It is also shared, so several processes can use the same mapping.
683 *
684 * You can pass IO::Buffer::READONLY in +flags+ argument to make a read-only buffer;
685 * this allows to work with files opened only for reading.
686 * Specifying IO::Buffer::PRIVATE in +flags+ creates a private mapping,
687 * which will not impact other processes or the underlying file.
688 * It also allows updating a buffer created from a read-only file.
689 *
690 * File.write('test.txt', 'test')
691 *
692 * buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY)
693 * # => #<IO::Buffer 0x00000001014a0000+4 EXTERNAL MAPPED FILE SHARED READONLY>
694 *
695 * buffer.readonly? # => true
696 *
697 * buffer.get_string
698 * # => "test"
699 *
700 * buffer.set_string('b', 0)
701 * # 'IO::Buffer#set_string': Buffer is not writable! (IO::Buffer::AccessError)
702 *
703 * # create read/write mapping: length 4 bytes, offset 0, flags 0
704 * buffer = IO::Buffer.map(File.open('test.txt', 'r+'), 4, 0)
705 * buffer.set_string('b', 0)
706 * # => 1
707 *
708 * # Check it
709 * File.read('test.txt')
710 * # => "best"
711 *
712 * Note that some operating systems may not have cache coherency between mapped
713 * buffers and file reads.
714 */
715static VALUE
716io_buffer_map(int argc, VALUE *argv, VALUE klass)
717{
718 rb_check_arity(argc, 1, 4);
719
720 // We might like to handle a string path?
721 VALUE io = argv[0];
722
723 rb_off_t file_size = rb_file_size(io);
724 // Compiler can confirm that we handled file_size <= 0 case:
725 if (UNLIKELY(file_size <= 0)) {
726 rb_raise(rb_eArgError, "Invalid negative or zero file size!");
727 }
728 // Here, we assume that file_size is positive:
729 else if (UNLIKELY((uintmax_t)file_size > SIZE_MAX)) {
730 rb_raise(rb_eArgError, "File larger than address space!");
731 }
732
733 size_t size;
734 if (argc >= 2 && !RB_NIL_P(argv[1])) {
735 size = io_buffer_extract_size(argv[1]);
736 if (UNLIKELY(size == 0)) {
737 rb_raise(rb_eArgError, "Size can't be zero!");
738 }
739 if (UNLIKELY(size > (size_t)file_size)) {
740 rb_raise(rb_eArgError, "Size can't be larger than file size!");
741 }
742 }
743 else {
744 // This conversion should be safe:
745 size = (size_t)file_size;
746 }
747
748 // This is the file offset, not the buffer offset:
749 rb_off_t offset = 0;
750 if (argc >= 3) {
751 offset = NUM2OFFT(argv[2]);
752 if (UNLIKELY(offset < 0)) {
753 rb_raise(rb_eArgError, "Offset can't be negative!");
754 }
755 if (UNLIKELY(offset >= file_size)) {
756 rb_raise(rb_eArgError, "Offset too large!");
757 }
758 if (RB_NIL_P(argv[1])) {
759 // Decrease size if it's set from the actual file size:
760 size = (size_t)(file_size - offset);
761 }
762 else if (UNLIKELY((size_t)(file_size - offset) < size)) {
763 rb_raise(rb_eArgError, "Offset too large!");
764 }
765 }
766
767 enum rb_io_buffer_flags flags = 0;
768 if (argc >= 4) {
769 flags = io_buffer_extract_flags(argv[3]);
770 }
771
772 return rb_io_buffer_map(io, size, offset, flags);
773}
774
775// Compute the optimal allocation flags for a buffer of the given size.
776static inline enum rb_io_buffer_flags
777io_flags_for_size(size_t size)
778{
779 if (size >= RUBY_IO_BUFFER_PAGE_SIZE) {
780 return RB_IO_BUFFER_MAPPED;
781 }
782
783 return RB_IO_BUFFER_INTERNAL;
784}
785
786/*
787 * call-seq: IO::Buffer.new([size = DEFAULT_SIZE, [flags = 0]]) -> io_buffer
788 *
789 * Create a new zero-filled IO::Buffer of +size+ bytes.
790 * By default, the buffer will be _internal_: directly allocated chunk
791 * of the memory. But if the requested +size+ is more than OS-specific
792 * IO::Buffer::PAGE_SIZE, the buffer would be allocated using the
793 * virtual memory mechanism (anonymous +mmap+ on Unix, +VirtualAlloc+
794 * on Windows). The behavior can be forced by passing IO::Buffer::MAPPED
795 * as a second parameter.
796 *
797 * buffer = IO::Buffer.new(4)
798 * # =>
799 * # #<IO::Buffer 0x000055b34497ea10+4 INTERNAL>
800 * # 0x00000000 00 00 00 00 ....
801 *
802 * buffer.get_string(0, 1) # => "\x00"
803 *
804 * buffer.set_string("test")
805 * buffer
806 * # =>
807 * # #<IO::Buffer 0x000055b34497ea10+4 INTERNAL>
808 * # 0x00000000 74 65 73 74 test
809 */
810VALUE
811rb_io_buffer_initialize(int argc, VALUE *argv, VALUE self)
812{
813 rb_check_arity(argc, 0, 2);
814
815 struct rb_io_buffer *buffer = NULL;
816 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
817
818 size_t size;
819 if (argc > 0) {
820 size = io_buffer_extract_size(argv[0]);
821 }
822 else {
823 size = RUBY_IO_BUFFER_DEFAULT_SIZE;
824 }
825
826 enum rb_io_buffer_flags flags = 0;
827 if (argc >= 2) {
828 flags = io_buffer_extract_flags(argv[1]);
829 }
830 else {
831 flags |= io_flags_for_size(size);
832 }
833
834 io_buffer_initialize(self, buffer, NULL, size, flags, Qnil);
835
836 return self;
837}
838
839static int
840io_buffer_validate_slice(VALUE source, void *base, size_t size)
841{
842 void *source_base = NULL;
843 size_t source_size = 0;
844
845 if (RB_TYPE_P(source, T_STRING)) {
846 RSTRING_GETMEM(source, source_base, source_size);
847 }
848 else {
849 rb_io_buffer_get_bytes(source, &source_base, &source_size);
850 }
851
852 // Source is invalid:
853 if (source_base == NULL) return 0;
854
855 // Base is out of range:
856 if (base < source_base) return 0;
857
858 const void *source_end = (char*)source_base + source_size;
859 const void *end = (char*)base + size;
860
861 // End is out of range:
862 if (end > source_end) return 0;
863
864 // It seems okay:
865 return 1;
866}
867
868static int
869io_buffer_validate(struct rb_io_buffer *buffer)
870{
871 if (buffer->source != Qnil) {
872 // Only slices incur this overhead, unfortunately... better safe than sorry!
873 return io_buffer_validate_slice(buffer->source, buffer->base, buffer->size);
874 }
875 else {
876 return 1;
877 }
878}
879
880enum rb_io_buffer_flags
881rb_io_buffer_get_bytes(VALUE self, void **base, size_t *size)
882{
883 struct rb_io_buffer *buffer = NULL;
884 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
885
886 if (io_buffer_validate(buffer)) {
887 if (buffer->base) {
888 *base = buffer->base;
889 *size = buffer->size;
890
891 return buffer->flags;
892 }
893 }
894
895 *base = NULL;
896 *size = 0;
897
898 return 0;
899}
900
901// Internal function for accessing bytes for writing, wil
902static void
903io_buffer_validate_for_writing(struct rb_io_buffer *buffer)
904{
905 if (buffer->flags & RB_IO_BUFFER_READONLY ||
906 (!NIL_P(buffer->source) && OBJ_FROZEN(buffer->source))) {
907 rb_raise(rb_eIOBufferAccessError, "Buffer is not writable!");
908 }
909
910 if (!io_buffer_validate(buffer)) {
911 rb_raise(rb_eIOBufferInvalidatedError, "Buffer is invalid!");
912 }
913}
914
915static struct rb_io_buffer *
916get_io_buffer_for_writing(VALUE self)
917{
918 struct rb_io_buffer *buffer = NULL;
919 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
920 io_buffer_validate_for_writing(buffer);
921 return buffer;
922}
923
924static inline void
925io_buffer_get_bytes_for_writing(struct rb_io_buffer *buffer, void **base, size_t *size)
926{
927 io_buffer_validate_for_writing(buffer);
928
929 if (buffer->base) {
930 *base = buffer->base;
931 *size = buffer->size;
932 } else {
933 *base = NULL;
934 *size = 0;
935 }
936}
937
938void
939rb_io_buffer_get_bytes_for_writing(VALUE self, void **base, size_t *size)
940{
941 struct rb_io_buffer *buffer = NULL;
942 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
943
944 io_buffer_get_bytes_for_writing(buffer, base, size);
945}
946
947static void
948io_buffer_validate_for_reading(struct rb_io_buffer *buffer)
949{
950 if (!io_buffer_validate(buffer)) {
951 rb_raise(rb_eIOBufferInvalidatedError, "Buffer has been invalidated!");
952 }
953}
954
955static void
956io_buffer_get_bytes_for_reading(struct rb_io_buffer *buffer, const void **base, size_t *size)
957{
958 io_buffer_validate_for_reading(buffer);
959
960 if (buffer->base) {
961 *base = buffer->base;
962 *size = buffer->size;
963 } else {
964 *base = NULL;
965 *size = 0;
966 }
967}
968
969void
970rb_io_buffer_get_bytes_for_reading(VALUE self, const void **base, size_t *size)
971{
972 struct rb_io_buffer *buffer = NULL;
973 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
974
975 io_buffer_get_bytes_for_reading(buffer, base, size);
976}
977
978/*
979 * call-seq: to_s -> string
980 *
981 * Short representation of the buffer. It includes the address, size and
982 * symbolic flags. This format is subject to change.
983 *
984 * puts IO::Buffer.new(4) # uses to_s internally
985 * # #<IO::Buffer 0x000055769f41b1a0+4 INTERNAL>
986 */
987VALUE
988rb_io_buffer_to_s(VALUE self)
989{
990 struct rb_io_buffer *buffer = NULL;
991 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
992
993 VALUE result = rb_str_new_cstr("#<");
994
995 rb_str_append(result, rb_class_name(CLASS_OF(self)));
996 rb_str_catf(result, " %p+%"PRIdSIZE, buffer->base, buffer->size);
997
998 if (buffer->base == NULL) {
999 rb_str_cat2(result, " NULL");
1000 }
1001
1002 if (buffer->flags & RB_IO_BUFFER_EXTERNAL) {
1003 rb_str_cat2(result, " EXTERNAL");
1004 }
1005
1006 if (buffer->flags & RB_IO_BUFFER_INTERNAL) {
1007 rb_str_cat2(result, " INTERNAL");
1008 }
1009
1010 if (buffer->flags & RB_IO_BUFFER_MAPPED) {
1011 rb_str_cat2(result, " MAPPED");
1012 }
1013
1014 if (buffer->flags & RB_IO_BUFFER_FILE) {
1015 rb_str_cat2(result, " FILE");
1016 }
1017
1018 if (buffer->flags & RB_IO_BUFFER_SHARED) {
1019 rb_str_cat2(result, " SHARED");
1020 }
1021
1022 if (buffer->flags & RB_IO_BUFFER_LOCKED) {
1023 rb_str_cat2(result, " LOCKED");
1024 }
1025
1026 if (buffer->flags & RB_IO_BUFFER_PRIVATE) {
1027 rb_str_cat2(result, " PRIVATE");
1028 }
1029
1030 if (buffer->flags & RB_IO_BUFFER_READONLY) {
1031 rb_str_cat2(result, " READONLY");
1032 }
1033
1034 if (buffer->source != Qnil) {
1035 rb_str_cat2(result, " SLICE");
1036 }
1037
1038 if (!io_buffer_validate(buffer)) {
1039 rb_str_cat2(result, " INVALID");
1040 }
1041
1042 return rb_str_cat2(result, ">");
1043}
1044
1045// Compute the output size of a hexdump of the given width (bytes per line), total size, and whether it is the first line in the output.
1046// This is used to preallocate the output string.
1047inline static size_t
1048io_buffer_hexdump_output_size(size_t width, size_t size, int first)
1049{
1050 // The preview on the right hand side is 1:1:
1051 size_t total = size;
1052
1053 size_t whole_lines = (size / width);
1054 size_t partial_line = (size % width) ? 1 : 0;
1055
1056 // For each line:
1057 // 1 byte 10 bytes 1 byte width*3 bytes 1 byte size bytes
1058 // (newline) (address) (space) (hexdump ) (space) (preview)
1059 total += (whole_lines + partial_line) * (1 + 10 + width*3 + 1 + 1);
1060
1061 // If the hexdump is the first line, one less newline will be emitted:
1062 if (size && first) total -= 1;
1063
1064 return total;
1065}
1066
1067// Append a hexdump of the given width (bytes per line), base address, size, and whether it is the first line in the output.
1068// If the hexdump is not the first line, it will prepend a newline if there is any output at all.
1069// If formatting here is adjusted, please update io_buffer_hexdump_output_size accordingly.
1070static VALUE
1071io_buffer_hexdump(VALUE string, size_t width, const char *base, size_t length, size_t offset, int first)
1072{
1073 char *text = alloca(width+1);
1074 text[width] = '\0';
1075
1076 for (; offset < length; offset += width) {
1077 memset(text, '\0', width);
1078 if (first) {
1079 rb_str_catf(string, "0x%08" PRIxSIZE " ", offset);
1080 first = 0;
1081 }
1082 else {
1083 rb_str_catf(string, "\n0x%08" PRIxSIZE " ", offset);
1084 }
1085
1086 for (size_t i = 0; i < width; i += 1) {
1087 if (offset+i < length) {
1088 unsigned char value = ((unsigned char*)base)[offset+i];
1089
1090 if (value < 127 && isprint(value)) {
1091 text[i] = (char)value;
1092 }
1093 else {
1094 text[i] = '.';
1095 }
1096
1097 rb_str_catf(string, " %02x", value);
1098 }
1099 else {
1100 rb_str_cat2(string, " ");
1101 }
1102 }
1103
1104 rb_str_catf(string, " %s", text);
1105 }
1106
1107 return string;
1108}
1109
1110/*
1111 * call-seq: inspect -> string
1112 *
1113 * Inspect the buffer and report useful information about it's internal state.
1114 * Only a limited portion of the buffer will be displayed in a hexdump style
1115 * format.
1116 *
1117 * buffer = IO::Buffer.for("Hello World")
1118 * puts buffer.inspect
1119 * # #<IO::Buffer 0x000000010198ccd8+11 EXTERNAL READONLY SLICE>
1120 * # 0x00000000 48 65 6c 6c 6f 20 57 6f 72 6c 64 Hello World
1121 */
1122VALUE
1123rb_io_buffer_inspect(VALUE self)
1124{
1125 struct rb_io_buffer *buffer = NULL;
1126 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1127
1128 VALUE result = rb_io_buffer_to_s(self);
1129
1130 if (io_buffer_validate(buffer)) {
1131 // Limit the maximum size generated by inspect:
1132 size_t size = buffer->size;
1133 int clamped = 0;
1134
1135 if (size > RB_IO_BUFFER_INSPECT_HEXDUMP_MAXIMUM_SIZE) {
1136 size = RB_IO_BUFFER_INSPECT_HEXDUMP_MAXIMUM_SIZE;
1137 clamped = 1;
1138 }
1139
1140 io_buffer_hexdump(result, RB_IO_BUFFER_INSPECT_HEXDUMP_WIDTH, buffer->base, size, 0, 0);
1141
1142 if (clamped) {
1143 rb_str_catf(result, "\n(and %" PRIuSIZE " more bytes not printed)", buffer->size - size);
1144 }
1145 }
1146
1147 return result;
1148}
1149
1150/*
1151 * call-seq: size -> integer
1152 *
1153 * Returns the size of the buffer that was explicitly set (on creation with ::new
1154 * or on #resize), or deduced on buffer's creation from string or file.
1155 */
1156VALUE
1157rb_io_buffer_size(VALUE self)
1158{
1159 struct rb_io_buffer *buffer = NULL;
1160 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1161
1162 return SIZET2NUM(buffer->size);
1163}
1164
1165/*
1166 * call-seq: valid? -> true or false
1167 *
1168 * Returns whether the buffer buffer is accessible.
1169 *
1170 * A buffer becomes invalid if it is a slice of another buffer (or string)
1171 * which has been freed or re-allocated at a different address.
1172 */
1173static VALUE
1174rb_io_buffer_valid_p(VALUE self)
1175{
1176 struct rb_io_buffer *buffer = NULL;
1177 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1178
1179 return RBOOL(io_buffer_validate(buffer));
1180}
1181
1182/*
1183 * call-seq: null? -> true or false
1184 *
1185 * If the buffer was freed with #free, transferred with #transfer, or was
1186 * never allocated in the first place.
1187 *
1188 * buffer = IO::Buffer.new(0)
1189 * buffer.null? #=> true
1190 *
1191 * buffer = IO::Buffer.new(4)
1192 * buffer.null? #=> false
1193 * buffer.free
1194 * buffer.null? #=> true
1195 */
1196static VALUE
1197rb_io_buffer_null_p(VALUE self)
1198{
1199 struct rb_io_buffer *buffer = NULL;
1200 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1201
1202 return RBOOL(buffer->base == NULL);
1203}
1204
1205/*
1206 * call-seq: empty? -> true or false
1207 *
1208 * If the buffer has 0 size: it is created by ::new with size 0, or with ::for
1209 * from an empty string. (Note that empty files can't be mapped, so the buffer
1210 * created with ::map will never be empty.)
1211 */
1212static VALUE
1213rb_io_buffer_empty_p(VALUE self)
1214{
1215 struct rb_io_buffer *buffer = NULL;
1216 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1217
1218 return RBOOL(buffer->size == 0);
1219}
1220
1221/*
1222 * call-seq: external? -> true or false
1223 *
1224 * The buffer is _external_ if it references the memory which is not
1225 * allocated or mapped by the buffer itself.
1226 *
1227 * A buffer created using ::for has an external reference to the string's
1228 * memory.
1229 *
1230 * External buffer can't be resized.
1231 */
1232static VALUE
1233rb_io_buffer_external_p(VALUE self)
1234{
1235 struct rb_io_buffer *buffer = NULL;
1236 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1237
1238 return RBOOL(buffer->flags & RB_IO_BUFFER_EXTERNAL);
1239}
1240
1241/*
1242 * call-seq: internal? -> true or false
1243 *
1244 * If the buffer is _internal_, meaning it references memory allocated by the
1245 * buffer itself.
1246 *
1247 * An internal buffer is not associated with any external memory (e.g. string)
1248 * or file mapping.
1249 *
1250 * Internal buffers are created using ::new and is the default when the
1251 * requested size is less than the IO::Buffer::PAGE_SIZE and it was not
1252 * requested to be mapped on creation.
1253 *
1254 * Internal buffers can be resized, and such an operation will typically
1255 * invalidate all slices, but not always.
1256 */
1257static VALUE
1258rb_io_buffer_internal_p(VALUE self)
1259{
1260 struct rb_io_buffer *buffer = NULL;
1261 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1262
1263 return RBOOL(buffer->flags & RB_IO_BUFFER_INTERNAL);
1264}
1265
1266/*
1267 * call-seq: mapped? -> true or false
1268 *
1269 * If the buffer is _mapped_, meaning it references memory mapped by the
1270 * buffer.
1271 *
1272 * Mapped buffers are either anonymous, if created by ::new with the
1273 * IO::Buffer::MAPPED flag or if the size was at least IO::Buffer::PAGE_SIZE,
1274 * or backed by a file if created with ::map.
1275 *
1276 * Mapped buffers can usually be resized, and such an operation will typically
1277 * invalidate all slices, but not always.
1278 */
1279static VALUE
1280rb_io_buffer_mapped_p(VALUE self)
1281{
1282 struct rb_io_buffer *buffer = NULL;
1283 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1284
1285 return RBOOL(buffer->flags & RB_IO_BUFFER_MAPPED);
1286}
1287
1288/*
1289 * call-seq: shared? -> true or false
1290 *
1291 * If the buffer is _shared_, meaning it references memory that can be shared
1292 * with other processes (and thus might change without being modified
1293 * locally).
1294 *
1295 * # Create a test file:
1296 * File.write('test.txt', 'test')
1297 *
1298 * # Create a shared mapping from the given file, the file must be opened in
1299 * # read-write mode unless we also specify IO::Buffer::READONLY:
1300 * buffer = IO::Buffer.map(File.open('test.txt', 'r+'), nil, 0)
1301 * # => #<IO::Buffer 0x00007f1bffd5e000+4 EXTERNAL MAPPED SHARED>
1302 *
1303 * # Write to the buffer, which will modify the mapped file:
1304 * buffer.set_string('b', 0)
1305 * # => 1
1306 *
1307 * # The file itself is modified:
1308 * File.read('test.txt')
1309 * # => "best"
1310 */
1311static VALUE
1312rb_io_buffer_shared_p(VALUE self)
1313{
1314 struct rb_io_buffer *buffer = NULL;
1315 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1316
1317 return RBOOL(buffer->flags & RB_IO_BUFFER_SHARED);
1318}
1319
1320/*
1321 * call-seq: locked? -> true or false
1322 *
1323 * If the buffer is _locked_, meaning it is inside #locked block execution.
1324 * Locked buffer can't be resized or freed, and another lock can't be acquired
1325 * on it.
1326 *
1327 * Locking is not thread safe, but is a semantic used to ensure buffers don't
1328 * move while being used by a system call.
1329 *
1330 * buffer.locked do
1331 * buffer.write(io) # theoretical system call interface
1332 * end
1333 */
1334static VALUE
1335rb_io_buffer_locked_p(VALUE self)
1336{
1337 struct rb_io_buffer *buffer = NULL;
1338 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1339
1340 return RBOOL(buffer->flags & RB_IO_BUFFER_LOCKED);
1341}
1342
1343/* call-seq: private? -> true or false
1344 *
1345 * If the buffer is _private_, meaning modifications to the buffer will not
1346 * be replicated to the underlying file mapping.
1347 *
1348 * # Create a test file:
1349 * File.write('test.txt', 'test')
1350 *
1351 * # Create a private mapping from the given file. Note that the file here
1352 * # is opened in read-only mode, but it doesn't matter due to the private
1353 * # mapping:
1354 * buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::PRIVATE)
1355 * # => #<IO::Buffer 0x00007fce63f11000+4 MAPPED PRIVATE>
1356 *
1357 * # Write to the buffer (invoking CoW of the underlying file buffer):
1358 * buffer.set_string('b', 0)
1359 * # => 1
1360 *
1361 * # The file itself is not modified:
1362 * File.read('test.txt')
1363 * # => "test"
1364 */
1365static VALUE
1366rb_io_buffer_private_p(VALUE self)
1367{
1368 struct rb_io_buffer *buffer = NULL;
1369 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1370
1371 return RBOOL(buffer->flags & RB_IO_BUFFER_PRIVATE);
1372}
1373
1374int
1375rb_io_buffer_readonly_p(VALUE self)
1376{
1377 struct rb_io_buffer *buffer = NULL;
1378 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1379
1380 return buffer->flags & RB_IO_BUFFER_READONLY;
1381}
1382
1383/*
1384 * call-seq: readonly? -> true or false
1385 *
1386 * If the buffer is <i>read only</i>, meaning the buffer cannot be modified using
1387 * #set_value, #set_string or #copy and similar.
1388 *
1389 * Frozen strings and read-only files create read-only buffers.
1390 */
1391static VALUE
1392io_buffer_readonly_p(VALUE self)
1393{
1394 return RBOOL(rb_io_buffer_readonly_p(self));
1395}
1396
1397static int
1398io_buffer_try_lock(struct rb_io_buffer *buffer)
1399{
1400 if (buffer->flags & RB_IO_BUFFER_LOCKED) {
1401 return 0;
1402 }
1403
1404 buffer->flags |= RB_IO_BUFFER_LOCKED;
1405 return 1;
1406}
1407
1408static void
1409io_buffer_lock(struct rb_io_buffer *buffer)
1410{
1411 if (!io_buffer_try_lock(buffer)) {
1412 rb_raise(rb_eIOBufferLockedError, "Buffer already locked!");
1413 }
1414}
1415
1416VALUE
1417rb_io_buffer_lock(VALUE self)
1418{
1419 struct rb_io_buffer *buffer = NULL;
1420 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1421
1422 io_buffer_lock(buffer);
1423
1424 return self;
1425}
1426
1427static void
1428io_buffer_unlock(struct rb_io_buffer *buffer)
1429{
1430 if (!(buffer->flags & RB_IO_BUFFER_LOCKED)) {
1431 rb_raise(rb_eIOBufferLockedError, "Buffer not locked!");
1432 }
1433
1434 buffer->flags &= ~RB_IO_BUFFER_LOCKED;
1435}
1436
1437VALUE
1438rb_io_buffer_unlock(VALUE self)
1439{
1440 struct rb_io_buffer *buffer = NULL;
1441 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1442
1443 io_buffer_unlock(buffer);
1444
1445 return self;
1446}
1447
1448int
1449rb_io_buffer_try_unlock(VALUE self)
1450{
1451 struct rb_io_buffer *buffer = NULL;
1452 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1453
1454 if (buffer->flags & RB_IO_BUFFER_LOCKED) {
1455 buffer->flags &= ~RB_IO_BUFFER_LOCKED;
1456 return 1;
1457 }
1458
1459 return 0;
1460}
1461
1462static VALUE
1463rb_io_buffer_locked_ensure(VALUE self)
1464{
1465 struct rb_io_buffer *buffer = NULL;
1466 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1467
1468 buffer->flags &= ~RB_IO_BUFFER_LOCKED;
1469
1470 return Qnil;
1471}
1472
1473/*
1474 * call-seq: locked { ... }
1475 *
1476 * Allows to process a buffer in exclusive way, for concurrency-safety. While
1477 * the block is performed, the buffer is considered locked, and no other code
1478 * can enter the lock. Also, locked buffer can't be changed with #resize or
1479 * #free.
1480 *
1481 * The following operations acquire a lock: #resize, #free.
1482 *
1483 * Locking is not thread safe. It is designed as a safety net around
1484 * non-blocking system calls. You can only share a buffer between threads with
1485 * appropriate synchronisation techniques.
1486 *
1487 * buffer = IO::Buffer.new(4)
1488 * buffer.locked? #=> false
1489 *
1490 * Fiber.schedule do
1491 * buffer.locked do
1492 * buffer.write(io) # theoretical system call interface
1493 * end
1494 * end
1495 *
1496 * Fiber.schedule do
1497 * # in `locked': Buffer already locked! (IO::Buffer::LockedError)
1498 * buffer.locked do
1499 * buffer.set_string("test", 0)
1500 * end
1501 * end
1502 */
1503VALUE
1504rb_io_buffer_locked(VALUE self)
1505{
1506 struct rb_io_buffer *buffer = NULL;
1507 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1508
1509 if (buffer->flags & RB_IO_BUFFER_LOCKED) {
1510 rb_raise(rb_eIOBufferLockedError, "Buffer already locked!");
1511 }
1512
1513 buffer->flags |= RB_IO_BUFFER_LOCKED;
1514
1515 return rb_ensure(rb_yield, self, rb_io_buffer_locked_ensure, self);
1516}
1517
1518/*
1519 * call-seq: free -> self
1520 *
1521 * If the buffer references memory, release it back to the operating system.
1522 * * for a _mapped_ buffer (e.g. from file): unmap.
1523 * * for a buffer created from scratch: free memory.
1524 * * for a buffer created from string: undo the association.
1525 *
1526 * After the buffer is freed, no further operations can't be performed on it.
1527 *
1528 * You can resize a freed buffer to re-allocate it.
1529 *
1530 * buffer = IO::Buffer.for('test')
1531 * buffer.free
1532 * # => #<IO::Buffer 0x0000000000000000+0 NULL>
1533 *
1534 * buffer.get_value(:U8, 0)
1535 * # in `get_value': The buffer is not allocated! (IO::Buffer::AllocationError)
1536 *
1537 * buffer.get_string
1538 * # in `get_string': The buffer is not allocated! (IO::Buffer::AllocationError)
1539 *
1540 * buffer.null?
1541 * # => true
1542 */
1543VALUE
1544rb_io_buffer_free(VALUE self)
1545{
1546 struct rb_io_buffer *buffer = NULL;
1547 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1548
1549 if (buffer->flags & RB_IO_BUFFER_LOCKED) {
1550 rb_raise(rb_eIOBufferLockedError, "Buffer is locked!");
1551 }
1552
1553 io_buffer_free(buffer);
1554
1555 return self;
1556}
1557
1558VALUE rb_io_buffer_free_locked(VALUE self)
1559{
1560 struct rb_io_buffer *buffer = NULL;
1561 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1562
1563 io_buffer_unlock(buffer);
1564 io_buffer_free(buffer);
1565
1566 return self;
1567}
1568
1569static bool
1570size_sum_is_bigger_than(size_t a, size_t b, size_t x)
1571{
1572 struct rbimpl_size_overflow_tag size = rbimpl_size_add_overflow(a, b);
1573 return size.overflowed || size.result > x;
1574}
1575
1576// Validate that access to the buffer is within bounds, assuming you want to
1577// access length bytes from the specified offset.
1578static inline void
1579io_buffer_validate_range(struct rb_io_buffer *buffer, size_t offset, size_t length)
1580{
1581 io_buffer_validate_for_reading(buffer);
1582
1583 if (size_sum_is_bigger_than(offset, length, buffer->size)) {
1584 rb_raise(rb_eArgError, "Specified offset+length is bigger than the buffer size!");
1585 }
1586}
1587
1588/*
1589 * call-seq: hexdump([offset, [length, [width]]]) -> string
1590 *
1591 * Returns a human-readable string representation of the buffer. The exact
1592 * format is subject to change.
1593 *
1594 * buffer = IO::Buffer.for("Hello World")
1595 * puts buffer.hexdump
1596 * # 0x00000000 48 65 6c 6c 6f 20 57 6f 72 6c 64 Hello World
1597 *
1598 * As buffers are usually fairly big, you may want to limit the output by
1599 * specifying the offset and length:
1600 *
1601 * puts buffer.hexdump(6, 5)
1602 * # 0x00000006 57 6f 72 6c 64 World
1603 */
1604static VALUE
1605rb_io_buffer_hexdump(int argc, VALUE *argv, VALUE self)
1606{
1607 rb_check_arity(argc, 0, 3);
1608
1609 size_t offset, length;
1610 struct rb_io_buffer *buffer = io_buffer_extract_offset_length(self, argc, argv, &offset, &length);
1611
1612 size_t width = RB_IO_BUFFER_HEXDUMP_DEFAULT_WIDTH;
1613 if (argc >= 3) {
1614 width = io_buffer_extract_width(argv[2], 1);
1615 }
1616
1617 // This may raise an exception if the offset/length is invalid:
1618 io_buffer_validate_range(buffer, offset, length);
1619
1620 VALUE result = Qnil;
1621
1622 if (io_buffer_validate(buffer) && buffer->base) {
1623 result = rb_str_buf_new(io_buffer_hexdump_output_size(width, length, 1));
1624
1625 io_buffer_hexdump(result, width, buffer->base, offset+length, offset, 1);
1626 }
1627
1628 return result;
1629}
1630
1631static VALUE
1632rb_io_buffer_slice(struct rb_io_buffer *buffer, VALUE self, size_t offset, size_t length)
1633{
1634 io_buffer_validate_range(buffer, offset, length);
1635
1636 VALUE instance = rb_io_buffer_type_allocate(rb_class_of(self));
1637 struct rb_io_buffer *slice = NULL;
1638 TypedData_Get_Struct(instance, struct rb_io_buffer, &rb_io_buffer_type, slice);
1639
1640 slice->flags |= (buffer->flags & RB_IO_BUFFER_READONLY);
1641 slice->base = (char*)buffer->base + offset;
1642 slice->size = length;
1643
1644 // The source should be the root buffer:
1645 if (buffer->source != Qnil) {
1646 RB_OBJ_WRITE(instance, &slice->source, buffer->source);
1647 }
1648 else {
1649 RB_OBJ_WRITE(instance, &slice->source, self);
1650 }
1651
1652 return instance;
1653}
1654
1655/*
1656 * call-seq: slice([offset, [length]]) -> io_buffer
1657 *
1658 * Produce another IO::Buffer which is a slice (or view into) the current one
1659 * starting at +offset+ bytes and going for +length+ bytes.
1660 *
1661 * The slicing happens without copying of memory, and the slice keeps being
1662 * associated with the original buffer's source (string, or file), if any.
1663 *
1664 * If the offset is not given, it will be zero. If the offset is negative, it
1665 * will raise an ArgumentError.
1666 *
1667 * If the length is not given, the slice will be as long as the original
1668 * buffer minus the specified offset. If the length is negative, it will raise
1669 * an ArgumentError.
1670 *
1671 * Raises RuntimeError if the <tt>offset+length</tt> is out of the current
1672 * buffer's bounds.
1673 *
1674 * string = 'test'
1675 * buffer = IO::Buffer.for(string).dup
1676 *
1677 * slice = buffer.slice
1678 * # =>
1679 * # #<IO::Buffer 0x0000000108338e68+4 SLICE>
1680 * # 0x00000000 74 65 73 74 test
1681 *
1682 * buffer.slice(2)
1683 * # =>
1684 * # #<IO::Buffer 0x0000000108338e6a+2 SLICE>
1685 * # 0x00000000 73 74 st
1686 *
1687 * slice = buffer.slice(1, 2)
1688 * # =>
1689 * # #<IO::Buffer 0x00007fc3d34ebc49+2 SLICE>
1690 * # 0x00000000 65 73 es
1691 *
1692 * # Put "o" into 0s position of the slice
1693 * slice.set_string('o', 0)
1694 * slice
1695 * # =>
1696 * # #<IO::Buffer 0x00007fc3d34ebc49+2 SLICE>
1697 * # 0x00000000 6f 73 os
1698 *
1699 * # it is also visible at position 1 of the original buffer
1700 * buffer
1701 * # =>
1702 * # #<IO::Buffer 0x00007fc3d31e2d80+4 INTERNAL>
1703 * # 0x00000000 74 6f 73 74 tost
1704 */
1705static VALUE
1706io_buffer_slice(int argc, VALUE *argv, VALUE self)
1707{
1708 rb_check_arity(argc, 0, 2);
1709
1710 size_t offset, length;
1711 struct rb_io_buffer *buffer = io_buffer_extract_offset_length(self, argc, argv, &offset, &length);
1712
1713 return rb_io_buffer_slice(buffer, self, offset, length);
1714}
1715
1716/*
1717 * call-seq: transfer -> new_io_buffer
1718 *
1719 * Transfers ownership of the underlying memory to a new buffer, causing the
1720 * current buffer to become uninitialized.
1721 *
1722 * buffer = IO::Buffer.new('test')
1723 * other = buffer.transfer
1724 * other
1725 * # =>
1726 * # #<IO::Buffer 0x00007f136a15f7b0+4 SLICE>
1727 * # 0x00000000 74 65 73 74 test
1728 * buffer
1729 * # =>
1730 * # #<IO::Buffer 0x0000000000000000+0 NULL>
1731 * buffer.null?
1732 * # => true
1733 */
1734VALUE
1735rb_io_buffer_transfer(VALUE self)
1736{
1737 struct rb_io_buffer *buffer = NULL;
1738 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1739
1740 if (buffer->flags & RB_IO_BUFFER_LOCKED) {
1741 rb_raise(rb_eIOBufferLockedError, "Cannot transfer ownership of locked buffer!");
1742 }
1743
1744 VALUE instance = rb_io_buffer_type_allocate(rb_class_of(self));
1745 struct rb_io_buffer *transferred;
1746 TypedData_Get_Struct(instance, struct rb_io_buffer, &rb_io_buffer_type, transferred);
1747
1748 *transferred = *buffer;
1749 io_buffer_zero(buffer);
1750
1751 return instance;
1752}
1753
1754static void
1755io_buffer_resize_clear(struct rb_io_buffer *buffer, void* base, size_t size)
1756{
1757 if (size > buffer->size) {
1758 memset((unsigned char*)base+buffer->size, 0, size - buffer->size);
1759 }
1760}
1761
1762static void
1763io_buffer_resize_copy(VALUE self, struct rb_io_buffer *buffer, size_t size)
1764{
1765 // Slow path:
1766 struct rb_io_buffer resized;
1767 io_buffer_initialize(self, &resized, NULL, size, io_flags_for_size(size), Qnil);
1768
1769 if (buffer->base) {
1770 size_t preserve = buffer->size;
1771 if (preserve > size) preserve = size;
1772 memcpy(resized.base, buffer->base, preserve);
1773
1774 io_buffer_resize_clear(buffer, resized.base, size);
1775 }
1776
1777 io_buffer_free(buffer);
1778 *buffer = resized;
1779}
1780
1781void
1782rb_io_buffer_resize(VALUE self, size_t size)
1783{
1784 struct rb_io_buffer *buffer = NULL;
1785 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
1786
1787 io_buffer_validate_for_reading(buffer);
1788
1789 if (buffer->flags & RB_IO_BUFFER_LOCKED) {
1790 rb_raise(rb_eIOBufferLockedError, "Cannot resize locked buffer!");
1791 }
1792
1793 if (buffer->base == NULL) {
1794 io_buffer_initialize(self, buffer, NULL, size, io_flags_for_size(size), Qnil);
1795 return;
1796 }
1797
1798 if (buffer->flags & RB_IO_BUFFER_EXTERNAL) {
1799 rb_raise(rb_eIOBufferAccessError, "Cannot resize external buffer!");
1800 }
1801
1802#if defined(HAVE_MREMAP) && defined(MREMAP_MAYMOVE)
1803 if (buffer->flags & RB_IO_BUFFER_MAPPED) {
1804 void *base = mremap(buffer->base, buffer->size, size, MREMAP_MAYMOVE);
1805
1806 if (base == MAP_FAILED) {
1807 rb_sys_fail("rb_io_buffer_resize:mremap");
1808 }
1809
1810 io_buffer_resize_clear(buffer, base, size);
1811
1812 buffer->base = base;
1813 buffer->size = size;
1814
1815 return;
1816 }
1817#endif
1818
1819 if (buffer->flags & RB_IO_BUFFER_INTERNAL) {
1820 if (size == 0) {
1821 io_buffer_free(buffer);
1822 return;
1823 }
1824
1825 void *base = realloc(buffer->base, size);
1826
1827 if (!base) {
1828 rb_sys_fail("rb_io_buffer_resize:realloc");
1829 }
1830
1831 io_buffer_resize_clear(buffer, base, size);
1832
1833 buffer->base = base;
1834 buffer->size = size;
1835
1836 return;
1837 }
1838
1839 io_buffer_resize_copy(self, buffer, size);
1840}
1841
1842/*
1843 * call-seq: resize(new_size) -> self
1844 *
1845 * Resizes a buffer to a +new_size+ bytes, preserving its content.
1846 * Depending on the old and new size, the memory area associated with
1847 * the buffer might be either extended, or rellocated at different
1848 * address with content being copied.
1849 *
1850 * buffer = IO::Buffer.new(4)
1851 * buffer.set_string("test", 0)
1852 * buffer.resize(8) # resize to 8 bytes
1853 * # =>
1854 * # #<IO::Buffer 0x0000555f5d1a1630+8 INTERNAL>
1855 * # 0x00000000 74 65 73 74 00 00 00 00 test....
1856 *
1857 * External buffer (created with ::for), and locked buffer
1858 * can not be resized.
1859 */
1860static VALUE
1861io_buffer_resize(VALUE self, VALUE size)
1862{
1863 rb_io_buffer_resize(self, io_buffer_extract_size(size));
1864
1865 return self;
1866}
1867
1868/*
1869 * call-seq: <=>(other) -> true or false
1870 *
1871 * Buffers are compared by size and exact contents of the memory they are
1872 * referencing using +memcmp+.
1873 */
1874static VALUE
1875rb_io_buffer_compare(VALUE self, VALUE other)
1876{
1877 const void *ptr1, *ptr2;
1878 size_t size1, size2;
1879
1880 rb_io_buffer_get_bytes_for_reading(self, &ptr1, &size1);
1881 rb_io_buffer_get_bytes_for_reading(other, &ptr2, &size2);
1882
1883 if (size1 < size2) {
1884 return RB_INT2NUM(-1);
1885 }
1886
1887 if (size1 > size2) {
1888 return RB_INT2NUM(1);
1889 }
1890
1891 return RB_INT2NUM(memcmp(ptr1, ptr2, size1));
1892}
1893
1894static void
1895io_buffer_validate_type(size_t size, size_t offset, size_t extend)
1896{
1897 if (size_sum_is_bigger_than(offset, extend, size)) {
1898 rb_raise(rb_eArgError, "Type extends beyond end of buffer! (offset=%"PRIdSIZE" > size=%"PRIdSIZE")", offset, size);
1899 }
1900}
1901
1902// Lower case: little endian.
1903// Upper case: big endian (network endian).
1904//
1905// :U8 | unsigned 8-bit integer.
1906// :S8 | signed 8-bit integer.
1907//
1908// :u16, :U16 | unsigned 16-bit integer.
1909// :s16, :S16 | signed 16-bit integer.
1910//
1911// :u32, :U32 | unsigned 32-bit integer.
1912// :s32, :S32 | signed 32-bit integer.
1913//
1914// :u64, :U64 | unsigned 64-bit integer.
1915// :s64, :S64 | signed 64-bit integer.
1916//
1917// :u128, :U128 | unsigned 128-bit integer.
1918// :s128, :S128 | signed 128-bit integer.
1919//
1920// :f32, :F32 | 32-bit floating point number.
1921// :f64, :F64 | 64-bit floating point number.
1922
1923#define ruby_swap8(value) value
1924
1925union swapf32 {
1926 uint32_t integral;
1927 float value;
1928};
1929
1930static float
1931ruby_swapf32(float value)
1932{
1933 union swapf32 swap = {.value = value};
1934 swap.integral = ruby_swap32(swap.integral);
1935 return swap.value;
1936}
1937
1938union swapf64 {
1939 uint64_t integral;
1940 double value;
1941};
1942
1943static double
1944ruby_swapf64(double value)
1945{
1946 union swapf64 swap = {.value = value};
1947 swap.integral = ruby_swap64(swap.integral);
1948 return swap.value;
1949}
1950
1951// Structures and conversion functions are now in numeric.h/numeric.c
1952// Unified swap function for 128-bit integers (works with both signed and unsigned)
1953// Since both rb_uint128_t and rb_int128_t have the same memory layout,
1954// we can use a union to make the swap function work with both types
1955static inline rb_uint128_t
1956ruby_swap128_uint(rb_uint128_t x)
1957{
1958 rb_uint128_t result;
1959#ifdef HAVE_UINT128_T
1960#if __has_builtin(__builtin_bswap128)
1961 result.value = __builtin_bswap128(x.value);
1962#else
1963 // Manual byte swap for 128-bit integers
1964 uint64_t low = (uint64_t)x.value;
1965 uint64_t high = (uint64_t)(x.value >> 64);
1966 low = ruby_swap64(low);
1967 high = ruby_swap64(high);
1968 result.value = ((uint128_t)low << 64) | high;
1969#endif
1970#else
1971 // Fallback swap function using two 64-bit integers
1972 // For big-endian data on little-endian host (or vice versa):
1973 // 1. Swap bytes within each 64-bit part
1974 // 2. Swap the order of the parts (since big-endian stores high first, little-endian stores low first)
1975 result.parts.low = ruby_swap64(x.parts.high);
1976 result.parts.high = ruby_swap64(x.parts.low);
1977#endif
1978 return result;
1979}
1980
1981static inline rb_int128_t
1982ruby_swap128_int(rb_int128_t x)
1983{
1984 union uint128_int128_conversion conversion = {
1985 .int128 = x
1986 };
1987 conversion.uint128 = ruby_swap128_uint(conversion.uint128);
1988 return conversion.int128;
1989}
1990
1991#define IO_BUFFER_VALIDATE_TYPE_FOR_WRITING(buffer, base, size, offset, type) \
1992 (io_buffer_get_bytes_for_writing(buffer, &(base), &(size)), \
1993 io_buffer_validate_type(size, offset, sizeof(type)))
1994
1995#define IO_BUFFER_DECLARE_TYPE(name, type, endian, wrap, unwrap, swap) \
1996static ID RB_IO_BUFFER_DATA_TYPE_##name; \
1997\
1998static VALUE \
1999io_buffer_read_##name(const void* base, size_t size, size_t *offset) \
2000{ \
2001 io_buffer_validate_type(size, *offset, sizeof(type)); \
2002 type value; \
2003 memcpy(&value, (char*)base + *offset, sizeof(type)); \
2004 if (endian != RB_IO_BUFFER_HOST_ENDIAN) value = swap(value); \
2005 *offset += sizeof(type); \
2006 return wrap(value); \
2007} \
2008\
2009static void \
2010io_buffer_write_##name(struct rb_io_buffer* buffer, size_t *offset, VALUE _value) \
2011{ \
2012 void* base; size_t size; \
2013 IO_BUFFER_VALIDATE_TYPE_FOR_WRITING(buffer, base, size, *offset, type); \
2014 type value = unwrap(_value); \
2015 IO_BUFFER_VALIDATE_TYPE_FOR_WRITING(buffer, base, size, *offset, type); \
2016 if (endian != RB_IO_BUFFER_HOST_ENDIAN) value = swap(value); \
2017 memcpy((char*)base + *offset, &value, sizeof(type)); \
2018 *offset += sizeof(type); \
2019} \
2020\
2021enum { \
2022 RB_IO_BUFFER_DATA_TYPE_##name##_SIZE = sizeof(type) \
2023};
2024
2025IO_BUFFER_DECLARE_TYPE(U8, uint8_t, RB_IO_BUFFER_BIG_ENDIAN, RB_UINT2NUM, RB_NUM2UINT, ruby_swap8)
2026IO_BUFFER_DECLARE_TYPE(S8, int8_t, RB_IO_BUFFER_BIG_ENDIAN, RB_INT2NUM, RB_NUM2INT, ruby_swap8)
2027
2028IO_BUFFER_DECLARE_TYPE(u16, uint16_t, RB_IO_BUFFER_LITTLE_ENDIAN, RB_UINT2NUM, RB_NUM2UINT, ruby_swap16)
2029IO_BUFFER_DECLARE_TYPE(U16, uint16_t, RB_IO_BUFFER_BIG_ENDIAN, RB_UINT2NUM, RB_NUM2UINT, ruby_swap16)
2030IO_BUFFER_DECLARE_TYPE(s16, int16_t, RB_IO_BUFFER_LITTLE_ENDIAN, RB_INT2NUM, RB_NUM2INT, ruby_swap16)
2031IO_BUFFER_DECLARE_TYPE(S16, int16_t, RB_IO_BUFFER_BIG_ENDIAN, RB_INT2NUM, RB_NUM2INT, ruby_swap16)
2032
2033IO_BUFFER_DECLARE_TYPE(u32, uint32_t, RB_IO_BUFFER_LITTLE_ENDIAN, RB_UINT2NUM, RB_NUM2UINT, ruby_swap32)
2034IO_BUFFER_DECLARE_TYPE(U32, uint32_t, RB_IO_BUFFER_BIG_ENDIAN, RB_UINT2NUM, RB_NUM2UINT, ruby_swap32)
2035IO_BUFFER_DECLARE_TYPE(s32, int32_t, RB_IO_BUFFER_LITTLE_ENDIAN, RB_INT2NUM, RB_NUM2INT, ruby_swap32)
2036IO_BUFFER_DECLARE_TYPE(S32, int32_t, RB_IO_BUFFER_BIG_ENDIAN, RB_INT2NUM, RB_NUM2INT, ruby_swap32)
2037
2038IO_BUFFER_DECLARE_TYPE(u64, uint64_t, RB_IO_BUFFER_LITTLE_ENDIAN, RB_ULL2NUM, RB_NUM2ULL, ruby_swap64)
2039IO_BUFFER_DECLARE_TYPE(U64, uint64_t, RB_IO_BUFFER_BIG_ENDIAN, RB_ULL2NUM, RB_NUM2ULL, ruby_swap64)
2040IO_BUFFER_DECLARE_TYPE(s64, int64_t, RB_IO_BUFFER_LITTLE_ENDIAN, RB_LL2NUM, RB_NUM2LL, ruby_swap64)
2041IO_BUFFER_DECLARE_TYPE(S64, int64_t, RB_IO_BUFFER_BIG_ENDIAN, RB_LL2NUM, RB_NUM2LL, ruby_swap64)
2042
2043IO_BUFFER_DECLARE_TYPE(u128, rb_uint128_t, RB_IO_BUFFER_LITTLE_ENDIAN, rb_uint128_to_numeric, rb_numeric_to_uint128, ruby_swap128_uint)
2044IO_BUFFER_DECLARE_TYPE(U128, rb_uint128_t, RB_IO_BUFFER_BIG_ENDIAN, rb_uint128_to_numeric, rb_numeric_to_uint128, ruby_swap128_uint)
2045IO_BUFFER_DECLARE_TYPE(s128, rb_int128_t, RB_IO_BUFFER_LITTLE_ENDIAN, rb_int128_to_numeric, rb_numeric_to_int128, ruby_swap128_int)
2046IO_BUFFER_DECLARE_TYPE(S128, rb_int128_t, RB_IO_BUFFER_BIG_ENDIAN, rb_int128_to_numeric, rb_numeric_to_int128, ruby_swap128_int)
2047
2048IO_BUFFER_DECLARE_TYPE(f32, float, RB_IO_BUFFER_LITTLE_ENDIAN, DBL2NUM, NUM2DBL, ruby_swapf32)
2049IO_BUFFER_DECLARE_TYPE(F32, float, RB_IO_BUFFER_BIG_ENDIAN, DBL2NUM, NUM2DBL, ruby_swapf32)
2050IO_BUFFER_DECLARE_TYPE(f64, double, RB_IO_BUFFER_LITTLE_ENDIAN, DBL2NUM, NUM2DBL, ruby_swapf64)
2051IO_BUFFER_DECLARE_TYPE(F64, double, RB_IO_BUFFER_BIG_ENDIAN, DBL2NUM, NUM2DBL, ruby_swapf64)
2052#undef IO_BUFFER_DECLARE_TYPE
2053
2054static inline size_t
2055io_buffer_buffer_type_size(ID buffer_type)
2056{
2057#define IO_BUFFER_DATA_TYPE_SIZE(name) if (buffer_type == RB_IO_BUFFER_DATA_TYPE_##name) return RB_IO_BUFFER_DATA_TYPE_##name##_SIZE;
2058 IO_BUFFER_DATA_TYPE_SIZE(U8)
2059 IO_BUFFER_DATA_TYPE_SIZE(S8)
2060 IO_BUFFER_DATA_TYPE_SIZE(u16)
2061 IO_BUFFER_DATA_TYPE_SIZE(U16)
2062 IO_BUFFER_DATA_TYPE_SIZE(s16)
2063 IO_BUFFER_DATA_TYPE_SIZE(S16)
2064 IO_BUFFER_DATA_TYPE_SIZE(u32)
2065 IO_BUFFER_DATA_TYPE_SIZE(U32)
2066 IO_BUFFER_DATA_TYPE_SIZE(s32)
2067 IO_BUFFER_DATA_TYPE_SIZE(S32)
2068 IO_BUFFER_DATA_TYPE_SIZE(u64)
2069 IO_BUFFER_DATA_TYPE_SIZE(U64)
2070 IO_BUFFER_DATA_TYPE_SIZE(s64)
2071 IO_BUFFER_DATA_TYPE_SIZE(S64)
2072 IO_BUFFER_DATA_TYPE_SIZE(u128)
2073 IO_BUFFER_DATA_TYPE_SIZE(U128)
2074 IO_BUFFER_DATA_TYPE_SIZE(s128)
2075 IO_BUFFER_DATA_TYPE_SIZE(S128)
2076 IO_BUFFER_DATA_TYPE_SIZE(f32)
2077 IO_BUFFER_DATA_TYPE_SIZE(F32)
2078 IO_BUFFER_DATA_TYPE_SIZE(f64)
2079 IO_BUFFER_DATA_TYPE_SIZE(F64)
2080#undef IO_BUFFER_DATA_TYPE_SIZE
2081
2082 rb_raise(rb_eArgError, "Invalid type name!");
2083}
2084
2085/*
2086 * call-seq:
2087 * size_of(buffer_type) -> byte size
2088 * size_of(array of buffer_type) -> byte size
2089 *
2090 * Returns the size of the given buffer type(s) in bytes.
2091 *
2092 * IO::Buffer.size_of(:u32) # => 4
2093 * IO::Buffer.size_of([:u32, :u32]) # => 8
2094 */
2095static VALUE
2096io_buffer_size_of(VALUE klass, VALUE buffer_type)
2097{
2098 if (RB_TYPE_P(buffer_type, T_ARRAY)) {
2099 size_t total = 0;
2100 for (long i = 0; i < RARRAY_LEN(buffer_type); i++) {
2101 total += io_buffer_buffer_type_size(RB_SYM2ID(RARRAY_AREF(buffer_type, i)));
2102 }
2103 return SIZET2NUM(total);
2104 }
2105 else {
2106 return SIZET2NUM(io_buffer_buffer_type_size(RB_SYM2ID(buffer_type)));
2107 }
2108}
2109
2110static inline VALUE
2111rb_io_buffer_get_value(const void* base, size_t size, ID buffer_type, size_t *offset)
2112{
2113#define IO_BUFFER_GET_VALUE(name) if (buffer_type == RB_IO_BUFFER_DATA_TYPE_##name) return io_buffer_read_##name(base, size, offset);
2114 IO_BUFFER_GET_VALUE(U8)
2115 IO_BUFFER_GET_VALUE(S8)
2116
2117 IO_BUFFER_GET_VALUE(u16)
2118 IO_BUFFER_GET_VALUE(U16)
2119 IO_BUFFER_GET_VALUE(s16)
2120 IO_BUFFER_GET_VALUE(S16)
2121
2122 IO_BUFFER_GET_VALUE(u32)
2123 IO_BUFFER_GET_VALUE(U32)
2124 IO_BUFFER_GET_VALUE(s32)
2125 IO_BUFFER_GET_VALUE(S32)
2126
2127 IO_BUFFER_GET_VALUE(u64)
2128 IO_BUFFER_GET_VALUE(U64)
2129 IO_BUFFER_GET_VALUE(s64)
2130 IO_BUFFER_GET_VALUE(S64)
2131
2132 IO_BUFFER_GET_VALUE(u128)
2133 IO_BUFFER_GET_VALUE(U128)
2134 IO_BUFFER_GET_VALUE(s128)
2135 IO_BUFFER_GET_VALUE(S128)
2136
2137 IO_BUFFER_GET_VALUE(f32)
2138 IO_BUFFER_GET_VALUE(F32)
2139 IO_BUFFER_GET_VALUE(f64)
2140 IO_BUFFER_GET_VALUE(F64)
2141#undef IO_BUFFER_GET_VALUE
2142
2143 rb_raise(rb_eArgError, "Invalid type name!");
2144}
2145
2146/*
2147 * call-seq: get_value(buffer_type, offset) -> numeric
2148 *
2149 * Read from buffer a value of +type+ at +offset+. +buffer_type+ should be one
2150 * of symbols:
2151 *
2152 * * +:U8+: unsigned integer, 1 byte
2153 * * +:S8+: signed integer, 1 byte
2154 * * +:u16+: unsigned integer, 2 bytes, little-endian
2155 * * +:U16+: unsigned integer, 2 bytes, big-endian
2156 * * +:s16+: signed integer, 2 bytes, little-endian
2157 * * +:S16+: signed integer, 2 bytes, big-endian
2158 * * +:u32+: unsigned integer, 4 bytes, little-endian
2159 * * +:U32+: unsigned integer, 4 bytes, big-endian
2160 * * +:s32+: signed integer, 4 bytes, little-endian
2161 * * +:S32+: signed integer, 4 bytes, big-endian
2162 * * +:u64+: unsigned integer, 8 bytes, little-endian
2163 * * +:U64+: unsigned integer, 8 bytes, big-endian
2164 * * +:s64+: signed integer, 8 bytes, little-endian
2165 * * +:S64+: signed integer, 8 bytes, big-endian
2166 * * +:u128+: unsigned integer, 16 bytes, little-endian
2167 * * +:U128+: unsigned integer, 16 bytes, big-endian
2168 * * +:s128+: signed integer, 16 bytes, little-endian
2169 * * +:S128+: signed integer, 16 bytes, big-endian
2170 * * +:f32+: float, 4 bytes, little-endian
2171 * * +:F32+: float, 4 bytes, big-endian
2172 * * +:f64+: double, 8 bytes, little-endian
2173 * * +:F64+: double, 8 bytes, big-endian
2174 *
2175 * A buffer type refers specifically to the type of binary buffer that is stored
2176 * in the buffer. For example, a +:u32+ buffer type is a 32-bit unsigned
2177 * integer in little-endian format.
2178 *
2179 * string = [1.5].pack('f')
2180 * # => "\x00\x00\xC0?"
2181 * IO::Buffer.for(string).get_value(:f32, 0)
2182 * # => 1.5
2183 */
2184static VALUE
2185io_buffer_get_value(VALUE self, VALUE type, VALUE _offset)
2186{
2187 const void *base;
2188 size_t size;
2189 size_t offset = io_buffer_extract_offset(_offset);
2190
2191 rb_io_buffer_get_bytes_for_reading(self, &base, &size);
2192
2193 return rb_io_buffer_get_value(base, size, RB_SYM2ID(type), &offset);
2194}
2195
2196/*
2197 * call-seq: get_values(buffer_types, offset) -> array
2198 *
2199 * Similar to #get_value, except that it can handle multiple buffer types and
2200 * returns an array of values.
2201 *
2202 * string = [1.5, 2.5].pack('ff')
2203 * IO::Buffer.for(string).get_values([:f32, :f32], 0)
2204 * # => [1.5, 2.5]
2205 */
2206static VALUE
2207io_buffer_get_values(VALUE self, VALUE buffer_types, VALUE _offset)
2208{
2209 size_t offset = io_buffer_extract_offset(_offset);
2210
2211 const void *base;
2212 size_t size;
2213 rb_io_buffer_get_bytes_for_reading(self, &base, &size);
2214
2215 if (!RB_TYPE_P(buffer_types, T_ARRAY)) {
2216 rb_raise(rb_eArgError, "Argument buffer_types should be an array!");
2217 }
2218
2219 VALUE array = rb_ary_new_capa(RARRAY_LEN(buffer_types));
2220
2221 for (long i = 0; i < RARRAY_LEN(buffer_types); i++) {
2222 VALUE type = rb_ary_entry(buffer_types, i);
2223 VALUE value = rb_io_buffer_get_value(base, size, RB_SYM2ID(type), &offset);
2224 rb_ary_push(array, value);
2225 }
2226
2227 return array;
2228}
2229
2230// Extract a count argument, which must be a positive integer.
2231// Count is generally considered relative to the number of things.
2232static inline size_t
2233io_buffer_extract_count(VALUE argument)
2234{
2235 if (rb_int_negative_p(argument)) {
2236 rb_raise(rb_eArgError, "Count can't be negative!");
2237 }
2238
2239 return NUM2SIZET(argument);
2240}
2241
2242static inline void
2243io_buffer_extract_offset_count(ID buffer_type, size_t size, int argc, VALUE *argv, size_t *offset, size_t *count)
2244{
2245 if (argc >= 1) {
2246 *offset = io_buffer_extract_offset(argv[0]);
2247 }
2248 else {
2249 *offset = 0;
2250 }
2251
2252 if (argc >= 2) {
2253 *count = io_buffer_extract_count(argv[1]);
2254 }
2255 else {
2256 if (*offset > size) {
2257 rb_raise(rb_eArgError, "The given offset is bigger than the buffer size!");
2258 }
2259
2260 *count = (size - *offset) / io_buffer_buffer_type_size(buffer_type);
2261 }
2262}
2263
2264/*
2265 * call-seq:
2266 * each(buffer_type, [offset, [count]]) {|offset, value| ...} -> self
2267 * each(buffer_type, [offset, [count]]) -> enumerator
2268 *
2269 * Iterates over the buffer, yielding each +value+ of +buffer_type+ starting
2270 * from +offset+.
2271 *
2272 * If +count+ is given, only +count+ values will be yielded.
2273 *
2274 * IO::Buffer.for("Hello World").each(:U8, 2, 2) do |offset, value|
2275 * puts "#{offset}: #{value}"
2276 * end
2277 * # 2: 108
2278 * # 3: 108
2279 */
2280static VALUE
2281io_buffer_each(int argc, VALUE *argv, VALUE self)
2282{
2283 RETURN_ENUMERATOR_KW(self, argc, argv, RB_NO_KEYWORDS);
2284
2285 const void *base;
2286 size_t size;
2287
2288 rb_io_buffer_get_bytes_for_reading(self, &base, &size);
2289
2290 ID buffer_type;
2291 if (argc >= 1) {
2292 buffer_type = RB_SYM2ID(argv[0]);
2293 }
2294 else {
2295 buffer_type = RB_IO_BUFFER_DATA_TYPE_U8;
2296 }
2297
2298 size_t offset, count;
2299 io_buffer_extract_offset_count(buffer_type, size, argc-1, argv+1, &offset, &count);
2300
2301 for (size_t i = 0; i < count; i++) {
2302 size_t current_offset = offset;
2303 VALUE value = rb_io_buffer_get_value(base, size, buffer_type, &offset);
2304 rb_yield_values(2, SIZET2NUM(current_offset), value);
2305 }
2306
2307 return self;
2308}
2309
2310/*
2311 * call-seq: values(buffer_type, [offset, [count]]) -> array
2312 *
2313 * Returns an array of values of +buffer_type+ starting from +offset+.
2314 *
2315 * If +count+ is given, only +count+ values will be returned.
2316 *
2317 * IO::Buffer.for("Hello World").values(:U8, 2, 2)
2318 * # => [108, 108]
2319 */
2320static VALUE
2321io_buffer_values(int argc, VALUE *argv, VALUE self)
2322{
2323 const void *base;
2324 size_t size;
2325
2326 rb_io_buffer_get_bytes_for_reading(self, &base, &size);
2327
2328 ID buffer_type;
2329 if (argc >= 1) {
2330 buffer_type = RB_SYM2ID(argv[0]);
2331 }
2332 else {
2333 buffer_type = RB_IO_BUFFER_DATA_TYPE_U8;
2334 }
2335
2336 size_t offset, count;
2337 io_buffer_extract_offset_count(buffer_type, size, argc-1, argv+1, &offset, &count);
2338
2339 VALUE array = rb_ary_new_capa(count);
2340
2341 for (size_t i = 0; i < count; i++) {
2342 VALUE value = rb_io_buffer_get_value(base, size, buffer_type, &offset);
2343 rb_ary_push(array, value);
2344 }
2345
2346 return array;
2347}
2348
2349/*
2350 * call-seq:
2351 * each_byte([offset, [count]]) {|byte| ...} -> self
2352 * each_byte([offset, [count]]) -> enumerator
2353 *
2354 * Iterates over the buffer, yielding each byte starting from +offset+.
2355 *
2356 * If +count+ is given, only +count+ bytes will be yielded.
2357 *
2358 * IO::Buffer.for("Hello World").each_byte(2, 2) do |offset, byte|
2359 * puts "#{offset}: #{byte}"
2360 * end
2361 * # 2: 108
2362 * # 3: 108
2363 */
2364static VALUE
2365io_buffer_each_byte(int argc, VALUE *argv, VALUE self)
2366{
2367 RETURN_ENUMERATOR_KW(self, argc, argv, RB_NO_KEYWORDS);
2368
2369 const void *base;
2370 size_t size;
2371
2372 rb_io_buffer_get_bytes_for_reading(self, &base, &size);
2373
2374 size_t offset, count;
2375 io_buffer_extract_offset_count(RB_IO_BUFFER_DATA_TYPE_U8, size, argc, argv, &offset, &count);
2376
2377 if (size_sum_is_bigger_than(offset, count, size)) {
2378 rb_raise(rb_eArgError, "Specified offset+count is bigger than the buffer size!");
2379 }
2380
2381 for (size_t i = 0; i < count; i++) {
2382 unsigned char *value = (unsigned char *)base + i + offset;
2383 rb_yield(RB_INT2FIX(*value));
2384 }
2385
2386 return self;
2387}
2388
2389static inline void
2390rb_io_buffer_set_value(struct rb_io_buffer *buffer, VALUE buffer_type, size_t *offset, VALUE value)
2391{
2392 ID type = RB_SYM2ID(buffer_type);
2393#define IO_BUFFER_SET_VALUE(name) if (type == RB_IO_BUFFER_DATA_TYPE_##name) {io_buffer_write_##name(buffer, offset, value); return;}
2394 IO_BUFFER_SET_VALUE(U8);
2395 IO_BUFFER_SET_VALUE(S8);
2396
2397 IO_BUFFER_SET_VALUE(u16);
2398 IO_BUFFER_SET_VALUE(U16);
2399 IO_BUFFER_SET_VALUE(s16);
2400 IO_BUFFER_SET_VALUE(S16);
2401
2402 IO_BUFFER_SET_VALUE(u32);
2403 IO_BUFFER_SET_VALUE(U32);
2404 IO_BUFFER_SET_VALUE(s32);
2405 IO_BUFFER_SET_VALUE(S32);
2406
2407 IO_BUFFER_SET_VALUE(u64);
2408 IO_BUFFER_SET_VALUE(U64);
2409 IO_BUFFER_SET_VALUE(s64);
2410 IO_BUFFER_SET_VALUE(S64);
2411
2412 IO_BUFFER_SET_VALUE(u128);
2413 IO_BUFFER_SET_VALUE(U128);
2414 IO_BUFFER_SET_VALUE(s128);
2415 IO_BUFFER_SET_VALUE(S128);
2416
2417 IO_BUFFER_SET_VALUE(f32);
2418 IO_BUFFER_SET_VALUE(F32);
2419 IO_BUFFER_SET_VALUE(f64);
2420 IO_BUFFER_SET_VALUE(F64);
2421#undef IO_BUFFER_SET_VALUE
2422
2423 rb_raise(rb_eArgError, "Invalid type name!");
2424}
2425
2427 struct rb_io_buffer *buffer;
2428 size_t offset;
2429 VALUE type, value;
2430};
2431
2432static VALUE
2433io_buffer_set_value_try(VALUE arguments)
2434{
2435 struct io_buffer_set_value_arguments *args = (void *)arguments;
2436 size_t offset = args->offset;
2437 rb_io_buffer_set_value(args->buffer, args->type, &offset, args->value);
2438 return SIZET2NUM(offset);
2439}
2440
2441/*
2442 * call-seq: set_value(type, offset, value) -> offset
2443 *
2444 * Write to a buffer a +value+ of +type+ at +offset+. +type+ should be one of
2445 * symbols described in #get_value.
2446 *
2447 * buffer = IO::Buffer.new(8)
2448 * # =>
2449 * # #<IO::Buffer 0x0000555f5c9a2d50+8 INTERNAL>
2450 * # 0x00000000 00 00 00 00 00 00 00 00
2451 *
2452 * buffer.set_value(:U8, 1, 111)
2453 * # => 1
2454 *
2455 * buffer
2456 * # =>
2457 * # #<IO::Buffer 0x0000555f5c9a2d50+8 INTERNAL>
2458 * # 0x00000000 00 6f 00 00 00 00 00 00 .o......
2459 *
2460 * Note that if the +type+ is integer and +value+ is Float, the implicit truncation is performed:
2461 *
2462 * buffer = IO::Buffer.new(8)
2463 * buffer.set_value(:U32, 0, 2.5)
2464 *
2465 * buffer
2466 * # =>
2467 * # #<IO::Buffer 0x0000555f5c9a2d50+8 INTERNAL>
2468 * # 0x00000000 00 00 00 02 00 00 00 00
2469 * # ^^ the same as if we'd pass just integer 2
2470 */
2471static VALUE
2472io_buffer_set_value(VALUE self, VALUE type, VALUE _offset, VALUE value)
2473{
2474 struct io_buffer_set_value_arguments arguments = {
2475 .buffer = get_io_buffer_for_writing(self),
2476 .offset = io_buffer_extract_offset(_offset),
2477 .type = type,
2478 .value = value,
2479 };
2480
2481 if (!io_buffer_try_lock(arguments.buffer)) {
2482 return io_buffer_set_value_try((VALUE)&arguments);
2483 }
2484 return rb_ensure(io_buffer_set_value_try, (VALUE)&arguments, rb_io_buffer_locked_ensure, self);
2485}
2486
2487static VALUE
2488io_buffer_set_values_try(VALUE arguments)
2489{
2490 struct io_buffer_set_value_arguments *args = (void *)arguments;
2491 size_t offset = args->offset;
2492
2493 for (long i = 0; i < RARRAY_LEN(args->type); i++) {
2494 VALUE type = rb_ary_entry(args->type, i);
2495 VALUE value = rb_ary_entry(args->value, i);
2496 rb_io_buffer_set_value(args->buffer, type, &offset, value);
2497 }
2498
2499 return SIZET2NUM(offset);
2500}
2501
2502/*
2503 * call-seq: set_values(buffer_types, offset, values) -> offset
2504 *
2505 * Write +values+ of +buffer_types+ at +offset+ to the buffer. +buffer_types+
2506 * should be an array of symbols as described in #get_value. +values+ should
2507 * be an array of values to write.
2508 *
2509 * buffer = IO::Buffer.new(8)
2510 * buffer.set_values([:U8, :U16], 0, [1, 2])
2511 * buffer
2512 * # =>
2513 * # #<IO::Buffer 0x696f717561746978+8 INTERNAL>
2514 * # 0x00000000 01 00 02 00 00 00 00 00 ........
2515 */
2516static VALUE
2517io_buffer_set_values(VALUE self, VALUE buffer_types, VALUE _offset, VALUE values)
2518{
2519 struct io_buffer_set_value_arguments arguments = {
2520 .buffer = get_io_buffer_for_writing(self),
2521 };
2522
2523 if (!RB_TYPE_P(buffer_types, T_ARRAY)) {
2524 rb_raise(rb_eArgError, "Argument buffer_types should be an array!");
2525 }
2526 arguments.type = buffer_types;
2527
2528 arguments.offset = io_buffer_extract_offset(_offset);
2529
2530 if (!RB_TYPE_P(values, T_ARRAY)) {
2531 rb_raise(rb_eArgError, "Argument values should be an array!");
2532 }
2533 arguments.value = values;
2534
2535 if (RARRAY_LEN(buffer_types) != RARRAY_LEN(values)) {
2536 rb_raise(rb_eArgError, "Argument buffer_types and values should have the same length!");
2537 }
2538
2539 if (!io_buffer_try_lock(arguments.buffer)) {
2540 return io_buffer_set_values_try((VALUE)&arguments);
2541 }
2542 return rb_ensure(io_buffer_set_values_try, (VALUE)&arguments, rb_io_buffer_locked_ensure, self);
2543
2544}
2545
2546static size_t IO_BUFFER_BLOCKING_SIZE = 1024*1024;
2547
2549 unsigned char * destination;
2550 const unsigned char * source;
2551 size_t length;
2552};
2553
2554static void *
2555io_buffer_memmove_blocking(void *data)
2556{
2557 struct io_buffer_memmove_arguments *arguments = (struct io_buffer_memmove_arguments *)data;
2558
2559 memmove(arguments->destination, arguments->source, arguments->length);
2560
2561 return NULL;
2562}
2563
2564static void
2565io_buffer_memmove_unblock(void *data)
2566{
2567 // No safe way to interrupt.
2568}
2569
2570static void
2571io_buffer_memmove(struct rb_io_buffer *buffer, size_t offset, const void *source_base, size_t source_offset, size_t source_size, size_t length)
2572{
2573 void *base;
2574 size_t size;
2575 io_buffer_get_bytes_for_writing(buffer, &base, &size);
2576
2577 io_buffer_validate_range(buffer, offset, length);
2578
2579 if (size_sum_is_bigger_than(source_offset, length, source_size)) {
2580 rb_raise(rb_eArgError, "The computed source range exceeds the size of the source buffer!");
2581 }
2582
2583 struct io_buffer_memmove_arguments arguments = {
2584 .destination = (unsigned char*)base+offset,
2585 .source = (unsigned char*)source_base+source_offset,
2586 .length = length
2587 };
2588
2589 if (arguments.length >= IO_BUFFER_BLOCKING_SIZE) {
2590 rb_nogvl(io_buffer_memmove_blocking, &arguments, io_buffer_memmove_unblock, &arguments, RB_NOGVL_OFFLOAD_SAFE);
2591 } else if (arguments.length != 0) {
2592 memmove(arguments.destination, arguments.source, arguments.length);
2593 }
2594}
2595
2596// (offset, length, source_offset) -> length
2597static VALUE
2598io_buffer_copy_from(struct rb_io_buffer *buffer, const void *source_base, size_t source_size, int argc, VALUE *argv)
2599{
2600 size_t offset = 0;
2601 size_t length;
2602 size_t source_offset;
2603
2604 // The offset we copy into the buffer:
2605 if (argc >= 1) {
2606 offset = io_buffer_extract_offset(argv[0]);
2607 }
2608
2609 // The offset we start from within the string:
2610 if (argc >= 3) {
2611 source_offset = io_buffer_extract_offset(argv[2]);
2612
2613 if (source_offset > source_size) {
2614 rb_raise(rb_eArgError, "The given source offset is bigger than the source itself!");
2615 }
2616 }
2617 else {
2618 source_offset = 0;
2619 }
2620
2621 // The length we are going to copy:
2622 if (argc >= 2 && !RB_NIL_P(argv[1])) {
2623 length = io_buffer_extract_length(argv[1]);
2624 }
2625 else {
2626 // Default to the source offset -> source size:
2627 length = source_size - source_offset;
2628 }
2629
2630 io_buffer_memmove(buffer, offset, source_base, source_offset, source_size, length);
2631
2632 return SIZET2NUM(length);
2633}
2634
2635/*
2636 * call-seq:
2637 * dup -> io_buffer
2638 * clone -> io_buffer
2639 *
2640 * Make an internal copy of the source buffer. Updates to the copy will not
2641 * affect the source buffer.
2642 *
2643 * source = IO::Buffer.for("Hello World")
2644 * # =>
2645 * # #<IO::Buffer 0x00007fd598466830+11 EXTERNAL READONLY SLICE>
2646 * # 0x00000000 48 65 6c 6c 6f 20 57 6f 72 6c 64 Hello World
2647 * buffer = source.dup
2648 * # =>
2649 * # #<IO::Buffer 0x0000558cbec03320+11 INTERNAL>
2650 * # 0x00000000 48 65 6c 6c 6f 20 57 6f 72 6c 64 Hello World
2651 */
2652static VALUE
2653rb_io_buffer_initialize_copy(VALUE self, VALUE source)
2654{
2655 struct rb_io_buffer *buffer = NULL;
2656 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
2657
2658 const void *source_base;
2659 size_t source_size;
2660
2661 rb_io_buffer_get_bytes_for_reading(source, &source_base, &source_size);
2662
2663 io_buffer_initialize(self, buffer, NULL, source_size, io_flags_for_size(source_size), Qnil);
2664
2665 VALUE result = io_buffer_copy_from(buffer, source_base, source_size, 0, NULL);
2666 RB_GC_GUARD(source);
2667 return result;
2668}
2669
2670/*
2671 * call-seq:
2672 * copy(source, [offset, [length, [source_offset]]]) -> size
2673 *
2674 * Efficiently copy from a source IO::Buffer into the buffer, at +offset+
2675 * using +memmove+. For copying String instances, see #set_string.
2676 *
2677 * buffer = IO::Buffer.new(32)
2678 * # =>
2679 * # #<IO::Buffer 0x0000555f5ca22520+32 INTERNAL>
2680 * # 0x00000000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
2681 * # 0x00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ *
2682 *
2683 * buffer.copy(IO::Buffer.for("test"), 8)
2684 * # => 4 -- size of buffer copied
2685 * buffer
2686 * # =>
2687 * # #<IO::Buffer 0x0000555f5cf8fe40+32 INTERNAL>
2688 * # 0x00000000 00 00 00 00 00 00 00 00 74 65 73 74 00 00 00 00 ........test....
2689 * # 0x00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ *
2690 *
2691 * #copy can be used to put buffer into strings associated with buffer:
2692 *
2693 * string = "data: "
2694 * # => "data: "
2695 * buffer = IO::Buffer.for(string) do |buffer|
2696 * buffer.copy(IO::Buffer.for("test"), 5)
2697 * end
2698 * # => 4
2699 * string
2700 * # => "data:test"
2701 *
2702 * Attempt to copy into a read-only buffer will fail:
2703 *
2704 * File.write('test.txt', 'test')
2705 * buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY)
2706 * buffer.copy(IO::Buffer.for("test"), 8)
2707 * # in `copy': Buffer is not writable! (IO::Buffer::AccessError)
2708 *
2709 * See ::map for details of creation of mutable file mappings, this will
2710 * work:
2711 *
2712 * buffer = IO::Buffer.map(File.open('test.txt', 'r+'))
2713 * buffer.copy(IO::Buffer.for("boom"), 0)
2714 * # => 4
2715 * File.read('test.txt')
2716 * # => "boom"
2717 *
2718 * Attempt to copy the buffer which will need place outside of buffer's
2719 * bounds will fail:
2720 *
2721 * buffer = IO::Buffer.new(2)
2722 * buffer.copy(IO::Buffer.for('test'), 0)
2723 * # in `copy': Specified offset+length is bigger than the buffer size! (ArgumentError)
2724 *
2725 * It is safe to copy between memory regions that overlaps each other.
2726 * In such case, the data is copied as if the data was first copied from the source buffer to
2727 * a temporary buffer, and then copied from the temporary buffer to the destination buffer.
2728 *
2729 * buffer = IO::Buffer.new(10)
2730 * buffer.set_string("0123456789")
2731 * buffer.copy(buffer, 3, 7)
2732 * # => 7
2733 * buffer
2734 * # =>
2735 * # #<IO::Buffer 0x000056494f8ce440+10 INTERNAL>
2736 * # 0x00000000 30 31 32 30 31 32 33 34 35 36 0120123456
2737 */
2738static VALUE
2739io_buffer_copy(int argc, VALUE *argv, VALUE self)
2740{
2741 rb_check_arity(argc, 1, 4);
2742
2743 struct rb_io_buffer *buffer = NULL;
2744 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
2745
2746 VALUE source = argv[0];
2747 const void *source_base;
2748 size_t source_size;
2749
2750 rb_io_buffer_get_bytes_for_reading(source, &source_base, &source_size);
2751
2752 VALUE result = io_buffer_copy_from(buffer, source_base, source_size, argc-1, argv+1);
2753 RB_GC_GUARD(source);
2754 return result;
2755}
2756
2757/*
2758 * call-seq: get_string([offset, [length, [encoding]]]) -> string
2759 *
2760 * Read a chunk or all of the buffer into a string, in the specified
2761 * +encoding+. If no encoding is provided +Encoding::BINARY+ is used.
2762 *
2763 * buffer = IO::Buffer.for('test')
2764 * buffer.get_string
2765 * # => "test"
2766 * buffer.get_string(2)
2767 * # => "st"
2768 * buffer.get_string(2, 1)
2769 * # => "s"
2770 */
2771static VALUE
2772io_buffer_get_string(int argc, VALUE *argv, VALUE self)
2773{
2774 rb_check_arity(argc, 0, 3);
2775
2776 size_t offset, length;
2777 struct rb_io_buffer *buffer = io_buffer_extract_offset_length(self, argc, argv, &offset, &length);
2778
2779 rb_encoding *encoding;
2780 if (argc >= 3) {
2781 encoding = rb_find_encoding(argv[2]);
2782 }
2783 else {
2784 encoding = rb_ascii8bit_encoding();
2785 }
2786
2787 const void *base;
2788 size_t size;
2789 io_buffer_get_bytes_for_reading(buffer, &base, &size);
2790
2791 io_buffer_validate_range(buffer, offset, length);
2792
2793 return rb_enc_str_new((const char*)base + offset, length, encoding);
2794}
2795
2796/*
2797 * call-seq: set_string(string, [offset, [length, [source_offset]]]) -> size
2798 *
2799 * Efficiently copy from a source String into the buffer, at +offset+ using
2800 * +memmove+.
2801 *
2802 * buf = IO::Buffer.new(8)
2803 * # =>
2804 * # #<IO::Buffer 0x0000557412714a20+8 INTERNAL>
2805 * # 0x00000000 00 00 00 00 00 00 00 00 ........
2806 *
2807 * # set buffer starting from offset 1, take 2 bytes starting from string's
2808 * # second
2809 * buf.set_string('test', 1, 2, 1)
2810 * # => 2
2811 * buf
2812 * # =>
2813 * # #<IO::Buffer 0x0000557412714a20+8 INTERNAL>
2814 * # 0x00000000 00 65 73 00 00 00 00 00 .es.....
2815 *
2816 * See also #copy for examples of how buffer writing might be used for changing
2817 * associated strings and files.
2818 */
2819static VALUE
2820io_buffer_set_string(int argc, VALUE *argv, VALUE self)
2821{
2822 rb_check_arity(argc, 1, 4);
2823
2824 struct rb_io_buffer *buffer = NULL;
2825 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
2826
2827 VALUE string = rb_str_to_str(argv[0]);
2828
2829 const void *source_base = RSTRING_PTR(string);
2830 size_t source_size = RSTRING_LEN(string);
2831
2832 VALUE result = io_buffer_copy_from(buffer, source_base, source_size, argc-1, argv+1);
2833 RB_GC_GUARD(string);
2834 return result;
2835}
2836
2837void
2838rb_io_buffer_clear(VALUE self, uint8_t value, size_t offset, size_t length)
2839{
2840 struct rb_io_buffer *buffer = NULL;
2841 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
2842
2843 void *base;
2844 size_t size;
2845 io_buffer_get_bytes_for_writing(buffer, &base, &size);
2846
2847 io_buffer_validate_range(buffer, offset, length);
2848
2849 memset((char*)base + offset, value, length);
2850}
2851
2852/*
2853 * call-seq: clear(value = 0, [offset, [length]]) -> self
2854 *
2855 * Fill buffer with +value+, starting with +offset+ and going for +length+
2856 * bytes.
2857 *
2858 * buffer = IO::Buffer.for('test').dup
2859 * # =>
2860 * # <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
2861 * # 0x00000000 74 65 73 74 test
2862 *
2863 * buffer.clear
2864 * # =>
2865 * # <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
2866 * # 0x00000000 00 00 00 00 ....
2867 *
2868 * buf.clear(1) # fill with 1
2869 * # =>
2870 * # <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
2871 * # 0x00000000 01 01 01 01 ....
2872 *
2873 * buffer.clear(2, 1, 2) # fill with 2, starting from offset 1, for 2 bytes
2874 * # =>
2875 * # <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
2876 * # 0x00000000 01 02 02 01 ....
2877 *
2878 * buffer.clear(2, 1) # fill with 2, starting from offset 1
2879 * # =>
2880 * # <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
2881 * # 0x00000000 01 02 02 02 ....
2882 */
2883static VALUE
2884io_buffer_clear(int argc, VALUE *argv, VALUE self)
2885{
2886 rb_check_arity(argc, 0, 3);
2887
2888 uint8_t value = 0;
2889 if (argc >= 1) {
2890 value = NUM2UINT(argv[0]);
2891 }
2892
2893 size_t offset, length;
2894 io_buffer_extract_offset_length(self, argc-1, argv+1, &offset, &length);
2895
2896 rb_io_buffer_clear(self, value, offset, length);
2897
2898 return self;
2899}
2900
2901static size_t
2902io_buffer_default_size(size_t page_size)
2903{
2904 // Platform agnostic default size, based on empirical performance observation:
2905 const size_t platform_agnostic_default_size = 64*1024;
2906
2907 // Allow user to specify custom default buffer size:
2908 const char *default_size = getenv("RUBY_IO_BUFFER_DEFAULT_SIZE");
2909 if (default_size) {
2910 // For the purpose of setting a default size, 2^31 is an acceptable maximum:
2911 int value = atoi(default_size);
2912
2913 // assuming sizeof(int) <= sizeof(size_t)
2914 if (value > 0) {
2915 return value;
2916 }
2917 }
2918
2919 if (platform_agnostic_default_size < page_size) {
2920 return page_size;
2921 }
2922
2923 return platform_agnostic_default_size;
2924}
2925
2927 struct rb_io *io;
2928 struct rb_io_buffer *buffer;
2929 rb_blocking_function_t *function;
2930 void *data;
2931};
2932
2933static VALUE
2934io_buffer_blocking_region_begin(VALUE _argument)
2935{
2936 struct io_buffer_blocking_region_argument *argument = (void*)_argument;
2937
2938 return rb_io_blocking_region(argument->io, argument->function, argument->data);
2939}
2940
2941static VALUE
2942io_buffer_blocking_region_ensure(VALUE _argument)
2943{
2944 struct io_buffer_blocking_region_argument *argument = (void*)_argument;
2945
2946 io_buffer_unlock(argument->buffer);
2947
2948 return Qnil;
2949}
2950
2951static VALUE
2952io_buffer_blocking_region(VALUE io, struct rb_io_buffer *buffer, rb_blocking_function_t *function, void *data)
2953{
2954 struct rb_io *ioptr;
2955 RB_IO_POINTER(io, ioptr);
2956
2957 struct io_buffer_blocking_region_argument argument = {
2958 .io = ioptr,
2959 .buffer = buffer,
2960 .function = function,
2961 .data = data,
2962 };
2963
2964 // If the buffer is already locked, we can skip the ensure (unlock):
2965 if (buffer->flags & RB_IO_BUFFER_LOCKED) {
2966 return io_buffer_blocking_region_begin((VALUE)&argument);
2967 }
2968 else {
2969 // The buffer should be locked for the duration of the blocking region:
2970 io_buffer_lock(buffer);
2971
2972 return rb_ensure(io_buffer_blocking_region_begin, (VALUE)&argument, io_buffer_blocking_region_ensure, (VALUE)&argument);
2973 }
2974}
2975
2977 // The file descriptor to read from:
2978 int descriptor;
2979 // The base pointer to read from:
2980 char *base;
2981 // The size of the buffer:
2982 size_t size;
2983 // The minimum number of bytes to read:
2984 size_t length;
2985};
2986
2987static VALUE
2988io_buffer_read_internal(void *_argument)
2989{
2990 size_t total = 0;
2991 struct io_buffer_read_internal_argument *argument = _argument;
2992
2993 while (true) {
2994 ssize_t result = read(argument->descriptor, argument->base, argument->size);
2995
2996 if (result < 0) {
2997 return rb_fiber_scheduler_io_result(result, errno);
2998 }
2999 else if (result == 0) {
3000 return rb_fiber_scheduler_io_result(total, 0);
3001 }
3002 else {
3003 total += result;
3004
3005 if (total >= argument->length) {
3006 return rb_fiber_scheduler_io_result(total, 0);
3007 }
3008
3009 argument->base = argument->base + result;
3010 argument->size = argument->size - result;
3011 }
3012 }
3013}
3014
3015VALUE
3016rb_io_buffer_read(VALUE self, VALUE io, size_t length, size_t offset)
3017{
3018 io = rb_io_get_io(io);
3019
3020 VALUE scheduler = rb_fiber_scheduler_current();
3021 if (scheduler != Qnil) {
3022 VALUE result = rb_fiber_scheduler_io_read(scheduler, io, self, length, offset);
3023
3024 if (!UNDEF_P(result)) {
3025 return result;
3026 }
3027 }
3028
3029 struct rb_io_buffer *buffer = NULL;
3030 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3031
3032 io_buffer_validate_range(buffer, offset, length);
3033
3034 int descriptor = rb_io_descriptor(io);
3035
3036 void * base;
3037 size_t size;
3038 io_buffer_get_bytes_for_writing(buffer, &base, &size);
3039
3040 base = (unsigned char*)base + offset;
3041 size = size - offset;
3042
3043 struct io_buffer_read_internal_argument argument = {
3044 .descriptor = descriptor,
3045 .base = base,
3046 .size = size,
3047 .length = length,
3048 };
3049
3050 return io_buffer_blocking_region(io, buffer, io_buffer_read_internal, &argument);
3051}
3052
3053/*
3054 * call-seq: read(io, [length, [offset]]) -> read length or -errno
3055 *
3056 * Read at least +length+ bytes from the +io+, into the buffer starting at
3057 * +offset+. If an error occurs, return <tt>-errno</tt>.
3058 *
3059 * If +length+ is not given or +nil+, it defaults to the size of the buffer
3060 * minus the offset, i.e. the entire buffer.
3061 *
3062 * If +length+ is zero, exactly one <tt>read</tt> operation will occur.
3063 *
3064 * If +offset+ is not given, it defaults to zero, i.e. the beginning of the
3065 * buffer.
3066 *
3067 * IO::Buffer.for('test') do |buffer|
3068 * p buffer
3069 * # =>
3070 * # <IO::Buffer 0x00007fca40087c38+4 SLICE>
3071 * # 0x00000000 74 65 73 74 test
3072 * buffer.read(File.open('/dev/urandom', 'rb'), 2)
3073 * p buffer
3074 * # =>
3075 * # <IO::Buffer 0x00007f3bc65f2a58+4 EXTERNAL SLICE>
3076 * # 0x00000000 05 35 73 74 .5st
3077 * end
3078 */
3079static VALUE
3080io_buffer_read(int argc, VALUE *argv, VALUE self)
3081{
3082 rb_check_arity(argc, 1, 3);
3083
3084 VALUE io = argv[0];
3085
3086 size_t length, offset;
3087 io_buffer_extract_length_offset(self, argc-1, argv+1, &length, &offset);
3088
3089 return rb_io_buffer_read(self, io, length, offset);
3090}
3091
3093 // The file descriptor to read from:
3094 int descriptor;
3095 // The base pointer to read from:
3096 char *base;
3097 // The size of the buffer:
3098 size_t size;
3099 // The minimum number of bytes to read:
3100 size_t length;
3101 // The offset to read from:
3102 off_t offset;
3103};
3104
3105static VALUE
3106io_buffer_pread_internal(void *_argument)
3107{
3108 size_t total = 0;
3109 struct io_buffer_pread_internal_argument *argument = _argument;
3110
3111 while (true) {
3112 ssize_t result = pread(argument->descriptor, argument->base, argument->size, argument->offset);
3113
3114 if (result < 0) {
3115 return rb_fiber_scheduler_io_result(result, errno);
3116 }
3117 else if (result == 0) {
3118 return rb_fiber_scheduler_io_result(total, 0);
3119 }
3120 else {
3121 total += result;
3122
3123 if (total >= argument->length) {
3124 return rb_fiber_scheduler_io_result(total, 0);
3125 }
3126
3127 argument->base = argument->base + result;
3128 argument->size = argument->size - result;
3129 argument->offset = argument->offset + result;
3130 }
3131 }
3132}
3133
3134VALUE
3135rb_io_buffer_pread(VALUE self, VALUE io, rb_off_t from, size_t length, size_t offset)
3136{
3137 io = rb_io_get_io(io);
3138
3139 VALUE scheduler = rb_fiber_scheduler_current();
3140 if (scheduler != Qnil) {
3141 VALUE result = rb_fiber_scheduler_io_pread(scheduler, io, from, self, length, offset);
3142
3143 if (!UNDEF_P(result)) {
3144 return result;
3145 }
3146 }
3147
3148 struct rb_io_buffer *buffer = NULL;
3149 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3150
3151 io_buffer_validate_range(buffer, offset, length);
3152
3153 int descriptor = rb_io_descriptor(io);
3154
3155 void * base;
3156 size_t size;
3157 io_buffer_get_bytes_for_writing(buffer, &base, &size);
3158
3159 base = (unsigned char*)base + offset;
3160 size = size - offset;
3161
3162 struct io_buffer_pread_internal_argument argument = {
3163 .descriptor = descriptor,
3164 .base = base,
3165 .size = size,
3166 .length = length,
3167 .offset = from,
3168 };
3169
3170 return io_buffer_blocking_region(io, buffer, io_buffer_pread_internal, &argument);
3171}
3172
3173/*
3174 * call-seq: pread(io, from, [length, [offset]]) -> read length or -errno
3175 *
3176 * Read at least +length+ bytes from the +io+ starting at the specified +from+
3177 * position, into the buffer starting at +offset+. If an error occurs,
3178 * return <tt>-errno</tt>.
3179 *
3180 * If +length+ is not given or +nil+, it defaults to the size of the buffer
3181 * minus the offset, i.e. the entire buffer.
3182 *
3183 * If +length+ is zero, exactly one <tt>pread</tt> operation will occur.
3184 *
3185 * If +offset+ is not given, it defaults to zero, i.e. the beginning of the
3186 * buffer.
3187 *
3188 * IO::Buffer.for('test') do |buffer|
3189 * p buffer
3190 * # =>
3191 * # <IO::Buffer 0x00007fca40087c38+4 SLICE>
3192 * # 0x00000000 74 65 73 74 test
3193 *
3194 * # take 2 bytes from the beginning of urandom,
3195 * # put them in buffer starting from position 2
3196 * buffer.pread(File.open('/dev/urandom', 'rb'), 0, 2, 2)
3197 * p buffer
3198 * # =>
3199 * # <IO::Buffer 0x00007f3bc65f2a58+4 EXTERNAL SLICE>
3200 * # 0x00000000 05 35 73 74 te.5
3201 * end
3202 */
3203static VALUE
3204io_buffer_pread(int argc, VALUE *argv, VALUE self)
3205{
3206 rb_check_arity(argc, 2, 4);
3207
3208 VALUE io = argv[0];
3209 rb_off_t from = NUM2OFFT(argv[1]);
3210
3211 size_t length, offset;
3212 io_buffer_extract_length_offset(self, argc-2, argv+2, &length, &offset);
3213
3214 return rb_io_buffer_pread(self, io, from, length, offset);
3215}
3216
3218 // The file descriptor to write to:
3219 int descriptor;
3220 // The base pointer to write from:
3221 const char *base;
3222 // The size of the buffer:
3223 size_t size;
3224 // The minimum length to write:
3225 size_t length;
3226};
3227
3228static VALUE
3229io_buffer_write_internal(void *_argument)
3230{
3231 size_t total = 0;
3232 struct io_buffer_write_internal_argument *argument = _argument;
3233
3234 while (true) {
3235 ssize_t result = write(argument->descriptor, argument->base, argument->size);
3236
3237 if (result < 0) {
3238 return rb_fiber_scheduler_io_result(result, errno);
3239 }
3240 else if (result == 0) {
3241 return rb_fiber_scheduler_io_result(total, 0);
3242 }
3243 else {
3244 total += result;
3245
3246 if (total >= argument->length) {
3247 return rb_fiber_scheduler_io_result(total, 0);
3248 }
3249
3250 argument->base = argument->base + result;
3251 argument->size = argument->size - result;
3252 }
3253 }
3254}
3255
3256VALUE
3257rb_io_buffer_write(VALUE self, VALUE io, size_t length, size_t offset)
3258{
3260
3261 VALUE scheduler = rb_fiber_scheduler_current();
3262 if (scheduler != Qnil) {
3263 VALUE result = rb_fiber_scheduler_io_write(scheduler, io, self, length, offset);
3264
3265 if (!UNDEF_P(result)) {
3266 return result;
3267 }
3268 }
3269
3270 struct rb_io_buffer *buffer = NULL;
3271 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3272
3273 io_buffer_validate_range(buffer, offset, length);
3274
3275 int descriptor = rb_io_descriptor(io);
3276
3277 const void * base;
3278 size_t size;
3279 io_buffer_get_bytes_for_reading(buffer, &base, &size);
3280
3281 base = (unsigned char*)base + offset;
3282 size = size - offset;
3283
3284 struct io_buffer_write_internal_argument argument = {
3285 .descriptor = descriptor,
3286 .base = base,
3287 .size = size,
3288 .length = length,
3289 };
3290
3291 return io_buffer_blocking_region(io, buffer, io_buffer_write_internal, &argument);
3292}
3293
3294/*
3295 * call-seq: write(io, [length, [offset]]) -> written length or -errno
3296 *
3297 * Write at least +length+ bytes from the buffer starting at +offset+, into the +io+.
3298 * If an error occurs, return <tt>-errno</tt>.
3299 *
3300 * If +length+ is not given or +nil+, it defaults to the size of the buffer
3301 * minus the offset, i.e. the entire buffer.
3302 *
3303 * If +length+ is zero, exactly one <tt>write</tt> operation will occur.
3304 *
3305 * If +offset+ is not given, it defaults to zero, i.e. the beginning of the
3306 * buffer.
3307 *
3308 * out = File.open('output.txt', 'wb')
3309 * IO::Buffer.for('1234567').write(out, 3)
3310 *
3311 * This leads to +123+ being written into <tt>output.txt</tt>
3312 */
3313static VALUE
3314io_buffer_write(int argc, VALUE *argv, VALUE self)
3315{
3316 rb_check_arity(argc, 1, 3);
3317
3318 VALUE io = argv[0];
3319
3320 size_t length, offset;
3321 io_buffer_extract_length_offset(self, argc-1, argv+1, &length, &offset);
3322
3323 return rb_io_buffer_write(self, io, length, offset);
3324}
3325
3327 // The file descriptor to write to:
3328 int descriptor;
3329 // The base pointer to write from:
3330 const char *base;
3331 // The size of the buffer:
3332 size_t size;
3333 // The minimum length to write:
3334 size_t length;
3335 // The offset to write to:
3336 off_t offset;
3337};
3338
3339static VALUE
3340io_buffer_pwrite_internal(void *_argument)
3341{
3342 size_t total = 0;
3343 struct io_buffer_pwrite_internal_argument *argument = _argument;
3344
3345 while (true) {
3346 ssize_t result = pwrite(argument->descriptor, argument->base, argument->size, argument->offset);
3347
3348 if (result < 0) {
3349 return rb_fiber_scheduler_io_result(result, errno);
3350 }
3351 else if (result == 0) {
3352 return rb_fiber_scheduler_io_result(total, 0);
3353 }
3354 else {
3355 total += result;
3356
3357 if (total >= argument->length) {
3358 return rb_fiber_scheduler_io_result(total, 0);
3359 }
3360
3361 argument->base = argument->base + result;
3362 argument->size = argument->size - result;
3363 argument->offset = argument->offset + result;
3364 }
3365 }
3366}
3367
3368VALUE
3369rb_io_buffer_pwrite(VALUE self, VALUE io, rb_off_t from, size_t length, size_t offset)
3370{
3372
3373 VALUE scheduler = rb_fiber_scheduler_current();
3374 if (scheduler != Qnil) {
3375 VALUE result = rb_fiber_scheduler_io_pwrite(scheduler, io, from, self, length, offset);
3376
3377 if (!UNDEF_P(result)) {
3378 return result;
3379 }
3380 }
3381
3382 struct rb_io_buffer *buffer = NULL;
3383 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3384
3385 io_buffer_validate_range(buffer, offset, length);
3386
3387 int descriptor = rb_io_descriptor(io);
3388
3389 const void * base;
3390 size_t size;
3391 io_buffer_get_bytes_for_reading(buffer, &base, &size);
3392
3393 base = (unsigned char*)base + offset;
3394 size = size - offset;
3395
3396 struct io_buffer_pwrite_internal_argument argument = {
3397 .descriptor = descriptor,
3398
3399 // Move the base pointer to the offset:
3400 .base = base,
3401
3402 // And the size to the length of buffer we want to read:
3403 .size = size,
3404
3405 // And the length of the buffer we want to write:
3406 .length = length,
3407
3408 // And the offset in the file we want to write from:
3409 .offset = from,
3410 };
3411
3412 return io_buffer_blocking_region(io, buffer, io_buffer_pwrite_internal, &argument);
3413}
3414
3415/*
3416 * call-seq: pwrite(io, from, [length, [offset]]) -> written length or -errno
3417 *
3418 * Write at least +length+ bytes from the buffer starting at +offset+, into
3419 * the +io+ starting at the specified +from+ position. If an error occurs,
3420 * return <tt>-errno</tt>.
3421 *
3422 * If +length+ is not given or +nil+, it defaults to the size of the buffer
3423 * minus the offset, i.e. the entire buffer.
3424 *
3425 * If +length+ is zero, exactly one <tt>pwrite</tt> operation will occur.
3426 *
3427 * If +offset+ is not given, it defaults to zero, i.e. the beginning of the
3428 * buffer.
3429 *
3430 * If the +from+ position is beyond the end of the file, the gap will be
3431 * filled with null (0 value) bytes.
3432 *
3433 * out = File.open('output.txt', File::RDWR) # open for read/write, no truncation
3434 * IO::Buffer.for('1234567').pwrite(out, 2, 3, 1)
3435 *
3436 * This leads to +234+ (3 bytes, starting from position 1) being written into
3437 * <tt>output.txt</tt>, starting from file position 2.
3438 */
3439static VALUE
3440io_buffer_pwrite(int argc, VALUE *argv, VALUE self)
3441{
3442 rb_check_arity(argc, 2, 4);
3443
3444 VALUE io = argv[0];
3445 rb_off_t from = NUM2OFFT(argv[1]);
3446
3447 size_t length, offset;
3448 io_buffer_extract_length_offset(self, argc-2, argv+2, &length, &offset);
3449
3450 return rb_io_buffer_pwrite(self, io, from, length, offset);
3451}
3452
3453static inline void
3454io_buffer_check_mask_size(size_t size)
3455{
3456 if (size == 0)
3457 rb_raise(rb_eIOBufferMaskError, "Zero-length mask given!");
3458}
3459
3460static void
3461memory_and(unsigned char * restrict output, const unsigned char * restrict base, size_t size, const unsigned char * restrict mask, size_t mask_size)
3462{
3463 for (size_t offset = 0; offset < size; offset += 1) {
3464 output[offset] = base[offset] & mask[offset % mask_size];
3465 }
3466}
3467
3468/*
3469 * call-seq:
3470 * source & mask -> io_buffer
3471 *
3472 * Generate a new buffer the same size as the source by applying the binary AND
3473 * operation to the source, using the mask, repeating as necessary.
3474 *
3475 * IO::Buffer.for("1234567890") & IO::Buffer.for("\xFF\x00\x00\xFF")
3476 * # =>
3477 * # #<IO::Buffer 0x00005589b2758480+4 INTERNAL>
3478 * # 0x00000000 31 00 00 34 35 00 00 38 39 00 1..45..89.
3479 */
3480static VALUE
3481io_buffer_and(VALUE self, VALUE mask)
3482{
3483 struct rb_io_buffer *buffer = NULL;
3484 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3485
3486 struct rb_io_buffer *mask_buffer = NULL;
3487 TypedData_Get_Struct(mask, struct rb_io_buffer, &rb_io_buffer_type, mask_buffer);
3488
3489 const void *base;
3490 size_t size;
3491 io_buffer_get_bytes_for_reading(buffer, &base, &size);
3492
3493 const void *mask_base;
3494 size_t mask_size;
3495 io_buffer_get_bytes_for_reading(mask_buffer, &mask_base, &mask_size);
3496
3497 io_buffer_check_mask_size(mask_size);
3498
3499 VALUE output = rb_io_buffer_new(NULL, size, io_flags_for_size(size));
3500 struct rb_io_buffer *output_buffer = NULL;
3501 TypedData_Get_Struct(output, struct rb_io_buffer, &rb_io_buffer_type, output_buffer);
3502
3503 memory_and(output_buffer->base, base, size, mask_base, mask_size);
3504
3505 return output;
3506}
3507
3508static void
3509memory_or(unsigned char * restrict output, const unsigned char * restrict base, size_t size, const unsigned char * restrict mask, size_t mask_size)
3510{
3511 for (size_t offset = 0; offset < size; offset += 1) {
3512 output[offset] = base[offset] | mask[offset % mask_size];
3513 }
3514}
3515
3516/*
3517 * call-seq:
3518 * source | mask -> io_buffer
3519 *
3520 * Generate a new buffer the same size as the source by applying the binary OR
3521 * operation to the source, using the mask, repeating as necessary.
3522 *
3523 * IO::Buffer.for("1234567890") | IO::Buffer.for("\xFF\x00\x00\xFF")
3524 * # =>
3525 * # #<IO::Buffer 0x0000561785ae3480+10 INTERNAL>
3526 * # 0x00000000 ff 32 33 ff ff 36 37 ff ff 30 .23..67..0
3527 */
3528static VALUE
3529io_buffer_or(VALUE self, VALUE mask)
3530{
3531 struct rb_io_buffer *buffer = NULL;
3532 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3533
3534 struct rb_io_buffer *mask_buffer = NULL;
3535 TypedData_Get_Struct(mask, struct rb_io_buffer, &rb_io_buffer_type, mask_buffer);
3536
3537 const void *base;
3538 size_t size;
3539 io_buffer_get_bytes_for_reading(buffer, &base, &size);
3540
3541 const void *mask_base;
3542 size_t mask_size;
3543 io_buffer_get_bytes_for_reading(mask_buffer, &mask_base, &mask_size);
3544
3545 io_buffer_check_mask_size(mask_size);
3546
3547 VALUE output = rb_io_buffer_new(NULL, size, io_flags_for_size(size));
3548 struct rb_io_buffer *output_buffer = NULL;
3549 TypedData_Get_Struct(output, struct rb_io_buffer, &rb_io_buffer_type, output_buffer);
3550
3551 memory_or(output_buffer->base, base, size, mask_base, mask_size);
3552
3553 return output;
3554}
3555
3556static void
3557memory_xor(unsigned char * restrict output, const unsigned char * restrict base, size_t size, const unsigned char * restrict mask, size_t mask_size)
3558{
3559 for (size_t offset = 0; offset < size; offset += 1) {
3560 output[offset] = base[offset] ^ mask[offset % mask_size];
3561 }
3562}
3563
3564/*
3565 * call-seq:
3566 * source ^ mask -> io_buffer
3567 *
3568 * Generate a new buffer the same size as the source by applying the binary XOR
3569 * operation to the source, using the mask, repeating as necessary.
3570 *
3571 * IO::Buffer.for("1234567890") ^ IO::Buffer.for("\xFF\x00\x00\xFF")
3572 * # =>
3573 * # #<IO::Buffer 0x000055a2d5d10480+10 INTERNAL>
3574 * # 0x00000000 ce 32 33 cb ca 36 37 c7 c6 30 .23..67..0
3575 */
3576static VALUE
3577io_buffer_xor(VALUE self, VALUE mask)
3578{
3579 struct rb_io_buffer *buffer = NULL;
3580 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3581
3582 struct rb_io_buffer *mask_buffer = NULL;
3583 TypedData_Get_Struct(mask, struct rb_io_buffer, &rb_io_buffer_type, mask_buffer);
3584
3585 const void *base;
3586 size_t size;
3587 io_buffer_get_bytes_for_reading(buffer, &base, &size);
3588
3589 const void *mask_base;
3590 size_t mask_size;
3591 io_buffer_get_bytes_for_reading(mask_buffer, &mask_base, &mask_size);
3592
3593 io_buffer_check_mask_size(mask_size);
3594
3595 VALUE output = rb_io_buffer_new(NULL, size, io_flags_for_size(size));
3596 struct rb_io_buffer *output_buffer = NULL;
3597 TypedData_Get_Struct(output, struct rb_io_buffer, &rb_io_buffer_type, output_buffer);
3598
3599 memory_xor(output_buffer->base, base, size, mask_base, mask_size);
3600
3601 return output;
3602}
3603
3604static void
3605memory_not(unsigned char * restrict output, const unsigned char * restrict base, size_t size)
3606{
3607 for (size_t offset = 0; offset < size; offset += 1) {
3608 output[offset] = ~base[offset];
3609 }
3610}
3611
3612/*
3613 * call-seq:
3614 * ~source -> io_buffer
3615 *
3616 * Generate a new buffer the same size as the source by applying the binary NOT
3617 * operation to the source.
3618 *
3619 * ~IO::Buffer.for("1234567890")
3620 * # =>
3621 * # #<IO::Buffer 0x000055a5ac42f120+10 INTERNAL>
3622 * # 0x00000000 ce cd cc cb ca c9 c8 c7 c6 cf ..........
3623 */
3624static VALUE
3625io_buffer_not(VALUE self)
3626{
3627 struct rb_io_buffer *buffer = NULL;
3628 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3629
3630 const void *base;
3631 size_t size;
3632 io_buffer_get_bytes_for_reading(buffer, &base, &size);
3633
3634 VALUE output = rb_io_buffer_new(NULL, size, io_flags_for_size(size));
3635 struct rb_io_buffer *output_buffer = NULL;
3636 TypedData_Get_Struct(output, struct rb_io_buffer, &rb_io_buffer_type, output_buffer);
3637
3638 memory_not(output_buffer->base, base, size);
3639
3640 return output;
3641}
3642
3643static inline int
3644io_buffer_overlaps(const struct rb_io_buffer *a, const struct rb_io_buffer *b)
3645{
3646 if (a->base > b->base) {
3647 return io_buffer_overlaps(b, a);
3648 }
3649
3650 return (b->base >= a->base) && (b->base < (void*)((unsigned char *)a->base + a->size));
3651}
3652
3653static inline void
3654io_buffer_check_overlaps(struct rb_io_buffer *a, struct rb_io_buffer *b)
3655{
3656 if (io_buffer_overlaps(a, b))
3657 rb_raise(rb_eIOBufferMaskError, "Mask overlaps source buffer!");
3658}
3659
3660static void
3661memory_and_inplace(unsigned char * restrict base, size_t size, unsigned char * restrict mask, size_t mask_size)
3662{
3663 for (size_t offset = 0; offset < size; offset += 1) {
3664 base[offset] &= mask[offset % mask_size];
3665 }
3666}
3667
3668/*
3669 * call-seq:
3670 * source.and!(mask) -> io_buffer
3671 *
3672 * Modify the source buffer in place by applying the binary AND
3673 * operation to the source, using the mask, repeating as necessary.
3674 *
3675 * source = IO::Buffer.for("1234567890").dup # Make a read/write copy.
3676 * # =>
3677 * # #<IO::Buffer 0x000056307a0d0c20+10 INTERNAL>
3678 * # 0x00000000 31 32 33 34 35 36 37 38 39 30 1234567890
3679 *
3680 * source.and!(IO::Buffer.for("\xFF\x00\x00\xFF"))
3681 * # =>
3682 * # #<IO::Buffer 0x000056307a0d0c20+10 INTERNAL>
3683 * # 0x00000000 31 00 00 34 35 00 00 38 39 00 1..45..89.
3684 */
3685static VALUE
3686io_buffer_and_inplace(VALUE self, VALUE mask)
3687{
3688 struct rb_io_buffer *buffer = NULL;
3689 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3690
3691 struct rb_io_buffer *mask_buffer = NULL;
3692 TypedData_Get_Struct(mask, struct rb_io_buffer, &rb_io_buffer_type, mask_buffer);
3693
3694 io_buffer_check_mask_size(mask_buffer->size);
3695 io_buffer_check_overlaps(buffer, mask_buffer);
3696
3697 void *base;
3698 size_t size;
3699 io_buffer_get_bytes_for_writing(buffer, &base, &size);
3700
3701 const void *mask_base;
3702 size_t mask_size;
3703 io_buffer_get_bytes_for_reading(mask_buffer, &mask_base, &mask_size);
3704
3705 memory_and_inplace(base, size, mask_buffer->base, mask_buffer->size);
3706
3707 return self;
3708}
3709
3710static void
3711memory_or_inplace(unsigned char * restrict base, size_t size, unsigned char * restrict mask, size_t mask_size)
3712{
3713 for (size_t offset = 0; offset < size; offset += 1) {
3714 base[offset] |= mask[offset % mask_size];
3715 }
3716}
3717
3718/*
3719 * call-seq:
3720 * source.or!(mask) -> io_buffer
3721 *
3722 * Modify the source buffer in place by applying the binary OR
3723 * operation to the source, using the mask, repeating as necessary.
3724 *
3725 * source = IO::Buffer.for("1234567890").dup # Make a read/write copy.
3726 * # =>
3727 * # #<IO::Buffer 0x000056307a272350+10 INTERNAL>
3728 * # 0x00000000 31 32 33 34 35 36 37 38 39 30 1234567890
3729 *
3730 * source.or!(IO::Buffer.for("\xFF\x00\x00\xFF"))
3731 * # =>
3732 * # #<IO::Buffer 0x000056307a272350+10 INTERNAL>
3733 * # 0x00000000 ff 32 33 ff ff 36 37 ff ff 30 .23..67..0
3734 */
3735static VALUE
3736io_buffer_or_inplace(VALUE self, VALUE mask)
3737{
3738 struct rb_io_buffer *buffer = NULL;
3739 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3740
3741 struct rb_io_buffer *mask_buffer = NULL;
3742 TypedData_Get_Struct(mask, struct rb_io_buffer, &rb_io_buffer_type, mask_buffer);
3743
3744 io_buffer_check_mask_size(mask_buffer->size);
3745 io_buffer_check_overlaps(buffer, mask_buffer);
3746
3747 void *base;
3748 size_t size;
3749 io_buffer_get_bytes_for_writing(buffer, &base, &size);
3750
3751 const void *mask_base;
3752 size_t mask_size;
3753 io_buffer_get_bytes_for_reading(mask_buffer, &mask_base, &mask_size);
3754
3755 memory_or_inplace(base, size, mask_buffer->base, mask_buffer->size);
3756
3757 return self;
3758}
3759
3760static void
3761memory_xor_inplace(unsigned char * restrict base, size_t size, unsigned char * restrict mask, size_t mask_size)
3762{
3763 for (size_t offset = 0; offset < size; offset += 1) {
3764 base[offset] ^= mask[offset % mask_size];
3765 }
3766}
3767
3768/*
3769 * call-seq:
3770 * source.xor!(mask) -> io_buffer
3771 *
3772 * Modify the source buffer in place by applying the binary XOR
3773 * operation to the source, using the mask, repeating as necessary.
3774 *
3775 * source = IO::Buffer.for("1234567890").dup # Make a read/write copy.
3776 * # =>
3777 * # #<IO::Buffer 0x000056307a25b3e0+10 INTERNAL>
3778 * # 0x00000000 31 32 33 34 35 36 37 38 39 30 1234567890
3779 *
3780 * source.xor!(IO::Buffer.for("\xFF\x00\x00\xFF"))
3781 * # =>
3782 * # #<IO::Buffer 0x000056307a25b3e0+10 INTERNAL>
3783 * # 0x00000000 ce 32 33 cb ca 36 37 c7 c6 30 .23..67..0
3784 */
3785static VALUE
3786io_buffer_xor_inplace(VALUE self, VALUE mask)
3787{
3788 struct rb_io_buffer *buffer = NULL;
3789 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3790
3791 struct rb_io_buffer *mask_buffer = NULL;
3792 TypedData_Get_Struct(mask, struct rb_io_buffer, &rb_io_buffer_type, mask_buffer);
3793
3794 io_buffer_check_mask_size(mask_buffer->size);
3795 io_buffer_check_overlaps(buffer, mask_buffer);
3796
3797 void *base;
3798 size_t size;
3799 io_buffer_get_bytes_for_writing(buffer, &base, &size);
3800
3801 const void *mask_base;
3802 size_t mask_size;
3803 io_buffer_get_bytes_for_reading(mask_buffer, &mask_base, &mask_size);
3804
3805 memory_xor_inplace(base, size, mask_buffer->base, mask_buffer->size);
3806
3807 return self;
3808}
3809
3810static void
3811memory_not_inplace(unsigned char * restrict base, size_t size)
3812{
3813 for (size_t offset = 0; offset < size; offset += 1) {
3814 base[offset] = ~base[offset];
3815 }
3816}
3817
3818/*
3819 * call-seq:
3820 * source.not! -> io_buffer
3821 *
3822 * Modify the source buffer in place by applying the binary NOT
3823 * operation to the source.
3824 *
3825 * source = IO::Buffer.for("1234567890").dup # Make a read/write copy.
3826 * # =>
3827 * # #<IO::Buffer 0x000056307a33a450+10 INTERNAL>
3828 * # 0x00000000 31 32 33 34 35 36 37 38 39 30 1234567890
3829 *
3830 * source.not!
3831 * # =>
3832 * # #<IO::Buffer 0x000056307a33a450+10 INTERNAL>
3833 * # 0x00000000 ce cd cc cb ca c9 c8 c7 c6 cf ..........
3834 */
3835static VALUE
3836io_buffer_not_inplace(VALUE self)
3837{
3838 struct rb_io_buffer *buffer = NULL;
3839 TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);
3840
3841 void *base;
3842 size_t size;
3843 io_buffer_get_bytes_for_writing(buffer, &base, &size);
3844
3845 memory_not_inplace(base, size);
3846
3847 return self;
3848}
3849
3850/*
3851 * Document-class: IO::Buffer
3852 *
3853 * IO::Buffer is a efficient zero-copy buffer for input/output. There are
3854 * typical use cases:
3855 *
3856 * * Create an empty buffer with ::new, fill it with buffer using #copy or
3857 * #set_value, #set_string, get buffer with #get_string or write it directly
3858 * to some file with #write.
3859 * * Create a buffer mapped to some string with ::for, then it could be used
3860 * both for reading with #get_string or #get_value, and writing (writing will
3861 * change the source string, too).
3862 * * Create a buffer mapped to some file with ::map, then it could be used for
3863 * reading and writing the underlying file.
3864 * * Create a string of a fixed size with ::string, then #read into it, or
3865 * modify it using #set_value.
3866 *
3867 * Interaction with string and file memory is performed by efficient low-level
3868 * C mechanisms like `memcpy`.
3869 *
3870 * The class is meant to be an utility for implementing more high-level mechanisms
3871 * like Fiber::Scheduler#io_read and Fiber::Scheduler#io_write and parsing binary
3872 * protocols.
3873 *
3874 * == Examples of Usage
3875 *
3876 * Empty buffer:
3877 *
3878 * buffer = IO::Buffer.new(8) # create empty 8-byte buffer
3879 * # =>
3880 * # #<IO::Buffer 0x0000555f5d1a5c50+8 INTERNAL>
3881 * # ...
3882 * buffer
3883 * # =>
3884 * # <IO::Buffer 0x0000555f5d156ab0+8 INTERNAL>
3885 * # 0x00000000 00 00 00 00 00 00 00 00
3886 * buffer.set_string('test', 2) # put there bytes of the "test" string, starting from offset 2
3887 * # => 4
3888 * buffer.get_string # get the result
3889 * # => "\x00\x00test\x00\x00"
3890 *
3891 * \Buffer from string:
3892 *
3893 * string = 'data'
3894 * IO::Buffer.for(string) do |buffer|
3895 * buffer
3896 * # =>
3897 * # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
3898 * # 0x00000000 64 61 74 61 data
3899 *
3900 * buffer.get_string(2) # read content starting from offset 2
3901 * # => "ta"
3902 * buffer.set_string('---', 1) # write content, starting from offset 1
3903 * # => 3
3904 * buffer
3905 * # =>
3906 * # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
3907 * # 0x00000000 64 2d 2d 2d d---
3908 * string # original string changed, too
3909 * # => "d---"
3910 * end
3911 *
3912 * \Buffer from file:
3913 *
3914 * File.write('test.txt', 'test data')
3915 * # => 9
3916 * buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY)
3917 * # =>
3918 * # #<IO::Buffer 0x00007f3f0768c000+9 EXTERNAL MAPPED FILE SHARED READONLY>
3919 * # ...
3920 * buffer.get_string(5, 2) # read 2 bytes, starting from offset 5
3921 * # => "da"
3922 * buffer.set_string('---', 1) # attempt to write
3923 * # in `set_string': Buffer is not writable! (IO::Buffer::AccessError)
3924 *
3925 * # To create writable file-mapped buffer
3926 * # Open file for read-write, pass size, offset, and flags=0
3927 * buffer = IO::Buffer.map(File.open('test.txt', 'r+'), 9, 0, 0)
3928 * buffer.set_string('---', 1)
3929 * # => 3 -- bytes written
3930 * File.read('test.txt')
3931 * # => "t--- data"
3932 *
3933 * <b>The class is experimental and the interface is subject to change, this
3934 * is especially true of file mappings which may be removed entirely in
3935 * the future.</b>
3936 */
3937void
3938Init_IO_Buffer(void)
3939{
3940 rb_cIOBuffer = rb_define_class_under(rb_cIO, "Buffer", rb_cObject);
3941
3942 /* Raised when an operation would resize or re-allocate a locked buffer. */
3943 rb_eIOBufferLockedError = rb_define_class_under(rb_cIOBuffer, "LockedError", rb_eRuntimeError);
3944
3945 /* Raised when the buffer cannot be allocated for some reason, or you try to use a buffer that's not allocated. */
3946 rb_eIOBufferAllocationError = rb_define_class_under(rb_cIOBuffer, "AllocationError", rb_eRuntimeError);
3947
3948 /* Raised when you try to write to a read-only buffer, or resize an external buffer. */
3949 rb_eIOBufferAccessError = rb_define_class_under(rb_cIOBuffer, "AccessError", rb_eRuntimeError);
3950
3951 /* Raised if you try to access a buffer slice which no longer references a valid memory range of the underlying source. */
3952 rb_eIOBufferInvalidatedError = rb_define_class_under(rb_cIOBuffer, "InvalidatedError", rb_eRuntimeError);
3953
3954 /* Raised if the mask given to a binary operation is invalid, e.g. zero length or overlaps the target buffer. */
3955 rb_eIOBufferMaskError = rb_define_class_under(rb_cIOBuffer, "MaskError", rb_eArgError);
3956
3957 rb_define_alloc_func(rb_cIOBuffer, rb_io_buffer_type_allocate);
3958 rb_define_singleton_method(rb_cIOBuffer, "for", rb_io_buffer_type_for, 1);
3959 rb_define_singleton_method(rb_cIOBuffer, "string", rb_io_buffer_type_string, 1);
3960
3961#ifdef _WIN32
3962 SYSTEM_INFO info;
3963 GetSystemInfo(&info);
3964 RUBY_IO_BUFFER_PAGE_SIZE = info.dwPageSize;
3965#else /* not WIN32 */
3966 RUBY_IO_BUFFER_PAGE_SIZE = sysconf(_SC_PAGESIZE);
3967#endif
3968
3969 RUBY_IO_BUFFER_DEFAULT_SIZE = io_buffer_default_size(RUBY_IO_BUFFER_PAGE_SIZE);
3970
3971 /* The operating system page size. Used for efficient page-aligned memory allocations. */
3972 rb_define_const(rb_cIOBuffer, "PAGE_SIZE", SIZET2NUM(RUBY_IO_BUFFER_PAGE_SIZE));
3973
3974 /* The default buffer size, typically a (small) multiple of the PAGE_SIZE.
3975 Can be explicitly specified by setting the RUBY_IO_BUFFER_DEFAULT_SIZE
3976 environment variable. */
3977 rb_define_const(rb_cIOBuffer, "DEFAULT_SIZE", SIZET2NUM(RUBY_IO_BUFFER_DEFAULT_SIZE));
3978
3979 rb_define_singleton_method(rb_cIOBuffer, "map", io_buffer_map, -1);
3980
3981 rb_define_method(rb_cIOBuffer, "initialize", rb_io_buffer_initialize, -1);
3982 rb_define_method(rb_cIOBuffer, "initialize_copy", rb_io_buffer_initialize_copy, 1);
3983 rb_define_method(rb_cIOBuffer, "inspect", rb_io_buffer_inspect, 0);
3984 rb_define_method(rb_cIOBuffer, "hexdump", rb_io_buffer_hexdump, -1);
3985 rb_define_method(rb_cIOBuffer, "to_s", rb_io_buffer_to_s, 0);
3986 rb_define_method(rb_cIOBuffer, "size", rb_io_buffer_size, 0);
3987 rb_define_method(rb_cIOBuffer, "valid?", rb_io_buffer_valid_p, 0);
3988
3989 rb_define_method(rb_cIOBuffer, "transfer", rb_io_buffer_transfer, 0);
3990
3991 /* Indicates that the memory in the buffer is owned by someone else. See #external? for more details. */
3992 rb_define_const(rb_cIOBuffer, "EXTERNAL", RB_INT2NUM(RB_IO_BUFFER_EXTERNAL));
3993
3994 /* Indicates that the memory in the buffer is owned by the buffer. See #internal? for more details. */
3995 rb_define_const(rb_cIOBuffer, "INTERNAL", RB_INT2NUM(RB_IO_BUFFER_INTERNAL));
3996
3997 /* Indicates that the memory in the buffer is mapped by the operating system. See #mapped? for more details. */
3998 rb_define_const(rb_cIOBuffer, "MAPPED", RB_INT2NUM(RB_IO_BUFFER_MAPPED));
3999
4000 /* Indicates that the memory in the buffer is also mapped such that it can be shared with other processes. See #shared? for more details. */
4001 rb_define_const(rb_cIOBuffer, "SHARED", RB_INT2NUM(RB_IO_BUFFER_SHARED));
4002
4003 /* Indicates that the memory in the buffer is locked and cannot be resized or freed. See #locked? and #locked for more details. */
4004 rb_define_const(rb_cIOBuffer, "LOCKED", RB_INT2NUM(RB_IO_BUFFER_LOCKED));
4005
4006 /* Indicates that the memory in the buffer is mapped privately and changes won't be replicated to the underlying file. See #private? for more details. */
4007 rb_define_const(rb_cIOBuffer, "PRIVATE", RB_INT2NUM(RB_IO_BUFFER_PRIVATE));
4008
4009 /* Indicates that the memory in the buffer is read only, and attempts to modify it will fail. See #readonly? for more details.*/
4010 rb_define_const(rb_cIOBuffer, "READONLY", RB_INT2NUM(RB_IO_BUFFER_READONLY));
4011
4012 /* Refers to little endian byte order, where the least significant byte is stored first. See #get_value for more details. */
4013 rb_define_const(rb_cIOBuffer, "LITTLE_ENDIAN", RB_INT2NUM(RB_IO_BUFFER_LITTLE_ENDIAN));
4014
4015 /* Refers to big endian byte order, where the most significant byte is stored first. See #get_value for more details. */
4016 rb_define_const(rb_cIOBuffer, "BIG_ENDIAN", RB_INT2NUM(RB_IO_BUFFER_BIG_ENDIAN));
4017
4018 /* Refers to the byte order of the host machine. See #get_value for more details. */
4019 rb_define_const(rb_cIOBuffer, "HOST_ENDIAN", RB_INT2NUM(RB_IO_BUFFER_HOST_ENDIAN));
4020
4021 /* Refers to network byte order, which is the same as big endian. See #get_value for more details. */
4022 rb_define_const(rb_cIOBuffer, "NETWORK_ENDIAN", RB_INT2NUM(RB_IO_BUFFER_NETWORK_ENDIAN));
4023
4024 rb_define_method(rb_cIOBuffer, "null?", rb_io_buffer_null_p, 0);
4025 rb_define_method(rb_cIOBuffer, "empty?", rb_io_buffer_empty_p, 0);
4026 rb_define_method(rb_cIOBuffer, "external?", rb_io_buffer_external_p, 0);
4027 rb_define_method(rb_cIOBuffer, "internal?", rb_io_buffer_internal_p, 0);
4028 rb_define_method(rb_cIOBuffer, "mapped?", rb_io_buffer_mapped_p, 0);
4029 rb_define_method(rb_cIOBuffer, "shared?", rb_io_buffer_shared_p, 0);
4030 rb_define_method(rb_cIOBuffer, "locked?", rb_io_buffer_locked_p, 0);
4031 rb_define_method(rb_cIOBuffer, "private?", rb_io_buffer_private_p, 0);
4032 rb_define_method(rb_cIOBuffer, "readonly?", io_buffer_readonly_p, 0);
4033
4034 // Locking to prevent changes while using pointer:
4035 // rb_define_method(rb_cIOBuffer, "lock", rb_io_buffer_lock, 0);
4036 // rb_define_method(rb_cIOBuffer, "unlock", rb_io_buffer_unlock, 0);
4037 rb_define_method(rb_cIOBuffer, "locked", rb_io_buffer_locked, 0);
4038
4039 // Manipulation:
4040 rb_define_method(rb_cIOBuffer, "slice", io_buffer_slice, -1);
4041 rb_define_method(rb_cIOBuffer, "<=>", rb_io_buffer_compare, 1);
4042 rb_define_method(rb_cIOBuffer, "resize", io_buffer_resize, 1);
4043 rb_define_method(rb_cIOBuffer, "clear", io_buffer_clear, -1);
4044 rb_define_method(rb_cIOBuffer, "free", rb_io_buffer_free, 0);
4045
4046 rb_include_module(rb_cIOBuffer, rb_mComparable);
4047
4048#define IO_BUFFER_DEFINE_DATA_TYPE(name) RB_IO_BUFFER_DATA_TYPE_##name = rb_intern_const(#name)
4049 IO_BUFFER_DEFINE_DATA_TYPE(U8);
4050 IO_BUFFER_DEFINE_DATA_TYPE(S8);
4051
4052 IO_BUFFER_DEFINE_DATA_TYPE(u16);
4053 IO_BUFFER_DEFINE_DATA_TYPE(U16);
4054 IO_BUFFER_DEFINE_DATA_TYPE(s16);
4055 IO_BUFFER_DEFINE_DATA_TYPE(S16);
4056
4057 IO_BUFFER_DEFINE_DATA_TYPE(u32);
4058 IO_BUFFER_DEFINE_DATA_TYPE(U32);
4059 IO_BUFFER_DEFINE_DATA_TYPE(s32);
4060 IO_BUFFER_DEFINE_DATA_TYPE(S32);
4061
4062 IO_BUFFER_DEFINE_DATA_TYPE(u64);
4063 IO_BUFFER_DEFINE_DATA_TYPE(U64);
4064 IO_BUFFER_DEFINE_DATA_TYPE(s64);
4065 IO_BUFFER_DEFINE_DATA_TYPE(S64);
4066
4067 IO_BUFFER_DEFINE_DATA_TYPE(u128);
4068 IO_BUFFER_DEFINE_DATA_TYPE(U128);
4069 IO_BUFFER_DEFINE_DATA_TYPE(s128);
4070 IO_BUFFER_DEFINE_DATA_TYPE(S128);
4071
4072 IO_BUFFER_DEFINE_DATA_TYPE(f32);
4073 IO_BUFFER_DEFINE_DATA_TYPE(F32);
4074 IO_BUFFER_DEFINE_DATA_TYPE(f64);
4075 IO_BUFFER_DEFINE_DATA_TYPE(F64);
4076#undef IO_BUFFER_DEFINE_DATA_TYPE
4077
4078 rb_define_singleton_method(rb_cIOBuffer, "size_of", io_buffer_size_of, 1);
4079
4080 // Data access:
4081 rb_define_method(rb_cIOBuffer, "get_value", io_buffer_get_value, 2);
4082 rb_define_method(rb_cIOBuffer, "get_values", io_buffer_get_values, 2);
4083 rb_define_method(rb_cIOBuffer, "each", io_buffer_each, -1);
4084 rb_define_method(rb_cIOBuffer, "values", io_buffer_values, -1);
4085 rb_define_method(rb_cIOBuffer, "each_byte", io_buffer_each_byte, -1);
4086 rb_define_method(rb_cIOBuffer, "set_value", io_buffer_set_value, 3);
4087 rb_define_method(rb_cIOBuffer, "set_values", io_buffer_set_values, 3);
4088
4089 rb_define_method(rb_cIOBuffer, "copy", io_buffer_copy, -1);
4090
4091 rb_define_method(rb_cIOBuffer, "get_string", io_buffer_get_string, -1);
4092 rb_define_method(rb_cIOBuffer, "set_string", io_buffer_set_string, -1);
4093
4094 // Binary buffer manipulations:
4095 rb_define_method(rb_cIOBuffer, "&", io_buffer_and, 1);
4096 rb_define_method(rb_cIOBuffer, "|", io_buffer_or, 1);
4097 rb_define_method(rb_cIOBuffer, "^", io_buffer_xor, 1);
4098 rb_define_method(rb_cIOBuffer, "~", io_buffer_not, 0);
4099
4100 rb_define_method(rb_cIOBuffer, "and!", io_buffer_and_inplace, 1);
4101 rb_define_method(rb_cIOBuffer, "or!", io_buffer_or_inplace, 1);
4102 rb_define_method(rb_cIOBuffer, "xor!", io_buffer_xor_inplace, 1);
4103 rb_define_method(rb_cIOBuffer, "not!", io_buffer_not_inplace, 0);
4104
4105 // IO operations:
4106 rb_define_method(rb_cIOBuffer, "read", io_buffer_read, -1);
4107 rb_define_method(rb_cIOBuffer, "pread", io_buffer_pread, -1);
4108 rb_define_method(rb_cIOBuffer, "write", io_buffer_write, -1);
4109 rb_define_method(rb_cIOBuffer, "pwrite", io_buffer_pwrite, -1);
4110}
#define rb_define_method(klass, mid, func, arity)
Defines klass#mid.
#define rb_define_singleton_method(klass, mid, func, arity)
Defines klass.mid.
void rb_include_module(VALUE klass, VALUE module)
Includes a module to a class.
Definition class.c:1695
VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
Defines a class under the namespace of outer.
Definition class.c:1519
int rb_block_given_p(void)
Determines if the current method is given a block.
Definition eval.c:1027
#define T_STRING
Old name of RUBY_T_STRING.
Definition value_type.h:78
#define OBJ_FROZEN
Old name of RB_OBJ_FROZEN.
Definition fl_type.h:136
#define rb_str_cat2
Old name of rb_str_cat_cstr.
Definition string.h:1684
#define CLASS_OF
Old name of rb_class_of.
Definition globals.h:205
#define SIZET2NUM
Old name of RB_SIZE2NUM.
Definition size_t.h:62
#define NUM2UINT
Old name of RB_NUM2UINT.
Definition int.h:45
#define NUM2DBL
Old name of rb_num2dbl.
Definition double.h:27
#define Qnil
Old name of RUBY_Qnil.
#define T_ARRAY
Old name of RUBY_T_ARRAY.
Definition value_type.h:56
#define NIL_P
Old name of RB_NIL_P.
#define DBL2NUM
Old name of rb_float_new.
Definition double.h:29
#define NUM2SIZET
Old name of RB_NUM2SIZE.
Definition size_t.h:61
void rb_category_warn(rb_warning_category_t category, const char *fmt,...)
Identical to rb_category_warning(), except it reports unless $VERBOSE is nil.
Definition error.c:476
VALUE rb_eRuntimeError
RuntimeError exception.
Definition error.c:1429
VALUE rb_ensure(VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*e_proc)(VALUE), VALUE data2)
An equivalent to ensure clause.
Definition eval.c:1178
@ RB_WARN_CATEGORY_EXPERIMENTAL
Warning is for experimental features.
Definition error.h:51
VALUE rb_cIO
IO class.
Definition io.c:192
VALUE rb_mComparable
Comparable module.
Definition compar.c:19
#define RB_OBJ_WRITE(old, slot, young)
Declaration of a "back" pointer.
Definition gc.h:603
VALUE rb_ary_new_capa(long capa)
Identical to rb_ary_new(), except it additionally specifies how many rooms of objects it should alloc...
VALUE rb_ary_push(VALUE ary, VALUE elem)
Special case of rb_ary_cat() that it adds only one element.
VALUE rb_ary_entry(VALUE ary, long off)
Queries an element of an array.
#define RETURN_ENUMERATOR_KW(obj, argc, argv, kw_splat)
Identical to RETURN_SIZED_ENUMERATOR_KW(), except its size is unknown.
Definition enumerator.h:260
VALUE rb_str_append(VALUE dst, VALUE src)
Identical to rb_str_buf_append(), except it converts the right hand side before concatenating.
Definition string.c:3833
#define rb_str_new(str, len)
Allocates an instance of rb_cString.
Definition string.h:1499
VALUE rb_str_locktmp(VALUE str)
Obtains a "temporary lock" of the string.
VALUE rb_str_unlocktmp(VALUE str)
Releases a lock formerly obtained by rb_str_locktmp().
Definition string.c:3400
VALUE rb_str_buf_new(long capa)
Allocates a "string buffer".
Definition string.c:1735
#define rb_str_new_cstr(str)
Identical to rb_str_new, except it assumes the passed pointer is a pointer to a C string.
Definition string.h:1515
VALUE rb_class_name(VALUE obj)
Queries the name of the given object's class.
Definition variable.c:500
void rb_define_alloc_func(VALUE klass, rb_alloc_func_t func)
Sets the allocator function of a class.
#define RB_SYM2ID
Just another name of rb_sym2id.
Definition symbol.h:43
VALUE rb_io_get_io(VALUE io)
Identical to rb_io_check_io(), except it raises exceptions on conversion failures.
Definition io.c:870
int rb_io_descriptor(VALUE io)
Returns an integer representing the numeric file descriptor for io.
Definition io.c:2992
#define RB_IO_POINTER(obj, fp)
Queries the underlying IO pointer.
Definition io.h:436
VALUE rb_io_get_write_io(VALUE io)
Queries the tied IO for writing.
Definition io.c:882
void * rb_nogvl(void *(*func)(void *), void *data1, rb_unblock_function_t *ubf, void *data2, int flags)
Identical to rb_thread_call_without_gvl(), except it additionally takes "flags" that change the behav...
Definition thread.c:1594
#define RB_NOGVL_OFFLOAD_SAFE
Passing this flag to rb_nogvl() indicates that the passed function is safe to offload to a background...
Definition thread.h:73
#define RB_NUM2INT
Just another name of rb_num2int_inline.
Definition int.h:38
#define RB_UINT2NUM
Just another name of rb_uint2num_inline.
Definition int.h:39
#define RB_INT2NUM
Just another name of rb_int2num_inline.
Definition int.h:37
#define RB_LL2NUM
Just another name of rb_ll2num_inline.
Definition long_long.h:28
#define RB_ULL2NUM
Just another name of rb_ull2num_inline.
Definition long_long.h:29
#define RB_NUM2ULL
Just another name of rb_num2ull_inline.
Definition long_long.h:33
#define RB_NUM2LL
Just another name of rb_num2ll_inline.
Definition long_long.h:32
VALUE rb_yield_values(int n,...)
Identical to rb_yield(), except it takes variadic number of parameters and pass them to the block.
Definition vm_eval.c:1397
VALUE rb_yield(VALUE val)
Yields the block.
Definition vm_eval.c:1374
#define RB_NUM2LONG
Just another name of rb_num2long_inline.
Definition long.h:57
#define RB_GC_GUARD(v)
Prevents premature destruction of local objects.
Definition memory.h:167
VALUE type(ANYARGS)
ANYARGS-ed function type.
#define NUM2OFFT
Converts an instance of rb_cNumeric into C's off_t.
Definition off_t.h:44
#define RARRAY_LEN
Just another name of rb_array_len.
Definition rarray.h:51
#define RARRAY_AREF(a, i)
Definition rarray.h:403
#define StringValue(v)
Ensures that the parameter object is a String.
Definition rstring.h:66
#define RSTRING_GETMEM(str, ptrvar, lenvar)
Convenient macro to obtain the contents and length at once.
Definition rstring.h:450
VALUE rb_str_to_str(VALUE obj)
Identical to rb_check_string_type(), except it raises exceptions in case of conversion failures.
Definition string.c:1796
#define TypedData_Get_Struct(obj, type, data_type, sval)
Obtains a C struct from inside of a wrapper Ruby object.
Definition rtypeddata.h:649
struct rb_data_type_struct rb_data_type_t
This is the struct that holds necessary info for a struct.
Definition rtypeddata.h:205
#define TypedData_Make_Struct(klass, type, data_type, sval)
Identical to TypedData_Wrap_Struct, except it allocates a new data region internally instead of takin...
Definition rtypeddata.h:508
#define errno
Ractor-aware version of errno.
Definition ruby.h:388
#define RB_NO_KEYWORDS
Do not pass keywords.
Definition scan_args.h:69
Scheduler APIs.
VALUE rb_fiber_scheduler_current(void)
Identical to rb_fiber_scheduler_get(), except it also returns RUBY_Qnil in case of a blocking fiber.
Definition scheduler.c:471
VALUE rb_fiber_scheduler_io_pwrite(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset)
Non-blocking write to the passed IO at the specified offset.
Definition scheduler.c:962
VALUE rb_fiber_scheduler_io_read(VALUE scheduler, VALUE io, VALUE buffer, size_t length, size_t offset)
Non-blocking read from the passed IO.
Definition scheduler.c:830
VALUE rb_fiber_scheduler_io_pread(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset)
Non-blocking read from the passed IO at the specified offset.
Definition scheduler.c:869
VALUE rb_fiber_scheduler_io_write(VALUE scheduler, VALUE io, VALUE buffer, size_t length, size_t offset)
Non-blocking write to the passed IO.
Definition scheduler.c:922
Ruby's IO, metadata and buffers.
Definition io.h:295
uintptr_t ID
Type that represents a Ruby identifier such as a variable name.
Definition value.h:52
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40