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 */