Class: Vagrant::Action

Inherits:
Object
  • Object
show all
Includes:
Util
Defined in:
lib/vagrant/action.rb,
lib/vagrant/action/vm.rb,
lib/vagrant/action/box.rb,
lib/vagrant/action/env.rb,
lib/vagrant/action/vm/nfs.rb,
lib/vagrant/action/warden.rb,
lib/vagrant/action/builder.rb,
lib/vagrant/action/builtin.rb,
lib/vagrant/action/env/set.rb,
lib/vagrant/action/general.rb,
lib/vagrant/action/vm/boot.rb,
lib/vagrant/action/vm/halt.rb,
lib/vagrant/action/vm/export.rb,
lib/vagrant/action/vm/import.rb,
lib/vagrant/action/vm/resume.rb,
lib/vagrant/action/box/verify.rb,
lib/vagrant/action/vm/destroy.rb,
lib/vagrant/action/vm/network.rb,
lib/vagrant/action/vm/package.rb,
lib/vagrant/action/vm/suspend.rb,
lib/vagrant/action/box/destroy.rb,
lib/vagrant/action/box/package.rb,
lib/vagrant/action/environment.rb,
lib/vagrant/action/box/download.rb,
lib/vagrant/action/vm/check_box.rb,
lib/vagrant/action/vm/customize.rb,
lib/vagrant/action/vm/host_name.rb,
lib/vagrant/action/vm/provision.rb,
lib/vagrant/action/box/unpackage.rb,
lib/vagrant/action/vm/nfs_helpers.rb,
lib/vagrant/action/general/package.rb,
lib/vagrant/action/general/validate.rb,
lib/vagrant/action/vm/discard_state.rb,
lib/vagrant/action/vm/forward_ports.rb,
lib/vagrant/action/vm/share_folders.rb,
lib/vagrant/action/vm/clear_nfs_exports.rb,
lib/vagrant/action/vm/match_mac_address.rb,
lib/vagrant/action/vm/package_vagrantfile.rb,
lib/vagrant/action/vm/clean_machine_folder.rb,
lib/vagrant/action/vm/clear_shared_folders.rb,
lib/vagrant/action/vm/check_guest_additions.rb,
lib/vagrant/action/vm/clear_forwarded_ports.rb,
lib/vagrant/action/vm/forward_ports_helpers.rb,
lib/vagrant/action/vm/destroy_unused_network_interfaces.rb

Overview

Manages action running and registration. Every Vagrant environment has an instance of Action to allow for running in the context of the environment, which is accessible at Environment#actions. Actions are the foundation of most functionality in Vagrant, and are implemented architecturally as "middleware."

Registering an Action

The main benefits of registering an action is the ability to retrieve and modify that registered action, as well as easily run the action. An example of registering an action is shown below, with a simple middleware which just outputs to STDOUT:

class StdoutMiddleware
  def initialize(app, env)
    @app = app
  end

  def call(env)
    puts "HI!"
    @app.call(env)
  end
end

Vagrant::Action.register(:stdout, StdoutMiddleware)

Then to run a registered action, assuming env is a loaded Environment:

env.actions.run(:stdout)

Or to retrieve the action class for any reason:

Vagrant::Action[:stdout]

Running an Action

There are various built-in registered actions such as start, stop, up, etc. Actions are built to be run in the context of an environment, so use Environment#actions to run all actions. Then simply call #run:

env.actions.run(:name)

Where :name is the name of the registered action.

Defined Under Namespace

Modules: Box, Env, General, VM Classes: Builder, Environment, Warden

Constant Summary collapse

@@reported_interrupt = 
false

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(env) ⇒ Action

Initializes the action with the given environment which the actions will be run in.

Parameters:



94
95
96
 
# File 'lib/vagrant/action.rb', line 94

def initialize(env)
  @env = env
end

Instance Attribute Details

#env ⇒ Object (readonly)

The environment to run the actions in.



88
89
90
 
# File 'lib/vagrant/action.rb', line 88

def env
  @env
end

Class Method Details

.[](key) ⇒ Object

Retrieves a registered action by key.

Parameters:

  • key (Symbol) 


82
83
84
 
# File 'lib/vagrant/action.rb', line 82

def [](key)
  actions[key.to_sym]
end

.actions ⇒ Array

Returns the list of registered actions.

Returns:

  • (Array) 


66
67
68
 
# File 'lib/vagrant/action.rb', line 66

def actions
  @actions ||= {}
end

.builtin! ⇒ Object

Registers the builtin actions. These are locked away in a method so that their definition can be deferred until after all the necessary Vagrant libraries are loaded. Hopefully in the future this will no longer be necessary with autoloading.



7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/vagrant/action/builtin.rb', line 7

def self.builtin!
  # provision - Provisions a running VM
  register(:provision, Builder.new do
    use VM::Provision
  end)

  # start - Starts a VM, assuming it already exists on the
  # environment.
  register(:start, Builder.new do
    use VM::CleanMachineFolder
    use VM::Customize
    use VM::ClearForwardedPorts
    use VM::ForwardPorts
    use VM::Provision
    use VM::NFS
    use VM::ClearSharedFolders
    use VM::ShareFolders
    use VM::HostName
    use VM::Network
    use VM::Boot
  end)

  # halt - Halts the VM, attempting gracefully but then forcing
  # a restart if fails.
  register(:halt, Builder.new do
    use VM::DiscardState
    use VM::Halt
  end)

  # suspend - Suspends the VM
  register(:suspend, Builder.new do
    use VM::Suspend
  end)

  # resume - Resume a VM
  register(:resume, Builder.new do
    use VM::Resume
  end)

  # reload - Halts then restarts the VM
  register(:reload, Builder.new do
    use Action[:halt]
    use Action[:start]
  end)

  # up - Imports, prepares, then starts a fresh VM.
  register(:up, Builder.new do
    use VM::CheckBox
    use VM::Import
    use VM::MatchMACAddress
    use VM::CheckGuestAdditions
    use Action[:start]
  end)

  # destroy - Halts, cleans up, and destroys an existing VM
  register(:destroy, Builder.new do
    use Action[:halt], :force => true
    use VM::ClearNFSExports
    use VM::Destroy
    use VM::CleanMachineFolder
    use VM::DestroyUnusedNetworkInterfaces
  end)

  # package - Export and package the VM
  register(:package, Builder.new do
    use Action[:halt]
    use VM::ClearForwardedPorts
    use VM::ClearSharedFolders
    use VM::Export
    use VM::PackageVagrantfile
    use VM::Package
  end)

  # box_add - Download and add a box.
  register(:box_add, Builder.new do
    use Box::Download
    use Box::Unpackage
    use Box::Verify
  end)

  # box_remove - Removes/deletes a box.
  register(:box_remove, Builder.new do
    use Box::Destroy
  end)

  # box_repackage - Repackages a box.
  register(:box_repackage, Builder.new do
    use Box::Package
  end)

  # Other callbacks. There will be more of these in the future. For
  # now, these are limited to what are needed internally.
  register(:before_action_run, Builder.new do
    use General::Validate
  end)
end

.register(key, callable) ⇒ Object

Registers an action and associates it with a symbol. This symbol can then be referenced in other action builds and callbacks can be registered on that symbol.

Parameters:

  • key (Symbol) 


75
76
77
 
# File 'lib/vagrant/action.rb', line 75

def register(key, callable)
  actions[key.to_sym] = callable
end

Instance Method Details

#run(callable_id, options = nil) ⇒ Object

Runs the given callable object in the context of the environment. If a symbol is given as the callable parameter, then it is looked up in the registered actions list which are registered with register.

Any options given are injected into the environment hash.

Parameters:

  • callable (Object) —

    An object which responds to call.

Raises:

  • (ArgumentError) 


105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/vagrant/action.rb', line 105

def run(callable_id, options=nil)
  callable = callable_id
  callable = Builder.new.use(callable_id) if callable_id.kind_of?(Class)
  callable = self.class.actions[callable_id] if callable_id.kind_of?(Symbol)
  raise ArgumentError, "Argument to run must be a callable object or registered action." if !callable || !callable.respond_to?(:call)

  action_environment = Action::Environment.new(env)
  action_environment.merge!(options || {})

  # Run the before action run callback, if we're not doing that already
  run(:before_action_run, action_environment) if callable_id != :before_action_run

  # Run the action chain in a busy block, marking the environment as
  # interrupted if a SIGINT occurs, and exiting cleanly once the
  # chain has been run.
  int_callback = lambda do
    if action_environment.interrupted?
      env.ui.error I18n.t("vagrant.actions.runner.exit_immediately")
      abort
    end

    env.ui.warn I18n.t("vagrant.actions.runner.waiting_cleanup") if !@@reported_interrupt
    action_environment.interrupt!
    @@reported_interrupt = true
  end

  Busy.busy(int_callback) { callable.call(action_environment) }
end