A behaviour for exported objects, run as a GenServer.

Rebus.Service hands each call on an exported object to a handler process as a message, and leaves the process to answer it. use Rebus.Object packages that for the common case: start_link/3 starts a GenServer that exports the object and turns each call into a callback, answering it from the callback's return value.

Example

defmodule Calculator do
  use Rebus.Object

  @calculator Rebus.Interface.new!("org.example.Calculator",
                methods: [{"Add", in: [a: "i", b: "i"], out: [sum: "i"]}],
                properties: [{"Precision", "u", :readwrite}]
              )

  @impl true
  def interfaces, do: [@calculator]

  @impl true
  def init(precision), do: {:ok, %{precision: precision}}

  @impl true
  def handle_method(%{member: "Add"}, [a, b], state), do: {:reply, [a + b], state}

  @impl true
  def handle_get_property(_interface, "Precision", state),
    do: {:ok, state.precision, state}

  @impl true
  def handle_set_property(_interface, "Precision", precision, state) when precision <= 16,
    do: {:ok, %{state | precision: precision}}

  def handle_set_property(_interface, "Precision", _precision, state),
    do: {:error, "org.freedesktop.DBus.Error.InvalidArgs", "Precision above 16", state}
end

{:ok, conn} = Rebus.connect(:session)
{:ok, _pid} = Rebus.Object.start_link(Calculator, 2, conn: conn, path: "/org/example/Calculator")

use Rebus.Object also defines child_spec/1, which takes {arg, opts} as start_link/3 takes them, so the object can be supervised:

children = [{Calculator, {2, conn: conn, path: "/org/example/Calculator"}}]

The child is :transient. An object that crashes is restarted and exports itself again. An object whose connection stops exits with {:shutdown, :disconnected}, which a supervisor treats as a normal exit, so it is not restarted: a restart would try to export on the same stopped connection and fail.

:temporary is the only other sensible value, for an object that should never be restarted, such as one started on demand under a DynamicSupervisor. Avoid :permanent. It restarts an object after its connection stops, every restart fails, and the supervisor gives up after its restart limit and exits, taking its other children with it.

use Rebus.Object takes the keys of Supervisor.child_spec/0, such as :restart or :id, as use GenServer does.

Lifetime

The object exports itself before its init/1 runs, and its export lives as long as the process. When the process exits, the connection fails every call still waiting for its answer with org.freedesktop.DBus.Error.Failed, and when a supervisor restarts it, the new process exports the object again.

Exceptions in callbacks are not rescued. The process crashes, the caller receives Failed, and the exception's detail stays off the wire.

The object stops with {:shutdown, :disconnected} when its connection stops, since its export is gone with the connection.

Methods

Each call to a declared method reaches handle_method/3 with its arguments, which have the declared types. The callback answers it by returning {:reply, body, state} or {:error, name, message, state}. Returning {:noreply, state} leaves the call open, to be answered later by any process holding the Rebus.Service.Call:

@impl true
def handle_method(%{member: "SlowAdd"} = call, [a, b], state) do
  Task.start(fn -> Rebus.Service.reply(call, [a + b]) end)
  {:noreply, state}
end

A reply that cannot be sent while the call is still open, such as a body that does not fit the method's out-signature, is a bug in the object, which stops with {:invalid_reply, reason}. Replying to a call that was already answered or has expired, or a reply whose delivery timed out, is not a bug, and the object carries on.

Properties

Get reaches handle_get_property/3, whose value is typed by the property's declaration. GetAll calls it for every readable property of the interface, in name order, and answers with the values together, or with the first error returned. Set reaches handle_set_property/4 with the new value, already checked against the declared type.

After a successful Set, the object emits org.freedesktop.DBus.Properties.PropertiesChanged as the property's emits_changed asks: with the new value when it is true, with the property's name only when it is :invalidates, and not at all when it is false or :const. A write-only property is never announced, since that would broadcast a value no one may read. A callback that returns {:ok, state, emit: false} suppresses the signal, for example when it stores a value other than the one it was given, and can emit its own with Rebus.Service.properties_changed/6.

The callbacks cannot carry Unix file descriptors, so an object whose properties have a type containing h serves them through Rebus.Service instead.

An object that declares readable properties without defining handle_get_property/3, or writable ones without handle_set_property/4, answers those calls with org.freedesktop.DBus.Error.NotSupported.

Keeping your own loop

A GenServer that exports itself with Rebus.Service.export/4 can still map its calls to these callbacks by passing them to dispatch/4 from its own handle_info/2:

@impl GenServer
def handle_info({_ref, %Rebus.Service.Call{}} = call, state),
  do: Rebus.Object.dispatch(call, __MODULE__, state)

Such a module defines handle_method/3 and the property callbacks it needs as plain functions. It cannot declare @behaviour Rebus.Object beside GenServer, since both behaviours have init/1, handle_info/2 and terminate/2 callbacks.