Ruby: include/ruby/memory_view.h File Reference

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

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()

static 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.

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