Anyone know what the void* return value is for? What are you supposed to return from your thread process?
al_create_thread

I believe it's just whatever you want to return.
To actually get a return value you'd need to use al_join_thread.

Your supposed to return the thread id so another thread can manage it and eventually stall/cancel it.

Edit: seeing the prototype and the definition, I think the documentation is somewhat wrong.

// does not really return 'true' but a valid ALLEGRO_THREAD or NULL; imho
ALLEGRO_THREAD *al_create_thread(void *(*proc)(ALLEGRO_THREAD *thread, void *arg), void *arg)

Once you return from your function, the thread is done. So that wouldn't really do what you think

This discussion is about the return value of the proc callback (i.e., the thread function), not the return value of al_create_thread() (which is what you are describing).

Well, it doesn't actually begin executing proc until you call al_start_thread. And it doesn't return true, it's a pointer to a newly created ALLEGRO_THREAD or zero (null) like Gull said.

It would sound better like :

Create a new thread which will run proc later when you call al_start_thread. The thread is passed its own thread handle and the value arg.

Returns a pointer to a newly created ALLEGRO_THREAD, or NULL if there was an error.

How does that sound?

I feel understood. Thanks Edgar. The two other are just reluctant trolls ;-p

Actually, I just didn't really understand what you were trying to say.

Apparently I'm incapable of parsing human languages.

Don't worry, you're not the only one with poor reading comprehension. Sometimes I think my brain just makes up what other people said.

What format are Allegro's docs in? I will submit a patch if its not too complex.

To be honest, I had assumed Gull was talking about the user function, because you (Edgar) were.

I don't think that's an entirely unreasonable thing to think.

The documentation is written in markdown (processed by pandoc). This particular function is documented here: http://sourceforge.net/p/alleg/allegro/ci/5.1/tree/docs/src/refman/threads.txt

It's just a simple wiki format, so you should be able to create a patch without actually installing pandoc.