/*

 * 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