MemoryView

MemoryView bietet die Funktionen, um multidimensionale homogene Arrays mit Elementen fester Größe auf Speicher unter Erweiterungsbibliotheken zu teilen.

Haftungsausschluss

• Diese Funktion ist noch experimentell. Die hier beschriebene Spezifikation kann sich in Zukunft ändern.

• Dieses Dokument ist in Arbeit. Bitte beachten Sie den Hauptzweig von Ruby für die neueste Version dieses Dokuments.

Übersicht

Wir befassen uns manchmal mit bestimmten Arten von Objekten, die Arrays mit gleich typisierten Elementen fester Größe auf einem zusammenhängenden Speicherbereich als interne Darstellung haben. Numo::NArray in numo-narray und Magick::Image in rmagick sind typische Beispiele für solche Objekte. MemoryView spielt die Rolle der Drehscheibe, um die internen Daten solcher Objekte ohne Kopie zwischen solchen Bibliotheken zu teilen.

Das kopierfreie Teilen von Daten ist in einigen Bereichen wie Datenanalyse, maschinelles Lernen und Bildverarbeitung sehr wichtig. In diesen Bereichen müssen die Leute große Mengen von Daten im Speicher mit mehreren Bibliotheken bearbeiten. Wenn wir gezwungen sind, zum Austausch großer Daten zwischen Bibliotheken zu kopieren, muss ein großer Teil der Datenverarbeitungszeit mit dem Kopieren von Daten belegt sein. Sie können solche Zeitverschwendung vermeiden, indem Sie MemoryView verwenden.

MemoryView hat zwei Kategorien von APIs

1. Producer API

   Klassen können ihren eigenen MemoryView-Eintrag registrieren, der es Objekten dieser Klassen ermöglicht, ihre MemoryView preiszugeben.

2. Consumer API

   Die Consumer API ermöglicht es uns, die MemoryView eines Objekts zu erhalten und zu verwalten.

MemoryView-Struktur

Eine MemoryView-Struktur, rb_memory_view_t, wird verwendet, um die MemoryView von Objekten zu exportieren. Diese Struktur enthält die Referenz auf das Objekt, das der Besitzer der MemoryView ist, den Zeiger auf den Kopf des exportierten Speichers und die Metadaten, die die Struktur des Speichers beschreiben. Die Metadaten können multidimensionale Arrays mit Strides beschreiben.

Die Mitglieder der MemoryView-Struktur

Die MemoryView-Struktur besteht aus den folgenden Mitgliedern.

• VALUE obj

  Die Referenz auf das ursprüngliche Objekt, das den über MemoryView exportierten Speicher besitzt.

  RubyVM verwaltet die Referenzzählung der MemoryView-exportierten Objekte, um sie vor der Garbage Collection zu schützen. Die Konsumenten müssen sich nicht darum kümmern, dieses Objekt vor GC zu schützen.

• void *data

  Der Zeiger auf den Kopf des exportierten Speichers.

• ssize_t byte_size

  Die Anzahl der Bytes im Speicher, auf den data zeigt.

• bool readonly

  true für schreibgeschützten Speicher, false für beschreibbaren Speicher.

• const char *format

  Eine Zeichenkette zur Beschreibung des Formats eines Elements oder NULL für ein unverpacktes Byte.

• ssize_t item_size

  Die Anzahl der Bytes in jedem Element.

• const rb_memory_view_item_component_t *item_desc.components

  Das Array der Metadaten der Komponente in einem Element.

• size_t item_desc.length

  Die Anzahl der Elemente in item_desc.components.

• ssize_t ndim

  Die Anzahl der Dimensionen.

• const ssize_t *shape

  Ein Array der Größe ndim, das die Anzahl der Elemente in jeder Dimension angibt. Dies kann NULL sein, wenn ndim 1 ist.

• const ssize_t *strides

  Ein Array der Größe ndim, das die Anzahl der Bytes angibt, die übersprungen werden müssen, um zum nächsten Element in jeder Dimension zu gelangen. Dies kann NULL sein, wenn ndim 1 ist.

• const ssize_t *sub_offsets

  Ein Array der Größe ndim, das die Offsets in jeder Dimension angibt, wenn die MemoryView ein verschachteltes Array bereitstellt. Dies kann NULL sein, wenn die MemoryView ein flaches Array bereitstellt.

• void *private_data

  Die privaten Daten, die der MemoryView-Anbieter intern verwendet. Dies kann NULL sein, wenn keine privaten Daten benötigt werden.

MemoryView APIs

Für Konsumenten

• bool rb_memory_view_available_p(VALUE obj)

  Gibt true zurück, wenn obj die Bereitstellung einer MemoryView unterstützt. Gibt andernfalls false zurück.

  Wenn diese Funktion true zurückgibt, bedeutet dies nicht, dass die Funktion rb_memory_view_get erfolgreich sein wird.

• bool rb_memory_view_get(VALUE obj, rb_memory_view_t *view, int flags)

  Wenn das gegebene obj die Bereitstellung einer MemoryView unterstützt, die den gegebenen flags entspricht, füllt diese Funktion view mit den Informationen der MemoryView und gibt true zurück. In diesem Fall wird die Referenzzählung von obj erhöht.

  Wenn die gegebene Kombination von obj und flags keine MemoryView bereitstellen kann, gibt diese Funktion false zurück. Der Inhalt von view wird in diesem Fall nicht berührt.

  Die bereitgestellte MemoryView muss mit rb_memory_view_release freigegeben werden, wenn die MemoryView nicht mehr benötigt wird.

• bool rb_memory_view_release(rb_memory_view_t *view)

  Gibt die gegebene MemoryView view frei und dekrementiert die Referenzzählung von view->obj.

  Konsumenten müssen diese Funktion aufrufen, wenn die MemoryView nicht mehr benötigt wird. Das Nichtaufrufen dieser Funktion führt zu Speicherlecks.

• ssize_t rb_memory_view_item_size_from_format(const char *format, const char **err)

  Berechnet die Anzahl der Bytes, die ein Element belegt.

  Wenn die Berechnung fehlschlägt, wird die fehlerhafte Position in format in err gespeichert und -1 zurückgegeben.

• void *rb_memory_view_get_item_pointer(rb_memory_view_t *view, const ssize_t *indices)

  Berechnet die Position des durch die gegebenen indices angegebenen Elements. Die Länge von indices muss gleich view->ndim sein. Diese Funktion initialisiert view->item_desc bei Bedarf.

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

  Gibt die Ruby-Objektrepräsentation des durch die gegebenen indices angegebenen Elements zurück. Die Länge von indices muss gleich view->ndim sein. Diese Funktion verwendet 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)

Füllt die Mitglieder von view als 1-dimensionales 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)

Füllt das Array strides mit den Byte-Strides eines zusammenhängenden Arrays mit der gegebenen Form und Elementgröße.

• void rb_memory_view_prepare_item_desc(rb_memory_view_t *view)

Füllt das Mitglied item_desc von view.

• bool rb_memory_view_is_contiguous(const rb_memory_view_t *view)

Gibt true zurück, wenn die Daten in der MemoryView view zeilenweise oder spaltenweise zusammenhängend sind.

Gibt andernfalls false zurück.

• bool rb_memory_view_is_row_major_contiguous(const rb_memory_view_t *view)

Gibt true zurück, wenn die Daten in der MemoryView view zeilenweise zusammenhängend sind.

Gibt andernfalls false zurück.

• bool rb_memory_view_is_column_major_contiguous(const rb_memory_view_t *view)

Gibt true zurück, wenn die Daten in der MemoryView view spaltenweise zusammenhängend sind.

Gibt andernfalls false zurück.