Dispatch Engine

The dispatch engine matches ride requests with available drivers using proximity-based search with geographic optimization.

Algorithm Overview

Bounding Box Pre-filter -- SQL WHERE clause limits candidate drivers to a geographic rectangle, using index-friendly comparisons on lat/lng columns
Haversine Distance -- Precise great-circle distance calculation for candidates within the bounding box
Sort & Offer -- Drivers sorted by distance (nearest first), ride offered sequentially

Bounding Box Optimization

Instead of calculating haversine distance for every driver in the database, the dispatch engine first applies a bounding box filter:

$latDelta = $radiusKm / 111.0;
$lngDelta = $radiusKm / (111.0 * cos(deg2rad($pickupLat)));

$query->where($db->quoteName('s.current_lat') . ' BETWEEN :latMin AND :latMax')
      ->where($db->quoteName('s.current_lng') . ' BETWEEN :lngMin AND :lngMax');

This reduces the candidate set from potentially thousands of drivers to only those within the approximate radius, making the haversine calculation feasible even with large driver fleets.

Configuration

Parameter	Source	Default
Max Dispatch Radius	Plugin params	10 km
Dispatch Timeout	Plugin params	60 seconds
Max Dispatch Attempts	Plugin params	5

Dispatch Record

Each offer creates a dispatch record tracking:

Driver offered
Attempt number
Distance to pickup
ETA estimate
Response (accepted/rejected/expired)
Timestamps (offered, responded)

Re-dispatch Flow

When a driver rejects or times out:

Dispatch record updated to rejected or expired
Next nearest driver selected (excluding already-offered drivers)
New dispatch record created with incremented attempt number
Process repeats until a driver accepts or max attempts reached

No Driver Available

If all dispatch attempts are exhausted:

Ride status set to no_driver
Rider notified
Rider may retry (creates fresh dispatch cycle)

Race Condition Prevention

Driver acceptance uses FOR UPDATE locking to prevent a driver from being assigned to multiple rides simultaneously. When two rides try to claim the same driver, only one will succeed.

Pages