diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 224b9005dec..3c956ad8eb3 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-
+
Functions and Operators
@@ -10577,15 +10577,205 @@ postgres=# select * from pg_xlogfile_name_offset(pg_stop_backup());
pg_stat_file returns a record containing the file
- size, last accessed time stamp, last modified time stamp,
- last file status change time stamp (Unix platforms only),
- file creation timestamp (Windows only), and a boolean indicating
- if it is a directory. Typical usages include:
+ size, last accessed time stamp, last modified time stamp,
+ last file status change time stamp (Unix platforms only),
+ file creation timestamp (Windows only), and a boolean
+ indicating if it is a directory. Typical usages include:
SELECT * FROM pg_stat_file('filename');
SELECT (pg_stat_file('filename')).modification;
+
+ The functions shown in manage
+ advisory locks. For details about proper usage of these functions, see
+ .
+
+
+
+ Advisory Lock Functions
+
+
+ Name Return Type Description
+
+
+
+
+
+
+ pg_advisory_lock(key bigint)
+
+ void
+ Obtain exclusive advisory lock
+
+
+
+ pg_advisory_lock(key1 int, key2 int)
+
+ void
+ Obtain exclusive advisory lock
+
+
+
+
+ pg_advisory_lock_shared(key bigint)
+
+ void
+ Obtain shared advisory lock
+
+
+
+ pg_advisory_lock_shared(key1 int, key2 int)
+
+ void
+ Obtain shared advisory lock
+
+
+
+
+ pg_try_advisory_lock(key bigint)
+
+ boolean
+ Obtain exclusive advisory lock if available
+
+
+
+ pg_try_advisory_lock(key1 int, key2 int)
+
+ boolean
+ Obtain exclusive advisory lock if available
+
+
+
+
+ pg_try_advisory_lock_shared(key bigint)
+
+ boolean
+ Obtain shared advisory lock if available
+
+
+
+ pg_try_advisory_lock_shared(key1 int, key2 int)
+
+ boolean
+ Obtain shared advisory lock if available
+
+
+
+
+ pg_advisory_unlock(key bigint)
+
+ boolean
+ Release an exclusive advisory lock
+
+
+
+ pg_advisory_unlock(key1 int, key2 int)
+
+ boolean
+ Release an exclusive advisory lock
+
+
+
+
+ pg_advisory_unlock_shared(key bigint)
+
+ boolean
+ Release a shared advisory lock
+
+
+
+ pg_advisory_unlock_shared(key1 int, key2 int)
+
+ boolean
+ Release a shared advisory lock
+
+
+
+
+ pg_advisory_unlock_all()
+
+ void
+ Release all advisory locks held by the current session
+
+
+
+
+
+
+
+ pg_advisory_lock
+
+
+ pg_advisory_lock locks an application-defined resource,
+ which may be identified either by a single 64-bit key value or two
+ 32-bit key values (note that these two key spaces do not overlap). If
+ another session already holds a lock on the same resource, the
+ function will wait until the resource becomes available. The lock
+ is exclusive. Multiple lock requests stack, so that if the same resource
+ is locked three times it must be also unlocked three times to be
+ released for other sessions' use.
+
+
+
+ pg_advisory_lock_shared
+
+
+ pg_advisory_lock_shared works the same as
+ pg_advisory_lock,
+ except the lock can be shared with other sessions requesting shared locks.
+ Only would-be exclusive lockers are locked out.
+
+
+
+ pg_try_advisory_lock
+
+
+ pg_try_advisory_lock is similar to
+ pg_advisory_lock, except the function will not wait for the
+ lock to become available. It will either obtain the lock immediately and
+ return true, or return false if the lock cannot be
+ acquired now.
+
+
+
+ pg_try_advisory_lock_shared
+
+
+ pg_try_advisory_lock_shared works the same as
+ pg_try_advisory_lock, except it attempts to acquire
+ shared rather than exclusive lock.
+
+
+
+ pg_advisory_unlock
+
+
+ pg_advisory_unlock will release a previously-acquired
+ exclusive advisory lock. It
+ will return true if the lock is successfully released.
+ If the lock was in fact not held, it will return false,
+ and in addition, an SQL warning will be raised by the server.
+
+
+
+ pg_advisory_unlock_shared
+
+
+ pg_advisory_unlock_shared works the same as
+ pg_advisory_unlock,
+ except to release a shared advisory lock.
+
+
+
+ pg_advisory_unlock_all
+
+
+ pg_advisory_unlock_all will release all advisory locks
+ held by the current session. (This function is implicitly invoked
+ at session end, even if the client disconnects ungracefully.)
+
+
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 2dd3f993725..ef8675b3a4e 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1,4 +1,4 @@
-
+
Concurrency Control
@@ -25,10 +25,10 @@
- Unlike traditional database systems which use locks for concurrency control,
- PostgreSQL
- maintains data consistency by using a multiversion model
- (Multiversion Concurrency Control, MVCC).
+ PostgreSQL provides a rich set of tools
+ for developers to manage concurrent access to data. Internally,
+ data consistency is maintained by using a multiversion
+ model (Multiversion Concurrency Control, MVCC).
This means that while querying a database each transaction sees
a snapshot of data (a database version)
as it was some
@@ -36,7 +36,10 @@
This protects the transaction from viewing inconsistent data that
could be caused by (other) concurrent transaction updates on the same
data rows, providing transaction isolation
- for each database session.
+ for each database session. MVCC, by eschewing
+ explicit locking methodologies of traditional database systems,
+ minimizes lock contention in order to allow for reasonable
+ performance in multiuser environments.
@@ -52,7 +55,9 @@
PostgreSQL for applications that cannot
adapt easily to MVCC behavior. However, proper
use of MVCC will generally provide better
- performance than locks.
+ performance than locks. In addition, application-defined advisory
+ locks provide a mechanism for acquiring locks that are not tied
+ to a single transaction.
@@ -859,6 +864,83 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222;
(e.g., while waiting for user input).
+
+
+ Advisory Locks
+
+
+ lock
+ advisory
+
+
+
+ PostgreSQL provides a means for
+ creating locks that have application-defined meanings. These are
+ called advisory locks, because the system does not
+ enforce their use — it is up to the application to use them
+ correctly. Advisory locks can be useful for locking strategies
+ that are an awkward fit for the MVCC model. Once acquired, an
+ advisory lock is held until explicitly released or the session ends.
+ Unlike standard locks, advisory locks do not
+ honor transaction semantics. For example, a lock acquired during a
+ transaction that is later rolled back will still be held following the
+ rollback. The same lock can be acquired multiple times by its
+ owning process: for each lock request there must be a corresponding
+ unlock request before the lock is actually released. (If a session
+ already holds a given lock, additional requests will always succeed, even
+ if other sessions are awaiting the lock.) Like all locks in
+ PostgreSQL, a complete list of advisory
+ locks currently held by any session can be found in the system view
+ pg_locks.
+
+
+
+ Advisory locks are allocated out of a shared memory pool whose size
+ is defined by the configuration variables
+ and
+ .
+ Care must be taken not to exhaust this
+ memory or the server will not be able to grant any locks at all.
+ This imposes an upper limit on the number of advisory locks
+ grantable by the server, typically in the tens to hundreds of thousands
+ depending on how the server is configured.
+
+
+
+ A common use of advisory locks is to emulate pessimistic locking
+ strategies typical of so called flat file data management
+ systems.
+ While a flag stored in a table could be used for the same purpose,
+ advisory locks are faster, avoid MVCC bloat, and are automatically
+ cleaned up by the server at the end of the session.
+ In certain cases using this method, especially in queries
+ involving explicit ordering and LIMIT clauses, care must be
+ taken to control the locks acquired because of the order in which SQL
+ expressions are evaluated. For example:
+
+SELECT pg_advisory_lock(id) FROM foo WHERE id = 12345; -- ok
+SELECT pg_advisory_lock(id) FROM foo WHERE id > 12345 LIMIT 100; -- danger!
+SELECT pg_advisory_lock(q.id) FROM
+(
+ SELECT id FROM foo WHERE id > 12345 LIMIT 100;
+) q; -- ok
+
+ In the above queries, the second form is dangerous because the
+ LIMIT is not guaranteed to be applied before the locking
+ function is executed. This might cause some locks to be acquired
+ that the application was not expecting, and hence would fail to release
+ (until it ends the session).
+ From the point of view of the application, such locks
+ would be dangling, although still viewable in
+ pg_locks.
+
+
+
+ The functions provided to manipulate advisory locks are described in
+ .
+
+
+
@@ -993,12 +1075,12 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222;
- Short-term share/exclusive page-level locks are used for
- read/write access. Locks are released immediately after each
- index row is fetched or inserted. But note that a GIN-indexed
- value insertion usually produces several index key insertions
- per row, so GIN may do substantial work for a single value's
- insertion.
+ Short-term share/exclusive page-level locks are used for
+ read/write access. Locks are released immediately after each
+ index row is fetched or inserted. But note that a GIN-indexed
+ value insertion usually produces several index key insertions
+ per row, so GIN may do substantial work for a single value's
+ insertion.