h5cpp.1

.TH H5CPP 1 2020-02-06 GNU h5cpp programming manual
.SH NAME
h5cpp \- compiles HDF5 compound datatype descriptors from C++ AST
.SH SYNOPSIS
.B h5cpp translation_unit.cpp --$(CXXFLAGS) -Doutput.h

.SH "DESCRIPTION"
H5CPP-compiler automates the tedious and error prone process of handwriting HDF5
compound type data descriptors providing similar level of data
serialization/persistence experience of popular interpreted languages
but compile time.
This non-intrusive source code transformation tool is a companion to h5cpp
template library it builds the AST of a specified translation unit,
identifies arbitrary deep POD struct variables referenced/used by the
template library operators:
.EX
    h5::create | h5::read | h5::write | h5::append
    h5::acreate | h5::aread | h5::awrite
.EE
and generates the necessary HDF5 compound datatype descriptors. In the second
phase, invoking system compiler (gcc,clang,msvc, ...)  on the now complete
translation unit produces the binary object file.

The h5cpp compiler assisted reflection and its companion header library
was developed for low latency event stream recording arising in high
frequency trading applications, Real Time Bidding and general machine
learning.

Primary competing idea to compiler assisted reflection is the recently
developed purely template based introspection and reflection for C++
which is not yet available. While there are many related work based on
runtime approach, or templates most of them requiring some modification
to original code making it intrusive, or less performance oriented.


.SH OPTIONS
.TP
.B -D
output filename to be generated
.TP
.B -v
verbose invocation of the underlying clang tooling framework to aid you with 
identifying search paths, etc...

.SH EXAMPLES
.B h5cpp translation_unit.cpp -- $(CXXFLAGS)  -Dgenerated.h
will build AST from translation_unit.cpp and create HDF5 compound descriptors in generated.h given 
the following POD struct type Record:
.PP
.EX
.B struct.h:
.in +4n
typedef unsigned long long int MyUInt; // typedefs or aliasing is fine
namespace sn::example {                // so are nested namespaces are
    struct Record {                    // currently must be a POD struct
        MyUInt                    idx; // typedef type
        float             field_02[7]; // const array mapped 
    };
}
.in
.EE
.PP
The output file `generated.h` are to be included in the translation unit file as if it existed,
as the following code snippet demonstrates:

.PP
.EX
.BI translation_unit.cpp:
.in +4n
#include <h5cpp/core>
   #include <generated.h> // this must match -Dspecified_name.h and the content will be overwritten
#include <h5cpp/io>

int main (int argc, char *argv[]) {
    [...]
    h5::fd_t fd = h5::create("example.h5",H5F_ACC_TRUNC);

    std::vector<sn::example::Record> data =
	        h5::utils::get_test_data<sn::example::Record>( N );
    h5::write(fd, "some_name", data );
}
.in
.EE
.PP
Once the LLVM based tool builds the AST, and identifies the entire tree of objects marked with the previously
discussed CRUD like operators, it will produce the correct minimal HDF5 type descriptor and the necessary 
registration macro.
.PP
.EX
.B generated.h:
.in +4n
#ifndef H5CPP_GUARD_ggket
#define H5CPP_GUARD_ggket

namespace h5{
    //template specialization of sn::example::Record to create HDF5 COMPOUND type
    template<> hid_t inline register_struct<sn::example::Record>(){
        hsize_t at_00_[] ={7};            hid_t at_00 = H5Tarray_create(H5T_NATIVE_FLOAT,1,at_00_);

        hid_t ct_00 = H5Tcreate(H5T_COMPOUND, sizeof (sn::example::Record));
        H5Tinsert(ct_00, "idx",	HOFFSET(sn::example::Record,idx),H5T_NATIVE_ULLONG);
        H5Tinsert(ct_00, "field_02",	HOFFSET(sn::example::Record,field_02),at_00);

        //closing all hid_t allocations to prevent resource leakage
        H5Tclose(at_00); 

        //if not used with h5cpp framework, but as a standalone code generator then
        //the returned 'hid_t ct_00' must be closed: H5Tclose(ct_00);
        return ct_00;
    };
}
H5CPP_REGISTER_STRUCT(sn::example::Record);
.in
.EE
.PP
Typically the compiler is invoked from a
.B Makefile
in the following manner:
.PP
.EX
.B Makefile:
.in +4n
[...]
generated.h: struct.h
	h5cpp  struct.cpp -- $(CXXFLAGS) $(INCLUDES) -Dgenerated.h

struct.o : struct.cpp generated.h 
	$(CXX) $(INCLUDES) -o struct.o  $(CXXFLAGS) -c struct.cpp

struct: struct.o
	$(CXX) $^ $(LIBS) -o $@	
.in
.EE
.PP

Details set of examples may be found in
.B /usr/share/h5cpp/examples
directory, for general use cases, interaction with linear algebra libraries as well as 
scaling the library to MPI based clusters.


.SH CAVEATS
silently fails when there exists white space between -D output_filename.h

.SH AUTHOR
2018-2020 steven varga <steven@vargaconsulting.ca>

.UR http://h5cpp.org