# Inputs and Outputs

> USearch for Java

### Arenas

Every output whose length only the call knows, such as matches, rows, products, monoliths and cursor or stream batches, lands in an `Arena` you pass, and the verb answers a view over it without copying.
`new Arena(executor)` places it where that executor computes, decided once, and `new Arena()` makes host pages for the calling thread.
Each call rewinds its arena, so the previous call's views die and a steady loop allocates once.
To keep a result past the next call, or to read one while making the next, pass that call another arena.
An arena serves one call at a time, so each deferred call needs its own.
A stale view's segments are closed, so reading one throws `IllegalStateException`.
An arena from a VRAM executor holds device memory, which host accessors refuse with `Status.DEVICE`.
It grows, fills and frees on that executor's first stream, so it serves only calls on that executor, keeps it reachable, and must be closed before it; a host arena may outlive its executor.

```java
try (Arena arena = new Arena(pool)) {
    for (RowsView batch : batches) {
        Matches matches = index.on(pool).search(batch, 10, arena);    // rewinds: last batch's matches are gone
        total += matches.score(0, 0);
}
}
try (Arena found = new Arena(); Arena fetched = new Arena()) {       // two live results, two arenas
    Matches hits = index.search(query, 10, found);
    for (int rank = 0; rank < hits.count(0); ++rank) {
        rerank(hits.key(0, rank), index.get(hits.key(0, rank), Scalar.F32, fetched));
}
}
List<Deferred<Matches>> calls = new ArrayList<>();
for (int shard = 0; shard < shards.length; ++shard) {
    calls.add(shards[shard].deferred(pools[shard]).search(queries, 10, arenas[shard]));    // one executor and one arena per submitted call
}
for (Deferred<Matches> call : calls) {
    try (call) {
        consume(call.join());
}
}
```

A blocking call holds its arena until it returns, and a deferred one until it is joined, closed or collected.
A call that finds its arena serving another call finishes with `Status.CONTENDED` and rewinds nothing, so the holder's views stay readable.
Closing an arena waits for the deferred calls naming it, and joining one of them afterwards throws `IllegalStateException`.
A null arena is refused with `Status.INVALID_ARGUMENT`, and fixed-size reports, like `DenseTraversalStats` and `describe`, stay the caller's own objects.
Every output verb takes an arena, so there is one verb per operation with no allocating twin, and no index holds an arena of its own.

### Rows & Scalars

Every verb is a batch over strided matrices, so a memory-mapped dataset reaches the index with no reshape and no copy, and a single vector is a one-row matrix.
`RowsView` borrows a `MemorySegment`: a heap one, which the array factories wrap, or a native one for a memory-mapped dataset.
The scalar type of the input is independent of the stored quantization, and the library converts on ingest.

```java
RowsView packed = RowsView.of(new float[] {0, 1, 1, 0}, 2);
RowsView padded = RowsView.strided(MemorySegment.ofArray(slab), rows, 768, 4096, Scalar.I8);
RowsView mapped = RowsView.of(channel.map(MapMode.READ_ONLY, 0, size, java.lang.foreign.Arena.ofAuto()), 768, Scalar.U8);
RowsView direct = RowsView.of(MemorySegment.ofBuffer(buffer), 768, Scalar.F32);
```

A heap segment is copied across the boundary for the duration of one call, since holding the JVM's own storage in place would stall every collector thread for as long as the batch runs.
A native segment is addressed in place with no copy at all, which is the argument to reach for when a batch is large.
A segment over a direct `ByteBuffer` captures the buffer's position and limit once, so moving the buffer later cannot widen what a call reads.

Quantization kinds run from the widest dynamic range down: `BF16`, the default, `F16`, `E5M2`, `E4M3`, `E3M2`, `E2M3`, `I8`, `I4X2`, `U8`, `U4X2`, `U1X8`; `F64` and `F32` cross as inputs and outputs only.
Sub-byte kinds count logical dimensions, so sixteen `U1X8` dimensions occupy two bytes per row.

### Search

Every ranked verb answers its `Matches`, read in place out of the arena: a queries-by-`columns` matrix of keys, the scores positionally paired with them, and one match count per query.
The wanted count is the "k" in kANN and bounds `columns`, the row width of both matrices the call wrote, and a recall sweep reuses one arena across every point, so it allocates once.
`count`, `key` and `score` all address one query by its position, so no call site multiplies out an offset of its own, and slots past a query's count hold memory the engine never wrote and are refused.

The breadth of the candidates rides each call rather than the handle, which lets a recall sweep run against one immutable index with no mutation between points.
Every verb with knobs beyond its inputs has a bare form and one taking its `Dense*Config`, named after the C structure it fills.
`Traversal.WALK`, the default, walks the graph, and `Traversal.SCAN` scores every entry published when the query's scan starts, exactly, on RAM and NVMe handles.
A `DenseTraversalStats` lent to a config is overwritten with what the walk reported, so one reading always belongs to one call.

```java
DenseTraversalStats stats = new DenseTraversalStats();
index.on(pool).insert(keys, vectors, new DenseInsertConfig().expansionFactor(256));
Matches matches = index.on(pool).search(queries, 10, arena);
matches = index.on(pool).search(queries, new DenseSearchConfig(10).expansionFactor(64).stats(stats), arena);
matches = index.on(pool).search(queries, new DenseSearchConfig(10).traversal(Traversal.SCAN), arena);
System.out.println(stats.computedDistances() + " distances computed by the wider search");
```

`import cloud.unum.usearch.*;`

## Scalar

A stored or exchanged scalar type, named by width and encoding.

```java
enum Scalar
```

Sub-byte kinds pack several dimensions per byte, as their xN suffixes spell.

The enumerators are ordered by shrinking dynamic range, and their codes carry the numbering gaps the C enum reserves for kinds not yet implemented.

- `UNKNOWN` ``: A type the library could not name.
- `F64` ``: 64-bit double precision.
- `F32` ``: 32-bit single precision.
- `BF16` ``: The brain floating-point format.
- `F16` ``: IEEE half precision.
- `E5M2` ``: 8-bit floating point with five exponent bits.
- `E4M3` ``: 8-bit floating point with four exponent bits.
- `E3M2` ``: 6-bit floating point with three exponent bits, one per byte.
- `E2M3` ``: 6-bit floating point with two exponent bits, one per byte.
- `I8` ``: An 8-bit signed integer.
- `I4X2` ``: Two 4-bit signed integers per byte.
- `I32` ``: A 32-bit signed integer, the coordinates of geospatial points.
- `U8` ``: An 8-bit unsigned integer.
- `U4X2` ``: Two 4-bit unsigned integers per byte.
- `U1X8` ``: Eight single-bit dimensions per byte.

## Traversal

How a search reaches the indexed entries it scores.

```java
enum Traversal
```

- `WALK` ``: Walks the graph, scoring the entries the expansion reaches - approximate, the default.
- `SCAN` ``: Scores every entry published when the query's scan starts - exact, on RAM and NVMe handles.

## Arena

Memory the library writes every output whose length scales with a call into - the matches of `DenseVerbs#search`, the rows of `DenseVerbs#get`, the products of `DenseVerbs#multiply`, the monolith of `DenseVerbs#saveBuffer` - reused across calls.

```java
class Arena
```

An executor places it where it computes, decided once, and nothing is allocated until a call writes into it. Every output verb requires one and answers a view over it; each call rewinds it, so a steady loop allocates once, and the previous call's views raise `IllegalStateException` rather than read stale memory. To keep one call's views alive past the next, pass the next call another arena.

An arena serves one call at a time and takes no lock: a second call naming it while the first holds it fails with CONTENDED and leaves the first call's views readable. A blocking call holds it until it returns, and a deferred one until it is joined, closed or collected. A VRAM arena holds device memory, so the views over it refuse host reads with DEVICE, and it serves only calls on the executor that made it, which it keeps reachable and which must be closed after it. One the program drops without closing is freed once neither it nor any view over it is reachable.

```
try (Arena arena = new Arena(pool)) {
    for (Key key : keys) {
        DenseVectors vectors = index.on(pool).get(key, Scalar.F32, arena); // valid until the next call given `arena`
    }
}
```

## RowsView

A slab viewed as rows of equal width: a base, a row count, a logical column count, and a byte pitch between consecutive row starts.

```java
class RowsView
```

It is the shape every batch argument takes, from `DenseVerbs#insert` to `DenseVerbs#attend`.

The slab is a `MemorySegment`: a heap one, as the array factories wrap, is copied into native memory for the duration of one call and never retained, and a native one - a mapped file, a direct buffer through `MemorySegment#ofBuffer`, an arena allocation - is addressed in place with no copy. A view borrows and never owns, so a native slab must stay open until every call it crosses is final.

## Matches

A ranked run a call wrote into its arena - a queries-by-columns matrix of keys, the scores positionally paired with them, and one match count per query, all read in place.

```java
class Matches
```

`key(int, int)` materializes a `[Key](https://www.unum.cloud/docs/usearch/java/keys.md#Key)` only for the slots a caller reads. Slots past a query's count hold memory the engine never wrote, so every accessor here refuses them. Valid until the arena's next call or its close, after which every accessor raises `IllegalStateException`.