SDL_thread.c File Reference

#include "../SDL_internal.h"
#include "SDL_thread.h"
#include "SDL_thread_c.h"
#include "SDL_systhread.h"
#include "SDL_hints.h"
#include "../SDL_error_c.h"

Include dependency graph for SDL_thread.c:

Go to the source code of this file.

Data Structures
struct	SDL_TLSEntry

Macros
#define	SDL_CreateThread   SDL_CreateThread_REAL
#define	SDL_CreateThreadWithStackSize   SDL_CreateThreadWithStackSize_REAL

Functions
SDL_TLSID	SDL_TLSCreate ()
	Create an identifier that is globally visible to all threads but refers to data that is thread-specific. More...
void *	SDL_TLSGet (SDL_TLSID id)
	Get the value associated with a thread local storage ID for the current thread. More...
int	SDL_TLSSet (SDL_TLSID id, const void *value, void(*destructor)(void *))
	Set the value associated with a thread local storage ID for the current thread. More...
static void	SDL_TLSCleanup ()
SDL_TLSData *	SDL_Generic_GetTLSData (void)
int	SDL_Generic_SetTLSData (SDL_TLSData *storage)
SDL_error *	SDL_GetErrBuf (void)
void	SDL_RunThread (SDL_Thread *thread)
SDL_Thread *	SDL_CreateThreadWithStackSize (int(*fn)(void *), const char *name, const size_t stacksize, void *data)
SDL_Thread *	SDL_CreateThread (int(*fn)(void *), const char *name, void *data)
SDL_Thread *	SDL_CreateThreadInternal (int(*fn)(void *), const char *name, const size_t stacksize, void *data)
SDL_threadID	SDL_GetThreadID (SDL_Thread *thread)
const char *	SDL_GetThreadName (SDL_Thread *thread)
int	SDL_SetThreadPriority (SDL_ThreadPriority priority)
void	SDL_WaitThread (SDL_Thread *thread, int *status)
void	SDL_DetachThread (SDL_Thread *thread)

Variables
static SDL_mutex *	SDL_generic_TLS_mutex
static SDL_TLSEntry *	SDL_generic_TLS

Macro Definition Documentation

SDL_CreateThread

#define SDL_CreateThread   SDL_CreateThread_REAL

Definition at line 297 of file SDL_thread.c.

SDL_CreateThreadWithStackSize

#define SDL_CreateThreadWithStackSize   SDL_CreateThreadWithStackSize_REAL

Definition at line 298 of file SDL_thread.c.

Function Documentation

SDL_CreateThread()

SDL_Thread* SDL_CreateThread	(	int(*)(void *)	fn,
		const char *	name,
		void *	data
	)

Definition at line 364 of file SDL_thread.c.

{
    /* !!! FIXME: in 2.1, just make stackhint part of the usual API. */
    const char *stackhint = SDL_GetHint(SDL_HINT_THREAD_STACK_SIZE);
    size_t stacksize = 0;
 
    /* If the SDL_HINT_THREAD_STACK_SIZE exists, use it */
    if (stackhint != NULL) {
        char *endp = NULL;
        const Sint64 hintval = SDL_strtoll(stackhint, &endp, 10);
        if ((*stackhint != '\0') && (*endp == '\0')) {  /* a valid number? */
            if (hintval > 0) {  /* reject bogus values. */
                stacksize = (size_t) hintval;
            }
        }
    }
 
#ifdef SDL_PASSED_BEGINTHREAD_ENDTHREAD
    return SDL_CreateThreadWithStackSize(fn, name, stacksize, data, pfnBeginThread, pfnEndThread);
#else
    return SDL_CreateThreadWithStackSize(fn, name, stacksize, data);
#endif
}

References NULL, SDL_CreateThreadWithStackSize, SDL_GetHint, SDL_HINT_THREAD_STACK_SIZE, and SDL_strtoll.

SDL_CreateThreadInternal()

SDL_Thread* SDL_CreateThreadInternal	(	int(*)(void *)	fn,
		const char *	name,
		const size_t	stacksize,
		void *	data
	)

Definition at line 391 of file SDL_thread.c.

                                                             {
#ifdef SDL_PASSED_BEGINTHREAD_ENDTHREAD
    return SDL_CreateThreadWithStackSize(fn, name, stacksize, data, NULL, NULL);
#else
    return SDL_CreateThreadWithStackSize(fn, name, stacksize, data);
#endif
}

References NULL, and SDL_CreateThreadWithStackSize.

Referenced by open_audio_device(), and SDL_TimerInit().

SDL_CreateThreadWithStackSize()

SDL_Thread* SDL_CreateThreadWithStackSize	(	int(*)(void *)	fn,
		const char *	name,
		const size_t	stacksize,
		void *	data
	)

Definition at line 309 of file SDL_thread.c.

{
    SDL_Thread *thread;
    int ret;
 
    /* Allocate memory for the thread info structure */
    thread = (SDL_Thread *) SDL_calloc(1, sizeof(*thread));
    if (thread == NULL) {
        SDL_OutOfMemory();
        return NULL;
    }
    thread->status = -1;
    SDL_AtomicSet(&thread->state, SDL_THREAD_STATE_ALIVE);
 
    /* Set up the arguments for the thread */
    if (name != NULL) {
        thread->name = SDL_strdup(name);
        if (thread->name == NULL) {
            SDL_OutOfMemory();
            SDL_free(thread);
            return NULL;
        }
    }
 
    thread->userfunc = fn;
    thread->userdata = data;
    thread->stacksize = stacksize;
 
    /* Create the thread and go! */
#ifdef SDL_PASSED_BEGINTHREAD_ENDTHREAD
    ret = SDL_SYS_CreateThread(thread, pfnBeginThread, pfnEndThread);
#else
    ret = SDL_SYS_CreateThread(thread);
#endif
    if (ret < 0) {
        /* Oops, failed.  Gotta free everything */
        SDL_free(thread->name);
        SDL_free(thread);
        thread = NULL;
    }
 
    /* Everything is running now */
    return thread;
}

References NULL, SDL_AtomicSet, SDL_calloc, SDL_free, SDL_OutOfMemory, SDL_strdup, SDL_SYS_CreateThread(), SDL_THREAD_STATE_ALIVE, and SDL_TLSEntry::thread.

SDL_DetachThread()

void SDL_DetachThread

(

SDL_Thread *

thread

)

A thread may be "detached" to signify that it should not remain until another thread has called SDL_WaitThread() on it. Detaching a thread is useful for long-running threads that nothing needs to synchronize with or further manage. When a detached thread is done, it simply goes away.

There is no way to recover the return code of a detached thread. If you need this, don't detach the thread and instead use SDL_WaitThread().

Once a thread is detached, you should usually assume the SDL_Thread isn't safe to reference again, as it will become invalid immediately upon the detached thread's exit, instead of remaining until someone has called SDL_WaitThread() to finally clean it up. As such, don't detach the same thread more than once.

If a thread has already exited when passed to SDL_DetachThread(), it will stop waiting for a call to SDL_WaitThread() and clean up immediately. It is not safe to detach a thread that might be used with SDL_WaitThread().

You may not call SDL_WaitThread() on a thread that has been detached. Use either that function or this one, but not both, or behavior is undefined.

It is safe to pass NULL to this function; it is a no-op.

Definition at line 445 of file SDL_thread.c.

{
    if (!thread) {
        return;
    }
 
    /* Grab dibs if the state is alive+joinable. */
    if (SDL_AtomicCAS(&thread->state, SDL_THREAD_STATE_ALIVE, SDL_THREAD_STATE_DETACHED)) {
        SDL_SYS_DetachThread(thread);
    } else {
        /* all other states are pretty final, see where we landed. */
        const int thread_state = SDL_AtomicGet(&thread->state);
        if ((thread_state == SDL_THREAD_STATE_DETACHED) || (thread_state == SDL_THREAD_STATE_CLEANED)) {
            return;  /* already detached (you shouldn't call this twice!) */
        } else if (thread_state == SDL_THREAD_STATE_ZOMBIE) {
            SDL_WaitThread(thread, NULL);  /* already done, clean it up. */
        } else {
            SDL_assert(0 && "Unexpected thread state");
        }
    }
}

References NULL, SDL_assert, SDL_AtomicCAS, SDL_AtomicGet, SDL_SYS_DetachThread(), SDL_THREAD_STATE_ALIVE, SDL_THREAD_STATE_CLEANED, SDL_THREAD_STATE_DETACHED, SDL_THREAD_STATE_ZOMBIE, SDL_WaitThread(), and SDL_TLSEntry::thread.

SDL_Generic_GetTLSData()

SDL_TLSData* SDL_Generic_GetTLSData

(

void

)

Definition at line 123 of file SDL_thread.c.

{
    SDL_threadID thread = SDL_ThreadID();
    SDL_TLSEntry *entry;
    SDL_TLSData *storage = NULL;
 
#if !SDL_THREADS_DISABLED
    if (!SDL_generic_TLS_mutex) {
        static SDL_SpinLock tls_lock;
        SDL_AtomicLock(&tls_lock);
        if (!SDL_generic_TLS_mutex) {
            SDL_mutex *mutex = SDL_CreateMutex();
            SDL_MemoryBarrierRelease();
            SDL_generic_TLS_mutex = mutex;
            if (!SDL_generic_TLS_mutex) {
                SDL_AtomicUnlock(&tls_lock);
                return NULL;
            }
        }
        SDL_AtomicUnlock(&tls_lock);
    }
#endif /* SDL_THREADS_DISABLED */
 
    SDL_MemoryBarrierAcquire();
    SDL_LockMutex(SDL_generic_TLS_mutex);
    for (entry = SDL_generic_TLS; entry; entry = entry->next) {
        if (entry->thread == thread) {
            storage = entry->storage;
            break;
        }
    }
#if !SDL_THREADS_DISABLED
    SDL_UnlockMutex(SDL_generic_TLS_mutex);
#endif
 
    return storage;
}

References mutex, SDL_TLSEntry::next, NULL, SDL_AtomicLock, SDL_AtomicUnlock, SDL_CreateMutex, SDL_generic_TLS, SDL_generic_TLS_mutex, SDL_LockMutex, SDL_MemoryBarrierAcquire, SDL_MemoryBarrierRelease, SDL_ThreadID, SDL_UnlockMutex, SDL_TLSEntry::storage, and SDL_TLSEntry::thread.

Referenced by SDL_SYS_GetTLSData().

SDL_Generic_SetTLSData()

int SDL_Generic_SetTLSData

(

SDL_TLSData *

storage

)

Definition at line 162 of file SDL_thread.c.

{
    SDL_threadID thread = SDL_ThreadID();
    SDL_TLSEntry *prev, *entry;
 
    /* SDL_Generic_GetTLSData() is always called first, so we can assume SDL_generic_TLS_mutex */
    SDL_LockMutex(SDL_generic_TLS_mutex);
    prev = NULL;
    for (entry = SDL_generic_TLS; entry; entry = entry->next) {
        if (entry->thread == thread) {
            if (storage) {
                entry->storage = storage;
            } else {
                if (prev) {
                    prev->next = entry->next;
                } else {
                    SDL_generic_TLS = entry->next;
                }
                SDL_free(entry);
            }
            break;
        }
        prev = entry;
    }
    if (!entry) {
        entry = (SDL_TLSEntry *)SDL_malloc(sizeof(*entry));
        if (entry) {
            entry->thread = thread;
            entry->storage = storage;
            entry->next = SDL_generic_TLS;
            SDL_generic_TLS = entry;
        }
    }
    SDL_UnlockMutex(SDL_generic_TLS_mutex);
 
    if (!entry) {
        return SDL_OutOfMemory();
    }
    return 0;
}

References SDL_TLSEntry::next, NULL, SDL_free, SDL_generic_TLS, SDL_generic_TLS_mutex, SDL_LockMutex, SDL_malloc, SDL_OutOfMemory, SDL_ThreadID, SDL_UnlockMutex, SDL_TLSEntry::storage, and SDL_TLSEntry::thread.

Referenced by SDL_SYS_SetTLSData().

SDL_GetErrBuf()

SDL_error* SDL_GetErrBuf

(

void

)

Definition at line 205 of file SDL_thread.c.

{
#if SDL_THREADS_DISABLED
    /* Non-thread-safe global error variable */
    static SDL_error SDL_global_error;
    return &SDL_global_error;
#else
    static SDL_SpinLock tls_lock;
    static SDL_bool tls_being_created;
    static SDL_TLSID tls_errbuf;
    static SDL_error SDL_global_errbuf;
    const SDL_error *ALLOCATION_IN_PROGRESS = (SDL_error *)-1;
    SDL_error *errbuf;
 
    /* tls_being_created is there simply to prevent recursion if SDL_TLSCreate() fails.
       It also means it's possible for another thread to also use SDL_global_errbuf,
       but that's very unlikely and hopefully won't cause issues.
     */
    if (!tls_errbuf && !tls_being_created) {
        SDL_AtomicLock(&tls_lock);
        if (!tls_errbuf) {
            SDL_TLSID slot;
            tls_being_created = SDL_TRUE;
            slot = SDL_TLSCreate();
            tls_being_created = SDL_FALSE;
            SDL_MemoryBarrierRelease();
            tls_errbuf = slot;
        }
        SDL_AtomicUnlock(&tls_lock);
    }
    if (!tls_errbuf) {
        return &SDL_global_errbuf;
    }
 
    SDL_MemoryBarrierAcquire();
    errbuf = (SDL_error *)SDL_TLSGet(tls_errbuf);
    if (errbuf == ALLOCATION_IN_PROGRESS) {
        return &SDL_global_errbuf;
    }
    if (!errbuf) {
        /* Mark that we're in the middle of allocating our buffer */
        SDL_TLSSet(tls_errbuf, ALLOCATION_IN_PROGRESS, NULL);
        errbuf = (SDL_error *)SDL_malloc(sizeof(*errbuf));
        if (!errbuf) {
            SDL_TLSSet(tls_errbuf, NULL, NULL);
            return &SDL_global_errbuf;
        }
        SDL_zerop(errbuf);
        SDL_TLSSet(tls_errbuf, errbuf, SDL_free);
    }
    return errbuf;
#endif /* SDL_THREADS_DISABLED */
}

References NULL, SDL_AtomicLock, SDL_AtomicUnlock, SDL_FALSE, SDL_free, SDL_malloc, SDL_MemoryBarrierAcquire, SDL_MemoryBarrierRelease, SDL_TLSCreate(), SDL_TLSGet(), SDL_TLSSet(), SDL_TRUE, and SDL_zerop.

Referenced by SDL_ClearError(), SDL_GetError(), SDL_GetErrorMsg(), and SDL_SetError().

SDL_GetThreadID()

SDL_threadID SDL_GetThreadID

(

SDL_Thread *

thread

)

Get the thread identifier for the specified thread.

Equivalent to SDL_ThreadID() if the specified thread is NULL.

Definition at line 401 of file SDL_thread.c.

{
    SDL_threadID id;
 
    if (thread) {
        id = thread->threadid;
    } else {
        id = SDL_ThreadID();
    }
    return id;
}

References SDL_ThreadID, and SDL_TLSEntry::thread.

SDL_GetThreadName()

const char* SDL_GetThreadName

(

SDL_Thread *

thread

)

Get the thread name, as it was specified in SDL_CreateThread(). 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().

Definition at line 414 of file SDL_thread.c.

{
    if (thread) {
        return thread->name;
    } else {
        return NULL;
    }
}

References NULL, and SDL_TLSEntry::thread.

SDL_RunThread()

void SDL_RunThread

(

SDL_Thread *

thread

)

Definition at line 261 of file SDL_thread.c.

{
    void *userdata = thread->userdata;
    int (SDLCALL * userfunc) (void *) = thread->userfunc;
 
    int *statusloc = &thread->status;
 
    /* Perform any system-dependent setup - this function may not fail */
    SDL_SYS_SetupThread(thread->name);
 
    /* Get the thread id */
    thread->threadid = SDL_ThreadID();
 
    /* Run the function */
    *statusloc = userfunc(userdata);
 
    /* Clean up thread-local storage */
    SDL_TLSCleanup();
 
    /* Mark us as ready to be joined (or detached) */
    if (!SDL_AtomicCAS(&thread->state, SDL_THREAD_STATE_ALIVE, SDL_THREAD_STATE_ZOMBIE)) {
        /* Clean up if something already detached us. */
        if (SDL_AtomicCAS(&thread->state, SDL_THREAD_STATE_DETACHED, SDL_THREAD_STATE_CLEANED)) {
            if (thread->name) {
                SDL_free(thread->name);
            }
            SDL_free(thread);
        }
    }
}

References int(), SDL_AtomicCAS, SDL_free, SDL_SYS_SetupThread(), SDL_THREAD_STATE_ALIVE, SDL_THREAD_STATE_CLEANED, SDL_THREAD_STATE_DETACHED, SDL_THREAD_STATE_ZOMBIE, SDL_ThreadID, SDL_TLSCleanup(), SDLCALL, and SDL_TLSEntry::thread.

Referenced by RunThread().

SDL_SetThreadPriority()

int SDL_SetThreadPriority

(

SDL_ThreadPriority

priority

)

Set the priority for the current thread

Definition at line 424 of file SDL_thread.c.

{
    return SDL_SYS_SetThreadPriority(priority);
}

References SDL_SYS_SetThreadPriority().

SDL_TLSCleanup()

static void SDL_TLSCleanup ( )

static

Definition at line 86 of file SDL_thread.c.

{
    SDL_TLSData *storage;
 
    storage = SDL_SYS_GetTLSData();
    if (storage) {
        unsigned int i;
        for (i = 0; i < storage->limit; ++i) {
            if (storage->array[i].destructor) {
                storage->array[i].destructor(storage->array[i].data);
            }
        }
        SDL_SYS_SetTLSData(NULL);
        SDL_free(storage);
    }
}

References SDL_TLSData::array, SDL_TLSData::data, SDL_TLSData::destructor, i, SDL_TLSData::limit, NULL, SDL_free, SDL_SYS_GetTLSData(), and SDL_SYS_SetTLSData().

Referenced by SDL_RunThread().

SDL_TLSCreate()

SDL_TLSID SDL_TLSCreate

(

void

)

Create an identifier that is globally visible to all threads but refers to data that is thread-specific.

Returns

The newly created thread local storage identifier, or 0 on error

static SDL_SpinLock tls_lock;
static SDL_TLSID thread_local_storage;
 
void SetMyThreadData(void *value)
{
    if (!thread_local_storage) {
        SDL_AtomicLock(&tls_lock);
        if (!thread_local_storage) {
            thread_local_storage = SDL_TLSCreate();
        }
        SDL_AtomicUnlock(&tls_lock);
    }
    SDL_TLSSet(thread_local_storage, value, 0);
}
 
void *GetMyThreadData(void)
{
    return SDL_TLSGet(thread_local_storage);
}

See also

SDL_TLSGet()

SDL_TLSSet()

Definition at line 33 of file SDL_thread.c.

{
    static SDL_atomic_t SDL_tls_id;
    return SDL_AtomicIncRef(&SDL_tls_id)+1;
}

References SDL_AtomicIncRef.

Referenced by SDL_GetErrBuf().

SDL_TLSGet()

void* SDL_TLSGet

(

SDL_TLSID

id

)

Get the value associated with a thread local storage ID for the current thread.

Parameters

id	The thread local storage ID

Returns

The value associated with the ID for the current thread, or NULL if no value has been set.

See also

SDL_TLSCreate()

SDL_TLSSet()

Definition at line 40 of file SDL_thread.c.

{
    SDL_TLSData *storage;
 
    storage = SDL_SYS_GetTLSData();
    if (!storage || id == 0 || id > storage->limit) {
        return NULL;
    }
    return storage->array[id-1].data;
}

References SDL_TLSData::array, SDL_TLSData::data, SDL_TLSData::limit, NULL, and SDL_SYS_GetTLSData().

Referenced by SDL_GetErrBuf().

SDL_TLSSet()

int SDL_TLSSet	(	SDL_TLSID	id,
		const void *	value,
		void(*)(void *)	destructor
	)

Set the value associated with a thread local storage ID for the current thread.

Parameters

id	The thread local storage ID
value	The value to associate with the ID for the current thread
destructor	A function called when the thread exits, to free the value.

Returns

0 on success, -1 on error

See also

SDL_TLSCreate()

SDL_TLSGet()

Definition at line 52 of file SDL_thread.c.

{
    SDL_TLSData *storage;
 
    if (id == 0) {
        return SDL_InvalidParamError("id");
    }
 
    storage = SDL_SYS_GetTLSData();
    if (!storage || (id > storage->limit)) {
        unsigned int i, oldlimit, newlimit;
 
        oldlimit = storage ? storage->limit : 0;
        newlimit = (id + TLS_ALLOC_CHUNKSIZE);
        storage = (SDL_TLSData *)SDL_realloc(storage, sizeof(*storage)+(newlimit-1)*sizeof(storage->array[0]));
        if (!storage) {
            return SDL_OutOfMemory();
        }
        storage->limit = newlimit;
        for (i = oldlimit; i < newlimit; ++i) {
            storage->array[i].data = NULL;
            storage->array[i].destructor = NULL;
        }
        if (SDL_SYS_SetTLSData(storage) != 0) {
            return -1;
        }
    }
 
    storage->array[id-1].data = SDL_const_cast(void*, value);
    storage->array[id-1].destructor = destructor;
    return 0;
}

References SDL_TLSData::array, SDL_TLSData::data, SDL_TLSData::destructor, i, SDL_TLSData::limit, NULL, SDL_const_cast, SDL_InvalidParamError, SDL_OutOfMemory, SDL_realloc, SDL_SYS_GetTLSData(), SDL_SYS_SetTLSData(), and TLS_ALLOC_CHUNKSIZE.

Referenced by SDL_GetErrBuf().

SDL_WaitThread()

void SDL_WaitThread	(	SDL_Thread *	thread,
		int *	status
	)

Wait for a thread to finish. Threads that haven't been detached will remain (as a "zombie") until this function cleans them up. Not doing so is a resource leak.

Once a thread has been cleaned up through this function, the SDL_Thread that references it becomes invalid and should not be referenced again. As such, only one thread may call SDL_WaitThread() on another.

The return code for the thread function is placed in the area pointed to by status, if status is not NULL.

You may not wait on a thread that has been used in a call to SDL_DetachThread(). Use either that function or this one, but not both, or behavior is undefined.

It is safe to pass NULL to this function; it is a no-op.

Definition at line 430 of file SDL_thread.c.

{
    if (thread) {
        SDL_SYS_WaitThread(thread);
        if (status) {
            *status = thread->status;
        }
        if (thread->name) {
            SDL_free(thread->name);
        }
        SDL_free(thread);
    }
}

References SDL_free, SDL_SYS_WaitThread(), and SDL_TLSEntry::thread.

Referenced by SDL_DetachThread().

Variable Documentation

SDL_generic_TLS

SDL_TLSEntry* SDL_generic_TLS

static

Definition at line 119 of file SDL_thread.c.

Referenced by SDL_Generic_GetTLSData(), and SDL_Generic_SetTLSData().

SDL_generic_TLS_mutex

SDL_mutex* SDL_generic_TLS_mutex

static

Definition at line 118 of file SDL_thread.c.

Referenced by SDL_Generic_GetTLSData(), and SDL_Generic_SetTLSData().