SDL Wiki
(This is the documentation for SDL3, which is under heavy development and the API is changing! SDL2 is the current stable version!)


Create a new thread with with the specified properties.

Header File

Defined in <SDL3/SDL_thread.h>


SDL_Thread * SDL_CreateThreadWithProperties(SDL_PropertiesID props);

Function Parameters

SDL_PropertiesID props the properties to use.

Return Value

(SDL_Thread *) 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.


These are the supported properties:

SDL makes an attempt to report SDL_PROP_THREAD_CREATE_NAME_STRING to the system, so that debuggers can display it. Not all platforms support this.

Thread naming is a little complicated: Most systems have very small limits for the string length (Haiku has 32 bytes, Linux currently has 16, Visual C++ 6.0 has nine!), and possibly other arbitrary rules. You'll have to see what happens with your system's debugger. The name should be UTF-8 (but using the naming limits of C identifiers is a better bet). 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().

The size (in bytes) of the new stack can be specified with SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER. Zero means "use the system default" which might be wildly different between platforms. x86 Linux generally defaults to eight megabytes, an embedded device might be a few kilobytes instead. You generally need to specify a stack that is a multiple of the system's page size (in many cases, this is 4 kilobytes, but check your system documentation).

Note that this "function" is actually a macro that calls an internal function with two extra parameters not listed here; they are hidden through preprocessor macros and are needed to support various C runtimes at the point of the function call. Language bindings that aren't using the C headers will need to deal with this.

The actual symbol in SDL is SDL_CreateThreadWithPropertiesRuntime, so there is no symbol clash, but trying to load an SDL shared library and look for "SDL_CreateThreadWithProperties" will fail.

Usually, apps should just call this function the same way on every platform and let the macros hide the details.


This function is available since SDL 3.0.0.

See Also

CategoryAPI, CategoryAPIFunction, CategoryThread

[ edit | delete | history | feedback | raw ]

[ front page | index | search | recent changes | git repo | offline html ]

All wiki content is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
Wiki powered by ghwikipp.