[Xen-changelog] [xen-unstable] State that getters and setters do not have asynchronous versions -- there's no

[Xen patchbot-unstable <patchbot-unstable@xxxxxxxxxxxxxxxxxxx>]

# 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