obidmscolumn.h 12.6 KB
Newer Older
Celine Mercier's avatar
Celine Mercier committed
1
/****************************************************************************
2
 * OBIDMS columns header file                                               *
Celine Mercier's avatar
Celine Mercier committed
3 4 5 6
 ****************************************************************************/

/**
 * @file obidmscolumn.h
7
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
Celine Mercier's avatar
Celine Mercier committed
8
 * @date 12 May 2015
9
 * @brief Header file for the functions and structures shared by all the OBIDMS columns.
Celine Mercier's avatar
Celine Mercier committed
10 11
 */

12

Celine Mercier's avatar
Celine Mercier committed
13 14 15 16 17 18 19
#ifndef OBIDMSCOLUMN_H_
#define OBIDMSCOLUMN_H_

#include <stdio.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdbool.h>
Eric Coissac's avatar
Eric Coissac committed
20
#include <time.h>
21
#include <stdbool.h>
Celine Mercier's avatar
Celine Mercier committed
22

23 24 25 26
#include "obidms.h"
#include "obitypes.h"
#include "obierrno.h"
#include "obilittlebigman.h"
27
#include "obidmscolumndir.h"
Celine Mercier's avatar
Celine Mercier committed
28
#include "obiblob_indexer.h"
Celine Mercier's avatar
Celine Mercier committed
29

30

31 32
#define ELEMENTS_NAMES_MAX (2048)     	/**< The maximum length of the list of elements names.
                                	     */
33
#define COLUMN_GROWTH_FACTOR (2)	 	/**< The growth factor when a column is enlarged.
34
                                	   	 */
35
#define MAXIMUM_LINE_COUNT (1000000000) /**< The maximum line count for the data of a column. //TODO
36
                                	     */
37
#define COMMENTS_MAX_LENGTH (2048)      /**< The maximum length for comments.
38
 	 	 	 	 	 	 	 	 	     */
39

40

Celine Mercier's avatar
Celine Mercier committed
41
/**
42
 * @brief OBIDMS column header structure.
Celine Mercier's avatar
Celine Mercier committed
43
 */
44
typedef struct OBIDMS_column_header {
45
	size_t			header_size;		   				    /**< Size of the header in bytes.
46
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
47 48
	size_t			data_size;			   				    /**< Size of the data in bytes.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
49
	index_t			line_count;							    /**< Number of lines of data allocated.
50
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
51
	index_t			lines_used;							    /**< Number of lines of data used.
52
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
Celine Mercier's avatar
Celine Mercier committed
53
	index_t			nb_elements_per_line;   			   	/**< Number of elements per line.
54 55 56 57
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	char			elements_names[ELEMENTS_NAMES_MAX+1];	/**< Names of the line elements with ';' as separator
															 *	 (should be the column name if one element per line).
															 */
58 59 60 61 62
	OBIType_t		returned_data_type;		    			/**< Type of the data that is returned when getting an
															 *   element from the column.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	OBIType_t		stored_data_type;		    			/**< Type of the data that is actually stored in the data
															 *   part of the column.
63 64 65 66 67 68 69 70 71 72 73
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	time_t			creation_date;			    			/**< Date of creation of the file.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	obiversion_t	version;				   				/**< Version of the column.
	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
	obiversion_t	cloned_from;			    			/**< Version of the column from which this column
															 *   was cloned from (-1 if it was not created by cloning
															 *   another column).
															 */
	char            name[OBIDMS_COLUMN_MAX_NAME+1]; 	    /**< The column name as a NULL terminated string.
	                                             	 	 	 */
Celine Mercier's avatar
Celine Mercier committed
74
	char            indexer_name[INDEXER_MAX_NAME+1]; 		/**< If there is one, the indexer name as a NULL terminated string.
75
	                                             	 	 	 */
76
	char 			comments[COMMENTS_MAX_LENGTH+1];		/**< Comments stored as a classical zero end C string.
77
												 	 	 	 */
78
} OBIDMS_column_header_t, *OBIDMS_column_header_p;
Celine Mercier's avatar
Celine Mercier committed
79

80

Eric Coissac's avatar
Eric Coissac committed
81
/**
82
 * @brief OBIDMS column structure.
Eric Coissac's avatar
Eric Coissac committed
83 84
 *
 * A data structure of this type is returned by the functions
85
 * creating, opening or cloning an OBIDMS column.
Eric Coissac's avatar
Eric Coissac committed
86
 */
87
typedef struct OBIDMS_column {
88 89 90 91 92 93
	OBIDMS_p                	dms;			 	/**< A pointer to the OBIDMS structure to which the column belongs.
	 	 	 	 	 	 	 	 	 	 	 	 	 */
	OBIDMS_column_directory_p   column_directory;	/**< A pointer to the OBIDMS column directory structure to which the column belongs.
	 	 	 	 	 	 	 	 	 	 	 	 	 */
	OBIDMS_column_header_p		header; 		 	/**< A pointer to the header of the column.
	 	 	 	 	 	 	 	 	 	 	 	 	 */
Celine Mercier's avatar
Celine Mercier committed
94
	Obi_indexer_p    			indexer;		    /**< A pointer to the blob indexer associated with the column if there is one.
95
	 	 	 	 	 	 	 	 	 	 	 	 	 */
96
	void*                   	data;   		 	/**< A `void` pointer to the beginning of the data.
97
	                                 	 	         *
98 99
													 *   @warning Never use this member directly outside of the code of the
													 *            low level functions of the OBIDMS.
100
													 */
Celine Mercier's avatar
Celine Mercier committed
101
	bool						writable;	     	/**< Indicates if the column is writable or not.
102 103 104 105 106 107
													 *       - `true` the column is writable
													 *       - `false` the column is read-only
													 *
													 * A column is writable only by its creator
													 * until it closes it.
													 */
108 109
	size_t						counter;			/**< Indicates by how many threads/programs (TODO) the column is used.
													 */
110 111
} OBIDMS_column_t, *OBIDMS_column_p;

Eric Coissac's avatar
Eric Coissac committed
112

113
/**
114 115 116
 * @brief Returns the latest version number of a column in a column directory using the column directory structure.
 *
 * @param column_directory A pointer as returned by obi_create_column_directory() or obi_open_column_directory().
117
 *
118 119
 * @returns The latest version number kept in the version file.
 * @retval -1 if an error occurred.
120
 *
121 122
 * @since May 2015
 * @author Eric Coissac (eric.coissac@metabarcoding.org)
123 124 125 126 127
 */
obiversion_t obi_get_latest_version_number(OBIDMS_column_directory_p column_directory);


/**
128 129 130 131
 * @brief Returns the latest version of a column in a column directory using the column name.
 *
 * @param dms A pointer on an OBIDMS.
 * @param column_name The column name.
132
 *
133 134
 * @returns The latest version number kept in the version file.
 * @retval -1 if an error occurred.
135
 *
136 137
 * @since May 2015
 * @author Eric Coissac (eric.coissac@metabarcoding.org)
138 139 140 141
 */
obiversion_t obi_column_get_latest_version_from_name(OBIDMS_p dms, const char* column_name);


Eric Coissac's avatar
Eric Coissac committed
142
/**
143
 * @brief Returns the header size in bytes of a column on this platform.
Eric Coissac's avatar
Eric Coissac committed
144
 *
145
 * The header size is defined as a multiple of the memory page size.
146
 * As of now the header size is defined as one time the page size.
Eric Coissac's avatar
Eric Coissac committed
147
 *
148
 * @returns The header size in bytes.
Eric Coissac's avatar
Eric Coissac committed
149 150 151 152 153 154 155 156
 *
 * @since May 2015
 * @author Eric Coissac (eric.coissac@metabarcoding.org)
 */
size_t obi_get_platform_header_size();


/**
157
 * @brief Creates a column.
Eric Coissac's avatar
Eric Coissac committed
158
 *
159
 * The minimum data size allocated is one memory page, and the data is initialized to the NA value of the OBIType.
Celine Mercier's avatar
Celine Mercier committed
160
 * If there is an indexer associated with the column, it is opened or created if it does not already exist.
161 162 163 164 165 166 167
 *
 * @warning If there is one element per line, elements_names should be equal to column_name.	// TODO change this condition?
 *
 * @param dms A pointer on an OBIDMS.
 * @param column_name The name of the new column.
 * @param data_type The OBIType code of the data.
 * @param nb_lines The number of lines to be stored.
168
 * @param nb_elements_per_line The number of elements per line.								// TODO talk about default values
169
 * @param elements_names The names of the elements with ';' as separator.
Celine Mercier's avatar
Celine Mercier committed
170
 * @param indexer_name The name of the indexer if there is one associated with the column.
171
 * @param comments Optional comments associated with the column.
172 173 174
 *
 * @returns A pointer on the newly created column structure.
 * @retval NULL if an error occurred.
Eric Coissac's avatar
Eric Coissac committed
175 176 177 178
 *
 * @since May 2015
 * @author Eric Coissac (eric.coissac@metabarcoding.org)
 */
179
OBIDMS_column_p obi_create_column(OBIDMS_p dms,
180
		                          const char* column_name,
181
								  OBIType_t data_type,
182 183
								  index_t nb_lines,
								  index_t nb_elements_per_line,
184
								  const char* elements_names,
Celine Mercier's avatar
Celine Mercier committed
185
								  const char* indexer_name,
Celine Mercier's avatar
Celine Mercier committed
186 187
								  const char* comments
								 );
Eric Coissac's avatar
Eric Coissac committed
188 189 190


/**
191
 * @brief Opens a column in read-only mode.
Eric Coissac's avatar
Eric Coissac committed
192
 *
193 194 195
 * @param dms A pointer on an OBIDMS.
 * @param column_name The name of the column.
 * @param version_number The version of the column that should be opened (if -1, the latest version is retrieved).
196
 *
197 198
 * @returns A pointer on the opened column structure.
 * @retval NULL if an error occurred.
Eric Coissac's avatar
Eric Coissac committed
199
 *
200 201
 * @since July 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
Eric Coissac's avatar
Eric Coissac committed
202
 */
203 204 205
OBIDMS_column_p obi_open_column(OBIDMS_p dms, const char* column_name, obiversion_t version_number);


206 207 208
/**
 * @brief Clones a column, and returns a pointer to the writable new column.
 *
209 210 211 212
 * @param dms A pointer on an OBIDMS.
 * @param column_name The name of the column to clone.
 * @param version_number The version of the column that should be cloned (if -1, the latest version is retrieved).
 * @param clone_data Whether the data should be copied or not.
213
 *
214 215
 * @returns A pointer to the created column.
 * @retval NULL if an error occurred.
216 217 218 219
 *
 * @since August 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Celine Mercier's avatar
Celine Mercier committed
220
OBIDMS_column_p obi_clone_column(OBIDMS_p dms, OBIDMS_column_p line_selection, const char* column_name, obiversion_t version_number, bool clone_data);
221 222


223
/**
224
 * @brief Truncates a column to the number of lines used if it is not read-only and closes it.
225
 *
226
 * @param column A pointer on an OBIDMS column.
227
 *
228 229
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
230 231 232 233 234 235 236
 *
 * @since July 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_close_column(OBIDMS_column_p column);


237
/**
238 239
 * @brief Truncates a column file to the number of lines used rounded to the nearest
 * 		  greater multiple of the page size.
240
 *
241
 * @param column A pointer on an OBIDMS column.
242
 *
243 244
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
245 246 247 248
 *
 * @since August 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
249
int obi_truncate_column(OBIDMS_column_p column);
250 251


252 253 254
/**
 * @brief Enlarges a column file.
 *
255
 * @param column A pointer on an OBIDMS column.
256
 *
257 258
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
259 260 261 262 263 264 265 266
 *
 * @since August 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int obi_enlarge_column(OBIDMS_column_p column);


/*
267
 * @brief Sets the data in a column to the NA value of the data OBIType.
268
 *
269 270 271
 * @param column A pointer on an OBIDMS column.
 * @param start The first line number of the block that should be set.
 * @param nb_lines The number of lines that should be set.
272 273 274 275
 *
 * @since August 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
276
void obi_ini_to_NA_values(OBIDMS_column_p column, index_t first_line_nb, index_t nb_lines);	// TODO make private?
277 278


279
/**
280 281 282
 * @brief Recovers the header of an OBIDMS column from the column name.
 *
 * @warning The header structure has to be munmapped by the caller.
283
 *
284 285
 * @param dms A pointer on an OBIDMS.
 * @param column_name The name of an OBIDMS column.
286 287
 * @param version_number The version of the column from which the header should be
 *        retrieved (-1: latest version).
288
 *
289 290
 * @returns A pointer on the mmapped header of the column.
 * @retval NULL if an error occurred.
291
 *
292
 * @since October 2015
293 294
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
295
OBIDMS_column_header_p obi_column_get_header_from_name(OBIDMS_p dms, const char* column_name, obiversion_t version_number);
296 297


298
/**
299
 * @brief Munmap a mmapped header as returned by obi_column_get_header_from_name().
300
 *
301
 * @param header A pointer on the mmapped header structure.
302
 *
303 304
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
305
 *
306
 * @since October 2015
307 308
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
309
int obi_close_header(OBIDMS_column_header_p header);
310 311


312
/**
313
 * @brief Recovers the index of an element in an OBIDMS column from the element's name.
314
 *
315 316
 * @param column A pointer on an OBIDMS column.
 * @param element_name The name of the element.
317
 *
318
 * @returns The index of the element in a line of the column.
319
 * @retval OBIIdx_NA if an error occurred.						// TODO not sure if this is "clean".
320 321 322 323
 *
 * @since July 2015
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
324
index_t obi_column_get_element_index_from_name(OBIDMS_column_p column, const char* element_name);
325 326


327 328 329 330 331 332 333 334 335 336 337 338
/**
 * @brief Prepares a column to set a value.
 *
 * @param column A pointer on an OBIDMS column.
 * @param line_nb The number of the line at which the value will be set.
 *
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since April 2016
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
339 340 341
int obi_column_prepare_to_set_value(OBIDMS_column_p column, index_t line_nb);


342 343
/**
 * @brief Prepares a column to recover a value.
344
 *
345 346
 * @param column A pointer on an OBIDMS column.
 * @param line_nb The number of the line at which the value will be recovered.
347
 *
348 349
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
350
 *
351
 * @since April 2016
352 353
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
354
int obi_column_prepare_to_get_value(OBIDMS_column_p column, index_t line_nb);
355 356


Celine Mercier's avatar
Celine Mercier committed
357
#endif /* OBIDMSCOLUMN_H_ */