org.apache.arrow.memory.AllocationReservation Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of arrow-memory Show documentation
Core off-heap memory management libraries for Arrow ValueVectors.
There is a newer version: 18.0.0
/*
 * 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.memory;

import io.netty.buffer.ArrowBuf;

/**
 * Supports cumulative allocation reservation. Clients may increase the size of the reservation
 * repeatedly until they
 * call for an allocation of the current total size. The reservation can only be used once, and
 * will throw an exception
 * if it is used more than once.
 * 
 * For the purposes of airtight memory accounting, the reservation must be close()d whether it is
 * used or not.
 * This is not threadsafe.
 * 
 */
public interface AllocationReservation extends AutoCloseable {

  /**
   * Add to the current reservation.
   *
   * Adding may fail if the allocator is not allowed to consume any more space.
   *
   * @param nBytes the number of bytes to add
   * @return true if the addition is possible, false otherwise
   * @throws IllegalStateException if called after buffer() is used to allocate the reservation
   */
  boolean add(final int nBytes);

  /**
   * Requests a reservation of additional space.
   *
   * The implementation of the allocator's inner class provides this.
   *
   * @param nBytes the amount to reserve
   * @return true if the reservation can be satisfied, false otherwise
   */
  boolean reserve(int nBytes);

  /**
   * Allocate a buffer whose size is the total of all the add()s made.
   *
   * The allocation request can still fail, even if the amount of space
   * requested is available, if the allocation cannot be made contiguously.
   *
   * @return the buffer, or null, if the request cannot be satisfied
   * @throws IllegalStateException if called called more than once
   */
  ArrowBuf allocateBuffer();

  /**
   * Get the current size of the reservation (the sum of all the add()s).
   *
   * @return size of the current reservation
   */
  int getSize();

  /**
   * Return whether or not the reservation has been used.
   *
   * @return whether or not the reservation has been used
   */
  public boolean isUsed();

  /**
   * Return whether or not the reservation has been closed.
   *
   * @return whether or not the reservation has been closed
   */
  public boolean isClosed();

  public void close();
}