Ruby  3.4.0dev (2024-11-05 revision e440268d51fe02b303e3817a7a733a0dac1c5091)
buffer.h
Go to the documentation of this file.
1 #ifndef RUBY_IO_BUFFER_H
2 #define RUBY_IO_BUFFER_H
14 #pragma once
15 
16 #include "ruby/ruby.h"
17 #include "ruby/internal/config.h"
18 
20 
21 // WARNING: This entire interface is experimental and may change in the future!
22 #define RB_IO_BUFFER_EXPERIMENTAL 1
23 
24 #define RUBY_IO_BUFFER_VERSION 2
25 
26 // The `IO::Buffer` class.
27 RUBY_EXTERN VALUE rb_cIOBuffer;
28 
29 // The operating system page size.
30 RUBY_EXTERN size_t RUBY_IO_BUFFER_PAGE_SIZE;
31 
32 // The default buffer size, usually a (small) multiple of the page size.
33 // Can be overridden by the RUBY_IO_BUFFER_DEFAULT_SIZE environment variable.
34 RUBY_EXTERN size_t RUBY_IO_BUFFER_DEFAULT_SIZE;
35 
36 // Represents the internal state of the buffer.
37 // More than one flag can be set at a time.
38 enum rb_io_buffer_flags {
39  // The memory in the buffer is owned by someone else.
40  // More specifically, it means that someone else owns the buffer and we shouldn't try to resize it.
41  RB_IO_BUFFER_EXTERNAL = 1,
42  // The memory in the buffer is allocated internally.
43  RB_IO_BUFFER_INTERNAL = 2,
44  // The memory in the buffer is mapped.
45  // A non-private mapping is marked as external.
46  RB_IO_BUFFER_MAPPED = 4,
47 
48  // A mapped buffer that is also shared.
49  RB_IO_BUFFER_SHARED = 8,
50 
51  // The buffer is locked and cannot be resized.
52  // More specifically, it means we can't change the base address or size.
53  // A buffer is typically locked before a system call that uses the data.
54  RB_IO_BUFFER_LOCKED = 32,
55 
56  // The buffer mapping is private and will not impact other processes or the underlying file.
57  RB_IO_BUFFER_PRIVATE = 64,
58 
59  // The buffer is read-only and cannot be modified.
60  RB_IO_BUFFER_READONLY = 128,
61 
62  // The buffer is backed by a file.
63  RB_IO_BUFFER_FILE = 256,
64 };
65 
66 // Represents the endian of the data types.
67 enum rb_io_buffer_endian {
68  // The least significant units are put first.
69  RB_IO_BUFFER_LITTLE_ENDIAN = 4,
70  RB_IO_BUFFER_BIG_ENDIAN = 8,
71 
72 #if defined(WORDS_BIGENDIAN)
73  RB_IO_BUFFER_HOST_ENDIAN = RB_IO_BUFFER_BIG_ENDIAN,
74 #else
75  RB_IO_BUFFER_HOST_ENDIAN = RB_IO_BUFFER_LITTLE_ENDIAN,
76 #endif
77 
78  RB_IO_BUFFER_NETWORK_ENDIAN = RB_IO_BUFFER_BIG_ENDIAN
79 };
80 
81 VALUE rb_io_buffer_new(void *base, size_t size, enum rb_io_buffer_flags flags);
82 VALUE rb_io_buffer_map(VALUE io, size_t size, rb_off_t offset, enum rb_io_buffer_flags flags);
83 
84 VALUE rb_io_buffer_lock(VALUE self);
85 VALUE rb_io_buffer_unlock(VALUE self);
86 int rb_io_buffer_try_unlock(VALUE self);
87 
88 VALUE rb_io_buffer_free(VALUE self);
89 VALUE rb_io_buffer_free_locked(VALUE self);
90 
91 // Access the internal buffer and flags. Validates the pointers.
92 // The points may not remain valid if the source buffer is manipulated.
93 // Consider using rb_io_buffer_lock if needed.
94 enum rb_io_buffer_flags rb_io_buffer_get_bytes(VALUE self, void **base, size_t *size);
95 void rb_io_buffer_get_bytes_for_reading(VALUE self, const void **base, size_t *size);
96 void rb_io_buffer_get_bytes_for_writing(VALUE self, void **base, size_t *size);
97 
98 VALUE rb_io_buffer_transfer(VALUE self);
99 void rb_io_buffer_resize(VALUE self, size_t size);
100 void rb_io_buffer_clear(VALUE self, uint8_t value, size_t offset, size_t length);
101 
102 // The length is the minimum required length.
103 VALUE rb_io_buffer_read(VALUE self, VALUE io, size_t length, size_t offset);
104 VALUE rb_io_buffer_pread(VALUE self, VALUE io, rb_off_t from, size_t length, size_t offset);
105 VALUE rb_io_buffer_write(VALUE self, VALUE io, size_t length, size_t offset);
106 VALUE rb_io_buffer_pwrite(VALUE self, VALUE io, rb_off_t from, size_t length, size_t offset);
107 
109 
110 #endif /* RUBY_IO_BUFFER_H */
#define RUBY_EXTERN
Declaration of externally visible global variables.
Definition: dllexport.h:45
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition: dllexport.h:74
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition: dllexport.h:65
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40