1 // SPDX-License-Identifier: 0BSD
3 ///////////////////////////////////////////////////////////////////////////////
6 /// \brief Detection of available hardware resources
8 // Author: Lasse Collin
10 ///////////////////////////////////////////////////////////////////////////////
12 /// Initialize some hardware-specific variables, which are needed by other
13 /// hardware_* functions.
14 extern void hardware_init(void);
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
);
21 /// Get the maximum number of worker threads.
22 extern uint32_t hardware_threads_get(void);
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);
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
,
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
);
44 /// This returns a system-specific default value if all of the following
45 /// conditions are true:
47 /// - An automatic number of threads was requested (--threads=0).
49 /// - --memlimit-compress wasn't used or it was reset to the default
50 /// value by setting it to 0.
52 /// Otherwise this is identical to hardware_memlimit_get(MODE_COMPRESS).
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);
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);
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);
72 /// Display the amount of RAM and memory usage limits and exit.
74 extern void hardware_memlimit_show(void);