org.apache.flink.runtime.state.gemini.engine.page.PageIndex Maven / Gradle / Ivy
/*
* 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.flink.runtime.state.gemini.engine.page;
import org.apache.flink.annotation.Internal;
import org.apache.flink.runtime.state.gemini.engine.snapshot.RegionSnapshot;
import java.io.IOException;
import java.util.Collection;
import java.util.Iterator;
import java.util.Map;
/**
* PageIndex is the metadata of all pages in Gemini, which belongs to {@link PageStore}.
* It consists of a array of {@link LogicalPageChain} where each chained page includes multi data page address.
*/
@Internal
public interface PageIndex {
/**
* Returns the page index context to which the key belongs,
* and create the target logical chained page if not found while {@code createIfMissing} is true.
*
* @param key The key to query.
* @param createIfMissing Flag indicates whether to create the new logical chained page if not found.
* @return The page index context to which the key belongs.
*/
PageIndexContext getPageIndexContext(K key, boolean createIfMissing);
/**
* Expand current array size of logical chained pages, previous elements must be copied to the new array.
*/
void expand();
/**
* Shrink the current array size of logical chained pages.
*
* NOTICE: it's still undefined of how to remove previous redundant logical chained pages.
*/
void shrink();
/**
* Snapshot all page indices to given region snapshots.
*
* @param regionSnapshots The given region snapshots, which might be consisted of DFS and local regions.
* @throws IOException
*/
void snapshot(Collection regionSnapshots) throws IOException;
/**
* Update the page status at target page index.
*
* @param pageId The page index to update.
* @param expectedStatus The expected page status.
* @param targetStatus The target page status.
* @return
*/
boolean updateLogicPageStatus(int pageId, PageStatus expectedStatus, PageStatus targetStatus);
/**
* Copy all page address with their data pages in this page index to the given map and return a new page index.
*
* Currently, we would "duplicate" the data page as map values to offer flexibility
* in case we could let page address mutable during snapshot.
*
*
This method would call {@link LogicalPageChain#copy(Map)} recursively.
*
* @param copiedDataPage A data page container, all data pages will be added into this container.
* @return The copied page index.
*/
PageIndex copy(Map copiedDataPage);
/**
* Remove logic page at the given logical page id.
*
* @param logicPageId the given logical page id.
*/
void removeLogicPage(int logicPageId);
/**
* Returns the logic chained page at given logic page id.
*
* @param logicPageId The given logic page id.
* @return The logic chained page at given logic page id.
*/
LogicalPageChain getLogicPage(int logicPageId);
/**
* Update the {@code targetLogicPage} at given logic page id.
*
* @param logicPageId The given logic page id.
* @param targetLogicPage The target logic page wants to be updated.
*/
void updateLogicPage(int logicPageId, LogicalPageChain targetLogicPage);
/**
* Creates a new empty logical page chain with current default chain length of this page index.
*
* @return a new empty logical page chain with current default chain length of this page index.
*/
LogicalPageChain createLogicalPageChain();
/**
* Returns the iterator of non-null page address of all chained pages within this page index.
*
* @return The iterator of non-null page address of all chained pages within this page index.
*/
Iterator pageIterator();
/**
* Returns current capacity of the array of logical chained pages.
*
* @return current capacity of the array of logical chained pages.
*/
int getIndexCapacity();
/**
* Returns all the logical chained pages.
*
* @return all the logical chained pages.
*/
LogicalPageChain[] getPageIndex();
}