Ruby: include/ruby/memory_view.h Source File

Ruby 4.0.5p0 (2026-05-20 revision 64336ffd0ee9e1f4c05891695a3d7b49cb709721)

memory_view.h
Go to the documentation of this file.
1#ifndef RUBY_MEMORY_VIEW_H /*-*-C++-*-vi:se ft=cpp:*/
2#define RUBY_MEMORY_VIEW_H 1
12
13#include "ruby/internal/config.h"
14
15#ifdef STDC_HEADERS
16# include <stddef.h> /* size_t */
17#endif
18
19#ifdef HAVE_SYS_TYPES_H
20# include <sys/types.h> /* ssize_t */
21#endif
22
23#include "ruby/internal/attr/pure.h" /* RBIMPL_ATTR_PURE */
24#include "ruby/internal/core/rtypeddata.h" /* rb_data_type_t */
25#include "ruby/internal/dllexport.h" /* RUBY_EXTERN */
26#include "ruby/internal/stdbool.h" /* bool */
27#include "ruby/internal/value.h" /* VALUE */
28
32 enum ruby_memory_view_flags {
33 RUBY_MEMORY_VIEW_SIMPLE = 0,
34 RUBY_MEMORY_VIEW_WRITABLE = (1<<0),
35 RUBY_MEMORY_VIEW_FORMAT = (1<<1),
36 RUBY_MEMORY_VIEW_MULTI_DIMENSIONAL = (1<<2),
37 RUBY_MEMORY_VIEW_STRIDES = (1<<3) | RUBY_MEMORY_VIEW_MULTI_DIMENSIONAL,
38 RUBY_MEMORY_VIEW_ROW_MAJOR = (1<<4) | RUBY_MEMORY_VIEW_STRIDES,
39 RUBY_MEMORY_VIEW_COLUMN_MAJOR = (1<<5) | RUBY_MEMORY_VIEW_STRIDES,
40 RUBY_MEMORY_VIEW_ANY_CONTIGUOUS = RUBY_MEMORY_VIEW_ROW_MAJOR | RUBY_MEMORY_VIEW_COLUMN_MAJOR,
41 RUBY_MEMORY_VIEW_INDIRECT = (1<<6) | RUBY_MEMORY_VIEW_STRIDES,
42};
43
45 typedef struct {
47 char format;
48
50 bool native_size_p;
51
53 bool little_endian_p;
54
56 size_t offset;
57
59 size_t size;
60
65 size_t repeat;
66} rb_memory_view_item_component_t;
67
77 typedef struct {
81 VALUE obj;
82
84 void *data;
85
87 ssize_t byte_size;
88
90 bool readonly;
91
111 const char *format;
112
116 ssize_t item_size;
117
119 struct {
125 const rb_memory_view_item_component_t *components;
126
128 size_t length;
129 } item_desc;
130
132 ssize_t ndim;
133
137 const ssize_t *shape;
138
142 const ssize_t *strides;
143
147 const ssize_t *sub_offsets;
148
150 void *private_data;
151
153 const struct rb_memory_view_entry *_memory_view_entry;
154} rb_memory_view_t;
155
157 typedef bool (* rb_memory_view_get_func_t)(VALUE obj, rb_memory_view_t *view, int flags);
158
160 typedef bool (* rb_memory_view_release_func_t)(VALUE obj, rb_memory_view_t *view);
161
163 typedef bool (* rb_memory_view_available_p_func_t)(VALUE obj);
164
166 typedef struct rb_memory_view_entry {
170 rb_memory_view_get_func_t get_func;
171
176 rb_memory_view_release_func_t release_func;
177
181 rb_memory_view_available_p_func_t available_p_func;
182} rb_memory_view_entry_t;
183
184 RBIMPL_SYMBOL_EXPORT_BEGIN()
185
186/* memory_view.c */
187
188
192bool rb_memory_view_register(VALUE klass, const rb_memory_view_entry_t *entry);
193
194 RBIMPL_ATTR_PURE()
200bool rb_memory_view_is_row_major_contiguous(const rb_memory_view_t *view);
201
202 RBIMPL_ATTR_PURE()
209bool rb_memory_view_is_column_major_contiguous(const rb_memory_view_t *view);
210
211 RBIMPL_ATTR_NOALIAS()
216void rb_memory_view_fill_contiguous_strides(const ssize_t ndim, const ssize_t item_size, const ssize_t *const shape, const bool row_major_p, ssize_t *const strides);
217
218 RBIMPL_ATTR_NOALIAS()
222bool rb_memory_view_init_as_byte_array(rb_memory_view_t *view, VALUE obj, void *data, const ssize_t len, const bool readonly);
223
228ssize_t rb_memory_view_parse_item_format(const char *format,
229 rb_memory_view_item_component_t **members,
230 size_t *n_members, const char **err);
231
238ssize_t rb_memory_view_item_size_from_format(const char *format, const char **err);
239
247void *rb_memory_view_get_item_pointer(rb_memory_view_t *view, const ssize_t *indices);
248
256 VALUE rb_memory_view_extract_item_members(const void *ptr, const rb_memory_view_item_component_t *members, const size_t n_members);
257
259void rb_memory_view_prepare_item_desc(rb_memory_view_t *view);
260
262 VALUE rb_memory_view_get_item(rb_memory_view_t *view, const ssize_t *indices);
263
271bool rb_memory_view_available_p(VALUE obj);
272
285bool rb_memory_view_get(VALUE obj, rb_memory_view_t* memory_view, int flags);
286
294bool rb_memory_view_release(rb_memory_view_t* memory_view);
295
296/* for testing */
298 RUBY_EXTERN VALUE rb_memory_view_exported_object_registry;
299 RUBY_EXTERN const rb_data_type_t rb_memory_view_exported_object_registry_data_type;
301
302 RBIMPL_SYMBOL_EXPORT_END()
303
304 RBIMPL_ATTR_PURE()
311static inline bool
312rb_memory_view_is_contiguous(const rb_memory_view_t *view)
313{
314 if (rb_memory_view_is_row_major_contiguous(view)) {
315 return true;
316 }
317 else if (rb_memory_view_is_column_major_contiguous(view)) {
318 return true;
319 }
320 else {
321 return false;
322 }
323}
324
325#endif /* RUBY_BUFFER_H */
dllexport.h
Tweaking visibility of C variables/functions.
RUBY_EXTERN
#define RUBY_EXTERN
Declaration of externally visible global variables.
Definition dllexport.h:45
RBIMPL_SYMBOL_EXPORT_END
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition dllexport.h:74
RBIMPL_SYMBOL_EXPORT_BEGIN
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:65
len
int len
Length of the buffer.
Definition io.h:8
ruby_memory_view_flags
ruby_memory_view_flags
Flags passed to rb_memory_view_get(), then to rb_memory_view_get_func_t.
Definition memory_view.h:32
rb_memory_view_get_item_pointer
void * rb_memory_view_get_item_pointer(rb_memory_view_t *view, const ssize_t *indices)
Calculate the location of the item indicated by the given indices.
Definition memory_view.c:513
rb_memory_view_is_row_major_contiguous
bool rb_memory_view_is_row_major_contiguous(const rb_memory_view_t *view)
Return true if the data in the MemoryView view is row-major contiguous.
Definition memory_view.c:149
rb_memory_view_get
bool rb_memory_view_get(VALUE obj, rb_memory_view_t *memory_view, int flags)
If the given obj supports to export a MemoryView that conforms the given flags, this function fills v...
Definition memory_view.c:815
rb_memory_view_extract_item_members
VALUE rb_memory_view_extract_item_members(const void *ptr, const rb_memory_view_item_component_t *members, const size_t n_members)
Return a value that consists of item members.
Definition memory_view.c:727
rb_memory_view_get_func_t
bool(* rb_memory_view_get_func_t)(VALUE obj, rb_memory_view_t *view, int flags)
Type of function of rb_memory_view_entry_t::get_func.
Definition memory_view.h:157
rb_memory_view_item_size_from_format
ssize_t rb_memory_view_item_size_from_format(const char *format, const char **err)
Calculate the number of bytes occupied by an element.
Definition memory_view.c:506
rb_memory_view_release_func_t
bool(* rb_memory_view_release_func_t)(VALUE obj, rb_memory_view_t *view)
Type of function of rb_memory_view_entry_t::release_func.
Definition memory_view.h:160
rb_memory_view_is_contiguous
static bool rb_memory_view_is_contiguous(const rb_memory_view_t *view)
Return true if the data in the MemoryView view is row-major or column-major contiguous.
Definition memory_view.h:312
rb_memory_view_entry_t
struct rb_memory_view_entry rb_memory_view_entry_t
Operations applied to a specific kind of a memory view.
rb_memory_view_release
bool rb_memory_view_release(rb_memory_view_t *memory_view)
Release the given MemoryView view and decrement the reference count of memory_view->obj.
Definition memory_view.c:837
rb_memory_view_fill_contiguous_strides
void rb_memory_view_fill_contiguous_strides(const ssize_t ndim, const ssize_t item_size, const ssize_t *const shape, const bool row_major_p, ssize_t *const strides)
Fill the strides array with byte-Strides of a contiguous array of the given shape with the given elem...
Definition memory_view.c:181
rb_memory_view_available_p
bool rb_memory_view_available_p(VALUE obj)
Return true if obj supports to export a MemoryView.
Definition memory_view.c:803
rb_memory_view_is_column_major_contiguous
bool rb_memory_view_is_column_major_contiguous(const rb_memory_view_t *view)
Return true if the data in the MemoryView view is column-major contiguous.
Definition memory_view.c:165
rb_memory_view_register
bool rb_memory_view_register(VALUE klass, const rb_memory_view_entry_t *entry)
Associates the passed class with the passed memory view entry.
Definition memory_view.c:132
rb_memory_view_available_p_func_t
bool(* rb_memory_view_available_p_func_t)(VALUE obj)
Type of function of rb_memory_view_entry_t::available_p_func.
Definition memory_view.h:163
rb_memory_view_init_as_byte_array
bool rb_memory_view_init_as_byte_array(rb_memory_view_t *view, VALUE obj, void *data, const ssize_t len, const bool readonly)
Fill the members of view as an 1-dimensional byte array.
Definition memory_view.c:200
rb_memory_view_get_item
VALUE rb_memory_view_get_item(rb_memory_view_t *view, const ssize_t *indices)
Definition memory_view.c:767
rb_memory_view_parse_item_format
ssize_t rb_memory_view_parse_item_format(const char *format, rb_memory_view_item_component_t **members, size_t *n_members, const char **err)
Deconstructs the passed format string, as describe in rb_memory_view_t::format.
Definition memory_view.c:389
rb_memory_view_prepare_item_desc
void rb_memory_view_prepare_item_desc(rb_memory_view_t *view)
Fill the item_desc member of view.
Definition memory_view.c:750
RBIMPL_ATTR_NOALIAS
#define RBIMPL_ATTR_NOALIAS()
Wraps (or simulates) __declspec((noalias)).
Definition noalias.h:66
inline
#define inline
Old Visual Studio versions do not support the inline keyword, so we need to define it to be __inline.
Definition defines.h:91
pure.h
Defines RBIMPL_ATTR_PURE.
RBIMPL_ATTR_PURE
#define RBIMPL_ATTR_PURE()
Wraps (or simulates) __attribute__((pure)).
Definition pure.h:33
rtypeddata.h
Defines struct RTypedData.
rb_data_type_t
struct rb_data_type_struct rb_data_type_t
This is the struct that holds necessary info for a struct.
Definition rtypeddata.h:205
stdbool.h
C99 shim for <stdbool.h>.
rb_memory_view_entry
Operations applied to a specific kind of a memory view.
Definition memory_view.h:166
rb_memory_view_entry::get_func
rb_memory_view_get_func_t get_func
Exports a memory view from a Ruby object.
Definition memory_view.h:170
rb_memory_view_entry::available_p_func
rb_memory_view_available_p_func_t available_p_func
Queries if an object understands memory view protocol.
Definition memory_view.h:181
rb_memory_view_entry::release_func
rb_memory_view_release_func_t release_func
Releases a memory view that was previously generated using rb_memory_view_entry_t::get_func.
Definition memory_view.h:176
rb_memory_view_item_component_t
Memory view component metadata.
Definition memory_view.h:45
rb_memory_view_item_component_t::native_size_p
bool native_size_p
:FIXME: what is a "native" size is unclear.
Definition memory_view.h:50
rb_memory_view_item_component_t::size
size_t size
The component's size.
Definition memory_view.h:59
rb_memory_view_item_component_t::format
char format
Definition memory_view.h:47
rb_memory_view_item_component_t::repeat
size_t repeat
How many numbers of components are there.
Definition memory_view.h:65
rb_memory_view_item_component_t::offset
size_t offset
The component's offset.
Definition memory_view.h:56
rb_memory_view_item_component_t::little_endian_p
bool little_endian_p
Endian of the component.
Definition memory_view.h:53
rb_memory_view_t
A MemoryView structure, rb_memory_view_t, is used for exporting objects' MemoryView.
Definition memory_view.h:77
rb_memory_view_t::components
const rb_memory_view_item_component_t * components
The array of rb_memory_view_item_component_t that describes the item structure.
Definition memory_view.h:125
rb_memory_view_t::item_size
ssize_t item_size
The number of bytes in each element.
Definition memory_view.h:116
rb_memory_view_t::strides
const ssize_t * strides
ndim size array indicating the number of bytes to skip to go to the next element in each dimension.
Definition memory_view.h:142
rb_memory_view_t::ndim
ssize_t ndim
The number of dimension.
Definition memory_view.h:132
rb_memory_view_t::_memory_view_entry
const struct rb_memory_view_entry * _memory_view_entry
DO NOT TOUCH THIS: The memory view entry for the internal use.
Definition memory_view.h:153
rb_memory_view_t::data
void * data
The pointer to the exported memory.
Definition memory_view.h:84
rb_memory_view_t::obj
VALUE obj
The original object that has the memory exported via this memory view.
Definition memory_view.h:81
rb_memory_view_t::sub_offsets
const ssize_t * sub_offsets
The offset in each dimension when this memory view exposes a nested array.
Definition memory_view.h:147
rb_memory_view_t::shape
const ssize_t * shape
ndim size array indicating the number of elements in each dimension.
Definition memory_view.h:137
rb_memory_view_t::private_data
void * private_data
The private data for managing this exported memory.
Definition memory_view.h:150
rb_memory_view_t::length
size_t length
The number of components in an item.
Definition memory_view.h:128
rb_memory_view_t::format
const char * format
A string to describe the format of an element, or NULL for unsigned bytes.
Definition memory_view.h:111
rb_memory_view_t::byte_size
ssize_t byte_size
The number of bytes in data.
Definition memory_view.h:87
rb_memory_view_t::readonly
bool readonly
true for readonly memory, false for writable memory.
Definition memory_view.h:90
value.h
Defines VALUE and ID.
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40