VirtualBox

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

Last change on this file since 67954 was 62485, checked in by vboxsync, 8 years ago

(C) 2016

  • 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: 8.7 KB
Line 
1/* $Id: MediumLock.h 62485 2016-07-22 18:36:43Z vboxsync $ */
2
3/** @file
4 *
5 * VirtualBox medium object lock collections
6 */
7
8/*
9 * Copyright (C) 2010-2016 Oracle Corporation
10 *
11 * This file is part of VirtualBox Open Source Edition (OSE), as
12 * available from http://www.virtualbox.org. This file is free software;
13 * you can redistribute it and/or modify it under the terms of the GNU
14 * General Public License (GPL) as published by the Free Software
15 * Foundation, in version 2 as it comes in the "COPYING" file of the
16 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
17 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
18 */
19
20#ifndef ____H_MEDIUMLOCK
21#define ____H_MEDIUMLOCK
22
23/* interface definitions */
24#include "VBox/com/VirtualBox.h"
25#include "VirtualBoxBase.h"
26#include "AutoCaller.h"
27
28#include <iprt/types.h>
29
30#include <list>
31#include <map>
32
33class Medium;
34class MediumAttachment;
35
36/**
37 * Single entry for medium lock lists. Has a medium object reference,
38 * information about what kind of lock should be taken, and if it is
39 * locked right now.
40 */
41class MediumLock
42{
43public:
44 /**
45 * Default medium lock constructor.
46 */
47 MediumLock();
48
49 /**
50 * Default medium lock destructor.
51 */
52 ~MediumLock();
53
54 /**
55 * Create a new medium lock description
56 *
57 * @param aMedium Reference to medium object
58 * @param aLockWrite @c true means a write lock should be taken
59 */
60 MediumLock(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
61
62 /**
63 * Copy constructor. Needed because we contain an AutoCaller
64 * instance which is deliberately not copyable. The copy is not
65 * marked as locked, so be careful.
66 *
67 * @param aMediumLock Reference to source object.
68 */
69 MediumLock(const MediumLock &aMediumLock);
70
71 /**
72 * Update a medium lock description.
73 *
74 * @note May be used in locked state.
75 *
76 * @return COM status code
77 * @param aLockWrite @c true means a write lock should be taken
78 */
79 HRESULT UpdateLock(bool aLockWrite);
80
81 /**
82 * Get medium object reference.
83 */
84 const ComObjPtr<Medium> &GetMedium() const;
85
86 /**
87 * Get medium object lock request type.
88 */
89 bool GetLockRequest() const;
90
91 /**
92 * Check if this medium object has been locked by this MediumLock.
93 */
94 bool IsLocked() const;
95
96 /**
97 * Acquire a medium lock.
98 *
99 * @return COM status code
100 * @param aIgnoreLockedMedia If set ignore all media which is already
101 * locked in an incompatible way.
102 */
103 HRESULT Lock(bool aIgnoreLockedMedia = false);
104
105 /**
106 * Release a medium lock.
107 *
108 * @return COM status code
109 */
110 HRESULT Unlock();
111
112private:
113 ComObjPtr<Medium> mMedium;
114 ComPtr<IToken> mToken;
115 AutoCaller mMediumCaller;
116 bool mLockWrite;
117 bool mIsLocked;
118 /** Flag whether the medium was skipped when taking the locks.
119 * Only existing and accessible media objects need to be locked. */
120 bool mLockSkipped;
121};
122
123
124/**
125 * Medium lock list. Meant for storing the ordered locking information
126 * for a single medium chain.
127 */
128class MediumLockList
129{
130public:
131
132 /* Base list data type. */
133 typedef std::list<MediumLock> Base;
134
135 /**
136 * Default medium lock list constructor.
137 */
138 MediumLockList();
139
140 /**
141 * Default medium lock list destructor.
142 */
143 ~MediumLockList();
144
145 /**
146 * Checks if medium lock declaration list is empty.
147 *
148 * @return true if list is empty.
149 */
150 bool IsEmpty();
151
152 /**
153 * Add a new medium lock declaration to the end of the list.
154 *
155 * @note May be only used in unlocked state.
156 *
157 * @return COM status code
158 * @param aMedium Reference to medium object
159 * @param aLockWrite @c true means a write lock should be taken
160 */
161 HRESULT Append(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
162
163 /**
164 * Add a new medium lock declaration to the beginning of the list.
165 *
166 * @note May be only used in unlocked state.
167 *
168 * @return COM status code
169 * @param aMedium Reference to medium object
170 * @param aLockWrite @c true means a write lock should be taken
171 */
172 HRESULT Prepend(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
173
174 /**
175 * Update a medium lock declaration.
176 *
177 * @note May be used in locked state.
178 *
179 * @return COM status code
180 * @param aMedium Reference to medium object
181 * @param aLockWrite @c true means a write lock should be taken
182 */
183 HRESULT Update(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
184
185 /**
186 * Remove a medium lock declaration and return an updated iterator.
187 *
188 * @note May be used in locked state.
189 *
190 * @return COM status code
191 * @param aIt Iterator for the element to remove
192 */
193 HRESULT RemoveByIterator(Base::iterator &aIt);
194
195 /**
196 * Clear all medium lock declarations.
197 *
198 * @note Implicitly unlocks all locks.
199 *
200 * @return COM status code
201 */
202 HRESULT Clear();
203
204 /**
205 * Get iterator begin() for base list.
206 */
207 Base::iterator GetBegin();
208
209 /**
210 * Get iterator end() for base list.
211 */
212 Base::iterator GetEnd();
213
214 /**
215 * Acquire all medium locks "atomically", i.e. all or nothing.
216 *
217 * @return COM status code
218 * @param aSkipOverLockedMedia If set ignore all media which is already
219 * locked for reading or writing. For callers
220 * which need to know which medium objects
221 * have been locked by this lock list you
222 * can iterate over the list and check the
223 * MediumLock state.
224 */
225 HRESULT Lock(bool aSkipOverLockedMedia = false);
226
227 /**
228 * Release all medium locks.
229 *
230 * @return COM status code
231 */
232 HRESULT Unlock();
233
234private:
235 Base mMediumLocks;
236 bool mIsLocked;
237};
238
239/**
240 * Medium lock list map. Meant for storing a collection of lock lists.
241 * The usual use case is creating such a map when locking all medium chains
242 * belonging to one VM, however that's not the limit. Be creative.
243 */
244class MediumLockListMap
245{
246public:
247
248 /**
249 * Default medium lock list map constructor.
250 */
251 MediumLockListMap();
252
253 /**
254 * Default medium lock list map destructor.
255 */
256 ~MediumLockListMap();
257
258 /**
259 * Checks if medium lock list map is empty.
260 *
261 * @return true if list is empty.
262 */
263 bool IsEmpty();
264
265 /**
266 * Insert a new medium lock list into the map.
267 *
268 * @note May be only used in unlocked state.
269 *
270 * @return COM status code
271 * @param aMediumAttachment Reference to medium attachment object, the key.
272 * @param aMediumLockList Reference to medium lock list object
273 */
274 HRESULT Insert(const ComObjPtr<MediumAttachment> &aMediumAttachment, MediumLockList *aMediumLockList);
275
276 /**
277 * Replace the medium lock list key by a different one.
278 *
279 * @note May be used in locked state.
280 *
281 * @return COM status code
282 * @param aMediumAttachmentOld Reference to medium attachment object.
283 * @param aMediumAttachmentNew Reference to medium attachment object.
284 */
285 HRESULT ReplaceKey(const ComObjPtr<MediumAttachment> &aMediumAttachmentOld, const ComObjPtr<MediumAttachment> &aMediumAttachmentNew);
286
287 /**
288 * Remove a medium lock list from the map. The list will get deleted.
289 *
290 * @note May be only used in unlocked state.
291 *
292 * @return COM status code
293 * @param aMediumAttachment Reference to medium attachment object, the key.
294 */
295 HRESULT Remove(const ComObjPtr<MediumAttachment> &aMediumAttachment);
296
297 /**
298 * Clear all medium lock declarations in this map.
299 *
300 * @note Implicitly unlocks all locks.
301 *
302 * @return COM status code
303 */
304 HRESULT Clear();
305
306 /**
307 * Get the medium lock list identified by the given key.
308 *
309 * @note May be used in locked state.
310 *
311 * @return COM status code
312 * @param aMediumAttachment Key for medium attachment object.
313 * @param aMediumLockList Out: medium attachment object reference.
314 */
315 HRESULT Get(const ComObjPtr<MediumAttachment> &aMediumAttachment, MediumLockList * &aMediumLockList);
316
317 /**
318 * Acquire all medium locks "atomically", i.e. all or nothing.
319 *
320 * @return COM status code
321 */
322 HRESULT Lock();
323
324 /**
325 * Release all medium locks.
326 *
327 * @return COM status code
328 */
329 HRESULT Unlock();
330
331private:
332 typedef std::map<ComObjPtr<MediumAttachment>, MediumLockList *> Base;
333 Base mMediumLocks;
334 bool mIsLocked;
335};
336
337#endif /* !____H_MEDIUMLOCK */
338/* 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