src/liblzma/api/lzma/hardware.h

   1 /**
   2  * \file        lzma/hardware.h
   3  * \brief       Hardware information
   4  * \note        Never include this file directly. Use <lzma.h> instead.
   5  *
   6  * See ../lzma.h for information about liblzma as a whole.
   7  *
   8  * Since liblzma can consume a lot of system resources, it also provides
   9  * ways to limit the resource usage. Applications linking against liblzma
  10  * need to do the actual decisions how much resources to let liblzma to use.
  11  * To ease making these decisions, liblzma provides functions to find out
  12  * the relevant capabilities of the underlying hardware. Currently there
  13  * is only a function to find out the amount of RAM, but in the future there
  14  * will be also a function to detect how many concurrent threads the system
  15  * can run.
  16  *
  17  * \note        On some operating systems, these function may temporarily
  18  *              load a shared library or open file descriptor(s) to find out
  19  *              the requested hardware information. Unless the application
  20  *              assumes that specific file descriptors are not touched by
  21  *              other threads, this should have no effect on thread safety.
  22  *              Possible operations involving file descriptors will restart
  23  *              the syscalls if they return EINTR.
  24  */
  25
  26 /*
  27  * Author: Lasse Collin
  28  *
  29  * This file has been put into the public domain.
  30  * You can do whatever you want with this file.
  31  */
  32
  33 #ifndef LZMA_H_INTERNAL
  34 #       error Never include this file directly. Use <lzma.h> instead.
  35 #endif
  36
  37
  38 /**
  39  * \brief       Get the total amount of physical memory (RAM) in bytes
  40  *
  41  * This function may be useful when determining a reasonable memory
  42  * usage limit for decompressing or how much memory it is OK to use
  43  * for compressing.
  44  *
  45  * \return      On success, the total amount of physical memory in bytes
  46  *              is returned. If the amount of RAM cannot be determined,
  47  *              zero is returned. This can happen if an error occurs
  48  *              or if there is no code in liblzma to detect the amount
  49  *              of RAM on the specific operating system.
  50  */
  51 extern LZMA_API(uint64_t) lzma_physmem(void) lzma_nothrow;
  52
  53
  54 /**
  55  * \brief       Get the number of processor cores or threads
  56  *
  57  * This function may be useful when determining how many threads to use.
  58  * If the hardware supports more than one thread per CPU core, the number
  59  * of hardware threads is returned if that information is available.
  60  *
  61  * \return      On success, the number of available CPU threads or cores is
  62  *              returned. If this information isn't available or an error
  63  *              occurs, zero is returned.
  64  */
  65 extern LZMA_API(uint32_t) lzma_cputhreads(void) lzma_nothrow;