pthread_threading.h

Thread creation features.

Note

Do not include this header file directly, but pthread.h.

unsigned pthread_t

Datatype to identify a POSIX thread.

Note

The pthread ids are one off to the index in the internal array.

int pthread_create(pthread_threading.h::pthread_t * newthread, const pthread_attr_t * attr, void *(*)(void *) start_routine, void * arg)

Spawn a new POSIX thread.

This functions starts a new thread. The thread will be joinable (from another pthread), unless attr tells to create the thread detached. A non-detached thread must be joined will stay a zombie into it is joined. You can call pthread_threading.h::pthread_exit() inside the thread, or return from start_routine().

Note

Cancellation is currently not implemented.

Note

In an embedded system you probably want to supply a statically allocated stack in attr.

Parameters

newthread:The identifier of the new thread.
attr:An attribute set that describes how the new thread should be started.
start_routine:The entry point of the new thread.
arg:Argument supplied to start_routine.

Return values

  • == 0 on success. != 0 on error.
void pthread_exit(void * retval)

Exit calling pthread.

Note

Only pthreads must call this function. Native threads must call sched_thread_exit(). A pthread must not call sched_thread_exit().

Parameters

retval:Return value, supplied to a joining thread.

Return values

  • This function does not return.
int pthread_join(pthread_threading.h::pthread_t th, void ** thread_return)

Join a pthread.

The current thread sleeps until th exits. The exit value of th gets written into thread_return. You can only join pthreads, and only pthreads can join. A thread must not join itself.

Parameters

th:pthread to join, the id was supplied by pthread_threading.h::pthread_create()
thread_return:Exit code of th.

Return values

  • == 0 on success. != 0 on error.
int pthread_detach(pthread_threading.h::pthread_t th)

Make a pthread unjoinable.

The resources of a detached thread get released as soon as it exits, without the need to call pthread_threading.h::pthread_join() out of another pthread. In fact you cannot join a detached thread, it will return an error. Detaching a thread while another thread tries to join it causes undefined behavior. A pthread may detach himself. A non-pthread may call this function, too. A pthread cannot be “attached” again.

Parameters

th:pthread to detach.

Return values

  • == 0 on success. != 0 on error.
pthread_threading.h::pthread_t pthread_self(void)

Returns the pthread id of the calling/current thread.

Note

This function should not be used to determine if the calling thread is a pthread. If your logic is sane then there should be no need to do that.

Return values

  • > 0 identifies the calling pthread. == 0 if the calling thread is not a pthread.
int pthread_equal(pthread_threading.h::pthread_t thread1, pthread_threading.h::pthread_t thread2)

Compared two pthread identifiers.

Return values

  • 0 if the ids identify two different threads.