include/lzma/hardware.h

0001 /* SPDX-License-Identifier: 0BSD */
0002
0003 /**
0004  * \file        lzma/hardware.h
0005  * \brief       Hardware information
0006  * \note        Never include this file directly. Use <lzma.h> instead.
0007  *
0008  * Since liblzma can consume a lot of system resources, it also provides
0009  * ways to limit the resource usage. Applications linking against liblzma
0010  * need to do the actual decisions how much resources to let liblzma to use.
0011  * To ease making these decisions, liblzma provides functions to find out
0012  * the relevant capabilities of the underlying hardware. Currently there
0013  * is only a function to find out the amount of RAM, but in the future there
0014  * will be also a function to detect how many concurrent threads the system
0015  * can run.
0016  *
0017  * \note        On some operating systems, these function may temporarily
0018  *              load a shared library or open file descriptor(s) to find out
0019  *              the requested hardware information. Unless the application
0020  *              assumes that specific file descriptors are not touched by
0021  *              other threads, this should have no effect on thread safety.
0022  *              Possible operations involving file descriptors will restart
0023  *              the syscalls if they return EINTR.
0024  */
0025
0026 /*
0027  * Author: Lasse Collin
0028  */
0029
0030 #ifndef LZMA_H_INTERNAL
0031 #   error Never include this file directly. Use <lzma.h> instead.
0032 #endif
0033
0034
0035 /**
0036  * \brief       Get the total amount of physical memory (RAM) in bytes
0037  *
0038  * This function may be useful when determining a reasonable memory
0039  * usage limit for decompressing or how much memory it is OK to use
0040  * for compressing.
0041  *
0042  * \return      On success, the total amount of physical memory in bytes
0043  *              is returned. If the amount of RAM cannot be determined,
0044  *              zero is returned. This can happen if an error occurs
0045  *              or if there is no code in liblzma to detect the amount
0046  *              of RAM on the specific operating system.
0047  */
0048 extern LZMA_API(uint64_t) lzma_physmem(void) lzma_nothrow;
0049
0050
0051 /**
0052  * \brief       Get the number of processor cores or threads
0053  *
0054  * This function may be useful when determining how many threads to use.
0055  * If the hardware supports more than one thread per CPU core, the number
0056  * of hardware threads is returned if that information is available.
0057  *
0058  * \return      On success, the number of available CPU threads or cores is
0059  *              returned. If this information isn't available or an error
0060  *              occurs, zero is returned.
0061  */
0062 extern LZMA_API(uint32_t) lzma_cputhreads(void) lzma_nothrow;