Permalink
Browse files

Tidy up the interface names, add documentation

Signed-off-by: David Scott <dave.scott@eu.citrix.com>
  • Loading branch information...
1 parent 6b3de58 commit 539667016b3a5194dc00af7d23702d1b07364f13 David Scott committed Feb 12, 2014
View
@@ -4,9 +4,9 @@ set -x
#obus-gen-interface ../vm.xml
#obus-gen-server ../vm.xml
-obus-gen-interface -o vm ../vm.xml
-obus-gen-interface -o resource ../resource.xml
-obus-gen-interface -o controller ../controller.xml
+obus-gen-interface -o vm ../org.xenserver.Vm.xml
+obus-gen-interface -o resource ../org.xenserver.Resource.xml
+obus-gen-interface -o controller ../org.xenserver.Controller.xml
PACKS=obus,lwt.syntax
@@ -1,5 +1,8 @@
-<node>
- <interface name="org.xenserver.api.controller">
+<!DOCTYPE node PUBLIC
+"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
+ <interface name="org.xenserver.Controller">
<method name="start_multiple">
<arg name="how_many" type="i" direction="in"/>
<arg name="time" type="s" direction="out"/>
@@ -0,0 +1,72 @@
+<!DOCTYPE node PUBLIC
+"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
+ <interface name="org.xenserver.Resource">
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ A storage or network resource which must be attached to the
+ local host. The resources and their local manifestations
+ are identified by URIs. The local URIs must be in a form
+ suitable for the low-level tools e.g. file:///dev/block or
+ nbd://foo/bar.
+ </doc:para>
+ <doc:para>
+ Both attach and detach methods return Task objects representing
+ the local activity. Callers must implement the TaskOwner
+ interface and pass their URI as method arguments.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ <method name="attach">
+ <arg name="global_uri" type="s" direction="in">
+ <doc:doc><doc:summary>The global URI identifying the resource.</doc:summary></doc:doc>
+ </arg>
+ <arg name="owner_uri" type="s" direction="in">
+ <doc:doc><doc:summary>The URI naming the local TaskOwner which is requesting this operation.</doc:summary></doc:doc>
+ </arg>
+ <arg name="operation_id" type="s" direction="in">
+ <doc:doc><doc:summary>An opaque operation identifier which will be logged. This should allow the logs to be partitioned per logical operation.</doc:summary></doc:doc>
+ </arg>
+ <arg name="task" type="o" direction="out">
+ <doc:doc><doc:summary>A Task representing the local activity of attaching the resource (e.g. logging into a server, zoning in a LUN etc)</doc:summary></doc:doc>
+ </arg>
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ Attach makes a global resource ready for local use.
+ The result of the Task object is the local URI which can
+ be given to the low-level tools (blkback via udev, qemu
+ qdisk etc) and an id which can be used to request a detach.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ </method>
+ <method name="detach">
+ <arg name="id" type="s" direction="in">
+ <doc:doc><doc:summary>The id of a previously attached resource.</doc:summary></doc:doc>
+ </arg>
+ <arg name="owner_uri" type="s" direction="in">
+ <doc:doc><doc:summary>The URI naming the local TaskOwner which is requ esting this operation.</doc:summary></doc:doc>
+ </arg>
+ <arg name="operation_id" type="s" direction="in">
+ <doc:doc><doc:summary>An opaque operation identifier which will be log ged. This should allow the logs to be partitioned per logical operation.</doc:summary></doc:doc>
+ </arg>
+ <arg name="task" type="o" direction="out">
+ <doc:doc><doc:summary>A Task representing the local activity of detaching the resource (e.g. unmounting the filesystem etc)</doc:summary></doc:doc>
+ </arg>
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ Detach takes a previously-attached resource and removes it from
+ this host so that it may be safely used by another. It should
+ always be possible to stop using a resource, so detach should
+ never fail. Any failure will be logged and considered a bug
+ in the implementation.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ </method>
+ </interface>
+</node>
@@ -0,0 +1,119 @@
+<!DOCTYPE node PUBLIC
+"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
+ <interface name="org.xenserver.Task">
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ Tasks represent a resource-consuming activity which
+ is running in the background. If the cancel method is
+ called then the activity will be stopped and the system
+ left in a consistent state. It is the client's responsibility
+ to call the destroy method when it ceases to care about
+ the result of the task. The destroy method can be called
+ at any time; the task will remain until the activity has
+ finished and then the task will be deleted.
+ </doc:para>
+ <doc:para>
+ <doc:example language="shell" title="simple example">
+ <doc:code>
+$ dbus-send --print-reply --session --dest=org.xenserver.foo \
+ /org/xenserver/task/2 \
+ org.freedesktop.DBus.Properties.GetAll \
+ string:"org.xenserver.Task"
+method return sender=:1.28 -> dest=:1.40 reply_serial=2
+ array [
+ dict entry(
+ string "cancelling"
+ variant boolean false
+ )
+ dict entry(
+ string "owner"
+ variant string ""
+ )
+ dict entry(
+ string "completed"
+ variant boolean true
+ )
+ ]
+ </doc:code>
+ </doc:example>
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ <method name="cancel">
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ Request an activity be cancelled asynchronously. The activity
+ should stop as soon as possible and the system should be left in
+ a consistent state: either with side-effects committed or all
+ side-effects rolled-back. A task which does not stop quickly
+ is considered buggy.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ </method>
+ <method name="getResult">
+ <arg name="result" type="s" direction="out">
+ <doc:doc><doc:summary>The output of a completed, successful task</doc:summary></doc:doc>
+ </arg>
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ Request the output of a completed, successful task. If the
+ task is still running this will throw XXX. If the task failed
+ then this will throw YYY.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ </method>
+ <method name="destroy">
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ Destroy should be called when the client ceases to be interested
+ in the success or failure of the Task. The task object will
+ remain until the associated activity has completed to permit
+ progress to be queried and to permit the task to be cancelled.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ </method>
+ <property name="completed" type="b" access="read">
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ True if the task has completed and the result or error is available.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ </property>
+ <property name="cancelling" type="b" access="read">
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ True if an attempt to cancel the task is in progress.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ </property>
+ <property name="owner" type="s" access="read">
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ A URI which names a taskOwner instance. The taskOwner will be asked periodically whether it still believes it owns the task. This catches the case where a task owner crashes and forgets; a well-behaved taskOwner will always call destroy when it has no further use for the task results.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ </property>
+ <signal name="Completed">
+ <doc:doc>
+ <doc:description>
+ <doc:para>Emitted when the task has completed and success/failure information is available.</doc:para>
+ </doc:description>
+ </doc:doc>
+ </signal>
+ </interface>
+</node>
@@ -0,0 +1,48 @@
+<!DOCTYPE node PUBLIC
+"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
+ <interface name="org.xenserver.TaskOwner">
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ A client who wishes to invoke asynchronous operations must
+ implement the TaskOwner interface. Services which expose
+ Task objects will automatically destroy them if the TaskOwner
+ does not claim ownership of them.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ <method name="ping">
+ <arg name="tasks" type="as" direction="in">
+ <doc:doc><doc:summary>An array of Task URIs</doc:summary></doc:doc>
+ </arg>
+ <arg name="alive" type="ab" direction="out">
+ <doc:doc><doc:summary>An array of booleans, one per Task URI. True means the Task is still wanted, False means the Task is safe to delete.</doc:summary></doc:doc>
+ </arg>
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ A heartbeat for Task objects. A service hosting Task objects
+ will periodically query the TaskOwner to determine whether the
+ Tasks have leaked (e.g. through a service crash and restart).
+ If a Task has leaked, it will be logged as a bug, and the
+ leaked Tasks automatically destroyed. A well-functioning client
+ will always call Task.destroy explicitly when it has no further
+ use for the Task.result information.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ </method>
+ <property name="tasks" type="as" access="read">
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ A list of task URIs which this owner believes it is is
+ currently responsible for.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ </property>
+</interface>
+</node>
@@ -1,5 +1,5 @@
<node>
- <interface name="org.xenserver.api.vm">
+ <interface name="org.xenserver.Vm">
<method name="start">
<arg name="config" type="s" direction="in"/>
</method>
@@ -67,9 +67,9 @@ def error(message):
command = args[0]
argument = args[1]
-TASK_INTERFACE="org.xenserver.api.task"
-TASKOWNER_INTERFACE="org.xenserver.api.taskOwner"
-RESOURCE_INTERFACE="org.xenserver.api.resource"
+TASK_INTERFACE="org.xenserver.Task"
+TASKOWNER_INTERFACE="org.xenserver.TaskOwner"
+RESOURCE_INTERFACE="org.xenserver.Resource"
class TaskOwner(dbus.service.Object):
def __init__(self):
@@ -69,8 +69,8 @@ def error(message):
next_task_id = 0
-TASK_INTERFACE="org.xenserver.api.task"
-TASKOWNER_INTERFACE="org.xenserver.api.taskOwner"
+TASK_INTERFACE="org.xenserver.Task"
+TASKOWNER_INTERFACE="org.xenserver.TaskOwner"
class Canceller(threading.Thread):
"""A thread which attempts to cleanly shutdown a process, resorting
@@ -233,14 +233,14 @@ def getResult(self):
if not self.completed:
error("%s: TaskNotFinished" % self.path)
raise dbus.exceptions.DBusException(
- 'org.xenserver.api.TaskNotFinished',
+ 'org.xenserver.TaskNotFinished',
'The task is still running.')
if self.returncode == 0:
return self.result
else:
error("%s: TaskAborted" % self.path)
raise dbus.exceptions.DBusException(
- 'org.xenserver.api.TaskAborted',
+ 'org.xenserver.TaskAborted',
'The task failed and has been rolled-back.')
@dbus.service.method(dbus_interface=dbus.PROPERTIES_IFACE, in_signature='ss', out_signature='v')
@@ -259,7 +259,7 @@ def GetAll(self, interface_name):
'The Task object does not implement the %s interface'
% interface_name)
-RESOURCE_INTERFACE="org.xenserver.api.resource"
+RESOURCE_INTERFACE="org.xenserver.Resource"
class Resource(dbus.service.Object):
def __init__(self):
View
@@ -1,16 +0,0 @@
-<node>
- <interface name="org.xenserver.api.resource">
- <method name="attach">
- <arg name="global_uri" type="s" direction="in"/>
- <arg name="owner_uri" type="s" direction="in"/>
- <arg name="operation_id" type="s" direction="in"/>
- <arg name="task" type="o" direction="out"/>
- </method>
- <method name="detach">
- <arg name="id" type="s" direction="in"/>
- <arg name="owner_uri" type="s" direction="in"/>
- <arg name="operation_id" type="s" direction="in"/>
- <arg name="task" type="o" direction="out"/>
- </method>
- </interface>
-</node>
View
@@ -1,48 +0,0 @@
-<!DOCTYPE node PUBLIC
-"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
-"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
-<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
- <interface name="org.xenserver.api.task">
- <method name="cancel">
- </method>
- <method name="getResult">
- <arg name="result" type="s" direction="out"/>
- </method>
- <method name="destroy">
- </method>
- <property name="completed" type="b" access="read">
- <doc:doc>
- <doc:description>
- <doc:para>
- True if the task has completed and the result or error is available.
- </doc:para>
- </doc:description>
- </doc:doc>
- </property>
- <property name="cancelling" type="b" access="read">
- <doc:doc>
- <doc:description>
- <doc:para>
- True if an attempt to cancel the task is in progress.
- </doc:para>
- </doc:description>
- </doc:doc>
- </property>
- <property name="owner" type="s" access="read">
- <doc:doc>
- <doc:description>
- <doc:para>
- A URI which names a taskOwner instance. The taskOwner will be asked periodically whether it still believes it owns the task. This catches the case where a task owner crashes and forgets; a well-behaved taskOwner will always call destroy when it has no further use for the task results.
- </doc:para>
- </doc:description>
- </doc:doc>
- </property>
- <signal name="Completed">
- <doc:doc>
- <doc:description>
- <doc:para>Emitted when the task has completed and success/failure information is available.</doc:para>
- </doc:description>
- </doc:doc>
- </signal>
- </interface>
-</node>
Oops, something went wrong.

0 comments on commit 5396670

Please sign in to comment.