Source file:

/Core/Loyc.Essentials/Utilities/Symbol.cs

Inheritance diagram for Loyc.SymbolPool:

Remarks

A collection of Symbols.

There is one global symbol pool (GSymbol.Pool) and you can create an unlimited number of private pools, each with an independent namespace.

Methods of this class are synchronized, so a SymbolPool can be used from multiple threads.

By default, SymbolPool uses weak references to refer to Symbols, so they can be garbage-collected when no longer in use. When creating a private pool you can tell the SymbolPool constructor to use strong references instead, which ensures that none of the symbols disappear, but risks a memory leak if the pool itself is never garbage-collected. Strong references also require less memory and may be slightly faster.

By default, all Symbol are given non-negative IDs. GSymbol.Empty (whose Name is "") has an Id of 0, but in a private pool, "" is not treated differently than any other symbol so a new ID will be allocated for it.

Properties
bool	UsesStrongReferences `[get]`

Symbol	this[string name] `[get]`

int	TotalCount `[get]`
	Returns the number of Symbols created in this pool. More...

Public Member Functions
	SymbolPool (int firstID)

Symbol	Get (string name)
	Gets a symbol from this pool, or creates it if it does not exist in this pool already. More...

Symbol	Get (string name, int id)
	Creates a Symbol in this pool with a specific ID, or verifies that the requested Name-Id pair is present in the pool. More...

Symbol	GetIfExists (string name)
	Gets a symbol from this pool, if the name exists already. More...

Symbol	GetGlobalOrCreateHere (string name)
	Gets a symbol from the global pool, if it exists there already; otherwise, creates a Symbol in this pool. More...

Symbol	GetById (int id)
	Gets a symbol by its ID, or null if there is no such symbol. More...

IEnumerator< Symbol >	GetEnumerator ()

Static Public Member Functions
static SymbolPool	new ()

static SymbolPool	new (int firstID, bool useStrongRefs)

static SymbolPool	new (int firstID, bool useStrongRefs, int poolId)
	Initializes a new Symbol pool. More...

Protected Member Functions
virtual void	Get (string name, out Symbol sym)
	Workaround for lack of covariant return types in C# More...

virtual void	Get (string name, int id, out Symbol sym)
	Workaround for lack of covariant return types in C# More...

virtual Symbol	NewSymbol (int id, string name)
	Factory method to create a new Symbol. More...

Protected fields
readonly int	_poolId

Protected static fields
static int	_nextPoolId = 1

Member Function Documentation

Symbol Loyc.SymbolPool.Get ( string name )

inline

Gets a symbol from this pool, or creates it if it does not exist in this pool already.

Parameters

name	Name to find or create.

Returns: A symbol with the requested name, or null if the name was null.

If Get("foo") is called in two different pools, two Symbols will be created, each with the Name "foo" but not necessarily with the same IDs. Note that two private pools re-use the same IDs, but this generally doesn't matter, as Symbols are compared by reference, not by ID.

Referenced by Loyc.SymbolPool.Get(), and Loyc.SymbolPool.GetGlobalOrCreateHere().

Symbol Loyc.SymbolPool.Get	(	string	name,
		int	id
	)

inline

Creates a Symbol in this pool with a specific ID, or verifies that the requested Name-Id pair is present in the pool.

Parameters

name	Name to find or create.
id	Id that must be associated with that name.

Exceptions

ArgumentNullException	name was null.
ArgumentException	The specified Name or Id is already in use, but the Name and Id do not match. For example, Get("a", 1) throws this exception if a Symbol with Id==1 is not named "a", or a Symbol with Name=="a" does not have Id==1.

Returns: A symbol with the requested Name and Id.

References Loyc.SymbolPool.Get().

virtual void Loyc.SymbolPool.Get	(	string	name,
		out Symbol	sym
	)

inlineprotectedvirtual

Workaround for lack of covariant return types in C#

References Loyc.SymbolPool.GetIfExists(), and Loyc.SymbolPool.NewSymbol().

virtual void Loyc.SymbolPool.Get	(	string	name,
		int	id,
		out Symbol	sym
	)

inlineprotectedvirtual

Workaround for lack of covariant return types in C#

References Loyc.SymbolPool.GetIfExists(), and Loyc.SymbolPool.NewSymbol().

Symbol Loyc.SymbolPool.GetById ( int id )

inline

Gets a symbol by its ID, or null if there is no such symbol.

Parameters

id	ID of a symbol. If this is a private pool and the ID does not exist in the pool, the global pool is searched instead.

GetById() uses a dictionary of ID numbers to Symbols for fast lookup. To save time and memory, this dictionary is not created until either GetById() or Get(string name, int id) is called.

Returns: The requested Symbol, or null if not found.

Symbol Loyc.SymbolPool.GetGlobalOrCreateHere ( string name )

inline

Gets a symbol from the global pool, if it exists there already; otherwise, creates a Symbol in this pool.

Parameters

name	Name of a symbol to get or create

Returns: A symbol with the requested name

References Loyc.SymbolPool.Get().

Symbol Loyc.SymbolPool.GetIfExists ( string name )

inline

Gets a symbol from this pool, if the name exists already.

Parameters

name	Symbol Name to find

Returns: Returns the existing Symbol if found; returns null if the name was not found, or if the name itself was null.

Referenced by Loyc.SymbolPool.Get().

static SymbolPool Loyc.SymbolPool.new	(	int	firstID,
		bool	useStrongRefs,
		int	poolId
	)

inlinestatic

Initializes a new Symbol pool.

Parameters

firstID	The first Symbol created in the pool will have the specified ID number, and IDs will proceed downward from there.
useStrongRefs	True to use strong references to the Symbols in the pool, false to use WeakReferences that allow garbage- collection of individual Symbols.
poolId	Numeric ID of the pool (affects the HashCode of Symbols from the pool)