#pragma section-numbers off
#pragma camelcase off


= SDL_CreateThread =
Use this function to create a new thread.

<<TableOfContents()>>

== Syntax ==
{{{#!highlight cpp
SDL_Thread* SDL_CreateThread(SDL_ThreadFunction fn,
                             const char*        name,
                             void*              data)
}}}
== Function Parameters ==
||'''fn''' ||the function to call in the new thread; see [[#Remarks|Remarks]] for details ||
||'''name''' ||the name of the thread; see [[#name|Remarks]] for details ||
||'''data''' ||a pointer that is passed to '''fn''' ||


== Return Value ==
Returns an opaque pointer to the new thread object on success, NULL if the new thread could not be created; call [[SDL_GetError]]() for more information.

== Code Examples ==
{{{#!highlight cpp
#include <stdio.h>
#include "SDL.h"

/* Very simple thread - counts 0 to 9 delaying 50ms between increments */
static int TestThread(void *ptr)
{
    int cnt;

    for (cnt = 0; cnt < 10; ++cnt) {
        printf("Thread counter: %d\n", cnt);
        SDL_Delay(50);
    }

    return cnt;
}

int main(int argc, char *argv[])
{
    SDL_Thread *thread;
    int         threadReturnValue;

    printf("Simple SDL_CreateThread test:\n");

    /* Simply create a thread */
    thread = SDL_CreateThread(TestThread, "TestThread", (void *)NULL);

    if (NULL == thread) {
        printf("SDL_CreateThread failed: %s\n", SDL_GetError());
    } else {
        SDL_WaitThread(thread, &threadReturnValue);
        printf("Thread returned value: %d\n", threadReturnValue);
    }

    return 0;
}
}}}
{{{#!highlight cpp
Output:
Simple SDL_CreateThread test:
Thread counter: 0
Thread counter: 1
Thread counter: 2
Thread counter: 3
Thread counter: 4
Thread counter: 5
Thread counter: 6
Thread counter: 7
Thread counter: 8
Thread counter: 9
Thread returned value: 10
}}}

== Remarks ==
[[SDL_CreateThread]]() creates a new thread of execution that shares all of its parent's global memory, signal handlers, file descriptors, etc, and runs the function '''fn''', passing it the void pointer '''data'''.  The thread quits when '''fn''' returns.

The function prototype for '''fn''' is:

{{{#!highlight cpp
int SDL_ThreadFunction(void* data)
}}}
  . where its parameter is:
 ||`data` ||what was passed as '''data''' to [[SDL_CreateThread]]() ||


<<Anchor(name)>>
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:

 . http://stackoverflow.com/questions/149932/naming-conventions-for-threads

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]]().

== Related Functions ==
 . [[SDL_WaitThread]]

----
[[CategoryAPI]], [[CategoryThread]]