view docs/xen-api/presentation.tex @ 0:7d21f7218375

Exact replica of unstable on 051908 + README-this
author Mukesh Rathor
date Mon May 19 15:34:57 2008 -0700 (2008-05-19)
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.