Ruby: rb_memory_view_t Struct Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Data Fields
rb_memory_view_t Struct Reference

A MemoryView structure, `rb_memory_view_t`, is used for exporting objects' MemoryView. More...

`#include <memory_view.h>`

## Data Fields
VALUE | obj
| The original object that has the memory exported via this memory view.
void * | data
| The pointer to the exported memory.
ssize_t | byte_size
| The number of bytes in data.
bool | readonly
| true for readonly memory, false for writable memory.
const char * | format
| A string to describe the format of an element, or NULL for unsigned bytes.
ssize_t | item_size
| The number of bytes in each element.
struct { |
const rb_memory_view_item_component_t * components |
| The array of rb_memory_view_item_component_t that describes the item structure. More...
size_t length |
| The number of components in an item. More...
} | item_desc |
| Description of each components.
ssize_t | ndim
| The number of dimension.
const ssize_t * | shape
| ndim size array indicating the number of elements in each dimension.
const ssize_t * | strides
| ndim size array indicating the number of bytes to skip to go to the next element in each dimension.
const ssize_t * | sub_offsets
| The offset in each dimension when this memory view exposes a nested array.
void * | private_data
| The private data for managing this exported memory.
const struct rb_memory_view_entry * | _memory_view_entry
| DO NOT TOUCH THIS: The memory view entry for the internal use.

## Detailed Description

A MemoryView structure, `rb_memory_view_t`, is used for exporting objects' MemoryView.

This structure contains the reference of the object, which is the owner of the MemoryView, the pointer to the head of exported memory, and the metadata that describes the structure of the memory. The metadata can describe multidimensional arrays with strides.

Definition at line 77 of file memory_view.h.

## Field Documentation

## ◆ _memory_view_entry

const struct rb_memory_view_entry* rb_memory_view_t::_memory_view_entry

DO NOT TOUCH THIS: The memory view entry for the internal use.

Definition at line 153 of file memory_view.h.

Referenced by rb_memory_view_get(), and rb_memory_view_release().

## ◆ byte_size

ssize_t rb_memory_view_t::byte_size

The number of bytes in data.

Definition at line 87 of file memory_view.h.

Referenced by rb_memory_view_init_as_byte_array().

## ◆ components

const rb_memory_view_item_component_t* rb_memory_view_t::components

The array of rb_memory_view_item_component_t that describes the item structure.

rb_memory_view_prepare_item_desc and rb_memory_view_get_item allocate this memory if needed, and rb_memory_view_release frees it.

Definition at line 125 of file memory_view.h.

Referenced by rb_memory_view_get_item(), rb_memory_view_init_as_byte_array(), rb_memory_view_prepare_item_desc(), and rb_memory_view_release().

## ◆ data

void* rb_memory_view_t::data

The pointer to the exported memory.

Definition at line 84 of file memory_view.h.

Referenced by rb_memory_view_get_item_pointer(), and rb_memory_view_init_as_byte_array().

## ◆ format

const char* rb_memory_view_t::format

A string to describe the format of an element, or NULL for unsigned bytes.

The format string is a sequence of the following pack-template specifiers:

c, C, s, s!, S, S!, n, v, i, i!, I, I!, l, l!, L, L!, N, V, f, e, g, q, q!, Q, Q!, d, E, G, j, J, x

For example, "dd" for an element that consists of two double values, and "CCC" for an element that consists of three bytes, such as an RGB color triplet.

Also, the value endianness can be explicitly specified by '<' or '>' following a value type specifier.

The items are packed contiguously. When you emulate the alignment of structure members, put '|' at the beginning of the format string, like "|iqc". On x86_64 Linux ABI, the size of the item by this format is 24 bytes instead of 13 bytes.

Definition at line 111 of file memory_view.h.

Referenced by rb_memory_view_get_item(), rb_memory_view_init_as_byte_array(), and rb_memory_view_prepare_item_desc().

## ◆ [struct]

struct { ... } rb_memory_view_t::item_desc

Description of each components.

Referenced by rb_memory_view_get_item(), rb_memory_view_init_as_byte_array(), rb_memory_view_prepare_item_desc(), and rb_memory_view_release().

## ◆ item_size

ssize_t rb_memory_view_t::item_size

The number of bytes in each element.

item_size should equal to rb_memory_view_item_size_from_format(format).

Definition at line 116 of file memory_view.h.

Referenced by rb_memory_view_get_item_pointer(), rb_memory_view_init_as_byte_array(), rb_memory_view_is_column_major_contiguous(), and rb_memory_view_is_row_major_contiguous().

## ◆ length

size_t rb_memory_view_t::length

The number of components in an item.

Definition at line 128 of file memory_view.h.

Referenced by rb_memory_view_get_item(), rb_memory_view_init_as_byte_array(), and rb_memory_view_prepare_item_desc().

## ◆ ndim

ssize_t rb_memory_view_t::ndim

The number of dimension.

Definition at line 132 of file memory_view.h.

Referenced by rb_memory_view_get_item_pointer(), rb_memory_view_init_as_byte_array(), rb_memory_view_is_column_major_contiguous(), and rb_memory_view_is_row_major_contiguous().

## ◆ obj

VALUE rb_memory_view_t::obj

The original object that has the memory exported via this memory view.

Definition at line 81 of file memory_view.h.

Referenced by rb_memory_view_get(), rb_memory_view_init_as_byte_array(), and rb_memory_view_release().

## ◆ private_data

void* rb_memory_view_t::private_data

The private data for managing this exported memory.

Definition at line 150 of file memory_view.h.

Referenced by rb_memory_view_init_as_byte_array().

## ◆ readonly

bool rb_memory_view_t::readonly

true for readonly memory, false for writable memory.

Definition at line 90 of file memory_view.h.

Referenced by rb_memory_view_init_as_byte_array().

## ◆ shape

const ssize_t* rb_memory_view_t::shape

ndim size array indicating the number of elements in each dimension.

This can be NULL when ndim == 1.

Definition at line 137 of file memory_view.h.

Referenced by rb_memory_view_get_item_pointer(), rb_memory_view_init_as_byte_array(), rb_memory_view_is_column_major_contiguous(), and rb_memory_view_is_row_major_contiguous().

## ◆ strides

const ssize_t* rb_memory_view_t::strides

ndim size array indicating the number of bytes to skip to go to the next element in each dimension.

Definition at line 142 of file memory_view.h.

Referenced by rb_memory_view_get_item_pointer(), rb_memory_view_init_as_byte_array(), rb_memory_view_is_column_major_contiguous(), and rb_memory_view_is_row_major_contiguous().

## ◆ sub_offsets

const ssize_t* rb_memory_view_t::sub_offsets

The offset in each dimension when this memory view exposes a nested array.

Or, NULL when this memory view exposes a flat array.

Definition at line 147 of file memory_view.h.

Referenced by rb_memory_view_get_item_pointer(), and rb_memory_view_init_as_byte_array().

The documentation for this struct was generated from the following file:

- include/ruby/memory_view.h