`SDL_IsMainThread()` behaves inconsistently/incorrectly on some platforms

[castholm]

Extracted from #12676, #14502 (comment)

#include <SDL3/SDL.h>
#include <SDL3/SDL_main.h>

int threadFunction(void * _) {
    SDL_Log("thread: CurrentThreadID: %" SDL_PRIu64, SDL_GetCurrentThreadID());
    SDL_Log("thread: IsMainThread: %d", SDL_IsMainThread());
    return 0;
}

int main(int argc, char *argv[]) {
    SDL_Thread *thread;
    if (!SDL_Init(0)) return -1;
    SDL_Log("main:   CurrentThreadID: %" SDL_PRIu64, SDL_GetCurrentThreadID());
    SDL_Log("main:   IsMainThread: %d", SDL_IsMainThread());
    thread = SDL_CreateThread(threadFunction, "thread", NULL);
    if (!thread) return -1;
    SDL_WaitThread(thread, NULL);
    return 0;
}

Compile the above program for Linux and run it.

main:   CurrentThreadID: 132321951314944
main:   IsMainThread: 1
thread: CurrentThreadID: 132321944307264
thread: IsMainThread: 1

Both threads report that they are the main thread.

Now compile the same program for Windows and run it.

main:   CurrentThreadID: 4036
main:   IsMainThread: 1
thread: CurrentThreadID: 5000
thread: IsMainThread: 0

Only one thread reports that it is the main thread.

Now update the program to call SDL_SetMainReady() before SDL_Init(), recompile for Linux and rerun it.

main:   CurrentThreadID: 126684362445824
main:   IsMainThread: 1
thread: CurrentThreadID: 126684355356224
thread: IsMainThread: 0

Only one thread reports that it is the main thread.

SDL currently flags a thread as the main thread at two points:

• When SDL_SetMainReady() is called, if no thread has yet been flagged has the main thread.
• When the video subsystem is initialized, regardless of any prior calls to SDL_SetMainReady().

The root cause of the inconsistency seems to be that not all platforms call SDL_SetMainReady() (e.g. the generic SDL_RunApp() implementation used on Linux).

The docs for SDL_IsMainThread() define the main thread as follows:

On Apple platforms, the main thread is the thread that runs your program's main() entry point. On other platforms, the main thread is the one that calls SDL_Init(SDL_INIT_VIDEO), which should usually be the one that runs your program's main() entry point. If you are using the main callbacks, SDL_AppInit(), SDL_AppIterate(), and SDL_AppQuit() are all called on the main thread.

Clearly something is wrong. Either the implementation should be updated such that all threads are considered the main thread until the video subsystem is initialized on all (non-Apple) platforms, which is currently not the case for e.g. Windows, or the docs should be updated to reflect the actual behavior.

However, I would argue that a more useful definition/behavior would be something like this:

1. If the platform has a native concept of a "main thread" (e.g. Apple platforms), that thread is always the main thread.
2. Otherwise, if the video system has been initialized, the thread that initialized it is the main thread.
   • This lets people do SDL_Init(0) -> SDL_CreateThread() -> SDL_Init(SDL_INIT_VIDEO).
3. Otherwise, the thread that initialized SDL by calling SDL_Init() (with any arguments) is the main thread.
   • For safety/maximum backward compatibility, SDL_SetMainReady() could still preemptively flag the calling thread as the main thread until SDL_Init() is called.
4. Otherwise, all threads will be considered the main thread (SDL can't know about threads created outside of SDL).

Documentation should be updated to reflect this accurately. (As an aside, the docs should also clarify whether SDL_CreateThread() is allowed to be called before SDL_Init(0) (which initialized the "threading subsystem" according to the docs). Currently it's a bit unclear.)

The bug can be considered fixed when SDL_IsMainThread() in the above program returns the same value on all platforms, and related docs have been updated.

[slouken]

Functionally, the thread that initializes the video can be considered the main thread, but because there are some (multiple) platforms that have the requirement that it actually be the main thread, I think we want to reflect that requirement in the documentation.

I think the most correct approach would be to flip it and have the Linux implementation call SDL_SetMainReady() and have that be the main thread and require the video initialization happen on that thread, but I don't want to break existing applications that have already set up a video thread as you've described. I don't think steps 3 and 4 are what we want, since an application might initialize joysticks on a thread, and that shouldn't interfere with initializing video on the main thread, and it would be confusing for multiple threads to think they are the main thread.

Given that, let's bump this to 3.6 for further consideration.

[castholm]

I agree, it would be good to communicate that there's a distinction between "the native main thread" and "the SDL main thread" and explain that SDL_IsMainThread() doesn't always paint the full picture. E.g. on multithreaded Emscripten only the main thread can interact with the DOM, but SDL uses MAIN_THREAD_EM_ASM() to make the user not need to care all that much, but that doesn't mean that it's always safe to use the regular non-main thread EM_ASM() in user code just because SDL_IsMainThread() returns true.

[maia-s]

If this isn't getting fixed for now, it'd be nice if the behaviour was documented. I have some code that relies on that if SDL_IsMainThread returns true on a particular thread, it won't ever return true on a different thread for the lifetime of the process. That's my issue and not yours, but I might not be the only one who interpreted it this way.

[maia-s]

Related, SDL_RunOnMainThread doesn't run the passed function on the main thread unless the video system has been inited. The following program prints this on macos (on_main is called from a thread with SDL_RunOnMainThread, and SDL_RunOnMainThread returns true):

[main] thread id: 8287854720, is main thread: true
[thread] thread id: 6104657920, is main thread: true
[on_main] thread id: 6104657920, is main thread: true

It works if you change it to init SDL_INIT_VIDEO instead.

Test program

#include <SDL3/SDL.h>
#include <stdio.h>

static void print_thread_id(const char* name) {
    fprintf(
        stderr,
        "[%s] thread id: %llu, is main thread: %s\n",
        name,
        (unsigned long long)SDL_GetCurrentThreadID(),
        SDL_IsMainThread() ? "true" : "false"
    );
}

static void on_main_fn(void* data) {
    print_thread_id("on_main");
}

static int thread_fn(void* data) {
    print_thread_id("thread");
    if (!SDL_RunOnMainThread(on_main_fn, NULL, true)) {
        fprintf(stderr, "SDL_RunOnMainThread failed: %s\n", SDL_GetError());
    }
    return 0;
}

int main() {
    if (!SDL_Init(SDL_INIT_EVENTS)) {
        fprintf(stderr, "SDL_Init failed: %s\n", SDL_GetError());
        return 1;
    }

    print_thread_id("main");

    SDL_Thread* thread = SDL_CreateThread(thread_fn, "thread", NULL);
    if (!thread) {
        fprintf(stderr, "SDL_CreateThread failed: %s\n", SDL_GetError());
        SDL_Quit();
        return 1;
    }
    SDL_DetachThread(thread);

    Uint32 ticks = SDL_GetTicks();
    while (SDL_GetTicks() - ticks < 1000) {
        SDL_PumpEvents();
    }

    SDL_Quit();
    return 0;
}

[slouken]

I'm moving this back to 3.4.0 for consideration.