src/xz/hardware.h

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