(892c46283a5ea4179500d951c9d4866c0051f27b)

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"

Include dependency graph for memory_view.h:

This graph shows which files directly or indirectly include this file:

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

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

typedef bool(*	rb_memory_view_available_p_func_t) (VALUE obj)
	Type of function of rb_memory_view_entry_t::available_p_func. More...

typedef struct rb_memory_view_entry	rb_memory_view_entry_t
	Operations applied to a specific kind of a memory view. More...

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

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

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

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

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

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

ssize_t	rb_memory_view_item_size_from_format (const char format, const char *err)
	Calculate the number of bytes occupied by an element. More...

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`. More...

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

void	rb_memory_view_prepare_item_desc (rb_memory_view_t *view)
	Fill the `item_desc` member of `view`. More...

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

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`. More...

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`. More...

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

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.

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

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

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

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

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

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

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

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

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

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

(892c46283a5ea4179500d951c9d4866c0051f27b)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ rb_memory_view_available_p_func_t

◆ rb_memory_view_entry_t

◆ rb_memory_view_get_func_t

◆ rb_memory_view_release_func_t

Enumeration Type Documentation

◆ ruby_memory_view_flags

Function Documentation

◆ rb_memory_view_available_p()

◆ rb_memory_view_extract_item_members()

◆ rb_memory_view_fill_contiguous_strides()

◆ rb_memory_view_get()

◆ rb_memory_view_get_item()

◆ rb_memory_view_get_item_pointer()

◆ rb_memory_view_init_as_byte_array()

◆ rb_memory_view_is_column_major_contiguous()

◆ rb_memory_view_is_contiguous()

◆ rb_memory_view_is_row_major_contiguous()

◆ rb_memory_view_item_size_from_format()

◆ rb_memory_view_parse_item_format()

◆ rb_memory_view_prepare_item_desc()

◆ rb_memory_view_register()

◆ rb_memory_view_release()