- Main Page
- Modules
- Classes

- Search for |

# Pin Thread API

## Typedefs

typedef INT32 | LEVEL_BASE::TLS_KEY
typedef UINT32 | THREADID
typedef UINT64 | PIN_THREAD_UID
typedef UINT32 | OS_THREAD_ID
typedef VOID | ROOT_THREAD_FUNC (VOID *arg)
typedef UINT32 | OS_PROCESS_ID

## Functions

OS_THREAD_ID | LEVEL_PINCLIENT::PIN_GetTid ()
THREADID | LEVEL_PINCLIENT::PIN_ThreadId ()
PIN_THREAD_UID | LEVEL_PINCLIENT::PIN_ThreadUid ()
OS_THREAD_ID | LEVEL_PINCLIENT::PIN_GetParentTid ()
VOID | LEVEL_PINCLIENT::PIN_Sleep (UINT32 milliseconds)
VOID | LEVEL_PINCLIENT::PIN_Yield ()
THREADID | LEVEL_PINCLIENT::PIN_SpawnInternalThread (ROOT_THREAD_FUNC *pThreadFunc, VOID *arg, size_t stackSize, PIN_THREAD_UID *pThreadUid)
VOID | LEVEL_PINCLIENT::PIN_ExitThread (INT32 exitCode)
BOOL | LEVEL_PINCLIENT::PIN_IsApplicationThread ()
BOOL | LEVEL_PINCLIENT::PIN_WaitForThreadTermination (const PIN_THREAD_UID &threadUid, UINT32 milliseconds, INT32 *pExitCode)
TLS_KEY | LEVEL_PINCLIENT::PIN_CreateThreadDataKey (DESTRUCTFUN destruct_func)
BOOL | LEVEL_PINCLIENT::PIN_DeleteThreadDataKey (TLS_KEY key)
BOOL | LEVEL_PINCLIENT::PIN_SetThreadData (TLS_KEY key, const VOID *data, THREADID threadId)
VOID * | LEVEL_PINCLIENT::PIN_GetThreadData (TLS_KEY key, THREADID threadId)

## Variables

GLOBALCONST TLS_KEY | LEVEL_BASE::INVALID_TLS_KEY = (-1)
GLOBALCONST UINT32 | LEVEL_PINCLIENT::MAX_CLIENT_TLS_KEYS = (TLS_KEY_CLIENT_LAST - TLS_KEY_CLIENT_FIRST + 1)
GLOBALCONST THREADID | INVALID_THREADID = static_cast<THREADID>(-1)
GLOBALCONST PIN_THREAD_UID | INVALID_PIN_THREAD_UID = static_cast<PIN_THREAD_UID>(-1)
GLOBALCONST OS_THREAD_ID | INVALID_OS_THREAD_ID = 0

## Detailed Description

A group of Pin threading primitives. These APIs are available in any thread, including any internal thread spawned by the tool.

## Typedef Documentation

typedef UINT32 OS_PROCESS_ID

| Process ID assigned by OS.

typedef UINT32 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.

Parameters:

  `[in]` | arg | argument of the main thread function, as specified by the thread creator.

typedef UINT32 THREADID

| Thread ID assigned by PIN.

typedef INT32 LEVEL_BASE::TLS_KEY

| Type that represents TLS key - a unique identifier of a slot in the thread local storage.

## Function Documentation

TLS_KEY LEVEL_PINCLIENT::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.

Parameters:

  `[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.

Returns:
  allocated TLS key, upon success; -1, if number of already allocated keys reached the MAX_CLIENT_TLS_KEYS limit.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

BOOL LEVEL_PINCLIENT::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.

Parameters:

  `[in]` | key | TLS key to be released

Returns:
  TRUE, upon success; FALSE, if if specified key is invalid

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID LEVEL_PINCLIENT::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.

Parameters:

  `[in]` | exitCode | exit code of the thread to be returned by the PIN_WaitForThreadTermination() function.

Returns:
  the function never returns.

Note:
  The vm lock is obtained during the call of this API.

Availability:
  Mode: JIT
  O/S: Linux, Windows
  CPU: All

OS_THREAD_ID LEVEL_PINCLIENT::PIN_GetParentTid | ( |  | ) |

| Get system identifier of the parent thread, if known.

Returns:
  system ID of the parent thread or INVALID_OS_THREAD_ID if the parent thread is unknown. On Windows the result is always INVALID_OS_THREAD_ID, since there is, in general, no well defined parent child relationship between threads.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID* LEVEL_PINCLIENT::PIN_GetThreadData | ( | TLS_KEY | key,
|  | THREADID | threadId
| ) |

| Get the value stored in the specified TLS slot of the thread.

Parameters:

  `[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.

Returns:
  value stored in the specified slot of the thread, if specified key is currently allocated; NULL, if specified key is invalid or the given thread is not yet registered in the pin thread database; undefined, if specified key is valid, but it is not currently allocated

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

OS_THREAD_ID LEVEL_PINCLIENT::PIN_GetTid | ( |  | ) |

| Get system identifier of the current thread.

Returns:
  system ID of the current thread.

Availability:
  Mode: JIT & Probe
  O/S: Linux, Windows & MacOS
  CPU: All

BOOL LEVEL_PINCLIENT::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()).

Returns:
  TRUE, if this function is called in a thread created by the application; FALSE, if this function is called in an internal thread spawned by the tool or Pin.

Availability:
  Mode: JIT
  O/S: Linux, Windows
  CPU: All

BOOL LEVEL_PINCLIENT::PIN_SetThreadData | ( | TLS_KEY | key,
|  | const VOID * | data,
|  | THREADID | threadId
| ) |

| Store specified value in the specified TLS slot of the thread.

Parameters:

  `[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.

Returns:
  TRUE, if specified key is currently allocated; FALSE, if specified key is invalid or the given thread is not yet registered in the pin thread database; undefined, if specified key is valid, but it is not currently allocated

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID LEVEL_PINCLIENT::PIN_Sleep | ( | UINT32 | milliseconds | ) |

| Delay execution of the current thread for the specified time interval.

Parameters:

  `[in]` | milliseconds | time interval, in milliseconds.

Availability:
  Mode: JIT & Probe
  O/S: Linux, Windows & MacOS
  CPU: All

THREADID LEVEL_PINCLIENT::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 application 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 one of the following recommended methods:

- All tool threads periodically check the state of the application process by calling the PIN_IsProcessExiting function. If this function indicates that the application process is about to terminate, the threads either return or call the PIN_ExitThread() function as soon as possible. The grace period for Pin to wait for the termination of tool threads can be specified with the -tool_exit_timeout command line switch.
- The tool uses the PIN_AddFiniUnlockedFunction() function to register a FINI_CALLBACK callback. When the registered function is called in an "unlocked" application thread, the tool requests each internal thread to exit and waits until the PIN_WaitForThreadTermination() function returns.

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.

Parameters:

  `[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.

Returns:
  ID of the new thread in Pin or INVALID_THREADID if the thread creation failed.

Note:
  The PIN_SpawnInternalThread() API is the only way for tools to create a private thread in the Pin-controlled process. System services, like CreateThread() in Windows or clone() in Linux should not be used for this purpose.

  Pin makes an effort to hide internal threads from the application so, usually, a tool's threads do not interfere with the application. However, the complete transparency of internal threads is not guaranteed, so tools should only use them when their instrumentation tasks cannot be done (effectively) by analysis routines within application threads. For example, a need to execute Windows services (Win32 APIs) may be a reason for creating a private thread in the tool. All Win32 APIs that do not modify the application's resources can be freely used in internal threads. In application threads, on the contrary, using Win32 APIs in analysis routines and Pin callbacks is not supported due to possible reentrancy and isolation problems.

  Internal threads remain blocked inside Pin until PIN_StartProgram() is called and Pin completes some initialization. On Linux, internal threads start running pThreadFunc before Pin executes the first application instruction. On Windows all threads, including Pin internal threads, start executing from the system runtime before they execute the pThreadFunc function. However, the system runtime blocks threads until the application has finished initializing its DLL's (i.e. until the application releases the internal "loader lock"). As a result, Pin internal threads on Windows do not execute pThreadFunc until after the application finishes executing the DLL initialization code.

Availability:
  Mode: JIT
  O/S: Linux, Windows
  CPU: All

THREADID LEVEL_PINCLIENT::PIN_ThreadId | ( |  | ) |

| Get identifier of the current thread in Pin.

Returns:
  ID of the current thread in Pin or INVALID_THREADID upon failure. Usually, the failure means that the function is called in a private tool's thread which is created by a direct call to a system service and not via the PIN_SpawnInternalThread() function.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

PIN_THREAD_UID LEVEL_PINCLIENT::PIN_ThreadUid | ( |  | ) |

| Get unique identifier of the current thread in Pin.

Returns:
  Unique ID of the current thread in Pin or INVALID_PIN_THREAD_UID upon failure. Usually, the failure means that the function is called in a private tool's thread which is created by a direct call to a system service and not via the PIN_SpawnInternalThread() function.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

BOOL LEVEL_PINCLIENT::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 FINI_CALLBACK callback if it is registered by the PIN_AddFiniUnlockedFunction(). 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.

Parameters:

  `[in]` | threadUid | unique identifier of the thread to be waited for termination
  `[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.
  `[in]` | 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.

Returns:
  TRUE - the thread has terminated, FALSE - the specified time-out interval elapsed.

Availability:
  Mode: JIT
  O/S: Linux, Windows
  CPU: All

VOID LEVEL_PINCLIENT::PIN_Yield | ( |  | ) |

| Yield the processor to another thread.

Availability:
  Mode: JIT & Probe
  O/S: Linux, Windows & MacOS
  CPU: All

## Variable Documentation

GLOBALCONST OS_THREAD_ID INVALID_OS_THREAD_ID = 0

| Invalid value of the OS_THREAD_ID type.

GLOBALCONST PIN_THREAD_UID INVALID_PIN_THREAD_UID = static_cast<PIN_THREAD_UID>(-1)

| Invalid value of the PIN_THREAD_UID type.

GLOBALCONST THREADID INVALID_THREADID = static_cast<THREADID>(-1)

| Invalid value of the THREADID type.

GLOBALCONST TLS_KEY LEVEL_BASE::INVALID_TLS_KEY = (-1)

| Invalid value of the TLS_KEY type.

GLOBALCONST UINT32 LEVEL_PINCLIENT::MAX_CLIENT_TLS_KEYS = (TLS_KEY_CLIENT_LAST - TLS_KEY_CLIENT_FIRST + 1)

| Maximum number of TLS keys that can be allocated by tool