emufs/external_sort/mergefile.h

   1 /* vim: set noexpandtab tabstop=4 shiftwidth=4:
   2  *----------------------------------------------------------------------------
   3  *                                  emufs
   4  *----------------------------------------------------------------------------
   5  * This file is part of emufs.
   6  *
   7  * emufs is free software; you can redistribute it and/or modify it under the
   8  * terms of the GNU General Public License as published by the Free Software
   9  * Foundation; either version 2 of the License, or (at your option) any later
  10  * version.
  11  *
  12  * emufs is distributed in the hope that it will be useful, but WITHOUT ANY
  13  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  14  * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
  15  * details.
  16  *
  17  * You should have received a copy of the GNU General Public License along
  18  * with emufs; if not, write to the Free Software Foundation, Inc., 59 Temple
  19  * Place, Suite 330, Boston, MA  02111-1307  USA
  20  *----------------------------------------------------------------------------
  21  * Creado:  dom may 30 04:57:18 ART 2004
  22  * Autores: Leandro Lucarella <llucare@fi.uba.ar>
  23  *----------------------------------------------------------------------------
  24  *
  25  * $Id$
  26  *
  27  */
  28
  29 /** \file
  30  *
  31  * Archivo temporal con un fragmento ordenado del archivo original.
  32  *
  33  * Interfaz de un archivo temporal con un fragmento ordenado del archivo
  34  * original utilizado para hacer el ordenamiento por fusión (merge sort).
  35  *
  36  */
  37
  38 #ifndef _EXTSORT_MERGEFILE_H_
  39 #define _EXTSORT_MERGEFILE_H_
  40
  41 #include <stdio.h>
  42
  43 /** Archivo temporal con un fragmento ordenado.
  44  *  Es una especie de cola almacenada en un archivo temporal. El modo de
  45  *  utilización es el siguiente: primero \ref mergefile_push "se lo llena" ,
  46  *  luego \ref mergefile_switch_to_input "lo pasa a modo de lectura" y
  47  *  finalmente se van \ref mergefile_pop "obteniendo los valores" en el mismo
  48  *  órden en que se los insertó. A diferencia de una cola regular, primero se
  49  *  insertan todos los valores y luego se los extrae.
  50  */
  51 typedef struct
  52 {
  53         FILE*  fp; /**< Puntero al archivo donde almacenar los datos. */
  54         size_t reg_size; /**< Tamaño del registro a almacenar. */
  55         void*  next; /**< Buffer con el próximo dato a obtener. */
  56 }
  57 MERGEFILE;
  58
  59 /** Crea un nuevo archivo temporal para ordenamiento externo. */
  60 MERGEFILE* mergefile_new(size_t reg_size);
  61
  62 /** Libera un archivo temporal para ordenamiento externo. */
  63 void mergefile_delete(MERGEFILE* mf);
  64
  65 /** Pasa a modo lectura el archivo.
  66  *  Antes de efectuar cualquier tipo de lectura (mergefile_pop() o
  67  *  mergefile_peek()) hay que llamar a esta función.
  68  *  \return 0 si hubo error.
  69  */
  70 int mergefile_switch_to_input(MERGEFILE* mf);
  71
  72 /** Inserta un nuevo dato en el archivo.
  73  *  \return 0 si hubo error.
  74  */
  75 int mergefile_push(MERGEFILE* mf, void* data);
  76
  77 /** Obtiene el próximo dato en el archivo, sacándolo de éste.
  78  *  \pre mergefile_switch_to_input() fue ejecutada.
  79  *  \return 0 si hubo error, si no, un puntero al próximo dato que debe ser
  80  *          liberado después de usado.
  81  */
  82 void* mergefile_pop(MERGEFILE* mf);
  83
  84 /** <em>Espía</em> el próximo dato en el archivo sin sacarlo.
  85  *  \pre mergefile_switch_to_input() fue ejecutada.
  86  *  \return 0 si hubo error, si no, un puntero al próximo dato que no debe ser
  87  *          liberado hasta que se quite el dato del archivo con mergefile_pop()
  88  *          definitivamente.
  89  */
  90 void* mergefile_peek(MERGEFILE* mf);
  91
  92 /** Verifica si quedan más datos para leer en el archivo.
  93  *  \pre mergefile_switch_to_input() fue ejecutada.
  94  *  \return 0 si no hay más.
  95  */
  96 int mergefile_has_more(MERGEFILE* mf);
  97
  98 #endif /* _EXTSORT_MERGEFILE_H_ */
  99