Pin
Classes | Typedefs | Functions
LOCK: Locking Primitives
Utilities API Reference

Classes

struct  PIN_LOCK
 

Typedefs

typedef PINVM::PINSYNC_POD_LOCK PIN_MUTEX
 
typedef PINVM::PINSYNC_POD_RWLOCK PIN_RWMUTEX
 
typedef PINVM::PINSYNC_POD_SEMAPHORE PIN_SEMAPHORE
 

Functions

VOID PIN_InitLock (PIN_LOCK *lock)
 
VOID PIN_GetLock (PIN_LOCK *lock, INT32 val)
 
INT32 PIN_ReleaseLock (PIN_LOCK *lock)
 
BOOL PIN_MutexInit (PIN_MUTEX *lock)
 
VOID PIN_MutexFini (PIN_MUTEX *lock)
 
VOID PIN_MutexLock (PIN_MUTEX *lock)
 
VOID PIN_MutexUnlock (PIN_MUTEX *lock)
 
BOOL PIN_MutexTryLock (PIN_MUTEX *lock)
 
BOOL PIN_RWMutexInit (PIN_RWMUTEX *lock)
 
VOID PIN_RWMutexFini (PIN_RWMUTEX *lock)
 
VOID PIN_RWMutexReadLock (PIN_RWMUTEX *lock)
 
VOID PIN_RWMutexWriteLock (PIN_RWMUTEX *lock)
 
VOID PIN_RWMutexUnlock (PIN_RWMUTEX *lock)
 
BOOL PIN_RWMutexTryReadLock (PIN_RWMUTEX *lock)
 
BOOL PIN_RWMutexTryWriteLock (PIN_RWMUTEX *lock)
 
BOOL PIN_SemaphoreInit (PIN_SEMAPHORE *sem)
 
VOID PIN_SemaphoreFini (PIN_SEMAPHORE *sem)
 
VOID PIN_SemaphoreSet (PIN_SEMAPHORE *sem)
 
VOID PIN_SemaphoreClear (PIN_SEMAPHORE *sem)
 
BOOL PIN_SemaphoreIsSet (PIN_SEMAPHORE *sem)
 
VOID PIN_SemaphoreWait (PIN_SEMAPHORE *sem)
 
BOOL PIN_SemaphoreTimedWait (PIN_SEMAPHORE *sem, unsigned timeout)
 

Detailed Description

Primitives for locking.
APIs from this group are available in any thread, including any internal thread spawned by the tool.

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

Typedef Documentation

◆ PIN_MUTEX

typedef PINVM::PINSYNC_POD_LOCK PIN_MUTEX

A simple non-recursive lock. PIN_MUTEX is different from PIN_LOCK because it provides just mutex locking without an extra "lock owner" parameter.

Note
For performance reasons this type request through compiler attributes to be aligned to a memory cache line (64 bytes). For statically allocated objects of this type it is enough. However, when allocating it dynamically it is advised to use allocation operation that enforces this alignment (e.g., memalign)

◆ PIN_RWMUTEX

typedef PINVM::PINSYNC_POD_RWLOCK PIN_RWMUTEX

A non-recursive multiple-reader / single-writer lock. Use this lock when multiple "reader" threads can simultaneously access a shared resource, but "writer" threads need to have exclusive access. This is a write-biased lock: if a writer thread blocks on the lock because there are active readers, new readers are prevented from acquiring the lock until the writer gets access. This prevents starvation of writer threads.

Note
For performance reasons this type request through compiler attributes to be aligned to a memory cache line (64 bytes). For statically allocated objects of this type it is enough. However, when allocating it dynamically it is advised to use allocation operation that enforces this alignment (e.g., memalign)

◆ PIN_SEMAPHORE

typedef PINVM::PINSYNC_POD_SEMAPHORE PIN_SEMAPHORE

A binary semaphore synchronization object. You can use this synchronization when one thread needs to wait for some condition to become true. A binary semaphore has exactly two states: "set" and "clear". It is possible for one or more threads to wait for the semaphore to become "set". Those threads resume when some other thread changes the state to "set".

Note that it is generally not safe to wait on a PIN_SEMAPHORE from an analysis routine or from a call-back function. Most Pin call-back functions are called while Pin holds an internal lock (the VM lock). Therefore, if you wait on a PIN_SEMAPHORE from a call-back, you will prevent any other thread from entering any call-back function (because the waiting thread also holds the VM lock). There is also a danger when waiting on a PIN_SEMAPHORE from an analysis routine. If a thread waits on a semaphore from an analysis routine, the application may also hold some locks of its own. Thus, you can cause a deadlock in the application if you wait on a semaphore while the application holds its own lock.

The dangers listed above do not exist if you wait on a PIN_SEMAPHORE from a Pin internal thread (see PIN_SpawnInternalThread()). Also, it is safe to set, clear, or test a semaphore from any thread, even when executing an analysis routine or call-back function.

Note
For performance reasons this type request through compiler attributes to be aligned to a memory cache line (64 bytes). For statically allocated objects of this type it is enough. However, when allocating it dynamically it is advised to use allocation operation that enforces this alignment (e.g., memalign)

Function Documentation

◆ PIN_GetLock()

VOID PIN_GetLock ( PIN_LOCK *  lock,
INT32  val 
)

Acquire the lock.

Parameters
[in]lockThe lock variable.
[in]valUsed for debugging. Typically, this is the ID of the calling thread. See the _owner field of PIN_LOCK.

◆ PIN_InitLock()

VOID PIN_InitLock ( PIN_LOCK *  lock)

Initialize the lock as free

Parameters
[in]lockThe lock variable to initialize.

◆ PIN_MutexFini()

VOID PIN_MutexFini ( PIN_MUTEX *  lock)

Destroy the PIN_MUTEX and deallocate resources. If you want to use the lock object again later, you must call PIN_MutexInit() again.

Parameters
[in]lockThe lock variable.

◆ PIN_MutexInit()

BOOL PIN_MutexInit ( PIN_MUTEX *  lock)

This function must be called to initialize a PIN_MUTEX before it is used.

Parameters
[in]lockThe lock variable.
Returns
TRUE on successful initialization. If FALSE is returned, initialization failed, and the PIN_MUTEX may not be used.

◆ PIN_MutexLock()

VOID PIN_MutexLock ( PIN_MUTEX *  lock)

Block the caller until the lock can be acquired.

Parameters
[in]lockThe lock variable.

◆ PIN_MutexTryLock()

BOOL PIN_MutexTryLock ( PIN_MUTEX *  lock)

Try to acquire the lock, but do not block the caller.

Parameters
[in]lockThe lock variable.
Returns
TRUE if the lock is acquired, FALSE if not.

◆ PIN_MutexUnlock()

VOID PIN_MutexUnlock ( PIN_MUTEX *  lock)

Release the lock.

Parameters
[in]lockThe lock variable.

◆ PIN_ReleaseLock()

INT32 PIN_ReleaseLock ( PIN_LOCK *  lock)

Release the lock.

Parameters
[in]lockThe lock variable.
Returns
The val parameter that was passed to PIN_GetLock() when the lock was acquired. Typically, this is the ID of the thread that owned the lock.

◆ PIN_RWMutexFini()

VOID PIN_RWMutexFini ( PIN_RWMUTEX *  lock)

Destroy the PIN_RWMUTEX and deallocate resources. If you want to use the lock object again later, you must call PIN_RWMutexInit() again.

Parameters
[in]lockThe lock variable.

◆ PIN_RWMutexInit()

BOOL PIN_RWMutexInit ( PIN_RWMUTEX *  lock)

This function must be called to initialize a PIN_RWMUTEX before it is used.

Parameters
[in]lockThe lock variable.
Returns
TRUE on successful initialization. If FALSE is returned, initialization failed, and the PIN_RWMUTEX may not be used.

◆ PIN_RWMutexReadLock()

VOID PIN_RWMutexReadLock ( PIN_RWMUTEX *  lock)

Acquire the lock for "read" access, blocking if necessary. Multiple readers may simultaneously hold the same lock.

Parameters
[in]lockThe lock variable.

◆ PIN_RWMutexTryReadLock()

BOOL PIN_RWMutexTryReadLock ( PIN_RWMUTEX *  lock)

Attempts to acquire the lock as a reader, but does not block the caller.

Parameters
[in]lockThe lock variable.
Returns
TRUE if the lock is acquired, FALSE if not.

◆ PIN_RWMutexTryWriteLock()

BOOL PIN_RWMutexTryWriteLock ( PIN_RWMUTEX *  lock)

Attempts to acquire the lock as a writer, but does not block the caller.

Parameters
[in]lockThe lock variable.
Returns
TRUE if the lock is acquired, FALSE if not.

◆ PIN_RWMutexUnlock()

VOID PIN_RWMutexUnlock ( PIN_RWMUTEX *  lock)

Release the lock. Used for both "readers" and "writers".

Parameters
[in]lockThe lock variable.

◆ PIN_RWMutexWriteLock()

VOID PIN_RWMutexWriteLock ( PIN_RWMUTEX *  lock)

Acquire the lock for "write" access, blocking if necessary. A writer has exclusive ownership of the lock, not shared with any other readers or writers.

Parameters
[in]lockThe lock variable.

◆ PIN_SemaphoreClear()

VOID PIN_SemaphoreClear ( PIN_SEMAPHORE *  sem)

Change the semaphore's state to "clear". This has no effect on any threads waiting on the semaphore.

Parameters
[in]semThe semaphore variable.

◆ PIN_SemaphoreFini()

VOID PIN_SemaphoreFini ( PIN_SEMAPHORE *  sem)

Destroy the PIN_SEMAPHORE and deallocate resources. If you want to use the lock object again later, you must call PIN_SemaphoreInit() again.

Parameters
[in]semThe semaphore variable.

◆ PIN_SemaphoreInit()

BOOL PIN_SemaphoreInit ( PIN_SEMAPHORE *  sem)

This function must be called to initialize a PIN_SEMAPHORE before it is used.

Parameters
[in]semThe semaphore variable.
Returns
TRUE on successful initialization. If FALSE is returned, initialization failed, and the PIN_SEMAPHORE may not be used.

◆ PIN_SemaphoreIsSet()

BOOL PIN_SemaphoreIsSet ( PIN_SEMAPHORE *  sem)

Check whether the semaphore's state is "set", but do not block.

Parameters
[in]semThe semaphore variable.
Returns
TRUE if the semaphore's state is "set".

◆ PIN_SemaphoreSet()

VOID PIN_SemaphoreSet ( PIN_SEMAPHORE *  sem)

Change the semaphore's state to "set" and tell any threads waiting on the semaphore to wake up. Note that threads waiting on the semaphore may not resume running right away, and they are guaranteed to resume only if the semaphore's state is still "set" when they actually do resume.

Parameters
[in]semThe semaphore variable.

◆ PIN_SemaphoreTimedWait()

BOOL PIN_SemaphoreTimedWait ( PIN_SEMAPHORE *  sem,
unsigned  timeout 
)

Block the calling thread until the semaphore's state is "set" or until a timeout expires. The calling thread resumes immediately if the state is already "set".

Parameters
[in]semThe semaphore variable.
[in]timeoutThe timeout period (milliseconds).
Returns
TRUE if the semaphore's state is "set", FALSE if this method returns due to the timeout.

◆ PIN_SemaphoreWait()

VOID PIN_SemaphoreWait ( PIN_SEMAPHORE *  sem)

Block the calling thread until the semaphore's state is "set". The calling thread resumes immediately if the state is already "set".

Parameters
[in]semThe semaphore variable.
Generated by   doxygen 1.8.17