The string manager class is a dictionary mapping integers to (constant) string values. More...

#include <Manager.h>

Inheritance diagram for smtk::string::Manager:

Collaboration diagram for smtk::string::Manager:

Public Types
enum	Event { Managed, Inserted, Removed, Unmanaged }
	Events that can occur during the lifecycle of the manager. More...

using	Visitor = std::function< smtk::common::Visit(Hash entry)>
	Signature for functions visiting strings in the manager or in a set held by the manager.

using	Observer = std::function< void(Event, Hash, const std::string &, Hash)>
	The signature used by observers to receive notifications from the string manager. More...

using	Observers = smtk::common::Observers< Observer >
	The type of container that holds the set of smtk::string::Manager observers.

Public Member Functions
Hash	manage (const std::string &s)
	Insert a string into the manager by computing a unique hash (the returned value).

std::size_t	unmanage (Hash h)
	Remove a hash from the manager. This also removes it from any string sets.

bool	hasValue (Hash h) const
	Return true if a string exists for the Hash (false otherwise).

const std::string &	value (Hash h) const
	Look up a string from its hashed value.

Hash	find (const std::string &s) const
	Look up a hash from a string value (without inserting it). More...

Hash	compute (const std::string &s) const
	Compute a hash from a string value (without inserting it into the manager). More...

Hash	insert (const std::string &set, Hash h)
	Add the hash h to the set s. More...

bool	insert (Hash set, Hash h)

bool	remove (const std::string &set, Hash h)
	Remove the hash h from the set s. More...

bool	remove (Hash set, Hash h)

bool	contains (const std::string &set, Hash h) const
	Return true if the set exists and contains hash h ; and false otherwise. More...

bool	contains (Hash set, Hash h) const

bool	contains (Hash h) const

bool	verify (Hash &verified, Hash input) const
	Verify a hash exists, possibly remapping it in the process. More...

bool	empty () const
	Return true if the manager is empty (i.e., managing no hashes) and false otherwise.

smtk::common::Visit	visitMembers (Visitor visitor, Hash set=Invalid)
	Visit all members of the set (or the entire Manager if passed the Invalid hash). More...

smtk::common::Visit	visitSets (Visitor visitor)
	Visit all set names in the manager. More...

Observers &	observers ()
	Return the set of string-manager observers (so you can insert/remove an observer).

void	setData (const std::unordered_map< Hash, std::string > &members, const std::unordered_map< Hash, std::unordered_set< Hash >> &sets)
	Set the manager's storage. This exists to allow easy deserialization.

void	reset ()
	Reset the manager to an empty state, clearing both members and sets.

Static Public Member Functions
static std::shared_ptr< Manager >	create ()

Static Public Attributes
static constexpr Hash	Invalid = 0
	An invalid hash (that should never exist inside the manager's storage).

Protected Member Functions
std::pair< Hash, bool >	computeInternal (const std::string &s) const
	Same as compute() but does not lock (you must hold m_writeLock upon entry).

std::pair< Hash, bool >	computeInternalAndInsert (const std::string &s)

Protected Attributes
Observers	m_observers

std::unordered_map< Hash, std::string >	m_data

std::unordered_map< Hash, std::unordered_set< Hash > >	m_sets

std::mutex	m_writeLock

std::unordered_map< Hash, Hash >	m_translation
	A translation map for deserialization. More...

std::atomic< int >	m_translationDepth { 0 }
	Record the "nesting depth" of deserializers.

Friends
class	DeserializationContext
	This class is a friend so it can access the m_translation table.

void SMTKCORE_EXPORT	from_json (const nlohmann::json &, std::shared_ptr< Manager > &)
	This function is a friend so it can access m_translation.

Detailed Description

The string manager class is a dictionary mapping integers to (constant) string values.

The manager also provides a way to store sets of strings (named with a string that is itself hashed by the manager).

Member Typedef Documentation

◆ Observer

using smtk::string::Manager::Observer = std::function<void(Event, Hash, const std::string&, Hash)>

The signature used by observers to receive notifications from the string manager.

The first parameter is the event type. The second parameter is the hash of the relevant string. The third parameter is the string itself. For Inserted/Removed events, the fourth parameter is the name of the set into which the hash is being inserted/removed. For other events, the fourth parameter is unspecified but you might generally expect it to be smtk::string::Manager::Invalid.

Member Enumeration Documentation

◆ Event

enum smtk::string::Manager::Event

Events that can occur during the lifecycle of the manager.

Enumerator
Managed	A string was added to the manager.
Inserted	A string was inserted into a set.
Removed	A string was removed from a set.
Unmanaged	A string was removed from the manager.

Member Function Documentation

◆ compute()

Hash smtk::string::Manager::compute ( const std::string & s ) const

Compute a hash from a string value (without inserting it into the manager).

If the string is not already managed, this will compute the hash value that would be used if the string were to be immediately inserted. This method allows hash collisions to be avoided; one can compute a hash while the map is write-locked and insert if needed.

Unlike the find() method, this will never return Manager::Invalid.

◆ contains()

bool smtk::string::Manager::contains	(	const std::string &	set,
		Hash	h
	)		const

Return true if the set exists and contains hash h ; and false otherwise.

If set is Invalid, then this returns true if the hash exists in m_data and false otherwise.

◆ find()

Hash smtk::string::Manager::find ( const std::string & s ) const

Look up a hash from a string value (without inserting it).

If the string has not been previously managed, then Manager::Invalid will be returned.

◆ insert()

Hash smtk::string::Manager::insert	(	const std::string &	set,
		Hash	h
	)

Add the hash h to the set s.

The set s need not exist prior to this call. It will be added to the manager as needed and then used as a key in the dictionary of sets. The returned value is the hash of the set s (when passing a string for the set name) or a boolean indicating whether the insertion actually occurred (when passing a hash for the set name). Note that inserting an already-existing member will return false.

◆ remove()

bool smtk::string::Manager::remove	(	const std::string &	set,
		Hash	h
	)

Remove the hash h from the set s.

This returns true if the hash was removed and false otherwise (i.e., because the set did not exist or did not contain h.

◆ verify()

bool smtk::string::Manager::verify	(	Hash &	verified,
		Hash	input
	)		const

Verify a hash exists, possibly remapping it in the process.

If input exists in the manager's table, then verified will be set to input. Otherwise, if input exists in the thread-local translation table (populated and valid only during deserialization), then verified will be set to the "destination hash" of input. In either of the above cases, this method returns true.

Failing the above, verified will be set to Invalid and this method returns false. This method is used to deserialize Token instances after the Manager has been deserialized.

See also: Token::fromHash

◆ visitMembers()

smtk::common::Visit smtk::string::Manager::visitMembers	(	Visitor	visitor,
		Hash	set = `Invalid`
	)

Visit all members of the set (or the entire Manager if passed the Invalid hash).

Your visitor may not modify the manager. You may terminate early by returning smtk::common::Halt.

◆ visitSets()

smtk::common::Visit smtk::string::Manager::visitSets ( Visitor visitor )

Visit all set names in the manager.

Your visitor may not modify the manager. You may terminate early by returning smtk::common::Halt.

Member Data Documentation

◆ m_translation

std::unordered_map<Hash, Hash> smtk::string::Manager::m_translation

protected

A translation map for deserialization.

This internal variable is checked when asked to retrieve a hash that does not exist in m_data. In this case, it may be a hash from a serialized string-manager on a different platform (with a different hash function). If it is, then an entry in this map will exist instructing the manager to return the destination hash instead of verifying the input hash (i.e., the Token will use the range of the map instead of the domain).

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

/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/string/Manager.h
/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/string/Manager.cxx

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends