Stop, examine and resume application threads API


Functions

BOOL LEVEL_PINCLIENT::PIN_StopApplicationThreads (THREADID tid)
BOOL LEVEL_PINCLIENT::PIN_IsThreadStoppedInDebugger (THREADID tid)
VOID LEVEL_PINCLIENT::PIN_ResumeApplicationThreads (THREADID tid)
UINT32 LEVEL_PINCLIENT::PIN_GetStoppedThreadCount ()
THREADID LEVEL_PINCLIENT::PIN_GetStoppedThreadId (UINT32 i)
const CONTEXTLEVEL_PINCLIENT::PIN_GetStoppedThreadContext (THREADID tid)
CONTEXTLEVEL_PINCLIENT::PIN_GetStoppedThreadWriteableContext (THREADID tid)

Detailed Description

This API allows the user to stop all application threads, examine and modify their state and then resume them. It is available in analysis routines and internal threads.

Function Documentation

const CONTEXT* LEVEL_PINCLIENT::PIN_GetStoppedThreadContext THREADID  tid  ) 
 

This function returns the CONTEXT (register state) of a stopped application thread. The caller can inspect the stopped thread's register state via PIN_GetContextReg() and related API's.

Parameters:
[in] tid Pin ID of a stopped thread.
Returns:
The CONTEXT for thread tid or NULL if that thread is not stopped.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

UINT32 LEVEL_PINCLIENT::PIN_GetStoppedThreadCount  ) 
 

This function can be called in two scenarios. First, it may be called after stopping threads with PIN_StopApplicationThreads(), in which case it tells the number of application threads that were stopped with that API.

Alternatively, this function may be called from a call-back that is registered via PIN_AddDebugInterpreter(). In this case, it tells the number of application threads that are stopped in the debugger.

Returns:
The number of stopped application threads. Returns zero if threads are not currently stopped.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

THREADID LEVEL_PINCLIENT::PIN_GetStoppedThreadId UINT32  i  ) 
 

This function returns the Pin thread ID of a stopped application thread.

Parameters:
[in] i An index in the range [0, n-1], where n is the value returned by PIN_GetStoppedThreadCount().
Returns:
The ID of the indexed thread, which is currently stopped. Returns INVALID_THREADID if i is out of range.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

CONTEXT* LEVEL_PINCLIENT::PIN_GetStoppedThreadWriteableContext THREADID  tid  ) 
 

This function is similar to PIN_GetStoppedThreadContext(), but it returns a CONTEXT that may be modified. The caller may modify the stopped thread's register state via PIN_SetContextReg() and related API's. The stopped thread uses the new register state when it resumes.

Parameters:
[in] tid Pin ID of a stopped thread.
Returns:
The CONTEXT for thread tid or NULL if that thread is not stopped.
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

BOOL LEVEL_PINCLIENT::PIN_IsThreadStoppedInDebugger THREADID  tid  ) 
 

This function returns true if the thread with denoted by 'tid' given by its arguments was stopped in the debugger. Note: If there is no thread with ID 'tid', this function returns false.

Parameters:
[in] tid The Pin thread ID to check
Returns:
TRUE if the specified thread was stopped in the debugger. FALSE indicates that the thread is either running, or doesn't exist
Availability:
Mode: JIT
O/S: Linux, Windows
CPU: IA-32 and Intel(R) 64 architectures

VOID LEVEL_PINCLIENT::PIN_ResumeApplicationThreads THREADID  tid  ) 
 

This function may be called after a successful call to PIN_StopApplicationThreads() in order to resume execution of the stopped application threads. If a thread's CONTEXT was changed while it was stopped, it resumes with the new CONTEXT.

Note:
When used in application thread, it is highly recommended to call it in the same analysis function that called PIN_StopApplicationThreads(). Deferring the call could result in a deadlock when the thread later tries to acquire a lock held by other application thread it suspended.
Parameters:
[in] tid The Pin thread ID of the calling thread. Should be called in the same thread as corresponding PIN_StopApplicationThreads()
Note:
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: IA-32 and Intel(R) 64 architectures

BOOL LEVEL_PINCLIENT::PIN_StopApplicationThreads THREADID  tid  ) 
 

This function may be called by either an application thread or by a Pin internal thread to stop all other application threads at a "safe point". Threads that are stopped at a safe point are always stopped in between traces, so the caller is guaranteed that they are not stopped in the middle of any analysis functions or call-back functions. Once stopped, the calling thread can examine and modify the registers of the stopped threads.

If this function is called by an internal thread, it stops all application threads. If it is called by an application thread, it stops all other application threads. When called by an application thread, this function may be called from an analysis function, but not from a call-back function.

Since this function blocks until other application threads finish their current trace, the caller must not hold any locks that the other threads might try to acquire. Doing so could result in a deadlock.

Parameters:
[in] tid The Pin thread ID of the calling thread.
Returns:
TRUE if the target threads are successfully stopped. FALSE indicates that some other thread is trying to stop the calling thread. In such a case, the caller should return from its analysis function to avoid a deadlock.
Note:
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: IA-32 and Intel(R) 64 architectures


Generated on Thu Feb 2 21:56:17 2017 for Pin by  doxygen 1.4.6