(** 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.
+val checksum_file : ?fail:exn callback -> Slave_types.source -> string -> string -> string callback -> unit
+ (** [checksum_file src pathname csumtype cb] calculates the checksum
+ of the file [pathname]. [csumtype] is one of the types
+ supported by libguestfs. *)
- 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 -> Slave_types.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. *)
-
-type domain = {
- dom_name : string;
- dom_state : Libvirt.Domain.state;
-}
- (** List of domains as returned in the [Get_domains] message callback.
-
- 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 get_domains : domain list callback -> unit
- (** [get_domains cb] sends the [Get_domains] message to the
- slave thread.
-
- 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. *)
+ doesn't make sense to use remote URIs.
+
+ If [fail] is passed, then failures cause this callback to
+ be called. If not, the global failure hook is called. *)
+
+val disk_usage : ?fail:exn callback -> Slave_types.source -> string -> int64 callback -> unit
+ (** [disk_usage src pathname cb] calculates the disk usage of
+ directory [pathname] and calls the callback with the answer
+ (size of {b kilobytes}). *)
+
+val download_dir_tarball : ?fail:exn callback -> Slave_types.source -> string -> Slave_types.download_dir_tarball_format -> string -> unit callback -> unit
+ (** [download_dir_tarball_format src pathname format localfile cb]
+ downloads directory [pathname] to the named local file (a
+ tarball), and then calls the callback function.
+
+ [format] controls the download format, which is one of
+ uncompressed tar, gzip-compressed tar, or xz-compressed tar. *)
+
+val download_dir_find0 : ?fail:exn callback -> Slave_types.source -> string -> string -> unit callback -> unit
+ (** [download_dir_find0 src pathname localfile cb] downloads the
+ list of filenames of directory [pathname] to the named local
+ file (a ASCII NUL-separated text file), and then calls the
+ callback function. *)
+
+val download_file : ?fail:exn callback -> Slave_types.source -> string -> string -> unit callback -> unit
+ (** [download_file src pathname localfile cb] downloads [pathname]
+ to the named local file, and then calls the callback function. *)
+
+val download_file_if_not_exist : ?fail:exn callback -> Slave_types.source -> string -> string -> unit callback -> unit
+ (** Like {!download_file} except that if [localfile] already exists
+ then the download is skipped. You can use this to implement
+ caching of remote files. *)
+
+val file_information : ?fail:exn callback -> Slave_types.source -> string -> string callback -> unit
+ (** [file_information src pathname cb] calculates the file
+ information of the file [pathname]. *)
+
+val open_domain : ?fail:exn callback -> string -> Slave_types.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 -> Slave_types.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. *)
+
+val read_directory : ?fail:exn callback -> Slave_types.source -> string -> Slave_types.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.
+
+ 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.
+
+ If [fail] is passed, then failures cause this callback to
+ be called. If not, the global failure hook is called. *)
+
+val run_command : ?fail:exn callback -> string -> unit callback -> unit
+ (** [run_command cmd] runs an external command [cmd]. This is
+ useful for possibly long-running commands as it keeps the
+ display interactive. Be careful to quote arguments in the
+ command properly (see {!Filename.quote}). The external command
+ must eventually terminate and must not wait for user input. *)
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_status_hook : string callback -> unit
+ (** Set the function in the main thread which is called to
+ update the status bar. The slave thread updates the
+ status bar when an operation starts or stops, keeping the
+ user informed of what is happening. *)
+
+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. *)
git.annexia.org / guestfs-browser.git / blobdiff