ÿØÿà JFIF ÿÛ „ ( % !1!%)+//. 383,7(-.+
-% %-////---/-.+/--+------/------/--0+--/-/-----.-----ÿÀ ¥2" ÿÄ ÿÄ J ! 1AQ"aq2‘#BR‚¡ÁÑ3br’¢±Âð$CSƒ²á4c“%DsÓñÿÄ ÿÄ * !1AQa‘"2q3±ð#b¡ÿÚ ? ¼QxJQa Íuò¸Zö Úü8,Ð Úú
"SS n<rçù–´âE—^ªBÖ9À\†¸ÔÁTÃÛ5
ëd´³Í#Ý;Þ38œî ¶ H£M:wÎ3…³…âpÔF&‚FK¸9„â4àGEõªfÿ ‘ñ(ß wpŽF|È¥ù®häðÍѶ¹‘[ÒinÙW¶ùñ Y˜Q{›K"išÒ[Ú8žë\F¹@-? v"ÔU”,ìöžkÿ {I‡£šÍ?e
ríV
?>
.........................................
.............................................................................
ÿØÿà JFIF ÿÛ „
(
% !1!%)+//. 383,7(-.+
-% %-////---/-.+/--+------/------/--0+--/-/-----.-----ÿÀ ¥2" ÿÄ
ÿÄ J ! 1AQ"aq2‘#BR‚¡ÁÑ3br’¢±Âð$CSƒ²á4c“%DsÓñÿÄ
ÿÄ * !1AQa‘"2q3±ð#b¡ÿÚ
? ¼QxJQa Íuò¸Zö
Úü8,Ð Úú
"SS n<rçù–´âE—^ªBÖ9À\†¸ÔÁTÃÛ5
ëd´³Í#Ý;Þ38œî ¶ H£M:wÎ3…³…âpÔF&‚FK¸9„â4àGEõªfÿ ‘ñ(ß wpŽF|È¥ù®häðÍѶ¹‘[ÒinÙW¶ùñ Y˜Q{›K"išÒ[Ú8žë\F¹@-? v"ÔU”,ìöžkÿ {I‡£šÍ?e
ríV
?>
.........................................
.............................................................................
????????????????????????????????????
????????????????????????????????????
ÿØÿà JFIF ÿÛ „ ( % !1!%)+//. 383,7(-.+
-% %-////---/-.+/--+------/------/--0+--/-/-----.-----ÿÀ ¥2" ÿÄ ÿÄ J ! 1AQ"aq2‘#BR‚¡ÁÑ3br’¢±Âð$CSƒ²á4c“%DsÓñÿÄ ÿÄ * !1AQa‘"2q3±ð#b¡ÿÚ ? ¼QxJQa Íuò¸Zö Úü8,Ð Úú
"SS n<rçù–´âE—^ªBÖ9À\†¸ÔÁTÃÛ5
ëd´³Í#Ý;Þ38œî ¶ H£M:wÎ3…³…âpÔF&‚FK¸9„â4àGEõªfÿ ‘ñ(ß wpŽF|È¥ù®häðÍѶ¹‘[ÒinÙW¶ùñ Y˜Q{›K"išÒ[Ú8žë\F¹@-? v"ÔU”,ìöžkÿ {I‡£šÍ?e
ríV
?>
.........................................
.............................................................................
ÿØÿà JFIF ÿÛ „
(
% !1!%)+//. 383,7(-.+
-% %-////---/-.+/--+------/------/--0+--/-/-----.-----ÿÀ ¥2" ÿÄ
ÿÄ J ! 1AQ"aq2‘#BR‚¡ÁÑ3br’¢±Âð$CSƒ²á4c“%DsÓñÿÄ
ÿÄ * !1AQa‘"2q3±ð#b¡ÿÚ
? ¼QxJQa Íuò¸Zö
Úü8,Ð Úú
"SS n<rçù–´âE—^ªBÖ9À\†¸ÔÁTÃÛ5
ëd´³Í#Ý;Þ38œî ¶ H£M:wÎ3…³…âpÔF&‚FK¸9„â4àGEõªfÿ ‘ñ(ß wpŽF|È¥ù®häðÍѶ¹‘[ÒinÙW¶ùñ Y˜Q{›K"išÒ[Ú8žë\F¹@-? v"ÔU”,ìöžkÿ {I‡£šÍ?e
ríV
?>
.........................................
.............................................................................
????????????????????????????????????
????????????????????????????????????
U:RDoc::TopLevel[ i I"memory_view.md:ETcRDoc::Parser::Markdowno:RDoc::Markup::Document: @parts[$S:RDoc::Markup::Heading:
leveli: textI"MemoryView;To: RDoc::Markup::Paragraph;[I"MemoryView provides the features to share multidimensional homogeneous arrays of
fixed-size element on memory among extension libraries.;TS; ;
i; I"Disclaimer;To:RDoc::Markup::List:
@type: BULLET: @items[o:RDoc::Markup::ListItem: @label0;[o; ;[I"gThis feature is still experimental. The specification described here can be changed in the future.;Fo;;0;[o; ;[I"yThis document is under construction. Please refer the master branch of ruby for the latest version of this document.;FS; ;
i; I"
Overview;To; ;[I"tWe 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.;To; ;[I"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.;To; ;[I"+MemoryView has two categories of APIs:;To;
;: NUMBER;[o;;0;[o; ;[I"Producer API;Fo; ;[I"nClasses can register own MemoryView entry which allows objects of that classes to expose their MemoryView;Fo;;0;[o; ;[I"Consumer API;Fo; ;[I"LConsumer API allows us to obtain and manage the MemoryView of an object;FS; ;
i; I"MemoryView structure;To; ;[I"eA 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.;TS; ;
i; I"'The member of MemoryView structure;To; ;[I"@The MemoryView structure consists of the following members.;To;
;;;[o;;0;[o; ;[I"VALUE obj;To; ;[I"ZThe reference to the original object that has the memory exported via the MemoryView.;Fo; ;[I"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.;Fo;;0;[o; ;[I" void *data;To; ;[I"4The pointer to the head of the exported memory.;Fo;;0;[o; ;[I"#ssize_t byte_size;To; ;[I"DThe number of bytes in the memory pointed by data.;Fo;;0;[o; ;[I" bool readonly;To; ;[I"Strue for readonly memory, false for writable memory.;To;;0;[o; ;[I"$const char *format;To; ;[I"NA string to describe the format of an element, or NULL for unsigned byte.;Fo;;0;[o; ;[I"#ssize_t item_size;To; ;[I")The number of bytes in each element.;Fo;;0;[o; ;[I"Mconst rb_memory_view_item_component_t *item_desc.components;To; ;[I">The array of the metadata of the component in an element.;Fo;;0;[o; ;[I")size_t item_desc.length;To; ;[I">The number of items in item_desc.components.;Fo;;0;[o; ;[I" ssize_t ndim;To; ;[I" The number of dimensions.;Fo;;0;[o; ;[I"&const ssize_t *shape;To; ;[I"A ndim size array indicating the number of elements in each dimension.
This can be NULL when ndim is 1.;Fo;;0;[o; ;[I"(const ssize_t *strides;To; ;[I"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.;Fo;;0;[o; ;[I",const ssize_t *sub_offsets;To; ;[I"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.;Fo;;0;[o; ;[I"$void *private_data;To; ;[I"~The private data that MemoryView provider uses internally.
This can be NULL when any private data is unnecessary.;FS; ;
i; I"MemoryView APIs;TS; ;
i; I"For consumers;To;
;;;[ o;;0;[o; ;[I"<bool rb_memory_view_available_p(VALUE obj);To; ;[I"wReturn true if obj supports to export a MemoryView. Return false otherwise.;Fo; ;[I"{If this function returns true, it doesn't mean the function rb_memory_view_get will succeed.;Fo;;0;[ o; ;[I"Wbool rb_memory_view_get(VALUE obj, rb_memory_view_t *view, int flags);To; ;[I"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.;Fo; ;[I"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.;Fo; ;[I"}The exported MemoryView must be released by rb_memory_view_release when the MemoryView is no longer needed.;Fo;;0;[o; ;[I"Ebool rb_memory_view_release(rb_memory_view_t *view);To; ;[I"pRelease the given MemoryView view and decrement the reference count of view->obj.;Fo; ;[I"{Consumers must call this function when the MemoryView is no longer needed. Missing to call this function leads memory leak.;Fo;;0;[o; ;[I"dssize_t rb_memory_view_item_size_from_format(const char *format, const char **err);To; ;[I":Calculate the number of bytes occupied by an element.;Fo; ;[I"When the calculation fails, the failed location in format is stored into err, and returns -1.;Fo;;0;[o; ;[I"gvoid *rb_memory_view_get_item_pointer(rb_memory_view_t *view, const ssize_t *indices);To; ;[I"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.;Fo;;0;[o; ;[I"_VALUE rb_memory_view_get_item(rb_memory_view_t *view, const ssize_t *indices);To; ;[I"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.;Fo;;0;[o; ;[I"rb_memory_view_init_as_byte_array(rb_memory_view_t *view, VALUE obj, void *data, const ssize_t len, const bool readonly);To; ;[I"JFill the members of view as an 1-dimensional byte array.;To;
;;;[o;;0;[o; ;[I"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);To; ;[I"{Fill the strides array with byte-Strides of a contiguous array of the given shape with the given element size.;To;
;;;[o;;0;[o; ;[I"Ovoid rb_memory_view_prepare_item_desc(rb_memory_view_t *view);To; ;[I"AFill the item_desc member of view.;To;
;;;[o;;0;[o; ;[I"Qbool rb_memory_view_is_contiguous(const rb_memory_view_t *view);To; ;[I"vReturn true if the data in the MemoryView view is row-major or column-major contiguous.;To; ;[I")Return false otherwise.;To;
;;;[o;;0;[o; ;[I"[bool rb_memory_view_is_row_major_contiguous(const rb_memory_view_t *view);To; ;[I"fReturn true if the data in the MemoryView view is row-major contiguous.;To; ;[I")Return false otherwise.;To;
;;;[o;;0;[o; ;[I"^bool rb_memory_view_is_column_major_contiguous(const rb_memory_view_t *view);To; ;[I"iReturn true if the data in the MemoryView view is column-major contiguous.;To; ;[I")Return false otherwise.;T:
@file@:0@omit_headings_from_table_of_contents_below0