Package org.apache.flink.runtime.io.network.partition.hybrid.tiered.storage

Interface TieredStorageMemoryManager

All Known Implementing Classes:
TieredStorageMemoryManagerImpl
public interface TieredStorageMemoryManager
The TieredStorageMemoryManager is to request or recycle buffers from LocalBufferPool for different memory owners, for example, the tiers, the buffer accumulator, etc. Note that the logic for requesting and recycling buffers is consistent for these owners.

The buffers managed by TieredStorageMemoryManager is categorized into two types: non-reclaimable buffers which cannot be immediately released and reclaimable buffers which can be reclaimed quickly and safely. Non-reclaimable buffers necessitates waiting for other operations to complete before releasing it, such as downstream consumption. On the other hand, reclaimable buffers can be freed up at any time, enabling rapid memory recycling for tasks such as flushing memory to disk or remote storage.

The TieredStorageMemoryManager does not provide strict memory limitations on any user can request. Instead, it only simply provides memory usage hints to memory users. It is very important to note that only users with non-reclaimable should check the memory hints by calling getMaxNonReclaimableBuffers before requesting buffers.

The TieredStorageMemoryManager needs to ensure that it would not hinder reclaimable users from acquiring buffers due to non-reclaimable users not releasing the buffers they have requested. So it is very important to note that only users with non-reclaimable should call ensureCapacity before requesting buffers to reserve enough buffers.

  • Method Details

    • setup

      void setup(BufferPool bufferPool, List<TieredStorageMemorySpec> storageMemorySpecs)
      Setup the TieredStorageMemoryManager. When setting up the manager, the TieredStorageMemorySpecs for different tiered storages should be ready to indicate each tiered storage's memory requirement specs.
      Parameters:
      bufferPool - the local buffer pool
      storageMemorySpecs - the memory specs for different tiered storages

    • setMetricGroup

      void setMetricGroup(TaskIOMetricGroup metricGroup)
      Set the TaskIOMetricGroup for this memory manager.
      Parameters:
      metricGroup - the metric group to set

    • listenBufferReclaimRequest

      void listenBufferReclaimRequest(Runnable onBufferReclaimRequest)
      Register a listener to listen the buffer reclaim request from the TieredStorageMemoryManager.

      When the left buffers in the BufferPool are not enough, TieredStorageMemoryManager will try to reclaim the buffers from the memory owners.

      Parameters:
      onBufferReclaimRequest - a Runnable to process the buffer reclaim request

    • getBufferPool

      BufferPool getBufferPool()
      Expose and get the internal BufferPool. Please note that this method is a temporary workaround for the remote tier plugin and may be removed at any time in the future. We strongly advise that users do not rely on this method.

    • requestBufferBlocking

      BufferBuilder requestBufferBlocking(Object owner)
      Request a BufferBuilder instance for a specific owner. The TieredStorageMemoryManagerImpl will not check whether a buffer can be requested. The manager only records the number of requested buffers. If the buffers is not enough to meet the request, the manager will request each tiered storage to reclaim their requested buffers as much as possible.

      This is not thread safe and is expected to be called only from the task thread.

      Parameters:
      owner - the owner to request buffer
      Returns:
      the requested buffer

    • getMaxNonReclaimableBuffers

      int getMaxNonReclaimableBuffers(Object owner)
      Return the number of the non-reclaimable buffers for the owner.

      Note that the available buffers are calculated dynamically based on some conditions, for example, the state of the BufferPool, the TieredStorageMemorySpec of the owner, etc. So the caller should always check before requesting non-reclaimable buffers.

      When invoking this method, the caller should be aware that the return value may occasionally be negative. This is due to the possibility of the buffer pool size shrinking to a point where it is smaller than the buffers owned by other users. In such cases, the maximum non-reclaimable buffer value returned may be negative.

    • ensureCapacity

      boolean ensureCapacity(int numAdditionalBuffers)
      Try best to reserve enough buffers that are guaranteed reclaimable along with the additional ones.

      Note that the available buffers are calculated dynamically based on some conditions, for example, the state of the BufferPool, the TieredStorageMemorySpec of the owner, etc. So the caller should always ensure capacity before requesting non-reclaimable buffers.

      Parameters:
      numAdditionalBuffers - the number of buffers that need to also be reserved in addition to guaranteed reclaimable buffers.
      Returns:
      True if the capacity meets the requirements, false otherwise.

    • numOwnerRequestedBuffer

      int numOwnerRequestedBuffer(Object owner)
      Return the number of requested buffers belonging to a specific owner.
      Parameters:
      owner - the owner of requesting buffers
      Returns:
      the number of requested buffers belonging to the owner.

    • transferBufferOwnership

      void transferBufferOwnership(Object oldOwner, Object newOwner, Buffer buffer)
      Notify the memory manager that transferring one buffer's ownership from the old owner to the new owner.
      Parameters:
      oldOwner - the old owner of one buffer
      newOwner - the new owner of one buffer
      buffer - the buffer to transfer the ownership

    • release

      void release()
      Release all the resources(if exists) and check the state of the TieredStorageMemoryManager.