Murphy D-Bus tutorial misleading: request/release

[pohly]

The https://01.org/murphy/documentation/resource-aware-applications howto shows how resources can be locked via the D-Bus API. The section about acquiring and releasing resource sets is so brief that it is misleading and encourages writing broken code:

How to acquire and release a resource set using the D-Bus API (from Python):

> rset_iface.request()
> rset_iface.release()

This makes it look like request() is blocking and the app is allowed to use the resource between request() and release(), which is not the case. The app needs to watch the status of the resource set and wait for it to become "acquired".

This is not called out explicitly anywhere as far as I can see. https://github.com/01org/murphy/blob/master/doc/plugins/resource-dbus/dbus-api-resource.txt does not document the correct use of request() and release() at all. The example tool just calls request() and does not wait for and/or check the result.

Here's a list of questions that the documentation should handle:

• What kind of errors and special cases need to be handled by the app?
• How can the app determine that its request is never going to succeed, for example because it included a non-existent resource (probably needs an API extension)?
• Does the app need to call request() again after the resource set entered "lost" or "available"?
• May the app call request() again when the request is already (and still) active? That may make life easier in some cases, because currently it is not possible to determine that just from the resource set instance, and may not even be possible in a race-free way at all.
• If request() may be called multiple times, does release() have to be called the same amount of times (nested behavior)?

[pohly]

I just posted an example script which waits for resource allocation in issue #5. It's untested, because allocation always succeeds, even in cases where it should fail. Is the logic in that script correct?

[ipuustin]

I agree, the documentation concerning the resource handling needs to be updated or preferably rewritten in a nice format. What we currently have is some API documentation, example resource client code and a brief tutorial. A full document with lots of examples and thorough explanation of the possible parameters to the calls is something we have to do.

[ipuustin]

I updated the documentation a bit, adding information about using the D-Bus API asynchronously.