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 type 'a callback = 'a -> unit
  25   (** A callback function in the main thread which is called when the
  26       command finishes (successfully).
  27
  28       This can also return some data (the ['a] parameter).  A command
  29       that returns a list of strings might have callback type [string
  30       list callback], and a command that returns nothing would have
  31       callback type [unit callback].
  32
  33       Note that errors are not returned this way.  Errors result
  34       in the command queue being discarded and the failure_hook
  35       function being called. *)
  36
  37 val no_callback : 'a callback
  38   (** The main thread uses this as a callback if it doesn't care about
  39       the return value from a command. *)
  40
  41 val connect : string option -> unit callback -> unit
  42   (** [connect uri cb] sends the [Connect] message to the slave
  43       thread.
  44
  45       This causes the slave thread to disconnect from libvirt and
  46       connect to the libvirt [uri].  If this succeeds, [cb] is called
  47       in the main thread.
  48
  49       Although you can connect to remote hosts, libguestfs won't
  50       usually be able to see the drives on those hosts, so it normally
  51       doesn't make sense to use remote URIs. *)
  52
  53 type domain = {
  54   dom_name : string;
  55   dom_state : Libvirt.Domain.state;
  56 }
  57     (** List of domains as returned in the [Get_domains] message callback.
  58
  59         Note that [dom_state] is the state of the domain and should
  60         control whether we are allowed to write to the domain's
  61         filesystem (disallowed if [dom_state] is [InfoRunning]). *)
  62
  63 val get_domains : domain list callback -> unit
  64   (** [get_domains cb] sends the [Get_domains] message to the
  65       slave thread.
  66
  67       This causes the slave thread to retrieve the list of domains
  68       from libvirt (active and inactive ones).  If this succeeds,
  69       [cb] is called in the main thread with the list of
  70       domains.  See also the {!domain} type. *)
  71
  72 val discard_command_queue : unit -> unit
  73   (** [discard_command_queue ()] discards any commands on the command
  74       queue.  The currently running command is not (and can not be)
  75       stopped. *)
  76
  77 val exit_thread : unit -> unit
  78   (** [exit_thread ()] causes the slave thread to exit, and returns
  79       once it has exited. *)
  80
  81 (** {2 Hooks}
  82
  83     Hooks are like callbacks, except they hook into special events
  84     that happen in the slave threads, rather than just being a
  85     response to commands.
  86
  87     The other difference is that hooks are global variables.  You can
  88     only set one hook of each type.
  89
  90     {!set_failure_hook} is used to catch errors in slave commands
  91     and display those in the main thread.
  92
  93     {!set_busy_hook} and {!set_idle_hook} are used to implement a
  94     "throbber". *)
  95
  96 val set_failure_hook : exn callback -> unit
  97   (** Set the function in the main thread which is called if there is
  98       an error in the slave thread.  If this is not set then errors
  99       are discarded.  [exn] is the exception. *)
 100
 101 val set_busy_hook : unit callback -> unit
 102   (** Set the function in the main thread which is called whenever
 103       the slave thread starts working on a command. *)
 104
 105 val set_idle_hook : unit callback -> unit
 106   (** Set the function in the main thread which is called whenever
 107       the slave thread stops working on a command {i and} has no
 108       more commands left in the queue to work on. *)