saslock.h File Reference

Shared Address Space User Locks. Address based locking for shared address space blocks and utility objects. More...

Go to the source code of this file.

## Macros

#define | __C__
| ignore this macro behind the curtain

## Typedefs

typedef void * | vm_address_t
| Generic address to be used as symbolic lock ID.

## Enumerations

enum | sas_userlock_request_t { SasUserLock__READ , SasUserLock__WRITE }
| SAS Lock request types.

## Functions

__C__ void | SASLockReset (void)
| Reset the SAS Lock tables. More...
__C__ void | SASLockInit (void)
| Initialize the SAS Lock tables. More...
__C__ void | SASLock (vm_address_t addr, sas_userlock_request_t lockT)
| Lock a SAS Address. More...
__C__ void | SASUnlock (vm_address_t addr)
| UnLock a SAS Address. More...
__C__ void | SASLockPrintHighLevelStats (void)
| Print High level Lock Statistic.
__C__ void | SASLockPrintDetailedStats (void)
| Print detailed Lock Statistic.
__C__ void | SASLockDetach (void)
| Detach the shared memory segment holding the SAS lock tables. More...
__C__ void | SASLockRemove (void)
| Remove the shared memory segment holding the SAS lock tables. More...

## Variables

__C__ int | SasLockOwner
| Lock Segment Owner TRUE if this process was the first to run and created the lock segment. Other process discover the exixting lock segment and simply attach it.

## Detailed Description

Shared Address Space User Locks. Address based locking for shared address space blocks and utility objects.

!

SAS Locks are not stored within the SAS blocks, which would create recoverability issues at large scale. Instead locks are address symbolic with active locks maintained in hash tables in shared memory. The byte effective address of the data becomes the lock symbol. In SAS storage addresses are context free across all processes sharing a SAS region. This enables locking across all processes sharing a SAS region.

SAS Locks implements shared read locks and exclusive write locks. SAS locks are recursive within a thread.

Todo:
  In a future implementation the intent is to extend SAS Locks to support Write Intent locks. Intent Locks would allow the holder to gain a shared lock that can be upgraded to exclusive write lock later, if needed. A Intent lock allows current holders of read locks to continue, but prevents new read locks from being granted. New read locks are held (not granted) until the corresponding Intent Lock or upgraded Write Lock is released (unlockd).

Todo:
  Need a API to return the PIDs associated with held locks. This will be needed to recover from hung or crashed processes.

## Function Documentation

## SASLock()

__C__ void SASLock | ( | vm_address_t | addr,
|  | sas_userlock_request_t | lockT
| ) |  |

Lock a SAS Address.

    Lock an address for shared read or exclusive write access by this thread.

    @param addr Data address to be locked.
    @param lockT Lock (SasUserLock__READ, SasUserLock__WRITE) type.

## SASLockDetach()

__C__ void SASLockDetach | ( | void |  | ) |

Detach the shared memory segment holding the SAS lock tables.

    Used for cleanup, called from SASCleanup.

## SASLockInit()

__C__ void SASLockInit | ( | void |  | ) |

Initialize the SAS Lock tables.

    Initialize the lock tables when a SAS region is created or a process
    attaches to the SAS Region after the system is restarted.
    The first process creates a shared memory segment unique to the
    region and sets SasLockOwner TRUE. Otherwise the existenting shm
    segment is attached and SasLockOwner is FALSE.
    This shm segment will hold the shared lock tables that hold active
    symbolic locks.

## SASLockRemove()

__C__ void SASLockRemove | ( | void |  | ) |

Remove the shared memory segment holding the SAS lock tables.

    Used for cleanup, called from SASRemove.

## SASLockReset()

__C__ void SASLockReset | ( | void |  | ) |

Reset the SAS Lock tables.

    Reset the lock tables to the initialized state. Any held locks will
    be lost without resuming any waiters.

    \note This API is intended to recover from hung or crashed processes.

## SASUnlock()

__C__ void SASUnlock | ( | vm_address_t | addr | ) |

UnLock a SAS Address.

    Unlock a previously locked address held by this thread.

    @param addr Data address to be unlocked.