# cartographer/sensor/collator_interface.h

## Overview

`CollatorInterface` is the abstract interface for sensor collators. A collator receives raw sensor `Data` packets for multiple trajectories, reorders/synchronizes them, and dispatches them to the appropriate trajectory builder via a callback. Concrete implementations are `Collator` (a single global collator for all trajectories) and `TrajectoryCollator` (a per-trajectory collator).

## Class: `cartographer::sensor::CollatorInterface`

### Callback

```cpp
using Callback =
    std::function<void(const std::string&, std::unique_ptr<Data>)>;
```

Invoked for each collated packet with the sensor ID and the data to dispatch.

### Interface

```cpp
class CollatorInterface {
 public:
  // Adds a trajectory to produce sorted sensor output for. Calls 'callback'
  // for each collated sensor data.
  virtual void AddTrajectory(
      int trajectory_id,
      const absl::flat_hash_set<std::string>& expected_sensor_ids,
      const Callback& callback) = 0;

  // Marks 'trajectory_id' as finished.
  virtual void FinishTrajectory(int trajectory_id) = 0;

  // Adds 'data' for 'trajectory_id' to be collated. 'data' must contain valid
  // sensor data. Sensor packets with matching 'data.sensor_id_' must be added
  // in time order.
  virtual void AddSensorData(int trajectory_id, std::unique_ptr<Data> data) = 0;

  // Dispatches all queued sensor packets. May only be called once.
  // AddSensorData may not be called after Flush.
  virtual void Flush() = 0;

  // Must only be called if at least one unfinished trajectory exists. Returns
  // the ID of the trajectory that needs more data before CollatorInterface is
  // unblocked. Returns 'nullopt' for implementations that do not wait for a
  // particular trajectory.
  virtual absl::optional<int> GetBlockingTrajectoryId() const = 0;
};
```

### Contract Notes

- `AddSensorData` — packets for a given sensor must be added in time order.
- `Flush` — dispatches all queued packets and may be called only once; afterwards `AddSensorData` is disallowed.
- `GetBlockingTrajectoryId` — used by the pose graph / map builder to wait for the trajectory that is lagging behind (returning `nullopt` means no particular trajectory blocks progress, as in `TrajectoryCollator`).

## Implementations

| Implementation | Scope | Synchronization behavior |
|----------------|-------|--------------------------|
| `Collator` | Single queue across all trajectories | Waits for every expected sensor of the blocking trajectory; deterministic output |
| `TrajectoryCollator` | One `OrderedMultiQueue` per trajectory | Waits only for the sensors of a single trajectory; non-deterministic interleaving between trajectories |

## Role in the SLAM Pipeline

`MapBuilder` constructs the collator based on the `collate_by_trajectory` option:
- `false` — a single `Collator` instance for all trajectories (default).
- `true` — a `TrajectoryCollator` with one queue per trajectory.

Sensor drivers call `AddSensorData(trajectory_id, MakeDispatchable(...))`, and the collator's callback hands each `Data` packet to `TrajectoryBuilderInterface::AddSensorData(sensor_id, std::move(data))`.

## See Also

- [TrajectoryCollator](internal/trajectory_collator.md) — Per-trajectory implementation
- [Collator](internal/collator.md) — Single-queue implementation
- [OrderedMultiQueue](internal/ordered_multi_queue.md) — Synchronization primitive
- [Dispatchable](internal/dispatchable.md) — Wraps data for the collator
- [MapBuilder](../mapping/map_builder.md) — Constructs the collator