Audacious  $Id:Doxyfile42802007-03-2104:39:00Znenolod$
core.h
Go to the documentation of this file.
00001 /*
00002  * core.h
00003  * Copyright 2011 John Lindgren
00004  *
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions are met:
00007  *
00008  * 1. Redistributions of source code must retain the above copyright notice,
00009  *    this list of conditions, and the following disclaimer.
00010  *
00011  * 2. Redistributions in binary form must reproduce the above copyright notice,
00012  *    this list of conditions, and the following disclaimer in the documentation
00013  *    provided with the distribution.
00014  *
00015  * This software is provided "as is" and without any warranty, express or
00016  * implied. In no event shall the authors be liable for any damages arising from
00017  * the use of this software.
00018  */
00019 
00020 #ifndef LIBAUDCORE_CORE_H
00021 #define LIBAUDCORE_CORE_H
00022 
00023 /* #define STRPOOL_DEBUG */
00024 
00025 /* "bool_t" means "int" for compatibility with GLib */
00026 #undef bool_t
00027 #define bool_t int
00028 
00029 #undef FALSE
00030 #define FALSE ((bool_t) 0)
00031 #undef TRUE
00032 #define TRUE ((bool_t) 1)
00033 
00034 /* Simple sanity check to catch (1) strings that are still in use after their
00035  * reference count has dropped to zero and (2) strings that should have been
00036  * pooled but never were.  If the check fails, the program is aborted. */
00037 #define STR_CHECK(str) do {if ((str) && (str)[-1] != '@') strpool_abort (str);} while (0)
00038 
00039 /* If the pool contains a copy of <str>, increments its reference count.
00040  * Otherwise, adds a copy of <str> to the pool with a reference count of one.
00041  * In either case, returns the copy.  Because this copy may be shared by other
00042  * parts of the code, it should not be modified.  If <str> is NULL, simply
00043  * returns NULL with no side effects. */
00044 #ifdef STRPOOL_DEBUG
00045 char * str_get_debug (const char * str, const char * file, int line);
00046 #define str_get(str) str_get_debug (str, __FILE__, __LINE__)
00047 #else
00048 char * str_get (const char * str);
00049 #endif
00050 
00051 /* Increments the reference count of <str>, where <str> is the address of a
00052  * string already in the pool.  Faster than calling str_get() a second time.
00053  * Returns <str> for convenience.  If <str> is NULL, simply returns NULL with no
00054  * side effects. */
00055 #ifdef STRPOOL_DEBUG
00056 char * str_ref_debug (char * str, const char * file, int line);
00057 #define str_ref(str) str_ref_debug (str, __FILE__, __LINE__)
00058 #else
00059 char * str_ref (char * str);
00060 #endif
00061 
00062 /* Decrements the reference count of <str>, where <str> is the address of a
00063  * string in the pool.  If the reference count drops to zero, releases the
00064  * memory used by <str>.   If <str> is NULL, simply returns NULL with no side
00065  * effects. */
00066 #ifdef STRPOOL_DEBUG
00067 void str_unref_debug (char * str, const char * file, int line);
00068 #define str_unref(str) str_unref_debug (str, __FILE__, __LINE__)
00069 #else
00070 void str_unref (char * str);
00071 #endif
00072 
00073 /* Calls str_get() on the first <len> characters of <str>.  If <str> has less
00074  * than or equal to <len> characters, equivalent to str_get(). */
00075 char * str_nget (const char * str, int len);
00076 
00077 /* Calls sprintf() internally, then pools the produced string with str_get(). */
00078 char * str_printf (const char * format, ...);
00079 
00080 /* Used by STR_CHECK; should not be called directly. */
00081 void strpool_abort (char * str);
00082 
00083 /* Releases all memory used by the string pool.  If strings remain in the pool,
00084  * a warning may be printed to stderr in order to reveal memory leaks. */
00085 void strpool_shutdown (void);
00086 
00087 #endif /* LIBAUDCORE_CORE_H */