# WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/

 Home Products Support Community News

# xen-changelog

## [Xen-changelog] [xen-unstable] State that getters and setters do not hav

 To: xen-changelog@xxxxxxxxxxxxxxxxxxx [Xen-changelog] [xen-unstable] State that getters and setters do not have asynchronous versions -- there's no Xen patchbot-unstable Thu, 30 Nov 2006 01:40:14 +0000 Wed, 29 Nov 2006 17:39:46 -0800 www-data@xxxxxxxxxxxxxxxxxx BK change log , , xen-devel@xxxxxxxxxxxxxxxxxxx xen-changelog-bounces@xxxxxxxxxxxxxxxxxxx
 # HG changeset patch # User Ewan Mellor # 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 --- 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 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 
 Current Thread [Xen-changelog] [xen-unstable] State that getters and setters do not have asynchronous versions -- there's no, Xen patchbot-unstable <=