Package com.mckoi.database

## Class LockingMechanism

- java.lang.Object
- - com.mckoi.database.LockingMechanism

    public final class LockingMechanism
    extends java.lang.Object

This class represents a model for locking the tables in a database during any sequence of concurrent read/write accesses.

Every table in the database has an 'access_queue' that is generated the first time the table is accessed. When a read or write request happens, the thread and the type of access is put onto the top of the queue. When the read/write access to the table has completed, the access is removed from the queue.

An access to the table may be 'blocked' until other threads have completed their access of the table.

A table that has a 'read lock' can not be altered until the table object is released. A table that has a 'write lock' may not be read until the table object is released.

The general rules are: a) A read request can go ahead if there are no write request infront of this request in the access queue. b) A write request can go ahead if the write request is at the front of the access queue.

This class requires some for-sight to which tables will be read/written to. We must pass all tables being read/written in a single stage. This implies a 2 stage process, the 1st determining which tables are being accessed and the 2nd performing the actual operations.

Some operations such as creating and dropping and modifying the security tables may require that no threads interfere with the database state while the operation is occuring. This is handled through an 'Excluside Mode'. When an object calls the locking mechanism to switch into exclusive mode, it blocks until all access to the database are complete, then continues, blocking all other threads until the exclusive mode is cancelled.

The locking system, in simple terms, ensures that any multiple read operations will happen concurrently, however write operations block until all operations are complete.

SYNCHRONIZATION: This method implements some important concurrent models for ensuring that queries can never be corrupted.

Author:
  Tobias Downer

### Field Summary

Fields
`static int` `EXCLUSIVE_MODE`
`static int` `SHARED_MODE` Class statics.

### Constructor Summary

Constructors
`LockingMechanism​(DebugLogger logger)` Constructor.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `finishMode​(int mode)` This must be called when the calls to a Database object have finished.
`boolean` `isInExclusiveMode()` Returns true if we are locked into exclusive mode.
`LockHandle` `lockTables​(DataTable[] t_write, DataTable[] t_read)` This method locks the given tables for either reading or writing.
`void` `reset()` Resets this object so it may be reused.
`void` `setMode​(int mode)` This method _must_ be called before a threads initial access to a Database object.
`void` `unlockTables​(LockHandle handle)` Unlocks the tables that were previously locked by the 'lockTables' method.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### SHARED_MODE

    public static final int SHARED_MODE

Class statics. These are used in the 'setMode' method to request either shared or exclusive access to the database.

See Also:
  Constant Field Values

#### EXCLUSIVE_MODE

    public static final int EXCLUSIVE_MODE

See Also:
  Constant Field Values

### Constructor Detail

#### LockingMechanism

    public LockingMechanism​(DebugLogger logger)

Constructor.

### Method Detail

#### reset

    public void reset()

Resets this object so it may be reused. This will release all internal DataTable queues that are being kept.

#### lockTables

    public LockHandle lockTables​(DataTable[] t_write,
                                 DataTable[] t_read)

This method locks the given tables for either reading or writing. It puts the access locks in a queue for the given tables. This 'reserves' the rights for this thread to access the table in that way. This reservation can be used by the system to decide table accessability.

NOTE: ** IMPORTANT ** We must ensure that a single Thread can not create multiple table locks. Otherwise it will cause situations where deadlock can result. NOTE: ** IMPORTANT ** We must ensure that once a lock has occured, it is unlocked at a later time _no matter what happens_. Otherwise there will be situations where deadlock can result. NOTE: A LockHandle should not be given to another Thread.

SYNCHRONIZATION: This method is synchronized to ensure multiple additions to the locking queues can happen without interference.

#### unlockTables

    public void unlockTables​(LockHandle handle)

Unlocks the tables that were previously locked by the 'lockTables' method. It is required that this method is called after the table references made by a query are released (set to null or forgotten). This usually means _after_ the result set has been written to the client. SYNCHRONIZATION: This method is synchronized so concurrent unlocking can not corrupt the queues.

#### isInExclusiveMode

    public boolean isInExclusiveMode()

Returns true if we are locked into exclusive mode.

#### setMode

    public void setMode​(int mode)

This method _must_ be called before a threads initial access to a Database object. It registers whether the preceding database accesses will be in an 'exclusive mode' or a 'shared mode'. In shared mode, any number of threads are able to access the database. In exclusive, the current thread may be the only one that may access the database. On requesting exclusive mode, it blocks until exclusive mode is available. On requesting shared mode, it blocks only if currently in exclusive mode. NOTE: 'exclusive mode' should be used only in system maintenance type operations such as creating and dropping tables from the database.

#### finishMode

    public void finishMode​(int mode)

This must be called when the calls to a Database object have finished. It 'finishes' the mode that the locking mechanism was set into by the call to the 'setMode' method. NOTE: ** IMPORTANT ** This method __MUST__ be guarenteed to be called some time after the 'setMode' method. Otherwise deadlock.