Remove backwards compatability logic to simplify the bindings

[ocaml-libvirt.git] / libvirt / libvirt.mli

diff --git a/libvirt/libvirt.mli b/libvirt/libvirt.mli
index 89c6d90..0185402 100644 (file)
--- a/libvirt/libvirt.mli
+++ b/libvirt/libvirt.mli
@@ -61,47 +61,44 @@ v}
    {{:http://libvirt.org/html/libvirt-libvirt.html}virConnect*, virDomain* and virNetwork* functions from libvirt}.
    For brevity I usually rename these modules like this:
 
    {{:http://libvirt.org/html/libvirt-libvirt.html}virConnect*, virDomain* and virNetwork* functions from libvirt}.
    For brevity I usually rename these modules like this:
 

-{v
+{[

 module C = Libvirt.Connect
 module D = Libvirt.Domain
 module N = Libvirt.Network
 module C = Libvirt.Connect
 module D = Libvirt.Domain
 module N = Libvirt.Network

-v}
+]}

 
    To get a connection handle, assuming a Xen hypervisor:
 
 
    To get a connection handle, assuming a Xen hypervisor:
 

-{v
+{[

 let name = "xen:///"
 let conn = C.connect_readonly ~name ()
 let name = "xen:///"
 let conn = C.connect_readonly ~name ()

-v}
+]}

 
    {3 Example: List running domains}
 
 
    {3 Example: List running domains}
 

-{v
+{[

 open Printf
 
 open Printf
 

-let n = C.num_of_domains conn in
-let ids = C.list_domains conn n in
-let domains = Array.map (D.lookup_by_id conn) ids in
-Array.iter (
+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)
 ) domains;
   fun dom ->
     printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
 ) domains;

-v}
+]}

 
    {3 Example: List inactive domains}
 
 
    {3 Example: List inactive domains}
 

-{v
-let n = C.num_of_defined_domains conn in
-let names = C.list_defined_domains conn n in
-Array.iter (
-  fun name ->
-    printf "inactive %s\n%!" name
-) names;
-v}
+{[
+let domains = D.get_domains conn [D.ListInactive] in
+List.iter (
+  fun dom ->
+    printf "inactive %s\n%!" (D.get_name dom)
+) domains;
+]}

 
    {3 Example: Print node info}
 
 
    {3 Example: Print node info}
 

-{v
+{[

 let node_info = C.get_node_info conn in
 printf "model = %s\n" node_info.C.model;
 printf "memory = %Ld K\n" node_info.C.memory;
 let node_info = C.get_node_info conn in
 printf "model = %s\n" node_info.C.model;
 printf "memory = %Ld K\n" node_info.C.memory;


@@ -117,7 +114,7 @@ printf "hostname = %s\n%!" hostname;
 
 let uri = C.get_uri conn in
 printf "uri = %s\n%!" uri
 
 let uri = C.get_uri conn in
 printf "uri = %s\n%!" uri

-v}
+]}

 
 *)
 
 
 *)
 


@@ -140,23 +137,25 @@ v}
     Note that even though you hold open (eg) a domain object, that
     doesn't mean that the domain (virtual machine) actually exists.
     The domain could have been shut down or deleted by another user.
     Note that even though you hold open (eg) a domain object, that
     doesn't mean that the domain (virtual machine) actually exists.
     The domain could have been shut down or deleted by another user.

-    Thus domain objects can through odd exceptions at any time.
+    Thus domain objects can raise odd exceptions at any time.

     This is just the nature of virtualisation.
 
     {3 Backwards and forwards compatibility}
 
     This is just the nature of virtualisation.
 
     {3 Backwards and forwards compatibility}
 

-    OCaml-libvirt is backwards and forwards compatible with
-    any libvirt >= 0.2.1.  One consequence of this is that
-    your program can dynamically link to a {i newer} version of
-    libvirt than it was compiled with, and it should still
-    work.
+    OCaml-libvirt requires libvirt version 1.0.2 or later. Future
+    releases of OCaml-libvirt will use newer features of libvirt
+    and therefore will require later versions of libvirt. It is always
+    possible to dynamically link your application against a newer
+    libvirt than OCaml-libvirt was originally compiled against.

 
 

-    When we link to an older version of libvirt.so, there may
-    be missing functions.  If ocaml-libvirt was compiled with
-    gcc, then these are turned into OCaml {!Libvirt.Not_supported}
-    exceptions.
+    {3 Get list of domains and domain infos}

 
 

-    We don't support libvirt < 0.2.1, and never will so don't ask us.
+    This is a very common operation, and libvirt supports various
+    different methods to do it.  We have hidden the complexity in a
+    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.

 
     {3 Threads}
 
 
     {3 Threads}
 


@@ -227,17 +226,19 @@ type ro = [`R]
 
        If you want to handle both read-write and read-only
        connections at runtime, use a variant similar to this:
 
        If you want to handle both read-write and read-only
        connections at runtime, use a variant similar to this:

-{v
+{[

 type conn_t =
     | No_connection
     | Read_only of Libvirt.ro Libvirt.Connect.t
     | Read_write of Libvirt.rw Libvirt.Connect.t
 type conn_t =
     | No_connection
     | Read_only of Libvirt.ro Libvirt.Connect.t
     | Read_write of Libvirt.rw Libvirt.Connect.t

-v}
-       See also the source of [mlvirsh].
+]}

     *)
 
     *)
 

-type ('a, 'b) job_t
-(** Forward definition of {!Job.t} to avoid recursive module dependencies. *)
+(** {3 Forward definitions}
+
+    These definitions are placed here to avoid the need to
+    use recursive module dependencies.
+*)

 
 (** {3 Connections} *)
 
 
 (** {3 Connections} *)
 


@@ -293,7 +294,12 @@ sig
   val list_domains : [>`R] t -> int -> int array
     (** [list_domains conn max] returns the running domain IDs,
        up to a maximum of [max] entries.
   val list_domains : [>`R] t -> int -> int array
     (** [list_domains conn max] returns the running domain IDs,
        up to a maximum of [max] entries.

+

        Call {!num_of_domains} first to get a value for [max].
        Call {!num_of_domains} first to get a value for [max].

+
+       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. *)
     *)
   val num_of_domains : [>`R] t -> int
     (** Returns the number of running domains. *)


@@ -305,7 +311,12 @@ sig
     (** [list_defined_domains conn max]
        returns the names of the inactive domains, up to
        a maximum of [max] entries.
     (** [list_defined_domains conn max]
        returns the names of the inactive domains, up to
        a maximum of [max] entries.

+

        Call {!num_of_defined_domains} first to get a value for [max].
        Call {!num_of_defined_domains} first to get a value for [max].

+
+       See also:
+       {!Libvirt.Domain.get_domains},
+       {!Libvirt.Domain.get_domains_and_infos}.

     *)
   val num_of_networks : [>`R] t -> int
     (** Returns the number of networks. *)
     *)
   val num_of_networks : [>`R] t -> int
     (** Returns the number of networks. *)


@@ -395,7 +406,7 @@ sig
     | InfoShutdown | InfoShutoff | InfoCrashed
 
   type info = {
     | InfoShutdown | InfoShutoff | InfoCrashed
 
   type info = {

-    state : state;                     (** running state *)
+    state : state;                     (** running state *)

     max_mem : int64;                   (** maximum memory in kilobytes *)
     memory : int64;                    (** memory used in kilobytes *)
     nr_virt_cpu : int;                 (** number of virtual CPUs *)
     max_mem : int64;                   (** maximum memory in kilobytes *)
     memory : int64;                    (** memory used in kilobytes *)
     nr_virt_cpu : int;                 (** number of virtual CPUs *)


@@ -417,10 +428,22 @@ sig
     | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
     | SchedFieldFloat of float | SchedFieldBool of bool
 
     | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
     | SchedFieldFloat of float | SchedFieldBool of bool
 

+  type typed_param = string * typed_param_value
+  and typed_param_value =
+    | TypedFieldInt32 of int32 | TypedFieldUInt32 of int32
+    | TypedFieldInt64 of int64 | TypedFieldUInt64 of int64
+    | TypedFieldFloat of float | TypedFieldBool of bool
+    | TypedFieldString of string
+

   type migrate_flag = Live
 
   type memory_flag = Virtual
 
   type migrate_flag = Live
 
   type memory_flag = Virtual
 

+  type list_flag =
+    | ListActive
+    | ListInactive
+    | ListAll
+

   type block_stats = {
     rd_req : int64;
     rd_bytes : int64;
   type block_stats = {
     rd_req : int64;
     rd_bytes : int64;


@@ -440,12 +463,15 @@ sig
     tx_drop : int64;
   }
 
     tx_drop : int64;
   }
 

+  val max_peek : [>`R] t -> int
+    (** Maximum size supported by the {!block_peek} and {!memory_peek}
+       functions.  If you want to peek more than this then you must
+       break your request into chunks. *)
+

   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 : [>`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
   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


@@ -470,16 +496,10 @@ sig
     (** Resume a domain. *)
   val save : [>`W] t -> filename -> unit
     (** Suspend a domain, then save it to the file. *)
     (** 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 : [>`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 : [>`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 shutdown : [>`W] t -> unit
     (** Shutdown a domain. *)
   val reboot : [>`W] t -> unit


@@ -491,12 +511,8 @@ sig
   val get_uuid_string : [>`R] t -> string
     (** Get the domain UUID (as a printable string). *)
   val get_id : [>`R] t -> int
   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
   val get_os_type : [>`R] t -> string
     (** Get the operating system type. *)
   val get_max_memory : [>`R] t -> int64


@@ -521,8 +537,6 @@ sig
     (** Undefine a domain - removes its configuration. *)
   val create : [>`W] t -> unit
     (** Launch a defined (inactive) domain. *)
     (** 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 get_autostart : [>`R] t -> bool
     (** Get the autostart flag for a domain. *)
   val set_autostart : [>`W] t -> bool -> unit


@@ -538,6 +552,10 @@ sig
        for a domain.  See the libvirt documentation for details
        of the array and bitmap returned from this function.
     *)
        for a domain.  See the libvirt documentation for details
        of the array and bitmap returned from this function.
     *)

+  val get_cpu_stats : [>`R] t -> typed_param list array
+    (** [get_pcpu_stats dom] returns the physical CPU stats
+       for a domain.  See the libvirt documentation for details.
+    *)

   val get_max_vcpus : [>`R] t -> int
     (** Returns the maximum number of vCPUs supported for this domain. *)
   val attach_device : [>`W] t -> xml -> unit
   val get_max_vcpus : [>`R] t -> int
     (** Returns the maximum number of vCPUs supported for this domain. *)
   val attach_device : [>`W] t -> xml -> unit


@@ -562,24 +580,52 @@ sig
   val interface_stats : [>`R] t -> string -> interface_stats
     (** Returns network interface stats. *)
 
   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.
 
        If successful then the data is written into [buf] starting
     (** [block_peek dom path offset size buf boff] reads [size] bytes at
        [offset] in the domain's [path] block device.
 
        If successful then the data is written into [buf] starting

-       at offset [boff], for [size] bytes. *)
-  val memory_peek : [>`R] t -> memory_flag list -> int64 -> int ->
+       at offset [boff], for [size] bytes.
+
+       See also {!max_peek}. *)
+  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.
 
        If successful then the data is written into [buf] starting
     string -> int -> unit
     (** [memory_peek dom Virtual offset size] reads [size] bytes
        at [offset] in the domain's virtual memory.
 
        If successful then the data is written into [buf] starting

-       at offset [boff], for [size] bytes. *)
+       at offset [boff], for [size] bytes.
+
+       See also {!max_peek}. *)

 
   external const : [>`R] t -> ro t = "%identity"
     (** [const dom] turns a read/write domain handle into a read-only
        domain handle.  Note that the opposite operation is impossible.
       *)
 
   external const : [>`R] t -> ro t = "%identity"
     (** [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. *)
 end
   (** Module dealing with domains.  [Domain.t] is the
       domain object. *)


@@ -601,16 +647,12 @@ sig
     (** Lookup a network by UUID string. *)
   val create_xml : [>`W] Connect.t -> xml -> rw t
     (** Create a network. *)
     (** 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 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
   val destroy : [>`W] t -> unit
     (** Destroy a network. *)
   val free : [>`R] t -> unit


@@ -708,7 +750,7 @@ sig
     (** Get the XML description. *)
   val get_autostart : [`R] t -> bool
     (** Get the autostart flag for the storage pool. *)
     (** Get the XML description. *)
   val get_autostart : [`R] t -> bool
     (** Get the autostart flag for the storage pool. *)

-  val set_autostart : [`W] t -> bool -> unit
+  val set_autostart : [>`W] t -> bool -> unit

     (** Set the autostart flag for the storage pool. *)
 
   val num_of_volumes : [`R] t -> int
     (** Set the autostart flag for the storage pool. *)
 
   val num_of_volumes : [`R] t -> int


@@ -761,9 +803,9 @@ sig
   val get_xml_desc : [`R] t -> xml
     (** Get the XML description. *)
 
   val get_xml_desc : [`R] t -> xml
     (** Get the XML description. *)
 

-  val create_xml : [`W] Pool.t -> xml -> unit
+  val create_xml : [>`W] Pool.t -> xml -> unit

     (** Create a storage volume. *)
     (** Create a storage volume. *)

-  val delete : [`W] t -> unit
+  val delete : [>`W] t -> vol_delete_flags -> unit

     (** Delete a storage volume. *)
   val free : [>`R] t -> unit
     (** Free a storage volume object in memory.
     (** Delete a storage volume. *)
   val free : [>`R] t -> unit
     (** Free a storage volume object in memory.


@@ -780,70 +822,6 @@ sig
 end
   (** Module dealing with storage volumes. *)
 
 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 :
 (** {3 Error handling and exceptions} *)
 
 module Virterror :


@@ -999,3 +977,16 @@ exception Not_supported of string
     See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
 *)
 
     See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
 *)
 

+(** {3 Utility functions} *)
+
+val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
+(** [map_ignore_errors f xs] calls function [f] for each element of [xs].
+
+    This is just like [List.map] except that if [f x] throws a
+    {!Virterror.t} exception, the error is ignored and [f x]
+    is not returned in the final list.
+
+    This function is primarily useful when dealing with domains which
+    might 'disappear' asynchronously from the currently running
+    program.
+*)