From: Julian Seward <jseward@acm.org>
Date: Sat, 10 Nov 2007 22:13:03 +0000 (+0000)
Subject: Clarify reason for existence of track_pre_thread_ll_create/_exit.
X-Git-Tag: svn/VALGRIND_3_3_0~151
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=88c1e8eb76674cdd87e60bf9bc9ca3f70497df24;p=thirdparty%2Fvalgrind.git

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 b836833b62..0cfafa56d9 100644
--- 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));