/*
 * This file is part of the Poliqarp suite.
 * 
 * Copyright (C) 2004-2009 by Instytut Podstaw Informatyki Polskiej
 * Akademii Nauk (IPI PAN; Institute of Computer Science, Polish
 * Academy of Sciences; cf. www.ipipan.waw.pl).  All rights reserved.
 * 
 * This file may be distributed and/or modified under the terms of the
 * GNU General Public License version 2 as published by the Free Software
 * Foundation and appearing in the file gpl.txt included in the packaging
 * of this file.  (See http://www.gnu.org/licenses/translations.html for
 * unofficial translations.)
 * 
 * A commercial license is available from IPI PAN (contact
 * Michal.Ciesiolka@ipipan.waw.pl or ipi@ipipan.waw.pl for more
 * information).  Licensees holding a valid commercial license from IPI
 * PAN may use this file in accordance with that license.
 * 
 * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING
 * THE WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE.
 */

/**
 * @file runs.h
 * @brief On-disk run manipulation routines.
 *
 * This file declares structures and routines that deal with runs (see
 * occurrences.h) stored on disk, allowing user to get current occurrence
 * from each run and fetch the next one.
 */

#ifndef POLIQARP_RUNS_H
#define POLIQARP_RUNS_H

#include <poliqarp-config.h>

#include <sakura/common/bitstream.h>

#include "block-list.h"
#include "occurrences.h"
#include "vector.h"

/**
 * Internal structure - a single run.
 */
struct run;

/**
 * A collection of runs.
 */
struct runs {
   struct run *data;                   /**< The collection proper. */
   FILE *file;                         /**< The underlying file. */
   size_t size;                        /**< Number of runs. */
   size_t block_size;                  /**< Block size of the file. */
   struct free_block_list *block_list; /**< List of free blocks. */
};

/**
 * Creates a collection of runs using information gathered during first
 * stage of index creation. Reads one block from each run into memory
 * and inserts it onto the list of free blocks.
 * @param runs the collection to be created.
 * @param occurrences collection of occurrences.
 * @param block_list list of free blocks.
 */
void runs_create(struct runs *runs, struct occurrences *occurrences,
   struct free_block_list *block_list);

/**
 * Frees all resources associated with a collection of runs.
 * @param runs the collection to be destroyed.
 */
void runs_destroy(struct runs *runs);

/**
 * Retrieves (uncompresses) next occurrence from a run.
 * @param runs the collection of runs.
 * @param which index of the run to fetch occurrence from.
 * @return 0 if the operation succeeded, -1 if there were no more occurrences.
 */
int runs_fetch_occurrence(struct runs *runs, size_t which);

/** 
 * Get the current occurrence from a run.
 * @param runs the collection of runs.
 * @param which index of the occurrence to retrieve.
 * @return the retrieved occurrence.
 */
struct occurrence *runs_get_current(struct runs *runs, size_t which);

#endif /* POLIQARP_RUNS_H */
