slave.mli

   1 (* Virt-resize UI.
   2  * Copyright (C) 2011 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
  21 (** {2 Commands and callbacks}
  22
  23     Commands for libvirt and libguestfs are executed in a separate
  24     slave thread.  This file describes the interface with that thread
  25     that the rest of the program sees.
  26
  27     Commands are intentionally as high level as possible.  Often a
  28     single command may perform many libvirt and libguestfs operations
  29     before returing a result.  This is to make use of the slave thread
  30     as simple as possible.
  31
  32     Commands are executed in a "continuation-passing style" (CPS),
  33     which means that you call a function to issue the command, passing
  34     in a callback ("continuation").  The function returns immediately.
  35     The callback may be called some time later once the issued command
  36     completes successfully.  Several commands can be queued up for
  37     execution.  Commands are executed and callbacks are performed in
  38     sequence.
  39
  40     The callback returns the result of the command.  The callback does
  41     not get invoked if there was an error, or if the command was
  42     cancelled before it runs (see {!discard_command_queue}).  For some
  43     commands the callback can be called multiple times (see
  44     documentation below).
  45 *)
  46
  47 type 'a callback = 'a -> unit
  48 (** A callback function in the main thread which is called when the
  49     command finishes successfully.
  50
  51     This can also return some data (the ['a] parameter).  A command
  52     that returns a list of strings might have callback type [string
  53     list callback], and a command that returns nothing would have
  54     callback type [unit callback].
  55
  56     Note that errors are not returned this way.  Each function can
  57     optionally supply an extra callback to handle errors, or if
  58     not supplied then it defaults to the failure hook set by
  59     {!set_failure_hook}. *)
  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 message =
  66   (** {!b Do not use this directly}.  Call {!Slave.exit_thread}
  67       instead. *)
  68   | Exit_thread
  69
  70   (** Open disk image(s).  Return the guest inspection data. *)
  71   | Open_images of (string * string option) list *
  72       Slave_types.inspection_data callback
  73
  74 val string_of_message : message -> string
  75 (** Useful debugging function to display a message. *)
  76
  77 val send_message : ?fail:exn callback -> message -> unit
  78 (** Send a message to the slave thread.
  79
  80     Note as described above, this function returns immediately.  A
  81     callback (passed in the message) is called some time later if
  82     the call succeeds, otherwise one of the failure methods
  83     described above is used. *)
  84
  85 val discard_command_queue : unit -> unit
  86 (** [discard_command_queue ()] discards any commands on the command
  87     queue.
  88
  89     The currently running command cannot be discarded (because of
  90     the design of libguestfs).  Instead the callback is discarded,
  91     so from the point of view of the main thread, the effect is
  92     similar. *)
  93
  94 val exit_thread : unit -> unit
  95 (** [exit_thread ()] causes the slave thread to exit, and returns
  96     synchronously once the slave thread has exited. *)
  97
  98 (** {2 Hooks}
  99
 100     Hooks are like callbacks, except they hook into special events
 101     that happen in the slave thread, rather than just being a response
 102     to commands.
 103
 104     The other difference is that hooks are global variables.  You can
 105     only set one hook of each type.
 106
 107     {!set_failure_hook} is used to catch errors in slave commands
 108     and display those in the main thread.
 109
 110     {!set_busy_hook} and {!set_idle_hook} are used to implement a
 111     "throbber".
 112
 113     {!set_progress_hook} is used to implement a progress bar. *)
 114
 115 val set_failure_hook : exn callback -> unit
 116 (** Set the function in the main thread which is called if there is an
 117     error in the slave thread.  If this is not set then errors are
 118     discarded.  [exn] is the exception. *)
 119
 120 val set_busy_hook : unit callback -> unit
 121 (** Set the function in the main thread which is called whenever
 122     the slave thread starts working on a command. *)
 123
 124 val set_idle_hook : unit callback -> unit
 125 (** Set the function in the main thread which is called whenever the
 126     slave thread stops working on a command {i and} has no more
 127     commands left in the queue to work on. *)
 128
 129 val set_status_hook : string callback -> unit
 130 (** Set the function in the main thread which is called to
 131     update the status bar.  The slave thread updates the
 132     status bar when an operation starts or stops, keeping the
 133     user informed of what is happening. *)
 134
 135 val set_progress_hook : (int64 * int64) callback -> unit
 136 (** Set the function in the main thread which is called whenever the
 137     slave thread receives a progress notification message from
 138     libguestfs. *)