ruby-dbus 0.23.0.beta2 → 0.23.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c671b06e04452129a899cd4b7877cf43f9c05b8e7bc6597e75bc460e250c97e7
-  data.tar.gz: 18f660c6e5804fd133cf8351d801f8e0d4e332f1473cc390bedf77341d71845d
+  metadata.gz: 2465a9a90d0b4837640d475566edfde23aee4dc1d7d439d76d1f861b71f13033
+  data.tar.gz: 906288ee9d180ff0bfd4e53f45982040f240da983e23c818acd91d449d9f7f05
 SHA512:
-  metadata.gz: 5cff2ab01f4db3d069a73b28f46cf861dcc81302ed239a7fc4332f46a7583b2394d679d5d73ab13f080b674e46f8961c89fa3fccc58ce9043d0bd33c4c2d02c4
-  data.tar.gz: 495c060e5161c2c5267b723598d3185b14d4c6517e41504f5b49971d3c355acec1ee3ab6285b7796bb7aa8cb61dfb5bd24535a2613a9f22cfb80f65ec8a1cf49
+  metadata.gz: f2939e81cff3f5db2dd768f9e0f1c04159b0285501c73840f14dd8f61ad9f539fbbbf35d7e408cca11847dcd31848131c1c4df69705798860f03e4255f02dedf
+  data.tar.gz: 553f1d4c97a284371d7a10a0f439a40d2861ff8c40c2318c09f6f818f5911644db05142dc7a8d5e377dac355ddc389fcc9858647a568184e8598fd3d3bb71154

data/NEWS.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## Ruby D-Bus 0.23.1 - 2023-10-03
+
+API:
+ * Add DBus::Object.dbus_reader_attr_accessor to declare a common use case
+   with a single call ([#140][]).
+ * BusConnection#request_name defaults to the simple use case: single owner
+   without queuing, failing fast; documented the complex use cases.
+
+[#140]: https://github.com/mvidner/ruby-dbus/pull/140
+
 ## Ruby D-Bus 0.23.0.beta2 - 2023-06-23
 
 License:

data/VERSION

@@ -1 +1 @@
-0.23.0.beta2
+0.23.1

data/examples/utils/listnames.rb

@@ -8,4 +8,12 @@ d = if ARGV.member?("--system")
     else
       DBus::SessionBus.instance
     end
-d.proxy.ListNames[0].each { |n| puts "\t#{n}" }
+d.proxy.ListNames[0].each do |n|
+  puts "\t#{n}"
+  qns = d.proxy.ListQueuedOwners(n)[0]
+  next if qns.size == 1 && qns.first == n
+
+  qns.each do |qn|
+    puts "\t\t#{qn}"
+  end
+end

data/lib/dbus/bus.rb

@@ -55,20 +55,107 @@ module DBus
       @proxy
     end
 
+    # Request a well-known name so that clients can find us.
+    # @note Parameters other than *name* are advanced, you probably don't need them.
+    #
+    # With no boolean flags, running a second instance of a program that calls `request_name`
+    # will result in the second one failing, which this library translates to an exception.
+    # If you want the second instance to take over, you need both
+    # `allow_replacement: true` and `replace_existing: true.`
+    #
     # @param name [BusName] the requested name
-    # @param flags [Integer] TODO: explain and add a better non-numeric API for this
-    # @raise NameRequestError if we could not get the name
-    # @example Usage
+    # @param replace_existing [Boolean]
+    #   Replace an existing owner of the name, if that owner set *allow_replacement*.
+    # @param allow_replacement [Boolean]
+    #   Other connections that specify *replace_existing* will be able to take
+    #   the name from us. We will get {#on_name_lost NameLost}. If we specified *queue*
+    #   we may get the name again, with {#on_name_acquired NameAcquired}.
+    # @param queue [Boolean]
+    #   Affects the behavior when the bus denies the name (sooner or later).
+    #   - If `false` (default), it is recommended to let the `NameRequestError` fall through and end your program.
+    #   - If `true`, you should `rescue` the `NameRequestError` and set up
+    #     {#on_name_acquired NameAcquired} and {#on_name_lost NameLost} handlers.
+    #     Meanwhile, the bus will put us in a queue waiting for *name* (this is the "sooner" case).
+    #     Also, if we had `allow_replacement: true`, another connection can cause us
+    #     to lose the name. We will be moved back to the queue, waiting for when the other owners give up
+    #     (the "later" case).
+    # @param flags [Integer,nil]
+    #    If specified, overrides the boolean parameters.
+    #    Use a bitwise sum `|` of:
+    #    -  NAME_FLAG_ALLOW_REPLACEMENT
+    #    -  NAME_FLAG_REPLACE_EXISTING
+    #    -  NAME_FLAG_DO_NOT_QUEUE
+    #    Note that `0` implies `queue: true`.
+    #
+    # @return [REQUEST_NAME_REPLY_PRIMARY_OWNER,REQUEST_NAME_REPLY_ALREADY_OWNER] on success
+    # @raise [NameRequestError] with #error_code REQUEST_NAME_REPLY_EXISTS or REQUEST_NAME_REPLY_IN_QUEUE, on failure
+    # @raise DBus::Error another way to fail is being prohibited to own the name
+    #   which is the default on the system bus
+    #
+    # @see https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name
+    #
+    # @example Simple usage
     #   bus = DBus.session_bus
     #   bus.object_server.export(DBus::Object.new("/org/example/Test"))
     #   bus.request_name("org.example.Test")
-    # @see https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name
-    def request_name(name, flags: 0)
+    #   # main loop
+    #
+    # @example Second instance taking over
+    #   bus = DBus.session_bus
+    #   bus.object_server.export(DBus::Object.new("/org/example/Test"))
+    #   bus.on_name_lost { exit }
+    #   bus.request_name("org.example.Test", allow_replacement: true, replace_existing: true)
+    #   # main loop
+    #
+    # @example Second instance waiting for its turn
+    #   bus = DBus.session_bus
+    #   bus.object_server.export(DBus::Object.new("/org/example/Test"))
+    #   bus.on_name_acquired { @owner = true }
+    #   begin
+    #     bus.request_name("org.example.Test", queue: true)
+    #   rescue DBus::Connection::NameRequestError => e
+    #     @owner = false
+    #   end
+    #   # main loop
+    def request_name(name,
+                     allow_replacement: false,
+                     replace_existing: false,
+                     queue: false,
+                     flags: nil)
+      if flags.nil?
+        flags = (allow_replacement ? NAME_FLAG_ALLOW_REPLACEMENT : 0) |
+                (replace_existing ? NAME_FLAG_REPLACE_EXISTING : 0) |
+                (queue ? 0 : NAME_FLAG_DO_NOT_QUEUE)
+      end
       name = BusName.new(name)
       r = proxy.RequestName(name, flags).first
       handle_return_of_request_name(r, name)
     end
 
+    # The caller has released his claim on the given name.
+    # Either the caller was the primary owner of the name, and the name is now unused
+    #   or taken by somebody waiting in the queue for the name,
+    # or the caller was waiting in the queue for the name and has now been removed from the queue.
+    RELEASE_NAME_REPLY_RELEASED = 1
+    # The given name does not exist on this bus.
+    RELEASE_NAME_REPLY_NON_EXISTENT = 2
+    # The caller was not the primary owner of this name, and was also not waiting in the queue to own this name.
+    RELEASE_NAME_REPLY_NOT_OWNER = 3
+
+    # @param name [BusName] the name to release
+    def release_name(name)
+      name = BusName.new(name)
+      proxy.ReleaseName(name).first
+    end
+
+    def on_name_acquired(&handler)
+      proxy.on_signal("NameAcquired", &handler)
+    end
+
+    def on_name_lost(&handler)
+      proxy.on_signal("NameLost", &handler)
+    end
+
     # Asks bus to send us messages matching mr, and execute slot when
     # received
     # @param match_rule [MatchRule,#to_s]

data/lib/dbus/connection.rb

@@ -153,17 +153,30 @@ module DBus
 
     # Exception raised when a service name is requested that is not available.
     class NameRequestError < Exception
+      # @return [Integer] one of
+      #   REQUEST_NAME_REPLY_IN_QUEUE
+      #   REQUEST_NAME_REPLY_EXISTS
+      attr_reader :error_code
+
+      def initialize(error_code)
+        @error_code = error_code
+        super()
+      end
     end
 
+    # In case RequestName did not succeed, raise an exception but first ask the bus who owns the name instead of us
+    # @param ret [Integer] what RequestName returned
+    # @param name Name that was requested
+    # @return [REQUEST_NAME_REPLY_PRIMARY_OWNER,REQUEST_NAME_REPLY_ALREADY_OWNER] on success
+    # @raise [NameRequestError] with #error_code REQUEST_NAME_REPLY_EXISTS or REQUEST_NAME_REPLY_IN_QUEUE, on failure
+    # @api private
     def handle_return_of_request_name(ret, name)
-      details = if ret == REQUEST_NAME_REPLY_IN_QUEUE
-                  other = proxy.GetNameOwner(name).first
-                  other_creds = proxy.GetConnectionCredentials(other).first
-                  "already owned by #{other}, #{other_creds.inspect}"
-                else
-                  "error code #{ret}"
-                end
-      raise NameRequestError, "Could not request #{name}, #{details}" unless ret == REQUEST_NAME_REPLY_PRIMARY_OWNER
+      if [REQUEST_NAME_REPLY_EXISTS, REQUEST_NAME_REPLY_IN_QUEUE].include?(ret)
+        other = proxy.GetNameOwner(name).first
+        other_creds = proxy.GetConnectionCredentials(other).first
+        message = "Could not request #{name}, already owned by #{other}, #{other_creds.inspect}"
+        raise NameRequestError.new(ret), message
+      end
 
       ret
     end

data/lib/dbus/object.rb

@@ -156,18 +156,32 @@ module DBus
       dbus_accessor(ruby_name, type, dbus_name: dbus_name, emits_changed_signal: emits_changed_signal)
     end
 
+    # A read-only property accessing a read-write instance variable.
+    # A combination of `attr_accessor` and {.dbus_reader}.
+    #
+    # @param  (see .dbus_attr_accessor)
+    # @return (see .dbus_attr_accessor)
+    def self.dbus_reader_attr_accessor(ruby_name, type, dbus_name: nil, emits_changed_signal: nil)
+      attr_accessor(ruby_name)
+
+      dbus_reader(ruby_name, type, dbus_name: dbus_name, emits_changed_signal: emits_changed_signal)
+    end
+
     # A read-only property accessing an instance variable.
     # A combination of `attr_reader` and {.dbus_reader}.
     #
+    # You may be instead looking for a variant which is read-write from the Ruby side:
+    # {.dbus_reader_attr_accessor}.
+    #
     # Whenever the property value gets changed from "inside" the object,
     # you should emit the `PropertiesChanged` signal by calling
     # {#dbus_properties_changed}.
     #
-    #   dbus_properties_changed(interface_name, {dbus_name.to_s => value}, [])
+    #     dbus_properties_changed(interface_name, {dbus_name.to_s => value}, [])
     #
     # or, omitting the value in the signal,
     #
-    #   dbus_properties_changed(interface_name, {}, [dbus_name.to_s])
+    #     dbus_properties_changed(interface_name, {}, [dbus_name.to_s])
     #
     # @param  (see .dbus_attr_accessor)
     # @return (see .dbus_attr_accessor)
@@ -213,18 +227,22 @@ module DBus
     # implement it with a read-write attr_accessor. In that case this method
     # uses {.dbus_watcher} to set up the PropertiesChanged signal.
     #
-    #   attr_accessor :foo_bar
-    #   dbus_reader :foo_bar, "s"
+    #     attr_accessor :foo_bar
+    #     dbus_reader :foo_bar, "s"
+    #
+    # The above two declarations have a shorthand:
+    #
+    #     dbus_reader_attr_accessor :foo_bar, "s"
     #
     # If the property value should change by other means than its attr_writer,
     # you should emit the `PropertiesChanged` signal by calling
     # {#dbus_properties_changed}.
     #
-    #   dbus_properties_changed(interface_name, {dbus_name.to_s => value}, [])
+    #     dbus_properties_changed(interface_name, {dbus_name.to_s => value}, [])
     #
     # or, omitting the value in the signal,
     #
-    #   dbus_properties_changed(interface_name, {}, [dbus_name.to_s])
+    #     dbus_properties_changed(interface_name, {}, [dbus_name.to_s])
     #
     # @param  (see .dbus_attr_accessor)
     # @return (see .dbus_attr_accessor)

data/spec/bus_connection_spec.rb

@@ -21,7 +21,6 @@ describe DBus::BusConnection do
     end
 
     context "when the name is taken already", tag_service: true do
-      # formerly it returned Service, now ObjectServer takes its role
       it "raises NameRequestError... too late" do
         name = "org.ruby.service"
         expect do
@@ -50,21 +49,35 @@ describe DBus::BusConnection do
 
   describe "#request_name", tag_bus: true do
     context "when the name request succeeds" do
-      it "returns something which can export objects" do
+      it "returns a success code" do
         name = "org.rubygems.ruby_dbus.RequestNameTest"
-        expect { bus.request_name(name) }.to_not raise_error
-        bus.proxy.ReleaseName(name)
+        expect(bus.request_name(name)).to eq DBus::Connection::REQUEST_NAME_REPLY_PRIMARY_OWNER
+        # second time, considered also a success
+        expect(bus.request_name(name)).to eq DBus::Connection::REQUEST_NAME_REPLY_ALREADY_OWNER
+        bus.release_name(name)
       end
     end
 
     context "when the name is taken already", tag_service: true do
-      # formerly it returned Service, now ObjectServer takes its role
       it "raises NameRequestError" do
         name = "org.ruby.service"
         expect do
-          # flags: avoid getting the name sometime later, unexpectedly
-          bus.request_name(name, flags: DBus::Connection::NAME_FLAG_DO_NOT_QUEUE)
+          bus.request_name(name)
+        end.to raise_error(DBus::Connection::NameRequestError)
+      end
+    end
+
+    context "when the name is taken already but we request queuing", tag_service: true do
+      it "raises NameRequestError but we are queued" do
+        name = "org.ruby.service"
+        owning = nil
+        # TODO: we do not expect the handlers to run
+        bus.on_name_acquired { owning = true }
+        bus.on_name_lost { owning = false }
+        expect do
+          bus.request_name(name, queue: true)
         end.to raise_error(DBus::Connection::NameRequestError)
+        expect(bus.release_name(name)).to eq DBus::BusConnection::RELEASE_NAME_REPLY_RELEASED
       end
     end
 

data/spec/mock-service/spaghetti-monster.rb

@@ -23,7 +23,7 @@ class TestChild < DBus::Object
   end
 
   dbus_interface "org.ruby.TestChild" do
-    dbus_attr_reader :name, "s"
+    dbus_reader_attr_accessor :name, "s"
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-dbus
 version: !ruby/object:Gem::Version
-  version: 0.23.0.beta2
+  version: 0.23.1
 platform: ruby
 authors:
 - Ruby DBus Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-06-23 00:00:00.000000000 Z
+date: 2023-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rexml
@@ -235,9 +235,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.3.26
 signing_key: