Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/pom.xml
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/pom.xml
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/pom.xml
Tue May 21 21:11:49 2024
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+<project xmlns="http://maven.apache.org/POM/4.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+ http://maven.apache.org/xsd/maven-4.0.0.xsd";>
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.apache.datasketches</groupId>
+ <artifactId>datasketches-memory</artifactId>
+ <version>2.2.0</version>
+ </parent>
+
+ <artifactId>datasketches-memory-java8</artifactId>
+ <name>${project.artifactId}</name>
+ <packaging>jar</packaging>
+
+ <properties>
+ <java.version>1.8</java.version>
+ <jdk-toolchain.version>8</jdk-toolchain.version>
+ <maven.compiler.source>${java.version}</maven.compiler.source>
+ <maven.compiler.target>${java.version}</maven.compiler.target>
+ <!-- override javadoc for this module only -->
+ <maven.javadoc.skip>false</maven.javadoc.skip>
+ </properties>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.testng</groupId>
+ <artifactId>testng</artifactId>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <!-- Used for UTF8 testing -->
+ <groupId>com.google.protobuf</groupId>
+ <artifactId>protobuf-java</artifactId>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <!-- Used for xxHash testing -->
+ <groupId>net.openhft</groupId>
+ <artifactId>zero-allocation-hashing</artifactId>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.jacoco</groupId>
+ <artifactId>jacoco-maven-plugin</artifactId>
+ <version>${jacoco-maven-plugin.version}</version>
+ <executions>
+ <execution>
+ <id>report</id>
+ <phase>test</phase>
+ <goals>
+ <goal>report</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+ </build>
+
+</project>
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/pom.xml
------------------------------------------------------------------------------
svn:executable = *
Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseBuffer.java
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseBuffer.java
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseBuffer.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,124 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datasketches.memory;
+
+/**
+ * Defines the relative positional API.
+ *
+ * @author Lee Rhodes
+ */
+public interface BaseBuffer extends BaseState {
+
+ /**
+ * Increments the current position by the given increment.
+ * Asserts that the resource is valid and that the positional invariants are
not violated,
+ * otherwise, if asserts are enabled throws an {@link AssertionError}.
+ * @param increment the given increment
+ * @return BaseBuffer
+ */
+ BaseBuffer incrementPosition(long increment);
+
+ /**
+ * Increments the current position by the given increment.
+ * Checks that the resource is valid and that the positional invariants are
not violated,
+ * otherwise throws an {@link IllegalArgumentException}.
+ * @param increment the given increment
+ * @return BaseBuffer
+ */
+ BaseBuffer incrementAndCheckPosition(final long increment);
+
+ /**
+ * Gets the end position
+ * @return the end position
+ */
+ long getEnd();
+
+ /**
+ * Gets the current position
+ * @return the current position
+ */
+ long getPosition();
+
+ /**
+ * Gets start position
+ * @return start position
+ */
+ long getStart();
+
+ /**
+ * The number of elements remaining between the current position and the end
position
+ * @return {@code (end - position)}
+ */
+ long getRemaining();
+
+ /**
+ * Returns true if there are elements remaining between the current position
and the end position
+ * @return {@code (end - position) > 0}
+ */
+ boolean hasRemaining();
+
+ /**
+ * Resets the current position to the start position,
+ * This does not modify any data.
+ * @return BaseBuffer
+ */
+ BaseBuffer resetPosition();
+
+ /**
+ * Sets the current position.
+ * Asserts that the positional invariants are not violated,
+ * otherwise, if asserts are enabled throws an {@link AssertionError}.
+ * @param position the given current position.
+ * @return BaseBuffer
+ */
+ BaseBuffer setPosition(long position);
+
+ /**
+ * Sets the current position.
+ * Checks that the positional invariants are not violated,
+ * otherwise, throws an {@link IllegalArgumentException}.
+ * @param position the given current position.
+ * @return BaseBuffer
+ */
+ BaseBuffer setAndCheckPosition(long position);
+
+ /**
+ * Sets start position, current position, and end position.
+ * Asserts that the positional invariants are not violated,
+ * otherwise, if asserts are enabled throws an {@link AssertionError}.
+ * @param start the start position in the buffer
+ * @param position the current position between the start and end
+ * @param end the end position in the buffer
+ * @return BaseBuffer
+ */
+ BaseBuffer setStartPositionEnd(long start, long position, long end);
+
+ /**
+ * Sets start position, current position, and end position.
+ * Checks that the positional invariants are not violated,
+ * otherwise, throws an {@link IllegalArgumentException}.
+ * @param start the start position in the buffer
+ * @param position the current position between the start and end
+ * @param end the end position in the buffer
+ * @return BaseBuffer
+ */
+ BaseBuffer setAndCheckStartPositionEnd(long start, long position, long end);
+
+}
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseBuffer.java
------------------------------------------------------------------------------
svn:executable = *
Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseState.java
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseState.java
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseState.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,264 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datasketches.memory;
+
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+
+import org.apache.datasketches.memory.internal.BaseStateImpl;
+
+/**
+ * Keeps key configuration state for Memory and Buffer plus some common static
variables
+ * and check methods.
+ *
+ * @author Lee Rhodes
+ */
+public interface BaseState {
+ /**
+ * The placeholder for the default MemoryRequestServer, if set at all.
+ */
+ static final MemoryRequestServer defaultMemReqSvr = null; //new
DefaultMemoryRequestServer();
+
+ //Byte Order Related
+
+ /**
+ * Gets the current Type ByteOrder.
+ * This may be different from the ByteOrder of the backing resource and of
the Native Byte Order.
+ * @return the current Type ByteOrder.
+ */
+ ByteOrder getTypeByteOrder();
+
+ /**
+ * Returns true if the Native ByteOrder is the same as the ByteOrder of the
+ * current Buffer or Memory and the same ByteOrder as the given byteOrder.
+ * @param byteOrder the given ByteOrder
+ * @return true if the Native ByteOrder is the same as the ByteOrder of the
+ * current Buffer or Memory and the same ByteOrder as the given byteOrder.
+ */
+ boolean isByteOrderCompatible(ByteOrder byteOrder);
+
+ /**
+ * Returns true if the given object is an instance of this class and has
equal data contents.
+ * @param that the given object
+ * @return true if the given Object is an instance of this class and has
equal data contents.
+ */
+ @Override
+ boolean equals(Object that);
+
+ /**
+ * Returns true if the given object is an instance of this class and has
equal contents to
+ * this object in the given range of bytes. This will also check two
distinct ranges within the
+ * same object for equals.
+ * @param thisOffsetBytes the starting offset in bytes for this object.
+ * @param that the given object
+ * @param thatOffsetBytes the starting offset in bytes for the given object
+ * @param lengthBytes the size of the range in bytes
+ * @return true if the given object has equal contents to this object in the
given range of
+ * bytes.
+ */
+ boolean equalTo(long thisOffsetBytes, Object that,
+ long thatOffsetBytes, long lengthBytes);
+
+ /**
+ * Gets the backing ByteBuffer if it exists, otherwise returns null.
+ * @return the backing ByteBuffer if it exists, otherwise returns null.
+ */
+ ByteBuffer getByteBuffer();
+
+ /**
+ * Gets the capacity of this object in bytes
+ * @return the capacity of this object in bytes
+ */
+ long getCapacity();
+
+ /**
+ * Gets the cumulative offset in bytes of this object from the backing
resource.
+ * This offset may also include other offset components such as the native
off-heap
+ * memory address, DirectByteBuffer split offsets, region offsets, and
unsafe arrayBaseOffsets.
+ *
+ * @return the cumulative offset in bytes of this object from the backing
resource.
+ */
+ long getCumulativeOffset();
+
+ /**
+ * Gets the cumulative offset in bytes of this object from the backing
resource including the given
+ * offsetBytes. This offset may also include other offset components such as
the native off-heap
+ * memory address, DirectByteBuffer split offsets, region offsets, and
unsafe arrayBaseOffsets.
+ *
+ * @param offsetBytes offset to be added to the cumulative offset.
+ * @return the cumulative offset in bytes of this object from the backing
resource including the
+ * given offsetBytes.
+ */
+ long getCumulativeOffset(long offsetBytes);
+
+ /**
+ * Returns the offset of address zero of this object relative to the address
zero of the
+ * backing resource but not including the size of any Java object header.
+ * @return the offset of address zero of this object relative to the address
zero of the
+ * backing resource but not including the size of any Java object header.
+ */
+ long getRegionOffset();
+
+ /**
+ * Returns the offset of address zero of this object relative to the address
zero of the
+ * backing resource plus the given offsetBytes but not including the size of
any Java object
+ * header.
+ * @param offsetBytes the given offsetBytes
+ * @return the offset of address zero of this object relative to the address
zero of the
+ * backing resource plus the given offsetBytes but not including the size of
any Java object
+ * header.
+ */
+ long getRegionOffset(long offsetBytes);
+
+ /**
+ * Returns true if this object is backed by an on-heap primitive array
+ * @return true if this object is backed by an on-heap primitive array
+ */
+ boolean hasArray();
+
+ /**
+ * Returns the hashCode of this object.
+ *
+ * <p>The hash code of this object depends upon all of its contents.
+ * Because of this, it is inadvisable to use these objects as keys in hash
maps
+ * or similar data structures unless it is known that their contents will
not change.</p>
+ *
+ * <p>If it is desirable to use these objects in a hash map depending only
on object identity,
+ * than the {@link java.util.IdentityHashMap} can be used.</p>
+ *
+ * @return the hashCode of this object.
+ */
+ @Override
+ int hashCode();
+
+ /**
+ * Returns the 64-bit hash of the sequence of bytes in this object specified
by
+ * <i>offsetBytes</i>, <i>lengthBytes</i> and a <i>seed</i>. Note that the
sequence of bytes is
+ * always processed in the same order independent of endianness.
+ *
+ * @param offsetBytes the given offset in bytes to the first byte of the
byte sequence.
+ * @param lengthBytes the given length in bytes of the byte sequence.
+ * @param seed the given long seed.
+ * @return the 64-bit hash of the sequence of bytes in this object specified
by
+ * <i>offsetBytes</i> and <i>lengthBytes</i>.
+ */
+ long xxHash64(long offsetBytes, long lengthBytes, long seed);
+
+ /**
+ * Returns a 64-bit hash from a single long. This method has been optimized
for speed when only
+ * a single hash of a long is required.
+ * @param in A long.
+ * @param seed A long valued seed.
+ * @return the hash.
+ */
+ long xxHash64(long in, long seed);
+
+ /**
+ * Returns true if this Memory is backed by a ByteBuffer.
+ * @return true if this Memory is backed by a ByteBuffer.
+ */
+ boolean hasByteBuffer();
+
+ /**
+ * Returns true if the backing resource is direct (off-heap) memory.
+ * This is the case for allocated direct memory, memory mapped files,
+ * @return true if the backing resource is direct (off-heap) memory.
+ */
+ boolean isDirect();
+
+ /**
+ * Returns true if this object or the backing resource is read-only.
+ * @return true if this object or the backing resource is read-only.
+ */
+ boolean isReadOnly();
+
+ /**
+ * Returns true if the backing resource of <i>this</i> is identical with the
backing resource
+ * of <i>that</i>. The capacities must be the same. If <i>this</i> is a
region,
+ * the region offset must also be the same.
+ * @param that A different non-null object
+ * @return true if the backing resource of <i>this</i> is the same as the
backing resource
+ * of <i>that</i>.
+ */
+ boolean isSameResource(Object that);
+
+ /**
+ * Returns true if this object is valid and has not been closed.
+ * This is relevant only for direct (off-heap) memory and Mapped Files.
+ * @return true if this object is valid and has not been closed.
+ */
+ boolean isValid();
+
+ /**
+ * Checks that the specified range of bytes is within bounds of this object,
throws
+ * {@link IllegalArgumentException} if it's not: i. e. if offsetBytes <
0, or length < 0,
+ * or offsetBytes + length > {@link #getCapacity()}.
+ * @param offsetBytes the given offset in bytes of this object
+ * @param lengthBytes the given length in bytes of this object
+ */
+ void checkValidAndBounds(long offsetBytes, long lengthBytes);
+
+ //Monitoring
+
+ /**
+ * Gets the current number of active direct memory allocations.
+ * @return the current number of active direct memory allocations.
+ */
+ static long getCurrentDirectMemoryAllocations() {
+ return BaseStateImpl.getCurrentDirectMemoryAllocations();
+ }
+
+ /**
+ * Gets the current size of active direct memory allocated.
+ * @return the current size of active direct memory allocated.
+ */
+ static long getCurrentDirectMemoryAllocated() {
+ return BaseStateImpl.getCurrentDirectMemoryAllocated();
+ }
+
+ /**
+ * Gets the current number of active direct memory map allocations.
+ * @return the current number of active direct memory map allocations.
+ */
+ static long getCurrentDirectMemoryMapAllocations() {
+ return BaseStateImpl.getCurrentDirectMemoryMapAllocations();
+ }
+
+ /**
+ * Gets the current size of active direct memory map allocated.
+ * @return the current size of active direct memory map allocated.
+ */
+ static long getCurrentDirectMemoryMapAllocated() {
+ return BaseStateImpl.getCurrentDirectMemoryMapAllocated();
+ }
+
+ //TO STRING
+
+ /**
+ * Returns a formatted hex string of a range of this object.
+ * Used primarily for testing.
+ * @param header a descriptive header
+ * @param offsetBytes offset bytes relative to this object start
+ * @param lengthBytes number of bytes to convert to a hex string
+ * @return a formatted hex string in a human readable array
+ */
+ String toHexString(String header, long offsetBytes, int lengthBytes);
+
+}
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseState.java
------------------------------------------------------------------------------
svn:executable = *
Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Buffer.java
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Buffer.java
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Buffer.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,371 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datasketches.memory;
+
+import static org.apache.datasketches.memory.internal.Util.negativeCheck;
+
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+import java.util.Objects;
+
+import org.apache.datasketches.memory.internal.BaseWritableBufferImpl;
+
+/**
+ * Defines the read-only API for relative positional access to a resource.
+ *
+ * @author Lee Rhodes
+ */
+public interface Buffer extends BaseBuffer {
+
+ //BYTE BUFFER
+ /**
+ * Accesses the given ByteBuffer for read-only operations. The returned
Buffer object has the
+ * same byte order, as the given ByteBuffer.
+ * @param byteBuffer the given ByteBuffer, must not be null.
+ * @return a new Buffer for read-only operations on the given ByteBuffer.
+ */
+ static Buffer wrap(ByteBuffer byteBuffer) {
+ return wrap(byteBuffer, byteBuffer.order());
+ }
+
+ /**
+ * Accesses the given ByteBuffer for read-only operations. The returned
Buffer object has
+ * the given byte order, ignoring the byte order of the given ByteBuffer.
+ * @param byteBuffer the given ByteBuffer, must not be null
+ * @param byteOrder the byte order to be used, which may be independent of
the byte order
+ * state of the given ByteBuffer
+ * @return a new Buffer for read-only operations on the given ByteBuffer.
+ */
+ static Buffer wrap(ByteBuffer byteBuffer, ByteOrder byteOrder) {
+ Objects.requireNonNull(byteBuffer, "byteBuffer must not be null");
+ Objects.requireNonNull(byteOrder, "byteOrder must not be null");
+ negativeCheck(byteBuffer.capacity(), "byteBuffer");
+ return BaseWritableBufferImpl.wrapByteBuffer(byteBuffer, true, byteOrder,
null);
+ }
+
+ //DUPLICATES
+ /**
+ * Returns a read-only duplicate view of this Buffer with the same but
independent values of
+ * <i>start</i>, <i>position</i> and <i>end</i>.
+ * <ul>
+ * <li>Returned object's origin = this object's origin</li>
+ * <li>Returned object's <i>start</i> = this object's <i>start</i></li>
+ * <li>Returned object's <i>position</i> = this object's <i>position</i></li>
+ * <li>Returned object's <i>end</i> = this object's <i>end</i></li>
+ * <li>Returned object's <i>capacity</i> = this object'
<i>capacityBytes</i></li>
+ * <li>Returned object's <i>start</i>, <i>position</i> and <i>end</i> are
mutable and
+ * independent of this object's <i>start</i>, <i>position</i> and
<i>end</i></li>
+ * </ul>
+ * @return a read-only duplicate view of this Buffer with the same but
independent values of
+ * <i>start</i>, <i>position</i> and <i>end</i>.
+ */
+ Buffer duplicate();
+
+ /**
+ * Returns a read-only duplicate view of this Buffer with the same but
independent values of
+ * <i>start</i>, <i>position</i> and <i>end</i>, but with the specified
byteOrder.
+ * <ul>
+ * <li>Returned object's origin = this object's origin</li>
+ * <li>Returned object's <i>start</i> = this object's <i>start</i></li>
+ * <li>Returned object's <i>position</i> = this object's <i>position</i></li>
+ * <li>Returned object's <i>end</i> = this object's <i>end</i></li>
+ * <li>Returned object's <i>capacity</i> = this object'
<i>capacityBytes</i></li>
+ * <li>Returned object's <i>start</i>, <i>position</i> and <i>end</i> are
mutable and
+ * independent of this object's <i>start</i>, <i>position</i> and
<i>end</i></li>
+ * </ul>
+ * @param byteOrder the given <i>ByteOrder</i>.
+ * @return a read-only duplicate view of this Buffer with the same but
independent values of
+ * <i>start</i>, <i>position</i> and <i>end</i>.
+ */
+ Buffer duplicate(ByteOrder byteOrder);
+
+ //NO MAP
+
+ //REGIONS
+ /**
+ * A region is a read-only view of this object.
+ * <ul>
+ * <li>Returned object's origin = this object's <i>position</i></li>
+ * <li>Returned object's <i>start</i> = 0</li>
+ * <li>Returned object's <i>position</i> = 0</li>
+ * <li>Returned object's <i>end</i> = this object's (<i>end</i> -
<i>position</i>)</li>
+ * <li>Returned object's <i>capacity</i> = this object's (<i>end</i> -
<i>position</i>)</li>
+ * <li>Returned object's <i>start</i>, <i>position</i> and <i>end</i> are
mutable and
+ * independent of this object's <i>start</i>, <i>position</i> and
<i>end</i></li>
+ * </ul>
+ * @return a new <i>Buffer</i> representing the defined region based on the
current
+ * <i>position</i> and <i>end</i>.
+ */
+ Buffer region();
+
+ /**
+ * A region is a read-only view of this object.
+ * <ul>
+ * <li>Returned object's origin = this objects' origin +
<i>offsetBytes</i></li>
+ * <li>Returned object's <i>start</i> = 0</li>
+ * <li>Returned object's <i>position</i> = 0</li>
+ * <li>Returned object's <i>end</i> = <i>capacityBytes</i></li>
+ * <li>Returned object's <i>capacity</i> = <i>capacityBytes</i></li>
+ * <li>Returned object's <i>start</i>, <i>position</i> and <i>end</i> are
mutable and
+ * independent of this object's <i>start</i>, <i>position</i> and
<i>end</i></li>
+ * <li>Returned object's byte order = <i>byteOrder</i></li>
+ * </ul>
+ *
+ * @param offsetBytes the starting offset with respect to the origin of this
<i>WritableBuffer</i>
+ * @param capacityBytes the <i>capacity</i> of the returned region in bytes
+ * @param byteOrder the given byte order
+ * @return a new <i>Buffer</i> representing the defined writable region
+ * based on the current <i>position</i>, <i>end</i> and byteOrder.
+ */
+ Buffer region(long offsetBytes, long capacityBytes, ByteOrder byteOrder);
+
+ //AS MEMORY
+ /**
+ * Convert this Buffer to a Memory. The current <i>start</i>,
<i>position</i> and <i>end</i>
+ * are ignored.
+ * @return Memory
+ */
+ default Memory asMemory() {
+ return asMemory(getTypeByteOrder());
+ }
+
+ /**
+ * Convert this Buffer to a Memory with the given byte order.
+ * The current <i>start</i>, <i>position</i> and <i>end</i> are ignored.
+ * @param byteOrder the given byte order.
+ * @return Memory
+ */
+ Memory asMemory(ByteOrder byteOrder);
+
+ //NO ACCESS PRIMITIVE HEAP ARRAYS for readOnly
+
+ //PRIMITIVE getX() and getXArray()
+ /**
+ * Gets the boolean value at the current position.
+ * Increments the position by 1.
+ * @return the boolean at the current position
+ */
+ boolean getBoolean();
+
+ /**
+ * Gets the boolean value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the boolean at the given offset
+ */
+ boolean getBoolean(long offsetBytes);
+
+ /**
+ * Gets the boolean array at the current position.
+ * Increments the position by <i>lengthBooleans - dstOffsetBooleans</i>.
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetBooleans offset in array units
+ * @param lengthBooleans number of array units to transfer
+ */
+ void getBooleanArray(boolean[] dstArray, int dstOffsetBooleans, int
lengthBooleans);
+
+ /**
+ * Gets the byte value at the current position.
+ * Increments the position by <i>Byte.BYTES</i>.
+ * @return the byte at the current position
+ */
+ byte getByte();
+
+ /**
+ * Gets the byte value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the byte at the given offset
+ */
+ byte getByte(long offsetBytes);
+
+ /**
+ * Gets the byte array at the current position.
+ * Increments the position by <i>Byte.BYTES * (lengthBytes -
dstOffsetBytes)</i>.
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetBytes offset in array units
+ * @param lengthBytes number of array units to transfer
+ */
+ void getByteArray(byte[] dstArray, int dstOffsetBytes, int lengthBytes);
+
+ /**
+ * Gets the char value at the current position.
+ * Increments the position by <i>Character.BYTES</i>.
+ * @return the char at the current position
+ */
+ char getChar();
+
+ /**
+ * Gets the char value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the char at the given offset
+ */
+ char getChar(long offsetBytes);
+
+ /**
+ * Gets the char array at the current position.
+ * Increments the position by <i>Character.BYTES * (lengthChars -
dstOffsetChars)</i>.
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetChars offset in array units
+ * @param lengthChars number of array units to transfer
+ */
+ void getCharArray(char[] dstArray, int dstOffsetChars, int lengthChars);
+
+ /**
+ * Gets the double value at the current position.
+ * Increments the position by <i>Double.BYTES</i>.
+ * @return the double at the current position
+ */
+ double getDouble();
+
+ /**
+ * Gets the double value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the double at the given offset
+ */
+ double getDouble(long offsetBytes);
+
+ /**
+ * Gets the double array at the current position.
+ * Increments the position by <i>Double.BYTES * (lengthDoubles -
dstOffsetDoubles)</i>.
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetDoubles offset in array units
+ * @param lengthDoubles number of array units to transfer
+ */
+ void getDoubleArray(double[] dstArray, int dstOffsetDoubles, int
lengthDoubles);
+
+ /**
+ * Gets the float value at the current position.
+ * Increments the position by <i>Float.BYTES</i>.
+ * @return the float at the current position
+ */
+ float getFloat();
+
+ /**
+ * Gets the float value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the float at the given offset
+ */
+ float getFloat(long offsetBytes);
+
+ /**
+ * Gets the float array at the current position.
+ * Increments the position by <i>Float.BYTES * (lengthFloats -
dstOffsetFloats)</i>.
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetFloats offset in array units
+ * @param lengthFloats number of array units to transfer
+ */
+ void getFloatArray(float[] dstArray, int dstOffsetFloats, int lengthFloats);
+
+ /**
+ * Gets the int value at the current position.
+ * Increments the position by <i>Integer.BYTES</i>.
+ * @return the int at the current position
+ */
+ int getInt();
+
+ /**
+ * Gets the int value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the int at the given offset
+ */
+ int getInt(long offsetBytes);
+
+ /**
+ * Gets the int array at the current position.
+ * Increments the position by <i>Integer.BYTES * (lengthInts -
dstOffsetInts)</i>.
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetInts offset in array units
+ * @param lengthInts number of array units to transfer
+ */
+ void getIntArray(int[] dstArray, int dstOffsetInts, int lengthInts);
+
+ /**
+ * Gets the long value at the current position.
+ * Increments the position by <i>Long.BYTES</i>.
+ * @return the long at the current position
+ */
+ long getLong();
+
+ /**
+ * Gets the long value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the long at the given offset
+ */
+ long getLong(long offsetBytes);
+
+ /**
+ * Gets the long array at the current position.
+ * Increments the position by <i>Long.BYTES * (lengthLongs -
dstOffsetLongs)</i>.
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetLongs offset in array units
+ * @param lengthLongs number of array units to transfer
+ */
+ void getLongArray(long[] dstArray, int dstOffsetLongs, int lengthLongs);
+
+ /**
+ * Gets the short value at the current position.
+ * Increments the position by <i>Short.BYTES</i>.
+ * @return the short at the current position
+ */
+ short getShort();
+
+ /**
+ * Gets the short value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the short at the given offset
+ */
+ short getShort(long offsetBytes);
+
+ /**
+ * Gets the short array at the current position.
+ * Increments the position by <i>Short.BYTES * (lengthShorts -
dstOffsetShorts)</i>.
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetShorts offset in array units
+ * @param lengthShorts number of array units to transfer
+ */
+ void getShortArray(short[] dstArray, int dstOffsetShorts, int lengthShorts);
+
+ //SPECIAL PRIMITIVE READ METHODS: compareTo
+ /**
+ * Compares the bytes of this Buffer to <i>that</i> Buffer.
+ * This uses absolute offsets not the start, position and end.
+ * Returns <i>(this < that) ? (some negative value) : (this > that) ?
(some positive value)
+ * : 0;</i>.
+ * If all bytes are equal up to the shorter of the two lengths, the shorter
length is
+ * considered to be less than the other.
+ * @param thisOffsetBytes the starting offset for <i>this Buffer</i>
+ * @param thisLengthBytes the length of the region to compare from <i>this
Buffer</i>
+ * @param that the other Buffer to compare with
+ * @param thatOffsetBytes the starting offset for <i>that Buffer</i>
+ * @param thatLengthBytes the length of the region to compare from <i>that
Buffer</i>
+ * @return <i>(this < that) ? (some negative value) : (this > that) ?
(some positive value)
+ * : 0;</i>
+ */
+ int compareTo(long thisOffsetBytes, long thisLengthBytes, Buffer that,
+ long thatOffsetBytes, long thatLengthBytes);
+
+}
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Buffer.java
------------------------------------------------------------------------------
svn:executable = *
Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/DefaultMemoryRequestServer.java
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/DefaultMemoryRequestServer.java
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/DefaultMemoryRequestServer.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,92 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datasketches.memory;
+
+/**
+ * This is a simple implementation of the MemoryRequestServer that creates
space on the Java heap
+ * for the requesting application. This capability is only available for
direct, off-heap
+ * allocated memory.
+ *
+ * <p>Using this default implementation could be something like the following:
+ *
+ * <blockquote><pre>
+ * class OffHeap {
+ * WritableMemory mem;
+ * MemoryRequestServer memReqSvr = null;
+ *
+ * void add(Object something) {
+ *
+ * if (outOfSpace) { // determine if out-of-space
+ * long spaceNeeded = ...
+ *
+ * //Acquire the MemoryRequestServer from the direct Memory the first
time.
+ * //Once acquired, this can be reused if more memory is needed later.
+ * //This is required for the default implementation because it returns
memory on heap
+ * // and on-heap memory does not carry a reference to the
MemoryRequestServer.
+ * memReqSvr = (memReqSvr == null) ? mem.getMemoryRequestServer() :
memReqSvr;
+ *
+ * //Request bigger memory
+ * WritableMemory newMem = memReqSvr.request(mem, spaceNeeded);
+ *
+ * //Copy your data from the current memory to the new one and resize
+ * moveAndResize(mem, newMem);
+ *
+ * //You are done with the old memory, so request close.
+ * //Note that it is up to the owner of the WritableHandle whether or
not to
+ * // actually close the resource.
+ * memReqSvr.requestClose(mem, newMem);
+ *
+ * mem = newMem; //update your reference to memory
+ * }
+ *
+ * //continue with the add process
+ * }
+ * }
+ * </pre></blockquote>
+ *
+ *
+ * @author Lee Rhodes
+ */
+public final class DefaultMemoryRequestServer implements MemoryRequestServer {
+
+ /**
+ * {@inheritDoc}
+ *
+ * <p>By default this allocates new memory requests on the Java heap.
+ */
+ @Override
+ public WritableMemory request(final WritableMemory currentWritableMemory,
final long capacityBytes) {
+ final WritableMemory wmem = WritableMemory.allocate((int)capacityBytes,
currentWritableMemory.getTypeByteOrder());
+ return wmem;
+ }
+
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This method does nothing in this default implementation because it is
application specific.
+ * This method must be overridden to explicitly close if desired.
+ * Otherwise, the AutoCloseable will eventually close the resource.
+ */
+ @Override
+ public void requestClose(final WritableMemory memToRelease, final
WritableMemory newMemory) {
+ //do nothing
+ }
+
+}
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/DefaultMemoryRequestServer.java
------------------------------------------------------------------------------
svn:executable = *
Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Handle.java
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Handle.java
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Handle.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,59 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datasketches.memory;
+
+/**
+ * A handle for read-only Memory resource.
+ *
+ * <p>The purpose of a Handle is to
+ * <ul><li>Provide a <i>strong reference</i> to an external
<i>resource</i>.</li>
+ * <li>Extend <i>AutoCloseable</i>, which provides a means to close the
resource.</li>
+ * <li>Provide other capabilites unique to a particular resource.</li>
+ * </ul>
+ *
+ * <p>Maintaining strong references to external resources is critical to avoid
accidental
+ * <i>use-after-free</i> scenarios, where the Garbage Collector will
automatically close an external
+ * resource if there are no remaining strong references to it. One very common
mistake, is to allow
+ * a newly created Handle to fall out-of-scope from the block where it was
created, such as from a
+ * try-with-resources statement. The Garbage Collector will eventually close
the Handle referent
+ * resource.</p>
+ *
+ * <p>Another <i>use-after-free</i> scenario is where a thread or agent, with
access to the
+ * Handle, prematurely closes a resource, when another part of the program is
still using that
+ * same resource. Avoiding this scenario requires careful planning and
design.</p>
+ *
+ * <p>The design philosophy here is that whatever process created the external
resource has the
+ * responsibility to <i>close()</i> that resource when it is no longer needed.
This responsibility
+ * can be delegated, by passing the appropriate Handle to the delegatee. In
principle, however, at
+ * any one time there should be only one agent holding the Handle and
responsible for closing the
+ * resource.</p>
+ *
+ * @author Lee Rhodes
+ * @author Roman Leventov
+ */
+public interface Handle extends AutoCloseable {
+
+ /**
+ * Gets a Memory
+ * @return a Memory
+ */
+ Memory get();
+
+}
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Handle.java
------------------------------------------------------------------------------
svn:executable = *
Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Map.java
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Map.java
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Map.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,46 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datasketches.memory;
+
+/**
+ * Read only interface for a memory mapped file
+ *
+ * @author Roman Leventov
+ * @author Lee Rhodes
+ * @author Praveenkumar Venkatesan
+ */
+public interface Map extends AutoCloseable {
+
+ /**
+ * @see <a
href="https://docs.oracle.com/javase/8/docs/api/java/nio/MappedByteBuffer.html#load--";>
+ * java/nio/MappedByteBuffer.load</a>
+ */
+ void load();
+
+ /**
+ * @return true if loaded
+ *
+ * @see <a href=
+ *
"https://docs.oracle.com/javase/8/docs/api/java/nio/MappedByteBuffer.html#isLoaded--";>
java
+ * /nio/MappedByteBuffer.isLoaded</a>
+ */
+ boolean isLoaded();
+
+}
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Map.java
------------------------------------------------------------------------------
svn:executable = *
Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MapHandle.java
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MapHandle.java
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MapHandle.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datasketches.memory;
+
+/**
+ * A Handle for a memory-mapped, read-only file resource. This
+ * joins a Read-only Handle with an AutoCloseable Map resource.
+ * Please read Javadocs for {@link Handle}.
+ *
+ * @author Lee Rhodes
+ * @author Roman Leventov
+ */
+public interface MapHandle extends Map, Handle { }
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MapHandle.java
------------------------------------------------------------------------------
svn:executable = *
Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Memory.java
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Memory.java
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Memory.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,488 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datasketches.memory;
+
+import static org.apache.datasketches.memory.internal.Util.negativeCheck;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+import java.nio.channels.WritableByteChannel;
+import java.util.Objects;
+
+import org.apache.datasketches.memory.internal.BaseWritableMemoryImpl;
+import org.apache.datasketches.memory.internal.Prim;
+import org.apache.datasketches.memory.internal.UnsafeUtil;
+
+/**
+ * Defines the read-only API for offset access to a resource.
+ *
+ * @author Lee Rhodes
+ */
+public interface Memory extends BaseState {
+
+ //BYTE BUFFER
+
+ /**
+ * Accesses the given <i>ByteBuffer</i> for read-only operations. The
returned <i>Memory</i> object has
+ * the same byte order, as the given <i>ByteBuffer</i>.
+ * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null and
with capacity ≥ 0.
+ * @return a new <i>Memory</i> for read-only operations on the given
<i>ByteBuffer</i>.
+ */
+ static Memory wrap(ByteBuffer byteBuffer) {
+ return wrap(byteBuffer, byteBuffer.order());
+ }
+
+ /**
+ * Accesses the given <i>ByteBuffer</i> for read-only operations. The
returned <i>Memory</i> object has
+ * the given byte order, ignoring the byte order of the given
<i>ByteBuffer</i> for future reads and writes.
+ * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null and
with capacity ≥ 0.
+ * @param byteOrder the byte order to be used. It must be non-null.
+ * @return a new <i>Memory</i> for read-only operations on the given
<i>ByteBuffer</i>.
+ */
+ static Memory wrap(ByteBuffer byteBuffer, ByteOrder byteOrder) {
+ Objects.requireNonNull(byteBuffer, "byteBuffer must not be null");
+ Objects.requireNonNull(byteOrder, "byteOrder must not be null");
+ negativeCheck(byteBuffer.capacity(), "byteBuffer");
+ return BaseWritableMemoryImpl.wrapByteBuffer(byteBuffer, true, byteOrder,
null);
+ }
+
+ //MAP
+ /**
+ * Maps the entire given file into native-ordered <i>Memory</i> for read
operations
+ * Calling this method is equivalent to calling
+ * {@link #map(File, long, long, ByteOrder) map(file, 0, file.length(),
ByteOrder.nativeOrder())}.
+ * @param file the given file to map. It must be non-null, length ≥ 0,
and readable.
+ * @return <i>MapHandle</i> for managing the mapped memory.
+ * Please read Javadocs for {@link Handle}.
+ */
+ static MapHandle map(File file) {
+ return map(file, 0, file.length(), ByteOrder.nativeOrder());
+ }
+
+ /**
+ * Maps the specified portion of the given file into <i>Memory</i> for read
operations.
+ * @param file the given file to map. It must be non-null and readable.
+ * @param fileOffsetBytes the position in the given file in bytes. It must
not be negative.
+ * @param capacityBytes the size of the mapped memory. It must not be
negative.
+ * @param byteOrder the byte order to be used for the mapped memory. It must
be non-null.
+ * @return <i>MapHandle</i> for managing the mapped memory.
+ * Please read Javadocs for {@link Handle}.
+ */
+ static MapHandle map(File file, long fileOffsetBytes, long capacityBytes,
ByteOrder byteOrder) {
+ Objects.requireNonNull(file, "file must be non-null.");
+ Objects.requireNonNull(byteOrder, "byteOrder must be non-null.");
+ if (!file.canRead()) { throw new IllegalArgumentException("file must be
readable."); }
+ negativeCheck(fileOffsetBytes, "fileOffsetBytes");
+ negativeCheck(capacityBytes, "capacityBytes");
+ return (MapHandle) BaseWritableMemoryImpl.wrapMap(file, fileOffsetBytes,
capacityBytes, true, byteOrder);
+ }
+
+ //REGIONS
+ /**
+ * A region is a read-only view of this object.
+ * <ul>
+ * <li>Returned object's origin = this object's origin + offsetBytes</li>
+ * <li>Returned object's capacity = capacityBytes</li>
+ * </ul>
+ * @param offsetBytes the starting offset with respect to the origin of this
<i>Memory</i>. It must be ≥ 0.
+ * @param capacityBytes the capacity of the region in bytes. It must be ≥
0.
+ * @return a new <i>Memory</i> representing the defined region based on the
given
+ * offsetBytes and capacityBytes.
+ */
+ default Memory region(long offsetBytes, long capacityBytes) {
+ return region(offsetBytes, capacityBytes, ByteOrder.nativeOrder());
+ }
+
+ /**
+ * A region is a read-only view of this object.
+ * <ul>
+ * <li>Returned object's origin = this object's origin +
<i>offsetBytes</i></li>
+ * <li>Returned object's capacity = <i>capacityBytes</i></li>
+ * <li>Returned object's byte order = <i>byteOrder</i></li>
+ * </ul>
+ * @param offsetBytes the starting offset with respect to the origin of this
Memory. It must be ≥ 0.
+ * @param capacityBytes the capacity of the region in bytes. It must be ≥
0.
+ * @param byteOrder the given byte order. It must be non-null.
+ * @return a new <i>Memory</i> representing the defined region based on the
given
+ * offsetBytes, capacityBytes and byteOrder.
+ */
+ Memory region(long offsetBytes, long capacityBytes, ByteOrder byteOrder);
+
+ //AS BUFFER
+ /**
+ * Returns a new <i>Buffer</i> view of this object.
+ * <ul>
+ * <li>Returned object's origin = this object's origin</li>
+ * <li>Returned object's <i>start</i> = 0</li>
+ * <li>Returned object's <i>position</i> = 0</li>
+ * <li>Returned object's <i>end</i> = this object's capacity</li>
+ * <li>Returned object's <i>capacity</i> = this object's capacity</li>
+ * <li>Returned object's <i>start</i>, <i>position</i> and <i>end</i> are
mutable</li>
+ * </ul>
+ * @return a new <i>Buffer</i>
+ */
+ default Buffer asBuffer() {
+ return asBuffer(ByteOrder.nativeOrder());
+ }
+
+ /**
+ * Returns a new <i>Buffer</i> view of this object, with the given
+ * byte order.
+ * <ul>
+ * <li>Returned object's origin = this object's origin</li>
+ * <li>Returned object's <i>start</i> = 0</li>
+ * <li>Returned object's <i>position</i> = 0</li>
+ * <li>Returned object's <i>end</i> = this object's capacity</li>
+ * <li>Returned object's <i>capacity</i> = this object's capacity</li>
+ * <li>Returned object's <i>start</i>, <i>position</i> and <i>end</i> are
mutable</li>
+ * </ul>
+ * @param byteOrder the given byte order
+ * @return a new <i>Buffer</i> with the given byteOrder.
+ */
+ Buffer asBuffer(ByteOrder byteOrder);
+
+ //ACCESS PRIMITIVE HEAP ARRAYS for readOnly
+ /**
+ * Wraps the given primitive array for read operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new <i>Memory</i> for read operations
+ */
+ static Memory wrap(byte[] array) {
+ Objects.requireNonNull(array, "array must be non-null");
+ return wrap(array, 0, array.length, ByteOrder.nativeOrder());
+ }
+
+ /**
+ * Wraps the given primitive array for read operations with the given byte
order.
+ * @param array the given primitive array.
+ * @param byteOrder the byte order to be used
+ * @return a new <i>Memory</i> for read operations
+ */
+ static Memory wrap(byte[] array, ByteOrder byteOrder) {
+ return wrap(array, 0, array.length, byteOrder);
+ }
+
+ /**
+ * Wraps the given primitive array for read operations with the given byte
order.
+ * @param array the given primitive array.
+ * @param offsetBytes the byte offset into the given array
+ * @param lengthBytes the number of bytes to include from the given array
+ * @param byteOrder the byte order to be used
+ * @return a new <i>Memory</i> for read operations
+ */
+ static Memory wrap(byte[] array, int offsetBytes, int lengthBytes, ByteOrder
byteOrder) {
+ Objects.requireNonNull(array, "array must be non-null");
+ Objects.requireNonNull(byteOrder, "byteOrder must be non-null");
+ negativeCheck(offsetBytes, "offsetBytes");
+ negativeCheck(lengthBytes, "lengthBytes");
+ UnsafeUtil.checkBounds(offsetBytes, lengthBytes, array.length);
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0, lengthBytes, true,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for read operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new <i>Memory</i> for read operations
+ */
+ static Memory wrap(boolean[] array) {
+ Objects.requireNonNull(array, "array must be non-null");
+ final long lengthBytes = array.length << Prim.BOOLEAN.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0, lengthBytes, true,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for read operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new <i>Memory</i> for read operations
+ */
+ static Memory wrap(char[] array) {
+ Objects.requireNonNull(array, "array must be non-null");
+ final long lengthBytes = array.length << Prim.CHAR.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, true,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for read operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new <i>Memory</i> for read operations
+ */
+ static Memory wrap(short[] array) {
+ Objects.requireNonNull(array, "arr must be non-null");
+ final long lengthBytes = array.length << Prim.SHORT.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, true,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for read operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new <i>Memory</i> for read operations
+ */
+ static Memory wrap(int[] array) {
+ Objects.requireNonNull(array, "arr must be non-null");
+ final long lengthBytes = array.length << Prim.INT.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, true,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for read operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new <i>Memory</i> for read operations
+ */
+ static Memory wrap(long[] array) {
+ Objects.requireNonNull(array, "arr must be non-null");
+ final long lengthBytes = array.length << Prim.LONG.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, true,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for read operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new <i>Memory</i> for read operations
+ */
+ static Memory wrap(float[] array) {
+ Objects.requireNonNull(array, "arr must be non-null");
+ final long lengthBytes = array.length << Prim.FLOAT.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, true,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for read operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new <i>Memory</i> for read operations
+ */
+ static Memory wrap(double[] array) {
+ Objects.requireNonNull(array, "arr must be non-null");
+ final long lengthBytes = array.length << Prim.DOUBLE.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, true,
ByteOrder.nativeOrder(), null);
+ }
+
+ //PRIMITIVE getX() and getXArray()
+ /**
+ * Gets the boolean value at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the boolean at the given offset
+ */
+ boolean getBoolean(long offsetBytes);
+
+ /**
+ * Gets the boolean array at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetBooleans offset in array units
+ * @param lengthBooleans number of array units to transfer
+ */
+ void getBooleanArray(long offsetBytes, boolean[] dstArray, int
dstOffsetBooleans, int lengthBooleans);
+
+ /**
+ * Gets the byte value at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the byte at the given offset
+ */
+ byte getByte(long offsetBytes);
+
+ /**
+ * Gets the byte array at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetBytes offset in array units
+ * @param lengthBytes number of array units to transfer
+ */
+ void getByteArray(long offsetBytes, byte[] dstArray, int dstOffsetBytes, int
lengthBytes);
+
+ /**
+ * Gets the char value at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the char at the given offset
+ */
+ char getChar(long offsetBytes);
+
+ /**
+ * Gets the char array at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetChars offset in array units
+ * @param lengthChars number of array units to transfer
+ */
+ void getCharArray(long offsetBytes, char[] dstArray, int dstOffsetChars, int
lengthChars);
+
+ /**
+ * Gets UTF-8 encoded bytes from this Memory, starting at offsetBytes to a
length of
+ * utf8LengthBytes, decodes them into characters and appends them to the
given Appendable.
+ * This is specifically designed to reduce the production of intermediate
objects (garbage),
+ * thus significantly reducing pressure on the JVM Garbage Collector.
+ * @param offsetBytes offset bytes relative to the Memory start
+ * @param utf8LengthBytes the number of encoded UTF-8 bytes to decode. It is
assumed that the
+ * caller has the correct number of utf8 bytes required to decode the number
of characters
+ * to be appended to dst. Characters outside the ASCII range can require 2,
3 or 4 bytes per
+ * character to decode.
+ * @param dst the destination Appendable to append the decoded characters to.
+ * @return the number of characters decoded
+ * @throws IOException if dst.append() throws IOException
+ * @throws Utf8CodingException in case of malformed or illegal UTF-8 input
+ */
+ int getCharsFromUtf8(long offsetBytes, int utf8LengthBytes, Appendable dst)
+ throws IOException, Utf8CodingException;
+
+ /**
+ * Gets UTF-8 encoded bytes from this Memory, starting at offsetBytes to a
length of
+ * utf8LengthBytes, decodes them into characters and appends them to the
given StringBuilder.
+ * This method does *not* reset the length of the destination StringBuilder
before appending
+ * characters to it.
+ * This is specifically designed to reduce the production of intermediate
objects (garbage),
+ * thus significantly reducing pressure on the JVM Garbage Collector.
+ * @param offsetBytes offset bytes relative to the Memory start
+ * @param utf8LengthBytes the number of encoded UTF-8 bytes to decode. It is
assumed that the
+ * caller has the correct number of utf8 bytes required to decode the number
of characters
+ * to be appended to dst. Characters outside the ASCII range can require 2,
3 or 4 bytes per
+ * character to decode.
+ * @param dst the destination StringBuilder to append decoded characters to.
+ * @return the number of characters decoded.
+ * @throws Utf8CodingException in case of malformed or illegal UTF-8 input
+ */
+ int getCharsFromUtf8(long offsetBytes, int utf8LengthBytes, StringBuilder
dst)
+ throws Utf8CodingException;
+
+ /**
+ * Gets the double value at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the double at the given offset
+ */
+ double getDouble(long offsetBytes);
+
+ /**
+ * Gets the double array at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetDoubles offset in array units
+ * @param lengthDoubles number of array units to transfer
+ */
+ void getDoubleArray(long offsetBytes, double[] dstArray, int
dstOffsetDoubles, int lengthDoubles);
+
+ /**
+ * Gets the float value at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the float at the given offset
+ */
+ float getFloat(long offsetBytes);
+
+ /**
+ * Gets the float array at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetFloats offset in array units
+ * @param lengthFloats number of array units to transfer
+ */
+ void getFloatArray(long offsetBytes, float[] dstArray, int dstOffsetFloats,
int lengthFloats);
+
+ /**
+ * Gets the int value at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the int at the given offset
+ */
+ int getInt(long offsetBytes);
+
+ /**
+ * Gets the int array at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetInts offset in array units
+ * @param lengthInts number of array units to transfer
+ */
+ void getIntArray(long offsetBytes, int[] dstArray, int dstOffsetInts, int
lengthInts);
+
+ /**
+ * Gets the long value at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the long at the given offset
+ */
+ long getLong(long offsetBytes);
+
+ /**
+ * Gets the long array at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetLongs offset in array units
+ * @param lengthLongs number of array units to transfer
+ */
+ void getLongArray(long offsetBytes, long[] dstArray, int dstOffsetLongs, int
lengthLongs);
+
+ /**
+ * Gets the short value at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @return the short at the given offset
+ */
+ short getShort(long offsetBytes);
+
+ /**
+ * Gets the short array at the given offset
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param dstArray The preallocated destination array.
+ * @param dstOffsetShorts offset in array units
+ * @param lengthShorts number of array units to transfer
+ */
+ void getShortArray(long offsetBytes, short[] dstArray, int dstOffsetShorts,
int lengthShorts);
+
+ //SPECIAL PRIMITIVE READ METHODS: compareTo, copyTo, writeTo
+ /**
+ * Compares the bytes of this Memory to <i>that</i> Memory.
+ * Returns <i>(this < that) ? (some negative value) : (this > that) ?
(some positive value)
+ * : 0;</i>.
+ * If all bytes are equal up to the shorter of the two lengths, the shorter
length is considered
+ * to be less than the other.
+ * @param thisOffsetBytes the starting offset for <i>this Memory</i>
+ * @param thisLengthBytes the length of the region to compare from <i>this
Memory</i>
+ * @param that the other Memory to compare with
+ * @param thatOffsetBytes the starting offset for <i>that Memory</i>
+ * @param thatLengthBytes the length of the region to compare from <i>that
Memory</i>
+ * @return <i>(this < that) ? (some negative value) : (this > that) ?
(some positive value)
+ * : 0;</i>
+ */
+ int compareTo(long thisOffsetBytes, long thisLengthBytes, Memory that,
+ long thatOffsetBytes, long thatLengthBytes);
+
+ /**
+ * Copies bytes from a source range of this Memory to a destination range of
the given Memory
+ * with the same semantics when copying between overlapping ranges of bytes
as method
+ * {@link java.lang.System#arraycopy(Object, int, Object, int, int)} has.
However, if the source
+ * and the destination ranges are exactly the same, this method throws {@link
+ * IllegalArgumentException}, because it should never be needed in
real-world scenarios and
+ * therefore indicates a bug.
+ * @param srcOffsetBytes the source offset for this Memory
+ * @param destination the destination Memory, which may not be Read-Only.
+ * @param dstOffsetBytes the destination offset
+ * @param lengthBytes the number of bytes to copy
+ */
+ void copyTo(long srcOffsetBytes, WritableMemory destination, long
dstOffsetBytes, long lengthBytes);
+
+ /**
+ * Writes bytes from a source range of this Memory to the given {@code
WritableByteChannel}.
+ * @param offsetBytes the source offset for this Memory
+ * @param lengthBytes the number of bytes to copy
+ * @param out the destination WritableByteChannel
+ * @throws IOException may occur while writing to the WritableByteChannel
+ */
+ void writeTo(long offsetBytes, long lengthBytes, WritableByteChannel out)
+ throws IOException;
+
+}
+
+
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Memory.java
------------------------------------------------------------------------------
svn:executable = *
Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryCloseException.java
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryCloseException.java
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryCloseException.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,49 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datasketches.memory;
+
+/**
+ * Specific RuntimeException for the AutoCloseable.close() method.
+ *
+ * @author Lee Rhodes
+ *
+ */
+public class MemoryCloseException extends MemoryException {
+ private static final long serialVersionUID = 2L;
+
+ /**
+ * The associated resource failed to close.
+ */
+ public MemoryCloseException() {
+ super("The associated resource failed to close.");
+ }
+
+ /**
+ * The associated resource failed to close, with comment
+ *
+ * @param resource the named resource that failed to close, plus other
comments.
+ */
+ public MemoryCloseException(final String resource) {
+ super("The associated resource, " + resource + ", failed to close");
+ }
+
+}
+
+
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryCloseException.java
------------------------------------------------------------------------------
svn:executable = *
Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryException.java
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryException.java
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryException.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datasketches.memory;
+
+/**
+ * Specific RuntimeExceptions for the datasketches-memory component.
+ *
+ * @author Lee Rhodes
+ *
+ */
+public class MemoryException extends RuntimeException {
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Constructs a new runtime exception with the specified detail message. The
cause is not
+ * initialized, and may subsequently be initialized by a call to
+ * Throwable.initCause(java.lang.Throwable).
+ *
+ * @param message the detail message. The detail message is saved for later
retrieval by the
+ * Throwable.getMessage() method.
+ */
+ public MemoryException(final String message) {
+ super(message);
+ }
+}
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryException.java
------------------------------------------------------------------------------
svn:executable = *
Added:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryRequestServer.java
==============================================================================
---
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryRequestServer.java
(added)
+++
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryRequestServer.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,50 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datasketches.memory;
+
+/**
+ * The MemoryRequestServer is a callback interface to provide a means for
direct (off-heap), heap and ByteBuffer
+ * backed resources to request more memory.
+ *
+ * @author Lee Rhodes
+ */
+public interface MemoryRequestServer {
+
+ /**
+ * Request new WritableMemory with the given capacity. The current Writable
Memory will be used to
+ * determine the byte order of the returned WritableMemory and other checks.
+ * @param currentWritableMemory the current writableMemory of the client. It
must be non-null.
+ * @param capacityBytes The capacity being requested. It must be ≥ 0.
+ *
+ * @return new WritableMemory with the given capacity.
+ */
+ WritableMemory request(WritableMemory currentWritableMemory, long
capacityBytes);
+
+ /**
+ * Request close the AutoCloseable resource. This only applies to resources
allocated using
+ * WritableMemory.allocateDirect(...).
+ * This may be ignored depending on the application implementation.
+ * @param memToClose the relevant WritbleMemory to be considered for
closing. It must be non-null.
+ * @param newMemory the newly allocated WritableMemory. It must be non-null.
+ * This is returned from the client to facilitate tracking for the
convenience of the resource owner.
+ */
+ void requestClose(final WritableMemory memToClose, WritableMemory newMemory);
+
+}
Propchange:
dev/datasketches/memory/2.2.0-RC1/apache-datasketches-memory-2.2.0-src/datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryRequestServer.java
------------------------------------------------------------------------------
svn:executable = *
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
