The pthread header files aren't in the doxygen page anymore after #1137,
because I `@file`'d the `.c` files, not the `.h` files.
This change moves doxygen boilerplate.
Closes#1199.
With `pthread_cleanup_(push|pop)` you can define a function that should
be ran if the thread is exited while it is inside this scope. A thread
can be ended here through an explicit call to `pthread_exit()`, or if
cancellation was requested and a cancellation point was hit.
`pthread_cleanup_*` is mostly only useful together with cancellation
points, and cancellation points are only useful with a cleanup
functionality. Cancellation points are at least partially implemented by
means of `pthread_testcancel()`.
C.f. ["Cancellation Points"][1].
[1]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_09_05_02
Application developers use `$(USEMODULES)` in their Makefiles to have
the relevant functionally automagically added to their apps. This even
does basic dependency tracking by means of `Makefile.dep`.
But an important thing is missing: the automatic adding of include
paths. This is inconvenient, error prone, and will hinder the RIOT core
developers in future to change folder structures.
This fixes#755.
The pthread ID cannot be reused as soon as the thread ends, because
another thread needs to join it first. `pthread_self()` uses the native
(i.e. RIOT's) thread ID to distinguish itself. A native thread ID can be
reused as soon as the thread ends, since the core knows no join
operation.
In order to not confuse itself with an earlier zombie thread (i.e a dead
non-detached thread, that was not joined, yet), we need to invalidate
the associated native thread ID.
This approach is sane since a dead thread won't call `pthread_self()`
anymore.
