Clarify reason for existence of track_pre_thread_ll_create/_exit.

git-svn-id: svn://svn.valgrind.org/valgrind/trunk@7139

diff --git a/include/pub_tool_tooliface.h b/include/pub_tool_tooliface.h
index b836833b62afa87e9525bfe552b6e1bea06cbcc6..0cfafa56d951ebabc4760c5eebde0119313272f8 100644 (file)
--- a/include/pub_tool_tooliface.h
+++ b/include/pub_tool_tooliface.h
@@ -573,6 +573,21 @@ void VG_(track_stop_client_code)(
 
    ll_exit: low level thread exit.  Called after the exiting thread
    has run its last instruction.
+
+   The _ll_ part makes it clear these events are not to do with
+   pthread_create or pthread_exit/pthread_join (etc), which are a
+   higher level abstraction synthesised by libpthread.  What you be
+   sure of from _ll_create/_ll_exit is the absolute limits of each
+   thread's lifetime, and hence be assured that all memory references
+   made by the thread fall inside the _ll_create/_ll_exit pair.  This
+   is important for tools that need a 100% accurate account of which
+   thread is responsible for every memory reference in the process.
+
+   pthread_create/join/exit do not give this property - they will
+   calls/returns to/from them happen arbitrarily far away from the
+   relevant low-level thread create/quit event.  In general a few
+   hundred instructions; hence a few hundred(ish) memory references
+   could get misclassified each time.
 */
 void VG_(track_pre_thread_ll_create)(void(*f)(ThreadId tid, ThreadId child));
 void VG_(track_pre_thread_ll_exit)  (void(*f)(ThreadId tid));