MySQL  8.0.18
Source Code Documentation
dictionary_client.h
Go to the documentation of this file.
1 /* Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
2 
3  This program is free software; you can redistribute it and/or modify
4  it under the terms of the GNU General Public License, version 2.0,
5  as published by the Free Software Foundation.
6 
7  This program is also distributed with certain software (including
8  but not limited to OpenSSL) that is licensed under separate terms,
9  as designated in a particular file or component or in included license
10  documentation. The authors of MySQL hereby grant you an additional
11  permission to link the program and your derivative works with the
12  separately licensed software that they have included with MySQL.
13 
14  This program is distributed in the hope that it will be useful,
15  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  GNU General Public License, version 2.0, for more details.
18 
19  You should have received a copy of the GNU General Public License
20  along with this program; if not, write to the Free Software
21  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 #ifndef DD_CACHE__DICTIONARY_CLIENT_INCLUDED
24 #define DD_CACHE__DICTIONARY_CLIENT_INCLUDED
25 
26 #include <stddef.h>
27 #include <memory>
28 #include <string>
29 #include <vector>
30 
31 #include "my_compiler.h"
32 #include "my_dbug.h"
33 #include "object_registry.h" // Object_registry
34 #include "sql/dd/object_id.h"
35 #include "sql/dd/string_type.h"
36 
37 class THD;
38 
39 namespace dd {
40 class Schema;
41 class Table;
42 class Entity_object;
43 } // namespace dd
44 
45 namespace dd {
46 namespace cache {
47 
48 class SPI_lru_cache;
49 
50 /**
51  A smart-pointer for managing an SPI_lru_cache even when it is only
52  forward declared. Automaticlly allocated cache with new, and assigns
53  m_spi_lru_cache to it, when dereferenced using non-const
54  operator->(). Destructor deletes the object pointed to by
55  m_spi_lru_cache.
56 */
59 
60  public:
61  /** Calls delete on m_spi_lru_cache unless nullptr. */
63 
64  /**
65  Creates cache on demand if m_spi_lru_cache is nullptr.
66  @return pointer to cache.
67  */
69 
70  /**
71  Const overload which does not create cache on demand, but merely
72  returns the pointer.
73  @return pointer to cache (may be nullptr)
74  */
75  const SPI_lru_cache *operator->() const { return m_spi_lru_cache; }
76 
77  /*
78  Predicate for nullptr.
79  @return true if points to valid cache, false otherwise.
80  */
81  bool is_nullptr() const { return (m_spi_lru_cache == nullptr); }
82 };
83 
84 /**
85  Implementation of a dictionary client.
86 
87  The dictionary client provides a unified interface to accessing dictionary
88  objects. The client is a member of the THD, and is typically used in
89  server code to access the dictionary. When we refer to "the user" below,
90  we mean the server code using the dictionary client.
91 
92  The main task of the client is to access a shared cache to retrieve
93  dictionary objects. The shared cache, in its turn, will access the
94  dictionary tables if there is a cache miss.
95 
96  To support cache eviction, the shared cache must keep track of which
97  clients that have acquired an object. When a client acquires an object
98  from the shared cache for the first time, it is added to a client local
99  object registry. Further acquisition of the same object from the client
100  will get the object from the client's registry. Thus, the usage tracking
101  in the shared cache only keep track of the number of clients currently
102  using the object, and hence, there must be an operation that complements
103  acquisition, to inform the shared cache that the object is not used
104  anymore. This complementing operation is called releasing the object.
105 
106  To manage releasing objects, the Auto_releaser class provides some
107  support. When an auto releaser is instantiated, it will keep track of
108  the objects that are acquired from the shared cache in its lifetime.
109  Auto releasers may be nested or stacked, and the current releaser is
110  the one at the top of the stack. The auto releaser stack is associated
111  with a dictionary client instance. When the auto releaser goes out
112  of scope, it will release all objects that have been acquired from the
113  shared cache in its lifetime. Objects retrieved earlier than that will
114  be automatically released by a releaser further down the auto releaser
115  stack. For more coarse grained control, there is a release method that
116  will release all objects acquired by the client.
117 
118  In addition to the auto releasers, the client has an object registry.
119  The registry holds pointers to all currently acquired objects. Thus,
120  the object registry is the union of the registers in the stack of
121  auto releasers. The client's object registry is used for looking up
122  objects, while the registers in the auto releasers are used for
123  releasing objects.
124 
125  The client also has a second registery of objects with uncommitted changes.
126  These are objects acquired by acquire_for_modification() or registered
127  with register_uncommitted_object(). These objects are only present in
128  the local registry and not in the shared cache. Once registered, the
129  objects can also be retrieved with normal acquire(). This means that
130  a given client has a view which includes uncommitted changes made
131  using the same client, while other clients do not see these changes.
132 
133  @note We must handle situations where an object is actually acquired from
134  the shared cache, while the dynamic cast to a subtype fails. We use
135  the auto release mechanism to achieve that.
136 
137  @note When a dictionary client method returns true, indicating that an
138  error has occurred, the error has been reported, either by the
139  client itself, or by the dictionary subsystem.
140 */
141 
142 template <typename T>
144 
146  public:
147  /**
148  Class to help releasing and deleting objects.
149 
150  This class keeps a register of shared objects that are automatically
151  released when the instance goes out of scope. When a new instance
152  is created, the encompassing dictionary client's current auto releaser
153  is replaced by this one, keeping a link to the old one. When the
154  auto releaser is deleted, it links the old releaser back in as the
155  client's current releaser.
156 
157  Shared objects that are added to the auto releaser will be released when
158  the releaser is deleted. Only the dictionary client is allowed to add
159  objects to the auto releaser.
160 
161  The usage pattern is that objects that are retrieved from the shared
162  dictionary cache are added to the current auto releaser. Objects that
163  are retrieved from the client's local object register are not added to
164  the auto releaser. Thus, when the releaser is deleted, it releases all
165  objects that have been retrieved from the shared cache during the
166  lifetime of the releaser.
167 
168  Similarly the auto releaser maintains a list of objects created
169  by acquire_uncached(). These objects are owned by the Auto_releaser
170  and are deleted when the auto releaser goes out of scope.
171  */
172 
174  friend class Dictionary_client;
175 
176  private:
180 
181  /**
182  Register an object to be auto released.
183 
184  @tparam T Dictionary object type.
185  @param element Cache element to auto release.
186  */
187 
188  template <typename T>
190  // Catch situations where we do not use a non-default releaser.
191  DBUG_ASSERT(m_prev != NULL);
192  m_release_registry.put(element);
193  }
194 
195  /**
196  Transfer an object from the current to the previous auto releaser.
197 
198  @tparam T Dictionary object type.
199  @param object Dictionary object to transfer.
200  */
201 
202  template <typename T>
203  void transfer_release(const T *object);
204 
205  /**
206  Remove an element from some auto releaser down the chain.
207 
208  Return a pointer to the releaser where the element was found.
209  Thus, the element may be re-inserted into the appropriate
210  auto releaser after e.g. changing the keys.
211 
212  @tparam T Dictionary object type.
213  @param element Cache element to auto remove.
214 
215  @return Pointer to the auto releaser where the object was signed up.
216  */
217 
218  template <typename T>
219  Auto_releaser *remove(Cache_element<T> *element);
220 
221  // Create a new empty auto releaser. Used only by the Dictionary_client.
222  Auto_releaser();
223 
224  public:
225  /**
226  Create a new auto releaser and link it into the dictionary client
227  as the current releaser.
228 
229  @param client Dictionary client for which to install this auto
230  releaser.
231  */
232 
233  explicit Auto_releaser(Dictionary_client *client);
234 
235  // Release all objects registered and restore previous releaser.
236  ~Auto_releaser();
237 
238  // Debug dump to stderr.
239  template <typename T>
240  void dump() const;
241  };
242 
243  private:
244  std::vector<Entity_object *> m_uncached_objects; // Objects to be deleted.
245  Object_registry m_registry_committed; // Registry of committed objects.
246  Object_registry m_registry_uncommitted; // Registry of uncommitted objects.
247  Object_registry m_registry_dropped; // Registry of dropped objects.
248  THD *m_thd; // Thread context, needed for cache misses.
249  Auto_releaser m_default_releaser; // Default auto releaser.
250  Auto_releaser *m_current_releaser; // Current auto releaser.
251 
252  /**
253  Se-private ids known not to exist in either TABLES or PARTITIONS
254  or both.
255  */
257 
258  /**
259  Get a dictionary object.
260 
261  The operation retrieves a dictionary object by one of its keys from the
262  cache and returns it through the object parameter. If the object is
263  already present in the client's local object registry, it is fetched
264  from there. Otherwise, it is fetched from the shared cache (possibly
265  involving a cache miss), and eventually added to the local object
266  registry.
267 
268  If no object is found for the given key, NULL is returned. The shared
269  cache owns the returned object, i.e., the caller must not delete it.
270  After using the object(s), the user must release it using one of the
271  release mechanisms described earlier.
272 
273  The reference counter for the object is incremented if the object is
274  retrieved from the shared cache. If the object was present in the local
275  registry, the reference counter stays the same. A cache miss is handled
276  transparently by the shared cache.
277 
278  @note This function must be called with type T being the same as
279  T::Cache_partition. Dynamic casting to the actual subtype
280  must be done at an outer level.
281 
282  @tparam K Key type.
283  @tparam T Dictionary object type.
284  @param key Key to use for looking up the object.
285  @param [out] object Object pointer, if an object exists, otherwise NULL.
286  @param [out] local_committed
287  Whether the object was read from the local
288  committed object registry.
289  @param [out] local_uncommitted
290  Whether the object was read from the local
291  uncommitted registry.
292 
293  @retval false No error.
294  @retval true Error (from handling a cache miss).
295  */
296 
297  template <typename K, typename T>
298  bool acquire(const K &key, const T **object, bool *local_committed,
299  bool *local_uncommitted) MY_ATTRIBUTE((warn_unused_result));
300 
301  /**
302  Get an uncommitted dictionary object that can be modified safely.
303 
304  The difference between this method and acquire(), is that this method
305  only looks in the local registry of uncommitted objects. That is, object
306  created by acquire_for_modification() or registered with
307  register_uncommitted_object(). It will not access the shared cache.
308  Objects that have been dropped are returned as nullptr, but
309  with the value of the parameter 'dropped' set to 'true'.
310 
311  @tparam K Key type.
312  @tparam T Dictionary object type.
313  @param key Key to use for looking up the object.
314  @param [out] object Object pointer, if an object exists, otherwise NULL.
315  @param [out] dropped Object exists, but has been dropped and has not yet
316  committed. In this case, 'object' is set to nullptr.
317  */
318 
319  template <typename K, typename T>
320  void acquire_uncommitted(const K &key, T **object, bool *dropped);
321 
322  /**
323  Mark all objects of a certain type as not being used by this client.
324 
325  This function is called with the client's own object registry, or with
326  the registry of an auto releaser (which will contain a subset of the
327  objects in the client's object registry).
328 
329  The function will release all objects of a given type in the registry
330  submitted.The objects must be present and in use. If the objects become
331  unused, they are added to the free list in the shared cache, which is
332  then rectified to enforce its capacity constraints. The objects are also
333  removed from the client's object registry.
334 
335  @tparam T Dictionary object type.
336  @param registry Object registry tp release from.
337 
338  @return Number of objects released.
339  */
340 
341  template <typename T>
342  size_t release(Object_registry *registry);
343 
344  /**
345  Release all objects in the submitted object registry.
346 
347  This function will release all objects from the client's registry, or
348  from the registry of an auto releaser.
349 
350  @param registry Object registry tp release from.
351 
352  @return Number of objects released.
353  */
354 
355  size_t release(Object_registry *registry);
356 
357  /**
358  Register an uncached object to be auto deleted.
359 
360  @tparam T Dictionary object type.
361  @param object Dictionary object to auto delete.
362  */
363 
364  template <typename T>
365  void auto_delete(T *object) {
366 #ifndef DBUG_OFF
367  // Make sure we do not sign up a shared object for auto delete.
370  static_cast<const typename T::Cache_partition *>(object), &element);
371  DBUG_ASSERT(element == nullptr);
372 
373  // Make sure we do not sign up an uncommitted object for auto delete.
375  static_cast<const typename T::Cache_partition *>(object), &element);
376  DBUG_ASSERT(element == nullptr);
377 
378  // We must require a top level non-default releaser to ensure a
379  // predictable life span of the objects.
381 #endif
382 
383  m_uncached_objects.push_back(object);
384  }
385 
386  /**
387  Remove an object from the auto delete vector.
388 
389  @tparam T Dictionary object type.
390  @param object Dictionary object to keep.
391  */
392 
393  template <typename T>
394  void no_auto_delete(T *object) {
395 #ifndef DBUG_OFF
396  // Make sure the object has been registered as uncommitted.
399  static_cast<const typename T::Cache_partition *>(object), &element);
400  DBUG_ASSERT(element != nullptr);
401 #endif
403  m_uncached_objects.end(), object),
404  m_uncached_objects.end());
405  }
406 
407  /**
408  Transfer object ownership from caller to Dictionary_client,
409  and register the object as uncommitted.
410 
411  This is intended for objects created by the caller that should
412  be managed by Dictionary_client. Transferring an object in this
413  way will make it accessible by calling acquire().
414 
415  This method takes a non-const argument as it only makes
416  sense to register objects not acquired from the shared cache.
417 
418  @tparam T Dictionary object type.
419  @param object Object to transfer ownership.
420  */
421 
422  template <typename T>
423  void register_uncommitted_object(T *object);
424 
425  /**
426  Transfer object ownership from caller to Dictionary_client,
427  and register the object as dropped.
428 
429  This method is used internally by the Dictionary_client for
430  keeping track of dropped objects. This is needed before
431  transaction commit if an attempt is made to acquire the
432  dropped object, to avoid consulting the shared cache, which
433  might contaminate the cache due to a cache miss (handled with
434  isolation level READ_COMMITTED). Instead of consulting the
435  shared cache, this Dictionary_client will recognize that the
436  object is dropped, and return a nullptr.
437 
438  This method takes a non-const argument as it only makes
439  sense to register objects not acquired from the shared cache.
440 
441  @tparam T Dictionary object type.
442  @param object Object to transfer ownership.
443  */
444 
445  template <typename T>
446  void register_dropped_object(T *object);
447 
448  /**
449  Remove the uncommitted objects from the client and (depending
450  on the parameter) put them into the shared cache,
451  thereby making them visible to other clients. Should be called
452  after commit to disk but before metadata locks are released.
453 
454  Can also be called after rollback in order to explicitly throw
455  the modified objects away before making any actions to compensate
456  for a partially completed statement. Note that uncommitted objects
457  are automatically removed once the topmost stack-allocated auto
458  releaser goes out of scope, so calling this function in case of
459  abort is only needed to make acquire return the old object again
460  later in the same statement.
461 
462  @param commit_to_shared_cache
463  If true, uncommitted objects will
464  be put into the shared cache.
465  @tparam T Dictionary object type.
466  */
467 
468  template <typename T>
469  void remove_uncommitted_objects(bool commit_to_shared_cache);
470 
471  template <typename T>
472  using Const_ptr_vec = std::vector<const T *>;
473 
474  /**
475  Fetch objects from DD tables that match the supplied key.
476 
477  @tparam Object_type Type of object to fetch.
478  @param coll Vector to fill with objects.
479  @param object_key The search key. If key is not supplied, then
480  we do full index scan.
481 
482  @return false Success.
483  @return true Failure (error is reported).
484  */
485 
486  template <typename Object_type>
487  bool fetch(Const_ptr_vec<Object_type> *coll, const Object_key *object_key)
488  MY_ATTRIBUTE((warn_unused_result));
489 
490  public:
491  // Initialize an instance with a default auto releaser.
492  explicit Dictionary_client(THD *thd);
493 
494  // Make sure all objects are released.
496 
497  /**
498  Retrieve an object by its object id.
499 
500  @tparam T Dictionary object type.
501  @param id Object id to retrieve.
502  @param [out] object Dictionary object, if present; otherwise NULL.
503 
504  @retval false No error.
505  @retval true Error (from handling a cache miss).
506  */
507 
508  template <typename T>
509  bool acquire(Object_id id, const T **object)
510  MY_ATTRIBUTE((warn_unused_result));
511 
512  /**
513  Retrieve an object by its object id.
514 
515  This function returns a cloned object that can be modified.
516 
517  @tparam T Dictionary object type.
518  @param id Object id to retrieve.
519  @param [out] object Dictionary object, if present; otherwise NULL.
520 
521  @retval false No error.
522  @retval true Error (from handling a cache miss).
523  */
524 
525  template <typename T>
526  bool acquire_for_modification(Object_id id, T **object)
527  MY_ATTRIBUTE((warn_unused_result));
528 
529  /**
530  Retrieve an object by its object id without caching it.
531 
532  The object is not cached but owned by the dictionary client, who
533  makes sure it is deleted. The object must not be released, and may not
534  be used as a parameter to the other dictionary client methods since it is
535  not known by the object registry.
536 
537  @tparam T Dictionary object type.
538  @param id Object id to retrieve.
539  @param [out] object Dictionary object, if present; otherwise NULL.
540 
541  @retval false No error.
542  @retval true Error (from reading the dictionary tables).
543  */
544 
545  template <typename T>
546  bool acquire_uncached(Object_id id, T **object)
547  MY_ATTRIBUTE((warn_unused_result));
548 
549  /**
550  Retrieve a possibly uncommitted object by its object id without caching it.
551 
552  The object is not cached but owned by the dictionary client, who
553  makes sure it is deleted. The object must not be released, and may not
554  be used as a parameter to the other dictionary client methods since it is
555  not known by the object registry.
556 
557  When the object is read from the persistent tables, the transaction
558  isolation level is READ UNCOMMITTED. This is necessary to be able to
559  read uncommitted data from an earlier stage of the same session.
560 
561  @tparam T Dictionary object type.
562  @param id Object id to retrieve.
563  @param [out] object Dictionary object, if present; otherwise nullptr.
564 
565  @retval false No error.
566  @retval true Error (from reading the dictionary tables).
567  */
568 
569  template <typename T>
570  bool acquire_uncached_uncommitted(Object_id id, T **object)
571  MY_ATTRIBUTE((warn_unused_result));
572 
573  /**
574  Retrieve an object by its name.
575 
576  @tparam T Dictionary object type.
577  @param object_name Name of the object.
578  @param [out] object Dictionary object, if present; otherwise NULL.
579 
580  @retval false No error.
581  @retval true Error (from handling a cache miss).
582  */
583 
584  template <typename T>
585  bool acquire(const String_type &object_name, const T **object)
586  MY_ATTRIBUTE((warn_unused_result));
587 
588  /**
589  Retrieve an object by its name.
590 
591  This function returns a cloned object that can be modified.
592 
593  @tparam T Dictionary object type.
594  @param object_name Name of the object.
595  @param [out] object Dictionary object, if present; otherwise NULL.
596 
597  @retval false No error.
598  @retval true Error (from handling a cache miss).
599  */
600 
601  template <typename T>
602  bool acquire_for_modification(const String_type &object_name, T **object)
603  MY_ATTRIBUTE((warn_unused_result));
604 
605  /**
606  Retrieve an object by its schema- and object name.
607 
608  @note We will acquire an IX-lock on the schema name unless we already
609  have one. This is needed for proper synchronization with schema
610  DDL in cases where the table does not exist, and where the
611  indirect synchronization based on table names therefore will not
612  apply.
613 
614  @todo TODO: We should change the MDL acquisition (see above) for a more
615  long term solution.
616 
617  @tparam T Dictionary object type.
618  @param schema_name Name of the schema containing the object.
619  @param object_name Name of the object.
620  @param [out] object Dictionary object, if present; otherwise NULL.
621 
622  @retval false No error.
623  @retval true Error (from handling a cache miss, or from
624  failing to get an MDL lock).
625  */
626 
627  template <typename T>
628  bool acquire(const String_type &schema_name, const String_type &object_name,
629  const T **object) MY_ATTRIBUTE((warn_unused_result));
630 
631  /**
632  Retrieve an object by its schema- and object name.
633 
634  This function returns a cloned object that can be modified.
635 
636  @note We will acquire an IX-lock on the schema name unless we already
637  have one. This is needed for proper synchronization with schema
638  DDL in cases where the table does not exist, and where the
639  indirect synchronization based on table names therefore will not
640  apply.
641 
642  @todo TODO: We should change the MDL acquisition (see above) for a more
643  long term solution.
644 
645  @tparam T Dictionary object type.
646  @param schema_name Name of the schema containing the object.
647  @param object_name Name of the object.
648  @param [out] object Dictionary object, if present; otherwise NULL.
649 
650  @retval false No error.
651  @retval true Error (from handling a cache miss, or from
652  failing to get an MDL lock).
653  */
654 
655  template <typename T>
656  bool acquire_for_modification(const String_type &schema_name,
657  const String_type &object_name, T **object)
658  MY_ATTRIBUTE((warn_unused_result));
659 
660  /**
661  Retrieve an object by its schema- and object name.
662 
663  @note We will acquire an IX-lock on the schema name unless we already
664  have one. This is needed for proper synchronization with schema
665  DDL in cases where the table does not exist, and where the
666  indirect synchronization based on table names therefore will not
667  apply.
668 
669  @note This is a variant of the method above asking for an object of type
670  T, and hence using T's functions for updating name keys etc.
671  This function, however, returns the instance pointed to as type
672  T::Cache_partition to ease handling of various subtypes
673  of the same base type.
674 
675  @todo TODO: We should change the MDL acquisition (see above) for a more
676  long term solution.
677 
678  @tparam T Dictionary object type.
679  @param schema_name Name of the schema containing the object.
680  @param object_name Name of the object.
681  @param [out] object Dictionary object, if present; otherwise NULL.
682 
683  @retval false No error.
684  @retval true Error (from handling a cache miss, or from
685  failing to get an MDL lock).
686  */
687 
688  template <typename T>
689  bool acquire(const String_type &schema_name, const String_type &object_name,
690  const typename T::Cache_partition **object)
691  MY_ATTRIBUTE((warn_unused_result));
692 
693  /**
694  Retrieve an object by its schema- and object name.
695 
696  This function returns a cloned object that can be modified.
697 
698  @note We will acquire an IX-lock on the schema name unless we already
699  have one. This is needed for proper synchronization with schema
700  DDL in cases where the table does not exist, and where the
701  indirect synchronization based on table names therefore will not
702  apply.
703 
704  @note This is a variant of the method above asking for an object of type
705  T, and hence using T's functions for updating name keys etc.
706  This function, however, returns the instance pointed to as type
707  T::Cache_partition to ease handling of various subtypes
708  of the same base type.
709 
710  @todo TODO: We should change the MDL acquisition (see above) for a more
711  long term solution.
712 
713  @tparam T Dictionary object type.
714  @param schema_name Name of the schema containing the object.
715  @param object_name Name of the object.
716  @param [out] object Dictionary object, if present; otherwise NULL.
717 
718  @retval false No error.
719  @retval true Error (from handling a cache miss, or from
720  failing to get an MDL lock).
721  */
722 
723  template <typename T>
724  bool acquire_for_modification(const String_type &schema_name,
725  const String_type &object_name,
726  typename T::Cache_partition **object)
727  MY_ATTRIBUTE((warn_unused_result));
728 
729  /**
730  Retrieve a table object by its se private id.
731 
732  @param engine Name of the engine storing the table.
733  @param se_private_id SE private id of the table.
734  @param [out] table Table object, if present; otherwise NULL.
735 
736  @note The object must be acquired uncached since we cannot acquire a
737  metadata lock in advance since we do not know the table name.
738  Thus, the returned table object is owned by the caller, who must
739  make sure it is deleted.
740 
741  @retval false No error or if object was not found.
742  @retval true Error (e.g. from reading DD tables, or if an
743  object of a wrong type was found).
744  */
745 
747  Object_id se_private_id,
748  Table **table)
749  MY_ATTRIBUTE((warn_unused_result));
750 
751  /**
752  Retrieve a table object by its partition se private id.
753 
754  @param engine Name of the engine storing the table.
755  @param se_partition_id SE private id of the partition.
756  @param [out] table Table object, if present; otherwise NULL.
757 
758  @retval false No error or if object was not found.
759  @retval true Error (from handling a cache miss).
760  */
761 
763  const String_type &engine, Object_id se_partition_id, Table **table)
764  MY_ATTRIBUTE((warn_unused_result));
765 
766  /**
767  Retrieve schema and table name by the se private id of the table.
768 
769  @param engine Name of the engine storing the table.
770  @param se_private_id SE private id of the table.
771  @param [out] schema_name Name of the schema containing the table.
772  @param [out] table_name Name of the table.
773 
774  @retval false No error OR if object was not found.
775  The OUT params will be set to empty
776  string when object is not found.
777  @retval true Error.
778  */
779 
781  Object_id se_private_id,
782  String_type *schema_name,
784  MY_ATTRIBUTE((warn_unused_result));
785 
786  /**
787  Retrieve schema and table name by the se private id of the partition.
788 
789  @param engine Name of the engine storing the table.
790  @param se_partition_id SE private id of the table partition.
791  @param [out] schema_name Name of the schema containing the table.
792  @param [out] table_name Name of the table.
793 
794  @retval false No error or if object was not found.
795  The OUT params will be set to empty
796  string when object is not found.
797  @retval true Error.
798  */
799 
801  Object_id se_partition_id,
802  String_type *schema_name,
804  MY_ATTRIBUTE((warn_unused_result));
805 
806  /**
807  Retrieve a table name of a given trigger name and schema.
808 
809  @param schema Schema containing the trigger.
810  @param trigger_name Name of the trigger.
811  @param [out] table_name Name of the table for which
812  trigger belongs to. Empty string if
813  there is no such trigger.
814 
815  @retval false No error.
816  @retval true Error.
817  */
818 
819  bool get_table_name_by_trigger_name(const Schema &schema,
820  const String_type &trigger_name,
822  MY_ATTRIBUTE((warn_unused_result));
823 
824  /**
825  Check if schema contains foreign key with specified name.
826 
827  @param schema Schema containing the foreign key.
828  @param foreign_key_name Name of the foreign key.
829  @param [out] exists Set to true if foreign key with
830  the name provided exists in the
831  schema, false otherwise.
832 
833  @retval false No error.
834  @retval true Error.
835  */
836 
837  bool check_foreign_key_exists(const Schema &schema,
838  const String_type &foreign_key_name,
839  bool *exists)
840  MY_ATTRIBUTE((warn_unused_result));
841 
842  /**
843  Check if schema contains check constraint with specified name.
844 
845  @param schema Schema containing the check constraint.
846  @param check_cons_name Name of the check constraint.
847  @param [out] exists Set to true if check constraint with
848  the name provided exists in the
849  schema, false otherwise.
850 
851  @retval false No error.
852  @retval true Error.
853  */
854 
855  bool check_constraint_exists(const Schema &schema,
856  const String_type &check_cons_name,
857  bool *exists);
858 
859  /**
860  Fetch the names of the components in the schema. Hidden components are
861  ignored. E.g., Object with dd::Table::hidden() == true will be ignored.
862 
863  @tparam T Type of object to retrieve names for.
864  @param schema Schema for which to get component names.
865  @param [out] names An std::vector containing all object names.
866 
867  @return true Failure (error is reported).
868  @return false Success.
869  */
870 
871  template <typename T>
872  bool fetch_schema_component_names(const Schema *schema,
873  std::vector<String_type> *names) const
874  MY_ATTRIBUTE((warn_unused_result));
875 
876  /**
877  Fetch the names of the tables in the schema belonging to specific
878  storage engine. E.g., Object with dd::Table::hidden() == true will be
879  ignored.
880 
881  @param schema Schema for which to get component names.
882  @param engine Engine name of tables to match.
883  @param [out] names An std::vector containing all object names.
884 
885  @return true Failure (error is reported).
886  @return false Success.
887  */
888 
889  bool fetch_schema_table_names_by_engine(const Schema *schema,
890  const String_type &engine,
891  std::vector<String_type> *names) const
892  MY_ATTRIBUTE((warn_unused_result));
893 
894  /**
895  Fetch the names of the server tables in the schema. Ignore tables
896  hidden by SE.
897 
898  @param schema Schema for which to get component names.
899  @param [out] names An std::vector containing all object names.
900 
901  @return true Failure (error is reported).
902  @return false Success.
903  */
904 
906  const Schema *schema, std::vector<String_type> *names) const
907  MY_ATTRIBUTE((warn_unused_result));
908 
909  /**
910  Fetch all global component ids of the given type.
911 
912  @tparam T Type of components to get.
913  @param [out] ids An std::vector containing all component ids.
914 
915  @return true Failure (error is reported).
916  @return false Success.
917  */
918 
919  template <typename T>
920  bool fetch_global_component_ids(std::vector<Object_id> *ids) const
921  MY_ATTRIBUTE((warn_unused_result));
922 
923  /**
924  Fetch all global component names of the given type.
925 
926  @tparam T Type of components to get.
927  @param [out] names An std::vector containing all component names.
928 
929  @return true Failure (error is reported).
930  @return false Success.
931  */
932 
933  template <typename T>
934  bool fetch_global_component_names(std::vector<String_type> *names) const
935  MY_ATTRIBUTE((warn_unused_result));
936 
937  /**
938  Fetch all components in the schema.
939 
940  @tparam T Type of components to get.
941  @param schema Schema for which to get components.
942  @param [out] coll An std::vector containing all components.
943 
944  @return true Failure (error is reported).
945  @return false Success.
946  */
947 
948  template <typename T>
949  bool fetch_schema_components(const Schema *schema, Const_ptr_vec<T> *coll)
950  MY_ATTRIBUTE((warn_unused_result));
951 
952  /**
953  Fetch all global components of the given type.
954 
955  @tparam T Type of components to get.
956  @param [out] coll An std::vector containing all components.
957 
958  @return true Failure (error is reported).
959  @return false Success.
960  */
961 
962  template <typename T>
964  MY_ATTRIBUTE((warn_unused_result));
965 
966  /**
967  Fetch Object ids of all the views referencing base table/ view/ stored
968  function name specified in "schema"."name". The views are retrieved
969  using READ_UNCOMMITTED reads as the views could be changed by the same
970  statement (e.g. multi-table/-view RENAME TABLE).
971 
972  @tparam T Type of the object (View_table/View_routine)
973  to retrieve view names for.
974  @param schema Schema name.
975  @param tbl_or_sf_name Base table/ View/ Stored function name.
976  @param[out] view_ids Vector to store Object ids of all the views
977  referencing schema.name.
978 
979  @return true Failure (error is reported).
980  @return false Success.
981  */
982  template <typename T>
983  bool fetch_referencing_views_object_id(const char *schema,
984  const char *tbl_or_sf_name,
985  std::vector<Object_id> *view_ids) const
986  MY_ATTRIBUTE((warn_unused_result));
987 
988  /**
989  Fetch the names of tables (children) which have foreign keys
990  defined to the given table (parent).
991 
992  @param parent_schema Schema name of parent table.
993  @param parent_name Table name of parent table.
994  @param parent_engine Storage engine of parent table.
995  @param uncommitted Use READ_UNCOMMITTED isolation.
996  @param[out] children_schemas Schema names of child tables.
997  @param[out] children_names Table names of child tables.
998 
999  @return true Failure (error is reported).
1000  @return false Success.
1001 
1002  @note Child tables are identified by matching pairs of names.
1003 
1004  @note This is a temporary workaround until WL#6049. This function will
1005  *not* take any locks protecting against DDL changes. So the returned
1006  names could become invalid at any time - e.g. due to DROP DATABASE,
1007  DROP TABLE or DROP FOREIGN KEY.
1008  */
1009 
1010  bool fetch_fk_children_uncached(const String_type &parent_schema,
1011  const String_type &parent_name,
1012  const String_type &parent_engine,
1013  bool uncommitted,
1014  std::vector<String_type> *children_schemas,
1015  std::vector<String_type> *children_names)
1016  MY_ATTRIBUTE((warn_unused_result));
1017 
1018  /**
1019  Invalidate a cache entry.
1020 
1021  This function will acquire a table object based on the schema qualified
1022  table name, and call 'invalidate(table_object)'.
1023 
1024  @note This function only applies to tables yet.
1025 
1026  @param schema_name Name of the schema containing the table.
1027  @param table_name Name of the table.
1028 
1029  @retval false No error.
1030  @retval true Error (from handling a cache miss, or from
1031  failing to get an MDL lock).
1032  */
1033 
1034  bool invalidate(const String_type &schema_name, const String_type &table_name)
1035  MY_ATTRIBUTE((warn_unused_result));
1036 
1037  /**
1038  Invalidate a cache entry.
1039 
1040  This function will remove and delete an object from the shared cache,
1041  based on the id of the object. If the object id is present in the local
1042  object registry and the auto releaser, it will be removed from there as
1043  well.
1044 
1045  @note There is no particular consideration of already dropped or modified
1046  objects in this method.
1047 
1048  @tparam T Dictionary object type.
1049  @param object Object to be invalidated.
1050  */
1051 
1052  template <typename T>
1053  void invalidate(const T *object);
1054 
1055  /**
1056  Remove and delete an object from the cache and the dd tables.
1057 
1058  This function will remove the object from the local registry as well as
1059  the shared cache. This means that all keys associated with the object will
1060  be removed from the maps, and the cache element wrapper will be deleted.
1061  Afterwards, the object pointed to will also be deleted, and finally, the
1062  corresponding entry in the appropriate dd table is deleted. The object may
1063  not be accessed after calling this function.
1064 
1065  @sa invalidate()
1066 
1067  @note The object parameter is const since the contents of the object
1068  is not really changed, the object is just deleted. The method
1069  makes sure there is an exclusive meta data lock on the object
1070  name.
1071 
1072  @note The argument to this funcion may come from acquire(), and may
1073  be an instance that is present in the uncommitted registry,
1074  or in the committed registry. These use cases are handled by
1075  the implementation of the function. The ownership of the
1076  'object' is not changed, instead, a clone is created and
1077  added to the dropped registry.
1078 
1079  @tparam T Dictionary object type.
1080  @param object Object to be dropped.
1081 
1082  @retval false The operation was successful.
1083  @retval true There was an error.
1084  */
1085 
1086  template <typename T>
1087  bool drop(const T *object) MY_ATTRIBUTE((warn_unused_result));
1088 
1089  /**
1090  Store a new dictionary object.
1091 
1092  This function will write the object to the dd tables. The object is
1093  added neither to the dictionary client's object registry nor the shared
1094  cache.
1095 
1096  @note A precondition is that the object has not been acquired from the
1097  shared cache. For storing an object which is already in the cache,
1098  please use update().
1099 
1100  @note After calling store(), the submitted dictionary object can not be
1101  used for further calls to store(). It might be used as an argument
1102  to update(), but this is not recommended since calling update()
1103  will imply transferring object ownership to the dictionary client.
1104  Instead, please call 'acquire_for_modification()' to get a new
1105  object instance to use for modification and further updates.
1106 
1107  @tparam T Dictionary object type.
1108  @param object Object to be stored.
1109 
1110  @retval false The operation was successful.
1111  @retval true There was an error.
1112  */
1113 
1114  template <typename T>
1115  bool store(T *object) MY_ATTRIBUTE((warn_unused_result));
1116 
1117  /**
1118  Update a persisted dictionary object, but keep the shared cache unchanged.
1119 
1120  This function will store a dictionary object to the DD tables after
1121  verifying that an object with the same id already exists. The old object,
1122  which may be present in the shared dictionary cache, is not modified. To
1123  make the changes visible in the shared cache, please call
1124  remove_uncommuitted_objects().
1125 
1126  @note A precondition is that the object has been acquired from the
1127  shared cache indirectly by acquire_for_modification(). For storing
1128  an object which is not already in the cache, please use store().
1129 
1130  @note The new_object pointer submitted to this function, is owned by the
1131  auto delete vector. When registering the new object as an uncommitted
1132  object, the object must be removed from the auto delete vector.
1133 
1134  @tparam T Dictionary object type.
1135  @param new_object New object, not present in the cache, to be
1136  stored persistently.
1137 
1138  @retval false The operation was successful.
1139  @retval true There was an error.
1140  */
1141 
1142  template <typename T>
1143  bool update(T *new_object) MY_ATTRIBUTE((warn_unused_result));
1144 
1145  /**
1146  Remove the uncommitted objects from the client.
1147 
1148  Can also be used to explicitly throw the modified objects
1149  away before making any actions to compensate
1150  for a partially completed statement. Note that uncommitted objects
1151  are automatically removed once the topmost stack-allocated auto
1152  releaser goes out of scope, so calling this function in case of
1153  abort is only needed to make acquire return the old object again
1154  later in the same statement.
1155  */
1156 
1158 
1159  /**
1160  Remove the uncommitted objects from the client and put them into
1161  the shared cache, thereby making them visible to other clients.
1162  Should be called after commit to disk but before metadata locks
1163  are released.
1164  */
1165 
1166  void commit_modified_objects();
1167 
1168  /**
1169  Remove table statistics entries from mysql.table_stats and
1170  mysql.index_stats.
1171 
1172  @param schema_name Schema name of the table
1173  @param table_name Table name of which stats should be cleaned.
1174 
1175  @return true - on failure
1176  @return false - on success
1177  */
1178  bool remove_table_dynamic_statistics(const String_type &schema_name,
1179  const String_type &table_name)
1180  MY_ATTRIBUTE((warn_unused_result));
1181 
1182  /**
1183  Debug dump of a partition of the client and its registry to stderr.
1184 
1185  @tparam T Dictionary object type.
1186  */
1187 
1188  template <typename T>
1189  void dump() const;
1190 };
1191 
1192 } // namespace cache
1193 } // namespace dd
1194 
1195 // Functions declarations exported only to facilitate unit testing.
1199 } // namespace dd_cache_unittest
1200 
1201 #endif // DD_CACHE__DICTIONARY_CLIENT_INCLUDED
bool fetch_schema_table_names_by_engine(const Schema *schema, const String_type &engine, std::vector< String_type > *names) const
Fetch the names of the tables in the schema belonging to specific storage engine. ...
Definition: dictionary_client.cc:2006
std::vector< const T * > Const_ptr_vec
Definition: dictionary_client.h:472
ENGINE_HANDLE * engine
Definition: mock_server.c:28
bool store(T *object)
Store a new dictionary object.
Definition: dictionary_client.cc:2450
bool acquire_uncached_table_by_partition_se_private_id(const String_type &engine, Object_id se_partition_id, Table **table)
Retrieve a table object by its partition se private id.
Definition: dictionary_client.cc:1573
SPI_lru_cache * m_spi_lru_cache
Definition: dictionary_client.h:58
bool get_table_name_by_se_private_id(const String_type &engine, Object_id se_private_id, String_type *schema_name, String_type *table_name)
Retrieve schema and table name by the se private id of the table.
Definition: dictionary_client.cc:1751
Definition: object_key.h:37
Object_registry m_registry_committed
Definition: dictionary_client.h:245
Class to help releasing and deleting objects.
Definition: dictionary_client.h:173
bool invalidate(const String_type &schema_name, const String_type &table_name)
Invalidate a cache entry.
Definition: dictionary_client.cc:2315
void rollback_modified_objects()
Remove the uncommitted objects from the client.
Definition: dictionary_client.cc:2798
Char_string_template< String_type_allocator > String_type
Definition: string_type.h:50
Auto_releaser m_default_releaser
Definition: dictionary_client.h:249
Inherit from an instantiation of the template to allow forward-declaring in Dictionary_client.
Definition: dictionary_client.cc:705
Base class for dictionary objects which has single column integer primary key.
Definition: entity_object.h:47
size_t release(Object_registry *registry)
Mark all objects of a certain type as not being used by this client.
Definition: dictionary_client.cc:969
bool update(T *new_object)
Update a persisted dictionary object, but keep the shared cache unchanged.
Definition: dictionary_client.cc:2500
bool acquire_uncached_uncommitted(Object_id id, T **object)
Retrieve a possibly uncommitted object by its object id without caching it.
Definition: dictionary_client.cc:1171
Dictionary_client * m_client
Definition: dictionary_client.h:177
THD * m_thd
Definition: dictionary_client.h:248
bool acquire_uncached_table_by_se_private_id(const String_type &engine, Object_id se_private_id, Table **table)
Retrieve a table object by its se private id.
Definition: dictionary_client.cc:1523
void auto_delete(T *object)
Register an uncached object to be auto deleted.
Definition: dictionary_client.h:365
bool drop(const T *object)
Remove and delete an object from the cache and the dd tables.
Definition: dictionary_client.cc:2417
bool fetch_schema_table_names_not_hidden_by_se(const Schema *schema, std::vector< String_type > *names) const
Fetch the names of the server tables in the schema.
Definition: dictionary_client.cc:2025
Object_registry m_registry_uncommitted
Definition: dictionary_client.h:246
bool check_constraint_exists(const Schema &schema, const String_type &check_cons_name, bool *exists)
Check if schema contains check constraint with specified name.
Definition: dictionary_client.cc:1906
~Dictionary_client()
Definition: dictionary_client.cc:1044
void remove_uncommitted_objects(bool commit_to_shared_cache)
Remove the uncommitted objects from the client and (depending on the parameter) put them into the sha...
Definition: dictionary_client.cc:2687
Object_registry m_registry_dropped
Definition: dictionary_client.h:247
bool acquire_for_modification(Object_id id, T **object)
Retrieve an object by its object id.
Definition: dictionary_client.cc:1104
Dictionary_client(THD *thd)
Definition: dictionary_client.cc:1034
void acquire_uncommitted(const K &key, T **object, bool *dropped)
Get an uncommitted dictionary object that can be modified safely.
Definition: dictionary_client.cc:930
bool fetch_global_components(Const_ptr_vec< T > *coll)
Fetch all global components of the given type.
Definition: dictionary_client.cc:2163
void register_uncommitted_object(T *object)
Transfer object ownership from caller to Dictionary_client, and register the object as uncommitted...
Definition: dictionary_client.cc:2588
void dump() const
Debug dump of a partition of the client and its registry to stderr.
Definition: dictionary_client.cc:2827
#define DBUG_ASSERT(A)
Definition: my_dbug.h:197
Auto_releaser()
Definition: dictionary_client.cc:758
~SPI_lru_cache_owner_ptr()
Calls delete on m_spi_lru_cache unless nullptr.
Definition: dictionary_client.cc:707
bool acquire(const K &key, const T **object, bool *local_committed, bool *local_uncommitted)
Get a dictionary object.
Definition: dictionary_client.cc:844
bool fetch_schema_component_names(const Schema *schema, std::vector< String_type > *names) const
Fetch the names of the components in the schema.
Definition: dictionary_client.cc:2051
SPI_lru_cache * operator->()
Creates cache on demand if m_spi_lru_cache is nullptr.
Definition: dictionary_client.cc:713
void transfer_release(const T *object)
Transfer an object from the current to the previous auto releaser.
Definition: dictionary_client.cc:727
A smart-pointer for managing an SPI_lru_cache even when it is only forward declared.
Definition: dictionary_client.h:57
void put(Cache_element< T > *element)
Add a new element to the registry.
Definition: object_registry.h:277
bool fetch_fk_children_uncached(const String_type &parent_schema, const String_type &parent_name, const String_type &parent_engine, bool uncommitted, std::vector< String_type > *children_schemas, std::vector< String_type > *children_names)
Fetch the names of tables (children) which have foreign keys defined to the given table (parent)...
Definition: dictionary_client.cc:2224
Implementation of a dictionary client.
Definition: dictionary_client.h:143
bool fetch(Const_ptr_vec< Object_type > *coll, const Object_key *object_key)
Fetch objects from DD tables that match the supplied key.
Definition: dictionary_client.cc:2062
void no_auto_delete(T *object)
Remove an object from the auto delete vector.
Definition: dictionary_client.h:394
bool fetch_global_component_ids(std::vector< Object_id > *ids) const
Fetch all global component ids of the given type.
Definition: dictionary_client.cc:1965
bool get_table_name_by_trigger_name(const Schema &schema, const String_type &trigger_name, String_type *table_name)
Retrieve a table name of a given trigger name and schema.
Definition: dictionary_client.cc:1836
Auto_releaser * m_prev
Definition: dictionary_client.h:179
bool is_nullptr() const
Definition: dictionary_client.h:81
Definition: dictionary_client.h:145
bool acquire_uncached(Object_id id, T **object)
Retrieve an object by its object id without caching it.
Definition: dictionary_client.cc:1140
Header for compiler-dependent features.
bool fetch_referencing_views_object_id(const char *schema, const char *tbl_or_sf_name, std::vector< Object_id > *view_ids) const
Fetch Object ids of all the views referencing base table/ view/ stored function name specified in "sc...
Definition: dictionary_client.cc:2175
unsigned long long Object_id
Definition: object_id.h:30
bool remove(const String_type &fname)
Remove a file name from the file system.
Definition: sdi_file.cc:283
static const char * key
Definition: suite_stubs.c:14
void dump() const
Definition: dictionary_client.cc:806
std::vector< Entity_object * > m_uncached_objects
Definition: dictionary_client.h:244
SPI_lru_cache_owner_ptr m_no_table_spids
Se-private ids known not to exist in either TABLES or PARTITIONS or both.
Definition: dictionary_client.h:256
bool is_cached(const dd::cache::SPI_lru_cache_owner_ptr &c, dd::Object_id id)
Definition: dictionary_client.cc:3119
bool remove_table_dynamic_statistics(const String_type &schema_name, const String_type &table_name)
Remove table statistics entries from mysql.table_stats and mysql.index_stats.
Definition: dictionary_client.cc:1666
bool fetch_schema_components(const Schema *schema, Const_ptr_vec< T > *coll)
Fetch all components in the schema.
Definition: dictionary_client.cc:2146
void get(const K &key, Cache_element< T > **element) const
Get the element corresponding to the given key.
Definition: object_registry.h:261
bool fetch_global_component_names(std::vector< String_type > *names) const
Fetch all global component names of the given type.
Definition: dictionary_client.cc:1986
#define NULL
Definition: types.h:55
void auto_release(Cache_element< T > *element)
Register an object to be auto released.
Definition: dictionary_client.h:189
~Auto_releaser()
Definition: dictionary_client.cc:769
Definition: schema.h:61
The version of the current data dictionary table definitions.
Definition: dictionary_client.h:39
bool check_foreign_key_exists(const Schema &schema, const String_type &foreign_key_name, bool *exists)
Check if schema contains foreign key with specified name.
Definition: dictionary_client.cc:1881
void register_dropped_object(T *object)
Transfer object ownership from caller to Dictionary_client, and register the object as dropped...
Definition: dictionary_client.cc:2624
Auto_releaser * m_current_releaser
Definition: dictionary_client.h:250
bool get_table_name_by_partition_se_private_id(const String_type &engine, Object_id se_partition_id, String_type *schema_name, String_type *table_name)
Retrieve schema and table name by the se private id of the partition.
Definition: dictionary_client.cc:1796
Definition: table.h:43
static int exists(node_address *name, node_list const *nodes, u_int with_uid)
Definition: node_list.c:108
Definition: dictionary_client.h:1196
Object_registry m_release_registry
Definition: dictionary_client.h:178
void insert(dd::cache::SPI_lru_cache_owner_ptr &c, dd::Object_id id)
Definition: dictionary_client.cc:3116
const SPI_lru_cache * operator->() const
Const overload which does not create cache on demand, but merely returns the pointer.
Definition: dictionary_client.h:75
void commit_modified_objects()
Remove the uncommitted objects from the client and put them into the shared cache, thereby making them visible to other clients.
Definition: dictionary_client.cc:2811
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_class.h:778
const char * table_name
Definition: rules_table_service.cc:55
Object registry containing several maps.
Definition: object_registry.h:60