Wiki Page Content

Differences between revisions 1 and 17 (spanning 16 versions)
Revision 1 as of 2010-05-25 04:29:40
Size: 1072
Editor: SheenaSmith
Comment: create page, add content (Wed Mar 10 ver; changeset 4428)
Revision 17 as of 2013-11-16 13:31:15
Size: 2712
Comment: Changed includes in example, see FAQDevelopment page.
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
#pragma disable-camelcase
||<tablewidth="100%" style="color: #FF0000;" :> DRAFT||
#pragma camelcase off
Line 15: Line 14:
Line 17: Line 15:
||'''thread'''||^a pointer to the [[SDL_Thread]]() to wait for^||
||'''status'''||^a pointer filled with status data^; see [[#Remarks|Remarks]] for details||
||'''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', see [[#Remarks|Remarks]] for details ||
Line 22: Line 20:
You can add your code example here
#include <stdio.h>
#include "SDL_thread.h"
#include "SDL_timer.h"

int TestThread(void *ptr);

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 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;
}
Line 26: Line 66:

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.
Line 28: Line 73:
<<Color2(green,Should anything be included here (or in Return Value?) that indicates what the "return code" might be? Seems like maybe 1 for waiting 0 for done -1 for error? Why is that not a Return Value? Just because it fills a pointer with it?)>> 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.
Line 31: Line 80:
 . [[SDL_CreateThread]]
 . [[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', see Remarks for details

Code Examples

#include <stdio.h>
#include "SDL_thread.h"
#include "SDL_timer.h"

int TestThread(void *ptr);

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 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;
}

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