X-Git-Url: https://git.llucax.com/z.facultad/75.06/emufs.git/blobdiff_plain/0c66d96638808a1d1ce87701ef3f7980ccee3e22..6b529d1ba8dc30ef7437503567b537568391dc27:/emufs/external_sort/mergepool.h

diff --git a/emufs/external_sort/mergepool.h b/emufs/external_sort/mergepool.h
index 49dee6a..d571dd3 100644
--- a/emufs/external_sort/mergepool.h
+++ b/emufs/external_sort/mergepool.h
@@ -35,28 +35,57 @@
  *
  */
 
-#ifndef _MERGEPOOL_H_
-#define _MERGEPOOL_H_
+#ifndef _EXTSORT_MERGEPOOL_H_
+#define _EXTSORT_MERGEPOOL_H_
 
+#include "base.h"
 #include "mergefile.h"
+#include <stdlib.h>
 
+/** <em>Pool</em> de archivos temporales para hacer un ordenamiento externo.
+ *  La forma de uso general es, de forma similar al MERGEFILE,
+ *  \ref mergepool_add_file "crear un archivo temporal" ,
+ *  \ref mergepool_append_data "agregarle datos" (repitiendo el proceso varias
+ *  veces creando un lote de archivos temporales) y finalmente ir
+ *  \ref mergepool_pop_min "obteniendo el mínimo valor del lote" hasta que no
+ *  haya más datos.
+ *  \warning Una vez obtenido un dato con mergepool_pop_min() no se pueden
+ *           agregar más archivos temporales ni datos al lote.
+ */
 typedef struct
 {
-	MERGEFILE** pool;
-	size_t      size;
-	enum { INPUT, OUTPUT } mode;
+	MERGEFILE**            pool; /**< Arreglo de archivos temporales. */
+	size_t                 size; /**< Cantidad de archivos que tiene el lote. */
+	size_t                 reg_size; /**< Tamaño del tipo de dato que guarda. */
+	CMP_FUNC               cmp; /**< Función de comparación. */
+	enum { INPUT, OUTPUT } mode; /**< Modo. */
 }
 MERGEPOOL;
 
-MERGEPOOL* mergepool_new();
+/** Crea un nuevo lote de archivos temporales para ordenamiento externo. */
+MERGEPOOL* mergepool_new(size_t reg_size, CMP_FUNC cmp);
 
+/** Libera un lote de archivos temporales para ordenamiento externo. */
 void mergepool_delete(MERGEPOOL* mp);
 
+/** Agrega un nuevo archivo temporal al lote.
+ *  \return puntero al nuevo archivo temporal o 0 si hubo error.
+ */
 MERGEFILE* mergepool_add_file(MERGEPOOL* mp);
 
-int mergepool_append_data(MERGEPOOL* mp, int data);
+/** Agrega un nuevo dato al lote que se almacena en el último archivo creado.
+ *  \pre mergepool_add_file() fue ejecutada (es decir, hay al menos un archivo
+ *       temporal en el lote.
+ *  \return 0 si hubo error.
+ */
+int mergepool_append_data(MERGEPOOL* mp, void* data);
 
-int mergepool_pop_min(MERGEPOOL* mp, int* min);
+/** Obtiene el mínimo dato en el lote, sácandolo de éste.
+ *  \post No se pueden ingresar más archivos o datos al lote.
+ *  \return 0 si hubo error, si no, un puntero al mínimo dato del lote que debe
+ *          ser liberado después de usado.
+ */
+void* mergepool_pop_min(MERGEPOOL* mp);
 
-#endif /* _MERGEPOOL_H_ */
+#endif /* _EXTSORT_MERGEPOOL_H_ */