From 9dd2b7f874aebc9461d93a3a2206ff710410d034 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 31 May 2004 05:56:59 +0000 Subject: [PATCH] Se documenta con doxygen lo que faltaba. --- emufs/external_sort/mergefile.h | 39 ++++++++++++++++++++++++++++++--- emufs/external_sort/mergepool.h | 35 ++++++++++++++++++++++++----- 2 files changed, 66 insertions(+), 8 deletions(-) diff --git a/emufs/external_sort/mergefile.h b/emufs/external_sort/mergefile.h index bab305b..6cbf748 100644 --- a/emufs/external_sort/mergefile.h +++ b/emufs/external_sort/mergefile.h @@ -40,26 +40,59 @@ #include +/** 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; - size_t reg_size; - void* next; + 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; +/** 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); +/** Inserta un nuevo dato en el archivo. + * \return 0 si hubo error. + */ int mergefile_push(MERGEFILE* mf, void* data); +/** 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); +/** Espía 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 /* _EXTSORT_MERGEFILE_H_ */ diff --git a/emufs/external_sort/mergepool.h b/emufs/external_sort/mergepool.h index 43503f0..d571dd3 100644 --- a/emufs/external_sort/mergepool.h +++ b/emufs/external_sort/mergepool.h @@ -42,24 +42,49 @@ #include "mergefile.h" #include +/** Pool 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; - size_t reg_size; - CMP_FUNC cmp; - 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; +/** 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); +/** 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); +/** 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 /* _EXTSORT_MERGEPOOL_H_ */ -- 2.43.0