The Dragon Feed

"Every rev (factor) of the dragon is a warning. Every gearshift bears the load (memory). The dragon unleashes its might at 1.0f, packing your data into the map like it never even felt it."

The Dragon Feed is the internal bulk-loading engine of ChaosTree's B-Tree and B+Tree architectures. Instead of utilizing standard iterative insertions—which suffer from pointer chasing, tree rebalancing, and heavy GC allocation rates—the Dragon Feed directly ingests raw sorted matrices and compiles them into contiguous memory pages.

The Gears (Packing Factor)

The Dragon Feed exposes a factor parameter, acting as the transmission for the engine. It dictates exactly how tightly the internal arrays should be packed during bulk ingestion.

- 0.5f (First Gear): 50% capacity. Leaves room for future random insertions without triggering node splits. Highest initial memory footprint.
- 1.0f (Top Gear): 100% capacity. Zero wasted bytes. Maximum CPU cache line saturation. Pure throughput.

15 Million Elements: The Parameter Sweep

The following benchmark demonstrates the flawless mathematical scaling of the Dragon Feed. As the packing factor increases, memory allocation and execution time drop in absolute linear lockstep.

Benchmark	Factor	Time (ms)	Allocated (MB)	GC Pauses (ms)
B+Tree	0.5f	25.00	256.5	247
B+Tree	0.6f	21.59	213.4	107
B+Tree	0.7f	20.48	182.7	360
B+Tree	0.8f	18.31	159.7	235
B+Tree	0.9f	17.10	141.8	274
B+Tree	1.0f	15.96	126.9	301
B-Tree	1.0f	15.76	126	193

At 1.0f, the engine processes 15,000,000 elements in 15.9 milliseconds, consuming only 126 MB of heap. There is zero algorithmic overhead remaining; execution time is strictly bound by main memory bandwidth and cache retrieval.

Usage

1. By Constructor

// Use the Dragon at top gear (1.0f)
// It is advised to leave a space for future operation.
// 1. Prepare your sorted data matrix
Integer[] sortedKeys = {1, 2, 3, 4, 5};
String[] values = {"A", "B", "C", "D", "E"};
Object[][] matrix = new Object[][]{sortedKeys, values};

// 2. Feed the Dragon
BPlusTreeMap fastMap = new BPlusTreeMap<>(
    BPlusTreeMap.Builder.degree(64)
        .factor(0.8f) // 80% packing density, leaves room for runtime inserts
        .importFlatMatrix(matrix)
        .build()
);

2. By Public API through array

WARNING: THE TRUE DRAGON OF CHAOSTREE. This is a high-performance, bare-metal array ingestion engine. It is hungry for raw array throughput, but it is extremely unforgiving. Use with absolute precision. THE FLAT MATRIX RULES:

Matrix Layout: The blast parameter must be exactly 2D: blast[0] contains the keys, and blast[1] contains the values.
Array Integrity: Neither array can be null, and both must be of exactly equal length.
No Null Keys: A key must never be null. If a value is empty/missing, you must explicitly place null in the value array at that index.
Strictly Sorted: The keys array MUST be strictly sorted according to the tree's comparator. Feeding unsorted data will instantly and silently corrupt the entire tree structure.
Minimum Degree: This API relies on chunked array-copying and only services trees with a degree >= 32.
FILL FACTOR: The factor determines node occupancy and has strict limits between 0.5f and 1.0f. A factor of 0.75f is highly recommended for bulk loading. This packs the nodes densely while leaving exactly enough buffer room to prevent future insertions from triggering massive, cascading split operations. Hold the Chaos!

Method: abstract void importFlatMatrix(Object[][] blast, float factor); Parameters: blast A 2D array where blast[0] is the sorted keys and blast[1] is the mapped values. factor The node fill factor, restricted to the range [0.5, 1.0].

    // Awaken the Dragon at top gear (1.0f)
    BPlusTreeMap<Integer, String> map = new BPlusTreeMap<>()
    //this creates a default degree of 64 and comparator null!
    map.insertFromMatrix(blast, factor);

3. By Public API through Sorted Map.Entry

Streams strictly sorted data directly into the tree in O(N) time.

WARNING: The provided iterator MUST yield elements in strict ascending order according to this tree's comparator. If the data is unsorted, the tree structure will be corrupted.

FILL FACTOR:

A value between 0.5 and 1.0 representing how full to pack each node.
Use 1.0f for read-only data.
Use a lower value to leave room for future insertions.
A value of 0.9f is used for bulk loading in my tree.
For read purposes, you can use 1.0f, but after that, any insert or remove operation will trigger massive split, merge, borrow, and array-shifting operations.

Parameters:

sortedData: An iterator providing strictly sorted elements.
fillFactor: A value between 0.5 and 1.0 representing how full to pack each node.

public void buildFromSorted(Iterator> it, float factor) The factor provide the node density [0.5f, 1f] more you pack the less it's take memory. Internally used in Serialization at a factor of 0.75f.

    // Use the Dragon at top gear (1.0f)
    BPlusTreeMap<Integer, String> map = new BPlusTreeMap<>()
    //this creates a default degree of 64 and comparator null!
    map.buildFromSorted(iterator, factor);

Nary set and map at glance

void buildFromSorted(Iterator it, float factor);
void importFlatArray(Object[] flatArray, float fillFactor);
// Note: Object[] toArray() is inherited from java.util.Collection acting as exportFlastArray()
I have also mentioned in code "You can treat it as exportFlatArray()"

Map Specific
void buildFromSorted(Iterator> it, float factor);
void importFlatMatrix(Object[][] flatMatrix, float factor);
Object[][] exportFlatMatrix();