VirtualBox

source: vbox/trunk/src/VBox/Main/include/MediumLock.h@ 98102

Last change on this file since 98102 was 98102, checked in by vboxsync, 21 months ago

Main/Machine: Assert that mData->mSession.mLockedMedia is locked before unlocking + modifying + relocking, as this seems to be an assumption in these three cases.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
  • Property svn:mergeinfo set to (toggle deleted branches)
    /branches/VBox-3.0/src/VBox/Main/include/MediumLock.h70973
    /branches/VBox-4.2/src/VBox/Main/include/MediumLock.h91503-91504,​91506-91508,​91510,​91514-91515,​91521
    /branches/VBox-4.3/src/VBox/Main/include/MediumLock.h91223
    /branches/VBox-4.3/trunk/src/VBox/Main/include/MediumLock.h91223
    /branches/dsen/gui/src/VBox/Main/include/MediumLock.h79076-79078,​79089,​79109-79110,​79112-79113,​79127-79130,​79134,​79141,​79151,​79155,​79157-79159,​79193,​79197
    /branches/dsen/gui2/src/VBox/Main/include/MediumLock.h79224,​79228,​79233,​79235,​79258,​79262-79263,​79273,​79341,​79345,​79354,​79357,​79387-79388,​79559-79569,​79572-79573,​79578,​79581-79582,​79590-79591,​79598-79599,​79602-79603,​79605-79606,​79632,​79635,​79637,​79644
    /branches/dsen/gui3/src/VBox/Main/include/MediumLock.h79645-79692
File size: 9.1 KB
Line 
1/* $Id: MediumLock.h 98102 2023-01-17 11:11:43Z vboxsync $ */
2
3/** @file
4 *
5 * VirtualBox medium object lock collections
6 */
7
8/*
9 * Copyright (C) 2010-2022 Oracle and/or its affiliates.
10 *
11 * This file is part of VirtualBox base platform packages, as
12 * available from https://www.virtualbox.org.
13 *
14 * This program is free software; you can redistribute it and/or
15 * modify it under the terms of the GNU General Public License
16 * as published by the Free Software Foundation, in version 3 of the
17 * License.
18 *
19 * This program is distributed in the hope that it will be useful, but
20 * WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * General Public License for more details.
23 *
24 * You should have received a copy of the GNU General Public License
25 * along with this program; if not, see <https://www.gnu.org/licenses>.
26 *
27 * SPDX-License-Identifier: GPL-3.0-only
28 */
29
30#ifndef MAIN_INCLUDED_MediumLock_h
31#define MAIN_INCLUDED_MediumLock_h
32#ifndef RT_WITHOUT_PRAGMA_ONCE
33# pragma once
34#endif
35
36/* interface definitions */
37#include "VBox/com/VirtualBox.h"
38#include "VirtualBoxBase.h"
39#include "AutoCaller.h"
40
41#include <iprt/types.h>
42
43#include <list>
44#include <map>
45
46class Medium;
47class MediumAttachment;
48
49/**
50 * Single entry for medium lock lists. Has a medium object reference,
51 * information about what kind of lock should be taken, and if it is
52 * locked right now.
53 */
54class MediumLock
55{
56public:
57 /**
58 * Default medium lock constructor.
59 */
60 MediumLock();
61
62 /**
63 * Default medium lock destructor.
64 */
65 ~MediumLock();
66
67 /**
68 * Create a new medium lock description
69 *
70 * @param aMedium Reference to medium object
71 * @param aLockWrite @c true means a write lock should be taken
72 */
73 MediumLock(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
74
75 /**
76 * Copy constructor. Needed because we contain an AutoCaller
77 * instance which is deliberately not copyable. The copy is not
78 * marked as locked, so be careful.
79 *
80 * @param aMediumLock Reference to source object.
81 */
82 MediumLock(const MediumLock &aMediumLock);
83
84 /**
85 * Update a medium lock description.
86 *
87 * @note May be used in locked state.
88 *
89 * @return COM status code
90 * @param aLockWrite @c true means a write lock should be taken
91 */
92 HRESULT UpdateLock(bool aLockWrite);
93
94 /**
95 * Get medium object reference.
96 */
97 const ComObjPtr<Medium> &GetMedium() const;
98
99 /**
100 * Get medium object lock request type.
101 */
102 bool GetLockRequest() const;
103
104 /**
105 * Check if this medium object has been locked by this MediumLock.
106 */
107 bool IsLocked() const;
108
109 /**
110 * Acquire a medium lock.
111 *
112 * @return COM status code
113 * @param aIgnoreLockedMedia If set ignore all media which is already
114 * locked in an incompatible way.
115 */
116 HRESULT Lock(bool aIgnoreLockedMedia = false);
117
118 /**
119 * Release a medium lock.
120 *
121 * @return COM status code
122 */
123 HRESULT Unlock();
124
125private:
126 ComObjPtr<Medium> mMedium;
127 ComPtr<IToken> mToken;
128 AutoCaller mMediumCaller;
129 bool mLockWrite;
130 bool mIsLocked;
131 /** Flag whether the medium was skipped when taking the locks.
132 * Only existing and accessible media objects need to be locked. */
133 bool mLockSkipped;
134};
135
136
137/**
138 * Medium lock list. Meant for storing the ordered locking information
139 * for a single medium chain.
140 */
141class MediumLockList
142{
143public:
144
145 /* Base list data type. */
146 typedef std::list<MediumLock> Base;
147
148 /**
149 * Default medium lock list constructor.
150 */
151 MediumLockList();
152
153 /**
154 * Default medium lock list destructor.
155 */
156 ~MediumLockList();
157
158 /**
159 * Checks if medium lock declaration list is empty.
160 *
161 * @return true if list is empty.
162 */
163 bool IsEmpty();
164
165 /**
166 * Add a new medium lock declaration to the end of the list.
167 *
168 * @note May be only used in unlocked state.
169 *
170 * @return COM status code
171 * @param aMedium Reference to medium object
172 * @param aLockWrite @c true means a write lock should be taken
173 */
174 HRESULT Append(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
175
176 /**
177 * Add a new medium lock declaration to the beginning of the list.
178 *
179 * @note May be only used in unlocked state.
180 *
181 * @return COM status code
182 * @param aMedium Reference to medium object
183 * @param aLockWrite @c true means a write lock should be taken
184 */
185 HRESULT Prepend(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
186
187 /**
188 * Update a medium lock declaration.
189 *
190 * @note May be used in locked state.
191 *
192 * @return COM status code
193 * @param aMedium Reference to medium object
194 * @param aLockWrite @c true means a write lock should be taken
195 */
196 HRESULT Update(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
197
198 /**
199 * Remove a medium lock declaration and return an updated iterator.
200 *
201 * @note May be used in locked state.
202 *
203 * @return COM status code
204 * @param aIt Iterator for the element to remove
205 */
206 HRESULT RemoveByIterator(Base::iterator &aIt);
207
208 /**
209 * Clear all medium lock declarations.
210 *
211 * @note Implicitly unlocks all locks.
212 *
213 * @return COM status code
214 */
215 HRESULT Clear();
216
217 /**
218 * Get iterator begin() for base list.
219 */
220 Base::iterator GetBegin();
221
222 /**
223 * Get iterator end() for base list.
224 */
225 Base::iterator GetEnd();
226
227 /**
228 * Acquire all medium locks "atomically", i.e. all or nothing.
229 *
230 * @return COM status code
231 * @param aSkipOverLockedMedia If set ignore all media which is already
232 * locked for reading or writing. For callers
233 * which need to know which medium objects
234 * have been locked by this lock list you
235 * can iterate over the list and check the
236 * MediumLock state.
237 */
238 HRESULT Lock(bool aSkipOverLockedMedia = false);
239
240 /**
241 * Release all medium locks.
242 *
243 * @return COM status code
244 */
245 HRESULT Unlock();
246
247private:
248 Base mMediumLocks;
249 bool mIsLocked;
250};
251
252/**
253 * Medium lock list map. Meant for storing a collection of lock lists.
254 * The usual use case is creating such a map when locking all medium chains
255 * belonging to one VM, however that's not the limit. Be creative.
256 */
257class MediumLockListMap
258{
259public:
260
261 /**
262 * Default medium lock list map constructor.
263 */
264 MediumLockListMap();
265
266 /**
267 * Default medium lock list map destructor.
268 */
269 ~MediumLockListMap();
270
271 /**
272 * Checks if medium lock list map is empty.
273 *
274 * @return true if list is empty.
275 */
276 bool IsEmpty();
277
278 /**
279 * Insert a new medium lock list into the map.
280 *
281 * @note May be only used in unlocked state.
282 *
283 * @return COM status code
284 * @param aMediumAttachment Reference to medium attachment object, the key.
285 * @param aMediumLockList Reference to medium lock list object
286 */
287 HRESULT Insert(const ComObjPtr<MediumAttachment> &aMediumAttachment, MediumLockList *aMediumLockList);
288
289 /**
290 * Replace the medium lock list key by a different one.
291 *
292 * @note May be used in locked state.
293 *
294 * @return COM status code
295 * @param aMediumAttachmentOld Reference to medium attachment object.
296 * @param aMediumAttachmentNew Reference to medium attachment object.
297 */
298 HRESULT ReplaceKey(const ComObjPtr<MediumAttachment> &aMediumAttachmentOld, const ComObjPtr<MediumAttachment> &aMediumAttachmentNew);
299
300 /**
301 * Remove a medium lock list from the map. The list will get deleted.
302 *
303 * @note May be only used in unlocked state.
304 *
305 * @return COM status code
306 * @param aMediumAttachment Reference to medium attachment object, the key.
307 */
308 HRESULT Remove(const ComObjPtr<MediumAttachment> &aMediumAttachment);
309
310 /**
311 * Clear all medium lock declarations in this map.
312 *
313 * @note Implicitly unlocks all locks.
314 *
315 * @return COM status code
316 */
317 HRESULT Clear();
318
319 /**
320 * Get the medium lock list identified by the given key.
321 *
322 * @note May be used in locked state.
323 *
324 * @return COM status code
325 * @param aMediumAttachment Key for medium attachment object.
326 * @param aMediumLockList Out: medium attachment object reference.
327 */
328 HRESULT Get(const ComObjPtr<MediumAttachment> &aMediumAttachment, MediumLockList * &aMediumLockList);
329
330 /**
331 * Acquire all medium locks "atomically", i.e. all or nothing.
332 *
333 * @return COM status code
334 */
335 HRESULT Lock();
336
337 /**
338 * Release all medium locks.
339 *
340 * @return COM status code
341 */
342 HRESULT Unlock();
343
344 /** Introspection. */
345 bool IsLocked(void) const { return mIsLocked; }
346
347private:
348 typedef std::map<ComObjPtr<MediumAttachment>, MediumLockList *> Base;
349 Base mMediumLocks;
350 bool mIsLocked;
351};
352
353#endif /* !MAIN_INCLUDED_MediumLock_h */
354/* vi: set tabstop=4 shiftwidth=4 expandtab: */
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