VirtualBox

source: vbox/trunk/src/VBox/Main/include/AutoStateDep.h@ 61609

Last change on this file since 61609 was 55401, checked in by vboxsync, 10 years ago

added a couple of missing Id headers

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.2 KB
Line 
1/* $Id: AutoStateDep.h 55401 2015-04-23 10:03:17Z vboxsync $ */
2#ifndef ____H_AUTOSTATEDEP
3#define ____H_AUTOSTATEDEP
4
5/** @file
6 *
7 * AutoStateDep template classes, formerly in MachineImpl.h. Use these if
8 * you need to ensure that the machine state does not change over a certain
9 * period of time.
10 */
11
12/*
13 * Copyright (C) 2006-2015 Oracle Corporation
14 *
15 * This file is part of VirtualBox Open Source Edition (OSE), as
16 * available from http://www.virtualbox.org. This file is free software;
17 * you can redistribute it and/or modify it under the terms of the GNU
18 * General Public License (GPL) as published by the Free Software
19 * Foundation, in version 2 as it comes in the "COPYING" file of the
20 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
21 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
22 */
23
24 /**
25 * Helper class that safely manages the machine state dependency by
26 * calling Machine::addStateDependency() on construction and
27 * Machine::releaseStateDependency() on destruction. Intended for Machine
28 * children. The usage pattern is:
29 *
30 * @code
31 * AutoCaller autoCaller(this);
32 * if (FAILED(autoCaller.rc())) return autoCaller.rc();
33 *
34 * Machine::AutoStateDependency<MutableStateDep> adep(mParent);
35 * if (FAILED(stateDep.rc())) return stateDep.rc();
36 * ...
37 * // code that depends on the particular machine state
38 * ...
39 * @endcode
40 *
41 * Note that it is more convenient to use the following individual
42 * shortcut classes instead of using this template directly:
43 * AutoAnyStateDependency, AutoMutableStateDependency,
44 * AutoMutableOrSavedStateDependency, AutoMutableOrRunningStateDependency
45 * or AutoMutableOrSavedOrRunningStateDependency. The usage pattern is
46 * exactly the same as above except that there is no need to specify the
47 * template argument because it is already done by the shortcut class.
48 *
49 * @param taDepType Dependency type to manage.
50 */
51 template <Machine::StateDependency taDepType = Machine::AnyStateDep>
52 class AutoStateDependency
53 {
54 public:
55
56 AutoStateDependency(Machine *aThat)
57 : mThat(aThat), mRC(S_OK),
58 mMachineState(MachineState_Null),
59 mRegistered(FALSE)
60 {
61 Assert(aThat);
62 mRC = aThat->i_addStateDependency(taDepType, &mMachineState,
63 &mRegistered);
64 }
65 ~AutoStateDependency()
66 {
67 if (SUCCEEDED(mRC))
68 mThat->i_releaseStateDependency();
69 }
70
71 /** Decreases the number of dependencies before the instance is
72 * destroyed. Note that will reset #rc() to E_FAIL. */
73 void release()
74 {
75 AssertReturnVoid(SUCCEEDED(mRC));
76 mThat->i_releaseStateDependency();
77 mRC = E_FAIL;
78 }
79
80 /** Restores the number of callers after by #release(). #rc() will be
81 * reset to the result of calling addStateDependency() and must be
82 * rechecked to ensure the operation succeeded. */
83 void add()
84 {
85 AssertReturnVoid(!SUCCEEDED(mRC));
86 mRC = mThat->i_addStateDependency(taDepType, &mMachineState,
87 &mRegistered);
88 }
89
90 /** Returns the result of Machine::addStateDependency(). */
91 HRESULT rc() const { return mRC; }
92
93 /** Shortcut to SUCCEEDED(rc()). */
94 bool isOk() const { return SUCCEEDED(mRC); }
95
96 /** Returns the machine state value as returned by
97 * Machine::addStateDependency(). */
98 MachineState_T machineState() const { return mMachineState; }
99
100 /** Returns the machine state value as returned by
101 * Machine::addStateDependency(). */
102 BOOL machineRegistered() const { return mRegistered; }
103
104 protected:
105
106 Machine *mThat;
107 HRESULT mRC;
108 MachineState_T mMachineState;
109 BOOL mRegistered;
110
111 private:
112
113 DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(AutoStateDependency)
114 DECLARE_CLS_NEW_DELETE_NOOP(AutoStateDependency)
115 };
116
117 /**
118 * Shortcut to AutoStateDependency<AnyStateDep>.
119 * See AutoStateDependency to get the usage pattern.
120 *
121 * Accepts any machine state and guarantees the state won't change before
122 * this object is destroyed. If the machine state cannot be protected (as
123 * a result of the state change currently in progress), this instance's
124 * #rc() method will indicate a failure, and the caller is not allowed to
125 * rely on any particular machine state and should return the failed
126 * result code to the upper level.
127 */
128 typedef AutoStateDependency<Machine::AnyStateDep> AutoAnyStateDependency;
129
130 /**
131 * Shortcut to AutoStateDependency<MutableStateDep>.
132 * See AutoStateDependency to get the usage pattern.
133 *
134 * Succeeds only if the machine state is in one of the mutable states, and
135 * guarantees the given mutable state won't change before this object is
136 * destroyed. If the machine is not mutable, this instance's #rc() method
137 * will indicate a failure, and the caller is not allowed to rely on any
138 * particular machine state and should return the failed result code to
139 * the upper level.
140 *
141 * Intended to be used within all setter methods of IMachine
142 * children objects (DVDDrive, NetworkAdapter, AudioAdapter, etc.) to
143 * provide data protection and consistency. There must be no VM process,
144 * i.e. use for settings changes which are valid when the VM is shut down.
145 */
146 typedef AutoStateDependency<Machine::MutableStateDep> AutoMutableStateDependency;
147
148 /**
149 * Shortcut to AutoStateDependency<MutableOrSavedStateDep>.
150 * See AutoStateDependency to get the usage pattern.
151 *
152 * Succeeds only if the machine state is in one of the mutable states, or
153 * if the machine is in the Saved state, and guarantees the given mutable
154 * state won't change before this object is destroyed. If the machine is
155 * not mutable, this instance's #rc() method will indicate a failure, and
156 * the caller is not allowed to rely on any particular machine state and
157 * should return the failed result code to the upper level.
158 *
159 * Intended to be used within setter methods of IMachine
160 * children objects that may operate on shut down or Saved machines.
161 */
162 typedef AutoStateDependency<Machine::MutableOrSavedStateDep> AutoMutableOrSavedStateDependency;
163
164 /**
165 * Shortcut to AutoStateDependency<MutableOrRunningStateDep>.
166 * See AutoStateDependency to get the usage pattern.
167 *
168 * Succeeds only if the machine state is in one of the mutable states, or
169 * if the machine is in the Running or Paused state, and guarantees the
170 * given mutable state won't change before this object is destroyed. If
171 * the machine is not mutable, this instance's #rc() method will indicate
172 * a failure, and the caller is not allowed to rely on any particular
173 * machine state and should return the failed result code to the upper
174 * level.
175 *
176 * Intended to be used within setter methods of IMachine
177 * children objects that may operate on shut down or running machines.
178 */
179 typedef AutoStateDependency<Machine::MutableOrRunningStateDep> AutoMutableOrRunningStateDependency;
180
181 /**
182 * Shortcut to AutoStateDependency<MutableOrSavedOrRunningStateDep>.
183 * See AutoStateDependency to get the usage pattern.
184 *
185 * Succeeds only if the machine state is in one of the mutable states, or
186 * if the machine is in the Running, Paused or Saved state, and guarantees
187 * the given mutable state won't change before this object is destroyed.
188 * If the machine is not mutable, this instance's #rc() method will
189 * indicate a failure, and the caller is not allowed to rely on any
190 * particular machine state and should return the failed result code to
191 * the upper level.
192 *
193 * Intended to be used within setter methods of IMachine
194 * children objects that may operate on shut down, running or saved
195 * machines.
196 */
197 typedef AutoStateDependency<Machine::MutableOrSavedOrRunningStateDep> AutoMutableOrSavedOrRunningStateDependency;
198
199#endif // ____H_AUTOSTATEDEP
200
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette