style(dat): tighten async-read comments and trim LOC

Condense the doc comments and fold ProcessPendingReads' deferred-trigger
vector back into the loop (fire the tickle under the lock - it's just a
game-thread enqueue). No behaviour change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3vcloud

GWToolboxdll/Modules/GwDatTextureModule.cpp

@@ -18,11 +18,8 @@
 
 namespace {
 
-    // Game file-request trigger: asks the client to load a file id from its dat/network. Anchored on
-    // the request function's unique DOWNLOAD_FLAG assertion string, so it survives client updates
-    // (unlike a raw byte pattern). It's the enqueue entry; the client pumps its download queue on its
-    // own, so no explicit "kick" is needed, and it's safe to call in-game (the requests-suspended flag
-    // it asserts on is only toggled from the client's Main).
+    // Asks the client to fetch a file id (dat or network). Found via its unique DOWNLOAD_FLAG assert
+    // string (survives client updates); safe in-game and enqueue-only - the client pumps its own queue.
     using RequestFiles_pt = void(__cdecl*)(uint32_t count, const uint32_t* file_ids, uint32_t flags);
     constexpr uint32_t kTriggerFlags = 0; // normal priority, non-cancelable
     RequestFiles_pt RequestFiles_Func = nullptr;
@@ -37,8 +34,7 @@ namespace {
         }
         Log::Log("[GwDat] game file-request trigger resolved at %p", reinterpret_cast<void*>(RequestFiles_Func));
         GwDatArchive::Instance().SetTrigger([](uint32_t file_id) {
-            // The request function touches client state, so issue it on the game thread.
-            GW::GameThread::Enqueue([file_id] {
+            GW::GameThread::Enqueue([file_id] { // touches client state; run on the game thread
                 if (RequestFiles_Func)
                     RequestFiles_Func(1, &file_id, kTriggerFlags);
             });
@@ -350,8 +346,7 @@ void GwDatTextureModule::Initialize()
     ToolboxModule::Initialize();
     // The dat is indexed lazily on the first read; start its dedicated read/decode worker.
     GwDatArchive::Instance().StartWorker();
-    // Let async reads prompt the client to fetch a streamed-only file (best-effort; see the helper).
-    WireGameFileTrigger();
+    WireGameFileTrigger(); // lets async reads tickle the client to fetch streamed-only files
 }
 
 IDirect3DTexture9** GwDatTextureModule::LoadTextureFromFileId(uint32_t file_id, uint32_t stream_id)

GWToolboxdll/Utils/GwDat/GwDatArchive.cpp

@@ -181,9 +181,8 @@ void GwDatArchive::StopWorker()
         std::scoped_lock<std::mutex> lock(m_task_mutex);
         m_worker_running = false;
     }
-    // Drop any undelivered async reads; callers tolerate non-delivery across a worker stop.
     std::scoped_lock<std::mutex> lock(m_pending_mutex);
-    m_pending_reads.clear();
+    m_pending_reads.clear(); // undelivered async reads are dropped on stop
 }
 
 void GwDatArchive::EnqueueTask(std::function<void()> task)
@@ -418,10 +417,10 @@ void GwDatArchive::ReadFileAsync(uint32_t file_id, ReadCallback callback, uint32
         return;
     if (!file_id) {
         std::vector<uint8_t> empty;
-        callback(empty); // nothing to look up
+        callback(empty);
         return;
     }
-    StartWorker(); // the poll loop must be running to deliver
+    StartWorker(); // the poll loop delivers
     const uint32_t deadline = GetTickCount() + kAsyncReadTimeoutMs;
     std::scoped_lock<std::mutex> lock(m_pending_mutex);
     m_pending_reads.push_back({file_id, stream_id, deadline, std::move(callback), false});
@@ -433,41 +432,30 @@ void GwDatArchive::SetTrigger(TriggerFn trigger)
     m_trigger = std::move(trigger);
 }
 
-// Worker-thread pass over the pending async reads: deliver any that now resolve, expire any past
-// their deadline. Callbacks fire outside the lock so they can't stall other ReadFileAsync callers.
+// Worker pass: deliver resolved reads, time out stale ones, tickle the client once per pending file.
 void GwDatArchive::ProcessPendingReads()
 {
-    std::vector<std::pair<ReadCallback, std::vector<uint8_t>>> ready;
-    std::vector<uint32_t> to_trigger; // file ids to ask the client to load, fired outside the lock
-    TriggerFn trigger;
+    std::vector<std::pair<ReadCallback, std::vector<uint8_t>>> ready; // callbacks fire outside the lock
     {
         std::scoped_lock<std::mutex> lock(m_pending_mutex);
-        if (m_pending_reads.empty())
-            return;
-        trigger = m_trigger; // copy so we can call it after releasing the lock
         const uint32_t now = GetTickCount();
         for (auto it = m_pending_reads.begin(); it != m_pending_reads.end();) {
             std::vector<uint8_t> data;
-            if (ReadFile(it->file_id, data, it->stream_id)) {
+            if (ReadFile(it->file_id, data, it->stream_id))
                 ready.emplace_back(std::move(it->callback), std::move(data));
-                it = m_pending_reads.erase(it);
-            }
-            else if (static_cast<int32_t>(now - it->deadline_ms) >= 0) { // deadline passed (wrap-safe)
+            else if (static_cast<int32_t>(now - it->deadline_ms) >= 0) // deadline passed (wrap-safe)
                 ready.emplace_back(std::move(it->callback), std::vector<uint8_t>{});
-                it = m_pending_reads.erase(it);
-            }
             else {
-                // Not resident yet: ask the client to fetch it, but only once per request.
-                if (trigger && !it->triggered) {
-                    to_trigger.push_back(it->file_id);
+                if (m_trigger && !it->triggered) { // ask the client to fetch it, once
+                    m_trigger(it->file_id);
                     it->triggered = true;
                 }
                 ++it;
+                continue;
             }
+            it = m_pending_reads.erase(it);
         }
     }
-    for (uint32_t file_id : to_trigger)
-        trigger(file_id);
     for (auto& [callback, data] : ready)
         callback(data);
 }

GWToolboxdll/Utils/GwDat/GwDatArchive.h

@@ -37,18 +37,14 @@ class GwDatArchive {
     // Decompressed bytes for a GW file id; stream_id picks a stream (0 = the file's own data). False if absent.
     bool ReadFile(uint32_t file_id, std::vector<uint8_t>& out, uint32_t stream_id = 0);
 
-    // Async variant of ReadFile: the worker retries the read until the file appears in the dat, then
-    // invokes `callback` (on the worker thread) with the decompressed bytes; if it hasn't shown up
-    // within ~1 minute the callback fires once with an empty vector. Lets callers wait for files the
-    // client streams in on demand (e.g. Steam .snapshot installs) without blocking. Starts the worker
-    // if needed. Undelivered requests are dropped (callback not called) if the worker is stopped.
+    // Async ReadFile: the worker retries until the file resolves, then calls `callback` (worker
+    // thread) with the bytes, or with an empty vector after ~1 min; dropped if the worker stops.
+    // For files the client streams in on demand (e.g. a Steam .snapshot).
     using ReadCallback = std::function<void(std::vector<uint8_t>&)>;
     void ReadFileAsync(uint32_t file_id, ReadCallback callback, uint32_t stream_id = 0);
 
-    // Optional hook that asks the running client to load a file id (from the dat or the network). When
-    // set, ReadFileAsync calls it once per pending file that isn't resident yet, so streamed-only files
-    // (e.g. a Steam .snapshot) get fetched instead of only waited for. Wired by the GWCA layer, which
-    // owns the game-function lookup; the pure reader here works with or without it.
+    // Optional hook to ask the client to fetch a file id; ReadFileAsync calls it once per pending
+    // file not yet resident. Wired by the GWCA layer; the reader works with or without it.
     using TriggerFn = std::function<void(uint32_t file_id)>;
     void SetTrigger(TriggerFn trigger);
 
@@ -112,13 +108,12 @@ class GwDatArchive {
     bool m_worker_running = false;
     bool m_worker_stop = false;
 
-    // Async ReadFile requests, retried by the worker until the file appears or the deadline passes.
     struct PendingRead {
         uint32_t file_id;
         uint32_t stream_id;
-        uint32_t deadline_ms;   // GetTickCount() value at which this request gives up
+        uint32_t deadline_ms;   // GetTickCount() at which the request gives up
         ReadCallback callback;
-        bool triggered = false; // whether we've already asked the client to load this file
+        bool triggered = false; // whether we've asked the client to fetch it yet
     };
     std::mutex m_pending_mutex; // guards m_pending_reads + m_trigger
     std::vector<PendingRead> m_pending_reads;