slave.mli

   1 (* Guestfs Browser.
   2  * Copyright (C) 2010 Red Hat Inc.
   3  *
   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.
   8  *
   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.
  13  *
  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.
  17  *)
  18
  19 (** The public interface to the slave thread.
  20     Please see HACKING file. *)
  21
  22 (** {2 Commands and callbacks}
  23
  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.
  27
  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.
  32
  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
  39     sequence.
  40
  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
  45     documentation below).
  46 *)
  47
  48 type 'a callback = 'a -> unit
  49   (** A callback function in the main thread which is called when the
  50       command finishes successfully.
  51
  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].
  56
  57       Note that errors are not returned this way.  Errors result
  58       in the command queue being discarded and the failure_hook
  59       function being called. *)
  60
  61 val no_callback : 'a callback
  62   (** The main thread uses this as a callback if it doesn't care about
  63       the return value from a command. *)
  64
  65 type domain = {
  66   dom_id : int;
  67   dom_name : string;
  68   dom_state : Libvirt.Domain.state;
  69 }
  70     (** List of domains as returned in the {!connect} callback. *)
  71
  72 val connect : string option -> domain list callback -> unit
  73   (** [connect uri cb] causes the slave thread to disconnect from
  74       libvirt and connect to the libvirt [uri].  If this succeeds,
  75       then the list of all domains fetched from libvirt and [cb] is
  76       called in the main thread.
  77
  78       Although you can connect to remote hosts, libguestfs won't
  79       usually be able to see the drives on those hosts, so it normally
  80       doesn't make sense to use remote URIs. *)
  81
  82 type inspection_data = {
  83   insp_all_filesystems : (string * string) list;
  84   (** see {!Guestfs.list_filesystems} *)
  85   insp_oses : inspection_os list;
  86   (** one entry per root (operating system), see {!Guestfs.inspect_os} *)
  87 }
  88     (** The inspection data returned in the callback from
  89         {!open_domain} and {!open_images}. *)
  90 and inspection_os = {
  91   insp_root : string;                 (** see {!Guestfs.inspect_os} *)
  92   insp_arch : string;
  93   insp_distro : string;
  94   insp_filesystems : string array;
  95   insp_hostname : string;
  96   insp_major_version : int;
  97   insp_minor_version : int;
  98   insp_mountpoints : (string * string) list;
  99   insp_package_format : string;
 100   insp_package_management : string;
 101   insp_product_name : string;
 102   insp_type : string;
 103   insp_windows_systemroot : string option;
 104 }
 105
 106 val open_domain : string -> inspection_data callback -> unit
 107   (** [open_domain name cb] retrieves the list of block devices for
 108       the libvirt domain [name], creates a libguestfs handle, adds
 109       those block devices, launches the handle, and performs
 110       inspection.
 111
 112       If this is successful, then [cb] is called in the main thread
 113       with the list of filesystems and the results of inspection.
 114
 115       The slave thread must be connected to libvirt (see {!connect})
 116       else this command will fail. *)
 117
 118 val open_images : string list -> inspection_data callback -> unit
 119   (** [open_images images cb] is like {!open_domain} except
 120       that it opens local disk image(s) directly. *)
 121
 122 type source = OS of inspection_os | Volume of string
 123   (** Source type used by {!read_directory}. *)
 124
 125 type direntry = {
 126   dent_name : string;          (** Basename in directory. *)
 127   dent_stat : Guestfs.stat;    (** stat(2) for this entry. *)
 128   dent_link : string;          (** (for symlinks only) readlink(2). *)
 129 }
 130     (** Directory entry returned by {!read_directory}. *)
 131
 132 val read_directory : source -> string -> direntry list callback -> unit
 133   (** [read_directory src dir cb] reads the contents of the directory
 134       [dir] from source [src], and calls the callback function [cb]
 135       with the resulting list of directory entries, if successful.
 136
 137       The source may be either a filesystem (if [src] is [Volume
 138       dev]), or a fully mounted up operating system (if [src] is [OS ...]).
 139       In the second case all the mountpoints of the operating system
 140       are mounted up so that the path may span mountpoints in the
 141       natural way. *)
 142
 143 val discard_command_queue : unit -> unit
 144   (** [discard_command_queue ()] discards any commands on the command
 145       queue.
 146
 147       The currently running command cannot be discarded (because of
 148       the design of libguestfs).  Instead the callback is discarded,
 149       so from the point of view of the main thread, the effect is
 150       similar. *)
 151
 152 val exit_thread : unit -> unit
 153   (** [exit_thread ()] causes the slave thread to exit, and returns
 154       once it has exited. *)
 155
 156 (** {2 Hooks}
 157
 158     Hooks are like callbacks, except they hook into special events
 159     that happen in the slave thread, rather than just being a response
 160     to commands.
 161
 162     The other difference is that hooks are global variables.  You can
 163     only set one hook of each type.
 164
 165     {!set_failure_hook} is used to catch errors in slave commands
 166     and display those in the main thread.
 167
 168     {!set_busy_hook} and {!set_idle_hook} are used to implement a
 169     "throbber". *)
 170
 171 val set_failure_hook : exn callback -> unit
 172   (** Set the function in the main thread which is called if there is
 173       an error in the slave thread.  If this is not set then errors
 174       are discarded.  [exn] is the exception. *)
 175
 176 val set_busy_hook : unit callback -> unit
 177   (** Set the function in the main thread which is called whenever
 178       the slave thread starts working on a command. *)
 179
 180 val set_idle_hook : unit callback -> unit
 181   (** Set the function in the main thread which is called whenever
 182       the slave thread stops working on a command {i and} has no
 183       more commands left in the queue to work on. *)