Package org.aspectj.org.eclipse.jdt.internal.core.nd

Class RawGrowableArray

java.lang.Object
org.aspectj.org.eclipse.jdt.internal.core.nd.RawGrowableArray
public final class RawGrowableArray extends Object
Implements a growable array of pointers that supports constant-time insertions and removals. Items are inserted at the end of the array, and each insertion hands back a unique identifier that can be used to remove the item quickly at a later time.

The memory format contains a header is as follows: 

 Byte                           Meaning
 --------------------------------------------
 0..3                           Pointer to the growable block. Null if the number of records <= inlineRecordCount
 4..7                           Record [0]
 8..11                  Record [1]
 ...
 k...k+4                        Record [inlineRecordCount-1]
As shown above, the first few records are stored inline with the array. inlineRecordCount is a tunable parameter which may be 0. If there are fewer than inlineRecordCount records, there is no growable block and all records are stored in the header. Storing the first few records in the header is intended as an optimization for very small arrays in the case where small arrays are expected to be a common case. If there are fewer than inlineRecordCount records stored in the array, the size of the array is not stored explicitly. It is computed on demand by searching for the first null entry among the inline records.

The memory format for a growable block is as follows: 

 Byte                           Meaning
 --------------------------------------------
 0..3                           Size of the array, including all inline records. This is also the index at which the next entry will
                                        be inserted
 4..7                           Capacity of this growable block.
 8..11                  Record [n]
 12..15                 Record [n+1]
 ...
 k...k+4                        Record [blockSize-1]

The growable block itself begins with a 4-byte int holding the size of the array, followed by a 4-byte int holding the capacity of the growable block. In the event that the array is larger than RawGrowableArray.GrowableBlockHeader.MAX_GROWABLE_SIZE enough to be using a metablock, there will be multiple growable blocks in use. In this case, the size and capacity stored in the metablock is used for the array and the size and capacity stored in each growable block will be filled in with 0s.

If capacity <= MAX_BLOCK_SIZE then this is a normal block containing a flat array of record pointers starting from the element numbered inlineRecordCount. If capacity > MAX_BLOCK_SIZE then then it is a metablock which holds record pointers to separate growable blocks, each of which holds exactly MAX_BLOCK_SIZE elements.

Every time an element is inserted in the array, the add method returns the element's index. Indices can be used to remove elements in constant time, but will be reassigned by the RawGrowableArray during removes by swapping the removed element with the last element in the array. If the owner of the array is keeping track of indices, it should update the relevant indices on remove.

The array itself is tightly packed. When an element is removed, the last element in the array is swapped into its location. Anyone keeping track of indices may rely on the fact that they are consecutive integers.

These arrays preserve insertion order until the first call to "remove". If element order matters, you should not remove individual elements but should instead destroy and rebuild the entire array.

Element additions and removals run in constant amortized time.

There are a lot of ints and longs used in the implementation of this class. In order to help clarify their function, they get the following suffixes:

  • index - holds an index into the array
  • size - holds a count of the number of indices
  • value - holds one of the pointer values inserted into the array
  • address - holds a pointer into the database (refers to a full 8-byte long, not the compressed 4-byte version)
  • bytes - holds the size (in bytes) of something in the database
  • block - holds a block number (in the case where a metablock is in use, the growable blocks are identified by block numbers).
  • blockCount - holds a number of blocks

  • Constructor Summary

    Constructors
    Constructor
    Description
    RawGrowableArray​(int inlineRecords)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    add​(Nd nd, long address, long value)
    Adds the given value to the array.
    void
    destruct​(Nd nd, long address)
     
    void
    ensureCapacity​(Nd nd, long address, int desiredSize)
    Ensures that the array contains at least enough space allocated to fit the given number of new elements.
    long
    get​(Nd nd, long address, int index)
    Returns the element at the given index (nonzero).
    int
    getCapacity​(Nd nd, long address)
     
    static int
    getMaxGrowableBlockSize()
     
    int
    getRecordSize()
    Returns the record size for a RawGrowableSize with the given number of inline records
    boolean
    isEmpty​(Nd nd, long address)
    Returns true iff the size of the array is 0
    long
    remove​(Nd nd, long address, int index)
    Removes an entry from the array, given an element index.
    int
    size​(Nd nd, long address)
    Returns the size of the array.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • RawGrowableArray

      public RawGrowableArray​(int inlineRecords)

  • Method Details

    • getMaxGrowableBlockSize

      public static int getMaxGrowableBlockSize()

    • size

      public int size​(Nd nd, long address)
      Returns the size of the array.
      Parameters:
      address - address of the array
      Returns:
      the array size, in number elements

    • add

      public int add​(Nd nd, long address, long value)
      Adds the given value to the array. Returns an index which can be later passed into remove in order to remove the element at a later time.

    • get

      public long get​(Nd nd, long address, int index)
      Returns the element at the given index (nonzero). The given index must be < size().

    • ensureCapacity

      public void ensureCapacity​(Nd nd, long address, int desiredSize)
      Ensures that the array contains at least enough space allocated to fit the given number of new elements.

    • remove

      public long remove​(Nd nd, long address, int index)
      Removes an entry from the array, given an element index. If the given index is not the last element in the list, the last element will have its index swapped with the removed element. If another element was swapped into the position of the removed element, this returns the value of that element. Otherwise, it returns 0.

    • getRecordSize

      public int getRecordSize()
      Returns the record size for a RawGrowableSize with the given number of inline records

    • destruct

      public void destruct​(Nd nd, long address)

    • isEmpty

      public boolean isEmpty​(Nd nd, long address)
      Returns true iff the size of the array is 0
      Parameters:
      address - address of the array
      Returns:
      the array size, in number elements

    • getCapacity

      public int getCapacity​(Nd nd, long address)