2 * Copyright (C) 2010 Red Hat Inc.
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License along
15 * with this program; if not, write to the Free Software Foundation, Inc.,
16 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19 (** The public interface to the slave thread.
20 Please see HACKING file. *)
22 (** {2 Commands and callbacks}
24 Commands for libvirt and libguestfs are executed in a separate slave
25 thread. This file describes the interface with that thread that the
26 rest of the program sees.
28 Commands are intentionally as high level as possible. Often a
29 single command may perform many libvirt and libguestfs operations
30 before returing a result. This is to make use of the slave thread
31 as simple as possible.
33 Commands are executed in a "continuation-passing style" (CPS),
34 which means that you call a function to issue the command, passing
35 in a callback ("continuation"). The function returns immediately.
36 The callback may be called some time later once the issued command
37 completes successfully. Several commands can be queued up for
38 execution. Commands are executed and callbacks are performed in
41 The callback returns the result of the command. The callback does
42 not get invoked if there was an error, or if the command was
43 cancelled before it runs (see {!discard_command_queue}). For some
44 commands the callback can be called multiple times (see
48 type 'a callback = 'a -> unit
49 (** A callback function in the main thread which is called when the
50 command finishes successfully.
52 This can also return some data (the ['a] parameter). A command
53 that returns a list of strings might have callback type [string
54 list callback], and a command that returns nothing would have
55 callback type [unit callback].
57 Note that errors are not returned this way. Each function can
58 optionally supply an extra callback to handle errors, or if
59 not supplied then it defaults to the failure hook set by
60 {!set_failure_hook}. *)
62 val no_callback : 'a callback
63 (** The main thread uses this as a callback if it doesn't care about
64 the return value from a command. *)
69 dom_state : Libvirt.Domain.state;
71 (** List of domains as returned in the {!connect} callback. *)
73 val connect : ?fail:exn callback -> string option -> domain list callback -> unit
74 (** [connect uri cb] causes the slave thread to disconnect from
75 libvirt and connect to the libvirt [uri]. If this succeeds,
76 then the list of all domains fetched from libvirt and [cb] is
77 called in the main thread.
79 Although you can connect to remote hosts, libguestfs won't
80 usually be able to see the drives on those hosts, so it normally
81 doesn't make sense to use remote URIs.
83 If [fail] is passed, then failures cause this callback to
84 be called. If not, the global failure hook is called. *)
86 type inspection_data = {
87 insp_all_filesystems : (string * string) list;
88 (** see {!Guestfs.list_filesystems} *)
89 insp_oses : inspection_os list;
90 (** one entry per root (operating system), see {!Guestfs.inspect_os} *)
92 (** The inspection data returned in the callback from
93 {!open_domain} and {!open_images}. *)
95 insp_root : string; (** see {!Guestfs.inspect_os} *)
98 insp_filesystems : string array;
99 insp_hostname : string;
100 insp_major_version : int;
101 insp_minor_version : int;
102 insp_mountpoints : (string * string) list;
103 insp_package_format : string;
104 insp_package_management : string;
105 insp_product_name : string;
107 insp_windows_systemroot : string option;
110 val open_domain : ?fail:exn callback -> string -> inspection_data callback -> unit
111 (** [open_domain name cb] retrieves the list of block devices for
112 the libvirt domain [name], creates a libguestfs handle, adds
113 those block devices, launches the handle, and performs
116 If this is successful, then [cb] is called in the main thread
117 with the list of filesystems and the results of inspection.
119 The slave thread must be connected to libvirt (see {!connect})
120 else this command will fail.
122 If [fail] is passed, then failures cause this callback to
123 be called. If not, the global failure hook is called. *)
125 val open_images : ?fail:exn callback -> string list -> inspection_data callback -> unit
126 (** [open_images images cb] is like {!open_domain} except
127 that it opens local disk image(s) directly.
129 If [fail] is passed, then failures cause this callback to
130 be called. If not, the global failure hook is called. *)
132 type source = OS of inspection_os | Volume of string
133 (** Source type used by {!read_directory}. *)
136 dent_name : string; (** Basename in directory. *)
137 dent_stat : Guestfs.stat; (** stat(2) for this entry. *)
138 dent_link : string; (** (for symlinks only) readlink(2). *)
140 (** Directory entry returned by {!read_directory}. *)
142 val read_directory : ?fail:exn callback -> source -> string -> direntry list callback -> unit
143 (** [read_directory src dir cb] reads the contents of the directory
144 [dir] from source [src], and calls the callback function [cb]
145 with the resulting list of directory entries, if successful.
147 The source may be either a filesystem (if [src] is [Volume
148 dev]), or a fully mounted up operating system (if [src] is [OS ...]).
149 In the second case all the mountpoints of the operating system
150 are mounted up so that the path may span mountpoints in the
153 If [fail] is passed, then failures cause this callback to
154 be called. If not, the global failure hook is called. *)
156 val discard_command_queue : unit -> unit
157 (** [discard_command_queue ()] discards any commands on the command
160 The currently running command cannot be discarded (because of
161 the design of libguestfs). Instead the callback is discarded,
162 so from the point of view of the main thread, the effect is
165 val exit_thread : unit -> unit
166 (** [exit_thread ()] causes the slave thread to exit, and returns
167 once it has exited. *)
171 Hooks are like callbacks, except they hook into special events
172 that happen in the slave thread, rather than just being a response
175 The other difference is that hooks are global variables. You can
176 only set one hook of each type.
178 {!set_failure_hook} is used to catch errors in slave commands
179 and display those in the main thread.
181 {!set_busy_hook} and {!set_idle_hook} are used to implement a
184 val set_failure_hook : exn callback -> unit
185 (** Set the function in the main thread which is called if there is
186 an error in the slave thread. If this is not set then errors
187 are discarded. [exn] is the exception. *)
189 val set_busy_hook : unit callback -> unit
190 (** Set the function in the main thread which is called whenever
191 the slave thread starts working on a command. *)
193 val set_idle_hook : unit callback -> unit
194 (** Set the function in the main thread which is called whenever
195 the slave thread stops working on a command {i and} has no
196 more commands left in the queue to work on. *)