Method: Puppet::Provider.instances

Defined in:
lib/puppet/provider.rb

.instances ⇒ Array<Puppet::Provider>

This method is abstract.

this method must be implemented by a subclass and this super method should never be called as it raises an exception.

Note:

The returned instances are instance of some subclass of Provider, not resources.

Returns a list of system resources (entities) this provider may/can manage. This is a query mechanism that lists entities that the provider may manage on a given system. It is is directly used in query services, but is also the foundation for other services; prefetching, and purging.

As an example, a package provider lists all installed packages. (In contrast, the File provider does not list all files on the file-system as that would make execution incredibly slow). An implementation of this method should be made if it is possible to quickly (with a single system call) provide all instances.

An implementation of this method should only cache the values of properties if they are discovered as part of the process for finding existing resources. Resource properties that require additional commands (than those used to determine existence/identity) should be implemented in their respective getter method. (This is important from a performance perspective; it may be expensive to compute, as well as wasteful as all discovered resources may perhaps not be managed).

An implementation may return an empty list (naturally with the effect that it is not possible to query for manageable entities).

By implementing this method, it is possible to use the ‘resources´ resource type to specify purging of all non managed entities.

Returns:

  • (Array<Puppet::Provider>) —

    a list of providers referencing the system entities

Raises:

  • (Puppet::DevError) —

    Error indicating that the method should have been implemented by subclass.

See Also:



382
383
384
 
# File 'lib/puppet/provider.rb', line 382

def self.instances
  raise Puppet::DevError, _("To support listing resources of this type the '%{provider}' provider needs to implement an 'instances' class method returning the current set of resources. We recommend porting your module to the simpler Resource API instead: https://puppet.com/search/docs?keys=resource+api") % { provider: name }
end