# HG changeset patch
# User Ewan Mellor <ewan@xxxxxxxxxxxxx>
# Node ID 884c25ba7d2679f1955d2946c179f85a1af1affd
# Parent 5e9812e53300c29690d78914d31ad3a9f42edcbc
State that getters and setters do not have asynchronous versions -- there's no
point, because they ought to be immediate.
Tidy up the examples in the presentation and wire-protocol sections, and bring
them into sync with the main body text.
Signed-off-by: Ewan Mellor <ewan@xxxxxxxxxxxxx>
---
docs/xen-api/presentation.tex | 5 ---
docs/xen-api/todo.tex | 2 +
docs/xen-api/wire-protocol.tex | 66 +++++++++++++----------------------------
3 files changed, 24 insertions(+), 49 deletions(-)
diff -r 5e9812e53300 -r 884c25ba7d26 docs/xen-api/presentation.tex
--- a/docs/xen-api/presentation.tex Wed Nov 29 23:31:07 2006 +0000
+++ b/docs/xen-api/presentation.tex Wed Nov 29 23:34:33 2006 +0000
@@ -131,9 +131,6 @@ of that class that has the specified {\t
``{\tt get\_by\_name\_label(name)}'' RPC that returns a set of objects of that
class that have the specified {\tt label}.
-\item Each class has a ``{\tt to\_XML()}'' RPC that serialises the
-state of all fields as an XML string.
-
\item Each class has a ``{\tt destroy(Ref x)}'' RPC that explicitly deletes
the persistent object specified by {\tt x} from the system. This is a
non-cascading delete -- if the object being removed is referenced by another
@@ -144,6 +141,6 @@ object then the {\tt destroy} call will
\subsection{Additional RPCs}
As well as the RPCs enumerated above, some classes have additional RPCs
-associated with them. For example, the {\tt VM} class have RPCs for cloning,
+associated with them. For example, the {\tt VM} class has RPCs for cloning,
suspending, starting etc. Such additional RPCs are described explicitly
in the API reference.
diff -r 5e9812e53300 -r 884c25ba7d26 docs/xen-api/todo.tex
--- a/docs/xen-api/todo.tex Wed Nov 29 23:31:07 2006 +0000
+++ b/docs/xen-api/todo.tex Wed Nov 29 23:34:33 2006 +0000
@@ -34,6 +34,8 @@ code, potential error description, but o
\item Clarify behaviour of progress field on asyncrhonous request polling when
that request fails.
+
+\item Clarify which calls have asynchronous counterparts by marking them as
such in the reference. (Individual getters and setters are too small and quick
to justify having async versions)
\end{itemize}
diff -r 5e9812e53300 -r 884c25ba7d26 docs/xen-api/wire-protocol.tex
--- a/docs/xen-api/wire-protocol.tex Wed Nov 29 23:31:07 2006 +0000
+++ b/docs/xen-api/wire-protocol.tex Wed Nov 29 23:34:33 2006 +0000
@@ -21,9 +21,9 @@ In our API Reference we specify the sign
In our API Reference we specify the signatures of API functions in the
following
style:
\begin{verbatim}
- (ref_vm Set) Host.ListAllVMs()
-\end{verbatim}
-This specifies that the function with name {\tt Host.ListAllVMs} takes
+ (ref_vm Set) VM.get_all()
+\end{verbatim}
+This specifies that the function with name {\tt VM.get\_all} takes
no parameters and returns a Set of {\tt ref\_vm}s.
These types are mapped onto XML-RPC types in a straight-forward manner:
\begin{itemize}
@@ -105,8 +105,8 @@ the struct contains a second element nam
the struct contains a second element named {\tt ErrorDescription}:
\begin{itemize}
\item The element of the struct named {\tt ErrorDescription} contains
-an array of string values. The first element of the array represents an error
code;
-the remainder of the array represents error parameters relating to that code.
+an array of string values. The first element of the array is an XML-RPC 32-bit
{\tt i4} and represents an error code;
+the remainder of the array are strings representing error parameters relating
to that code.
\end{itemize}
For example, an XML-RPC return value from the {\tt Host.ListAllVMs} function
above
@@ -161,19 +161,19 @@ A session can be terminated with the {\t
\subsection{Synchronous and Asynchronous invocation}
-Each method call (apart from those on ``Session'' and ``Task'' objects)
+Each method call (apart from methods on ``Session'' and ``Task'' objects
+and ``getters'' and ``setters'' derived from fields)
can be made either synchronously or asynchronously.
A synchronous RPC call blocks until the
return value is received; the return value of a synchronous RPC call is
exactly as specified in Section~\ref{synchronous-result}.
-Each of the methods specified in the API Reference is synchronous.
-However, although not listed explicitly in this document, each
-method call has an asynchronous analogue in the {\tt Async}
-namespace. For example, synchronous call {\tt VM.Install(...)}
+Only synchronous API calls are listed explicitly in this document.
+All asynchronous versions are in the special {\tt Async} namespace.
+For example, synchronous call {\tt VM.clone(...)}
(described in Chapter~\ref{api-reference})
has an asynchronous counterpart, {\tt
-Async.VM.Install(...)}, that is non-blocking.
+Async.VM.clone(...)}, that is non-blocking.
Instead of returning its result directly, an asynchronous RPC call
returns a {\tt task-id}; this identifier is subsequently used
@@ -186,39 +186,14 @@ The {\tt task-id} is provided in the {\t
The {\tt task-id} is provided in the {\tt Value} field if {\tt Status} is set
to
{\tt Success}.
-Two special RPC calls are provided to poll the status of
-asynchronous calls:
-\begin{verbatim}
- Array<task_id> Async.Task.GetAllTasks (session_id s)
- task_status Async.Task.GetStatus (session_id s, task_id t)
-\end{verbatim}
-
-{\tt Async.Task.GetAllTasks} returns a set of the currently
-executing asynchronous tasks belong to the current user\footnote{
-%
-The current user is determined by the username that was provided
-to {\tt Session.Login}.
-%
-}.
-
-{\tt Async.Task.GetStatus} returns a {\tt task\_status} result.
-This is an XML-RPC struct with three elements:
-\begin{itemize}
- \item The first element is named {\tt Progress} and contains
-an {\tt Integer} between 0 and 100 representing the estimated percentage of
-the task currently completed.
- \item The second element is named {\tt ETA} and contains a {\tt DateTime}
-representing the estimated time the task will be complete.
- \item The third element is named {\tt Result}. If {\tt Progress}
-is not 100 then {\tt Result} contains the empty string. If {\tt Progress}
-{\em is\/} set to 100, then {\tt Result} contains the function's return
-result (as specified in Section~\ref{synchronous-result})\footnote{
-%
-Recall that this itself is a struct potentially containing status, errorcode,
-value fields etc.
-%
-}.
-\end{itemize}
+The RPC call
+\begin{verbatim}
+ (ref_task Set) Task.get_all(session_id s)
+\end{verbatim}
+returns a set of all task IDs known to the system. The status (including any
+returned result and error codes) of these tasks
+can then be queried by accessing the fields of the Task object in the usual
way.
+Note that, in order to get a consistent snapshot of a task's state, it is
advisable to call the ``get\_record'' function.
\section{Example interactive session}
@@ -267,7 +242,8 @@ Next, the user may acquire a list of all
\begin{verbatim}
>>> all_vms = xen.VM.do_list(session)['Value']
>>> all_vms
-['b7b92d9e-d442-4710-92a5-ab039fd7d89b',
'23e1e837-abbf-4675-b077-d4007989b0cc', '2045dbc0-0734-4eea-9cb2-b8218c6b5bf2',
'3202ae18-a046-4c32-9fda-e32e9631866e']
+['b7b92d9e-d442-4710-92a5-ab039fd7d89b',
'23e1e837-abbf-4675-b077-d4007989b0cc',
+ '2045dbc0-0734-4eea-9cb2-b8218c6b5bf2',
'3202ae18-a046-4c32-9fda-e32e9631866e']
\end{verbatim}
Note the VM references are internally UUIDs. Once a reference to a VM has been
acquired a lifecycle operation may be invoked:
_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog
|
Home