src/io/generic/SDL_asyncio_generic.c - external/github.com/libsdl-org/SDL - Git at Google

 /*
   Simple DirectMedia Layer
   Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>

   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
   arising from the use of this software.

   Permission is granted to anyone to use this software for any purpose,
   including commercial applications, and to alter it and redistribute it
   freely, subject to the following restrictions:

   1. The origin of this software must not be misrepresented; you must not
      claim that you wrote the original software. If you use this software
      in a product, an acknowledgment in the product documentation would be
      appreciated but is not required.
   2. Altered source versions must be plainly marked as such, and must not be
      misrepresented as being the original software.
   3. This notice may not be removed or altered from any source distribution.
 */

 // The generic backend uses a threadpool to block on synchronous i/o.
 // This is not ideal, it's meant to be used if there isn't a platform-specific
 // backend that can do something more efficient!

 #include "SDL_internal.h"
 #include "../SDL_sysasyncio.h"

 // on Emscripten without threads, async i/o is synchronous. Sorry. Almost
 // everything is MEMFS, so it's just a memcpy anyhow, and the Emscripten
 // filesystem APIs don't offer async. In theory, directly accessing
 // persistent storage _does_ offer async APIs at the browser level, but
 // that's not exposed in Emscripten's filesystem abstraction.
 #if defined(SDL_PLATFORM_EMSCRIPTEN) && !defined(__EMSCRIPTEN_PTHREADS__)
 #define SDL_ASYNCIO_USE_THREADPOOL 0
 #else
 #define SDL_ASYNCIO_USE_THREADPOOL 1
 #endif

 typedef struct GenericAsyncIOQueueData
 {
     SDL_Mutex *lock;
     SDL_Condition *condition;
     SDL_AsyncIOTask completed_tasks;
 } GenericAsyncIOQueueData;

 typedef struct GenericAsyncIOData
 {
     SDL_Mutex *lock;  // !!! FIXME: we can skip this lock if we have an equivalent of pread/pwrite
     SDL_IOStream *io;
 } GenericAsyncIOData;

 static void AsyncIOTaskComplete(SDL_AsyncIOTask *task)
 {
     SDL_assert(task->queue);
     GenericAsyncIOQueueData *data = (GenericAsyncIOQueueData *) task->queue->userdata;
     SDL_LockMutex(data->lock);
     LINKED_LIST_PREPEND(task, data->completed_tasks, queue);
     SDL_SignalCondition(data->condition);  // wake a thread waiting on the queue.
     SDL_UnlockMutex(data->lock);
 }

 // synchronous i/o is offloaded onto the threadpool. This function does the threaded work.
 // This is called directly, without a threadpool, if !SDL_ASYNCIO_USE_THREADPOOL.
 static void SynchronousIO(SDL_AsyncIOTask *task)
 {
     SDL_assert(task->result != SDL_ASYNCIO_CANCELED);  // shouldn't have gotten in here if canceled!

     GenericAsyncIOData *data = (GenericAsyncIOData *) task->asyncio->userdata;
     SDL_IOStream *io = data->io;
     const size_t size = (size_t) task->requested_size;
     void *ptr = task->buffer;

     // this seek won't work if two tasks are reading from the same file at the same time,
     // so we lock here. This makes multiple reads from a single file serialize, but different
     // files will still run in parallel. An app can also open the same file twice to avoid this.
     SDL_LockMutex(data->lock);
     if (task->type == SDL_ASYNCIO_TASK_CLOSE) {
         bool okay = true;
         if (task->flush) {
             okay = SDL_FlushIO(data->io);
         }
         okay = SDL_CloseIO(data->io) && okay;
         task->result = okay ? SDL_ASYNCIO_COMPLETE : SDL_ASYNCIO_FAILURE;
     } else if (SDL_SeekIO(io, (Sint64) task->offset, SDL_IO_SEEK_SET) < 0) {
         task->result = SDL_ASYNCIO_FAILURE;
     } else {
         const bool writing = (task->type == SDL_ASYNCIO_TASK_WRITE);
         task->result_size = (Uint64) (writing ? SDL_WriteIO(io, ptr, size) : SDL_ReadIO(io, ptr, size));
         if (task->result_size == task->requested_size) {
             task->result = SDL_ASYNCIO_COMPLETE;
         } else {
             if (writing) {
                 task->result = SDL_ASYNCIO_FAILURE;  // it's always a failure on short writes.
             } else {
                 const SDL_IOStatus status = SDL_GetIOStatus(io);
                 SDL_assert(status != SDL_IO_STATUS_READY);  // this should have either failed or been EOF.
                 SDL_assert(status != SDL_IO_STATUS_NOT_READY);  // these should not be non-blocking reads!
                 task->result = (status == SDL_IO_STATUS_EOF) ? SDL_ASYNCIO_COMPLETE : SDL_ASYNCIO_FAILURE;
             }
         }
     }
     SDL_UnlockMutex(data->lock);

     AsyncIOTaskComplete(task);
 }

 #if SDL_ASYNCIO_USE_THREADPOOL
 static SDL_InitState threadpool_init;
 static SDL_Mutex *threadpool_lock = NULL;
 static bool stop_threadpool = false;
 static SDL_AsyncIOTask threadpool_tasks;
 static SDL_Condition *threadpool_condition = NULL;
 static int max_threadpool_threads = 0;
 static int running_threadpool_threads = 0;
 static int idle_threadpool_threads = 0;
 static int threadpool_threads_spun = 0;

 static int SDLCALL AsyncIOThreadpoolWorker(void *data)
 {
     SDL_LockMutex(threadpool_lock);

     while (!stop_threadpool) {
         SDL_AsyncIOTask *task = LINKED_LIST_START(threadpool_tasks, threadpool);
         if (!task) {
             // if we go 30 seconds without a new task, terminate unless we're the only thread left.
             idle_threadpool_threads++;
             const bool rc = SDL_WaitConditionTimeout(threadpool_condition, threadpool_lock, 30000);
             idle_threadpool_threads--;

             if (!rc) {
                 // decide if we have too many idle threads, and if so, quit to let thread pool shrink when not busy.
                 if (idle_threadpool_threads) {
                     break;
                 }
             }

             continue;
         }

         LINKED_LIST_UNLINK(task, threadpool);

         SDL_UnlockMutex(threadpool_lock);

         // bookkeeping is done, so we drop the mutex and fire the work.
         SynchronousIO(task);

         SDL_LockMutex(threadpool_lock);  // take the lock again and see if there's another task (if not, we'll wait on the Condition).
     }

     running_threadpool_threads--;

     // this is kind of a hack, but this lets us reuse threadpool_condition to block on shutdown until all threads have exited.
     if (stop_threadpool) {
         SDL_BroadcastCondition(threadpool_condition);
     }

     SDL_UnlockMutex(threadpool_lock);

     return 0;
 }

 static bool MaybeSpinNewWorkerThread(void)
 {
     // if all existing threads are busy and the pool of threads isn't maxed out, make a new one.
     if ((idle_threadpool_threads == 0) && (running_threadpool_threads < max_threadpool_threads)) {
         char threadname[32];
         SDL_snprintf(threadname, sizeof (threadname), "SDLasyncio%d", threadpool_threads_spun);
         SDL_Thread *thread = SDL_CreateThread(AsyncIOThreadpoolWorker, threadname, NULL);
         if (thread == NULL) {
             return false;
         }
         SDL_DetachThread(thread);  // these terminate themselves when idle too long, so we never WaitThread.
         running_threadpool_threads++;
         threadpool_threads_spun++;
     }
     return true;
 }

 static void QueueAsyncIOTask(SDL_AsyncIOTask *task)
 {
     SDL_assert(task != NULL);

     SDL_LockMutex(threadpool_lock);

     if (stop_threadpool) {  // just in case.
         task->result = SDL_ASYNCIO_CANCELED;
         AsyncIOTaskComplete(task);
     } else {
         LINKED_LIST_PREPEND(task, threadpool_tasks, threadpool);
         MaybeSpinNewWorkerThread();  // okay if this fails or the thread pool is maxed out. Something will get there eventually.

         // tell idle threads to get to work.
         // This is a broadcast because we want someone from the thread pool to wake up, but
         // also shutdown might also be blocking on this. One of the threads will grab
         // it, the others will go back to sleep.
         SDL_BroadcastCondition(threadpool_condition);
     }

     SDL_UnlockMutex(threadpool_lock);
 }

 // We don't initialize async i/o at all until it's used, so
 //  JUST IN CASE two things try to start at the same time,
 //  this will make sure everything gets the same mutex.
 static bool PrepareThreadpool(void)
 {
     bool okay = true;
     if (SDL_ShouldInit(&threadpool_init)) {
         max_threadpool_threads = (SDL_GetNumLogicalCPUCores() * 2) + 1;  // !!! FIXME: this should probably have a hint to override.
         max_threadpool_threads = SDL_clamp(max_threadpool_threads, 1, 8);  // 8 is probably more than enough.

         okay = (okay && ((threadpool_lock = SDL_CreateMutex()) != NULL));
         okay = (okay && ((threadpool_condition = SDL_CreateCondition()) != NULL));
         okay = (okay && MaybeSpinNewWorkerThread());  // make sure at least one thread is going, since we'll need it.

         if (!okay) {
             if (threadpool_condition) {
                 SDL_DestroyCondition(threadpool_condition);
                 threadpool_condition = NULL;
             }
             if (threadpool_lock) {
                 SDL_DestroyMutex(threadpool_lock);
                 threadpool_lock = NULL;
             }
         }

         SDL_SetInitialized(&threadpool_init, okay);
     }
     return okay;
 }

 static void ShutdownThreadpool(void)
 {
     if (SDL_ShouldQuit(&threadpool_init)) {
         SDL_LockMutex(threadpool_lock);

         // cancel anything that's still pending.
         SDL_AsyncIOTask *task;
         while ((task = LINKED_LIST_START(threadpool_tasks, threadpool)) != NULL) {
             LINKED_LIST_UNLINK(task, threadpool);
             task->result = SDL_ASYNCIO_CANCELED;
             AsyncIOTaskComplete(task);
         }

         stop_threadpool = true;
         SDL_BroadcastCondition(threadpool_condition);  // tell the whole threadpool to wake up and quit.

         while (running_threadpool_threads > 0) {
             // each threadpool thread will broadcast this condition before it terminates if stop_threadpool is set.
             // we can't just join the threads because they are detached, so the thread pool can automatically shrink as necessary.
             SDL_WaitCondition(threadpool_condition, threadpool_lock);
         }

         SDL_UnlockMutex(threadpool_lock);

         SDL_DestroyMutex(threadpool_lock);
         threadpool_lock = NULL;
         SDL_DestroyCondition(threadpool_condition);
         threadpool_condition = NULL;

         max_threadpool_threads = running_threadpool_threads = idle_threadpool_threads = threadpool_threads_spun = 0;

         stop_threadpool = false;
         SDL_SetInitialized(&threadpool_init, false);
     }
 }
 #endif


 static Sint64 generic_asyncio_size(void *userdata)
 {
     GenericAsyncIOData *data = (GenericAsyncIOData *) userdata;
     return SDL_GetIOSize(data->io);
 }

 static bool generic_asyncio_io(void *userdata, SDL_AsyncIOTask *task)
 {
     return task->queue->iface.queue_task(task->queue->userdata, task);
 }

 static void generic_asyncio_destroy(void *userdata)
 {
     GenericAsyncIOData *data = (GenericAsyncIOData *) userdata;
     SDL_DestroyMutex(data->lock);
     SDL_free(data);
 }


 static bool generic_asyncioqueue_queue_task(void *userdata, SDL_AsyncIOTask *task)
 {
     #if SDL_ASYNCIO_USE_THREADPOOL
     QueueAsyncIOTask(task);
     #else
     SynchronousIO(task);  // oh well. Get a better platform.
     #endif
     return true;
 }

 static void generic_asyncioqueue_cancel_task(void *userdata, SDL_AsyncIOTask *task)
 {
     #if !SDL_ASYNCIO_USE_THREADPOOL  // in theory, this was all synchronous and should never call this, but just in case.
     task->result = SDL_ASYNCIO_CANCELED;
     AsyncIOTaskComplete(task);
     #else
     // we can't stop i/o that's in-flight, but we _can_ just refuse to start it if the threadpool hadn't picked it up yet.
     SDL_LockMutex(threadpool_lock);
     if (LINKED_LIST_PREV(task, threadpool) != NULL) {  // still in the queue waiting to be run? Take it out.
         LINKED_LIST_UNLINK(task, threadpool);
         task->result = SDL_ASYNCIO_CANCELED;
         AsyncIOTaskComplete(task);
     }
     SDL_UnlockMutex(threadpool_lock);
     #endif
 }

 static SDL_AsyncIOTask *generic_asyncioqueue_get_results(void *userdata)
 {
     GenericAsyncIOQueueData *data = (GenericAsyncIOQueueData *) userdata;
     SDL_LockMutex(data->lock);
     SDL_AsyncIOTask *task = LINKED_LIST_START(data->completed_tasks, queue);
     if (task) {
         LINKED_LIST_UNLINK(task, queue);
     }
     SDL_UnlockMutex(data->lock);
     return task;
 }

 static SDL_AsyncIOTask *generic_asyncioqueue_wait_results(void *userdata, Sint32 timeoutMS)
 {
     GenericAsyncIOQueueData *data = (GenericAsyncIOQueueData *) userdata;
     SDL_LockMutex(data->lock);
     SDL_AsyncIOTask *task = LINKED_LIST_START(data->completed_tasks, queue);
     if (!task) {
         SDL_WaitConditionTimeout(data->condition, data->lock, timeoutMS);
         task = LINKED_LIST_START(data->completed_tasks, queue);
     }
     if (task) {
         LINKED_LIST_UNLINK(task, queue);
     }
     SDL_UnlockMutex(data->lock);
     return task;
 }

 static void generic_asyncioqueue_signal(void *userdata)
 {
     GenericAsyncIOQueueData *data = (GenericAsyncIOQueueData *) userdata;
     SDL_LockMutex(data->lock);
     SDL_BroadcastCondition(data->condition);
     SDL_UnlockMutex(data->lock);
 }

 static void generic_asyncioqueue_destroy(void *userdata)
 {
     GenericAsyncIOQueueData *data = (GenericAsyncIOQueueData *) userdata;
     SDL_DestroyMutex(data->lock);
     SDL_DestroyCondition(data->condition);
     SDL_free(data);
 }

 bool SDL_SYS_CreateAsyncIOQueue_Generic(SDL_AsyncIOQueue *queue)
 {
     #if SDL_ASYNCIO_USE_THREADPOOL
     if (!PrepareThreadpool()) {
         return false;
     }
     #endif

     GenericAsyncIOQueueData *data = (GenericAsyncIOQueueData *) SDL_calloc(1, sizeof (*data));
     if (!data) {
         return false;
     }

     data->lock = SDL_CreateMutex();
     if (!data->lock) {
         SDL_free(data);
         return false;
     }

     data->condition = SDL_CreateCondition();
     if (!data->condition) {
         SDL_DestroyMutex(data->lock);
         SDL_free(data);
         return false;
     }

     static const SDL_AsyncIOQueueInterface SDL_AsyncIOQueue_Generic = {
         generic_asyncioqueue_queue_task,
         generic_asyncioqueue_cancel_task,
         generic_asyncioqueue_get_results,
         generic_asyncioqueue_wait_results,
         generic_asyncioqueue_signal,
         generic_asyncioqueue_destroy
     };

     SDL_copyp(&queue->iface, &SDL_AsyncIOQueue_Generic);
     queue->userdata = data;
     return true;
 }


 bool SDL_SYS_AsyncIOFromFile_Generic(const char *file, const char *mode, SDL_AsyncIO *asyncio)
 {
     #if SDL_ASYNCIO_USE_THREADPOOL
     if (!PrepareThreadpool()) {
         return false;
     }
     #endif

     GenericAsyncIOData *data = (GenericAsyncIOData *) SDL_calloc(1, sizeof (*data));
     if (!data) {
         return false;
     }

     data->lock = SDL_CreateMutex();
     if (!data->lock) {
         SDL_free(data);
         return false;
     }

     data->io = SDL_IOFromFile(file, mode);
     if (!data->io) {
         SDL_DestroyMutex(data->lock);
         SDL_free(data);
         return false;
     }

     static const SDL_AsyncIOInterface SDL_AsyncIOFile_Generic = {
         generic_asyncio_size,
         generic_asyncio_io,
         generic_asyncio_io,
         generic_asyncio_io,
         generic_asyncio_destroy
     };

     SDL_copyp(&asyncio->iface, &SDL_AsyncIOFile_Generic);
     asyncio->userdata = data;
     return true;
 }

 void SDL_SYS_QuitAsyncIO_Generic(void)
 {
     #if SDL_ASYNCIO_USE_THREADPOOL
     ShutdownThreadpool();
     #endif
 }


 #if SDL_ASYNCIO_ONLY_HAVE_GENERIC
 bool SDL_SYS_AsyncIOFromFile(const char *file, const char *mode, SDL_AsyncIO *asyncio)
 {
     return SDL_SYS_AsyncIOFromFile_Generic(file, mode, asyncio);
 }

 bool SDL_SYS_CreateAsyncIOQueue(SDL_AsyncIOQueue *queue)
 {
     return SDL_SYS_CreateAsyncIOQueue_Generic(queue);
 }

 void SDL_SYS_QuitAsyncIO(void)
 {
     SDL_SYS_QuitAsyncIO_Generic();
 }
 #endif
	/*
	Simple DirectMedia Layer
	Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>

	This software is provided 'as-is', without any express or implied
	warranty. In no event will the authors be held liable for any damages
	arising from the use of this software.

	Permission is granted to anyone to use this software for any purpose,
	including commercial applications, and to alter it and redistribute it
	freely, subject to the following restrictions:

	1. The origin of this software must not be misrepresented; you must not
	claim that you wrote the original software. If you use this software
	in a product, an acknowledgment in the product documentation would be
	appreciated but is not required.
	2. Altered source versions must be plainly marked as such, and must not be
	misrepresented as being the original software.
	3. This notice may not be removed or altered from any source distribution.
	*/

	// The generic backend uses a threadpool to block on synchronous i/o.
	// This is not ideal, it's meant to be used if there isn't a platform-specific
	// backend that can do something more efficient!

	#include "SDL_internal.h"
	#include "../SDL_sysasyncio.h"

	// on Emscripten without threads, async i/o is synchronous. Sorry. Almost
	// everything is MEMFS, so it's just a memcpy anyhow, and the Emscripten
	// filesystem APIs don't offer async. In theory, directly accessing
	// persistent storage _does_ offer async APIs at the browser level, but
	// that's not exposed in Emscripten's filesystem abstraction.
	#if defined(SDL_PLATFORM_EMSCRIPTEN) && !defined(__EMSCRIPTEN_PTHREADS__)
	#define SDL_ASYNCIO_USE_THREADPOOL 0
	#else
	#define SDL_ASYNCIO_USE_THREADPOOL 1
	#endif

	typedef struct GenericAsyncIOQueueData
	{
	SDL_Mutex *lock;
	SDL_Condition *condition;
	SDL_AsyncIOTask completed_tasks;
	} GenericAsyncIOQueueData;

	typedef struct GenericAsyncIOData
	{
	SDL_Mutex *lock; // !!! FIXME: we can skip this lock if we have an equivalent of pread/pwrite
	SDL_IOStream *io;
	} GenericAsyncIOData;

	static void AsyncIOTaskComplete(SDL_AsyncIOTask *task)
	{
	SDL_assert(task->queue);
	GenericAsyncIOQueueData data = (GenericAsyncIOQueueData ) task->queue->userdata;
	SDL_LockMutex(data->lock);
	LINKED_LIST_PREPEND(task, data->completed_tasks, queue);
	SDL_SignalCondition(data->condition); // wake a thread waiting on the queue.
	SDL_UnlockMutex(data->lock);
	}

	// synchronous i/o is offloaded onto the threadpool. This function does the threaded work.
	// This is called directly, without a threadpool, if !SDL_ASYNCIO_USE_THREADPOOL.
	static void SynchronousIO(SDL_AsyncIOTask *task)
	{
	SDL_assert(task->result != SDL_ASYNCIO_CANCELED); // shouldn't have gotten in here if canceled!

	GenericAsyncIOData data = (GenericAsyncIOData ) task->asyncio->userdata;
	SDL_IOStream *io = data->io;
	const size_t size = (size_t) task->requested_size;
	void *ptr = task->buffer;

	// this seek won't work if two tasks are reading from the same file at the same time,
	// so we lock here. This makes multiple reads from a single file serialize, but different
	// files will still run in parallel. An app can also open the same file twice to avoid this.
	SDL_LockMutex(data->lock);
	if (task->type == SDL_ASYNCIO_TASK_CLOSE) {
	bool okay = true;
	if (task->flush) {
	okay = SDL_FlushIO(data->io);
	}
	okay = SDL_CloseIO(data->io) && okay;
	task->result = okay ? SDL_ASYNCIO_COMPLETE : SDL_ASYNCIO_FAILURE;
	} else if (SDL_SeekIO(io, (Sint64) task->offset, SDL_IO_SEEK_SET) < 0) {
	task->result = SDL_ASYNCIO_FAILURE;
	} else {
	const bool writing = (task->type == SDL_ASYNCIO_TASK_WRITE);
	task->result_size = (Uint64) (writing ? SDL_WriteIO(io, ptr, size) : SDL_ReadIO(io, ptr, size));
	if (task->result_size == task->requested_size) {
	task->result = SDL_ASYNCIO_COMPLETE;
	} else {
	if (writing) {
	task->result = SDL_ASYNCIO_FAILURE; // it's always a failure on short writes.
	} else {
	const SDL_IOStatus status = SDL_GetIOStatus(io);
	SDL_assert(status != SDL_IO_STATUS_READY); // this should have either failed or been EOF.
	SDL_assert(status != SDL_IO_STATUS_NOT_READY); // these should not be non-blocking reads!
	task->result = (status == SDL_IO_STATUS_EOF) ? SDL_ASYNCIO_COMPLETE : SDL_ASYNCIO_FAILURE;
	}
	}
	}
	SDL_UnlockMutex(data->lock);

	AsyncIOTaskComplete(task);
	}

	#if SDL_ASYNCIO_USE_THREADPOOL
	static SDL_InitState threadpool_init;
	static SDL_Mutex *threadpool_lock = NULL;
	static bool stop_threadpool = false;
	static SDL_AsyncIOTask threadpool_tasks;
	static SDL_Condition *threadpool_condition = NULL;
	static int max_threadpool_threads = 0;
	static int running_threadpool_threads = 0;
	static int idle_threadpool_threads = 0;
	static int threadpool_threads_spun = 0;

	static int SDLCALL AsyncIOThreadpoolWorker(void *data)
	{
	SDL_LockMutex(threadpool_lock);

	while (!stop_threadpool) {
	SDL_AsyncIOTask *task = LINKED_LIST_START(threadpool_tasks, threadpool);
	if (!task) {
	// if we go 30 seconds without a new task, terminate unless we're the only thread left.
	idle_threadpool_threads++;
	const bool rc = SDL_WaitConditionTimeout(threadpool_condition, threadpool_lock, 30000);
	idle_threadpool_threads--;

	if (!rc) {
	// decide if we have too many idle threads, and if so, quit to let thread pool shrink when not busy.
	if (idle_threadpool_threads) {
	break;
	}
	}

	continue;
	}

	LINKED_LIST_UNLINK(task, threadpool);

	SDL_UnlockMutex(threadpool_lock);

	// bookkeeping is done, so we drop the mutex and fire the work.
	SynchronousIO(task);

	SDL_LockMutex(threadpool_lock); // take the lock again and see if there's another task (if not, we'll wait on the Condition).
	}

	running_threadpool_threads--;

	// this is kind of a hack, but this lets us reuse threadpool_condition to block on shutdown until all threads have exited.
	if (stop_threadpool) {
	SDL_BroadcastCondition(threadpool_condition);
	}

	SDL_UnlockMutex(threadpool_lock);

	return 0;
	}

	static bool MaybeSpinNewWorkerThread(void)
	{
	// if all existing threads are busy and the pool of threads isn't maxed out, make a new one.
	if ((idle_threadpool_threads == 0) && (running_threadpool_threads < max_threadpool_threads)) {
	char threadname[32];
	SDL_snprintf(threadname, sizeof (threadname), "SDLasyncio%d", threadpool_threads_spun);
	SDL_Thread *thread = SDL_CreateThread(AsyncIOThreadpoolWorker, threadname, NULL);
	if (thread == NULL) {
	return false;
	}
	SDL_DetachThread(thread); // these terminate themselves when idle too long, so we never WaitThread.
	running_threadpool_threads++;
	threadpool_threads_spun++;
	}
	return true;
	}

	static void QueueAsyncIOTask(SDL_AsyncIOTask *task)
	{
	SDL_assert(task != NULL);

	SDL_LockMutex(threadpool_lock);

	if (stop_threadpool) { // just in case.
	task->result = SDL_ASYNCIO_CANCELED;
	AsyncIOTaskComplete(task);
	} else {
	LINKED_LIST_PREPEND(task, threadpool_tasks, threadpool);
	MaybeSpinNewWorkerThread(); // okay if this fails or the thread pool is maxed out. Something will get there eventually.

	// tell idle threads to get to work.
	// This is a broadcast because we want someone from the thread pool to wake up, but
	// also shutdown might also be blocking on this. One of the threads will grab
	// it, the others will go back to sleep.
	SDL_BroadcastCondition(threadpool_condition);
	}

	SDL_UnlockMutex(threadpool_lock);
	}

	// We don't initialize async i/o at all until it's used, so
	// JUST IN CASE two things try to start at the same time,
	// this will make sure everything gets the same mutex.
	static bool PrepareThreadpool(void)
	{
	bool okay = true;
	if (SDL_ShouldInit(&threadpool_init)) {
	max_threadpool_threads = (SDL_GetNumLogicalCPUCores() * 2) + 1; // !!! FIXME: this should probably have a hint to override.
	max_threadpool_threads = SDL_clamp(max_threadpool_threads, 1, 8); // 8 is probably more than enough.

	okay = (okay && ((threadpool_lock = SDL_CreateMutex()) != NULL));
	okay = (okay && ((threadpool_condition = SDL_CreateCondition()) != NULL));
	okay = (okay && MaybeSpinNewWorkerThread()); // make sure at least one thread is going, since we'll need it.

	if (!okay) {
	if (threadpool_condition) {
	SDL_DestroyCondition(threadpool_condition);
	threadpool_condition = NULL;
	}
	if (threadpool_lock) {
	SDL_DestroyMutex(threadpool_lock);
	threadpool_lock = NULL;
	}
	}

	SDL_SetInitialized(&threadpool_init, okay);
	}
	return okay;
	}

	static void ShutdownThreadpool(void)
	{
	if (SDL_ShouldQuit(&threadpool_init)) {
	SDL_LockMutex(threadpool_lock);

	// cancel anything that's still pending.
	SDL_AsyncIOTask *task;
	while ((task = LINKED_LIST_START(threadpool_tasks, threadpool)) != NULL) {
	LINKED_LIST_UNLINK(task, threadpool);
	task->result = SDL_ASYNCIO_CANCELED;
	AsyncIOTaskComplete(task);
	}

	stop_threadpool = true;
	SDL_BroadcastCondition(threadpool_condition); // tell the whole threadpool to wake up and quit.

	while (running_threadpool_threads > 0) {
	// each threadpool thread will broadcast this condition before it terminates if stop_threadpool is set.
	// we can't just join the threads because they are detached, so the thread pool can automatically shrink as necessary.
	SDL_WaitCondition(threadpool_condition, threadpool_lock);
	}

	SDL_UnlockMutex(threadpool_lock);

	SDL_DestroyMutex(threadpool_lock);
	threadpool_lock = NULL;
	SDL_DestroyCondition(threadpool_condition);
	threadpool_condition = NULL;

	max_threadpool_threads = running_threadpool_threads = idle_threadpool_threads = threadpool_threads_spun = 0;

	stop_threadpool = false;
	SDL_SetInitialized(&threadpool_init, false);
	}
	}
	#endif


	static Sint64 generic_asyncio_size(void *userdata)
	{
	GenericAsyncIOData data = (GenericAsyncIOData ) userdata;
	return SDL_GetIOSize(data->io);
	}

	static bool generic_asyncio_io(void userdata, SDL_AsyncIOTask task)
	{
	return task->queue->iface.queue_task(task->queue->userdata, task);
	}

	static void generic_asyncio_destroy(void *userdata)
	{
	GenericAsyncIOData data = (GenericAsyncIOData ) userdata;
	SDL_DestroyMutex(data->lock);
	SDL_free(data);
	}


	static bool generic_asyncioqueue_queue_task(void userdata, SDL_AsyncIOTask task)
	{
	#if SDL_ASYNCIO_USE_THREADPOOL
	QueueAsyncIOTask(task);
	#else
	SynchronousIO(task); // oh well. Get a better platform.
	#endif
	return true;
	}

	static void generic_asyncioqueue_cancel_task(void userdata, SDL_AsyncIOTask task)
	{
	#if !SDL_ASYNCIO_USE_THREADPOOL // in theory, this was all synchronous and should never call this, but just in case.
	task->result = SDL_ASYNCIO_CANCELED;
	AsyncIOTaskComplete(task);
	#else
	// we can't stop i/o that's in-flight, but we _can_ just refuse to start it if the threadpool hadn't picked it up yet.
	SDL_LockMutex(threadpool_lock);
	if (LINKED_LIST_PREV(task, threadpool) != NULL) { // still in the queue waiting to be run? Take it out.
	LINKED_LIST_UNLINK(task, threadpool);
	task->result = SDL_ASYNCIO_CANCELED;
	AsyncIOTaskComplete(task);
	}
	SDL_UnlockMutex(threadpool_lock);
	#endif
	}

	static SDL_AsyncIOTask generic_asyncioqueue_get_results(void userdata)
	{
	GenericAsyncIOQueueData data = (GenericAsyncIOQueueData ) userdata;
	SDL_LockMutex(data->lock);
	SDL_AsyncIOTask *task = LINKED_LIST_START(data->completed_tasks, queue);
	if (task) {
	LINKED_LIST_UNLINK(task, queue);
	}
	SDL_UnlockMutex(data->lock);
	return task;
	}

	static SDL_AsyncIOTask generic_asyncioqueue_wait_results(void userdata, Sint32 timeoutMS)
	{
	GenericAsyncIOQueueData data = (GenericAsyncIOQueueData ) userdata;
	SDL_LockMutex(data->lock);
	SDL_AsyncIOTask *task = LINKED_LIST_START(data->completed_tasks, queue);
	if (!task) {
	SDL_WaitConditionTimeout(data->condition, data->lock, timeoutMS);
	task = LINKED_LIST_START(data->completed_tasks, queue);
	}
	if (task) {
	LINKED_LIST_UNLINK(task, queue);
	}
	SDL_UnlockMutex(data->lock);
	return task;
	}

	static void generic_asyncioqueue_signal(void *userdata)
	{
	GenericAsyncIOQueueData data = (GenericAsyncIOQueueData ) userdata;
	SDL_LockMutex(data->lock);
	SDL_BroadcastCondition(data->condition);
	SDL_UnlockMutex(data->lock);
	}

	static void generic_asyncioqueue_destroy(void *userdata)
	{
	GenericAsyncIOQueueData data = (GenericAsyncIOQueueData ) userdata;
	SDL_DestroyMutex(data->lock);
	SDL_DestroyCondition(data->condition);
	SDL_free(data);
	}

	bool SDL_SYS_CreateAsyncIOQueue_Generic(SDL_AsyncIOQueue *queue)
	{
	#if SDL_ASYNCIO_USE_THREADPOOL
	if (!PrepareThreadpool()) {
	return false;
	}
	#endif

	GenericAsyncIOQueueData data = (GenericAsyncIOQueueData ) SDL_calloc(1, sizeof (*data));
	if (!data) {
	return false;
	}

	data->lock = SDL_CreateMutex();
	if (!data->lock) {
	SDL_free(data);
	return false;
	}

	data->condition = SDL_CreateCondition();
	if (!data->condition) {
	SDL_DestroyMutex(data->lock);
	SDL_free(data);
	return false;
	}

	static const SDL_AsyncIOQueueInterface SDL_AsyncIOQueue_Generic = {
	generic_asyncioqueue_queue_task,
	generic_asyncioqueue_cancel_task,
	generic_asyncioqueue_get_results,
	generic_asyncioqueue_wait_results,
	generic_asyncioqueue_signal,
	generic_asyncioqueue_destroy
	};

	SDL_copyp(&queue->iface, &SDL_AsyncIOQueue_Generic);
	queue->userdata = data;
	return true;
	}


	bool SDL_SYS_AsyncIOFromFile_Generic(const char file, const char mode, SDL_AsyncIO *asyncio)
	{
	#if SDL_ASYNCIO_USE_THREADPOOL
	if (!PrepareThreadpool()) {
	return false;
	}
	#endif

	GenericAsyncIOData data = (GenericAsyncIOData ) SDL_calloc(1, sizeof (*data));
	if (!data) {
	return false;
	}

	data->lock = SDL_CreateMutex();
	if (!data->lock) {
	SDL_free(data);
	return false;
	}

	data->io = SDL_IOFromFile(file, mode);
	if (!data->io) {
	SDL_DestroyMutex(data->lock);
	SDL_free(data);
	return false;
	}

	static const SDL_AsyncIOInterface SDL_AsyncIOFile_Generic = {
	generic_asyncio_size,
	generic_asyncio_io,
	generic_asyncio_io,
	generic_asyncio_io,
	generic_asyncio_destroy
	};

	SDL_copyp(&asyncio->iface, &SDL_AsyncIOFile_Generic);
	asyncio->userdata = data;
	return true;
	}

	void SDL_SYS_QuitAsyncIO_Generic(void)
	{
	#if SDL_ASYNCIO_USE_THREADPOOL
	ShutdownThreadpool();
	#endif
	}


	#if SDL_ASYNCIO_ONLY_HAVE_GENERIC
	bool SDL_SYS_AsyncIOFromFile(const char file, const char mode, SDL_AsyncIO *asyncio)
	{
	return SDL_SYS_AsyncIOFromFile_Generic(file, mode, asyncio);
	}

	bool SDL_SYS_CreateAsyncIOQueue(SDL_AsyncIOQueue *queue)
	{
	return SDL_SYS_CreateAsyncIOQueue_Generic(queue);
	}

	void SDL_SYS_QuitAsyncIO(void)
	{
	SDL_SYS_QuitAsyncIO_Generic();
	}
	#endif