1  ///////////////////////////////////////////////////////////////////////////////
       2  //
       3  /// \file       hardware.h
       4  /// \brief      Detection of available hardware resources
       5  //
       6  //  Author:     Lasse Collin
       7  //
       8  //  This file has been put into the public domain.
       9  //  You can do whatever you want with this file.
      10  //
      11  ///////////////////////////////////////////////////////////////////////////////
      12  
      13  /// Initialize some hardware-specific variables, which are needed by other
      14  /// hardware_* functions.
      15  extern void hardware_init(void);
      16  
      17  
      18  /// Set the maximum number of worker threads.
      19  /// A special value of UINT32_MAX sets one thread in multi-threaded mode.
      20  extern void hardware_threads_set(uint32_t threadlimit);
      21  
      22  /// Get the maximum number of worker threads.
      23  extern uint32_t hardware_threads_get(void);
      24  
      25  /// Returns true if multithreaded mode should be used for .xz compression.
      26  /// This can be true even if the number of threads is one.
      27  extern bool hardware_threads_is_mt(void);
      28  
      29  
      30  /// Set the memory usage limit. There are separate limits for compression,
      31  /// decompression (also includes --list), and multithreaded decompression.
      32  /// Any combination of these can be set with a single call to this function.
      33  /// Zero indicates resetting the limit back to the defaults.
      34  /// The limit can also be set as a percentage of installed RAM; the
      35  /// percentage must be in the range [1, 100].
      36  extern void hardware_memlimit_set(uint64_t new_memlimit,
      37  		bool set_compress, bool set_decompress, bool set_mtdec,
      38  		bool is_percentage);
      39  
      40  /// Get the current memory usage limit for compression or decompression.
      41  /// This is a hard limit that will not be exceeded. This is obeyed in
      42  /// both single-threaded and multithreaded modes.
      43  extern uint64_t hardware_memlimit_get(enum operation_mode mode);
      44  
      45  /// This returns a system-specific default value if all of the following
      46  /// conditions are true:
      47  ///
      48  ///   - An automatic number of threads was requested (--threads=0).
      49  ///
      50  ///   - --memlimit-compress wasn't used or it was reset to the default
      51  ///     value by setting it to 0.
      52  ///
      53  /// Otherwise this is identical to hardware_memlimit_get(MODE_COMPRESS).
      54  ///
      55  /// The idea is to keep automatic thread count reasonable so that too
      56  /// high memory usage is avoided and, with 32-bit xz, running out of
      57  /// address space is avoided.
      58  extern uint64_t hardware_memlimit_mtenc_get(void);
      59  
      60  /// Returns true if the value returned by hardware_memlimit_mtenc_get() is
      61  /// a system-specific default value. coder.c uses this to ignore the default
      62  /// memlimit in case it's too small even for a single thread in multithreaded
      63  /// mode. This way the default limit will never make xz fail or affect the
      64  /// compressed output; it will only make xz reduce the number of threads.
      65  extern bool hardware_memlimit_mtenc_is_default(void);
      66  
      67  /// Get the current memory usage limit for multithreaded decompression.
      68  /// This is only used to reduce the number of threads. This limit can be
      69  /// exceeded if the number of threads are reduce to one. Then the value
      70  /// from hardware_memlimit_get() will be honored like in single-threaded mode.
      71  extern uint64_t hardware_memlimit_mtdec_get(void);
      72  
      73  /// Display the amount of RAM and memory usage limits and exit.
      74  tuklib_attr_noreturn
      75  extern void hardware_memlimit_show(void);