X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=slave.mli;h=5eaa9c93929aeb246eaf62936b7be39180de1def;hb=298cc147ee0015df2128f9efe0402004e9820b9c;hp=994890f8547c86296e8659a0ba683907d568bab4;hpb=bbfe03c47f1d7f03c3e6c0cab9e4f500f588c80a;p=guestfs-browser.git diff --git a/slave.mli b/slave.mli index 994890f..5eaa9c9 100644 --- a/slave.mli +++ b/slave.mli @@ -19,60 +19,160 @@ (** 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 list_applications : ?fail:exn callback -> Slave_types.inspection_os -> Guestfs.application array callback -> unit + (** [list_applications os cb] lists the applications in the + guest using libguestfs inspection. *) + +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 reopen : ?fail:exn callback -> Slave_types.inspection_data callback -> unit + (** [reopen cb] reruns the last {!open_domain} or {!open_images} + command, if there was one. *) + +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 @@ -81,8 +181,8 @@ val exit_thread : unit -> unit (** {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. @@ -91,7 +191,9 @@ val exit_thread : unit -> unit 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 @@ -106,3 +208,14 @@ val set_idle_hook : unit callback -> unit (** 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. *)