Paso el fin de línea a formato Unix (perdon tenia que verlo para estudiar :P).

[z.facultad/75.06/emufs.git] / emufs / external_sort / mergefile.h

diff --git a/emufs/external_sort/mergefile.h b/emufs/external_sort/mergefile.h
index 44c5fdd7b381629f7212b3ce79f11b35974cb2be..6cbf74802114c7a2d062ed297d27bb6263bc0582 100644 (file)
--- a/emufs/external_sort/mergefile.h
+++ b/emufs/external_sort/mergefile.h
@@ -22,7 +22,7 @@
  * Autores: Leandro Lucarella <llucare@fi.uba.ar>
  *----------------------------------------------------------------------------
  *
- * $Id: tipo1.h 542 2004-05-28 19:45:02Z rmarkie $
+ * $Id$
  *
  */
 
@@ -35,32 +35,65 @@
  *
  */
 
-#ifndef _MERGEFILE_H_
-#define _MERGEFILE_H_
+#ifndef _EXTSORT_MERGEFILE_H_
+#define _EXTSORT_MERGEFILE_H_
 
 #include <stdio.h>
 
+/** Archivo temporal con un fragmento ordenado.
+ *  Es una especie de cola almacenada en un archivo temporal. El modo de
+ *  utilización es el siguiente: primero \ref mergefile_push "se lo llena" ,
+ *  luego \ref mergefile_switch_to_input "lo pasa a modo de lectura" y
+ *  finalmente se van \ref mergefile_pop "obteniendo los valores" en el mismo
+ *  órden en que se los insertó. A diferencia de una cola regular, primero se
+ *  insertan todos los valores y luego se los extrae.
+ */
 typedef struct
 {
-       FILE* fp;
-       int   next;
-       int   more;
+       FILE*  fp; /**< Puntero al archivo donde almacenar los datos. */
+       size_t reg_size; /**< Tamaño del registro a almacenar. */
+       void*  next; /**< Buffer con el próximo dato a obtener. */
 }
 MERGEFILE;
 
-MERGEFILE* mergefile_new();
+/** Crea un nuevo archivo temporal para ordenamiento externo. */
+MERGEFILE* mergefile_new(size_t reg_size);
 
+/** Libera un archivo temporal para ordenamiento externo. */
 void mergefile_delete(MERGEFILE* mf);
 
+/** Pasa a modo lectura el archivo.
+ *  Antes de efectuar cualquier tipo de lectura (mergefile_pop() o
+ *  mergefile_peek()) hay que llamar a esta función.
+ *  \return 0 si hubo error.
+ */
 int mergefile_switch_to_input(MERGEFILE* mf);
 
-int mergefile_push(MERGEFILE* mf, int data);
+/** Inserta un nuevo dato en el archivo.
+ *  \return 0 si hubo error.
+ */
+int mergefile_push(MERGEFILE* mf, void* data);
 
-int mergefile_pop(MERGEFILE* mf);
+/** Obtiene el próximo dato en el archivo, sacándolo de éste.
+ *  \pre mergefile_switch_to_input() fue ejecutada.
+ *  \return 0 si hubo error, si no, un puntero al próximo dato que debe ser
+ *          liberado después de usado.
+ */
+void* mergefile_pop(MERGEFILE* mf);
 
-int mergefile_peek(MERGEFILE* mf);
+/** <em>Espía</em> el próximo dato en el archivo sin sacarlo.
+ *  \pre mergefile_switch_to_input() fue ejecutada.
+ *  \return 0 si hubo error, si no, un puntero al próximo dato que no debe ser
+ *          liberado hasta que se quite el dato del archivo con mergefile_pop()
+ *          definitivamente.
+ */
+void* mergefile_peek(MERGEFILE* mf);
 
+/** Verifica si quedan más datos para leer en el archivo.
+ *  \pre mergefile_switch_to_input() fue ejecutada.
+ *  \return 0 si no hay más.
+ */
 int mergefile_has_more(MERGEFILE* mf);
 
-#endif /* _MERGEFILE_H_ */
+#endif /* _EXTSORT_MERGEFILE_H_ */