plucky (3) SDL_CreateThreadWithProperties.3.gz

NAME

       SDL_CreateThreadWithProperties - Create a new thread with with the specified properties.

HEADER FILE

       Defined in SDL3/SDL_thread.h

SYNOPSIS

       #include "SDL3/SDL.h"

       SDL_Thread * SDL_CreateThreadWithProperties(SDL_PropertiesID props);

DESCRIPTION

       These are the supported properties:

       •  SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER :
         an SDL_ThreadFunction
        value that will be called at
         the start of the new thread's life. Required.

       •  SDL_PROP_THREAD_CREATE_NAME_STRING :
         the name of the new thread, which might be available to debuggers.
         Optional, defaults to NULL.

       •  SDL_PROP_THREAD_CREATE_USERDATA_POINTER :
         an arbitrary app-defined pointer, which is passed to the entry function
         on the new thread, as its only parameter. Optional, defaults to NULL.

       •  SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER :
         the size, in bytes, of the new thread's stack. Optional, defaults to 0
         (system-defined default).

       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:

       https://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 ().

       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.

FUNCTION PARAMETERS

       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.

AVAILABILITY

       This function is available since SDL 3.2.0.

SEE ALSO

       •(3), SDL_CreateThread(3), •(3), SDL_WaitThread(3)