ruby/doc/memory_view.md

MemoryView

MemoryView provides the features to share multidimensional homogeneous arrays of fixed-size element on memory among extension libraries.

Disclaimer

• This feature is still experimental. The specification described here can be changed in the future.

• This document is under construction. Please refer the master branch of ruby for the latest version of this document.

Overview

We sometimes deal with certain kinds of objects that have arrays of the same typed fixed-size elements on a contiguous memory area as its internal representation. Numo::NArray in numo-narray and Magick::Image in rmagick are typical examples of such objects. MemoryView plays the role of the hub to share the internal data of such objects without copy among such libraries.

Copy-less sharing of data is very important in some field such as data analysis, machine learning, and image processing. In these field, people need to handle large amount of on-memory data with several libraries. If we are forced to copy to exchange large data among libraries, a large amount of the data processing time must be occupied by copying data. You can avoid such wasting time by using MemoryView.

MemoryView has two categories of APIs:

1. Producer API

   Classes can register own MemoryView entry which allows objects of that classes to expose their MemoryView

2. Consumer API

   Consumer API allows us to obtain and manage the MemoryView of an object

MemoryView structure

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.

The member of MemoryView structure

The MemoryView structure consists of the following members.

• VALUE obj

  The reference to the original object that has the memory exported via the MemoryView.

  RubyVM manages the reference count of the MemoryView-exported objects to guard them from the garbage collection. The consumers do not have to struggle to guard this object from GC.

• void *data

  The pointer to the head of the exported memory.

• ssize_t byte_size

  The numbero f bytes in the memory pointed by data.

• bool readonly

  true for readonly memory, false for writable memory.

• const char *format

  A string to describeth e format of an element, or NULL for unsigned byte.

• ssize_t item_size

  The number of bytes in each element.

• const rb_memory_view_item_component_t *item_desc.components

  The array of the metadata of the component in an element.

• size_t item_desc.length

  The number of items in item_desc.components.

• ssize_t ndim

  The number of dimensions.

• const ssize_t *shape

  A ndim size array indicating the number of elements in each dimension. This can be NULL when ndim is 1.

• const ssize_t *strides

  A ndim size array indicating the number of bytes to skip to go to the next element in each dimension. This can be NULL when ndim is 1.

• const ssize_t *sub_offsets

  A ndim size array consisting of the offsets in each dimension when the MemoryView exposes a nested array. This can be NULL when the MemoryView exposes a flat array.

• void *private_data

  The private data that MemoryView provider uses internally. This can be NULL when any private data is unnecessary.

MemoryView APIs

For consumers

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

• bool rb_memory_view_get(VALUE obj, rb_memory_view_t *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.

• bool rb_memory_view_release(rb_memory_view_t *view)

  Release the given MemoryView view and decrement the reference count of view->obj.

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

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

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

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

  Return the Ruby object representation of the item indicated by the given indices. The length of indices must equal to view->ndim. This function uses rb_memory_view_get_item_pointer.

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

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

• void rb_memory_view_prepare_item_desc(rb_memory_view_t *view)

  Fill the item_desc member of view.

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

  Return false otherwise.

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

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