Skip to content

GitLab

O
OBITools3
Commit 4b7f2d26 authored by Celine Mercier's avatar Celine Mercier
Browse files
Options

Doxygen documentation corrected and completed.

parent 45af8396
Hide whitespace changes
Inline Side-by-side
Showing with 669 additions and 688 deletions
src/obidebug.h
View file @ 4b7f2d26
/*
* obidebug.h
*
* Created on: June 25th 2015
* Author: Celine Mercier (celine.mercier@metabarcoding.org)
/****************************************************************************
* Header file for the debugging code *
****************************************************************************/
/**
* @file obidebug.h
* @author Celine Mercier (celine.mercier@metabarcoding.org)
* @date 25 June 2015
* @brief Header file for the debugging code.
*/
......@@ -12,7 +16,7 @@
#include <limits.h>
//#ifndef DEBUG_LEVEL
//#ifndef DEBUG_LEVEL // TODO
//#define DEBUG_LEVEL MAXINT
//#endif
......
src/obidms.c
View file @ 4b7f2d26
/*
* obidms.c
*
* @date 23 May 2015
* @Author: coissac
/********************************************************************
* OBIDMS functions *
********************************************************************/
/**
* @file obidms.c
* @author Eric Coissac (eric.coissac@metabarcoding.org)
* @date 23 May 2015
* @brief OBIDMS functions.
*/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
......@@ -18,7 +23,7 @@
#include "obidmscolumn.h"
#define DEBUG_LEVEL 0
#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?)
/**************************************************************************
......@@ -29,27 +34,22 @@
/**
* Internal function building the directory name from an OBIDMS name.
* Internal function building the OBIDMS directory name from an OBIDMS name.
*
* The function builds the directory name corresponding to an OBIDMS.
* It checks also that the name is not too long.
* It also checks that the name is not too long.
*
* @warning The returned pointer has to be freed by the caller.
*
* @param dms_name the name of the OBIDMS
*
* @return a pointer to the directory name
* @retvalue <directory_name> if everything is ok
* @retvalue NULL if an error occurs
* @param dms_name The name of the OBIDMS.
*
* ###Error values
* - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation.
* - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit.
* @returns A pointer to the directory name.
* @retval NULL if an error occurred.
*
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
static char *build_directory_name(const char *dms_name);
static char* build_directory_name(const char* dms_name);
/************************************************************************
......@@ -58,9 +58,9 @@ static char *build_directory_name(const char *dms_name);
*
************************************************************************/
static char *build_directory_name(const char *dms_name)
static char* build_directory_name(const char* dms_name)
{
char *directory_name;
char* directory_name;
// Build the database directory name
if (asprintf(&directory_name, "%s.obidms", dms_name) < 0)
......
src/obidms.h
View file @ 4b7f2d26
/*
* obidms.h
*
* Created on: 23 mai 2015
* Author: coissac
/********************************************************************
* OBIDMS header file *
********************************************************************/
/**
* @file obidmscolumn.h
* @author Eric Coissac (eric.coissac@metabarcoding.org)
* @date 23 May 2015
* @brief Header file for the OBIDMS functions and structures.
*/
#ifndef OBIDMS_H_
#define OBIDMS_H_
#include <stdlib.h>
#include <sys/stat.h>
#include <errno.h>
......@@ -17,38 +23,37 @@
#include "obierrno.h"
#define OBIDMS_MAX_NAME (2048) /**< The maximum length of an OBIDMS name
*/
/** @brief A structure describing an OBIDMS instance
/**
* @brief A structure describing an OBIDMS instance
*
* A pointer to this structure is returned on creation
* and opening of an OBITools Data Management System (DMS)
*/
typedef struct OBIDMS {
char directory_name[OBIDMS_MAX_NAME+1]; /**< The name of the directory
* containing the DMS
* containing the DMS.
*/
DIR* directory; /**< A directory entry usable to
* refer and scan the database directory
* refer and scan the database directory.
*/
} OBIDMS_t, *OBIDMS_p;
/*@
* @brief Checks if an OBIDMS exists
/**
* @brief Checks if an OBIDMS exists.
*
* @param dms_name a pointer to a C string containing the name of the database.
* The actual directory name used to store the DMS will be
* `<dms_name>.obidms`.
* @param dms_name A pointer to a C string containing the name of the database.
*
* @return an integer value indicating the status of the database
* @retvalue 1 the database exist
* @retvalue 0 the database does not exist
* @retvalue -1 an error occurred
* @returns An integer value indicating the status of the database
* @retval 1 if the database exists.
* @retval 0 if the database does not exist.
* @retval -1 if an error occurred.
*
* @see obi_close_dms()
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
......@@ -62,79 +67,62 @@ int obi_dms_exists(const char* dms_name);
* if a directory with this name does not already exist
* before creating the new database.
*
* @param dms_name a pointer to a C string containing the name of the database.
* The actual directory name used to store the DMS will be
* `<name>.obidms`
* @param dms_name A pointer to a C string containing the name of the database.
* The actual directory name used to store the DMS will be
* `<dms_name>.obidms`.
*
* @return a pointer to an OBIDMS structure describing the newly created DMS
* @retval NULL on error and the `obi_errno` variable is set.
*
* ###Error values
* - OBIDMS_EXIST_ERROR : a database with the same name already exists.
* - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit.
* - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation.
* @returns A pointer to an OBIDMS structure describing the newly created DMS.
* @retval NULL if an error occurred.
*
* @see obi_close_dms()
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
OBIDMS_p obi_create_dms(const char *dms_name);
OBIDMS_p obi_create_dms(const char* dms_name);
/**
* @brief Opens an existing OBITools Data Management instance (OBIDMS).
*
* @param dms_name a pointer to a C string containing the name of the database.
* The actual directory name used to store the DMS will be
* `<name>.obidms`
*
* @return a pointer to an OBIDMS structure describing the newly created DMS
* @retval NULL on error and the `obi_errno`variable is set.
* @param dms_name A pointer to a C string containing the name of the database.
*
* ###Error values
* - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit.
* - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation.
* @returns A pointer to an OBIDMS structure describing the opened DMS.
* @retval NULL if an error occurred.
*
* @see obi_close_dms()
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
OBIDMS_p obi_open_dms(const char *dms_name);
OBIDMS_p obi_open_dms(const char* dms_name);
/**
* @brief Creates a new OBIDMS instance.
* @brief Creates or opens a new OBIDMS instance.
*
* If the database already exists, this function opens it, otherwise it
* creates a new database.
*
* @param dms_name a pointer to a C string containing the name of the database.
* The actual directory name used to store the DMS is
* `<name>.obidms`
*
* @return a pointer to an OBIDMS structure describing the newly created DMS
* @retval NULL on error and the `obi_errno`variable is set.
* @param dms_name A pointer to a C string containing the name of the database.
*
* ###Error values
* - OBIDMS_LONG_NAME_ERROR : the database name exceeds the limit.
* - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation.
* @returns A pointer to an OBIDMS structure describing the OBIDMS.
* @retval NULL if an error occurred.
*
* @see obi_close_dms()
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
OBIDMS_p obi_dms(const char *dms_name);
OBIDMS_p obi_dms(const char* dms_name);
/**
* @brief Closes an opened OBITools Data Management instance (OBIDMS).
*
* @param dms a pointer as returned by obi_create_dms() or obi_open_dms()
* @param dms A pointer as returned by obi_create_dms() or obi_open_dms().
*
* @return an integer value indicating the success of the operation. Even on
* error, the `OBIDMS` structure is freed
* @retvalue 0 on success
* @retvalue -1 on failure and the `obi_errno` variable is set.
* @returns An integer value indicating the success of the operation. Even on
* error, the `OBIDMS` structure is freed.
* @retval 0 on success.
* @retval -1 if an error occurred?-.
*
* @see obi_create_dms()
* @see obi_open_dms()
......
src/obidmscolumn.c
View file @ 4b7f2d26
/****************************************************************************
* OBIDMS_column functions *
* OBIDMS columns functions *
****************************************************************************/
/**
* @file obidmscolumn.c
* @author Celine Mercier
* @author Celine Mercier (celine.mercier@metabarcoding.org)
* @date 22 May 2015
* @brief Functions for the shared elements of all the OBIColumn structures.
* @brief Functions shared by all the OBIDMS columns.
*/
......@@ -19,7 +19,7 @@
#include <fcntl.h>
#include <stdbool.h>
#include <math.h>
#include <sys/mman.h> /* mmap() is defined in this header */
#include <sys/mman.h>
#include "obidmscolumn.h"
#include "obidmscolumndir.h"
......@@ -30,7 +30,7 @@
#include "obilittlebigman.h"
#define DEBUG_LEVEL 0
#define DEBUG_LEVEL 0 // TODO has to be defined somewhere else (cython compil flag?)
/**************************************************************************
......@@ -47,18 +47,16 @@
*
* @warning The returned pointer has to be freed by the caller.
*
* @param column_name the name of the OBIDMS column.
*
* @return a pointer to the column file name
* @retvalue NULL if an error occurs
* @param column_name The name of the OBIDMS column file.
* @param version_number The version number of the OBIDMS column file.
*
* ###Error values
* - OBIDMS_MEMORY_ERROR : something wrong occurred during memory allocation.
* @returns A pointer to the column file name.
* @retval NULL if an error occurred.
*
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
static char *build_column_file_name(const char *column_name, obiversion_t version_number);
static char* build_column_file_name(const char* column_name, obiversion_t version_number);
/**
......@@ -69,32 +67,28 @@ static char *build_column_file_name(const char *column_name, obiversion_t versio
*
* @warning The returned pointer has to be freed by the caller.
*
* @param column_name the name of the OBIDMS column.
*
* @return a pointer to the version file name
* @retvalue NULL if an error occurs
* @param column_name The name of the OBIDMS column.
*
* ###Error values
* - OBIDMS_MEMORY_ERROR : something wrong occurs during memory allocation.
* @returns A pointer to the version file name.
* @retval NULL if an error occurred.
*
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
static char *build_version_file_name(const char *column_name);
static char* build_version_file_name(const char* column_name);
/**
* @brief Internal function returning a new column version number
* in the `dms` database
* in the OBIDMS database.
*
* @param dms a pointer as returned by obi_create_dms() or obi_open_dms()
* @param column_name the name of the column
* @param block is the call is blocking or not
* - `true` the call is blocking
* - `false` the call is not blocking
* @param column_directory A pointer as returned by obi_create_column_directory() or obi_open_column_directory().
* @param block Whether the call is blocking or not:
* - `true` the call is blocking
* - `false` the call is not blocking.
*
* @return the bigger version number used for this column
* @retvalue -1 if the column does not exist
* @returns The next version number for this column.
* @retval -1 if an error occurred.
*
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
......@@ -104,50 +98,50 @@ static obiversion_t obi_get_new_version_number(OBIDMS_column_directory_p column_
/**
* @brief Internal function creating a new column version file
* in the `dms` database
* in the OBIDMS database.
*
* The new file is initialized with the minimum version number `0`.
*
* @param dms a pointer as returned by obi_create_dms() or obi_open_dms()
* @param column_name the name of the column
* @param column_directory A pointer as returned by obi_create_column_directory() or obi_open_column_directory().
*
* @return the next usable version number for this column : `0`
* @retvalue -1 if the column does not exist
* @returns The next usable version number for this column : `0`.
* @retval -1 if an error occurred.
*
* @since May 2015
* @author Eric Coissac (eric.coissac@metabarcoding.org)
*/
static int create_version_file(OBIDMS_column_directory_p column_directory);
static obiversion_t create_version_file(OBIDMS_column_directory_p column_directory);
/**
* @brief Internal function setting the elements names of the lines of a
* column in the header of the OBIDMS column structure.
* column in the header of the OBIDMS column structure.
*
* @param column a pointer as returned by obi_create_column()
* @param elements_names the names of the elements with ';' as separator
* @param column A pointer as returned by obi_create_column().
* @param elements_names The names of the elements with ';' as separator.
*
* @return 0 if the operation was successfully completed
* @retvalue -1 if an error occurred
* @retval 0 if the operation was successfully completed.
* @retval -1 if an error occurred.
*
* @since July 2015
* @author Celine Mercier (celine.mercier@metabarcoding.org)
*/
int obi_column_set_elements_names(OBIDMS_column_p column, const char* elements_names);
static int obi_column_set_elements_names(OBIDMS_column_p column, const char* elements_names);
/**
* @brief Internal function computing how many lines of an OBIDMS column fill in a memory page.
* @brief Internal function computing how many lines of an OBIDMS column
* fit in a memory page.
*
* @param data_type the data OBIType
* @param nb_elements_per_line the number of elements per line
* @param data_type The data OBIType.
* @param nb_elements_per_line The number of elements per line.
*
* @return the line count for one memory page
* @returns The line count for one memory page.
*
* @since September 2015
* @author Celine Mercier (celine.mercier@metabarcoding.org)
*/
size_t get_line_count_per_page(OBIType_t data_type, size_t nb_elements_per_line);
static size_t get_line_count_per_page(OBIType_t data_type, size_t nb_elements_per_line);
/************************************************************************
......@@ -232,10 +226,10 @@ static obiversion_t obi_get_new_version_number(OBIDMS_column_directory_p column_
else
{
obi_set_errno(OBICOL_UNKNOWN_ERROR);
obidebug(1, "\nError opening a version file");
free(version_file_name);
return -1;
}
obidebug(1, "\nError opening a version file");
free(version_file_name);
}
// Test if the version file size is ok
......@@ -346,7 +340,7 @@ static obiversion_t obi_get_new_version_number(OBIDMS_column_directory_p column_
}
static int create_version_file(OBIDMS_column_directory_p column_directory)
static obiversion_t create_version_file(OBIDMS_column_directory_p column_directory)
{
off_t loc_size;
obiversion_t version_number;
......@@ -652,7 +646,6 @@ OBIDMS_column_p obi_create_column(OBIDMS_p dms,
nb_lines = minimum_line_count;
// The number of elements names should be equal to the number of elements per line
if ((elements_names == NULL) && (nb_elements_per_line > 1))
{
obidebug(1, "\nCan't create column because no elements names were given for a number of elements per line greater than 1");
......@@ -723,6 +716,7 @@ OBIDMS_column_p obi_create_column(OBIDMS_p dms,
if (column_file_descriptor < 0)
{
obi_set_errno(OBICOL_UNKNOWN_ERROR);
obidebug(1, "\nError opening a column file");
free(column_file_name);
return NULL;
}
......@@ -800,11 +794,11 @@ OBIDMS_column_p obi_create_column(OBIDMS_p dms,
header->creation_date = time(NULL);
header->version = version_number;
header->cloned_from = -1;
header->comments[0] = 0x0;
header->comments[0] = 0x0; // TODO
obi_column_set_elements_names(new_column, elements_names);
strncpy(header->name, column_name, OBIDMS_MAX_COLNAME);
strncpy(header->name, column_name, OBIDMS_COLUMN_MAX_NAME);
// Fill the data with NA values
obi_ini_to_NA_values(new_column, 0, nb_lines);
......@@ -816,7 +810,9 @@ OBIDMS_column_p obi_create_column(OBIDMS_p dms,
}
OBIDMS_column_p obi_open_column(OBIDMS_p dms, const char* column_name, obiversion_t version_number)
OBIDMS_column_p obi_open_column(OBIDMS_p dms,
const char* column_name,
obiversion_t version_number)
{
OBIDMS_column_p column;
OBIDMS_column_directory_p column_directory;
......@@ -941,7 +937,10 @@ OBIDMS_column_p obi_open_column(OBIDMS_p dms, const char* column_name, obiversio
}
OBIDMS_column_p obi_clone_column(OBIDMS_p dms, const char* column_name, obiversion_t version_number, bool clone_data)
OBIDMS_column_p obi_clone_column(OBIDMS_p dms,
const char* column_name,
obiversion_t version_number,
bool clone_data)
{
OBIDMS_column_p column_to_clone;
OBIDMS_column_p new_column;
......@@ -1032,7 +1031,7 @@ int obi_close_column(OBIDMS_column_p column)
}
int obi_truncate_column_to_lines_used(OBIDMS_column_p column)
int obi_truncate_column_to_lines_used(OBIDMS_column_p column) // TODO is it necessary to unmap/remap?
{
size_t file_size;
size_t data_size;
......@@ -1193,7 +1192,8 @@ int obi_enlarge_column(OBIDMS_column_p column)
return -1;
}
// Remap the data: try enlarging mapped region (this actually never works on my mac without the MAP_FIXED flag which overwrites everything)
// Remap the data: try enlarging mapped region (TODO this actually never works on my mac without the MAP_FIXED flag which overwrites everything)
// TODO : makes separate function even if it's only used here?
//obidebug(2, "\ntry enlarging mapped region: old size = %ld, new size = %ld, size = %ld", old_data_size, new_data_size, new_data_size - old_data_size);
new_data = mmap(column->data,
new_data_size - old_data_size,
......@@ -1267,7 +1267,9 @@ int obi_truncate_and_close_column(OBIDMS_column_p column)
}
void obi_ini_to_NA_values(OBIDMS_column_p column, size_t start, size_t nb_lines)
void obi_ini_to_NA_values(OBIDMS_column_p column,
size_t start,
size_t nb_lines)
{
size_t i, end, nb_elements;
......@@ -1311,7 +1313,7 @@ void obi_ini_to_NA_values(OBIDMS_column_p column, size_t start, size_t nb_lines)
}
void obi_column_make_unwritable(OBIDMS_column_p column)
void obi_column_make_unwritable(OBIDMS_column_p column) // TODO this might be irrelevant
{
column->writable = false;
}
......@@ -1410,7 +1412,7 @@ OBIType_t obi_column_get_data_type_from_name(OBIDMS_p dms, const char* column_na
return -1;
}
// Check endianness?
// TODO Check endianness?
data_type = header->data_type;
......@@ -1496,7 +1498,7 @@ size_t obi_column_get_line_count_from_name(OBIDMS_p dms, const char* column_name
return -1;
}
// Check endianness?
// TODO Check endianness?
line_count = header->line_count;
......@@ -1524,7 +1526,7 @@ size_t obi_column_get_element_index_from_name(OBIDMS_column_p column, const char
if (elements_names == NULL)
{
obidebug(1, "\nError strdup-ing the elements names");
return -1;
return SIZE_MAX; //TODO
}
element_index = 0;
......@@ -1550,7 +1552,7 @@ size_t obi_column_get_element_index_from_name(OBIDMS_column_p column, const char
obidebug(1, "\nCan't find an element name");
free(elements_names);
return -1;
return SIZE_MAX; //TODO
}
......
src/obidmscolumn.h
View file @ 4b7f2d26
/****************************************************************************
* OBIDMS_column header file *
* OBIDMS columns header file *
****************************************************************************/
/**
* @file obidmscolumn.h
* @author Celine Mercier
* @author Celine Mercier (celine.mercier@metabarcoding.org)
* @date 12 May 2015
* @brief Header file for the shared elements of all the OBIDMS column structures.
* @brief Header file for the functions and structures shared by all the OBIDMS columns.
*/
#ifndef OBIDMSCOLUMN_H_
#define OBIDMSCOLUMN_H_
......@@ -25,64 +26,76 @@
#include "obilittlebigman.h"
#include "obidmscolumndir.h"
#define ELEMENTS_NAMES_MAX (2048)
#define GROWTH_FACTOR (2)
#define MAXIMUM_LINE_COUNT (1000000)
#define ELEMENTS_NAMES_MAX (2048) /**< The maximum length of the list of elements names.
*/
#define GROWTH_FACTOR (2) /**< The growth factor when a column is enlarged.
*/
#define MAXIMUM_LINE_COUNT (1000000) /**< The maximum line count for the data of a column. //TODO
*/
typedef int32_t obiversion_t; /**< Used to store the column version number
*/
/**
* @brief OBIColumnHeader structure.
* @brief OBIDMS column header structure.
*/
typedef struct OBIDMS_column_header {
bool little_endian; /**< endianness of the column:
* - `true` on little endian platforms
* - `false` on big endian platforms
*
* @see obi_is_little_endian()
*/
int header_size; /**< size of the header in bytes */
size_t line_count; /**< number of lines of data */
size_t lines_used; /**< number of lines of data used */
size_t nb_elements_per_line; /**< number of elements per line (default : 1) */
char elements_names[ELEMENTS_NAMES_MAX+1]; /**< names of the line elements (default : "["column_name"]") */
OBIType_t data_type; /**< type of the data */
time_t creation_date; /**< date of creation of the file */
obiversion_t version; /**< version of the OBIColumn */
obiversion_t cloned_from; /**< version of the OBIColumn from which the column was cloned from (-1 if it does not come from cloning).*/
char name[OBIDMS_MAX_COLNAME+1]; /**< The column name as a NULL
* terminated string.
*/