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 #undef NULL
00026 #ifdef __cplusplus /* *sigh* */
00027 #define NULL 0
00028 #else
00029 #define NULL ((void *) 0)
00030 #endif
00031 
00032 /* "bool_t" means "int" for compatibility with GLib */
00033 #undef bool_t
00034 #define bool_t int
00035 
00036 #undef FALSE
00037 #define FALSE ((bool_t) 0)
00038 #undef TRUE
00039 #define TRUE ((bool_t) 1)
00040 
00041 /* Simple sanity check to catch (1) strings that are still in use after their
00042  * reference count has dropped to zero and (2) strings that should have been
00043  * pooled but never were.  If the check fails, the program is aborted. */
00044 #define STR_CHECK(str) do {if ((str) && (str)[-1] != '@') strpool_abort (str);} while (0)
00045 
00046 /* If the pool contains a copy of <str>, increments its reference count.
00047  * Otherwise, adds a copy of <str> to the pool with a reference count of one.
00048  * In either case, returns the copy.  Because this copy may be shared by other
00049  * parts of the code, it should not be modified.  If <str> is NULL, simply
00050  * returns NULL with no side effects. */
00051 #ifdef STRPOOL_DEBUG
00052 char * str_get_debug (const char * str, const char * file, int line);
00053 #define str_get(str) str_get_debug (str, __FILE__, __LINE__)
00054 #else
00055 char * str_get (const char * str);
00056 #endif
00057 
00058 /* Increments the reference count of <str>, where <str> is the address of a
00059  * string already in the pool.  Faster than calling str_get() a second time.
00060  * Returns <str> for convenience.  If <str> is NULL, simply returns NULL with no
00061  * side effects. */
00062 #ifdef STRPOOL_DEBUG
00063 char * str_ref_debug (char * str, const char * file, int line);
00064 #define str_ref(str) str_ref_debug (str, __FILE__, __LINE__)
00065 #else
00066 char * str_ref (char * str);
00067 #endif
00068 
00069 /* Decrements the reference count of <str>, where <str> is the address of a
00070  * string in the pool.  If the reference count drops to zero, releases the
00071  * memory used by <str>.   If <str> is NULL, simply returns NULL with no side
00072  * effects. */
00073 #ifdef STRPOOL_DEBUG
00074 void str_unref_debug (char * str, const char * file, int line);
00075 #define str_unref(str) str_unref_debug (str, __FILE__, __LINE__)
00076 #else
00077 void str_unref (char * str);
00078 #endif
00079 
00080 /* Calls str_get() on the first <len> characters of <str>.  If <str> has less
00081  * than or equal to <len> characters, equivalent to str_get(). */
00082 char * str_nget (const char * str, int len);
00083 
00084 /* Calls sprintf() internally, then pools the produced string with str_get(). */
00085 char * str_printf (const char * format, ...);
00086 
00087 /* Used by STR_CHECK; should not be called directly. */
00088 void strpool_abort (char * str);
00089 
00090 /* Releases all memory used by the string pool.  If strings remain in the pool,
00091  * a warning may be printed to stderr in order to reveal memory leaks. */
00092 void strpool_shutdown (void);
00093 
00094 #endif /* LIBAUDCORE_CORE_H */