Class: Vagrant::Plugin::V2::Communicator
- Inherits:
-
Object
- Object
- Vagrant::Plugin::V2::Communicator
- 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.
Class Method Summary collapse
-
.match?(machine) ⇒ Boolean
This returns true/false depending on if the given machine can be communicated with using this communicator.
Instance Method Summary collapse
-
#download(from, to) ⇒ Object
Download a file from the remote machine to the local machine.
-
#execute(command, opts = nil) {|type, data| ... } ⇒ Integer
Execute a command on the remote machine.
-
#initialize(machine) ⇒ Communicator
constructor
Initializes the communicator with the machine that we will be communicating with.
-
#ready? ⇒ Boolean
Checks if the target machine is ready for communication.
-
#sudo(command, opts = nil) ⇒ Object
Executes a command on the remote machine with administrative privileges.
-
#test(command, opts = nil) ⇒ Object
Executes a command and returns true if the command succeeded, and false otherwise.
-
#upload(from, to) ⇒ Object
Upload a file to the remote machine.
-
#wait_for_ready(duration) ⇒ Boolean
wait_for_ready waits until the communicator is ready, blocking until then.
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.
37 38 |
# File 'lib/vagrant/plugin/v2/communicator.rb', line 37 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.
25 26 27 |
# File 'lib/vagrant/plugin/v2/communicator.rb', line 25 def self.match?(machine) true end |
Instance Method Details
#download(from, to) ⇒ Object
Download a file from the remote machine to the local machine.
76 77 |
# File 'lib/vagrant/plugin/v2/communicator.rb', line 76 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.
101 102 |
# File 'lib/vagrant/plugin/v2/communicator.rb', line 101 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.
45 46 47 |
# File 'lib/vagrant/plugin/v2/communicator.rb', line 45 def ready? false 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.
109 110 |
# File 'lib/vagrant/plugin/v2/communicator.rb', line 109 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.
118 119 |
# File 'lib/vagrant/plugin/v2/communicator.rb', line 118 def test(command, opts=nil) end |
#upload(from, to) ⇒ Object
Upload a file to the remote machine.
84 85 |
# File 'lib/vagrant/plugin/v2/communicator.rb', line 84 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.
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 |
# File 'lib/vagrant/plugin/v2/communicator.rb', line 56 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 |