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/MurmurHash3v2.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/MurmurHash3v2.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/MurmurHash3v2.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,359 @@
+/*
+ * 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 java.nio.charset.StandardCharsets.UTF_8;
+import static org.apache.datasketches.memory.internal.UnsafeUtil.unsafe;
+
+/**
+ * <p>The MurmurHash3 is a fast, non-cryptographic, 128-bit hash function that
has
+ * excellent avalanche and 2-way bit independence properties.</p>
+ *
+ * <p>Austin Appleby's C++
+ * <a
href="https://github.com/aappleby/smhasher/blob/master/src/MurmurHash3.cpp";>
+ * MurmurHash3_x64_128(...), final revision 150</a>,
+ * which is in the Public Domain, was the inspiration for this implementation
in Java.</p>
+ *
+ * <p>This implementation of the MurmurHash3 allows hashing of a block of
on-heap Memory defined by an offset
+ * and length. The calling API also allows the user to supply the small output
array of two longs,
+ * so that the entire hash function is static and free of object
allocations.</p>
+ *
+ * <p>This implementation produces exactly the same hash result as the
+ * MurmurHash3 function in datasketches-java given compatible inputs.</p>
+ *
+ * @author Lee Rhodes
+ */
+public final class MurmurHash3v2 {
+ private static final long C1 = 0x87c37b91114253d5L;
+ private static final long C2 = 0x4cf5ad432745937fL;
+
+ //Provided for backward compatibility
+
+ /**
+ * Returns a 128-bit hash of the input.
+ * Provided for compatibility with older version of MurmurHash3,
+ * but empty or null input now throws IllegalArgumentException.
+ * @param in long array
+ * @param seed A long valued seed.
+ * @return the hash
+ */
+ public static long[] hash(final long[] in, final long seed) {
+ if ((in == null) || (in.length == 0)) {
+ throw new IllegalArgumentException("Input in is empty or null.");
+ }
+ return hash(Memory.wrap(in), 0L, in.length << 3, seed, new long[2]);
+ }
+
+ /**
+ * Returns a 128-bit hash of the input.
+ * Provided for compatibility with older version of MurmurHash3,
+ * but empty or null input now throws IllegalArgumentException.
+ * @param in int array
+ * @param seed A long valued seed.
+ * @return the hash
+ */
+ public static long[] hash(final int[] in, final long seed) {
+ if ((in == null) || (in.length == 0)) {
+ throw new IllegalArgumentException("Input in is empty or null.");
+ }
+ return hash(Memory.wrap(in), 0L, in.length << 2, seed, new long[2]);
+ }
+
+ /**
+ * Returns a 128-bit hash of the input.
+ * Provided for compatibility with older version of MurmurHash3,
+ * but empty or null input now throws IllegalArgumentException.
+ * @param in char array
+ * @param seed A long valued seed.
+ * @return the hash
+ */
+ public static long[] hash(final char[] in, final long seed) {
+ if ((in == null) || (in.length == 0)) {
+ throw new IllegalArgumentException("Input in is empty or null.");
+ }
+ return hash(Memory.wrap(in), 0L, in.length << 1, seed, new long[2]);
+ }
+
+ /**
+ * Returns a 128-bit hash of the input.
+ * Provided for compatibility with older version of MurmurHash3,
+ * but empty or null input now throws IllegalArgumentException.
+ * @param in byte array
+ * @param seed A long valued seed.
+ * @return the hash
+ */
+ public static long[] hash(final byte[] in, final long seed) {
+ if ((in == null) || (in.length == 0)) {
+ throw new IllegalArgumentException("Input in is empty or null.");
+ }
+ return hash(Memory.wrap(in), 0L, in.length, seed, new long[2]);
+ }
+
+ //Single primitive inputs
+
+ /**
+ * Returns a 128-bit hash of the input.
+ * Note the entropy of the resulting hash cannot be more than 64 bits.
+ * @param in a long
+ * @param seed A long valued seed.
+ * @param hashOut A long array of size 2
+ * @return the hash
+ */
+ public static long[] hash(final long in, final long seed, final long[]
hashOut) {
+ final long h1 = seed ^ mixK1(in);
+ final long h2 = seed;
+ return finalMix128(h1, h2, 8, hashOut);
+ }
+
+ /**
+ * Returns a 128-bit hash of the input.
+ * Note the entropy of the resulting hash cannot be more than 64 bits.
+ * @param in a double
+ * @param seed A long valued seed.
+ * @param hashOut A long array of size 2
+ * @return the hash
+ */
+ public static long[] hash(final double in, final long seed, final long[]
hashOut) {
+ final double d = (in == 0.0) ? 0.0 : in; // canonicalize -0.0, 0.0
+ final long k1 = Double.doubleToLongBits(d); // canonicalize all NaN forms
+ final long h1 = seed ^ mixK1(k1);
+ final long h2 = seed;
+ return finalMix128(h1, h2, 8, hashOut);
+ }
+
+ /**
+ * Returns a 128-bit hash of the input.
+ * An empty or null input throws IllegalArgumentException.
+ * @param in a String
+ * @param seed A long valued seed.
+ * @param hashOut A long array of size 2
+ * @return the hash
+ */
+ public static long[] hash(final String in, final long seed, final long[]
hashOut) {
+ if ((in == null) || (in.length() == 0)) {
+ throw new IllegalArgumentException("Input in is empty or null.");
+ }
+ final byte[] byteArr = in.getBytes(UTF_8);
+ return hash(Memory.wrap(byteArr), 0L, byteArr.length, seed, hashOut);
+ }
+
+ //The main API call
+
+ /**
+ * Returns a 128-bit hash of the input as a long array of size 2.
+ *
+ * @param mem The input on-heap Memory. Must be non-null and non-empty,
+ * otherwise throws IllegalArgumentException.
+ * @param offsetBytes the starting point within Memory.
+ * @param lengthBytes the total number of bytes to be hashed.
+ * @param seed A long valued seed.
+ * @param hashOut the size 2 long array for the resulting 128-bit hash
+ * @return the hash.
+ */
+ @SuppressWarnings("restriction")
+ public static long[] hash(final Memory mem, final long offsetBytes, final
long lengthBytes,
+ final long seed, final long[] hashOut) {
+ if ((mem == null) || (mem.getCapacity() == 0L)) {
+ throw new IllegalArgumentException("Input mem is empty or null.");
+ }
+ final Object uObj = ((WritableMemory) mem).getArray();
+ if (uObj == null) {
+ throw new IllegalArgumentException("The backing resource of input mem is
not on-heap.");
+ }
+ long cumOff = mem.getCumulativeOffset() + offsetBytes;
+
+ long h1 = seed;
+ long h2 = seed;
+ long rem = lengthBytes;
+
+ // Process the 128-bit blocks (the body) into the hash
+ while (rem >= 16L) {
+ final long k1 = unsafe.getLong(uObj, cumOff); //0, 16, 32, ...
+ final long k2 = unsafe.getLong(uObj, cumOff + 8); //8, 24, 40, ...
+ cumOff += 16L;
+ rem -= 16L;
+
+ h1 ^= mixK1(k1);
+ h1 = Long.rotateLeft(h1, 27);
+ h1 += h2;
+ h1 = (h1 * 5) + 0x52dce729L;
+
+ h2 ^= mixK2(k2);
+ h2 = Long.rotateLeft(h2, 31);
+ h2 += h1;
+ h2 = (h2 * 5) + 0x38495ab5L;
+ }
+
+ // Get the tail (if any): 1 to 15 bytes
+ if (rem > 0L) {
+ long k1 = 0;
+ long k2 = 0;
+ switch ((int) rem) {
+ case 15: {
+ k2 ^= (unsafe.getByte(uObj, cumOff + 14) & 0xFFL) << 48;
+ }
+ //$FALL-THROUGH$
+ case 14: {
+ k2 ^= (unsafe.getShort(uObj, cumOff + 12) & 0xFFFFL) << 32;
+ k2 ^= (unsafe.getInt(uObj, cumOff + 8) & 0xFFFFFFFFL);
+ k1 = unsafe.getLong(uObj, cumOff);
+ break;
+ }
+
+ case 13: {
+ k2 ^= (unsafe.getByte(uObj, cumOff + 12) & 0xFFL) << 32;
+ }
+ //$FALL-THROUGH$
+ case 12: {
+ k2 ^= (unsafe.getInt(uObj, cumOff + 8) & 0xFFFFFFFFL);
+ k1 = unsafe.getLong(uObj, cumOff);
+ break;
+ }
+
+ case 11: {
+ k2 ^= (unsafe.getByte(uObj, cumOff + 10) & 0xFFL) << 16;
+ }
+ //$FALL-THROUGH$
+ case 10: {
+ k2 ^= (unsafe.getShort(uObj, cumOff + 8) & 0xFFFFL);
+ k1 = unsafe.getLong(uObj, cumOff);
+ break;
+ }
+
+ case 9: {
+ k2 ^= (unsafe.getByte(uObj, cumOff + 8) & 0xFFL);
+ }
+ //$FALL-THROUGH$
+ case 8: {
+ k1 = unsafe.getLong(uObj, cumOff);
+ break;
+ }
+
+ case 7: {
+ k1 ^= (unsafe.getByte(uObj, cumOff + 6) & 0xFFL) << 48;
+ }
+ //$FALL-THROUGH$
+ case 6: {
+ k1 ^= (unsafe.getShort(uObj, cumOff + 4) & 0xFFFFL) << 32;
+ k1 ^= (unsafe.getInt(uObj, cumOff) & 0xFFFFFFFFL);
+ break;
+ }
+
+ case 5: {
+ k1 ^= (unsafe.getByte(uObj, cumOff + 4) & 0xFFL) << 32;
+ }
+ //$FALL-THROUGH$
+ case 4: {
+ k1 ^= (unsafe.getInt(uObj, cumOff) & 0xFFFFFFFFL);
+ break;
+ }
+
+ case 3: {
+ k1 ^= (unsafe.getByte(uObj, cumOff + 2) & 0xFFL) << 16;
+ }
+ //$FALL-THROUGH$
+ case 2: {
+ k1 ^= (unsafe.getShort(uObj, cumOff) & 0xFFFFL);
+ break;
+ }
+
+ case 1: {
+ k1 ^= (unsafe.getByte(uObj, cumOff) & 0xFFL);
+ break;
+ }
+ //default: break; //can't happen
+ }
+
+ h1 ^= mixK1(k1);
+ h2 ^= mixK2(k2);
+ }
+ return finalMix128(h1, h2, lengthBytes, hashOut);
+ }
+
+ //--Helper methods----------------------------------------------------
+
+ /**
+ * Self mix of k1
+ *
+ * @param k1 input argument
+ * @return mix
+ */
+ private static long mixK1(long k1) {
+ k1 *= C1;
+ k1 = Long.rotateLeft(k1, 31);
+ k1 *= C2;
+ return k1;
+ }
+
+ /**
+ * Self mix of k2
+ *
+ * @param k2 input argument
+ * @return mix
+ */
+ private static long mixK2(long k2) {
+ k2 *= C2;
+ k2 = Long.rotateLeft(k2, 33);
+ k2 *= C1;
+ return k2;
+ }
+
+ /**
+ * Final self mix of h*.
+ *
+ * @param h input to final mix
+ * @return mix
+ */
+ private static long finalMix64(long h) {
+ h ^= h >>> 33;
+ h *= 0xff51afd7ed558ccdL;
+ h ^= h >>> 33;
+ h *= 0xc4ceb9fe1a85ec53L;
+ h ^= h >>> 33;
+ return h;
+ }
+
+ /**
+ * Finalization: Add the length into the hash and mix
+ * @param h1 intermediate hash
+ * @param h2 intermediate hash
+ * @param lengthBytes the length in bytes
+ * @param hashOut the output array of 2 longs
+ * @return hashOut
+ */
+ private static long[] finalMix128(long h1, long h2, final long lengthBytes,
final long[] hashOut) {
+ h1 ^= lengthBytes;
+ h2 ^= lengthBytes;
+
+ h1 += h2;
+ h2 += h1;
+
+ h1 = finalMix64(h1);
+ h2 = finalMix64(h2);
+
+ h1 += h2;
+ h2 += h1;
+
+ hashOut[0] = h1;
+ hashOut[1] = h2;
+ return hashOut;
+ }
+
+}
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/MurmurHash3v2.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/ReadOnlyException.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/ReadOnlyException.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/ReadOnlyException.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,38 @@
+/*
+ * 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 exception thrown when attempting to write into a read-only Resource.
+ *
+ * @author Praveenkumar Venkatesan
+ */
+public class ReadOnlyException extends MemoryException {
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Read Only Exception
+ * @param message the error message
+ */
+ public ReadOnlyException(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/ReadOnlyException.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/Utf8CodingException.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/Utf8CodingException.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/Utf8CodingException.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,129 @@
+/*
+ * 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 exception will be thrown for errors encountered during either the
encoding of characters
+ * to Utf8 bytes, or the decoding of Utf8 bytes to characters.
+ *
+ * @author Lee Rhodes
+ */
+public final class Utf8CodingException extends RuntimeException {
+
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * A coding exception occured processing UTF_8
+ * @param message the error message
+ */
+ public Utf8CodingException(final String message) {
+ super(message);
+ }
+
+ //DECODE
+ /**
+ * Exception for a short UTF_8 Decode Byte Sequence
+ * @param leadByte the given lead byte
+ * @param address the given address
+ * @param limit the given limit
+ * @param required what is required
+ * @return the exception
+ */
+ public static Utf8CodingException shortUtf8DecodeByteSequence(final byte
leadByte, final long address,
+ final long limit, final int required) {
+ final String s = "Too few Utf8 decode bytes remaining given the leading
byte. "
+ + shortSeq(leadByte, address, limit, required);
+ return new Utf8CodingException(s);
+ }
+
+ /**
+ * Exception for an illegal UTF_8 Decode Byte Sequence
+ * @param bytes the illegal byte sequence
+ * @return the exception.
+ */
+ public static Utf8CodingException illegalUtf8DecodeByteSequence(final byte[]
bytes) {
+ final String s = "Invalid UTF-8 decode byte sequence: " + badBytes(bytes);
+ return new Utf8CodingException(s);
+ }
+
+ //ENCODE
+ /**
+ * Exception for out-of-memory
+ * @return the exception
+ */
+ public static Utf8CodingException outOfMemory() {
+ final String s = "Out-of-memory with characters remaining to be encoded";
+ return new Utf8CodingException(s);
+ }
+
+ /**
+ * Exception for an unpaired surrogate
+ * @param c The last char to encode is an unpaired surrogate
+ * @return the exception plus the unpaired surrogate character
+ */
+ public static Utf8CodingException unpairedSurrogate(final char c) {
+ final String s = "Last char to encode is an unpaired surrogate: 0X"
+ + Integer.toHexString(c & 0XFFFF);
+ return new Utf8CodingException(s);
+ }
+
+ /**
+ * Exception for a short UTF_8 encode byte length
+ * @param remaining The surrogate pair that is short
+ * @return the exception plus the surrogate pair that is short
+ */
+ public static Utf8CodingException shortUtf8EncodeByteLength(final int
remaining) {
+ final String s = "Too few MemoryImpl bytes to encode a surrogate pair: " +
remaining;
+ return new Utf8CodingException(s);
+ }
+
+ /**
+ * Exception for an illegal surrogate pair
+ * @param c1 the first character of the pair
+ * @param c2 the second character of the pair
+ * @return the exception plus the illegal pair
+ */
+ public static Utf8CodingException illegalSurrogatePair(final char c1, final
char c2) {
+ final String s = "Illegal Surrogate Pair: Char 1: " +
Integer.toHexString(c1 & 0XFFFF)
+ + ", Char 2: " + Integer.toHexString(c2 & 0XFFFF);
+ return new Utf8CodingException(s);
+ }
+
+ private static String shortSeq(final byte leadByte, final long address,
final long limit,
+ final int required) {
+ final String s = "Lead byte: " + Integer.toHexString(leadByte & 0xFF)
+ + ", offset: 0X" + Long.toHexString(address)
+ + ", limit: 0X" + Long.toHexString(limit)
+ + ", required: " + required;
+ return s;
+ }
+
+ private static String badBytes(final byte[] bytes) {
+ final StringBuilder sb = new StringBuilder();
+ final int len = bytes.length;
+ int i = 0;
+ for (; i < (len - 1); i++) {
+ sb.append("0X" + Integer.toHexString(bytes[i] & 0XFF)).append(", ");
+ }
+ sb.append("0X" + Integer.toHexString(bytes[i] & 0XFF));
+ return sb.toString();
+ }
+
+}
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/Utf8CodingException.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/WritableBuffer.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/WritableBuffer.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/WritableBuffer.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,410 @@
+/*
+ * 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 java.util.Objects;
+
+import org.apache.datasketches.memory.internal.BaseWritableBufferImpl;
+import org.apache.datasketches.memory.internal.Util;
+
+/**
+ * Defines the writable API for relative positional access to a resource
+ *
+ * @author Lee Rhodes
+ */
+public interface WritableBuffer extends Buffer {
+
+ //BYTE BUFFER
+ /**
+ * Accesses the given <i>ByteBuffer</i> for write operations. The returned
<i>WritableBuffer</i> object has
+ * the same byte order, as the given <i>ByteBuffer</i>.
+ * @param byteBuf the given ByteBuffer. It must be non-null and with
capacity ≥ 0.
+ * @return a new <i>WritableBuffer</i> for write operations on the given
<i>ByteBuffer</i>.
+ */
+ static WritableBuffer writableWrap(ByteBuffer byteBuf) {
+ return writableWrap(byteBuf, byteBuf.order(), defaultMemReqSvr);
+ }
+
+ /**
+ * Accesses the given <i>ByteBuffer</i> for write operations. The returned
<i>WritableBuffer</i> object has
+ * the given byte order, ignoring the byte order of the given
<i>ByteBuffer</i> for future writes and following reads.
+ * However, this does not change the byte order of data already in the
<i>ByteBuffer</i>.
+ * @param byteBuf the given ByteBuffer. It must be non-null and with
capacity ≥ 0.
+ * @param byteOrder the byte order to be used.
+ * @param memReqSvr A user-specified <i>MemoryRequestServer</i>, which must
not be null.
+ * This is a callback mechanism for a user client to request a larger
<i>WritableBuffer</i>.
+ * @return a new <i>WritableBuffer</i> for write operations on the given
<i>ByteBuffer</i>.
+ */
+ static WritableBuffer writableWrap(ByteBuffer byteBuf, ByteOrder byteOrder,
MemoryRequestServer memReqSvr) {
+ Objects.requireNonNull(byteBuf, "ByteBuffer 'byteBuf' must not be null");
+ Objects.requireNonNull(byteOrder, "ByteOrder 'byteOrder' must not be
null");
+ Util.negativeCheck(byteBuf.capacity(), "byteBuf.capacity");
+ if (byteBuf.isReadOnly()) {
+ throw new ReadOnlyException("Cannot create a WritableBuffer from a
ReadOnly ByteBuffer.");
+ }
+ return BaseWritableBufferImpl.wrapByteBuffer(byteBuf, false, byteOrder,
memReqSvr);
+ }
+
+ // NO MAP
+ // NO ALLOCATE DIRECT
+
+ //DUPLICATES
+ /**
+ * Returns a duplicate writable 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 duplicate writable view of this Buffer with the same but
independent values of
+ * <i>start</i>, <i>position</i> and <i>end</i>.
+ */
+ WritableBuffer writableDuplicate();
+
+ /**
+ * Returns a duplicate writable 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 duplicate writable view of this Buffer with the same but
independent values of
+ * <i>start</i>, <i>position</i> and <i>end</i>.
+ */
+ WritableBuffer writableDuplicate(ByteOrder byteOrder);
+
+ //REGIONS
+ /**
+ * A writable region is a writable 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>WritableBuffer</i> representing the defined writable
region.
+ */
+ WritableBuffer writableRegion();
+
+ /**
+ * A writable region is a writable 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>
+ *
+ * <p><b>Note: </b><i>asWritableMemory()</i> and <i>asMemory()</i>
+ * will return the originating <i>Memory</i> byte order.</p>
+ * @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>WritableBuffer</i> representing the defined writable
region
+ * with the given offsetBytes, capacityBytes and byte order.
+ */
+ WritableBuffer writableRegion(long offsetBytes, long capacityBytes,
+ ByteOrder byteOrder);
+
+ //AS WRITABLE MEMORY
+ /**
+ * Convert this WritableBuffer to a WritableMemory.
+ * If this object's capacity is zero, the returned object is effectively
immutable and
+ * the backing storage and byte order are unspecified.
+ * @return WritableMemory
+ */
+ default WritableMemory asWritableMemory() {
+ return asWritableMemory(ByteOrder.nativeOrder());
+ }
+
+ /**
+ * Convert this WritableBuffer to a WritableMemory with the given byte order.
+ * If this object's capacity is zero, the returned object is effectively
immutable and
+ * the backing storage and byte order are unspecified.
+ * @param byteOrder the byte order to be used.
+ * @return WritableMemory
+ */
+ WritableMemory asWritableMemory(ByteOrder byteOrder);
+
+ //NO ALLOCATE HEAP VIA AUTOMATIC BYTE ARRAY
+
+ //NO ACCESS PRIMITIVE HEAP ARRAYS for WRITE
+
+ //PRIMITIVE putX() and putXArray()
+ /**
+ * Puts the boolean value at the current position.
+ * Increments the position by 1.
+ * @param value the value to put
+ */
+ void putBoolean(boolean value);
+
+ /**
+ * Puts the boolean value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start.
+ * @param value the value to put
+ */
+ void putBoolean(long offsetBytes, boolean value);
+
+ /**
+ * Puts the boolean array at the current position.
+ * Increments the position by <i>lengthBooleans - srcOffsetBooleans</i>.
+ * @param srcArray The source array.
+ * @param srcOffsetBooleans offset in array units
+ * @param lengthBooleans number of array units to transfer
+ */
+ void putBooleanArray(boolean[] srcArray, int srcOffsetBooleans,
+ int lengthBooleans);
+
+ /**
+ * Puts the byte value at the current position.
+ * Increments the position by <i>Byte.BYTES</i>.
+ * @param value the value to put
+ */
+ void putByte(byte value);
+
+ /**
+ * Puts the byte value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putByte(long offsetBytes, byte value);
+
+ /**
+ * Puts the byte array at the current position.
+ * Increments the position by <i>Byte.BYTES * (lengthBytes -
srcOffsetBytes)</i>.
+ * @param srcArray The source array.
+ * @param srcOffsetBytes offset in array units
+ * @param lengthBytes number of array units to transfer
+ */
+ void putByteArray(byte[] srcArray, int srcOffsetBytes, int lengthBytes);
+
+ /**
+ * Puts the char value at the current position.
+ * Increments the position by <i>Character.BYTES</i>.
+ * @param value the value to put
+ */
+ void putChar(char value);
+
+ /**
+ * Puts the char value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putChar(long offsetBytes, char value);
+
+ /**
+ * Puts the char array at the current position.
+ * Increments the position by <i>Character.BYTES * (lengthChars -
srcOffsetChars)</i>.
+ * @param srcArray The source array.
+ * @param srcOffsetChars offset in array units
+ * @param lengthChars number of array units to transfer
+ */
+ void putCharArray(char[] srcArray, int srcOffsetChars, int lengthChars);
+
+ /**
+ * Puts the double value at the current position.
+ * Increments the position by <i>Double.BYTES</i>.
+ * @param value the value to put
+ */
+ void putDouble(double value);
+
+ /**
+ * Puts the double value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putDouble(long offsetBytes, double value);
+
+ /**
+ * Puts the double array at the current position.
+ * Increments the position by <i>Double.BYTES * (lengthDoubles -
srcOffsetDoubles)</i>.
+ * @param srcArray The source array.
+ * @param srcOffsetDoubles offset in array units
+ * @param lengthDoubles number of array units to transfer
+ */
+ void putDoubleArray(double[] srcArray, int srcOffsetDoubles, int
lengthDoubles);
+
+ /**
+ * Puts the float value at the current position.
+ * Increments the position by <i>Float.BYTES</i>.
+ * @param value the value to put
+ */
+ void putFloat(float value);
+
+ /**
+ * Puts the float value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putFloat(long offsetBytes, float value);
+
+ /**
+ * Puts the float array at the current position.
+ * Increments the position by <i>Float.BYTES * (lengthFloats -
srcOffsetFloats)</i>.
+ * @param srcArray The source array.
+ * @param srcOffsetFloats offset in array units
+ * @param lengthFloats number of array units to transfer
+ */
+ void putFloatArray(float[] srcArray, int srcOffsetFloats, int lengthFloats);
+
+ /**
+ * Puts the int value at the current position.
+ * Increments the position by <i>Integer.BYTES</i>.
+ * @param value the value to put
+ */
+ void putInt(int value);
+
+ /**
+ * Puts the int value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putInt(long offsetBytes, int value);
+
+ /**
+ * Puts the int array at the current position.
+ * Increments the position by <i>Integer.BYTES * (lengthInts -
srcOffsetInts)</i>.
+ * @param srcArray The source array.
+ * @param srcOffsetInts offset in array units
+ * @param lengthInts number of array units to transfer
+ */
+ void putIntArray(int[] srcArray, int srcOffsetInts, int lengthInts);
+
+ /**
+ * Puts the long value at the current position.
+ * Increments the position by <i>Long.BYTES</i>.
+ * @param value the value to put
+ */
+ void putLong(long value);
+
+ /**
+ * Puts the long value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putLong(long offsetBytes, long value);
+
+ /**
+ * Puts the long array at the current position.
+ * Increments the position by <i>Long.BYTES * (lengthLongs -
srcOffsetLongs)</i>.
+ * @param srcArray The source array.
+ * @param srcOffsetLongs offset in array units
+ * @param lengthLongs number of array units to transfer
+ */
+ void putLongArray(long[] srcArray, int srcOffsetLongs, int lengthLongs);
+
+ /**
+ * Puts the short value at the current position.
+ * Increments the position by <i>Short.BYTES</i>.
+ * @param value the value to put
+ */
+ void putShort(short value);
+
+ /**
+ * Puts the short value at the given offset.
+ * This does not change the position.
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putShort(long offsetBytes, short value);
+
+ /**
+ * Puts the short array at the current position.
+ * Increments the position by <i>Short.BYTES * (lengthShorts -
srcOffsetShorts)</i>.
+ * @param srcArray The source array.
+ * @param srcOffsetShorts offset in array units
+ * @param lengthShorts number of array units to transfer
+ */
+ void putShortArray(short[] srcArray, int srcOffsetShorts, int lengthShorts);
+
+ // NO ATOMIC METHODS
+
+ //OTHER WRITE METHODS
+ /**
+ * Returns the primitive backing array, otherwise null.
+ * @return the primitive backing array, otherwise null.
+ */
+ Object getArray();
+
+ /**
+ * Clears all bytes of this Buffer from position to end to zero. The
position will be set to end.
+ */
+ void clear();
+
+ //NO clearBits(...)
+
+ /**
+ * Fills this Buffer from position to end with the given byte value.
+ * The position will be set to <i>end</i>.
+ * @param value the given byte value
+ */
+ void fill(byte value);
+
+ //NO fill(offsetBytes, lengthBytes, value)
+
+ //NO setBits(...)
+
+ //OTHER WRITABLE API METHODS
+ /**
+ * WritableBuffer enables this for ByteBuffer backed resources. However, the
object returned is in the form of
+ * a WritableMemory. To convert to WritableBuffer use asWritableBuffer(). To
enable for Heap and Direct Memory
+ * resources, use the WritableMemory to configure and then call
asWritableBuffer().
+ * Map backed resources will always return null.
+ * Gets the MemoryRequestServer object, if set, for the above resources to
request additional memory.
+ * The user must customize the actions of the MemoryRequestServer by
+ * implementing the MemoryRequestServer interface and set using the
following method:
+ * <ul>
+ * <li>{@link WritableBuffer#writableWrap(ByteBuffer, ByteOrder,
MemoryRequestServer)}</li>
+ * </ul>
+ * Simple implementation examples include the DefaultMemoryRequestServer in
the main tree, as well as
+ * the ExampleMemoryRequestServerTest and the use with ByteBuffer documented
in the DruidIssue11544Test
+ * in the test tree.
+ * @return the MemoryRequestServer object or null.
+ */
+ public MemoryRequestServer getMemoryRequestServer();
+
+}
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/WritableBuffer.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/WritableHandle.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/WritableHandle.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/WritableHandle.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,36 @@
+/*
+ * 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 writable direct memory or a memory-mapped, writable file
resource.
+ * Please read Javadocs for {@link Handle}.
+ *
+ * @author Lee Rhodes
+ * @author Roman Leventov
+ */
+public interface WritableHandle extends Handle {
+
+ /**
+ * Gets a WritableMemory
+ * @return a WritableMemory
+ */
+ WritableMemory getWritable();
+}
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/WritableHandle.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/WritableMap.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/WritableMap.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/WritableMap.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,37 @@
+/*
+ * 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;
+
+/**
+ * Writable interface for a memory mapped file
+ *
+ * @author Roman Leventov
+ * @author Lee Rhodes
+ * @author Praveenkumar Venkatesan
+ */
+public interface WritableMap extends Map {
+
+ /**
+ * @see <a
href="https://docs.oracle.com/javase/8/docs/api/java/nio/MappedByteBuffer.html#force--";>
+ * java/nio/MappedByteBuffer.force</a>
+ */
+ void force();
+
+}
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/WritableMap.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/WritableMapHandle.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/WritableMapHandle.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/WritableMapHandle.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, writable file resource.
+ * Joins a WritableHandle with an AutoCloseable WritableMap resource
+ * Please read Javadocs for {@link Handle}.
+ *
+ * @author Roman Leventov
+ * @author Lee Rhodes
+ */
+public interface WritableMapHandle extends WritableMap, WritableHandle { }
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/WritableMapHandle.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/WritableMemory.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/WritableMemory.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/WritableMemory.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,639 @@
+/*
+ * 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.nio.ByteBuffer;
+import java.nio.ByteOrder;
+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 writable API for offset access to a resource.
+ *
+ * @author Lee Rhodes
+ */
+public interface WritableMemory extends Memory {
+
+ //BYTE BUFFER
+ /**
+ * Accesses the given <i>ByteBuffer</i> for write operations. The returned
<i>WritableMemory</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, with
capacity ≥ 0, and writable.
+ * @return a new <i>WritableMemory</i> for write operations on the given
<i>ByteBuffer</i>.
+ */
+ static WritableMemory writableWrap(ByteBuffer byteBuffer) {
+ return writableWrap(byteBuffer, byteBuffer.order(), defaultMemReqSvr);
+ }
+
+ /**
+ * Accesses the given <i>ByteBuffer</i> for write operations. The returned
<i>WritableMemory</i> object has
+ * the given byte order, ignoring the byte order of the given
<i>ByteBuffer</i> for future writes and following reads.
+ * However, this does not change the byte order of data already in the
<i>ByteBuffer</i>.
+ * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null, with
capacity ≥ 0, and writable.
+ * @param byteOrder the byte order to be used. It must be non-null.
+ * @return a new <i>WritableMemory</i> for write operations on the given
<i>ByteBuffer</i>.
+ */
+ static WritableMemory writableWrap(ByteBuffer byteBuffer, ByteOrder
byteOrder) {
+ return writableWrap(byteBuffer, byteOrder, defaultMemReqSvr);
+ }
+
+ /**
+ * Accesses the given <i>ByteBuffer</i> for write operations. The returned
<i>WritableMemory</i> object has
+ * the given byte order, ignoring the byte order of the given
<i>ByteBuffer</i> for future reads and writes.
+ * However, this does not change the byte order of data already in the
<i>ByteBuffer</i>.
+ * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null, with
capacity ≥ 0, and writable.
+ * @param byteOrder the byte order to be used. It must be non-null.
+ * @param memReqSvr A user-specified <i>MemoryRequestServer</i>, which may
be null.
+ * This is a callback mechanism for a user client to request a larger
<i>WritableMemory</i>.
+ * @return a new <i>WritableMemory</i> for write operations on the given
<i>ByteBuffer</i>.
+ */
+ static WritableMemory writableWrap(ByteBuffer byteBuffer, ByteOrder
byteOrder, MemoryRequestServer memReqSvr) {
+ Objects.requireNonNull(byteBuffer, "byteBuffer must be non-null");
+ Objects.requireNonNull(byteOrder, "byteOrder must be non-null");
+ negativeCheck(byteBuffer.capacity(), "byteBuffer");
+ if (byteBuffer.isReadOnly()) { throw new ReadOnlyException("byteBuffer
must be writable."); }
+ return BaseWritableMemoryImpl.wrapByteBuffer(byteBuffer, false, byteOrder,
memReqSvr);
+ }
+
+ //MAP
+ /**
+ * Maps the entire given file into native-ordered WritableMemory for write
operations
+ * Calling this method is equivalent to calling
+ * {@link #writableMap(File, long, long, ByteOrder) writableMap(file, 0,
file.length(), ByteOrder.nativeOrder())}.
+ * @param file the given file to map. It must be non-null, with length ≥
0, and writable.
+ * @return WritableMapHandle for managing the mapped Memory.
+ * Please read Javadocs for {@link Handle}.
+ */
+ static WritableMapHandle writableMap(File file) {
+ return writableMap(file, 0, file.length(), ByteOrder.nativeOrder());
+ }
+
+ /**
+ * Maps the specified portion of the given file into Memory for write
operations.
+ *
+ * <p><b>Note:</b> Always qualify this method with the class name, e.g.,
+ * <i>WritableMemory.map(...)</i>.
+ * @param file the given file to map. It must be non-null, writable and
length ≥ 0.
+ * @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 given file. It must be
non-null.
+ * @return WritableMapHandle for managing the mapped Memory.
+ * Please read Javadocs for {@link Handle}.
+ */
+ static WritableMapHandle writableMap(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.canWrite()) { throw new ReadOnlyException("file must be
writable."); }
+ negativeCheck(file.length(), "file.length()");
+ negativeCheck(fileOffsetBytes, "fileOffsetBytes");
+ negativeCheck(capacityBytes, "capacityBytes");
+ return BaseWritableMemoryImpl.wrapMap(file, fileOffsetBytes,
capacityBytes, false, byteOrder);
+ }
+
+ //ALLOCATE DIRECT
+ /**
+ * Allocates and provides access to capacityBytes directly in native
(off-heap) memory.
+ * Native byte order is assumed.
+ * The allocated memory will be 8-byte aligned, but may not be page aligned.
+ *
+ * <p><b>NOTE:</b> Native/Direct memory acquired may have garbage in it.
+ * It is the responsibility of the using application to clear this memory,
if required,
+ * and to call <i>close()</i> when done.</p>
+ *
+ * @param capacityBytes the size of the desired memory in bytes. It must be
≥ 0.
+ * @return WritableHandle for this off-heap resource.
+ * Please read Javadocs for {@link Handle}.
+ */
+ static WritableHandle allocateDirect(long capacityBytes) {
+ return allocateDirect(capacityBytes, ByteOrder.nativeOrder(),
defaultMemReqSvr);
+ }
+
+ /**
+ * Allocates and provides access to capacityBytes directly in native
(off-heap) memory.
+ * The allocated memory will be 8-byte aligned, but may not be page aligned.
+ *
+ * <p><b>NOTE:</b> Native/Direct memory acquired may have garbage in it.
+ * It is the responsibility of the using application to clear this memory,
if required,
+ * and to call <i>close()</i> when done.</p>
+ *
+ * @param capacityBytes the size of the desired memory in bytes. It must be
≥ 0.
+ * @param byteOrder the given byte order. It must be non-null.
+ * @param memReqSvr A user-specified MemoryRequestServer, which may be null.
+ * This is a callback mechanism for a user client of direct memory to
request more memory.
+ * @return WritableHandle for this off-heap resource.
+ * Please read Javadocs for {@link Handle}.
+ */
+ static WritableHandle allocateDirect(long capacityBytes, ByteOrder
byteOrder, MemoryRequestServer memReqSvr) {
+ Objects.requireNonNull(byteOrder, "byteOrder must be non-null");
+ negativeCheck(capacityBytes, "capacityBytes");
+ return BaseWritableMemoryImpl.wrapDirect(capacityBytes, byteOrder,
memReqSvr);
+ }
+
+ //REGIONS
+ /**
+ * A writable region is a writable view of this object.
+ * This returns a new <i>WritableMemory</i> representing the defined
writable region with the
+ * given offsetBytes and capacityBytes.
+ * <ul>
+ * <li>Returned object's origin = this objects' origin +
<i>offsetBytes</i></li>
+ * <li>Returned object's capacity = <i>capacityBytes</i></li>
+ * </ul>
+ *
+ * @param offsetBytes the starting offset with respect to this object. It
must be ≥ 0.
+ * @param capacityBytes the capacity of the returned object in bytes. It
must be ≥ 0.
+ * @return a new <i>WritableMemory</i> representing the defined writable
region.
+ */
+ default WritableMemory writableRegion(long offsetBytes, long capacityBytes) {
+ return writableRegion(offsetBytes, capacityBytes, getTypeByteOrder());
+ }
+
+ /**
+ * A writable region is a writable view of this object.
+ * This returns a new <i>WritableMemory</i> representing the defined
writable region with the
+ * given offsetBytes, capacityBytes and byte order.
+ * <ul>
+ * <li>Returned object's origin = this objects' 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 this object. It
must be ≥ 0.
+ * @param capacityBytes the capacity of the returned object in bytes. It
must be ≥ 0.
+ * @param byteOrder the given byte order. It must be non-null.
+ * @return a new <i>WritableMemory</i> representing the defined writable
region.
+ */
+ WritableMemory writableRegion(long offsetBytes, long capacityBytes,
ByteOrder byteOrder);
+
+ //AS WRITABLE BUFFER
+ /**
+ * Returns a new <i>WritableBuffer</i> with a writable 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>WritableBuffer</i> with a view of this WritableMemory
+ */
+ default WritableBuffer asWritableBuffer() {
+ return asWritableBuffer(getTypeByteOrder());
+ }
+
+ /**
+ * Returns a new <i>WritableBuffer</i> with a writable 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>WritableBuffer</i> with a view of this WritableMemory
+ */
+ WritableBuffer asWritableBuffer(ByteOrder byteOrder);
+
+ //ALLOCATE HEAP VIA AUTOMATIC BYTE ARRAY
+ /**
+ * Creates on-heap WritableMemory with the given capacity and the native
byte order.
+ * @param capacityBytes the given capacity in bytes. It must be ≥ 0.
+ * @return a new WritableMemory for write operations on a new byte array.
+ */
+ static WritableMemory allocate(int capacityBytes) {
+ return allocate(capacityBytes, ByteOrder.nativeOrder(), defaultMemReqSvr);
+ }
+
+ /**
+ * Creates on-heap WritableMemory with the given capacity and the given byte
order.
+ * @param capacityBytes the given capacity in bytes. It must be ≥ 0.
+ * @param byteOrder the given byte order to allocate new Memory object with.
It must be non-null.
+ * @return a new WritableMemory for write operations on a new byte array.
+ */
+ static WritableMemory allocate(int capacityBytes, ByteOrder byteOrder) {
+ return allocate(capacityBytes, byteOrder, defaultMemReqSvr);
+ }
+
+ /**
+ * Creates on-heap WritableMemory with the given capacity and the given byte
order.
+ * @param capacityBytes the given capacity in bytes. It must be ≥ 0.
+ * @param byteOrder the given byte order to allocate new Memory object with.
It must be non-null.
+ * @param memReqSvr A user-specified <i>MemoryRequestServer</i>, which may
be null.
+ * This is a callback mechanism for a user client to request a larger
<i>WritableMemory</i>.
+ * @return a new WritableMemory for write operations on a new byte array.
+ */
+ static WritableMemory allocate(int capacityBytes, ByteOrder byteOrder,
MemoryRequestServer memReqSvr) {
+ final byte[] arr = new byte[capacityBytes];
+ negativeCheck(capacityBytes, "capacityBytes");
+ return writableWrap(arr, 0, capacityBytes, byteOrder, memReqSvr);
+ }
+
+ //ACCESS PRIMITIVE HEAP ARRAYS for WRITE
+
+ /**
+ * Wraps the given primitive array for write operations assuming native byte
order.
+ *
+ * <p><b>Note:</b> Always qualify this method with the class name, e.g.,
+ * <i>WritableMemory.wrap(...)</i>.
+ * @param array the given primitive array. It must be non-null.
+ * @return a new WritableMemory for write operations on the given primitive
array.
+ */
+ static WritableMemory writableWrap(byte[] array) {
+ return writableWrap(array, 0, array.length, ByteOrder.nativeOrder(),
defaultMemReqSvr);
+ }
+
+ /**
+ * Wraps the given primitive array for write operations with the given byte
order.
+ *
+ * <p><b>Note:</b> Always qualify this method with the class name, e.g.,
+ * <i>WritableMemory.wrap(...)</i>.
+ * @param array the given primitive array. It must be non-null.
+ * @param byteOrder the byte order to be used. It must be non-null.
+ * @return a new WritableMemory for write operations on the given primitive
array.
+ */
+ static WritableMemory writableWrap(byte[] array, ByteOrder byteOrder) {
+ return writableWrap(array, 0, array.length, byteOrder, defaultMemReqSvr);
+ }
+
+ /**
+ * Wraps the given primitive array for write operations with the given byte
order.
+ *
+ * <p><b>Note:</b> Always qualify this method with the class name, e.g.,
+ * <i>WritableMemory.wrap(...)</i>.
+ * @param array the given primitive array. It must be non-null.
+ * @param offsetBytes the byte offset into the given array. It must be ≥
0.
+ * @param lengthBytes the number of bytes to include from the given array.
It must be ≥ 0.
+ * @param byteOrder the byte order to be used. It must be non-null.
+ * @return a new WritableMemory for write operations on the given primitive
array.
+ */
+ static WritableMemory writableWrap(byte[] array, int offsetBytes, int
lengthBytes, ByteOrder byteOrder) {
+ return writableWrap(array, offsetBytes, lengthBytes, byteOrder,
defaultMemReqSvr);
+ }
+
+ /**
+ * Wraps the given primitive array for write operations with the given byte
order. If the given
+ * lengthBytes is zero, backing storage, byte order and read-only status of
the returned
+ * WritableMemory object are unspecified.
+ *
+ * <p><b>Note:</b> Always qualify this method with the class name, e.g.,
+ * <i>WritableMemory.wrap(...)</i>.
+ * @param array the given primitive array. It must be non-null.
+ * @param offsetBytes the byte offset into the given array. It must be ≥
0.
+ * @param lengthBytes the number of bytes to include from the given array.
It must be ≥ 0.
+ * @param byteOrder the byte order to be used. It must be non-null.
+ * @param memReqSvr A user-specified <i>MemoryRequestServer</i>, which may
be null.
+ * This is a callback mechanism for a user client to request a larger
<i>WritableMemory</i>.
+ * @return a new WritableMemory for write operations on the given primitive
array.
+ */
+ static WritableMemory writableWrap(byte[] array, int offsetBytes, int
lengthBytes, ByteOrder byteOrder,
+ MemoryRequestServer memReqSvr) {
+ 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, offsetBytes,
lengthBytes, false, byteOrder, memReqSvr);
+ }
+
+ /**
+ * Wraps the given primitive array for write operations assuming native byte
order.
+ * @param array the given primitive array. It must be non-null.
+ * @return a new WritableMemory for write operations on the given primitive
array.
+ */
+ static WritableMemory writableWrap(boolean[] array) {
+ Objects.requireNonNull(array, "array must be non-null");
+ final long lengthBytes = array.length << Prim.BOOLEAN.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0, lengthBytes, false,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for write operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new WritableMemory for write operations on the given primitive
array.
+ */
+ static WritableMemory writableWrap(char[] array) {
+ Objects.requireNonNull(array, "array must be non-null");
+ final long lengthBytes = array.length << Prim.CHAR.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, false,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for write operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new WritableMemory for write operations on the given primitive
array.
+ */
+ static WritableMemory writableWrap(short[] array) {
+ Objects.requireNonNull(array, "arr must be non-null");
+ final long lengthBytes = array.length << Prim.SHORT.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, false,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for write operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new WritableMemory for write operations on the given primitive
array.
+ */
+ static WritableMemory writableWrap(int[] array) {
+ Objects.requireNonNull(array, "arr must be non-null");
+ final long lengthBytes = array.length << Prim.INT.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, false,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for write operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new WritableMemory for write operations on the given primitive
array.
+ */
+ static WritableMemory writableWrap(long[] array) {
+ Objects.requireNonNull(array, "arr must be non-null");
+ final long lengthBytes = array.length << Prim.LONG.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, false,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for write operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new WritableMemory for write operations on the given primitive
array.
+ */
+ static WritableMemory writableWrap(float[] array) {
+ Objects.requireNonNull(array, "arr must be non-null");
+ final long lengthBytes = array.length << Prim.FLOAT.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, false,
ByteOrder.nativeOrder(), null);
+ }
+
+ /**
+ * Wraps the given primitive array for write operations assuming native byte
order.
+ * @param array the given primitive array.
+ * @return a new WritableMemory for write operations on the given primitive
array.
+ */
+ static WritableMemory writableWrap(double[] array) {
+ Objects.requireNonNull(array, "arr must be non-null");
+ final long lengthBytes = array.length << Prim.DOUBLE.shift();
+ return BaseWritableMemoryImpl.wrapHeapArray(array, 0L, lengthBytes, false,
ByteOrder.nativeOrder(), null);
+ }
+ //END OF CONSTRUCTOR-TYPE METHODS
+
+ //PRIMITIVE putX() and putXArray()
+ /**
+ * Puts the boolean value at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putBoolean(long offsetBytes, boolean value);
+
+ /**
+ * Puts the boolean array at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param srcArray The source array.
+ * @param srcOffsetBooleans offset in array units
+ * @param lengthBooleans number of array units to transfer
+ */
+ void putBooleanArray(long offsetBytes, boolean[] srcArray, int
srcOffsetBooleans, int lengthBooleans);
+
+ /**
+ * Puts the byte value at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putByte(long offsetBytes, byte value);
+
+ /**
+ * Puts the byte array at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param srcArray The source array.
+ * @param srcOffsetBytes offset in array units
+ * @param lengthBytes number of array units to transfer
+ */
+ void putByteArray(long offsetBytes, byte[] srcArray, int srcOffsetBytes, int
lengthBytes);
+
+ /**
+ * Puts the char value at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putChar(long offsetBytes, char value);
+
+ /**
+ * Puts the char array at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param srcArray The source array.
+ * @param srcOffsetChars offset in array units
+ * @param lengthChars number of array units to transfer
+ */
+ void putCharArray(long offsetBytes, char[] srcArray, int srcOffsetChars, int
lengthChars);
+
+ /**
+ * Encodes characters from the given CharSequence into UTF-8 bytes and puts
them into this
+ * <i>WritableMemory</i> begining at the given offsetBytes.
+ * 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 this <i>WritableMemory</i>
start
+ * @param src The source CharSequence to be encoded and put into this
WritableMemory. It is
+ * the responsibility of the caller to provide sufficient capacity in this
+ * <i>WritableMemory</i> for the encoded Utf8 bytes. Characters outside the
ASCII range can
+ * require 2, 3 or 4 bytes per character to encode.
+ * @return the number of bytes encoded
+ */
+ long putCharsToUtf8(long offsetBytes, CharSequence src);
+
+ /**
+ * Puts the double value at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putDouble(long offsetBytes, double value);
+
+ /**
+ * Puts the double array at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param srcArray The source array.
+ * @param srcOffsetDoubles offset in array units
+ * @param lengthDoubles number of array units to transfer
+ */
+ void putDoubleArray(long offsetBytes, double[] srcArray, int
srcOffsetDoubles, int lengthDoubles);
+
+ /**
+ * Puts the float value at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putFloat(long offsetBytes, float value);
+
+ /**
+ * Puts the float array at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param srcArray The source array.
+ * @param srcOffsetFloats offset in array units
+ * @param lengthFloats number of array units to transfer
+ */
+ void putFloatArray(long offsetBytes, float[] srcArray, int srcOffsetFloats,
int lengthFloats);
+
+ /**
+ * Puts the int value at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putInt(long offsetBytes, int value);
+
+ /**
+ * Puts the int array at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param srcArray The source array.
+ * @param srcOffsetInts offset in array units
+ * @param lengthInts number of array units to transfer
+ */
+ void putIntArray(long offsetBytes, int[] srcArray, int srcOffsetInts, int
lengthInts);
+
+ /**
+ * Puts the long value at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putLong(long offsetBytes, long value);
+
+ /**
+ * Puts the long array at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param srcArray The source array.
+ * @param srcOffsetLongs offset in array units
+ * @param lengthLongs number of array units to transfer
+ */
+ void putLongArray(long offsetBytes, long[] srcArray, int srcOffsetLongs, int
lengthLongs);
+
+ /**
+ * Puts the short value at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param value the value to put
+ */
+ void putShort(long offsetBytes, short value);
+
+ /**
+ * Puts the short array at the given offset
+ * @param offsetBytes offset bytes relative to this <i>WritableMemory</i>
start
+ * @param srcArray The source array.
+ * @param srcOffsetShorts offset in array units
+ * @param lengthShorts number of array units to transfer
+ */
+ void putShortArray(long offsetBytes, short[] srcArray, int srcOffsetShorts,
int lengthShorts);
+
+ //Atomic Methods
+ /**
+ * Atomically adds the given value to the long located at offsetBytes.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param delta the amount to add
+ * @return the the previous value
+ */
+ long getAndAddLong(long offsetBytes, long delta);
+
+ /**
+ * Atomically sets the current value at the memory location to the given
updated value
+ * if and only if the current value {@code ==} the expected value.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param expect the expected value
+ * @param update the new value
+ * @return {@code true} if successful. False return indicates that
+ * the current value at the memory location was not equal to the expected
value.
+ */
+ boolean compareAndSwapLong(long offsetBytes, long expect, long update);
+
+ /**
+ * Atomically exchanges the given value with the current value located at
offsetBytes.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param newValue new value
+ * @return the previous value
+ */
+ long getAndSetLong(long offsetBytes, long newValue);
+
+ //OTHER WRITE METHODS
+ /**
+ * Returns the primitive backing array, otherwise null.
+ * @return the primitive backing array, otherwise null.
+ */
+ Object getArray();
+
+ /**
+ * Clears all bytes of this Memory to zero
+ */
+ void clear();
+
+ /**
+ * Clears a portion of this Memory to zero.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param lengthBytes the length in bytes
+ */
+ void clear(long offsetBytes, long lengthBytes);
+
+ /**
+ * Clears the bits defined by the bitMask
+ * @param offsetBytes offset bytes relative to this Memory start.
+ * @param bitMask the bits set to one will be cleared
+ */
+ void clearBits(long offsetBytes, byte bitMask);
+
+ /**
+ * Fills all bytes of this Memory region to the given byte value.
+ * @param value the given byte value
+ */
+ void fill(byte value);
+
+ /**
+ * Fills a portion of this Memory region to the given byte value.
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param lengthBytes the length in bytes
+ * @param value the given byte value
+ */
+ void fill(long offsetBytes, long lengthBytes, byte value);
+
+ /**
+ * Sets the bits defined by the bitMask
+ * @param offsetBytes offset bytes relative to this Memory start
+ * @param bitMask the bits set to one will be set
+ */
+ void setBits(long offsetBytes, byte bitMask);
+
+
+ //OTHER WRITABLE API METHODS
+ /**
+ * WritableMemory enables this for ByteBuffer, Heap and Direct Memory backed
resources.
+ * Map backed resources will always return null.
+ * Gets the MemoryRequestServer object, if set, for the above resources to
request additional memory.
+ * The user must customize the actions of the MemoryRequestServer by
+ * implementing the MemoryRequestServer interface and set using one of these
methods:
+ * <ul><li>{@link WritableMemory#allocateDirect(long, ByteOrder,
MemoryRequestServer)}</li>
+ * <li>{@link WritableMemory#allocate(int, ByteOrder,
MemoryRequestServer)}</li>
+ * <li>{@link WritableMemory#writableWrap(ByteBuffer, ByteOrder,
MemoryRequestServer)}</li>
+ * </ul>
+ * Simple implementation examples include the DefaultMemoryRequestServer in
the main tree, as well as
+ * the ExampleMemoryRequestServerTest and the use with ByteBuffer documented
in the DruidIssue11544Test
+ * in the test tree.
+ * @return the MemoryRequestServer object or null.
+ */
+ MemoryRequestServer getMemoryRequestServer();
+
+}
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/WritableMemory.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/XxHash.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/XxHash.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/XxHash.java
Tue May 21 21:11:49 2024
@@ -0,0 +1,192 @@
+/*
+ * 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.XxHash64.hash;
+import static org.apache.datasketches.memory.internal.XxHash64.hashBooleans;
+import static org.apache.datasketches.memory.internal.XxHash64.hashBytes;
+import static org.apache.datasketches.memory.internal.XxHash64.hashChars;
+import static org.apache.datasketches.memory.internal.XxHash64.hashDoubles;
+import static org.apache.datasketches.memory.internal.XxHash64.hashFloats;
+import static org.apache.datasketches.memory.internal.XxHash64.hashInts;
+import static org.apache.datasketches.memory.internal.XxHash64.hashLongs;
+import static org.apache.datasketches.memory.internal.XxHash64.hashShorts;
+
+/**
+ * The XxHash is a fast, non-cryptographic, 64-bit hash function that has
+ * excellent avalanche and 2-way bit independence properties.
+ * This java version adapted the C++ version and the
OpenHFT/Zero-Allocation-Hashing implementation
+ * referenced below as inspiration.
+ *
+ * <p>The C++ source repository:
+ * <a href="https://github.com/Cyan4973/xxHash";>
+ * https://github.com/Cyan4973/xxHash</a>. It has a BSD 2-Clause License:
+ * <a href="http://www.opensource.org/licenses/bsd-license.php";>
+ * http://www.opensource.org/licenses/bsd-license.php</a>. See LICENSE.
+ *
+ * <p>Portions of this code were adapted from
+ * <a
href="https://github.com/OpenHFT/Zero-Allocation-Hashing/blob/master/src/main/java/net/openhft/hashing/XxHash.java";>
+ * OpenHFT/Zero-Allocation-Hashing</a>, which has an Apache 2 license as does
this site. See LICENSE.
+ *
+ * @author Lee Rhodes
+ */
+public final class XxHash {
+
+ private XxHash() { /* singleton */ }
+
+ /**
+ * Hash the given arr starting at the given offset and continuing for the
given length using the
+ * given seed.
+ * @param arr the given array
+ * @param offsetBooleans starting at this offset
+ * @param lengthBooleans continuing for this length
+ * @param seed the given seed
+ * @return the hash
+ */
+ public static long hashBooleanArr(final boolean[] arr, final long
offsetBooleans,
+ final long lengthBooleans, final long seed) {
+ return hashBooleans(arr, offsetBooleans, lengthBooleans, seed);
+ }
+
+ /**
+ * Hash the given arr starting at the given offset and continuing for the
given length using the
+ * given seed.
+ * @param arr the given array
+ * @param offsetBytes starting at this offset
+ * @param lengthBytes continuing for this length
+ * @param seed the given seed
+ * @return the hash
+ */
+ public static long hashByteArr(final byte[] arr, final long offsetBytes,
+ final long lengthBytes, final long seed) {
+ return hashBytes(arr, offsetBytes, lengthBytes, seed);
+ }
+
+ /**
+ * Hash the given arr starting at the given offset and continuing for the
given length using the
+ * given seed.
+ * @param arr the given array
+ * @param offsetShorts starting at this offset
+ * @param lengthShorts continuing for this length
+ * @param seed the given seed
+ * @return the hash
+ */
+ public static long hashShortArr(final short[] arr, final long offsetShorts,
+ final long lengthShorts, final long seed) {
+ return hashShorts(arr, offsetShorts, lengthShorts, seed);
+ }
+
+ /**
+ * Hash the given arr starting at the given offset and continuing for the
given length using the
+ * given seed.
+ * @param arr the given array
+ * @param offsetChars starting at this offset
+ * @param lengthChars continuing for this length
+ * @param seed the given seed
+ * @return the hash
+ */
+ public static long hashCharArr(final char[] arr, final long offsetChars,
+ final long lengthChars, final long seed) {
+ return hashChars(arr, offsetChars, lengthChars, seed);
+ }
+
+ /**
+ * Hash the given arr starting at the given offset and continuing for the
given length using the
+ * given seed.
+ * @param arr the given array
+ * @param offsetInts starting at this offset
+ * @param lengthInts continuing for this length
+ * @param seed the given seed
+ * @return the hash
+ */
+ public static long hashIntArr(final int[] arr, final long offsetInts,
+ final long lengthInts, final long seed) {
+ return hashInts(arr, offsetInts, lengthInts, seed);
+ }
+
+ /**
+ * Hash the given arr starting at the given offset and continuing for the
given length using the
+ * given seed.
+ * @param arr the given array
+ * @param offsetLongs starting at this offset
+ * @param lengthLongs continuing for this length
+ * @param seed the given seed
+ * @return the hash
+ */
+ public static long hashLongArr(final long[] arr, final long offsetLongs,
+ final long lengthLongs, final long seed) {
+ return hashLongs(arr, offsetLongs, lengthLongs, 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.
+ */
+ public static long hashLong(final long in, final long seed) {
+ return hash(in, seed);
+ }
+
+ /**
+ * Hash the given arr starting at the given offset and continuing for the
given length using the
+ * given seed.
+ * @param arr the given array
+ * @param offsetFloats starting at this offset
+ * @param lengthFloats continuing for this length
+ * @param seed the given seed
+ * @return the hash
+ */
+ public static long hashFloatArr(final float[] arr, final long offsetFloats,
+ final long lengthFloats, final long seed) {
+ return hashFloats(arr, offsetFloats, lengthFloats, seed);
+ }
+
+ /**
+ * Hash the given arr starting at the given offset and continuing for the
given length using the
+ * given seed.
+ * @param arr the given array
+ * @param offsetDoubles starting at this offset
+ * @param lengthDoubles continuing for this length
+ * @param seed the given seed
+ * @return the hash
+ */
+ public static long hashDoubleArr(final double[] arr, final long
offsetDoubles,
+ final long lengthDoubles, final long seed) {
+ return hashDoubles(arr, offsetDoubles, lengthDoubles, seed);
+ }
+
+ /**
+ * Hash the given arr starting at the given offset and continuing for the
given length using the
+ * given seed.
+ * @param str the given string
+ * @param offsetChars starting at this offset
+ * @param lengthChars continuing for this length
+ * @param seed the given seed
+ * @return the hash
+ */
+ public static long hashString(final String str, final long offsetChars,
+ final long lengthChars, final long seed) {
+ return org.apache.datasketches.memory.internal.XxHash64.hashString(str,
offsetChars, lengthChars, seed);
+ }
+
+}
+
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/XxHash.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/internal/AccessByteBuffer.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/internal/AccessByteBuffer.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/internal/AccessByteBuffer.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.internal;
+
+import static org.apache.datasketches.memory.internal.UnsafeUtil.unsafe;
+
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+
+/**
+ * Acquires access to a ByteBuffer.
+ *
+ * @author Lee Rhodes
+ * @author Praveenkumar Venkatesan
+ * @author Roman Leventov
+ */
+@SuppressWarnings("restriction")
+final class AccessByteBuffer {
+
+ static final ByteBuffer ZERO_READ_ONLY_DIRECT_BYTE_BUFFER =
+ ByteBuffer.allocateDirect(0).asReadOnlyBuffer();
+
+ private static final long NIO_BUFFER_ADDRESS_FIELD_OFFSET =
+ UnsafeUtil.getFieldOffset(java.nio.Buffer.class, "address");
+ private static final long NIO_BUFFER_CAPACITY_FIELD_OFFSET =
+ UnsafeUtil.getFieldOffset(java.nio.Buffer.class, "capacity");
+ private static final long BYTE_BUFFER_HB_FIELD_OFFSET =
+ UnsafeUtil.getFieldOffset(java.nio.ByteBuffer.class, "hb");
+ private static final long BYTE_BUFFER_OFFSET_FIELD_OFFSET =
+ UnsafeUtil.getFieldOffset(java.nio.ByteBuffer.class, "offset");
+
+ final long nativeBaseOffset;
+ final long capacityBytes;
+ final long regionOffset;
+ final Object unsafeObj;
+ final boolean resourceReadOnly;
+ final ByteOrder byteOrder; //not used externally, here for reference.
+
+ /**
+ * The given ByteBuffer may be either readOnly or writable
+ * @param byteBuf the given ByteBuffer
+ */
+ AccessByteBuffer(final ByteBuffer byteBuf) {
+ capacityBytes = byteBuf.capacity();
+ resourceReadOnly = byteBuf.isReadOnly();
+ byteOrder = byteBuf.order();
+ final boolean direct = byteBuf.isDirect();
+ if (direct) {
+ nativeBaseOffset = ((sun.nio.ch.DirectBuffer) byteBuf).address();
+ unsafeObj = null;
+ regionOffset = 0L; //address() is already adjusted for direct slices, so
regionOffset = 0
+ } else {
+ nativeBaseOffset = 0L;
+ // ByteBuffer.arrayOffset() and ByteBuffer.array() throw
ReadOnlyBufferException if
+ // ByteBuffer is read-only. This uses reflection for both writable and
read-only cases.
+ // Includes the slice() offset for heap.
+ regionOffset = unsafe.getInt(byteBuf, BYTE_BUFFER_OFFSET_FIELD_OFFSET);
+ unsafeObj = unsafe.getObject(byteBuf, BYTE_BUFFER_HB_FIELD_OFFSET);
+ }
+ }
+
+ /**
+ * This method is adapted from
+ *
https://github.com/odnoklassniki/one-nio/blob/master/src/one/nio/mem/DirectMemory.java
+ * : wrap(...). See LICENSE.
+ */
+ static ByteBuffer getDummyReadOnlyDirectByteBuffer(final long address, final
int capacity) {
+ final ByteBuffer buf = ZERO_READ_ONLY_DIRECT_BYTE_BUFFER.duplicate();
+ unsafe.putLong(buf, NIO_BUFFER_ADDRESS_FIELD_OFFSET, address);
+ unsafe.putInt(buf, NIO_BUFFER_CAPACITY_FIELD_OFFSET, capacity);
+ buf.limit(capacity);
+ return buf;
+ }
+
+}
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/internal/AccessByteBuffer.java
------------------------------------------------------------------------------
svn:executable = *
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
