Gitiles
Code Review Sign In
gerrit.openbmc.org / openbmc / sdbusplus / 6c97486fd88991f6f40335a9fdfac03d05386138
commit6c97486fd88991f6f40335a9fdfac03d05386138[log] [tgz]
authorEd Tanous <edtanous@google.com>Wed Aug 31 13:21:32 2022 -0700
committerEd Tanous <edtanous@google.com>Thu Sep 01 08:03:20 2022 -0700
treebc75a0388c58afd1e2c630a348ff54d16003a07f
parent164b98bda29029d8260c5370f43c1a9cb08c473a [diff]
Make asio connection use composed operations

Composed operations [1] are the way that asio is attempting to support
multiple executor, coroutine, and async concepts in parallel.  This
commit is the first in hopefully a line of commits where we move to a
pattern that is more generally reusable, and reliant on fewer strict
types.

This is coming up because asio has removed support for
completion_token_type on the async_result object when used with
yield_context.  A discussion with the maintainers on slack makes it seem
like this was unintentional, but regardless, we can improve this code.

The primary upshot of this is that async_send is now moved to use
async_initiate, which abstracts away all the result and completion types
from the code.  This requires moving some of the details namespaces
structures to allow for construction without requiring the callback type
paramter.  In the same move, it moves what was previously a duplicated
callback into its own class, called do_unpack, which separates the two
concepts, and makes it more clear which is responsible for what.

In doing this move, the templates are now moved to be called
"CompletionToken", to be more in line with other asio async operations.
There are a number of cases where these template parameters already
weren't callbacks, so changing the naming to be inline with asio seems
appropriate.

This allows sdbusplus to support boost 1.80.0.

[1] https://www.boost.org/doc/libs/1_80_0/libs/beast/doc/html/beast/using_io/writing_composed_operations.html

Signed-off-by: Ed Tanous <edtanous@google.com>
Change-Id: I9d25040abbffbedb39f55eb93c0d7270091cdd63
2 files changed
tree: bc75a0388c58afd1e2c630a348ff54d16003a07f
  1. docs/
  2. example/
  3. include/
  4. src/
  5. subprojects/
  6. test/
  7. tools/
  8. .clang-format
  9. .clang-ignore
  10. .editorconfig
  11. .flake8
  12. .gitignore
  13. .isort.cfg
  14. .markdownlint.yaml
  15. .prettierrc.yaml
  16. .shellcheck
  17. .shellcheckrc
  18. LICENSE
  19. meson.build
  20. meson_options.txt
  21. OWNERS
  22. pyproject.toml
  23. README.md
  24. setup.cfg
README.md

sdbusplus

sdbusplus contains two parts:

  1. A C++ library (libsdbusplus) for interacting with D-Bus, built on top of the sd-bus library from systemd.
  2. A tool (sdbus++) to generate C++ bindings to simplify the development of D-Bus-based applications.

Dependencies

The sdbusplus library requires sd-bus, which is contained in libsystemd.

The sdbus++ application requires Python 3 and the Python libraries mako and inflection.

Building

The sdbusplus library is built using meson.

meson build
cd build
ninja
ninja test
ninja install

Optionally, building the tests and examples can be disabled by passing -Dtests=disabled and -Dexamples=disabled respectively to `meson.

The sdbus++ application is installed as a standard Python package using setuptools.

cd tools
./setup.py install

C++ library

The sdbusplus library builds on top of the sd-bus library to create a modern C++ API for D-Bus. The library attempts to be as lightweight as possible, usually compiling to exactly the sd-bus API calls that would have been necessary, while also providing compile-time type-safety and memory leak protection afforded by modern C++ practices.

Consider the following code:

auto b = bus::new_default_system();
auto m = b.new_method_call("org.freedesktop.login1",
                           "/org/freedesktop/login1",
                           "org.freedesktop.login1.Manager",
                           "ListUsers");
auto reply = b.call(m);

std::vector<std::tuple<uint32_t, std::string, message::object_path>> users;
reply.read(users);

In a few, relatively succinct, C++ lines this snippet will create a D-Bus connection to the system bus, and call the systemd login manager to get a list of active users. The message and bus objects are automatically freed when they leave scope and the message format strings are generated at compile time based on the types being read. Compare this to the corresponding server code within logind.

In general, the library attempts to mimic the naming conventions of the sd-bus library: ex. sd_bus_call becomes sdbusplus::bus::call, sd_bus_get_unique_name becomes sdbusplus::bus::get_unique_name, sd_bus_message_get_signature becomes sdbusplus::message::get_signature, etc. This allows a relatively straight-forward translation back to the sd-bus functions for looking up the manpage details.

Binding generation tool

sdbusplus also contains a bindings generator tool: sdbus++. The purpose of a bindings generator is to reduce the boilerplate associated with creating D-Bus server or client applications. When creating a server application, rather than creating sd-bus vtables and writing C-style functions to handle each vtable callback, you can create a small YAML file to define your D-Bus interface and the sdbus++ tool will create a C++ class that implements your D-Bus interface. This class has a set of virtual functions for each method and property, which you can overload to create your own customized behavior for the interface.

There are currently two types of YAML files: interface and error. Interfaces are used to create server and client D-Bus interfaces. Errors are used to define C++ exceptions which can be thrown and will automatically turn into D-Bus error responses.

[[D-Bus client bindings are not yet implemented. See openbmc/openbmc#851.]]

Generating bindings

How to use tools/sdbus++

The path of your file will be the interface name. For example, for an interface org.freedesktop.Example, you would create the files org/freedesktop/Example.interface.yaml and org/freedesktop/Example.errors.yaml] for interfaces and errors respectively. These can then be used to generate the server and error bindings:

sdbus++ interface server-header org.freedesktop.Example > \
    org/freedesktop/Example/server.hpp
sdbus++ interface server-cpp org.freedesktop.Example > \
    org/freedesktop/Example/server.cpp
sdbus++ error exception-header org.freedesktop.Example > \
    org/freedesktop/Example/error.hpp \
sdbus++ error exception-cpp org.freedesktop.Example > \
    org/freedesktop/Example/error.cpp

Markdown-based documentation can also be generated from the interface and exception files:

sdbus++ interface markdown org.freedesktop.Example > \
    org/freedesktop/Example.md
sdbus++ error markdown org.freedesktop.Example >> \
    org/freedesktop/Example.md

See the example/meson.build for more details.

Installing sdbusplus on custom distributions

Installation of sdbusplus bindings on a custom distribution requires a few packages to be installed prior. Although these packages are the same for several distributions the names of these packages do differ. Below are the packages needed for Ubuntu and Fedora.

Installation on Ubuntu

sudo apt install git meson libtool pkg-config g++ libsystemd-dev \
    python3 python3-pip python3-yaml python3-mako python3-inflection

Installation on Fedora

sudo dnf install git meson libtool gcc-c++ pkgconfig systemd-devel \
    python3 python3-pip python3-yaml python3-mako

Install the inflection package using the pip utility (on Fedora)

pip3 install inflection