doc/memory_view.md

   1 # MemoryView
   2
   3 MemoryView provides the features to share multidimensional homogeneous arrays of
   4 fixed-size element on memory among extension libraries.
   5
   6 ## Disclaimer
   7
   8 * This feature is still experimental.  The specification described here can be changed in the future.
   9
  10 * This document is under construction.  Please refer the master branch of ruby for the latest version of this document.
  11
  12 ## Overview
  13
  14 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.
  15 Numo::NArray in numo-narray and Magick::Image in rmagick are typical examples of such objects.
  16 MemoryView plays the role of the hub to share the internal data of such objects without copy among such libraries.
  17
  18 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.
  19
  20 MemoryView has two categories of APIs:
  21
  22 1. Producer API
  23
  24     Classes can register own MemoryView entry which allows objects of that classes to expose their MemoryView
  25
  26 2. Consumer API
  27
  28     Consumer API allows us to obtain and manage the MemoryView of an object
  29
  30 ## MemoryView structure
  31
  32 A MemoryView structure, `rb_memory_view_t`, is used for exporting objects' MemoryView.
  33 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.
  34
  35 ### The member of MemoryView structure
  36
  37 The MemoryView structure consists of the following members.
  38
  39 - `VALUE obj`
  40
  41     The reference to the original object that has the memory exported via the MemoryView.
  42
  43     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.
  44
  45 - `void *data`
  46
  47     The pointer to the head of the exported memory.
  48
  49 - `ssize_t byte_size`
  50
  51     The number of bytes in the memory pointed by `data`.
  52
  53 - `bool readonly`
  54
  55     `true` for readonly memory, `false` for writable memory.
  56
  57 - `const char *format`
  58
  59     A string to describe the format of an element, or NULL for unsigned byte.
  60
  61 - `ssize_t item_size`
  62
  63     The number of bytes in each element.
  64
  65 - `const rb_memory_view_item_component_t *item_desc.components`
  66
  67     The array of the metadata of the component in an element.
  68
  69 - `size_t item_desc.length`
  70
  71     The number of items in `item_desc.components`.
  72
  73 - `ssize_t ndim`
  74
  75     The number of dimensions.
  76
  77 - `const ssize_t *shape`
  78
  79     A `ndim` size array indicating the number of elements in each dimension.
  80     This can be `NULL` when `ndim` is 1.
  81
  82 - `const ssize_t *strides`
  83
  84     A `ndim` size array indicating the number of bytes to skip to go to the next element in each dimension.
  85     This can be `NULL` when `ndim` is 1.
  86
  87 - `const ssize_t *sub_offsets`
  88
  89     A `ndim` size array consisting of the offsets in each dimension when the MemoryView exposes a nested array.
  90     This can be `NULL` when the MemoryView exposes a flat array.
  91
  92 - `void *private_data`
  93
  94     The private data that MemoryView provider uses internally.
  95     This can be `NULL` when any private data is unnecessary.
  96
  97 ## MemoryView APIs
  98
  99 ### For consumers
 100
 101 - `bool rb_memory_view_available_p(VALUE obj)`
 102
 103     Return `true` if `obj` supports to export a MemoryView.  Return `false` otherwise.
 104
 105     If this function returns `true`, it doesn't mean the function `rb_memory_view_get` will succeed.
 106
 107 - `bool rb_memory_view_get(VALUE obj, rb_memory_view_t *view, int flags)`
 108
 109     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.
 110
 111     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.
 112
 113     The exported MemoryView must be released by `rb_memory_view_release` when the MemoryView is no longer needed.
 114
 115 - `bool rb_memory_view_release(rb_memory_view_t *view)`
 116
 117     Release the given MemoryView `view` and decrement the reference count of `view->obj`.
 118
 119     Consumers must call this function when the MemoryView is no longer needed.  Missing to call this function leads memory leak.
 120
 121 - `ssize_t rb_memory_view_item_size_from_format(const char *format, const char **err)`
 122
 123     Calculate the number of bytes occupied by an element.
 124
 125     When the calculation fails, the failed location in `format` is stored into `err`, and returns `-1`.
 126
 127 - `void *rb_memory_view_get_item_pointer(rb_memory_view_t *view, const ssize_t *indices)`
 128
 129     Calculate the location of the item indicated by the given `indices`.
 130     The length of `indices` must equal to `view->ndim`.
 131     This function initializes `view->item_desc` if needed.
 132
 133 - `VALUE rb_memory_view_get_item(rb_memory_view_t *view, const ssize_t *indices)`
 134
 135     Return the Ruby object representation of the item indicated by the given `indices`.
 136     The length of `indices` must equal to `view->ndim`.
 137     This function uses `rb_memory_view_get_item_pointer`.
 138
 139 - `rb_memory_view_init_as_byte_array(rb_memory_view_t *view, VALUE obj, void *data, const ssize_t len, const bool readonly)`
 140
 141   Fill the members of `view` as an 1-dimensional byte array.
 142
 143 - `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)`
 144
 145   Fill the `strides` array with byte-Strides of a contiguous array of the given shape with the given element size.
 146
 147 - `void rb_memory_view_prepare_item_desc(rb_memory_view_t *view)`
 148
 149   Fill the `item_desc` member of `view`.
 150
 151 - `bool rb_memory_view_is_contiguous(const rb_memory_view_t *view)`
 152
 153   Return `true` if the data in the MemoryView `view` is row-major or column-major contiguous.
 154
 155   Return `false` otherwise.
 156
 157 - `bool rb_memory_view_is_row_major_contiguous(const rb_memory_view_t *view)`
 158
 159   Return `true` if the data in the MemoryView `view` is row-major contiguous.
 160
 161   Return `false` otherwise.
 162
 163 - `bool rb_memory_view_is_column_major_contiguous(const rb_memory_view_t *view)`
 164
 165   Return `true` if the data in the MemoryView `view` is column-major contiguous.
 166
 167   Return `false` otherwise.