StringManager

The StringManager is the abstract table storing all the shared strings.  Shared strings register/unregister themselves with the manager, which keeps tracks of reference counts for each allocated string.  When a string no longer has any references, the memory is freed.  Strings are managed via SharedStringEntries.

Author

David C.  Haley (david at the-haleys dot com)

Summary
The StringManager is the abstract table storing all the shared strings.
Add a string reference to the manager.
Remove a string reference from the manager.
Count the number of times a string is referenced.
Returns the number of unique strings in the table.
Return how many bytes are used by the shared string manager.
Dump the shared string table to an output stream.
Total number of (unique) strings
Get an entry in the table for a given string, creating if necessary.
Decrease the reference count of a shared string.
Get an entry in the shared string table.
The StringManager manages a collection of SharedStringEntries.
Utility macros.
Declares a shared string wrapper.
Associates a declared wrapper with a table manager.

addString

const std::string * addString(const std::string &str)

Add a string reference to the manager.  Actually allocates memory if necessary.

Parameters

strThe string to manage.

Returns

A pointer to the managed string memory.

deleteString

void deleteString(const std::string &str)

Remove a string reference from the manager.  Will delete the string memory if necessary (i.e. no more references).

Parameters

strThe string to remove.

Debugging/ Informational

countRefs

size_t countRefs(const std::string &str) const

Count the number of times a string is referenced.  If the string is not in the manager table, it is referenced 0 times.

Author

David C.  Haley (david at the-haleys dot com)

Parameters

strThe string whose references to count.

Returns

The number of references to a given string.

numStrings

size_t numStrings() const

Returns the number of unique strings in the table.

Author

David C.  Haley (david at the-haleys dot com)

Returns

The number of unique strings.

bytesUsed

virtual size_t bytesUsed() const = 0

Return how many bytes are used by the shared string manager.  Includes memory for the shared strings, the table to store them, plus any overhead.  Note that due to byte padding, structures may be larger than you might expect.

Author

David C.  Haley (david at the-haleys dot com)

Returns

The total number of bytes used by this shared string table.

dumpTable

virtual void dumpTable(std::ostream &os) const = 0

Dump the shared string table to an output stream.  The format of this output is left to the subclass implementations.  Generally it will contain a textual representation of table structure as well as the managed strings.

Note

This function is pure virtual.  Subclasses must implement it.

Usage

aTable->dumpTable(cout); // dump table to cout

Author

David C.  Haley (david at the-haleys dot com)

Parameters

osThe output stream to write to.

Private Members

numStrings_

size_t numStrings_

Total number of (unique) strings

prepareEntry

virtual SharedStringEntry * prepareEntry(const std::string &str) = 0

Get an entry in the table for a given string, creating if necessary.  The intention of this function is that you call it when adding a new string to the table: it will look up and return the right entry whose refcount to increment, or it will create a new, empty entry.

Note

This function is pure virtual.  Subclasses must implement it.

Author

David C.  Haley (david at the-haleys dot com)

Parameters

str -

Returns

...

unrefEntry

virtual bool unrefEntry(const std::string &str) = 0

Decrease the reference count of a shared string.  Frees memory if the string’s refcount drops to zero.

Note

This function is pure virtual.  Subclasses must implement it.

Parameters

strThe string to unreference.

Returns

True if the entry’s refcount went to zero and was deleted.

getEntry

virtual const SharedStringEntry * getEntry(const std::string &str) const = 0

Get an entry in the shared string table.  Returns null if there is no such entry.

Note

This function is pure virtual.  Subclasses must implement it.

Author

David C.  Haley (david at the-haleys dot com)

Parameters

strThe string whose entry to get.

Returns

The shared string table entry corresponding to /str/.

SharedStringEntry

The StringManager manages a collection of SharedStringEntries.  A SharedStringEntry is a paired reference count and std::string object.

SharedString

Utility macros.

Summary
Declares a shared string wrapper.
Associates a declared wrapper with a table manager.

Macros

DECLARE_MANAGER_WRAPPER

Declares a shared string wrapper.  This macro should be executed in your header files whenever you want to make visible your shared string class.  After declaring a wrapper, you should define it using the macro ASSOCIATE_MANAGER_WRAPPER in a C++ source file.

Usage

Typical usage would be something like so

DECLARE_MANAGER_WRAPPER(HashTableWrapper);
typedef SharedString::SharedString< HashTableWrapper > shared_str;

Parameters

nameThe name of the manager wrapper to declare.

ASSOCIATE_MANAGER_WRAPPER

Associates a declared wrapper with a table manager.  This macro should be executed once in a C++ source file.  It is important that you use the macro once, as changing the wrapper’s manager could have unpredictable consequences.

Note

You may associate the wrapper with a manager at any point of time during program execution.  That being said, you must have a wrapper associated the first time you use a shared string.

Usage

After having defined a wrapper -HashTableWrapper- using DECLARE_MANAGER_WRAPPER, typical usage would be something like so:

SharedString::HashTable * gTable;
ASSOCIATE_MANAGER_WRAPPER(HashTableWrapper, gTable);

Parameters

nameThe name of the manager wrapper to define.
managerPtrA pointer to the manager to define the wrapper with.
const std::string * addString(const std::string &str)
Add a string reference to the manager.
void deleteString(const std::string &str)
Remove a string reference from the manager.
size_t countRefs(const std::string &str) const
Count the number of times a string is referenced.
size_t numStrings() const
Returns the number of unique strings in the table.
virtual size_t bytesUsed() const = 0
Return how many bytes are used by the shared string manager.
virtual void dumpTable(std::ostream &os) const = 0
Dump the shared string table to an output stream.
size_t numStrings_
Total number of (unique) strings
virtual SharedStringEntry * prepareEntry(const std::string &str) = 0
Get an entry in the table for a given string, creating if necessary.
virtual bool unrefEntry(const std::string &str) = 0
Decrease the reference count of a shared string.
virtual const SharedStringEntry * getEntry(const std::string &str) const = 0
Get an entry in the shared string table.
The StringManager is the abstract table storing all the shared strings.
The StringManager manages a collection of SharedStringEntries.
Associates a declared wrapper with a table manager.
Declares a shared string wrapper.