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.
|[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.|
- ID of the new thread in Pin or INVALID_THREADID if the thread creation failed.
- 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.
- Mode: JIT
O/S: Linux, Windows