Class BlockTable


  • public class BlockTable
    extends java.lang.Object
    A block table is like a page table for blocks in a blender file.

    A block table provides access to Blocks of a given BlenderFile instance based on memory addresses (see BlockHeader.getAddress()) and supports in instantiation of new blocks.

    All blocks of a block table have the same encoding which is also the same encoding used by the entire blender file (see Encoding and BlenderFile).

    Blocks in a block list are ordered by their address to improve lookup performance. Blocks in a blender file have to be stored in a different order which is supposed to be maintained in a BlockList (required only when writing to .blend files).

    To support allocation of blocks and issue addresses to them, the block table has access to an Allocator.

    A block table may or may not reference so-called offheap areas (see OffheapAreas). Each offheap area contains a list of blocks of a specific struct type. When retrieving a block for a given address, the block table uses the SDNA index to potentially search the assigned offheap area, for the block by an exact match of the start address. If no offheap area exists for the given struct type, it will search the block in regular heap area.

    Author:
    homac
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.Comparator<? super Block> BLOCKS_ASCENDING_ADDRESS
      This comparator can be used with methods such as Collections.sort(List, Comparator) to sort blocks ascending by address.
    • Constructor Summary

      Constructors 
      Constructor Description
      BlockTable​(Encoding encoding)
      Instantiates a new block table with the given encoding.
      BlockTable​(Encoding encoding, java.util.List<Block> blocks, int[] offheapStructs)
      Instantiates a new block table with the given encoding and initialises it with the blocks of the given list.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void add​(Block block)
      Method to add a block to the ascending sorted list.
      Block allocate​(Identifier blockCode, int size)
      This method allocates memory and assigns it to a block with the given code.
      Block allocate​(Identifier code, long size)
      This method allocates memory on heap and assigns it to a new block with the given code.
      Block allocate​(Identifier blockCode, long size, int sdnaIndex, int count)
      This method allocates memory for 'count' structs of type 'sdnaIndex' and assigns it to a new block with the given blockCode.
      boolean exists​(long address)
      Determines if a block, which contains this address, exists on heap.
      boolean exists​(long startAddress, int sdnaIndex)
      Determines if a block with this startAddress exists either on or off heap.
      Block findBlock​(long startAddress)
      Returns the block, which is associated with the given start address.
      void free​(Block block)
      This method removes the given block from the block list, and releases its allocated memory region (to be available for allocation again).
      Allocator getAllocator()
      Returns the allocator used by this block table.
      protected Block getBlock​(long address)
      Returns the block which contains the given address.
      Block getBlock​(long address, int sdnaIndex)
      Returns the block which contains the given address.
      Block getBlock​(long address, java.lang.Class<?> type)
      returns the block which contains the data of the given address and type (struct or scalar).
      Block getBlock​(long address, java.lang.Class<?>[] type)
      Returns the block for a given address and type (array, pointer, struct or scalar).
      java.util.List<Block> getBlocks​(Identifier blockCode)
      Returns a list of blocks which have the given block code.
      void getBlocks​(Identifier blockCode, java.util.List<Block> list)
      Retrieve all blocks with the given block code which are on heap.
      java.util.List<Block> getBlocksSorted()
      This method returns the internal list of blocks which are on heap and sorted by their address.
      Encoding getEncoding()  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • BLOCKS_ASCENDING_ADDRESS

        public static final java.util.Comparator<? super Block> BLOCKS_ASCENDING_ADDRESS
        This comparator can be used with methods such as Collections.sort(List, Comparator) to sort blocks ascending by address.
    • Constructor Detail

      • BlockTable

        public BlockTable​(Encoding encoding)
        Instantiates a new block table with the given encoding.
      • BlockTable

        public BlockTable​(Encoding encoding,
                          java.util.List<Block> blocks,
                          int[] offheapStructs)
        Instantiates a new block table with the given encoding and initialises it with the blocks of the given list.
        Parameters:
        encoding -
        offheapStructs - List of SDNA indices which are in offheap areas
        blocks - to be inserted in the new block table.
    • Method Detail

      • getBlock

        public Block getBlock​(long address,
                              java.lang.Class<?>[] type)
        Returns the block for a given address and type (array, pointer, struct or scalar).
      • getBlock

        public Block getBlock​(long address,
                              java.lang.Class<?> type)
        returns the block which contains the data of the given address and type (struct or scalar).
      • getBlock

        public Block getBlock​(long address,
                              int sdnaIndex)
        Returns the block which contains the given address. The sdnaIndex is required to access offheap areas. The method identifies whether the struct is in an offheap area or not. If the data is know to be on heap, sdnaIndex can be -1 too.
      • getBlock

        protected Block getBlock​(long address)
        Returns the block which contains the given address.
      • findBlock

        public Block findBlock​(long startAddress)
        Returns the block, which is associated with the given start address. Thus, it will only return a block which has an exact match with the given address.
        Parameters:
        startAddress - Start address of the block to search for.
        Returns:
        The block associated with the given address or null if none was found.
      • allocate

        public Block allocate​(Identifier blockCode,
                              int size)
        This method allocates memory and assigns it to a block with the given code.
      • add

        protected void add​(Block block)
        Method to add a block to the ascending sorted list.
      • allocate

        public Block allocate​(Identifier blockCode,
                              long size,
                              int sdnaIndex,
                              int count)
        This method allocates memory for 'count' structs of type 'sdnaIndex' and assigns it to a new block with the given blockCode.
      • allocate

        public Block allocate​(Identifier code,
                              long size)
        This method allocates memory on heap and assigns it to a new block with the given code.

        Note: If you have declared offheap areas, and want to allocate a block for a struct which is declared to be offheap, then use the method allocate(Identifier, long, int, int) instead!

        Parameters:
        code - Block code to be assigned to the block
        size - Size of the block body in bytes.
        Returns:
        Allocated block.
        See Also:
        allocate(Identifier, long, int, int)
      • free

        public void free​(Block block)
        This method removes the given block from the block list, and releases its allocated memory region (to be available for allocation again).
      • exists

        public boolean exists​(long address)
        Determines if a block, which contains this address, exists on heap.

        Use exists(long, int) to check offheap areas too.

        See Also:
        exists(long, int)
      • exists

        public boolean exists​(long startAddress,
                              int sdnaIndex)
        Determines if a block with this startAddress exists either on or off heap.
      • getEncoding

        public Encoding getEncoding()
        Returns:
        encoding used by all blocks of this block table.
      • getBlocks

        public java.util.List<Block> getBlocks​(Identifier blockCode)
        Returns a list of blocks which have the given block code.
      • getBlocks

        public void getBlocks​(Identifier blockCode,
                              java.util.List<Block> list)
        Retrieve all blocks with the given block code which are on heap. This does not include offheap areas!
      • getAllocator

        public Allocator getAllocator()
        Returns the allocator used by this block table.

        This allocator does not know about offheap areas.

      • getBlocksSorted

        public java.util.List<Block> getBlocksSorted()
        This method returns the internal list of blocks which are on heap and sorted by their address.

        Please note, that the list of blocks returned by this method is sorted by block.header.address and does not contain blocks from offheap areas. If you are looking for the complete list of blocks in their original sequence in the file than refer to BlenderFile.getBlocks()