GH-948: Use buffer indexing for UUID vector (#949)

## What's Changed

The current UUID vector implementation creates new buffer slices when
reading values through holders, which has several drawbacks:
- Memory overhead: Each slice creates a new ArrowBuf object
- Performance impact: Buffer slicing is slower than direct buffer
indexing
- Inconsistency: Other fixed-width types (like Decimal) use buffer
indexing with a `start` offset field

### Proposed Changes

1. Add `start` field to UUID holders to track buffer offsets:
   - `UuidHolder`: Add `public int start = 0;`
   - `NullableUuidHolder`: Add `public int start = 0;`
2. Update `UuidVector` to use buffer indexing
3. Update readers and writers

### Related Work

- Original UUID extension type implementation: GH-825 (#903)

Closes #948

Author: jhrotko

performance/src/main/java/org/apache/arrow/vector/UuidVectorBenchmarks.java

@@ -0,0 +1,134 @@
+/*
+ * 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.arrow.vector;
+
+import java.util.UUID;
+import java.util.concurrent.TimeUnit;
+import org.apache.arrow.memory.BufferAllocator;
+import org.apache.arrow.memory.RootAllocator;
+import org.apache.arrow.vector.complex.impl.UuidWriterImpl;
+import org.apache.arrow.vector.holders.NullableUuidHolder;
+import org.openjdk.jmh.annotations.Benchmark;
+import org.openjdk.jmh.annotations.BenchmarkMode;
+import org.openjdk.jmh.annotations.Mode;
+import org.openjdk.jmh.annotations.OutputTimeUnit;
+import org.openjdk.jmh.annotations.Scope;
+import org.openjdk.jmh.annotations.Setup;
+import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.annotations.TearDown;
+import org.openjdk.jmh.profile.GCProfiler;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.RunnerException;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
+
+/** Benchmarks for {@link UuidVector}. */
+@State(Scope.Benchmark)
+public class UuidVectorBenchmarks {
+  // checkstyle:off: MissingJavadocMethod
+
+  private static final int VECTOR_LENGTH = 10_000;
+
+  private static final int ALLOCATOR_CAPACITY = 1024 * 1024;
+
+  private BufferAllocator allocator;
+
+  private UuidVector vector;
+
+  private UUID[] testUuids;
+
+  @Setup
+  public void prepare() {
+    allocator = new RootAllocator(ALLOCATOR_CAPACITY);
+    vector = new UuidVector("vector", allocator);
+    vector.allocateNew(VECTOR_LENGTH);
+    vector.setValueCount(VECTOR_LENGTH);
+
+    // Pre-generate UUIDs for consistent benchmarking
+    testUuids = new UUID[VECTOR_LENGTH];
+    for (int i = 0; i < VECTOR_LENGTH; i++) {
+      testUuids[i] = new UUID(i, i * 2L);
+    }
+  }
+
+  @TearDown
+  public void tearDown() {
+    vector.close();
+    allocator.close();
+  }
+
+  @Benchmark
+  @BenchmarkMode(Mode.AverageTime)
+  @OutputTimeUnit(TimeUnit.MICROSECONDS)
+  public void setWithHolder() {
+    NullableUuidHolder holder = new NullableUuidHolder();
+    for (int i = 0; i < VECTOR_LENGTH; i++) {
+      vector.get(i, holder);
+      vector.setSafe(i, holder);
+    }
+  }
+
+  @Benchmark
+  @BenchmarkMode(Mode.AverageTime)
+  @OutputTimeUnit(TimeUnit.MICROSECONDS)
+  public void setUuidDirectly() {
+    for (int i = 0; i < VECTOR_LENGTH; i++) {
+      vector.setSafe(i, testUuids[i]);
+    }
+  }
+
+  @Benchmark
+  @BenchmarkMode(Mode.AverageTime)
+  @OutputTimeUnit(TimeUnit.MICROSECONDS)
+  public void setWithWriter() {
+    UuidWriterImpl writer = new UuidWriterImpl(vector);
+    for (int i = 0; i < VECTOR_LENGTH; i++) {
+      writer.writeExtension(testUuids[i]);
+    }
+  }
+
+  @Benchmark
+  @BenchmarkMode(Mode.AverageTime)
+  @OutputTimeUnit(TimeUnit.MICROSECONDS)
+  public void getWithUuidHolder() {
+    NullableUuidHolder holder = new NullableUuidHolder();
+    for (int i = 0; i < VECTOR_LENGTH; i++) {
+      vector.get(i, holder);
+    }
+  }
+
+  @Benchmark
+  @BenchmarkMode(Mode.AverageTime)
+  @OutputTimeUnit(TimeUnit.MICROSECONDS)
+  public void getUuidDirectly() {
+    for (int i = 0; i < VECTOR_LENGTH; i++) {
+      UUID uuid = vector.getObject(i);
+    }
+  }
+
+  public static void main(String[] args) throws RunnerException {
+    Options opt =
+        new OptionsBuilder()
+            .include(UuidVectorBenchmarks.class.getSimpleName())
+            .forks(1)
+            .addProfiler(GCProfiler.class)
+            .build();
+
+    new Runner(opt).run();
+  }
+  // checkstyle:on: MissingJavadocMethod
+}

vector/src/main/java/org/apache/arrow/vector/UuidVector.java

@@ -23,7 +23,9 @@
 import org.apache.arrow.memory.ArrowBuf;
 import org.apache.arrow.memory.BufferAllocator;
 import org.apache.arrow.memory.util.ArrowBufPointer;
+import org.apache.arrow.memory.util.ByteFunctionHelpers;
 import org.apache.arrow.memory.util.hash.ArrowBufHasher;
+import org.apache.arrow.util.Preconditions;
 import org.apache.arrow.vector.complex.impl.UuidReaderImpl;
 import org.apache.arrow.vector.complex.reader.FieldReader;
 import org.apache.arrow.vector.extension.UuidType;
@@ -132,7 +134,8 @@ public int hashCode(int index) {
 
   @Override
   public int hashCode(int index, ArrowBufHasher hasher) {
-    return getUnderlyingVector().hashCode(index, hasher);
+    int start = this.getStartOffset(index);
+    return ByteFunctionHelpers.hash(hasher, this.getDataBuffer(), start, start + UUID_BYTE_WIDTH);
   }
 
   /**
@@ -145,45 +148,31 @@ public int isSet(int index) {
     return getUnderlyingVector().isSet(index);
   }
 
-  /**
-   * Gets the UUID value at the given index as an ArrowBuf.
-   *
-   * @param index the index to retrieve
-   * @return a buffer slice containing the 16-byte UUID
-   * @throws IllegalStateException if the value at the index is null and null checking is enabled
-   */
-  public ArrowBuf get(int index) throws IllegalStateException {
-    if (NullCheckingForGet.NULL_CHECKING_ENABLED && this.isSet(index) == 0) {
-      throw new IllegalStateException("Value at index is null");
-    } else {
-      return getBufferSlicePostNullCheck(index);
-    }
-  }
-
   /**
    * Reads the UUID value at the given index into a NullableUuidHolder.
    *
    * @param index the index to read from
    * @param holder the holder to populate with the UUID data
    */
   public void get(int index, NullableUuidHolder holder) {
-    if (NullCheckingForGet.NULL_CHECKING_ENABLED && this.isSet(index) == 0) {
+    Preconditions.checkArgument(index >= 0, "Cannot get negative index in UUID vector.");
+    if (isSet(index) == 0) {
       holder.isSet = 0;
-    } else {
-      holder.isSet = 1;
-      holder.buffer = getBufferSlicePostNullCheck(index);
+      return;
     }
+    holder.isSet = 1;
+    holder.buffer = getDataBuffer();
+    holder.start = getStartOffset(index);
   }
 
   /**
-   * Reads the UUID value at the given index into a UuidHolder.
+   * Calculates the byte offset for a given index in the data buffer.
    *
-   * @param index the index to read from
-   * @param holder the holder to populate with the UUID data
+   * @param index the index of the UUID value
+   * @return the byte offset in the data buffer
    */
-  public void get(int index, UuidHolder holder) {
-    holder.isSet = 1;
-    holder.buffer = getBufferSlicePostNullCheck(index);
+  public final int getStartOffset(int index) {
+    return index * UUID_BYTE_WIDTH;
   }
 
   /**
@@ -207,7 +196,7 @@ public void set(int index, UUID value) {
    * @param holder the holder containing the UUID data
    */
   public void set(int index, UuidHolder holder) {
-    this.set(index, holder.isSet, holder.buffer);
+    this.set(index, holder.buffer, holder.start);
   }
 
   /**
@@ -217,28 +206,11 @@ public void set(int index, UuidHolder holder) {
    * @param holder the holder containing the UUID data
    */
   public void set(int index, NullableUuidHolder holder) {
-    this.set(index, holder.isSet, holder.buffer);
-  }
-
-  /**
-   * Sets the UUID value at the given index with explicit null flag.
-   *
-   * @param index the index to set
-   * @param isSet 1 if the value is set, 0 if null
-   * @param buffer the buffer containing the 16-byte UUID data
-   */
-  public void set(int index, int isSet, ArrowBuf buffer) {
-    getUnderlyingVector().set(index, isSet, buffer);
-  }
-
-  /**
-   * Sets the UUID value at the given index from an ArrowBuf.
-   *
-   * @param index the index to set
-   * @param value the buffer containing the 16-byte UUID data
-   */
-  public void set(int index, ArrowBuf value) {
-    getUnderlyingVector().set(index, value);
+    if (holder.isSet == 0) {
+      getUnderlyingVector().setNull(index);
+    } else {
+      this.set(index, holder.buffer, holder.start);
+    }
   }
 
   /**
@@ -249,10 +221,12 @@ public void set(int index, ArrowBuf value) {
    * @param sourceOffset the offset in the source buffer where the UUID data starts
    */
   public void set(int index, ArrowBuf source, int sourceOffset) {
-    // Copy bytes from source buffer to target vector data buffer
-    ArrowBuf dataBuffer = getUnderlyingVector().getDataBuffer();
-    dataBuffer.setBytes((long) index * UUID_BYTE_WIDTH, source, sourceOffset, UUID_BYTE_WIDTH);
-    getUnderlyingVector().setIndexDefined(index);
+    Preconditions.checkNotNull(source, "Cannot set UUID vector, the source buffer is null.");
+
+    BitVectorHelper.setBit(getUnderlyingVector().getValidityBuffer(), index);
+    getUnderlyingVector()
+        .getDataBuffer()
+        .setBytes((long) index * UUID_BYTE_WIDTH, source, sourceOffset, UUID_BYTE_WIDTH);
   }
 
   /**
@@ -286,25 +260,34 @@ public void setSafe(int index, UUID value) {
    * @param holder the holder containing the UUID data, or null to set a null value
    */
   public void setSafe(int index, NullableUuidHolder holder) {
-    if (holder != null) {
-      getUnderlyingVector().setSafe(index, holder.isSet, holder.buffer);
-    } else {
+    if (holder == null || holder.isSet == 0) {
       getUnderlyingVector().setNull(index);
+    } else {
+      this.setSafe(index, holder.buffer, holder.start);
     }
   }
 
   /**
    * Sets the UUID value at the given index from a UuidHolder, expanding capacity if needed.
    *
    * @param index the index to set
-   * @param holder the holder containing the UUID data, or null to set a null value
+   * @param holder the holder containing the UUID data
    */
   public void setSafe(int index, UuidHolder holder) {
-    if (holder != null) {
-      getUnderlyingVector().setSafe(index, holder.isSet, holder.buffer);
-    } else {
-      getUnderlyingVector().setNull(index);
-    }
+    this.setSafe(index, holder.buffer, holder.start);
+  }
+
+  /**
+   * Sets the UUID value at the given index by copying from a source buffer, expanding capacity if
+   * needed.
+   *
+   * @param index the index to set
+   * @param buffer the source buffer to copy from
+   * @param start the offset in the source buffer where the UUID data starts
+   */
+  public void setSafe(int index, ArrowBuf buffer, int start) {
+    getUnderlyingVector().handleSafe(index);
+    this.set(index, buffer, start);
   }
 
   /**
@@ -400,15 +383,9 @@ public TransferPair getTransferPair(BufferAllocator allocator) {
     return getTransferPair(this.getField().getName(), allocator);
   }
 
-  private ArrowBuf getBufferSlicePostNullCheck(int index) {
-    return getUnderlyingVector()
-        .getDataBuffer()
-        .slice((long) index * UUID_BYTE_WIDTH, UUID_BYTE_WIDTH);
-  }
-
   @Override
   public int getTypeWidth() {
-    return getUnderlyingVector().getTypeWidth();
+    return UUID_BYTE_WIDTH;
   }
 
   /** {@link TransferPair} for {@link UuidVector}. */