Pin Thread API


Typedefs

typedef INT32 LEVEL_BASE::TLS_KEY
typedef UINT32 THREADID
typedef UINT32 OS_THREAD_ID
typedef UINT32 OS_PROCESS_ID

Functions

OS_THREAD_ID LEVEL_PINCLIENT::PIN_GetTid ()
THREADID LEVEL_PINCLIENT::PIN_ThreadId ()
OS_THREAD_ID LEVEL_PINCLIENT::PIN_GetParentTid ()
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)
BOOL LEVEL_PINCLIENT::PIN_SetThreadData (TLS_KEY key, const VOID *data, THREADID currentThreadId)
VOID * LEVEL_PINCLIENT::PIN_GetThreadData (TLS_KEY key)
VOID * LEVEL_PINCLIENT::PIN_GetThreadData (TLS_KEY key, THREADID currentThreadId)

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 OS_THREAD_ID INVALID_OS_THREAD_ID = 0

Detailed Description

These APIs provide Pin thread support.

Typedef Documentation

typedef UINT32 OS_PROCESS_ID
 

Process ID assigned by OS.

typedef UINT32 OS_THREAD_ID
 

Thread ID assigned by OS.

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

OS_THREAD_ID LEVEL_PINCLIENT::PIN_GetParentTid  ) 
 

Get ID of the parent thread assigned by OS.

Returns:
OS thread ID of the parent thread; INVALID_OS_THREAD_ID, if parent thread is unknown
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All

VOID* LEVEL_PINCLIENT::PIN_GetThreadData TLS_KEY  key,
THREADID  currentThreadId
 

Fast variant of the PIN_GetThreadData function

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

VOID* LEVEL_PINCLIENT::PIN_GetThreadData TLS_KEY  key  ) 
 

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] currentThreadId ID of the current thread assigned by pin. This ID can be obtained by the PIN_ThreadId() function call or received as the value of the IARG_THREAD_ID argument. This optional parameter, if supplied, significantly improves performance of this function.
Returns:
value stored in the specified slot of the thread, if specified key is currently allocated; NULL, if specified key is invalid or the current 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  ) 
 

Returns OS thread ID associated with current thread

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

BOOL LEVEL_PINCLIENT::PIN_SetThreadData TLS_KEY  key,
const VOID *  data,
THREADID  currentThreadId
 

Fast variant of the PIN_SetThreadData function

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

BOOL LEVEL_PINCLIENT::PIN_SetThreadData TLS_KEY  key,
const VOID *  data
 

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] currentThreadId ID of the current thread assigned by pin. This ID can be obtained by the PIN_ThreadId() function call or received as the value of the IARG_THREAD_ID argument. This optional parameter, if supplied, significantly improves performance of this function.
Returns:
TRUE, if specified key is currently allocated; FALSE, if specified key is invalid or the current 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

THREADID LEVEL_PINCLIENT::PIN_ThreadId  ) 
 

Get ID of the current thread assigned by pin

Returns:
ID of the current thread; INVALID_THREADID if current thread is not yet registered in the pin thread database. It could happen if a client tool created private thread but did not register it by calling to the PIN_RegisterNewThread function
Availability:
Mode: JIT
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 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


Generated on Thu May 15 03:23:40 2008 for Pin by  doxygen 1.4.6