The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

memtoc

Tictoc-style memory tracking for R. Simple start/stop syntax for monitoring RAM usage during code execution with continuous background polling to estimate peak memory. Inspired by the tictoc package for timing.

Installation

# install.packages("pak")
pak::pak("jcoa05/memtoc")
# Or using devtools
devtools::install_github("jcoa05/memtoc")

Quick start

library(memtoc)

# Track memory for any operation
tic_mem("data processing")
data <- read.csv("large_file.csv")
processed <- transform(data)
toc_mem()
#> ✔ data processing: 142.3 MB peak | 89.1 MB current | 2.34 sec | 3 samples

Why memtoc?

R’s built-in memory tools (gc(), object.size()) only show point-in-time snapshots. Prioritizing ease of use, memtoc estimates peak memory by continuously sampling in the background.

tic_mem("matrix operation")
x <- matrix(rnorm(1e8), ncol = 1000)  # ~800 MB temporary allocation
y <- colMeans(x)                        
rm(x)  # A peak is recorded only if a sample captured the allocation
toc_mem()
#> ✔ matrix operation: 812.4 MB peak | 45.2 MB current | 3.21 sec | 7 samples
# without background polling, you'd only see the final 45 MB.

Features

Feature	Description
🎯 Background polling	Background sampling estimates peak usage
📊 Nested tracking	Track pipelines and individual steps simultaneously
⚡ Parallel monitoring	Auto-detect and monitor `future` workers
💾 Crash recovery	Recover data if R crashes mid-computation
⚠️ System warnings	Alerts when system RAM is running low
📝 Logging	Collect results for later analysis

Background polling

tic_mem("job", interval = 0.5)  # Sample every 0.5 seconds
# ... your code ...
result <- toc_mem()
result$trajectory  # Full memory timeline

Nested tracking

tic_mem("full pipeline")
  tic_mem("step 1"); do_step1(); toc_mem()
  tic_mem("step 2"); do_step2(); toc_mem()
  tic_mem("step 3"); do_step3(); toc_mem()
toc_mem()

Parallel worker monitoring

library(future)
plan(multisession, workers = 4)

tic_mem("parallel job", workers = "auto")
result <- future_lapply(1:100, heavy_function)
toc_mem()
#> ✔ parallel job: 1.2 GB peak | 245 MB current | 5.4 sec | 4 workers

Crash recovery

Checkpoints live in R’s session-specific temporary directory. After an R restart, use mem_recover(path = ...) with the actual path to a surviving checkpoint from the previous session. Recovery is impossible if that temporary directory has been removed. Normal completion removes checkpoints.

# List checkpoints in this R session
mem_recover()
#> ℹ Found 1 recovery file: PID 12345 (152 samples)
data <- mem_recover(pid = 12345)

Reference

Function	Description
`tic_mem()`	Start tracking
`toc_mem()`	Stop tracking and report results
`mem_log()`	Get logged results as data frame
`mem_clearlog()`	Clear the log
`mem_clear()`	Clear orphaned tracking entries
`mem_recover()`	Recover data from crashed sessions
`mem_capabilities()`	Check available features
`mem_diagnose()`	Detailed troubleshooting
`mem_parallel_info()`	Check parallel backend status

Documentation

See vignette("memtoc") for a detailed tutorial, or ?tic_mem for function help.

Requirements

R ≥ 4.1.0
Dependencies: ps, cli, and callr installed automatically
Optional: future and parallelly for parallel worker monitoring

tictoc: Timing (memtoc is for memory)
bench: Benchmarking with memory tracking
profmem: Memory profiling

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.