/*
 * 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 block-list.h
 * @brief List of free blocks in a file.
 *
 * This is basically a standard singly linked list, used to store the numbers
 * of free blocks in a file (a list of size_t-ints). One notable feature is that
 * it has an underlying vector, which maps logical to physical numbers of 
 * blocks, updated on-the-fly as blocks are allocated from this list.
 */

#ifndef POLIQARP_BLOCK_LIST_H
#define POLIQARP_BLOCK_LIST_H

#include <stdio.h>

#include "vector.h"

/** 
 * Internal structure: the element of a list.
 */
struct free_block_list_elem;

/**
 * List of free blocks.
 */
struct free_block_list {
   struct free_block_list_elem *head;  /**< First element of the list. */
   struct vector *map;                 /**< Logical to physical map. */
   FILE *file;                         /**< File associated with this list. */
   size_t block_size;                  /**< Size of the block. */
};

/**
 * Creates a block list.
 * @param list the list to be created.
 * @param file file associated with this list.
 * @param block_size size of a single block.
 * @param map map of physical numbers of allocated blocks.
 */
void free_block_list_create(struct free_block_list *list, FILE *file,
   size_t block_size, struct vector *map);

/** 
 * Frees all resources allocated to a block list. Does not close the
 * file nor destroy the block map.
 * @param list the list to be destroyed.
 */
void free_block_list_destroy(struct free_block_list *list);

/**
 * Appends a block onto the start of a list.
 * @param list the block list.
 * @param block number of the block to append.
 */
void free_block_list_append(struct free_block_list *list, size_t block);

/**
 * Allocates a block from the list, removing it. If there's no free block,
 * this function creates one by appending it to the end of the file.
 * The block map is updated appropriately.
 * @param list the list to allocate a block from.
 * @return number of an allocated block.
 */
size_t free_block_list_alloc(struct free_block_list *list);

#endif /* POLIQARP_BLOCK_LIST_H */
