Home Libraries Author Links

Abstract Data Type StmAccessLock
[AccessLock: Access Control of Thread Resources]

Collaboration diagram for Abstract Data Type StmAccessLock:

Detailed Description

A valid StmAccessLock object manages the access to resources concurrently used by several StmThread objects.

AccessLock.

The read access to such a resource protected by a StmAccessLock object is granted by StmReadOnlyTicket objects whereas the read/write access is granted by a StmReadWriteTicket object.

StmReadOnlyTicket objects can be obtained by an arbitrary number of threads as long as no write access is pending. A StmReadWriteTicket object can be obtained by at most one thread provided no read access is pending.

Valid objects of type StmAccessLock can be achieved only as return values of stmAccessLockCreate(). Moreover, variables of type StmAccessLock may have the value NULL meaning invalid or undefined.


Files

file  StmAccessLockAdtDoc.h
 Documentation of the abstract structure data type type StmAccessLock.

Modules

 Abstract Data Type StmReadOnlyTicket
 A valid StmReadOnlyTicket grants read only access to a resource protected by a valid StmAccessLock object.
 Abstract Data Type StmReadWriteTicket
 A valid StmReadWriteTicket grants read and write access to a resource protected by a valid StmAccessLock object.

StmAccessLock Representation

An object of abstract data type StmAccessLock is represented as a pointer to its implementation.

typedef struct StmAccessLockImpl_ StmAccessLockImpl_
 Type name of implementation structure.
typedef StmAccessLockImpl_ * StmAccessLock
 Pointer to implementation.
typedef const StmAccessLockImpl_ * ConstStmAccessLock
 Pointer to constant implementation.

StmAccessLock Creation and Destruction

StmAccessLock stmAccessLockCreate (void)
 Creation of a new StmAccessLock object.
int stmAccessLockDestroy (StmAccessLock lock)
 Destruction of the StmAccessLock object lock.

StmAccessLock Method Functions

StmReadOnlyTicket stmAccessLockTakeReadOnly (StmAccessLock lock)
 Return a StmReadOnlyTicket object granting read access for the resource protected by the StmAccessLock object lock.
StmReadOnlyTicket stmAccessLockTryReadOnly (StmAccessLock lock)
 Try to return a StmReadOnlyTicket object granting read access for the resource protected by the StmAccessLock object lock.
StmReadWriteTicket stmAccessLockConvertReadOnly (StmAccessLock lock, StmReadOnlyTicket ticket)
 Convert the StmReadOnlyTicket object ticket granting read access to the resource protected by the StmAccessLock object lock to a StmReadWriteTicket object granting write access to the resource and return it.
int stmAccessLockGiveReadOnly (StmAccessLock lock, StmReadOnlyTicket ticket)
 Release the StmReadOnlyTicket object ticket granting read access to the resource protected by the StmAccessLock object lock.
StmReadWriteTicket stmAccessLockTakeReadWrite (StmAccessLock lock)
 Return a StmReadWriteTicket object granting write access for the resource protected by the StmAccessLock object lock.
StmReadWriteTicket stmAccessLockTryReadWrite (StmAccessLock lock)
 Try to return a StmReadWriteTicket object granting write access for the resource protected by the StmAccessLock object lock.
StmReadOnlyTicket stmAccessLockConvertReadWrite (StmAccessLock lock, StmReadWriteTicket ticket)
 Convert the StmReadWriteTicket object ticket granting write access to the resource protected by the StmAccessLock object lock to a StmReadOnlyTicket object granting read access to the resource and return it.
int stmAccessLockGiveReadWrite (StmAccessLock lock, StmReadWriteTicket ticket)
 Release the StmReadWriteTicket object ticket granting write access to the resource protected by the StmAccessLock object lock.

Typedef Documentation

typedef struct StmAccessLockImpl_ StmAccessLockImpl_

Type name of implementation structure.

Definition at line 60 of file StmAccessLockAdtDoc.h.

typedef StmAccessLockImpl_* StmAccessLock

Pointer to implementation.

Definition at line 63 of file StmAccessLockAdtDoc.h.

typedef const StmAccessLockImpl_* ConstStmAccessLock

Pointer to constant implementation.

Definition at line 66 of file StmAccessLockAdtDoc.h.

Function Documentation

StmAccessLock stmAccessLockCreate ( void   ) 

Creation of a new StmAccessLock object.

Effects:
The function creates a StmAccessLock object. This object has to be used as argument of the other StmAccessLock functions.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmAccessLock object created on success.

See also:
stmAccessLockDestroy().

int stmAccessLockDestroy ( StmAccessLock  lock  ) 

Destruction of the StmAccessLock object lock.

Parameters:
[in] lock The StmAccessLock object to be destroyed.
Effects:
The function destroys the StmAccessLock object lock. It is no error to call the function for a StmAccessLock object with value NULL in which case the function does nothing.
Returns:
-1 on error. Then the variable errno contains the error's cause.

0 on success.

See also:
stmAccessLockCreate().

StmReadOnlyTicket stmAccessLockTakeReadOnly ( StmAccessLock  lock  ) 

Return a StmReadOnlyTicket object granting read access for the resource protected by the StmAccessLock object lock.

Parameters:
[in] lock The StmAccessLock object.
Effects:
If the function succeeds, the calling thread obtains read access to the resource protected by lock. If the resource is locked by a write access of another thread and/or if write accesses of other threads are pending, the calling thread is blocked until those accesses are finished.
Returns:
A valid StmReadOnlyTicket object granting read access to the resource protected by lock on success.

NULL on error. Then the variable errno is set to EINVAL, if lock is invalid, or to EBUSY, if the calling thread also holds a write lock.

StmReadOnlyTicket stmAccessLockTryReadOnly ( StmAccessLock  lock  ) 

Try to return a StmReadOnlyTicket object granting read access for the resource protected by the StmAccessLock object lock.

Parameters:
[in] lock The StmAccessLock object.
Effects:
If the resource protected by lock is not locked by a write access of another thread and if no write accesses of other threads are pending, the calling thread obtains read access to the resource and the function succeeds.
Returns:
A valid StmReadOnlyTicket object granting read access on success.

NULL on error. Then the variable errno is set to EINVAL, if lock is invalid, to EAGAIN, if the resource is locked by a write access of another thread and/or if write accesses of other threads are pending, or to EBUSY, if the calling thread also holds a write lock.

StmReadWriteTicket stmAccessLockConvertReadOnly ( StmAccessLock  lock,
StmReadOnlyTicket  ticket 
)

Convert the StmReadOnlyTicket object ticket granting read access to the resource protected by the StmAccessLock object lock to a StmReadWriteTicket object granting write access to the resource and return it.

Parameters:
[in] lock The StmAccessLock object.
[in] ticket The StmReadOnlyTicket object to be converted.
Effects:
The calling thread revokes the read access legitimated by the valid StmReadOnlyTicket object ticket thus invalidating ticket and rather obtains write access to the resource protected by lock. If that resource is also locked by read accesses of other threads and/or if write accesses of other threads are pending, the calling thread is blocked until those accesses are finished. Therefore it is not guaranteed that when obtaining the write access, the resource is in the same state as it was at the time of revoking the read access, since in between write accesses of other threads could have been served.
Returns:
A valid StmReadWriteTicket object granting write access on success.

NULL on error. Then the variable errno is set to EINVAL, if lock is invalid, to EPERM, if ticket is invalid, or to EBUSY, if the calling thread held more than one read access.

int stmAccessLockGiveReadOnly ( StmAccessLock  lock,
StmReadOnlyTicket  ticket 
)

Release the StmReadOnlyTicket object ticket granting read access to the resource protected by the StmAccessLock object lock.

Parameters:
[in] lock The StmAccessLock object.
[in] ticket The StmReadOnlyTicket object to be released.
Effects:
The calling thread revokes the read access legitimated by the valid StmReadOnlyTicket object ticket thus invalidating ticket.
Returns:
0 on success.

-1 on error. Then the variable errno is set to EINVAL, if lock is invalid or to EPERM, if ticket is invalid.

StmReadWriteTicket stmAccessLockTakeReadWrite ( StmAccessLock  lock  ) 

Return a StmReadWriteTicket object granting write access for the resource protected by the StmAccessLock object lock.

Parameters:
[in] lock The StmAccessLock object.
Effects:
If the function succeeds, the calling thread obtains write access to the resource protected by lock. If the resource is locked by a write access of another thread and/or by read accesses of other threads, the calling thread is blocked until those accesses are finished.
Returns:
A valid StmReadWriteTicket object granting write access to the resource protected by lock on success.

NULL on error. Then the variable errno is set to EINVAL, if lock is invalid, or to EBUSY, if the calling thread also holds a read lock.

StmReadWriteTicket stmAccessLockTryReadWrite ( StmAccessLock  lock  ) 

Try to return a StmReadWriteTicket object granting write access for the resource protected by the StmAccessLock object lock.

Parameters:
[in] lock The StmAccessLock object.
Effects:
If the resource protected by lock is not locked by a write access of another thread or by read accesses of other threads, the calling thread obtains write access to the resource and the function succeeds.
Returns:
A valid StmReadWriteTicket object granting write access on success.

NULL on error. Then the variable errno is set to EINVAL, if lock is invalid, to EAGAIN, if the resource is locked by a write access of another thread or by read accesses of other threads, or to EBUSY, if the calling thread also holds a read lock.

StmReadOnlyTicket stmAccessLockConvertReadWrite ( StmAccessLock  lock,
StmReadWriteTicket  ticket 
)

Convert the StmReadWriteTicket object ticket granting write access to the resource protected by the StmAccessLock object lock to a StmReadOnlyTicket object granting read access to the resource and return it.

Parameters:
[in] lock The StmAccessLock object.
[in] ticket The StmReadWriteTicket object to be converted.
Effects:
The calling thread revokes the write access legitimated by the valid StmReadWriteTicket object ticket thus invalidating ticket and rather obtains read only access to the resource protected by lock. It is not guaranteed that when obtaining the read access, the resource is in the same state as it was at the time of revoking the write access, since in between write accesses of other threads could have been served.
Returns:
A valid StmReadOnlyTicket object granting read access on success.

NULL on error. Then the variable errno is set to EINVAL, if lock is invalid, to EPERM, if ticket is invalid, or to EBUSY, if the calling thread held more than one write access.

int stmAccessLockGiveReadWrite ( StmAccessLock  lock,
StmReadWriteTicket  ticket 
)

Release the StmReadWriteTicket object ticket granting write access to the resource protected by the StmAccessLock object lock.

Parameters:
[in] lock The StmAccessLock object.
[in] ticket The StmReadWriteTicket object to be released.
Effects:
The calling thread revokes the write access legitimated by the valid StmReadWriteTicket object ticket thus invalidating ticket.
Returns:
0 on success.

-1 on error. Then the variable errno is set to EINVAL, if lock is invalid or to EPERM, if ticket is invalid.

© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).