|
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:
- The tool uses the PIN_AddPrepareForFiniFunction() function to register a PREPARE_FOR_FINI_CALLBACK callback. When the registered function is called in an "unlocked" thread, the tool requests each other internal thread to exit and waits until the PIN_WaitForThreadTermination() function returns.
- Note:
- : Pin doesn't wait for internal threads termination after the callbacks.
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
|