|
Pin
|
Typedefs | |
| typedef INT32 | TLS_KEY |
| typedef UINT32 | THREADID |
| typedef UINT64 | PIN_THREAD_UID |
| typedef NATIVE_TID | OS_THREAD_ID |
| typedef VOID | ROOT_THREAD_FUNC(VOID *arg) |
| typedef UINT32 | OS_PROCESS_ID |
Enumerations | |
| enum | { TLS_KEY_INTERNAL_EXCEPTION, TLS_KEY_CLIENT_FIRST, TLS_KEY_CLIENT_LAST = TLS_KEY_CLIENT_FIRST + 63 } |
Variables | |
| const TLS_KEY | INVALID_TLS_KEY = (-1) |
| const UINT32 | MAX_CLIENT_TLS_KEYS = (TLS_KEY_CLIENT_LAST - TLS_KEY_CLIENT_FIRST + 1) |
| const THREADID | INVALID_THREADID = static_cast< THREADID >(-1) |
| const PIN_THREAD_UID | INVALID_PIN_THREAD_UID = static_cast< PIN_THREAD_UID >(-1) |
| const OS_THREAD_ID | INVALID_OS_THREAD_ID = INVALID_NATIVE_TID |
A group of Pin threading primitives. These APIs are available in any thread, including any internal thread spawned by the tool. They 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
| typedef UINT32 OS_PROCESS_ID |
Process ID assigned by OS.
| typedef NATIVE_TID OS_THREAD_ID |
Thread ID assigned by OS.
| typedef UINT64 PIN_THREAD_UID |
Unique thread ID which, unlike THREADID identifier, is not reused by Pin after the thread termination. The uniqueness of this identifier allows to use it in the PIN_WaitForThreadTermination() function which monitors the thread's state.
| typedef VOID ROOT_THREAD_FUNC(VOID *arg) |
Main (starting) function of a thread.
| [in] | arg | argument of the main thread function, as specified by the thread creator. |
| typedef UINT32 THREADID |
Thread ID assigned by PIN.
| typedef INT32 TLS_KEY |
Type that represents TLS key - a unique identifier of a slot in the thread local storage.
| anonymous enum |
Keys to access client data in the thread local storage
| TLS_KEY PIN_CreateThreadDataKey | ( | DESTRUCTFUN | destruct_func | ) |
Allocate a new TLS key and associate it with a given data destruction function. Upon successful return, any thread of the process can use PIN_SetThreadData() and PIN_GetThreadData() functions to store and retrieve values in its own slot, referenced by the allocated key. The initial value associated with the key in all threads is NULL. At the thread exit, if a key has a non-NULL pointer to the cleanup (destruction) function, and the thread has a non-NULL value in the corresponding slot, the function is called with the slot's value as its sole argument. The order in which destructors are invoked is undefined.
| [in] | destructFun | optional parameter that specifies data destruction function to be associated with the new key. This function is called just after notifying the client about VM thread exit. By default (NULL destructor), the data is not cleaned up. |
| BOOL PIN_DeleteThreadDataKey | ( | TLS_KEY | key | ) |
Release TLS key, allocated by a previous call to the PIN_CreateThreadDataKey() function. The function has no effect if specified key is not allocated/already released. After the key is released, a client should not attempt to use it for any further TLS access. Doing otherwise results in undefined behavior.
| [in] | key | TLS key to be released |
| VOID PIN_ExitThread | ( | INT32 | exitCode | ) |
Terminate the current thread.
This function is intended for threads created by the tool (see PIN_SpawnInternalThread()) and is not normally used for threads created by the application, since application threads exit automatically when Pin executes a thread termination system call on their behalf.
If this call is made on an application thread, Pin will make any callbacks registered for thread exit before the thread is terminated.
| [in] | exitCode | exit code of the thread to be returned by the PIN_WaitForThreadTermination() function. |
| OS_THREAD_ID PIN_GetParentTid | ( | ) |
Get system identifier of the parent thread, if known.
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.
| [in] | tid | Pin ID of a stopped thread. |
| UINT32 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.
| THREADID PIN_GetStoppedThreadId | ( | UINT32 | i | ) |
This function returns the Pin thread ID of a stopped application thread.
| [in] | i | An index in the range [0, n-1], where n is the value returned by PIN_GetStoppedThreadCount(). |
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.
| [in] | tid | Pin ID of a stopped thread. |
Get the value stored in the specified TLS slot of the thread.
| [in] | key | TLS key, referencing the slot, whose value is requested. The key should be allocated by a previous call to the PIN_CreateThreadDataKey() function. |
| [in] | threadId | Thread ID assigned by pin of the thread for which TLS access is desired, not necessarily the current thread. This ID can be obtained by the PIN_ThreadId() function call or received as the value of the IARG_THREAD_ID argument. |
| OS_THREAD_ID PIN_GetTid | ( | ) |
Threading API for clients
Get system identifier of the current thread.
| BOOL PIN_IsApplicationThread | ( | ) |
Check to see if the current thread is created by the application or it is an internal thread spawned by the tool or Pin itself (see PIN_SpawnInternalThread()).
| BOOL 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.
| [in] | tid | The Pin thread ID to check |
| VOID 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.
| [in] | tid | The Pin thread ID of the calling thread. Should be called in the same thread as corresponding PIN_StopApplicationThreads() |
Store specified value in the specified TLS slot of the thread.
| [in] | key | TLS key, referencing the slot, where the value will be stored upon successful return. The key should be allocated by a previous call to the PIN_CreateThreadDataKey() function. |
| [in] | data | value to be stored in the TLS slot of the current thread. |
| [in] | threadId | Thread ID assigned by pin of the thread for which TLS access is desired, not necessarily the current thread. This ID can be obtained by the PIN_ThreadId() function call or received as the value of the IARG_THREAD_ID argument. |
| VOID PIN_Sleep | ( | UINT32 | milliseconds | ) |
Delay execution of the current thread for the specified time interval.
| [in] | milliseconds | time interval, in milliseconds. |
| BOOL PIN_SpawnApplicationThread | ( | const CONTEXT * | ctxt | ) |
Start a new thread which will begin to execute with the register state from the context. At least the flags register in the context must be sensible (even if all of the thread's registers will be set in the thread start callback).
This function requires the VM lock to operate, so will acquire and release it if it is not already held.
| [in] | ctxt | context for the new thread. |
| THREADID PIN_SpawnInternalThread | ( | ROOT_THREAD_FUNC * | pThreadFunc, |
| VOID * | arg, | ||
| size_t | stackSize, | ||
| PIN_THREAD_UID * | pThreadUid | ||
| ) |
Create a new tool internal thread in the current process.
It is safe to create internal threads in the tool's main procedure and spawn new internal threads from existing ones. However new internal threads cannot be created in any other places, like Pin callbacks and analysis routines in application threads.
In order to ensure graceful termination of internal threads on the application's exit, the tool can use the following recommended method:
Many of Pin's APIs, that are primarily intended for application threads, are also available in internal threads. Look at the API's description ( Availability paragraph) or the description of the corresponding group of APIs to check whether a specific API is available in internal threads.
| [in] | pThreadFunc | main (starting) function of the thread |
| [in] | arg | argument of the main thread function |
| [in] | stackSize | size of the thread's stack, in bytes. The function rounds this value up to the page size. If this parameter is zero, DEFAULT_THREAD_STACK_SIZE bytes will be allocated for the stack. |
| [out] | pThreadUid | pointer to a variable that receives the unique identifier of the new thread in Pin. This identifier can be used in the PIN_WaitForThreadTermination() function to monitor the thread's state. If the caller specifies NULL for this parameter, the unique thread ID is not returned. |
| BOOL PIN_StopApplicationThreads | ( | THREADID | tid | ) |
Pin client functions to temporarily stop all application threads, examine their state and resume.
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.
| [in] | tid | The Pin thread ID of the calling thread. |
| THREADID PIN_ThreadId | ( | ) |
Get identifier of the current thread in Pin.
| PIN_THREAD_UID PIN_ThreadUid | ( | ) |
Get unique identifier of the current thread in Pin.
| BOOL PIN_WaitForThreadTermination | ( | const PIN_THREAD_UID & | threadUid, |
| UINT32 | milliseconds, | ||
| INT32 * | pExitCode | ||
| ) |
Delay the current thread until the specified thread is terminated or the time-out interval elapses.
To avoid deadlocks, the caller should not hold any lock that the target thread may try to acquire. For example, this function can be safely used in the PREPARE_FOR_FINI_CALLBACK callback if it is registered by the PIN_AddPrepareForFiniFunction(). However, it is not recommended to use this function in other Pin callbacks if the target thread is an application thread or an internal thread that uses Pin APIs. This is because most of Pin APIs and callbacks are serialized by the same internal lock.
This function can not be used to wait for the termination of the calling thread.
| [in] | threadUid | unique identifier of the thread to be waited for termination, provided by PIN_SpawnInternalThread() or PIN_ThreadUid(). |
| [in] | milliseconds | time-out interval, in milliseconds. If this parameter is zero, the function tests the thread's state and returns immediately. If this parameter is PIN_INFINITE_TIMEOUT, the time-out interval never elapses. |
| [out] | pExitCode | optional pointer to a variable that receives exit code of the thread. If this pointer is NULL or the thread has not terminated, the exit code is not returned. |
| VOID PIN_Yield | ( | ) |
Yield the processor to another thread.
| const OS_THREAD_ID INVALID_OS_THREAD_ID = INVALID_NATIVE_TID |
Invalid value of the OS_THREAD_ID type.
| const PIN_THREAD_UID INVALID_PIN_THREAD_UID = static_cast< PIN_THREAD_UID >(-1) |
Invalid value of the PIN_THREAD_UID type.
| const TLS_KEY INVALID_TLS_KEY = (-1) |
Invalid value of the TLS_KEY type.
| const UINT32 MAX_CLIENT_TLS_KEYS = (TLS_KEY_CLIENT_LAST - TLS_KEY_CLIENT_FIRST + 1) |
Maximum number of TLS keys that can be allocated by tool
1.8.17