Class TileRequestScheduler

Namespace

LansMap.Core.Tiles.Sources

Prioritizes and schedules tile fetches by view membership, pan direction, retry budget, and backoff.

public sealed class TileRequestScheduler

Inheritance

object

TileRequestScheduler

Remarks

Time is injected as seconds. In-view tiles and fetch candidates are different sets: only candidates may be queued, but a tile that is merely mid-decode is still wanted, so its backoff is not reclaimed.

Constructors

TileRequestScheduler(int, int)

Creates a scheduler with a concurrency cap and a per-tile retry budget.

public TileRequestScheduler(int maxInFlight, int maxRetries)

Parameters

maxInFlight int

Maximum concurrent fetches.

maxRetries int

Fetch attempts before a tile is treated as permanently failed.

Fields

StarvationGuaranteeSeconds

public const double StarvationGuaranteeSeconds = 5

Field Value

double

Properties

FailureCount

Number of failure records, including permanent ones that never expire.

public int FailureCount { get; }

Property Value

int

InFlightCount

Number of fetches occupying a slot right now.

public int InFlightCount { get; }

Property Value

int

TransientFailureCount

Subset of FailureCount that can still be reclaimed once backoff elapses and the tile leaves the wanted set. Excludes permanent records.

public int TransientFailureCount { get; }

Property Value

int

Methods

CollectCancellations(double, List<TileCoord>)

Collects in-flight tiles that left the wanted set: unconditionally below 0.7 of the download finished, or at/above 0.7 but stalled with no forward progress for longer than the stale-hold reclaim window. The caller aborts them and must then call MarkCancelled(TileCoord).

public void CollectCancellations(double now, List<TileCoord> result)

Parameters

now double

Current time in seconds.

result List<TileCoord>

Cleared first, then filled. A tile missing from candidates only because it is mid-decode is not offered.

ForgetCompleted(long)

Forgets a completion so an evicted tile can be fetched again.

public void ForgetCompleted(long key)

Parameters

key long

Packed tile key.

IsBackingOff(long, double)

True while a failed or refused tile is inside its backoff window.

public bool IsBackingOff(long key, double now)

Parameters

key long

Packed tile key.

now double

Current time in seconds.

Returns

bool

True when a failure record exists and now is still before its retry instant. Callers of TryDequeue(double, out TileCoord) already get this skip; a requester that calls around it must ask.

IsPermanentlyFailed(long)

True when this tile should not be requested again: a classified permanent error, or fetch attempts at the retry cap.

public bool IsPermanentlyFailed(long key)

Parameters

key long

Packed tile key.

Returns

bool

True for a permanent or exhausted-retry record. Upload refusals alone never set this.

MarkCancelled(TileCoord)

Releases the in-flight slot after the caller aborted the fetch. Does not record a failure.

public void MarkCancelled(TileCoord t)

Parameters

t TileCoord

Tile previously listed by CollectCancellations(double, List<TileCoord>).

MarkCompleted(TileCoord)

Records a successful upload: releases the slot, clears backoff, and will not fetch again until ForgetCompleted(long).

public void MarkCompleted(TileCoord t)

Parameters

t TileCoord

Tile now resident.

MarkFailed(TileCoord, double)

Records a failed fetch as a transport error. Prefer the classified overload for network failures.

public void MarkFailed(TileCoord t, double now)

Parameters

t TileCoord

Tile whose fetch failed.

now double

Current time in seconds, for backoff.

MarkFailed(TileCoord, double, TileFetchError)

Records a failed fetch. Permanent errors (not found, unauthorized, protocol) stop immediately and survive leaving the view; others increment the retry budget and back off.

public void MarkFailed(TileCoord t, double now, TileFetchError error)

Parameters

t TileCoord

Tile whose fetch failed.

now double

Current time in seconds, for backoff.

error TileFetchError

Classified fetch outcome.

Remarks

Backoff is exponential from 0.5 s, capped at 30 s, scaled by the error class, and never shortens a longer wait the tile already earned. The tile is re-pended immediately when it is still a candidate and under the retry cap.

MarkProgress(TileCoord, float)

Updates download progress for an in-flight tile. Unknown tiles are ignored.

public void MarkProgress(TileCoord t, float progress)

Parameters

t TileCoord

In-flight tile.

progress float

Fraction complete, 0 to 1; CollectCancellations(double, List<TileCoord>) aborts unwanted fetches still below 0.7 immediately, and unwanted fetches at or above 0.7 once stalled past its stale-hold reclaim window.

MarkStarted(TileCoord)

Records that a fetch for this tile now occupies an in-flight slot.

public void MarkStarted(TileCoord t)

Parameters

t TileCoord

Tile whose transport has started.

MarkUploadRefused(TileCoord, double)

Records that the fetch succeeded but residency refused the upload. Does not charge the retry budget and does not mark the tile completed.

public void MarkUploadRefused(TileCoord t, double now)

Parameters

t TileCoord

Tile whose decoded payload was not stored.

now double

Current time in seconds, for a refusals-only backoff that never shortens a wait a fetch failure already earned.

Requeue(TileCoord)

Puts a dequeued tile back when the caller could not start it. No-op if already completed or in flight.

public void Requeue(TileCoord t)

Parameters

t TileCoord

Tile previously returned by TryDequeue(double, out TileCoord).

ResetFailures()

Clears every failure record, including permanent ones. Completions are left in place.

public void ResetFailures()

TryDequeue(double, out TileCoord)

Takes the highest-priority pending tile that is not backing off, if a slot is free.

public bool TryDequeue(double now, out TileCoord tile)

Parameters

now double

Current time in seconds; tiles still inside their backoff window are skipped.

tile TileCoord

The dequeued coordinate on success; default otherwise.

Returns

bool

True when a tile was dequeued. False when in-flight is at cap or every pending tile is backing off.

UpdateVisible(double, List<TileCoord>, List<TileCoord>, TileCoord, double, double)

Rebuilds the wanted set and the pending fetch list for this frame.

public void UpdateVisible(double now, List<TileCoord> inView, List<TileCoord> candidates, TileCoord centerTile, double velTileX, double velTileY)

Parameters

now double

Current time in seconds.

inView List<TileCoord>

Whole footprint this frame is drawing; those keys stay wanted even if not fetchable.

candidates List<TileCoord>

Subset that still needs fetching (not resident, not queued for decode). Only these may be queued. Off-screen prefetch keys listed here are wanted too.

centerTile TileCoord

View center in tile coordinates, for priority.

velTileX double

Pan velocity X in tiles per second, same zoom as centerTile.

velTileY double

Pan velocity Y in tiles per second, same zoom as centerTile.

Remarks

Pass the same list for both roles when there is no residency of your own. A key in neither list gets its retry budget back once backoff elapses, except permanent failures. Completed tiles, in-flight tiles, and tiles at the retry cap or already marked permanent are not pended.