The Stringcache
[Miscellaneous]

Functions
EAPI int	cmaid_stringcache_init (void)
	Initialize the cmaid stringcache internal structure.
EAPI void	cmaid_stringcache_shutdown (void)
	Shutdown the stringcache internal structures.
EAPI const char *	cmaid_stringcache_instance (const char *str)
	Retrieves an instance of a string for use in a program.
EAPI void	cmaid_stringcache_release (const char *str)
	Notes that the given string has lost an instance.

---

Detailed Description

These functions allow you to store one copy of a string, and use it throughout your program.

This is a method to reduce the number of duplicated strings kept in memory. It's pretty common for the same strings to be dynamically allocated repeatedly between applications and libraries, especially in circumstances where you could have multiple copies of a structure that allocates the string. So rather than duplicating and freeing these strings, you request a read-only pointer to an existing string and only incur the overhead of a hash lookup.

It sounds like micro-optimizing, but profiling has shown this can have a significant impact as you scale the number of copies up. It improves string creation/destruction speed, reduces memory use and decreases memory fragmentation, so a win all-around.

---

Function Documentation

EAPI int cmaid_stringcache_init

(

void

)

Initialize the cmaid stringcache internal structure.

Returns:

Zero on failure, non-zero on successful initialization.

EAPI const char* cmaid_stringcache_instance

(

const char *

str

)

Retrieves an instance of a string for use in a program.

Parameters:

str

The string to retrieve an instance of.

Returns:

A pointer to an instance of the string on success. NULL on failure.

EAPI void cmaid_stringcache_release

(

const char *

str

)

Notes that the given string has lost an instance.

Parameters:

str

The given string. It will free the string if no other instances are left.

EAPI void cmaid_stringcache_shutdown

(

void

)

Shutdown the stringcache internal structures.

Frees the internal stringcache, if it isn't used elsewhere. In other words