(This is a proposal for an API change. No code has been written yet.)
…so, thinking about Unga’s thread debugging problem, I’m wondering if
changing the SDL_CreateThread API is a good idea for SDL 1.3:
SDL_Thread *SDL_CreateThread(
SDL_ThreadFunction fn,
const char *name, // NEW!
void *data,
pfnSDL_CurrentBeginThread pfnBeginThread,
pfnSDL_CurrentEndThread pfnEndThread
);
“name” is the new parameter, takes a string in UTF-8 format, which SDL
will make a copy of before returning. NULL is acceptable if you don’t
care about naming a thread.
The purpose would be to provide a meaningful identifier for each thread.
Many systems offer facilities for setting a thread name, so that, say,
their debuggers can report a human-readable identifier when one crashes.
SDL will provide this name to the system if such a facility exists, and
keep a copy too, so that the name can be queried through the SDL API as
well, with a new SDL_GetThreadName() API…
const char *SDL_GetThreadName(SDL_Thread *thread);
…this function returns a pointer to a UTF-8 string that names the
specified thread, or NULL if it doesn’t have a name. This is internal
memory, not to be free()'d by the caller, and remains valid until the
specified thread is cleaned up by SDL_WaitThread().
There are no requirements for thread naming conventions, so long as the
string is null-terminated UTF-8, but these guidelines are helpful in
choosing a name:
If a system imposes requirements, SDL will try to munge the string for
it (truncate, etc), but the original string contents will be available
from SDL_GetThreadName().
Caveat: We could add an SDL_SetThreadName() function, but there are a
few problems with this approach. One: if your new thread crashes before
the creating thread has a chance to set the name, then you’re out of
luck. However, we can definitely set it before calling the thread’s
entry point if SDL_CreateThread is responsible for it. Two: Mac OS X
offers pthread_setname_np(), which only works on the current thread, so
we’d have to do this at the only place SDL has control of the created
thread. And three: no race conditions about changing names this way,
which is nice.
This would be a 1.3 change; no API change for 1.2.
–ryan.
