From 9f8798170dba82b8d46de02ab46105cf61b41f87 Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Mon, 31 Jan 2011 13:19:59 -0500 Subject: [PATCH] GApplication: add notes about GDBus architecture Some people are trying to write code that calls g_application_register() then checks to see if we became the primary name owner before exporting objects. This sort of approach worked with libdbus-1 because method calls to the freshly-acquired name would not be dispatched until the application returned to the mainloop. With GDBus, however, dispatches can occur at any time (including in the brief space between acquiring the name and actually registering the object). Add documentation to make it clear that you should not expect this to work. --- gio/gapplication.c | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/gio/gapplication.c b/gio/gapplication.c index 7c2ff89..49ab61f 100644 --- a/gio/gapplication.c +++ b/gio/gapplication.c @@ -64,6 +64,22 @@ * For details on valid application identifiers, see * g_application_id_is_valid(). * + * The application identifier is claimed by the application as a + * well-known bus name on the user's session bus. This means that the + * uniqueness of your application is scoped to the current session. It + * also means that your application may provide additional services + * (through registration of other object paths) at that bus name. + * + * The registration of these object paths should be done with the shared + * GDBus session bus. Note that due to the internal architecture of + * GDBus, method calls can be dispatched at any time (even if a main + * loop is not running). For this reason, you must ensure that any + * object paths that you wish to register are registered before + * #GApplication attempts to acquire the bus name of your application + * (which happens in g_application_register()). Unfortunately, this + * means that you can not use g_application_get_is_remote() to decide if + * you want to register object paths. + * * GApplication provides convenient life cycle management by maintaining * a use count for the primary application instance. * The use count can be changed using g_application_hold() and @@ -904,7 +920,14 @@ g_application_get_is_remote (GApplication *application) * * This is the point at which the application discovers if it is the * primary instance or merely acting as a remote for an already-existing - * primary instance. + * primary instance. This is implemented by attempting to acquire the + * application identifier as a uniue bus name on the session bus using + * GDBus. + * + * Due to the internal architecture of GDBus, method calls can be + * dispatched at any time (even if a main loop is not running). For + * this reason, you must ensure that any object paths that you wish to + * register are registered before calling this function. * * If the application has already been registered then %TRUE is * returned with no work performed. -- 2.7.4