00-CPP-101.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# C/C++ 101\n",
    "\n",
    "**Table of contents:**\n",
    " - [C](#C)\n",
    " - [C++](#sec-cpp)\n",
    " - [Summary](#Summary)\n",
    "\n",
    "If you have never written a program in C/C++, this notebook provides the basic concepts to follow along."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## C\n",
    "\n",
    "<div class=\"alert alert-block alert-success\">\n",
    "    <ul>\n",
    "        <li>C is a simple and small language</li>\n",
    "        <li>C is a DIY language (write your own data structures!)</li>\n",
    "        <li>C is a generic assembly language</li>\n",
    "        <li>If there's anything \"missing\" from C it's λ-functions</li>\n",
    "    </ul>\n",
    "</div>\n",
    "\n",
    "One of the simplest C programs is shown below. It includes a module `stdio.h` that provides standard I/O functions including `printf` that lets programs print a string to a terminal.\n",
    "\n",
    "If arguments are passed to the program, they are available in the `argv` array, which is of length `argc`. The first argument is the name of the program itself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%writefile src/hello.c\n",
    "#include <stdio.h>\n",
    "\n",
    "int main(int argc, char *argv[])\n",
    "{\n",
    "    printf(\"Hello, World!\\n\");\n",
    "\n",
    "    if (argc > 1)\n",
    "    {\n",
    "        printf(\"Arguments:\\n\");\n",
    "        for (int i = 0; i < argc; ++i)\n",
    "            printf(\"argv[%d] = %s\\n\", i, argv[i]);\n",
    "    }\n",
    "    else\n",
    "        printf(\"No arguments\\n\");\n",
    "\n",
    "    return 0;\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A C program (source code) must be compiled to machine code before it can be executed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "gcc -o build/hello src/hello.c\n",
    "build/hello --foo bar baz"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The HDF5 library appears to a C program as another module that provides functions to perform HDF5 tasks. Using the HDF5 library, in the example below, we retrieve and print the HDF5 library version, and create an \"empty\" HDF5 file.\n",
    "\n",
    "Unlike several other languages, a variable definition in C must indicate the variable's type, which precedes the variable name. E.g., the variables `[maj,min,rel]num` are of type `unsigned integer`.\n",
    "\n",
    "External modules typically introduce API-specific types. Perhaps the most important API-type in the HDF5 library is `hid_t`. It is used to identify and track entities managed by the HDF5 library.\n",
    "\n",
    "Since the C runtime doesn't have a garbage collector, the programmer is in charge of managing (and not wasting) resources. Similarly, the HDF5 library delegates control over HDF5 entities (identified by an `hid_t`!) to the programmer. Perhaps the single most important rule when using the HDF5 C-API in a program is Powell's rule: \n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "<b>The Powell rule:</b> <i>\"If you break it, you are going to own it.\"</i> In other words, if you call an HDF5 library API (e.g., <tt>H5*[create,open]</tt>) that returns a value of type <tt>hid_t</tt>, then you are going to own the underlying resources allocated by the HDF5 library. You must explicitely release these resources by calling appropriate functions (e.g., <tt>H5*close</tt>) that tell the library that the application does no longer require those resources. Failing to release unused resources (a resource leak) often leads to poor performance, abnormal program behavior, or application or system crashes, etc.\n",
    "</div>\n",
    "\n",
    " Case in point: See the matching `H5Fcreate` and `H5Fclose` calls in the example below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%writefile src/hello_hdf5.c\n",
    "#include \"hdf5.h\"\n",
    "#include <stdio.h>\n",
    "\n",
    "int main(int argc, char *argv[])\n",
    "{\n",
    "    unsigned majnum, minnum, relnum;\n",
    "    H5get_libversion(&majnum, &minnum, &relnum);\n",
    "    printf(\"Hello, HDF5 library %d.%d.%d!\", majnum, minnum, relnum);\n",
    "\n",
    "    // If the user provided a filename, create a file under that name\n",
    "    // otherwise, create a file called \"build/hello.h5\"\n",
    "    hid_t file = H5Fcreate((argc > 1 ? argv[1] : \"build/hello.h5\"), H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);\n",
    "    H5Fclose(file);\n",
    "\n",
    "    return 0;\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since the HDF5 library is not part of the standard set of modules that ships with the C compiler, we must tell the compiler (and linker) something about the location of the HDF5 module via command line options. (See the compiler manual for details: `man gcc`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "gcc -o build/hello_hdf5 src/hello_hdf5.c -Wall -pedantic -I/usr/include/hdf5/serial -L/usr/lib/x86_64-linux-gnu -lhdf5_serial\n",
    "build/hello_hdf5 build/foo.h5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"sec-cpp\"></a>\n",
    "## C++\n",
    "\n",
    "<div class=\"alert alert-block alert-success\">\n",
    "    <ul>\n",
    "        <li>C++ is not a small language (but it's not a strict superset of C!)</li>\n",
    "        <li>C++ comes with batteries included</li>\n",
    "        <li>C++ has namespaces (and modules as of C++20)</li>\n",
    "        <li>C++ has λ-functions (since C++11)</li>\n",
    "        <li>When used competently, in modern C++, you can get the conciseness of Python <i>and</i> the performance of C</li>\n",
    "    </ul>\n",
    "</div>\n",
    "\n",
    "There are several (C++) idiomatic language bindings available for the HDF5 library, including __[HighFive](https://bluebrain.github.io/HighFive/poster/)__, __[H5CPP](https://github.com/steven-varga/h5cpp)__, and __[h5cpp](https://github.com/ess-dmsc/h5cpp)__. Programmers who want their code to look like modern C++ (rather than C) should check them out! The Powell rule still applies, but can be conveniently folded into idioms such as __[RAII](https://en.cppreference.com/w/cpp/language/raii)__.\n",
    "\n",
    "In this tutorial, we take advantage of a few batteries included with C++ while sticking with the HDF5 library C-API. That way, our examples are less verbose than plain C, but it's easier to follow how the HDF5 libary API is used. On the flipside, we won't be able to showcase the elegance of C++, but that isn't a goal of this tutorial.\n",
    "\n",
    "A C++ compiler would have no issue with the C example shown earlier, but a C compiler would not be satisfied with the C++ code shown next."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%writefile src/hello_hdf5.cpp\n",
    "#include \"hdf5.h\"\n",
    "#include <iostream>\n",
    "\n",
    "int main(int argc, char *argv[])\n",
    "{\n",
    "    unsigned majnum, minnum, relnum;\n",
    "    H5get_libversion(&majnum, &minnum, &relnum);\n",
    "    std::cout << \"Hello, HDF5 library \"\n",
    "        << majnum << \".\" << minnum << \".\" << relnum << \"!\" << std::endl;\n",
    "\n",
    "    // If the user provided a filename, create a file under that name\n",
    "    // otherwise, create a file called \"build/hello.h5\"\n",
    "    hid_t file = H5Fcreate((argc > 1 ? argv[1] : \"build/hello.1.h5\"), H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);\n",
    "    H5Fclose(file);\n",
    "\n",
    "    return 0;\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "g++ -o build/hello_hdf5.1 src/hello_hdf5.cpp -Wall -pedantic -I/usr/include/hdf5/serial -L/usr/lib/x86_64-linux-gnu -lhdf5_serial\n",
    "build/hello_hdf5.1 build/bar.h5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "C/C++ programs need to be compiled into machine code before they can be executed. Variables are typed and the most important HDF5 library C-API type is `hid_t` for identifying and tracking HDF5 entities. Values of type `hid_t` are signs which symbolize resources allocated by the HDF5 library on behalf of the caller. The caller is responsible for releasing resources no longer required (Powell rule). For application developers, several fine C++ language bindings of the HDF5 library are available. If you are already using the HDF5 library through __[`h5py`](https://www.h5py.org/)__, __[HDFql](https://www.hdfql.com/)__, or __[`rhdf5`](https://bioconductor.org/packages/release/bioc/html/rhdf5.html)__, good for you! &#128077;"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "hdf5-tutorial",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}