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