shsql: table locking

SQL database system
| Manual page for table(locking)

## Table write and table read locking

shsql provides table write locking and table read locking, which are described below. shsql also provides record locking which is somewhat different in that it is under programmer control; it is discussed on its own manual page.``

All types of shsql locking are "advisory", meaning that they are a convention that "obedient" processes adhere to. Any process that uses the shsql API for database access is "obedient". For example, if a shsql process gets a write-lock on a table, another shsql process will respect this and refrain from writing to the table, but other non-shsql processes will not be prevented (eg. by the operating system) from writing.``

## Write locking

In order to insure that only one shsql process can update a certain table at any one point in time, table "write-locking" is done. During normal operation tables are write-locked only for the short amount of time that it takes to actually write the update to the table. However, certain activities such as table cleaning / index rebuild and manual editing of data files cause tables to be write-locked for longer periods of time.``

A shsql process may write-lock no more than one data file at a time.``

There are no restrictions on reading from a write-locked table.``

Write locks are obtained by opening a file in the `locks` directory called tablename`.wlock` and then using fcntl(2) to gain exclusive access to that file. To release the lock, exclusive access is released via fcntl(2).`` The file generally remains, but if removed, the next process to issue a write lock will create a new one.``

When one process wants to update a data file and finds it write-locked, it retries several times. After some number of failed tries the attempt is aborted with an error (error code# 9).``

## Read locking

During some administrative activities that radically modify a data file, such as table cleaning / index rebuild, manual editing, or use of the ALTER command, table "read-locking" is done, to prevent all shsql processes from accessing invalid data. Since all of these activities work in a separate temp file copy, the read lock is only held for the brief time that it takes to replace the original data file with the modified copy.``

When a process wants to read from a data file and finds it read-locked by someone else, it waits (indefinitely) until the readlock file is gone, at which time it resumes.`` Thus, holders of read locks must minimize the time that any one table is tied up, and if a read-locking activity seems to end abnormally, make sure that the `.readlock` file is removed.``

A read lock is obtained by creating a file in the data directory called tablename`.readlock`. This is followed by a short wait to allow any in-progress reads to finish.`` The read lock is released by removing the file. shsql programs that need to set a read-lock will exit without doing anything if a readlock file already exists for the table of interest.``
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` April 30, 2004.