Commit 410a80c4 authored by Havoc Pennington's avatar Havoc Pennington

2003-04-29 Havoc Pennington <hp@redhat.com>

	* glib/dbus-gmain.c: docs cleanups

	* dbus/dbus-types.h: add docs on int64 types

	* dbus/dbus-memory.c: fix docs to avoid putting private API in
	public API docs section
parent ae759bff
2003-04-29 Havoc Pennington <hp@redhat.com>
* glib/dbus-gmain.c: docs cleanups
* dbus/dbus-types.h: add docs on int64 types
* dbus/dbus-memory.c: fix docs to avoid putting private API in
public API docs section
2003-04-29 Havoc Pennington <hp@redhat.com> 2003-04-29 Havoc Pennington <hp@redhat.com>
* dbus-1.pc.in, dbus-glib-1.pc.in: rename these from * dbus-1.pc.in, dbus-glib-1.pc.in: rename these from
......
...@@ -39,7 +39,7 @@ ...@@ -39,7 +39,7 @@
* *
* @code * @code
* DBusError error; * DBusError error;
* _dbus_error_init (&error); * dbus_error_init (&error);
* dbus_some_function (arg1, arg2, &error); * dbus_some_function (arg1, arg2, &error);
* if (dbus_error_is_set (&error)) * if (dbus_error_is_set (&error))
* { * {
...@@ -178,6 +178,8 @@ dbus_error_free (DBusError *error) ...@@ -178,6 +178,8 @@ dbus_error_free (DBusError *error)
* message will be deduced from the name. If the error name is unknown * message will be deduced from the name. If the error name is unknown
* to D-BUS the default message will be totally useless, though. * to D-BUS the default message will be totally useless, though.
* *
* @todo should be called dbus_error_set_const()
*
* @param error the error. * @param error the error.
* @param name the error name (not copied!!!) * @param name the error name (not copied!!!)
* @param message the error message (not copied!!!) * @param message the error message (not copied!!!)
...@@ -214,7 +216,7 @@ dbus_set_error_const (DBusError *error, ...@@ -214,7 +216,7 @@ dbus_set_error_const (DBusError *error,
* src is reinitialized to an empty error. dest may not * src is reinitialized to an empty error. dest may not
* contain an existing error. If the destination is * contain an existing error. If the destination is
* #NULL, just frees and reinits the source error. * #NULL, just frees and reinits the source error.
* *
* @param src the source error * @param src the source error
* @param dest the destination error or #NULL * @param dest the destination error or #NULL
*/ */
...@@ -288,6 +290,8 @@ dbus_error_is_set (const DBusError *error) ...@@ -288,6 +290,8 @@ dbus_error_is_set (const DBusError *error)
* If no memory can be allocated for the error message, * If no memory can be allocated for the error message,
* an out-of-memory error message will be set instead. * an out-of-memory error message will be set instead.
* *
* @todo should be called dbus_error_set()
*
* @todo stdio.h shouldn't be included in this file, * @todo stdio.h shouldn't be included in this file,
* should write _dbus_string_append_printf instead * should write _dbus_string_append_printf instead
* *
......
...@@ -27,7 +27,6 @@ ...@@ -27,7 +27,6 @@
#include "dbus-list.h" #include "dbus-list.h"
#include <stdlib.h> #include <stdlib.h>
/** /**
* @defgroup DBusMemory Memory Allocation * @defgroup DBusMemory Memory Allocation
* @ingroup DBus * @ingroup DBus
...@@ -36,6 +35,20 @@ ...@@ -36,6 +35,20 @@
* Functions and macros related to allocating and releasing * Functions and macros related to allocating and releasing
* blocks of memory. * blocks of memory.
* *
*/
/**
* @defgroup DBusMemoryInternals Memory allocation implementation details
* @ingroup DBusInternals
* @brief internals of dbus_malloc() etc.
*
* Implementation details related to allocating and releasing blocks
* of memory.
*/
/**
* @addtogroup DBusMemory
*
* @{ * @{
*/ */
...@@ -74,6 +87,14 @@ ...@@ -74,6 +87,14 @@
* @param memory the memory to free * @param memory the memory to free
*/ */
/** @} */ /* end of public API docs */
/**
* @addtogroup DBusMemoryInternals
*
* @{
*/
#ifdef DBUS_BUILD_TESTS #ifdef DBUS_BUILD_TESTS
static dbus_bool_t debug_initialized = FALSE; static dbus_bool_t debug_initialized = FALSE;
static int fail_nth = -1; static int fail_nth = -1;
...@@ -387,6 +408,15 @@ set_guards (void *real_block, ...@@ -387,6 +408,15 @@ set_guards (void *real_block,
#endif #endif
/** @} */ /* End of internals docs */
/**
* @addtogroup DBusMemory
*
* @{
*/
/** /**
* Allocates the given number of bytes, as with standard * Allocates the given number of bytes, as with standard
* malloc(). Guaranteed to return #NULL if bytes is zero * malloc(). Guaranteed to return #NULL if bytes is zero
...@@ -625,6 +655,15 @@ dbus_free_string_array (char **str_array) ...@@ -625,6 +655,15 @@ dbus_free_string_array (char **str_array)
} }
} }
/** @} */ /* End of public API docs block */
/**
* @addtogroup DBusMemoryInternals
*
* @{
*/
/** /**
* _dbus_current_generation is used to track each * _dbus_current_generation is used to track each
* time that dbus_shutdown() is called, so we can * time that dbus_shutdown() is called, so we can
...@@ -651,36 +690,6 @@ struct ShutdownClosure ...@@ -651,36 +690,6 @@ struct ShutdownClosure
_DBUS_DEFINE_GLOBAL_LOCK (shutdown_funcs); _DBUS_DEFINE_GLOBAL_LOCK (shutdown_funcs);
static ShutdownClosure *registered_globals = NULL; static ShutdownClosure *registered_globals = NULL;
/**
* The D-BUS library keeps some internal global variables, for example
* to cache the username of the current process. This function is
* used to free these global variables. It is really useful only for
* leak-checking cleanliness and the like. WARNING: this function is
* NOT thread safe, it must be called while NO other threads are using
* D-BUS. You cannot continue using D-BUS after calling this function,
* as it does things like free global mutexes created by
* dbus_threads_init(). To use a D-BUS function after calling
* dbus_shutdown(), you have to start over from scratch, e.g. calling
* dbus_threads_init() again.
*/
void
dbus_shutdown (void)
{
while (registered_globals != NULL)
{
ShutdownClosure *c;
c = registered_globals;
registered_globals = c->next;
(* c->func) (c->data);
dbus_free (c);
}
_dbus_current_generation += 1;
}
/** /**
* Register a cleanup function to be called exactly once * Register a cleanup function to be called exactly once
* the next time dbus_shutdown() is called. * the next time dbus_shutdown() is called.
...@@ -713,4 +722,43 @@ _dbus_register_shutdown_func (DBusShutdownFunction func, ...@@ -713,4 +722,43 @@ _dbus_register_shutdown_func (DBusShutdownFunction func,
return TRUE; return TRUE;
} }
/** @} */ /** @} */ /* End of private API docs block */
/**
* @addtogroup DBusMemory
*
* @{
*/
/**
* The D-BUS library keeps some internal global variables, for example
* to cache the username of the current process. This function is
* used to free these global variables. It is really useful only for
* leak-checking cleanliness and the like. WARNING: this function is
* NOT thread safe, it must be called while NO other threads are using
* D-BUS. You cannot continue using D-BUS after calling this function,
* as it does things like free global mutexes created by
* dbus_threads_init(). To use a D-BUS function after calling
* dbus_shutdown(), you have to start over from scratch, e.g. calling
* dbus_threads_init() again.
*/
void
dbus_shutdown (void)
{
while (registered_globals != NULL)
{
ShutdownClosure *c;
c = registered_globals;
registered_globals = c->next;
(* c->func) (c->data);
dbus_free (c);
}
_dbus_current_generation += 1;
}
/** @} */ /** End of public API docs block */
...@@ -137,7 +137,7 @@ _dbus_timeout_set_interval (DBusTimeout *timeout, ...@@ -137,7 +137,7 @@ _dbus_timeout_set_interval (DBusTimeout *timeout,
* only used in the message bus daemon implementation. * only used in the message bus daemon implementation.
* *
* @param timeout the timeout * @param timeout the timeout
* @param interval the new interval * @param enabled #TRUE if timeout should be enabled.
*/ */
void void
_dbus_timeout_set_enabled (DBusTimeout *timeout, _dbus_timeout_set_enabled (DBusTimeout *timeout,
......
...@@ -77,6 +77,37 @@ typedef dbus_uint32_t dbus_unichar_t; ...@@ -77,6 +77,37 @@ typedef dbus_uint32_t dbus_unichar_t;
* A 16-bit signed integer on all platforms. * A 16-bit signed integer on all platforms.
*/ */
/**
* @typedef dbus_uint64_t
*
* A 64-bit unsigned integer on all platforms that support it.
* If supported, #DBUS_HAVE_INT64 will be defined.
*/
/**
* @typedef dbus_int64_t
*
* A 64-bit signed integer on all platforms that support it.
* If supported, #DBUS_HAVE_INT64 will be defined.
*/
/**
* @def DBUS_INT64_CONSTANT
*
* Declare a 64-bit signed integer constant. The macro
* adds the necessary "LL" or whatever after the integer,
* giving a literal such as "325145246765LL"
*/
/**
* @def DBUS_UINT64_CONSTANT
*
* Declare a 64-bit unsigned integer constant. The macro
* adds the necessary "ULL" or whatever after the integer,
* giving a literal such as "325145246765ULL"
*/
/** @} */ /** @} */
#endif /* DBUS_TYPES_H */ #endif /* DBUS_TYPES_H */
...@@ -394,8 +394,11 @@ create_source (void *connection_or_server, ...@@ -394,8 +394,11 @@ create_source (void *connection_or_server,
/** /**
* Sets the watch and timeout functions of a #DBusConnection * Sets the watch and timeout functions of a #DBusConnection
* to integrate the connection with the GLib main loop. * to integrate the connection with the GLib main loop.
* Pass in #NULL for the #GMainContext unless you're
* doing something specialized.
* *
* @param connection the connection * @param connection the connection
* @param context the #GMainContext or #NULL for default context
*/ */
void void
dbus_connection_setup_with_g_main (DBusConnection *connection, dbus_connection_setup_with_g_main (DBusConnection *connection,
...@@ -446,11 +449,14 @@ dbus_connection_setup_with_g_main (DBusConnection *connection, ...@@ -446,11 +449,14 @@ dbus_connection_setup_with_g_main (DBusConnection *connection,
/** /**
* Sets the watch and timeout functions of a #DBusServer * Sets the watch and timeout functions of a #DBusServer
* to integrate the server with the GLib main loop. * to integrate the server with the GLib main loop.
* In most cases the context argument should be #NULL.
* *
* @param server the server * @param server the server
* @param context the #GMainContext or #NULL for default
*/ */
void void
dbus_server_setup_with_g_main (DBusServer *server, GMainContext *context) dbus_server_setup_with_g_main (DBusServer *server,
GMainContext *context)
{ {
GSource *source; GSource *source;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment