Multi-threading

a5R can parallelise vectorised operations across threads with rayon, a Rust library for data parallelism. By default a5R uses a single thread, so there is no overhead; you opt in to parallelism when you need it. Work is split across elements, so a single polygon part, covering or centre cell gains nothing.

Setting the thread count

a5_threads() reports the thread count and a5_threads(n) sets it, as options() and par() do:

a5_threads() # the default: 1
#> [1] 1

a5_threads(2)
a5_threads()
#> [1] 2

a5_info() also reports the count. To set it for a whole script or batch job, set an R option or environment variable before library(a5R); both are read when the package loads:

# In .Rprofile or at the top of a script
options(a5R.threads = 4)

A5R_NUM_THREADS=4 Rscript script.R

To use more threads for one block of code only, wrap it in with(), as with mirai::daemons(). The previous count is restored afterwards, even if the code fails:

set.seed(1)
cells <- a5_lonlat_to_cell(runif(1e4, -180, 180), runif(1e4, -80, 80), 10)
boundaries <- with(a5_threads(2), {
  a5_cell_to_boundary(cells)
})
a5_threads()
#> [1] 1

Setting a count returns the previous one, so old <- a5_threads(4) and later a5_threads(old) work too.

What gets parallelised

Threading applies to vectorised functions that process each element independently:

Function	Per-element cost	Benefit
`a5_cell_to_boundary()`, `a5_cell_to_boundary_xy()`	Heavy (boundary + WKB/WKT)	High
`a5_polygon_to_cells()`	Heavy (per-part fill, hole subtraction)	High
`a5_line_string_to_cells()`	Heavy (per-feature tracing)	High
`a5_grid_disk()`, `a5_grid_disk_vertex()`, `a5_spherical_cap()`	Heavy (per-cell traversal)	High
`a5_cell_to_subcells()`	Heavy (per-cell search)	High
`a5_lonlat_to_cell()`, `a5_cell_to_lonlat()`	Moderate (projection)	High
`a5_cell_to_supercell()`	Moderate (projection)	High
`a5_cell_distance()`	Moderate (2 projections + distance)	Medium
`a5_union(x, y)`, `a5_intersect()`, `a5_difference()`, `a5_contains()`, `a5_overlaps()`	Varies with covering size	Medium
`a5_covering_to_supercells()`	Search within each covering	Medium
`a5_cell_to_children()`, `a5_uncompact()`	Light (per-element expansion)	Low
`a5_cell_to_parent()`, `a5_get_resolution()`, `a5_migrate()`	Light (bit operations)	Low

For the one-to-many functions (a5_grid_disk(), a5_spherical_cap(), a5_cell_to_children(), a5_uncompact()) the per-element work is parallelised; assembling the result, especially the simplify = FALSE list, is sequential, so the list form gains less than the flat form.

Scalar and bulk operations (a5_compact(), a5_cell_area(), a5_cell_child(), a5_cell_children_range()) are unaffected: they are already fast or do not split by element.

When is it worthwhile?

Each parallel call pays a small fixed cost to hand work to the threads. For small vectors this can outweigh the benefit. As a rule of thumb:

< 1,000 elements: stick with 1 thread
1,000–10,000: 2–4 threads help for heavy operations (boundaries, indexing)
> 10,000: use as many threads as you have cores

Here is a comparison on about 695,000 cells:

cells <- a5_uncompact(a5_polygon_to_cells(wk::rct(-10, 50, 10, 60), resolution = 12))
length(cells)
#> [1] 694889

a5_threads(1)
system.time(a5_cell_to_boundary(cells))
#>    user  system elapsed
#>   0.952   0.005   0.956

a5_threads(8)
system.time(a5_cell_to_boundary(cells))
#>    user  system elapsed
#>   1.206   0.009   0.248

user time (total CPU work across all threads) rises while elapsed (wall-clock) time falls: that is the parallelism at work.

Other parallel code

a5R uses its own rayon thread pool, separate from R’s parallelism. Combining the two multiplies the thread count, so keep the product within your cores:

Separate-process workers (mirai, future::multisession, PSOCK clusters) start at one a5R thread, like any new session. Raise it inside a worker only if the workers leave cores idle.
Forked workers (parallel::mclapply(), future::multicore) inherit the count but not the threads, so a5R runs on one thread in each of them unless the worker calls a5_threads(n) itself.

Each a5_threads(n) call rebuilds the thread pool, which takes well under a millisecond, so scoping a count with with() around each heavy call costs nothing measurable.