CrossRegionBridge (CRB)

CrossRegionBridge (CRB) is an ultra-high-performance, lock-free, and zero-allocation developer framework designed to act as an asynchronous data and task bridge between independent region tick-loops on Folia servers, with a transparent fallback implementation for classic Paper servers.

If you are developing multi-threaded plugins, cross-region features, or complex minigames for Folia, CRB solves the complex threading issues of region-to-region communications safely and efficiently.

Key Features

• Actor-Model Messaging: Regional tick threads communicate exclusively via thread-safe, lock-free message passing.
• Zero-Allocation Object Pool: Reuses message envelopes via a highly concurrent Object Pool to completely eliminate Garbage Collector pressure and prevent micro-stutters/lag spikes.
• Lock-Free Concurrency: Utilizes low-overhead JCTools (MpscQueue for mailboxes, MpmcQueue for pooling) to eliminate thread contention and lock overhead.
• Context-Aware Futures: Solves the biggest issue in Folia development—ensuring that async query callbacks (like .thenAccept(...)) are automatically routed back and executed strictly inside the thread context of the originating region.
• Paper Fallback: Run the exact same codebase on classic Paper servers. The framework transparently routes executions to the main server thread to guarantee Bukkit API safety.
• Minimal Footprint: The core module is entirely clean Java code with zero dependencies on Bukkit/Minecraft internals.

How it Works under the Hood

CRB implements a highly optimized On-Demand Tick Scheduling mechanism:

1. When Region A sends a query to Region B, the message is pushed lock-free into Region B's mailbox.
2. If Region B's mailbox was empty, a task is scheduled on Folia's RegionScheduler using Compare-And-Swap (CAS).
3. Region B processes the mailbox during its next tick, completes the query, and routes a ResponseEnvelope back to Region A.
4. Region A processes the response during its own tick, executing your developer callback safely.

This reactive scheduling ensures absolute zero CPU overhead on inactive or empty regions.