From 8164139fa6259257817898b3d389d96bd60f8c13 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Fri, 22 Nov 2002 22:30:02 +0000 Subject: 2002-11-22 Havoc Pennington * dbus/dbus.h: fixups for doc warnings * Doxyfile.in (FILE_PATTERNS): we need to scan .h to pick up macros (QUIET): make it quiet so we can see warnings * dbus/dbus-memory.c: teach D-BUS to allocate and free memory --- ChangeLog | 10 ++++ Doxyfile.in | 4 +- dbus/Makefile.am | 9 +++- dbus/dbus-hash.h | 0 dbus/dbus-memory.c | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++ dbus/dbus-memory.h | 46 +++++++++++++++++ dbus/dbus-message.c | 6 +-- dbus/dbus.h | 9 ++-- 8 files changed, 214 insertions(+), 9 deletions(-) create mode 100644 dbus/dbus-hash.h create mode 100644 dbus/dbus-memory.c create mode 100644 dbus/dbus-memory.h diff --git a/ChangeLog b/ChangeLog index 489f84aa..31f23c14 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2002-11-22 Havoc Pennington + + * dbus/dbus.h: fixups for doc warnings + + * Doxyfile.in (FILE_PATTERNS): we need to scan .h to pick up + macros + (QUIET): make it quiet so we can see warnings + + * dbus/dbus-memory.c: teach D-BUS to allocate and free memory + 2002-11-22 Havoc Pennington * Makefile.am: include "Doxyfile" target in all-local diff --git a/Doxyfile.in b/Doxyfile.in index 224271b0..d7b7019d 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -41,7 +41,7 @@ SHOW_USED_FILES = YES #--------------------------------------------------------------------------- # configuration options related to warning and progress messages #--------------------------------------------------------------------------- -QUIET = NO +QUIET = YES WARNINGS = YES WARN_IF_UNDOCUMENTED = YES WARN_FORMAT = @@ -50,7 +50,7 @@ WARN_LOGFILE = # configuration options related to the input files #--------------------------------------------------------------------------- INPUT = dbus bus -FILE_PATTERNS = *.c +FILE_PATTERNS = *.c *.h RECURSIVE = YES #EXCLUDE = test diff --git a/dbus/Makefile.am b/dbus/Makefile.am index c233c766..e39897d2 100644 --- a/dbus/Makefile.am +++ b/dbus/Makefile.am @@ -8,15 +8,22 @@ lib_LTLIBRARIES=libdbus-1.la dbusinclude_HEADERS= \ dbus.h \ dbus-macros.h \ + dbus-memory.h \ dbus-message.h libdbus_1_la_SOURCES= \ + dbus-memory.c \ dbus-message.c +## this library is linked into both libdbus and the bus +## itself, but does not export any symbols from libdbus. +## It contains utility functions not in the public API. + noinst_LTLIBRARIES=libdbus-convenience.la libdbus_convenience_la_SOURCES= \ - dbus-hash.c + dbus-hash.c \ + dbus-hash.h libdbus_1_la_LIBADD= $(DBUS_CLIENT_LIBS) libdbus-convenience.la ## don't export symbols that start with "_" (we use this diff --git a/dbus/dbus-hash.h b/dbus/dbus-hash.h new file mode 100644 index 00000000..e69de29b diff --git a/dbus/dbus-memory.c b/dbus/dbus-memory.c new file mode 100644 index 00000000..018c45d3 --- /dev/null +++ b/dbus/dbus-memory.c @@ -0,0 +1,139 @@ +/* -*- mode: C; c-file-style: "gnu" -*- */ +/* dbus-memory.c D-BUS memory handling + * + * Copyright (C) 2002 Red Hat Inc. + * + * Licensed under the Academic Free License version 1.2 + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * + */ + +#include "dbus-memory.h" +#include + +/** + * @defgroup Memory Memory Allocation + * @ingroup DBus + * @brief dbus_malloc(), dbus_free(), etc. + * + * Functions and macros related to allocating and releasing + * blocks of memory. + * + * @{ + */ + +/** + * @def dbus_new + * + * Safe macro for using dbus_malloc(). Accepts the type + * to allocate and the number of type instances to + * allocate as arguments, and returns a memory block + * cast to the desired type, instead of as a void*. + * + * @param type type name to allocate + * @param count number of instances in the allocated array + * @returns the new memory block or NULL on failure + */ + +/** + * @def dbus_new0 + * + * Safe macro for using dbus_malloc0(). Accepts the type + * to allocate and the number of type instances to + * allocate as arguments, and returns a memory block + * cast to the desired type, instead of as a void*. + * The allocated array is initialized to all-bits-zero. + * + * @param type type name to allocate + * @param count number of instances in the allocated array + * @returns the new memory block or NULL on failure + */ + +/** + * Allocates the given number of bytes, as with standard + * malloc(). Guaranteed to return NULL if bytes is zero + * on all platforms. Returns NULL if the allocation fails. + * The memory must be released with dbus_free(). + * + * @param bytes number of bytes to allocate + * @return allocated memory, or NULL if the allocation fails. + */ +void* +dbus_malloc (size_t bytes) +{ + if (bytes == 0) /* some system mallocs handle this, some don't */ + return NULL; + else + return malloc (bytes); +} + +/** + * Allocates the given number of bytes, as with standard malloc(), but + * all bytes are initialized to zero as with calloc(). Guaranteed to + * return NULL if bytes is zero on all platforms. Returns NULL if the + * allocation fails. The memory must be released with dbus_free(). + * + * @param bytes number of bytes to allocate + * @return allocated memory, or NULL if the allocation fails. + */ +void* +dbus_malloc0 (size_t bytes) +{ + if (bytes == 0) + return NULL; + else + return calloc (bytes, 1); +} + +/** + * Resizes a block of memory previously allocated by dbus_malloc() or + * dbus_malloc0(). Guaranteed to free the memory and return NULL if bytes + * is zero on all platforms. Returns NULL if the resize fails. + * If the resize fails, the memory is not freed. + * + * @param memory block to be resized + * @param bytes new size of the memory block + * @return allocated memory, or NULL if the resize fails. + */ +void* +dbus_realloc (void *memory, + size_t bytes) +{ + if (bytes == 0) /* guarantee this is safe */ + { + dbus_free (memory); + return NULL; + } + else + { + return realloc (memory, bytes); + } +} + +/** + * Frees a block of memory previously allocated by dbus_malloc() or + * dbus_malloc0(). + * + * @param memory block to be freed + */ +void +dbus_free (void *memory) +{ + if (memory) /* we guarantee it's safe to free (NULL) */ + free (memory); +} + +/** @} */ diff --git a/dbus/dbus-memory.h b/dbus/dbus-memory.h new file mode 100644 index 00000000..b8b6559c --- /dev/null +++ b/dbus/dbus-memory.h @@ -0,0 +1,46 @@ +/* -*- mode: C; c-file-style: "gnu" -*- */ +/* dbus-memory.h D-BUS memory handling + * + * Copyright (C) 2002 Red Hat Inc. + * + * Licensed under the Academic Free License version 1.2 + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * + */ +#if !defined (DBUS_INSIDE_DBUS_H) && !defined (DBUS_COMPILATION) +#error "Only can be included directly, this file may disappear or change contents." +#endif + +#ifndef DBUS_MEMORY_H +#define DBUS_MEMORY_H + +#include +#include /* for size_t - is there a better header for this? */ + +DBUS_BEGIN_DECLS + +void* dbus_malloc (size_t bytes); +void* dbus_malloc0 (size_t bytes); +void* dbus_realloc (void *memory, + size_t bytes); +void dbus_free (void *memory); + +#define dbus_new(type, count) ((type*)dbus_malloc (sizeof (type) * (count))); +#define dbus_new0(type, count) ((type*)dbus_malloc0 (sizeof (type) * (count))); + +DBUS_END_DECLS + +#endif /* DBUS_MESSAGE_H */ diff --git a/dbus/dbus-message.c b/dbus/dbus-message.c index 4bda9481..1064f424 100644 --- a/dbus/dbus-message.c +++ b/dbus/dbus-message.c @@ -24,7 +24,7 @@ #include "dbus-message.h" /** - * @defgroup DBusMessage + * @defgroup DBusMessage DBusMessage * @ingroup DBus * @brief DBusMessage object * @@ -55,7 +55,7 @@ dbus_message_new (void) /** * Increments the reference count of a DBusMessage. * - * @arg message The message + * @param message The message * @see dbus_message_unref */ void @@ -67,7 +67,7 @@ dbus_message_ref (DBusMessage *message) /** * Decrements the reference count of a DBusMessage. * - * @arg message The message + * @param message The message * @see dbus_message_ref */ void diff --git a/dbus/dbus.h b/dbus/dbus.h index 3d166df4..74c64465 100644 --- a/dbus/dbus.h +++ b/dbus/dbus.h @@ -29,12 +29,15 @@ #include #include +#undef DBUS_INSIDE_DBUS_H + /** - * @defgroup DBus + * @defgroup DBus D-BUS message system + * + * @{ */ -#undef DBUS_INSIDE_DBUS_H - /** @} */ + #endif /* DBUS_H -- cgit