Wiki Page Content

Differences between revisions 12 and 23 (spanning 11 versions)
Revision 12 as of 2013-10-05 20:43:25
Size: 2147
Comment: Removed and added spaces in example.
Revision 23 as of 2018-12-12 14:53:52
Size: 2724
Editor: RyanGordon
Comment: Restoring page
Deletions are marked like this. Additions are marked like this.
Line 16: Line 16:
||'''status''' ||pointer to an integer that will receive the value returned from the thread function by its 'return', see [[#Remarks|Remarks]] for details || ||'''status''' ||pointer to an integer that will receive the value returned from the thread function by its 'return', or '''NULL''' to not receive such value back. see [[#Remarks|Remarks]] for details ||
Line 20: Line 20:
#include <stdio.h>
#include "SDL_thread.h"
#include "SDL_timer.h"
Line 21: Line 24:
#include <stdio.h>
#include <SDL_thread.h>
#include <SDL_timer.h>
// Very simple thread - counts 0 to 9 delaying 50ms between increments
static int TestThread(void *ptr)
{
    int cnt;
Line 25: Line 29:
int TestThread(void *ptr);     for (cnt = 0; cnt < 10; ++cnt) {
        printf("\nThread counter: %d", cnt);
        SDL_Delay(50);
    }

    // Return the final value to the SDL_WaitThread function above
    return cnt;
}
Line 35: Line 46:
    thread = SDL_CreateThread(TestThread, (void *)NULL);     thread = SDL_CreateThread(TestThread, "TestThread", (void *)NULL);
Line 44: Line 55:
        printf("\nThread returned value:%d", threadReturnValue);         printf("\nThread returned value: %d", threadReturnValue);
Line 47: Line 58:
    return 1;
}

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

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

    // Return the final value to the SDL_WaitThread function above
    return cnt;
    return 0;
Line 66: Line 63:
The return code for the thread function is placed in the area pointed to by '''status''', if '''status''' is not NULL. The return code is the value returned by the 'return' statement in the thread function.
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 a NULL thread to this function; it is a no-op.
Line 72: Line 78:
 . [[SDL_DetachThread]]

SDL_WaitThread

Use this function to wait for a thread to finish.

Syntax

void SDL_WaitThread(SDL_Thread* thread,
                    int*        status)

Function Parameters

thread

the SDL_Thread pointer that was returned from the SDL_CreateThread() call that started this thread

status

pointer to an integer that will receive the value returned from the thread function by its 'return', or NULL to not receive such value back. see Remarks for details

Code Examples

#include <stdio.h>
#include "SDL_thread.h"
#include "SDL_timer.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("\nThread counter: %d", cnt);
        SDL_Delay(50);
    }

    // Return the final value to the SDL_WaitThread function above
    return cnt;
}

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

    printf("\nSimple SDL_CreateThread test:");

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

    if (NULL == thread) {
        printf("\nSDL_CreateThread failed: %s\n", SDL_GetError());
    } else {
        // Wait for the thread to complete. The thread functions return code will
        //       be placed in the "threadReturnValue" variable when it completes.
        //
        SDL_WaitThread(thread, &threadReturnValue);
        printf("\nThread returned value: %d", threadReturnValue);
    }

    return 0;
}

Remarks

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 a NULL thread to this function; it is a no-op.

Note that the thread pointer is freed by this function and is not valid afterward.


CategoryAPI, CategoryThread

None: SDL_WaitThread (last edited 2018-12-12 14:53:52 by RyanGordon)

Feedback
Please include your contact information if you'd like to receive a reply.
Submit