Affects: Server-7.1   —   Status: Un-Assigned

This description arises from a discussion on dev-public, thread    
"Re: TODO: Jan, please implement SHOW LOCKS" in January 2005.
[mysql internal address]/secure/mailarchive/mail.php?folder=5&mail=31862
At the time we expected that InnoDB would act on lock display soon,
and we would have liked to agree on a common general idea for all
storage engines. Now (December 2008) we seem to have failed in the
original objective, but we still can propose what the server should have.
So here's an editable document.


Locks are just another type of event, so they'll be in
EVENTS_WAITS_CURRENT and all histories or summaries.
Phylum:    Instrument
Class:     Wait
Order      Synchronization Object  /* abbreviated 'Synch' */
Family     Lock

Example: 'Wait/Synch/Lock/Row-Exclusive/InnoDB'.

That would be the end of this task description, if it weren't
for the fact that people also want to know what's blocking what.


LOCKS is a single (noticeably un-normalized) table with one row for    
each lock that is "current" on a database, tablespace, table, or row.
In theory, a new lock is inserted when a request is made, updated when
a request changes (e.g. a shared lock becomes exclusive or status changes
to granted), deleted when lock is released (e.g. at end of transaction).
Values come from the storage engine or the performance schema instruments.

WL#2360 says:
"Values in PERFORMANCE_SCHEMA tables are non-deterministic,
non-consistent, non-repeatable. PERFORMANCE_SCHEMA tables cannot be locked,
indexed, or backed up. Selections on PERFORMANCE_SCHEMA tables should not
be cached."
That is true for PERFORMANCE_SCHEMA.LOCKS too.

WL#2360 also says:
"Every user has SELECT privilege for all PERFORMANCE_SCHEMA tables, and no other
privilege." That is true for PERFORMANCE_SCHEMA.LOCKS too. There is no
requirement for a SUPER privilege or a PROCESS privilege.
We'll try to use the same table for all storage engines. That means    
that we can't guarantee that it's up to date or consistent, and it means    
that some columns will be always NULL since they're not applicable.

Other DBMSs might include locks of internal spaces (e.g. the sequence number    
instance) in tables like this. But we'd expect to control such things
with a mutex. Mutexes aren't part of this task. See later section "Mutexes".



Name                       Comments    
----                       --------

/* The object_xxxx fields are whatever is necessary to identify    
   an object. "Resource" is a better word but events_waits_current
   already has object_schema, object_name, object_type, object_instance_begin.
   Often some of the object_xxxx fields will be blank (NULL).
   The data type is always VARCHAR(64) CHARACTER SET UTF8,
   but if a storage engine has a numeric identifier for an object,    
   that's fine, we will show it as decimal with no zerofill. */    
object_schema              Ordinarily this will have a database name.
object_name                A table name, a routine name, a file name, or
                           some other resource identifier.
                           If one can lock all objects of a given type,
                           this will be a wildcard. 
                           INNODB_LOCKS has: lock_table, lock_index.
object_type                INNODB.LOCKS_TYPE has: 'RECORD', 'TABLE'.
                           We prefer the term 'row', and we expect there
                           will be more possibilities with more storage
                           engines and future considerations. So our list is:
                           DATABASE, TABLESPACE, TABLE, ROW, INDEX, INDEX KEY,
                           FILE, SEQUENCE, ROUTINE, BLOCK.
object_instance_begin      The identifier of the lock. It's not enough to
                           identify a lock by object_name. We might
                           have a sequence number from a storage engine here,
                           or we might have a memory address.
                           INNODB_LOCKS has: lock_id.
location                   This is NULL except for rows, index keys, or blocks.
                           This has a location within a table / tablespace.
                           It might be a partial row primary key value,
                           a ROWID, a block number plus a record number within
                           the block (INNODB_LOCKS has lock_space, lock_page,
                           lock_rec). Usually it's numeric.
                           This might have the beginning of a range, but we do
                           not have a way to show the end of a range.

/* The transaction_xxxx_id columns have whatever is necessary to identify    
   a transaction. Again, depending on circumstances, some of these may    
   be blank (NULL). In a more normalized structure, we'd probably want    
   to have a single ID and use it to look up the other information.    
   These are always INTEGER fields. */    
transaction_process_id    Corresponds to "SHOW PROCESSLIST" number    
transaction_thread_id     Corresponds to events_waits_current.thread_id    
transaction_serial_id     Corresponds to InnoDB "trx id"

/* The transaction_xxxx_id columns show "who requested the lock".
   The blocking_transaction_xxxx_id columns show "who currently has the
   lock (and is therefore blocking)".
   But the "who is blocking" question is tough. See later discussion. */    
blocking_transaction_process_id  Who is blocking.
blocking_transaction_thread_id   Who is blocking.
blocking_transaction_serial_id   Who is blocking.
                                 INNODB_LOCKS has: lock_trx_id.

blocking_object_instance_id      The lock that we're waiting for.
                                 This should point to another row in
                                 performance_schema.locks, with a status of
                                 "Granted", and with the same resource_xxxx_id
                                 columns. Sometimes we're trying to get a
                                 row lock and we're waiting for a table lock,
                                 so the resource_xxxx_id columns will differ.
                                 Sometimes we're trying to get an exclusive
                                 lock and we're blocked by several transactions
                                 that have a shared lock, so this column might
                                 only be showing one of many 'blocking' rows.  

request_mode              CHAR. Use the same abbreviations as in
                          INNODB_LOCKS.LOCK_MODE but allow other common
                          abbreviations for other possible storage engines.
                          'X' exclusive
                          'X.GAP' exclusive on gap between keys
                          'AUTO_INC' exclusive on sequence
                          'IX' intent exclusive
                          'IS' intent shared
                          'IS.GAP' intent shared on gap between keys
                          'IU' intent update
                          'S' shared
                          'S.GAP' shared on gap between keys
                          'U' update
                          The "mode that you request the lock" may differ from
                          the "mode that you hold the lock", but we show only

request_status            CHAR or ENUM
                          'GRANTED' request was successful
                          'UPGRADE' e.g. converting from shared to exclusive 
                          'WAIT' request is entered, probably blocked
                          'ESCALATE' maybe use this for granularity change
                          'FAIL' deadlock, timeout, table full

request_count             If request_status='granted', the value here    
                          is the number of other transactions which are    
                          waiting for this lock to be released. Might be    
                          just a binary value ("is blocking (yes/no)?").    
                          In WL#321 "SHOW LOCK QUEUE" the column name is
                          We do not list the waiting transactions, and we do
                          not list the waiting lock requests, that would be
                          hard. Maybe 'waiting_count' would be a better name.

storage_engine            CHAR. Typically this is 'INNODB'.
                          This is NULL when no storage engine is involved.
                          The storage engine might also be in EVENT_NAME.

/* These further columns exist in events_waits_current. */
event_name                E.g. 'Wait/Synch/Lock/Row-Exclusive/InnoDB'
timer_start               When lock was requested.
                          Doesn't appear in our model DBMSs.
                          Data type might be TIMESTAMP.
timer_end                 When lock was granted, or when it failed.
timer_wait                This is either "timer_end - timer_start"
                          or "current_time - timer_start" in pseudo-picoseconds.

/* These further columns exist in Robin Schumacher's 'syslocks' request.
   Technically user name and user host are unnecessary, because we can
   look up them up via thread_id. But we don't want to force users to
   do subqueries and joins every time, so if they always need these
   columns, they should get them. */

Perhaps a way to think of a LOCKS table is as a join of
EVENTS_WAITS_HISTORY wait/synch/lock rows from different threads, where
thread-1.object_name,object-location = thread-2.object-name,object-location
and event_name like 'wait/synch/lock%'.

Additional columns in Event Summaries

Since locks are events, we have all the summary information
that we have for all events. For example:

    EVENT_NAME: wait/synch/lock/sql/table
SUM_TIMER_WAIT: 31412802980
AVG_TIMER_WAIT: 3926600372
MAX_TIMER_WAIT: 24824640490

But we want a breakdown by result -- what happened to those 8 requests?
Therefore we'd have more columns. For example:
COUNT_STAR_ESCALATED   2              /* DB2 name = lock_escals */

We must add these columns to EVENTS_WAITS_SUMMARY tables,
so a description is necessary in WL#4816 PERFORMANCE_SCHEMA Summaries.
They will always be NULL for non-lock events.
There is no need for separate LOCKS_SUMMARY views of these tables. 

Two more possible columns are "high water marks", that is,
counters for the maximum events that were ever happening simultaneously.
HIGH_WATER_MARK_REQUESTED /* How many were ever active at the same time */
HIGH_WATER_MARK_WAITED    /* How many of the above were blocked */
You can get the figures by counting rows in PERFORMANCE_SCHEMA.LOCKS.
Although this is good for calculating resource usage, and perhaps for
deciding how much memory to allocate for some lock tables, it is not
really monitoring. We won't have high water marks.

Deadlock counting suggestions should go to WL#4689 Deadlock Monitor.

Source of Information

Often we can expect that the storage engine has an internal lock list
so the easiest way to get information is by querying the
storage engine directly. That would mean changing storage-engine API.

Alternatively there might be tables specific to the storage engine
that we can read in order to populate PERFORMANCE_SCHEMA.LOCKS.
For example, the InnoDB plugin supplies, in information_schema:
If the plugin is unavailable one can struggle with SHOW ENGINE INNODB STATUS.

Alternatively the performance schema instruments will give us
* "who is blocked" and "what the last lock request was"
* "how many times a table was locked, and for how long, and current status"
  See WL#4816 HLS text after the words "[ OBJECT SUMMARIES ]"
* "locking events in the history"
* "summary of locks by thread or globally"

But PERFORMANCE_SCHEMA "history" tables are fixed size, so even a
long history might not have every row lock. Perhaps we should
have a count of row locks in the "object summaries" table, that is,
you could find out that thread x has y row locks on table z. Perhaps
we should have the last ten granted row locks in the "object summaries"
table, that is, you could find out the rows that thread x has on table
z, but only ten of them. With a combination of "long history" plus
"count of row locks by table" plus "last 10 row locks on table" you
probably can answer the important question "who is blocking". How
probably? Peter thinks: if it's 90% that's not as good as what the
the storage engine's own table has, but it would be universal, and
we could test in a real installation to see if it would be adequate.

So MySQL populates PERFORMANCE_SCHEMA.LOCKS in different ways for
different storage engines, depending whether we instrument the
storage engine code, and depending whether the storage engine
exposes information from its own internal tables. What the user
sees should be consistent, though -- MySQL must try to make the
information look the same, and be in one table.

SHOW Syntax

The original (January 2005) request was for a new SHOW statement.
Perhaps this requirement is now superseded. We only need the tables.
But the specification of "SHOW Syntax" remains in case somebody likes it.

[LIKE 'tablename']    
[LIMIT number_of_locks_to_print]    
WHERE engine='InnoDB'                /* later, 'engine='MyISAM' etc. */    
[AND resource_object_id='something']    
[LIMIT number_of_locks_to_print]    
Some comments (from the discussion thread)    
Nowadays MySQL warns that SHOW INNODB STATUS is deprecated syntax    
and users should use SHOW ENGINE INNODB STATUS instead. Peter expects    
that this is analogous.    

Since MySQL has LIKE 'pattern' for other SHOW statements, e.g.    
SHOW STATUS [LIKE 'pattern'], Peter believes users will expect to see    
"LIKE 'tablename'" rather than "tablename".    

And Peter believes "LIMIT number_of_locks_to_print", rather than    
"number_of_locks_to_print", might help avoid a parsing problem later    
if we add a new clause before number_of_locks_to_print. Specifically,    
he worries that someone will want to have    



Originally this specification included mutexes.
Now it doesn't.

There is a similarity. We could be showing mutexes and
filling in these columns of PERFORMANCE_SCHEMA.LOCKS:
object_name = event_name, or part of event_name
object_type = 'MUTEX'
object_instance_begin = address
request_mode = 'X' (mutex locking is always exclusive)
request_status = 'WAIT' or 'GRANTED'
request_count = how many others are blocked

Currently one can get some information per mutex
with MUTEX_INSTANCES, for example:
NAME: wait/synch/mutex/sql/LOG::LOCK_log

Or one could have a separate table which lists
only the holders of currently-held mutexes.
In that case, it's simply a list of copies of
EVENTS_WAITS_CURRENT mutex rows which don't
disappear until the mutex is unlocked.

Other lock situations to consider are: GET_LOCKS, FLUSH TABLES WITH READ LOCK,
metadata locks.

Other worklog entries    

In the past, there have been other suggestions for MySQL lock display:    
"SHOW TABLE LOCKS [FROM (db|table)] [FOR user];" (WL#320, Jeremy Cole)    
"SHOW LOCK QUEUE [FROM (db|table)]" (WL#321, Jeremy Cole)    
"SHOW FULL PROCESSLIST" (WL#1275, Mark Matthews)    
These are raw-idea-bin suggestions, and Peter thinks we can ignore them.    
(Sergei Golubchik, on the other hand, thinks we should consider them.)    
And there is a task in the benchmarks queue:   
WL#2288 Patch Innodb-code to add status variable to show number of row locks   

Some of the "mysqladmin debug" code might be worth looking at.

Falcon has WL#3765 Falcon Diagnostics.


BUG#23076 No way of viewing locks from within the server (Mark Leith)

MySQL 5.6 Reference manual re INNODB_LOCKS table

"MySQL Internals: SHOW LOCKS or equivalent"

Harrison Fisk's patch
[mysql internal address]/secure/mailarchive/mail.php?folder=4&mail=24248

BUG#33601 adding a view for information_schema to identify lock waiting
relations (another patch)

BUG#46391 No statistics are displayed for named locks from GET_LOCK() etc.

A table [performance_schema] locks is mentioned in the WL#2360 file attachment
[mysql internal address]/worklog/download/performance.txt?fid=400

Some more private references are visible by clicking on the 'Progress'
for 2009-04-13, to see what was deleted from 'References' on this date.