From c8cd6cd28857b14199ee99683f789eb11a28794e Mon Sep 17 00:00:00 2001 From: Iaroslav Date: Sat, 8 Aug 2020 04:21:59 +0700 Subject: [PATCH] Document memory module and several ND objects --- .../kmath/structures/BoxingNDField.kt | 1 - .../kmath/structures/BufferedNDAlgebra.kt | 3 +- .../kmath/structures/ComplexNDField.kt | 4 +- .../kmath/structures/ExtendedNDField.kt | 7 ++ .../kmath/structures/MemoryBuffer.kt | 1 - .../scientifik/kmath/structures/NDAlgebra.kt | 7 +- .../kmath/structures/NDStructure.kt | 77 ++++++++++++--- .../kmath/structures/RealNDField.kt | 4 +- .../kotlin/scientifik/memory/Memory.kt | 97 ++++++++++++++++--- .../kotlin/scientifik/memory/MemorySpec.kt | 17 +++- .../scientifik/memory/DataViewMemory.kt | 18 ++-- .../scientifik/memory/ByteBufferMemory.kt | 48 ++++----- 12 files changed, 217 insertions(+), 67 deletions(-) diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/BoxingNDField.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/BoxingNDField.kt index 516f9a8cd..4cbb565c1 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/BoxingNDField.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/BoxingNDField.kt @@ -3,7 +3,6 @@ package scientifik.kmath.structures import scientifik.kmath.operations.Field import scientifik.kmath.operations.FieldElement - class BoxingNDField>( override val shape: IntArray, override val elementContext: F, diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/BufferedNDAlgebra.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/BufferedNDAlgebra.kt index baf1a05a6..06922c56f 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/BufferedNDAlgebra.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/BufferedNDAlgebra.kt @@ -11,7 +11,8 @@ interface BufferedNDAlgebra : NDAlgebra> { /** * Convert any [NDStructure] to buffered structure using strides from this context. - * If the structure is already [NDBuffer], conversion is free. If not, it could be expensive because iteration over indexes + * If the structure is already [NDBuffer], conversion is free. If not, it could be expensive because iteration over + * indices. * * If the argument is [NDBuffer] with different strides structure, the new element will be produced. */ diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/ComplexNDField.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/ComplexNDField.kt index 2f7d20b6d..be0b9e5c6 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/ComplexNDField.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/ComplexNDField.kt @@ -98,13 +98,13 @@ inline fun BufferedNDField.produceInline(crossinline init } /** - * Map one [ComplexNDElement] using function with indexes + * Map one [ComplexNDElement] using function with indices. */ inline fun ComplexNDElement.mapIndexed(crossinline transform: ComplexField.(index: IntArray, Complex) -> Complex): ComplexNDElement = context.produceInline { offset -> transform(strides.index(offset), buffer[offset]) } /** - * Map one [ComplexNDElement] using function without indexes + * Map one [ComplexNDElement] using function without indices. */ inline fun ComplexNDElement.map(crossinline transform: ComplexField.(Complex) -> Complex): ComplexNDElement { val buffer = Buffer.complex(strides.linearSize) { offset -> ComplexField.transform(buffer[offset]) } diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/ExtendedNDField.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/ExtendedNDField.kt index 1fe449632..24aa48c6b 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/ExtendedNDField.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/ExtendedNDField.kt @@ -2,6 +2,13 @@ package scientifik.kmath.structures import scientifik.kmath.operations.ExtendedField +/** + * [ExtendedField] over [NDStructure]. + * + * @param T the type of the element contained in ND structure. + * @param N the type of ND structure. + * @param F the extended field of structure elements. + */ interface ExtendedNDField, N : NDStructure> : NDField, ExtendedField ///** diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/MemoryBuffer.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/MemoryBuffer.kt index 70e4a8f0f..1d0c87580 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/MemoryBuffer.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/MemoryBuffer.kt @@ -10,7 +10,6 @@ import scientifik.memory.* * @property spec the spec of [T] type. */ open class MemoryBuffer(protected val memory: Memory, protected val spec: MemorySpec) : Buffer { - override val size: Int get() = memory.size / spec.objectSize private val reader: MemoryReader = memory.reader() diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/NDAlgebra.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/NDAlgebra.kt index f2805529c..f09db3c72 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/NDAlgebra.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/NDAlgebra.kt @@ -105,10 +105,11 @@ interface NDRing, N : NDStructure> : Ring, NDSpace } /** - * Field for n-dimensional structures. + * Field of [NDStructure]. * - * @param T the type of the element contained in ND structure - * @param F field of structure elements + * @param T the type of the element contained in ND structure. + * @param N the type of ND structure. + * @param F field of structure elements. */ interface NDField, N : NDStructure> : Field, NDRing { diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/NDStructure.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/NDStructure.kt index bcd74ed2a..9d7735053 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/NDStructure.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/NDStructure.kt @@ -3,15 +3,38 @@ package scientifik.kmath.structures import kotlin.jvm.JvmName import kotlin.reflect.KClass - +/** + * Represents n-dimensional structure, i.e. multidimensional container of items of the same type and size. The number + * of dimensions and items in an array is defined by its shape, which is a sequence of non-negative integers that + * specify the sizes of each dimension. + * + * @param T the type of items. + */ interface NDStructure { - + /** + * The shape of structure, i.e. non-empty sequence of non-negative integers that specify sizes of dimensions of + * this structure. + */ val shape: IntArray + /** + * The count of dimensions in this structure. It should be equal to size of [shape]. + */ val dimension: Int get() = shape.size + /** + * Returns the value at the specified indices. + * + * @param index the indices. + * @return the value. + */ operator fun get(index: IntArray): T + /** + * Returns the sequence of all the elements associated by their indices. + * + * @return the lazy sequence of pairs of indices to values. + */ fun elements(): Sequence> override fun equals(other: Any?): Boolean @@ -19,6 +42,9 @@ interface NDStructure { override fun hashCode(): Int companion object { + /** + * Indicates whether some [NDStructure] is equal to another one. + */ fun equals(st1: NDStructure<*>, st2: NDStructure<*>): Boolean { if (st1 === st2) return true @@ -36,9 +62,9 @@ interface NDStructure { } /** - * Create a NDStructure with explicit buffer factory + * Creates a NDStructure with explicit buffer factory. * - * Strides should be reused if possible + * Strides should be reused if possible. */ fun build( strides: Strides, @@ -91,9 +117,24 @@ interface NDStructure { } } +/** + * Returns the value at the specified indices. + * + * @param index the indices. + * @return the value. + */ operator fun NDStructure.get(vararg index: Int): T = get(index) +/** + * Represents mutable [NDStructure]. + */ interface MutableNDStructure : NDStructure { + /** + * Inserts an item at the specified indices. + * + * @param index the indices. + * @param value the value. + */ operator fun set(index: IntArray, value: T) } @@ -104,7 +145,7 @@ inline fun MutableNDStructure.mapInPlace(action: (IntArray, T) -> T) { } /** - * A way to convert ND index to linear one and back + * A way to convert ND index to linear one and back. */ interface Strides { /** @@ -141,6 +182,9 @@ interface Strides { } } +/** + * Simple implementation of [Strides]. + */ class DefaultStrides private constructor(override val shape: IntArray) : Strides { /** * Strides for memory access @@ -180,19 +224,14 @@ class DefaultStrides private constructor(override val shape: IntArray) : Strides override val linearSize: Int get() = strides[shape.size] - override fun equals(other: Any?): Boolean { if (this === other) return true if (other !is DefaultStrides) return false - if (!shape.contentEquals(other.shape)) return false - return true } - override fun hashCode(): Int { - return shape.contentHashCode() - } + override fun hashCode(): Int = shape.contentHashCode() companion object { private val defaultStridesCache = HashMap() @@ -204,8 +243,20 @@ class DefaultStrides private constructor(override val shape: IntArray) : Strides } } +/** + * Represents [NDStructure] over [Buffer]. + * + * @param T the type of items. + */ abstract class NDBuffer : NDStructure { + /** + * The underlying buffer. + */ abstract val buffer: Buffer + + /** + * The strides to access elements of [Buffer] by linear indices. + */ abstract val strides: Strides override fun get(index: IntArray): T = buffer[strides.offset(index)] @@ -263,8 +314,8 @@ class MutableBufferNDStructure( ) : NDBuffer(), MutableNDStructure { init { - if (strides.linearSize != buffer.size) { - error("Expected buffer side of ${strides.linearSize}, but found ${buffer.size}") + require(strides.linearSize == buffer.size) { + "Expected buffer side of ${strides.linearSize}, but found ${buffer.size}" } } diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/RealNDField.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/RealNDField.kt index b89f28233..e2a1a33df 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/RealNDField.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/RealNDField.kt @@ -93,13 +93,13 @@ inline fun BufferedNDField.produceInline(crossinline initiali } /** - * Map one [RealNDElement] using function with indexes + * Map one [RealNDElement] using function with indices. */ inline fun RealNDElement.mapIndexed(crossinline transform: RealField.(index: IntArray, Double) -> Double): RealNDElement = context.produceInline { offset -> transform(strides.index(offset), buffer[offset]) } /** - * Map one [RealNDElement] using function without indexes + * Map one [RealNDElement] using function without indices. */ inline fun RealNDElement.map(crossinline transform: RealField.(Double) -> Double): RealNDElement { val array = DoubleArray(strides.linearSize) { offset -> RealField.transform(buffer[offset]) } diff --git a/kmath-memory/src/commonMain/kotlin/scientifik/memory/Memory.kt b/kmath-memory/src/commonMain/kotlin/scientifik/memory/Memory.kt index 7c6886202..a749a7074 100644 --- a/kmath-memory/src/commonMain/kotlin/scientifik/memory/Memory.kt +++ b/kmath-memory/src/commonMain/kotlin/scientifik/memory/Memory.kt @@ -1,77 +1,148 @@ package scientifik.memory +/** + * Represents a display of certain memory structure. + */ interface Memory { + /** + * The length of this memory in bytes. + */ val size: Int /** - * Get a projection of this memory (it reflects the changes in the parent memory block) + * Get a projection of this memory (it reflects the changes in the parent memory block). */ fun view(offset: Int, length: Int): Memory /** - * Create a copy of this memory, which does not know anything about this memory + * Creates an independent copy of this memory. */ fun copy(): Memory /** - * Create and possibly register a new reader + * Gets or creates a reader of this memory. */ fun reader(): MemoryReader + /** + * Gets or creates a writer of this memory. + */ fun writer(): MemoryWriter - companion object { - - } + companion object } +/** + * The interface to read primitive types in this memory. + */ interface MemoryReader { + /** + * The underlying memory. + */ val memory: Memory + /** + * Reads [Double] at certain [offset]. + */ fun readDouble(offset: Int): Double + + /** + * Reads [Float] at certain [offset]. + */ fun readFloat(offset: Int): Float + + /** + * Reads [Byte] at certain [offset]. + */ fun readByte(offset: Int): Byte + + /** + * Reads [Short] at certain [offset]. + */ fun readShort(offset: Int): Short + + /** + * Reads [Int] at certain [offset]. + */ fun readInt(offset: Int): Int + + /** + * Reads [Long] at certain [offset]. + */ fun readLong(offset: Int): Long + /** + * Disposes this reader if needed. + */ fun release() } /** - * Use the memory for read then release the reader + * Uses the memory for read then releases the reader. */ inline fun Memory.read(block: MemoryReader.() -> Unit) { - reader().apply(block).apply { release() } + reader().apply(block).release() } +/** + * The interface to write primitive types into this memory. + */ interface MemoryWriter { + /** + * The underlying memory. + */ val memory: Memory + /** + * Writes [Double] at certain [offset]. + */ fun writeDouble(offset: Int, value: Double) + + /** + * Writes [Float] at certain [offset]. + */ fun writeFloat(offset: Int, value: Float) + + /** + * Writes [Byte] at certain [offset]. + */ fun writeByte(offset: Int, value: Byte) + + /** + * Writes [Short] at certain [offset]. + */ fun writeShort(offset: Int, value: Short) + + /** + * Writes [Int] at certain [offset]. + */ fun writeInt(offset: Int, value: Int) + + /** + * Writes [Long] at certain [offset]. + */ fun writeLong(offset: Int, value: Long) + /** + * Disposes this writer if needed. + */ fun release() } /** - * Use the memory for write then release the writer + * Uses the memory for write then releases the writer. */ inline fun Memory.write(block: MemoryWriter.() -> Unit) { - writer().apply(block).apply { release() } + writer().apply(block).release() } /** - * Allocate the most effective platform-specific memory + * Allocates the most effective platform-specific memory. */ expect fun Memory.Companion.allocate(length: Int): Memory /** - * Wrap a [Memory] around existing [ByteArray]. This operation is unsafe since the array is not copied - * and could be mutated independently from the resulting [Memory] + * Wraps a [Memory] around existing [ByteArray]. This operation is unsafe since the array is not copied + * and could be mutated independently from the resulting [Memory]. */ expect fun Memory.Companion.wrap(array: ByteArray): Memory diff --git a/kmath-memory/src/commonMain/kotlin/scientifik/memory/MemorySpec.kt b/kmath-memory/src/commonMain/kotlin/scientifik/memory/MemorySpec.kt index 4d0035d09..59a93f290 100644 --- a/kmath-memory/src/commonMain/kotlin/scientifik/memory/MemorySpec.kt +++ b/kmath-memory/src/commonMain/kotlin/scientifik/memory/MemorySpec.kt @@ -7,7 +7,7 @@ package scientifik.memory */ interface MemorySpec { /** - * Size of [T] in bytes after serialization + * Size of [T] in bytes after serialization. */ val objectSize: Int @@ -24,9 +24,19 @@ interface MemorySpec { fun MemoryWriter.write(offset: Int, value: T) } +/** + * Reads the object with [spec] starting from [offset]. + */ fun MemoryReader.read(spec: MemorySpec, offset: Int): T = with(spec) { read(offset) } + +/** + * Writes the object [value] with [spec] starting from [offset]. + */ fun MemoryWriter.write(spec: MemorySpec, offset: Int, value: T): Unit = with(spec) { write(offset, value) } +/** + * Reads array of [size] objects mapped by [spec] at certain [offset]. + */ inline fun MemoryReader.readArray(spec: MemorySpec, offset: Int, size: Int): Array = Array(size) { i -> spec.run { @@ -34,7 +44,10 @@ inline fun MemoryReader.readArray(spec: MemorySpec, offset: } } +/** + * Writes [array] of objects mapped by [spec] at certain [offset]. + */ fun MemoryWriter.writeArray(spec: MemorySpec, offset: Int, array: Array): Unit = with(spec) { array.indices.forEach { i -> write(offset + i * objectSize, array[i]) } } -//TODO It is possible to add elastic MemorySpec with unknown object size \ No newline at end of file +// TODO It is possible to add elastic MemorySpec with unknown object size diff --git a/kmath-memory/src/jsMain/kotlin/scientifik/memory/DataViewMemory.kt b/kmath-memory/src/jsMain/kotlin/scientifik/memory/DataViewMemory.kt index 38ec14824..974750502 100644 --- a/kmath-memory/src/jsMain/kotlin/scientifik/memory/DataViewMemory.kt +++ b/kmath-memory/src/jsMain/kotlin/scientifik/memory/DataViewMemory.kt @@ -4,13 +4,13 @@ import org.khronos.webgl.ArrayBuffer import org.khronos.webgl.DataView import org.khronos.webgl.Int8Array -class DataViewMemory(val view: DataView) : Memory { - +private class DataViewMemory(val view: DataView) : Memory { override val size: Int get() = view.byteLength override fun view(offset: Int, length: Int): Memory { require(offset >= 0) { "offset shouldn't be negative: $offset" } require(length >= 0) { "length shouldn't be negative: $length" } + require(offset + length <= size) { "Can't view memory outside the parent region." } if (offset + length > size) throw IndexOutOfBoundsException("offset + length > size: $offset + $length > $size") @@ -33,11 +33,11 @@ class DataViewMemory(val view: DataView) : Memory { override fun readInt(offset: Int): Int = view.getInt32(offset, false) - override fun readLong(offset: Int): Long = (view.getInt32(offset, false).toLong() shl 32) or - view.getInt32(offset + 4, false).toLong() + override fun readLong(offset: Int): Long = + view.getInt32(offset, false).toLong() shl 32 or view.getInt32(offset + 4, false).toLong() override fun release() { - // does nothing on JS because of GC + // does nothing on JS } } @@ -72,7 +72,7 @@ class DataViewMemory(val view: DataView) : Memory { } override fun release() { - //does nothing on JS + // does nothing on JS } } @@ -81,13 +81,17 @@ class DataViewMemory(val view: DataView) : Memory { } /** - * Allocate the most effective platform-specific memory + * Allocates memory based on a [DataView]. */ actual fun Memory.Companion.allocate(length: Int): Memory { val buffer = ArrayBuffer(length) return DataViewMemory(DataView(buffer, 0, length)) } +/** + * Wraps a [Memory] around existing [ByteArray]. This operation is unsafe since the array is not copied + * and could be mutated independently from the resulting [Memory]. + */ actual fun Memory.Companion.wrap(array: ByteArray): Memory { @Suppress("CAST_NEVER_SUCCEEDS") val int8Array = array as Int8Array return DataViewMemory(DataView(int8Array.buffer, int8Array.byteOffset, int8Array.length)) diff --git a/kmath-memory/src/jvmMain/kotlin/scientifik/memory/ByteBufferMemory.kt b/kmath-memory/src/jvmMain/kotlin/scientifik/memory/ByteBufferMemory.kt index 9ec2b3a09..b5a0dd51b 100644 --- a/kmath-memory/src/jvmMain/kotlin/scientifik/memory/ByteBufferMemory.kt +++ b/kmath-memory/src/jvmMain/kotlin/scientifik/memory/ByteBufferMemory.kt @@ -6,19 +6,18 @@ import java.nio.file.Files import java.nio.file.Path import java.nio.file.StandardOpenOption - private class ByteBufferMemory( val buffer: ByteBuffer, val startOffset: Int = 0, override val size: Int = buffer.limit() ) : Memory { - - @Suppress("NOTHING_TO_INLINE") private inline fun position(o: Int): Int = startOffset + o override fun view(offset: Int, length: Int): Memory { - if (offset + length > size) error("Selecting a Memory view outside of memory range") + require(offset >= 0) { "offset shouldn't be negative: $offset" } + require(length >= 0) { "length shouldn't be negative: $length" } + require(offset + length <= size) { "Can't view memory outside the parent region." } return ByteBufferMemory(buffer, position(offset), length) } @@ -28,10 +27,9 @@ private class ByteBufferMemory( copy.put(buffer) copy.flip() return ByteBufferMemory(copy) - } - private val reader = object : MemoryReader { + private val reader: MemoryReader = object : MemoryReader { override val memory: Memory get() = this@ByteBufferMemory override fun readDouble(offset: Int) = buffer.getDouble(position(offset)) @@ -47,13 +45,13 @@ private class ByteBufferMemory( override fun readLong(offset: Int) = buffer.getLong(position(offset)) override fun release() { - //does nothing on JVM + // does nothing on JVM } } override fun reader(): MemoryReader = reader - private val writer = object : MemoryWriter { + private val writer: MemoryWriter = object : MemoryWriter { override val memory: Memory get() = this@ByteBufferMemory override fun writeDouble(offset: Int, value: Double) { @@ -81,7 +79,7 @@ private class ByteBufferMemory( } override fun release() { - //does nothing on JVM + // does nothing on JVM } } @@ -89,26 +87,32 @@ private class ByteBufferMemory( } /** - * Allocate the most effective platform-specific memory + * Allocates memory based on a [ByteBuffer]. */ -actual fun Memory.Companion.allocate(length: Int): Memory { - val buffer = ByteBuffer.allocate(length) - return ByteBufferMemory(buffer) -} +actual fun Memory.Companion.allocate(length: Int): Memory = + ByteBufferMemory(checkNotNull(ByteBuffer.allocate(length))) -actual fun Memory.Companion.wrap(array: ByteArray): Memory { - val buffer = ByteBuffer.wrap(array) - return ByteBufferMemory(buffer) -} +/** + * Wraps a [Memory] around existing [ByteArray]. This operation is unsafe since the array is not copied + * and could be mutated independently from the resulting [Memory]. + */ +actual fun Memory.Companion.wrap(array: ByteArray): Memory = ByteBufferMemory(checkNotNull(ByteBuffer.wrap(array))) +/** + * Wraps this [ByteBuffer] to [Memory] object. + * + * @receiver the byte buffer. + * @param startOffset the start offset. + * @param size the size of memory to map. + * @return the [Memory] object. + */ fun ByteBuffer.asMemory(startOffset: Int = 0, size: Int = limit()): Memory = ByteBufferMemory(this, startOffset, size) /** - * Use direct memory-mapped buffer from file to read something and close it afterwards. + * Uses direct memory-mapped buffer from file to read something and close it afterwards. */ -fun Path.readAsMemory(position: Long = 0, size: Long = Files.size(this), block: Memory.() -> R): R { - return FileChannel.open(this, StandardOpenOption.READ).use { +fun Path.readAsMemory(position: Long = 0, size: Long = Files.size(this), block: Memory.() -> R): R = + FileChannel.open(this, StandardOpenOption.READ).use { ByteBufferMemory(it.map(FileChannel.MapMode.READ_ONLY, position, size)).block() } -} \ No newline at end of file