libvirt_async 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b24efe4c5438e07c1fbc9fac06b82493e242deb7
-  data.tar.gz: c49f812826b3e2275065f52f587a29ef3dec95ae
+SHA256:
+  metadata.gz: e2b8dda8105b9fe625c1d8bf71634ad66d1dca7507315c09e340eab1b9cfbde5
+  data.tar.gz: 5dc290b2014113e4ad84f3ed36dc4afbe177c95a1124948c2efd47a689062078
 SHA512:
-  metadata.gz: cbb0387eabbed0bd926268e62e7995fead38c42e5ee7b01f663e24d03f41c165cf54c219d17102842d4d6a98d6ba18d0f0c91ea4f43b61b57fe31877c80e4af4
-  data.tar.gz: deb1c6f89322e867a97da6b4d3e7e694b515b9f5e9c7edaced04865cf18b386ef946aafae8eaf502fd89ad84329449c79195dcfef06a90a248edcfb6942abdef
+  metadata.gz: 645fdff4cfe5c25e405ee02c49fa3c15c1a4ae6ad58922cd4ded7a14215ede30559480a6f2712d384d1268d49ff8eda4dd916ce2332d749a46a3f49d7c0907d3
+  data.tar.gz: 5cf5d9a3b65a5e019e420298f98d8acd2c6480b2eb9b29867a4c42e8111987ed67c7abeef27f4cbaa2786384da97ae746043c3a5c69c95651d844f6ae0995cdc

data/CHANGELOG.md

@@ -1,11 +1,13 @@
 # Changelog
 
 ## Unreleased
+- Add StreamRead for working with non-block streams in read mode
+- Improve README
 
 ## 0.1.1
-- fix async tasks hierarchy
+- Fix async tasks hierarchy
 
 ## 0.1.0
 
-- register implementations
-- debug logging
+- Register implementations
+- Debug logging

data/README.md

@@ -1,7 +1,9 @@
 # LibvirtAsync
 
-Libvirt event async implementation.
-Libvirt event api implementation on Fibers based on [libvirt-ruby](https://github.com/qwe/libvirt-ruby) and [async](https://github.com/socketry/async)
+Libvirt event loop asynchronous implementation on Fibers.
+Based on [libvirt-ruby](https://github.com/qwe/libvirt-ruby) and [async](https://github.com/socketry/async).
+Allows to receive domain events.
+Allows to work with streams in asynchronous mode.
 
 ## Installation
 
@@ -21,21 +23,133 @@ Or install it yourself as:
 
 ## Usage
 
+`LibvirtAsync.register_implementations!` must be called once per process before connecting to hypervisor.
+
+### Receiving domain events
+
+We can subscribe for event from all hypervisor's domains 
 ```ruby
 require 'libvirt_async'
 
-LibvirtAsync.use_logger!
-LibvirtAsync.logger.level = Logger::Severity::DEBUG # optional for debugging
 LibvirtAsync.register_implementations!
+
+connection = Libvirt::open('qemu+tcp://127.0.0.1:16509')
+
+some_object = Object.new
+
+connection.domain_event_register_any(
+    Libvirt::Connect::DOMAIN_EVENT_ID_LIFECYCLE,
+    ->(connection, domain, event, detail, opaque) { 
+      puts "LIFECYCLE event #{domain.uuid} #{event} #{detail}" 
+    },
+    nil, # optional domain, can be omitted
+    some_object # will be an opaque in callback, can be omitted
+)
 ```
 
-## Development
+Or we can subscribe on particular domain
+
+```ruby
+require 'libvirt_async'
+
+LibvirtAsync.register_implementations!
+
+connection = Libvirt::open('qemu+tcp://127.0.0.1:16509')
+domain = connection.list_all_domains.first
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. 
-You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+some_object = Object.new
+
+connection.domain_event_register_any(
+    Libvirt::Connect::DOMAIN_EVENT_ID_LIFECYCLE,
+    ->(connection, domain, event, detail, opaque) { 
+      puts "LIFECYCLE event #{domain.uuid} #{event} #{detail}" 
+    },
+    domain, 
+    some_object # will be an opaque in callback, can be omitted
+)
+```
+
+All available domain events:
+```ruby
+connection.domain_event_register_any(
+    Libvirt::Connect::DOMAIN_EVENT_ID_REBOOT,
+    ->(connection, domain, opaque) { 
+      puts "REBOOT event #{domain.uuid}" 
+    }
+)
+
+connection.domain_event_register_any(
+    Libvirt::Connect::DOMAIN_EVENT_ID_RTC_CHANGE,
+    ->(connection, domain, utc_offset, opaque) { 
+      puts "RTC_CHANGE event #{domain.uuid} #{utc_offset}" 
+    }
+)
+
+connection.domain_event_register_any(
+    Libvirt::Connect::DOMAIN_EVENT_ID_WATCHDOG,
+    ->(connection, domain, action, opaque) { 
+      puts "WATCHDOG event #{domain.uuid} #{action}" 
+    }
+)
+
+connection.domain_event_register_any(
+    Libvirt::Connect::DOMAIN_EVENT_ID_IO_ERROR,
+    ->(connection, domain, src_path, dev_alias, action, opaque) { 
+      puts "IO_ERROR event #{domain.uuid} #{src_path} #{dev_alias} #{action}" 
+    }
+)
+
+connection.domain_event_register_any(
+    Libvirt::Connect::DOMAIN_EVENT_ID_IO_ERROR_REASON,
+    ->(connection, domain, src_path, dev_alias, action, opaque) { 
+      puts "IO_ERROR_REASON event #{domain.uuid} #{src_path} #{dev_alias} #{action}" 
+    }
+)
+
+connection.domain_event_register_any(
+    Libvirt::Connect::DOMAIN_EVENT_ID_GRAPHICS,
+    ->(connection, domain, phase, local, remote, auth_scheme, subject, opaque) { 
+      puts "GRAPHICS event #{domain.uuid} #{phase} #{local} #{remote} #{auth_scheme} #{subject}" 
+    }
+)
+```
+
+### Taking screenshot
+
+```ruby
+require 'libvirt_async'
+
+LibvirtAsync.register_implementations!
+
+connection = Libvirt::open('qemu+tcp://127.0.0.1:16509')
+domain = connection.list_all_domains.first
+
+file = File.new("/screenshots/#{domain.uuid}.pnm", 'wb')
+stream = LibvirtAsync::StreamRead.new(connection, file)
+mime_type = domain.screenshot(stream.stream, 0)
+puts "screenshot saving initiated mime_type=#{mime_type}"
+
+# will start screenshot saving
+stream.call do |success, reason, io|
+  # this block will be called asynchronously on complete or error
+  io.close
+  if success
+   puts "screenshot saved at #{io.path}"
+  else
+   puts "screenshot was not saved: #{reason}"
+  end
+end
+```
+
+Logging.
+```ruby
+require 'libvirt_async'
+
+LibvirtAsync.use_logger!
+LibvirtAsync.logger.level = Logger::Severity::DEBUG # for debugging
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. 
-To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Look at [ruby-libvirt Documenation](https://libvirt.org/ruby/documentation.html) for further details.
 
 ## Contributing
 

data/lib/libvirt_async.rb

@@ -2,6 +2,7 @@ require 'libvirt_async/version'
 require 'libvirt_async/error'
 require 'libvirt_async/log_formatter'
 require 'libvirt_async/implementations'
+require 'libvirt_async/stream_read'
 
 module LibvirtAsync
   def register_implementations!

data/lib/libvirt_async/stream_read.rb

@@ -0,0 +1,144 @@
+module LibvirtAsync
+  class StreamRead
+    # StreamRead allows to work with stream in non-block read mode.
+
+    STATE_COMPLETED = 'completed'.freeze
+    STATE_CANCELLED = 'cancelled'.freeze
+    STATE_FAILED = 'failed'.freeze
+    STATE_PENDING = 'pending'.freeze
+
+    class RecvError < StandardError
+    end
+
+    include WithDbg
+
+    attr_reader :state, :stream, :io
+
+    # @param connection [Libvirt::Connection]
+    # @param io [IO]
+    # @return [LibvirtAsync::Stream]
+    def initialize(connection, io)
+      @connection = connection
+      @io = io
+      @callback = nil
+      @state = STATE_PENDING
+      @stream = @connection.stream(Libvirt::Stream::NONBLOCK)
+    end
+
+    # @yield asynchronously on complete or error
+    # @yieldparam success [Boolean]
+    # @yieldparam reason [String,NilClass]
+    # @yieldparam io [IO]
+    def call(&block)
+      add_callback(block) if block_given?
+
+      run
+    end
+
+    def add_callback(block)
+      raise ArgumentError, 'block must be a Proc' unless @callback.is_a?(Proc)
+      @callback = block
+    end
+
+    def run
+      raise ArgumentError, 'block must be given' if @callback.nil?
+
+      dbg { "#{to_s}#call event_add_callback calling" }
+      @cb_opaque = stream.event_add_callback(
+          Libvirt::Stream::EVENT_READABLE,
+          -> (_stream, events, _opaque) { stream_callback(events) },
+          self
+      )
+      dbg { "#{to_s}#call event_add_callback called" }
+
+      nil
+    rescue Libvirt::Error => e
+      dbg { "#{to_s}#call error occurred\n<#{e.class}>: #{e.message}\n#{e.backtrace.join("\n")}" }
+      @state = STATE_FAILED
+      stream&.finish rescue nil
+      on_error(e)
+      @cb_opaque = nil
+    end
+
+    def cancel
+      dbg { "#{to_s}#cancel" }
+      return if stream.nil?
+
+      @state = STATE_CANCELLED
+      stream.event_remove_callback
+      stream.finish
+      @stream = nil
+    rescue Libvirt::Error => e
+      dbg { "#{to_s}#cancel error occurred\n<#{e.class}>: #{e.message}\n#{e.backtrace.join("\n")}" }
+      @stream = nil
+    ensure
+      @cb_opaque = nil
+    end
+
+    def to_s
+      "#<#{self.class}:0x#{object_id.to_s(16)} @state=#{@state}>"
+    end
+
+    def inspect
+      to_s
+    end
+
+    private
+
+    def on_error(error)
+      @callback.call(false, "#{error.class}: #{error.message}", io)
+    end
+
+    def on_receive(data)
+      io.write(data)
+    end
+
+    def on_complete
+      @callback.call(true, nil, io)
+    end
+
+    # @param events [Integer]
+    def stream_callback(events)
+      dbg { "#{to_s}#stream_callback events=#{events}" }
+      return unless (Libvirt::Stream::EVENT_READABLE & events) != 0
+      # `stream.finish` will be executed asynchronously
+      # so callback will be triggered even after we complete data transfer.
+      if state != STATE_PENDING
+        dbg { "#{to_s}#stream_callback called for #{state} stream. Skipping." }
+        return
+      end
+
+      process_read
+
+    rescue RecvError, Libvirt::Error => e
+      dbg { "#{to_s}#stream_callback error occurred\n<#{e.class}>: #{e.message}\n#{e.backtrace.join("\n")}" }
+      @state = STATE_FAILED
+      stream.finish rescue nil
+      on_error(e)
+      @cb_opaque = nil
+    end
+
+    def process_read
+      code, data = stream.recv(1024)
+      dbg { "#{to_s}#stream_callback recv code=#{code}, size=#{data&.size}" }
+
+      case code
+      when 0
+        dbg { "#{to_s}#stream_callback finished" }
+        @state = STATE_COMPLETED
+        stream.finish
+        on_complete
+        @cb_opaque = nil
+      when -1
+        dbg { "#{to_s}#stream_callback code -1" }
+        raise RecvError, 'error code -1 received'
+      when -2
+        dbg { "#{to_s}#stream_callback is not ready" }
+      else
+        dbg { "#{to_s}#stream_callback ready code=#{code}" }
+        on_receive(data)
+      end
+    end
+
+  end
+end

data/lib/libvirt_async/version.rb

@@ -1,3 +1,3 @@
 module LibvirtAsync
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libvirt_async
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Denis Talakevich
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-12-29 00:00:00.000000000 Z
+date: 2020-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-libvirt
@@ -75,6 +75,7 @@ files:
 - lib/libvirt_async/handle.rb
 - lib/libvirt_async/implementations.rb
 - lib/libvirt_async/log_formatter.rb
+- lib/libvirt_async/stream_read.rb
 - lib/libvirt_async/timer.rb
 - lib/libvirt_async/util.rb
 - lib/libvirt_async/version.rb
@@ -102,8 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: Libvirt event async implementation.