------------------------------------------------------------
revno: 2617.69.32
committer: Dmitry Lenev <dlenev@mysql.com>
branch nick: mysql-next-bg46747
timestamp: Wed 2009-08-19 18:12:27 +0400
message:
Fix for bug #46747 "Crash in MDL_ticket::upgrade_shared_lock_to_exclusive
on TRIGGER + TEMP table".
Server crashed when one tried to drop trigger which had its subject
table shadowed by a temporary table with the same name.
This problem occured because in such situation DROP TRIGGER has opened
temporary table instead of base table on which trigger was defined.
Attempt to upgrade metadata lock on this temporary table led to crash
(we don't acquire metadata locks for temporary tables).
This fix ensures that DROP TRIGGER ignores temporary tables when
trying to open table on which trigger to be dropped is defined.
revno: 2617.69.33
committer: Konstantin Osipov <kostja@sun.com>
branch nick: mysql-next-46452
timestamp: Wed 2009-08-19 18:39:31 +0400
message:
Bug#46452 "Crash in MDL, HANDLER OPEN + TRUNCATE TABLE".
Flush open HANDLER tables before TRUNCATE, which is a DDL.
----------------------------------------------------------
revno: 2617.69.28
committer: Konstantin Osipov <kostja@sun.com>
branch nick: 5.4-azalea-bugfixing
timestamp: Tue 2009-08-18 15:27:35 +0400
message:
An attempt to fix a link failure on Windows -- Sroutine_hash_entry
is forward-declared as class.
(Part of WL#4284).
----------------------------------------------------------
revno: 2617.69.25
committer: Konstantin Osipov <kostja@sun.com>
branch nick: 5.4-42546
timestamp: Fri 2009-08-14 23:52:00 +0400
message:
A cleanup in open_tables() and lock_tables():
change return type of these functions to bool from int,
to follow convention in the rest of the code.
(Part of WL#4284 review fixes).
A pre-requisite patch for Bug#30977 "Concurrent statement using
stored function and DROP FUNCTION breaks SBR".
This patch changes the MDL API by introducing a namespace for
lock keys: MDL_TABLE for tables and views and MDL_PROCEDURE
for stored procedures and functions. The latter is needed for
the fix for Bug#30977.
Bug #42074 concurrent optimize table and
alter table = Assertion failed: thd->is_error()
This assertion could occur if OPTIMIZE TABLE was started on a InnoDB table
and the table was altered to different storage engine after OPTIMIZE
had started. This allowed OPTIMIZE to pass the initial checks for
storage engine support, but fail once it reached "recreate+analyze"
if this operation was not supported by the new storage engine.
The bug had no consequences for non-debug builds of the server.
In detail, the assertion was triggered when ha_analyze() returned
HA_ADMIN_NOT_IMPLEMENTED. This led to a code path which included an
assert checking for diagnostics area contents. Since this area had
not been filled, the assertion was triggered. The diagnostics area
is in this case only used to provide more detailed information about
why optimize failed. The triggered code path sends this information
to the client and clears the diagnostic area.
This patch fixed the problem by adding an error message to the diagnostic
area if ha_analyze() fails. This error message contains the error code
returned by ha_analyze().
Test case added to innodb_mysql_sync.test.
Bug #43272 HANDLER SQL command does not work under LOCK TABLES
HANDLER commands are now explicitly disallowed in LOCK TABLES mode.
Before, HANDLER OPEN gave the misleading error message: "Table x was
not locked with LOCK TABLES". This patch changes HANDLER OPEN/READ/CLOSE
to give ER_LOCK_OR_ACTIVE_TRANSACTION "Can't execute the given command
because you have active locked tables or an active transaction" in
LOCK TABLES mode.
Test case added to lock.test.
Bug #45067 Assertion `stmt_da->is_error()' in
Delayed_insert::open_and_lock_table
The assert was triggered when delayed insert was killed by another
connection using mysql_notify_thread_having_shared_lock().
During handling of thd->killed, thd.fatal_error() was called without
a previous call to my_error() which triggered the assert.
This patch allows the assert to pass if thd->killed has been set.
----------------------------------------------------------
revno: 2617.69.24
committer: Konstantin Osipov <kostja@sun.com>
branch nick: 5.4-42546
timestamp: Fri 2009-08-14 19:22:05 +0400
message:
A pre-requisite for a fix for Bug#42546 "Backup: RESTORE fails, thinking it
finds an existing table"
Back-port from WL 148 "Foreign keys" feature tree a patch
that introduced Prelocking_strategy class -- a way to parameterize
open_tables() behaviour, implemented by Dmitry Lenev.
(Part of WL#4284).
----------------------------------------------------------
revno: 2617.69.21
committer: Konstantin Osipov <kostja@sun.com>
branch nick: 5.4-4284-1-assert
timestamp: Thu 2009-08-13 20:13:55 +0400
message:
A fix and a test case for Bug#46610 "MySQL 5.4.4: MyISAM MRG engine crash
on auto-repair of child".
Also fixes Bug#42862 "Crash on failed attempt to open a children of a
merge table".
MERGE engine needs to extend the global table list
with TABLE_LIST elements for child tables,
so that they are opened and locked.
Previously these table list elements were allocated
in memory of ha_myisammrg object (MERGE engine handler).
That would lead to access to freed memory in
recover_from_failed_open_table_attempt(), which would
try to recover a MERGE table child (MyISAM table)
and use for that TABLE_LIST of that child.
But by the time recover_from_failed_open_table_attempt()
is invoked, ha_myisammrg object that owns this
TABLE_LIST may be destroyed, and thus TABLE_LIST
memory freed.
The fix is to ensure that TABLE_LIST elements
that are added to the global table list (lex->query_tables)
are always allocated in thd->mem_root, which is not
destroyed until end of execution.
If previously TABLE_LIST elements were allocated
at ha_myisammrg::open() (i.e. when the TABLE
object was created and added to the table cache),
now they are allocated in ha_myisammrg::add_chidlren_list()
(i.e. right after "open" of the merge parent in
open_tables()).
We still create a list of children names
at ha_myisammrg::open() to use as a basis
for creation of TABLE_LISTs, that allows
to avoid reading the merge handler data
file on every execution.
Bug #22876 Four-way deadlock
This bug was fixed as a part of Bug#989
"If DROP TABLE while there's an active transaction, wrong binlog order"
A statement which would have caused circular wait will now
be aborted with ER_LOCK_DEADLOCK.
Test case based on bug description added to innodb_mysql_lock.test.
Note that innodb_lock_wait_timeout is set to 5 mins to
prevent race conditions in the test.
Bug #39675 rename tables on innodb tables with pending
transactions causes slave data issue
Bug was already fixed as part of patch for Bug#989
(If DROP TABLE while there's an active transaction,
wrong binlog order)
Test case added to rpl_innodb.test.
Bug #45066 FLUSH TABLES WITH READ LOCK deadlocks against LOCK TABLE
Test coverage for combinations of LOCK TABLE READ / WRITE and
FLUSH TABLES / FLUSH TABLES WITH READ LOCK added to lock.test.
LOCK and FLUSH are executed sequentially from one connection.
----------------------------------------------------------
revno: 2617.69.20
committer: Konstantin Osipov <kostja@sun.com>
branch nick: 5.4-4284-1-assert
timestamp: Thu 2009-08-13 18:29:55 +0400
message:
WL#4284 "Transactional DDL locking"
A review fix.
Since WL#4284 implementation separated MDL_request and MDL_ticket,
MDL_request becamse a utility object necessary only to get a ticket.
Store it by-value in TABLE_LIST with the intent to merge
MDL_request::key with table_list->table_name and table_list->db
in future.
Change the MDL subsystem to not require MDL_requests to
stay around till close_thread_tables().
Remove the list of requests from the MDL context.
Requests for shared metadata locks acquired in open_tables()
are only used as a list in recover_from_failed_open_table_attempt(),
which calls mdl_context.wait_for_locks() for this list.
To keep such list for recover_from_failed_open_table_attempt(),
introduce a context class (Open_table_context), that collects
all requests.
A lot of minor cleanups and simplications that became possible
with this change.
----------------------------------------------------------
revno: 2617.69.2
committer: Konstantin Osipov <kostja@sun.com>
branch nick: 5.4-azalea-bugfixing
timestamp: Mon 2009-08-03 19:26:04 +0400
message:
A fix and a test case for Bug#45035 "Altering table under LOCK TABLES
results in "Error 1213 Deadlock found...".
If a user had a table locked with LOCK TABLES
for READ and for WRITE in the same connection, ALTER TABLE
could fail.
Root cause analysis:
If a connection issues
LOCK TABLE t1 write, t1 a read, t1 b read;
the new LOCK TABLES code in 6.0 (part of WL 3726) will create
the following list of TABLE_LIST objects
(thd->locked_tables_list->m_locked_tables):
{"t1" "b" tl_read_no_insert}, {"t1" "a" tl_read_no_insert},
{"t1" "t1" tl_write }
Later on, when we try to ALTER table t1, mysql_alter_table()
closes all TABLE instances and releases its thr_lock locks,
keeping only an exclusive metadata lock on t1.
But when ALTER is finished, Locked_table_list::reopen_tables()
tries to restore the original list of open and locked tables.
Before this patch, it used to do so one by one:
Open t1 b, get TL_READ_NO_INSERT lock,
Open t1 a, get TL_READ_NO_INSERT lock
Open t1, try to get TL_WRITE lock, deadlock.
The cause of the deadlock is that thr_lock.c doesn't
resolve the situation when the read list only consists
of locks taken by the same thread, followed by this very
thread trying to take a WRITE lock. Indeed, since
thr_lock_multi always gets a sorted list of locks,
WRITE locks always precede READ locks in the list
to lock.
Don't try to fix thr_lock.c deficiency, keep this
code simple.
Instead, try to take all thr_lock locks at once
in ::reopen_tables().
------------------------------------------------------------
revno: 2617.65.6
committer: Dmitry Lenev <dlenev@mysql.com>
branch nick: mysql-azalea-bg39674
timestamp: Sat 2009-07-25 00:28:43 +0400
message:
Fix for bug #39674 "On shutdown mdl_destroy() called before
plugin_shutdown()".
Attempt to shutdown PBXT engine plugin led to assertion failure
caused by using already destroyed mutex in metadata locking
subsystem.
This problem stemmed from the fact that we MDL subsystem and
table definition cache were deinitialized before plugin shutdown
while PBXT plugin during its shutdown process accessed tables and
therefore expected them to be in working shape.
This patch solves this problem by moving deinitialization of
these two subsystems after plugins are shut down.
No test case is provided since such test case would require
using PBXT or other plugin which accesses tables during its
shutdown process.
------------------------------------------------------------
revno: 2617.43.3
committer: Davi Arnaut <Davi.Arnaut@Sun.COM>
branch nick: 40188-6.0
timestamp: Thu 2009-05-07 13:15:54 +0200
message:
Sort results as the file list of the database directory is not
sorted (MY_DONT_SORT).
(This is a follow-up fix for WL#4284).
2617.31.12, 2617.31.15, 2617.31.15, 2617.31.16, 2617.43.1
- initial changeset that introduced the fix for
Bug#989 and follow up fixes for all test suite failures
introduced in the initial changeset.
------------------------------------------------------------
revno: 2617.31.1
committer: Davi Arnaut <Davi.Arnaut@Sun.COM>
branch nick: 4284-6.0
timestamp: Fri 2009-03-06 19:17:00 -0300
message:
Bug#989: If DROP TABLE while there's an active transaction, wrong binlog order
WL#4284: Transactional DDL locking
Currently the MySQL server does not keep metadata locks on
schema objects for the duration of a transaction, thus failing
to guarantee the integrity of the schema objects being used
during the transaction and to protect then from concurrent
DDL operations. This also poses a problem for replication as
a DDL operation might be replicated even thought there are
active transactions using the object being modified.
The solution is to defer the release of metadata locks until
a active transaction is either committed or rolled back. This
prevents other statements from modifying the table for the
entire duration of the transaction. This provides commitment
ordering for guaranteeing serializability across multiple
transactions.
- Incompatible change:
If MySQL's metadata locking system encounters a lock conflict,
the usual schema is to use the try and back-off technique to
avoid deadlocks -- this schema consists in releasing all locks
and trying to acquire them all in one go.
But in a transactional context this algorithm can't be utilized
as its not possible to release locks acquired during the course
of the transaction without breaking the transaction commitments.
To avoid deadlocks in this case, the ER_LOCK_DEADLOCK will be
returned if a lock conflict is encountered during a transaction.
Let's consider an example:
A transaction has two statements that modify table t1, then table
t2, and then commits. The first statement of the transaction will
acquire a shared metadata lock on table t1, and it will be kept
utill COMMIT to ensure serializability.
At the moment when the second statement attempts to acquire a
shared metadata lock on t2, a concurrent ALTER or DROP statement
might have locked t2 exclusively. The prescription of the current
locking protocol is that the acquirer of the shared lock backs off
-- gives up all his current locks and retries. This implies that
the entire multi-statement transaction has to be rolled back.
- Incompatible change:
FLUSH commands such as FLUSH PRIVILEGES and FLUSH TABLES WITH READ
LOCK won't cause locked tables to be implicitly unlocked anymore.
----------------------------------------------------------
revno: 2617.23.20
committer: Konstantin Osipov <kostja@sun.com>
branch nick: mysql-6.0-runtime
timestamp: Wed 2009-03-04 16:31:31 +0300
message:
WL#4284 "Transactional DDL locking"
Review comments: "Objectify" the MDL API.
MDL_request and MDL_context still need manual construction and
destruction, since they are used in environment that is averse
to constructors/destructors.
----------------------------------------------------------
revno: 2617.23.19
committer: Konstantin Osipov <kostja@sun.com>
branch nick: mysql-6.0-runtime
timestamp: Tue 2009-03-03 01:20:44 +0300
message:
Metadata locking: realign comments. No semantical changes,
only enforce a bit of the coding style.
This is a review fix for WL#4284 "Transactional DDL locking".
------------------------------------------------------------
revno: 2617.23.18
committer: Davi Arnaut <Davi.Arnaut@Sun.COM>
branch nick: 4284-6.0
timestamp: Mon 2009-03-02 18:18:26 -0300
message:
Bug#989: If DROP TABLE while there's an active transaction, wrong binlog order
WL#4284: Transactional DDL locking
This is a prerequisite patch:
These changes are intended to split lock requests from granted
locks and to allow the memory and lifetime of granted locks to
be managed within the MDL subsystem. Furthermore, tickets can
now be shared and therefore are used to satisfy multiple lock
requests, but only shared locks can be recursive.
The problem is that the MDL subsystem morphs lock requests into
granted locks locks but does not manage the memory and lifetime
of lock requests, and hence, does not manage the memory of
granted locks either. This can be problematic because it puts the
burden of tracking references on the users of the subsystem and
it can't be easily done in transactional contexts where the locks
have to be kept around for the duration of a transaction.
Another issue is that recursive locks (when the context trying to
acquire a lock already holds a lock on the same object) requires
that each time the lock is granted, a unique lock request/granted
lock structure structure must be kept around until the lock is
released. This can lead to memory leaks in transactional contexts
as locks taken during the transaction should only be released at
the end of the transaction. This also leads to unnecessary wake
ups (broadcasts) in the MDL subsystem if the context still holds
a equivalent of the lock being released.
These issues are exacerbated due to the fact that WL#4284 low-level
design says that the implementation should "2) Store metadata locks
in transaction memory root, rather than statement memory root" but
this is not possible because a memory root, as implemented in mysys,
requires all objects allocated from it to be freed all at once.
This patch combines review input and significant code contributions
from Konstantin Osipov (kostja) and Dmitri Lenev (dlenev).
------------------------------------------------------------
revno: 3035.4.1
committer: Davi Arnaut <Davi.Arnaut@Sun.COM>
branch nick: 39897-6.0
timestamp: Thu 2009-01-15 12:17:57 -0200
message:
Bug#39897: lock_multi fails in pushbuild: timeout waiting for processlist
The problem is that relying on the "Table lock" thread state in
its current position to detect that a thread is waiting on a lock
is race prone. The "Table lock" state change happens before the
thread actually tries to grab a lock on a table.
The solution is to move the "Table lock" state so that its set
only when a thread is actually going to wait for a lock. The state
change happens after the thread fails to grab the lock (because it
is owned by other thread) and proceeds to wait on a condition.
This is considered part of work related to WL#4284 "Transactional
DDL locking"
Warning: this patch contains an incompatible change.
When waiting on a lock in thr_lock.c, the server used to display "Locked"
processlist state. After this patch, the state is "Table lock".
The new state was actually intended to be display since year 2002,
when Monty added it. But up until removal of thd->locked boolean
member, this state was ignored by SHOW PROCESSLIST code.
-----------------------------------------------------------
2497.479.10 Sergei Golubchik 2008-08-27
proc_info_hook, mysys access to thd->proc_info
This patch is necessary for backport of WL#4284 "Transactional
DDL locking".
------------------------------------------------------------
revno: 2630.22.3
committer: Davi Arnaut <Davi.Arnaut@Sun.COM>
branch nick: 4284-6.0
timestamp: Thu 2008-08-07 22:33:43 -0300
message:
WL#4284: Transactional DDL locking
Make transaction management more modular through a new interface.
The overall objective of this change is to provide groundwork
for the design of transactional DDL locking by cleaning up the
transaction high level API to better distinguish operations implicit
and explicit, and single statement transaction from operations on
the normal transaction.
Having a a high-level interface for transaction management provides
a better base for implementing transactional concepts that are not
always tied to storage engines and also makes it easier to interect
with other higher level modules of the server.
------------------------------------------------------------
revno: 2630.13.17
committer: Davi Arnaut <Davi.Arnaut@Sun.COM>
branch nick: 4284-6.0
timestamp: Sun 2008-07-27 10:14:46 -0300
message:
Post-merge fixes:
Remove dependency on binlog, require not embedded as test uses
the event scheduler and disable abort on error for syntax only
available on servers built with debugging support.
This is a patch in scope of WL#4284 "Transactional DDL locking"
------------------------------------------------------------
revno: 2630.13.16
committer: Davi Arnaut <Davi.Arnaut@Sun.COM>
branch nick: WL#4284
timestamp: Sat 2008-07-26 13:38:20 -0300
message:
WL#4284: Transactional DDL locking
SQL statements' effect on transactions.
Currently the MySQL server and its storage engines are not
capable of rolling back operations that define or modify data
structures (also known as DDL statements) or operations that
alter any of the system tables (the mysql database). Allowing
these group of statements to participate in transactions
is unfeasible at this time (since rollback has no effect
whatsoever on them) and goes against the design of our metadata
locking subsystem.
The solution is to issue implicit commits before and after
those statements execution. This effectively confines each of
those statements to its own special transaction and ensures
that metadata locks taken during this special transaction
are not leaked into posterior statements/transactions.
----------------------------------------------------------
revno: 2630.2.7
committer: Konstantin Osipov <konstantin@mysql.com>
branch nick: mysql-6.0-runtime
timestamp: Wed 2008-06-04 15:18:52 +0400
message:
Fix a code regression (not observable externally) that I introduced
in the fix for Bug#26141
(backporting as part of all patches related to WL#3726)
----------------------------------------------------------
revno: 2630.2.23
committer: Konstantin Osipov <konstantin@mysql.com>
branch nick: mysql-6.0-runtime
timestamp: Fri 2008-06-27 21:15:11 +0400
message:
Add an assert that we never call COMMIT or ROLLBACK while having
a table lock.
------------------------------------------------------------
revno: 2630.4.39
committer: Dmitry Lenev <dlenev@mysql.com>
branch nick: mysql-6.0-3726-w2
timestamp: Thu 2008-06-26 13:08:27 +0400
message:
Fix warnings about passing pointer to not fully-initialized THD
object to constructor of base Open_tables_state classe, which
appeared on Windows and were introduced by one of the patches
implementing WL#3726 "DDL locking for all metadata objects".
----------------------------------------------------------
revno: 2630.4.38
committer: Konstantin Osipov <konstantin@mysql.com>
branch nick: mysql-6.0-4144
timestamp: Wed 2008-06-25 22:07:06 +0400
message:
WL#4144 - Lock MERGE engine children.
Committing a version of the patch merged with WL#3726
on behalf of Ingo.
Step #1: Move locking from parent to children.
MERGE children are now left in the query list of tables
after inserted there in open_tables(). So they are locked
by lock_tables() as all other tables are.
The MERGE parent does not store locks any more. It appears
in a MYSQL_LOCK with zero lock data. This is kind of a "dummy"
lock.
All other lock handling is also done directly on the children.
To protect against parent or child modifications during LOCK
TABLES, the children are detached after every statement and
attached before every statement, even under LOCK TABLES.
The children table list is removed from the query list of tables
on every detach and on close of the parent.
Step #2: Move MERGE specific functionality from SQL layer
into table handler.
Functionality moved from SQL layer (mainly sql_base.cc)
to the table handler (ha_myisammrg.cc).
Unnecessary code is removed from the SQL layer.
Step #3: Moved all MERGE specific members from TABLE
to ha_myisammrg.
Moved members from TABLE to ha_myisammrg.
Renamed some mebers.
Fixed comments.
Step #4: Valgrind and coverage testing
Valgrind did not uncover new problems.
Added purecov comments.
Added a new test for DATA/INDEX DIRECTORY options.
Changed handling of ::reset() for non-attached children.
Fixed the merge-big test.
Step #5: Fixed crashes detected during review
Changed detection when to attach/detach.
Added new tests.
Backport also the fix for Bug#44040 "MySQL allows creating a
MERGE table upon VIEWs but crashes when using it"
------------------------------------------------------------
revno: 2630.4.37
committer: Dmitry Lenev <dlenev@mysql.com>
branch nick: mysql-6.0-3726-w2
timestamp: Wed 2008-06-25 20:28:57 +0400
message:
Fix build failure of mysql-6.0-3726 tree on Windows.
The failure was caused by the fact that sql/mdl.cc was
using __func__ macro without including sql_profile.h
header which contained definition of this macro for
those platforms that miss it.
This patch solves this problem by moving this define to
include/my_global.h which makes it available in modules
which don't/can't include sql/mysql_priv.h.
This is a patch that is part of WL#3726.
----------------------------------------------------------
revno: 2630.4.36
committer: Konstantin Osipov <konstantin@mysql.com>
branch nick: mysql-6.0-3726
timestamp: Wed 2008-06-25 17:03:37 +0400
message:
As per discussion with Serg and Dmitri, remove the code
that is trying to emulate LOCK TABLES when locking tables for prelocking.
This code was worked around by the engines, and has no effect.
We may still have to do something to ensure that statement-based
replication is consistent in MVCC engines, or other engines
that downgrade table level locks, but this will have to be done
somehow differently.
----------------------------------------------------------
revno: 2630.4.35
committer: Konstantin Osipov <konstantin@mysql.com>
branch nick: mysql-6.0-3726
timestamp: Wed 2008-06-25 16:44:00 +0400
message:
Fix a MyISAM-specific bug in the new implementation of
LOCK TABLES (WL#3726).
If more than one instance of a MyISAM table are open in the
same connection, all of them must share the same status_param.
Otherwise, unlock of a table may lead to lost records.
See also comments in thr_lock.c.
------------------------------------------------------------
revno: 2630.4.33
committer: Dmitry Lenev <dlenev@mysql.com>
branch nick: mysql-6.0-3726-w2
timestamp: Fri 2008-06-20 17:11:20 +0400
message:
WL#3726 "DDL locking for all metadata objects".
After-review fixes in progress.
Minimized dependency of mdl.cc on other modules (particularly
made it independant of mysql_priv.h) in order to be able
write unit tests for metadata locking subsystem.
----------------------------------------------------------
revno: 2630.4.31
committer: Konstantin Osipov <konstantin@mysql.com>
branch nick: mysql-6.0-3726
timestamp: Thu 2008-06-12 06:23:08 +0400
message:
Extend the signature of TABLE_LIST::init_one_table() to
initialize lengths
This is part of WL#3726 post-review fixes.
----------------------------------------------------------
revno: 2630.10.1
committer: Konstantin Osipov <konstantin@mysql.com>
branch nick: mysql-6.0-lock-tables-tidyup
timestamp: Wed 2008-06-11 15:49:58 +0400
message:
WL#3726, review fixes.
Now that we have metadata locks, we don't need to keep a crippled
TABLE instance in the table cache to indicate that a table is locked.
Remove all code that used this technique. Instead, rely on metadata
locks and use the standard open_table() and close_thread_table()
to manipulate with the table cache tables.
Removes a list of functions that have become unused (see the comment
for sql_base.cc for details).
Under LOCK TABLES, keep a TABLE_LIST instance for each table
that may be temporarily closed. For that, implement an own class for
LOCK TABLES mode, Locked_tables_list.
This is a pre-requisite patch for WL#4144.
This is not exactly a backport: there is no new
online ALTER table in Celosia, so the old alter table
code was changed to work with the new table cache API.
