Merge pull request #670 from apache/ffm_phase3

FFM phase3

Author: leerho

pom.xml

@@ -33,7 +33,7 @@ under the License.
 
   <groupId>org.apache.datasketches</groupId>
   <artifactId>datasketches-java</artifactId>
-  <version>8.0.0-SNAPSHOT</version>
+  <version>9.0.0-SNAPSHOT</version>
   <packaging>jar</packaging>
 
   <name>${project.artifactId}</name>
@@ -190,7 +190,7 @@ under the License.
               <configuration>
                 <rules>
                   <requireJavaVersion>
-                    <version>[22,)</version> <!-- java.version -->
+                    <version>[24,)</version> <!-- java.version -->
                   </requireJavaVersion>
                   <requireMavenVersion>
                     <version>[${maven.version},4.0.0)</version>

src/main/java/org/apache/datasketches/common/MemorySegmentStatus.java

@@ -44,8 +44,6 @@ public interface MemorySegmentStatus {
    * Returns true if an internally referenced MemorySegment has the same backing resource as <i>that</i>,
    * or equivalently, if their two memory regions overlap.  This applies to both on-heap and off-heap MemorySegments.
    *
-   * <p>This returns false if either segment is <i>null</i> or not alive.</p>
-   *
    * <p><b>Note:</b> If both segments are on-heap and not read-only, it can be determined if they were derived from
    * the same backing memory (array).  However, this is not always possible off-heap. Because of this asymmetry, this definition
    * of "isSameResource" is confined to the existence of an overlap.</p>
@@ -59,8 +57,6 @@ public interface MemorySegmentStatus {
    * Returns true if the two given MemorySegments have to the same backing resource, or equivalently,
    * if the two memory regions overlap.  This applies to both on-heap and off-heap MemorySegments.
    *
-   * <p>This returns false if either segment is <i>null</i> or not alive.</p>
-   *
    * <p><b>Note:</b> If both segments are on-heap and not read-only, it can be determined if they were derived from
    * the same backing memory (array).  However, this is not always possible off-heap. Because of this asymmetry, this definition
    * of "isSameResource" is confined to the existence of an overlap.</p>
@@ -70,7 +66,6 @@ public interface MemorySegmentStatus {
    * @return true if the two given MemorySegments have to the same backing resource.
    */
   static boolean isSameResource(final MemorySegment seg1, final MemorySegment seg2) {
-    if ((seg1 == null) || (seg2 == null) || !seg1.scope().isAlive() || !seg2.scope().isAlive()) { return false; }
     final Optional<MemorySegment> opt = seg1.asOverlappingSlice(seg2);
     return opt.isPresent();
   }

src/main/java/org/apache/datasketches/common/Util.java

@@ -424,6 +424,19 @@ public static long floorPowerOf2(final long n) {
     return Long.highestOneBit(n);
   }
 
+  /**
+   * This is a long integer equivalent to <i>Math.ceil(n / (double)(1 << k))</i>
+   * where: <i>0 &lt; k &le; 6</i> and <i>n</i> is a non-negative long.
+   * These limits are not checked for speed.
+   * @param n the input dividend as a positive long greater than zero.
+   * @param k the input divisor exponent of 2 as a positive integer where 0 &lt; k &le; 6.
+   * @return the long integer equivalent to <i>Math.ceil(n / 2^k)</i>.
+   */
+  public static long ceilingMultiple2expK(final long n, final int k) {
+    final long mask = (1L << k) - 1L;
+    return (n & mask) > 0 ? (n >>> k) + 1 : n >>> k;
+  }
+
   /**
    * Computes the inverse integer power of 2: 1/(2^e) = 2^(-e).
    * @param e a positive value between 0 and 1023 inclusive

src/main/java/org/apache/datasketches/common/positional/PositionInvariantsException.java

@@ -0,0 +1,39 @@
+/*
+ * 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.common.positional;
+
+/**
+ * Position operation violation.
+ */
+public class PositionInvariantsException extends RuntimeException {
+  private static final long serialVersionUID = 1L;
+
+  /**
+   * The associated position operation violated one of the positional invariants.
+   *
+   * <p>The invariants equation is {@code 0 <= start <= position <= end <= capacity}.</p>
+   *
+   * @param details of the violation.
+   */
+  public PositionInvariantsException(final String details) {
+    super(details);
+  }
+}
+

src/main/java/org/apache/datasketches/common/positional/Positional.java

@@ -0,0 +1,118 @@
+/*
+ * 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.common.positional;
+
+/**
+ * Defines the relative positional API.
+ * This is different from and simpler than Java ByteBuffer positional API.
+ * <ul><li>All based on longs instead of ints.</li>
+ * <li>Eliminated "mark". Mark is rarely used and confusing with its silent side effects.</li>
+ * <li>The invariants are {@code 0 <= start <= position <= end <= capacity}.</li>
+ * <li>It always starts up as (0, 0, capacity, capacity).</li>
+ * <li>You set (start, position, end) in one call with
+ * {@link #setStartPositionEnd(long, long, long)}</li>
+ * <li>Position can be set directly or indirectly when using the positional get/put methods.
+ * <li>Added incrementPosition(long), which is much easier when you know the increment.</li>
+ * <li>This approach eliminated a number of methods and checks, and has no unseen side effects,
+ * e.g., mark being invalidated.</li>
+ * <li>Clearer method naming (IMHO).</li>
+ * </ul>
+ *
+ * @author Lee Rhodes
+ */
+public interface Positional {
+
+  /**
+   * Gets an instance of this Positional.
+   * @param capacity the upper limit of positional range.
+   * @return an instance of Positional.
+   */
+  static Positional getInstance(final long capacity) {
+    return new PositionalImpl(capacity);
+  }
+
+  /**
+   * Increments the current position by the given increment.
+   * @param increment the given increment
+   * @return this Positional
+   */
+  Positional incrementPosition(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 this Positional
+   */
+  Positional resetPosition();
+
+  /**
+   * Sets the current position.
+   * Checks that the positional invariants are not violated.
+   * @param position the given current position.
+   * @return this Positional
+   * @throws PositionInvariantsException if positional invariants have been violated.
+   */
+  Positional setPosition(long position);
+
+  /**
+   * Sets start position, current position, and end position.
+   * Checks that the positional invariants are not violated.
+   * @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 this Positional
+   * @throws PositionInvariantsException if positional invariants have been violated.
+   */
+  Positional setStartPositionEnd(
+      long start,
+      long position,
+      long end);
+
+}

src/main/java/org/apache/datasketches/common/positional/PositionalImpl.java

@@ -0,0 +1,133 @@
+/*
+ * 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.common.positional;
+
+/**
+ * This implements the positional API.
+ * This is different from and simpler than Java BufferImpl positional approach.
+ * <ul><li>All based on longs instead of ints.</li>
+ * <li>Eliminated "mark". Rarely used and confusing with its silent side effects.</li>
+ * <li>The invariants are {@code 0 <= start <= position <= end <= capacity}.</li>
+ * <li>It always starts up as (0, 0, capacity, capacity).</li>
+ * <li>You set (start, position, end) in one call with <i>setStartPositionEnd(long, long, long)</i></li>
+ * <li>Position can be set directly or indirectly when using the positional get/put methods.
+ * <li>Added incrementPosition(long), which is much easier when you know the increment.</li>
+ * <li>This approach eliminated a number of methods and checks, and has no unseen side effects,
+ * e.g., mark being invalidated.</li>
+ * <li>Clearer method naming (IMHO).</li>
+ * </ul>
+ *
+ * @author Lee Rhodes
+ */
+class PositionalImpl implements Positional {
+  private final long capacity;
+  private long start = 0;
+  private long pos = 0;
+  private long end;
+
+  /**
+   * Construct with total capacity.
+   * @param capacity the upper limit of positional range.
+   */
+  PositionalImpl(
+      final long capacity) {
+    this.capacity = end = capacity;
+  }
+
+  @Override
+  public final PositionalImpl incrementPosition(final long increment) {
+    pos += increment;
+    return this;
+  }
+
+  @Override
+  public final long getEnd() {
+    return end;
+  }
+
+  @Override
+  public final long getPosition() {
+    return pos;
+  }
+
+  @Override
+  public final long getStart() {
+    return start;
+  }
+
+  @Override
+  public final long getRemaining()  {
+    return end - pos;
+  }
+
+  @Override
+  public final boolean hasRemaining() {
+    return (end - pos) > 0;
+  }
+
+  @Override
+  public final PositionalImpl resetPosition() {
+    pos = start;
+    return this;
+  }
+
+  @Override
+  public final PositionalImpl setPosition(final long position) {
+    checkInvariants(start, position, end, capacity);
+    pos = position;
+    return this;
+  }
+
+  @Override
+  public final PositionalImpl setStartPositionEnd(final long start, final long position, final long end) {
+    checkInvariants(start, position, end, capacity);
+    this.start = start;
+    this.end = end;
+    pos = position;
+    return this;
+  }
+
+  //RESTRICTED
+
+  /**
+   * The invariants equation is: {@code 0 <= start <= position <= end <= capacity}.
+   * If this equation is violated an <i>PositionInvariantsException</i> will be thrown.
+   * @param start the lowest start position
+   * @param pos the current position
+   * @param end the highest position
+   * @param cap the capacity of the backing buffer.
+   */
+  private static final void checkInvariants(final long start, final long pos, final long end,
+        final long cap) {
+    if ((start | pos | end | cap | (pos - start) | (end - pos) | (cap - end) ) < 0L) {
+      throw new PositionInvariantsException(
+          "Violation of Invariants: "
+              + "start: " + start
+              + " <= pos: " + pos
+              + " <= end: " + end
+              + " <= cap: " + cap
+              + "; (pos - start): " + (pos - start)
+              + ", (end - pos): " + (end - pos)
+              + ", (cap - end): " + (cap - end)
+      );
+    }
+  }
+
+}