Ruby: include/ruby/memory_view.h Source File

Ruby 3.0.5p211 (2022-11-24 revision ba5cf0f7c52d4d35cc6a173c89eda98ceffa2dcf)

memory_view.h
Go to the documentation of this file.
1#ifndef RUBY_MEMORY_VIEW_H
2#define RUBY_MEMORY_VIEW_H 1
13#include "ruby/internal/dllexport.h"
14#include "ruby/internal/stdbool.h"
15#include "ruby/internal/value.h"
16#include "ruby/intern.h"
17
18 enum ruby_memory_view_flags {
19 RUBY_MEMORY_VIEW_SIMPLE = 0,
20 RUBY_MEMORY_VIEW_WRITABLE = (1<<0),
21 RUBY_MEMORY_VIEW_FORMAT = (1<<1),
22 RUBY_MEMORY_VIEW_MULTI_DIMENSIONAL = (1<<2),
23 RUBY_MEMORY_VIEW_STRIDES = (1<<3) | RUBY_MEMORY_VIEW_MULTI_DIMENSIONAL,
24 RUBY_MEMORY_VIEW_ROW_MAJOR = (1<<4) | RUBY_MEMORY_VIEW_STRIDES,
25 RUBY_MEMORY_VIEW_COLUMN_MAJOR = (1<<5) | RUBY_MEMORY_VIEW_STRIDES,
26 RUBY_MEMORY_VIEW_ANY_CONTIGUOUS = RUBY_MEMORY_VIEW_ROW_MAJOR | RUBY_MEMORY_VIEW_COLUMN_MAJOR,
27 RUBY_MEMORY_VIEW_INDIRECT = (1<<6) | RUBY_MEMORY_VIEW_STRIDES,
28};
29
30 typedef struct {
31 char format;
32 unsigned native_size_p: 1;
33 unsigned little_endian_p: 1;
34 size_t offset;
35 size_t size;
36 size_t repeat;
37} rb_memory_view_item_component_t;
38
39 typedef struct {
40 /* The original object that has the memory exported via this memory view.
41 * The consumer of this memory view has the responsibility to call rb_gc_mark
42 * for preventing this obj collected by GC. */
43 VALUE obj;
44
45 /* The pointer to the exported memory. */
46 void *data;
47
48 /* The number of bytes in data. */
49 ssize_t byte_size;
50
51 /* true for readonly memory, false for writable memory. */
52 bool readonly;
53
54 /* A string to describe the format of an element, or NULL for unsigned bytes.
55 * The format string is a sequence of the following pack-template specifiers:
56 *
57 * c, C, s, s!, S, S!, n, v, i, i!, I, I!, l, l!, L, L!,
58 * N, V, f, e, g, q, q!, Q, Q!, d, E, G, j, J, x
59 *
60 * For example, "dd" for an element that consists of two double values,
61 * and "CCC" for an element that consists of three bytes, such as
62 * an RGB color triplet.
63 *
64 * Also, the value endianness can be explicitly specified by '<' or '>'
65 * following a value type specifier.
66 *
67 * The items are packed contiguously. When you emulate the alignment of
68 * structure members, put '|' at the beginning of the format string,
69 * like "|iqc". On x86_64 Linux ABI, the size of the item by this format
70 * is 24 bytes instead of 13 bytes.
71 */
72 const char *format;
73
74 /* The number of bytes in each element.
75 * item_size should equal to rb_memory_view_item_size_from_format(format). */
76 ssize_t item_size;
77
78 struct {
79 /* The array of rb_memory_view_item_component_t that describes the
80 * item structure. rb_memory_view_prepare_item_desc and
81 * rb_memory_view_get_item allocate this memory if needed,
82 * and rb_memory_view_release frees it. */
83 const rb_memory_view_item_component_t *components;
84
85 /* The number of components in an item. */
86 size_t length;
87 } item_desc;
88
89 /* The number of dimension. */
90 ssize_t ndim;
91
92 /* ndim size array indicating the number of elements in each dimension.
93 * This can be NULL when ndim == 1. */
94 const ssize_t *shape;
95
96 /* ndim size array indicating the number of bytes to skip to go to the
97 * next element in each dimension. */
98 const ssize_t *strides;
99
100 /* The offset in each dimension when this memory view exposes a nested array.
101 * Or, NULL when this memory view exposes a flat array. */
102 const ssize_t *sub_offsets;
103
104 /* the private data for managing this exported memory */
105 void *const private;
106} rb_memory_view_t;
107
108 typedef bool (* rb_memory_view_get_func_t)(VALUE obj, rb_memory_view_t *view, int flags);
109 typedef bool (* rb_memory_view_release_func_t)(VALUE obj, rb_memory_view_t *view);
110 typedef bool (* rb_memory_view_available_p_func_t)(VALUE obj);
111
112 typedef struct {
113 rb_memory_view_get_func_t get_func;
114 rb_memory_view_release_func_t release_func;
115 rb_memory_view_available_p_func_t available_p_func;
116} rb_memory_view_entry_t;
117
118 RBIMPL_SYMBOL_EXPORT_BEGIN()
119
120/* memory_view.c */
121bool rb_memory_view_register(VALUE klass, const rb_memory_view_entry_t *entry);
122
123 RBIMPL_ATTR_PURE()
124bool rb_memory_view_is_row_major_contiguous(const rb_memory_view_t *view);
125 RBIMPL_ATTR_PURE()
126bool rb_memory_view_is_column_major_contiguous(const rb_memory_view_t *view);
127 RBIMPL_ATTR_NOALIAS()
128void 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);
129 RBIMPL_ATTR_NOALIAS()
130bool rb_memory_view_init_as_byte_array(rb_memory_view_t *view, VALUE obj, void *data, const ssize_t len, const bool readonly);
131ssize_t rb_memory_view_parse_item_format(const char *format,
132 rb_memory_view_item_component_t **members,
133 size_t *n_members, const char **err);
134ssize_t rb_memory_view_item_size_from_format(const char *format, const char **err);
135void *rb_memory_view_get_item_pointer(rb_memory_view_t *view, const ssize_t *indices);
136 VALUE rb_memory_view_extract_item_members(const void *ptr, const rb_memory_view_item_component_t *members, const size_t n_members);
137void rb_memory_view_prepare_item_desc(rb_memory_view_t *view);
138 VALUE rb_memory_view_get_item(rb_memory_view_t *view, const ssize_t *indices);
139
140bool rb_memory_view_available_p(VALUE obj);
141bool rb_memory_view_get(VALUE obj, rb_memory_view_t* memory_view, int flags);
142bool rb_memory_view_release(rb_memory_view_t* memory_view);
143
144/* for testing */
145 RUBY_EXTERN VALUE rb_memory_view_exported_object_registry;
146 RUBY_EXTERN const rb_data_type_t rb_memory_view_exported_object_registry_data_type;
147
148 RBIMPL_SYMBOL_EXPORT_END()
149
150 RBIMPL_ATTR_PURE()
151static inline bool
152rb_memory_view_is_contiguous(const rb_memory_view_t *view)
153{
154 if (rb_memory_view_is_row_major_contiguous(view)) {
155 return true;
156 }
157 else if (rb_memory_view_is_column_major_contiguous(view)) {
158 return true;
159 }
160 else {
161 return false;
162 }
163}
164
165#endif /* RUBY_BUFFER_H */
ptr
struct RIMemo * ptr
Definition: debug.c:88
dllexport.h
Tewaking visibility of C variables/functions.
RUBY_EXTERN
#define RUBY_EXTERN
Definition: dllexport.h:36
RBIMPL_SYMBOL_EXPORT_END
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition: dllexport.h:86
RBIMPL_SYMBOL_EXPORT_BEGIN
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition: dllexport.h:77
len
uint8_t len
Definition: escape.c:17
intern.h
ruby_memory_view_flags
ruby_memory_view_flags
Definition: memory_view.h:18
RUBY_MEMORY_VIEW_MULTI_DIMENSIONAL
@ RUBY_MEMORY_VIEW_MULTI_DIMENSIONAL
Definition: memory_view.h:22
RUBY_MEMORY_VIEW_SIMPLE
@ RUBY_MEMORY_VIEW_SIMPLE
Definition: memory_view.h:19
RUBY_MEMORY_VIEW_FORMAT
@ RUBY_MEMORY_VIEW_FORMAT
Definition: memory_view.h:21
RUBY_MEMORY_VIEW_WRITABLE
@ RUBY_MEMORY_VIEW_WRITABLE
Definition: memory_view.h:20
RUBY_MEMORY_VIEW_STRIDES
@ RUBY_MEMORY_VIEW_STRIDES
Definition: memory_view.h:23
RUBY_MEMORY_VIEW_INDIRECT
@ RUBY_MEMORY_VIEW_INDIRECT
Definition: memory_view.h:27
RUBY_MEMORY_VIEW_COLUMN_MAJOR
@ RUBY_MEMORY_VIEW_COLUMN_MAJOR
Definition: memory_view.h:25
RUBY_MEMORY_VIEW_ANY_CONTIGUOUS
@ RUBY_MEMORY_VIEW_ANY_CONTIGUOUS
Definition: memory_view.h:26
RUBY_MEMORY_VIEW_ROW_MAJOR
@ RUBY_MEMORY_VIEW_ROW_MAJOR
Definition: memory_view.h:24
rb_memory_view_get_item_pointer
void * rb_memory_view_get_item_pointer(rb_memory_view_t *view, const ssize_t *indices)
Definition: memory_view.c:510
rb_memory_view_is_row_major_contiguous
bool rb_memory_view_is_row_major_contiguous(const rb_memory_view_t *view)
Definition: memory_view.c:147
rb_memory_view_get
bool rb_memory_view_get(VALUE obj, rb_memory_view_t *memory_view, int flags)
Definition: memory_view.c:812
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)
Definition: memory_view.c:724
rb_memory_view_get_func_t
bool(* rb_memory_view_get_func_t)(VALUE obj, rb_memory_view_t *view, int flags)
Definition: memory_view.h:108
rb_memory_view_item_size_from_format
ssize_t rb_memory_view_item_size_from_format(const char *format, const char **err)
Definition: memory_view.c:503
rb_memory_view_release_func_t
bool(* rb_memory_view_release_func_t)(VALUE obj, rb_memory_view_t *view)
Definition: memory_view.h:109
rb_memory_view_release
bool rb_memory_view_release(rb_memory_view_t *memory_view)
Definition: memory_view.c:833
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)
Definition: memory_view.c:179
rb_memory_view_available_p
bool rb_memory_view_available_p(VALUE obj)
Definition: memory_view.c:800
rb_memory_view_is_column_major_contiguous
bool rb_memory_view_is_column_major_contiguous(const rb_memory_view_t *view)
Definition: memory_view.c:163
rb_memory_view_exported_object_registry
VALUE rb_memory_view_exported_object_registry
Definition: memory_view.c:35
rb_memory_view_register
bool rb_memory_view_register(VALUE klass, const rb_memory_view_entry_t *entry)
Definition: memory_view.c:131
rb_memory_view_available_p_func_t
bool(* rb_memory_view_available_p_func_t)(VALUE obj)
Definition: memory_view.h:110
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)
Definition: memory_view.c:198
rb_memory_view_get_item
VALUE rb_memory_view_get_item(rb_memory_view_t *view, const ssize_t *indices)
Definition: memory_view.c:764
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)
Definition: memory_view.c:386
rb_memory_view_prepare_item_desc
void rb_memory_view_prepare_item_desc(rb_memory_view_t *view)
Definition: memory_view.c:747
rb_memory_view_exported_object_registry_data_type
const rb_data_type_t rb_memory_view_exported_object_registry_data_type
Definition: memory_view.c:61
RBIMPL_ATTR_NOALIAS
#define RBIMPL_ATTR_NOALIAS()
Wraps (or simulates) __declspec((noalias))
Definition: noalias.h:55
RBIMPL_ATTR_PURE
#define RBIMPL_ATTR_PURE()
Wraps (or simulates) __attribute__((pure))
Definition: pure.h:33
stdbool.h
C99 shim for <stdbool.h>
const
#define const
Definition: strftime.c:108
rb_data_type_struct
Definition: rtypeddata.h:70
rb_memory_view_entry_t
Definition: memory_view.h:112
rb_memory_view_entry_t::release_func
rb_memory_view_release_func_t release_func
Definition: memory_view.h:114
rb_memory_view_entry_t::available_p_func
rb_memory_view_available_p_func_t available_p_func
Definition: memory_view.h:115
rb_memory_view_entry_t::get_func
rb_memory_view_get_func_t get_func
Definition: memory_view.h:113
rb_memory_view_item_component_t
Definition: memory_view.h:30
rb_memory_view_item_component_t::native_size_p
unsigned native_size_p
Definition: memory_view.h:32
rb_memory_view_item_component_t::little_endian_p
unsigned little_endian_p
Definition: memory_view.h:33
rb_memory_view_item_component_t::size
size_t size
Definition: memory_view.h:35
rb_memory_view_item_component_t::format
char format
Definition: memory_view.h:31
rb_memory_view_item_component_t::repeat
size_t repeat
Definition: memory_view.h:36
rb_memory_view_item_component_t::offset
size_t offset
Definition: memory_view.h:34
rb_memory_view_t
Definition: memory_view.h:39
rb_memory_view_t::components
const rb_memory_view_item_component_t * components
Definition: memory_view.h:83
rb_memory_view_t::item_size
ssize_t item_size
Definition: memory_view.h:76
rb_memory_view_t::strides
const ssize_t * strides
Definition: memory_view.h:98
rb_memory_view_t::ndim
ssize_t ndim
Definition: memory_view.h:90
rb_memory_view_t::data
void * data
Definition: memory_view.h:46
rb_memory_view_t::obj
VALUE obj
Definition: memory_view.h:43
rb_memory_view_t::sub_offsets
const ssize_t * sub_offsets
Definition: memory_view.h:102
rb_memory_view_t::shape
const ssize_t * shape
Definition: memory_view.h:94
rb_memory_view_t::length
size_t length
Definition: memory_view.h:86
rb_memory_view_t::format
const char * format
Definition: memory_view.h:72
rb_memory_view_t::byte_size
ssize_t byte_size
Definition: memory_view.h:49
rb_memory_view_t::readonly
bool readonly
Definition: memory_view.h:52
value.h
Defines VALUE and ID.
VALUE
unsigned long VALUE
Definition: value.h:38
err
int err
Definition: win32.c:142