Stringshare
[Data Types]
These functions allow you to store one copy of a string, and use it throughout your program. More...
Functions | |
static Eina_Bool | eina_stringshare_replace (const char **p_str, const char *news) |
EAPI int | eina_stringshare_init (void) |
Initialize the eina stringshare internal structure. | |
EAPI int | eina_stringshare_shutdown (void) |
Shut down the eina stringshare internal structures. | |
EAPI const char * | eina_stringshare_add_length (const char *str, unsigned int slen) |
Retrieve an instance of a string for use in a program. | |
EAPI const char * | eina_stringshare_add (const char *str) |
Retrieve an instance of a string for use in a program. | |
EAPI const char * | eina_stringshare_ref (const char *str) |
Increment references of the given shared string. | |
EAPI void | eina_stringshare_del (const char *str) |
Note that the given string has lost an instance. | |
EAPI int | eina_stringshare_strlen (const char *str) |
Note that the given string must be shared. | |
EAPI void | eina_stringshare_dump (void) |
Dump the contents of the stringshare. | |
static Eina_Stringshare_Node * | _eina_stringshare_node_from_str (const char *str) |
static void | _eina_stringshare_small_bucket_dump (Eina_Stringshare_Small_Bucket *bucket, struct dumpinfo *di) |
static void | _eina_stringshare_small_dump (struct dumpinfo *di) |
static Eina_Bool | eina_iterator_array_check (const Eina_Rbtree *rbtree, Eina_Stringshare_Head *head, struct dumpinfo *fdata) |
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.
For more information, you can look at the Stringshare Tutorial.
Function Documentation
EAPI int eina_stringshare_init | ( | void | ) |
Initialize the eina stringshare internal structure.
- Returns:
- 1 or greater on success, 0 on error.
This function allocates the memory needed by the stringshare internal structure and sets up the error module of Eina. It is also called by eina_init(). It returns 0 on failure, otherwise it returns the number of times it has already been called.
References eina_error_init(), EINA_ERROR_PERR, eina_error_shutdown(), and eina_magic_string_init().
Referenced by eina_init().
EAPI int eina_stringshare_shutdown | ( | void | ) |
Shut down the eina stringshare internal structures.
- Returns:
- 0 when the stringshare module is completely shut down, 1 or greater otherwise.
This function frees the memory allocated by eina_stringshare_init() and shuts down the error module. It is also called by eina_shutdown(). It returns 0 when it is called the same number of times than eina_stringshare_init().
References eina_error_shutdown(), and eina_magic_string_shutdown().
Referenced by eina_init(), and eina_shutdown().
EAPI const char * eina_stringshare_add_length | ( | const char * | str, | |
unsigned int | slen | |||
) |
Retrieve an instance of a string for use in a program.
- Parameters:
-
str The string to retrieve an instance of. slen The string size (<= strlen(str)).
- Returns:
- A pointer to an instance of the string on success.
NULL
on failure.
This function retrieves an instance of str
. If str
is NULL
, then NULL
is returned. If str
is already stored, it is just returned and its reference counter is increased. Otherwise it is added to the strings to be searched and a duplicated string of str
is returned.
This function does not check string size, but uses the give the exact given size. This can be used to stringshare part of a larger buffer or substring.
- Note:
- it's not possible to have more than 65k references or strings bigger than 65k since we use 'unsigned short' to save space.
- See also:
- eina_stringshare_add()
Referenced by eina_stringshare_add().
EAPI const char * eina_stringshare_add | ( | const char * | str | ) |
Retrieve an instance of a string for use in a program.
- Parameters:
-
str The NULL terminated string to retrieve an instance of.
- Returns:
- A pointer to an instance of the string on success.
NULL
on failure.
This function retrieves an instance of str
. If str
is NULL
, then NULL
is returned. If str
is already stored, it is just returned and its reference counter is increased. Otherwise it is added to the strings to be searched and a duplicated string of str
is returned.
The string str must be NULL terminated ('') and its full length will be used. To use part of the string or non-null terminated, use eina_stringshare_add_length() instead.
- Note:
- it's not possible to have more than 65k references or strings bigger than 65k since we use 'unsigned short' to save space.
- See also:
- eina_stringshare_add_length()
References eina_stringshare_add_length().
EAPI const char * eina_stringshare_ref | ( | const char * | str | ) |
Increment references of the given shared string.
This is similar to eina_stringshare_add(), but it's faster since it will avoid lookups if possible, but on the down side it requires the parameter to be shared before, in other words, it must be the return of a previous eina_stringshare_add().
There is no unref since this is the work of eina_stringshare_del().
EAPI void eina_stringshare_del | ( | const char * | str | ) |
Note that the given string has lost an instance.
- Parameters:
-
str string The given string.
This function decreases the reference counter associated to str
if it exists. If that counter reaches 0, the memory associated to str
is freed. If str
is NULL, the function returns immediatly.
Note that if the given pointer is not shared or NULL, bad things will happen, likely a segmentation fault.
References EINA_ERROR_PWARN.
EAPI int eina_stringshare_strlen | ( | const char * | str | ) |
Note that the given string must be shared.
- Parameters:
-
str the shared string to know the length. It is safe to give NULL, in that case -1 is returned.
This function is a cheap way to known the length of a shared string. Note that if the given pointer is not shared or NULL, bad things will happen, likely a segmentation fault. If in doubt, try strlen().
EAPI void eina_stringshare_dump | ( | void | ) |
Dump the contents of the stringshare.
This function dumps all strings in the stringshare to stdout with a DDD: prefix per line and a memory usage summary.
References eina_iterator_foreach(), and eina_iterator_free().