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 CONTEXT *	LEVEL_PINCLIENT::PIN_GetStoppedThreadContext (THREADID tid)
CONTEXT *	LEVEL_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

PIN_GetStoppedThreadContext()

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

PIN_GetStoppedThreadCount()

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

PIN_GetStoppedThreadId()

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

PIN_GetStoppedThreadWriteableContext()

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

PIN_IsThreadStoppedInDebugger()

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

PIN_ResumeApplicationThreads()

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]

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

PIN_StopApplicationThreads()

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