MySQL  8.0.16
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 #endif
378 
379  m_uncached_objects.push_back(object);
380  }
381 
382  /**
383  Remove an object from the auto delete vector.
384 
385  @tparam T Dictionary object type.
386  @param object Dictionary object to keep.
387  */
388 
389  template <typename T>
390  void no_auto_delete(T *object) {
391 #ifndef DBUG_OFF
392  // Make sure the object has been registered as uncommitted.
395  static_cast<const typename T::Cache_partition *>(object), &element);
396  DBUG_ASSERT(element != nullptr);
397 #endif
399  m_uncached_objects.end(), object),
400  m_uncached_objects.end());
401  }
402 
403  /**
404  Transfer object ownership from caller to Dictionary_client,
405  and register the object as uncommitted.
406 
407  This is intended for objects created by the caller that should
408  be managed by Dictionary_client. Transferring an object in this
409  way will make it accessible by calling acquire().
410 
411  This method takes a non-const argument as it only makes
412  sense to register objects not acquired from the shared cache.
413 
414  @tparam T Dictionary object type.
415  @param object Object to transfer ownership.
416  */
417 
418  template <typename T>
419  void register_uncommitted_object(T *object);
420 
421  /**
422  Transfer object ownership from caller to Dictionary_client,
423  and register the object as dropped.
424 
425  This method is used internally by the Dictionary_client for
426  keeping track of dropped objects. This is needed before
427  transaction commit if an attempt is made to acquire the
428  dropped object, to avoid consulting the shared cache, which
429  might contaminate the cache due to a cache miss (handled with
430  isolation level READ_COMMITTED). Instead of consulting the
431  shared cache, this Dictionary_client will recognize that the
432  object is dropped, and return a nullptr.
433 
434  This method takes a non-const argument as it only makes
435  sense to register objects not acquired from the shared cache.
436 
437  @tparam T Dictionary object type.
438  @param object Object to transfer ownership.
439  */
440 
441  template <typename T>
442  void register_dropped_object(T *object);
443 
444  /**
445  Remove the uncommitted objects from the client and (depending
446  on the parameter) put them into the shared cache,
447  thereby making them visible to other clients. Should be called
448  after commit to disk but before metadata locks are released.
449 
450  Can also be called after rollback in order to explicitly throw
451  the modified objects away before making any actions to compensate
452  for a partially completed statement. Note that uncommitted objects
453  are automatically removed once the topmost stack-allocated auto
454  releaser goes out of scope, so calling this function in case of
455  abort is only needed to make acquire return the old object again
456  later in the same statement.
457 
458  @param commit_to_shared_cache
459  If true, uncommitted objects will
460  be put into the shared cache.
461  @tparam T Dictionary object type.
462  */
463 
464  template <typename T>
465  void remove_uncommitted_objects(bool commit_to_shared_cache);
466 
467  template <typename T>
468  using Const_ptr_vec = std::vector<const T *>;
469 
470  /**
471  Fetch objects from DD tables that match the supplied key.
472 
473  @tparam Object_type Type of object to fetch.
474  @param coll Vector to fill with objects.
475  @param object_key The search key. If key is not supplied, then
476  we do full index scan.
477 
478  @return false Success.
479  @return true Failure (error is reported).
480  */
481 
482  template <typename Object_type>
483  bool fetch(Const_ptr_vec<Object_type> *coll, const Object_key *object_key)
484  MY_ATTRIBUTE((warn_unused_result));
485 
486  public:
487  // Initialize an instance with a default auto releaser.
488  explicit Dictionary_client(THD *thd);
489 
490  // Make sure all objects are released.
492 
493  /**
494  Retrieve an object by its object id.
495 
496  @tparam T Dictionary object type.
497  @param id Object id to retrieve.
498  @param [out] object Dictionary object, if present; otherwise NULL.
499 
500  @retval false No error.
501  @retval true Error (from handling a cache miss).
502  */
503 
504  template <typename T>
505  bool acquire(Object_id id, const T **object)
506  MY_ATTRIBUTE((warn_unused_result));
507 
508  /**
509  Retrieve an object by its object id.
510 
511  This function returns a cloned object that can be modified.
512 
513  @tparam T Dictionary object type.
514  @param id Object id to retrieve.
515  @param [out] object Dictionary object, if present; otherwise NULL.
516 
517  @retval false No error.
518  @retval true Error (from handling a cache miss).
519  */
520 
521  template <typename T>
522  bool acquire_for_modification(Object_id id, T **object)
523  MY_ATTRIBUTE((warn_unused_result));
524 
525  /**
526  Retrieve an object by its object id without caching it.
527 
528  The object is not cached but owned by the dictionary client, who
529  makes sure it is deleted. The object must not be released, and may not
530  be used as a parameter to the other dictionary client methods since it is
531  not known by the object registry.
532 
533  @tparam T Dictionary object type.
534  @param id Object id to retrieve.
535  @param [out] object Dictionary object, if present; otherwise NULL.
536 
537  @retval false No error.
538  @retval true Error (from reading the dictionary tables).
539  */
540 
541  template <typename T>
542  bool acquire_uncached(Object_id id, T **object)
543  MY_ATTRIBUTE((warn_unused_result));
544 
545  /**
546  Retrieve a possibly uncommitted object by its object id without caching it.
547 
548  The object is not cached but owned by the dictionary client, who
549  makes sure it is deleted. The object must not be released, and may not
550  be used as a parameter to the other dictionary client methods since it is
551  not known by the object registry.
552 
553  When the object is read from the persistent tables, the transaction
554  isolation level is READ UNCOMMITTED. This is necessary to be able to
555  read uncommitted data from an earlier stage of the same session.
556 
557  @tparam T Dictionary object type.
558  @param id Object id to retrieve.
559  @param [out] object Dictionary object, if present; otherwise nullptr.
560 
561  @retval false No error.
562  @retval true Error (from reading the dictionary tables).
563  */
564 
565  template <typename T>
566  bool acquire_uncached_uncommitted(Object_id id, T **object)
567  MY_ATTRIBUTE((warn_unused_result));
568 
569  /**
570  Retrieve an object by its name.
571 
572  @tparam T Dictionary object type.
573  @param object_name Name of the object.
574  @param [out] object Dictionary object, if present; otherwise NULL.
575 
576  @retval false No error.
577  @retval true Error (from handling a cache miss).
578  */
579 
580  template <typename T>
581  bool acquire(const String_type &object_name, const T **object)
582  MY_ATTRIBUTE((warn_unused_result));
583 
584  /**
585  Retrieve an object by its name.
586 
587  This function returns a cloned object that can be modified.
588 
589  @tparam T Dictionary object type.
590  @param object_name Name of the object.
591  @param [out] object Dictionary object, if present; otherwise NULL.
592 
593  @retval false No error.
594  @retval true Error (from handling a cache miss).
595  */
596 
597  template <typename T>
598  bool acquire_for_modification(const String_type &object_name, T **object)
599  MY_ATTRIBUTE((warn_unused_result));
600 
601  /**
602  Retrieve an object by its schema- and object name.
603 
604  @note We will acquire an IX-lock on the schema name unless we already
605  have one. This is needed for proper synchronization with schema
606  DDL in cases where the table does not exist, and where the
607  indirect synchronization based on table names therefore will not
608  apply.
609 
610  @todo TODO: We should change the MDL acquisition (see above) for a more
611  long term solution.
612 
613  @tparam T Dictionary object type.
614  @param schema_name Name of the schema containing the object.
615  @param object_name Name of the object.
616  @param [out] object Dictionary object, if present; otherwise NULL.
617 
618  @retval false No error.
619  @retval true Error (from handling a cache miss, or from
620  failing to get an MDL lock).
621  */
622 
623  template <typename T>
624  bool acquire(const String_type &schema_name, const String_type &object_name,
625  const T **object) MY_ATTRIBUTE((warn_unused_result));
626 
627  /**
628  Retrieve an object by its schema- and object name.
629 
630  This function returns a cloned object that can be modified.
631 
632  @note We will acquire an IX-lock on the schema name unless we already
633  have one. This is needed for proper synchronization with schema
634  DDL in cases where the table does not exist, and where the
635  indirect synchronization based on table names therefore will not
636  apply.
637 
638  @todo TODO: We should change the MDL acquisition (see above) for a more
639  long term solution.
640 
641  @tparam T Dictionary object type.
642  @param schema_name Name of the schema containing the object.
643  @param object_name Name of the object.
644  @param [out] object Dictionary object, if present; otherwise NULL.
645 
646  @retval false No error.
647  @retval true Error (from handling a cache miss, or from
648  failing to get an MDL lock).
649  */
650 
651  template <typename T>
652  bool acquire_for_modification(const String_type &schema_name,
653  const String_type &object_name, T **object)
654  MY_ATTRIBUTE((warn_unused_result));
655 
656  /**
657  Retrieve an object by its schema- and object name.
658 
659  @note We will acquire an IX-lock on the schema name unless we already
660  have one. This is needed for proper synchronization with schema
661  DDL in cases where the table does not exist, and where the
662  indirect synchronization based on table names therefore will not
663  apply.
664 
665  @note This is a variant of the method above asking for an object of type
666  T, and hence using T's functions for updating name keys etc.
667  This function, however, returns the instance pointed to as type
668  T::Cache_partition to ease handling of various subtypes
669  of the same base type.
670 
671  @todo TODO: We should change the MDL acquisition (see above) for a more
672  long term solution.
673 
674  @tparam T Dictionary object type.
675  @param schema_name Name of the schema containing the object.
676  @param object_name Name of the object.
677  @param [out] object Dictionary object, if present; otherwise NULL.
678 
679  @retval false No error.
680  @retval true Error (from handling a cache miss, or from
681  failing to get an MDL lock).
682  */
683 
684  template <typename T>
685  bool acquire(const String_type &schema_name, const String_type &object_name,
686  const typename T::Cache_partition **object)
687  MY_ATTRIBUTE((warn_unused_result));
688 
689  /**
690  Retrieve an object by its schema- and object name.
691 
692  This function returns a cloned object that can be modified.
693 
694  @note We will acquire an IX-lock on the schema name unless we already
695  have one. This is needed for proper synchronization with schema
696  DDL in cases where the table does not exist, and where the
697  indirect synchronization based on table names therefore will not
698  apply.
699 
700  @note This is a variant of the method above asking for an object of type
701  T, and hence using T's functions for updating name keys etc.
702  This function, however, returns the instance pointed to as type
703  T::Cache_partition to ease handling of various subtypes
704  of the same base type.
705 
706  @todo TODO: We should change the MDL acquisition (see above) for a more
707  long term solution.
708 
709  @tparam T Dictionary object type.
710  @param schema_name Name of the schema containing the object.
711  @param object_name Name of the object.
712  @param [out] object Dictionary object, if present; otherwise NULL.
713 
714  @retval false No error.
715  @retval true Error (from handling a cache miss, or from
716  failing to get an MDL lock).
717  */
718 
719  template <typename T>
720  bool acquire_for_modification(const String_type &schema_name,
721  const String_type &object_name,
722  typename T::Cache_partition **object)
723  MY_ATTRIBUTE((warn_unused_result));
724 
725  /**
726  Retrieve a table object by its se private id.
727 
728  @param engine Name of the engine storing the table.
729  @param se_private_id SE private id of the table.
730  @param [out] table Table object, if present; otherwise NULL.
731 
732  @note The object must be acquired uncached since we cannot acquire a
733  metadata lock in advance since we do not know the table name.
734  Thus, the returned table object is owned by the caller, who must
735  make sure it is deleted.
736 
737  @retval false No error or if object was not found.
738  @retval true Error (e.g. from reading DD tables, or if an
739  object of a wrong type was found).
740  */
741 
743  Object_id se_private_id,
744  Table **table)
745  MY_ATTRIBUTE((warn_unused_result));
746 
747  /**
748  Retrieve a table object by its partition se private id.
749 
750  @param engine Name of the engine storing the table.
751  @param se_partition_id SE private id of the partition.
752  @param [out] table Table object, if present; otherwise NULL.
753 
754  @retval false No error or if object was not found.
755  @retval true Error (from handling a cache miss).
756  */
757 
759  const String_type &engine, Object_id se_partition_id, Table **table)
760  MY_ATTRIBUTE((warn_unused_result));
761 
762  /**
763  Retrieve schema and table name by the se private id of the table.
764 
765  @param engine Name of the engine storing the table.
766  @param se_private_id SE private id of the table.
767  @param [out] schema_name Name of the schema containing the table.
768  @param [out] table_name Name of the table.
769 
770  @retval false No error OR if object was not found.
771  The OUT params will be set to empty
772  string when object is not found.
773  @retval true Error.
774  */
775 
777  Object_id se_private_id,
778  String_type *schema_name,
780  MY_ATTRIBUTE((warn_unused_result));
781 
782  /**
783  Retrieve schema and table name by the se private id of the partition.
784 
785  @param engine Name of the engine storing the table.
786  @param se_partition_id SE private id of the table partition.
787  @param [out] schema_name Name of the schema containing the table.
788  @param [out] table_name Name of the table.
789 
790  @retval false No error or if object was not found.
791  The OUT params will be set to empty
792  string when object is not found.
793  @retval true Error.
794  */
795 
797  Object_id se_partition_id,
798  String_type *schema_name,
800  MY_ATTRIBUTE((warn_unused_result));
801 
802  /**
803  Retrieve a table name of a given trigger name and schema.
804 
805  @param schema Schema containing the trigger.
806  @param trigger_name Name of the trigger.
807  @param [out] table_name Name of the table for which
808  trigger belongs to. Empty string if
809  there is no such trigger.
810 
811  @retval false No error.
812  @retval true Error.
813  */
814 
815  bool get_table_name_by_trigger_name(const Schema &schema,
816  const String_type &trigger_name,
818  MY_ATTRIBUTE((warn_unused_result));
819 
820  /**
821  Check if schema contains foreign key with specified name.
822 
823  @param schema Schema containing the foreign key.
824  @param foreign_key_name Name of the foreign key.
825  @param [out] exists Set to true if foreign key with
826  the name provided exists in the
827  schema, false otherwise.
828 
829  @retval false No error.
830  @retval true Error.
831  */
832 
833  bool check_foreign_key_exists(const Schema &schema,
834  const String_type &foreign_key_name,
835  bool *exists)
836  MY_ATTRIBUTE((warn_unused_result));
837 
838  /**
839  Check if schema contains check constraint with specified name.
840 
841  @param schema Schema containing the check constraint.
842  @param check_cons_name Name of the check constraint.
843  @param [out] exists Set to true if check constraint with
844  the name provided exists in the
845  schema, false otherwise.
846 
847  @retval false No error.
848  @retval true Error.
849  */
850 
851  bool check_constraint_exists(const Schema &schema,
852  const String_type &check_cons_name,
853  bool *exists);
854 
855  /**
856  Fetch the names of the components in the schema. Hidden components are
857  ignored. E.g., Object with dd::Table::hidden() == true will be ignored.
858 
859  @note This is an intermediate solution which will be replaced
860  by the implementation in WL#6599.
861 
862  @tparam T Type of object to retrieve names for.
863  @param schema Schema for which to get component names.
864  @param [out] names An std::vector containing all object names.
865 
866  @return true Failure (error is reported).
867  @return false Success.
868  */
869 
870  template <typename T>
871  bool fetch_schema_component_names(const Schema *schema,
872  std::vector<String_type> *names) const
873  MY_ATTRIBUTE((warn_unused_result));
874 
875  /**
876  Fetch all global component ids of the given type.
877 
878  @tparam T Type of components to get.
879  @param [out] ids An std::vector containing all component ids.
880 
881  @return true Failure (error is reported).
882  @return false Success.
883  */
884 
885  template <typename T>
886  bool fetch_global_component_ids(std::vector<Object_id> *ids) const
887  MY_ATTRIBUTE((warn_unused_result));
888 
889  /**
890  Fetch all global component names of the given type.
891 
892  @tparam T Type of components to get.
893  @param [out] names An std::vector containing all component names.
894 
895  @return true Failure (error is reported).
896  @return false Success.
897  */
898 
899  template <typename T>
900  bool fetch_global_component_names(std::vector<String_type> *names) const
901  MY_ATTRIBUTE((warn_unused_result));
902 
903  /**
904  Fetch all components in the schema.
905 
906  @tparam T Type of components to get.
907  @param schema Schema for which to get components.
908  @param [out] coll An std::vector containing all components.
909 
910  @return true Failure (error is reported).
911  @return false Success.
912  */
913 
914  template <typename T>
915  bool fetch_schema_components(const Schema *schema, Const_ptr_vec<T> *coll)
916  MY_ATTRIBUTE((warn_unused_result));
917 
918  /**
919  Fetch all global components of the given type.
920 
921  @tparam T Type of components to get.
922  @param [out] coll An std::vector containing all components.
923 
924  @return true Failure (error is reported).
925  @return false Success.
926  */
927 
928  template <typename T>
930  MY_ATTRIBUTE((warn_unused_result));
931 
932  /**
933  Fetch Object ids of all the views referencing base table/ view/ stored
934  function name specified in "schema"."name". The views are retrieved
935  using READ_UNCOMMITTED reads as the views could be changed by the same
936  statement (e.g. multi-table/-view RENAME TABLE).
937 
938  @tparam T Type of the object (View_table/View_routine)
939  to retrieve view names for.
940  @param schema Schema name.
941  @param tbl_or_sf_name Base table/ View/ Stored function name.
942  @param[out] view_ids Vector to store Object ids of all the views
943  referencing schema.name.
944 
945  @return true Failure (error is reported).
946  @return false Success.
947  */
948  template <typename T>
949  bool fetch_referencing_views_object_id(const char *schema,
950  const char *tbl_or_sf_name,
951  std::vector<Object_id> *view_ids) const
952  MY_ATTRIBUTE((warn_unused_result));
953 
954  /**
955  Fetch the names of tables (children) which have foreign keys
956  defined to the given table (parent).
957 
958  @param parent_schema Schema name of parent table.
959  @param parent_name Table name of parent table.
960  @param parent_engine Storage engine of parent table.
961  @param uncommitted Use READ_UNCOMMITTED isolation.
962  @param[out] children_schemas Schema names of child tables.
963  @param[out] children_names Table names of child tables.
964 
965  @return true Failure (error is reported).
966  @return false Success.
967 
968  @note Child tables are identified by matching pairs of names.
969 
970  @note This is a temporary workaround until WL#6049. This function will
971  *not* take any locks protecting against DDL changes. So the returned
972  names could become invalid at any time - e.g. due to DROP DATABASE,
973  DROP TABLE or DROP FOREIGN KEY.
974  */
975 
976  bool fetch_fk_children_uncached(const String_type &parent_schema,
977  const String_type &parent_name,
978  const String_type &parent_engine,
979  bool uncommitted,
980  std::vector<String_type> *children_schemas,
981  std::vector<String_type> *children_names)
982  MY_ATTRIBUTE((warn_unused_result));
983 
984  /**
985  Invalidate a cache entry.
986 
987  This function will acquire a table object based on the schema qualified
988  table name, and call 'invalidate(table_object)'.
989 
990  @note This function only applies to tables yet.
991 
992  @param schema_name Name of the schema containing the table.
993  @param table_name Name of the table.
994 
995  @retval false No error.
996  @retval true Error (from handling a cache miss, or from
997  failing to get an MDL lock).
998  */
999 
1000  bool invalidate(const String_type &schema_name, const String_type &table_name)
1001  MY_ATTRIBUTE((warn_unused_result));
1002 
1003  /**
1004  Invalidate a cache entry.
1005 
1006  This function will remove and delete an object from the shared cache,
1007  based on the id of the object. If the object id is present in the local
1008  object registry and the auto releaser, it will be removed from there as
1009  well.
1010 
1011  @note There is no particular consideration of already dropped or modified
1012  objects in this method.
1013 
1014  @tparam T Dictionary object type.
1015  @param object Object to be invalidated.
1016  */
1017 
1018  template <typename T>
1019  void invalidate(const T *object);
1020 
1021  /**
1022  Remove and delete an object from the cache and the dd tables.
1023 
1024  This function will remove the object from the local registry as well as
1025  the shared cache. This means that all keys associated with the object will
1026  be removed from the maps, and the cache element wrapper will be deleted.
1027  Afterwards, the object pointed to will also be deleted, and finally, the
1028  corresponding entry in the appropriate dd table is deleted. The object may
1029  not be accessed after calling this function.
1030 
1031  @sa invalidate()
1032 
1033  @note The object parameter is const since the contents of the object
1034  is not really changed, the object is just deleted. The method
1035  makes sure there is an exclusive meta data lock on the object
1036  name.
1037 
1038  @note The argument to this funcion may come from acquire(), and may
1039  be an instance that is present in the uncommitted registry,
1040  or in the committed registry. These use cases are handled by
1041  the implementation of the function. The ownership of the
1042  'object' is not changed, instead, a clone is created and
1043  added to the dropped registry.
1044 
1045  @tparam T Dictionary object type.
1046  @param object Object to be dropped.
1047 
1048  @retval false The operation was successful.
1049  @retval true There was an error.
1050  */
1051 
1052  template <typename T>
1053  bool drop(const T *object) MY_ATTRIBUTE((warn_unused_result));
1054 
1055  /**
1056  Store a new dictionary object.
1057 
1058  This function will write the object to the dd tables. The object is
1059  added neither to the dictionary client's object registry nor the shared
1060  cache.
1061 
1062  @note A precondition is that the object has not been acquired from the
1063  shared cache. For storing an object which is already in the cache,
1064  please use update().
1065 
1066  @note After calling store(), the submitted dictionary object can not be
1067  used for further calls to store(). It might be used as an argument
1068  to update(), but this is not recommended since calling update()
1069  will imply transferring object ownership to the dictionary client.
1070  Instead, please call 'acquire_for_modification()' to get a new
1071  object instance to use for modification and further updates.
1072 
1073  @tparam T Dictionary object type.
1074  @param object Object to be stored.
1075 
1076  @retval false The operation was successful.
1077  @retval true There was an error.
1078  */
1079 
1080  template <typename T>
1081  bool store(T *object) MY_ATTRIBUTE((warn_unused_result));
1082 
1083  /**
1084  Update a persisted dictionary object, but keep the shared cache unchanged.
1085 
1086  This function will store a dictionary object to the DD tables after
1087  verifying that an object with the same id already exists. The old object,
1088  which may be present in the shared dictionary cache, is not modified. To
1089  make the changes visible in the shared cache, please call
1090  remove_uncommuitted_objects().
1091 
1092  @note A precondition is that the object has been acquired from the
1093  shared cache indirectly by acquire_for_modification(). For storing
1094  an object which is not already in the cache, please use store().
1095 
1096  @note The new_object pointer submitted to this function, is owned by the
1097  auto delete vector. When registering the new object as an uncommitted
1098  object, the object must be removed from the auto delete vector.
1099 
1100  @tparam T Dictionary object type.
1101  @param new_object New object, not present in the cache, to be
1102  stored persistently.
1103 
1104  @retval false The operation was successful.
1105  @retval true There was an error.
1106  */
1107 
1108  template <typename T>
1109  bool update(T *new_object) MY_ATTRIBUTE((warn_unused_result));
1110 
1111  /**
1112  Remove the uncommitted objects from the client.
1113 
1114  Can also be used to explicitly throw the modified objects
1115  away before making any actions to compensate
1116  for a partially completed statement. Note that uncommitted objects
1117  are automatically removed once the topmost stack-allocated auto
1118  releaser goes out of scope, so calling this function in case of
1119  abort is only needed to make acquire return the old object again
1120  later in the same statement.
1121  */
1122 
1124 
1125  /**
1126  Remove the uncommitted objects from the client and put them into
1127  the shared cache, thereby making them visible to other clients.
1128  Should be called after commit to disk but before metadata locks
1129  are released.
1130  */
1131 
1132  void commit_modified_objects();
1133 
1134  /**
1135  Remove table statistics entries from mysql.table_stats and
1136  mysql.index_stats.
1137 
1138  @param schema_name Schema name of the table
1139  @param table_name Table name of which stats should be cleaned.
1140 
1141  @return true - on failure
1142  @return false - on success
1143  */
1144  bool remove_table_dynamic_statistics(const String_type &schema_name,
1145  const String_type &table_name)
1146  MY_ATTRIBUTE((warn_unused_result));
1147 
1148  /**
1149  Debug dump of a partition of the client and its registry to stderr.
1150 
1151  @tparam T Dictionary object type.
1152  */
1153 
1154  template <typename T>
1155  void dump() const;
1156 };
1157 
1158 } // namespace cache
1159 } // namespace dd
1160 
1161 // Functions declarations exported only to facilitate unit testing.
1165 } // namespace dd_cache_unittest
1166 
1167 #endif // DD_CACHE__DICTIONARY_CLIENT_INCLUDED
std::vector< const T * > Const_ptr_vec
Definition: dictionary_client.h:468
ENGINE_HANDLE * engine
Definition: mock_server.c:28
bool store(T *object)
Store a new dictionary object.
Definition: dictionary_client.cc:2409
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:1539
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:1717
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:2274
void rollback_modified_objects()
Remove the uncommitted objects from the client.
Definition: dictionary_client.cc:2757
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:671
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:935
Sergei Dialog Client Authentication NULL
Definition: dialog.cc:352
bool update(T *new_object)
Update a persisted dictionary object, but keep the shared cache unchanged.
Definition: dictionary_client.cc:2459
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:1137
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:1489
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:2376
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:1872
~Dictionary_client()
Definition: dictionary_client.cc:1010
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:2646
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:1070
Dictionary_client(THD *thd)
Definition: dictionary_client.cc:1000
void acquire_uncommitted(const K &key, T **object, bool *dropped)
Get an uncommitted dictionary object that can be modified safely.
Definition: dictionary_client.cc:896
bool fetch_global_components(Const_ptr_vec< T > *coll)
Fetch all global components of the given type.
Definition: dictionary_client.cc:2122
void register_uncommitted_object(T *object)
Transfer object ownership from caller to Dictionary_client, and register the object as uncommitted...
Definition: dictionary_client.cc:2547
void dump() const
Debug dump of a partition of the client and its registry to stderr.
Definition: dictionary_client.cc:2786
#define DBUG_ASSERT(A)
Definition: my_dbug.h:128
Auto_releaser()
Definition: dictionary_client.cc:724
~SPI_lru_cache_owner_ptr()
Calls delete on m_spi_lru_cache unless nullptr.
Definition: dictionary_client.cc:673
bool acquire(const K &key, const T **object, bool *local_committed, bool *local_uncommitted)
Get a dictionary object.
Definition: dictionary_client.cc:810
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:1973
SPI_lru_cache * operator->()
Creates cache on demand if m_spi_lru_cache is nullptr.
Definition: dictionary_client.cc:679
void transfer_release(const T *object)
Transfer an object from the current to the previous auto releaser.
Definition: dictionary_client.cc:693
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:2183
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:2021
void no_auto_delete(T *object)
Remove an object from the auto delete vector.
Definition: dictionary_client.h:390
bool fetch_global_component_ids(std::vector< Object_id > *ids) const
Fetch all global component ids of the given type.
Definition: dictionary_client.cc:1931
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:1802
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:1106
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:2134
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:772
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:3081
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:1632
bool fetch_schema_components(const Schema *schema, Const_ptr_vec< T > *coll)
Fetch all components in the schema.
Definition: dictionary_client.cc:2105
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:1952
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:735
Definition: schema.h:60
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:1847
void register_dropped_object(T *object)
Transfer object ownership from caller to Dictionary_client, and register the object as dropped...
Definition: dictionary_client.cc:2583
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:1762
Definition: table.h:43
Definition: dictionary_client.h:1162
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:3078
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:2770
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_class.h:776
const char * table_name
Definition: rules_table_service.cc:55
Object registry containing several maps.
Definition: object_registry.h:60