LOCK: Locking Primitives


Typedefs

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

Functions

VOID LEVEL_BASE::PIN_InitLock (PIN_LOCK *lock)
VOID LEVEL_BASE::PIN_GetLock (PIN_LOCK *lock, INT32 val)
INT32 LEVEL_BASE::PIN_ReleaseLock (PIN_LOCK *lock)
BOOL LEVEL_BASE::PIN_MutexInit (PIN_MUTEX *lock)
VOID LEVEL_BASE::PIN_MutexFini (PIN_MUTEX *lock)
VOID LEVEL_BASE::PIN_MutexLock (PIN_MUTEX *lock)
VOID LEVEL_BASE::PIN_MutexUnlock (PIN_MUTEX *lock)
BOOL LEVEL_BASE::PIN_MutexTryLock (PIN_MUTEX *lock)
BOOL LEVEL_BASE::PIN_RWMutexInit (PIN_RWMUTEX *lock)
VOID LEVEL_BASE::PIN_RWMutexFini (PIN_RWMUTEX *lock)
VOID LEVEL_BASE::PIN_RWMutexReadLock (PIN_RWMUTEX *lock)
VOID LEVEL_BASE::PIN_RWMutexWriteLock (PIN_RWMUTEX *lock)
VOID LEVEL_BASE::PIN_RWMutexUnlock (PIN_RWMUTEX *lock)
BOOL LEVEL_BASE::PIN_RWMutexTryReadLock (PIN_RWMUTEX *lock)
BOOL LEVEL_BASE::PIN_RWMutexTryWriteLock (PIN_RWMUTEX *lock)
BOOL LEVEL_BASE::PIN_SemaphoreInit (PIN_SEMAPHORE *sem)
VOID LEVEL_BASE::PIN_SemaphoreFini (PIN_SEMAPHORE *sem)
VOID LEVEL_BASE::PIN_SemaphoreSet (PIN_SEMAPHORE *sem)
VOID LEVEL_BASE::PIN_SemaphoreClear (PIN_SEMAPHORE *sem)
BOOL LEVEL_BASE::PIN_SemaphoreIsSet (PIN_SEMAPHORE *sem)
VOID LEVEL_BASE::PIN_SemaphoreWait (PIN_SEMAPHORE *sem)
BOOL LEVEL_BASE::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

typedef PINVM::PINSYNC_POD_LOCK LEVEL_BASE::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.

typedef PINVM::PINSYNC_POD_RWLOCK LEVEL_BASE::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.

typedef PINVM::PINSYNC_POD_SEMAPHORE LEVEL_BASE::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.


Function Documentation

VOID LEVEL_BASE::PIN_GetLock PIN_LOCK *  lock,
INT32  val
 

Acquire the lock.

Parameters:
[in] lock The lock variable.
[in] val Used for debugging. Typically, this is the ID of the calling thread. See the _owner field of PIN_LOCK.

VOID LEVEL_BASE::PIN_InitLock PIN_LOCK *  lock  ) 
 

Initialize the lock as free

Parameters:
[in] lock The lock variable to initialize.

VOID LEVEL_BASE::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] lock The lock variable.

BOOL LEVEL_BASE::PIN_MutexInit PIN_MUTEX lock  ) 
 

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

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

VOID LEVEL_BASE::PIN_MutexLock PIN_MUTEX lock  ) 
 

Block the caller until the lock can be acquired.

Parameters:
[in] lock The lock variable.

BOOL LEVEL_BASE::PIN_MutexTryLock PIN_MUTEX lock  ) 
 

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

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

VOID LEVEL_BASE::PIN_MutexUnlock PIN_MUTEX lock  ) 
 

Release the lock.

Parameters:
[in] lock The lock variable.

INT32 LEVEL_BASE::PIN_ReleaseLock PIN_LOCK *  lock  ) 
 

Release the lock.

Parameters:
[in] lock The 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.

VOID LEVEL_BASE::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] lock The lock variable.

BOOL LEVEL_BASE::PIN_RWMutexInit PIN_RWMUTEX lock  ) 
 

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

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

VOID LEVEL_BASE::PIN_RWMutexReadLock PIN_RWMUTEX lock  ) 
 

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

Parameters:
[in] lock The lock variable.

BOOL LEVEL_BASE::PIN_RWMutexTryReadLock PIN_RWMUTEX lock  ) 
 

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

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

BOOL LEVEL_BASE::PIN_RWMutexTryWriteLock PIN_RWMUTEX lock  ) 
 

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

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

VOID LEVEL_BASE::PIN_RWMutexUnlock PIN_RWMUTEX lock  ) 
 

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

Parameters:
[in] lock The lock variable.

VOID LEVEL_BASE::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] lock The lock variable.

VOID LEVEL_BASE::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] sem The semaphore variable.

VOID LEVEL_BASE::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] sem The semaphore variable.

BOOL LEVEL_BASE::PIN_SemaphoreInit PIN_SEMAPHORE sem  ) 
 

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

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

BOOL LEVEL_BASE::PIN_SemaphoreIsSet PIN_SEMAPHORE sem  ) 
 

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

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

VOID LEVEL_BASE::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] sem The semaphore variable.

BOOL LEVEL_BASE::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] sem The semaphore variable.
[in] timeout The timeout period (milliseconds).
Returns:
TRUE if the semaphore's state is "set", FALSE if this method returns due to the timeout.

VOID LEVEL_BASE::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] sem The semaphore variable.


Generated on Sun Jan 28 23:35:38 2018 for Pin by  doxygen 1.4.6