availableCores: Get Number of Available Cores on The Current Machine

Description Usage Arguments Details Value Avoid ending up with zero cores Advanced usage See Also Examples

View source: R/availableCores.R

Description

The current/main R session counts as one, meaning the minimum number of cores available is always at least one.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
availableCores(
  constraints = NULL,
  methods = getOption2("parallelly.availableCores.methods", c("system", "nproc",
    "mc.cores", "BiocParallel", "_R_CHECK_LIMIT_CORES_", "PBS", "SGE", "Slurm", "LSF",
    "fallback", "custom")),
  na.rm = TRUE,
  logical = getOption2("parallelly.availableCores.logical", TRUE),
  default = c(current = 1L),
  which = c("min", "max", "all"),
  omit = getOption2("parallelly.availableCores.omit", 0L)
)

Arguments

constraints

An optional character specifying under what constraints ("purposes") we are requesting the values. For instance, on systems where multicore processing is not supported (i.e. Windows), using constrains = "multicore" will force a single core to be reported.

methods

A character vector specifying how to infer the number of available cores.

na.rm

If TRUE, only non-missing settings are considered/returned.

logical

Passed to detectCores(logical = logical), which, if supported, returns the number of logical CPUs (TRUE) or physical CPUs/cores (FALSE). This argument is only if argument methods includes "system".

default

The default number of cores to return if no non-missing settings are available.

which

A character specifying which settings to return. If "min" (default), the minimum value is returned. If "max", the maximum value is returned (be careful!) If "all", all values are returned.

omit

(integer; non-negative) Number of cores to not include.

Details

The following settings ("methods") for inferring the number of cores are supported:

For any other value of a methods element, the R option with the same name is queried. If that is not set, the system environment variable is queried. If neither is set, a missing value is returned.

Value

Return a positive (>= 1) integer. If which = "all", then more than one value may be returned. Together with na.rm = FALSE missing values may also be returned.

Avoid ending up with zero cores

Note that some machines might have a limited number of cores, or the R process runs in a container or a cgroup that only provides a small number of cores. In such cases:

ncores <- availableCores() - 1

may return zero, which is often not intended and is likely to give an error downstream. Instead, use:

ncores <- availableCores(omit = 1)

to put aside one of the cores from being used. Regardless how many cores you put aside, this function is guaranteed to return at least one core.

Advanced usage

It is possible to override the maximum number of cores on the machine as reported by availableCores(methods = "system"). This can be done by first specifying options(parallelly.availableCores.methods = "mc.cores") and then the number of cores to use, e.g. options(mc.cores = 8).

See Also

To get the set of available workers regardless of machine, see availableWorkers().

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
message(paste("Number of cores available:", availableCores()))

## Not run: 
options(mc.cores = 2L)
message(paste("Number of cores available:", availableCores()))

## End(Not run)

## Not run: 
## IMPORTANT: availableCores() may return 1L
options(mc.cores = 1L)
ncores <- availableCores() - 1      ## ncores = 0
ncores <- availableCores(omit = 1)  ## ncores = 1
message(paste("Number of cores to use:", ncores))

## End(Not run)

## Not run: 
## Use 75% of the cores on the system but never more than four
options(parallelly.availableCores.custom = function() {
  ncores <- max(parallel::detectCores(), 1L, na.rm = TRUE)
  ncores <- min(as.integer(0.75 * ncores), 4L)
  max(1L, ncores)
})
message(paste("Number of cores available:", availableCores()))

## What is available minus one core but at least one
options(parallelly.availableCores.custom = function() {
  max(1L, parallelly::availableCores() - 1L)
})
message(paste("Number of cores available:", availableCores()))

## End(Not run)

parallelly documentation built on Nov. 21, 2021, 9:07 a.m.