Learn R Programming

data.table (version 1.11.8)

setDTthreads: Set or get number of threads that data.table should use

Description

Set and get number of threads to be used in data.table functions that are parallelized with OpenMP. Default value 0 means to utilize all CPU available with an appropriate number of threads calculated by OpenMP. getDTthreads() returns the number of threads that will be used. This affects data.table only and does not change R itself or other packages using OpenMP. The most common usage expected is setDTthreads(1) to limit data.table to one thread for pre-existing explicitly parallel user code; e.g. via packages parallel and foreach. Otherwise, nested parallelism may bite. As data.table becomes more parallel automatically internally, we expect explicit user parallelism to be needed less often.

Attempting to setDTthreads() to more than the number of logical CPUs is intended to be ineffective; i.e., getDTthreads() will still return the number of logical CPUs in that case. Further, there is a hard coded limit of 1024 threads (with warning when imposed) to prevent accidentally picking up the value of INT_MAX (2 billion; i.e. unlimited) from omp_get_thread_limit(). We have followed the advice of section 1.2.1.1 in the R-exts manual: "... or, better, for the regions in your code as part of their specification... num_threads(nthreads).. That way you only control your own code and not that of other OpenMP users." All the parallel region in data.table contain this directive. This is mandated by a grep in the package's quality control release procedure script.

Usage

setDTthreads(threads)
getDTthreads(verbose = getOption("datatable.verbose", FALSE))

Arguments

threads

An integer >= 0. Default 0 means use all CPU available and leave the operating system to multi task.

verbose

Display the value returned by some OpenMP function calls.

Value

A length 1 integer. The old value is returned by setDTthreads so you can store that value and pass it to setDTthreads again after the section of your code where you, probably, limited to one thread.