VirtualBox

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

Last change on this file was 98103, checked in by vboxsync, 17 months ago

Copyright year updates by 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)
    /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
RevLine 
[9360]1/* $Id: MediumLock.h 98103 2023-01-17 14:15:46Z vboxsync $ */
2
3/** @file
4 *
[27120]5 * VirtualBox medium object lock collections
[9360]6 */
7
8/*
[98103]9 * Copyright (C) 2010-2023 Oracle and/or its affiliates.
[9360]10 *
[96407]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
[9360]28 */
29
[76562]30#ifndef MAIN_INCLUDED_MediumLock_h
31#define MAIN_INCLUDED_MediumLock_h
[76487]32#ifndef RT_WITHOUT_PRAGMA_ONCE
33# pragma once
34#endif
[9360]35
[30764]36/* interface definitions */
37#include "VBox/com/VirtualBox.h"
[28353]38#include "VirtualBoxBase.h"
39#include "AutoCaller.h"
[14667]40
[30764]41#include <iprt/types.h>
42
43#include <list>
44#include <map>
45
46class Medium;
47class MediumAttachment;
48
[9360]49/**
[27120]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.
[9360]53 */
[27120]54class MediumLock
[9360]55{
56public:
[27120]57 /**
58 * Default medium lock constructor.
59 */
60 MediumLock();
[9360]61
[27120]62 /**
63 * Default medium lock destructor.
64 */
65 ~MediumLock();
[9360]66
[15762]67 /**
[27120]68 * Create a new medium lock description
[24301]69 *
[27120]70 * @param aMedium Reference to medium object
71 * @param aLockWrite @c true means a write lock should be taken
[15762]72 */
[28353]73 MediumLock(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
[15762]74
75 /**
[28353]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 /**
[28582]85 * Update a medium lock description.
[28353]86 *
[28582]87 * @note May be used in locked state.
[28353]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 /**
[28556]100 * Get medium object lock request type.
101 */
102 bool GetLockRequest() const;
103
104 /**
[48297]105 * Check if this medium object has been locked by this MediumLock.
106 */
107 bool IsLocked() const;
108
109 /**
[27120]110 * Acquire a medium lock.
[28353]111 *
112 * @return COM status code
[48297]113 * @param aIgnoreLockedMedia If set ignore all media which is already
114 * locked in an incompatible way.
[15762]115 */
[48297]116 HRESULT Lock(bool aIgnoreLockedMedia = false);
[15762]117
118 /**
[27120]119 * Release a medium lock.
[28353]120 *
121 * @return COM status code
[15762]122 */
[28353]123 HRESULT Unlock();
[15762]124
[27120]125private:
126 ComObjPtr<Medium> mMedium;
[48297]127 ComPtr<IToken> mToken;
[28353]128 AutoCaller mMediumCaller;
[27120]129 bool mLockWrite;
[28353]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;
[27120]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
[28353]145 /* Base list data type. */
146 typedef std::list<MediumLock> Base;
147
[15762]148 /**
[27120]149 * Default medium lock list constructor.
[23648]150 */
[27120]151 MediumLockList();
[23675]152
153 /**
[27120]154 * Default medium lock list destructor.
155 */
156 ~MediumLockList();
157
158 /**
[28353]159 * Checks if medium lock declaration list is empty.
160 *
161 * @return true if list is empty.
162 */
163 bool IsEmpty();
164
165 /**
[27120]166 * Add a new medium lock declaration to the end of the list.
[23675]167 *
[27120]168 * @note May be only used in unlocked state.
169 *
[28353]170 * @return COM status code
[27120]171 * @param aMedium Reference to medium object
172 * @param aLockWrite @c true means a write lock should be taken
[23675]173 */
[28353]174 HRESULT Append(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
[24618]175
176 /**
[27120]177 * Add a new medium lock declaration to the beginning of the list.
[24933]178 *
[27120]179 * @note May be only used in unlocked state.
180 *
[28353]181 * @return COM status code
[27120]182 * @param aMedium Reference to medium object
183 * @param aLockWrite @c true means a write lock should be taken
[24933]184 */
[28353]185 HRESULT Prepend(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
[24933]186
187 /**
[27120]188 * Update a medium lock declaration.
[24618]189 *
[28584]190 * @note May be used in locked state.
[27120]191 *
[28353]192 * @return COM status code
[27120]193 * @param aMedium Reference to medium object
194 * @param aLockWrite @c true means a write lock should be taken
[24618]195 */
[28353]196 HRESULT Update(const ComObjPtr<Medium> &aMedium, bool aLockWrite);
[24618]197
198 /**
[28353]199 * Remove a medium lock declaration and return an updated iterator.
[24618]200 *
[28353]201 * @note May be used in locked state.
[24618]202 *
[28353]203 * @return COM status code
204 * @param aIt Iterator for the element to remove
[24618]205 */
[28353]206 HRESULT RemoveByIterator(Base::iterator &aIt);
[9360]207
[27120]208 /**
[28582]209 * Clear all medium lock declarations.
[28353]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 /**
[27120]228 * Acquire all medium locks "atomically", i.e. all or nothing.
[28353]229 *
230 * @return COM status code
[48297]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.
[27120]237 */
[48297]238 HRESULT Lock(bool aSkipOverLockedMedia = false);
[27120]239
240 /**
241 * Release all medium locks.
[28353]242 *
243 * @return COM status code
[27120]244 */
[28353]245 HRESULT Unlock();
[27120]246
247private:
[28353]248 Base mMediumLocks;
[27120]249 bool mIsLocked;
[28353]250};
[27120]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 /**
[28353]267 * Default medium lock list map destructor.
[27120]268 */
269 ~MediumLockListMap();
270
[28353]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
[98102]344 /** Introspection. */
345 bool IsLocked(void) const { return mIsLocked; }
346
[27120]347private:
[28353]348 typedef std::map<ComObjPtr<MediumAttachment>, MediumLockList *> Base;
349 Base mMediumLocks;
350 bool mIsLocked;
351};
[27120]352
[76562]353#endif /* !MAIN_INCLUDED_MediumLock_h */
[14949]354/* vi: set tabstop=4 shiftwidth=4 expandtab: */
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
ContactPrivacy policyTerms of Use