libvirt_ffi 0.4.0 → 0.5.3

data/lib/libvirt/domain.rb

@@ -2,10 +2,10 @@
 
 module Libvirt
   class Domain
-
     def self.load_ref(dom_ptr)
       ref_result = FFI::Domain.virDomainRef(dom_ptr)
-      raise Error, "Couldn't retrieve domain reference" if ref_result < 0
+      raise Errors::LibError, "Couldn't retrieve domain reference" if ref_result.negative?
+
       new(dom_ptr)
     end
 
@@ -13,9 +13,11 @@ module Libvirt
       @dom_ptr = dom_ptr
 
       free = ->(obj_id) do
+        Util.log(:debug) { "Finalize Libvirt::Domain 0x#{obj_id.to_s(16)} @dom_ptr=#{@dom_ptr}," }
         return unless @dom_ptr
+
         fr_result = FFI::Domain.virDomainFree(@dom_ptr)
-        STDERR.puts "Couldn't free Libvirt::Domain (0x#{obj_id.to_s(16)}) pointer #{@dom_ptr.address}" if fr_result < 0
+        warn "Couldn't free Libvirt::Domain (0x#{obj_id.to_s(16)}) pointer #{@dom_ptr.address}" if fr_result.negative?
       end
       ObjectSpace.define_finalizer(self, free)
     end
@@ -24,8 +26,11 @@ module Libvirt
       state = ::FFI::MemoryPointer.new(:int)
       reason = ::FFI::MemoryPointer.new(:int)
       result = FFI::Domain.virDomainGetState(@dom_ptr, state, reason, 0)
-      raise Error, "Couldn't get domain state" if result < 0
-      [state.read_int, reason.read_int]
+      raise Errors::LibError, "Couldn't get domain state" if result.negative?
+
+      state_sym = FFI::Domain.enum_type(:state)[state.read_int]
+      reason_sym = FFI::Domain.state_reason(state_sym, reason.read_int)
+      [state_sym, reason_sym]
     end
 
     def to_ptr
@@ -35,7 +40,8 @@ module Libvirt
     def uuid
       buff = ::FFI::MemoryPointer.new(:char, FFI::Domain::UUID_STRING_BUFLEN)
       result = FFI::Domain.virDomainGetUUIDString(@dom_ptr, buff)
-      raise Error, "Couldn't get domain uuid" if result < 0
+      raise Errors::LibError, "Couldn't get domain uuid" if result.negative?
+
       buff.read_string
     end
 
@@ -68,16 +74,115 @@ module Libvirt
     end
 
     def screenshot(stream, display = 0)
+      dbg { "#screenshot stream=#{stream}, display=#{display}," }
+
       mime_type, pointer = FFI::Domain.virDomainScreenshot(@dom_ptr, stream.to_ptr, display, 0)
-      raise Error, "Couldn't attach domain screenshot" if pointer.null?
+      raise Errors::LibError, "Couldn't attach domain screenshot" if pointer.null?
+
       # free pointer required
       mime_type
     end
 
     def free_domain
       result = FFI::Domain.virDomainFree(@dom_ptr)
-      raise Error, "Couldn't free domain" if result < 0
+      raise Errors::LibError, "Couldn't free domain" if result.negative?
+
       @dom_ptr = nil
     end
+
+    def start(flags = 0)
+      result = FFI::Domain.virDomainCreateWithFlags(@dom_ptr, flags)
+      raise Errors::LibError, "Couldn't start domain" if result.negative?
+    end
+
+    def reboot(flags = 0)
+      result = FFI::Domain.virDomainReboot(@dom_ptr, flags)
+      raise Errors::LibError, "Couldn't reboot domain" if result.negative?
+    end
+
+    def shutdown(flags = :ACPI_POWER_BTN)
+      result = FFI::Domain.virDomainShutdownFlags(@dom_ptr, flags)
+      raise Errors::LibError, "Couldn't shutdown domain" if result.negative?
+    end
+
+    def power_off(flags = 0)
+      result = FFI::Domain.virDomainDestroyFlags(@dom_ptr, flags)
+      raise Errors::LibError, "Couldn't power off domain" if result.negative?
+    end
+
+    def reset(flags = 0)
+      result = FFI::Domain.virDomainReset(@dom_ptr, flags)
+      raise Errors::LibError, "Couldn't reset domain" if result.negative?
+    end
+
+    def suspend
+      result = FFI::Domain.virDomainSuspend(@dom_ptr)
+      raise Errors::LibError, "Couldn't suspend domain" if result.negative?
+    end
+
+    def resume
+      result = FFI::Domain.virDomainResume(@dom_ptr)
+      raise Errors::LibError, "Couldn't resume domain" if result.negative?
+    end
+
+    # Undefine a domain.
+    # If the domain is running, it's converted to transient domain, without stopping it.
+    # If the domain is inactive, the domain configuration is removed.
+    # @param options_or_flags [Array<Symbol>,Hash{Symbol=>Boolean},Integer,Symbol,nil]
+    # @see Libvirt::FFI::Domain enum :undefine_flags_values for acceptable keys
+    # @see Libvirt::Util.parse_flags for possible argument values
+    # @raise [Libvirt::Errors::LibError] if operation failed
+    def undefine(options_or_flags = nil)
+      flags = Util.parse_flags options_or_flags, FFI::Domain.enum_type(:undefine_flags_values)
+      result = FFI::Domain.virDomainUndefineFlags(@dom_ptr, flags)
+      raise Errors::LibError, "Couldn't resume domain" if result.negative?
+    end
+
+    # After save_memory(:PAUSED) you need to call #start and #resume
+    # to move domain to the running state.
+    def save_memory(flags = :PAUSED)
+      result = FFI::Domain.virDomainManagedSave(@dom_ptr, flags)
+      raise Errors::LibError, "Couldn't save domain memory" if result.negative?
+    end
+
+    # Sets metadata
+    # @param metadata [String] xml node for element type, text for other types
+    #   DESCRIPTION 0x0 - Operate on <description>
+    #   TITLE 0x1 - Operate on <title>
+    #   ELEMENT 0x2 - Operate on <metadata>
+    # @param type [Integer,Symbol] one of :ELEMENT, :TITLE, :DESCRIPTION
+    # @param key [String] xml key (required for type element)
+    # @param uri [String] xml namespace (required for type element)
+    # @param flags [Integer,Symbol] one off AFFECT_CURRENT, AFFECT_CONFIG, AFFECT_LIVE
+    #   AFFECT_CURRENT 0x0 - Affect current domain state.
+    #   AFFECT_LIVE 0x1 - Affect running domain state.
+    #   AFFECT_CONFIG 0x2 - Affect persistent domain state.
+    # @raise [Libvirt::Errors::LibError] if operation failed
+    def set_metadata(metadata, type: :ELEMENT, key: nil, uri: nil, flags: :AFFECT_CURRENT)
+      result = FFI::Domain.virDomainSetMetadata(@dom_ptr, type, metadata, key, uri, flags)
+      raise Errors::LibError, "Couldn't set domain metadata" if result.negative?
+    end
+
+    # Retrieves metadata
+    # @param type [Integer,Symbol] one of :ELEMENT, :TITLE, :DESCRIPTION
+    # @param uri [String] xml namespace (required for type element)
+    # @param flags [Integer,Symbol] one off AFFECT_CURRENT, AFFECT_CONFIG, AFFECT_LIVE
+    #   AFFECT_CURRENT 0x0 - Affect current domain state.
+    #   AFFECT_LIVE 0x1 - Affect running domain state.
+    #   AFFECT_CONFIG 0x2 - Affect persistent domain state.
+    # @raise [Libvirt::Errors::LibError] if operation failed
+    # @return [String] xml node, title, or description.
+    def get_metadata(type: :ELEMENT, uri: nil, flags: :AFFECT_CURRENT)
+      result = FFI::Domain.virDomainGetMetadata(@dom_ptr, type, uri, flags)
+      raise Errors::LibError, "Couldn't get domain metadata" if result.nil?
+
+      result
+    end
+
+    private
+
+    def dbg(&block)
+      Util.log(:debug, 'Libvirt::Domain', &block)
+    end
   end
 end

data/lib/libvirt/domain_callback_storage.rb

@@ -1,6 +1,7 @@
+# frozen_string_literal: true
+
 module Libvirt
   class DomainCallbackStorage
-
     class CallbackDataStruct < ::FFI::Struct
       layout :connection_pointer, :pointer,
              :callback_id, :int
@@ -14,46 +15,43 @@ module Libvirt
     #   cb_data [Libvirt::DomainCallbackStorage::CallbackDataStruct],
     #   cb_data_free_func [FFI::Function]
     def allocate_struct
-      Util.logger.debug { "Libvirt::DomainCallbackStorage#allocate_struct" }
+      dbg { '#allocate_struct' }
 
       cb_data_ptr = ::FFI::MemoryPointer.new(:char, CallbackDataStruct.size, false)
       cb_data = CallbackDataStruct.new(cb_data_ptr)
-      cb_data_free_func = ::FFI::Function.new(:void, [:pointer]) do |pointer|
-        Util.logger.debug { "Libvirt::DomainCallbackStorage cb_data_free_func triggered" }
-        remove_struct(pointer: pointer)
+      cb_data_free_func = FFI::Common.free_function do |pointer|
+        dbg { 'Libvirt::DomainCallbackStorage cb_data_free_func triggered' }
+        remove_struct(pointer)
       end
       [cb_data, cb_data_free_func]
     end
 
     def store_struct(cb_data, connection_pointer:, callback_id:, cb:, opaque:)
-      Util.logger.debug { "Libvirt::DomainCallbackStorage#store_struct" }
+      dbg { '#store_struct' }
 
       cb_data[:connection_pointer] = connection_pointer
       cb_data[:callback_id] = callback_id
       @inner_storage[connection_pointer.address][callback_id] = { cb: cb, opaque: opaque, pointer: cb_data.pointer }
     end
 
-    def remove_struct(pointer: nil, connection_pointer: nil, callback_id: nil)
-      Util.logger.debug { "Libvirt::DomainCallbackStorage#remove_struct pointer=#{pointer}, connection_pointer=#{connection_pointer}, callback_id=#{callback_id}," }
+    def remove_struct(pointer)
+      dbg { "#remove_struct pointer=#{pointer}" }
 
-      if pointer
-        cb_data_struct = CallbackDataStruct.new(pointer)
-        connection_pointer = cb_data_struct[:connection_pointer]
-        callback_id = cb_data_struct[:callback_id]
-      end
+      cb_data_struct = CallbackDataStruct.new(pointer)
+      connection_pointer = cb_data_struct[:connection_pointer]
+      callback_id = cb_data_struct[:callback_id]
+      dbg { "#remove_struct pointer=#{pointer}, connection_pointer=#{connection_pointer}, callback_id=#{callback_id}," }
 
       cb_data = @inner_storage[connection_pointer.address].delete(callback_id)
-      pointer ||= cb_data[:pointer]
       @inner_storage.delete(connection_pointer.address) if @inner_storage[connection_pointer.address].empty?
 
-      #pointer.free
       cb_data[:opaque]
     end
 
     # @param [::FFI::Pointer]
     # @return [Array<2>] cb [Proc], opaque [Object]
     def retrieve_from_pointer(pointer)
-      Util.logger.debug { "Libvirt::DomainCallbackStorage#retrieve_from_pointer pointer=#{pointer}," }
+      dbg { "#retrieve_from_pointer pointer=#{pointer}," }
 
       cb_data_struct = CallbackDataStruct.new(pointer)
       connection_pointer = cb_data_struct[:connection_pointer]
@@ -61,5 +59,11 @@ module Libvirt
       cb_data = @inner_storage[connection_pointer.address][callback_id]
       [cb_data[:cb], cb_data[:opaque]]
     end
+
+    private
+
+    def dbg(&block)
+      Util.log(:debug, 'Libvirt::DomainCallbackStorage', &block)
+    end
   end
 end

data/lib/libvirt/errors.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Libvirt
+  module Errors
+    class Error < StandardError
+      # Generic error
+    end
+
+    class LibError < Error
+      # Object contains detailed error information retrieved from libvirt.
+
+      ERROR_FIELDS = [:code, :domain, :message, :level].freeze
+
+      attr_reader :client_message,
+                  :error_data,
+                  :error_code,
+                  :error_domain,
+                  :error_message,
+                  :error_level
+
+      # @param client_message [String, nil] optional client message
+      # When client_message ommited and virGetLastError return error
+      # message will be following: "ERROR_LEVEL: ERROR_NUMBER (ERROR_DOMAIN) ERROR_MESSAGE".
+      # When client message provided and virGetLastError return error
+      # message will be following: "CLIENT_MESSAGE\nERROR_LEVEL: ERROR_NUMBER (ERROR_DOMAIN) ERROR_MESSAGE".
+      # When client message is provided and virGetLastError return no error
+      # message will be following: "CLIENT_MESSAGE".
+      def initialize(client_message = nil)
+        @client_message = client_message
+        ptr = FFI::Error.virGetLastError
+        unless ptr.null?
+          struct = FFI::Error::Struct.new(ptr)
+          @error_data = struct.members.map { |m| [m, struct[m]] }.to_h
+          @error_code = error_data[:code]
+          @error_domain = error_data[:domain]
+          @error_message = error_data[:message]
+          @error_level = error_data[:level]
+        end
+
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        if error_data.nil?
+          client_message
+        elsif client_message.nil?
+          format '%<level>s: %<code>s (%<domain>s) %<message>s',
+                 level: error_level,
+                 code: error_code,
+                 domain: error_domain,
+                 message: error_message
+        else
+          format "%<client_message>s\n%<level>s: %<code>s (%<domain>s) %<message>s",
+                 client_message: client_message,
+                 level: error_level,
+                 code: error_code,
+                 domain: error_domain,
+                 message: error_message
+        end
+      end
+    end
+  end
+end

data/lib/libvirt/event.rb

@@ -21,19 +21,19 @@ module Libvirt
 
     attr_accessor :debug
 
-    Opaque = Struct.new(:cb, :opaque, :ff)
+    Opaque = Struct.new(:cb, :opaque, :free_func)
 
     def invoke_handle_callback(watch, fd, events, opaque)
       cb = opaque.cb
       op = opaque.opaque
-      dbg { "Libvirt::Event INVOKE_HANDLE_CALLBACK watch=#{watch} fd=#{fd} events=#{events} op=#{op}" }
+      dbg { "INVOKE_HANDLE_CALLBACK watch=#{watch} fd=#{fd} events=#{events} op=#{op}" }
       cb.call(watch, fd, events, op)
     end
 
     def invoke_timeout_callback(timer, opaque)
       cb = opaque.cb
       op = opaque.opaque
-      dbg { "Libvirt::Event INVOKE_TIMEOUT_CALLBACK timer=#{timer} op=#{op}" }
+      dbg { "INVOKE_TIMEOUT_CALLBACK timer=#{timer} op=#{op}" }
       cb.call(timer, op)
     end
 
@@ -59,20 +59,25 @@ module Libvirt
       true
     end
 
-    def register(add_handle:, update_handle:, remove_handle:, add_timer:, update_timer:, remove_timer:)
+    def schedule_operation(&block)
+      @schedule.call(&block)
+    end
+
+    def register(add_handle:, update_handle:, remove_handle:, add_timer:, update_timer:, remove_timer:, schedule:) # rubocop:disable Metrics/ParameterLists
       @add_handle = add_handle
       @update_handle = update_handle
       @remove_handle = remove_handle
       @add_timer = add_timer
       @update_timer = update_timer
       @remove_timer = remove_timer
+      @schedule = schedule
 
-      @add_handle_cb = FFI::Event.event_add_handle_func(&method(:_add_handle).to_proc)
-      @update_handle_cb = ::FFI::Function.new(:void, [:int, :int], &method(:_update_handle).to_proc)
-      @remove_handle_cb = ::FFI::Function.new(:int, [:int], &method(:_remove_handle).to_proc)
-      @add_timer_cb = FFI::Event.event_add_timeout_func(&method(:_add_timer).to_proc)
-      @update_timer_cb = ::FFI::Function.new(:void, [:int, :int], &method(:_update_timer).to_proc)
-      @remove_timer_cb = ::FFI::Function.new(:int, [:int], &method(:_remove_timer).to_proc)
+      @add_handle_cb = FFI::Event.callback_function(:virEventAddHandleFunc, &method(:_add_handle))
+      @update_handle_cb = FFI::Event.callback_function(:virEventUpdateHandleFunc, &method(:_update_handle))
+      @remove_handle_cb = FFI::Event.callback_function(:virEventRemoveHandleFunc, &method(:_remove_handle))
+      @add_timer_cb = FFI::Event.callback_function(:virEventAddTimeoutFunc, &method(:_add_timer))
+      @update_timer_cb = FFI::Event.callback_function(:virEventUpdateTimeoutFunc, &method(:_update_timer))
+      @remove_timer_cb = FFI::Event.callback_function(:virEventRemoveTimeoutFunc, &method(:_remove_timer))
 
       FFI::Event.virEventRegisterImpl(
           @add_handle_cb,
@@ -87,51 +92,54 @@ module Libvirt
 
     private
 
-    def _add_handle(fd, event, cb, opaque, ff)
-      dbg { "Libvirt::Event ADD_HANDLE fd=#{fd}, #{event}=event, cb=#{cb}, opaque=#{opaque}, ff=#{ff}" }
-      op = Opaque.new(cb, opaque, ff)
+    def _add_handle(fd, event, cb, opaque, free_func)
+      dbg { "ADD_HANDLE fd=#{fd}, #{event}=event, cb=#{cb}, opaque=#{opaque}, free_func=#{free_func}" }
+      op = Opaque.new(cb, opaque, free_func)
       @add_handle.call(fd, event, op)
     end
 
     def _update_handle(watch, event)
-      dbg { "Libvirt::Event UPDATE_HANDLE watch=#{watch}, event=#{event}" }
+      dbg { "UPDATE_HANDLE watch=#{watch}, event=#{event}" }
       @update_handle.call(watch, event)
     end
 
     def _remove_handle(watch)
-      dbg { "Libvirt::Event REMOVE_HANDLE watch=#{watch}" }
+      dbg { "REMOVE_HANDLE watch=#{watch}" }
       op = @remove_handle.call(watch)
-      free_func = op.ff
+      free_func = op.free_func
       opaque = op.opaque
-      free_func.call(opaque) unless free_func.null?
+      schedule_operation do
+        dbg { "REMOVE_HANDLE delayed free_func watch=#{watch}" }
+        free_func.call(opaque) unless free_func.null?
+      end
       0
     end
 
-    def _add_timer(timeout, cb, opaque, ff)
-      dbg { "Libvirt::Event ADD_TIMER timeout=#{timeout}, cb=#{cb}, opaque=#{opaque}, ff=#{ff}" }
-      op = Opaque.new(cb, opaque, ff)
+    def _add_timer(timeout, cb, opaque, free_func)
+      dbg { "ADD_TIMER timeout=#{timeout}, cb=#{cb}, opaque=#{opaque}, free_func=#{free_func}" }
+      op = Opaque.new(cb, opaque, free_func)
       @add_timer.call(timeout, op)
     end
 
     def _update_timer(timer, timeout)
-      dbg { "Libvirt::Event UPDATE_TIMER timer=#{timer}, timeout=#{timeout}" }
+      dbg { "UPDATE_TIMER timer=#{timer}, timeout=#{timeout}" }
       @update_timer.call(timer, timeout)
     end
 
     def _remove_timer(timer)
-      dbg { "Libvirt::Event REMOVE_TIMER timer=#{timer}" }
+      dbg { "REMOVE_TIMER timer=#{timer}" }
       op = @remove_timer.call(timer)
-      free_func = op.ff
+      free_func = op.free_func
       opaque = op.opaque
-      free_func.call(opaque) unless free_func.null?
+      schedule_operation do
+        dbg { "REMOVE_TIMER async free_func timer=#{timer}" }
+        free_func.call(opaque) unless free_func.null?
+      end
       0
     end
 
     def dbg(&block)
-      return unless debug
-
-      Util.log(:debug, &block)
+      Util.log(:debug, 'Libvirt::Event', &block)
     end
-
   end
 end

data/lib/libvirt/ffi.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Libvirt
+  module FFI
+    # https://libvirt.org/html/index.html
+    # namespace for libvirt C bindings
+
+    require 'libvirt/ffi/helpers'
+    require 'libvirt/ffi/common'
+    require 'libvirt/ffi/error'
+    require 'libvirt/ffi/host'
+    require 'libvirt/ffi/domain'
+    require 'libvirt/ffi/event'
+    require 'libvirt/ffi/stream'
+    require 'libvirt/ffi/storage'
+  end
+end