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 >:

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:

To ensure that the mutex is locked and unlocked correctly.
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

T	Dictionary 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

element Element 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

K Key type.

Parameters

key	Key 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

lock	Autolocker 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

K Key type.

Parameters

	key	Key to use for looking up the object.
[out]	element	Wrapper 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

true	If the object is missed, and this thread must handle the miss.
false	Otherwise.

◆ 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

K Key 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

K Key type.

Parameters

	key	Key used when loading the object.
	object	New object to be added.
[out]	element	Element 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

lock	Autolocker 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

element Element 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

element	Element to be removed.
lock	Autolocker 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

element	Element for which new keys should be generated.
object	New 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

thd	Thread context.

Return values

true	Failure, e.g. timeout from metadata lock acquisition.
false	Otherwise.

◆ 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

K Key type.

Parameters

key	Key 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:

sql/dd/impl/cache/cache_element.h
sql/dd/impl/cache/shared_multi_map.h
sql/dd/impl/cache/shared_multi_map.cc

Classes

Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Shared_multi_map()

◆ ~Shared_multi_map()

Member Function Documentation

◆ available()

◆ drop()

◆ drop_if_present()

◆ dump()

◆ evict_all_unused()

◆ get()

◆ m_map() [1/2]

◆ m_map() [2/2]

◆ map_capacity_exceeded()

◆ pool_capacity_exceeded()

◆ put()

◆ rectify_free_list()

◆ release()

◆ remove()

◆ replace()

◆ reset()

◆ set_capacity()

◆ shutdown()

◆ use_if_present()

Member Data Documentation

◆ initial_capacity

◆ m_capacity

◆ m_element_pool

◆ m_free_list

◆ m_lock

◆ m_miss_handled