gimbal_quark.h File Reference

Go to the source code of this file.

Macros
#define	GBL_QUARK_INVALID

Typedefs
typedef uintptr_t	GblQuark

Functions
Static State
Methods for static initialization, finalization, and state
GBL_RESULT	GblQuark_init (GblContext *pCtx, size_t extraPageSize, size_t initialEntries)
GBL_RESULT	GblQuark_final (void)
GblContext *	GblQuark_context (void)
Statistics
Methods for querying and reporting usage stats
size_t	GblQuark_count (void)
size_t	GblQuark_pageCount (void)
size_t	GblQuark_pageSize (void)
size_t	GblQuark_bytesUsed (void)
size_t	GblQuark_bytesAvailable (void)
size_t	GblQuark_totalCapacity (void)
size_t	GblQuark_fragmentedBytes (void)
float	GblQuark_utilization (void)
String Interning
Methods for creating, retrieving, and converting GblQuarks
GblQuark	GblQuark_fromString (const char *pStr, size_t len)
GblQuark	GblQuark_fromStatic (const char *pSstring)
GblQuark	GblQuark_tryString (const char *pStr, size_t len)
const char *	GblQuark_toString (GblQuark quark)
const char *	GblQuark_internString (const char *pStr, size_t len)
const char *	GblQuark_internStatic (const char *pString)

Detailed Description

GblQuark and string interning API

A GblQuark is an integral unique identifier associated with a given string. Two different C string pointers containing the same string value will have the same GblQuark. GblQuark is libGimbal's implementation of string interning.

A GblQuark is highly useful for situations when string comparison speed is what matters the most, such as for hash tables. For example, libGimbal's property system internally represents property names as GblQuarks so that accessing a property by name is optimized.

This string interning mechanism is implemented as a hash table mapping a given regular string to a GblQuark unique identifier. When a non-static string is registered, it is allocated within a paged static buffer, whose lifetime is that of the program.

Note

When working with string literals, the internal allocations can be elided by using GblQuark_fromStatic() or GblQuark_internStatic(), since a string literal's lifetime is global.

All functions in this API are thread-safe.

Example Usage

// create a quark from a string literal
GblQuark quark1 = GblQuark_fromStatic("String");

// create a quark from a regular string buffer
char buffer[] = "String";
GblQuark quark2 = GblQuark_fromString(buffer);

// the two values are equal
GBL_ASSERT(quark1 == quark2);

// convert them back to regular strings to show values are equal
GBL_ASSERT(strcmp(GblQuark_toString(quark1),
                  GblQuark_toString(quark2) == 0);

Author

2023 Falco Girgis

Copyright

MIT License

Definition in file gimbal_quark.h.

Macro Definition Documentation

GBL_QUARK_INVALID

#define GBL_QUARK_INVALID

Value of an invalid or NULL GblQuark.

Definition at line 52 of file gimbal_quark.h.

Function Documentation

GblQuark_init()

GblQuark_init	(	GblContext *	pCtx,
		size_t	extraPageSize,
		size_t	initialEntries
	)

Initializes the GblQuark registry with the given capacities (called automatically with defaults)

Initializes the GblQuark API with the given configuration parameters or default if they're all set to NULL and 0.

Note

The API is already initialized internally as soon as it's used, so this is typically not required.

Attention

This will invalidate any exiting GblQuark values!

Parameters

pCtx	context from which to allocate and log
extraPageSize	size of each chunk allocation used beyond the builtin static initial page
initialEntries	initial number of entries to preallocate in the hash table

Returns

result code

GblQuark_final()

GblQuark_final

(

void

)

Finalizes the GblQuark registry, releasing all resources (called automatically upon shutdown)

Finalizes the GblQuark API, releasing all internally allocated paged data and clearing the hash map.

Note

This will invalidate all existing GblQuark values and is typically called when the application exits

Returns

result code

GblQuark_context()

GblQuark_context

(

void

)

Returns a pointer to the GblContext object associated with the GblQuark registry.

Returns

GblContext object used for logging and allocation internally

GblQuark_count()

GblQuark_count

(

void

)

Returns the total number of quarks maintained within the registry.

Returns

total number of GblQuarks which have been created internally

GblQuark_pageCount()

GblQuark_pageCount

(

void

)

Returns the total number of allocation pages used by the registry.

Returns

number of pages which have been allocated to store interned strings

GblQuark_pageSize()

GblQuark_pageSize

(

void

)

Returns the size of each dynamically allocated page used by the registry.

Returns

size of each additional page beyond the default static one for holding interned strings

GblQuark_bytesUsed()

GblQuark_bytesUsed

(

void

)

Returns the total number of bytes used for string allocations by the registry.

Returns

total number of bytes used on all pages by interned strings

GblQuark_bytesAvailable()

GblQuark_bytesAvailable

(

void

)

Returns the total number of bytes remaining available on the current allocation page.

Returns

total number of bytes available on the current page

GblQuark_totalCapacity()

GblQuark_totalCapacity

(

void

)

Returns the total number of bytes allocated (used or unused) for string storage.

Returns

total combined byte size of all active pages

GblQuark_fragmentedBytes()

GblQuark_fragmentedBytes

(

void

)

Returns the total number of unused, unavailable, but allocated bytes for string storage.

Returns

total number of leftover/wasted bytes at the end of a page that were too small to fill

GblQuark_utilization()

GblQuark_utilization

(

void

)

Returns the utilization factor of total capacity vs bytes used (ranging 0.0-1.0)

Returns

Ratio of GblQuark_bytesUsed() over GblQuark_totalCapacity(), representing what percentage of available resources is being utilized

GblQuark_fromString()

GblQuark GblQuark_fromString	(	const char *	pStr,
		size_t	len
	)

Returns the GblQuark associated with the given string, adding a new entry to the registry if necessary.

GblQuark_fromStatic()

GblQuark_fromStatic

(

const char *

pString

)

Returns the GblQuark associated with the given STATIC string, which can save an allocation when initially registering.

Equivalent to GblQuark_fromString(), except for no internal storage is allocated for the string, since its lifetime is known to be global.

Parameters

pString

string literal

Returns

quark value or GBL_QUARK_INVALID if the string is NULL

See also

GblQuark_fromString

GblQuark_tryString()

GblQuark GblQuark_tryString	(	const char *	pStr,
		size_t	len
	)

Returns the GblQuark associated with the given string, returning GBL_QUARK_INVALID if it was not previously registered.

GblQuark_toString()

GblQuark_toString

(

GblQuark

quark

)

Returns the NULL-terminated interned C string associated with a given GblQuark.

Retrieves the internal C string representation of the given quark or NULL if the quark's value is GBL_QUARK_INVALID

Parameters

quark

value of existing quark

Returns

NULL-terminated C string or NULL

GblQuark_internString()

const char * GblQuark_internString	(	const char *	pStr,
		size_t	len
	)

Creates a GblQuark from the given string (if necessary), also returning its interned string.

GblQuark_internStatic()

GblQuark_internStatic

(

const char *

pString

)

Creates a GblQuark from the given STATIC string (if necessary, saving on allocating), also returning its interned string.

Equivalent to GblQuark_internString() except that the internal allocation of the string is ellided, because the string's lifetime is known to be global. So the return value is the same as the argument.

Parameters

pString

static or literal string or NULL

Returns

pString

See also

GblQuark_internString