Add dyninstAPI/BPatch_thread.h

docs/dyninstAPI/developer/API.rst

@@ -32,6 +32,7 @@ DyninstAPI
   BPatch_private.h
   BPatch_process.h
   BPatch_snippet.h
+  BPatch_thread.h
   codegen-aarch64.h
   codegen.h
   codegen-power.h

docs/dyninstAPI/developer/BPatch_thread.h.rst

@@ -0,0 +1,25 @@
+.. _`sec-dev:BPatch_thread.h`:
+
+BPatch_thread.h
+###############
+
+.. cpp:namespace:: dev
+
+.. cpp:class:: BPatch_thread
+   
+  **A thread of execution running in a process**
+
+  .. cpp:member:: private bool madeExitCallback_
+
+    Sometimes we get per-thread exit notifications, sometimes we  just get whole-process. So keep track of whether we've notified the user of an exit so we don't duplicate when the process exits.
+
+  .. cpp:function:: protected BPatch_thread(BPatch_process *parent, PCThread *thr)
+  .. cpp:function:: protected static BPatch_thread *createNewThread(BPatch_process *proc, PCThread *thr)
+
+  .. cpp:function:: protected void updateThread(PCThread *newThr)
+
+    Currently only used on an exec to replace the underlying PCThread
+
+  .. cpp:function:: protected bool madeExitCallback()
+  .. cpp:function:: protected void setMadeExitCallback()
+

docs/dyninstAPI/public/BPatch_thread.h.rst

@@ -5,36 +5,35 @@ BPatch_thread.h
 
 .. cpp:class:: BPatch_thread
    
-  The **BPatch_thread** class represents and controls a thread of
-  execution that is running in a process.
+  **A thread of execution running in a process**
 
   .. cpp:function:: void getCallStack(std::vector<BPatch_frame>& stack)
 
     This function fills the given vector with current information about the
-    call stack of the thread. Each stack frame is represented by a
-    BPatch_frame (see section 4.24 for information about this class).
+    call stack of the thread.
+
+  .. cpp:function:: BPatch_process * getProcess()
+
+    Returns a pointer to the process that owns this thread
 
   .. cpp:function:: dynthread_t getTid()
 
-    This function returns a platform-specific identifier for this thread.
-    This is the identifier that is used by the threading library. For
-    example, on pthread applications this function will return the thread’s
-    pthread_t value.
+    Returns a platform-specific identifier for this thread.
+
+    This is the identifier that is used by the threading library.
 
   .. cpp:function:: Dyninst::LWP getLWP()
 
-    This function returns a platform-specific identifier that the operating
-    system uses to identify this thread. For example, on UNIX platforms this
-    returns the LWP id. On Windows this returns a HANDLE object for the
-    thread.
+    Returns a platform-specific identifier that the operating
+    system uses to identify this thread.
 
   .. cpp:function:: unsigned getBPatchID()
 
     This function returns a Dyninst-specific identifier for this thread.
     These ID’s apply only to running threads, the BPatch ID of an already
     terminated thread my be repeated in a new thread.
 
-  .. cpp:function:: BPatch_function *getInitialFunc()
+  .. cpp:function:: BPatch_function * getInitialFunc()
 
     Return the function that was used by the application to start this
     thread. For example, on pthread applications this will return the
@@ -54,21 +53,22 @@ BPatch_thread.h
     this thread. It is illegal to perform any thread-level operations on a
     dead on arrival thread.
 
-  .. cpp:function:: BPatch_process *getProcess()
+  .. cpp:function:: ~BPatch_thread()
 
-    Return the BPatch_process that contains this thread.
+  .. cpp:function:: unsigned long os_handle()
 
-  .. cpp:function:: void *oneTimeCode(const BPatch_snippet &expr, bool *err = NULL)
+  .. cpp:function:: void * oneTimeCode(const BPatch_snippet &expr, bool *err = NULL)
 
     Cause the snippet expr to be evaluated by the process immediately. This
     is similar to the BPatch_process::oneTimeCode function, except that the
     snippet is guaranteed to run only on this thread. The process must be
     stopped to call this function. The behavior is synchronous; oneTimeCode
     will not return until after the snippet has been run in the application.
 
-  .. cpp:function:: bool oneTimeCodeAsync(const BPatch_snippet &expr, \
-       void *userData = NULL, \
-       BpatchOneTimeCodeCallback cb = NULL)
+    Have mutatee execute specified code expr once.  Wait until done.
+
+  .. cpp:function:: bool oneTimeCodeAsync(const BPatch_snippet &expr, void *userData = NULL,\
+                                          BPatchOneTimeCodeCallback cb = NULL)
 
     This function sets up the snippet expr to be evaluated by this thread at
     the next available opportunity. When the snippet finishes running,

dyninstAPI/h/BPatch_thread.h

@@ -50,10 +50,6 @@ class PCThread;
 
 typedef Dyninst::THR_ID dynthread_t;
 
-/*
- * Represents a thread of execution.
- */
-
 class BPATCH_DLL_EXPORT BPatch_thread {
     friend class BPatch_frame;
     friend class BPatch_process;
@@ -62,31 +58,23 @@ class BPATCH_DLL_EXPORT BPatch_thread {
 
     BPatch_process *proc;
     PCThread *llthread;
-	// Sometimes we get per-thread exit notifications, sometimes we 
-	// just get whole-process. So keep track of whether we've notified
-	// the user of an exit so we don't duplicate when the process exits.
+
 	bool madeExitCallback_;
 
  protected:
     BPatch_thread(BPatch_process *parent, PCThread *thr);
 
-    //Generator for above constructor
     static BPatch_thread *createNewThread(BPatch_process *proc, PCThread *thr);
 
-    // Currently only used on an exec to replace the underlying PCThread
     void updateThread(PCThread *newThr);
 
 	bool madeExitCallback() { return madeExitCallback_; }
 	void setMadeExitCallback() { madeExitCallback_ = true; }
 
  public:
 
-    //  BPatch_thread::getCallStack
-    //  Returns a vector of BPatch_frame, representing the current call stack
     bool getCallStack(BPatch_Vector<BPatch_frame>& stack);
 
-    //  BPatch_thread::getProcess
-    //  Returns a pointer to the process that owns this thread
     BPatch_process *  getProcess();
 
     dynthread_t getTid();
@@ -105,12 +93,8 @@ class BPATCH_DLL_EXPORT BPatch_thread {
 
     unsigned long os_handle();
 
-    //  BPatch_thread::oneTimeCode
-    //  Have mutatee execute specified code expr once.  Wait until done.
     void * oneTimeCode(const BPatch_snippet &expr, bool *err = NULL);
 
-    //  BPatch_thread::oneTimeCodeAsync
-    //  Have mutatee execute specified code expr once.  Dont wait until done.
     bool oneTimeCodeAsync(const BPatch_snippet &expr, void *userData = NULL, BPatchOneTimeCodeCallback cb = NULL);
 };