view docs/xen-api/presentation.tex @ 17965:14fd83fe71c3

Add facility to get notification of domain suspend by event channel.
This event channel will be notified when the domain transitions to the
suspended state, which can be much faster than raising VIRQ_DOM_EXC
and waiting for the notification to be propagated via xenstore.

No attempt is made here to prevent multiple subscribers (last one
wins), or to detect that the subscriber has gone away. Userspace tools
should take care.

Signed-off-by: Brendan Cully <brendan@cs.ubc.ca>
author Keir Fraser <keir.fraser@citrix.com>
date Fri Jul 04 12:00:24 2008 +0100 (2008-07-04)
parents a2903704c17a
line source
1 %
2 % Copyright (c) 2006-2007 XenSource, Inc.
3 %
4 % Permission is granted to copy, distribute and/or modify this document under
5 % the terms of the GNU Free Documentation License, Version 1.2 or any later
6 % version published by the Free Software Foundation; with no Invariant
7 % Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the
8 % license is included in the section entitled
9 % "GNU Free Documentation License" or the file fdl.tex.
10 %
11 % Authors: Ewan Mellor, Richard Sharp, Dave Scott, Jon Harrop.
12 %
14 The API is presented here as a set of Remote Procedure Calls, with a wire
15 format based upon XML-RPC. No specific language bindings are prescribed,
16 although examples will be given in the python programming language.
18 Although we adopt some terminology from object-oriented programming,
19 future client language bindings may or may not be object oriented.
20 The API reference uses the terminology {\em classes\/} and {\em objects\/}.
21 For our purposes a {\em class\/} is simply a hierarchical namespace;
22 an {\em object\/} is an instance of a class with its fields set to
23 specific values. Objects are persistent and exist on the server-side.
24 Clients may obtain opaque references to these server-side objects and then
25 access their fields via get/set RPCs.
27 %In each class there is a $\mathit{uid}$ field that assigns an indentifier
28 %to each object. This $\mathit{uid}$ serves as an object reference
29 %on both client- and server-side, and is often included as an argument in
30 %RPC messages.
32 For each class we specify a list of
33 fields along with their {\em types\/} and {\em qualifiers\/}. A
34 qualifier is one of:
35 \begin{itemize}
36 \item $\mathit{RO}_\mathit{run}$: the field is Read
37 Only. Furthermore, its value is automatically computed at runtime.
38 For example: current CPU load and disk IO throughput.
39 \item $\mathit{RO}_\mathit{ins}$: the field must be manually set
40 when a new object is created, but is then Read Only for
41 the duration of the object's life.
42 For example, the maximum memory addressable by a guest is set
43 before the guest boots.
44 \item $\mathit{RW}$: the field is Read/Write. For example, the name
45 of a VM.
46 \end{itemize}
48 A full list of types is given in Chapter~\ref{api-reference}. However,
49 there are three types that require explicit mention:
50 \begin{itemize}
51 \item $t~\mathit{Ref}$: signifies a reference to an object
52 of type $t$.
53 \item $t~\mathit{Set}$: signifies a set containing
54 values of type $t$.
55 \item $(t_1, t_2)~\mathit{Map}$: signifies a mapping from values of
56 type $t_1$ to values of type $t_2$.
57 \end{itemize}
59 Note that there are a number of cases where {\em Ref}s are {\em doubly
60 linked\/}---e.g.\ a VM has a field called {\tt VIFs} of type
61 $(\mathit{VIF}~\mathit{Ref})~\mathit{Set}$; this field lists
62 the network interfaces attached to a particular VM. Similarly, the VIF
63 class has a field called {\tt VM} of type $(\mathit{VM}~{\mathit
64 Ref})$ which references the VM to which the interface is connected.
65 These two fields are {\em bound together\/}, in the sense that
66 creating a new VIF causes the {\tt VIFs} field of the corresponding
67 VM object to be updated automatically.
69 The API reference explicitly lists the fields that are
70 bound together in this way. It also contains a diagram that shows
71 relationships between classes. In this diagram an edge signifies the
72 existence of a pair of fields that are bound together, using standard
73 crows-foot notation to signify the type of relationship (e.g.\
74 one-many, many-many).
76 \section{RPCs associated with fields}
78 Each field, {\tt f}, has an RPC accessor associated with it
79 that returns {\tt f}'s value:
80 \begin{itemize}
81 \item ``{\tt get\_f(Ref x)}'': takes a
82 {\tt Ref} that refers to an object and returns the value of {\tt f}.
83 \end{itemize}
85 Each field, {\tt f}, with attribute
86 {\em RW} and whose outermost type is {\em Set\/} has the following
87 additional RPCs associated with it:
88 \begin{itemize}
89 \item an ``{\tt add\_to\_f(Ref x, v)}'' RPC adds a new element v to the set\footnote{
90 %
91 Since sets cannot contain duplicate values this operation has no action in the case
92 that {\tt v} was already in the set.
93 %
94 };
95 \item a ``{\tt remove\_from\_f(Ref x, v)}'' RPC removes element {\tt v} from the set;
96 \end{itemize}
98 Each field, {\tt f}, with attribute
99 {\em RW} and whose outermost type is {\em Map\/} has the following
100 additional RPCs associated with it:
101 \begin{itemize}
102 \item an ``{\tt add\_to\_f(Ref x, k, v)}'' RPC adds new pair {\tt (k, v)}
103 to the mapping stored in {\tt f} in object {\tt x}. Adding a new pair for duplicate
104 key, {\tt k}, overwrites any previous mapping for {\tt k}.
105 \item a ``{\tt remove\_from\_f(Ref x, k)}'' RPC removes the pair with key {\tt k}
106 from the mapping stored in {\tt f} in object {\tt x}.
107 \end{itemize}
109 Each field whose outermost type is neither {\em Set\/} nor {\em Map\/},
110 but whose attribute is {\em RW} has an RPC acessor associated with it
111 that sets its value:
112 \begin{itemize}
113 \item For {\em RW\/} ({\em R\/}ead/{\em
114 W\/}rite), a ``{\tt set\_f(Ref x, v)}'' RPC function is also provided.
115 This sets field {\tt f} on object {\tt x} to value {\tt v}.
116 \end{itemize}
118 \section{RPCs associated with classes}
120 \begin{itemize}
121 \item Each class has a {\em constructor\/} RPC named ``{\tt create}'' that
122 takes as parameters all fields marked {\em RW\/} and
123 $\mathit{RO}_\mathit{ins}$. The result of this RPC is that a new {\em
124 persistent\/} object is created on the server-side with the specified field
125 values.
127 \item Each class has a {\tt get\_by\_uuid(uuid)} RPC that returns the object
128 of that class that has the specified {\tt uuid}.
130 \item Each class that has a {\tt name\_label} field has a
131 ``{\tt get\_by\_name\_label(name)}'' RPC that returns a set of objects of that
132 class that have the specified {\tt label}.
134 \item Each class has a ``{\tt destroy(Ref x)}'' RPC that explicitly deletes
135 the persistent object specified by {\tt x} from the system. This is a
136 non-cascading delete -- if the object being removed is referenced by another
137 object then the {\tt destroy} call will fail.
139 \end{itemize}
141 \subsection{Additional RPCs}
143 As well as the RPCs enumerated above, some classes have additional RPCs
144 associated with them. For example, the {\tt VM} class has RPCs for cloning,
145 suspending, starting etc. Such additional RPCs are described explicitly
146 in the API reference.