VirtualBox

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

Last change on this file since 100841 was 98263, checked in by vboxsync, 23 months ago

Main: rc() -> hrc()/vrc().

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