X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;ds=sidebyside;f=libvirt%2Flibvirt.mli;h=018540218e79564fd8e6189d9eda9bcc3d87c25f;hb=d7e0e6112db9411b0d7aaa8cbf5ce85c27e7d52d;hp=89c6d9047c2ca6904a755920db70dd277632c244;hpb=6de624657b83a1792cf21393cb71f61a446a9c52;p=ocaml-libvirt.git diff --git a/libvirt/libvirt.mli b/libvirt/libvirt.mli index 89c6d90..0185402 100644 --- 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: -{v +{[ module C = Libvirt.Connect module D = Libvirt.Domain module N = Libvirt.Network -v} +]} To get a connection handle, assuming a Xen hypervisor: -{v +{[ let name = "xen:///" let conn = C.connect_readonly ~name () -v} +]} {3 Example: List running domains} -{v +{[ 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; -v} +]} {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} -{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; @@ -117,7 +114,7 @@ printf "hostname = %s\n%!" hostname; 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. - 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} - 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} @@ -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: -{v +{[ 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} *) @@ -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. + 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. *) @@ -305,7 +311,12 @@ sig (** [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]. + + See also: + {!Libvirt.Domain.get_domains}, + {!Libvirt.Domain.get_domains_and_infos}. *) val num_of_networks : [>`R] t -> int (** Returns the number of networks. *) @@ -395,7 +406,7 @@ sig | 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 *) @@ -417,10 +428,22 @@ sig | 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 list_flag = + | ListActive + | ListInactive + | ListAll + type block_stats = { rd_req : int64; rd_bytes : int64; @@ -440,12 +463,15 @@ sig 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_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 @@ -470,16 +496,10 @@ sig (** 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 @@ -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 - (** [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 @@ -521,8 +537,6 @@ sig (** 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 @@ -538,6 +552,10 @@ sig 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 @@ -562,24 +580,52 @@ sig 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 - 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 - 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. *) + + 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. *) @@ -601,16 +647,12 @@ sig (** 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 @@ -708,7 +750,7 @@ sig (** 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 @@ -761,9 +803,9 @@ sig 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. *) - 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. @@ -780,70 +822,6 @@ sig 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 : @@ -999,3 +977,16 @@ exception Not_supported of string 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. +*)