enlightenment/efl
enlightenment
/
efl
8
7
Fork 14
Code Issues 13 Pull Requests 3 Projects Releases Wiki Activity

doxy -> .h 

SVN revision: 58445
This commit is contained in:
Carsten Haitzler 2011-04-07 13:13:11 +00:00
parent c46642cb97
commit 703b835643
2 changed files with 180 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

180
legacy/eina/src/include/eina_stringshare.h
View File

@ -55,6 +55,30 @@
#include "eina_types.h"
/**
* @addtogroup Eina_Stringshare_Group Stringshare
*
* 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 @ref tutorial_stringshare_page.
*
* @{
*/
/**
* @addtogroup Eina_Data_Types_Group Data Types
*
@ -67,14 +91,166 @@
* @{
*/
/**
* @brief Retrieve an instance of a string for use in a program.
*
* @param str The string to retrieve an instance of.
* @param slen The string size (<= strlen(str)).
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This function retrieves an instance of @p str. If @p str is
* @c NULL, then @c NULL is returned. If @p 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 @p str is returned.
*
* This function does not check string size, but uses the
* exact given size. This can be used to share_common part of a larger
* buffer or substring.
*
* @see eina_share_common_add()
*/
EAPI const char *eina_stringshare_add_length(const char *str, unsigned int slen) EINA_WARN_UNUSED_RESULT;
/**
* @brief Retrieve an instance of a string for use in a program.
*
* @param str The NULL terminated string to retrieve an instance of.
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This function retrieves an instance of @p str. If @p str is
* @c NULL, then @c NULL is returned. If @p 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 @p str is returned.
*
* The string @p str must be NULL terminated ('@\0') and its full
* length will be used. To use part of the string or non-null
* terminated, use eina_stringshare_add_length() instead.
*
* @see eina_stringshare_add_length()
*/
EAPI const char *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_RESULT;
/**
* @brief Retrieve an instance of a string for use in a program
* from a format string.
*
* @param fmt The NULL terminated format string to retrieve an instance of.
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This function retrieves an instance of @p fmt. If @p fmt is
* @c NULL, then @c NULL is returned. If @p fmt 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
* is returned.
*
* The format string @p fmt must be NULL terminated ('@\0') and its full
* length will be used. To use part of the format string or non-null
* terminated, use eina_stringshare_nprintf() instead.
*
* @see eina_stringshare_nprintf()
*/
EAPI const char *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(1, 2);
/**
* @brief Retrieve an instance of a string for use in a program
* from a format string.
*
* @param fmt The NULL terminated format string to retrieve an instance of.
* @param args The va_args for @p fmt
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This function retrieves an instance of @p fmt with @p args. If @p fmt is
* @c NULL, then @c NULL is returned. If @p fmt with @p args 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
* is returned.
*
* The format string @p fmt must be NULL terminated ('@\0') and its full
* length will be used. To use part of the format string or non-null
* terminated, use eina_stringshare_nprintf() instead.
*
* @see eina_stringshare_nprintf()
*/
EAPI const char *eina_stringshare_vprintf(const char *fmt, va_list args) EINA_WARN_UNUSED_RESULT;
/**
* @brief Retrieve an instance of a string for use in a program
* from a format string with size limitation.
* @param len The length of the format string to use
* @param fmt The format string to retrieve an instance of.
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This function retrieves an instance of @p fmt limited by @p len. If @p fmt is
* @c NULL or @p len is < 1, then @c NULL is returned. If the resulting string
* is already stored, it is returned and its reference counter is increased. Otherwise
* it is added to the strings to be searched and a duplicated string
* is returned.
*
* @p len length of the format string will be used. To use the
* entire format string, use eina_stringshare_printf() instead.
*
* @see eina_stringshare_printf()
*/
EAPI const char *eina_stringshare_nprintf(unsigned int len, const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(2, 3);
/**
* Increment references of the given shared string.
*
* @param str The shared string.
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This is similar to eina_share_common_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_share_common_add().
*
* There is no unref since this is the work of eina_share_common_del().
*/
EAPI const char *eina_stringshare_ref(const char *str);
/**
* @brief Note that the given string has lost an instance.
*
* @param str string The given string.
*
* This function decreases the reference counter associated to @p str
* if it exists. If that counter reaches 0, the memory associated to
* @p str is freed. If @p str is NULL, the function returns
* immediately.
*
* Note that if the given pointer is not shared or NULL, bad things
* will happen, likely a segmentation fault.
*/
EAPI void eina_stringshare_del(const char *str);
/**
* @brief Note that the given string @b must be shared.
*
* @param 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, bad
* things will happen, likely a segmentation fault. If in doubt, try
* strlen().
*/
EAPI int eina_stringshare_strlen(const char *str) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
* @brief Dump the contents of the share_common.
*
* This function dumps all strings in the share_common to stdout with a
* DDD: prefix per line and a memory usage summary.
*/
EAPI void eina_stringshare_dump(void);
static inline Eina_Bool eina_stringshare_replace(const char **p_str, const char *news) EINA_ARG_NONNULL(1);
@ -90,4 +266,8 @@ static inline Eina_Bool eina_stringshare_replace_length(const char **p_str, cons
* @}
*/
/**
* @}
*/
#endif /* EINA_STRINGSHARE_H_ */

179
legacy/eina/src/lib/eina_stringshare.c
View File

@ -22,13 +22,6 @@
* if not, see <http://www.gnu.org/licenses/>.
*/
/**
* @page tutorial_stringshare_page Stringshare Tutorial
*
* to be written...
*
*/
#ifdef HAVE_CONFIG_H
# include "config.h"
#endif
@ -561,43 +554,6 @@ eina_stringshare_shutdown(void)
* API *
*============================================================================*/
/**
* @addtogroup Eina_Stringshare_Group Stringshare
*
* 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 @ref tutorial_stringshare_page.
*
* @{
*/
/**
* @brief Note that the given string has lost an instance.
*
* @param str string The given string.
*
* This function decreases the reference counter associated to @p str
* if it exists. If that counter reaches 0, the memory associated to
* @p str is freed. If @p str is NULL, the function returns
* immediately.
*
* Note that if the given pointer is not shared or NULL, bad things
* will happen, likely a segmentation fault.
*/
EAPI void
eina_stringshare_del(const char *str)
{
@ -632,26 +588,6 @@ eina_stringshare_del(const char *str)
eina_share_common_del(stringshare_share, str);
}
/**
* @brief Retrieve an instance of a string for use in a program.
*
* @param str The string to retrieve an instance of.
* @param slen The string size (<= strlen(str)).
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This function retrieves an instance of @p str. If @p str is
* @c NULL, then @c NULL is returned. If @p 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 @p str is returned.
*
* This function does not check string size, but uses the
* exact given size. This can be used to share_common part of a larger
* buffer or substring.
*
* @see eina_share_common_add()
*/
EAPI const char *
eina_stringshare_add_length(const char *str, unsigned int slen)
{
@ -675,25 +611,6 @@ eina_stringshare_add_length(const char *str, unsigned int slen)
sizeof(char), sizeof(char));
}
/**
* @brief Retrieve an instance of a string for use in a program.
*
* @param str The NULL terminated string to retrieve an instance of.
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This function retrieves an instance of @p str. If @p str is
* @c NULL, then @c NULL is returned. If @p 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 @p str is returned.
*
* The string @p str must be NULL terminated ('@\0') and its full
* length will be used. To use part of the string or non-null
* terminated, use eina_stringshare_add_length() instead.
*
* @see eina_stringshare_add_length()
*/
EAPI const char *
eina_stringshare_add(const char *str)
{
@ -715,26 +632,6 @@ eina_stringshare_add(const char *str)
return eina_stringshare_add_length(str, slen);
}
/**
* @brief Retrieve an instance of a string for use in a program
* from a format string.
*
* @param fmt The NULL terminated format string to retrieve an instance of.
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This function retrieves an instance of @p fmt. If @p fmt is
* @c NULL, then @c NULL is returned. If @p fmt 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
* is returned.
*
* The format string @p fmt must be NULL terminated ('@\0') and its full
* length will be used. To use part of the format string or non-null
* terminated, use eina_stringshare_nprintf() instead.
*
* @see eina_stringshare_nprintf()
*/
EAPI const char *
eina_stringshare_printf(const char *fmt, ...)
{
@ -759,27 +656,6 @@ eina_stringshare_printf(const char *fmt, ...)
return ret;
}
/**
* @brief Retrieve an instance of a string for use in a program
* from a format string.
*
* @param fmt The NULL terminated format string to retrieve an instance of.
* @param args The va_args for @p fmt
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This function retrieves an instance of @p fmt with @p args. If @p fmt is
* @c NULL, then @c NULL is returned. If @p fmt with @p args 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
* is returned.
*
* The format string @p fmt must be NULL terminated ('@\0') and its full
* length will be used. To use part of the format string or non-null
* terminated, use eina_stringshare_nprintf() instead.
*
* @see eina_stringshare_nprintf()
*/
EAPI const char *
eina_stringshare_vprintf(const char *fmt, va_list args)
{
@ -801,25 +677,6 @@ eina_stringshare_vprintf(const char *fmt, va_list args)
return ret;
}
/**
* @brief Retrieve an instance of a string for use in a program
* from a format string with size limitation.
* @param len The length of the format string to use
* @param fmt The format string to retrieve an instance of.
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This function retrieves an instance of @p fmt limited by @p len. If @p fmt is
* @c NULL or @p len is < 1, then @c NULL is returned. If the resulting string
* is already stored, it is returned and its reference counter is increased. Otherwise
* it is added to the strings to be searched and a duplicated string
* is returned.
*
* @p len length of the format string will be used. To use the
* entire format string, use eina_stringshare_printf() instead.
*
* @see eina_stringshare_printf()
*/
EAPI const char *
eina_stringshare_nprintf(unsigned int len, const char *fmt, ...)
{
@ -845,20 +702,6 @@ eina_stringshare_nprintf(unsigned int len, const char *fmt, ...)
return eina_stringshare_add_length(tmp, len);
}
/**
* Increment references of the given shared string.
*
* @param str The shared string.
* @return A pointer to an instance of the string on success.
* @c NULL on failure.
*
* This is similar to eina_share_common_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_share_common_add().
*
* There is no unref since this is the work of eina_share_common_del().
*/
EAPI const char *
eina_stringshare_ref(const char *str)
{
@ -901,17 +744,6 @@ eina_stringshare_ref(const char *str)
return eina_share_common_ref(stringshare_share, str);
}
/**
* @brief Note that the given string @b must be shared.
*
* @param 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, bad
* things will happen, likely a segmentation fault. If in doubt, try
* strlen().
*/
EAPI int
eina_stringshare_strlen(const char *str)
{
@ -934,12 +766,6 @@ eina_stringshare_strlen(const char *str)
return len;
}
/**
* @brief Dump the contents of the share_common.
*
* This function dumps all strings in the share_common to stdout with a
* DDD: prefix per line and a memory usage summary.
*/
EAPI void
eina_stringshare_dump(void)
{
@ -947,8 +773,3 @@ eina_stringshare_dump(void)
_eina_stringshare_small_dump,
sizeof(_eina_stringshare_single));
}
/**
* @}
*/