From 1a163e765c0d6a86d2aa2ffb18a1d7e29a052e7a Mon Sep 17 00:00:00 2001 From: "John (J5) Palmieri" Date: Tue, 22 Nov 2005 20:37:00 +0000 Subject: * configure.in: Add test/name-test/Makefile to the generated Makefile list * dbus/dbus-shared.h (#define DBUS_NAME_FLAG_ALLOW_REPLACEMENT): New flag which replaces DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT (#define DBUS_NAME_FLAG_DO_NOT_QUEUE): New flag for specifying not to queue an ower if it can't be the primary owner * bus/bus.h: Add new internal BusOwner struct * bus/driver.c (bus_driver_handle_hello): Send flags (0 for default) to bus_registry_ensure and don't set the prohibit_replacement flag since they are now set per BusOwner and not per name. (bus_driver_handle_list_queued_owners): bus method (ListQueuedOwners) that returns the list of connections in a name's connection queue * bus/services.c (struct BusService): remove prohibit_replacement field (struct BusOwner): new struct for keeping track of queued connections and their associated flags for the queue (struct BusRegistry): add a BusOwner memory pool (bus_registry_new): initialize the BusOwner memory pool (bus_registry_unref): free the BusOwner memory pool (_bus_service_find_owner_link): new internal method for searching the queue for a specific connection (bus_owner_set_flags): new method for adding setting the flags on a bus owner (bus_owner_new): new method that creates a BusOwner object from the pool and sets its flags (bus_owner_ref, bus_owner_unref): ref counting for BusOwner objects (bus_registry_ensure): Add the flags parameter (bus_registry_acquire_service): Switch from using raw connections to using the BusOwner struct Add new state machine for dealing with the new set of flags (bus_registry_set_service_context_table, struct OwnershipCancelData, cancel_ownership, free_ownership_cancel_data, add_cancel_ownership_to_transaction, struct OwnershipRestoreData, restore_ownership, free_ownership_restore_data, add_restore_ownership_to_transaction): Switch to using BusOwner instead of raw connections (bus_service_add_owner): Add flags parameter Switch to using BusOwner instead of raw connections Add state machine for dealing with the new set of flags (bus_service_swap_owner): Swaps the first and second owners in the queue. Used to make sure proper signals are sent when a service looses or gains primary ownership. We never insert an owner at the top of the queue. Instead we insert it in the second position and then swap. (bus_service_remove_owner): Remove the owner from the queue sending out the NameLost and NameOwnerChanged signals if the we were the primary owner (bus_service_get_primary_owners_connection): New method that extracts the connection from the primary owner (bus_service_get_primary_owner): Returns the BusOwner instead of the connection (bus_service_get_allow_replacement): Changed from the old bus_service_get_prohibit_replacement method. Checks the flags of the primary owner and returns if it can be replaced or not (bus_service_set_prohibit_replacement): removed (bus_service_has_owner): returns TRUE if and owner with the specified connection exists in the queue * dbus/dbus-bus.c (dbus_bus_connection_get_unique_name): New helper method that only compiles if tests are enabled. Allows us to get the unique name of a connection so we can check it against the queue when doing regression tests * bus/activation.c (bus_activation_send_pending_auto_activate), bus/dispatch.c (bus_dispatch), bus/driver.c (bus_driver_handle_get_service_owner, bus_driver_handle_get_connection_unix_user, bus_driver_handle_get_connection_unix_process_id, bus_driver_handle_get_connection_selinux_security_context), bus/signals.c (connection_is_primary_owner): use bus_service_get_primary_owners_connection instead of bus_service_get_primary_owner * dbus/dbus-sysdeps.c (_dbus_connect_unix_socket, _dbus_listen_unix_socket): Calculate the length of the socket path and use that instead of using a fixed length which was causing socket names to contain many trailing Nul bytes. * dbus/dbus-glib-lowlevel.h, glib/dbus-gobject.c (dbus_g_method_get_sender): New method for extracting the sender from a DBusGMethodInvocation (dbus_g_method_return_get_reply): changed name to dbus_g_method_get_reply (dbus_g_method_return_send_reply): changed name to dbus_g_method_send reply * doc/dbus-specification.xml: New docs that describe how the new queueing system works and talks about the changes to the how we specify socket names * glib/examples/example-service.c, glib/examples/example-signal-emitter.c, glib/examples/statemachine/statemachine-server.c: Changed the RequestName flags to the new system * test/name-test/ (test-names.c, run-test.sh, Makefile.am): New regression test suite for testing various states of the new queueing system --- doc/TODO | 5 -- doc/dbus-specification.xml | 162 ++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 147 insertions(+), 20 deletions(-) (limited to 'doc') diff --git a/doc/TODO b/doc/TODO index 31ef3a10..82538dca 100644 --- a/doc/TODO +++ b/doc/TODO @@ -28,11 +28,6 @@ Important for 1.0 Kind of a major API change, but seems high-value. - - figure out what the deal is with trailing nul bytes in - abstract socket names - http://lists.freedesktop.org/archives/dbus/2005-August/003179.html - - Important for 1.0 GLib Bindings === diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index d1184650..da9a813f 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -2229,13 +2229,37 @@ the next one specified, and so forth. For example unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2 + + + + + Transports [FIXME we need to specify in detail each transport and its possible arguments] + Current transports include: unix domain sockets (including abstract namespace on linux), TCP/IP, and a debug/testing transport using in-process pipes. Future possible transports include one that tunnels over X11 protocol. + + + Unix Domain Sockets + + Unix domain sockets can be either paths in the file system or on Linux + kernels, they can be abstract which are similar to paths but i + do not show up in the file system. + + + + When a socket is opened by the D-Bus library it truncates the path + name right befor the first trailing Nul byte. This is true for both + normal paths and abstract paths. Note that this is a departure from + previous versions of D-Bus that would create sockets with a fixed + length path name. Names which were shorter than the fixed length + would be padded by Nul bytes. + + @@ -2625,8 +2649,79 @@ This method call should be sent to org.freedesktop.DBus and asks the message bus to - assign the given name to the method caller. The flags argument - contains any of the following values logically ORed together: + assign the given name to the method caller. Each name maintains a + queue of possible owners, where the head of the queue is the primary + or current owner of the name. Each potential owner in the queue + maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and + DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName + call. When RequestName is invoked the following occurs: + + + + If the method caller is currently the primary owner of the name, + the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE + values are updated with the values from the new RequestName call, + and nothing further happens. + + + + + + If the current primary owner (head of the queue) has + DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName + invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then + the caller of RequestName replaces the current primary owner at + the head of the queue and the current primary owner moves to the + second position in the queue. If the caller of RequestName was + in the queue previously its flags are updated with the values from + the new RequestName in addition to moving it to the head of the queue. + + + + + + If replacement is not possible, and the method caller is + currently in the queue but not the primary owner, its flags are + updated with the values from the new RequestName call. + + + + + + If replacement is not possible, and the method caller is + currently not in the queue, the method caller is appended to the + queue. + + + + + + If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE + set and is not the primary owner, it is removed from the + queue. This can apply to the previous primary owner (if it + was replaced) or the method caller (if it updated the + DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the + queue, or if it was just added to the queue with that flag set). + + + + + + Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the + queue," even if another application already in the queue had specified + DBUS_NAME_FLAG_REPLACE_EXISTING. This comes up if a primary owner + that does not allow replacement goes away, and the next primary owner + does allow replacement. In this case, queued items that specified + DBUS_NAME_FLAG_REPLACE_EXISTING do not + automatically replace the new primary owner. In other words, + DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the + time RequestName is called. This is deliberate to avoid an infinite loop + anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT + and DBUS_NAME_FLAG_REPLACE_EXISTING. + + + The flags argument contains any of the following values logically ORed + together: @@ -2639,23 +2734,51 @@ - DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT + DBUS_NAME_FLAG_ALLOW_REPLACEMENT 0x1 - If the application succeeds in becoming the owner of the specified name, - then ownership of the name can't be transferred until the application - disconnects. If this flag is not set, then any application trying to become - the owner of the name will succeed and the previous owner will be - sent a org.freedesktop.DBus.NameLost signal. + + If an application A specifies this flag and succeeds in + becoming the owner of the name, and another application B + later calls RequestName with the + DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A + will lose ownership and receive a + org.freedesktop.DBus.NameLost signal, and + application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT + is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING + is not specified by application B, then application B will not replace + application A as the owner. + DBUS_NAME_FLAG_REPLACE_EXISTING 0x2 + Try to replace the current owner if there is one. If this flag is not set the application will only become the owner of - the name if there is no current owner. + the name if there is no current owner. If this flag is set, + the application will replace the current owner if + the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT. + + + + + DBUS_NAME_FLAG_DO_NOT_QUEUE + 0x4 + + + Without this flag, if an application requests a name that is + already owned, the application will be placed in a queue to + own the name when the current owner gives it up. If this + flag is given, the application will not be placed in the + queue, the request for the name will simply fail. This flag + also affects behavior when an application is replaced as + name owner; by default the application moves back into the + waiting queue, unless this flag was provided when the application + became the name owner. + @@ -2679,18 +2802,27 @@ 1 The caller is now the primary owner of the name, replacing any previous owner. Either the name had no owner before, or the caller specified - DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner did not - specify DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT. + DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified + DBUS_NAME_FLAG_ALLOW_REPLACEMENT. DBUS_REQUEST_NAME_REPLY_IN_QUEUE 2 - The name already had an owner, DBUS_NAME_FLAG_REPLACE_EXISTING was not specified, and the current owner specified DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT. + + The name already had an owner, + DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either + the current owner did not specify + DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting + application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING. + - DBUS_REQUEST_NAME_REPLY_EXISTS - 3 - The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified. + DBUS_REQUEST_NAME_REPLY_EXISTS 3 + The name already has an owner, + DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either + DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the + current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not + specified by the requesting application. DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER -- cgit