2006-10-27 Havoc Pennington <hp@redhat.com>

	* dbus/dbus-connection.c (dbus_connection_open_private): document
	how to choose shared vs. private connections

diff --git a/ChangeLog b/ChangeLog
index f0d4d89..7e5458b 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,9 @@
 2006-10-27  Havoc Pennington  <hp@redhat.com>
+       
+       * dbus/dbus-connection.c (dbus_connection_open_private): document
+       how to choose shared vs. private connections
+
+2006-10-27  Havoc Pennington  <hp@redhat.com>
 
        * dbus/dbus-test.c: enclose more of the file in the
        DBUS_BUILD_TESTS check.

diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c
index db62558..552ecfd 100644 (file)
--- a/dbus/dbus-connection.c
+++ b/dbus/dbus-connection.c
@@ -2381,6 +2381,11 @@ _dbus_connection_block_pending_call (DBusPendingCall *pending)
  * Because this connection is shared, no user of the connection
  * may call dbus_connection_close(). However, when you are done with the
  * connection you should call dbus_connection_unref().
+ *
+ * @note Prefer dbus_connection_open() to dbus_connection_open_private()
+ * unless you have good reason; connections are expensive enough
+ * that it's wasteful to create lots of connections to the same
+ * server.
  * 
  * @param address the address.
  * @param error address where an error can be returned.
@@ -2419,7 +2424,12 @@ dbus_connection_open (const char     *address,
  * (The dbus_connection_close() can be skipped if the
  * connection is already known to be disconnected, for example
  * if you are inside a handler for the Disconnected signal.)
- * 
+ *
+ * @note Prefer dbus_connection_open() to dbus_connection_open_private()
+ * unless you have good reason; connections are expensive enough
+ * that it's wasteful to create lots of connections to the same
+ * server.
+ *
  * @param address the address.
  * @param error address where an error can be returned.
  * @returns new connection, or #NULL on failure.