include/root/Compression.h

0001 // @(#)root/zip:$Id$
0002 // Author: David Dagenhart   May 2011
0003
0004 /*************************************************************************
0005  * Copyright (C) 1995-2011, Rene Brun and Fons Rademakers.               *
0006  * All rights reserved.                                                  *
0007  *                                                                       *
0008  * For the licensing terms see $ROOTSYS/LICENSE.                         *
0009  * For the list of contributors see $ROOTSYS/README/CREDITS.             *
0010  *************************************************************************/
0011
0012 #ifndef ROOT_Compression
0013 #define ROOT_Compression
0014
0015 #include "RtypesCore.h"
0016 #include "ROOT/RConfig.hxx"
0017
0018 #include <string>
0019
0020 namespace ROOT {
0021
0022 /// The global settings depend on a global variable named R__ZipMode which can be
0023 /// modified by a global function named R__SetZipMode. Both are defined in Bits.h.
0024 ///
0025 ///  - The default is to use the global setting and the default of the global
0026 ///    setting is to use the ZLIB compression algorithm.
0027 ///  - The LZMA algorithm (from the XZ package) is also available. The LZMA
0028 ///    compression usually results in greater compression factors, but takes
0029 ///    more CPU time and memory when compressing. LZMA memory usage is particularly
0030 ///    high for compression levels 8 and 9.
0031 ///  - Finally, the LZ4 package results in worse compression ratios
0032 ///    than ZLIB but achieves much faster decompression rates.
0033 ///
0034 /// The current algorithms support level 1 to 9. The higher the level the greater
0035 /// the compression and more CPU time and memory resources used during compression.
0036 /// Level 0 means no compression.
0037 ///
0038 /// Recommendation for the compression algorithm's levels:
0039 ///  - ZLIB is recommended to be used with compression level 1 [101]
0040 ///  - LZMA is recommended to be used with compression level 7-8 (higher is better,
0041 ///   since in the case of LZMA we don't care about compression/decompression speed)
0042 ///   [207 - 208]
0043 ///  - LZ4 is recommended to be used with compression level 4 [404]
0044 ///  - ZSTD is recommended to be used with compression level 5 [505]
0045
0046 struct RCompressionSetting {
0047    struct EDefaults { /// Note: this is only temporarily a struct and will become a enum class hence the name convention
0048                       /// used.
0049       enum EValues {
0050          /// Use the global compression setting for this process; may be affected by rootrc.
0051          kUseGlobal = 0,
0052          /// Use the compile-time default setting
0053          kUseCompiledDefault = 101,
0054          /// Use the default analysis setting; fast reading but poor compression ratio
0055          kUseAnalysis = 404,
0056          /// Use the new recommended general-purpose setting; it is a best trade-off between compression
0057          /// ratio/decompression speed
0058          kUseGeneralPurpose = 505,
0059          /// Use the setting that results in the smallest files; very slow read and write
0060          kUseSmallest = 207,
0061       };
0062    };
0063    struct ELevel { /// Note: this is only temporarily a struct and will become a enum class hence the name convention
0064                    /// used.
0065       enum EValues {
0066          /// Some objects use this value to denote that the compression algorithm
0067          /// should be inherited from the parent object
0068          kInherit = -1,
0069          /// Compression level reserved for "uncompressed state"
0070          kUncompressed = 0,
0071          /// Compression level reserved when we are not sure what to use (1 is for the fastest compression)
0072          kUseMin = 1,
0073          /// Compression level reserved for ZLIB compression algorithm (fastest compression)
0074          kDefaultZLIB = 1,
0075          /// Compression level reserved for LZ4 compression algorithm (trade-off between file ratio/decompression speed)
0076          kDefaultLZ4 = 4,
0077          /// Compression level reserved for ZSTD compression algorithm (trade-off between file ratio/decompression
0078          /// speed)
0079          kDefaultZSTD = 5,
0080          /// Compression level reserved for old ROOT compression algorithm
0081          kDefaultOld = 6,
0082          /// Compression level reserved for LZMA compression algorithm (slowest compression with smallest files)
0083          kDefaultLZMA = 7
0084       };
0085    };
0086    struct EAlgorithm { /// Note: this is only temporarily a struct and will become a enum class hence the name
0087                        /// convention used.
0088       enum EValues {
0089          /// Some objects use this value to denote that the compression algorithm
0090          /// should be inherited from the parent object (e.g., TBranch should get the algorithm from the TTree)
0091          kInherit = -1,
0092          /// Use the global compression algorithm
0093          kUseGlobal = 0,
0094          /// Use ZLIB compression
0095          kZLIB,
0096          /// Use LZMA compression
0097          kLZMA,
0098          /// Use the old compression algorithm
0099          kOldCompressionAlgo,
0100          /// Use LZ4 compression
0101          kLZ4,
0102          /// Use ZSTD compression
0103          kZSTD,
0104          /// Undefined compression algorithm (must be kept the last of the list in case a new algorithm is added).
0105          kUndefined
0106       };
0107    };
0108
0109    static std::string AlgorithmToString(EAlgorithm::EValues algorithm);
0110    static EAlgorithm::EValues AlgorithmFromCompressionSettings(int compSettings)
0111    {
0112       return std::min(EAlgorithm::EValues::kUndefined, static_cast<EAlgorithm::EValues>(compSettings / 100));
0113    }
0114 };
0115
0116 // clang-format off
0117
0118 int CompressionSettings(RCompressionSetting::EAlgorithm::EValues algorithm, int compressionLevel);
0119
0120 // clang-format on
0121
0122 } // namespace ROOT
0123
0124 #endif