Ruby: include/ruby/memory_view.h File Reference

Ruby 3.4.5p51 (2025-07-16 revision 20cda200d3ce092571d0b5d342dadca69636cb0f)

Data Structures | Typedefs | Enumerations | Functions
memory_view.h File Reference

Memory View. More...

`#include "ruby/internal/config.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/core/rtypeddata.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/stdbool.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Data Structures
struct | rb_memory_view_item_component_t
| Memory view component metadata. More...
struct | rb_memory_view_t
| A MemoryView structure, rb_memory_view_t, is used for exporting objects' MemoryView. More...
struct | rb_memory_view_entry
| Operations applied to a specific kind of a memory view. More...

## Typedefs
typedef 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.
typedef 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.
typedef bool(* | rb_memory_view_available_p_func_t) (VALUE obj)
| Type of function of rb_memory_view_entry_t::available_p_func.
typedef struct rb_memory_view_entry | rb_memory_view_entry_t
| Operations applied to a specific kind of a memory view.

## Enumerations
enum | ruby_memory_view_flags { RUBY_MEMORY_VIEW_SIMPLE = 0 , RUBY_MEMORY_VIEW_WRITABLE = (1<<0) , RUBY_MEMORY_VIEW_FORMAT = (1<<1) , RUBY_MEMORY_VIEW_MULTI_DIMENSIONAL = (1<<2) , RUBY_MEMORY_VIEW_STRIDES = (1<<3) | RUBY_MEMORY_VIEW_MULTI_DIMENSIONAL , RUBY_MEMORY_VIEW_ROW_MAJOR = (1<<4) | RUBY_MEMORY_VIEW_STRIDES , RUBY_MEMORY_VIEW_COLUMN_MAJOR = (1<<5) | RUBY_MEMORY_VIEW_STRIDES , RUBY_MEMORY_VIEW_ANY_CONTIGUOUS = RUBY_MEMORY_VIEW_ROW_MAJOR | RUBY_MEMORY_VIEW_COLUMN_MAJOR , RUBY_MEMORY_VIEW_INDIRECT = (1<<6) | RUBY_MEMORY_VIEW_STRIDES }
| Flags passed to rb_memory_view_get(), then to rb_memory_view_get_func_t. More...

## Functions
bool | rb_memory_view_register (VALUE klass, const rb_memory_view_entry_t *entry)
| Associates the passed class with the passed memory view entry.
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.
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.
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 element size.
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.
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.
ssize_t | rb_memory_view_item_size_from_format (const char *format, const char **err)
| Calculate the number of bytes occupied by an element.
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.
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.
void | rb_memory_view_prepare_item_desc (rb_memory_view_t *view)
| Fill the item_desc member of view.
VALUE | rb_memory_view_get_item (rb_memory_view_t *view, const ssize_t *indices)
bool | rb_memory_view_available_p (VALUE obj)
| Return true if obj supports to export a MemoryView.
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 view by the information of the MemoryView and returns true.
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.
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.

## Detailed Description

Memory View.

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Definition in file memory_view.h.

## Typedef Documentation

## ◆ rb_memory_view_available_p_func_t

typedef bool(* rb_memory_view_available_p_func_t) (VALUE obj)

Type of function of rb_memory_view_entry_t::available_p_func.

Definition at line 163 of file memory_view.h.

## ◆ rb_memory_view_entry_t

typedef struct rb_memory_view_entry rb_memory_view_entry_t

Operations applied to a specific kind of a memory view.

## ◆ rb_memory_view_get_func_t

typedef 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 at line 157 of file memory_view.h.

## ◆ rb_memory_view_release_func_t

typedef 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 at line 160 of file memory_view.h.

## Enumeration Type Documentation

## ◆ ruby_memory_view_flags

enum ruby_memory_view_flags

Flags passed to rb_memory_view_get(), then to rb_memory_view_get_func_t.

Definition at line 32 of file memory_view.h.

## Function Documentation

## ◆ rb_memory_view_available_p()

bool rb_memory_view_available_p | ( | VALUE | obj | ) |

Return true if obj supports to export a MemoryView.

Return false otherwise.

If this function returns true, it doesn't mean the function rb_memory_view_get will succeed.

Definition at line 803 of file memory_view.c.

Referenced by rb_memory_view_available_p().

## ◆ 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.

When an item is a single member, the return value is a single value.

When an item consists of multiple members, an array will be returned.

Definition at line 727 of file memory_view.c.

Referenced by rb_memory_view_extract_item_members(), and rb_memory_view_get_item().

## ◆ 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 element size.

Definition at line 181 of file memory_view.c.

Referenced by rb_memory_view_fill_contiguous_strides().

## ◆ 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 view by the information of the MemoryView and returns true.

In this case, the reference count of obj is increased.

If the given combination of obj and flags cannot export a MemoryView, this function returns false. The content of view is not touched in this case.

The exported MemoryView must be released by rb_memory_view_release when the MemoryView is no longer needed.

Definition at line 815 of file memory_view.c.

Referenced by rb_memory_view_get().

## ◆ rb_memory_view_get_item()

VALUE rb_memory_view_get_item | ( | rb_memory_view_t * | view,
|  | const ssize_t * | indices )

- Return a value that consists of item members in the given memory view.

Definition at line 767 of file memory_view.c.

Referenced by rb_memory_view_get_item().

## ◆ 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.

The length of indices must equal to view->ndim.

This function initializes view->item_desc if needed.

Definition at line 513 of file memory_view.c.

Referenced by rb_memory_view_get_item(), and rb_memory_view_get_item_pointer().

## ◆ 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 at line 200 of file memory_view.c.

Referenced by rb_memory_view_init_as_byte_array().

## ◆ 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.

Return false otherwise.

Definition at line 165 of file memory_view.c.

Referenced by rb_memory_view_is_column_major_contiguous(), and rb_memory_view_is_contiguous().

## ◆ rb_memory_view_is_contiguous()

bool rb_memory_view_is_contiguous | ( | const rb_memory_view_t * | view | ) |
| inlinestatic

Return true if the data in the MemoryView view is row-major or column-major contiguous.

Return false otherwise.

Definition at line 312 of file memory_view.h.

Referenced by rb_memory_view_is_contiguous().

## ◆ 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.

Return false otherwise.

Definition at line 149 of file memory_view.c.

Referenced by rb_memory_view_is_contiguous(), and rb_memory_view_is_row_major_contiguous().

## ◆ 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.

When the calculation fails, the failed location in format is stored into err, and returns -1.

Definition at line 506 of file memory_view.c.

Referenced by rb_memory_view_item_size_from_format().

## ◆ 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 at line 389 of file memory_view.c.

Referenced by rb_memory_view_item_size_from_format(), rb_memory_view_parse_item_format(), and rb_memory_view_prepare_item_desc().

## ◆ 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 at line 750 of file memory_view.c.

Referenced by rb_memory_view_get_item(), and rb_memory_view_prepare_item_desc().

## ◆ 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.

This has to be called before actually creating a memory view from an instance.

Definition at line 132 of file memory_view.c.

Referenced by rb_memory_view_register().

## ◆ 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.

Consumers must call this function when the MemoryView is no longer needed. Missing to call this function leads memory leak.

Definition at line 837 of file memory_view.c.

Referenced by rb_memory_view_release().