Class: Libvirt::Collection::DomainCollection

Inherits:
AbstractCollection show all
Defined in:
lib/libvirt/collection/domain_collection.rb

Overview

Represents a collection of domains. This is an enumerable (in the Ruby sense) object, but it is not directly an Array. This collection is a special enumerable which allows you to do things such as get only the active domains, create a new domain from a specification, etc.

If you enumerate the entire collection, then this is equivalent to enumerating over #all domains. e.g. collection.length is equivalent to calling collection.all.length (where collection is a DomainCollection object).

Instance Attribute Summary

Attributes inherited from AbstractCollection

#interface

Instance Method Summary collapse

Methods inherited from AbstractCollection

#initialize

Constructor Details

This class inherits a constructor from Libvirt::Collection::AbstractCollection

Instance Method Details

#active ⇒ Array<Domain>

Returns all the active (running) domains for the connection which this collection belongs to.

Returns:



67
68
69
70
71
72
73
74
 
# File 'lib/libvirt/collection/domain_collection.rb', line 67

def active
  # Do some pointer and array fiddling to extract the ids of the active
  # domains from the libvirt API
  ids = read_array(:virConnectListDomains, :virConnectNumOfDomains, :int)

  # Lookup all the IDs and make them proper Domain objects
  ids.collect { |id| find_by_id(id) }
end

#all ⇒ Array<Domain>

Returns all domains (active and inactive) for the connection this collection belongs to.

Returns:



93
94
95
 
# File 'lib/libvirt/collection/domain_collection.rb', line 93

def all
  active + inactive
end

#create(spec) ⇒ Domain

Creates a new domain and starts it. This domain configuration is not persisted, so it may disappear after the next reboot or shutdown.

Parameters:

  • spec (Object)

Returns:



58
59
60
61
 
# File 'lib/libvirt/collection/domain_collection.rb', line 58

def create(spec)
  spec = spec.is_a?(String) ? spec : spec.to_xml
  nil_or_object(FFI::Libvirt.virDomainCreateXML(interface, spec, 0), Domain)
end

#define(spec) ⇒ Domain

Defines a new domain with the given valid specification. This method doesn't start the domain.

Parameters:

  • spec (Object)

Returns:



48
49
50
51
 
# File 'lib/libvirt/collection/domain_collection.rb', line 48

def define(spec)
  spec = spec.is_a?(String) ? spec : spec.to_xml
  nil_or_object(FFI::Libvirt.virDomainDefineXML(interface, spec), Domain)
end

#find(value) ⇒ Domain

Searches for a domain. This will search first by name, then by ID, then by UUID, returning a result as soon as one is found.

Returns:



16
17
18
19
20
 
# File 'lib/libvirt/collection/domain_collection.rb', line 16

def find(value)
  result = find_by_name(value) rescue nil
  result ||= find_by_id(value) rescue nil
  result ||= find_by_uuid(value) rescue nil
end

#find_by_id(id) ⇒ Domain

Searches for a domain by ID.

Returns:



32
33
34
 
# File 'lib/libvirt/collection/domain_collection.rb', line 32

def find_by_id(id)
  nil_or_object(FFI::Libvirt.virDomainLookupByID(interface, id), Domain)
end

#find_by_name(name) ⇒ Domain

Searches for a domain by name.

Returns:



25
26
27
 
# File 'lib/libvirt/collection/domain_collection.rb', line 25

def find_by_name(name)
  nil_or_object(FFI::Libvirt.virDomainLookupByName(interface, name), Domain)
end

#find_by_uuid(uuid) ⇒ Domain

Searches for a domain by UUID.

Returns:



39
40
41
 
# File 'lib/libvirt/collection/domain_collection.rb', line 39

def find_by_uuid(uuid)
  nil_or_object(FFI::Libvirt.virDomainLookupByUUIDString(interface, uuid), Domain)
end

#inactive ⇒ Array<Domain>

Returns all the inactive (not running) domains for the connection which this collection belongs to.

Returns:



80
81
82
83
84
85
86
87
 
# File 'lib/libvirt/collection/domain_collection.rb', line 80

def inactive
  # Do some pointer and array fiddling to extract the names of the active
  # domains from the libvirt API
  ids = read_array(:virConnectListDefinedDomains, :virConnectNumOfDefinedDomains, :string)

  # Lookup all the names and make them proper Domain objects
  ids.collect { |id| find_by_name(id) }
end