content: /*
   * 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;
  
  /**
   * 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.
   *
   * <p>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.
     *
     * <p>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
     * @deprecated use {@link #add(long)} instead
     */
    @Deprecated(forRemoval = true)
    boolean add(int nBytes);
  
    /**
     * Add to the current reservation.
     *
     * <p>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(long nBytes);
  
    /**
     * Requests a reservation of additional space.
     *
     * <p>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
     * @deprecated use {@link #reserve(long)} instead
     */
    @Deprecated(forRemoval = true)
    boolean reserve(int nBytes);
  
    /**
     * Requests a reservation of additional space.
     *
     * <p>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(long nBytes);
  
    /**
     * Allocate a buffer whose size is the total of all the add()s made.
     *
     * <p>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 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();
  
    /**
     * Get the current size of the reservation (the sum of all the add()s) as a long value.
     *
     * @return size of the current reservation
     */
    long getSizeLong();
  
    /**
     * Return whether or not the reservation has been used.
     *
     * @return whether or not the reservation has been used
     */
    boolean isUsed();
  
    /**
     * Return whether or not the reservation has been closed.
     *
     * @return whether or not the reservation has been closed
     */
    boolean isClosed();
  
    @Override
    void close();
  }
  