obitools/obitools3
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 66 Wiki Activity

Doxygen documentation corrected and completed.

Browse Source
This commit is contained in:
Celine Mercier
2015-09-30 12:03:46 +02:00
parent 45af8396b8
commit 4b7f2d268b
25 changed files with 670 additions and 689 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
src/obidmscolumn.c
View File

@ -1,12 +1,12 @@
/****************************************************************************
* 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.
* @param column_name The name of the OBIDMS column file.
* @param version_number The version number of the OBIDMS column file.
*
* @return a pointer to the column file name
* @retvalue NULL if an error occurs
*
* ###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.
* @param column_name The name of the OBIDMS column.
*
* @return a pointer to the version file name
* @retvalue NULL if an error occurs
*
* ###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
}