libpression version 0.19.0

Major Changes

+ BREAKING CHANGE `pressio_release` is no longer a noop, and has new
  signature.  The signature change was made to better support wrappers
  like swig.  It has been changed from a noop to freeing the memory
  associated with a particular instance of the library.  This allows
  users to create several handles for the library for error handling
  purposes.
+ BREAKING CHANGE new API `pressio_compressor_release` now should be called on
  pressio_compressor* pointers when they are no longer needed.
  Internally it uses shared pointers, and depending on the
  implementation of the compressor it either returns a static copy of
  the shared pointer (i.e. SZ) for compressors where global memory is
  used to configure compressors, or a new shared pointer for each (i.e.
  ZFP).  This allows compressors such as ZFP that may be used in a
  multi-threaded context to actually be used in that way.
+ BREAKING CHANGE `pressio_instance` now actually returns a new instance
  each time it is called rather than a possibly shared instance
+ The plugin registration system has been completely re-written to no
  longer require disparate edits to various files to introduce new
  plugins, instead, users create an instance of `pressio_register` to
  register to their type.  This also allows non-library compressors to
  be introduced without recompiling libpressio.

Minor Changes

+ MemoryChecks are now supported for test cases.  Various memory leaks
  in test cases are now removed. Added a valgrind suppression file for
  the libgomp malloc that is never freed when valgrind can see it.
+ `pressio_get_compressor` and `pressio_new_metrics` now correctly
  return a nullpointer when the lookup fails
+ SWIG now passes input arrays as INPLACE_ARRAYs instead.  This has a
  minor performance improvement.
+ New C++ only integration test case was added.
+ Several private APIs were removed as no longer required

Bug Fixes

+ a few incorrectly documented functions were correctly documented

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
-project(libpressio VERSION "0.18.2" LANGUAGES CXX C)
+project(libpressio VERSION "0.19.0" LANGUAGES CXX C)
 
 #correct was to set a default build type
 # https://blog.kitware.com/cmake-and-the-default-build-type/
@@ -13,6 +13,9 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
 endif()
 
 enable_testing()
+include(CTestCustom.cmake)
+include(CTest)
+
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 option(BUILD_SHARED_LIBS "build libpressio as a shared library" ON)
 
@@ -70,8 +73,12 @@ add_library(libpressio
   #public headers
   include/libpressio.h
   include/libpressio_ext/cpp/compressor.h
+  include/libpressio_ext/cpp/data.h
+  include/libpressio_ext/cpp/libpressio.h
   include/libpressio_ext/cpp/metrics.h
-  include/libpressio_ext/cpp/plugins.h
+  include/libpressio_ext/cpp/options.h
+  include/libpressio_ext/cpp/pressio.h
+  include/libpressio_ext/cpp/printers.h
   include/libpressio_ext/io/posix.h
   include/pressio.h
   include/pressio_compressor.h
@@ -81,9 +88,6 @@ add_library(libpressio
   include/pressio_option.h
   include/pressio_options.h
   include/pressio_options_iter.h
-
-  #private headers
-  src/pressio_compressor_impl.h
   )
 
 target_include_directories(libpressio

COPYRIGHT.txt

@@ -1,6 +1,6 @@
 Copyright © 2019 , UChicago Argonne, LLC
 All Rights Reserved
-[libpressio, Version 0.18.2]
+[libpressio, Version 0.19.0]
 Robert Underwood
 Argonne National Laboratory
 

CTestCustom.cmake

@@ -0,0 +1,2 @@
+set(MEMORYCHECK_SANITIZER_OPTIONS "--leak-checks=full")
+set(MEMORYCHECK_SUPPRESSIONS_FILE "${CMAKE_SOURCE_DIR}/test/valgrind.supp")

README.md

@@ -150,7 +150,8 @@ main(int argc, char* argv[])
 
   // free options and the library
   pressio_options_free(sz_options);
-  pressio_release(&library);
+  pressio_compressor_release(compressor);
+  pressio_release(library);
   return 0;
 }
 ~~~

include/libpressio_ext/cpp/compressor.h

@@ -1,6 +1,7 @@
 #ifndef LIBPRESSIO_COMPRESSOR_IMPL_H
 #define LIBPRESSIO_COMPRESSOR_IMPL_H
 #include <string>
+#include <memory>
 
 /*!\file 
  * \brief an extension header for adding compressor plugins to libpressio
@@ -155,5 +156,31 @@ class libpressio_compressor_plugin {
   struct pressio_metrics* metrics_plugin;
 };
 
+/**
+ * wrapper for the compressor to use in C
+ */
+struct pressio_compressor {
+  /**
+   * \param[in] impl a newly constructed compressor plugin
+   */
+  pressio_compressor(std::shared_ptr<libpressio_compressor_plugin>&& impl): plugin(std::forward<std::shared_ptr<libpressio_compressor_plugin>>(impl)) {}
+  /**
+   * defaults constructs a compressor with a nullptr
+   */
+  pressio_compressor()=default;
+  /**
+   * move constructs a compressor from another pointer
+   */
+  pressio_compressor(pressio_compressor&& compressor)=default;
+  /**
+   * move assigns a compressor from another pointer
+   */
+  pressio_compressor& operator=(pressio_compressor&& compressor)=default;
+
+  /**
+   * pointer to the implementation
+   */
+  std::shared_ptr<libpressio_compressor_plugin> plugin;
+};
 
 #endif

include/libpressio_ext/cpp/libpressio.h

@@ -0,0 +1,10 @@
+/**
+ * \file
+ * \brief convenience header for the c++ interface
+ */
+#include "compressor.h"
+#include "data.h"
+#include "metrics.h"
+#include "options.h"
+#include "pressio.h"
+#include "printers.h"

include/libpressio_ext/cpp/metrics.h

@@ -2,6 +2,7 @@
 #define PRESIO_METRIC_PLUGIN
 
 #include <memory>
+#include <vector>
 
 struct pressio_options;
 struct pressio_data;
@@ -113,4 +114,10 @@ struct pressio_metrics {
   std::unique_ptr<libpressio_metrics_plugin> plugin;
 };
 
+/**
+ * returns a composite metrics plugin from a vector of metrics_plugins
+ */
+std::unique_ptr<libpressio_metrics_plugin> make_m_composite(std::vector<std::unique_ptr<libpressio_metrics_plugin>>&& plugins); 
+
+
 #endif

include/libpressio_ext/cpp/pressio.h

@@ -0,0 +1,193 @@
+/**
+ * \file
+ * \brief C++ interface to the compressor loader
+ */
+#ifndef LIBPRESSIO_PRESSIO_IMPL_H
+#define LIBPRESSIO_PRESSIO_IMPL_H
+#include <map>
+#include <memory>
+#include <functional>
+#include "compressor.h"
+#include "metrics.h"
+
+/**
+ * a type that registers constructor functions
+ */
+template <class T>
+struct pressio_registry {
+  /**
+   * construct a element of the registered type
+   *
+   * \param[in] name the item to construct
+   * \returns the result of the factory function
+   */
+  T build(std::string const& name) const {
+    if (auto factory = factories.find(name); factory != factories.end()) {
+      return factory->second();
+    } else {
+      return nullptr;
+    }
+  }
+
+  /**
+   * register a factory function with the registry at the provided name
+   *
+   * \param[in] name the name to register
+   * \param[in] factory the constructor function which takes 0 arguments
+   */
+  template <class Name, class Factory>
+  void regsiter_factory(Name&& name, Factory&& factory) {
+    factories.emplace(std::forward<Name>(name), std::forward<Factory>(factory));
+  }
+
+  /**
+   * \returns an begin iterator over the registered types
+   */
+  auto begin() const { return std::begin(factories); }
+  /**
+   * \returns an end iterator over the registered types
+   */
+  auto end() const { return std::end(factories); }
+
+  private:
+  std::map<std::string, std::function<T()>> factories;
+};
+
+/**
+ * a class that registers a type on construction, using a type over a function
+ * to force it to be called at static construction time
+ */
+class pressio_register{
+  public:
+  /**
+   * Registers a new factory with a name in a registry.  Designed to be used as a static inline variable
+   *
+   * \param[in] registry the registry to use
+   * \param[in] name the name to register
+   * \param[in] factory the factory to register
+   */
+  template <class RegistryType, class NameType, class Factory>
+  pressio_register(pressio_registry<RegistryType>& registry, NameType&& name, Factory&& factory) {
+    registry.regsiter_factory(name, factory);
+  }
+};
+
+/**
+ * the registry for compressor plugins
+ */
+pressio_registry<std::shared_ptr<libpressio_compressor_plugin>>& compressor_plugins();
+/**
+ * the registry for metrics plugins
+ */
+pressio_registry<std::unique_ptr<libpressio_metrics_plugin>>& metrics_plugins();
+
+/**
+ * the libraries basic state
+ */
+struct pressio {
+  public:
+
+  /**
+   * sets an error code and message
+   * \param[in] code non-zero represents an error
+   * \param[in] msg a human readable description of the error
+   */
+  void set_error(int code, std::string const& msg) {
+    error.code = code;
+    error.msg = msg;
+  }
+
+  /**
+   * \returns the last error code for this library object
+   */
+  int err_code() const { return error.code; }
+
+  /**
+   * \returns the last error message for this library object
+   */
+  std::string const& err_msg() const { return error.msg; }
+
+  /**
+   * Returns an instance of a compressor
+   * \param[in] compressor_id name of the compressor to request
+   * \returns an instance of compressor registered at name, or nullptr on error
+   */
+  std::shared_ptr<libpressio_compressor_plugin> get_compressor(std::string const& compressor_id) {
+    auto compressor = compressor_plugins().build(compressor_id);
+    if (compressor) return compressor;
+    else {
+      set_error(1, std::string("invalid compressor id ") + compressor_id);
+      return nullptr;
+    }
+  }
+
+  /**
+   * Returns a composite metric for all the metric_ids requested
+   * \param[in] first iterator to the first metric_id requested
+   * \param[in] last iterator to the last metric_id requested
+   * \returns an instance of a metrics module regsitered at a name wrapping it in a composite if nessisary
+   */
+  template <class ForwardIt>
+  std::unique_ptr<libpressio_metrics_plugin> get_metrics(ForwardIt first, ForwardIt last) {
+    std::vector<std::unique_ptr<libpressio_metrics_plugin>> plugins;
+
+    for (auto metric = first; metric != last; ++metric) {
+      plugins.emplace_back(metrics_plugins().build(*metric));
+      if(not plugins.back()) {
+        set_error(2, std::string("failed to construct metrics plugin: ") + *metric);
+        return nullptr;
+      }
+    }
+
+    auto metrics = make_m_composite(std::move(plugins));
+
+    if(metrics) return metrics;
+    else {
+      set_error(3, "failed to construct composite metric");
+      return nullptr;
+    };
+  }
+
+  /**
+   * \returns the version string for this version of libpressio
+   *
+   * \see pressio_version
+   */
+  static const char* version();
+
+  /**
+   * \returns the features string for this version of libpressio
+   *
+   * \see pressio_features
+   */
+  static const char* features();
+
+  /**
+   * \returns the supported compressors list for this version of libpressio
+   *
+   * \see pressio_supported_compressors
+   */
+  static const char* supported_compressors();
+
+  /**
+   * \returns the major version number of libpressio
+   */
+  static unsigned int major_version();
+
+  /**
+   * \returns the minor version number of libpressio
+   */
+  static unsigned int minor_version();
+
+  /**
+   * \returns the patch version number of libpressio
+   */
+  static unsigned int patch_version();
+
+  private:
+  struct {
+    int code;
+    std::string msg;
+  } error;
+};
+#endif

include/pressio.h

@@ -14,17 +14,17 @@ struct pressio_compressor;
 struct pressio_metrics;
 
 /**
- * gets a reference to a possibly shared instance of libpressio; initializes the library if necessary
+ * gets a reference to a new instance of libpressio; initializes the library if necessary
  * \returns a pointer to a library instance
  */
 struct pressio* pressio_instance();
 
 
 /**
- * \param[in,out] library the pointer to the library
+ * \param[in] library the pointer to the library
  * \returns informs the library that this instance is no longer required; the pointer passed becomes invalid
  */
-void pressio_release(struct pressio** library);
+void pressio_release(struct pressio* library);
 
 /**
  * \param[in] library the pointer to the library

include/pressio_compressor.h

@@ -13,6 +13,11 @@ struct pressio_compressor;
 struct pressio_data;
 struct pressio_options;
 
+/*!
+ * \param[in] compressor deallocates a reference to a compressor.
+ */
+void pressio_compressor_release(struct pressio_compressor* compressor);
+
 //option getting/setting functions
 /*!
  * \returns a pressio options struct that represents the compile time configuration of the compressor