MySQL 8.0.31
Source Code Documentation
dd::cache::Shared_multi_map< T > Class Template Reference

Implementation of a shared set of maps for a given object type. More...

#include <shared_multi_map.h>

Inheritance diagram for dd::cache::Shared_multi_map< T >:
[legend]

Classes

class  Autolocker
 

Public Member Functions

 Shared_multi_map ()
 Initialize the mutex and condition variable. More...
 
 ~Shared_multi_map ()
 Destroy the mutex and condition variable. More...
 
void shutdown ()
 Shutdown the shared map. More...
 
bool reset (THD *thd)
 Reset the shared map. More...
 
void set_capacity (size_t capacity)
 Set capacity of the shared map. More...
 
template<typename K >
bool available (const K &key)
 Check if an element with the given key is available. More...
 
template<typename K >
bool get (const K &key, Cache_element< T > **element)
 Get a wrapper element from the map handling the given key type. More...
 
template<typename K >
void put (const K *key, const T *object, Cache_element< T > **element)
 Put a new object and element wrapper into the map. More...
 
void release (Cache_element< T > *element)
 Release one element. More...
 
void drop (Cache_element< T > *element)
 Delete an element from the map. More...
 
template<typename K >
void drop_if_present (const K &key)
 Delete an object corresponding to the key from the map if exists. More...
 
void replace (Cache_element< T > *element, const T *object)
 Replace the object and re-generate the keys for an element. More...
 
void dump () const
 Debug dump of the shared multi map to stderr. More...
 

Private Member Functions

template<typename K >
Element_map< K, Cache_element< T > > * m_map ()
 Template helper function getting the element map. More...
 
template<typename K >
const Element_map< K, Cache_element< T > > * m_map () const
 
template<typename K >
Cache_element< T > * use_if_present (const K &key)
 Template function to find an element and mark it as used. More...
 
void remove (Cache_element< T > *element, Autolocker *lock)
 Remove an element from the map. More...
 
bool map_capacity_exceeded () const
 Check if the current map capacity is exceeded. More...
 
bool pool_capacity_exceeded () const
 Check if the pool capacity is exceeded. More...
 
void rectify_free_list (Autolocker *lock)
 Helper function to evict unused elements from the free list until the cache capacity is not exceeded. More...
 
void evict_all_unused (Autolocker *lock)
 Helper function to evict all unused elements from the free list and the cache. More...
 

Private Attributes

mysql_mutex_t m_lock
 We need a mutex to lock this instance for thread safety, as well as a condition variable for synchronizing handling of cache misses. More...
 
mysql_cond_t m_miss_handled
 
Free_list< Cache_element< T > > m_free_list
 
std::vector< Cache_element< T > * > m_element_pool
 
size_t m_capacity
 

Static Private Attributes

static const size_t initial_capacity = 256
 

Additional Inherited Members

- Public Types inherited from dd::cache::Multi_map_base< T >
typedef Element_map< constT *, Cache_element< T > >::Const_iterator Const_iterator
 
typedef Element_map< constT *, Cache_element< T > >::Iterator Iterator
 
- Protected Member Functions inherited from dd::cache::Multi_map_base< T >
template<typename K >
Element_map< K, Cache_element< T > > * m_map ()
 Template function to get an element map. More...
 
template<typename K >
const Element_map< K, Cache_element< T > > * m_map () const
 
void remove_single_element (Cache_element< T > *element)
 Helper function to remove the mapping of a single element, without deleting the element itself. More...
 
void add_single_element (Cache_element< T > *element)
 Helper function to add a single element. More...
 
void dump () const
 Debug dump of the multi map base to stderr. More...
 

Detailed Description

template<typename T>
class dd::cache::Shared_multi_map< T >

Implementation of a shared set of maps for a given object type.

The implementation is an extension of the Multi_map_base, and adds support for:

  • Locking and thread synchronization.
  • Broadcasting a miss which has been handled.
  • Tracking object usage.
  • Managing the free list.
  • Tracking cache misses.
  • Maintaining a pool of allocated cache elements.
  • Deleting objects and elements after releasing the mutex.

The pool of vacant cache elements is used to avoid deleting and allocating memory. We keep a pool of up to 'max_connections' elements. When a new element is needed, we first try to get one from the pool. If that does not succeed, a new element is allocated dynamically. In this case, the allocation will happen while the mutex is locked.

When an element and object are to be removed from the shared map and deleted, the size of the pool decides whether the element should be added to the pool or not. If it is not added to the pool, it is signed up for being deleted by the Autolocker. The element's object is always signed up for being deleted, it is never reused even if the corresponding element is added to the pool. The Autolocker is used for two purposes:

  1. To ensure that the mutex is locked and unlocked correctly.
  2. To delete unused elements and objects outside the scope where the mutex is locked.

When the Autolocker is deleted, it will first unlock the mutex, then it will iterate over the elements and objects and delete them.

Note
The multi map provides support for tracking cache misses, but does not handle the miss. The miss must be handled by the user of the multi map.
Template Parameters
TDictionary object type.

Constructor & Destructor Documentation

◆ Shared_multi_map()

template<typename T >
dd::cache::Shared_multi_map< T >::Shared_multi_map ( )
inline

Initialize the mutex and condition variable.

Set initial map capacity.

◆ ~Shared_multi_map()

template<typename T >
dd::cache::Shared_multi_map< T >::~Shared_multi_map ( )
inline

Destroy the mutex and condition variable.

Member Function Documentation

◆ available()

template<typename T >
template<typename K >
bool dd::cache::Shared_multi_map< T >::available ( const K &  key)
inline

Check if an element with the given key is available.

◆ drop()

template<typename T >
void dd::cache::Shared_multi_map< T >::drop ( Cache_element< T > *  element)

Delete an element from the map.

This function will remove the element from all maps, using remove(), and delete the object pointed to. This means that all keys associated with the element will be removed from the maps, and the cache element wrapper will be deleted. The object may not be accessed after calling this function.

Parameters
elementElement pointer.

◆ drop_if_present()

template<typename T >
template<typename K >
template void dd::cache::Shared_multi_map< T >::drop_if_present< Resource_group::Id_key > ( const K &  key)

Delete an object corresponding to the key from the map if exists.

This function will find the element corresponding to the key if it exists. After that it will remove the element from all maps, using remove(), and delete the object pointed to. This means that all keys associated with the element will be removed from the maps, and the cache element wrapper will be deleted.

Template Parameters
KKey type.
Parameters
keyKey to be checked.

◆ dump()

template<typename T >
void dd::cache::Shared_multi_map< T >::dump ( ) const
inline

Debug dump of the shared multi map to stderr.

◆ evict_all_unused()

template<typename T >
void dd::cache::Shared_multi_map< T >::evict_all_unused ( Autolocker lock)
private

Helper function to evict all unused elements from the free list and the cache.

Used during e.g. shutdown.

Parameters
lockAutolocker to use for signing up for auto delete.

◆ get()

template<typename T >
template<typename K >
template bool dd::cache::Shared_multi_map< T >::get< Resource_group::Aux_key > ( const K &  key,
Cache_element< T > **  element 
)

Get a wrapper element from the map handling the given key type.

If the wrapped object is present, mark it as used and return it. If the object is in the process of being loaded, wait for loading to be completed. If the object is not present, and not being loaded, mark it as missed and return.

Template Parameters
KKey type.
Parameters
keyKey to use for looking up the object.
[out]elementWrapper element pointer, if present, either immediately or after a cache miss handled by another thread. NULL if awakened after a miss handled by another thread, which was unable to load the object from elsewhere. NULL if the object is not present, and no other thread is missing it.
Return values
trueIf the object is missed, and this thread must handle the miss.
falseOtherwise.

◆ m_map() [1/2]

template<typename T >
template<typename K >
Element_map< K, Cache_element< T > > * dd::cache::Shared_multi_map< T >::m_map ( )
inlineprivate

Template helper function getting the element map.

Const and non-const variants.

Note
Slightly weird syntax is needed to help the parser to resolve this correctly.
Template Parameters
KKey type.
Returns
The element map handling keys of type K.

◆ m_map() [2/2]

template<typename T >
template<typename K >
const Element_map< K, Cache_element< T > > * dd::cache::Shared_multi_map< T >::m_map ( ) const
inlineprivate

◆ map_capacity_exceeded()

template<typename T >
bool dd::cache::Shared_multi_map< T >::map_capacity_exceeded ( ) const
inlineprivate

Check if the current map capacity is exceeded.

Returns
true If the cache capacity is exceeded. false If there is additional capacity in the cache.

◆ pool_capacity_exceeded()

template<typename T >
bool dd::cache::Shared_multi_map< T >::pool_capacity_exceeded ( ) const
inlineprivate

Check if the pool capacity is exceeded.

We keep enough elements to let all connections have a cache miss at the same time without needing to allocate a new element, i.e., we use 'max_connections' as the pool capacity.

Returns
true If the pool capacity is exceeded. false If there is additional capacity for vacant elements.

◆ put()

template<typename T >
template<typename K >
template void dd::cache::Shared_multi_map< T >::put< Resource_group::Aux_key > ( const K *  key,
const T *  object,
Cache_element< T > **  element 
)

Put a new object and element wrapper into the map.

The new object may be NULL if it does not exist in the DD tables. In that case, we must still update the missing set and broadcast, if necessary, because other threads may be waiting. Then, the element returned is also NULL.

Otherwise, we check that the actual object instance is not present in the map, then all the keys are generated based on the new object. The keys that are missed are removed from the missed set, and then we verify that all keys are either present or absent.

If no keys are present, it means we must add the new object. We remove the least recently used objects, if cache capacity is exceeded, and add the new object to the reverse map. We also mark the object as being used. The element wrapper of the new object is returned.

If all keys are present, we return the wrapper element already present and delete the newly read object.

Finally, if at least one key was missed, we broadcast that the miss has been handled.

Note
This function will delete the newly read object if an object with the same keys is already present.
The function may add a new object which is not registered as being missed, i.e., without a preceding cache miss In this case, the submitted key is NULL.
Template Parameters
KKey type.
Parameters
keyKey used when loading the object.
objectNew object to be added.
[out]elementElement wrapper: NULL if the new object is NULL, otherwise the wrapper of the newly read object or the existing object with the same keys.

◆ rectify_free_list()

template<typename T >
void dd::cache::Shared_multi_map< T >::rectify_free_list ( Autolocker lock)
private

Helper function to evict unused elements from the free list until the cache capacity is not exceeded.

Parameters
lockAutolocker to use for signing up for auto delete.

◆ release()

template<typename T >
void dd::cache::Shared_multi_map< T >::release ( Cache_element< T > *  element)

Release one element.

The element must be present and in use. If the element becomes unused, it is added to the free list, which is then rectified to enforce its capacity constraints.

Parameters
elementElement pointer.

◆ remove()

template<typename T >
void dd::cache::Shared_multi_map< T >::remove ( Cache_element< T > *  element,
Autolocker lock 
)
private

Remove an element from the map.

This function will remove the element from the multi map. This means that all keys associated with the element will be removed from the maps, and the cache element wrapper will be deleted. The object itself is not deleted. It is up to the outer layer to decide what to do with the object.

Parameters
elementElement to be removed.
lockAutolocker to use for signing up for auto delete.

◆ replace()

template<typename T >
void dd::cache::Shared_multi_map< T >::replace ( Cache_element< T > *  element,
const T *  object 
)

Replace the object and re-generate the keys for an element.

The element must be present and in use. The keys by which it is hashed are removed from the internal maps. The new keys are generated, and the element, with its new keys, is added to the maps again.

Parameters
elementElement for which new keys should be generated.
objectNew object to replace the old one.

◆ reset()

template<typename T >
bool dd::cache::Shared_multi_map< T >::reset ( THD thd)

Reset the shared map.

Locks and deletes all objects present, but keeps the element pool and the capacity setting.

Parameters
thdThread context.
Return values
trueFailure, e.g. timeout from metadata lock acquisition.
falseOtherwise.

◆ set_capacity()

template<typename T >
void dd::cache::Shared_multi_map< T >::set_capacity ( size_t  capacity)
inline

Set capacity of the shared map.

◆ shutdown()

template<typename T >
void dd::cache::Shared_multi_map< T >::shutdown

Shutdown the shared map.

Delete all objects present.

◆ use_if_present()

template<typename T >
template<typename K >
Cache_element< T > * dd::cache::Shared_multi_map< T >::use_if_present ( const K &  key)
private

Template function to find an element and mark it as used.

The function looks up the appropriate element map. If the key is present in the map, the element is marked as being used and returned. If the element was in the free list, it is removed from the list.

Template Parameters
KKey type.
Parameters
keyKey to use for looking up the element.
Returns
Element found associated with the key, if present, otherwise NULL.

Member Data Documentation

◆ initial_capacity

template<typename T >
const size_t dd::cache::Shared_multi_map< T >::initial_capacity = 256
staticprivate

◆ m_capacity

template<typename T >
size_t dd::cache::Shared_multi_map< T >::m_capacity
private

◆ m_element_pool

template<typename T >
std::vector<Cache_element<T> *> dd::cache::Shared_multi_map< T >::m_element_pool
private

◆ m_free_list

template<typename T >
Free_list<Cache_element<T> > dd::cache::Shared_multi_map< T >::m_free_list
private

◆ m_lock

template<typename T >
mysql_mutex_t dd::cache::Shared_multi_map< T >::m_lock
private

We need a mutex to lock this instance for thread safety, as well as a condition variable for synchronizing handling of cache misses.

We provide a set of operations for using these variables.

◆ m_miss_handled

template<typename T >
mysql_cond_t dd::cache::Shared_multi_map< T >::m_miss_handled
private

The documentation for this class was generated from the following files: