Class: Vagrant::Plugin::V2::Communicator

Inherits:
Object
  • Object
show all
Defined in:
lib/vagrant/plugin/v2/communicator.rb

Overview

Base class for a communicator in Vagrant. A communicator is responsible for communicating with a machine in some way. There are various stages of Vagrant that require things such as uploading files to the machine, executing shell commands, etc. Implementors of this class are expected to provide this functionality in some way.

Note that a communicator must provide all of the methods in this base class. There is currently no way for one communicator to provide say a more efficient way of uploading a file, but not provide shell execution. This sort of thing will come in a future version.

Direct Known Subclasses

Remote::Communicator

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(machine) ⇒ Communicator

Initializes the communicator with the machine that we will be communicating with. This base method does nothing (it doesn't even store the machine in an instance variable for you), so you're expected to override this and do something with the machine if you care about it.

Parameters:

  • machine (Machine) —

    The machine this instance is expected to communicate with.



43
44
 
# File 'lib/vagrant/plugin/v2/communicator.rb', line 43

def initialize(machine)
end

Class Method Details

.match?(machine) ⇒ Boolean

This returns true/false depending on if the given machine can be communicated with using this communicator. If this returns true, then this class will be used as the primary communication method for the machine.

Returns:

  • (Boolean) 


31
32
33
 
# File 'lib/vagrant/plugin/v2/communicator.rb', line 31

def self.match?(machine)
  true
end

Instance Method Details

#download(from, to) ⇒ Object

Download a file from the remote machine to the local machine.

Parameters:

  • from (String) —

    Path of the file on the remote machine.

  • to (String) —

    Path of where to save the file locally.



82
83
 
# File 'lib/vagrant/plugin/v2/communicator.rb', line 82

def download(from, to)
end

#execute(command, opts = nil) {|type, data| ... } ⇒ Integer

Execute a command on the remote machine. The exact semantics of this method are up to the implementor, but in general the users of this class will expect this to be a shell.

This method gives you no way to write data back to the remote machine, so only execute commands that don't expect input.

Parameters:

  • command (String) —

    Command to execute.

Yields:

  • (type, data) —

    Realtime output of the command being executed.

Yield Parameters:

  • type (String) —

    Type of the output. This can be :stdout, :stderr, etc. The exact types are up to the implementor.

  • data (String) —

    Data for the given output.

Returns:

  • (Integer) —

    Exit code of the command.



107
108
 
# File 'lib/vagrant/plugin/v2/communicator.rb', line 107

def execute(command, opts=nil)
end

#ready? ⇒ Boolean

Checks if the target machine is ready for communication. If this returns true, then all the other methods for communicating with the machine are expected to be functional.

Returns:

  • (Boolean) 


51
52
53
 
# File 'lib/vagrant/plugin/v2/communicator.rb', line 51

def ready?
  false
end

#reset! ⇒ Object

Reset the communicator. For communicators which establish a persistent connection to the remote machine, this connection should be terminated and re-established. The communicator instance should be in a "fresh" state after calling this method.



131
132
 
# File 'lib/vagrant/plugin/v2/communicator.rb', line 131

def reset!
end

#sudo(command, opts = nil) ⇒ Object

Executes a command on the remote machine with administrative privileges. See #execute for documentation, as the API is the same.

See Also:



115
116
 
# File 'lib/vagrant/plugin/v2/communicator.rb', line 115

def sudo(command, opts=nil)
end

#test(command, opts = nil) ⇒ Object

Executes a command and returns true if the command succeeded, and false otherwise. By default, this executes as a normal user, and it is up to the communicator implementation if they expose an option for running tests as an administrator.

See Also:



124
125
 
# File 'lib/vagrant/plugin/v2/communicator.rb', line 124

def test(command, opts=nil)
end

#upload(from, to) ⇒ Object

Upload a file to the remote machine.

Parameters:

  • from (String) —

    Path of the file locally to upload.

  • to (String) —

    Path of where to save the file on the remote machine.



90
91
 
# File 'lib/vagrant/plugin/v2/communicator.rb', line 90

def upload(from, to)
end

#wait_for_ready(duration) ⇒ Boolean

wait_for_ready waits until the communicator is ready, blocking until then. It will wait up to the given duration or raise an exception if something goes wrong.

Parameters:

  • duration (Integer) —

    Timeout in seconds.

Returns:

  • (Boolean) —

    Will return true on successful connection or false on timeout.



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/vagrant/plugin/v2/communicator.rb', line 62

def wait_for_ready(duration)
  # By default, we implement a naive solution.
  begin
    Timeout.timeout(duration) do
      while true
        return true if ready?
        sleep 0.5
      end
    end
  rescue Timeout::Error
    # We timed out, we failed.
  end

  return false
end