'Tictoc'-Style Memory Usage Tracking

Provides simple start/stop memory tracking functions tic_mem() and toc_mem() that can be nested, inspired by the 'tictoc' package. Track RAM usage during code execution with support for logging, custom messages, nested tracking blocks, and parallel worker monitoring. Features continuous background polling to estimate peak memory usage across main process and workers. Integrates with the 'future' package ecosystem for automatic worker detection. Designed for monitoring memory consumption in parallel workflows.

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

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

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

Related packages

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