Fix Issue 14097 - root/async.c: free after use

Also add some docs.

src/root/async.c

@@ -109,7 +109,15 @@ unsigned __stdcall startthread(void *p)
     AsyncRead *aw = (AsyncRead *)p;
 
     //printf("aw->filesdim = %p %d\n", aw, aw->filesdim);
-    for (size_t i = 0; i < aw->filesdim; i++)
+
+    // We need to cache aw->filesdim in order to prevent it from
+    // being accessed after aw is freed. (It is possible that just
+    // before the loop finishes the main thread calls
+    // AsyncRead::dispose() and frees aw before it is accessed
+    // for the last time.
+    size_t dim = aw->filesdim;
+
+    for (size_t i = 0; i < dim; i++)
     {   FileData *f = &aw->files[i];
 
         f->result = f->file->read();
@@ -243,7 +251,14 @@ void *startthread(void *p)
     AsyncRead *aw = (AsyncRead *)p;
 
     //printf("startthread: aw->filesdim = %p %d\n", aw, aw->filesdim);
+
+    // We need to cache aw->filesdim in order to prevent it from
+    // being accessed after aw is freed. (It is possible that just
+    // before the loop finishes the main thread calls
+    // AsyncRead::dispose() and frees aw before it is accessed
+    // for the last time.
     size_t dim = aw->filesdim;
+
     for (size_t i = 0; i < dim; i++)
     {   FileData *f = &aw->files[i];
 

src/root/async.h

@@ -22,10 +22,25 @@
 
 struct AsyncRead
 {
+    // Creates a new instance of a AsyncRead. `nfiles` is maximum
+    // number of files that can be queued for reading.
     static AsyncRead *create(size_t nfiles);
+
+    // Queues a file for reading. Can only be called before `start()`.
+    // Only `nfiles` can be added to the queue (`nfiles` is the
+    // parameter to `create()`).
     void addFile(File *file);
+
+    // Starts a background thread which reads (asynchronously) all queued files.
     void start();
+
+    // Blocks the calling thread until the background thread
+    // finishes reading the i-th file.
     int read(size_t i);
+
+    // Frees the object returned by `AsyncRead::create()`. It is safe to call
+    // only after `read()` is called for all queued files, because it doesn't
+    // wait for the background thread to finish.
     static void dispose(AsyncRead *);
 };