VirtualBox

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

Last change on this file since 78043 was 76562, checked in by vboxsync, 6 years ago

Main: Use MAIN_INCLUDED_ and MAIN_INCLUDED_SRC_ as header guard prefixes with scm.

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