Module refcount_protect 

Reference-counted GC protection using a map + VECSXP backing.

This module provides an alternative to gc_protect that uses reference counting instead of R’s LIFO protect stack. This allows releasing protections in any order and avoids the --max-ppsize limit.

Architecture

The module is built around two key abstractions:

1. MapStorage - Trait abstracting over map implementations (BTreeMap, HashMap)
2. Arena - Generic arena using RefCell for interior mutability

For thread-local storage without RefCell overhead, use the define_thread_local_arena! macro.

How It Works

┌─────────────────────────────────────────────────────────────────────┐
│  Arena<M: MapStorage>                                               │
│  ┌─────────────────────────┐   ┌───────────────────────────────────┐│
│  │  Map<usize, Entry>      │   │  VECSXP (R_PreserveObject'd)      ││
│  │  ────────────────────── │   │  ─────────────────────────────    ││
│  │  sexp_a → {count:2, i:0}│◄──┤  [0]: sexp_a                      ││
│  │  sexp_b → {count:1, i:1}│◄──┤  [1]: sexp_b                      ││
│  │  sexp_c → {count:1, i:2}│◄──┤  [2]: sexp_c                      ││
│  └─────────────────────────┘   │  [3]: <free>                      ││
│                                └───────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────┘

Available Types

Type	Map	Storage	Use Case
RefCountedArena	BTreeMap	RefCell	General purpose, ordered
HashMapArena	HashMap	RefCell	Large collections
ThreadLocalArena	BTreeMap	thread_local	Lowest overhead
ThreadLocalHashArena	HashMap	thread_local	Large + low overhead

Fast Hash (feature-gated)

With the refcount-fast-hash feature enabled, additional types become available:

Type	Map	Storage	Use Case
FastHashMapArena	ahash HashMap	RefCell	Faster for large collections
ThreadLocalFastHashArena	ahash HashMap	thread_local	Fastest for large + hot loops

These use ahash instead of SipHash for improved throughput. Not DOS-resistant, but suitable for local, non-hostile environments.

Macros

impl_hashmap_map_storage 🔒

Implement MapStorage for a HashMap-like type.

Structs

Arena

A reference-counted arena for GC protection, generic over map type.

ArenaGuard

An RAII guard that unprotects a SEXP when dropped.

ThreadLocalArena

Thread-local BTreeMap-based arena.

ThreadLocalFastHashArena

Thread-local fast hash arena using ahash.

ThreadLocalHashArena

Thread-local HashMap-based arena.

Constants

THREAD_LOCAL_BTREE_STATE 🔒

THREAD_LOCAL_FAST_HASH_STATE 🔒

THREAD_LOCAL_HASH_STATE 🔒

Traits

MapStorage

Trait abstracting over map implementations for arena storage.

ThreadLocalArenaOps

Trait providing default implementations for all thread-local arena methods.

Type Aliases

FastHashMap

HashMap with ahash for faster hashing (not DOS-resistant).

FastHashMapArena

Fast hash arena using ahash (requires refcount-fast-hash feature).

HashMapArena

HashMap-based arena (faster for large collections).

NoSendSync 🔒

Enforces !Send + !Sync (R API is not thread-safe).

RefCountedArena

BTreeMap-based arena (default, good for reference counting).

RefCountedGuard

Legacy type alias for backwards compatibility.