12940b44dSPeter Avalos /**
22940b44dSPeter Avalos  * \file        lzma/hardware.h
32940b44dSPeter Avalos  * \brief       Hardware information
42940b44dSPeter Avalos  *
52940b44dSPeter Avalos  * Since liblzma can consume a lot of system resources, it also provides
62940b44dSPeter Avalos  * ways to limit the resource usage. Applications linking against liblzma
72940b44dSPeter Avalos  * need to do the actual decisions how much resources to let liblzma to use.
82940b44dSPeter Avalos  * To ease making these decisions, liblzma provides functions to find out
9*e151908bSDaniel Fojt  * the relevant capabilities of the underlying hardware. Currently there
102940b44dSPeter Avalos  * is only a function to find out the amount of RAM, but in the future there
112940b44dSPeter Avalos  * will be also a function to detect how many concurrent threads the system
122940b44dSPeter Avalos  * can run.
132940b44dSPeter Avalos  *
142940b44dSPeter Avalos  * \note        On some operating systems, these function may temporarily
152940b44dSPeter Avalos  *              load a shared library or open file descriptor(s) to find out
162940b44dSPeter Avalos  *              the requested hardware information. Unless the application
172940b44dSPeter Avalos  *              assumes that specific file descriptors are not touched by
182940b44dSPeter Avalos  *              other threads, this should have no effect on thread safety.
192940b44dSPeter Avalos  *              Possible operations involving file descriptors will restart
202940b44dSPeter Avalos  *              the syscalls if they return EINTR.
212940b44dSPeter Avalos  */
222940b44dSPeter Avalos 
232940b44dSPeter Avalos /*
242940b44dSPeter Avalos  * Author: Lasse Collin
252940b44dSPeter Avalos  *
262940b44dSPeter Avalos  * This file has been put into the public domain.
272940b44dSPeter Avalos  * You can do whatever you want with this file.
282940b44dSPeter Avalos  *
292940b44dSPeter Avalos  * See ../lzma.h for information about liblzma as a whole.
302940b44dSPeter Avalos  */
312940b44dSPeter Avalos 
322940b44dSPeter Avalos #ifndef LZMA_H_INTERNAL
332940b44dSPeter Avalos #	error Never include this file directly. Use <lzma.h> instead.
342940b44dSPeter Avalos #endif
352940b44dSPeter Avalos 
362940b44dSPeter Avalos 
372940b44dSPeter Avalos /**
382940b44dSPeter Avalos  * \brief       Get the total amount of physical memory (RAM) in bytes
392940b44dSPeter Avalos  *
402940b44dSPeter Avalos  * This function may be useful when determining a reasonable memory
412940b44dSPeter Avalos  * usage limit for decompressing or how much memory it is OK to use
422940b44dSPeter Avalos  * for compressing.
432940b44dSPeter Avalos  *
442940b44dSPeter Avalos  * \return      On success, the total amount of physical memory in bytes
452940b44dSPeter Avalos  *              is returned. If the amount of RAM cannot be determined,
462940b44dSPeter Avalos  *              zero is returned. This can happen if an error occurs
472940b44dSPeter Avalos  *              or if there is no code in liblzma to detect the amount
482940b44dSPeter Avalos  *              of RAM on the specific operating system.
492940b44dSPeter Avalos  */
502940b44dSPeter Avalos extern LZMA_API(uint64_t) lzma_physmem(void) lzma_nothrow;
5115ab8c86SJohn Marino 
5215ab8c86SJohn Marino 
5315ab8c86SJohn Marino /**
5415ab8c86SJohn Marino  * \brief       Get the number of processor cores or threads
5515ab8c86SJohn Marino  *
5615ab8c86SJohn Marino  * This function may be useful when determining how many threads to use.
5715ab8c86SJohn Marino  * If the hardware supports more than one thread per CPU core, the number
5815ab8c86SJohn Marino  * of hardware threads is returned if that information is available.
5915ab8c86SJohn Marino  *
6015ab8c86SJohn Marino  * \brief       On success, the number of available CPU threads or cores is
6115ab8c86SJohn Marino  *              returned. If this information isn't available or an error
6215ab8c86SJohn Marino  *              occurs, zero is returned.
6315ab8c86SJohn Marino  */
6415ab8c86SJohn Marino extern LZMA_API(uint32_t) lzma_cputhreads(void) lzma_nothrow;
65