/*
 * 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/indexCheckpoint.h#1 $
 */

#ifndef INDEX_CHECKPOINT_H
#define INDEX_CHECKPOINT_H

#include "index.h"

/**
 * Construct and initialize the checkpoint sub-structure of an index.
 *
 * @param index  the index receive the new checkpoint structure.
 *
 * @return UDS_SUCCESS or an error code
 **/
int makeIndexCheckpoint(Index *index) __attribute__((warn_unused_result));

/**
 * Free the checkpoint sub-structure of an index.
 *
 * @param checkpoint  the structure to free
 **/
void freeIndexCheckpoint(IndexCheckpoint *checkpoint);

/**
 * Get the current checkpointing frequency of an index.
 *
 * @param checkpoint  the checkpoint state of the index
 *
 * @return the number of chapters between checkpoints
 **/
unsigned int getIndexCheckpointFrequency(IndexCheckpoint *checkpoint)
  __attribute__((warn_unused_result));

/**
 * Set checkpointing frequency for the index.
 *
 * @param checkpoint  the checkpoint state of the index
 * @param frequency   The new checkpointing frequency
 *
 * @return the old checkpointing frequency
 **/
unsigned int setIndexCheckpointFrequency(IndexCheckpoint *checkpoint,
                                         unsigned int     frequency);

/**
 * Gets the number of checkpoints completed during the lifetime of this index
 *
 * @param checkpoint  the checkpoint state of the index
 *
 * @return            the number of checkpoints completed
 **/
uint64_t getCheckpointCount(IndexCheckpoint *checkpoint)
  __attribute__((warn_unused_result));

/**
 * If incremental checkpointing is in progress, finish it.
 *
 * @param index     The index
 *
 * @return          UDS_SUCCESS or an error code
 *
 * @note        This function is called automatically during normal operation;
 *              its presence here is for tests that expect checkpointing to
 *              have completed at some point in their logic.  It is not an
 *              error to call this function if checkpointing is not in
 *              progress, it silently returns success.
 **/
int finishCheckpointing(Index *index) __attribute__((warn_unused_result));

/**
 * Process one zone's incremental checkpoint operation. Automatically
 * starts, processes, and finishes a checkpoint over multiple invocations
 * as successive chapters are closed and written.
 *
 * Uses its own mutex to serialize the starting and finishing or aborting,
 * but allows parallel execution of the incremental progress.
 *
 * @param index             The index to checkpoint
 * @param zone              The current zone number
 * @param newVirtualChapter The number of the chapter which the calling
 *                          zone has just opened
 *
 * @return UDS_SUCCESS or an error code.
 **/
int processCheckpointing(Index        *index,
                         unsigned int  zone,
                         uint64_t      newVirtualChapter)
  __attribute__((warn_unused_result));

/**
 * Process saves done outside any zone by the chapter writer.
 *
 * Grabs the mutex associated with processCheckpointing().
 *
 * @param index         The index to process.
 *
 * @return UDS_SUCCESS or an error code.
 **/
int processChapterWriterCheckpointSaves(Index *index)
  __attribute__((warn_unused_result));

#endif // INDEX_CHECKPOINT_H