mirror/netcdf-c
2
0
Fork 0
mirror of https://github.com/Unidata/netcdf-c.git synced 2024-11-21 03:13:42 +08:00
Code Issues Packages Projects Releases Wiki Activity
086eed0e39
netcdf-c/libncpoco
History
Dennis Heimbigner 3ffe7be446 Enhance/Fix filter support 
re: Discussion https://github.com/Unidata/netcdf-c/discussions/2214

The primary change is to support so-called "standard filters".
A standard filter is one that is defined by the following
netcdf-c API:
````
int nc_def_var_XXX(int ncid, int varid, size_t nparams, unsigned* params);
int nc_inq_var_XXXX(int ncid, int varid, int* usefilterp, unsigned* params);
````
So for example, zstandard would be a standard filter by defining
the functions *nc_def_var_zstandard* and *nc_inq_var_zstandard*.

In order to define these functions, we need a new dispatch function:
````
int nc_inq_filter_avail(int ncid, unsigned filterid);
````
This function, combined with the existing filter API can be used
to implement arbitrary standard filters using a simple code pattern.
Note that I would have preferred that this function return a list
of all available filters, but HDF5 does not support that functionality.

So this PR implements the dispatch function and implements
the following standard functions:
    + bzip2
    + zstandard
    + blosc
Specific test cases are also provided for HDF5 and NCZarr.
Over time, other specific standard filters will be defined.

## Primary Changes
* Add nc_inq_filter_avail() to netcdf-c API.
* Add standard filter implementations to test use of *nc_inq_filter_avail*.
* Bump the dispatch table version number and add to all the relevant
   dispatch tables (libsrc, libsrcp, etc).
* Create a program to invoke nc_inq_filter_avail so that it is accessible
  to shell scripts.
* Cleanup szip support to properly support szip
  when HDF5 is disabled. This involves detecting
  libsz separately from testing if HDF5 supports szip.
* Integrate shuffle and fletcher32 into the existing
  filter API. This means that, for example, nc_def_var_fletcher32
  is now a wrapper around nc_def_var_filter.
* Extend the Codec defaulting to allow multiple default shared libraries.

## Misc. Changes
* Modify configure.ac/CMakeLists.txt to look for the relevant
  libraries implementing standard filters.
* Modify libnetcdf.settings to list available standard filters
  (including deflate and szip).
* Add CMake test modules to locate libbz2 and libzstd.
* Cleanup the HDF5 memory manager function use in the plugins.
* remove unused file include//ncfilter.h
* remove tests for the HDF5 memory operations e.g. H5allocate_memory.
* Add flag to ncdump to force use of _Filter instead of _Deflate
  or _Shuffle or _Fletcher32. Used for testing.
2022-03-14 12:39:37 -06:00
..
CMakeLists.txt Add filter support to NCZarr 2021-09-02 17:04:26 -06:00
COPYRIGHT Add filter support to NCZarr 2021-09-02 17:04:26 -06:00
cp_test.c Add filter support to NCZarr 2021-09-02 17:04:26 -06:00
cp_unix.c Enhance/Fix filter support 2022-03-14 12:39:37 -06:00
cp_win32.c Add filter support to NCZarr 2021-09-02 17:04:26 -06:00
cptestlib.c Add filter support to NCZarr 2021-09-02 17:04:26 -06:00
Makefile.am Support MSYS2/Mingw platform 2021-12-23 22:18:56 -07:00
ncpoco.c Add filter support to NCZarr 2021-09-02 17:04:26 -06:00
ncpoco.h Add filter support to NCZarr 2021-09-02 17:04:26 -06:00
README.md Docs migration 2021-11-11 10:47:49 -07:00
SourceLicence Add filter support to NCZarr 2021-09-02 17:04:26 -06:00

README.md

The cpoco Multi-Platform Dynamic-Loading Library

Description

The primary goal of the cpoco project is to provide a C language version of the poco multi-platform dynamic loading library. The poco libraries are written in C++.

The secondary goal of cpoco is to support dynamic loading of HDF5 filters by the netCDF C library.

Mutual Exclusion Support

Internally, cpoco (like poco) supports serialized access to the dynamic loading functions using mutual exclusion locks. For nix systems, this usually requires pthreads support.

In any case, it is possible to disable the use of mutual exclusion if you know you are operating in a single threaded environment: see the installation section below.

Implementataion Restrictions

Currently support is provided for the following systems.

  • libdl supporting operating systems: e.g. linux, os-x, cygwin.
  • Windows-32 api

Installation

Automake

Automake-based configuration is provided using ./configure is provided for systems supporting autoconf/automake.

Use this command to see the available options.

./configure --help

The most important options are these.

  • --disable-mutex -- disable using mutual exclusion (default is enabled)
  • --disable-pthread -- disable using pthreads (default is enabled if operating system provides it)
  • --enable-shared -- build a shared library (default is enabled)
  • --enable-static -- build a static library (default is enabled)
  • --prefix= -- defaults to /usr/local

Note that is --enable-shared is disabled, then the test program will not run because the test shared library (libcpt) cannot be built.

Use these commands to build, test, and install using autoconf.

# Invoke configure
./configure <options>
make all
# If testing is desired
make check
# Optional
make install

The are those shown by ./configure --help.

CMake

Cmake-based configuration is provided provided for systems supporting it. If building for windows, then this is the only option provided.

Use these commands to build using cmake.

# Create a build directory
rm -fr build
mkdir build
cd build
# Invoke cmake
cmake <flags> ..
cmake --build .
# If testing is desired
CTEST_OUTPUT_ON_FAILURE=1 cmake --build . --target test
# Optional
cmake --build . --target install

The are these:

  • -DENABLE_MUTEX -- use mutual exclusion (default is true)
  • -DENABLE_PTHREAD -- use pthreads (if available) (default is true)
  • -DCMAKE_INSTALL_PREFIX= -- installation directory (defaults to /usr/local or c:/Program Files)

Support

Author: Dennis Heimbigner
Organization: University Corporation for Atmospheric Research
Initial Release: 2015-9-28 Last Modified: 2018-03-27

Copyright: Copyright 2018, UCAR/Unidata; see COPYRIGHT file for copying and redistribution conditions. This code is Derived from the poco library (See Poco Information below).

Change Log

  1. (2016-09-28) Initial release.
  2. (2018-03-27) Updated to make fix some automake problems.

Poco Information

Poco License

Boost Software License - Version 1.0 - August 17th, 2003

Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the "Software") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following:

The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.