libvirt 0.1.0

data/lib/libvirt/domain.rb

@@ -0,0 +1,241 @@
+module Libvirt
+  # Represents a domain within libvirt, which is a single virtual
+  # machine or environment, typically.
+  class Domain
+    # Initializes a new {Domain} object. If you're calling this directly,
+    # omit the `pointer` argument, since that is meant for internal use.
+    def initialize(pointer=nil)
+      @pointer = pointer if pointer.is_a?(FFI::Pointer)
+      ObjectSpace.define_finalizer(self, method(:finalize))
+    end
+
+    # Returns the name of the domain as a string.
+    #
+    # @return [String]
+    def name
+      FFI::Libvirt.virDomainGetName(self)
+    end
+
+    # Returns the UUID of the domain as a string.
+    #
+    # @return [String]
+    def uuid
+      output_ptr = FFI::MemoryPointer.new(:char, 36)
+      FFI::Libvirt.virDomainGetUUIDString(self, output_ptr)
+      output_ptr.read_string
+    end
+
+    # Returns the hypervisor ID number for this domain.
+    #
+    # @return [Integer]
+    def id
+      FFI::Libvirt.virDomainGetID(self)
+    end
+
+    # Returns the OS type of the domain.
+    #
+    # @return [String]
+    def os_type
+      FFI::Libvirt.virDomainGetOSType(self)
+    end
+
+    # Returns the current state this domain is in.
+    #
+    # @return [Symbol]
+    def state
+      domain_info[:state]
+    end
+
+    # Returns the maximum memory (in KB) allowed on this domain.
+    #
+    # @return [Integer]
+    def max_memory
+      domain_info[:maxMem]
+    end
+
+    # Sets the maximum memory (in KB) allowed on this domain.
+    #
+    # @return [Boolean] Success of the command.
+    def max_memory=(value)
+      FFI::Libvirt.virDomainSetMaxMemory(self, value) == 0
+    end
+
+    # Returns the memory (in KB) currently allocated to this domain.
+    #
+    # @return [Integer]
+    def memory
+      domain_info[:memory]
+    end
+
+    # Sets the memory (in KB) on an active domain.
+    #
+    # @return [Boolean] Success of the command.
+    def memory=(value)
+      FFI::Libvirt.virDomainSetMemory(self, value) == 0
+    end
+
+    # Returns the number of virtual CPUs for this domain.
+    #
+    # @return [Integer]
+    def virtual_cpus
+      domain_info[:nrVirtCpu]
+    end
+
+    # Sets the number of virtual CPUs for this domain.
+    #
+    # @return [Boolean] Success of the command.
+    def virtual_cpus=(value)
+      FFI::Libvirt.virDomainSetVcpus(self, value) == 0
+    end
+
+    # Returns the maximum number of virtual CPUs supported for this guest
+    # VM.
+    #
+    # @return [Integer]
+    def max_virtual_cpus
+      FFI::Libvirt.virDomainGetMaxVcpus(self)
+    end
+
+    # Returns the CPU time used in nanoseconds.
+    #
+    # @return [Integer]
+    def cpu_time_used
+      domain_info[:cpuTime]
+    end
+
+    # Returns the XML description of this domain.
+    #
+    # @return [String]
+    def xml
+      # TODO: The flags in the 2nd parameter
+      FFI::Libvirt.virDomainGetXMLDesc(self, 0)
+    end
+
+    # Returns boolean of whether the domain is active (running) or not.
+    #
+    # @return [Boolean]
+    def active?
+      result = FFI::Libvirt.virDomainIsActive(self)
+      return nil if result == -1
+      result == 1
+    end
+
+    # Returns boolean of whether the domain is persistent, or whether it
+    # will still exist after it is shut down.
+    #
+    # @return [Boolean]
+    def persistent?
+      result = FFI::Libvirt.virDomainIsPersistent(self)
+      return nil if result == -1
+      result == 1
+    end
+
+    # Returns boolean of whether the domain autostarts on boot.
+    #
+    # @return [Boolean]
+    def autostart?
+      output_ptr = FFI::MemoryPointer.new(:int)
+      return nil if FFI::Libvirt.virDomainGetAutostart(self, output_ptr) < 0
+      output_ptr.read_int == 1
+    end
+
+    # Sets the autostart status. This assignment sets the value immediately
+    # on the domain.
+    #
+    # @param [Boolean] value
+    # @return [Boolean] The set value
+    def autostart=(value)
+      FFI::Libvirt.virDomainSetAutostart(self, value ? 1 : 0)
+      value
+    end
+
+    # Starts the domain (moves it from the inactive to running state), and
+    # returns a boolean of whether the call succeeded or not.
+    #
+    # @return [Boolean]
+    def create
+      return true if active?
+      FFI::Libvirt.virDomainCreate(self) == 0
+    end
+    alias :start :create
+
+    # Stops a running domain and returns a boolean of whether the call succeeded
+    # or not.
+    #
+    # @return [Boolean]
+    def destroy
+      FFI::Libvirt.virDomainDestroy(self) == 0
+    end
+    alias :stop :destroy
+
+    # Suspends an active domain, the process is frozen but the memory is still
+    # allocated. Returns a boolean of whether the call succeeded or not.
+    #
+    # @return [Boolean]
+    def suspend
+      FFI::Libvirt.virDomainSuspend(self) == 0
+    end
+
+    # Resumes a suspended domain, returns a boolean of whether the call
+    # succeeded or not.
+    #
+    # @return [Boolean]
+    def resume
+      return true if active?
+      FFI::Libvirt.virDomainResume(self) == 0
+    end
+
+    # Reboots the domain.
+    #
+    # @return [Boolean]
+    def reboot
+      FFI::Libvirt.virDomainReboot(self, 0) == 0
+    end
+
+    # Shutdown a domain, stopping the domain OS.
+    #
+    # @return [Boolean]
+    def shutdown
+      FFI::Libvirt.virDomainShutdown(self) == 0
+    end
+
+    # Undefine a domain. This will not stop it if it is running.
+    #
+    # @return [Boolean]
+    def undefine
+      FFI::Libvirt.virDomainUndefine(self) == 0
+    end
+
+    # Provides the pointer to the domain. This allows this object to be used
+    # directly with the FFI layer which expects a `virDomainPtr`.
+    #
+    # @return [FFI::Pointer]
+    def to_ptr
+      @pointer
+    end
+
+    # Provide a meaningful equality check so that two domains can easily
+    # be checked for equality. This works by comparing UUIDs.
+    #
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(Domain) && other.uuid == uuid
+    end
+
+    protected
+
+    # Queries the domain info from libvirt to get standard information
+    # about this domain.
+    def domain_info
+      result = FFI::Libvirt::DomainInfo.new
+      FFI::Libvirt.virDomainGetInfo(self, result.to_ptr)
+      result
+    end
+
+    # Cleans the `virDomainPtr` underlying the class when the class is
+    # released.
+    def finalize(*args)
+      FFI::Libvirt.virDomainFree(self)
+    end
+  end
+end

data/lib/libvirt/error.rb

@@ -0,0 +1,91 @@
+module Libvirt
+  # Represents the actual `libvirt` error object which most erroneous
+  # events set. This contains important information such as the message,
+  # domain, etc.
+  class Error
+    @@error_block = nil
+    @@raise_errors = true
+
+    attr_reader :interface
+
+    class << self
+      # Gets the last error (if there is one) and returns the {Error}
+      # representing it.
+      #
+      # @return [Error]
+      def last_error
+        pointer = FFI::Libvirt.virGetLastError
+        return nil if pointer.null?
+        new(pointer)
+      end
+
+      # Sets an error handling function. This will call the given block
+      # whenever an error occurs within libvirt.
+      def on_error(&block)
+        @@error_block = block
+      end
+
+      # Returns whether or not Libvirt is currently configured to raise
+      # errors automatically when it is reported.
+      #
+      # @return [Boolean]
+      def raise_errors; @@raise_errors; end
+
+      # Set this to a boolean true/false to control whether the library
+      # automatically raises {Exception::LibvirtError} whenever an error
+      # occurs.
+      #
+      # @param [Boolean] value
+      def raise_errors=(value)
+        @@raise_errors = !!value
+      end
+
+      protected
+
+      def error_handler(userdata, error_ptr)
+        error_object = new(error_ptr)
+        @@error_block.call(error_object) if @@error_block
+
+        # Raise the exception
+        raise Exception::LibvirtError, error_object if @@raise_errors
+      end
+    end
+
+    # This proc needs to be assigned to a constant so that it is never GC'd
+    # and can be assigned as a callback to the API.
+    ERROR_HANDLER_PROC = method(:error_handler)
+    FFI::Libvirt.virSetErrorFunc(nil, ERROR_HANDLER_PROC)
+
+    # Initializes a new error object. This shouldn't be called publicly.
+    # Instead use {last_error} or obtain the error from any of the exceptions
+    # which the library raises.
+    def initialize(pointer)
+      @interface = FFI::Libvirt::Error.new(pointer)
+    end
+
+    # Returns the error code of the error. Internally, this is represented
+    # by a C `enum`, so this will actually return a Ruby `Symbol` representation
+    # of the error.
+    #
+    # @return [Symbol]
+    def code
+      interface[:code]
+    end
+
+    # Returns the domain or "category" in which this error occured. This
+    # is represented internally as a C `enum`, so this will actually return
+    # a Ruby `symbol`.
+    #
+    # @return [Symbol]
+    def domain
+      interface[:domain]
+    end
+
+    # Returns a human-friendly message related to the error.
+    #
+    # @return [String]
+    def message
+      interface[:message]
+    end
+  end
+end

data/lib/libvirt/exception.rb

@@ -0,0 +1,19 @@
+module Libvirt
+  # Contains all the potential exceptions which the library can
+  # throw. This is different from a {Libvirt::Error}, which represents
+  # an actual `libvirt` error object.
+  module Exception
+    # Represents an exceptional event within the Libvirt library.
+    # This contains an `error` readable attribute which, if available,
+    # is a {Libvirt::Error} object, which contains more details
+    # about the error which occurred.
+    class LibvirtError < StandardError
+      attr_reader :error
+
+      def initialize(error)
+        @error = error
+        super(error.message)
+      end
+    end
+  end
+end

data/lib/libvirt/network.rb

@@ -0,0 +1,118 @@
+module Libvirt
+  # Represents a network within libvirt, which is a network interface
+  # such as a host-only network for VirtualBox, for example.
+  class Network
+    # Initializes a new {Network} object given a `virNetworkPtr`. Please
+    # do not call this directly. Instead, use the {Connection#networks}
+    # object.
+    def initialize(pointer)
+      @pointer = pointer
+      ObjectSpace.define_finalizer(self, method(:finalize))
+    end
+
+    # Returns the name of the network as a string.
+    #
+    # @return [String]
+    def name
+      FFI::Libvirt.virNetworkGetName(self)
+    end
+
+    # Returns the XML descriptions of this network.
+    #
+    # @return [String]
+    def xml
+      FFI::Libvirt.virNetworkGetXMLDesc(self, 0)
+    end
+
+    # Returns the UUID of the network as a string.
+    #
+    # @return [String]
+    def uuid
+      output_ptr = FFI::MemoryPointer.new(:char, 36)
+      FFI::Libvirt.virNetworkGetUUIDString(self, output_ptr)
+      output_ptr.read_string
+    end
+
+    # Returns the bridge that this network is attached to.
+    #
+    # @return [String]
+    def bridge
+      FFI::Libvirt.virNetworkGetBridgeName(self)
+    end
+
+    # Determine if the network is set to autostart on boot or not.
+    #
+    # @return [Boolean]
+    def autostart?
+      output_ptr = FFI::MemoryPointer.new(:int)
+      return nil if FFI::Libvirt.virNetworkGetAutostart(self, output_ptr) < 0
+      output_ptr.read_int == 1
+    end
+
+    # Set the autostart value on the network.
+    #
+    # @return [Boolean]
+    def autostart=(value)
+      FFI::Libvirt.virNetworkSetAutostart(self, value ? 1 : 0)
+      value
+    end
+
+    # Determine if the network is active or not.
+    #
+    # @return [Boolean]
+    def active?
+      FFI::Libvirt.virNetworkIsActive(self) == 1
+    end
+
+    # Determine if the network is persistent or not.
+    #
+    # @return [Boolean]
+    def persistent?
+      FFI::Libvirt.virNetworkIsPersistent(self) == 1
+    end
+
+    # Starts a network.
+    def create
+      FFI::Libvirt.virNetworkCreate(self)
+    end
+    alias :start :create
+
+    # Stops a network.
+    def destroy
+      FFI::Libvirt.virNetworkDestroy(self)
+    end
+    alias :stop :destroy
+
+    # Undefines the network, but will not stop it if it is
+    # running.
+    def undefine
+      FFI::Libvirt.virNetworkUndefine(self)
+    end
+
+    # Converts to the actual `virNetworkPtr` of this structure. This allows
+    # this object to be used directly with the FFI layer which expects a
+    # `virNetworkPtr`.
+    #
+    # @return [FFI::Pointer]
+    def to_ptr
+      @pointer
+    end
+
+    # Provide a meaningful equality check for two networks by comparing
+    # UUID.
+    #
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(Network) && other.uuid == uuid
+    end
+
+    protected
+
+    # Cleans up the `virNetworkPtr` and releases the resources associated
+    # with it. This is automatically called when this object is garbage
+    # collected.
+    def finalize(*args)
+      FFI::Libvirt.virNetworkFree(self)
+    end
+  end
+end

data/lib/libvirt/node.rb

@@ -0,0 +1,118 @@
+module Libvirt
+  # Represents a node which libvirt resides on.
+  class Node
+    # Initializes a node object with the given {Connection} pointer. This
+    # shouldn't be called directly. Instead, retrieve the node using
+    # {Connection#node}.
+    def initialize(pointer)
+      # This pointer can either be a `virConnectPtr` directly or a
+      # {Connection} since it implements `to_ptr`.
+      @pointer = pointer
+
+      # We increase the reference count on the connection while this
+      # node object is in use.
+      FFI::Libvirt.virConnectRef(connection)
+
+      # Register finalizer for reference cleanup
+      ObjectSpace.define_finalizer(self, method(:finalize))
+    end
+
+    # Returns the connection this node belongs to as a {Connection}
+    # object.
+    #
+    # @return [Connection]
+    def connection
+      @connection ||= @pointer.is_a?(Connection) ? @pointer : Connection.new(@pointer)
+    end
+
+    # Returns the devices connected to this node.
+    #
+    # @return [Collection::NodeDeviceCollection]
+    def devices
+      Collection::NodeDeviceCollection.new(connection)
+    end
+
+    # Returns the free memory available on the node. This is returned
+    # in bytes.
+    #
+    # @return [Integer]
+    def free_memory
+      FFI::Libvirt.virNodeGetFreeMemory(connection)
+    end
+
+    # Returns the CPU model of the node.
+    #
+    # @return [String]
+    def cpu_model
+      info[:model]
+    end
+
+    # Returns the memory size in kilobytes.
+    #
+    # @return [Integer]
+    def memory
+      info[:memory]
+    end
+
+    # Returns the number of active CPUs.
+    #
+    # @return [Integer]
+    def cpus
+      info[:cpus]
+    end
+
+    # Returns the expected CPU frequency in MHz.
+    #
+    # @return [Integer]
+    def mhz
+      info[:mhz]
+    end
+
+    # Returns the number of NUMA cell, 1 for uniform memory access.
+    #
+    # @return [Integer]
+    def nodes
+      info[:nodes]
+    end
+
+    # Returns the number of CPU sockets per node.
+    #
+    # @return [Integer]
+    def sockets
+      info[:sockets]
+    end
+
+    # Returns the number of cores per socket.
+    #
+    # @return [Integer]
+    def cores
+      info[:cores]
+    end
+
+    # Returns the number of threads per core.
+    #
+    # @return [Integer]
+    def threads
+      info[:threads]
+    end
+
+    protected
+
+    # Returns the {FFI::Libvirt::NodeInfo} structure associated with this
+    # node. The various fields of this structure are accessed using the
+    # other methods in this class.
+    #
+    # @return [FFI::Libvirt::NodeInfo]
+    def info
+      result = FFI::Libvirt::NodeInfo.new
+      FFI::Libvirt.virNodeGetInfo(connection, result.to_ptr)
+      result
+    end
+
+    # Releases the reference to the underlying connection structure.
+    # This is automatically called when the object is garbage collected.
+    def finalize(*args)
+      FFI::Libvirt.virConnectClose(connection)
+    end
+  end
+end

data/lib/libvirt/node_device.rb

@@ -0,0 +1,75 @@
+module Libvirt
+  # Represents a device on a node.
+  class NodeDevice
+    # Initializes a node device with the given `virNodeDevicePtr`. This
+    # should not be called directly. Instead, call {Node#devices} to get
+    # a list of the devices.
+    #
+    # @param [FFI::Pointer] pointer
+    def initialize(pointer)
+      @pointer = pointer
+      ObjectSpace.define_finalizer(self, method(:finalize))
+    end
+
+    # Returns the name of this device.
+    #
+    # @return [String]
+    def name
+      FFI::Libvirt.virNodeDeviceGetName(self)
+    end
+
+    # Returns the XML specification for this device.
+    #
+    # @return [String]
+    def xml
+      FFI::Libvirt.virNodeDeviceGetXMLDesc(self, 0)
+    end
+
+    # Detaches the device from the node itself so that it may be bound to
+    # a guest domain.
+    #
+    # @return [Boolean]
+    def dettach
+      FFI::Libvirt.virNodeDeviceDettach(self) == 0
+    end
+
+    # Reattach the device onto the node.
+    #
+    # @return [Boolena]
+    def reattach
+      FFI::Libvirt.virNodeDeviceReAttach(self) == 0
+    end
+
+    # Reset the device. The exact semantics of this method are hypervisor
+    # specific.
+    #
+    # @return [Boolena]
+    def reset
+      FFI::Libvirt.virNodeDeviceReset(self) == 0
+    end
+
+    # Destroy the device, removing the virtual device from the host operating
+    # system.
+    #
+    # @return [Boolean]
+    def destroy
+      FFI::Libvirt.virNodeDeviceDestroy(self) == 0
+    end
+
+    # Returns the underlying `virNodeDevicePtr`. This allows this object to
+    # be used directly with FFI methods.
+    #
+    # @return [FFI::Pointer]
+    def to_ptr
+      @pointer
+    end
+
+    protected
+
+    # Frees the underlying resources of the node device. This is called
+    # automatically when this object is garbage collected.
+    def finalize(*args)
+      FFI::Libvirt.virNodeDeviceFree(self)
+    end
+  end
+end