(* Virt-resize UI.
 * Copyright (C) 2011 Red Hat Inc.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 *)

(** The public interface to the slave thread. *)

(** {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.

    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.  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. *)

type message =
  (** {!b Do not use this directly}.  Call {!Slave.exit_thread}
      instead. *)
  | Exit_thread

  (** Open disk image(s).  Return the guest inspection data. *)
  | Open_images of (string * string option) list *
      Slave_types.inspection_data callback

val string_of_message : message -> string
(** Useful debugging function to display a message. *)

val send_message : ?fail:exn callback -> message -> unit
(** Send a message to the slave thread.

    Note as described above, this function returns immediately.  A
    callback (passed in the message) is called some time later if
    the call succeeds, otherwise one of the failure methods
    described above is used. *)

val discard_command_queue : unit -> unit
(** [discard_command_queue ()] discards any commands on the command
    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
    synchronously once the slave thread has exited. *)

(** {2 Hooks}

    Hooks are like callbacks, except they hook into special events
    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.

    {!set_failure_hook} is used to catch errors in slave commands
    and display those in the main thread.

    {!set_busy_hook} and {!set_idle_hook} are used to implement a
    "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 an
    error in the slave thread.  If this is not set then errors are
    discarded.  [exn] is the exception. *)

val set_busy_hook : unit callback -> unit
(** Set the function in the main thread which is called whenever
    the slave thread starts working on a command. *)

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. *)