(** The public interface to the slave thread.
Please see HACKING file. *)
-(** {2 Commands and callbacks} *)
+(** {2 Commands and callbacks}
+
+ Commands for libvirt and libguestfs are executed in a separate slave
+ thread. This file describes the interface with that thread that the
+ rest of the program sees.
+
+ Commands are intentionally as high level as possible. Often a
+ single command may perform many libvirt and libguestfs operations
+ before returing a result. This is to make use of the slave thread
+ as simple as possible.
+
+ Commands are executed in a "continuation-passing style" (CPS),
+ which means that you call a function to issue the command, passing
+ in a callback ("continuation"). The function returns immediately.
+ The callback may be called some time later once the issued command
+ completes successfully. Several commands can be queued up for
+ execution. Commands are executed and callbacks are performed in
+ sequence.
+
+ The callback returns the result of the command. The callback does
+ not get invoked if there was an error, or if the command was
+ cancelled before it runs (see {!discard_command_queue}). For some
+ commands the callback can be called multiple times (see
+ documentation below).
+*)
type 'a callback = 'a -> unit
(** A callback function in the main thread which is called when the
- command finishes (successfully).
+ command finishes successfully.
This can also return some data (the ['a] parameter). A command
that returns a list of strings might have callback type [string
list callback], and a command that returns nothing would have
callback type [unit callback].
- Note that errors are not returned this way. Errors result
- in the command queue being discarded and the failure_hook
- function being called. *)
+ Note that errors are not returned this way. Each function can
+ optionally supply an extra callback to handle errors, or if
+ not supplied then it defaults to the failure hook set by
+ {!set_failure_hook}. *)
val no_callback : 'a callback
(** The main thread uses this as a callback if it doesn't care about
the return value from a command. *)
-val connect : string option -> unit callback -> unit
- (** [connect uri cb] sends the [Connect] message to the slave
- thread.
+type domain = {
+ dom_id : int;
+ dom_name : string;
+ dom_state : Libvirt.Domain.state;
+}
+ (** List of domains as returned in the {!connect} callback. *)
- This causes the slave thread to disconnect from libvirt and
- connect to the libvirt [uri]. If this succeeds, [cb] is called
- in the main thread.
+val connect : ?fail:exn callback -> string option -> domain list callback -> unit
+ (** [connect uri cb] causes the slave thread to disconnect from
+ libvirt and connect to the libvirt [uri]. If this succeeds,
+ then the list of all domains fetched from libvirt and [cb] is
+ called in the main thread.
Although you can connect to remote hosts, libguestfs won't
usually be able to see the drives on those hosts, so it normally
- doesn't make sense to use remote URIs. *)
+ doesn't make sense to use remote URIs.
-type domain = {
- dom_name : string;
- dom_state : Libvirt.Domain.state;
+ If [fail] is passed, then failures cause this callback to
+ be called. If not, the global failure hook is called. *)
+
+type inspection_data = {
+ insp_all_filesystems : (string * string) list;
+ (** see {!Guestfs.list_filesystems} *)
+ insp_oses : inspection_os list;
+ (** one entry per root (operating system), see {!Guestfs.inspect_os} *)
+}
+ (** The inspection data returned in the callback from
+ {!open_domain} and {!open_images}. *)
+and inspection_os = {
+ insp_root : string; (** see {!Guestfs.inspect_os} *)
+ insp_arch : string;
+ insp_distro : string;
+ insp_filesystems : string array;
+ insp_hostname : string;
+ insp_major_version : int;
+ insp_minor_version : int;
+ insp_mountpoints : (string * string) list;
+ insp_package_format : string;
+ insp_package_management : string;
+ insp_product_name : string;
+ insp_type : string;
+ insp_windows_systemroot : string option;
+}
+
+val open_domain : ?fail:exn callback -> string -> inspection_data callback -> unit
+ (** [open_domain name cb] retrieves the list of block devices for
+ the libvirt domain [name], creates a libguestfs handle, adds
+ those block devices, launches the handle, and performs
+ inspection.
+
+ If this is successful, then [cb] is called in the main thread
+ with the list of filesystems and the results of inspection.
+
+ The slave thread must be connected to libvirt (see {!connect})
+ else this command will fail.
+
+ If [fail] is passed, then failures cause this callback to
+ be called. If not, the global failure hook is called. *)
+
+val open_images : ?fail:exn callback -> (string * string option) list -> inspection_data callback -> unit
+ (** [open_images images cb] is like {!open_domain} except that it
+ opens local disk image(s) directly. [images] is a list of
+ [(filename, format)] pairs.
+
+ If [fail] is passed, then failures cause this callback to
+ be called. If not, the global failure hook is called. *)
+
+type source = OS of inspection_os | Volume of string
+ (** Source type used by {!read_directory}. *)
+
+type direntry = {
+ dent_name : string; (** Basename in directory. *)
+ dent_stat : Guestfs.stat; (** stat(2) for this entry. *)
+ dent_link : string; (** (for symlinks only) readlink(2). *)
}
- (** List of domains as returned in the [Get_domains] message callback.
+ (** Directory entry returned by {!read_directory}. *)
- Note that [dom_state] is the state of the domain and should
- control whether we are allowed to write to the domain's
- filesystem (disallowed if [dom_state] is [InfoRunning]). *)
+val read_directory : ?fail:exn callback -> source -> string -> direntry list callback -> unit
+ (** [read_directory src dir cb] reads the contents of the directory
+ [dir] from source [src], and calls the callback function [cb]
+ with the resulting list of directory entries, if successful.
-val get_domains : domain list callback -> unit
- (** [get_domains cb] sends the [Get_domains] message to the
- slave thread.
+ The source may be either a filesystem (if [src] is [Volume
+ dev]), or a fully mounted up operating system (if [src] is [OS ...]).
+ In the second case all the mountpoints of the operating system
+ are mounted up so that the path may span mountpoints in the
+ natural way.
- This causes the slave thread to retrieve the list of domains
- from libvirt (active and inactive ones). If this succeeds,
- [cb] is called in the main thread with the list of
- domains. See also the {!domain} type. *)
+ If [fail] is passed, then failures cause this callback to
+ be called. If not, the global failure hook is called. *)
val discard_command_queue : unit -> unit
(** [discard_command_queue ()] discards any commands on the command
- queue. The currently running command is not (and can not be)
- stopped. *)
+ queue.
+
+ The currently running command cannot be discarded (because of
+ the design of libguestfs). Instead the callback is discarded,
+ so from the point of view of the main thread, the effect is
+ similar. *)
val exit_thread : unit -> unit
(** [exit_thread ()] causes the slave thread to exit, and returns
(** {2 Hooks}
Hooks are like callbacks, except they hook into special events
- that happen in the slave threads, rather than just being a
- response to commands.
+ that happen in the slave thread, rather than just being a response
+ to commands.
The other difference is that hooks are global variables. You can
only set one hook of each type.
and display those in the main thread.
{!set_busy_hook} and {!set_idle_hook} are used to implement a
- "throbber". *)
+ "throbber".
+
+ {!set_progress_hook} is used to implement a progress bar. *)
val set_failure_hook : exn callback -> unit
(** Set the function in the main thread which is called if there is
(** Set the function in the main thread which is called whenever
the slave thread stops working on a command {i and} has no
more commands left in the queue to work on. *)
+
+val set_progress_hook : (int64 * int64) callback -> unit
+ (** Set the function in the main thread which is called whenever
+ the slave thread receives a progress notification message
+ from libguestfs. *)