{[
open Printf
-let domains =
- fst (Libvirt.get_domains conn ~want_info:false [D.ListActive]) in
+let domains = D.get_domains conn [D.ListActive] in
List.iter (
fun dom ->
printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
{3 Example: List inactive domains}
{[
-let domains =
- fst (Libvirt.get_domains conn ~want_info:false [D.ListInactive]) in
+let domains = D.get_domains conn [D.ListInactive] in
List.iter (
fun dom ->
printf "inactive %s\n%!" (D.get_name dom)
We don't support libvirt < 0.2.1, and never will so don't ask us.
- {3 Get list of domains}
+ {3 Get list of domains and domain infos}
This is a very common operation, and libvirt supports various
different methods to do it. We have hidden the complexity in a
- flexible {!Libvirt.get_domains} call which is easy to use and
+ flexible {!Libvirt.Domain.get_domains} and
+ {!Libvirt.Domain.get_domains_and_infos} calls which is easy to use and
automatically chooses the most efficient method depending on the
version of libvirt in use.
| Read_only of Libvirt.ro Libvirt.Connect.t
| Read_write of Libvirt.rw Libvirt.Connect.t
]}
- See also the source of [mlvirsh].
*)
(** {3 Forward definitions}
use recursive module dependencies.
*)
-type ('a, 'b) job_t
-(** Forward definition of {!Job.t}. *)
-
(** {3 Connections} *)
module Connect :
Call {!num_of_domains} first to get a value for [max].
- See also: {!Libvirt.get_domains}.
+ See also:
+ {!Libvirt.Domain.get_domains},
+ {!Libvirt.Domain.get_domains_and_infos}.
*)
val num_of_domains : [>`R] t -> int
(** Returns the number of running domains. *)
Call {!num_of_defined_domains} first to get a value for [max].
- See also: {!Libvirt.get_domains}.
+ See also:
+ {!Libvirt.Domain.get_domains},
+ {!Libvirt.Domain.get_domains_and_infos}.
*)
val num_of_networks : [>`R] t -> int
(** Returns the number of networks. *)
type memory_flag = Virtual
type list_flag =
- | ListNoState | ListRunning | ListBlocked
- | ListPaused | ListShutdown | ListShutoff | ListCrashed
| ListActive
| ListInactive
| ListAll
functions. If you want to peek more than this then you must
break your request into chunks. *)
- val list_all_domains : 'a Connect.t -> ?want_info:bool -> list_flag list -> 'a t array * info array
- (** [list_all_domains conn flags] returns all domains which
- match [flags].
-
- This can return both active and inactive domains. The
- list of flags controls what domains are returned. See
- {!list_flag}.
-
- The two arrays returned will have the same length, unless
- [~want_info] is [false] in which case the info array
- will be zero-length. The default for [~want_info] is [true].
- In most cases there is no extra penalty for getting the
- info fields, or the penalty is insignificant.
-
- This call was introduced in libvirt 0.4.5. Because you
- might dynamically link to an older version of libvirt which
- doesn't have this call, you should use {!Libvirt.get_domains}
- which uses the most efficient way to get domains for the
- available version of libvirt.
- *)
val create_linux : [>`W] Connect.t -> xml -> rw t
(** Create a new guest domain (not necessarily a Linux one)
from the given XML.
*)
- val create_linux_job : [>`W] Connect.t -> xml -> ([`Domain], rw) job_t
- (** Asynchronous domain creation. *)
val lookup_by_id : 'a Connect.t -> int -> 'a t
(** Lookup a domain by ID. *)
val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
(** Resume a domain. *)
val save : [>`W] t -> filename -> unit
(** Suspend a domain, then save it to the file. *)
- val save_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
- (** Asynchronous domain suspend. *)
val restore : [>`W] Connect.t -> filename -> unit
(** Restore a domain from a file. *)
- val restore_job : [>`W] Connect.t -> filename -> ([`Domain_nocreate], rw) job_t
- (** Asynchronous domain restore. *)
val core_dump : [>`W] t -> filename -> unit
(** Force a domain to core dump to the named file. *)
- val core_dump_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
- (** Asynchronous core dump. *)
val shutdown : [>`W] t -> unit
(** Shutdown a domain. *)
val reboot : [>`W] t -> unit
val get_uuid_string : [>`R] t -> string
(** Get the domain UUID (as a printable string). *)
val get_id : [>`R] t -> int
- (** [getid dom] returns the ID of the domain.
-
- Do not call this on a defined but not running domain. Those
- domains don't have IDs, and you'll get an error here.
- *)
-
+ (** [get_id dom] returns the ID of the domain. In most cases
+ this returns [-1] if the domain is not running. *)
val get_os_type : [>`R] t -> string
(** Get the operating system type. *)
val get_max_memory : [>`R] t -> int64
(** Undefine a domain - removes its configuration. *)
val create : [>`W] t -> unit
(** Launch a defined (inactive) domain. *)
- val create_job : [>`W] t -> ([`Domain_nocreate], rw) job_t
- (** Asynchronous launch domain. *)
val get_autostart : [>`R] t -> bool
(** Get the autostart flag for a domain. *)
val set_autostart : [>`W] t -> bool -> unit
val interface_stats : [>`R] t -> string -> interface_stats
(** Returns network interface stats. *)
- val block_peek : [>`R] t -> string -> int64 -> int -> string -> int -> unit
+ val block_peek : [>`W] t -> string -> int64 -> int -> string -> int -> unit
(** [block_peek dom path offset size buf boff] reads [size] bytes at
[offset] in the domain's [path] block device.
at offset [boff], for [size] bytes.
See also {!max_peek}. *)
- val memory_peek : [>`R] t -> memory_flag list -> int64 -> int ->
+ val memory_peek : [>`W] t -> memory_flag list -> int64 -> int ->
string -> int -> unit
(** [memory_peek dom Virtual offset size] reads [size] bytes
at [offset] in the domain's virtual memory.
(** [const dom] turns a read/write domain handle into a read-only
domain handle. Note that the opposite operation is impossible.
*)
+
+ val get_domains : ([>`R] as 'a) Connect.t -> list_flag list -> 'a t list
+ (** Get the active and/or inactive domains using the most
+ efficient method available.
+
+ See also:
+ {!get_domains_and_infos},
+ {!Connect.list_domains},
+ {!Connect.list_defined_domains}.
+ *)
+
+ val get_domains_and_infos : ([>`R] as 'a) Connect.t -> list_flag list ->
+ ('a t * info) list
+ (** This gets the active and/or inactive domains and the
+ domain info for each one using the most efficient
+ method available.
+
+ See also:
+ {!get_domains},
+ {!Connect.list_domains},
+ {!Connect.list_defined_domains},
+ {!get_info}.
+ *)
+
end
(** Module dealing with domains. [Domain.t] is the
domain object. *)
(** Lookup a network by UUID string. *)
val create_xml : [>`W] Connect.t -> xml -> rw t
(** Create a network. *)
- val create_xml_job : [>`W] Connect.t -> xml -> ([`Network], rw) job_t
- (** Asynchronous create network. *)
val define_xml : [>`W] Connect.t -> xml -> rw t
(** Define but don't activate a network. *)
val undefine : [>`W] t -> unit
(** Undefine configuration of a network. *)
val create : [>`W] t -> unit
(** Start up a defined (inactive) network. *)
- val create_job : [>`W] t -> ([`Network_nocreate], rw) job_t
- (** Asynchronous start network. *)
val destroy : [>`W] t -> unit
(** Destroy a network. *)
val free : [>`R] t -> unit
end
(** Module dealing with storage volumes. *)
-(** {3 Jobs and asynchronous processing} *)
-
-module Job :
-sig
- type ('jobclass, 'rw) t = ('jobclass, 'rw) job_t
- (** A background asynchronous job.
-
- Jobs represent a pending operation such as domain creation.
- The possible types for a job are:
-
-{v
-(`Domain, `W) Job.t Job creating a new domain
-(`Domain_nocreate, `W) Job.t Job acting on an existing domain
-(`Network, `W) Job.t Job creating a new network
-(`Network_nocreate, `W) Job.t Job acting on an existing network
-v}
- *)
-
- type job_type = Bounded | Unbounded
- (** A Bounded job is one where we can estimate time to completion. *)
-
- type job_state = Running | Complete | Failed | Cancelled
- (** State of the job. *)
-
- type job_info = {
- typ : job_type; (** Job type (Bounded, Unbounded) *)
- state : job_state; (** Job state (Running, etc.) *)
- running_time : int; (** Actual running time (seconds) *)
- (** The following fields are only available in Bounded jobs: *)
- remaining_time : int; (** Estimated time left (seconds) *)
- percent_complete : int (** Estimated percent complete *)
- }
-
- val get_info : ('a,'b) t -> job_info
- (** Get information and status about the job. *)
-
- val get_domain : ([`Domain], 'a) t -> 'a Domain.t
- (** Get the completed domain from a job.
-
- You should only call it on a job in state Complete. *)
-
- val get_network : ([`Network], 'a) t -> 'a Network.t
- (** Get the completed network from a job.
-
- You should only call it on a job in state Complete. *)
-
- val cancel : ('a,'b) t -> unit
- (** Cancel a job. *)
-
- val free : ('a, [>`R]) t -> unit
- (** Free a job object in memory.
-
- The job object is automatically freed if it is garbage
- collected. This function just forces it to be freed right
- away.
- *)
-
- external const : ('a, [>`R]) t -> ('a, ro) t = "%identity"
- (** [const conn] turns a read/write job into a read-only
- job. Note that the opposite operation is impossible.
- *)
-end
- (** Module dealing with asynchronous jobs. *)
-
(** {3 Error handling and exceptions} *)
module Virterror :
might 'disappear' asynchronously from the currently running
program.
*)
-
-val get_domains : ([>`R] as 'a) Connect.t -> ?want_info:bool -> Domain.list_flag list -> 'a Domain.t list * Domain.info list
- (** Get the active and/or inactive domains using the most
- efficient method available.
-
- The two lists returned will have the same length, unless
- [~want_info] is [false] in which case the info list will be
- zero-length. The default for [~want_info] is [true]. In most
- cases there is no extra penalty for getting the info fields, or
- the penalty is insignificant.
-
- See also:
- {!Domain.list_all_domains},
- {!Connect.list_domains},
- {!Connect.list_defined_domains}.
- *)