trexio/src/templates_front/templator_front.org

Templator for frontend

• Constant file prefixes (not used by generator)
• Coding conventions
  • Memory allocation
• Front end
  • Error handling
  • Back ends
  • Read/write behavior
  • TREXIO file type
  • Polymorphism of the file handle
  • File opening
  • File closing
• Templates for front end
  • Template for frontend read/write a number
  • Template for frontend read/write a dataset
• Back ends
• File suffixes

Constant file prefixes (not used by generator)   noxport

#+NAME:header

/* This file was generated from the templator_front.org org-mode file.
 To generate it, open trexio.org in Emacs and execute
 M-x org-babel-tangle
*/

<<header>>

module trexio

use, intrinsic :: iso_c_binding

<<header>>
#ifndef _TREXIO_H
#define _TREXIO_H

#include <stdint.h>

<<header>>
#include <pthread.h>
#include <assert.h>
#include <stdlib.h>
#include <string.h>
#include <pthread.h>

#include "trexio.h"
#include "trexio_s.h"
#include "trexio_text.h"
#include "trexio_hdf5.h"
/*
#include "trexio_json.h"
,*/

<<header>>
#ifndef _TREXIO_S_H
#define _TREXIO_S_H

#include "trexio.h"
#include <pthread.h>
#include <assert.h>

Coding conventions

• integer types will be defined using types given in stdint.h
• pointers are always initialized to NULL
• when memory is freed, the pointer is set to NULL
• assert.h should be used extensively
• variable names are in lower case
• #define constants are in upper case
• structs are suffixed by _s
• types are suffixed by _t

Memory allocation

Memory allocation of structures can be facilitated by using the following macro, which ensures that the size of the allocated object is the same as the size of the data type pointed by the pointer.

#define MALLOC(T) (T*) malloc (sizeof(T));
#define CALLOC(N,T) (T*) calloc ((N),sizeof(T));

When a pointer is freed, it should be set to NULL. This can be facilitated by the use of the following macro:

#define FREE(X) { free(X) ; (X)=NULL; }

Front end

All calls to TREXIO are thread-safe.

Error handling

typedef int32_t trexio_exit_code;

#define TREXIO_FAILURE       ( (trexio_exit_code) -1 )
#define TREXIO_SUCCESS       ( (trexio_exit_code)  0 )
#define TREXIO_INVALID_ARG_1 ( (trexio_exit_code)  1 )
#define TREXIO_INVALID_ARG_2 ( (trexio_exit_code)  2 )
#define TREXIO_INVALID_ARG_3 ( (trexio_exit_code)  3 )
#define TREXIO_INVALID_ARG_4 ( (trexio_exit_code)  4 )
#define TREXIO_INVALID_ARG_5 ( (trexio_exit_code)  5 )
#define TREXIO_END           ( (trexio_exit_code) 10 )
#define TREXIO_READONLY      ( (trexio_exit_code) 11 )
#define TREXIO_ERRNO         ( (trexio_exit_code) 12 )
#define TREXIO_INVALID_ID    ( (trexio_exit_code) 20 )
#define TREXIO_ALLOCATION_FAILED  (  (trexio_exit_code)  21  )
#define TREXIO_INVALID_NUM   ( (trexio_exit_code) 22 )

Back ends

typedef int32_t back_end_t;

#define TREXIO_HDF5             ( (back_end_t) 0 )
#define TREXIO_TEXT             ( (back_end_t) 1 ) 
#define TREXIO_JSON             ( (back_end_t) 2 ) 
#define TREXIO_INVALID_BACK_END ( (back_end_t) 3 )

Read/write behavior

Every time a reading function is called, the data is read from the disk. If data needs to be cached, this is left to the user of the library.

Writing to TREXIO files is done with transactions (all-or-nothing effect) in a per-group fashion. File writes are attempted by calling explicitly the flush function, or when the TREXIO file is closed. If writing is impossible because the data is not valid, no data is written.

The order in which the data is written is not necessarily consistent with the order in which the function calls were made.

The TREXIO files are supposed to be opened by only one program at a time: if the same TREXIO file is modified simultaneously by multiple concurrent programs, the behavior is not specified.

TREXIO file type

trexio_s is the the main type for TREXIO files, visible to the users of the library. This type is kept opaque, and all modifications to the files will be necessarily done through the use of functions, taking such a type as argument.

File creation and opening functions will return TREXIO file handles, namely pointers to trexio_s types. All functions accessing to the TREXIO files will have as a first argument the TREXIO file handle.

typedef struct trexio_s trexio_t;

struct trexio_s {
char*             file_name;
pthread_mutex_t   thread_lock;
back_end_t        back_end;
char              mode;
char              padding[7];   /* Ensures the proper alignment of back-ends */
};

Polymorphism of the file handle

Polymorphism of the trexio_t type is handled by ensuring that the corresponding types for all back ends can be safely casted to trexio_t. This is done by making the back end structs start with struct trexio_s:

struct trexio_back_end_s {
trexio_t     parent ;
/* add below specific back end data */
}

File opening

trexio_t* trexio_open(const char* file_name, const char mode, const back_end_t back_end);

trexio_t* trexio_open(const char* file_name, const char mode, const back_end_t back_end) {

if (file_name == NULL) return NULL;
if (file_name[0] == '\0') return NULL;

if (back_end <  0) return NULL;
if (back_end >= TREXIO_INVALID_BACK_END) return NULL;

if (mode != 'r' && mode != 'w' && mode != 'a') return NULL;

trexio_t* result = NULL;

/* Allocate data structures */
switch (back_end) {

case TREXIO_TEXT:
 result = (trexio_t*) malloc (sizeof(trexio_text_t));
 break;

case TREXIO_HDF5:
 result = (trexio_t*) malloc (sizeof(trexio_hdf5_t));
 break;
/*
case TREXIO_JSON:
 result = (trexio_t*) malloc (sizeof(trexio_json_t));
 break;
,*/      
}

assert (result != NULL);    /* TODO: Error handling */


/* Data for the parent type */

result->file_name   = (char*) calloc(strlen(file_name)+1,sizeof(char));
strcpy(result->file_name, file_name);
result->back_end    = back_end;
result->mode        = mode;
int irc = pthread_mutex_init ( &(result->thread_lock), NULL);
assert (irc == 0);

trexio_exit_code rc;

/* Back end initialization */

rc = TREXIO_FAILURE;

switch (back_end) {

case TREXIO_TEXT:
 rc = trexio_text_init(result);
 break;

case TREXIO_HDF5:
 rc = trexio_hdf5_init(result);
 break;
/*
case TREXIO_JSON:
 rc = trexio_json_init(result);
 break;
,*/      
}

if (rc != TREXIO_SUCCESS) {
 free(result->file_name);
 free(result);
 return NULL;
}

/* File locking */

rc = TREXIO_FAILURE;

switch (back_end) {

case TREXIO_TEXT:
 rc = trexio_text_lock(result);
 break;

case TREXIO_HDF5:
 rc = TREXIO_SUCCESS;
 break;
/*
case TREXIO_JSON:
 rc = trexio_json_lock(result);
 break;
*/      
}

if (rc != TREXIO_SUCCESS) {
 free(result->file_name);
 free(result);
 return NULL;
}

return result;
}

interface
type (c_ptr) function trexio_open (filename, mode, backend) bind(C)
  use, intrinsic :: iso_c_binding
  character(kind=c_char), dimension(*)   :: filename
  character(kind=c_char), intent(in)     :: mode
  integer (c_int32_t), intent(in), value :: backend
end function trexio_open
end interface

File closing

trexio_exit_code trexio_close(trexio_t* file);

trexio_exit_code trexio_close(trexio_t* file) {

if (file == NULL) return TREXIO_FAILURE;

trexio_exit_code rc;

/* Terminate the back end */
switch (file->back_end) {

case TREXIO_TEXT:
 rc = trexio_text_finalize(file);
 break;

case TREXIO_HDF5:
 rc = trexio_hdf5_finalize(file);
 break;
/*
case TREXIO_JSON:
 rc = trexio_json_finalize(file);
 break;
,*/      
default:
 assert (1 == 0);  /* Impossible case */
}

if (rc != TREXIO_SUCCESS) {
 free(file->file_name);
 free(file);
 return TREXIO_FAILURE;
}

/* File unlocking */

rc = TREXIO_FAILURE;

switch (file->back_end) {

case TREXIO_TEXT:
 rc = trexio_text_unlock(file);
 break;

case TREXIO_HDF5:
 rc = TREXIO_SUCCESS;
 break;
/*
case TREXIO_JSON:
 rc = trexio_json_unlock(file);
 break;
*/      
}

/* Terminate front end */

free(file->file_name);
file->file_name = NULL;

int irc = pthread_mutex_destroy( &(file->thread_lock) );

free(file);

if (irc != 0) return TREXIO_ERRNO;
if (rc != TREXIO_SUCCESS) return TREXIO_FAILURE;
 
return TREXIO_SUCCESS;
}

interface
type (c_int32_t) function trexio_close (trex_file) bind(C)
  use, intrinsic :: iso_c_binding
  type (c_ptr), intent(in), value :: trex_file
end function trexio_close
end interface

Templates for front end

Template for frontend read/write a number

trexio_exit_code trexio_read_$group_num$(trexio_t* file, int64_t* num);
trexio_exit_code trexio_write_$group_num$(trexio_t* file, const int64_t num);

trexio_exit_code trexio_read_$group_num$(trexio_t* file, int64_t* num) {
if (file == NULL) return TREXIO_INVALID_ARG_1;

uint64_t u_num = 0;
trexio_exit_code rc = TREXIO_FAILURE;

switch (file->back_end) {

case TREXIO_TEXT:
rc = trexio_text_read_$group_num$(file, &u_num);
break;

case TREXIO_HDF5:
rc = trexio_hdf5_read_$group_num$(file, &u_num);
break;
/*
case TREXIO_JSON:
rc =trexio_json_read_$group_num$(file, &u_num);
break;
,*/      
}

if (rc != TREXIO_SUCCESS) return rc;
                         
/**/ *num = (int64_t) u_num;
return TREXIO_SUCCESS;
}

trexio_exit_code trexio_write_$group_num$(trexio_t* file, const int64_t num) {
if (file == NULL) return TREXIO_INVALID_ARG_1;
if (num  <  0   ) return TREXIO_INVALID_ARG_2;

trexio_exit_code rc = TREXIO_FAILURE;

switch (file->back_end) {

case TREXIO_TEXT:
rc = trexio_text_write_$group_num$(file, (uint64_t) num);
break;

case TREXIO_HDF5:
rc = trexio_hdf5_write_$group_num$(file, (uint64_t) num);
break;
/*
case TREXIO_JSON:
rc = trexio_json_write_$group_num$(file, (uint64_t) num);
break;
,*/      
}
if (rc != TREXIO_SUCCESS) return rc;
                         
return TREXIO_SUCCESS;
}

interface
integer (c_int32_t) function trexio_write_$group_num$ (trex_file, num) bind(C)
use, intrinsic :: iso_c_binding
type (c_ptr), intent(in), value :: trex_file
integer (c_int64_t), intent(in), value :: num
end function trexio_write_$group_num$
end interface

interface
integer (c_int32_t) function trexio_read_$group_num$ (trex_file, num) bind(C)
use, intrinsic :: iso_c_binding
type (c_ptr), intent(in), value :: trex_file
integer (c_int64_t), intent(inout), value :: num
end function trexio_read_$group_num$
end interface

Template for frontend read/write a dataset

trexio_exit_code trexio_read_$group$_$group_dset$(trexio_t* file, $group_dset_dtype$* $group_dset$);
trexio_exit_code trexio_write_$group$_$group_dset$(trexio_t* file, const $group_dset_dtype$* $group_dset$);

trexio_exit_code trexio_read_$group$_$group_dset$(trexio_t* file, $group_dset_dtype$* $group_dset$) {
if (file  == NULL) return TREXIO_INVALID_ARG_1;
if ($group_dset$ == NULL) return TREXIO_INVALID_ARG_2;

trexio_exit_code rc;
uint64_t $group_dset_dim$ = -1;

switch (file->back_end) {

case TREXIO_TEXT:
rc = trexio_text_read_$group_dset_dim$(file, &$group_dset_dim$);
break;

case TREXIO_HDF5:
rc = trexio_hdf5_read_$group_dset_dim$(file, &$group_dset_dim$);
break;
/*
case TREXIO_JSON:
rc = trexio_json_read_$group_dset_dim$(file, &$group_dset_dim$);
break;
*/
}

if (rc != TREXIO_SUCCESS) return rc;

if ($group_dset_dim$ <= 0L) return TREXIO_INVALID_NUM;

uint32_t rank = $group_dset_rank$;
uint64_t dims[$group_dset_rank$] = {$group_dset_dim_list$}; 

switch (file->back_end) {

case TREXIO_TEXT:
return trexio_text_read_$group$_$group_dset$(file, $group_dset$, rank, dims);
break;

case TREXIO_HDF5:
return trexio_hdf5_read_$group$_$group_dset$(file, $group_dset$, rank, dims);
break;
/*
case TREXIO_JSON:
return trexio_json_read_$group$_$group_dset$(file, $group_dset$);
break;
,*/
default:
return TREXIO_FAILURE;  /* Impossible case */
}
}

trexio_exit_code trexio_write_$group$_$group_dset$(trexio_t* file, const $group_dset_dtype$* $group_dset$) {
if (file  == NULL) return TREXIO_INVALID_ARG_1;
if ($group_dset$ == NULL) return TREXIO_INVALID_ARG_2;

trexio_exit_code rc;
uint64_t $group_dset_dim$ = -1;
switch (file->back_end) {

case TREXIO_TEXT:
rc = trexio_text_read_$group_dset_dim$(file, &$group_dset_dim$);
break;

case TREXIO_HDF5:
rc = trexio_hdf5_read_$group_dset_dim$(file, &$group_dset_dim$);
break;
/*
case TREXIO_JSON:
rc = trexio_json_read_$group_dset_dim$(file, &$group_dset_dim$);
break;
*/
}

if (rc != TREXIO_SUCCESS) return rc;
if ($group_dset_dim$ <= 0L) return TREXIO_INVALID_NUM;

uint32_t rank = $group_dset_rank$;
uint64_t dims[$group_dset_rank$] = {$group_dset_dim_list$}; 

switch (file->back_end) {

case TREXIO_TEXT:
return trexio_text_write_$group$_$group_dset$(file, $group_dset$, rank, dims);
break;

case TREXIO_HDF5:
return trexio_hdf5_write_$group$_$group_dset$(file, $group_dset$, rank, dims);
break;
/*
case TREXIO_JSON:
return trexio_json_write_$group$_$group_dset$(file, $group_dset$);
break;
,*/
default:
return TREXIO_FAILURE;  /* Impossible case */
}
}

Back ends

TREXIO has multiple possible back ends:

• HDF5: The most efficient back-end, by default
• Text files: not to be used for production, but useful for debugging
• JSON: for portability

File suffixes   noxport

#endif

#endif

end module trexio