/*
 * Copyright (c) 2020 Red Hat, Inc.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA. 
 *
 * $Id: //eng/uds-releases/jasper/src/uds/indexPageMap.h#2 $
 */

#ifndef INDEX_PAGE_MAP_H
#define INDEX_PAGE_MAP_H 1

#include "common.h"
#include "geometry.h"
#include "indexComponent.h"

extern const IndexComponentInfo INDEX_PAGE_MAP_INFO;

typedef struct indexPageMap IndexPageMap;

typedef struct {
  unsigned int lowestList;
  unsigned int highestList;
} IndexPageBounds;

/*
 *  Notes on IndexPageMap
 *
 *  Each volume maintains an index page map which records how the chapter delta
 *  lists are distributed among the index pages for that chapter.
 *
 *  The map is conceptually a two-dimensional array indexed by chapter number
 *  and index page number within the chapter.  Each entry contains the number
 *  of the last delta list on that index page.  In order to save memory, the
 *  information for the last page in each chapter is not recorded, as it is
 *  known from the geometry.
 */

typedef uint16_t IndexPageMapEntry;

struct indexPageMap {
  const Geometry         *geometry;
  uint64_t                lastUpdate;
  IndexPageMapEntry      *entries;
};

/**
 * Create an index page map.
 *
 * @param geometry     The geometry governing the index.
 * @param mapPtr       A pointer to hold the new map.
 *
 * @return             A success or error code.
 **/
int makeIndexPageMap(const Geometry *geometry, IndexPageMap **mapPtr)
  __attribute__((warn_unused_result));

/**
 * Free an index page map.
 *
 * @param map  The index page map to destroy.
 **/
void freeIndexPageMap(IndexPageMap *map);

/**
 * Get the virtual chapter number of the last update to the index page map.
 *
 * @param map   The index page map
 *
 * @return the virtual chapter number of the last chapter updated
 **/
uint64_t getLastUpdate(const IndexPageMap *map);

/**
 * Update an index page map entry.
 *
 * @param map                   The map to update
 * @param virtualChapterNumber  The virtual chapter number being updated.
 * @param chapterNumber         The chapter of the entry to update
 * @param indexPageNumber       The index page of the entry to update
 * @param deltaListNumber       The value of the new entry
 *
 * @return UDS_SUCCESS or an error code
 **/
int updateIndexPageMap(IndexPageMap    *map,
                       uint64_t         virtualChapterNumber,
                       unsigned int     chapterNumber,
                       unsigned int     indexPageNumber,
                       unsigned int     deltaListNumber)
  __attribute__((warn_unused_result));

/**
 * Find the page number of the index page in a chapter that will contain the
 * chapter index entry for a given chunk name, if it exists.
 *
 * @param [in]  map                 The map to search
 * @param [in]  name                The chunk name
 * @param [in]  chapterNumber       The chapter containing the index page
 * @param [out] indexPageNumberPtr  A pointer to hold the result, guaranteed to
 *                                  be a valid index page number on UDS_SUCCESS
 *
 * @return UDS_SUCCESS, or UDS_INVALID_ARGUMENT if the chapter number
 *         is out of range
 **/
int findIndexPageNumber(const IndexPageMap *map,
                        const UdsChunkName *name,
                        unsigned int        chapterNumber,
                        unsigned int       *indexPageNumberPtr)
  __attribute__((warn_unused_result));

/**
 * Get the lowest and highest numbered delta lists for the given immutable
 * chapter index page from the index page map.
 *
 * @param map             The index page map
 * @param chapterNumber   The chapter containing the delta list
 * @param indexPageNumber The index page number within the chapter
 * @param bounds          A structure to hold the list number bounds
 *                        for the given page
 *
 * @return UDS_SUCCESS or an error code
 **/
int getListNumberBounds(const IndexPageMap *map,
                        unsigned int        chapterNumber,
                        unsigned int        indexPageNumber,
                        IndexPageBounds    *bounds)
  __attribute__((warn_unused_result));

/**
 * Compute the size of the index page map save image, including all headers.
 *
 * @param geometry      The index geometry.
 *
 * @return The number of bytes required to save the index page map.
 **/
uint64_t computeIndexPageMapSaveSize(const Geometry *geometry);

/**
 * Escaped for testing....
 *
 * @param geometry      The index geometry.
 *
 * @return              The number of bytes required for the page map data,
 *                      exclusive of headers.
 **/
size_t indexPageMapSize(const Geometry *geometry)
  __attribute__((warn_unused_result));

#endif // INDEX_PAGE_MAP_H