- Main Page
- Modules
- Classes

- Search for |

# 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 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

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

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