CardPictureLoaderWorker Class Reference

Handles asynchronous loading of card images, both locally and via network. More...

#include <card_picture_loader_worker.h>

Inheritance diagram for CardPictureLoaderWorker:

Collaboration diagram for CardPictureLoaderWorker:

Public Slots
void	clearNetworkCache ()
	Clears the network cache and redirect cache.
QNetworkReply *	makeRequest (const QUrl &url, CardPictureLoaderWorkerWork *workThread)
	Makes a network request for the given URL using the specified worker.
void	processQueuedRequests ()
	Ensures the pacing and quota-reset timers reflect the current queue and recovery state.
void	dispatchQueuedRequest ()
	Chooses a request from the queue and starts it, respecting the quota and pacing.
bool	processSingleRequest ()
	Processes a single queued request.
void	handleImageLoaded (const ExactCard &card, const QImage &image)
	Handles an image that has finished loading.
void	cacheRedirect (const QUrl &originalUrl, const QUrl &redirectUrl)
	Caches a redirect mapping between original and redirected URL.
void	removedCachedUrl (const QUrl &url)
	Removes a URL from the network cache.

Signals
void	imageLoadEnqueued (const ExactCard &card)
	Emitted when an image load is enqueued.
void	imageLoaded (const ExactCard &card, const QImage &image)
	Emitted when an image has finished loading.
void	imageRequestQueued (const QUrl &url, const ExactCard &card, const QString &setName)
	Emitted when a request is added to the network queue.
void	imageRequestSucceeded (const QUrl &url)
	Emitted when a network request successfully completes.
void	networkCacheCleared ()
	Emitted after clearNetworkCache() has finished clearing both caches.

Public Member Functions
	CardPictureLoaderWorker ()
	Constructs a CardPictureLoaderWorker.
	~CardPictureLoaderWorker () override
void	enqueueImageLoad (const ExactCard &card)
	Enqueues an ExactCard for loading.
void	queueRequest (const QUrl &url, CardPictureLoaderWorkerWork *worker)
	Queues a network request for a given URL and worker thread.
void	onHostRateLimited (const QString &host)
	Handles a server returning HTTP 429 by reducing that host's request quota.
bool	shutdownThread ()
	Stops the worker thread and reports whether it stopped.
QThread *	workerThread () const
	Returns the worker's QThread.

Private Slots
void	resetRequestQuota ()
	Resets the request quota for rate-limiting.
void	handleImageLoadEnqueued (const ExactCard &card)
	Handles image load requests enqueued on this worker.

Private Member Functions
int	hostAllowanceCeiling (const QString &host) const
	Effective per-host allowance ceiling for a host.
bool	isUnlockedHost (const QString &host) const
	Whether a host may skip dispatch pacing and per-host allowance entirely.
QUrl	getCachedRedirect (const QUrl &originalUrl) const
	Returns cached redirect URL for the given original URL, if available.
bool	requestTouchesNetwork (const QUrl &url) const
	Whether a request for this URL would actually touch the network, rather than being served from the disk cache.
QUrl	resolveCachedRedirect (const QUrl &url) const
	Follows the cached-redirect chain to the URL that will actually be requested.
void	loadRedirectCache ()
	Loads redirect cache from disk.
void	saveRedirectCache () const
	Saves redirect cache to disk.
void	cleanStaleEntries ()
	Removes stale redirect entries older than TTL.
void	updateTimerState ()
	Starts or stops the pacing and quota-reset timers to match the queue and recovery state.

Private Attributes
QThread *	pictureLoaderThread
	Thread for executing worker tasks.
QNetworkAccessManager *	networkManager
	Network manager for HTTP requests.
QNetworkDiskCache *	cache
	Disk cache for downloaded images.
QHash< QUrl, QPair< QUrl, QDateTime > >	redirectCache
	Maps original URLs to redirects with timestamp.
QString	cacheFilePath
	Path to persistent redirect cache file.
bool	picDownload
	Whether downloading images from network is enabled.
QQueue< QPair< QUrl, CardPictureLoaderWorkerWork * > >	requestLoadQueue
	Queue of pending network requests.
QTimer	requestTimer
	Timer to reset the request quota.
QTimer	dispatchTimer
	Timer pacing individual network requests.
QHash< QString, int >	hostRequestQuota
	Sustained per-host request allowance.
QHash< QString, int >	hostRequestLimits
	User-set per-host request allowances.
QHash< QString, int >	hostQuotaRemaining
	Per-host allowance left in the current second.
QHash< QString, QDateTime >	hostLast429
	When each host was last rate limited.
QHash< QString, int >	hostInFlight
	Network replies currently in flight, per host.
CardPictureLoaderLocal *	localLoader
	Loader for local images.
QSet< QString >	currentlyLoading
	Deduplication: contains pixmapCacheKey currently being loaded.

Static Private Attributes
static constexpr int	CacheTTLInDays = 30
	Time-to-live for redirect cache entries (days).
static constexpr int	MAX_IN_FLIGHT_PER_HOST = 6
	Maximum concurrent in-flight network replies per host.
static constexpr int	MAX_REDIRECT_CHAIN_DEPTH = 10
	Bound on how many cached-redirect hops dispatch resolution will follow.

Detailed Description

Handles asynchronous loading of card images, both locally and via network.

Responsibilities:

• Maintain a queue of network image requests with rate-limiting.
• Load images from local cache first via CardPictureLoaderLocal.
• Handle network redirects and persistent caching of redirects.
• Deduplicate simultaneous requests for the same card.
• Emit signals for status updates and loaded images.

Constructor & Destructor Documentation

CardPictureLoaderWorker()

CardPictureLoaderWorker::CardPictureLoaderWorker ( )

explicit

Constructs a CardPictureLoaderWorker.

Initializes network manager, cache, redirect cache, local loader, and request quota timer.

Here is the call graph for this function:

Here is the caller graph for this function:

~CardPictureLoaderWorker()

CardPictureLoaderWorker::~CardPictureLoaderWorker ( )

override

Here is the call graph for this function:

Member Function Documentation

cacheRedirect

void CardPictureLoaderWorker::cacheRedirect ( const QUrl & originalUrl, const QUrl & redirectUrl )

slot

Caches a redirect mapping between original and redirected URL.

Here is the caller graph for this function:

cleanStaleEntries()

void CardPictureLoaderWorker::cleanStaleEntries ( )

private

Removes stale redirect entries older than TTL.

Here is the call graph for this function:

Here is the caller graph for this function:

clearNetworkCache

void CardPictureLoaderWorker::clearNetworkCache ( )

slot

Clears the network cache and redirect cache.

Runs on the worker thread; invoke it via a queued call when coming from another thread, since both caches are owned by the worker thread.

Here is the call graph for this function:

Here is the caller graph for this function:

dispatchQueuedRequest

void CardPictureLoaderWorker::dispatchQueuedRequest ( )

slot

Chooses a request from the queue and starts it, respecting the quota and pacing.

Here is the call graph for this function:

Here is the caller graph for this function:

enqueueImageLoad()

void CardPictureLoaderWorker::enqueueImageLoad

(

const ExactCard &

card

)

Enqueues an ExactCard for loading.

Parameters

card	ExactCard to load

This will first try to load the image locally; if that fails, it will enqueue a network request.

Here is the call graph for this function:

Here is the caller graph for this function:

getCachedRedirect()

QUrl CardPictureLoaderWorker::getCachedRedirect ( const QUrl & originalUrl ) const

nodiscardprivate

Returns cached redirect URL for the given original URL, if available.

Here is the caller graph for this function:

handleImageLoaded

void CardPictureLoaderWorker::handleImageLoaded ( const ExactCard & card, const QImage & image )

slot

Handles an image that has finished loading.

Parameters

card	The ExactCard that was loaded
image	The loaded QImage; empty if loading failed

Called when image loading is done. Failures are indicated by an empty QImage.

Here is the call graph for this function:

Here is the caller graph for this function:

handleImageLoadEnqueued

void CardPictureLoaderWorker::handleImageLoadEnqueued ( const ExactCard & card )

privateslot

Handles image load requests enqueued on this worker.

Here is the call graph for this function:

Here is the caller graph for this function:

hostAllowanceCeiling()

int CardPictureLoaderWorker::hostAllowanceCeiling ( const QString & host ) const

nodiscardprivate

Effective per-host allowance ceiling for a host.

Parameters

host	The host to look up

Returns

The allowance ceiling in requests/second, or DownloadSettings::UNLIMITED_HOST_QUOTA when the developer unlocked the host and no user limit is set for it.

Here is the call graph for this function:

Here is the caller graph for this function:

imageLoaded

void CardPictureLoaderWorker::imageLoaded ( const ExactCard & card, const QImage & image )

signal

Emitted when an image has finished loading.

Here is the caller graph for this function:

imageLoadEnqueued

void CardPictureLoaderWorker::imageLoadEnqueued ( const ExactCard & card )

signal

Emitted when an image load is enqueued.

Here is the caller graph for this function:

imageRequestQueued

void CardPictureLoaderWorker::imageRequestQueued ( const QUrl & url, const ExactCard & card, const QString & setName )

signal

Emitted when a request is added to the network queue.

Here is the caller graph for this function:

imageRequestSucceeded

void CardPictureLoaderWorker::imageRequestSucceeded ( const QUrl & url )

signal

Emitted when a network request successfully completes.

Here is the caller graph for this function:

isUnlockedHost()

bool CardPictureLoaderWorker::isUnlockedHost ( const QString & host ) const

nodiscardprivate

Whether a host may skip dispatch pacing and per-host allowance entirely.

A host is unlocked while it has no user limit and no reduced allowance installed by a 429. A 429 drops it out of the fast path until resetRequestQuota() walks the allowance back up.

Here is the call graph for this function:

Here is the caller graph for this function:

loadRedirectCache()

void CardPictureLoaderWorker::loadRedirectCache ( )

private

Loads redirect cache from disk.

Here is the caller graph for this function:

makeRequest

QNetworkReply * CardPictureLoaderWorker::makeRequest ( const QUrl & url, CardPictureLoaderWorkerWork * workThread )

slot

Makes a network request for the given URL using the specified worker.

Parameters

url	URL to load
workThread	Worker handling the request

Returns

The QNetworkReply object representing the request

Here is the call graph for this function:

Here is the caller graph for this function:

networkCacheCleared

void CardPictureLoaderWorker::networkCacheCleared ( )

signal

Emitted after clearNetworkCache() has finished clearing both caches.

Here is the caller graph for this function:

onHostRateLimited()

void CardPictureLoaderWorker::onHostRateLimited

(

const QString &

host

)

Handles a server returning HTTP 429 by reducing that host's request quota.

Parameters

host	The host that returned 429

Here is the call graph for this function:

Here is the caller graph for this function:

processQueuedRequests

void CardPictureLoaderWorker::processQueuedRequests ( )

slot

Ensures the pacing and quota-reset timers reflect the current queue and recovery state.

Here is the call graph for this function:

Here is the caller graph for this function:

processSingleRequest

bool CardPictureLoaderWorker::processSingleRequest ( )

slot

Processes a single queued request.

Returns

true if a request was processed, false if queue is empty.

Here is the call graph for this function:

Here is the caller graph for this function:

queueRequest()

void CardPictureLoaderWorker::queueRequest	(	const QUrl &	url,
		CardPictureLoaderWorkerWork *	worker )

Queues a network request for a given URL and worker thread.

Parameters

url	URL to load
worker	Worker handling this request

Here is the call graph for this function:

Here is the caller graph for this function:

removedCachedUrl

void CardPictureLoaderWorker::removedCachedUrl ( const QUrl & url )

slot

Removes a URL from the network cache.

Here is the caller graph for this function:

requestTouchesNetwork()

bool CardPictureLoaderWorker::requestTouchesNetwork ( const QUrl & url ) const

nodiscardprivate

Whether a request for this URL would actually touch the network, rather than being served from the disk cache.

Here is the call graph for this function:

Here is the caller graph for this function:

resetRequestQuota

void CardPictureLoaderWorker::resetRequestQuota ( )

privateslot

Resets the request quota for rate-limiting.

Here is the call graph for this function:

Here is the caller graph for this function:

resolveCachedRedirect()

QUrl CardPictureLoaderWorker::resolveCachedRedirect ( const QUrl & url ) const

nodiscardprivate

Follows the cached-redirect chain to the URL that will actually be requested.

Parameters

url	The URL to resolve

Returns

The final URL after chasing cached redirects, or url itself if none lead elsewhere

Dispatch decisions (unlocked-host fast path, 429 backoff, in-flight cap) must key on the host a request really goes to, not the URL that merely redirects to it.

Here is the call graph for this function:

Here is the caller graph for this function:

saveRedirectCache()

void CardPictureLoaderWorker::saveRedirectCache ( ) const

private

Saves redirect cache to disk.

Here is the caller graph for this function:

shutdownThread()

bool CardPictureLoaderWorker::shutdownThread ( )

nodiscard

Stops the worker thread and reports whether it stopped.

Called from the owning thread (CardPictureLoader) on its way out. QThread::quit() posts an exit request to the worker's event loop and QThread::wait() blocks (bounded) until the loop has returned and the thread finished. Only QThread members are touched here, so this method is safe to call from the owning thread. The worker object itself is freed by the finished() -> deleteLater chain (see the constructor); the QThread object is deleted afterwards by the owner (CardPictureLoader::~CardPictureLoader), not by this method.

Returns

true if the thread stopped within the timeout, false if it is still running (in which case the owner must not delete the QThread).

Here is the caller graph for this function:

updateTimerState()

void CardPictureLoaderWorker::updateTimerState ( )

private

Starts or stops the pacing and quota-reset timers to match the queue and recovery state.

Here is the caller graph for this function:

workerThread()

QThread * CardPictureLoaderWorker::workerThread

(

)

const

Returns the worker's QThread.

Returns

The worker thread

Only meaningful while the worker object is alive; capture it before calling shutdownThread().

Here is the caller graph for this function:

Member Data Documentation

cache

QNetworkDiskCache* CardPictureLoaderWorker::cache

private

Disk cache for downloaded images.

cacheFilePath

QString CardPictureLoaderWorker::cacheFilePath

private

Path to persistent redirect cache file.

CacheTTLInDays

int CardPictureLoaderWorker::CacheTTLInDays = 30

staticconstexprprivate

Time-to-live for redirect cache entries (days).

currentlyLoading

QSet<QString> CardPictureLoaderWorker::currentlyLoading

private

Deduplication: contains pixmapCacheKey currently being loaded.

dispatchTimer

QTimer CardPictureLoaderWorker::dispatchTimer

private

Timer pacing individual network requests.

hostInFlight

QHash<QString, int> CardPictureLoaderWorker::hostInFlight

private

Network replies currently in flight, per host.

hostLast429

QHash<QString, QDateTime> CardPictureLoaderWorker::hostLast429

private

When each host was last rate limited.

hostQuotaRemaining

QHash<QString, int> CardPictureLoaderWorker::hostQuotaRemaining

private

Per-host allowance left in the current second.

hostRequestLimits

QHash<QString, int> CardPictureLoaderWorker::hostRequestLimits

private

User-set per-host request allowances.

hostRequestQuota

QHash<QString, int> CardPictureLoaderWorker::hostRequestQuota

private

Sustained per-host request allowance.

localLoader

CardPictureLoaderLocal* CardPictureLoaderWorker::localLoader

private

Loader for local images.

MAX_IN_FLIGHT_PER_HOST

int CardPictureLoaderWorker::MAX_IN_FLIGHT_PER_HOST = 6

staticconstexprprivate

Maximum concurrent in-flight network replies per host.

MAX_REDIRECT_CHAIN_DEPTH

int CardPictureLoaderWorker::MAX_REDIRECT_CHAIN_DEPTH = 10

staticconstexprprivate

Bound on how many cached-redirect hops dispatch resolution will follow.

networkManager

QNetworkAccessManager* CardPictureLoaderWorker::networkManager

private

Network manager for HTTP requests.

picDownload

bool CardPictureLoaderWorker::picDownload

private

Whether downloading images from network is enabled.

pictureLoaderThread

QThread* CardPictureLoaderWorker::pictureLoaderThread

private

Thread for executing worker tasks.

redirectCache

QHash<QUrl, QPair<QUrl, QDateTime> > CardPictureLoaderWorker::redirectCache

private

Maps original URLs to redirects with timestamp.

requestLoadQueue

QQueue<QPair<QUrl, CardPictureLoaderWorkerWork *> > CardPictureLoaderWorker::requestLoadQueue

private

Queue of pending network requests.

requestTimer

QTimer CardPictureLoaderWorker::requestTimer

private

Timer to reset the request quota.

---

The documentation for this class was generated from the following files:

• cockatrice/src/interface/card_picture_loader/card_picture_loader_worker.h
• cockatrice/src/interface/card_picture_loader/card_picture_loader_worker.cpp