initDTthreads

C++ Function Reference

1 Signature

void initDTthreads()

2 Description

Initializes thread configuration based on environment and system state.

3 Details

Thread count determination algorithm:Check R_DATATABLE_NUM_THREADSIf unset, use R_DATATABLE_NUM_PROCS_PERCENTApply system limits (num_procs, thread_limit)Honor OpenMP settingsEnsure at least one thread

4 Call Graph

5 Source Code

Implementation

File: inst/include/Utilities/openme-utils.hpp • Lines 124-150

inline void initDTthreads() {
    // called at package startup from init.c
    // also called by setDTthreads(threads=NULL) (default) to reread environment variables; see setDTthreads below
    // No verbosity here in this setter. Verbosity is in getDTthreads(verbose=TRUE)
    int ans = getIntEnv("R_DATATABLE_NUM_THREADS", INT_MIN);
    if (ans>=1) {
        ans = imin(ans, omp_get_num_procs());  // num_procs is a hard limit; user cannot achieve more. ifndef _OPENMP then myomp.h defines this to be 1
    } else {
        // Only when R_DATATABLE_NUM_THREADS is unset (or <=0) do we use PROCS_PERCENT; #4514
        int perc = getIntEnv("R_DATATABLE_NUM_PROCS_PERCENT", 50); // use "NUM_PROCS" to use the same name as the OpenMP function this uses
        // 50% of logical CPUs by default; half of 8 is 4 on laptop with 4 cores. Leaves plenty of room for other processes: #3395 & #3298
        if (perc<=1 || perc>100) {
            Rcpp::warning(("Ignoring invalid R_DATATABLE_NUM_PROCS_PERCENT==%d. If used it must be an integer between 2 and 100. Default is 50. See ?setDTtheads."), perc);
            // not allowing 1 is to catch attempts to use 1 or 1.0 to represent 100%.
            perc = 50;
        }
        ans = imax(omp_get_num_procs()*perc/100, 1); // imax for when formula would result in 0.
    }
    ans = imin(ans, omp_get_thread_limit());  // honors OMP_THREAD_LIMIT when OpenMP started; e.g. CRAN sets this to 2. Often INT_MAX meaning unlimited/unset
    ans = imin(ans, omp_get_max_threads());   // honors OMP_NUM_THREADS when OpenMP started, plus reflects any omp_set_* calls made since
    // max_threads() -vs- num_procs(): https://software.intel.com/en-us/forums/intel-visual-fortran-compiler-for-windows/topic/302866
    ans = imin(ans, getIntEnv("OMP_THREAD_LIMIT", INT_MAX));  // user might expect `Sys.setenv(OMP_THREAD_LIMIT=2);setDTthreads()` to work. Satisfy this
    ans = imin(ans, getIntEnv("OMP_NUM_THREADS", INT_MAX));   //   expectation by reading them again now. OpenMP just reads them on startup (quite reasonably)
    ans = imax(ans, 1);  // just in case omp_get_* returned <=0 for any reason, or the env variables above are set <=0
    DTthreads = ans;
    DTthrottle = imax(1, getIntEnv("R_DATATABLE_THROTTLE", 1024)); // 2nd thread is used only when n>1024, 3rd thread when n>2048, etc
}

6 Usage Example

#include "BigDataStatMeth.hpp"

// Example usage
auto result = initDTthreads(...);

--- title: "initDTthreads" subtitle: "C++ Function Reference" --- ## Signature ```cpp void initDTthreads() ``` ## Description Initializes thread configuration based on environment and system state. ## Details Thread count determination algorithm:Check R_DATATABLE_NUM_THREADSIf unset, use R_DATATABLE_NUM_PROCS_PERCENTApply system limits (num_procs, thread_limit)Honor OpenMP settingsEnsure at least one thread ## Call Graph ::: {.diagram-section} <object type="image/svg+xml" data="images/_big_data_stat_meth_8hpp_a32e65a19d36ceec1952e48362e4153b8_cgraph.svg" class="class-diagram"> <img src="images/_big_data_stat_meth_8hpp_a32e65a19d36ceec1952e48362e4153b8_cgraph.svg" alt="Function dependencies"/> </object> ::: ## Source Code ::: {.callout-note collapse="true"} ### Implementation **File:** `inst/include/Utilities/openme-utils.hpp` • **Lines 124-150** ```cpp inline void initDTthreads() { // called at package startup from init.c // also called by setDTthreads(threads=NULL) (default) to reread environment variables; see setDTthreads below // No verbosity here in this setter. Verbosity is in getDTthreads(verbose=TRUE) int ans = getIntEnv("R_DATATABLE_NUM_THREADS", INT_MIN); if (ans>=1) { ans = imin(ans, omp_get_num_procs()); // num_procs is a hard limit; user cannot achieve more. ifndef _OPENMP then myomp.h defines this to be 1 } else { // Only when R_DATATABLE_NUM_THREADS is unset (or <=0) do we use PROCS_PERCENT; #4514 int perc = getIntEnv("R_DATATABLE_NUM_PROCS_PERCENT", 50); // use "NUM_PROCS" to use the same name as the OpenMP function this uses // 50% of logical CPUs by default; half of 8 is 4 on laptop with 4 cores. Leaves plenty of room for other processes: #3395 & #3298 if (perc<=1 || perc>100) { Rcpp::warning(("Ignoring invalid R_DATATABLE_NUM_PROCS_PERCENT==%d. If used it must be an integer between 2 and 100. Default is 50. See ?setDTtheads."), perc); // not allowing 1 is to catch attempts to use 1 or 1.0 to represent 100%. perc = 50; } ans = imax(omp_get_num_procs()*perc/100, 1); // imax for when formula would result in 0. } ans = imin(ans, omp_get_thread_limit()); // honors OMP_THREAD_LIMIT when OpenMP started; e.g. CRAN sets this to 2. Often INT_MAX meaning unlimited/unset ans = imin(ans, omp_get_max_threads()); // honors OMP_NUM_THREADS when OpenMP started, plus reflects any omp_set_* calls made since // max_threads() -vs- num_procs(): https://software.intel.com/en-us/forums/intel-visual-fortran-compiler-for-windows/topic/302866 ans = imin(ans, getIntEnv("OMP_THREAD_LIMIT", INT_MAX)); // user might expect `Sys.setenv(OMP_THREAD_LIMIT=2);setDTthreads()` to work. Satisfy this ans = imin(ans, getIntEnv("OMP_NUM_THREADS", INT_MAX)); // expectation by reading them again now. OpenMP just reads them on startup (quite reasonably) ans = imax(ans, 1); // just in case omp_get_* returned <=0 for any reason, or the env variables above are set <=0 DTthreads = ans; DTthrottle = imax(1, getIntEnv("R_DATATABLE_THROTTLE", 1024)); // 2nd thread is used only when n>1024, 3rd thread when n>2048, etc } ``` ::: ## Usage Example ```cpp #include "BigDataStatMeth.hpp" // Example usage auto result = initDTthreads(...); ```