Pin
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
Stop, examine and resume application threads API

Functions

BOOL LEVEL_PINCLIENT::PIN_StopApplicationThreads (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]tidPin 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]iAn 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]tidPin 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
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.

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]tidThe 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
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]tidThe 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
CPU: IA-32 and Intel(R) 64 architectures